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 / xls-serializer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  13.9 KB  |  279 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>HSSF Serializer</title>
  22.         <version>0.9</version>
  23.         <type>Technical document</type>
  24.         <authors>
  25.             <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
  26.             <person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
  27.             <person name="J├╢rg Heinicke" email="jheinicke@gmx.de"/>
  28.         </authors>
  29.         <abstract>This document describes the HSSF serializer of Cocoon.</abstract>
  30.     </header>
  31.     <body>
  32.         <s1 title="HSSF Serializer">
  33.             <p>The HSSF serializer catches SAX events and creates a spreadsheet in the
  34.                 XLS format used by Microsoft Excel (but the output looks just dandy in
  35.                 <link href="http://www.gnome.org/gnumeric">Gnumeric</link> or
  36.                 <link href="http://www.openoffice.org">OpenOffice.org</link> as well).
  37.             </p>
  38.             <p>The HSSF Serializer supports most of the functionality supplied by the
  39.                 <link href="http://jakarta.apache.org/poi/hssf">HSSF API</link> which is
  40.                 part of the
  41.                 <link href="http://jakarta.apache.org/poi">Jakarta POI project</link>.
  42.             </p>
  43.             <ul>
  44.                 <li>Name: xls</li>
  45.                 <li>Class: org.apache.cocoon.serialization.HSSFSerializer</li>
  46.                 <li>Cacheable: no</li>
  47.             </ul>
  48.         </s1>
  49.         <s1 title="Usage">
  50.             <p>Using the HSSF Serializer is fairly simple. You'll need a sitemap of
  51.                 course. Once you have that, well, you're half there. Add </p>
  52.             <source><![CDATA[
  53. <map:serializer name="xls"
  54.                 src="org.apache.cocoon.serialization.HSSFSerializer"
  55.                 locale="us"/>
  56.             ]]></source>
  57.             <p>into the <code><map:serializers/></code> section of your sitemap.
  58.                 The locale is optional and is used only to validate numbers. Please note
  59.                 that numbers not in US-default format may not be compatible with Gnumeric
  60.                 (it's less cosmopolitan then the HSSF Serializer ;-) ). Setting the locale
  61.                 lets you use default number formats from other locales. Set this to a two
  62.                 letter lowercase country code. See java.util.Locale for details.
  63.             </p>
  64.             <p>Next, set up an entry for each URL or set of URLs (via matching rules)
  65.                 resembling this:
  66.             </p>
  67.             <source><![CDATA[
  68. <map:match pattern="hello.xls">
  69.     <map:generate src="docs/samples/hello-page.xml"/>
  70.     <map:transform src="stylesheets/page/simple-page2xls.xsl"/>
  71.     <map:serialize type="xls"/>
  72. </map:match>
  73.             ]]></source>
  74.             <p>The most important question is now, which what XML the serializer is fed.
  75.                 You will get it answered in the next paragraph.</p>
  76.         </s1>
  77.         <s1 title="Required XML Format">
  78.             <p>The HSSF Serializer expects data in the same XML language as the popular
  79.                 spreadsheet progam Gnumeric. You have different possibilities to get such
  80.                 a document:</p>
  81.             <ul>
  82.                 <li>You can create and save a spreadsheet using Gnumeric.</li>
  83.                 <li>You can write it yourself using the
  84.                     <link href="http://cvs.gnome.org/lxr/source/gnumeric/gnumeric.xsd">
  85.                     Schemas</link> or DTDs available at the
  86.                     <link href="http://www.gnome.org/gnumeric">Gnumeric's website</link>
  87.                     or in Gnumeric's CVS repository.
  88.                 </li>
  89.                 <li>You can take one of the samples delivered with Cocoon and start from
  90.                     there.</li>
  91.                 <li>Or you use the empty workbook from appendix A in
  92.                     <link href="http://www.superlinksoftware.com/gnumeric-xml.pdf">
  93.                     The Gnumeric File Format PDF</link> (all further references to 'PDF'
  94.                     mean this file), which can further simplified to the following:<br/>
  95.                 </li>
  96.             </ul>
  97.             <source><![CDATA[
  98. <gmr:Workbook xmlns:gmr="http://www.gnome.org/gnumeric/v7">
  99.     <gmr:SheetNameIndex>
  100.         <gmr:SheetName>Sheet1</gmr:SheetName>
  101.     </gmr:SheetNameIndex>
  102.     <gmr:Sheets>
  103.         <gmr:Sheet>
  104.             <gmr:Name>Sheet1</gmr:Name>
  105.             <gmr:MaxCol>-1</gmr:MaxCol>
  106.             <gmr:MaxRow>-1</gmr:MaxRow>
  107.             <gmr:Cells>
  108.                 <!-- add your cells here -->
  109.             </gmr:Cells>
  110.         </gmr:Sheet>
  111.     </gmr:Sheets>
  112. </gmr:Workbook>
  113.             ]]></source>
  114.             <p>While HSSFSerializer ignores the bulk of the elements, it is suggested
  115.                 you provide at a minimum the basic elements as in the list below. As a
  116.                 general rule, if Gnumeric in the versions 0.7 - 1.04 will load the XML
  117.                 (provided it is tar'd and gzipped as expected), then the HSSFSerializer
  118.                 should be able to handle it.</p>
  119.             <p>As a general guideline the following elements are supported in this
  120.                 release. For the nesting have a look into the sample files or the PDF.
  121.             </p>
  122.             <ul>
  123.                 <li>
  124.                     <code>gmr:Workbook</code> -  Required. Basically the root element.
  125.                 </li>
  126.                 <li>
  127.                     <code>gmr:Sheets</code> - Required. Container for the spreadsheets.
  128.                 </li>
  129.                 <li>
  130.                     <code>gmr:Sheet</code> - Required for each sheet. For the attributes
  131.                     have a look at the example above or into the PDF.
  132.                 </li>
  133.                 <li>
  134.                     <code>gmr:Name</code> - Required? Defines the sheet's name as it
  135.                     appears on the little tabs under the workbook in your favorite GUI
  136.                     spreadsheet application.
  137.                 </li>
  138.                 <li>
  139.                     <code>gmr:MaxRow</code>, <code>gmr:MaxCol</code> - Used to set the
  140.                     dimensions for the sheet. This can be wrong and your spreadsheet
  141.                     application may not care, but some other ports depend upon this, so
  142.                     we set it to be compatible.
  143.                 </li>
  144.                 <li>
  145.                     <code>gmr:Rows</code>, <code>gmr:Cols</code> - Used to determine the
  146.                     default row or column width in points via the attribute
  147.                     <code>DefaultSizePts</code>.
  148.                 </li>
  149.                 <li>
  150.                     <code>gmr:RowInfo</code>, <code>gmr:ColInfo</code> - Used to
  151.                     determine the row height/column width for a specific row/column in
  152.                     points.<br/>
  153.                     Attributes:
  154.                     <ul>
  155.                         <li><code>No</code> - row/column number</li>
  156.                         <li><code>Unit</code> - row/column height</li>
  157.                     </ul>
  158.                     The count of the rows/columns starts with 0.
  159.                 </li>
  160.                 <li>
  161.                     <code>gmr:Cells</code> - Required. Container for all cells.
  162.                 </li>
  163.                 <li>
  164.                     <code>gmr:Cell</code> - Defines the actual column and row number as
  165.                     well as the data type.<br/>
  166.                     Attributes:
  167.                     <ul>
  168.                         <li><code>Row</code> - row number</li>
  169.                         <li><code>Col</code> - col number</li>
  170.                         <li>
  171.                             <code>ValueType</code> - the data type<br/>
  172.                             If you don't specify the data type, the cell content will not
  173.                             be shown! The type is determined by a numerical key, where
  174.                             the following are known: 10 - empty, 20 - boolean,
  175.                             30 - integer, 40 - float, 50 - error, 60 - string,
  176.                             70 - cell range, 80 - array
  177.                         </li>
  178.                     </ul>
  179.                 </li>
  180.                 <li>
  181.                     <code>gmr:Content</code> - Defines the start of the value contained
  182.                     in the cell. This is obsolete as of Gnumeric 1.03. It's not
  183.                     recommended to use it, because it may not be supported in future
  184.                     versions. With POI release 1.5.1 I didn't use <code>gmr:Content</code>,
  185.                     but I had to specify '10' as <code>ValueType</code> on empty cells.
  186.                     Otherwise I got strange output.
  187.                 </li>
  188.                 <li>
  189.                     <code>gmr:Styles</code> - Required if you want to use styles.
  190.                     Container for <code>gmr:StyleRegion's</code>.
  191.                 </li>
  192.                 <li>
  193.                     <code>gmr:StyleRegion</code> - Defines the region that the style
  194.                     applies to.<br/>
  195.                     Attributes:
  196.                     <ul>
  197.                         <li><code>startRow</code> - self-explanatory</li>
  198.                         <li><code>startCol</code> - self-explanatory</li>
  199.                         <li><code>endRow</code> - self-explanatory</li>
  200.                         <li><code>endCol</code> - self-explanatory</li>
  201.                     </ul>
  202.                     Again: The count of the rows/columns starts with 0.
  203.                 </li>
  204.                 <li>
  205.                     <code>gmr:Style</code> - Specifies the style for a StyleRegion.<br/>
  206.                     Attributes:
  207.                     <ul>
  208.                         <li>
  209.                             <code>HAlign</code> - specifies the horizontal alignment.<br/>
  210.                             Possible values: 1 - general, 2 - left, 4 - right, 8 - center,
  211.                             16 - fill, 32 - justify, 64 - center across selection
  212.                         </li>
  213.                         <li>
  214.                             <code>VAlign</code> - specifies the vertical alignment.<br/>
  215.                             Possible values: 1 - top, 2 - bottom, 4 - center, 8 - justify
  216.                         </li>
  217.                         <li>
  218.                             <code>WrapText</code> - specifies whether to wrap text around
  219.                             or not<br/>
  220.                             Possible values: 0 - don't wrap, 1 - do wrap
  221.                         </li>
  222.                         <li>
  223.                             <code>Shade</code> - kind a stupid flag<br/>
  224.                             If you're setting a background color and want it filled ...
  225.                             use Shade="1".
  226.                         </li>
  227.                         <li>
  228.                             <code>Format</code> - number format to use.<br/>
  229.                             Generally, Excel and Gnumeric have the same formats.
  230.                         </li>
  231.                     </ul>
  232.                 </li>
  233.                 <li>
  234.                     <code>gmr:Font</code> - Defines the font used for the style region.<br/>
  235.                     Attributes:
  236.                     <ul>
  237.                         <li><code>Bold</code> - self-explanatory</li>
  238.                         <li><code>Italic</code> - self-explanatory</li>
  239.                         <li><code>Underline</code> - self-explanatory</li>
  240.                         <li><code>StrikeThrough</code> - self-explanatory</li>
  241.                     </ul>
  242.                     Set the values of the attributes to 0 or 1 to disable or enable a
  243.                     specific font style.
  244.                 </li>
  245.                 <li>
  246.                     <code>gmr:StyleBorder</code> - Defines the borders that are used for
  247.                     a style region. It contains one element for each possible border
  248.                     specifying the style and the color of the border.
  249.                 </li>
  250.             </ul>
  251.             <p>For more specific information on the Gnumeric file format, especially on
  252.                 some more interesting attributes or attribute values or the nesting of
  253.                 the elements, I only can recommend you to read the PDF or to have a look
  254.                 at the sample files. If you want it more complicated, you can also get
  255.                 the information from the Schema file (look above for the link).</p>
  256.         </s1>
  257.         <s1 title="Automatic Excel Spreadsheet Generation">
  258.             <p>Hmm, I don't want to say to much on this. I showed you the XML the
  259.                 serializer wants to have. Now it's up to you to generate this XML
  260.                 dynamically. The best way to do this is using a XSLT stylesheet. You need
  261.                 some information on this? Hmm, have a look at the
  262.                 <link href="http://www.w3.org/Style/XSL/">W3C's XSL page</link>. From
  263.                 there you get many links to tutorials, articals, the surprisingly
  264.                 readable XSLT spec and so on.
  265.             </p>
  266.         </s1>
  267.         <s1 title="Future Features">
  268.             <p>So HSSF Serializer is well on its way to being darn near everything you
  269.                 need to create fancy smancy reports in Excel or OpenOffice. (And you can
  270.                 just serialize the output from your stylesheets as XML for Gnumeric
  271.                 version).</p>
  272.             <ul>
  273.                 <li>Add support for formulas. (not yet supported by HSSF)</li>
  274.                 <li>Add support for custom data formats. (not yet supported by HSSF)</li>
  275.             </ul>
  276.         </s1>
  277.     </body>
  278. </document>
  279.