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: 9/10/08 7:57:24 PM
Updated by: David Legg
A new version has been created, state: draft
Parts
=====
Long description
----------------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 8591 bytes (previous version: 8558 bytes)
Content diff:
(31 equal lines skipped)
This ability lets the LinkRewriterTransformer look up the new value of an
attribute to be replaced at run time.</p>
+++ <h2>Transformer Configuration</h2>
+++
+++ <p>The following configuration entries in <map:transformer> block are
+++ recognised:</p>
+++
+++ <ul>
+++ <li>link-attrs - Space-separated list of attributes to consider links (to be
+++ transformed). The whole value of the attribute is considered a link and
+++ transformed.</li>
+++ <li>link-attr - 0..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:</li>
+++ <ul>
+++ <li>name - (required) name of the attribute whose value contains
link(s).</li>
+++ <li>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'.</li>
+++ </ul>
+++
+++ <li>schemes - Space-separated list of URI schemes to explicitly include. If
+++ specified, all URIs with unlisted schemes will <em>not</em> be
converted.</li>
+++ <li>exclude-schemes - Space-separated list of URI schemes to explicitly
exclude.
+++ Defaults to 'http https ftp news mailto'.</li>
+++ <li>bad-link-str - String to use for links with a correct InputModule
prefix,
+++ but no value therein. Defaults to the original URI.</li>
+++ <li>namespace-uri - The namespace uri of elements whose attributes are
+++ considered for transformation. Defaults to the empty namespace ("").</li>
+++ </ul>
+++
+++ <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>
+++
+++ <h2>InputModule Configuration</h2>
+++
<h3><strong>Example</strong></h3>
--- <p>For instance, if we had an
+++ <p>Suppose 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>
+++ configured to read values from an XML file containing the following
fragment:
+++ </p>
<pre> <site>
<faq>
(6 equal lines skipped)
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
(71 equal lines skipped)
<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>
---
--- <ul>
--- <li>link-attrs - Space-separated list of attributes to consider links (to be
--- transformed). The whole value of the attribute is considered a link and
--- transformed.</li>
--- <li>link-attr - 0..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:</li>
--- <ul>
--- <li>name - (required) name of the attribute whose value contains
link(s).</li>
--- <li>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'.</li>
--- </ul>
---
--- <li>schemes - Space-separated list of URI schemes to explicitly include. If
--- specified, all URIs with unlisted schemes will <em>not</em> be
converted.</li>
--- <li>exclude-schemes - Space-separated list of URI schemes to explicitly
exclude.
--- Defaults to 'http https ftp news mailto'.</li>
--- <li>bad-link-str - String to use for links with a correct InputModule
prefix,
--- but no value therein. Defaults to the original URI.</li>
--- <li>namespace-uri - The namespace uri of elements whose attributes are
--- considered for transformation. Defaults to the empty namespace ("").</li>
--- </ul>
---
--- <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>
