Chapter 18. iText PDF generation
Seam now includes a component set for generating documents with iText. The primary focus of Seam's iText document support is for the generation of PDF documents, but Seam also offers basic support for RTF document generation.
18.1. Using PDF Support
iText support is provided by
jboss-seam-pdf.jar
. This JAR
contains the iText JSF controls (which 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, place jboss-seam-pdf.jar
in your WEB-INF/lib
directory along with the iText JAR
file. No further configuration is required to use Seam's iText support.
The Seam iText module requires that Facelets be used as the view technology. Future versions of the library may also support the use of JSP. It also requires the use of the
seam-ui
package.
The
examples/itext
project contains an example of the PDF support in action. It demonstrates proper deployment packaging, and contains several examples demonstrating the key PDF-generation features currently supported.
18.1.1. Creating a document
<p:document>
|
Description
Documents are generated by Facelet XHTML files using tags in the
http://jboss.com/products/seam/pdf namespace. Documents should always have the document 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.
Attributes
Metadata Attributes
Usage
<p:document xmlns:p="http://jboss.com/products/seam/pdf"> The document goes here. </p:document> |
18.1.2. Basic Text Elements
Seam provides special UI components for generating content suitable to PDF.
<p:image>
and <p:paragraph>
tags form the foundations of simple documents. Tags like <p:font>
provide style information.
<p:paragraph>
|
Description
For most purposes, text should be sectioned into paragraphs so that text fragments can be assigned a logical flow, format and style.
Attributes
Usage
<p:paragraph alignment="justify"> This is a simple document. It is not very fancy. </p:paragraph> |
<p:text>
|
Description
The
text tag lets application data produce text fragments using normal JSF converter mechanisms. It is very similar to the outputText tag used when rendering HTML documents.
Attributes
Usage
<p:paragraph> The item costs <p:text value="#{product.price}"> <f:convertNumber type="currency" currencySymbol="$"/> </p:text> </p:paragraph> |
<p:html>
|
Description
The
html tag renders HTML content into the PDF.
Attributes
Usage
<p:html value="This is HTML with <b>some markup</b>" /> <p:html> <h1>This is more complex HTML</h1> <ul> <li>one</li> <li>two</li> <li>three</li> </ul> </p:html> <p:html> <s:formattedText value="*This* is |Seam Text| as HTML. It's very^cool^." /> </p:html> |
<p:font>
|
Description
The
font tag defines the default font to be used for all text inside of it.
Attributes
Usage
<p:font name="courier" style="bold" size="24"> <p:paragraph>My Title</p:paragraph> </p:font> |
<p:textcolumn>
|
Description
p:textcolumn inserts a text column that can be used to control the flow of text. The most common case is to support right to left direction fonts.
Attributes
Usage
<p:textcolumn left="400" right="600" direction="rtl"> <p:font name="/Library/Fonts/Arial Unicode.ttf" encoding="Identity-H" embedded="true">#{phrases.arabic}</p:font> </p:textcolumn> |
<p:newPage>
|
Description
p:newPage inserts a page break.
Usage
<p:newPage /> |
<p:image>
|
Description
p:image inserts an image into the document. Images can be loaded from the classpath or from the web application context using the value attribute.
Resources can also be dynamically generated by application code. The
imageData attribute can specify a value binding expression whose value is a java.awt.Image object.
Attributes
Usage
<p:image value="/jboss.jpg" /> <p:image value="#{images.chart}" /> |
<p:anchor>
|
Description
p:anchor defines clickable links from a document. It supports the following attributes:
Attributes
Usage
<p:listItem> <p:anchor reference="#reason1">Reason 1</p:anchor> </p:listItem> ... <p:paragraph> <p:anchor name="reason1"> It's the quickest way to get "rich" </p:anchor> ... </p:paragraph> |
18.1.3. Headers and Footers
<p:header>
<p:footer>
|
Description
The
p:header and p:footer components let you place header and footer text on each page of a generated document. Header and footer declarations should appear at the beginning of a document.
Attributes
Usage
<p:facet name="header"> <p:font size="12"> <p:footer borderWidthTop="1" borderColorTop="blue" borderWidthBottom="0" alignment="center"> Why Seam? [<p:pageNumber />] </p:footer> </p:font> </f:facet> |
<p:pageNumber>
|
Description
The current page number can be placed inside a header or footer with the
p:pageNumber tag. The page number tag can only be used in the context of a header or footer and can only be used once.
Usage
<p:footer borderWidthTop="1" borderColorTop="blue" borderWidthBottom="0" alignment="center"> Why Seam? [<p:pageNumber />] </p:footer> |
18.1.4. Chapters and Sections
<p:chapter>
<p:section>
|
Description
If the generated document follows a book/article structure, the
p:chapter and p:section tags can be used to provide structure. Sections can only be used inside chapters, but they may be nested to any depth required. Most PDF viewers provide easy navigation between chapters and sections in a document.
Attributes
Usage
<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> |
<p:header>
|
Description
Any chapter or section can contain a
p:title . The title will be displayed next to the chapter or section number. The body of the title may contain raw text or may be a p:paragraph .
|
18.1.5. Lists
List structures can be displayed with the
p:list
and p:listItem
tags. Lists may contain arbitrarily-nested sublists. List items may not be used outside of a list. The following document uses the ui:repeat
tag to display a list of values retrieved from a Seam component.
<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>
<p:list>
|
Attributes
Usage
<p:list style="numbered"> <ui:repeat value="#{documents}" var="doc"> <p:listItem>#{doc.name}</p:listItem> </ui:repeat> </p:list> |
<p:listItem>
|
Description
p:listItem supports the following attributes:
Attributes
Usage
... |
18.1.6. Tables
Table structures can be created using the
p:table
and p:cell
tags. Unlike many table structures, there is no explicit row declaration. If a table has three columns, then every three 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.
<p:table>
|
Description
p:table supports the following attributes.
Attributes
Usage
<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:cell>
|
Description
p:cell supports the following attributes:
Attributes
Usage
<p:cell>...</p:cell> |
18.1.7. Document Constants
This section documents some of the constants shared by attributes on multiple tags.
18.1.7.1. Color Values
Seam documents do not yet support a full color specification. Currently, only named colors are supported. They are:
white
, gray
, lightgray
, darkgray
, black
, red
, pink
, yellow
, green
, magenta
, cyan
and blue
.
18.1.7.2. Alignment Values
Seam PDF supports the following horizontal alignment values:
left
, right
, center
, justify
and justifyall
. The vertical alignment values are top
, middle
, bottom
, and baseline
.