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 / svg-serializer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  8.2 KB  |  195 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>The SVG Serializer</title>
  22.   <authors>
  23.     <person name="Ross Burton" email="rossb@apache.org"/>
  24.   </authors>
  25.   </header>
  26.   
  27.   <body>
  28.     <s1 title="SVG Serializer">
  29.       <s2 title="Introduction">
  30.         <p>
  31.           The SVG Serializer is an advanced serializer which accepts
  32.           valid Scalable Vector Graphic documents (currently to the
  33.           2000-08-02 Candidate Recommendation specification) and
  34.           renders it to an image which is served just like any other
  35.           document in Cocoon.
  36.         </p>
  37.         <p>
  38.           Why would you want to do this? Well, charts can be produced from the
  39.           same data which generates tables, graphical images with text labels
  40.           all following a standard theme can be generated or normal pages can be
  41.           beautified.
  42.         </p>
  43.         <note>
  44.           For examples of this serializer, see the Cocoon welcome
  45.           page in the distribution (<code>[cocoon
  46.           root]/welcome</code>).
  47.         </note>
  48.         <p>
  49.           So how does this serializer work?
  50.         </p>
  51.         <ol>
  52.           <li>Parse and validate SVG document</li>
  53.           <li>Call Batik's <code>Transcoder</code> to encode this image as an image file, and return it to the user.</li>
  54.         </ol>
  55.         <p>
  56.           The SVG xml document must have a root element <svg>, using xml namespace
  57.           it is recommended to use the prefix <em>em</em>, and the namespace uri
  58.           <em>http://www.w3.org/2000/svg</em>.
  59.         </p>
  60.       </s2>
  61.   
  62.       <s2 title="Usage">
  63.         <p>The best way to explain how this serializer works is to show some examples.</p>
  64.         <s3 title="Basic Example">
  65.           <p>This is a basic example of the serializer.</p>
  66.           <source><![CDATA[
  67. <map:serializers>
  68.   <map:serializer>
  69.     <map:serializer name="svg2jpeg" mime-type="image/jpeg" 
  70.         src="org.apache.cocoon.serialization.SVGSerializer">
  71.       <parameter name="transcoder" 
  72.           value="org.apache.batik.transcoder.image.JPEGTranscoder"/>
  73.   </map:serializer>
  74. <map:serializers>
  75. ...
  76. <map:pipeline>
  77.   <map:match pattern="sample.jpeg">
  78.     <map:generate type="file" src="sample.svg"/> 
  79.     <map:serialize type="svg2jpeg"/>
  80.   </map:match>    
  81. </map:pipeline>
  82.        ]]></source>
  83.           <p>
  84.             When the resource <code>sample.jpeg</code> is requested, a SAX event
  85.             stream is generated from the file <code>sample.svg</code>, which is
  86.             serialized using the <code>svg2jpeg</code> serializer. This
  87.             serializer is configured to use a specific transcoder. The MIME type
  88.             is specified so that Cocoon can tell the client which type the
  89.             document is. It can be seen that in general the use of this
  90.             serializer is identical to that of the other serializers.
  91.           </p>
  92.           <p>
  93.             The parameter <em>transcoder</em> selects explicitly a batik transcoder.
  94.             You may want to rely on the default <em>mime-type</em> to 
  95.             transcoder association, omitting the transcoder parameter
  96.           </p>
  97.           <table>
  98.             <tr><th>mime-type</th><th>transcoder-class</th></tr>
  99.             <tr><td>image/jpeg</td><td>org.apache.batik.transcoder.image.JPEGTranscoder</td></tr>
  100.             <tr><td>image/jpg</td><td>org.apache.batik.transcoder.image.JPEGTranscoder</td></tr>
  101.             <tr><td>image/png</td><td>org.apache.batik.transcoder.image.PNGTranscoder</td></tr>
  102.             <tr><td>image/tiff</td><td>org.apache.batik.transcoder.image.TIFFTranscoder</td></tr>
  103.           </table>
  104.         </s3>
  105.         
  106.         <s3 title="Advanced Example">
  107.           <p>This is a more advanced sample of using the SVG Serializer.</p>
  108.           <source><![CDATA[
  109. <map:serializers>
  110.   <map:serializer>
  111.     <map:serializer name="svg2jpeg" mime-type="image/jpeg" 
  112.         src="org.apache.cocoon.serialization.SVGSerializer">
  113.       <parameter name="transcoder" 
  114.           value="org.apache.batik.transcoder.image.JPEGTranscoder"/>
  115.       <parameter name="background_color" type="color" value="#00FF00"/>
  116.   </map:serializer>
  117. <map:serializers>
  118. ...
  119. <map:pipeline>
  120.   <map:match pattern="sample.jpeg">
  121.     <map:generate type="file" src="sample.svg"/> 
  122.     <map:serialize type="svg2jpeg"/>
  123.   </map:match>    
  124. </map:pipeline>
  125.        ]]></source>
  126.           <p>
  127.             In this example another parameter is given to the serializer,
  128.             <code>background_color</code>. This parameter is passed to the
  129.             transcoder. The <code>type</code> argument specifies the type of
  130.             data to convert the <code>value</code> to. In this example the
  131.             string "#00FF00" is converted to a <code>Color</code> object, which
  132.             is passed to the transcoder as the background colour to
  133.             use.
  134.           </p>
  135.           <p>
  136.             For a list of the parameters available for each transcoder, refer to
  137.             the Batik API docs.
  138.           </p>
  139.           <fixme author="rossb@apache.org">
  140.                   Create a document summarising the transcoder hints
  141.           </fixme>
  142.           <p>
  143.             The following table summarizes most useful general SVG ImageTranscoder parameters,
  144.             all of these parameters are mapped to Batik's SVG ImageTranscoder hints.
  145.           </p>
  146.           <table>
  147.             <tr><td>width</td><td>float</td><td>Specifies the width of the rasterized image explictly.
  148.               If no height is specified the aspect ratio is kept.</td>
  149.             </tr>
  150.             <tr><td>height</td><td>float</td><td>Specifies the width of the rasterized image explictly.
  151.               If no width is specified the aspect ration is kept.</td>
  152.             </tr>
  153.             <tr><td>background_color</td><td>color</td><td>
  154.               Defines the background color
  155.               to use for opaque image formats, or the background color that may
  156.               be used for image formats that support alpha channel.
  157.               A color value of format <code>RRGGBB</code>, 
  158.               or <code>#RRGGBB</code> sets the background color of the rasterized image, by default
  159.               the background color is white.</td>
  160.             </tr>
  161.             <tr><td>language</td><td>string</td><td>to set the default language to use 
  162.               (may be used by a <switch> SVG element for example), by default language is
  163.               set to <code>en</code>.</td>
  164.             </tr>
  165.             <tr><td>user_stylesheet_ur</td><td>string</td><td>to fix the URI of a user stylesheet</td>
  166.             </tr>
  167.             <tr><td>pixel_to_mm</td><td>float</td><td>to specify the pixel to millimeter conversion factor, by default
  168.               its value is <code>0.264583</code> (96dpi).</td>
  169.             </tr>
  170.           </table>
  171.           <p>
  172.             For this to work reliably with any transcoder, some magic must be
  173.             done.
  174.           </p>
  175.           <ol>
  176.             <li>First, the parameter name is transformed to upper-case and then "KEY_" is
  177.             prepended. This is to match the internal naming scheme of the hints
  178.             in the Batik <code>Transcoder</code> interfaces.
  179.             </li>
  180.             <li>This name is then
  181.             looked up via Reflection to ensure it is a valid parameter on the
  182.             specified transcoder.
  183.             </li>
  184.             <li>Then the value is converted to the type
  185.             specified in the <code>type</code> attribute (currently supported
  186.             types are string, float, integer, boolean and color) and passed to
  187.             the transcoder.
  188.             </li>
  189.           </ol>
  190.       </s3>
  191.     </s2>
  192.   </s1>
  193. </body>
  194. </document>
  195.