Parameter interception with Magic Data is powerful but complicated. It is not the sort thing you can just fumble your way through. To use it you really need to read this documentation and the associated documentation for Magic Data Symbols.
Before getting in too deep, consider if your requirement can be solved with Magic Data Templates. Templates are easier to use and carry less overhead and arev easier to use than this Magic Data On Block Load addon.
Using Magic Data Tokens with parameter interception in the template mode is very similar to using templates, except you are no longer limited to the templates available and can process tokens within any block parameter.
The real power of Parameter Interception comes from Replace Mode, where you can unilaterally intercept and replace block parameters according to tokens. To use Replace Mode requires some understanding of how block data is structured.
Here we are using parameter interception to intercept and process parameters to the content block. This is similar to what can be achieved with Magic Data Templates, but with the flexibility of not requiring a special block template and paves the way to applying similar techniques to any parameter of any block.
Magic Data works with Rule Sets. Each Rule Set specifies a list of Block Types, Page Areas and Match Rules, such as any block in an area, a block with a particular class, or a specific id-name.
Within any Block Type, individual parameters can be picked out and further rules specify how they are matched and modified or replaced.
A separate list of Page Selection rules specifies which pages have which Rule Sets applied to them.
When Magic Data adjusts a block parameter, it does so according to a Token. A Token is a short piece of text enclosed by [% %]. Within a token are a series of Symbols that define what the token does.
Within parameter interception tokens can be used in two basic modes:
The Template mode is relevant to any block parameter that contains free format text. Most obviously the standard Content block, but there are plenty more. When templating, you edit the Token and Symbols into the text of a block and Magic Data will then process the token and insert the outcome.
If all you want to do is use tokens in text, Magic Data Templates provides an easy interface for the most common uses of Magic Data simply by assigning block templates.
In the Replace mode, you create a Token and Symbols within Magic Data. Magic Data will then process the token and replace the original block parameter with the outcome.
Replace mode is where you get the real power of Magic Data On Block Load. For example, you can replace the identity of a file set loaded by a gallery or slider based on a page or user attribute. These are the two use-cases already noted in the Marketplace page.
To help you develop and test Magic Data Rule Sets and Page Selections, Magic Data provides some built in developer tools.
Beneath the Page Selection rules dashboard page, in the Page Selection tester you can pick a page and get a report on which Rule Sets will be applied to the page and a trace of how that decision was made.
On the Symbols dashboard page provided by the core Magic Data addon, the Symbols Available section lists all Symbols installed through Magic Data and other addons such as Magic Data Symbols1 and associated help text.
Also on the Symbols page is the Token Symbol evaluation tester. Here you can enter a series of symbols and see how they evaluate in the context of specific pages and users. As with the Page Selection tester, evaluation is accompanied by a detailed trace on how the result was derived. See Magic Data for more details.
On the On Block Load Configuration page, two areas of logging can be enabled:
Page Selection logging - logs a trace of page selection decisions made, similar to the trace provided by the Page Selection tester.
Rule Set application logging - logs a trace of the decisions made applying rule sets to blocks within pages.
These logging options help you debug how rules are applied to blocks and pages.
Additionally, on the Symbols page, Token Symbol evaluation logging will log a trace of how Symbols within Tokens are evaluated, similar to the trace provided by the Token Symbol evaluation tester.
Also on the On Block Load Configuration page, options allow:
Enable (or disable) Magic Data globally. If a rule breaks the front end of your site you can disable Magic Data while you fix it. If your site breaks completely, you can also disable Magic Data by using phpMyAdmin to delete the Config table entry ‘MAGIC_DATA_ENABLE’ or define MAGIC_DATA_ENABLE as false in config/site.
Extend Magic Data to system pages. This allows Magic Data to work on editable blocks within system pages (as long as they are outside of the dashboard). Only select this if you need it because the rule evaluation process becomes a little bit less efficient for all pages, not just system pages.
Enable caching of rule evaluation. Once your Magic Data rules are developed and working, they can be cached to minimise overhead.
All Page Selection rules will be evaluated for all pages (and possibly even system pages). This could create a significant overhead, so any rule can be marked End if matched to prevent further Page Selection rule evaluation if a page is matched. If Page Selection rules become complex and apply to many pages, it can actually be more efficient to select All Pages, as with this rule no complicated decisions need to be made.
A Default Rule Set can be attached to a Page Selection so that selected pages can be prevented from having any magic applied.
Similarly, an Error Rule Set will cause an exception to be thrown. This can be a useful developer aid to notify when any preceding Page Selection rules have not been matched and ended processing, so catching pages that would otherwise slip through unnoticed.
Within a Rule Set, All Areas will look in all areas of a page. As with All Pages, this can actually be more efficient if a lot of magic is going on.
Special Contexts will extend magic data into blocks inside stacks, Global Areas blocks, Parent Area blocks and blocks loaded by Blocks by AJAX.
Within the Parameter Replacement Rules, End if complete will prevent any further rules operating on that block parameter if there are no more tokens left unprocessed. Exception if incomplete can be useful during rule development to throw an exception if any tokens remain incomplete at the end of a sequence of rules.
We have already mentioned a couple of special rules above. The more useful and usual rules for parameter replacement split into two modes, Template and Replace, as introduced under Basic Concepts.
Template - You edit the Token and Symbols into the text of a block and Magic Data will then process the token and insert the outcome.
Replace - You create a Token and Symbols within Magic Data. Magic Data will then process the token and replace the original block parameter with the outcome.
These modes are sub-divided by:
If tokens exist - The tokens will only be replaced if all the tokens involved in the replacement rule evaluate to non-null values.
Always - All tokens will always be replaced, including those with null values.
Tokens that exist - Tokens that evaluate to non-null values will be replaced. Remaining tokens will be left in place.
Beneath the replacement rule selection is a text field. When a Replace mode rule is selected, the original block parameter will be replaced with the text in this field and the evaluated result of any tokens within this field. Tokens within this text can use the existing block parameter data through the symbol ORIGINAL_PARAMETER.
When a Template mode rule is selected, the content of this field is used through the symbol REPLACEMENT_TEXT.
Parameter interception will not be processed for any block where block caching is eneabled in concrete5.6.1+. This is because concrete5.6.1 renders blocks into the block cache when they are saved and still in 'edit' mode. So Magic Data never gets a chance to intercept parameters of such blocks as they are retrieved to render the view (because that never happens).
Ways round this:
Magic Data v1 used to have a highly experimental 'Cache Breaker' option. In Magic Data v2 this has now been removed because, while it worked in concrete5.5 and 5.6, it could not work in cocncrete5.6.1+.