You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by gk...@apache.org on 2008/04/10 20:57:12 UTC
svn commit: r646923 -
/cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html
Author: gkossakowski
Date: Thu Apr 10 11:57:09 2008
New Revision: 646923
URL: http://svn.apache.org/viewvc?rev=646923&view=rev
Log:
Publishing LinkRewriter docs.
Modified:
cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html
Modified: cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html?rev=646923&r1=646922&r2=646923&view=diff
==============================================================================
--- cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html (original)
+++ cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html Thu Apr 10 11:57:09 2008
@@ -156,8 +156,100 @@
</ul>
</li>
</ul>
- <div id="contentBody"><div id="bodyText"><h1 class="docTitle">LinkRewriterTransformer</h1><h1>Summary</h1><p>No summary available. The summary needs to be defined using the
- <tt>@cocoon.sitemap.component.documentation</tt> annotation in the Java source file for this component.</p><h1>Basic information</h1><table class="bodyTable"><tr class="a"><th>Component type</th><td>Transformer</td></tr><tr class="b"><th>Cocoon block</th><td>linkrewriter</td></tr><tr class="a"><th>Java class</th><td>org.apache.cocoon.transformation.LinkRewriterTransformer</td></tr><tr class="b"><th>Name in Sitemap</th><td></td></tr><tr class="a"><th>Cacheable</th><td>No</td></tr></table><h1>Documentation</h1><p>No documentation available yet.</p></div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
+ <div id="contentBody"><div id="bodyText"><h1 class="docTitle">LinkRewriterTransformer</h1><h1>Summary</h1><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><h1>Basic information</h1><table class="bodyTable"><tr class="a"><th>Component type</th><td>Transformer</td></tr><tr class="b"><th>Cocoon block</th><td>linkrewriter</td></tr><tr class="a"><th>Java class</th><td>org.apache.cocoon.transformation.LinkRewriterTransformer</td></tr><tr class="b"><th>Name in Sitemap</th><td></td></tr><tr class="a"><th>Cacheable</th><td>No</td></tr></table><h1>Documentation</h1><h3 xmlns:p="http://outerx.org/daisy/1.0#publisher" xmlns:ns="http://outerx.org/daisy/1.0"><strong>Example</strong></h3><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 xmlns:p="http://outerx.org/daisy/1.0#publisher" xmlns:ns="http://outerx.org/daisy/1.0">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>With the above config template, we can have a matcher like:<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>Which would cause the 'mapper' XMLFileModule to be configured with a
+different XML file, depending on the request.<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 xmlns:p="http://outerx.org/daisy/1.0#publisher" xmlns:ns="http://outerx.org/daisy/1.0">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></br>
+$0 = url(x1) bar url(x2)<br></br>
+$1 = x1<br></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><div class="note"><div><strong>Note: </strong>This transformer may be used to convert the URIs containing the
+<tt xmlns:p="http://outerx.org/daisy/1.0#publisher" xmlns:ns="http://outerx.org/daisy/1.0">servlet: </tt>protocol to access blocks into browser-recognisable URIs</div></div></div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
us: <a href="http://cocoon.zones.apache.org/daisy/cdocs/1102?branch=1&language=1">View, Edit or comment</a> on the latest development version (registration required).
</div></div></div>
</div>