Squiz Matrix keywords

Squiz Matrix is a content management system I’ve built stuff with for several years now. I’ve found the keyword replacement and conditional functionality to be consistently useful, so I thought I’d share some tips and tricks thereanent.

What are they? permalink

Keyword replacements are templating-style keywords used to add dynamic values to pages (or ‘assets’ in Matrix parlance). They start and end with the per cent symbol (e.g. %asset_name%) or — if nested — curly brackets, e.g. {globals_site_name}. The Matrix Manuals site has full documentation on common and global keywords.

Keyword modifiers allow you to modify or perform logic on the values returned by those keywords. They’re denoted by a carat symbol, e.g. ^trim. The full keyword modifiers documentation is also available on the Squiz site.

Here are a few examples of keyword replacements and conditionals I’ve used in the course of building stuff with Matrix, in order to give you an idea of how they work.

Example 1 (decode JSON; conditionals; ‘not equals’ operator) permalink

This first example could be added to an <a> element. It checks the current page’s lineage in the Matrix asset map and if it’s not under the site with ID 123456 then it print a target attribute so the link opens in a new window.

%asset_linking_lineage^json_decode^index:0^neq:123456:target="_blank"%

%asset_linking_lineage% is the keyword and the chain of ^ modifiers first decodes the JSON in which the keyword returns the lineage, then looks at the first item, checks whether it’s not equal to 123456, then finally prints target="_blank". A further : could be added to provide an ‘else’ condition.

Example 2 (split into array and get index; reverse array) permalink

This next one converts the string value of metadata field foo (item one;item two;item three, for example) into an array (splitting at the semicolon) and gets the first item:

%asset_metadata_foo^explode:;^index:0%

And this checks whether the last item in an array (again based on a string delimited by semicolons) is empty or has a value:

%asset_metadata_foo^explode:;^array_reverse^index:0^eq::EMPTY:HAS VALUE%

Example 3 (nested keywords; date-based conditionals; get asset attributes; count words) permalink

This is a more complex example, using nested keywords. It could be used in an Asset Listing (in the relevant Type Format bodycopy asset) to print Single Calendar Events occuring in the past (using PHP date formatting).

Additionally an elipsis is added if the description attribute is over 40 characters in length.

%event_start_date^lt_date:{globals_date_Y-m-d}:
<div class="event">
    <p>{event_start_datetime_d} {event_start_datetime_F} {event_start_datetime_Y}</p>
    <h3>{asset_name_linked}</h3>
    <p>{asset_attribute_description^maxwords:40^trim}{asset_attribute_description^wordcount^gt:40:...:}</p>
    <p><a href="{asset_url}">Read More</a></p>
</div>
%

Example 4 (keywords in a Design; as_asset modifier; trim output; count characters; ‘greater than’ operator) permalink

Keywords are also useful in Designs (templates). The example below concerns a metadata field of type Related Asset. Related Asset fields allow you to specify the ID of another asset.

The logic checks first whether there is a value in the Related Asset metadata field foo. If so, it prints a <div> with the related asset’s contents.

%begin_asset_metadata_foo%
  <div class="foo">
    %asset_metadata_foo^as_asset:asset_contents_raw%
  </div>
%end_asset%

%asset_metadata_foo% is the ID of the related asset specified in the foo metadata field. The ^as_asset modfier allows us to access a keyword of that asset, in this case %asset_contents_raw%.

The below example works for a metadata field of type WYSIWYG, where we use ^charcount to check whether the field has a value.

%begin_asset_metadata_bar^trim^charcount^gt:0%
<div class="bar">
    %asset_metadata_bar%
</div>
%end_asset%

Here’s another example of the ^as_asset modifier used earlier to access the contents of a Related Asset metadata field:

%form_submission_id^as_asset:asset_metadata_email%

Here we get the value of the metadata field email on the Form Submission asset with ID form_submission_id. This example could be used in the Email Options screen of a Custom Form, for example.

Example 5 (format dates; find and replace) permalink

If you’re dealing with events, the %event_datetime_summary% keyword is useful. You can use modifers to format the output conform to your site’s style guide. The below, for example, will convert 30th May 2020 9:00am-5:30pm to 30 May 2020 9am – 5.30pm; or 30th May 2020 9:00am - 31st May 2020 5:30pm to 30 May 2020 9am – 31 May 2020 5.30pm.

`%event_datetime_summary^replace:-: – ^replace:th:^replace:rd:^replace:st:^replace:nd:^replace:\:00:^replace:\::.%`

Example 6 (get external data; PHP date format; mathematical functions) permalink

Finally, Matrix allows you to pull in data from sources outwith the CMS. You can use modifers on keywords representing those external database fields.

The below example pulls a date in Unix time and formats it. It uses the PHP Date I parameter to check whether daylight savings time (DST) is currently in place. If so (that is to say a value of 1 is returned), 3600 seconds are subtracted and this new value is then formatted into a readable time and printed, otherwise the time will be printed in a readable form as is.

%data_source_record_set_time^date_format:I^eq:1:{data_source_record_set_time^subtract:3600^date_format:g\:ia}:{data_source_record_set_time^date_format:g\:ia}%

Very occasionally a keyword isn’t documented. One time I wanted to print the submission date of Form Submissions being listed in an Asset Listing but it wasn’t immediately obvious how to do it. Some trial and error yielded %asset_attribute_submitted_short%.

The Paint Layouts Conditional Keywords screen offers some additional conditionals, like checking whether the user has admin access or if Maintenance Mode is on. It also allows you to nest conditionals.

Thanks for reading. For more Matrix-related tips, see my cheatsheet over at GitHub.