Documentation

Content and HTML blocks

To use these templates, simply insert Magic Data tokens into Content or HTML blocks. For example, insert [%PAGE OWNER USERNAME%] into the block and assign a Magic Data template and it will be expanded into the name of the page owner.

Just set a Magic Data template for a block and any tokens will be processed.

While develoiping, remember that you can always test Magic Data tokens in the Symbols dashboard page.

[%PAGE OWNER USERNAME%] is just an easy symbol expression to get you started. The list of symbols available from Magic Data is growing and you can pull all sorts of page, user and eCommerce product data into your blocks.

If you also have Blocks by AJAX, additional templates are provided for AJAX loading the Content block and HTML block. Again, simply assign them to the respective Content or HTML blocks and they will be AJAX loaded with token expansion.

Page List Block

A template is also included for the Page List block. This will process any Magic Data tokens found in the listed page descriptions and enables the ORIGINAL_PAGE symbol to function within a page list. 

However, please be aware that tokens written in page descriptions will only be processed by the Page List block with this template, and will not be processed in other locations that page descriptions are shown, such as in page metadata.

Page List Teasers

This template combines the functionality of the Magic Data Page List template with jordanlev's Page List Teasers template. It requires Page List Teasers to be installed in order to work.

Magic Data Attributes

Text and Textarea attributes

You can use any attribute within a Magic Data expression. These new attributes actually process Magic Data expressions wrtitten inside the attributes. In all other respects they behave the same as the core Text and Text Area attribnutes.

Magic Data Direct attribute

A Magic Data Direct attribute selects a snippet of Magic Data to be evaluated when the attribute is displayed. For use in situations where you jsut want to evaluate the magic data without needing to place a [%token%] within text.

Magic Data Select attribute

(Requires Uber List v1.11.1+). The Magic Data Select attribute is the ultimately flexible list attribute, encompassing the capabilities of many other select attributes and more. It does for select attributes what Uber List has achieved for lists.

When creating attributes of this type in the dashboard, Magic Data expressions are used to define the list of options the attribute will select between. Then, when the attribute is attached to a page, user or file (or anything else you can attach an attribute to), a selection can be made as with a regular select attribute. These attributes can be configured for single or multi selection (but obviously not user added options).

Some ideas for use:

  • A page selector that lists a limited set of pages.
  • A page selector that adapts the pages it lists to where and what the attribute is attached to.
  • A user selector that lists users from just one group.
  • A file selector that lists files from a file set or matching an attribute value.
  • Select an entry from a form or csv file (requires Magic Data Forms)
  • Context sensitive product options

concrete5.6 Cache

The block cache in concrete5.6 likes to cache blocks when they are saved. If you get any edit-mode content displayed when viewing a page, you should disable the block cache, clear it, then re-enable it.

Note that when the block cache is enabled, tokens are processed at the time a block is saved. For example, [%UID USERNAME%] could be processed to show the current user at the time the block is saved or cached, not the current user at the time the page is viewed!

If you find the block cache is getting in the way of Magic Data evaluation, you can use the bloicks provided by the Cacher Free Content addon. This is a free addon providing cache free clones of the core Content and HTML blocks. Use regular blocks where you want caching. Use cache free blocks where you dont.

Styling templates from within Magic Data

Templates generlly support optional inner and outer wrapping elements. These elements are only wrapped around the block output if they are required by Magic Data styling symbols. For deatils, prease refer to the built in symbol documentation and filter the symbols shown for this addon. 

As an example, the following content cold be added to an HTML block and the block assigned a Magic Data  template.

<h3>HTML Block - AJAX - Magic Template Test</h3>
<p>This whole block will be wrapped in styled defined by the Magic Data below. 
Note the Magic Data ends by returning a white space so that nothing is shown on the page.
[%
"1px dashed blue" ADD_TEMPLATE_STYLE "border" 'inner' 
"10px" ADD_TEMPLATE_STYLE  "border-radius" 'inner'
"white" ADD_TEMPLATE_STYLE "background" "inner"
"20px" ADD_TEMPLATE_STYLE  "padding"  'inner' 

"pink" ADD_TEMPLATE_STYLE "background"  
"15px" ADD_TEMPLATE_STYLE "border-radius" 
"10px" ADD_TEMPLATE_STYLE "padding"  
SET ' '
%] </p>

The above Magic Data  adds two wrapping div elements. Styles for the 'inner' div are set by naming 'inner' explicitly. Styles for the 'outer' element take 'outer' as a default.

By itself, this doesn't achieve anything that cannot be achieved using block design. However, as usual, the power of such Magic Data  symbols becomes more apparent when combined with other site data. For example, a block could be styled differently depending on any items of site data accessible through Magic Data .

Developing block templates

A helper is provided by the Magic Data package for those wanting to develop further block templates. For flexibility, it is best used within a test for Magic Data being installed.

$md_pkg  = Package::getByHandle('jl_magic_data');
if(is_object($md_pkg)){
  $mdsh = Loader::helper('md_evaluate', 'jl_magic_data');
  echo $mdsh->fill_and_template($content);
} else {
  echo $content;
}

In the above example, if Magic Data is not installed the content of a block is shown unprocessed. An slightly different approach would be to show an error message. You can see this being used in its simplest form in the template for the HTML block.

More developer information can be found in the hwoto Integrating Magic Data Tokens with other blocks and at http://www.c5magic.co.uk/add-ons/magic-data/

With v2.0 the MagicDataSymbolsHelper class bundled with this addon package is deprecated. Such code will continue to work, but is no longer the preferred way to process magic data.