You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by cr...@apache.org on 2003/04/02 06:27:29 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/serializers xls-serializer.xml
crossley 2003/04/01 20:27:29
Modified: src/documentation/xdocs/userdocs/serializers
xls-serializer.xml
Log:
Major re-write of this doc. Added new section "Required XML format".
Changed example sitemap snippet: no point specifying mime-type because
it is hardcoded.
Submitted by: Joerg Heinicke <joerg.heinicke.at.gmx.de>
PR: 18164
Revision Changes Path
1.2 +256 -182 cocoon-2.1/src/documentation/xdocs/userdocs/serializers/xls-serializer.xml
Index: xls-serializer.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/serializers/xls-serializer.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xls-serializer.xml 9 Mar 2003 00:08:25 -0000 1.1
+++ xls-serializer.xml 2 Apr 2003 04:27:29 -0000 1.2
@@ -2,189 +2,263 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
- <header>
- <title>XML Serializer</title>
- <version>0.9</version>
- <type>Technical document</type>
- <authors>
- <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
- <person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
- </authors>
- <abstract>This document describes the HSSF serializer of Cocoon.</abstract>
- </header>
- <body>
- <s1 title="HSSF Serializer">
- <p>The HSSF serializer is the catches SAX events and creates a
- spreadsheet in the XLS format used by Microsoft Excel (but
- the output looks just dandy in
- <link
- href="http://www.gnome.org/gnumeric">Gnumeric</link> or
- <link
- href="http://www.openoffice.org">OpenOffice.org</link>
- as well). The HSSF Serializer expects data in the
- same tag language as the popular spreadsheet progam
- Gnumeric. You can locate schemas and dtd's for this
- format on the gnumeric website or in it's CVS
- repository. One of the easiest ways to use the HSSF
- Serializer is to create a spreadsheet using Gnumeric
- and then refactor it into an XSLT page.
- </p>
- <p>The HSSF Serializer supports most of the
- functionality supplied by the
- <link href="http://jakarta.apache.org/poi/hssf">HSSF
- API</link> which is part of the <link
- href="http://jakarta.apache.org/poi">Jakarta POI
- project</link>.
- </p>
- <ul>
- <li>Name : xls</li>
- <li>Class: org.apache.cocoon.serialization.HSSFSerializer</li>
- <li>Cacheable: ?</li>
- </ul>
- </s1>
- <s1 title="Usage">
- <p>Using the HSSF Serializer is fairly simple. You'll
- need a sitemap of course. Once you have that well,
- you're half there. Add </p>
- <source>
- <map:serializer name="xls" src="org.apache.cocoon.serialization.HSSFSerializer" mime-type="application/vnd.ms-excel" locale="us"/>
- </source>
- <p>
- to the sitemap between the map:serializers tags. The locale is optional
- and is used only to validate numbers. Please note that numbers not in US-default
- format may mot be compatible with Gnumeric (its less cosmopolitan then the
- HSSF Serializer ;-) ). Setting the locale lets you use default number formats
- from other locales. Set this to a two letter lowercase country code. See
- java.util.Locale for details.
- </p>
- <p>
- Next,
- set up an entry for each url or set of urls (via
- matching rules) resembling this:
- </p>
- <source>
- <map:match pattern="hello.xls">
- <map:generate src="docs/samples/hello-page.xml"/>
- <map:transform src="stylesheets/page/simple-page2xls.xsl"/>
- <map:serialize type="xls"/>
- </map:match>
- </source>
- <p>
- As for the stylesheets tts best to look at the sources
- for the Cocoon samples. You'll find the HSSF Serializer
- examples under "Legacy Formats" from the main samples
- page. You can find the source under <link
- href="http://cvs.apache.org/viewcvs/cocoon-2.1/src/webapp/samples/poi/">
- cocoon-2.1/src/webapp/samples/poi</link> in the Cocoon
- sources.
- </p>
- </s1>
- <s1 title="Required XML format">
- <p>It is suggested that you use the sample stylesheets
- as a template until you master the format. You'll probably
- want to graduate from that to using Gnumeric to create
- templates and adapt them into stylesheets. HSSFSerializer
- assumes the XML it is serializing uses the same tag
- library as the <link href="http://www.gnome.org">Gnome project's</link>
- (http://www.gnome.org) <link href="http://www.gnome.org/gnumeric">
- Gnumeric spreadsheet</link>. At this time the serializer
- supports the same tags used in the 0.7-1.04 version. The
- schema for this format was created by POI committer Marc
- Johnson and can be found <link href="http://cvs.gnome.org/lxr/source/gnumeric/gnumeric.xsd">
- here</link>. While HSSFSerializer ignores
- the bulk of the tags, it is suggested you provide at a
- minimum the basic tags in the example above. As a general
- rule, if Gnumeric 0.7-1.04 will load the XML (provided it
- is tar'd and gzipped as expected) then the HSSFSerializer
- should be able to handle it. While you can simply output
- an XML document in this format via a file or some other
- process (servlet/etc.), you'll probably have existing
- documents you'd like to format into spreadsheets. The
- best way to do this is to create a stylesheet. There are
- a number of good books and references on XSLT. A good one
- is Michael Kay's book from Wrox publishing so aptly
- named XSLT Programmer's Reference. Another is the XSLT
- book from O'Reilly. The first is good as a lookup reference.
- The latter is good for concepts, etc. You can also find
- a wealth of information at http://www.xml.org. The XSLT
- spec is surprisingly readable.
- </p>
- <p>As a general guideline these tags are not ignored in
- this release:
- </p>
- <ul>
- <li>gmr:Workbook - Required, basically the root
- element</li>
- <li>gmr:Sheets - Required</li>
- <li>gmr:Sheet - Required for each sheet</li>
- <li>gmr:Name - Defines the sheet's name as it
- appears on the little tabs under the
- workbook in your favorite GUI spreadsheet
- application.</li>
- <li>gmr:MaxCol - Used to set the dimensions for
- the sheet. This can be wrong and your
- spreadsheet program may not care but some
- other ports depend upon this, so we set it
- to be compatible.</li>
- <li>gmr:Cols - Used to determine the default
- column width</li>
- <li>gmr:ColInfo - Used to set the column width
- for a specific column. (the attribute is a
- misnomer, the unit is characters)</li>
- <li>gmr:Rows - Used to set the default row
- height in points.</li>
- <li>gmr:RowInfo - Used to set the row height for
- a specific row in points.</li>
- <li>gmr:Cells - Required</li>
- <li>gmr:Cell - defines the actual column and row
- number as well as the data type.</li>
- <li>gmr:Content - defines the start of the value
- contained in the cell. This is obsolete as of
- Gnumeric 1.03. Its still supported by HSSF, but
- may not be in future versions.</li>
- <li>gmr:Styles - required if StyleRegion is
- used. (parent collection node)</li>
- <li>gmr:StyleRegion - defines a style for a
- region of the spreadsheet.</li>
- <li>gmr:Style - Specifies the actaul style for a
- StyleRegion. HAlign attribute specifies the
- horizontal alignment and may have a value of
- 1 (General), 2 (Left), 4 (Right), 8 (Center),
- 16 (Fill),32 (Justify), or 64 (Center accross
- selection). VAlign specifies the vertical
- alignment (top,bottom,center,justify are 1, 2, 4
- and 8 respectively). WrapText specifies whether
- to wrap text around or not (0 = don't, 1 = do),
- Shade is a kidna stupid flag...if you're setting
- a background color and want it filled...use
- Shade="1". Format is the number format to use.
- Generally, Excel and Gnumeric have the same
- formats.</li>
- <li>Font - Font is a child of the StyleRegion.
- The attirbutes are pretty darned obvious. If
- you don't know what Bold or Italic mean then
- well, we can't help you here.</li>
- <li>StyleBorder - StyleBorder a child of the
- Style tag. It contains child elements for each border
- a cell could have (Top, Bottom, Left, Right,
- Diagnol) and each of these specify a border
- Style and optionally a Color.</li>
- </ul>
+ <header>
+ <title>HSSF Serializer</title>
+ <version>0.9</version>
+ <type>Technical document</type>
+ <authors>
+ <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
+ <person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
+ <person name="Jörg Heinicke" email="jheinicke@gmx.de"/>
+ </authors>
+ <abstract>This document describes the HSSF serializer of Cocoon.</abstract>
+ </header>
+ <body>
+ <s1 title="HSSF Serializer">
+ <p>The HSSF serializer catches SAX events and creates a spreadsheet in the
+ XLS format used by Microsoft Excel (but the output looks just dandy in
+ <link href="http://www.gnome.org/gnumeric">Gnumeric</link> or
+ <link href="http://www.openoffice.org">OpenOffice.org</link> as well).
+ </p>
+ <p>The HSSF Serializer supports most of the functionality supplied by the
+ <link href="http://jakarta.apache.org/poi/hssf">HSSF API</link> which is
+ part of the
+ <link href="http://jakarta.apache.org/poi">Jakarta POI project</link>.
+ </p>
+ <ul>
+ <li>Name: xls</li>
+ <li>Class: org.apache.cocoon.serialization.HSSFSerializer</li>
+ <li>Cacheable: no</li>
+ </ul>
+ </s1>
+ <s1 title="Usage">
+ <p>Using the HSSF Serializer is fairly simple. You'll need a sitemap of
+ course. Once you have that, well, you're half there. Add </p>
+ <source><![CDATA[
+<map:serializer name="xls"
+ src="org.apache.cocoon.serialization.HSSFSerializer"
+ locale="us"/>
+ ]]></source>
+ <p>into the <code><map:serializers/></code> section of your sitemap.
+ The locale is optional and is used only to validate numbers. Please note
+ that numbers not in US-default format may not be compatible with Gnumeric
+ (it's less cosmopolitan then the HSSF Serializer ;-) ). Setting the locale
+ lets you use default number formats from other locales. Set this to a two
+ letter lowercase country code. See java.util.Locale for details.
+ </p>
+ <p>Next, set up an entry for each URL or set of URLs (via matching rules)
+ resembling this:
+ </p>
+ <source><![CDATA[
+<map:match pattern="hello.xls">
+ <map:generate src="docs/samples/hello-page.xml"/>
+ <map:transform src="stylesheets/page/simple-page2xls.xsl"/>
+ <map:serialize type="xls"/>
+</map:match>
+ ]]></source>
+ <p>The most important question is now, which what XML the serializer is fed.
+ You will get it answered in the next paragraph.</p>
+ </s1>
+ <s1 title="Required XML Format">
+ <p>The HSSF Serializer expects data in the same XML language as the popular
+ spreadsheet progam Gnumeric. You have different possibilities to get such
+ a document:</p>
+ <ul>
+ <li>You can create and save a spreadsheet using Gnumeric.</li>
+ <li>You can write it yourself using the
+ <link href="http://cvs.gnome.org/lxr/source/gnumeric/gnumeric.xsd">
+ Schemas</link> or DTDs available at the
+ <link href="http://www.gnome.org/gnumeric">Gnumeric's website</link>
+ or in Gnumeric's CVS repository.
+ </li>
+ <li>You can take one of the samples delivered with Cocoon and start from
+ there.</li>
+ <li>Or you use the empty workbook from appendix A in
+ <link href="http://www.superlinksoftware.com/gnumeric-xml.pdf">
+ The Gnumeric File Format PDF</link> (all further references to 'PDF'
+ mean this file), which can further simplified to the following:<br/>
+ </li>
+ </ul>
+ <source><![CDATA[
+<gmr:Workbook xmlns:gmr="http://www.gnome.org/gnumeric/v7">
+ <gmr:SheetNameIndex>
+ <gmr:SheetName>Sheet1</gmr:SheetName>
+ </gmr:SheetNameIndex>
+ <gmr:Sheets>
+ <gmr:Sheet>
+ <gmr:Name>Sheet1</gmr:Name>
+ <gmr:MaxCol>-1</gmr:MaxCol>
+ <gmr:MaxRow>-1</gmr:MaxRow>
+ <gmr:Cells>
+ <!-- add your cells here -->
+ </gmr:Cells>
+ </gmr:Sheet>
+ </gmr:Sheets>
+</gmr:Workbook>
+ ]]></source>
+ <p>While HSSFSerializer ignores the bulk of the elements, it is suggested
+ you provide at a minimum the basic elements as in the list below. As a
+ general rule, if Gnumeric in the versions 0.7 - 1.04 will load the XML
+ (provided it is tar'd and gzipped as expected), then the HSSFSerializer
+ should be able to handle it.</p>
+ <p>As a general guideline the following elements are supported in this
+ release. For the nesting have a look into the sample files or the PDF.
+ </p>
+ <ul>
+ <li>
+ <code>gmr:Workbook</code> - Required. Basically the root element.
+ </li>
+ <li>
+ <code>gmr:Sheets</code> - Required. Container for the spreadsheets.
+ </li>
+ <li>
+ <code>gmr:Sheet</code> - Required for each sheet. For the attributes
+ have a look at the example above or into the PDF.
+ </li>
+ <li>
+ <code>gmr:Name</code> - Required? Defines the sheet's name as it
+ appears on the little tabs under the workbook in your favorite GUI
+ spreadsheet application.
+ </li>
+ <li>
+ <code>gmr:MaxRow</code>, <code>gmr:MaxCol</code> - Used to set the
+ dimensions for the sheet. This can be wrong and your spreadsheet
+ application may not care, but some other ports depend upon this, so
+ we set it to be compatible.
+ </li>
+ <li>
+ <code>gmr:Rows</code>, <code>gmr:Cols</code> - Used to determine the
+ default row or column width in points via the attribute
+ <code>DefaultSizePts</code>.
+ </li>
+ <li>
+ <code>gmr:RowInfo</code>, <code>gmr:ColInfo</code> - Used to
+ determine the row height/column width for a specific row/column in
+ points.<br/>
+ Attributes:
+ <ul>
+ <li><code>No</code> - row/column number</li>
+ <li><code>Unit</code> - row/column height</li>
+ </ul>
+ The count of the rows/columns starts with 0.
+ </li>
+ <li>
+ <code>gmr:Cells</code> - Required. Container for all cells.
+ </li>
+ <li>
+ <code>gmr:Cell</code> - Defines the actual column and row number as
+ well as the data type.<br/>
+ Attributes:
+ <ul>
+ <li><code>Row</code> - row number</li>
+ <li><code>Col</code> - col number</li>
+ <li>
+ <code>ValueType</code> - the data type<br/>
+ If you don't specify the data type, the cell content will not
+ be shown! The type is determined by a numerical key, where
+ the following are known: 10 - empty, 20 - boolean,
+ 30 - integer, 40 - float, 50 - error, 60 - string,
+ 70 - cell range, 80 - array
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code>gmr:Content</code> - Defines the start of the value contained
+ in the cell. This is obsolete as of Gnumeric 1.03. It's not
+ recommended to use it, because it may not be supported in future
+ versions. In the release 1.5.1 I used I didn't use
+ <code>gmr:Content</code>, but I had to specify '10' as
+ <code>ValueType</code> of empty cells. Otherwise I got strange
+ output.
+ </li>
+ <li>
+ <code>gmr:Styles</code> - Required if you want to use styles.
+ Container for <code>gmr:StyleRegion's</code>.
+ </li>
+ <li>
+ <code>gmr:StyleRegion</code> - Defines the region that the style
+ applies to.<br/>
+ Attributes:
+ <ul>
+ <li><code>startRow</code> - self-explanatory</li>
+ <li><code>startCol</code> - self-explanatory</li>
+ <li><code>endRow</code> - self-explanatory</li>
+ <li><code>endCol</code> - self-explanatory</li>
+ </ul>
+ Again: The count of the rows/columns starts with 0.
+ </li>
+ <li>
+ <code>gmr:Style</code> - Specifies the style for a StyleRegion.<br/>
+ Attributes:
+ <ul>
+ <li>
+ <code>HAlign</code> - specifies the horizontal alignment.<br/>
+ Possible values: 1 - general, 2 - left, 4 - right, 8 - center,
+ 16 - fill, 32 - justify, 64 - center across selection
+ </li>
+ <li>
+ <code>VAlign</code> - specifies the vertical alignment.<br/>
+ Possible values: 1 - top, 2 - bottom, 4 - center, 8 - justify
+ </li>
+ <li>
+ <code>WrapText</code> - specifies whether to wrap text around
+ or not<br/>
+ Possible values: 0 - don't wrap, 1 - do wrap
+ </li>
+ <li>
+ <code>Shade</code> - kind a stupid flag<br/>
+ If you're setting a background color and want it filled ...
+ use Shade="1".
+ </li>
+ <li>
+ <code>Format</code> - number format to use.<br/>
+ Generally, Excel and Gnumeric have the same formats.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code>gmr:Font</code> - Defines the font used for the style region.<br/>
+ Attributes:
+ <ul>
+ <li><code>Bold</code> - self-explanatory</li>
+ <li><code>Italic</code> - self-explanatory</li>
+ <li><code>Underline</code> - self-explanatory</li>
+ <li><code>StrikeThrough</code> - self-explanatory</li>
+ </ul>
+ Set the values of the attributes to 0 or 1 to disable or enable a
+ specific font style.
+ </li>
+ <li>
+ <code>gmr:StyleBorder</code> - Defines the borders that are used for
+ a style region. It contains one element for each possible border
+ specifying the style and the color of the border.
+ </li>
+ </ul>
+ <p>For more specific information on the Gnumeric file format, especially on
+ some more interesting attributes or attribute values or the nesting of
+ the elements, I only can recommend you to read the PDF or to have a look
+ at the sample files. If you want it more complicated, you can also get
+ the information from the Schema file (look above for the link).</p>
+ </s1>
+ <s1 title="Automatic Excel Spreadsheet Generation">
+ <p>Hmm, I don't want to say to much on this. I showed you the XML the
+ serializer wants to have. Now it's up to you to generate this XML
+ dynamically. The best way to do this is using a XSLT stylesheet. You need
+ some information on this? Hmm, have a look at the
+ <link href="http://www.w3.org/Style/XSL/">W3C's XSL page</link>. From
+ there you get many links to tutorials, articals, the surprisingly
+ readable XSLT spec and so on.
+ </p>
</s1>
<s1 title="Future Features">
- <p>
- So HSSF Serializer is well on its way to being darn near
- everything you need to create fancy smancy reports in
- Excel or OpenOffice. (And you can just XML Serialize the
- output from your stylesheets for Gnumeric version).
- </p>
- <ul>
- <li>Add support for formulas. (not yet supported by
- HSSF)</li>
- <li>Add support for custom data formats. (not yet
- supported by HSSF)</li>
- </ul>
+ <p>So HSSF Serializer is well on its way to being darn near everything you
+ need to create fancy smancy reports in Excel or OpenOffice. (And you can
+ just serialize the output from your stylesheets as XML for Gnumeric
+ version).</p>
+ <ul>
+ <li>Add support for formulas. (not yet supported by HSSF)</li>
+ <li>Add support for custom data formats. (not yet supported by HSSF)</li>
+ </ul>
</s1>
-
- </body>
+ </body>
</document>