You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2007/06/07 20:08:54 UTC
[DAISY] Created: Tags
A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/1391.html
Document ID: 1391
Branch: main
Language: default
Name: Tags
Document Type: Cocoon Document
Created: 6/7/07 6:08:35 PM
Creator (owner): Reinhard Pötz
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 16646 bytes
Content:
<html>
<body>
<p>The JXTemplate Generator tags are defined in the namespace</p>
<pre>http://apache.org/cocoon/templates/jx/1.0
</pre>
<h2>template</h2>
<p>The <tt>template</tt> tag defines a new template:</p>
<pre><jx:template xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">
body
</jx:template>
</pre>
<h2>import</h2>
<p>The <tt>import</tt> tag allows you to include another template within the
current template. The content of the imported template is compiled and will be
executed in place of the <tt>import</tt> tag:</p>
<pre><jx:import uri="URI" [context="Expression"]/>
</pre>
<p>The Cocoon source resolver is used to resolve <tt>uri</tt>. If
<tt>context</tt> is present, then its value is used as the context for
evaluating the imported template, otherwise the current context is used.</p>
<h2>set</h2>
<p>The <tt>set</tt> tag creates a local alias of an object. The <tt>var</tt>
attribute specifies the name of a variable to assign the object to. The
<tt>value</tt> attribute specifies the object (defaults to <tt>body</tt> if not
present):</p>
<pre><jx:set var="Name" [value="Value"]>
[body]
</jx:set>
</pre>
<p>If used within a <tt>macro</tt> definition (see below) variables created by
<tt>set</tt> are only visible within the body of the <tt>macro</tt>.</p>
<p>Jexl Example:</p>
<pre><jx:set var="greeting" value="Hello ${user}"/>
The value of greeting is ${greeting}
</pre>
<p>JXPath Example:</p>
<pre><jx:set var="greeting" value="Hello #{user}"/>
The value of greeting is #{$greeting}
</pre>
<h2>if</h2>
<p>The <tt>if</tt> tag allows the conditional execution of its body according to
value of its <tt>test</tt> attribute:</p>
<pre><jx:if test="Expression">
body
</jx:if>
</pre>
<p>Jexl Example:</p>
<pre><jx:if test="${cart.numberOfItems == 0}">
Your cart is empty
</jx:if>
</pre>
<p>JXPath Example:</p>
<pre><jx:if test="#{cart/numberOfItems = 0}">
Your cart is empty
</jx:if>
</pre>
<h2>choose</h2>
<p>The <tt>choose</tt> tag performs conditional block execution by its embedded
<tt>when</tt> sub tags. It renders the body of the first <tt>when</tt> tag whose
<tt>test</tt> condition evaluates to true. If none of the <tt>test</tt>
conditions of its nested <tt>when</tt> tags evaluate to <tt>true</tt>, then the
body of its <tt>otherwise</tt> tag is evaluated, if present:</p>
<pre><jx:choose>
<jx:when test="Expression">
body
</jx:when>+
<jx:otherwise>
body
</jx:otherwise>?
</jx:choose>
</pre>
<p>Jexl Example:</p>
<pre><jx:choose>
<jx:when test="${!user.loggedIn}">
<jx:set var="label" value="Log in">
</jx:when>
<jx:otherwise>
<jx:set var="label" value="Log out">
</jx:otherwise>
</jx:choose>
</pre>
<p>JXPath Example:</p>
<pre><jx:choose>
<jx:when test="#{not(user/loggedIn)}">
<jx:set var="label" value="Log in">
</jx:when>
<jx:otherwise>
<jx:set var="label" value="Log out">
</jx:otherwise>
</jx:choose>
</pre>
<h2>out</h2>
<p>The <tt>out</tt> tag evaluates an expression and outputs the result of the
evaluation:</p>
<pre><jx:out value="Expression"/>
</pre>
<p>Jexl Example:</p>
<pre><jx:out value="${cart.numberOfItems}">
</pre>
<p>JXPath Example:</p>
<pre><jx:out value="#{cart/numberOfItems}">
</pre>
<h2>forEach</h2>
<p>The <tt>forEach</tt> tag allows you to iterate over a collection of objects:
</p>
<pre><jx:forEach [var="Name"] [varStatus="Name"] [items="Expression"]
[begin="NumExpr"] [end="NumExpr"] [step="NumExpr"]>
body
</jx:forEach>
</pre>
<p>The <tt>items</tt> attribute specifies the list of items to iterate over. The
<tt>var</tt> attribute specifies the name of a variable to hold the current
item. The <tt>begin</tt> attribute specifies the element to start with
(<tt>0</tt> = first item, <tt>1</tt> = second item, ...). If unspecified it
defaults to <tt>0</tt>. The <tt>end</tt> attribute specifies the item to end
with (<tt>0</tt> = first item, <tt>1</tt> = second item, ...). If unspecified it
defaults to the last item in the list. Every <tt>step</tt> items are processed
(defaults to <tt>1</tt> if <tt>step</tt> is absent). Either <tt>items</tt> or
both <tt>begin</tt> and <tt>end</tt> must be present.</p>
<p>An alternate form of <tt>forEach</tt> is supported for convenience when using
XPath (since you can specify the selection criteria for the collection using
XPath itself):</p>
<pre><jx:forEach select="XPathExpression">
body
</jx:forEach>
</pre>
<p>When using XPath expressions within <tt>forEach</tt> the current element is
the context node and can be referenced with: <tt>#{.}</tt></p>
<p>Jexl Example:</p>
<pre><jx:forEach var="item" items="${cart.cartItems}"
begin="${start}" end="${count-start}" step="1">
<td>${item.productId}</td>
</jx:forEach>
</pre>
<p>JXPath Example:</p>
<pre><jx:forEach select="#{cart/cartItems[position() &lt;= $count]}}>
<td>#{./productId}</td>
</jx:forEach>
</pre>
<p>If the <tt>varStatus</tt> attribute is present a variable will be created to
hold information about the current loop status. The variable named by the
<tt>varStatus</tt> attribute will hold a reference to an object with the
following properties:</p>
<table>
<tbody>
<tr>
<th>
<p>Property:</p>
</th>
<th>
<p>Description:</p>
</th>
</tr>
<tr>
<td>
<p>current</p>
</td>
<td>
<p>The item from the collection for the current round of iteration</p>
</td>
</tr>
<tr>
<td>
<p>index</p>
</td>
<td>
<p>The zero-based index for the current round of iteration</p>
</td>
</tr>
<tr>
<td>
<p>count</p>
</td>
<td>
<p>The one-based count for the current round of iteration</p>
</td>
</tr>
<tr>
<td>
<p>first</p>
</td>
<td>
<p>True if this is the first round of iteration</p>
</td>
</tr>
<tr>
<td>
<p>last</p>
</td>
<td>
<p>True if this is the last round of iteration</p>
</td>
</tr>
<tr>
<td>
<p>begin</p>
</td>
<td>
<p>The value of the <tt>begin</tt> attribute</p>
</td>
</tr>
<tr>
<td>
<p>end</p>
</td>
<td>
<p>The value of the <tt>end</tt> attribute</p>
</td>
</tr>
<tr>
<td>
<p>step</p>
</td>
<td>
<p>The value of the <tt>step</tt> attribute</p>
</td>
</tr>
</tbody>
</table>
<p>Jexl Example:</p>
<pre><jx:forEach items="${items}" varStatus="status">
index=${status.index},
count=${status.count},
current=${status.current},
first=${status.first},
last=${status.last},
begin=${status.begin},
end=${status.end}
</jx:forEach>
</pre>
<p>JXPath Example:</p>
<pre><jx:forEach select="#{items}" varStatus="status">
index=#{$status/index},
count=#{$status/count},
current=#{$status/current},
first=#{$status/first},
last=#{$status/last},
begin=#{$status/begin},
end=#{$status/end}
</jx:forEach>
</pre>
<h2>formatNumber</h2>
<p>The <tt>formatNumber</tt> tag is used to display numeric data, including
currencies and percentages, in a locale-specific manner. It determines from the
locale, for example, whether to use a period or a comma for delimiting the
integer and decimal portions of a number. Here is its syntax:</p>
<pre><jx:formatNumber value="Expression"
[type="Type"] [pattern="Expression"]
[currencyCode="Expression"] [currencySymbol="Expression"]
[maxIntegerDigits="Expression"] [minIntegerDigits="Expression"]
[maxFractionDigits="Expression"] [minFractionDigits="Expression"]
[groupingUsed="Expression"]
[var="Name"] [locale="Expression"]>
</pre>
<p>Only the <tt>value</tt> attribute is required. It is used to specify the
numeric value that is to be formatted.</p>
<p>The value of the <tt>type</tt> attribute should be either "number",
"currency", or "percent", and indicates what type of numeric value is being
formatted. The default value for this attribute is "number". The
<tt>pattern</tt> attribute takes precedence over the <tt>type</tt> attribute and
allows more precise formatting of numeric values following the pattern
conventions of the <tt>java.text.DecimalFormat</tt> class.</p>
<p>When the <tt>type</tt> attribute has a value of "currency", the
<tt>currencyCode</tt> attribute can be used to explicitly specify the currency
for the numerical value being displayed. As with language and country codes,
currency codes are governed by an ISO standard. This code is used to determine
the currency symbol to display as part of the formatted value.</p>
<p>Alternatively, you can use the <tt>currencySymbol</tt> attribute to
explicitly specify the currency symbol. Note that as of JDK 1.4 and the
associated introduction of the <tt>java.util.Currency</tt> class, the
<tt>currencyCode</tt> attribute of <tt>formatNumber</tt> takes precedence over
the <tt>currencySymbol</tt> attribute. For earlier versions of the JDK, however,
the <tt>currencySymbol</tt> attribute takes precedence.</p>
<p>The <tt>maxIntegerDigits</tt>, <tt>minIntegerDigits</tt>,
<tt>maxFractionDigits</tt>, and <tt>minFractionDigits</tt> attributes are used
to control the number of significant digits displayed before and after the
decimal point. These attributes require integer values.</p>
<p>The <tt>groupingUsed</tt> attribute takes a <tt>Boolean</tt> value and
controls whether digits before the decimal point are grouped. For example, in
English-language locales, large numbers have their digits grouped by threes,
with each set of three delimited by a comma. Other locales delimit such
groupings with a period or a space. The default value for this attribute is
<tt>true</tt>.</p>
<h2>formatDate</h2>
<p>The <tt>formatDate</tt> tag provides facilities to format Date values:</p>
<pre><jx:formatDate value="Expression" [dateStyle="Style"]
[timeStyle="Style"] [pattern="Expression"] [type="Type"] [var="Name"]
[locale="Expression"]>
</pre>
<p>Only the value attribute is required. Its value should be an instance of the
<tt>java.util.Date</tt> class, specifying the date and/or time data to be
formatted and displayed.</p>
<p>The optional <tt>timeZone</tt> attribute indicates the time zone in which the
date and/or time are to be displayed. If not present, then the JVM's default
time zone is used (that is, the time zone setting specified for the local
operating system).</p>
<p>The <tt>type</tt> attribute indicates which fields of the specified
<tt>Date</tt> instance are to be displayed, and should be either "time", "date",
or "both". The default value for this attribute is "date", so if no
<tt>type</tt> attribute is present, the <tt>formatDate</tt> tag -- true to its
name -- will only display the date information associated with the <tt>Date</tt>
instance, specified using the tag's value attribute.</p>
<p>The <tt>dateStyle</tt> and <tt>timeStyle</tt> attributes indicate how the
date and time information should be formatted, respectively. Valid styles are
"default", "short", "medium", "long", and "full". The default value is,
naturally, "default", indicating that a locale-specific style should be used.
The semantics for the other four style values are as defined by the
java.text.DateFormat class.</p>
<p>Rather than relying on the built-in styles, you can use the pattern attribute
to specify a custom style. When present, the value of the pattern attribute
should be a pattern string following the conventions of the
java.text.SimpleDateFormat class. These patterns are based on replacing
designated characters within the pattern with corresponding date and time
fields. For example, the pattern MM/dd/yyyy indicates that two-digit month and
date values and a four-digit year value should be displayed, separated by
forward slashes.</p>
<p>If the <tt>var</tt> attribute is specified, then a String value containing
the formatted date is assigned to the named variable. Otherwise, the
<tt>formatDate</tt> tag will write out the formatting results.</p>
<h2>macro</h2>
<p>The <tt>macro</tt> tag allows you define a new custom tag.</p>
<pre><jx:macro name="Name" [targetNamespace="Namespace"]>
<jx:parameter name="Name" [optional="Boolean"] [default="Value"]/>*
body
</jx:macro>
</pre>
<p>For example:</p>
<pre><jx:macro name="d">
<tr><td></td></tr>
</jx:macro>
</pre>
<p>The tag being defined in this example is <tt><d></tt> and it can be
used like any other tag:</p>
<pre><d/>
</pre>
<p>However, when this tag is used it will be replaced with a row containing a
single empty data cell.</p>
<p>When such a tag is used, the attributes and content of the tag become
available as variables in the body of the <tt>macro</tt>'s definition, for
example:</p>
<pre><jx:macro name="tablerows">
<jx:parameter name="list"/>
<jx:parameter name="color"/>
<jx:forEach var="item" items="${list}">
<tr><td bgcolor="${color}">${item}</td></tr>
</jx:forEach>
</jx:macro>
</pre>
<p>The <tt>parameter</tt> tags in the macro definition define formal parameters,
which are replaced with the actual attribute values of the tag when it is used.
</p>
<p>Assuming you had this code in your flowscript:</p>
<pre>var greatlakes = ["Superior", "Michigan", "Huron", "Erie", "Ontario"];
sendPage(uri, {greatlakes: greatlakes});</pre>
<p>and a template like this:</p>
<pre><table>
<tablerows list="${greatlakes}" color="blue"/>
</table>
</pre>
<p>When the <tt>tablerows</tt> tag is used in this situation the following
output would be generated:</p>
<pre><table>
<tr><td bgcolor="blue">Superior</td></tr>
<tr><td bgcolor="blue">Michigan</td></tr>
<tr><td bgcolor="blue">Huron</td></tr>
<tr><td bgcolor="blue">Erie</td></tr>
<tr><td bgcolor="blue">Ontario</td></tr>
</table>
</pre>
<h2>evalBody</h2>
<p>Within the body of a macro the <tt>evalBody</tt> tag treats the content of
the macro tag invocation as a <em>JX</em>Template and executes it. For example,
the below macro uses this facility to implement the
<a href="http://java.sun.com/products/jsp/jstl/">JSTL</a> <tt>forTokens</tt>
tag:</p>
<pre><jx:macro name="forTokens">
<jx:parameter name="var"/>
<jx:parameter name="items"/>
<jx:parameter name="delims"/>
<jx:forEach var="${var}"
items="${java.util.StringTokenizer(items, delims)}">
<jx:evalBody/>
</jx:forEach>
</jx:macro>
</pre>
<p>The tag produced by this macro can be used like this:</p>
<pre><forTokens var="letter" items="a,b,c,d,e,f,g" delims=",">
letter = ${letter} <br/>
</forTokens>
</pre>
<p>which would create the following output:</p>
<pre> letter = a <br/>
letter = b <br/>
letter = c <br/>
letter = d <br/>
letter = e <br/>
letter = f <br/>
letter = g <br/>
</pre>
<h2>eval</h2>
<p>The <tt>eval</tt> tag permits dynamic evaluation of custom tags.</p>
<pre><jx:eval select="Expression"/>
</pre>
<p>Within the body of a macro, information about the current invocation is
available via a special variable <tt>macro</tt>. This variable contains the
following properties:</p>
<table>
<tbody>
<tr>
<th>
<p>Property:</p>
</th>
<th>
<p>Description:</p>
</th>
</tr>
<tr>
<td>
<p>arguments</p>
</td>
<td>
<p>A map containing the all of the attributes from the tag invocation</p>
</td>
</tr>
<tr>
<td>
<p>body</p>
</td>
<td>
<p>A reference to the content of the tag invocation</p>
</td>
</tr>
</tbody>
</table>
<p>You can store the value of <tt>body</tt> in another variable and invoke it
later using <tt>jx:eval</tt>. The <tt>select</tt> attribute of <tt>jx:eval</tt>
specifies an expression that must evaluate to a macro invocation. For example:
</p>
<pre><jx:set var="tags" value="${java.util.HashMap()}"/>
<jx:macro name="dynamic-tag">
<jx:parameter name="id"/>
<jx:set var="ignored" value="${tags.put(id, macro.body)}"/>
</jx:macro>
<dynamic-tag id="example">
<em>This tag was invoked dynamically</em>
</dynamic-tag>
<p>I'm about to invoke a dynamic tag:</p>
<jx:eval select="${tags.example}"/>
</pre>
<p>The above template produces the following output:</p>
<pre><p>I'm about to invoke a dynamic tag:</p>
<em>This tag was invoked dynamically</em>
</pre>
</body>
</html>
Collections
===========
The document belongs to the following collections: cdocs-template