cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Created: Variable substitution
Date Fri, 03 Mar 2006 17:05:58 GMT
A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/855.html

Document ID: 855
Branch: main
Language: default
Name: Variable substitution
Document Type: Cocoon Document
Created: 3/3/06 3:43:02 PM
Creator (owner): Bruno Dumon
State: publish

Parts
=====

Content
-------
Mime type: text/xml
Size: 4425 bytes
Content:
<html>
<body>

<h1>Introduction</h1>

<p>In various attributes in the sitemap, you can dynamically insert values by
using putting an expression between curly braces: <tt>{expression}</tt>. These
expressions will then be evaluted and replaced with their value.</p>

<h1>Summary</h1>

<p>There are basically two types of expressions:</p>

<ul>
<li>an expression that retrieves a value returned from a matcher or action</li>
<li>an expression that uses an input module to retrieve some value</li>
</ul>

<h2>Expressions that retrieve a value returned from a matcher or action</h2>

<p>Matchers and actions can return a map of values to the sitemap.</p>

<p>A common example of this is the following:</p>

<pre>&lt;map:match pattern="*/*.html"&gt;
  &lt;map:generate src="{2}.xml"/&gt;
  &lt;map:transformer src="{1}.xsl"/&gt;
  &lt;map:serialize type="html"/&gt;
&lt;/map:match&gt;</pre>

<p>The matcher matches on the request URL path. The matcher will returns a map
to the sitemap containing the following mappings:</p>

<pre>key  -&gt;  value
--------------
1    -&gt;  value matched by first wildcard
2    -&gt;  value matched by second wildcard</pre>

<p>Note that naming the keys '1', '2', etc. is simply a convention followed by
most matcher implementations. Actions will typically return more descriptive
names.</p>

<p>In case matchers are nested, you can use <tt>../</tt> syntax to climb
up in
the matcher/action tree.</p>

<p>For example:</p>

<pre>&lt;map:match pattern="*/*.html"&gt;
  &lt;map:act type="GetXyz"&gt;
    &lt;map:generate src="{xyz}/{../2}.xml"/&gt;
  &lt;/map:act&gt;
  &lt;map:transformer src="{1}.xsl"/&gt;
  &lt;map:serialize type="html"/&gt;
&lt;/map:match&gt;
</pre>

<p>In this example we added an imagined action "GetXyz" which returns a map with
a key "xyz". To refer to the wildcard from the matcher, we now need to use
<tt>{../2}</tt>.</p>

<p>If there would be other components nested, e.g. a selector, then these do not
influence the nesting. So adding a selector to the previous sample doesn't
change anything:</p>

<pre>&lt;map:match pattern="*/*.html"&gt;
  &lt;map:act type="GetXyz"&gt;
    &lt;map:select type="something"&gt;
       &lt;map:when test="x"&gt;
         &lt;map:generate type="x-gen" src="{xyz}/{../2}.xml"/&gt;
       &lt;/map:when&gt;
       &lt;map:otherwise&gt;
         &lt;map:generate src="{xyz}/{../2}.xml"/&gt;
       &lt;/map:otherwise&gt;
     &lt;/map:select&gt;
  &lt;/map:act&gt;
  &lt;map:transformer src="{1}.xsl"/&gt;
  &lt;map:serialize type="html"/&gt;
&lt;/map:match&gt;
</pre>

<p>Referencing values using the <tt>../</tt> syntax can work as many levels
deep
as you want. This might get complicated though. Therefore you can give names to
matchers and actions.</p>

<p>For example:</p>

<pre>&lt;map:match pattern="*/*.html" name="mymatcher"&gt;
  &lt;map:act type="GetXyz"&gt;
    &lt;map:generate src="{xyz}/{#mymatcher:2}.xml"/&gt;
  &lt;/map:act&gt;
  &lt;map:transformer src="{1}.xsl"/&gt;
  &lt;map:serialize type="html"/&gt;
&lt;/map:match&gt;
</pre>

<p>Tip: if you are in a situation where you actually need to give names to
actions and matchers, you are probably making your sitemap too complex.</p>

<p>For completeness we should mention the following features (rather obscure):
</p>

<ul>
<li>It is possible to reference variables matched at the root level by starting
the expression with "/"</li>
<li>You can add <tt>sitemap:</tt> in front of all these expressions. For
example, <tt>{sitemap:1}</tt>. Leaving out the <tt>sitemap:</tt> can
be
considered as a shorthand notation for this. Practically, there is no reason to
ever use this <tt>sitemap:</tt> syntax.</li>
</ul>

<h2>Expressions that uses an input module to retrieve some value</h2>

<p>The syntax for these is:</p>

<pre>{&lt;input module name&gt;:&lt;input module specific string&gt;}</pre>

<p>Input modules are basically components that get some value from somewhere.
For example, the "request-param" input module retrieves the value of request
parameters. The following example takes the name of the stylesheet to apply from
a request parameter called "style":</p>

<pre>&lt;map:match pattern="*.html"&gt;
  &lt;map:generate src="{1}.xml"/&gt;
  &lt;map:transformer src="{request-param:style}.xsl"/&gt;
  &lt;map:serialize type="html"/&gt;
&lt;/map:match&gt;
</pre>

<p class="fixme">Add link to input module docs, once we have these.</p>

</body>
</html>

Collections
===========
The document belongs to the following collections: documentation

Mime
View raw message