Administrator Guide

Creating Presentation Templates

Publisher uses Presentation Templates to define how a content item is formatted and displayed when it is published. A Data Entry Template defines the properties that make up a structured content item and determines the types of data that users can enter in the Content Item Editor to create a content item. When the content item is previewed or published, a Presentation Template is used to format that data for display. Presentation Templates can include basic formatting, images, and standard boilerplate text, as well as programming logic to display information based on the value of specific content item properties. A Presentation Template is a text file that includes XML-like tags that are replaced with content from the Publisher. A Presentation Template can output any type of text file, including a Java source file, an html file, or a Cascading Style Sheet file.

You can also create a stand-alone Presentation Template that is publishable without a content item or Data Entry Template. This is useful when you want to create a simple single-page portlet that lists links to content items.

Producers or Administrators are responsible for creating Presentation Templates and attaching them to the associated Data Entry Templates. You must have one of these roles to create and edit Presentation Templates.

This chapter includes the following topics:

Creating and Editing Presentation Templates

You can create new Presentation Templates or edit one of the default Presentation Templates, included with the sample portlet templates, to fit your company terminology or content collection needs. You use the Presentation Template Editor to create and edit Presentation Templates.

The Presentation Template Editor has slightly different display modes, depending on whether you are creating a Presentation Template for the first time, editing a normal Presentation Template, or editing an independently publishable Presentation Template.

This section discusses how to:

Use the Presentation Template Editor.
Use a WYSIWYG editor to create Presentation Template code.
Create independently publishable Presentation Templates.
Copy, move, rename, and delete Presentation Templates.

Using the Presentation Template Editor

To launch the Presentation Template Editor, perform one of the following actions in Publisher Explorer:

Click New | Presentation Template.
Right-click in the right pane and choose New | Presentation Template.
Right-click an existing Presentation Template and choose Edit Presentation Template. When you publish an existing Data Entry Template it will pick up the changes to a Presentation Template. Data Entry Templates must be republished to display the change.

You can also access the Presentation Template Editor from the Configure Portlet Wizard and the Configure Portlet Template Wizard.

The Presentation Template Editor includes the following fields:

Name: The template name. This name does not have to match the associated Data Entry Template.

Note:

Renaming an existing Presentation Template does not remove its association with its attached Data Entry Template. If you rename a Presentation Template that is referenced in other Presentation Templates, you must also change the name in those references.

Publishing Name: This field appears only when you are creating a new Presentation Template or editing an independently publishable Presentation Template. Use it only when you want to create or edit a publishable Presentation Template. The name you enter here, plus the .html extension, becomes the file name that is created on the web server when you publish the Presentation Template.

If you do not want to create a publishable Presentation Template, ignore this field and select a Data Entry Template to attach to the Presentation Template. This field is then replaced by the Extension field.

Extension: The extension (file type) for the file that will be created when the content item is published. You can use any extension that is valid for a basic text file (.html, .js, .jsp, .asp, .xml, .txt). If you do not enter an extension, the system uses .html.
Data Entry Template: The Data Entry Template associated with the Presentation Template. Content items created with the selected Data Entry Template will be formatted using the current Presentation Template when they are published.

Do not attach a Data Entry Template if you are creating an independently publishable Presentation Template.

Publishable: For normal Presentation Templates, this field determines whether or not the Presentation Template can be used on its own to publish a content item as a web page or if it must be referenced by another Presentation Template. Select from:

Complete Page: The template can be used on its own to publish a content item as a web page.
Page Component: The template can be used only as a component that is referenced by other Presentation Templates. Typical page component Presentation Templates include header or footer templates.

If you are creating or editing an independently publishable Presentation Template, you must select Complete Page.

Note:

Do not confuse Complete Page Presentation Templates with independently publishable Presentation Templates. While an independently publishable Presentation Template must be a Complete Page template, a Complete Page template is not necessarily an independently publishable Presentation Template. The Complete Page designation simply means that the Presentation Template does not have to be referenced by another Presentation Template in order to be used to publish a content item.

For more information on referencing Page Component Presentation Templates in another Presentation Template, see Include Element <pcs:include>.

Exclude from Search: Prevents users from using the Search feature to locate published content. Published content items created from the associated Data Entry Template will not be indexed by the Search Server, preventing them from being returned in a search.
Related Items to Publish: If there are other content items that must be published when a content item created with this Presentation Template is published, specify them here. For example, when you publish a News article, you must also publish the Index to display the new article.

Note:

You cannot add related items to Page Component Presentation Templates because Page Components are published only as part of a page.

Code: The programming logic for the template is contained in this text field. The text in the Code field can include any code that is valid for the file type specified in the Extension field. To reference Publisher objects, you must use Publisher tags (covered later in this chapter). You can enter code in a Presentation Template in two ways:

Enter the text manually by typing or pasting in the Code field.
Upload an existing text-based file from your local drive, using the Upload button.

You can use the WYSIWYG editor of your choice to create and edit template code before uploading the file or copying and pasting the code into the Code field.

Use the Tag Helper to help you create Publisher (pcs) tags that can be inserted in the Code field.

Use Validate to check the syntax of any pcs tags in the Code field. (Code between HTML tags is not verified.) To correct a syntax error, click the line number to select the part of the code in which the error occurs.

Note:

Whenever you create a new Presentation Template (unless it is an independently publishable Presentation Template), create at least one content item from the associated Data Entry Template. This enables you to preview the Presentation Template on the preview site.

For more information on using a WYSIWYG editor, seeUsing a WYSIWYG Editor.

For more information on the Tag Helper, see Using Tag Helper to Write Presentation Template Code.

For more information on Presentation Template code, see Presentation Template Code.

Using a WYSIWYG Editor

You can create Presentation Template code in a WYSIWYG editor and upload or copy it to the Presentation Template Editor.

To create Presentation Template code in a WYSIWYG editor:

Create the page as a normal web page and use placeholders for Publisher elements.
Open the Presentation Template in the Presentation Template Editor and click Upload to import your page into the Code field.

Caution:

The uploaded file will replace any text in the Code field. If you want to add to an existing template without overwriting anything, use copy and paste instead.

Use the Tag Helper to replace your placeholders with pcs tags.
Click Validate to check the syntax of any pcs tags.

To edit existing template code using a WYSIWYG editor:

Click Download in the Presentation Template Editor and save the file to your computer.
After editing the code in the file, use Upload to enter it in the Presentation Template Editor.

Creating an Independently Publishable Presentation Template

If you are designing a published content portlet that consists of a simple collection of links to other content items, the usual triad of Content Item, Data Entry Template, and Presentation Template may be unnecessary, especially if the Data Entry Template would contain no properties. Instead, you can create a stand-alone Presentation Template that is publishable without a content item or Data Entry Template. Such an independently publishable Presentation Template uses pcs functions to refer to the content items to be included in the portlet, without the necessity of referring to a Data Entry Template or associated content item.

To create an independently publishable Presentation Template:

In Publisher Explorer, create a folder for the Presentation Template.
Launch the Presentation Template Editor.
Enter the Presentation Template Name and Publishing Name that will be used for the file name on the web server. The system adds the .html extension when the template is published.
In the Publishable field, select Complete Page.
In the Code section, enter or upload the Presentation Template code.

You can use any tag or expression in the pcs language in an independently publishable Presentation Template. The following function and method are specific to independently publishable Presentation Templates:

TemplateByPath(folder?,path): returns only independently publishable Presentation Templates.
folder.templates: returns the independently publishable Presentation Templates in the folder.

For more information on Presentation Template code syntax, see Presentation Template Code.

Note:

Independently publishable Presentation Templates cannot be tracked in workflow.

Copying, Moving, Renaming, and Deleting Presentation Templates

You can copy, move, rename, and delete Presentation Templates in Publisher Explorer, just as you do with any Publisher component. Note the following considerations, however, when performing these functions on Presentation Templates:

You can move Presentation Templates from one folder to another in Publisher without breaking references to Data Entry Templates and files. The only exceptions are the file paths in the pcs:include tag: after moving a Presentation Template, you must update paths in this tag to reflect the new location of the Presentation Template.
Renaming a Presentation Template does not remove its association with its attached Data Entry Template, but if the renamed Presentation Template is referenced by other Presentation Templates, you must update the name in the Presentation Templates that reference it.
If you delete a Presentation Template that is attached to a Data Entry Template, you cannot publish or preview content items created from that Data Entry Template until you attach another Presentation Template. Deleting a Presentation Template is permanent. There is no undo.

Presentation Template Code

All Publisher elements use the same syntax and basic components. Review this section before building any Publisher elements.

This section provides an overview of Publisher elements (pcs tags) and discusses proper syntax for:

Property Names
Expressions
Paths

Publisher Elements (PCS Tags)

Publisher elements (tags) are formatted like XML elements and begin with the prefix pcs. For example:

<pcs:tagname attributename=attributevalue...> Content 
</pcs:tagname>

During publication, Publisher replaces the pcs tag with the value of the expression, or the contents of the tag if the expression fails.

Text outside pcs tags is left unchanged when the template is processed during publication. Tags can appear inside HTML elements, inside HTML tags, and inside quoted strings.

Attribute values must be surrounded by single or double quotes, as in HTML or XML:

<pcs:value property="dog"> (legal)

<pcs:value property='dog'> (legal)

<pcs:value property=dog> (not legal)

The table below summarizes the Publisher elements. A detailed explanation of each element is provided in the sections that follow.

Table 10-1 Publisher Elements (PCS Tags)
Element	Description
<pcs:value>	Displays the value of a Publisher property or the results of an expression. Accepts the following Publisher properties: Text, Long Text, Integer, Real, Boolean, Date, and Selection List.
<pcs:if>	Displays content in a published content item only if the specified condition is True. Accepts any legal expression, such as a content item property or string comparison.
<pcs:foreach>	Iterates through a collection of objects. Accepts an expression. The code between the tags is evaluated with each iteration.
<pcs:include>	Inserts the referenced Presentation Template in the content item. Accepts a path only.
<pcs:insert>	Displays a content item as a component of the current item. Accepts an expression or path. Can only be used with content items that have an associated Presentation Template.
<pcs:html>	Allows you to enter standard HTML and XML code in the Code field of the Presentation Template Editor.

You can add Publisher elements (pcs tags) to a Presentation Template by hand or use Tag Helper to create tags. For information on Tag Helper, see Using Tag Helper to Write Presentation Template Code and the online help.

Value Element <pcs:value>

The <pcs:value> tag can be used to display the results of an expression or the following Publisher properties: Text, Long Text, Integer, Real, Boolean, Date, and Selection List. Publisher translates the property value to a text string.

Syntax:

<pcs:value expr="expression" (format="format pattern")>default text</pcs:value>

Examples:

<pcs:value expr="headline"></pcs:value>
<pcs:value expr="article.author">Anonymous</pcs:value>
<pcs:value property='screenwriter.name'><pcs:value 
property='writer.name'></pcs:value></pcs:value>
<img src="<pcs:value expr="photo.location"></pcs:value>">
<a href="<pcs:value property='homepage.location'></pcs:value>">
<pcs:value expr='creation_time' format="MMMM dd"></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 tag 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>

Date Formatting

The date format attribute is optional. If given, it provides a pattern describing how the date should appear in the published document. The format string conforms to the Java language's SimpleDateFormat definition. Formatting a date is useful for showing only part of the date value, e.g. only the time of day or only the day and month. For example:

<pcs:value expr='creation_time' format="MMMM dd"></pcs:value>">

If no format attribute is given, the date is formatted according to the setting of the system configuration property com.plumtree.content.template.defaultDatePublishFormat. If this property is not set, the built-in format used is MM/dd/yyyy hh:mm aa.

Conditional Element <pcs:if>

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. For details, see Expressions. 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 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 following table summarizes how different types of values are considered True or False:

Table 10-2 Value Consideration - True/False
Type of Value	considered True if	considered 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

Iterator Element <pcs:foreach>

The <pcs:foreach> tag allows you to iterate through a collection of objects. The collection can be referenced using an expression. The code between the tags will be evaluated with each value in the iteration.

ForEach elements can be nested. A ForEach element evaluates itself before (repeatedly) evaluating its content.

Syntax:

<pcs:foreach var="variable" expr="expression">

content

</pcs:foreach>

Examples:

<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>

</pcs:foreach>

<pcs:foreach var="item" expr="folderByPath('/authors/latest')">

The list of values through which the tag iterates (the type of object stored in the variable) depends on the result of the expression.

Table 10-3 Variable Object Types (Based on Result of Expression)
Result of Expression	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	list with content item as the only entry	content item
Presentation Template	list with publishable Presentation Template as the only entry	Presentation Template

On each iteration, the variable named in the var= attribute is set to each value in turn. The variable can be used within the content of the foreach tag by other PCS language expressions. If the list expression fails to evaluate, the foreach element expansion fails and the element is dropped.

Auxiliary Variables

Using the auxiliary variables defined within the ForEach tag, you can provide information about the list or about each item in the list. The auxiliary variables are named by appending a suffix to the variable name defined in the ForEach var attribute. The var attribute can be omitted from the ForEach tag; no variable will be defined for the element. The auxiliary variables are still defined and can be used without a prefix.

The following variables are defined:

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.)

Note:

Do not confuse variable suffixes (VariableName_position) with property references (VariableName.name).

Include Element <pcs:include>

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.

Like a server-side include, the Include tag 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 tag, create a separate Presentation Template that includes the content you want to include in your page.

Syntax:

<pcs:include templatepath="path">default text</pcs:include>

Example:

<pcs:include templatepath="/boilerplate/footer">Copyright 2003
</pcs:include>

Insert Element <pcs:insert>

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 Publisher content items that have an associated Presentation Template.

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>

<pcs:insert path="path"></pcs:insert>

For details on syntax for expressions and paths, see the previous chapter.

Examples:

<pcs:insert expr="word_of_the_day">See the dictionary.</pcs:insert>

<pcs:insert path="/news/latest"></pcs:insert>

HTML Element <pcs:html>

Standard HTML and XML code can be entered directly into the Code field in the Presentation Template Editor. However, referencing Publisher 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.

Publisher replaces an element named <pcs:html:xxx> with an HTML element with a tag name 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 on expressions, see Publisher Element Syntax earlier in this section). 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 Publisher 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 (covered next).

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 <pcs:html> tag 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 pcs element has content.

Some browsers support a start tag without a corresponding end tag. For example, <IMG …> without a corresponding </IMG>. The <pcs:html> tag 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 <pcs:html> tag 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).

For example, the element <pcs:html:foo>Stuff</pcs:html:foo> would produce the following, given the additional attributes shown:

Table 10-4 Style Attributes (<pcs:html> Tag)
Attribute	Result
(no extra attributes)	`<foo>Stuff</foo>`
`style="UNARY"`	`<foo>Stuff`
`style="ORPHAN"`	`Stuff</foo>`
`style="EMPTY"`	`<foo/>`
`content="OMIT"`	`<foo></foo>`
`style="UNARY" content="OMIT"`	`<foo>`
`style="ORPHAN" content="OMIT"`	`</foo>`
`style="EMPTY" content="OMIT" (redundant)`	`<foo/>`

Property Names

A Presentation Template is evaluated in the context of a content item (unless it is an independently published Presentation Template). The Data Entry Template corresponding to the content item controls the names and types of any user-defined properties. All content items also have a set of system-defined properties (such as the property, name). The names of system-defined and user-defined properties can be used in a template to refer to the corresponding property values for the current content item.

The simplest property expression is the name of one of the properties in the content item being published:

<pcs:tag property="Headline">

In more advanced uses, the property expression might be a dotted expression. Evaluating from left to right, each property to the left of a dot must evaluate to something that has a property with the name to the right of the dot.

In the example below, “author" is a property in the current content item which refers to a content item having a property “bio", which refers to another content item, which has a property “hometown".

<pcs:tag property="author.bio.hometown">

The only characters that the system treats as unique in a property name are alphabetic (a-z) and numeric (0-9). All other characters (punctuation, blanks) are treated as equivalent and are replaced with an underscore (“_”). Uppercase and lowercase letters are treated equivalently. For example, all of the following tags are equivalent:

<pcs:tag property="jug_head">

<pcs:tag property="JUG HEAD">

<pcs:tag property="Jug+Head">

Caution:

If you change the name of a property in a Data Entry Template, you must also change any references in the associated Presentation Template.

System-Defined Properties

System-defined properties can be applied to the current content item or any Publisher object associated with the current content item. A property applies to the preceding value of the expression (to the left of the dot). If the property is not preceded by a dot, it applies to the current content item.

Caution:

The property names listed in this section are used by Publisher. If you create a property with the same name, it will override the system-defined property. For example, creating a property named location will prevent the URL to that content item from being accessed using a Publisher expression. This could be desirable if the content item should redirect to another location.

The following properties are defined by the system:

Table 10-5 System-Defined Properties
Property	Description
location	URL indicating where the Publisher object was or will be published. Useful for building links on a page. This property is treated as text. Valid for: content item, file property, image property, folder, publishable Presentation Template.
created	Date that the Publisher object was created. Valid for: content item, folder, publishable Presentation Template.
createdBy	Name of the user who created the Publisher object. Valid for: content item, folder, publishable Presentation Template.
modified	Date that the Publisher object was last modified. Valid for: content item, folder, publishable Presentation Template.
modifiedBy	Name of the user that last modified the Publisher object. Valid for: content item, folder, publishable Presentation Template.
published	Date that the Publisher object was last published. Valid for: content item, publishable Presentation Template.
publishedBy	Name of the user who last published the Publisher object. Valid for: content item, publishable Presentation Template.
name	Name of the Publisher object as it appears in Publisher Explorer. This property is treated as text. Valid for: content item, file property, image property, folder, publishable Presentation Template,
pcs_id	Unique identifier string assigned to the Publisher object by the system. As long as the object exists, the unique id will not change, even if the object is renamed or moved to a different folder. Valid for: content item, folder, publishable Presentation Template.
pcs_path	Full path to the Publisher object, within the folder hierarchy. The path starts with a “/", and each component of the path is separated from the next by another “/". Special characters in names are not translated to underscores, so if any of the components’ names contains a slash character, the result can be confusing. Valid for: content item, folder, enumeration, publishable Presentation Template.
height	Vertical dimension, in pixels. This property is treated as an integer. Valid for: image property.
width	Horizontal dimension, in pixels. This property is treated as an integer. Valid for: image property.
length	Length of the object in units appropriate to the type of the object. Valid for: any expression that produces text, in which case the result is the number of characters in the text; a list, in which case the result is the number of values in the list.
folder	Folder that contains the Publisher object. Valid for: content item, folder, publishable Presentation Template.
item	Current content item. This property can be used to access the current content item; without it there is no way to compare the current object with another item reference. Useful in expressions that test whether two item references are the same. Valid for: content item, publishable Presentation Template.
subfolders	A list of subfolders. Valid for: folder.

Expressions

Any Publisher tag that accepts a property can also use a general expression. An expression attribute's value can be:

a property name
a constant
an expression (one or more expressions combined with an operator)
a function call

Property Names

Expressions can be used to reference Publisher properties. To reference a property, use the rules described in Property Names.

Constants

A constant expression can be a number constant or a string constant.

A number 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. XML escaping rules must be applied 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 &quote;help!&quote;h'">

Expressions

All expressions are supported within expression attributes. Expressions can be compared and combined using relational, arithmetic and logical operators (detailed in the sections that follow.)

Note:

Comparisons are case-sensitive; property names are not. Strings allow the use of spaces and punctuation marks; property names do not.

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)

Relational Operators

The following relational operators are supported in the expression attribute:

Table 10-6 Relational Operators
Operator	Meaning	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	<=

Note:

Since the greater-than and less-than characters 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.

expr="'blue'=='Blue'" is false.

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:

Table 10-7 Comparisons - Rules
Value Types	Equality operators (== and !=)	Relational operators (>, ≥, <, ≤)
text v. text	exact same characters in same sequence	relative alphabetic value of first differing character
number v. number	same numerical values	relative numerical values
enumeration v. enumeration	based on same enumeration type, contain same selections	n/a
text v. number	text is converted to number and compared	text is converted to number and compared
text v. enumeration	enumeration is converted to text and compared	n/a
item v. item	same item	n/a

Arithmetic Operators

The following arithmetic operators are defined:

Table 10-8 Arithmetic Operators
Operator	Meaning	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 above
/	numeric division	same as above
%	numeric remainder	same as above

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:

Table 10-9 Logical Operators
Operator	Meaning	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 following table provides some examples:

Table 10-10 Logical Expression 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

( )

* / %

+ -

> ≥ < ≤

== !=

&and;

&or;

Lowest

Functions

The only functions available for use in expressions are those predefined by the system:

Table 10-11 Functions for use in Properties
Function	Parameters	Return Value
`itemByPath(path)` `itemByPath(folder, path)`	path: String folder: Folder	The content item identified by the path.
`TemplateByPath(folder, path)`	path: String folder: Folder	The publishable Presentation Template identified by the path.
`folderByPath(path)` `folderByPath(folder, path)`	path: String folder: Folder	The folder identified by the path string.
`objectByUid(uid)`	uid: String (unique identifier obtained from Publisher)	The object identified by the UID.

Note:

Relative paths are based on the Presentation Template, not the content item being published. To get the name of a folder relative to the item, use

<pcs:value expr="itemByPath(folder, 'my/sub/folder').name"> **Expression Failed**</pcs:value>

For details on using paths, see the Paths section that follows.

Functions can be used to access the properties of another content item, as shown in the examples below.

<pcs:value expr='itemByPath(“/News/Headlines")'>**Expression Failed **</pcs:value>

The first example would evaluate to **Expression Failed** because the property cannot be rendered. This can be corrected by adding a property reference, as shown below.

<pcs:value expr='itemByPath(“/News/Headlines").name'>
**Expression Failed **</pcs:value>

Paths

Many Publisher tags use a path to reference a Publisher object. A path string is similar to a filesystem path or URL; that is, a string of names with slashes (/) separating them. The last name is the name of the desired object, and the preceding names are the folders to traverse to find the object.

If the path begins with a slash, it is an absolute path. The search begins at the root folder of the publishing site.

path="/library/includes/music/symphony"

In this example, the site root folder is searched for a folder named “library". That folder is searched for a folder named “includes". That folder is searched for a folder named “music". That folder is searched for an object called “symphony", and that object is used by the tag.

If the path does not begin with a slash, it is a relative path. The search begins at the folder containing the template or content item in use.

path="show/public/navbar"

In this example, the current folder is searched for a folder named “show". That folder is searched for a folder named “public". That folder is searched for an object called “navbar", and that object is used by this tag.

Caution:

Spaces or special characters in any of the folder names or the object names must be represented by underscores (_) in the path.

path="Related_Templates/july_and_august/summer_festival"

Folder and template names are not case sensitive. The code below is equivalent to the previous path.

path="related_templates/July_and_August/SUMMER_FESTIVAL"

The special path component ".." (two periods, often called "dot-dot") refers to the folder above the current folder:

path='../../vegetables/onions'

This example starts with the current folder, goes to the folder containing it, goes up again one folder, goes down into the folder “vegetables", and then accesses the object called “onions".

Since a root folder has no container, applying “.." to a root folder has the same effect as trying to access any folder that does not exist.

Using Tag Helper to Write Presentation Template Code

The Tag Helper is an interface that helps you to include Publisher elements, images, and portal controls in a Presentation Template. Each tabbed page in the Tag Helper creates a specific tag that can be added to the Code field in the Presentation Template Editor. Click the tabs in the Tag Helper window to access the appropriate tag:

Value
If
ForEach
Images
Portal Controls
Insert
Include
HTML

For more information on Tag Helper, see the online help.

For more information on Publisher elements (pcs tags), see Presentation Template Code

For more information on Portal Controls, see the AquaLogic User Interaction Development Guide on dev2dev.bea.com.

Using CSS and JavaScript Files

If you are creating content items for a web site, you can ensure consistency from one web page to the next using a Cascading Style Sheets (.css) file, a .js (JavaScript) file, or both. To manage .css and .js files, bring them into your Publisher database and publish them to your web site:

Create a .css or .js file in the appropriate program of your choice.
In Publisher Explorer, create a content item to contain the text from the .css or JavaScript file you created in step 1:

Create a Data Entry Template with one property of the Long Text property type.
Create a Presentation Template. Use the Value tag to reference the property you created in the Data Entry Template.
Create a content item from the Data Entry Template and paste the contents of the .css or .js file into it. For Publishing Name, specify the name you want the file to have when published to the Web, followed by the extension (.css or .js).

In Publisher Explorer, create another content item to serve as a link between the .css or .js content item. web pages should reference the content item you create in this step, not the content item created in step 2.

Create a Data Entry Template for the linking content item. The Data Entry Template should have a single property of the Item property type.
Create a Presentation Template for the Data Entry Template. Use the HTML tag to specify the name of the .css or .js content item and other variables. For example:

JavaScript (.js):

 <pcs:html:script attr:language="JavaScript" expr:src="item_name.location">

</pcs:html:SCRIPT>

Cascading Style Sheet (.css):

 <pcs:html:link attr:rel="stylesheet" expr:href="css_link.location" attr:type="text/css"></pcs:html:link>

Create a content item from the Data Entry Template you created in step 3a. In the Item property, type the name of the content item that contains the .css or .js file you created in step 2c.

In Publisher Explorer, create a Data Entry Template and content items for web pages.

Create a Data Entry Template with the appropriate properties and property types for the web page.
Create a Presentation Template for the Data Entry Template. Use the Insert tag to insert the content item created in step 3. For example: <hps:insert path="/assets/css_linked_item"></hps:insert>
From the Data Entry Template you created in step 4a, create the content items that use the .css or .js file(s).

Caution:

You must publish the content items created in steps 2 and 3 along with the web pages.

Whenever you want to apply a different .css or JavaScript file, you can copy the contents of the new .js or .css file into the content item you created in step 2c and republish to the web site.

Presentation Template Tools

Publisher provides Presentation Template Tools in the form of JSPs so the Presentation Template creator can use these tools to access Publisher functionality from published content.

The JSPs are:

content_item.jsp
create_folder.jsp
search.jsp

content_item.jsp

You can use this to open the Content Item Editor.

Table 10-12 content_item.jsp parameters
Parameter	Description
fid	the id of the folder to create a new content item
dfid	the id of the folder containing the Data Entry Template specified by the det parameter
det	the name of the Data Entry Template to use to create a new content item. The Data Entry Template must be located in either the folder specified by dfid or fid
ctid	the id of the Data Entry Template to use to create a new content item
ciid	the id of the content item to open in the Content Item Editor
checkout	set to true to check out the content item specified by ciid
view	set to “submit” to force the user to get the simple submit view of the Content Item Editor

Examples:

To create a new content item in the articles folder using the news article Data Entry Template (also located in the articles folder):

<pcs:value expr=’pcs_location’></pcs:value>/published_tools/content_item.jsp?fid=<pcs:valueexpr=”folderByPath(‘Articles’).pcs_id”></pcs:value>&det=News%20Article”

To edit an existing content item:

<pcs:value expr=’pcs_location’></pcs:value>/published_tools/content_item.jsp?ciid=<pcs:value expr=’pcs_id’></pcs:value>

create_folder.jsp

Use this to prompt the user to create a new folder.

Table 10-13 create_folder.jsp parameter
Parameter	Description
fid	the id of the parent folder to create the new folder

Example:

To prompt the user to create a new folder within the articles folder:

<pcs:value expr=”pcs_location”></pcs:value>/published_tools/create_folder.jsp?<pcs:value expr=”folderByPath(‘Articles’).pcs_id”></pcs:value>

search.jsp

Use this to search for published content items associated with a particular portlet.

Table 10-14 search.jsp parameters
Parameter	Description
fid	search for content items associated with the same portlet as the folder id specified here. If it is not specified, it will search for content items associated with the current portlet if it exists
searchtext	the text to search for

Example:

To search for the string “hello world” in content items associated with the current portlet:

<pcs:value expr=”pcs_location”></pcs:value>/published_tools/search.jsp?searchtext=hello%20world

Note: The above JSPs respect the security of the folder in which the action is taking place.