Chapter 15. iText PDF generation - JBoss Seam 1.1.5 正式版英文参考手册
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.
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.
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/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.
Documents are generated by facelets documents 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. The following is a a small PDF document consisting only a single line of text:
<p:document xmlns:p="http://jboss.com/products/seam/pdf">
A very tiny PDF
</p:document>
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 ui:repeat tag to to display a list of values retrieved from a Seam component.
<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>
The p:document tag supports the following attributes:
- type
The type of the document to be produced. Valid values are PDF, RTF and HTML modes. Seam defaults to PDF generation, and many of the features only work correctly when generating PDF documents.
- pageSize
The size of the page to be generate. The most commonly used values would be LETTER and A4. A full list of supported pages sizes can be found in com.lowagie.text.PageSize class. Alternatively, pageSize can provide the width and height of the page directly. The value "612 792", for example, is equizalent to the LETTER page size.
- orientation
The orientation of the page. Valid values are portrait and landscape. In landscape mode, the height and width page size values are reversed.
- margins
The left, right, top and bottom margin values.
- marginMirroring
Indicates that margin settings should be reversed an alternating pages.
Document metadata is also set as attributes of the document tag. The following metadata fields are supported:
- title
- subject
- keywords
- author
- creator
The p:header and p:footer 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.
- alignment
The alignment of the header/footer box section. (see Section 15.8.2, “Alignment Values” for alignment values)
- backgroundColor
The background color of the header/footer box. (see Section 15.8.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 15.8.1, “Color Values” for color values)
- borderWidth
The width of the border. Inidvidual border sides can be specified using borderWidthLeft, borderWidthRight, borderWidthTop and borderWidthBottom.
If the generated document follows a book/article structure, the p:chapter and p:section tags can be used to provide the necessary structure. Sections can only be used inside of chapters, but they may be nested arbitrarily deep.
- 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 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.
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.
p:list supports the following attributes:
- style
The ordering/bulleting style of list. One of: NUMBERED, LETTERED, GREEK, ROMAN, ZAPFDINGBATS, ZAPFDINGBATS_NUMBER. If no style is given, the list items are bulleted.
- 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.
p:listItem supports the following attributes:
- alignment
The alignment of the list item. (See Section 15.8.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.
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.
p:table supports the following 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 3 columns and the first column should be twice the size of the second and third column.
- headerRows
The initial number of rows which are considered to be headers or footer rows and should be repeated if the table spans multiple pages.
- footerRows
The number of rows that are considered to be footer rows. This value is subtracted from the headerRows value. If document has 2 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 that the table spans.
- horizontalAlignment
The horizontal alignment of the table. (See Section 15.8.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
p:cell supports the following attributes.
- colspan
Cells can span more than one column by declaring a colspan greater than 1. Tables do not have the ability to span across multiple rows.
- horizontalAlignment
The horizontal alignment of the cell. (see Section 15.8.2, “Alignment Values” for possible values)
- verticalAlignment
The vertical alignment of the cell. (see Section 15.8.2, “Alignment Values” for possible values)
- padding
Padding on a given side can also be specified using paddingLeft, paddingRight, paddingTop and paddingBottom.
- useBorderPadding
- leading
- multipliedLeading
- indent
- verticalAlignment
- extraParagraphSpace
- fixedHeight
- noWrap
- minimumHeight
- followingIndent
- rightIndent
- spaceCharRatio
- runDirection
- arabicOptions
- useAscender
- grayFill
- rotation
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.
Most uses of text should be sectioned into paragraphs so that text fragments can be flowed, formatted and styled in logical groups.
- 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
The text tag allows text fragments to be produced from application data using normal JSF converter mechanisms. It is very similar to the outputText tag used when rendering HTML documents. Here is an example:
<p:paragraph>
The item costs <p:text value="#{product.price}">
<f:convertNumber type="currency" currencySymbol="$"/>
</p:text>
</p:paragraph>
- value
The value to be displayed. This will typically be a value binding expression.
Font declarations have no direct
- familyName
The font family. One of: 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
p:image inserts an image into the document.
- resource
The location of the image resource to be included. Resources should be relative to the document root of the web application.
- 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 15.8.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
p:anchor defines clickable links from a document. It supports the following 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 postion with a name of link1. Links may also be a full URL to point to a resource outside of the document.
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.