Variables
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.
Variable Modifiers
| Modifier | Description |
|---|---|
| append | 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. Options: value: The value to add to the end of the variable. 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: {#variable|append value=" world"} - Adds " world" to the variable. {#variable|append key="key" value="world"} {#variable|append value="world" space="yes"} |
| array | Sets an existing variable to be an array or creates a new variable as an array. Options: key: The array key to set. The value can be another variable. Examples: {#variable|array} Setting a key when creating the array {#variable|array key="keyName"} {#variable|array key=""} You can setup a multidimensional array by the following: {#variable.key|array} or {#variable.key.key2|array} |
| capitalize strtoupper upper |
Makes all letters in the variable upper case. Options: output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'yes'. You can you 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|capitalize} Save the value back to the original value and don't output the value. {#variable|capitalize save="yes" output="no"} |
| ceiling | 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. Example: {#variable|floor} |
| date | Formats a timestamp as a date string. See the Date Formats page for available date and time formats. Options: format: The date format output - Whether or not to output the result. 'yes' or 'no'. Defaults to 'no'. Example: {#variable|date format="Y"} |
| debug | Debug a variable to see what value it has. Example: {#variable|debug} |
| decrement subtract |
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: Subtracts 3 from the variable. {#variable|decrement value="3"} Use another variable to decrement. {#number|set value="1"} Save the decremented value to a new variable called "new" instead of the original variable. {#variable|decrement value="2" saveAs="new" save="no"} |
| default | 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. Options: value: The default value Example: {#variable|default value="My Default Value"} |
| divide | Divides the variable value by a number and saves the result. Does not output the result. The variable should be a number, although strings could also be used. Options: value: The number to divide by. Example: {#variable|divide value="3"} - Divides the variable by 3. |
| escapeQuotes | Escapes single and double quotes with a backslash "\". By default it will escape both double and single quotes. Options: double: Whether or not to escape double quotes. "yes" or "no". Defaults to "yes" single: Whether or not to escape single quotes. "yes" or "no". Defaults to "yes" save: Whether or not to save the escaped string to the variable. If the value is saved then it is not outputted. 'yes' or 'no'. Defaults to 'no'. Examples: {#variable|escapeQuotes} - Escape both single and double quotes {#variable|escapeQuotes double="no"} - Only escape single quotes {#variable|escapeQuotes single="no"} - Only escape double quotes {#variable|escapeQuotes save="yes"} - Escape both single and double quotes and save to the variable |
| explode |
Splits a string on the specified delimiter. The result is saved as an array to the specified variable.
Options: Examples: In the above 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. Using the above example we define the {#new} variable as an empty array first. {#new|array} |
| first | 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.
Options: Examples: |
| floor | 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. Example: {#variable|floor} |
| get |
Gets an array value for the specified array key. If saveAs is set then the value is not outputted. |
| htmlentities | Convert all applicable characters to HTML entities Example: {#variable|htmlentities} |
| implode |
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. 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. Optional Options: Example: In the above 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. |
| increment add |
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: Adds 3 to the variable. {#variable|increment value="3"} Use another variable to increment. {#number|set value="1"} Save the incremented value to a new variable called "new" instead of the original variable. {#variable|increment value="2" saveAs="new" save="no"} |
| injectHtml |
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: You can you 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"} Examples: 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> {#var|injectHtml value=' <a href="/more">read more</a>'} The resulting HTML will be: <p>Hello <a href="/more">read more</a></p> Note that if value contains double quotes you must use single quotes for the value option. |
| json | Encodes the variable as a complete JSON string. The variable can be an array or a string. The JSON string needs to have a root key. If the key option is not set then "data" is used. Options: key: The root key to use in the JSON string. Defaults to "data". save: Whether or not to save the JSON string to the variable. If the value is saved then it is not outputted. 'yes' or 'no'. Defaults to 'no'. Example: Assume that the variable is an array: array( {#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"}} |
| jsonValue | 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 | 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.
Options: Examples: |
| length count |
Gets the length of a string or the number if items in an array. By default this does not output. output - Whether or not to output the result. 'yes' or 'no'. Defaults to 'no'. |
| lower strtolower |
Makes all letters in the variable lower case. Options: output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'yes'. You can you 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 | 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. Options: substring - A sub string to remove from the beginning of the string. save - Whether or not to save the trimmed value to the variable. 'yes' or 'no'. Defaults to 'no'. Example: {#variable|ltrim} |
| modulus | Finds the remainder of division by dividing the variable value by a number and saves the result. Does not output the result. The variable should be a number, although strings could also be used. Options: value: The number to divide the variable by. Example: {#variable|modulus value="3"} - Divides the variable by 3 and saves the remainder. |
| multiply | Multiplies the variable value by a number and saves the result. Does not output the result. The variable should be a number, although strings could also be used. Options: value: The number to multiple the variable by. Example: {#variable|multiply value="3"} - Multiplies the variable by 3. |
| nl2br | Converts new line characters to <br />. Example: {#variable|nl2br} |
| number | Format a string as a number. Options: numberDecimalPlaces - The number of decimal places to use. Defaults to 0. decimalSeparator - The decimal separator. Defaults to a period "." thousandSeparator - The thousands separtor. Defaults to a comma "," Example: {#variable|number} |
| obfuscate |
Obfuscates part of a string with another character. This could be used to display sensitive information like credit card numbers. Options: character: The character used as the replacement character. Defaults to '*'. You can you 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: 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 | 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. Options: value: The value to add to the beginning of the variable. 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: {#variable|prepend value="hello "} - Prepend "hello " to the variable. {#variable|prepend key="key" value="hello"} - Add "hello" to the beginning of {#variable|prepend value="hello" space="yes"} - Prepend " hello" to the variable (notice the space) |
| replace | Replaces all occurrences of the search string with the replacement string in the variable. Options: search: The value to search for in the variable value. This value will be replaced. replace: The value to replace the search value with. save - Whether or not to save the trimmed value to the variable. 'yes' or 'no'. Defaults to 'no'. Example: Assume that {#variable} holds a value of "100 little monkeys" {#variable|replace search="monkeys" replace="elephants"} This will output "100 little elephants" |
| reverse |
If the variable is an array then the array is reversed. If it's a string then the order of the string is reversed. Options: Examples: |
| round | Round 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. Example: {#variable|round} |
| rtrim | 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. Options: substring - A sub string to remove from the end of the string. save - Whether or not to save the trimmed value to the variable. 'yes' or 'no'. Defaults to 'no'. Example: {#variable|rtrim} |
| set assign |
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. Options: value - The value to set to the variable. key - If the variable is an array this will be used as an array key to assign the value to. Examples: {#variable|set value="variable value"} You can set a variable to a variable by: "} If the variable does not exist it will be created either as a string or as an array if the "key" parameter is set. You can setup a multidimensional array by the following: {#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'))). |
| setapi |
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. Options:
This will return 5 posts from the blog as an array This will return 5 posts from the blog after it's been processed by the blog content template with an id of 1. |
| shuffle randomize |
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. output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'no'. You can you 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"} |
| striptags | Removes any HTML tags in the variable. The variable must be a string. Example: {#variable|striptags} |
| swap | Swaps the value for a string. If the string equals swap1 then it is changed to swap2 and vice versa. Options: swap1: One value for the variable. swap2: The other value for the variable Example: {#variable|swap swap1="value 1" swap2="value 2"} |
| time | Formats a timestamp as a time string. See the Date Formats page for available date and time formats. Options: format: The time format output - Whether or not to output the result. 'yes' or 'no'. Defaults to 'no'. Example: {#variable|time format="H:i A"} |
| trim | 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. Options: substring - A sub string to remove from the beginning of the string. save - Whether or not to save the trimmed value to the variable. 'yes' or 'no'. Defaults to 'no' Example: {#variable|trim} |
| truncate shorten | Shortens a string variable. Options: length: The new length of the string. preserveWords: Whether or not to preserve whole words - "true" or "false". Defaults to 'true'. useHtmlEntities: Whether or not to preserve and not count HTML entities - "true" or "false". Defaults to 'true'. append: A string to append to the end of the truncated string. Defaults to '…' (...) save: Whether or not to save the truncated string to the variable instead of outputting the truncated string. 'true' or 'false'. Defaults to 'false'. stripTags: Whether or not to strip HTML tags. 'true' or 'false'. Defaults to 'false'. Examples: {#variable|truncate length="3"} - shorten the variable to 3 characters. {#variable|shorten length="3"} - shorten the variable to 3 characters. |
| ucfirst |
Makes the first letter upper case. output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'yes'. You can you 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 |
Makes the first letter of each word upper case. Options: output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'yes'. You can you 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"} |
| unset | Unsets a value from a variable if the variable is an array. Options: key: The array key whose value should be removed or a comma separated string of array keys whose values should be removed. Examples: {#variable|unset key="key1"} {#variable|unset key="key1, key2, key3"} |
| url |
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. Example: {#variable|url} |
| urlEncode |
Encodes a string to be used in the query part of a URL Options: output: Whether or not to output the result. 'yes' or 'no'. Defaults to 'yes'. You can you 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"} 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> |