| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>The SVG Serializer</title> |
| <authors> |
| <person name="Ross Burton" email="rossb@apache.org"/> |
| </authors> |
| </header> |
| |
| <body> |
| <s1 title="SVG Serializer"> |
| <s2 title="Introduction"> |
| <p> |
| The SVG Serializer is an advanced serializer which accepts |
| valid Scalable Vector Graphic documents (currently to the |
| 2000-08-02 Candidate Recommendation specification) and |
| renders it to an image which is served just like any other |
| document in Cocoon. |
| </p> |
| <p> |
| Why would you want to do this? Well, charts can be produced from the |
| same data which generates tables, graphical images with text labels |
| all following a standard theme can be generated or normal pages can be |
| beautified. |
| </p> |
| <note> |
| For examples of this serializer, see the Cocoon welcome |
| page in the distribution (<code>[cocoon |
| root]/welcome</code>). |
| </note> |
| <p> |
| So how does this serializer work? |
| </p> |
| <ol> |
| <li>Parse and validate SVG document</li> |
| <li>Call Batik's <code>Transcoder</code> to encode this image as an image file, and return it to the user.</li> |
| </ol> |
| <p> |
| The SVG xml document must have a root element <svg>, using xml namespace |
| it is recommended to use the prefix <em>em</em>, and the namespace uri |
| <em>http://www.w3.org/2000/svg</em>. |
| </p> |
| </s2> |
| |
| <s2 title="Usage"> |
| <p>The best way to explain how this serializer works is to show some examples.</p> |
| <s3 title="Basic Example"> |
| <p>This is a basic example of the serializer.</p> |
| <source><![CDATA[ |
| <map:serializers> |
| <map:serializer> |
| <map:serializer name="svg2jpeg" mime-type="image/jpeg" |
| src="org.apache.cocoon.serialization.SVGSerializer"> |
| <parameter name="transcoder" |
| value="org.apache.batik.transcoder.image.JPEGTranscoder"/> |
| </map:serializer> |
| <map:serializers> |
| ... |
| <map:pipeline> |
| <map:match pattern="sample.jpeg"> |
| <map:generate type="file" src="sample.svg"/> |
| <map:serialize type="svg2jpeg"/> |
| </map:match> |
| </map:pipeline> |
| ]]></source> |
| <p> |
| When the resource <code>sample.jpeg</code> is requested, a SAX event |
| stream is generated from the file <code>sample.svg</code>, which is |
| serialized using the <code>svg2jpeg</code> serializer. This |
| serializer is configured to use a specific transcoder. The MIME type |
| is specified so that Cocoon can tell the client which type the |
| document is. It can be seen that in general the use of this |
| serializer is identical to that of the other serializers. |
| </p> |
| <p> |
| The parameter <em>transcoder</em> selects explicitly a batik transcoder. |
| You may want to rely on the default <em>mime-type</em> to |
| transcoder association, omitting the transcoder parameter |
| </p> |
| <table> |
| <tr><th>mime-type</th><th>transcoder-class</th></tr> |
| <tr><td>image/jpeg</td><td>org.apache.batik.transcoder.image.JPEGTranscoder</td></tr> |
| <tr><td>image/jpg</td><td>org.apache.batik.transcoder.image.JPEGTranscoder</td></tr> |
| <tr><td>image/png</td><td>org.apache.batik.transcoder.image.PNGTranscoder</td></tr> |
| <tr><td>image/tiff</td><td>org.apache.batik.transcoder.image.TIFFTranscoder</td></tr> |
| </table> |
| </s3> |
| |
| <s3 title="Advanced Example"> |
| <p>This is a more advanced sample of using the SVG Serializer.</p> |
| <source><![CDATA[ |
| <map:serializers> |
| <map:serializer> |
| <map:serializer name="svg2jpeg" mime-type="image/jpeg" |
| src="org.apache.cocoon.serialization.SVGSerializer"> |
| <parameter name="transcoder" |
| value="org.apache.batik.transcoder.image.JPEGTranscoder"/> |
| <parameter name="background_color" type="color" value="#00FF00"/> |
| </map:serializer> |
| <map:serializers> |
| ... |
| <map:pipeline> |
| <map:match pattern="sample.jpeg"> |
| <map:generate type="file" src="sample.svg"/> |
| <map:serialize type="svg2jpeg"/> |
| </map:match> |
| </map:pipeline> |
| ]]></source> |
| <p> |
| In this example another parameter is given to the serializer, |
| <code>background_color</code>. This parameter is passed to the |
| transcoder. The <code>type</code> argument specifies the type of |
| data to convert the <code>value</code> to. In this example the |
| string "#00FF00" is converted to a <code>Color</code> object, which |
| is passed to the transcoder as the background colour to |
| use. |
| </p> |
| <p> |
| For a list of the parameters available for each transcoder, refer to |
| the Batik API docs. |
| </p> |
| <fixme author="rossb@apache.org"> |
| Create a document summarising the transcoder hints |
| </fixme> |
| <p> |
| The following table summarizes most useful general SVG ImageTranscoder parameters, |
| all of these parameters are mapped to Batik's SVG ImageTranscoder hints. |
| </p> |
| <table> |
| <tr><td>width</td><td>float</td><td>Specifies the width of the rasterized image explictly. |
| If no height is specified the aspect ratio is kept.</td> |
| </tr> |
| <tr><td>height</td><td>float</td><td>Specifies the width of the rasterized image explictly. |
| If no width is specified the aspect ration is kept.</td> |
| </tr> |
| <tr><td>background_color</td><td>color</td><td> |
| Defines the background color |
| to use for opaque image formats, or the background color that may |
| be used for image formats that support alpha channel. |
| A color value of format <code>RRGGBB</code>, |
| or <code>#RRGGBB</code> sets the background color of the rasterized image, by default |
| the background color is white.</td> |
| </tr> |
| <tr><td>language</td><td>string</td><td>to set the default language to use |
| (may be used by a <switch> SVG element for example), by default language is |
| set to <code>en</code>.</td> |
| </tr> |
| <tr><td>user_stylesheet_ur</td><td>string</td><td>to fix the URI of a user stylesheet</td> |
| </tr> |
| <tr><td>pixel_to_mm</td><td>float</td><td>to specify the pixel to millimeter conversion factor, by default |
| its value is <code>0.264583</code> (96dpi).</td> |
| </tr> |
| </table> |
| <p> |
| For this to work reliably with any transcoder, some magic must be |
| done. |
| </p> |
| <ol> |
| <li>First, the parameter name is transformed to upper-case and then "KEY_" is |
| prepended. This is to match the internal naming scheme of the hints |
| in the Batik <code>Transcoder</code> interfaces. |
| </li> |
| <li>This name is then |
| looked up via Reflection to ensure it is a valid parameter on the |
| specified transcoder. |
| </li> |
| <li>Then the value is converted to the type |
| specified in the <code>type</code> attribute (currently supported |
| types are string, float, integer, boolean and color) and passed to |
| the transcoder. |
| </li> |
| </ol> |
| </s3> |
| </s2> |
| </s1> |
| </body> |
| </document> |