Plumtree Content Server Templating Specification

Using Expressions in Content Server Elements

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

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 &gt; 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

Relational Operators

The following relational operators are supported in the expression attribute:

Operator

Definition

Equivalent JavaScript

==

is equal to

==

!=

is not equal to

!=

&gt;

is greater than

>

&ge;

is greater than or equal to

>=

&lt;

is less than

<

&le;

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 &gt; 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
(== and !=)

Relative Operators
(&gt; , &ge;, &lt; and &le;)

text vs. text

exact same characters in same
sequence

relative alphabetic value of first differing character

number vs. number

same numerical values

relative numerical values

enumeration vs.
enumeration

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

enumeration is converted to text and compared

n/a

item vs. item

same item

n/a

Arithmetic Operators

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.

Logical Operators

The following logical operators are defined:

Operator

Definition

JavaScript Equivalent

&and;

logical AND

&&

&or;

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" &and; "bar"

"bar"

"" &and; "bar"

""

"" &and; 0

""

"foo" &or; "bar"

"foo"

"" &or; "bar" &or; "bax"

"bar"

"" &or; 0

0

!""

True

!"foo"

False

Operator Precedence

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

!
( )
.
* / %
+ -
&gt; &ge; &lt; &le;
== !=
&and;
&or;

Lowest

Functions

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.

Object References

The table below summarizes the functions available to reference Content Server objects.

Function

Parameters

Return Value

itemByPath(path)
itemByPath(folder, path)

path: String
folder: Folder

The content item identified by the path parameter.

templateByPath(path)
templateByPath(folder, path)

path: String
folder: Folder

The template identified by the path parameter.

folderByPath(path)
folderByPath(folder, path)

path: String
folder: Folder

The folder identified by the path parameter.

objectByUid(uid)

uid: String (unique identifier obtained from
Content Server)

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.

String Operations

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 &lt; and &gt;, & to &amp;, " to &quot; and ' to &#39;. All other characters are left unchanged.

body ==
'<strong>"this" & 'that'</strong>'

encode(body) == '&lt;strong&gt;&quot;this&quot; &amp;&#39;that&#39;&lt;/strong&gt;'

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', ' ', '_') ==
'hello_world'

translate('Hello world', 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') ==
'HELLO WORLD'

translate('Hello_World', 'el_', '31') ==
'H311oWor1d'

(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

List Operations

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.
(Available in 5.0.2 and above.)

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).
(Available in 5.0.2 and above.)

Remove unpublished and hidden articles:

expr="filter(articles, 'filtered.published !=null &and; !filtered.hidden')"

Remove a folder from the list if an item in the folder 'Index' has not been published:

expr="filter(folder.subfolders,
      'itemByPath(filtered, &quot;index&quot;).published == null')"

Note: Because the string expression is un-encoded you must encode the &gt; and &lt; 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.
(Available in 6.0 and above.)

 

Property Names

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.

Constants

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&apos;t yell &quote;help!&quote;h'">

You can also reference specific content items using paths, explained next.

Next: Using Paths