Getting started with On Block Load and Parameter Interception

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.

An exercise to add Template rules to 'About' page content.

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.

1. In the dashboard, locate Rule Sets. Add a new rule set at the top of the list called Content Template and give it a description such as Provide general purpose templating for Content blocks. Click Save.
2. Now click the Edit button for the Content Template Rule Set. Add a new match rule, select the Content block type, area Main and Match Rule Any. Click Save.
3. Now click the Edit button for the match rule. Add a new block parameter and select content (this will be the only choice available). Leave the Match Rule as Any and under Replacement Rule select Template tokens that exist. Click Save.
4. Now go to the Page Selection dashboard page and add a new rule. Select the About page and check This page. Select the rule set Content Template you have just created. Click Save.
5. Now go to the On Block Load Configuration dashboard page and make sure Enable Magic Data is checked and everything else if un-checked (you can have a play with the other options later).
6. While in the dashboard, turn off all caching.
7. Now 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 [%CID OWNER USERNAME%].
8. Save the block and publish the page. You should see the token replaced with your user name.

Some basic concepts

Rule Sets

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.

Page Selection

A separate list of Page Selection rules specifies which pages have which Rule Sets applied to them.

Tokens & Symbols

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:

Template

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.

Replace

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.

Developer Tools

To help you develop and test Magic Data Rule Sets and Page Selections, Magic Data provides some built in developer tools.

Page Selection tester

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.

Token Symbol evaluation tester

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.

Logging

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.

General Configuration

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.

Special Options

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.

Parameter Replacement 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.

Cache

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:

• Switch off the block cache.
• It only applies where a block enables block caching by setting the flags in the block controller. So for sites when you want block caching generally enabled, but need parameter interception for a particular block, a small override of the block controller to change the flags can help.
• The core team have now committed to making block caching selective (as page caching currently is), so in an upcoming version of cocnrete5 you can switch off the block cache just where you need it switched off.
• Load the block using Blocks By Ajax. 

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+.

Other useful addons

1. Magic Data Symbols - provides symbols for use with Magic Data.
2. Magic Data Templates - provides templates for use with Magic Data.
3. Highlighted Code Block - when installed, Magic Data will use this block to provide improved help during block parameter selection.
4. Fileset Attribute - can be easier to use than a text or numeric attribute if you want to subvert filesets.
5. Page Selector Attribute - can be easier to use than a text or numeric attribute if you want to subvert page names.
6. Stack Selector Attribute - can be easier to use than a text or numeric attribute if you want to subvert stack selection.