Content Server elements are tags that allow you to insert programming logic within a Content Server template to display properties and content from the associated content item. The table below summarizes available Content Server elements. A detailed explanation of each element is provided in the sections that follow.
|
Element |
Tag |
Definition |
Accepted Values |
|
<pcs:value> |
Displays Content Server properties (Text, Long Text, Integer, Real, Boolean, Date, and Selection List). |
A Content Server property or an expression. | |
|
<pcs:if> |
Displays content in a published content item only if the specified condition is True. |
An expression. | |
|
<pcs:foreach> |
Iterates through a collection of objects. The code between the tags is evaluated with each iteration. |
An expression or path. | |
|
<pcs:include> |
Inserts the referenced Presentation Template in the content item. |
A path. | |
|
<pcs:insert> |
Displays a content item as a component of the current item. Can only be used with content items that have an associated Presentation Template. |
An expression or path. | |
|
<pcs:html> |
Allows you to enter standard HTML and XML code in the Code field of the Presentation Template Editor. |
Valid HTML or XML. |
Before creating any Content Server elements, make sure to read the previous page, Key Terms and Basic Syntax.
The <pcs:value> tag can be used to display an expression or any of the following Content Server properties:
Text
Long Text
Integer
Real
Boolean
Date (see Date Formatting below)
Selection List
Content Server translates the property value or expression to a text string. Angle brackets (<>) and ampersands (&) are not permitted. For details on syntax, see Using Properties and Using Expressions.
Syntax:
<pcs:value property='property'>default text</pcs:value>
or
<pcs:value expr="expression">default text</pcs:value>
Examples:
<pcs:value property='article.author'>Anonymous</pcs:value>
<pcs:value property='screenwriter.name'>
<pcs:value property='writer.name'></pcs:value>
</pcs:value><pcs:value expr="headline"></pcs:value>
<img src="<pcs:value expr="photo.location"></pcs:value>">
<a href="<pcs:value property='homepage.location'></pcs:value>">
If the value referenced by the tag is not found, the contents of the element are evaluated. The text between the tags is displayed, and any <pcs> tags inside the element are transformed. You can use the value element to display the result of a calculation based on the values of referenced properties. For example:
<pcs:value expr=""bonus - agent.commissions * agent.tax_rate"></pcs:value>
The Value element provides an optional date format attribute. The format attribute allows you to set the pattern that defines how the date should appear in the published document.
Syntax:
<pcs:value expr="expression" (format="format pattern")>default text</pcs:value>
Example:
<pcs:value expr='creation_time' format="MMMM dd"></pcs:value>">
The format date string conforms to the Java language's SimpleDateFormat definition (for details, see Date String Formatting). If you do not set the format attribute, the date is formatted according to the system configuration property com.plumtree.content.template.defaultDatePublishFormat. The default format is MM/dd/yyyy hh:mm aa.
The <pcs:if> tag is used to display content in a published content item only if the specified condition is True. The tag accepts any valid expression, including a content item property (expression) or a string comparison. See Using Expressions for details.
When the content item is published, the expression in the tag is evaluated. if the expression evaluates to True, the contents of the element are evaluated; otherwise the element is ignored.
Syntax:
<pcs:if expr="expression">conditional content</pcs:if>
Examples:
<pcs:if expr="item.show_me">
<pcs:value expr="item.name"></pcs:value>
<pcs:value expr="item.description"></pcs:value>
</pcs:if><pcs:if expr='Author=="Poe"'>
Books by Edgar Allen Poe:
<pcs:value expr="booklist"></pcs:value>
</pcs:if>
To determine whether a property has a value, compare it with null:
<pcs:if expr="story.coauthor == null">...
NOTE: If a text property exists and you compare it to null it will return False. To check for empty string values compare with an empty string:
<pcs:value expr="story.coauthor == ''>...
To test that a property is defined in the Data Entry Template, compare it with undefined:
<pcs:if expr="story.coauthor == undefined">...</pcs:if>
If a property is not defined and you compare it with null, the result will be False.
The table below summarizes how different types of values are considered True or False:
|
Value Type |
True if: |
False if: |
|
text |
has length > 0 |
has length == 0 |
|
number |
is non-zero |
is zero |
|
boolean |
is True |
is False |
|
null |
never |
always |
|
item |
is defined |
is not defined |
|
collection |
is defined |
is not defined |
|
enumeration |
contains at least one selection |
is empty |
The <pcs:foreach> tag allows you to iterate through a collection of objects. The collection can be referenced using either an expression or path. The code between the tags will be evaluated with each value in the iteration. For details on syntax, see Using Expressions and Using Paths.
Iterator elements can be nested. An Iterator element evaluates itself before (repeatedly) evaluating its content.
Syntax:
<pcs:foreach var="variable" expr="expression">
content
</pcs:foreach>
Examples:
<pcs:foreach var="item" expr="folderByPath('/authors/latest')"></pcs:foreach>
<pcs:foreach var="item" expr="article_list">
<pcs:value expr="item.headline"></pcs:value>
<pcs:value expr="item.story"></pcs:value>
</pcs:foreach>
On each iteration, the variable named in the var attribute is set to each value in turn. The var attribute only supports alphabetic characters (a-z, A-Z).
The variable defined by the var attribute can be used within the content of the foreach tag by other PCS expressions, as shown in the second example above. If the list expression fails to evaluate, the foreach tag expansion fails, the variable is undefined, and the element is dropped.
The list of values through which the tag iterates (the type of object stored in the variable) depends on the result of the expression. The table below summarizes how different types of results are treated.
|
Result |
Values Iterated |
Variable Object Type |
|
list |
each value in the list |
content item |
|
enumeration (i.e., Selection List) |
each selected value |
selected string |
|
folder |
each content item in the folder |
content item |
|
content item |
the content item |
list with content item as the only entry |
Auxiliary variables allow you to access information about the list or about each item in the list. The auxiliary variables are used by appending a suffix to the variable name defined in the var attribute of the foreach tag. If you omit the var attribute from the foreach tag, you can use the auxiliary variables without a prefix.
The following variables are defined:
|
Variable |
Returns |
|
VariableName_position |
The position of the current item in the list. Starts at 1 and increments with each item. |
|
VariableName_size |
The number of items in the list. |
|
VariableName_previous |
The value that VariableName held on the previous iteration. (The value on the first pass is null.) |
|
VariableName_next |
The value that VariableName has in the next iteration. (The value on the last pass is null.) |
For example,
<pcs:foreach var="item" expr="article_list">
<pcs:value expr="item.headline"></pcs:value>
<pcs:value expr="item.story"></pcs:value>
This is item <pcs:value expr="item_position"></pcs:value>
out of <pcs:value expr="item_size"></pcs:value>
Last item: <pcs:value expr="item_previous"></pcs:value>
Next item: <pcs:value expr="item_next"></pcs:value>
</pcs:foreach>
The <pcs:include> tag inserts the referenced Presentation Template in the content item. The template can only be referenced by a path. The path can be relative or absolute. Relative paths are relative to the template, not the content item. For details on syntax, see Using Paths.
Like a server-side include, the Include element is used most often to display headers, footers, and other kinds of boilerplate content within a page. Using this method ensures that boilerplate content appears uniformly across different types of published content and simplifies changes to the boilerplate section of a page by moving common code to a single template.
Before using the Include element, create a separate Presentation Template that includes the content you want to include in your page.
If the specified template cannot be accessed, the include fails and the element's content is evaluated. In the example below, “Copyright 2003" is displayed if the path does not exist.
Syntax:
<pcs:include templatepath="path">default text</pcs:include>
Example:
<pcs:include templatepath="/boilerplate/footer">Copyright 2003</pcs:include>
The <pcs:insert> tag displays a content item as a component of the current item. The second content item can be referenced by either an expression or path. The Insert tag can only be used with Content Server content items that have an associated Presentation Template. For details on syntax, see Using Properties and Using Expressions.
When the expression is evaluated or the path is traversed, the result is expected to be a content item. The Presentation Template for the content item is selected and implemented using the same rules that would be used if it were being published directly. The results replace the Insert element.
If the specified content item cannot be accessed, the insert fails, and the element's content is evaluated instead. Possible failures include:
No template found for the inserted content item.
Expression does not evaluate to a content item.
Path does not resolve to a content item.
Infinite recursive expansion encountered.
In the first example below, “See the dictionary." is displayed if there is no property named word_of_the_day.
Syntax:
<pcs:insert expr="expression"></pcs:insert>
or
<pcs:insert path="path"></pcs:insert>
Examples:
<pcs:insert expr="word_of_the_day">See the dictionary.</pcs:insert>
<pcs:insert path="/news/latest"></pcs:insert>
Standard HTML and XML code can be entered directly into the Code field in the Presentation Template Editor. However, referencing Content Server objects can result in code that cannot be evaluated properly by an HTML editor. The <pcs:html> tag resolves this issue.
The <pcs:html> tag is generically replaced with a fully composed HTML or XML element to be displayed to the user. This element makes it easier to edit Presentation Templates using a standard WYSIWYG editor, by using syntax that will not be evaluated as faulty code.
Content Server replaces an element named <pcs:html:xxx> with an HTML element with a tagname of <xxx>. The start tag is given attributes derived from the attributes of the <pcs:html:xxx> element. There can be any number of attributes. Each attribute can be either an expression attribute or a literal attribute.
An expression attribute has the form expr:yyy="an_expression", where yyy is any legal attribute name and an_expression is any legal expression (for details, see Using Expressions). The corresponding attribute generated in the resulting tag is yyy="result", where result is the text that results from evaluating the expression an_expression. This form allows you to provide a value, calculated at publishing time, as the value of the attribute.
A literal attribute has the form attr:yyy="value", where yyy is any legal attribute name and value is any legal attribute value. The corresponding attribute generated in the resulting tag is yyy="value". This allows you to add attributes that should be constructed exactly as shown.
Syntax:
<pcs:html:xxx ( style="UNARY|EMPTY|ORPHAN" )? ( content="OMIT" )? (
expr:yyy="expr" | attr:yyy="value" )* >content of element
</pcs:html:xxx>
Examples:
<pcs:html:a expr:href="nextchapter.location">Next Chapter
</pcs:html:a><pcs:html:a attr:href="chap2/overview.htm">Next Chapter
</pcs:html:a>
The text between the tags is evaluated based on the resulting HTML code. The examples above would create a “Next Chapter" link to the next chapter as defined by the referenced Content Server property (nextchapter.location) or static location (chap2/overview.htm).
By default, an element generated by the HTML tag has a start tag and an end tag and content. To override this format, use the additional style and content attributes.
The optional style and content attributes of the HTML tag allow the Presentation Template to override the standard HTML tag format.
XML supports "empty-element" tags which combine the start and end tags like this: <FOO/>. The HTML element will generate an empty-element tag if you include the style="EMPTY" attribute. If this attribute is given, no content is generated even if the HTML element has content.
Some browsers support a start tag without a corresponding end tag. For example, <IMG …> without a corresponding </IMG>. The HTML element will generate a tag like this if you include the style="UNARY" attribute. If this attribute is given, any content generated by the pcs element is placed after the start tag.
In some odd cases HTML supports an end tag with no start tag. The HTML element will generate a tag like this if you include the style="ORPHAN" attribute. If this attribute is given, any content generated by the element is placed before the end tag.
To prevent the content from being generated, include the attribute content="OMIT" (the content is not evaluated, so any side effects from the content will not occur).
The table below shows the result of using the element <pcs:html:foo>Stuff</pcs:html:foo> with a variety of additional attributes.
|
Attributes |
Result |
|
no additional attributes |
<foo>Stuff</foo> |
|
style="EMPTY" |
<foo/> |
|
style="UNARY" |
<foo>Stuff |
|
style="ORPHAN" |
Stuff</foo> |
|
content="OMIT" |
<foo></foo> |
|
style="UNARY" content="OMIT" |
<foo> |
|
style="ORPHAN" content="OMIT" |
</foo> |
|
style="EMPTY" content="OMIT" (redundant) |
<foo/> |
As noted above, each type of attribute used in Content Server elements requires specific syntax. For details, see the pages that follow:
Next: Using Properties