[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Norman Richards
norman.richards at jboss.com
Sun Feb 4 20:54:34 EST 2007
User: nrichards
Date: 07/02/04 20:54:34
Modified: doc/reference/en/modules itext.xml
Log:
add some better examples, restructure a bit
Revision Changes Path
1.4 +476 -367 jboss-seam/doc/reference/en/modules/itext.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: itext.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/itext.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- itext.xml 25 Jan 2007 22:15:43 -0000 1.3
+++ itext.xml 5 Feb 2007 01:54:34 -0000 1.4
@@ -1,10 +1,10 @@
<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>
+ <para>Seam now includes an 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>
+ <section id="itext.intro">
<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
@@ -14,40 +14,23 @@
<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>
+ <para> The <literal>examples/pdf</literal> 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>
+ <section id="itext.document">
<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>
+ <literal>document</literal> tag at the root of the document. The <literal>document</literal> 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>
+ The document goes here.
</p:document>
</programlisting>
@@ -161,289 +144,233 @@
</section>
- <section>
- <title>Headers and Footers</title>
+ <section id="itext.text">
+ <title>Basic Text Elements</title>
+
+ <para> Useful documents will need to contain more than just text; however, the standard UI components are geared
+ towards HTML generation and are not useful for generating PDF content. Instead, Seam provides a special UI
+ components for generating suitable PDF content. Tags like <literal><p:image></literal> and
+ <literal><p:paragraph></literal> are the basic foundations of simple documents. Tags like
+ <literal><p:font></literal> provide style information to all the content surrounging them. </para>
+
+ <programlisting>
+<p:document xmlns:p="http://jboss.com/products/seam/pdf">
+ <p:image alignment="right" wrap="true" resource="/logo.jpg" />
+ <p:font size="24">
+ <p:paragraph spacingAfter="50">My First Document</p:paragraph>
+ </p:font>
+
+ <p:paragraph alignment="justify">
+ This is a simple document. It isn't very fancy.
+ </p:paragraph>
+</p:document>
+ </programlisting>
- <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>
+ <section>
+ <title>p:paragraph</title>
+ <para>Most uses of text should be sectioned into paragraphs so that text fragments can be flowed, formatted
+ and styled in logical groups. </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>
+ <literal>firstLineIndent</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>
+ <para> </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>
+ <literal>extraParagraphSpace</literal>
</term>
<listitem>
- <para>The chapter number. Every chapter should be assigned a chapter number.</para>
+ <para> </para>
</listitem>
</varlistentry>
-
<varlistentry>
<term>
- <literal>numberDepth</literal>
+ <literal>leading</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>
+ <para> </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>
+ <literal>multipliedLeading</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>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>listSymbol</literal>
+ <literal>spacingBefore</literal>
</term>
<listitem>
- <para>For bulleted lists, specifies the bullet symbol. </para>
+ <para>The blank space to be inserted before the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>indent</literal>
+ <literal>spacingAfter</literal>
</term>
<listitem>
- <para>The indentation level of the list.</para>
+ <para>The blank space to be inserted after the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>lowerCase</literal>
+ <literal>indentationLeft</literal>
</term>
<listitem>
- <para>For list styles using letters, indicates whether the letters should be lower case.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>charNumber</literal>
+ <literal>indentationRight</literal>
</term>
<listitem>
- <para>For ZAPFDINGBATS, indicates the character code of the bullet character.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>numberType</literal>
+ <literal>keepTogether</literal>
</term>
<listitem>
- <para>For ZAPFDINGBATS_NUMBER, indicates the numbering style.</para>
+ <para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
- <title>p:listItem</title>
+ <title>p:text</title>
+ <para>The <literal>text</literal> tag allows text fragments to be produced from application data using
+ normal JSF converter mechanisms. It is very similar to the <literal>outputText</literal> tag used when
+ rendering HTML documents. Here is an example: </para>
+
+ <programlisting>
+<p:paragraph>
+ The item costs <p:text value="#{product.price}">
+ <f:convertNumber type="currency" currencySymbol="$"/>
+ </p:text>
+</p:paragraph>
+ </programlisting>
- <para><literal>p:listItem</literal> supports the following attributes:</para>
<variablelist>
<varlistentry>
<term>
- <literal>alignment</literal>
+ <literal>value</literal>
</term>
<listitem>
- <para>The alignment of the list item. (See <xref linkend="itext.alignment"/> for possible
- values)</para>
+ <para>The value to be displayed. This will typically be a value binding expression.</para>
</listitem>
</varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>p:font</title>
+ <para>Font declarations have no direct </para>
+ <variablelist>
<varlistentry>
<term>
- <literal>indentationLeft</literal>
+ <literal>familyName</literal>
</term>
<listitem>
- <para>The left indentation amount.</para>
+ <para>The font family. One of: <literal>COURIER</literal>, <literal>HELVETICA</literal>,
+ <literal>TIMES-ROMAN</literal>, <literal>SYMBOL</literal> or
+ <literal>ZAPFDINGBATS</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>indentationRight</literal>
+ <literal>size</literal>
</term>
<listitem>
- <para>The right indentation amount.</para>
+ <para>The point size of the font.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>listSymbol</literal>
+ <literal>style</literal>
</term>
<listitem>
- <para>Overrides the default list symbol for this list item.</para>
+ <para>The font styles. Any combination of : <literal>NORMAL</literal>, <literal>BOLD</literal>,
+ <literal>ITALIC</literal>, <literal>OBLIQUE</literal>, <literal>UNDERLINE</literal>,
+ <literal>LINE-THROUGH</literal></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:newPage</title>
+ <para><literal>p:newPage</literal> inserts a page break. </para>
+ </section>
<section>
- <title>p:table</title>
- <para><literal>p:table</literal> supports the following attributes.</para>
+ <title>p:image</title>
+ <para><literal>p:image</literal> inserts an image into the document.</para>
<variablelist>
<varlistentry>
<term>
- <literal>columns</literal>
+ <literal>resource</literal>
</term>
<listitem>
- <para>The number of columns (cells) that make up a table row.</para>
+ <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>widths</literal>
+ <literal>rotation</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>
+ <para>The rotation of the image in degrees.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>headerRows</literal>
+ <literal>height</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>
+ <para>The height of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>footerRows</literal>
+ <literal>width</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>
+ <para>The width of the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>widthPercentage</literal>
+ <literal>alignment</literal>
</term>
<listitem>
- <para>The percentage of the page width that the table spans.</para>
+ <para>The alignment of the image. (see <xref linkend="itext.alignment"/> for possible values)
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>horizontalAlignment</literal>
+ <literal>alt</literal>
</term>
<listitem>
- <para>The horizontal alignment of the table. (See <xref linkend="itext.alignment"/> for possible
- values)</para>
+ <para>Alternative text representation for the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>skipFirstHeader</literal>
+ <literal>indentationLeft</literal>
</term>
<listitem>
<para> </para>
@@ -451,7 +378,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>runDirection</literal>
+ <literal>indentationRight</literal>
</term>
<listitem>
<para> </para>
@@ -459,55 +386,57 @@
</varlistentry>
<varlistentry>
<term>
- <literal>lockedWidth</literal>
+ <literal>spacingBefore</literal>
</term>
<listitem>
- <para> </para>
+ <para>The blank space to be inserted before the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>splitRows</literal>
+ <literal>spacingAfter</literal>
</term>
<listitem>
- <para> </para>
+ <para>The blank space to be inserted after the element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>spacingBefore</literal>
+ <literal>widthPercentage</literal>
</term>
<listitem>
- <para>The blank space to be inserted before the element.</para>
+ <para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>spacingAfter</literal>
+ <literal>initialRotation</literal>
</term>
<listitem>
- <para>The blank space to be inserted after the element.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>extendLastRow</literal>
+ <literal>dpi</literal>
</term>
<listitem>
- <para> </para>
+ <para/>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>headersInEvent</literal>
+ <literal>scalePercent</literal>
</term>
<listitem>
- <para> </para>
+ <para>The scaling factor (as a percentage) to use for the image. This can be expressed as a
+ single percentage value or as two percentage values representing separate x and y scaling
+ percentages.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>splitLate</literal>
+ <literal>wrap</literal>
</term>
<listitem>
<para> </para>
@@ -515,7 +444,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>keepTogether</literal>
+ <literal>underlying</literal>
</term>
<listitem>
<para> </para>
@@ -524,206 +453,381 @@
</variablelist>
</section>
-
<section>
- <title>p:cell</title>
+ <title>p:anchor</title>
- <para><literal>p:cell</literal> supports the following attributes.</para>
+ <para><literal>p:anchor</literal> defines clickable links from a document. It supports the following
+ attributes:</para>
<variablelist>
<varlistentry>
<term>
- <literal>colspan</literal>
+ <literal>name</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>
+ <para>The name of an in-document anchor destination.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>horizontalAlignment</literal>
+ <literal>reference</literal>
</term>
<listitem>
- <para>The horizontal alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
- values)</para>
+ <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 id="itext.header">
+ <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>verticalAlignment</literal>
+ <literal>alignment</literal>
</term>
<listitem>
- <para>The vertical alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
- values)</para>
+ <para>The alignment of the header/footer box section. (see <xref linkend="itext.alignment"/> for
+ alignment values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>padding</literal>
+ <literal>backgroundColor</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>
+ <para>The background color of the header/footer box. (see <xref linkend="itext.color"/> for
+ color values) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>useBorderPadding</literal>
+ <literal>borderColor</literal>
</term>
<listitem>
- <para> </para>
+ <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>leading</literal>
+ <literal>borderWidth</literal>
</term>
<listitem>
- <para> </para>
+ <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 id="itext.chapters">
+ <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. Most PDF viewers provide easy navigation
+ between chapters and sections in a document. </para>
+
+
+ <programlisting>
+<p:document xmlns:p="http://jboss.com/products/seam/pdf"
+ title="Hello">
+
+ <p:chapter number="1">
+ <p:title><p:paragraph>Hello</p:paragraph></p:title>
+ <p:paragraph>Hello #{user.name}!</p:paragraph>
+ </p:chapter>
+
+ <p:chapter number="2">
+ <p:title><p:paragraph>Goodbye</p:paragraph></p:title>
+ <p:paragraph>Goodbye #{user.name}.</p:paragraph>
+ </p:chapter>
+
+</p:document>
+ </programlisting>
+
+
+
+ <section>
+ <title>p:chapter and p:section</title>
+ <variablelist>
<varlistentry>
<term>
- <literal>multipliedLeading</literal>
+ <literal>number</literal>
</term>
<listitem>
- <para> </para>
+ <para>The chapter number. Every chapter should be assigned a chapter number.</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
- <literal>indent</literal>
+ <literal>numberDepth</literal>
</term>
<listitem>
- <para> </para>
+ <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 raw text or may be a
+ <literal>p:paragraph</literal>. </para>
+ </section>
+ </section>
+
+
+ <section id="itext.list">
+ <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. he
+ 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:p="http://jboss.com/products/seam/pdf"
+ xmlns:ui="http://java.sun.com/jsf/facelets"
+ title="Hello">
+ <p:list style="numbered">
+ <ui:repeat value="#{documents}" var="doc">
+ <p:listItem>#{doc.name}</p:listItem>
+ </ui:repeat>
+ </p:list>
+</p:document>
+ </programlisting>
+
+
+
+
+ <section>
+ <title>p:list</title>
+
+
+ <para><literal>p:list</literal> supports the following attributes:</para>
+
+ <variablelist>
<varlistentry>
<term>
- <literal>verticalAlignment</literal>
+ <literal>style</literal>
</term>
<listitem>
- <para> </para>
+ <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>extraParagraphSpace</literal>
+ <literal>listSymbol</literal>
</term>
<listitem>
- <para> </para>
+ <para>For bulleted lists, specifies the bullet symbol. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>fixedHeight</literal>
+ <literal>indent</literal>
</term>
<listitem>
- <para> </para>
+ <para>The indentation level of the list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>noWrap</literal>
+ <literal>lowerCase</literal>
</term>
<listitem>
- <para> </para>
+ <para>For list styles using letters, indicates whether the letters should be lower case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>minimumHeight</literal>
+ <literal>charNumber</literal>
</term>
<listitem>
- <para> </para>
+ <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>followingIndent</literal>
+ <literal>alignment</literal>
</term>
<listitem>
- <para> </para>
+ <para>The alignment of the list item. (See <xref linkend="itext.alignment"/> for possible
+ values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>rightIndent</literal>
+ <literal>indentationLeft</literal>
</term>
<listitem>
- <para> </para>
+ <para>The left indentation amount.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>spaceCharRatio</literal>
+ <literal>indentationRight</literal>
</term>
<listitem>
- <para> </para>
+ <para>The right indentation amount.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>runDirection</literal>
+ <literal>listSymbol</literal>
</term>
<listitem>
- <para> </para>
+ <para>Overrides the default list symbol for this list item.</para>
</listitem>
</varlistentry>
+ </variablelist>
+ </section>
+ </section>
+
+ <section id="itext.tables">
+ <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. Header and footer rows can be declared, and the headers and footers
+ will be repeated in the event a table structure spans multiple pages.</para>
+
+ <programlisting>
+<p:document xmlns:p="http://jboss.com/products/seam/pdf"
+ xmlns:ui="http://java.sun.com/jsf/facelets"
+ title="Hello">
+ <p:table columns="3" headerRows="1">
+ <p:cell>name</p:cell>
+ <p:cell>owner</p:cell>
+ <p:cell>size</p:cell>
+ <ui:repeat value="#{documents}" var="doc">
+ <p:cell>#{doc.name}</p:cell>
+ <p:cell>#{doc.user.name}</p:cell>
+ <p:cell>#{doc.size}</p:cell>
+ </ui:repeat>
+ </p:table>
+</p:document>
+ </programlisting>
+
+
+ <section>
+ <title>p:table</title>
+ <para><literal>p:table</literal> supports the following attributes.</para>
+ <variablelist>
<varlistentry>
<term>
- <literal>arabicOptions</literal>
+ <literal>columns</literal>
</term>
<listitem>
- <para> </para>
+ <para>The number of columns (cells) that make up a table row.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>useAscender</literal>
+ <literal>widths</literal>
</term>
<listitem>
- <para> </para>
+ <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>grayFill</literal>
+ <literal>headerRows</literal>
</term>
<listitem>
- <para> </para>
+ <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>rotation</literal>
+ <literal>footerRows</literal>
</term>
<listitem>
- <para> </para>
+ <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>
- </variablelist>
- </section>
- </section>
-
- <section>
- <title>Basic Text Elements</title>
-
- <para>Text can be placed anywhere in the document template, but it is often desirable to surround text with
- either structural tags or formatting tags to control the rendering of the text. </para>
-
- <section>
- <title>p:paragraph</title>
- <para>Most uses of text should be sectioned into paragraphs so that text fragments can be flowed, formatted
- and styled in logical groups. </para>
- <variablelist>
<varlistentry>
<term>
- <literal>firstLineIndent</literal>
+ <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>
@@ -731,7 +835,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>extraParagraphSpace</literal>
+ <literal>runDirection</literal>
</term>
<listitem>
<para> </para>
@@ -739,7 +843,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>leading</literal>
+ <literal>lockedWidth</literal>
</term>
<listitem>
<para> </para>
@@ -747,7 +851,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>multipliedLeading</literal>
+ <literal>splitRows</literal>
</term>
<listitem>
<para> </para>
@@ -771,7 +875,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>indentationLeft</literal>
+ <literal>extendLastRow</literal>
</term>
<listitem>
<para> </para>
@@ -779,7 +883,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>indentationRight</literal>
+ <literal>headersInEvent</literal>
</term>
<listitem>
<para> </para>
@@ -787,138 +891,111 @@
</varlistentry>
<varlistentry>
<term>
- <literal>keepTogether</literal>
+ <literal>splitLate</literal>
</term>
<listitem>
<para> </para>
</listitem>
</varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>p:text</title>
- <para>The <literal>text</literal> tag allows text fragments to be produced from application data using
- normal JSF converter mechanisms. It is very similar to the <literal>outputText</literal> tag used when
- rendering HTML documents. Here is an example: </para>
-
- <programlisting>
-<p:paragraph>
- The item costs <p:text value="#{product.price}">
- <f:convertNumber type="currency" currencySymbol="$"/>
- </p:text>
-</p:paragraph>
- </programlisting>
-
- <variablelist>
<varlistentry>
<term>
- <literal>value</literal>
+ <literal>keepTogether</literal>
</term>
<listitem>
- <para>The value to be displayed. This will typically be a value binding expression.</para>
+ <para> </para>
</listitem>
</varlistentry>
</variablelist>
</section>
+
<section>
- <title>p:font</title>
- <para>Font declarations have no direct </para>
+ <title>p:cell</title>
+
+ <para><literal>p:cell</literal> supports the following attributes.</para>
+
<variablelist>
<varlistentry>
<term>
- <literal>familyName</literal>
+ <literal>colspan</literal>
</term>
<listitem>
- <para>The font family. One of: <literal>COURIER</literal>, <literal>HELVETICA</literal>,
- <literal>TIMES-ROMAN</literal>, <literal>SYMBOL</literal> or
- <literal>ZAPFDINGBATS</literal>.</para>
+ <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>size</literal>
+ <literal>horizontalAlignment</literal>
</term>
<listitem>
- <para>The point size of the font.</para>
+ <para>The horizontal alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
+ values)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>style</literal>
+ <literal>verticalAlignment</literal>
</term>
<listitem>
- <para>The font styles. Any combination of : <literal>NORMAL</literal>, <literal>BOLD</literal>,
- <literal>ITALIC</literal>, <literal>OBLIQUE</literal>, <literal>UNDERLINE</literal>, <literal>LINE-THROUGH</literal></para>
+ <para>The vertical alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
+ values)</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>
+ <literal>padding</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>
+ <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>rotation</literal>
+ <literal>useBorderPadding</literal>
</term>
<listitem>
- <para>The rotation of the image in degrees.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>height</literal>
+ <literal>leading</literal>
</term>
<listitem>
- <para>The height of the image.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>width</literal>
+ <literal>multipliedLeading</literal>
</term>
<listitem>
- <para>The width of the image.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>alignment</literal>
+ <literal>indent</literal>
</term>
<listitem>
- <para>The alignment of the image. (see <xref linkend="itext.alignment"/> for possible values)
- </para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>alt</literal>
+ <literal>verticalAlignment</literal>
</term>
<listitem>
- <para>Alternative text representation for the image.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>indentationLeft</literal>
+ <literal>extraParagraphSpace</literal>
</term>
<listitem>
<para> </para>
@@ -926,7 +1003,7 @@
</varlistentry>
<varlistentry>
<term>
- <literal>indentationRight</literal>
+ <literal>fixedHeight</literal>
</term>
<listitem>
<para> </para>
@@ -934,31 +1011,32 @@
</varlistentry>
<varlistentry>
<term>
- <literal>spacingBefore</literal>
+ <literal>noWrap</literal>
</term>
<listitem>
- <para>The blank space to be inserted before the element.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>spacingAfter</literal>
+ <literal>minimumHeight</literal>
</term>
<listitem>
- <para>The blank space to be inserted after the element.</para>
+ <para> </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
- <literal>widthPercentage</literal>
+ <literal>followingIndent</literal>
</term>
<listitem>
- <para/>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>initialRotation</literal>
+ <literal>rightIndent</literal>
</term>
<listitem>
<para> </para>
@@ -966,25 +1044,23 @@
</varlistentry>
<varlistentry>
<term>
- <literal>dpi</literal>
+ <literal>spaceCharRatio</literal>
</term>
<listitem>
- <para/>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>scalePercent</literal>
+ <literal>runDirection</literal>
</term>
<listitem>
- <para>The scaling factor (as a percentage) to use for the image. This can be expressed as a
- single percentage value or as two percentage values representing separate x and y scaling
- percentages.</para>
+ <para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <literal>wrap</literal>
+ <literal>arabicOptions</literal>
</term>
<listitem>
<para> </para>
@@ -992,50 +1068,39 @@
</varlistentry>
<varlistentry>
<term>
- <literal>underlying</literal>
+ <literal>useAscender</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>
+ <literal>grayFill</literal>
</term>
<listitem>
- <para>The name of an in-document anchor destination.</para>
+ <para> </para>
</listitem>
</varlistentry>
-
<varlistentry>
<term>
- <literal>reference</literal>
+ <literal>rotation</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>
+ <para> </para>
</listitem>
</varlistentry>
-
-
</variablelist>
</section>
</section>
- <section>
+
+
+ <section id="itext.constant">
<title>Document Constants</title>
+
+ <para>This section documents some of the constants shared by attributes on multiple tags. </para>
+
<section id="itext.color">
<title>Color Values</title>
<para>Seam documents do not yet support a full color specification. Currently, only named colors are
@@ -1048,15 +1113,59 @@
<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>
+ <para> Where alignment values are used, the Seam PDF supports the following horizontal alignment values:
+ <literal>left</literal>, <literal>right</literal>, <literal>center</literal>,
+ <literal>justify</literal> and <literal>justifyall</literal>. The vertical alignment values are
+ <literal>top</literal>, <literal>middle</literal>, <literal>bottom</literal>, and
+ <literal>baseline</literal>.</para>
</section>
</section>
+ <section id="itext.configuration">
+ <title>Configuring iText</title>
- <section>
+ <para>Document generation works out of the box with no additional configuration needed. However, there are a few
+ points of configuration that are needed for more serious applications. </para>
+
+ <para> The default implementation serves PDF documents from a generic URL, <literal>/seam-doc.seam</literal>.
+ Many browsers (and users) would prefer to see URLs that contain the actual PDF name like
+ <literal>/myDocument.pdf</literal>. This capability requires some configuration. To serve PDF files, all
+ *.pdf resources should be mapped to the Seam Servlet Filter, as shown here:</para>
+
+ <programlisting>
+<filter>
+ <filter-name>Seam Servlet Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamServletFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>Seam Servlet Filter</filter-name>
+ <url-pattern>*.pdf</url-pattern>
+</filter-mapping>
+</programlisting>
+
+ <para> The <literal>useExtensions</literal> option on the document store component completes the functionality
+ by instructing the document store to generate URLs with the correct filename extension for the document type
+ being generated. </para>
+
+ <programlisting>
+<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:pdf="http://jboss.com/products/seam/pdf">
+ <pdf:documentStore useExtensions="true" />
+</components>
+</programlisting>
+
+ <para> Generated documents are stored in conversation scope and will expire when the conversation ends. At that
+ point, references to the document will be invalid. To You can specify a default view to be shown when a
+ document does not exist using the <literal>errorPage</literal> property of the documentStore. </para>
+ <programlisting>
+<pdf:documentStore useExtensions="true" errorPage="/pdfMissing.seam" />
+</programlisting>
+ </section>
+
+
+ <section id="itext.links">
<title>iText links</title>
<para>For further information on iText, see:</para>
More information about the jboss-cvs-commits
mailing list