Keyword Modifiers

Last Updated: 09 Feb 2017

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:

Keyword Modifier Operation
abs Displays the absolute value of a returned numerical value.

Example:
%asset_version^abs%
Effect: 0.2.220 > 0.2
add:<numeral> Adds a set numeral argument to a returned numerical value.

Example:
%asset_assetid^add:10%
Effect: 129 > 139
append:<string> Append a string at the end of the returned value.
 
Example: %asset_attribute_name^append:*%
Effect: name > name*
append_if:<string> Append a string at the end of the returned value if it is not empty.
 
Example: %asset_attribute_name^append_if:*%
Effect:
name > name*
array_slice:<offset:length:preserve_keys>

Extracts a slice of an array. If length is not specified, the resulting array slice will have everything from offset until the end of the array.
The slice will be reindexed with new numeric keys unless preserve_keys is set to 1.

Example: %globals_get_days^array_slice:4%
Effect: If var "days" is an array of strings ['mon', 'tue', 'wed', 'thus', 'fri', 'sat', 'sun'], then output would be ['fri', 'sat', 'sun'].

Example: %globals_get_days^array_slice:4:2%
Effect: ['fri', 'sat']

Example: %globals_get_days^array_slice:4:2:1%
Effect: [4 => 'fri', 5 => 'sat']

array_reverse:<preserve_keys> Reverses the element order in the array.

Example: %globals_get_primes^array_reverse%
Effect: [2,3,5,7] > [7,5,3,2,]
array_keys Returns all the keys of an array.

Example: %globals_get_colours^array_keys%
Effect: {"white":"FFFFFF","black":"000000"} > ["white","black"]
array_values Returns all the values of an array.

Example: %globals_get_colours^array_values%
Effect: {"white":"FFFFFF","black":"000000"} > ["FFFFFF","000000"]
array_key_exists:<key:true:false> Displays 1 (true) or nothing (false), determined by whether the set <key> argument exists in the array as array key. This value can be overridden with true and false arguments.

Example: %globals_get_countries^array_key_exists:nz:yes:no%
Effect: {"au":"Australia","nz":"New Zealand"} > yes
as_asset:<asset_keyword> Dynamically supplies an asset ID on a set asset_keyword.

Example:
%asset_assetid^as_asset:asset_name%
Effect:
The name of the asset whose ID is supplied by the asset_assetid keyword replacement.

Example:
%order_number^as_asset:asset_attribute_delivery_addr%        
Effect: The delivery address of the order asset whose ID is supplied by the order_number keyword replacement.
as_csv An array-specific modifier to convert returned array data into a CSV format string value.
 
Example: %globals_get^as_csv%
Effect: Converts the returning array data into CSV format.
 
Regular string modifiers can be appended to this modifier to be applied to the resulting keyword replacement, e.g. %globals_get^as_csv^uppercase%.
as_csv_noheader An array-specific modifier to convert returned array data into a CSV format (without header) string value.

Example: %globals_get^as_csv_noheader%
Effect: Converts the returning array data into CSV format (without header).
 
Regular string modifiers can be appended to this modifier to be applied to the resulting keyword replacement.
as_json An array-specific modifier to convert returned array data into a JSON format string value.
 
Example: %globals_get^as_json%
Effect: Converts the returning array data into JSON format.
 
Regular string modifiers can be appended to this modifier to be applied to the resulting keyword replacement.
as_url_string An array-specific modifier to convert returned array data into a URL string value.

Example: %globals_get^as_url_string%
Effect: Converts the returning array data into a URL string value.

Regular string modifiers can be appended to this modifier to be applied to the resulting keyword replacement. 
as_xml An array-specific modifier to convert returned array data into a XML format string value.
 
Example: %globals_get^as_xml%
Effect: Converts the returning array data into XML format.
 
Regular string modifiers can be appended to this modifier to be applied to the resulting keyword replacement. 
base64decode Decodes data from a returned base64 encoded string.
base64encode Encodes returned data to a base64 string.
base64url_decode Decodes data from a returned base64 URL encoded string.
base64url_encode URL encodes returned data to a base64 string. A :no_pad argument can also be passed to strip whites space characters from the end of the string.
capitalize Capitalises the first character of a returned value.

Example:
%asset_name^capitalize%
Effect: home page > Home page
count An array-specific modifier that will return a count of the elements within the returned array data.
 
Example: %globals_visted_assets^count%
Effect: The number of elements within the returned array, e.g. 3.
cdata Wraps a returned value in a CDATA block. This modifier will handle escaping CDATA when CDATA is already supplied.

Example:
%asset_contents^cdata%
Effect: <![CDATA[asset contents ]]>
ceil Rounds a returned numerical value up to the nearest whole integer.

Example: %item_price^ceil%
Effect: 8.67 > 9
charcount Determines the character count of a returned value.

Example: %asset_short_name^charcount%
Effect: documents > 9
contains:<string:YES:NO> Tests if a specified string argument appears in the returned value, returning the number of recurrences. Append the YES and NO arguments for a specified yes or no response.

Example: %asset_name^contains:M%
Effect: Squiz Matrix > 1

Example:
%asset_name^contains:M:Found:Not Found%
Effect: Squiz Matrix > Found

Example:
%asset_name^contains:B:Found:Not Found%
Effect: Squiz Matrix > Not Found
context:<context> Sources the returned value from the specified context.

Example:
%asset_name^context:French%
Effect: Returns the asset name in the French context, eg. Page d'accueil.
css_safe Returns a keyword string that is suitable for use as an HTML class or ID, which in turn can then be used as a CSS selector.

Example: %asset_name^css_safe%
Effect: 'Welcome to Squiz Matrix!' > 'Welcome_to_Squiz_Matrix'
date_format:<format> Formats a returned date string value to a set PHP date format argument.

Example:
%asset_created^date_format:Y%
Effect: 2010-03-03 10:00:00 > 2010

Please note that this output format is defined in PHP date format. For more information, visit the PHP: Date Manual.
decrement Decreases a returned numerical value by one.

Example:
%asset_assetid^decrement%
Effect: 100 > 99
divide:<numeral> Divides a returned numerical value by a set numeral argument.

Example:
%asset_assetid^divide:2%
Effect: 50 > 25
empty:<replacement> Displays the set replacement argument when a returned value is empty.

Example:
%question_answer_46_q1^empty:notanswered%
Effect: not answered will be displayed if the value is empty.
eq:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned numerical value is equal to a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^eq:20%
Effect: If the asset ID is 20, 1 will be displayed. If it is not 20, 0 will be displayed.

Example: %asset_assetid^eq:20:YES:NO%
Effect: If the asset ID is 20, YES will be displayed. If it is not 20, NO will be displayed.
eq_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is equal to a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^eq_date:2000-01-01%
Effect: If the update date is 1st of Jan, 2000, 1 will be displayed. If it is not this date, nothing will be displayed.

Example: %asset_updated^eq_date:2000-01-01:YES:NO%
Effect: If the update date is 1st of Jan, 2000, YES will be displayed. If it is not this date, NO will be displayed.
escapehtml Escapes the HTML of a returned value. See http://www.w3.org/TR/charmod/#sec-Escaping for more information on character escaping.

Example:
%asset_contents^escapehtml%
Effect: asset&contents > asset&amp;contents
escapequotes Escapes quotes within a returned value. See http://www.w3.org/TR/charmod/#sec-Escaping for more information on character escaping.

Example:
%asset_contents^escapequotes%
Effect: "assetcontents" > \"asset contents\"
explode:<delimiter> Converts and splits a string by the specified <delimiter> into an array.
Example: %globals_get_date^explode:-%
Effect: "1982-11-11" > ["1982","11","11"]
floor Rounds a returned numerical value down to the nearest whole integer.
Example: %item_price^floor%
Effect: 13.65 > 13
gt:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned numerical value is greater than a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^gt:10%
Effect: If the asset ID is greater than 10, 1 will be displayed. If it is 10 or less, 0 will be displayed.

Example: %asset_assetid^gt:10:YES:NO%
Effect: If the asset ID is greater than 10, YES will be displayed. If it is 10 or less, NO will be displayed.
gt_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is greater than a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^gt_date:2000-01-01%
Effect: If the update date is earlier than 1st of Jan, 2000, 1 will be displayed. If it is later than this date, nothing will be displayed.

Example: %asset_updated^gt_date:2000-01-01:NEW:OLD%
Effect: If the update date is later than 1st of Jan, 2000, NEW will be displayed. If it is earlier than this date, OLD will be displayed.
gte:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned numerical value is greater than or equal to a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^gte:30%
Effect: If the asset ID is 30 or greater, 1 will be displayed. If it is less than 30, 0 will be displayed.

Example: %asset_assetid^gte:30:YES:NO%
Effect: If the asset ID is 30 or greater, YES will be displayed. If it is less than 30, NO will be displayed.
gte_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is greater than or equal to a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^gte_date:2000-01-01%
Effect: If the update date is 1st of Jan, 2000 or earlier, 1 will be displayed. If it is later than this date, nothing will be displayed.

Example: %asset_updated^gte_date:2000-01-01:NEW:OLD%
Effect: If the update date is 1st of Jan, 2000 or later, NEW will be displayed. If it is earlier than this date, OLD will be displayed.
htmlentities:<flag> Converts all applicable characters to HTML entities. Takes a flag argument to specify how to handle quotes, invalid code unit sequences and the used document type. The default flag is ENT_COMPAT.
 
Available flags can be found on the PHP: htmlentities documentation.
 
Example: %asset_metadata_feature.about^htmlentities:ENT_HTML5%
Effect: what " ' ' " < > ! , . / ? '  : ; > <p>what " ' ' " &lt; &gt; ! , . / ? ' &nbsp;: ;</p>
implode:<glue> An array-specific modifier that joins array elements with a "glue" string. If <glue> is not specified then it will simply join the array elements.

Example: %globals_get_primes^implode%
Effect: [2,3,5,7] > "2357"

Example: %globals_get_primes^implode:+%
Effect: [2,3,5,7] > "2+3+5+7"
in_array:<value:true:false > Displays 1 (true) or nothing (false), determined by whether the set <value> argument exists in the array as an array value. This value can be overridden with true and false arguments.

Example: %globals_get_countries^in_array:Australia%
Effect: {"au":"Australia","nz":"New Zealand"} > 1
increment Increases a returned numerical value by one.

Example:
%asset_count^increment%
Effect: 10 > 11
index:<index> An array-specific modifier that will return the value of returned array or JSON data at a specified index argument.
 
Example: %globals_session_details^index:address^index:city%
Before: {"address":{"city":"Sydney","postcode":"4000"}}
After: Sydney

Example: %globals_session_array^index:1%
Before: ["Sydney","Brisbane","Melbourne"]
After: Brisbane

If you are using this modifier on a string array, 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%
json_encode Encodes a returned value into a JSON string.

Example:
%asset_metadata_text_field^json_encode%
Effect: <p><a href="http://example.com">Download</a></p> > <p><a href=\"http:\/\/example.com\">Download<\/a><\/p>
json_decode Returns the array data for a given JSON string. This modifier should be used in conjunction with other array modifiers, such as the Index modifier.

Example: %asset_metadata_data^json_decode^index:City%
Effect: {"value":"Montague Rd","City":"Brisbane","State": "QLD"} > Brisbane
lastchars:<numeral Returns the last characters of a returned value, based on a set numeral argument.
 
Example: %asset_name^lastchars:4%
Effect: homepage > page
lowercase Displays a returned value in lowercase.

Example:
%asset_name^lowercase%
Effect: My Site > my site
lt:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned numerical value is less than a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^lt:32%
Effect: If the asset ID is less than 32, 1 will be displayed. If it is 32 or greater, nothing will be displayed.

Example: %asset_assetid^lt:32:YES:NO%
Effect: If the asset ID is less than 32, YES will be displayed. If it is 32 or greater, NO will be displayed.
lt_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is less than a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^lt_date:2000-01-01%
Effect: If the update date is earlier than 1st of Jan, 2000, 1 will be displayed. If it is later than this date, nothing will be displayed.

Example: %asset_updated^lt_date:2000-01-01:OLD:NEW%
Effect: If the update date is earlier than 1st of Jan, 2000, OLD will be displayed. If it is later than this date, NEW will be displayed.
lte:<x:true:false> Displays 1 (true) or 0 (false), determined by whether a returned numerical value is less than or equal to a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^lte:65%
Effect: If the asset ID is 65 or less, 1 will be displayed. If it is greater than 65, 0 will be displayed.

Example: %asset_assetid^lte:65:YES:NO%
Effect: If the asset ID is 65 or less, YES will be displayed. If it is greater than 65, NO will be displayed.
lte_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is less than or equal to a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^lte_date:2000-01-01%
Effect: If the update date is 1st of Jan, 2000 or earlier, 1 will be displayed. If it is later than this date, nothing will be displayed.

Example: %asset_updated^lte_date:2000-01-01:OLD:NEW%
Effect: If the update date is 1st of Jan, 2000 or earlier, OLD will be displayed. If it is later than this date, NEW will be displayed.
maxchars:<numeral> Limits the maximum character count of a returned value to a set numeral argument.

Example:
%asset_type^maxchars:4%
Effect: Thesaurus > Thes
maxwords:<numeral> Limits the maximum word count of a returned value to a set numeral argument. Please note that any content tags and attributes will count towards the word count of the value.

Example:
%asset_contents^maxwords:100%
Effect: The first 100 words of the asset's contents will be displayed.
md5 Displays the computer MD5 hash of the returned value.

Example:
%asset_name^md5%
Effect: Home > 8cf04a9734132302f96da8e113e80ce5
modulo:<numeral> Calculates n modulo d, where n is a returned numeric value and d is a set numeral argument.

Example:
%page_number^modulo:3%
Effect: 8 > 2
multiply:<numeral> Multiplies a returned numerical value by a set numeral argument.

Example:
%asset_assetid^multiply:10%
Effect: 8 > 80
negate Negates a returned numerical value.

Example:
%total_tax^negate%
Effect: 70 > -70
neq:<x:true:false> Displays 1 (true) or 0 (false), determined by whether a returned numerical value is not equal to a set x argument. This value can be overridden with true and false arguments.

Example:
%asset_assetid^neq:17%
Effect: If the asset ID is not 17, 1 will be displayed. If it is 17, 0 will be displayed.

Example: %asset_assetid^neq:17:YES:NO%
Effect: If the asset ID is not 17, YES will be displayed. If it is 17, NO will be displayed.
neq_date:<x:true:false> Displays 1 (true) or nothing (false), determined by whether a returned date value is not equal to a set x date. This value can be overridden with true and false arguments.

Example:
%asset_updated^neq_date:2000-01-01%
Effect: If the update date is not 1st of Jan, 2000, 1 will be displayed. If it is this date, nothing will be displayed.

Example: %asset_updated^neq_date:2000-01-01:NO:YES%
Effect: If the update date is not 1st of Jan, 2000, NO will be displayed. If it is this date, YES will be displayed.
nl2br Inserts a <br /> (HTML line break) before each new line in a returned value.

Example:
%asset_contents_raw^nl2br%
Effect: asset<br/>
contents.
notempty:<replacement> Displays the set replacement argument when a returned value is not empty.

Example:
%question_answer_46_q1^notempty:answered%
Effect: answered will be displayed if the value is not empty
number_format:<precision> Rounds a returned numerical value to a specific number of decimal places, grouped in thousands, determined by a set precision argument. If no precision argument is set, the returned value will round to the nearest whole integer.

Example:
%item_price^number_format:2%
Effect: 1234567.789 > 123,456.79
preg_replace:<regex> Replaces the regular expression value with a set replacement.

For use in conjunction with the Regular Expression asset. For more information, refer to the Regular Expression chapter in the Other CMS Assets manual.
preg_match:<regex> Returns a success/failure value if the regular expression matches the returned keyword value.
 
For use in conjunction with the Regular Expression asset. For more information, refer to the Regular Expression chapter in the Other CMS Assets manual. 
preg_match_result:<regex> Returns regular expression matches on the returned keyword value as an array.
 
For use in conjunction with the Regular Expression asset. For more information, refer to the Regular Expression chapter in the Other CMS Assets manual. 
prepend:<string> Prepend a string at the beginning of the returned value.
 
Example: %asset_assetid^prepend:#%
Effect: 123 > #123
prepend_if:<string> Prepend a string at the beginning of the returned value if it is not empty.
 
Example: %asset_assetid^prepend_if:#%
Effect: 123 > #123 
rawurldecode Displays the URL-decoded equivalent of a returned value (RFC 3986 compatible).

Example:
%asset_url^rawurldecode%
Effect: site.com%2%3Floc%3Dsth%20aus > site.com/?loc=sth aus
rawurlencode Displays the URL-encoded equivalent of a returned value (RFC 3986 compatible).

Example:
%asset_url^rawurlencode%
Effect: site.com/?loc=sth aus > site.com%2%3Floc%3Dsth%20aus
replace:<string:replacestring> Replaces a string in the returned value with the value of a specified replace string. You can use regular expression values on the string that is to be replaced [see note 1 below].

Example:
%asset_name^replace:Matrix:CMS%
Effect: Squiz Matrix > Squiz CMS
reverse Reverses the returned value of a keyword. This modifier is best used in conjunction with other modifiers, to further configure a returned value.

Example: %asset_name^reverse%
Effect:
Page > egaP

Example:
%asset_name^reverse^maxchars:4^reverse%
Effect:
PageHome > Home
round:<precision> Rounds a returned numerical value to a specific number of decimal places determined by a set precision argument. If no precision argument is set, the returned value will round to the nearest whole integer.

Example:
%item_price^round:1%
Effect: 1.36 > 1.4
sha1 Displays the computer SHA1 hash of the returned value.

Example:
%asset_name^sha1%
Effect: Home > 70f8bb9a8a5393ef080507a89e4b98d139000d65
sign:<plus:minus:zero> Displays the sign (+, - or 0) of a returned numerical value. This returned sign can be overridden with plus, minus and zero arguments.

Example:
%asset_version^sign%
Effect: 0.2.123 > +

Example: %asset_version^sign:up:down:even%
Effect: 0.2.123 > up
squareroot Displays the square root of a returned numerical value.

Example:
%item_price^sqareroot%
Effect: 25 > 5
stripdecl Removes an XML declaration from a returned value.

Example:
%order_xml^stripdecl%
Effect: Removes XML declaration, eg.
<?xml version="1.0" encoding="ISO-8859-1"?>
striphtml:<allowable tags> Removes any HTML from a returned value using the strip_tags PHP function.
 
Example:
%asset_contents^striphtml%
Before: <u>Contents</u>
After: Contents

You can optionally pass the <allowable tags> argument to restrict the modifier from removing certain HTML tags.
 
Example: %asset_contents^striphtml:<p><strong>%
Before: <div><p><strong>Contents</strong></p></div> 
After: <p><strong>Contents</strong></p>
subtract:<numeral> Subtracts a set numeral argument from a returned numerical value.

Example:
%asset_assetid^subtract:6%
Effect: 111> 105
tag:<tagname> Wraps a returned value in a set tagname argument XML tag.

Example:
%asset_name^tag:h1%
Before: About Us
After: <h1>About Us</h1>

You can also add additional attributes to the tag:

Example: %asset_name^tag:h1 class="heading%
Before: About Us
After: <h1 class="heading">About Us</h1>
tagif:<tagname> Wraps a returned non-empty value in a set tagname argument XML tag. If the returned value is empty, no tags are printed.

Example: %asset_metadata_description^tagif:p%
Before: About Squiz Matrix
After: <p>About Squiz Matrix</p>

You can also add additional attributes to the tag:

Example: %asset_metadata_description^tagif:p class="description%
Before: Squiz Matrix
After: <p class="description">About Squiz Matrix</p>
titleize Capitalises the first character of each word in a returned value.

Example:
%asset_name^titleize%
Effect: home page > Home Page
trim Strips whitespace from the beginning and end of a returned value.

Example:
%asset_content^trim%
Effect: content > content
unescapehtml  Works in the opposite manner to the escapehtml modifier.
 
Converts the global GET/POST/SESSION/COOKIE keywords' values to their original unescaped versions.
 

This modifier can cause XSS vulnerabilities and should only be used in specific implementations.

underscore Replaces white-space (ie. spaces, tabs, newlines) in a returned value with underscores.

Example:
%asset_name^underscore%
Effect: Home Page > Home_Page
uppercase Displays a returned value in uppercase.

Example:
%asset_name^uppercase%
Effect: training > TRAINING
urldecode Displays the URL-decoded equivalent of a returned value.

Example:
%asset_url^urldecode%
Effect: example.com%2Fhome > example.com/home
urlencode Displays the URL-encoded equivalent of a returned value.

Example:
%asset_url^urlencode%
Effect: example.com/home > example.com%2Fhome
wordcount Displays the total words in a returned value.

Example:
%asset_name^wordcount%
Effect: Home Page of My Site > 5
xpath:<delimiter:xpath> Runs a set xpath argument query on a returned value and inserts a set delimiter argument between each returned element.

Example:
%asset_contents^xpath:<li><li>://item/title%
Effect: The path lists all titles in the feed, delimited by </li><li>.
xpathe:<expression> Evaluates a set xpath expression on a returned value.

Example:
%asset_contents^xpathe:count(//h1)%
Effect: Counts the number of level 1 headings in the content of the asset.
xslt:<assetid> Applies the XSLT of a file type asset (specified by asset ID) to the XML content of a returned value.

Example:
%asset_contents_raw^xslt:190%
Effect: Applies the XSLT of the file asset (#190) to our asset content XML.

Note 1: 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:

Pre Modifier Operation
with_get:<parameters> Sets a specified set of global GET parameter values (in URL query format) on the root keyword.

Example: %globals_asset_contents:187^with_get:root=187%
Effect: Passes the GET var "root" when outputting the content of asset #187.
with_post:<parameters> Sets a specified set of global POST parameter values (in URL query format) on the root keyword.

Example: %globals_asset_contents:187^with_post:root=187%
Effect: Passes the POST var "root" when outputting the content of asset #187.
with_context:<context> Sources the returned value from the specified context.

Example:
%globals_asset_contents^context:French%
Effect: Returns the asset content in the French context.

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

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.