The symbol engine built in to Magic Data is pluggable and expandable. As such, the most up-to-date documentation can be found on the dashboard Symbols page, along with the Token Symbol evaluation tester.

As a general principle, Tokens and the Symbols within them should only retrieve information and never actually modify files or the database.

The list of Available Symbols is growing, so rather than rely on the lists here, plese chack out the Available Symbols page, though even that is by no means complete!

Using Symbols

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 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 Token symbol evaluation tester. There are more examples in many of the associated help popovers on the Symbols dashboard page.

JohntheFish AS_UID - Evaluates to 1 as I am the super-admin of my development system. You will obviously need to enter your own username.

john@c5magic.co.uk AS_UID - Also evaluates to 1, for the same reason.

JohntheFish IN_GROUP Administrators - Evaluates to 1 because I have already added myself to the group "Administrators".

PAGE OWNER EMAIL AS_LINK - Evaluates to a link to john@c5magic.co.uk, because I own all pages on my development system.

PAGE OWNER ATTRIBUTE favourite_fileset AS_FSID - Evaluates to the fileset ID for whatever fileset I name in a user attribute with the handle favourite_fileset. Tokens like this come in useful for changing which gallery is displayed in a global area or stack depending on the user.

PAGE OWNER ATTRIBUTE favourite_fileset AS_FSID OR ORIGINAL_PARAMETER - Extends the above example to default back to the original value if the attribute does not exist or does not evaluate as a fileset ID.

Some basic control symbols provided are IF and SWITCH.

SET true IF "result for false" "result for true" - Evaluates to "result for true". Note that the first item after the IF is the false result and the second item is the true result. The SET at the start is entirely optional, but sometimes can help clarify an expression.

SET JohntheFish IN_GROUP Administrators IF "Proletariat" "I have the power" - Evaluates to "I have the power".

SET b SWITCH a|b|c|d "result string a" "result string b" "result string c" "result string d" - Evaluates to "result string b". Here the first item after the SWITCH is a pipe | separated list that is used to index into the following items.

Have a play with the Token symbol evaluation tester, try some examples, and see what you can come up with. The diagnostic trace will let you know where anything is going wrong.

Extending Symbols

The symbols provided are not intended to be complete. Magic Data is an addon for developers and it is expected those wanting specific symbol functionality will be able to do some minimal PHP to add symbols specific to their requirement.

Further symbols can easily be added as root level models or in packages. Please see Developing Symbols for deatils.

You should consider developing one or more custom symbols where you find you are repeatedly writing similar symbol expressions. The ideal split is to use PHP to do the heavy processing, but use Magic Data to provide flexibility, so you don't need to re-write PHP code every time you need a minor adjustment.

Remember that the list of Available Symbols is growing, so plese chack out the Available Symbols page, but bear in mind that even that is by no means complete!