home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / encodeurl-transformer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  4.5 KB  |  135 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.  <header>
  21.   <title>EncodeURL Transformer</title>
  22.   <subtitle>in @doctitle@</subtitle>
  23.   <version>0.9</version>
  24.   <type>Technical document</type>
  25.   <authors>
  26.    <person name="Bernhard Huber" email="huber@apache.org"/>
  27.   </authors>
  28.   <abstract>This document describes the EncodeURL transformer.</abstract>
  29.  </header>
  30.  <body>
  31.   <s1 title="EncodeURL Transformer">
  32.    <p>
  33.     The encodeURL transformer emits encoded URLs.
  34.     This transformer applies encodeURL method to URLs.
  35.     You may want to use this transform to avoid doing the manually
  36.     encodeURL() call.
  37.    </p>
  38.    <p>
  39.     Usually this transformer is appended as last transformer before
  40.     the serialization process. In this case it is possible to encode
  41.     URLs introduced in the generator, and xslt transformer phase.
  42.    </p>
  43.    <p>
  44.     You can specify which attributes hold URL values in order to restrict
  45.     URL rewriting to specific attributes only. In the current implementation
  46.     you specify include, and exclude patterns as regular expressions, concatting
  47.     element-name + "/@" + attribute-name.
  48.    </p>
  49.    <p>
  50.     The EncodeURLTransformer has several configuration options. These options
  51.     may be specified in the sitemap, or by each request.
  52.    </p>
  53.    <dl>
  54.      <dt>include-name</dt>
  55.      <dd>RE pattern for including attributes from encode URL rewriting, 
  56.        The attribute values are encoded, if an 
  57.        expressions of the form <code>element-name/@attribute-name</code>
  58.        matches.
  59.        <br/>
  60.        By default <code>include-name</code> is defined as
  61.        <code>.*/@href|.*/@action|frame/@src</code>.
  62.      </dd>
  63.      <dt>exclude-name</dt>
  64.      <dd>RE pattern for excluding attributes from encode URL rewriting,
  65.        The attribute values are not encoded, if an 
  66.        expressions of the form <code>element-name/@attribute-name</code>
  67.        matches.
  68.        <br/>
  69.        By default <code>exclude-name</code> is defined as
  70.        <code>img/@src</code>.
  71.      </dd>
  72.    </dl>
  73.    <ul>
  74.     <li>Name : encodeURL</li>
  75.     <li>Class: org.apache.cocoon.transformation.EncodeURLTransformer</li>
  76.     <li>Cacheable: yes.</li>
  77.    </ul>
  78.    <p>
  79.     A simple example might help to use the EncodeURLTransformer effectivly:
  80.    </p>
  81.    <p>
  82.     Add the EncodeURLTransformer to the components in your sitemap.xmap
  83.    </p>
  84. <source><![CDATA[
  85. ...
  86. <map:components>
  87. ...
  88.   <map:transformers default="xslt">
  89.   ...
  90.     <map:transformer name="encodeURL"
  91.       src="org.apache.cocoon.transformation.EncodeURLTransformer">
  92.       <!-- default configuration, explicitly defined -->
  93.       <include-name>.*/@href|.*/@action|frame/@src</include-name>
  94.       <exclude-name>img/@src</exclude-name>
  95.     </map:transformer>
  96.   ...
  97. ]]></source>
  98.    <p>
  99.      Next define in your pipeline to use the EncodeURLTransformer
  100.    </p>
  101. <source><![CDATA[
  102. <map:match pattern="*.xsp">
  103.   <map:generate type="serverpages" name="docs/samples/xsp/{1}.xsp"/>
  104.   <map:transform src="stylesheets/page/simple-page2html.xsl"/>
  105.   
  106.   <map:transform type="encodeURL"/>
  107.   <map:serialize/>
  108. </map:match>
  109. ]]></source>
  110.  
  111.    <p>
  112.     In this example pipeline it is assumed that the attribute
  113.     <code>href</code> of element <code>a</code> contains an URL which should get 
  114.     encoded.
  115.     Moreover the attribute <code>action</code> of any element contains an URL
  116.     which should get encoded, too.
  117.     Finally the attribute <code>src</code> of element 
  118.     <code>frame</code> should get encoded, too.
  119.    </p>
  120.    <p>
  121.     The attribute <code>src</code> of element <code>img</code> is excluded from
  122.     encoding.
  123.    </p>
  124.    <p>
  125.      In other words, images are served regardless of the current session, in contrast
  126.      anchor links, form actions, and frame src are served depending on the current session.
  127.    </p>
  128.    <p>
  129.     The encoding itself applies the servlet method <code>response.encodeURL()</code>
  130.     upon the URL.
  131.    </p>
  132.   </s1>
  133.  </body>
  134. </document>
  135.