Keyword Modifiers

Last Updated: 05 Feb 2020

Keyword replacements can be modified using a variety of keyword modifiers to further configure the returned values. These modifiers are represented as extensions added to existing standard keyword replacements, denoted by a caret (^) character followed by the modifier keyword and any necessary modifier  arguments.  For example,  if the keyword replacement %asset_contents^maxwords:10% was used, the first ten words of the body of the asset will be displayed.

Bookmarks

Multiple modifiers can be used on a single keyword replacement, separated by the caret character. For example, %item_price^subtract:2^multiply:10%. This keyword replacement would subtract two from the item price value before multiplying the new value by ten.

You can use keyword replacements as modifier arguments using the special replace_keywords modifier. For more information, refer to the Using Keyword Replacements as Argument Values section in this chapter.

Keyword modifiers are also supported on the keyword replacements available for use within Simple Edit Layouts. For more information, refer to the Simple Edit Layout chapter of the Simple Edit Layouts manual.

Available Keyword Modifiers

The keyword modifiers available are as follows:

Array Based Modifiers

Using array based modifiers directly on a keyword, such as ^index and ^count, only work on keyword values that actually produce an array or JSON object to start with.

If you are using these modifiers on array or JSON strings, such as JSON stored in a metadata text field, you must first use the ^json_decode modifier to convert the string to a JSON object:

%asset_metadata_details^json_decode^index:address^index:city%

Using Regular Expression in Modifiers

When using regular expression values on the replace and contains keyword modifiers, the following characters are supported: \s (whitespace characters) [a-z A-Z] [0-9] [|~!@#$*={}+;.,'"]

Example: % asset_metadata_foo^replace:(\s):_% (This will remove any white space, as understood by PHP, and replace them with an underscore).

The following characters need to be escaped with a backslash: [ ] - ( ) :

The following characters needs to be double escaped with two backslashes: ^ e.g. ^replace:\\^:caret

Example: % asset_metadata_foo^replace:[~!@#$\(\)*\-={}\[\]+;.,'"]:_% (replaces any of the character provided with an underscore).

The following characters are not supported in regex on this keyword modifier: & (is converted to &amp;) < (is converted to &lt;) > (is converted to &gt;)

The following characters are used within the Squiz Matrix keyword system and, as such, are also not supported in regex on this keyword modifier: %

Pre Keyword Evaluation Modifiers

Unlike the standard keyword modifiers, the pre keyword evaluation modifiers are actioned on before the root keyword is evaluated. These pre modifiers can be used in conjunction with the regular keyword modifiers that are outlined above.

The following pre modifiers are available:

Reserved Chars

The following characters are reserved for use within the Squiz Matrix keyword system and, as such, need to be escaped with a backslash when used as a modifier argument: : ^

When using the caret character (^) on a modifier that accepts regular expression values, such as the replace modifier, it will need to be double escaped.

In the example below, we have escaped these reserved characters that are being used in the modifier arguments:

%asset_name^eq:\^:caret:other%
%asset_name^replace:\\^:caret%
%asset_name^replace:\::colon%

Using Keyword Replacement Values as Modifier Arguments

A keyword replacement can be nested within a keyword modifier to use its value as a modifier argument. This is done through the use of a special replace_keywords modifier, appended to the beginning of the regular modifier string after the caret (^) character in the keyword format. Please note that keywords nested within a modifier are enclosed in braces (curly brackets) rather than percent signs.

In the example below, the replace_keywords modifier has been used to replace the asset_metadata_price argument within the eq modifier:

%asset_metadata_show_price^replace_keywords:eq:1:{asset_metadata_price}%

In this example, if the asset_metadata_show_price value is equal to 1, it will be replaced with the returned value of the asset_metadata_price keyword replacement. If the replace_keywords modifier was not used, the value would simply use the text {asset_metadata_price};    the    keyword would not be replaced correctly.

When using the replace_keywords modifier, you can append additional modifiers onto the nested keyword using the caret (^) character. An example of this is shown below:

%asset_name^replace_keywords:replace:{asset_name^maxchars:1}:ABC%

In this example, the maxchars modifier has been appended within the braces (curly brackets) on the nested asset_name keyword. This example will grab the name of the asset, and replace the first character of the asset's name with the supplied string (in this case, 'ABC').

As of version 5.4.0.0 of Matrix you no longer need to use the ^replace_keywords modifier to use Keyword Replacement values as modifier arguments. You can simply just do it like this:

 %asset_metadata_show_price^eq:1:{asset_metadata_price}%
If you would want to use the curly brackets without replacing the keyword, you can just escape them like this:
 %asset_metadata_show_price^eq:1:\{asset_metadata_price\}%

Previous Chapter Next Chapter