Documentation

Getting started with templates

The quickest way to get started is with Magic Data Templates. Magic Data Templates provides an easy interface for the most common uses of Magic Data simply by assigning block templates that process embedded Magic Data tokens.

  1. Install Magic Data (this addon)
  2. Install Magic Data Templates
  3. Install Magic Data Symbols.
  4. Visit the dashboard Symbols Settings page to enable concrete5 toolbar and edit dialog integration.
  5. You may also want to install Cache Free Content for cache free versions of the core Content and HTML blocks.

A basic exercise to add Template rules to 'About' page content.

On your development system, set up a new concrete5 site with the sample content.

  1. On the dashboard settings page for Magic Data, make sure it is enabled.
  2. Go to the About page and Edit the content of the content block in the Main area. Insert some text like We are now testing Magic Data's templating engine with [%PAGE OWNER USERNAME%].
  3. Save the block.
  4. Assign the Magic Data custom template and publish the page. You should see the token replaced with your user name.

Tokens, Expressions & Symbols

A Token is a short piece of text enclosed by [% %]. Within a token is an Expression built as a series of Symbols that define what the token does. Symbols are by default all uppercase. However, should you want to make them case-agnostic, you can check an option on the Magic Data > Symbols Settings page.

Within a Token [% .... %]Symbols are separated by spaces. If you need a contiguous piece of text, then you can place it in single or double quotes.

Symbols are evaluated left to right. Parenthesis (....) can be used to group or change the order of evaluation.

Symbols generally work on the result of preceding symbols, with any additional values being taken from those immediately following. Rather than get bogged down in syntax, it is easiest to just look at some examples and try them in the Symbol evaluation tester.

If you find your Magic Data expressions are getting complicated, you can place comments between /* and */ . When an expression spans multiple lines, any line behinning with # will be ignored. You can also split out complex expressions as snippets and re-use them elsewhere. Please look up 'snippets' in the built in documentation for more information.

Nevertheless, while Magic Data can support enormously complex expressions, at some point it usually makes more sense to code in php, either directly creating the functionality you want, or creating your own specialised Magic Data symbols to replace complex subexpressions. A custom Magic Data symbol is a very easy way to bring specialised php functionality into a web page.

There are more examples in many of the associated help popovers on the Symbols dashboard page at Magic Data > Symbols dashboard page. To see what symbols are available you can find a live copy of the symbols list and a live symbols documentation page on my support site.

There are also some examples at documentation for Magic Data Symbols and plenty of examples in the addon pages of www.c5magic.co.uk.

Developer Tools

To help you develop and test tokens, Magic Data provides a Symbol Evaluation tester. With Magic Data 2.10, the Symbol tester is available as a popup from the concrete5 toolbar and from many block edit dialogs. Simply highlight your Magic Data expression on the page or in an edit dialog, click the Symbol Tester icon, and evaluate them in the popup.

On the Magic Data > Symbols dashboard page, the lower fold expands to the Symbol Tester. Here you can enter a series of symbols and see how they evaluate in the context of specific pages and users. Evaluation is accompanied by a detailed trace on how the result was derived.

Integration of the Symbol Tester popup with the concrete5 toolbar and block edit dialogs is enabled through the Magic Data > Symbols Settings dashboard page. 

Also on the Symbols Settings page is a checkbox for Token Symbol evaluation logging. When checked and saved, this logs a trace of how Magic Data tokens are evaluated throughout a site, similar to the trace provided by the Symbol Tester.

Be careful about leaving this enabled, it can creates an enormous volume of data!

Other options on the Symbols Settings page disable Magic Data everywhere except in the Symbol Tester and allow case-agnostic symbols.

If you have frequently used snippets of Magic Data, you can create and manage a library through the Magic Data > Snippets dashboard page, then re-use those snippets with the APPLY_SNIPPET symbol.

Please check my support site regulararly for new symbols, examples and ideas for using Magic Data - http://www.c5magic.co.uk/add-ons/magic-data/.

Extension and Integration

Magic Data can be integrated with other addons in several easy ways:

1. Token and Symbol engine

Any addon can call the Magic Data token and symbol engine to process text for embedded Magic Data tokens or to process Magic Data expressions directly.

This is usually just a case of adding a standard helper file and then calling it in a single line of standard code. See Integrating Magic Data Tokens with other blocks.

Add one file, call one helper, and an addon is Magic Data enabled! The top concrete5 blogging platform Pro Blog  integrates Magic Data for even more flexible blogging.

Magic Data compatibility can also be built into a theme. Just bundle a couple of model classes and change Area to Magic Area and an entire theme is Magic Data enabled. See Magic Data Enabling for Themes.

Templating is an obvious use for the Magic Data Token and Symbol engine. But once you start thinking creatively, it can do a whole lot more to extend the flexibility of many blocks. Any decision within a block can now be engineered to respond using a Magic Data expression.

Universal Content Puller uses Magic Data for conditional display. Magic Data On Block Load uses Magic Data to subvert and manipulate any block parameters as they are loaded.

If you want to provide deeper integration of Magic Data within a block or addon, you can even embed the Symbol Tester within your block or dashboard page!

2. Symbol Plugins

The Magic Data symbol engine is fully expandable through a simple plugin architecture. The ideal split is to use PHP to do the heavy processing with custom symbols, but use Magic Data to provide flexibility, so you don't need to re-write PHP code every time you need a minor adjustment. The Magic Data Developer addon provides a useful symbol source viewer popup that integrates with Magic Data documentation and help.

Addons can provide addon specific symbols with a class containing a few lines of code placed at a standard location in the addon package. For example, a specialised symbol is available to provide Oembed funtionality through magic Data.

3. Symbol Area Helper

Where a block or addon uses Magic Data directly, rather than using a plain text area to enter symbols, the MdSymbolAreaHelper can be used to provide a text area for Magic Data input supported by a fully featured symbol tester, complete with debug trace and documentation help. By using this helper for entering symbols, you can test Magic Data expressions directly in the block edit or single page page edit dialog. 

An easy example to follow is provided in the Magic Data Direct block.

4. Magic Data Developer

The Magic Data Developer extension provides a symbol source viewer popup, blocks for front-end symbols listings, documentation and the symbol tester, symbols to help develop Magic Data extensions, and symbols to pull member, addon and theme information from concrete5.org.

Security

If you develop anything that takes user input from a page (such as a form) and then outputs that user input onto a page in a situation where Magic Data is processed, any Magic Data the user enters with the form could be evaluated and thus present a security risk.

Magic Data provides a sanitize interface that strips all Magic Data tokens from text or data structures. This interface is similar to the token fill interface, except it sanitizes.

Developers should use the sanitize interface to clean inputs in any such scircumstances. Please contact JohnTheFish if you need advice on security.

 

Other useful addons

  1. Magic Data Templates - templates for use with Magic Data.
  2. Magic Data Symbols1 - symbols for use with Magic Data.
  3. Cache Free Content - cache free versions of the core Content and HTML blocks.
  4. Magic Data Commerce - symbol and template integration with eCommerce
  5. Similar & Recently Purchased Products - symbols for upselling integrated with eCommerce.
  6. Magic Data On Block Load - extends the capability of Magic Data beyond templates though parameter interception.
  7. Magic Yogurt - process Magic Data from your theme.
  8. Blocks by AJAX - enables Magic Data within AJAX interactions.
  9. Magic Data Developer - Developer resources and symbols
  10. Uber List - Lists powered by Magic Data