Variable Modifiers

As of March 2017, Branch Code is deprecated and no longer developed. Use the Twig syntax instead.

Variable tags have a number of modifiers that let you either modify the variable value or perform some sort of action on the variable.

Outputting and Saving the modified variable

Some variable modifiers are intended to output the modified variable value. Some are intended to save the modified value back to the original variable. There are two options that are usually used with those types of modifiers: output and save.

output: This option is typically used on variable modifiers that are intended to output the modified variable value. It can be set to "no" or "false" to not output the value. That would typically happen if you're saving the value to another variable.

save: This option is typically used on variable modifiers that are intended to save the modified variable value back to the original variable. You can set it to "no" or "false" to not save the value back to the original variable. This will usually result in the value being outputted, unless there is an output option to control that as well.

saveAs: With this option you can save the modified value to a new variable.

Note that with anything, there are a few exceptions to the above guidelines.

18
ModifierDescription
append back to top

Append a string value to the variable and saves the result. Does not output the result. If the variable does not exist it will be created. The value can be appended to an array as well in two different ways. If the variable is an array already and the "key" parameter is not passed then the value will be added to the array stack. If the variable is an array and the key parameter is passed the value will be appended as a string to that array key. If that array key does not exist it will be created add set to the value.

Required options

value The value to add to the end of the variable.

Optional options

key The array key that should be used to add the new value to the variable if the variable is an array.
space Whether or not to put a space before the value. This only applies if the variable is a string or if the variable is an array and the specified array key already exists.

Examples

Add " world" to the variable.

{#variable|append value=" world"}

Create a new array and add values to it

{#variable|array}
{#variable|append value="value 1"}
{#variable|append value="value 2"}

Add a value with an array key

{#variable|append key="key" value="world"}

Add a value and have a space before it

{#variable|append value="world" space="yes"}

Examples using a variable as the value

You can use a variable as the value for the variable modifier. It's called a nested variable. You cannot, however, nest a variable within another nested variable.

Correct

{#variable|append value="{#var2}"}

Incorrect

{#variable|append value="{#name|append value=' {#last}'}"}

Use a variable as a value with a variable modifier

You can use variable modifiers on the nested variable. That modifier can include parameters so long as the quotes used are different then the quotes used with the main variable.

{#variable|append value="{#var2|upper}"}

{#variable|append value="{#var2|append value=' another value'}"}

Use multiple variables in the value

In this example we are setting the first and last name as the value. We are also using the ucfirst modifier to capitalize the first letter of the first name.

{#fullName|append value="{#first|ucfirst} {#last}"}

Using a variable within a string

You can also include the nested variable within a string

{#variable|append value="Hi, my name is {#name}. How are you?"}

{#variable|append value="Hi, my name is {#name|ucwords}. How are you?"}

array back to top

Sets an existing variable to be an array or creates a new variable as an array.

Optional options

key The array key to set. The value can be another variable.

Examples

Create an empty array

{#variable|array}

Setting a key when creating the array

{#variable|array key="keyName"}
{#variable|array key="{#otherVariable}"}

Creating a multi-dimensional array

{#variable.key|array} or {#variable.key.key2|array}

autoEmbed back to top

Takes a string and looks for any URLs for embeddable resources (YouTube videos for example) and using the oEmbed protocol converts the URL into the appropriate embed code. 

Multiple URLs can be converted in the same string. 

The URLs are the URL for the page that the content exists on. For example, for YouTube you could use https://www.youtube.com/watch?v=iwGFalTRHDA . You don't need to get any special embed URL or code. 

For a full list of supported providers see the Embed URL attribute documentation.

By default the value is outputted automatically. 

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Embed just one URL

Assume that the variable holds a value with just a single URL like https://www.youtube.com/watch?v=iwGFalTRHDA

This will output the following:

{#variable|autoEmbed}

This will output the following code:

<iframe width="459" height="344" src="https://www.youtube.com/embed/iwGFalTRHDA?feature=oembed" frameborder="0" allowfullscreen></iframe>

Find embeddable URLs in a sentence

Assume that the variable contains the following:

<p>Vimeo video:<br> https://vimeo.com/180528272</p><p>YouTube video:<br>https://www.youtube.com/watch?v=rdBYmk4dfLE</p>

The following is outputted:

Vimeo video:

YouTube video:

{#variable|autoEmbed}

This will output the following code:

<p>Vimeo video: <br><iframe src="https://player.vimeo.com/video/180528272" width="640" height="360" frameborder="0" title="SpaceX - Igniting Interest In Space Exploration" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe></p><p>YouTube video:<br><iframe width="480" height="270" src="https://www.youtube.com/embed/rdBYmk4dfLE?feature=oembed" frameborder="0" allowfullscreen></iframe></p>

Get the embed code and save the value back to the same variable

{#variable|autoEmbed save="yes" output="no"}

Get the embed code and save the value to a different variable

{#variable|autoEmbed saveAs="otherVariable" output="no"}

capitalize strtoupper upper back to top

Makes all letters in the variable upper case.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Capitalize and output the value

{#variable|capitalize}

Save the value back to the original value and don't output the value.

{#variable|capitalize save="yes" output="no"}

ceiling back to top

Rounds up a number and saves the result to the variable. Does not output the result. The variable value should be a number. If not, it will be converted to a float.

Examples

{#variable|ceiling}

changeApiTagWrapper back to top

This will change the HTML tag that is surrounding an API tag. 

The TinyMCE editor (the rich text editor used in the software) forces everything to be wrapped in a block level element. This is a good thing. By default if you simply paste an API tag into the editor the tag will be wrapped with <p></p> tags. This can cause validation and layout issues if the API content template is also outputting block level elements like a <div> or another <p> tag. You can easily change the <p> tag in the editor to a <div> tag but you can't always count on content editors to do that. That is where this variable modifier comes in.

By default this modifier will look for an API tag (any tag that starts with {ap_api and ends with } ) that is surrounded by a <p> tag and replace the <p></p> tags with <div></div> . You can of course change the search tag and the replacement tag.

Optional options

attributes Any HTML attributes to add to the new tag. If this is set then the new attributes will replace any existing attributes on the original HTML tag.
output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
replace The name of the HTML tag to replace the search tag with. Do not include the brackets < >.
Default value: div
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".
search The name of the HTML tag to search for to be replaced by the replace tag. Do not include the brackets < >.

Examples

Replace <p> tags around an API tag with <div> tags.

Assume that the variable holds the following HTML:
<p>{ap_api:blog:postFilter templateId="3"}</p>

We want it to be:
<div>{ap_api:blog:postFilter templateId="3"}</div>

{#variable|changeApiTagWrapper}

Replace <p> tags around an API tag with <div> tags and add a style attribute.

Assume that the variable holds the following HTML:
<p>{ap_api:blog:postFilter templateId="3"}</p>

We want it to be:
<div style="float: right;">{ap_api:blog:postFilter templateId="3"}</div>

Note that if tag attributes contain double quotes then you must use single quotes for the value option (or vice versa).

{#variable|changeApiTagWrapper attributes='style="float:right;"'}

countryAbbreviation back to top

Gets the 2 letter country abbreviation for the variable value if the variable value is a valid country or country abbreviation.

By default the value will be outputted.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Default behavior

This will output the abbreviation. The value will not be saved back to the original variable.

{#variable|countryAbbreviation}

Save the abbreviation instead of outputting it

This will save the abbreviation back to the original variable instead of outputting it.

{#variable|countryAbbreviation save="yes" output="no"}

This will save the abbreviation to a new variable named "country" instead of outputting it.

{#variable|countryAbbreviation saveAs="country" output="no"}

countryData back to top

Gets an array of country data for the variable value if the variable value is a valid country or country abbreviation.

The array contains the following information.

name: the full country name
abbreviation: the 2 letter country abbreviation
abbreviationLong: the 3 letter country abbreviation

If the variable value does not contain a valid country name or abbreviation then the returned value is an empty array.

By default the value will be saved back to the original variable.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|countryData}

You can then access the information like an array.

{#variable.name}
{#variable.abbreviation}
{#variable.abbreviationLong}

countryName back to top

Gets the full country name for the variable value if the variable value is a valid country or country abbreviation.

By default the country name will be outputted.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Default behavior

This will output the country name. The value will not be saved back to the original variable.

{#variable|countryName}

Save the country name instead of outputting it

This will save the country name back to the original variable instead of outputting it.

{#variable|countryName save="yes" output="no"}

This will save the country name to a new variable named "country" instead of outputting it.

{#variable|countryName saveAs="country" output="no"}

date back to top

Formats a timestamp as a date string. See the Date Formats page for available date and time formats.

Required options

format The date format

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Format a date as a year and output it

{#variable|date format="Y"}

Format a date and save it to another variable without outputting it

{#variable|date format="M d, Y" saveAs="newVariable" output="no"}

debug back to top

Debug a variable to see what value it has.

Examples

{#variable|debug}

decrement subtract back to top

Decrements a numeric variable by a certain numeric value. The variable should be a number. By default the new value is saved back to the original variable and not outputted.

Required options

value The number to subtract from the variable.

Optional options

key If the variable is an array this would be the array key of the value to decrement.
output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".
type The type of value the number should be treated as. It could be an integer or float value. "int" means integer.
Default value: int
Accepted values: "int" , "float"

Examples

Subtract 3 from a variable

{#variable|decrement value="3"}

Use another variable to decrement

{#number|set value="1"}
{#variable|decrement value="{#otherVariable}"}

default back to top

Outputs a default value for a variable if the variable does not exist or does not have a value. This is similar to the set modifier except that this one outputs the value instead of saving it.

Required options

value The default value

Examples

{#variable|default value="My Default Value"}

divide back to top

Divides the variable value by a number. By default this saves the result back to the variable and does not output the result. The variable should be a number, although strings could also be used.

Required options

value The value to divide by

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Divide a variable by 3

(assuming that the variable value is already a number)

{#variable|divide value="3"}

Save the value to a new variable and don't output the value.

{#variable|divide value="2" saveAs="newVariable" output="no"}

escapeCurlyBrackets back to top

Escapes the opening curly bracket { by wrapping it in a span tag so that any Aptuitiv code isn't processed. This is useful if you are writing any example Aptuitiv code on a page.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|escapeCurlyBrackets}

escapeQuotes back to top

Escapes single and double quotes with a backslash "\". By default it will escape both double and single quotes.

Optional options

double Whether or not to escape double quotes
Default value: yes
Accepted values: "yes" , "no"
single Whether or not to escape single quotes
Default value: yes
Accepted values: "yes" , "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"

Examples

Escape both single and double quotes

{#variable|escapeQuotes}

Only escape single quotes

{#variable|escapeQuotes double="no"}

Only escape double quotes

{#variable|escapeQuotes single="no"}

Escape both single and double quotes and save to the variable

{#variable|escapeQuotes save="yes"}

explode back to top

Splits a string into an array on the specified delimiter. The result is saved to a new variable specified by the 'saveAs' option.

Required options

delimiter The string delimiter to split the variable value on.
saveAs The name of the variable to save to. The value should not contain brackets or "#".

Examples

Explode an array and save it to a new variable

In this example a new variable called is created and now contains an array of 3 letters.

If you're using this inside of a loop it's highly recommended that you define the new variable first. If you don't do that then in the next iteration of the loop that new variable will already exist with the values from the previous iteration.

{#variable|set value="a,b,c"}
{#variable|explode delimiter="," saveAs="new"}

Using the above example we define the {#new} variable as an empty array first.

{#new|array}
{#variable|set value="a,b,c"}
{#variable|explode delimiter="," saveAs="new"}

first back to top

Retrieves the first value from an array. The value can be saved to a new variable or outputted. If the variable is a string then the first letter is retrieved.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Get and output the first value of the array held by {#variable}.

{#variable|first}

Get the first value of the array held by {#variable} and save to a variable called {#new}.

{#variable|first saveAs="new"}

Get the first value of the array held by {#variable}. Then, if that value is an array and it has a value with an array key called "key" get that value and save it to a variable called {#new}.

{#variable|first saveAs="new" key="key"}

floor back to top

Rounds down a number and saves the result to the variable. Does not output the result. The variable value should be a number. If not, it will be converted to a float.

Examples

{#variable|floor}

get back to top

Gets an array value for the specified array key.

Required options

key The array key to retrieve the value from.

Optional options

default A default value to use if the array key does not exist in the array.
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Get a value at the array key "key"

{#variable|get key="key"}

Get a value and if it doesn't exist use a default value

{#variable|get key="key" default="default value"}

Get a value and save it to a new variable

{#variable|get key="key" saveAs="newVariable"}

html2Text back to top

This will convert HTML to plain text. 

The following modifications will occur.

  • All HTML tags will be removed.
  • Any <br /> tags will be converted to a new-line character.
  • Any <p> tags will have two new-line characters added after the closing </p> tag.
  • Any link URLs will get added to the bottom of the text with a reference after the original link to the URL.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Convert the HTML to plain text and output the result

{#variable|html2Text}

Convert the HTML to plain text and save it back to the original variable and do not output the result.

{#variable|html2Text save="yes" output="no"}

Convert the HTML to plain text and save it to a new variable and do not output the result.

The new variable is called {#newVar}

{#variable|html2Text saveAs="newVar" output="no"}

htmlentities back to top

Convert all applicable characters to HTML entities.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|htmlentities}

htmlSpecialCharacters back to top

Escapes any HTML special characters in a variable value.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|htmlSpecialCharacters}

implode back to top

Joins array values together as a string.

This will only work on variables whose value is an array. If the variable value is not an array then nothing will happen and the original value will simply be returned.

By default the imploded value will be outputted. However, you can turn that off with the output option, save the imploded value to a new variable with the saveAs option or save the imploded value back to the original variable with the save option.

Required options

glue The string to use to "glue" the array values together.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

In this example a new variable called is created and now contains the following value: a, b. The imploded value is not outputted.

If you're using this inside of a loop it's highly recommended that you define the new variable first. If you don't do that then in the next iteration of the loop that new variable will already exist with the values from the previous iteration.

{#new|set value=""}
{#variable|array}
{#variable|append value="a"}
{#variable|append value="b"}
{#variable|implode glue=", " saveAs="new" output="no"}

increment add back to top

Increments a numeric variable by a certain numeric value. The variable should be a number. By default the new value is saved back to the original variable and not outputted.

Required options

value The number to add to the variable

Optional options

key If the variable is an array this would be the array key of the value to increment.
output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".
type The type of value the number should be treated as. It could be an integer or float value. "int" means integer.
Default value: int
Accepted values: "int" , "float"

Examples

Adds 3 to the variable

{#variable|increment value="3"}

Use another variable to increment.

{#number|set value="1"}
{#variable|increment value="{#number}"}

Save the incremented value to a new variable called "new" instead of the original variable.

{#variable|increment value="2" saveAs="new" save="no"}

injectHtml back to top

Inserts an HTML snippet immediately before a closing block level tag (</p> </div>) or a closing span tag </span> if they are the last HTML tag in the variable value. If they are not then the HTML snippet is simply appended to the variable value.

Required options

value The HTML snippet to inject into the variable content.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

{#var|injectHtml value=' <a href="/more">read more</a>' output="yes" save="yes" saveTo="newVariable"}

The variable {#var} contains the following HTML:

<p>Hello.</p>

We want to inject the following code before the closing </p> tag:

<a href="/more">read more</a>

Note that if value contains double quotes you must use single quotes for the value option.

{#var|injectHtml value=' <a href="/more">read more</a>'}

The resulting HTML will be:

<p>Hello <a href="/more">read more</a></p>

integer int back to top

Converts the variable value to an integer. 

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Convert the variable value to an integer if it was not already.

{#variable|integer}

Save the value back to the original value and don't output the value.

{#variable|integer save="yes" output="no"}

json back to top

Encodes the variable as a complete JSON string.  The variable can be an array or a string.

If the key option is not set then "data" is used.

Optional options

key The root key to use in the JSON string.
Default value: data
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
useKey Whether or not to output the variable as the value for the root key specified in the key parameter.
Default value: yes
Accepted values: "yes, true, no, false"

Examples

Assume that the variable is an array:

array(
fruit: 'apple',
vegetable: 'lettuce'
)

{#variable|json}

That would output

{"data":{"fruit":"apple","vegetable":"lettuce"}}

If we wanted to set a different root key we would do the following:

{#variable|json key="food"}

That would output

{"food":{"fruit":"apple","vegetable":"lettuce"}}

"useKey" Settings

If we wanted the JSON object to not be assigned to the root key:

{#variable|json useKey="no"}

That would output

{"fruit":"apple","vegetable":"lettuce"}

Instead of

{"data":{"fruit":"apple","vegetable":"lettuce"}}

jsonDecode back to top

Converts a JSON formatted string into an array.

By default the variable is overwritten with the new array value. The value is not outputted by default.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Decode a JSON string

{#variable|jsonDecode}

jsonValue back to top

Encodes a value to be a part of a JSON string.  This helps to properly quote and escape characters.

Examples

{#variable|jsonValue}

Below is some example code that could be used in a Content Template.

{fruit: {#variable|jsonValue}}

last back to top

Retrieves the last value from an array. The value can be saved to a new variable or outputted. If the variable is a string then the last letter is retrieved.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Get and output the last value of the array held by {#variable}.

{#variable|last}

Get the last value of the array held by {#variable} and save to a variable called {#new}.

{#variable|last saveAs="new"}

Get the last value of the array held by {#variable}. Then, if that value is an array and it has a value with an array key called "key" get that value and save it to a variable called {#new}.

{#variable|last saveAs="new" key="key"}

length count back to top

Gets the length of a string or the number if items in an array.  By default this will output the result.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|length}

or

{#variable|count}

Save the value to a new variable and don't output the value.

{#variable|count saveAs="newVariable" output="no"}

lower strtolower back to top

Makes all letters in the variable lower case.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|lower}

Save the value back to the original value and don't output the value.

{#variable|lower save="yes" output="no"}

ltrim back to top

Trims a variable (strips whitespace and optionally other characters from the beginning of a string. If substring option is passed the exact substring (case insensitive) plus whitespace characters will be removed.

Optional options

substring A sub string to remove from the beginning of the string.
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"

Examples

{#variable|ltrim}

md5 back to top

Converts the string to a MD5 hash.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|md5}

Save the value back to the original value and don't output the value.

{#variable|md5 save="yes" output="no"}

An example use case could be to to show the Gravatar image for someone.

Gravatar works using an MD5 hash of an email address to retrieve the person's avatar image.

<img src="https://www.gravatar.com/avatar/{#email|md5}">

md5Hmac back to top

Converts the string to a MD5 hash using the HMAC method.

Required options

key Shared secret key used for generating the hash
Accepted values: "Any string"

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|md5Hmac key="secret"}

Save the value back to the original value and don't output the value.

{#variable|md5Hmac key="secret" save="yes" output="no"}

Submitting information to an Authorize.net payment form

Authorize.net hosted payment forms require that you submit what they call a "fingerprint hash". The hash is a combination of the API Login Id, a random set of numbers, the current timestamp and the amount separated by a "^" and hashed using the HMAC-MD5 hashing algorithm.

Below is a basic payment form that shows how this could be used.

{** Payment Amount **}
{#amount|set value="10"}

{** Sequence Number **}
{#sequence|set value="1234"}

{** API Login Id **}
{#loginId|set value="YOUR_API_LOGIN_ID"}

{** Build the string used to generate the hash **}
{#source|set value="{#loginId}"}
{#source|append value="^"}
{#source|append value="{#sequence}"}
{#source|append value="^"}
{#source|append value="{#global.timestamp}"}
{#source|append value="^"}
{#source|append value="{#amount}"}
{#source|append value="^"}

{** Generate the hash value and save it to a variable called "hash". The API key is used as the hash key value **}
{#source|md5Hmac key="96jNbQ6Gd3625ZgE" output="no" saveAs="hash"}

{** Build the form **}
<form method="post" action="https://secure.authorize.net/gateway/transact.dll">
<input type="hidden" name="x_fp_hash" value="{#hash}">
<input type="hidden" name="x_fp_sequence" value="{#sequence}">
<input type="hidden" name="x_fp_timestamp" value="{#global.timestamp}">
<input type="hidden" name="x_version" value="3.1">
<input type="hidden" name="x_login" value="{#loginId}">
<input type="hidden" name="x_show_form" value="PAYMENT_FORM">
<input type="hidden" name="x_method" value="CC">
<input type="hidden" name="x_amount" value="{#amount}">
<input type="hidden" name="x_description" value="Payment Description">
<input type="submit" value="Buy">
</form>

modulus back to top

Finds the remainder of division by dividing the variable value by a number .  By default this saves the result back to the variable and does not output the result. The variable should be a number, although strings could also be used.

Required options

value The number to divide by.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Divide a variable by 3 and save the remainder

(assuming that the variable value is already a number)

{#variable|modulus value="3"}

Save the value to a new variable and don't output the value.

{#variable|modulus value="2" saveAs="newVariable" output="no"}

multiply back to top

Multiplies the variable value by a number.  By default this saves the result back to the variable and does not output the result. The variable should be a number, although strings could also be used.

Required options

value The value to multiply by.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Multiply a variable by 3

(assuming that the variable value is already a number)

{#variable|multiply value="3"}

Save the value to a new variable and don't output the value.

{#variable|multiply value="2" saveAs="newVariable" output="no"}

nl2Array back to top

Takes a string and breaks it up by new line character and saves the result as an array.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Break up {#variable} by new line character and save the result as an array back to {#variable}

{#variable|nl2Array}

Break up {#variable} by new line character and save the result as an array to a new variable called {#var}.

{#variable|nl2Array saveAs="var" save="no"}

nl2br back to top

Converts new line characters to <br />.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Convert new lines in {#variable} to <br /> tags and output the result.

{#variable|nl2br}

Convert new lines in {#variable} to <br /> tags and save it back to {#variable}.

The result will not be outputted.

{#variable|nl2br save="yes" output="no"}

Convert new lines in {#variable} to <br /> tags and save it to a new variable called {#var}.

The result will not be outputted.

{#variable|nl2br saveAs="var" output="no"}

nlc2Array back to top

Takes a string and breaks it up by new line character and by comma and saves the result as an array.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Break up {#variable} by new line character and comma and save the result as an array back to {#variable}

{#variable|nlc2Array}

Break up {#variable} by new line character and comma and save the result as an array to a new variable called {#var}.

{#variable|nlc2Array saveAs="var" save="no"}

number back to top

Format a string as a number.

Optional options

decimalSeparator The decimal separator
Default value: a period "."
numberDecimalPlaces The number of decimal places to use.
output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".
thousandSeparator The thousands separtor.
Default value: a comma ","

Examples

{#variable|number}

obfuscate back to top

Obfuscates part of a string with another character. This could be used to display sensitive information like credit card numbers.

Optional options

character The character used as the replacement character.
Default value: *
length The length of the string to obfuscate. If left out then the entire string will be obfuscated.
output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".
start The character in the string to start at.
Default value: 0 (the first character)

Examples

In these examples assume that {#variable} holds a value of 1111222233334444.

Output the value: **********334444.

{#variable|obfuscate length="10"}

Save the value back to the original value and don't output the value.

{#variable|obfuscate length="10" save="yes" output="no"}

Output the value but use X as the character and do 12 characters: XXXXXXXXXXXX4444.

{#variable|obfuscate length="12" character="X"}

prepend back to top

Prepends a string value to a variable and saves the result.  Does not output the result.

If the variable does not exist it will be created. The value can be prepended to an array as well in two different ways. If the variable is an array already and the "key" parameter is not passed then the value will be added to the beginning of the array stack. If the variable is an array and the "key" parameter is passed the value will be prepended as a string to that array key. If that array key does not exist it will be created add set to the value.

Required options

value The value to add to the beginning of the variable.

Optional options

key The array key that should be used to add the new value to the variable if the variable is an array.
space Whether or not to put a space after the value. This only applies if the variable is a string or if the variable is an array and the specified array key already exists.

Examples

Prepend "hello " to the variable.

{#variable|prepend value="hello "}

Add "hello" to the beginning of {#variable.key}

{#variable|prepend key="key" value="hello"}

Prepend " hello" to the variable

(notice the space)

{#variable|prepend value="hello" space="yes"}

Examples using a variable as the value

You can use a variable as the value for the variable modifier. It's called a nested variable. You cannot, however, nest a variable within another nested variable.

Correct

{#variable|prepend value="{#var2}"}

Incorrect

{#variable|prepend value="{#name|append value=' {#last}'}"}

Use a variable as a value with a variable modifier

You can use variable modifiers on the nested variable. That modifier can include parameters so long as the quotes used are different then the quotes used with the main variable.

{#variable|prepend value="{#var2|upper}"}

{#variable|prepend value="{#var2|append value=' another value'}"}

Use multiple variables in the value

In this example we are setting the first and last name as the value. We are also using the ucfirst modifier to capitalize the first letter of the first name.

{#fullName|prepend value="{#first|ucfirst} {#last}"}

Using a variable within a string

You can also include the nested variable within a string

{#variable|prepend value="Hi, my name is {#name}. How are you?"}

{#variable|prepend value="Hi, my name is {#name|ucwords}. How are you?"}

removeNewLines back to top

Removes line breaks from a string.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|removeNewLines}

replace back to top

Replaces all occurrences of the search string with the replacement string in the variable.

Required options

replace The value to replace the search value with.
search The value to search for in the variable value. This value will be replaced.

Optional options

save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"

Examples

Assume that {#variable} holds a value of "100 little monkeys"

{#variable|replace search="monkeys" replace="elephants"}

This will output "100 little elephants"

reverse back to top

If the variable is an array then the array is reversed. If it's a string then the order of the string is reversed.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Reverse the variable value and save it back to {#variable}.

{#variable|reverse}

Reverses the variable value and saves to a new variable called {#new}.

{#variable|reverse saveAs="new" save="no"}

round back to top

Round a number and saves the result to the variable. By default this does not output the result.The variable value should be a number. If not, it will be converted to a float.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Round the variable and save it back to itself.

{#variable|round}

Round the variable but don't save it. Output it instead.

{#variable|round save="no" output="yes"}

rtrim back to top

Trims a variable (strips whitespace and optionally other characters from the end of a string. If substring option is passed the exact substring (case insensitive) plus whitespace characters will be removed.

Optional options

substring A sub string to remove from the end of the string.
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"

Examples

{#variable|rtrim}

set assign back to top

Set a value to the string.  Does not output the new value. This can also be used to set a value to an array.

If the variable has content already this will overwrite that content. If you need to add to string or array use prepend or append

Required options

value The value to set to the variable.

Optional options

key If the variable is an array this will be used as an array key to assign the value to.

Examples

Set a value

{#variable|set value="variable value"}

Set a value using another variable

If the variable does not exist it will be created either as a string or as an array if the "key" parameter is set.

{#var|set value="{#variable}"}

Setting a multi-dimensional array

{#var.key.key2|set value="val"} turns into: array('key' => array('key2' => 'val'))

or

{#var.key.key2|set key="key3" value="val"} turns into: array('key' => array('key2' => array('key3' => 'val')))

Examples using a variable as the value

You can use a variable as the value for the variable modifier. It's called a nested variable. You cannot, however, nest a variable within another nested variable.

Correct

{#variable|set value="{#var2}"}

Incorrect

{#variable|set value="{#name|append value=' {#last}'}"}

Use a variable as a value with a variable modifier

You can use variable modifiers on the nested variable. That modifier can include parameters so long as the quotes used are different then the quotes used with the main variable.

{#variable|set value="{#var2|upper}"}

{#variable|set value="{#var2|append value=' another value'}"}

Use multiple variables in the value

In this example we are setting the first and last name as the value. We are also using the ucfirst modifier to capitalize the first letter of the first name.

{#fullName|set value="{#first|ucfirst} {#last}"}

Using a variable within a string

You can also include the nested variable within a string

{#variable|set value="Hi, my name is {#name}. How are you?"}

{#variable|set value="Hi, my name is {#name|ucwords}. How are you?"}

setapi back to top

Sets the value of a variable to be the result of an API call.

By default the API response will be an array of data.  You can have the response run through an App Content Template by specifying the templateId and responseFormat values.

Required options

call The API call to make

Optional options

key If the variable is an array this will be used as an array key to assign the value to.
responseFormat How the API call response will be returned. data or template. Defaults to data. data means that the response will be an array. template means that the response will be passed through an App Content Template.

Any option that you would normally set for an API tag you could set as an option for the modifier.

Examples

Return 5 posts from the blog as an array

{#variable|setApi call="blog.postFilter" limit="5"}

Return 5 posts from the blog after it's been processed by the blog content template with an id of 1.

{#variable|setApi call="blog.postFilter" templateId="1" limit="5" responseFormat="template"}

Get a single app item based on it's id.

In this example we're using a variable called {#itemId} that would have been setup in earlier code to contain the numeric id of the item to return.

{#variable|setApi call="app.itemFilter" attr[id]="{#itemId}"}

sha1 back to top

Converts the string to a SHA1 hash.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|sha1}

Save the value back to the original value and don't output the value.

{#variable|sha1 save="yes" output="no"}

shuffle randomize back to top

If the variable value is an array then the contents of the array will be reordered in a random order.

If the variable value is a string then the characters in the string will be randomly shuffled.

By default the value will be shuffled and then saved back to the variable without outputting the new value.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Shuffle the variable value without outputting the result.

{#variable|shuffle}

"randomize" does the same thing as "shuffle".

{#variable|randomize}

Shuffle the variable value and save to a new variable called {#newVariable}

{#variable|shuffle save="no" saveAs="newVariable"}

sort back to top

Sorts the array by the array values. By default it sorts in ascending order and the result is saved back to the same variable.

If the variable is not an array then nothing will happen.

Optional options

direction The direction to sort in. Ascending or descending
Default value: asc
Accepted values: "asc or desc"
output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Sort an array in ascending order and save it back to the variable.

{#array|sort}

Sort an array in descending order and save to another variable.

{#array|sort direction="desc" save="no" saveAs="newVariable"}

sortByKey back to top

Sorts the array by the array keys. By default it sorts in ascending order and the result is saved back to the same variable.

If the variable is not an array then nothing will happen.

Optional options

direction The direction to sort in. Ascending or descending
Default value: asc
Accepted values: "asc or desc"
output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Sort an array in ascending order by the array keys and save it back to the variable.

{#array|sortByKey}

Sort an array by the array keys in descending order and save to another variable.

{#array|sortByKey direction="desc" save="no" saveAs="newVariable"}

stateAbbreviation provinceAbbreviation back to top

Gets the 2 letter state/province abbreviation for the variable value if the variable value is a valid state/province or state/province abbreviation.

By default the value will be outputted.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Default behavior

This will output the abbreviation. The value will not be saved back to the original variable.

{#variable|stateAbbreviation}

Save the abbreviation instead of outputting it

This will save the abbreviation back to the original variable instead of outputting it.

{#variable|stateAbbreviation save="yes" output="no"}

This will save the abbreviation to a new variable named "state" instead of outputting it.

{#variable|stateAbbreviation saveAs="state" output="no"}

stateData provinceData back to top

Gets an array of state/province data for the variable value if the variable value is a valid state/province or state/province abbreviation.

The array contains the following information.

name: the full state/province name
abbreviation: the 2 letter state/province abbreviation

If the variable value does not contain a valid state/province name or abbreviation then the returned value is an empty array.

By default the value will be saved back to the original variable.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

{#variable|stateData}

You can then access the information like an array.

{#variable.name}
{#variable.abbreviation}

stateName provinceName back to top

Gets the full state/province name for the variable value if the variable value is a valid state/province or state/province abbreviation.

By default the state/province name will be outputted.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Default behavior

This will output the state/province name. The value will not be saved back to the original variable.

{#variable|stateName}

Save the state/province name instead of outputting it

This will save the state/province name back to the original variable instead of outputting it.

{#variable|stateName save="yes" output="no"}

This will save the state/province name to a new variable named "state" instead of outputting it.

{#variable|stateName saveAs="state" output="no"}

striptags back to top

Removes any HTML tags in the variable. The variable must be a string.

By default all HTML tags and comments will be removed, however, with the "remove" or "allowed" parameters you can either remove only specific tags or keep certain tags.

Optional options

allowed A comma separated list of allowed HTML tags.
output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
remove A comma separated list of specific HTML tags to remove.
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

If both "remove" and "allowed" are set the "remove" parameter will be used and "allowed" will be ignored.

Examples

{#variable|striptags}

Save the value instead of outputting it

This will save the value back to the original value instead of outputting it.

{#variable|striptags output="no"}

This will save the value to a new variable called "new" instead of outputting it.

{#variable|striptags output="no" saveAs="new"}

Removing specific tags

This will remove only "script" tags instead of all tags.

{#variable|striptags remove="script"}

This is how you can specify multiple tags to remove. In this example only "strong", "b", "em" and "i" tags will be removed.

{#variable|striptags remove="strong,b,em,i"}

Remove all tags except for certain ones

This will remove all tags except for links.

{#variable|striptags allowed="a"}

This is how you can specify multiple tags to keep. In this example only "p", "ol" and "li" tags will be kept. All other HTML tags will be removed.

{#variable|striptags allowed="p,ol,li"}

swap back to top

Swaps the value for a string. If the string equals swap1 then it is changed to swap2 and vice versa.

Required options

swap1 One value for the variable.
swap2 The other value for the variable.

Examples

{#variable|swap swap1="value 1" swap2="value 2"}

text2Html back to top

This will convert a plain text value to an HTML value. The following modifications will occur.

  • Any special characters like "&" will be converted to the appropriate HTML entity. For example & will get converted to &amp; .
  • Any plain text URLs will be converted to a HTML link with an optional link target set.
  • Any plain text FTP links will be converted to a HTML link with an option link target set.
  • Any plain text emails will be converted to a HTML "mailto" link.
  • New lines will be converted to <br /> or <br> tags.

Optional options

linkTarget The target for links.
Accepted values: "_blank" , "_self" , "_parent" , "_top"
output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
removeThisSiteDomain Whether or not the domain name and protocol of this site should be removed. If the domain of the site is "mydomain.com" this would convert http://www.mydomain.com/page to /page and https://www.mydomain.com/secure-page to /secure-page
Default value: yes
Accepted values: "yes" , "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Convert plain text to HTML

{#variable|text2Html}

Set the link target so that links will open in a new window

{#variable|text2Html linkTarget="_blank"}

Convert the plain text to HTML and save the value back to the original variable.

{#variable|text2Html save="yes" output="no"}

Convert the plain text to HTML and save the value to a new variable.

{#variable|text2Html saveAs="new" output="no"}

time back to top

Formats a timestamp as a time string. See the Date Formats page for available date and time formats.

Required options

format The time format.

Optional options

output Whether or not to output the value.
Default value: no
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Format the time as Hour:Minute AM (or PM) and output it

{#variable|time format="H:i A"}

Format a timestamp as Hour:Minute and save it to a new variable without outputting it.

{#variable|time format="H:i" saveAs="newVariable" output="no"}

timeAgo back to top

Formats a timestamp as human readable time ago from now (e.g. 2 minutes ago, 5 hours ago or 6 days ago).

Optional options

limit After 1 'limit' (e.g. 'day'), full date formatting will be used instead of time ago.
Accepted values: "second" , "minute" , "hour" , "day" , "week" , "month" , "year" , "decade"
format Date format used when full date formatting is used (if limit is specified).
Default value: M d, Y g:i a
Accepted values: "Any PHP date format"
simpleDays Sets whether or not to substitute "Today", or "Yesterday" into the formatted date (if limit is specified).
Default value: true
Accepted values: "true" , "yes" , "false" , "no"
simpleDayFormat The part of the date format that will be replaced with the simple day (e.g. 'M d, Y').
Default value: 'M d, Y'

Examples

Default Time Ago

{#post.publishedOnTimestamp|timeAgo}

Time Ago with Limit

{#post.publishedOnTimestamp|timeAgo limit="day"}

Time Ago with Limit and Custom Format

{#post.publishedOnTimestamp|timeAgo limit="day" format="M d, Y h:m a"}

Time Ago with Limit and No Simple Days

{#post.publishedOnTimestamp|timeAgo limit="day" simpleDays="false"}

Time Ago with Limit and Format and Simple Day Format

'simpleDayFormat' should always match a portion of 'format' for simpleDays to work properly.

{#post.publishedOnTimestamp|timeAgo limit="day" format="M D, Y g:i a" simpleDayFormat ="M D, Y"}

trim back to top

Trims a variable (strips whitespace and optionally other characters from the beginning and end of a string. If substring option is passed the exact substring (case insensitive) plus whitespace characters will be removed.

Optional options

substring A sub string to remove from the beginning of the string.
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"

Examples

Trim the variable and output it.

{#variable|trim}

truncate shorten back to top

Shortens a string variable.

Required options

length The new length of the string.

Optional options

append A string to append to the end of the truncated string.
Default value: … ....
preserveWords Whether or not to preserve whole words
Default value: true
Accepted values: "true" , "false"
useHtmlEntities Whether or not to preserve and not count HTML entities.
Default value: true
Accepted values: "true" , "false"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: false
Accepted values: "yes" or "no"
stripTags Whether or not to strip HTML tags.
Default value: false
Accepted values: "true" , "false"

Examples

Shorten the variable to 3 characters.

{#variable|truncate length="3"}

Shorten the blog post and strip HTML tags

{#post.content|truncate stripTags="true" length="100"}

ucfirst back to top

Makes the first letter upper case.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value

{#variable|ucfirst}

Save the value back to the original value and don't output the value.

{#variable|ucfirst save="yes" output="no"}

ucwords back to top

Makes the first letter of each word upper case.

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value

{#variable|ucwords}

Save the value back to the original value and don't output the value.

{#variable|ucwords save="yes" output="no"}

unique back to top

Takes an array and saves an new array with just the unique values back to the variable. 

If the variable value is not an array then nothing happens.

In many cases the values in the array are strings or numbers.

Multi-dimensional arrays

If your variable holds a multi-dimensional array where the values are each an array, then you can reduce the variable value down to unique values based on the 2nd level array values.

For example, say the that our variable {#deserts} contained an array of information about baked goods.

array(
  array(
    'name' => 'Chocolate cake',
    'type' => 'cake',
    'description' => 'Chocolate cakes are super good!'
  ),
  array(
    'name' => 'Upside Down Strawberry Cake',
    'type' => 'cake',
    'description' => 'The strawberries in this cake move from the top to the bottom.'
  ),
  array(
    'name' => 'Blueberry Pie',
    'type' => 'pie',
    'description' => 'Blueberry pies are great with vanilla ice cream.'
  ),
  array(
    'name' => 'Oatmeal Chocolate Chip Cookies',
    'type' => 'cookie',
    'description' => 'Oatmeal chocolate chip cookies are my favorite!'
  ),
  array(
    'name' => 'Apple Pie',
    'type' => 'pie',
    'description' => 'Apple pie is good with a little bit of caramel on the top.'
  )
)

If we wanted to reduce this down to only one of each type of desert (cake, pie and cookie) then we could specify the "type" array key to use that value as the unique value to compare.

{#deserts|unique key="type"}

That will leave us with just one cake, one pie and one cookie.

Optional options

save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: yes
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

Examples

Get unique values for an array

{#array|unique}

Get unique values and save them to another variable

{array|unique saveAs="otherVariable"}

If the values are an array then you can reduce the top level array by a value in the value arrays

{#array|unique key="myKey"}

unset back to top

This will either unset a variable or unsets a specific value from a variable if the variable is an array.

Unsetting the entire variable will completely clear it's value. 

Optional options

key The array key whose value should be removed or a comma separated string of array keys whose values should be removed.

Examples

Unset an entire variable

{#variable|unset}

Unset a single value in an array

{#variable|unset key="key1"}

Unset multiple values in an array

{#variable|unset key="key1, key2, key3"}

url back to top

Makes sure that a URL value is outputted correctly. If the URL doesn't start with "http" or another valid protocol then it will be added. (of course if the URL starts with "/" then that won't happen.) Also, if the URL starts with the website's domain then that is removed so that the URL is a relative URL.

Examples

{#variable|url}

urlEncode back to top

Encodes a string to be used in the query part of a URL

Optional options

output Whether or not to output the value.
Default value: yes
Accepted values: "yes" or "no"
save Whether or not to save the value back to the original variable.
If output is set to "no" but save is not set then "save" will automatically be set to "yes".
If save is set to "yes" and output is not specified then output will automatically be set to "no".
Default value: no
Accepted values: "yes" or "no"
saveAs The name of the variable to save to. The value should not contain brackets or "#".
If saveAs is set and output is not specified then output will automatically be set to "no".

You can use any combination of the options above. For example you can output the value, save it back to the original variable and save to another variable all at the same time.

Examples

Output the value.

{#variable|urlEncode}

Save the value back to the original value and don't output the value.

{#variable|urlEncode save="yes" output="no"}

Example scenario

An example scenario where you might use this is if you have an app (like Directory) that is trying to pass information to a form through the URL. The form content template would then take that information and populate a field.

In this example the URL form the form is going to be domain.com/contact?name=Name . The goal is to have a link from a Directory Profile page to the contact form. The contact form would have a hidden field that would hold the name of the person that the email is for. In order to get that value from the profile page to the form the value needs to be passed in the URL. To make sure that any special characters are handled correctly the profile name should be encoded to be safely passed in the URL. That's the whole purpose of this variable modifier. Below is an example of building the link to the contact form.

<a href="/contact?name={#profile.profileName|urlEncode}">Email Me</a>