Help Center

Menu

Keyword modifiers

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.

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.

Reserved characters

The : and ^ characters are reserved for use within keyword system and must 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 must be double-escaped.

In the examples below, the reserved characters are escaped according to these rules:

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

Keywords nested within a modifier are enclosed in braces ({ and }) 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 use the text {asset_metadata_price} and 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 {} 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).

Keyword modifiers

Keyword modifier Description

Pre-keyword evaluation modifiers

Unlike the standard keyword modifiers, the pre keyword evaluation modifiers are evaluated before the root keyword is evaluated. This type of modifier can be used in conjunction with the regular keyword modifiers described in Keyword modifiers.

Keyword replacement Description

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]

  • [|~!@#$*={}+;.,'"]

For example, %asset_metadata_foo^replace:(\s):_% removes any white space, as understood by PHP, and replaces it with an underscore.

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

The following characters needs to be double escaped with two backslashes: ^. For example, replace:\\^:caret

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

The following characters are not supported in regex on this keyword modifier:

  • & is converted to &

  • < is converted to &lt;.

  • > is converted to &gt;.

The % character is used within the keyword syntax system and are also not supported in regex on this keyword modifier.