SeamFramework.orgCommunity Documentation
Seam now includes a 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.
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 supportfon.
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.
The examples/itext
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.
|
Description Documents are generated by facelet XHTML files using tags in the
Attributes
Metadata Attributes
Usage <p:document xmlns:p="http://jboss.com/products/seam/pdf"> |
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
<p:image>
and <p:paragraph>
are the
basic foundations of simple documents. Tags like <p:font>
provide style
information to all the content surrounging them.
|
Description Most uses of text should be sectioned into paragraphs so that text fragments can be flowed, formatted and styled in logical groups. Attributes
Usage <p:paragraph alignment="justify"> |
|
Description The Attributes
Usage <p:paragraph> |
|
Description The Attributes
Usage
|
|
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"> |
|
Description
Usage <p:newPage /> |
|
Description
Resources can also be dynamically generated by application code. The
Attributes
Usage <p:image value="/jboss.jpg" /> <p:image value="#{images.chart}" /> |
|
Description
Attributes
Usage <p:listItem><p:anchor reference="#reason1">Reason 1</p:anchor></p:listItem> |
|
Description The Attributes
Usage <p:facet name="header"> |
|
Description The current page number can be placed inside of a header or footer using the
Usage <p:footer borderWidthTop="1" borderColorTop="blue" |
|
Description If the generated document follows a book/article structure, the
Attributes
Usage <p:document xmlns:p="http://jboss.com/products/seam/pdf" |
|
Description Any chapter or section can contain a |
List structures can be displayed using the p:list
and p:listItem
tags. Lists may contain arbitrarily-nested sublists. List items may not be used outside of a list. he
following document uses the ui:repeat
tag to 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>
|
Attributes
Usage <p:list style="numbered"> |
|
Description
Attributes
Usage ... |
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 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.
|
Description
Attributes
Usage <p:table columns="3" headerRows="1"> |
|
Description
Attributes
Usage <p:cell>...</p:cell> |
This section documents some of the constants shared by attributes on multiple tags.
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
.
Charting support is also provided with jboss-seam-pdf.jar
. Charts can be used in PDF
documents or can be used as images in an HTML page. Charting requires the JFreeChart library
(jfreechart.jar
and jcommon.jar
) to be added to the
WEB-INF/lib
directory. Three types of charts are currently supported: pie charts, bar
charts and line charts.
|
Description Displays a bar chart. Attributes
Usage <p:barchart title="Bar Chart" legend="true" |
|
Description Displays a line chart. Attributes
Usage <p:linechart title="Line Chart" |
|
Description Displays a pie chart. Attributes
Usage <p:piechart title="Pie Chart" circular="false" direction="anticlockwise" |
|
Description Category data can be broken down into series. The series tag is used to categorize a set of data with a series and apply styling to the entire series. Attributes
Usage <p:series key="data1"> |
|
Description The data tag describes each data point to be displayed in the graph. Attributes
Usage <p:data key="foo" value="20" sectionPaint="#111111" |
|
Description The color component declares a color or gradient than can be referenced when drawing filled shapes. Attributes
Usage <p:color id="foo" color="#0ff00f"/> |
|
Description Describes a stroke used to draw lines in a chart. Attributes
Usage <p:stroke id="dot2" width="2" cap="round" join="bevel" dash="2 3" /> |
Seam can use iText to generate barcodes in a wide variety of formats. These barcodes can be embedded in a PDF document or displayed as an image on a web page. Note that when used with HTML images, barcodes can not currently display barcode text in the barcode.
|
Description Displays a barcode image. Attributes
Usage <p:barCode type="code128" |
Seam now provides experimental support for rendering Swing components to into a PDF image. Some Swing look and feels supports, notably ones that use native widgets, will not render correctly.
|
Description Renders a Swing component into a PDF document. Attributes
Usage <p:swing width="310" height="120" component="#{aButton}" /> |
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.
The default implementation serves PDF documents from a generic URL,
/seam-doc.seam
. Many browsers (and users) would prefer to see URLs that contain the
actual PDF name like /myDocument.pdf
. This capability requires some configuration. To
serve PDF files, all *.pdf
resources should be mapped to the DocumentStoreServlet:
<servlet>
<servlet-name>Document Store Servlet</servlet-name>
<servlet-class>org.jboss.seam.document.DocumentStoreServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Document Store Servlet</servlet-name>
<url-pattern>*.pdf</url-pattern>
</servlet-mapping>
The use-extensions
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.
<components xmlns="http://jboss.com/products/seam/document"
xmlns:pdf="http://jboss.com/products/seam/document">
<document:document-store use-extensions="true" />
</components>
The document store stores documents in conversation scope, and documents will expire when the conversation ends. At
that point, references to the document will be invalid. You can specify a default view to be shown
when a document does not exist using the error-page
property of the documentStore
.
<document:document-store use-extensions="true" error-page="/documentMissing.seam" />