[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Norman Richards
norman.richards at jboss.com
Wed Jan 17 06:20:34 EST 2007
User: nrichards
Date: 07/01/17 06:20:34
Added: doc/reference/en/modules itext.xml
Log:
add itext docs
Revision Changes Path
1.1 date: 2007/01/17 11:20:34; author: nrichards; state: Exp;jboss-seam/doc/reference/en/modules/itext.xml
Index: itext.xml
===================================================================
<chapter id="itext">
<title>iText PDF generation</title>
<para>Seam now includes an optional component set for generating documents using iText. The primary focus of Seam's
iText document support is for the generation of PDF doucuments, but Seam also offers basic support for RTF
document generation.</para>
<section>
<title>Using PDF Support</title>
<para>iText support is provided by jboss-seam-pdf.jar. This JAR contains the iText JSF controls, which are used
to construct views that can render to PDF, and the DocumentStore component, which serves the rendered
documents to the user. To include PDF support in your application, included jboss-seam-pdf.jar in your
WEB-INF/lib directory along with the iText JAR file. There is no further configuration needed to use Seam's
iText support. </para>
<para> The Seam iText module requires the use of Facelets as the view technology. Future versions of the library
may also support the use of JSP. Additionally, it requires the use of the seam-ui package.</para>
<para> The examples/pdf project contains an example of the PDF support in action. It demonstrates proper
deployment packaging, and it contains a number examples that demonstrate the key PDF generation features
current supported. </para>
</section>
<section>
<title>Creating a document</title>
<para> Documents are generated by facelets documents using tags in the
<literal>http://jboss.com/products/seam/pdf</literal> namespace. Documents should always have the
<literal>document</literal> tag at the root of the document. The document tag prepares Seam to generate
a document into the DocumentStore and renders an HTML redirect to that stored content. The following is a a
small PDF document consisting only a single line of text: </para>
<programlisting>
<p:document xmlns:p="http://jboss.com/products/seam/pdf">
A very tiny PDF
</p:document>
</programlisting>
<para> Documents should be composed entirely using Seam document components. Controls meant for HTML rendering
are generally not supported. However, pure control structures can be used. The following document uses the
<literal>ui:repeat</literal> tag to to display a list of values retrieved from a Seam component. </para>
<programlisting>
<p:document xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:p="http://jboss.com/products/seam/pdf">
<p:list>
<ui:repeat value="#{lists.numbers}" var="item">
<p:listItem><p:font style="bold">#{item}</p:font>:
This is some information...</p:listItem>
</ui:repeat>
</p:list>
</p:document>
</programlisting>
<section>
<title>p:document</title>
<para> The p:document tag supports the following attributes: </para>
<variablelist>
<varlistentry>
<term>
<literal>type</literal>
</term>
<listitem>
<para>The type of the document to be produced. Valid values are <literal>PDF</literal>,
<literal>RTF</literal> and <literal>HTML</literal> modes. Seam defaults to PDF
generation, and many of the features only work correctly when generating PDF
documents.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>pageSize</literal>
</term>
<listitem>
<para>The size of the page to be generate. The most commonly used values would be
<literal>LETTER</literal> and <literal>A4</literal>. A full list of supported pages
sizes can be found in <literal>com.lowagie.text.PageSize</literal> class.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>margins</literal>
</term>
<listitem>
<para>The left, right, top and bottom margin values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>marginMirroring</literal>
</term>
<listitem>
<para>Indicates that margin settings should be reversed an alternating pages.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Document metadata is also set as attributes of the document tag. The following metadata fields are
supported:</para>
<variablelist>
<varlistentry>
<term>
<literal>title</literal>
</term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>subject</literal>
</term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>keywords</literal>
</term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>author</literal>
</term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>creator</literal>
</term>
<listitem>
<para/>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Headers and Footers</title>
<section>
<title>p:header and p:footer</title>
<para>The <literal>p:header</literal> and <literal>p:footer</literal> components provide the ability to
place header and footer text on each page of a generated document, with the exception of the first page.
Header and footer declarations should appear near the top of a document. </para>
<variablelist>
<varlistentry>
<term>
<literal>alignment</literal>
</term>
<listitem>
<para>The alignment of the header/footer box section. (see <xref linkend="itext.alignment"/> for
alignment values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>backgroundColor</literal>
</term>
<listitem>
<para>The background color of the header/footer box. (see <xref linkend="itext.color"/> for
color values) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>borderColor</literal>
</term>
<listitem>
<para>The border color of the header/footer box. Individual border sides can be set using
<literal>borderColorLeft</literal>, <literal>borderColorRight</literal>,
<literal>borderColorTop</literal> and <literal>borderColorBottom</literal>.(see <xref
linkend="itext.color"/> for color values) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>borderWidth</literal>
</term>
<listitem>
<para>The width of the border. Inidvidual border sides can be specified using
<literal>borderWidthLeft</literal>, <literal>borderWidthRight</literal>,
<literal>borderWidthTop</literal> and <literal>borderWidthBottom</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:pageNumber</title>
<para>The current page number can be placed inside of a header or footer using the
<literal>p:pageNumber</literal> tag. The page number tag can only be used in the context of a header or
footer and can only be used once.</para>
</section>
</section>
<section>
<title>Chapters and Sections</title>
<para>If the generated document follows a book/article structure, the <literal>p:chapter</literal> and
<literal>p:section</literal> tags can be used to provide the necessary structure. Sections can only be
used inside of chapters, but they may be nested arbitrarily deep. </para>
<section>
<title>p:chapter and p:section</title>
<variablelist>
<varlistentry>
<term>
<literal>number</literal>
</term>
<listitem>
<para>The chapter number. Every chapter should be assigned a chapter number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>numberDepth</literal>
</term>
<listitem>
<para>The depth of numbering for section. All sections are numbered relative to their
surrounding chapter/sections. The fourth section of of the first section of chapter three
would be section 3.1.4, if displayed at the default number depth of three. To omit the
chapter number, a number depth of 2 should be used. In that case, the section number would
be displayed as 1.4.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:title</title>
<para>Any chapter or section can contain a <literal>p:title</literal>. The title will be displayed next to
the chapter/section number. The body of the title may contain text or may be a
<literal>p:paragraph</literal>. </para>
</section>
</section>
<section>
<title>Lists</title>
<para>List structures can be displayed using the <literal>p:list</literal> and <literal>p:listItem</literal>
tags. Lists may contain arbitrarily-nested sublists. List items may not be used outside of a list.</para>
<section>
<title>p:list</title>
<para><literal>p:list</literal> supports the following attributes:</para>
<variablelist>
<varlistentry>
<term>
<literal>style</literal>
</term>
<listitem>
<para>The ordering/bulleting style of list. One of: <literal>NUMBERED</literal>,
<literal>LETTERED</literal>, <literal>GREEK</literal>, <literal>ROMAN</literal>,
<literal>ZAPFDINGBATS</literal>, <literal>ZAPFDINGBATS_NUMBER</literal>. If no style is
given, the list items are bulleted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>listSymbol</literal>
</term>
<listitem>
<para>For bulleted lists, specifies the bullet symbol. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indent</literal>
</term>
<listitem>
<para>The indentation level of the list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>lowerCase</literal>
</term>
<listitem>
<para>For list styles using letters, indicates whether the letters should be lower case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>charNumber</literal>
</term>
<listitem>
<para>For ZAPFDINGBATS, indicates the character code of the bullet character.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>numberType</literal>
</term>
<listitem>
<para>For ZAPFDINGBATS_NUMBER, indicates the numbering style.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:listItem</title>
<para><literal>p:listItem</literal> supports the following attributes:</para>
<variablelist>
<varlistentry>
<term>
<literal>alignment</literal>
</term>
<listitem>
<para>The alignment of the list item. (See <xref linkend="itext.alignment"/> for possible
values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationLeft</literal>
</term>
<listitem>
<para>The left indentation amount.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationRight</literal>
</term>
<listitem>
<para>The right indentation amount.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>listSymbol</literal>
</term>
<listitem>
<para>Overrides the default list symbol for this list item.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Tables</title>
<para>Table structures can be created using the <literal>p:table</literal> and <literal>p:cell</literal> tags.
Unlike many table structures, there is no explicit row declaration. If a table has 3 columns, then every 3
cells will automatically form a row. </para>
<section>
<title>p:table</title>
<para><literal>p:table</literal> supports the following attributes.</para>
<variablelist>
<varlistentry>
<term>
<literal>columns</literal>
</term>
<listitem>
<para>The number of columns (cells) that make up a table row.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>widths</literal>
</term>
<listitem>
<para>The relative widths of each column. There should be one value for each column. For example: widths="2 1 1" would
indicate that there are 3 columns and the first column should be twice the size of the second and third column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>headerRows</literal>
</term>
<listitem>
<para>The initial number of rows which are considered to be headers or footer rows and should be
repeated if the table spans multiple pages. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>footerRows</literal>
</term>
<listitem>
<para>The number of rows that are considered to be footer rows. This value is subtracted from
the <literal>headerRows</literal> value. If document has 2 rows which make up the header and
one row that makes up the footer, <literal>headerRows</literal> should be set to 3 and
<literal>footerRows</literal> should be set to 1</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>widthPercentage</literal>
</term>
<listitem>
<para>The percentage of the page width that the table spans.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>horizontalAlignment</literal>
</term>
<listitem>
<para>The horizontal alignment of the table. (See <xref linkend="itext.alignment"/> for possible values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>skipFirstHeader</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>runDirection</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>lockedWidth</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>splitRows</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingBefore</literal>
</term>
<listitem>
<para>The blank space to be inserted before the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingAfter</literal>
</term>
<listitem>
<para>The blank space to be inserted after the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extendLastRow</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>headersInEvent</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>splitLate</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>keepTogether</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:cell></title>
<para><literal>p:cell</literal> supports the following attributes.</para>
<variablelist>
<varlistentry>
<term>
<literal>colspan</literal>
</term>
<listitem>
<para>Cells can span more than one column by declaring a <literal>colspan</literal> greater than
1. Tables do not have the ability to span across multiple rows. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>horizontalAlignment</literal>
</term>
<listitem>
<para>The horizontal alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>verticalAlignment</literal>
</term>
<listitem>
<para>The vertical alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>padding</literal>
</term>
<listitem>
<para>Padding on a given side can also be specified using <literal>paddingLeft</literal>,
<literal>paddingRight</literal>, <literal>paddingTop</literal> and
<literal>paddingBottom</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>useBorderPadding</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>leading</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>multipliedLeading</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indent</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>verticalAlignment</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extraParagraphSpace</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fixedHeight</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>noWrap</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>minimumHeight</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>followingIndent</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>rightIndent</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spaceCharRatio</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>runDirection</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>arabicOptions</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>useAscender</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>grayFill</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>rotation</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Basic Text Elements</title>
<section>
<title>p:paragraph</title>
<variablelist>
<varlistentry>
<term>
<literal>firstLineIndent</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>extraParagraphSpace</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>leading</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>multipliedLeading</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingBefore</literal>
</term>
<listitem>
<para>The blank space to be inserted before the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingAfter</literal>
</term>
<listitem>
<para>The blank space to be inserted after the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationLeft</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationRight</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>keepTogether</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:font</title>
<variablelist>
<varlistentry>
<term>
<literal>familyName</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>size</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>style</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:newPage</title>
<para><literal>p:newPage</literal> inserts a page break. </para>
</section>
<section>
<title>p:image</title>
<para><literal>p:image</literal> inserts an image into the document.</para>
<variablelist>
<varlistentry>
<term>
<literal>resource</literal>
</term>
<listitem>
<para>The location of the image resource to be included. Resources should be relative to the
document root of the web application.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>rotation</literal>
</term>
<listitem>
<para>The rotation of the image in degrees.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>height</literal>
</term>
<listitem>
<para>The height of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>width</literal>
</term>
<listitem>
<para>The width of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>alignment</literal>
</term>
<listitem>
<para>The alignment of the image. (see <xref linkend="itext.alignment"/> for possible values)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>alt</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationLeft</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>indentationRight</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingBefore</literal>
</term>
<listitem>
<para>The blank space to be inserted before the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>spacingAfter</literal>
</term>
<listitem>
<para>The blank space to be inserted after the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>widthPercentage</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>initialRotation</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>dpi</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>wrap</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>underlying</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>p:anchor></title>
<para><literal>p:anchor</literal> defines clickable links from a document. It supports the following
attributes:</para>
<variablelist>
<varlistentry>
<term>
<literal>name</literal>
</term>
<listitem>
<para>The name of an in-document anchor destination.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>reference</literal>
</term>
<listitem>
<para>The destination the link refers to. Links to other points in the document should begin
with a "#". For example, "#link1" to refer to an anchor postion with a
<literal>name</literal> of <literal>link1</literal>. Links may also be a full URL to point
to a resource outside of the document.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Document Constants</title>
<section id="itext.color">
<title>Color Values</title>
<para>Seam documents do not yet support a full color specification. Currently, only named colors are
supported. They are: <literal>white</literal>, <literal>gray</literal>, <literal>lightgray</literal>,
<literal>darkgray</literal>, <literal>black</literal>, <literal>red</literal>,
<literal>pink</literal>, <literal>yellow</literal>, <literal>green</literal>,
<literal>magenta</literal>, <literal>cyan</literal> and <literal>blue</literal>. </para>
</section>
<section id="itext.alignment">
<title>Alignment Values</title>
<para><literal>left</literal>, <literal>right</literal>, <literal>center</literal>,
<literal>justify</literal>, <literal>justifyall</literal>, <literal>top</literal>,
<literal>middle</literal>, <literal>bottom</literal>, <literal>baseline</literal></para>
</section>
</section>
<section>
<title>iText links</title>
<para>For further information on iText, see:</para>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://www.lowagie.com/iText/">iText Home Page</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.manning.com/lowagie/">iText in Action</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list