cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/serializers xls-serializer.xml
Date Wed, 02 Apr 2003 04:27:29 GMT
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>
  -                        &lt;map:serializer name="xls" src="org.apache.cocoon.serialization.HSSFSerializer"
mime-type="application/vnd.ms-excel" locale="us"/&gt;
  -                        </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>
  -                         &lt;map:match pattern="hello.xls"&gt;
  -                                &lt;map:generate src="docs/samples/hello-page.xml"/&gt;
  -                                &lt;map:transform src="stylesheets/page/simple-page2xls.xsl"/&gt;
  -                                &lt;map:serialize type="xls"/&gt;
  -                         &lt;/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>&lt;map:serializers/&gt;</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>
  
  
  

Mime
View raw message