4 Programming with Oracle WebCenter Sites

In addition to managing your content, Oracle WebCenter Sites handles many useful tasks for you, including storing web pages and pieces of web pages, called pagelets, in WebCenter Sites caches, and maintaining those caches so that visitors to your website never see an outdated page. In order for WebCenter Sites to do this, you must code with WebCenter Sites tags and Java methods.

A WebCenter Sites page is composed of various element assets, blocks of code that can retrieve the content of your pages from the WebCenter Sites database, or that perform other tasks, such as deleting outdated items from the database, and Template assets, which are generally used to format the content of your web pages. Elements and templates can be written in a number of scripting and markup languages, including HTML, XML, JSP, CSS, and JavaScript. Note, however, that WebCenter Sites only evaluates XML and JSP.

This chapter gives you a brief overview of programming with WebCenter Sites. It contains the following sections:

Section 4.1, "Choosing a Coding Language"
Section 4.2, "The Oracle WebCenter Sites Context"
Section 4.3, "WebCenter Sites JSP"
Section 4.4, "WebCenter Sites XML"
Section 4.5, "WebCenter Sites Tags"
Section 4.6, "Variables"
Section 4.7, "Other WebCenter Sites Storage Constructs"
Section 4.8, "Values for Special Characters"

Note:

The following feature is deprecated in WebCenter Sites 11g Release 1 (11.1.1.8.0): SOAP-based web services. This feature is replaced by REST services.

4.1 Choosing a Coding Language

Choose your coding or markup language based on what the element or template that you are creating does. For example, you typically use HTML and XML for page layout and JSP and Java for logic. Elements that display content that may change, such as a newspaper article, should usually be written in XML or JSP. This is because such elements use logic to retrieve their content from the WebCenter Sites database, and thus are managed using WebCenter Sites XML or JSP tags.

WebCenter Sites also has a Java API, which you will use in conjunction with WebCenter Sites JSP tags if you choose JSP as your coding language.

The following table lists the situations to which each language is best suited:

Table 4-1 Coding Language Usage

Code	When to Use
`XML`	The element contains mostly text, with few loops and conditionals.
`JSP`	The element requires conditional operators, or relational operators other than = or !=. The element uses many loops. Loops perform better in JSP than in XML. The element contains calls to Java code.

Note that elements written in XML or JSP can call any type of element, but you cannot mix XML and JSP in the same element. For example, an element written in either XML or JSP can call another element written in HTML, XML, or JSP. However, an element written in HTML cannot call an element written in XML or JSP.

4.2 The Oracle WebCenter Sites Context

When you code for a Oracle WebCenter Sites project, you code within the Oracle WebCenter Sites context. The WebCenter Sites context provides access to the Java servlets that compose WebCenter Sites, and to the WebCenter Sites Java objects whose methods and tags allow you access to WebCenter Sites functionality.

You code in the WebCenter Sites context no matter what language you code your project in; WebCenter Sites XML and JSP tags provide an easy-to use interface to WebCenter Sites's Java objects, so that even web designers with little or no Java experience can create WebCenter Sites web pages.

4.2.1 The ICS Object

When you are coding for Oracle WebCenter Sites, you often access the methods and tags of the Interface to WebCenter Sites (ICS) object. The ICS object encapsulates some of WebCenter Sites's core functionality, allowing you to access servlets that control the WebCenter Sites tree (the TreeManager servlet) and the input of data into the database (the CatalogManager servlet).

You also use ICS methods and tags to perform tasks such as creating and displaying variables and using if/then statements to perform tasks based on specified conditions. For a complete list of the ICS object's methods and tags, see the Oracle Fusion Middleware WebCenter Sites Tag Reference

4.2.2 The FTCS tag

Each WebCenter Sites element or template begins and ends with the ftcs tag. This tag creates the WebCenter Sites context, alerting WebCenter Sites that code contained within the opening and closing ftcs tags will contain WebCenter Sites tags and access ICS methods.

If you use the WebCenter Sites user interface or the Oracle WebCenter Sites Explorer tool to create elements and templates, the opening and closing ftcs tags are automatically added after the standard directives. You must code within the opening and closing ftcs tags; WebCenter Sites is unaware of any code which falls outside of these tags.

If you create element and template code using some other method, you must add the opening ftcs tag after your directives, and use the closing ftcs tag as the last line of your code.

4.3 WebCenter Sites JSP

JSP programmers have a set of standard tools at their disposal, including directives, actions, and JSP objects. If you are programming in JSP within WebCenter Sites, you have access to many of these features. Sometimes, however, you must substitute a WebCenter Sites tag for a JSP directive or action, or access a WebCenter Sites object rather than one of JSP's implicit objects.

The following sections detail the differences between standard JSP and WebCenter Sites JSP, and how standard JSP functionality maps to WebCenter Sites tags and methods:

Section 4.3.1, "WebCenter Sites Standard Beginning"
Section 4.3.2, "JSP Implicit Objects"
Section 4.3.3, "Syntax"
Section 4.3.4, "Actions"
Section 4.3.5, "Declarations"
Section 4.3.6, "Scriptlets and Expressions"
Section 4.3.7, "JSP Directives"
Section 4.3.8, "Oracle WebCenter Sites Tag Libraries"

4.3.1 WebCenter Sites Standard Beginning

If you use either the WebCenter Sites user interface or Oracle WebCenter Sites Explorer to create your Template assets, CSElement assets, and non-asset elements, WebCenter Sites automatically seeds the element or template with a standard beginning.

The standard beginning for a JSP element in Oracle WebCenter Sites Explorer follows:

<%@ taglib prefix="cs" uri="futuretense_cs/ftcs1_0.tld" %>
<%@ taglib prefix="ics" uri="futuretense_cs/ics.tld" %>
<%@ taglib prefix="satellite" uri="futuretense_cs/satellite.tld" %>
<%//
// elementName
//
// INPUT
//
// OUTPUT
//%>
<%@ page import="COM.FutureTense.Interfaces.FTValList" %>
<%@ page import="COM.FutureTense.Interfaces.ICS" %>
<%@ page import="COM.FutureTense.Interfaces.IList" %>
<%@ page import="COM.FutureTense.Interfaces.Utilities" %>
<%@ page import="COM.FutureTense.Util.ftErrors" %>
<%@ page import="COM.FutureTense.Util.ftMessage"%>
<cs:ftcs>

<!-- user code here -->

</cs:ftcs>

If you use the WebCenter Sites user interface to create Template and CSElement assets, you will also see a standard beginning similar to the preceding code sample. The standard beginning for these assets imports additional tag libraries for use with basic assets and includes tags that log dependencies between the Template and CSElement assets and the content that they render.

If you use a tool other than Oracle WebCenter Sites Explorer or the WebCenter Sites user interface to create your elements and templates, you must copy the standard beginning into your code verbatim.

The following sections explain the standard beginning for Oracle WebCenter Sites Explorer.

4.3.1.1 Taglib Directives

The following taglib directives import the base tag libraries that you will use with WebCenter Sites. If you use the WebCenter Sites user interface to create template and CSElement assets, you will see additional taglib directives in your seed code.

<%@ taglib prefix="cs" uri="futuretense_cs/ftcs1_0.tld" %>
<%@ taglib prefix="ics" uri="futuretense_cs/ics.tld" %>
<%@ taglib prefix="satellite" uri="futuretense_cs/satellite.tld" %>

The first directive imports the ftcs1_0 tags, which create the FTCS context. These tags are used in each template or element that you create, and indicate that the code enclosed by them will be controlled by WebCenter Sites.

The second directive imports the ics tags, which provide access to WebCenter Sites's core functionality.

The third directive imports the satellite tags, which are for use with Satellite Server.

For more information about these tag libraries, see Section 4.3.8, "Oracle WebCenter Sites Tag Libraries."

For information about commonly used tags that are found in these tag libraries, see Section 4.5, "WebCenter Sites Tags."

To add taglib directives to these defaults, modify and save the OpenMarket/Xcelerate/AssetType/Template/ModelJsp.xml file.

4.3.1.2 Page Directives

The following page directives import the base Java interfaces that you will use with WebCenter Sites:

<%@ page import="COM.FutureTense.Interfaces.FTValList" %>
<%@ page import="COM.FutureTense.Interfaces.ICS" %>
<%@ page import="COM.FutureTense.Interfaces.IList" %>
<%@ page import="COM.FutureTense.Interfaces.Utilities" %>
<%@ page import="COM.FutureTense.Util.ftErrors" %>
<%@ page import="COM.FutureTense.Util.ftMessage"%>

The first page directive imports the FTValList interface, which creates a list of
name/value pairs that you use to pass arguments to WebCenter Sites subsystems like the CatalogManager and TreeManager.

The second page directive imports the ICS interface, which provides access to the core WebCenter Sites functionality.

The third page directive imports the IList interface, which contains the methods to access the rows in a WebCenter Sites query or list object. It also contains the methods that a third party must implement when attempting to construct and register a list object for use within an WebCenter Sites XML page.

The fourth page directive imports the Utilities interface, which provides a simple interface for some common tasks such as formatting dates, reading and writing files, and sending email.

The fifth page directive imports the ftErrors class, which contains error codes.

The sixth page directive imports the ftMessage class, which contains error messages used by WebCenter Sites.

To add page directives to the standard directives for JSP elements, modify and save the OpenMarket/Xcelerate/AssetType/Template/ModelJsp.xml file.

4.3.1.3 The cs:ftcs Tag

Each WebCenter Sites JSP template or element must have the cs:ftcs tag as its first and last tags. This tag creates the WebCenter Sites context, alerting WebCenter Sites that code contained within the opening and closing cs:ftcs tags will contain WebCenter Sites tags.

You must code within the opening and closing cs:ftcs tags; WebCenter Sites is unaware of any code which falls outside of these tags.

4.3.2 JSP Implicit Objects

JSP provides several implicit objects that are available for developers to use. In the WebCenter Sites context, however, you are often dealing with WebCenter Sites's objects, and should use WebCenter Sites JSP tags and Java methods to access these objects, instead of using JSP's implicit objects.

The following table maps JSP's implicit objects and some of their commonly used methods to the WebCenter Sites tag or method that you should use to replace them.

Table 4-2 JSP Implicit Object Mapping

Object	Method	WebCenter Sites Tag or Method
`request`	`getParameter`	`ics:getvar tag`
`request`	`getParameterNames`	`ICS.GetVars() method`
`request`	`getCookie`	`ics:getCookie tag`
`response`	`addCookie`	`satellite:cookie tag`
`session`	`getAttribute`	`ics:getssvar tag`
`session`	`setAttribute`	`ics:setssvar tag`
`out`	`println`	`ics:getvar tag or render:stream tag`

4.3.3 Syntax

Oracle WebCenter Sites uses standard JSP syntax. When you are nesting tags, for example, using a JSP expression as the value of a JSP tag's parameter, remember to use single quotes to contain the expression, as in the following example:

name='<%=ics.GetVar("myVariable")%>'

4.3.4 Actions

Standard JSP allows developers to use several different actions. The following table describes what actions should be replaced with WebCenter Sites tags and which can be used as usual:

Table 4-3 JSP Actions vs. WebCenter Sites Tags

Action	WebCenter Sites
`<jsp:forward>`	Use the `render:satellitepage` or `render:callelement` tags instead.
`<jsp:getproperty>`	Use this for custom Java Beans. If you want to find the value of one of the WebCenter Sites properties, use the `<ics:getproperty>` tag.
`<jsp:include>`	Use the `render:satellitepage` or `render:callelement` tags instead.
`<jsp:setProperty>`	Use this to set properties in custom Java Beans. Use the WebCenter Sites Property Editor to set WebCenter Sites properties.
`<jsp:useBean>`	Use this for custom Java Beans.

4.3.5 Declarations

In standard JSP, you usually declare variables within a JSP declaration. In WebCenter Sites, you use the ics:setvar tag to declare variables that are available in the WebCenter Sites context.

For more information about WebCenter Sites variables, see Section 4.6, "Variables."

4.3.6 Scriptlets and Expressions

You can use scriptlets and expressions without any variation from normal JSP usage.

When you use an expression as the value of the parameter for a WebCenter Sites JSP tag, however, be sure that you nest quotation marks correctly, as described in Section 4.3.3, "Syntax."

4.3.7 JSP Directives

When you are coding JSP in a Oracle WebCenter Sites context, there are some caveats for using directives, which are outlined in the following table:

Table 4-4 JSP Directives vs. WebCenter Sites Tags

Directive WebCenter Sites

Directive	WebCenter Sites
`IncludeDirective`	Use the `render:satellitepage` or `render:callelement` tags to include other files in your JSP pages.
`Page Directive`	If you use the WebCenter Sites user interface or the Oracle WebCenter Sites Explorer tool to create elements or templates, your element or template is automatically seeded with standard page directives. In addition to the standard directives, you must add one other page directive to set the `contentType` for each WebCenter Sites element or template that you create. Set your page's content type to text/html and the character set to UTF-8 by providing the following page directive as the first line of every WebCenter Sites JSP file: `<%@ page contentType="text/html; charset=UTF-8" %>`
`Taglib Directive`	WebCenter Sites automatically seeds your templates and elements with commonly used taglib directives. You can add additional WebCenter Sites taglib directives to an element or Template asset as needed; a list of the WebCenter Sites tag libraries follows this table.

IncludeDirective

Use the render:satellitepage or render:callelement tags to include other files in your JSP pages.

Page Directive

If you use the WebCenter Sites user interface or the Oracle WebCenter Sites Explorer tool to create elements or templates, your element or template is automatically seeded with standard page directives.

In addition to the standard directives, you must add one other page directive to set the contentType for each WebCenter Sites element or template that you create.

Set your page's content type to text/html and the character set to
UTF-8 by providing the following page directive as the first line of every WebCenter Sites JSP file:

<%@ page contentType="text/html; charset=UTF-8" %>

Taglib Directive

WebCenter Sites automatically seeds your templates and elements with commonly used taglib directives.

You can add additional WebCenter Sites taglib directives to an element or Template asset as needed; a list of the WebCenter Sites tag libraries follows this table.

4.3.8 Oracle WebCenter Sites Tag Libraries

WebCenter Sites has a series of JSP tag libraries that correspond to functions in WebCenter Sites's APIs.

The following table lists the WebCenter Sites tag libraries and describes their functions. Use this table as a reference when deciding which tag libraries to import into your JSPs.

4.3.8.1 Tag Libraries for Both Basic and Flex Assets

Table 4-5 Tag Libraries for Both Basic and Flex Assets

Tag Library	Description
`acl.tld`	Tags for creating and manipulating Access Control Lists.
`date.tld`	Tags that convert dates with year, month, day, and optional hour, minute, and am/pm fields into epoch format long integers representing milliseconds since Jan 1, 1970, 0:00 GMT. Date tags also convert long integers into dates.
`dir.tld`	Directory Services tags.
`ftcs1_0.tld`	Tags that create the FTCS context. These tags are used in each template or element that you create, and indicate that the code enclosed by them will be controlled by WebCenter Sites.
`ics.tld`	Tags which provide access to core WebCenter Sites functionality, including access to the CatalogManager and TreeManager commands, and basic coding constructs like if/then statements.
`insite.tld`	Tags for Web Mode.
`localestring.tld`	Tags for localizing text strings.
`name.tld`	Tags that access the name of the user who is currently logged in to WebCenter Sites and manipulate usernames in directory services.
`object.tld`	Tags for manipulating WebCenter Sites objects.
`property.tld`	Tags for retrieving values from WebCenter Sites property files.
`render.tld`	Tags that render basic assets.
`tags for working with satellite server`	Many of these tags have RENDER equivalents (as defined in `render.tld`) that are preferred for building sites with WebCenter Sites.
`soap.tld`	WebCenter Sites SOAP tags.
`time.tld`	Tags that get and set the timing for determining the performance of elements.
`user.tld`	Tags to log users in and out of WebCenter Sites.
`webservices.tld`	Web services tags that allow you to consume certain types of public websites as part of a WebCenter Sites page.

4.3.8.2 Tag Libraries for Basic Assets

Table 4-6 Tag Libraries for Basic Assets

Tag Library	Description
`asset.tld`	Tags that retrieve and manipulate basic assets.
`siteplan.tld`	Tags that allow access to the site plan tree. You use these tags to create navigation for a site that uses basic assets.

4.3.8.3 Tag Libraries for Flex Assets

Table 4-7 Tag Libraries for Flex Assets

Tag Library	Description
`assetset.tld`	Tags for creating assetsets with flex assets.
`blobservice.tld`	Tags for retrieving and manipulating blobs that are attributes of flex assets.
`calculator.tld`	Tags that provide basic calculator and boolean functions.
`cart.tld`	Tags that allow you to add, delete, and otherwise manipulate items in a shopping cart object.
`cartset.tld`	Tags that allow you store, retrieve, delete, and list shopping cart objects for a registered buyer.
`commercecontext.tld`	Tags that access the objects in the visitor context.
`currency.tld`	Tags that convert floating point values and currency strings, and perform formatting and rounding operations on currency strings.
`decimal.tld`	Tags that format floating point values as decimal objects in different locales.
`hash.tld`	Tags that allow you to cast an IList as a hash table and search it by key.
`listobject.tld`	Tags that construct WebCenter Sites resultset lists, which are used throughout your elements as arguments for other tags.
`locale1.tld`	Tags that generate a locale object, which is used to describe the desired locale for various other tags in the system.
`misc.tld`	Miscellaneous tags, including a tag that returns the names of all the columns in an input list
`searchstate.tld`	Tags for creating searchstates to constrain groups of flex assets (assetsets).
`session.tld`	A tag that flushes all stored objects for a given session.
`string.tld`	Tags that perform string manipulations.
`textformat.tld`	Tags that format text.
`vdm.tld`	Visitor Data Management tags, which enable you to record and retrieve information about website visitors from WebCenter Sites, or from other databases.

For complete descriptions of the WebCenter Sites tags used for template development, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.

4.4 WebCenter Sites XML

This section explains the basics of WebCenter Sites XML. WebCenter Sites XML uses standard XML syntax and is defined by the futuretense_cs.dtd. As with WebCenter Sites JSP tags, WebCenter Sites XML tags provide access to WebCenter Sites servlets and objects.

The following sections describe things to be aware of when coding with WebCenter Sites XML.

4.4.1 WebCenter Sites Standard Beginning

If you use the WebCenter Sites user interface or the Oracle WebCenter Sites Explorer tool to create your templates and elements, WebCenter Sites automatically seeds the element with the following standard beginning:

<?xml version="1.0" ?>
<!DOCTYPE ftcs SYSTEM "futuretense_cs.dtd">
<ftcs version="1.2">
</ftcs>

If you use some other tool to create your elements and templates, you must copy this code into them verbatim.

The following sections explain this standard beginning.

4.4.1.1 XML Version and Encoding

The first line in any WebCenter Sites XML template or element must set the XML version, as follows:

<?xml version="1.0"?>

Note that in order for your element to run, <?xml version="1.0"?> must be the first line in the element, with no spaces before the text. The line must also have a hard return at the end, placing it on its own line.

If you need to set the encoding for this template or element, you can do this as follows:

<?xml version="1.0" encoding="utf-8"?>

4.4.1.2 The DTD File

WebCenter Sites XML is defined by the futuretense_cs.dtd file. You must import this file into each WebCenter Sites element or template that you code by entering the following line immediately after the XML version statement:

<!DOCTYPE ftcs SYSTEM "futuretense_cs.dtd">

4.4.1.3 The FTCS Tag

Each WebCenter Sites XML template or element must have the ftcs tag as its first and last tags. This tag creates the WebCenter Sites context, alerting WebCenter Sites that code contained within the opening and closing FTCS tags will contain WebCenter Sites tags.

You must code within the opening and closing ftcs tags; WebCenter Sites is unaware of any code which falls outside of these tags.

4.4.2 XML Entities and Reserved Characters

Because symbols such as < and > are reserved characters in XML, you must not place them in your content. For example, the following code confuses the XML parser because the less-than sign (<) appears inside some text:

<P>4 < 7</P>

You must use character entities in place of reserved characters. Character entities begin with &# and end with a semicolon. Between the &# and the semicolon, you specify the decimal Latin-1 (a superset of ASCII) value of the character. For example, the decimal Latin-1 value of the < character is 60, so the correct way to code the preceding line in XML is:

<P>4 &#60; 7</P>

See Section 4.8, "Values for Special Characters" for a list of these character entities.

4.4.3 XML Parsing Errors

The XML parser that processes WebCenter Sites tags ensures that the tags are syntactically correct. This simplifies tracking down hard-to-find problems related to tagging syntax errors. A misspelled tag name is not reported as an error. This is because the XML parser doesn't require all tag names to exist in the DTD.

When a page request is made to a WebCenter Sites system and an XML syntax error is detected, the results streamed back will contain useful information to help you locate the problem. The results include a general error description, followed by the line/column location of the error. For example, the following error reports a bad parameter name:

Illegal attribute name NAM Illegal attribute name NAM 
Location: null(6,11) 
Context:

And the next error reports an incorrect tag nesting:

Close tag IF does not match start tag THEN Close tag IF does not match start tag THEN 
Location: null(13,3) 
Context:

The XML parser also detects run-time errors. These are errors where the XML tags are syntactically correct, however, some error in the structure is detected during processing. For example, the following error reports an invalid use of ARGUMENT:

Failed to run template:c:\FutureTense\elements\dan.xml Runtime error Argument invalid [Argument 5]
Containing tag: FTCS

4.5 WebCenter Sites Tags

WebCenter Sites has an extensive set of tags in both JSP and XML that allow you to access the various functions of WebCenter Sites and its product family. You use these tags in conjunction with HTML, Java, JavaScript, and custom tags that you create, to code your website.

This section provides and overview of the tags that you are most likely to use in your Template assets and elements. For complete information on all of the WebCenter Sites tags, see the Oracle Fusion Middleware WebCenter Sites Tag Reference

The tags discussed here are arranged by usage, as follows:

Section 4.5.1, "Tags That Create the WebCenter Sites Context"
Section 4.5.2, "Tags That Handle Variables"
Section 4.5.3, "Tags That Call Pages and Elements."
Section 4.5.4, "Tags That Create URLs."
Section 4.5.5, "Tags That Control Caching."
Section 4.5.6, "Tags That Set Cookies."
Section 4.5.7, "Programming Construct Tags."
Section 4.5.8, "Tags That Manage Compositional and Approval Dependencies."
Section 4.5.9, "Tags That Retrieve Information About Basic Assets."
Section 4.5.10, "Tags That Create Assetsets (Flex Assets)."
Section 4.5.11, "Tags That Create Searchstates (Flex Assets)."

4.5.1 Tags That Create the WebCenter Sites Context

The following table describes tags that create the WebCenter Sites context in which you code. You use these tags in every template or element that you write.

FTCS (XML) ftcs1_0:ftcs (JSP)

FTCS (XML)	ftcs1_0:ftcs (JSP)
`<FTCS>` `</FTCS>`	`<ftcs1_0:ftcs>` `</ftcs1_0:ftcs>`

<FTCS>

</FTCS>

<ftcs1_0:ftcs>

</ftcs1_0:ftcs>

The FTCS tag creates the WebCenter Sites context. The opening FTCS tag should be the first tag in your code, and the closing FTCS tag should be the last tag in your code. WebCenter Sites is unaware of anything that falls outside of the opening and closing FTCS tags. Consequently, content outside the tags will not be cached, and the tags will not operate correctly.

4.5.2 Tags That Handle Variables

The following tags handle variables in WebCenter Sites.

CSVAR (XML) ics:getvar (JSP)

CSVAR (XML)	ics:getvar (JSP)
`<CSVAR NAME="variableName"/>`	`<ics:getvar` `name="variableName"/>`

<CSVAR NAME="variableName"/>

<ics:getvar

name="variableName"/>

CSVAR displays the value of a variable, session variable, built-in, or counter.

SETVAR (XML) ics:setvar (JSP)

SETVAR (XML)	ics:setvar (JSP)
`<SETVAR` `NAME="variableName"` `VALUE="variableValue"/>`	`<ics:setvar` `name="variableName"` `value="variableValue"/>`

<SETVAR

NAME="variableName"

VALUE="variableValue"/>

<ics:setvar

name="variableName"

value="variableValue"/>

SETVAR sets the value of a regular, WebCenter Sites variable.The value of the variable exists for the duration of the page evaluation unless it is explicitly deleted using REMOVEVAR.

SETSSVAR (XML) ics:setvar (JSP)

SETSSVAR (XML)	ics:setvar (JSP)
`<SETSSVAR` `NAME="variableName"` `VALUE="variableValue"/>`	`<ics:setssvar` `name="variableName"` `value="variableValue"/>`

<SETSSVAR

NAME="variableName"

VALUE="variableValue"/>

<ics:setssvar

name="variableName"

value="variableValue"/>

SETSSVAR sets a session variable.

REPLACEALL (XML) ics:resolvevariables (JSP)

REPLACEALL (XML)	ics:resolvevariables (JSP)
`<REPLACEALL` `NAME="variableName"` `VALUE="variableValue"/>`	`<ics:resolvevariables` `name="variableName"` `[output="variable name"]` `[delimited="true\|false"]/>`

<REPLACEALL

NAME="variableName"

VALUE="variableValue"/>

<ics:resolvevariables

name="variableName"

[output="variable name"]

[delimited="true|false"]/>

REPLACEALL and ics:resolvevariables resolve multiple WebCenter Sites variables. In other words, when you want to use WebCenter Sites variables in HTML tags, you use these tags to resolve the variables.

For more information about variables in WebCenter Sites, see Section 4.6, "Variables."

4.5.3 Tags That Call Pages and Elements

Use the following tags to call elements or templates.

Note:

CACHECONTROL, used below, has been deprecated.

RENDER.SATELLITEPAGE (XML) render:satellitepage (JSP)

RENDER.SATELLITEPAGE (XML)	render:satellitepage (JSP)
`<RENDER.SATELLITEPAGE` `PAGENAME="nameOfPageEntry"` `[CACHECONTROL="expiration_date_and_time"]` `[ARGS_var1="value1"]/>`	`<render:satellitepage` `pagename="nameOfPageEntry"` `[cachecontrol="expiration_date_and_time"]>` `<[render:argument name="variable1" value="value1"]/>` `</render:satellitepage>`

<RENDER.SATELLITEPAGE

PAGENAME="nameOfPageEntry"

[CACHECONTROL="expiration_date_and_time"]

[ARGS_var1="value1"]/>

<render:satellitepage

pagename="nameOfPageEntry"

[cachecontrol="expiration_date_and_time"]>

<[render:argument name="variable1" value="value1"]/>

</render:satellitepage>

RENDER.SATELLITEPAGE requests a WebCenter Sites pagelet and caches that pagelet in both WebCenter Sites and Satellite Server, if the pagelet is not already in cache. If you wish to call a page or pagelet without caching it individually, use the RENDER.CALLELEMENT tag. The RENDER.SATELLITEPAGE tag has a stacked scope, so the only variables available to the page are ones that you explicitly pass in.

RENDER.CALLELEMENT (XML) render:callelement (JSP)

RENDER.CALLELEMENT (XML)	render:callelement (JSP)
`<RENDER.CALLELEMENT` `ELEMENTNAME="nameOfElement"` `[ARGS_var1="value"]/>`	`<ics:callelement element="element name">` `<ics:argument name="argument name" value="arg value"/>` `</ics:callelement>`

<RENDER.CALLELEMENT

ELEMENTNAME="nameOfElement"

[ARGS_var1="value"]/>

<ics:callelement element="element name">

<ics:argument name="argument name" value="arg value"/>

</ics:callelement>

RENDER.CALLELEMENT is similar to the RENDER.SATELLITEPAGE tag in that both tags call other WebCenter Sites code, either in an element or in a page. However, code called by RENDER.CALLELEMENT does not get cached as an individual page or pagelet on Satellite Server.

Use RENDER.CALLELEMENT to process the content of an element that you wrote for the WebCenter Sites Content Applications and you want the scope of that element to be stacked. The element must exist in the ElementCatalog.

4.5.4 Tags That Create URLs

RENDER.GETPAGEURL (XML) render:getpageurl (JSP)

RENDER.GETPAGEURL (XML)	render:getpageurl (JSP)
`<RENDER.GETPAGEURL` `OUTSTR="myURL"` `PAGENAME="SiteCatalogPageEntry"` `cid="IDofAsset"` `[p="IDofParentPage"]` `[c="AssetType"]` `[ADDSESSION="true"]` `[DYNAMIC="true"]` `[PACKEDARGS="stringFromPACKARGStag"]` `[ARGS_xxx="y"]/>`	`<render:getpageurl` `outstr="myURL"` `pagename="SiteCatalogPageEntry"` `cid="IDofAsset"` `[p="IDofParentPage"]` `[c="AssetType"]` `[addsession="true"]` `[dynamic="true"]` `[packedargs="stringFromPACKARGStag"]>` `<[render:argument name="xxx" value="yyy"]/>` `</render:getpageurl>`

<RENDER.GETPAGEURL

OUTSTR="myURL"

PAGENAME="SiteCatalogPageEntry"

cid="IDofAsset"

[p="IDofParentPage"]

[c="AssetType"]

[ADDSESSION="true"]

[DYNAMIC="true"]

[PACKEDARGS="stringFromPACKARGStag"]

[ARGS_xxx="y"]/>

<render:getpageurl

outstr="myURL"

pagename="SiteCatalogPageEntry"

cid="IDofAsset"

[p="IDofParentPage"]

[c="AssetType"]

[addsession="true"]

[dynamic="true"]

[packedargs="stringFromPACKARGStag"]>

<[render:argument name="xxx" value="yyy"]/>

</render:getpageurl>

This tag creates a URL for an asset, processing the arguments passed to it into a URL-encoded string and returning it as the variable specified by the OUTSTR parameter. If rendermode is set to export, the tag creates a file name for a static HTML file (unless you specify that you want a dynamic URL). If rendermode is set to live, the tag creates a dynamic URL.

RENDER.SATELLITEBLOB (XML) render:satelliteblob (JSP)

RENDER.SATELLITEBLOB (XML)	render:satelliteblob (JSP)
`<RENDER.SATELLITEBLOB` `SERVICE="HTMLtagName"` `BLOBTABLE="blobTable"` `BLOBKEY="primaryKeyName"` `BLOBWHERE="primaryKeyValue"` `BLOBCOL="columnName"` `BLOBHEADERNAMEN="headername"` `BLOBHEADERVALUEN="mimetype"` `[ARGS_format1="5"]` `[CACHECONTROL="expirationDateAndTime"]/>`	`<render:satelliteblob` `service="HTMLtagName"` `blobtable="blobTable"` `blobkey="primaryKeyName"` `blobwhere="primaryKeyValue"` `blobcol="columnName"` `blobheadernameN="headername"` `blobheadervalueN="mimetype"` `[cachecontrol="expirationDateAndTime"]>` `<[render:argument name="format1" value="5"]/>` `</render:satelliteblob>`

<RENDER.SATELLITEBLOB

SERVICE="HTMLtagName"

BLOBTABLE="blobTable"

BLOBKEY="primaryKeyName"

BLOBWHERE="primaryKeyValue"

BLOBCOL="columnName"

BLOBHEADERNAMEN="headername"

BLOBHEADERVALUEN="mimetype"

[ARGS_format1="5"]

[CACHECONTROL="expirationDateAndTime"]/>

<render:satelliteblob

service="HTMLtagName"

blobtable="blobTable"

blobkey="primaryKeyName"

blobwhere="primaryKeyValue"

blobcol="columnName"

blobheadernameN="headername"

blobheadervalueN="mimetype"

[cachecontrol="expirationDateAndTime"]>

<[render:argument name="format1" value="5"]/>

</render:satelliteblob>

This tag creates an HTML tag with a BlobServer URL for assets that are blobs. For example, imagefile assets from the Burlington Financial sample site are blobs stored in the WebCenter Sites database which means they must be served by the BlobServer servlet. This tag creates an HTML tag that instructs a browser how to find and format the specified blob.

4.5.5 Tags That Control Caching

The following tag lets you control whether or not the output of the current template or element gets cached.

ics.disablecache (XML)	ics:disablecache (JSP)
`<ics.disablecache/>`	`<ics:disablecache/>`

Use ics.disable cache in conjunction with if/then statements that check for error conditions; if an error is present, the resulting rendered page will not be cached. For complete information and code samples for the ics.disablecache tag, see Section 28.8.2, "Ensuring that Incorrect Pages Are Not Cached."

4.5.6 Tags That Set Cookies

The following tag sets cookies in WebCenter Sites.

satellite.cookie (XML) satellite:cookie (JSP)

satellite.cookie (XML)	satellite:cookie (JSP)
`<satellite.cookie` `name="cookie_name"` `value="cookie_value"` `timeout="timeout"` `secure="true\|false"` `url="URL"` `[domain="domain"]/>`	`<satellite:cookie>` `<satellite:parameter name='name' value='cookie_name'/>` `<satellite:parameter name='value' value='cookie_value'/>` `<satellite:parameter name='timeout' value='cookie_timeout'/>` `<satellite:parameter name='secure' value='true\|false'/>` `<satellite:parameter name='url' value='url'>` `</satellite:cookie>`

<satellite.cookie

name="cookie_name"

value="cookie_value"

timeout="timeout"

secure="true|false"

url="URL"

[domain="domain"]/>

<satellite:cookie>

<satellite:parameter name='name' value='cookie_name'/>

<satellite:parameter name='value' value='cookie_value'/>

<satellite:parameter name='timeout' value='cookie_timeout'/>

<satellite:parameter name='secure' value='true|false'/>

<satellite:parameter name='url' value='url'>

</satellite:cookie>

satellite.cookie sets a cookie on the user's browser. This tag is the only way to set cookies in either XML or JSP.

4.5.7 Programming Construct Tags

The following tags allow you to use basic programming constructs.

IF/THEN/ELSE (XML) ics:if/ics:then/ics:else (JSP)

IF/THEN/ELSE (XML)	ics:if/ics:then/ics:else (JSP)
`<IF COND="LOGICAL_EXPRESSION">` `<THEN>` `tags and/or text` `</THEN>` `<ELSE>` `tags and/or text` `</ELSE>` `</IF>`	`<ics:if condition="logical expression">` `<ics:then>` `tags and/or text` `</ics:then>` `<ics:else>` `tags and/or text` `</ics:else>` `</ics:if>`

<IF COND="LOGICAL_EXPRESSION">

<THEN>

tags and/or text

</THEN>

<ELSE>

tags and/or text

</ELSE>

</IF>

<ics:if condition="logical expression">

<ics:then>

tags and/or text

</ics:then>

<ics:else>

tags and/or text

</ics:else>

</ics:if>

IF, THEN, ELSE determine conditions. You typically use these tags to determine the value of a variable.

LOOP (XML) ics:listloop (JSP)

LOOP (XML)	ics:listloop (JSP)
`<LOOP [FROM="START"]` `[COUNT="LOOP_TIMES"]` `[LIST="LIST_NAME"]` `[UNTIL="END"]>` `...` `</LOOP>`	`<ics:listloop` `listname="some list"` `[maxrows="number of loops"]` `[startrow="start row"]` `[endrow="end row"]/>`

<LOOP [FROM="START"]

[COUNT="LOOP_TIMES"]

[LIST="LIST_NAME"]

[UNTIL="END"]>

...

</LOOP>

<ics:listloop

listname="some list"

[maxrows="number of loops"]

[startrow="start row"]

[endrow="end row"]/>

LOOP and ics:listloop iterate through items in a list. Remember that excess code within these tags affects the performance of the template. Whenever possible, keep statements that do not need to be repeated outside the LOOP tags.

4.5.8 Tags That Manage Compositional and Approval Dependencies

For complete information about compositional and approval dependencies, see Section 28.1, "About Dependencies."

RENDER.LOGDEP (XML) render:logdep (JSP)

RENDER.LOGDEP (XML)	render:logdep (JSP)
`<RENDER.LOGDEP ASSET="asset name"` `CID="asset id"` `C="asset type"/>`	`<render:logdep asset="asset name"` `cid="asset id"` `c="asset type"/>`

<RENDER.LOGDEP ASSET="asset name"

CID="asset id"

C="asset type"/>

<render:logdep asset="asset name"

cid="asset id"

c="asset type"/>

Use the RENDER.LOGDEP tag if your template uses tags that obtain an asset's data without loading the asset, such as ASSET.CHILDREN.

RENDER.UNKNOWNDEPS (XML)	render.unknowndeps (JSP)
`<RENDER.UNKNOWNDEPS/>`	`<render:unknowndeps/>`

Use the RENDER.UNKNOWNDEPS tag if a page has a query or some other indeterminate connection to its dependent assets. This tag causes the page or pagelet to be regenerated at every publish because the dependencies cannot be determined. This means that you should use this tag sparingly.

RENDER.FILTER (XML) render:filter (JSP)

RENDER.FILTER (XML)	render:filter (JSP)
`<RENDER.FILTER LIST="list name"` `LISTVARNAME="output list name"` `LISTDICOL="assetID column"` `[LISTTYPECOL="assettype column"]` `[TYPE="asset type"]` `[ID="asset id"]` `[VARNAME="output variable"/>`	`<render:filter list="list name"` `listvarname="output list name"` `listidcol="assetID column"` `[listtypecol="assettype column"]` `[type="asset type"]` `[id="asset id"]` `[varname="output variable"/>`

<RENDER.FILTER LIST="list name"

LISTVARNAME="output list name"

LISTDICOL="assetID column"

[LISTTYPECOL="assettype column"]

[TYPE="asset type"]

[ID="asset id"]

[VARNAME="output variable"/>

<render:filter list="list name"

listvarname="output list name"

listidcol="assetID column"

[listtypecol="assettype column"]

[type="asset type"]

[id="asset id"]

[varname="output variable"/>

Use the RENDER.FILTER tag to check for unapproved assets and prevent them from being included in the exported page. This tag filters either a single asset or list of assets by comparing each asset ID against the assetid column in the ApprovedAssets database table. During export rendering, it filters what can be published based on approval status. During live rendering, RENDER.FILTER does nothing. Use this tag whenever you have a database query for a list of assets in your template.

4.5.9 Tags That Retrieve Information About Basic Assets

ASSET.LOAD (XML) asset:load (JSP)

ASSET.LOAD (XML)	asset:load (JSP)
`<ASSET.LOAD` `NAME="assetName"` `TYPE="assetType"` `OBJECTID="object.id"` `[FIELD="fieldName"]` `[VALUE="fieldValue"]` `[DEPTYPE="EXACT, EXISTS,` `or GREATER"]/>`	`<asset:load` `name="assetName"` `type="assetType"` `objectid="object.id"` `[field="fieldName"]` `[value="fieldValue"]` `[deptype="exact,exists,or greater"]/>`

<ASSET.LOAD

NAME="assetName"

TYPE="assetType"

OBJECTID="object.id"

[FIELD="fieldName"]

[VALUE="fieldValue"]

[DEPTYPE="EXACT, EXISTS,

or GREATER"]/>

<asset:load

name="assetName"

type="assetType"

objectid="object.id"

[field="fieldName"]

[value="fieldValue"]

[deptype="exact,exists,or greater"]/>

This tag queries the database for a specific asset and then loads the asset's data into memory as an object. The object is then available to your elements until either the session is flushed or the name that is assigned to the object is overwritten.

The scope of the object names that you assign to loaded assets is global. Be sure to use unique object names so that your elements do not overwrite objects by mistake. A convenient naming convention is to include the element name in the asset name. For an example of creating unique asset object names by using this convention, see Section 29.1, "Example 1: Basic Modular Design."

ASSET.LOAD automatically logs a dependency between the template or element that uses the tag and the asset data that the tag retrieves.

ASSET.SCATTER (XML) asset:scatter (JSP)

ASSET.SCATTER (XML)	asset:scatter (JSP)
`<ASSET.SCATTER` `NAME="assetName"` `PREFIX="variablePrefix"/>`	`<asset:scatter` `name="assetName"` `prefix="variablePrefix"/>`

<ASSET.SCATTER

NAME="assetName"

PREFIX="variablePrefix"/>

<asset:scatter

name="assetName"

prefix="variablePrefix"/>

This tag retrieves values from all of the fields of an asset object that has already been retrieved (loaded) with the ASSET.LOAD tag and turns those values into WebCenter Sites variables. For example, if you want to display the headline, byline, description, and so on of an article online, you can use this tag to retrieve all of those values with one call.

ASSET.GET (XML) asset:get (JSP)

ASSET.GET (XML)	asset:get (JSP)
`<ASSET.GET` `NAME="assetName"` `FIELD="fieldName"` `[OUTPUT="outputVariable"]/>`	`<asset:get` `name="assetName"` `field="fieldName"` `[output="outputVariable"]/>`

<ASSET.GET

NAME="assetName"

FIELD="fieldName"

[OUTPUT="outputVariable"]/>

<asset:get

name="assetName"

field="fieldName"

[output="outputVariable"]/>

This tag retrieves the value from one specified field of an asset object that has already been retrieved (loaded) with the ASSET.LOAD tag and turns that value into a WebCenter Sites variable. For example, if you need only the headline of an article to use in a link to that article, you can use this tag to retrieve that one value.

ASSET.CHILDREN (XML) asset:children (JSP)

ASSET.CHILDREN (XML)	asset:children (JSP)
`<ASSET.CHILDREN` `NAME="assetName"` `LIST= "listName"` `[CODE= "NameOfAssociation"]` `[OBJECTTYPE= "typeOfObject"]` `[OBJECTID="objectID"]` `[ORDER="nrank"]/>`	`<asset:children` `name="assetName"` `list="listName"` `[code="NameOfAssociation"]` `[objectype="typeOfObject"]` `[objectid="objectID"]` `[order="nrank"]/>`

<ASSET.CHILDREN

NAME="assetName"

LIST= "listName"

[CODE= "NameOfAssociation"]

[OBJECTTYPE= "typeOfObject"]

[OBJECTID="objectID"]

[ORDER="nrank"]/>

<asset:children

name="assetName"

list="listName"

[code="NameOfAssociation"]

[objectype="typeOfObject"]

[objectid="objectID"]

[order="nrank"]/>

This tag queries the AssetRelationTree table and then builds a list of assets that are children of the asset that you specified. You use this tag to retrieve assets in a collection, to retrieve the image assets associated with article assets, and so on.

Use the RENDER.LOGDEP tag in conjunction with ASSET.CHILDREN to log a dependency between the element or template in which it appears and the content that ASSET.CHILDREN retrieves.

4.5.9.1 Performance Notes About the Asset Tags

ASSET.LOAD and ASSET.CHILDREN are database queries, so you should use them only when necessary, because queries to the database take time. For example, you might want to include error checking code after an ASSET.LOAD tag and before its subsequent ASSET.CHILDREN tag that determines whether an asset was returned by the ASSET.LOAD. If there is no asset, there is no reason to invoke the ASSET.CHILDREN tag.
An ASSET.SCATTER call takes much longer than a single ASSET.GET call.

4.5.10 Tags That Create Assetsets (Flex Assets)

Assetset tags specify a set of one or more flex assets that you want to retrieve from the database.

You can retrieve the following information from an assetset:

The values for one attribute for each of the flex assets in the assetset
The values for multiple attributes for each of the flex assets in the assetset
A list of the flex assets in the assetset
A count of the flex assets in the assetset
A list of unique attribute values for an attribute for all flex assets in the assetset
A count of unique attribute values for an attribute for all flex assets in the assetset

The following tables describe the assetset tags that you will use most frequently.

ASSETSET.SETASSET (XML) assetset:setasset (JSP)

ASSETSET.SETASSET (XML)	assetset:setasset (JSP)
`<ASSETSET.SETASSET` `NAME="assetsetname"` `TYPE="assettype"` `ID="assetid"` `[LOCALE="localeobject"]` `[DEPTYPE="exact\|exists\|none"]` `/>`	`<assetset:setasset name="assetsetname" type="assettype" id="assetid" [locale="localeobject"] [deptype="exact\|exists\|none"]/>`

<ASSETSET.SETASSET

NAME="assetsetname"

TYPE="assettype"

ID="assetid"

[LOCALE="localeobject"]

[DEPTYPE="exact|exists|none"]

/>

<assetset:setasset name="assetsetname" type="assettype" id="assetid" [locale="localeobject"] [deptype="exact|exists|none"]/>

ASSETSET.SETASSET builds an asset set from a single asset that you specify and defines a compositional dependency between the template or element that it appears in and the content that it retrieves.

ASSETSET.SETSEARCHEDASSETS (XML) assetset:setsearchedassets (JSP)

ASSETSET.SETSEARCHEDASSETS (XML)	assetset:setsearchedassets (JSP)
`<ASSETSET.SETSEARCHEDASSETS` `NAME="assetsetname"` `[ASSETTYPES="assettype"] [CONSTRAINT="searchstateobject"] [LOCALE="localeobject"] [SITE="siteidentifier"] [DEPTYPE="exact\|exists\|none"]/>`	`<assetset:setsearchedassets` `name="assetsetname"` `[assettypes="assettype"]` `[constraint="searchstateobject"]` `[locale="localeobject"]` `[site="siteidentifier"]` `[deptype="exact\|exists\|none"]/>`

<ASSETSET.SETSEARCHEDASSETS

NAME="assetsetname"

[ASSETTYPES="assettype"] [CONSTRAINT="searchstateobject"] [LOCALE="localeobject"] [SITE="siteidentifier"] [DEPTYPE="exact|exists|none"]/>

<assetset:setsearchedassets

name="assetsetname"

[assettypes="assettype"]

[constraint="searchstateobject"]

[locale="localeobject"]

[site="siteidentifier"]

[deptype="exact|exists|none"]/>

ASSETSET.SETSEARCHEDASSETS creates an assetset object which represents all assets of specific types narrowed by specified search criteria (represented by the searchstate object that you name in the constraint parameter).

This tag also defines a compositional dependency between the template or element in which it appears and the each asset in the set.

ASSETSET.GETMULTIPLEVALUES (XML) assetset:getmultiplevalues (JSP)

ASSETSET.GETMULTIPLEVALUES (XML)	assetset:getmultiplevalues (JSP)
`<ASSETSET.GETMULTIPLEVALUES` `NAME="assetsetname"` `LIST="listname"` `[BYASSET="true\|false"]` `PREFIX="prefix"/>`	`<assetset:getmultiplevalues` `name="assetsetname"` `list="listname"` `[byasset="true\|false"]` `prefix="prefix"/>`

<ASSETSET.GETMULTIPLEVALUES

NAME="assetsetname"

LIST="listname"

[BYASSET="true|false"]

PREFIX="prefix"/>

<assetset:getmultiplevalues

name="assetsetname"

list="listname"

[byasset="true|false"]

prefix="prefix"/>

ASSETSET.GETMULTIPLEVALUES scatters attribute values from several attributes (and potentially more than one asset) into several specified lists.

It is recommended that you use ASSETSET.GETMULTIPLEVALUES when the goal is to display a fixed-format table of assets, or to obtain many attributes of a single asset (such as for a product detail page).

ASSETSET.GETMULTIPLEVALUES has the following limitations:

Only non-foreign attributes can be scattered.

Text-type attributes cannot be scattered.

ASSETSET.GETATTRIBUTEVALUES (XML) assetset:getattributevalues (JSP)

ASSETSET.GETATTRIBUTEVALUES (XML)	assetset:getattributevalues (JSP)
`<ASSETSET.GETATTRIBUTEVALUES` `NAME="assetsetname"` `ATTRIBUTE="attribname"` `[TYPENAME="assettypename"]` `LISTVARNAME="varname"` `[ORDERING="ascending\|descending"]/>`	`<assetset:getattributevalues` `name="assetsetname"` `attribute="attribname"` `[typename="assettypename"]` `listvarname="varname"` `[ordering="ascending\|descending"]/>`

<ASSETSET.GETATTRIBUTEVALUES

NAME="assetsetname"

ATTRIBUTE="attribname"

[TYPENAME="assettypename"]

LISTVARNAME="varname"

[ORDERING="ascending|descending"]/>

<assetset:getattributevalues

name="assetsetname"

attribute="attribname"

[typename="assettypename"]

listvarname="varname"

[ordering="ascending|descending"]/>

ASSETSET.GETATTRIBUTEVALUES gets the list of values for a specified attribute of the assets represented by an assetset.

ASSETSET.GETASSETLIST (XML) assetset:getassetlist (JSP)

ASSETSET.GETASSETLIST (XML)	assetset:getassetlist (JSP)
`<ASSETSET.GETASSETLIST` `NAME="assetsetname"` `[LIST="attriblist"]` `[MAXCOUNT="rowcount"]` `[METHOD="random\|highest"]` `LISTVARNAME="varname/>`	`<assetset:getassetlist` `name="assetsetname"` `[list="attriblist"]` `[maxcount="rowcount"]` `[method="random\|highest"]` `listvarname="varname"/>`

<ASSETSET.GETASSETLIST

NAME="assetsetname"

[LIST="attriblist"]

[MAXCOUNT="rowcount"]

[METHOD="random|highest"]

LISTVARNAME="varname/>

<assetset:getassetlist

name="assetsetname"

[list="attriblist"]

[maxcount="rowcount"]

[method="random|highest"]

listvarname="varname"/>

ASSETSET.GETASSETLIST retrieves an ordered list of assets, given optional sort criteria. The resulting list has two columns, assetid and assettype, that are sorted by the criteria that you specify.

4.5.11 Tags That Create Searchstates (Flex Assets)

Searchstate tags assemble criteria that filter the assets that you retrieve using the assetset tags.

You build a searchstate by adding or removing constraints to narrow or broaden the list of flex assets that are described by the searchstate.

The following tables describe the searchstate tags that you will use most frequently.

SEARCHSTATE.CREATE (XML) searchstate:create (JSP)

SEARCHSTATE.CREATE (XML)	searchstate:create (JSP)
`<SEARCHSTATE.CREATE` `NAME="ssname"` `[OP="and\|or"]/>`	`<searchstate:create` `name="ssname"` `[op="and\|or"]/>`

<SEARCHSTATE.CREATE

NAME="ssname"

[OP="and|or"]/>

<searchstate:create

name="ssname"

[op="and|or"]/>

SEARCHSTATE.CREATE builds an empty searchstate object. You must begin constructing a searchstate with this tag.

SEARCHSTATE.ADDSTANDARDCONSTRAINT (XML) searchstate:addstandardconstraint (JSP)

SEARCHSTATE.ADDSTANDARDCONSTRAINT (XML)	searchstate:addstandardconstraint (JSP)
`<SEARCHSTATE.ADDSTANDARDCONSTRAINT` `NAME="ssname"` `[BUCKET="bucketname"]` `[TYPENAME="assettype"]` `ATTRIBUTE="attribname"` `[LIST="listname"]` `[IMMEDIATEONLY="true\|false"]` `[CASEINSENSITIVE="true\|false"]/>`	`<searchstate:addstandardconstraint` `name="ssname"` `[bucket="bucketname"]` `[typename="assettype"]` `attribute="attribname"` `[list="listname"]` `[immediateonly="true\|false"]` `[caseinsensitive="true\|false"]/>`

<SEARCHSTATE.ADDSTANDARDCONSTRAINT

NAME="ssname"

[BUCKET="bucketname"]

[TYPENAME="assettype"]

ATTRIBUTE="attribname"

[LIST="listname"]

[IMMEDIATEONLY="true|false"]

[CASEINSENSITIVE="true|false"]/>

<searchstate:addstandardconstraint

name="ssname"

[bucket="bucketname"]

[typename="assettype"]

attribute="attribname"

[list="listname"]

[immediateonly="true|false"]

[caseinsensitive="true|false"]/>

SEARCHSTATE.ADDSTANDARDCONSTRAINT adds an attribute name/value constraint into a new or existing searchstate object.

You can constrain the attribute by a list of values that you specify in the list parameter.

SEARCHSTATE.ADDSIMPLESTANDARDCONSTRAINT (XML) searchstate:addsimplestandardconstraint (JSP)

SEARCHSTATE.ADDSIMPLESTANDARDCONSTRAINT (XML)	searchstate:addsimplestandardconstraint (JSP)
`<SEARCHSTATE.ADDSIMPLESTANDARDCONSTRAINT` `NAME="ssname"` `[BUCKET="bucketname"]` `[TYPENAME="assettype"]` `ATTRIBUTE="attribname"` `VALUE="value"` `[IMMEDIATEONLY="true\|false"]/>`	`<searchstate:addsimplestandardconstraint` `name="ssname"` `[bucket="bucketname"]` `[typename="assettype"]` `attribute="attribname"` `value="value"` `[immediateonly="value"]/>`

<SEARCHSTATE.ADDSIMPLESTANDARDCONSTRAINT

NAME="ssname"

[BUCKET="bucketname"]

[TYPENAME="assettype"]

ATTRIBUTE="attribname"

VALUE="value"

[IMMEDIATEONLY="true|false"]/>

<searchstate:addsimplestandardconstraint

name="ssname"

[bucket="bucketname"]

[typename="assettype"]

attribute="attribname"

value="value"

[immediateonly="value"]/>

SEARCHSTATE.ADDSIMPLESTANDARDCONSTRAINT adds an attribute name/single value constraint to an existing searchstate.

This tag is the simple version of SEARCHSTATE.ADDSTANDARDCONSTRAINT. The object referred to by NAME is updated to reflect the new constraint. If the attribute name is already in the searchstate, then the new constraint replaces the old constraint.

SEARCHSTATE.ADDRANGECONSTRAINT (XML) searchstate:addrangeconstraint (JSP)

SEARCHSTATE.ADDRANGECONSTRAINT (XML)	searchstate:addrangeconstraint (JSP)
`<SEARCHSTATE.ADDRANGECONSTRAINT` `NAME="ssname"` `[BUCKET="bucketname"]` `[TYPENAME="assettype"]` `ATTRIBUTE="attribname"` `LOWER="lowrange"` `UPPER="uprange"` `[CASEINSENSITIVE="true\|false"]/>`	`<searchstate:addrangeconstraint` `name="ssname"` `[bucket="bucketname"]` `[typename="assettype"]` `attribute="attribname"` `lower="lowrange"` `upper="uprange"` `[caseinsensitive="true\|false"]` `/>`

<SEARCHSTATE.ADDRANGECONSTRAINT

NAME="ssname"

[BUCKET="bucketname"]

[TYPENAME="assettype"]

ATTRIBUTE="attribname"

LOWER="lowrange"

UPPER="uprange"

[CASEINSENSITIVE="true|false"]/>

<searchstate:addrangeconstraint

name="ssname"

[bucket="bucketname"]

[typename="assettype"]

attribute="attribname"

lower="lowrange"

upper="uprange"

[caseinsensitive="true|false"]

/>

SEARCHSTATE.ADDRANGECONSTRAINT adds a range constraint for a specific attribute name.

SEARCHSTATE.ADDRICHTEXTCONSTRAINT (XML) searchstate:addrichtextconstraint (JSP)

SEARCHSTATE.ADDRICHTEXTCONSTRAINT (XML)	searchstate:addrichtextconstraint (JSP)
`<SEARCHSTATE.ADDRICHTEXTCONSTRAINT` `NAME="ssname"` `[BUCKET="bucketname"]` `[TYPENAME="assettype"]` `ATTRIBUTE="attribname"` `VALUE="criteria"` `[PARSER="parsername"]` `CONFIDENCE="minlevel"` `[MAXCOUNT="number"] />`	`<searchstate:addrangeconstraint` `name="ssname"` `[bucket="bucketname"]` `[typename="assettype"]` `attribute="attribname"` `lower="lowrange"` `upper="uprange"` `[caseinsensitive="true\|false"]` `/>`

<SEARCHSTATE.ADDRICHTEXTCONSTRAINT

NAME="ssname"

[BUCKET="bucketname"]

[TYPENAME="assettype"]

ATTRIBUTE="attribname"

VALUE="criteria"

[PARSER="parsername"]

CONFIDENCE="minlevel"

[MAXCOUNT="number"] />

<searchstate:addrangeconstraint

name="ssname"

[bucket="bucketname"]

[typename="assettype"]

attribute="attribname"

lower="lowrange"

upper="uprange"

[caseinsensitive="true|false"]

/>

SEARCHSTATE.ADDRICHTEXTCONSTRAINT adds an attribute name and rich-text expression to the list of rich-text constraints in the searchstate.

SEARCHSTATE.TOSTRING (XML) searchstate:tostring (JSP)

SEARCHSTATE.TOSTRING (XML)	searchstate:tostring (JSP)
`<SEARCHSTATE.TOSTRING` `NAME="objname"` `VARNAME="varname"/>`	`<searchstate:tostring` `name="objname"` `varname="varname"/>`

<SEARCHSTATE.TOSTRING

NAME="objname"

VARNAME="varname"/>

<searchstate:tostring

name="objname"

varname="varname"/>

SEARCHSTATE.TOSTRING converts a searchstate object into its string representation that is suitable for various uses, such as saving in a session variable or packing into a URL.

SEARCHSTATE.FROMSTRING (XML) searchstate:fromstring (JSP)

SEARCHSTATE.FROMSTRING (XML)	searchstate:fromstring (JSP)
`<SEARCHSTATE.FROMSTRING` `NAME="objname"` `VALUE="stringval"/>`	`<searchstate:fromstring` `name="objname"` `value="stringval"/>`

<SEARCHSTATE.FROMSTRING

NAME="objname"

VALUE="stringval"/>

<searchstate:fromstring

name="objname"

value="stringval"/>

SEARCHSTATE.FROMSTRING provides the ability for a searchstate object to be initialized from its string representation. You must create an empty searchstate using the SEARCHSTATE.CREATE tag before you can use this tag.

4.6 Variables

WebCenter Sites supports the following kinds of variables:

Regular variables, which last for the duration of the current template or element, unless you explicitly remove them. Regular variables have a global scope.
Session variables, which last for the duration of the current session.

WebCenter Sites provides several standard variables whose names are reserved. You can retrieve the values of these variables, but you cannot use their names for other variables that you create.

This section describes the following topics:

Section 4.6.1, "Reserved Variables"
Section 4.6.2, "Setting Regular Variables"
Section 4.6.3, "Setting Session Variables"
Section 4.6.4, "Working With Variables"
Section 4.6.5, "Variables and Precedence"
Section 4.6.6, "Best Practices with Variables"

4.6.1 Reserved Variables

The following table defines the standard WebCenter Sites variables. Unless otherwise noted, these are regular variables:

Table 4-8 Reserved Variables

Variable	Definition
`tablename`	A variable that is set to a tablename before the `execsql` tags can be run.
`pagename`	The name of the WebCenter Sites page being invoked.
`ftcmd`	A variable used in calls to CatalogManager.
`username`	A session variable that contains the name of the user who is currently logged in to the current session.
`password`	A session variable that contains the password of the user who is currently logged in to the current session.
`authusername`	A variable that you can set to the username of a user who you want to log in to WebCenter Sites. This can be sent to WebCenter Sites via a URL.
`authpassword`	A variable that you can set to the password of a user who you want to log in to WebCenter Sites. This can be sent to WebCenter Sites via a URL.
`currentACL`	A session variable that contains the ACLs that the current user belongs to.
`errno`	Error numbers reported by WebCenter Sites tags.
`context`	Reserved for future use in the `render:calltemplate` tag. For more information, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.
`site`	The full name of the site, as stored in the `name` column of the `Publication` table. The `site` variable is set as a `resarg` in all of the Template and Site Entry assets. The site owns the Template and SiteEntry assets that you create within the site.
`sitepfx`	The site prefix (and short name of the site), as stored in the `cs_prefix` column of the `Publication` table.
`ft_ss`	An internal variable that is automatically set by WebCenter Sites to support communication with Satellite Server. When `ft_ss` is set to `true`, WebCenter Sites infers that a request is from Satellite Server.
`c`	The asset type that a template formats. WebCenter Sites sets this variable by default when you save the Template asset.
`cid`	The ID of the asset being rendered or formatted by a template.
`ct`	The value of a child template, if there is one. For a thorough explanation of child templates, see Section 29.3, "Example 3: Using the ct Variable."
`p`	The ID of an asset's parent page, if there is one.
`rendermode`	Specifies whether a page entry is to be delivered live, exported, or previewed. By default, `rendermode` is `live`. When you use Export to Disk, or the Preview function, WebCenter Sites automatically overrides the value of this variable with `export` or `preview`. This value is used internally and must not be modified.
`seid`	The ID of a SiteEntry asset.
`tid`	The ID of a Template asset.
`eid`	The ID of a CSElement asset, `eid` is available to the CSElement's root element.

4.6.2 Setting Regular Variables

Most of the variables that you will use while coding WebCenter Sites templates and elements are regular variables. Regular variables last for the duration of the current template or element, unless they are explicitly deleted using WebCenter Sites tags.

4.6.2.1 Setting Variables with SETVAR

Inside a WebCenter Sites element, you can call the SETVAR XML or JSP tags to create a variable and establish its initial value. For example, the following SETVAR XML tag creates a variable named dog and sets its value to fido:

<SETVAR NAME="dog" VALUE="fido"/>

If the variable already exists, SETVAR resets its value to the new value. For example, the following command resets the value of dog to mocha:

<SETVAR NAME="dog" VALUE="mocha"/>

4.6.2.2 Setting Variables via a URL

WebCenter Sites creates a page when a browser goes to a URL managed by a WebCenter Sites application. Each page is associated with a particular URL. Imagine, for example, a page associated with a URL having the following format:

http://host:port/servlet/ContentServer?pagename=Experiment/Hello

At the end of every URL, you can set one or more variables. For example, the following URL creates three variables in the Hello page:

http://host:port/servlet/ContentServer?pagename=Experiment/Hello&dog=fido&cat=fifi

The preceding URL creates the following variables available to Hello:

A variable named pagename whose value is Experiment/Hello
A variable named dog whose initial value is fido.
A variable named cat whose initial value is fifi.

4.6.2.3 Setting Default Variables for Elements and Templates with Oracle WebCenter Sites Explorer

You can use Oracle WebCenter Sites Explorer to create default variables in a page by placing the variables in either of the following fields:

resargs1 or resargs2 fields of the SiteCatalog database table
resdetails1 or resdetails2 fields of the ElementCatalog database table

For example, you can use Oracle WebCenter Sites Explorer to access the SiteCatalog table, and then create variables dog and cat by placing name/value pairs in the resargs1 and resargs2 fields:

Description of the illustration l_addingvariables.gif

Note that we placed one name/value pair in resargs1 and another in resargs2. Alternatively, we could have put both name/value pairs in resargs1, as shown in the following diagram:

Description of the illustration l_doubleresargsvalue.gif

You can also set the values of dog and cat in the ElementCatalog table by putting name/value pairs in the resdetails1 and resdetails2 fields:

Description of the illustration l_catalogaddvariables.gif

Variables set through the URL or through POST and GET operations take precedence over variables set using the SiteCatalog or ElementCatalog tables. For example, if a URL sets variable dog to rex and the SiteCatalog sets dog to fido, then the resulting value of dog will be rex.

4.6.2.4 Setting Variables Using HTML Forms

In CGI programming, a buyer fills out a form. Then, the browser encodes the buyer's responses as name/value pairs, which get passed to the CGI script.

Although WebCenter Sites does not use traditional CGI programming, a WebCenter Sites element can still display a form. As in traditional programming, the browser encodes the buyer's responses as name/value pairs. However, instead of passing these name/value pairs to a CGI program, the pairs get passed to a different WebCenter Sites page. The receiving WebCenter Sites page can access the name/value pairs as it would access any WebCenter Sites variable.

Cookie names and values are also instantiated as variables. For more information about cookies, see Chapter 9, "Sessions and Cookies"

4.6.3 Setting Session Variables

HTTP is a stateless protocol. To overcome this limitation, WebCenter Sites can maintain state between requests and, thus, keep track of sessions.

A browser connection to the WebCenter Sites system establishes a session. Thereafter, the session is uniquely identified to the system. WebCenter Sites can deliver pages whose content and behavior are based on this unique identity.

When a client first enters your site, a unique session is established. WebCenter Sites associates a default user identity with a new session and maintains that information in session variables. Session variables contain values that are available for the duration of the session. They are saved as part of the user's session and are used to retain the value of a variable across page requests.

In a clustered configuration, the session state is maintained across all cluster members. Session variables should be used carefully, since there is a resource cost that is proportionate to the number and size of session variables used.

Session state is lost under these conditions:

The client exits.
The session has timed out. WebCenter Sites can optionally terminate a session if no requests have been made for some period of time.
The application server has been restarted.

Server resources associated with the session are de-allocated when the following occurs:

The session has been explicitly terminated by the client via a WebCenter Sites tag.
The session has timed out.
The application server has been restarted.

Use the SETSSVAR XML and JSP tags to create a session variable. If the session variable already exists, SETSSVAR resets the variable's value. For example, the following SETSSVAR XML tag sets the session variable profile to the value 10154:

<SETSSVAR NAME="profile" VALUE="10154"/>

4.6.4 Working With Variables

The following sections describe how to work with WebCenter Sites variables.

4.6.4.1 Retrieving a Variable's Value

The syntax you use to read the value of a variable depends on the kind of variable:

Table 4-9 Variables and Syntax

Type of Variable	Syntax	Example
String Variable	`Variables.variable_name`	`Variables.dog`
Counter Variable	`Counters.variable_name`	`Counters.position`
Session Variables	`SessionVariables.variable_name`	`SessionVariables.username`
Property	`CS.Property.property_name`	`cs.use.short.jsp.names`

WebCenter Sites XML provides quite a few methods for accessing list variables.

4.6.4.2 Displaying a Variable's Value

Use the CSVAR XML tag to display the value of any kind of variable, including properties and session variables. Use the ics:getvar JSP tag to view the value of a regular WebCenter Sites variable; or the ics:getssvar JSP tag to display the value of a session variable. For example, if the following code appears in an XML element:

<SETVAR NAME="mood" VALUE="happy"/>
<p>My dog is <CSVAR NAME="Variables.mood"/>.</p>

then the resulting page displays the following text:

My dog is happy.

You can also include literal values as part of the NAME argument to the CSVAR XML tag; for example, the following code will also generate "My dog is happy.", but evaluates more slowly:

<SETVAR NAME="mood" VALUE="happy"/>
<p><CSVAR NAME="My dog is Variables.mood"/>.</p>

4.6.4.3 Assigning One Variable Value to Another Variable

You can assign the value of one variable to another variable. You accomplish this task differently if you are coding with XML than if you are coding with JSP.

JSP

If you are coding with JSP, you cannot use the ics:getvar tag to evaluate the variable value because you cannot nest one JSP tag within another JSP tag. To circumvent this limitation, use the ics.GetVar Java method to substitute variable values, as shown in the following sample code:

<ics:setvar name="myVar" value="Fred"/>
<ics:setvar name="yourVar" value='<%=ics.GetVar("myVar")%>'/>
<ics:getvar name="yourVar"/>

Note:

You must enclose the expression that evaluates the variable value ('<%=icsGetVar("myVar")%>' in the example) in single quotes. Otherwise your JSP element will throw an exception.

XML

The following lines of XML assign the value carambola to a variable named your_favorite:

<SETVAR NAME="my_favorite" VALUE="carambola"/>
<SETVAR NAME="your_favorite" VALUE="Variables.my_favorite"/>

Taking this one step further, you can concatenate two variable values and assign the result to a third variable. For example, the following sets the variable car to the value red rabbit.

<SETVAR NAME="color" VALUE="red"/>
<SETVAR NAME="model" VALUE="rabbit"/>
<SETVAR NAME="car" VALUE="Variables.color Variables.model"/>

4.6.4.4 Using Variables in HTML Tags

You can use XML and JSP variables within traditional HTML tags, although you code differently to accomplish this in XML and JSP.

JSP

If you are coding with JSP, you use the ics:getvar tag or the ics.GetVar Java method to evaluate the variable value.

You can also use the ics.resolvevariables tag to resolve variables that are contained within a string. For example, the following code displays the phrase, "The date is," along with the value of the CS.Date variable:

<ics.resolvevariables name="The date is $(CS.Date)." delimited="true"/>

The delimited parameter indicates that you have used the delimiters $( and ) to explicitly mark the variable or variables that you want to resolve. If you want to use variables to specify a list name and a column in that list, for example, you use the following syntax:

<ics.resolvevariables name="$(Variables.listname).$(Variables.columnname)" delimited="true"/>

If the delimited parameter is set to false, no delimiters are used to set off variables.

XML

You can use XML variables inside HTML tags if you use the appropriate attributes. For example, the following code does not contain the appropriate attributes and, therefore, does not set the background color to red:

<SETVAR NAME="color" VALUE="red"/>
<TABLE bgcolor="Variables.color">
...

To use XML variable values within an HTML tag, you must use the REPLACEALL attribute within that HTML tag. The REPLACEALL attribute tells the system to substitute the current value of this XML variable within this HTML tag. Therefore, the correct way to code the preceding lines is as follows:

<SETVAR NAME="color" VALUE="red"/>
<TABLE bgcolor="Variables.color" REPLACEALL="Variables.color">
...

You can combine multiple variable values within one REPLACEALL attribute. For example, the following HTML TABLE tag uses two XML variables:

<SETVAR NAME="color" VALUE="red"/>
<SETVAR NAME="myborder" VALUE="3"/>
<TABLE bgcolor="Variables.color" border="Variables.myborder"
     REPLACEALL="Variables.color,Variables.myborder">
...

The <REPLACEALL> tag is an alternative to the REPLACEALL attribute. The <REPLACEALL> tag performs substitutions within its domain; for example:

<SETVAR NAME="highlight" VALUE="red"/>
<SETVAR NAME="diminish"  VALUE="gray"/>
<REPLACEALL LIST="Variables.highlight,Variables.diminish">
<TABLE>
  <TR BGCOLOR="Variables.highlight"><TD>Diamonds</TD></TR>
  <TR BGCOLOR="Variables.highlight"><TD>Pearls</TD></TR>
  <TR><TD>Malachite</TD></TR>
  <TR BGCOLOR="Variables.diminish"><TD>Coal</TD></TR>
</TABLE>
</REPLACEALL>

The output of this section is:

Description of g-replaceallresults.gif follows

Description of the illustration g-replaceallresults.gif

The REPLACEALL tag performs a string search and replace, and is, therefore, potentially very slow. Use the REPLACEALL attribute where possible. If you must use the REPLACEALL tag, keep the amount of code you enclose with it as small as possible.

4.6.4.5 Evaluating Variables with IF/THEN/ELSE

WebCenter Sites XML and JSP provides the IF/THEN/ELSE construct available in most computer languages. However, the only conditional operation for variables is to compare two values for equality or inequality. You can't, for example, compare two values to see if one is greater than another. (You can write Java code to do that, however.)

For example, the following code branches depending on the value of a variable named greeting.

<IF COND="Variables.greeting=Hello">
<THEN>
     <p>Welcome.</p>
</THEN>
<ELSE>
     <p>So long.</p>
</ELSE>
</IF>

If greeting is set to Hello, then WebCenter Sites generates the HTML:

<p>Welcome.</p>

If greeting is set to anything other than Hello, WebCenter Sites generates:

<p>So long.</p>

4.6.5 Variables and Precedence

Variables set through a URL or through HTTP GET and POST operations take precedence over variables set with the resargs and resdetails columns in the SiteCatalog and ElementCatalog tables.

4.6.6 Best Practices with Variables

Because all variables are global and the syntax for accessing variables from items in lists and from other sources is the same, good coding practices help you to avoid errors. For example:

Because it is easy to reuse base names in your elements, use prefixes in front of variables to define them uniquely. The recommended syntax to use is: Variables.assettype:fieldname.

For example, Variables.Article:description.

The ASSET.SCATTER tag makes it easy for you to use this syntax through its PREFIX attribute. For more information about this tag, see Chapter 28, "Coding Elements for Templates and CSElements."
If you are going to use the RESOLVEVARIABLES tags to resolve your variables, set the DELIMITED parameter to true and use the delimiters $( and ) to explicitly indicate the variables you want to resolve.
Use debugging to catch naming conflicts. Use the Property Editor to set the com.fatwire.logging.cs property (in the commons-logging.properties file or in log4j.properties, depending on which logging framework you are using). When this property is enabled, WebCenter Sites writes a record of all the variables that are created to the WebCenter Sites log file.

For a list of the error values that WebCenter Sites tags can write to the errno variable, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.

4.7 Other WebCenter Sites Storage Constructs

In addition to regular and session variables, WebCenter Sites supports a number of storage constructs. The following sections describe these constructs and how to use them:

Section 4.7.1, "Built-ins"
Section 4.7.2, "Lists"
Section 4.7.3, "Counters"

4.7.1 Built-ins

WebCenter Sites provides several built-ins, which return values such as the current date.

The general syntax of a built-in is:

CS.builtin

For example, UniqueID is a built-in that generates a unique ID. The following syntax generates or references this built-in variable:

CS.UniqueID

For a list of built-ins in WebCenter Sites, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.

4.7.2 Lists

A list consists of a table of values organized in rows and columns. Use the SETROW or GOTOROW tags to identity the proper row.

The following entities create lists:

The SELECTTO, EXECSQL, CATALOGDEF, STRINGLIST and CALLSQL tags
CatalogManager commands
TreeManager commands
Custom tags

Use the following syntax to refer to a current row's column value:

listname.colname

For example, if a list named cars had a column named color, the value of the current row would be referenced as:

cars.color

4.7.2.1 Looping Through Lists

Use the LOOP XML tag or the ics:listloop JSP tag to iterate through a list. For each row in the list, WebCenter Sites executes the instructions between the loop tags.

For example, consider a table named MyCars containing the following rows:

Table 4-10 Example Table with Rows

id	Model	Color	Year
224	Ford Focus	blue	2001
358	VW Rabbit	red	1998
359	Toyota Corolla	yellow	2000
372	Alpha Romeo Spider	red	1982
401	Porsche 911	red	1984
423	Dodge Voyager	tan	1991

The following XML searches MyCars for red cars. The SELECTTO XML and JSP tags write this information into a list variable named carlist.

<SETVAR NAME="color" VALUE="red"/>
<SELECTTO FROM="MyCars" WHERE="color" WHAT="*" LIST="carlist"/>
Red cars: <BR/>
<OL>
<LOOP LIST="carlist">
    <LI><CSVAR NAME="carlist.model"/> </LI>
</LOOP>
</OL>

The preceding XML generates the following HTML:

Red cars: <BR/>
<OL>
 <LI> VW Rabbit </LI>
 <LI> Alpha Romeo Spider </LI>
 <LI> Porsche 911 </LI>
</OL>

4.7.3 Counters

A counter is an XML variable whose value is an integer. Three tags control counters:

Table 4-11 Counters

Tag	What It Does
SETCOUNTER	Initializes a counter variable
INCCOUNTER	Changes the counter's value by a specified amount
REMOVECOUNTER	Destroys the counter variable

To create a counter, you call SETCOUNTER. To change its value, call INCCOUNTER. For example, consider the following code:

<SETCOUNTER NAME="c" VALUE="10"/>
<INCCOUNTER NAME="c" VALUE="3"/>
<p>Current value is <CSVAR NAME="Counters.c"/></p>

The output of this code is:

Current value is 13

Notice that you reference counter variables using the syntax:

Counters.name

4.8 Values for Special Characters

If you need to use special (non-alphanumeric) characters in your XML or JSP, you will need to use their hexadecimal character representation. For example, the following line specifies a space as part of a variable value:

    <SETVAR NAME="foo" VALUE="foo%20bar"/>

The following are hexadecimal values for special characters that are commonly used in WebCenter Sites:

Table 4-12 Values for Special Characters

Hexadecimal Value	Character
%22	doublequote (")
%20	one space
%3c	less than sign (<)
%3e	greater than sign (>)
%26	ampersand (&)
%09	tab (\t)
%0a	newline (\n)
%0d	carriage return (\r)
%25	percent (%)