Variable Modifiers

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

Optional options

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?"}

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

Optional options

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}

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

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"}

Makes all letters in the variable upper case.

Optional options

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"}

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}

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

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;"'}

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

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"}

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

Examples

{#variable|countryData}

You can then access the information like an array.

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

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

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"}

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

Required options

Optional options

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 a variable to see what value it has.

Examples

{#variable|debug}

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

Optional options

Examples

Subtract 3 from a variable

{#variable|decrement value="3"}

Use another variable to decrement

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

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

Examples

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

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

Optional options

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"}

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

Examples

{#variable|escapeCurlyBrackets}

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

Optional options

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"}

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

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"}

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

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"}

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}

Gets an array value for the specified array key.

Required options

Optional options

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"}

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

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"}

Convert all applicable characters to HTML entities.

Optional options

Examples

{#variable|htmlentities}

Escapes any HTML special characters in a variable value.

Optional options

Examples

{#variable|htmlSpecialCharacters}

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

Optional options

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"}

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

Optional options

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"}

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

Optional options

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>

Converts the variable value to an integer. 

Optional options

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"}

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

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"}}

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

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}

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}}

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

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"}

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

Optional options

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"}

Makes all letters in the variable lower case.

Optional options

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"}

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

Examples

{#variable|ltrim}

Converts the string to a MD5 hash.

Optional options

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}">

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

Required options

Optional options

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>

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

Optional options

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"}

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

Optional options

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"}

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

Optional options

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"}

Converts new line characters to <br />.

Optional options

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"}

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

Optional options

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"}

Format a string as a number.

Optional options

Examples

{#variable|number}

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

Optional options

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"}

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

Optional options

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?"}

Removes line breaks from a string.

Optional options

Examples

{#variable|removeNewLines}

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

Required options

Optional options

Examples

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

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

This will output "100 little elephants"

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

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

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"}

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

Examples

{#variable|rtrim}

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

Optional options

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?"}

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

Optional options

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}"}

Converts the string to a SHA1 hash.

Optional options

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"}

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

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"}

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

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"}

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

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"}

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

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"}

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

Examples

{#variable|stateData}

You can then access the information like an array.

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

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

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"}

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

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"}

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

Required options

Examples

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

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

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"}

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

Required options

Optional options

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"}

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

Optional options

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"}

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

Examples

Trim the variable and output it.

{#variable|trim}

Shortens a string variable.

Required options

Optional options

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"}

Makes the first letter upper case.

Optional options

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"}

Makes the first letter of each word upper case.

Optional options

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"}

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

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"}

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

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"}

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}

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

Optional options

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>