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 2008/04/02 09:29:41 UTC
[DAISY] Updated: LinkRewriterTransformer
A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/1102.html
Document ID: 1102
Branch: main
Language: default
Name: LinkRewriterTransformer (unchanged)
Document Type: Sitemap Component (unchanged)
Updated on: 4/2/08 7:29:21 AM
Updated by: Luca Morandini
A new version has been created, state: draft
Parts
=====
Short description
-----------------
This part has been added.
Mime type: text/xml
File name: null
Size: 207 bytes
Content:
<html>
<body>
<p>Rewrites URIs in links to a value determined by an InputModule. The URI
scheme identifies the InputModule to use, and the rest of the URI is used as the
attribute name.</p>
</body>
</html>
Long description
----------------
This part has been added.
Mime type: text/xml
File name: null
Size: 6651 bytes
Content:
<html>
<body>
<p><strong>Example</strong></p>
<p>For instance, if we had an
<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/XMLFileModule.html">XMLFileModule</a>,
configured to read values from an XML file:</p>
<pre> <site>
<faq>
<how_to_boil_eggs href="faq/eggs.html"/>
</faq>
</site>
</pre>
<p>mapped to the prefix 'site:', then <link
href="site:/site/faq/how_to_boil_eggs/@href"> would be replaced with <link
href="faq/eggs.html"></p>
<h3>InputModule Configuration</h3>
<p>InputModules are configured twice; first statically in cocoon.xconf, and then
dynamically at runtime, with dynamic configuration (if any) taking precedence.
Transformer allows you to pass a dynamic configuration to used InputModules as
follows.</p>
<p>First, a template Configuration is specified in the static
<map:components> block of the sitemap within <input-module> tags:
</p>
<pre> <map:transformer name="linkrewriter"
src="org.apache.cocoon.transformation.LinkRewriterTransformer">
<link-attrs>href src</link-attrs>
<schemes>site ext</schemes>
<input-module name="site">
<file src="cocoon://samples/link/linkmap" reloadable="true"/>
</input-module>
<input-module name="mapper">
<input-module name="site">
<file src="{src}" reloadable="true"/>
</input-module>
<prefix>/site/</prefix>
<suffix>/@href</suffix>
</input-module>
</map:transformer>
</pre>
<p>Here, we have first configured which attributes to examine, and which URL
schemes to consider rewriting. In this example, <a href="site:index">
would be processed. See below for more configuration options.</p>
<p>Then, we have established dynamic configuration templates for two modules,
'site' (an
<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/XMLFileModule.html">XMLFileModule</a>
and 'mapper' (A
<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/SimpleMappingMetaModule.html">SimpleMappingMetaModule</a>.
All other InputModules will use their static configs. Note that, when
configuring a meta InputModule like 'mapper', we need to also configure the
'inner' module (here, 'site') with a nested <input-module>.</p>
<p>There is one further twist; to have <em>really</em> dynamic configuration, we
need information available only when the transformer actually runs. This is why
the above config was called a "template" configuration; it needs to be
'instantiated' and provided extra info, namely:</p>
<ul>
<li>The {src} string will be replaced with the map:transform @src attribute
value.</li>
<li>Any other {variables} will be replaced with map:parameter values</li>
</ul>
<p>With the above config template, we can have a matcher like:</p>
<pre> <map:match pattern="**welcome">
<map:generate src="index.xml"/>
<map:transform type="linkrewriter" src="cocoon:/{1}linkmap"/>
<map:serialize type="xml"/>
</map:match>
</pre>
<p>Which would cause the 'mapper' XMLFileModule to be configured with a
different XML file, depending on the request.</p>
<p>Similarly, we could use a dynamic prefix:</p>
<pre> <prefix>{prefix}</prefix>
</pre>
<p>in the template config, and:</p>
<pre> <map:parameter name="prefix" value="/site/"/>
</pre>
<p>in the map:transform</p>
<p>A live example of LinkRewriterTransformer can be found in the
<a href="http://forrest.apache.org/">Apache Forrest</a> sitemap.</p>
<h3>Transformer Configuration</h3>
<p>The following configuration entries in map:transformer block are recognised:
</p>
<p>link-attrsSpace-separated list of attributes to consider links (to be
transformed). The whole value of the attribute is considered link and
transformed.link-attr0..n of these elements each specify an attribute containing
link(s) (to be transformed) and optionally a regular expression to locate
substring(s) of the attribute value considered link(s). Has two attributes:
name(required) name of the attribute whose value contains
link(s).pattern(optional) regular expression such that when matched against the
attribute value, all parenthesized expressions (except number 0) will be
considered links that should be transformed. If absent, the whole value of the
attribute is considered to be a link, as if the attribute was included in
'link-attrs'. schemesSpace-separated list of URI schemes to explicitly include.
If specified, all URIs with unlisted schemes will <em>not</em> be
converted.exclude-schemesSpace-separated list of URI schemes to explicitly
exclude. Defaults to 'http https ftp news mailto'.bad-link-strString to use for
links with a correct InputModule prefix, but no value therein. Defaults to the
original URI.namespace-uriThe namespace uri of elements whose attributes are
considered for transformation. Defaults to the empty namespace ("").</p>
<p>The attributes considered to contain links are a <em>set</em> of the
attributes specified in 'link-attrs' element and all 'link-attr' elements. Each
attribute should be specified only once either in 'link-attrs' or 'link-attr';
i.e. an attribute can have at most 1 regular expression associated with it. If
neither 'link-attrs' nor 'link-attr' configuration is present, defaults to
'href'.</p>
<p>Below is an example of regular expression usage that will transform links x1
and x2 in <action target="foo url(x1) bar url(x2)"/>:</p>
<pre> <map:transformer name="linkrewriter"
src="org.apache.cocoon.transformation.LinkRewriterTransformer">
<link-attr name="target" pattern="(?:url\((.*?)\).*?){1,2}$"/>
<!-- additional configuration ... -->
</map:transformer>
</pre>
<p>When matched against the value of target attribute above, the parenthesized
expressions are:<br/>
$0 = url(x1) bar url(x2)<br/>
$1 = x1<br/>
$2 = x2</p>
<p>Expression number 0 is always discarded by the transformer and the rest are
considered links and re-written.</p>
<p>If present, map:parameter's from the map:transform block override the
corresponding configuration entries from map:transformer. As an exception,
'link-attr' parameters are not recognised; 'link-attrs' parameter overrides both
'link-attrs' and 'link-attr' configuration.</p>
<p class="note">This transformer may be used to convert the URIs containing the
<tt>servlet: </tt>protocol to access blocks into browser-recognisable URIs</p>
</body>
</html>