Any Content Server tag that accepts a property can also use an expression. You can use any of the following within an expression's expr attribute:
Expressions are supported within expression attributes. Expressions can be combined and compared using relational, arithmetic and logical operators. Expressions are evaluated in order of precedence, also explained below (Operator Precedence).
IMPORTANT: Expressions are case-sensitive; property names are not. Expressions allow the use of spaces and punctuation marks; property names do not. Angle brackets (<>) and ampersands (&) are not permitted within object names. For details on encoding special characters, see String Operations below.
Examples:
expr="story.author == 'Joe'"
expr="17 != magic_number"
expr="story_list.length != item.reference_count"
expr="item.interest_level > item.skill + item.ref.skill"
expr="'hello world' == 'hello' + ' ' + 'world'"
expr="4" (non-zero integer is always treated as true)
If the expression represents a date, the Value element allows you to set the formatting. For details, see Content Server Elements: Value Element: Date Formatting
The following relational operators are supported in the expression attribute:
Operator |
Definition |
Equivalent JavaScript |
== |
is equal to |
== |
!= |
is not equal to |
!= |
> |
is greater than |
> |
≥ |
is greater than or equal to |
>= |
< |
is less than |
< |
≤ |
is less than or equal to |
<= |
Since the greater-than and less-than characters (angle brackets <>) have special meaning in XML and are reserved, the equivalent entities listed above must be used instead.
(NOT correct) <pcs:if expr="subscriber_count > 100">...
(correct) <pcs:if expr="subscriber_count > 100">...
The result of a comparison expression using these operators is a boolean True or False. When comparing two strings, case is significant. For example, the code below would return False.
expr="'blue'=='Blue'"
To determine whether a property has a value, compare it with null:
expr="story.coauthor == null"
When comparing values of various types, the following rules apply:
Value Types |
Equality
Operators |
Relative
Operators |
text vs. text |
exact same characters in same |
relative alphabetic value of first differing character |
number vs. number |
same numerical values |
relative numerical values |
enumeration
vs. |
based on same enumeration type, contain same selections |
n/a |
text vs. number |
text is converted to number and compared |
text is converted to number and compared |
text vs. |
enumeration is converted to text and compared |
n/a |
item vs. item |
same item |
n/a |
The following arithmetic operators are defined:
Operator |
Definition |
Notes |
+ |
numeric addition or text concatenation |
If both operands are numbers, calculates sum; otherwise treats operands as text |
- |
numeric subtraction |
If either operand is text, attempts to convert to a number before calculating |
* |
numeric multiplication |
same as subtraction |
/ |
numeric division |
same as subtraction |
% |
numeric remainder |
same as subtraction |
These operators are the same as their JavaScript equivalents. As in JavaScript, all numbers are treated as real numbers; even if two property values are both integers, the result of calculating with them will be a real number. For example, 5 / 4 will result in 1.25, unlike in some languages where the result would be 1.
The following logical operators are defined:
Operator |
Definition |
JavaScript Equivalent |
∧ |
logical AND |
&& |
∨ |
logical OR |
|| |
! |
logical NOT |
! |
As in JavaScript, the result of an expression of several similar logical operators will be the value of the first operand that satisfies the logical operator; the rest of the operands are not evaluated. The AND operator is satisfied by the first operand that evaluates equivalent to False. The OR operator is satisfied by the first operand that evaluates equivalent to True. The table below provides some examples:
Expression |
Result |
"foo" ∧ "bar" |
"bar" |
"" ∧ "bar" |
"" |
"" ∧ 0 |
"" |
"foo" ∨ "bar" |
"foo" |
"" ∨ "bar" ∨ "bax" |
"bar" |
"" ∨ 0 |
0 |
!"" |
True |
!"foo" |
False |
The order in which operators are evaluated is the same as in JavaScript. Operations with higher precedence take place before operations with lower precedence. Operators with the same precedence are evaluated left to right. The list of operators below is in order of precedence, from highest to lowest:
Highest
!
( )
.
* / %
+ -
> ≥ < ≤
== !=
∧
∨Lowest
Expression attributes can also contain function calls. Function calls are always the function name followed by a set of parentheses. If the function accepts parameters, expressions are placed between the parentheses and separated by commas to provide argument values. For example:
foobar(arg1, arg2, arg3)
The arguments may be any expressions. For example:
foobar(17, author.bio, help('green', (author.age + 21) != epoch))
The only functions available for use in expressions are those predefined by the system. This includes object references, string operations and list operations.
The table below summarizes the functions available to reference Content Server objects.
Function |
Parameters |
Return Value |
itemByPath(path) |
path: String |
The content item identified by the path parameter. |
templateByPath(path) |
path: String |
The template identified by the path parameter. |
folderByPath(path) |
path: String |
The folder identified by the path parameter. |
objectByUid(uid) |
uid: String (unique identifier obtained from |
The object identified by the UID. |
IMPORTANT: Relative paths are based on the template, not the content item being published. To get the name of a folder relative to the content item, use the following code:
<pcs:value expr="itemByPath(folder, 'my/sub/folder').name">
**Expression Failed**</pcs:value>
You can also reference specific content items using paths, explained next.
Functions can be used to access the properties of another content item. You must include a property reference, as shown in the example below.
(NOT correct) <pcs:value expr='itemByPath("/News/Headlines")'>**Expression Failed
**</pcs:value>(correct) <pcs:value expr='itemByPath("/News/Headlines").name'>**Expression Failed **</pcs:value>
The first example would evaluate to **Expression Failed** because the property being accessed cannot be rendered.
If a Presentation Template is in XML or Java, text entered through the Content Item Editor can break the format of the published text file. This could happen through angle brackets surfacing in an XML file, or quotes not being properly escaped in a Java program. The following string operations help you control the output of your template (5.0.2 and above). Simple string operations are also available, detailed below.
Function |
Return Value |
Example |
encode(String content) |
HTML encodes the passed string, converting < and > characters to < and >, & to &, " to " and ' to '. All other characters are left unchanged. |
body == encode(body) == '<strong>"this" &'that'</strong>' |
replace(String str, String match, String replace) |
Returns the string specified by the str parameter with all occurrences of the string passed in the match parameter with the string passed in the replace parameter. The replace and match parameters must be HTML encoded to match characters such as < or >. |
replace('hello world', 'hello', 'goodbye') == 'goodbye world' |
translate(String str, String fromChars, String toChars) |
Substitutes the characters found in the fromChars parameter with the character at the same index in the toChars parameter. If fromChars is longer than toChars the extra characters are removed from the string. If toChars is longer than fromChars the extra characters are ignored. |
translate('hello world', ' ', '_') == translate('Hello world', 'abcdefghijklmnopqrstuvwxyz',
'ABCDEFGHIJKLMNOPQRSTUVWXYZ') == translate('Hello_World',
'el_', '31') == (the underscore is removed because there is no character in the third position of the toChars parameter) |
Simple string operations are also available in version 6.0 and above, detailed in the table below.
Function |
Return Value |
startswith(string1, string2) |
True if string1 starts with string2 |
contains(string1, string2) |
True if string1 contains string2 |
substring(string1, begin<,end?>) |
A substring of string1 from the position defined by begin, and optionally ending at the position defined by end |
substringBefore(string1, string2) |
A substring of string1 upto the first occurrence of string2 |
substringAfter(string1, string2) |
A substring of string1 after the first occurrence of string2 (if there is no match an empty string is returned) |
toupper(string1,language,country) |
string1 in all uppercase characters, with an optional language and country |
tolower(string1,language,country) |
string1 in all lowercase characters, with an optional language and country |
The table below summarizes available list operation functions.
Function |
Return Value |
Example |
List sort(List list, String propertyExpr, Boolean ascending) |
Sorts the passed list according to the parameters
passed. A list can contain three types of objects: a String from a Selection
List, a Content Item, and a Folder. If no parameters are passed, Strings
are sorted in their natural order, and Folders and Content Items are sorted
by name. Both propertyExpr and ascending
are optional parameters. If a propertyExpr refers
to two values that are not sort compatible (i.e., different object types),
the sort operation will fail. |
Sort content items or folders by created date: sort(articles, 'created') Sort content items by the name of a file in a File property named "file": sort(articles, 'file.name') Sort by most recently published date, then by name: sort(sort(list, 'published', false)) |
List filter(List list, String testExpr) |
Returns a copy of the passed list with all
items that fail the textExpr removed. Each item
in the list it is assigned to a variable named "filtered" and
the expression is evaluated. The textExpr is
evaluated in the same manner as the expr in
the <pcs:if> tag. The contents of textExpr
must be xml encoded to contain special characters (quotes, angle bracket
characters , or ampersands). |
Remove unpublished and hidden articles: expr="filter(articles, 'filtered.published !=null ∧ !filtered.hidden')" Remove a folder from the list if an item in the folder 'Index' has not been published: expr="filter(folder.subfolders, Note: Because the string expression is un-encoded you must encode the > and < in the string to have it properly evaluated. |
join(list,list,list) |
Takes two or more lists and joins them together.
A content item or publishable Presentation Template are treated as single
item lists, and a Folder is treated as a list of the content items in
the folder. |
|
Expressions can be used to reference Content Server properties. To reference a property in an expression, use the same rules described in the previous page, Using Properties.
A constant expression can be an integer constant or a string constant.
An integer constant is any string of digits. The string can be preceded by a minus sign and can contain at most one decimal point. If there is a decimal point, there must be at least one digit on either side of the decimal point. Any of the examples below is legal:
<pcs:tag expr="43">
<pcs:tag expr="-43">
<pcs:tag expr="4.3">
A string constant is any string of characters surrounded by single or double quotes. You must use XML escaping rules if quotes in the expression could be confused with the quotes around the attribute value. Any of the examples below is legal:
<pcs:tag expr="'hello'">
<pcs:tag expr="'goodbye'"
<pcs:tag expr="'don't yell "e;help!"e;h'">
You can also reference specific content items using paths, explained next.
Next: Using Paths