cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gkossakow...@apache.org
Subject svn commit: r646923 - /cocoon/site/site/2.2/blocks/linkrewriter/1.0/1102_1_1.html
Date Thu, 10 Apr 2008 18:57:12 GMT
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> &lt;site&gt;
+   &lt;faq&gt;
+     &lt;how_to_boil_eggs href=&quot;faq/eggs.html&quot;/&gt;
+   &lt;/faq&gt;
+ &lt;/site&gt;
+</pre><p>mapped to the prefix 'site:', then &lt;link
+href=&quot;site:/site/faq/how_to_boil_eggs/@href&quot;&gt; would be replaced
with &lt;link
+href=&quot;faq/eggs.html&quot;&gt;</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
+&lt;map:components&gt; block of the sitemap within &lt;input-module&gt; tags:
+</p><pre>  &lt;map:transformer name=&quot;linkrewriter&quot;
+      src=&quot;org.apache.cocoon.transformation.LinkRewriterTransformer&quot;&gt;
+    &lt;link-attrs&gt;href src&lt;/link-attrs&gt;
+    &lt;schemes&gt;site ext&lt;/schemes&gt;
+    &lt;input-module name=&quot;site&quot;&gt;
+      &lt;file src=&quot;cocoon://samples/link/linkmap&quot; reloadable=&quot;true&quot;/&gt;
+    &lt;/input-module&gt;
+    &lt;input-module name=&quot;mapper&quot;&gt;
+      &lt;input-module name=&quot;site&quot;&gt;
+        &lt;file src=&quot;{src}&quot; reloadable=&quot;true&quot;/&gt;
+      &lt;/input-module&gt;
+      &lt;prefix&gt;/site/&lt;/prefix&gt;
+      &lt;suffix&gt;/@href&lt;/suffix&gt;
+    &lt;/input-module&gt;
+  &lt;/map:transformer&gt;
+ </pre><p>Here, we have first configured which attributes to examine, and which
URL
+schemes to consider rewriting. In this example, &lt;a href=&quot;site:index&quot;&gt;
+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 &lt;input-module&gt;.</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 &quot;template&quot; 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>    &lt;map:match
pattern=&quot;**welcome&quot;&gt;
+      &lt;map:generate src=&quot;index.xml&quot;/&gt;
+      &lt;map:transform type=&quot;linkrewriter&quot; src=&quot;cocoon:/{1}linkmap&quot;/&gt;
+      &lt;map:serialize type=&quot;xml&quot;/&gt;
+    &lt;/map:match&gt;
+</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>
  &lt;prefix&gt;{prefix}&lt;/prefix&gt;
+</pre><p>in the template config, and:</p><pre>   &lt;map:parameter
name=&quot;prefix&quot; value=&quot;/site/&quot;/&gt;
+</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 (&quot;&quot;).</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 &lt;action target=&quot;foo url(x1) bar url(x2)&quot;/&gt;:</p><pre>
  &lt;map:transformer name=&quot;linkrewriter&quot;
+       src=&quot;org.apache.cocoon.transformation.LinkRewriterTransformer&quot;&gt;
+     &lt;link-attr name=&quot;target&quot; pattern=&quot;(?:url\((.*?)\).*?){1,2}$&quot;/&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></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>



Mime
View raw message