Output Filter/Modifiers
Last updated Jan 21st, 2021 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$311 per month—let's make that $500!
Learn moreWhat are Filters?¶
Filters in Revolution allow you to manipulate the way data is presented or parsed in a tag. They allow you to modify values from inside your templates.
Input Filter¶
Output Filter¶
In Revolution, the Output Filter applies one or more of series of output modifiers, which behave similarly to PHx calls in MODX Evolution - except they're built into the core. The syntax looks like this:
[[element:modifier=`value`]]
They can also be chained (executed left to right):
[[element:modifier:anothermodifier=`value`:andanothermodifier:yetanother=`value2`]]
You can also use these to modify Snippet output; note that the modifier comes after the Snippet name and before the question mark, e.g.
[[mySnippet:modifier=`value`? &mySnippetParam=`something`]]
If you have longer code in a :then=`...`:else=`...`
statement and you want to make it more readable by putting it on multiple lines, it has to be done like this:
[[+placeholder:is=`0`:then=`
// code
`:else=`
// code
`]]
Output Modifiers¶
The following table lists some of the existing modifiers and shows examples of their use. Although the examples below are placeholder tags, the output modifiers can be used with any MODX tag. Make sure that the placeholder used are actually receiving data.
Conditional output modifiers¶
Modifier | Description | Example |
---|---|---|
if, input | if - sets an additional condition. input - adds the data to be processed to the tag |
[[*id:is=`1`:and:if=`[[*id]]`:ne=`2`:then=`Yes`:else=`No`]] |
or | Can be used to string output modifiers together with an "OR" relationship. | [[+numbooks:is=`5`:or:is=`6`:then=`There are 5 or 6 books!`:else=`Not sure how many books`]] |
and | Can be used to string output modifiers together with an "AND" relationship. | [[*numbooks:is=`1`:and:if=`[[*id]]`:ne=`2`:then=`Yes`:else=`No`]] |
isequalto, isequal, equalto, equals, is, eq | Compares to a passed value, and moves on if it's the same. Used with "then" and "else" | [[+numbooks:isequalto=`5`:then=`There are 5 books!`:else=`Not sure how many books`]] |
notequalto, notequals, isnt, isnot, neq, ne | Compares to a passed value, and moves on if it is not the same. Used with "then" and "else" | [[+numbooks:notequalto=`5`:then=`Not sure how many books`:else=`There are 5 books!`]] |
greaterthanorequalto, equalorgreaterthen, ge, eg, isgte, gte | Compares to a passed value, and moves on if it is greater than or equal to the value. Used with "then" and "else". | [[+numbooks:gte=`5`:then=`There are 5 books or more than 5 books`:else=`There are less than 5 books`]] |
isgreaterthan, greaterthan, isgt, gt | Compares to a passed value, and moves on if it is greater than the value. Used with "then" and "else". | [[+numbooks:gt=`5`:then=`There are more than 5 books`:else=`There are less than 5 books`]] |
equaltoorlessthan, lessthanorequalto, el, le, islte, lte | Compares to a passed value, and moves on if it is less then or equal to the value. Used with "then" and "else". | [[+numbooks:lte=`5`:then=`There are 5 or less than 5 books`:else=`There are more than 5 books`]] |
islowerthan, islessthan, lowerthan, lessthan, islt, lt | Compares to a passed value, and moves on if it is less than the value. Used with "then" and "else". | [[+numbooks:lt=`5`:then=`There are less than 5 books`:else=`There are more than 5 books`]] |
contains | Checks to see if value contains a passed string. | [[+author:contains=`Samuel Clemens`:then=`Mark Twain`]] |
containsnot | Check to see if the value does not contain the passed string. | [[+author:containsnot=`Samuel Clemens`:then=`Somebody Else`]] |
in, IN, inarray, inArray | Check to see if the value is in an array (comma seperated) | [[+id:in=`5,15,22`:then=`Yes in array`]]` |
hide | Will check earlier conditions, and hide the element if the conditions were met. | [[+numbooks:lt=`1`:hide]] |
show | Will check earlier conditions, and show the element if the conditions were met. | [[+numbooks:gt=`0`:show]] |
then | Conditional usage. | [[+numbooks:gt=`0`:then=`Now available!`]] |
else | Conditional usage, together with then. | [[+numbooks:gt=`0`:then=`Now available!`:else=`Sorry, currently sold out.`]] |
select | Output a replacement, if the value is found in the list of values before the equal sign. Otherwise the result is empty. | [[+numbooks:select=`0=Value 0&1=Value 1&2=Value 2`]] |
memberof, ismember, mo | Checks if the user is a member of the specified group(s). | [[+modx.user.id:memberof=`Administrator`]] |
String output modifiers¶
Modifier | Description | Example |
---|---|---|
cat | Appends the option's value (if not empty) to the input value | [[+numbooks:cat=`books`]] |
after, append | Appends the options value to the input value (if both not empty) Added in 2.6.0. | [[+totalnumber:after=`total`]] |
before, prepend | Prepends the options value to the input value (if both not empty) Added in 2.6.0. | [[+booknum:before=`book #`]] |
lcase, lowercase, strtolower | Transforms strings to lowercase. Similar to PHP's strtolower | [[+title:lcase]] |
ucase, uppercase, strtoupper | Transforms strings to uppercase. Similar to PHP's strtoupper | [[+headline:ucase]] |
ucwords | Transforms the first letter of a word to uppercase. Similar to PHP's ucwords | [[+title:ucwords]] |
ucfirst | Transforms the first letter of the string to uppercase. Similar to PHP's ucfirst | [[+name:ucfirst]] |
htmlent, htmlentities | Replaces any character that has an HTML entity with that entity. Similar to PHP's htmlentities. Uses the current value the system setting modx_charset with flag ENT_QUOTES |
[[+email:htmlent]] |
esc,escape | Safely escapes character values using regex and str_replace. | Also escapes [, ] and [[+email:escape]] |
strip | Replaces all linebreaks, tabs and multiple spaces with just one space | [[+textdocument:strip]] |
stripString | Strips string of specified value | [[+name:stripString=`Mr.`]] |
replace | Replaces one value with another | [[+pagetitle:replace=`Mr.==Mrs.`]] |
striptags, stripTags,notags,strip_tags | Removes HTML tags from the input. Optionally accepts a value to indicate which tags to allow. Similar to PHP's strip_tags | [[+code:strip_tags=` `]] |
stripmodxtags | Removes MODX tags from the input. (Added in v2.7) | [[+code:stripmodxtags]] |
len,length, strlen | Counts the length of the passed string. Similar to PHP's strlen | [[+longstring:strlen]] |
reverse, strrev | Reverses the input, character by character. Similar to PHP's strrev | [[+mirrortext:reverse]] |
wordwrap | Inserts a newline character after the set amount of characters. Similar to PHP's wordwrap. Takes optional value to set wordwrap position. | [[+bodytext:wordwrap=`80`]] |
wordwrapcut | Inserts a newline character after the set amount of characters, irrespective of word boundaries. Similar to PHP's wordwrap, with word cutting enabled. Takes optional value to set wordwrap position. | [[+bodytext:wordwrapcut=`80`]] |
limit | Limits a string to a certain number of characters. Defaults to 100. | [[+description:limit=`50`]] |
ellipsis | Adds an ellipsis to and truncates a string if it's longer than a certain number of characters. Only uses spaces as breakpoints. Defaults to 100. | [[+description:ellipsis=`50`]] |
tag | Displays the raw element without the :tag. Useful for documentation. | [[+showThis:tag]] |
tvLabel | Display's the Label from a tv usefull when using select or checkboxes etc where you use `Label==1 | |
math | Returns the result of an advanced calculation (expensive on processor. not recommended) Removed in Revolution 2.2.6. | [[+blackjack:add=`21`]] |
add,increment,incr | Returns input incremented by option (default: +1) | [[+downloads:incr]] |
subtract,decrement,decr | Returns input decremented by option (default: -1) | [[+countdown:decr]] [[+moneys:subtract=`100`]] |
multiply,mpy | Returns input multiplied by option (default: *2) | [[+trifecta:mpy=`3`]] |
divide,div | Returns input divided by option (default: /2) Does not accept 0. | [[+rating:div=`4`]] |
modulus,mod | Returns the option modulus on input (default: %2, returns 0 or 1) | [[+number:mod]] or [[+number:mod=`3`]] |
ifempty,default,empty, isempty | Returns the input value if empty | [[+name:default=`anonymous`]] |
notempty, !empty, ifnotempty, isnotempty | Returns the input value if not empty | [[+name:notempty=`Hello [[+name]]!`]] |
nl2br | Converts a new line character (\n) to an html element. Use this if you're taking in input, you think that there should be new lines in it, and there aren't. Similar to PHP's nl2br. | [[+textfile:nl2br]] |
date | Formats a unix timestamp into a different format. Similar to PHP's strftime. Value is format. See Date Formats. | [[+birthyear:date=`%Y`]] |
strtotime | Converts a date string into a unix timestamp. Useful to combine this with the date output filter. Similar to PHP's strtotime. Takes in a date. See Date Formats. | [[+thetime:strtotime]] |
fuzzydate | Returns a pretty date format with yesterday and today being filtered. Takes in a date. | [[+createdon:fuzzydate]] |
ago | Returns a pretty date format in seconds, minutes, weeks or months ago. Takes in a date (strtotime). | [[+createdon:date=`%d-%m-%Y`:ago]] |
md5 | Creates an MD5 hash of the input string. Similar to PHP's md5. | [[+password:md5]] |
cdata | Wraps the text with CDATA tags | [[+content:cdata]] |
userinfo | Returns the requested user data. The element must be a modUser ID. The value field is the column to grab, e.g. fullname, email. See Examples below. | [[+modx.user.id:userinfo=`username`]] |
isloggedin | Returns true if user is authenticated in this context. | [[+modx.user.id:isloggedin]] |
isnotloggedin | Returns true if user is not authenticated in this context. | [[+modx.user.id:isnotloggedin]] |
toPlaceholder | Puts the input value into the passed placeholder. Does not prevent the output of the TV value, so add [[*someTV:toPlaceholder=`placeholder`:notempty= ``]] if you don't want to output the value of the TV itself. |
[[*someTV:toPlaceholder=`placeholder`]] |
cssToHead | Put a <link> element into , where the input value is placed inside the href attribute. Uses modX.regClientCSS. |
[[+cssTV:cssToHead]] |
htmlToHead | Insert a block of HTML code in the header of the page, before </head> . Uses modX.regClientStartupHTMLBlock |
[[+htmlTV:htmlToHead]] |
htmlToBottom | Insert HTML code at the end of the page, before </body> . Uses modX.regClientHTMLBlock. |
[[+htmlTV:htmlToBottom]] |
jsToHead | Insert JS code (or a link) in the header of the page, before </head> . Uses modX.regClientStartupScript. |
[[+jsTV:jsToHead]] |
jsToBottom | Insert JS code (or a link) at the end of the page, before </body> . Uses modX.regClientScript. |
[[+jsTV:jsToBottom]] |
urlencode | Converts the input into a URL-friendly string similar to how an HTML form would do so. Similar to PHP's urlencode | [[+mystring:urlencode]] |
urldecode | Converts the input from an URL-friendly string Similar to PHP's urldecode | [[+myparam:urldecode]] |
filterPathSegment | Added in 2.7. Converts the input into a URL-friendly string with the same mechanism that turns a pagetitle into an alias, including transliteration if enabled. Useful for custom urls. | [[+pagetitle:filterPathSegment]] |
Caching¶
In general, any content in a placeholder that you think might change dynamically should be uncached. For example:
[[+placeholder:default=`A default value!`]]
This means that this could sometimes be empty, and sometimes not. Why would you ever want that cached? That would eliminate the point of the output modifier.
Sometimes, output modifiers can be used on a cached placeholder - but only if you're calling the Snippet that sets them cached as well. Otherwise, you're performing an illogical maneuver - trying to cache statically something that was never meant to be static.
In general, the rule is: If you set a placeholder in an uncached Snippet, the placeholder needs to be uncached as well if you expect the content of the placeholder to differ.
Using an Output Modifier with Tag Properties¶
If you have properties on the tag, you'll want to specify those after the modifier:
[[!getResources:default=`Sorry - nothing matched your search.`?
&tplFirst=`blogTpl`
&parents=`2,3,4,8`
&tvFilters=`blog_tags==%[[!tag:htmlent]]%`
&includeTVs=`1`
]]
Creating a Custom Output Modifier¶
Also, Snippets can be used as custom modifiers. Simply put the Snippet name instead of the modifier. Example with a snippet named 'makeExciting' that appends a variable amount of exclamation marks:
[[*pagetitle:makeExciting=`4`]]
This document variable call with an output modifier will pass these properties to the snippet:
Param | Value | Example Result |
---|---|---|
input | The element's value. | The value of [[*pagetitle]] |
options | Any value passed to the modifier. | '4' |
token | The type of the parent element. | * (the token on pagetitle ) |
name | The name of the parent element. | pagetitle |
tag | The complete parent tag. | [[*pagetitle:makeExciting=`4`]] |
Here is a sample implementation for our snippet makeExciting:
$defaultExcitementLevel = 1;
$result = $input;
if (isset($options)) {
$numberOfExclamations = $options;
} else {
$numberOfExclamations = $defaultExcitementLevel;
}
for ( $i = $numberOfExclamations; $i > 0; $i-- ) {
$result = $result . '!';
}
return $result;
The return value of the call will be whatever the snippet returns. For our example, the result will be the value of the pagetitle document variable appended with four exclamation marks.
The original input value will be returned if the snippet returns an empty string.
Chaining (Multiple Output Filters)¶
A good example of chaining would be to format a date string to another format, like so:
[[+mydate:strtotime:date=`%Y-%m-%d`]]
Directly accessing the modx_user_attributes
table in the database using output modifiers instead of a Snippet can be accomplished simply by utilizing the userinfo modifier. Select the appropriate column from the table and specify it as the property of the output modifier, like so:
User Internal Key: [[!+modx.user.id:userinfo=`internalKey`]]<br />
User name: [[!+modx.user.id:userinfo=`username`]]<br />
Full Name: [[!+modx.user.id:userinfo=`fullname`]]<br />
E-mail: [[!+modx.user.id:userinfo=`email`]]<br />
Phone: [[!+modx.user.id:userinfo=`phone`]]<br />
Mobile Phone: [[!+modx.user.id:userinfo=`mobilephone`]]<br />
Fax: [[!+modx.user.id:userinfo=`fax`]]<br />
Date of birth: [[!+modx.user.id:userinfo=`dob`:date=`%Y-%m-%d`]]<br />
Gender: [[!+modx.user.id:userinfo=`gender`]]<br />
Country: [[+modx.user.id:userinfo=`country`]]<br />
State: [[+modx.user.id:userinfo=`state`]]<br />
Zip Code: [[+modx.user.id:userinfo=`zip`]]<br />
Photo: [[+modx.user.id:userinfo=`photo`]]<br />
Comment: [[+modx.user.id:userinfo=`comment`]]<br />
Password: [[+modx.user.id:userinfo=`password`]]<br />
Cache Password: [[+modx.user.id:userinfo=`cachepwd`]]<br />
Last Login: [[+modx.user.id:userinfo=`lastlogin`:date=`%Y-%m-%d`]]<br />
The Login:[[+modx.user.id:userinfo=`thislogin`:date=`%Y-%m-%d`]]<br />
Number of Logins: [[+modx.user.id:userinfo=`logincount`]]
[[!+modx.user.id]]
defaults to the currently logged in user ID. You can of course replace that with [[*createdby]]
or other resource field or placeholders that return a numeric ID representing a user.
Note that the user ID and username is already available by default in MODX, so you dont need to use the "userinfo" modifier:
[[!+modx.user.id]] - Prints the ID
[[!+modx.user.username]] - Prints the username
You will most likely want to call these uncached (see note about caching above) to prevent unexpected results.
See Also¶
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$311 per month—let's make that $500!
Learn more