第18章 iText PDF 生成

Seam には iText を使用してドキュメント生成を行うためのコンポーネントセットが含まれています。 Seam iText ドキュメントサポートの主な狙いは PDF ドキュメントの生成ですが、 RTF ドキュメント生成に対しても基本的なサポートを提供します。

18.1. PDF サポートの使用

iText サポートは jboss-seam-pdf.jar により提供されます。 この JAR には iText JSF コントロール (PDF にレンダリング可能なビューを構成) と DocumentStore コンポーネント (ユーザーにレンダリングしたドキュメントを提供) が含まれます。 アプリケーションに PDF サポートを含ませるには jboss-seam-pdf.jar を WEB-INF/lib ディレクトリに iText の JAR ファイルと共に含ませます。 Seam の iText サポートを使用する上で必要な設定はこれだけです。
Seam iText モジュールにはビューテクノロジーとして Facelets を使用する必要があります。 ライブラリの今後のバージョンも JSP の使用に対応する可能性があります。 また、 seam-ui パッケージの使用も必要となります。
examples/itext プロジェクトには実行可能なデモ用 PDF サポートのサンプルが含まれています。 正確なパッケージ化の導入を行い、 現在サポートされている PDF 生成の主要な機能を実際に示すサンプルがいくつか含まれています。

18.1.1. ドキュメントの作成

<p:document>
説明
ドキュメントは http://jboss.com/products/seam/pdf 名前空間にあるタグを使い Facelet XHTML ファイルで生成されます。ドキュメントにはそのルートに必ず document タグがあるはずです。document タグは Seam が ドキュメントを DocumentStore に生成し、その格納コンテンツに HTML リダイレクトをレンダリングするよう準備を行います。
Attributes
type
生成されるドキュメントのタイプです。有効な値は PDF、RTF、HTML です。Seam のデフォルト設定は PDF 生成となるため、多くの機能は PDF ドキュメント生成時にのみ正常に動作します。
pageSize
生成されるページのサイズです。最も一般的に使用される値は、LETTER と A4 です。対応するページサイズの全一覧は、com.lowagie.text.PageSize クラスにあります。代わりに、pageSize は直接、ページの幅と高さを示すことも可能です。例えば、値「612 792」は LETTER ページサイズと同じです。
orientation
ページの向きです。有効な値は portrait と landscape です。横向きモードではページの高さと幅のサイズ値が逆になります。
margins
左右と上下の余白の値です。
marginMirroring
余白の設定が交互のページで逆になることを示します。
disposition
Web ブラウザで PDF を生成する場合に、ドキュメントの HTTP Content-Disposition を決定します。 有効な値は、 可能であればブラウザウィンドウ内にドキュメントを表示させることを表す inline と、 ドキュメントをダウンロードとして処理することを表す attachment です。 デフォルト値は inline です。
fileName
添付用です。 この値はダウンロードしたファイル名を上書きします。
メタデータ属性
  • title
  • subject
  • keywords
  • author
  • creator
使用方法 
<p:document xmlns:p="http://jboss.com/products/seam/pdf"> 
  The document goes here. 
</p:document>

18.1.2. 基本的なテキストのエレメント

Seam では PDF に適したコンテンツを生成できるよう特殊な UI コンポーネントを提供します。 <p:image> タグと <p:paragraph> タグはシンプルなドキュメントの基盤を形成します。 <p:font> のようなタグはスタイル情報を提供します。
<p:paragraph>
説明
ほとんどの場合、 テキストを段落ごとに区切ることでテキストの断片に論理的な流れやフォーマットおよびスタイルを与えることができるようになります。
Attributes
  • firstLineIndent
  • extraParagraphSpace
  • leading
  • multipliedLeading
  • spacingBefore — エレメントの前に空白スペースが挿入されます。
  • spacingAfter — エレメントの後に空白スペースが挿入されます。
  • indentationLeft
  • indentationRight
  • keepTogether
使用方法 
<p:paragraph alignment="justify">
  This is a simple document. It isn't very fancy. 
</p:paragraph>
<p:text>
説明
text タグにより通常の JSF 変換メカニズムを使用して、アプリケーションデータからテキストの断片を生成することができます。HTML ドキュメントをレンダリングする場合に使用する outputText タグと非常に似ています。
Attributes
  • value — 表示される値です。 一般的には値バインディング式になります。
使用方法 
<p:paragraph> 
  The item costs <p:text value="#{product.price}"> 
    <f:convertNumber type="currency" 
                     currencySymbol="$"/> 
  </p:text> 
</p:paragraph>
<p:html>
説明
html タグは HTML コンテンツを PDF にレンダリングします。
Attributes
  • value — 表示されるテキストです。
使用方法 
<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>
説明
font タグはその中のすべてのテキストに使用されるデフォルトフォントを定義します。
Attributes
  • name — フォントの名前です。例えば、COURIER、HELVETICA、TIMES-ROMAN、SYMBOL、ZAPFDINGBATS です。
  • size — フォントのポイントサイズです。
  • style — フォントのスタイルです。以下の組み合わせとなります。NORMAL、BOLD、ITALIC、OBLIQUE、UNDERLINE、LINE-THROUGH
  • encoding — 文字セットエンコーディングです。
使用方法 
<p:font name="courier" style="bold" size="24"> 
  <p:paragraph>My Title</p:paragraph> 
</p:font>
<p:textcolumn>
説明
p:textcolumn はテキストの流れを制御するために使用可能なテキスト列を挿入します。最も一般的な使用方法は、右から左の方向のフォントに対応することです。
Attributes
  • left — テキスト列の左の範囲です。
  • right — テキスト列の右の範囲です。
  • direction — 列のテキスト表記の向きです。RTL、LTR、NO-BIDI、DEFAULT
使用方法 
<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>
説明
p:newPage は改ページを挿入します。
使用方法 
<p:newPage />
<p:image>
説明
p:image は画像をドキュメントに挿入します。画像はクラスパスまたは Web アプリケーションコンテキストから value 属性を使ってロードすることができます。
リソースはアプリケーションコードで動的に生成することもできます。 imageData 属性は値バインディング式を指定することができ、 この値は java.awt.Image オブジェクトです。
Attributes
  • value — アプリケーションが生成した画像にバインドするリソース名またはメソッド式です。
  • rotation — 度数で表される画像の回転です。
  • height — 画像の高さです。
  • width — 画像の幅です。
  • alignment — 画像の位置です (可能な値については 「位置調整の値」 を参照)。
  • alt — 画像の別のテキスト表現です。
  • indentationLeft
  • indentationRight
  • spacingBefore — エレメントの前に空白スペースが挿入されます。
  • spacingAfter — エレメントの後に空白スペースが挿入されます。
  • widthPercentage
  • initialRotation
  • dpi
  • scalePercent — 画像に使用する倍率です (パーセンテージ)。単一のパーセンテージ値として表すか、x と y の別々の倍率値を表す 2 つのパーセンテージ値として表すこともできます。
  • wrap
  • underlying
使用方法 
<p:image value="/jboss.jpg" />

<p:image value="#{images.chart}" />
<p:anchor>
説明
p:anchor はドキュメントからクリックできるリンクを定義します。次の属性に対応します。
Attributes
  • name — ドキュメント内のアンカーの目的点の名前です。
  • reference — リンクの参照先です。ドキュメント内の別のポイントへのリンクは「#」で開始します。例えば「#link1」は link1 の name が付いたアンカーの位置を参照します。ドキュメントの外にあるリソースをポイントするには、リンクは完全な URL である必要があります。
使用方法 
<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. ヘッダーとフッター

<p:header>
<p:footer>
説明
p:header と p:footer のコンポーネントにより、生成されたドキュメントの各ページにヘッダーとフッターを配置します。ヘッダーとフッターの宣言はドキュメントの冒頭に出現するはずです。
Attributes
  • alignment — ヘッダーとフッターのボックスセクションの位置です (位置の値については 「位置調整の値」 を参照)。
  • backgroundColor — ヘッダーとフッターボックスの背景色です (色の値については 「色の値」 を参照)。
  • borderColor — ヘッダーとフッターボックスの境界線の色です。borderColorLeft、borderColorRight、borderColorTop、borderColorBottom を使用して境界線ごとに設定が可能です (色の値については 「色の値」 を参照)。
  • borderWidth — 境界線の太さです。borderWidthLeft、borderWidthRight、borderWidthTop、borderWidthBottom を使用して境界線ごとに指定が可能です。
使用方法 
<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>
説明
現在のページ番号は p:pageNumber タグを使うとヘッダーまたはフッターの内側に配置できます。このページ番号タグはヘッダーまたはフッターのコンテキスト内でのみ、1 度だけ使用可能です。
使用方法 
<p:footer borderWidthTop="1" borderColorTop="blue" 
   borderWidthBottom="0" alignment="center"> 
  Why Seam? [<p:pageNumber />] 
</p:footer>

18.1.4. 章とセクション

<p:chapter>
<p:section>
説明
生成されるドキュメントが book または article の構造をとる場合、p:chapter と p:section のタグを使用して構成することができます。セクションは章の内側でのみ使用できますが、必要に応じていずれの深さにもネストさせることができます。ほとんどの PDF ビューアはドキュメント内の章とセクション間を簡単に移動できる機能を備えています。
Attributes
  • alignment — ヘッダーとフッターのボックスセクションの位置です (位置の値については 「位置調整の値」 を参照)。
  • number — 章番号です。 各章すべてに章番号を割り当ててください。
  • numberDepth — セクションの番号付けの深さです。すべてのセクションはその前後の章やセクションに応じて番号が付けられます。デフォルトの番号の深さ 3 で表示すると、第 3 章の第 1 セクションにある 4 番目のセクションは 3.1.4 となります。章番号を省略するには、番号の深さに 2 を使用します。この場合、セクション番号は 1.4 と表示されます。
使用方法 
<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>
説明
いずれの章やセクションにも p:title を含むことができます。タイトルは章やセクション番号の隣に表示されます。タイトルの本文には raw テキストを含めるか、p:paragraph とすることも可能です。

18.1.5. 一覧

一覧の構成は p:list と p:listItem のタグを使って表示させることができます。 一覧には適宜ネストされたサブリストを含ませることもできます。 一覧のアイテムは一覧の外側では使用できません。 次のドキュメントは ui:repeat タグを使って Seam コンポーネントから取得した値の一覧を表示しています。 
<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 — 一覧の並び順や箇条書きのスタイルです。NUMBERED、LETTERED、GREEK、ROMAN、ZAPFDINGBATS、ZAPFDINGBATS_NUMBER のいずれかです。スタイルの指定がない場合は、一覧のアイテムはデフォルトで箇条書きになります。
  • listSymbol — 箇条書きリストの場合、 箇条書きの文の前に付ける記号を指定します。
  • indent — 一覧のインデントのレベルです。
  • lowerCase — 文字を使った一覧スタイルの場合、 その文字を小文字にするかどうかを示します。
  • charNumber — ZAPFDINGBATS の場合、 箇条書きに使用する文字コードを示します。
  • numberType — ZAPFDINGBATS_NUMBER の場合、 番号付けのスタイルを示します。
使用方法 
<p:list style="numbered"> 
  <ui:repeat value="#{documents}" var="doc">
    <p:listItem>#{doc.name}</p:listItem> 
  </ui:repeat> 
</p:list>
<p:listItem>
説明
p:listItem は次の属性に対応しています。
Attributes
  • alignment — ヘッダーとフッターのボックスセクションの位置です (位置の値については 「位置調整の値」 を参照)。
  • alignment — 一覧アイテムの位置です (可能な値については 「位置調整の値」 を参照)。
  • indentationLeft — 左のインデントの数です。
  • indentationRight — 右のインデントの数です。
  • listSymbol — この一覧のアイテムに対しデフォルトの一覧の記号を上書きします。
使用方法 
...

18.1.6. 表

表の構成は p:table と p:cell のタグを使って作成することができます。 多くの表構成とは異なり、明示的な行の宣言はありません。 表に列が 3 つある場合は、3 セルで自動的に行を 1 つ形成します。 ヘッダーとフッターの行を宣言することができ、 表の構成が複数ページに渡る場合にはヘッダーとフッターは繰り返し使用されます。
<p:table>
説明
p:table は次の属性に対応しています。
Attributes
  • columns — 表の 1 行を構成する列数 (セル数) です。
  • widths — 各列の相対幅です。各列に対して値は 1 つです。例えば、widths="2 1 1" の場合、列は 3 つあり 1 番目の列幅は 2 番目と 3 番目の列の 2 倍になることを示しています。
  • headerRows — ヘッダーとフッターの行とみなされる最初の行数です。 表が複数ページに渡る場合は繰り返し使用されます。
  • footerRows — フッターの行とみなされる行数です。headerRows 値からこの値が差し引かれます。ヘッダーを構成する行が 2 つ、フッターを構成する行が 1 つあるドキュメントの場合、headerRows は 3 に footerRows は 1 にそれぞれ設定されます。
  • widthPercentage — 表でまたがるページ幅の割合です。
  • horizontalAlignment — 表の水平位置です (可能な値については 「位置調整の値」 を参照)。
  • skipFirstHeader
  • runDirection
  • lockedWidth
  • splitRows
  • spacingBefore — エレメントの前に空白スペースが挿入されます。
  • spacingAfter — エレメントの後に空白スペースが挿入されます。
  • extendLastRow
  • headersInEvent
  • splitLate
  • keepTogether
使用方法 
<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>
説明
p:cell は次の属性に対応しています。
Attributes
  • colspan — colspan を 1 より大きい値に宣言することでセルが複数の列にまたがることができます。セルは複数行にまたがることはできません。
  • horizontalAlignment — セルの水平位置です (可能な値については 「位置調整の値」 を参照)。
  • verticalAlignment — セルの垂直位置です (可能な値については 「位置調整の値」 を参照)。
  • padding — paddingLeft、paddingRight、paddingTop、paddingBottom を使って特定のサイドのパディングを指定します。
  • useBorderPadding
  • leading
  • multipliedLeading
  • indent
  • verticalAlignment
  • extraParagraphSpace
  • fixedHeight
  • noWrap
  • minimumHeight
  • followingIndent
  • rightIndent
  • spaceCharRatio
  • runDirection
  • arabicOptions
  • useAscender
  • grayFill
  • rotation
使用方法 
<p:cell>...</p:cell>

18.1.7. ドキュメントの定数

本項では複数のタグで属性により共有される定数をいくつか説明します。

18.1.7.1. 色の値

Seam のドキュメントはまだフルカラー仕様に対応していません。 現在、 次の指定色にのみ対応しています。white、 gray、 lightgray、 darkgray、 black、 red、 pink、 yellow、 green、 magenta、 cyan、 blue です。

18.1.7.2. 位置調整の値

Seam PDF は次の横方向の位置調整値、 left、 right、 center、 justify、 justifyall に対応します。 縦方向の値は top、 middle、 bottom、 baseline です。