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
type
The type of the document to be produced. Valid values are PDF, RTF and HTML. Seam defaults to PDF generation, and many features only work correctly when generating PDF documents.
pageSize
The size of the page to be generated. The most commonly used values are LETTER and A4. A full list of supported pages sizes can be found in the com.lowagie.text.PageSize class. Alternatively, pageSize can provide the width and height of the page directly. The value "612 792", for example, is equivalent to the LETTER page size.
orientation
The orientation of the page. Valid values are portrait and landscape. Landscape mode swaps the height and width page values.
margins
The left, right, top and bottom margin values.
marginMirroring
Indicates that margin settings should be reversed on alternating pages.
disposition
When generating PDFs in a web browser, this determines the HTTP Content-Disposition of the document. Valid values are inline, which indicates the document should be displayed in the browser window if possible, and attachment, which indicates that the document should be treated as a download. The default value is inline.
fileName
For attachments, this value overrides the downloaded file name.
Metadata Attributes
  • title
  • subject
  • keywords
  • author
  • creator
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
  • firstLineIndent
  • extraParagraphSpace
  • leading
  • multipliedLeading
  • spacingBefore — The blank space to be inserted before the element.
  • spacingAfter — The blank space to be inserted after the element.
  • indentationLeft
  • indentationRight
  • keepTogether
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
  • value — The value to be displayed. This is typically a value binding expression.
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
  • value — The text to be displayed.
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
  • name — The font name, for example: COURIER, HELVETICA, TIMES-ROMAN, SYMBOL or ZAPFDINGBATS.
  • size — The point size of the font.
  • style — The font styles. Any combination of : NORMAL, BOLD, ITALIC, OBLIQUE, UNDERLINE, LINE-THROUGH
  • encoding — The character set encoding.
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
  • left — The left bounds of the text column
  • right — The right bounds of the text column
  • direction — The run direction of the text in the column: RTL, LTR, NO-BIDI, DEFAULT
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
  • value — A resource name or a method expression that binds to an application-generated image.
  • rotation — The rotation of the image in degrees.
  • height — The height of the image.
  • width — The width of the image.
  • alignment — The alignment of the image. (See Section 18.1.7.2, “Alignment Values” for possible values.)
  • alt — Alternative text representation for the image.
  • indentationLeft
  • indentationRight
  • spacingBefore — The blank space to be inserted before the element.
  • spacingAfter — The blank space to be inserted after the element.
  • widthPercentage
  • initialRotation
  • dpi
  • scalePercent — 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.
  • wrap
  • underlying
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
  • name — The name of an in-document anchor destination.
  • reference — 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 position with a name of link1. To point to a resource outside the document, links must be a complete URL.
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
  • alignment — The alignment of the header/footer box section. (See Section 18.1.7.2, “Alignment Values” for alignment values.)
  • backgroundColor — The background color of the header/footer box. (See Section 18.1.7.1, “Color Values” for color values.)
  • borderColor — The border color of the header/footer box. Individual border sides can be set using borderColorLeft, borderColorRight, borderColorTop and borderColorBottom. (See Section 18.1.7.1, “Color Values” for color values.)
  • borderWidth — The width of the border. Individual border sides can be specified using borderWidthLeft, borderWidthRight, borderWidthTop and borderWidthBottom.
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
  • alignment — The alignment of the header/footer box section. (See Section 18.1.7.2, “Alignment Values” for alignment values.)
  • number — The chapter number. Every chapter should be assigned a chapter number.
  • numberDepth — The depth of numbering for section. All sections are numbered relative to their surrounding chapters/sections. The fourth section of the first section of chapter three would be section 3.1.4, if displayed at the default number depth of 3. To omit the chapter number, a number depth of 2 should be used — this would display the section number as 1.4.
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
  • style — The ordering/bulleting style of the list. One of: NUMBERED, LETTERED, GREEK, ROMAN, ZAPFDINGBATS, ZAPFDINGBATS_NUMBER. If no style is given, the list items are bulleted by default.
  • listSymbol — For bulleted lists, specifies the bullet symbol.
  • indent — The indentation level of the list.
  • lowerCase — For list styles using letters, indicates whether the letters should be lower case.
  • charNumber — For ZAPFDINGBATS, indicates the character code of the bullet character.
  • numberType — For ZAPFDINGBATS_NUMBER, indicates the numbering style.
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
  • alignment — The alignment of the header/footer box section. (See Section 18.1.7.2, “Alignment Values” for alignment values.)
  • alignment — The alignment of the list item. (See Section 18.1.7.2, “Alignment Values” for possible values.)
  • indentationLeft — The left indentation amount.
  • indentationRight — The right indentation amount.
  • listSymbol — Overrides the default list symbol for this list item.
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
  • columns — The number of columns (cells) that make up a table row.
  • widths — 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 three columns and the first column should be twice the size of the second and third column.
  • headerRows — The initial number of rows considered to be header and footer rows, which should be repeated if the table spans multiple pages.
  • footerRows — The number of rows considered to be footer rows. This value is subtracted from the headerRows value. If document has two rows which make up the header and one row that makes up the footer, headerRows should be set to 3 and footerRows should be set to 1.
  • widthPercentage — The percentage of the page width spanned by the table.
  • horizontalAlignment — The horizontal alignment of the table. (See Section 18.1.7.2, “Alignment Values” for possible values.)
  • skipFirstHeader
  • runDirection
  • lockedWidth
  • splitRows
  • spacingBefore — The blank space to be inserted before the element.
  • spacingAfter — The blank space to be inserted after the element.
  • extendLastRow
  • headersInEvent
  • splitLate
  • keepTogether
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
  • colspan — Cells can span more than one column by declaring a colspan greater than one. Cells cannot span multiple rows.
  • horizontalAlignment — The horizontal alignment of the cell. (See Section 18.1.7.2, “Alignment Values” for possible values.)
  • verticalAlignment — The vertical alignment of the cell. (See Section 18.1.7.2, “Alignment Values” for possible values.)
  • padding — Specify padding on a particular side using paddingLeft, paddingRight, paddingTop and paddingBottom.
  • useBorderPadding
  • leading
  • multipliedLeading
  • indent
  • verticalAlignment
  • extraParagraphSpace
  • fixedHeight
  • noWrap
  • minimumHeight
  • followingIndent
  • rightIndent
  • spaceCharRatio
  • runDirection
  • arabicOptions
  • useAscender
  • grayFill
  • rotation
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.