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.
On your development system, set up a new concrete5 site with the sample content.
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.
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/.
Magic Data can be integrated with other addons in several easy ways:
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.
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!
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.
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.
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.
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.