[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: 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 &lt;map:transformer&gt; 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 &lt;action target="foo url(x1) bar url(x2)"/&gt;:</p>
+++ 
+++ <pre>   &lt;map:transformer name="linkrewriter"
+++        src="org.apache.cocoon.transformation.LinkRewriterTransformer"&gt;
+++      &lt;link-attr name="target" pattern="(?:url\((.*?)\).*?){1,2}$"/&gt;
+++      &lt;!-- additional configuration ... --&gt;
+++    &lt;/map:transformer&gt;
+++ </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> &lt;site&gt;
       &lt;faq&gt;
(6 equal lines skipped)
    href="site:/site/faq/how_to_boil_eggs/@href"&gt; would be replaced with &lt;link
    href="faq/eggs.html"&gt;</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 &lt;action target="foo url(x1) bar url(x2)"/&gt;:</p>
--- 
--- <pre>   &lt;map:transformer name="linkrewriter"
---        src="org.apache.cocoon.transformation.LinkRewriterTransformer"&gt;
---      &lt;link-attr name="target" pattern="(?:url\((.*?)\).*?){1,2}$"/&gt;
---      &lt;!-- additional configuration ... --&gt;
---    &lt;/map:transformer&gt;
--- </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>