SeamFramework.orgCommunity Documentation
Seamでは素晴らしいJExcelAPI ライブラリを通じて、Microsoft® Excel® スプレッドアプリケーションのスプレッドシートを作成することもできます。作成されたドキュメントはthe Microsoft® Excel® spreadsheet applicationの95、97、2000、XP、2003の各バージョンと互換性があります。現在のところは、ライブラリの機能の内、限定的にいくつかの機能が使えるのみですが、ライブラリで可能なすべてのことをSeamでも可能にすることが最終的な目標です。Seamで可能な操作、今のところ不可能な操作について詳しく知りたい場合は、JExcelAPIのドキュメントを参照して下さい。
Microsoft® Excel® スプレッドアプリケーションはjboss-seam-excel.jar
によって提供されます。このJARは、Microsoft® Excel® スプレッドアプリケーションJSFコントロールを含み、ドキュメント出力のためのビューと、出力済みのドキュメントを保持するためのDocumentStoreコンポーネントを構築するために利用されます。Microsoft® Excel® スプレッドアプリケーションを有効にするためには、jboss-seam-excel.jar
をjxl.jar
と共にWEB-INF/lib
へ配置し、web.xmlにDocumentStoreサーブレットの設定を行います。
Microsoft® Excel® スプレッドアプリケーションのためのSeamモジュールではビューテクノロジーとして Facelets を使用する必要があります。また、 seam-ui パッケージの使用も必要となります。
examples/excel
プロジェクトには実行可能なMicrosoft® Excel® スプレッドアプリケーションのサンプルが含まれています。 サンプルを用いて、適切なデプロイメントや主要な機能を体験することができます。
Microsoft® Excel® スプレッドアプリケーションのスプレッドシートAPIのさまざまな機能を使用するためにモジュールをカスタマイズすることが簡単にできます。ExcelWorkbook
インタフェースを実装し、それをcomponents.xmlに登録して下さい。
<excel:excelFactory>
<property name="implementations">
<key
>myExcelExporter</key>
<value
>my.excel.exporter.ExcelExport</value>
</property>
</excel:excelFactory
>
そして、excel名前空間をcomponentsタグに登録して下さい。
xmlns:excel="http://jboss.com/products/seam/excel"
あとは、myExcelExporter
オブジェクトにUIWorkbook型を設定すると、作成した出力モジュールが使用されます。デフォルトは"jxl"ですが、"csv"を指定することによって、CSV出力を使用することもできます。
ドキュメントを.xls拡張子とともに出力するためのサーブレットの設定の仕方については項18.6. 「iText を設定する」を参照して下さい。
もし、IEで(特にhttpsで)、作成されたファイルを開いた際に問題が発生した場合は、ブラウザの制限が厳しすぎないか(http://www.nwnetworks.com/iezones.htm/を参照)、web.xmlでのセキュリティ制約が厳しすぎないか、またはその両方を確認して下さい。
シートを利用するための基本は簡単です。それは、使いなれた<h:dataTable>
に似ており、List
、Set
、Map
、Array
、DataModel
に結びつけることができます。
<e:workbook xmlns:e="http://jboss.com/products/seam/excel">
<e:worksheet>
<e:cell column="0" row="0" value="Hello world!"/>
</e:worksheet>
</e:workbook>
これはあまり使える例ではありません。もう少し一般的な例を見てみましょう。
<e:workbook xmlns:e="http://jboss.com/products/seam/excel">
<e:worksheet value="#{data}" var="item">
<e:column>
<e:cell value="#{item.value}"/>
</e:column>
</e:worksheet>
</e:workbook>
はじめに、一番外側にはworkbook要素を置きます。これは、箱の役割を果たし、なんの属性も持ちません。その子要素として、worksheet要素を置きます。worksheet要素は二つの属性を持ちます。value="#{data}"はデータを結びつけるためのEL式であり、var="item"は現在のアイテムの名前です。worksheet要素の中には、一つだけcolumn要素があり、その中にはcell要素があります。cell要素はデータの中の列挙されたアイテムの内、現在のアイテムを、最終的に結び付けます。
データをシートに出力するための手始めはこれですべてです。
workbook要素は、一番外側の要素であり、worksheet要素やスタイルシートのためのlink要素の親となります。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:cell value="Hello World" row="0" column="0"/>
</e:worksheet>
<e:workbook>
これは、一つシートを持ち、そのA1セルに挨拶が書かれたブックを定義します。
worksheet要素はworkbook要素の子要素であり、column要素やワークシートコマンドの親要素です。worksheet要素はセルや式や画像やハイパーリンクなどの表示要素を含み、workbook要素を構成するページに相当します。
|
子要素
ファセット
|
<e:workbook>
<e:worksheet name="foo" startColumn="1" startRow="1">
<e:column value="#{personList}" var="person">
<f:facet name="header">
<e:cell value="Last name"/>
</f:facet>
<e:cell value="#{person.lastName}"/>
</e:column>
</e:worksheet>
<e:workbook>
これはB2セルから表示が開始される、"foo"という名前のワークシートを定義します。
column要素は、worksheet要素の子要素で、cell要素、image要素、formula要素、hyperlink要素の親要素です。これらはワークシートのデータ列挙を制御するためのタグになります。書式の制御については項19.14.5. 「列の設定」を参照して下さい。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:column value="#{personList}" var="person">
<f:facet name="header">
<e:cell value="Last name"/>
</f:facet>
<e:cell value="#{person.lastName}"/>
</e:column>
</e:worksheet>
<e:workbook>
これは、ヘッダーと値の列挙からなる列を定義します。
cell要素は、column要素の中(値の列挙のため)、あるいはworksheet要素の中(column
属性とrow
属性を用いた直接的な配置のため)に置かれ、値の出力する役割を担います(通常データテーブルのvar
属性を含むEL式を通じて出力されます)。 ???
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet
>
<e:column value="#{personList}" var="person">
<f:facet name="header">
<e:cell value="Last name"/>
</f:facet>
<e:cell value="#{person.lastName}"/>
</e:column>
</e:worksheet>
</e:workbook
>
これは、ヘッダーと値の列挙からなる列を定義します。
validation要素はcell要素かformula要素の中に置かれます。validation要素は、セルの値に制約を付加します。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:column value="#{personList}" var="person"
>
<e:cell value="#{person.age">
<e:numericValidation condition="between" value="4"
value2="18"/>
</e:cell>
</e:column>
</e:worksheet>
</e:workbook
>
これは、値が4と18の間の値でなければならないというバリデーション条件をセルに付加します。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:column value="#{personList}" var="person"
>
<e:cell value="#{person.position">
<e:rangeValidation startColumn="0" startRow="0"
endColumn="0" endRow="10"/>
</e:cell>
</e:column>
</e:worksheet>
</e:workbook
>
これは、値がA1:A10の範囲にある値のどれかでなければならないというバリデーション条件をセルに付加します。
|
属性
子要素
ファセット
|
e:listValidation要素は、複数のe:listValidationItem要素を保持するための、ただの入れ物です。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:column value="#{personList}" var="person"
>
<e:cell value="#{person.position">
<e:listValidation>
<e:listValidationItem value="manager"/>
<e:listValidationItem value="employee"/>
</e:listValidation>
</e:cell>
</e:column>
</e:worksheet>
</e:workbook
>
これは、セルの値が"manager"もしくは"employee"でなければならないというバリデーション条件をセルに付加します。
書式マスクはcell要素、あるいはformula要素の属性によって定義されます。書式マスクには二つの種類があり、一つは数値マスク、一つは日付マスクです。
書式マスクがあった場合、まずそれが組み込みの形式であるかどうかがチェックされます。組み込みの形式は例えば、"format1"や"accounting_float"のようなものです( jxl.write.NumberFormats を参照して下さい。)
マスクがリストになかった場合は、カスタムマスクとして扱われます( java.text.DecimalFormat を参照下さい)。例えば"0.00"であったり、自動的に一番近いものに変換された書式が採用されます。
書式マスクがあった場合、まずそれが組み込みの形式であるかどうかがチェックされます。組み込みの形式は例えば、"format1"や"format2"のようなものです( jxl.write.DecimalFormats を参照して下さい)。
マスクがリストになかった場合は、カスタムマスクとして扱われます( java.text.DateFormat を参照して下さい)。例えば"dd.MM.yyyy"であったり、自動的に一番近いものに変換された書式が採用されます。
formula要素は、column要素の中(値の列挙のため)、あるいはworksheet要素の中(column
属性とrow
属性を用いた直接的な配置のため)に置かれ、ある範囲のセル値の計算や関数の適用を行います。formula要素は本質的にセルなので、利用可能な属性を見るためには項19.6. 「cell要素」を参照して下さい。formula要素は、テンプレートにも適用することができ、通常のセルと同様、独自のフォントなどの定義を持つこともできることに注意して下さい。
セルの式は、value
属性の中に、通常のMicrosoft® Excel® スプレッドアプリケーションと同じ書き方で記述します。複数のシートを横断する式を使用する場合は、その式が参照される前に、その式に登場するワークシートが存在しなければならないことに注意して下さい。値は文字列です。
<e:workbook>
<e:worksheet name="fooSheet">
<e:cell column="0" row="0" value="1"/>
</e:worksheet>
<e:worksheet name="barSheet">
<e:cell column="0" row="0" value="2"/>
<e:formula column="0" row="1"
value="fooSheet!A1+barSheet1!A1">
<e:font fontSize="12"/>
</e:formula>
</e:worksheet>
</e:workbook
>
これは、BarSheetのB1セルに、FooSheetとBarSheetのA1セル同士を加算する式を定義します。
image要素は、column要素の中(値の列挙のため)、あるいはworksheet要素の中(startColumn/startRow
属性とrowSpan/columnSpan
属性を用いた直接的な配置のため)に置かれます。spanはオプションであり、省略された場合は、画像はリサイズされずに挿入されます。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:image startRow="0" startColumn="0" rowSpan="4"
columnSpan="4" URI="http://foo.org/logo.jpg"/>
</e:worksheet>
</e:workbook
>
これは、与えられたURIの画像をA1:E5の領域に表示します。
hyperlink要素は、column要素の中(値の列挙のため)、あるいはworksheet要素の中(startColumn/startRow
属性とendColumn/endRow
属性を用いた直接的な配置のため)に置かれます。これらは、URIに対するリンクを追加します。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:hyperLink startRow="0" startColumn="0" endRow="4"
endColumn="4" URL="http://seamframework.org"
description="The Seam Framework"/>
</e:worksheet>
</e:workbook
>
これは、seamframework.orgのページを指すメッセージ付きリンクを、A1:E5の領域に表示します。
header要素とfooter要素はworksheet要素の子要素であり、facet要素を含み、facet要素は、コマンドの埋め込まれた文字列を含みます。文字列は構文解析され、コマンドの結果を含んだ文字列として表示されます。
|
属性
子要素
ファセット
|
|
属性
子要素
ファセット
|
facet要素の内容には、以下のように#で区切られたさまざまなコマンドを含めることができます。
#date# |
現在の日付を挿入します。 |
#page_number# |
現在のページを挿入します。 |
#time# |
現在の時刻を挿入します。 |
#total_pages# |
総ページ数を挿入します。 |
#worksheet_name# |
シート名を挿入します。 |
#workbook_name# |
ブック名を挿入します。 |
#bold# |
強調文字に切り替えます。次の#bold#まで有効となります。 |
#italics# |
斜体文字に切り替えます。次の#italic#まで有効となります。 |
#underline# |
下線を引きます。次の#underline#まで有効となります。 |
#double_underline# |
二重下線を引きます。次の#double_underline#まで有効となります。 |
#outline# |
アウトラインフォントに切り替えます。次の#outline#まで有効となります。 |
#shadow# |
影付き文字に切り替えます。次の#shadow#まで有効となります。 |
#strikethrough# |
取り消し線を引きます。次の#strikethrough#まで有効となります。 |
#subscript# |
下付き文字に切り替えます。次の#subscript#まで有効となります。 |
#superscript# |
上付き文字に切り替えます。次の#superscript#まで有効となります。 |
#superscript# |
フォント名を設定します。#font_name=Verdana#のように設定します。 |
#font_size# |
フォントサイズを設定します。#font_size=12#のように設定します。 |
<e:workbook>
<e:worksheet
>
<e:header>
<f:facet name="left">
This document was made on #date# and has #total_pages# pages
</f:facet>
<f:facet name="right">
#time#
</f:facet>
</e:header>
<e:worksheet>
</e:workbook>
printArea要素とprintTitle要素はワークシートやワークシートテンプレートの子要素であり、印刷範囲や印刷タイトルを設定します。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet
>
<e:printTitles firstRow="0" firstColumn="0"
lastRow="0" lastColumn="9"/>
<e:printArea firstRow="1" firstColumn="0"
lastRow="9" lastColumn="9"/>
</e:worksheet>
</e:workbook>
これは、A1:A10の領域を印刷タイトルとし、B2:J10の領域を印刷範囲とします。
ワークシートコマンド要素はworkbook要素の子要素であり、通常一回だけ実行されます。
行や列のグルーピングを行います。
|
属性
子要素
ファセット
|
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet
>
<e:groupRows startRow="4" endRow="9" collapse="true"/>
<e:groupColumns startColumn="0" endColumn="9" collapse="false"/>
</e:worksheet>
</e:workbook>
これは、5行目から10行目まで、5列目から10列目までの範囲をグルーピングし、初期状態で行を折りたたみます(列は折りたたみません)。
改ページを行います。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet
>
<e:rowPageBreak row="4"/>
</e:worksheet>
</e:workbook
>
これは、5行目で改ページを行います。
セルを結合します。
|
属性
子要素
ファセット
|
<e:workbook>
<e:worksheet>
<e:mergeCells startRow="0" startColumn="0" endRow="9" endColumn="9"/>
</e:worksheet>
</e:workbook
>
これは、A1:J10の範囲のセルを結合します。
もし、専用のXHMLドキュメントを作成する代わりに、既存のJSFデータテーブルを出力したい場合は、org.jboss.seam.excel.excelExporter.export
コンポーネントを使い、データテーブルのIDをSeamのEL式として渡すことで、簡単に実現することができます。このようなテーブルがあり、
<h:form id="theForm">
<h:dataTable id="theDataTable" value="#{personList.personList}"
var="person">
...
</h:dataTable>
</h:form>
これをMicrosoft® Excel®のスプレッドシートとして表示させたい場合は、
<h:commandLink
value="Export"
action="#{excelExporter.export('theForm:theDataTable')}"
/>
のように、フォームの中に記述します。もちろん、ボタンや、s:linkやその他の手段によって、出力を実行することもできます。データテーブルの中に専用の出力用のタグを記述できるようにする計画もあり、そうするとデータテーブルのIDを渡さなくても済むようになります。
フォーマット処理については項19.14. 「フォントとレイアウト」を参照して下さい。
CSS風のスタイル属性とタグ属性を組み合わせて、出力の見た目を制御することができます。最も汎用的なもの(font、border、backgroundなど)はCSSで記述でき、そうでないものはタグ属性で記述できます。
CSS属性は、styleClass
で指定されるCSSクラスのタグの中で、親クラスから子クラスへと波及し、適用されます。CSS属性は、最終的にはstyle
属性によって定義されます。それらは、ほぼどこにでも配置することができますが、たとえば列幅をその列の中のあるセルにおいて設定するようなことはできません。
もし、書式マスクやフォントを指定する際に、スペースやセミコロンなどの特殊な文字を使用する場合は、xls-format-mask:'$;$'のように、CSS文字列をシングルクォーテーションで囲むことによってエスケープすることができます。
外部スタイルシートはe:linkタグによって参照されます。e:linkタグは、workbook要素の子要素となります。
|
属性
子要素
ファセット
|
<e:workbook>
<e:link URL="/css/excel.css"/>
</e:workbook
>
これは、"/css/excel.css"で示されるスタイルシートを参照します。
以下のXLS-CSS属性のグループは、フォントとその属性を定義します。
xls-font-family |
フォント名です。フォントがOSによってサポートされていることを確認して下さい。 |
xls-font-size |
フォントサイズです。値は数値です。 |
xls-font-color |
フォントの色です( jxl.format.Colour を参照して下さい)。 |
xls-font-bold |
フォントを強調文字にするかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-font-italic |
フォントを斜体文字にするかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-font-script-style |
フォントの上付きや下付きを設定します( jxl.format.ScriptStyle を参照して下さい。) |
xls-font-underline-style |
フォントの下線を設定します( jxl.format.UnderlineStyle を参照して下さい)。 |
xls-font-struck-out |
フォントに取り消し線をつけるかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-font |
すべてのフォント設定を略記で行います。フォント名は'Times New Roman'のようにスペース区切りにして、記述の一番最後に置きます。"italic"や"bold"や"struckout"などを使用することができます。 Example style="xls-font: red bold italic 22 Verdana" |
以下のXLS-CSS属性のグループは、セルのボーダーを定義します。
xls-border-left-color |
セルの左ボーダーの色です( jxl.format.Colour を参照して下さい)。 |
xls-border-left-line-style |
セルの左ボーダーのスタイルです( jxl.format.LineStyle を参照して下さい)。 |
xls-border-left |
セルの左ボーダーの色とスタイルの設定を略記で行います。例えばstyle="xls-border-left: thick red"のようになります。 |
xls-border-top-color |
セルの上ボーダーの色です( jxl.format.Colour を参照して下さい)。 |
xls-border-top-line-style |
セルの上ボーダーのスタイルです( jxl.format.LineStyle を参照して下さい)。 |
xls-border-top |
セルの上ボーダーの色とスタイルの設定を略記で行います。例えばstyle="xls-border-top: thick red"のようになります。 |
xls-border-right-color |
セルの右ボーダーの色です( jxl.format.Colour を参照して下さい)。 |
xls-border-right-line-style |
セルの右ボーダーのスタイルです( jxl.format.LineStyle を参照して下さい)。 |
xls-border-right |
セルの右ボーダーの色とスタイルの設定を略記で行います。例えばstyle="xls-border-right: thick red"のようになります。 |
xls-border-bottom-color |
セルの下ボーダーの色です( jxl.format.Colour を参照して下さい)。 |
xls-border-bottom-line-style |
セルの下ボーダーのスタイルです( jxl.format.LineStyle を参照して下さい)。 |
xls-border-bottom |
セルの下ボーダーの色とスタイルの設定を略記で行います。例えばstyle="xls-border-bottom: thick red"のようになります。 |
xls-border |
セルの上下左右のボーダーの色とスタイルの設定を略記で行います。例えばstyle="xls-border: thick red"のようになります。 |
以下のXLS-CSS属性のグループは、セルの背景を定義します。
xls-background-color |
背景の色です( jxl.format.LineStyle )を参照して下さい。 |
xls-background-pattern |
背景のパターンです( jxl.format.Pattern を参照して下さい)。 |
xls-background |
背景の色とパターンの設定を略記で行います。記述のルールについては上を参照して下さい。 |
以下のXLS-CSS属性のグループは、列幅等を定義します。
xls-column-width |
列幅です。最初は大きめの値(5000まで)を使って下さい。XHTMLモードで使用され、e:columnタグで適用されます。 |
xls-column-widths |
列幅です。最初は大きめの値(5000まで)を使って下さい。データテーブルの出力時に使用され、データテーブルのスタイル属性で適用されます。数値、あるいは、元の設定を有効にするためには"*"を指定して下さい。 Example style="xls-column-widths: 5000, 5000, *, 10000" |
xls-column-autosize |
列幅の自動調整を行うかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-column-hidden |
列を非表示にするかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-column-export |
列を出力時に表示するかどうかを設定します。"true"もしくは"false"を設定して下さい。デフォルトはtrueです。 |
以下のXLS-CSS属性のグループは、セルのプロパティを定義します。
xls-alignment |
セル値の水平方向の配置を設定します( jxl.format.Alignment を参照して下さい)。 |
xls-force-type |
セルのデータ型を強制します。値は文字列で、"general"、"number"、"text"、"date"、"formula"、"bool"のどれかです。データ型は自動的に検出されるので、この属性を使うことはまれです。 |
xls-format-mask |
セルの書式マスクを設定します。項19.6.2. 「書式マスク」を参照して下さい。 項19.6.2. 「書式マスク」 |
xls-indentation |
セル値のインデントを設定します。値は数値です。 |
xls-locked |
セルをロックするかどうかを設定します。ブックレベルでのロックとともに使用します。"true"もしくは"false"を設定して下さい。 |
xls-orientation |
セル値の方向を設定します( jxl.format.Orientation を参照して下さい)。 |
xls-vertical-alignment |
セル値の垂直方向の配置を設定します( jxl.format.VerticalAlignment を参照して下さい)。 |
xls-shrink-to-fit |
セル値をセルに合わせて縮小するかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
xls-wrap |
セル値を折り返すかどうかを設定します。"true"もしくは"false"を設定して下さい。 |
データテーブル出力においても、XHTMLモードの場合と同じXLS-CSS属性が適用されますが、列幅については例外的にデータテーブルのxls-column-widths
属性が適用されます(UIColumnがstyleやstyleClass属性をサポートしないからです)。
このライブラリには、メッセージ国際化のためのリソースバンドルのキーが二つだけ存在します。二つとも、不正なデータ形式に対するエラーメッセージであり、二つとも、引数を一つ取ります(不正なデータの内容)。
org.jboss.seam.excel.not_a_number
—数値であると想定されたデータが、実際にはそうではなかった場合のエラーメッセージです。
org.jboss.seam.excel.not_a_date
—日付であると想定されたデータが、実際にはそうではなかった場合のエラーメッセージです。
Microsoft® Excel® スプレッドアプリケーションのコア機能は、素晴らしいJExcelAPIライブラリに基づいており、そのほとんどの特徴や制限を、そのまま引き継いでいます。JExcelAPIライブラリに関する情報はhttp://jexcelapi.sourceforge.net/で見つけることができます。
フォーラムやメーリングリストに参加する場合は、そこでの参加者がSeamやライブラリの使い方に関するすべてを知っているわけではないということ、また、そこでのすべての問題はJBoss Seam JIRAの"excel"モジュール以下にもレポート済みであるということを気にとめておいて下さい。