Oracle® Fusion Middleware

Oracle ADF FacesによるWebユーザー・インタフェースの開発

12c (12.1.2)

E48096-02(原本部品番号:E23447-02)

2013年12月

ADF Facesコンポーネントとサポート・アーキテクチャを使用してWebベース・アプリケーションを作成する方法について説明した、開発者向けのドキュメント

Oracle Fusion Middleware Oracle ADF FacesによるWebユーザー・インタフェースの開発 12c (12.1.2)

E48096-02

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

原本主著者:  Robin Whitmore (lead)、Peter Jew、Kathryn Munn、Walter Egan、Himanshu Marathe、Ralph Gordon、Cindy Hall、Michele Whittaker

原本協力著者:  Poh Lee Tan

原本協力者:  ADF Faces開発チーム、Frank Nimphius、Laura Akel、Katia Obradovic-Sarkic

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントが、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供される場合は、次のNoticeが適用されます。

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

このソフトウェアまたはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアまたはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用する際、このソフトウェアまたはハードウェアを安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアまたはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracleおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXはThe Open Groupの登録商標です。

このソフトウェアまたはハードウェアおよびドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- 対象読者

- ドキュメントのアクセシビリティについて

- 関連ドキュメント

- 表記規則

このガイドで説明する新機能

- リリース12c (12.1.2)の新機能と変更された機能

- リリース12c (12.1.2)に関するこのドキュメントにおけるその他の大きな変更

第I部 ADF Faces概説

1 ADF Facesの概要

- 1.1 ADF Facesについて

- 1.2 ADF Facesフレームワーク

- 1.3 ADF Facesコンポーネント

2 ADF Facesデモ・アプリケーション

- 2.1 ADF Facesデモ・アプリケーションについて

- 2.2 ADF Facesデモ・アプリケーションのダウンロードとインストール

3 ADF FacesとJDeveloperの概要

- 3.1 JDeveloperでの宣言的開発について

- 3.2 アプリケーション・ワークスペースの作成

- 3.2.1 ADF Facesアプリケーション・ワークスペースの作成方法

- 3.2.2 アプリケーション・ワークスペースを作成する場合の処理

- 3.3 ページ・フローの定義

- 3.3.1 ページ・フローの定義方法

- 3.3.2 ダイアグラマを使用してページ・フローを作成する場合の処理

- 3.4 ビュー・ページの作成

- 3.4.1 JSFページの作成方法

- 3.4.2 JSFページの作成時に発生する処理

- 3.4.3 Faceletsエンジンを使用するためのアプリケーションの更新に関する必知事項

- 3.4.4 自動コンポーネント・バインディングに関する必知事項

- 3.4.5 ADF FacesコンポーネントのJSFページへの追加方法

- 3.4.6 コンポーネントをページへ追加する場合の処理

- 3.4.7 コンポーネント属性の設定方法

- 3.4.8 「プロパティ」ウィンドウを使用したときに行われる処理

- 3.5 EL式の作成

- 3.5.1 EL式の作成方法

- 3.5.2 EL書式タグの使用方法

- 3.5.3 EL式のマネージドBean内での使用方法

- 3.6 マネージドBeanの作成と使用

- 3.6.1 JDeveloperでのマネージドBeanの作成方法

- 3.6.2 JDeveloperを使用してマネージドBeanを作成する場合の処理

- 3.6.3 コンポーネント・バインディングおよびマネージドBeanに関する必知事項

- 3.7 ADF Faces Javadocの表示

- 3.7.1 ADF Facesのソース・コードおよびJavadocの表示方法

第II部 ADF Facesアーキテクチャの理解

4 ADF Facesクライアント側アーキテクチャの使用方法

- 4.1 ADF Facesアーキテクチャの使用について

- 4.2 JavaScriptのページへの追加

- 4.2.1 インラインのJavaScriptの使用方法

- 4.2.2 JavaScriptライブラリのインポート方法

- 4.2.3 クライアント・イベント・ソースへのアクセスに関する必知事項

- 4.3 クライアント側コンポーネントのインスタンス化

- 4.3.1 クライアント側インスタンス用にコンポーネントを構成する方法

- 4.3.2 clientComponentをtrueに設定した場合の処理

- 4.4 クライアント・イベントのリスニング

- 4.4.1 クライアント・イベントをリスニングする方法

- 4.5 クライアントでのコンポーネント・プロパティへのアクセス

- 4.5.1 クライアントでのプロパティ値の設定方法

- 4.5.2 実行時の処理: クライアント・プロパティのクライアントでの設定方法

- 4.5.3 無効化されたプロパティを非保護にする方法

- 4.5.4 クライアントとサーバーのプロパティ値を同期させない方法

- 4.6 クライアント側コンポーネントに対するボーナス属性の使用

- 4.6.1 ボーナス属性の作成方法

- 4.6.2 ボーナス属性のマーシャリングに関する必知事項

- 4.7 レンダリングおよび可視性の理解

- 4.7.1 Javascriptを使用した可視性の設定方法

- 4.7.2 VisibleとisShowing関数に関する必知事項

- 4.8 ページでのクライアント・コンポーネントの検索

- 4.8.1 ネーミング・コンテナ内のコンポーネントの検索に関する必知事項

- 4.9 JavaScriptライブラリのパーティション化

- 4.9.1 JavaScript機能の作成方法

- 4.9.2 JavaScriptパーティションの作成方法

- 4.9.3 実行時の処理: JavaScriptのパーティション化

5 ADF FacesでのJSFライフサイクルの使用

- 5.1 JSFライフサイクルとADF Facesの使用について

- 5.2 immediate属性の使用

- 5.2.1 immediate属性の使用方法

- 5.3 最適化されたライフサイクルの使用

- 5.4 クライアント側ライフサイクルの使用

- 5.5 サブフォームを使用したページでのセクションの作成

- 5.6 オブジェクト・スコープ・ライフサイクル

- 5.7 ページ間の値の受渡し

- 5.7.1 Javaコード内でのpageFlowScopeスコープの使用方法

- 5.7.2 Javaコードを記述せずにpageFlowScopeスコープを使用する方法

- 5.7.3 実行時に行われる処理: 値の受渡し方法

6 イベントの処理

- 6.1 イベントおよびイベント処理について

- 6.1.1 イベントおよび部分ページ・レンダリング

- 6.1.2 クライアント側イベント・モデル

- 6.2 ADF Facesサーバー・イベントの使用

- 6.2.1 サーバー側イベントの処理方法

- 6.3 ADF Facesクライアント・イベントに対するJavaScriptの使用

- 6.3.1 クライアント側イベントの使用方法

- 6.3.2 イベントの発生元を返す方法

- 6.3.3 イベントのクライアント側属性の使用方法

- 6.3.4 イベント実行時のUI入力のブロック方法

- 6.3.5 イベントがサーバーに伝播されないようにする方法

- 6.3.6 レスポンスが必要でないことを示す方法

- 6.3.7 実行時の処理: クライアント側イベントの機能の仕方

- 6.3.8 ネーミング・コンテナの使用に関する必知事項

- 6.4 クライアントからサーバーへのカスタム・イベントの送信

- 6.4.1 クライアントからサーバーへのカスタム・イベントの送信方法

- 6.4.2 実行時の処理: クライアント・リスナーとサーバー・リスナーの協働の仕方

- 6.4.3 データのマーシャリングとアンマーシャリングに関する必知事項

- 6.5 イベント・レスポンス内でのスクリプトの実行

- 6.6 ADF Facesのクライアント動作タグの使用

- 6.6.1 scrollComponentIntoViewBehaviorタグの使用方法

- 6.7 ポーリング・イベントを使用したページの更新

- 6.7.1 pollコンポーネントの使用方法

7 入力の検証および変換

- 7.1 ADF Facesの変換および検証について

- 7.1.1 ADF Facesコンバータおよびバリデータのユースケースと例

- 7.1.2 ADF Facesコンバータおよびバリデータの追加機能

- 7.2 変換、検証とJSFライフサイクル

- 7.3 変換の追加

- 7.3.1 コンバータの追加方法

- 7.3.2 複数のコンバータ・パターンを指定する方法

- 7.3.3 実行時の処理: コンバータの機能の仕方

- 7.3.4 日時コンバータに関する必知事項

- 7.4 カスタムADF Facesコンバータの作成

- 7.4.1 カスタムADF Facesコンバータの作成方法

- 7.4.1.1 サーバー側(Java)での変換の実装

- 7.4.1.2 ADF Facesコンバータのfaces-config.xmlファイルへの登録

- 7.4.1.3 クライアント側(Javascript)での変換の実装

- 7.4.2 JSFページでのカスタムADF Facesコンバータの使用

- 7.5 検証の追加

- 7.5.1 検証の追加方法

- 7.5.1.1 ADF Faces検証の追加

- 7.5.1.2 検証属性の使用

- 7.5.1.3 ADF Facesバリデータの使用

- 7.5.2 実行時の処理: バリデータの機能の仕方

- 7.5.3 複数バリデータに関する必知事項

- 7.6 カスタムJSF検証の作成

- 7.6.1 バッキングBeanの検証メソッドの作成方法

- 7.6.2 バッキングBeanの検証メソッドを作成するときに行われる処理

- 7.6.3 カスタムJSFバリデータの作成方法

- 7.6.4 カスタムJSFバリデータを使用するときに行われる処理

8 部分ページ・コンテンツの再レンダリング

- 8.1 部分ページ・レンダリングについて

- 8.2 部分トリガーの使用

- 8.2.1 部分トリガーの使用方法

- 8.2.2 ブラウザの戻るボタンの使用に関する必知事項

- 8.2.3 PPRとスクリーン・リーダーに関する必知事項

- 8.3 targetタグを使用したPPRの実行

- 8.3.1 targetタグを使用して部分ページ・レンダリングを有効にする方法

- 8.4 部分ページ・レンダリングのプログラムによる有効化

- 8.4.1 部分ページ・レンダリングをプログラムで有効にする方法

- 8.5 部分ページ・ナビゲーションの使用

- 8.5.1 部分ページ・ナビゲーションの使用方法

- 8.5.2 PPRナビゲーションに関する必知事項

第III部 レイアウトの作成

9 Webページ上のコンテンツの編成

- 9.1 Webページ上のコンテンツの編成について

- 9.1.1 レイアウト・コンポーネントの追加機能

- 9.2 ページ・レイアウトの開始

- 9.2.1 ジオメトリ管理およびコンポーネントの拡大

- 9.2.2 拡大可能なコンポーネントへのコンポーネントのネスト

- 9.2.3 クイック・スタート・レイアウトの使用

- 9.2.4 ジオメトリ管理コンポーネント使用のヒント

- 9.2.5 documentタグの構成方法

- 9.3 グリッドでのコンテンツの配置

- 9.3.1 panelGridLayout、gridRowおよびgridCellコンポーネントを使用してグリッドベースのレイアウトを作成する方法

- 9.3.2 ジオメトリ管理およびpanelGridLayoutコンポーネントに関する必知事項

- 9.3.3 グリッドの構造に関する必知事項

- 9.3.4 使用するレイアウト・コンポーネントの決定に関する必知事項

- 9.4 コンテンツをページ全体に拡大するための設定

- 9.4.1 panelStretchLayoutコンポーネントの使用方法

- 9.4.2 ジオメトリ管理およびpanelStretchLayoutコンポーネントに関する必知事項

- 9.5 スプリッタを使用したサイズ変更可能なペインの作成

- 9.5.1 panelSplitterコンポーネントの使用方法

- 9.5.2 ジオメトリ管理およびpanelSplitterコンポーネントに関する必知事項

- 9.6 事前定義済固定領域へのページ・コンテンツの配置

- 9.6.1 panelBorderLayoutコンポーネントを使用して事前定義済固定領域にページ・コンテンツを配置する方法

- 9.7 フォームでのコンテンツの配置

- 9.7.1 panelFormLayoutコンポーネントの使用方法

- 9.7.2 groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法に関する必知事項

- 9.8 ダッシュボードでのコンテンツの配置

- 9.8.1 panelDashboardコンポーネントの使用方法

- 9.8.2 ジオメトリ管理およびpanelDashboardコンポーネントに関する必知事項

- 9.9 コンテンツの動的な表示および非表示

- 9.9.1 showDetailコンポーネントの使用方法

- 9.9.2 showDetailHeaderコンポーネントの使用方法

- 9.9.3 panelBoxコンポーネントの使用方法

- 9.9.4 表示イベントに関する必知事項

- 9.9.5 スキニングとshowDetailコンポーネントに関する必知事項

- 9.9.6 スキニングとshowDetailHeaderコンポーネントに関する必知事項

- 9.9.7 スキニングとpanelBoxコンポーネントに関する必知事項

- 9.10 パネルにおけるコンテンツの表示または非表示

- 9.10.1 panelAccordionコンポーネントの使用方法

- 9.10.2 panelTabbedコンポーネントの使用方法

- 9.10.3 panelDrawerコンポーネントの使用方法

- 9.10.4 panelSpringboardコンポーネントの使用方法

- 9.10.5 グリッド・モードとストライプ・モードの切替えに関する必知事項

- 9.10.6 コンテンツを表示するためのshowDetailItemコンポーネントの使用方法

- 9.10.7 ジオメトリ管理およびshowDetailItemコンポーネントに関する必知事項

- 9.10.8 showDetailItem表示イベントに関する必知事項

- 9.10.9 スキニングとpanelTabbedコンポーネントに関する必知事項

- 9.11 静的ボックスの項目の表示

- 9.11.1 panelHeaderコンポーネントの使用方法

- 9.11.2 decorativeBoxコンポーネントの使用方法

- 9.11.3 ジオメトリ管理およびdecorativeBoxコンポーネントに関する必知事項

- 9.11.4 スキニングとpanelHeaderコンポーネントに関する必知事項

- 9.11.5 スキニングとdecorativeBoxコンポーネントに関する必知事項

- 9.12 1つ以上の列における箇条書きリストの表示

- 9.12.1 panelListコンポーネントの使用方法

- 9.12.2 リスト階層の作成に関する必知事項

- 9.13 関連する項目のグループ化

- 9.13.1 panelGroupLayoutコンポーネントの使用方法

- 9.13.2 ジオメトリ管理およびpanelGroupLayoutコンポーネントに関する必知事項

- 9.14 空白または線を使用したコンテンツの分割

- 9.14.1 spacerコンポーネントの使用方法

- 9.14.2 separatorコンポーネントの使用方法

10 フラグメント、ページ・テンプレート、コンポーネントの作成および再利用

- 10.1 再利用可能なコンテンツについて

- 10.1.1 再利用可能なコンポーネントのユースケースと例

- 10.1.2 再利用可能なコンポーネントの追加機能

- 10.2 再利用可能なコンポーネントの共通機能

- 10.2.1 リクエスト・スコープ内のページ

- 10.2.2 カスタマイズのための子コンポーネントへのアクセス

- 10.3 ページ・テンプレートの使用

- 10.3.1 ページ・テンプレートの作成方法

- 10.3.2 ページ・テンプレートを作成する場合の処理

- 10.3.3 ページ・テンプレートに基づくJSFページの作成方法

- 10.3.4 テンプレートを使用してページを作成する場合の処理

- 10.3.5 実行時の処理: ページ・テンプレートが解決される仕組み

- 10.3.6 ページ・テンプレートおよびネーミング・コンテナに関する必知事項

- 10.4 ページ・フラグメントの使用

- 10.4.1 ページ・フラグメントの作成方法

- 10.4.2 ページ・フラグメントを作成する場合の処理

- 10.4.3 JSFページでのページ・フラグメントの使用方法

- 10.4.3.1 「コンポーネント」ウィンドウを使用したページ・フラグメントの追加

- 10.4.3.2 「アプリケーション」ウィンドウを使用したページ・フラグメントの追加

- 10.4.4 実行時の処理: ページ・フラグメントが解決される仕組み

- 10.5 宣言コンポーネントの使用

- 10.5.1 宣言コンポーネントの作成方法

- 10.5.2 宣言コンポーネントを作成する場合の処理

- 10.5.3 宣言コンポーネントのデプロイ方法

- 10.5.4 JSFページでの宣言コンポーネントの使用方法

- 10.5.5 JSFページに宣言コンポーネントを使用する場合の処理

- 10.5.6 実行時に行われる処理: 宣言コンポーネント

- 10.6 ページへのリソースの追加

- 10.6.1 ページ・テンプレートおよび宣言コンポーネントへのリソースの追加方法

- 10.6.2 実行時の処理: ドキュメント・ヘッダーにリソースを追加する方法

第IV部 一般的なADF Facesコンポーネントの使用

11 入力コンポーネントの使用およびフォームの定義

- 11.1 入力コンポーネントおよびフォームについて

- 11.1.1 入力コンポーネントのユースケースと例

- 11.1.2 入力コンポーネントおよびフォームの追加機能

- 11.2 formの定義

- 11.2.1 ページへのformの追加方法

- 11.2.2 ページへのsubformの追加方法

- 11.2.3 formをリセットするボタンの追加方法

- 11.3 inputTextコンポーネントの使用方法

- 11.3.1 inputTextコンポーネントの追加方法

- 11.3.2 inputTextコンポーネントへのテキストの挿入機能の追加方法

- 11.4 数値入力コンポーネントの使用方法

- 11.4.1 inputNumberSliderまたはinputRangeSliderコンポーネントの追加方法

- 11.4.2 inputNumberSpinboxコンポーネントの追加方法

- 11.5 カラー・チューザおよび日付チューザの使用方法

- 11.5.1 inputColorコンポーネントの追加方法

- 11.5.2 inputDateコンポーネントの追加方法

- 11.5.3 inputDateコンポーネントなしでのタイム・ゾーンの選択に関する必知事項

- 11.5.4 カスタム・タイム・ゾーン・リストの作成に関する必知事項

- 11.6 選択コンポーネントの使用方法

- 11.6.1 選択コンポーネントの使用方法

- 11.6.2 SelectManyChoiceコンポーネントのcontentDelivery属性に関する必知事項

- 11.7 シャトル・コンポーネントの使用方法

- 11.7.1 selectManyShuttleまたはselectOrderShuttleコンポーネントの追加方法

- 11.7.2 選択イベントのクライアント・リスナーの使用方法に関する必知事項

- 11.8 richTextEditorコンポーネントの使用方法

- 11.8.1 richTextEditorコンポーネントの追加方法

- 11.8.2 richTextEditorコンポーネントへのテキストの挿入機能を追加する方法

- 11.8.3 ツールバーのカスタマイズ方法

- 11.9 ファイルのアップロード機能の使用方法

- 11.9.1 inputFileコンポーネントの使用方法

- 11.9.2 複数のファイルをアップロードするようにinputFileコンポーネントを構成する方法

- 11.9.3 一時的なファイルの格納に関する必知事項

- 11.9.4 複数のファイルのアップロードに関する必知事項

- 11.9.5 inputFileコンポーネントのユーザー・インタフェースのカスタマイズに関する必知事項

- 11.10 コード・エディタの使用

- 11.10.1 codeEditorコンポーネントの追加方法

12 表、ツリー、およびその他のコレクションベースのコンポーネントの使用

- 12.1 コレクションベース・コンポーネントについて

- 12.1.1 コレクションベース・コンポーネントのユースケースと例

- 12.1.2 コレクションベース・コンポーネントの追加機能

- 12.2 コレクションベース・コンポーネントの共通機能

- 12.2.1 行およびノードへのデータの表示

- 12.2.2 コンテンツの配信

- 12.2.3 行の選択

- 12.2.4 表、ツリーおよびツリー表のデータの編集

- 12.2.5 表、ツリーおよびツリー表でのポップアップ・ダイアログの使用

- 12.2.6 クライアントのコレクション・コンポーネントへのアクセス

- 12.2.7 表、ツリーおよびツリー表コンポーネントのジオメトリ管理

- 12.3 表へのデータの表示

- 12.3.1 列および列データ

- 12.3.2 表の書式設定

- 12.3.3 列の書式設定

- 12.3.4 ページへの表の表示方法

- 12.3.5 ページに表を追加する場合の処理

- 12.3.6 実行時の処理: データ配信

- 12.3.7 プログラムを使用した表の列のソートの有効化に関する必知事項

- 12.3.8 表の選択された行でのアクションの実行に関する必知事項

- 12.3.9 表の選択コンポーネント値の動的な決定に関する必知事項

- 12.4 表への非表示機能の追加

- 12.4.1 detailStampファセットの使用方法

- 12.4.2 実行時に行われる処理: rowDisclosureEvent

- 12.5 表でのフィルタ処理の有効化

- 12.5.1 表へのフィルタ処理機能の追加方法

- 12.6 ツリーへのデータの表示

- 12.6.1 ツリーへのデータの表示方法

- 12.6.2 ページにツリーを追加する場合の処理

- 12.6.3 実行時に行われる処理: ツリー・コンポーネント・イベント

- 12.6.4 プログラムを使用したノードの開閉に関する必知事項

- 12.6.5 プログラムを使用したノードの選択に関する必知事項

- 12.7 ツリー表へのデータの表示

- 12.7.1 ツリー表へのデータの表示方法

- 12.8 行を値として渡す

- 12.9 表メニュー、ツールバーおよびステータス・バーの表示

- 12.9.1 表、ツリーまたはツリー表を含むpanelCollectionの追加方法

- 12.10 リストへのコレクションの表示

- 12.10.1 リストへのコレクションの表示方法

- 12.11 カルーセルでのイメージの表示

- 12.11.1 カルーセルの作成方法

- 12.11.2 カルーセル・コンポーネントと各種ブラウザに関する必知事項

- 12.12 表、ツリーまたはツリー表からのデータのエクスポート

- 12.12.1 表、ツリーまたはツリー表データの外部形式へのエクスポート方法

- 12.12.2 実行時の処理: 行の選択がエクスポートされるデータに与える影響

- 12.13 コレクションベースのコンポーネントからクライアント上の選択された値へのアクセス

- 12.13.1 スタンプ設定されたコンポーネントの選択内容から値へのアクセス方法

- 12.13.2 選択された値へのアクセスに関する必知事項

13 値リスト・コンポーネントの使用方法

- 13.1 値リスト・コンポーネントについて

- 13.1.1 値リスト・コンポーネントの追加機能

- 13.2 ListOfValuesデータ・モデルの作成

- 13.2.1 ListOfValuesデータ・モデルの作成方法

- 13.3 inputListOfValuesコンポーネントの使用方法

- 13.3.1 InputListOfValuesコンポーネントの使用方法

- 13.3.2 LOVコンポーネントの「検索および選択」ダイアログのスキニングに関する必知事項

- 13.4 InputComboboxListOfValuesコンポーネントの使用方法

- 13.4.1 InputComboboxListOfValuesコンポーネントの使用方法

14 問合せコンポーネントの使用方法

- 14.1 問合せコンポーネントについて

- 14.1.1 問合せコンポーネントのユースケースと例

- 14.1.2 問合せコンポーネントの追加機能

- 14.2 問合せデータ・モデルの作成

- 14.2.1 問合せデータ・モデルの作成方法

- 14.3 quickQueryコンポーネントの使用方法

- 14.3.1 モデルを使用したquickQueryコンポーネントの追加方法

- 14.3.2 モデルなしでのquickQueryコンポーネントの使用方法

- 14.3.3 実行時の処理: フレームワークによりquickQueryコンポーネントがレンダリングされて検索が実行される仕組み

- 14.4 queryコンポーネントの使用方法

- 14.4.1 queryコンポーネントの追加方法

15 ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法

- 15.1 ポップアップ・ダイアログ、メニューおよびウィンドウについて

- 15.1.1 ポップアップ・ダイアログ、メニュー、ウィンドウのユースケースと例

- 15.1.2 ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能

- 15.2 ポップアップの宣言的な作成

- 15.2.1 ダイアログの作成方法

- 15.2.2 パネル・ウィンドウの作成方法

- 15.2.3 ポップアップ・メニューの作成方法

- 15.2.4 ノート・ウィンドウの作成方法

- 15.2.5 実行時に行われる処理: popupコンポーネントのイベント

- 15.2.6 ダイアログ・イベントに関する必知事項

- 15.3 ポップアップの宣言的な呼出し

- 15.3.1 af:showPopupBehaviorタグを使用してポップアップを宣言的に呼び出す方法

- 15.3.2 af:showPopupBehaviorタグを使用してポップアップを呼び出した場合の処理

- 15.4 ポップアップのプログラムによる呼出し

- 15.4.1 ポップアップをプログラムで呼び出す方法

- 15.4.2 ポップアップをプログラムで呼び出した場合の処理

- 15.5 ポップアップへのコンテキスト情報の表示

- 15.5.1 コンテキスト情報の作成方法

- 15.6 インライン・ポップアップの自動取消の制御

- 15.6.1 インライン・ポップアップの自動取消を無効にする方法

- 15.6.2 インライン・ポップアップの自動取消を無効にした場合の処理

- 15.7 ポップアップの入力フィールドのリセット

- 15.7.1 ポップアップの入力フィールドのリセット方法

- 15.7.2 入力フィールドをリセットするようにポップアップを構成した場合の処理

16 メニュー、ツールバーおよびツールボックスの使用方法

- 16.1 メニュー、ツールバーおよびツールボックスについて

- 16.1.1 メニュー・コンポーネントのユースケースと例

- 16.1.2 メニューおよびツールバー・コンポーネントの追加機能

- 16.2 メニュー・バーでのメニューの使用方法

- 16.2.1 メニュー・バーのメニューの作成および使用方法

- 16.3 ツールバーの使用方法

- 16.3.1 ツールバーの作成および使用方法

- 16.3.2 実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法

- 16.3.3 ツールバーに関する必知事項

17 Calendarコンポーネントの使用方法

- 17.1 Calendarコンポーネントの作成について

- 17.1.1 Calendarのユースケースと例

- 17.1.2 Calendarの追加機能

- 17.2 Calendarの作成

- 17.2.1 Calendarのクラス

- 17.2.2 カレンダを作成する方法

- 17.3 Calendarコンポーネントの構成

- 17.3.1 Calendarコンポーネントの構成方法

- 17.3.2 実行時の処理: CalendarイベントおよびPPR

- 17.4 ポップアップ・コンポーネントを使用した機能の追加

- 17.4.1 ポップアップ・コンポーネントを使用した機能の追加方法

- 17.5 ツールバーのカスタマイズ

- 17.5.1 ツールバーのカスタマイズ方法

- 17.6 Calendarのスタイル設定

- 17.6.1 アクティビティのスタイル設定方法

- 17.6.2 実行時の処理: アクティビティのスタイル設定

- 17.6.3 日付のカスタマイズ方法

18 出力コンポーネントの使用

- 18.1 出力テキスト、イメージ、アイコンおよびメディア・コンポーネントについて

- 18.1.1 出力コンポーネントのユースケースと例

- 18.1.2 出力コンポーネントの追加機能

- 18.2 出力テキストおよび書式設定された出力テキストの表示

- 18.2.1 出力テキストの表示方法

- 18.2.2 outputFormattedコンポーネントで使用可能な書式設定コードと文字コードに関する必知事項

- 18.3 アイコンの表示

- 18.3.1 アイコンの表示方法

- 18.4 イメージの表示

- 18.4.1 イメージの表示方法

- 18.5 リンクとしてのイメージの使用

- 18.5.1 イメージをリンクとして使用する方法

- 18.6 アイコンを使用したアプリケーション・ステータスの表示

- 18.7 ビデオ・クリップおよび音声クリップの再生

- 18.7.1 音声クリップおよびビデオ・クリップの再生を可能にする方法

19 ヒント、メッセージおよびヘルプの表示

- 19.1 ヒントおよびメッセージの表示について

- 19.1.1 メッセージング・コンポーネントのユースケースおよび例

- 19.1.2 メッセージ・コンポーネントのその他の機能

- 19.2 コンポーネントのヒントの表示

- 19.2.1 コンポーネントへのヒントの表示方法

- 19.3 検証および変換用のヒントとエラー・メッセージの表示

- 19.3.1 コンポーネント・インスタンスへのバリデータおよびコンバータのカスタム・メッセージの定義方法

- 19.3.2 コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法

- 19.3.3 コンポーネントのメッセージをインラインで表示する方法

- 19.3.4 グローバル・メッセージをインラインで表示する方法

- 19.3.5 実行時の処理: メッセージの表示

- 19.4 単一のラベルおよびメッセージを使用したコンポーネントのグループ化

- 19.4.1 単一のラベルおよびメッセージを使用したコンポーネントのグループ化方法

- 19.5 コンポーネントへのヘルプの表示

- 19.5.1 ヘルプ・プロバイダの作成方法

- 19.5.1.1 リソース・バンドル・ベースのプロバイダの作成方法

- 19.5.1.2 XLIFFプロバイダの作成方法

- 19.5.1.3 マネージドBeanプロバイダの作成方法

- 19.5.1.4 外部URLヘルプ・プロバイダを作成する方法

- 19.5.1.5 カスタムJavaクラス・ヘルプ・プロバイダの作成方法

- 19.5.2 ヘルプ・プロバイダの登録方法

- 19.5.3 UIコンポーネントからのヘルプ・コンテンツへのアクセス方法

- 19.5.4 外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法

- 19.6 複数のメッセージ・タイプの組合せ

20 ナビゲーション・コンポーネントの使用

- 20.1 ナビゲーション・コンポーネントについて

- 20.1.1 ナビゲーション・コンポーネントのユースケースおよび例

- 20.1.2 ナビゲーション・コンポーネントのその他の機能

- 20.2 ナビゲーション・コンポーネントの共通機能

- 20.3 ボタンおよびリンクのナビゲーション目的での使用

- 20.3.1 ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法

- 20.3.2 ボタンおよびリンクをActionEventの配信なしでナビゲーションに使用する方法

- 20.3.3 部分ページ・ナビゲーションの使用に関する必知事項

- 20.4 リンクに対するブラウザのコンテキスト・メニューの構成

- 20.4.1 コマンド・リンクへのブラウザ・コンテキスト・メニューの構成方法

- 20.4.2 コマンド・リンクにブラウザのコンテキスト・メニューを構成する場合の処理

- 20.5 ボタンまたはリンクの機能の呼出し目的での使用

- 20.5.1 ファイルをダウンロードするためのアクション・コンポーネントの使用方法

- 20.5.2 入力フィールドをリセットするためのアクション・コンポーネントの使用方法

- 20.6 ページ階層用のナビゲーション・アイテムの使用

- 20.6.1 ページ階層用のナビゲーション・ケースの作成方法

- 20.7 メニュー・モデルを使用したページ階層の作成

- 20.7.1 メニュー・モデル・メタデータの作成方法

- 20.7.2 「ADFメニュー・モデルの作成」ウィザードを使用する場合の処理

- 20.7.3 メニュー・モデルへのnavigationPaneコンポーネントのバインド方法

- 20.7.4 メニュー・モデルでのbreadCrumbsコンポーネントの使用方法

- 20.7.5 メニュー・モデルでのmenuBarコンポーネントの使用方法

- 20.7.6 実行時に行われる処理: メニュー・モデルによるページ階層の作成方法

- 20.7.7 カスタム属性の使用に関する必知事項

- 20.8 単純なナビゲーション階層の作成

- 20.8.1 単純なページ階層の作成方法

- 20.8.2 breadCrumbsコンポーネントの使用方法

- 20.8.3 ナビゲーション・タブの削除に関する必知事項

- 20.8.4 ナビゲーション・タブのサイズに関する必知事項

- 20.8.5 圧縮レイアウトのナビゲーション・タブに関する必知事項

- 20.9 trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成

- 20.9.1 トレイン・モデルの作成方法

- 20.9.2 トレイン・モデルへのマネージドBeanの構成方法

- 20.9.3 JSFページでのトレイン・モデルへのバインド方法

21 実行時のコンポーネントの決定

- 21.1 実行時のコンポーネントの決定について

- 21.2 動的コンポーネントのモデルの作成

- 21.2.1 グループのないモデルの作成方法

- 21.2.2 グループを使用するモデルの作成方法

- 21.3 動的コンポーネントをフォームとしてページに追加する

- 21.3.1 動的コンポーネントをグループなしでフォームとしてページに追加する方法

- 21.3.2 動的コンポーネントをグループ付きでフォームとしてページに追加する方法

- 21.4 動的コンポーネントを表としてページに追加する

- 21.4.1 動的コンポーネントをグループなしで表としてページに追加する方法

- 21.4.2 動的コンポーネントをグループ付きで表としてページに追加する方法

- 21.5 動的コンポーネントでの検証および変換の使用

- 21.6 動的および静的のコンポーネントの同時使用

第V部 ADFデータ視覚化コンポーネントの使用

22 ADFデータ視覚化コンポーネントの概要

- 22.1 ADFデータ視覚化コンポーネントについて

- 22.1.1 グラフ・コンポーネントのユースケースおよび例

- 22.1.2 ゲージ・コンポーネントのユースケースおよび例

- 22.1.3 ピボット・テーブルのユースケースおよび例

- 22.1.4 地理マップのユースケースおよび例

- 22.1.5 テーマ・マップ・コンポーネントのユースケースおよび例

- 22.1.6 ガント・チャート・コンポーネントのユースケースおよび例

- 22.1.7 時系列コンポーネントのユースケースおよび例

- 22.1.8 階層ビューア・コンポーネントのユースケースおよび例

- 22.1.9 ツリーマップおよびサンバースト・コンポーネントのユースケースおよび例

- 22.1.10 データ視覚化コンポーネントの追加機能

- 22.2 データ視覚化コンポーネントの共通機能

- 22.2.1 コンテンツの配信

- 22.2.2 自動部分ページ・レンダリング(PPR)

- 22.2.3 アクティブ・データ・サポート

- 22.2.4 グラフ、ゲージ、ツリーマップおよびサンバーストのコンテキスト・メニュー

- 22.2.5 スクリーン・リーダーのサポート

- 22.2.6 アプリケーション・リソース・バンドルのテキスト・リソース

- 22.3 ADFデータ視覚化コンポーネントへのデータの指定

23 グラフ・コンポーネントの使用方法

- 23.1 グラフ・コンポーネントについて

- 23.1.1 グラフ・コンポーネントのユースケースおよび例

- 23.1.2 エンド・ユーザー機能およびプレゼンテーション機能

- 23.1.2.1 グラフ・レイアウト

- 23.1.2.2 サイズ設定

- 23.1.2.3 イメージ形式

- 23.1.2.4 データ・マーカー選択

- 23.1.2.5 コンテキスト・メニュー

- 23.1.2.6 参照面/線およびアラート

- 23.1.2.7 系列の非表示および表示

- 23.1.2.8 ドリル

- 23.1.2.9 注釈

- 23.1.2.10 ポップアップのサポート

- 23.1.2.11 時間セレクタ

- 23.1.2.12 双方向サポート

- 23.1.2.13 ドラッグ・アンド・ドロップ

- 23.1.2.14 スクリーン・リーダーのサポート

- 23.1.3 グラフ・コンポーネントの追加機能

- 23.2 グラフ・コンポーネントの使用方法

- 23.2.1 グラフ・タイプのデータ要件

- 23.2.2 グラフの構成

- 23.2.3 ページへのグラフの追加方法

- 23.2.4 ページにグラフを追加する場合の処理

- 23.2.5 表形式データを使用したグラフの作成方法

- 23.2.6 グラフのイメージ形式に関する必知事項

- 23.2.7 ビジュアル・エディタおよび「プロパティ」ウィンドウでのグラフの編集

- 23.3 グラフ表示要素のカスタマイズ

- 23.3.1 グラフのサイズとスタイルの変更

- 23.3.1.1 グラフが初めて表示される際のサイズの指定方法

- 23.3.1.2 グラフの動的サイズ変更の指定方法

- 23.3.1.3 特定のスタイルシートをグラフに使用する方法

- 23.3.2 グラフの背景、描画エリアおよびタイトルの変更

- 23.3.2.1 グラフの背景と描画エリアのカスタマイズ方法

- 23.3.2.2 グラフのタイトルと脚注の指定方法

- 23.3.3 グラフの軸およびラベルのカスタマイズ方法

- 23.3.3.1 軸のタイトル、外観およびスケーリングの指定方法

- 23.3.3.2 軸でのスクロールの指定

- 23.3.3.3 軸のティック・マークとティック・ラベルの外観の制御方法

- 23.3.3.4 軸の数値の書式設定

- 23.3.3.5 データ軸の最小値および最大値の設定方法

- 23.3.4 グラフの凡例のカスタマイズ方法

- 23.3.5 グラフのツールチップのカスタマイズ

- 23.4 グラフのテキスト、色およびデータ値の書式設定

- 23.4.1 グラフのテキストの書式設定

- 23.4.1.1 スキンを使用したグラフ・フォントの全体的な設定方法

- 23.4.2 グラフの一部への透明色の指定

- 23.4.3 グラフでのグラデーション特殊効果の使用

- 23.4.3.1 グラデーション特殊効果のグラフへの追加方法

- 23.4.3.2 グラデーション特殊効果をグラフに追加する場合の処理

- 23.4.4 グラフ内のデータ値の書式設定

- 23.4.4.1 カテゴリ・データ値の書式設定方法

- 23.4.4.2 数値データ値の書式設定方法

- 23.4.4.3 自動位取りおよび精度に関する必知事項

- 23.5 データの系列およびグループの外観のカスタマイズ

- 23.5.1 グラフ・データ値の色、スタイルおよび表示の変更

- 23.5.1.1 個々の系列アイテムの色とスタイルの指定方法

- 23.5.1.2 系列アイテムの非表示および表示を有効にする方法

- 23.5.2 円グラフの外観の変更

- 23.5.2.1 円グラフ全体の外観のカスタマイズ方法

- 23.5.2.2 円グラフのスライスの切離しのカスタマイズ方法

- 23.5.3 グラフでの線の外観の変更

- 23.5.3.1 グラフでのデータ線またはデータ・マーカーの表示

- 23.5.3.2 グラフ系列の線の外観の変更

- 23.5.4 パレート・グラフのカスタマイズ方法

- 23.5.5 散布図の系列マーカー・データ値のカスタマイズ

- 23.5.6 グラフ・マーカーの形状のカスタマイズ

- 23.5.7 参照線または領域のグラフへの追加

- 23.5.7.1 設計時に参照線または領域を作成する方法

- 23.5.7.2 設計時に参照線または領域を作成する場合の処理

- 23.5.7.3 参照線または領域の動的作成方法

- 23.6 グラフへのアニメーションの使用

- 23.6.1 アクティブ・データを表示するデータ・バインドされたグラフ・コンポーネントの構成方法

- 23.6.2 グラフのアニメーション効果の指定

- 23.7 インタラクティブな機能のグラフへの追加

- 23.7.1 マーカーと凡例の淡色表示の追加方法

- 23.7.2 ズームとスクロール・レベルの変更に対応する方法

- 23.7.3 インタラクティブな時間軸のグラフへの追加

- 23.7.3.1 時間データを表示する相対的範囲の定義方法

- 23.7.3.2 時間データを表示する明示的範囲の定義方法

- 23.7.3.3 グラフへの時間セレクタの追加方法

- 23.7.4 アラートおよび注釈のグラフへの追加

- 23.7.4.1 グラフへのアラートの追加方法

- 23.7.4.2 グラフへの注釈の追加

- 23.7.5 ドリル可能なグラフの作成

- 23.7.6 グラフへのドラッグ・アンド・ドロップの追加

- 23.7.6.1 グラフにドラッグ・アンド・ドロップを追加する方法

- 23.7.6.2 グラフへのドラッグ・アンド・ドロップの追加に関する必知事項

- 23.7.7 グラフへのポップアップの追加方法

- 23.7.8 グラフのデータ・マーカー選択サポートの追加

- 23.7.8.1 グラフへの選択サポートの追加方法

- 23.7.8.2 グラフのデータ・マーカー選択に関する必知事項

- 23.7.9 グラフのコンテキスト・メニューの構成

24 ゲージ・コンポーネントの使用方法

- 24.1 ゲージ・コンポーネントについて

- 24.1.1 ゲージ・コンポーネントのユースケースおよび例

- 24.1.2 ゲージ・コンポーネントのエンド・ユーザー機能およびプレゼンテーション機能

- 24.1.3 ゲージ・コンポーネントの追加機能

- 24.2 ゲージ・コンポーネントの使用方法

- 24.2.1 ゲージの構成

- 24.2.2 ページへのゲージの追加方法

- 24.2.3 ページにゲージを追加する場合の処理

- 24.2.4 表形式データを使用したゲージの作成方法

- 24.2.5 ゲージのイメージ形式に関する必知事項

- 24.2.6 表へのゲージの追加方法

- 24.3 ゲージ表示要素の構成

- 24.3.1 ゲージしきい値の構成方法

- 24.3.2 ゲージ・ラベルのカスタマイズ方法

- 24.3.3 ゲージ・インジケータおよびティック・マークのカスタマイズ方法

- 24.4 ゲージ・スタイル要素の書式設定

- 24.4.1 ゲージ・サイズの変更方法およびCSSスタイルの適用方法

- 24.4.2 ゲージ要素の透明度の指定

- 24.4.3 ゲージ・テキストの書式設定方法

- 24.4.4 ゲージのテキスト・リソースの指定方法

- 24.4.5 スキンを使用してゲージ・スタイルをグローバルに設定する方法

- 24.5 ゲージの数値データ値の書式設定

- 24.5.1 ゲージの数値データ値の書式設定方法

- 24.5.2 自動位取りおよび精度に関する必知事項

- 24.6 ゲージの特殊効果およびアニメーションの追加

- 24.6.1 グラデーション特殊効果のゲージへの追加方法

- 24.6.2 グラデーション特殊効果をゲージに追加する場合の処理

- 24.6.3 ゲージへの相互作用の追加方法

- 24.6.4 ゲージへのアニメーションの使用

- 24.6.5 ゲージのアニメーション効果の指定方法

- 24.6.5.1スキニングおよびゲージのアニメーション効果に関する必知事項

- 24.6.6 アクティブ・データを表示するゲージの構成方法

- 24.7 ゲージのカスタム形状の使用方法

- 24.7.1 事前作成されたカスタム形状スタイルの使用方法

- 24.7.2 カスタム形状グラフィック・ファイルの使用方法

- 24.7.3 サポートされているSVG機能に関する必知事項

25 ピボット・テーブル・コンポーネントの使用方法

- 25.1 ピボット・テーブル・コンポーネントについて

- 25.1.1 ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントのユースケースおよび例

- 25.1.2 ピボット・テーブル・コンポーネントのエンド・ユーザー機能およびプレゼンテーション機能

- 25.1.2.1 ピボット・フィルタ・バー

- 25.1.2.2 ピボット処理

- 25.1.2.3 データ・セルの編集

- 25.1.2.4 データおよびヘッダーのソート

- 25.1.2.5 ドリル

- 25.1.2.6 スクロールおよびページ・コントロール

- 25.1.2.7 永続ヘッダー・レイヤー

- 25.1.2.8 大規模データ・セットの分割ビュー

- 25.1.2.9 サイズ設定

- 25.1.2.10 ヘッダー・セルの折返し

- 25.1.2.11 ADS(アクティブ・データ・サポート)

- 25.1.3 ピボット・テーブル・コンポーネントの追加機能

- 25.2 ピボット・テーブル・コンポーネントの使用方法

- 25.2.1 ピボット・テーブルのデータ要件

- 25.2.2 ピボット・テーブルの構成

- 25.2.3 ページへのピボット・テーブルの追加方法

- 25.2.4 ピボット・テーブルの表示サイズおよびスタイルの構成

- 25.2.5 ページにピボット・テーブルを追加する場合の処理

- 25.2.6 大規模なデータ・セットの表示について

- 25.2.7 タッチ装置でのピボット・テーブルに関する必知事項

- 25.3 ヘッダーおよびデータ・セルのスタンプの構成

- 25.3.1 varおよびvarStatusプロパティの使用方法

- 25.3.2 ヘッダーおよびデータ・セルのスタンプの構成方法

- 25.4 ピボット・フィルタ・バーの使用方法

- 25.4.1 ピボット・テーブルでのピボット・フィルタ・バーの使用方法

- 25.4.2 グラフでのピボット・フィルタ・バーの使用方法

- 25.5 ピボット・テーブルへの相互作用の追加

- 25.5.1 ピボット・テーブルでの選択の使用方法

- 25.5.2 部分ページ・レンダリングの使用方法

- 25.5.3 ピボット・テーブルからのエクスポート

- 25.5.4 印刷可能ページでのピボット・テーブルの表示

- 25.6 CellFormatによるピボット・テーブルのセルのコンテンツの書式設定

- 25.6.1 データ・セルに対するCellFormatオブジェクトの使用方法

- 25.6.2 セルの書式設定の指定

- 25.6.3 CellFormatを使用したストップライトおよび条件付き書式設定の構成

26 ガント・チャート・コンポーネントの使用方法

- 26.1 ガント・チャート・コンポーネントについて

- 26.1.1 ガント・チャート・コンポーネントのユースケースおよび例

- 26.1.2 エンド・ユーザー機能およびプレゼンテーション機能

- 26.1.2.1 ガント・チャートの領域

- 26.1.2.2 情報パネル

- 26.1.2.3 ツールバー

- 26.1.2.4 スクロール、ズームおよびパン

- 26.1.2.5 依存関係の表示

- 26.1.2.6 コンテキスト・メニュー

- 26.1.2.7 行の選択

- 26.1.2.8 タスクの編集

- 26.1.2.9 サーバー側イベント

- 26.1.2.10 印刷

- 26.1.2.11 コンテンツの配信

- 26.1.3 ガント・チャート・コンポーネントの追加機能

- 26.2 ガント・チャート・コンポーネントの使用方法

- 26.2.1 プロジェクト・ガント・チャートのデータ

- 26.2.2 リソース使用率ガント・チャートのデータ

- 26.2.3 スケジュール・ガント・チャートのデータ

- 26.2.4 ガント・チャートのタスクおよびリソース

- 26.2.5 ガント・チャートの構成

- 26.2.6 ページへのガント・チャートの追加方法

- 26.2.7 ページにガント・チャートを追加する場合の処理

- 26.3 ガント・チャートのタスクおよびリソースのカスタマイズ

- 26.3.1 新しいタスク・タイプの作成

- 26.3.2 リソース使用率ガント・チャートでの積上げ棒の構成

- 26.3.3 リソース容量線の構成

- 26.3.4 リソース属性の詳細の表示

- 26.4 ガント・チャートの表示要素のカスタマイズ

- 26.4.1 ガント・チャートでの休日の指定

- 26.4.1.1 曜日を休日として指定する方法

- 26.4.1.2 特定の日付を休日として指定する方法

- 26.4.2 ガント・チャート機能に読取り専用の値を適用する方法

- 26.4.3 ガント・チャートの時間軸のカスタマイズ方法

- 26.4.4 ガント・チャートの凡例の作成およびカスタマイズ

- 26.4.5 ガント・チャートのツールバーのカスタマイズ

- 26.4.6 ガント・チャートのポップアップ・メニューのカスタマイズ

- 26.4.7 カスタム・データ・フィルタの指定方法

- 26.5 ガント・チャートへのインタラクティブ機能の追加

- 26.5.1 選択したタスクまたはリソースでのアクションの実行

- 26.5.2 ガント・チャートでのページ・コントロールの使用方法

- 26.5.3 ガント・チャート間の同期スクロールの構成

- 26.5.4 ガント・チャートの印刷

- 26.5.4.1 印刷オプション

- 26.5.4.2 印刷イベントを処理するアクション・リスナー

- 26.5.5 タスク・バーへのダブルクリック・イベントの追加

- 26.5.6 ドロップ・ターゲットまたはドラッグ・ソースとしてのガント・チャートの使用

27 時系列コンポーネントの使用

- 27.1 時系列コンポーネントについて

- 27.1.1 時系列のユースケースと例

- 27.1.2 エンド・ユーザー機能およびプレゼンテーション機能

- 27.1.2.1 レイアウト・オプション

- 27.1.2.2 時系列アイテムの選択

- 27.1.2.3 時系列のグループ化とソート

- 27.1.2.4 ドラッグ・アンド・ドロップのサポート

- 27.1.2.5 コンテンツの配信

- 27.1.2.6 時系列のイメージ形式

- 27.1.2.7 印刷可能または電子メール送信可能なページの時系列表示

- 27.1.3 時系列コンポーネントの追加機能

- 27.2 時系列コンポーネントの使用

- 27.2.1 時系列コンポーネントのデータ要件

- 27.2.2 時系列の構成

- 27.2.3 ページへの時系列の追加方法

- 27.2.4 ページに時系列を追加する場合の処理

- 27.3 時系列コンポーネントへのデータの追加

- 27.3.1 時系列へのデータの追加方法

- 27.3.2 2つの時系列のデータの構成に関する必知事項

- 27.3.3 時系列へのデータの追加に関する必知事項

- 27.4 時系列表示要素のカスタマイズ

- 27.4.1 時系列アイテムのカスタマイズ

- 27.4.2 時系列へのカスタム・タイム・スケールの追加方法

- 27.5 インタラクティブ機能の時系列への追加

- 27.5.1 時系列アイテムへのポップアップの追加方法

- 27.5.2 時系列のコンテキスト・メニューの構成方法

- 27.5.3 時系列へのドラッグ・アンド・ドロップの追加方法

28 マップ・コンポーネントの使用方法

- 28.1 マップ・コンポーネントについて

- 28.1.1 マップ・コンポーネントのユースケースおよび例

- 28.1.2 マップのエンド・ユーザー機能およびプレゼンテーション機能

- 28.1.2.1 地理マップのエンド・ユーザー機能およびプレゼンテーション機能

- 28.1.2.2 テーマ・マップのエンド・ユーザー機能およびプレゼンテーション機能

- 28.1.3 マップ・コンポーネントの追加機能

- 28.2 地理マップ・コンポーネントの使用方法

- 28.2.1 地理マップ・コンポーネントの構成

- 28.2.2 ページへの地理マップの追加方法

- 28.2.3 ページに地理マップを追加する場合の処理

- 28.2.4 マップ点テーマのアクティブ・データ・サポートに関する必知事項

- 28.3 地理マップ表示属性のカスタマイズ

- 28.3.1 マップ・サイズの調整方法

- 28.3.2 マップ・ズーム制御のストラテジの指定方法

- 28.3.3 マップ選択のカスタマイズおよび使用方法

- 28.3.4 マップの凡例をカスタマイズする方法

- 28.4 地理マップ・テーマのカスタマイズ

- 28.4.1 テーマのズーム・レベルのカスタマイズ方法

- 28.4.2 マップ・テーマのラベルのカスタマイズ方法

- 28.4.3 色マップ・テーマのカスタマイズ方法

- 28.4.4 点テーマの点のイメージのカスタマイズ方法

- 28.4.5 マップのポイント・イメージをカスタマイズする場合の処理

- 28.4.6 棒グラフ・テーマの棒のカスタマイズ方法

- 28.4.7 マップ棒グラフ・テーマの棒をカスタマイズする場合の処理

- 28.4.8 円グラフ・テーマのスライスのカスタマイズ方法

- 28.4.9 マップ円グラフ・テーマのスライスをカスタマイズする場合の処理

- 28.5 地理マップへのツールバーの追加

- 28.5.1 ツールバーのマップへの追加方法

- 28.5.2 ツールバーをマップに追加する場合の処理

- 28.6 テーマ・マップ・コンポーネントの使用方法

- 28.6.1 テーマ・マップの構成

- 28.6.2 事前作成された基準となるマップに関する必知事項

- 28.6.3 レイヤー・ブラウザの使用方法

- 28.6.4 ページへのテーマ・マップの追加方法

- 28.6.5 ページにテーマ・マップを追加する場合の処理

- 28.6.6 テーマ・マップのイメージ形式に関する必知事項

- 28.7 テーマ・マップ表示属性のカスタマイズ

- 28.7.1 テーマ・マップ・ラベルのカスタマイズ方法

- 28.7.2 データを表示するツールチップの構成方法

- 28.7.3 エリアおよびマーカー・ラベルでの数値データ値の書式設定方法

- 28.8 インタラクティブ機能のテーマ・マップへの追加

- 28.8.1 テーマ・マップで選択およびアクション・イベントを構成する方法

- 28.8.2 テーマ・マップ・エリアおよびマーカーにポップアップを追加する方法

- 28.8.3 アニメーション効果の構成方法

- 28.8.4 テーマ・マップ・コンポーネントにドラッグ・アンド・ドロップを追加する方法

29 階層ビューア・コンポーネントの使用方法

- 29.1 階層ビューア・コンポーネントについて

- 29.1.1 階層ビューアのユースケースおよび例

- 29.1.2 エンド・ユーザー機能およびプレゼンテーション機能

- 29.1.2.1 レイアウト

- 29.1.2.2 ナビゲーション

- 29.1.2.3 ティルト・パン

- 29.1.2.4 コントロール・パネル

- 29.1.2.5 印刷

- 29.1.2.6 双方向サポート

- 29.1.2.7 状態の管理

- 29.1.3 階層ビューア・コンポーネントの追加機能

- 29.2 階層ビューア・コンポーネントの使用方法

- 29.2.1 階層ビューア・コンポーネントの構成

- 29.2.2 ページへの階層ビューアの追加方法

- 29.2.3 ページに階層ビューアを追加する場合の処理

- 29.2.4 階層ビューアのレンダリングとHTMLに関する必知事項

- 29.3 階層ビューアでのノードの管理

- 29.3.1 ノード・コンテンツの指定方法

- 29.3.2 ノードのコントロールの構成方法

- 29.3.3 アクセッサのノード定義の指定

- 29.3.4 ノード定義と特定のデータ行のセットとの関連付け

- 29.3.5 アンカー・ノードの祖先レベルの指定方法

- 29.4 パネル・カードの使用

- 29.4.1 パネル・カードの作成方法

- 29.4.2 実行時の処理: パネル・カード・コンポーネントのレンダリング方法

- 29.5 階層ビューアでのナビゲーションの構成

- 29.5.1 階層ビューアでの上方向へのナビゲーションの構成方法

- 29.5.2 階層ビューアでの同レベル・ナビゲーションの構成方法

- 29.5.3 階層ビューアで同レベル・ナビゲーションを構成する場合の処理

- 29.6 階層ビューアの外観のカスタマイズ

- 29.6.1 階層ビューアのサイズの調整方法

- 29.6.1.1 スキニングとhierarchyViewerコンポーネントに関する必知事項

- 29.6.2 階層ビューアにイメージを含める方法

- 29.6.3 コントロール・パネルの表示の構成方法

- 29.6.4 リンクおよびラベルの表示を構成する方法

- 29.6.5 ホバー・ディテール・ウィンドウの無効化の方法

- 29.7 階層ビューア・コンポーネントへの対話性の追加

- 29.7.1 ノード選択アクションを構成する方法

- 29.7.2 ポップアップ・ウィンドウを起動するための階層ビューアの構成

- 29.7.3 階層ビューアのドラッグ・アンド・ドロップの構成

- 29.7.3.1 階層ビューアのドラッグ・アンド・ドロップの構成方法

- 29.7.3.2 階層ビューアのドラッグ・アンド・ドロップに関する必知事項

- 29.8 階層ビューアへの検索の追加

- 29.8.1 階層ビューアでの検索の構成方法

- 29.8.2 階層ビューアでの検索の構成に関する必知事項

30 ツリーマップとサンバースト・コンポーネントの使用

- 30.1 ツリーマップとサンバースト・コンポーネントについて

- 30.1.1 ツリーマップとサンバーストの使用ケースと例

- 30.1.2 ツリーマップとサンバーストのエンド・ユーザー機能およびプレゼンテーション機能

- 30.1.2.1 ツリーマップとサンバーストのレイアウト

- 30.1.2.2 属性グループ

- 30.1.2.3 凡例サポート

- 30.1.2.4 パターンのサポート

- 30.1.2.5 ノード選択のサポート

- 30.1.2.6 ツールチップのサポート

- 30.1.2.7 ポップアップのサポート

- 30.1.2.8 コンテキスト・メニュー

- 30.1.2.9 ドリルのサポート

- 30.1.2.10 その他のノード・サポート

- 30.1.2.11 ドラッグ・アンド・ドロップのサポート

- 30.1.2.12 ソートのサポート

- 30.1.2.13 ツリーマップとサンバーストのイメージ形式

- 30.1.2.14 拡張ノード・コンテンツ

- 30.1.2.15 印刷とメールのサポート

- 30.1.2.16 ADS(アクティブ・データ・サポート)

- 30.1.2.17 独立性のサポート(ツリーマップのみ)

- 30.1.2.18 ツリーマップ・グループ・ノード・ヘッダーのカスタマイズ(ツリーマップのみ)

- 30.1.3 ツリーマップおよびサンバースト・コンポーネントの追加機能

- 30.2 ツリーマップおよびサンバースト・コンポーネントの使用

- 30.2.1 ツリーマップとサンバーストのデータ要件

- 30.2.2 ツリーマップ・コンポーネントの使用

- 30.2.2.1 ツリーマップの構成

- 30.2.2.2 ツリーマップをページに追加する方法

- 30.2.2.3 ツリーマップをページに追加した場合の処理内容

- 30.2.3 サンバースト・コンポーネントの使用

- 30.2.3.1 サンバーストの構成

- 30.2.3.2 サンバーストをページに追加する方法

- 30.2.3.3 ページへのサンバースト追加時の処理内容

- 30.3 ツリーマップとサンバースト・コンポーネントへのデータの追加

- 30.3.1 ツリーマップあるいはサンバースト・コンポーネントへのデータの追加方法

- 30.3.2 ツリーマップおよびサンバーストへのデータ追加に関する必知事項

- 30.4 ツリーマップとサンバーストの表示要素のカスタマイズ

- 30.4.1 ツリーマップとサンバーストの表示サイズとスタイルの構成

- 30.4.2 パターン表示の構成

- 30.4.3 ツリーマップとサンバーストの属性グループ

- 30.4.3.1 ツリーマップとサンバーストの離散属性グループの構成方法

- 30.4.3.2 ツリーマップとサンバーストの連続属性グループの構成方法

- 30.4.3.3 属性グループの構成に関する必知事項

- 30.4.4 ツリーマップとサンバーストの凡例の構成方法

- 30.4.5 ツリーマップとサンバーストのその他のノードの構成

- 30.4.5.1 ツリーマップとサンバーストのその他のノードの構成方法

- 30.4.5.2 ツリーマップおよびサンバーストのその他のノードの構成に関する必知事項

- 30.4.6 ツリーマップとサンバーストのソートの構成

- 30.4.7 ツリーマップとサンバーストの拡張ノード・コンテンツの構成

- 30.4.7.1 拡張ノード・コンテンツをツリーマップに追加する方法

- 30.4.7.2 拡張ノード・コンテンツをサンバーストに追加する方法

- 30.4.7.3 ツリーマップ上の拡張ノード・コンテンツの構成に関する必知事項

- 30.4.8 ツリーマップとサンバーストでのアニメーションの構成方法

- 30.4.9 ツリーマップとサンバーストでのラベルの構成

- 30.4.9.1 ツリーマップ・リーフ・ノード・ラベルの構成方法

- 30.4.9.2 サンバースト・ノード・ラベルの構成方法

- 30.4.10 ツリーマップ・ノード・ヘッダーとグループ・ギャップの構成

- 30.4.10.1 ツリーマップ・ノード・ヘッダーの構成方法

- 30.4.10.2 ツリーマップ・ノード・ヘッダーに関する必知事項

- 30.4.10.3 ツリーマップ・グループ・ギャップのカスタマイズ方法

- 30.5 ツリーマップとサンバーストヘの対話機能の追加

- 30.5.1 ツリーマップとサンバーストのツールチップの構成

- 30.5.2 ツリーマップとサンバーストのポップアップの構成

- 30.5.2.1 ツリーマップおよびサンバースト・コンポーネントへのポップアップの追加方法

- 30.5.2.2 ツリーマップおよびサンバースト・コンポーネントへのポップアップの追加に関する必知事項

- 30.5.3 ツリーマップとサンバーストの選択サポートの構成

- 30.5.3.1 ツリーマップおよびサンバースト・コンポーネントへの選択サポートの追加方法

- 30.5.3.2 ツリーマップおよびサンバーストへの選択サポートの追加に関する必知事項

- 30.5.4 ツリーマップとサンバーストのコンテキスト・メニューの構成

- 30.5.4.1 ツリーマップとサンバーストのコンテキスト・メニューの構成方法

- 30.5.4.2 ツリーマップおよびサンバーストのコンテキスト・メニューの構成に関する必知事項

- 30.5.5 ツリーマップとサンバーストのドリル・サポートの構成

- 30.5.5.1 ツリーマップとサンバーストのドリル・サポートの構成方法

- 30.5.5.2 ツリーマップとドリル・サポートに関する必知事項

- 30.5.6 ツリーマップおよびサンバーストへのドラッグ・アンド・ドロップの追加方法

- 30.5.7 独立性サポートの構成(ツリーマップのみ)

- 30.5.7.1 独立性サポートを無効化する方法

- 30.5.7.2 ツリーマップと独立性サポートに関する必知事項

第VI部 ビューの完成

31 スタイルおよびスキンを使用した外観のカスタマイズ

- 31.1 スタイルおよびスキンを使用した外観のカスタマイズについて

- 31.1.1 外観のカスタマイズのユースケースおよび例

- 31.1.2 外観のカスタマイズの追加機能

- 31.2 コンポーネントのスタイル・プロパティの変更

- 31.2.1 インライン・スタイルの設定方法

- 31.2.2 スタイル・クラスの設定方法

- 31.3 エンド・ユーザーによるアプリケーションのADFスキン変更の許可

- 31.3.1 エンド・ユーザーによるアプリケーションのADFスキン変更を許可する方法

- 31.3.2 実行時の処理: エンド・ユーザーによるアプリケーションのADFスキンの変更方法

32 ページの国際化およびローカライズ

- 32.1 ADF Facesページの国際化およびローカライズについて

- 32.1.1 ページの国際化およびローカライズのユースケースおよび例

- 32.1.2 ページの国際化およびローカライズの追加機能

- 32.2 JDeveloperにおける自動リソース・バンドル統合の使用

- 32.2.1 リソース・バンドル・オプションの設定方法

- 32.2.2 リソース・バンドル・オプションを設定する場合の処理

- 32.2.3 JDeveloper生成リソース・バンドルでのエントリの作成方法

- 32.2.4 JDeveloper生成リソース・バンドルでエントリを生成する場合の処理

- 32.3 リソース・バンドルおよびロケールの手動による定義

- 32.3.1 リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する方法

- 32.3.2 リソース・バンドルをJavaクラスとして作成する方法

- 32.3.3 リソース・バンドル・ファイルの編集方法

- 32.3.4 アプリケーションへのロケールの登録方法

- 32.3.5 アプリケーションへのリソース・バンドルの登録方法

- 32.3.6 アプリケーションでのリソース・バンドルの使用方法

- 32.3.7 ADFスキンおよびコントロールのヒントに関する必知事項

- 32.3.8 カスタマイズ可能アプリケーションでのリソース・バンドルのオーバーライドに関する必知事項

- 32.4 エンド・ユーザーが実行時にロケールを指定するためのページの構成

- 32.4.1 エンド・ユーザーがロケールを指定するようにページを構成する方法

- 32.4.2 ロケールを指定するためにページを構成する場合の処理

- 32.4.3 実行時の処理: エンド・ユーザーによるロケールの指定方法

- 32.5 ADF Facesのオプションのローカライゼーション・プロパティの構成

- 32.5.1 オプションのローカライゼーション・プロパティの構成方法

33 アクセス可能なADF Facesページの開発

- 33.1 ADF Facesでのアクセシビリティ・サポートについて

- 33.1.1 ADF Facesアクセシビリティ・サポートのユースケースおよび例

- 33.1.2 ADFページでのアクセシビリティ・サポートの追加情報

- 33.2 ADF Facesでのアクセシビリティ・サポートの構成

- 33.2.1 サインインでのアクセシビリティ・サポート・ガイドライン

- 33.2.2 trinidad-config.xmlにおけるアクセシビリティ・サポートの構成方法

- 33.3 コンポーネント・レベルのアクセシビリティ・プロパティの指定

- 33.3.1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

- 33.3.2 スクリーン・リーダー・モードでのADF Faces表コンポーネントの使用方法

- 33.3.3 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

- 33.3.4 ADF Facesコンポーネントのアクセス・キーの定義方法

- 33.3.5 ローカライズされたラベルおよびアクセス・キーの定義方法

- 33.4 アクセス可能なページの作成

- 33.4.1 部分ページ・レンダリングの使用方法

- 33.4.2 スクリプトの使用方法

- 33.4.3 スタイルの使用方法

- 33.4.4 ページ構造およびナビゲーションの使用方法

- 33.4.5 イメージおよび表の使用方法

- 33.4.6 WAI-ARIAランドマーク・リージョンの使用方法

- 33.5 アクセシビリティ監査ルールの実行

- 33.5.1 コード監査プロファイルの作成方法

- 33.5.2 監査レポートの実行方法

34 カスタムADF Facesコンポーネントの作成

- 34.1 カスタムADF Facesコンポーネントについて

- 34.1.1 JDeveloperを使用したカスタム・コンポーネントの開発

- 34.1.2 カスタム・コンポーネントの例

- 34.2 ワークスペースと基礎ファイルの設定

- 34.2.1 JDeveloperカスタム・コンポーネント環境の設定方法

- 34.2.2 Faces構成ファイルの追加方法

- 34.2.3 MyFaces Trinidadスキン構成ファイルの追加方法

- 34.2.4 Cascading Style Sheetの追加方法

- 34.2.5 リソース・キット・ローダーの追加方法

- 34.2.6 JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法

- 34.2.7 JavaScriptライブラリ機能構成ファイルの追加方法

- 34.2.8 Faceletタグ・ライブラリ構成ファイルの追加方法

- 34.3 クライアント側の開発

- 34.3.1 コンポーネントのJavaScriptファイルの作成方法

- 34.3.2 イベントのJavaScriptファイルの作成方法

- 34.3.3 ピアのJavaScriptファイルの作成方法

- 34.3.4 JavaScriptライブラリ機能構成ファイルへのカスタム・コンポーネントの追加方法

- 34.4 サーバー側の開発

- 34.4.1 イベント・リスナーのクラスの作成方法

- 34.4.2 イベントのクラスの作成方法

- 34.4.3 コンポーネントの作成

- 34.4.4 コンポーネントのクラスの作成方法

- 34.4.5 faces-config.xmlファイルへのコンポーネントの追加方法

- 34.4.6 リソース・バンドルのクラスの作成方法

- 34.4.7 レンダラのクラスの作成方法

- 34.4.8 faces-config.xmlファイルへのレンダラの追加方法

- 34.4.9 JSPタグ・プロパティの作成方法

- 34.4.10 タグ・ライブラリ・ディスクリプタの構成方法

- 34.4.11 リソース・ローダーの作成方法

- 34.4.12 MyFaces Trinidad Cascading Style Sheetの作成方法

- 34.5 コンポーネント・ライブラリのデプロイ

- 34.5.1 コンポーネント・ライブラリのデプロイ方法

- 34.6 アプリケーションへのカスタム・コンポーネントの追加

- 34.6.1 Webデプロイメント・ディスクリプタの構成方法

- 34.6.2 JavaScriptロギングとアサーションを有効にする方法

- 34.6.3 JSFページへのカスタム・コンポーネントの追加方法

- 34.6.4 tagPaneカスタム・コンポーネントの使用に関する必知事項

35 JSFページでのユーザー・カスタマイズの許可

- 35.1 ユーザー・カスタマイズについて

- 35.1.1 ユーザー・カスタマイズのユースケースおよび例

- 35.2 セッション変更永続性の実装

- 35.2.1 セッション変更永続性の実装方法

- 35.2.2 変更永続性を使用するようアプリケーションを構成する場合の処理

- 35.2.3 実行時の処理: 変更をどのように永続させるか

- 35.2.4 テンプレートおよび領域での変更永続性の使用に関する必知事項

36 ドラッグ・アンド・ドロップ機能の追加

- 36.1 ドラッグ・アンド・ドロップ機能について

- 36.1.1 ドラッグ・アンド・ドロップの追加機能

- 36.2 属性のドラッグ・アンド・ドロップ機能の追加

- 36.2.1 ドラッグ・アンド・ドロップ機能の追加方法

- 36.3 オブジェクトのドラッグ・アンド・ドロップ機能の追加

- 36.3.1 単一オブジェクトのドラッグ・アンド・ドロップ機能の追加方法

- 36.3.2 実行時の処理: キーボード修飾子の使用方法

- 36.3.3 ClientDropListenerの使用に関する必知事項

- 36.4 コレクションのドラッグ・アンド・ドロップ機能の追加

- 36.4.1 コレクションのドラッグ・アンド・ドロップ機能の追加方法

- 36.4.2 dragDropEndListenerに関する必知事項

- 36.5 コンポーネントのドラッグ・アンド・ドロップ機能の追加

- 36.5.1 コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

- 36.6 panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加

- 36.6.1 panelDashboardコンポーネントへのドラッグ・アンド・ドロップ機能の追加方法

- 36.6.2 panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の追加方法

- 36.7 Calendarへのドラッグ・アンド・ドロップ機能の追加

- 36.7.1 Calendarへのドラッグ・アンド・ドロップ機能の追加方法

- 36.7.2 Calendarのドラッグ・アンド・ドロップに関する必知事項

- 36.8 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加

- 36.8.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加

- 36.8.1.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加方法

- 36.8.2 DVTガント・チャートのドラッグ・アンド・ドロップ機能の追加

- 36.8.2.1 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加方法

- 36.8.3 DVT階層ビューア、サンバースト、およびツリーマップにドラッグ・アンド・ドロップ機能を追加する

- 36.8.3.1 DVT階層ビューアのドラッグ・アンド・ドロップの例

- 36.8.3.2 DVTサンバーストのドラッグ・アンド・ドロップの例

- 36.8.3.3 DVTツリーマップのドラッグ・アンド・ドロップの例

- 36.8.3.4 DVT階層ビューア、サンバースト、またはツリーマップ・コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

- 36.8.4 時系列コンポーネントのドラッグ・アンド・ドロップ機能の追加

37 異なる出力モードの使用方法

- 37.1 異なる出力モードの使用方法について

- 37.1.1 出力モードのユースケース

- 37.2 印刷用ページの表示

- 37.2.1 showPrintablePageBehaviorタグの使用方法

- 37.3 電子メール送信可能なページの作成

- 37.3.1 電子メール送信可能なページの作成方法

- 37.3.2 電子メール・クライアントでのページのレンダリングのテスト方法

- 37.3.3 実行時の処理: ADF FacesでJSFページがどのようにして電子メール送信可能なページに変換されるか

38 非同期バックエンドでのアクティブ・データ・サービスの使用方法

- 38.1 アクティブ・データ・サービスについて

- 38.1.1 アクティブ・データ・サービスのユースケースおよび例

- 38.2 アクティブ・データ・サービスを使用するためのプロセスの概要

- 38.3 マネージドBeanでのActiveModelインタフェースの実装

- 38.4 読取り一貫性の維持に関する必知事項

- 38.5 アクティブ・データ・サービスへのイベント渡し

- 38.6 データ更新イベント・リスナーの登録

- 38.7 アクティブ・データを表示するためのADFコンポーネントの構成

第VII部 付録

A ADF Facesの構成

- A.1 ADF Facesの構成について

- A.2 web.xmlでの構成

- A.2.1 web.xmlでのJSFとADF Facesの構成方法

- A.2.2 web.xmlに必要な要素に関する必知事項

- A.2.3 web.xmlのADF Facesコンテキスト・パラメータに関する必知事項

- A.2.3.1 状態保存

- A.2.3.2 デバッギング

- A.2.3.3 ファイルのアップロード

- A.2.3.4 リソース・デバッグ・モード

- A.2.3.5 ユーザー・カスタマイズ

- A.2.3.6 Real User Experience Insightに対するアプリケーションの有効化

- A.2.3.7 アサーション

- A.2.3.8 ダイアログ接頭辞

- A.2.3.9 CSSクラス名の圧縮

- A.2.3.10 アプリケーションに複数のADFスキンがある場合のキャッシュの制御

- A.2.3.11 テストの自動化

- A.2.3.12 UIViewRootキャッシング

- A.2.3.13 テーマと色調スタイル

- A.2.3.14 部分ページ・レンダリング

- A.2.3.15 部分ページ・ナビゲーション

- A.2.3.16 ポストバック・ペイロード・サイズの最適化

- A.2.3.17 JavaScriptのパーティション化

- A.2.3.18 フレームバスティング

- A.2.3.19 バージョン番号情報

- A.2.3.20 自動生成されたコンポーネントIDの抑制

- A.2.3.21 ADF Facesキャッシング・フィルタ

- A.2.3.22 コマンド・リンクへのネイティブのブラウザ・コンテキスト・メニューの構成

- A.2.3.23 Internet Explorer互換性ビュー・モード

- A.2.3.24 セッション・タイムアウトの警告

- A.2.3.25 HTTPストリーミングにおけるJSPタグの実行

- A.2.3.26 クリーンなURL

- A.2.3.27 ページのロード中スプラッシュ画面

- A.2.3.28 グラフとゲージのイメージ形式

- A.2.3.29 レイアウトと表コンポーネントの形状管理

- A.2.3.30 表におけるスクロールバーの動作

- A.2.3.31 本番プロジェクト・ステージ

- A.2.4 web.xmlのその他のコンテキスト・パラメータに関する必知事項

- A.3 faces-config.xmlでの構成

- A.3.1 faces-config.xmlでのADF Facesの構成方法

- A.4 adf-config.xmlでの構成

- A.4.1 adf-config.xmlでのADF Facesの構成方法

- A.4.2 ADF Faces Caching Filterへのキャッシング・ルールの定義

- A.4.3 コンポーネント出力形式としてのFlashの構成

- A.4.4 コンテンツ配信ネットワークの使用

- A.4.4.1 スキン・スタイルシートおよびCDNに関する必知事項

- A.4.4.2 リソース・ファイルのCDN用の準備に関する必知事項

- A.5 adf-settings.xmlでの構成

- A.5.1 adf-settings.xmlでのADF Facesの構成方法

- A.5.2 adf-settings.xmlの要素に関する必知事項

- A.5.2.1 ヘルプ・システム

- A.5.2.2 キャッシング・ルール

- A.6 trinidad-config.xmlでの構成

- A.6.1 trinidad-config.xmlでのADF Facesの機能の構成方法

- A.6.2 trinidad-config.xmlの要素に関する必知事項

- A.6.2.1 アニメーションの有効化

- A.6.2.2 スキン・ファミリ

- A.6.2.3 タイムゾーンおよび年

- A.6.2.4 拡張デバッグ出力

- A.6.2.5 ページ・アクセシビリティ・レベル

- A.6.2.6 言語読取り方向

- A.6.2.7 通貨コードおよび数値の桁/小数点の区切り文字

- A.6.2.8 日付と数値ロケールの書式設定

- A.6.2.9 出力モード

- A.6.2.10 アクティブなPageFlowScopeインスタンスの数

- A.6.2.11 ファイルのアップロード

- A.6.2.12 カスタム・ファイル・アップロード・プロセッサ

- A.6.2.13 クライアント側検証および変換

- A.6.3 システム・プロパティの構成に関する必知事項

- A.7 trinidad-skins.xmlでの構成

- A.8 RequestContext EL暗黙オブジェクトの使用

- A.9 パフォーマンス・チューニング

B コンバータおよびバリデータ・メッセージのメッセージ・キー

- B.1 ADF Facesのデフォルト・メッセージについて

- B.2 メッセージ・キーおよびセッター・メソッド

- B.3 コンバータおよびバリデータのメッセージ・キーおよびセッター・メソッド

- B.3.1 af:convertColor

- B.3.2 af:convertDateTime

- B.3.3 af:convertNumber

- B.3.4 af:validateByteLength

- B.3.5 af:validateDateRestriction

- B.3.6 af:validateDateTimeRange

- B.3.7 af:validateDoubleRange

- B.3.8 af:validateLength

- B.3.9 af:validateRegExp

C キーボード・ショートカット

- C.1 キーボード・ショートカットについて

- C.2 タブのトラバース

- C.2.1 ページでのタブのトラバース順序

- C.2.2 表でのタブのトラバース順序

- C.3 ショートカット・キー

- C.3.1 アクセラレータ・キー

- C.3.2 アクセス・キー

- C.3.3 一般的なコンポーネントのショートカット・キー

- C.3.4 ウィジェットのショートカット・キー

- C.3.5 スクリーン・リーダー・モードのショートカット・キー

- C.3.6 リッチ・テキスト・エディタ・コンポーネントのショートカット・キー

- C.3.7 表、ツリーおよびツリー表コンポーネントのショートカット・キー

- C.3.8 スクリーン・リーダー・モードにおける表、ツリーおよびツリー表コンポーネントのショートカット・キー

- C.3.9 ADFデータ視覚化コンポーネントのショートカット

- C.3.10 カレンダ・コンポーネントのショートカット・キー

- C.3.11 スクリーン・リーダー・モードでのカレンダ・コンポーネントのショートカット・キー

- C.4 デフォルトのカーソルまたはフォーカスの配置

- C.5 [Enter]キー

D ADF Facesを使用したタッチ装置のWebアプリケーションの作成

- D.1 ADF Facesを使用したタッチ装置のWebアプリケーションの作成の概要

- D.2 タッチ装置上のモバイル・ブラウザでのADF Facesの動作

- D.3 モバイル・ブラウザでADF Facesコンポーネントを使用する場合のベスト・プラクティス

E クイック・スタート・レイアウト・テーマ

F コード・サンプル

- F.1 第4章「ADF Facesのクライアント・サイド・アーキテクチャの使用」のサンプル

- F.1.1 adf-js-partitions.xmlファイル

- F.2 第23章「グラフ・コンポーネントの使用方法」のサンプル

- F.3 第30章「ツリーマップおよびサンバースト・コンポーネントの使用」のサンプル

- F.3.1 ツリーマップおよびサンバースト人口調査データ例のサンプル・コード

- F.3.2 サンバースト・マネージドBeanのサンプル・コード

- F.4 第34章「カスタムADF Facesコンポーネントの作成」のサンプル

- F.4.1 JavaScriptのイベント・コード

- F.4.2 タグ・ライブラリ・ディスクリプタ・ファイルのコード例

- F.4.3 コンポーネント・クラスのコード例

- F.4.4 レンダラ・クラスのコード例

G ADF Facesのトラブルシューティング

- G.1 ADF Facesのトラブルシューティングの概要

- G.2 ADFアプリケーションのビュー・レイヤーのトラブルシューティングの開始

- G.3 一般的な問題の解決

- G.3.1 アプリケーションで予期しない白い背景が表示される

- G.3.2 アプリケーションに予想されるイメージがない

- G.3.3 ADFスキンが適切にレンダリングしない

- G.3.4 データ視覚化コンポーネントが予想どおりに表示できない

- G.3.5 高可用性アプリケーションでNotSerializableExceptionが表示される

- G.3.6 すべてのWebブラウザで問題を再現できない

- G.3.7 アプリケーションにコンテンツがない

- G.3.8 ブラウザでADF_Faces-60098エラーが表示される

- G.3.9 ブラウザでHTTP 404または500のエラーが表示される

- G.3.10 ブラウザでページ間の移動ができない

- G.4 My Oracle Supportを使用したその他のトラブルシューティング情報

はじめに

『Oracle ADF FacesによるWebユーザー・インタフェースの開発』へようこそ。

対象読者

このドキュメントは、ADF Facesコンポーネントの豊富な機能を使用して、Webアプリケーションのビュー・レイヤーを作成する開発者を対象としています。

ドキュメントのアクセシビリティについて

オラクル社のアクセシビリティへの取組みの詳細は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

Oracleカスタマは、My Oracle Supportから電子サポートにアクセスできます。詳細は、http://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoまたはhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs (聴覚障害者向け)を参照してください。

関連ドキュメント

詳細は、次の関連ドキュメントを参照してください。

- Oracle ADFスキン・エディタによるADFスキンの作成

- Oracle Application Development Frameworkの理解

- Oracle JDeveloperによるアプリケーションの開発

- Oracle Application Development FrameworkによるFusion Webアプリケーションの開発

- Oracle ADFアプリケーションの管理

- Oracle ADFモバイル・ブラウザ・アプリケーションの開発

- Oracle ADFデスクトップ統合によるアプリケーションの開発

- Oracle ADF Faces Java APIリファレンス

- Oracle ADFデータ視覚化コンポーネントJava APIリファレンス

- Oracle ADF Faces JavaScript APIリファレンス

- Oracle ADF Facesタグ・リファレンス

- Oracle ADF Facesスキン・セレクタ・タグ・リファレンス

- Oracle ADF Facesデータ視覚化ツール・タグ・リファレンス

- Oracle ADFライフサイクルJava APIリファレンス

- Oracle ADFリソース・バンドルJava APIリファレンス

- Oracle JDeveloper 12cリリース・ノート(JDeveloper 12cインストール内およびOracle Technology Networkからアクセス)

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック体

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

このガイドで説明する新機能

次の各トピックでは、ADF Facesの新機能と変更された機能について、およびこのガイドに記載されているその他の重要な変更について紹介します。このドキュメントは、以前は『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』と呼ばれていたドキュメントの新版です。

リリース12c (12.1.2)の新機能と変更された機能

Oracle JDeveloperおよびOracle Application Development Framework (Oracle ADF)のOracle Fusion Middlewareリリース12c (12.1.2)で、新規に追加または変更された開発機能は次のとおりです。これらの機能について、このガイドで説明しています。

- 新しいSkyrosスキン。コンポーネントの実行時のイメージが、すべて新しいSkyrosスキンを反映するように置き換えられました。さらに、次の変更も加えられました。

- 23.4.1.1項「スキンを使用したグラフ・フォントの全体的な設定方法」から、blafplus-rich.desktopスキンに関する記述が削除されました。

- Faceletsのサポート。すべての章で、Faceletsに関する説明が改訂されました。

- 新しいJDeveloperウィンドウ名、コンテキスト・メニューのオプション、およびJDeveloperのユーザー・インタフェースに対するその他の変更が、このガイドのすべての章に反映されています。

- ボタン・コンポーネントとリンク・コンポーネントが、それぞれaf:buttonコンポーネントとaf:linkコンポーネントに統合されました。このガイドに記載されているすべてのサンプル・コードが、これらの新しいコンポーネントを反映するために更新されました。

- 新しいtargetタグにより、特定のイベント(1つまたは複数)がコンポーネントによって起動されたときに、どのターゲット・コンポーネントを実行およびレンダリングするかを明示的に記述できるようになりました。これにより、部分ページ・レンダリングをより詳細に制御できます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- convertTimeZoneコンバータは、inputTextおよびinputDateコンポーネントとともに2桁の年パターンが使用されている場合に、4桁の年の値を解釈できます。7.3.4項「日時コンバータに関する必知事項」を参照してください。

- 新しいpanelGridLayout、gridRowおよびgridCellコンポーネント。9.3項「グリッドでのコンテンツの配置」を参照してください。

- 新しいpanelDrawerおよびpanelSpringboardコンポーネント。9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

- 入力コンポーネント用の新しいplaceholder属性およびusage属性。

- inputTextコンポーネントの詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。

- inputColorコンポーネントの詳細は、11.5.1項「inputColorコンポーネントの追加方法」を参照してください。

- inputDateコンポーネントの詳細は、11.5.2項「inputDateコンポーネントの追加方法」を参照してください。

- inputDateコンポーネントに対して、タイム・ゾーンのカスタム・リストを構成できます。11.5.4項「カスタム・タイム・ゾーン・リストの作成に関する必知事項」を参照してください。

- inputNumberSliderおよびinputRangeSliderコンポーネントの新しいanimationInterval属性。11.4.1項「inputNumberSliderまたはinputRangeSliderコンポーネントの追加方法」を参照してください。

- selectBooleanCheckboxコンポーネントの不確定(または混合)状態のサポート。11.6項「選択コンポーネントの使用方法」を参照してください。

- inputFileコンポーネントでの複数ファイルのアップロードのサポート。11.9項「ファイルのアップロード機能の使用方法」を参照してください。

- コード編集用のウィジェットをレンダリングする新しいcodeEditorコンポーネント。11.10項「コード・エディタの使用」を参照してください。

- calendarコンポーネントの新しい属性allDayActivityOrder、hourZoomおよびtimeSlotsPerHour。17.3.1項「Calendarコンポーネントの構成方法」を参照してください。

- tableコンポーネントとtreeTableコンポーネントで、連続スクロールではなく行のページ単位で移動できるようになりました。12.2.2項「コンテンツの配信」を参照してください。

- tableコンポーネントとtreeTableコンポーネントで、列の固定を最終列から開始できるようになりました。12.3.2項「表の書式設定」を参照してください。

- tableおよびtreeTableコンポーネントで、個々の行が複数列にまたがれるようになりました。12.3.3項「列の書式設定」を参照してください。

- 新しいlistViewおよびlistItemコンポーネントにより、単純な1列の表が提供されます。12.10項「リストへのコレクションの表示」を参照してください。

- buttonおよびlinkコンポーネントの新しいselected属性。これをtrueに設定すると、コンポーネントがレンダリング時に選択済としてスタイル設定されます。これらのコンポーネントのiconPosition属性も、アイコンが指定された場合にコンポーネントがそのアイコンをどこにレンダリングするかを決定するために、追加の値(topとbottom)をサポートするようになりました。20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

- navigationPaneコンポーネントに対する変更:

- navigationPaneコンポーネントによってレンダリングされるタブのサイズを決定する機能。20.8.4項「ナビゲーション・タブのサイズに関する必知事項」を参照してください。

- コンベア・ベルトのようにタブのオーバーフローを表示します。20.8.5項「圧縮レイアウトのナビゲーション・タブに関する必知事項」を参照してください。

- 新しいdynamicComponentにより、レンダリングするコンポーネントを実行時に正確に指定できます。第21章「実行時のコンポーネントの決定」を参照してください。

- 対話型のデータ視覚化ツールである新しいtimelineコンポーネントを使用すると、ユーザーがイベントを時間順に表示して、定義された時間範囲内で時間を進めたり戻したりできます。27章「時系列コンポーネントの使用」を参照してください。22章「ADFデータ視覚化コンポーネントについて」も、この新しいコンポーネントの紹介を追加するために改訂されました。

- サイズと色で視覚的に表された、2つのディメンションにまたがる数量的な階層データを表示する、新しいtreemapおよびsunburstコンポーネント。次を参照してください。

- 第22章「ADFデータ視覚化コンポーネントの概要」

- 第30章「ツリーマップおよびサンバースト・コンポーネントの使用」

- 第33.3.3項「ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン」

- 36.8.3項「DVT階層ビューア、サンバースト、およびツリーマップにドラッグ・アンド・ドロップ機能を追加する」

- HTML5のサポート。クライアントのブラウザでHTML5がサポートされている場合、次のDVTコンポーネントについてはFlashではなくHTML5がデフォルトのイメージ形式になります。

- gauge。24.2.5項「ゲージのイメージ形式に関する必知事項」を参照してください。

- graph。23.2.6項「グラフのイメージ形式に関する必知事項」を参照してください。

- thematicMap。28.6.6項「テーマ・マップのイメージ形式に関する必知事項」を参照してください。

HTML5は、サンバースト、時系列およびツリーマップを含むすべての新しいDVTコンポーネントにとっても、デフォルトのイメージ形式です。

- graphコンポーネントの新しい属性positionHintおよびmaxWidth。23.3.4項「グラフの凡例のカスタマイズ方法」を参照してください。

- グラフでのデータ・マーカー選択のサポート。23.7.8項「グラフのデータ・マーカー選択サポートの追加」を参照してください。

- pivotTableコンポーネントの新機能:

- シングルクリックでの編集。25.1.2.3項「データ・セルの編集」を参照してください。

- 列およびヘッダー・レイヤーのソートに関するコンテキスト・メニュー・オプション。25.1.2.4項「データおよびヘッダーのソート」を参照してください。

- スクロールバーにかわる新しいページ制御と、行および列データ・セルまたはヘッダーの開始位置を設定するための属性。25.1.2.6項「スクロールおよびページ・コントロール」と25.2.6項「大規模なデータ・セットの表示について」を参照してください。

- 大規模なデータ・セットを表示する場合の永続ヘッダー・レイヤー・ラベル。25.1.2.7項「永続ヘッダー・レイヤー」を参照してください。

- 大規模データ・セット内のデータの分割表示構成。25.1.2.8項「大規模データ・セットの分割ビュー」を参照してください。

- ヘッダー・セルでの長いヘッダー・タイトルの折返し。25.1.2.10項「ヘッダー・セルの折返し」を参照してください。

- アクティブ・データ・サービス(ADS)のサポート。25.1.2.11項「ADS(アクティブ・データ・サポート)」を参照してください。

- ヘッダーおよびデータ・セルの宣言スタイル属性。25.2.4項「ピボット・テーブルの表示サイズおよびスタイルの構成」を参照してください。

- モバイル機器のサポート。25.2.7項「タッチ装置でのピボット・テーブルに関する必知事項」を参照してください。

- ピボット・フィルタ・バー。25.4.2項「Using a Pivot Filter Bar with a Graph」を参照してください。

- 印刷可能ページのサポート。25.5.4項「Displaying Pivot Tables in Printable Pages」を参照してください。

- hierarchyViewerコンポーネントでのドラッグ・アンド・ドロップのサポート。36.8.3項「DVT階層ビューア、サンバースト、およびツリーマップにドラッグ・アンド・ドロップ機能を追加する」を参照してください。

- popupコンポーネントがshowPrintablePageBehaviorタグの有効なルートになりました。37.2項「印刷用のページの表示」を参照してください。

- 編集可能なコンポーネントの値は、その値が最後のリクエスト以降に変更された場合にのみポストバックされます。A.2.3.16項「ポストバック・ペイロード・サイズの最適化」を参照してください。

- HTMLページでのADFバージョン情報の表示または非表示。A.2.3.19項「バージョン番号情報」を参照してください。

- ADF Facesキャッシング・フィルタ(ACF)によるOracle Traffic Directorのサポート。A.2.3.21項「ADF Facesキャッシング・フィルタ」を参照してください。

- 無効なブラウザの通知。A.2.3.23項「Internet Explorer互換性ビュー・モード」を参照してください。

- 警告ダイアログが表示された場合のセッション・タイムアウト。A.2.3.24項「セッション・タイムアウトの警告」を参照してください。

- URL内の動的URLパラメータの削除。A.2.3.26項「クリーンなURL」を参照してください。

- ページのロード中に表示されるスプラッシュ画面を無効にする機能。A.2.3.27項「ページのロード中スプラッシュ画面」を参照してください。

- 特定のレイアウト・コンポーネントや表がどのように拡大処理されるかをグローバルにコントロールします。A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

- コンテンツ配信ネットワーク(CDN)のサポート。付録A「コンテンツ配信ネットワークの使用」を参照してください。

- タブレットおよびモバイル機器のサポートの強化。付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

リリース12c (12.1.2)に関するこのドキュメントにおけるその他の大きな変更

リリース12c (12.1.2)に対応して、このドキュメントは修正と明確化のためにいくつかの面で更新されました。さらに、次の各項では次のような大きな変更または追加も行われました。

- 各章に、ユースケースと例に関する項が含められました。

- 各章のすべての概要の項が、「...について」というタイトルに変わりました。

- 7.4項「カスタムADF Facesコンバータの作成」を明確化のために改訂しました。

- 7.4.1項「カスタムADF Facesコンバータの作成方法」のサンプル・コードを更新しました。

- 7.5.1項「検証の追加方法」から不要になった文章を削除しました。

- 「カルーセルでのイメージの表示」の項を「出力コンポーネントの使用」の章から「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」の章に移動しました。12.11項「カルーセルでのイメージの表示」を参照してください。

- 19章「ヒント、メッセージおよびヘルプの表示」を明確化のために改訂し、不要になったコンテンツを削除しました。

- カスタマイズ可能なアプリケーションでリソース・バンドルをオーバーライドする場合にadf-config.xmlファイルで行う構成について説明するために、32章「ページの国際化およびローカライズ」を改訂しました。32.3.8項「カスタマイズ可能なアプリケーションでのリソース・バンドルのオーバーライドに関する必知事項」を参照してください。

- 22章「ADFデータ視覚化コンポーネントの概要」を改訂し、graphおよびgaugeコンポーネントの埋込みフォントに関する不要になったコンテンツを削除しました。さらに、アクティブ・データ・サービス(ADS)をサポートするDVTコンポーネントのリストを記載しました。

- 23章「グラフ・コンポーネントの使用方法」の様々な項を、次の目的のために改訂しました。

- より多くのユースケースを追加する。

- サンプル・コードおよび手順のエラーを修正する。

- グラフ・コンポーネントに含まれている既存のコンポーネントを反映する。

- 時間セレクタを作成するための手順が追加されました。23.7.3.3項「グラフへの時間セレクタの追加方法」を参照してください。

- 24章「ゲージ・コンポーネントの使用方法」の様々な項を、次の目的のために改訂しました。

- サンプル・コードおよび手順のエラーを修正する。

- ゲージ・コンポーネントに含まれている既存のコンポーネントを反映する。

- 24.4.3項「ゲージ・テキストの書式設定方法」のコンテンツを24.4.4項「ゲージのテキスト・リソースの指定方法」に移動する。

- スキニング・キーを使用して様々な機能を実現する方法を説明する。

- 24章「ゲージ・コンポーネントの使用方法」から次の項を削除しました。

- 「ゲージ・セット内のゲージのレイアウトの指定方法」

- 「ゲージ・セット表示の構成に関する必知事項」

- 33.3.3項「ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン」を改訂し、treemapおよびsunburstコンポーネントに関するガイドラインを記載しました。

- 29章「階層ビューア・コンポーネントの使用方法」の様々な項を、次の目的のために改訂しました。

- サンプル・コードおよび手順のエラーを修正する

- スキニング・キーを使用して様々な機能を実現する方法を説明する。

- 29章「階層ビューア・コンポーネントの使用方法」から、ポップアップ・メニューを起動するように階層ビューアを構成する方法に関する不要になった項を削除しました。

- グラフ・コンポーネントとガント・コンポーネントのドラッグ・アンド・ドロップ機能を36.8項「DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加」にまとめました。

- 37.3項「メール可能なページの作成」を改訂して、サポートされている電子メール・クライアントのリストを追加し、tableおよびtreeTableコンポーネントに関する情報を追加しました。

- A.2.3.11項「テストの自動化」を改訂し、テスト自動化が有効にされた後にのみアサーション失敗エラーを生成するコーディング・エラーを記載しました。

- アプリケーション・ユーザー・インタフェースのトラブルシューティングを記載するために新しい付録を追加しました。付録G「ADF Facesのトラブルシューティング」を参照してください。

第I部

ADF Facesのスタート・ガイド

第I部には、次の章が含まれています。

- 第1章「ADF Facesの概要」

- 第2章「ADF Facesのデモ・アプリケーション」

- 第3章「ADF FacesとJDeveloperの概要」

1 ADF Facesについて

この章では、ADF Facesについてを、フレームワークの機能およびライブラリ内の各コンポーネント・タイプの概要も含めて説明します。

この章では、次の項目について説明します。

- 1.1項「ADF Facesについて」

- 1.2項「ADF Facesフレームワーク」

- 1.3項「ADF Facesコンポーネント」

1.1 ADF Facesについて

ADF Facesは、150を超えるAjax対応JavaServer Faces (JSF)コンポーネントと完結したフレームワークのセットであり、これらはすべてJSF 2.0規格に基づいて構築されています。当初、ADF FacesはJSFコンポーネントの第1世代のセットであり、それ以降、Apache Software Foundationに無償提供されました。このセットはApache MyFaces Trinidadと呼ばれ(現在はApache Software Foundationから入手できます)、現在のADF Facesの基盤となっています。

ADF FacesとJSF 2.0を使用すると、JavaScriptのハード・コーディングは最小限でAjaxベースのアプリケーションを比較的簡単に実装できます。たとえば、株式アナリストがドラッグ・アンド・ドロップを使用して新しい株式シンボルを表ビューに追加し、高度なプッシュ・テクノロジを使用してサーバー・モデルで更新できる株式トレーダのダッシュボード・アプリケーションを簡単に構築できます。新しい取引を行うために、株式トレーダは実際のページを離れることなく、クライアントの新規株式の購入プロセスをナビゲートできます。この機能の大部分は、ADF Facesコンポーネントのサポートが組み込まれた機能豊富な開発環境であるOracle JDeveloperを使用して宣言的に実装できるため、Webアプリケーションの表示レイヤーを迅速かつ簡単に構築できます。

注意:

ADF Facesは標準JSFテクノロジに準拠しているため、このガイドではJSF標準に付加する点、または異なる点を主に説明しています。このため、ADF Facesを使用して開発を始める前に、JSFがどのように機能するかについて、基本的な知識を得ておく必要があります。JSFの詳細は、http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.htmlを参照してください。

1.2 ADF Facesフレームワーク

ADF Facesフレームワークは、次のような豊富な機能を提供します。

- JSF 2.0仕様への組込み
ADF Facesでは、Faceletを含むJSF 2.0がサポートされます。新しいJavaServer Faces 2.0機能のいくつかには、ADF Facesのパラレル機能があります。JSF 2.0で導入された新機能、およびADF FacesとJSF 2.0間に存在する機能の重複を理解するには、http://www.oracle.com/technetwork/developer-tools/adf/learnmore/adffaces-jsf20-190927.pdfのOTNで、ホワイトペーパー『JavaServer Faces 2.0 Overview and Adoption Roadmap in Oracle ADF Faces and Oracle JDeveloper 11g』を参照してください。

- デスクトップまたはタブレット・デバイスのブラウザで実行するように最適化された完全な機能を備えた大型のリッチ・コンポーネント。
ライブラリには、ジオメトリ管理レイアウト・コンポーネント、テキストおよび選択コンポーネント、ソート可能な階層データ表およびツリー、メニュー、ページ内ダイアログ、汎用コントロールなど、150を超えるリッチ・インターネット・アプリケーション(RIA)コンポーネントが用意されています。詳細は、第1.3項「ADF Facesコンポーネント」を参照してください。タブレットで実行するADF Facesの詳細は、付録D「ADF Facesを使用したタッチ・デバイス用のWebアプリケーションの作成」を参照してください。

- 普及したAjaxサポート
ADF Facesの多くのコンポーネントに、AJAXスタイル機能がネイティブで実装されています。たとえば、ADF Facesの表コンポーネントでは、表のスクロール、列ヘッダーのクリックによる表のソート、1つまたは複数の行の選択マークおよび表の特定の行の拡張を実行でき、すべてサーバーへのページ送信を必要とせずコーディングも不要です。ADF Facesでは、この機能は部分ページ・レンダリング(PPR)として実装されます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- 開発者がJavaScriptを記述する必要性の限定
ADF Facesは、複雑なJavaScriptの大部分をユーザーから隠します。かわりに、コンポーネントの動作は宣言的に制御します。ADF Facesを使用して、リッチで機能的、魅力的なWeb UIを、JavaScriptの使用をまったく必要としない宣言的な方法で実装できます。

たとえば、ADF Facesに独自の機能を追加する必要がある場合に、クライアント側コンポーネントとイベント・フレームワークを使用して簡単に追加できる場合があります。詳細は、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

- サーバーとクライアント両方で拡張されたライフサイクル
ADF Facesは、標準JSF 2.0ページ・リクエストのライフサイクルを拡張します。この例として、クライアント側の値のライフサイクル、複数のフォームを使用する必要なしに独立して送信可能な領域をページに作成できるサブフォーム・コンポーネント、処理用に送信されるページの部分を限定できる最適化されたライフサイクルなどがあります。詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

- イベント処理
ADF Facesは標準JSFイベント処理手法に準拠し、完全なクライアント側イベント・モデルを提供します。イベントの詳細は、第6章「イベントの処理」を参照してください。

- 部分ページ・ナビゲーション
ADF Facesアプリケーションは、ナビゲーションにPPRを使用できるため、ページ間をナビゲートする際にJavaScriptライブラリおよびスタイルシートを繰り返しロードする必要がなくなります。詳細は、8.5項「部分ページ・ナビゲーションの使用」を参照してください。

- クライアント側の検証、変換およびメッセージング
ADF Facesバリデータは、クライアント側とサーバー側の両方で動作できます。クライアント側バリデータはJavaScriptで記述され、クライアント側で捕捉された検証エラーはサーバーとの間をラウンドトリップしなくても処理できます。詳細は、第7章「入力の検証および変換」を参照してください。

- サーバー側プッシュおよびストリーミング
ADF Facesフレームワークには、ADF Facesコンポーネントのリアルタイム・データ更新を提供できるようにするサーバー側プッシュが含まれます。詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

- アクティブなジオメトリ管理
ADF Facesには、使用可能なスクリーン領域をどの程度利用できているかをコンポーネントが判断できるようにするクライアント側ジオメトリ管理機能が用意されています。フレームワークで、レイアウト・コンポーネントにブラウザのサイズ変更アクティビティが通知され、これによってコンポーネントで子のサイズ変更が可能になります。これによって、特定のコンポーネントを拡大または縮小し、ブラウザの使用可能な領域を満たすことができます。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- 高度なテンプレートおよび宣言コンポーネント
ページ・テンプレートやページ・フラグメント、複数のコンポーネントで構成され、アプリケーション全体で使用できるコンポジット・コンポーネントを作成できます。詳細は、第10章「フラグメント、ページ・テンプレート、コンポーネントの作成および再利用」を参照してください。

- 高度な視覚化コンポーネント
ADF Facesには、動的チャート、グラフ、ゲージ、および基礎となるデータをリアルタイムで表示するその他のグラフィックをレンダリングできるFlashおよびPNG対応のコンポーネントである、データ視覚化のコンポーネントが含まれます。詳細は、第V部「ADFデータ視覚化コンポーネントの使用」を参照してください。

- スキニング
ADF Facesコンポーネントのスキンを実装することで、独自のルック・アンド・フィールを作成できます。Oracleでは、スキンを宣言的に作成および変更できるスタンドアロン・スキン・エディタを用意しています。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 出力モード
通常はHTMLブラウザで表示されるページを電子メールや印刷ビューなどの別のモードで表示できるように設定可能です。詳細は、第37章「異なる出力モードの使用」を参照してください。

- 国際化
異なるロケールを使用するようJSFページまたはアプリケーションを構成し、ユーザーのブラウザの言語設定に基づいて適切な言語を表示できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- アクセシビリティ
ADF Facesコンポーネントには、スクリーン・リーダーなどの様々な障害支援技術と連動するアクセシビリティが組み込まれています。ADF Facesのアクセシビリティ監査ルールにより、アクセス可能なHTMLマークアップを使用して、アクセス可能なイメージ、表、フレーム、フォーム、エラー・メッセージおよびポップアップ・ウィンドウの作成が指示されています。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- ユーザー駆動のパーソナライズ
多くのADF Facesコンポーネントで、ユーザーは実行時にコンポーネントの表示を変更できます。デフォルトでは、これらの変更はページ・リクエストの間有効です。ただし、変更がユーザーのセッションの間永続するようアプリケーションを構成できます。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- ドラッグ・アンド・ドロップ
ADF Facesフレームワークでは、ユーザーは、1つのコンポーネントを別のコンポーネントにドラッグ・アンド・ドロップすることで、データを別の場所に移動できます。詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

- 他のOracle ADFテクノロジとの統合
ADF Facesは、ADFビジネス・コンポーネント、ADFコントローラ、ADFデータ・バインディングなどの他のOracle ADFテクノロジと組み合せて使用できます。ADF FacesをADFテクノロジ・スタックと組み合せて使用する方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

- Oracle JDeveloperとの統合された宣言的開発
JDeveloperは、ビジュアル・レイアウト・エディタ、ADF Facesコンポーネントをページにドラッグ・アンド・ドロップできる「コンポーネント」ウィンドウ、コンポーネント機能を宣言的に構成する「プロパティ」ウィンドウなどのADF Facesコンポーネントの宣言的サポートが組み込まれた機能豊富な開発環境です。JDeveloperの使用の詳細は、第3章「ADF FacesとJDeveloperの概要」を参照してください。

1.3 ADF Facesコンポーネント

ADF Facesコンポーネントは、通常次のカテゴリに分けられます。

- レイアウト・コンポーネント
レイアウト・コンポーネントはページのレイアウトを決めるコンテナとして機能し、ADF Facesレイアウト・コンポーネントには、コンテンツを表示または非表示にできたり、セクション、リストまたは空の領域を提供するインタラクティブなコンテナ・コンポーネントも含まれます。JDeveloperにはビルトインのクイックスタート・レイアウトが用意されており、希望するページの外観に基づいて宣言的にレイアウト・コンポーネントをページに追加できます。レイアウト・コンポーネントとジオメトリ管理の詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

標準のレイアウト・コンポーネントに加えて、ADF Facesは次の特殊なレイアウト・コンポーネントも提供します。

- エクスプローラ・タイプのメニューおよびツールバー・コンテナ: メニュー・バーとツールバーを作成できます。ユーザーは、メニューやツールバーを使用して、指定されたオプションのリスト(メニューの場合)またはボタン(ツールバーの場合)を選択し、アプリケーションへ変更を加えることができます。詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

- セカンダリ・ウィンドウ: ポップアップ・ウィンドウまたはダイアログにデータを表示します。ADF Facesでのダイアログ・フレームワークには、親ページとは別の新しいポップアップ・ブラウザ・ウィンドウに表示されるプロセスのためのページの作成をサポートするインフラストラクチャが用意されています。複数のダイアログで個々の制御フローを持ちます。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- コア構造コンポーネントおよびタグ: ドキュメント、フォーム、サブフォーム、リソースなどのページおよびレイアウトを作成するために必要なタグを提供します。これらのタグについては、様々な章で説明しています。

- テキストおよび選択コンポーネント
これらのコンポーネントでは、単純な出力テキストコンポーネントから選択コンポーネントなどの入力コンポーネント、さらに複雑な値リスト・コンポーネントにテキストを表示できます。

- 出力コンポーネント: テキストおよびグラフィックを表示し、ビデオや音楽クリップも再生できます。ADF Facesには、回転カルーセルにグラフィックを表示できるカルーセル・コンポーネントも含まれます。詳細は、第18章「出力コンポーネントの使用」を参照してください。

- 入力コンポーネント: ユーザーによるデータの入力と、色の選択や日付の選択などのその他の情報の入力を可能にします。ADF Facesには、ユーザーが処理するデータを選択できる簡単なリストやファイル・アップロード・コンポーネントも用意されています。入力コンポーネントの詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。

- 値リスト(LOV)コンポーネント: 特定の値の検索やお気に入りとしてマークされている値の表示などの機能を含むモデルによって駆動されるリストからのユーザーによる選択を可能にします。このLOVコンポーネントは、あるオブジェクトの属性の移入に使用されるフィールドが、実際はデータベースの外部キー関係のように他のオブジェクトのリスト内に含まれる場合に有用です。詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

- データ・ビュー
ADF Facesには、複雑なデータを表示するための様々な方法が用意されています。

- 表およびツリー・コンポーネント: 表または展開可能なツリー形式で構造化されたデータを表示します。ADF Facesの表には、列データのソート、データのフィルタリング、行の詳細コンテンツの表示/非表示などの機能があります。ツリーには、展開/縮小動作が組み込まれています。ツリー表は、表の機能をツリーのデータ階層機能と組み合せたものです。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

- データ視覚化コンポーネント: ユーザーは、複雑なデータをリアルタイムで表示および分析できます。ADFデータ視覚化コンポーネントには、グラフ、ゲージ、ピボット・テーブル、時系列、地理マップ、テーマ・マップ、ガント・チャート、階層ビューア、および行セットや階層データ(組織図など)を表示するツリーマップとサンバーストが含まれます。詳細は、第22章「ADFデータ視覚化コンポーネントについて」を参照してください。

- 問合せコンポーネント: ユーザーによるデータの問合せを可能にします。問合せコンポーネントでは、複数の検索基準、基準の動的な追加と削除、選択可能な検索演算子、すべてに一致/いずれかに一致の選択、シード済または保存済の検索、基本または拡張モードおよび検索のパーソナライズがサポートされます。詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

- 特殊表示コンポーネント: Calendarコンポーネントでは、アクティビティが日、週、月またはリスト表示に表示されます。ユーザーがアクティビティを作成、編集、削除できるポップアップ・コンポーネントを実装できます。詳細は、第17章「Calendarコンポーネントの使用方法」を参照してください。カルーセル・コンポーネントでは、イメージのコレクションをスクロールバー形式で表示できます。詳細は、12.11項「カルーセルでのイメージの表示」を参照してください。

- メッセージングとヘルプ: フレームワークでは、入力コンポーネントのツールチップ、メッセージおよびヘルプを表示する機能と、アプリケーションのグローバル・メッセージを表示する機能が提供されます。ヘルプ・フレームワークでは、アプリケーション全体で再利用できるメッセージを作成できます。Javaクラス、マネージドBean、XLIFFファイルまたは標準プロパティ・ファイルを使用してヘルプ・プロバイダを作成するか、外部HTMLベースのヘルプ・システムにリンクできます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 階層型メニュー・モデル: ADF Facesには、階層式のページをナビゲートするためのタブやブレッドクラムなどのアイテムをレンダリングするナビゲーション・コンポーネントが用意されています。フレームワークで、メタデータ・ファイルとともに使用し、各ページに適切な数の階層レベルを生成するためのすべての情報と、各レベルに属するナビゲーション・アイテムを含むXMLベースのメニュー・モデルが提供されます。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

- 汎用コントロール
汎用コントロールには、ナビゲートに使用されるコンポーネントと、イメージおよびアイコンを表示するコンポーネントが含まれます。

- ナビゲーション・コンポーネント: ユーザーのあるページから次のページへの移動を可能にします。ADF Facesナビゲーション・コンポーネントには、ボタンとリンク、および異なるメニューのレベルを介してアクセスされる、より複雑な階層型のページ・フローを作成する機能が含まれます。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

- イメージおよびアイコン・コンポーネント: アイコンのようにシンプルなイメージからビデオのように複雑なイメージまで表示できます。詳細は、第18章「出力コンポーネントの使用」を参照してください。

- 操作
コンポーネントではありませんが、これらのタグはコンポーネントと連動して、ドラッグ・アンド・ドロップ、検証、各種イベント・リスナーなどの追加機能を提供します。これらの操作タグについては、それらを使用するコンポーネントとともに説明されています。

2 ADF Facesデモ・アプリケーション

この章では、この開発者ガイドとともに使用できるADF Facesデモ・アプリケーションについて説明します。

この章には次の項が含まれます:

- 2.1項「ADF Facesデモ・アプリケーションについて」

- 2.2項「ADF Facesデモ・アプリケーションのダウンロードとインストール」

2.1 ADF Facesデモ・アプリケーションについて

ADF Facesには、コンポーネントとアーキテクチャ機能のサンプルを試したり、ソース・コードを表示できるデモ・アプリケーションが含まれています。

デモ・アプリケーションには、次のものが含まれています。

- タグ・ガイド: ADF Facesコンポーネント、バリデータ、コンバータと多様なタグのデモ、および属性値の変更のコンポーネントへの影響を確認できるプロパティ・エディタ。図2-1に、selectManyCheckboxコンポーネントのデモを示します。各デモには、関連するタグ・ドキュメントへのリンクが用意されています。

図2-1 タグのデモ

- スキニング: 様々なコンポーネントのスキニングのデモ。たとえば、スタイル・セレクタの変更がコンポーネントの表示に与える影響を確認できます。図2-2に、スタイル・セレクタの設定によって影響を受けるinputNumberSpinboxコンポーネントを示します。

図2-2 スキニングのデモ

- 機能のデモ: ADFコンポーネントの様々な使用方法を示す各種ページ。たとえば、File Explorerは、ディレクトリ構造を表示し、ディレクトリとファイルの作成、保存、移動を行えるライブ・データ・モデルを使用したアプリケーションです。このアプリケーションは、図2-3に示すように、実際に動かすことのできるアプリケーションでADF Facesのコンポーネントと機能を紹介するためのものです。

図2-3 File Explorerアプリケーション

その他のページは、レイアウト・コンポーネント、AJAXポストバック機能、ドラッグ・アンド・ドロップなどのADF Facesの主なアーキテクチャ上の機能を示します。図2-4に、AutoSubmit属性と部分ページ・レンダリングを使用するデモを示します。

図2-4 フレームワークのデモ

- ビジュアル・デザイン: コンポーネント・タイプを様々に使用して異なるUIデザインを実現するデモ。図2-5に、ツールバーの異なる外観を得る様子を示します。

図2-5 ツールバーのデザインのデモ

- Styles: インライン・スタイルとコンテンツ・スタイルの設定によってコンポーネントがいかに影響されるかのデモ。図2-6に、panelBoxコンポーネントに適用される異なるスタイルを示します。

図2-6 スタイルのデモ

- 混同されやすいコンポーネント: 同様の機能を提供するコンポーネントの比較。図2-7に、選択リストを表示する各種コンポーネントの違いを示します。

図2-7 混同されやすいコンポーネント

File Explorerは完全に機能するアプリケーションのため、このガイドの多くの項で、重要な点を説明したり、コード・サンプルを示すためにこのアプリケーションが使用されます。File Explorerアプリケーションのソースは、fileExplorerディレクトリにあります。

File Explorerアプリケーションでは、fileExplorerTemplateページ・テンプレートが使用されます。このテンプレートには、アプリケーションの基本的なルック・アンド・フィールを提供する多くのレイアウト・コンポーネントが含まれます。レイアウト・コンポーネントの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。テンプレートの使用の詳細は、第10章「フラグメント、ページ・テンプレート、コンポーネントの作成および再利用」を参照してください。

アプリケーションの左側には、図2-8に示すディレクトリ構造と結果表付きの検索フィールドの2つの領域を持つpanelAccordionコンポーネントが含まれます。

図2-8 ディレクトリ構造パネルと検索パネル

両方の領域とも、展開および縮小できます。ディレクトリ構造は、treeコンポーネントを使用して作成されています。検索領域は、入力コンポーネント、ボタンおよびtableコンポーネントを使用して作成されています。panelAccordionコンポーネントの使用の詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。入力コンポーネントの使用の詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。コマンド・ボタンの使用の詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。表とツリーの使用の詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

File Explorerアプリケーションの右側では、図2-9に示すようにタブ付きペインを使用して表、ツリー表またはリストのいずれかでディレクトリの内容を表示します。

図2-9 タブ付きパネルでのディレクトリの内容

表およびツリー表にはツールバーが組み込まれ、内容の表示方法を操作できます。表とリストでは、ファイルまたはサブディレクトリをディレクトリからドラッグし、別のディレクトリにドロップできます。すべてのタブで、ファイルを右クリックし、ポップアップ・メニューからファイルのプロパティをポップアップ・ウィンドウに表示できます。タブ付きのペインの使用の詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。表およびツリー表のツールバーの詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。ドラッグ・アンド・ドロップの有効化の詳細は、第36章「コンポーネントのドラッグ・アンド・ドロップ機能の追加」を参照してください。ポップアップ・メニューおよびポップアップ・ウィンドウの使用の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

File Explorerアプリケーションの上部には、図2-10に示すメニューとツールバーが含まれます。

図2-10 メニューとツールバー

メニュー・オプションでは、ファイルやディレクトリの作成と削除、コンテンツの表示方法の変更を行えます。「ヘルプ」メニューでは、図2-11に示す、ユーザーがダイアログにフィードバックを入力できるヘルプ・システムが開きます。

図2-11 ヘルプ・システム

ヘルプ・システムは、リッチ・テキスト・エディタを含む様々な入力コンポーネントを使用して作成された多くのフォームで構成されています。メニューの詳細は、16.2項「メニュー・バーでのメニューの使用方法」を参照してください。ヘルプ・システムの作成の詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。入力コンポーネントの詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。

File Explorerのツールバー内には、ディレクトリ構造内を移動できるコントロールと、スキンを変更してアプリケーションのルック・アンド・フィールを変更できるコントロールがあります。図2-12に、簡単なスキンを使用したFile Explorerアプリケーションを示します。

図2-12 簡単なスキンを使用したFile Explorerアプリケーション

ツールバーの詳細は、16.3項「ツールバーの使用方法」を参照してください。スキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

2.2 ADF Facesデモ・アプリケーションのダウンロードとインストール

デモ・アプリケーション(コードおよび実行)を表示するには、JDeveloperをインストールし、アプリケーションをダウンロードしてJDeveloper内で開きます。

ADF Facesデモ・アプリケーションは、Oracle Technology Network (OTN) Webサイトからダウンロードできます。
http://www.oracle.com/technetwork/developer-tools/adf/overview/index-092391.htmlに移動し、ページの「Download」セクションの「ADF Faces Rich Client Components Demo」リンクをクリックします。表示されたページでは、アプリケーションが含まれているWARファイルをダウンロードする方法の詳細、およびアプリケーションをスタンドアロン・サーバーにデプロイする方法またはJDeveloperに含まれている統合WebLogicサーバーを使用してアプリケーションを実行する方法が説明されています。

アプリケーションをインストールしない場合には、「ADF Faces Rich Client Components Hosted Demo」リンクをクリックして、OTNから直接アプリケーションを実行できます。

3 ADF FacesとJDeveloperの概要

この章では、JDeveloperを使用してADF Facesアプリケーションを宣言的に作成する方法について説明します。

この章では、次の項目について説明します。

- 3.1項「JDeveloperでの宣言的開発について」

- 3.2項「アプリケーション・ワークスペースの作成」

- 3.3項「ページ・フローの定義」

- 3.4項「ビュー・ページの作成」

- 3.5項「EL式の作成」

- 3.6項「マネージドBeanの作成と使用」

- 3.7項「ADF Faces Javadocの表示」

3.1 JDeveloperでの宣言的開発について

JDeveloper 11gをADF FacesおよびJSFと組み合せて使用すると、EL式の作成や自動コンポーネント・バインディングなどのようにページやマネージドBeanを宣言的に生成できるケースが多くなります。また、ナビゲーションや構成を制御するメタデータなどのXMLメタデータが宣言的に生成されるケースも多くなります。

大まかにとらえると、ADF Facesのビュー・プロジェクト開発プロセスは次の作業で構成されます。

- アプリケーション・ワークスペースの作成

- ページ・フローの設計

- FaceletsページまたはJavaServer Pages (JSP)のいずれかを使用したページの設計および作成

- アプリケーションのデプロイ。デプロイの詳細は、『Oracle ADFアプリケーションの管理』を参照してください。アプリケーションでADF FacesをADFモデル・レイヤー、ADFコントローラおよびADFビジネス・コンポーネントとともに使用する場合は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「Fusion Webアプリケーションのデプロイ」の章を参照してください。

開発サイクル全体を通じて継続されるタスクとしては、次のものがあります。

- マネージドBeanの作成

- EL式の作成および使用

- ADF Facesソース・コードおよびJavadocの表示

JDeveloperには、デバッグやテストの機能も含まれています。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFコンポーネントのテストとデバッグ」の章を参照してください。

3.2 アプリケーション・ワークスペースの作成

新規アプリケーションを作成する最初のステップは、名前を割り当て、ソース・ファイルを保存するディレクトリを指定することです。ビュー・レイヤーのみ含むアプリケーションを作成するか、ADF Facesプロジェクトを既存のアプリケーションに追加できます。

注意:

このドキュメントでは、使用されているビジネス・サービスやそれらのサービスへのバインドに関係なく、アプリケーションでADF Facesプロジェクトを作成する方法についてのみ説明します。ADF FacesをADFモデル・レイヤー、ADFコントローラおよびADFビジネス・コンポーネントとともに使用する方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

3.2.1 ADF Facesアプリケーション・ワークスペースの作成方法

アプリケーション・ワークスペースの作成には、「アプリケーションの作成」ウィザードを使用します。

アプリケーションを作成する手順:

1. 「アプリケーション」ウィンドウで、「新規」→「アプリケーション」をクリックします。

2. 「新規ギャラリ」で、「カスタム・アプリケーション」を選択して「OK」をクリックします。

3. 「カスタム・アプリケーションの作成」ダイアログで、選択項目の名前、ディレクトリの場所およびパッケージ接頭辞を設定し、「次へ」をクリックします。

4. 「プロジェクトの名前付け」ページで、必要に応じて、ビュー・プロジェクトの名前と場所を変更できます。「プロジェクトの機能」タブで、「ADF Faces」を「選択済」に移動します。ADF Facesに必要なライブラリとメタデータ・ファイルがプロジェクトに追加されます。「次へ」をクリックします。

5. 「Java設定の構成」ページで、作成するJavaクラスのパッケージ名、Javaソース・パスおよび出力ディレクトリを必要に応じて変更します。「終了」をクリックします。

ヒント:

ADF Facesを既存のプロジェクト(JEE Webアプリケーションのビュー・プロジェクトなど)に追加することもできます。これは次のように行います。

1. プロジェクトを右クリックして、「プロジェクト・プロパティ」を選択します。

2. 「プロジェクト・プロパティ」ダイアログで、「機能」を選択し、「追加」(緑のプラス記号)アイコンをクリックし、ADF Facesを「選択済」ペインに移動します。

3.2.2 アプリケーション・ワークスペースを作成する場合の処理

カスタム・テンプレートを使用してアプリケーション・ワークスペースを作成し、プロジェクトに対してADF Facesを選択すると、JDeveloperによって、ADF Facesアプリケーションに必要なすべてのソースおよび構成ファイルを含むプロジェクトが作成されます。また、次のライブラリがJDeveloperでプロジェクトに追加されます。

- JSF 2.1

- JSTL 1.2

- JSPランタイム

プロジェクトの作成後、名前を変更できます。図3-1に、新規ADF Facesアプリケーションのワークスペースを示します。

図3-1 ADF Facesアプリケーションの新規ワークスペース

アプリケーションの作成時に選択したオプションに基づいて、JDeveloperで構成ファイルに構成パラメータも設定されます。web.xmlファイルには、JSFアプリケーションの実行に必要な構成が含まれます(ADF Facesに固有の設定は、ADF Facesコンポーネントを使用してJSFページを作成したときに追加されます)。例3-1に、ADF Facesアプリケーションの新規作成時にJDeveloperによって生成されるweb.xmlファイルを示します。

例3-1 生成されたweb.xmlファイル

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
</web-app>

特定のADF Faces機能に必要な構成は、このガイドの別の章で説明されています。たとえば、変更永続性フレームワークを使用するために必要な構成は、第35章「JSFページでのユーザー・カスタマイズの許可」で説明されています。ADF Facesアプリケーションの構成の包括的な情報は、付録A「ADF Facesの構成」を参照してください。

3.3 ページ・フローの定義

アプリケーション・ワークスペース作成後の次のステップは、通常、UIのフローを設計することです。標準JSFアプリケーションの場合と同様に、ADF Facesアプリケーションでは、ページ・フローの定義にナビゲーション・ケースとルールが使用されます。これらの定義は、faces-config.xmlファイルに格納されます。JDeveloperには、アイコンを使用してページ・フローを宣言的に定義できるダイアグラマがあります。

図3-2に、特定の顧客のデータを表示するDisplayCustomerページと、ユーザーが顧客情報を編集できるEditCustomerページの2つのページを含む簡単なページ・フロー用に作成されたナビゲーション・ダイアグラムを示します。ページの表示からページの編集へ進むナビゲーション・ルールと、ページの編集からページの表示へ戻るナビゲーション・ルールが1つずつあります。

図3-2 JDeveloperのナビゲーション・ダイアグラム

注意:

ADFモデル・データ・バインディングおよびADFコントローラを使用する場合は、ADFタスク・フローを使用してナビゲーション・ルールを定義します。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFタスク・フローの概要」の章を参照してください。

ベスト・プラクティス:

ADF ControllerはJSFデフォルト・コントローラの拡張です。技術的にはアプリケーションでJSFコントローラとADF Controllerを使用できますが、いずれか一方のみを使用するようにしてください。

JSF 2.0の登場により、2つのページ間の単純なナビゲーションにはナビゲーション・ケースを作成する必要がなくなりました。すべての使用可能なルールを確認した後で一致するナビゲーション・ケースが見つからない場合、ナビゲーション・ハンドラはアクションの結果がビューIDに対応するかどうかを確認します。アクションの結果に一致するビューが見つかった場合は、一致するビューへの暗黙的なナビゲーションが行われます。JSFアプリケーションでのナビゲーション機能の詳細は、Sun社のWebサイト(http://download.oracle.com/javaee/index.html)の「Java EE 6 tutorial」を参照してください。

3.3.1 ページ・フローの定義方法

FaceletまたはJSPXページを使用し、ナビゲーション・ダイアグラマを使用して、ページ・フローを宣言的に作成します。ダイアグラマを使用すると、アプリケーションでナビゲーションが機能するために必要なXMLメタデータが、JDeveloperによってfaces-config.xmlファイルに作成されます。

始める前に:

ページ・フローに関する知識が役立つ場合があります。詳細は、3.3項「ページ・フローの定義」を参照してください。

ページ・フローを作成する手順:

1. 「アプリケーション」ウィンドウで、アプリケーションのfaces-config.xmlファイルをダブルクリックします。これは、デフォルトではプロジェクトのWeb Content/WEB-INFノードにあります。

2. エディタ・ウィンドウで、「ダイアグラム」タブをクリックし、ナビゲーション・ダイアグラマを開きます。

3. 「コンポーネント」ウィンドウが表示されていない場合は、メイン・メニューから「ウィンドウ」→「コンポーネント」を選択します。デフォルトでは、「コンポーネント」ウィンドウはJDeveloperの右上部に表示されます。

4. 「コンポーネント」ウィンドウで、ドロップダウン・メニューを使用して「ADFタスク・フロー」を選択します。
コンポーネントは、「ソース要素」、「コンポーネント」および「ダイアグラムの注釈」の3つのアコーディオン・パネルに含まれています。図3-3に、JSFナビゲーション・コンポーネントが表示されている「コンポーネント」ウィンドウを示します。

図3-3 JDeveloper内のコンポーネント

5. 使用するコンポーネントを選択し、ダイアグラムにドラッグします。
新たに追加されたコンポーネントを使用してJDeveloperでダイアグラムが再描画されます。

ヒント:

「概要」タブをクリックし、ナビゲーション・ルールとナビゲーション・ケースの作成を概要エディタで行うこともできます。エディタのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

また、ソース・エディタでページを直接編集することで、要素をfaces-config.xmlファイルに手動で追加できます。ソース・エディタにファイルを表示するには、「ソース」タブをクリックします。

アプリケーションのナビゲーションを定義したら、次はページを作成したり、ナビゲーションを使用するコンポーネントを追加したりできます。ページでのナビゲーション・コンポーネントの使用の詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

3.3.2 ダイアグラマを使用してページ・フローを作成する場合の処理

ページ・フローの作成にダイアグラマを使用すると、JDeveloperで関連するXMLエントリがfaces-config.xmlファイルに作成されます。例3-2に、図3-2に示すナビゲーション・ルール用に生成されたXMLを示します。

例3-2 faces-config.xmlのナビゲーション・ルール

<navigation-rule>
<from-view-id>/DisplayCustomer</from-view-id>
<navigation-case>
<from-outcome>edit</from-outcome>
<to-view-id>/EditCustomer</to-view-id>
</navigation-case>
</navigation-rule>
<navigation-rule>
<from-view-id>/EditCustomer</from-view-id>
<navigation-case>
<from-outcome>back</from-outcome>
<to-view-id>/DisplayCustomer</to-view-id>
</navigation-case>
</navigation-rule>

3.4 ビュー・ページの作成

計画段階で作成したページ・フローからページ・アイコンをダブルクリックすると、実際のJSFページ・ファイルを作成できます。FaceletページまたはJSPページの作成を選択できます。Faceletページでは、拡張子*.jsfを使用します。Faceletは、JSF中心の宣言的XMLビュー定義テクノロジであり、JSPエンジンの使用の代替方法を提供します。

ADF FacesアプリケーションのJSPページを作成する場合は、拡張子*.jspxを使用するXMLベースのJSPドキュメントを作成します。XMLベースのドキュメントの使用には、次の利点があります。

- UIコンポーネント・タグの整形式のツリーとしてのページの処理がシンプルになります。

- Javaコードとコンポーネント・タグの混在を防げます。

- ドキュメント作成やレポート監査のためのページの解析が容易になります。

ベスト・プラクティス:

Faceletの使用には、次の利点があります。

- FaceletレイヤーはJSF専用に作成されるため、タグのコンパイルと実行時にオーバーヘッドが削減され、パフォーマンスが向上します。

- Faceletは、JSF 2.0のプライマリ・ビュー定義テクノロジと考えられます。

- JSF標準に対する将来のパフォーマンス拡張の一部は、Faceletでのみ使用可能になります。

ADF Facesには、ページ全体のレイアウトを定義する際に使用可能なコンポーネントが多数用意されています。JDeveloperには、これらのコンポーネントを使用した事前定義済のクイック・スタート・レイアウトが含まれており、すばやく簡単に正しくレイアウトを構築できます。1列、2列または3列のレイアウトから選択でき、列の動作を指定できます。たとえば、1つの列の幅はロックし、他の列は拡大してブラウザの使用可能な領域を埋めることができます。図3-4に、2番目の列が2つのペインに分割されている2列レイアウトで使用可能なクイック・スタート・レイアウトを示します。レイアウト・コンポーネントの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

図3-4 クイック・レイアウト

ベスト・プラクティス:

すべてのブラウザで正しく動作するレイアウトの作成には時間がかかる場合があります。事前定義されたクイック・レイアウトを使用して、潜在的な問題を回避します。

レイアウト・コンポーネントの追加とともに、選択したクイック・レイアウトにテーマを適用することも選択できます。これらのテーマは、クイック・スタート・レイアウトで使用されるコンポーネントの一部に色のスタイルを追加します。色およびその追加場所を確認するには、付録D「クイック・スタート・レイアウトのテーマ」を参照してください。テーマの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

同じレイアウトをアプリケーションの多くのページで使用する場合には、ADF Facesでは事前定義済ページ・テンプレートを作成および使用できます。テンプレートを作成する場合、テンプレートの開発者はテンプレートを使用するページのレイアウトを決定するだけではなく、すべてのページに表示される静的コンテンツを含めたり、各ページで有効な値に置き換えられるプレースホルダ属性を作成できます。

たとえば、ADF FacesにはOracle Three-Column-Layoutテンプレートが含まれています。このテンプレートには、図3-5に示すように、ブランド、ヘッダー、著作権情報などの特定のコンテンツ用の領域が含まれ、静的ロゴおよびビジー・アイコンも表示されます。

図3-5 Oracle3列レイアウト・テンプレート

テンプレートにレイアウトなどの変更を加えるたびに、テンプレートを使用するページも自動的に更新されます。テンプレートの作成と使用の詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

ベスト・プラクティス:

テンプレートを使用して、一貫性を実現し、将来的にアプリケーションの複数のページを簡単に更新できるようにします。

JSFページを作成する際、ページに関連するバッキングBeanを作成することも選択できます。バッキングBeanを使用すると、ページ上のコンポーネントにプログラムからアクセスできます。JSFページでのバッキングBeanの詳細は、3.4.4項「自動コンポーネント・バインディングに関する必知事項」を参照してください。

ベスト・プラクティス:

プログラムからのアクセスや処理が必要なコンポーネントを含むページについてのみバッキングBeanを作成します。リスナーなど、コンポーネント属性のEL式を使用してアクセスする追加機能を提供することのみ必要な場合は、かわりにマネージドBeanを使用します。

ページ・ファイルを作成した後は、そのファイルにUIコンポーネントを追加したり、そのページのソースを操作することができます。

3.4.1 JSFページの作成方法

「JSFページの作成」ダイアログを使用して、JSFページ(FaceletまたはJSP)を作成します。

始める前に:

ページの作成時には様々なオプションに関する知識が役立つ場合があります。詳細は、3.4項「ビュー・ページの作成」を参照してください。

JSFページを作成する手順:

1. 「アプリケーション」ウィンドウで、ページを保存するノード(ディレクトリ)を右クリックし、「新規」→「ページ」を選択します。
または

ナビゲーション・ダイアグラムから、まだ作成されていないページのページ・アイコンをダブルクリックします。

2. 「JSFページの作成」ダイアログに従って操作を進めます。ヘルプを参照するには、ダイアログで「ヘルプ」をクリックします。バッキングBeanおよび関連するバインディングの自動作成に使用できる「マネージドBean」ページの詳細は、3.4.4項「自動コンポーネント・バインディングに関する必知事項」を参照してください。

注意:

Faceletページでは任意の拡張子を使用できますが、Faceletページをカスタマイズ可能にするには.jsf拡張子を使用する必要があります。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

3.4.2 JSFページの作成時に発生する処理

「JSFページの作成」ダイアログを使用してJSFページを作成すると、JDeveloperによって物理ファイルが作成され、必要なコードがファイル内に追加されます(コンポーネント・ライブラリをインポートし、ページを表示するためのコード)。作成されるコードは、FaceletまたはJSPページを作成するよう選択したかどうかによって異なります。

例3-3に、JDeveloperで最初に作成されたときのFaceletページを示します。

例3-3 JDeveloperで作成された宣言的Faceletページ・ソース

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html>
<f:view xmlns:f="http://java.sun.com/jsf/core" xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:document title="DisplayCustomer.jsf" id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>

例3-4に、JDeveloperで最初に作成されたときの.jspxページを示します。

例3-4 JDeveloperで作成された宣言的JSPXページ・ソース

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1" xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document title="EditCustomer" id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>
</jsp:root>

クイック・レイアウトの1つを使用することを選択した場合、JDeveloperにより、レイアウトの表示に必要なコンポーネントも追加されます。例3-5に、2列のレイアウトを選択した場合に生成されるコードを示します(このレイアウトでは、最初の列はロックされ、2番目の列は使用可能なブラウザ領域全体に拡大され、テーマの適用を選択することもできます)。

図3-5 2列レイアウト

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1" xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document title="EditCustomer" id="d1">
<af:form id="f1">
<af:panelGridLayout id="pgl1">
<af:gridRow height="100%" id="gr1">
<af:gridCell width="100px" halign="stretch"
valign="stretch" id="gc1">
<!-- Left -->
</af:gridCell>
<af:gridCell width="100%" halign="stretch"
valign="stretch" id="gc2">
<af:decorativeBox theme="dark" id="db2">
<f:facet name="center">
<af:decorativeBox theme="medium" id="db1">
<f:facet name="center">
<!-- Content -->
</f:facet>
</af:decorativeBox>
</f:facet>
</af:decorativeBox>
</af:gridCell>
</af:gridRow>
</af:panelGridLayout>
</af:form>
</af:document>
</f:view>
</jsp:root>

ダイアログの「マネージドBean」タブを使用してバッキングBeanを自動作成するよう選択した場合は、そのページ用のバッキングBeanも作成および登録され、既存のコンポーネントがそのBeanにバインドされます。例3-6に、ページのバッキングBean用に作成されたコードを示します。

例3-6 JDeveloperで作成された宣言バッキングBeanのソース

package view.backing;

import oracle.adf.view.rich.component.rich.RichDocument;
import oracle.adf.view.rich.component.rich.RichForm;

public class MyFile {
private RichForm f1;
private RichDocument d1;

public void setF1(RichForm f1) {
this.f1 = f1;
}

public RichForm getF1() {
return f1;
}

public void setD1(RichDocument d1) {
this.document1 = d1;
}

public RichDocument getD1() {
return d1;
}
}

ヒント:

バッキングBeanのソースはJSFページからアクセスできます。エディタでページを右クリックして「移動先」を選択し、リストからBeanを選択します。

また、次のライブラリがJDeveloperでビュー・プロジェクトに追加されます。

- ADF Facesランタイム11

- ADF Commonランタイム

- ADF DVT Facesランタイム

- ADF DVT Facesデータバインディング・ランタイム

- ADF DVT FacesデータバインディングMDSランタイム

- Oracle JEWT

JDeveloperは、web.xmlファイルにエントリも追加します。例3-7に、JSFページの作成後に作成されるweb.xmlファイルを示します。

例3-7 JSFページの作成後のweb.xmlファイルのコード

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>resources</servlet-name>
<servlet-class>
org.apache.myfaces.trinidad.webapp.ResourceServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>BIGRAPHSERVLET</servlet-name>
<servlet-class>oracle.adf.view.faces.bi.webapp.GraphServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>BIGAUGESERVLET</servlet-name>
<servlet-class>oracle.adf.view.faces.bi.webapp.GaugeServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>MapProxyServlet</servlet-name>
<servlet-class>oracle.adf.view.faces.bi.webapp.MapProxyServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/adf/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/afr/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>BIGRAPHSERVLET</servlet-name>
<url-pattern>/servlet/GraphServlet/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>BIGAUGESERVLET</servlet-name>
<url-pattern>/servlet/GaugeServlet/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>MapProxyServlet</servlet-name>
<url-pattern>/mapproxy/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>resources</servlet-name>
<url-pattern>/bi/*</url-pattern>
</servlet-mapping>
<context-param>
<param-name>javax.faces.FACELETS_VIEW_MAPPINGS</param-name>
<param-value>*.jsf;*.xhtml</param-value>
</context-param>
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>javax.faces.PARTIAL_STATE_SAVING</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>If this parameter is true, there will be an automatic check of the modification date of your JSPs, and saved state will be discarded when JSP's change. It will also automatically check if your skinning css files have changed without you having to restart the server. This makes development easier, but adds overhead. For this reason this parameter should be set to false when your application is deployed.</description>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>Whether the 'Generated by...' comment at the bottom of ADF Faces HTML pages should contain version number information.</description>
<param-name>oracle.adf.view.rich.versionString.HIDDEN</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>Security precaution to prevent clickjacking: bust frames if the ancestor window domain(protocol, host, and port) and the frame domain are different. Another options for this parameter are always and never.</description>
<param-name>org.apache.myfaces.trinidad.security.FRAME_BUSTING</param-name>
<param-value>differentOrigin</param-value>
</context-param>
<context-param>
<param-name>javax.faces.VALIDATE_EMPTY_FIELDS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS</param-name>
<param-value>auto</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_SKIP_XML_INSTRUCTIONS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_DECORATORS</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator
</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_RESOURCE_RESOLVER</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver
</param-value>
</context-param>
<context-param>
<param-name>oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT</param-name>
<param-value>HTML5</param-value>
</context-param>
<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
<dispatcher>ERROR</dispatcher>
</filter-mapping>
<mime-mapping>
<extension>swf</extension>
<mime-type>application/x-shockwave-flash</mime-type>
</mime-mapping>
<mime-mapping>
<extension>amf</extension>
<mime-type>application/x-amf</mime-type>
</mime-mapping>
</web-app>

注意:

Faceletsコンテキスト・パラメータは、Faceletsページを作成した場合にのみ作成されます。

JSFページを作成すると、例3-8のようなADF Facesのデフォルト・レンダー・キット(HTMLクライアントでのコンポーネントの表示に使用)を定義するエントリがJDeveloperによってfaces-config.xmlファイルに作成されます。

例3-8 生成されたfaces-config.xmlファイル

<?xml version="1.0" encoding="windows-1252"?>
<faces-config version="2.1" xmlns="http://java.sun.com/xml/ns/javaee">
<application>
<default-render-kit-id>oracle.adf.rich</default-render-kit-id>
</application>
</faces-config>

例3-9のようなtrinidad-config.xmlファイルのエントリによって、アプリケーションのユーザー・インタフェース(UI)コンポーネントで使用されるデフォルト・スキンが定義されます。

例3-9 生成されたtrinidad-config.xmlファイル

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>skyros</skin-family>
<skin-version>v1</skin-version>
</trinidad-config>

ページがJDeveloperに初めて表示される場合、ビジュアル・エディタ(「設計」タブをクリックしてアクセス)に表示され、WYSIWYG環境でページを見ることができます。「ソース」タブをクリックして、ページのソースをソース・エディタに表示することもできます。JDeveloperの左下部にある構造ウィンドウには、ページが階層形式で表示されます。

3.4.3 Faceletsエンジンを使用するためのアプリケーションの更新に関する必知事項

JSF 2.1 Webアプリケーションは、FaceletsエンジンまたはJSPサーブレット・エンジンを使用して実行できます。デフォルトでは、*.jsfおよび*.xhtml拡張子を持つドキュメントはFaceletsエンジンによって処理され、*.jspおよび*.jspx拡張子を持つドキュメントはJSPエンジンによって処理されます。ただし、この動作はweb.xmlファイルでjavax.faces.FACELETS_VIEW_MAPPINGSコンテキスト・パラメータを設定することで変更できます。ADF FacesではJSPページをFaceletsエンジンで実行できるため、JSPページの既存のアプリケーションでFaceletsエンジンを使用することを決定できます。そのためには、例3-10に示すコードをweb.xmlページに挿入します。

例3-10 Faceletsエンジンを使用してJSPページとFaceletページの両方を実行するためのweb.xmlコード

<context-param>
<param-name>javax.faces.FACELETS_VIEW_MAPPINGS</param-name>
<!-- Map both *.jspx and *.jsf to the Facelets engine -->
<param-value>*.jsf; *.jspx</param-value>
</context-param>

<context-param>
<param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
<param-value>true</param-value>
</context-param>

<context-param>
<param-name>javax.faces.FACELETS_DECORATORS</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator
</param-value>
</context-param>

<context-param>
<param-name>
javax.faces.FACELETS_RESOURCE_RESOLVER
</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver
</param-value>
</context-param>

その後、ADF Facesライブラリを再デプロイする必要があります。

Faceletsエンジンを使用するようにアプリケーションを変更した場合は、アプリケーションで、ADF Facesとは現在互換性のないJSFの部分状態保存が使用されます。例3-11に示すエントリを明示的に追加する必要があります。

この非互換性が解決されたら、エントリを削除して部分状態保存を再び有効にする必要があります。部分状態保存サポートの最新情報は、http://www.oracle.com/technetwork/developer-tools/jdev/documentation/index.htmlにある最新のリリース・ノートを確認してください。

例3-11 Faceletsエンジンを使用する場合に追加するweb.xmlコード

<context-param>
<param-name>javax.faces.PARTIAL_STATE_SAVING</param-name>
<param-value>false</param-value>
</context-param>

注意:

サーブレット・エンジンからFaceletsエンジンに切り替える場合は、アプリケーションの特定の部分が予想どおりに機能しないことがあります。たとえば、カスタムJSPタグがある場合、これらのタグをFaceletsエンジンで機能させるには、再実装する必要があります。詳細は、ADF Facesのリリース・ノートを参照してください。

3.4.4 自動コンポーネント・バインディングに関する必知事項

バッキングBeanは、JSFページのUIコンポーネントのロジックとプロパティを含むマネージドBeanです(マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください)。JSFページを作成する際、「JSFページの作成」ダイアログの「ページの実装」オプションの選択肢の1つを選択してUIコンポーネントを自動的に公開するよう選択すると、JDeveloperでページのバッキングBeanが自動的に作成(または、選択したマネージドBeanが使用)されます。ページに追加するコンポーネントごとに、JDeveloperでそのコンポーネントのBeanプロパティが挿入され、binding属性を使用してコンポーネント・インスタンスとそのプロパティがバインドされて、Beanでコンポーネント・インスタンスを受け入れたり、返すことができます。

自動コンポーネント・バインディングを使用すると、具体的にはJDeveloperで次の処理が行われます。

- JSFファイルと同じ名前を使用してJavaBeanを作成し、view.backingパッケージに含めます(JDeveloperでバッキングBeanを作成するよう選択した場合)。

- バッキングBeanに対するfaces-config.xmlファイルに、マネージドBeanが作成されます。デフォルトでは、マネージドBeanの名前はbacking_<page_name>で、Beanはrequestスコープを使用します(スコープの詳細は、5.6項「オブジェクト・スコープ・ライフサイクル」を参照してください)。

注意:

JDeveloperでは、マネージドBeanのプロパティ・エントリはfaces-config.xmlファイルに作成されません。特定のプロパティ値でBeanをインスタンス化する場合、この構成をfaces-config.xmlファイルに手動で行う必要があります。詳細は、A.3.1項「faces-config.xmlでのADF Facesの構成方法」を参照してください。

- 新規に作成したBeanまたは選択したBeanでは、JSFページに配置した各コンポーネント・タグに対するプロパティおよびアクセッサ・メソッドが追加されます。JDeveloperでバインディング属性の値としてEL式を使用し、コンポーネント・タグとそのプロパティがバインドされます。

- ページから削除されたコンポーネントのプロパティとメソッドが削除されます。

ページが作成され、コンポーネントが追加された後、ビジュアル・エディタでコンポーネントをダブルクリックして、使用するコンポーネントにメソッド・バインディング式を宣言的に追加できます(これにより、属性をバインドするマネージドBeanおよびメソッドを選択できるエディタが起動します)。ページに自動コンポーネント・バインディングが使用されている場合、コンポーネントをダブルクリックすると、コンポーネントがバインドされる可能性のあるスケルトン・メソッドが、ページのバッキングBeanに自動的に作成されます。たとえば、ボタン・コンポーネントを追加し、ビジュアル・エディタでこれをダブルクリックすると、「バインドActionプロパティ」ダイアログにページのバッキングBeanと新しいスケルトン・アクション・メソッドが、図3-6に示すように表示されます。

図3-6 「バインドActionプロパティ」ダイアログ

これらのメソッドから選択するか、新しいメソッド名を入力すると、JDeveloperでページのバッキングBeanに新規スケルトン・メソッドが自動的に作成されます。その後、メソッドにロジックを追加する必要があります。

注意:

自動コンポーネント・バインディングがページで使用されていない場合は、既存のマネージドBeanを選択するか、新規バッキングBeanを作成してバインディングを作成する必要があります。

たとえば、myfile.jsfというファイル名でJSFページを作成したとします。JDeveloperによるデフォルトのバッキングBeanの自動作成を選択した場合は、JDeveloperによって、view.backing.MyFile.javaというバッキングBeanが作成され、ViewControllerプロジェクトの¥srcディレクトリに配置されます。このバッキングBeanはfaces-config.xmlファイルでマネージドBeanとして構成され、デフォルトのマネージドBean名はbacking_myfileとなります。

例3-12に、自動コンポーネント・バインディングを使用し、form、inputTextおよびbuttonコンポーネントを含むJSFページのコードを示します。

例3-12 自動コンポーネント・バインディングを使用するJSFページのコード

<f:view>
<af:document id="d1" binding="#{backing_myfile.d1}">
<af:form id="f1" binding="#{backing_myfile.f1}">
<af:inputText label="Label 1" binding="#{backing_MyFile.it1}"
id="inputText1"/>
<af:button text="button 1"
binding="#{backing_MyFile.b1}"
id="b1"/>
</af:form>
</af:document>
</f:view>

例3-13に、対応するバッキングBeanのコードを示します。

例3-13 自動コンポーネント・バインディングを使用するバッキングBeanのコード

package view.backing;

import oracle.adf.view.rich.component.rich.RichDocument;
import oracle.adf.view.rich.component.rich.RichForm;
import oracle.adf.view.rich.component.rich.input.RichInputText;
import oracle.adf.view.rich.component.rich.nav.RichButton;

public class MyFile {
private RichForm f1;
private RichDocument d1;
private RichInputText it1;
private RichButton b1;

public void setForm1(RichForm f1) {
this.form1 = f1;
}

public RichForm getF1() {
return f1;
}

public void setD1(RichDocument d1) {
this.d1 = d1;
}

public RichDocument getD1() {
return d1;
}

public void setIt1(RichInputText it1) {
this.inputText1 = inputText1;
}

public RichInputText getInputText1() {
return inputText1;
}

public void setB1(RichButton b1) {
this.button1 = button1;
}

public RichButton getB1() {
return b1;
}

public String b1_action() {
// Add event code here...
return null;
}
}

例3-14に、ページのバッキングBeanをマネージドBeanとして登録するようfaces-config.xmlファイルに追加されたコードを示します。

例3-14 バッキングBeanの登録

<managed-bean>
<managed-bean-name>backing_MyFile</managed-bean-name>
<managed-bean-class>view.backing.MyFile</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
</managed-bean>

注意:

マネージドBeanをfaces-config.xmlファイルに登録するかわりに、Faceletを使用している場合は、登録するバッキングBeanで注釈を使用することを選択できます。マネージドBeanおよびバッキングBeanでの注釈の使用の詳細は、http://www.oracle.com/technetwork/java/index.htmlにある「Java EE 6 tutorial」を参照してください。

また、JSFページのバッキングBeanであるJavaファイルを編集する際、メソッド・バインディング・ツールバーがソース・エディタに表示され、選択したページのコンポーネントに適切なメソッドを迅速かつ容易にバインドできます。イベントを選択すると、JDeveloperで図3-7に示すようなイベントのスケルトン・メソッドが作成されます。

図3-7 ソース・エディタでのスケルトン・メソッドの宣言的作成

ページの作成後に、自動コンポーネント・バインディングをオンまたはオフにでき、バッキングBeanを別のJavaクラスに変更することもできます。ビジュアル・エディタでJSFページを開き、「JDeveloper」メニューから「設計」→「ページ・プロパティ」を選択します。ここで、「自動バインド」オプションを選択または選択解除したり、マネージドBeanクラスを変更したりできます。ダイアログの使用の詳細が必要な場合は、「ヘルプ」をクリックします。

注意:

自動バインディングを無効にした場合、ページでバインドされている既存のコンポーネントのバインド属性は変わりません。自動バインディングを有効にした場合、バインドされているすべての既存のコンポーネントと新たに挿入するコンポーネントが、選択したバッキングBeanにバインドされます。自動バインディングが有効で、Beanの選択を変えた場合、既存のすべてのバインディングと新規バインディングが新しいBeanに切り替わります。

JSFページのバッキングBeanにはページ・エディタからアクセスできます。ページを右クリックして「Beanに移動」を選択し、JSFに関連付けられているBeanのリストからBeanを選択します。

3.4.5 ADF FacesコンポーネントのJSFページへの追加方法

ページの作成後、「コンポーネント」ウィンドウを使用して、コンポーネントをページにドラッグ・アンド・ドロップできます。コンポーネントを追加すると、必要なページ・コードが宣言的に自動追加され、各コンポーネント属性に既定の値が設定されます。

ヒント:

特定のADF Facesコンポーネントの追加および使用の詳細な手順と情報は、第IV部「一般的なADF Facesコンポーネントの使用」を参照してください。

注意:

ADF FacesコンポーネントをMyFaces Trinidadコンポーネント(tr:タグ)またはその他のAjax対応ライブラリ・コンポーネントと同じページで使用することはできません。Trinidad HTMLタグ(trh:)はADF Facesコンポーネントと同じページで使用できますが、ブラウザ・レイアウトに問題が生じる場合があります。常にADF Facesコンポーネントのみを使用してレイアウトを実現するように試みてください。

ADF Facesコンポーネントを使用して作成したページと他のコンポーネントを使用して作成したページはアプリケーションに混在できることに注意してください。

始める前に:

ページの作成について理解しておくと役立ちます。詳細は、3.4項「ビュー・ページの作成」を参照してください。

ADF Facesコンポーネントをページに追加する手順:

1. 「アプリケーション」ウィンドウで、JSFページをダブルクリックして開きます。

2. 「コンポーネント」ウィンドウが表示されていない場合は、メニューから「ウィンドウ」→「コンポーネント」を選択します。デフォルトでは、「コンポーネント」ウィンドウはJDeveloperの右上部に表示されます。

3. 「コンポーネント」ウィンドウで、ドロップダウン・メニューを使用して「ADF Faces」を選択します。

ヒント:

「コンポーネント」ウィンドウで「ADF Faces」ページが使用可能でない場合は、ADF Facesタグ・ライブラリをプロジェクトに追加する必要があります。

Faceletファイルの場合:

1. プロジェクト・ノードを右クリックして、「プロジェクト・プロパティ」を選択します。

2. 「JSPタグ・ライブラリ」を選択して、ADF Facesライブラリをプロジェクトに追加します。ヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

JSPXファイルの場合:

1. 「コンポーネント」ウィンドウの中を右クリックし、「タグ・ライブラリの編集」を選択します。

2. 「コンポーネント・ウィンドウのカスタマイズ」ダイアログで、「ADF Facesコンポーネント」を「選択済のライブラリ」に移動し、「OK」をクリックします。

コンポーネントは、「一般コントロール」(ボタン、アイコン、メニューなどのコンポーネントを含みます)、「テキストおよび選択」、「データ・ビュー」(表やツリーなどのコンポーネントを含みます)、「メニューおよびツールバー」、「レイアウト」および「操作」の6つのアコーディオン・パネルに含まれます。

図3-8に、ADF Facesの一般コントロールを表示している「コンポーネント」ウィンドウを示します。

図3-8 JDeveloperの「コンポーネント」ウィンドウ

4. 使用するコンポーネントを選択し、ページにドラッグします。
新たに追加されたコンポーネントを使用して、JDeveloperでビジュアル・エディタのページが再描画されます。ビジュアル・エディタでは、ページのコンポーネントを直接選択し、ポップアップ・メニューを使用してコンポーネントを追加できます。

ヒント:

「コンポーネント」ウィンドウからコンポーネントをドラッグし、構造ウィンドウにドロップしたり、ソース・エディタ内のコードに直接ドロップすることもできます。

ソース・エディタでページを直接編集することで、いつでもコンポーネントを追加できます。ソース・エディタにページを表示するには、ウィンドウの下部にある「ソース」をクリックします。

3.4.6 コンポーネントをページへ追加する場合の処理

コンポーネントを「コンポーネント」ウィンドウからJSFページにドラッグ・アンド・ドロップすると、対応するコードがJSFページに自動的に追加されます。このコードには、コンポーネントのレンダリングに必要なタグと一部のコンポーネント属性の値が含まれます。例3-15に、入力テキスト・コンポーネントとボタン・コンポーネントをパレットからドロップした場合のコードを示します。

例3-15 JDeveloperでJSFページに宣言的に追加されるタグ

<af:inputText label="Label 1" id="it1"/>
<af:button text="button 1" id="b1"/>

注意:

自動コンポーネント・バインディングを使用するよう選択した場合、ページのバッキングBeanの対応するプロパティに値がバインドされたbinding属性もJDeveloperによって追加されます。詳細は、3.4.4項「自動コンポーネント・バインディングに関する必知事項」を参照してください。

必須である子コンポーネントを含むコンポーネント(表、リストなど)をドロップすると、JDeveloperでウィザードが起動され、親と各子コンポーネントを定義できます。図3-9に、表コンポーネントと表の子である列コンポーネントの作成に使用する「表」ウィザードを示します。

図3-9 JDeveloperの表ウィザード

例3-16に、ウィザードを使用して3つの列を持つ表を作成した場合に作成されるコードを示します。各列はデータの表示にoutputTextを使用します。

例3-16 表コンポーネントの宣言コード

<af:table var="row" rowBandingInterval="0" id="t1">
<af:column sortable="false" headerText="col1" id="c1">
<af:outputText value="#{row.col1}" id="ot1"/>
</af:column>
<af:column sortable="false" headerText="col2" id="c2">
<af:outputText value="#{row.col2}" id="ot2"/>
</af:column>
<af:column sortable="false" headerText="col3" id="c3">
<af:outputText value="#{row.col3}" id="ot3"/>
</af:column>
</af:table>

3.4.7 コンポーネント属性の設定方法

コンポーネントのページへのドロップ後、「プロパティ」ウィンドウ(デフォルトではJDeveloperの右下部に表示)を使用して、各コンポーネントの属性値を設定できます。

ヒント:

「プロパティ」ウィンドウが表示されていない場合は、メイン・メニューから「ウィンドウ」→「プロパティ」を選択します。

図3-10に、inputTextコンポーネントの属性が表示されている「プロパティ」ウィンドウを示します。

図3-10 JDeveloperの「プロパティ」ウィンドウ

「プロパティ」ウィンドウには、類似のプロパティをグループにした各セクションがあります。たとえば、「プロパティ」ウィンドウでは、inputTextによく使用される属性は「共通」セクションにまとめられ、コンポーネントの動作に影響するプロパティは「動作」セクションにまとめられています。図3-11に、inputTextコンポーネントの「プロパティ」ウィンドウにある「動作」セクションを示します。

図3-11 「プロパティ」ウィンドウの「動作」セクション

始める前に:

ページの作成時には様々なオプションに関する知識が役立つ場合があります。詳細は、3.4項「ビュー・ページの作成」を参照してください。

コンポーネント属性の設定手順:

1. ビジュアル・エディタまたは「構造」ウィンドウ、あるいはソース・エディタでのタグの直接選択で、コンポーネントを選択します。

2. 「プロパティ」ウィンドウで、設定する属性が含まれているセクションを開きます。

ヒント:

一部の属性は、複数のセクションに表示されます。あるセクションで値を入力または変更すると、他のセクションでもその値が変更されます。インスペクタの最上部の検索フィールドに属性名を入力して、属性を検索できます。

3. フィールドに値を直接入力するか、フィールドにドロップダウン・リストがある場合はそのリストを使用して、値を選択します。フィールドの右にあるドロップダウンを使用して、値の設定に使用できるツールを含むポップアップを起動することもできます。これらのツールは、特定のプロパティ・エディタ(「編集」を選択して開く)または値のEL式の作成に使用できる式ビルダー(「式ビルダー」を選択して開く)です。式ビルダーの使用の詳細は、3.5項「EL式の作成」を参照してください。このポップアップには、図3-12に示すようにプロパティの説明も表示されます。

図3-12 プロパティ・ツールとヘルプ

3.4.8 「プロパティ」ウィンドウを使用したときに行われる処理

「プロパティ」ウィンドウを使用して属性値を設定または変更すると、入力された値に合致するように、属性のページ・ソースがJDeveloperで自動的に変更されます。

ヒント:

ソース・エディタでページを直接編集することで、いつでも属性値を変更できます。ソース・エディタにページを表示するには、ウィンドウの下部にある「ソース」をクリックします。

3.5 EL式の作成

EL式は、属性と実行時に決まるオブジェクト値とのバインドに、ADF Facesアプリケーション全体で使用されます。たとえば、#{UserList.selectedUsers}は選択したユーザーのセットを参照でき、#{user.name}は特定のユーザー名を参照でき、#{user.role == 'manager'}はユーザーがマネージャかどうかを判断します。実行時、汎用式エバリュエータによって、これらの式に対してそれぞれList、Stringおよびbooleanの値が返され、コードなしで自動的に各オブジェクトとそのプロパティにアクセスします。

実行時、特定のJSF UIコンポーネント(inputTextコンポーネント、outputTextコンポーネントなど)の値は、そのvalue属性によって決まります。コンポーネントにはその値として静的テキストを割り当てることができますが、通常、value属性には、表示データを決定するために実行時インフラストラクチャにより評価されるEL式が含まれます。たとえば、現在ログイン中のユーザーの名前を表示するoutputTextコンポーネントには、value属性に#{UserInfo.name}という式を設定できます。コンポーネントの任意の属性(value属性だけでなく)にEL式を使用して値を割り当てることができるため、動的、かつデータ駆動型のユーザー・インタフェースの作成が容易になります。たとえば、UIコンポーネントのrendered属性に#{not empty UserList.selectedUsers}などのブール値の式を使用すると、表示するオブジェクト・セットが空のときにはそのコンポーネントを非表示にできます。UserListというオブジェクトの選択ユーザーのリストが空の場合、rendered属性はfalseと評価されるため、コンポーネントはページに表示されません。

通常のJSFアプリケーションでは、UserListのようなオブジェクトはマネージドBeanとして作成します。JSFランタイムでは、EL式でBeanを最初に参照した際に、Beanのオンデマンドのインスタンス化が管理されます。値を表示する場合、ページを表示する際にランタイムでEL式が評価され、マネージドBeanから値を得て、コンポーネントにデータが移入されます。ユーザーがUIコンポーネントのデータを更新すると、同じEL式に基づいて、JSFランタイムで該当するマネージドBeanに値が戻されます。マネージドBeanの作成と使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。EL式の詳細は、http://www.oracle.com/technetwork/java/index.htmlの「Java EE 6 tutorial」を参照してください。

注意:

EL式を編集可能コンポーネントのvalue属性に使用している場合は、そのコンポーネントに対応する設定メソッドが必要です。そうでないと、EL式は読取り専用と評価され、値の更新は許可されません。

たとえば、ページにinputTextコンポーネント(IDはit1)があり、その値が#{myBean.inputValue}に設定されているとします。inputText値を更新するには、myBeanマネージドBeanに次のような取得および設定メソッドが必要です。

public void setIt1(RichInputText it1) {
this.it1 = it1;
}

public RichInputText getIt1() {
return it1;
}

標準のEL到達可能オブジェクトおよびオペランドとともに、ADF FacesはEL関数タグを提供します。これらは、EL式で使用できる特定の機能を提供するタグです。書式タグを使用して文字列メッセージにパラメータを追加でき、タイム・ゾーン・タグを使用して、タイム・ゾーンを返すことができます。書式タグの詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。タイム・ゾーン・タグの詳細は、11.5.3項「inputDateコンポーネントなしでのタイム・ゾーンの選択に関する必知事項」を参照してください。

3.5.1 EL式の作成方法

JDeveloperの式ビルダーを使用してEL式を宣言的に作成できます。「プロパティ」ウィンドウからビルダーにアクセスできます。

始める前に

EL式に関する知識が役立つ場合があります。詳細は、3.5項「EL式の作成」を参照してください。

式ビルダーの使用手順:

1. 「プロパティ」ウィンドウで、変更する属性を見つけて、右端のドロップダウン・メニューを使用して「式ビルダー」を選択します。

2. 次の機能を使用して式を作成します。

- 「変数」ドロップダウンを使用して、式に含める項目を選択します。これらの項目は、階層形式のバインディング・オブジェクトであるツリーに表示されます。ツリーの各アイコンは、式で使用できる各種タイプのバインディング・オブジェクトを表します。
ツリーの絞り込みには、ドロップダウン・フィルタを使用するか、検索フィールドに検索条件を入力します。ADF Facesで公開されているELでアクセス可能なオブジェクトは、図3-13に示すように、「JSFマネージドBean」ノードの「adfFacesContext」ノードにあります。

図3-13 式ビルダーでのadfFacesContextオブジェクト

ヒント:

これらのオブジェクトの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

ツリーで項目を選択すると、その項目がEL式内の「式」ボックスに移動されます。「式」ボックスに式を直接入力することもできます。

- 演算子ボタンを使用して、式に論理演算子または算術演算子を追加します。

図3-14に、explorerマネージドBeanのlabelプロパティにコンポーネントのラベルの値をバインドする式の作成に使用される「式ビルダー」ダイアログを示します。

図3-14 「式ビルダー」ダイアログ

ヒント:

EL式を作成する正しい構文の使用の詳細は、http://download.oracle.com/javaee/index.htmlの「Java EE 6 tutorial」を参照してください。

3.5.2 EL書式タグの使用方法

ADF EL書式タグでは、プレースホルダ・パラメータを使用するテキストを作成でき、このテキストを、Stringを受け取るコンポーネント属性の値として使用できます。実行時に、プレースホルダはパラメータ値で置換されます。

たとえば、現在のユーザーの名前がマネージドBeanに格納され、メッセージ内でその名前をoutputTextコンポーネントの値として表示するとします。例3-17に示すように、formatStringタグを使用できます。

例3-17 formatStringタグを使用した、パラメータ付きメッセージの表示

<af:outputText value="#{af:formatString('The current user is: {0},
someBean.currentUser)}" />

この例では、formatStringタグはキーが"0"である1つのパラメータを受け取り、値someBean.currentUserに解決します。

formatStringタグおよびformatNamedタグという2つのタイプの書式タグが使用可能です。formatStringタグは索引付きパラメータを使用しますが、formatNamedタグは名前付きパラメータを使用します。タイプごとに4つのタグがあり、それぞれ異なる数のパラメータ(最大4)を受け取ります。たとえば、formatString2タグは2つの索引付きパラメータを受け取り、formatNamed4タグは4つの名前付きパラメータを受け取ります。

formatNamedタグを使用する場合は、キーと値の両方を設定します。例3-18に、formatNamed2タグを使用して特定のディスク上のファイル数を表示するメッセージを示します。このメッセージには2つのパラメータが含まれます。

例3-18 formatNamed2タグを使用したメッセージの表示

<af:outputText value="#{af:formatNamed2(
'The disk named {disk}, contains {fileNumber} files', 'disk', bean.disk, 'fileNumber', bean.fileNumber)}" />

3.5.3 EL式のマネージドBean内での使用方法

必要なEL式はJDeveloperで作成され、作成されない式は式ビルダーを使用して作成できますが、マネージドBean内でEL式にアクセスしたり、EL式を設定または起動する必要がある場合もあります。

例3-19に、EL式への参照を取得し、適合するオブジェクトを返す(または作成する)方法を示します。

例3-19 マネージドBeanからのEL式の解決

public static Object resolveExpression(String expression) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
ValueExpression valueExp =
elFactory.createValueExpression(elContext, expression,
Object.class);
return valueExp.getValue(elContext);
}

例3-20に、メソッド式を解決する方法を示します。

例3-20 マネージドBeanからのメソッド式の解決

public static Object resloveMethodExpression(String expression,
Class returnType,
Class[] argTypes,
Object[] argValues) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
MethodExpression methodExpression =
elFactory.createMethodExpression(elContext, expression, returnType,
argTypes);
return methodExpression.invoke(elContext, argValues);
}

例3-21に、マネージドBeanで新たにオブジェクトを設定する方法を示します。

例3-21 マネージドBeanでの新たなオブジェクトの設定

public static void setObject(String expression, Object newValue) {
FacesContext facesContext = getFacesContext();
Application app = facesContext.getApplication();
ExpressionFactory elFactory = app.getExpressionFactory();
ELContext elContext = facesContext.getELContext();
ValueExpression valueExp =
elFactory.createValueExpression(elContext, expression,
Object.class);

//Check that the input newValue can be cast to the property type
//expected by the managed bean.
//Rely on Auto-Unboxing if the managed Bean expects a primitive
Class bindClass = valueExp.getType(elContext);
if (bindClass.isPrimitive() || bindClass.isInstance(newValue)) {
valueExp.setValue(elContext, newValue);
}
}

3.6 マネージドBeanの作成と使用

マネージドBeanは、様々な構成ファイルを使用してアプリケーションに登録するJavaクラスです。JSFアプリケーションを起動すると、これらの構成ファイルが解析されてBeanが使用可能になり、EL式で参照できるため、Beanのプロパティとメソッドにアクセスできます。マネージドBeanが初めて参照されたときにまだ存在していない場合、マネージドBean作成機能によりBeanのデフォルトのコンストラクタ・メソッドがコールされて、Beanがインスタンス化されます。また、プロパティが宣言されると、宣言されたデフォルトの値が移入されます。

多くの場合、マネージドBeanは、フロント・エンドで処理することが最適なイベントやデータ操作を処理します。標準JSFアプリケーションでのマネージドBeanの使用方法の詳細は、http://www.oracle.com/technetwork/java/index.htmlの「Java EE 6 tutorial」を参照してください。

ベスト・プラクティス:

マネージドBeanを使用して、現在のユーザーなどのブックキーピング情報のみを格納します。すべてのアプリケーション・データおよび処理データは、アプリケーションのビジネス・レイヤーのロジックによって処理される必要があります。

標準JSFアプリケーションでは、マネージドBeanはfaces-config.xml構成ファイルに登録されます。

注意:

ADFモデル・データ・バインディングおよびADFコントローラを使用する場合は、faces-config.xmlファイルではなく、ADFタスク・フローにマネージドBeanを登録する必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「Fusion WebアプリケーションでのマネージドBeanの使用」の章を参照してください。

3.6.1 JDeveloperでのマネージドBeanの作成方法

faces-config.xmlファイルに概要エディタを使用して、マネージドBeanの作成とJSFアプリケーションへの登録を同時に行えます。

始める前に

マネージドBeanに関する知識が役立つ場合があります。詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

マネージドBeanの作成および登録手順:

1. 「アプリケーション」ウィンドウで、アプリケーションのfaces-config.xmlをダブルクリックします。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 概要エディタで、「マネージドBean」ナビゲーション・タブをクリックします。
図3-15に、File Explorerアプリケーションを含むADF Facesのデモ・アプリケーションで使用されるfaces-config.xmlファイルの場合のエディタを示します。

図3-15 faces-config.xmlファイル内のマネージドBean

4. 「追加」アイコンをクリックして「マネージドBean」表に行を追加します。

5. 「マネージドBeanの作成」ダイアログで値を入力します。ダイアログの使用の詳細が必要な場合は、「ヘルプ」をクリックします。JDeveloperでクラス・ファイルを作成する場合は、「クラスが存在しない場合は生成」オプションを選択します。

注意:

マネージドBeanを登録するスコープまたは値を格納するスコープを決める場合は、次のことを考慮してください。

- 必ず、できるだけ狭いスコープを使用するようにしてください。

- マネージドBeanがコンポーネント・インスタンスを受け入れおよび返すことでコンポーネント・バインディングに参加する場合(つまり、ページ上のUIコンポーネントがbinding属性を使用してBean上のコンポーネント・プロパティにバインドする場合)は、マネージドBeanがrequestまたはbackingBeanスコープに格納されている必要があります。これらのスコープの1つに格納できない場合(たとえば、高可用性の理由でsessionスコープに格納する必要がある場合)は、ComponentReference APIを使用する必要があります。詳細は、3.6.3項「コンポーネント・バインディングおよびマネージドBeanに関する必知事項」を参照してください。

- sessionScopeスコープは、ユーザー情報やコンテキスト情報などのセッション全体に関係する情報にのみ使用します。あるページから別のページへの値の受渡しには、sessionScopeスコープは使用しないようにします。

様々なオブジェクト・スコープの詳細は、5.6項「オブジェクト・スコープ・ライフサイクル」を参照してください。

6. オプションでBeanに管理プロパティを追加できます。Beanがインスタンス化される際、指定した値が管理プロパティに設定されます。「Managed Bean」表でBeanを選択した状態で「新規」アイコンをクリックし、「管理プロパティ」表に行を追加します。「プロパティ」ウィンドウで、プロパティ名を入力します(他のフィールドはオプションです)。

注意:

このエディタを使用して管理プロパティを宣言できますが、対応するコードはJavaクラスに生成されません。適切なタイプのプライベート・メンバー・フィールドを作成し、コード・エディタのポップアップ・メニューの「アクセッサの生成」メニュー項目を選択して、これらのBeanプロパティに対応するgetおよびsetメソッドを生成することにより、コードを追加する必要があります。

3.6.2 JDeveloperを使用してマネージドBeanを作成する場合の処理

マネージドBeanを作成する際、Javaファイルを生成するよう選択すると、指定された名前とデフォルト・コンストラクタを使用してスタブ・クラスが自動的に作成されます。例3-22に、viewパッケージに格納されたMyBeanクラスに追加されるコードを示します。

例3-22 マネージドBean用に生成されたコード

package view;

public class MyBean {
public MyBean() {
}
}

ここでページに必要なロジックを追加する必要があります。このロジックは、マネージドBeanのmanaged-bean-nameを参照するEL式を使用して参照できます。たとえば、my_beanマネージドBeanのmyInfoプロパティにアクセスする場合、EL式は次のようになります。

#{my_bean.myInfo}

JDeveloperで、faces-config.xmlファイルへのmanaged-bean要素の追加も行われます。例3-23は、MyBeanクラスに対して作成されたmanaged-bean要素を示しています。

例3-23 faces-config.xmlファイルでのマネージドBeanの構成

<managed-bean>
<managed-bean-name>my_bean</managed-bean-name>
<managed-bean-class>view.MyBean</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

3.6.3 コンポーネント・バインディングおよびマネージドBeanに関する必知事項

マネージドBeanの問題を回避するには、(コンポーネントのbinding属性を通じて) Beanでコンポーネント・バインディングを使用する必要がある場合に、requestスコープにBeanを格納する必要があります(アプリケーションでFusionテクノロジ・スタックを使用する場合は、backingBeanスコープに格納する必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のFusion WebアプリケーションでのマネージドBeanの使用に関する項を参照してください。ただし、BeanをrequestまたはbackingBeanスコープに格納できない状況が発生することがあります。たとえば、マネージドBeanがクラスタ化環境にデプロイできるようにsessionスコープに格納されているため、シリアライズ可能なインタフェースを実装する必要がある場合があります。シリアライズ可能な場合、リクエスト中に変更されるマネージドBeanは、フェイルオーバーのために他のサーバーに配信できます。一方、ADF Facesコンポーネント(および一般にJSFコンポーネント)はシリアライズ可能ではありません。そのため、シリアライズされたマネージドBeanがコンポーネント・バインディングを使用してコンポーネントにアクセスしようとした場合、参照されるコンポーネントをシリアライズできないため、Beanはシリアライズに失敗します。ADF Facesコンポーネントはスレッド・セーフではないため、シリアライズされたマネージドBeanにバインドされたコンポーネントには、スレッドの安全性の問題もあります。

requestまたはbackingBeanスコープを使用していないバッキングBeanにUIコンポーネント・インスタンスへのコンポーネント参照を格納する必要がある場合は、Trinidad ComponentReference APIを使用してコンポーネント・インスタンスへの参照を格納する必要があります。UIComponentReference.newUIComponentReference()メソッドは、現在のページのUIComponentインスタンスを取得するために使用できるシリアライズ可能参照オブジェクトを作成します。例3-24に、マネージドBeanがUIComponentReference APIを使用して検索フィールドの値を取得および設定する方法を示します。

例3-24 UIComponentReference APIを使用するセッション・スコープ・マネージドBean

...
private ComponentReference<UIInput> searchField;
...
public void setSearchField(UIInput searchField)
{
if( this.searchField == null)
this.searchField = ComponentReference.newUIComponentReference(searchField);
}

public UIInput getSearchField()
{
return searchField ==null ? null : searchField.getComponent();
}
....

UIComponentReference APIを使用する際には、次の点に注意してください。

- APIは、リクエスト・スレッドでコールされるかぎりスレッド・セーフです。

- 渡されるADF FacesコンポーネントにはIDが必要です。

- コンポーネントがネーミング・コンテナ間で移動される場合、または祖先ネーミング・コンテナのいずれかでIDが変更された場合は、参照が中断されます。

UIComponentReference APIの詳細は、Trinidad Javadocを参照してください。

3.7 ADF Faces Javadocの表示

ADF Facesを処理する際に、ADF FacesクラスのJavadocを表示することが必要になる場合があります。JavadocはJDeveloperから表示できます。

3.7.1 ADF Facesのソース・コードおよびJavadocの表示方法

ADF Faces Javadocは、JDeveloperから直接表示できます。

クラスのJavadocを表示する手順:

1. メイン・メニューから、「ナビゲート」→「Javadocに移動」を選択します。

2. 「Javadocに移動」ダイアログで、表示するクラス名を入力します。名前が正確にわからない場合でも、名前を入力し始めると、JDeveloperによって名前が合致するクラスのリストが表示されます。ADF Facesコンポーネントは、oracle.adf.view.richパッケージにあります。

ヒント:

Javaクラス・ファイルでは、名前または関数にカーソルを置いて[Ctrl]+[D]を押すことで、クラス名参照またはJavaScript関数コールのJavadocに直接移動できます。

第II部

ADF Facesアーキテクチャの理解

第II部には、次の章が含まれています。

- 第4章「ADF Facesクライアント側アーキテクチャの使用方法」

- 第5章「ADF FacesでのJSFライフサイクルの使用」

- 第6章「イベントの処理」

- 第7章「入力の検証および変換」

- 第8章「部分ページ・コンテンツの再レンダリング」

4 ADF Facesクライアント側アーキテクチャの使用方法

この章では、ADF Facesクライアント側アーキテクチャの概要を説明します。

この章では、次の項目について説明します。

- 4.1項「ADF Facesアーキテクチャの使用について」

- 4.2項「JavaScriptのページへの追加」

- 4.3項「クライアント側コンポーネントのインスタンス化」

- 4.4項「クライアント・イベントのリスニング」

- 4.5項「クライアントでのコンポーネント・プロパティへのアクセス」

- 4.6項「クライアント側コンポーネントに対するボーナス属性の使用」

- 4.7項「レンダリングおよび可視性の理解」

- 4.8項「ページでのクライアント・コンポーネントの検索」

- 4.9項「JavaScriptライブラリのパーティション化」

4.1 ADF Facesアーキテクチャの使用について

ADF Facesは、JavaServer Facesアーキテクチャを拡張し、標準のサーバー中心モデルの上にクライアント側フレームワークを追加しています。ADF Facesコンポーネントの大部分は、リクエストのためにサーバー側で生成されるHTMLにレンダリングされます。また、ADF Facesでは、クライアント側コンポーネントとイベント・モデルを使用してクライアントに到達できるようにコンポーネントを実装できます。

ADF Facesフレームワークには、JavaScriptを使用するために通常必要な機能の多くがすでに含まれています。多くの場合、JavaScriptを使用しなくても、リッチなコンポーネント機能を宣言的に実現できます。ただし、クライアント側イベントに対するカスタム処理など、独自のJavaScriptを追加する必要がある場合があります。このような場合は、クライアント側フレームワークを使用できます。

最も多く対話対象となるJavaScriptクラスはAdfUIComponentとそのサブクラスです。このクラスのインスタンスは、サーバー側コンポーネントのクライアント側表現です。クライアント側コンポーネントは、イベント処理がサポートされる簡単なプロパティ・コンテナとみなすことができます。クライアント側コンポーネントは、主に、アプリケーション開発者とフレームワーク自体の両方に対するAPI規定を公開することでページに動作を追加するためにあります。特に、クライアントでのボタンの状態の切替えを可能にするのは、この規定です。

各クライアント・コンポーネントには、プロパティ(キーと値のペア)のセットと、サポートされている各イベント・タイプ用のリスナーのリストがあります。すべてのADF Faces JavaScriptクラスは、他のJavaScriptライブラリと名前が競合しないようAdfで始まります。たとえば、RichButtonはAdfButtonを持ち、RichDocumentはAdfRichDocumentを持つなどです。

クライアント側JavaScriptレイヤーでは、クライアント・コンポーネントは主にフレームワークおよび開発者にAPI規定を提供するために存在します。クライアント・コンポーネントは、状態を格納し、APIを提供するためにのみ存在するため、DOM (Document Object Model)と直接対話しません。DOMとのすべての対話は、ピアと呼ばれる媒介を使用して行われます。ピアは、Javaレンダラによって生成されたDOMと対話し、その状態の更新およびユーザー操作への応答を処理します。

ピアでは、この他に次のような多くの処理が行われます。

- DOMの初期化とクリーンアップ

- DOMのイベント処理

- ジオメトリ管理

- 部分ページ・レスポンスの処理

- 子の可視性の変更の処理

この分離により、コンポーネントおよびアプリケーション開発者がコンポーネントのDOM実装の変更から隔離され、コンポーネント(たとえば、Flashコンポーネント)がHTML DOMで実装されているかどうかをアプリケーションが知る必要もまったくなくなります。

大部分のコンポーネントベースのフレームワーク同様、JSFのコンポーネント・モデルに固有の特性は、コンポーネントはネストして階層(通常コンポーネント・ツリーと呼ばれる)を形成できるということです。これは、親コンポーネントで子が追跡され、コンポーネント・ツリーをたどって特定のコンポーネントの子孫をすべて見つけることができるということです。コンポーネント・ツリー全体はサーバーにあり、ADF Facesクライアント側コンポーネント・ツリーにはあまり移入されません。

パフォーマンスを最適化するために、クライアント・コンポーネントは、clientListenerハンドラが登録されているため、またはページ開発者がクライアント側のコンポーネントと対話する必要があり、クライアント・コンポーネントを使用可能として構成したため必要になった場合にのみ存在します。例外的なケースを除き、クライアント・フレームワークを理解する必要はありません。アーキテクチャ機能の大部分は、コードを作成せずに宣言的に使用できます。

たとえば、フレームワークでは、各サーバー側コンポーネントに対応するクライアント・コンポーネントをすべて作成するわけではないため、クライアント版のコンポーネント・インスタンスが必要な場合もあります。4.3項「クライアント側コンポーネントのインスタンス化」に、これを宣言的に行う方法が説明されています。JDeveloperの「プロパティ」ウィンドウを使用して、4.7項「レンダリングおよび可視性の理解」で説明されている、コンポーネントをレンダリングするかどうか、あるいは非表示にするかどうかを決めるプロパティを設定します。

注意:

既存のサーバー側コンポーネントに対応しないJavaScriptコンポーネントが存在することも可能です。たとえば、一部のADF Facesコンポーネントでは、ポップアップ・コンテンツが必要なクライアント側動作を持ちます。これらのコンポーネントでは、サーバー側Java RichPopupコンポーネントが存在しなくても、AdfRichPopup JavaScriptコンポーネントを作成できます。

その他の機能では、ADF Faces JavaScript APIの使用が必要な場合があります。たとえば、4.8項「ページでのクライアント・コンポーネントの検索」では、APIを使用して特定のクライアント側コンポーネントを探す方法を説明し、4.5項「クライアントでのコンポーネント・プロパティへのアクセス」では、特定のプロパティにアクセスする方法を説明しています。

JavaScriptを多用したフレームワークに共通する問題は、大規模なJavaScriptコード・ベースをクライアントに送信する最良の方法を決定することです。すべてのコードが単一のJavaScriptライブラリにある場合はダウンロード時間が長くなりますが、JavaScriptを多くのライブラリに分割しすぎると、ラウンドトリップが大量になります。この問題を軽減するために、ADF FacesではJavaScriptコードがパーティションに集約されます。JavaScriptライブラリ・パーティションには、コンポーネントのコードまたは通常一緒に使用される機能、あるいはその両方が含まれています。詳細は、4.9項「JavaScriptライブラリのパーティション化」を参照してください。

4.2 JavaScriptのページへの追加

インラインJavaScriptをページに直接追加するか、JavaScriptライブラリをページにインポートできます。ライブラリをインポートする場合は、ページ・コンテンツ・サイズが削減され、ライブラリをページ間で共有でき、ブラウザによってキャッシュできます。可能な場合には必ずJavaScriptライブラリをインポートする必要があります。インラインJavaScriptは、ページ固有の小さなスクリプトが必要な場合にのみ使用します。

パフォーマンスのヒント:

JavaScriptを必要とするページにのみJavaScriptを含めると、JavaScriptがテンプレートに含まれている場合とは異なり、それを必要としないページではロードする必要がないため、パフォーマンスが向上します。ただし、ほとんどのページで同じJavaScriptコードを使用する場合は、ライブラリをインポートするためのスクリプトまたはタグをテンプレートに含めることを検討してください。

ただし、JavaScriptコード・ライブラリが非常に大きくなった場合、ライブラリを内容に応じて分割し、(テンプレートではなく)ページで必要な部分のみを含めることに注意してください。この方法で、ブラウザ・キャッシュが使用され、ページのHTMLコンテンツが小さくなるため、パフォーマンスが向上します。

4.2.1 インラインのJavaScriptの使用方法

JavaScriptをページに作成し、clientListenerタグを使用して呼び出します。

始める前に

ページへのJavaScriptの追加に関する知識が役立つ場合があります。詳細は、4.2項「JavaScriptのページへの追加」を参照してください。

インラインのJavaScriptを使用する手順:

1. 例4-1に太字で示すコードを追加して、MyFaces Trinidadタグ・ライブラリをページのルート要素に追加します。

例4-1 ページでのMyFaces Trinidadタグ・ライブラリ

<f:view xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:trh="http://myfaces.apache.org/trinidad/html">

2. 「コンポーネント」ウィンドウのレイアウト・パネルにあるCore Structureグループの中のリソースをページ上にドラッグ・アンド・ドロップします。

注意:

ページまたはテンプレートにf:verbatimタグを使用してJavaScriptを指定しないでください。

3. 「リソースの挿入」ダイアログで、ドロップダウン・メニューから「JavaScript」を選択し、「OK」をクリックします。

4. ページの<af:resource>タグ内にJavaScriptを作成します。
たとえば、例4-6に示すsayHello関数は、例4-4のようにJSFページに含めることができます。

例4-2 インラインのJavaScript

<af:resource>
function sayHello()
{
alert("Hello, world!")
}
</af:resource>

5. 「構造」ウィンドウで、JavaScriptを呼び出すコンポーネントを右クリックし、「componentの中に挿入」→「ADF Faces」→「クライアント・リスナー」の順に選択します。

6. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドにJavaScript関数の名前を入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

4.2.2 JavaScriptライブラリのインポート方法

af:resourceタグを使用して、ページからJavaScriptライブラリにアクセスします。このタグは、documentタグのmetaContainerファセットの内部に含める必要があります。

始める前に

ページへのJavaScriptの追加に関する知識が役立つ場合があります。詳細は、4.2項「JavaScriptのページへの追加」を参照してください。

ページからJavaScriptライブラリにアクセスする手順:

1. documentタグの下に、例4-3に太字で示すコードを追加し、JavaScriptライブラリが含まれるディレクトリへの相対パスに/mySourceDirectoryを置き換えます。

例4-3 JavaScriptライブラリへのアクセス

<af:document>
<f:facet name="metaContainer">
<af:resource source="/mySourceDirectory"/>
</facet>
<af:form></af:form>
</af:document>

2. 「構造」ウィンドウで、JavaScriptを呼び出すコンポーネントを右クリックし、「componentの中に挿入」→「ADF Faces」→「クライアント・リスナー」の順に選択します。

3. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドに関数の名前を入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

4.2.3 クライアント・イベント・ソースへのアクセスに関する必知事項

JavaScriptでクライアント・コンポーネントにアクセスする必要がある場合、リスナーのコンテキストで行われ、イベントのソース・コンポーネントにアクセスする必要がある場合がしばしばあります。getSource()メソッドを使用してクライアント・コンポーネントを取得します。例4-4に、名前を表示するためにソース・クライアント・コンポーネントにアクセスするsayHello関数を示します。

例4-4 クライアント・イベント・ソースへのアクセス

function sayHello(actionEvent)
{
var component=actionEvent.getSource();

//Get the ID for the component
var id=component.getId();

alert("Hello from "+id);
}

クライアント・イベント・ソースへのアクセスの詳細は、6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。クライアント側プロパティへのアクセスの詳細は、4.5項「クライアントでのコンポーネント・プロパティへのアクセス」を参照してください。実行時にクライアント・イベントを処理する方法の詳細は、6.3.7項「実行時の処理: クライアント側イベントの機能の仕方」を参照してください。

4.3 クライアント側コンポーネントのインスタンス化

デフォルトでは、フレームワークでは、どのコンポーネントが、対応するクライアント側コンポーネント・インスタンスを持つかについて保証されません。クライアント上のコンポーネントと対話するには、通常はclientListenerハンドラを登録します。登録されているclientListenerハンドラがコンポーネントにある場合、コンポーネントはクライアント側表現を自動的に持ちます。clientComponent属性をtrueに設定して、コンポーネントがクライアントで使用できるよう明示的に構成することもできます。

4.3.1 クライアント側インスタンス用にコンポーネントを構成する方法

clientComponent属性を使用してクライアント側インスタンスを持つようにコンポーネントを手動で構成できます。

パフォーマンスのヒント:

クライアントのコンポーネントとプログラムで対話する場合にのみclientComponentをtrueに設定します。

注意:

フレームワークが独自に使用するためにクライアント・コンポーネントを作成する場合、そのクライアント・コンポーネントにはその時点でフレームワークが必要とする情報のみ含まれます。たとえば、一部の属性は使用可能でない場合があります。

始める前に

クライアント側インスタンスに関する知識が役立つ場合があります。詳細は、4.3項「クライアント側コンポーネントのインスタンス化」を参照してください。

クライアント側インスタンスのコンポーネントを構成する手順:

1. 「構造」ウィンドウで、クライアント側インスタンスを必要とするコンポーネントを選択します。

2. 「プロパティ」ウィンドウでClientSideをtrueに設定します。

4.3.2 clientComponentをtrueに設定した場合の処理

clientComponent属性をtrueに設定すると、コンポーネントのAdfUIComponentクラスのインスタンスがフレームワークで作成されます。このクラスでは、クライアント側で操作できるAPIが提供され、基本的なプロパティ・アクセッサ・メソッド(getProperty()、setProperty()など)、イベント・リスナーの登録およびイベント配信関連のAPIも提供されます。フレームワークには、プロパティ固有のアクセッサ・メソッド(getText()、setText()など)を公開するレンダラ固有のサブクラス(AdfRichOutputTextなど)も用意されています。これらのアクセッサ・メソッドは、AdfUIComponentクラスのgetProperty()およびsetProperty()メソッドをラップするのみのラッパーで、コーディングが簡便になるよう用意されています。

たとえば、sayHello関数から値(表示するテキスト)を取得するoutputTextコンポーネントがページにあるとします。この関数は、値を設定するためにoutputTextコンポーネントにアクセスできる必要があります。これが機能するには、クライアント側バージョンのoutputTextコンポーネントがある必要があります。例4-5に、JSFページ・コードを示します。outputTextコンポーネントにid値があり、clientComponent属性がtrueに設定されていることに注意してください。また、値はJavaScriptで設定されるため、例には値がないことにも注意してください。

例4-5 コンポーネントの追加

<af:button text="Say Hello">
<af:clientListener method="sayHello" type="action"/>
</af:button>

<af:outputText id="greeting" value="" clientComponent="true">

outputTextにクライアント側表現があるため、JavaScriptでこれを見つけて使用できます。

注意:

クライアント・リスナーがない場合やclientComponent属性がtrueに設定されていない場合でも、ADF Facesフレームワークは自身の目的のためにクライアント・コンポーネントを作成することがあります。ただし、これらのクライアント・コンポーネントは完全に機能しない場合があります。

4.4 クライアント・イベントのリスニング

従来のJSFアプリケーションでは、クライアントでイベントを処理する場合、DOMレベルのイベントをリスニングする必要があります。ただし、これらの実装は移植可能な形式で配信されません。ADF Facesのクライアント側イベント・モデルはJSFイベント・モデルと似ていますが、クライアントで実装されます。クライアント側イベント・モデルはDOMの要約で、コンポーネントレベルのイベント・モデルとライフサイクルが提供され、サーバーから独立して実行されます。このため、ボタンのclickイベントをリスニングする必要がありません。かわりに、キーまたはマウスのイベントで発生するAdfActionEventイベントをリスニングできます。

クライアントによって送信されるイベントはすべてAdfBaseEventクラスのサブクラスです。各クライアント・イベントには、イベントをトリガーしたコンポーネントであるソースがあります。イベントには、イベントをリスニングするリスナーを判断するタイプ(actionまたはdialogなど)もあります。クライアント・リスナーは、af:clientListenerタグを使用してコンポーネントに宣言的に登録します。

4.4.1 クライアント・イベントをリスニングする方法

af:clientListenerタグを使用して、クライアント・イベントに対して対応するJavascriptをコールします。たとえば、クリックされたら"Hello World"アラートを表示する必要のあるボタンがあるとします。最初に、アラートを表示することでイベントに応答するJavaScript関数を作成する必要があります。次に、その関数を呼び出すクライアント・リスナーをコンポーネントに追加します。

始める前に

クライアント・イベント処理に関する知識が役立つ場合があります。詳細は、4.4項「クライアント・イベントのリスニング」を参照してください。

クライアント・イベントをリスニングする手順:

1. JavaScript関数を実装します。たとえば、アラートを表示するには、例4-6に示すJavaScript関数を作成できます。

例4-6 JavaScriptイベント・ハンドラ

function sayHello(event)
{
alert("Hello, world!")
}

2. 「コンポーネント」ウィンドウで、「操作」パネルの「リスナー」グループから「クライアント・リスナー」を、イベントを発生させる子としてコンポーネントにドラッグ・アンド・ドロップします。
手順1で作成した関数と、リスナーが応答する必要のあるアクションのタイプを入力します。例4-7に、sayHello関数のリスナーに対して作成するコードを示します。

例4-7 クライアント・リスナーの登録

<af:button text="Say Hello">
<af:clientListener method="sayHello" type="action"/>
</af:button>

ヒント:

ボタンにクライアント・リスナーが登録されているため、フレームワークで、クライアント版のコンポーネントが自動的に作成されます。

クライアント版のコンポーネントがあるため、ボタンがクリックされると、AdfActionクライアント・イベントが起動されます。AdfActionイベントをリスニングするようclientListenerタグが構成されているため、sayHello関数が実行されます。クライアント側イベントの詳細は、6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。

4.5 クライアントでのコンポーネント・プロパティへのアクセス

コンポーネントの各組込みプロパティには、簡易アクセッサ・メソッドがコンポーネント・クラスに用意されています。たとえば、クライアント・コンポーネントでgetValue()メソッドをコールし、サーバーで使用されたのと同じ値を受け取ることができます。

注意:

ADF Faces内のブール・プロパティを含むすべてのクライアント・プロパティでgetXyz関数命名規則を使用します。ブール・プロパティのisXyz命名規則は使用されません。

定数もクラス・オブジェクトのプロパティ名に使用できます。たとえば、styleClassを使用するかわりにAdfRichDialog.STYLE_CLASS定数を使用できます。

注意:

一部のJavaScript実行環境では、文字列をコーディングすると呼出しのたびにオブジェクトを割り当てる必要があるため、JavaScriptでは、文字列をコーディングするよりも定数を参照する方が効率的です。

コンポーネントのプロパティが変更されると、最終的な結果として、コンポーネントのDOMが新しい状態を反映するように更新されます。場合によっては、サーバーへのラウンドトリップは発生しません。このプロセスにおけるコンポーネントのロールはかなり限られています。新しいプロパティ値を格納してから、変更をピアに通知するだけです。ピアには、新しいコンポーネント状態を反映するようにDOMを更新するロジックが含まれます。

注意:

すべてのプロパティの変更が、クライアント側のピアを使用して処理されるわけではありません。一部のプロパティ変更はサーバーに伝播され、PPRを使用してコンポーネントがレンダリングされます。

クライアントに設定されるほとんどのプロパティ値は、サーバーとの自動同期が行われる原因になります(ただし、一部の複合Javaオブジェクトはクライアントにまったく送信されません)。ただし、これとは異なる動作をするセキュア・プロパティと分離プロパティの2種類のプロパティがあります。

セキュア・プロパティは、クライアントにまったく設定できないプロパティです。たとえば、悪意のあるクライアントでJavaScriptを使用してcommandLinkコンポーネントのimmediateフラグがtrueに設定されるとします。この変更がサーバーに伝播された結果、サーバー側の検証が省略され、セキュリティ・ホールとなる可能性があります(immediateプロパティの使用の詳細は、5.2項「immediate属性の使用」を参照してください)。つまり、immediateプロパティはセキュア・プロパティです。

JavaScriptからセキュア・プロパティの設定を試みると失敗します。詳細は、4.5.3項「無効化されたプロパティを非保護にする方法」を参照してください。表4-1に、クライアント・コンポーネントのセキュア・プロパティを示します。

表4-1 セキュア・クライアント・プロパティ

コンポーネント

セキュア・プロパティ

AdfRichChooseColor

colorData

AdfRichComboboxListOfValue

disabled

readOnly

AdfRichCommandButton

disabled

readOnly

blocking

AdfRichCommandImageLink

blocking

disabled

partialSubmit

AdfRichCommandLink

readOnly

AdfRichDialog

dialogListener

AdfRichDocument

failedConnectionText

AdfRichInputColor

disabled

readOnly

colorData

AdfRichInputDate

disabled

readOnly

valuePassThru

AdfRichInputFile

disabled

readOnly

AdfRichInputListOfValues

disabled

readOnly

AdfRichInputNumberSlider

disabled

readOnly

AdfRichInputNumberSplinBox

disabled

readOnly

maximum

minimum

stepSize

AdfRichInputRangeSlider

disabled

readOnly

AdfRichInputText

disabled

readOnly

secret

AdfRichPopUp

launchPopupListener

model

returnPopupListener

returnPopupDataListener

createPopupId

AdfRichUIQuery

conjunctionReadOnly

model

queryListener

queryOperationListener

AdfRichSelectBooleanCheckbox

disabled

readOnly

AdfRichSelectBooleanRadio

disabled

readOnly

AdfRichSelectManyCheckbox

disabled

readOnly

valuePassThru

AdfRichSelectManyChoice

disabled

readOnly

valuePassThru

AdfRichSelectManyListBox

disabled

readOnly

valuePassThru

AdfRichSelectManyShuttle

disabled

readOnly

valuePassThru

AdfRichSelectOneChoice

disabled

readOnly

valuePassThru

AdfRichSelectOneListBox

disabled

readOnly

valuePassThru

AdfRichSelectOneRadio

disabled

readOnly

valuePassThru

AdfRichSelectOrderShuttle

disabled

readOnly

valuePassThru

AdfRichUITable

filterModel

AdfRichTextEditor

disabled

readOnly

AdfUIChart

chartDrillDownListener

AdfUIColumn

sortProperty

AdfUICommand

actionExpression

returnListener

launchListener

immediate

AdfUIComponentRef

componentType

AdfUIEditableValueBase

immediate

valid

required

localValueSet

submittedValue

requiredMessageDetail

AdfUIMessage.js

for

AdfUINavigationLevel

level

AdfUINavigationTree

rowDisclosureListener

startLevel

immediate

AdfUIPage

rowDisclosureListener

immediate

AdfUIPoll

immediate

pollListener

AdfUIProgress

immediate

AdfUISelectBoolean

selected

AdfUISelectInput

actionExpression

returnListener

AdfUISelectRange

immediate

rangeChangeListener

AdfUIShowDetailBase

immediate

disclosureListener

AdfUISingleStep

selectedStep

maxStep

AdfUISubform

default

AdfUITableBase

rowDisclosureListener

selectionListener

immediate

sortListener

rangeChangeListener

showAll

AdfUITreeBase

immediate

rowDisclosureListener

selectionListener

focusRowKey

focusListener

AdfUITreeTable

rangeChangeListener

AdfUIValueBase

converter

ADF Facesでは、disabledプロパティを非保護にできるように構成できます。この機能は、JavaScriptを使用してボタンを有効および無効にする必要がある場合に役立ちます。

分離プロパティは、クライアントで設定できるがサーバーに伝播することはできないプロパティです。これらのプロパティには、サーバーのライフサイクルに依存しないクライアント上のライフサイクルがあります。たとえば、クライアント・フォーム入力コンポーネント(AdfRichInputTextなど)には、JavaのEditableValueHolderコンポーネントのようにsubmittedValueプロパティがあります。ただし、このプロパティの設定はサーバーに直接影響しません。この場合、標準のフォーム送信手法によって、送信された値のサーバーでの更新を処理します。

プロパティは、分離とセキュアの両方にすることができます。実際には、このようなプロパティはクライアント上で分離プロパティのように動作します。これらはクライアントで設定できますが、サーバーには送信されません。ただし、サーバーではセキュア・プロパティとして動作するため、クライアントがこれらを設定しようとすると拒否されます。

4.5.1 クライアントでのプロパティ値の設定方法

ADF Facesフレームワークには、基礎となるADFUIComponent.setProperty関数をコールして適切なプロパティ名を渡す便利なsetXYZ関数が用意されています(詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください)。例4-8に、setProperty関数を使用して、値が変更されたときにinputTextコンポーネントのbackgroundcolorプロパティを赤に設定する方法を示します。

例4-8

<af:form>
<af:resource type="javascript">
function color(event) {
var inputComponent = event.getSource();
inputComponent.setproperty("inlineStyle", "background-color:Red");
}
</af:resource>
<af:outputText id="it" label="label">
<af:clientListener method="color" type="valueChange"/>
</af:inputText>
</af:form>

これらの関数を使用してプロパティの値を変更できます。分離プロパティまたはセキュア・プロパティでないかぎり、値はサーバー上でも変更されます。

4.5.2 実行時の処理: クライアント・プロパティのクライアントでの設定方法

クライアントでsetProperty()関数をコールすると、プロパティが新しい値に設定され、同時にPropertyChangeEventイベントが古い値と新しい値を使用して起動されます(値が異なる場合)。また、プロパティを設定すると、コンポーネントが自身を再レンダリングする場合があります。

4.5.3 無効化されたプロパティを非保護にする方法

デフォルトでは、無効化されたプロパティは保護されたプロパティです。つまり、JavaScriptを使用してそれをクライアント上に設定することはできません。ただし、disabledプロパティを非保護に設定するには、unsecuredプロパティを使用します。disabledプロパティを非保護にする必要のあるコンポーネントのコードに、このプロパティとdisabledの値を手動で追加する必要があります。たとえば、disabledプロパティを非保護にする必要のあるボタンのコードは次のようになります。

<af:button text="commandButton 1" id="cb1" unsecure="disabled"/>

disabled属性が安全な場合、アプリケーションはdisabled属性により、アクション・イベントが配布されるべきでないときには配布されないようにします。disabled属性を非保護にすると、サーバーはそのdisabled属性を正しいものとして信頼できなくなります。このため、ユーザーはactionListenersを使用して同等のチェックを実行する必要があります。

たとえば、支出承認ページがあり、そのページで特定のマネージャが$200未満の請求書のみ承認できるようにするとします。そのため、現在のユーザーが請求書の承認を許可されていないかぎり、承認ボタンを無効にする必要があります。disabled属性を非保護にしないと、承認ボタンは、サーバーへのラウンドトリップが発生するまで無効のままになります。現在のユーザーが経費を承認できるかどうかはロジックが決定します。つまり、レンダリングのときに、ボタンが現在のユーザーに対して正しく表示されないことがあります。ページがロードされる際に、ボタンを正しく表示するには、unsecure属性をdisabledに設定し、クライアント上でJavaScriptを使用してボタンを無効にするかどうか決定します。ただし、この場合は、任意のJavaScript(制御できない悪意のあるJavaScriptを含む)が同じことを行う可能性があります。

悪意のあるJavaScriptを回避するには、ボタンにactionListenerを使用してサーバー上でロジックを実行します。サーバーにロジックを追加すると、無効な属性を変更してはならない場合に、それが変更されません。支出承認の例では、承認を実行する前にJavaScriptを使用して金額が$200以下であることをチェックし、また、ボタンにactionListenerを使用して現在のマネージャに適切な支出権限があることを再度チェックする必要があります。

同様に、アプリケーションを実行時に変更できるようにし、ユーザーがunsecureまたはdisabled属性、あるいはその両方を編集できるようにする場合は、サーバーとのラウンドトリップが発生した場合と同じロジックがアプリケーションによって実行されるようにする必要があります。

4.5.4 クライアントとサーバーのプロパティ値を同期させない方法

プロパティの値をサーバーに常に配信して同期することは望ましくない場合があります。たとえば、フォームにinputTextコンポーネントがあり、ユーザーがコンポーネントの1つで値を変更したらすぐに、変更済インジケータを表示するとします。この操作を行うには、JavaScriptを使用して、valueChangeEventイベントが配信されたらクライアント・コンポーネントのchanged属性をtrueに設定します。また、ユーザーがページを送信した場合は、その時点で値が保存されるため、変更済インジケータを表示しません。

次の例に示すように、JavaScriptを使用して、valueChangeEventが配信されたらchanged属性をtrueに設定します。

例4-9 JavaScriptを使用したchangedプロパティの設定

<af:form>
<af:resource type="javascript">
function changed(event) {
var inputComponent = event.getSource();
inputComponent.setChanged(true);
}
</af:resource>
<af:inputText id="it" label="label">
<af:clientListener method="changed" type="valueChange"/>
</af:inputText>
<af:button text="Submit"/>
</af:form>

コンポーネントのすべてのプロパティは一般にサーバーと同期されるため、この例を使用すると、changed属性の値(true)はサーバーにも送信されます。このため、変更済インジケータは引き続き表示されます。

値がサーバーに保存されたときにインジケータを表示しないようにするには、次のいずれかの代替方法を使用できます。

- イベント・リスナーを使用して、ロジックをクライアントからサーバーに移動します。この代替方法は、valueChangeEventイベントなど、サーバーに配信されるイベントがある場合に使用します。例4-10に、コード例を示します。

例4-10 サーバー上のプロパティ値を設定するJSFコード

<af:form>
<af:inputText label="label"
autoSubmit="true"
changed="#{test.changed}"
valueChangeListener="#{test.valueChange}"/>
<af:button text="Submit" />
</af:form>

例4-11に、対応するマネージドBeanコードを示します。

例4-11 マネージドBeanを使用したプロパティ値の設定

import javax.faces.event.ValueChangeEvent;
import oracle.adf.view.rich.context.AdfFacesContext;

public class TestBean {
public TestBean() {}

public void valueChange(ValueChangeEvent valueChangeEvent)
{
setChanged(true);
AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
adfFacesContext.addPartialTarget(valueChangeEvent.getComponent());
FacesContext.getCurrentInstance().renderResponse();
}

public void setChanged(boolean changed)
{
_changed = changed;
}

public boolean isChanged()
{
return _changed;
}
private boolean _changed;
}

- カスタム・サーバー・イベントとserverListenerタグを呼び出すJavaScriptを使用して、ロジックをサーバーに移動します。この方法は、配信されるイベントがない場合に使用します。例4-12に、JSFコードを示します。

例4-12 JavaScriptとサーバー・リスナーを使用してプロパティ値を設定するJSFコード

<af:form>
<af:resource type="javascript">
function changed(event)
{
var inputComponent = event.getSource();
AdfCustomEvent.queue(inputComponent, "myCustomEvent", null, true);
}
</af:resource>
<af:inputText label="label" changed="#{test2.changed}">
<af:serverListener type="myCustomEvent"
method="#{test2.doCustomEvent}"/>
<af:clientListener method="changed" type="valueChange"/>
</af:inputText>
<af:button text="Submit"/>
</af:form>

例4-13に、マネージドBeanコードを示します。

例4-13 カスタム・イベントを使用したプロパティ値の設定

package test;

import javax.faces.context.FacesContext;

import oracle.adf.view.rich.context.AdfFacesContext;
import oracle.adf.view.rich.render.ClientEvent;

public class Test2Bean
{
public Test2Bean()
{
}

public void doCustomEvent(ClientEvent event)
{
setChanged(true);
AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
adfFacesContext.addPartialTarget(event.getComponent());
FacesContext.getCurrentInstance().renderResponse();
}

public void setChanged(boolean changed)
{
_changed = changed;
}

public boolean isChanged()
{
return _changed;
}
private boolean _changed;

}

- クライアント・コンポーネントでchanged属性をtrueに設定し、これがサーバーに伝播されますが、その後コマンド・コンポーネントでactionListenerを使用して、changed属性をfalseに戻します。例4-14に、JSFコードを示します。

例4-14 コマンド・コンポーネント上のリスナーを使用してプロパティ値を設定するJSFコード

<af:form>
<af:resource type="javascript">
function changed(event) {
var inputComponent = event.getSource();
inputComponent.setChanged(true);
}
</af:resource>
<af:inputText binding="#{test3.input}" label="label">
<af:clientListener method="changed" type="valueChange"/>
</af:inputText>
<af:button text="Submit" actionListener="#{test3.clear}"/>
</af:form>

例4-15に、対応するマネージドBeanコードを示します。

例4-15 ActionLIstenerを使用したプロパティ値の設定

package test;

import javax.faces.event.ActionEvent;

import oracle.adf.view.rich.component.rich.input.RichInputText;

public class Test3Bean
{
public Test3Bean()
{
}

public void clear(ActionEvent actionEvent)
{
_input.setChanged(false);
}

public void setInput(RichInputText input)
{
_input = input;
}

public RichInputText getInput()
{
return _input;
}

private RichInputText _input;
}

4.6 クライアント側コンポーネントに対するボーナス属性の使用

組込みプロパティ以外の情報をクライアントに送信する必要がある場合もあります。これは、ボーナス属性を使用して行えます。ボーナス属性は、clientAttributeタグを使用してコンポーネントに追加できる追加属性です。パフォーマンス上の理由から、クライアントに送信されるボーナス属性は、clientAttributeで指定されたもののみです。

clientAttributeタグでは、サーバー側コンポーネントの属性マップに追加される名前と値のペアを指定します。サーバー側属性マップの移入に加えて、clientAttributeタグを使用すると、ボーナス属性がクライアントに送信され、AdfUIComponent.getProperty("bonusAttributeName")メソッドを使用してアクセスできます。

フレームワークで、属性値のクライアントへのマーシャリングが行われます。マーシャリング・レイヤーで、文字列、ブール、数値、日付、配列、マップなど、各オブジェクト型のマーシャリングがサポートされます。マーシャリングの詳細は、6.4.3項「データのマーシャリングとアンマーシャリングに関する必知事項」を参照してください。

パフォーマンスのヒント:

マーシャリングによる過度のオーバーヘッドを防ぐため、クライアント側ボーナス属性を多用しないでください。

注意:

clientAttributeタグは、(アプリケーションで定義される)ボーナス属性にのみ使用します。クライアントで標準のコンポーネント属性にアクセスする必要がある場合、clientAttributeタグを使用するのではなく、clientComponent属性をtrueに設定します。詳細は、4.3項「クライアント側コンポーネントのインスタンス化」を参照してください。

4.6.1 ボーナス属性の作成方法

「コンポーネント」ウィンドウを使用してコンポーネントにボーナス属性を追加できます。

始める前に

ボーナス属性に関する知識が役立つ場合があります。詳細は、4.6項「クライアント側コンポーネントに対するボーナス属性の使用」を参照してください。

ボーナス属性を作成する手順:

1. 「構造」ウィンドウで、ボーナス属性を追加するコンポーネントを選択します。

2. 「コンポーネント」ウィンドウで、「操作」パネルから「クライアント属性」をコンポーネントに子としてドラッグ・アンド・ドロップします。

3. 「プロパティ」ウィンドウで、名前属性と値属性を設定します。

4.6.2 ボーナス属性のマーシャリングに関する必知事項

クライアント側ボーナス属性は、サーバーからクライアントへ自動的に配信されますが、その逆は行われません。つまり、クライアントでのボーナス属性の変更または設定は、サーバーに反映されません。既知(ボーナス以外)の属性のみ、クライアントからサーバーへ同期がとられます。アプリケーションで定義されたデータをサーバーに送り返す必要がある場合、カスタム・イベントを作成します。詳細は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

4.7 レンダリングおよび可視性の理解

すべてのADF Faces表示コンポーネントには、コンポーネントをページに表示してユーザーに見えるようにするかどうかに関係するrenderedとvisibleの2つの属性があります。

rendered属性のセマンティクは非常に厳密です。renderedがfalseに設定されている場合、サーバーへのラウンドトリップなしにコンポーネントをクライアントで表示することはできません。ページのコンテンツの動的な表示/非表示をサポートするために、フレームワークにはvisible属性が追加されています。falseに設定されている場合、コンポーネントのマークアップはクライアントで使用可能ですが、コンポーネントは表示されません。したがって、setVisible(true)またはsetVisible(false)メソッドをコールすると、JavaからのコールであろうとJavaScriptからのコールであろうと、コンポーネントがブラウザ内で表示または非表示になります(renderedがtrueに設定されている場合)。ただし、visibleは単純にDOMのコンテンツを表示および非表示にするため、renderedを使用した場合と常に同じ視覚的変化を提供するとはかぎりません。

パフォーマンスのヒント:

JavaScriptなど、サーバーへのラウンドトリップなしに可視性を切り替える必要がある場合にのみvisible属性をfalseに設定します。非表示のコンポーネントも、検証を含むコンポーネント・ライフサイクルを経過します。

クライアントでのみ可視性を切り替える必要がない場合は、かわりにrendered属性をfalseに設定します。コンポーネントをレンダリングしない(表示しないのではなく)場合、コンポーネントはクライアント側表現を持たず、コンポーネント・ライフサイクルを経過しないため、サーバーのパフォーマンスとクライアントのレスポンス時間が向上します。

例4-16に、2つのoutputTextコンポーネントを示します。一度にその一方のみがレンダリングされます。最初のoutputTextコンポーネントは、値がinputTextコンポーネントに入力されなかった場合にレンダリングされます。2番目のoutputTextコンポーネントは、値が入力されたときにレンダリングされます。

例4-16 レンダリングされる/レンダリングされないコンポーネント

<af:panelGroupLayout layout="horizontal">
<af:inputText label="Input some text" id="input"
value="#{myBean.inputValue}"/>
<af:button text="Enter"/>
</af:panelGroupLayout>
<af:panelGroupLayout layout="horizontal">
<af:outputLabel value="You entered:"/>
<af:outputText value="No text entered" id="output1"
rendered="#{myBean.inputValue==null}"/>
<af:outputText value="#{myBean.inputValue}"
rendered="#{myBean.inputValue !=null}"/>
</af:panelGroupLayout>

コンポーネントがクライアントでレンダリングされる場合、visibleプロパティを使用してコンポーネントをページに表示したり、非表示にできます。

例4-17に例4-16と同じ機能を示しますが、この例ではvisible属性を使用して、どのコンポーネントが表示されるのか決定します(rendered属性はデフォルトでtrueに設定されるため、明示的に設定する必要はありません)。

例4-17 表示可能/表示不可能なコンポーネント

<af:panelGroupLayout layout="horizontal">
<af:inputText label="Input some text" id="input"
value="#{myBean.inputValue}"/>
<af:button text="Enter"/>
</af:panelGroupLayout>
<af:panelGroupLayout layout="horizontal">
<af:outputLabel value="You entered:"/>
<af:outputText value="No text entered" id="output1"
visible="#{myBean.inputValue==null}"/>
<af:outputText value="#{myBean.inputValue}"
visible="#{myBean.inputValue !=null}"/>
</af:panelGroupLayout>

ただし、visible属性のかわりにrendered属性を使用することは、サーバー側でのパフォーマンスを向上させるため、JavaScriptで可視性を処理することもできます。

例4-18に、コンポーネントの可視性を処理するJavaScriptのページ・コードを示します。

例4-18 JavaScriptを使用した可視性の切替え

function showText()
{
var output1 = AdfUIComponent.findComponent("output1")
var output2 = AdfUIComponent.findComponent("output2")
var input = AdfUIComponent.findComponent("input")

if (input.getValue() == "")
{
output1.setVisible(true);
}
else
{
output2.setVisible(true)
}

}

4.7.1 Javascriptを使用した可視性の設定方法

コンポーネントのvisible属性を切り替えられる条件付きJavaScript関数を作成できます。

始める前に

コンポーネントの表示方法に関する知識が役立つ場合があります。詳細は、4.7項「レンダリングおよび可視性の理解」を参照してください。

可視性を設定する手順:

1. 可視性を切り替えるJavaScriptを作成します。例4-18に、値がない場合にoutputTextコンポーネントの可視性を有効にし、そうでない場合は別のoutputTextコンポーネントの可視性を有効にするスクリプトを示します。

2. JavaScript関数で必要なコンポーネントごとに、「プロパティ」ウィンドウで「拡張」セクションを開き、ClientComponent属性をtrueに設定します。これによって、JavaScriptで使用されるクライアント・コンポーネントが作成されます。

3. 可視性を切り替えるコンポーネントのvisible属性をfalseに設定します。

例4-19に、JavaScriptを使用した可視性の切替えに使用されるページ・コード全体を示します。

例4-19 JavaScriptでの可視性の切替え

<f:view>
<af:resource>
function showText()
{
var output1 = AdfUIComponent.findComponent("output1")
var output2 = AdfUIComponent.findComponent("output2")
var input = AdfUIComponent.findComponent("input")

if (input.value == "")
{
output1.setVisible(true);
}
else
{
output2.setVisible(true)
}

}
</af:resource>
<af:document>
<af:form>
<af:panelGroupLayout layout="horizontal">
<af:inputText label="Input some text" id="input"
value="#{myBean.inputValue}" clientComponent="true"
immediate="true"/>
<af:button text="Enter" clientComponent="true">
<af:clientListener method="showText" type="action"/>
</af:button>
</af:panelGroupLayout>
<af:panelGroupLayout layout="horizontal">
<af:outputLabel value="You entered:" clientComponent="false"/>
<af:outputText value="No text entered" id="output1"
visible="false" clientComponent="true"/>
<af:outputText value="#{myBean.inputValue}" id="output2"
visible="false" clientComponent="true"/>
</af:panelGroupLayout>
</af:form>
</af:document>
</f:view>

4.7.2 VisibleとisShowing関数に関する必知事項

コンポーネントの親のvisible属性がfalseに設定されている場合、visible属性がtrueに設定されている子コンポーネントにisVisible関数が実行されると、子が表示されていなくてもtrueが返されます。たとえば、outputTextコンポーネントを子として含むpanelGroupLayoutコンポーネントがあり、panelGroupLayoutコンポーネントのvisible属性はfalseに設定され、outputTextコンポーネントのvisible属性はデフォルトのまま(true)とします。クライアントでは、panelGroupLayoutコンポーネントもoutputTextコンポーネントも表示されませんが、isVisible関数がoutputTextコンポーネントに実行されると、trueが返されます。

このため、フレームワークにはisShowing()関数が用意されています。この関数は、コンポーネントのvisible属性がfalseに設定されている場合、またはコンポーネントの親のvisibleがfalseに設定されている場合、falseを返します。

4.8 ページでのクライアント・コンポーネントの検索

イベントのソースではないクライアント・コンポーネントを検索する必要がある場合、AdfUIComponent.findComponent(expr)メソッドを使用できます。このメソッドはJSFのUIComponent.findComponent()メソッドと似ており、指定した検索式に合致するIDを使用してUIComponentオブジェクトを検索して返します。AdfUIComponent.findComponent(expr)メソッドは、サーバーではなくクライアントでのみ機能します。

例4-20に、コンポーネントのIDを使用してoutputTextコンポーネントを検索するsayHello関数を示します。

例4-20 findComponent()を使用したクライアント・コンポーネントの検索

function sayHello(actionEvent)
{
var buttonComponent=actionEvent.getSource();

//Find the client component for the "greeting" af:outputText
var greetingComponent=buttonComponent.findComponent("greeting");

//Set the value for the outputText component
greetingComponent.setValue("Hello World")
}

ADF Facesには、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドもあります。このメソッドは、IDの文字列をハードコーディングする場合に使用します。クライアントIDがコンポーネントから取得される場合は、AdfUIComponent.findComponent(expr)を使用します。

注意:

似たような名前のAdfPage.PAGE.findComponent(clientId)というメソッドもありますが、この関数は、リリース間で変わる可能性のある実装固有の識別子を使用し、ページ作成者は使用しません。

4.8.1 ネーミング・コンテナ内のコンポーネントの検索に関する必知事項

見つける必要があるコンポーネントがネーミング・コンテナ(pageTemplate、subform、tableおよびtreeなど)であるコンポーネントにある場合は、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドを使用するかわりに、AdfUIComponent.findComponent(expr)メソッドを使用します。絶対式も相対式も使用できます。

ヒント:

コンポーネントがネーミング・コンテナかどうかは、コンポーネント・タグのドキュメントを確認して判断できます。タグのドキュメントには、コンポーネントがネーミング・コンテナかどうかが示されています。

絶対式は次のように作成されます。

":" + (namingContainersToJumpUp * ":") + some ending portion of the clientIdOfComponentToFind

たとえば、myTemplateテンプレートを使用するページのID r1のリージョンに含まれるID pc1のパネル・コレクション・コンポーネント内にあるID t1の表を検索するには、次の文字列を使用できます。

:myTemplate:r1:pc1:t1

または、両方のコンポーネント(検索を実行するコンポーネントと検索されるコンポーネント)が同じNamingContainerコンポーネントを階層のどこかで共有する場合は、相対パスを使用して、検索を実行するコンポーネントとの相対で検索を実行できます。相対パスには、たとえば次のように、先頭に複数のNamingContainer.SEPARATOR_CHAR文字があります。

":" + clientIdOfComponentToFind

前述の例で、検索元のコンポーネントが表と同じリージョンにある場合、次を使用できます。

::somePanelCollection:someTable

ヒント:

ネーミング・コンテナをフォルダと考え、clientIdをファイル・パスと考えます。フォルダとファイルに関して、2つの連続ピリオドとスラッシュ(../)を使用して、階層内の上にフォルダに移動します。これは、複数のコロン(:)文字がfindComponent()式で果たす役割と同じです。先頭の単一のコロン(:)は、ファイル・パスが、ファイル構造のルートからの絶対パスであることを意味します。式の先頭に複数のコロン(:)文字がある場合、最初のコロンは無視され、他のコロンは考慮されます。コロン(:)文字当たり1セットのピリオドとスラッシュ(../)が考慮されます。

AdfPage.findComponentByAbsoluteId()メソッドを使用する場合、パスは常に絶対パスであるため、先頭のコロンは不要です。

絶対パスを使用するか相対パスを使用するかを決める際、次の点に注意します。

- 検索対象のコンポーネントが常に同じネーミング・コンテナ内あることがわかっている場合は、絶対パスを使用します。

- 検索元のコンポーネントと検索対象のコンポーネントの相対的位置が常に同じであることがわかっている場合は、相対パスを使用します。

クライアントにはgetChildren()関数もgetFacet()関数もありません。かわりに、すべての子コンポーネントとファセット(つまり、すべての子孫)にアクセスするAdfUIComponent.visitChildren()関数が用意されています。ADF Facesはスパース・コンポーネント・ツリー(クライアント・コンポーネントが必要に応じて作成されるツリー)であるため、getParent()メソッドがクライアントで返すコンポーネントは、サーバー上の実際の親ではない場合があります(先祖である可能性はあります)。同様に、クライアント上に直接の子として出現するコンポーネントは、任意の子孫である可能性があります。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

4.9 JavaScriptライブラリのパーティション化

JavaScriptを多用したフレームワークに共通する問題は、大規模なJavaScriptコード・ベースをクライアントに送信する最良の方法を決定することです。極端な方法は、すべてのコードを1つのJavaScriptライブラリにバンドリングすることで、この方法ではダウンロード時間が長くなります。逆の極端な方法はJavaScriptコードを多数の小さなJavaScriptライブラリに分割することで、この方法ではラウンドトリップ数が大きくなります。どちらの方法でも初期ページをロードするためのユーザーの待ち時間が不必要に長くなります。

この問題を軽減するために、ADF FacesではJavaScriptコードがパーティションに集約されます。JavaScriptライブラリ・パーティションには、コンポーネントのコードまたは通常一緒に使用される機能、あるいはその両方が含まれています。ADF Facesではデフォルトで、ダウンロード・サイズ合計とラウンドトリップ数合計のバランスをとることを意図したパーティション化が行われます。

ADF Facesのライブラリ・パーティション化方式の利点の1つは、構成可能であることです。アプリケーションによって使用するコンポーネントおよび機能が異なるため、ADF Facesのデフォルトのパーティション化がすべてのアプリケーションに最適であるとはかぎりません。このため、ADF FacesのJavaScriptライブラリのパーティション化はアプリケーションごとにカスタマイズ可能になっています。このパーティション化により、アプリケーション開発者はJavaScriptライブラリのフットプリントをアプリケーションの要件に合せて調整できます。

ADF Facesは、そのコンポーネントのJavaScriptファイルをJavaScript機能にグループ化します。JavaScript機能は、その機能を記述する論理識別子に関連付けられたJavaScriptファイルのコレクションです。たとえば、panelStretchLayoutクライアント・コンポーネントは、次の2つのJavaScriptファイルで構成されます。

- oracle/adf/view/js/component/rich/layout/
AdfRichPanelStretchLayout.js

- oracle/adfinternal/view/js/laf/dhtml/rich/
AdfDhtmlPanelStretchLayoutPeer.js

これらの2つのファイルは、AdfRichPanelStretchLayout機能にグループ化されます。

JavaScriptの機能は、JavaScriptパーティションにグループ化されます。JavaScriptパーティションでは、ダウンロード・サイズとラウンドトリップ数に影響を与えることを目標に、JavaScript機能をより大きなコレクションにグループ化できます。たとえば、panelStretchLayoutコンポーネントはpanelSplitterコンポーネントで使用されることが多く、この2つのコンポーネントの機能は、子を拡大できる他のADF Facesレイアウト・コンポーネントとともにストレッチ・パーティションにグループ化されます。実行時に、ページがロードされると、フレームワークはページで使用されるコンポーネントを決定し、必要な機能をそこから判断します(機能名は、コンポーネントのコンストラクタ名と同じです)。これらの機能を含むパーティションのみダウンロードされます。

機能およびパーティションは、構成ファイルを使用して定義されます。ADF Facesには、デフォルトの機能およびパーティション構成ファイルが含まれています。独自の実装を作成することでデフォルトのパーティションを上書きできます。カスタムADF Facesコンポーネントを作成する場合、これらのコンポーネントに独自の機能およびパーティション構成ファイルを作成できます。

デフォルトでJavaScriptのパーティション化は有効にされています。アプリケーションでJavaScriptのパーティション化を使用するかどうかは、web.xmlファイルのコンテキスト・パラメータによって決定されます。詳細は、A.2.3.17項「JavaScriptのパーティション化」を参照してください。

4.9.1 JavaScript機能の作成方法

adf-js-features.xmlファイルを作成してから機能にエントリを追加することでJavaScript機能を作成できます。

注意:

カスタムADF Facesコンポーネントを作成する場合に、JavaScript機能を作成できます。すべての既存のADF Facesコンポーネントには、すでにそれらのコンポーネント向けに作成された機能があり、これらは変更できません。

始める前に

JavaScriptのパーティション化の動作に関する知識が役立つ場合があります。詳細は、4.9項「JavaScriptライブラリのパーティション化」を参照してください。

コンポーネント用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

JavaScript機能を作成する手順:

1. 「アプリケーション」ウィンドウで、「META-INF」を右クリックして「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

3. 「XMLファイルの作成」ダイアログで、ファイル名をadf-js-features.xmlとしてMETA-INFディレクトリに保存します。

4. ソース・エディタで、生成されたコードを例4-21のコードに置き換えます。

例4-21 adf-js-features.xmlファイルのXML

<?xml version="1.0" encoding="utf-8" ?>
<adf-js-features xmlns="http://xmlns.oracle.com/adf/faces/feature">

</adf-js-features>

5. 次の要素を追加すると、関連するコンポーネント・ファイルおよび依存性とともに機能が移入されます。

- features: 構成ファイルのルート要素です。

- feature: features要素の子として作成されます。この要素には1つのfeature-name子要素が含まれている必要があり、feature-class要素およびfeature-dependency要素はいくつでも含めることができます。

- feature-name: feature要素の子として作成されます。機能の名前を指定します。この値にはクライアント・コンポーネントのコンストラクタ名を使用する必要があります。

- feature-class: feature要素の子として作成されます。この機能に含める1つのJavaScriptファイルまたはクラスの場所を指定します。複数のfeature-class要素がある場合もあります。

- feature-dependency: feature要素の子として作成されます。この機能が依存する別の機能の名前を指定します。たとえば、コンポーネントBでコンポーネントAを拡張する場合、コンポーネントAを示す機能はコンポーネントBへの依存性としてリストされている必要があります。依存性を記述することで、フレームワークは2つの機能が同じパーティションになくても、依存するクラスが使用できることを確認できます。

例4-22に、ポップアップ・コンポーネントを使用し、ポップアップ機能への依存性を持つ架空のカスタム・コンポーネントのfeature要素を示します。

例4-22 JavaScript機能の構成

<features xmlns="http://xmlns.oracle.com/adf/faces/feature">
<feature>
<feature-name>AcmeMyPane</feature-name>
<feature-class>
oracle/adfdemo/acme/js/component/AcmeMyPane.js
</feature-class>
<feature-class>
oracle/adfdemo/acme/js/event/AcmePaneSelectEvent.js
</feature-class>
<feature-class>
oracle/adfdemo/acme/js/component/AcmeMyPanePeer.js
</feature-class>

<!-- Dependencies -->

<!-- Popup hints -->
<feature-dependency>AdfRichPopup</feature-dependency>

</feature>

4.9.2 JavaScriptパーティションの作成方法

adf-js-partitions.xmlファイルを作成してから機能にエントリを追加することでJavaScriptパーティションを作成できます。

注意:

ADF Facesには、デフォルトのadf-js-partitions.xmlファイルがあります(第F.1.1項「adf-js-partitions.xmlファイル」を参照)。パーティションの構成を変更する場合は、独自の完全なadf-js-partitions.xmlファイルを作成する必要があります。実行時にフレームワークは、そのファイルのWEB-INFディレクトリを検索します。見つからない場合は、デフォルトのパーティション・ファイルがロードされます。

始める前に

JavaScriptのパーティション化の動作に関する知識が役立つ場合があります。詳細は、4.9項「JavaScriptライブラリのパーティション化」を参照してください。

JavaScriptパーティションを作成する手順:

1. 「アプリケーション」ウィンドウで、「WEB-INF」を右クリックして「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

3. 「XMLファイルの作成」ダイアログで、ファイル名をadf-js-partitions.xmlとしてWEB-INFディレクトリに保存します。

4. ソース・エディタで、生成されたコードを例4-23のコードに置き換えます。

例4-23 adf-js-partitions.xmlファイルのXML

<?xml version="1.0" encoding="utf-8" ?>
<partitions xmlns="http://xmlns.oracle.com/adf/faces/partition">

</partitions>

5. 次の要素を追加すると、関連する機能とともにパーティションが移入されます。

- partitions: 構成ファイルのルート要素です。

- partition: partitions要素の子として作成されます。この要素には1つのpartition-name子要素および1つ以上のfeature要素が含まれている必要があります。

- partition-name: partition要素の子として作成されます。パーティションの名前を指定します。この値は、このパーティションのJavaScriptライブラリに一意のURLを作成するために使用されます。

- feature: partition要素の子として作成されます。このパーティションに含める機能を指定します。複数のfeature要素がある場合もあります。

ヒント:

adf-js-features.xmlファイルで構成され、パーティションに表示されない機能は、独自のパーティションに存在するものとして扱われます。

例4-24に、AdfRichTree機能およびAdfRichTreeTable機能を含むtreeパーティションのpartition要素を示します。

例4-24 JavaScriptパーティションの構成

<partition>
<partition-name>tree</partition-name>
<feature>AdfUITree</feature>
<feature>AdfUITreeTable</feature>
<feature>AdfRichTree</feature>
<feature>AdfRichTreeTable</feature>
</partition>

4.9.3 実行時の処理: JavaScriptのパーティション化

ADF Facesによって、アプリケーションの初期化時にライブラリのパーティション構成ファイルがロードされます。まず、ADF Facesによって、META-INFディレクトリのすべてのadf-js-features.xmlファイルが検索され、見つかったすべてのファイルがロードされます(ADF Facesのデフォルトの機能構成ファイルを含む)。

パーティション構成ファイルについては、ADF FacesはWEB-INFディレクトリでadf-js-partitions.xmlという名前の1つのファイルを検索します。このファイルが見つからない場合は、ADF Facesのデフォルトのパーティション構成が使用されます。

レンダリング・トラバース中、ADF Facesはページによって必要とされるJavaScript機能に関する情報を収集します。トラバース終了時に(レンダリングされた)ページ・コンテンツによって必要とされるJavaScript機能の包括的なセットが認識されます。必要とされるJavaScript機能のセットが認識されると、ADF Facesはパーティション構成ファイルを使用して、この機能セットを必要とされるパーティションのセットにマップします。必要とされるパーティションのセットを使用して、これらのパーティションへのHTML <script>参照は、HTMLドキュメントの末尾直前でレンダリングされます。

5 ADF FacesでのJSFライフサイクルの使用

この章では、JSFページ・リクエストのライフサイクルとADF Facesからライフサイクルへの追加、およびアプリケーションでのライフサイクル・プロパティの使用方法について説明します。

この章では、次の項目について説明します。

- 5.1項「JSFライフサイクルとADF Facesの使用について」

- 5.2項「immediate属性の使用」

- 5.3項「最適化されたライフサイクルの使用」

- 5.4項「クライアント側ライフサイクルの使用」

- 5.5項「サブフォームを使用したページでのセクションの作成」

- 5.6項「オブジェクト・スコープ・ライフサイクル」

- 5.7項「ページ間の値の受渡し」

5.1 JSFライフサイクルとADF Facesの使用について

ADF Facesアプリケーションでは、JSFライフサイクルとADF Facesライフサイクルの両方が使用されます。ただし、ADF FacesライフサイクルではJSFライフサイクルが拡張され、クライアント側の値のライフサイクル、1つのページに複数のフォームを使用する弊害(ユーザーの編集内容の消失など)なしに独立して送信可能なセクションをページに作成できるサブフォーム・コンポーネント、追加スコープなどの追加機能を提供します。

フレームワークによって提供されるライフサイクルの強化についてよりよく理解するには、標準のJSFライフサイクルについて理解することが重要です。この項の説明は概要にすぎません。詳細な説明は、http://www.jcp.org/en/jsr/detail?id=314にあるJSFの仕様を参照してください。

JSFページが送信され、新しいページがリクエストされると、JSFページ・リクエスト・ライフサイクルが起動されます。このライフサイクルでは、ページの値の送信、現在のページのコンポーネントの検証、コンポーネントのナビゲーションと結果ページへの表示および状態の保存とリストアが処理されます。FacesServletオブジェクトで、JSFアプリケーションのページ・リクエスト・ライフサイクルが管理されます。FacesServletオブジェクトで、リクエスト処理に必要な情報を含み、ライフサイクルを実行するオブジェクトを起動するFacesContextと呼ばれるオブジェクトが作成されます。

JSFライフサイクル・フェーズでは、UIコンポーネント・ツリーを使用してfacesコンポーネントの表示を管理します。このツリーはJSFページのランタイム表現で、ページ内の各UIコンポーネント・タグがツリーのUIコンポーネント・インスタンスに対応します。

図5-1に、ページ・リクエストのJSFライフサイクルを示します。ここに示すとおり、各フェーズの前後でイベントが処理されます。

図5-1 ADF Facesアプリケーションでのページ・リクエストのライフサイクル

JSFアプリケーションでは、ページ・リクエスト・ライフサイクルは次のようになります。

- ビューのリストア:コンポーネント・ツリーが構築されます。これが初めてのレンダリングでない場合(ページがサーバーに送り返された場合)、適切な状態でツリーがリストアされます。これが初めてのレンダリングの場合、コンポーネント・ツリーが作成され、レスポンスのレンダリング・フェーズに移ります。

- リクエスト値の適用: ツリーの各コンポーネントでリクエスト・パラメータから新規の値が(decodeメソッドを使用して)抽出され、ローカルに格納されます。関連付けられているほとんどのイベントは、後の処理のためにキューされます。コンポーネントのimmediate属性がtrueに設定されている場合、検証、変換およびコンポーネントに関連付けられているイベントがこのフェーズで処理されます。詳細は、5.2項「immediate属性の使用」を参照してください。

- 検証の処理: コンポーネントのローカル値が、入力タイプから基礎のデータ型に変換されます。コンバータが失敗した場合、このフェーズが続行されて完了します(残りのすべてのコンバータ、バリデータおよび必要なチェックが実行されます)が、完了時にライフサイクルがレスポンスのレンダリング・フェーズに移ります。
失敗がない場合、コンポーネントのrequired属性が確認されます。値がtrueで、関連付けられているフィールドに値が含まれている場合、関連付けられているバリデータが実行されます。値がtrueで、フィールド値がない場合、このフェーズは完了します(残りのすべてのバリデータが実行されます)が、ライフサイクルがレスポンスのレンダリング・フェーズに移ります。値がfalseの場合、値が入力されていないかぎり(この場合は検証が実行されない)、フェーズが完了します。変換と検証の詳細は、第7章「入力の検証および変換」を参照してください。

このフェーズの最後に、変換後のローカル値が設定され、検証および変換のエラー・メッセージとイベントがFacesContextにキューイングされ、値変更イベントが配信されます。

ヒント:

要約すると、編集可能な入力コンポーネントの検証の処理フェーズでの手順は次のとおりです。

1. コンバータが失敗した場合、必要なチェックとバリデータが実行されません。

2. コンバータは成功したが、必要なチェックが失敗した場合、バリデータが実行されません。

3. コンバータと必要なチェックが成功した場合、すべてのバリデータが実行されます。1つのバリデータが失敗した場合でも、残りのバリデータは実行されます。これは、ユーザーがエラーを修正する際に使用できる、入力されたデータの問題点を可能なかぎりフィードバックするためです。
たとえば、2015年の日付のみを受け入れるdateTimeRangeバリデータがあり、ユーザーが日曜日を選択できないdateRestrictionValidatorバリデータがあるとします。ユーザーがNovember 16, 2014(日曜日)と入力した場合、両方のバリデータが失敗することをフィードバックし、ユーザーが有効な日付を入力する可能性を最大限にします。

- モデル値の更新: 検証されたコンポーネントのローカル値がモデルに移動され、ローカル・コピーが破棄されます。

- アプリケーションの起動: アプリケーション・レベルのロジック(イベント・ハンドラなど)が実行されます。

- レスポンスのレンダリング: ツリー内のコンポーネントがレンダリングされます。後続のリクエストおよびビューのリストア・フェーズ用に状態情報が保存されます。

ライフサイクルの説明の一環として、ユーザーが日付を入力し、ボタンをクリックして入力値を送信する単純な入力テキスト・コンポーネントを持つページを考えてみます。valueChangeListenerメソッドもコンポーネントに登録されています。例5-1に、この例のコードを示します。

例5-1 JSFライフサイクルを説明するためのサンプル・コード

<af:form>
<af:inputText value="#{mybean.date}"
valueChangeListener="#{mybean.valueChangeListener}">
<af:convertDateTime dateStyle="long"/>
</af:inputText>
<af:button text="Save"  actionListener="#{mybean.actionListener}"/>
</af:form>

ユーザーが文字列「June 25, 2015」を入力し、送信ボタンをクリックするとします。図5-2に、値がライフサイクルでどのように受け渡され、各イベントがどの時点で処理されるかを示します。

図5-2 JSFライフサイクルでの値とイベントの例

5.2 immediate属性の使用

immediate属性を使用して、ライフサイクルのリクエスト値の適用フェーズまでコンポーネントの処理を進めることができます。actionSourceコンポーネント(buttonなど)がimmediateに設定されている場合、イベントはアプリケーションの起動フェーズではなくリクエスト値の適用フェーズで配信されます。actionListenerハンドラは、レスポンスのレンダリング・フェーズをコールします。

たとえば、「取消」ボタンをimmediateに構成し、アクションが前のページに戻るために使用される文字列を返すようにする場合があります(ナビゲーションの詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください)。「取消」ボタンはimmediateに設定されているため、ユーザーが「取消」ボタンをクリックすると、図5-3に示すように、すべての検証がスキップされ、入力されたデータはモデルに更新されず、ユーザーは期待どおりにナビゲートします。

図5-3 immediateに設定されたボタンのライフサイクル

注意:

ナビゲーションを提供せず、immediateに設定されているボタンは、レスポンスのレンダリング・フェーズに直接進み、検証、モデルの更新、アプリケーションの起動のフェーズは省略され、新しい値はサーバーにプッシュされません。

表示イベントを呼び出すコンポーネント(showDetailコンポーネントなど)やeditableValueHolderコンポーネント(inputTextコンポーネントなど、変更可能な値を保持するコンポーネント)もimmediateに設定できます。actionSourceコンポーネントと同様に、イベントはリクエスト値の適用フェーズに配信されます。一方、editableValueHolderコンポーネントでは、フェーズをスキップするかわりに、valueChangeEventsイベントの変換、検証および配信が、検証の処理フェーズではなく、ライフサイクル初期のリクエスト値の適用フェーズで実行されます。スキップされるライフサイクル・フェーズはありません。

図5-4に、immediate属性がtrueに設定されている入力コンポーネントのライフサイクルを示します。入力コンポーネントは文字列として入力された日付を取得し、ボタンがクリックされたときにDateオブジェクトとしてその日付を格納します。

図5-4 入力コンポーネントのimmediate属性

入力コンポーネントのimmediate属性をtrueを設定すると、1つ以上の入力コンポーネントをその他のコンポーネントより前に検証する必要がある場合に役立ちます。これらのコンポーネントの1つで無効なデータが検出されると、同じページの他の入力コンポーネントの検証が省略されるため、ページに表示されるエラー・メッセージの数が削減されます。

パフォーマンスのヒント:

immediate属性をtrueに設定すると、パフォーマンスが向上する場合があります。

- ナビゲーション・トレインを作成し、navigationPaneコンポーネント内にcommandNavigationItemコンポーネントがある場合、immediate属性をtrueに設定して、次のページへの移動時に、現在のページ(トレイン・ストップ)からのデータの処理を回避します。詳細は、20.9.1項「トレイン・モデルの作成方法」を参照してください。

- 他の値の前に入力コンポーネント値を検証する必要がある場合、immediate属性をtrueに設定します。ライフサイクルの早い段階でエラーが検出され、その他の処理が行われずに済みます。

別の例として、あるフォームに、検索の実行を起動するように構成されているボタンを使用して文字列の検索に使用される入力コンポーネント、および日付の送信に使用される関連付けられたボタンを使用して日付の入力に使用される別の入力テキスト・コンポーネントが設定されているとします。この例では、検索入力コンポーネントとボタンの両方をimmediateに設定します。これにより、無効な文字列が日付フィールドに入力された場合でも、日付入力コンポーネントのコンバータが起動されないため、ユーザーは検索を実行できます。また、検索入力テキストはimmediateに設定され、日付入力フィールドは設定されないため、検索入力テキストのみ処理されます。両方のフィールドは同じフォーム内にあるため、ユーザーが日付フィールドに有効な日付を入力し、その後、検索を実行して「保存」ボタンをクリックしない場合、検索結果が表示されるときに、入力した値が引き続き表示されます。例5-2に、2つのフィールドと2つのボタンに使用されるコードを示します。

例5-2 immediateを使用する入力コンポーネントとコマンド・コンポーネント

<af:form>
<af:inputText immediate="true" label="Search"  value="#{mybean.search}"
valueChangeListener="#{mybean.searchValueChangeListener}"/>
<af:button immediate="true" text="search"
actionListener="#{mybean.searchActionListener}"/>
[.... tags to render search result ....]

<af:inputText label="Date" value="#{mybean.date}"
valueChangeListener="#{mybean.valueChangeListener}">
<af:convertDateTime dateStyle="long"/>
</af:inputText>
<af:button text="save"  actionListener="#{mybean.actionListener}"/>
</af:form>

図5-5に、ユーザーが次のことを行う場合のこのページのライフサイクルを示します。

- appleを「日付」入力フィールドに入力する(これは有効なエントリではありません)。

- orangeを「検索」フィールドに入力する。

- 「検索」ボタンをクリックして、orangeの検索を実行する。

- 「保存」ボタンをクリックして値appleを日付として入力します。

図5-5 コマンド・コンポーネントと入力コンポーネント両方のimmediate属性

同じページのeditableValueHolderおよびactionSourceコンポーネントにimmediate属性を使用する場合、次の点に注意する必要があります。

- actionSourceコンポーネントがeditableValueHolderコンポーネントからのデータを必要とする場合、そのデータはモデル値の更新フェーズが終了するまで入手できません。immediateなactionSourceコンポーネントがあり、このコンポーネントでデータが必要な場合、editableValueHolderフィールドのimmediateも設定します。こうすることで、editableValueHolderコンポーネントのgetValueメソッドをコールでき、ローカル値が返されます。モデルにはまだプッシュされていませんが、コンポーネントで使用できます。

- immediateなeditableValueHolderコンポーネントが検証に失敗した場合でも、immediateなactionSourceコンポーネントは実行されます。

5.2.1 immediate属性の使用方法

始める前に

immediate属性に関する知識が役立つ場合があります。詳細は、5.2項「immediate属性の使用」を参照してください。

immediate属性を使用する手順:

1. JSFページで、immediateにするコンポーネントを選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを開き、immediate属性をtrueに設定します。

5.3 最適化されたライフサイクルの使用

ADF Facesには、ページの特定のコンポーネントにのみJSFページ・リクエスト・ライフサイクル(変換と検証を含む)を実行する最適化されたライフサイクルが用意されています。この部分ページ・ライフサイクルは、部分ページ・レンダリング(PPR)と呼ばれます。特定のADF Facesコンポーネントはイベント・ルート・コンポーネントとして見なされ、最適化されたライフサイクルが実行される境界を決定します。イベント・ルート・コンポーネントは、2通りの方法で決定できます。

- コンポーネント: 特定のコンポーネントが常にイベント・ルート・コンポーネントになります。領域とポップアップは、フレームワークが境界として認識しているコンポーネントの例です。リージョンまたはポップアップの内部でトリガーされるイベントに関係なく、ライフサイクルはリージョンまたはポップアップの外部のコンポーネントでは実行されません。

- イベント: 特定のイベントはルートであるコンポーネントを示します。たとえば、showDetailコンポーネントを展開または縮小する(9.9項「コンテンツの動的な表示および非表示」を参照)と送信される表示イベントは、showDetailコンポーネントがルートであることを示すため、ライフサイクルはshowDetailコンポーネントと任意の子コンポーネントでのみ実行されます。対応するイベント・ルート・コンポーネントを持つイベントのリストは、6.1.1項「イベントおよび部分ページ・レンダリング」の表6-1を参照してください。

イベント・ルートで実行されているコンポーネントおよびその子コンポーネントとは別に、イベント・ルート階層外部の他のコンポーネントを最適化されたライフサイクルに参加するように宣言して構成できます。コンポーネントの特定のイベントに限って最適化されたライフサイクルをトリガーさせたり、実際に実行されるコンポーネントと単にリフレッシュされるだけのコンポーネントを設定することもできます。

ADF FacesフレームワークでのPPRの使用方法とアプリケーションでのPPRの使用方法の詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

5.4 クライアント側ライフサイクルの使用

ADF Facesフレームワークは、クライアント側変換および検証を提供します。サーバーにアクセスせずにページで実行できる独自のJavaScriptベースのコンバータおよびバリデータを作成できます。

クライアント側検証を使用して、特定のクライアント・イベントがキューに入れられたときに、適切なフォームまたはサブフォームのクライアント検証をトリガーできます(サブフォームの詳細は、5.5項「サブフォームを使用したページでのセクションの作成」を参照してください)。このクライアント検証が失敗し、既知のエラーがあることがわかった場合は、通常サーバーに伝播するイベント(たとえば、フォームが送信されたときのボタンのactionEvent)はサーバーに移動しません。イベントが配信されないということは、なにも送信されないということでもあり、クライアント・リスナーはコールされません。これは、サーバーで検証が失敗した場合にライフサイクルがレスポンスのレンダリング・フェーズにジャンプするサーバー側検証に似ています。アクション・イベントはキューに入れられますが、決して配信されず、actionListenerハンドラ・メソッドは決してコールされません。

たとえば、ADF Facesで入力コンポーネントにrequired属性を用意し、この検証がクライアントで実行されるとします。この属性をtrueに設定すると、コンポーネントの値がnullの場合、フレームワークでページにエラーが表示され、サーバーへの送信は必要ありません。例5-3に、inputTextコンポーネントのrequired属性をtrueに設定し、actionListener属性がマネージドBeanのメソッドにバインドされているボタンを含むコードを示します。

例5-3 簡単なクライアント側検証の例

<af:form>
<af:inputText id="input1" required="true" value="a"/>
<af:button text="Search" actionListener="#{demoForm.search}"/>
</af:form>

このページを実行した場合、inputTextコンポーネントの値のフィールドをクリアし、フィールドからタブ移動すると、フィールドが赤い縁取りで再表示されます。フィールドをクリックすると、図5-6に示すように、値が必要なことを示すエラー・メッセージが表示されます。サーバーへの送信はなく、エラーの検出とメッセージの生成はすべてクライアントで行われます。

図5-6 クライアント側検証でサーバーへの送信なしにエラーを表示

この例で、値のフィールドをクリアし、「検索」ボタンをクリックした場合、必須フィールドが空でありエラーが発生するため、ページは送信されません。アクション・イベントは配信されず、アクション・リスナーにバインドされたメソッドは実行されません。サーバーで検証が失敗したことをクライアントが通知できる場合はページを送信する理由がないため、このプロセスは適切です。

クライアント側の検証と変換の詳細は、第7章「入力の検証および変換」を参照してください。

5.5 サブフォームを使用したページでのセクションの作成

JSF参照実装では、ページのセクションを別個に送信する場合、複数のフォームを使用する必要があります。ただし、複数のフォームにはページの状態の複数のコピーが必要なため、送信されないフォームでのユーザーの編集内容が失われる可能性があります。

ADF Facesには、別個に送信可能なページのセクションを示すサブフォーム・コンポーネントのサポートが追加されています。サブフォームのコンテンツは、サブフォーム内部のコンポーネントがページの送信に関与する場合にのみ検証(または処理)されるため、まったく別のフォーム要素を使用するという妥協をすることなく、検証されてモデルへプッシュされるコンポーネントのセットを比較的きめ細かく制御できます。サブフォームを使用するページの送信時に、ページの状態が一度だけ書き込まれ、すべてのユーザー編集内容が保持されます。

ベスト・プラクティス:

常にページごとに1つのみのformタグを使用します。複数のformタグを使用する必要がある場合は、subformタグを使用します。

サブフォームでは、ページがそのサブフォーム外のコンポーネントによって送信された場合でも、リクエスト値の適用フェーズでその子コンポーネントを常に実行できます。ただし、検証の処理フェーズとモデル値の更新フェーズはスキップされます(これは、送信されない場合はリクエスト値の適用フェーズを実行できない通常のフォーム・コンポーネントとは異なります)。サブフォーム外のコンポーネントが送信アクションの原因となった場合にサブフォーム内のコンポーネントを検証の処理フェーズとモデル値の更新フェーズで処理できるようにするには、default属性を使用します。サブフォームのdefault属性をtrueに設定すると、そのサブフォームはほとんどの点で他のサブフォームと同様に動作しますが、ページのどのサブフォームにもその子コンポーネントからの適切なイベントがない場合、defaultがtrueに設定されたサブフォームは、その子コンポーネントの1つが送信の原因となったかのように動作します。サブフォームの詳細は、11.2項「formの定義」を参照してください。

5.6 オブジェクト・スコープ・ライフサイクル

実行時、ページがデータにアクセスできるオブジェクト・スコープに必要なデータを格納することで、データをページに渡します。スコープによってオブジェクトの存続期間が決まります。オブジェクトをスコープに置くと、EL式を使用してスコープからアクセスできます。たとえば、fooという名前のマネージドBeanを作成し、Beanをリクエスト・スコープに存続させるよう定義するとします。このBeanにアクセスするには、#{requestScope.foo}という式を使用します。

標準JSFアプリケーションには、次の5種類のスコープがあります。

- applicationScope: オブジェクトは、アプリケーションの間使用できます。

- sessionScope: オブジェクトは、セッションの間使用できます。

- viewScope: オブジェクトは、ユーザーが現在のビューとの対話を終了するまで使用可能です。オブジェクトはUIViewRootオブジェクトのマップに格納されます。このオブジェクトは、ページがリフレッシュされるかビューにリダイレクトされると空になります。

ヒント:

ページのリフレッシュまたは同じビューへのリダイレクト後もオブジェクトを残す必要がある場合は、ADF FacesバージョンのviewScopeを使用します。

- flashScope: オブジェクトは、単一のビュー遷移中に使用可能で、次のビューに移動する前にクリアされます。flashScopeにパラメータ値を配置し、結果のページで使用可能にし、リダイレクト後も残すことができます。

- requestScope: オブジェクトは、HTTPリクエストが送信されてから、レスポンスがクライアントに返るまでの間使用できます。

標準JSFスコープに加え、ADF Facesには次のスコープが用意されています。

- pageFlowScope: オブジェクトは、ユーザーがあるページから別のページへのナビゲートを続けるかぎり使用できます。ユーザーが新たなブラウザ・ウィンドウを開いてナビゲートを始めた場合、そのウィンドウで別のpageFlowScopeスコープを持ちます。

- backingBeanScope: ページ・フラグメントと宣言コンポーネントのみに対するマネージドBeanに使用します。オブジェクトは、HTTPリクエストが送信されてから、レスポンスがクライアントに返るまでの間使用できます。このスコープは、複数のページ・フラグメントと宣言コンポーネントがページにある場合があり、値の競合を避けるために別々のスコープ・インスタンスに値を保持するために必要です。ページ・フラグメントまたは宣言コンポーネントに対して作成されるマネージドBeanには、backingBeanScopeスコープを使用します。

- viewScope: オブジェクトは、現在のビューのIDが変更されるまで使用できます。viewScopeスコープを使用して特定のページの値を保持します。JSF viewScopeとは異なり、ADF FacesのviewScopeに格納されるオブジェクトは、ページのリフレッシュや同じビューIDへのリダイレクト後も残ります。

注意:

これらは標準JSFスコープではないため、EL式には、Beanを参照するためのスコープを明示的に含める必要があります。たとえば、pageFlowScopeスコープからMyBeanマネージドBeanを参照するには、#{pageFlowScope.MyBean}という式になります。

オブジェクト・スコープは、プログラミング言語のグローバル変数およびローカル変数のスコープに相当します。スコープが広いほど、オブジェクトの可用性が高くなります。存続期間の間、これらのオブジェクトで特定のインタフェースの公開、情報の保持および他のオブジェクトへの変数とパラメータの受渡しを行うことができます。たとえば、sessionScopeスコープに定義されているマネージドBeanは、複数のページ・リクエストの間使用できます。しかし、requestScopeスコープに定義されているマネージドBeanは、1つのページ・リクエストの間のみ使用できます。

図5-7に、各タイプのスコープが有効な期間およびページ・フローとの関係を示します。

図5-7 スコープとページ・フローの関係

マネージドBeanを登録するスコープまたは値を格納するスコープを決める場合、可能なかぎり狭いスコープを常に使用するようにします。sessionScopeスコープは、ユーザー情報やコンテキスト情報などのセッション全体に関係する情報にのみ使用します。あるページから別のページへの値の受渡しには、sessionScopeスコープは使用しないようにします。

注意:

フルFusionテクノロジ・スタックを使用している場合、様々な構成ファイルにマネージドBeanを登録するためのオプションがあります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のFusion WebアプリケーションでのマネージドBeanの使用に関する項を参照してください。

5.7 ページ間の値の受渡し

注意:

完全なFusionテクノロジ・スタックを使用していて、ADFバインド・タスク・フローのページ間またはADFリージョンとページの間での値の受渡しについての情報が必要な場合は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFタスク・フローの概説」の章を参照してください。

ADF FacesのpageFlowScopeスコープは、ページ間での値の受渡しを容易にするため、マスター/ディテール・ページを簡単に開発できます。pageFlowScopeスコープに追加された値は、redirectディレクティブを使用する場合でも、ユーザーがページ間を移動する際に自動的に継続使用できます。ただし、sessionスコープとは異なり、これらの値を表示できるのは、現在のページ・フローまたはプロセス内のみです。ユーザーが新たなウィンドウを開いてナビゲートを始めた場合、そのウィンドウは固有のプロセスを持ちます。各ウィンドウに格納された値は独立したままです。

標準JSFスコープに格納されているオブジェクト同様、pageFlowスコープに格納されているオブジェクトもEL式を介してアクセスできます。pageFlowスコープとの唯一の違いは、オブジェクト名にpageFlowScope接頭辞を使用する必要があることです。たとえば、ボタンのラベルをpageFlowスコープに格納されているマネージドBeanで指定し、ボタンが選択されるとBeanのメソッドがコールされるようにする場合は、ページに次のコードを使用します。

<af:button text="#{pageFlowScope.buttonBean.label}"
action="#{pageFlowScope.buttonBean.action}"/>

pageFlowScopeは、Javaコードからアクセスできるjava.util.Mapオブジェクトです。setPropertyListenerタグでは、スコープにプロパティ値を設定でき、タグでリスニングするイベントを定義することもできます。たとえば、type属性をactionに設定したsetPropertyListenerタグを使用すると、ナビゲーション前にアクション・ソース(buttonなど)で値を設定する宣言的方法が提供されます。pageFlowScopeスコープとsetPropertyListenerタグを併用して、バッキングBeanにJavaコードを記述せずに、ページ間で値を受渡しできます。たとえば、setPropertyListenerタグとコマンド・コンポーネントを使用してpageFlowScopeスコープに値を設定するページと、テキスト・コンポーネントでpageFlowScopeスコープを使用して値を取得する別のページがある場合があります。

pageFlowScopeスコープを使用して、ダイアログなどの2つ目のウィンドウ間で値を設定することもできます。buttonコンポーネントなどから2つ目のウィンドウを起動する場合、launchEventイベントおよびpageFlowScopeスコープを使用して、親プロセスの値をオーバーライドせずに2つ目のウィンドウとの間で値を受け渡すことができます。

5.7.1 Javaコード内でのpageFlowScopeスコープの使用方法

pageFlowスコープは、アプリケーションのJavaコード内からアクセスできます。終了したら、スコープを必ずクリアしてください。

注意:

アプリケーションでADFコントローラが使用されている場合は、スコープを手動でクリアする必要はありません。

始める前に

オブジェクト・スコープに関する知識が役立つ場合があります。詳細は、5.6項「オブジェクト・スコープ・ライフサイクル」を参照してください。pageFlowスコープを使用して値を渡す方法も理解しておく必要があります。詳細は、5.7項「ページ間の値の受渡し」を参照してください。

JavaコードでpageFlowScopeを使用する手順:

1. pageFlowScopeスコープへの参照を得るために、org.apache.myfaces.trinidad.context.RequestContext.
getPageFlowScope()メソッドを使用します。
たとえば、pageFlowScopeスコープからオブジェクトを取得するには、次のJavaコードを使用します。

import java.util.Map;
import org.apache.myfaces.trinidad.context.RequestContext;
. . .
Map pageFlowScope = RequestContext.getCurrentInstance().getPageFlowScope();
Object myObject = pageFlowScope.get("myObjectName");

2. pageFlowScopeスコープをクリアするには、スコープにアクセスしてから手動でクリアします。
たとえば、次のJavaコードを使用してスコープをクリアします。

RequestContext afContext = RequestContext.getCurrentInstance();
afContext.getPageFlowScope().clear();

5.7.2 Javaコードを記述せずにpageFlowScopeスコープを使用する方法

Javaコードを記述せずにpageFlowScopeスコープを使用するには、setPropertyListenerタグとコマンド・コンポーネントを組み合せて使用し、スコープに値を設定します。setPropertyListenerタグでは、リスニングするイベント・タイプを定義するtype属性を使用します。このタイプに合致しないイベントはすべて無視されます。設定後は、ページ・フロー内の別のページからその値にアクセスできます。

ヒント:

(以前のバージョンのADF Facesで使用されていた可能性がある)setActionListenerタグを使用するかわりに、setPropertyListenerタグを使用し、イベント・タイプをactionに設定します。

pageFlowScopeスコープに値を設定する手順:

1. 値を設定するページ上で、「コンポーネント」ウィンドウを使用してコマンド・コンポーネントを作成します。コマンド・コンポーネントの作成方法は、20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

2. 「コンポーネント」ウィンドウで、「操作」パネルの「リスナー」グループから、「プロパティ・リスナーの設定」をドラッグしてコマンド・コンポーネントに子としてドロップします。
または、コンポーネントを右クリックし、「ボタンの中に挿入」→「ADF Faces」→「setPropertyListener」の順に選択します。

3. 「プロパティ・リスナーの設定の挿入」ダイアログで、「自」フィールドに別のコンポーネントに設定される値を設定します。
たとえば、従業員の名前を格納するMyBeanという名前のマネージドBeanがあり、次のページに値を受け渡すとします。「自」フィールドに#{myBean.empName}と入力します。

4. 「至」フィールドにpageFlowScopeスコープでの値を設定します。

たとえば、「至」フィールドに#{pageFlowScope.empName}と入力します。

5. 「タイプ」ドロップダウン・メニューから、「アクション」を選択します。
これによって、リスナーで、コマンド・コンポーネントに関連付けられているアクション・イベントをリスニングできます。

pageFlowScopeスコープから値にアクセスする手順:

1. 値のアクセス元のページに、値を表示するコンポーネントをドロップします。

2. コンポーネントの値を、setPropertyListenerタグで設定したTo値と同じ値に設定します。
たとえば、outputTextコンポーネントで従業員名にアクセスするには、このコンポーネントの値を#{pageFlowScope.empName}に設定します。

5.7.3 実行時に行われる処理: 値の受渡し方法

setPropertyListenerタグを含むボタンをユーザーがクリックすると、リスナーが実行され、To値が解決されて取得され、その後、プロパティとしてpageFlowScopeスコープに格納されます。EL式を通じてそのプロパティにアクセスする後続のページでは、式は元のページによって設定された値に解決されます。

6 イベントの処理

この章では、サーバーおよびクライアントでのイベントの処理方法について説明します。

この章では、次の項目について説明します。

- 6.1項「イベントおよびイベント処理について」

- 6.2項「ADF Facesサーバー・イベントの使用」

- 6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」

- 6.4項「クライアントからサーバーへのカスタム・イベントの送信」

- 6.5項「イベント・レスポンス内でのスクリプトの実行」

- 6.6項「ADF Facesのクライアント動作タグの使用」

- 6.7項「ポーリング・イベントを使用したページの更新」

6.1 イベントおよびイベント処理について

従来のJSFアプリケーションでは、イベント処理は通常サーバーで行われます。JSFのイベント処理はJavaBeansイベント・モデルをベースにしており、JSFアプリケーションでイベント・クラスおよびイベント・リスナー・インタフェースを使用して、コンポーネントで生成されたイベントが処理されます。

アプリケーションでのイベントの例には、ボタンまたはリンクのクリック、メニューまたはリストからの項目の選択、入力フィールドの値の変更などがあります。ボタンのクリックなどのユーザー・アクティビティが発生すると、コンポーネントは、イベントに関する情報を格納し、イベントを生成したコンポーネントを識別するイベント・オブジェクトを作成します。イベントはイベント・キューにも追加されます。JSFライフサイクル内の適切な時期に、JSFは、コンポーネントに対して、対応する登録済リスナーにイベントをブロードキャストするように指示し、リスナーは、イベントを処理するリスナー・メソッドを起動します。リスナー・メソッドによって、ユーザー・インタフェースの変更がトリガーされる場合、またはバックエンド・アプリケーション・コードが起動される場合(あるいはその両方)があります。

標準JSFコンポーネントと同様に、コンポーネントがアクティブになると、ADF FacesコンポーネントでActionEventイベントが配信され、コンポーネントのローカル値が変更されると、ADF Facesの入力および選択コンポーネントでValueChangeEventイベントが配信されます。

たとえば、File Explorerアプリケーションでは、commandMenuItemコンポーネントを使用してユーザーがファイルまたはフォルダを新たに作成できるサブメニューが「ファイル」メニューに含まれます。ユーザーが「フォルダ」commandMenuItemをクリックすると、ActionEventイベントが起動されます。コンポーネントのactionListener属性の値として設定されているEL式がheaderManagerマネージドBeanのcreateNewDirectoryメソッドと解決されるため、このメソッドが起動されてディレクトリが新たに作成されます。

注意:

組込みイベント機能を持つADF Facesコンポーネントはformタグに含める必要があります。

ADF Facesは標準JSFイベント処理手法に準拠していますが、次の2つの主要な方法を提供することでイベント処理機能を向上させています。

- AJAXベースの機能(部分ページ・レンダリング)

- クライアント側イベント・モデル

6.1.1 イベントおよび部分ページ・レンダリング

標準JSFイベントとは異なり、ADF FacesイベントではAJAXスタイルの部分ポストバックがサポートされ、部分ページ・レンダリング(PPR)が行えます。フル・ページ・レンダリングのかわりに、ADF Facesのイベントおよびコンポーネントでは、リクエスト時にページの一部のみがリフレッシュされる部分ページ・レンダリングがトリガーされます。

特定のコンポーネントはイベント・ルート・コンポーネントとみなされます。イベント・ルート・コンポーネントによってページでの境界が決まるため、その境界内のコンポーネントにのみライフサイクルを実行できます(ライフサイクルのこの機能の詳細は、5.3項「最適化されたライフサイクルの使用」を参照)。イベント・ルート内でイベントが発生した場合、ページでは、ルートの子であるコンポーネントのみリフレッシュされます。イベント・ルート・コンポーネントの例はポップアップです。ポップアップ内でイベントが発生した場合は、ポップアップとその子のみレンダリングされ、ページ全体はレンダリングされません。

イベント・ルート・コンポーネントとみなされるコンポーネントは、次のとおりです。

- popup

- region

- panelCollection

- calendar

- editableValueHolderコンポーネント(inputTextなど)

また、特定のイベントは、特定のコンポーネントをイベント・ルート・コンポーネントとして指定します。たとえば、showDetailコンポーネントを展開または縮小する(9.9項「コンテンツの動的な表示および非表示」を参照)と送信される表示イベントは、showDetailコンポーネントがルートであることを示します。ライフサイクルはshowDetailコンポーネント(および子コンポーネントまたはこれをトリガーとするその他のコンポーネント)でのみ実行され、展開または縮小時にこのコンポーネントのみがレンダリングされます。

表6-1に、ADF Facesでのすべてのイベント・タイプと、ソース・コンポーネントがイベント・ルートかどうかを示します。

表6-1 イベントとイベントのルート・コンポーネント

イベント・タイプ

コンポーネントのトリガー先

イベント・ルートか

action

すべてのコマンド・コンポーネント

false

dialog

dialog

false

disclosure

showDetail、showDetailHeader

true

disclosure

showDetailItem

true

focus

tree、treeTable

true

launch

すべてのコマンド・コンポーネント

該当せず

launchPopup

inputListOfValues、inputComboboxListOfValues

true

load

document

該当せず

poll

poll

true

popupOpened

popup

該当せず

popupOpening

popup

該当せず

popupClosed

popup

該当せず

propertyChange

すべてのコンポーネント

該当せず

queryEvent

query、quickQuery

true

queryOperation

query、quickQuery

true

rangeChange

table

該当せず

regionNavigation

region

該当せず

return

すべてのコマンド・コンポーネント

true

returnPopupData

inputListOfValues、inputComboboxListOfValues

true

returnPopup

inputListOfValues、inputComboboxListOfValues

true

rowDisclosure

tree、treeTable、treemap、sunburst

true

sort

treeTable、table

true

valueChange

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)

true

ヒント:

イベント・ルートを処理したときにイベント・ルートの外部にあるコンポーネントを処理する必要がある場合は、どのコンポーネントをサポートするのか、それらをライフサイクル内で実行すべきか、または単にレンダリングすべきかをプログラムにより決定できます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

6.1.2 クライアント側イベント・モデル

サーバー側のアクションおよび値変更イベントの他に、ADF Facesコンポーネントでは、クライアント側のアクションおよび値変更イベント、その他のサーバーおよびクライアント・イベントが起動されます。サーバー・コンポーネントとクライアント・コンポーネントの両方で生成されるイベント(選択イベントなど)も、サーバー・コンポーネントでのみ生成されるイベント(起動イベントなど)も、クライアント・コンポーネントでのみ生成されるイベント(ロード・イベントなど)もあります。

デフォルトでは、ほとんどのクライアント・イベントはサーバーに伝播されます。コンポーネント状態に対する変更は、サーバーに自動的に同期されて状態の一貫性が確保され、必要に応じてイベントがサーバーに配信されてさらに処理されます。ただし、伝播されないようにイベントを構成することもできます。

また、サーバー側Javaコンポーネントにクライアント側イベント・リスナーを登録すると、ADF FacesフレームワークでJavaScriptコンポーネントが必要であるとみなされ、クライアント側コンポーネントが作成されます。

クライアント側JavaScriptイベントのソースはいくつかあります。DOMイベントやプロパティ変更イベントから自動的に導出されることもあれば、他のイベントの処理時に手動で作成することもできます。

6.2 ADF Facesサーバー・イベントの使用

ADF Facesには、多数のサーバー側イベントが用意されています。表6-2に、サーバーのADF Facesコンポーネントで生成されるイベントと、これをトリガーするコンポーネントを示します。

表6-2 ADF Facesサーバー・イベント

イベント

トリガー元コンポーネント

ActionEvent

すべてのコマンド・コンポーネント。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

ActiveDataEvent

イベントに基づくコンポーネントの更新に使用されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アクティブ・データ・サービスの使用方法」の章を参照してください。

AttributeChangeEvent

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)。詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。

CalendarActivity
DurationChangeEvent

CalendarActivityEvent

CalendarDisplay
ChangeEvent

CalendarEvent

Calendarコンポーネント。詳細は、第17章「Calendarコンポーネントの使用方法」を参照してください。

CarouselSpinEvent

carouselコンポーネント。詳細は、12.11項「カルーセルでのイメージの表示」を参照してください。

ColumnSelectionEvent

ColumnVisibility
ChangeEvent

tableおよびtreeTableコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

ContextInfoEvent

contextInfoコンポーネント。詳細は、15.5項「ポップアップへのコンテキスト情報の表示」を参照してください。

DialogEvent

dialogコンポーネント。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

DisclosureEvent

showDetail、showDetailHeader、showDetailItemコンポーネント。詳細は、9.9項「コンテンツの動的な表示および非表示」および9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

DropEvent

ドラッグ・アンド・ドロップをサポートするコンポーネント。詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

FocusEvent *

treeおよびtreeTableコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

ItemEvent

panelTabbedコンポーネント。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。また、navigationPaneコンポーネント。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

LaunchEvent

すべてのコマンド・コンポーネント。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

LaunchPopupEvent

inputListOfValuesおよびinputComboboxListOfValuesコンポーネント。詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

LoadEvent **

documentコンポーネント。詳細は、9.2.5項「documentタグの構成方法」を参照してください。

PollEvent

pollコンポーネント。詳細は、6.7項「ポーリング・イベントを使用したページの更新」を参照してください。

PopupCanceledEvent

PopupFetchEvent

ポップアップ・コンポーネント。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

QueryEvent

QueryOperationEvent

queryおよびquickQueryコンポーネント。詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

RangeChangeEvent

tableコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

RegionNavigationEvent

regionコンポーネント。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「リージョンとしてのタスク・フローの使用」の章を参照してください。

ReturnEvent

すべてのコマンド・コンポーネント。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

ReturnPopupEvent

inputListOfValuesおよびinputComboboxListOfValuesコンポーネント。詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

ReturnPopupDataEvent

ポップアップ・コンポーネント。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

RowDisclosureEvent

treeおよびtreeTableコンポーネント、ならびにtreemapおよびsunburst DVTコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」および第30章「ツリーマップとサンバースト・コンポーネントの使用」を参照してください。

SelectionEvent

table、treeおよびtreeTableコンポーネント、ならびにtreemapおよびsunburst DVTコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」および第30章「ツリーマップとサンバースト・コンポーネントの使用」を参照してください。

SortEvent

tableおよびtreeTableコンポーネント。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

ValueChangeEvent

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)。詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。

WindowLifecycleEvent

ウィンドウのLifecycleStateが変更されたときに配信されます。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

WindowLifecycle
NavigateEvent

新しい場所にナビゲートするために現在のウィンドウがアンロードされたときに配信されます。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

* このフォーカス・イベントは、特定のサブツリーがフォーカスされると生成されます。クライアント側のキーボード・フォーカス・イベントとは異なります。

** LoadEventイベントは、初期ページが表示された後に起動されます(データ・ストリーミングの結果は後で届くことがあります)。

6.2.1 サーバー側イベントの処理方法

すべてのサーバー・イベントには、関連付けられたコンポーネントに対するイベント・リスナーがあります。そのイベントを処理するハンドラを作成し、そのハンドラ・コードをコンポーネントのリスナーと関連付ける必要があります。

たとえば、File Explorerアプリケーションの場合、ユーザーが表の行を選択すると選択イベントが起動されます。表のselectionListener属性は、TableContentView.javaマネージドBeanのtableSelectFileItemハンドラ・メソッドにバインドされているため、このメソッドがイベントに対応して起動されます。

始める前に

サーバー側イベントに関する知識が役立つ場合があります。詳細は、6.2項「ADF Facesサーバー・イベントの使用」を参照してください。

サーバー側イベントを処理する手順:

1. マネージドBean(イベント・リスナーを使用するページの場合はバッキングBean)に、イベント(イベント・タイプ)を唯一のパラメータとし、voidを返すpublicメソッドを作成します。例6-1に、tableSelectFileItemハンドラのコードを示します(マネージドBeanの作成と使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。)

例6-1 イベント・リスナー・メソッド

public void tableSelectFileItem(SelectionEvent selectionEvent)
{
FileItem data = (FileItem)this.getContentTable().getSelectedRowData();
setSelectedFileItem(data);
}

ヒント:

イベント・リスナー・コードがアプリケーションの複数ページで使用されることが多い場合、すべてのページでアクセスできるイベント・リスナー実装クラスの作成を検討します。すべてのサーバー・イベント・リスナー・クラスの実装では、processEvent()メソッド(Eventはイベント・タイプ)をオーバーライドする必要があります。

たとえば、LaunchListenerイベント・リスナーは、LaunchEventのインスタンスを単一引数とします。実装では、次のメソッド・シグネチャに示すように、イベント処理メソッドをオーバーライドする必要があります。

public void processLaunch (LaunchEvent evt)
{
// your code here
}

2. イベント・リスナー・メソッドをコンポーネントに登録するには、構造ウィンドウでイベントを起動するコンポーネントを選択します。「プロパティ」ウィンドウでイベント・リスナー・プロパティの隣にあるドロップダウン・メニューを使用して「編集」を選択します。

3. 「属性の編集」ダイアログで、ステップ1で作成したマネージドBeanとメソッドを選択します。
例6-2に、選択イベント・リスナー・メソッドをtableコンポーネントに登録するサンプル・コードを示します。

例6-2 イベント・リスナー・メソッドの登録

<af:table id="folderTable" var="file"
. . .
rowSelection="single"
selectionListener="#{explorer.tableContentView.tableSelectFileItem}"
. . .
</af:table>

6.3 ADF Facesクライアント・イベントに対するJavaScriptの使用

ほとんどのコンポーネントは、クライアント側イベントに対しても動作できます。クライアント上でイベントを処理すると、サーバーとのラウンドトリップが節約されます。クライアント側イベントを使用する場合は、マネージドBeanにイベント・ハンドラ・コードを含めるかわりに、コール元のページまたはJavaScriptライブラリに含めることのできるJavaScriptを使用します。

デフォルトでは、クライアント・イベントはクライアントでのみ処理されます。ただし、ボタンがクリックされたことを示すAdfActionEventイベントのようにサーバーに配信されるイベント・タイプもあります。コンポーネントの状態に応じてサーバーに配信されるイベントもあります。たとえば、AdfValueChangeEventイベントは、autoSubmit属性がtrueに設定されている場合サーバーに配信されます。追加処理が不要な場合は、イベントのサーバーへの配信を取り消すことができます。ただし、取り消すことができないクライアント・イベントもあります。たとえば、popupOpenedイベント・タイプは、ポップアップ・ウィンドウが開くと配信されるため、このイベントのサーバーへの配信は取り消すことができません。

パフォーマンスのヒント:

イベントにサーバー処理が不要な場合は、イベントがサーバーに伝播されないよう、処理の最後にイベントを取り消すことを検討してください。詳細は、6.3.5項「イベントがサーバーに伝播されないようにする方法」を参照してください。

表6-3に、ADF Facesクライアント・コンポーネントで生成されるイベント、イベントがサーバーに送信されるかどうか、イベントが取消し可能かどうか、およびイベントをトリガーするコンポーネントをリストします。

表6-3 ADF Facesクライアント・イベント

イベント・クラス

イベント・タイプ

サーバーへの伝播

取消し可能

トリガー元コンポーネント

AdfActionEvent

action

はい

はい

すべてのコマンド・コンポーネント

AdfBusyStateEvent

busyState

いいえ

いいえ

ページによってトリガーされます

AdfCarouselSpinEvent

event

はい

いいえ

carousel

AdfColumnSelectionEvent

event

はい

はい

table、treeTable

AdfComponentEvent

load

はい

はい

document

PPRナビゲーションが使用されている場合でも、ドキュメントのコンテンツがクライアントに表示された後。onLoad DOMイベントに常に対応するとはかぎりません。

AdfComponentFocusEvent

いいえ

はい

フォーカスを受け取ることのできる任意のコンポーネント

AdfDialogEvent

event

はい

はい

dialog

ユーザーがダイアログでOKボタンまたは取消しボタンを選択したとき

AdfDisclosureEvent

event

はい

はい

panelBox、region、showDetail、showDetailHeader、showDetailItem

公開状態がユーザーによって切り替えられたとき

AdfDomComponentEvent

inlineFrameLoad

はい

はい

inlineFrame

内部iframeがそのloadイベントを起動したとき

AdfDropEvent

drop

はい

いいえ

ドラッグ・アンド・ドロップをサポートする任意のコンポーネント

AdfFocusEvent

focus

はい

はい

tree、treeTable

AdfItemEvent

item

はい

はい

commandNavigationItem
showDetailItem

AdfLaunchPopupEvent

launch

はい

はい

inputListOfValues、inputComboboxListOfValues

AdfPollEvent

poll

はい

はい

poll

AdfPopupCanceledEvent

popupCanceled

はい

はい

popup

ポップアップが予期せず閉じられるか、cancelメソッドが呼び出された後

AdfPopupClosedEvent

popupClosed

いいえ

いいえ

popup

ポップアップ・ウィンドウまたはダイアログが閉じた後

AdfPopupOpenedEvent

popupOpened

いいえ

いいえ

popup

ポップアップ・ウィンドウまたはダイアログが開いた後

AdfPopupOpeningEvent

popupOpening

いいえ

はい

popup

ポップアップ・ウィンドウまたはダイアログが開く前

AdfPropertyChangeEvent

propertyChange

いいえ

いいえ

すべてのコンポーネント

AdfQueryEvent

event

はい

はい

query、quickQuery

問合せアクション時(ユーザーが検索アイコンまたは検索ボタンをクリックしたとき)

AdfQueryOperationEvent

event

はい

はい

query、quickQuery

AdfReturnEvent

returnEvent

はい

はい

すべてのコマンド・コンポーネント

AdfReturnPopupDataEvent

launchEvent

はい

はい

inputListOfValues、inputComboboxListOfValues

AdfReturnPopupEvent

returnPopup

はい

はい

inputListOfValues、inputComboboxListOfValues

AdfRowDisclosureEvent

rowDisclosure

はい

はい

tree、treeTable

行の公開状態が切り替えられたとき

AdfRowKeySetChangeEvent

selection、rowDisclosure

表の表示イベントに対しては常に行われます。サーバー上の選択リスナーまたは公開リスナーの場合は◎です。

はい

table、treeTable、tree

AdfSelectionEvent

selection

はい

はい

tree、treeTable、table

選択状態が変わったとき

AdfSortEvent

sort

はい

はい

treeTable、table

ユーザーが表のデータをソートしたとき

AdfValueChangeEvent

valueChange

はい

はい

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)

入力または選択コンポーネントの値が変更されたとき

表6-4に示すように、ADF Facesではクライアント・キーボードおよびマウス・イベントもサポートされます。

表6-4 サポートされるキーボードとマウスのイベント・タイプ

イベント・タイプ

イベントが発生するタイミング

click

ユーザーがコンポーネントをクリックしたとき

dblclick

ユーザーがコンポーネントをダブルクリックしたとき

mousedown

ユーザーがコンポーネント上でマウス・ボタンを押したとき

mouseup

ユーザーがコンポーネント上でマウス・ボタンを離したとき

mousemove

ユーザーがコンポーネント上でマウスを移動したとき

mouseover

コンポーネント内にマウスが移動したとき

mouseout

コンポーネントからマウスが移動したとき

keydown

コンポーネントのフォーカス中にユーザーがキーを押したとき

keyup

コンポーネントのフォーカス中にユーザーがキーを離したとき

keypress

コンポーネントのフォーカス中にキーを押す動作が正常に完了したとき

focus

コンポーネントがキーボード・フォーカスを得たとき

blur

コンポーネントがキーボード・フォーカスを失ったとき

ベスト・プラクティス:

キーボードおよびマウス・イベントは、元のDOMイベントへのアクセスを提供し、キー・コードやマウス座標などの取得用の便利な一連の関数も提供するAdfBaseEventクラスのAdfUIInputEventサブクラスを使用して、ネイティブDOMイベントをラップします。AdfBaseEventクラスは、これらのイベントの実装方法に関するブラウザの違いも考慮します。したがって、getNativeEvent()メソッドを直接呼び出すことは避け、かわりにAdfUIInputEvent APIを使用する必要があります。

clientListenerタグによって、クライアント側イベント・ハンドラ・スクリプトをコンポーネントに登録する宣言的方法が提供されます。サポートされているクライアント・イベント・タイプが発生すると、スクリプトが起動されます。例6-3に、アクション・イベントに関連付けられているJavaScript関数の例を示します。

例6-3 clientListenerタグ

<af:button id="button0"
text="Do something in response to an action">
<af:clientListener method="someJSMethod" type="action"/>
</af:button>

ヒント:

コンポーネントのJavaScriptプロパティのかわりにclientListenerタグを使用します。

すべてのADF Facesコンポーネントは、JSF 2.0クライアント動作APIをサポートします。ADF Facesコンポーネントのクライアント・イベントは、クライアント動作としても公開されます。クライアント動作タグ(f:ajaxなど)では、クライアント動作に対応して実行されるJavaScriptをコンポーネントに宣言的に添付できます。たとえば、例6-4に、inputTextコンポーネントに添付されたf:ajaxタグを示します。このタグにより、changeクライアント・イベントがinputTextコンポーネントで発生したときにoutputTextコンポーネントがレンダリングされます。

例6-4 f:ajaxクライアント動作タグの使用

af:inputText ...>
<f:ajax name="change" render="ot1" execute="@this" />
</af:inputText>
<af:outputText id="ot1" ... />

6.3.1 クライアント側イベントの使用方法

クライアント側イベントを使用するには、まず、イベントを処理するJavaScriptを作成する必要があります。次に、clientListenerタグを使用します。

始める前に

クライアント側イベントに関する知識が役立つ場合があります。詳細は、6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。

クライアント側イベントを使用する手順:

1. JavaScriptイベント・ハンドラ関数を作成します。JavaScriptの作成の詳細は、4.2項「JavaScriptのページへの追加」を参照してください。その機能内に、次の機能を追加できます。

- ページでクライアント・コンポーネントを検索する
イベント・ハンドラを別のコンポーネントで動作させるには、ページでそのコンポーネントを検索する必要があります。たとえば、File Explorerアプリケーションで、ユーザーが「ヘルプ」メニューのフィードバックの送信メニュー項目を選択した場合、関連付けられたJavaScript関数はヘルプ・ポップアップ・ダイアログを開くためにそのダイアログを検索する必要があります。クライアント・コンポーネントの検索の詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。

- イベントの元のソースを返す
ページに同じコンポーネントが複数ある場合、JavaScript関数はイベントを発行したコンポーネントを判断することが必要な場合があります。たとえば、複数のコンポーネントが同じポップアップ・ダイアログを開くことができ、そのダイアログをコール元コンポーネントに位置合せする必要があるとします。ポップアップ・ダイアログを位置合せする場所を決定するには、AdfLaunchPopupEventのソースがわかっている必要があります。詳細は、6.3.2項「イベントの発生元を返す方法」を参照してください。

- 子属性を追加する
クライアント・イベント・ハンドラは、コンポーネントの特定の属性を操作することが必要な場合があります。たとえば、File Explorerアプリケーションで、ユーザーが「ヘルプ」メニューで「バージョン情報」メニュー項目を選択した場合、ユーザーがフィードバックを提供できるダイアログが起動します。このダイアログを開いて表示するために使用される関数は、他のダイアログによっても使用され、異なる方法で表示されることが必要な場合があります。したがって、関数では、ダイアログの位置合せの方法に関する情報とともに、どのダイアログを表示するかを知っておく必要があります。この情報は、クライアント属性で搬送されます。クライアント属性は、クライアントへのカスタム・サーバー側属性のマーシャリングにも使用できます。詳細は、6.3.3項「イベントのクライアント側属性の使用方法」を参照してください。

- サーバーへの伝播を取り消す
一部のコンポーネントは、表6-3に示したようにサーバーにクライアント側イベントを伝播します。この追加処理が不要な場合は、その伝播を取り消すことができます。詳細は、6.3.5項「イベントがサーバーに伝播されないようにする方法」を参照してください。

2. JavaScript関数の作成後、イベント・メソッドをコールするイベント・リスナーを追加する必要があります。

注意:

または、ADF Facesコンポーネントのすべてのクライアント・イベントはクライアント動作としても公開されるため、JSF 2.0クライアント動作タグ(f:ajaxなど)を使用してクライアント・イベントに応答できます。詳細は、「Java EE 6 tutorial」(http://download.oracle.com/javaee/index.html)を参照してください。

1. JavaScriptを呼び出すコンポーネントを選択して、「プロパティ」ウィンドウでClientComponentをtrueに設定します。

2. 「コンポーネント」ウィンドウの「操作」パネルで「リスナー」グループから「クライアント・リスナー」をドラッグし、選択したコンポーネントに子としてドロップします。

3. 「クライアント・リスナーの挿入」ダイアログで、メソッドを入力し、JavaScript関数のタイプを選択します。
clientListenerタグのmethod属性で、対応するイベントが発生したときにコールするJavaScript関数を指定します。JavaScript関数は1つのパラメータ(イベント・オブジェクト)をとる必要があります。

clientListenerタグのtype属性で、action、valueChangeなどのタグでリスニングするクライアント・イベント・タイプを指定します。表6-3に、ADF Facesクライアント・イベントをリストしています。

clientListenerタグのtype属性では、キーボードおよびマウスのイベントに関連するクライアント・イベント・タイプもサポートされます。表6-4に、キーボードとマウスのイベント・タイプを示しています。

例6-5に、Explorer.js JavaScriptファイルのshowHelpFileExplorerPopup関数の起動に使用されるコードを示します。

例6-5 JSFページのclientListenerタグ

<af:commandMenuItem id="feedbackMenuItem"
text="#{explorerBundle['menuitem.feedback']}"
clientComponent="true">
<af:clientListener method="Explorer.showHelpFileExplorerPopup"
type="action"/>
</af:commandMenuItem>

4. 「コンポーネント」ウィンドウで、関数によって必要とされる属性を追加するには、「操作」パネルから「クライアント属性」を、選択したコンポーネントへと子としてドラッグ・アンド・ドロップします。「プロパティ」ウィンドウに属性の値を入力します。例6-6に、showAboutFileExplorerPopup関数の属性値の設定に使用されるコードを示します。

例6-6 属性の追加

<af:commandMenuItem id="aboutMenuItem"
text="#{explorerBundle['menuitem.about']}"
clientComponent="true">
<af:clientListener method="Explorer.showAboutFileExplorerPopup"
type="action"/>
<af:clientAttribute name="popupCompId" value=":fe:aboutPopup"/>
<af:clientAttribute name="align" value="end_after"/>
<af:clientAttribute name="alignId" value="aboutMenuItem"/>
</af:commandMenuItem>

ベスト・プラクティス:

キーボードおよびマウス・イベントは、元のDOMイベントへのアクセスを提供し、キー・コードやマウス座標などの取得用の便利な一連の関数も提供するAdfBaseEventクラスのAdfUIInputEventサブクラスを使用して、ネイティブDOMイベントをラップします。AdfBaseEventクラスは、これらのイベントの実装方法に関するブラウザの違いも考慮します。したがって、getNativeEvent()メソッドを直接呼び出すことは避け、かわりにAdfUIInputEvent APIを使用する必要があります。

6.3.2 イベントの発生元を返す方法

JavaScriptメソッドgetSource()は、クライアント・イベントの元のソースを返します。たとえば、File Explorerアプリケーションには、例6-7に示すshowAboutFileExplorerPopup関数が含まれます。この関数は、値を渡すクライアント属性を使用して、特定のポップアップ・ダイアログまたはウィンドウに配置を設定するために複数のイベントによって使用できます。関数を使用する各イベントは属性に対して異なる値を持つため、関数は、対応する属性値にアクセスできるようにイベントを起動したソースについて知っておく必要があります(クライアント属性の使用の詳細は、6.3.3項「イベントのクライアント側属性の使用方法」を参照してください)。

例6-7 クライアント・イベントのソース・コンポーネントの検出

Explorer.showAboutFileExplorerPopup = function(event)
{
var source = event.getSource();
var alignType = source.getProperty("align");
var alignCompId = source.getProperty("alignId");
var popupCompId = source.getProperty("popupCompId");

source.show({align:alignType, alignId:alignCompId});

event.cancel();
}

getSource()メソッドがコールされ、現在のフォーカス・イベントを発生したクライアント・コンポーネント(このケースではポップアップ・コンポーネント)が決まります。

6.3.3 イベントのクライアント側属性の使用方法

スクリプト・ロジックによってコンポーネントになんらかの変更を加えることが必要になる場合があります。これを行うには、イベントによって渡された属性値が必要な場合があります。たとえば、File Explorerアプリケーションには、例6-8に示すshowAboutFileExplorerPopup関数が含まれます。この関数は、値を渡すクライアント属性を使用して、特定のポップアップ・コンポーネントに配置を設定するために使用できます。属性値は、ソース・コンポーネントでgetPropertyメソッドを呼び出すことでアクセスされます。

例6-8 JavaScriptからアクセスされる属性値

Explorer.showAboutFileExplorerPopup = function(event)
{
var source = event.getSource();
var alignType = source.getProperty("align");
var alignCompId = source.getProperty("alignId");
var popupCompId = source.getProperty("popupCompId");

var aboutPopup = event.getSource().findComponent(popupCompId);
aboutPopup.show({align:alignType, alignId:alignCompId});

event.cancel();
}

例6-9に示すように、値はソース・コンポーネントで設定されます。

例6-9 コンポーネントでの属性の設定

<af:commandMenuItem id="aboutMenuItem"
text="#{explorerBundle['menuitem.about']}"
clientComponent="true">
<af:clientListener method="Explorer.showAboutFileExplorerPopup"
type="action"/>
<af:clientAttribute name="popupCompId" value=":aboutPopup"/>
<af:clientAttribute name="align" value="end_after"/>
<af:clientAttribute name="alignId" value="aboutMenuItem"/>
</af:commandMenuItem>

このように属性を使用すると、同じイベントをトリガーする異なるコンポーネントでスクリプトを再利用できます。

6.3.4 イベント実行時のUI入力のブロック方法

実行時間が長いイベントの処理中に、ユーザーがUIを操作できないようにする場合があります。たとえば、アプリケーションがボタンを使用して命令を送信し、処理の一部にユーザーのアカウントに対する請求を作成する処理が含まれているとします。ユーザーが不注意でボタンを2回押した場合、そのアカウントは2回請求されることになります。サーバーの処理が完了するまでユーザーの操作をブロックすることで、誤ったクライアント・アクティビティが発生しないようにできます。

ADF Faces JavaScript APIには、AdfBaseEvent.preventUserInput関数が含まれます。イベントの処理中にすべてのユーザー入力を阻止するためにpreventUserInput関数をコールすると、ブラウザ・ウィンドウ全体にグラス・ペインが表示され、イベントがサーバーとのラウンドトリップを完了するまでそれ以上入力できなくなります。

preventUserInput関数は、カスタム・イベント、カスタム・クライアント・スクリプトで発生したイベント、またはカスタム・クライアント・コンポーネントのピアで発生したイベントでのみ使用できます。また、イベントをサーバーに伝播する必要があります。例6-10に、JavaScriptでpreventUserInputを使用する方法を示します。

例6-10 UI入力のブロック

function queueEvent(event)
{
event.cancel(); // cancel action event
var source = event.getSource();

var params = {};
var type = "customListener";
var immediate = true;
var isPartial = true;
var customEvent =  new AdfCustomEvent(source, type, params, immediate);
customEvent.preventUserInput();
customEvent.queue(isPartial);
}

6.3.5 イベントがサーバーに伝播されないようにする方法

一部のクライアント・イベントは、クライアントでの処理が完了すると、デフォルトでサーバーに伝播されます。この伝播が行われないようにすることが必要な状況もあります。たとえば、ボタンがクリックされるとJavaScriptコードを実行するbuttonコンポーネントを使用している場合、サーバーにactionListenerイベント・リスナーがなければ、イベントを伝播してもリソースの無駄使いになります。サーバーへ伝播されないようにするには、リスナーでイベントのcancel()関数をコールします。cancel()関数がコールされると、isCanceled()関数でtrueが返されます。

例6-11に、伝播を取り消すshowAboutFileExplorerPopup関数を示します。

例6-11 クライアント・イベントのサーバーへの伝播の取消し

Explorer.showAboutFileExplorerPopup = function(event)
{
var source = event.getSource();
var alignType = source.getProperty("align");
var alignCompId = source.getProperty("alignId");
var popupCompId = source.getProperty("popupCompId");

var aboutPopup = event.getSource().findComponent(popupCompId);
aboutPopup.show({align:alignType, alignId:alignCompId});

event.cancel();
}

イベントを取り消すことで、行われないデフォルト処理もあります。たとえば、ポップアップ・メニューのAdfUIInputEventイベントを取り消すと、このイベントを受けて表示されるポップアップ・メニューがブラウザで表示されません。

cancel()関数コールは、イベントを取り消せない場合に無視されます。イベントは、isCancelable()関数からfalseを返すことでこれを示します(取消しできないイベントは、表6-3の「取消し可能」列に「×」が表示されています)。これは一般に、イベントが、結果がすでに完了し、ブロックできないという通知であることを意味します。また、取り消された後でイベントの取消しを元に戻す方法はありません。

6.3.6 レスポンスが必要でないことを示す方法

フレームワークにイベントのレスポンスの処理を期待しない場合があります。たとえば、表のコンテンツをスプレッドシートにエクスポートする場合、コールから戻るのを待つ必要はありません。フレームワークにレスポンスが不要であることを通知するには、AdfBaseEvent.noResponseExpected()メソッドを使用します。

6.3.7 実行時の処理: クライアント側イベントの機能の仕方

一般に、イベント処理はブラウザのネイティブ・イベント・ループから取得されます。ページは、ドキュメントをバブル・アップするすべてのDOMイベントを受け取り、DOMのその部分に関連付けられているピアに渡します。ピアは、DOMイベントをラップするJavaScriptイベント・オブジェクトの作成を担当し、イベントをキューに入れるページに返します(ピアおよびADF Facesアーキテクチャの詳細は、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください)。

各DOMイベントのページでの処理(この結果、通常コンポーネント・イベントがキューイングされる)後、ページのイベント・キューは、通常ブラウザのイベント・ループの最後で空になります。ただし、タイマー起動時にポーリング・イベントを発生するポーリング・コンポーネントなど、ユーザー入力とは無関係にイベントがキューイングされることがあるため、イベントをキューイングすると、ユーザー入力がなくても、イベント・キューを空にするタイマーも起動されます。

イベント・キューは先入れ先出しキューです。イベント・キューを空にするには、ページで各イベント・オブジェクトを捕捉し、イベント・ソースのbroadcast()関数に配信します。このループは、キューが空になるまで続きます。イベントのブロードキャストによって、導出された新規イベントのキューイングが間接的に引き起こされることは非常に理にかなっています(一般的です)。導出されたイベントは、同じループでブロードキャストされます。

イベントがコンポーネントにブロードキャストされると、コンポーネントで次の処理が行われます。

1. イベントをピアのDispatchComponentEventメソッドに配信します。

2. そのイベント・タイプ用に登録されているリスナーにイベントを配信します。

3. イベントをバブルする必要があるかどうかを確認し、必要な場合はバブルを開始します。ほとんどのイベントがバブルされます。例外には、プロパティ変更イベント(キューイングされず、このプロセスにまったく関与しない)やマウスの移動イベント(効率を高めるため)があります。
イベントがバブルされるとき、イベントはAdfUIComponentのHandleBubbledEvent関数に配信され、ここからピアのDispatchComponentEvent関数に渡されます。クライアント・イベント・リスナーではなく、ピアがイベントを受け取ることに注意してください。

イベントのバブルは、イベントのstopBubbling()関数をコールすることでブロックされます。その後で、isBubblingStopped()関数はtrueを返し、バブルは続行されません。取消しと同様に、このコールは元に戻せません。

注意:

イベントを取り消してもバブルは止まりません。イベントの取消しとバブルの停止の両方を行う場合は、両方の関数をコールする必要があります。

4. 前述の処理でイベントが取り消されない場合は、AdfUIComponent.HandleEventメソッドをコールします。このメソッドでは、イベントでのリクエストに応じてイベントがサーバー・イベント・キューに追加されます。

6.3.8 ネーミング・コンテナの使用に関する必知事項

ADF Facesのいくつかのコンポーネントは、pageTemplate、subform、tableおよびtreeなどのNamingContainerコンポーネントです。NamingContainerコンポーネントを含むページでクライアント側APIとイベントを使用する場合、ソース・コンポーネントでfindComponent()メソッドを使用する必要があります。

たとえば、例6-12に示すように、File Explorerアプリケーション内のいずれかのページのすべてのコンポーネントは最終的にpageTemplateコンポーネント内に存在するため、JavaScript関数はgetSource()およびfindComponent()メソッドを使用する必要があります。getSource()メソッドは、コンポーネントの検索に使用できるAdfUIComponentクラスにアクセスします。

例6-12 findComponent()メソッドを使用するJavaScript

function showPopup(event)
{
event.cancel();
var source = event.getSource();
var popup = source.findComponent("popup");
popup.show({align:"after_end", alignId:"button"});
}

findComponent()メソッドを使用すると、メソッドを起動したコンポーネントでローカルに検索が開始します。ネーミング・コンテナの使用の詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。

6.4 クライアントからサーバーへのカスタム・イベントの送信

clientAttributeタグでは、サーバーからクライアントへのボーナス属性の送信はサポートされますが、これらの属性のサーバーへの同期化は行われません。カスタム・データをサーバーに戻すには、AdfCustomEventクラスとserverListenerタグを使用して送信されるカスタム・イベントを使用します。

AdfCustomEvent.queue() JavaScriptメソッドによって、clientComponent属性がtrueに設定されているコンポーネントからカスタム・イベントを起動できます。カスタム・イベント・オブジェクトには、クライアント・イベント・ソースと、イベントに含まれるパラメータのマップに関する情報が含まれます。カスタム・イベントは即時配信(リクエスト値の適用フェーズ中)にも非即時配信(アプリケーションの起動フェーズ中)にも設定できます。

たとえば、File Explorerアプリケーションでは、ユーザーは左側の検索フィールドにファイル名を入力した後、[Enter]キーを押して検索を起動します。例6-13 に示すように、これは、inputTextフィールドに、[Enter]キーが押されると、JavaScript関数を起動するclientListenerが含まれているためです。

例6-13 clientListenerによってJavaScript関数が起動され、ServerLIstenerが起動される

//Code on the JSF page...
<af:inputText id="searchCriteriaName"
value="#{explorer.navigatorManager.searchNavigator.
searchCriteriaName}"
shortDesc="#{explorerBundle['navigator.filenamesearch']}">
<af:serverListener type="enterPressedOnSearch"
method="#{explorer.navigatorManager.
searchNavigator.searchOnEnter}"/>
<af:clientListener type="keyPress"
method="Explorer.searchNameHandleKeyPress"/>
</af:inputText>

//Code in JavaScript file...
Explorer.searchNameHandleKeyPress = function (event)
{
if (event.getKeyCode()==AdfKeyStroke.ENTER_KEY)
{
var source = event.getSource();
AdfCustomEvent.queue(source,
"enterPressedOnSearch",
{},
false);
}
}

JavaScriptには、イベント・ソース、カスタム・イベント・タイプとして文字列enterPressedOnSearch、nullパラメータ・マップ、即時パラメータにFalseをとるAdfCustomEvent.queueメソッドが含まれています。

ページのinputTextにも、次のserverListenerタグが含まれています。

<af:serverListener type="enterPressedOnSearch"
method="#{explorer.navigatorManager.
searchNavigator.searchOnEnter}"/>

タイプ値enterPressedOnSearchがJavaScriptのAdfCustomEvent.queueメソッドのパラメータの値と同じであるため、メソッド式#{explorer.navigatorManager.searchNavigator.searchOnEnter}に解決されるメソッドが起動されます。

6.4.1 クライアントからサーバーへのカスタム・イベントの送信方法

クライアントからサーバーへカスタム・イベントを送信するには、カスタム・イベント・タイプを使用してクライアント・イベントを起動し、バッキングBeanにサーバー・リスナー・メソッドを記述し、このメソッドでカスタム・イベントを処理する必要があります。次に、サーバー・リスナーをコンポーネントに登録します。

始める前に

サーバーへのカスタム・イベントの送信に関する知識が役立つ場合があります。詳細は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

カスタム・イベントを送信する手順:

1. イベント・ソース、カスタム・イベント・タイプおよびサーバーに送信するパラメータを指定してAdfCustomEvent.queue()メソッドを使用し、カスタム・イベントを処理するJavaScriptを作成します。
たとえば、[Enter]キーが押されると検索機能を起動するJavaScriptでは、例6-14に示すようなイベント・ソース、カスタム・イベント・タイプとして文字列enterPressedOnSearch、nullパラメータ・マップ、即時パラメータとしてFalseをとるAdfCustomEvent.queueメソッドを使用します。

例6-14 カスタム・イベント用のサンプルJavaScript

Explorer.searchNameHandleKeyPress = function (event)
{
if (event.getKeyCode()==AdfKeyStroke.ENTER_KEY)
{
var source = event.getSource();
AdfCustomEvent.queue(source,
"enterPressedOnSearch",
{},
false);
}
}

2. マネージドBeanにサーバー・リスナー・メソッドを作成します。このメソッドはpublicで、oracle.adf.view.rich.render.ClientEventオブジェクトを引数とし、void型を返します。例6-15に、別のメソッドをコールして検索を実行し、ナビゲータをリフレッシュするだけのSearchNavigatorViewマネージドBeanに使用されるコードを示します。

例6-15 カスタム・クライアント・イベント用サーバー・リスナー・メソッド

public void searchOnEnter(ClientEvent clientEvent)
{
doRealSearchForFileItem();

// refresh search navigator
this.refresh();
}

注意:

JavaからJavaScriptへの変換では、Numbers、chars、Java Objects、arraysおよび文字列でないCharSequencesの型情報が失われます。このため、サーバーに送信されるオブジェクトが初めはサーバーにある場合、変換が正しく行われるようにするロジックを追加します。6.4.3項「データのマーシャリングとアンマーシャリングに関する必知事項」を参照してください。

3. clientListenerを登録するには、「コンポーネント」ウィンドウで、「操作」パネルからイベントを発生させるコンポーネントへと「クライアント・リスナー」をドラッグ・アンド・ドロップします。

注意:

カスタム・クライアント・イベントを発生させるコンポーネントでは、クライアント側で生成されたコンポーネントが使用可能になるよう、clientComponent属性をtrueに設定します。

4. 「クライアント・リスナーの挿入」ダイアログで、メソッドおよびJavaScript関数のタイプを入力します。スクリプトがページに含まれていない場合はライブラリ名を必ず含めます。タイプは、カスタム・イベントの識別に使用される任意の文字列です。たとえば、File ExplorerではenterPressedOnSearchが使用されていました。

5. サーバー・リスナーを登録するには、「コンポーネント」ウィンドウで、「操作」パネルから「サーバー・リスナー」を、clientListenerタグへと兄弟としてドラッグ・アンド・ドロップします。

6. 「サーバー・リスナーの挿入」ダイアログで、enterPressedOnSearchなどのこのサーバー・リスナーに対する値としてクライアント・リスナーのタイプ値に使用される文字列を入力します。
「プロパティ」ウィンドウで、ステップ2で作成したメソッドに解決される式をmethod属性に入力します。

6.4.2 実行時の処理: クライアント・リスナーとサーバー・リスナーの協働の仕方

実行時、[Enter]キーを押すなど、ユーザーによってイベントが発生すると、クライアント・リスナー・スクリプトが実行されます。このスクリプトでAdfCustomEvent.queue()メソッドをコールし、指定したイベント・タイプのカスタム・イベントが入力コンポーネントのキューに置かれます。入力コンポーネントに登録されているサーバー・リスナーがカスタム・イベントを受け取り、関連付けられているBeanメソッドが実行されます。

6.4.3 データのマーシャリングとアンマーシャリングに関する必知事項

マーシャリングとアンマーシャリングは、プログラミング言語のデータ・オブジェクトをバイト・ストリームに変換し、同じまたは別のプログラミング言語のネイティブ・データ・オブジェクトに戻すプロセスです。ADF Facesでは、マーシャリングとアンマーシャリングは、データを適切な形式に変換して、クライアント上のJavaScriptとサーバー側のJava間で最適に交換できるようにすることを意味します。

表6-5に、JavaScript型とADF Facesの対応するJava型とのマッピングを示します。

表6-5 JavaScriptとJavaの型マップ

JavaScript型

Java型

Boolean

java.lang.Boolean

Number

java.lang.Double

String

java.lang.String

Date

java.util.Date

Array

java.util.ArrayList

Object

java.util.Map

表6-6に、Java型とJavaScript型のマッピングを示します。

表6-6 JavaとJavaScriptの型マップ

Java型

JavaScript型

java.lang.Boolean

Boolean

java.lang.Double

Number

java.lang.Integer

Number

java.lang.Float

Number

java.lang.Long

Number

java.lang.Short

Number

java.lang.Character

String

java.lang.CharSequence

String

java.util.Collection

Array

java.util.Date

Date

java.util.Map

Object

Array

Array

java.awt.Color

TrColor

変換処理中に情報が失われる可能性あることに注意してください。たとえば、次の例に示すように、カスタム・イベントを使用して数値1と文字列testを送信するとします。

AdfCustomEvent.queue(event.getSource(), "something", {first:1, second:"test"});

JavaScriptからJavaへの変換では数値はDoublesに変換されるため、サーバー側リスナーでfirstパラメータの型がjava.lang.Doubleになります。ただし、初めはサーバー側でintだったパラメータが、JavaからJavaScriptへの変換で数値になった可能性もあります。サーバーへ戻る際にDoubleに変換されます。

6.5 イベント・レスポンス内でのスクリプトの実行

ExtendedRenderKitServiceクラスを使用すると、アクション・メソッド・バインディングの起動後などのイベント・レスポンスにJavaScriptを追加できます。これは、ユーザーにデータベース接続が確立できないことを通知するアラートの送信などの簡単なメッセージの場合もあれば、プログラムからポップアップ・ダイアログを終了させるためのポップアップ・ウィンドウでのhide()などの関数のコールの場合もあります。

たとえば、File ExplorerアプリケーションでユーザーがUpOneFolderナビゲーション・ボタンをクリックしてフォルダ構造を上に移動すると、フォルダ・ペインが再描画されて、選択した親フォルダが表示されます。UpOneFolderボタン・イベントのクリックを受けてHandleUpOneFolder()メソッドがコールされます。ExtendedRenderKitServiceクラスを使用してJavaScriptがレスポンスに追加されます。

例6-16に、actionListener属性が、ボタンがクリックされたときにアクション・イベントを処理するHandleUpOneFolder()ハンドラ・メソッドにバインドされているページのUpOneFolderコードを示します。

例6-16 JavaScriptをレスポンスに追加するメソッドの起動

<af:btton id="upOneFolder"
. . .
actionListener="#{explorer.headerManager.handleUpOneFolder}"/>

例6-17に、ExtendedRenderKitServiceクラスを使用するhandleUpOneFolderメソッドを示します。

例6-17 JavaScriptのレスポンスへの追加

public void handleUpOneFolder(ActionEvent actionEvent)
{
UIXTree folderTree =
feBean.getNavigatorManager().getFoldersNavigator().getFoldersTreeComponent();
Object selectedPath =
feBean.getNavigatorManager().getFoldersNavigator().getFirstSelectedTreePath();

if (selectedPath != null)
{
TreeModel model =
_feBean.getNavigatorManager().getFoldersNavigator().getFoldersTreeModel();
Object oldRowKey = model.getRowKey();
try
{
model.setRowKey(selectedPath);
Object parentRowKey = model.getContainerRowKey();
if (parentRowKey != null)
{
folderTree.getSelectedRowKeys().clear();
folderTree.getSelectedRowKeys().add(parentRowKey);
// This is an example of how to force a single attribute
// to rerender. The method assumes that the client has an optimized
// setter for "selectedRowKeys" of tree.
FacesContext context =  FacesContext.getCurrentInstance();
ExtendedRenderKitService erks =
Service.getRenderKitService(context,
ExtendedRenderKitService.class);
String clientRowKey = folderTree.getClientRowKeyManager().
getClientRowKey(context, folderTree, parentRowKey);
String clientId = folderTree.getClientId(context);
StringBuilder builder = new StringBuilder();
builder.append("AdfPage.PAGE.findComponent('");
builder.append(clientId);
builder.append("').setSelectedRowKeys({'");
builder.append(clientRowKey);
builder.append("':true});");
erks.addScript(context, builder.toString());
}
}
finally
{
model.setRowKey(oldRowKey);
}
// Only really needed if using server-side rerendering
// of the tree selection, but performing it here saves
// a roundtrip (just one, to fetch the table data, instead
// of one to process the selection event only after which
// the table data gets fetched!)
_feBean.getNavigatorManager().getFoldersNavigator().openSelectedFolder();
}

}

6.6 ADF Facesのクライアント動作タグの使用

クライアント側での動作を実装する場合、通常はJavaScriptを記述し、それをクライアント・リスナーとしてコンポーネントに登録する必要がありますが、ADF Facesのクライアント動作タグを使用すると、一般的なクライアント操作を宣言的に実行できます。JavaScriptコードを記述するかわりにこれらのタグを使用して同じ処理を実装すると、ブラウザにダウンロードする必要のあるJavaScriptコードの量が少なくなります。

ADF Facesは、クライアント・リスナーのかわりに使用できる次のクライアント動作タグを提供します。

- panelDashboardBehavior: 応答性を向上させるために、実行時にpanelDasboardコンポーネントに子コンポーネントを挿入できます。詳細は、9.8.1項「panelDashboardコンポーネントの使用方法」を参照してください。

- insertTextBehavior: コマンド・コンポーネントで、inputTextコンポーネントのカーソル位置にテキストを挿入できます。詳細は、11.3.2項「inputTextコンポーネントへのテキストの挿入機能の追加方法」を参照してください。

- richTextEditorInsertBehavior: コマンド・コンポーネントで、richTextEditorコンポーネントのカーソル位置にテキスト(事前フォーマット済テキストを含む)を挿入できます。詳細は、11.8.2項「richTextEditorコンポーネントへのテキストの挿入機能を追加する方法」を参照してください。

- autoSuggestBehavior: ユーザーが入力する内容に一致するドロップダウン・リストの項目を値リスト・コンポーネントに表示できるようにします。詳細は、13.1項「値リスト・コンポーネントについて」を参照してください。

- showPopupBehavior: コマンド・コンポーネントでポップアップ・コンポーネントを起動できます。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

- showPrintablePageBehavior: コマンド・コンポーネントで、ページの印刷可能版を生成して表示できます。詳細は、37.2項「印刷用ページの表示」を参照してください。

- checkUncommittedDataBehavior: immediate属性がtrueに設定されている場合にユーザーがページ外へのナビゲートを試行したときに、コマンド・コンポーネントが警告を表示できるようにします。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

- scrollComponentIntoViewBehavior: クリックして、コマンド・コンポーネントから名前付きのコンポーネントに移動できます。詳細は、6.6.1項「scrollComponentIntoViewBehaviorタグの使用方法」を参照してください。

ヒント:

ADF Facesは、スクロールされるコンポーネントがページにまだレンダリングされていない場合に使用できるサーバー側scrollComponentIntoView APIも提供します。

たとえば、表を特定の行にスクロールできるようにする場合に、表が最初にレンダリングされるときに行がビューの範囲外になることがあります。scrollComponentIntoView APIをデータ・フェッチ・イベントの一部として使用できます。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

- target: 指定されたイベントが発生したときに、コンポーネントを宣言的に実行するか、コンポーネントのリストを表示します。詳細は、第8.3項「targetタグを使用したPPRの実行」を参照してください。

クライアント動作タグで、サーバー側イベント配信が自動的に取り消されます。したがって、親コンポーネントのactionListenerまたはaction 属性が無視されます。これは無効にすることができません。サーバー側の機能もトリガーする場合は、クライアント側イベントを使用する(6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照)か、AdfCustomEventおよびaf:serverListenerを使用してサーバー側イベントを配信するクライアント・リスナーを追加します(6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照)。

6.6.1 scrollComponentIntoViewBehaviorタグの使用方法

ユーザーがページの特定のコンポーネントに移動できるようにする場合は、scrollComponentIntoViewBehaviorタグを使用します。このアクションは、HTMLのアンカーと似ています。たとえば、commandLinkコンポーネントを使用して、ユーザーがページの特定の部分に移動できるようにできます。richTextEditorおよびinlineFrameコンポーネントの場合は、サブコンポーネントに移動できます。たとえば、図6-1は、そのテキストに多数のセクションがあるrichTextEditorコンポーネントを示しています。エディタの下にあるコマンド・リンクを使用すると、テキストの特定部分に移動できます。

図6-1 エディタのscrollComponentIntoViewBehaviorタグ

ユーザーがスクロールしたコンポーネントにフォーカスを切り替えるためのタグを構成することもできます。

始める前に:

動作タグに関する知識が役立つ場合があります。詳細は、6.6項「ADF Facesのクライアント動作タグの使用」を参照してください。

scrollComponentIntoViewBehaviorタグを使用する手順:

1. ユーザーがクリックして、指定されたコンポーネントに移動するコマンド・コンポーネントを作成します。手順の詳細は、20.3.1項「ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法」を参照してください。

2. 「コンポーネント」ウィンドウの「操作」パネルから、「コンポーネントのビュー内へのスクロール動作」をコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。

3. 「コンポーネントのビュー内へのスクロール動作の挿入」ダイアログで、ドロップダウン矢印を使用して「編集」を選択し、移動してユーザーの移動先であるコンポーネントを選択します。

4. 移動後にコンポーネントにフォーカスを設定する場合は、「プロパティ」ウィンドウで、focus属性をtrueに設定します。

5. richTextEditorまたはinlineFrameコンポーネントの場合は、オプションで、subTargetId属性の値を入力します。このIDは、richTextEditorまたはinlineFrameコンポーネントの値で定義されています。
たとえば、図6-1に示されているscrollComponentIntoViewBehaviorタグのsubTargetId属性の値は、Introductionです。richTextEditorの値は、例6-18に示されているプロパティにバインドされています。Introductionは最初のヘッダーのIDです。

例6-18 プロパティに定義されているsubTargetId値

private static final String _RICH_SECTIONED_VALUE =
"<div>\n" +
"    <h2>\n" +
"      <a id=\"Introduction\"></a>Introduction</h2>\n" +
"    <p>\n" +
"      The ADF Table component is used to display a list of structured data. For example,\n" +
"      if we have a data structure called Person that has two properties - firstname and\n" +
"      lastname, we could use a Table with two columns - one for firstname, and the other\n" +
"      for lastname - to display a list of Person objects.\n" +
"    </p>\n" +
"  </div>\n" +
"  <div>\n" +
"    <h2>\n" +
"      <a id=\"The_Table_Model\"></a>The Table Model</h2>\n" +
"    <p>\n" +
. . .
</div>";

6.7 ポーリング・イベントを使用したページの更新

ADF Facesは、pollEventを使用して指定された間隔でサーバーと通信できるpollコンポーネントを提供します。たとえば、ポーリング・コンポーネントを使用して、outputTextコンポーネントを更新したり、サーバーにハートビートを配信して、それらのセッションがタイムアウトするのを防ぐことができます。

ポーリング時刻に必要な処理を行うために使用されるpollEventのリスナーを作成する必要があります。たとえば、pollコンポーネントを使用してoutputTextコンポーネントの値を更新する場合は、データ・ソース内の値をチェックしてからコンポーネントを更新するpollEventListenerメソッドを実装します。

pollコンポーネントがそのポーリング・イベントを配信する頻度を決定する時間間隔を構成できます。経過後にページがタイムアウトになることを許可される時間も構成します。ページのポーリングはセッションがタイムアウトにならない原因となるため、これが役立つ場合があります。サーバーにリクエストが送信されるたびに、セッション・タイムアウト値がページに書き込まれ、セッションをいつタイムアウトにするかを決定します。pollコンポーネントは(時間間隔に基づいて)サーバーにリクエストを継続的に送信するため、セッションは決してタイムアウトになりません。これは、ネットワーク使用量とメモリーの両方でコストが高くなります。

この問題を回避するために、web.xml構成ファイルには、タイムアウトにする前にページを実行する必要のある時間の長さを指定するoracle.adf.view.rich.poll.TIMEOUTコンテキスト・パラメータが含まれます。キーボードやマウスのアクティビティがない場合、ページはタイムアウトに対して適格とみなされます。デフォルトのタイムアウト期間は10分に設定されています。このため、ユーザーが10分間非アクティブの(つまり、キーボードやマウスを使用していない)場合、フレームワークはポーリングを停止し、その時点から、ページは標準サーバー側セッション・タイムアウトに参加します(詳細は、A.2.3.24項「セッション・タイムアウトの警告」を参照してください)。

アプリケーションがタイムアウトになる場合、ユーザーがマウスを移動するかキーボードを再び使用すると、新しいセッション・タイムアウト値がページに書き込まれ、ポーリングが再び開始します。

pollコンポーネントのtimeout属性を使用して、特定のページについてこの時間をオーバーライドできます。

6.7.1 pollコンポーネントの使用方法

pollコンポーネントを使用する場合、通常はポーリング・イベントの機能を処理するハンドラ・メソッドも作成します。

始める前に

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、6.7項「ポーリング・イベントを使用したページの更新」を参照してください。

pollコンポーネントを使用する手順:

1. マネージドBeanで、ポーリング・イベントのハンドラを作成します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. 「コンポーネント」ウィンドウの「操作」パネルから「ポーリング」をページ上にドラッグ・アンド・ドロップします。

3. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Interval: ポーリング・イベント間の時間をミリ秒単位で入力します。ポーリングを無効にするには0に設定します。

- PollListener: 手順1のメソッドに評価されるEL式を入力します。

- Timeout: web.xmlファイルのグローバル・タイムアウト値をオーバーライドする場合は、Timeoutをミリ秒単位で設定します。この時間が経過すると、ページはポーリングを停止し、セッションがタイムアウトになります。

7 入力の検証および変換

この章では、アプリケーションのADF Faces入力コンポーネントに変換と検証の機能を追加する方法について説明します。また、カスタムJSF変換および検証を追加する方法と、エラー(検証によって生じたもの以外も含む)の処理と表示の方法についても説明します。

この章では、次の項目について説明します。

- 7.1項「ADF Facesの変換および検証について」

- 7.2項「変換、検証とJSFライフサイクル」

- 7.3項「変換の追加」

- 7.4項「カスタムADF Facesコンバータの作成」

- 7.5項「検証の追加」

- 7.6項「カスタムJSF検証の作成」

7.1 ADF Facesの変換および検証について

ADF Facesの入力コンポーネントでは、変換機能がサポートされます。Webアプリケーションで、int、long、dateなどの様々な型をモデル・レイヤーに格納できます。ただし、クライアント・ブラウザで表示されるとき、ユーザー・インタフェースには、ユーザーが読取りまたは変更できるような形式でデータが表示される必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが「date」フィールドを編集してフォームを送信した場合、文字列は、アプリケーションで要求されるタイプに変換される必要があります。変換後のデータは、規則および条件に対して検証されます。逆に、String以外の型として格納したデータを表示および更新用にStringに変換することもできます。af:inputDateなどの多くのコンポーネントで、変換機能が自動的に提供されます。

ADF Facesの入力コンポーネントでは、検証機能もサポートされます。1つ以上のバリデータ・タグをコンポーネントに追加できます。また、ビジネス・ニーズに応じてカスタム・バリデータを作成することもできます。

バリデータとコンバータには、ユーザーが関連付けられているフィールドをクリックすると表示されるデフォルトのヒント・メッセージがあります。コンバータの場合、ヒントは、通常、入力値に使用する、指定されたパターンに基づいた適切な形式をユーザーに示します。バリデータの場合、ヒントを使用して、コンポーネントに構成されている検証に基づいた有効な値が示されます。変換または検証に失敗すると、関連付けられたエラー・メッセージがユーザーに表示されます。これらのメッセージはダイアログに表示することも、変換または検証に失敗したコンポーネントと並べてページ自体に表示することもできます。ADF Facesアプリケーションでのメッセージの表示の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

ADF Facesコンバータは、標準JSFコンバータを拡張するコンバータのセットです。入力コンポーネントのADF Facesコンバータはクライアント側で動作するため、変換のエラーはクライアントで捕捉され、サーバーへのラウンドトリップが回避されます。ADF Facesコンバータは、入力コンポーネントに簡単にドラッグ・アンド・ドロップできます。

ADF Facesバリデータは、標準JSFバリデータも補強します。ADF Facesバリデータは、クライアント側とサーバー側の両方で動作できます。クライアント側バリデータはJavaScriptで記述され、クライアント側で捕捉された検証エラーはサーバーとの間をラウンドトリップしなくても処理できます。

7.1.1 ADF Facesコンバータおよびバリデータのユースケースと例

ADF Facesコンバータを使用して、入力コンポーネントからモデルで要求される形式に入力を変換します。一般的なユースケースは、数値の入力のための入力コンポーネントの使用と、ユーザーが入力した文字列をモデルで処理するための数値に変換するためのコンバータの組込みです。たとえば、af:inputTextコンポーネントは製品ID属性に使用されます。af:convertNumberコンバータをaf:inputTextコンポーネントに追加して、StringをNumberに変換します。別の例は、製品のコストの属性用にinputTextコンポーネントがある場合です。af:convertNumberを使用して、入力文字列を適切な通貨形式に変換できます。

入力文字列を検証するのと同じ方法で、バリデータを入力コンポーネントに追加します。たとえば、バリデータをaf:inputTextコンポーネントに追加して、製品IDの桁数が適切な範囲内にあることを確認できます。af:validateLengthをaf:inputTextに追加し、minimumおよびmaximum属性を設定して有効な桁の長さを定義します。

7.1.2 ADF Facesコンバータおよびバリデータの追加機能

コンバータおよびバリデータを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。次に、役に立つ可能性のある他のセクションへのリンクを示します。

- JSFライフサイクルでの変換と検証の動作の詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

- ADF Facesでは、デフォルトのメッセージのかわりに変換エラー・メッセージの詳細部分をカスタマイズできます。メッセージの作成の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

7.2 変換、検証とJSFライフサイクル

データを持つフォームが送信されると、編集可能なvalue属性がバインドされているUIコンポーネントごとに、リクエスト値がブラウザからサーバーに送信されます。リクエスト値は、JSFのリクエスト値の適用フェーズでデコードされ、デコードされた値はコンポーネントのsubmittedValue属性にローカルに保存されます。値に変換が必要な場合(Stringとして表示されるが、java.util.Dateオブジェクトとして格納されている場合など)、データは、UIコンポーネントごとに検証の処理フェーズで正しい型に変換されます。

検証または変換に失敗した場合、ライフサイクルはレスポンスのレンダリング・フェーズに進み、対応するエラー・メッセージがページに表示されます。変換および検証が正常に終了すると、モデルの更新フェーズが開始され、変換および検証された値がモデルの更新に使用されます。

検証または変換エラーが起きた場合、検証または変換に失敗したコンポーネントで、関連付けられたエラー・メッセージがキューに置かれ、コンポーネント自身は無効とされます。その後、現在のページがエラー・メッセージを使用して再表示されます。ADF Facesのコンポーネントには、これらのメッセージを宣言的に設定する方法が用意されています。

JSFライフサイクルでの変換と検証の動作の詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

7.3 変換の追加

Webアプリケーションは、モデル・レイヤー内に多くのタイプのデータ(int、long、dateなど)を格納できます。ただし、クライアント・ブラウザで表示されるとき、ユーザー・インタフェースには、ユーザーが読取りまたは変更できるような形式でデータが表示される必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが「date」フィールドを編集してフォームを送信した場合、文字列は、アプリケーションで要求されるタイプに変換される必要があります。1つのUIコンポーネントには1つのコンバータのみを設定できます。

af:inputTextコンポーネントを作成し、コンバータを持つタイプの属性を設定すると、コンバータのタグが入力コンポーネントの子としてJDeveloperで自動的に追加されます。このタグでコンバータが起動され、ユーザーが入力したString型が、オブジェクトで規定された型に変換されます。

String型と単純なデータ型の間の変換を処理するJSFの標準コンバータでは、javax.faces.convert.Converterインタフェースが実装されます。用意されているJSF標準コンバータ・クラスは次のとおりです。

- BigDecimalConverter

- BigIntegerConverter

- BooleanConverter

- ByteConverter

- CharacterConverter

- DateTimeConverter

- DoubleConverter

- EnumConverter

- FloatConverter

- IntegerConverter

- LongConverter

- NumberConverter

- ShortConverter

表7-1に、ADF Facesにより提供されるコンバータを示します。

表7-1 ADF Facesのコンバータ

コンバータ

タグ名

説明

ColorConverter

af:convertColor

java.lang.Stringオブジェクトをjava.awt.Colorオブジェクトに変換します。カラー・パターンのセットをコンバータの属性として指定します。

DateTimeConverter

af:convertDateTime

java.lang.Stringオブジェクトをjava.util.Dateオブジェクトに変換します。日付のパターンとスタイルをコンバータの属性として指定します。

NumberConverter

af:convertNumber

java.lang.Stringオブジェクトをjava.lang.Numberオブジェクトに変換します。数値のパターンと型をコンバータの属性として指定します。

バリデータ同様、ADF Facesのコンバータはクライアント側でも実行されます。

コンバータが明示的に追加されていない場合、ADF Facesでデータ型に基づいたコンバータの作成が試行されます。このため、値が次の型にバインドされている場合、明示的にコンバータを追加する必要はありません。

- java.util.Date

- java.util.Color

- java.awt.Color

- java.lang.Number

- java.lang.Integer

- java.lang.Long

- java.lang.Short

- java.lang.Byte

- java.lang.Float

- java.lang.Double

表7-1にリストされているコンバータとは異なり、JavaScript対応のコンバータはtypeによって適用され、標準のコンバータのかわりに使用されてclassおよびid属性をオーバーライドします。これらのコンバータには、コンポーネント内にネストできるタグは関連付けられていません。

7.3.1 コンバータの追加方法

UIコンポーネントにコンバータを手動で挿入できます。

始める前に:

コンバータに関する知識が役立つ場合があります。詳細は、7.3項「変換の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。

タグを持つADF Facesコンバータを追加する手順:

1. 「構造」ウィンドウで、コンバータを追加するコンポーネントを右クリックして「componentの中に挿入」を選択し、ADF Facesコンバータを挿入するために「ADF Faces」を選択します。
「JSF」→「コンバータ」を選択してJSFコンバータを挿入することもできます。

2. コンバータ・タグ(「日時の変換」など)を選択し、「OK」をクリックします。

3. JSFページでコンポーネントを選択し、「プロパティ」ウィンドウで、変換エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
複数のパターンを設定できるADF Facesコンバータもあります。詳細は、7.3.2項「複数のコンバータ・パターンを指定する方法」を参照してください。

ADF Facesでは、変換エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailconvertDateなどの変換エラー・タイプ)に値を設定することにより、変換に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。メッセージの作成の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

7.3.2 複数のコンバータ・パターンを指定する方法

一部のコンバータでは、複数のコンバータ・パターンがサポートされます。パターンでは、変換で受け入れられるデータの形式を指定します。複数のパターンが複数の形式に対応します。たとえば、ユーザーは、スラッシュ(/)またはハイフン(-)をセパレータとして使用して日付を入力できます。すべてのコンバータが複数のパターンをサポートするわけではありませんが、パターン一致は柔軟であり、複数のパターンが必要ではない場合もあります。

例7-1に、af:convertColorタグに対する複数パターンの使用を示します。「255-255-000」と「FFFF00」の両方の値が使用可能です。

例7-1 af:convertColorの複数パターン

<af:inputColor colorData="#{adfFacesContext.colorPalette.default49}" id="sic3"
label="Select a color" value="#{demoColor.colorValue4}" chooseId="chooseId">
<af:convertColor patterns="rrr-ggg-bbb RRGGBB #RRGGBB"
transparentAllowed="false"/>
</af:inputColor>

例7-2に、「6/9/2007」と「2007/9/6」の両方が使用可能なaf:convertDateTimeタグの使用を示します。

例7-2 af:convertDateTimeの複数パターン

<af:inputDate id="mdf5" value="2004/09/06" label="attached converter">
<af:convertDateTime pattern="yyyy/M/d" secondaryPattern="d/M/yyyy" />
</af:inputDate>

例7-3に、type属性がcurrencyに設定されており、$78.57と$078.57を変換の値として使用できるaf:convertNumberタグを示します。

例7-3 通貨属性が設定されているaf:convertNumber

<af:inputText label="type=currency" value="#{validate.currency}" id="it1">
<af:convertNumber type="currency"/>
</af:inputText>

7.3.3 実行時の処理: コンバータの機能の仕方

ユーザーがコンバータを含むページを送信すると、ADF Facesのvalidate()メソッドでコンバータのgetAsObject()メソッドがコールされ、String値が必要なオブジェクト・タイプに変換されます。アタッチされているコンバータがなく、コンポーネントがモデルのBeanプロパティにバインドされている場合、ADFでモデルのデータ型を確認して適切なコンバータを見つけます。変換に失敗すると、コンポーネントのvalid属性がfalseに設定され、JSFでFacesContextによってメンテナンスされているキューにエラー・メッセージが追加されます。変換が正常終了し、コンポーネントにアタッチされているバリデータがある場合、変換された値がバリデータに渡されます。コンポーネントにアタッチされているバリデータがない場合、変換された値はローカル値として格納され、モデルの更新に後で使用されます。

7.3.4 日時コンバータに関する必知事項

日付コンバータでは、あいまいにならないように、4桁の年のパターンを使用する必要があります。パターンとして2桁の年の書式を使用すると、4桁の年の値がすべて2桁の年の値として表示されます。たとえば、パターンとして2桁の年の書式(MM-dd-yyなど)を使用している場合、日付値03-01-1910と03-01-2010は入力フィールドに03-01-10と表示されるので、サーバーに正しい年の値が格納されても、正確に解釈されないおそれがあります。

図7-1は、inputDateコンポーネントに表示されている日付値と、その下にあってサーバーに保存されている元の値を表示するoutputTextコンポーネントを示しています。

図7-1 年の書式が2桁の日付コンバータ

2桁の年の書式を使用すると、2桁の年を含むすべての文字列が、two-digit-year-startからtwo-digit-year-start + 100までの範囲内の日付に解決されます。たとえば、two-digit-year-startの値が1912で、文字列が01/01/50の場合、その日付は01/01/1950として解決されます。この範囲外の日付を入力するには、エンド・ユーザーは完全な(4桁の)年を使用して日付を入力する必要があります。two-digit-year-start要素とその構成方法の詳細は、第A.6.2項「trinidad-config.xmlの要素に関する必知事項」を参照してください。

注意:

2桁の年の書式を使用している間は、ユーザーが既存の値を編集しても、2桁の年はtwo-digit-year-startによって決定される範囲内の年になります。

たとえば、two-digit-year-startが1950 (年の値は1950年から2050年の範囲で解決される)で、inputDateコンポーネントの値が03/01/1776 (03/01/76と表示される)であるとします。ユーザーがこの値を03/01/77に変更すると、新しい日付は期待する03/01/1777ではなく、03/01/1977になります。

12時間形式(MM/dd/yyyy - hh:mmなど)をパターンとしてaf:convertDateTimeで使用する場合は、am/pmプレースホルダもパターンに含める必要があります(MM/dd/yyyy - hh:mm aなど)。含めないと、ピッカーでam/pmオプションが表示されず、am/pm情報を保存できません。図7-2に、inputDateコンポーネントのパターンにam/pmプレースホルダが含まれているケースと含まれていないケースを示します。

図7-2 af:convertDateTimeでのAM/PMプレースホルダの使用

convertDateTimeパターンにタイムゾーン・プレースホルダ(z)を含めてタイムゾーン情報を表示する場合は(たとえばyyyy-MM-dd hh:mm:ss a zのように)、トリニダードのconvertDateTimeがタイムゾーン名の表示より優先される点に注意してください。コンバータをinputTextまたはoutputTextとともに使用すると、タイムゾーンはGMT + xという形式で表示されます。inputDateとともに使用すると、(UTC-08:00) ロサンゼルス - 太平洋標準時(PT)などの事前構成済の表示値の選択肢を使用してタイムゾーンが表示されます。

7.4 カスタムADF Facesコンバータの作成

カスタムJSFコンバータは、Javaを使用してサーバー側で動作します。ADF FacesコンバータはJSFコンバータと同様に動作しますが、Javascriptを使用したクライアント側での変換と検証もサポートしています。

7.4.1 カスタムADF Facesコンバータの作成方法

カスタムADF Facesコンバータを作成するには、変換用のビジネス・ロジックを作成し、カスタム・コンバータをアプリケーションに登録する必要があります。カスタムADF Facesコンバータを使用するには、f:converterタグを使用して、カスタムADF Facesコンバータをそのタグのプロパティとして設定します。または、入力コンポーネントのconverter属性を使用して、そのコンバータにバインドすることもできます。

7.4.1.1 サーバー側(Java)での変換の実装

ADF Facesコンバータは、サーバー側ではカスタムJSFコンバータと同様に実装されます。

1. javax.faces.converter.Converterインタフェースを実装するJavaクラスを作成します。Converterインタフェースを実装するには、実装にpublic no-argsコンストラクタ、属性に対するアクセッサ・メソッドのセットおよびgetAsObjectおよびgetAsStringメソッドを含める必要があります。
getAsObject()メソッドは、次の例のようにFacesContextインスタンス、UIコンポーネントおよび指定されたオブジェクトに変換されるString値を引数とします。

public Object getAsObject(FacesContext context,
UIComponent component,
java.lang.String value){
..
}

getAsString()メソッドは、FacesContextインスタンス、UIコンポーネントおよびString値に変換されるオブジェクトを引数とします。次に例を示します。

public String getAsString(FacesContext context,
UIComponent component,
Object value){
..
}

これらのクラスの詳細は、Javadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。

2. 必要な変換ロジックを追加します。このロジックでは、javax.faces.convert.ConverterExceptionを使用して適切な例外をスローし、javax.faces.application.FacesMessageを使用して対応するエラー・メッセージを生成します。
ConverterインタフェースとFacesMessageエラー・ハンドラの詳細は、javax.faces.convert.ConverterExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。

アプリケーションでクライアントに状態を保存する場合、カスタムADF FacesコンバータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照するか、http://docs.oracle.com/javaee/index.htmlを参照してください。

7.4.1.2 ADF Facesコンバータのfaces-config.xmlファイルへの登録

コンバータは、faces-config.xmlファイルに登録する必要があります。

1. faces-config.xmlファイルを開きます。
faces-config.xmlファイルは、JDeveloperの「アプリケーション」ウィンドウの、「View_Project」→WEB-INFノードにあります。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 「コンバータ」を選択し、「追加」をクリックしてコンバータ情報を入力します。

「ヘルプ」をクリックするか、[F1]を押すと、コンバータの登録に関する追加のヘルプが表示されます。

7.4.1.3 クライアント側(Javascript)での変換の実装

ADFフレームワークでは、サーバーへのポストバックを最小限に抑えるために、クライアント側での変換と検証がサポートされています。クライアント側での実装は、通常はオプションです。クライアント側の実装を利用できない場合、フレームワークはJSFの場合と同様に、単にポストバック中にサーバー側のコンバータを呼び出します。

inputNumberSlider、inputNumberSpinboxおよびinputDateなどのように、ポストバックなしのクライアント相互作用をサポートする特定のコンポーネントとともにコンバータを使用する場合には、クライアント側の実装が必要です。あるコンポーネントにとってクライアント側のコンバータが必要かどうかを調べるには、そのコンポーネントのtagdocを参照します。

ADF Facesクライアント側コンバータは、クライアントでJavaScriptが使用されていることを除き、サーバー上の標準JSF変換と同じように動作します。JavaScriptコンバータ・オブジェクトはConverterException例外をスローでき、getAsObject()およびgetAsString()メソッドをサポートします。

7.4.1.3.1 クライアント側バージョンのコンバータの作成

例7-4に示すように、JavaScriptバージョンのコンバータを作成し、関連する情報をコンストラクタに渡します。

例7-4 コンバータ・インタフェース

function TrConverter()
{
}

/**
* Convert the specified model object value, into a String for display
* @param value Model object value to be converted
* @param label label to identify the editableValueHolder to the user
* @return the value as a string or undefined in case of no converter mechanism is
* available (see TrNumberConverter).
*/
TrConverter.prototype.getAsString = function(value, label){}

/**
* Convert the specified string value into a model data object
* which can be passed to validators
* @param value String value to be converted
* @param label label to identify the editableValueHolder to the user
* @return the converted value or undefined in case of no converter mechanism is
* available (see TrNumberConverter).
*/

TrConverter.prototype.getAsObject = function(value, label){}

エラーが発生した場合、クライアントはTrConverterException例外をスローしてTrFacesMessageエラー・メッセージを表示できます。

例7-5に、TrFacesMessageのシグネチャを示します。

例7-5 TrFacesMessageのシグネチャ

/**
* Message similar to javax.faces.application.FacesMessage
* @param summary - Localized summary message text
* @param detail - Localized detail message text
* @param severity - An optional severity for this message.  Use constants
* SEVERITY_INFO, SEVERITY_WARN, SEVERITY_ERROR, and
*   SEVERITY_FATAL from the FacesMessage class.  Default is
*   SEVERITY_INFO
*/
function TrFacesMessage(summary,detail,severity){
..
}

例7-6に、TrFacesExceptionのシグネチャを示します。

例7-6 TrFacesExceptionのシグネチャ

/**
* TrConverterException is an exception thrown by the getAsObject() or getAsString()
* method of a Converter, to indicate that the requested conversion cannot be performed.
* @param facesMessage the TrFacesMessage associated with this exception
* @param summary Localized summary message text, used to create only if facesMessage is null
* @param detail Localized detail message text, used only if facesMessage is null
*/
function TrConverterException(facesMessage, summary, detail){
..
}

7.4.1.3.2 クライアント側での変換を有効にするためのサーバー側コンバータの変更

サーバー側コンバータに変更を加えて、このクラスがクライアント側での変換をサポートすることを示すClientConverterインタフェースを実装します。インタフェース・メソッドの詳細は、http://myfaces.apache.orgにあるClientConverterのjavadocを参照してください。

例7-7に、社会保障番号用のカスタム・コンバータのJavaScript実装を示します。

例7-7 JavaScriptによるクライアント側カスタム・コンバータ

function ssnGetAsString(value)
{
return value.substring(0,3) + '-' +
value.substring(3,5) + '-' +
value.substring(5);
}

function ssnGetAsObject(value)
{
if (!value)
return (void 0);

var len=value.length;
var messageKey = SSNConverter.NOT;
if (len < 9 )
messageKey = SSNConverter.SHORT;
else if (len > 11)
messageKey = SSNConverter.LONG;
else if (len == 9)
{
if (!isNaN(value))
return value;
}
else if (len == 11 && value.charAt(3) == '-' && value.charAt(6) == '-')
{
var result = value.substring(0,3) +
value.substring(4,6) +
value.substring(7);

if (!isNaN(result))
return result;
}

if (messageKey!=void(0) && this._messages!=void(0))
return new ConverterException(this._messages[messageKey]);

return (void 0);
}

function SSNConverter(messages)
{
this._messages = messages;
}

SSNConverter.prototype = new Converter();
SSNConverter.prototype.getAsString = ssnGetAsString;
SSNConverter.prototype.getAsObject = ssnGetAsObject;

SSNConverter.SHORT = 'S';
SSNConverter.LONG  = 'L';
SSNConverter.NOT   = 'N';

例7-8に、社会保障番号用のサーバー側コンバータを実装するJavaクラスを示します。getAsObject()メソッドとgetAsString()メソッドでは、Javaコードの詳細が省略されています。

例7-8 Javaによるサーバー側カスタム・コンバータ

package oracle.adfdemo.view.faces.convertValidate;

import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.convert.Converter;
import javax.faces.convert.ConverterException;

import oracle.adf.view.faces.converter.ClientConverter;
/**
* <p>Social Security number converter.</p>
*
*/
public class SSNConverter implements Converter, ClientConverter
{
public static final String CONVERTER_ID = "oracle.adfdemo.SSN";

public Object getAsObject(
FacesContext context,
UIComponent component,
String value)
{
// some Java code ...
}

public String getAsString(
FacesContext context,
UIComponent component,
Object value)
{
// some Java code ...
}

public String getClientConversion(
FacesContext context,
UIComponent component)
{
// in a real app the messages would be translated
return "new SSNConverter({" +
"S:'Value \"{0}\" in \"{1}\" is too short.'," +
"L:'Value \"{0}\" in \"{1}\" is too long.'," +
"N:'Value \"{0}\" in \"{1}\" " +
"is not a social security number.'})";
}

public String getClientScript(
FacesContext context,
UIComponent component)
{
// check if the script has already been returned this request
Object scriptReturned =
context.getExternalContext().getRequestMap().get(CONVERTER_ID);

// if scriptReturned is null the script hasn't been returned yet
if ( scriptReturned == null)
{
context.getExternalContext().getRequestMap().put(CONVERTER_ID,
Boolean.TRUE);
return  _sSSNjs;
}
// if scriptReturned is not null, then script has already been returned,
// so don't return it again.
else
return null;

}
private static final String _sSSNjs =
"function ssnGetAsString(value)"+
"{return value.substring(0,3) + '-' " +
"+ value.substring(3,5) + '-' + value.substring(5);}" +
"function ssnGetAsObject(value)" +
"{if (!value)return (void 0);" +
"var len=value.length;"+
"var messageKey = SSNConverter.NOT;" +
"if (len < 9 )"+
"messageKey = SSNConverter.SHORT;" +
"else if (len > 11)"+
"messageKey = SSNConverter.LONG;" +
"else if (len == 9)" +
"{ if (!isNaN(value))" +
"return value;" +
"}" +
"else if (len == 11 && value.charAt(3) == '-' && " +
"value.charAt(6) == '-')" +
"{" +
"var result = value.substring(0,3) + value.substring(4,6) + " +
"value.substring(7);"+
"if (!isNaN(result))"+
"return result;" +
"}" +
"if (messageKey!=void(0) && this._messages!=void(0))" +
"return new ConverterException(this._messages[messageKey]);" +
"return void(0);}" +
"function SSNConverter(messages)" +
"{this._messages = messages;}" +
"SSNConverter.prototype = new Converter();" +
"SSNConverter.prototype.getAsString = ssnGetAsString;" +
"SSNConverter.prototype.getAsObject = ssnGetAsObject;" +
"SSNConverter.SHORT = 'S';" +
"SSNConverter.LONG  = 'L';" +
"SSNConverter.NOT   = 'N';";

}

7.4.2 JSFページでのカスタムADF Facesコンバータの使用

カスタムADF Facesコンバータがアプリケーションで特定のデータ型のクラスの下に登録されると、カスタム・コンバータ・オブジェクトと同じ型の値バインディングがコンポーネント値で参照されるたびに、JSFでそのクラスのコンバータが値の変換に自動的に使用されます。この場合、次のコードに示すように、converter属性を使用してカスタム・コンバータをコンポーネントに登録する必要はありません。

<af:inputText value="#{myBean.myProperty}"/>

myPropertyのデータ型は、カスタム・コンバータと同じ型です。かわりに、コンバータ・クラスを入力コンポーネントのconverter属性にバインドすることもできます。

7.5 検証の追加

ユーザーがフィールド内のデータを編集または入力してフォームを送信したときに、設定した規則および条件に対してデータが検証されるように、検証を追加できます。検証に失敗すると、アプリケーションでエラー・メッセージが表示されます。たとえば、図7-3では、af:validateDateTimeRangeコンポーネントによってユーザー入力に対する特定の日付範囲がメッセージ・ヒントに設定されており、無効な値が入力されると、メッセージ・ポップアップ・ウィンドウにエラー・メッセージが表示されます。

図7-3 エラー・メッセージ付き日付範囲バリデータ

クライアント側の検証が必要な場合、ビュー・レイヤーでADF Facesの検証を使用します。ADF Facesに用意されているすべてのバリデータは、クライアント側ピアを持ちます。多くのコンポーネントは、検証を提供する属性を持ちます。詳細は、7.5.1.2項「検証属性の使用」を参照してください。また、ADF Facesは、クライアントとサーバーの両方で実行できる独立した検証クラスを提供します。詳細は、7.5.1.3項「ADF Facesバリデータの使用」を参照してください。独自のバリデータも作成できます。カスタム・バリデータの詳細は、7.6.3項「カスタムJSFバリデータの作成方法」を参照してください。

7.5.1 検証の追加方法

デフォルトでは、ADF Facesの構文およびセマンティク検証は、クライアント側とサーバー側の両方で行われます。クライアント側の検証では、バリデータでデータを捕捉および表示し、サーバーへのラウンドトリップは不要です。

7.5.1.1 ADF Faces検証の追加

ADF Facesでは、次のタイプの検証が提供されます。

- UIコンポーネント属性: ADF Faces入力コンポーネントには、データの検証に使用できる属性が備わっています。たとえば、値が必須かどうかを指定するには、ADF Facesの入力コンポーネントのrequired属性を使用して簡単な検証を指定できます。required属性をtrueに設定した場合、コンポーネントは値を持つ必要があります。コンポーネントが値を持たない場合、アプリケーションによりエラー・メッセージが表示されます。詳細は、7.5.1.2項「検証属性の使用」を参照してください。

- デフォルトADF Facesバリデータ: JSFフレームワークで提供されるバリデータには、日付範囲の検証、入力されたデータの長さの検証などのよく使用される検証チェックが用意されています。詳細は、7.5.1.3項「ADF Facesバリデータの使用」を参照してください。

- カスタムのADF Facesバリデータ: 独自のバリデータを作成して、UIコンポーネントに対して使用するように選択できます。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。

検証が追加されると、検証エラーをページにインラインで、またはポップアップ・ウィンドウに表示できるようになります。検証エラーで作成されたメッセージの表示の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

7.5.1.2 検証属性の使用

多くのADF FacesのUIコンポーネントには、簡単な検証を提供する属性が備わっています。たとえば、af:inputDateコンポーネントには、日付値に使用できる最大値と最小値を指定するmaxValue属性とminValue属性があります。

UIコンポーネントのヘルプを参照するには、「プロパティ」ウィンドウで属性の名前を右クリックし、「ヘルプ」を選択します。

7.5.1.3 ADF Facesバリデータの使用

ADF Facesバリデータは、サーバーまたはクライアントで実行できる個別のクラスです。表7-2に、バリデータとそのロジックを示します。

表7-2 ADF Facesのバリデータ

バリデータ

タグ名

説明

ByteLengthValidator

af:validateByteLength

エンコード時に文字列のバイト数が検証されます。inputTextのmaximumLength属性と似ていますが、これはユーザーが入力できる文字数を限定します。

DateRestrictionValidator

af:validateDateRestriction

入力された日付が、指定された制限に対し有効かどうかが検証されます。

DateTimeRangeValidator

af:validateDateTimeRange

入力された日付が、指定された範囲内かどうかが検証されます。範囲はバリデータの属性として指定します。

DoubleRangeValidator

af:validateDoubleRange

コンポーネント値が指定された範囲内にあるかが検証されます。値は浮動小数点型に変換可能である必要があります。

LengthValidator

af:validateLength

コンポーネントの長さが指定された範囲内にあるかが検証されます。値はjava.lang.String型である必要があります。

LongRangeValidator

af:validateLongRange

コンポーネント値が指定された範囲内にあるかが検証されます。値は数値型か、longデータ型に変換可能なStringである必要があります。

RegExpValidator

af:validateRegExp

Java正規表現構文を使用するデータを検証します。

注意:

コンポーネントにカスタム・バリデータを登録する場合、標準JSFのf:validatorタグを使用します。カスタム・バリデータの使用の詳細は、7.6項「カスタムJSF検証の作成」を参照してください。

ADF Facesバリデータを追加する手順:

1. 「構造」ウィンドウで、バリデータを追加するコンポーネントを右クリックして「componentの中に挿入」を選択し、ADF Facesバリデータを挿入するために「ADF Faces」を選択します。
「JSF」→「バリデータ」を選択してJSF参照実装バリデータを挿入することもできます。

2. バリデータ・タグ(「日付時間範囲の検証」など)を選択し、「OK」をクリックします。

3. JSFページでコンポーネントを選択し、「プロパティ」ウィンドウで、検証エラー用のメッセージなどの値を属性に設定します。
ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。

ADF Facesでは、検証エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailmaximumなどの検証エラー・タイプ)に値を設定することにより、検証に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。

7.5.2 実行時の処理: バリデータの機能の仕方

ユーザーがページを送信すると、ADF Facesで送信された値を確認し、null以外の値に対して変換を実行します。変換された値は、validate()メソッドに渡されます。値が空の場合、コンポーネントのrequired属性が確認され、指定されている場合はエラー・メッセージが生成されます。送信された値がnull以外の場合、検証プロセスが続けられ、コンポーネントのすべてのバリデータが宣言順にコールされます。

注意:

ADF Facesでは、クライアント側サポートのある、JSFバリデータの拡張が提供されます。

ADF Faces検証が検証の処理フェーズで実行されます。エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。モデルの更新フェーズは、変換または検証にエラーがない場合にのみ発生します。コンポーネントのすべての検証が終了すると、モデル・レイヤーに制御が移り、モデルの更新の検証フェーズが実行されます。検証の処理フェーズ同様、エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。

ライフサイクルはレスポンスのレンダリング・フェーズに移り、現在のページが再表示されます。コンポーネントがエラーを生成した場合、ADF Facesはエラーを自動的にハイライト表示します。たとえば、ADF Facesは、検証エラーがある場合に図7-4に示すようにinputTextコンポーネントの周囲に赤いボックスをレンダリングします。

図7-4 検証エラー

検証または変換エラーの発生時のエラー・メッセージの追加の詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

7.5.3 複数バリデータに関する必知事項

UIコンポーネントには、バリデータを設定しないことも、複数設定することもできます。コンポーネントのrequired属性を設定し、バリデータを使用することができます。ただし、required属性をtrueに設定し、値がnullまたは長さがゼロの文字列の場合、コンポーネントは無効化され、コンポーネントに登録された他のバリデータはコールされません。

コンポーネントが空でも有効になるケースが存在する場合は、この組合せでは問題があることがあります。たとえば、ページに「Cancel」ボタンが含まれている場合、ユーザーはデータを入力しなくても、そのボタンをクリックすればページを閉じることができるようにする必要があります。このようなケースを処理するには、「Cancel」ボタンのコンポーネントのimmediate属性をtrueに設定します。この属性により、リクエスト値の適用フェーズ中にアクションを実行できます。次に、デフォルトのJSFアクション・リスナーはFacesContext.renderResponse()をコールして、アクション実行時に検証をバイパスします。詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

7.6 カスタムJSF検証の作成

ビジネス・ニーズに合せて独自の検証ロジックを追加できます。1つのページのコンポーネントにカスタム検証ロジックが必要な場合、ページのバッキングBeanに検証メソッドを作成します。

アプリケーション内の様々なページで再利用されるロジックを作成する場合、またはクライアント側で検証を実行できるようにする場合は、JSFバリデータ・クラスを作成します。その後、クライアント側でバリデータを実行できるADF Faces版を作成します。

7.6.1 バッキングBeanの検証メソッドの作成方法

1つのページのコンポーネントにカスタム検証が必要な場合、必要な検証を提供するメソッドをバッキングBeanに作成します。

始める前に:

カスタムJSF検証に関する知識が役立つ場合があります。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。

バッキングBeanの検証メソッドを追加する手順:

1. 検証の必要なコンポーネントをJSFページに挿入します。

2. ビジュアル・エディタで、コンポーネントをダブルクリックします。

3. 「バインド「バリデータ」プロパティ」ダイアログで検証メソッドを含めるマネージドBeanを入力または選択し、「新規」をクリックして新規のマネージドBeanを作成します。提供されているデフォルト・メソッド・シグネチャを使用するか、ロジックがすでにある場合は既存のメソッドを選択します。
ダイアログで「OK」をクリックすると、JDeveloperでスケルトン・メソッドをコードに追加し、ソース・エディタにBeanを開きます。

4. 必要な検証ロジックを追加します。このロジックでは、javax.faces.validator.ValidatorException例外を使用して適切な例外をスローし、javax.faces.application.FacesMessageエラー・メッセージを使用して対応するエラー・メッセージを生成します。
ValidatorインタフェースとFacesMessageの詳細は、javax.faces.validator.ValidatorExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。

7.6.2 バッキングBeanの検証メソッドを作成するときに行われる処理

検証メソッドを作成すると、選択したマネージドBeanにJDeveloperでスケルトン・メソッドが追加されます。例7-9に、JDeveloperにより生成されるコードを示します。

例7-9 検証メソッドのマネージドBeanコード

public void inputText_validator(FacesContext facesContext,
UIComponent uiComponent, Object object) {
// Add event code here...
}

入力コンポーネントを含むフォームが送信されると、validator属性がバインドされているメソッドが実行されます。

7.6.3 カスタムJSFバリデータの作成方法

カスタム・バリデータを作成するには、インタフェースのValidator実装を作成してから、アプリケーションにカスタム・バリデータを登録することで、検証のビジネス・ロジックを作成する必要があります。バリデータのタグを作成するか、f:validatorタグを使用してカスタム・バリデータをそのタグの属性とすることもできます。

さらに、バリデータのクライアント側バージョンを作成できます。ADF Facesクライアント側検証は、クライアントでJavaScriptが使用されることを除き、サーバー上の標準検証と同じように動作します。JavaScriptバリデータ・オブジェクトはValidatorExceptions例外をスローでき、validate()メソッドをサポートします。

始める前に:

カスタムJSF検証に関する知識が役立つ場合があります。詳細は、7.6項「カスタムJSF検証の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、7.1.2項「ADF Facesコンバータおよびバリデータの追加機能」を参照してください。

カスタムJSFバリデータを作成する手順:

1. javax.faces.validator.Validatorインタフェースを実装するJavaクラスを作成します。Validatorインタフェースを実装するには、実装にpublic no-argsコンストラクタ、属性に対するアクセッサ・メソッドのセットおよびvalidateメソッドを含める必要があります。

public void validate(FacesContext facesContext,
UIComponent uiComponent,
Object object)
throws ValidatorException {
..
}

これらのクラスの詳細は、Javadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。

2. 必要な検証ロジックを追加します。このロジックでは、javax.faces.validate.ValidatorException例外を使用して適切な例外をスローし、javax.faces.application.FacesMessageエラー・メッセージを使用して対応するエラー・メッセージを生成します。
ValidatorインタフェースとFacesMessageの詳細は、javax.faces.validator.ValidatorExceptionおよびjavax.faces.application.FacesMessageのJavadocを参照するか、http://docs.oracle.com/javaee/index.htmlにアクセスしてください。

3. アプリケーションでクライアントに状態を保存する場合、カスタム・バリデータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。
詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照してください。

4. バリデータをfaces-config.xmlファイルに登録します。

1. faces-config.xmlファイルを開きます。
faces-config.xmlファイルは、JDeveloperの「アプリケーション」ウィンドウの、「View_Project」→WEB-INFノードにあります。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 「バリデータ」を選択し、「追加」をクリックしてバリデータ情報を入力します。
「ヘルプ」をクリックするか、[F1]を押すと、バリデータの登録に関する追加のヘルプが表示されます。

バリデータのクライアント版を作成する手順:

1. JavaScript版のバリデータを記述し、関連する情報をコンストラクタに渡します。

2. 2つのメソッドを持つorg.apache.myfaces.trinidad.validator.ClientValidatorインタフェースを実装します。1つ目のメソッドはgetClientScript()で、JavaScriptのValidatorオブジェクトの実装を返します。2つ目のメソッドはgetClientValidation()で、バリデータ・インスタンスのインスタンス化に使用されるJavaScriptコンストラクタを返します。
例7-10に、Javaのバリデータを示します。

例7-10 Javaバリデータ

public String getClientValidation(
FacesContext context,
UIComponent component)
{
return ("new SSNValidator('Invalid social security number.','Value \"{1}\"
must start with \"123\".')");
}

Javaバリデータは、例7-11に示すJavaScriptバリデータをコールします。

例7-11 クライアント側JavaScriptバリデータ

function SSNValidator(summary, detail)
{
this._detail = detail;
this._summary = summary;
}

JSFページでカスタム・バリデータを使用する手順:

- JSFページにタグを持つカスタム・バリデータを使用するには、これをコンポーネントのタグ内に手動でネストさせる必要があります。
例7-12に、inputTextコンポーネント内にネストするカスタム・バリデータ・タグを示します。faces-config.xmlファイル内に宣言されていたバリデータのプロパティの値を提供するためにタグ属性が使用されていることに注意してください。

例7-12 JSFページ上のカスタム・バリデータ・タグ

<h:inputText id="empnumber" required="true">
<hdemo:emValidator emPatterns="9999|9 9 9 9|9-9-9-9" />
</h:inputText>

カスタム・タグを使用せずにカスタム・バリデータを使用する手順:

カスタム・タグを使用せずにカスタム・バリデータを使用するには、f:validatorタグ内にバリデータのIDをネスト(faces-config.xmlファイルで構成されているとおりに)させる必要があります。バリデータのID属性は、使用するバリデータをアプリケーションが動的に決定できるEL式をサポートします。

1. 「構造」ウィンドウから、検証を追加する入力コンポーネントを右クリックし、「componentの中に挿入」→「JSF」→「バリデータ」を選択します。

2. 入力コンポーネントが選択された状態で、「プロパティ」ウィンドウでドロップダウン・リストからバリデータのIDを選択し、「OK」をクリックします。
バリデータのIDをf:validatorタグのプロパティにするコードが、JDeveloperでJSFページに挿入されます。

例7-13に、f:validatorタグを使用するバリデータのJSFページでのコードを示します。

例7-13 JSFページ上のコンポーネントにネストされたカスタム・バリデータ

<af:inputText id="empnumber" required="true">
<f:validator validatorID="emValidator"/>
</af:inputText>

7.6.4 カスタムJSFバリデータを使用するときに行われる処理

カスタムJSFバリデータを使用すると、アプリケーションでカスタム・タグまたはf:validatorタグで参照されるバリデータ・クラスにアクセスし、validate()メソッドを実行します。このメソッドは、検証される値に対してロジックを実行して、その値が有効かどうかを判断します。バリデータが属性を持つ場合、それらの属性もアクセスされ、検証ルーチンで使用されます。標準バリデータ同様、カスタム検証に失敗すると、関連付けられているメッセージがFacesContextインスタンスのメッセージ・キューに置かれます。

8 部分ページ・コンテンツの再レンダリング

この章では、ADF Facesコンポーネントに用意されている部分ページ・レンダリング機能を使用して、ページ全体ではなく、ページの一部をレンダリングする方法について説明します。

この章では、次の項目について説明します。

- 8.1項「部分ページ・レンダリングについて」

- 8.2項「部分トリガーの使用」

- 8.3項「targetタグを使用したPPRの実行」

- 8.4項「部分ページ・レンダリングのプログラムによる有効化」

- 8.5項「部分ページ・ナビゲーションの使用」

8.1 部分ページ・レンダリングについて

Ajax(非同期のJavaScriptおよびXML)は、対話型Webアプリケーションを作成するためのWeb開発手法であり、Ajaxを使用したアプリケーションでは、Webページ全体を再レンダリングせずに少量のデータを内部的にサーバーと交換するため、Webページのレスポンスが向上します。その結果、Webページの対話性、速度および使い勝手が向上します。

ADF Facesでは、Ajaxの部分ページ・レンダリング動作を実現する機能を部分ページ・レンダリング(PPR)と呼びます。PPRでは、JSFページ・リクエスト・ライフサイクル(変換と検証を含む)がページ上の特定のコンポーネントについてのみ実行されます。一部のADF Facesコンポーネントはイベント・ルート・コンポーネントとみなされ、この最適化されたライフサイクルが実行される境界を決定します。

イベント・ルート・コンポーネントは、2通りの方法で決定できます。

- イベント: 特定のイベントはルートであるコンポーネントを示します。たとえば、showDetailコンポーネントを展開または縮小する(9.9項「コンテンツの動的な表示および非表示」を参照)と送信される表示イベントは、showDetailコンポーネントがルートであることを示します。showDetailコンポーネントが展開または縮小されると、そのコンポーネントおよびその子コンポーネントでのみライフサイクルが実行されます。ルート・コンポーネントを識別するその他のイベントの例は、ツリーのノードの展開時の表示イベント、または表でのソート・イベントです。対応するイベント・ルート・コンポーネントを持つイベントの完全なリストは、6.1.1項「イベントおよび部分ページ・レンダリング」の表6-1を参照してください。

- コンポーネント: 一部のコンポーネントは暗黙の境界として認識されるため、ルート・コンポーネントです。たとえば、フレームワークはポップアップ・ダイアログが境界であることを認識します。ダイアログ内でトリガーされたイベントに関係なく、ダイアログ外のコンポーネントでライフサイクルは実行されません。ポップアップでのみ実行されます。
イベント・ルート・コンポーネントとみなされるコンポーネントは、次のとおりです。

- popup

- region

- panelCollection

- calendar

- editableValueHolderコンポーネント(inputTextなど)

この組込みPPR機能で対応できないケースとして、境界の外にあるコンポーネントを最適化されたライフサイクルに含める必要が生じる場合があります。これは、部分トリガー属性を使用して、1つのコンポーネントがトリガーとして機能し、別のコンポーネントがリスナーとして機能するように依存関係を設定することにより、宣言的に構成できます。トリガー・コンポーネントでイベントが発生すると、トリガー・コンポーネントとトリガーの子コンポーネントでライフサイクルが実行され(前述のように)、その後、リスナーが存在する場合はリスナー・コンポーネントとリスナーの子コンポーネントでもライフサイクルが実行されます。

たとえば、必須属性がtrueに設定されたinputTextコンポーネントがページにあるとします。同じページにラジオ・ボタンがあり、選択すると、図8-1に示すようにoutputTextコンポーネントのテキストをページに表示または非表示します。

図8-1 必須フィールドと自動送信のブール

また、必要なテキストをフィールドに入力する前にユーザーがラジオ・ボタンを選択できるようにするとします。送信アクションを自動的にトリガーするようにラジオ・ボタン・コンポーネントを設定し、そのimmediate属性をtrueに設定してinputTextコンポーネントより前に処理されるようにすることもできますが、valueChangeEventリスナーを追加し、その中でレスポンスのレンダリング・フェーズに移って、ラジオ・ボタンが処理されるときに入力テキスト・コンポーネントに対して検証が実行されないようにする必要もあります。

このコードをリスナーに書き込むかわりに、partialTriggersを使用して、ラジオ・ボタンおよび出力テキスト・コンポーネントのみでライフサイクルが実行されるように設定することができます。例5-4に示すように、ラジオ・ボタンをトリガーとし、出力テキストを含むpanelGroupLayoutコンポーネントをターゲットとして設定します。

ヒント:

出力テキストは、非表示として構成されている場合にレンダリングされないため、ターゲットにすることができません。したがって、panelGroupLayoutコンポーネントに配置され、これがターゲットとして構成されます。

例8-1 宣言的なPPRの例

<af:form>
<af:inputText label="Required Field" required="true"/>
<af:selectBooleanRadio id="show" autoSubmit="true" text="Show"
value="#{validate.show}"/>
<af:selectBooleanRadio id="hide" autoSubmit="true" text="Hide"
value="#{validate.hide}"/>
<af:panelGroupLayout partialTriggers="show hide" id="panel">
<af:outputText value="You can see me!" rendered="#{validate.show}"/>
</af:panelGroupLayout>
</af:form>

ラジオ・ボタンのautoSubmit属性がtrueに設定されているため、ボタンが選択されると、SelectionEventが起動され、ラジオ・ボタンがルートとみなされます。panelGroupLayoutコンポーネントが両方のラジオ・コンポーネントのターゲットとして設定されているため、イベントが起動されると、selectBooleanRadio(ルート)、panelGroupLayoutコンポーネント(ルートのターゲット)とその子コンポーネント(outputTextコンポーネント)のみライフサイクルの処理が行われます。outputTextコンポーネントは表示ラジオ・ボタンの選択時にのみレンダリングされるよう構成されているため、ユーザーは、ラジオ・ボタンの上の必須入力フィールドにテキストを入力しなくても、ラジオ・ボタンを選択して出力テキストを表示できます。

ただし、部分トリガー属性を使用してコンポーネント間の依存関係を設定した場合は、トリガー・コンポーネントからのあらゆるイベントにより、ターゲット・コンポーネントとその子コンポーネントの実行とレンダリングが引き起こされます。その結果、検証エラーが発生する場合があります。

たとえば、例8-2に示すように、panelGroupLayout内にoutputTextコンポーネントのかわりにinputTextコンポーネントを使用し、このrequired属性をtrueに設定するとします。

例8-2 PPRで検証されるpanelGroupコンポーネント内のinputTextコンポーネント

<af:form>
<af:selectBooleanRadio id="show1" autoSubmit="true" text="Show"
value="#{validate.show1}"/>
<af:selectBooleanRadio id="hide1" autoSubmit="true" text="Hide"
value="#{validate.hide1}"/>
<af:panelGroupLayout partialTriggers="show1 hide1">
<af:inputText label="Required Field" required="true"
rendered="#{validate.show1}"/>
</af:panelGroupLayout>
</af:form>

この例では、ライフサイクルはルート(selectBooleanRadioコンポーネント)、ターゲット(panelGroupLayoutコンポーネント)およびターゲットの子(inputTextコンポーネント)で実行されるため、inputTextコンポーネントは検証されます。inputTextコンポーネントが必須としてマークされているため、値がないと、検証が失敗し、エラーがスローされます。エラーのため、ライフサイクルはレスポンスのレンダリング・フェーズに移り、ラジオ・ボタンにバインドされているモデル値は更新されません。このため、ラジオ・ボタンの値が更新されず、panelGroupLayoutコンポーネントは表示または非表示にできません。

このようなケースに対しては、コンポーネントによって特定のイベント(1つまたは複数)が起動されたときに、どのターゲットを実行し、どのターゲットをレンダリングするかを明示的に構成することができます。この新しい例では、selectBooleanRadioボタンで発生したvalueChangeイベントによってPPRをトリガーしますが、panelGroupLayoutコンポーネントとその子コンポーネントでライフサイクルを実行するかわりに、ラジオ・ボタンでのみ実行します。ただし、フォーム全体をレンダリングする必要があります。そのレンダリングの実行時に、inputTextコンポーネントをレンダリングするかどうかを決定できます。PPRを引き起こすイベントと、実行およびレンダリングの対象にするコンポーネントを明示的に決定する必要がある場合は、targetタグを使用します。例8-3に、これを行うJSFコードを示します。

例8-3 PPRに含めるイベントとコンポーネントを決定するtargetタグ

<af:panelFormLayout id="pfl1">
<af:selectBooleanRadio id="show2" autoSubmit="true" text="Show"
value="#{validate.show2}"/>
<af:target events="valueChange" execute="show2 hide2" render="pfl1"/>
<af:selectBooleanRadio id="hide2" autoSubmit="true" text="Hide"
value="#{validate.hide2}"/>

<af:target events="valueChange" execute="hide2 show2" render="pfl1"/>
<af:panelGroupLayout id="pgl1">
<af:inputText label="Required Field" required="true"
rendered="#{validate.show2}"/>
</af:panelGroupLayout>
</af:panelFormLayout>

この例では、どちらかのselectBooleanRadioコンポーネントからvalueChangeイベントが起動された場合に、selectBooleanRadioコンポーネントのみでライフサイクルが実行される一方で、panelFormLayoutコンポーネント全体がレンダリングされます。

ヒント:

アプリケーションでFusionテクノロジ・スタックを使用する場合、任意のページで自動部分ページ・レンダリング機能を有効にできます。これによって、バックエンド・ビジネス・ロジックの結果として値が変更されるコンポーネントが自動的に再レンダリングされます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の部分ページ・レンダリングとイテレータ・バインディングに関する必知事項を参照してください。

また、ADF FacesアプリケーションはナビゲーションにPPRを使用できます。標準JSFアプリケーションでは、あるページから次のページへのナビゲーションには新しいページのレンダリングが必要です。Ajaxのようなコンポーネントを使用する場合、様々なJavaScriptライブラリおよびスタイル・シートのダウンロードに必要な時間により、これがオーバーヘッドの原因になることがあります。このコストの高いオーバーヘッドを回避するために、ADF Facesアーキテクチャは、実際には単一ページに残ったままオプションで完全ページ遷移をシミュレートすることで、JavaScriptコードおよびスキン・スタイルの再ロードの必要性を回避できます。

注意:

PPRが機能するためには、ブラウザでJavaScriptが有効になっている必要があります。

8.2 部分トリガーの使用

部分トリガーを使用した場合、トリガー・コンポーネントと呼ばれるコンポーネントでイベントが発生すると、ターゲット・コンポーネントと呼ばれるコンポーネントが再レンダリングされます。

たとえば、図8-2に示すように、File Explorerアプリケーションには「検索」パネルに検索結果を表示する表が含まれています。検索ボタンを使用すると、この表(この表のみ)がレンダリングされます。検索ボタンがトリガーとして構成され、表がターゲットとして構成されています。このボタンからイベントが起動されると、表とそのコンポーネントでライフサイクルが実行されます(ボタンと同様に)。

図8-2 検索ボタンで再レンダリングされる表

注意:

トリガー・コンポーネントに関連付けられているすべてのイベントではなく、特定のイベントが発生したときにのみ、コンポーネントを実行またはレンダリングすることが必要になる場合があります。このような場合には、targetタグを使用する必要があります。詳細は、8.3項「targetタグを使用したPPRの実行」を参照してください。コンポーネントを実行またはレンダリングするかどうかをなんらかのロジックによって決める必要がある場合は、プログラムによってPPRを有効にすることができます。詳細は、8.4項「部分ページ・レンダリングのプログラムによる有効化」を参照してください。

トリガー・コンポーネントで、PPRリクエストが発生したことをフレームワークに通知する必要があります。コマンド・コンポーネントでは、partialSubmit属性をtrueに設定することでこれを行えます。これを行うと、コマンド・コンポーネントがクリックされるたびに部分ページ・リクエストが発生します。

たとえば、ページにinputTextコンポーネント、buttonコンポーネントおよびoutputTextコンポーネントが含まれているとします。ユーザーがinputTextコンポーネントに値を入力してbuttonコンポーネントをクリックすると、入力値がoutputTextコンポーネントに反映されます。このbuttonコンポーネントのpartialSubmit属性をtrueに設定できます。

ただし、コマンド・コンポーネント以外のコンポーネントでPPRをトリガーできます。ADF Facesの入力コンポーネントと選択コンポーネントには、値が変更されると部分ページ・リクエストを自動的にトリガーする機能があります。この機能を使用するには、入力または選択コンポーネントのautoSubmit属性を使用して、値が入力されて送信されると、valueChangeEventイベントが発生するようにします。ターゲット・コンポーネントが設定されているかぎり、フレームワークにPPRを実行するよう通知するのはこのイベントです。前述の例で、buttonコンポーネントを削除し、かわりにinputTextコンポーネントのautoSubmit属性をtrueに設定することもできます。値が変更されるたびに、PPRリクエストが起動されます。

ヒント:

入力コンポーネントのautoSubmit属性とコマンド・コンポーネントのpartialSubmit属性は同じものではありません。partialSubmitがtrueに設定されている場合、partialTriggers属性に値を持つコンポーネントのみでライフサイクルが実行されます。

autoSubmit属性は、入力コンポーネントと選択コンポーネントで使用され、値が変更されると自動的にフォームを送信するようフレームワークに指示します。autoSubmit属性がtrueに設定されている場合にフォームが送信されると、valueChangeEventイベントが起動され、ライフサイクルはそのイベントのルートとされているコンポーネントとその子でのみ実行されます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

PPRがトリガーされると、ターゲットとして構成されているすべてのコンポーネントでライフサイクルが実行されます。コンポーネントは、partialTriggers属性をトリガー・コンポーネントの相対IDに設定することで、ターゲットとして構成します。相対IDの詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。

たとえば、inputTextコンポーネントに対する変更を受けてoutputTextを更新するには、partialTriggers属性をinputTextコンポーネントの相対IDに設定します。

コンポーネントのイベントには、たとえばshowDetailコンポーネントのdisclosureイベントや表のsortイベントのように、デフォルトでPPRをトリガーするものがあるため、注意が必要です。これは、partialTriggers属性をそのコンポーネントのIDに設定することでターゲットに対して構成された任意のコンポーネントが、これらのタイプのイベントの発生時に再レンダリングすることを意味します。PPRをトリガーするイベントを限定するには、partialTriggers属性を使用するかわりに、targetタグを使用する必要があります。このタグを使用すれば、どのイベントがPPRを引き起こすかを明示的に設定できます。

partialTriggers属性のかわりにtargetタグを使用する必要があるもう1つの例として、トリガー・コンポーネントがinputLovまたはinputComboBoxLovで、ターゲット・コンポーネントがrequiredに設定された依存入力コンポーネントであるケースがあげられます。このケースでは、LOVポップアップが表示されたときに、入力コンポーネントに対して検証エラーがスローされます。かわりにtargetタグを使用すると、どのコンポーネントを実行するかと(LOV)、どのコンポーネントをレンダリングするかを(入力コンポーネント)、明示的に設定できます。詳細は、8.3項「targetタグを使用したPPRの実行」を参照してください。

8.2.1 部分トリガーの使用方法

別のコンポーネントで発生したイベントに基づいてコンポーネントをレンダリングするには、どのコンポーネントがトリガーかを宣言する必要があります。

ベスト・プラクティス:

同じページに対して部分トリガーとtargetタグの両方を使用しないでください。判断がつかないときには、targetタグのみを使用します。詳細は、8.3項「targetタグを使用したPPRの実行」を参照してください。

始める前に:

宣言的な部分ページ・レンダリングに関する知識が役立つ場合があります。詳細は、8.2項「部分トリガーの使用」を参照してください。

部分トリガーを使用するには:

1. 構造ウィンドウで、トリガー・コンポーネント(そのアクションによってPPRが起こるコンポーネント)を選択します。

- 「プロパティ」ウィンドウの「共通」セクションを開き、id属性が設定されていない場合は設定します。値はそのコンポーネントのネーミング・コンテナ内で一意である必要があります。コンポーネントがネーミング・コンテナ内に含まれていない場合、IDはページで一意である必要があります。ネーミング・コンテナの詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。

ヒント:

JDeveloperは、コンポーネントIDを自動的に割り当てます。この値を安全に変更できます。コンポーネントのIDは、有効なXML名であることが必要です。つまり、名前の先頭に数字を使用したり、IDにスペースを使用することはできません。JSFではIDでのコロン(:)も禁止されています。

- トリガー・コンポーネントがコマンド・コンポーネントの場合、「プロパティ」ウィンドウで「動作」セクションを開き、partialSubmit属性をtrueに設定します。

- トリガー・コンポーネントがフォーム内の入力または選択コンポーネントで、値を送信する場合は、「プロパティ」ウィンドウの「動作」セクションを開き、コンポーネントのautoSubmit属性をtrueに設定します。

注意:

コンポーネントで値を送信する場合のみ、autoSubmit属性をtrueに設定します。値を送信しない場合、他のロジックを使用してコンポーネントでValueChangeEventイベントを起動する必要があります。このイベントによってデフォルトでPPRが起こり、トリガー・コンポーネントをpartialTriggers属性の値として持つコンポーネントが再レンダリングされます。

2. 構造ウィンドウで、PPRのトリガー元イベントが発生したときに再レンダリングするターゲット・コンポーネントを選択します。

3. 「プロパティ」ウィンドウの「動作」セクションを開き、partialTriggers属性にカーソルを合わせたときに表示されるアイコンをクリックして「編集」を選択します。

4. 「属性の編集」ダイアログで、トリガー・コンポーネントを選択済パネルに移動し、「OK」をクリックします。トリガー・コンポーネントがネーミング・コンテナ内にある場合、JDeveloperで相対パスが自動的に作成されます。

ヒント:

selectBooleanRadioコンポーネントは、部分ページ・レンダリングで1つのコンポーネントのように動作しますが、実際は複数コンポーネントです。したがって、グループ内の異なるselectBooleanRadioの選択に基づいて他のコンポーネント(inputTextコンポーネントなど)を変更する場合、親コンポーネント内にまとめ、親コンポーネントのpartialTriggers属性がすべてのSelectBooleanRadioコンポーネントを指すように設定する必要があります。

例8-4に、PPRを実行するよう構成されたlinkコンポーネントを示します。

例8-4 部分送信を介して部分ページ・レンダリングを有効化するためのコード

<af:link id="deleteFromCart" partialSubmit="true"
actionListener="#{homeBean...}" text="Delete From Cart">

例8-4に示したIDがdeleteFromCartのリンクがクリックされると再レンダリングされるoutputTextコンポーネントを、例8-5に示します。

例8-5 他のコンポーネントによってトリガーされる部分ページ・レンダリングのコード

<af:outputText id="estimatedTotalInPopup"
partialTriggers="deleteFromCart"
value="#{shoppingCartBean...}"/>

ヒント:

PPRの最中にページ上のコンポーネントが検証されないようにするには、targetタグを使用する必要があります。詳細は、8.3項「targetタグを使用したPPRの実行」を参照してください。

8.2.2 ブラウザの戻るボタンの使用に関する必知事項

ADF Facesアプリケーションでは、一部のコンポーネントで(暗黙的に、あるいは部分トリガーをリスニングするよう構成されていて)PPRが使用されるため、ユーザーがブラウザの戻るボタンをクリックしたときの動作は、単にJSFコンポーネントを使用するアプリケーションとは多少異なります。

単純なJSFコンポーネントを使用するアプリケーションでは、ユーザーがブラウザの戻るボタンをクリックすると、最後にレンダリングされたときのDocument Object Model (DOM)の状態にページがブラウザによって戻されます。しかし、JavaScriptの状態は、ユーザーが最初にページにアクセスしたときの状態です。

たとえば、ユーザーがPageAにアクセスしたとします。ユーザーがページ上のコンポーネントと対話した後で、PPRイベントがJavaScriptを使用して発生したとします。この新しいバージョンのページをPageA1と呼びます。次に、ユーザーがPageBにナビゲートし、ブラウザの戻るボタンをクリックしてPageAに戻るとします。PageA1上にはDOMがあったためユーザーにはDOMが表示されますが、JavaScriptは実行されないため、ページの一部はPageAの場合と同様になります。これは、ページに対する変更が失われることを意味する場合があります。ページをリフレッシュするとJavaScriptが実行されるため、ユーザーはPageA1を表示していたときの状態に戻ります。ADF Facesを使用するアプリケーションでは、リフレッシュは不要ですが、フレームワークは組込みサポートを提供するため、戻るボタンがクリックされるとJavaScriptが実行されます。

8.2.3 PPRとスクリーン・リーダーに関する必知事項

スクリーン・リーダーでは、部分ページ・リクエストで全ページの再読上げは実行されません。PPRによって、スクリーン・リーダーは部分ページ・リクエストを起動したコンポーネントから始まるページを読み込みます。ターゲット・コンポーネントは、部分リクエストを起動するコンポーネントの後に配置する必要があります。このようにしないと、更新したターゲット・コンポーネントがスクリーン・リーダーに読み込まれません。

8.3 targetタグを使用したPPRの実行

多くのイベントが関連付けられている表などのコンポーネントでは、イベントがトリガーされるたびにPPRが発生し、その表の子コンポーネントや、その表を部分トリガーとするコンポーネントが実行およびレンダリングされます。特定のイベントが発生した場合にのみコンポーネントがレンダリングまたは実行されるようにする場合や、特定のコンポーネントのみが実行またはレンダリングされるようにする場合は、targetタグを使用します。

特定の状況でコンポーネントの検証をスキップする必要がある場合には、targetタグが特に役立ちます。たとえば、図8-3に示すような、必須フィールドと「Submit」ボタンおよび「Cancel」ボタンを含むフォームがあるとします。

図8-3 「Cancel」ボタンがクリックされると処理される必須フィールド

通常の状況では、「Cancel」ボタンがクリックされるとフォーム内のすべてのフィールドが処理されます。入力テキストフィールドは必須であるため、その検証は失敗します。

この失敗を回避するには、targetタグを「Cancel」ボタンの子として使用します。targetタグを使用すると、特定のイベント(1つまたは複数)がコンポーネントによって起動されたときに、どのターゲットを実行およびレンダリングするかを記述できます。この例では、例8-6に示すように、「Cancel」ボタンのtargetタグをそのボタンのみが実行されるように構成しています。

例8-6 どのコンポーネントを実行およびレンダリングするかを決定するボタンのtargetタグ

<af:panelFormLayout id="pfl1" labelAlignment="top">
. . .
<af:panelLabelAndMessage id="plam12" for="it3">
<af:inputText label="Required Field" required="true"
rendered="#{validate.show3}" id="it3"/>
</af:panelLabelAndMessage>
<af:panelGroupLayout layout="horizontal" id="pgl9">
<af:button text="submit" partialSubmit="true" id="cb2"
<af:target execute="@this it3" render="pfl1"/>
</af:button>
<af:button actionListener="#{validate.handleCancel}"
partialSubmit="true" text="cancel" id="cb1">
<af:target execute="@this"/>
</af:button>
</af:panelGroupLayout>
</af:panelFormLayout>

この例では、「Submit」ボタンがクリックされると、そのボタンとinputTextコンポーネントが実行され、panelFormLayoutコンポーネントのコンテンツがレンダリングされます。ただし、「Cancel」ボタンがクリックされた場合は、「Cancel」ボタンのみが実行されます。そのクリックの結果としてレンダリングされるものは何もありません。

LOVコンポーネントと依存入力テキスト・コンポーネントを使用する場合には、検証に関する別の一般的な問題が生じることがあります。たとえば、ユーザーが従業員名を選択するためのinputListOfValuesコンポーネントがあるとします。ユーザーがLOVから名前を選択したときに従業員番号入力テキストフィールドにその従業員の番号が自動的に移入されるようにするとともに、そのフィールドを必須フィールドにします。

LOVをトリガーとして設定して部分トリガーを使用し、入力テキスト・コンポーネントをターゲットとして使用すると、その入力テキスト・コンポーネントはポップアップが閉じたときに検証に失敗します。ユーザーが検索アイコンをクリックすると、ライフサイクルがルート(inputListOfValuesコンポーネント)とターゲット(inputTextコンポーネント)の両方で実行されるため、inputTextコンポーネントが検証されます。図8-4に示すように、inputTextコンポーネントが必須としてマークされているのに値がないため、検証が失敗します。

図8-4 値が必須であるため検証エラーがスローされる

かわりに、例8-7に示すようにtargetタグをinputListOfValuesコンポーネントの子として使用して、inputListOfValuesコンポーネントのみが実行され、入力テキスト・コンポーネントが新しく選択された値でレンダリングされるように構成することができます。

例8-7 LOVコンポーネントでのtargetタグの使用

<af:panelFormLayout id="pfl2">
<af:inputListOfValues label="Ename" id="lov21" required="true"
value="#{validateLOV.ename}" autoSubmit="true"
popupTitle="Search and Select: Ename" searchDesc="Choose a name"
model="#{validateLOV.listOfValuesModel}"
validator="#{validateLOV.validate}">
<af:target execute="@this" render="it1"/>
</af:inputListOfValues>
<af:inputText label="Empno" value="#{validateLOV.empno}" required="true"
id="it1"/>

</af:panelFormLayout>

8.3.1 targetタグを使用して部分ページ・レンダリングを有効にする方法

targetタグは、PPRを引き起こすイベントの発生元となるコンポーネントの子として配置します。たとえば、図8-3のフォームの場合は、targetタグを「Cancel」ボタンの子として配置します。その後、PPRに含めるイベントとコンポーネントを明示的に指定します。

ベスト・プラクティス:

同じページに対して部分トリガーとtargetタグの両方を使用しないでください。判断がつかないときには、targetタグのみを使用します。

始める前に:

formコンポーネントに関する知識が役立つ場合があります。詳細は、8.3項「targetタグを使用したPPRの実行」を参照してください。

targetタグを使用するには:

1. 「コンポーネント」ウィンドウで、「操作」パネルから「ターゲット」をドラッグし、PPRを制御するイベントをトリガーするコンポーネントの子としてドロップします。

2. 「プロパティ」ウィンドウで、次を設定します。

- Events: そのコンポーネントでtargetタグによって処理するイベントの空白区切りリストを入力します。次のイベントがサポートされています。

- action

- calendar

- calendarActivity

- calendarActivity

- durationChange

- calendarDisplayChange

- carouselSpin

- contextInfo

- dialog

- disclosure

- focus

- item

- launch

- launchPopup

- poll

- popupCanceled

- popupFetch

- query

- queryOperation

- rangeChange

- regionNavigation

- return

- returnPopupData

- returnPopup

- rowDisclosure

- selection

- sort

- valueChange

コンポーネントが実行するイベントのうち、このリストに含めなかったものは、フレームワークによって通常どおりに処理されます。

コンポーネントのすべてのイベントをtargetタグで制御する場合は、@allキーワードを使用します。

デフォルトは@allです。

- Execute: event属性で指定されたリストに含まれるイベント(1つまたは複数)が発生したときに実行するコンポーネントのコンポーネントIDの空白区切りリストを入力します。コンポーネントIDのかわりに、次のキーワードを使用できます。

- @this: ターゲットの親コンポーネントのみが実行されます。

- @all: 同じaf:formタグ内のすべてのコンポーネントが実行されます。これを使用すると、すべてのコンポーネントが通常のページ・ライフサイクルの中で実行されるため、実際にはPPRが行われません。

- @default: イベント・ルート・コンポーネントまたは部分トリガーを使用して(つまりtargetタグが使用されていないかのように)コンポーネントの実行が処理されます。この値がデフォルトです。

注意:

JSFタグf:ajaxでは@noneキーワードがサポートされていますが、af:targetタグではサポートされません。

- Render: event属性で指定されたリストに含まれるイベント(1つまたは複数)が発生したときにレンダリングするコンポーネントのコンポーネントIDの空白区切りリストを入力します。コンポーネントIDのかわりに、次のキーワードを使用できます。

- @this: ターゲットの親コンポーネントのみがレンダリングされます。

- @all: 同じaf:formタグ内のすべてのコンポーネントがレンダリングされます。

- @default: コンポーネントのレンダリングはフレームワークによって決定されます。この値がデフォルトです。

図8-3に示されているラジオ・ボタンと必須フィールドを備えたフォームのコードを、例8-8に示します。最初のtargetタグは、show3ラジオ・ボタンの子であり、show3およびhide3ラジオ・ボタンを実行してpanelFormLayoutをレンダリングするように構成されているため、そのボタンが選択されると、2つのラジオ・ボタンのみでライフサイクルが実行され、フォーム全体がレンダリングされます。inputTextコンポーネントは、executeリストに含まれていないため実行されませんが、フォームに含まれているためレンダリングされます。

targetタグは、「Submit」ボタンと「Cancel」ボタンでも使用されています。「Submit」ボタンの場合、入力テキスト・コンポーネントでライフサイクルを実行する必要があるため、そのターゲットのexecute属性に対する値のリストに、「Submit」ボタンとともに入力テキスト・コンポーネントも指定されています。ただし、「Cancel」ボタンの場合は、入力テキスト・コンポーネントを処理しないため、そのターゲットのexecute属性に対する値のリストに入力テキスト・コンポーネントは含まれていません。したがって、検証エラーがスローされることはありません。

例8-8 targetタグの使用による検証の問題の回避

<af:panelFormLayout id="pfl1">
<af:panelLabelAndMessage label="Show/Hide Field" id="plam11">
<af:selectBooleanRadio id="show3" autoSubmit="true" text="Show" group="group3"
value="#{validate.show3}">
<af:target execute="show3 hide3" render="pfl1"/>
</af:selectBooleanRadio>
<af:selectBooleanRadio id="hide3" autoSubmit="true" text="Hide" group="group3"
value="#{validate.hide3}">
<af:target execute="hide3 show3" render="pfl1"/>
</af:selectBooleanRadio>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="Required Field" id="plam12" showRequired="true">
<af:inputText label="Required Field" required="true" simple="true"
rendered="#{validate.show3}" id="it3"/>
</af:panelLabelAndMessage>
<af:panelGroupLayout layout="horizontal" id="pgl9">
<f:facet name="separator">
<af:spacer width="2px" id="s7"/>
</f:facet>

<af:commandButton text="submit" partialSubmit="true"
disabled="#{validate.hide3}" id="cb2">
<af:target execute="@this it3" render="pfl1"/>
</af:commandButton>
<af:commandButton actionListener="#{validate.handleCancel}"
partialSubmit="true" text="cancel" id="cb1">
<af:target execute="@this" render="ot10"/>
</af:commandButton>

<af:outputText clientComponent="true"
value="Cancel Click: #{validate.clickCount}" id="ot10"/>
</af:panelGroupLayout>

8.4 部分ページ・レンダリングのプログラムによる有効化

特定のロジックに基づいてターゲットをレンダリングする必要がある場合は、プログラムによって部分ページ・レンダリングを有効にすることができます。

8.4.1 部分ページ・レンダリングをプログラムで有効にする方法

部分ページ・レンダリングを有効にするにはaddPartialTargetメソッドを使用します。

PPRをプログラムによって有効にする手順:

1. ターゲット・コンポーネントがレンダリングされる原因となるイベントのリスナー・メソッドを作成します。

addPartialTarget()メソッドを使用して、イベントがトリガーされると部分ターゲット・コンポーネントが再レンダリングされるよう、そのイベントの部分ターゲットとしてコンポーネントを追加します(そのIDを使用)。このメソッドを使用して、再レンダリングするコンポーネントと再レンダリングをトリガーするイベントを関連付けます。

たとえば、File ExplorerアプリケーションにはNavigatorManager.refresh()メソッドが含まれています。起動されると、ナビゲータ・アコーディオンが再レンダリングされます。

例8-9 部分ターゲットを使用した再レンダリング

public void refresh()
{
for (BaseNavigatorView nav: getNavigators())
{
nav.refresh();
}

AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
adfFacesContext.addPartialTarget(_navigatorAccordion);
}

2. JSFページで、ターゲット・コンポーネントを選択します。「プロパティ」ウィンドウで、コンポーネントIDを入力してClientComponentをtrueに設定します。

注意:

clientComponent属性をtrueに設定して、クライアントIDが生成されるようにします。

3. 「プロパティ」ウィンドウで、リフレッシュおよび手順1で作成したリスナー・メソッドへのバインドを引き起こすイベントのリスナーを見つけます。

8.5 部分ページ・ナビゲーションの使用

従来のページ全体の遷移のかわりに、PPRリクエストを使用してナビゲーションがトリガーされるように、ADF Facesアプリケーションを構成できます。新しいページは、PPRを使用してクライアントに送信されます。部分ページ・ナビゲーションは、デフォルトでは無効になっています。

部分ページ・ナビゲーションが使用される場合、位置を把握しておく(ブックマーク用、リフレッシュが行われたとき用など)ために、フレームワークでURLのハッシュ部分を使用します。URLのこの部分には、ブラウザに表示される実際のページが含まれます。

また、JavaScriptおよびCSSは各ページにロードされません。resourceタグを使用して、現在のページに固有のJavaScriptおよびCSSコンテンツを含める必要があります。<f:verbatim>または<trh:stylesheet>タグは機能しません。詳細は、4.2項「JavaScriptのページへの追加」を参照してください。

アプリケーションで部分ページ・ナビゲーションが有効になっている場合、getリクエストはボタンおよびリンク・コンポーネントに対してサポートされます。

注意:

PPR getリクエストは、Internet Explorerでサポートされません。このブラウザを使用する場合、URLは標準の取得リクエストを使用してロードされます。

他のブラウザの場合、これらのコンポーネントのgetリクエストはアプリケーション内のページに対してのみサポートされます。

8.5.1 部分ページ・ナビゲーションの使用方法

部分ページ・ナビゲーションは、web.xmlファイルのoracle.adf.view.rich.pprNavigation.OPTIONSコンテキスト・パラメータをonに設定することで有効にできます。

始める前に:

部分ページ・ナビゲーションに関する知識が役立つ場合があります。詳細は、8.5項「部分ページ・ナビゲーションの使用」を参照してください。

部分ページ・ナビゲーションを使用する手順:

1. web.xmlファイルをダブルクリックします。

2. ソース・エディタで、oracle.adf.view.rich.pprNavigation.OPTIONSパラメータを次のいずれかに変更します。

- on: 部分ページ・ナビゲーションを有効にします。

注意:

パラメータをonに設定する場合、ナビゲーションに含まれるコマンド・コンポーネントのpartialSubmit属性をtrueに設定する必要があります。

- onWithForcePPR: 部分ページ・ナビゲーションを有効にし、すべてのアクション・イベント(ナビゲーションが行われないアクション・イベントも含む)でPPRチャネルを使用するためのフレームワークを通知します。部分ページ・ナビゲーションでは、PPRチャネルを介してアクション・イベントを送信する必要があるため、このオプションを使用して部分ページ・ナビゲーションを簡単に有効化できます。
部分ページ・ナビゲーションを使用している場合、通常はページのビジュアル・コンテンツのみ再レンダリングされます(ヘッダー・コンテンツはすべてのページで一定のままです)。ただし、ページのアクションがフル・ページ送信を使用するように定義されている場合、およびアクションでナビゲーションが行われない場合も、ドキュメント全体が再レンダリングされます。

8.5.2 PPRナビゲーションに関する必知事項

PPRナビゲーションを使用する前に、次の点に注意します。

- PPRナビゲーションを使用する場合、このナビゲーションに関連するすべてのページで同じCSSスキンを使用する必要があります。

- resourceタグを使用して、現在のページに固有のJavaScriptおよびCSSコンテンツを含める必要があります。

- 標準のページ・ナビゲーションとは異なり、部分ナビゲーションではJavaScriptグローバル(グローバル・スコープに定義されている変数および関数)はアンロードされません。これが発生するのは、ウィンドウ・オブジェクトが部分ページの遷移でも残るためです。ページ固有のグローバル変数および関数を使用するアプリケーションでは、AdfPage.getPageProperty()メソッドおよびAdfPage.setPageProperty()メソッドを使用して、それらのオブジェクトを格納する必要があります。

第III部

レイアウトの作成

第III部には、次の章が含まれています。

- 第9章「Webページ上のコンテンツの編成」

- 第10章「フラグメント、ページ・テンプレート、コンポーネントの作成および再利用」

9 Webページ上のコンテンツの編成

この章では、ADF Facesのいくつかのレイアウト・コンポーネントを使用して、Webページ上のコンテンツを編成する方法を説明します。

この章では、次の項目について説明します。

- 9.1項「Webページ上のコンテンツの編成について」

- 9.2項「ページ・レイアウトの開始」

- 9.3項「グリッドでのコンテンツの配置」

- 9.4項「コンテンツをページ全体に拡大するための設定」

- 9.5項「スプリッタを使用したサイズ変更可能なペインの作成」

- 9.6項「事前定義済固定領域へのページ・コンテンツの配置」

- 9.7項「フォームでのコンテンツの配置」

- 9.8項「ダッシュボードでのコンテンツの配置」

- 9.9項「コンテンツの動的な表示および非表示」

- 9.10項「パネルにおけるコンテンツの表示または非表示」

- 9.11項「静的ボックスの項目の表示」

- 9.12項「1つ以上の列における箇条書きリストの表示」

- 9.13項「関連する項目のグループ化」

- 9.14項「空白または線を使用したコンテンツの分割」

9.1 Webページ上のコンテンツの編成について

ADF Facesには、その他のコンポーネントをページに配置する際に使用可能なレイアウト・コンポーネントが多数用意されています。通常、これらのコンポーネントを使用してページの作成を開始します。その後、その他の機能(データやボタンのレンダリングなど)を提供するコンポーネントを、ファセット内またはレイアウト・コンポーネントの子コンポーネントとして追加します。

ヒント:

アプリケーション内のページのレイアウトを設計できるページ・テンプレートを作成できます。テンプレートはアプリケーションのすべてのページで使用できます。詳細は、第10章「フラグメント、ページ・テンプレート、コンポーネントの作成および再利用」を参照してください。

コンテナとして機能するレイアウト・コンポーネントに加え、ADF Facesには、コンテンツの表示や非表示、またはセクション、リスト、空白の表示が可能な対話型のレイアウト・コンポーネントもあります。一部のレイアウト・コンポーネントには、ウィンドウのサイズが変更された場合にブラウザ・ウィンドウに合せてコンテンツが拡大する機能や、拡大するコンポーネント内に配置された場合には拡大する機能などのジオメトリ管理機能もあります。レイアウト・コンポーネントの拡大およびジオメトリ管理機能の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

表9-1では、ADF Facesの各レイアウト・コンポーネントを簡単に説明しています。

表9-1 ADF Facesのレイアウト・コンポーネント

コンポーネント

説明

子の拡大

拡大

ページ管理コンポーネント

document

HTMLページの標準の各ルート要素(<html>、<body>および<head>)を作成します。すべてのページにこのコンポーネントを使用する必要があります。詳細は、9.2項「ページ・レイアウトの開始」を参照してください。

X

form

HTMLの<form>要素を作成します。詳細は、9.2項「ページ・レイアウトの開始」を参照してください。

ページ・レイアウト・コンテナ

panelGridLayout

gridRowおよびgridCellコンポーネントとともに使用され、HTML表に類似したレイアウトを提供します。ここで行とセルを定義し、他のコンポーネントをセルの子として配置します。詳細は、9.3項「グリッドでのコンテンツの配置」を参照してください。

X (gridRowおよびgridCellコンポーネントが拡大するように構成されている場合)

X (dimensionsFrom属性がparentに設定されている場合)

panelStretchLayout

他のコンポーネントを配置できるtop、bottom、start、centerおよびendファセットを含みます。詳細は、9.4項「コンテンツをページ全体に拡大するための設定」を参照してください。

X

X (dimensionsFrom属性がparentに設定されている場合)

panelSplitter

再配置可能な仕切線を使用してリージョンを2つの部分(firstファセットおよびsecondファセット)に分割します。このファセットには別のコンポーネントを配置できます。詳細は、9.5項「スプリッタを使用したサイズ変更可能なペインの作成」を参照してください。

X

X (dimensionsFrom属性がparentに設定されている場合)

panelDashboard

子コンポーネント(通常はpanelBoxコンポーネント)の縦表示を提供します。詳細は、9.8項「ダッシュボードでのコンテンツの配置」を参照してください。

X

X (dimensionsFrom属性がparentに設定されている場合)

panelBorderLayout

中心に配置できる子コンポーネントを持つことができ、12のファセットと追加コンポーネントを配置できる枠線も含みます。これらは中心を囲みます。詳細は、9.6項「事前定義済固定領域へのページ・コンテンツの配置」を参照してください。

panelFormLayout

ラベルやフィールドが縦に並ぶように、inputTextコンポーネントなどの入力フォーム・コントロールを配置します。複数の列をサポートしており、footerファセットが含まれます。詳細は、9.7項「フォームでのコンテンツの配置」を参照してください。

表示/非表示機能のあるコンポーネント

showDetailHeader

ヘッダーの下のコンテンツを表示または非表示にできます。通常、panelHeaderコンポーネントの子として使用されます。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

X (type属性がstretchに設定されている場合)

X (type属性がstretchに設定されている場合)

showDetailItem

panelAccordionの各ペイン、またはpanelTabbedコンポーネントの各タブのコンテンツを保持するために使用されます。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

X(単一の子コンポーネントを含み、そのstretchChildren属性がfirstに設定されている場合)。

panelBox

子コンポーネントを含むことのできるタイトル付きのボックス。toolbarファセットがあります。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

X(拡大されているか、type属性がstretchに設定されている場合)

X

panelAccordion

showDetailItemコンポーネントとともに使用され、開閉が可能なパネルとして表示されます。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

X (dimensionsFrom属性がparentに設定されている場合)

panelTabbed

showDetailItemコンポーネントとともに使用され、タブ付きの一連のパネルとして表示されます。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

タブとナビゲーション階層を組み合せて使用する場合、たとえば、各タブが他のナビゲーション・アイテムのセットを含む別ページまたはリージョンである場合、かわりにナビゲーション・メニューのnavigationPaneコンポーネントを使用できます。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

X (dimensionsFrom属性がparentに設定されている場合)

panelDrawer

showDetailItemコンポーネントとともに使用され、ドローワのように開いたり閉じたりできる一連のタブとして表示されます。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

X

panelSpringboard

showDetailItemコンポーネントとともに使用され、グリッドまたはストライプの中で一連のアイコンとして表示されます。ユーザーがアイコンをクリックすると、関連するshowDetailItemのコンテンツがストライプの下に表示されます。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

X

showDetail

トグル・アイコンを介してコンテンツを表示または非表示にします。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

その他のコンテナ

panelHeader

子コンポーネントが含まれ、メッセージ、ツールバーおよびヘルプ・トピックを含むヘッダーを表示します。詳細は、9.11項「静的ボックスの項目の表示」を参照してください。

X (type属性がstretchに設定されている場合)

X (type属性がstretchに設定されている場合)

panelCollection

table、treeおよびtreeTableなどの収集コンポーネントとともに使用され、これらのコンポーネントのメニュー、ツールバーおよびステータス・バーを表示します。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

X(表、ツリーまたはツリー表が1つのみの場合)

X

decorativeBox

ファセットでスタイル・テーマを使用してその子に枠線付きの外観を適用するコンテナ・コンポーネントを作成します。このコンポーネントは、通常、タブを表示するように構成されているnavigationPaneコンポーネントのコンテナとして使用されます。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

X(中央ファセット内)

X (dimensionsFrom属性がparentに設定されている場合)

inlineFrame

インラインiframeタグを作成します。

X

navigationPane

ナビゲーション階層の1レベルを表す一連のナビゲーション・アイテムを作成します。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

X(タブを表示するように構成されている場合)

panelList

各子コンポーネントをリスト項目として出力し、隣に黒丸をレンダリングします。ネストさせて階層リストを作成できます。詳細は、9.12項「1つ以上の列における箇条書きリストの表示」を参照してください。

panelWindow

ポップアップ・ウィンドウ内に子コンポーネントを表示します。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

toolbox

子のtoolbarおよびmenuコンポーネントを一緒に表示します。詳細は、16.3項「ツールバーの使用方法」を参照してください。

グループ化コンテナ

panelGroupLayout

子コンポーネントを縦または横にグループ化します。JSPページでは、複数のコンポーネントをファセットに含める場合にファセットで使用されます(ファセット・ページはファセット内の複数の子を操作できます)。詳細は、9.13項「関連する項目のグループ化」を参照してください。

X(レイアウトがscrollまたはverticalに設定されている場合のみ)

group

グループの親コンポーネントに管理されている場合を除き、レイアウトに関係なく子コンポーネントをグループ化します。JSPページでは、複数のコンポーネントをファセットに含める場合にファセットで使用されます(ファセット・ページはファセット内の複数の子を操作できます)。詳細は、9.13項「関連する項目のグループ化」を参照してください。

間隔調整コンポーネント

separator

項目間に水平線を作成します。詳細は、9.14項「空白または線を使用したコンテンツの分割」を参照してください。

spacer

空白の領域を作成します。詳細は、9.14項「空白または線を使用したコンテンツの分割」を参照してください。

9.1.1 レイアウト・コンポーネントの追加機能

ページにレイアウト・コンポーネントを追加した後で、イベントへの応答などの機能を追加することが必要になる場合があります。レイアウト・コンポーネントで使用できる他の機能へのリンクを次に示します。

- テンプレート: レイアウトを作成した後で、それをテンプレートとして保存できます。テンプレートのレイアウトを変更すると、そのテンプレートを使用するすべてのページにレイアウトの変更が自動的に反映されます。詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

- テーマ: テーマは、panelBoxコンポーネントなどの一部のレイアウト・コンポーネントに色のスタイルを追加します。テーマの使用の詳細は、付録31「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- スキン: スキンを使用して、レイアウト・コンポーネントのアイコンおよびその他のプロパティを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- ローカライゼーション: 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- アクセシビリティ: 入力コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- イベント: レイアウト・コンポーネントは、なんらかのロジックを実行することでアプリケーションで対応できるサーバー側とクライアント側両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。

- ユーザー・カスタマイズ: showDetailHeaderコンポーネントなどの一部のコンポーネントには、展開または縮小できる領域があります。ユーザーがページを離れるときにコンポーネントの状態(展開または縮小)を保存できるようにアプリケーションを構成できます。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

9.2 ページ・レイアウトの開始

ADF Facesコンポーネントを使用するJSFページには、viewタグで囲まれたdocumentタグが必要です。ページを構成するその他すべてのコンポーネントが、<af:document>と</af:document>の間に入ります。documentタグは、ページ内のその他のコンポーネントを表示できる非表示のページ・インフラストラクチャや、ブラウザのタイトル・テキストをレンダリングします。たとえば、実行時に、documentタグによりクライアント・ページのルート要素が作成されます。HTML出力では、<html>、<head>、<body>などのHTMLページの標準のルート要素が生成されます。

デフォルトでは、documentタグは、拡大可能なコンポーネントを使用可能なブラウザ領域に合せて拡大できるように構成されます。ページがレンダリングされるときに特定のコンポーネントがフォーカスを持つようにしたり、データが送信される前に失敗した接続に関するメッセージやナビゲートに関する警告を提供したりするように、タグをさらに構成できます。詳細は、9.2.5項「documentタグの構成方法」を参照してください。

通常、次に使用されるコンポーネントは、ADF Faces formコンポーネントです。このコンポーネントは、ユーザーによるページ・データの操作を可能にするコントロールを含むことができるHTMLのform要素を作成します。

注意:

1ページで複数のHTMLフォームを使用できますが、ページ当たり使用できるADF Faces formタグは1つだけです。詳細は、11.2項「formの定義」を参照してください。

例9-1に示すように、JDeveloperはview、documentおよびformタグを自動的に挿入します。詳細は、3.4項「ビュー・ページの作成」を参照してください。

例9-1 JDeveloperのウィザードで作成された最初のJSFページ

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html>
<f:view xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:document title="untitled1.jsf" id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>

これらのタグがページに配置されたら、レイアウト・コンポーネントを使用して、ページ上のその他のコンポーネントをレンダリングする方法と場所を制御できます。その他すべてのコンポーネントを保持するコンポーネントは、ルート・コンポーネントとみなされます。ルート・コンポーネントとして使用するコンポーネントの選択は、含まれているコンポーネントのコンテンツをブラウザ・ウィンドウに合せて拡大されるように表示するか、ウィンドウに収まらないコンテンツにアクセスするためにスクロールバーを使用してコンテンツを移動できるようにするかによって異なります。拡大と配置の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

ヒント:

レイアウトを自身で作成するかわりに、目的のレイアウトでページを表示する適切に構成されたコンポーネントを提供するJDeveloperのクイック・レイアウト・テンプレートを使用できます。詳細は、9.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

9.2.1 ジオメトリ管理およびコンポーネントの拡大

ジオメトリ管理は、ユーザー、親コンポーネントおよび子コンポーネントがアプリケーションのコンポーネントの実際のサイズと場所をネゴシエーションするプロセスです。たとえば、コンポーネントは、ブラウザに最初にロードされたとき、ブラウザがサイズ変更されたとき、またはユーザーが明示的にサイズ変更したときにサイズ変更されます。

デフォルトでは、有効なビジュアル・ルート・コンポーネントが1つのみ存在する場合、コンポーネントがジオメトリ管理をサポートしていれば、そのルート・コンポーネントはブラウザの可視領域を使用するように自動的に拡大されます。ジオメトリ管理コンポーネントの例は、panelGridLayoutおよびpanelSplitterなどです。ルート・コンポーネントで子コンポーネントの拡大がサポートされている場合(および、子コンポーネントでも拡大がサポートされている場合)、配置レイアウト領域(子コンポーネントの拡大がサポートされていない領域)に達するまで、コンポーネント階層を下がって子コンポーネントのサイズが再計算されます。拡大を有効化するためにコードを記述する必要はありません。

注意:

フレームワークでは、ポップアップ・ダイアログ、ポップアップ・ウィンドウまたはインラインではないメッセージは、ルート・コンポーネントとみなされません。formコンポーネントがdocumentコンポーネントの直接の子コンポーネントである場合には、フレームワークにより、formタグ内のビジュアル・ルートの有無が確認されます。ポップアップのサイズ変更の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

表9-1に示されているように、それ自体とその子コンポーネントも拡大できるコンポーネントはpanelGridLayout、panelStretchLayout、panelSplitterおよびpanelDashboardコンポーネントです。また、panelAccordionまたはpanelTabbedコンポーネントの直接の子としてshowDetailItemコンポーネントが使用されている場合は、showDetailItemコンポーネントのコンテンツを拡大できます。そのため、ページのコンテンツをブラウザ・ウィンドウに合せる必要がある場合には、showDetailItemコンポーネントを含むpanelStretchLayout、panelSplitter、panelDashboard、panelAccordionコンポーネント、およびshowDetailItemコンポーネントを含むpanelTabbedコンポーネントをルート・コンポーネントとして使用する必要があります。

たとえば、図9-1は、panelStretchLayoutコンポーネントのcenterファセットに配置された表を示しています。表はブラウザ領域に合せて拡大されます。表全体がブラウザ・ウィンドウに収まらない場合は、表のデータ本体部分にスクロールバーが追加されます。

図9-1 子コンポーネントが拡大されるコンポーネント内の表

図9-2に、子コンポーネントを拡大できないpanelGroupLayoutコンポーネント内にネストしている同じ表を示します(明確化のために、panelGroupLayoutコンポーネントが赤い点線で囲まれています)。表コンポーネントでは、表のプロパティで設定されている一部の列および行のみが表示されています。

図9-2 子コンポーネントが拡大されないコンポーネント内の表

パフォーマンスのヒント:

ジオメトリ管理のコストは、子コンポーネントの複雑さに直接関係しています。そのため、ジオメトリ管理される親コンポーネントに属する子コンポーネントの数はできるだけ少なくなるようにしてください。

9.2.2 拡大可能なコンポーネントへのコンポーネントのネスト

子コンポーネントを拡大できるコンポーネントを選択しても、実際に拡大されるのは次のコンポーネントのみです。

- decorativeBox(拡大するように構成されている場合)

- inputText(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox(拡大するように構成されている場合)

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGridLayout(拡大するように構成されている場合)

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合)

- panelHeader(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- showDetailHeader(拡大するように構成されている場合)

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

次のレイアウト・コンポーネントは、子コンポーネントを拡大するコンポーネントのファセット内に配置しても拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合)

- panelLabelAndMessage

- panelList

- showDetail

- tableLayout (MyFaces Trinidadコンポーネント)

ジオメトリ管理とサイズ変更に関する1つの興味深い考え方は、次に示すようにコンポーネントを4種類のパズル・ピースとして考えることです。

図9-3 ジオメトリ管理のコンポーネントの4つのカテゴリ

拡大できるコンポーネントは、自身の子を拡大するコンポーネントの内部にのみ配置できます。拡大されないコンポーネントを自身の子コンポーネントを拡大するコンポーネントのファセット内で使用する場合は、それを遷移コンポーネントにラップする必要があります。遷移コンポーネントは拡大できますが、その子は拡大されません。遷移コンポーネントは、常に、子を拡大するコンポーネントと拡大されないコンポーネントの間で使用する必要があります。ラップしないと、コンポーネントのレンダリング時に予期しない結果になる場合があります。

たとえば、panelSplitterコンポーネントの一方の側にフォームを表示する必要があるとします。ルート・コンポーネントがpanelStretchLayoutであるため、このコンポーネントがページの最初のコンポーネントであるとします。panelSplitterコンポーネント(デフォルト設定に構成されています)をpanelStretchLayoutコンポーネントに子として追加し、そのコンポーネントの最初のファセットに追加し、panelFormLayoutコンポーネントを追加します。図9-4に、これらのコンポーネントがどのように相互に適合するかを示します。panelSplitterは子を拡大できるためpanelFormLayoutを拡大しようとしますが、panelFormLayoutは拡大できないため、panelFormLayoutコンポーネントはpanelSplitterコンポーネントに適合しません。

図9-4 あるレイアウト・シナリオでのコンポーネントの順序

コンポーネントが子を拡大するコンポーネントに適合しない場合は、ブラウザがコンポーネントのレンダリングを試行したときに予期しない結果になることがあります。

有効なレイアウトにするには、拡大されないコンポーネントを、子を拡大するコンポーネントで使用する場合に、遷移コンポーネントを使用する必要があります。panelFormLayoutの例を解決するには、panelFormLayoutコンポーネントを、scrollに設定されたpanelGroupLayoutコンポーネントで囲むことができます。図9-5に示すように、このコンポーネントは拡大されますが、子を拡大しません。

図9-5 2番目のレイアウト・シナリオでのコンポーネントの順序

この場合は、すべてのコンポーネントが相互に適合します。panelGroupLayoutコンポーネントはpanelFormLayoutを拡大しようとしないため、正しくレンダリングされます。また、panelGroupLayoutコンポーネントは拡大できるため、レイアウトは拡大できるコンポーネントと拡大できないコンポーネント間で分割されません。

ヒント:

拡大できないコンポーネントのリストにあるコンポーネントを、幅を100%に設定して拡大しないでください。予期しない結果になる場合があります。かわりに、拡大されるコンポーネントを、拡大できるコンポーネントで囲みます。

scrollに設定されたpanelGroupLayoutコンポーネントは、拡大されないコンポーネントを持つレイアウトで拡大できないコンポーネントを使用する場合に、これらのコンポーネントに適したコンテナです。

ヒント:

コンポーネントが拡大されるかされないかが常に親の設定に基づいて決まることがわかっている場合は、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータをautoに設定することを検討してください。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

9.2.3 クイック・スタート・レイアウトの使用

「新規ギャラリ」ウィザードを使用してJSFページ(またはページ・フラグメント)を作成する場合、様々な事前定義済のクイック・スタート・レイアウトから選択できます。それらのレイアウトの1つを選択すると、JDeveloperによって必要なコンポーネントが追加され、ユーザーが希望する外観と動作が得られるようにそれらのコンポーネントの属性が設定されます。クイック・レイアウトを使用すると、時間を節約できるのに加え、レイアウト・コンポーネントが正しく連携して使用されるので希望どおりのジオメトリ管理を実現できます。

1列、2列および3列の形式から選択できます。それらの形式では、各列に表示する独立したペインの数、およびそれらのペインを拡大可能にするか固定サイズのままにするかを選択できます。図9-6に、2列形式で使用可能な様々なレイアウトを示します。

図9-6 クイック・レイアウト

レイアウト・コンポーネントの追加とともに、選択したクイック・レイアウトにテーマを適用することも選択できます。これらのテーマは、クイック・スタート・レイアウトで使用されるコンポーネントの一部に色のスタイルを追加します。色およびその追加場所を確認するには、付録D「クイック・スタート・レイアウトのテーマ」を参照してください。テーマの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

クイック・レイアウトを使用したページの作成の詳細は、3.4項「ビュー・ページの作成」を参照してください。

9.2.4 ジオメトリ管理コンポーネント使用のヒント

すべてのブラウザでページが期待どおりに表示されるようにするには、ページの作成時に、JDeveloperで提供されるクイック・レイアウトの1つを使用します。これらのレイアウトを使用すると、正しいコンポーネントが使用されて正確に構成されます。詳細は、9.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

ベスト・プラクティス:

クイック・スタート・レイアウトを使用して、レイアウト表示の問題を回避します。

ただし、自分でレイアウトを作成する場合のために、拡大されるコンポーネントと配置されるコンポーネントの両方を含むレイアウトを作成する際のヒントを次に示します。

- ジオメトリ管理機能のあるルート・コンポーネント内(gridRowとgridCellコンポーネントを含むpanelStretchLayout、panelGridLayout、panelSplitter、showDetailItemを含むpanelAccordion、およびshowDetailItemを含むpanelTabbed)にページ・コンテンツを配置します。

- パーセント単位で高さの値を指定しないでください。かわりに、拡大がサポートされているコンポーネントや、子コンポーネントを拡大するコンポーネントの外にコンポーネント構造を作成します。詳細は、9.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

- layout属性がscrollに設定されているpanelGroupLayoutコンポーネントなどの遷移コンポーネントを使用して、この拡大可能な構造内に、拡大できないコンポーネントまたは配置が行われるコンポーネントのグループを作成します。このコンポーネントでは拡大がサポートされていますが、子コンポーネントは拡大されないため、拡大されるコンポーネントと配置が行われるコンポーネントの遷移が可能です。

- どのWebブラウザでも一貫して機能するわけではないため、拡大できないコンテナまたは配置が行われるコンテナ内で、縦方向の拡大を試行しないでください。

- 親の配置されるコンポーネント(つまり、子を拡大しないコンポーネント)に含まれるコンポーネントの場合は、幅を95%より大きく設定しないでください。このような設定を行うと、予期しない結果になることがあります。

- 親コンポーネントが768ピクセル以上の場合は、拡大されるコンポーネントのstyleClass属性をAFStretchWidthに設定します。このスタイルは、様々なブラウザと親のパディングまたは枠線を考慮して、親コンテナの100%となるようにコンポーネントを拡大します。

- 親コンポーネントが768ピクセル以下の場合は、拡大されるコンポーネントのstyleClass属性をAFAuxiliaryStretchWidthに設定します。このスタイルは、様々なブラウザと親のパディングまたは枠線を考慮して、親コンテナの100%となるようにコンポーネントを拡大します。

注意:

Microsoft Internet Explorer 7がスクロール・コンテナ内の幅を計算する方法により、2つの異なるスタイルが必要です(これはInternet Explorer 8で解決されました)。アプリケーションへのアクセスに使用されるブラウザのバージョンを管理できない場合は、説明に従ってこれらのスタイルを使用する必要があります。

- positionスタイルは使用しないでください。

- documentタグのmaximized属性がtrueに設定されていることを確認します(これはデフォルトです)。属性の設定の詳細は、9.2.5項「documentタグの構成方法」を参照してください。

この章の残りの部分では、ADF Facesのレイアウト・コンポーネント、およびそれらを使用してページを設計する方法を説明しています。各コンポーネントで拡大が処理される方法の詳細は、それぞれの「ジオメトリ管理に関する必知事項」の項に記載されています。

9.2.5 documentタグの構成方法

documentタグには、ページの動作を制御するために構成できる多数の属性が含まれています。たとえば、ブラウザがアドレス・バーに挿入できるアイコン(通称ファビコン)を構成できます。図9-7に、Firefoxブラウザのアドレス・バーのOracleアイコンを示します。

図9-7 documentタグに構成された小さなアイコン

次の機能のタグを構成することもできます。

- フォーカス: ページが初めてレンダリングされるときにフォーカスを受け取るコンポーネントを設定できます。

- コミットされていないデータ: ユーザーがページから移動しようとしたときにデータがまだ送信されていない場合に、警告メッセージを表示できます。

- 状態保存: 個々のページのweb.xmlファイルで設定をオーバーライドして、ページの状態がクライアントまたはサーバーに保存されるようにすることができます。

documentタグを構成する手順:

1. 構造ウィンドウで、af:documentノードを選択します。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- InitialFocusId: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、ページを初めてレンダリングするときにフォーカスするコンポーネントを選択します。
このフォーカスはクライアントで行われるため、選択するコンポーネントには対応するクライアント・コンポーネントが必要です。詳細は、4.3項「クライアント側コンポーネントのインスタンス化」を参照してください。

- Maximized: ルート・コンポーネントを拡張して使用可能なすべてのブラウザ領域に合せる場合はtrueに設定します。documentタグのmaximized属性がtrueに設定されていると、フレームワークにより単一のビジュアル・ルート・コンポーネントが検索され、そのコンポーネントが拡大可能な場合は、ブラウザの表示可能領域全体にコンポーネントが拡大されます。これに対応しているコンポーネントは、panelStretchLayoutおよびpanelSplitterです。documentタグのmaximized属性は、デフォルトでtrueに設定されています。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- Title: ブラウザのタイトル・バーに表示するテキストを入力します。

3. 「外観」セクションを開き、次の属性を設定します。

- FailedConnectionText: サーバーとの接続を確立できない場合に表示するテキストを入力します。

- Small Icon Source: ブラウザがアドレス・バーに挿入できる(通常は16x16ピクセルの)アイコン(通称ファビコン)にURIを入力します。値が指定されていない場合は、各ブラウザで指定されるか、なんらかの別の値が表示されます。
アイコンのスペース区切りリストを入力でき、ブラウザは通常、サポートする最初の値を表示します。たとえば、Microsoft Internet Explorerでは、ファビコンに.icoのみサポートされます。そのため、次の値があるとします。

/images/small-icon.png /small-icon.ico

Internet Explorerはsmall-icon.icoを表示し、Firefoxはsmall-icon.pngを表示します。

ファイルがWebアプリケーションのルート・フォルダの内部にある場合は、アドレスで1つのスラッシュ(/)を使用します。ファイルがサーバーのルート・フォルダにある場合は、2つのスラッシュ(//)を使用します。

- Large Icon Source: ブラウザがページにデバイスのホーム・ページへのブックマークを付ける場合に使用できるアイコン(通常は129x129ピクセル)へのURIを入力します。

図9-8 大きなアイコンを表示しているモバイル・デバイス

値が指定されていない場合は、各ブラウザで指定されるか、なんらかの別の値が表示されます。

アイコンのスペース区切りリストを入力でき、ブラウザは通常、サポートする最初の値を表示します。

ファイルがWebアプリケーションのルート・フォルダの内部にある場合は、アドレスで1つのスラッシュ(/)を使用します。ファイルがサーバーのルート・フォルダにある場合は、2つのスラッシュ(//)を使用します。

ヒント:

異なるバージョンのiPhoneやiPadは異なるサイズのイメージを使用します。最大サイズ(129x129ピクセル)を使用でき、イメージは必要なサイズにスケール変更されます。

4. データがコミットされていないことがアプリケーションによって検出されたときにユーザーに警告メッセージを表示する場合は、「動作」セクションを展開し、UncommittedDataWarningをonに設定します。警告メッセージは、ユーザーがデータをコミットせずにページを終了しようとする場合、またはサーバーにコミットされていないデータがある場合に表示されます。デフォルトでは、これはoffに設定されます。

注意:

アプリケーションがADFコントローラを使用しない場合、データは中間層にポストされるときにコミットされるとみなされます。たとえば、ユーザーがボタンをクリックした場合、データが実際にバック・エンドに書き込まれたかどうかにかかわらず、中間層でナビゲーションが発生した場合に警告は表示されません。

5. 「拡張」セクションを開き、StateSavingをページで使用する状態保存のタイプに設定します。
ADF Facesアプリケーションの場合は、トークン付きのクライアント状態保存をアプリケーションで使用するように構成することをお薦めします。これにより、ページ状態がセッションに保存され、トークンがクライアントで永続します。この設定はアプリケーションにグローバルに影響し、すべてのページの状態がセッションに保存され、トークンと情報が状態にかかわらず永続化されます。

web.xmlのグローバル設定をページで次のいずれかにオーバーライドできます。

- client: 状態は、トークンを使用せずにクライアントに完全に保存されます。この設定は、セッション失効メッセージが表示されないようにします。

- default: ページの状態はweb.xmlの設定に基づきます。

- server: ページの状態はサーバーに保存されます。

状態保存の詳細は、付録A「web.xmlでの構成」を参照してください。

9.3 グリッドでのコンテンツの配置

コンテンツをページのグリッド領域(HTMLテーブルと同様)に配置し、ブラウザがサイズ変更されたときにコンテンツが拡大されるように構成するには、panelGridLayoutコンポーネントを使用します。panelGridLayoutコンポーネントはレイアウト・コンポーネントに最大限の柔軟性を提供しながら、ごく少量のHTML要素しか生成しません。これにより、個々のセルを境界内に配置する方法を完全に管理できます。

panelGridLayoutコンポーネントは子のgridRowコンポーネントを使用して行を作成し、それらの行の中でgridCellコンポーネントを使用して列を構成します。gridCellコンポーネントにコンポーネントを配置して、データ、イメージまたは他のコンテンツを表示します。

図9-9に、2つのgridRowコンポーネントが含まれているpanelGridLayoutコンポーネントを示します。各gridRowコンポーネントには、2つのgridCellコンポーネントが含まれています。各gridCellコンポーネントには、1つのchooseDateコンポーネントが含まれています。

図9-9 それぞれ2つのセルを持つ2つの行の簡単なグリッド・レイアウト

panelGridLayoutコンポーネントはネスト可能です。図9-10に、親panelGridLayoutコンポーネントを使用して作成された複雑なレイアウト(背景をピンクに設定)を示します。

図9-10 ネストしたpanelGridLayoutコンポーネントを使用して作成された複雑なグリッド・レイアウト

このpanelGridLayoutの最初のgridRowコンポーネントには、1つのgridCellコンポーネントが含まれています。このgridCellコンポーネントには、ヘッダー用に別のpanelGridLayoutコンポーネントが含まれています。このヘッダー・グリッドには2つのgridRowコンポーネントが含まれており、それぞれ2つのgridCellコンポーネントが含まれています。右上部のgridCellには、検索機能のためのコンポーネントが含まれ、左下部のgridCellには、Oracleロゴが含まれています。

親panelGridLayoutコンポーネントの次の4つのgridRowsには、gridCellコンポーネントが1つだけ含まれています。それぞれに、formコンポーネントとボタンがあります。最後のgridRowコンポーネントには、1つのgridCellコンポーネントが含まれており、フッター用に別のpanelGridLayoutコンポーネントが含まれています。このフッターは、gridRowコンポーネントと4つのgridCellコンポーネントから構成され、それぞれinputTextコンポーネントが含まれています。

子を拡大するコンポーネントに配置した場合、デフォルトで、panelGridLayoutはその親コンテナに合せて拡大されます。ただし、グリッド内のコンテンツが領域に合せるように拡大されるかどうかは、gridRowおよびgridCellコンポーネントによって決定されます。

デフォルトでは、子コンテンツは拡大されません。gridRowコンポーネントによって、高さが決定されます。デフォルトでは、高さは行のセルにある最も高い子コンポーネントの高さによって決まります。gridCellコンポーネントによって、幅が決定されます。デフォルトでは、セルの幅は列にある他のセルの幅によって決定されます。したがって、列内で少なくとも1つのセルを決定済の幅に設定する必要があります。これを固定のCSS長やグリッド内の残りの空白のパーセンテージに設定すると、セル内のコンポーネントに基づいた幅を決定できます。

かわりに、使用可能なブラウザ領域が完全に埋まるようにグリッドのコンテンツを拡大するには、次の条件を満たす必要があります。

- gridCellの中にコンポーネントが1つしかない。

- セルのhalignおよびvalign属性がstretchに設定されている。

- セルの有効な幅と高さが、他のセルや行によって自動的に決まるように設定されていない(設定されていると、循環依存関係が発生する)。

各セルは、子コンポーネントをセルのすべての辺に固定しようとします。固定できない場合(子コンポーネントを拡大できない場合など)、子コンポーネントは開始時にセルの上部に配置されます。

9.3.1 panelGridLayout、gridRowおよびgridCellコンポーネントを使用してグリッドベースのレイアウトを作成する方法

JDeveloperは、ユーザーの入力に基づいて宣言的にグリッドを作成するダイアログを提供します。一定数のgridRowコンポーネントをpanelGridLayoutコンポーネントに配置して、グリッドを手動で作成します。次に、gridCellコンポーネントをgridRowコンポーネントに追加し、gridCellコンポーネントに実際のコンテンツを含むコンポーネントを配置します。panelGridLayoutコンポーネントをネストさせる場合、子panelGridLayoutコンポーネントをgridCellコンポーネントに配置します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.3項「グリッドでのコンテンツの配置」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelGridLayout、gridRowおよびgridCellコンポーネントを作成して使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・グリッド・レイアウト」をJSFページにドラッグ・アンド・ドロップします。

2. 「パネル・グリッド・レイアウトの作成」ダイアログで、グリッドの列数と行数を入力し、グリッドの内側マージンと外側マージンを設定して、「次」をクリックします。
グリッドの内側マージンと外側マージンを設定する際、次の点に留意してください。

- グリッドの内側マージン: 固定されたCSSサイズ(例: 2px)に設定します。

- 列: marginStartプロパティの値を、最初のもの(これは「グリッドの外側マージン」の設定により処理)を除くすべてのgridCellコンポーネントに設定します。

- 行: marginTopプロパティの値を、最初のもの(これは「グリッドの外側マージン」の設定により処理)を除くすべてのgridRowコンポーネントに設定します。

- グリッドの外側マージン: 固定されたCSSサイズ(例: 2px)に設定します。

- 一番上: marginTopプロパティを一番上のgridRowコンポーネントのみに設定します。

- 一番下: marginBottomプロパティを最後のgridRowコンポーネントのみに設定します。

- 左: marginStartプロパティを最初のgridCellコンポーネントのみに設定します。

- 右: marginEndプロパティを最後のgridCellコンポーネントのみに設定します。

注意:

marginBottomおよびmarginTopの場合、競合する単位タイプは無視されます。たとえば、RowAのmarginTopが2pxに設定され、RowBのmarginTopが5emに設定されている場合、これが発生した最初の単位タイプになるため、マージンは2pxになります。

「パネル・グリッド・レイアウトの作成」ダイアログを使用する場合、marginTopおよびmarginBottomプロパティが設定され、競合が回避されます。

注意:

panelGridLayoutコンポーネントで子を拡大する必要がある場合は、行の高さをauto以外の値に、セル幅をauto以外の値に設定してください。次に「プロパティ」ウィンドウを使用して、拡大を許可するように他のプロパティを設定します。詳細は、手順5を参照してください。

3. このダイアログの2ページ目で、セル幅と行の高さを個別に設定します。

- グリッドの幅: widthプロパティを各gridCellコンポーネントに設定します。各列を次のいずれかに設定します。

- dontCare: セルの幅は列内の他のセルによって決定されます。これがデフォルトです。

- auto: セルの幅は対応する列内のコンポーネントによって決定されます。ブラウザは最初にこれらのコンポーネントをすべて描画し、これに合せて行の高さを調整します。

- パーセンテージ: セルの対応する列の幅を、他の列が使用していない残りの領域の正規化されたパーセンテージにする場合、パーセンテージを入力します。たとえば、25%などです。

- 固定のCSSサイズ: 幅を固定の幅に制限する場合、固定のCSSサイズを入力します。たとえば、20pxや20emなどです。

注意:

次の点に注意してください。

- セルが複数行にまたがるようにする場合、widthはdontCareに設定する必要があります。

- 列内のセルの幅がそれぞれ異なる値に設定されている場合(たとえば、autoに設定されているものや固定の幅に設定されているものがある場合)、列の幅は発生した最初の単位タイプの最大値になります。

- 列内のすべてのセルがdontCareに設定されている場合、子コンポーネントに基づいた最も幅の広いセルによって列の幅が決定されます(セルがすべてautoに設定されている場合と類似しています)。

- グリッドの高さ: heightプロパティを各gridRowコンポーネントに設定します。各行を次のいずれかに設定します。

- auto: 行の高さは行のコンポーネントによって決定されます。ブラウザは最初に子コンポーネントを描画し、これに合せて行の高さを調整します。これがデフォルトです。

- パーセンテージ: panelGridLayoutコンポーネント自体の高さが固定の場合、または親コンポーネントによって拡大されている場合、パーセンテージを入力します。たとえば、25%などです。行の高さは、他の行が使用していない残りの領域の正規化されたパーセンテージとなります。

- 固定のCSS長: 高さを固定の高さに制限する場合、固定のCSS長を入力します。たとえば、10pxや20emなどです。

「終了」をクリックします。

4. デフォルトでは、panelGridLayoutコンポーネントは使用可能なブラウザ領域に合せて拡大されます。かわりに、panelGridLayoutコンポーネントを、子を拡大しないコンポーネントの子として使用する場合は、panelGridLayoutコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

「プロパティ」ウィンドウで、DimensionsFromを次の1つに設定します。

- children: panelGridLayoutコンポーネントは、子コンポーネントからディメンションを取得します。

注意:

この設定を使用する場合、子の行コンポーネントの高さをパーセンテージとして設定できません。panelGridLayout内の領域は可用性に基づいて分割されないためです。「プロパティ」ウィンドウを使用して、ダイアログを終了するときに設定した行の高さを変更できます。

- parent: panelGridLayoutコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

注意:

この設定を使用する場合、子の行コンポーネントの高さをパーセンテージとして設定できません。

- auto: panelGridLayoutコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelGridLayoutコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelGridLayoutコンポーネントのサイズはその子コンポーネントのサイズに基づきます。これがデフォルトです。

5. panelGridLayoutコンポーネントで子を拡大する必要がある場合は、次のように設定してください。

- 行のheightをauto以外の値に設定します。

- セルのwidthをauto以外の値に設定します。

- gridCellコンポーネントのhalignをstretchに設定します。

- gridCellコンポーネントのvalignをstretchに設定します。

- 子コンポーネントのみをgridCellコンポーネントに配置します。

6. セルが複数の列で構成されるようにする場合、ColumnSpanを、含める列数に設定します。デフォルト値は1です。

注意:

1を超える値にcolumnSpanを設定する場合、width属性の値をdontCareに設定する必要があります。

7. セルが複数の行で構成されるようにする場合、RowSpanを、含める行数に設定します。デフォルト値は1です。

8. Halignを設定して、セルのコンテンツの横の配置を決定します。コンテンツをセルの開始位置に合せる場合(LTRロケールでは左)、これをstart(デフォルト)に設定します。centerまたはendに設定することもできます。panelGridLayoutを拡大する場合、Halignをstretchに設定します(panelGridLayoutコンポーネントの拡大の詳細は、手順5を参照してください)。

9. Valignを設定して、セルのコンテンツの縦の配置を決定します。コンテンツをセルの上部に合せる場合、これをtop(デフォルト)に設定します。これをmiddleまたはbottomに設定することもできます。panelGridLayoutを拡大する場合、Valignをstretchに設定します(panelGridLayoutコンポーネントの拡大の詳細は、手順5を参照してください)。

9.3.2 ジオメトリ管理およびpanelGridLayoutコンポーネントに関する必知事項

panelGridLayoutコンポーネントは子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次に、panelGridLayoutコンポーネント内で拡大可能なコンポーネントを示します。

- decorativeBox(拡大するように構成されている場合)

- calendar

- inputText(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox(拡大するように構成されている場合)

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGridLayout (gridRowおよびgridCellコンポーネントが拡大するように構成されている場合)

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合のみ)

- panelHeader(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- showDetailHeader(拡大するように構成されている場合)

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

次に、panelGridLayoutコンポーネント内に配置された場合、拡大できないコンポーネントを示します。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelLabelAndMessage

- panelList

- showDetail

- tableLayout (MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントに配置することはできません。したがって、拡大できないコンポーネントをpanelGridLayoutコンポーネントのgridCellに配置する必要がある場合、子を拡大しないように、panelGridLayout、gridRow、and gridCellコンポーネントを構成する必要があります。

9.3.3 グリッドの構造に関する必知事項

ページのサンプルを与えられても、それをグリッドに分ける方法を知らない場合があります。連続するグリッドのグリッド分割、行および列を決定するには次のヒントが役立ちます。

グリッドを設計するには:

1. デザインを1枚の紙に印刷するか、グラフィック・プログラムで開き、デザインの上に色つきの線を描けるように準備します。

2. 列の分割を表すことになる縦線を任意の色(たとえば赤)で描きます。

3. 行の分割を表すことになる横線を任意の色(たとえば緑)で描きます。

4. これで基本的なグリッド構造が作成されました。別の色(たとえば黄色)を使用して、複数の行または列にまたがるセルにXマークを描きます。
図9-11に、4列4行に分割され、列がまたがる箇所が複数ある設計を示します。

図9-11 列、行、スパンの候補を示す線

5. 最初の試みでは、列の線がほとんど意味を成さないことがわかります。たとえば、図9-11では、中央の2つの列には隣の列にまたがるセルが含まれます。これはかわりに2つのグリッドが必要なことを示しています。
4色(たとえば、赤紫)を使用して分割が意味を成すような線を引き、それを繰り返します。

図9-12は2つの連続するグリッドを使用する同一の設計を示します。

図9-12 連続するグリッドによる列のまたがりの単純化

6. これで、コンテンツがどこに配置され、どこで列や行がまたがるか視覚的に確認できるので、gridRowコンポーネントとgridCellコンポーネントをコーディングできます。セルのサイズや縦横の配置を正確に指定することもできます。

ヒント:

グリッド内に列にまたがるラベルを持つフィールドがある場合は、ビルトイン・ラベルを使用するかわりに、それらのラベルが非表示になるように構成(通常はsimple属性を使用)し、ラベルに別個のoutputLabelコンポーネントを使用します。

たとえば、図9-12では、PhoneおよびEmailフィールドのラベルは最初の列にありますが、それらのフィールド自体は2番目の列にあります。このレイアウトを作成するには、対応するinputTextコンポーネント内のラベルを使用するかわりに、次の手順を実行します。

1. 2列目のphoneおよびemailフィールドにinputTextコンポーネントを置きます。

2. それらのコンポーネントのsimple属性をtrueに設定して、ビルトイン・ラベルを非表示にします。

3. 新規のoutputLabelコンポーネントを1列目のラベルに追加します。

図9-13に最終的なグリッド設計を示します。

図9-13 最終的なグリッド設計

ベスト・プラクティスのヒント:

panelGridLayoutコンポーネントは3層以内にする必要があります。

9.3.4 使用するレイアウト・コンポーネントの決定に関する必知事項

panelGridLayoutコンポーネントはレイアウト・コンポーネントに最大限の柔軟性を提供しながら、ごく少量のHTML要素しか生成しません。これにより、個々のセルを境界内に配置する方法を完全に管理できます。反対に、panelGroupLayoutでは構造の個々の子の表示方法をほとんど制御できず、panelStretchLayoutでは少数のグリッド構造のみ生成され、多くの場合、複数のpanelStretchLayoutコンポーネントのネストを必要とします。複数コンポーネントのネストには、より多くのHTML要素が必要とされ、コードの管理がより複雑になります。このため、複雑なレイアウトにはpanelGridLayoutコンポーネントを使用します。

たとえば、一連のボタン・コンポーネントの配置など、配置を詳細に制御する必要がない単純な構造には、panelGroupLayoutを使用します。複数のpanelGroupLayoutコンポーネントをネストしているということは、panelGridLayoutのほうがより適していることを意味します。

9.4 コンテンツをページ全体に拡大するための設定

コンテンツをページの定義済領域に配置し、ブラウザがサイズ変更されたらコンテンツが拡大されるようにする必要がある場合には、panelStretchLayoutコンポーネントを使用します。panelStretchLayoutコンポーネントは、ファセット内に配置されたコンポーネントが拡大されるコンポーネントの1つです。図9-14に、コンポーネントのファセットを示します。

図9-14 panelStretchLayoutコンポーネントのファセット

注意:

図9-14は、アプリケーションにおける言語の読み方向が左から右に構成されている場合のファセットを示しています。言語の方向が右から左の場合は、startおよびendファセットが入れ替ります。

topおよびbottomファセットの高さを設定すると、含まれるコンポーネントはその高さに合うように拡大されます。同様に、startおよびendファセットの幅を設定すると、それらのファセットに含まれるコンポーネントはその幅まで拡大されます。それらのファセットに配置されているコンポーネントがない場合、ファセットはレンダリングされません。つまり、ファセットは領域を占有しません。設定した領域をファセットで占有し、空白のままにする場合は、spacerコンポーネントを挿入します。9.14項「空白または線を使用したコンテンツの分割」を参照してください。centerファセットの子コンポーネントは、残りの領域に合うよう拡大されます。コンポーネント拡大の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

Topまたはbottomのファセットの高さ、あるいはstartまたはendファセットの幅を設定するかわりに、高さまたは幅をautoに設定できます。これにより、ファセットの子コンポーネントに必要な正確な領域を使用するように、ファセット自体がサイズを設定できます。領域は、Webブラウザがファセットのコンテンツの表示に必要だと判断する領域の量に基づいて割り当てられます。

パフォーマンスのヒント:

値としてautoを使用すると、ページのパフォーマンスが低下します。最初に高さまたは幅を設定し、auto属性の使用は控えるようにしてください。

File Explorerアプリケーションでは、テンプレートのルート・コンポーネントとしてpanelStretchLayoutコンポーネントが使用されています。子コンポーネントは、centerおよびbottomファセットにのみ配置されています。そのため、centerファセット内のすべてのコンポーネントは、ウィンドウの幅全体、およびウィンドウの上部から、高さがbottomHeight属性で指定されているbottomファセットの上部までの大きさに合うように拡大されます。例9-2に、fileExplorerTemplateファイルの省略形のコードを示します。

例9-2 File Explorerのテンプレート・ファイルのpanelStretchLayout

<af:panelStretchLayout
bottomHeight="#{attrs.footerGlobalSize}">
<f:facet name="center">
<af:panelSplitter orientation="vertical" ...>
.
.
.
</af:panelSplitter
</f:facet>
<f:facet name="bottom">
<af:panelGroupLayout layout="vertical">
.
.
.
</af:panelGroupLayout>
</f:facet>
</af:panelStretchLayout>

テンプレートではEL式を使用して、bottomHeight属性の値が指定されています。この式により、テンプレートに定義されたfooterGlobalSize属性の値(デフォルトは0)に解決されます。テンプレートが使用されているページでは、この値がオーバーライドされます。たとえば、index.jspxページではこのテンプレートを使用して、値が30に設定されています。そのため、File Explorerアプリケーションによりレンダリングされると、panelStretchLayoutコンポーネントのコンテンツはページの上部30ピクセルの場所から開始されます。

9.4.1 panelStretchLayoutコンポーネントの使用方法

panelStretchLayoutコンポーネントには、直接の子コンポーネントを配置できません。かわりに、ファセット内にコンポーネントを配置します。panelStretchLayoutは、ファセット内のコンポーネントをブラウザに合せて拡大するように構成できるコンポーネントの1つです。panelStretchLayoutコンポーネントはネスト可能です。詳細は、9.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.4項「コンテンツをページ全体に拡大するための設定」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelStretchLayoutコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・ストレッチ・レイアウト」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、必要に応じて属性を設定します。
top、bottom、startおよびendファセットに子コンポーネントが存在する場合は、それらのコンポーネントにより、topHeight、bottomHeight、startWidthおよびendWidth属性で定義されている領域が占有されます。たとえば、topHeight属性はtopファセットの高さを、startWidth属性はstartファセットの幅を指定します。topおよびbottomファセットの子コンポーネントは、topHeightとbottomHeight属性で設定されている高さまでそれぞれ拡大され、startおよびendファセットの子コンポーネントは、startWidthとendWidth属性で設定されている幅までそれぞれ拡大されます。数値で大きさを設定するかわりに、topHeight、bottomHeight、startWidthおよびendWidth属性をautoに設定すると、ファセットのコンテンツの表示に必要な領域の量がブラウザにより決定されます。

注意:

ファセットの幅または高さの値としてautoを使用するようにそのファセットを設定した場合、子コンポーネントは拡大できる必要がありません。実際には、ファセットの幅に依存しない安定した単独の幅を使用する必要があります。

たとえば、子コンポーネントが子を自動的に拡大できるファセットではautoを使用しないでください。これらのコンポーネントは、不安定なoffsetWidth値をレポートする原因となる独自の組込み拡大幅をデフォルトで持ち、この値は領域の量を判断するためにブラウザによって使用されます。

また、autoは、幅にパーセント長を使用する子コンポーネントと一緒に使用しないでください。ファセットのコンテンツは、パーセント幅に依存することも、周囲のコンテナの幅全体を使用するコンポーネントにすることもできません。

値を明示的に指定しない場合、topHeight、bottomHeight、startWidthおよびendWidth属性の値は、それぞれデフォルトで50ピクセルになります。topとbottomファセットの幅、およびstartとendファセットの高さは、panelStretchLayoutの親コンポーネントの幅と高さから導出されます。

ヒント:

ファセットに子コンポーネントが含まれない場合はレンダリングが行われないため、領域は占有されません。構成した領域を占有するには、ファセットに子コンポーネントを配置する必要があります。

3. panelStretchLayoutコンポーネントは、使用可能なブラウザの領域全体に拡大するように構成できます。また、子を拡大しないコンポーネントの内部にpanelStretchLayoutコンポーネントを配置する場合は、panelStretchLayoutコンポーネントを拡大しないように構成することもできます。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

DimensionsFromを次のいずれかの値に設定します。

- children: 拡大するかわりに、panelStretchLayoutコンポーネントは子コンポーネントからディメンションを取得します。

注意:

この設定を使用する場合は、topおよびbottomファセットの高さの設定に割合を使用できません。使用すると、それらのファセットはこのpanelStretchLayoutコンポーネントのサイズからディメンションを取得しようとしますが、panelStretchLayoutコンポーネントはそのコンテンツから高さを取得するため取得できず、循環依存関係が発生します。いずれかのファセットに割合が使用されている場合、それは無視され、デフォルトの50pxがかわりに使用されます。

また、この設定を使用している場合は、panelStretchLayoutコンポーネントの高さを(たとえば、inlineStyleまたはstyleClass属性を通じて)設定することはできません。設定すると、panelStretchLayoutの高さと子コンポーネントの高さが競合する原因となります。

- parent: panelStretchLayoutコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます(つまり、panelStretchLayoutコンポーネントは拡大されます)。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: panelStretchLayoutコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelStretchLayoutコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelStretchLayoutコンポーネントはその子コンポーネントのサイズに基づきます。

4. コンポーネントにコンテンツを配置するには、必要なコンポーネントを任意のファセットにドラッグ・アンド・ドロップします。子コンポーネントを拡大する場合には、拡大がサポートされているコンポーネントである必要があります。詳細は、9.4.2項「ジオメトリ管理およびpanelStretchLayoutコンポーネントに関する必知事項」を参照してください。
JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。含まれているすべてのコンポーネントを拡大するには、子のコンポーネントも拡大できる必要があります。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelStretchLayoutコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ストレッチ・レイアウト」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

9.4.2 ジオメトリ管理およびpanelStretchLayoutコンポーネントに関する必知事項

panelStretchLayoutコンポーネントは子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次に、panelStretchLayoutコンポーネントのファセット内で拡大できるコンポーネントを示します。

- decorativeBox(拡大するように構成されている場合)

- calendar

- inputText(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox(拡大するように構成されている場合)

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合のみ)

- panelHeader(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- showDetailHeader(拡大するように構成されている場合)

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

panelStretchLayoutコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelLabelAndMessage

- panelList

- showDetail

- tableLayout (MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、panelStretchLayoutコンポーネントのファセットに拡大できないコンポーネントに配置する必要がある場合は、拡大できる遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelStretchLayoutコンポーネントのファセット内のpanelBoxコンポーネント(拡大しない)にコンテンツを配置する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをpanelStretchLayoutコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、9.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

9.5 スプリッタを使用したサイズ変更可能なペインの作成

ユーザーに表示する一意のコンテンツのグループがある場合は、panelSplitterコンポーネントを使用して、調整可能なスプリッタによって分離された複数のペインを提供することを検討します。ADF Facesデモ・アプリケーションは、panelSplitterを使用して、図9-15に示すようにエディタ領域からコンポーネント・デモ領域を分離します。ユーザーは、スプリッタをドラッグすることでペインのサイズを変更でき、エディタを表示するパネルを縮小および復元することもできます。パネルが縮小されると、パネルのコンテンツが非表示になります。パネルが復元されると、コンテンツが表示されます。

図9-15 panelSplitterを使用してコンテンツを分割しているADF Facesデモ・アプリケーション

panelSplitterコンポーネントでは、調整可能なスプリッタで分離された2つのペインにコンテンツを編成できます。ペインは、(図9-15に示されているスプリッタのように)水平に並べるか、垂直に並べることができます。ADF Facesデモ・アプリケーションでは、別のpanelSplitterコンポーネントを使用して、ページのメイン本体からアプリケーションのグローバル・メニューを分離します。図9-16に、ドキュメントとソースへのアクセスを含むメニューを表示するように展開されたpanelSplitterコンポーネントを示します。

図9-16 縦に分割されて開かれたpanelSplitter

スプリッタの矢印ボタンをクリックすると、グローバル・メニューが表示されているパネルが閉じられ、図9-17に示すように、メニュー項目が表示されなくなります。

図9-17 縦に分割されて閉じられたpanelSplitter

panelSplitterコンポーネントのファセットにコンポーネントを配置します。panelSplitterコンポーネントではジオメトリ管理を使用して、実行時に子コンポーネントを拡大します。つまり、ユーザーがパネルを1つ閉じると、使用可能な領域に合うように別のパネルのコンテンツが明示的にサイズ変更されます。

注意:

ユーザーはペインをサイズ変更または縮小することでsplitterPositionおよびcollapsed属性の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。変更の永続性の有効化および使用方法の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

9.5.1 panelSplitterコンポーネントの使用方法

panelSplitterコンポーネントを使用すると、スプリッタで分割された2つのペインを作成できます。それぞれのスプリッタ・コンポーネントには、firstおよびsecondという2つのファセットがあり、それぞれ第1パネルと第2パネルに対応します。子コンポーネントが存在できるのはファセット内のみです。3つ以上のペインを作成するには、panelSplitterコンポーネントをネストします。

始める前に

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.5項「スプリッタを使用したサイズ変更可能なペインの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelSplitterコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・スプリッタ」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。

3. 「向き」をverticalに設定して、縦のペインを2つ作成します(一方をもう一方の上に配置)。デフォルトでは値はhorizontalで、この場合、横方向のペインは左から右(または言語の読み方向によっては右から左)に配置されます。

4. SplitterPositionおよびPositionedFromEndを設定して、スプリッタの最初の配置位置を決定します。デフォルトで、splitterPosition属性の値は200ピクセルで、positionedFromEnd属性はfalseです。この設定は、ADF Facesでは調整可能なスプリッタの初期位置が、(orientation属性の値に応じて)startまたはtopパネルから計測されることを意味します。たとえば、orientation属性がhorizontalで、splitterPosition属性が200、positionedFromEnd属性がfalse(すべてデフォルト値)に設定されている場合、図9-18に示されているように、ADF Facesによりスプリッタはstartパネルから200ピクセルの位置に配置されます。

図9-18 startパネルから計測されたスプリッタの位置

positionedFromEnd属性がtrueに設定されている場合、ADF Facesではスプリッタの初期位置はend(またはorientationの値に応じてbottomパネル)から計測されます。図9-19に、endパネルから200ピクセル計測したスプリッタの位置を示します。

図9-19 endパネルから計測されたスプリッタの位置

5. collapsedを設定して、スプリッタを閉じた状態(非表示)にするかどうかを決定します。デフォルトではcollapsed属性はfalseで、どちらのペインも表示されます。ユーザーがスプリッタの矢印ボタンをクリックすると、collapsed属性がtrueに設定され、いずれかのペインが非表示になります。
ADF Facesは、collapsedおよびpositionedFromEnd属性を使用して、ユーザーがスプリッタ上の矢印ボタンをクリックしたときに非表示に(縮小)するパネル(第1または第2パネル)を決定します。collapsed属性がtrueに設定され、positionedFromEnd属性がfalseに設定されている場合は、第1パネルが非表示になり、第2パネルは使用可能な領域に合せて拡大されます。collapsed属性がtrueに設定され、positionedFromEnd属性がtrueに設定されている場合は、第2パネルがかわりに非表示になります。視覚的には、ユーザーは、ボタン上の矢印の方向を参照することで、縮小されるパネルを知ることができます。ユーザーがスプリッタ上の矢印ボタンをクリックすると、矢印の方向にパネルが縮小します。

6. デフォルトでは、panelSplitterコンポーネントは使用可能なブラウザ領域に合せて拡大されます。子を拡大しないコンポーネントにpanelSplitterを配置する場合は、panelSplitterコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

「プロパティ」ウィンドウで、DimensionsFromを次の1つに設定します。

- children: 拡大するかわりに、panelSplitterコンポーネントは子コンポーネントからディメンションを取得します。

注意:

この設定を使用し、orientation属性をverticalに設定した場合、collapsibleパネルのコンテンツは子コンポーネントによって決定されずに、splitterPosition属性の値によって決定されます。他のペインのサイズは、その子コンポーネントによって決定されます。

また、この設定を使用している場合は、panelSplitterコンポーネントの高さを(たとえば、inlineStyleまたはstyleClass属性を通じて)設定することはできません。設定すると、panelSplitterの高さと子コンポーネントの高さが競合する原因となります。

- parent: panelSplitterコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: panelSplitterコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelSplitterコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelSplitterコンポーネントはその子コンポーネントのサイズに基づきます。

7. コンポーネントにコンテンツを配置するには、必要なコンポーネントをfirstファセットおよびsecondファセットにドラッグ・アンド・ドロップします。orientationがhorizontalに設定されている場合、firstファセットがleftファセットになります。orientationがverticalに設定されている場合、firstファセットがtopファセットになります。子コンポーネントを拡大する場合には、拡大がサポートされているコンポーネントである必要があります。詳細は、9.5.2項「ジオメトリ管理およびpanelSplitterコンポーネントに関する必知事項」を参照してください。
JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelSplitterコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・スプリッタ」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

8. 3つ以上のペインを作成するには、別のパネル・スプリッタ・コンポーネントをファセットに挿入し、ネストされたスプリッタ・ペインを作成します(図9-20を参照)。

図9-20 ネストしたpanelSplitterコンポーネント

例9-3に、スプリッタ・コンポーネントをネストする際に、JDeveloperによって生成されるコードを示します。

例9-3 ネストしたpanelSplitterコンポーネント

<af:panelSplitter ...>
<f:facet name="first">
<!-- first panel child components components here -->
</f:facet>
<f:facet name="second">
<!-- Contains nested splitter component -->
<af:panelSplitter orientation="vertical" ...>
<f:facet name="first">
<!-- first panel child components components here -->
</f:facet>
<f:facet name="second">
<!-- second panel child components components here -->
</f:facet>
</af:panelSplitter>
</f:facet>
</af:panelSplitter>

9. ユーザーがパネルを開閉する際にいくつかの操作を実行する必要がある場合は、clientListenerタグを使用して、collapsed属性およびpropertyChangeイベント・タイプにクライアント・サイドのJavaScriptスクリプトをアタッチします。クライアント側のイベントの詳細は、第6章「イベントの処理」を参照してください。

9.5.2 ジオメトリ管理およびpanelSplitterコンポーネントに関する必知事項

panelSplitterコンポーネントは子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次のコンポーネントは、panelSplitterコンポーネントのfirstまたはsecondファセットの内部で拡大できます。

- decorativeBox(拡大するように構成されている場合)

- calendar

- inputText(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox(拡大するように構成されている場合)

- panelCollection(拡大するように構成されている場合)

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合のみ)

- panelHeader(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- showDetailHeader(拡大するように構成されている場合)

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

panelSplitterコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelLabelAndMessage

- panelList

- showDetail

- tableLayout (MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、panelSplitterコンポーネントのファセットに拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelBoxコンポーネントにコンテンツを配置し、panelSplitterコンポーネントのファセットに配置するように設定する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをpanelSplitterコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、9.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

9.6 事前定義済固定領域へのページ・コンテンツの配置

panelBorderLayoutコンポーネントは、ファセットを使用してコンポーネントをページの事前定義済領域に含めます。centerファセットのかわりに、panelBorderレイアウト・コンポーネントは0からn個の直接子コンポーネント(索引付きの子とも呼ばれます)を受け取り、それらが中央に連続的にレンダリングされます。ファセットは子コンポーネントを囲みます。

図9-21に、panelBorderLayoutコンポーネントのファセットを示します。

図9-21 panelBorderLayoutのファセット

panelBorderLayoutコンポーネントのサポートされている12のファセットは次のとおりです。

- top: 中央領域の上に子コンポーネントがレンダリングされます。

- bottom: 中央領域の下に子コンポーネントがレンダリングされます。

- start: 複数の読み方向がサポートされます。クライアント・ブラウザの読み方向が左から右の場合、このファセットは、topおよびbottomファセットの子コンポーネントの間にある中央領域の左側に子コンポーネントをレンダリングします。読み方向が右から左の場合、子コンポーネントは中央領域の右側にレンダリングされます。アプリケーションで両方の読み方向をサポートする必要がある場合は、このファセットを使用すると、方向が変更されてもコンテンツが適切な場所に表示されます。両方の方向をサポートする必要がない場合は、leftまたはrightファセットを使用します。

- end: 複数の読み方向がサポートされます。クライアント・ブラウザの読み方向が左から右の場合、このファセットは、topおよびbottomファセットの子コンポーネントの間にある中央領域の右側に子コンポーネントをレンダリングします。読み方向が右から左の場合、子コンポーネントは中央領域の左側にレンダリングされます。アプリケーションで両方の読み方向をサポートする必要がある場合は、このファセットを使用すると、方向が変更されてもコンテンツが適切な場所に表示されます。両方の方向をサポートする必要がない場合は、leftまたはrightファセットを使用します。

- left: 1つの読み方向のみがサポートされます。このファセットは、topおよびbottomファセットの子コンポーネントの間にある中央領域の左側に子コンポーネントをレンダリングします。読み方向が左から右で、leftおよびstartファセットの両方が使用されている場合には、leftファセットがstartファセットより優先されます(つまり、startファセットのコンテンツは表示されません)。読み方向が右から左で、leftおよびendファセットの両方が使用されている場合にも、leftファセットがendファセットより優先されます。

- right: 1つの読み方向のみがサポートされます。このファセットは、topおよびbottomファセットの子コンポーネントの間にある中央領域の右側に子コンポーネントをレンダリングします。読み方向が左から右で、rightおよびendファセットの両方が使用されている場合は、rightファセットがendファセットより優先されます。読み方向が右から左で、rightおよびstartファセットの両方が使用されている場合は、rightファセットがstartファセットより優先されます。

- innerTop: 中央領域の上でtopファセットの子コンポーネントの下に子コンポーネントがレンダリングされます。

- innerBottom: 中央領域の下でbottomファセットの子コンポーネントの上に子コンポーネントがレンダリングされます。

- innerLeft: leftファセットと同じように子コンポーネントをレンダリングしますが、innerTopとinnerBottomファセット、およびleftファセットと中央領域の間にレンダリングします。

- innerRight: rightファセットと同じように子コンポーネントをレンダリングしますが、innerTopファセットとinnerBottomファセット、およびrightファセットと中央領域の間にレンダリングします。

- innerStart: 読み方向が左から右の場合は、innerLeftファセットと同じように子コンポーネントをレンダリングします。読み方向が右から左の場合は、innerRightファセットと同じように子コンポーネントをレンダリングします。

- innerEnd: 読み方向が左から右の場合は、innerRightファセットと同じように子コンポーネントをレンダリングします。読み方向が右から左の場合は、innerLeftファセットと同じように子コンポーネントをレンダリングします。

panelBorderLayoutコンポーネントでは子コンポーネントの拡大がサポートされておらず、子コンポーネントが拡大されるコンポーネント内に配置されても拡大しません。そのため、各ファセットのサイズは、このコンポーネントに含まれているコンポーネントのサイズで決定されます。コンテンツをブラウザ・ウィンドウに合せて拡大する場合は、かわりにpanelStretchLayoutコンポーネントを使用することを検討してください。詳細は、9.4項「コンテンツをページ全体に拡大するための設定」を参照してください。

9.6.1 panelBorderLayoutコンポーネントを使用して事前定義済固定領域にページ・コンテンツを配置する方法

JSFページに使用できるpanelBorderLayoutコンポーネントの数に制限はありません。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.6項「事前定義済固定領域へのページ・コンテンツの配置」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelBorderLayoutコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル枠線レイアウト」をJSFページにドラッグ・アンド・ドロップします。

2. 「コンポーネント」ウィンドウから、panelBorderLayoutコンポーネントの子コンポーネントとして、ウィンドウ中央へのコンテンツの表示に使用するコンポーネントをドラッグ・アンド・ドロップします。
子コンポーネントは、挿入した順番で連続して表示されます。他のタイプのレイアウトで子コンポーネントを表示する場合は、panelGroupLayoutコンポーネントにそのコンポーネントをラップします。詳細は、9.13項「関連する項目のグループ化」を参照してください。

3. 中央を囲むコンテンツを配置するには、必要なコンポーネントを各ファセットにドラッグ・アンド・ドロップします。
JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelBorderLayoutコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル枠線レイアウト」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

9.7 フォームでのコンテンツの配置

panelFormLayoutコンポーネントを使用すると、入力フィールドや選択リスト・フィールドなど、複数のコンポーネントを1つ以上の列に配置できます。File Explorerアプリケーションでは、panelFormLayoutコンポーネントを使用してファイル・プロパティが表示されています。図9-22に示されているように、コンポーネントはラベルが右揃えになるように構成されています。

図9-22 フォーム内の右揃えのラベルおよび左揃えのフィールド

図9-23に、ラベルがフィールドの上に表示されるように構成されているコンポーネントを使用した同じページを示します。

図9-23 フォーム内でフィールドの上に表示されているラベル

1つ以上の列にラベル付きのフィールドを表示するようにpanelFormLayoutコンポーネントを構成できます。フォームの各フィールドは、panelFormLayoutコンポーネントの子コンポーネントです。目的の行数を設定し、行より多くの子コンポーネントがある場合は、残りの子コンポーネントが新しい列に配置されます。例9-4に、10個のinputText子コンポーネントを持つpanelFormLayoutコンポーネントを示します。

例9-4

<af:panelFormLayout id="pfl1" rows="10">
<af:inputText label="Label 1" id="it1"/>
<af:inputText label="Label 2" id="it2"/>
<af:inputText label="Label 3" id="it3"/>
<af:inputText label="Label 4" id="it4"/>
<af:inputText label="Label 5" id="it5"/>
<af:inputText label="Label 6" id="it6"/>
<af:inputText label="Label 7" id="it7"/>
<af:inputText label="Label 8" id="it8"/>
<af:inputText label="Label 9" id="it9"/>
<af:inputText label="Label 10" id="it10"/>
</af:panelFormLayout>

panelFormLayoutのrow属性は10に設定されているため、10個のinputTextコンポーネントは、図9-24に示すようにすべて1つの列に表示されます。

図9-24 1つの列に表示されたすべてのinputTextコンポーネント

ただし、row属性が8に設定されている場合は、図9-25に示すように、最初の8個のinputTextコンポーネントは最初の列に表示され、最後の2つのコンポーネントは2列目に表示されます。

図9-25 2列に表示されたコンポーネント

ただし、それぞれに表示される行数は、構成された行数によってのみ決定されるわけではありません。panelFormLayoutコンポーネントのmaxColumns属性は、デフォルトで、4列以上レンダリングしないように設定されています(PDAアプリケーションの場合は2列)。この値により、実際に行数が決定されます。たとえば、25の子コンポーネントがあり、5行表示するようにコンポーネントを設定し、デフォルトの最大列数を3に設定したままにした場合、5行表示するように設定しても、実際はコンポーネントにより9行表示されます。これは、最大列数が設定された行数をオーバーライドするためです。最大3列のみ許可するように設定されているため、すべての子コンポーネントを表示するにはコンポーネントで9行を使用する必要があります。コンポーネントで5行のみが表示されるようにするには、最大列数を5に設定する必要があります。

ADF Facesでは、ブラウザの標準のHTMLフローで決定されたデフォルトのラベル幅およびフィールド幅が使用されます。また、ラベルおよびフィールドに使用する明示的な幅を指定できます。フォーム・レイアウト内の列数にかかわらず、指定する幅はすべてのラベルとフィールドに適用されます。幅は、ピクセル単位の絶対数またはパーセント値を使用して指定します。ラベルの長さが合わない場合は、テキストが折り返されます。

ヒント:

ページが英語以外の言語で表示される場合は、異なる言語および文字で使用するためにラベルに余分な空白を残す必要があります。

9.7.1 panelFormLayoutコンポーネントの使用方法

ページに1つ以上のpanelFormLayoutコンポーネントを使用して、必要なフォーム・レイアウトを作成できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.7項「フォームでのコンテンツの配置」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelFormLayoutを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・フォーム・レイアウト」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、ラベルの配置を設定します。
デフォルトで、子の入力コンポーネントのフィールド・ラベルはフィールドの横に表示されます。フィールドの上にラベルを配置するには、labelAlignment属性をtopに設定します。

注意:

panelFormLayoutコンポーネントを別のpanelFormLayoutコンポーネントにネストすると、ネストされたレイアウトのラベルの位置はtopになります。

3. rowsおよびmaxColumnsを設定して、panelFormLayoutコンポーネントの行数と列数を決定します。
rows属性の値は、ADF Facesにより、その後から新しい列が開始される行の番号として使用される数値です。デフォルトでは、2147483647 (Integer.MAX_VALUE)に設定されています。これは、rendered="true"およびvisible="true"に設定されているすべての子コンポーネントが、単一の列にレンダリングされることを意味します。

フォームに複数の列を含める場合は、rows属性をレンダリングされる子コンポーネントの倍数に設定し、maxColumns属性をフォームに表示する最大列数に設定します。maxColumnsのデフォルト値は3です。(PDAの場合、デフォルトは2です。)

注意:

panelFormLayoutコンポーネントが別のpanelFormLayoutコンポーネント内に存在している場合、内側のpanelFormLayoutコンポーネントのmaxColumns値は常に1です。

たとえば、rows属性が6に設定されていて、レンダリングされた子が1から6ある場合、リストは1列に表示されます。レンダリングされた子コンポーネントが7から12ある場合、リストは2列に表示されます。子コンポーネントが13以上ある場合、リストは3列に表示されます。レンダリングされたすべての子コンポーネントを1列に表示するには、rows属性をデフォルトの値に設定しなおします。

レンダリングされた子コンポーネントの数に、maxColumn属性で許可されている数を超える列が必要な場合には、rows属性の値がオーバーライドされます。たとえば、レンダリングされた子コンポーネントが100あり、rows属性が30に設定されていて、maxColumns属性が3(デフォルト)の場合、リストは3列34行で表示されます。maxColumns属性が2に設定されている場合、リストは2列51行で表示されます。

ヒント:

レンダリングされた子コンポーネントが参照するのは、panelFormLayoutコンポーネントの直接の子コンポーネントのみです。そのため、複数の行をレンダリングするコンポーネント(selectManyCheckboxなど)が子の場合は、そのすべての行がレンダリングされた単一の子とみなされ、別々の列に分割できません。

4. 必要に応じてfieldWidthおよびlabelWidthを設定します。
ADF Facesでは、ブラウザの標準のHTMLフローで決定されたデフォルトのラベル幅およびフィールド幅が使用されます。また、ラベルおよびフィールドに使用する明示的な幅を指定できます。

panelFormLayoutコンポーネントのlabelWidth属性ではラベルの優先幅を、fieldWidth属性ではフィールドの優先幅を設定できます。

注意:

labelWidthコンポーネントに指定する値は、labelAlignment属性がtopに設定されていて、ラベルがフィールドの上に表示されるレイアウトでは無視されます。

フォーム・レイアウト内の列数にかかわらず、指定する幅はすべてのラベルとフィールドに適用され、異なる列に異なる幅を設定することはできません。em、px、%などの任意のCSS単位を使用して幅を指定します。使用される単位は、labelWidth属性とfieldWidth属性の両方で同じである必要があります。

パーセント値を使用する場合は次のようにします。

- 指定するパーセント幅は、表示される列数に関係なく、panelFormLayoutコンポーネントが占有する幅全体のパーセントです。

- labelWidthおよびfieldWidthのパーセントの合計は、100%になる必要があります。合計が100%未満の場合、幅は100%になるように正規化されます。たとえば、labelWidthを10%に、fieldWidthを30%に設定した場合、実行時にlabelWidthは33%に、fieldWidthは67%になります。

- 一方の幅を明示的に設定してもう一方の幅を指定しない場合(labelWidthのパーセントは指定してfieldWidthは指定しないなど)、指定されていないパーセント幅がADF Facesにより自動的に計算されます。

注意:

panelFormLayoutコンポーネントに複数の列とフッターが含まれている場合、パーセントの分数分割がサポートされていないWebブラウザでは、メインのフォーム項目とフッター項目の位置の間にわずかにオフセットが生じることがあります。この影響を最小限にするために、labelWidthのパーセントは、列数で均等に分割できるようにしてください。

panelFormLayoutコンポーネントの幅が領域の600ピクセルを占有し、labelWidth属性が50%に設定されているとします。1列に表示される場合、ラベル幅もフィールド幅も300ピクセルになります。2列に表示される場合は、各列が300ピクセルであるため、列の各ラベル幅とフィールド幅は150ピクセルになります。

ラベル・テキストの長さが指定されたラベル幅の1行に収まらない場合は、ADF Facesによりラベル・テキストが自動的に折り返されます。指定されたフィールド幅がpanelFormLayoutコンポーネントに配置した子コンテンツの最低サイズより狭い場合は、子コンテンツの最低サイズがフィールド幅として自動的に使用されます。

注意:

割り当てられた領域よりフィールドが広い場合、ブラウザはフィールドを切り捨てず、ラベル列の領域を使用します。これが原因で、ラベルが予想以上に折り返される可能性があります。この場合は、フィールド・コンテンツの幅を狭くすることを検討してください(inputTextコンポーネントに、幅がより狭いcontentStyleを使用するなど)。

5. 必要な子コンポーネントを挿入します。
通常は、入力テキストやチェック・ボックスを複数選択などのラベル付きのフォーム入力コンポーネント、およびユーザーの入力を可能にするその他の類似のコンポーネントを挿入します。

ヒント:

通常はpanelFormLayoutコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelFormLayoutコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

例9-5は、図9-22に示したFile Explorerアプリケーションのproperties.jspxページで使用されているpanelFormLayoutコンポーネントを示します。

例9-5 panelFormLayoutコンポーネント

<af:panelFormLayout rows="5" id="pfl1">
<af:inputText value="#{fileItemProperties.type}"
label="#{explorerBundle['fileproperties.type']}"
readOnly="true" id="it2"/>
<af:inputText value="#{fileItemProperties.location}"
label="#{explorerBundle['fileproperties.currentpath']}"
readOnly="true" id="it3"/>
<af:inputText value="#{fileItemProperties.size}"
label="#{explorerBundle['fileproperties.size']}"
readOnly="true" id="it4"/>
<af:inputText value="#{fileItemProperties.contains}"
label="#{explorerBundle['fileproperties.contains']}"
readOnly="true" id="it5"/>
</af:panelFormLayout>

ヒント:

入力コンポーネント以外のコンポーネント(label属性がない)を使用する場合、またはpanelFormLayoutコンポーネント内の単一のラベルで複数の入力コンポーネントをグループ化する場合は、まずpanelLabelAndMessageコンポーネントにそのコンポーネントをラップします。panelLabelAndMessageコンポーネントの使用方法の詳細は、19.4項「単一のラベルおよびメッセージを使用したコンポーネントのグループ化」を参照してください。

6. フォーム・レイアウトに意味的に関連する入力コンポーネントをグループ化するには、groupコンポーネントを使用してグループに属するコンポーネントをラップします。group内にコンポーネントを配置すると、デフォルトではpanelFormLayoutコンポーネントによりグループの始まりと終わりにセパレータが描かれます。StartBoundaryおよびEndBoundary属性の設定により、セパレータを常に表示または常に表示しないようにgroupコンポーネントを構成できます。
groupコンポーネントの使用方法の詳細は、9.7.2項「groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法に関する必知事項」を参照してください。

7. 子の入力コンポーネントの下にコンテンツを追加するには、必要なコンポーネントをfooterファセットに挿入します。
JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

例9-6に、panelFormLayoutコンポーネントにpanelGroupLayoutコンポーネントを使用してfooterの子コンポーネントを配置するサンプル・コードを示します。

例9-6 水平に配置されたpanelFormLayoutのfooterの子コンポーネント

<af:panelFormLayout>
<f:facet name="footer">
<af:panelGroupLayout layout="horizontal">
<af:button text="Save"/>
<af:button text="Cancel"/>
<f:facet name="separator">
<af:spacer width="3" height="3"/>
</f:facet>
</af:panelGroupLayout>
</f:facet>
.
.
.
</af:panelFormLayout>

9.7.2 groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法に関する必知事項

groupコンポーネント自体は何もレンダリングしませんが、panelFormLayoutコンポーネントの子のコンポーネントをグループ化するために使用すると、デフォルトにより各groupコンポーネントの子コンポーネントの周辺にセパレータが表示されます。たとえば、panelFormLayoutコンポーネントによって作成されたフォーム・レイアウト内のいくつかの入力フィールドをグループ化するとします。title属性を使用してグループのタイトルを表示することも選択できます。

注意:

グループ・タイトルの横の長さが現在のpanelFormLayout列の幅より短いと、タイトルが収まるようにpanelFormLayoutの横幅が拡大されます。

startBoundary属性はグループの上にセパレータを表示するかどうか制御し、endBoundary属性はグループの下にセパレータを表示するかどうか制御します。線を表示するには、その属性をshowに設定します。線を非表示にするには、その属性をhideに設定します。2つの隣り合うグループに線を表示しないようにするには、隣接部の属性を両方ともhideに設定するか、1つをhideに、もう1つをdontCareに設定します。デフォルトでは、これらの属性はdontCareに設定されます。つまり、親のコンポーネント(この場合はpanelFormLayoutコンポーネント)に線が表示されます。

例9-7に、panelFormLayoutコンポーネント内の3セットの子コンポーネントをグループ化するサンプル・コードを示します。最初のグループではセパレータが非表示に設定されています。ただし、2番目のグループはグループの開始位置にセパレータを表示するように構成されているため、線が表示されます。2番目のグループはタイトルとグループの終了位置の線も表示するように設定されています。3番目のグループは、startBoundary属性がdontCareに設定されているため、2番目のグループの終了位置の線が表示されます。

例9-7 panelFormLayoutの子コンポーネントのグループ化

<af:panelFormLayout maxColumns="1" labelWidth="75" id="pfl4">
<af:group id="g1" startBoundary="hide" endBoundary="hide">
<af:selectOneChoice label="Prompt" value="option1" id="soc4">
<af:selectItem label="Option 1" value="option1" id="si30"/>
<af:selectItem label="Option 2" value="option2" id="si31"/>
</af:selectOneChoice>
<af:selectOneChoice label="Prompt" value="option1" id="soc5">
<af:selectItem label="Option 1" value="option1" id="si32"/>
<af:selectItem label="Option 2" value="option2" id="si33"/>
</af:selectOneChoice>
<af:panelLabelAndMessage label="Prompt" id="plam6" for="it6">
<af:panelGroupLayout layout="horizontal" id="pgl4">
<af:inputText simple="true" contentStyle="width: 100px;"
label="inputText" id="it6"/>
<af:button partialSubmit="true" text="Browse..." id="cb3"/>
</af:panelGroupLayout>
</af:panelLabelAndMessage>
</af:group>
<af:group id="g2" title="Grouped Set of Forms" startBoundary="show"
endBoundary="show">
<af:selectManyListbox label="Prompt" contentStyle="width: 100px"
id="sml3">
<af:selectItem label="Option 1" value="option1" id="si34"/>
<af:selectItem label="Option 2" value="option2" id="si35"/>
<af:selectItem label="Option 3" value="option3" id="si36"/>
<af:selectItem label="Option 4" value="option4" id="si37"/>
</af:selectManyListbox>
</af:group>
<af:group id="g3" startBoundary="dontCare" endBoundary="dontCare">
<af:selectManyCheckbox label="Prompt" id="smc3">
<af:selectItem label="Value 1" value="value1" id="si38"/>
<af:selectItem label="Value 2" value="value2" id="si39"/>
<af:selectItem label="Value 3" value="value3" id="si40"/>
</af:selectManyCheckbox>
</af:group>
</af:panelFormLayout>

図9-26に示すように、実行時にはpanelFormLayoutコンポーネントにより、子コンポーネントの2番目のgroupの前後にセパレータが描かれタイトルが添えられます。

図9-26 panelFormLayoutのグループ化されたコンポーネント

9.7項「フォームでのコンテンツの配置」で説明したように、panelFormLayoutコンポーネントは特定のコンポーネント属性を使用して、列と行にその子コンポーネントを表示する方法(グループ化および非グループ化)を決定します。groupコンポーネントを使用して、子コンポーネントを複数の列に表示するpanelFormLayoutコンポーネントに関連コンポーネントをグループ化する場合、groupコンポーネントの子コンポーネントは常に同じ列に表示されるため、groupコンポーネントの内部の子コンポーネントは列をまたがって分割されません。

JSPページでは、ファセットに1つの子コンポーネントしか含められません(Faceletページには制限がありません)。そのため、panelFormLayoutコンポーネントのfooterファセットの子コンポーネントをgroupコンポーネントを使用してグループ化する場合は、例9-8に示すように、すべてのgroupコンポーネントおよびグループ化されていないその他の子コンポーネントを、1つのルートgroupコンポーネントに配置する必要があります。

例9-8 ルートgroupコンポーネントが1つ含まれるpanelFormLayoutのfooterファセット

<af:panelFormLayout ...>
<f:facet name="footer">
<af:group id="g2">
<af:inputText rows="2" label="footer item 1" id="it10"/>
<af:group id="g3">
<af:inputText columns="5" label="footer group item 1"
id="it11"/>
<af:inputText columns="5" label="footer group item 2"
id="it12"/>
<af:inputText columns="5" label="footer group item 3"
id="it13"/>
</af:group>
<af:panelGroupLayout layout="horizontal" id="pgl2">
<f:facet name="separator">
<af:spacer width="10" id="s2"/>
</f:facet>
<af:button text="Page 1" partialSubmit="true"
id="cb3"/>
<af:button text="Page 2" partialSubmit="true"
id="cb4"/>
</af:panelGroupLayout>
</af:group>
</f:facet>
.
.
.
</af:panelFormLayout>

図9-27に示すように、panelFormLayoutコンポーネントのグループ化された子コンポーネントと同じように、panelFormLayoutコンポーネントにより、実行時にデフォルトでfooterファセットの各groupコンポーネントの子コンポーネントの周辺にセパレータがレンダリングされます。

図9-27 グループ化されたコンポーネントを含むpanelGroupLayoutのfooter

注意:

JSPページでは、panelFormLayoutコンポーネントのfooterファセットでサポートされているのは、2レベルのグループ化されたコンポーネントのみで、footerファセットに3レベル以上ネストしたgroupコンポーネントを配置することはできません。たとえば、次のコードは無効です。

<f:facet name="footer">
<!-- Only one root group -->
<af:group id-"g1">
<af:outputText value="Footer item 1" id="ot1"/>
<!-- Any number of groups at this level -->
<af:group id="g2">
<af:outputText value="Group 1 item 1" id="ot2"/>
<af:outputText value="Group 1 item 2" id="ot3"/>
<!-- But not another nested group. This is illegal. -->
<af:group id="g3">
<af:outputText value="Nested Group 1 item 1" id="ot4"/>
<af:outputText value="Nested Group 1 item 2" id="ot5"/>
</af:group>
</af:group>
<af:outputText value="Another footer item" id="ot6"/>
</af:group>
</f:facet>

groupコンポーネントがpanelFormLayout列の最初にあると、startBoundaryがshowに設定されていても上にセパレータは表示されません。列の最後のgroupコンポーネントも同様に、endBoundary属性がshowに設定されていても、下にセパレータは表示されません。

9.8 ダッシュボードでのコンテンツの配置

panelDashboardコンポーネントでは、panelFormコンポーネントと同様に、行および列にその子コンポーネントを配置できます。ただし、図9-28に示されているように、panelDashboardの子は、テキスト・コンポーネントではなく、コンテンツを含むpanelBoxコンポーネントです。

図9-28 panelBoxの子コンポーネントを含むpanelDashboard

panelDashboardコンポーネントを追加する場合、コンポーネントに含まれる列数および各行の高さを構成します。ダッシュボードは、子を拡大して構成済の領域を埋めます。すべての子コンポーネントが、指定した列数と行の高さ内に収まらない場合、panelDashboardコンポーネントにスクロールバーが表示されます。

子を拡大するコンポーネントに配置した場合、デフォルトで、panelDashboardは子の数にかかわらずその親コンテナに合せて拡大されます。これは、ブラウザがダッシュボードのニーズを超えてサイズ変更された場合に、ダッシュボードに空白の領域があることを意味する場合があります。

たとえば、dimensionsFrom属性をparentに設定することでpanelDashboardがその親からサイズを継承するように設定したとします。列を1に、rowHeightを50pxに設定します。次に、2つのpanelBoxコンポーネントを追加します。columnsは1に設定されているため、行は2つになります。親コンポーネントはpanelStretchLayoutであるため、panelDashboardはボックスの高さにかかわらずpanelStretchLayoutに合せて拡大され、図9-29に示すように最終的に余分な領域ができます(ダッシュボードの色が紫紅に変わり、境界が見やすくなります)。

図9-29 領域に合せて拡大されたpanelDashboard

ダッシュボードを拡大しない場合は、子を拡大しないコンポーネントに配置し、(dimensionsFrom属性をchildrenに設定することで)子に基づいてサイズを決定するようにpanelDashboardを構成します。これは、rowHeight属性を乗算することで、子の表示に必要な行数と同じ高さになります。

前の例では、scrollに設定されたpanelGroupLayoutにダッシュボードを配置した場合、rowHeightが50に設定されているため、図9-30に示すように、ブラウザ・ウィンドウのサイズにかかわらず、panelDashboardは常に100pxの高さを少し上回ります。

図9-30 拡大されないpanelDashboard

panelDashboardコンポーネントでは、宣言的なドラッグ・アンド・ドロップ動作もサポートされており、ユーザーは子コンポーネントを再配置できます。図9-31に示されているように、ユーザーは、たとえばpanelBox 10をpanelBox 4とpanelBox 5の間に移動できます。ボックスをドロップできる場所にはシャドウが表示されます。

図9-31 panelDashboardのドラッグ・アンド・ドロップ機能

注意:

ユーザーがコンポーネントをpanelDashboardコンポーネントの内外にドラッグできるドラッグ・アンド・ドロップ機能を構成することもできます。詳細は、36.6項「panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加」を参照してください。

子コンポーネントを移動する機能とともに、panelDashboardコンポーネントは、ユーザーが子コンポーネントをレンダリングから非レンダリングに切り替えられるようにし、挿入または削除されるpanelBoxesの外観を与えるAPIも提供します。ダッシュボードは、部分ページ・レンダリングを使用して、ページ全体を再描画することなく子コンポーネントの新しいセットを再描画します。

panelDashboardBehaviorタグを使用して、コンポーネントのレンダリングの応答性を向上させることができます。このタグを使用すると、コマンド・コンポーネントをアクティブ化し、視覚的な変更をダッシュボードに適用してから、アプリケーション・コードでサーバーのコンポーネント・ツリーを変更できます。アクション・イベントがサーバーに送信される前に、この領域の拡大が行われるため、コマンド・コンポーネントのアクション・リスナーがコンポーネント・ツリーを変更し、ダッシュボードでの挿入の最適化されたエンコーディングを準備している間に、ユーザーはすぐにフィードバックを確認できます。

たとえば、図9-32は、panelSplitterコンポーネントの右パネルで使用されるpanelDashboardコンポーネントを示しています。左パネルにリンクとして表示されているリスト項目は、panelDashboardの各panelBoxコンポーネントを表しています。すべてのpanelBoxコンポーネントが表示されている場合、リンクはすべて非アクティブです。ただし、ユーザーがpanelBoxコンポーネントの1つを削除すると、対応するリンクがアクティブになります。ユーザーはそのリンクをクリックして、panelBoxを再挿入できます。panelDashboardBehaviorタグをcommandLinkコンポーネントとともに使用することで、ユーザーは挿入済ボックスの描画を確認できます。

図9-32 panelDashboardBehaviorタグを使用するcommandLinkコンポーネント

このタグを使用しない場合、アクション・リスナーが処理している間、ユーザーがダッシュボード構造に対する変更を確認できるまで多少の遅延があります。

図9-33は、panelDashboardコンポーネントを使用した実際的な例を示しています。ページの上部にあるリンクの1つを選択すると、ダッシュボードに表示されるpanelBoxesが変わります。ページの左側にある関連リンクをクリックして、panelBoxを追加することもできます。

図9-33 panelDashboardの実際的な例

9.8.1 panelDashboardコンポーネントの使用方法

panelDashboardをページに追加した後で、ダッシュボードを構成して、拡大するかどうかを決定できます。その後、子コンポーネントを追加し、コンポーネントを再配置できるようにする場合は、子コンポーネントにもcomponentDragSourceタグを追加します。コンポーネントの挿入および削除を許可する場合は、アクションを処理するためのリスナーを実装します。panelDashboardBehaviorタグを使用して、panelDashboardコンポーネントでの挿入への応答性を向上させることもできます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.8項「ダッシュボードでのコンテンツの配置」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelDashboardコンポーネントを使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・ダッシュボード」をページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。

3. columnsを、子コンポーネントを表示するために使用する列数に設定します。子コンポーネントは各列に合せて拡大されます。

4. RowHeightを、各行の高さのピクセル数に設定します。子コンポーネントは、この高さまで拡大されます。

5. デフォルトでは、panelDashboardコンポーネントは使用可能なブラウザ領域に合せて拡大されます。かわりに、panelDashboardコンポーネントを、子を拡大しないコンポーネントの子として使用する場合は、panelDashboardコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

「外観」セクションで、DimensionsFromを次のいずれかに設定します。

- children: panelDashboardコンポーネントは、子コンポーネントからディメンションを取得します。

注意:

この設定を使用する場合は、panelDashboardコンポーネントの高さを(たとえばinlineStyleまたはstyleClass属性を通じて)設定できません。設定すると、panelDashboardの高さと子コンポーネントの高さが競合する原因となります。

- parent: panelDashboardコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: panelDashboardコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelDashboardコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelDashboardコンポーネントはその子コンポーネントのサイズに基づきます。

6. 「コンポーネント」ウィンドウから、panelBox子コンポーネントをドラッグ・アンド・ドロップします。

ヒント:

panelDashboardコンポーネントでは、regionコンポーネントも子コンポーネントとしてサポートされています。

7. ユーザーが子コンポーネントを並べ替えられるようにするには、「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「コンポーネント・ドラッグ元」を各子コンポーネントに子としてドラッグ・アンド・ドロップします。

8. コンポーネントを追加および削除できるようにする場合は、マネージドBeanを作成し、子の追加またはドロップ時に子の並替えを行うハンドラ・メソッドを実装します。このイベントはドロップ・イベントとみなされるため、ドラッグ・アンド・ドロップ・フレームワークを使用する必要があります。ドロップ・イベントのハンドラの作成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。
最適化されたライフサイクルを使用するには、ハンドラにpanelDashboardコンポーネントのprepareOptimizedEncodingOfInsertedChild()メソッドをコールさせます。これにより、挿入された子コンポーネントのみがレンダリングのためにダッシュボードから送信されます。

注意:

panelDashboardBehaviorタグを使用する予定の場合は、関連付けられているコマンド・コンポーネントのactionListenerハンドラからこのAPIをコールする必要があります。

9. 手順7でcomponentDragSourceタグを追加した場合、panelDashboardのDropEventハンドラも実装する必要があります。panelDashboardコンポーネントを選択している状態で、「動作」セクションを開き、DropListener属性をハンドラ・メソッドにバインドします。

10. panelDashboardBehaviorタグを使用する場合は、挿入を開始するために使用するコマンド・コンポーネントをドラッグ・アンド・ドロップします。

11. 「プロパティ」ウィンドウで、コマンド・コンポーネントのActionListenerを、コンポーネント・ツリーの変更を処理するマネージドBeanのハンドラにバインドします。ハンドラでpanelDashboardコンポーネントのprepareOptimizedEncodingOfInsertedChild()メソッドをコールします。これにより、挿入されたレンダリング対象の子コンポーネントのみがダッシュボードから送信されます。例9-9に、子コンポーネントの挿入を処理するマネージドBeanのコードを示します。

例9-9 「挿入」ボタンのアクション・リスナー・コード

public void handleInsert(ActionEvent e)
{
UIComponent eventComponent = e.getComponent();
String panelBoxId = eventComponent.getAttributes().get("panelBoxId").toString();
UIComponent panelBox = _dashboard.findComponent(panelBoxId);

// Make this panelBox rendered:
panelBox.setRendered(true);

// Becaue the dashboard is already shown, perform an optimized
// render so the whole dashboard does not have to be re-encoded:
int insertIndex = 0;
List<UIComponent> children = _dashboard.getChildren();
for (UIComponent child : children)
{
if (child.equals(panelBox))
{
// Let the dashboard know that only the one child component should be
// encoded during the render phase:
_dashboard.prepareOptimizedEncodingOfInsertedChild(
FacesContext.getCurrentInstance(),
insertIndex);
break;
}

if (child.isRendered())
{
// Count only rendered children because that is all that the
// panelDashboard can see:
insertIndex++;
}
}
// Add the side bar as a partial target because we need to
// redraw the state of the side bar item that corresponds to the inserted item:
RequestContext rc = RequestContext.getCurrentInstance();
rc.addPartialTarget(_sideBar);
}

12. 「コンポーネント」ウィンドウで、「操作」パネルの「動作」グループから「パネル・ダッシュボード動作」タグをドラッグし、コマンド・コンポーネントに子としてドロップします。

13. 「プロパティ」ウィンドウで以下を入力します。

- for: 関連するpanelDashboardコンポーネントのIDを入力します。

- index: 挿入するコンポーネントの索引を決定するメソッドに解決されるEL式を入力します。panelDashboardBehaviorタグを使用する場合、プレースホルダ要素は、サーバーから戻った後で実際のコンポーネントがレンダリングされるDOMツリーに挿入されます。サーバーで挿入が行われる前に挿入のプレースホルダが追加されるため、ユーザーがページをリロードしても、子コンポーネントが継続的に同じ順序で表示されるように、子の挿入場所を指定する必要があります。

9.8.2 ジオメトリ管理およびpanelDashboardコンポーネントに関する必知事項

このコンポーネントでは、列数およびrowHeight属性に基づき、子がグリッドに編成されます。panelDashboard内で拡大可能な子コンポーネントは次のとおりです。

- inputText (rows属性が1より大きく設定され、simple属性がtrueに設定されている場合)

- panelBox

- region(拡大するように構成されている場合)

- table(拡大するように構成されている場合)

その他のコンポーネントを子コンポーネントとしてpanelDashboardコンポーネントに配置しようとすると、コンポーネントの階層は無効になります。

9.9 コンテンツの動的な表示および非表示

ユーザーがコンテンツの表示または非表示を選択できるようにすることが必要な場合があります。ユーザー・インタフェースのすべての機能を一度に表示する必要がなければ、ユーザーの意志でインタフェースの一部を表示および非表示にできるコンポーネントを使用して領域を節約できます。

showDetailコンポーネントを使用すると、ユーザーがラベルの下のコンテンツを開いた状態(表示)または閉じた状態(非表示)にすることが可能な切替えアイコン付きのラベルを作成できます。コンテンツが閉じた状態(非表示)の場合、デフォルトのラベルは「表示」で、展開アイコンが表示されます。コンテンツが開いた状態(表示)の場合、デフォルトのラベルは「非表示」で、縮小アイコンが表示されます。

たとえば、File ExplorerアプリケーションのnewFileItemページでは、showDetailコンポーネントを使用してファイル・プロパティを表示および非表示にしています。図9-34に示すように、コンポーネントは、ページが表示されたらプロパティが非表示になるように構成されています。

図9-34 閉じた状態のshowDetail

ユーザーが切替えアイコンをクリックすると、図9-35に示されているようにプロパティが表示されます。

図9-35 開いた状態のshowDetail

表示されているテキストおよび非表示のテキストを表示するために、outputTextコンポーネントより複雑なコンポーネントを使用する場合は、コンポーネントをshowDetailコンポーネントのpromptファセットに追加できます。表示に設定すると、promptファセットのコンテンツが、表示されているテキストおよび非表示のテキストの値と置き換えられます。showDetailコンポーネントの使用方法は、9.9.1項「showDetailコンポーネントの使用方法」を参照してください。

showDetailコンポーネントと同じように、showDetailHeaderコンポーネントでもコンテンツの表示を切り替えられますが、showDetailHeaderコンポーネントにはヘッダーにラベルと切替えアイコンがあり、メニュー・バー、ツールバーおよびテキスト用のファセットも用意されています。

ヒント:

showDetailHeaderコンポーネントは、表示イベントを処理することを除き、panelHeaderコンポーネントと同じです。panelHeaderコンポーネントの詳細は、9.11項「静的ボックスの項目の表示」を参照してください。

図9-36に示すように、タイトル行のすべてのファセットにすべてを表示するのに十分な領域がない場合、showDetailHeaderテキストが切り捨てられ、省略記号が表示されます。

図9-36 showDetailHeaderが切り捨てられた場合のテキスト

コンテンツを表示するのに十分な領域がある場合は、図9-37に示すように、contextファセットとツールバーの間に追加の領域が配置されます。

図9-37 ツールバーの前に追加された領域

また、showDetailHeaderコンポーネントをエラー、警告、情報または確認のメッセージとして使用するように構成できます。コンテンツは、ヘッダーの下で表示または非表示になります。たとえば、File ExplorerアプリケーションのnewFileItemページはshowDetailHeaderコンポーネントを使用して、新規ファイルの作成のヘルプを表示します。デフォルトでは、図9-35に示すようにヘルプは非表示になります。ユーザーがヘッダー内の切替えアイコンをクリックすると、図9-38に示すように、コンテンツが表示されます。

図9-38 ヘルプの表示に使用されているshowDetailHeaderコンポーネント

showDetailHeaderコンポーネントをpanelHeaderコンポーネントとともに使用してページをセクションとサブセクションに分割し、一部のコンテンツを非表示にできます。showDetailHeaderコンポーネントには、ツールバー・ファセットやメニュー・バー・ファセットなど、いくつかのファセットが含まれます。これらのファセットは、panelHeaderコンポーネントの場合と同じです。panelHeaderコンポーネントの詳細は、9.11項「静的ボックスの項目の表示」を参照してください。

showDetailHeaderコンポーネントをネストさせて、コンテンツの階層を作成できます。ネストされた各コンポーネントのヘッダーは、階層を示すために異なるスタイルになります。図9-39に、ネストした3つのshowDetailHeaderコンポーネントおよびその異なるスタイルを示します。

図9-39 ネストしたshowDetailHeaderコンポーネントにより作成された階層

注意:

サイズの処理は、デフォルトでヘッダー・コンポーネントの物理包含によって決定されます。つまり、最初のヘッダー・コンポーネントは見出しレベル1としてレンダリングされます。最初のヘッダー・コンポーネントにネストされるヘッダー・コンポーネントは見出しレベル2などとしてレンダリングされます。各ヘッダー・コンポーネントの見出しレベルは、headerLevel属性を使用して手動でオーバーライドできます。

panelBoxコンポーネントは、ヘッダーの下に情報を表示または非表示にできるようにする場合、およびページのその他の情報と分けるためのボックスが必要な場合に使用します。File Explorerアプリケーションでは、図9-40に示すように、properties.jspxページに2つのpanelBoxコンポーネントを使用して、属性およびファイルの履歴を表示します。

図9-40 2つのpanelBoxコンポーネント

図9-41に、「履歴」panelBoxコンポーネントが非表示の状態になっている同じページを示します。

図9-41 非表示のpanelBoxコンポーネント

panelBoxコンポーネントに背景色を設定して、コンテンツをページの残りの部分とさらに区別することができます。2色の組合せ(ランプと呼ばれる)が用意されており、各組合せにはnone、light、mediumおよびdarkの4つの色のレベルがあります。図9-42に図9-40と同じパネル・ボックスを示しますが、下のpanelBoxコンポーネントはcoreランプの中間色が表示されるように構成されています。

図9-42 背景色を使用したパネル・ボックス

panelBoxコンポーネントのサイズは、ピクセル・サイズを明示的に割り当てて設定することも、親に対する割合で設定することもできます。また、タイトルの位置を設定することも、アイコンを追加することもできます。また、panelBoxコンポーネントには、ボックスにツールバーおよびツールバー・ボタンを追加できるtoolbarファセットがあります。

showDetail、showDetailHeaderおよびpanelBoxコンポーネントはすべて、サーバー上の表示イベントを処理します。表示イベントは、ユーザーがコンポーネントの表示と非表示を切り替えるたびに送信されます。これは、データが送信または受信されない場合でも、サーバーとのラウンドトリップが必要であることを意味します。表示イベントをクライアント上で処理するようにこれらのコンポーネントを構成して、パフォーマンスを向上させることができます。イベントは別のイベントが送信されるまで、またはコンポーネントがデータの変更を検出するまでサーバーに送信されません。

コンテンツの複数の大きな領域を表示および非表示にする必要がある場合は、panelAccordionおよびpanelTabbedコンポーネントの使用を検討してください。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

9.9.1 showDetailコンポーネントの使用方法

showDetailコンポーネントを使用して、コンテンツの1セットを表示および非表示にできます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

showDetailコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「詳細の表示」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、必要に応じて属性を設定します。
コンポーネントの子コンポーネントを表示する場合は、Disclosedをtrueに設定します。

注意:

コンテンツを表示および非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

DisclosedTextを、コンテンツが開いた状態(表示)の場合に切替えアイコンの隣に表示するラベルに設定します。値が指定されない場合、ラベルはデフォルトで「非表示」になります。

UndisclosedTextを、コンテンツが閉じた状態(非表示)の場合に切替えアイコンの隣に表示するラベルに設定します。値が指定されない場合、ラベルはデフォルトで「表示」になります。

注意:

disclosedTextには値を指定してundisclosedTextには指定しない場合、ADF Facesにより、開いた状態および閉じた状態の両方にdisclosedTextの値が自動的に使用されます。同様に、undisclosedTextには値を指定してdisclosedTextには指定しない場合、コンテンツが非表示または表示されると、undisclosedTextの値が使用されます。

disclosedTextおよびundisclosedTextに指定されたテキストを使用するかわりに、promptファセットを使用して、切替えアイコンの隣にレンダリングされるコンポーネントを追加できます。

showDetailコンポーネントと任意の子コンポーネントとの間のパディングを変更することもできます。詳細は、9.9.5項「スキニングとshowDetailコンポーネントに関する必知事項」を参照してください。

3. 「動作」セクションを開き、ユーザーがコンポーネントのコンテンツを表示または非表示にする際に実行する必要のあるバッキングBeanで、DisclosureListenerをDisclosureListenerメソッドに設定します。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

4. 表示イベントをクライアントで処理する場合は、HandleDisclosureをclientに設定します。イベントは別のイベントが送信されるまで、またはコンポーネントがデータの変更を検出して更新が必要になるまでサーバーに送信されません。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

注意:

disclosureListenerを、表示イベントを処理するリスナー・メソッドにバインドした場合、handleDisclosure値は無視され、イベントはサーバーで処理されます。

パフォーマンスのヒント:

コンポーネントでデータ変更を処理しない場合は、handleDisclosure属性をclientに設定する必要があります。

5. コンテンツを追加するには、必要な子コンポーネントをshowDetailコンポーネントに挿入します。

9.9.2 showDetailHeaderコンポーネントの使用方法

showDetailHeaderコンポーネントは、ヘッダーの下にコンテンツを1セット表示する必要がある場合や、表示または非表示にできるメッセージとしてコンテンツを使用する場合に使用します。showDetailHeaderコンポーネントは、コンテンツを非表示にできるようにする場合に、ヘッダーおよびコンテンツの階層を作成する際にも使用できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

showDetailHeaderコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「ディテール・ヘッダーの表示」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。Textをセクション・ヘッダーのラベルにするテキスト文字列に設定します。

3. Iconを、セクション・ヘッダーのアイコンに使用するイメージ・ファイルのURIに設定します。アイコン・イメージはヘッダー・ラベルの前に表示されます。

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

4. 特定のメッセージ情報の表示にヘッダーを使用している場合は、MessageTypeを次のいずれかの値に設定します。

- confirmation: 指定されたアイコン・イメージが確認アイコン(上に緑のチェックマークが表示されたメモ・ページ)に置き換えられます。

- error: 指定されたアイコン・イメージがエラー・アイコン(中にxがある赤い丸)に置き換えられます。ヘッダー・ラベルも赤に変わります。

- info: 指定されたアイコン・イメージが情報アイコン(中にIがある青い丸)に置き換えられます。

- warning: 指定されたアイコン・イメージが警告アイコン(中に感嘆符がある黄色の三角)に置き換えられます。

- none: デフォルト。icon属性に指定されていないかぎり、アイコンは表示されません。

図9-43に、メッセージ・タイプに使用される各アイコンを示します。

図9-43 メッセージ・タイプに使用されるアイコン

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

5. コンポーネントの子コンポーネントを表示する場合は、Disclosedをtrueに設定します。

注意:

コンテンツを表示および非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

6. 「動作」セクションを開き、ユーザーがコンポーネントのコンテンツを表示または非表示にする際に実行する必要のあるバッキングBeanで、DisclosureListenerをdisclosureListenerメソッドに設定します。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

7. 表示イベントをクライアントで処理する場合は、HandleDisclosureをclientに設定します。イベントは別のイベントが送信されるまで、またはコンポーネントがデータの変更を検出して更新が必要になるまでサーバーに送信されません。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

注意:

disclosureListenerを、表示イベントを処理するリスナー・メソッドにバインドした場合、handleDisclosure値は無視され、イベントはサーバーで処理されます。

パフォーマンスのヒント:

コンポーネントでデータ変更を処理しない場合は、handleDisclosure属性をclientに設定する必要があります。

8. showDetailHeaderコンポーネントがジオメトリ管理を処理する方法を制御する場合は、「外観」セクションを開き、Typeを設定します。コンポーネントの拡大またはその子の拡大を行わない場合は、これをflowに設定します。showDetailHeaderコンポーネントの高さは、その子によってのみ決定されます。コンポーネントの拡大およびその子の拡大を行う場合は、stretchに設定します(単一の子コンポーネントのみ拡大されます)。showDetailHeaderコンポーネントの親コンポーネントでジオメトリ管理を決定する場合は、デフォルトに設定したままにします。ジオメトリ管理の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

9. ヘッダーにボタンまたはアイコンを追加するには、「コンポーネント」ウィンドウの「レイアウト」パネルから「メニューおよびツールバー・コンテナ」グループのtoolbarコンポーネントをtoolbarファセットにドラッグ・アンド・ドロップします。新しく挿入されたtoolbarコンポーネントに任意数のボタン・コンポーネントを追加します。toolbarコンポーネントの使用方法の詳細は、16.3項「ツールバーの使用方法」を参照してください。

注意:

panelHeaderコンポーネントでは、ツールバーのオーバーフローはサポートされていません。

10. ヘッダーにメニューを追加するには、menuBarファセットにmenuコンポーネントを挿入します。メニュー作成の詳細は、16.2項「メニュー・バーでのメニューの使用方法」を参照してください。

ヒント:

toolbarファセットにメニューを配置することも、menuファセットにツールバー(およびツールボックス)を配置することも可能です。これらのファセットの主な違いは場所です。toolbarファセットはmenuファセットの前に配置されます。

11. サブセクション・ヘッダーを作成するには、既存のshowDetailHeaderコンポーネントに別のshowDetailHeaderコンポーネントを挿入します。

12. コンポーネントの見出しレベルをオーバーライドするには、headerLevelを目的のレベル(H1、H2などからH6)に設定します。
見出しレベルは、特にスクリーン・リーダー・アプリケーションで使用する場合に、正しいページ構造を決定するのに使用されます。デフォルトで、headerLevelは-1に設定されており、ページの物理的位置に基づいて、ヘッダーでサイズを決定できます。つまり、最初のヘッダー・コンポーネントはH1に設定されます。そのH1コンポーネントにネストされるヘッダー・コンポーネントはH2などに設定されます。

注意:

スクリーン・リーダー・アプリケーションでは、HTMLヘッダー・レベルの割当てを利用して、ページの基本構造を識別します。ヘッダー・コンポーネントおよびヘッダー・レベルの割当てがページで意味をなすようにしてください。

オーバーライド値を使用する場合は、ページの公開可能なセクション内にヘッダーを含めた場合の影響について考慮してください。たとえば、ページに縮小可能な領域がある場合は、領域が縮小および表示されるときに、オーバーライドされた構造が意味を持つようにする必要があります。

13. 見出し階層の構造ではなく、ヘッダー・テキストのサイズのみを変更する場合は、size属性を設定します。
size属性では、ヘッダー・テキストに使用する数値を指定し、スキンをオーバーライドします。最大の数字は0で、これはH1ヘッダー・レベルに対応します。最小は5で、H6ヘッダーに対応します。

デフォルトで、size属性は-1です。これは、ADF Facesにより、使用するヘッダー・レベルのスタイルが最上位の親コンポーネントから自動的に計算されることを意味します。ネストされているコンポーネントを使用する場合は、size属性を明示的に設定して、表示する適切なヘッダー・スタイルを取得する必要はありません。

注意:

テキストのスタイルはsize属性を使用して強制できますが(最大のテキストが0の場合)、size属性の値は階層には影響しません。影響を受けるのはテキストのスタイルのみです。

スキンを使用して別のヘッダーの外観を変更することもできます。詳細は、9.9.6項「スキニングとshowDetailHeaderコンポーネントに関する必知事項」を参照してください。

14. セクションまたはサブセクションにコンテンツを追加するには、必要な子コンポーネントをshowDetailHeaderコンポーネントに挿入します。

9.9.3 panelBoxコンポーネントの使用方法

ページには、任意の数のpanelBoxコンポーネントを挿入できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelBoxコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・ボックス」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、「外観」セクションを開き、ランプで使用するランプを選択します。
coreランプでは様々な青が使用され、highlightランプでは様々な黄色が使用されます。使用する色は、カスタム・スキンを作成することで変更できます。詳細は、第9.9.7項「スキニングとpanelBoxコンポーネントに関する必知事項」を参照してください。

3. Backgroundをlight、medium、darkまたはdefaultのいずれかの値に設定します。デフォルトの背景色は透明です。

4. Textを、コンテナのヘッダー部分のタイトルとして表示するテキスト文字列に設定します。

5. Iconを、ヘッダー・テキストの前に表示するアイコン・イメージのURIに設定します。

注意:

textおよびicon属性の両方が設定されていない場合、panelBoxコンポーネントのヘッダー部分は表示されません。

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

6. TitleHalignをcenter、start、end、leftまたはrightのいずれかの値に設定します。この値により、コンテナのヘッダー部分のタイトルの横位置(アイコン・イメージを含む)が決定されます。

7. 「動作」セクションを開き、ユーザーがコンポーネントのコンテンツを表示または非表示にする際に実行する必要のあるバッキングBeanで、DisclosureListenerをdisclosureListenerメソッドに設定します。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

8. 表示イベントをクライアントで処理する場合は、HandleDisclosureをclientに設定します。イベントは別のイベントが送信されるまで、またはコンポーネントがデータの変更を検出して更新が必要になるまでサーバーに送信されません。
表示イベントおよびリスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

注意:

disclosureListenerを、表示イベントを処理するリスナー・メソッドにバインドした場合、handleDisclosure値は無視され、イベントはサーバーで処理されます。

パフォーマンスのヒント:

コンポーネントでデータ変更を処理しない場合は、handleDisclosure属性をclientに設定する必要があります。

9. ツールバー・ボタンを追加するには、「コンポーネント」ウィンドウの「レイアウト」パネルから「メニューおよびツールバー・コンテナ」グループの「ツールバー」をtoolbarファセットにドラッグ・アンド・ドロップします。次に必要な数のボタン・コンポーネントをtoolbarコンポーネントに挿入します。toolbarおよびボタン・コンポーネントの使用法は、16.3項「ツールバーの使用方法」を参照してください。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelBoxコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ボックス」→「ツールバー」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

10. 表示するコンテナにコンテンツを追加するには、必要なコンポーネントをpanelBoxコンポーネントの子コンポーネントとして挿入します。
通常、panelBoxコンポーネントに子コンポーネントを1つ挿入し、その子コンポーネントに表示するコンテンツを挿入します。この子コンポーネントでコンテンツの表示方法を制御できますが、親のpanelBoxコンポーネントは制御できません。

11. panelBoxコンポーネントの幅を変更するには、inlineStyle属性を希望する正確なピクセル・サイズに設定します。または、inlineStyle属性を、panelBoxコンポーネントが含まれる外側の要素の割合に設定します。例9-10に、幅を変更するために使用するコードを示します。

例9-10 inlineStyle属性が設定されたpanelBoxコンポーネント

<af:panelBox inlineStyle="width:50%;" ...>
<!-- child contents here -->
</af:panelBox>

9.9.4 表示イベントに関する必知事項

disclosed属性では、ヘッダーの下のコンテンツを表示(開いた状態)または非表示(閉じた状態)のどちらにするかを指定します。デフォルトではdisclosed属性はtrueで、コンテンツが表示されます。この属性がfalseに設定されていると、コンテンツは非表示になります。コンテンツが開いた状態と閉じた状態を相互に切り替えるためにコードを記述する必要はありません。切替えは、ADF Facesにより自動的に処理されます。

ユーザーが切替えアイコンをクリックしてコンテンツを表示または非表示にすると、デフォルトで、コンポーネントからサーバーにorg.apache.myfaces.trinidad.event.DisclosureEventイベントが送信されます。DisclosureEventイベントには、ソース・コンポーネントおよびその状態、つまり表示(開いている)または非表示(閉じている)に関する情報が含まれています。isExpanded()メソッドは、ノードを開く(表示)か閉じる(非表示)かを決定するboolean値を返します。コンポーネントにそのコンテンツの表示および非表示のみを行わせる場合は、コードを記述する必要はありません。

ただし、DisclosureEventイベントの特別な処理を実行する場合は、コンポーネントのdisclosureListener属性をバッキングBeanのdisclosureListenerメソッドにバインドできます。ユーザーが表示されているまたは非表示のアイコンをクリックするたびに、DisclosureEventイベントへのレスポンスとしてdisclosureListenerメソッドが起動されます。

例9-11に示されているように、disclosureListenerメソッドは、単一のdisclosureEventイベント・オブジェクトを持つpublicメソッドで、戻りタイプがvoidである必要があります。

例9-11 disclosureListenerメソッド

public void some_disclosureListener(DisclosureEvent disclosureEvent) {
// Add event handling code here
}

コンポーネントのimmediate属性がtrueに設定されている場合以外、DisclosureEventイベントはデフォルトでは、アプリケーションの起動フェーズに送信されます。immediate属性がtrueに設定されている場合、イベントは可能なかぎり早期のフェーズ(通常はリクエスト値の適用フェーズ)で送信されます。

リスナー・メソッドを使用して表示イベントに応答する必要がない場合は、handleDisclosure属性をclientに設定することを検討します。この設定により、表示イベントがクライアントで処理されます。イベントは別のイベントが送信されるまで、またはコンポーネントがデータの変更を検出して更新が必要になるまでサーバーに送信されません。disclosureListener属性がリスナー・メソッドにバインドされている場合は、handleDisclosure属性がclientに設定されていても、イベントはサーバーにも自動的に送信されます。

disclosureListenerメソッドを使用し、クライアント上のイベントにも応答する場合は、AdfDisclosureEventクライアント側イベントを使用できます。クライアントのAdfDisclosureEventイベントのイベント・ルートは、イベントのソース・コンポーネントに設定されており、disclosed属性がtrueのパネルに対するイベントのみがサーバーに送信されます。クライアント側のイベントおよびイベント・ルートの詳細は、第6章「イベントの処理」を参照してください。

disclosed属性の値は実行時に永続可能であるため、ユーザーがコンテンツを表示または非表示にした場合、ADF Facesでは属性値を変更して保持できるので、その値はユーザーのセッション中その状態のままになります。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

注意:

showDetail、showDetailHeader、panelBoxコンポーネントなどのように、組込みのイベント機能のあるADF Facesコンポーネントは、formコンポーネントで囲む必要があります。

9.9.5 スキニングとshowDetailコンポーネントに関する必知事項

ADF Facesによって使用されるデフォルトのスキンでは、showDetailコンポーネントの子コンポーネントがインデントされます。child-containerスキニング・キーを使用してインデントを制御できます。次に例を示します。

例9-12 スキニング・キーを使用したshowDetailのインデントの変更

af|showDetail {  -tr-layout: flush;}
af|showDetail::child-container {
padding-left: 10px;
}

詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.9.6 スキニングとshowDetailHeaderコンポーネントに関する必知事項

また、デフォルトでは、showDetailHeaderコンポーネントのヘッダー・サイズに使用されるスタイルはスキンによって制御されます。2以上のヘッダー・サイズは、サイズ2として表示されます。つまり、サイズ3、4または5のスタイルには違いがなく、すべてサイズ2と同じスタイルで表示されます。これは、カスタム・スキンを作成することで変更できます。

詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.9.7 スキニングとpanelBoxコンポーネントに関する必知事項

panelBoxコンポーネントのcoreランプでは様々な青が使用され、highlightランプでは様々な黄色が使用されます。カスタム・スキンを作成し、様々なpanelBoxスキン・スタイル・セレクタを構成することにより、カラーを変更できます。

これらのスタイル・セレクタはすべて、2つの擬似クラスによって増強されます。1つ目の擬似クラスはrampであり、:coreまたは:highlightの値を持つことができます。2つ目の擬似クラスはbackgroundであり、:default、:light、:mediumまたは:darkの値を持つことができます。たとえば、ヘッダー開始セルの背景色をピンク色にする場合、panelBoxのramp属性がcoreでbackground属性がdefaultのときは、以下のようにします。

af|panelBox::header-start:core:default {background-color:pink; border: none;}

ヘッダーおよびコンテンツの変更に別名を使用することもできます。たとえば、.AFPanelBoxHeaderCoreMedium:aliasはaf|panelBox::header-start:core:medium、af|panelBox::header-center:core:medium、およびaf|panelBox::header-end:core:mediumに含まれます。このため、core mediumのpanelBoxのヘッダーの背景色を変更する場合は、これら3つのセレクタのかわりに..AFPanelBoxHeaderCoreMedium:aliasも使用できます。

詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.10 パネルにおけるコンテンツの表示または非表示

非表示および表示できるコンテンツの複数の領域を表示する必要がある場合は、panelAccordion、panelTabbed、panelDrawer、またはpanelSpringboardコンポーネントを使用できます。これらのコンポーネントでも、showDetailItemコンポーネントを使用して実際のコンテンツを表示します。

panelAccordionコンポーネントを使用すると、開くことのできる一連のペインを作成できます。ユーザーが一度に複数のパネルを開くことや、一度に1つのパネルのみを開くことができるように設定可能です。複数のパネルを開いている場合は、showDetailItemコンポーネントのヘッダーをドラッグして、パネルの高さを調整できます。

パネルが縮小されている場合は、パネル・ヘッダーのみ表示されます。パネルが展開されている場合は、パネル・コンテンツがパネル・ヘッダーの下に表示されます(ユーザーは、panelAccordionコンポーネントのヘッダーまたは展開アイコンをクリックしてペインを展開できます)。図9-44に示されているように、File ExplorerアプリケーションではpanelAccordionコンポーネントを使用して、「フォルダ」および「検索」ペインを表示しています。

図9-44 panelAccordionペイン

実行時、使用可能なブラウザの領域が、開かれたパネルのコンテンツの表示に必要な領域より少ない場合、表示されていないパネルをユーザーが選択して移動できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。図9-45は、「検索」パネルを表示する十分な領域がないときにFile Explorerアプリケーションの「フォルダ」パネルの右下に表示されるオーバーフロー・アイコンを示します。

図9-45 panelAccordionのオーバーフロー・アイコン

ユーザーがオーバーフロー・アイコンをクリックすると、ユーザーが選択してナビゲートするためのオーバーフロー・ポップアップ・メニューが表示されます(図9-46を参照)。

図9-46 panelAccordionのオーバーフロー・ポップアップ・メニュー

図9-47に示すように、ペインをドラッグ・アンド・ドロップで再配置できるようにpanelAccordionを構成することもできます。

図9-47 ドラッグ・アンド・ドロップで並替えできるペイン

順序が変更されると、showDetailItemコンポーネントのdisplayIndex属性も変更されて新しい順序を反映します。

注意:

オーバーフローしている項目は並替えできません。

panelAccordionコンポーネントの使用方法は、9.10.1項「panelAccordionコンポーネントの使用方法」を参照してください。

panelTabbedコンポーネントを使用すると、タブ付きの一連のペインを作成できます。panelAccordionペインとは異なり、panelTabbedペインは閉じることも開くこともできません。かわりに、ユーザーがタブを選択すると、選択したタブのコンテンツが表示されます。タブは表示領域の上か下(またはその両方)、または左か右に表示されます。

デフォルトでは、タブの幅はラベルとして表示されるテキストによって決まります。タブの幅に最小または最大値を設定することもできます。テキストが収まらない場合は、テキストが切り詰められたことを示す省略記号が表示されるように設定できます。

個々のタブを削除する(閉じる)ようにpanelTabbedコンポーネントを構成できます。このコンポーネントは、すべてのタブを削除する、最後のタブを除いてすべて削除する、またはタブを削除しないように構成できます。

各タブのコンテンツを含むshowDetailItemがいつ作成されるかを構成できます。タブが少数の場合は、現在表示されているタブに関係なく、panelTabbedコンポーネントが初めて作成されるときにすべてのshowDetailItemコンポーネントを作成できます。ただし、panelTabbedコンポーネントに多数のshowDetailItemコンポーネントが含まれる場合は、ページのレンダリングが低速になることがあります。パフォーマンスを向上させるには、かわりに対応するタブが選択されたときにのみshowDetailItemコンポーネントを作成するようpanelTabbedコンポーネントを構成できます。さらに、アクセスされるたびに再作成する必要がないように、ユーザーが別のタブを選択した後でshowDetailItemを破棄するか、コンポーネント・ツリーで選択されているshowDetailItemコンポーネントを保持するように、配信メソッドを構成できます。

File ExplorerアプリケーションではpanelTabbedコンポーネントを使用して、図9-48に示されているように、メインのパネルにコンテンツを表示しています。

図9-48 panelTabbedペイン

ヒント:

タブとナビゲーション階層を組み合せて使用する場合、たとえば、各タブが他のナビゲーション・アイテムのセットを含む別ページまたはリージョンである場合、ナビゲーション・パネル・コンポーネントを使用してナビゲーション・メニューを作成できます。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

すべてのタブを表示できない場合、panelTabbedコンポーネントでもオーバーフローがサポートされます。オーバーフローの処理方法は、-tr-layout-typeスキニング・キーがどのように構成されているかによって決まります。詳細は、第9.10.9項「スキニングとpanelTabbedコンポーネントに関する必知事項」を参照してください。

注意:

オーバーフローは、位置属性がabove、below、またはbothに設定されているときにのみサポートされます。

パフォーマンスのヒント:

panelTabbedコンポーネント内の子コンポーネントの数、および子コンポーネントの複雑さが、オーバーフローのパフォーマンスに影響します。できる限りオーバーフローを避けるようにパネル・コンポーネントのサイズを設定してください。

panelTabbedコンポーネントの使用方法は、9.10.2項「panelTabbedコンポーネントの使用方法」を参照してください。

panelDrawerコンポーネントは、コンテナ・コンポーネントの横に付けてタブをレンダリングします。デフォルトでは、ドロワーはpanelDrawerの親に合わせて配置しますが、別の近い祖先を選択できます。関連するコンポーネントの始めまたは終わりに合わせて配置できます。ユーザーがタブをクリックすると、ドロワーが開き、子のshowDetailItemのコンテンツが表示されます。図9-49にドロワーが閉じたpanelDrawerを示します。

図9-49 ドロワーが閉じたpanelDrawerコンポーネント

図9-50に示すように、ユーザーがタブをクリックすると対応するドロワーが開きます。

図9-50 最後のドロワーが開いたpanelDrawerコンポーネント

ドロワーが開く幅は、width属性の設定によります。width属性に値がない場合は、開くドロワーのサイズは、showDetailItemコンポーネントの子に含まれるコンテンツにより決定されます。そうでなければ、width属性は、panelDrawerが位置揃えの基準とするコンポーネントのパーセンテージに設定できます。

panelSpringboardコンポーネントは、そのコンテンツを一連のアイコンとしてグリッドかストライプのいずれかに表示します。アイコンをクリックすると、クリックされたアイコンと関連する子のshowDetailItemコンポーネントはそのコンテンツをストライプの下に表示します。

たとえば、図9-51は関連するアイコンをグリッドに表示するように構成された10個の子のshowDetailItemコンポーネントを含むpanelSpringboardコンポーネントを示します。

図9-51 グリッド・モードのpanelSpringboardコンポーネント

図9-52は、Teamアイコンをクリックした後の同じpanelSpringboardコンポーネントを示します。panelSpringboardアイコンは、ストライプの中の一番上に移動し、選択されたアイコンと関連するコンテンツが表示されます。

図9-52 ストライプ・モードのpanelSpringboardコンポーネント

panelSpringboardコンポーネントと同様に、panelAccordion、panelTabbed、およびpanelDrawerコンポーネントは、showDetailItemコンポーネントを1つ使用して各パネルにコンテンツを配置します。たとえば、4つのペインを使用する場合、panelAccordion、panelTabbedまたはpanelDrawerコンポーネントのそれぞれにshowDetailItemコンポーネントを4つ挿入します。showDetailItemコンポーネントを使用するには、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。ツールバーをshowDetailItemコンポーネントのtoolbarファセットに追加でき、ツールバーはshowDetailItemが表示されると表示されます。図9-48に、File ExplorerアプリケーションのshowDetailItemコンポーネントで使用されているツールバーを示します。

showDetailItem子コンポーネントは、そのアイテムに関する情報を示すためにバッジを表示することもできます。たとえば、図9-51のpanelSpringboardでは、バッジはホームshowDetailItemの多数のアイテムを表示するために使用されます。

panelAccordionおよびpanelTabbedコンポーネントを拡大するように構成することも、現在表示されているshowDetailItemの子からディメンションを取得するように構成することもできます。親コンポーネントが子の拡大を許可する場合に、panelSpringboardコンポーネントが拡大されます。親が子を拡大しない場合、panelSpringboardコンポーネントのサイズはその子であるshowDetailItemコンポーネントのコンテンツに基づきます。panelDrawerコンポーネントは、特定の幅が設定されない限り含有するコンポーネントのサイズで開かれます。

パネル・コンポーネントを拡大するように構成する場合、showDetailItemコンポーネントが単一の子を拡大するように構成できます。ただし、それには、その子がshowDetailItemコンポーネントの唯一の子である必要があります。

9.10.1 panelAccordionコンポーネントの使用方法

1つのページで、通常はページの異なる領域にあるかネストされている複数のpanelAccordionコンポーネントを使用できます。panelAccordionコンポーネントを追加した後に、一連のshowDetailItemコンポーネントを挿入して、1つのパネルに1つのshowDetailItemを使用してペインを配置します。次に、各showDetailItemにコンポーネントを挿入してパネル・コンテンツを配置します。showDetailItemの使用手順は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelAccordionコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・アコーディオン」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。

3. ユーザーが同時に複数のパネルのコンテンツを開いて参照できるようにする場合は、DiscloseManyをtrueに設定します。
デフォルト値はfalseです。これは、一度に開くことのできるパネルが1つのみであることを意味します。たとえば、最初にページがロードされた際に、開いているパネルAと閉じているパネルBが1つずつあるとします。一度に開くことのできるパネルは1つのみであるため、ユーザーがパネルBを開くとパネルAが閉じます。

4. ユーザーがすべてのペインを閉じることができるようにする場合は、DiscloseNoneをtrueに設定します。
デフォルト値はfalseです。これは、必ず1つのパネルが開かれたままになることを意味します。

5. ユーザーがドラッグ・アンド・ドロップによってペインを再配置できるようにする場合は、「動作」セクションを開き、Reorderをenabledに設定します。デフォルトはdisabledです。

注意:

panelAccordionにshowDetailItemコンポーネント以外のコンポーネントがある場合(手順8のヒントを参照)、それらのコンポーネントはクライアントでのみ並べ替えることができます。したがって、新しい順序は保持されません。

6. デフォルトでは、panelAccordionコンポーネントは使用可能なブラウザ領域に合せて拡大されます。かわりに、panelAccordionコンポーネントを、子を拡大しないコンポーネントの子として使用する場合は、panelAccordionコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

DimensionsFromを次のいずれかの値に設定します。

- children: panelAccordionコンポーネントは、現在表示されているshowDetailItemコンポーネントからそのディメンションを取得します。

注意:

この設定を使用する場合は、panelAccordionコンポーネントの高さを(たとえばinlineStyleまたはstyleClass属性を通じて)設定できません。設定すると、panelAccordionの高さと子コンポーネントの高さが競合する原因となります。

同様に、showDetailItemコンポーネントのstretchChildren、flexおよびinflexibleHeight属性を設定すると、サイズを決定するためにpanelAccordionへの循環参照が発生するため、これらの属性は設定できません。

- parent: panelAccordionコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: panelAccordionコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelAccordionコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelAccordionコンポーネントはその子コンポーネントのサイズに基づきます。

注意:

panelAccordionを拡大し、showDetailItemのコンテンツも拡大する場合は、特定の方法でshowDetailItemを構成する必要があります。詳細は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

7. デフォルトでは、panelTabbedコンポーネントが作成されると、すべてのshowDetailItem子コンポーネントが作成されます。子が多数の場合は、パフォーマンスを向上するために、タブが選択された場合にのみshowDetailItem子コンポーネントを作成するか、タブが最初に選択された場合にのみshowDetailItem子コンポーネントを作成し、その時点以降、作成されたままになるように、panelTabbedを構成できます。
childCreation属性を使用して、子コンポーネントをいつ作成するかを構成します。それには、Behaviorセクションを拡大して、ChildCreationを以下の1つに設定します。

- immediate: panelTabbedコンポーネントが作成されるとすべてのshowDetailItemコンポーネントが作成されます。

- lazy: 関連付けられたタブが選択されたときにのみshowDetailItemコンポーネントが作成されます。タブが選択されると、showDetailItemコンポーネントはコンポーネント・ツリーに作成されたままになります。

- lazyUncached: 関連付けられたタブが選択されたときにのみshowDetailItemコンポーネントが作成されます。別のタブが選択されると、showDetailItemコンポーネントは破棄されます。

8. デフォルトで、panelAccordionコンポーネントの子コンポーネントとしてshowDetailItemコンポーネントを使用すると、パネルが1つ追加されます。さらにペインを追加するには、panelAccordionコンポーネントにshowDetailItemコンポーネントを挿入します。必要な数だけペインを追加できます。

ヒント:

通常はアコーディオン・パネルの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、アコーディオン・パネルにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

パネルに表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。手順は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

9.10.2 panelTabbedコンポーネントの使用方法

panelTabbedコンポーネントを使用してタブ付きのペインを作成する方法は、panelAccordionコンポーネントを使用したアコーディオン・ペインの作成方法に似ています。panelTabbedコンポーネントを追加した後で、一連のshowDetailItemコンポーネントを挿入して、表示するタブ付きのパネル・コンテンツを配置します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelTabbedコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「タブ付きパネル」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。

3. 「位置」を設定して、タブの表示位置を決めます。次のいずれかに設定できます。

- above: タブがコンテンツの上に表示されます。これがデフォルトです。

- below: タブがコンテンツの下に表示されます。

- start: クライアント・ブラウザの読み方向が左から右(LTR)の場合、タブは左側に表示されます。読み方向が右から左(RTL)の場合、タブは右側にレンダリングされます。

- end: タブは、LTRロケールでは右側に表示され、RTLロケールでは左側に表示されます。

- left: タブは常に左側に表示されます。

- right: タブは常に右側に表示されます。

ヒント:

position属性をstartまたはendに設定すると、ロケールの読み方向に基づき位置を変更できます。たとえば、positionをendに設定すると、タブはUSロケールでは右側に表示され、Arabicロケールでは左側に表示されます。positionをleftまたはrightに設定すると、タブはロケールとは関係なく指定された側に表示されます。

4. ユーザーがタブを閉じられる(削除できる)ようにするには、tabRemovalを設定します。この属性を設定して、すべてのタブの削除、または最後のタブを除くすべてのタブの削除を許可できます。実際に削除するにはハンドラを実装し、関連するshowDetailItemコンポーネントのリスナーを構成する必要があります。各showDetailItemコンポーネントでこれをオーバーライドして、各タブを削除できなくするか(閉じるアイコンは表示されません)、閉じるアイコンを無効にできます。
タブが削除されるように構成すると、閉じるアイコンがタブの終わりに表示されます(タブのクリックまたはタブの移動のいずれでも)。

詳細は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

注意:

タブの削除は、位置属性がabove、below、またはbothに設定されているときにのみサポートされます。

5. デフォルトでは、タブのサイズはラベルとして使用されるテキストによって決まります。そのかわりに、タブを一定のサイズに設定して、表示できないテキストを省略記号で表すことができます。それには、次のように設定します。

- maxTabSize: サイズをピクセル単位で設定します。タブのサイズがこれよりも大きくなることはありません。使用可能なタブ領域を埋めるには、infinityに設定します。これがデフォルトです。

- minTabSize: サイズをピクセル単位で設定します。タブのサイズがこれよりも小さくなることはありません。

- truncationStyle: maxTabSizeに基づき、表示しきれないテキストを切り捨てたときに省略記号を表示するには、ellipsisを設定します。「なし」に設定すると、タブに収まらないテキストは単に切り詰められます。maxTabSizeを設定しないと、タブが常にテキストと同じ大きさで表示されます。

注意:

切捨てと拡張は、truncationStyleをellipsisに設定したときにのみサポートされます。noneに設定すると、maxTabSizeおよびminTabSizeは無視され、タブのサイズはテキストの長さに基づきます。

6. デフォルトでは、panelTabbedコンポーネントは使用可能なブラウザ領域に合せて拡大されます。かわりに、panelTabbedコンポーネントを、子を拡大しないコンポーネントの子として使用する場合は、panelTabbedコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

DimensionsFromを次のいずれかの値に設定します。

- disclosedChild: panelTabbedコンポーネントは、現在表示されているshowDetailItemコンポーネントからそのディメンションを取得します。

注意:

この設定を使用する場合は、panelTabbedコンポーネントの高さを(たとえばinlineStyleまたはstyleClass属性を通じて)設定できません。設定すると、panelTabbedの高さと子コンポーネントの高さが競合する原因となります。

- parent: panelTabbedコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: panelTabbedコンポーネントの親コンポーネントがその子の拡大を許可する場合、panelTabbedコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、panelTabbedコンポーネントはその子コンポーネントのサイズに基づきます。

7. デフォルトで、panelTabbedコンポーネントの子としてshowDetailItemコンポーネントを使用すると、タブ付きパネルが1つ作成されます。さらにペインを追加するには、panelTabbedコンポーネントにshowDetailItemコンポーネントを挿入します。必要な数だけタブ付きのペインを追加できます。

ヒント:

通常はpanelTabbedコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelTabbedコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

パネルに表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。showDetailItemの使用方法は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

9.10.3 panelDrawerコンポーネントの使用方法

panelDrawerコンポーネントを使用してタブ付きのペインを作成する方法は、panelTabbedコンポーネントを使用したアコーディオン・ペインの作成方法に似ています。panelDrawerコンポーネントを追加した後に、一連のshowDetailItemコンポーネントを挿入して、表示するドロワー・コンテンツを配置します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelDrawerコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、パネル・ドロワーをJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。

3. panelDrawerの位置合せの基準となるコンポーネントにAlignIdを設定します。プロパティ・フィールドの上にマウスを置くと現れるアイコンをクリックして、「編集」を選択すると「プロパティの編集: AlignId」ダイアログが表示されます。そこでコンポーネントを選択します。alignId属性を設定しない場合、panelDrawerはその親に位置合せします。

4. 「位置」を設定して、ドロワーのタブの表示位置を決めます。位置合せしたコンポーネントの終わり(LTRロケールでは右)にタブを表示するには、それをend(デフォルト)に設定します。それをstart、leftまたはrightに設定することもできます。

ヒント:

position属性をstartまたはendに設定すると、ロケールの読み方向に基づき位置を変更できます。たとえば、positionをendに設定すると、タブはUSロケールでは右側に表示され、Arabicロケールでは左側に表示されます。positionをleftまたはrightに設定すると、タブはロケールとは関係なく指定された側に表示されます。

5. ドロワーの「width」と「height」を設定します。デフォルトでは、panelDrawerコンポーネントは、showDetailItemコンポーネントのコンテンツのサイズ.に合わせて拡大されます。同様に、以下がtrueの場合にshowDetailItemは拡大を許可します。

- panelDrawerにはwidth属性とheight属性が定義されています。

- showDetailItemには単一の子が含まれます。

- showDetailItemの子のコンポーネントでは、幅、高さ、マージン、境界線、パディングに値が指定されていません。

- 子は拡大可能である必要があります。

注意:

ドロワーが開かれてからコンテンツのサイズが変更される(たとえば、ドロワー内部のshowDetailをトグルすると、新しいコンテンツが表示される)場合、widthおよびheight属性を想定できる最大サイズに設定します。そうしないと、サイズが変更されたコンテンツが正しく表示されないことがあります。

6. 必要に応じてMaximumHeightおよびMaximumWidthを設定します。デフォルトでは100%に設定されています。

7. 「外観」セクションを開き、「ShowHandles」を設定します。デフォルトでは、この値はalwaysに設定され、ハンドルは常に表示されます。それをwhenOpenに設定することもできます。これによりハンドルはドロワーが開いたときにのみ表示されます。対応するshowDetailItemの公開属性をtrueに設定することにより、プログラムからドロワーを開く必要があります。たとえば、ハンドルのかわりにボタンを使用してドロワーを開くことがあります。ボタンと関連するアクションはshowDetailItemのdisclosed属性をtrueに設定します。

8. panelDrawerコンポーネントの内部にshowDetailItemコンポーネントを挿入することによりドロワーを追加します。必要な数だけドロワーを追加できます。

注意:

panelDrawerはコンテンツのオーバーフローをサポートしません。このため、panelDrawerの位置合せの基準となるコンポーネントには、すべてのタブとそのコンテンツを納められるだけの高さが必要です。

ヒント:

通常はpanelDrawerコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelDrawerコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

ドロワーに表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。showDetailItemの使用方法は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

9.10.4 panelSpringboardコンポーネントの使用方法

panelSpringboardは、他のパネル・コンポーネントと同様に一連のshowDetailItemコンポーネントを含みます。各showDetailItemは、アイコンによって表されます。各showDetailItemにコンポーネントを挿入して、パネル・コンテンツを配置します。showDetailItemの使用手順は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelSpringboardコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、Panel SpringboardをJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、「外観」セクションを開き、DisplayModeを設定してpanelSpringboardが最初にレンダリングされるときの表示方法を指定します。図9-51に示すように、アイコンだけを表示するには、それをgridに設定します。図9-52に示すように、アイコンをストライプの上部に沿って表示し、選択されたアイコンのコンテンツをストライプの下に表示するには、それをstripに設定します。

ヒント:

2つのモードを切替えられるようにするには、Javascriptをページに追加する必要があります。詳細は、9.10.5項「グリッド・モードとストライプ・モードの切替えに関する必知事項」を参照してください。

3. 表示モードが変わるときにロジックを実行するには、「拡張」セクションを開き、そのロジックを処理するbean上のメソッドにSpringboardChangeListenerを設定します。

4. 実行時にデフォルトでは、panelSpringboardコンポーネントが作成されると、すべてのshowDetailItem子コンポーネントが作成されます。子が多数の場合は、パフォーマンスを向上するために、タブが選択された場合にのみshowDetailItem子コンポーネントを作成するか、タブが最初に選択された場合にのみshowDetailItem子コンポーネントを作成し、その時点以降、作成されたままになるように、panelSpringboardを構成できます。
childCreation属性を使用して、子コンポーネントをいつ作成するかを構成します。それには、Behaviorセクションを拡大して、ChildCreationを以下の1つに設定します。

- immediate: panelSpringboardコンポーネントが作成されるとすべてのshowDetailItemコンポーネントが作成されます。

- lazy: 関連付けられたアイコンが選択されたときにのみshowDetailItemコンポーネントが作成されます。一度アイコンが選択され、関連するshowDetailItemがレンダリングされると、showDetailItemコンポーネントはツリー内で作成された状態を保ちます。

- lazyUncached: 関連付けられたアイコンが選択されたときにのみshowDetailItemコンポーネントが作成されます。別のアイコンが選択されると、showDetailItemコンポーネントは破棄されます。

5. showDetailItemコンポーネントをpanelSpringboardコンポーネントの中に挿入します。必要な数だけ追加できます。それらを子として追加する順序が、それらがspringboardに表示される順序になります。

ヒント:

通常はpanelSpringboardコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelSpringboardにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。手順は、9.10.6項「コンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

9.10.5 「グリッド・モードとストライプ・モードの切替えに関する必知事項」

デフォルトでは、panelSpringboardは最初グリッド・モードでレンダリングします。ユーザーがアイコンをクリックすると、panelSpringboardはSpringboardChangeListenerイベントを発生させ、ストライプ・モードに変わります。2つのモードを切替えられるようにするには、そのイベントをリッスンし、ソース(Springboard)を特定し、displayMode属性を希望のモードに設定する必要があります。

たとえば、表示モードをグリッドに設定するには、例9-13に示すJavaScriptを使用します。

例9-13 表示モードをグリッドに変更するJavascriptコード

<af:resource type="javascript">
function backToGrid(actionEvent)
{
actionEvent.cancel();
var eventSource = actionEvent.getSource();
var object_navigator = eventSource.findComponent("panelSpringboardId");
object_navigator.setProperty(AdfRichPanelSpringboard.DISPLAY_MODE, "grid",
true);
}

例9-14に示すようにリンクからコードをコールします。

例9-14 Javascriptをコールするページ・コード

<af:link id="logo" text="Back to Grid">
<af:clientListener type="click" method="backToGrid"/>
</af:link>

Javascriptをページ上で使用する方法は、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

9.10.6 コンテンツを表示するためのshowDetailItemコンポーネントの使用方法

showDetailItemコンポーネントをpanelAccordion、panelTabbed、panelDrawer、またはpanelSpringboardコンポーネントのみに挿入します。各showDetailItemコンポーネントは、1つのパネルに対応します。一般的に、親コンポーネントに2つ以上のshowDetailItemコンポーネントを挿入します。表示する子コンポーネントをshowDetailItemコンポーネントに挿入します。

showDetailItemコンポーネントのdisclosed属性は、対応するパネルのコンテンツを表示(開いた状態)または非表示(閉じた状態)のどちらにするかを指定します。デフォルトではdisclosed属性はfalseで、コンテンツは非表示(閉じた状態)になります。この属性がtrueに設定されていると、コンテンツは表示(開いた状態)されます。コンテンツが開いた状態と閉じた状態を相互に切り替えるためにコードを記述する必要はありません。切替えは、ADF Facesにより自動的に処理されます。

次の手順では、9.10.1項「panelAccordionコンポーネントの使用方法」、9.10.2項「panelTabbedコンポーネントの使用方法」、9.10.3項「panelDrawerコンポーネントの使用方法」および9.10.4項「panelSpringboardコンポーネントの使用方法」の説明に従って、JSFページにpanelAccordion、panelTabbed、 panelDrawerまたはpanelSpringboardコンポーネントをそれぞれ追加済であると仮定しています。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.10項「パネルにおけるコンテンツの表示または非表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

showDetailItemコンポーネントを使用してパネル・コンテンツを追加する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから「詳細アイテムの表示」コンポーネントをドラッグ・アンド・ドロップして、panelAccordionなどの親コンポーネントの中に1つ以上のshowDetailItemコンポーネントを挿入します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。

3. Textを、このパネル、タブまたはアイコンに表示するラベルに設定します。

4. アイコンを追加するには、Iconを、使用するイメージ・ファイルのURIに設定します。HoverIcon、DepressedIcon、DisabledIconを設定することもできます。

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

5. showDetailItemコンポーネントが、拡大されるように構成されたpanelAccordionコンポーネント内で使用されている場合は、showDetailItemとそのコンテンツを拡大するように構成できますが、showDetailItemコンポーネントには1つの子コンポーネントのみ含まれている必要があります。各showDetailItemコンポーネントのFlexおよびStretchChildrenを設定する必要があります。
各showDetailItemコンポーネントに次の属性を使用して、パネル・コンテンツの柔軟性を制御します。

- Flex: 1つのpanelAccordionコンポーネントのshowDetailItemコンポーネントにどのくらいの領域が配分されるかを決定する負でない整数を指定します。デフォルトではflex属性の値は0(ゼロ)で、各showDetailItemコンポーネントのパネル・コンテンツはフレキシブルではありません。パネルのフレキシブルなコンテンツを有効にするには、1または2など、flexに0より大きい数値を指定します。flex値が大きいと、コンテンツは、flex値の小さいコンポーネントより大きくなります。フレキシブルなコンテンツが2つの場合、その高さは割り当てられたflex値に正確に比例します。コンポーネントAではflexが2に設定されていて、コンポーネントBではflexが1に設定されている場合、コンポーネントAの高さはコンポーネントBの2倍です。

- InflexibleHeight: パネルで使用するピクセル数を指定します。デフォルトは100ピクセルです。パネルのflex値が0(ゼロ)の場合、ADF Facesによりそのパネルに100ピクセルが使用され、ゼロ以外のパネルに残りの領域が配分されます。指定されたinflexibleHeight値を考慮した場合に、パネルのコンテンツがpanelAccordionコンテナ内に収まらない際には、ADF Facesにより近くのコンテンツが自動的にオーバーフロー・メニューに移動されます(図9-46を参照)。また、パネルのflex値がゼロ以外の場合は、その値が、その他のパネルがオーバーフロー・メニューに移動する前に、パネルが縮小される最低の高さになります。

- StretchChildren: firstに設定されている場合、単一の子コンポーネントが拡大されます。ただし、拡大できる子コンポーネントであることが必要です。詳細は、9.10.7項「ジオメトリ管理およびshowDetailItemコンポーネントに関する必知事項」を参照してください。

たとえば、File Explorerアプリケーションでは、showDetailItemコンポーネントを使用してナビゲータ・パネルにコンテンツが表示されています。両方のナビゲータが開かれている場合「検索」ナビゲータにはより多くの領域が必要なため、flex属性は2に設定され、「フォルダ」ナビゲータのshowDetailItemコンポーネントにはデフォルトのflex値1が使用されています。この設定により、「検索」ナビゲータが開かれている場合は、「フォルダ」ナビゲータより大きくなります。

注意:

File Explorerアプリケーションでは、flex属性に直接値を設定するかわりに、値の決定に使用されるメソッドに解決されるEL式が使用されています。EL式を使用すると、メタデータを使用してモデル情報を指定することを後から決めた場合に、プログラムで値を変更できます。

ユーザーは、実行時にパネルの高さを変更して、flexおよびinflexibleHeight属性の値を変更できます。これらの値は、ユーザーのセッション中に変わらないように永続化できます。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

フレキシブルなアコーディオン・パネル・コンテンツに関する次の追加情報に注意してください。

- ADF Facesでフレキシブルなコンテンツを有効にするには、flex値が0より大きいペイン(showDetailItemコンポーネント)が2つ以上必要です。これは、ADF Facesでは、パネル・コンテンツにどのくらいの領域を割り当てるかの決定に、2つのコンポーネントのflexの割合が使用されているためです。実行時、フレキシブルなコンテンツの表示の結果を確認するには、2つ以上のペインが開かれている必要があります。

- showDetailItemコンポーネントの子コンポーネントが1つのみでflex値がゼロ以外の場合、かつstretchChildren属性がfirstに設定されている場合、ADF Facesにより、panelAccordionコンポーネントのdiscloseMany属性の値にかかわらずその子コンポーネントが拡大されます。

- すべてのshowDetailItemコンポーネントに0(ゼロ)のflex値があり、それらのパネル・コンテンツが表示されている場合、表示されるコンテンツが非フレキシブルに設定されていても、ADF Facesは最後に表示されたshowDetailItemコンポーネントのコンテンツを、コンポーネントのflex値が1であるかのように拡大しますが、それはshowDetailItemコンポーネントの子が1つのみであり、stretchChildren属性がfirstに設定されている場合だけです。最後に表示されたパネルに複数の子コンポーネントがあるか、stretchChildren属性がnoneに設定されている場合、コンテンツは拡大されません。

flex属性が設定されていても、ジオメトリ管理に関する制限事項があります。詳細は、9.10.7項「ジオメトリ管理およびshowDetailItemコンポーネントに関する必知事項」を参照してください。

6. 拡大するように構成されたpanelSpringboardコンポーネントの中でshowDetailItemコンポーネントが使用されている場合、showDetailItemを拡大するように構成し、次にそのコンテンツを拡大するように構成できます。ただし、showDetailItemコンポーネントは1つの子コンポーネントのみを含む必要があり、その子コンポーネントに幅、高さ、マージン、境界線、パディングは設定しません。
コンテンツを拡大するには、各showDetailItemコンポーネントでStretchChildrenをfirstに設定します。

ヒント:

showDetailItemの中に配置されるコンポーネントでは拡大はサポートされません。showDetailItemに複数のコンポーネントを子として配置する場合は拡大がサポートされないためstretchChildrenをnoneに設定する必要があります。

7. 「動作」セクションを開きます。DisclosureListenerを、ユーザーがこのパネル、タブまたはアイコンを選択した場合に実行するバッキングBeanのdisclosureListenerメソッドに設定します。
サーバーの表示イベントおよびイベント・リスナーの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

8. このパネル、タブまたはアイコンを無効(ユーザーがパネルまたはタブを選択できない状態)にする場合は、Disabledをtrueに設定します。

9. このパネル、タブまたはアイコンの子コンポーネントを表示する場合は、Disclosedをtrueに設定します。
disclosed属性は、デフォルトでfalseに設定されています。これは、このパネル、タブまたはアイコンのコンテンツが非表示になることを意味します。

注意:

disclosedとrendered属性の違いに注意してください。rendered属性の値がfalseの場合、ユーザーはそのアコーディオン・ヘッダー・バーまたはタブ・リンク、およびその対応するコンテンツを使用できません。ただし、disclosed属性がfalseに設定されている場合は、その項目のコンテンツが現在は非表示でも、アコーディオン・ヘッダー・バーまたはタブ・リンクが表示されているため、ユーザーは表示することが可能です。

disclosed属性がtrueに設定されているshowDetailItemコンポーネントがない場合は、ADF Facesにより、最初に有効にされたshowDetailItemコンポーネントのコンテンツが自動的に表示されます(panelAccordionコンポーネントの子で、表示されないペインの設定が行われている場合を除きます)。

注意:

コンテンツを表示または非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

10. panelAccordionコンポーネントで使用されているshowDetailItemコンポーネントの場合は、「動作」セクションを開き、showDetailItemコンポーネントが表示される順序を反映するようにDisplayIndexを設定します。単純にページのコード内での順序で表示する場合は、デフォルトの-1のままにします。

ヒント:

一部のshowDetailItemコンポーネントのdisplayIndexの値が-1で、他のコンポーネントでは正の数である場合、-1の値のコンポーネントは、正の数を持つコンポーネントより後に、ページのコードに出現する順序で表示されます。

ヒント:

親panelAccordionコンポーネントが並替えを許可するように構成されている場合は、この値を実行時に変更できます。

11. panelTabbedコンポーネントのタブの削除を許可することを選択した場合は、「動作」セクションを展開し、Removeを次のいずれかに設定します。

- inherit: 対応するタブは、親panelTabbedコンポーネントで許可されている場合に削除できます。これがデフォルトです。

- no: 対応するタブは削除できず、閉じるアイコンは表示されません。

- disabled: 対応するタブには無効な閉じるアイコンが表示されます。

ItemListenerを、コンポーネントの実際の削除を処理するハンドラ・メソッドに解決されるEL式に設定します。

12. (panelAccordionコンポーネントのみでサポートされている)パネルにツールバー・ボタンを追加するには、「コンポーネント」ウィンドウで、「レイアウト」パネルの「メニューおよびツールバー・コンテナ」グループから、そのパネルを定義するshowDetailItemコンポーネントのtoolbarファセットに「ツールバー」を挿入します。次に必要な数のボタン・コンポーネントをtoolbarコンポーネントに挿入します。toolbarファセットがshowDetailItemコンポーネントにある場合でも、ツールバーおよびボタンをレンダリングするのはpanelAccordionコンポーネントです。toolbarおよびボタン・コンポーネントの使用法は、16.3項「ツールバーの使用方法」を参照してください。

注意:

アコーディオン・パネルが閉じている場合、ツールバーおよびそのボタンは表示されません。ツールバーおよびそのボタンは、パネルが開かれている場合にのみ、パネル・ヘッダーに表示されます。

13. showDetailItemに関する情報を追加するには(たとえば、panelSpringboardには注意書きを表示するなど)、Badgeに値を入力します。

14. パネルにコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。

9.10.7 ジオメトリ管理およびshowDetailItemコンポーネントに関する必知事項

panelAccordion、panelTabbed、panelDrawerおよびpanelSpringboardコンポーネントは、子コンポーネントの拡大にジオメトリ管理を使用するコンポーネントに配置された場合、どちらも拡大されるように構成できます。ただし、デフォルトでshowDetailItemはその子を拡大しません。

panelAccordionコンポーネントでは、showDetailItemコンポーネントが拡大されるのは、panelAccordionコンポーネントのdiscloseMany属性がtrueに設定されている場合(つまり、フレキシブルでないコンテンツまたはフレキシブルなコンテンツを表示するために複数のペインが開かれる場合)、showDetailItemコンポーネントに含まれる子コンポーネントが1つのみの場合、およびshowDetailItemコンポーネントのstretchChildren属性がfirstに設定されている場合のみです。

その他のパネル・コンポーネントでは、以下の場合にshowDetailItemコンポーネントが拡大を許可します。

- 含まれる子が1つのみの場合

- stretchChildren属性がfirstに設定されている場合

- 子に幅、高さ、境界およびパディングが設定されていない場合

- 子が拡大可能である場合

前述の項目がすべてtrueの場合、showDetailItemコンポーネントは子コンポーネントを拡大できます。次に、showDetailItemコンポーネント内で拡大可能なコンポーネントを示します。

- decorativeBox(拡大するように構成されている場合)

- calendar

- inputText(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection(拡大するように構成されている場合)

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合のみ)

- panelLabelAndMessage(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

showDetailItemコンポーネント内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelList

- tableLayout (MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントの子として配置することはできません。そのため、showDetailItemコンポーネントの子として拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない別のコンポーネントでそのコンポーネントをラップする必要があります。

たとえば、panelListコンポーネントにコンテンツを配置し、showDetailItemコンポーネント内に表示されるようにする場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをshowDetailItemコンポーネントの子として配置し、panelListコンポーネントをそのコンポーネントに配置します。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

9.10.8 showDetailItem表示イベントに関する必知事項

パネル・コンポーネントの中のshowDetailItemコンポーネントでは表示イベントのキューイングがサポートされるため、サーバーおよびクライアントで検証が適切に処理されます。

一般に、disclosed属性を持つコンポーネントの場合、デフォルトで、クライアントのAdfDisclosureEventのイベント・ルートはイベントのソース・コンポーネントに設定されており、disclosed属性がtrueのパネルに対するイベントのみがサーバーに送信されます。panelAccordion、panelTabbedまたはpanelDrawerコンポーネントの中で使用されるshowDetailItemコンポーネントでは、イベント・ルートはそのパネル・コンポーネントです(つまり、イベント・ソースの親コンポーネントではなく、イベント・ソース・コンポーネントです)。このため、前に開かれたパネルの値はサーバーに送信されません。

たとえば、panelTabbedコンポーネントの中にshowDetailItemコンポーネントが2つあり、discloseMany属性がfalseに、discloseNone属性がfalseに設定されているとします。showDetailItem 1コンポーネントは開かれ、showDetailItem 2は開かれていないとします。このシナリオでは次のようになります。

- クライアント:

- ユーザーがshowDetailItem 2をクリックして表示すると、クライアントのみの表示イベントが発生して、showDetailItem 1コンポーネントのdisclosed属性がfalseに設定されます。この最初のイベントが取り消されない場合、別のクライアントの表示イベントが発生し、showDetailItem 2コンポーネントのdisclosed属性がtrueに設定されます。この2番目のイベントが取り消されない場合、イベントはサーバーに送信されます。それ以外の場合、表示はそれ以上変更されません。

- サーバー:

- サーバーの表示イベントが発生して、showDetailItem 2コンポーネントのdisclosed属性がtrueに設定されます。この最初のサーバー・イベントが取り消されない場合、別のサーバーの表示イベントが発生し、showDetailItem 1コンポーネントのdisclosed属性がfalseに設定されます。どちらのサーバー・イベントも取り消されない場合は、その新規状態がレンダリングされ、ユーザーはクライアントで新しく公開した状態を確認できます。それ以外の場合、クライアントは以前と同じように見えます。

discloseMany属性がfalseに、discloseNone属性がtrueに設定されているpanelAccordionコンポーネントの場合、この情報が当てはまるのは、表示の変更が両方の変更を強制する場合(2つの表示状態が関連する場合)のみです。表示の変更が片方のみの場合、クライアントとサーバーの表示イベントは1つずつです。

discloseMany属性がtrue(および任意のdiscloseNone設定)に設定されているpanelAccordionの場合、実行される表示の変更は1つのみで、クライアントとサーバーの表示イベントは1つずつです。

表示イベントの詳細は、9.9.4項「表示イベントに関する必知事項」を参照してください。

9.10.9 スキニングとpanelTabbedコンポーネントに関する必知事項

-tr-layout-typeスキニング・キーを使用すると、親コンテナが小さすぎてすべてのタブを表示できない場合のpanelTabbedコンポーネントでのオーバーフローの処理方法を構成できます。この圧縮レイアウトでは、1つ以上のオーバーフロー・ボタンを表示するか、コンベア・ベルトのように、非表示になっているタブを順に広げて表示できます。

注意:

オーバーフローは、position属性がabove、below、またはbothに設定されているときにのみサポートされます。

図9-53にオーバーフローの圧縮レイアウトを示します。ユーザーがオーバーフロー・アイコンをクリックすると、非表示になっているアイテムがポップアップに表示されます。

図9-53 オーバーフローの圧縮レイアウト

例9-15に、スキニング・キーを使用してオーバーフローのレイアウトを表示する方法を示します。

例9-15 スキニング・キーを使用して圧縮レイアウトをオーバーフローにする設定

af|panelTabbed {
-tr-layout-type: overflow;
}

図9-54にコンベアによる圧縮レイアウトを示します。ユーザーがオーバーフロー・アイコンをクリックすると、コンベア・ベルトの場合のように、非表示になっていたタブが順に表示域に移動してきます。その結果、反対側にあるタブは非表示になります。

図9-54 コンベア・ベルトによる圧縮レイアウト

例9-16に、スキニング・キーを使用してコンベア・ベルトによるレイアウトを使用する方法を示します。

例9-16 スキニング・キーを使用して圧縮レイアウトをコンベア・ベルトにする設定

af|panelTabbed {
-tr-layout-type: conveyor;
}

注意:

panelTabbedコンポーネントで圧縮レイアウトをサポートするには、親コンポーネントが子を拡大するようになっているか、親コンポーネントに特定の幅が設定されている必要があります。

したがって、次のレイアウト構成はサポートされません。

- 子を拡大しない親コンテナを使用する。

- それぞれの子に明示的なサイズを指定せず、複数の子を水平に表示する親コンテナを使用する。たとえば、layout='horizontal'の場合、panelGroupLayoutは無効ですが、panelSplitterであれば明示的にスプリッタ位置が指定されているので有効になります。

- 幅の値をパーセンテージで割り当てるstyleClassまたはinlineStyleを持つ圧縮レイアウト・コンポーネントを設定する。圧縮レイアウト・コンポーネントにstyleClass='AFStretchWidth'を割り当てる場合もこれに該当します。

スキンの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.11 静的ボックスの項目の表示

panelHeaderコンポーネントは、メッセージの表示や関連するヘルプ・トピックなどのヘッダー・タイプ機能が必要な場合に使用できますが、コンテンツの表示および非表示機能を指定する必要はありません。

ページの別のルック・アンド・フィールに遷移する必要がある場合は、decorativeBoxコンポーネントを使用できます。decorativeBoxコンポーネントは、テーマおよびスキニング・キーを使用して、その様々なファセットの枠および色を制御します。詳細は、9.11.5項「スキニングとdecorativeBoxコンポーネントに関する必知事項」を参照してください。

panelHeaderコンポーネントには、特定タイプのコンポーネント用のファセットや、ヘッダーからヘルプ・トピックを起動する機能があります。次に、panelHeaderコンポーネントでサポートされているファセットを示します。

- context: ヘッダーのヘッダー・テキストの横に情報を表示します。

- help: ヘルプ情報を表示します。後方互換性が必要な場合にのみ使用します。かわりに、panelHeaderコンポーネントではhelpTopicId属性を使用します。

- info: ヘッダー・テキストの下に情報を表示します。右揃えになります。

- legend: ヘルプ・テキストが存在する場合は、ヘルプ・コンテンツの左側でinfoファセットのコンテンツの下に情報が表示されます。ヘルプ・テキストが存在しない場合、legendコンテンツはヘッダーの下に直接レンダリングされます。

- toolbar: メニュー・バーの前にツールバーを表示します。

- menuBar: ツールバーの後ろにメニュー・バーを表示します。

図9-55に、panelHeaderコンポーネントの様々なファセットを示します。

図9-55 panelHeaderおよびそのファセット

タイトル行のすべてのファセットにすべてを表示するのに十分な領域がない場合、panelHeaderテキストが切り捨てられ、省略記号が表示されます。ユーザーが切り捨てられたテキスト上にカーソルを起動すると、図9-56に示すように、ツールチップに完全なテキストが表示されます。

図9-56 panelHeaderが切り捨てられた場合のテキスト

コンテンツを表示するのに十分な領域がある場合は、図9-57に示すように、contextファセットとツールバーの間に追加の領域が配置されます。

図9-57 ツールバーの前に追加された領域

セクションの階層を表すようにpanelHeadersコンポーネントを構成できます。たとえば、図9-58に示すように、サブヘッダーのあるメイン・ヘッダー、およびサブヘッダーのあるヘッダー・レベル1を表示できます。

図9-58 panelHeaderコンポーネントを使用したサブセクションの作成

それぞれにpanelHeaderコンポーネントをネストさせてサブセクションを作成します。panelHeaderコンポーネントをネストさせると、階層に応じてヘッダー・テキストが自動的にサイズ調整され、一番外側のpanelHeaderコンポーネントのテキストが最も大きくなります。

注意:

サイズの処理は、デフォルトでヘッダー・コンポーネントの物理包含によって決定されます。つまり、最初のヘッダー・コンポーネントは見出しレベル1としてレンダリングされます。最初のヘッダー・コンポーネントにネストされるヘッダー・コンポーネントは見出しレベル2などとしてレンダリングされます。各ヘッダー・コンポーネントの見出しレベルは、headerLevel属性を使用して手動でオーバーライドできます。

panelHeaderコンポーネントの使用の詳細は、9.11.1項「panelHeaderコンポーネントの使用方法」を参照してください。

decorativeBoxコンポーネントには、テーマを使用したスタイル設定機能が用意されています。これには、topとcenterの2つのファセットがあります。topファセットは色のない領域を提供し、centerファセットは実際のボックスです。topファセットの高さは、コンポーネントがtopファセットに配置されているかどうかに依存します。ファセットが設定されていると、topHeight属性を使用して、コンテンツが占めるサイズが指定されます。

centerファセットのボックスの色は、使用されるテーマとスキンによって決まります。図9-59に、デフォルトで使用できる様々なテーマを示します。

図9-59 decorativeBoxコンポーネントで使用されているテーマ

デフォルトでは、decorativeBoxコンポーネントは親コンポーネントに合せて拡大されます。子コンポーネントからディメンションを継承するようにdecorativeBoxコンポーネントを構成することもできます。たとえば、図9-60では、親に合せて拡大されるように構成されたミディアム・テーマのdecorativeBoxコンポーネントを示していますが、ダーク・テーマのdecorativeBoxは、最大で子outputTextコンポーネントと同じ大きさになるように構成されています。

図9-60 拡大できる、または拡大できないdecorativeBox

9.11.1 panelHeaderコンポーネントの使用方法

panelHeaderコンポーネントを1つ使用して特定の情報を指定することも、一連のpanelHeaderコンポーネントをネストさせてコンテンツの階層組織を作成することもできます。コンテンツを表示および非表示にできるようにする場合は、かわりにshowDetailHeaderコンポーネントを使用します。詳細は、9.9.2項「showDetailHeaderコンポーネントの使用方法」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.11項「静的ボックスの項目の表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelHeaderコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「パネル・ヘッダー」をページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。

3. Textを、このパネルに表示するラベルに設定します。

4. ラベルの前にアイコンを追加するには、Iconを、使用するイメージ・ファイルのURIに設定します。

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

5. 特定のメッセージ情報の表示にヘッダーを使用している場合は、MessageTypeを次のいずれかの値に設定します。

- confirmation: 指定されたアイコン・イメージが確認アイコン(上に緑のチェックマークが表示されたメモ・ページ)に置き換えられます。

- error: 指定されたアイコン・イメージがエラー・アイコン(中にxがある赤い丸)に置き換えられます。ヘッダー・ラベルも赤に変わります。

- info: 指定されたアイコン・イメージが情報アイコン(中にIがある青い丸)に置き換えられます。

- none: デフォルト。アイコンは表示されません。

- warning: 指定されたアイコン・イメージが警告アイコン(中に感嘆符がある黄色の三角)に置き換えられます。

図9-61に、様々なメッセージ・タイプに使用されるアイコンを示します。

図9-61 メッセージ・タイプのアイコン

注意:

このアイコンには代替テキストを指定できないため、アクセシビリティを考慮した製品を作成するには、このアイコンは装飾目的でのみ使用します。アクセシビリティを考慮した方法で、このアイコンの意味を指定する必要があります。

6. ヘッダーにヘルプを表示するには、HelpTopicIdにトピックIDを入力します。ヘルプ・トピックの作成および使用方法の詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

7. コンポーネントの見出しレベルをオーバーライドするには、headerLevelを目的のレベル(H1、H2などからH6)に設定します。
見出しレベルは、特にスクリーン・リーダー・アプリケーションで使用する場合に、正しいページ構造を決定するのに使用されます。デフォルトで、headerLevelは-1に設定されており、ページの物理的位置に基づいて、ヘッダーでサイズを決定できます。つまり、最初のヘッダー・コンポーネントはH1に設定されます。そのH1コンポーネントにネストされるヘッダー・コンポーネントはH2などに設定されます。

注意:

スクリーン・リーダー・アプリケーションでは、HTMLヘッダー・レベルの割当てを利用して、ページの基本構造を識別します。ヘッダー・コンポーネントおよびヘッダー・レベルの割当てがページで意味をなすようにしてください。

オーバーライド値を使用する場合は、ページの公開可能なセクション内にヘッダーを含めた場合の影響について考慮してください。たとえば、ページに縮小可能な領域がある場合は、領域が縮小および表示されるときに、オーバーライドされた構造が意味を持つようにする必要があります。

8. 見出し階層の構造ではなく、ヘッダー・テキストのサイズのみを変更する場合は、size属性を設定します。
size属性では、ヘッダー・テキストに使用する数値を指定し、スキンをオーバーライドします。最大の数字は0で、これはH1ヘッダー・レベルに対応します。最小は5で、H6ヘッダーに対応します。

デフォルトで、size属性は-1です。これは、ADF Facesにより、使用するヘッダー・レベルのスタイルが最上位の親コンポーネントから自動的に計算されることを意味します。ネストされているコンポーネントを使用する場合は、size属性を明示的に設定して、表示する適切なヘッダー・スタイルを取得する必要はありません。

注意:

テキストのスタイルはsize属性を使用して強制できますが(最大のテキストが0の場合)、size属性の値は階層には影響しません。影響を受けるのはテキストのスタイルのみです。

ADF Facesにより使用されるデフォルトのスキンでは、サイズ3以上に使用されるスタイルがサイズ2と同じように表示されます。これは、カスタム・スキンを作成することで変更できます。詳細は、9.11.4項「スキニングとpanelHeaderコンポーネントに関する必知事項」を参照してください。

9. panelHeaderコンポーネントがジオメトリ管理を処理する方法を制御する場合は、「外観」セクションを開き、Typeを次のいずれかに設定します。ジオメトリ管理の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- flow: コンポーネントは拡大されないか、子を拡大しません。panelHeaderコンポーネントの高さは、その子によってのみ決定されます。

- stretch: コンポーネントは拡大され、その子を拡大します(単一の子コンポーネントのみ拡大します)。

- default: panelHeaderコンポーネントの親コンポーネントでジオメトリ管理を決定する場合。

10. パネルにツールバー・ボタンを追加するには、toolbarコンポーネントをtoolbarファセットに挿入します。次に必要な数のボタン・コンポーネントをtoolbarコンポーネントに挿入します。toolbarおよびボタンの使用方法は、16.3項「ツールバーの使用方法」を参照してください。

注意:

panelHeaderコンポーネントでは、ツールバーのオーバーフローはサポートされていません。

11. パネルにメニューを追加するには、menuBarファセットにmenuコンポーネントを挿入します。メニュー・バーへのメニュー作成の詳細は、16.2項「メニュー・バーでのメニューの使用方法」を参照してください。

ヒント:

toolbarファセットにメニューを配置することも、menuファセットにツールバー(およびツールボックス)を配置することも可能です。これらのファセットの主な違いは場所です。toolbarファセットはmenuファセットの前に配置されます。

12. 必要に応じて、その他のファセットにコンテンツを追加します。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelHeaderコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ヘッダー」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

13. パネルにコンテンツを追加するには、必要な子コンポーネントをpanelHeaderコンポーネントに挿入します。

9.11.2 decorativeBoxコンポーネントの使用方法

decorativeBoxコンポーネントを使用して、ページに色付きの領域またはボックスを配置します。このコンポーネントは、通常、タブを表示するように構成されているnavigationPaneコンポーネントのコンテナとして使用されます。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

decorativeBoxコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「装飾ボックス」をページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開き、Top Heightにtopファセットの高さを設定します。

3. テーマを変更するには、「スタイルおよびテーマ」セクションを開き、別のテーマを選択します。

4. デフォルトでは、decorativeBoxコンポーネントは使用可能なブラウザ領域に合せて拡大されます。かわりに、decorativeBoxコンポーネントを、子を拡大しないコンポーネントの子として使用する場合は、decorativeBoxコンポーネントが拡大を処理する方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントが拡大されるかどうかを構成します。

注意:

dimensionsFrom属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。ジオメトリ管理がdimensionsFrom属性によって決定されるコンポーネントを、親コンポーネントが子の拡大を許可していれば必ず拡大するようにする場合は、dimensionsFrom属性を設定するのではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。dimensionsFrom属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSが設定されるので、次の説明にあるように、dimensionsFromの値はコンポーネントのデフォルト値に基づくものになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

DimensionsFromを次のいずれかの値に設定します。

- children: decorativeBoxコンポーネントは、子コンポーネントからディメンションを取得します。

注意:

この設定を使用する場合は、topファセットの高さの設定に割合を使用できません。使用すると、topファセットはこのdecorativeBoxコンポーネントのサイズからディメンションを取得しようとしますが、decorativeBoxコンポーネントはそのコンテンツから高さを取得するため取得できず、循環依存関係が発生します。割合が使用される場合、それは無視され、デフォルトの50pxがかわりに使用されます。

同様に、decorativeBoxの高さを(たとえばinlineStyleまたはstyleClass属性を通じて)設定することはできません。設定すると、decorativeBoxの高さと子コンポーネントの高さが競合する原因となります。

- parent: decorativeBoxコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

- auto: decorativeBoxコンポーネントの親コンポーネントがその子の拡大を許可する場合、decorativeBoxコンポーネントは親に合せて拡大されます。親がその子を拡大しない場合、decorativeBoxコンポーネントはその子コンポーネントのサイズに基づきます。

詳細は、9.11.3項「ジオメトリ管理およびdecorativeBoxコンポーネントに関する必知事項」を参照してください。

9.11.3 ジオメトリ管理およびdecorativeBoxコンポーネントに関する必知事項

decorativeBoxコンポーネントは、そのcenterファセット内の子コンポーネントを拡大でき、このコンポーネント自体も拡大できます。次のコンポーネントは、decorativeBoxコンポーネントのcenterファセット内で拡大できます。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection(拡大するように構成されている場合)

- panelDashboard

- panelGroupLayout (layout属性がscrollまたはverticalに設定されている場合のみ)

- panelLabelAndMessage(拡大するように構成されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tableLayout(拡大するように構成されている場合。これはMyFaces Trinidadコンポーネントであることに注意してください)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

decorativeBoxコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout (layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelList

- showDetail

- showDetailHeader

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、decorativeBoxコンポーネントのファセットに拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelBoxコンポーネントにコンテンツを配置し、decorativeBoxコンポーネントのファセットに配置するように設定する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをdecorativeBoxコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、9.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

9.11.4 スキニングとpanelHeaderコンポーネントに関する必知事項

またデフォルトではpanelHeaderコンポーネントのヘッダー・サイズに使用されるスタイルはスキンによって制御されます。2以上のヘッダー・サイズは、サイズ2として表示されます。つまり、サイズ3、4または5のスタイルには違いがなく、すべてサイズ2と同じスタイルで表示されます。これは、カスタム・スキンを作成することで変更できます。

詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.11.5 スキニングとdecorativeBoxコンポーネントに関する必知事項

decorativeBoxコンポーネントは、テーマおよびスキニング・キーを使用して、その様々なファセットの枠および色を制御します。たとえば、使用しているスキンに応じて、デフォルトのテーマを使用する場合、decorativeBoxコンポーネント本体は白、枠は青で、左上隅は丸くなります。ミディアム・テーマを使用する場合、本体は中間色の青になります。

注意:

Skyrosスキンの単純な境界線機能を使用する場合、角などの境界要素はまったくレンダリングされません。

スキンを使用して、decorativeBoxコンポーネントのスタイルをさらに制御できます。スキニング・キーは、次のコンポーネント領域に対して定義できます。

- top-start

- top

- top-end

- start

- end

- bottom-start

- bottom

- bottom-end

スキンの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9.12 1つ以上の列における箇条書きリストの表示

panelListコンポーネントは、図9-62に示されているように、それぞれの隣に黒丸が付いた子コンポーネントの垂直のリストを表示するためのレイアウト要素です。rendered属性がtrueに設定されている子コンポーネント、およびvisible属性がtrueに設定されている子コンポーネントのみが、リストの順で表示の対象となります。

注意:

動的データ(JSFバインディングによって実行時に決定されるデータのリストなど)を表示するには、11.6項「選択コンポーネントの使用方法」で説明されているように選択コンポーネントを使用します。モデル・レイヤーを変更するリストを作成する必要がある場合は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

図9-62 デフォルトの黒丸が付いたpanelListコンポーネント

デフォルトで、黒丸は子コンポーネントのスタイルの設定に使用されます。四角や白丸など、使用できるスタイルは他にもあります。表示する項目のリストが非常に長い場合は、リストを列に分割することもできます。

9.12.1 panelListコンポーネントの使用方法

項目のリストを1つ作成するには、panelListコンポーネントを1つ使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.12項「1つ以上の列における箇条書きリストの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelListコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「パネル・リスト」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開き、listStyle属性を以下のような有効なCSS 2.1リスト・スタイル値の1つに設定します。

- list-style-type: disc

- list-style-type: square

- list-style-type: circle

- list-style-type: decimal

- list-style-type: lower-alpha

- list-style-type: upper-alpha

たとえば、list-style-type: disc属性の値は黒丸に対応し、list-style-type: circle値は白丸に対応します。

使用する有効なスタイル値の完全なリストは、次のサイトにある生成されたリストに関するCSS 2.1の仕様を参照してください。

http://www.w3.org/TR/CSS21/generate.html

ヒント:

一部のブラウザは、upper-roman、lower-roman、lower-greekなど、他のブラウザよりも多くのスタイル・オプションをサポートします。これらの表示はWebブラウザ間で一貫性がないため、使用時には注意してください。

例9-17に、リストのスタイルをcircleに設定するコードを示します。

例9-17 listStyle属性が設定されたpanelListコンポーネント

<af:panelList listStyle="list-style-type: circle" ...>
<!-- child components here -->
</af:panelList>

3. panelListコンポーネントに(箇条書き項目として表示する)必要な数の子コンポーネントを挿入します。

ヒント:

通常はパネル・リストの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、パネル・リストにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

たとえば、一連のcommandLinkコンポーネントまたはoutputFormattedコンポーネントを挿入できます。

注意:

ADF Facesでは、デフォルトで、panelListコンポーネントのレンダリングされたすべての子コンポーネントは単一の列に表示されます。リストを2列以上に分割する方法、およびrowsおよびmaxColumns属性の使用方法の詳細は、9.7項「フォームでのコンテンツの配置」を参照してください。panelListおよびpanelFormLayoutコンポーネントでの列表示に対するrowsおよびmaxColumns属性の使用の概念も同じです。

9.12.2 リスト階層の作成に関する必知事項

panelListコンポーネントをネストさせて、リスト階層を作成できます。図9-63に示されているように、リスト階層には外部項目と内部項目があり、外部項目に属する内部項目は外部項目の下にインデント表示されます。内部項目の各グループは、ネストした単一のpanelListコンポーネントによって作成されます。

図9-63 ネストしたpanelListコンポーネントを使用して作成された階層リスト

図9-63のようなリスト階層を作成するには、groupコンポーネントを使用して、外部項目とその内部項目の各グループを構成するコンポーネントをラップします。例9-18に、4つの内部項目を持つ外部項目が1つと、2つの内部項目を持つ別の外部項目があるリスト階層の作成方法に関するコードを示します。

例9-18 ネストしたpanelListコンポーネント

<af:panelList>
<!-- First outer item and its four inner items -->
<af:group>
<af:commandLink text="item 1"/>
<af:panelList>
<af:commandLink text="item 1.1"/>
<af:commandLink text="item 1.2"/>
<af:commandLink text="item 1.3"/>
<af:commandLink text="item 1.4"/>
</af:panelList>
</af:group>
<!-- Second outer item and its two inner items -->
<af:group>
<af:commandLink text="item 2"/>
<af:panelList>
<af:commandLink text="item 2.1"/>
<af:commandLink text="item 2.2"/>
</af:panelList>
</af:group>
</af:panelList>

デフォルトで、外部リスト項目(item 1およびitem 2など)は黒丸の箇条書きスタイルで、内部リスト項目(item 1.1およびitem 2.1など)は白丸の箇条書きスタイルで表示されます。

panelGroupLayoutコンポーネントの詳細は、9.13項「関連する項目のグループ化」を参照してください。

9.13 関連する項目のグループ化

類似する項目を親コンポーネント内に保持するには、groupまたはpanelGroupLayoutコンポーネントを使用します。groupコンポーネントは、意味的に関連のある子コンポーネントを集約またはグループ化します。panelGroupLayoutコンポーネントとは異なり、groupコンポーネントはその子コンポーネントのレイアウトを提供しません。単独で使用される場合、groupコンポーネントは何もレンダリングしません。実行時にgroupコンポーネントの内部の子コンポーネントのみレンダリングされます。

関連するコンポーネントのグループ化には、任意の数のgroupコンポーネントを使用できます。たとえば、panelFormLayoutコンポーネントによって作成されたフォーム・レイアウト内のいくつかの入力フィールドをグループ化するとします。

例9-19に、panelFormLayoutコンポーネント内の2セットの子コンポーネントをグループ化するサンプル・コードを示します。

例9-19 panelFormLayoutの子コンポーネントのグループ化

<af:panelFormLayout>
<af:inputDate label="Pick a date"/>
<!-- first group -->
<af:group>
<af:selectManyCheckbox label="Select all that apply">
<af:selectItem label="Coffee" value="1"/>
<af:selectItem label="Cream" value="1"/>
<af:selectItem label="Low-fat Milk" value="1"/>
<af:selectItem label="Sugar" value="1"/>
<af:selectItem label="Sweetener"/>
</af:selectManyCheckbox>
<af:inputText label="Special instructions" rows="3"/>
</af:group>
<!-- Second group -->
<af:group>
<af:inputFile label="File to upload"/>
<af:inputText label="Enter passcode"/>
</af:group>
<af:inputText label="Comments" rows="3"/>
<af:spacer width="10" height="15"/>
<f:facet name="footer"/>
</af:panelFormLayout>

panelGroupLayoutコンポーネントを使用すると、図9-64に示すように、折り返さずに一連の子コンポーネントを縦または横に配置することも、折り返して続けて配置することもできます。layout属性の値により子コンポーネントの配置が決定されます。

図9-64 panelGroupLayoutの配置

すべての配置において、panelGroupLayoutコンポーネントのseparatorファセットを使用して、隣接する子コンポーネントの各ペアを線または空白で区切ることができます。詳細は、9.14項「空白または線を使用したコンテンツの分割」を参照してください。

横のレイアウトを使用する場合は、子コンポーネントを縦または横に並べることもできます。図9-65に示すように、上部の位置を合せて、高いコンポーネントの隣に低いコンポーネントを作成できます。

図9-65 上部の位置を合せた水平レイアウトのpanelGroupLayout

panelSplitterまたはpanelStretchLayoutコンポーネントとは異なり、panelGroupLayoutコンポーネントでは子コンポーネントは拡大されません。ページのルート・コンポーネントとしてpanelSplitterまたはpanelStretchLayoutコンポーネントを使用し、配置するが拡大しない子コンポーネントが多数あるとします。子コンポーネントを配置する際にスクロールバーを表示するには、layout属性がscrollに設定されたpanelGroupLayoutコンポーネントで子コンポーネントをラップし、そのpanelGroupLayoutコンポーネントをpanelSplitterまたはpanelStretchLayoutコンポーネントのファセットに配置します。

panelGroupLayoutコンポーネントでlayout属性がscrollに設定されていて、panelGroupLayoutコンポーネントに含まれているコンテンツがpanelGroupLayoutコンポーネント自体より大きい場合、ADF Facesでは、実行時に自動的にスクロールバーが表示されます。スクロールバーを有効にするコードを記述する必要も、オーバーフローを制御するインライン・スタイルを設定する必要もありません。

たとえば、ユーザーによる子コンポーネントのコンテンツの表示や非表示を可能にするpanelSplitterコンポーネントなどのレイアウト・コンポーネントを使用する際には、コンテンツが表示された場合にスクロールバーを表示するためのコードや、コンテンツが非表示にされた場合にスクロールバーを非表示にするためのコードを記述する必要はありません。表示するコンテンツを単純にpanelGroupLayoutコンポーネントにラップし、layout属性をscrollに設定します。

File Explorerアプリケーションには、検索条件を表示および非表示にするために使用されるpanelSplitterコンポーネントが含まれています。検索条件が非表示で、検索結果が領域に収まらない場合は、図9-66に示すようにスクロールバーがレンダリングされます。

図9-66 panelGroupLayoutを使用してレンダリングされたスクロールバー

9.13.1 panelGroupLayoutコンポーネントの使用方法

panelGroupLayoutコンポーネントは、必要なレイアウトにするためにいくつでもネストさせることができます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.13項「関連する項目のグループ化」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

panelGroupLayoutコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「パネル・グループ・レイアウト」をJSFページにドラッグ・アンド・ドロップします。

2. panelGroupLayoutコンポーネントに必要な子コンポーネントを挿入します。

ヒント:

通常はpanelGroupLayoutコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelGroupLayoutコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

3. 隣接する子コンポーネントの間に間隔または区切り線を追加するには、separatorファセットにspacerまたはseparatorコンポーネントを挿入します。

4. 「プロパティ」ウィンドウで「外観」セクションを開きます。子コンポーネントを希望のレイアウトに配置するには、Layoutを次のいずれかの値に設定します。

- default: 折り返された連続のレイアウトです。
実行時、コンテンツがブラウザの使用可能な領域を超えると(子コンポーネントが親コンテナであるpanelGrouplayoutの幅より大きい場合)、すべての子コンポーネントが表示されるよう、ブラウザによりコンテンツが次の行に配置されます。

注意:

ADF Facesでは、コンテンツの配置時に双方向のアルゴリズムが使用されます。右から左のコンテンツおよび左から右のコンテンツが混在し、コンテンツが連続して配置されない場合があります。

- horizontal: 横のレイアウトになり、子コンポーネントは横に並べられます。コンテンツがブラウザの使用可能な領域を超えても折り返されません。
横のレイアウトでは、子コンポーネントを縦に並べることも横に並べることもできます。デフォルトで、horizontalの子コンポーネントは架空の水平線と垂直線を基準にしてそれぞれの中央に配置されます。horizontalコンポーネントの横および縦の配置を変更するには、次の属性を使用します。

- halign: 横の配置を設定します。デフォルトは、centerです。使用できるその他の値はstart、end、left、rightです。
たとえば、言語の読み方向が左から右の場合にhorizontalの子コンポーネントを常に左揃えにし、読み方向が右から左の場合には右揃えにするには、halignをstartに設定します。

- valign: 縦の配置を設定します。デフォルトはmiddleです。使用できるその他の値はtop、bottom、baselineです。
テキストのフォント・サイズを変更した出力テキスト・コンポーネント(outputTextなど)で、valignをbaselineに設定すると、図9-67に示されているように、文字が配置されている架空の線に沿ってテキストの文字が並べられます。そのようなテキスト・コンポーネントでvalignをbottomに設定した場合、bottomの縦の配列ではすべての文字の一番下の部分が同じ架空の線上に配置されるため、結果は見栄えのよい外観にはなりません。

図9-67 テキストのbottomおよびbaselineの縦の位置

注意:

layoutがhorizontalではない場合、halignおよびvalign属性は無視されます。

- scroll: 縦のレイアウトになり、子コンポーネントは縦に並べられ、必要な場合には縦のスクロールバーが表示されます。

- vertical: 縦のレイアウトになり、子コンポーネントは縦に並べられます。

9.13.2 ジオメトリ管理およびpanelGroupLayoutコンポーネントに関する必知事項

panelGroupLayoutコンポーネントは子コンポーネントを拡大できませんが、panelSplitterまたはpanelStretchLayoutコンポーネントの子で、layout属性がscrollまたはverticalに設定されている場合には拡大できます。

9.14 空白または線を使用したコンテンツの分割

ページ内に空白の部分を配置して、コンポーネントの間に間隔を設け、すべてのコンポーネントを互いのすぐ隣やすぐ下に詰めて配置した場合よりも見やすくすることができます。この目的で提供されているADF Facesコンポーネントは、spacerコンポーネントです。

heightおよびwidth属性を使用して、縦または横、あるいはその両方の空白をページに組み込むことができます。

height: ページに組み込む縦の空白の量を決定する属性。例9-20に、縦の空白を使用して、2つの長いoutputTextコンポーネントの間に一定の間隔を設けるよう設定されたページを示します。

例9-20 縦の空白

<af:panelGroupLayout layout="vertical">
<af:outputText value="This is a long piece of text for this page..."/>
<af:spacer height="10"/>
<af:outputText value="This is some more lengthy text ..."/>
</af:panelGroupLayout>

図9-68に、ブラウザで表示した場合に、spacerコンポーネントがページ出力に及ぼす影響を示します。

図9-68 ブラウザで表示した縦の空白

width属性は、コンポーネント間に組み込む横の空白の量を決定します。例9-21に、2つのコンポーネントの間に横方向の間隔を設けるよう設定されたページのソースの一部を示します。

例9-21 横の空白

<af:outputLabel value="Your credit rating is currently:"/>
<af:spacer width="10"/>
<af:outputText value="Level 8"/>

図9-69に、ブラウザで表示した場合の、横方向の間隔調整コンポーネントの影響を示します。

図9-69 ブラウザで表示した横の空白

separatorコンポーネントを使用すると横線を作成できます。図9-70に、2つのpanelBoxコンポーネント間にseparatorコンポーネントを挿入した場合のproperties.jspxファイルの外観を示します。

図9-70 線を作成するためのseparatorコンポーネントの使用

通常、spacerおよびseparatorコンポーネントは、その他のレイアウト・コンポーネントのファセットに使用します。これにより、分割するコンポーネントに空白または線が表示されます。

9.14.1 spacerコンポーネントの使用方法

ページには、必要な数だけspacerコンポーネントを使用できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.14項「空白または線を使用したコンテンツの分割」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

spacerコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「スペーサ」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。必要に応じて幅と高さを設定します。

注意:

高さが指定されていて幅が指定されていない場合、ブロック・レベルのHTML要素がレンダリングされ、その近くに新しい行が表示されます。幅が指定されている場合、指定されている高さの値に関係なく、HTML標準を厳密にサポートするユーザー・エージェントに適用可能な行の高さより低くなりません。

9.14.2 separatorコンポーネントの使用方法

ページには、必要な数だけseparatorコンポーネントを使用できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、9.14項「空白または線を使用したコンテンツの分割」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、9.1.1項「レイアウト・コンポーネントの追加機能」を参照してください。

separatorコンポーネントを作成および使用する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルで「セパレータ」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、必要に応じてプロパティを設定します。

10 フラグメント、ページ・テンプレート、コンポーネントの作成および再利用

この章では、再利用可能なコンテンツを作成し、それらを使用してJSFページの一部またはページ全体を作成する方法を説明します。ページ・テンプレートを使用してページに適用できるページ全体のレイアウトを定義する方法を説明します。また、ページ・フラグメントを使用して複雑なページを構築する方法についても説明します。その後、既存のADF Facesコンポーネントを使用して再利用可能な宣言コンポーネントを作成する方法を説明します。

この章では、次の項目について説明します。

- 10.1項「再利用可能なコンテンツについて」

- 10.2項「再利用可能なコンポーネントの共通機能」

- 10.3項「ページ・テンプレートの使用」

- 10.4項「ページ・フラグメントの使用」

- 10.5項「宣言コンポーネントの使用」

- 10.6項「ページへのリソースの追加」

10.1 再利用可能なコンテンツについて

アプリケーションにJSFページを作成する場合、一部のページが複雑で長くなり、編集が込み入って煩雑になることがあります。非常に特有なレイアウトに配置されたコンポーネントのグループが常にページに含まれる場合や、ページの複数の部分で特定のコンポーネントのグループを使用する場合もあります。あるいは、ページの一部またはページ全体を、他の開発者と共有する必要がある場合もあります。どのような場合でも、UIに変更が発生すると、多くの場所とページに変更内容を反映する必要があります。それらすべてのページを作成して維持し、構造やレイアウトの一部またはすべてが一貫していることを確認するのは、非効率的な作業になっていく可能性があります。

個々のUIコンポーネントを使用してページを作成するかわりに、ページのビルディング・ブロックを使用してページの一部またはページ全体を作成できます。ビルティング・ブロックには、頻繁にまたは一般的に使用されるUIコンポーネントが含まれており、アプリケーションの1つ以上のページで使用するための再利用可能なコンテンツを作成できます。アプリケーションに応じて、1つ以上のページに、1つのタイプのみのビルディング・ブロックを使用することも、すべてのタイプを使用することもできます。また、複数のビルディング・ブロックをアプリケーション全体で共有できます。ビルディング・ブロックに変更を加えた場合は、再利用可能なコンテンツを使用しているJSFページも自動的に更新されます。このため、アプリケーションで再利用可能なコンテンツを作成および使用することで、構造とレイアウトが常に一貫したWebユーザー・インタフェースと、スケーラブルで拡張可能なアプリケーションを作成できます。

ADF Facesには、次のタイプの再利用可能なビルディング・ブロックがあります。

- ページ・テンプレート: ページ・テンプレートを作成することで、個々のコンポーネントとページ・フラグメントを使用してページ全体のレイアウトを作成できます。たとえば、複数のJSFページに特定の方法で複数のコンポーネントを繰り返しレイアウトする場合には、それらのページ用にページ・テンプレートを作成することを検討します。ページの作成にページ・テンプレートを使用すると、アプリケーション全体の構造およびレイアウトで常にページの一貫性を保つことができます。
ページ・テンプレートと宣言コンポーネントは機能の大部分を共有します。主な違いは、ページ・テンプレートがページ・テンプレート・モデルを使用してADFモデル・バインディングとADFコントローラをサポートすることです。value属性を使用して、ページ・テンプレート内部のバインディングとして使用するオブジェクトを指定できます。valueがページ・テンプレート・モデル・バインディングの場合は、ADFモデル・ページ・バインディングを使用でき、ADFページ定義を使用して、含めるビューを決定できます。

ページ・テンプレートの作成および使用方法の詳細は、10.3項「ページ・テンプレートの使用」および10.3.3項「ページ・テンプレートに基づくJSFページの作成方法」を参照してください。

- ページ・フラグメント: ページ・フラグメントを使用すると、ページの一部を作成できます。JSFページは、1つ以上のページ・フラグメントで構成されます。たとえば、大規模なJSFページは、複数の小規模なページ・フラグメントに分割するとより簡単にメンテナンスできます。ページ・フラグメントの作成および使用方法の詳細は、10.4項「ページ・フラグメントの使用」を参照してください。

- 宣言コンポーネント: 宣言コンポーネント機能を使用すると、個々の既存のUIコンポーネントを、1つ以上のページで宣言的に使用できる再利用可能な1つのコンポジット・コンポーネントにアセンブルできます。たとえば、複数の場所にコンポーネントのグループを挿入する場合、個々のコンポーネントを構成するコンポジット宣言コンポーネントを作成し、その宣言コンポーネントをアプリケーション全体の複数の場所に再利用することを検討します。宣言コンポーネントは、ページ・テンプレートでも使用できます。
宣言コンポーネントは、ADFライブラリJARファイルの一部としてデプロイされます。これは、コンポーネントを独自のネームスペースに挿入できるようにする独自のTLDファイルを備えています。宣言コンポーネントでは、ファセットをコンポーネントに渡すことができ、属性およびメソッド式を渡すこともできます。宣言コンポーネントの内部では、属性およびファセットはEL式を使用してアクセスできます。ADFモデルまたはADFコントローラが関係しないため、オーバーヘッドは比較的低く、ADFモデル・トランザクションまたはADFコントローラ・ページ・フローもサポートしません。

宣言コンポーネントの内部にある個々のコンポーネントを参照してはならず、宣言コンポーネント内の個々のコンポーネントは外部コンポーネントを参照してはなりません。その理由は、宣言コンポーネント内または使用ページ内の変更は、部分トリガーが機能しなくなる原因となるためです。宣言コンポーネントの作成および使用方法の詳細は、10.5項「宣言コンポーネントの使用」を参照してください。

ヒント:

アプリケーションでADFコントローラやADFモデル・レイヤーが使用されている場合は、ADFリージョンも使用できます。ADFバインド・タスク・フローとともに使用されるリージョンは、ビジネス・ロジック、プロセス・フローおよびUIコンポーネントのすべてを、アプリケーション全体で再利用可能な1つのパッケージにカプセル化します。ADFバインド・タスク・フローをリージョンとして作成および使用する方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「タスク・フローをリージョンとして使用する方法」の章を参照してください。

ページ・テンプレート、ページ・フラグメントおよび宣言コンポーネントは、アプリケーション内のページに一貫性のある構造およびレイアウトを提供します。これらのビルディング・ブロックは、同じアプリケーション内で再利用できるだけでなく、異なるアプリケーション間でも共有できます。ビルディング・ブロックを更新すると、それを使用しているすべてのインスタンスが自動的に更新されます。

ページ・テンプレートは、変更されない静的領域と実行時に変更される動的領域の両方をサポートするデータ・バインドされたテンプレートです。ページ・フラグメントを使用して、モジュール形式のページを作成できます。たとえば、ヘッダー、フッターおよび企業ロゴのページ・フラグメントを作成し、これらのフラグメントをアプリケーション全体で再利用できます。宣言コンポーネントは、グループ内で常に使用される複数のコンポーネントがある場合に使用できます。宣言コンポーネントを作成することで、それをタグ・ライブラリに追加し、JDeveloperの「コンポーネント」ウィンドウから宣言コンポーネントをドラッグ・アンド・ドロップできます。

ページ・テンプレート、宣言コンポーネントおよびリージョンにより、javax.faces.component.NamingContainerインタフェースが実装されます。実行時に、再利用可能なコンテンツを使用するページで、ページ・テンプレート、宣言コンポーネントまたはリージョンによりコンポーネントのサブツリーが作成され、使用ページの単一のJSFコンポーネント・ツリーに挿入されます。使用ページには独自のネーミング・コンテナがあるため、ページに再利用可能なコンテンツを追加する場合、partialTargetsやfindComponent()などのメカニズムを使用する際には、ページに表示される様々なコンポーネントの異なるネーミング・コンテナを考慮する必要があるため、十分に注意してください。ネーミング・コンテナの詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。

CSSやJavaScriptなどのリソースを含めることを計画している場合は、af:resourceタグを使用してリソースをページに追加できます。このタグがページ・テンプレートと宣言コンポーネントで使用されている場合は、JSPの実行時に、指定されたリソースが使用ページに追加されます。詳細は、10.6項「ページへのリソースの追加」を参照してください。

ページの一部へのナビゲートにADFタスク・フローを使用していない場合は、領域を使用できず、かわりに他の複合コンポーネントの1つを使用します。複合コンポーネントのうち、複合コンポーネントの内部でバインディングを使用する必要があり、それらがホスト・ページのバインディングと異なる場合は、ページ・テンプレートを使用する必要があります。宣言コンポーネントは、ページにバインディングが不要で、バインドされたタスク・フローをページの一部として使用する必要がない場合に使用する必要があります。

10.1.1 再利用可能なコンポーネントのユースケースと例

File Explorerアプリケーションでは、fileExploreorTemplateを使用して、アプリケーション内のすべてのページに一貫性のあるルック・アンド・フィールを提供します。ファイルのファセットは、様々なタイプの情報を配置する作業領域を提供します。テンプレートは、すべてのページに著作権情報を表示するために使用されるappCopyrightファセットを定義します。

File Explorerアプリケーションのメイン・ページは、ページ・テンプレートを使用するだけでなく、ページ・フラグメントも使用して、テンプレートの個々のファセットのコンテンツを含めます。header.jspxページ・フラグメントには、アプリケーションのメニュー・コマンドが含まれます。

グループとして機能し、複数の場所で繰り返される複数のコンポーネントがある場合は、宣言コンポーネントを定義して、これらのコンポーネントをグループ化できます。コンポーネントを作成した後で、この宣言コンポーネントを他のコンポーネントと同様に使用できます。たとえば、姓、名および電子メール・アドレスを示すために複数のinputTextコンポーネントを使用できます。この3つのinputTextコンポーネントはアプリケーションで繰り返し使用されるため、それらの宣言コンポーネントを作成できます。

10.1.2 再利用可能なコンポーネントの追加機能

再利用可能なコンポーネントを実装する前に、他のOracle ADF機能を理解することが役立つ場合があります。再利用可能なコンポーネントに関連する他の機能へのリンクを次に示します。

- カスタマイズの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「MDSでのアプリケーションのカスタマイズ」の章を参照してください。

- 事前に構成されたレイアウトを提供するためのクイック・スタート・レイアウトの使用の詳細は、9.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

- モデル・パラメータとADFモデル・データ・バインディングの使用に関する詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ・テンプレートの使用に関する項を参照してください。

- ページ・テンプレートを再利用のためにADFライブラリのJARファイルにパッケージ化する方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

10.2 再利用可能なコンポーネントの共通機能

ページ・テンプレートと宣言コンポーネントは、いくつかの共通機能を共有します。

10.2.1 リクエスト・スコープ内のページ

ページのすべてのview部分(フラグメント、宣言コンポーネントおよびメイン・ページ)では、同じリクエスト・スコープが共有されます。このため、1つのページに同じフラグメントまたは宣言コンポーネントを複数回使用する場合や、バッキングBeanが共有される場合に競合が発生する可能性があります。宣言コンポーネントとページ・テンプレートには、backingBeanScopeを使用する必要があります。スコープの詳細は、5.6項「オブジェクト・スコープ・ライフサイクル」を参照してください。

10.2.2 カスタマイズのための子コンポーネントへのアクセス

ページ・テンプレートまたは宣言コンポーネントの子コンポーネントを外部参照によって変更できるかどうかを制御できます。たとえば、子コンポーネントのカスタマイズを有効または無効にできます。af:pageTemplateDefとaf:componentDefの両方に、アクセスを制御するdefinition属性があります。definitionがpublicに設定されている場合、直接の子コンポーネントをカスタマイズできますが、definitionがprivateに設定されている場合は、子コンポーネントをカスタマイズできません。デフォルト値はprivateです。definition属性を変更するには、ソース・ファイルを編集するか、「プロパティ」ウィンドウを使用します。

カスタマイズの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「MDSでのアプリケーションのカスタマイズ」の章を参照してください。

10.3 ページ・テンプレートの使用

ページ・テンプレートでは、ページの特定の属性値など、ページ・レイアウト全体を定義できます。テンプレートを使用してページを作成すると、定義したレイアウトがすべて継承されます。テンプレートのレイアウトを変更すると、そのテンプレートを使用するすべてのページにレイアウトの変更が自動的に反映されます。テンプレートのレイアウトは、自分で作成することも、多数あるクイック・レイアウト設計の1つを使用して作成することもできます。これらの事前定義済レイアウトを使用すると、必要なレイアウトの外観および動作を実装するために必要となる適切なコンポーネントが自動的に挿入されて構成されます。たとえば、1つの列の幅はロックし、他の列は拡大してブラウザの使用可能な領域を埋めることができます。図10-1に、2番目の列が2つのペインに分割されている2列レイアウトで使用可能なクイック・レイアウトを示します。レイアウト・コンポーネントの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

図10-1 クイック・レイアウト

アプリケーションにページ・テンプレートを使用するには、まず、ページ・テンプレート定義を作成します。ページ・テンプレートはXMLコンテンツを埋め込むため、ページ・テンプレート定義はFaceletまたはJSP XMLドキュメントである必要があります。ページのすべてのコンポーネントをf:viewタグで囲む必要のある通常のJSFページとは対照的に、ページ・テンプレート定義にはf:viewタグを含めることができず、ルート・タグとしてpageTemplateDefが必要です。テンプレートを使用するページにはdocumentタグが含まれている必要があります(JDeveloperにより、デフォルトで使用ページにdocumentタグが追加されます)。

ページ・テンプレートには、固定コンテンツ領域および動的コンテンツ領域を作成できます。たとえば、「Help」ボタンを必ずページ上部の右端に配置する場合、そのボタンをテンプレート・レイアウトに定義すれば、ページ作成者がそのテンプレートを使用してページを作成する際に、「Help」ボタンを追加および構成する必要はありません。一方、動的コンテンツ領域は、ページ作成者がテンプレートの定義済のファセット内にコンテンツを追加することや、作成中のページのタイプに固有のプロパティ値を設定することが可能なテンプレートの領域です。

ページ・テンプレートの完全な説明は、2つのセクションを持つpageTemplateDefタグ内に定義されています。1つのセクションがxmlContentタグ内にあり、これには、テンプレートのサポートされるコンテンツ領域(ファセットで定義)と使用可能なプロパティ(属性で定義)を記述するすべてのページ・テンプレート・コンポーネント・メタデータが含まれます。2つ目のセクション(xmlContentタグの外)は、テンプレートの実際のページ・レイアウトを構成するすべてのコンポーネントが定義される部分です。レイアウト・セクションのコンポーネントは、ページ・テンプレートのコンテンツのレンダリングに使用されるJSFコンポーネント・サブツリーを提供します。

ファセットは、ページ上のコンテンツのプレースホルダとして機能します。テンプレートを使用するページでは、ページ作成者がテンプレートにコンテンツを挿入できるのは、すでに定義済の名前付きファセットに対してのみです。これは、ページ・テンプレートを設計する際には、各名前付きファセットのfacet要素を使用して、xmlContentタグ内に使用可能なすべてのファセットを定義する必要があることを意味します。ページ・テンプレート定義のレイアウト・セクションで、様々なコンポーネントを使用してテンプレート・レイアウトを作成する場合には、facetRefタグを使用して、ページ作成者がテンプレートにコンテンツを挿入できるそれらのコンポーネント内の名前付きファセットを参照します。

たとえば、fileExplorerTemplateテンプレートには、例10-1に示すように、コピーライト情報用のファセット、およびアプリケーション情報用の別のファセットが含まれます。

例10-1 テンプレートのファセット定義

<facet>  <description>
<![CDATA[Area to put a link to more information
about the application.]]>
</description>
<facet-name>appAbout</facet-name>
</facet>
<facet>
<description>
<![CDATA[The copyright region of the page.  If present, this area
typically contains an outputText component with the copyright
information.]]>
</description>
<facet-name>appCopyright</facet-name>
</facet>

例10-2に示されているテンプレートのレイアウト・セクションでは、セルにappCopyrightファセットへの参照が含まれる表と、appAboutファセットへの参照が含まれる別のファセットがpanelGroupLayoutコンポーネントに含まれています。これは、ページ開発者がコンテンツの配置を許可される場所です。

例10-2 ページ・テンプレート内のファセット参照

<af:panelGroupLayout layout="vertical">
<afh:tableLayout width="100%">
<afh:rowLayout>
<afh:cellFormat>
<af:facetRef facetName="appCopyright"/>
</afh:cellFormat>
</afh:rowLayout>
</afh:tableLayout>
<af:facetRef facetName="appAbout"/>
</af:panelGroupLayout>

注意:

ページ・テンプレート定義のレイアウト・セクションで、各名前付きファセットを参照できるのは一度のみです。つまり、同じテンプレート定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

pageTemplateDefタグは、ページ・テンプレート定義に必要なすべての情報およびコンポーネントを記述しますが、ページ・テンプレートを使用するJSFページでは、pageTemplateタグを使用して、ページ・テンプレート定義を参照します。例10-2に、index.jspxページがfileExplorerTemplateテンプレートを参照する方法、テンプレートの属性の値を提供する方法、およびテンプレートのファセット定義内にコンテンツを配置する方法を示します。

設計時、テンプレートを使用するページ開発者は、例10-3に示すように、f:facetタグを使用してappCopyrightファセットにコンテンツを挿入できます。

例10-3 JSFページでのページ・テンプレート・ファセットの使用

<af:pageTemplate id="fe"
viewId="/fileExplorer/templates/fileExplorerTemplate.jspx">
<f:attribute name="documentTitle"
value="#{explorerBundle['global.branding_name']}"/>
<f:attribute name="headerSize" value="70"/>
<f:attribute name="navigatorsSize" value="370"/>
.
.
.
<f:facet name="appCopyright">
<!-- Copyright info about File Explorer demo -->
<af:outputFormatted value="#{explorerBundle['about.copyright']}"/>
</f:facet>
.
.
.
</af:pageTemplate>

実行時、テンプレート定義のaf:facetRef facetName="appCopyright"に示されているように、挿入されたコンテンツはページの適切な場所に表示されます。

注意:

JDeveloperでページ・テンプレートを実行ターゲットとして実行することはできません。ページ・テンプレートを使用するページを実行できます。

ページ・テンプレート属性は、テンプレートで設定または変更できるコンポーネント・プロパティ(headerGlobalSizeなど)を指定します。facet要素の情報は、テンプレートのどこにコンテンツを挿入できるかを指定するために使用されますが、attribute要素の情報は、テンプレートへの受渡しに使用可能なページ属性、およびテンプレート・プロパティを設定または変更するために、それらの属性を使用できるテンプレートの場所の指定に使用されます。ページ・テンプレートでは、動的属性もinlineタグとしてサポートされます。たとえば、af:pageTemplate headerSize="70"は有効な構文です。

ページ・テンプレートでそのテンプレート自体の属性を参照する場合には、pageTemplateDefタグに、テンプレートに定義された各属性を参照するためのEL変数名が含まれるvar属性が必要です。たとえば、fileExplorerTemplateテンプレートでは、pageTemplateDefタグのvarの値はattrsに設定されています。テンプレートのレイアウト・セクションで、ページ作成者が独自の値の指定や、デフォルト値の変更を実行できるそれらのコンポーネント属性に、#{attrs.someAttributeName}などのEL式を使用します。

たとえば、fileExplorerTemplateテンプレート定義ではヘッダー・サイズの属性が定義されますが、例10-4に示すように、デフォルトのint値である100ピクセルが設定されています。

例10-4 ページ・テンプレートの属性の定義

<attribute>
<description>
Specifies the number of pixels tall that the global header content should
consume.
</description>
<attribute-name>headerGlobalSize</attribute-name>
<attribute-class>int</attribute-class>
<default-value>100</default-value>
</attribute>

次のコードに示すように、テンプレートのレイアウト・セクションでは、panelSplitterコンポーネントのsplitterPosition属性が、EL式#{attrs.headerGlobalSize}でheaderGlobalSize属性を参照しています。

<af:panelSplitter splitterPosition="#{attrs.headerGlobalSize}" ../>

ページ作成者はこのテンプレートを使用すると、次のコードに示すように、f:attributeを使用してheaderGlobalSizeを変更できます。

<af:pageTemplate ..>
<f:attribute name="headerGlobalSize" value="50"/>
.
.
.
</af:pageTemplate>

実行時、属性名を参照するEL式が示すように、指定された属性値はテンプレートの適切な部分に置き換えられます。

ヒント:

ページ・テンプレートのリソース・バンドルを定義すると、テンプレートを使用するページでもリソース・バンドルを使用できるようになります。リソース・バンドルの使用の詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

複数のテンプレートで同じコンテンツを再利用する必要がある場合は、テンプレートをネストできます。たとえば、アプリケーションに3種類のページがあり、ヘッダーとフッターが常に同じであるとします。同じヘッダーとフッターの設計を3つの異なるテンプレートに含めるかわりに、ヘッダー・テンプレートとフッター・テンプレートを作成し、これらのテンプレートを異なる各ページ・テンプレートに単純にネストできます。

単純なページ・テンプレートの場合、レイアウト・セクション全体のすべてのコンポーネントをページ・テンプレート定義ファイルに配置するだけでかまいません。より複雑なページ・テンプレートの場合は、メンテナンスしやすいようレイアウト・セクションを複数の小規模なフラグメント・ファイルに分割し、jsp:includeタグを使用して、様々なフラグメント・ファイルを組み入れて連携させます。

ページ・テンプレートのレイアウト・セクションをより小さな複数のフラグメント・ファイルに分割する場合、すべてのページ・テンプレート・コンポーネント・メタデータがメイン・ページ・テンプレート定義ファイルのxmlContentタグ内に含まれている必要があります。pageTemplateDefタグ内では1つのxmlContentタグのみ使用できます。フラグメント・ファイル内ではページ・テンプレート・コンポーネント・メタデータを使用できません。フラグメント・ファイルには、ページ・テンプレート・レイアウト・コンポーネントの一部のみ含めることができます。

注意:

ページ・テンプレートを、その他のページ・テンプレートにネストさせることはできません。

テンプレートに、CSSに定義されているカスタム・スタイルまたはJavaScriptなどのリソースが必要な場合は、af:resourceタグを使用して、使用ページにそれらのリソースを含める必要があります。詳細は、10.6項「ページへのリソースの追加」を参照してください。

10.3.1 ページ・テンプレートの作成方法

JDeveloperは、名前付きファセットおよび属性を宣言的に追加してテンプレートのテンプレート・コンポーネント・メタデータ・セクションを作成できる「JSFページ・テンプレートの作成」ウィザードを提供することで、ページ・テンプレート定義の作成を簡略化します。メタデータ・コードの生成に加えて、JDeveloperでは、プロジェクトで作成するすべてのページ・テンプレートを追跡するpagetemplate-metadata.xmlファイルも作成および変更されます。

パフォーマンスのヒント:

ページ・テンプレートはすべてのアプリケーション・ページで使用される可能性があるため、共通のオーバーヘッドを回避できるよう最適化する必要があります。オーバーヘッドの一例は、ボックスなどの丸い角で、オーバーヘッドはかなり大きいです。これをテンプレートに追加することは、各ページにオーバーヘッドを追加することになります。

始める前に:

テンプレートに関する知識が役立つ場合があります。詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

ページ・テンプレート定義を作成する手順:

1. 「アプリケーション」ウィンドウで、ページ・テンプレートを作成して保存するノードを右クリックし、「新」→「ADFページ・テンプレート」を選択します。

2. 「ページ・テンプレートの作成」ダイアログで、ページ・テンプレート定義のファイル名を入力します。
ページ・テンプレート定義にはXMLコンテンツが埋め込まれているため、ページ・テンプレート定義は、XMLドキュメント(ファイル拡張子は.jspx)である必要があります。

パフォーマンスのヒント:

サーバー側、ネットワーク・トラフィックおよびクライアント処理に影響があるため、長い名前にしないでください。

3. テンプレート定義用のディレクトリ名をそのまま使用するか、新しい場所を選択します。
ページ・テンプレートをADFライブラリとしてパッケージ化する場合は、デフォルトのディレクトリ名を受け入れないでください。他のADFライブラリからのページ・テンプレートと競合する可能性を最小限にするために、一意のディレクトリ名を指定してください。

4. ドキュメント・タイプとして、「Facelets」またはJSP XMLを選択します。

5. ページ・テンプレート定義のページ・テンプレート名を入力し、「次」をクリックします。

6. 「ページ・テンプレートの作成」ダイアログの「(オプション)開始コンテンツの追加」ページで、テンプレートの選択肢をいずれか選択してからテンプレートを選択し、「次」をクリックします。

- 空白のテンプレート: 空白のページから始める場合に選択します。

- 既存のテンプレートのコピー: 既存のページを使用して始める場合に選択します。

- クイック・スタート・レイアウトのコピー:事前定義された様々なテンプレート(1列、2列または3列のレイアウトがあります)を利用する場合に選択します。

7. 「ページ・テンプレートの作成」ダイアログの「ファセット定義と属性の追加」ページで、ファセットと属性を追加できます。

- 「ファセット定義」セクションで、「追加」をクリックしてファセット名と説明を追加します。
ファセットは、ページ・テンプレートの事前定義済領域で、テンプレートを使用してページを作成する際にコンテンツを挿入できます。各ファセットには一意の名前が必要です。たとえば、ページのメインのコンテンツ領域にはmainというファセットを、ページのブランド領域にはbrandingというファセットを定義できます。

ヒント:

ページでのテンプレートのネストまたは複数のテンプレートの使用を計画している場合は、混乱を避けるために、すべてのテンプレートのファセットに一意の名前を使用します。

- 「属性」セクションで、「追加」をクリックして属性を追加します。
属性はUIコンポーネント属性で、テンプレートを使用してページを作成する際にページに渡すことができます。各属性には名前とクラス・タイプが必要です。属性(手順13で構成するコンポーネントの属性など)を使用するものは、そのタイプを使用できる必要があります。デフォルト値を割り当て、「必須」チェック・ボックスを選択することで、値が必須であることを指定できます。

- 「次」をクリックします。

8. ページ・テンプレート・コンテンツにADFモデル・データ・バインディングが使用されている場合は、「ページ定義の作成」チェック・ボックスを選択し、「追加」をクリックして1つ以上のモデル・パラメータを追加します。モデル・パラメータとADFモデル・データ・バインディングの使用に関する詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ・テンプレートの使用に関する項を参照してください。
ウィザードを完了すると、JDeveloperにより、ビジュアル・エディタにページ・テンプレート定義ファイルが表示されます。例10-5に、ウィザードを使用してページ・テンプレート定義のメタデータを定義する際に、JDeveloperにより追加されるコードを示します。このコードは、ソース・エディタで表示できます。

ヒント:

テンプレートを作成したら、「構造」ウィンドウでpageTemplateDefタグを選択し、「プロパティ」ウィンドウを使用して、ファセットと属性を追加できます。

注意:

テンプレート・コンポーネント・メタデータのファセット名や属性名を変更または削除する場合は、そのテンプレートを使用するJSFページのみでなく、テンプレート定義のレイアウト・セクションで参照されているファセットや属性名を手動で変更または削除する必要があります。

例10-5 ページ・テンプレート定義のコンポーネント・メタデータ

<af:pageTemplateDef var="attrs">
<af:xmlContent>
<component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
<description/>
<display-name>sampleTemplateDef1</display-name>
<facet>
<facet-name>main</facet-name>
</facet>
.
.
.
<attribute>
<attribute-name>Title</attribute-name>
<attribute-class>java.lang.String</attribute-class>
<default-value>Replace title here</default-value>
<required>true</required>
</attribute>
.
.
.
</component>
</af:xmlContent>
.
.
.
</af:pageTemplateDef>

9. 「コンポーネント」ウィンドウで、コンポーネントをページにドラッグ・アンド・ドロップします。
ページ・テンプレートを使用するJSFページですでに使用されているため、ページ・テンプレート定義のレイアウト・セクション(またはレイアウト・セクションの一部を含むフラグメント・ファイル)では、f:viewタグを使用できません。

ベスト・プラクティスのヒント:

テンプレートには、documentまたはformタグを使用しないでください。理論上、テンプレート定義にdocumentおよびformタグを使用できますが、そうすると使用ページで使用できなくなります。ページ・テンプレートはページ・フラグメントに使用できるため、別のページに使用され、これらのタグが使用ページに含まれることになります。ページ・テンプレートにはdocumentタグを追加しないでください。

レイアウト・セクションには、コンポーネントをいくつでも追加できます。ただし、テンプレートには1つのルート・コンポーネントのみ必要です。クイック・スタート・レイアウトを使用しない場合、通常は、panelStretchLayoutまたはpanelGroupLayoutなどのパネル・コンポーネントを追加してから、そのパネル・コンポーネントにレイアウトを定義するコンポーネントを追加します。詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

宣言コンポーネントおよびデータ・バインドされたコンポーネントは、レイアウト・セクションで使用されます。宣言コンポーネントの使用の詳細は、10.5項「宣言コンポーネントの使用」を参照してください。ページ・テンプレート内のデータ・バインドされたコンポーネントの使用方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ・テンプレートの使用に関する項を参照してください。

10. 別のテンプレートをこのテンプレートにネストする場合は、「コンポーネント」ウィンドウで、「レイアウト」パネルの「コア構造」グループから「テンプレート」をドラッグしてページにドロップします。

注意:

ADFデータ・バインディングを使用しないテンプレートまたは宣言コンポーネントにADFデータバインドされたテンプレートをネストすることはできません。

また、ネストされたテンプレートはレンダリング当たり複数回使用することはできません。たとえば、表やツリーなど、その子にスタンプを設定するコンポーネントの子としては使用できません。

11. 「テンプレートの挿入」ダイアログで、ネストするテンプレートを選択します。

ヒント:

ダイアログには、現在のプロジェクトに含まれるか、ADFライブラリで提供されているすべてのテンプレートが表示されます。ADFライブラリの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

12. 「コンポーネント」ウィンドウで、「レイアウト」パネルの「コア構造」グループから「ファセット」をドラッグしてページにドロップします。
たとえば、ページ・テンプレートのメインのコンテンツ領域にmainファセットを定義した場合、panelStretchLayoutコンポーネントのcenterファセットにfacetRefタグを子として追加し、mainファセットを参照します。設計時、ページ作成者がmainファセットにコンテンツをドロップすると、そのコンテンツはテンプレートに定義されているように、ページの適切な場所に配置されます。

適切な名前付きファセットを参照するためにfacetRefタグを使用すると、JDeveloperにより「ファセットの挿入」ダイアログが表示されます。そのダイアログで、ドロップダウン・リストからファセット名を選択するか、ファセット名を入力します。ページ・テンプレート定義ファイルのコンポーネント・メタデータにまだ定義されていないファセット名を入力すると、JDeveloperにより、xmlContentタグ内のコンポーネント・メタデータに新しいファセット定義用のエントリが自動的に追加されます。

注意:

ページ・テンプレート定義のレイアウト・セクションで、各ファセットを参照できるのは一度のみです。つまり、同じテンプレート定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

注意:

このテンプレートに別のテンプレートをネストした場合は、ネストされたテンプレート内およびこのテンプレート内の各ファセットに対してファセット参照を作成する必要があります。

13. ページ・テンプレートのどこに属性を使用するかを指定するには、ページ・テンプレートのvar属性値を使用して、レイアウト・セクションの適切なコンポーネントにある関連する属性を参照します。

pageTemplateDefタグのvar属性では、ページ・テンプレートの独自の属性へのアクセスに使用するEL変数名を指定します。例10-5に示すように、JDeveloperにより使用されるvarのデフォルト値はattrsです。

たとえば、title属性を定義し、panelHeaderコンポーネントを追加した場合は、次のコードに示すように、panelHeaderコンポーネントのtext値にEL式#{attrs.title}を使用して、titleの値を参照します。

<af:panelHeader text="#{attrs.title}">

14. テンプレート・レイアウトに別のファイルを指定するには、次のコードに示すように、subviewタグでラップされたjsp:includeタグを使用してフラグメント・ファイルを参照します。

<f:subview id="secDecor">
<jsp:include page="fileExplorerSecondaryDecoration.jspx"/>
</f:subview>

指定されたフラグメント・ファイルも、階層の先頭にjsp:rootのみを含むXMLドキュメントである必要があります。フラグメントの使用方法の詳細は、10.4.3項「JSFページでのページ・フラグメントの使用方法」を参照してください。

コンポーネントにテンプレート・レイアウトを定義する複数のフラグメント・ファイルを作成し、ページ・テンプレート定義にフラグメント・ファイルを指定することにより、大規模なテンプレート・ファイルをメンテナンスしやすい小規模なファイルに分割できます。

10.3.2 ページ・テンプレートを作成する場合の処理

注意:

ページ・テンプレートのコンポーネントにADFモデル・データ・バインディングが使用されている場合、またはテンプレートの作成時にADFページ定義を関連付けることを選択した場合は、JDeveloperにより、ADFモデルに関連するファイルおよびフォルダが自動的に作成されます。ページ・テンプレートおよびADFモデル・データ・バインディングで使用されるファイルの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ・テンプレートの使用に関する項を参照してください。

初めてウィザードを使用してプロジェクトにページ・テンプレートを作成すると、pagetemplate-metadata.xmlファイルが自動的に作成されて、ファイルシステムの/ViewController/src/META-INFディレクトリに保存されます。

ウィザードを使用して定義する各ページ・テンプレートに対して、JDeveloperにより、ページ・テンプレート定義ファイル(sampleTemplateDef1.jspxなど)が作成され、pagetemplate-metadata.xmlファイルにエントリが追加されます。例10-6に、pagetemplate-metadata.xmlファイルの例を示します。

例10-6 pagetemplate-metadata.xmlファイルのサンプル

<pageTemplateDefs xmlns="http://xmlns.oracle.com/adf/faces/rich/pagetemplate">
<pagetemplate-jsp-ui-def>/sampleTemplateDef1.jspx</pagetemplate-jsp-ui-def>
<pagetemplate-jsp-ui-def>/sampleTemplateDef2.jspx</pagetemplate-jsp-ui-def>
</pageTemplateDefs>

注意:

「アプリケーション」ウィンドウでページ・テンプレートの名前の変更または削除を実行すると、JDeveloperにより、ファイル・システムのページ・テンプレート定義ファイルの名前の変更または削除が行われますが、pagetemplate-metadata.xmlファイルのページ・テンプレート・エントリは手動で変更または削除し、そのテンプレートを使用するJSFページを更新または削除する必要があります。

pagetemplate-metadata.xmlファイルには、プロジェクトに作成したすべてのページ・テンプレートの名前およびパスが含まれます。このファイルは、ウィザードを使用してテンプレートベースのJSFページを作成する場合、およびページ・テンプレート定義を含むプロジェクトをデプロイする場合に、使用可能なページ・テンプレートを判断するために使用されます。

10.3.3 ページ・テンプレートに基づくJSFページの作成方法

通常、JSFページは、ページ・テンプレート定義が作成および格納されているのと同じプロジェクトに作成します。テンプレートに基づくページの作成先となるプロジェクトにページ・テンプレートが存在しない場合は、まず、ページ・テンプレート・プロジェクトをADFライブラリJARファイルにデプロイします。プロジェクトのデプロイに関する詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。ページ・テンプレート・プロジェクトをデプロイすると、アプリケーションで作業している他の開発者とページ・テンプレートを共有できます。

注意:

テンプレートにjsp:includeタグが使用されている場合は、ADFライブラリにデプロイして別のアプリケーションで再利用することはできません。

ページ・テンプレートを使用して、JSFページまたはページ・フラグメントを作成できます。後からページ・テンプレートのレイアウト・セクションを変更すると、そのテンプレートを使用するすべてのページまたはページ・フラグメントがレイアウトの変更内容で自動的に更新されます。

テンプレートを使用するページで、pageTemplateタグの前後にコンテンツを追加できます。一般的に、pageTemplateタグはページに1つのみ使用しますが、複数使用することに対する制限はありません。

JDeveloperでは、「JSFページの作成」ウィザード、または「JSFページ・フラグメントの作成」ウィザードにテンプレートの選択オプションが用意されているため、ページ・テンプレートに基づくJSFページの作成が簡略化されます。

始める前に:

テンプレートに関する知識が役立つ場合があります。詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

ページ・テンプレートに基づくJSFページまたはページ・フラグメントを作成する手順:

1. 3.4.1項「JSFページの作成方法」の手順に従って、「JSFページの作成」ダイアログを開きます。ダイアログで、使用するページ・テンプレートを使用可能な選択肢から選択します。

ヒント:

「ADFページ・テンプレートの参照」を選択した場合、選択できるページ・テンプレートは、JDeveloperのテンプレート・ウィザードを使用して作成されたページ・テンプレートのみです。

ヒント:

テンプレートをページ全体のベースにするかわりに、ページの領域にテンプレートを使用できます。たとえば、ページのヘッダーでのみテンプレートを使用できます。テンプレートをページ内の領域に適用するには、「コンポーネント」ウィンドウの「レイアウト」パネルから、「テンプレート」をドラッグして目的のコンポーネントにドロップします。

デフォルトでは、JDeveloperにより、新しいページまたはページ・フラグメントがビジュアル・エディタに表示されます。ページ・テンプレートで定義されたファセットは、ビジュアル・エディタに名前付きボックスとして表示されます。ページ・テンプレートにデフォルト値が含まれる場合は、「プロパティ」ウィンドウにその値が表示され、デフォルト値にビジュアル表現(サイズなど)がある場合は、ページ・テンプレート定義のレイアウト・セクションで定義されたコンポーネントによってレンダリングされるコンテンツとともに、それがビジュアル・エディタに反映されます。

2. 構造ウィンドウで、(af:formの下の)af:pageTemplateが表示されるまでjsp:rootを開きます。
formタグ内で、pageTemplateタグの前後にコンテンツをドロップできます。

3. 「コンポーネント」ウィンドウからテンプレートのファセットにコンポーネントをドラッグ・アンド・ドロップして、コンポーネントを追加します。構造ウィンドウのaf:pageTemplate内に、ページ・テンプレート定義のコンポーネント・メタデータ・セクションに事前に定義されているファセット(f:facet - mainなど)が表示されます。
ファセットにドロップできるコンポーネントのタイプは、ページ・テンプレート定義のfacetRefタグの場所によって異なります。たとえば、facetRefタグがページ・テンプレート定義のtableコンポーネント内に配置されるよう定義した場合、tableコンポーネントに子として使用できるのはcolumnコンポーネントのみであるため、ファセットにドロップできるのはcolumnコンポーネントのみです。

ヒント:

テンプレート・ファセットにドロップするコンテンツには、ADFモデル・データ・バインディングが含まれている可能性があります。つまり、「データ・コントロール」パネルから項目をドラッグ・アンド・ドロップできます。ADFモデル・データ・バインディングの使用方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

4. 構造ウィンドウで、af:pageTemplateを選択します。これにより、「プロパティ」ウィンドウに、ページ・テンプレート定義に事前に定義されているすべての属性が表示されます。事前定義済の属性にはデフォルト値があります。
事前定義済の属性に静的値を割り当てることも、EL式(#{myBean.somevalue}など)を使用することもできます。属性に値を入力すると、JDeveloperによりコードにf:attributeタグが追加され、(存在する場合は)属性のデフォルト値が割り当てた値に置き換えられます(例10-7を参照)。

実行時、デフォルトまたは割り当てられた属性値が、属性名を参照するEL式(#{attrs.someAttributeName}など)によってページ・テンプレート定義に指定されているように、テンプレートの適切な部分に使用または表示されます。

注意:

事前定義済のテンプレート定義属性のみでなく、Id、ValueおよびViewIdなど、pageTemplateタグのその他の属性も「プロパティ」ウィンドウに表示されます。

pageTemplateタグのViewId属性では、実行時に使用ページで使用するページ・テンプレート定義ファイルを指定します。ウィザードを使用してテンプレート・ベースのJSFページを作成する場合、JDeveloperでは、ViewId属性に適切な値が自動的に割り当てられます。ViewId属性値は削除できません。削除するとランタイム・エラーが発生し、テンプレートに基づくページの部分がレンダリングされません。

5. CSSまたはJavaScriptなどのリソースを含めるには、af:resourceタグを使用する必要があります。詳細は、10.6項「ページへのリソースの追加」を参照してください。

10.3.4 テンプレートを使用してページを作成する場合の処理

テンプレートを使用してページを作成すると、JDeveloperにより、例10-7に示すように、ページ・テンプレート定義を参照するpageTemplateタグが挿入されます。テンプレートのファセットに追加されるコンポーネントでは、ファセットの参照にf:facetタグが使用されます。指定した属性値はすべて、f:attributeタグに表示されます。

例10-7 ページ・テンプレートを参照するJSFページ

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document>
<af:form>
.
.
.
<af:pageTemplate viewId="/sampleTemplateDef1.jspx" id="template1">
<f:attribute name="title" value="Some Value"/>
<f:facet name="main">
<!-- add contents here -->
</f:facet>
</af:pageTemplate>
.
.
.
</af:form>
</af:document>
</f:view>
</jsp:root>

10.3.5 実行時の処理: ページ・テンプレートが解決される仕組み

ページ・テンプレートを使用するJSFページが実行されると、次の処理が行われます。

- 使用ページのpageTemplateコンポーネントでは、viewId属性(<af:pageTemplate viewId="/sampleTemplateDef1.jspx"/>など)を使用して、テンプレート・コンポーネント・メタデータおよびレイアウトが含まれるページ・テンプレート定義ファイルが特定されます。

- pageTemplateDefタグのレイアウト・セクションに定義されたコンポーネント・サブツリーがインスタンス化され、ページのpageTemplateタグで識別される場所にある使用ページのコンポーネント・ツリーに挿入されます。

- 使用ページにより、ファセット・コンテンツがfacetタグを使用してテンプレートに渡されます。各facetタグのファセット・コンテンツは、pageTemplateDefタグのレイアウト・セクションにある対応するfacetRefタグで指定されているように、テンプレートの適切な場所に挿入されます。

- 使用ページにより、値がattributeタグを使用してテンプレートに渡されます。pageTemplateDefタグにより、pageTemplateタグが内部的に独自のパラメータを参照できるように、var属性の値が設定されます。pageTemplateタグにより設定されるのはパラメータのみで、それらのパラメータはランタイムによりpageTemplateDefタグに定義されている属性にマップされます。

- テンプレート・コンポーネント・メタデータを使用して、pageTemplateタグにより属性にデフォルト値が適用され、必要な値が確認されます。

注意:

ページ・テンプレートは、JSFの処理中ではなく、JSPの実行中(つまり、コンポーネント・ツリーの作成中)に処理されます。これは、コンポーネント・ツリーの作成が必要なタグ内に、ページ・テンプレートから作成されるフラグメントを使用できないことを意味します。たとえば、iteratorタグ内にテンプレートに基づいてフラグメントを含めることはできず、ループ内に含まれることになります。

ページ・テンプレートでADFモデル・データ・バインディングを使用した場合に起きることの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のページ・テンプレートの使用に関する項を参照してください。

10.3.6 ページ・テンプレートおよびネーミング・コンテナに関する必知事項

pageTemplateコンポーネントは、(テンプレート定義の直接のコンテンツであるか、jsp:includeアクションを使用して含められるフラグメント・コンテンツであるかに関係なく)テンプレートのすべてのコンテンツのネーミング・コンテナとして機能します。テンプレート・ベースのページで作業している場合は、ページ・テンプレートの内部の個々のコンポーネントを参照しないでください。ページ・テンプレートまたはその使用ページに加えられた変更は、部分トリガーが不適切に動作する原因となることがあります。詳細は、6.3.8項「ネーミング・コンテナの使用に関する必知事項」を参照してください。

10.4 ページ・フラグメントの使用

アプリケーションのWebページを作成して短時間で、一部のページが大規模で管理不能になることがあります。複雑なページの作成およびメンテナンスのプロセスを簡略化する1つの方法は、ページ・フラグメントの使用です。

大規模で複雑なページを複数の小規模なページ・フラグメントに分割すると、メンテナンスしやすくなります。ページの設計方法によっては、あるページに作成されたページ・フラグメントを別のページで再利用できます。たとえば、複数ページの異なる部分に同じフォームを使用する場合、フォームにそれらのコンポーネントを含むページ・フラグメントを作成し、それらのページ・フラグメントをいくつかのページに再利用すると便利です。1つ以上の複雑なページにページ・フラグメントをいくつ作成するかの判断は、アプリケーション、ページの一部を複数のページで再利用する程度、および複雑なページを簡略化する要望によって異なります。

ページ・フラグメントは不完全なJSFページです。ADF Facesを使用する完全なJSFページでは、documentタグがf:viewタグで囲まれている必要があります。ページ全体のコンテンツは、documentタグで囲まれます。一方、ページ・フラグメントは完全なページの一部を表し、f:viewまたはdocumentタグを含みません。ページ・フラグメントのコンテンツは、jsp:rootタグで囲まれます。

ページ・フラグメントを使用してJSFページを作成する際には、ページの異なる部分を定義する1つ以上のページ・フラグメントを使用できます。同じページ・フラグメントを、1つのページで複数回使用することも、複数のページで使用することもできます。

注意:

ページのすべてのview部分(フラグメント、宣言コンポーネントおよびメイン・ページ)では、同じリクエスト・スコープが共有されます。このため、1つのページに同じフラグメントまたは宣言コンポーネントを複数回使用すると競合が発生し、そのフラグメントまたはコンポーネントでバッキングBeanが共有されます。スコープの詳細は、5.6項「オブジェクト・スコープ・ライフサイクル」を参照してください。

たとえば、File Explorerアプリケーションには、次のページ・フラグメントを含むメイン・ページ(index.jspx)が1つ使用されています。

- popups.jspx: アプリケーションで使用されるすべてのポップアップ・コードが含まれます。

- help.jspx: ヘルプ・コンテンツが含まれます。

- header.jspx: アプリケーションのツールバーおよびメニューが含まれます。

- navigators.jspx: アプリケーションのノード階層を表示するツリーが含まれます。

- contentViews.jspx: ナビゲーション・ペインで選択されたノードのコンテンツが含まれます。

例10-8に、含まれるheader.jspxページ・フラグメントの省略形のコードを示します。f:viewまたはdocumentタグが含まれていないことに注意してください。

例10-8 header.jspxページ・フラグメント

<?xml version='1.0' encoding='UTF-8'?>
<ui:composition xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:f="http://java.sun.com/jsf/core">
<af:panelStretchLayout id="headerStretch">
<f:facet name="center">
<!-- By default, every toolbar is placed on a new row -->
<af:toolbox id="headerToolbox"
binding="#{explorer.headerManager.headerToolbox}">
.
.
.
</af:toolbox>
</f:facet>
</af:panelStretchLayout>
</ui:composition>

JSFページでページ・フラグメントを使用する場合は、index.jspxページの省略形のコードである例10-9に示すように、ページ・フラグメント・コンテンツを使用するページの部分に、jsp:includeタグを挿入し、必要なページ・フラグメント・ファイルを指定します。

例10-9 フラグメントを含むFile Explorerの索引JSFページ

<?xml version='1.0' encoding='utf-8'?>
<ui:composition xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:trh="http://myfaces.apache.org/trinidad/html">
<jsp:directive.page contentType="text/html;charset=utf-8"/>
<f:view>
.
.
.
<af:document id="fileExplorerDocument"
title="#{explorerBundle['global.branding_name']}">
<af:form id="mainForm">
<!-- Popup menu definition -->
<jsp:include page="/fileExplorer/popups.jspx"/>
<jsp:include page="/fileExplorer/help.jspx"/>
.
.
.
<f:facet name="header">
<af:group>
<!-- The file explorer header with all the menus and toolbar buttons -->
<jsp:include page="/fileExplorer/header.jspx"/>
</af:group>
</f:facet>
<f:facet name="navigators">
<af:group>
<!-- The auxiliary area for navigating the file explorer -->
<jsp:include page="/fileExplorer/navigators.jspx"/>
</af:group>
</f:facet>
<f:facet name="contentViews">
<af:group>
<!-- Show the contents of the selected folder in the folders navigator -->
<jsp:include page="/fileExplorer/contentViews.jspx"/>
</af:group>
</f:facet>
.
.
.
</af:form>
</af:document>
</f:view>
</ui:composition>

ページ・フラグメントを変更する場合、ページ・フラグメントを使用するページは、変更によって自動的に更新されます。ページ・フラグメントから作成されたページでは、レイアウトを変更すると、ページ・フラグメントのみの変更では不十分である可能性が非常に高くなります。ページ・フラグメントを使用するすべてのページも変更することが必要な場合があります。

注意:

使用ページでADFモデル・データ・バインディングが使用されている場合、含まれるページ・フラグメントでは、使用ページのバインディング・コンテナが使用されます。ADFの無制限タスク・フローの一部として作成されたページ・フラグメントにのみ、独自のバインディング・コンテナを使用できます。ADFバインド・タスク・フローの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFタスク・フローの概要」の章を参照してください。

例10-10に示すように、完全なJSFページ同様、ページ・フラグメントもページ・テンプレートをベースにすることができます。ページ・テンプレートの作成および適用方法の詳細は、10.3項「ページ・テンプレートの使用」および10.3.3項「ページ・テンプレートに基づくJSFページの作成方法」を参照してください。

例10-10 テンプレートに基づくページ・フラグメント

<?xml version='1.0' encoding='UTF-8'?>
<ui:composition xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:f="http://java.sun.com/jsf/core">
<af:pageTemplate viewId="/someTemplateDefinition.jspx">
.
.
.
</af:pageTemplate>
</ui:composition>

10.4.1 ページ・フラグメントの作成方法

ページ・フラグメントはJSFページと同様ですが、ページ・フラグメントではf:viewまたはdocumentタグを使用しない点が異なります。JSFページ・フラグメントの作成ウィザードを使用して、ページ・フラグメントを作成できます。ウィザードを使用してページ・フラグメントを作成する場合、JDeveloperはページ・フラグメント・ファイルに拡張子.jsffを使用します。ウィザードを使用しない場合は、(File Explorerアプリケーションと同様に)ファイル拡張子として.jspxを使用できます。JDeveloperの「アプリケーション」ウィンドウで作業しているときに完全なJSFページとページ・フラグメントを迅速に区別できること以外に、.jsffを使用する特別な理由はありません。

始める前に:

フラグメントに関する知識が役立つ場合があります。詳細は、10.4項「ページ・フラグメントの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

ページ・フラグメントを作成する手順:

1. 「アプリケーション」ウィンドウで、ページ・テンプレートを作成して保存するノードを右クリックし、「新」→「ADFページ・フラグメント」を選択します。

2. 「ADFページ・フラグメントの作成」ダイアログで、ページ・フラグメント・ファイルの名前を入力します。

3. ページ・フラグメント用のデフォルトのディレクトリをそのまま使用するか、新しい場所を選択します。
JDeveloperでは、デフォルトで、ファイルシステム内のプロジェクトの/public_htmlディレクトリにページ・フラグメントが保存されます。たとえば、デフォルトのディレクトリを/public_html/fragmentsに変更できます。

4. ADFページ・テンプレートまたはクイック・スタート・レイアウトを使用してフラグメントを事前に設計することも、空白のページから始めることもできます。

- ページ・テンプレートに基づいてページ・フラグメントを作成する場合は、「ADFページ・テンプレートの参照」ラジオ・ボタンを選択し、ドロップダウン・リストからテンプレート名を選択します。ページ・テンプレートの使用の詳細は、10.3.3項「ページ・テンプレートに基づくJSFページの作成方法」を参照してください。

- クイック・スタート・レイアウトを使用する場合は、「クイック・スタート・レイアウトのコピー」ラジオ・ボタンを選択し、フラグメントで使用するレイアウトを参照して選択します。クイック・スタート・レイアウトには、特定の動作および外観を得るために必要な正確に構成されたレイアウト・コンポーネントが用意されています。詳細は、9.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

ページ・フラグメントの作成が完了すると、JDeveloperにより、ビジュアル・エディタにページ・フラグメント・ファイルが表示されます。

5. ページ・フラグメントのコンテンツを定義するには、「コンポーネント」ウィンドウから必要なコンポーネントをドラッグしてページにドロップします。
table、panelHeaderまたはf:facetなど、任意のADF Facesコンポーネントまたは標準のJSFコンポーネントを使用できます。

例10-11に、menuコンポーネントを含むページ・フラグメントの例を示します。

例10-11 ページ・フラグメントのサンプル

<?xml version='1.0' encoding='UTF-8'?>
<ui:composition xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:pageTemplate viewId="/MytemplateDef1.jspx" id="pt1">
<!-- page fragment contents start here -->
<af:menu id="viewMenu"
<af:group>
<af:commandMenuItem type="check" text="Folders"/>
<af:commandMenuItem type="check" text="Search"/>
</af:group>
<af:group>
<af:commandMenuItem type="radio" text="Table"/>
<af:commandMenuItem type="radio" text="Tree Table"/>
<af:commandMenuItem type="radio" text="List"/>
</af:group>
<af:commandMenuItem text="Refresh"/>
</menu>
</ui:composition>

10.4.2 ページ・フラグメントを作成する場合の処理

JDeveloperでは、ページ・フラグメント・ファイルは通常のJSFページとは異なるファイル拡張子を使用するため、アプリケーション内の.jsffファイルを認識および解釈するための構成エントリがweb.xmlファイルに追加されます。例10-12に、ウィザードを使用してページ・フラグメントを初めて作成するときにJDeveloperによって追加される、.jsffファイルに必要なweb.xml構成エントリを示します。

例10-12 .jsffファイルを認識および解析するためのweb.xmlのエントリ

<jsp-config>
<jsp-property-group>
<url-pattern>*.jsff</url-pattern>
<is-xml>true</is-xml>
</jsp-property-group>
</jsp-config>

*.jsffにurl-patternサブ要素を指定し、jsp-property-group要素のis-xmlサブ要素をtrueに設定することで、アプリケーションは拡張子が.jsffのファイルが実際はJSPドキュメントであることを認識します。そのため、このファイルは、XMLドキュメントとして解析される必要があります。

10.4.3 JSFページでのページ・フラグメントの使用方法

JSFページ内でページ・フラグメントを使用するには、「コンポーネント」ウィンドウまたは「アプリケーション」ウィンドウを使用してページを追加します。

10.4.3.1 「コンポーネント」ウィンドウを使用したページ・フラグメントの追加

jsp:includeタグを使用して、目的のページ・フラグメント・ファイルを含めることができます。

始める前に:

フラグメントに関する知識が役立つ場合があります。詳細は、10.4項「ページ・フラグメントの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

「コンポーネント」ウィンドウを使用してページ・フラグメントを追加するには:

1. 「コンポーネント」ウィンドウの「JSP」ページで、「含める」をドラッグしてページにドロップします。

2. 「インクルードの挿入」ダイアログでドロップダウン・リストを使用して、含めるJSFページを選択します。オプションで、ページが含まれる前にバッファをフラッシュするかどうかを選択します。ダイアログのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

10.4.3.2 「アプリケーション」ウィンドウを使用したページ・フラグメントの追加

ページ・フラグメントをページに直接ドラッグ・アンド・ドロップできます。

始める前に:

フラグメントに関する知識が役立つ場合があります。詳細は、10.4項「ページ・フラグメントの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

「アプリケーション」ウィンドウを使用してページ・フラグメントを追加するには:

1. 「アプリケーション」ウィンドウで、ページ・フラグメントをページにドラッグ・アンド・ドロップします。

2. 「Subview要素追加の確認」ダイアログで、「はい」をクリックします。

10.4.4 実行時の処理: ページ・フラグメントが解決される仕組み

組込みページを含むページが実行されると、JSFツリー・コンポーネントの作成時に、jsp:includeタグによりビューIDが検証され、親ページのjsp:includeタグの場所にコンテンツが動的に追加されます。コンポーネント・ツリーが作成されると、フラグメントは親ページの一部になります。

10.5 宣言コンポーネントの使用

宣言コンポーネントは、その他の既存のADF Facesコンポーネントで構成される再利用可能なコンポジットUIコンポーネントです。様々な状況で、同じコンポーネントを繰り返し再利用しているとします。一般的に使用されるUI要素を繰り返しコピーして貼り付けるかわりに、それらのコンポーネントを構成する宣言コンポーネントを定義し、そのコンポジット宣言コンポーネントを複数の場所またはページに再利用できます。

注意:

ADFモデル・レイヤー・バインディングを属性の値として使用する場合は、かわりにページ・テンプレートを使用する必要があります。詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

アプリケーションに宣言コンポーネントを使用するには、まず、XML構文で記述されたJSFドキュメントであるXMLベースの宣言コンポーネント定義(ファイル拡張子は.jspx)を作成します。宣言コンポーネントJSFファイルには、f:viewおよびdocumentタグが含まれず、ルート・タグとしてcomponentDefが必要です。

宣言コンポーネントの完全な説明は、2つのセクション内に定義されています。1つのセクションはxmlContentで、宣言コンポーネントのサポートされているコンテンツ領域を説明するすべてのページ・テンプレート・コンポーネント・メタデータが含まれています。宣言コンポーネントのメタデータには次のものが含まれます。

- ファセット: ファセットは、宣言コンポーネントを構成する個々のコンポーネントに最終的に配置されるコンテンツのプレースホルダとして機能します。各コンポーネントは1つのファセットを参照します。ページ・デザイナは、宣言コンポーネントを使用する場合に、コンテンツをファセットに挿入し、コンテンツをコンポーネントに挿入できます。

ヒント:

ファセットは、宣言コンポーネント内でコンテンツを含むことのできる唯一の領域です。つまり、JSFページに使用した場合、宣言コンポーネントに子がない可能性もあります。コンテンツが必要なすべての領域にファセットを作成します。

- 属性: 個々のコンポーネントに属性を移入するために値を使用できる属性を定義します。たとえば、宣言コンポーネントにpanelBoxコンポーネントが使用されている場合に、Titleという名前の属性を作成するとします。次に、Title属性の値が、panelBoxコンポーネントのtext属性の値として使用されるように宣言コンポーネントを設計します。ユーザーがオーバーライドできる属性にデフォルト値を指定できます。

ヒント:

宣言コンポーネントのユーザーは、個々のコンポーネントに直接属性を設定できないため、ユーザーによる設定またはデフォルト値のオーバーライドが可能なすべての属性に、必ず属性を作成する必要があります。

また、宣言コンポーネントでクライアント側の属性(attributeDragSourceなど)を使用できるようにする場合は、その属性を作成し、宣言コンポーネントで使用される適切なコンポーネントに子として含める必要があります。詳細は、10.5.1項「宣言コンポーネントの作成方法」を参照してください。

- メソッド: 組み込まれるコンポーネントのいずれかにあるプロパティをバインドできるメソッドを定義できます。たとえば、宣言コンポーネントにボタンが含まれる場合、メソッド名およびシグネチャを宣言し、actionListener属性をその宣言済メソッドにバインドできます。ページ開発者が宣言コンポーネントを使用する際には、コンポーネントに必要なロジックが含まれるマネージドBeanのメソッドにリバインドします。
たとえば、宣言コンポーネントに、actionEventメソッドを起動する必要があるボタンが含まれるとします。シグネチャvoid method(javax.faces.event.ActionEvent)を使用するmethod1という名前の宣言メソッドを作成します。次に、ボタンのactionListener属性を、宣言済メソッドにバインドします。ページ開発者が宣言コンポーネントを使用する際には、JDeveloperにより、同じシグネチャを使用するバッキングBeanにメソッドを指定するよう求められます。

- タグ・ライブラリ: すべての宣言コンポーネントは、アプリケーションで使用するためにインポートするタグ・ライブラリに含まれている必要があります。

2つ目のセクション(xmlContentタグの外)は、宣言コンポーネントを構成するすべてのコンポーネントが定義される部分です。各コンポーネントには、コンポーネントへのコンテンツの追加に使用されるファセットへの参照が含まれます。

プロジェクトで宣言コンポーネントを使用するには、まず、宣言コンポーネントを含むライブラリをADFライブラリとしてデプロイする必要があります。次に、デプロイされたADFライブラリJARファイルをプロジェクトのプロパティに追加します。これにより、1つまたは複数のJSPタグ・ライブラリがプロジェクトのプロパティに自動的に挿入されます。そうすると、そのコンポーネントが「コンポーネント」ウィンドウに表示されるようになり、それをJSFページにドラッグ・アンド・ドロップできます。

たとえば、panelBoxコンポーネントを使用する宣言コンポーネントを作成するとします。panelBoxコンポーネントのツールバーに、バッキングBeanのactionEventメソッドの起動に使用できる3つのボタンを含めるとします。これを実行するには、次のものを作成します。

- panelBoxコンポーネントのコンテンツを保持するためのcontentという名前のファセットを1つ。

- panelBoxコンポーネントのタイトルとして表示するテキストを決定するTitleという名前の属性を1つ。

- 各ボタンに表示するテキストを決定する属性を3つ(各ボタンに1つずつで、buttonText1、buttonText2およびbuttonText3という名前)。

- ボタンをレンダリングするかどうかを決定する属性を3つ(各ボタンに1つずつで、display1、display2およびdisplay3という名前)。これは、コンポーネントが使用されるたびに3つのボタンすべてが必要であるかどうかがわからないためです。

- それぞれがactionEventメソッド・シグネチャを使用する宣言メソッドを3つ(各ボタンに1つずつで、method1、method2およびmethod3という名前)。

- text属性が作成したTitle属性にバインドされ、contentファセットを参照するpanelBoxコンポーネントを1つ。

- 3つのButtonコンポーネント。それぞれのtext属性は対応するbuttonText属性に、render属性は対応するdisplay属性に、actionListener属性は対応するmethod名にバインドされます。

図10-2に、このような宣言コンポーネントがビジュアル・エディタでどのように表示されるかを示します。

図10-2 ビジュアル・エディタの宣言コンポーネント

ページ開発者が必要な属性またはメソッドを含む宣言コンポーネントをページにドロップすると、値を要求するダイアログが開きます。

開発者がレンダリングされる初めの2つのボタンにのみ値を設定し、出力テキストを含むpanelGroupLayoutコンポーネントを追加した場合、ページは図10-3のようにレンダリングされます。

図10-3 表示される宣言コンポーネント

注意:

宣言コンポーネントのコンポーネント・レイアウトには、フラグメントまたはADFのデータ・バインドされたコンポーネントは使用できません。いくつかのコンポーネントをADFモデル・レイヤーにバインドする必要がある場合は、バインド先のコンポーネント属性用に属性を作成します。宣言コンポーネントのユーザーは、それらの属性をADFモデル・レイヤーに手動でバインドできます。

また、宣言コンポーネントは外部のJARファイルで送信され、参照ファイルを見つけられないため、jsp:includeタグを使用できません。

宣言コンポーネントに、CSSに定義されているカスタム・スタイルまたはJavaScriptなどのリソースが必要な場合は、af:resourceタグを使用して、使用ページにそれらのリソースを含める必要があります。詳細は、10.6項「ページへのリソースの追加」を参照してください。

10.5.1 宣言コンポーネントの作成方法

JDeveloperは、ファセットを作成し、宣言コンポーネントの属性とメソッドを定義できる「ADF宣言コンポーネントの作成」ウィザードを提供することで、宣言コンポーネント定義の作成を簡略化します。ウィザードでは、宣言コンポーネントのタグ・ライブラリ情報について記述するメタデータもcomponent-extensionタイルに作成されます。タグ・ライブラリ・メタデータは、宣言コンポーネントのJSPタグ・ライブラリの作成に使用されます。

まず、componentDefタグのxmlContentセクション内にあるファセットおよび属性に、テンプレート・コンポーネント・メタデータを追加します。ファセットおよび属性に必要なコンポーネント・メタデータをすべて追加したら、xmlContentの外のセクションに、宣言コンポーネントの実際のレイアウトを定義するコンポーネントを追加します。

ベスト・プラクティスのヒント:

宣言コンポーネントのタグ・ライブラリ定義(TLD)はコンポーネントを使用する前に生成する必要があるため、使用される前にコンポーネントをJARファイルにデプロイする必要があります。宣言コンポーネントのみが含まれるアプリケーションを作成することをお薦めします。これにより、単一ライブラリのすべての宣言コンポーネントをデプロイして、複数のアプリケーションで使用できます。

始める前に:

宣言コンポーネントに関する知識が役立つ場合があります。詳細は、10.5項「宣言コンポーネントの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

宣言コンポーネント定義を作成する手順:

1. 「アプリケーション」ウィンドウで、宣言コンポーネントを作成して保存するノードを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「JSF/Facelets」、「ADF宣言コンポーネント」の順に選択し、「OK」をクリックします。

3. 「ADF宣言コンポーネントの作成」ダイアログで、宣言コンポーネントの名前とファイル名を入力します。
ここで指定した名前は、「コンポーネント」ウィンドウにおける宣言コンポーネントの表示名、およびコンポーネント・タグ用に生成されたJavaクラスの名前として使用されます。宣言コンポーネントの名前に使用できるのは、SampleNameやmyPanelBoxのような英数字のみです。

ファイル名は、宣言コンポーネント定義ファイル(componentDef1.jspxなど)の名前です。宣言コンポーネント定義ファイルはXMLドキュメントである必要があるため、JDeveloperでは、デフォルトで.jspxがファイル拡張子として使用されます。

4. 宣言コンポーネント用のデフォルトのディレクトリ名をそのまま使用するか、新しい場所を選択します。
JDeveloperでは、デフォルトで、ファイルシステムの/ViewController/public_htmlディレクトリに宣言コンポーネント定義が保存されます。たとえば、すべての宣言コンポーネント定義を/View Controller/public_html/declcompsディレクトリに保存できます。

5. パッケージ名(dcomponent1など)を入力します。JDeveloperでは、宣言コンポーネントのJavaクラスの作成時にパッケージ名が使用されます。

6. 新しい宣言コンポーネントを含むタグ・ライブラリを選択します。タグ・ライブラリが存在しない場合、または新しいライブラリを作成する場合は、「タグ・ライブラリの追加」をクリックし、次の操作を実行してタグ・ライブラリのメタデータを作成します。

1. 宣言コンポーネントを格納するJSPタグ・ライブラリの名前(dcompLib1など)を入力します。

2. タグ・ライブラリのURI(/dcomponentLib1など)を入力します。

3. タグ・ライブラリに使用する接頭辞(dcなど)を入力します。

7. 宣言コンポーネントへのカスタム・ロジックの追加を可能にする場合は、「カスタム・コンポーネント・クラスの使用」チェック・ボックスを選択してクラス名を入力します。

8. 名前付きファセットを追加するには、「ファセット定義」タブをクリックし、「追加」アイコンをクリックします。
宣言コンポーネントのファセットは、コンテンツを最終的に挿入できる事前定義済の領域です。宣言コンポーネントを作成するために使用するコンポーネントはファセットを参照します。ページ開発者は、宣言コンポーネントを使用する場合、コンテンツをファセットに配置し、コンテンツを個々のコンポーネントに配置できます。各ファセットには一意の名前が必要です。たとえば、宣言コンポーネントにpanelBoxコンポーネントがある場合は、panelBoxコンポーネントのコンテンツ領域にbox-mainという名前のファセットを定義できます。

9. 属性を追加するには、「属性」をクリックし、「追加」をクリックします。
属性は、宣言コンポーネントに渡すことのできるUIコンポーネント属性です。各属性には名前とクラス・タイプが必要です。使用可能なクラス・タイプは、java.lang.String、int、booleanおよびfloatです。デフォルト値を割り当て、「必須」チェック・ボックスを選択することで、値が必須であることを指定できます。

ヒント:

ユーザーが値の設定や変更を行える組込みコンポーネントの属性用に属性を作成する必要があります。

ドラッグ・アンド・ドロップ機能に使用されるattributeDragSourceタグに必要な値など、コンポーネントの機能をサポートするために追加が必要なタグにも属性を追加してください。

10. 宣言メソッドを追加するには、「メソッド」タブをクリックし、「追加」アイコンをクリックします。
宣言メソッドでは、コマンド・コンポーネント・アクションまたはアクション・リスナーをメソッド・シグネチャにバインドできます。これは、後でコンポーネントが使用されるページのバッキングBeanに同じシグネチャの実際のメソッドに解決されます。参照(...)アイコンをクリックして、シグネチャを検索および作成できる「メソッド・シグネチャ」ダイアログを開きます。

ダイアログを完了すると、JDeveloperにより、ビジュアル・エディタに宣言コンポーネント定義ファイルが表示されます。

ヒント:

宣言コンポーネントを作成したら、構造ウィンドウでcomponentDefタグを選択するか、「プロパティ」ウィンドウを使用して、ファセットと属性を追加できます。

11. 「コンポーネント」ウィンドウで、コンポーネントを構造ウィンドウ内のcomponentDefタグの子としてドラッグ・アンド・ドロップします。
panelBoxコンポーネントをドロップしたとします。構造ウィンドウでは、JDeveloperにより、xmlContentタグの後ろにコンポーネントが追加されます。xmlContentタグの前後のどこにレイアウトするコンポーネントを配置するかは問題ではありませんが、一貫性を保つことをお薦めします。

宣言コンポーネントのコンポーネント・レイアウトには、任意の数のコンポーネントを使用できます。通常、panelFormLayoutまたはpanelGroupLayoutなどのコンポーネントを追加してから、そのパネル・コンポーネントにレイアウトを定義するコンポーネントを追加します。

注意:

宣言コンポーネントのコンポーネント・レイアウトには、フラグメントまたはADFのデータ・バインドされたコンポーネントは使用できません。いくつかのコンポーネントをADFモデル・レイヤーにバインドする必要がある場合は、それらのコンポーネント属性用に属性を作成します。宣言コンポーネントのユーザーは、それらの属性をADFモデル・レイヤーに手動でバインドできます。ADFモデル・レイヤーの使用方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「Fusion WebアプリケーションでのADFモデルの使用」の章を参照してください。

また、宣言コンポーネントは外部のJARファイルで送信され、参照ファイルを見つけられないため、jsp:includeタグを使用できません。

12. ページ作成者がコンポーネントを使用してコンテンツを挿入できる(レイアウト・セクション内の)コンポーネントで、facetRefタグを使用して適切な名前付きファセットを参照します。
たとえば、メインのコンテンツ領域にcontentファセットを定義した場合、panelBoxコンポーネントにfacetRefタグを子として追加し、contentファセットを参照します。設計時、ページ開発者がcontentファセットにコンポーネントをドロップすると、そのコンポーネントはpanelBoxコンポーネントに配置されます。

「コンポーネント」ウィンドウの「コア構造」パネルから「ファセット」をドラッグしてページ内の目的の場所にドロップすると、「ファセット定義の挿入」ダイアログが表示されます。そのダイアログで、ドロップダウン・リストからファセット名を選択するか、ファセット名を入力して、「OK」をクリックします。定義ファイルのコンポーネント・メタデータにまだ定義されていないファセット名を入力すると、JDeveloperにより、xmlContentタグ内のコンポーネント・メタデータに新しいファセット定義用のエントリが自動的に追加されます。

注意:

各ファセットを参照できるのは一度のみです。つまり、同じ宣言コンポーネント定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

13. 宣言コンポーネントのどこに属性を使用するかを指定するには、「プロパティ」ウィンドウと式ビルダーを使用して、作成した属性にコンポーネントの属性値をバインドします。

たとえば、Title属性を定義し、panelBoxをコンポーネントとして追加した場合は、図10-4に示すように、「プロパティ」ウィンドウでテキスト属性の隣にあるドロップダウン・メニューを使用して式ビルダーを開きます。

図10-4 「プロパティ」ウィンドウにおける属性の式ビルダーの起動

式ビルダーで、スコープ内変数→attrsノードを開くと、「プロパティ」ウィンドウで属性の値に使用できる作成済の属性を選択できます。たとえば、図10-5は、式ビルダーで選択されたTitle属性を示しています。式を属性の値として追加する場合は、「OK」をクリックします。

図10-5 式ビルダーに表示されている作成済の属性

14. 宣言コンポーネント内のボタンで起動するメソッドを指定するには、そのコンポーネントのactionListener属性の隣にあるドロップダウン・メニューを使用し、「編集」を選択して「プロパティの編集」ダイアログを開きます。このダイアログを使用すると、宣言コンポーネントに作成した宣言メソッドのいずれかを選択できます。
ダイアログで「宣言コンポーネント・メソッド」を選択し、ドロップダウン・リストから宣言メソッドを選択して「OK」をクリックします。

10.5.2 宣言コンポーネントを作成する場合の処理

「ADF宣言コンポーネントの作成」ウィザードを初めて使用する際には、ウィザードに入力した名前を使用してメタデータ・ファイルが作成されます。コンポーネントのすべての定義は、componentDefタグに含まれています。このタグでは2つの属性が使用されます。1つ目はvarで、属性値にアクセスするために個々のコンポーネントにより使用される変数です。デフォルトで、varの値はattrsです。2つ目の属性はcomponentVarで、メソッドにアクセスするために個々のコンポーネントにより使用される変数です。componentVarがcomponentに設定されている場合は、JSF 2.0と互換性がなく、式がエラーになります。別の変数を使用してcomponentVarを設定する必要があります。

ファセット、属性およびメソッドを説明するメタデータは、xmlContentタグに含まれます。ファセット情報はfacetタグに、属性情報はattributeタグに、メソッド情報はライブラリ情報同様にcomponent-extensionタグに含まれます。例10-13に、図10-2に示されている宣言コンポーネントの省略形のコードを示します。

例10-13 xmlContentタグの宣言コンポーネント・メタデータ

<af:xmlContent>
<component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
<display-name>myPanelBox</display-name>
<facet>
<description>Holds the content in the panel box</description>
<facet-name>content</facet-name>
</facet>
<attribute>
<attribute-name>Title</attribute-name>
<attribute-class>java.lang.String</attribute-class>
<required>true</required>
</attribute>
<attribute>
<attribute-name>buttonText1</attribute-name>
<attribute-class>java.lang.String</attribute-class>
</attribute>
. . .
<component-extension>
<component-tag-namespace>dcomponent1</component-tag-namespace>
<component-taglib-uri>/componentLib1</component-taglib-uri>
<method-attribute>
<attribute-name>method1</attribute-name>
<method-signature>
void method(javax.faces.event.ActionEvent)
</method-signature>
</method-attribute>
<method-attribute>
<attribute-name>method2</attribute-name>
<method-signature>
void method(javax.faces.event.ActionEvent)
</method-signature>
</method-attribute>
. . .
</component-extension>
</component>
</af:xmlContent>

組込みコンポーネントのメタデータは、xmlContentタグの後ろに含まれます。これらのコンポーネントのコードは、コンポーネントに直接設定した属性値を含み、標準JSFページのものと同じです。属性またはメソッドに作成したバインドでは、バインドにコンポーネントの変数が使用されます。例10-14に、ツールバーに3つのボタンがあるpanelBoxコンポーネントのコードを示します。facetRefタグがpanelBoxコンポーネントの子であるため、ページ開発者が追加するすべてのコンテンツがpanelBoxコンポーネントの子になることに注意してください。

例10-14 宣言コンポーネント内のコンポーネント

<af:panelBox text="#{attrs.Title}" inlineStyle="width:25%;">
<f:facet name="toolbar">
<af:group>
<af:toolbar>
<af:button text="#{attrs.buttonText1}"
actionListener="#{component.handleMethod1}"
rendered="#{attrs.display1}"/>
<af:button text="#{attrs.buttonText2}"
rendered="#{attrs.display2}"
actionListener="#{component.handleMethod2}"/>
<af:button text="#{attrs.buttonText3}"
rendered="#{attrs.display3}"
actionListener="#{component.handleMethod3}"/>
</af:toolbar>
</af:group>
</f:facet>
<af:facetRef facetName="content"/>
</af:panelBox>

初めてウィザードを使用してプロジェクトに宣言コンポーネントを作成する際には、JDeveloperにより、ファイルシステムの/ViewController/src/META-INFディレクトリに格納されるdeclarativecomp-metadata.xmlファイルが自動的に作成されます。

ウィザードを使用して定義する各宣言コンポーネントに対して、JDeveloperにより、宣言コンポーネント定義ファイル(componentDef1.jspxなど)が作成され、declarativecomp-metadata.xmlファイルにエントリが追加されます。例10-15に、declarativecomp-metadata.xmlファイルの例を示します。

例10-15 declarativecomp-metadata.xmlファイルのサンプル

<declarativeCompDefs
xmlns="http://xmlns.oracle.com/adf/faces/rich/declarativecomp">
<declarativecomp-jsp-ui-def>
/componentDef1.jspx
</declarativecomp-jsp-ui-def>
<declarativecomp-taglib>
<taglib-name>
dcompLib1
</taglib-name>
<taglib-uri>
/componentLib1
</taglib-uri>
<taglib-prefix>
dc
</taglib-prefix>
</declarativecomp-taglib>
</declarativeCompDefs>

注意:

「アプリケーション」ウィンドウで宣言コンポーネントの名前の変更または削除を実行すると、JDeveloperにより、ファイルシステムの宣言コンポーネント定義ファイルの名前の変更または削除が行われますが、declarativecomp-metadata.xmlファイルの宣言コンポーネント・エントリは、手動で変更または削除して、その宣言コンポーネントを使用するJSFページを更新または削除する必要があります。

declarativecomp-metadata.xmlファイルには、プロジェクトに作成したすべての宣言コンポーネントの名前、パスおよびタグ・ライブラリの情報が含まれます。プロジェクトのデプロイ時には、JDeveloperによりメタデータが使用され、宣言コンポーネントのJSPタグ・ライブラリおよびJavaクラスが作成されます。

JDeveloperは、faces-config.xmlファイルにエントリも追加します。

10.5.3 宣言コンポーネントのデプロイ方法

宣言コンポーネントを表示するには、タグ・ライブラリ定義(TLD)が必要です。プロジェクトをデプロイすると、JDeveloperにより自動的にTLDが生成されます。このため、宣言コンポーネントを使用するには、まず、宣言コンポーネントを含むプロジェクトをデプロイする必要があります。これは、プロジェクトに宣言コンポーネントを使用する前、または他の開発者と宣言コンポーネントを共有する前に、ADFライブラリJARファイルに宣言コンポーネント定義プロジェクトをデプロイする必要があることを意味します。ADFライブラリJARファイルにプロジェクトを展開する手順は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

簡単に説明すると、宣言コンポーネント定義を含むプロジェクトをデプロイすると、JDeveloperにより次の項目がADFライブラリJARファイルに追加されます。

- 各宣言コンポーネント定義(つまり、各componentDefコンポーネント)用のコンポーネント・タグ・クラス(componentDef1Tag.classなど)

- プロジェクトdeclarativecomp-metadata.xmlファイルの情報を使用した、宣言コンポーネント用の1つ以上のJSP TLDファイル

使用プロジェクトで宣言コンポーネントを使用するには、デプロイ済のADFライブラリJARファイルをプロジェクトのプロパティに追加します。ADFライブラリJARファイルを追加する手順は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。デプロイ済のJARファイルを追加すると、JDeveloperにより、プロジェクトのプロパティに(再利用可能な宣言コンポーネントを含む)1つ以上のJSPタグ・ライブラリが自動的に挿入され、「コンポーネント」ウィンドウに表示されます。

10.5.4 JSFページでの宣言コンポーネントの使用方法

JDeveloperで、「コンポーネント」ウィンドウからコンポーネントを選択してドラッグし、ページの目的の場所にドロップして、その他のUIコンポーネントと同じように宣言コンポーネントをJSFページに追加します。宣言コンポーネントは、そのユーザー独自のタグ・ライブラリ用のパレットのページに表示されます。図10-6に、「コンポーネント」ウィンドウ内の、宣言コンポーネントを含むライブラリのページを示します。

例10-6 宣言コンポーネントが表示された「コンポーネント」ウィンドウ

必要な属性を含む宣言コンポーネントをページにドラッグすると、定義済の属性に値を入力できるダイアログが開きます。

宣言コンポーネントをページに追加したら、宣言メソッドをマネージドBeanの実際のメソッドに手動でバインドする必要があります。

次の手順を実行する前に、宣言コンポーネントを使用するJSFページを作成中のプロジェクトに、宣言コンポーネントを含むADFライブラリJARファイルを追加しておく必要があります。ADFライブラリJARファイルを追加する手順は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

始める前に:

宣言コンポーネントに関する知識が役立つ場合があります。詳細は、10.5項「宣言コンポーネントの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

JSFページで宣言コンポーネントを使用する手順:

1. 「アプリケーション」ウィンドウで、JSFページ(またはページ・テンプレート)をダブルクリックし、ビジュアル・エディタで開きます。

2. 「コンポーネント」ウィンドウで、タグ・ライブラリ・パネルから宣言コンポーネントをドラッグしてページにドロップします。
同じページに同じ宣言コンポーネントを複数回追加できます。

宣言コンポーネント定義に必須属性が含まれる場合は、JDeveloperにより、挿入する宣言コンポーネントの必須の値を入力するためのダイアログが開かれます。

3. 「コンポーネント」ウィンドウからテンプレートのファセットにコンポーネントをドラッグ・アンド・ドロップして、コンポーネントを追加します。「構造」ウィンドウで、dcがタグ・ライブラリ接頭辞でありmyPanelBoxが宣言コンポーネント名であるdc:myPanelBoxなど、宣言コンポーネントの要素が表示されるまで構造を展開します。
その下に、宣言コンポーネント定義に定義されているファセット(f:facet - contentなど)があります。これらのファセットにコンポーネントを追加します。

コンテンツを宣言コンポーネントに直接追加することはできません。コンテンツは名前付きファセットにのみドロップできます。ファセットにドロップできるコンポーネントのタイプは、宣言コンポーネント定義のfacetRefタグの場所によって異なります。たとえば、facetRefを宣言コンポーネント定義のtableの子として定義した場合、tableはcolumnの子のみ受け入れるため、columnコンポーネントのみファセットにドロップできます。

注意:

宣言コンポーネントの直接の子として配置できるコンポーネントはありません。宣言コンポーネントに表示するコンテンツはすべて、宣言コンポーネントのファセットに配置する必要があります。

4. 構造ウィンドウで、宣言コンポーネント要素(dc:myPanelBoxなど)を再度選択します。「プロパティ」ウィンドウに、宣言コンポーネント定義で事前に定義したすべての属性およびメソッド(Titleなど)が表示されます。属性にはデフォルト値があります。
属性に静的値を割り当てることも、EL式(#{myBean.somevalue}など)を使用することもできます。どのメソッドも、宣言コンポーネントに定義されている宣言済メソッドと同じシグネチャを使用するメソッドにバインドする必要があります。

実行時、属性名を参照するEL式(#{attrs.someAttributeName}など)によって宣言コンポーネント定義に指定されているとおりに、属性値が適切な部分に表示されます。

5. CSSまたはJavaScriptなどのリソースを含める必要がある場合は、af:resourceタグを使用してそれらのリソースを含める必要があります。詳細は、10.6項「ページへのリソースの追加」を参照してください。

10.5.5 JSFページに宣言コンポーネントを使用する場合の処理

ページに宣言コンポーネントを追加したら、宣言コンポーネント定義のコンポーネント・レイアウト・セクションに定義されているコンポーネントによってレンダリングされるコンテンツとともに、コンポーネントの定義済ファセットが名前付きのボックスとしてビジュアル・エディタに表示されます。

その他のUIコンポーネントと同じように、ページに初めて宣言コンポーネントを追加すると、次に示すように、JDeveloperにより、宣言コンポーネント・タグ・ライブラリの名前空間および接頭辞がページのjsp:rootタグに追加されます。

<jsp:root xmlns:dc="/dcomponentLib1: ..>

この例で、dcはタグ・ライブラリの接頭辞で、/dcomponentLib1は名前空間です。

JDeveloperにより、ページに宣言コンポーネントのタグが追加されます。タグには、コンポーネントの追加時にダイアログに設定したように、コンポーネントの属性値が含まれます。例10-16に、3つのoutputFormattedコンポーネントが含まれ、ユーザーがpanelGroupLayoutコンポーネントを追加したMyPanelBox宣言コンポーネントのコードを示します。

例10-16 コンテンツを含む宣言コンポーネントのJSFコード

<dc:myPanelBox title="My Panel Box" buttonText1="Button 1"
display1="true" display2="true" buttonText2="Button 2"
display3="false">
<f:facet name="Content">
<af:panelGroupLayout layout="scroll">
<af:outputFormatted value="outputFormatted1"
styleUsage="instruction"/>
<af:outputFormatted value="outputFormatted2"
styleUsage="instruction"/>
<af:outputFormatted value="outputFormatted3"
styleUsage="instruction"/>
</af:panelGroupLayout>
</f:facet>
</dc:myPanelBox>

10.5.6 実行時に行われる処理: 宣言コンポーネント

宣言コンポーネントを使用するJSFページが実行されると、次の処理が行われます。

- 使用ページの宣言コンポーネント・タグにより、宣言コンポーネント・タグ・クラスと、宣言コンポーネントのメタデータおよびレイアウトを含む定義ファイルが特定されます。

- componentDefタグのレイアウト・セクションに定義されたコンポーネント・サブツリーがインスタンス化され、ページの宣言コンポーネント・タグで識別される場所にある使用ページのコンポーネント・ツリーに挿入されます。

- componentDefタグにより、宣言コンポーネントが内部的に独自の属性を参照できるように、var属性の値が設定されます。宣言コンポーネントにより設定されるのは属性値のみで、それらの値はランタイムによりcomponentDefタグに定義されている属性にマップされます。

- 宣言コンポーネント・メタデータを使用して、宣言コンポーネントにより属性にデフォルト値が適用され、必要な値が確認されます。

- 使用ページにより、ファセット・コンテンツがfacetタグを使用して宣言コンポーネントに渡されます。各facetタグのファセット・コンテンツは、componentDefタグのレイアウト・セクションにある対応するfacetRefタグで指定されているように、宣言コンポーネントの適切な場所に挿入されます。

10.6 ページへのリソースの追加

CSSまたはJavaScriptをページ、ページ・テンプレートまたは宣言コンポーネントに追加するには、af:resourceタグを使用する必要があります。リソースはページ(HTMLの見出し要素内)にのみ追加できるため、このタグはページ・テンプレートと宣言コンポーネントで特に役立ちます。このタグをページ・テンプレートと宣言コンポーネントで使用できる場合は、JSPの実行時に、使用ページにリソースが追加されます。このタグが使用されない場合、ブラウザは、スタイルまたはリンク・タグが検出されるたびに、ページ・テンプレートおよび宣言コンポーネントを使用するページを再レイアウトすることが必要な場合があります。リソースは任意のページ・リクエスト中にページに追加できますが、ドキュメント・コンポーネントがレンダリングされる前に追加する必要があります。

リソース・タグはPPRとともに使用できます。PPRでは、次の要件が適用されます。

- URLリソースが、ページに追加される前にクライアントで比較されること。これにより、重複が追加されないことが保証されます。

- CSSリソースが、PPRナビゲーション中にページから削除されること。新しいページには新しいCSSリソースがあります。

- af:resourceタグで使用されるリソースがADFスキンCSSではないこと。ADFスキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

10.6.1 ページ・テンプレートおよび宣言コンポーネントへのリソースの追加方法

af:resourceタグを使用してリソースの場所を定義します。その後、使用ページのドキュメント・ヘッダーにリソースが追加されます。

始める前に:

使用可能なリソースに関する知識が役立つ場合があります。詳細は、10.6項「ページへのリソースの追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、10.1.2項「再利用可能なコンポーネントの追加機能」を参照してください。

リソースを追加する手順:

1. 「コンポーネント」ウィンドウで、「レイアウト」パネルの「コア構造」グループから「リソース」をドラッグしてページにドロップします。

2. 「リソースの挿入」ダイアログで、次のように設定します。

- タイプ: ドロップダウンリストから、cssまたはjavascriptを選択します。

- リソース: ページに含める外部リソースのソースのURIを入力します。URIがスラッシュ(/)から始まる場合、URIはコンテキストに対して相対的となり、2つのスラッシュ(//)から始まる場合は、サーバーに対して相対的となります。その他はすべて、ブラウザのURIの場所に対して相対的な非絶対のURIです。この属性を指定しない場合、リソース・コンテンツはタグ本体から取得されます。

3. 「OK」をクリックします。

10.6.2 実行時の処理: ドキュメント・ヘッダーにリソースを追加する方法

JSPタグ実行中に、af:resourceタグは親コンポーネントが作成されている場合にのみ実行されます。実行時に、オブジェクトがRichDocumentコンポーネント内のセットに追加されます。RichDocumentは、指定されたリソース(CSSまたはJavaScript)を使用ページに追加します。

第IV部

一般的なADF Facesコンポーネントの使用

第IV部には、次の章が含まれています。

- 第11章「入力コンポーネントの使用およびフォームの定義」

- 第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」

- 第13章「LOVコンポーネントの使用方法」

- 第14章「問合せコンポーネントの使用方法」

- 第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」

- 第16章「メニュー、ツールバーおよびツールボックスの使用方法」

- 第17章「Calendarコンポーネントの使用方法」

- 第18章「出力コンポーネントの使用」

- 第19章「ヒント、メッセージおよびヘルプの表示」

- 第20章「ナビゲーション・コンポーネントの使用」

- 第21章「実行時のコンポーネントの決定」

11 入力コンポーネントの使用およびフォームの定義

この章では、フォームの定義方法と入力コンポーネントの作成方法について説明します。エンド・ユーザーはこれらを使用して、データの入力(inputTextなど)、値の選択(inputNumber、inputRange、inputColor、inputDateおよびselectコンポーネントなど)、テキストの編集(richTextEditorなど)、およびファイルのロード(inputFileなど)を行えます。

この章では、次の項目について説明します。

- 11.1項「入力コンポーネントおよびフォームについて」

- 11.2項「formの定義」

- 11.3項「inputTextコンポーネントの使用方法」

- 11.4項「数値入力コンポーネントの使用方法」

- 11.5項「カラー・チューザおよび日付チューザの使用方法」

- 11.6項「選択コンポーネントの使用方法」

- 11.7項「シャトル・コンポーネントの使用方法」

- 11.8項「richTextEditorコンポーネントの使用方法」

- 11.9項「ファイルのアップロード機能の使用方法」

- 11.10項「コード・エディタの使用」

サイズが大きくなる可能性のある項目リスト、またはオブジェクト間の関係を表す可能性のある(別のオブジェクトの外部キーである属性を表すリストを作成する場合など)項目リストから選択する入力コンポーネントを使用する場合には、値リスト・コンポーネントを使用できます。これらのコンポーネントの詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

11.1 入力コンポーネントおよびフォームについて

入力コンポーネントは、様々な形式のユーザー入力を受け入れます。最も一般的な形式は、フォームの内部に表示され、フォームの送信時に送信されるテキスト、数値、日付および選択リストです。入力された値または選択は、さらに処理される前に検証および変換できます。図11-1は、ADF Facesの標準入力コンポーネントを示しています。

図11-1 ADF Faces入力コンポーネント

ADF Faces入力コンポーネントには、図11-2に示すように、ユーザーが1つまたは複数の値を選択できるいくつかのコンポーネントも含まれます。

図11-2 コンポーネントの選択

11.1.1 入力コンポーネントのユースケースと例

多くの場合、入力コンポーネントは、ユーザー入力用のフォームの作成に使用されます。たとえば、File Explorerアプリケーションには、ユーザーが新規ファイルを作成できるフォームが含まれます。図11-3に示すように、入力コンポーネントでは、ユーザーが名前やサイズの入力、権限の選択、キーワードとファイルの説明の追加を行うことができます。アスタリスクで示されているように、「名前」フィールドは必須です。ユーザーが値を入力しなかった場合は、エラー・メッセージが表示されます。その検証および関連エラー・メッセージは、コンポーネントごとに構成することも(required属性またはrequiredMessageDetail属性を設定して)、サーバーで処理することもできます(showRequired属性を設定して)。

図11-3 入力コンポーネントを使用したフォーム

richTextEditorコンポーネントには、ユーザーに単純なテキスト以外を入力させる場合に必要になる、異なるフォント、サイズ、行揃えおよびその他の編集機能を使用した書式設定可能な、多数の行にわたるリッチ・テキスト入力が用意されています。たとえば、richTextEditorをWebベースのディスカッション・フォーラムで使用して、図11-4に示すように、ユーザーが公開する必要のあるテキストを書式設定できるようにすることができます。

図11-4 ディスカッション・フォーラムで使用されるrichTextEditor

inputFileコンポーネントでは、ユーザーはアプリケーション・サーバーにアップロードするローカル・ファイルを参照できます。たとえば、電子メール・メッセージでは、図11-5に示すようにユーザーがメッセージにファイルを添付できます。

図11-5 fileUploadコンポーネント

ADF Faces選択コンポーネントを使用すると、ユーザーは値を入力するかわりに項目のリストから選択できるようになります。ADF Facesは、単一選択の選択リストと複数選択の選択リストの両方を提供します。単一選択リストは、図11-6に示すように、オンライン食品注文での目的の飲料など、リストから1つの値を選択するために使用します。

図11-6 ユーザーはselectOneChoiceコンポーネントから1つの値を選択できる

ADF単一選択コンポーネントには、ドロップダウン・リスト(図11-6を参照)、リスト・ボックス、ラジオ・ボタンおよびチェックボックスがあります。

ADF複数選択コンポーネントでは、ユーザーはリストの値を複数選択できます。たとえば、1つの飲料タイプを選択するかわりに、selectManyChoiceコンポーネントでは、図11-7に示すようにユーザーが複数の飲料を選択できます。

図11-7 ユーザーはselectManyChoiceコンポーネントから複数の値を選択できる

ADF複数選択コンポーネントには、ドロップダウン・リスト、チェックボックス、チェックボックス・リスト、シャトルおよび順序付け済シャトルが含まれます。

ベスト・プラクティス:

選択リストまたは値リスト(LOV)コンポーネントを使用して、リストを表示できます。LOVコンポーネントは、選択リストが大きい場合に使用する必要があります。LOVコンポーネントは、ListOfValueModelクラスを使用したモデルドリブンであり、APIを使用してプログラムで構成できます。これらは、問合せパネルを含むこともあるポップアップ・ウィンドウの内部の選択リストを表します。選択リストは、単純に静的な値リストを表示します。LOVコンポーネントは単一選択であり、1つのオプションしか選択できないため、複数選択には使用しないでください。LOVコンポーネントの使用の詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

フォーム・コンポーネントには、その他のコンポーネント用のコンテナがあります。formコンポーネントは、埋め込まれた入力コンポーネントからの値を送信できるリージョンを表します。1ページ当たりでサポートされるフォーム・コンポーネントは1つのみです。ADF Facesには、form内で個別にコンポーネント値を送信できるサブリージョンを定義することで柔軟性を高めるsubformコンポーネントも用意されています。

注意:

af:autoSuggestBehaviorタグによって提案項目のリストを表示するように構成された入力コンポーネントを使用していて、AdfCustomEventタグを使用してカスタム・イベントをサーバーに送信する場合、サーバー・リスナーは実行されません。これは、af:autoSuggestBehaviorタグがリクエスト値の適用フェーズ後に入力値のライフ・サイクルに割り込み、レスポンスのレンダリング・フェーズに移るためです。

11.1.2 入力コンポーネントおよびフォームの追加機能

入力コンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページに入力コンポーネントまたはフォームを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。入力コンポーネントで使用できる他の機能へのリンクを次に示します。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- クライアント・コンポーネント: 入力コンポーネントはクライアント・コンポーネントにすることができます。クライアントでコンポーネントを処理するには、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

- JavaScript API: すべての入力コンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください。

- イベント: 入力コンポーネントは、なんらかのロジックを実行することでアプリケーションで対応できるサーバー側とクライアント側両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。

- 検証および変換を入力コンポーネントに追加できます。詳細は、第7章「入力の検証および変換」を参照してください。

- ヒントとメッセージを表示でき、入力コンポーネントにオンライン・ヘルプを関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 特定の入力コンポーネントをページの他のコンポーネントより前に検証することが必要になる場合があります。詳細は、5.2項「immediate属性の使用」を参照してください。

- 選択コンポーネントから行った選択に基づいてページの他のコンポーネントを更新できます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

- scrollComponentIntoViewBehaviorタグをrichTextEditorコンポーネントとともに使用すると、ユーザーはコンポーネント内の特定の領域にジャンプできます。詳細は、6.6.1項「scrollComponentIntoViewBehaviorタグの使用方法」を参照してください。

- スキンを使用して、必須および変更済通知に使用するアイコンを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 入力コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- アプリケーションでADFモデルを使用する場合は、自動的にバインドされるフォームを、データ・コントロールを使用して作成できます(ADFビジネス・コンポーネントに基づくか、その他のビジネス・サービスに基づくかを問いません)。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた基本的なページの作成」の章を参照してください。

11.2 formの定義

formは、他のコンポーネントのコンテナとして機能するコンポーネントです。フォーム内で送信アクションが発生すると、変更された入力値が送信されます。たとえば、入力コンポーネントと選択コンポーネントで構成される入力フォーム、および送信コマンド・ボタンを作成し、すべてをform内に配置できます。ユーザーが複数の入力フィールドに値を入力して送信ボタンをクリックすると、それらの新しい入力値が送信されて処理されます。

JDeveloperでJSFページを作成すると、デフォルトで、ページにformコンポーネントが自動的に挿入されます。ページにコンポーネントを追加すると、formコンポーネント内に挿入されます。

ヒント:

ページにaf:formタグがない状態で、そのページにADF Facesコンポーネントをドラッグ・アンド・ドロップすると、JDeveloperにより、コンポーネントをformコンポーネントで囲むよう要求されます。

例11-1に、2つの入力コンポーネント、およびクリックされると両方の入力値が送信されて処理される送信ボタンを示します。

例11-1 入力コンポーネントのコンテナとしてのADF Facesのform

<af:form id="f1">
<af:panelFormLayout id="pfl1">
<af:inputText value="#{myBean.firstName}"
label="#{FirstName}"
id="it1">
</af:inputText>
<af:inputText value="#{myBean.lastName}"
label="#{LastName}"
id="it2">
</af:inputText>
<af:button text="Submit" id="b1"/>
</af:panelFormLayout>
</af:form>

ページに使用できるformコンポーネントは1つのみであるため、入力値を送信できる個別のリージョンを作成するには、form内にsubformを使用します。リージョンにおいて、subform内の値は、subform内のコンポーネントが値の送信を行う場合にのみ検証および処理されます。また、subform内に別のsubformをネストさせて、値を送信できるネストしたリージョンを作成することもできます。subformの詳細は、5.5項「サブフォームを使用したページでのセクションの作成」を参照してください。

例11-2に、それぞれ独自の入力コンポーネントとボタン(送信ボタンなど)を含む2つのsubformを持つformを示します。送信ボタンをクリックすると、そのsubform内の入力値のみが送信されて処理されます。

例11-2 form内のADF Facesのsubform

<af:form id="f1">
<af:subform id="s1">
<af:panelFormLayout id="pfl1">
<af:inputText value="#{myBean.firstName}"
label="#{FirstName}"
id="it1">
</af:inputText>
<af:inputText value="#{myBean.lastName}"
label="#{LastName}"
id="it2">
</af:inputText>
<af:button text="Submit" id="b1"/>
</af:panelFormLayout>
</af:subform>

<af:subform id="s2">
<af:panelFormLayout id="pfl2">
<af:inputText value="#{myBean.primaryPhone}"
label="#{PrimaryPhone}"
id="it3">
</af:inputText>
<af:inputText value="#{myBean.cellPhone}"
label="#{CellPhone}"
id="it4">
</af:inputText>
<af:button text="Submit" id="b2"/>
</af:panelFormLayout>
</af:subform>
</af:form>

基本的なボタンの他に、form内にその他のコマンド・コンポーネントを追加して、そのform内の任意のフィールドで機能させることができます。

11.2.1 ページへのformの追加方法

多くの場合、JDeveloperを使用してformコンポーネントを追加します。ただし、手動でのformの追加や、特定の属性値を使用したformの構成が必要な場合があります。

始める前に:

formコンポーネントに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

ページにformを追加する手順:

1. 「コンポーネント」ウィンドウで、「レイアウト」パネルの「コア構造」グループから、「フォーム」をドラッグしてページにドロップします。

2. 「Properties」ウィンドウで「共通」セクションを開くと、オプションで次の設定ができます。

- DefaultCommand: [Enter]キーが押され、form内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。

- UsesUpload: formでファイルのアップロードをサポートするかどうかを指定します。デフォルト値はFalseです。ファイルのアップロードの詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。

- TargetFrame: 新しいページを表示するかどうかを指定します。使用可能な値は、HTMLのターゲット属性の有効な値です。デフォルトは、_selfです。

11.2.2 ページへのsubformの追加方法

ページのセクションで値を個別に送信できることが必要な場合は、formコンポーネント内にsubformコンポーネントを追加する必要があります。

始める前に:

formおよびsubformに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

formコンポーネントをページに追加する必要があります。手順は、11.2.1項「ページへのformの追加方法」を参照してください。

ページにsubformを追加する手順:

1. 「コンポーネント」ウィンドウで、「レイアウト」パネルの「コア構造」グループから、「サブ・フォーム」をformコンポーネントの子としてページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Default: subformで値を送信済であると仮定するかどうかを指定します。デフォルト値falseに設定すると、その他のsubformコンポーネントが送信されていない場合にのみ、そのsubformコンポーネントは送信済とみなされます。trueに設定すると、そのsubformコンポーネントは値を送信済とみなされます。

ヒント:

subformは、リクエスト値の適用より後のフェーズ(つまり、decode()より後)に対してイベントが子またはファセットの1つによってキューに入れられた場合に送信済とみなされます。ライフサイクル・フェーズの詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

- Default Command: [Enter]キーが押され、subform内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。

11.2.3 formをリセットするボタンの追加方法

ボタン・コンポーネントを追加し、af:resetListenerを使用してそのボタンが他の入力コンポーネントをデフォルト値にリセットするように構成します。リセット・ボタンは、そのformまたはsubform内のコンポーネントでのみ機能します。

始める前に:

formコンポーネントに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

resetListenerを使用してボタンをページに追加するには:

1. 「コンポーネント」ウィンドウで、「一般コントロール」パネルから「ボタン」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで、次を設定します。

- Text: ボタンのテキスト・ラベルを指定します。
このプロパティは「共通」セクションにあります。

- Disabled: ボタンを無効にするかどうかを指定します。たとえば、ボタンを無効化する必要のある特定の状況を判断するEL式を入力できます。
このプロパティは「動作」セクションにあります。

3. 「コンポーネント」ウィンドウで、「操作」パネルの「リスナー」グループからリスナー・リセット・コンポーネントをドラッグし、ボタン・コンポーネントに子としてドロップします。

4. 「リスナー・リセットの挿入」ダイアログで、「型」ドロップダウン・リストからactionを選択し、「OK」をクリックします。

11.3 inputTextコンポーネントの使用方法

ピッカー、スライダ、スピン・ボックスなど、入力コンポーネントには多くのバリエーションがありますが、inputTextコンポーネントは、値入力のための基本的な入力コンポーネントです。inputTextコンポーネントは、1行の入力フィールドとして定義することも、rows属性を1より大きい値に設定してテキスト領域として定義することもできます。ただし、リッチ・テキストを入力できるようにする場合は、11.8項「richTextEditorコンポーネントの使用方法」で説明されているように、richTextEditorコンポーネントの使用を検討してください。

autoComplete属性を使用して、inputTextコンポーネントでオートコンプリートを使用できます。trueに設定されている場合、コンポーネントは以前のエントリを記憶し、ユーザーがそれらのエントリと一致する値から始まる値を入力したときにそれらのエントリを表示します。

secret属性をtrueに設定することで、パスワードなどの入力値を非表示にできます。その他のADF Facesコンポーネントと同じように、inputTextコンポーネントではラベル、テキストおよびメッセージがサポートされています。このコンポーネントをラベルなしで表示する場合は、simple属性をtrueに設定します。図11-8に、1行のinputTextコンポーネントを示します。

図11-8 1行のinputTextコンポーネント

rows属性を使用して、inputTextコンポーネントで複数行のテキストを表示できます。rows属性を1より大きい値に設定し、simple属性をtrueに設定した場合、inputTextコンポーネントは、dimensionsFrom属性を使用してそのコンテナに合せて拡大するように構成できます。コンポーネントが拡大される方法の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。図11-10に、複数行のinputTextコンポーネントを示します。

複数のinputTextコンポーネントを追加して、入力フォームを作成できます。図11-9に、2つのinputTextコンポーネントを使用した入力フォームを示します。

図11-9 inputTextコンポーネントで作成したフォーム

コマンド・コンポーネントと連携して、inputTextコンポーネントに特定のテキストを挿入するinsertTextBehaviorタグも構成できます。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoiceコンポーネントで選択したリスト項目など)を指定できます。たとえば、図11-10は、ユーザーがすでにテキストを入力したinputTextコンポーネントを示しています。

図11-10 テキストが入力済のinputTextコンポーネント

この後、ユーザーがドロップダウン・リストから追加テキストを選択し、コマンド・ボタンをクリックすると、図11-11に示すように、inputTextコンポーネントにそのテキストが表示されます。

図11-11 テキストが挿入済のinputTextコンポーネント

11.3.1 inputTextコンポーネントの追加方法

第9章「Webページ上のコンテンツの編成」で説明されている任意のレイアウト・コンポーネントの内部で、inputTextコンポーネントを使用できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputTextコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「入力テキスト」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Label: ラベルとして使用するテキストを指定するための値を入力します。
使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- Value: コンポーネントの値を指定します。値のELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指していて、それが値の編集が可能なコンポーネントの場合、コンポーネントは読取り専用モードでレンダリングされます。

注意:

inputTextコンポーネントを使用してCharacter Large Object (CLOB)を表示する場合は、CLOBを文字列に変換するカスタム・コンバータを作成する必要があります。変換の詳細は、第7章の「カスタムADF Facesコンバータの作成」を参照してください。

3. 「外観」セクションを開き、次の設定を行います。

- Columns: テキスト・フィールドに表示される文字の数を指定します。

- Rows: 表示される行数を入力し、テキスト・コントロールの高さを指定します。デフォルト値は1で、1行の入力フィールドを生成します。行数は、ブラウザのデフォルトのフォント・サイズに基づいて見積られます。
Rowsを1より大きな値に設定した場合にデフォルトのテキスト折返し動作を変更するには、wrap属性も設定する必要があります。

- DimensionsFrom: inputTextコンポーネントでジオメトリ管理を処理する方法を決定します。この属性に次のいずれかを設定します。

- auto: inputTextコンポーネントの親コンポーネントがその子の拡大を許可する場合、rows属性が1より大きい数値に設定され、simple属性がtrueに設定されているかぎり、inputTextコンポーネントは親コンポーネントに合せて拡大されます。親コンポーネントが拡大を許可しない場合、inputTextコンポーネントはそのディメンションをコンテンツから取得します。

- content: inputTextコンポーネントは、そのディメンションをコンポーネント・コンテンツから取得します。これがデフォルトです。

- parent: inputTextコンポーネントは、そのディメンションをinlineStyle属性から取得します。inlineStyleの値が存在しない場合、親コンテナによってサイズが決定されます。

- Secret: 1行のテキスト・コントロールにのみ適用されるブール値を指定します。trueに設定されている場合、secret属性により、テキストの実際の値がユーザーには非表示になります。

- Wrap: 複数行のテキスト・コントロールで使用されるテキストの折返しタイプを指定します。この属性は、1行のコンポーネントでは無視されます。デフォルトでは属性がsoftに設定されており、複数行のテキストは視覚的には折り返されますが、送信される値に改行は含まれません。この属性をoffに設定すると折返しは無効にされ、複数行のテキストは水平にスクロールして表示されます。hardに設定すると、行の折返しに必要な改行がテキストの値に含まれます。

- ShowRequired: フィールドが必須であることを視覚的に表示するかどうかを指定します。required属性をtrueに設定しても、視覚的な表示が行われることに注意してください。showRequired属性は、別のフィールドの値が変更された場合にのみ、フィールドが必須の場合に使用する必要があります。

- Changed: フィールドの値が変更されるたびに青い円を表示するかどうかを指定します。これをtrueに設定した場合は、changedDesc属性も設定します。

- ChangedDesc: 変更済アイコン上にマウスを移動したときにツールチップに表示されるテキストを指定します。デフォルトでは、テキストは"変更済"です。別の値を指定することで、これをオーバーライドできます。

- Editable: コンポーネントを常に編集可能にするかどうかを決定します。そうする場合は、alwaysを選択します。ユーザーがマウスを値の上に移動するまでその値を読取り専用にする場合は、onAccessを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、どの祖先コンポーネントでもeditable値が定義されていない場合は、alwaysの値が使用されます。

- AccessKey: フィールドにアクセスするために押すキーを指定します。

- LabelAndAccessKey: ラベルとアクセス・キーを別々に指定するかわりに、2つを結合して、アクセス・キーがラベルの一部になるようにできます。アクセス・キーとして使用する文字の前にアンパサンド(&)を付けます。
たとえば、フィールドのラベルが「Description」で、Dをアクセス・キーにする場合は、&Descriptionと入力します。

注意:

値はXMLのページ・ソースに格納されるため、アンパサンド(&)文字をエスケープする必要があります。そのため、ソース・ページでは、アンパサンドを意味する文字&amp;を使用して表されます。

- Simple: ラベルを表示しない場合にtrueに設定します。

- Placeholder: 入力コンポーネントが空でフォーカスが設定されていない場合に、コンポーネントに表示されるテキストを指定します。コンポーネントにフォーカスが設定されるか、値が入力されると、プレースホルダ・テキストは非表示になります。
プレースホルダ・テキストは、ユーザーが入力コンポーネントに入力する必要のある内容を知らせる目的で使用されます。

4. ラベル・テキストのスタイルを設定する場合は、「スタイル」セクションを展開し、LabelStyleを設定します。CSSスタイル・プロパティと値を入力します。たとえば、ラベル・テキストを折り返さない場合は、値にwhite-space:nowrap;と入力します。

5. 「動作」セクションを開き、次の設定を行います。

- Required: 値が必要かどうかを指定します。trueに設定されている場合、値を入力する必要があることをユーザーに知らせるために視覚的に表示されます。値が入力されない場合、例外が発生し、コンポーネントの検証が失敗します。

- ReadOnly: コントロールを、値の編集が可能なフィールドとして表示するか、出力スタイルのテキスト・コントロールとして表示するかを指定します。

- AutoSubmit: 値が変更されたらコンポーネントを自動的に送信するかどうかを指定します。autoSubmit属性の使用の詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

- AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、onに設定します。一致を表示しない場合はoffに設定します。デフォルトはonです。

- AutoTab: 現在のコンポーネントの最大長に達した場合に、フォーカスを次のタブ位置に自動的に移動するかどうかを指定します。

- Usage: HTML5ブラウザでの入力コンポーネントのレンダリング方法を指定します。有効な値は、auto、textおよびsearchです。デフォルトはautoです。
使用方法のタイプがsearchの場合、入力コンポーネントはHTML5の検索入力タイプとしてレンダリングされます。一部のHTML5ブラウザでは、検索テキストの消去に使用できる「取消」アイコンが追加される場合があります。

- MaximumLength: テキスト・コントロールに入力できる1行当たりの最大文字数を指定します。これには、改行を表す文字も含まれます。0以下に設定されている場合、maximumLength属性は無視されます。Internet Explorerなどのブラウザでは、改行は2文字として扱われます。

- Converter: コンバータ・オブジェクトを指定します。詳細は、7.3項「変換の追加」を参照してください。

- Validator: EL式を使用して、バリデータ・メソッドへのメソッド参照を指定します。詳細は、7.5項「検証の追加」を参照してください。

6. スペルチェックを無効にする場合は、「その他」セクションを開いてSpellCheckをoffに設定します。デフォルトでは、スペルチェックはブラウザのスペルチェック設定と同じ設定になります。
たとえば、Mozilla Firefoxではスペルチェック機能はデフォルトで有効になっています。

11.3.2 inputTextコンポーネントへのテキストの挿入機能の追加方法

insertTextBehaviorタグは、コマンド・コンポーネントと連携して、inputTextコンポーネントに特定のテキストを挿入します。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoiceコンポーネントで選択したリスト項目など)を指定できます。inputTextコンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてinsertTextBehaviorタグを追加します。

注意:

insertTextBehaviorタグでは、サーバー側イベントの配信が自動的に取り消されます。親コマンド・コンポーネントのactionListenerまたはaction属性は無視されます。サーバー側機能をトリガーする必要もある場合は、サーバー側イベントを配信するためにカスタム・クライアント・リスナーを追加する必要があります。詳細は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

始める前に

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

insertTextBehaviorタグを追加する前に、11.3.1項「inputTextコンポーネントの追加方法」の説明に従ってinputTextコンポーネントを作成する必要があります。clientComponent属性をtrueに設定します。

テキスト挿入動作を追加する手順:

1. テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順の詳細は、20.3.1項「ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法」を参照してください。

2. 「コンポーネント」ウィンドウで、「操作」パネルの「動作」グループから、「テキストの挿入動作」をドラッグしてコマンド・コンポーネントに子としてドロップします。

3. 「テキストの挿入動作」ダイアログで、次の内容を入力します。

- For: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するinputTextコンポーネントに移動して選択します。

- Value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoiceコンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。例11-3に、ドロップダウン・リストの値または静的テキストの値を挿入できるinputTextコンポーネントのページ・コードを示します。

例11-3 insertTextBehaviorタグの使用

<af:inputText clientComponent="true"
id="idInputText"
label="String value"
value="#{demoInput.value}"
rows="10"
columns="60">
</af:inputText>
<af:selectOneChoice id="targetChoice"
autoSubmit="true"
value="#{demoInput.choiceInsertText}"
label="Select text to insert">
<af:selectItem label="Some Text." value="Some Text." id="si1"/>
<af:selectItem label="0123456789" value="0123456789" id="si2"/>
<af:selectItem label="~!@#$%^*" value="~!@#$%^*" id="si3"/>
<af:selectItem label="Two Lines" value="\\\\nLine 1\\\\nLine 2" id="si4"/>
</af:selectOneChoice>
<af:button text="Insert Selected Text"
id="firstButton"
partialTriggers="targetChoice">
<af:insertTextBehavior for="idInputText" value="#{demoInput.choiceInsertText}">
</af:insertTextBehavior>
</af:button>
<af:button text="Insert Static Text" id="b1">
<af:insertTextBehavior for="idInputText" value="Some Static Text."/>
</af:button>

4. デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、「プロパティ」ウィンドウでinsertTextBehaviorコンポーネントのtriggerType属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。

11.4 数値入力コンポーネントの使用方法

スライダ・コンポーネントを使用すると、スライダ上の位置が値に対応している1つまたは2つのマーカーがあるスライダを作成できます。スライダの値が表示され、一方にはマイナス・アイコンが、もう一方にはプラス・アイコンがあります。ユーザーはマーカーを選択し、スライダ上を移動させて値を選択します。図11-12(水平レイアウト)および図11-13(垂直レイアウト)に示すように、inputNumberSliderコンポーネントにはマーカーが1つあり、ユーザーはスライダから値を1つ選択できます。

図11-12 水平レイアウトのinputNumberSlider

図11-13 垂直レイアウトのinputNumberSlider

図11-14に示すように、inputRangeSliderコンポーネントにはマーカーが2つあり、ユーザーは範囲のエンド・ポイントを選択できます。

図11-14 水平レイアウトのinputRangeSlider

また、inputNumberSliderおよびinputRangeSliderコンポーネントを構成すると、図11-15に示すように再生/一時停止ボタンを追加し、スライダがコンポーネントの増分値の中をアニメーションで移動するようにできます。

図11-15 再生/一時停止ボタン付きのinputRangeSlider

図11-16に示すように、inputNumberSpinboxは、数値用の入力フィールド、および入力フィールドの現在の値を増減させるための上矢印キーと下矢印キーのセットを作成する入力コンポーネントです。

図11-16 inputNumberSpinbox

11.4.1 inputNumberSliderまたはinputRangeSliderコンポーネントの追加方法

inputNumberSliderまたはinputRangeSliderコンポーネントを追加する際には、表示される数値の範囲と増分を決定できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.4項「数値入力コンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputNumberSliderまたはinputRangeSliderコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「スライダ(番号)」または「スライダ(範囲)」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで、「共通」セクションを開いて、次の属性を設定します(inputRangeSliderコンポーネントの場合は、「データ」セクションも開きます)。

- Label: コンポーネントのラベルを指定します。

- Minimum: 選択可能な最小値を指定します。この値は、スライダの開始値です。

- Maximum: 選択可能な最大値を指定します。この値は、スライダの終了値です。

- MinimumIncrement: 最小の増分値を指定します。これは、ユーザーがプラスまたはマイナスのアイコンをクリックすると適用される増分です。

- MajorIncrement: 大きい方の2つの目盛り間の距離を指定します。この値を指定すると、ラベルの付いた値が表示されます。たとえば、図11-14のinputRangeSliderコンポーネントのmajorIncrement値は5.0です。0未満の場合、大きい方の増分値は表示されません。

- MinorIncrement: 小さい方の2つの目盛り間の距離を指定します。0未満の場合、小さい方の増分値は表示されません。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

3. 「外観」セクションを展開し、Orientationを設定して、コンポーネントを水平レイアウトと垂直レイアウトのどちらにするかを指定します。この項のその他の属性の詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。

4. 「その他」セクションを開き、AnimationIntervalをミリ秒単位の値に設定します。デフォルト値は0です。
値がゼロより大きい場合は、コンポーネントの下に再生ボタンが表示されます。クリックすると、スライダが増分値の中をアニメーションで移動し、増分のたびに指定時間(ミリ秒単位)停止します。アニメーションの再生中、再生ボタンは一時停止ボタンに変化します。このボタンを押すと、アニメーションは現在の増分値で停止します。

たとえば、図11-15のinputRangeSliderコンポーネントのanimationInterval値は999です。

11.4.2 inputNumberSpinboxコンポーネントの追加方法

inputNumberSpinboxコンポーネントを使用すると、ユーザーは一連の数値をスクロールして値を選択できるようになります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.4項「数値入力コンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputNumberSpinboxコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「入力数値スピンボックス」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで「データ」セクションを開き、次の設定を行います。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

- Minimum: 入力フィールドで許可される最小値を指定します。

- Maximum: 入力フィールドで許可される最大値を指定します。

- StepSize: スピン・ボックスが入力フィールドの数値を増減する際の増分を指定します。

3. 「外観」および「動作」セクションを開き、属性を設定します。これらの属性設定の詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。

11.5 カラー・チューザおよび日付チューザの使用方法

inputColorコンポーネントでは、ユーザーがパレットから色を選択できます。これは、色のコードを入力するテキスト入力フィールドを表します。図11-17に示すように、ポップアップのパレットから色を選択するためのボタンも表示します。

図11-17 ポップアップのchooseColorコンポーネントが含まれるinputColorコンポーネント

デフォルトでは、ポップアップのコンテンツ配信は遅延です。ユーザーがボタンをクリックすると、inputColorコンポーネントがPPRリクエストを受信し、レンダラがchooseColorコンポーネントをpopupコンポーネントに表示します。

パフォーマンスのヒント:

inputColorコンポーネントのclientComponent属性がtrueに設定されている場合、ポップアップおよびchooseColorコンポーネントは即時に配信されます。カラー・パレットが大きい場合、これは初期ページ・ロードのパフォーマンスに悪影響を与えることがあります。

デフォルトの色のコード形式は16進の色の形式です。ただし、ColorConverterクラスを使用して書式設定をオーバーライドできます。

inputDateコンポーネントを使用すると、図11-18に示すように、日付を入力するためのテキスト入力フィールドと、ポップアップ・カレンダから日付を選択するためのボタンを作成できます。デフォルトの日付フォーマットは、現在のロケールに適切な省略の日付フォーマットです。たとえば、米語(ENU)のデフォルトの書式はmm/dd/yyです。ただし、この書式は日時コンバータを使用してオーバーライドできます(コンバータの使用方法の詳細は、7.3項「変換の追加」を参照してください)。

図11-18 inputDateコンポーネント

日時コンバータを追加して、日付と時間の両方を表示するように構成すると、ユーザーが時間を入力するための追加のコントロールのある日付ピッカーがモーダル・ダイアログとして表示されます。また、コンバータがタイム・ゾーンを表示するように構成されている場合、図11-19に示すようにタイム・ゾーン・ドロップダウン・リストがダイアログに表示されます。

図11-19 日時コンバータが使用されている場合のモーダル・ダイアログ

11.5.1 inputColorコンポーネントの追加方法

inputColorコンポーネントを使用すると、ユーザーによる入力テキスト・フィールドへの値の入力や、カラー・チューザからの色の選択が可能になります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.5項「カラー・チューザおよび日付チューザの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputColorコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「入力色」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Label: コンポーネントのラベルを指定します。

- Compact: 図11-20に示すように、入力テキスト・フィールドを表示しない場合はtrueに設定します。

図11-20 CompactモードのinputColorコンポーネント

3. 「データ」セクションを開き、次の属性を設定します。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

- ColorData: 標準のカラー・パレットに表示される色のリストを指定します。表示される色の数は、49 (7色x7色)、64 (8色x8色)または121 (11色x11色)です。この属性に設定される数値により、width属性の有効な値が決定されます。たとえば、colorData属性を49に設定した場合、幅は7にする必要があります。色の数が幅に合っていない場合、リストの余分な色要素は無視され、欠落している色要素は色なしとして表示されます。色のリストは、クライアント側ではタイプTrColorの配列であることが必要です。

- CustomColorData: カスタム定義の色のリストを指定します。色の数は7、8、11のいずれかです。色のリストは、クライアント側ではタイプTrColorの配列であることが必要です。サーバー側では、java.awt.ColorオブジェクトのListまたは16進の色文字列のリストである必要があります。

- DefaultColor: #000000など、16進の色のコードを使用してデフォルトの色を指定します。

4. 「外観」セクションを開き、次の属性を設定します。

- Width: セルにおける標準のパレットの幅を指定します。有効な値は7、8および11で、colorDataおよびcustomColorData属性の値に対応します。

- CustomVisible: 「カスタム・カラー」ボタンおよびカスタム・カラー行を表示するかどうかを指定します。trueに設定すると、「カスタム・カラー」ボタンおよびカスタム・カラー行がレンダリングされます。

- DefaultVisible: 「デフォルト」ボタンを表示するかどうかを指定します。trueに設定すると、「デフォルト」ボタンがレンダリングされます。「デフォルト」ボタンを使用すると、ユーザーはdefaultColor属性の値として、簡単に色のセットを選択できるようになります。

- LastUsedVisible: 「最終使用」ボタンを表示するかどうかを指定します。trueに設定すると、「最終使用」ボタンがレンダリングされ、ユーザーは前回使用した色を選択できるようになります。

- Editable: ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用にする場合は、onAccessに設定します。コンポーネントを常に編集可能にする場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、どの祖先コンポーネントでもeditable値が定義されていない場合は、alwaysの値が使用されます。

- Placeholder: 入力コンポーネントが空でフォーカスが設定されていない場合に、コンポーネントに表示されるテキストを指定します。コンポーネントにフォーカスが設定されるか、値が入力されると、プレースホルダ・テキストは非表示になります。
プレースホルダ・テキストは、ユーザーが入力コンポーネントに入力する必要のある内容を知らせる目的で使用されます。

5. ラベルのスタイルを設定する場合は、「スタイル」セクションを展開し、LabelStyleを設定します。ラベルのCSSスタイル・プロパティと値を入力します。たとえば、ラベル・テキストを折り返さない場合は、値にwhite-space:nowrap;と入力します。

6. 「動作」セクションを開き、次の属性を設定します。

- ChooseId: 色の値を選択するために使用できるchooseColorコンポーネントのIDを指定します。設定しない場合、inputColorコンポーネントには、chooseColorコンポーネントが使用された独自のデフォルトのポップアップ・ダイアログが使用されます。

- AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、trueに設定します。一致を表示しない場合はfalseに設定します。デフォルトはtrueです。

- Usage: HTML5ブラウザでの入力コンポーネントのレンダリング方法を指定します。有効な値は、auto、textおよびsearchです。デフォルトはautoです。
使用方法のタイプがsearchの場合、入力コンポーネントはHTML5の検索入力タイプとしてレンダリングされます。一部のHTML5ブラウザでは、検索テキストの消去に使用できる「取消」アイコンが追加される場合があります。

11.5.2 inputDateコンポーネントの追加方法

inputDateコンポーネントを使用すると、ユーザーは日付の入力または選択を実行できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.5項「カラー・チューザおよび日付チューザの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputDateコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「入力日」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Label: コンポーネントのラベルを指定します。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

3. オプションで、「スタイル」セクションを開き、LabelStyle属性をCSSスタイル・プロパティと値に設定します。たとえば、ラベル・テキストを折り返さない場合は、値としてwhite-space:nowrap;を入力します。

4. 「データ」セクションを開き、次の属性を設定します。

- MinValue: 日付値に許可される最小値を指定します。タグで固定値に設定されている場合、この値はISO 8601の日付として解析されます。ISO 8601の日付は、yyyy-MM-dd (2002-02-15など)の形式です。この他すべての使用方法では、java.util.Dateオブジェクトが必要です。

- MaxValue: 日付値に許可される最大値を指定します。タグで固定値に設定されている場合、この値はISO 8601の日付として解析されます。ISO 8601の日付は、yyyy-MM-dd (2002-02-15など)の形式です。この他すべての使用方法では、java.util.Dateオブジェクトが必要です。

- DisableDays: org.apache.myfaces.trinidad.model.DateListProviderインタフェースの実装へのバインディングを指定します。getDateListメソッドによって、無効に指定される個々のjava.util.DateオブジェクトのListが生成されます。日付は、指定されたベース・カレンダのコンテキストに存在する必要があります。

パフォーマンスのヒント:

このバインディングには、定期的なラウンドトリップが必要です。特定の曜日(土曜日および日曜日など)のみを無効にする場合は、disableDaysOfWeek属性を使用します。

- DisableDaysOfWeek: 各週に無効の状態でレンダリングする必要のある曜日を空白で区切ったリストで指定します。リストには、sun、mon、tue、wed、thu、fri、satの1つ以上の略語を含める必要があります。デフォルトでは、すべての曜日が有効です。

- DisableMonths: 各年に無効の状態でレンダリングする必要のある月を空白で区切ったリストで指定します。リストには、jan、feb、mar、apr、may、jun、jul、aug、sep、oct、nov、decの1つ以上の略語を含める必要があります。デフォルトでは、すべての月が有効です。

5. 「動作」セクションを開き、次の設定を行います。

- ChooseId: 日付値を選択するために使用できるchooseDateコンポーネントのIDを指定します。設定しない場合、inputDateコンポーネントには、chooseDateコンポーネントが使用された独自のポップアップ・ダイアログが使用されます。

- AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、trueに設定します。一致を表示しない場合はfalseに設定します。デフォルトはtrueです。

- Usage: HTML5ブラウザでの入力コンポーネントのレンダリング方法を指定します。有効な値は、auto、textおよびsearchです。デフォルトはautoです。
使用方法のタイプがsearchの場合、入力コンポーネントはHTML5の検索入力タイプとしてレンダリングされます。一部のHTML5ブラウザでは、検索テキストの消去に使用できる「取消」アイコンが追加される場合があります。

6. 「外観」セクションを開き、次の設定を行います。

- Editable: ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用にする場合は、onAccessに設定します。コンポーネントを常に編集可能にする場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、どの祖先コンポーネントでもeditable値が定義されていない場合は、alwaysの値が使用されます。

- Placeholder: 入力コンポーネントが空でフォーカスが設定されていない場合に、コンポーネントに表示されるテキストを指定します。コンポーネントにフォーカスが設定されるか、値が入力されると、プレースホルダ・テキストは非表示になります。
プレースホルダ・テキストは、ユーザーが入力コンポーネントに入力する必要のある内容を知らせる目的で使用されます。

7. オプションで、「データ」セクションを開き、TimeZoneList属性をタイム・ゾーンのカスタム・リストに設定します。

11.5.3 inputDateコンポーネントなしでのタイム・ゾーンの選択に関する必知事項

デフォルトでは、関連付けられたコンバータがタイム・ゾーンを表示するように構成されている場合、たとえばコンバータのパターンにタイム・ゾーン・プレースホルダzを含めた場合、inputDateコンポーネントにはタイム・ゾーンのドロップダウン・リストが表示されます。ユーザーは、このリストを使用してタイム・ゾーンの変更のみ行うことができます。リストは、最も一般的なタイム・ゾーンを表示するように構成されています。

ただし、inputDateコンポーネントの外部のタイム・ゾーンのリストを表示する必要がある場合があります。たとえば、「アプリケーション・プリファレンス」ページで、アプリケーションにすべてのinputDatesを表示するために使用されるタイム・ゾーンをユーザーが選択できるようにするselectOneChoiceコンポーネントを使用できます。バッキングBeanは、タイム・ゾーンIDとjava.util.TimeZoneオブジェクト間の変換を処理します。アプリケーションのinputDateインスタンスのコンバータは、タイム・ゾーンをそのタイム・ゾーン・オブジェクトにバインドします。

DateTimeUtilsクラスのAPIを使用するか、コンポーネントでEL式を使用して、このリストにアクセスできます。

DateTimeUtilsクラスのメソッドを次に示します。

- getCommonTimeZoneSelectItems (): よく使用されるタイム・ゾーンのリストを返します。

- getCommonTimeZoneSelectItems (String timeZoneId): リストの一部でない特定のタイム・ゾーンを含め、よく使用されるタイム・ゾーンのリストを返します。

ELを使用してこのリストにアクセスするには、次のいずれかの式を使用します。

- af:getCommonTimeZoneSelectItems
次に例を示します。

<f:selectItems value="#{af:getCommonTimeZoneSelectItems()}" id="tzones2" />

- af:getMergedTimeZoneSelectItems (id)
次に例を示します。

<f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" />

inputDateコンポーネントとそのタイム・ゾーンの選択リストを同じページで使用している場合は、inputDateのタイム・ゾーンのローカル値をクリアして、選択の値バインディングが優先されるようにする必要があります。そうしないと、null以外のローカル値が優先され、inputDateコンポーネントは更新されていないように見えます。例11-4では、バッキングBeanに、バインディング属性を使用したinputDateコンポーネントへの参照があります。ユーザーが新しいタイム・ゾーンを選択すると、IDが設定され、コードがinputDateのコンバータを取得し、そのタイム・ゾーンをクリアします。ページがレンダリングされる場合、コンバータのタイム・ゾーンのローカル値はnullであるため、#{demoInput.preferredTimeZone}と評価され、更新されたタイム・ゾーンを取得します。

例11-4 inputDateとタイム・ゾーンの選択リストの併用

<af:selectOneChoice label="Select a new timezone" id="soc1"
value="#{demoInput.preferredTimeZoneId}" autoSubmit="true">
<f:selectItems
value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}"
id="tzones" />
</af:selectOneChoice>
<af:inputDate label="First inputDate with timezone bound" id="bound1"
partialTriggers="tzpick"  binding="#{demoInput.boundDate1}">
<af:convertDateTime type="both" timeStyle="full"
timeZone="#{demoInput.preferredTimeZone}"/>
</af:inputDate>

DemoInputBean.java
public void setPreferredTimeZoneId(String _preferredTimeZoneId)
{
TimeZone tz = TimeZone.getTimeZone(_preferredTimeZoneId);
setPreferredTimeZone (tz);
this._preferredTimeZoneId = _preferredTimeZoneId;
}

public void setPreferredTimeZone(TimeZone _preferredTimeZone)
{
this._preferredTimeZone = _preferredTimeZone;
DateTimeConverter conv1 = (DateTimeConverter)
_boundDate1.getConverter();
conv1.setTimeZone(null);
}

11.5.4 カスタム・タイム・ゾーン・リストの作成に関する必知事項

Time Zone List属性を使用すると、inputDateコンポーネントにタイム・ゾーンのカスタム・リストを表示するように構成できます。

例11-5に示すinputDateコンポーネントでは、testInputバッキングBeanによって米国の3つのタイム・ゾーンのみを表示するように定義されたカスタム・タイム・ゾーン・リストが使用されています。

例11-5 カスタム・タイム・ゾーン・リストの使用

<af:inputDate id="idtzl" label="InputDate with timezoneList set"
timeZoneList="#{testInput.timezoneList}">
<af:convertDateTime type="both" timeStyle="full" timeZone="#{testInput.timezone}/>
</af:inputDate>

testInput.java
public void setTimezoneList(List<String> _timezoneList)
{
this._timezoneList = _timezoneList;
}
public List<String> getTimezoneList()
{
return _timezoneList;
}
private List<String> _timezoneList = new ArrayList<String>
(Arrays.asList("America/Los_Angeles", "America/Denver", "America/New_York"));

図11-21に、例11-5のバッキングBeanによって定義された、inputDateコンポーネント内のカスタム・タイム・ゾーン・リストを示します。

図11-21 inputDateコンポーネント内のカスタム・タイム・ゾーン・リスト

getCustomTimeZoneSelectItemsヘルパーELメソッドを使用して、カスタム・タイム・ゾーンをSelectItemsのリストとして取得することもできます。そのリストを、例11-6に示されているように、selectOneChoiceなどのコンポーネントに対して使用できます。

例11-6 getCustomTimeZoneSelectItemsメソッドを使用したカスタム・タイム・ゾーン・リストへのアクセス

<af:selectOneChoice label="Select a timezone" id="soctzlel" value="America/New_York">
<f:selectItems value="#{af:getCustomTimeZoneSelectItems('America/New_York', testInput.timezoneList)}" id="tzonesel" />
</af:selectOneChoice>

図11-22に、例11-6のgetCustomTimeZoneSelectItemsメソッドによって定義された、selectOneChoiceコンポーネント内のカスタム・タイム・ゾーン・リストを示します。

図11-22 selectOneChoiceコンポーネント内のカスタム・タイム・ゾーン・リスト

getCustomTimeZoneSelectItemsヘルパーELメソッドは、入力パラメータ・リストがタイムゾーン・オフセットによって保存されていることを前提としています。getCustomTimeZoneSelectItemsメソッドの詳細は、ADF Faces APIのドキュメントを参照してください。

11.6 選択コンポーネントの使用方法

選択コンポーネントを使用すると、ユーザーは項目のリストやグループから、単一または複数の値を選択できるようになります。ADF Facesには、単純なブール・ラジオ・ボタンから、ユーザーが複数の項目を選択できるリスト・ボックスまで、様々な選択コンポーネントがあります。選択コンポーネント内の項目のリストは、複数のselectItemコンポーネントで構成されています。

selectItemコンポーネントを除くすべての選択コンポーネントは、ValueChangeEventおよびAttributeChangeEventイベントを送信します。selectItemコンポーネントは、AttributeChangeEventイベントのみを送信します。これらのイベント用に、valueChangeListenerハンドラまたはattributeChangeListenerハンドラ(あるいはその両方)を作成する必要があります。

selectBooleanCheckboxコンポーネント値は、常にオブジェクトではなくブール値に設定する必要があります。図11-23に示すように、選択状態と選択解除状態を切り替えます。

図11-23 selectBooleanCheckboxコンポーネント

selectBooleanCheckboxコンポーネントには、図11-24に示すように、そのコンポーネントが選択されてもクリアされてもいないことを示す第3の混合状態も存在します。混合状態のチェック・ボックスをクリックすると、そのボックスは選択された状態になります。チェック・ボックスは選択された状態とクリアされた状態の間で切り替わりますが、クリックや他のクリック操作によって混合状態に戻ることはありません。

図11-24 混合状態のselectBooleanCheckboxコンポーネント

selectBooleanRadioコンポーネントにはブール値の選択肢が表示され、常にブール値に設定する必要があります。selectBooleanCheckboxコンポーネントとは異なり、selectBooleanRadioコンポーネントを使用すると、同じgroup属性を使用してselectBooleanRadioコンポーネントをグループ化できます。

たとえば、ユーザーが10歳から18歳までの年齢かどうかを決定する1つのブール値と、ユーザーが19歳から100歳までの年齢かどうかを決定する別のブール値があるとします。図11-25に示すように、2つのselectBooleanRadioコンポーネントをページの任意の場所に配置でき、これらは隣り合っている必要はありません。ページ内での物理的な配置にかかわらず、同じgroup値を共有するかぎり、これらの選択は相互に排他的になります。

ヒント:

各selectBooleanRadioコンポーネントは、一意のブール値にバインドされている必要があります。

図11-25 selectBooleanRadioコンポーネント

selectOneRadioコンポーネントを使用して、図11-26に示すように、ユーザーが単一値を選択できるラジオ・ボタンのリストを作成します。

図11-26 selectOneRadioコンポーネント

selectManyCheckboxコンポーネントを使用して、図11-27に示すように、ユーザーが1つ以上の値を選択できるチェックボックスのリストを作成します。

図11-27 selectManyCheckboxコンポーネント

selectOneListboxコンポーネントを使用すると、図11-28に示すように、ユーザーは影付きのボックスに表示された項目のリストから値を1つ選択できるコンポーネントを作成できます。

図11-28 selectOneListboxコンポーネント

selectManyListboxコンポーネントは、ユーザーが項目リストから多くの値を選択できるコンポーネントを作成するものです。図11-29に示すように、このコンポーネントには、チェック・ボックスのリストの先頭に表示される「すべて」チェック・ボックスが含まれます。

図11-29 selectManyListboxコンポーネント

selectOneChoiceコンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから値を1つ選択できるメニュー形式のコンポーネントを作成できます。selectOneChoiceコンポーネントは、ドロップダウン・リストの項目が比較的少ない場合に使用します。

ベスト・プラクティス:

多数の項目が必要な場合は、inputComboboxListOfValuesコンポーネントを使用します。詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

図11-30に、selectOneChoiceコンポーネントを示します。

図11-30 selectOneChoiceコンポーネント

図11-31に示すように、selectOneChoiceコンポーネントは、コンパクト・モードで表示されるように構成できます。コンパクト・モードでは、入力フィールドが小さなアイコンに置き換えられます。

図11-31 コンパクト・モードのselectOneChoiceコンポーネント

ユーザーがアイコンをクリックすると、図11-32に示されているようにドロップダウン・リストが表示されます。

図11-32 コンパクト・モードのselectOneChoiceコンポーネントのリスト

selectManyChoiceコンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから複数の値を選択できるメニュー形式のドロップダウン・コンポーネントを作成できます。このコンポーネントは、選択項目のリストの先頭に表示される「すべて」選択項目を含めるように構成できます。図11-33に示すように、選択肢の数が15より多い場合は、スクロールバーが表示されます。

図11-33 selectManyChoiceコンポーネント

デフォルトでは、すべてのselectItem子コンポーネントは、ページがレンダリングされるときに、selectManyChoiceコンポーネントの作成時に作成されます。ただし、リスト項目がアクセスされる方法が低速な場合は、パフォーマンスが低下することがあります。この遅延は、ユーザーが項目を1回選択し、その後のアクセス時に変更しない可能性が高い場合に、特に問題になることがあります。

たとえば、ページに表示される内容のフィルタに使用されるselectManyChoiceコンポーネントがあり、子selectItemコンポーネントの値がWebサービスからアクセスされるとします。ユーザーが、ページにアクセスするたびに選択内容を変更する可能性が低いことも想定します。デフォルトでは、ページがレンダリングされるたびに、ユーザーが実際に参照する必要があるかどうかにかかわらず、すべてのselectItemsを構築する必要があります。かわりに、selectManyChoiceコンポーネントのcontentDelivery属性をimmediate(デフォルト)からlazyに変更できます。lazy設定により、selectItemコンポーネントはユーザーがドロップダウンをクリックしたときにのみ作成されます。

immediateとlazyのどちらでも、ユーザーが選択を行うと、選択されたselectItemコンポーネントの値がフィールドに表示されます。ただし、遅延コンテンツ配信が使用されている場合は、その後のアクセス時に、選択された値をselectItemコンポーネントから取得する(これにより、これらのコンポーネントの作成が必要になります)かわりに、値がlazySelectedLabel属性から取得されます。この属性は、通常、選択された項目を表すStringsの配列を返すメソッドにバインドされます。selectItemコンポーネントは、ユーザーがドロップダウンを使用してこれらを表示または変更するまで作成されません。

selectManyChoiceコンポーネントでlazy配信メソッドを使用する場合は、制限事項があります。selectManyChoiceコンポーネントのコンテンツ配信とその制限事項の詳細は、11.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性に関する必知事項」を参照してください。

次のコンポーネントの場合、コントロールの上にラベルを表示させるには、これらをpanelFormLayoutコンポーネント内に配置します。

- selectOneChoice

- selectOneRadio

- selectOneListbox

- selectManyChoice

- selectManyCheckbox

- selectManyListbox

次のコンポーネントでは、セキュリティ上の理由から、属性disabled、immediate、readOnly、required、requireMessageDetailおよびvalueをクライアント上のJavaScriptから設定することはできません(詳細は、4.5.1項「クライアントでのプロパティ値の設定方法」を参照してください)。

- selectOneChoice

- selectOneRadio

- selectOneListbox

- selectBooleanRadio

- selectBooleanCheckbox

- selectManyChoice

- selectManyCheckbox

- selectManyListbox

11.6.1 選択コンポーネントの使用方法

選択コンポーネントの追加手順は、どのコンポーネントでも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItemコンポーネントを追加して構成します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.6項「選択コンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

選択コンポーネントを使用する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから選択コンポーネントをドラッグしてページにドロップします。

2. selectBooleanCheckboxおよびselectBooleanRadioコンポーネント以外のすべての選択コンポーネントで、マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが開きます。ダイアログの2番目のページで、次のプロパティを設定できます。

- Label: リストのラベルを入力します。

- RequiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

- Validator: マネージドBeanの検証メソッドに解決されるEL式を入力します(詳細は、第7章「入力の検証および変換」を参照してください)。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

注意:

selectBooleanRadioまたはselectBooleanCheckboxコンポーネントを作成し、value属性の値を入力する場合、selected属性はvalue属性の型安全な別名であるため値を入力できません。両方を使用することはできません。

- ValueChangeListener: 値変更イベントを処理するマネージドBeanのリスナーに解決されるEL式を入力します。

3. 「プロパティ」ウィンドウの「外観」セクションを開き、表11-1に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。

表11-1 選択コンポーネントの外観属性

コンポーネント

属性

selectOneRadio、selectManyCheckbox

Layout: verticalに設定すると、ボタンまたはチェック・ボックスが縦に表示されます。horizontalに設定すると、単一の水平な線に表示されます。

selectManyListbox

Size: リストに表示する項目の数に設定します。リスト内の項目数がsize属性の値より大きい場合は、スクロール・バーが表示されます。

selectManyListbox、selectManyChoice

SelectAllVisible: trueに設定すると、ユーザーがリスト内のすべての項目を選択できる「すべて」選択が表示されます。

selectOneChoice

Mode: compactに設定すると、ユーザーがドロップダウン・アイコンをクリックした場合にのみコンポーネントが表示されます。

selectOneRadio、selectOneListbox、selectOneChoice

UnselectedLabel: 値がnullであり、何も選択されていないことを示すオプションのテキストを入力します。unselectedLabelが設定されておらず、コンポーネントに選択した値が含まれない場合、ラベルおよび値として空の文字列を持つオプションが最初のオプションとして選択ボックスにレンダリングされます(すでに定義された空のオプションが存在しない場合)。unselectedLabel値を定義する場合は、required属性をtrueに設定する必要があります。そうしないと、2つの空白オプションがリストに表示されます。オプションが正しく選択され、unselectedLabelが設定されていない場合、空のオプションはレンダリングされません。

4. 「プロパティ」ウィンドウの「動作」セクションを開き、表11-2に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。

表11-2 選択コンポーネントの動作属性

コンポーネント

属性

ブール選択コンポーネントを除くすべて

ValuePassThru: クライアントに値を渡すかどうかを指定します。valuePassThruがfalseの場合、この値およびオプションの値は、索引に変換されてからクライアントに送信されます。そのため、valuePassThruがfalseの場合、値またはオプション、あるいはその両方としてカスタム・オブジェクトを使用するときに、独自のコンバータを記述する必要はありません。クライアント側での実際の値を知る必要がある場合は、valuePassThruをtrueに設定できます。これにより、カスタム・コンバータが使用可能な場合は、カスタム・コンバータを使用して、クライアントに値が渡されます。カスタム・コンバータは、カスタム・オブジェクトを使用する場合に必要です。デフォルトは、falseです。

選択コンポーネントがADFモデル・バインディングを使用している場合、この値は無視されます。

selectBooleanRadio

Group: 同じgroup値を持つその他すべてのselectBooleanRadioコンポーネントに対して相互に排他的であるグループの名前を入力します。

5. ユーザーがマウスを値の上に移動するまでselectOneChoiceまたはselectManyChoiceコンポーネントの値を読取り専用として表示する場合は、「外観」セクションを開き、EditableをonAccessに設定します。コンポーネントを常に編集可能にする場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、どの祖先コンポーネントでもeditable値が定義されていない場合は、alwaysの値が使用されます。

6. ページがレンダリングされるたびにselectManyChoiceの子selectItemコンポーネントを作成しない場合は、次の操作を実行します。

- 選択した項目のラベルを格納でき、それらのラベルを文字列の配列として返すロジックを作成します。

- 「拡張」セクションを開き、ContentDeliveryをlazyに設定します。

- LazySelectedLabelを、選択した項目の配列を返すメソッドにバインドします。

遅延コンテンツ配信の使用には制限があることに注意してください。selectManyChoiceコンポーネントのコンテンツ配信の詳細は、11.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性に関する必知事項」を参照してください。

7. af:selectBooleanCheckboxコンポーネントを、そのコンポーネントが選択されてもクリアされてもいないことを示す不確定(または混合)状態で表示する場合は、「拡張」セクションを開いてnullValueMeans属性をmixedに設定します。
ユーザーがシングル・クリックによってselectBooleanCheckboxコンポーネントを混合状態にすることはできません。たとえば、チェック・ボックスの一部の(すべてではなく)子オプションが有効または無効になっているときに、そのチェック・ボックスが混合状態として表示されるようにすることができます。この混合状態は、そのチェック・ボックスのすべての子オプションが有効になると選択状態に変わり、すべての子オプションが無効になると選択解除状態に変わります。この動作は自動ではなく、バックエンド・アプリケーション・コードによって管理する必要があります。

8. ブール・コンポーネントの場合は、ブール・コンポーネントの子として、任意の数のselectItemコンポーネントをドラッグ・アンド・ドロップします。これらはリストの項目を表します(その他の選択コンポーネントの場合は、手順2のダイアログにより自動的に追加されます)。

9. selectItemコンポーネントが選択された状態で、「プロパティ」ウィンドウで「共通」セクションを開き、設定されていない場合はvalue属性の値を入力します。これが送信される値です。

10. 「外観」セクションを開き、設定されていない場合はLabelの値を入力します。これがリストに表示されるテキストです。

11. 項目が無効化された状態でリストに表示されるようにする場合は、「動作」セクションを開いて、Disabledをtrueに設定します。

11.6.2 SelectManyChoiceコンポーネントのcontentDelivery属性に関する必知事項

selectManyChoiceコンポーネントのcontentDelivery属性がimmediate(デフォルト)に設定されている場合は、次のようになります。

- ページへの初回アクセス時:

- ページがレンダリングされると、selectManyChoiceおよびすべてのselectItemコンポーネントが作成されます。これは、多くの項目がある場合、またはselectItemコンポーネントの値がたとえばWebサービスからアクセスされる場合に、パフォーマンスの問題を引き起こすことがあります。

- selectManyChoiceコンポーネントのレンダリング時に、まだ何も選択されていないためフィールドには何も表示されません。

- ユーザーがドロップ・ダウンをクリックすると、すべての項目が表示されます。

- ユーザーが項目を選択すると、選択したselectItemコンポーネントに対応するラベルがフィールドに表示されます。

- ページが送信されると、値がモデルにポストバックされます。

- その後のアクセス時: ページがレンダリングされると、selectManyChoiceおよびすべてのselectItemコンポーネントが再び作成されます。選択したselectItemコンポーネントのラベルがフィールドに表示されます。これは、ページへの初回アクセス時と同じパフォーマンスの問題の原因となります。

selectManyChoiceコンポーネントのcontentDelivery属性がlazyに設定されている場合は、次のようになります。

- ページへの初回アクセス時:

- selectManyChoiceはページがレンダリングされると作成されますが、selectItemコンポーネントは作成されません。

- selectManyChoiceコンポーネントのレンダリング時に、まだ何も選択されていないためフィールドには何も表示されません。

- ユーザーがドロップ・ダウンをクリックすると、selectItemコンポーネントが作成されます。この状況が発生している間、ユーザーには"ビジー"・スピナーが表示されます。コンポーネントが作成されると、すべての項目が表示されます。

- ユーザーが項目を選択すると、選択したselectItemコンポーネントに対応するラベルがフィールドに表示されます。

- ページが送信されると、値がモデルにポストバックされます。

- その後のアクセス時:

- ページの初回レンダリング時には、selectManyChoiceコンポーネントのみ作成されます。この時点で、lazySelectedLabel属性の値を使用して、選択された項目が表示されます。

- ユーザーがドロップ・ダウンをクリックすると、selectItemコンポーネントが作成されます。この状況が発生している間、ユーザーには"ビジー"・スピナーが表示されます。コンポーネントが作成されると、すべての項目が表示されます。
selectItemコンポーネントが作成されると、selectManyChoiceコンポーネントはcontentDelivery属性がimmediateに設定されているかのように動作し、selectItemコンポーネントの実際の値を使用して、選択された項目を表示します。

selectManyChoiceコンポーネントでの遅延コンテンツ配信の使用には、次の制限があります。

- selectManyChoiceの値をリクエスト・スコープに格納することはできません。ポストバックでは、value属性はクライアントから返された内容をデコードするかわりにモデルからアクセスされます。値がリクエスト・スコープに格納される場合、その値は空になります。リクエスト・スコープには値を格納しないでください。

- ポストバックでは、コンバータはコールされません。ポストバックをコンバータに依存している場合は、遅延コンテンツ配信を使用しないでください。

- スクリーン・リーダー・モードでは、contentDelivery属性は無視されます。selectItemコンポーネントは、ページのレンダリング時に必ず作成されます。

11.7 シャトル・コンポーネントの使用方法

selectManyShuttleおよびselectOrderShuttleコンポーネントを使用すると、ユーザーが一方のリスト・ボックスからもう一方のリスト・ボックスに項目を移動するための2つのリスト・ボックスおよびボタンを作成できます。ユーザーは、先行(「使用可能な値」)リスト・ボックスと後続(「選択した値」)リスト・ボックスの間を移動させる単一の項目または複数の項目を選択できます。どちらのコンポーネントでも、コントロールの上にラベルを表示する場合には、それらをpanelFormLayoutコンポーネント内に配置します。

図11-34に、selectManyShuttleコンポーネントを示します。

図11-34 selectManyShuttleコンポーネント

図11-35に示すように、selectOrdershuttleコンポーネントには、ユーザーが「選択した値」リスト・ボックスの値を並べ替えるために使用する上矢印および下矢印ボタンを追加で含めることができます。リストを並べ替えると、ValueChangeEventイベントが送信されます。readOnly属性をtrueに設定した場合は、並べ替える値が、後続リスト(「選択した値」)に表示される選択済の値であることを確認します。

図11-35 selectOrderShuttleコンポーネント

他のselectManyコンポーネント同様、これらのコンポーネントのvalue属性は、含まれるselectItemコンポーネントの1つの値と一致する値のListまたはArrayである必要があります。selectItemsの1つの値がListまたはArrayにある場合、その項目は後続リストに表示されます。selectManyListboxコンポーネントをselectManyShuttleに直接変換することもできます。リストボックスでどの項目が選択されているかを確認するvalueにかわり、これがselectOrderShuttleコンポーネントの後続リストに表示される項目の選択に影響します。

その他の選択コンポーネント同様、項目のリストまたは配列は、selectManyShuttleまたはselectOrderShuttleコンポーネントにネストしているselectItemコンポーネントで構成されています。例11-7に、ユーザーがファイル・タイプのリストから上位5つのファイル・タイプを選択できるselectOrderShuttleコンポーネントのサンプルを示します。

例11-7 selectOrderShuttleのJSFページ・コード

<af:selectOrderShuttle value="#{helpBean.topFive}"
leadingHeader="#{explorerBundle['help.availableFileTypes']}"
trailingHeader="#{explorerBundle['help.top5']}"
simple="true" id="sos1">
<af:selectItem label="XLS" id="si1"/>
<af:selectItem label="DOC" id="si2"/>
<af:selectItem label="PPT" id="si3"/>
<af:selectItem label="PDF" id="si4"/>
<af:selectItem label="Java" id="si5"/>
<af:selectItem label="JWS" id="si6"/>
<af:selectItem label="TXT" id="si7"/>
<af:selectItem label="HTML" id="si8"/>
<af:selectItem label="XML" id="si9"/>
<af:selectItem label="JS" id="si10"/>
<af:selectItem label="PNG" id="si11"/>
<af:selectItem label="BMP" id="si12"/>
<af:selectItem label="GIF" id="si13"/>
<af:selectItem label="CSS" id="si14"/>
<af:selectItem label="JPR" id="si15"/>
<af:selectItem label="JSPX" id="si16"/>
<f:validator validatorId="shuttle-validator"/>
</af:selectOrderShuttle>

selectOrdershuttleコンポーネントのreorderOnly属性をtrueに設定すると、移動機能が無効にされ、「選択した値」リスト・ボックスのみが表示されます。図11-36に示すように、ユーザーは、リスト・ボックス内の項目の並替えのみを実行できます。

図11-36 並替え専用モードのselectOrderShuttleコンポーネント

11.7.1 selectManyShuttleまたはselectOrderShuttleコンポーネントの追加方法

シャトル・コンポーネントの追加手順は、どちらのコンポーネントも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItemコンポーネントを追加して構成します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.7項「シャトル・コンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

selectManyShuttleまたはselectOrderShuttleコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「シャトル」または「シャトル(順序付け済)」をドラッグし、ページにドロップします。

2. マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが表示されます。ダイアログの2番目のページで、次の設定を行うことができます。

- Label: リストのラベルを入力します。

- RequiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

- Size: リストの表示サイズ(項目の数)を指定します。指定するサイズは、10から20項目の範囲である必要があります。属性が設定されていない場合、または10より小さい値の場合、サイズはデフォルトまたは最小値の10になります。指定された属性値が20項目より多い場合、サイズは最大値の20になります。

- Validator: マネージドBeanの検証メソッドに解決されるEL式を入力します。

- Value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

- ValueChangeListener: 値変更イベントを処理するマネージドBeanのリスナーに解決されるEL式を入力します。

3. 「プロパティ」ウィンドウで「外観」セクションを開き、次の設定を行います。

- Layout: コンポーネントを水平または垂直レイアウトのどちらにするかを指定します。デフォルトはhorizontalで、先行および後続のリスト・ボックスは相互に隣り合って表示されます。verticalに設定すると、先行のリスト・ボックスは後続のリスト・ボックスの上に表示されます。

- LeadingHeader: シャトル・コンポーネントの先行リストのヘッダー・テキストを指定します。

- LeadingDescShown: trueに設定すると、先行のリスト・ボックスの下部に選択された項目の説明が表示されます。

- TrailingHeader: シャトル・コンポーネントの後続リストのヘッダーを指定します。

- TrailingDescShown: trueに設定すると、後続のリスト・ボックスの下部に選択された項目の説明が表示されます。

4. 「動作」セクションを開き、オプションで次の属性を設定します。

- ValuePassThru: クライアントに値を渡すかどうかを指定します。valuePassThruがfalseの場合、この値およびオプションの値は、索引に変換されてからクライアントに送信されます。そのため、valuePassThruがfalseの場合、値またはオプション、あるいはその両方としてカスタム・オブジェクトを使用するときに、独自のコンバータを記述する必要はありません。クライアント側での実際の値を知る必要がある場合は、valuePassThruをtrueに設定できます。これにより、カスタム・コンバータが使用可能な場合は、カスタム・コンバータを使用して、クライアントに値が渡されます。カスタム・コンバータは、カスタム・オブジェクトを使用する場合に必要です。デフォルトはfalseです。

- ReorderOnly (selectOrderShuttleコンポーネントのみ): シャトル・コンポーネントを並替え専用モードにするかどうかを指定します。このモードでは、ユーザーは値リストの順序を変更できますが、追加や削除はできません。

5. 「構造」ウィンドウでselectItemコンポーネントの1つを選択し、「プロパティ」ウィンドウで必要な属性を設定します。

ヒント:

先行または後続のリスト・ボックスに説明を表示することを選択した場合は、各selectItemコンポーネントのshortDesc属性に値を設定する必要があります。

11.7.2 選択イベントのクライアント・リスナーの使用方法に関する必知事項

項目の選択のイベントに応答して処理を実行するJavaScriptコードを作成することで、ユーザーが選択された各項目をあるリストから別のリストに移動する前に、その項目に関する情報をユーザーに提供できます。たとえば、コードでその項目に関する追加情報を取得し、ユーザーが項目を移動するかどうかの選択を行えるようにポップアップとして表示できます。図11-37に、ユーザーがMeyersを選択し、ポップアップがこの選択に関する追加情報を提供するselectManyShuttleコンポーネントを示します。

図11-37 selectionListenerが含まれるselectManyShuttle

この機能は、selectManyShuttleまたはselectOrderShuttleコンポーネントにクライアント・リスナーを追加し、このイベントを処理するJavaScriptメソッドを作成して実装します。JavaScriptコードは、ユーザーがリストから項目を選択すると実行されます。イベントのクライアント・リスナーの詳細は、4.4項「クライアント・イベントのリスニング」を参照してください。

選択イベントを処理するシャトル・コンポーネントにクライアント・リスナーを追加する方法:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「リスナー」グループから「クライアント・リスナー」をドラッグし、シャトル・コンポーネントに子としてドロップします。

2. 「クライアント・リスナーの挿入」ダイアログで、「メソッド」フィールドに関数名(次の手順でこの関数を実装します)を入力し、「タイプ」ドロップダウンから「propertyChange」を選択します。
たとえば、関数としてshowDetailsを入力した場合、JDeveloperにより、例11-8に太字で示されたコードが入力されます。

例11-8 選択を登録するためのclientListenerの使用

<af:selectManyShuttle value="#{demoInput.manyListValue1}" id="sms1"
valuePassThru="true" ...>
<af:clientListener type="propertyChange" method="showDetails"/>
<af:selectItem label="coffee" value="bean" id="si1" />
...
</af:selectManyShuttle>

このコードにより、showDetails関数は、プロパティ値が変更されるたびにコールされます。

3. JavaScriptで、前の手順で入力された関数を実装します。この関数により、次の操作が実行されます。

- イベントのソースを取得して、シャトル・コンポーネントを取得します。

- クライアントJavaScript APIコールを使用して、選択した項目の情報を取得します。

例11-9では、AdfShuttleUtils.getLastSelectionChangeをコールして、最後に選択された項目の値が取得されています。

例11-9 選択の処理に使用されるJavaScriptメソッドshowDetailsのサンプル

function showDetails(event)
{
if(AdfRichSelectManyShuttle.SELECTION == event.getPropertyName())
{
var shuttleComponent = event.getSource();
var lastChangedValue =    AdfShuttleUtils.getLastSelectionChange(shuttleComponent, event.getOldValue());
var side = AdfShuttleUtils.getSide(shuttleComponent, lastChangedValue);
if(AdfShuttleUtils.isSelected(shuttleComponent, lastChangedValue))
{
//do something...
}
else
{
//do something else
}
if(AdfShuttleUtils.isLeading(shuttleComponent, lastChangedValue))
{
//queue a custom event (see serverListener) to call a java method on the server
}
}
}

11.8 richTextEditorコンポーネントの使用方法

richTextEditorコンポーネントは、書式設定されたテキストを使用できる入力フィールドを提供します。ラベル、テキストおよびメッセージもサポートされています。ユーザーは、フォント名、サイズ、スタイルの変更、順序付けられたリストの作成、およびテキストの両端の調整を実行でき、その他の様々な機能も使用できます。richTextEditorコンポーネントは、HTMLソース・ファイルの編集にも使用できます。2つのコマンド・ボタンを使用して、標準の書式設定されたテキストの編集とHTMLソース・ファイルの編集を相互に切り替えられます。図11-38に、標準のリッチ・テキスト編集モードのリッチ・テキスト・エディタ・コンポーネントを示します。

図11-38 標準の編集モードのrichTextEditorコンポーネント

図11-39に、ソース・コード編集モードのエディタを示します。

図11-39 ソース編集モードのrichTextEditor

次にサポートされているその他の機能を示します。

- フォント・タイプ

- フォント・サイズ

- リンク付け/リンク解除

- スタイルのクリア

- 元に戻す/やり直し

- 太字/イタリック/下線

- 下付き/上付き

- 調整(左、中央、右、均等)

- 順序付けられたリスト/順序付けられていないリスト

- インデント

- 文字色/背景色

- リッチ・テキスト編集モード/ソース・コード編集モード

リッチ・テキスト・エディタの値(入力されたテキスト)は、整形式のXHTMLフラグメントです。値の書式設定を可能にするために、ブラウザ固有の要件で値の一部が変更される場合があります。また、セキュリティ上の理由から、スクリプト関連タグや属性などの一部の機能が削除されます。このコンポーネントにより、ユーザーによる最小限の変更のみが記録されるという保証はありません。エディタでXHTMLドキュメントを編集しているため、次の要素が変更される可能性があります。

- 意味のない空白

- 要素の最小化

- 要素タイプ

- 属性の順序

- 文字エンティティの使用

エディタでサポートされているのは、次の例外を除いて4つのHTMLタグのみです。

- script、noscript

- frame、frameset、noframes

- フォーム関連要素(input、select、optgroup、option、textarea、form、button、label、isindex)

- ドキュメント関連要素(html、head、body、meta、title、base、link)

richTextEditorコンポーネントでは、コンテンツを取得するタグ(applet、iframe、object、imgおよびaなど)もサポートされています。ブラウザで許可されているのは同じドメインのコンテンツとの対話のみであるため、iframeタグの場合は、コンテンツがページのその他の部分と対話できないようにする必要があります。ただし、ページのこの部分はアプリケーションの管理外です。

richTextEditorコンポーネントではpxやemなどのフォント単位はサポートされていませんが、HTML仕様に説明されているように1から7のフォント・サイズはサポートされています。埋込みタグや未知のタグ(<foo>など)はサポートされていません。

クライアント側では、richTextEditorコンポーネントで、getValueおよびsetValueメソッドがサポートされていません。クライアント上のコンポーネントの値が、サーバー上の値と同一であるという保証はありません。そのため、richTextEditorでは、クライアント側のコンバータおよびバリデータがサポートされていません。それでも、サーバー側のコンバータおよびバリデータは機能します。

リッチ・テキスト・エディタでは、ValueChangeEventおよびAttributeChangeEventイベントが送信されます。必要に応じて、これらのイベント用にvalueChangeListenerおよびattributeChangeListenerハンドラを作成します。

コマンド・コンポーネントと連携して、richTextEditorコンポーネントに特定のテキストを挿入するrichTextEditorInsertBehaviorタグも構成できます。入力するテキストには、簡単な文字列、またはマネージドBeanなどに保持されている事前フォーマット済テキストを指定できます。

デフォルトでは、richTextEditorコンポーネントのツールバーでは、図11-40に示すように、ユーザーはフォント、フォントのサイズと太さ、テキストの文字位置、表示モードなどの多くの側面を変更できます。

図11-40 richTextEditorコンポーネントのツールバー

図11-41に、カスタマイズされているツールバーを示します。ツールバー・ボタンの多くは削除されており、カスタム・ツールバー・ボタンおよびメニューのあるツールバーが追加されています。

図11-41 カスタマイズされたrichTextEditorのツールバー

11.8.1 richTextEditorコンポーネントの追加方法

richTextEditorコンポーネントを追加した後で、テキストを特定の場所に挿入できるように構成し、ツールバーをカスタマイズすることもできます。詳細は、11.8.2項「richTextEditorコンポーネントへのテキストの挿入機能を追加する方法」および11.8.3項「ツールバーのカスタマイズ方法」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

richTextEditorコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「リッチ・テキスト・エディタ」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、value属性を設定します。

3. 「外観」セクションを開き、次の設定を行います。

- Rows: 表示される文字の概数で編集ウィンドウの高さを指定します。

- Columns: 表示される文字の概数で編集ウィンドウの幅を指定します。

- Label: コンポーネントのラベルを指定します。

4. 「動作」セクションを開き、次の設定を行います。

- EditMode: WYSIWYGまたはソース・モードを使用してエディタを表示するかどうかを選択します。

- ContentDelivery: コンポーネントが最初にレンダリングされる際に、エディタ内のデータをフェッチするかどうかを指定します。contentDelivery属性の値がimmediateの場合、レンダリングされる際に、データがフェッチされてコンポーネントに表示されます。値がlazyに設定されている場合は、データがフェッチされて後続のリクエスト中にクライアントに送信されます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

ヒント:

richTextEditorコンポーネントの幅は、全幅または100%に設定できます。ただし、これが確実に機能するのは、エディタがジオメトリ管理の親コンポーネントに配置されている場合のみです。panelFormLayoutまたはpanelGroupLayoutなどの配置レイアウト・コンテナに配置されていると、機能しない場合があります。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

11.8.2 richTextEditorコンポーネントへのテキストの挿入機能を追加する方法

richTextEditorコンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてrichTextEditorInsertBehaviorタグを追加します。

始める前に

リッチ・テキスト・エディタ・コンポーネントに関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

11.8.1項「richTextEditorコンポーネントの追加方法」の説明に従ってrichTextEditorコンポーネントを作成する必要があります。clientComponent属性をtrueに設定します。

テキスト挿入動作を追加する手順:

1. テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順の詳細は、20.3.1項「ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法」を参照してください。

2. 「コンポーネント」ウィンドウで、「操作」パネルの「動作」グループから「リッチ・テキスト・エディタの挿入動作」をドラッグして、コマンド・コンポーネントに子としてドロップします。

3. 「リッチ・テキスト・エディタの挿入動作」ダイアログで、次の内容を入力します。

- For: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するrichTextEditorコンポーネントに移動して選択します。

- Value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoiceコンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。ユーザーに事前フォーマット済テキストを入力させる場合は、そのテキストに解決されるEL式を入力します。たとえば、例11-10は、demoInputマネージドBeanの属性の値としての事前フォーマット済テキストを示しています。

例11-10 マネージドBeanの事前フォーマット済テキスト

private static final String _RICH_INSERT_VALUE =
"<p align=\"center\" style=\"border: 1px solid gray;
margin: 5px; padding: 5px;\">" +
"<font size=\"4\"><span style=\"font-family: Comic Sans MS,
Comic Sans,cursive;\">Store Hours</span></font><br/>\n" +
"<font size=\"1\">Monday through Friday 'til 8:00 pm</font><br/>\n" +
"<font size=\"1\">Saturday &amp; Sunday 'til 5:00 pm</font>" +
"</p>";

例11-11に、テキストがrichTextEditorInsertBehaviorタグからどのように参照されるかを示します。

例11-11 richTextEditorInsertBehaviorタグの使用

<af:richTextEditor id="idRichTextEditor" label="Rich text value"
value="#{demoInput.richValue2}"/>
. . .
</af:richTextEditor>
<af:button text="Insert Template Text" id="b1">
<af:richTextEditorInsertBehavior for="idRichTextEditor"
value="#{demoInput.richInsertValue}"/>
</af:button>

4. デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、triggerType属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。

11.8.3 ツールバーのカスタマイズ方法

作成するカスタム・ファセットに、追加するツールバーおよびツールバー・ボタンを配置します。次に、含まれている項目の表示方法および表示場所を決定するキーワードとともに、ツールバーの属性からファセットを参照します。

richTextEditorコンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてrichTextEditorInsertBehaviorタグを追加します。

始める前に

リッチ・テキスト・エディタ・コンポーネントに関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

ツールバーをカスタマイズする手順:

1. 「コンポーネント」ウィンドウのJSFページで、追加するツールバーの各セクションについて「コア」パネルから「ファセット」をドラッグ・アンド・ドロップします。
たとえば、図11-41に示されているカスタム・ボタンを追加するには、2つの<f:facet>タグを追加します。各ファセットには、ページに対する一意な名前を付けてください。

ヒント:

ADF Facesの今後のリリースと競合が生じないようにするには、すべてのファセット名をcustomToolbarで開始します。

2. 「コンポーネント」ウィンドウの「ADF Faces」ページで、「メニューおよびツールバー」パネルから「ツールバー」を各ファセットにドラッグ・アンド・ドロップし、ツールバー・ボタンまたはその他のコンポーネントを追加し、必要に応じて構成します。
ツールバーとツールバー・ボタンの詳細は、16.3項「ツールバーの使用方法」を参照してください。

3. richTextEditorコンポーネントを選択した状態で、「プロパティ」ウィンドウの「外観」セクションで、toolboxLayout属性のドロップダウン・アイコンをクリックし、「編集」を選択します。

4. 「プロパティの編集: ToolboxLayout」ダイアログで、カスタム・ファセット内のコンテンツを表示する順序に従ってファセット名を追加します。これらのファセットのみでなく、次のキーワードを使用して、デフォルトのツールバーのすべてまたは一部を含めることもできます。

- all: デフォルトのツールバーのすべてのツールバー・ボタンおよびテキスト。allが入力された場合、カスタムでないボタンのキーワードは無視されます。

- font: フォント選択およびフォント・サイズ・ボタン。

- history: 元に戻すボタンと再実行ボタン。

- mode: リッチ・テキスト・モードおよびソース・コード・モード・ボタン。

- color: 前景色および背景色ボタン。

- formatAll: 太字、イタリック、下線、上付き、下付き、取消線ボタン。formatAllが指定されている場合、formatCommonおよびformatUncommonは無視されます。

- formatCommon: 太字、イタリックおよび下線ボタン。

- formatUncommon: 上付き、下付きおよび取消線ボタン。

- justify: 左、中央、右および両端揃えボタン。

- list: 箇条書きおよび番号付きリスト・ボタン。

- indent: アウトデントおよびインデント・ボタン。

- link: リンクの追加および削除ボタン。

たとえば、customToolbar1およびcustomToolbar2という名前の2つのファセットを作成し、デフォルトのツールバー全体をカスタム・ツールバーの間に表示する場合は、次のリストを入力します。

- customToolbar1

- all

- customToolbar2

ツールバーのレイアウトは、次のキーワードを使用して決定することもできます。

- newline: 新しい行の次の名前付きファセット(またはtoolboxLayout属性のリストの次のキーワード)にツールバーを配置します。たとえば、customToolbar2ファセットのツールバーを新しい行に表示する場合は、次のリストを入力します。

- customToolbar1

- all

- newline

- customToolbar2

かわりに、デフォルトのすべてのツールバーを使用せず、フォント、色および共通書式設定ボタンのみ使用し、これらのボタンを新しい行に表示する場合は、次のリストを入力します。

- customToolbar1

- customToolbar2

- newline

- font

- color

- formatCommon

- stretch: 使用可能なすべての領域を埋めるために拡大されるspacerコンポーネントを追加して、次の名前付きファセット(またはデフォルトのツールバーの次のキーワード)がツールバーに右揃えで表示されるようにします。

11.9 ファイルのアップロード機能の使用方法

inputFileコンポーネントを使用すると、ユーザーにファイルのアップロード機能および更新機能を提供できます。このコンポーネントを使用すると、ユーザーはローカル・ファイルを選択し、サーバー上の選択可能な場所にアップロードできます(ファイルをサーバーからユーザーにダウンロードするには、20.5.1項「ファイルをダウンロードするためのアクション・コンポーネントの使用方法」を参照してください)。

inputFileコンポーネントにより、ファイルのアップロード時に標準のValueChangeEventイベントが送信され、ロード・プロセスが透過的に管理されます。inputFileコンポーネントのvalueプロパティは、ファイルのアップロード時に、org.apache.myfaces.trinidad.model.UploadedFileクラスのインスタンスに設定されます。

アップロード・プロセスを開始するには、まず、アップロードを許可するようにページのフォームを構成する必要があります。次に、図11-42に示すように、ファイルのアップロードに使用できるコマンド・ボタンなどのアクション・コンポーネントを作成します。

図11-42 inputFileコンポーネント

ファイルがアップロードされ、(最初のロードが成功した後またはその値が初期値として指定された後に)inputFileの値がnull以外の場合は、「更新」ボタンを作成できます。図11-43に示されているように、このボタンは「参照」ボタンのかわりに表示されます。これにより、ユーザーはinputFileコンポーネントの値を変更できます。

図11-43 更新モードのinputFileコンポーネント

注意:

ファイルがアップロードされると、inputFileコンポーネントの値はorg.apache.myfaces.trinidad.model.UploadedFileクラスのインスタンスになります。したがって、値(つまりファイル自体)にアクセスする必要がある場合は、このクラスにアクセスする必要があります。binding属性を通じてコンポーネントにアクセスすると、コンポーネントにのみアクセスし、アップロード・ファイルにはアクセスしません。

readOnlyプロパティをtrueに設定すると、特定のファイルのみをロードできるようにコンポーネントを指定することもできます。図11-44に示すように、このモードでは、指定されたファイルのみをロードできます。

図11-44 読取り専用モードのinputFileコンポーネント

inputFileコンポーネントでは、デフォルトでファイルを1つのみアップロードできますが、複数のファイルをアップロードするように構成することもできます。図11-45に、複数のファイルをアップロードするように構成されたinputFileコンポーネントを示します。

図11-45 複数ファイル用のinputFileコンポーネント

ユーザーは、「参照」ボタンで表示される「ファイルのアップロード」ダイアログで複数のファイルを選択するか、コンポーネントのドロップ・セクションに複数のファイルをドラッグ・アンド・ドロップできます。ドロップ・セクションにファイルが表示されたら、図11-46に示すように、「アップロード」をクリックしてファイルをアップロードします。

図11-46 アップロード準備のできたファイルを表示したinputFileコンポーネント

inputFileコンポーネントは、h:formタグまたはaf:formタグに配置できますが、どちらの場合も、ファイルのアップロードをサポートするようにformタグを設定必要があります。JSFの基本HTMLであるh:formを使用する場合は、enctypeをmultipart/form-dataに設定します。これにより、リクエストはサーバーへのファイル・アップロードをサポートするためのマルチパート・リクエストになります。ADF Facesのaf:formタグを使用している場合は、usesUploadをtrueに設定します。これは、enctypeをmultipart/form-dataに設定してファイル・アップロードをサポートするのと同じ機能を実行します。

ADF Facesフレームワークでは、ファイルの汎用アップロードが実行されます。アップロード後にファイルを処理(たとえば、xmlファイル、pdfファイルなどの処理)するには、actionListenerまたはアクション・メソッドを作成する必要があります。

inputFileコンポーネントのvalueは、org.apache.myfaces.trinidad.model.UploadedFileインタフェースのインスタンスです。このAPIを使用すると、ファイル名、MIMEタイプ、サイズだけでなく、ファイルの実際のバイト・ストリームを取得できます。

注意:

APIを使用して、ファイルのアップロード元に関するパス情報をクライアントから取得することはできません。

アップロードされたファイルは、ファイルとしてファイル・システムに格納できますが、メモリーに格納することもできます。この違いがAPIよって表面化されることはありません。フィルタを使用すると、リクエストの完了後、確実にUploadedFileコンテンツがクリーン・アップされます。このため、複数のリクエストにわたってUploadedFileオブジェクトを有効にキャッシュすることはできません。ファイルを保持する必要がある場合は、リクエストが完了する前にファイルを永続記憶域にコピーする必要があります。

たとえば、例11-12に示すように、ファイルを保存するかわりに、マネージドBeanをValueChangeEventイベントへのレスポンスとして使用し、ファイルのアップロードが成功したという内容のメッセージを追加します。

例11-12 アップロード・メッセージを表示するためのvalueChangeListenerの使用

JSF Page Code ----->
<af:form usesUpload="true" id="f1">
<af:inputFile label="Upload:"
valueChangeListener="#{managedBean.fileUploaded}" id="if1"/>
<af:button text="Begin" id="b1"/>
</af:form>

Managed Bean Code ---->
import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;
import javax.faces.event.ValueChangeEvent;
import org.apache.myfaces.trinidad.model.UploadedFile;

public class ABackingBean
{
...
public void fileUploaded(ValueChangeEvent event)
{
UploadedFile file = (UploadedFile) event.getNewValue();
if (file != null)
{
FacesContext context = FacesContext.getCurrentInstance();
FacesMessage message = new FacesMessage(
"Successfully uploaded file " + file.getFilename() +
" (" + file.getLength() + " bytes)");
context.addMessage(event.getComponent().getClientId(context), message);
// Here's where we could call file.getInputStream()
}
}
}

また、例11-13に示すように、値をマネージドBeanに直接バインドすることでアップロードを処理できます。

例11-13 マネージドBeanへの値のバインド

JSF Page Code ---->
<af:form usesUpload="true">
<af:inputFile label="Upload:" value="#{managedBean.file}" id="if1"/>
<af:button text="Begin" action="#{managedBean.doUpload}" id="b1"/>
</af:form>

Managed Bean Code ---->
import org.apache.myfaces.trinidad.model.UploadedFile;public class AManagedBean
{
public UploadedFile getFile()
{
return _file;
}
public void setFile(UploadedFile file)
{
_file = file;
}

public String doUpload()
{
UploadedFile file = getFile();
// ... and process it in some way
}
private UploadedFile _file;

}

注意:

inputFileコンポーネントを使用して複数のファイルをアップロードする場合、event.getNewValue()の戻り型はUploadedFileではなく、List<UploadedFile>になります。また、マネージドBeanの値バインディングも、UploadedFileではなく、List<UploadedFile>になります。

11.9.1 inputFileコンポーネントの使用方法

Javaクラスは、inputFileコンポーネントにバインドする必要があります。このクラスにより、アップロードしたファイルの値が含まれます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

inputFileコンポーネントを追加する手順:

1. 入力ファイルの値を保持するJavaクラスを作成します。org.apache.myfaces.trinidad.model.UploadedFileインタフェースのインスタンスであることが必要です。

2. af:formコンポーネントを選択し、UsesUploadをtrueに設定します。

3. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから「入力ファイル」をドラッグしてページにドロップします。

4. valueを手順1で作成したクラスに設定します。

5. ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用として表示する場合は、「外観」セクションを開き、EditableをonAccessに設定します。コンポーネントを常に編集可能にする場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、どの祖先コンポーネントでもeditable値が定義されていない場合は、alwaysの値が使用されます。

6. 「コンポーネント」ウィンドウで、「一般コントロール」パネルから任意のコマンド・コンポーネントをドラッグしてページにドロップします。これは、アップロード・プロセスの開始に使用されます。

7. コマンド・コンポーネントが選択された状態で、actionListener属性を、アップロード後にファイルを処理するリスナーに設定します。

11.9.2 複数のファイルをアップロードするようにinputFileコンポーネントを構成する方法

inputFileコンポーネントで複数のファイルをアップロードするには、uploadTypeおよびmaximumFiles属性を使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

複数のファイルをアップロードするようにinputFileコンポーネントを構成するには:

1. フォームで、inputFileコンポーネントを選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開き、次の設定を行います。

- autoHeightRows: inputFileコンポーネントの高さを決定するための行数を指定します。rowsの値より小さい値を指定する必要があります。

- rows: ドロップ・セクションに表示されるファイル数を指定します。デフォルトでは、これは5に設定されています。

3. 「拡張」セクションを開き、maximumFiles属性を設定して、ユーザーがアップロードできるファイルの最大数を指定します。デフォルトでは、これは1に設定され、1ファイルのみのアップロードが許可されています。1より小さい値(たとえば-1)に設定すると、無制限の数のファイルをアップロードできるようになります。

4. 「動作」セクションを開き、uploadType属性を設定して、ファイルを自動的にアップロードするか、ファイルをアップロードするためにユーザーが「アップロード」ボタンをクリックする必要があるかを指定します。
表11-3に、uploadType属性に指定可能な値を示します。

表11-3 inputFileコンポーネントのuploadTypeの値

値

説明

submit

1ファイルのみをアップロードします。ドロップ・セクション(ユーザーがファイルをドラッグ・アンド・ドロップできる場所)は表示されません。

auto

ドロップ・セクションが表示されます。複数のファイルをアップロードできます。ファイルがドロップ・セクションに表示されると、すぐにアップロードが開始されます。

maximumFilesが1に設定されている場合、ユーザーは、一度に複数のファイルを選択するのではなく、1つずつファイルを選択して、複数のファイルをアップロードできます。

manual

ドロップ・セクションが表示されます。複数のファイルをアップロードできます。アップロードは、「アップロード」ボタンをクリックすると開始されます。

maximumFilesが1に設定されている場合、ユーザーは、一度に複数のファイルを選択するのではなく、1つずつファイルを選択して、複数のファイルをアップロードできます。

autoIfMultiple

複数のファイルをアップロードします。ファイルがドロップ・セクションに表示されると、すぐにアップロードが開始されます。デフォルトでは、uploadTypeはautoIfMultipleに設定されています。

maximumFilesが1に設定されている場合、ユーザーは1つのファイルのみを選択してアップロードできます。ドロップ・セクションも表示されません。

manualIfMultiple

複数のファイルをアップロードします。アップロードは、「アップロード」ボタンをクリックすると開始されます。

maximumFilesが1に設定されている場合、ユーザーは1つのファイルのみを選択してアップロードできます。ドロップ・セクションも表示されません。

5. 「その他」セクションを開き、displayMode属性を設定して、複数ファイル・アップロード用のユーザー・インタフェースを表示するかどうかを指定します。デフォルトでは、この属性はdefaultに設定され、複数ファイル・アップロード用のユーザー・インタフェースが表示されます。有効な値は、default、dropAreaおよびnoneです。

注意:

uploadTypeがautoに設定されていて、autoSubmitがtrueに設定されている場合には、requiredをtrueに設定しないでください。それによって検証エラーがスローされる可能性があるためです。

詳細は、11.9.5項「inputFileコンポーネントのユーザー・インタフェースのカスタマイズに関する必知事項」を参照してください。

アップロードされたファイルをドロップ・セクションから削除するか、アップロード中のファイルのアップロードを取り消すには、ファイル名およびプログレス・バーの横にある「取消」アイコンをクリックします。すべてのファイルのアップロードを取り消すには、図11-47に示すように「アップロードの停止」ボタンをクリックします。

図11-47 inputFileコンポーネントでアップロード中のファイル

11.9.3 一時的なファイルの格納に関する必知事項

ADF Facesではアップロードされるファイルが(ディスクまたはメモリーに)一時的に格納されるため、アップロード・ファイルでハード・ドライブやメモリーを一杯にしようとするサービス拒否攻撃を未然に防ぐため、デフォルトでは、許容される着信アップロード・リクエストのサイズが制限されています。デフォルトでは、1つのリクエストで最初の100KBがメモリーに格納されます。これが一杯になると、ディスク領域が使用されます。この場合も、デフォルトでは、すべてのファイルに対し、1つのリクエストで2,000KBのディスク領域に制限されます。これらの制限を超えると、フィルタによりEOFExceptionがスローされます。

ファイルは、デフォルトで、java.io.File.createTempFile()メソッドによって使用される一時ディレクトリに格納されます。これは通常、システム・プロパティjava.io.tmpdirによって定義されます。明らかに、これは一部のアプリケーションでは不十分であるため、例11-14に示すように3つのサーブレット・コンテキスト初期化パラメータを使用して、これらの値を構成できます。

例11-14 ファイルのアップロード・サイズおよびディレクトリを定義するパラメータ

<context-param>
<!-- Maximum memory per request (in bytes) -->
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY</param-name>
<!-- Use 500K -->
<param-value>512000</param-value>
</context-param>
<context-param>
<!-- Maximum disk space per request (in bytes) -->
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE</param-name>
<!-- Use 5,000K -->
<param-value>5120000</param-value>
</context-param>
<context-param>
<!-- directory to store temporary files -->
<param-name>org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR</param-name>
<!-- Use a TrinidadUploads subdirectory of /tmp -->
<param-value>/tmp/TrinidadUploads/</param-value>
</context-param>
<context-param>
<!-- Maximum file size that can be uploaded.-->
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE</param-name>
<!-- Use 5,000K -->
<param-value>5120000</param-value>
</context-param>
<!-- This filter is always required;  one of its functions is
file upload. -->
<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>

org.apache.myfaces.trinidad.webapp.UploadedFileProcessorクラス全体をtrinidad-config.xml構成ファイルの<uploaded-file-processor>要素に置き換えることで、ファイルのアップロード・プロセスをカスタマイズできます。UploadedFileProcessorクラスを置き換えると、例11-14にリストされているパラメータは無関係になり、デフォルトのUploadedFileProcessorクラスによってのみ処理されます。

<uploaded-file-processor>要素は、oracle.adf.view.rich.webapp.UploadedFileProcessorインタフェースを実装するクラスの名前である必要があります。このAPIにより、個々のアップロード・ファイルが着信リクエストから取得される際に処理され、そのコンテンツを残りのリクエストで使用できるようになります。大部分のアプリケーションは、デフォルトのUploadedFileProcessorクラスで十分ですが、大規模ファイルのアップロードをサポートする必要のあるアプリケーションでは、リクエスト中にADF Facesで一時記憶域を処理するかわりに、ファイルをただちに最終的な宛先に格納することでパフォーマンスを向上させます。

11.9.4 複数のファイルのアップロードに関する必知事項

inputFileコンポーネントは、HTML5を使用してドラッグ・アンド・ドロップ機能や複数ファイルのアップロードをサポートします。HTML5をサポートしないブラウザでは、図11-48に示すように、ドラッグ・アンド・ドロップ機能と複数ファイルのアップロードにJavaアップレットが使用されます。

図11-48 HTML5以外のブラウザのinputFileコンポーネント

HTML5をサポートしていないブラウザでJavaも使用できない場合は、inputFileコンポーネントにドロップ・セクションは表示されません。

注意:

OracleAS Single Sign-On (SSO)を使用している場合、Oracle HTTP Serverのシングル・サインオンを有効にするmod_osso.confファイルを構成する必要がある場合があります。このファイルは、ORACLEOHS_HOME/ohs/conf/にあります。ここで、ORACLEOHS_HOMEはOracle HTTP Serverがインストールされているホーム・ディレクトリです。アップロード・アプレットが非HTML5ブラウザで適切に機能するようにするには、構成が必要です。

次のパラメータを使用してmod_osso.confファイルを更新します。

OssoSecureCookies off
OssoHTTPOnly Off

Header unset Pragma
OssoSendCacheHeaders off

OracleAS Single Sign-Onの詳細は、『Oracle Platform Security Servicesによるアプリケーションの保護』を参照してください。

単一ファイル・アップロード・モードの場合、inputFileコンポーネントでアップロードできるのは、2GB未満のファイルのみです。複数ファイル・アップロード・モードでは、inputFileコンポーネントはファイルを2 GBのサイズのチャンクに分割することにより、デフォルトで2 GBより大きいファイルをアップロードできます。チャンクのサイズは、web.xmlのパラメータorg.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZEで制御できます。2 GBがデフォルト値であり、最大値でもあります。次に例を示します。

<context-param>
<!-- Maximum file chunk size that can be uploaded.-->
<param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE</param-name>
<!-- Use 1,000 MB as chunk size -->
<param-value>1000000000</param-value>
</context-param>

チャンク機能を使用した大きなファイルのアップロードは、すべてのブラウザでサポートされているわけではありません。詳細は、Oracle Technology NetworkのOracle JDeveloperリリース・ノートを参照してください。

すべてのファイルをアップロードしたら、必ずフォームを送信する必要があります。これを行わないと、inputFileコンポーネントのデータはサーバーにアップロードされません。inputFileコンポーネントでautoSubmitがtrueに設定されている場合は、すべてのファイルのアップロードが終わるとフォームが自動的に送信されます。フォームの送信が完了すると、inputFileコンポーネントがリフレッシュされてドロップ・セクションのファイル・リストが空になり、さらにファイルをアップロードできるようになります。アップロードされたファイルのリストを表示するには、例11-12に示すように、ValueChangeListenerを追加するか、値をマネージドBeanにバインドします。

11.9.5 inputFileコンポーネントのユーザー・インタフェースのカスタマイズに関する必知事項

inputFileコンポーネントのユーザー・インタフェースは、displayMode属性を使用してカスタマイズできます。displayMode属性をnoneに設定すると、ユーザー・インタフェースが表示されないため、ファイルをアップロードするAPIを起動するためのカスタム・ユーザー・インタフェースを開発者が作成する必要があります。この属性をdropAreaに設定すると、ファイルのドラッグ・アンド・ドロップをサポートするドロップ領域がレンダリングされます。カスタム・ユーザー・インタフェースの残りの部分を追加するのは、開発者の責任です。inputFileコンポーネントのカスタム・インタフェースは、それが複数のファイルをアップロードするように構成されている場合にのみ表示されます。

図11-49に、displayModeの値が異なるinputFileコンポーネントを示します。

図11-49 inputFileコンポーネントのdisplayMode属性の値

例11-15に、displayModeがdropAreaに設定され、ファイルの参照とアップロードのために入力フィールドおよびボタンを追加してカスタマイズされた、inputFileコンポーネントを示します。アップロードされるファイルの説明を入力するために、inputTextコンポーネントが追加されています。

例11-15 入力フィールドおよびボタンを追加してカスタマイズされたinputFileコンポーネント

<af:inputFile binding="#{editor.component}" id="testid" immediate="true"
maximumFiles="-1"valueChangeListener="#{demoFile.fileUpdate}"
displayMode="dropArea" uploadType="manual"contentStyle="width:200px;
height:100px"/>

<af:panelFormLayout maxColumns="2" rows="1">
<input type="file" id="dmoTpl:cidf1"/>
<af:inputText clientComponent="true" id="cidd1" label="Please Enter a
Description"/>
</af:panelFormLayout>

<af:panelFormLayout maxColumns="2" rows="2">
<af:panelLabelAndMessage for="cidn1" label="Filename:" id="plm1">
<af:outputText clientComponent="true" id="cidn1"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage for="cids1" label="Filesize:" id="plm2">
<af:outputText clientComponent="true" id="cids1"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage for="cidp1" label="% Complete:" id="plm3">
<af:outputText clientComponent="true" id="cidp1"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage for="cidst1" label="Status:" id="plm4">
<af:outputText clientComponent="true" id="cidst1"/>
</af:panelLabelAndMessage>
</af:panelFormLayout>

<af:panelFormLayout maxColumns="2" rows="1">
<af:button id="cup1" text="Upload">
<af:clientListener method="uploadClick" type="click"/>
</af:button>
<af:button id="cl1" text="Clear">
<af:clientListener method="clearQueue" type="click"/>
</af:button>
</af:panelFormLayout>

図11-50は、実行時の例11-15のinputFileコンポーネントを示しています。

図11-50 カスタマイズされたinputFileコンポーネント

JavaScript APIメソッドを使用して、inputFileコンポーネントの動作をカスタマイズできます。詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください。

11.10 コード・エディタの使用

af:codeEditorコンポーネントを使用すると、ブラウザ内でコード編集を実行できるほか、Fusion Webアプリケーションで実行時にプログラム・コードを表示および編集できます。コード・エディタ・コンポーネントの入力フィールドはテキストを受け入れます。また、ツールバー、キーワードの構文的な色分け、基本検証、エラーのハイライト、ログ用のメッセージ・ペインなど、いくつかの一般的なコード編集機能も備えています。コード・エディタを使用すると、ユーザーはエラーや警告に対してIDEソフトウェアを実行してプログラム・コードをテストする必要がなくなります。

コード・エディタ・コンポーネントは、図11-51に示すように、JavaScript、XML、Groovyの各言語をサポートします。

図11-51 JavaScript、XMLおよびGroovyをサポートするコード・エディタ・コンポーネント

コード・エディタ・コンポーネントには、次の機能があります。

- 行番号付け

- 元に戻す操作および操作の再実行(キーボード・ショートカット[Ctrl]+[Z]および[Ctrl]+[Y]を使用しても実行可能)

- 特定の行へのジャンプ

- 検索および置換

- テキストの色分け

- 構文や検索した用語のハイライト

- 自動インデント

- 自動書式設定

- エラー・メッセージ用のメッセージ・ペイン

- 1000行を超えるコードを持つ大きなファイルのサポート

コード・エディタでコードを追加または編集するには、エディタ領域をクリックしてコードを追加します。コード行を前方にインデントするには、[F2]を押してエディタの編集モードを有効にし、[Tab]キーを押します。コード行を後方にインデントするには、[Shift]キーを押しながら[Tab]キーを押します。コードをインデントするには、編集モードを有効にする必要があります。編集モードが有効になっていない場合、[Tab]キーまたは[Shift]+[Tab]キーを押すと、それぞれ次または前のコンポーネントに移動します。

ユーザーは、ツールバー(図11-52を参照)を使用して、変更の取消しと再実行、テキストの検索と置換、および特定の行番号へのジャンプ操作を実行できます。

図11-52 コード・エディタのツールバー

文字列を検索するには、「検索」フィールドに検索条件を入力し、「次を検索」または「前を検索」アイコンをクリックして、コード・エディタ内の検索文字列の位置を特定します。図11-53に、コード・エディタで文字列検索に使用される、ツールバーの「検索」フィールドを示します。

図11-53 コード・エディタのツールバーの「検索」フィールドの使用

大/小文字を区別して文字列を検索したり、検索した用語を置換したりするには、「検索と置換」アイコンから「検索と置換」ダイアログを開いて、図11-54に示すような操作をダイアログから実行します。

図11-54 コード・エディタの「検索と置換」ダイアログの使用

注意:

「完全一致」チェック・ボックスが選択されている場合は、「検索と置換」ダイアログでエディタの英語以外の文字列を検索することはできません。ただし、「すべて置換」ボタンを使用する場合は、「完全一致」チェック・ボックスが選択されていても、英語以外の文字列のすべてのインスタンスを置換できます。

特定の行番号にジャンプするには、図11-55に示すように、「指定行に移動」フィールドに数字を入力して、「指定行にジャンプ」をクリックします。

図11-55 コード・エディタの「指定行に移動」の機能の使用

コード・エディタ・コンポーネントでは、すべての警告とエラーを付属のメッセージ・ペインにリストするように構成できます。図11-56に、サーバーで実行されているXMLパーサーで検出されたすべてのXMLエラーをリストしたメッセージ・ペインを示します。

図11-56 コード・エディタのメッセージ・ペイン

メッセージ・ペインは、コード・エディタのテキスト領域の下にある編集不可能な領域です。コードのコンパイルの検証サポートや、エラーまたは警告メッセージなど、コードに関するステータス情報の表示に使用されます。メッセージ・ペインのメッセージをクリックすると、コード・エディタの対応する各コード行に移動できます。

また、プログラムを使用して様々なタイプのマーカーを追加するようにコード・エディタを構成することもできます。図11-57に、エラー、クリティカル、警告、情報の各マーカーが表示されたコード・エディタを示します。

図11-57 コード・エディタでのマーカーの使用

11.10.1 codeEditorコンポーネントの追加方法

codeEditorコンポーネントを追加する場合は、language属性を使用してコード・エディタで使用するプログラミング言語を構成します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.10項「コード・エディタの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。

codeEditorコンポーネントを追加するには:

1. 「コンポーネント」ウィンドウで、「テキストおよび選択」パネルからコード・エディタ・コンポーネントをドラッグし、ページにドロップします。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、Languageを設定します。有効な値は、javascript、groovyおよびxmlです。

3. 「外観」セクションを開き、次の設定を行います。

- LineNumbers: コード・エディタに行番号を表示するかどうかを指定します。
有効な値は、yesおよびnoです。

- Simple: ラベルを表示しない場合にtrueに設定します。

4. 「動作」セクションを開き、次のように設定します。

- ReadOnly: コード・エディタ内のコードを編集可能にするか、出力スタイルのテキストとして表示するかを指定します。

- Disabled: コード・エディタを無効にするかどうかを指定します。

12 表、ツリー、およびその他のコレクションベースのコンポーネントの使用

この章では、構造化データをコンポーネント内に表示する方法を説明します。このコンポーネントは、データのコレクションを反復処理してコレクション内の各行を表示できます。ADF Facesのtable、tree、treeTable、listViewおよびcarouselの各コンポーネントを使用します。アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してこれらのコンポーネントを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFによるデータバインドされた表の作成」、「マスター/ディテール・データの表示」および「より複雑なデータバインドADF Facesコンポーネントの使用」の各章を参照してください。

この章では、次の項目について説明します。

- 12.1項「コレクションベース・コンポーネントについて」

- 12.2項「コレクションベース・コンポーネントの共通機能」

- 12.3項「表へのデータの表示」

- 12.4項「表への非表示機能の追加」

- 12.5項「表でのフィルタ処理の有効化」

- 12.6項「ツリーへのデータの表示」

- 12.7項「ツリー表へのデータの表示」

- 12.8項「行を値として渡す」

- 12.9項「表メニュー、ツールバーおよびステータス・バーの表示」

- 12.10項「リストへのコレクションの表示」

- 12.11項「カルーセルでのイメージの表示」

- 12.12項「表、ツリーまたはツリー表からのデータのエクスポート」

- 12.13項「コレクションベースのコンポーネントからクライアント上の選択された値へのアクセス」

12.1 コレクションベース・コンポーネントについて

ADF Facesには、構造化データのコレクションの反復処理と表示に使用できるコンポーネントが用意されています。表示される各レコード用に子コンポーネントを含め、それらのコンポーネントを個々のレコードにバインドするかわりに、これらのコンポーネントがコレクション全体にバインドされ、各レコードの値にスタンプを設定することにより、1つのコンポーネント(outputTextコンポーネントなど)が繰り返しレンダリングされます。

構造化データを、複数の行と1つの列からなる単純な表として表示するにはListViewコンポーネントを使用し、複数の列に表示するにはADF Faces tableコンポーネントを使用します。階層データは、ADF Facesのツリー・コンポーネントを使用してツリー構造として表示することも、ADF Facesのツリー表コンポーネントを使用して表形式で表示することもできます。イメージのコレクションはカルーセル・コンポーネントに表示できます。図12-1に、ADF Facesのコレクションベース・コンポーネントを示します。

図12-1 ADF Facesのコレクションベース・コンポーネント

ヒント:

表は使用しないが、同じスタンプ設定機能が必要な場合には、イテレータ・タグを使用できます。たとえば、元素周期表のリストを表示し、各元素に対して名前、原子番号、記号およびグループを表示するとします。次の例に示すように、イテレータ・タグを使用できます。

<af:iterator var="row" first="3" rows="3" varStatus="stat"
value="#{periodicTable.tableData}" >
<af:outputText value="#{stat.count}.Index:#{stat.index} of
#{stat.model.rowCount}"/>
<af:outputText label="Element Name" value="#{row.name}"/>
<af:outputText label="Atomic Number" value="#{row.number}"/>
<af:outputText label="Symbol" value="#{row.symbol}"/>
<af:outputText label="Group" value="#{row.group}"/>
</af:iterator>

各子には、必要に応じて何度でもスタンプ設定できます。反復は、first属性で指定された索引から開始され、row属性で指定された索引まで行われます。row属性が0に設定されている場合、反復は基礎となるデータにそれ以上要素がなくなるまで続けられます。

12.1.1 コレクションベース・コンポーネントのユースケースと例

コレクションベース・コンポーネントは、構造化データの表示に使用されます。たとえば、図12-2に示すように、File Explorerアプリケーションの表タブでは、選択されたディレクトリのコンテンツの表示に表が使用されています。

図12-2 File Explorerアプリケーションの表コンポーネント

File Explorerアプリケーションのディレクトリなど、階層データ(親子関係のあるデータ)は、ツリー・コンポーネントを使用して展開可能なツリーとして表示できます。項目は、データの親子構造をミラー化するノードとして表示されます。各最上位レベル・ノードを展開して子ノードを表示でき、子ノードを展開してその子ノードを表示できます。展開された各ノードを縮小して、子ノードを非表示にできます。図12-3に、ツリー・コンポーネントを使用して表示されるFile Explorerアプリケーションのファイル・ディレクトリを示します。

図12-3 File Explorerアプリケーションのツリー・コンポーネント

ツリー表コンポーネントを使用して階層データを表示することもできます。ツリー表でも、展開および縮小可能な親子のノードを表示できますが、これは表形式で、ページにノードの属性値がデータの列として表示されます。たとえば、表コンポーネントを使用してディレクトリのコンテンツを表示するだけでなく、File Explorerアプリケーションには、図12-4に示すように、ツリー表コンポーネントを使用してコンテンツを表示する別のタブもあります。

図12-4 File Explorerアプリケーションのツリー表

ツリー・コンポーネント同様、ツリー表コンポーネントも、項目間の親子関係を表示できます。また、表コンポーネントと同じように、ツリー表コンポーネントでも列の項目の属性値を表示できます。ツリー表コンポーネントでも、表コンポーネントで使用可能なほとんどの機能を使用できます。

表、ツリーおよびツリー表をpanelCollectionコンポーネントで囲むことにより、ツールバーおよびステータス・バーを表に追加できます。上部のパネルには、メニューとメニュー・オプション、ツールバーとツールバー・ボタン、およびステータス・バーなど、メニュー・タイプのコンポーネントを保持するツールバーのみでなく、標準のメニュー・バーも含まれます。デフォルトで追加されているボタンおよびメニューもあります。たとえば、表、ツリーまたはツリー表をpanelCollectionコンポーネントで囲むと、「表示」メニューを含むツールバーが追加されます。このメニューには、表、ツリーまたはツリー表コンポーネントに固有のメニュー項目が含まれます。

図12-5に、panelCollectionコンポーネントを使用して作成されたツールバー、メニューおよびツールバー・ボタンのあるFile Explorerアプリケーションのツリー表を示します。

図12-5 パネル・コレクションを使用したTreeTable

listViewコンポーネントは単純な表であり、構造化データをリスト形式で表示できます。表とは異なり、列がないため、単純な表形式のレイアウトよりも多様なパターンでデータを表示できます。

実際のデータを表示する各コンポーネントは、1つの子listItemコンポーネントに含まれています。図12-6に、1つの子listItemコンポーネントを含むlistViewコンポーネントを示します。listItemコンポーネントには、レイアウト・コンポーネント、出力コンポーネントおよびボタン・コンポーネントが混在しています。

図12-6 listItemコンポーネントを使用して各行のデータを保持するlistViewコンポーネント

listViewコンポーネントでは、階層データも表示できます。親データにバインドされたコンポーネントがgroupHeaderStampファセットに配置されている場合、そのデータはヘッダーに表示されます。図12-7に、アルファベット文字(親データ)がヘッダーに表示され、子である個人のデータが親の下の各行に表示される様子を示します。

図12-7 階層データのグループ別表示が可能

カルーセル・コンポーネントは、図12-8に示すように、イメージのコレクションを回転カルーセルに表示します。ユーザーは、下部にあるスライダを使用するか、補助イメージの1つをクリックしてそのイメージを前面に移動することにより、前面のイメージを変更できます。

図12-8 ADF Facesカルーセル

12.1.2 コレクションベース・コンポーネントの追加機能

コレクションベース・コンポーネントを実装する前に、ADF Facesのその他の機能を理解しておくと役立ちます。また、ページにコレクションベース・コンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。表およびツリー・コンポーネントで使用できる他の機能へのリンクを次に示します。

- ツールバーのカスタマイズ: 表およびツリー表コンポーネントのメニュー、ツールバーおよびステータス・バーを提供するpanelCollectionコンポーネントに含まれるツールバーをカスタマイズできます。メニュー、ツールバー、ツールバー・ボタンの詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

- 表の幅のジオメトリ管理: 表が、子を拡大するコンポーネントの子である場合、この幅の設定はオーバーライドされ、表はコンテナに合うように自動的に拡大されます。コンポーネントが拡大される方法の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- アクティブ・データ: アプリケーションでアクティブ・データを使用する場合は、データ・ソースのデータが変更されるたびに、表およびツリーのデータを自動的に更新できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アクティブ・データ・サービスの使用方法」の章を参照してください。

注意:

アクティブ・データを使用し、アプリケーションでADFビジネス・コンポーネントを使用する場合は、表が次の条件に適合する必要があります。

- 表またはツリーが、単一の属性のみ含む同種データにバインドされていること。

- 表でフィルタを使用しないこと。

- ツリー・コンポーネントのnodeStampファセットに、単一のoutputTextタグが含まれ、他のタグが含まれていないこと。

- イベント: コレクションベース・コンポーネントは、サーバー側とクライアント側両方のイベントを起動します。これに対する応答としてアプリケーションでなんらかのロジックを実行できます。詳細は、第6章「イベントの処理」を参照してください。

- 部分ページ・レンダリング: ページ上の他のコンポーネントで実行されたアクションに基づいて、コレクションベース・コンポーネントをリフレッシュして新しいデータを表示することができます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

- パーソナライズ: コンポーネントの表示方法は実行時にユーザーが変更できますが(列の並替えや列幅の変更など)、ユーザーがそのページから移動した後もその値を維持するには、ユーザーのカスタマイズを許可するようにアプリケーションが構成されている必要があります。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADFビジネス・コンポーネントがどのように構成されているかに基づいて、バインドされた表およびツリーを自動的に作成できます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「ADFによるデータバインドされた表の作成」および「マスター/ディテール・データの表示」の章を参照してください。

12.2 コレクションベース・コンポーネントの共通機能

コレクションベース・コンポーネントには、データの配信方法やデータの表示と編集の方法など、多数の共通する機能があります。これらのコンポーネントを使用する前に、この共有機能と、その構成方法を理解することが重要です。

12.2.1 行およびノードへのデータの表示

表示するレコードごとに1つの子コンポーネントを持ち、そのコンポーネントを個々のレコードにバインドするのではなく、コレクションベース・コンポーネントはコレクション全体にバインドされ、各レコードの値をスタンプすることによって1つのコンポーネント(たとえばoutputTextコンポーネント)が繰返しレンダリングされます。たとえば、表に子の列コンポーネントが2つ含まれるとします。各列には、出力コンポーネントを使用して行の単一の属性値が表示され、4つのレコードが表示されます。データを表示するために、2つの出力コンポーネントの4セットをバインドするかわりに、表自体が4つすべてのレコードのコレクションにバインドされ、1セットの出力コンポーネントが単純に4回スタンプ設定されます。各行にスタンプが設定されると、現在行のデータが表のvar属性にコピーされ、出力コンポーネントが行の正しい値を取得できるようになります。特に、クライアント・コンポーネントでスタンプ設定がどのように機能するかの詳細は、第12.2.6項「クライアントのコレクション・コンポーネントへのアクセス」を参照してください。

例12-1に、var属性の値がrowである表のJSFコードを示します。値が変数の特定のプロパティにバインドされているため、列の各outputTextコンポーネントにより行のデータが表示されます。

例12-1 値へのアクセスにvar属性を使用する表のJSFコード

<af:table var="row" value="#{myBean.allEmployees}">
<af:column>
<af:outputText value="#{row.firstname}"/>
</af:column>
<af:column>
af:outputText value="#{row.lastname}"/>
</af:column>
</af:table>

コレクションベース・コンポーネントは、CollectionModelクラスを使用して基礎となるコレクションのデータにアクセスします。このクラスは、JSF DataModelクラスを拡張し、行キーおよびソートのサポートを追加します。DataModelクラスでは、行は索引によって完全に識別されます。他のユーザーが行を追加したことにより、ある行を削除するユーザー・リクエストで異なる行が削除されてしまうなど、あるリクエストから次のリクエストまでに基礎となるデータが変更される場合、この識別方法が原因で問題が発生する可能性があります。これを回避するため、CollectionModelクラスは索引ではなく行キーに基づいています。

java.util.List、arrayおよびjavax.faces.model.DataModelなど、別のモデル・クラスも使用できます。これらのクラスのいずれかを使用する場合は、表コンポーネントにより、インスタンスがCollectionModelクラスに自動的に変換されますが、機能は追加されません。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表を作成すると、コレクション・モデルが作成されます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「ADFによるデータバインドされた表の作成」の章を参照してください。

12.2.2 コンテンツの配信

コレクション・コンポーネントは仮想化されているため、サーバーのコンポーネントに存在するすべての行がクライアントに配信されて表示されるわけではありません。コレクション・コンポーネントは、一度に一定数の行をデータ・ソースからフェッチするように構成されます。レンダリング時にすぐにデータをコンポーネントに配信することも(使用可能な場合)、コンポーネントのシェルがレンダリングされた後に遅延フェッチすることもできます(デフォルトでは、コンポーネントはデータが使用可能な場合にデータをフェッチします)。

即時配信では、データは初期リクエスト時にフェッチされます。遅延配信では、ページにコレクション・コンポーネントが1つ以上含まれる場合、ページで最初に標準のライフサイクルが実行されます。ただし、最初のリクエスト時にデータがフェッチされるのではなく、特別な個別の部分ページ・レンダリング(PPR)リクエストが実行され、コンポーネントのフェッチ・サイズの値として設定された行数が戻されます。ページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみがコンポーネントに対して実行され、対応するデータのフェッチおよび表示が可能になります。ユーザーのアクションにより後続のデータ・フェッチが実行される場合(別の行セットのために表をスクロールするなど)、別のPPRリクエストが実行されます。

コンテンツが使用可能なときに配信されるようにコンテンツ配信を構成すると、フレームワークでは最初のリクエストの間にデータの可用性をチェックし、使用可能であれば、そのデータがコンポーネントに送信されます。使用可能でない場合、データは遅延配信と同じように、別のPPRリクエスト時にロードされます。

注意:

アプリケーションでFusionテクノロジ・スタックが使用されない場合は、whenAvailableのサポートをCollectionModel実装に明示的に追加する必要があります。たとえば、Facesデモ・アプリケーションのWhenAvailableData.javaマネージドBeanを参照してください。

アプリケーションでFusionテクノロジ・スタックを使用する場合は、作成されたCollectionModel実装でこれらのAPIが自動的に使用されます。

パフォーマンスのヒント:

データのフェッチにコスト(時間)がかかると予想されるときは、遅延配信を使用する必要があります。たとえば、データベース接続が低速で待機時間が長い場合や、データベース以外の低速のデータ・ソース(たとえばWebサービス)からデータをフェッチする場合です。ページに表、ツリーまたはツリー表以外のコンポーネントが複数含まれる場合も、遅延配信を使用する必要があります。遅延配信を使用すると、データが使用可能になる前に、初期ページのレイアウト・コンポーネントおよびその他のコンポーネントが最初にレンダリングされます。

即時配信は、表、ツリーまたはツリー表がページの唯一のコンテキストである場合、またはコンポーネントが大きなデータ・セットを返さないと予想される場合に使用する必要があります。この場合、ユーザー・レスポンス時間がより高速で、サーバーCPU利用率がより高ければ、2番目のリクエストはサーバーに移動しないため、レスポンス時間は遅延配信を使用する場合よりも高速になります(または、場合によっては高速に感じます)。ただし、フェッチ・ブロックとして構成された行数のみが最初に返されます。遅延配信と同様に、ユーザーのアクションが後続のデータ・フェッチの原因となる場合は、次の行セットが配信されます。

使用可能な場合、配信は、データが初期レンダリング時に使用可能な場合には即時を使用し、データが最初は使用可能でない場合は遅延にフォールバックするという追加の柔軟性を提供します。

クライアントに表示されるのは、ブラウザに表示される際にページに収まる行数のみです。それ以上の行は、ユーザーがコンポーネントを垂直にスクロールしたとき(スクロールではなくページ区切りが設定されている場合は、ユーザーが別の行セットに移動したとき)にフェッチされます。コンポーネントを埋めるために1回でクライアントからサーバーにリクエストされる行数は、fetchSize属性により決定されます。表の場合のデフォルト値は25です。そのため、表の高さが低ければ、フェッチ・サイズ25はコンポーネントを埋めるのに十分です。ただし、コンポーネントの高さが高い場合、サーバーからのデータのリクエストは複数回になります。そのため、fetchSize属性は大きな数に設定しておく必要があります。たとえば、表の高さが600ピクセルで、各行の高さが18ピクセルの場合、表を埋めるのに少なくとも45行必要です。fetchSizeが25の場合、表を埋めるために、表はサーバーに対してリクエストを2回実行する必要があります。この例では、フェッチ・サイズを50に設定します。

ただし、フェッチ・サイズを大きくしすぎると、サーバーとクライアントの両方に影響を与えます。サーバーでは、データ・ソースから必要以上に行がフェッチされ、時間とメモリー使用量が増加します。クライアント側では、それらの行の処理とコンポーネントへのアタッチに時間がかかります。

デスクトップ・デバイスでは、ユーザーがデータの行をスクロールできるように、表にはスクロール・バーがデフォルトでレンダリングされます。かわりに、図12-9に示すように、scrollPolicy属性を使用して表がページ区切りになるようにして、特定の行のページにジャンプできるフッターを表示することもできます。

図12-9 ページ区切りの表

ビューポートが狭すぎてフッター全体を表示できない場合は、次に示すように、現在表示されているページとナビゲーション・ボタンのみを表示するコンパクトなフッターが表示されます。

図12-10 コンパクト・モードで表示されたページ区切りの表

注意:

タブレット・デバイスでは、表はデフォルトでページ区切りで表示されるようにレンダリングされます。

表をページ区切りで表示するには、scrollPolicy属性とautoHeightRows属性をそれぞれpageと0に設定し、表をフロー・コンテナ(子を拡大しないコンポーネント)の中に配置する必要があります。フロー・コンテナ・コンポーネントの詳細は、第9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

スクロールするように構成された表の場合、ページに表示される行の数はfetchSize属性によって決まります。

注意:

デフォルトでは、スクロールバーを使用するように表が構成されている場合に、iOSオペレーティング・システムでスクロールバーが表示されるのはコンテンツにマウスを置いたときのみとなります。他のオペレーティング・システムでもこれと同じ動作となるようにアプリケーションを構成するには、web.xmlファイルにあるoracle.adf.view.rich.table.scrollbarBehaviorパラメータを設定します。詳細は、A.2.3.30項「表におけるスクロールバーの動作」を参照してください。

displayRow属性を使用して、最初に表示されるデータのセットを構成することもできます。デフォルトで、データ・ソースの最初のレコードが一番上の行またはノードに表示され、後続のレコードはそれより下の行またはノードに表示されます。また、ソースの最後のレコードを最初に表示するように、コンポーネントを構成することもできます。この場合、最後のレコードはコンポーネントの下の行またはノードに表示され、ユーザーは上にスクロールして先行するレコードを表示できます。また、選択した行を表示するように、コンポーネントを構成することも可能です。これは、ユーザーがコンポーネントに移動したときに、複数のパラメータに基づいて、特定の行がプログラムで選択されるようにする場合に便利です。選択された行を表示するように構成した場合、その行は表の先頭に表示され、ユーザーは上または下にスクロールして他の行を表示できます。

注意:

JavaScriptを使用して、表またはツリーを動的にサイズ変更することはできません。表、ツリーおよびツリー表の高さは初めてレンダリングされるときに設定され、JavaScript APIを使用して変更することはできません。

12.2.3 行の選択

行をまったく選択しないか、1行だけ選択するか、複数行選択するかを構成するには、rowSelection属性を使用します(carouselコンポーネントの場合は複数選択はできません)。この設定により、選択した行に対してロジックを実行できます。たとえば、ユーザーが表の行の1つまたはツリーのノードの1つを選択してからボタンをクリックすると、選択された行のデータが別のページに表示され、そのページでデータを編集できるようにする場合です。

注意:

複数の選択を実行できるようにコンポーネントを構成した場合、ユーザーが行を1つ選択し、[Shift]キーを押して別の行を選択すると、間にあるすべての行が選択されます。この選択は、選択が複数のデータ・フェッチ・ブロックにまたがる場合でも保持されます。同様に、[Ctrl]キーを使用して、隣接していない行を選択することもできます。

たとえば、表が一度に25行のみフェッチするように構成されている場合に、ユーザーが100行選択すると、フレームワークにより選択が追跡されます。

コンポーネントで選択されている行(またはノード)が変更されると、コンポーネントにより選択イベントが起動されます。このイベントにより、選択解除された行や選択された行が報告されます。コンポーネントにより選択が宣言的に処理される際、選択された行でロジックを実行する必要がある場合は、それらの行にアクセスしてロジックを実行するコードを実装する必要があります。これは、マネージドBeanの選択リスナー・メソッドで実行できます。詳細は、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

パフォーマンスのヒント:

ユーザーは、マウスとスクロールバーを使用するか、キーボードの上下の矢印キーを使用して、表内を移動できます。デフォルトでは、ユーザーが行をクリックするとすぐに選択イベントが起動されます。つまり、ユーザーが矢印キーで行間を移動している場合は、ユーザーの移動に伴い、各行で選択イベントが起動されます。

ユーザーがキーを使用して表内を移動することが予想される場合は、delaySelectionEvent属性をtrueに設定すると、選択イベントが300ミリ秒遅れて起動されるようにできます。ユーザーが300ミリ秒以内に別の行に移動した場合、選択イベントは取り消されます。

12.2.4 表、ツリーおよびツリー表のデータの編集

表、ツリーまたはツリー表の実際のデータの表示に使用するコンポーネントを選択できます。たとえば、データを読取り専用にする場合は、データの表示にoutputTextコンポーネントを使用します。反対に、データを編集できるようにする場合にはinputTextコンポーネントを使用し、リストから選択する場合にはSelectOneコンポーネントを1つ使用します。これらのコンポーネントはすべて、列コンポーネントの子として配置されるか(表およびツリー表の場合)、nodeStampファセットに配置されます(ツリーの場合)。

値の編集が可能なコンポーネントを使用してデータを表示する場合、表、ツリーまたはツリー表で、すべての行を編集可能として一度に表示するか、現在アクティブな行以外のすべての行を読取り専用として表示するかを、editingMode属性を使用して選択できます。たとえば、図12-11に、行をすべて編集できる表を示します。ページは、ページに追加されたコンポーネント(inputText、inputDateおよびinputComboBoxListOfValuesコンポーネントなど)を使用してレンダリングされます。

図12-11 すべての行を編集できる表

図12-12に示したのは同じ表(つまり、inputText、inputDateおよびinputComboBoxListOfValuesコンポーネントを使用してデータを表示しています)ですが、アクティブな行にのみ編集可能なコンポーネントが表示されるように構成されています。ユーザーは、別の行をクリックして編集可能にできます(一度に1行のみ編集可能になります)。ページを作成するために図12-11と同じ入力コンポーネントが使用されていても、編集可能でない行のデータの表示に、outputTextコンポーネントが使用されていることに注意してください。これらのコンポーネントを実際にレンダリングしている行は、アクティブな行のみです。

図12-12 一度に1行のみを編集できる表

現在アクティブな行は、表のactiveRowKey属性によって決定されます。デフォルトでは、この属性の値は表の最初に表示される行です。表(またはツリーやツリー表)がリフレッシュされると、アクティブな行が表示されていなければ、そのコンポーネントがスクロールしてアクティブな行が表示されます。ユーザーがコンテンツを編集するために行をクリックすると、その行がアクティブな行になります。

編集できる行(またはノード)を1つのみにする場合、ユーザーがある行(またはノード)から次の行へ移動し、一度に1行のデータを送信(および検証)すると、表(またはツリーやツリー表)ではPPRが実行されます。すべての行を編集できるようにする場合、現在表示されている行またはノードを超えてスクロールするなど、PPRが実行されるイベントが発生するとデータが送信されます。

注意:

ツリーと表は、ブラウザのコピー・アンド・ペーストをサポートしています。コピー可能なテキスト・フィールドにマウスを置くと、カーソルがI字状になります。マウスをクリックしてテキストをコピーすると、その行が選択された状態になります。

編集可能なコンポーネントがすべて、クリックして編集するモードで表示されるわけではありません。たとえば、HTMLの入力要素を複数行表示するコンポーネントがこれに当たります。次のコンポーネントが含まれます。

- SelectManyCheckbox

- SelectManyListBox

- SelectOneListBox

- SelectOneRadio

- SelectManyShuttle

パフォーマンスのヒント:

レンダリングおよびポストバック中のパフォーマンスを向上させるには、表での編集を1行のみに構成する必要があります。

出力コンポーネントは入力コンポーネントよりも少ないHTMLを生成するため、一度に1行のみ編集することを選択した場合、ページはより迅速に表示されます。また、クライアント・コンポーネントは読取り専用行に対して作成されません。表(またはツリーやツリー表)はユーザーがある行から次の行に移動したときにPPRを実行するため、その行のデータのみ送信されます。これにより、すべてのセルの編集を許可して一度に表のすべての行のすべてのデータを送信する表よりもパフォーマンスが向上します。単一行の編集のみ許可すると、単一行のデータのみが検証のために送信され、その行のエラーのみ表示されるため、検証もより直感的になります。

12.2.5 表、ツリーおよびツリー表でのポップアップ・ダイアログの使用

表、ツリーまたはツリー表は、ユーザーのアクションに基づいてポップアップ・ダイアログが表示されるように構成できます。たとえば、ユーザーがセルまたはノード上にマウスを置いた場合に、選択された行の一部のデータが表示されるようにポップアップ・ダイアログを構成できます。ユーザーが表やツリー表の行、またはツリーのノードを右クリックした場合のために、ポップアップ・メニューを作成することも可能です。また、表やツリー表では、ユーザーが特定の行ではなく、表の任意の場所を右クリックした場合のために、ポップアップ・メニューを作成できます。

すべての表、ツリーおよびツリー表には、contextMenuファセットが含まれます。ポップアップ・メニューをこのファセットに配置すると、ユーザーが行を右クリックした場合に、関連するメニューが表示されます。サーバーでポップアップ・メニューがフェッチされると、コンポーネントにより、ポップアップ・メニューが表示されている行に対しての現行性が自動的に確立されます。現行性の確立とは、表のモデルの現行行が、ポップアップ・メニューが表示されている行を指すことです。これを実現するには、表示されるたびにメニューをフェッチできるように、メニューが含まれるpopupコンポーネントのcontentDelivery属性がlazyUncachedに設定されている必要があります。

ヒント:

選択された行に基づいて、ポップアップ・メニューにコンテンツが動的に表示されるようにするには、ポップアップ・コンテンツの配信をlazyUncachedに設定します。また、現在行を取得し、その現在行に基づいてデータを表示できるマネージドBeanのメソッドにsetPropertyListenerタグを追加します。

<af:tree value="#{fs.treeModel}"
contextMenuSelect="false" var="node" ..>
<f:facet name="contextMenu">
<af:popup id="myPopup" contentDelivery="lazyUncached">
<af:setPropertyListener from="#{fs.treeModel.rowData}"
to="#{dynamicContextMenuTable.currentTreeRowData}"
type="popupFetch" />
<af:menu>
<af:menu text="Node Info (Dynamic)">
<af:commandMenuItem actionListener=
"#{dynamicContextMenuTable.alertTreeRowData}"
text=
"Name - #{dynamicContextMenuTable.currentTreeRowData.name}" />
<af:commandMenuItem actionListener=
"#{dynamicContextMenuTable.alertTreeRowData}"
text=
"Path - #{dynamicContextMenuTable.currentTreeRowData.path}" />
<af:commandMenuItem actionListener=
"#{dynamicContextMenuTable.alertTreeRowData}"
text="Date -
#{dynamicContextMenuTable.currentTreeRowData.lastModified}" />
</af:menu>
</af:menu>
</af:popup>
</f:facet>
...
</af:tree>

バッキングBeanのコードは次のようになります。

public class DynamicContextMenuTableBean
{
...
public void setCurrentTreeRowData(Map currentTreeRowData)
{
_currentTreeRowData = currentTreeRowData;
}

public Map getCurrentTreeRowData()
{
return _currentTreeRowData;
}

private Map _currentTreeRowData;
}

表およびツリー表には、bodyContextMenuファセットが含まれます。メニューが含まれるポップアップをこのファセットに追加すると、ユーザーが特定の行ではなく、表をクリックした場合に表示されます。

ポップアップ・メニューの作成の詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

12.2.6 クライアントのコレクション・コンポーネントへのアクセス

ADF Facesでは、コレクションベース・コンポーネントの内容はサーバーでレンダリングされます。次のような場合には、クライアントがサーバー上のそのコンテンツにアクセスする必要があります。

- クライアント側のアプリケーション・ロジックが、行固有のコンポーネントの状態を読み取る必要がある場合。たとえば、行の選択の変更に応じて、ページ内のその他のコンポーネント(通常はメニュー項目やツールバー・ボタン)の無効化や表示の状態をアプリケーションで更新する必要がある場合です。このロジックは、スタンプ設定されたinputHiddenコンポーネントを使用してクライアントに送信される、行固有のメタデータに依存している場合があります。これを有効化するために、アプリケーションでは、スタンプ設定されたコンポーネントから行固有の属性値を取得できる必要があります。

- クライアント側のアプリケーション・ロジックが、行固有のコンポーネントの状態を変更する必要がある場合。たとえば、表の行にあるスタンプ設定されたコマンド・リンクをクリックすると、同じ行のその他のコンポーネントの状態が更新される場合です。

- ピアはコンポーネント・インスタンスにアクセスしてイベント処理動作を実行することが必要な場合があります(詳細は、4.1項「ADF Facesアーキテクチャの使用について」を参照してください)。たとえば、マウスのクリックに対してクライアント側アクション・イベントを配信するには、AdfDhtmlCommandLinkPeerクラスに、イベント・ソースとして機能するコンポーネント・インスタンスへの参照が必要です。コンポーネントでは、クライアント・リスナーや、イベント配信動作を制御するdisabledやpartialSubmitなどの属性を含め、関連状態が保持されます。

ADF Facesフレームワークでは、クライアント側でELがサポートされないのみでなく、クライアントへの表モデル全体の送信もサポートされていないため、クライアント側のコードは、値にアクセスするようスタンプ設定されているコンポーネントに依存できません。各行で同じコンポーネント・インスタンスを再利用するかわりに、各行に新しいJavaScriptクライアント・コンポーネントが作成されます(どの行にもコンポーネントが1つ作成される必要があると仮定しています)。

そのため、クライアント上の行固有のデータにアクセスするには、それ自体がスタンプ設定されたコンポーネントを使用して値にアクセスする必要があります。クライアント側のデータ・モデルを使用せずにこれを実現するには、クライアント側の選択変更リスナーを使用します。詳細な手順は、第12.13項「コレクションベースのコンポーネントからクライアント上の選択された値へのアクセス」を参照してください。

12.2.7 表、ツリーおよびツリー表コンポーネントのジオメトリ管理

デフォルトでは、表、ツリーおよびツリー表は子を拡大するコンポーネント(たとえば、panelStretchLayoutコンポーネントの内部のpanelCollectionコンポーネント)に配置され、表、ツリーまたはツリー表は既存の領域に合せて拡大されます。ただし、列を表全体に拡大するには、columnStretching属性を使用して、特定の列が未使用の領域全体に拡大されるように指定する必要があります。そうしないと、表はできるだけ多くの行に合せて垂直にのみ拡大されます。図12-13に示すように列は拡大されません。

図12-13 表は拡大されるが列は拡大されない

子を拡大しないコンポーネント(たとえば、verticalに設定されたpanelGroupLayoutコンポーネントの内部のpanelCollectionコンポーネント)に配置されたときは、デフォルトでは、図12-14に示すように、表の幅は300px (27.27em単位。11pxフォント設定で換算すると300px)に設定され、デフォルトのフェッチ・サイズは25行を返すように設定されます。

図12-14 表は拡大されない

子を拡大しないコンポーネントに表を配置する場合は、autoHeightRows属性を使用して、指定した行数より多く表示されないように表の高さを制御できます。この属性を正の整数に設定した場合、表の高さは行セットの数によって決定されます。その数値がfetchSize属性より大きい場合は、fetchSize属性の行数のみ返されます。autoHeightRowsを-1(デフォルト)に設定して、自動サイズ設定をオフにできます。

自動サイズ設定は、子を拡大するコンポーネントと拡大しないコンポーネントの両方で同じ表を使用する場合に役立つことがあります。たとえば、6列があり、12行を表示できる表があるとします。これを子を拡大するコンポーネントで使用する場合は、表を使用可能な領域に合せて拡大します。その表を子を拡大しないコンポーネントで使用する場合は、表の高さを修正できるようにします。ただし、表の高さを設定すると、他のコンポーネントに配置した場合に、その表は拡大されません。この問題を解決するには、autoHeightRows表は行の数に応属性を設定します(拡大するコンポーネントでは無視され、拡大しないコンポーネントでは適用されます)。

注意:

autoHeightRows属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。親が拡大可能な場合は必ず表コンポーネントが拡大され、そうでない場合はfetchSize属性のサイズになるようにするには、autoHeightRows属性ではなく、DEFAULT_DIMENSIONSパラメータを設定してください。autoHeightRows属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSは、autoHeightRowsの値が-1 (表は拡大されない)になるように設定されます。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

12.3 表へのデータの表示

表コンポーネントの直接的な子は、columnコンポーネントである必要があります。表示されるそれぞれの列コンポーネントは、表の個別の列として表示されます。列コンポーネントには、コンテンツやイメージの表示、またはその他の機能の提供に使用されるコンポーネントが含まれます。列コンポーネントで使用可能な機能の詳細は、12.3.1項「列および列データ」を参照してください。

各列の子コンポーネントは、その列の各行のデータを表示します。列では、子コンポーネントは行ごとには作成されませんが、表では各行のレンダリングにスタンプ設定機能が使用されます。各子には、行ごとに一度スタンプが設定され、これがすべての行に対して繰り返されます。各行にスタンプが設定されると、現在行のデータが、EL式を使用して特定可能なプロパティにコピーされます。このプロパティに使用する名前を、表のvarプロパティを使用して指定します。表のレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

このスタンプ設定動作のため、一部のコンポーネントが列内で機能しない場合があります。入力および出力コンポーネントなど、大部分のコンポーネントは問題なく機能します。セル内に複数のコンポーネントを使用する必要がある場合は、それらをpanelGroupLayoutコンポーネントでラップします。表内の表など、それ自体がスタンプ機能をサポートしているコンポーネントはサポートされていません。実行時に値が動的に決定されるコンポーネントの使用方法の詳細は、12.3.9項「表の選択コンポーネント値の動的な決定に関する必知事項」を参照してください。

表にdetailStampファセットを使用して、オプションで表示または非表示にできるデータを指定できます。このファセットにコンポーネントを追加すると、表の各行に、展開および縮小するためのアイコンが付いた追加の列が表示されます。ユーザーがアイコンをクリックして開くと、図12-15に示すように、ファセットに追加されたコンポーネントが表示されます。

図12-15 オプションで表示可能な追加のデータ

ユーザーが開かれた状態のアイコンをクリックして閉じると、図12-16に示すように、コンポーネントが非表示になります。

図12-16 追加のデータを非表示にすることが可能

detailStampファセットの使用方法の詳細は、12.4項「表への非表示機能の追加」を参照してください。

12.3.1 列および列データ

列には、データの表示に使用されるコンポーネントが含まれます。前述したように、各項目の表示に必要な子コンポーネントは1つのみで、値は表のレンダリング時にスタンプ設定されます。列はソート可能であり、ソート時に大文字と小文字を区別するかどうかを構成できます。デフォルトでは、大文字と小文字が区別されます。

列にはフィルタリング要素を入れることもできます。ユーザーがフィルタに値を入力すると、フィルタに入力した値に一致するデータ・セットが返されます。フィルタは、大文字と小文字を区別する、または大文字と小文字を区別しないように設定できます。これが許可されるように表が構成されている場合、ユーザーは列を並べ替えることもできます。

列には、ヘッダー・ファセットとフッター・ファセットの両方があります。ヘッダー・ファセットは、列のヘッダー・テキスト属性のかわりに使用できるため、スタイル設定可能なコンポーネントを使用できます。フッター・ファセットは、列の下部に表示されます。たとえば、図12-17では、フッター・ファセットを使用して、2つの列の下部に合計が表示されています。戻された行数が表示可能な範囲を超えている場合、フッター・ファセットは表示されますが、ユーザーは最後の行までスクロールできます。

図12-17 列のフッター・ファセット

12.3.2 表の書式設定

表コンポーネントには、ユーザーを支援する書式設定や視覚的な補助が多数用意されています。これらの機能を有効にし、どのように表示するかを指定できます。次の機能が含まれます。

- 行の選択: デフォルトでは、ユーザーは実行時に行を選択できません。ページのその他の場所または別のページにおいて、行でアクションを実行するために、ユーザーが行を選択できるようにするには、rowSelection属性を設定して、表で行の選択を有効化します。表は、単一の行または複数の行を選択できるように構成できます。選択された行でプログラムを使用してアクションを実行する方法の詳細は、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

- スクロール/ページ区切り: デスクトップ・デバイスでは、ユーザーはすべての行をスクロールできるように、デフォルトで表にスクロールバーがレンダリングされます。タブレット・デバイスでは、スクロールバーのかわりに表にページ番号が付けられ、ユーザーが特定の行のあるページにジャンプできるフッターが表示されます。デフォルトは、scrollPolicy属性を設定することで変更できます。

- 表の高さ: 表の高さを絶対的(300ピクセルなど)に設定することも、autoHeightRows属性を使用して、一度に表示する行数に基づいて表の高さを決定することもできます。詳細は、12.2.7項「表、ツリーおよびツリー表コンポーネントのジオメトリ管理」を参照してください。

注意:

表がpanelSplitterコンポーネントなどのレイアウト管理コンテナに配置されている場合、表はコンテナによりサイズ設定され、autoHeightRowsは適用されません。

注意:

JavaScriptを使用して、表を動的にサイズ変更することはできません。表の高さは初めてレンダリングされるときに設定され、JavaScript APIを使用して変更することはできません。

- グリッド線: デフォルトで、ADF表コンポーネントには、水平および垂直の両方のグリッド線が描画されます。これらは、horizontalGridVisibleおよびverticalGridVisible属性を使用して個別に無効化できます。

- バンディング: columnBandingInterval属性を使用して、行または列のグループが異なる背景色で交互に表示されます。これは、隣り合う行または列のグループを区別する際に役立ちます。デフォルトでは、バンディングは無効化されています。

- 列グループ: 表の列は、列コンポーネントをネストさせることで、列グループにグループ化できます。各グループには、すべての列をリンクする独自の列グループ見出しを設定できます。

- 編集可能セル: 表へのデータの表示に入力テキスト・コンポーネントを使用する場合は、すべてのセルを編集できるように表を構成することも、ユーザーが明示的にセルをクリックして編集するように構成することもできます。詳細は、12.2.4項「表、ツリーおよびツリー表のデータの編集」を参照してください。

パフォーマンスのヒント:

ユーザーがクリックした場合にのみセルの編集を可能にすると、表は最初はより早くロードされます。これは、表に大量のデータを表示する場合に便利です。

- 列の拡大: 列の幅すべてを合せても表全体に満たない場合は、columnStretching属性を設定し、領域を埋めるために列を拡大するかどうか、拡大する場合はどの列を拡大するかを決定できます。列の最小の幅を設定して、表に多くの列があり、拡大を有効にする場合に、列が設定した最小幅より小さくならないようにすることができます。拡大する各列の幅の割合を設定して、列が拡大されたときに占める領域の量を決定することもできます。

注意:

列の最小幅の合計がビューポートの表示可能領域以上である場合、表はビューポートの外部に拡張され、ビューポートの外部にアクセスするためのスクロールバーが表示されます。

パフォーマンスのヒント:

列の拡大はデフォルトで無効化されています。この機能を有効化すると、複雑な表(データ量の多い表や、列がネストしている表など)に使用した場合には、クライアントのレンダリング時間のパフォーマンスに影響があります。

注意:

行ヘッダーとして構成された列または固定として構成された列は拡大されません。拡大すると、ユーザーが表のスクロール可能な本体にアクセスできなくなる可能性が高くなるためです。

- 列の選択: ユーザーにデータの列の選択を許可できます。行の選択同様、単一の列または複数の列を選択できるように構成できます。columnSelectionListenerを使用して、新しい列がユーザーによって選択されたときに呼び出されるColumnSelectionEventに応答することもできます。このイベントにより、選択解除された列や選択された列が報告されます。

- 列の並替え: ユーザーは、実行時に列ヘッダーをドラッグ・アンド・ドロップして列を並べ替えられます。デフォルトでは、列の並替えが許可されており、panelCollectionコンポーネントのメニュー項目で処理されます。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

- 列の固定: 列を固定し、スクロールされても見えなくならないように表を構成できます。列は、表の右側または左側に固定できます。これは、表のfreezeDirection属性で制御されます。列のfrozen属性を使用して、固定を開始する列を選択します。

12.3.3 列の書式設定

各列コンポーネントにも、ユーザーを支援する書式設定や視覚的な補助が多数用意されています。これらの機能を有効にし、どのように表示するかを指定できます。次の機能が含まれます。

- 列のソート: ユーザーが、指定された列を基準とし、sortable属性を使用して昇順または降順にコンテンツをソートできるよう列を構成できます。列ヘッダーの特別なインジケータにより、ユーザーは列がソート可能であることがわかります。ユーザーがアイコンをクリックして、前にソートされていない列をソートすると、列のコンテンツは昇順でソートされます。次に同じヘッダーをクリックすると、コンテンツは降順でソートされます。
ソートでは、デフォルトで大文字と小文字が区別されます。つまり、ソートするとabcはABCより前になります。かわりに、abcとABCとを区別せずソートするように列を構成するには、sortStrength属性を使用します。

表をソートできるようにするには、基礎となるデータ・モデルでもソートがサポートされている必要があります。詳細は、12.3.7項「プログラムを使用した表の列のソートの有効化に関する必知事項」を参照してください。

- コンテンツの位置合せ: align属性を使用して、列内のコンテンツをstart、end、left、rightまたはcenterに位置合せできます。

ヒント:

アプリケーションで複数の読み方向がサポートされている場合は、leftおよびrightではなく、startおよびendを使用します。

- 列の幅: width属性を使用して、列の幅をピクセル単位の絶対値として指定できます。列を拡大可能として構成する場合、幅を割合として設定することもできます。

- 列のまたがり: colSpan属性を使用して、他の列にまたがる列を構成できます。ただし、通常は、spanの値にEL式を使用して、実際には列の特定のセルのみが複数列にまたがることができるようにします。たとえば、図12-18に示すツリー表では、そのノードが親ノードである場合のみに、右にあるすべての行にまたがるようにcolSpanの値が設定されています。

図12-18 複数列にまたがるのはノードが親のときのみ

- 行折返し: noWrap属性を使用し、行を越えて列のコンテンツを折り返すかどうかを定義できます。デフォルトでは、コンテンツは折り返されません。

- 行ヘッダー: rowHeader属性を使用して、一番左の列を行ヘッダーに定義できます。その場合、一番左の列は列ヘッダーと同じ外観でレンダリングされますが、スクロールしてページから見えなくなることはありません。図12-19に、最初の列が行ヘッダーとして構成されている場合に部門を表示する表がどのように表示されるかを示します。

図112-19 表の行ヘッダー

行ヘッダー列の使用を選択し、行を選択できるように表を構成した場合、ユーザーが行の上にマウスを置くと、行ヘッダー列には図12-20に示すような選択矢印が表示されます。

図12-20 行ヘッダーの選択アイコン

複数選択が許可される表では、ユーザーはマウスをクリックして行ヘッダーをドラッグし、連続した行ブロックを選択できます。また、ユーザーが上または下にドラッグすると、表が垂直に自動スクロールします。

加えて、エラーが発生した結果としてその行のコンポーネントに対するメッセージが生成された場合は、重大度を表すアイコンが行ヘッダーに表示されます。複数のメッセージが存在する場合は、重大度が最も高いアイコンが表示されます。図12-21で行ヘッダーにエラーのアイコンが表示されているのは、入力された日付が正しくないからです。

図12-21 行ヘッダーに表示されるメッセージ・アイコン

パフォーマンスのヒント:

行ヘッダーを使用すると表の複雑さが増し、パフォーマンスに悪影響が及ぶことがあります。

ヒント:

列の並替えや列幅の変更など、ユーザーは実行時に表が表示される方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

12.3.4 ページへの表の表示方法

「ADF Faces Tableの作成」ダイアログを使用して、JSFページに表を追加できます。このダイアログは、表に必要な各列へのcolumnコンポーネントの追加にも使用できます。また、EL式を使用して基礎となるモデルまたはBeanに表をバインドできます。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表を作成すると、バインディングが実行されます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「ADFによるデータバインドされた表の作成」の章を参照してください。

ダイアログでの入力が完了して、表と列がページに追加されたら、「プロパティ」ウィンドウを使用して表または列の追加の属性を構成することや、表イベントに応答するためのリスナーを追加することができます。表のバインド先となるCollectionModelクラスを実装する必要があります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.3項「表へのデータの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

ページに表を表示する手順:

1. org.apache.myfaces.trinidad.model.CollectionModelクラスを拡張するJavaクラスを作成します。
コレクション・コンポーネントでは、CollectionModelクラスを使用して基礎となるコレクションのデータにアクセスします。このクラスはJSFのDataModelクラスを拡張したものですが、索引ではなく行キーに基づいて基礎となるデータの変更をサポートしています。また、ソートなど、より高度な機能もサポートします。

java.util.List、arrayおよびjavax.faces.model.DataModelなど、別のモデル・クラスも使用できます。このような別のクラスのいずれかを使用する場合は、コレクション・コンポーネントにより、インスタンスがCollectionModelクラスに自動的に変換されますが、機能は追加されません。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

2. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「表」をページにドラッグ・アンド・ドロップします。

3. 「ADF Faces表の作成」ダイアログを使用して、表を任意の既存モデルにバインドします。表が有効なモデルにバインドされると、作成される列がダイアログにより自動的に表示されます。ダイアログを使用して列のheaderおよびvalue属性の値を編集し、データの表示に使用されるコンポーネントのタイプを選択します。または、手動で列を構成し、後日バインドすることもできます。ダイアログのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

注意:

inputTextコンポーネントを使用してCharacter Large Object (CLOB)を表示する場合は、CLOBを文字列に変換するカスタム・コンバータを作成する必要があります。変換の詳細は、第7章の「カスタムADF Facesコンバータの作成」を参照してください。

4. 「プロパティ」ウィンドウで「共通」セクションを開きます。すでに表をモデルにバインドしてある場合は、value属性を設定します。このセクションを使用して、表固有の次の属性を設定できます。

- RowSelection: 行を選択可能にする場合に値を設定します。有効な値はnone、single、multipleおよびmultipleNoSelectAllです。

注意:

ユーザーは、rowSelection属性がmultipleに設定され、その表に行ヘッダーも含まれている場合に、行ヘッダーの列ヘッダーをクリックして表のすべての行およびすべての列を選択できます。ユーザーがすべての列および行を選択できないようにするには、rowSelectionをmultipleNoSelectAllに設定します。

選択された行でプログラムを使用してアクションを実行する方法の詳細は、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

- ColumnSelection: 列を選択可能にする場合に値を設定します。有効な値はnone、singleおよびmultipleです。

5. 「列」セクションを開きます。「ADF Faces Tableの作成」ダイアログを使用して表をバインドしてある場合、これらの設定を完了する必要があります。このセクションを使用して、表のバインドの変更、各行のデータへのアクセスに使用される変数名の変更、および各列に使用される表示ラベルやコンポーネントの変更を実行できます。

ヒント:

リストに表示されていないコンポーネントを使用する場合は、「プロパティ」ウィンドウで任意のコンポーネントを選択してから、手動で変更してください。

1. 「構造」ウィンドウで、ダイアログによって作成されたコンポーネントを右クリックして「変換」をクリックします。

2. リストから必要なコンポーネントを選択します。これで、「プロパティ」ウィンドウを使用して新しいコンポーネントを構成できます。

ヒント:

列に複数のコンポーネントを表示する場合は、その他のコンポーネントを手動で追加し、それらをpanelGroupLayoutコンポーネントでラップします。これを行うには:

1. 構造ウィンドウで、1つ目のコンポーネントを右クリックし、「前に挿入」または「後ろに挿入」を選択します。挿入するコンポーネントを選択します。

2. デフォルトで、コンポーネントは縦に表示されます。1つの列内に複数のコンポーネントを隣接させて表示するには、[Shift]キーを押して、「構造」ウィンドウで両方のコンポーネントを選択します。選択内容を右クリックし、「囲む」を選択します。

3. panelGroupLayoutを選択します。

6. 「外観」セクションを開きます。このセクションを使用し、次に示す表固有の属性を設定して、表の外観を設定します。

- Width: 表の幅を指定します。ピクセル数または割合で幅を指定できます。デフォルト設定は300ピクセルです。(columnStretching属性を使用して)列を拡大するように表を構成する場合は、幅を割合に設定する必要があります。

ヒント:

表が、子を拡大するコンポーネントの子である場合、この幅の設定はオーバーライドされ、表はコンテナに合うように自動的に拡大されます。コンポーネントの拡大方法の詳細は、12.2.7項「表、ツリーおよびツリー表コンポーネントのジオメトリ管理」を参照してください。

- ColumnStretching: 列の幅すべてを合せても表全体に満たない場合は、この属性を設定し、領域を埋めるために列を拡大するかどうか、拡大する場合はどの列を拡大するかも決定できます。

注意:

子を拡大するコンポーネントの中に表が配置されている場合、自動的に拡大されるのは表のみです。表に合うように列を拡大する場合、列の拡大は手動で構成する必要があります。

注意:

行ヘッダーとして構成された列または固定として構成された列は拡大されません。拡大すると、ユーザーが表のスクロール可能な本体にアクセスできなくなる可能性が高くなるためです。

パフォーマンスのヒント:

列の拡大はデフォルトで無効化されています。この機能を有効化すると、クライアントにおける複雑な表のレンダリング時間のパフォーマンスに影響する場合があります。

列の拡大を次のいずれかの値に設定できます。

- blank: 空の列を自動的に挿入して拡大する場合に使用します(表の幅全体が行の背景色になります)。

- 名前が指定された列: 現在表にある列を拡大する列として選択できます。

- last: 最後の列を、ウィンドウ内の使用されていない領域に合せて拡大する場合に使用します。

- none: 何も拡大されないデフォルトのオプションです。パフォーマンスを最適化する場合に使用します。

- multiple: width属性にパーセント値が設定されたすべての列がそのパーセント値まで拡大されます。これは、他の列が(拡大されない)幅にレンダリングされた後に行われます。割合値は合計で加重されます。たとえば、これらの列のwidth属性を50%に設定した場合、各列は、他のすべての列がレンダリングされた後の残り領域の1/3を占めます。

ヒント:

列の幅は実行時に変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの幅値は保持されません。変更の永続性の有効化および使用方法の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- HorizontalGridVisible: 水平のグリッド線を描画するかどうかを指定します。

- VerticalGridVisible: 垂直のグリッド線を描画するかどうかを指定します。

- RowBandingInterval: 色のバンディングの目的で、連続する何行で行グループを形成するかを指定します。デフォルトでは、これは0に設定されており、すべての行が同じ背景色で表示されます。別の色を使用する場合は、これを1に設定します。

- ColumnBandingInterval: 列のバンディングが行われる間隔を指定します。この値により、表の列バンディングの表示が制御されます。たとえば、columnBandingIntervalが1の場合、表内にバンディングされた列が交互に表示されます。

- FilterVisible: 入力されたフィルタ基準に一致する行のみが表示されるように、表にフィルタを追加できます。フィルタ処理を許可するように表を構成する場合、大文字と小文字を区別する、または大文字と小文字を区別しないようにフィルタを設定できます。詳細は、12.5項「表でのフィルタ処理の有効化」を参照してください。

- ScrollPolicy: デスクトップ・デバイスでは、デフォルトで表にスクロールバーがレンダリングされ、ユーザーはすべての行をスクロールできます。タブレット・デバイスでは、スクロールバーのかわりに表にページ番号が付けられ、ユーザーが特定の行のあるページにジャンプできるフッターが表示されます。このデフォルトの動作を維持するには、値をautoに設定します。表に必ずスクロールバーが表示されるようにするには、値をscrollに設定します。表で行が必ず一連のページとして表示され、各ページに移動するナビゲーションがフッターに表示されるようにするには、値をpageに設定します。

注意:

表をページ区切りで表示するには、scrollPolicy属性とautoHeightRows属性をそれぞれpageと0に設定し、表をフロー・コンテナ(子を拡大しないコンポーネント)の中に配置する必要があります。これらの条件が満たされない場合、表にはスクロールバーが表示されます。フロー・コンテナ・コンポーネントの詳細は、第9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- テキスト属性: アクセシビリティを目的とした表のサマリーや説明だけでなく、行を表示できない場合に表示されるテキストを決定するテキスト文字列を定義できます。

7. 「動作」セクションを開きます。このセクションを使用し、次に示す表固有の属性を設定して、表の動作を構成します。

- ColumnResizing: エンド・ユーザーが実行時に列の幅をサイズ変更できるようにするかどうかを指定します。disabledに設定した場合、列の幅はページがレンダリングされた後で設定され、ユーザーはそれらの幅を変更できません。

ヒント:

columnResizingがtrueに設定されている場合、ユーザーは実行時に列幅の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの幅値は保持されません。変更の永続性の有効化および使用方法の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- DisableColumnReordering: デフォルトでは、panelCollectionコンポーネントにデフォルトで含まれるメニュー・オプションを使用して、実行時に列を並べ替えられます。これは、ユーザーが列の順序を変更できないように変更できます。(panelCollectionコンポーネントには、表、ツリーおよびツリー表のデフォルトのメニューとツールバー・ボタンが用意されています。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。)

注意:

ユーザーは列の順序を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- FetchSize: 各データ・フェッチで戻されるブロックのサイズを設定します。デフォルトは25です。

ヒント:

表に合せるには何行必要であるかを判断するには、表の高さを取得して各行の高さで割ることで、fetchSize属性の値を決定する必要があります。fetchSize属性の値が小さすぎると、表を埋めるためにサーバーと何度もやりとりすることになります。値が大きすぎると、サーバーでは、データ・ソースから必要以上に行がフェッチされ、時間とメモリー使用量が増加します。クライアント側では、それらの行の処理とコンポーネントへのアタッチに時間がかかります。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、コンポーネントのレンダリングと同時にデータがフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中にデータがフェッチされてクライアントに送信されます。属性がwhenAvailable(デフォルト)に設定されている場合、レンダラはデータが使用可能かどうかをチェックします。使用可能な場合、コンテンツは即時に配信されます。使用可能でない場合は、遅延配信が使用されます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- AutoHeightRows: 表に初期状態で表示する行の数を指定します。返された行の数がこの値を超えている場合は、スクロールバーが表示されます。表がfetchSizeと同じサイズになるようにするには、0に設定します。表の親コンテナが子を拡大するように構成されている場合に親コンテナいっぱいに表が拡大されるようにするには、-1を設定します(表の拡大の詳細は、12.2.7項「表、ツリーおよびツリー表コンポーネントのジオメトリ管理」を参照)。それ以外の場合は、fetchSizeの現在の設定より小さい特定の数に設定してください。

注意:

autoHeightRows属性の設定について、次の点に注意してください。

- inlineStyle属性に高さを指定しても効果はなく、AutoHeightRowsの値でオーバーライドされます。

- inlineStyle属性にmin-heightまたはmax-heightを指定することは推奨されず、autoHeightRows属性と互換性がありません。

- コンポーネントをpanelSplitterのようなレイアウト管理コンテナに配置すると、このコンテナによりコンポーネントのサイズが指定されます(自動のサイズ指定は発生しません)。

注意:

autoHeightRows属性のデフォルト値は、DEFAULT_DIMENSIONS web.xmlパラメータによって決まります。親が拡大可能な場合は必ず表コンポーネントが拡大され、そうでない場合はfetchSize属性のサイズになるようにするには、autoHeightRows属性ではなく、DEFAULT_DIMENSIONSパラメータをautoに設定してください。

DEFAULT_DIMENSIONSパラメータをautoに設定し、子を拡大しない親の中に表を配置する場合、autoHeightRows属性をオーバーライドする値がなければ、表の幅はAFStretchWidthスタイル・クラスから取得されます。この場合、表の幅はデフォルトで子の列コンポーネントを収容できるように拡大されます。

autoHeightRows属性は、グローバル設定をオーバーライドする場合に設定します。

デフォルトでは、DEFAULT_DIMENSIONSは、autoHeightRowsの値が-1 (表は拡大されない)になるように設定されます。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

- DisplayRow: 最初に表示される際に表に表示する行を指定します。使用可能な値は、表の上部に最初の行を表示する場合はfirst、表の下部に最後の行を表示する場合はlast(ユーザーが先行する行を表示するには上にスクロールする必要があります)、表で最初に選択された行を表示する場合はselectedです。

注意:

この属性が正常に機能するには、表モデルの合計の行数が把握されている必要があります。

- EditingMode: 編集可能なコンポーネントに、すべての行を編集可能にするか(editAll)、ユーザーがクリックした場合に編集可能にするか(clickToEdit)を指定します。詳細は、12.2.4項「表、ツリーおよびツリー表のデータの編集」を参照してください。

ヒント:

clickToEditを選択した場合は、アクティブな行のみ編集できます。この行はactiveRowKey属性によって決定されます。デフォルトでは、表が最初にレンダリングされるときに、アクティブな行は最初に表示される行です。ユーザーが別の行をクリックすると、その行がアクティブな行になります。activeRowKey属性に別の値を設定することで、この動作を変更できます。

- ContextMenuSelect: ポップアップ・メニューを開くために右クリックする際に、行を選択するかどうかを指定します。trueに設定すると、行が選択されます。ポップアップ・メニューの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- FilterModel: filterVisibleとともに使用します。詳細は、12.5項「表でのフィルタ処理の有効化」を参照してください。

- 様々なリスナー: 表で対応するイベントが起動された場合に実行されるメソッドにリスナーをバインドします。詳細は、第6章「イベントの処理」を参照してください。

8. 「拡張」セクションを開き、次の表固有の属性を設定します。

- activeRowKey: clickToEditを選択すると、アクティブな行のみを編集できます。この行はactiveRowKey属性によって決定されます。デフォルトでは、表が最初にレンダリングされるときに、アクティブな行は最初に表示される行です。ユーザーが別の行をクリックすると、その行がアクティブな行になります。activeRowKey属性に別の値を設定することで、この動作を変更できます。

- DisplayRowKey: 最初に表示される際に表に表示する行キーを指定します。値が文字列ではない場合があるため、属性は宣言的にではなくプログラムで設定する必要があります。この属性を指定すると、displayRow属性がオーバーライドされます。

注意:

この属性が正常に機能するには、表モデルの合計の行数が把握されている必要があります。

9. 「その他」セクションを開き、次の設定を行います。

- BlockRowNavigationOnError: 検証エラーが存在する行からユーザーが移動できるようにする場合に指定します。alwaysに設定すると、行の検証エラーが発生したときは常に、ユーザーが別の行に移動することは禁止されます。neverに設定すると、ユーザーが別の行への移動を禁止されることはなくなります。auto (デフォルト)に設定すると、ユーザーが移動できるかどうかはフレームワークによって決定されます。
たとえば、表の値がそのページ上の別のコンポーネントとの間で共有されていることがあります。1つの表で、ユーザーが多数のレコードを表示できるようになっているとします。特定のレコードが選択されたときに、その情報がフォーム内に表示されます。ユーザーがそのフォームでデータを変更したことが原因でエラーが発生した場合に、ユーザーが表をスクロールしてそのレコードから移動することができないようにするとします。この例の場合は、BlockRowNavigationOnErrorを「always」に設定します。

- FreezeDirection: 列を固定可能にする場合は、列を表の先頭(LTRロケールの左側)と表の末尾(LTRロケールの右側)のどちらから固定するかを指定します。固定を開始する列を、該当の列のfrozen属性を使用して構成する必要があります。
たとえば、最初の3列を固定する場合を考えます。表のfreezeDirectionをstartに設定し、3番目の列のfrozenをtrueに設定します。

最後の4列を固定する場合は、freezeDirectionをendに設定し、最後から4番目の列のfrozenをtrueに設定します。

- SelectionEventDelay: ユーザーが上下の矢印キーを使用して表内を移動することが予想される場合は、trueに設定します。
ユーザーは、マウスとスクロールバーを使用するか、上下の矢印キーを使用して、表内を移動できます。デフォルトでは、ユーザーが行をクリックするとすぐに選択イベントが起動されます。つまり、ユーザーが矢印キーで行間を移動している場合は、ユーザーの移動に伴い、各行で選択イベントが起動されます。

ユーザーがキーを使用して表内を移動することが予想される場合は、selectionEventDelay属性をtrueに設定すると、選択イベントが300ミリ秒遅れて起動されるようになります。ユーザーが300ミリ秒以内に別の行に移動した場合、選択イベントは取り消されます。

10. 構造ウィンドウで列を選択します。「プロパティ」ウィンドウの「共通」セクションを開いて、次の列固有の属性を設定します。

- HeaderText: 列のヘッダーに表示するテキストを指定します。outputTextコンポーネントを含むheaderファセットを追加する場合と等しい出力内容が生成されるため便利です。outputText以外のコンポーネントを使用する場合は、かわりに列のheaderファセットを使用する必要があります(詳細は手順14を参照してください)。headerファセットを追加すると、headerText属性の値は列ヘッダーにレンダリングされません。

- Align: この列の配置を指定します。start、endおよびcenterを使用して、左から右への文字表示でそれぞれ左揃え、右揃え、中央揃えにします。leftまたはrightの値は、左から右と右から左のどちらの文字表示であるかにかかわらず、左揃えまたは右揃えのセルが必要な場合に使用できます。デフォルト値はnullで、これはスキンに依存し、行のヘッダー列とデータ列の対比で異なることを示します。スキンの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- Sortable: 列をソート可能にするかどうかを指定します。ソート可能な列には、クリックするとその列のプロパティで表がソートされるヘッダーがあります。列をソート可能にするには、sortable属性をtrueに設定し、この列のプロパティによるソートが、基礎となるモデルでサポートされている必要があることに注意してください。詳細は、12.3.7項「プログラムを使用した表の列のソートの有効化に関する必知事項」を参照してください。

注意:

列選択が有効になっている場合、列ヘッダーをクリックすると、列をソートするかわりに列が選択されます。この場合、列は昇順/降順ソート・インジケータをクリックすることでソートできます。

- SortStrength: ソート時に重要とみなされる差異のレベルを指定します。次の1つを選択します(これらの値は、Java Collatorオブジェクトでの値と同じです)。

- Primary: ソートでは文字自体が考慮されます。大文字と小文字の違いやアクセント記号は無視されます。abc、ÁBC、ábc、ABCをソートすると、abc、ÁBC、ábc、ABC (出現順)となります。これは、大文字と小文字を区別しない場合に指定します。

- Secondary: 文字を考慮してソートされ、その後でアクセント記号が考慮されます。大文字/小文字は無視されます。abc、ÁBC、ábcおよびABCは、abc、ABC、ÁBC、ábcとソートされます。アクセントのないロケールでは、結果的に大文字と小文字を区別しない検索が行われます。

- Tertiary: 文字を考慮してソートされ、その後でアクセント記号、大文字と小文字の違いの順に考慮されます。abc、ÁBC、ábc、ABCをソートするとabc、ABC、ábc、ÁBCとなります。アクセントのないロケールでは、結果的に大文字と小文字を区別する検索が行われます。

- Identical: 文字、アクセント、大文字/小文字、および他のあらゆる差異(句読点付きの単語など)が考慮されます。abc、ab-c、ÁBC、ábcおよびABCは、abc、ABC、ábc、ÁBC、ab-cとソートされます。この結果は大文字と小文字を区別する検索となり、これがデフォルトです。

- Filterable: 列をフィルタ処理可能にするかどうかを指定します。フィルタ処理可能な列には、列ヘッダーの上部にフィルタ・フィールドが配置されます。列をフィルタ処理可能にするには、この属性をtrueに設定し、表にfilterModel属性を設定する必要があることに注意してください。リーフ列のみがフィルタ処理可能で、フィルタ・コンポーネントは、列ヘッダーが存在する場合にのみ表示されます。この列のsortProperty属性は、filterModelクラスのfilterProperty属性のキーとして使用する必要があります。

注意:

フィルタ処理が有効化されている(filterable=true)列には、フィルタ基準入力フィールドとして使用する入力コンポーネントを指定できます。これを実行するには、列にフィルタ・ファセットを追加し、入力コンポーネントを追加します。詳細は、12.5項「表でのフィルタ処理の有効化」を参照してください。

11. 「外観」セクションを開きます。このセクションを使用し、次に示す列固有の属性を使用して、列の外観を設定します。

- DisplayIndex: 列の表示順序索引を指定します。列を並べ替えることが可能で、displayIndex属性に基づいて表に表示されます。displayIndex属性値が設定されていない列は、データ・ソースでの順序に基づいて最後に表示されます。親列の外にある子の列を並べ替えることはできないため、displayIndex属性はトップレベルの列にのみ適用されます。

- Width: 列の幅を指定します。表で列の拡大を使用する場合は、幅の割合を入力する必要があります。
列の拡大では、列の幅の割合が重みとして扱われます。たとえば、すべての列が50%の幅で、3つを超える列がある場合、各列には領域が均等に割り当てられますが、依然としてminWidth属性に設定された値が適用されます。

割合としての幅は領域の実際の割合ではなく重みであるため、表で列の拡大がオンになっていて、1列のみが割合の幅で拡大されるものとしてリストされている場合、その列は、残りの列のピクセル幅で指定されていない、表の残り領域をすべて使用します。

- MinimumWidth: 列幅の最低ピクセル数を指定します。ユーザーが列のサイズ変更を試行すると、この最小幅が強制されます。また、列がフレキシブルな場合にも、この最小幅より小さいサイズには縮小されません。ピクセル幅が定義されていて最小幅の方が大きい場合、最小幅は2つのうち小さい方の値になります。デフォルトで、最小幅は10ピクセルです。

- ShowRequired: 対応する属性にデータが必要な場合に、列ヘッダーにアスタリスクを表示するかどうかを指定します。

- HeaderNoWrapおよびNoWrap: コンテンツをヘッダーおよび列内で折り返すかどうかを指定します。

- RowHeader: 列を表の行ヘッダーにする場合は、trueに設定します。

パフォーマンスのヒント:

行ヘッダーを使用すると表の複雑さが増し、パフォーマンスに悪影響が及ぶことがあります。

12. 「動作」セクションを開きます。このセクションを使用し、次に示す列固有の属性を使用して、列の動作を構成します。

- SortProperty: この列によって表示されるプロパティを指定します。これは、フレームワークによって列のデータのソートに使用されるプロパティです。

- Frozen: 列を固定するかどうかを指定します。固定すると、スクロールしたときにページから消えることはなくなります。固定列までの表の列は、ヘッダーでロックされ、その他の列とともにスクロールされません。親を固定せずに子の列を単独で固定することはできないため、frozen属性はトップレベルの列にのみ適用されます。

注意:

デフォルトでは、この列とそれよりも左の列が固定されます。つまり、この列とそれよりも左にある列はスクロールされません。これを変更するには、表コンポーネントのfreezeDirection属性をendに設定します。デフォルトでは、startに設定されています。

パフォーマンスのヒント:

固定された列を使用すると表の複雑さが増し、パフォーマンスに悪影響が及ぶことがあります。

- Selected: trueに設定すると、最初のレンダリング時に列が選択されます。

13. この列が後続の列にまたがるようにするには、「その他」セクションを開いてColSpanを設定します。これには、その列がまたがる列の数を設定するか、表の最後までまたがる場合はALLを設定できます。その列のすべてのセルをまたがらせるわけではない場合は、EL式を使用し、解決した結果が特定のセルとなるように式を作成します。
例12-2に、ツリー表コンポーネントで親ノードのみがすべての列にまたがるようにcolSpanを設定する方法を示します。

例12-2 親ノードが表の末尾までまたがるcolSpanの設定

<af:column id="c1" sortable="true" sortProperty="Dname"
colSpan="#{testBean.container ? 'ALL' : '1'}"
headerText="DepartmentName">
<af:outputText value="#{node.Dname}" id="ot2"/>
</af:column>

例12-3に、対応するマネージドBeanコードを示します。

例12-3 列のまたがりを設定するためのマネージドBeanのコード

public class TestBean
{
public boolean isContainer()
{
return _treeTable.isContainer();
}
}

14. 既存の表に列を追加するには、「構造」ウィンドウで表を右クリックし、「表の中に挿入」→「列」を選択します。

15. 表にファセットを追加するには、表を右クリックして「ファセット - 表」を選択し、追加するファセットのタイプを選択します。その後、ファセットに直接コンポーネントを追加できます。

ヒント:

JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、これらの子コンポーネントを1つのコンテナ(たとえばpanelGroupLayoutコンポーネントやgroupコンポーネント)の中にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

16. 列にファセットを追加するには、列を右クリックして「ファセット - 列」を選択し、追加するファセットのタイプを選択します。その後、ファセットに直接コンポーネントを追加できます。

ヒント:

JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、これらの子コンポーネントを1つのコンテナ(たとえばpanelGroupLayoutコンポーネントやgroupコンポーネント)の中にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

17. 列にコンポーネントを子として追加し、データを表示します。
コンポーネントの値は、表のvar属性および表示する属性の変数値セットにバインドする必要があります。たとえば、File Explorerアプリケーションの表では、var属性の値としてfileが使用されており、1列目に各行のファイル名が表示されています。そのため、ディレクトリ名の表示に使用される出力コンポーネントの値は、#{file.name}です。

ヒント:

列の直接の子が入力コンポーネントの場合は、その幅を列幅に適切な幅に設定してください。幅が親列にとって広すぎる大きさに設定されていると、ブラウザにより、テキスト入力カーソルが必要以上に大きく拡大され、隣接する列を隠してしまう可能性があります。たとえば、inputTextコンポーネントのサイズが80ピクセルで、その親列のサイズが20ピクセルに設定されている場合、その表の入力カーソルは、隣接する列のクリック可能領域を覆ってしまいます。

入力コンポーネントが列の直接の子ではない場合に、サイズが自動的に設定されるようにするには、contentStyle="width:auto"を設定します。

12.3.5 ページに表を追加する場合の処理

JDeveloperを使用してページに表を追加すると、JDeveloperにより、各属性の列のある表が作成されます。表をモデルにバインドすると、列にはモデルの属性が反映されます。まだモデルにバインドしていない場合は、JDeveloperにより、デフォルト値を使用して列が作成されます。デフォルト値の変更(列の追加/削除、列ヘッダーの変更など)は、表作成ダイアログで行うことも、後で「プロパティ」ウィンドウを使用して行うこともできます。

例12-4に、File Explorerアプリケーション内の表の省略形のページ・コードを示します。

例12-4 File Explorerアプリケーション内のADF Facesの表

<af:table id="folderTable" var="file"
value="#{explorer.contentViewManager.
tableContentView.contentModel}"
binding="#{explorer.contentViewManager.
tableContentView.contentTable}"
emptyText="#{explorerBundle['global.no_row']}"
rowselection="multiple"
contextMenuId=":context1" contentDelivery="immediate"
columnStretching="last"
selectionListener="#{explorer.contentViewManager.
tableContentView.tableFileItem}"
summary="table data">
<af:column width="180" sortable="true" sortStrength="identical"
sortProperty="name"
headerText="" align="start">
<f:facet name="header">
<af:outputText value="#{explorerBundle['contents.name']}"/>
</f:facet>
<af:panelGroupLayout>
<af:image source="#{file.icon}"
inlineStyle="margin-right:3px; vertical-align:middle;"
shortDesc="file icon"/>
<af:outputText value="#{file.name}" noWrap="true"/>
</af:panelGroupLayout>
</af:column>
<af:column width="70" sortable="true" sortStrength="identical"
sortProperty="property.size">
<f:facet name="header">
<af:outputText value="#{explorerBundle['contents.size']}"/>
</f:facet>
<af:outputText value="#{file.property.size}" noWrap="true"/>
</af:column>
...
<af:column width="100">
<f:facet name="header">
<af:outputText value="#{explorerBundle['global.properties']}"/>
</f:facet>
<af:commandLink text="#{explorerBundle['global.properties']}"
partialSubmit="true"
action="#{explorer.launchProperties}"
returnListener="#{explorer.returnFromProperties}"
windowWidth="300" windowHeight="300"
useWindow="true">
</af:commandLink>
</af:column>
</af:table>

12.3.6 実行時の処理: データ配信

表を含むページがリクエストされ、コンテンツ配信がlazyに設定されている場合、ページでは最初は標準のライフサイクルが実行されます。ただし、そのリクエスト中にデータがフェッチされるのではなく、独立した特別なPPRリクエストが実行されます。ページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみが実行され、対応するデータがフェッチおよび表示されます。ユーザーのアクションにより後続のデータ・フェッチが実行される場合(表のスクロールなど)、別のPPRリクエストが実行されます。図12-22に、2番目のPPRリクエスト中の表を含むページを示します。

図12-22 2番目のPPRリクエストでデータをフェッチする表

ユーザーがソート可能な列のヘッダーをクリックすると、tableコンポーネントによりSortEventイベントが生成されます。このイベントにはgetSortCriteriaプロパティがあり、これを使用して、ソートの強さとともに表のソートに使用する必要のある基準が返されます。表は、基礎となるCollectionModelインスタンスにsetSortCriteria()メソッドをコールしてこのイベントに対応し、登録済の任意のSortListenerインスタンスをコールします。

12.3.7 プログラムを使用した表の列のソートの有効化に関する必知事項

表の列のソートを有効にできるのは、基礎となるモデルでソートがサポートされている場合のみです。モデルがCollectionModelインスタンスの場合は、次のメソッドを実装する必要があります。

- public boolean isSortable(String propertyName)

- public List getSortCriteria()

- public void setSortCriteria(List criteria)

2番目と3番目のメソッドの基準はリストであり、このリストの各項目はorg.apache.myfaces.trinidad.model.SortCriterion (ソートの強さをサポートしています)のインスタンスです。

詳細は、MyFaces TrinidadのWebサイト(http://myfaces.apache.org/trinidad/index.html)を参照してください。

モデルがCollectionModelインスタンスではない場合、モデルは表コンポーネントによりラップされ、org.apache.myfaces.trinidad.model.SortableModelインスタンスになります。SortableModelは、CollectionModelを拡張する、すべてのソート機能を実装した具体クラスです。

注意:

自動サポートは、1つの列のみソートします。複数列のソートはサポートされていません。

12.3.8 表の選択された行でのアクションの実行に関する必知事項

コレクションベースのコンポーネントでは、ユーザーが1つ以上の行を選択し、その行に対してなんらかのアクションを実行できます(carouselコンポーネントでは複数選択はサポートされません)。

コンポーネントの選択状態が変更されると、選択イベントが起動されます。selectionEventイベントは、選択解除された行と選択された行をレポートします。

コンポーネントの選択イベントをリスニングするには、selectionListener属性を使用するか、addselectionListener()メソッドで表にリスナーを追加して、コンポーネントにリスナーを登録します。これにより、リスナーは選択された行にアクセスし、それらの行に対してアクションを実行できます。

RowKeySetオブジェクトは、現在の選択内容、つまり選択されている1つ以上の行であり、コンポーネントのgetSelectedRowKeys()メソッドをコールすることで取得できます。プログラムを使用して選択内容を変更するには、次のいずれかを実行します。

- RowKeySetオブジェクトでrowKeyオブジェクトを追加するか、rowKeyオブジェクトを削除します。

- コンポーネントに対してsetRowIndex()またはsetRowKey()メソッドをコールして、特定の行を現在行にします。その後、RowKeySetオブジェクトに対してadd()またはremove()メソッドをコールして、その行を選択内容に追加するか、選択内容から削除できます。

例12-5に、ユーザーが行を選択してから「削除」ボタンをクリックしてこれらの行を削除できる表の部分を示します。アクション・リスナーは、mybeanマネージドBeanのperformDeleteメソッドにバインドされています。

例12-5 行の選択

<af:table binding="#{mybean.table}" rowselection="multiple" ...>
...
</af:table>
<af:button text="Delete" actionListener="#{mybean.performDelete}"/>

例12-6に、選択されたすべての行を反復し、それぞれにmarkForDeletionメソッドをコールするアクション・メソッドperformDeleteを示します。

例12-6 rowKeyオブジェクトの使用

public void performDelete(ActionEvent action)
{
UIXTable table = getTable();
Iterator selection = table.getSelectedRowKeys().iterator();
Object oldKey = table.getRowKey();
try
{
while(selection.hasNext())
{
Object rowKey = selection.next();
table.setRowKey(rowKey);
MyRowImpl row = (MyRowImpl) table.getRowData();
//custom method exposed on an implementation of Row interface.
row.markForDeletion();
}
}
finally
{
// restore the old key:
table.setRowKey(oldKey);
}
}

12.3.9 表の選択コンポーネント値の動的な決定に関する必知事項

表にselectOneコンポーネントを使用する場合がありますが、各行でコンポーネントに異なる選択内容が表示される必要があります。そのため、実行時に項目のリストを動的に決定する必要があります。

個々の項目にスタンプを設定するにはforEachコンポーネントを使用する必要があると考える可能性がありますが、forEachはCollectionModelインスタンスと連携しないため機能しません。また、表で使用されるようなコンポーネント管理のEL変数を使用するEL式にはバインドできません。forEachコンポーネントはJSFタグの実行ステップで関数を実行しますが、表では次に示すコンポーネントのエンコーディング・ステップで実行します。そのため、forEachコンポーネントは表の準備ができる前に実行され、反復関数は実行されません。

selectOneコンポーネントの場合、直接の子はitemsコンポーネントであることが必要です。itemsコンポーネントは行変数(<f:items value="#{row.Items}"/>など)に直接バインドできますが、こうすると、基礎となるモデルを変更できなくなります。

かわりに、例12-7に示すように、項目のリストを作成するマネージドBeanを作成します。

例12-7 項目のリストを戻すマネージドBean

public List<SelectItem> getItems()
{
// Grab the list of items
FacesContext context = FacesContext.getCurrentInstance();
Object rowItemObj =  context.getApplication().evaluateExpressionGet(
context, "#{row.items}", Object.class);
if (rowItemObj == null)
return null;
// Convert the model objects into items
List<SomeModelObject> list =  (List<SomeModelObject>) rowItemObj;
List<SelectItem> items = new ArrayList<SelectItem>(list.size());
for (SomeModelObject entry : list)
{
items.add(new SelectItem(entry.getValue(), entry.getLabel());public
}
// Return the items
return items;
}

例12-8に示すように、ページの1つのコンポーネントからリストにアクセスできます。

例12-8 JSFページからの項目へのアクセス

<af:table var="row">
<af:column>
<af:selectOneChoice value="#{row.myValue}">
<f:Items value="#{page_backing.Items}"/>
</af:selectOneChoice>
</af:column>
</af:table>

12.4 表への非表示機能の追加

表にdetailStampファセットを使用して、表示または非表示にできるデータを指定できます。このファセットにコンポーネントを追加すると、表に、切替えアイコンが付いた追加の列が表示されます。ユーザーがアイコンをクリックすると、ファセットに追加されたコンポーネントが表示されます。ユーザーが再度切替えアイコンをクリックすると、コンポーネントが非表示になります。図12-23に、コンテンツがdetailStampファセットに追加された際に表示される追加の列を示します。

注意:

detailStampファセットを使用する表がスクリーン・リーダー・モードでレンダリングされると、そのファセットのコンテンツがポップアップ・ウィンドウに表示されます。アクセシビリティの詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

図12-23 detailStampファセットが表示されていない表

図12-24に、1行目のdetailStampファセットが表示されている同じ表を示します。

図12-24 表示されているdetailStampファセット

ファセットのrendered属性にEL式を使用して、切替えアイコンと詳細を表示するかどうかを決定できます。たとえば、ショッピング・カート・ページでdetailStampファセットを使用して、ギフト・ラッピング情報を表示するとします。ただし、すべての注文アイテムにギフト・ラッピング情報があるわけではないため、注文アイテムに表示する情報がある場合にのみ切替えアイコンを表示します。表示する情報があるかどうかを決定するメソッドをマネージドBeanに作成し、rendered属性をそのメソッドにバインドできます。図12-25に、表示する情報がある行に対してのみアイコンが表示されている同じ表を示します。

図12-25 条件付きdetailStampファセット

注意:

列を固定できるように表を設定している場合、detailStampファセットを表示すると固定機能が働かなくなります。つまり、詳細が表示されている間、ユーザーは列を固定できません。

12.4.1 detailStampファセットの使用方法

detailStampファセットを使用するには、表示または非表示にするデータにバインドされているコンポーネントをファセットに挿入します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.4項「表への非表示機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

detailStampファセットを使用する手順:

1. ファセットに表示するコンポーネントを、「コンポーネント」ウィンドウから「構造」ウィンドウのdetailStampファセットにドラッグします(図12-26を参照)。

図12-26 構造ウィンドウのdetailStampファセット

注意:

JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

ヒント:

ファセットが「構造」ウィンドウに表示されていない場合は、表を右クリックして「ファセット - 表」→詳細スタンプを選択します。

2. 表示する属性が現在のレコードに固有の場合は、現在のレコードのデータの表示に表の変数が使用されるように、(単純にコンポーネントが属性にバインドされる)JSFコードを置き換えます。
例12-9の省略形のコードは、図12-24に示したdetailStampファセットの表示に使用されているものです。この図では、選択された行の詳細が表示されています。

例12-9 detailStampファセットのコード

<af:table rowSelection="multiple" var="test1"
value="#{tableTestData}"
<f:facet name="detailStamp">
<af:panelFormLayout rows="4" labelWidth="33%" fieldWidth="67%"
inlineStyle="width:400px">
<af:inputText label="Name" value="#{test1.name}"/>
<af:group>
<af:inputText label="Size" value="#{test1.size}"/>
<af:inputText label="Date Modified" value="#{test1.inputDate}"/>
<af:inputText label="Created by"/>
</af:group>
</af:panelFormLayout>
</f:facet>
</af:table>

3. detailStampファセットにそのアイコンとコンポーネントを条件付きで表示する場合は、ファセットのrendered属性を、ファセットをレンダリングする必要があるかどうかを決定するマネージドBeanのメソッドに設定します。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合、データ・コントロールから属性をドラッグし、detailStampファセットにドロップできます。コードを変更する必要はありません。

12.4.2 実行時に行われる処理: rowDisclosureEvent

ユーザーが行の詳細を表示または非表示にすると、表によりrowDisclosureEventイベントが生成されます。このイベントは、詳細を切り替える(開くまたは閉じる)ように表に指示します。

rowDisclosureEventイベントには関連付けられたリスナーがあります。表のrowDisclosureListener属性は、マネージドBeanのメソッドにバインドできます。このメソッドは、必要な後処理を実行するためのrowDisclosureEventイベントへのレスポンスとして起動されます。

12.5 表でのフィルタ処理の有効化

値がフィルタに一致する行のみを表に表示するために使用できるフィルタを表に追加できます。有効化されて、表示に設定されている場合、検索可能な各列の上に検索条件入力フィールドが表示されます。

たとえば、図12-27の表は、Locationの値が1700である行のみを表示するようにフィルタ処理されています。

図12-27 フィルタ処理された表

フィルタ処理された表の検索は例による問合せに基づいており、QBEテキストまたは日付入力フィールド書式を使用します。検索基準を変更するための>や<などの演算子の文字を入力できるようにするため、入力バリデータは無効になっています。たとえば、数値列の検索条件として>1500を入力できます。ワイルドカード文字もサポートされています。検索は、大文字と小文字を区別する、または大文字と小文字を区別しないようにできます。列でQBEがサポートされていない場合、検索条件入力フィールドはその列にレンダリングされません。

フィルタ処理機能では、データを表にフィルタ処理するためのモデルが使用されます。表のfilterModel属性オブジェクトは、FilterableQueryDescriptorクラスのインスタンスにバインドする必要があります。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表を作成すると、フィルタ処理が作成されます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「ADFによるデータバインドされた表の作成」の章を参照してください。

例12-10では、フィルタ入力フィールドを有効にするために表のfilterVisible属性がtrueに設定されていて、filterModelインスタンスの列を識別するために列にsortProperty属性が設定されています。各列要素では、filterable属性がtrueに設定されています。

例12-10 フィルタ処理が有効にされている表コンポーネント

<af:table value="#{myBean.products}" var="row"
queryListener="#{tableFilter.processTableFilter}"
filterModel="#{tableFilter.queryDescriptor}"
...
filterVisible="true"
...
rowselection="single">
...
<af:column sortProperty="ProductID" filterable="true" sortable="true"
<af:outputText value="#{row.ProductID}">
...
</af:column>
<af:column sortProperty="Name" filterable="true" sortable="true"
<af:outputText value="#{row.Name}"/>
...
</af:column>
<af:column sortProperty="warehouse" filterable="true" sortable="true"
<af:outputText value="#{row.warehouse}"/>
...
</af:column>
</af:table>

12.5.1 表へのフィルタ処理機能の追加方法

表にフィルタ処理機能を追加するには、まずフィルタ処理機能を提供するクラスを作成します。次に表をそのクラスにバインドし、フィルタ処理機能を使用するよう表と列を構成します。フィルタ処理機能を使用する列では、headerText属性に値が設定されているか、headerファセットにコンポーネントが含まれている必要があります。これにより、フィルタ・コンポーネントが表示されます。また、filterModelクラスではsortProperty属性が使用されるため、列もソート可能に構成されている必要があります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.5項「表でのフィルタ処理の有効化」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

表にフィルタ処理機能を追加する手順:

1. FilterableQueryDescriptorクラスのサブクラスであるJavaクラスを作成します。ConjunctionCriterionオブジェクトを返すように実装する必要があります。このクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

2. 12.3項「表へのデータの表示」で説明されているように、表を作成します。

3. 「構造」ウィンドウで表を選択し、次の属性を「プロパティ」ウィンドウで設定します。

- FilterVisible: 検索可能な列の上にフィルタ条件入力フィールドを表示する場合はtrueに設定します。

- FilterModel: 手順1で作成したFilterableQueryDescriptorクラスのインスタンスにバインドします。

- QueryListener: 表フィルタを処理するリスナー・メソッドにバインドします。

ヒント:

フィルタにinputTextコンポーネント以外のコンポーネント(inputDateコンポーネントなど)を使用する場合は、filterVisibleをtrueに設定するかわりに、filterファセットに必要なコンポーネントを追加できます。これを行うには:

1. 「構造」ウィンドウで、フィルタ処理する列を右クリックし、「af:columnの中に挿入」→「JSF Core」→フィルタ・ファセットを選択します。

2. 「コンポーネント」ウィンドウから、コンポーネントをファセットにドラッグ・アンド・ドロップします。

3. コンポーネントの値を、手順1で作成したFilterableQueryDescriptorクラスのgetFilterConjunctionCriterionメソッドから返されたConjunctionCriterionオブジェクトとなるように設定します。値では、次の例のように、行に使用される変数を考慮する必要があります。

#{af:inputDate label="Select Date" id="name"
value="row.queryDescriptor.
filterConjunctionCriterion.criterionMap.
Hiredate.value"}

4. 「構造」ウィンドウで表の列を選択し、「プロパティ」ウィンドウで表の各列に対して次の設定を行います。

- Filterable: trueに設定します。

- FilterFeatures: caseSensitiveまたはcaseInsensitiveに設定します。指定されない場合、大文字と小文字の区別はモデルによって決定されます。

12.6 ツリーへのデータの表示

ADF Facesツリー・コンポーネントには、組織図や階層ディレクトリ構造などの階層データが表示されます。これらのタイプのデータには一連の最上位レベル・ノードがある場合があり、構造内の各要素は他の要素を含むように拡張できます。たとえば、組織図では、階層の任意の数の従業員が任意の数の直属の部下を持つことができます。ツリー・コンポーネントを使用すると、従業員の直属の部下が子ノードとして表示される階層を表示できます。

ツリー・コンポーネントでは、複数のルート要素がサポートされます。データは構造を表す形式で表示され、各要素が適切なレベルにインデントされて階層内での適切なレベルを示し、その親に接続されます。ユーザーは、階層の一部を展開および縮小できます。図12-28に、File Explorerアプリケーションのディレクトリの表示に使用されたツリーを示します。

図12-28 File Explorerアプリケーションのツリー・コンポーネント

ADF Facesのツリー・コンポーネントでは、基礎となる階層のデータにアクセスするためのモデルを使用します。特定のモデル・クラスはoracle.adf.view.rich.model.TreeModelで、12.3項「表へのデータの表示」で説明されているように、CollectionModelを拡張します。

ツリーをサポートする独自のツリー・モデルを作成する必要があります。ツリー・モデルは行のコレクションです。現在行に子の行が含まれている場合にtrueを返すisContainer()メソッドがあります。現在行の子にアクセスするには、enterContainer()メソッドをコールします。このメソッドをコールすると、TreeModelインスタンスが子の行のコレクションに変わります。親のコレクションに戻すには、exitContainer()メソッドをコールします。

例12-11に示すように、TreeModelクラスの作成時には、org.apache.myfaces.trinidad.model.ChildPropertyTreeModelクラスが便利です。

例12-11 TreeModelの作成

List<TreeNode> root = new ArrayList<TreeNode>();
for(int i = 0; i < firstLevelSize; i++)
{
List<TreeNode> level1 = new ArrayList<TreeNode>();
for(int j = 0; j < i; j++)
{
List<TreeNode> level2 = new ArrayList<TreeNode>();
for(int k=0; k<j; k++)
{
TreeNode z = new TreeNode(null, _nodeVal(i,j,k));
level2.add(z);
}
TreeNode c = new TreeNode(level2, _nodeVal(i,j));
level1.add(c);
}
TreeNode n = new TreeNode(level1, _nodeVal(i));
root.add(n);
}
ChildPropertyTreeModel model = new ChildPropertyTreeModel(root, "children");
private String _nodeVal(Integer... args)
{
StringBuilder s = new StringBuilder();
for(Integer i : args)
s.append(i);
return s.toString();
}

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用してツリーを作成すると、モデルが作成されます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「マスター/ディテール・データの表示」の章を参照してください。

ツリーは、表の操作と同じような方法で操作できます。次の操作を実行できます。

- ノードを現在のノードにするには、リストへの適切な索引を使用してツリーでsetRowIndex()メソッドをコールします。または、適切なrowKeyオブジェクトを使用してsetRowKey()メソッドをコールします。

- 特定のノードにアクセスするには、まずそのノードを現在のノードにしてから、ツリーでgetRowData()メソッドをコールします。

- 展開または縮小されているノードの行にアクセスするには、RowDisclosureEventでgetAddedSetメソッドおよびgetRemovedSetメソッドをコールします。詳細は、12.6.4項「プログラムを使用したノードの開閉に関する必知事項」を参照してください。

- ノードの子コレクションを操作するには、setRowIndex()およびsetRowKey()メソッドをコールする前にenterContainer()メソッドをコールします。その後、exitContainer()メソッドをコールして親ノードに戻します。

- ツリー(任意のレベル)内のノードのrowKeyを指すには、focusRowKey属性を使用します。focusRowKey属性が設定されるのは、ユーザーがノードを右クリックして「先頭として表示」(またはpanelCollectionコンポーネントの「先頭として表示」ツールバー・ボタン)を選択したときです。
focusRowKey属性が設定されていると、focusRowKeyで指定されたノードがツリーのルート・ノードとしてツリーにレンダリングされ、ルート・ノードの横に「階層セレクタ」アイコンが表示されます。「階層セレクタ」アイコンをクリックすると、ツリーのルート・ノードからfocusRowKeyオブジェクトへのパスを示す「階層セレクタ」ダイアログが表示されます。この表示の方法は、pathStampファセットに配置されているコンポーネントによって決まります。

注意:

JavaScriptを使用して、ツリーを動的にサイズ変更することはできません。ツリーの高さは初めてレンダリングされるときに設定され、JavaScript APIを使用して変更することはできません。

表と同様、ツリーでも、個々のノードのコンテンツを表示するためにスタンプ設定機能が使用されます。ツリーには、各ノードのデータの表示に使用されるコンポーネントのホルダーであるnodeStampファセットが含まれます。各ノードが一度ずつ、すべてのノードで繰り返しレンダリング(スタンプ設定)されます。各ノードにスタンプが設定されると、現在のノードのデータが、EL式を使用して特定可能なプロパティにコピーされます。このプロパティに使用する名前を、ツリーのvarプロパティを使用して指定します。ツリーのレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

このスタンプ設定動作のため、ADF Facesツリーで子としてサポートされるのは、特定タイプのコンポーネントのみです。動作が設定されていないすべてのコンポーネントは、大部分がValueHolderまたはActionSourceインタフェースを実装するコンポーネントとしてサポートされています。

例12-12では、ツリーに表示されるデータを識別する変数nodeを使用して各要素のデータを参照しています。nodeStampファセットは、node変数からさらにプロパティを取得して、各要素のデータを表示します。

例12-12 ツリーへのデータの表示

<af:tree var="node">
<f:facet name="nodeStamp">
<af:outputText value="#{node.firstname}"/>
</f:facet>
</af:tree>

ツリーにもpathStampファセットが含まれます。このファセットは、nodeStampファセットがツリーのコンテンツのレンダリング方法を決定するのと同じように、「階層セレクタ」ダイアログのコンテンツのレンダリング方法を決定します。「階層セレクタ」ポップアップではユーザー入力が許可されないため、pathStampファセットの内部のコンポーネントは、単純なoutputText、imageおよびoutputFormattedタグの組合せにすることができ、入力コンポーネント(EditableValueHolderコンポーネント)にすることはできません。このファセットが提供されていない場合、「階層セレクタ」アイコンはレンダリングされません。

たとえば、pathStampファセットにイメージおよびoutputTextコンポーネントを含めると、ツリーにより、「階層セレクタ」ダイアログの各ノード・レベルにイメージとoutputTextコンポーネントがレンダリングされます。値へのアクセスには同じEL式を使用します。たとえば、outputTextコンポーネントのパスの各ノードに名前を表示する場合、EL式は<af:outputText value="#{node.firstname}"/>になります。

ヒント:

panelCollectionコンポーネントにより作成されたデフォルトのツールバー・ボタンの動作方法の決定には、pathStampファセットも使用されます。ボタンを使用する場合は、ノード値にバインドされたコンポーネントを追加します。panelCollectionコンポーネントの使用方法の詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

12.6.1 ツリーへのデータの表示方法

ツリーを作成するには、ページにツリー・コンポーネントを追加し、表示および動作プロパティを構成します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.6項「ツリーへのデータの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

ページにツリーを追加する手順:

1. 例12-11に示すように、org.apache.myfaces.trinidad.model.TreeModelクラスを拡張するJavaクラスを作成します。

2. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「ツリー」をドラッグ・アンド・ドロップして「ツリーの挿入」ダイアログを開きます。

3. 必要に応じてツリーを構成します。ダイアログのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

4. 「プロパティ」ウィンドウの「データ」セクションを開いて、次の属性を設定します。

- Value: ツリーをバインドするオブジェクトのEL式を指定します。手順1で作成したように、org.apache.myfaces.trinidad.model.TreeModelのインスタンスであることが必要です。

- Var: 各ノードを表す変数名を指定します。

- VarStatus: オプションで、コンポーネントの状態の判断に使用可能な変数を入力します。レンダー・レスポンス・フェーズ中に、ツリーによりモデル行が反復され、各ノードがレンダリングされます。指定された任意のノードに対して、varStatus属性で次の情報を指定します。

- model: CollectionModelインスタンスへの参照

- index: 現在行の索引

- rowKey: 現在のノードの一意キー

5. 「外観」セクションを開き、次の属性を設定します。

- DisplayRow: 最初に表示される際にツリーに表示するノードを指定します。使用可能な値は、最初のノードを表示する場合はfirst、最後のノードを表示する場合はlast、ツリーの最初に選択されたノードを表示する場合はselectedです。デフォルトは、firstです。

- DisplayRowKey: 最初に表示される際にツリーに表示する行キーを指定します。この属性はプログラムのみを使用して設定する必要があります。この属性を指定すると、displayRow属性がオーバーライドされます。

- Summary: オプションで、ツリーによって表示されるデータのサマリーを入力します。

6. 「動作」セクションを開き、次の属性を設定します。

- InitiallyExpanded: コンポーネントが初めてレンダリングされる際に、すべてのノードを開いておく場合はtrueに設定します。

- EditingMode: ツリーへのデータの表示に使用された編集可能なコンポーネントで、すべてのノードを編集可能にするか(editAll)、ユーザーがノードをクリックした場合に編集可能にするか(clickToEdit)を指定します。詳細は、12.2.4項「表、ツリーおよびツリー表のデータの編集」を参照してください。

- ContextMenuSelect: 右クリックしてポップアップ・メニューを開く際に、ノードを選択するかどうかを決定します。trueに設定すると、ノードが選択されます。ポップアップ・メニューの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- RowSelection: ノードを選択可能にする場合に値を設定します。有効な値はnone、singleまたはmultipleです。選択されたノードでプログラムを使用してアクションを実行する方法の詳細は、12.6.5項「プログラムを使用したノードの選択に関する必知事項」を参照してください。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、コンポーネントのレンダリングと同時にデータがフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中にデータがフェッチされてクライアントに送信されます。属性がwhenAvailable(デフォルト)に設定されている場合、レンダラはデータが使用可能かどうかをチェックします。使用可能な場合、コンテンツは即時に配信されます。使用可能でない場合は、遅延配信が使用されます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- FetchSize: データ・フェッチ・ブロックの行数を指定します。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- AutoHeightRows: スクロール・バーを表示する前に表示するノードの最大数に設定します。デフォルト値は-1です(いくつであっても自動サイズ設定は行われません)。値を0に設定して、fetchSizeと同じ値にすることができます。

注意:

autoHeightRows属性の設定について、次の点に注意してください。

- inlineStyle属性に高さを指定しても効果はなく、AutoHeightRowsの値でオーバーライドされます。

- inlineStyle属性にmin-heightまたはmax-heightを指定すると、autoHeightRows属性との間に矛盾が生じるため、このような指定はしないでください。

- コンポーネントをpanelSplitterのようなレイアウト管理コンテナに配置すると、このコンテナによりコンポーネントのサイズが指定されます(自動のサイズ指定は発生しません)。詳細は、12.2.7項「表、ツリーおよびツリー表コンポーネントのジオメトリ管理」を参照してください。

- SelectionListener: オプションで、選択イベントを処理するリスナーにEL式を入力します。詳細は、12.6.5項「プログラムを使用したノードの選択に関する必知事項」を参照してください。

- FocusListener: オプションで、フォーカス・イベントを処理するリスナーにEL式を入力します。

- RowDisclosureListener: オプションで、ノードの表示イベントを処理するリスナー・メソッドにEL式を入力します。

7. 「拡張」セクションを開き、次の属性を設定します。

- FocusRowKey: オプションで、最初にフォーカスされるノードを入力します。

- DisclosedRowKeys: オプションで、ノードの表示を処理するバッキングBeanのメソッドにEL式を入力します。詳細は、12.6.4項「プログラムを使用したノードの開閉に関する必知事項」を参照してください。

- SelectedRowKeys: オプションで、最初に選択されるノードのキーを入力します。詳細は、12.6.5項「プログラムを使用したノードの選択に関する必知事項」を参照してください。

8. データをツリーに表示するためのコンポーネントを追加するには、目的のコンポーネントを「コンポーネント」ウィンドウからnodeStampファセットにドラッグします。図12-29に、File Explorerアプリケーションのディレクトリの表示に使用されたツリーのnodeStampファセットを示します。

図12-29 構造ウィンドウのnodeStampファセット

コンポーネントの値は、ツリーのvar属性および表示する属性の変数値セットにバインドする必要があります。たとえば、File Explorerアプリケーションのツリーでは、var属性の値としてfolderが使用されており、各ノードのディレクトリ名が表示されています。そのため、ディレクトリ名の表示に使用される出力コンポーネントの値は、#{folder.name}です。

ヒント:

JSPまたはJSPXページ上のファセットに配置できる子コンポーネントは1つのみです。そのため、1つのノードにつき複数のコンポーネントを使用する場合は、そのコンポーネントを、図12-29に示すように、ファセットの直接の子にできるグループ・コンポーネント内に配置します。

12.6.2 ページにツリーを追加する場合の処理

ページにツリーを追加すると、JDeveloperによりnodeStampファセットが追加され、ツリーのノードにスタンプが設定されます。例12-13に、File Explorerアプリケーション内のディレクトリ構造を表示するツリーの省略形のコードを示します。

例12-13 JSFページ内のADF Facesツリーのコード

<af:tree id="folderTree"
var="folder"
binding="#{explorer.navigatorManager.foldersNavigator
.foldersTreeComponent}"
value="#{explorer.navigatorManager.foldersNavigator.
foldersTreeModel}"
disclosedRowKeys="#{explorer.navigatorManager.foldersNavigator.
foldersTreeDisclosedRowKeys}"
rowSelection="single"
contextMenuId=":context2"
selectionListener="#{explorer.navigatorManager.foldersNavigator.
showSelectedFolderContent}">
<f:facet name="nodeStamp">
<af:panelGroupLayout>
<af:image id="folderNodeStampImg" source="#{folder.icon}"
inlineStyle="vertical-align:middle; margin-right:3px;
shortDesc="folder icon"/>
<af:outputText id="folderNodeStampText" value="#{folder.name}"/>
</af:panelGroupLayout>
</f:facet>
</af:tree>

12.6.3 実行時に行われる処理: ツリー・コンポーネント・イベント

ツリーは、階層でのレベルを示すためにノードがインデントされている形式で表示されます。ユーザーはクリックしてノードを開き、子ノードを表示できます。ユーザーは開いた状態のノードをクリックして閉じることもできます。ユーザーがこれらのアイコンのいずれかをクリックすると、コンポーネントによりRowDisclosureEventイベントが生成されます。このイベントに対応する処理を実行するには、カスタムのrowDisclosureListenerメソッドを登録します。詳細は、12.6.4項「プログラムを使用したノードの開閉に関する必知事項」を参照してください。

ユーザーがノードを選択または選択解除すると、ツリー・コンポーネントによりselectionEventイベントが起動されます。選択されたノードに基づいてツリー・コンポーネントで後処理を実行する、カスタムのselectionListenerインスタンスを登録できます。詳細は、12.6.5項「プログラムを使用したノードの選択に関する必知事項」を参照してください。

12.6.4 プログラムを使用したノードの開閉に関する必知事項

RowDisclosureEventイベントには、閉じた状態のすべてのノード用のRemovedSetオブジェクトと、開いた状態のすべてのノード用のAddedSetオブジェクトの2つのRowKeySetオブジェクトがあります。コンポーネントは、追加されたセットの全ノードの下位のサブツリーを開き、削除されたセットの全ノードの下位のサブツリーを閉じます。

例12-14に示すように、カスタムのrowDisclosureListenerメソッドは、ツリー・コンポーネントで後処理を実行できます。

例12-14 rowDisclosureListenerを含むツリー表コンポーネント

<af:treeTable id="folderTree" var="directory" value="#{fs.treeModel}"
binding="#{editor.component}" rowselection="multiple"
columnselection="multiple" focusRowKey="#{fs.defaultFocusRowKey}"
selectionListener="#{fs.Table}"
contextMenuId="treeTableMenu"
rowDisclosureListener="#{fs.handleRowDisclosure}">

例12-15に、行公開イベントを処理するバッキングBeanメソッドを示します。例は、ツリー・ノードの展開を示しています。ツリー・ノードを縮小する場合は、getRemovedSetを使用します。

例12-15 rowDisclosureEvent用バッキングBeanメソッド

public void handleRowDisclosure(RowDisclosureEvent rowDisclosureEvent)
throws Exception {
Object rowKey = null;
Object rowData = null;
RichTree tree = (RichTree) rowDisclosureEvent.getSource();
RowKeySet rks = rowDisclosureEvent.getAddedSet();

if (rks != null) {
int setSize = rks.size();
if (setSize > 1) {
throw new Exception("Unexpected multiple row disclosure
added row sets found.");
}

if (setSize == 0) {
// nothing in getAddedSet indicates this is a node
// contraction, not expansion. If interested only in handling
// node expansion at this point, return.
return;
}

rowKey = rks.iterator().next();
tree.setRowKey(rowKey);
rowData = tree.getRowData();

// Do whatever is necessary for accessing tree node from
// rowData, by casting it to an appropriate data structure
// for example, a Java map or Java bean, and so forth.
}
}

ツリーおよびツリー表では、oracle.adf.view.rich.model.RowKeySetクラスのインスタンスを使用して、どのノードが開かれているかを追跡します。このインスタンスは、コンポーネントのdisclosedRowKeys属性として格納されます。例12-16に示すように、このインスタンスを使用して、階層内のノードの開いた状態または閉じた状態をプログラムで制御できます。RowKeySetインスタンスに含まれるノードは開かれ、その他すべてのノードは閉じられます。addAll()メソッドによりすべての要素がセットに追加され、removeAll()メソッドによりすべてのノードがセットから削除されます。

例12-16 disclosedRowKeys属性を含むツリー・コンポーネント

<af:tree var="node"
inlineStyle="width:90%; height:300px"
id="displayRowTable"
varStatus="vs"
rowselection="single"
disclosedRowKeys="#{treeTableTestData.disclosedRowKeys}"
value="#{treeTableTestData.treeModel}">

例12-17に、公開された行キーを処理するバッキングBeanメソッドを示します。

例12-17 行キーを処理するためのバッキングBeanメソッド

public RowKeySet getDisclosedRowKeys()
{
if (disclosedRowKeys == null)
{
// Create the PathSet that we will use to store the initial
// expansion state for the tree
RowKeySet treeState = new RowKeySetTreeImpl();
// RowKeySet requires access to the TreeModel for currency.
TreeModel model = getTreeModel();
treeState.setCollectionModel(model);
// Make the model point at the root node
int oldIndex = model.getRowIndex();
model.setRowKey(null);
for(int i = 1; i<=19; ++i)
{
model.setRowIndex(i);
treeState.setContained(true);
}
model.setRowIndex(oldIndex);
disclosedRowKeys = treeState;
}
return disclosedRowKeys;
}

12.6.5 プログラムを使用したノードの選択に関する必知事項

ツリーおよびツリー表コンポーネントを使用すると、単一のノードのみまたは複数のノードを選択できるようになります。コンポーネントで複数の選択が許可されている場合、ユーザーは[Ctrl]を押しながらクリックする操作、および[Shift]を押しながらクリックする操作で複数のノードを選択できます。

ユーザーがノードを選択または選択解除すると、ツリー・コンポーネントによりselectionEventイベントが起動されます。このイベントには、選択解除されたすべてのノード用のRemovedSetオブジェクトと、選択されたすべてのノード用のAddedSetの2つのRowKeySetオブジェクトがあります。

ツリーおよびツリー表コンポーネントは、クラスoracle.adf.view.rich.model.RowKeySetのインスタンスを使用して選択されたノードを追跡します。このインスタンスは、コンポーネントのselectedRowKeys属性として格納されます。このインスタンスを使用して、階層内のノードの選択状態をプログラムで制御できます。RowKeySetインスタンスに含まれるノードは選択されているとみなされ、その他すべてのノードは選択解除されているとみなされます。addAll()メソッドによりすべてのノードがセットに追加され、removeAll()メソッドによりすべてのノードがセットから削除されます。ツリーおよびツリー表ノードの選択は、表の行の選択と同じように機能します。表の行選択のサンプル・コードは、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

12.7 ツリー表へのデータの表示

ADF Facesのツリー表コンポーネントでは、表形式で階層データが表示されます。ツリー表コンポーネントでは、階層の各ツリー・ノードのデータの列を表示できるため、ツリー表コンポーネントの表示はツリー・コンポーネントの表示より複雑です。コンポーネントには、階層のノードの開閉だけでなく、メイン・ツリー内のサブツリーにフォーカスするメカニズムもあります。図12-30に、File Explorerアプリケーションで使用されるツリー表を示します。ツリー・コンポーネント同様、ツリー表でも、コレクションのファイル間の階層関係を表示できます。また、表コンポーネントと同じように、各ファイルの属性値も表示できます。

図12-30 File Explorerアプリケーションのツリー表

ツリー表コンポーネントの直下の子は、表コンポーネントと同じように、列コンポーネントであることが必要です。表とは異なり、ツリー表コンポーネントには、階層のノードの1次識別子を含む列が配置されるnodeStampファセットがあります。treeTableコンポーネントでは、Treeコンポーネントと同じスタンプ設定動作がサポートされています(詳細は、12.6項「ツリーへのデータの表示」を参照してください)。

注意:

nodeStampファセットは、1列のみ含むことができます(これがツリーのノードになります)。

たとえば、(図12-30に示す)File Explorerアプリケーションの1次識別子はファイル名です。これは、nodeStampファセットに含まれる列です。タイプや「サイズ」などのその他の列は、1次識別子の属性値を表示し、ツリー表コンポーネントの直接の子です。このツリー表では、nodeStampファセット列の各ノードのデータ、および子の列の各コンポーネントのデータにスタンプを設定するために使用される変数の値としてnodeが使用されています。例12-18に、File Explorerアプリケーション内のツリー表の省略形のコードを示します。

例12-18 treeTableの行へのスタンプ設定

<af:treeTable id="folderTreeTable" var="file"
value="#{explorer.contentViewManager.treeTableContentView.
contentModel}"
binding="#{explorer.contentViewManager.treeTableContentView.
contentTreeTable}"
emptyText="#{explorerBundle['global.no_row']}"
columnStretching="last"
rowSelection="single"
selectionListener="#{explorer.contentViewManager.
treeTableContentView.treeTableSelectFileItem}"
summary="treeTable data">
<f:facet name="nodeStamp">
<af:column headerText="#{explorerBundle['contents.name']}"
width="200" sortable="true" sortProperty="name">
<af:panelGroupLayout>
<af:image source="#{file.icon}"
shortDesc="#{file.name}"
inlineStyle="margin-right:3px; vertical-align:middle;"/>
<af:outputText id="nameStamp" value="#{file.name}"/>
</af:panelGroupLayout>
</af:column>
</f:facet>
<f:facet name="pathStamp">
<af:panelGroupLayout>
<af:image source="#{file.icon}"
shortDesc="#{file.name}"
inlineStyle="margin-right:3px; vertical-align:middle;"/>
<af:outputText value="#{file.name}"/>
</af:panelGroupLayout>
</f:facet>
<af:column headerText="#{explorerBundle['contents.type']}">
<af:outputText id="typeStamp" value="#{file.type}"/>
</af:column>
<af:column headerText="#{explorerBundle['contents.size']}">
<af:outputText id="sizeStamp" value="#{file.property.size}"/>
</af:column>
<af:column headerText="#{explorerBundle['contents.lastmodified']}"
width="140">
<af:outputText id="modifiedStamp"
value="#{file.property.lastModified}"/>
</af:column>
</af:treeTable>

ツリー表コンポーネントでは、表とツリーの両方と同じ多くの属性がサポートされています。これらの属性の詳細は、12.3項「表へのデータの表示」および12.6項「ツリーへのデータの表示」を参照してください。

12.7.1 ツリー表へのデータの表示方法

ツリー表を作成するには、「ツリー表の挿入」ウィザードを使用します。ウィザードが完了したら、「プロパティ」ウィンドウを使用してツリー表の追加プロパティを構成できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.7項「ツリー表へのデータの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

ページにツリー表を追加する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「ツリー表」をページにドラッグ・アンド・ドロップして、「ツリー表の挿入」ウィザードを開きます。

2. ウィザードを完了することで表を構成します。ウィザードのヘルプを参照するには、「ヘルプ」をクリックするか[F1]を押します。

3. 「プロパティ」ウィンドウを使用して、その他の属性を必要に応じて構成します。

ヒント:

ツリー表の属性は、表およびツリー・コンポーネントの属性と同じです。属性の構成の詳細は、12.3.4項「ページへの表の表示方法」および12.6.1項「ツリーへのデータの表示方法」を参照してください。

12.8 行を値として渡す

コレクションから行全体を値として渡すことが必要な場合があります。そのためには、表で行を表すために使用される変数、またはツリーでノードを表すために使用される変数を、pageFlowスコープのプロパティに値として渡します。別のページは、スコープからその値にアクセスできます。setPropertyListenerタグでこれを行うことができます(使用手順を含むsetPropertyListenerタグの詳細は、5.7項「ページ間の値の受渡し」を参照してください)。

たとえば、マスター・ページにある単一選択の表に従業員を一覧表示し、ユーザーが行の1つを選択してボタンをクリックすると、その行のデータを編集するための新しいページに移動できるようにするとします(例12-19を参照)。EL変数名empは、表の1行(従業員)を表すために使用されます。buttonコンポーネントのaction属性値は、静的な文字列結果showEmpDetailです。これで、ユーザーが従業員詳細ページに移動できるようになります。setPropertyListenerタグにはfrom値(変数emp)が使用され、toの値に格納されます。

例12-19 setPropertyListenerおよびpageFlowScopeの使用

<af:table value="#{myManagedBean.allEmployees}" var="emp"
rowSelection="single">
<af:column headerText="Name">
<af:outputText value="#{emp.name}"/>
</af:column>
<af:column headerText="Department Number">
<af:outputText value="#{emp.deptno}"/>
</af:column>
<af:column headertext="Select">
<af:button text="Show more details" action="showEmpDetail">
<af:setPropertyListener from="#{emp}"
to="#{pageFlowScope.empDetail}"
type="action"/>
</af:button>
</af:column>
</af:table>

ユーザーが特定の従業員の行のボタンをクリックすると、リスナーが実行され、表の現在行(従業員)に対応する#{emp}の値が取得されます。取得された行オブジェクトは、#{pageFlowScope.empDetail} EL式を使用してpageFlowScopeのempDetailプロパティとして格納されます。アクション・イベントの実行は静的結果になり、ユーザーは詳細ページにナビゲートされます。詳細ページでは、例12-20に示すように、outputTextコンポーネントは、pageFlowScope.empDetailオブジェクトから値を取得します。

例12-20 pageFlowScopeオブジェクトの取得

<h:panelGrid columns="2">
<af:outputText value="Firstname:"/>
<af:inputText value="#{pageFlowScope.empDetail.name}"/>
<af:outputText value="Email:"/>
<af:inputText value="#{pageFlowScope.empDetail.email}"/>
<af:outputText value="Hiredate:"/>
<af:inputText value="#{pageFlowScope.empDetail.hiredate}"/>
<af:outputText value="Salary:"/>
<af:inputText value="#{pageFlowScope.empDetail.salary}"/>
</h:panelGrid>

12.9 表メニュー、ツールバーおよびステータス・バーの表示

panelCollectionコンポーネントを使用して、表、ツリーおよびツリー表にメニュー、ツールバーおよびステータス・バーを追加できます。panelCollectionコンポーネントを使用するには、表、ツリーまたはツリー表コンポーネントをpanelCollectionコンポーネントの直接の子として追加します。panelCollectionコンポーネントには、デフォルトのメニューとツールバー・ボタンが用意されています。

図12-31に、ツリー表コンポーネントを含む、File ExplorerアプリケーションのpanelCollectionコンポーネントを示します。ツールバーには、ツリー表で実行可能なアクション(ノードの開閉など)を提供するメニュー、ユーザーがツリー表を連結解除できるボタン、およびユーザーがツリー表に表示された行を変更できるボタンが含まれます。特定のツールバー項目を表示しないようにツールバーを構成できます。たとえば、ユーザーがツリーまたは表をデタッチできるボタンをオフにすることができます。メニュー、ツールバー、ツールバー・ボタンの詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

図12-31 メニューおよびツールバーのあるツリー表のパネル・コレクション

panelCollectionコンポーネントには、メニュー・コンポーネントを保持するmenuファセット、ツールバー・コンポーネント用のtoolbarファセット、別のツールバー・コンポーネント・セット用のsecondaryToolbarファセット、およびステータス項目用のstatusbarファセットが含まれています。

デフォルトのトップレベルのメニューおよびツールバー項目は、panelCollectionコンポーネントの子として使用されているコンポーネントにより異なります。

- 表およびツリー: デフォルトのトップレベルのメニューは「表示」です。

- 選択可能な列が含まれる表およびツリー表: デフォルトのトップレベルのメニュー項目は「表示」および「書式設定」です。

- 表およびツリー表: デフォルトのツールバー・メニューは「連結解除」です。

- 選択可能な列が含まれる表およびツリー表: デフォルトのトップレベルのツールバー項目は「固定」、「連結解除」および「折返し」です。

- ツリーおよびツリー表(pathStampファセットが使用されている場合): ツールバー・ボタン「上に移動」、「先頭に移動」および「先頭として表示」も表示されます。

例12-21に、panelCollectionコンポーネントにどのようにメニューおよびツールバーが含まれるかを示します。

例12-21 表、メニューおよびツールバーを含むpanelCollectionコンポーネント

<af:panelCollection
binding="#{editor.component}">
<f:facet name="viewMenu">
<af:group>
<af:commandMenuItem text="View Item 1..."/>
<af:commandMenuItem text="View Item 2.."/>
<af:commandMenuItem text="View Item 3..." disabled="true"/>
<af:commandMenuItem text="View Item 4"/>
</af:group>
</f:facet>

<f:facet name="menus">
<af:menu text="Actions">
<af:commandMenuItem text="Add..." />
<af:commandMenuItem text="Create.." />
<af:commandMenuItem text="Update..." disabled="true"/>
<af:commandMenuItem text="Copy"/>
<af:commandMenuItem text="Delete"/>
<af:commandMenuItem text="Remove" accelerator="control A"/>
<af:commandMenuItem text="Preferences"/>
</af:menu>
</f:facet>
<f:facet name="toolbar">
<af:toolbar>
<af:button shortDesc="Create" icon="/new_ena.png">
</af:button>
<af:button shortDesc="Update" icon="/update_ena.png">
</af:button>
<af:button shortDesc="Delete" icon="/delete_ena.png">
</af:button>
</af:toolbar>
</f:facet>
<f:facet name="secondaryToolbar">
</f:facet>
<f:facet name="statusbar">
<af:toolbar>
<af:outputText id="statusText" ... value="Custom Statusbar Message"/>
</af:toolbar>
</f:facet>
<af:table rowselection="multiple" columnselection="multiple"
...
<af:column
...
</af:column>

ヒント:

panelCollectionコンポーネント内で、メニューを連結解除可能にできます。詳細は、16.2項「メニュー・バーでのメニューの使用方法」を参照してください。ユーザーに次のいずれかを期待する場合は、連結解除可能メニューの使用を検討してください。

- ページで類似のコマンドを繰り返し実行する場合。

- 大規模な表、ツリー表またはツリーにおいて、異なる行のデータで類似のコマンドを実行する場合。

- 長くて幅の広い表やツリー表、およびツリーでデータを表示する場合。ユーザーは一度クリックすることで、表示または非表示にする列やブランチを選択できます。

- 長くて幅の広い表、ツリー表またはツリーでデータを書式設定する場合。

12.9.1 表、ツリーまたはツリー表を含むpanelCollectionの追加方法

panelCollectionコンポーネントを追加してから、panelCollectionコンポーネントに表、ツリーまたはツリー表を追加します。その後、メニューおよびツールバーを追加および変更できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

集約表示のコンポーネントを含むpanelCollectionコンポーネントを作成する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルから、「パネル・コレクション」をページにドラッグ・アンド・ドロップします。表、ツリーまたはツリー表をそのコンポーネントの子として追加します。
または、ページに表、ツリーまたはツリー表がすでに存在している場合は、コンポーネントを右クリックして「囲む」を選択します。次に「パネル・コレクション」を選択して、panelCollectionコンポーネントでコンポーネントを囲みます。

2. オプションで、特定のツールバーおよびメニュー項目をオフにして、panelCollectionツールバーをカスタマイズします。そのためには、「構造」ウィンドウでpanelCollectionコンポーネントを選択します。「プロパティ」ウィンドウで、featuresOff属性を設定します。表12-1に、有効な値とツールバーでのそれぞれの効果を示します。

表12-1 featuresOff属性の有効値

値

表示されないもの

statusBar

ステータス・バー

viewMenu

「表示」メニュー

formatMenu

「書式設定」メニュー

columnsMenuItem

「表示」メニューの「列」メニュー項目

columnsMenuItem:colId

例:
columnsMenuItem:col1, col2

「列」メニュー内の一致するIDを持つ列

たとえば、左の値はIDがcol1およびcol2の列を表示しません。

freezeMenuItem

「表示」メニューの「固定」メニュー項目

detachMenuItem

「表示」メニューの「連結解除」メニュー項目

sortMenuItem

「表示」メニューの「ソート」メニュー項目

reorderColumnsMenuItem

「表示」メニューの「列の並替え」メニュー項目

resizeColumnsMenuItem

「書式設定」メニューの「列のサイズ変更」メニュー項目

wrapMenuItem

「書式設定」メニューの「折返し」メニュー項目

showAsTopMenuItem

ツリーの「表示」メニューの「先頭として表示」メニュー項目

scrollToFirstMenuItem

ツリーの「表示」メニューの「最初にスクロール」メニュー項目

scrollToLastMenuItem

ツリーの「表示」メニューの「最後にスクロール」メニュー項目

freezeToolbarItem

「固定」ツールバー項目

detachToolbarItem

「連結解除」ツールバー項目

wrapToolbarItem

「折返し」ツールバー項目

showAsTopToolbarItem

「先頭として表示」ツールバー項目

wrap

「折返し」メニューおよびツールバー項目

freeze

「固定」メニューおよびツールバー項目

detach

「連結解除」メニューおよびツールバー項目

3. コンポーネントにカスタムのメニューおよびツールバーを追加します。

- メニュー: menuファセットにmenuコンポーネントを追加します。

- ツールバー: toolbarまたはsecondaryToolbarファセットにtoolbarコンポーネントを追加します。

- ステータス項目: statusbarファセットに項目を追加します。

- ビュー・メニュー: viewMenuファセットにcommandMenuItemコンポーネントを追加します。複数項目の場合は、commandMenuItemコンポーネントのコンテナとしてgroupコンポーネントを使用します。

「コンポーネント」ウィンドウから、コンポーネントをファセットにドラッグ・アンド・ドロップします。たとえば、menuファセットに「メニュー」をドロップし、同じファセットに「メニュー項目」をドロップしてメニュー・リストを作成します。メニューおよびツールバーの詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

12.10 リストへのコレクションの表示

複数の列を持つ表を使用するかわりに、listViewおよびlistItemコンポーネントを使用すると、1つの列のみを持つ表のような単純な形式で構造化データを表示できます。図12-32に、1つのlistItemコンポーネントを持ち、それを使用して各行にエラー・アイコン、タスク情報およびアクション・ボタンを表示するlistViewコンポーネントを示します。

図12-32 1つのlistItemコンポーネントを持つlistViewコンポーネント

図12-33に示すように、表示するデータを列を使用してグループ化するかわりに、1つのlistItemコンポーネントに保持された複数のレイアウト・コンポーネントおよびその他のコンポーネントの組合せによって実際のデータが表示されます。この例では、listItemコンポーネントに1つの大きなpanelGroupLayoutコンポーネントが含まれ、子を水平に表示するように設定されています。子として別のpanelGroupLayoutコンポーネントが3つあり、これらを使用して表における列のように子をグループ化しています。これらのpanelGroupLayoutコンポーネントも、それぞれの子を水平に表示するように設定されています。これらのレイアウト・コンポーネントの2番目には、1つのpanelGroupLayoutコンポーネントが含まれ、子コンポーネント(この場合は3つのoutputTextコンポーネント)を垂直に表示するように設定されています。

図12-33 データを表示する複数のコンポーネントを含むlistItemコンポーネント

例12-22に、対応するコードを示します。

例12-22 listViewコンポーネント

<af:listView id="listView" binding="#{editor.component}"
var="item" varStatus="vs" partialTriggers="::pprLV"
value="#{demolistView.taskModel}"
selection="multiple">
<af:listItem id="lvi">
<af:showPopupBehavior popupId="::ctxtMenu"
triggerType="contextMenu"/>
<af:panelGroupLayout id="panelGroupLayout1"
layout="horizontal"
styleClass="AFStretchWidth">
<af:panelGroupLayout id="panelGroupLayout2"
layout="horizontal"
inlineStyle="margin-left:20px; width:45px"
halign="center" valign="middle">
<af:image rendered="#{vs.index %6 ==1}"
source="/images/error.png" id="i1"
shortDesc="Error at Line #{vs.index + 1}"/>
</af:panelGroupLayout>
<af:panelGroupLayout id="panelGroupLayout3" layout="horizontal"
inlineStyle="width:100%">
<af:panelGroupLayout id="panelGroupLayout5"
layout="vertical"
inlineStyle="min-width:300px">
<af:outputText id="outputText1" value="#{item.taskName}"
styleClass="taskName"/>
<af:outputText id="outputText2"
value="#{item.projectDesc}"
styleClass="taskProjectDesc"/>
<af:outputText id="outputText3" value="#{item.created}"
styleClass="taskCreated"/>
</af:panelGroupLayout>
</af:panelGroupLayout>
<af:panelGroupLayout id="panelGroupLayout4"
layout="horizontal" halign="end"
valign="middle"
inlineStyle="margin-right:20px">
<af:button id="cb1" text="Action"
shortDesc="Click To Invoke Action for Item #{vs.index + 1}">
<af:showPopupBehavior popupId="::popupDialog"
alignId="cb1" align="afterStart"/>
</af:button>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:listItem>
</af:listView>

listViewコンポーネントをコレクションにバインドします。その後、コンポーネントは各アイテムに値をスタンプ設定し、1つのlistItemコンポーネントを繰り返しレンダリングします。各アイテムにスタンプが設定されると、現在の行のデータが、listViewコンポーネントのvar属性を使用するEL式を使用して特定可能なプロパティにコピーされます。リストのレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

この例では、listViewの値はdemolistView.taskModelオブジェクトにバインドされています。このオブジェクトのプロパティには、varプロパティ(itemに設定されている)を使用してアクセスできます。たとえば、タスク名を表示する場合は、outputTextコンポーネントの値はitem.taskNameに設定されます。

また、listViewコンポーネントには、制限付きの2レベルの階層を表示することもできます。階層を表示するには、listViewをCollectionModelではなくTreeModelにバインドする必要があります。TreeModelは、1つのルート・レベルと1つの子レベルを持つことができます(TreeModelクラスの詳細は、第12.6項「ツリーへのデータ表示」を参照)。

ツリーの場合と同様に、listViewも、スタンプ設定を使用して個々のノードの値を表示し、ノードの親グループの表示に使用されるコンポーネントのホルダーとなるファセット(groupHeaderStampという名前のファセット)を使用します。ただし、listViewで許可されるのは2レベルのみであるため、groupHeaderStampファセットには、ルート・レベルのみの表示に使用されるコンポーネントが含まれます。

図12-34に、ルートがアルファベット文字、リーフ・ノードが従業員オブジェクトという単純な階層を表示するlistViewコンポーネントを示します。

図12-34 listViewコンポーネントの単純な階層

例12-23に示すように、従業員オブジェクトの表示に使用されるコンポーネントはlistItemコンポーネント内に配置され、アルファベット文字の表示に使用されるコンポーネントはgroupHeaderStampファセットのlistItemコンポーネント内に配置されています。

例12-23 listViewコンポーネントのgroupHeaderStampファセット

<af:listView id="listView" binding="#{editor.component}"
var="item" varStatus="vs" groupDisclosurePolicy="noDisclosure"
value="#{demolistView.ABTreeModel}">
<af:listItem id="listItem1">
<af:panelGroupLayout id="pgl3" layout="vertical">
<af:outputText id="ot2" value="#{item.ename}" styleClass="ABName"/>
<af:outputText id="ot3" value="#{item.job}" styleClass="ABJob"/>
</af:panelGroupLayout>
</af:listItem>
<f:facet name="groupHeaderStamp">
<af:listItem id="listItem2" styleClass="ABHeader">
<af:outputText id="ot1" value="#{item.alphabetHeading}"/>
</af:listItem>
</f:facet>
</af:listView>

listViewコンポーネントに階層を表示する場合は、図12-35に示すように、ヘッダーで子コンポーネントを表示または非表示にできるように構成できます。

図12-35 閉じるヘッダーを表示するように構成されたlistViewコンポーネント

デフォルトでは、listViewコンポーネントはすべての子を表示するように構成されます。groupDisclosurePolicy属性を使用すると、これを変更できます。

ユーザーがグループの開閉を行うと、RowDisclosureEventが起動されます。groupDisclosureListenerを使用すると、プログラムからノードを開閉できます。詳細は、12.6.4項「プログラムを使用したノードの開閉に関する必知事項」を参照してください。

ユーザーが行またはノードを選択または選択解除すると、SelectionEventが起動されます。selectionListenerを使用すると、プログラムでイベントに応答できます。詳細は、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

12.10.1 リストへのコレクションの表示方法

リストを作成するには、CollectionModelインスタンスにバインドされたlistViewコンポーネントと、1つのlistItemコンポーネントを使用します。単純な親子のヘッダーを表示する場合は、groupHeaderStampファセット内に2つ目のlistItemコンポーネントを配置します。次に、レイアウト・コンポーネントとその他のテキスト・コンポーネントを追加して、実際のデータを表示します。

リストにコレクションを表示するには:

1. リストのバインド先となるモデルのJavaクラスを作成します。リストにヘッダー付きのグループを表示する場合、org.apache.myfaces.trinidad.model.TreeModelクラスを拡張するモデルを使用する必要があります。それ以外の場合は、org.apache.myfaces.trinidad.model.CollectionModelクラスを拡張します。

ヒント:

java.util.List、array、javax.faces.model.DataModelなど、別のモデル・クラスも使用できます。このような別のクラスのいずれかを使用する場合は、listViewコンポーネントにより、インスタンスがCollectionModelクラスに自動的に変換されますが、機能は追加されません。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

2. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「リスト・ビュー」をページにドラッグ・アンド・ドロップします。

3. 「プロパティ」ウィンドウの「その他」セクションを開いて、次のとおりに設定します。

- Value: 手順1で作成したモードにリストをバインドするためのEL式を指定します。

- Var: 各ノードを表す変数名を指定します。

- First: リストに表示する最初の行として設定する行を指定します。

- FetchSize: 各データ・フェッチで戻されるブロックのサイズを設定します。デフォルトは25です。

- Rows: 行範囲に表示する行の数を指定します。デフォルトでは、この値は25 (fetchSize属性と同じ値)です。

- SelectedRowKeys: オプションで、最初に選択されるノードのキーを入力します。詳細は、12.6.5項「プログラムを使用したノードの選択に関する必知事項」を参照してください。

- Selection: 行を選択可能にするための値(つまりrowSelection属性)を設定します。有効な値はnone、singleおよびmultipleです。選択された行でプログラムを使用してアクションを実行する方法の詳細は、12.3.8項「表の選択された行でのアクションの実行に関する必知事項」を参照してください。

4. listViewコンポーネントの子として、「リスト・アイテム」をドラッグ・アンド・ドロップします。

5. レイアウトとその他のコンポーネントをlistViewコンポーネントにドラッグ・アンド・ドロップして、目的の構成を作成します。例については、図12-33および例12-22を参照してください。

6. listViewコンポーネントに単純な階層を表示する場合は、groupHeaderStampファセットに「リスト・アイテム」をドラッグ・アンド・ドロップします。例12-23に、「構造」ウィンドウ内のgroupHeaderStampファセットを示します。

図12-36 構造ウィンドウのgroupHeaderStampファセット

7. listItemコンポーネントに「出力テキスト」をドラッグ・アンド・ドロップしてヘッダー・テキストを表示し、必要に応じてoutputTextコンポーネントを構成します。

12.11 カルーセルでのイメージの表示

図12-37に示すように、イメージを回転カルーセルに表示できます。ユーザーは、下部にあるスライダを使用するか、補助イメージの1つをクリックしてそのイメージを前面に移動することにより、前面のイメージを変更できます。

図12-37 ADF Facesカルーセル

デフォルトでは、カルーセルは水平に表示されます。カルーセルの水平方向のオブジェクトは中央に垂直に整列され、カルーセル自体はそのコンテナの中央に水平に整列されます。

参照ローロデックス(回転式カード・ファイル)が必要な場合は、垂直に表示されるようにカルーセルを構成できます。デフォルトでは、垂直方向のカルーセルの中のオブジェクトは水平方向の中央がそろうように整列され、カルーセル自体は垂直方向の中央に整列されます(図12-38を参照)。カルーセルの位置合せ属性を使用して、位置合せを変更できます。

図12-38 垂直カルーセル・コンポーネント

ベスト・プラクティス:

一般に、カルーセルは子を拡大する親コンポーネントに配置する必要があります(panelSplitterやpanelStretchLayoutなど)。子を拡大するコンポーネントにカルーセルを配置しない場合、カルーセルは幅500px、高さ300pxのデフォルト・サイズで表示されます。これらのサイズは変更できます。

前後のイメージを部分的に表示するかわりに、映写フィルム風デザインで(図12-39を参照)、またはルーミー・サーキュラー・デザインで(図12-40を参照)イメージを表示するようにカルーセルを構成することができます。

図12-39 カルーセルの映写フィルム風表示

図12-40 カルーセルのルーミー・サーキュラー表示

デフォルトでは、カルーセルが循環モードで表示するように構成されている場合、補助アイテム(現在、中央に表示されていないアイテム)にポインタを置くと、そのアイテムが枠で囲まれ選択可能であることが示されます(この枠は、アプリケーションがSkyrosまたはFusion FX v1.2以降のスキンを使用している場合にのみ、表示されることに注意してください)。図12-41に示すように、アイテムが移動し、最大サイズで表示されるように、カルーセルを構成できます。

図12-41 マウスを置いた場所に移動する補助アイテム

カルーセルに現在のイメージのみを表示するように構成することもできます(図12-42を参照)。

図12-42 カルーセルにイメージを1つだけ表示できる

イメージの一覧表示に使用されるコントロールを構成できます。前後への矢印付きの、複数のイメージにまたがるスライダを表示することも、前後へのボタンのみを表示することも(図12-42を参照)、前後へのボタンとスライド・カウンタを表示することもできます(図12-43を参照)。

図12-43 スライダのない次および前ボタン

子carouselItemコンポーネントは、カルーセルにオブジェクトとそのオブジェクトのタイトルを表示します。表示するオブジェクトごとにcarouselItemコンポーネントを作成し、これらのコンポーネントを個々のオブジェクトにバインドするかわりに、carouselコンポーネントを完全なコレクションにバインドします。ツリーが各データ行をスタンプ・アウトするのと同様の方法で、コンポーネントは、各項目の値をスタンプ処理することで1つのcarouselItemコンポーネントを繰り返しレンダリングします。各項目にスタンプが設定されると、現在の項目のデータが、carouselコンポーネントvar属性を使用するEL式を使用して特定可能なプロパティにコピーされます。カルーセルのレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。カルーセルには、テキストの表示に使用されるcarouselItemコンポーネントのホルダーと各項目の短い説明の両方であり、各項目について表示されるイメージの親コンポーネントでもあるnodeStampファセットが含まれます。

たとえば、図12-37に示すADF FacesデモのcarouselItem JSFページには、各ADF Facesコンポーネントのイメージを表示するcarouselコンポーネントが含まれます。demoCarouselItem (CarouselBean.java)マネージドBeanには、これらの各コンポーネントのリストが含まれます。carouselコンポーネントのvalue属性は、そのリストを表すそのBeanのitemsプロパティにバインドされます。カルーセル・コンポーネントのvar属性は、表示する各項目の値の保持に使用され、各項目の適切な値を取得するためにcarouselItemコンポーネントとimageコンポーネントの両方で使用されます。例12-24に、カルーセルのJSFページ・コードを示します。カルーセルのスタンプ動作の詳細は、12.6項「ツリーへのデータの表示」を参照してください。

例12-24 carouselコンポーネントのJSFページ・コード

<af:carousel id="carousel" binding="#{editor.component}"
var="item"
value="#{demoCarousel.items}"
carouselSpinListener="#{demoCarousel.handleCarouselSpin}">
<f:facet name="nodeStamp">
<af:carouselItem id="crslItem" text="#{item.title}" shortDesc="#{item.title}">
<af:image id="img" source="#{item.url}" shortDesc="#{item.title}"/>
</af:carouselItem>
</f:facet>
</af:carousel>

carouselItemコンポーネントは、子コンポーネントのみ拡大します。単一のimageコンポーネントをcarouselItemの内部に配置した場合、イメージはその項目に割り当てられた正方形に合せて拡大されます(ユーザーがカルーセルをスピンすると、これらのサイズが縮小または拡大されます)。

ベスト・プラクティス:

imageコンポーネントは、拡大されたときの動作を変更するジオメトリ管理コントロールを提供しません。拡大されたときにイメージが適切な縦横比を保つためには、同じ幅と高さのイメージを使用する必要があります。

carouselコンポーネントでは、CollectionModelクラスを使用して基礎となるコレクションのデータにアクセスします。このクラスは、JSF DataModelクラスを拡張し、行キーのサポートを追加します。DataModelクラスでは、行は索引によって完全に識別されます。ただし、基になるデータが変更された場合に問題を回避するために、CollectionModelクラスが索引ではなく行キーに基づいています。

java.util.List、arrayおよびjavax.faces.model.DataModelなど、別のモデル・クラスも使用できます。他のいずれかのクラスを使用する場合は、carouselコンポーネントにより、インスタンスがCollectionModelクラスに自動的に変換されますが、機能は追加されません。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、項目を表すデータ・ソースに対するADFビジネス・コンポーネントを作成でき、作成するとモデルが作成されます。その後、カルーセルを宣言的に作成でき、そのカルーセルは自動的にそのモデルにバインドされます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADF Facesカルーセル・コンポーネントの使用」の章を参照してください。

カルーセル・コンポーネントは仮想化されているため、サーバーのコンポーネントに存在するすべての項目がクライアントに配信されて表示されるわけではありません。データ・ソースから一度に一定数の行をフェッチするようにカルーセルを構成します。レンダリング時にすぐにデータをコンポーネントに配信することも、コンポーネントのシェルがレンダリングされた後に遅延フェッチすることもできます。デフォルトでは、カルーセルは初期リクエストのデータを遅延してフェッチします。ページにこれらのコンポーネントが1つ以上含まれる場合、ページでは最初は標準のライフサイクルが実行されます。ただし、カルーセルはその初期リクエスト時にデータをフェッチするかわりに、特殊な部分ページ・レンダリング(PPR)リクエストをコンポーネントで別途実行し、カルーセルのフェッチ・サイズの値として設定される項目数が返されます。ページのレンダリング直後であるため、レスポンスのレンダリング・フェーズのみがカルーセルに対して実行され、対応するデータのフェッチおよび表示が可能になります。ユーザーが後続のデータ・フェッチの原因となる操作(たとえば、カルーセルを別のイメージ・セットに回転)を実行すると、別のPPRリクエストが実行されます。

パフォーマンスのヒント:

ページにカルーセルより多くのコンポーネントが含まれる場合は、遅延配信を使用する必要があります。遅延配信を使用すると、データが使用可能になる前に、初期ページのレイアウト・コンポーネントおよびその他のコンポーネントが最初にレンダリングされます。

即時配信は、カルーセルがページの唯一のコンテキストである場合、またはカルーセルが大きな項目セットを返さないと予想される場合に使用します。この場合、ユーザー・レスポンス時間がより高速で、サーバーCPU利用率がより高ければ、2番目のリクエストはサーバーに移動しないため、レスポンス時間は遅延配信を使用する場合よりも高速になります(または、場合によっては高速に感じます)。ただし、フェッチ・ブロックとして構成された項目数のみが最初に返されます。遅延配信と同様に、ユーザーのアクションが後続のデータ・フェッチの原因となる場合は、次の項目セットが配信されます。

スライダ・コントロールでは、ユーザーはコレクションをナビゲートできます。通常、スライダ上のサムにはオブジェクトの総数のうちの現在のオブジェクト番号(6/20など)が表示されます。オブジェクトの総数が大きすぎて計算できない場合、スライダ上のサムには現在のオブジェクト番号のみ表示されます。たとえば、会社の従業員電話帳にカルーセルが使用されているとします。デフォルトでは、電話帳には全従業員の顔写真が表示されますが、コストの高いデータベース・コールを行わないと、その日システムに厳密に94,409人の従業員がいることがわからない場合があります。

カルーセルとともに他のコンポーネントを使用できます。たとえば、ツールバーまたはメニュー・バーを追加し、ユーザーが現在のオブジェクトに対するアクションを実行できるボタンまたはメニュー項目をそれらに追加できます。

12.11.1 カルーセルの作成方法

カルーセルを作成するには、まず、表示するイメージを含むデータ・モデルを作成する必要があります。次に、carouselコンポーネントをそのモデルにバインドし、carouselItemコンポーネントをカルーセルのnodeStampファセットに挿入します。最後に、imageコンポーネント(またはimageコンポーネントを含むその他のコンポーネント)をcarouselItemコンポーネントに子として挿入します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.11項「カルーセルでのイメージの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

表示するイメージのコレクションを提供するデータ・モデルを作成します。データ・モデルは、List、Array、DataModelまたはCollectionModelにすることができます。コレクションがCollectionModel以外の場合、フレームワークはそれをCollectionModelに自動的に変換します。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

データ・モデルは、カルーセルに表示する各イメージについて次の情報を提供する必要があります。

- イメージのURL

- カルーセルのイメージの下に表示されるタイトル

- ユーザーがイメージ上にカーソルを置いたときに表示するテキストに使用される短い説明

たとえば、ADF Facesデモ・アプリケーションのCarouselBean.javaおよびCarouselMediaBean.javaクラスを参照してください。

カルーセルを作成する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「カルーセル」をページにドラッグ・アンド・ドロップします。

ベスト・プラクティス:

子を拡大する親コンテナにカルーセルを配置します。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、次の設定を行います。

- Orientation: デフォルトでは、カルーセルは水平に表示されます。図12-38に示すように垂直に表示する場合は、verticalを選択します。horizontalに設定した場合は、halign属性を使用して、項目を整列する方法を構成する必要があります。verticalに設定した場合は、valign属性を使用して、項目を整列する方法を設定します。

- Halign: 垂直カルーセルの項目を表示する方法を指定します。有効な値は次のとおりです。

- center: 中心点が同一になるように項目を位置合せします。これがデフォルトです。

- end: 右端が整列するように項目を位置合せします(ブラウザに表示されているのが左から右への言語の場合)。

- start: 左端が整列するように項目を位置合せします(ブラウザに表示されているのが左から右への言語の場合)。

- Valign: 水平カルーセルの項目を表示する方法を指定します。有効な値は次のとおりです。

- middle: 中央点が同一になるように項目を位置合せします。これがデフォルトです。

- bottom: 下端が整列するように項目を位置合せします。

- top: 上端が整列するように項目を位置合せします。

- Value: カルーセルをモデルにバインドします。

3. 「データ」セクションを開き、次の属性を設定します。

- Var: 個々の項目データにアクセスするためにELで使用される変数を入力します。

- VarStatus: カルーセルのステータスにアクセスするためにELで使用される変数を入力します。varStatusの共通プロパティは次のとおりです。

- model: コンポーネントのCollectionModelを返します。

- index: ゼロ・ベースの項目索引を返します。

4. 「外観」セクションを開き、次の設定を行います。

- EmptyText: 項目が返されない場合に表示するテキストを入力します。リソース・バンドルを使用している場合は、ドロップダウン・メニューを使用して「テキスト・リソースの選択」を選択します。

5. 子を拡大する親コンポーネントにカルーセルを配置しない場合、カルーセルは幅500px、高さ300pxで表示されます。これらの設定は変更できます。そのためには、「スタイル」セクションを開き、「レイアウト」タブをクリックして高さと幅をピクセル単位で設定します。

6. 「動作」セクションを開き、次の設定を行います。

- FetchSize: 各データ・フェッチで戻されるブロックのサイズを設定します。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、カルーセルのレンダリングと同時に項目がフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中に項目がフェッチされてクライアントに送信されます。

- CarouselSpinListener: カルーセルが回転されたときにロジックを実行する必要がある場合に、カルーセルの回転を処理するハンドラ・メソッドにバインドします。例12-25に、回転が行われたときに詳細パネルを再描画するCarouselBeanのハンドラ・メソッドを示します。

例12-25 CarouselSpinEventのハンドラ

public void handleCarouselSpin(CarouselSpinEvent event)
{
RichCarousel carousel = (RichCarousel)event.getComponent();
carousel.setRowKey(event.getNewItemKey());
ImageInfo itemData = (ImageInfo)carousel.getRowData();
_currentImageInfo = itemData;

// Redraw the detail panel so that we can update the selected details.
RequestContext rc = RequestContext.getCurrentInstance();
rc.addPartialTarget(_detailPanel);
}

7. 「拡張」セクションを開き、CurrentItemKeyを設定します。カルーセルが最初にレンダリングされるときに表示する項目を指定します。値そのもの(または値を解決した結果)が、CollectionModelでのその項目の主キーである必要があります。

8. 「その他」セクションを開き、次の設定を行います。

- AuxiliaryOffset: オフセット・シフトをコントロールする値を入力します。カルーセルの項目は、現在のカルーセル項目の方向にある最も近い項目を基準として、この値に従ってシフトされます(DisplayItemsモードがcircularのとき)。

- AuxiliaryPopOut: hoverを選択すると、補助アイテムにマウス・ポインタを置いたときにそのアイテムがフル・サイズでレンダリングされ、不透明のオーバーレイが除去されます。

- AuxiliaryScale: サイズ・スケーリングをコントロールする値を入力します。カルーセルの項目は、現在のカルーセル項目の方向にある最も近い項目を基準として、この値に従って拡大されます(DisplayItemsモードがcircularのとき)。値が1の場合は、補助アイテムはすべて同じサイズになります。値が1より小さい場合は、補助アイテムは現在の項目から離れるに従って小さくなります。値が1より大きい場合は、補助アイテムは現在の項目から離れるに従って大きくなります。

- ControlArea: カルーセル・イメージの参照に使用するコントロールを指定します。有効な値は次のとおりです。

- full: スライダに、組込みの次および前ボタン、現在の項目テキストおよびイメージ番号が表示されます。これがデフォルトです。

- compact: 次および前ボタンと項目テキストのみ表示されます。

- small: 次および前ボタンが、現在の項目テキストおよびイメージ番号とともに表示されます。

- none: スライダは表示されません。

- DisplayItems: circularを選択すると、カルーセルに複数のイメージが表示されます。カルーセルに一度に1つのイメージを表示する場合は、oneByOneを選択します。

ヒント:

DisplayItemsモードがcircularモードの場合にルーミー・サーキュラー・デザインを実現するには、AuxiliaryScaleを0.8、AuxiliaryOffsetを0.8に設定します。アイテムを循環モードの映写フィルム風デザインで表示するには、AuxiliaryScaleを1.0、AuxiliaryOffsetを1.1に設定します。

10. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「カルーセル・アイテム」をCarouselコンポーネントのnodeStampファセットにドラッグします。
カルーセルのvar属性に設定された変数値を使用して、CarouselItemコンポーネントの属性をデータ・モデルのプロパティにバインドします。たとえば、例12-24のカルーセルは、itemをvar属性の値として使用します。このため、carouselItemのtext属性の値はitem.titleになります(titleが、データ・モデルのカルーセル項目に使用されるテキストへのアクセスに使用されるプロパティである場合)。

11. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、イメージをドラッグしてcarouselItemの子としてドロップします。
カルーセルのvar属性に設定された変数値を使用して、imageコンポーネントの属性をデータ・モデルのプロパティにバインドします。たとえば、例12-24のカルーセルは、itemをvar属性の値として使用します。このため、imageのsource属性の値はitem.urlになります(urlがイメージへのアクセスに使用されるプロパティである場合)。

機能を増やす場合は、イメージ・コンポーネントを他のコンポーネントで囲むことができます。たとえば、図12-44に、イメージがpanelGroupLayoutコンポーネントで囲まれ、clientListenerを使用してメニューとナビゲーション・バーを表示するJavaScript関数をコールするカルーセルを示します。

図12-44 より複雑なカルーセルのレイアウトの使用

例12-26に、対応するページ・コードを示します。

例12-26 カルーセルのより複雑なレイアウト

<af:carouselItem id="mainItem" text="#{item.title}" shortDesc="#{item.title}">
<af:panelGroupLayout id="itemPgl" layout="vertical">
<af:image id="mainImg" source="#{item.url}" shortDesc="#{item.title}"
styleClass="MyImage">
<af:clientListener method="handleItemOver" type="mouseOver"/>
<af:clientListener method="handleItemDown" type="mouseDown"/>
<af:showPopupBehavior triggerType="contextMenu" popupId="::itemCtx"/>
</af:image>
<af:panelGroupLayout id="overHead" styleClass="MyOverlayHeader"
layout="vertical" clientComponent="true">
<af:menuBar id="menuBar">
<af:menu id="menu" text="Menu">
<af:commandMenuItem id="menuItem1" text="Menu Item 1"/>
<af:commandMenuItem id="menuItem2" text="Menu Item 2"/>
<af:commandMenuItem id="menuItem3" text="Menu Item 3"/>
</af:menu>
</af:menuBar>
</af:panelGroupLayout>
<af:panelGroupLayout id="overFoot" styleClass="MyOverlayFooter"
layout="vertical" clientComponent="true"
halign="center">
<af:panelGroupLayout id="footHorz" layout="horizontal">
<f:facet name="separator">
<af:spacer id="footSp" width="8"/>
</f:facet>
<af:link . . .
/>
<af:outputText id="pageInfo" value="Page 1 of 1"/>
<af:link . . .
/>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:carouselItem>

例12-27に、対応するJavaScriptを示します。

例12-27 マウス・オーバーとマウス・ダウンを処理するJavaScriptコード

function handleItemOver(uiInputEvent)
{
var imageComponent = uiInputEvent.getCurrentTarget();
var carousel = null;
var componentParent = imageComponent.getParent();
while (componentParent != null)
{
if (componentParent instanceof AdfRichCarousel)
{
carousel = componentParent;
}
componentParent = componentParent.getParent();
}
if (carousel == null)
{
AfLogger.LOGGER.severe("Unable to find the carousel component!");
return;
}
var currentItemKeyPattern = ":"+ carousel.getCurrentItemKey() +":";

var overlayHeaderComponent = imageComponent.findComponent("overHead");
var overlayHeaderId = overlayHeaderComponent.getClientId();
// In IE we get mouseover for other items as well. This is despite having an
// overlay div on top
if(overlayHeaderId.indexOf(currentItemKeyPattern) == -1)
return;
if (overlayHeaderId != window._myHeader)
{
// ensure only one set of overlays are visible
hideExistingOverlays();
}
var overlayFooterComponent = imageComponent.findComponent("overFoot");

window._myHeader = overlayHeaderComponent.getClientId();
window._myFooter = overlayFooterComponent.getClientId();

// do not propagate to the server otherwise all stamps will get this property on
// next data fetch
overlayHeaderComponent.setProperty("inlineStyle", "display:block", false, AdfUIComponent.PROPAGATE_LOCALLY);
overlayFooterComponent.setProperty("inlineStyle", "display:block", false, AdfUIComponent.PROPAGATE_LOCALLY);
}

function handleItemDown(uiInputEvent)
{
if (uiInputEvent.isLeftButtonPressed())
{
// Only hide the overlays if the left button was pressed
hideExistingOverlays();
}
}

パフォーマンスのヒント:

カルーセルの構造が単純なほど、実行が高速になります。

12.11.2 カルーセル・コンポーネントと各種ブラウザに関する必知事項

一部のブラウザでは、カルーセルの項目の装飾がより豊富になります。たとえば、図12-45に示すように、SafariとGoogle Chromeには、カルーセルの項目の周囲にわずかに影が表示され、現行でない項目はより明るい色でオーバーレイされ、補助項目が現在の項目でないことがわかりやすくなります。

図12-45 Google Chromeに表示されるカルーセル・コンポーネント

図12-46に、Internet Explorerでの同じコンポーネントを示します。

図12-46 Microsoft Internet Explorerに表示されたカルーセル・コンポーネント

12.12 表、ツリーまたはツリー表からのデータのエクスポート

表、ツリーまたはツリー表から、あるいはデータ視覚化プロジェクトのガント・チャートの表領域から、データをMicrosoft Excelスプレッドシートまたはカンマ区切り形式(CSV)ファイルにエクスポートできます。ユーザーが表をエクスポートできるようにするには、エクスポートの起動に使用するアクション・ソース(ボタンやリンクなど)を作成し、exportCollectionActionListenerコンポーネントを追加して、エクスポートするデータに関連付けます。exportCollectionActionListenerを構成するときに、表またはツリーのすべての行をエクスポートするか、ユーザーが選択した行のみをエクスポートするかを指定します。

ヒント:

DVTピボット表からデータをエクスポートすることもできます。詳細は、25.5.3項「ピボット・テーブルからのエクスポート」を参照してください。

たとえば、図12-47に示すADF Facesデモ・アプリケーションの表には、ユーザーがデータをExcelのスプレッドシートに、またはCSVファイルとしてエクスポートするためのボタンがあります。

図12-47 データをエクスポートするためのボタンがある表

ユーザーがボタンの1つをクリックすると、すべての行をスプレッドシートまたはCSVにエクスポートする処理がリスナーによって実行されます。図12-47に示すように、ユーザーが選択する行のみがエクスポートされるように、exportCollectionActionListenerコンポーネントを構成することも可能です。

次の値のみエクスポートできます

- 値ホルダー・コンポーネント(inputコンポーネントやoutputコンポーネントなど)の値。

- selelctOneChoiceおよびselectOneListboxコンポーネントで使用されるselectItemコンポーネントの値(他の選択コンポーネントのselectItemコンポーネントの値はエクスポートされません)。

- コマンド・コンポーネントのtext属性の値。

- imageおよびiconコンポーネントのshortDesc属性の値。

imageコンポーネントおよびiconコンポーネントのshortDesc属性の値がエクスポートされないようにするには(たとえば、セル内にイメージがある場合)、事前定義済のskipObjectComponentフィルタ・メソッドを使用します。このメソッドはexportCollectionActionListenerの前に実行され、実行するとObjectコンポーネントはエクスポートされなくなります。独自のフィルタ・メソッドを作成して任意の必要なロジックをexportCollectionActionListenerの実行前に適用することもできます。

ブラウザ、およびリスナーの構成に応じて、図12-48に示すようにブラウザのダイアログが開くか(このダイアログで、ユーザーはファイルを開くか保存するかを選択できます)、ファイルがブラウザに表示されます。たとえば、ユーザーがMicrosoft Internet Explorerでページを表示していて、exportCollectionActionListenerコンポーネントにファイル名が指定されていない場合、ファイルはブラウザに表示されます。Mozilla Firefoxでは、ダイアログが開かれます。

図12-48 Excelへのエクスポート・ダイアログ

ユーザーがファイルの保存を選択した場合は、後でそのファイルをスプレッドシート・アプリケーションで開くことができます(図12-49を参照)。ユーザーがファイルを開くことを選択した場合、その後の動作はブラウザにより異なります。たとえば、ユーザーがページをMicrosoft Internet Explorerで見ているときにスプレッドシートをエクスポートした場合は、スプレッドシートはブラウザ・ウィンドウに表示されます。ユーザーがMozilla Firefoxでページを表示している場合は、スプレッドシートがExcelで開かれます。

図12-49 Excelにエクスポートされたデータファイル

注意:

スプレッドシートの場合は、ファイルのフォーマットがファイル拡張子で指定されたものとは異なるというExcelの警告が表示されることがあります。この警告は無視して問題ありません。

12.12.1 表、ツリーまたはツリー表データの外部形式へのエクスポート方法

ボタン、リンク、メニュー項目などのコマンド・コンポーネントを作成し、そのコンポーネントの内部にexportCollectionActionListenerを追加します。その後、exportCollectionActionListenerコンポーネントのexportedId属性を、データをエクスポートするコレクション・コンポーネントIDに設定して、エクスポートするデータ・コレクションを関連付けます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、12.12項「表、ツリーまたはツリー表からのデータのエクスポート」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

ページに表、ツリーまたはツリー表が存在している必要があります。ない場合は、この章の指示に従って表、ツリーまたはツリー表を作成します。たとえば、表を追加するには、12.3項「表へのデータの表示」を参照してください。

ヒント:

ユーザーがエクスポートする行を選択できるようにするには、選択が許可されるよう表を構成します。詳細は、12.3.2項「表の書式設定」を参照してください。

外部形式にコレクション・データをエクスポートする手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、コマンド・コンポーネント(たとえばボタン)をページにドラッグ・アンド・ドロップします。

ヒント:

表、ツリーまたはツリー表にコマンド・コンポーネントのあるツールバーを作成する場合は、コレクション・コンポーネントをpanelCollectionコンポーネントで囲みます。このコンポーネントにより、ツールバー機能が追加されます。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

コマンド・コンポーネントのデフォルトのラベルを、意味のある名前(たとえば「スプレッドシートにエクスポート」)に変更することをお薦めします。

2. 「コンポーネント」ウィンドウの「操作」パネルから、「エクスポート・コレクション・アクション・リスナー」をコマンド・コンポーネントに子としてドラッグします。

3. 「エクスポート・コレクション・アクション・リスナーの挿入」ダイアログで、次の設定を行います。

- ExportedId: エクスポートする表、ツリーまたはツリー表のIDを指定します。手動で入力するか、ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログを使用して、コンポーネントを選択します。

- Type: excelHTMLに設定すると、Microsoft Excelスプレッドシートにエクスポートされます。CSVに設定すると、カンマ区切り値形式ファイルにエクスポートされます。

4. exportCollectionActionListenerコンポーネントがまだ選択されている状態で、「プロパティ」ウィンドウで次のとおりに設定します。

- Filename: エクスポートするコンテンツの選択したファイル名を指定します。この属性を設定すると、通常は「ファイルの保存」ダイアログが表示されますが、最終的にはブラウザにより異なります。この属性を設定しない場合、通常、コンテンツはブラウザにインライン表示されます(可能な場合)。

- Title: エクスポートするドキュメントのタイトルを指定します。タイトルを表示するかどうか、およびどれくらいの精度で表示するかは、スプレッドシート・アプリケーションに依存します。

- exportedRows: 表のすべての行をエクスポートするか、ユーザーが選択した行のみをエクスポートするかを指定します。表でdetailStampファセットが使用されている場合は、データをエクスポートするかどうかを選択できます(detailStampファセットの詳細は、12.4項「表への非表示機能の追加」を参照してください)。次のいずれかを設定します。

- all: すべての行が自動的に選択され、エクスポートされます。

- selected: ユーザーが選択した行のみがエクスポートされます。

- allWithoutDetails: detailStampファセットのデータを除くすべての行が選択され、エクスポートされます。

- selectedWithoutDetails: ユーザーが選択した行のみがエクスポートされます(detailStampファセットのデータを除く)。

- RowLimit: エクスポートできる行の最大数を表す数値を入力します。制限なしの場合は、-1を入力します。

- Charset: デフォルトではUTF-8が使用されます。必要であれば、別のキャラクタ・セットを指定できます。

- FilterName: skipObjectComponentと入力すると、任意のObjectコンポーネントを処理対象から除外するための組込みメソッドが実行されるようになります。

- FilterMethod: 評価結果がメソッドとなるようなEL式を入力します。このメソッドは、必要なオーバーライド・ロジックを処理するExportCollectionActionListenerの前に起動されます。

例12-28に、表およびそのexportCollectionActionListenerコンポーネントのコードを示します。exportedId値が、表のid値に設定されていることに注意してください。

例12-28 exportCollectionActionListenerを使用した表のエクスポート

<af:table contextMenuId="thePopup" selectionListener="#{fs.Table}"
rowselection="multiple" columnselection="multiple"
columnBandingInterval="1"
binding="#{editor.component}" var="test1" value="#{tableTestData}"
id="table" summary="table data">
<af:column>
. . .
</af:column>
</af:table>
<af:button text="Export To Excel" immediate="true">
<af:exportCollectionActionListener type="excelHTML" exportedId="table"
filename="export.xls" title="ADF Faces Export"/>

12.12.2 実行時の処理: 行の選択がエクスポートされるデータに与える影響

エクスポートされるデータは、選択したキーの順序ではなく、索引順でエクスポートされています。つまり、選択した行のエクスポートを可能にして、ユーザーが8、4、2(という順序で)行を選択すると、行はExcelに2、4、8という順序でエクスポートされて表示されます。

12.13 コレクションベースのコンポーネントからクライアント上の選択された値へのアクセス

ADF Facesフレームワークでは、クライアント側でのELのサポートが存在せず、コレクション・モデル全体をクライアントに送信することもサポートされていないため、クライアント上でJavaScriptを使用して値にアクセスする必要がある場合に、クライアント側のコードがコンポーネント・スタンピングに依存して値にアクセスすることはできません。各行で同じコンポーネント・インスタンスを再利用するかわりに、完全に解決されるEL式を使用して、各行に新しいJavaScriptコンポーネントが作成されます(どの行にもコンポーネントが1つ作成される必要があると仮定しています)。

したがって、クライアント上で行固有のデータにアクセスするには、コレクションベース・コンポーネントそのものを使用して値にアクセスする必要があります。クライアント側のデータ・モデルを使用せずにこれを実現するには、クライアント側の選択変更リスナーを使用します。

12.13.1 スタンプ設定されたコンポーネントの選択内容から値へのアクセス方法

コレクションベースのコンポーネントからクライアント上の値にアクセスするには、まずコンポーネントにクライアント表現があることを確認する必要があります。その後で、選択変更リスナーをクライアント上で登録する必要があります。そのリスナーは、選択された行を特定し、その行に対応するスタンプされたコンポーネントを見つけ、このコレクション・コンポーネントを使用して行固有の名前を特定し、選択されたデータに対して必要な操作を行うように設定する必要があります。

始める前に:

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、12.1.2項「コレクションベース・コンポーネントの追加機能」を参照してください。

コレクションベース・コンポーネントから選択された値にアクセスする手順:

1. ページの構造ウィンドウで、スタンプ設定された行に関連付けられたコンポーネントを選択します。たとえば、例12-29の表では、outputTextコンポーネントを使用してスタンプ設定された行が表示されています。

例12-29 スタンプ設定された行にoutputTextコンポーネントが使用されている表コンポーネント

<af:table var="row" value="#{data}" rowSelection="single">
<af:column headerText="Name">
<af:outputText value="#{row.name}"/>
</af:column>
</af:table>

コンポーネントに次の設定を行います。

- 「プロパティ」ウィンドウの「共通」セクションを開き、コンポーネントの一意のIDがまだ定義されていない場合は、Id属性を使用して設定します。

- 「拡張」セクションを開き、ClientComponentをTrueに設定します。

2. 「コンポーネント」ウィンドウの「操作」パネルから、「クライアント・リスナー」をコレクション・コンポーネントに子としてドラッグ・アンド・ドロップします。

3. 「クライアント・リスナーの挿入」ダイアログで、「メソッド」フィールドに関数名(次の手順でこの関数を実装します)を入力し、「タイプ」ドロップダウンから「selection」を選択します。
たとえば、関数としてmySelectedRowを入力した場合、JDeveloperにより、例12-30に太字で示されたコードが入力されます。

例12-30 選択を登録するためのclientListenerの使用

<af:table var="row" value="#{data}" rowSelection="single">
<af:clientListener type="selection" method="mySelectedRow"/>
...
</af:table>

このコードにより、mySelectedRow関数は、選択内容が変更されるたびにコールされます。

4. JavaScriptライブラリで、前の手順で入力された関数を実装します。この関数により、次の操作が実行されます。

- どの行が選択されているかを調べます。そのためには、リスナーに渡されるイベント・オブジェクトを使用します。選択イベントの場合、イベント・オブジェクトのタイプはAdfSelectionEventです。このタイプは、選択された各行キーのプロパティを含むPOJSO (plain old JavaScript object)を返すgetAddedSet()メソッドを介して、新規に選択された行キーへのアクセスを可能にします。このオブジェクトへのアクセスが可能になったら、"for in"ループを使用して行キーを反復できます。たとえば、例12-31のコードは最初の行キー(この場合は唯一の行キー)を抽出します。

例12-31 "for" inループを使用した行キーの反復

function showSelectedName(event)
{
var firstRowKey;
var addRowKeys=event.getAddedSet();

for(var rowKey in addedRowKeys)
{
firstRowKey=rowKey;
break;
}
}

- 選択された行に関連付けられているスタンプ設定されたコンポーネントを検索します。クライアント側コンポーネントAPIのAdfUIComponentは、検索するコンポーネントのIDを受け取ってAdfUIComponentインスタンスを返すfindComponent()メソッドを公開します。スタンプ設定されたコンポーネントを使用している場合は、そのIDだけでなく、行キーでもコンポーネントを検索する必要があります。これをサポートするために、AdfUITableクラスは、IDと行キーの両方を受け取るfindComponent()のオーバーロード・メソッドを提供します。
選択イベントの場合、コンポーネントはイベントのソースです。したがって、コレクション・コンポーネントをイベントのソースから取得し、このコレクション・コンポーネントを使用してそのIDと行キーを使用するインスタンスを見つけることができます。例12-32にこれを示します。nameStampは表のIDです。

例12-32 選択された行を指定したスタンプ設定されたコンポーネント・インスタンスの検索

// The table needs to find the stamped component.
// Fortunately, in the case of selection events, the
// table is the event source.
var table = event.getSource();

// Use the table to find the name stamp component by id/row key:
var nameStamp = table.findComponent("nameStamp", firstRowKey);

5. コンポーネントを使用するために必要なその他のコードを追加します。スタンプ設定されたコンポーネントを検出したら、その他のコンポーネントの場合と同じように通信できます。たとえば、例12-33では、スタンプされたコンポーネントを使用してname属性の行固有の値(例12-29で示したスタンプされた値)を取得してから、この名前をアラートに表示する方法を示します。

例12-33 スタンプ設定されたコンポーネントの行の名前の取得

if (nameStamp)
{    // This is the row-specific name
var name = nameStamp.getValue();

alert("The selected name is: " + name);
}

例12-34にJavaScriptの全コードを示します。

例12-34 選択された行の値へのアクセスに使用されるJavaScript

function showSelectedName(event)
{
var firstRowKey;
var addedRowKeys = event.getAddedSet();

for (var rowKey in addedRowKeys)
{
firstRowKey = rowKey;
break;
}
// The table needs to find the stamped component.
// Fortunately, in the case of selection events, the
// table is the event source.
var table = event.getSource();

// We use the table to find the name stamp component by id/row key:
var nameStamp = table.findComponent("nameStamp", firstRowKey);

if (nameStamp)
{
// This is the row-specific name
var name = nameStamp.getValue();

alert("The selected name is: " + name);
}
}

12.13.2 選択された値へのアクセスに関する必知事項

行キーはサーバー上のtokenizedで、これはクライアント上の行キーとサーバー上の行キーに類似点がない可能性があることを意味します。そのため、クライアント側APIによって処理される行キー(AdfSelectionEvent.getAddedSet()など)のみ有効です。

また、対応する行がスクロールされて画面から見えなくなっていて、クライアントで使用できない場合には、AdfUITable.findComponent(id, rowKey)メソッドによりnullが戻される可能性があることに注意してください。AdfUITable.findComponent()メソッドの戻り値にnullがないか必ず確認してください。

13 値リスト・コンポーネントの使用方法

この章では、値リスト・コンポーネントを使用して、ユーザーが値を選択できるオブジェクトのモデルドリブン・リストを表示する方法を説明します。ここでは、値リスト機能をListOfValuesデータ・モデルとともに使用するデータ・モデルの作成方法を説明します。また、inputListOfValuesコンポーネントおよびinputComboboxListOfValuesコンポーネントをページに追加する方法も説明します。

この章では、次の項目について説明します。

- 13.1項「値リスト・コンポーネントについて」

- 13.2項「ListOfValuesデータ・モデルの作成」

- 13.3項「inputListOfValuesコンポーネントの使用方法」

- 13.4項「inputComboboxListOfValuesコンポーネントの使用方法」

13.1 値リスト・コンポーネントについて

ADF Facesには、各リスト項目の複数の属性を表示でき、ユーザーがオプションで必要な項目を検索できる値リスト(LOV)入力コンポーネントが2つあります。このLOVコンポーネントは、あるオブジェクトの属性の移入に使用されるフィールドが、実際はデータベースの外部キー関係のように他のオブジェクトのリスト内に含まれる場合に有用です。たとえば、ユーザーが従業員情報を編集できるフォームがあるとします。ユーザーがまず編集する従業員レコードを探す必要のある別のページを用意するかわりに、図13-1に示すように、その検索および選択機能をフォームに組み込むことができます。

図13-1 値リスト入力フィールド

このフォームにおいて、従業員名フィールドは従業員のリストが含まれるLOVです。ユーザーがinputListOfValuesコンポーネントの検索アイコンをクリックすると、図13-2に示すように、「検索および選択」ポップアップ・ダイアログに、ユーザーが従業員を検索できる検索フィールドとともにすべての従業員が表示されます。結果表が空の場合は、独自のメッセージをresultTableファセット経由で表示できます。

図13-2 値リスト・コンポーネントの「検索」ポップアップ・ダイアログ

ユーザーがページに戻ると、図13-3に示すように、その従業員の現在の情報がフォームに表示されます。ユーザーは、データを編集して保存できます。

図13-3 LOVコンポーネントを使用して移入されたフォーム

前の図に示したように、inputListOfValuesコンポーネントはユーザーが項目を検索および選択できるポップアップ・ダイアログを表示します。リストは表に表示されます。対照的に、inputComboboxListOfValuesコンポーネントでは、ユーザーは、単純なドロップダウン・リストから選択するか、inputListOfValuesコンポーネントの場合のように検索するという2つの異なる方法で項目を選択できます。

searchContentファセットを使用して、「検索および選択」ダイアログにレンダリングするカスタム・コンテンツを作成することもできます。returnPopupDataValue属性を定義し、ユーザーが「検索および選択」ダイアログから項目を選択してダイアログを閉じたときにプログラムでこの属性に値を設定します。この値は、ReturnPopupEventからreturnPopupListenerへの戻り値になります。returnPopupListenerを実装する場合は、LOVコンポーネントとその依存コンポーネントの値の設定やカスタム・コンテンツの表示などの機能を実行できます。searchContentファセットで、表、ツリー、入力テキストなどのコンポーネントを追加して、カスタム・コンテンツを表示できます。

searchContentファセットとListOfValuesモデルの両方を実装する場合、searchContentファセットの実装は「検索および選択」ダイアログのレンダリングよりも優先されます。例13-1に、表コンポーネントを使用してカスタム・コンテンツトを表示するコードを示します。

例13-1 「検索および選択」ダイアログへのカスタム・コンテンツの追加

<af:inputListOfValues model="#{bean.listOfValuesModel}"
...
returnPopupDataValue="#{bean.returnPopupDataValue}"
returnPopupListener="#{bean.returnPopupListener}">
<f:facet name="searchContent">
<af:table id="t1" value="#{bean.listModel}" var="row"
selectionListener="#{bean.selected}"
...
</f:facet>
</af:inputListOfValues>

どちらのコンポーネントでも、オートコンプリート機能がサポートされているため、ユーザーが値の一部を入力フィールドに入力し、[Tab]を使用してフィールドから移動すると、条件の一部に一致する行がダイアログに移入されます。これを機能させるには、ユーザーが一部を入力した後に[Tab]を使用してフィールドから移動した場合に、入力した値がサーバーに戻されるロジックを実装する必要があります。サーバーでは、モデル実装により、部分的に入力された値を使用してリストがフィルタ処理され、値リストを取得する問合せが実行されます。ADF Facesには、この機能のためのAPIが用意されています。

ユーザーが部分的なエントリを入力した後でタブで移動したときにオートコンプリート機能を追加する場合は、カスタム・ポップアップを無効にする必要があります。LaunchPopupListener()コードで、launchPopupEvent.setLaunchPopup(false)を追加して、ユーザーがタブで移動したときにカスタム・ポップアップが起動しないようにします。「検索」リンクをクリックすると、「検索および選択」ダイアログが起動します。例13-2に、カスタム・ポップアップを無効にするために使用されるマネージドBean内のリスナー・コードを示します。

例13-2 カスタム・ポップアップの無効化

public void LaunchPopupListener(LaunchPopupEvent launchPopupEvent) {
if (launchPopupEvent.getPopupType().equals
(LaunchPopupEvent.PopupType.SEARCH_DIALOG)
{
...

launchPopupEvent.setLaunchPopup(false);
}
}

readOnly属性がtrueに設定されている場合、入力フィールドは無効になります。readOnlyがfalseに設定されている場合、editMode属性は許可される入力のタイプを決定します。editModeがselectに設定されている場合、値はリストから選択することでのみ入力できます。editModeがinputに設定されている場合、値は入力することもできます。

ユーザーが部分的な値を入力したときに提案される項目のリストを自動的に表示するようにLOVコンポーネントを実装することもできます。たとえば、ユーザーがAdと入力したときに、部分的にAdに一致する提案リストが、提案される項目リストとして表示されます(図13-4を参照)。一致がない場合は、「結果が見つかりません。」メッセージが表示されます。

図13-4 LOVの提案される項目リスト

図13-5に示すように、ユーザーは、このリストから項目を選択して入力フィールドに入力できます。

図13-5 選択された提案項目

af:autoSuggestBehaviorタグのsuggestItems値にリストを取得して表示するメソッドを設定して、このタグをLOVコンポーネントの内部に追加することで、自動提案動作を追加します。このメソッドはマネージドBeanに作成できます。ADFモデルを使用している場合、メソッドはデフォルトで実装されます。

LOVモデル実装で、リストをさらにフィルタ処理するスマート・リストを実装できます。両方のLOVコンポーネントのスマート・リストを実装できます。ADFモデルを使用している場合、inputComboboxListOfValuesでは、そのLOVの表示基準として定義されたスマート・リスト・フィルタを宣言的に選択できます。スマート・リストが実装され、自動提案動作も使用されている場合、自動提案は最初にスマート・リストから検索します。ユーザーが何も行わずに2秒間待機した場合、自動提案はリスト全体からも検索して結果を追加します。maxSuggestedItems属性は、返す項目の数を指定します(-1は完全なリストを示します)。maxSuggestedItems > 0の場合は、ユーザーがクリックしてLOVの「検索および選択」ダイアログを起動できる「次へ」リンクがレンダリングされます。例13-3に、自動提案動作とスマート・リストの両方を備えたLOVコンポーネントのコードを示します。

例13-3 自動提案動作とスマート・リスト

af:autoSuggestBehavior
suggestItems="#{bean.suggestItems}"
smartList="#{bean.smartList}"/>
maxSuggestedItems="7"/>

図13-6に、inputComboboxListOfValuesコンポーネントでリストを表示する方法を示します。ポップアップ・ダイアログに問合せパネルが含まれる場合や、スマート・リストが使用されていない場合は、ドロップダウン・リストの下部に「検索」リンクが表示されます。問合せパネルが使用されていない場合や、スマート・リストが有効になっている場合は、「次へ」リンクが表示されます。

図13-6 従業員名のリストが表示されたinputComboboxListOfValues

inputComboboxListOfValuesコンポーネントのドロップダウン・リストには、次の内容を表示できます。

- 完全なリスト: 図13-6に示したように、ListOfValuesModel.getItems()メソッドにより項目の完全なリストが戻されます。

- お気に入りリスト: ListOfValuesModel.getRecentItems()メソッドにより、最近選択された項目のリストが戻されます。

- 検索リンク: ポップアップの「検索および選択」ダイアログが開かれるリンク。リンクは、ドロップダウン・リストのスクロール可能なリージョンにはありません。

- customActionsファセット: その他のコンテンツを追加するためのファセット。一般的に、これには1つ以上のlinkコンポーネントが含まれます。目的のアクション(たとえば、ポップアップ・ダイアログの起動)が実行されるようにlinkのロジックを実装するのは、開発者が行います。

各行に表示される列数は、getItemDescriptors()メソッドを使用してモデルから取得できます。デフォルトではすべての列が表示されます。

inputListOfValuesコンポーネントのポップアップ・ダイアログや、inputComboboxListOfValuesコンポーネントのオプションの検索ポップアップ・ダイアログにも、新規レコードを作成する機能があります。inputListOfValuesコンポーネントの場合は、コンポーネントのcreatePopupId属性が設定されているときに表示されるtoolbarコンポーネントにbuttonがあり、作成アイコンが付いています。実行時に、buttonコンポーネントがLOVポップアップ・ダイアログに表示されます(図13-7を参照)。

図13-7 ポップアップ・ダイアログのツールバーにある作成アイコン

ユーザーが「作成」ボタンをクリックすると、新規レコードの作成に使用できるポップアップ・ダイアログが表示されます。inputComboboxListOfValuesの場合は、ツールバーではなく、「作成」というラベル付きのlinkがダイアログ下部のcustomActionsファセットに表示されます。このリンクにより、ユーザーが新規レコードを作成できるポップアップが起動されます。どちらの場合も、実際に新規レコードを作成するためのコードを入力する必要があります。

inputListOfValuesコンポーネントとinputComboboxListOfValuesコンポーネントの両方でcontextファセットがサポートされます。このファセットでは、コンテキスト情報の表示に使用できるaf:contextInfoコントロールを追加できます。ユーザーがこの領域をクリックすると、コンテキスト情報を表示するポップアップ・ウィンドウが起動します。

ヒント:

独自の作成機能を作成するかわりに、ADFビジネス・コンポーネントおよびADFデータ・バインディングを使用できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の入力表の作成に関する項を参照してください。

問合せコンポーネント同様、LOVコンポーネントもデータ・モデルに依存して機能を提供しています。このデータ・モデルはListOfValuesModelクラスです。このモデルでは、値リストの表示に表モデルが使用され、問合せモデルにアクセスしてリストの検索を実行することも可能です。LOVコンポーネントを使用するには、指定されたインタフェースをListOfValuesModelに実装する必要があります。

ヒント:

独自のListOfValuesModelクラスを作成するかわりに、ADFビジネス・コンポーネントを使用して必要な機能を作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「実行時でのユーザー・カスタマイズの許可」の章を参照してください。

ユーザーがリストで項目を選択すると、データは選択された行のオブジェクト(ここでは各オブジェクトは選択した行のrowData)のリストとして返されます。オブジェクトのリストは、選択された後でキューに入れられるReturnPopupEventイベントで入手できます。

QueryModelクラスも実装する場合は、ユーザーが検索の実行やリストのフィルタ処理に使用できるQueryコンポーネントがポップアップ・ダイアログに含まれます。LOVポップアップ・ダイアログでのQueryコンポーネントの使用に関して、次の点に注意してください。

- 保存済検索機能はサポートされていません。

- ポップアップ・ダイアログのQueryコンポーネントとその機能は、対応するQueryDescriptorクラスに基づいています。

- LOVポップアップ・ダイアログに含めることのできるコンポーネントは、query、toolbarおよびtableのみです。

ユーザーが「検索」ボタンをクリックして検索を開始すると、ListOfValuesModel.performQuery()メソッドが起動され、検索が実行されます。問合せモデルの詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

値リスト・コンポーネントを使用するのは、選択プロセスが複雑すぎて単純な選択コンポーネントでは処理できない場合です。値リスト・コンポーネントでは、アクセッサ、スマート・リスト、自動提案およびその他の機能を使用して選択リストをフィルタ処理して、リスト基準を微調整できます。ポップアップ・ウィンドウにカスタム・コンテンツを作成できます。returnPopupListenerにコードを追加して、ポップアップ・ウィンドウが閉じるときに機能を実行できます。customActionsファセットを使用して、追加のコンテンツを追加できます。作成機能により、ユーザーは新規レコードを作成できます。値リスト・コンポーネントは、データ入力を簡単にするために、データ入力機能の豊富なセットを提供します。

13.1.1 値リスト・コンポーネントの追加機能

値リスト・コンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページに値リスト・コンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。入力コンポーネントで使用できる他の機能へのリンクを次に示します。

- クライアント・コンポーネント: コンポーネントはクライアント・コンポーネントにすることができます。クライアントでコンポーネントを処理するには、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

- JavaScript API: すべての値リスト・コンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください。

- イベント: 値リスト・コンポーネントは、なんらかのロジックを実行することでアプリケーションで対応できるサーバー側とクライアント側両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。

- 検証および変換を値リスト・コンポーネントに追加できます。詳細は、第7章「入力の検証および変換」を参照してください。

- ヒントとメッセージを表示でき、値リスト・コンポーネントにオンライン・ヘルプを関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 特定の値リスト・コンポーネントをページの他のコンポーネントより前に検証することが必要になる場合があります。詳細は、5.2項「immediate属性の使用」を参照してください。

- 値リスト・コンポーネントから行った選択に基づいてページの他のコンポーネントを更新できます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

- スキンを使用してコンポーネントの外観を変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 値リスト・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- LOVコンポーネントは問合せコンポーネントを使用して検索リストに移入します。問合せコンポーネントの詳細は、第14章「問合せコンポーネントの使用方法」を参照してください。

- selectOneChoiceなど、その他のリスト・コンポーネントでも、ユーザーはリストから選択できますが、ポップアップ・ダイアログは含まれず、小規模なリストを対象としています。選択コンポーネント、リスト・ボックス・コンポーネントおよびラジオ・ボタンの詳細は、第11章「入力コンポーネントの使用およびフォームの定義」を参照してください。

- アプリケーションでADFモデルを使用する場合は、自動的にバインドされるフォームを、データ・コントロールを使用して作成できます(ADFビジネス・コンポーネントに基づくか、その他のビジネス・サービスに基づくかを問いません)。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた基本的なページの作成」の章を参照してください。

13.2 ListOfValuesデータ・モデルの作成

LOVコンポーネントを使用するには、ADF FacesのAPIを使用してLOV機能にアクセスするデータ・モデルが必要です。LOVデータ・モデルの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

13.2.1 ListOfValuesデータ・モデルの作成方法

操作を開始する前に:

値リスト・データ・モデルに関する知識が役立つ場合があります。詳細は、13.2項「ListOfValuesデータ・モデルの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、13.1.1項「値リスト・コンポーネントの追加機能」を参照してください。

ListOfValuesモデルおよび関連するイベントを作成する手順:

1. 各インタフェース・クラスの実装を作成します。表13-1にAPIを説明します。

表13-1 ListOfValuesモデルのAPI

メソッド

機能

autoCompleteValue()

コンポーネントでautoSubmitがtrueに設定されている場合、検索アイコンがクリックされるか、値が変更されてユーザーが[Tab]を使用して入力フィールドから移動するとコールされます。このメソッドにより、ダイアログを開くか、値をオートコンプリートするかが決定されます。このメソッドにより、フィルタ処理されたオブジェクトのリストが戻されます。

valueSelected(value)

値が「検索および選択」ダイアログから選択されて、「OK」ボタンがクリックされた場合にコールされます。このメソッドにより、モデルは選択された値に基づいてモデルを更新できます。

isAutoCompleteEnabled()

オートコンプリートを有効化するかどうかを決定するためにブールが戻されます。

getTableModel()

TableModelクラスの実装が戻されます。「検索および選択」ダイアログの表は、これに基づいて作成されます。

getItems()およびgetRecentItems()

コンボボックス・ドロップダウンに表示するitemsおよびrecentItemsリストが戻されます。inputComboboxListOfValuesコンポーネントでのみ有効です。inputListOfValuesコンポーネントにはnullが戻されます。

getItemDescriptors()

inputComboboxListOfValuesコンポーネントのドロップダウン・リストに表示するcolumnDescriptorsのリストを返します。

getQueryModel()およびgetQueryDescriptor()

「検索および選択」ダイアログに作成されるqueryコンポーネントに基づいてqueryModelが戻されます。

performQuery()

queryコンポーネントの検索ボタンがクリックされるとコールされます。

ListOfValuesモデルの例として、ADF FacesアプリケーションのApplication Sourcesディレクトリにある、oracle.adfdemo.view.lovパッケージのDemoLOVBeanおよびDemoComboboxLOVBeanクラスを参照してください。

2. inputListOfValuesコンポーネントの場合は、リストの移入に使用された属性にアクセスするマネージドBean (LOVモデルの作成に使用されたものと同じマネージドBeanでもかまいません)にロジックを指定します。inputComboboxListOfValuesコンポーネントでは、getItems()およびgetRecentItems()メソッドを使用してリストが戻されます。

3. InputListOfValuesコンポーネントに使用される「検索および選択」ポップアップ・ダイアログの場合、またはInputComboboxListOfValuesコンポーネントに「検索および選択」ポップアップ・ダイアログを使用する場合は、ListOfValuesModel.autoCompleteValue()およびListOfValuesModel.valueSelected()メソッドを実装します。これらのメソッドによりポップアップ・ダイアログが開かれ、コンポーネントに選択された値が適用されます。

13.3 inputListOfValuesコンポーネントの使用方法

inputListOfValuesコンポーネントでは、13.2項「ListOfValuesデータ・モデルの作成」に記載されているように、項目のリストにアクセスするために実装したListOfValuesモデルが使用されます。

13.3.1 InputListOfValuesコンポーネントの使用方法

始める前に:

inputListOfValuesコンポーネントに関する知識が役立つ場合があります。詳細は、13.3項「nputListOfValuesコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、13.1.1項「値リスト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

ページまたはページ・フラグメントを作成します。モデルに検索APIも実装すると、コンポーネントでは、ユーザーがリスト内の値を検索することもできるようになります。

inputListOfValuesコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「入力値リスト」をページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- model: 13.2.1項「ListOfValuesデータ・モデルの作成方法」で作成したように、ListOfValuesModel実装に解決されるEL式を入力します。

- value: 13.2.1項「ListOfValuesデータ・モデルの作成方法」で作成したように、リストへの移入に使用された属性値に解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性値を設定します。

- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。

- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。

- Placeholder: inputListOfValuesコンポーネントが空でフォーカスが設定されていない場合に、コンポーネントに表示されるテキストを指定します。コンポーネントにフォーカスが設定されるか、値が入力されると、プレースホルダ・テキストは非表示になります。
プレースホルダ・テキストは、ユーザーがinputListOfValuesコンポーネントに入力する必要のある内容を知らせる目的で使用されます。

このセクションの残りの属性は、他の入力コンポーネントと同じ方法で移入できます。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

4. 「動作」セクションを開き、次の属性値を設定します。

- autoSubmit: 該当するアクション(クリックやテキストの変更など)が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。

- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。このようにすると、toolbarコンポーネントが表の上に表示されます。このツールバーにはbuttonコンポーネントがあり、定義したポップアップ・ダイアログにバインドされています。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。

- launchPopupListener: ポップアップの起動時に追加の機能を提供するために実装するlaunchPopupListenerに解決されるEL式を入力します。

- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerコンポーネントに解決されるEL式を入力します。

- Usage: HTML5ブラウザでのinputListOfValuesコンポーネントのレンダリング方法を指定します。有効な値は、auto、textおよびsearchです。デフォルトはautoです。
使用方法のタイプがsearchの場合、inputListOfValuesコンポーネントはHTML5の検索入力タイプとしてレンダリングされます。一部のHTML5ブラウザでは、検索テキストの消去に使用できる「取消」アイコンが追加される場合があります。

このセクションの残りの属性は、他の入力コンポーネントと同じ方法で移入できます。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

5. ユーザーが新しい項目を作成できるようにする場合は、手順4で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

6. 「コンポーネント」ウィンドウの「操作」パネルの「動作」グループから、「自動提案動作」をドラッグし、inputListOfValuesコンポーネントに子としてドロップします。
自動提案動作を追加する場合は、immediateプロパティをtrueに設定しないでください。immediateをtrueに設定すると、リクエスト値の適用フェーズで検証が行われるため、検証エラーがある場合に提案リストが表示されないことがあります。

7. 「プロパティ」ウィンドウで、自動提案属性のそれぞれを次のとおりに入力します。

- suggestItemsメソッドに解決されるEL式。
メソッドはsuggestItemsのList<javax.model.SelectItem>を返す必要があります。メソッド・シグネチャは、List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)の形式である必要があります。

- smartListメソッドに解決されるEL式。メソッドはスマート・リスト項目のList<javax.model.SelectItem>を返す必要があります。

- 自動提案リストに表示される項目数。完全なリストを表示するには-1を入力します。

このメソッドをマネージドBeanで実装している場合、JSFページ・エントリは例13-4に示す形式である必要があります。

例13-4 LOVのautoSuggestBehaviorタグ

<af:inputListOfValues value="#{bean.value}" id="inputId">
...
<af:autoSuggestBehavior
suggestItems="#{bean.suggestItems}"
smartList="#{bean.smartList}"
maxSuggestedItems="7"/>
</af:inputListOfValues>

コンポーネントがADFモデルなどのデータ・モデルで使用される場合、suggestItemメソッドはデフォルト実装で提供される必要があります。

8. ADFモデルを使用していない場合は、suggestItemsメソッドを作成してリストを処理および表示します。suggestItemsメソッド・シグネチャを例13-5に示します。

例13-5 suggestItemsメソッド・シグネチャ

List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
oracle.adf.view.rich.model.AutoSuggestUIHints)

13.3.2 LOVコンポーネントの「検索および選択」ダイアログのスキニングに関する必知事項

デフォルトでは、inputComboboxListOfValuesおよびinputListOfValuesコンポーネントの「検索および選択」ダイアログのサイズは、レンダリング時にエンド・ユーザーが変更できます。例13-6に示すように、アプリケーションのスキン・ファイルで-tr-stretch-search-dialogセレクタ・キーをfalseに設定することにより、エンド・ユーザーがこれらのダイアログのサイズを変更できないようにできます。-tr-stretch-search-dialogセレクタ・キーのデフォルト値はtrueです。スキニングの詳細は、スキニングに関する章を参照してください。

例13-6 「検索および選択」ダイアログのサイズ変更の無効化

af|inputComboboxListOfValues{
-tr-stretch-search-dialog: false;
}
af|inputListOfValues{
-tr-stretch-search-dialog: false;
}

13.4 InputComboboxListOfValuesコンポーネントの使用方法

inputComboboxListOfValuesコンポーネントを使用すると、ユーザーはドロップダウン・リストから値を選択し、inputListOfValuesコンポーネントと同じように、ページのLOVフィールドおよび可能な場合はその他のフィールドに移入できます。ただし、リストの値を完全なリストとして表示することや、最近参照した値ごとに表示することも可能になります。問合せAPIを実装していれば、13.2項「ListOfValuesデータ・モデルの作成」で説明されているように、ポップアップ・ダイアログで検索を実行するようにコンポーネントを構成することもできます。

スキニングと「検索および選択」ダイアログのサイズ変更の詳細は、第13.3.2項「LOVコンポーネントの「検索および選択」ダイアログのスキニングに関する必知事項」を参照してください。

13.4.1 InputComboboxListOfValuesコンポーネントの使用方法

始める前に:

inputComboboxListOfValuesコンポーネントに関する知識が役立つ場合があります。詳細は、13.4項「InputComboboxListOfValuesコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、13.1.1項「値リスト・コンポーネントの追加機能」を参照してください。

inputComboboxListOfValuesコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、入力値リスト(コンボボックス)をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- model: 13.2.1項「ListOfValuesデータ・モデルの作成方法」で作成したように、ListOfValuesModel実装に解決されるEL式を入力します。

- value: 13.2.1項「ListOfValuesデータ・モデルの作成方法」で作成したように、リストへの移入に使用された属性値に解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性値を設定します。

- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。

- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。

- Placeholder: inputComboboxListOfValuesコンポーネントが空でフォーカスが設定されていない場合に、コンポーネントに表示されるテキストを指定します。コンポーネントにフォーカスが設定されるか、値が入力されると、プレースホルダ・テキストは非表示になります。
プレースホルダ・テキストは、ユーザーがinputComboboxListOfValuesコンポーネントに入力する必要のある内容を知らせる目的で使用されます。

このセクションの残りの属性は、他の入力コンポーネントと同じ方法で移入できます。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

4. 「動作」セクションを開き、次の属性値を設定します。

- autoSubmit: 該当するアクション(クリックやテキストの変更など)が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。

- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。このようにすると、toolbarコンポーネントが表の上に表示されます。このツールバーにはbuttonコンポーネントがあり、定義したダイアログにバインドされています。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。

- launchPopupListener: ポップアップ・ダイアログが開かれる際に追加の機能を提供するために実装するlaunchPopupListenerハンドラに解決されるEL式を入力します。

- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerハンドラに解決されるEL式を入力します。

- Usage: HTML5ブラウザでのinputComboboxListOfValuesコンポーネントのレンダリング方法を指定します。有効な値は、auto、textおよびsearchです。デフォルトはautoです。
使用方法のタイプがsearchの場合、inputComboboxListOfValuesコンポーネントはHTML5の検索入力タイプとしてレンダリングされます。一部のHTML5ブラウザでは、検索テキストの消去に使用できる「取消」アイコンが追加される場合があります。

このセクションの残りの属性は、他の入力コンポーネントと同じ方法で移入できます。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。

5. launchPopupListenerを使用している場合は、LaunchPopupEventクラスのgetPopupType()メソッドを使用してイベントのソースを区別できます。getPopupType()は、イベントが「LOV検索および選択」ダイアログを起動した結果である場合にDROPDOWN_LISTを返し、イベントがユーザーによるダイアログでの「検索」ボタンのクリックの結果である場合にSEARCH_DIALOGを返します。

6. ユーザーが新しい項目を作成できるようにする場合は、手順5で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

7. 「コンポーネント」ウィンドウの「操作」パネルの「動作」グループから、「自動提案動作」をドラッグし、inputComboboxListOfValuesコンポーネントに子としてドロップします。
自動提案動作を追加する場合は、immediateプロパティをtrueに設定しないでください。immediateをtrueに設定すると、リクエスト値の適用フェーズで検証が行われるため、検証エラーがある場合に提案リストが表示されないことがあります。

8. 「プロパティ」ウィンドウで、自動提案属性のそれぞれを次のとおりに入力します。

- suggestItemsメソッドに解決されるEL式。
メソッドはsuggestItemsのList<javax.model.SelectItem>を返す必要があります。メソッド・シグネチャは、List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)の形式である必要があります。

- smartListメソッドに解決されるEL式。メソッドはスマート・リスト項目のList<javax.model.SelectItem>を返す必要があります。

- 自動提案リストに表示される項目数。完全なリストを表示するには-1を入力します。

このメソッドをマネージドBeanで実装している場合、JSFページ・エントリは例13-7に示す形式である必要があります。

例13-7 LOVのautoSuggestBehaviorタグ

<af:inputComboboxListOfValues value="#{bean.value}" id="inputId">
...
<af:autoSuggestBehavior
suggestItems="#{bean.suggestItems}"
smartList="#{bean.smartList}"
maxSuggestedItems="7"/>
</af:inputComboboxListOfValues>

コンポーネントがADFモデルなどのデータ・モデルで使用される場合、suggestItemメソッドはデフォルト実装で提供される必要があります。

9. コンポーネントをADFモデルとともに使用していない場合は、suggestItemsメソッドを作成してリストを処理および表示します。suggestItemsメソッド・シグネチャを例13-8に示します。

例13-8 suggestItemsメソッド・シグネチャ

List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
oracle.adf.view.rich.model.AutoSuggestUIHints)

14 問合せコンポーネントの使用方法

この章では、queryおよびquickQuery検索パネル・コンポーネントの使用方法を説明します。queryコンポーネントを構成して検索基準を指定する方法、検索基準を動的に追加および削除する方法、および保存済検索を作成およびパーソナライズする方法を説明します。また、quickQueryコンポーネントを構成してページに追加する方法も説明します。

この章では、次の項目について説明します。

- 14.1項「問合せコンポーネントについて」

- 14.2項「問合せデータ・モデルの作成」

- 14.3項「quickQueryコンポーネントの使用方法」

- 14.4項「queryコンポーネントの使用方法」

14.1 問合せコンポーネントについて

queryおよびquickQueryコンポーネントは、データ・セットの検索に使用されます。queryコンポーネントには、一連の包括的な検索基準およびコントロールが用意されており、quickQueryコンポーネントは、単一基準での検索に使用できます。

queryコンポーネントでは、次の機能がサポートされています。

- 複数の検索基準に対する選択および検索

- 基準アイテムの動的な追加および削除

- 単一基準に関連付けられている検索演算子の選択

- すべてに一致またはいずれかに一致論理積の選択

- 基本または拡張モードでの表示

- 保存済検索の作成

- 保存済検索のパーソナライズ

queryコンポーネントの拡張モードを使用すると、デフォルトで、ユーザーは現在表示されている検索に基準アイテムを追加および削除できるようになります。ただし、基本モードで特定の機能を非表示(および拡張モードでのみ表示)にできる独自のQueryModelクラスを実装できます。たとえば、拡張モードでのみ演算子を表示することや、拡張モードでは基本モードより多くの基準を表示することができます。

通常、問合せの結果は表またはツリー表に表示され、queryコンポーネントのresultComponentId属性を使用して識別されます。ただし、その他の出力コンポーネントに結果を表示することもできます。結果を表示するように構成されているコンポーネントは、検索が実行されると自動的にレンダリングされます。

図14-1に、検索条件が3つある拡張モードのqueryコンポーネントを示します。

図14-1 検索条件が3つあるqueryコンポーネント

基準がすでに決定されており、ユーザーがそこから選択できるシード済検索を作成することも、ユーザーが基準を追加してそれらの検索を保存できるようにすることも可能です。たとえば、例14-1に従業員のシード済検索を示します。ユーザーは、検索が実行される基準に値を入力できます。また、オペランド(次より大きい、次と等しい、次より小さい)や、論理積(ANDまたはOR問合せを作成する、すべてに一致またはいずれかに一致)も選択できます。ユーザーは「フィールドの追加」ドロップダウン・リストをクリックして1つ以上の基準を追加し、その検索を保存できます。アプリケーションが永続性を使用するように構成されている場合は、それらの検索基準を選択されたオペランドと論理積とともに保存し、指定された検索名を使用して再アクセスできます(永続性の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください)。

quickQueryコンポーネントは、queryコンポーネントを簡略化したバージョンです。ユーザーは、ドロップダウン・リストから選択して、任意の検索可能属性の検索を実行できます。図14-2に、水平レイアウトのquickQueryコンポーネントを示します。

図14-2 水平レイアウトのquickQueryコンポーネント

queryおよびquickQueryコンポーネントのどちらでも、検索の定義および実行にQueryModelクラスが使用されます。ユーザーが実行できるようにする特定の各検索に、関連するQueryModelクラスを作成します。

ヒント:

独自のQueryModel実装を作成するかわりに、必要な機能を提供するADFビジネス・コンポーネントを使用できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFによるデータバインドされた検索フォームの作成」の章を参照してください。

QueryModelクラスは、一連の検索基準を定義するQueryDescriptorオブジェクトを管理します。QueryModelクラスでは、QueryDescriptorオブジェクトの作成、削除および更新が行われます。QueryModelクラスでは、シード済検索およびユーザーがパーソナライズした検索の両方の保存済検索も取得されます。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

一連の検索基準アイテムのそれぞれにQueryDescriptorクラスを作成する必要があります。QueryDescriptorクラスでは、各シード済検索の作成に必要な基準および論理積へのアクセスが行われます。また、エンド・ユーザーのアクションに応じた、基準の動的な追加、削除、または追加と削除も実行されます。QueryDescriptorクラスにも、モードや自動実行などの様々なUIヒントがあります。詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。1つのQueryModelクラスで、複数のQueryDescriptorオブジェクトを管理できます。

ユーザーが新しい保存済検索を作成すると、その保存済検索用に新しいQueryDescriptorオブジェクトが作成されます。ユーザーは、削除、選択、リセットおよび更新など、保存検索で様々な操作を実行できます。検索が実行または変更されると、適切なQueryModelメソッドがコールされて正しいQueryDescriptorオブジェクトが戻されるのみでなく、リクエスト値の適用フェーズ中にQueryOperationEventイベントがブロードキャストされます。このイベントは、JSFライフサイクルのアプリケーションの起動フェーズ中に、QueryOperationListenerハンドラにより使用されます。QueryOperationEventイベントでは、QueryDescriptorオブジェクトが引数として使用され、リスナーに渡されます。ADF Facesには、デフォルトでそのリスナーが実装されています。リスナーで実行される内容の詳細は、表14-2を参照してください。

たとえば、保存済検索の更新は、QueryModelのupdate()メソッドをコールすることで完了します。QueryOperationEventイベントがキューイングされ、更新操作に関連するモデル情報の変更処理を実行するQueryOperationListenerハンドラによって使用されます。

QueryOperationEventイベントを生成する問合せ操作のアクションは、次のとおりです。

- 検索の保存

- 保存済検索の削除

- 基本モードおよび拡張モードの切替え

- 保存済検索のリセット

- 別の保存済検索の選択

- 保存済検索の更新

- 依存基準がある基準の値の更新

AttributeCriterionクラスのhasDependentCriterionメソッドは、基準に依存関係があるかどうかを確認するためにコールできます。デフォルトでは、このメソッドはfalseを返しますが、基準に依存基準がある場合はtrueを返します。その基準の値が変更されると、QueryOperationEventがJSFライフサイクルのモデル値の更新フェーズ用にキューイングされます。モデルには、モデルのルート基準に入力された値に基づき、依存基準の値を更新するためのリスナーが必要です。

14.1.1 問合せコンポーネントのユースケースと例

問合せコンポーネントは、アプリケーションのニーズに対応するために様々なモードで使用できます。シード済検索で構成し、カスタマイズおよびパーソナライズ機能を提供できます。問合せコンポーネントは、エンタープライズ検索機能の実装に使用できる機能豊富なコンポーネントです。

問合せおよびクイック問合せコンポーネントを使用して、複雑なトランザクション検索フォームを作成できます。問合せコンポーネントはモデルドリブンであり、多くの機能および表示オプションを提供します。クイック問合せコンポーネントはフットプリントが小さく、1つの属性での標準検索を提供します。問合せコンポーネントはフットプリントがより大きくなりますが、複数条件の検索とその他の検索機能を提供します。

14.1.2 問合せコンポーネントの追加機能

問合せコンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページに問合せまたはクイック問合せコンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。問合せコンポーネントで使用できる他の機能へのリンクを次に示します。

- すべての問合せコンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください。

- ヒントとメッセージを表示でき、問合せコンポーネントにオンライン・ヘルプを関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- スキンを使用してコンポーネントの外観を変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 問合せコンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- アプリケーションでADFモデルを使用する場合は、自動的にバインドされる検索フォームを、データ・コントロールを使用して作成できます(ADFビジネス・コンポーネントに基づくか、その他のビジネス・サービスに基づくかを問いません)。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた検索フォームの作成」の章を参照してください。

14.2 問合せデータ・モデルの作成

queryコンポーネントを使用するには、まずQueryModelクラスを作成する必要があります。問合せデータ・モデルの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

ヒント:

quickQueryコンポーネントは、QueryModelクラスを実装せずに使用できます。ただし、マネージドBeanにいくつかのロジックを追加する必要があります。詳細は、14.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

問合せコンポーネントには、UIXQueryコンポーネントに対するrefresh()メソッドがあります。このメソッドは、モデル定義が変更され、問合せコンポーネントをリフレッシュする必要がある場合(つまり、すべての子が削除されて再作成された場合など)にコールする必要があります。新しい基準をQueryDescriptorに追加したか既存の基準を削除したときに、基礎となるモデルがコンポーネントのサブツリーで予期されるのとは異なる基準オブジェクトのコレクションを返す場合は、このメソッドをコールする必要があります。QueryOperationListener、QueryListenerおよびActionListenerは、すべてこのメソッドをコールする必要があります。問合せコンポーネント自体は、アプリケーションの起動フェーズの最後にフラッシュされます。このメソッドは、レスポンスのレンダリング・フェーズ中に呼び出された場合は実行されません。

実装での必要事項の理解に役立つように、表14-1および表14-2に、図14-3に表示されているUIコンポーネントの機能と対応するインタフェースとのマッピングを示します。

図14-3 問合せコンポーネントおよび関連するポップアップ・ダイアログ

表14-1に、queryコンポーネントにレンダリングされたUIアーティファクト、関連するクラス、クラス・プロパティ、およびアーティファクトが使用するメソッドを示します。

表14-1 問合せのUIアーティファクトおよび関連するモデル・クラスの操作とプロパティ

UIアーティファクト

使用されるクラスのプロパティ/メソッド

コメント

1

「検索」パネル

QueryDescriptorインスタンスは、パネルに表示される項目を作成します。

保存済検索に基づきます。

2

表示アイコン

検索パネルを開閉します。

3

「一致」タイプ・ラジオ・ボタン

ConjunctionCriterionクラスのgetConjunction()メソッドを介して使用できます。

問合せが実行されると、検索フィールド間に使用するデフォルトの論理積が表示されます。デフォルトが設定されていて、それがすべての検索フィールドで同一の場合、選択された状態で表示されます。検索フィールドが、フィールド間に異なる論理積を使用するように構成されている場合、UIで値は選択されません。

たとえば、All連結タイプがすべての検索フィールド間に使用されている場合は、Allが選択された状態で表示されます。AllとAnyが混在している場合は、ラジオ・ボタンは何も選択されずに表示されます。

conjunctionReadOnlyプロパティがtrueに設定されている場合、一致タイプは読取り専用になります。displayMode属性がsimpleに設定されている場合には、レンダリングされません。

4

検索フィールドのグループ

QueryDescriptorオブジェクトの検索フィールドのコレクションはConjunctionCriterionオブジェクトで表され、QueryDescriptorクラスのメソッドgetConjunctionCriterion()により戻されます。getCriterionList()メソッドは、List<Criterion>リストを戻します。

現在の選択された検索に関連付けられた1つ以上の検索フィールドが表示されます。

5

検索フィールド

AttributeCriterionクラスは、検索フィールド・インスタンスに固有の情報を指定します。AttributeCriterionオブジェクトは、ConjunctionCriterionクラスのgetCriterionList()メソッドにより戻されるList<Criterion>リストの項目です(4を参照)。

AttributeDescriptorクラスは、検索フィールドに関連する静的な情報を提供します。これは、AttributeCriterionクラスのメソッドgetAttribute()を介して使用できます。

AttributeDescriptorクラスのgetConverter()メソッドをオーバーライドして、javax.faces.convert.Converterタイプのコンバータ・オブジェクトを返すことができます。定義されている場合、属性値はこのコンバータ・インスタンスを使用して変換されます。デフォルトの戻り値はnullです。

AttributeCriterionクラスのhasDependentCriterionメソッドは、基準に依存関係がある場合にtrueを返します。基準に依存関係がある場合、依存する基準フィールドはこの基準の値が変更されたときにリフレッシュされます。デフォルトでは、このメソッドはfalseを返します。

各検索フィールドには、ラベル、演算子、1つ以上の値コンポーネント(入力テキスト・コンポーネントなど)およびオプションの削除アイコンが含まれます。これらのレンダリングに必要な情報は、(保存済検索の)検索フィールドのインスタンスに固有の情報か、どの保存済検索に含まれているかに関係なく汎用的で不変な情報です。

たとえば、従業員ビジネス・オブジェクトに検索フィールドEmployee NameおよびSalaryが含まれるとします。

ユーザーは、Low Salaried EmployeeおよびHigh Salaried Employeesという名前の2つの異なる検索を構成できます。どちらの検索にも、EmployeeおよびSalary属性に基づいて2つの検索フィールドが含まれます。どちらの保存済検索もEmployeeオブジェクトの同じ属性に基づいていますが、Salary検索フィールドは、Low Salaried Employees検索の場合にはデフォルトの演算子が「次より小さい」で値が「50000.00」になるように構成されており、High Salaried Employees検索の場合にはデフォルトの演算子が「次より大きい」で値が「100000.00」になるように構成されています。UIで保存済検索を選択すると、その検索に適切な演算子と値が表示されます。

ユーザーが選択した検索に関係なく、Salaryの検索フィールドには数値コンポーネントがレンダリングされ、ラベルにはSalaryが表示されている必要があります。

6

「保存済の検索」ドロップダウン

システム検索およびユーザーの保存済検索は、QueryModelクラスのメソッドgetSystemQueries()およびgetUserQueries()を介して使用できます。

使用可能なシステム検索およびユーザーの保存済検索のリストが表示されます。保存済の検索は、アルファベット順に示されます。

saveQueryModeプロパティがdefaultに設定されている場合は、「パーソナライズ」オプションも追加されます。このオプションを選択すると、ユーザーが保存済検索をパーソナライズできる「パーソナライズ」ダイアログが開かれます。ユーザーは、既存の保存済検索を複製または更新できます。

表14-2に、様々なUIアーティファクトの動作と、その動作を実行するために起動される関連するメソッドを示します。

表14-2 UIアーティファクトの動作および関連するメソッド

UIアーティファクト

起動されるクラス・メソッド

生成されるイベント

コメント

7

「削除」アイコン

アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドremoveCriterion()が自動的にコールされます。

ActionEvent

現在のQueryDescriptorオブジェクトから検索フィールドが削除されます。

8

「検索」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

モデル値の更新フェーズ中に、選択された演算子および検索フィールドに入力された値が、演算子および値コンポーネントに追加されたEL式を使用するモデルに自動的に更新されます(詳細は、14.4.1項「queryコンポーネントの追加方法」を参照してください)。これらの式により、AttributeCriterionクラスでget/setOperator()、get/setOperators()およびgetValues()メソッドがそれぞれ起動されます。

アプリケーションの起動フェーズ中に、queryコンポーネントに登録されているQueryListenerが起動され、検索が実行されます。

このリスナーを実装する必要があります。

QueryEvent

常にフッターにレンダリングされます(displayMode属性がsimpleに設定されている場合、フッターのコンテンツはレンダリングされません)。

選択演算子と選択された「一致」ラジオ、および各検索フィールドに入力された値を使用して問合せが実行されます(選択が行われない場合はデフォルトが使用されます)。

9

「リセット」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent.
Operation.RESET操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドreset()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを元の状態にリセットするには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

検索フィールドが、前に保存されていた状態にリセットされます。

10

「保存」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent.
Operation.SAVE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドcreate()がコールされます。create()メソッドへのコール後に、update()メソッドがコールされ、新しい保存済検索に(ダイアログ内でユーザーにより選択された)ヒントが保存されます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数に基づいて新しいオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

ユーザーにより追加された新しい検索フィールドも含め、現在の保存済検索の設定に基づいて新しい保存済検索が作成されます。

11

「フィールドの追加」ドロップダウン・リスト

アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドaddCriterion()が自動的にコールされます。AttributeDescriptorオブジェクト(名前引数で識別される)に基づいて新しいAttributeCriterionオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。

ActionEvent

既存の保存済検索に、検索フィールドとして属性が追加されます。

12

モード(「基本」または「拡張」)ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent.
Operation.MODE_CHANGE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドchangeMode()がコールされます。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

モード・ボタンをクリックすると、モードが切り替わります。

13

「削除」ボタン

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドdelete()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを削除するには、このメソッドをオーバーライドする必要があります。

ActionEvent

現在使用中でなければ、選択された保存済検索が削除されます。

14

「複製」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中に、QueryOperationEventイベントがQueryOperationEvent.
Operation.DUPLICATE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドupdate()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数を使用してQueryDescriptorオブジェクトを更新するには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listener)。

選択されている保存済検索を複製します。

15

「適用」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent.
Operation.UPDATE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドupdate()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数を使用してQueryDescriptorオブジェクトを更新するには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listener)。

選択された保存済検索に行われた変更が適用されます。

16

「OK」ボタン

「適用」ボタンと同じです。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

選択された保存済検索に行われた変更が適用され、その後ダイアログが終了されます。

17

「取消」ボタン

このアクションにはメソッドが定義されていません。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

ダイアログ内で行われた編集が取り消されます。

14.2.1 問合せデータ・モデルの作成方法

操作を開始する前に:

問合せデータ・モデルに関する知識が役立つ場合があります。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

問合せモデル・クラスを作成する手順:

1. 各インタフェース・クラスの実装を作成します。QueryModelクラスを1つ実装してから、システムの各シード済検索用の適切な基準(演算子および値)が指定されたQueryDescriptorクラスを実装します。問合せに対する様々なモデル・クラスの実装の例は、ADF Facesのサンプル・アプリケーションのoracle.adfdemo.view.query.richパッケージにあるクラスを参照してください。

注意:

問合せに構成(AttributeCriterion/ConjunctionCriterionを含むConjunctionCriterion 1...nなど)が使用されている場合、この関係が抽象インタフェースによって強制されることはありません。実装で、アソシエーションに構成を使用するかどうか、およびそれらのオブジェクトのライフサイクルをどのように管理するかを決定する必要があります。

2. QueryEventイベント(queryコンポーネントのボタンにより参照される)をリスニングするマネージドBeanに、QueryListenerハンドラ・メソッドを作成します。このリスナーにより、QueryModelの適切なAPIが起動され、問合せが実行されます。例14-1に、検索基準のString表現を構成する基本のQueryListener実装のリスナー・メソッドを示します。このStringは、検索結果として表示されます。

例14-1 QueryListenerハンドラ・メソッド

public void processQuery(QueryEvent event)
{
DemoQueryDescriptor descriptor = (DemoQueryDescriptor) event.getDescriptor();
String sqlString = descriptor.getSavedSearchDef().toString();
setSqlString(sqlString);
}

14.3 quickQueryコンポーネントの使用方法

quickQueryコンポーネントには、検索する属性をユーザーが選択できるドロップダウン・リストが1つ含まれています。使用できる検索可能属性は、モデルの実装またはマネージドBeanから導出されます。ユーザーは、選択した属性またはすべての属性を検索できます。

quickQueryコンポーネントは、queryコンポーネントを使用した、より複雑な検索の開始点として使用できます。たとえば、ユーザーはある属性に対してクイック問合せ検索を実行し、成功した場合により複雑な検索に進むことができます。quickQueryコンポーネントは、ユーザーがquickQueryコンポーネントからqueryコンポーネントに切り替えられるようにするマネージドBeanのメソッドにバインドできるコマンド・コンポーネントをendファセットに配置できるようにすることで、これをサポートします。

quickQueryコンポーネントはドロップダウン・リストに検索可能な基準をレンダリングし、実行時に選択された基準のタイプに応じて、quickQueryコンポーネントは属性タイプに基づいて別の基準フィールドをレンダリングします。たとえば、属性タイプがNumberの場合、inputNumberSpinboxコンポーネントがレンダリングされます。問合せに完全なモデルを実装しているかぎり、これらのコンポーネントを追加する必要はありません。マネージドBeanにロジックが設定されていて、完全なモデルが必要ない場合は、手動でquickQueryコンポーネント・アーティファクトを作成します。詳細は、14.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

14.3.1 モデルを使用したquickQueryコンポーネントの追加方法

始める前に

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.3項「quickQueryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

QueryModelクラスおよび関連クラスを作成します。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

quickQueryコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「クイック問合せ」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- id: コンポーネントの一意のIDを入力します。

- layout: 基準と値が隣接した状態でコンポーネントを水平に表示するか(図14-2)、垂直に表示するか(図14-4)を指定します。

図14-4 垂直に表示するよう設定されたquickQueryコンポーネント

- model: 14.2項「問合せデータ・モデルの作成」で作成した、QueryModelクラスを実装するクラスに評価されるEL式を入力します。

- value: 14.2項「問合せデータ・モデルの作成」で作成した、QueryDescriptorクラスを実装するクラスに評価されるEL式を入力します。

3. 「動作」セクションを開き、次の属性を設定します。

- conjunctionReadOnly: ユーザーが「いずれかに一致」または「すべてに一致」ラジオ・ボタンを設定できるようにするかどうかを指定します。falseに設定すると、ユーザーは論理積を設定できます。trueに設定すると、ラジオ・ボタンはレンダリングされません。

- queryListener: 14.2項「問合せデータ・モデルの作成」で作成したQueryListenerハンドラに評価されるEL式を入力します。

4. ページに表(または検索結果を表示するその他のコンポーネント)をドラッグ・アンド・ドロップします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

5. ユーザーが「拡張」リンクをクリックしたときにquickQueryコンポーネントが完全なqueryコンポーネントに切り替わるようにするには、リンク・コンポーネントのロジックをquickQueryコンポーネントのEndファセットの中で実装します。このロジックで、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示してください。

14.3.2 モデルなしでのquickQueryコンポーネントの使用方法

たとえば、すべての問合せロジックが検索を実行して結果を返すQueryListenerハンドラなどの単純なマネージドBeanに存在する場合は、モデルなしでquickQueryコンポーネントを使用できます。完全なquickQueryコンポーネントの作成に必要なコンポーネントを手動で追加およびバインドする必要があります。

始める前に:

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.3項「quickQueryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

quickQueryコンポーネントを追加する手順:

1. マネージドBeanに、ユーザーが検索できる属性を表示するselectOneChoiceコンポーネントのvalueChangeListenerハンドラを作成します。valueChangeListenerハンドラは、検索する属性の選択を処理します。

2. マネージドBeanに、検索を実行するQueryListenerハンドラを作成します。このハンドルでは、問合せを実行するコンポーネントおよび値の取得に、検索基準値の入力に使用される入力コンポーネントのIDが使用されます。

3. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「クイック問合せ」をドラッグしてページにドロップします。

4. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- id: コンポーネントの一意のIDを入力します。

- layout: 基準と値が隣接した状態でコンポーネントを水平に表示するか(図14-2)、垂直に表示するか(図14-4)を指定します。

5. 「動作」セクションを開いて、QueryListener属性を、手順2で作成したQueryListenerハンドラに解決されるEL式に設定します。

6. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「選択」をドラッグしてquickQueryコンポーネントのcriteriaItemsファセットにドロップします。ダイアログで、ユーザーが検索できる属性のリストに評価されるEL式を入力するか、静的なリストを入力するかを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

7. 構造ウィンドウでcriteriaItemsファセットのselectOneChoiceコンポーネントを選択し、次の属性を設定します。

- simple: コンポーネントのラベルを表示しない場合はtrueに設定します。

- valueChangeListener: 手順1で作成したリスナーに評価されるEL式を入力します。

- autoSubmit: trueに設定します。

8. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「アイテムの選択」をselectOneChoiceにドラッグします。追加できる数の上限はありません。selectOneChoiceおよびselectItemsコンポーネントの使用方法の詳細は、11.6項「選択コンポーネントの使用方法」を参照してください。

9. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、inputTextコンポーネントをquickQueryコンポーネントに直接の子としてドラッグします。次の属性を設定します。

- simple: ラベルを表示しない場合はtrueに設定します。

- value: ユーザーが入力する値を含むプロパティに評価されるEL式を入力します。

ヒント:

inputTextコンポーネントを追加しない場合は、実行時に、無効化されたinputTextコンポーネントおよび無効化された実行アイコンがレンダリングされます。

10. ユーザーが「拡張」リンクをクリックしたときにquickQueryコンポーネントが完全なqueryコンポーネントに切り替わるようにするには、リンク・コンポーネントのロジックをquickQueryコンポーネントのEndファセットの中で実装します。このロジックで、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示してください。

11. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、table (または検索結果を表示するその他のコンポーネント)をページにドラッグします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

14.3.3 実行時の処理: フレームワークによりquickQueryコンポーネントがレンダリングされて検索が実行される仕組み

quickQueryコンポーネントがQueryDescriptorオブジェクトにバインドされている場合、selectOneChoiceおよびinputTextコンポーネントは、実行時にページがレンダリングされる際に自動的に追加されます。ただし、独自のコンポーネントを追加することもできます。検索可能属性を表示するコンポーネントとinputTextコンポーネントの両方を追加する場合、コンポーネントから名前/値ペアを取得するにはQueryListenerハンドラが必要です。

検索可能属性の表示に独自のコンポーネントのみを使用する場合(およびデフォルトの入力テキスト・コンポーネントを使用する場合)は、フレームワークにより入力テキスト・コンポーネントが表示されます。問合せを実行するには、QueryListenerハンドラが、ドロップダウン・リストから属性名を、QueryDescriptor.getCurrentCriterion()メソッドから値を取得するように設定する必要があります。

検索可能属性値の収集に独自のコンポーネントのみを使用する場合(および属性名の指定にデフォルトのselectOneChoiceコンポーネントを使用する場合)は、フレームワークによりselectOneChoiceコンポーネントが表示されます。QueryListenerハンドラが、QueryDescriptor.getCurrentCriterion()メソッドから属性名を、コンポーネントから値を取得するように設定する必要があります。

QuickQueryコンポーネントのvalue属性をQueryDescriptorオブジェクトにバインドせず、両方のコンポーネントを使用することを選択した場合、「移動」ボタンがクリックされると、フレームワークによりQueryDescriptorオブジェクトのないQueryEventイベントがキューイングされます。その後、指定されたQueryListenerハンドラにより、名前へのアクセスにchangeValueListenerハンドラが使用され、値へのアクセスに入力コンポーネントが使用されて問合せが実行されます。selectOneChoiceコンポーネントから属性名を取得し、inputTextコンポーネントから属性値を取得して問合せを実行するには、QueryListenerハンドラを実装する必要があります。

14.4 queryコンポーネントの使用方法

queryコンポーネントは、フル機能検索に使用されます。基本および拡張モードがあり、ユーザーはボタンをクリックすることで切替えできます。

基本モード問合せの機能は次のとおりです。

- 選択可能な検索条件演算子のドロップダウン・リスト

- ANDまたはOR(すべて一致または一部一致)とともに使用する選択可能なWHERE句

- 保存済(シード済)検索

- パーソナライズされた保存済検索

拡張モードの問合せフォームにも、検索可能属性のリストから選択することで、ユーザーが動的に検索条件を追加できる機能があります。ユーザーは、追加された任意の条件を後から削除できます。

ユーザーは、演算子のドロップダウン・リストから選択して、検索用に問合せを作成できます。入力フィールドは、値リスト(LOV)、数値スピナー、日付チューザ、あるいはその他の入力コンポーネントとして構成されます。

リストの複数項目の選択をサポートするには、モデルでviewCriteriaItemにコントロール・ヒントを表示し、基礎となる属性を、対応する表示オブジェクト内のLOVとして定義する必要があります。ヒントは、複数選択またはin演算子機能を有効または無効にするために使用されます。複数選択が有効になっている場合に、EqualsまたはDoes not equal演算子を選択すると、検索基準フィールドがselectManyChoiceコンポーネントとしてレンダリングされます。ユーザーは、リストから複数の項目を選択できます。

検索基準フィールドのコンポーネントは、基礎となる属性のデータ型、選択されている演算子、および複数選択が有効になっているかどうかによって異なります。たとえば、Contains演算子が選択されているString型の属性の検索フィールドは、表14-3に示されているように、inputTextコンポーネントとしてレンダリングされます。

演算子がEqualsまたはDoes not equalであり、複数選択が有効になっていない場合、コンポーネントは、モデルの「デフォルトのリスト・タイプ」ヒントで指定されているコンポーネントにデフォルトで設定されます。

表14-3 String型の検索基準フィールドのレンダリング済コンポーネント

演算子

コンポーネント

複数選択が有効な場合のコンポーネント

Starts with

af:inputText

af:inputText

Ends with

af:inputText

af:inputText

Equals

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Does not equal

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Contains

af:inputText

af:inputText

Does not contain

af:inputText

af:inputText

Is blank

なし

なし

Is not blank

なし

なし

基礎となる属性がNumberデータ型の場合にレンダリングされるコンポーネントを、表14-4に示します。

表14-4 Number型の検索基準フィールドのレンダリング済コンポーネント

演算子

コンポーネント

複数選択が有効な場合のコンポーネント

Equals

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Does not equal

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Less than

af:inputNumberSpinBox

af:inputNumberSpinBox

Less than or equal to

af:inputNumberSpinBox

af:inputNumberSpinBox

Greater than

af:inputNumberSpinBox

af:inputNumberSpinBox

Greater than or equal to

af:inputNumberSpinBox

af:inputNumberSpinBox

Between

af:inputNumberSpinBox

af:inputNumberSpinBox

Not between

af:inputNumberSpinBox

af:inputNumberSpinBox

Is blank

なし

なし

Is not blank

なし

なし

基礎となる属性がDateデータ型の場合にレンダリングされるコンポーネントを表14-5に示します。

表14-5 Date型の検索基準フィールドのレンダリング済コンポーネント

演算子

コンポーネント

複数選択が有効な場合のコンポーネント

Equals

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Does not equal

デフォルトのリスト・タイプ・ヒント

af:selectManyChoice

Before

af:inputDate

af:inputDate

After

af:inputDate

af:inputDate

On or before

af:inputDate

af:inputDate

On or after

af:inputDate

af:inputDate

Between

af:inputDate (2)

af:inputDate (2)

Not between

af:inputDate (2)

af:inputDate (2)

Is blank

なし

なし

Is not blank

なし

なし

検索基準の基礎となる属性がLOVとして定義されている場合、オートコンプリート機能を有効にするには、AttributeCriterionクラスのgetModelListメソッドから返されるListOfValuesモデル・インスタンスで、そのisAutoCompleteEnabledメソッドに対してtrueを返す必要があります。LOVの詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

autoSubmitがtrueに設定されている場合、検索基準での値の変更は、すぐにモデルにプッシュされます。queryコンポーネントは、依存基準がある場合のみ、その基準リストを自動的にフラッシュします。基準インスタンスに依存基準がなく、autoSubmitがtrueに設定されている場合、queryコンポーネントは部分的にのみリフレッシュされます。

「すべてに一致」または「いずれかに一致」ラジオ・ボタン・グループで、問合せをさらに変更できます。「すべてに一致」を選択すると、基本的にAND関数になります。問合せでは、選択した条件にすべて一致する行のみが返されます。「いずれかに一致」を選択すると、OR関数になります。問合せでは、基準アイテムのいずれか1つに一致するすべての行が返されます。

すべての検索基準の値(null値を含む)を入力して「すべてに一致」または「いずれかに一致」ラジオ・ボタンを選択した後、ユーザーは「検索」ボタンをクリックして問合せを開始できます。問合せ結果は、出力コンポーネントに表示できます。通常、出力コンポーネントは表またはツリー表ですが、resultComponentId属性に指定することで、af:forms、af:outputTextおよび図形など、その他の表示コンポーネントを結果コンポーネントとして関連付けることができます。

「基本」または「拡張」ボタンが有効化および表示されている場合、ユーザーは2つのモードを切り替えられます。各モードでは、そのモードに定義された検索条件のみが表示されます。検索条件フィールドは、基本のみ、拡張のみ、または両方のモードで表示されるように定義できます。

拡張モードでは、コントロール・パネルにも、検索可能属性のポップアップ・リストを表示する「フィールドの追加」ボタンが含まれます。ユーザーがこれらの属性のいずれかを選択すると、動的に生成された検索条件の入力フィールドおよびドロップダウンの演算子のリストが表示されます。すべての検索条件入力フィールドおよび新しく追加されたフィールドの位置は、モデル実装により決定されます。

この新しく作成された検索条件フィールドでも、隣に削除アイコンが表示されます。ユーザーは、後からこのアイコンをクリックして、追加したフィールドを削除できます。初めから定義されていた検索条件フィールドは、削除アイコンがないため、ユーザーが削除することはできません。図14-5に、「Salary」という名前の動的に追加された検索基準フィールドがある拡張モードのqueryコンポーネントを示します。フィールドの隣にある削除アイコン(X)に注目してください。

図14-5 動的に追加された検索規準のある拡張モードの問合せ

ユーザーは、「保存」ボタンをクリックして、入力された検索条件およびモードを保存することもできます。ポップアップ・ダイアログでは、ユーザーは保存済検索に名前を付け、チェック・ボックスを選択してヒントを指定できます。セッションを超えて保存済検索を使用可能にする場合は、永続データ・ストアが必要です。永続性の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

シード済検索は、基本的に、アプリケーション開発者によって作成された保存済検索です。コンポーネントを初期化すると、ユーザーは、そのqueryコンポーネントに関連付けられているシード済検索を選択できるようになります。

ユーザーが作成した保存済検索およびシード済システム検索は、「保存済の検索」ドロップダウン・リストに表示されます。シード済検索とユーザーの保存済検索は、仕切線によって区切られます。

保存済検索およびシード済検索を今後の使用に備えてパーソナライズすることもできます。保存済検索のパーソナライズには、永続データ・ストア機能が必要です。永続性の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

前述のデフォルトの表示の他に、コンパクト・モードまたは簡易モードで表示するようにqueryコンポーネントを構成することもできます。コンパクト・モードにはヘッダーや境界がなく、「保存済の検索」ドロップダウン・リストが開くアイコンまたは閉じるアイコンの隣に移動します。図14-6に示すqueryコンポーネントは図14-5のものと同じですが、コンパクト・モードに設定されています。

図14-6 コンパクト・モードのqueryコンポーネント

簡易モードでは、ヘッダーおよびフッターがなく、通常その領域に表示されるボタンもないコンポーネントが表示されます。図14-7に、簡易モードに設定された同じqueryコンポーネントを示します。

図14-7 簡易モードのqueryコンポーネント

queryコンポーネントではtoolbarファセットおよびfooterファセットがサポートされており、ボタンなどのコンポーネントを問合せに追加できます。たとえば、quickQueryおよびqueryコンポーネントを切り替えるコマンド・コンポーネントを作成し、それらをtoolbarファセットのツールバーに配置できます。

queryコンポーネントはそのサブコンポーネント(入力フィールド、選択リスト、ボタンなど)のレンダリングを行うため、inlineStyleは問合せとともに使用できません。inlineStyleを使用すると、予期しない表示動作が発生することがあります。

14.4.1 queryコンポーネントの追加方法

始める前に:

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.4項「queryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

QueryModelクラスおよび関連クラスを作成します。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

queryコンポーネントを追加する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「問合せ」をドラッグしてページにドロップします。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- id: コンポーネントの一意のIDを設定します。

- model: 14.2項「問合せデータ・モデルの作成」で作成した、QueryModelクラスに解決されるEL式を入力します。

- value: 14.2項「問合せデータ・モデルの作成」で作成した、QueryDescriptorクラスに解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性を設定します。

- displayMode: コンポーネントをデフォルト・モード、簡易モードまたはコンパクト・モードのいずれで表示するかを指定します。

- saveQueryMode: 実行時に保存済検索を表示および使用するかどうかを指定します。ユーザーがすべての保存済検索を表示および編集できるようにする場合は、defaultに設定します。ユーザーは保存済検索を表示および選択できるが、更新できないようにする場合は、readOnlyに設定します。保存済検索を表示しない場合は、hiddenに設定します。

- modeButtonPosition: ユーザーがモードを基本から拡張に切り替えられるボタンをツールバーに表示するか(デフォルト)、footerファセットに表示するかを指定します。

- modeChangeVisible: 基本または拡張の切替えボタンを非表示にする場合は、falseに設定します。

4. 「動作」セクションを開き、次の設定を行います。

- conjunctionReadOnly: 検索がすべての基準に一致(問合せではAND関数を使用)するか、いずれかの基準に一致(問合せではOR関数を使用)するかの決定に、ユーザーがラジオ・ボタンを選択できるようにする場合は、falseに設定します。trueに設定すると、ラジオ・ボタンはレンダリングされません。

- queryListener:: 14.2項「問合せデータ・モデルの作成」で作成した、QueryListenerハンドラに評価されるEL式を入力します。

5. 「その他」セクションを開き、次の設定を行います。

- CriterionFeatures: matchCaseDisplayedに設定すると、すべての文字列ベース検索基準で大文字と小文字を区別することが要求されます。requiredDisplayedに設定すると、すべての基準が表示されることが要求されます。

- runQueryAutomatically: 初期レンダリング、選択された保存済の検索の変更、およびリセット時に、システムまたはユーザーが作成したすべての保存済検索が自動的に実行されるようにするには、allSavedSearchesを選択します。
開発者が設計時に各システム問合せの「自動的に実行」オプションを選択できるようにするには、searchDependentを選択します。デフォルトはsearchDependentです。

ユーザーが作成した新しい保存済検索では、searchDependentが選択されていると、「保存済の検索の作成」ダイアログの「自動的に実行」オプションがデフォルトで選択されます。allSavedSearchesが選択されている場合、「自動的に実行」オプションは表示されませんが、暗黙的にtrueに設定されます。

6. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、table (または検索結果を表示するその他のコンポーネント)をページにドラッグします。表にIDを設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

7. 「構造」ウィンドウで、queryコンポーネントを選択し、resultComponentIDを表のIDに設定します。

15 ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法

この章では、JSFページのダイアログ、メニュー、ウィンドウなど、セカンダリ・ウィンドウでポップアップを作成および使用する方法について説明します。使用できるオプションとしては、宣言的またはプログラムによるポップアップの起動、コンテキストに依存した情報の表示、入力フィールドのリセット、インライン・ポップアップの自動取消の制御などがあります。

この章では、次の項目について説明します。

- 15.1項「ポップアップ・ダイアログ、メニューおよびウィンドウについて」

- 15.2項「ポップアップの宣言的な作成」

- 15.3項「ポップアップの宣言的な呼出し」

- 15.4項「ポップアップのプログラムによる呼出し」

- 15.5項「ポップアップへのコンテキスト情報の表示」

- 15.6項「インライン・ポップアップの自動取消の制御」

- 15.7項「ポップアップの入力フィールドのリセット」

15.1 ポップアップ・ダイアログ、メニューおよびウィンドウについて

popupコンポーネントを他のいくつかのADF Facesコンポーネントとともに使用して、情報を表示またはエンド・ユーザーからの入力を要求する様々なダイアログ、メニューおよびウィンドウを作成できます。これらのコンポーネントを使用して、エンド・ユーザーがセカンダリ・ウィンドウの情報の表示と非表示、追加データの入力または機能の呼出しを行うことのできる機能を構成できます。これらのコンポーネントによって提供される機能により、プライマリ・インタフェースでレンダリングされるコンテンツの補足であるコンテンツまたは機能をレンダリングでき、その結果、整然としたユーザー・フレンドリなインタフェースを開発できます。

popupコンポーネントは非表示のレイアウト・コントロールであり、インライン(つまり、同じページに属する)ダイアログ、ウィンドウおよびメニューを表示するために他のコンポーネントと一緒に使用されます。popupコンポーネントはプライマリ・インタフェース内から呼び出され、アプリケーションは、ポップアップ・ブロッカの干渉を受けずに、プライマリ・インタフェースのコンテンツなど、popupコンポーネントにレンダリングするコンテンツを管理します。popupコンポーネントにレンダリングするコンテンツのタイプはHTMLにすることをお薦めします。FlashやPDFファイルなどの他のタイプのコンテンツは、popupコンポーネントに適切にレンダリングされないことがあります。

図15-1に、popupコンポーネントがADF Facesコンポーネントと連携してセカンダリ・ウィンドウをレンダリングする例を示します。

図15-1 ダイアログ、メニューおよびウィンドウのADF Facesコンポーネント

親ページとは別に表示されるプロセスのページの作成をサポートするために、ADF Facesにはダイアログ・フレームワークが用意されています。このフレームワークでは、独自の制御フローを持つ複数のダイアログ・ページがサポートされています。たとえば、ユーザーがWebサイトで購入を選択した後の支払い手続き(チェックアウト)中に、支払いを完了する前に新しいクレジット・カードへの申込みを決定したとします。外部ブラウザ・ウィンドウで、ダイアログ・フレームワークを使用してクレジット・カードのトランザクションが開始されます。クレジット・カードのトランザクションが終了しても、元のページのチェックアウト・トランザクションは終了しません。

このダイアログ・フレームワークは、親ページの一部としてインラインで使用することもできます。これが役立つのは、ページ独自の制御フローが必要であるけれども、外部ウィンドウがポップアップ・ブロッカでブロックされることを防ぎたい場合です。

アプリケーションで完全なFusionテクノロジ・スタックを使用する場合は、このダイアログ・フレームワークがADFタスク・フローで使用するためにADFコントローラと統合されていることに注意してください。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のモーダル・ダイアログでのバインド・タスク・フローの実行に関する項を参照してください。

アプリケーションのweb.xmlファイルでLAST_WINDOW_SESSION_TIMEOUTという名前のコンテキスト・パラメータを使用して、アプリケーションでウィンドウが1つのみ開いている場合にセッション・タイムアウトが発生するまでの最大非アクティブ期間を指定できます。コンテキスト・パラメータに対して指定する最大非アクティブ期間は、セッション・タイムアウトに対して指定する値よりも小さい必要があります。この機能を有効にし、セッションにウィンドウが1つのみ開いている場合、セッション・タイムアウトはこのコンテキスト・パラメータに対して指定した値に設定されます。例15-1に、web.xmlファイルのLAST_WINDOW_SESSION_TIMEOUTコンテキスト・パラメータの値を1800秒に設定する方法を示します。

例15-1 アプリケーションの最後のウィンドウのセッション・タイムアウトの指定

<!-- Sets the session timeout to 1800 seconds when there is only one window open
in the session and 1800 seconds is smaller then the original session timeout. This
gives your application the option to end the session when an end user closes the
last window. Specify a value in seconds. A negative value disables this feature.
The default value is -1. -->
<context-param>
<param-name>LAST_WINDOW_SESSION_TIMEOUT</param-name>
<param-value>1800</param-value>
</context-param>

アプリケーションのweb.xmlファイルの構成の詳細は、付録A「web.xmlでの構成」を参照してください。

15.1.1 ポップアップ・ダイアログ、メニュー、ウィンドウのユースケースと例

dialogコンポーネントをpopupコンポーネントに子として配置し、実行時にポップアップにダイアログをレンダリングできます。dialogコンポーネントは、popupコンポーネントの唯一の直接の子コンポーネントである必要があります。実行時に、エンド・ユーザーは情報(検索基準など)を表示または入力でき、dialogコンポーネントのデフォルトのボタンを使用できます。このボタンがクリックされると、dialogEventが呼び出されます。図15-2に、エンド・ユーザーが「閉じる」ボタンをクリックすることでダイアログを閉じる例を示します。

図15-2 af:dialogコンポーネント

ポップアップ内でコンポーネントを使用して、別のコンポーネントに関連するコンテキスト情報を表示することもできます。そのように構成されている場合は、関連コンポーネントが小さな四角形を表示します。マウスが置かれると、アイコンが拡大し、ノート・アイコンも表示されます(図15-3を参照)。

図15-3 マウスを置くとアイコンが大きくなり、ノートが表示される

ユーザーがノート・アイコンをクリックすると、関連付けられたポップアップにそのコンテンツが表示されます。

15.1.2 ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能

popupコンポーネントを使用してダイアログ、メニューおよびウィンドウを作成する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページにpopupコンポーネント(または関連コンポーネント)を追加した後で、アクセシビリティやローカライズなどの機能を追加することが必要になる場合があります。これらのコンポーネントで使用できる他の機能へのリンクを次に示します。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- イベント: dialogコンポーネントは、ADF Faces buttonコンポーネントをレンダリングします。buttonコンポーネントをshowPopupBehaviorタグとともに使用してポップアップを起動することもできます。buttonコンポーネントをshowPopupBehaviorタグとともに使用すると、アクティブ化されたときにActionEventイベントが配信されます。サーバーおよびクライアント上でのイベントの処理方法の詳細は、第6章「イベントの処理」を参照してください。

- メッセージ: ポップアップ・ダイアログとセカンダリ・ウィンドウは、ユーザーに様々なレベルのヘルプ情報を提供するためによく使用されます。ユーザーへのメッセージの表示方法の詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- ローカライズ: 作成するポップアップ・ダイアログ、メニューおよびウィンドウのラベルのテキストを直接入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、テキスト文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- スキン: スキンを変更することで、ポップアップ・ダイアログ、メニューおよびウィンドウの作成に使用するコンポーネントのルック・アンド・フィールを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- アクセシビリティ: ポップアップ・ダイアログ、メニューおよびウィンドウをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- ダイアログ・フレームワーク: アプリケーションで完全なFusionテクノロジ・スタックを使用する場合は、ダイアログ・フレームワークがADFタスク・フローで使用するためにADFコントローラと統合されていることに注意してください。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アプリケーションでのダイアログの使用」の章を参照してください。

15.2 ポップアップの宣言的な作成

dialog、panelWindow、menuおよびnoteWindowコンポーネントは、すべてpopupコンポーネントの内部で使用して、表15-1に示すようにインライン・ポップアップを表示できます。popupコンポーネントの子コンポーネントが存在しない場合は、非常に単純なインライン・ポップアップが表示されます。

表15-1 popupコンポーネントで使用されるコンポーネント

コンポーネント

実行時の表示

dialog

子をダイアログ内に表示し、OK、Yes、NoおよびCancelのアクションがアクティブ化されたときにイベントを配信します。詳細は、15.2.1項「ダイアログの作成方法」を参照してください。

panelWindow

ダイアログに似たウィンドウに子を表示しますが、イベントはサポートしません。詳細は、15.2.2項「パネル・ウィンドウの作成方法」を参照してください。

menu

関連コンポーネントのポップアップ・メニューを表示します。詳細は、15.2.3項「ポップアップ・メニューの作成方法」を参照してください。

noteWindow

特定のUIコンポーネントに関連付けられた読取り専用の情報を表示します。ノート・ウィンドウはヘルプやメッセージの表示に使用され、通常はマウスを置いたり、フォーカスをしたときに表示されます。詳細は、15.2.4項「ノート・ウィンドウの作成方法」を参照してください。

dialog、panelWindow、menuまたはnoteWindowコンポーネントのいずれも直接の子コンポーネントとして持たないpopupコンポーネント

コンテンツをインラインで表示します。

dialogコンポーネントとpanelWindowコンポーネントはいずれも定義ヘルプがサポートされていますが、ヘルプ・アイコン(疑問符が表示された青い丸)の上にカーソルを移動するとコンテンツが表示されます。dialogおよびpanelWindowコンポーネントでは説明ヘルプはサポートされません。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

一般的には、buttonコンポーネントをshowPopupBehaviorタグとともに使用してポップアップを起動します。showPopupBehaviorタグを、起動する必要のあるコンポーネントに関連付けます。このタグは、(必要に応じて)ポップアップの位置も制御します。

buttonコンポーネントのアクション・イベントとともに使用することに加えて、showPopupBehaviorタグは他のイベント(showDetailイベントやselectionイベントなど)とともに使用することもできます。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

showPopupBehaviorタグをアクション・コンポーネントとともに使用するかわりに、バッキングBeanメソッドを作成してポップアップを起動、取消または非表示にできます。作成するバッキングBeanメソッドは、アクション・コンポーネントによって返されるactionEventを引数として受け取ります。この代替方法の詳細は、15.4項「ポップアップのプログラムによる呼出し」を参照してください。

デフォルトで、ポップアップのコンテンツは、ポップアップが表示されるまでサーバーから送信されません。このため、開かれたときにポップアップが表示されるスピードと、親ページがレンダリングされるスピードが入れ替わります。ポップアップがロードされると、すぐに表示できるよう、コンテンツはクライアントにおいてデフォルトでキャッシュされます。

popupコンポーネントのcontentDelivery属性を次のいずれかのオプションに設定することで、コンテンツの配信戦略を変更できます。

- lazy - 前述のデフォルトの方法。コンテンツは、ポップアップが一度表示されるまでロードされず、ロードされるとキャッシュされます。

- immediate - コンテンツはすぐにページにロードされるため、コンテンツを可能なかぎり迅速に表示できます。この方法は、ページが使用されるたびにすべてのユーザーが必ず使用するポップアップに使用します。

- lazyUncached - コンテンツはポップアップが表示されるまでロードされず、ポップアップを表示するたびにコンテンツが再ロードされます。この方法は、失効するか期限切れになる可能性があるデータをポップアップに表示する場合に使用します。

popupコンポーネントのcontentDelivery属性をlazyに設定することを選択した場合、別のpopupコンポーネント属性(childCreation)をdeferredに設定することで、popupコンポーネントとそれをホストするページのパフォーマンスをさらに最適化できます。これにより、アプリケーションがコンテンツを配信するまでpopupコンポーネントの子コンポーネントの作成が遅延されます。childCreation属性のデフォルト値はimmediateです。

15.2.1 ダイアログの作成方法

ダイアログの終了時にイベントを起動する必要がある場合は、ダイアログを作成します。dialogコンポーネントをpopupコンポーネントに子として追加した後、他のコンポーネントを追加してデータを表示および収集できます。

デフォルトでは、dialogコンポーネントは次のボタンの組合せを持つことができます。

- 取消

- OK

- 「OK」および「取消」

- 「はい」および「いいえ」

- 「はい」、「いいえ」および「取消」

- なし

これらのボタンは、クリックされるとdialogEventを起動します。buttonBarファセットを使用して、ダイアログに他のボタンを追加できます。追加するボタンはdialogEventを起動しません。かわりに、標準のactionEventを起動します。actionEventがダイアログ内のコンポーネントに対してのみ起動されるようにするために、追加するボタンのpartialSubmit属性をtrueに設定してください。ただし、af:popupコンポーネントのautoCancelプロパティの値をdisabledに設定した場合は、ボタンを追加し、そのpartialSubmit属性をfalseに設定できます。この後者のオプション(partialSubmitをfalseに設定)を選択すると、アプリケーションはpopupコンポーネントの可視性(また、拡張によりdialogコンポーネント)をリストアする前にページを再ロードしてページのコンポーネントを再初期化するため、エンド・ユーザーの待機時間が長くなります。af:popupコンポーネントのautoCancelプロパティの値がenabled(デフォルト値)に設定されている場合は、ボタンのpartialSubmit属性をtrueに設定する必要があります。af:popupコンポーネントのautoCancelプロパティの使用の詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

始める前に:

dialogコンポーネントの属性およびその他のコンポーネントがインライン・ダイアログの機能に与える影響を理解することが役立つ場合があります。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

インライン・ダイアログを作成する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「ポップアップ」をドラッグしてページにドロップします。

ヒント:

位置はpopupの呼出しに使用されるコンポーネントによって決定されるため、popupコンポーネントがページに表示されるかどうかは関係ありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- ContentDelivery: ポップアップのコンポーネントにコンテンツが配信される方法を選択します。

ヒント:

ダイアログの入力コンポーネントの値は、ユーザーがダイアログの「取消」ボタンをクリックしたときにリセットされません。ユーザーが2回目にダイアログを開いた場合、これらの値が依然として表示されます。この値をサーバーの現在の値に合せるには、contentDelivery属性をlazyUncachedに設定します。

- Animate: アニメーションを有効にするにはtrueを選択します。アニメーションはtrinidad-config.xmlファイルの構成とそのスキン・プロパティによって決定されます(詳細は、A.6.2.1項「アニメーションの有効化」を参照してください)。falseを選択することで、この設定をオーバーライドできます。

- LauncherVar: 起動コンポーネントの参照に使用する変数を入力します。この変数は、popupまたはその子コンポーネントでのイベント配信時にのみ、またEventContextがlauncherに設定されている場合にのみアクセス可能です。

- EventContext: ポップアップが複数のオブジェクトによって共有されている場合、たとえばポップアップ内のダイアログに表で選択された行に関する情報が表示される場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーがコールされる前にクリックされた行が現在の行になり、その行のデータのみ返されます。詳細は、15.2.5項「実行時に行われる処理: popupコンポーネントのイベント」を参照してください。

3. 必要に応じて、「プロパティ」ウィンドウで次の属性を設定します。

- AutoCancel: インライン・ポップアップの自動取消を防ぐにはdisabledを選択します。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

- ChildCreation: deferredを選択すると、popupコンポーネントの子コンポーネントの作成はアプリケーションのコンテンツが配信されるまで延期されます。childCreation属性のデフォルト値はimmediateです。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

- ResetEditableValues: エンド・ユーザーがダイアログを取り消す場合にエンド・ユーザーが入力した編集可能な値をnullにリセットするには、whenCanceledを選択します。
または、resetListenerコンポーネントを使用できます。resetListenerコンポーネントの使用の詳細は、15.7項「ポップアップの入力フィールドのリセット」を参照してください。

4. 「コンポーネント」ウィンドウから、「ダイアログ」をpopupコンポーネントに直接の子としてドラッグ・アンド・ドロップします。

5. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- Type: ダイアログに表示する組込みの部分送信ボタンを選択します。
たとえば、type属性をyesNoCancelに設定した場合、ダイアログには「はい」、「いいえ」、「取消」のボタンが表示されます。これらのいずれかのボタンがクリックされると、ダイアログが閉じ、関連付けられた結果(ok、yes、noまたはcancel)がイベントで配信されます。ok、yesおよびnoの結果はdialogEventで配信されます。cancelの結果はPopupCanceledイベントで送信されます。ロジックの決定に結果を使用して、適切なリスナー・プロパティを使用し、イベントを処理するメソッドにバインドできます。

ヒント:

エラーまたはそれより高い重大度のADF Facesメッセージがある場合、ダイアログは閉じません。

- Title: ダイアログ・ウィンドウにタイトルとして表示するテキストを入力します。

- CloseIconVisible: 「閉じる」アイコンをダイアログに表示するかどうかを選択します。

- Modal: ダイアログをモーダルにするかどうかを選択します。モーダル・ダイアログでは、ユーザーはダイアログが閉じられるまでメイン・ページに戻ることができません。

- Resize: ユーザーがダイアログのサイズを変更できるようにするかどうかを選択します。デフォルトはoffです。

- StretchChildren: 子コンポーネントをダイアログに合せて拡大するかどうかを選択します。firstに設定されている場合、ダイアログは単一の子コンポーネントを拡大します。ただし、拡大できる子コンポーネントであることが必要です。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

注意:

Resizeをonに設定するかStretchChildrenをfirstに設定した場合は、ContentWidthおよびContentHeightも設定する必要があります(手順8を参照)。それ以外の場合、サイズはデフォルトで250x250ピクセルになります。

6. 「外観」セクションを開き、テキスト属性を設定します。
ボタン・テキストとアクセス・キーを別々に指定するかわりに、2つを結合して、アクセス・キーがボタン・テキストの一部になるようにできます。アクセス・キーとして使用する文字の前にアンパサンド(&)を付けます。

たとえば、肯定ボタンのテキストを「OK」にし、「OK」の「O」をアクセス・キーにする場合は、「&OK」と入力します。

7. 「動作」セクションを開き、必要に応じてDialogListener属性の値を入力します。値は、イベントを処理するダイアログ・リスナー・メソッドへのEL式メソッド参照である必要があります。
たとえば、項目の削除を確認するダイアログを作成するとします。例15-2に示すdeleteItemメソッドのようなメソッドをマネージドBeanに作成できます。このメソッドは、イベントからの結果にアクセスします。結果がyes以外の場合は、ダイアログが閉じられます。結果がyes(ユーザーが項目を閉じることを意味します)の場合、メソッドは選択された項目を取得し、削除します。

例15-2 項目を削除するdialogEventのハンドラ

public void deleteItem(DialogEvent dialogEvent)
{
if (dialogEvent.getOutcome() != DialogEvent.Outcome.yes)
{
return;
}

// Ask for selected item from FileExplorerBean
FileItem selectedFileItem = _feBean.getLastSelectedFileItem();
if (selectedFileItem == null)
{
return;
}
else
{
// Check if we are deleting a folder
if (selectedFileItem.isDirectory())
{
_feBean.setSelectedDirectory(null);
}
}

this.deleteSelectedFileItem(selectedFileItem);
}

例15-3に、dialogListener属性がdeleteItemメソッドにバインドされる方法を示します。

例15-3 メソッドにバインドされているdialogListener属性

<af:dialog title="#{explorerBundle['deletepopup.popuptitle']}"
type="yesNo"
dialogListener="#{explorer.headerManager.deleteItem}"
id="d1">

dialogEventは、結果がok、yesまたはnoの場合にのみサーバーに伝播されます。必要に応じてこれをブロックできます。詳細は、6.3.5項「イベントがサーバーに伝播されないようにする方法」を参照してください。

ユーザーが「取消」ボタン(または「閉じる」アイコン)をクリックした場合、結果はcancelで、popupCancelクライアント・イベントがpopupコンポーネントで発生します。popupコンポーネントにレンダリングされた入力コンポーネントに入力された値は、サーバーに送信されません。popupコンポーネントがレンダリングした後で値が変更された編集可能コンポーネントは、変更された値をサーバーに送信しません。popupCancelイベントがサーバーに配信されます。

8. ダイアログのサイズを固定する場合、またはresizeがonに設定済かstretchChildrenがfirstに設定済の場合は、「外観」セクションを開いて次の属性を設定します。

- ContentHeight: 目的の高さをピクセル単位で入力します。

- ContentWidth: 目的の幅をピクセル単位で入力します。

ヒント:

(resize属性がonに設定されている場合)ユーザーは実行時にこれらの属性の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了すると値は保持されません。変更の永続性の有効化および使用方法の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

注意:

アクション・コンポーネントをshowPopupBehaviorタグなしで使用してダイアログを起動する場合に、そのアクション・コンポーネントのwindowHeight属性およびwindowWidth属性の値が指定されている場合は、アクション・コンポーネントでの値がcontentHeightおよびcontentWidthの値よりも優先されます。ダイアログ・フレームワークでは、アクション・コンポーネントを使用してダイアログを起動するときにshowPopupBehaviorタグを指定しないことも許可されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のモーダル・ダイアログでのバインド・タスク・フローの実行に関する項を参照してください。showPopupBehaviorタグの詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

9. 必要に応じて、buttonコンポーネントをbuttonBarファセットに追加します。追加したbuttonコンポーネントによって起動されるのは、標準のactionEventであり、dialogEventではありません。actionEventがダイアログ内のコンポーネントに対してのみ起動されるようにするために、buttonコンポーネントのpartialSubmit属性をtrueに設定してください。buttonコンポーネントのpartialSubmit属性をfalseに設定できるのは、af:popupコンポーネントのautoCancelプロパティがdisabledに設定されている場合です。af:popupコンポーネントのautoCancelプロパティとbuttonコンポーネントのpartialSubmitプロパティの値によって、buttonコンポーネントがクリックされたときにどのようにダイアログを閉じて再ロードするかが決まります。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

ヒント:

ファセットがビジュアル・エディタに表示されていない場合は、「構造」ウィンドウでdialogコンポーネントを右クリックして「ファセット - ダイアログ」→「ButtonBar」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

デフォルトでは、追加したbuttonコンポーネントはクリックされてもダイアログが閉じることはありません。buttonコンポーネントのactionListenerを、ダイアログの終了およびその他の必要な処理を管理するハンドラにバインドする必要があります。これを行う方法の例は、タグのドキュメントを参照してください。

10. ダイアログのデータを表示または収集するコンポーネントを挿入します。panelGroupLayoutなどのレイアウト・コンポーネントを使用してコンポーネントを含めます。

ヒント:

通常は、ダイアログの「取消」ボタンまたは「閉じる」アイコンをクリックすると、inputTextコンポーネントに入力されたデータは送信されません。ただし、ダイアログのinputTextコンポーネントでautoSubmit属性をtrueに設定すると、この設定が送信の原因となるためダイアログの取消動作がオーバーライドされます。

11. 親ページにロジックを追加して、ポップアップとダイアログを呼び出します。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

15.2.2 パネル・ウィンドウの作成方法

panelWindowコンポーネントはdialogコンポーネントに似ていますが、ボタンの構成やファセットへのボタンの追加はできません。panelWindowのデータを処理するロジックを呼び出す必要がある場合は、popupコンポーネントのcancelイベントのリスナーを作成する必要があります。

panelWindowコンポーネントを含むpopupコンポーネントは、formコンポーネントに含まれている必要があります。

ヒント:

Fusionテクノロジ・スタックを使用するアプリケーションでpanelWindowをインライン・ポップアップとして使用する場合に、ダイアログの外観をエミュレートするには、panelStretchLayoutコンポーネントの中央ファセットにpanelWindowコンポーネントを配置し、buttonボタンをbottomファセットに配置します。

始める前に:

panelWindowコンポーネントの属性がインライン・ウィンドウの機能に与える影響を理解することが役立つ場合があります。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

インライン・ウィンドウを作成する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「ポップアップ」をドラッグしてページにドロップします。

ヒント:

位置はpopupの呼出しに使用されるコンポーネントによって決定されるため、popupコンポーネントがページに表示されるかどうかは関係ありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- ContentDelivery: ポップアップのコンポーネントにコンテンツが配信される方法を選択します。

ヒント:

入力コンポーネントの値は、ユーザーがpanelWindowコンポーネントを閉じたときにリセットされません。ユーザーが2回目にウィンドウを開いた場合、これらの値が依然として表示されます。この値をサーバーの現在の値に合せるには、contentDelivery属性をlazyUncachedに設定します。

- Animate: アニメーションを有効にするにはtrueを選択します。アニメーションはtrinidad-config.xmlファイルの構成とそのスキン・プロパティによって決定されます(詳細は、A.6.2.1項「アニメーションの有効化」を参照してください)。

- LauncherVar: 変数の名前(sourceなど)を入力します。表のvar属性と同様に、この変数はリクエスト・スコープの参照を、showPopupBehaviorタグを含むコンポーネントに格納するために使用されます。変数は、popupまたはその子コンポーネントでのイベント配信時にのみ、またEventContextがlauncherに設定されている場合にのみアクセス可能です。

- EventContext: ポップアップが複数のオブジェクトによって共有されている場合、たとえばポップアップ内のウィンドウに表で選択された行に関する情報が表示される場合は、launcherを選択します。この属性をlauncherに設定すると、イベント・リスナーがコールされる前にクリックされた行が現在の行になり、その行のデータのみ返されます。詳細は、15.2.5項「実行時に行われる処理: popupコンポーネントのイベント」を参照してください。

- PopupCancelListener: ウィンドウが閉じられるときに呼び出すロジックでハンドラに評価されるEL式に設定します。

- 必要に応じて、「AutoCancel」ドロップダウンで値を選択します。この値によって、自動取消の動作が決定します。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

3. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「パネル・ウィンドウ」をpopupコンポーネントに直接の子としてドラッグ・アンド・ドロップします。

4. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- Modal: ウィンドウをモーダルにするかどうかを選択します。モーダル・ウィンドウでは、ユーザーはウィンドウが閉じられるまでメイン・ページに戻ることができません。

- CloseIconVisible: 「閉じる」アイコンをウィンドウに表示するかどうかを選択します。

- Title: ウィンドウにタイトルとして表示されるテキスト。

- Resize: ユーザーがダイアログのサイズを変更できるようにするかどうかを選択します。デフォルトはoffです。

- StretchChildren: 子コンポーネントをウィンドウに合せて拡大するかどうかを選択します。firstに設定されている場合、ウィンドウは単一の子コンポーネントを拡大します。ただし、拡大できる子コンポーネントであることが必要です。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

注意:

Resizeをonに設定するかStretchChildrenをfirstに設定した場合は、ContentWidthおよびContentHeightも設定する必要があります(手順6を参照)。それ以外の場合、サイズはデフォルトで250x250ピクセルになります。

5. ウィンドウのサイズを固定する場合、またはResizeをonに設定済かStretchChildrenをfirstに設定済の場合は、「外観」セクションを開いて次の属性を設定します。

- ContentHeight: 目的の高さをピクセル単位で入力します。

- ContentWidth: 目的の幅をピクセル単位で入力します。

ヒント:

(resize属性がonに設定されている場合)ユーザーは実行時にこれらの属性の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了すると値は保持されません。変更の永続性の有効化および使用方法の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

注意:

アクション・コンポーネントをshowPopupBehaviorタグなしで使用してダイアログを起動する場合に、そのアクション・コンポーネントのwindowHeight属性およびwindowWidth属性の値が設定されている場合は、アクション・コンポーネントでの値がcontentHeightおよびcontentWidthの値よりも優先されます。showPopupBehaviorタグの詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

6. ウィンドウのデータを表示または収集するコンポーネントを挿入します。panelGroupLayoutなどのレイアウト・コンポーネントを使用してコンポーネントを含めます。

7. 親ページにロジックを追加して、ポップアップとパネル・ウィンドウを呼び出します。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

15.2.3 ポップアップ・メニューの作成方法

popupコンポーネント内でメニュー・コンポーネントを使用して、ポップアップ・メニューを作成します。特定のトリガーに基づいて、別のコンポーネントからコンテキスト・メニュー・ポップアップを呼び出すことができます。かわりに、ツールバーのツールバー・ボタンでポップアップ・メニューを起動する場合は、16.3項「ツールバーの使用方法」を参照してください。

始める前に:

popupコンポーネントの属性およびその他のコンポーネントがポップアップ・メニューの機能に与える影響を理解することが役立つ場合があります。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

インライン・ポップアップ・メニューを作成する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「ポップアップ」をドラッグしてページにドロップします。

ヒント:

位置はpopupの呼出しに使用されるコンポーネントによって決定されるため、popupコンポーネントがページに表示されるかどうかは関係ありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- ContentDelivery: ポップアップのコンポーネントにコンテンツが配信される方法を決定します。

- Animate: アニメーションを有効にするにはtrueを選択します。アニメーションはtrinidad-config.xmlファイルの構成とそのスキン・プロパティによって決定されます(詳細は、A.6.2.1項「アニメーションの有効化」を参照してください)。falseを選択することで、この設定をオーバーライドできます。

- LauncherVar: 起動コンポーネントの参照に使用する変数名(sourceなど)を入力します。この変数は、popupまたはその子コンポーネントでのイベント配信時にのみ、またEventContextがlauncherに設定されている場合にのみアクセス可能です。

- EventContext: ポップアップが複数のオブジェクトによって共有されている場合、たとえばポップアップ内のメニューに表で選択された行に関する情報が表示される場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーがコールされる前にクリックされた行が現在の行になり、その行のデータのみ返されます。詳細は、15.2.5項「実行時に行われる処理: popupコンポーネントのイベント」を参照してください。

- 必要に応じて、「AutoCancel」ドロップダウンで値を選択します。この値によって、自動取消の動作が決定します。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

3. 「コンポーネント」ウィンドウで、「メニュー」をpopupコンポーネントに直接の子としてドラッグ・アンド・ドロップし、commandMenuItemコンポーネントを使用してメニューを作成します。作成方法は、16.2.1項「メニュー・バーのメニューの作成および使用方法」を参照してください。

ヒント:

これはポップアップ・メニューであるため、16.2.1項「メニュー・バーのメニューの作成および使用方法」の手順1から5に従ってメニュー・バーまたは複数メニューを作成する必要はありません。

4. 親ページにロジックを追加して、ポップアップとポップアップ・メニューを呼び出します。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

15.2.4 ノート・ウィンドウの作成方法

noteWindowコンポーネントを使用して、読取り専用テキストを表示します。noteWindowコンポーネントを含むpopupコンポーネントは、formコンポーネントに含まれている必要があります。

始める前に:

noteWindowコンポーネントの属性およびその他のコンポーネントが機能に与える影響を理解することが役立つ場合があります。詳細は、15.2項「ポップアップの宣言的な作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

インライン・ウィンドウを作成する手順:

1. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「ポップアップ」をドラッグしてページにドロップします。

ヒント:

位置はpopupの呼出しに使用されるコンポーネントによって決定されるため、popupコンポーネントがページに表示されるかどうかは関係ありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- ContentDelivery: ポップアップのコンポーネントにコンテンツが配信される方法を決定します。

- Animate: アニメーションを有効にするにはtrueを選択します。アニメーションはtrinidad-config.xmlファイルの構成とそのスキン・プロパティによって決定されます(詳細は、A.6.2.1項「アニメーションの有効化」を参照してください)。falseを選択することで、この設定をオーバーライドできます。

- LauncherVar: 起動コンポーネントの参照に使用する変数を入力します。この変数は、popupまたはその子コンポーネントでのイベント配信時にのみ、またEventContextがlauncherに設定されている場合にのみアクセス可能です。

- EventContext: ポップアップが複数のオブジェクトによって共有されている場合、たとえばポップアップ内のウィンドウに表で選択された行に関する情報が表示される場合は、launcherを選択します。この属性をlauncherに設定すると、イベント・リスナーがコールされる前にクリックされた行が現在の行になり、その行のデータのみ返されます。詳細は、15.2.5項「実行時に行われる処理: popupコンポーネントのイベント」を参照してください。

- PopupCancelListener: ウィンドウが閉じられるときに呼び出すロジックでハンドラに評価されるEL式に設定します。

- 必要に応じて、「AutoCancel」ドロップダウンで値を選択します。この値によって、自動取消の動作が決定します。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

3. 「コンポーネント」ウィンドウの「レイアウト」パネルの「セカンダリ・ウィンドウ」グループから、「ノート・ウィンドウ」をpopupコンポーネントに直接の子としてドラッグ・アンド・ドロップします。

4. ウィンドウに表示するテキストを入力する手順:

1. 「ソース」タブをクリックしてページのソース・コードを表示します。

2. af:noteWindowタグから閉じるスラッシュ(/)を削除します。

3. af:noteWindowタグの下に、表示するテキストを単純なHTMLタグを使用して入力し、閉じるaf:noteWindowタグで終了します。

例15-4に、ノート・ウィンドウのテキストを表示します。

例15-4 af:noteWindowタグ内のテキスト

<af:popup id="popupHead" contentDelivery="lazyUncached">
<af:noteWindow inlineStyle="width:200px" id="nw3">
<p>In anatomy, the head of an animal is the rostral part (from
anatomical position) that usually comprises the brain, eyes,
ears, nose, and mouth (all of which aid in various sensory
functions, such as sight, hearing, smell, and taste). Some very
simple animals may not have a head, but many bilaterally
symmetric forms do.</p>
</af:noteWindow>
</af:popup>

図15-4に、ノートがどのように表示されるかを示します。

図15-4 ノート・ウィンドウに表示されるテキスト

5. 必要に応じて、「プロパティ」ウィンドウの「動作」セクションを開いて「AutoDismissalTimeout」フィールドで秒数を指定します。指定する値によって、アプリケーションが自動的に閉じる前にノート・ウィンドウが表示される秒数が決定されます。指定する値によって、デフォルトの自動消去動作がオーバーライドされます。エンド・ユーザーがノート・ウィンドウのコンテンツにマウスを移動すると、自動消去動作はノート・ウィンドウのデフォルトの自動消去動作に戻るため、このオーバーライドは取り消されます。デフォルトの自動消去動作では、フォーカスが起動ソースまたはポップアップのコンテンツから変更された場合にノート・ウィンドウが終了します。

注意:

タイムアウト取消期間はマウス・カーソルを重ねることでトリガーされ、キーボードの同等の操作は用意されていないため、このプロパティで有効化された機能は使い勝手がよいとは言えません。

6. 親ページにロジックを追加して、ポップアップとノート・ウィンドウを呼び出します。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

15.2.5 実行時に行われる処理: popupコンポーネントのイベント

コンテンツがポップアップに配信され、contentDelivery属性がlazyまたはlazyUncachedに設定されている場合は、popupFetchサーバー側イベントが起動します。このイベントには、eventContextとlauncherVarの2つのプロパティがあります。eventContextプロパティは、イベントの配信元のコンテキストがポップアップのコンテキスト(self)とポップアップを起動したコンポーネント(launcher)のどちらであるかを決定します。コンテキストをlauncherに設定すると、フレームワークはポップアップを起動したコンポーネントがポップアップではなくイベントを起動したかのうように動作するため、ポップアップが複数のコンポーネントによって共有されている場合に非常に便利な可能性があります。変数を使用して表の行をスタンプ・アウトするのと同様の方法で、launcherVarプロパティを使用して現在のランチャを追跡します。

たとえば、表の中の列で、linkコンポーネントを使用して人物のファースト・ネームを表示するとします。このlinkコンポーネントにマウスを置くと、ポップアップnoteWindowが起動されて、その人物のフル・ネームが表示されます。このnoteWindowは表のすべての行で使用されますが、表示する必要があるのはクリックされたlinkコンポーネントが存在する行のフル・ネームのみであるため、eventContextプロパティを使用して、コンテキストがその行となるようにします(例15-5を参照)。

例15-5 共有ポップアップでのeventContextの使用

<af:popup id="noteWindow" contentDelivery="lazyUncached" eventContext="launcher"
launcherVar="source">
<af:noteWindow>
<af:outputText value="#{testBean.fullName}"/>
</af:noteWindow>
</af:popup>
<af:table var="person" value="#{testBean.people}">
<af:column id="firstName">
<af:link text="#{person.firstName}">
<af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/>
</af:link>
</af:column>
</af:table>

変数ソースを使用して、ソースから値を取得し、それらを適用するか、値を設定できます。たとえば、例15-6に示すようにsetPropertyListenerおよびclientAttributeタグを使用して、表で使用されるpeopleオブジェクトの姓名値を取得し、それをウィンドウで使用されるtestBeanのfullNameプロパティの値として設定できます。

例15-6 launcherVarプロパティを使用したポップアップのコンポーネントの値の設定

<af:popup id="noteWindow" contentDelivery="lazyUncached" eventContext="launcher"
launcherVar="source">
<af:noteWindow>
<af:outputText value="#{testBean.fullName}"/>
</af:noteWindow>
<af:setPropertyListener from="#{source.attributes.fullName}"
to="#{testBean.fullName}" type="popupFetch"/>
</af:popup>
<af:table var="person" value="#{testBean.people}">
<af:column id="firstName">
<f:facet name="header">
<af:outputText value="First Name"/>
</f:facet>
<af:link text="#{person.firstName}">
<af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/>
<af:clientAttribute name="fullName" value="#{person.fullName}"/>
</af:link>
</af:column>
</af:table>

この例では、launcherVarプロパティ・ソースはpopupFetchイベントを使用して現在の行の姓名を取得します。setPropertyListenerタグの使用の詳細は、5.7.2項「Javaコードを記述せずにpageFlowScopeスコープを使用する方法」を参照してください。クライアント属性の使用の詳細は、4.6項「クライアント側コンポーネントに対するボーナス属性の使用」を参照してください。showPopupBehaviorタグの詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

ポップアップは、次のクライアント側イベントも起動します。

- popupOpening: ポップアップが呼び出されたときに起動します。このイベントがクライアント側のリスナーで取り消されると、ポップアップは表示されません。

- popupOpened: ポップアップが表示可能になった後、起動されます。このイベントを使用する1つの例は、ポップアップでデフォルトのフォーカスをオーバーライドするカスタム・ルールの作成です。

- popupCanceled: 自動消去やポップアップ・クライアント・コンポーネントのcancelメソッドの明示的な起動によってポップアップが予期せずに閉じると、起動します。このクライアント側イベントには、サーバー側の対応するイベントもあります。

- popupClosed: ポップアップが非表示の場合、またはポップアップが予期せず閉じた場合に起動します。このクライアント側イベントには、サーバー側の対応するイベントもあります。

「はい」ボタンのクリックなど、肯定的な状況でポップアップが閉じられた場合は非表示になります。「閉じる」アイコンまたは「取消」ボタンがクリックされた場合など、ポップアップが自動消去によって閉じられた場合は取り消されます。どちらのタイプの消去でも、popupClosedクライアント側イベントが発生します。ポップアップを取り消すと、サーバー側に対応するイベントを持つクライアント側popupCanceledイベントも発生します。イベントに対しステータス登録されたリスナーがないかぎり、イベントはサーバーに伝播されません。伝播される場合、ポップアップの子コンポーネントの処理が阻止されるため、送信された値と検証は無視されます。ポップアップが取り消された場合に必要な処理を行うロジックを含む、popupCanceledイベントのリスナーを作成できます。

クライアント側イベントに基づくロジックを呼び出す場合は、カスタム・クライアント・リスナー・メソッドを作成できます。詳細は、4.4項「クライアント・イベントのリスニング」を参照してください。クライアント・イベントに基づいてサーバー側ロジックを呼び出す場合は、そのロジックを呼び出すserverListenerタグを追加できます。詳細は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

15.2.6 ダイアログ・イベントに関する必知事項

dialogコンポーネントは、エンド・ユーザーが「OK」、「はい」、「いいえ」または「取消」ボタンをクリックしたときにdialogEventを生成します。dialogコンポーネントは、エラーまたはそれ以上の重大度のメッセージがページに存在しなければ、エンド・ユーザーが「OK」、「はい」または「いいえ」ボタンをクリックしたときに自動的に非表示になります。「取消」ボタンまたは閉じるアイコンを選択するエンド・ユーザーは、親popupコンポーネントを取り消し、ポップアップ取消イベントを生成します。

「OK」、「はい」、「いいえ」または「取消」ボタンによって返されるdialogEventをインターセプトするようにdialogListener属性を構成できます。「OK」、「はい」および「いいえ」ボタンによって返されるdialogEventのみ、サーバーに伝播されます。「取消」ボタン、[Esc]キーおよび閉じるアイコンによって返されるdialogEventは、クライアント・ダイアログ・イベントをキューに入れ、サーバーに伝播しません。

dialogコンポーネントを起動するアクション・コンポーネントのactionListenerが、dialogコンポーネントから制御が戻った後にアクション(たとえば、inputTextコンポーネントの更新)を実行するように構成されている場合は、inputTextコンポーネントに対してresetValue()を呼び出すことも必要になります。これが必要になるのは、アクション・コンポーネントのimmediateの値がtrueに設定されている場合です。

dialogコンポーネントおよびpopupコンポーネントによって起動されるイベントの詳細は、Oracle ADF Facesタグ・リファレンスを参照してください。

15.3 ポップアップの宣言的な呼出し

ADF Facesのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。showPopupBehaviorタグは宣言的なソリューションを提供するため、popupコンポーネントを開くJavaScriptを作成したり、スクリプトをpopupコンポーネントに登録したりする必要はありません。クライアントの動作タグの詳細は、6.6項「ADF Facesのクライアントの動作タグの使用」を参照してください。

showPopupBehaviorタグは、指定されたイベント(たとえば、アクション・コンポーネントのactionEventやshowDetailコンポーネントのdisclosureEvent)をリスニングします。ただし、showPopupBehaviorタグはサーバーへのそのイベントの配信も取り消します。したがって、showPopupBehaviorタグがリスニングするイベントに基づいてサーバー側ロジックを起動する必要がある場合は、JavaScriptを使用してポップアップを起動するか、15.4項「ポップアップのプログラムによる呼出し」の説明に従ってpopupコンポーネントをプログラムで起動する必要があります。

15.3.1 af:showPopupBehaviorタグを使用してポップアップを宣言的に呼び出す方法

showPopupBehaviorタグは、ポップアップを呼び出すコンポーネントとともに使用します。たとえば、ダイアログを呼び出すbuttonコンポーネントや、右クリックされたときにコンテキスト・メニューを呼び出すinputTextコンポーネントです。

始める前に:

popupコンポーネントを宣言的に呼び出す場合は、使用可能な構成オプションに関する知識が役立つ場合があります。詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

次のタスクを完了する必要があります。

宣言的に呼び出すタイプのポップアップ作成し(15.2項「ポップアップの宣言的な作成」を参照)、ポップアップを呼び出すコンポーネントを作成します。

showPopupBehaviorタグを使用する手順:

1. 「コンポーネント」ウィンドウの「操作」パネルの「動作」グループから、「ポップアップ表示動作」をドラッグし、ポップアップを呼び出すコンポーネントに子としてドロップします。

2. 「プロパティ」ウィンドウで、PopupIdプロパティのフィールドにマウスを置いて表示されたアイコンをクリックし、表示されたコンテキスト・メニューで「編集」を選択します。「プロパティの編集: PopupId」ダイアログを使用して、呼び出すポップアップ・コンポーネントを選択し、「OK」をクリックします。

3. 「プロパティ」ウィンドウの「TriggerType」ドロップダウン・メニューで、ポップアップを呼び出すトリガーを選択します。デフォルトはactionで、アクション・コンポーネントに対して使用できます。マウスが右クリックされたときにポップアップをトリガーするにはcontextMenuを使用します。カーソルがコンポーネント上に置かれたときにポップアップをトリガーするにはmouseHoverを使用します。カーソルがコンポーネントから離れるとポップアップが閉じます。ポップアップをトリガーできるコンポーネントおよびマウス/キーボード・イベントの詳細なリストは、Oracle ADF Facesタグ・リファレンスのshowPopupBehaviorタグのドキュメントを参照してください。

注意:

showPopupBehaviorタグのtriggerType属性に対して選択されたイベントは、サーバーに配信されません。このイベントに基づいてサーバー側ロジックを起動する必要がある場合は、JavaScriptまたはカスタム・イベントを使用してポップアップを呼び出すか(6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照)、ポップアップをプログラムで呼び出す必要があります(15.4項「ポップアップのプログラムによる呼出し」を参照)。

4. AlignIdプロパティのフィールドにマウスを置いて表示されたアイコンをクリックし、表示されたコンテキスト・メニューで「編集」を選択します。「プロパティの編集: AlignId」ダイアログを使用して、ポップアップの位置合せの基準となるコンポーネントを選択します。

5. 「位置合せ」ドロップダウン・メニューから、前の手順で選択したコンポーネントを基準としてポップアップを配置する方法を選択します。

注意:

dialogおよびpanelWindowコンポーネントでは、対応するポップアップをユーザーが移動できるため、alignIdまたはalign属性は不要です。AlignIdを設定した場合、値はダイアログまたはウィンドウの位置を手動でドラッグ・アンド・ドロップすることでオーバーライドされます。AlignIdまたはAlignに値が入力されていない場合、ダイアログまたはウィンドウはブラウザの中央に開きます。

また、triggerType属性がcontextMenuに設定されている場合、配置は常にマウスの位置に基づきます。

15.3.2 af:showPopupBehaviorタグを使用してポップアップを呼び出した場合の処理

設計時に、「プロパティ」ウィンドウで選択したソース・ファイルの中に、対応する値がJDeveloperによって生成されます。例15-7に示すサンプル・コードでは、ボタン「Show Popup」がクリックされると、id属性が"popup2"であるaf:popupコンポーネントにテキストが表示されます。

例15-7 ボタン・コンポーネントに関連付けられたshowPopupBehavior

<af:button text="Click me" clientComponent="true" id="popupButton2">
<showPopupBehavior popupId="popup2" alignId="popupButton2" align="afterStart"/>
</af:button>
...
<af:popup id="popup2">
<af:panelGroupLayout layout="vertical">
<af:outputText value="Some"/>
<af:outputText value="popup"/>
<af:outputText value="content"/>
</af:panelGroupLayout>
</af:popup>

例15-7のコードはADF Facesに、ポップアップの内容をid属性で指定されたbuttonに合せることと、配置の位置としてafterStart(ポップアップをボタンのすぐ下に配置する)を使用することを指示するものです(図15-5を参照)。

図15-5 ボタンおよびポップアップ・コンテンツ

15.4 ポップアップのプログラムによる呼出し

アクション・コンポーネントによって生成されたactionEventへの応答として、プログラムでポップアップを表示、非表示または取り消すことができます。actionEventをサーバーに即時に配信してサーバー側ロジックを起動できるようにし、サーバー側ロジックの起動結果に対してポップアップを表示、非表示または取り消すことができるようにするには、この機能を実装します。

ここで説明するポップアップのプログラムによる呼出しは、showPopupBehaviorタグがactionEventをサーバーに即時に配信しない、15.3項「ポップアップの宣言的な呼出し」で説明したポップアップの呼出し方法とは異なります。

15.2項「ポップアップの宣言的な作成」で説明したように、コンポーネント(dialog、panelWindow、menuまたはnoteWindow)の1つをpopupコンポーネントに配置することで、目的のタイプのポップアップを作成します。popupコンポーネントが呼出し時に適切なコンテキストにあることを確認してください。これを簡単に行う方法の1つは、例15-8に示すようにページのバッキングBeanにバインドすることです。

例15-8 popupコンポーネントのバッキングBeanへのバインド

<af:popup
id="p1"
binding="#{mybean.popup}"
...
/>

これが完了したら、アクション・コンポーネントのactionListener属性がpopupコンポーネントを参照するように構成します。具体的には、ポップアップ・バインディングのアクセッサを呼び出します。

ポップアップの呼出し、取消または非表示を行うバッキングBeanメソッドのコードを作成します。例15-9に示すshowPopupバッキングBeanメソッドでは、HINT_LAUNCH_IDヒントを使用してアクション・コンポーネントを指定しています。このコンポーネントからactionEventがこのメソッドに渡されます。p1を使用して参照されているポップアップに対して、showメソッドを呼び出します。

例15-9 ポップアップを呼び出すバッキングBeanメソッド

public void showPopup(ActionEvent event) {
{
FacesContext context = FacesContext.getCurrentInstance();
UIComponent source = (UIComponent)event.getSource();
String alignId = source.getClientId(context);
RichPopup.PopupHints hints = new RichPopup.PopupHints();
hints.add(RichPopup.PopupHints.HintTypes.HINT_ALIGN_ID,source)
.add(RichPopup.PopupHints.HintTypes.HINT_LAUNCH_ID,source)
.add(RichPopup.PopupHints.HintTypes.HINT_ALIGN,
RichPopup.PopupHints.AlignTypes.ALIGN_AFTER_END);
p1.show(hints);
}

例15-10に、actionEventに対してポップアップを取り消すバッキングBeanメソッドを示します。

例15-10 ポップアップを取り消すバッキングBeanメソッド

public void cancelPopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.cancel();
}

例15-11に、actionEventに対してポップアップを非表示にするバッキングBeanメソッドを示します。

例15-11 ポップアップを非表示にするバッキングBeanメソッド

public void hidePopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.hide();
}

前の例のp1オブジェクトは、次のパッケージのRichPopupクラスのインスタンスを参照します。

oracle.adf.view.rich.component.rich.RichPopup

RichPopupの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

15.4.1 ポップアップをプログラムで呼び出す方法

ポップアップの表示、取消または非表示を行うバッキングBeanメソッドを参照するように、アクション・コンポーネントのactionListener属性を構成します。

始める前に:

popupコンポーネントをプログラムで呼び出す場合は、使用可能な構成オプションに関する知識が役立つ場合があります。詳細は、15.4項「ポップアップのプログラムによる呼出し」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

次のタスクを完了する必要があります。

15.2項「ポップアップの宣言的な作成」の説明に従って、サーバー側メソッドで呼び出すポップアップのタイプを作成します。

ポップアップをプログラムで呼び出す手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、アクション・コンポーネントをJSFページにドラッグ・アンド・ドロップします。たとえば、「ボタン」です。

2. 「プロパティ」ウィンドウで、「動作」セクションを開いて次の属性を設定します。

- PartialSubmit: trueを選択すると、ユーザーがアクション・コンポーネントをクリックした後にFusion Webアプリケーションのページ全体がレンダリングされることはなくなります。デフォルト値(false)を指定すると、エンド・ユーザーがアクション・コンポーネントを呼び出した後にアプリケーションのページ全体がレンダリングされます。ページ・レンダリングの詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- ActionListener: 評価した結果がバッキングBeanメソッドとなるEL式を指定します。実行時にエンド・ユーザーがアクション・コンポーネントを呼び出したときに、このメソッドのロジックが実行されます。

3. 手順2でアクション・コンポーネントがactionEventを渡すときに呼び出される、バッキングBeanのロジックをプログラミングします。
詳細は、例15-9「ポップアップを呼び出すバッキングBeanメソッド」、例15-10「ポップアップを取り消すバッキングBeanメソッド」または例15-11「ポップアップを非表示にするバッキングBeanメソッド」を参照してください。

15.4.2 ポップアップをプログラムで呼び出した場合の処理

実行時に、エンド・ユーザーは、ポップアップの表示、取消または非表示を行うためにサーバー側メソッドを呼び出すように構成されているアクション・コンポーネントを呼び出すことができます。たとえば、図15-6に、popupコンポーネントの内部にレンダリングするpanelWindowコンポーネントを示します。panelWindowコンポーネントは、2つのボタン(「取消」および「非表示」)を公開します。前者はcancelメソッド、後者はhideメソッドを呼び出します。ページのtableコンポーネントのSupplierName列内にレンダリングされているlinkコンポーネントをエンド・ユーザーが呼び出すと、ポップアップが表示されます。

図15-6 サーバー側メソッドによって呼び出されるpopupコンポーネント

15.5 ポップアップへのコンテキスト情報の表示

ユーザーがページでタスクを完了するのにより多くの情報が必要だが、ページにアクセスするたびに必要にはならない情報や、情報を表示するためにダイアログを起動する複数のボタンによって、ページが乱雑になるのは望ましくない場合があります。コンポーネントの右クリックで起動するポップアップに情報を表示することも考えられますが、その情報をポップアップで参照できることがユーザーからはわかりません。

contextInfoコンポーネントでは、ポップアップに追加情報を表示し、追加情報が使用可能であることをユーザーに通知することもできます。contextInfoコンポーネントを、コンテキスト情報をサポートするコンポーネントのコンテキスト・ファセットに配置すると、図15-7に示すように、小さなオレンジ色の正方形がコンポーネントの左上に表示されます。

図15-7 contextInfoに表示される正方形

ユーザーが正方形の上にカーソルを置くと、図15-8に示すようにノート・アイコンの付いた大きな三角形とツールチップが表示され、追加情報が使用可能であることが示されます。

図15-8 contextInfoコンポーネントは追加情報が使用可能であることを示す

showPopupBehaviorタグがcontextInfoコンポーネントの子の1つであるため、参照されるポップアップはユーザーが情報アイコンをクリックしたときに表示されます(図15-9を参照)。

図15-9 contextInfoコンポーネントから起動されたダイアログ

15.5.1 コンテキスト情報の作成方法

showPopupBehaviorコンポーネントをcontextInfoコンポーネントの子として使用すると、ポップアップ・コンポーネントを、contextInfoコンポーネントを含むコンポーネントに位置揃えできます。

始める前に:

1. contextInfoコンポーネントの親になるコンポーネントを作成します。次のコンポーネントではcontextInfoコンポーネントがサポートされます。

- column

- link

- inputComboboxListOfValues

- inputListOfValues

- inputText

- outputFormatted

- outputText

- selectOneChoice

2. 15.2項「ポップアップの宣言的な作成」の説明に従って、表示するポップアップを作成します。

3. 他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

contextInfoコンポーネントを使用する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「コンテキスト情報」をドラッグし、追加情報のアイコンを表示するコンポーネントのContextファセットにドロップします。

ヒント:

ファセットがビジュアル・エディタに表示されていない場合は、「構造」ウィンドウでコンポーネントを右クリックして「ファセット - コンポーネント名」→「コンテキスト」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

2. contextInfoコンポーネントが表示されるときにサーバー側ロジックを実行する必要がある場合は、「プロパティ」ウィンドウの「動作」セクションを開いて、イベントを処理できるハンドラにContextInfoListenerをバインドします。

注意:

showPopupBehaviorタグを使用してポップアップを起動する場合は、サーバーへのcontextInfoEventの配信が取り消されます。このイベントに基づいてサーバー側ロジックを起動する必要がある場合は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」の説明に従って、JavaScriptまたはカスタム・イベントを使用してポップアップを起動する必要があります。

3. 「コンポーネント」ウィンドウの「操作」パネルの「動作」グループから、「ポップアップ表示動作」をドラッグし、contextInfoに子としてドロップします。

4. エディタでshowPopupBehaviorタグが選択されている状態で、「プロパティ」ウィンドウで属性を設定します(15.3.1項「af:showPopupBehaviorタグを使用してポップアップを宣言的に呼び出す方法」の説明を参照)。TriggerTypeには、contextInfoと入力してください。

15.6 インライン・ポップアップの自動取消の制御

popupコンポーネントを他の多数のコンポーネントとともに使用して、インライン・ポップアップを作成できます。つまり、インライン・ウィンドウ、ダイアログおよびポップアップ・メニューです。他のコンポーネントには次のものがあります。

- インライン・ダイアログを作成するためのダイアログ・コンポーネント
詳細は、15.2.1項「ダイアログの作成方法」を参照してください。

- インライン・ウィンドウを作成するためのpanelWindowコンポーネント
詳細は、15.2.2項「パネル・ウィンドウの作成方法」を参照してください。

- ポップアップ・メニューを作成するためのメニュー・コンポーネント
詳細は、15.2.3項「ポップアップ・メニューの作成方法」を参照してください。

- ノート・ウィンドウを作成するためのnoteWindowコンポーネント
詳細は、15.2.4項「ノート・ウィンドウの作成方法」を参照してください。

デフォルトでは、Fusion Webアプリケーションは、インライン・ポップアップを定義するメタデータが置換された場合にインライン・ポップアップを自動的に取り消します。この状況が発生するシナリオの一部を次に示します。

- partialSubmitプロパティがfalseに設定されているアクション・コンポーネントの呼出し。Fusion Webアプリケーションは、このようなアクション・コンポーネントを呼び出した後でページ全体をレンダリングします。対照的に、アクション・コンポーネントのpartialSubmitプロパティがtrueに設定されている場合は、Fusion Webアプリケーションはコンテンツを部分的にレンダリングします。ページ・レンダリングの詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- エンド・ユーザーがコンテンツを表示または非表示にするための切替えアイコンをレンダリングするコンポーネントは、popupコンポーネントをホストします。たとえば、showDetailItemコンポーネントやpanelTabbedコンポーネントなどです。切替えアイコンをレンダリングするコンポーネントの使用の詳細は、9.9項「コンテンツの動的な表示および非表示」を参照してください。

- Fusion Webアプリケーションがインライン・ポップアップを表示するときにフェイルオーバーが発生します。フェイルオーバー時に、Fusion Webアプリケーションはページ全体を置換します。

前のリストで説明したデフォルトの動作は、インライン・ポップアップ・コンポーネントの自動取消を無効にすることで変更できます。これは、前述のいずれかのイベントが発生した場合にFusion Webアプリケーションがインライン・ポップアップを自動的に取り消さないことを意味します。かわりに、Fusion Webアプリケーションはインライン・ポップアップをリストアします。

15.6.1 インライン・ポップアップの自動取消を無効にする方法

popupコンポーネントのautoCancelプロパティをdisabledに設定することで、インライン・ポップアップの自動取消を無効にします。

始める前に:

他のコンポーネントが機能に与える影響を理解することが役立つ場合があります。詳細は、15.6項「インライン・ポップアップの自動取消の制御」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

インライン・ポップアップの自動取消を制御する手順:

1. 「構造」ウィンドウで、自動取消動作を構成するaf:popupコンポーネントを右クリックし、「プロパティに移動」を選択します

2. 「プロパティ」ウィンドウの「共通」セクションを開き、「AutoCancel」ドロップダウン・リストで「disabled」を選択します。

15.6.2 インライン・ポップアップの自動取消を無効にした場合の処理

例15-12に示すように、JDeveloperは、af:popupコンポーネントのautoCancelプロパティの値をdisabledに設定します。

例15-12 インライン・ポップアップの自動取消を防ぐためのメタデータ

<af:popup id="p1" autoCancel="disabled">
...
</af:popup>

実行時に、Fusion Webアプリケーションは、ページを再レンダリングするコマンドの呼出し前にインライン・ポップアップが表示された場合に、ページを再レンダリングした後でインライン・ポップアップをリストアします。

15.7 ポップアップの入力フィールドのリセット

resetListenerコンポーネントをpopupコンポーネントとともに使用すると、ユーザーが入力フィールドの入力値をリセットできるようになります。popupコンポーネントにレンダリングする入力コンポーネントに対してこの機能を実装するユースケースを次に示します。

- エンド・ユーザーに、前に入力した不適切な値のリセットを許可する

- 値を削除する。この場合、エンド・ユーザーが入力した値をアプリケーションがサーバーに送信する前に、popupコンポーネントがpopupCanceledEventを呼び出します。
popupCancelEventを呼び出すエンド・ユーザー操作の例としては、ボタンのクリック(たとえば「閉じる」というラベルの付いたボタン)、ポップアップ・ダイアログのタイトル・バーにある取消しアイコンのクリック、[Esc]キーの押下などがあります。

popupコンポーネントの構成方法に応じて、データがクライアントにキャッシュされることがあります。たとえば、popupコンポーネントのcontentDelivery属性をimmediateに設定した場合、アプリケーションは常にデータをクライアントにキャッシュします。

contentDelivery属性に対して選択した設定によってpopupコンポーネントのコンテンツ配信方針がどのように決定されるかの詳細は、15.2項「ポップアップの宣言的な作成」および15.2.5項「実行時に行われる処理: popupコンポーネントのイベント」を参照してください。

例15-13に、contentDelivery属性がimmediateに設定され、15.2.1項「ダイアログの作成方法」で説明したようにユーザーのポップアップがdialogEventsを生成する事前構成済のコントロールとともにdialogコンポーネントをレンダリングするpopupコンポーネントのメタデータを示します。このシナリオでは、エンド・ユーザーが入力したデータはクライアントにキャッシュされます。アプリケーションは、リセットするデータをサーバーに送信しません。また、dialogコンポーネントによってレンダリングされる事前構成済コントロールは、検証エラーが発生した場合にポップアップが閉じない原因となることがあります。

例15-13 popupコンポーネントのresetListenerタグ

<af:popup id="popup" contentDelivery="immediate">
<af:resetListener type="popupCanceled"/>
</af:popup>

popupコンポーネントとは無関係にresetListenerコンポーネントを使用する方法の詳細は、20.5.2項「入力フィールドをリセットするためのアクション・コンポーネントの使用方法」を参照してください。

注意:

resetListenerコンポーネントのtype属性をpopupCanceledに設定すると、popupコンポーネントのresetEditableValues属性をwhenCanceledに設定するのと同じ機能が提供されます。popupコンポーネントのresetEditableValues属性の設定の詳細は、15.2.1項「ダイアログの作成方法」を参照してください。

15.7.1 ポップアップの入力フィールドのリセット方法

エンド・ユーザーがポップアップの入力フィールドのデータをnullにリセットできるようにするには、resetListenerコンポーネントのtype属性をpopupCanceledに設定します。

始める前に:

popupコンポーネントでこの機能を構成できるユースケースを理解することが役立つ場合があります。詳細は、15.7項「ポップアップの入力フィールドのリセット」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、15.1.2項「ポップアップ・ダイアログ、メニューおよびウィンドウの追加機能」を参照してください。

ポップアップの入力フィールドをリセットする手順:

1. 15.2項「ポップアップの宣言的な作成」の説明に従って、必要なポップアップ・ダイアログのタイプを作成します。

2. 「コンポーネント」ウィンドウの「操作」パネルの「リスナー」グループから、リセット・リスナーをpopupコンポーネントに直接の子としてドラッグ・アンド・ドロップします。

3. JDeveloperが表示する「リセット・リスナーの挿入」ダイアログで、popupCanceledをresetListenerコンポーネントが応答するイベントのタイプとして入力します。
「リセット・リスナーの挿入」ダイアログで「ヘルプ」をクリックして、サポートされる値のリストを表示します。

15.7.2 入力フィールドをリセットするようにポップアップを構成した場合の処理

popupコンポーネントとresetListenerコンポーネントでエンド・ユーザーがpopupコンポーネントの入力フィールドをnullにリセットできるように構成した場合、JDeveloperは例15-14に示すようなエントリを作成します。

例15-14 リセット・リスナーを使用して入力フィールドをリセットするように構成されたpopupコンポーネント

<af:popup id="popupDialog" contentDelivery="lazyUncached"
popupCanceledListener="#{demoInput.resetPopupClosed}">
<af:dialog title="Enter an Incorrect Value">
<af:inputText id="it2" label="Always-incorrect Value" value="#{demoInput.value}">
<f:validator binding="#{demoInput.obstinateValidator2}"/>
</af:inputText>
</af:dialog>
<af:resetListener type="popupCanceled"/>
</af:popup>

図15-10に示すように、実行時にpopupCanceledイベントを生成するエンド・ユーザー操作により、resetListenerコンポーネントはpopupコンポーネントの入力フィールドの値をnullにリセットします。

図15-10 入力フィールドをリセットするpopupコンポーネント

16 メニュー、ツールバーおよびツールボックスの使用方法

この章では、メニューとツールバーをADF Facesのmenu、menuBar、commandMenuItem、goMenuItem、toolbarおよびtoolboxの各コンポーネントを使用して作成する方法を説明します。

ページの階層をナビゲートできるナビゲーション・メニューの作成の詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

この章では、次の項目について説明します。

- 16.1項「メニュー、ツールバーおよびツールボックスについて」

- 16.2項「メニュー・バーでのメニューの使用方法」

- 16.3項「ツールバーの使用方法」

16.1 メニュー、ツールバーおよびツールボックスについて

メニュー・バーとツールバーでは、メニュー、ボタンおよびその他の単純なコンポーネントを水平バーに編成できます。ユーザーがバーのメニューをクリックすると、メニューがドロップダウン表示され、ユーザーがメニュー項目を選択すると、アプリケーション内でなんらかのアクションが発生します。ツールバーのアイコンでも、アプリケーションでなんらかのアクションが発生します。図16-1に、メニューとツールバーの作成に使用される様々なコンポーネントを示します。

図16-1 メニューおよびツールバー・コンポーネント

16.1.1 メニュー・コンポーネントのユースケースと例

メニュー・コンポーネントを使用して、ユーザーが項目の追加または編集、データの検索、ビューの変更またはヘルプの起動を行えるメニューを作成します。たとえば、図16-2に示すように、ADF Facesデモ・アプリケーションには、メニュー・バーとツールバーの両方があります。

図16-2 File Explorerアプリケーションのメニュー・バーおよびツールバー

図16-3に示すように、ユーザーがメニュー・バーのメニュー項目を選択すると、menuコンポーネントにより、メニュー項目のリストが表示されます。

図16-3 File Explorerアプリケーションのメニュー

図16-4に示されているように、メニューはネスト可能です。

図16-4 ネストしたメニュー項目

ツールバーのボタンでも、ユーザーはアプリケーションに対してなんらかのアクションを呼び出したり、標準メニューと同じ動作をするポップアップ・メニューを開いたりできます。

ツールバーおよびメニュー・バーは、ツールボックスを使用して編成できます。ツールボックスを使用すると、同じ行にあるツールバーの相対的なサイズや、複数レイヤーのツールバーおよびメニュー・バーを垂直方向に定義できます。

注意:

表にメニューおよびツールバーを作成する場合は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」の手順に従ってください。

コンポーネントのポップアップ・メニュー(ユーザーがコンポーネントを右クリックすると起動されるメニュー)を作成する場合は、15.2.3項「ポップアップ・メニューの作成方法」の手順に従います。

16.1.2 メニューおよびツールバー・コンポーネントの追加機能

メニューおよびツールバー・コンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページにこれらのコンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。メニューおよびツールバー・コンポーネントで使用できる他の機能へのリンクを次に示します。

- 機能の呼出し: ADF Facesには、ファイルのダウンロードや送信した値のリセットなどの機能を呼び出すためにメニュー・コマンド・コンポーネントとともに使用できるタグが用意されています。詳細は、20.5項「ボタンまたはリンクの機能の呼出し目的での使用」を参照してください。

- 表メニュー: 表の上に表示され、(アプリケーション全体ではなく)その表でのみ動作するメニューおよびツールバーを作成できます。詳細は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

- ポップアップ・メニュー: ユーザーがUIの項目を右クリックしたときにポップアップで起動するメニューを作成できます。詳細は、15.2.3項「ポップアップ・メニューの作成方法」を参照してください。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- イベント: コマンド・メニュー・コンポーネントを使用してアクション・イベントを起動できます。イベントの詳細は、第6章「イベントの処理」を参照してください。アクション・イベントの詳細は、20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

- アクセシビリティ: メニュー・コンポーネントの特定の属性を使用すると、キーボードを使用してメニューを開くためのショートカットを作成できます。アクセス・キーの定義方法は、33.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。アクセシビリティの詳細は、33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」を参照してください。

- ローカライゼーション: 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- スキン: スキンを変更することで、メニューのルック・アンド・フィール(選択したメニュー項目の表示に使用されるアイコンなど)をいくつかの基本機能(表示されるメニュー項目の最大数など)とともに変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

16.2 メニュー・バーでのメニューの使用方法

メニュー・バー項目(File Explorerアプリケーションの「ファイル」など)を含むバーのレンダリングには、menuBarコンポーネントを使用します。この項目に該当するものには、menuコンポーネント(垂直メニューを保持する)の他に、commandMenuItemコンポーネント(アプリケーションに対する操作を呼び出す)やgoMenuItemコンポーネント(URLを呼び出す)があります(図16-5を参照)。

図16-5 menuBarおよび子コンポーネント

メニュー・コンポーネントにcommandMenuItemコンポーネントまたはgoMenuItemコンポーネントを入れることや、menuコンポーネントをmenuコンポーネントの内側にネストしてサブメニューを作成することもできます。図16-6に、メニューの作成に使用されている様々なコンポーネントを示します。

図16-6 メニューの作成に使用されているコンポーネント

ツールボックス内に配置することにより、複数のメニュー・バーを使用できます。ツールボックス内に配置すると、メニュー・バーが縦に並べて表示され、ツールボックスの最初のメニュー・バーが一番上に、最後のメニュー・バーが一番下に表示されます。(ツールボックス内にグループ化することで)1つのツールボックス行で複数のメニュー・バーを使用すると、flex属性によって、どのメニュー・バーが最も多くの領域を占めるかが決定されます。

メニュー・バーを縦ではなく横に並べて表示する場合は、メニュー・バーをgroupコンポーネント内に配置します。

ヒント:

toolboxコンポーネントを使用して、メニュー・バーとツールバーをグループ化することや、複数のメニュー・バーをグループ化することが可能です。groupコンポーネントを使用して、同じ行のメニュー・バーとツールバーをグループ化できます。

メニュー・バー内で、1つのコンポーネントを拡大するように設定して、メニュー・バーが常にその親コンテナと同じサイズになるようにすることができます。たとえば、図16-7では、メニュー・バーは、「無効なGMI」メニューとコンポーネント・ガイド・ボタンの間に配置されるスペーサ・コンポーネントを拡大するように設定されています。ウィンドウがサイズ変更されると、スペーサ・コンポーネントが拡大または縮小されて、メニュー・バーは常に親と同じ幅で表示されます。このようなスペーサ・コンポーネントを使用すると、スペーサの右側にあるコンポーネントがメニュー・バーに右揃えされたままになります。

図16-7 スペーサ・コンポーネントの拡大と縮小

メニュー・バー内のすべてのコンポーネントが表示されなくなるようにウィンドウがサイズ変更されると、メニュー・バーに、図16-8に示すように矢印カーソルで識別されるオーバーフロー・アイコンが表示されます。

図16-8 メニュー・バーのオーバーフロー・アイコン

オーバーフロー・アイコンをクリックすると、図16-9に示すように、残りのコンポーネントがポップアップ・ウィンドウに表示されます。

図16-9 オーバーフロー・ポップアップ・ウィンドウ内のmenuコンポーネント

メニューおよびサブメニューは、ブラウザ・ウィンドウ上で連結解除して移動できるように設定できます。図16-10に、連結解除可能に構成された連結解除可能メニューのメニュー1サブメニューを示します。メニューの先頭には、連結解除が可能であることを示すバーがレンダリングされています。

図16-10 連結解除可能メニュー

ユーザーは、連結解除可能メニューをブラウザ内の任意の場所にドラッグできます。図16-11に示すように、マウス・ボタンを離すと、そのメニューはユーザーが閉じるまでアプリケーション上に残ります。

図16-11 移動している連結解除可能メニュー

ヒント:

ユーザーが次の操作をする可能性がある場合は、連結解除可能メニューの使用を検討してください。

- ページで類似のコマンドを繰り返し実行する場合。

- 大規模な表、ツリー表またはツリーにおいて、異なる行のデータで類似のコマンドを実行する場合。

- 長くて幅の広い表、ツリー表またはツリーでデータを表示する場合。ユーザーは一度クリックすることで、表示または非表示にする列やブランチを選択できます。

- 長くて幅の広い表、ツリー表またはツリーでデータを書式設定する場合。

menuおよびcommandMenuItemコンポーネントのそれぞれに、アイコン・イメージを含めることができます。図16-12に示す「削除」メニュー項目は、削除アイコン(赤色のx)を表示するように構成されています。

図16-12 メニューで使用されているアイコン

グラフィックを常に表示するだけでなく、メニュー項目が選択されたときにグラフィックを表示するようにcommandMenuItemコンポーネントを構成できます。たとえば、選択されたときにチェックマークを表示するようにcommandMenuItemコンポーネントを構成したり、グループ内の項目の1つが選択されたときにラベルの横にアイコンが表示されるようにメニュー項目をグループ化してラジオ・ボタンのグループのような動作をするように構成したりできます。図16-13に、選択時にチェックマークを使用するよう構成された「フォルダ」メニュー項目を含む「表示」メニューを示します。「表」、「ツリー表」および「リスト」メニュー項目はラジオ・ボタンとして構成されており、ユーザーは1つのグループのみ選択できます。

図16-13 選択されたメニュー項目を示すアイコンとラジオ・ボタン

commandMenuItemコンポーネントは、反意語を含むように構成することもできます。反意語は、ユーザーがメニュー項目を選択すると別のテキストを表示します。図16-14に、「特別」メニュー内の「開く」メニュー項目を示します。

図16-14 File Explorerアプリケーションの「編集」メニュー

図16-14に示すcommandMenuItemコンポーネントは「元に戻す」というメニュー項目のためのものであり、この項目は反意語として構成されています。ユーザーが「元に戻す」を選択すると、次回このメニューをユーザーが表示したときに、このメニュー項目には反意語である「リストア」が表示されます(図16-15を参照)。

図16-15 反意語のメニュー項目

ユーザーがメニュー項目を選択するとアクションが発生するため、commandMenuItemコンポーネントのactionまたはactionListener属性を、必要な機能を実行するメソッドにバインドする必要があります。

メニューには、commandMenuItemコンポーネントの他、1つ以上のgoMenuItemコンポーネントを含めることもできます。これらはナビゲーション・コンポーネントであり、直接ページ・ナビゲーションを実行するという点でlinkコンポーネントに似ていますが、ActionEventイベントは配信しません。図16-16に、外部のWebサイトにナビゲートするために使用される3つのgoMenuItemコンポーネントを示します。

図16-16 goMenuItemコンポーネントを使用できるメニュー

メニュー・バーから起動されるメニューのみでなく、ユーザーがUIコンポーネントを右クリックした場合や、ユーザーがコマンド・コンポーネントをクリックした場合に起動されるポップアップ・メニューも作成できます。詳細は、15.2.3項「ポップアップ・メニューの作成方法」を参照してください。

注意:

ADF Facesには、ユーザーが現行ページの印刷可能バージョンを表示できる埋込み機能を持つボタンが用意されています。メニューおよびメニュー・バーは、これらのページにはレンダリングされません。詳細は、「ADF Facesのクライアント動作タグの使用」を参照してください。

デフォルトで、メニューのコンテンツは、ページがレンダリングされるとすぐに送信されます。メニューで大量の子(複数のmenuおよびcommandMenuItemコンポーネント)を使用することを計画している場合は、遅延コンテンツ配信を使用するようにメニューを構成することを選択できます。これは、メニューがアクセスされるまで、子コンポーネントがサーバーから取得されないことを意味します。

注意:

ポップアップ・メニューとして使用されるメニューのコンテンツ配信は、メニュー自体ではなく、親のポップアップ・ダイアログにより決定されます。

主にアプリケーション全体におけるナビゲーションを可能にするメニューで、アプリケーションの選択項目に対する変更には使用されないメニューも作成できます。このタイプのメニューを作成するには、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

16.2.1 メニュー・バーのメニューの作成および使用方法

メニューを作成するには、まず、メニューが表示されるメニュー・バーを作成する必要があります。その後、必要に応じてmenuおよびcommandMenuItemコンポーネントを追加および構成します。

注意:

表にメニューを作成する場合は、12.9項「表メニュー、ツールバーおよびステータス・バーの表示」に説明されている手順に従ってください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、16.2項「メニュー・バーでのメニューの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、16.1.2項「メニューおよびツールバー・コンポーネントの追加機能」を参照してください。

メニュー・バーのメニューを作成および使用する手順:

1. 複数のメニュー・バー、またはツールバーとメニュー・バーの組合せを使用する予定の場合は、toolboxコンポーネントを作成します。作成するには、「ツールボックス」コンポーネントを「コンポーネント」ウィンドウの「メニューおよびツールバー」パネルからドラッグ・アンド・ドロップします。

ヒント:

panelHeader、showDetailHeaderおよびshowDetailItemコンポーネントでは、セクション・ヘッダーおよびアコーディオン・パネル・ヘッダーにtoolboxやtoolbarを追加するためのtoolbarファセットがサポートされています。

2. 「コンポーネント」ウィンドウから「メニュー・バー」をドラッグ・アンド・ドロップしてメニュー・バーを作成します。toolboxコンポーネントを使用している場合は、「メニュー・バー」をtoolboxコンポーネントの直接の子としてドロップする必要があります。

ヒント:

ツールボックスでは、iterator、switcherおよびgroupの各コンポーネントを直接の子として使用することもできます。ただし、これらのコンポーネントが、ツールボックスの本来の直接の子である子コンポーネントをラップしていることが条件です。ツールボックスの詳細は、16.3項「ツールバーの使用方法」を参照してください。

3. ツールボックスに複数のメニュー・バーをグループ化する場合は、各メニュー・バーについて、「外観」セクションを開き、flex属性を設定して、各メニュー・バーの相対サイズを決定します。flex属性の数値が大きいほど、ツールボックスが長くなります。例16-4に示すメニュー・バーのセットでは、menuBar2が最も長く、次に長いのはmenuBar4です。flex属性が設定されていないことが理由で残りのメニュー・バーはサイズが同一になり、menuBar4よりも短くなります。

例16-1 ツールバーの長さを決定するflex属性

<af:toolbox>
<af:menuBar id="menuBar1" flex="0">
<af:menu text="MenuA"/>
</af:menBar>
<af:menuBar id="menuBar2" flex="2">
<af:menu text="MenuB"/>
</af:menuBar>
<af:menuBar id="menuBar3" flex="0">
<af:menu text="MenuC"/>
</af:menuBar>
<af:menuBar id="menuBar4" flex="1">
<af:menu text="MenuD"/>
</af:toolbar>
</af:toolbox>

パフォーマンスのヒント:

実行時、使用可能なブラウザの領域が、toolboxのコンテンツの表示に必要な領域より少ない場合、表示されていない項目をユーザーが選択して表示できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。toolboxコンポーネント内の子コンポーネントの数、および子の複雑さが、オーバーフローのパフォーマンスに影響します。可能な場合は、オーバーフローしないように、toolboxコンポーネントのサイズを設定する必要があります。詳細は、16.3.2項「実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法」を参照してください。

ヒント:

groupコンポーネントを使用して、同じ行に表示するメニュー・バー(またはメニュー・バーとツールバー)をグループ化できます。groupコンポーネントを使用しない場合、メニュー・バーは次の行に表示されます。

flex属性がどのように機能するかの詳細は、16.3.2項「実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法」を参照してください。

4. 必要な数のmenuコンポーネントをメニュー・バーに挿入します。挿入するには、「コンポーネント」ウィンドウから「メニュー」をドラッグし、menuBarコンポーネントに子としてドロップします。
commandMenuItemコンポーネントを直接メニュー・バーに挿入することもできます。このようにするには、「コンポーネント」ウィンドウの「メニューおよびツールバー」パネルから「メニュー・アイテム」をドラッグ・アンド・ドロップします。これにより、ツールバー・ボタンと同じようにレンダリングされるcommandMenuItemコンポーネントが作成されます。

ヒント:

通常はメニュー・バーの直接の子である子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、メニュー・バーにもこららのコンポーネントを直接の子として使用できます。

5. 各menuコンポーネントに対し、「プロパティ」ウィンドウの「外観」セクションを開いて次の属性を設定します。

- Text: メニューのラベル・テキストを入力します。アクセス・キー(キーボードを使用してメニューにアクセスする際に使用する文字)も設定する場合は、この属性は空白のままにしておき、かわりにtextAndAccessKeyの値を入力します。

- TextAndAccessKey: 従来のアンパサンド表記を使用して、メニュー・ラベルとアクセス・キーを入力します。たとえば、&amp;Fileではメニュー・ラベルが「File」に設定され、同時に、メニュー・アクセス・キーが文字Fに設定されます。アクセス・キーとアンパサンド表記の詳細は、33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」を参照してください。

- Icon: ドロップダウン・リストを使用してアイコンを選択します。アイコンがこのメニューに表示されない場合は、リストの右側にあるドロップダウン・メニューを使用して「編集」を選択し、アイコンを参照して選択します。

6. メニューを連結解除可能にする場合は(図16-10を参照)、「プロパティ」ウィンドウの「動作」セクションを開き、Detachable属性をtrueに設定します。実行時、ユーザーはメニューをドラッグして連結を解除し、画面の任意の場所にドロップできます(図16-11を参照)。

7. メニューで遅延コンテンツ配信を使用する場合は、ContentDelivery属性をlazyに設定します。

注意:

コンテンツの遅延配信を使用する場合、メニューのコンテンツはメニューがアクセスされるまで把握されないため、子のcommandMenuItemコンポーネントに設定されているアクセラレータが機能しなくなります。メニューでアクセラレータをサポートする必要がある場合は、ContentDeliveryをimmediateに設定する必要があります。

注意:

メニューがポップアップ・ダイアログまたはウィンドウ内で使用される場合、ポップアップ・ダイアログまたはウィンドウによりメニューのコンテンツ配信が決定されるため、ContentDeliveryはimmediateに設定されたままにします。

8. ナビゲーションとともになんらかのアクションを呼び出すメニュー項目を作成するには、「コンポーネント」ウィンドウから「メニュー・アイテム」をドラッグし、menuコンポーネントに子としてドロップしてcommandMenuItemコンポーネントを作成します。垂直方向のメニューの項目を定義するいくつかのcommandMenuItemコンポーネントを作成します。必要な場合には、commandMenuItemコンポーネントをgroupコンポーネントでラップし、項目をグループとして表示できます。
例16-2に「フォルダ」および「検索」メニュー項目を1つのグループにグループ化し、「表」、「ツリー表」および「リスト」メニュー項目を2番目のグループにグループ化し、「リフレッシュ」メニュー項目を最後に単独で表示する簡略化されたコードを示します。

例16-2 メニュー項目のグループ化

<af:menu id="viewMenu"
<af:group>
<af:commandMenuItem type="check" text="Folders"/>
<af:commandMenuItem type="check" text="Search"/>
</af:group>
<af:group>
<af:commandMenuItem type="radio" text="Table"/>
<af:commandMenuItem type="radio" text="Tree Table"/>
<af:commandMenuItem type="radio" text="List"/>
</af:group>
<af:commandMenuItem text="Refresh"/>
</menu>

図16-17に、最初にアクセスされた際にメニューがどのように表示されるかを示します。

注意:

デフォルトでは、ADF FacesコンポーネントではSkyrosスキンが使用されます。これは、独自のスキンを作成することで変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

図16-17 type属性を使用してグループ化したメニュー項目

ヒント:

デフォルトでは、メニューに表示できるのは14項目のみです。メニューに15項目以上追加すると、残りの項目へのアクセスに使用するスクロールバーとともに、最初の14項目が表示されます。表示される項目の数を変更する場合は、af|menu {-tr-visible-items}スキニング・キーを編集します。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

既存のmenuコンポーネントに別のmenuコンポーネントを挿入して、サブメニューを作成できます(図16-4を参照)。

ヒント:

通常はメニューの直接の子である子コンポーネントをiteratorおよびswitcherコンポーネントにラップすれば、メニューにもこれらのコンポーネントを直接の子として使用できます。

9. 各commandMenuItemコンポーネントに対し、「プロパティ」ウィンドウの「共通」セクションを開いて次の属性を設定します。

- Type: このメニュー項目のタイプを指定します。メニュー項目のタイプが指定されると、ADF Facesにより、ビジュアルなインジケータ(ラジオ・ボタンなど)および動作の切替えがメニュー項目に追加されます。実行時に、ユーザーがタイプ(default以外)の指定されたメニュー項目を選択すると、ADF Facesにより、ビジュアルなインジケータまたはメニュー項目ラベルが表示されます。次に示す使用可能なtype値のいずれかを使用します。

- default: メニュー項目にはタイプが割り当てられません。選択されているかどうかに関係なく、メニュー項目は同じ方法で表示されます。

- antonym: メニュー項目ラベルが表示されます。メニュー項目が選択されると、(メニュー項目が選択されない場合に表示される)textまたはtextAndAccessKey属性の値で定義されたメニュー項目ではなく、SelectedText属性に設定された値が表示されます。このタイプを選択する場合には、SelectedTextに値を設定する必要があります。

- check: スキンに応じて、メニュー項目ラベルの横の正方形またはチェック・マークを切り替えます。正方形は、メニュー項目が選択されている場合に青で表示され、選択されていない場合はグレー表示されます。

- radio: メニュー項目ラベルの隣のラジオ・ボタンを切り替えます。ラジオ・ボタンは、メニュー項目が選択されている場合に青い円で表示され、選択されていない場合はグレー表示されます。

- Text: メニュー項目のラベル・テキストを入力します。アクセス・キー(キーボードを使用して項目にアクセスする際に使用する文字)も表示する場合は、この属性は空にして、かわりにTextAndAccessKeyに値を入力します。または、accessKey属性を使用して、アクセス・キーを別に設定することもできます。

- Selected: このメニュー項目を選択された状態で表示する場合にtrueに設定します。selected属性がサポートされているのはcheck、radioおよびantonymタイプのメニュー項目のみです。

- SelectedText: このメニュー項目が選択された場合に、メニュー項目に表示する代替のラベルを設定します。この値は、antonymを除くすべてのタイプで無視されます。

10. 「外観」セクションを開き、次の属性を設定します。

- Icon: ドロップダウン・リストを使用してアイコンを選択します。アイコンがこのメニューに表示されない場合は、リストの右側にあるドロップダウン・メニューを使用して「編集」を選択し、アイコンを参照して選択します。

- Accelerator: このメニュー項目を選択してそのコマンドをアクティブ化するためのキーストロークを入力します(たとえばControl N)。ADF Facesによってキーストロークが変換され、キーストロークのテキスト・バージョン(たとえば「Ctrl+N」)がメニュー項目ラベルの隣に表示されます(図16-4を参照)。

注意:

コンテンツの遅延配信を使用する場合、メニューのコンテンツはアクセスされるまで把握されないため、子のcommandMenuItemコンポーネントに設定されているアクセラレータが機能しなくなります。メニューでアクセラレータ・キーをサポートする必要がある場合は、contentDelivery属性をimmediateに設定しておく必要があります。

- TextAndAccessKey: 従来のアンパサンド表記を使用して、メニュー項目ラベルとアクセス・キーを入力します。たとえば、&amp;Saveではメニュー項目ラベルがSaveに設定され、同時に、メニュー項目アクセス・キーが文字Sに設定されます。アクセス・キーとアンパサンド表記の詳細は、33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」を参照してください。

11. 「動作」セクションを開き、次の属性を設定します。

- Action: メニュー項目が選択された場合に起動される、オブジェクト(マネージドBeanなど)のアクション・メソッドに対して評価されるEL式を使用します。式は、パラメータが指定されず、java.lang.Objectオブジェクトを返すpublicメソッドに対して評価される必要があります。
commandMenuItemコンポーネントによって生成されたアクションのレスポンスとしてナビゲートさせる場合は、EL式を入力するかわりに、静的アクションの結果値をaction属性の値として入力します。partialSubmit属性をfalseに設定するか、リダイレクトを使用する必要があります。アプリケーションにおけるナビゲーションの構成方法の詳細は、3.3項「ページ・フローの定義」を参照してください。

- ActionListener: このメニュー項目が選択されたときに通知されるアクション・リスナー・メソッドを表す式を指定します。このメソッドをaction属性にバインドされたメソッドのかわりに使用して、action属性でナビゲーションのみ処理できます。式では、ActionEventパラメータを受け取るpublicメソッドを評価し、戻り型がvoidである必要があります。

12. ナビゲートのみを行うメニュー項目(通常は外部サイトへのナビゲート)を作成するには、「コンポーネント」ウィンドウから「メニュー・アイテム(実行)」をメニューに子としてドラッグ・アンド・ドロップします。

13. 「プロパティ」ウィンドウの「共通」セクションを開いて、次の属性を設定します。

- Text: リンクのテキストを入力します。

ヒント:

かわりに、textAndAccessKey属性を使用して、リンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、33.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

- Destination: リンクのナビゲート先のページのURIを入力します。たとえば、オラクル社のホームページにナビゲートするには、http://www.oracle.comと入力します。

- TargetFrame: ドロップダウン・リストを使用して、新しいページを表示する必要がある場所を指定します。次の値の1つを選択します。

- _blank: リンクにより、ドキュメントは新しいウィンドウに開かれます。

- _parent: リンクにより、ドキュメントは親ウィンドウに開かれます。たとえば、リンクがダイアログに表示された場合、結果のページは親ウィンドウにレンダリングされます。

- _self: リンクにより、ドキュメントは同じページまたはリージョンに開かれます。

- _top: リンクにより、ページ全体が置き換えられて、ドキュメントはウィンドウ全体に開かれます。

14. 親コンポーネントの幅と等しくなるようにメニュー・バーを拡大させるには、「構造」ウィンドウでmenuBarコンポーネントを選択してから「プロパティ」ウィンドウの「外観」セクションを開き、StretchIdをメニュー・バーの中のコンポーネントのIDに設定します。このコンポーネントが拡大されて、メニュー・バーのサイズが親と同一になります。メニュー・バーのその他のコンポーネントは静的サイズのままですが、その1つのコンポーネントは拡大されます。
また例16-3に示すように、spacerコンポーネントを挿入し、そのコンポーネントIDをメニュー・バーのstretchIdとして設定することでコンポーネントの位置を左右に調整する場合にも、stretchId属性を使用できます。

例16-3 menuBarコンポーネントの位置を調整するためのspacerの使用

<af:menuBar binding="#{editor.component}" id="menuBar1" stretchId="stretch1">
<af:menu text="File" id="m1">
. . .
</af:menu>
. . .
<af:commandMenuItem text="Disabled CMI"/>
<af:goMenuItem textAndAccessKey="O&amp;racle destination="http://www.oracle.com"
id="gmi1"/>
<af:goMenuItem text="Disabled GMI" destination="http://www.gizmo.com"
shortDesc="disabled goMenuItem" id="gmi2"/>
<af:spacer id="stretch1" clientComponent="true"/>
<af:commandMenuItem textAndAccessKey="Component G&amp;uide"
action="guide" id="cmi9"/>
</af:menuBar>

16.3 ツールバーの使用方法

アプリケーションには、メニューのみでなく、アプリケーションの操作の開始に使用するツールバー・ボタンを含むツールバーも作成できます。ボタンには、テキスト、アイコンまたは両方を組み合せて表示できます。ツールバー・ボタンでは、メニューをポップアップ・ウィンドウに開くこともできます。ツールバー・ボタンのみでなく、ドロップダウン・リストなどのその他のUIコンポーネントをツールバーに表示できます。図16-18に、File Explorerアプリケーションのツールバーを示します。

ヒント:

ツールバーには、ツールバー・ボタンのかわりにボタンやリンクを入れることができます。ただし、ツールバー・ボタンには、ポップアップ・メニューの表示など、追加の機能もあります。ツールバー・ボタンは、toolbarコンポーネントの外でも使用できます。

図16-18 File Explorerアプリケーションのツールバー

toolbarコンポーネントには、inputTextコンポーネント、LOVコンポーネント、選択リスト・コンポーネント、コマンド・コンポーネントなど、様々なタイプのコンポーネントを含めることができます。ADF Facesのbuttonコンポーネントにはpopupファセットがあり、これを利用するとツールバー・ボタンからポップアップ・メニューを表示できます。ポップアップ・ダイアログのみが表示され、アクション・イベントが起動されないようにツールバー・ボタンを構成できます。メニュー同様、groupコンポーネントを使用して、ツールバー上の関連するツールバー・ボタンをグループ化できます。

toolboxで囲むことにより、複数のtoolbarを使用できます。toolbarをtoolboxで囲むことによりtoolbarが積み重なり、ページの最初のtoolbarが上に表示され、最後のtoolbarが下に表示されます。たとえば、図16-18に示すように、File Explorerアプリケーションでは、現在選択されているフォルダ名が「現在場所」ツールバーに表示されています。toolbarを複数使用する際は、toolbarにflex属性を設定し、どのツールバーに最も領域を使用するかを決定できます。この場合は、「現在場所」ツールバーが最も長くなるよう設定されています。

ツールバーを(縦ではなく)横に並べて表示する場合は、groupコンポーネント内に配置します。

ヒント:

toolboxコンポーネントを使用して、メニュー・バーとツールバーをグループ化することや、複数のメニュー・バーをグループ化することが可能です。ツールバーのグループ化同様、groupコンポーネントを使用して、同じ行のメニュー・バーとツールバーをグループ化できます。

toolbar内では、ツールバーがその親コンテナと常に同じ大きさになるように、1つのコンポーネントを拡大するよう設定できます。たとえば、File Explorerアプリケーションでは、現在の場所を表示する下側のツールバーには、選択されたフォルダを表示するコンポーネントが含まれています。このコンポーネントは、ウィンドウのサイズが変更されると拡大するように設定されており、コンポーネントとツールバーは常に親と同じ幅になります。一方、上側のツールバーのコンポーネントは拡大するように設定されていないため、ウィンドウがサイズ変更されてもサイズは変わりません。ウィンドウが、ツールバー内のすべてのコンポーネントを表示できないようなサイズに変更された場合、図16-19の右上端にある矢印カーソルで示すように、ツールバーにはオーバーフロー・アイコンが表示されます。

図16-19 ツールバーのオーバーフロー・アイコン

オーバーフロー・アイコンをクリックすると、図16-20に示すように、残りのコンポーネントがポップアップ・ウィンドウに表示されます。

図16-20 オーバーフロー・ポップアップ・ウィンドウ内のtoolbarコンポーネント

ツールバーでオーバーフローが発生することが予測される場合、オーバーフローで役に立つ特別なレイアウト・ロジックのあるtoolboxにラップすることをお薦めします。

16.3.1 ツールバーの作成および使用方法

ページで複数のtoolbarコンポーネントを使用する場合、またはメニュー・バーとツールバーを一緒に使用することを計画している場合は、まず、それらを表示するtoolboxコンポーネントを作成します。その後、ツールバーを作成し、最後にツールバー・ボタンを作成します。

ヒント:

単一のツールバーまたはメニュー・バーでレイアウト上の問題が発生した場合は、toolboxコンポーネントでラップすることを検討してください。これは、このコンポーネントで、オーバーフローやレイアウトの問題を処理できるためです。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、16.3項「ツールバーの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、16.1.2項「メニューおよびツールバー・コンポーネントの追加機能」を参照してください。

ツールバーを作成および使用する手順:

1. 複数のツールバー、またはツールバーとメニュー・バーの組合せを使用する予定の場合は、toolboxコンポーネントを作成します。作成するには、「ツールボックス」コンポーネントを「コンポーネント」ウィンドウの「メニューおよびツールバー」パネルからドラッグ・アンド・ドロップします。

ヒント:

panelHeader、showDetailHeaderおよびshowDetailItemコンポーネントでは、セクション・ヘッダーおよびアコーディオン・パネル・ヘッダーにtoolboxやtoolbarを追加するためのtoolbarファセットがサポートされています。

2. 「ツールバー」をJSFページにドラッグ・アンド・ドロップします。toolboxコンポーネントを使用している場合は、「ツールバー」をtoolboxコンポーネントに直接の子としてドロップする必要があります。

ヒント:

ツールボックスでは、iterator、switcherおよびgroupの各コンポーネントを直接の子として使用することもできます。ただし、これらのコンポーネントが、ツールボックスの本来の直接の子である子コンポーネントをラップしていることが条件です。

3. 複数のツールバーを1つのツールボックスの中でグループ化する場合は、各ツールバーについて、「外観」セクションを開き、Flex属性を設定します。この属性によって、各ツールバーの相対サイズが決定します。flex属性の数値が大きいほど、ツールボックスが長くなります。例16-4に示すツールバーのセットでは、toolbar2が最も長く、toolbar4が次に長くなり、flex属性が設定されていないため、残りのツールバーは同じサイズになり、toolbar4よりも短くなります。

例16-4 ツールバーの長さを決定するflex属性

<af:toolbox>
<af:toolbar id="toolbar1" flex="0">
<af:button text="ButtonA"/>
</af:toolbar>
<af:toolbar id="toolbar2" flex="2">
<af:button text="ButtonB"/>
</af:toolbar>
<af:toolbar id="toolbar3" flex="0">
<af:button text="ButtonC"/>
</af:toolbar>
<af:toolbar id="toolbar4" flex="1">
<af:button text="ButtonD"/>
</af:toolbar>
</af:toolbox>

パフォーマンスのヒント:

実行時、使用可能なブラウザの領域が、toolboxのコンテンツの表示に必要な領域より少ない場合、表示されていない項目をユーザーが選択して表示できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。toolboxコンポーネント内の子コンポーネントの数、および子の複雑さが、オーバーフローのパフォーマンスに影響します。可能な場合は、オーバーフローしないように、toolboxコンポーネントのサイズを設定する必要があります。詳細は、16.3.2項「実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法」を参照してください。

ヒント:

groupコンポーネントを使用して、同じ行に表示するツールバー(またはメニュー・バーとツールバー)をグループ化できます。groupコンポーネントを使用しない場合、ツールバーは次の行に表示されます。

flex属性がどのように機能するかの詳細は、16.3.2項「実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法」を参照してください。

4. 必要に応じてtoolbarにコンポーネントを挿入します。ツールバー上にbuttonを作成するには、「コンポーネント」ウィンドウの「一般コントロール」セクションから「ボタン」をドラッグし、toolbarコンポーネントに直接の子としてドロップします。

ヒント:

groupコンポーネントを使用して、バーの関連するボタンをラップできます。このようにすると、グループ間に区切り線が挿入されます(図16-17を参照)。

ツールバーでは、iteratorコンポーネントやswitcherコンポーネントを直接の子として使用することもできます。ただし、これらのコンポーネントが、ツールバーの本来の直接の子である子コンポーネントをラップしていることが条件です。

ヒント:

その他のコンポーネント、たとえばボタンやリンク、入力コンポーネント、選択コンポーネントなどをツールバーに配置できます。ただし、拡大することはできません。ツールバーの拡大の詳細は、手順9を参照してください。

5. 各buttonコンポーネントに対し、「プロパティ」ウィンドウの「共通」セクションを開いて次の属性を設定します。

- Text: このツールバー・ボタンのラベルを入力します。

- Type: ツールバー・ボタンのタイプを指定します。ツールバー・ボタンのタイプを指定すると、ボタンがクリックされた際にアイコンが表示されます。次に示す使用可能なtype値のいずれかを使用します。

- default: ツールバー・ボタンにはタイプは割り当てられません。

- check: 選択されている場合はdepressedIcon値が表示され、選択されていない場合はデフォルトのicon値が表示されます。

- radio: グループ内のその他のツールバー・ボタンとともに使用すると、現在クリックされているボタンが選択されている状態になり、前にクリックされたグループ内のボタンの選択が解除されます。

注意:

タイプをradioに設定する場合は、タイプがradioに設定されている別のツールバー・ボタンを含むgroupタグでツールバー・ボタンをラップする必要があります。

- Selected: このツールバー・ボタンが選択されているように表示する場合にtrueに設定します。selected属性がサポートされているのは、チェックマーク・タイプおよびラジオ・タイプのツールバー・ボタンのみです。

- Icon: イメージ・ファイルのURIに設定します(コンポーネントの内側にアイコンをレンダリングする場合)。アイコンをレンダリングする場合は、「外観」セクションのhoverIcon、disabledIcon、depressedIconおよびiconPositionの値も設定します。

ヒント:

text属性(またはtextAndAccessKey属性)かicon属性、あるいはその両方を使用できます。

- IconPosition: アイコンを指定した場合は、テキストを基準としてアイコンの位置を指定できます。指定するには、ドロップダウン・リストから値を選択します。

- <default> (leading): アイコンをテキストの前にレンダリングします。

- trailing: アイコンをテキストの後にレンダリングします。

- top: アイコンをテキストの上にレンダリングします。

- bottom: アイコンをテキストの下にレンダリングします。

- Action: ユーザーがボタンを押した場合に起動される、オブジェクト(マネージドBeanなど)のアクション・メソッドに対して評価されるEL式を使用します。式は、パラメータが指定されず、java.lang.Objectオブジェクトを返すpublicメソッドに対して評価される必要があります。
ボタンによって生成されたアクションのレスポンスとしてナビゲートさせる場合は、EL式を入力するかわりに、静的アクションの結果値をaction属性の値として入力します。partialSubmitをfalseに設定するか、リダイレクトを使用する必要があります。ナビゲーションの構成方法の詳細は、3.3項「ページ・フローの定義」を参照してください。

- ActionListener: ユーザーがこのボタンをクリックしたときに通知されるアクション・リスナー・メソッドを表す式を指定します。このメソッドをaction属性にバインドされたメソッドのかわりに使用して、action属性でナビゲーションのみ処理できます。式では、ActionEventパラメータを受け取るpublicメソッドを評価し、戻り型がvoidである必要があります。

6. 「外観」セクションを開き、次のプロパティを設定します。

- HoverIcon: ドロップダウン・リストを使用して、マウス・カーソルがこのツールバー・ボタンの上にある場合に表示するアイコンを選択します。アイコンがこのメニューにない場合は、リストの右側にあるドロップダウン・メニューを使用して「編集」を選択し、参照してアイコンを選択します。

- DepressedIcon: ドロップダウン・リストを使用して、ツールバー・ボタンがアクティブになっている場合に表示するアイコンを選択します。アイコンがこのメニューにない場合は、リストの右側にあるドロップダウン・メニューを使用して「編集」を選択し、参照してアイコンを選択します。

7. ボタンがクリックされたときにアクション・イベントを起動しない場合は、「動作」セクションを開き、ActionDeliveryをnoneに設定します。これは、ボタンで単純にポップアップ・ウィンドウを開く場合に役立ちます。noneに設定されている場合は、ツールバー・ボタンのpopupファセットにpopupコンポーネントが必要で(手順8を参照)、actionまたはactionListener属性には値を設定できません。このボタンで標準コマンド・コンポーネントとしてアクション・イベントを起動する場合は、clientServer属性に設定します。

8. ツールバー・ボタンからポップアップ・メニューが起動されるようにするには、buttonコンポーネントのpopupファセットにmenuコンポーネントを挿入します。詳細は、16.2.1項「メニュー・バーのメニューの作成および使用方法」を参照してください。

9. ツールバーを含む親コンポーネントと同じ幅になるようにツールバーを拡大する場合は、stretchIdを、拡大する必要のあるツールバー内のコンポーネントのIDに設定します。ツールバーのその他のコンポーネントは静的サイズのままですが、その1つのコンポーネントは拡大されます。

たとえば、例16-5に示すように、File Explorerアプリケーションで、選択されているフォルダ名を表示するinputTextコンポーネントは拡大し、「現在のフォルダ」という語を表示するoutputTextコンポーネントは静的サイズのままになります。

例16-5 stretchId属性の使用

<af:toolbar id="headerToolbar2" flex="2" stretchId="pathDisplay">
<af:outputText id="currLocation" noWrap="true"
value="#{explorerBundle['menuitem.location']}"/>
<af:inputText id="pathDisplay" simple="true" inlineStyle="width:100%"
contentStyle="width:100%"
binding="#{explorer.headerManager.pathDisplay}"
value="#{explorer.headerManager.displayedDirectory}"
="true"
validator="#{explorer.headerManager.validatePathDisplay}"/>
</af:toolbar>

また例16-6に示すように、spacerコンポーネントを挿入し、そのコンポーネントIDをtoolbarのstretchIdとして設定することでコンポーネントの位置を左右に調整する場合にも、stretchId属性を使用できます。

例16-6 toolbarコンポーネントの位置を調整するためのspacerの使用

<af:toolbar flex="1" stretchId="stretch1">
<af:button text="Forward"
icon="/images/fwdarrow_gray.gif"
disabled="true"></af:button>
<af:button icon="/images/uplevel.gif" />

<!-- Insert a stretched spacer to push subsequent buttons to the right -->

<af:spacer id="stretch1" clientComponent="true"/>

<af:button text="Reports" />
<af:button id="toggleRefresh"
text="Refresh:OFF" />
</af:toolbar>

16.3.2 実行時に行われる処理: メニュー・バーとツールバーのサイズの決定方法

メニュー・バーまたはツールバーを含むページが最初に表示またはサイズ変更される場合、各バーに必要な領域は、バーのflex属性の値に基づいています。各バーに割り当てられるサイズの割合は、そのflex属性値をすべてのflex属性値の合計で割って決定されます。たとえば、ツールボックスに3つのツールバーがあり、同じ行に表示されるように、それらのツールバーがグループ化されているとします。最初のツールバーにはflex属性値1が、2番目のツールバーにもflex属性値1が指定されていて、3番目のツールバーにはflex属性値2が指定されており、すべてのflex属性値の合計が4であるとします。この例で、各ツールバーの割当ての割合は次のとおりです。

- ツールバー1: 1/4 = 25%

- ツールバー2: 1/4 = 25%

- ツールバー3: 2/4 = 50%

バーの割当てが決まり、サイズがそれに応じて設定されると、ツールバー内の各要素は左から右に配置されます。収まりきらないコンポーネントは、表示される場合と同じ順序を維持したまま、左から右ではなく上から下の順序で、バーのオーバーフロー・リストに配置されます。

注意:

アプリケーションが右から左に読み取るように構成されている場合、ツールバーは右から左に配置されます。詳細は、A.6.2.6項「言語読取り方向」を参照してください。

16.3.3 ツールバーに関する必知事項

ツールバーは、ツールバーやツールバー・ボタンをセクション・ヘッダーおよびアコーディオン・パネル・ヘッダーに追加するためのtoolbarファセットがあるpanelHeader、showDetailHeader、showDetailItemなどの親コンポーネントによってサポートおよびレンダリングされます。

実行時のツールバーについて、次の点に注意してください。

- ヘッダーが閉じている場合、ツールバーおよびそのボタンはヘッダーに表示されません。ツールバーが表示されるのは、ヘッダーが開いている場合のみです。

- ヘッダーの使用可能な領域がツールバーやそのすべてのボタンに必要な領域より少ない場合、ADF Facesにより、ユーザーがオーバーフロー・リストから非表示のボタンを選択できるオーバーフロー・アイコンが自動的にレンダリングされます。

- ツールバーは、印刷可能ページにはレンダリングされません。

17 Calendarコンポーネントの使用方法

この章ではADF Faces Calendarコンポーネントを使用して、Calendarアプリケーションを作成する方法について説明します。

この章では、次の項目について説明します。

- 17.1項「Calendarコンポーネントの作成について」

- 17.2項「Calendarの作成」

- 17.3項「Calendarコンポーネントの構成」

- 17.4項「ポップアップ・コンポーネントを使用した機能の追加」

- 17.5項「ツールバーのカスタマイズ」

- 17.6項「Calendarのスタイル設定」

17.1 Calendarコンポーネントの作成について

ADF Facesにはカレンダ・コンポーネントが含まれており、デフォルトでは特定のプロバイダ(プロバイダとはアクティビティの所有者)のアクティビティが日、週、月またはリストのビューで表示されます。図17-1に、いくつかのサンプル・アクティビティがある週表示モードのADF Faces Calendar を示します。

図17-1 週表示を示しているADF Faces Calendar

ビューのサブセットのみを表示するようにカレンダを構成できます。たとえば、Calendarでmonthおよびlist表示を使用しない場合があります。図17-2に示すように、日表示と週表示のみ使用可能になるように構成できます。日表示および週表示のみ使用可能であるため、これらのボタンのみがツールバーに表示されます。

図17-2 週表示と日表示のみ使用するように構成されたCalendar

デフォルトでは、Calendarにはformatting-localeパラメータを使用してtrinidad-config.xmlファイルに設定されたロケールに基づく日および時刻が表示されます。詳細は、A.6項「trinidad-config.xmlでの構成」を参照してください。このファイルでロケールが指定されていない場合は、ブラウザから送信されたロケールに基づきます。たとえば、米国のデフォルトでは、週の開始日は日曜日であり、午後2時は2:00 PMと表示されます。フランスのデフォルトでは、開始日は月曜日であり、午後2時は14:00と表示されます。Calendarのタイムゾーンもtrinidad-config.xmlのtime-zoneパラメータ設定に基づきます。このデフォルトは、Calendarの構成時にオーバーライドできます。詳細は、17.3項「Calendarコンポーネントの構成」を参照してください。

カレンダにはツールバーが含まれており、表示の変更(日、週、月またはリスト)、前後の日、週、月への移動、および本日に戻るための機能が組み込まれています。ツールバーは完全にカスタマイズ可能です。表示するボタンとテキストを選択でき、ボタンやその他のコンポーネントを追加することもできます。詳細は、17.5項「ツールバーのカスタマイズ」を参照してください。

ヒント:

これらのツールバー・ボタンを使用すると、Calendarの属性値が変わります。それらの値がセッション中に変わらないよう、永続するように構成できます。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

値が永続され、ユーザーがシステムにログインするたびに使用されるように、アプリケーションを構成することもできます。この永続性を実現するには、アプリケーションでFusionテクノロジ・スタックを使用する必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「実行時でのユーザー・カスタマイズの許可」の章を参照してください。

カレンダ・コンポーネントに表示されるアクティビティは、CalendarModelクラスから返されるアクティビティおよびプロバイダに基づいています。デフォルトでは、Calendarコンポーネントは読取り専用です。つまり、Calendarコンポーネントは返されたアクティビティのみ表示できます。ユーザーがアクティビティを編集、作成および削除できるように、Calendarでサポートされているファセット内に機能を追加できます。特定のイベントが起動されると、対応するファセット内に配置されたポップアップ・コンポーネントが開き、ユーザーがアクティビティまたはカレンダに対して操作を実行できるようになります。

たとえば、ユーザーがCalendar内のアクティビティをクリックすると、CalendarActivityEventが起動され、ActivityDetailファセットのポップアップ・コンポーネントが開きます。図17-3に示すように、ユーザーがアクティビティを表示および編集できるフォームを含んでいるダイアログ・コンポーネントを使用することもできます。

図17-3 アクティビティを編集するために実装されているダイアログ

イベント、ファセットおよびポップアップ・コンポーネントを使用した追加機能の実装の詳細は、17.4項「ポップアップ・コンポーネントを使用した機能の追加」を参照してください。

Calendarコンポーネントでは、ADF Facesのドラッグ・アンド・ドロップ・アーキテクチャ機能がサポートされています。ユーザーは、アクティビティをCalendarの異なる領域にドラッグしてコピーまたは移動を行ったり、アクティビティのハンドルをドラッグしてアクティビティの期間を変更したりすることもできます。ドラッグ・アンド・ドロップ機能の追加の詳細は、36.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」を参照してください。

デフォルトでは、カレンダのアクティビティは青色の「ランプ」を使用して表示されます。色ランプとは、特定の色ファミリ内の色のセットであり、アクティビティの様々な状態を表すのに使用されます。図17-1に示すように、デフォルトのCalendarでは、日次表示で表示される短期間のアクティビティの場合、アクティビティの時間は濃い青の背景色で表示され、アクティビティのタイトルは薄い青の背景色で表示されます。色ランプを変更することで、アクティビティの表示方法をカスタマイズできます。

各アクティビティはプロバイダ、つまり所有者に関連付けられています。図17-4に示すように、複数のプロバイダのアクティビティを表示できるようにCalendarを実装する場合、各プロバイダのアクティビティが異なる色で表示されるようにそれぞれのアクティビティのスタイルを設定できます。

図17-4 様々なプロバイダのアクティビティがある月表示

17.1.1 Calendarのユースケースと例

Calendarコンポーネントでは、日、週、月またはリスト表示でのアクティビティの作成など、カレンダ関連の機能を実装するために必要な機能が提供されます。表示の切替えに使用できるカスタマイズ可能なツールバーが備えられています。構成可能な週の開始や日の開始機能もあります。他のADF Facesコンポーネントと同様に、スタイルと外観をカスタマイズするためのスキニングもサポートされます。

Calendarファセットに挿入することでポップアップを作成し、機能をさらに追加できます。ユーザーがある領域からCalendar内の別の領域にアクティビティをドラッグ・アンド・ドロップできるようにCalendarを実装することもできます。

Calendarは、CalendarModelクラスを使用して、特定の期間のアクティビティを表示します。Calendarのモデル・クラスの独自の実装を作成する必要があります。アプリケーションでFusionテクノロジ・スタックを使用する場合は、アクティビティを表すデータソースに対するADFビジネス・コンポーネントを作成でき、作成するとモデルが作成されます。その後、Calendarを宣言的に作成でき、そのCalendarは自動的にそのモデルにバインドされます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のADF Faces Calendarコンポーネントの使用に関する項を参照してください。

アプリケーションでFusionテクノロジ・スタックを使用しない場合は、CalendarModelクラスと、関連するCalendarActivityクラスおよびCalendarProviderクラスの独自の実装を作成します。これらのクラスは、抽象メソッドを使用する抽象クラスです。Calendarの実装に適した、メソッドを支援する機能を提供する必要があります。詳細は、17.2項「Calendarの作成」を参照してください。

17.1.2 Calendarの追加機能

Calendarコンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページにCalendarコンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。Calendarコンポーネントで使用できる他の機能へのリンクを次に示します。

- クライアント・コンポーネント: コンポーネントはクライアント・コンポーネントにすることができます。クライアントでコンポーネントを処理するには、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

- JavaScript API: すべてのコンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください。

- イベント: コンポーネントは、なんらかのロジックを実行することでアプリケーションで対応できるサーバー側とクライアント側両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。

- ヒントとメッセージを表示することや、オンライン・ヘルプをカレンダ・コンポーネントに関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- カレンダ・コンポーネントから行った選択に基づいてページ上の他のコンポーネントを更新できます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。

- スキンを使用して外観を変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。このファイルを利用すると、このような文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- 追加機能のためのポップアップを作成できます。追加機能を提供するためのこれらのイベントの使用の詳細は、17.4項「ポップアップ・コンポーネントを使用した機能の追加」を参照してください。

- アプリケーションでADFモデルを使用する場合は、自動的にバインドされるフォームを、データ・コントロールを使用して作成できます(ADFビジネス・コンポーネントに基づくか、その他のビジネス・サービスに基づくかを問いません)。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた基本的なページの作成」の章を参照してください。

17.2 Calendarの作成

Calendarコンポーネントをページに追加する前に、ADF Faces Calendarの抽象クラスを拡張するJavaクラスのCalendarで必要なロジックを実装する必要があります。クラスを作成すると、Calendarをページに追加できます。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADFビジネス・コンポーネントを使用してCalendarクラスを実装します。これで、カレンダ・コンポーネントを宣言的に作成してバインドできるようになります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のADF Faces Calendarコンポーネントの使用に関する項を参照してください。

ロジックを実装する前に、次の項で説明されているCalendarModelクラスおよびCalendarActivityクラスについて理解しておくと役立ちます。

17.2.1 Calendarのクラス

Calendarコンポーネントは、CalendarModelクラスの実装にバインドする必要があります。CalendarModelクラスには、Calendarのデータが含まれます。このクラスは、次の一連のパラメータに基づき、Calendarアクティビティのコレクションを返します。

- プロバイダID: アクティビティの所有者。たとえば、Calendarが現在セッション中の所有者に関連付けられているアクティビティのみ返すように、またはその他の所有者のアクティビティも返すようにCalendarModelクラスを実装できます。

- 時間範囲: その時間内に開始するすべてのアクティビティの時間の拡大を返す必要があります。Calendarの日付範囲はその開始時刻を含み、終了時刻を含まないため(ハーフ・オープンとも呼びます)、開始時刻より前に開始し、開始時刻より後(また、終了時刻より前)に終了するものを含め、その範囲と交差するすべてのアクティビティを返します。

Calendarアクティビティは、Calendar上のオブジェクトを表し、通常は一定の期間にわたります。CalendarActivityクラスは抽象クラスであり、このクラスのメソッドは特定のアクティビティに関する情報を返すために実装できます。

アクティビティは再帰可能で、関連するキーワードを設定でき、特定の時間タイプ(TIME(開始および終了時刻あり)やALLDAYなど)に設定できます。アクティビティには開始日と終了日、ロケーション、タイトルおよびタグを設定することもできます。

CalendarProviderクラスは、アクティビティの所有者を表します。プロバイダは、Calendarに対して有効化または無効化できます。

17.2.2 カレンダを作成する方法

CalendarModelクラスおよびCalendarActivityクラスの独自の実装を作成し、抽象メソッドを実装してロジックを提供します。

始める前に:

CalendarModelおよびCalendarActivityクラスに関する知識が役立つ場合があります。詳細は、17.2.1項「Calendarのクラス」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

Calendarモデル・クラスを作成する手順:

1. oracle.adf.view.rich.model.CalendarModelクラスのインスタンスを返すマネージドBeanを作成します。このインスタンスの要件は次のとおりです。

- oracle.adf.view.rich.model.CalendarModelクラスを拡張する。

- 抽象メソッドを実装する。
CalendarModelクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

- Calendarに必要なその他の機能を実装する。たとえば、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.calendar.rich.model.DemoCalendarBeanマネージドBeanでのように、タイムゾーンを設定するロジックを追加できます(デモ・アプリケーションのダウンロードおよびインストールの詳細は、第2章「ADF Facesデモ・アプリケーション」を参照してください)。

マネージドBeanの作成の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. oracle.adf.view.rich.model.CalendarActivityクラスのインスタンスを返すマネージドBeanを作成します。このインスタンスの要件は次のとおりです。

- oracle.adf.view.rich.model.CalendarActivityクラスを拡張する。

- 抽象メソッドを実装する。
CalendarActivityクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

- 他にもカレンダのアクティビティに必要な機能がある場合は実装します。例については、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.calendar.rich.model.DemoCalendarActivityマネージドBeanを参照してください。

ヒント:

1つのアクティビティのインスタンスごとにスタイルを変える(たとえば、各プロバイダのアクティビティを異なる色で表示する)場合は、アクティビティがどのグループに属するかを表すタグをgetTagsメソッドを使用して返す必要があります(グループには、たとえばプロバイダIDを使用します)。詳細は、17.6.1項「アクティビティのスタイル設定方法」を参照してください。

3. oracle.adf.view.rich.model.CalendarProviderクラスのインスタンスを返すマネージドBeanを作成します。このインスタンスの要件は次のとおりです。

- oracle.adf.view.rich.model.CalendarProviderクラスを拡張する。

- 抽象メソッドを実装する。
CalendarProviderクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

- 他にもカレンダのプロバイダに必要な機能がある場合は実装します。

Calendarコンポーネントを作成する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「カレンダ」をドラッグしてJSFページにドロップします。

ヒント:

calendarコンポーネントは、子を拡大できる親コンポーネントによって拡大できます。calendarが拡大できないコンポーネントの子コンポーネントの場合は、デフォルトの幅と高さが使用され、ユーザーは実行時に拡大できません。ただし、インライン・スタイル属性を使用して、デフォルトの幅と高さをオーバーライドできます。デフォルトの高さと幅の詳細は、17.3項「Calendarコンポーネントの構成」を参照してください。コンポーネントの拡大の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

2. 「プロパティ」ウィンドウの「カレンダ・データ」パネルを開き、EL式をValueに入力します。この式を解決した結果は、CalendarModelクラスを拡張するこのマネージドBeanとなる必要があります。

17.3 Calendarコンポーネントの構成

Calendarの多くの表示属性(1日の始まりに表示する時刻など)を構成します。

17.3.1 Calendarコンポーネントの構成方法

カレンダを構成するには、「プロパティ」ウィンドウを使用します。

始める前に:

Calendarコンポーネントに関する知識が役立つ場合があります。詳細は、17.3項「Calendarコンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

Calendarを構成する手順:

1. calendarコンポーネントが選択されている状態で、「プロパティ」ウィンドウの「共通」セクションを開いて次のとおりに設定します。

- AvailableViews: 使用可能な表示を選択します。値は次のいずれかまたはその組合せにすることができます。

- all

- day

- week

- month

- list

複数の値を入力する場合は、値の間にスペースを入力します。たとえば、Calendarで日および週表示を使用する場合は、次のように入力します。

day week

注意:

allが入力された場合は、リストで省略されているかどうかにかかわらず、すべての表示を使用できます。

対応するボタンが自動的にツールバーに表示されます。表示順は、availableViews属性のリストでの順序です。

注意:

month表示の特定の日のタスクのオーバーフローを処理するために、monthを入力し、allを入力しない場合は、dayも入力する必要があります。

- View: Calendarが表示されるときのデフォルトにする表示を選択します。ユーザーは、Calendarのツールバーにある対応するボタンをクリックしてこの値を変更できます。有効な値は次のとおりです。

- day

- list

- month

- week

- StartDayOfWeek: 月表示または週表示の左端に週の開始日として表示される曜日を入力します。設定しない場合、デフォルトはユーザーのロケールに基づきます。有効な値は次のとおりです。

- sun

- mon

- tue

- wed

- thu

- fri

- sat

- StartHour: dayビューおよびweekビューの先頭に表示する「時」を表す数値(24時間形式、0が午前0時)を入力します。カレンダでは1日の24時間すべてがレンダリングされますが、カレンダはstartHourまでスクロールされて、この「時」がビューの先頭に表示されます。ユーザーは、この時間よりも上にスクロールすると、startHourの値よりも前に開始するアクティビティを見ることができます。

- ListType: list表示でアクティビティを表示する方法を選択します。有効な値は次のとおりです。

- day: アクティブな日のアクティビティのみ表示します。

- dayCount: listCount属性の値に基づき、アクティブな日以降を含む日数を表示します。

- month: アクティブな日が属する月のアクティビティをすべて表示します。

- week: アクティブな日が属する週のアクティビティをすべて表示します。

- ListCount: 表示する日のアクティビティ数を入力します(listType属性がdayCountに設定されている場合のみ使用します)。
図17-5に、listTypeがdayCountに設定され、listCount値が14に設定されているリスト表示のCalendarを示します。

図17-5 dayCountタイプを使用したリスト表示

2. 「プロパティ」ウィンドウの「カレンダ・データ」セクションを開いて、次のとおりに設定します。

- ActiveDay: Calendarに表示される日付範囲を決定するために使用される日を設定します。デフォルトでは、アクティブ日はユーザーの今日の日付です。Calendarを初めて開くときのデフォルトのアクティブ日を今日の日付にする場合は、この設定を変更しないでください。
別の日を選択した場合、その日がactiveDay属性の値になります。たとえば、Calendarに初めてアクセスする場合、現在の日付がアクティブ日になります。ユーザーは、月表示の日リンクをクリックすることでアクティブ日にする別の日を選択できます。アクティブ日は、ユーザーが別の月または年を選択した場合にも変更されます。

- TimeZone: Calendarのタイムゾーンを設定します。設定しない場合、値はAdfFacesContextから取得されます。有効な値はjava.util.TimeZoneオブジェクトです。デフォルトでは、trinidad-config.xmlファイルのformatting-localeパラメータに基づいて時刻が表示されます。詳細は、A.6項「trinidad-config.xmlでの構成」を参照してください。

3. 「プロパティ」ウィンドウの「外観」セクションを開いて、次のとおりに設定します。

- AllDayActivityOrder: 終日アクティビティの表示を制御するために、アクティビティのタグに対応する文字列のリストを指定します。アクティビティはタグごとにグループ化されて、allDayActivityOrderで指定された順に表示されます。アクティビティにタグがない場合や、アクティビティのタグがallDayActivityOrderのリストで指定されていない場合は、そのようなアクティビティがまとめてデフォルトのグループとして表示されます。各グループの中では、アクティビティが多い順に行が表示されます。たとえば、allDayActivityOrder = holiday absenceの場合は、終日アクティビティはこの順序で表示されます。

- holidayタグ付きのアクティビティ

- absenceタグ付きのアクティビティ

- タグのないアクティビティ

図17-6に示すカレンダでは、allDayActivityOrderがholiday absenceに設定されています。holidayタグの付いたアクティビティが先頭に表示され、次にabsenceタグ付きのアクティビティが表示されます。残りのアクティビティは、その後で表示されます。アクティビティが最も多い行が最初に表示されます。

図17-6 allDayActivityOrderを使用するカレンダ表示

- HourZoom: Calendarに表示される時間セルのズーム係数を設定します。ズーム係数は、dayまたはweek表示の時間の高さに適用されます。有効な値は、autoまたはゼロ以外の正の数(小数も可)です。デフォルトの値は1です。
1より大きい値を指定すると、指定した倍率でカレンダが拡大されます。たとえば、値2を指定すると、Calendarが200%に拡大されます。値0.5を指定すると、Calendarが50%に縮小されます。autoを設定すると、密にスケジュールされた時間的に重ならない複数のアクティビティが縦方向のスペース不足のために重なって表示されることのないように、Calendarが最も見やすい表示となる最適な係数で拡大されます。

- TimeSlotsPerHour: 日または週表示で1時間当たりに表示するタイム・スロットの数を設定します。タイム・スロットとは、1時間当たりのマイナー分割(時間をさらに短い間隔に分割する点線で示される)の数です。たとえば、値4を指定すると、1時間当たり4つのタイム・スロットがレンダリングされ、各スロットが15分になります。有効な値は、autoまたはゼロ以外の正の整数です。デフォルトの値はautoです。
autoに設定すると、スキン・プロパティ-tr-time-slots-per-hourが使用されます。たとえば、af|calendar {-tr-time-slots-per-hour: 4}を指定すると、15分間隔のマイナー分割(点線)がレンダリングされます。

4. ユーザーが既存のアクティビティのハンドルをドラッグして、そのアクティビティの期間を拡張または縮小できるようにする場合は、CalendarActivityDurationChangeListenerのハンドラを実装します。このハンドラには、アクティビティの終了時間を変更する機能を含める必要があります。ユーザーがアクティビティを移動し、開始時間および終了時間を変更できるようにするには、ドラッグ・アンド・ドロップ機能を実装します。詳細は、36.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」を参照してください。

これで、次の機能を追加できます。

- ポップアップ・コンポーネントを使用したアクティビティの作成、編集および削除。詳細は、17.4項「ポップアップ・コンポーネントを使用した機能の追加」を参照してください。

- Calendar上でのアクティビティを移動します。詳細は、36.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」を参照してください。

- ツールバーのツールバー・ボタンを変更または追加します。詳細は、17.5項「ツールバーのカスタマイズ」を参照してください。

- Calendarとイベントの外観を変更します。詳細は、17.6項「Calendarのスタイル設定」を参照してください。

17.3.2 実行時の処理: CalendarイベントおよびPPR

Calendarには、アクティビティの編集や追加など、Calendarに必要な追加機能を簡単に実装する方法を提供するためにファセットとともに使用する2つのイベントがあります。この2つのイベントとは、CalendarActivityEvent(アクティビティに対するアクションが発生したときに起動します)とCalendarEvent(カレンダ自体に対するアクションが発生したときに起動します)です。追加機能を提供するためのこれらのイベントの使用の詳細は、17.4項「ポップアップ・コンポーネントを使用した機能の追加」を参照してください。

Calendarでは、特定の変更が発生したときに起動されるイベントもサポートされています。CalendarActivityDurationChangeEventは、ユーザーが開始と終了の日時を変更することによってアクティビティの期間を変更したときに起動されます。CalendarDisplayChangeEventは、表示属性の値が変更されたときに起動されます。たとえば、ユーザーがview属性をdayからmonthに変更した場合は、カレンダが自動的にレンダリングされます。その理由は、カレンダ・コンポーネントが部分ページ・レンダリング(PPR)のターゲットとなり、その結果として即時リフレッシュが起動されるからです。

17.4 ポップアップ・コンポーネントを使用した機能の追加

ユーザーがアクティビティを処理すると、CalendarActivityEventが起動します。このイベントにより、ユーザーのアクションに基づいて、ファセットに含まれるポップアップ・コンポーネントが表示されます。たとえば、ユーザーがアクティビティを右クリックした場合、CalendarActivityEventにより、activityContextMenu内のポップアップ・コンポーネントが表示されます。イベントはサーバーにも配信され、構成されたリスナーがイベントを処理できます。ファセットのポップアップ・コンポーネントを作成します(または、ポップアップ・コンポーネントを使用しない場合は、サーバー側リスナーを実装します)。このポップアップ・コンポーネントとファセットの中で開発者が実装した機能によって、ユーザーがアクティビティを作成、削除および編集したり、カレンダのインスタンスを構成したりできるようになります。

表17-1に、イベントを起動する様々なユーザー・アクション、起動されるイベント、およびイベントが起動されたときにその内容を表示する関連ファセットを示します。表では、ポップアップ・コンポーネントで使用する必要のあるコンポーネントも示します。ファセット内に、関連リスナーのハンドラで実装された機能とともに、ポップアップおよび関連コンポーネントを作成します。ポップアップ・コンポーネントを表のいずれのファセットにも挿入しない場合は、関連イベントがサーバーに配信されるため、イベントのハンドラを実装することでサーバーでイベントを処理できます。

表17-1 Calendar Facesイベントおよび関連ファセット

ユーザー・アクション

イベント

関連ファセット

ポップアップで使用するコンポーネント

アクティビティを右クリックします。

CalendarActivityEvent

activityContextMenu: この中のポップアップ・コンポーネントを使用してポップアップ・メニューを表示できます。ユーザーはこのメニューで、アクティビティに対して実行するアクション(編集や削除など)を選択できます。

menu

アクティビティを選択して、[Del]キーを押します。

CalendarActivityEvent

activityDelete: 指定されたポップアップ・コンポーネントを使用して、ユーザーが選択したアクティビティを削除できるダイアログを表示します。

dialog

アクティビティをクリックまたはダブルクリックするか、アクティビティを選択して[Enter]キーを押します。

CalendarActivityEvent

activityDetail: 指定されたポップアップ・コンポーネントを使用して、アクティビティの詳細を表示します。

dialog

アクティビティの上にカーソルを置きます。

CalendarActivityEvent

activityHover: 指定されたポップアップ・コンポーネントを使用して、アクティビティに関する高水準な情報を表示します。

noteWindow

Calendar(アクティビティ上やツールバー内ではありません)を右クリックします。

CalendarEvent

contextMenu: 指定されたポップアップ・コンポーネントを使用して、Calendarのポップアップ・メニューを表示します。

menu

Calendarの空き領域(アクティビティではありません)をクリックまたはダブルクリックします。

CalendarEvent

create: 指定されたポップアップ・コンポーネントを使用して、ユーザーがアクティビティを作成できるダイアログを表示します。

dialog

17.4.1 ポップアップ・コンポーネントを使用した機能の追加方法

機能を追加するには、関連ファセット内にポップアップ・コンポーネントと関連コンポーネントを作成します。

始める前に:

ポップアップ・コンポーネントに関する知識が役立つ場合があります。詳細は、17.4項「ポップアップ・コンポーネントを使用した機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

ポップアップ・コンポーネントを使用して機能を追加する手順:

1. 図17-7に示すように、「構造」ウィンドウでaf:calendarコンポーネント・ノードを開き、Calendarファセットを表示します。

図17-7 「構造」ウィンドウ内のCalendarファセット

2. 表17-1に基づき、機能を提供するユーザー・アクションに対応するポップアップ・コンポーネントをファセットに作成します。たとえば、アクティビティをクリックして[Del]キーを押すことで、ユーザーがアクティビティを削除できるようにする場合は、activityDeleteファセットにポップアップ・ダイアログを追加します。
ポップアップ・コンポーネントを追加するには、「構造」ウィンドウでファセットを右クリックし、「facetNameの中に挿入」→「ポップアップ」を選択します。

ポップアップ・コンポーネントの作成の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

例17-1に、activityDeleteファセットで使用されるダイアログ・ポップアップ・コンポーネントのJSFコードを示します。

例17-1 「アクティビティの削除」ダイアログのJSFコード

<f:facet name="activityDelete">
<af:popup id="delete" contentDelivery="lazyUncached">
<!-- don't render if the activity is null -->
<af:dialog dialogListener="#{calendarBean.deleteListener}"
affirmativeTextAndAccessKey="Yes" cancelTextAndAccessKey="No"
rendered="#{calendarBean.currActivity != null}">
<af:spacer height="20"/>
<af:outputText value="Are you sure you want to delete this activity?"/>
<af:panelFormLayout>
<af:inputText label="Title" value="#{calendarBean.currActivity.title}"
readOnly="true"/>
<af:inputDate label="From" value="#{calendarBean.currActivity.from}"
readOnly="true">
<af:convertDateTime type="date" dateStyle="short"
timeZone="#{calendarBean.timeZone}"
pattern="#{calendarBean.currActivity.dateTimeFormat}"/>
</af:inputDate>
<af:inputDate label="To" value="#{calendarBean.currActivity.to}"
readOnly="true">
<af:convertDateTime type="date" dateStyle="short"
timeZone="#{calendarBean.timeZone}"
pattern="#{calendarBean.currActivity.dateTimeFormat}"/>
</af:inputDate>
<af:inputText label="Location" readOnly="true"
rendered="#{calendarBean.currActivity.location != null}"
value="#{calendarBean.currActivity.location}"/>
</af:panelFormLayout>
</af:dialog>
</af:popup>
</f:facet>

図17-8に、ユーザーがアクティビティをクリックして[Del]キーを押したときに、ダイアログがどのように表示されるかを示します。

図17-8 「アクティビティの削除」ダイアログ

3. calendarActivityListenerに必要なロジックを実装します。たとえば、activityDeleteFacetのダイアログを実装している場合は、現在のアクティビティを保存できるロジックをcalendarActivityListenerに実装して、(次の手順で)ダイアログ・リスナーにロジックを実装するときに削除するアクティビティがわかるようにします。例17-2に、ADF Facesデモ・アプリケーションのcalendar.jspxページのcalendarActivityListenerを示します。

例17-2 calendarActivityListenerハンドラ

public void activityListener(CalendarActivityEvent ae)
{
CalendarActivity activity = ae.getCalendarActivity();
if (activity == null)
{
// no activity with that id is found in the model
setCurrActivity(null);
return;
}

setCurrActivity(new DemoCalendarActivityBean((DemoCalendarActivity)activity,
getTimeZone()))

4. ポップアップ・イベントのハンドラにポップアップ・コンポーネントのロジックを実装します。たとえば、「削除」ダイアログの場合、ダイアログが閉じたときに実際のアクティビティを削除するdialogListenerのハンドラを実装します。ダイアログおよび他のポップアップ・コンポーネントの作成の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

17.5 ツールバーのカスタマイズ

デフォルトでは、カレンダのツールバーを使用して、ユーザーは日、週、月およびリストのビュー切替え、ビュー内の前後の項目への移動、現在の日への移動ができます。また、ツールバーには、現在の表示のテキストによる説明も表示されます。たとえば日表示では、図17-9に示すようにアクティブ日が表示されます。

図17-9 日表示のCalendarのツールバー

図17-10に、カスタマイズされているツールバーを示します。このツールバーには、一番上のツールバーに右揃えされているボタンおよび2番目のツールバーのボタンを含め、ツールバー・ボタンが追加されています。

図17-10 カスタマイズされたCalendarのツールバー

17.5.1 ツールバーのカスタマイズ方法

作成するカスタム・ファセットに、追加するツールバーおよびツールバー・ボタンを配置します。次に、含まれている項目の表示方法および表示場所を決定するキーワードとともに、Calendarの属性からファセットを参照します。

始める前に:

Calendarツールバーのカスタマイズに関する知識が役立つ場合があります。詳細は、17.5項「ツールバーのカスタマイズ」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

ツールバーをカスタマイズする手順:

1. 「コンポーネント」ウィンドウの「JSF」ページの、レイアウト(コア構造)パネルから、追加するツールバーのセクションごとに「ファセット」をドラッグ・アンド・ドロップします。たとえば、図17-10に示されているカスタム・ボタンを追加するには、4つのfacetタグを追加します。各ファセットには、ページに対する一意な名前を付けてください。

ヒント:

ADF Facesの今後のリリースと競合が生じないようにするには、すべてのファセット名をcustomToolbarで開始します。たとえば、図17-10に示されている「位置合せ」ボタンを含むツールバーのセクションは、customToolbarAlignファセットです。

2. 「コンポーネント」ウィンドウの「ADF Faces」ページの「メニューおよびツールバー」パネルから、「ツールバー」を各ファセットにドラッグ・アンド・ドロップし、ツールバー・ボタンを追加し、必要に応じてボタンとツールバーを構成します。ツールバーとツールバー・ボタンの詳細は、16.3項「ツールバーの使用方法」を参照してください。

3. カレンダを選択し、「プロパティ」ウィンドウのToolboxLayout属性の横にあるドロップダウン・メニューで「編集」を選択します。

4. 「プロパティの編集: ToolboxLayout」ダイアログで、この属性の値を設定します。この値は、カスタム・ファセット名のリストに、カスタム・ファセット内のコンテンツを表示する順序で設定する必要があります。これらのファセットのみでなく、次のキーワードを使用して、デフォルトのツールバーのすべてまたは一部を含めることもできます。

- all: デフォルトのツールバーにすべてのツールバー・ボタンおよびテキストを表示します。

- dates: 「前へ」ボタン、「次へ」ボタンおよび「今日」ボタンのみ表示します。

- range: 現在の日付範囲を示す文字列のみ表示します。

- views: ユーザーが表示を変更できるボタンのみ表示します。

注意:

allキーワードを使用する場合、dates、rangeおよびviewsキーワードは無視されます。

たとえば、customToolbar1およびcustomToolbar2という名前の2つのファセットを作成し、デフォルトのツールバー全体をカスタム・ツールバーの間に表示させる場合、toolboxLayout属性の値は次のリスト項目となります。

- customToolbar1

- all

- customToolbar2

ツールバーのレイアウトは、次のキーワードを使用して決定することもできます。

- newline: 新しい行の次の名前付きファセット(またはtoolboxLayout属性のリストの次のキーワード)にツールバーを配置します。たとえば、customToolbar2ファセットのツールバーを新しい行に表示させる場合、リストは次のようになります。

- customToolbar1

- all

- newline

- customToolbar2

デフォルトのツールバーのすべては使用せず、viewsセクションとdatesセクションのみ使用し、それぞれのセクションを新しい行に表示させる場合、リストは次のようになります。

- customToolbar1

- customToolbar2

- newline

- views

- newline

- dates

- stretch: 使用可能なすべての領域を埋めるために拡大されるspacerコンポーネントを追加して、次の名前付きファセット(またはデフォルトのツールバーの次のキーワード)がツールバーに右揃えで表示されるようにします。例17-3に示すtoolboxLayout属性の値は、図17-10に表示されているツールバーのものです。このツールバーは、customToolbarAlignファセット内に配置されています。customToolbarBoldファセットに表示されているツールバー・ボタンは、stretchキーワードがファセットの前に指定されているため、ツールバー内で右揃えで表示されています。

例17-3 カスタム・ツールバーの値

<af:calendar binding="#{editor.component}" id="calendar1"
value="#{calendarBean.calendarModel}"
timeZone="#{calendarBean.timeZone}"
toolboxLayout="customToolbarAlign all customToolbarTZ stretch
customToolbarBold newline customToolbarCreate"
. . .
<f:facet name="customToolbarAlign">
<af:toolbar>
<af:button id="alignLeft" shortDesc="align left"
icon="/images/alignleft16.png" type="radio"
selected="true"/>
<af:button id="alignCenter" shortDesc="align center"
icon="/images/aligncenter16.png" type="radio"
selected="false"/>
<af:button id="alignRight" shortDesc="align right"
icon="/images/alignright16.png" type="radio"
selected="false"/>
</af:toolbar>
</f:facet>
. . .
</af:calendar>

17.6 Calendarのスタイル設定

他のADF Facesコンポーネントと同様、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」で説明されているように、Calendarコンポーネントもスタイル設定できます。ただし、標準のスタイル設定手順とともに、CalendarコンポーネントにはCalendarのインスタンスのスタイル設定を簡単にする特定の属性があります。これらの属性は次のとおりです。

- activityStyles: 各アクティビティ・インスタンスを個々にスタイル設定できます。たとえば、異なるプロバイダに属しているアクティビティを別の色で表示できます。

- dateCustomizer: 月表示の日にCalendar日以外の文字列を表示できます。たとえば、図17-11に示されているように、カウントダウンまたはカウントアップ・タイプの数値を表示できます。この属性を使用すると、日のヘッダーの空白部分に文字列を追加できます。

図17-11 Calendarのカスタマイズ済の日付表示

17.6.1 アクティビティのスタイル設定方法

activityStyles属性は、InstanceStylesオブジェクトを使用して、アクティビティの特定のインスタンスをスタイル設定します。InstanceStylesクラスは、スキニング・キーに基づくインスタンスごとのインライン・スタイルを提供します。

activityStyles属性は、特定のプロバイダに属しているアクティビティを特定の色を使用して表示するために最もよく使用されます。たとえば、図17-12に示されているCalendarは、異なる3つのプロバイダに属しているアクティビティを示しています。プロバイダのアクティビティを表すために使用されている色は、左のペインで変更できます。activityStyles属性は、アクティビティが関連付けられているプロバイダに基づき、各アクティビティに表示される色を決定するために使用します。

図17-12 プロバイダごとに異なる色を表示するようにスタイル設定されているアクティビティ

このCalendarでは、単一の色を使用するかわりに、色の範囲が使用されています。これは、色ランプと呼ばれます。色ランプとは、特定の色ファミリ内の色のセットであり、アクティビティの様々な状態を表すのに使用されます。たとえば、Tedのアクティビティでは青色のランプを使用しています。期間が1日以内のアクティビティは、青色の中間色のテキストで表示されます。複数日にまたがるアクティビティは、青色の中間色のボックスに白いテキストで表示されます。濃い青は開始時間の背景色で、薄い青はタイトルの背景色です。これら3つの異なる青は、すべて青い色ランプの一部です。

CalendarActivityRampクラスは、組込み色ランプをサポートする(InstanceStylesの)サブクラスであり、代表的な色を取得して(たとえば、Tedのアクティビティには青が選択されています)、Calendarで各アクティビティを表示するために使用する正しい色ランプを返すことができます。

activityStyles属性は、mapオブジェクトにバインドする必要があります。マップ・キーは、アクティビティに対するgetTagsメソッドから返されるセットです。InstanceStylesオブジェクトのマップ値は、ほとんどの場合CalendarActivityRampのインスタンスです。このInstanceStylesオブジェクトはスキンニング・キーを取り込み、各アクティビティのスタイルを返します。

始める前に:

Calendarスタイルに関する知識が役立つ場合があります。詳細は、17.6項「Calendarのスタイル設定」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

アクティビティをスタイル設定する手順:

1. CalendarActivityクラスで、getTagsメソッドが、返された文字列を特定のスタイルにマップするためにactivityStyles属性で使用される文字列セットを返すようにします。たとえば、図17-12に示す様々なプロバイダに様々な色ランプを使用するには、各プロバイダ用の文字列を返す必要があります。この場合、現在のユーザーに属するアクティビティはMeを返し、Maryに属するアクティビティはMJを返し、Tedに属するアクティビティはTCを返すことができます。CalendarActivityクラスの実装の詳細は、17.2.2項「カレンダを作成する方法」を参照してください。

2. キーがgetTagsメソッドから返されたセットであり、値がInstanceStylesオブジェクト(CalendarActivityRampインスタンスなど)であるマップを作成します。
たとえば、図17-12に示す様々な色ランプを使用するには、表17-2に示す値を使用してマップを作成します。

表17-2 activityStyles属性のマップ

キー(文字列セット)

値(InstanceStylesオブジェクト)

{"Me"}

CalendarActivityRamp.getActivityRamp (CalendarActivityRamp.RampKey.RED)

{"LE"}

CalendarActivityRamp.getActivityRamp (CalendarActivityRamp.RampKey.ORANGE)

{"TF"}

CalendarActivityRamp.getActivityRamp (CalendarActivityRamp.RampKey.BLUE)

3. 「構造」ウィンドウでカレンダ・コンポーネントを選択し、「プロパティ」ウィンドウでactivityStyles属性をマップにバインドします。

17.6.2 実行時の処理: アクティビティのスタイル設定

各アクティビティに対するCalendarのレンダリング中、レンダラはCalendarActivity.getTagsメソッドをコールして文字列セットを取得します。次に、文字列セットはactivityStyles属性にバインドされているマップに渡され、InstanceStylesオブジェクトが返されます(CalendarActivityRampの場合もあります)。

次の例を参照してください。

- 文字列セット{"Me"}が渡された場合、赤のCalendarActivityRampが返されます。

- 文字列セット{"LE"}が渡された場合、オレンジのCalendarActivityRampが返されます。

- 文字列セット{"TF"}が渡された場合、青のCalendarActivityRampが返されます。

17.6.3 日付のカスタマイズ方法

月表示の日のヘッダーに日付の数値文字列以外の内容を表示する場合、dateCustomizer属性を、日付に表示する内容を決定するDateCustomizerクラスの実装にバインドできます。

始める前に:

Calendarスタイル設定に関する知識が役立つ場合があります。詳細は、17.6項「Calendarのスタイル設定」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、17.1.2項「Calendarの追加機能」を参照してください。

日付文字列をカスタマイズする手順:

1. oracle.adf.view.rich.util.DateCustomizerクラスのサブクラスを作成します。このサブクラスは、次のスキニング・キーを使用して、表示する内容を決定します。
DateCustomizer.formatメソッドに渡されるキーは、次のとおりです。

- af|calendar::day-header-row: 日表示で、ヘッダーの曜日をカスタマイズします。たとえば、「木曜」を「木」で置換します。

- af|calendar::list-day-of-month-link: リスト表示で、日付リンクのテキストをカスタマイズします。たとえば、「1月1日」を「元日」で置換します。

- af|calendar::list-day-of-week-column: リスト表示で、左のリスト列の曜日をカスタマイズします。たとえば、「木曜」を「木」で置換します。

- af|calendar::month-grid-cell-header-day-link: 月表示で、セル・ヘッダーの日付リンクのラベルをカスタマイズします。たとえば、「5」を「-34」で置換します。

- af|calendar::month-grid-cell-header-misc: 月表示で、セル・ヘッダーの空き領域に様々なテキストを追加します。たとえば、1月1日に対して「元日」というテキストを追加します。

- af|calendar::week-header-day-link: 週表示で、ヘッダーの各日付の日付リンクをカスタマイズします。たとえば、「1/1(日)」を「元日」で置換します。

- af|calendar::toolbar-display-range:day: 日表示、またはlistType = dayのときのリスト表示で、ツールバーの日付文字列をカスタマイズします。

- af|calendar::toolbar-display-range:month: 月表示、またはlistType = monthのときのリスト表示で、ツールバーの日付文字列をカスタマイズします。

DateCustomizer.formatRangeメソッドに渡されるキーは、次のとおりです。

- af|calendar::toolbar-display-range:week: 週表示、またはlistType = weekのときのリスト表示で、ツールバーの日付文字列をカスタマイズします。

- af|calendar::toolbar-display-range:list: リスト表示、またはlistType = listのときのリスト表示で、ツールバーの日付文字列をカスタマイズします。

例17-4に示すDemoDateCustomizerクラスでは、週の最初の曜日のところに週番号が表示され、日付のかわりに特定の日までのカウントダウン数値が表示されます(図17-11を参照)。

例17-4 DateCustomizerクラス

public class MyDateCustomizer extends DateCustomizer
{
public String format(Date date, String key, Locale locale, TimeZone tz)
{

if ("af|calendar::month-grid-cell-header-misc".equals(key))
{

// return appropriate string

}
else if ("af|calendar::month-grid-cell-header-day-link".equals(key))
{

// return appropriate string
}

return null;

}

}

2. マネージドBeanの中で、DateCustomizerクラスのインスタンスを作成します。次に例を示します。

private DateCustomizer _dateCustomizer = new DemoDateCustomizer();

3. Calendarコンポーネントで、マネージドBeanに作成したDateCustomizerインスタンスにdateCustomizer属性をバインドします。

18 出力コンポーネントの使用

この章では、ADF Faces outputText、outputFormatted、image、iconおよびstatusIndicatorの各コンポーネントを使用して出力テキスト、イメージ、およびアイコンを表示する方法と、mediaコンポーネントを使用してユーザーによるビデオや音声クリップの再生を可能にする方法を説明します。

この章では、次の項目について説明します。

- 18.1項「出力テキスト、イメージ、アイコンおよびメディア・コンポーネントについて」

- 18.2項「出力テキストおよび書式設定された出力テキストの表示」

- 18.3項「アイコンの表示」

- 18.4項「イメージの表示」

- 18.5項「リンクとしてのイメージの使用」

- 18.6項「アイコンを使用したアプリケーション・ステータスの表示」

- 18.7項「ビデオ・クリップおよび音声クリップの再生」

18.1 出力テキスト、イメージ、アイコンおよびメディア・コンポーネントについて

ADF Facesには、テキスト、アイコン、イメージを表示するためのコンポーネント、およびJSFページで音声クリップやビデオ・クリップを再生するためのコンポーネントが用意されています。

図18-1 ADF Faces出力コンポーネント

18.1.1 出力コンポーネントのユースケースと例

outputTextコンポーネントは、読取り専用テキストを表示するために、他の多くのコンポーネントの子として使用できます。テキストを書式設定する必要がある場合は、outputFormattedコンポーネントを使用できます。たとえば、図18-2に示すように、説明テキストで太字書式のテキストを使用することが必要な場合があります。

図18-2 説明テキストでのoutputFormattedコンポーネントの使用

多くのADF Facesコンポーネントには、アイコンを関連付けできます。たとえば、メニューでは、各メニュー項目にアイコンを関連付けできます。それぞれのアイコンに使用するイメージは、そのメニュー項目コンポーネント自体のicon属性の値として識別します。アイコンがサポートされているコンポーネントへのアイコン追加の詳細と手順は、それぞれのコンポーネントの章で説明されています。コンポーネント内でアイコンを提供するだけでなく、ADF Facesにはメッセージを表示する際に使用されるアイコンもあります。これらのアイコンは、メッセージの外でも使用できます。

ページにイメージを表示するには、imageコンポーネントを使用します。イメージを使用して、リンク(イメージ・マップを含む)として使用することも、サーバーのステータスを表すために使用することもできます。

mediaコンポーネントは、オーディオ・ビジュアル・コンテンツ(通知やタスク実施の指示など)を表示するのに使用します。mediaコンポーネントのすべてのコントロールを表示するか、一般的なコントロールまたは最小限のコントロールのみを表示するか、表示可能なコントロールなし(たとえば、コントロールはポップアップ・メニューからのみ可能)にするかを構成できます。コントロールなしにすることもできます。通常は、クリップが非常に短くコントロールが不要な場合は、コントロールを表示しません。

mediaコンポーネントがページのプライマリ・コンポーネントのときは、一般的にすべてのコントロールが表示されます(図18-3を参照)。

図18-3 プレーヤの下部にすべてのコントロールを表示

18.1.2 出力コンポーネントの追加機能

出力コンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページにこれらのコンポーネントを追加した後で、ドラッグ・アンド・ドロップやアクセシビリティなどの機能を追加することが必要になる場合があります。出力コンポーネントで使用できる他の機能へのリンクを次に示します。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- 変換: 場合によっては、値を表示するために文字列に変換することが必要です。変換の詳細は、第7章「入力の検証および変換」を参照してください。

- ドラッグ・アンド・ドロップ: ユーザーが出力コンポーネントまたは出力コンポーネントの値をページ上の別の領域にドラッグ・アンド・ドロップできるようにページを構成できます。詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

- ローカライゼーション: 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- スキン: スキンを変更することで、出力コンポーネントのルック・アンド・フィールを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

18.2 出力テキストおよび書式設定された出力テキストの表示

ページに出力テキストを表示するためのADF Facesコンポーネントは2つあります。outputTextは書式設定されていないテキストを表示し、outputFormattedはテキストを表示して限られた範囲の書式設定オプションを設定できます。

明示的に指定された、またはリソース・バンドルまたはBeanからの単純テキストを表示するには、outputTextコンポーネントを使用します。valueプロパティの値として表示されるようにテキストを定義します。次に例を示します。

<af:outputText value="The submitted value was: "/>

例18-1に、2つのoutputTextコンポーネントを示します。1つ目では表示されるテキストが明示的に指定され、2つ目ではマネージドBeanからテキストが取得され、表示可能なテキスト値に値が変換されます(変換の詳細は、7.3項「変換の追加」を参照してください)。

例18-1 出力テキスト

<af:panelGroupLayout>
<af:outputText value="The submitted value was: "/>
<af:outputText value="#{demoInput.date}">
<af:convertDateTime dateStyle="long"/>
</af:outputText>
</af:panelGroupLayout>

escape属性を使用して、現在のマークアップ言語でHTMLおよびXMLの特殊文字をエスケープするかどうかを指定できます。デフォルトでは、特殊文字はエスケープされます。

例18-2に、2つのoutputTextコンポーネントを示します。1つ目ではescape属性にデフォルト値trueが使用され、2つ目では属性がfalseに設定されています。

例18-2 escapeプロパティ・セットがある出力テキストと、ない出力テキスト

<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"/>
<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"
escape="false"/>

図18-4に、escape属性の2とおりの設定をブラウザで表示したときの結果の違いを示します。

図18-4 escape属性を使用した出力テキスト

絶対に必要な場合以外、escape属性はfalseに設定しないでください。限られた数のHTMLタグを使用できるoutputFormattedコンポーネントを使用することをお薦めします。

outputFormattedコンポーネントでも、outputTextコンポーネント同様、valueプロパティに指定されたテキストが表示されますが、値にHTMLタグを含めることができます。値の一部のみを特定の方法で書式設定する場合は、outputFormattedコンポーネントの書式設定機能を使用します。コンポーネント値全体に同じスタイル設定を使用する必要がある場合は、値にHTMLを使用するかわりに、コンポーネント全体にスタイルを適用します。コンポーネントのすべてのインスタンスを特定の方法で書式設定する場合は、カスタム・スキンを作成する必要があります。インライン・スタイルの使用方法およびスキンの作成方法の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

例18-3に、値の一部のみが太字で表示されるoutputFormattedコンポーネントを示します(JSPXページの&lt;などのエンティティを使用する必要があります)。

例18-3 JSPXファイルの一部のテキストを太字にするためのoutputFormattedの使用

<af:outputFormatted value="&lt;b>This is in bold.&lt;/b> This is not bold"/>

例18-4 JSPファイルの一部のテキストを太字にするためのoutputFormattedの使用

<af:outputFormatted value="<b>This is in bold.</b> This is not bold"/>

図18-5に、コンポーネントによりテキストがどのように表示されるかを示します。

図18-5 outputFormattedコンポーネントを使用して書式設定されたテキスト

18.2.1 出力テキストの表示方法

出力テキストを表示する前に、値の一部を特別な方法で書式設定するかどうかを確認します。その場合は、outputFormattedコンポーネントを使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、18.2項「出力テキストおよび書式設定された出力テキストの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

出力テキストを表示する手順:

1. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「出力テキスト」をページにドラッグ・アンド・ドロップします。outputFormattedコンポーネントを作成するには、「コンポーネント」ウィンドウから「出力テキスト(フォーマット設定済)」をドラッグ・アンド・ドロップします。

ヒント:

値の一部に特別な書式設定を適用する場合は、outputFormattedコンポーネントを使用します。

ヒント:

アクティブ・データを使用したコンポーネントのテキストの変更をサポートする場合(たとえば、データソースからプッシュされているデータによって、表示されるテキストを決定する場合)、outputTextコンポーネントのかわりに、activeOutputTextコンポーネントを使用する必要があります。activeOutputTextコンポーネントを作成するには、「コンポーネント」ウィンドウから「出力テキスト(アクティブ)」をドラッグします。

2. 「プロパティ」ウィンドウの「共通」セクションを開き、表示する値をvalue属性で設定します。outputFormattedコンポーネントを使用している場合は、表18-1および表18-2の説明に従い、HTML書式設定コードを使用して必要に応じてテキストを書式設定します。
outputFormattedコンポーネントではstyleUsage属性もサポートされています。この属性値により、テキストに次に示す事前定義済のスタイルが適用されます。

- inContextBranding

- instruction

- pageStamp

図18-6に、styleUsage値によりコンポーネントにどのようなスタイルが適用されるかを示します。

図18-6 styleUsage属性の値

注意:

styleUsageおよびstyleClass属性の両方が設定されている場合は、styleClass属性が優先されます。

18.2.2 outputFormattedコンポーネントで使用可能な書式設定コードと文字コードに関する必知事項

特定の書式設定と文字コードのみ使用できます。表18-1に、outputFormattedコンポーネントの値の書式設定に使用可能な書式設定コードをリストします。

表18-1 af:outputFormatted値で使用するための書式設定コード

フォーマット・コード

効果

<br>

改行

<hr>

水平方向の罫線

<ol>...</ol><ul>...</ul><li>...</li>

リスト: 順序付けられたリスト、順序付けられていないリストおよびリスト項目

<p>...</p>

パラグラフ

<b>...</b>

太字

<i>...</i>

イタリック

<tt>...</tt>

テレタイプまたは等幅

<big>...</big>

大きいフォント

<small>...</small>

小さいフォント

<pre>...</pre>

事前フォーマット済: 保存済の空白と改行文字で定義されたレイアウト

<span>...</span>

囲まれたテキスト全体に影響

<a>...</a>

アンカー

表18-2に、値の特殊文字を表示するための文字コードをリストします。

表18-2 af:outputFormatted値で使用するための文字コード

文字コード

文字

&lt;

次より小さい

&gt;

次より大きい

&amp;

アンパサンド

&reg;

登録商標

&copy;

コピーライト

&nbsp;

改行なしの空白

&quot;

二重引用符

属性class、styleおよびsizeは、href構成と同様に、outputFormattedコンポーネントのvalue属性でも使用できます。その他すべてのHTMLタグは無視されます。

注意:

セキュリティ上の理由から、出力値ではJavaScriptはサポートされていません。

18.3 アイコンの表示

ADF Facesには、図18-7に示されているように、メッセージ・コンポーネントで使用される一連のアイコンが用意されています。

図18-7 ADF Facesのアイコン

アイコンをmessageコンポーネントの外に表示する場合は、iconコンポーネントを使用し、表示するアイコン・タイプの名前を指定します。

注意:

アイコンに使用されるイメージは、アプリケーションで使用されているスキンによって決定されます。イメージを変更する場合は、カスタム・スキンを作成します。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

18.3.1 アイコンの表示方法

ADF Facesアプリケーションでメッセージを使用すると、アイコンが自動的に追加されます。messageコンポーネントに追加する必要はありません。ただし、アイコンをmessageコンポーネントの外で使用することもできます。アプリケーションのスキンに定義されている標準アイコンのいずれかを表示するには、iconコンポーネントを使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、18.3項「アイコンの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

標準アイコンを表示する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「アイコン」をページにドラッグ・アンド・ドロップします。

2. 図18-7に示されているように、「共通」セクションを開き、Nameをアイコン機能の1つの名前に設定します。たとえば、中に白いXがある赤い丸を表示する場合は、Nameをerrorに設定します。

3. 「外観」セクションを開き、アイコンの代替テキストとして表示するテキストをShortDescで設定します。

18.4 イメージの表示

ページにイメージを表示するには、imageコンポーネントを使用し、source属性をファイルが存在するURIに設定します。imageコンポーネントでは、イメージの詳細な説明へのリンクを提供することで、アクセシビリティの説明テキストもサポートされています。

imageコンポーネントは、リンクとして使用することもでき、イメージ・マップを入れることができますが、その場合はlinkコンポーネント内に配置する必要があります。詳細は、18.5項「リンクとしてのイメージの使用」を参照してください。

18.4.1 イメージの表示方法

imageコンポーネントを使用してイメージを表示します。

始める前に:

他のADF Faces機能を使用して追加できる機能について理解しておくと役立つ可能性があります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

イメージを表示する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「イメージ」をページにドラッグ・アンド・ドロップします。

ヒント:

アクティブ・データを使用したイメージのsource属性の変更をサポートする場合(たとえば、データソースからプッシュされているデータによって、表示されるイメージを決定する場合)、imageコンポーネントのかわりに、activeImageコンポーネントを使用する必要があります。activeImageコンポーネントを作成するには、「コンポーネント」ウィンドウから「イメージ(アクティブ)」をドラッグします。

2. 「イメージの挿入」ダイアログで、次の設定を行います。

- Source: イメージ・ファイルへのURIを入力します。

- ShortDesc: イメージの代替テキストとして使用するテキストに設定します。

3. イメージの長い説明を表示する場合は、「プロパティ」ウィンドウでLongDescURL属性を設定します。この属性では、表示したい情報が存在するURIを指定します。

18.5 リンクとしてのイメージの使用

ADF Facesのlinkコンポーネントを利用すると、イメージをリンクとしてレンダリングできます。必要に応じてテキストも表示できます。ユーザーがアイコンにマウスを置いた場合や、アイコンが押された場合または無効化された場合に、別々のアイコンを設定できます。linkコンポーネントの詳細は、20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

イメージをlinkコンポーネントとして使用して、1つ以上の移動先にリンクすることができます。イメージを単一の移動先への単純なリンクとして使用する場合は、linkコンポーネントを使用してその中にイメージを入れ、linkコンポーネントのdestination属性をリンクの移動先のURIに設定します。

イメージをグラフィカルなナビゲーション・メニューとして使用して、グラフィックの領域ごとに別のURIに移動するように設定するには、imageコンポーネントをlinkコンポーネントの中に入れて、イメージに対するサーバー側イメージ・マップを作成します。

18.5.1 イメージをリンクとして使用する方法

linkコンポーネントを使用して、イメージをリンクとしてレンダリングします。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、18.5項「リンクとしてのイメージの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

イメージを1つ以上のlinkコンポーネントとして使用する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「リンク」をページにドラッグ・アンド・ドロップします。

2. 「イメージ」を「リンク」コンポーネントに子としてドラッグ・アンド・ドロップします。

3. 「イメージの挿入」ダイアログで、次の設定を行います。

- Source: イメージ・ファイルへのURIを入力します。

- ShortDesc: イメージの代替テキストとして使用するテキストに設定します。

4. イメージの異なる領域を別々の移動先にリンクさせる場合は、次のようにします。

- イメージのイメージ・マップを作成し、サーバーに保存します。

- 「プロパティ」ウィンドウで、ImageMapType属性をserverに設定します。

- 「リンク」コンポーネントを選択し、「プロパティ」ウィンドウで「宛先」をサーバー上のイメージ・マップのURIに設定します。

5. イメージ全体を単一の移動先にリンクする場合は、「リンク」コンポーネントを選択し、リンク先のURIを「宛先」の値として入力します。

18.6 アイコンを使用したアプリケーション・ステータスの表示

ADF FacesにはstatusIndicatorコンポーネントがあり、サーバー・アクティビティを示すために使用できます。表示される内容は、アプリケーションが使用しているスキンおよびサーバーの構成方法によって異なります。デフォルトでは、次のものが表示されます。

- アプリケーションが標準のデータ転送サービスを使用するように構成されている場合、データ転送中にアニメーション化されたスピニング・アイコンが表示されます。

サーバーがビジーではない場合、静的アイコンが表示されます。

- アプリケーションがアクティブ・データ・サービス(ADS)を使用するように構成されている場合、ステータス・インジケータに表示される内容は、ADSがどのように構成されているかによって異なります。

注意:

ADSを使用すると、アプリケーションをアクティブ・データ・ソースにバインドできます。ADSを使用するには、Fusionテクノロジ・スタックを使用する必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アクティブ・データ・サービスの使用方法」の章を参照してください。

ADSは、データをモデルにプッシュするように構成するか、アプリケーションが指定の間隔でデータをポーリングするように構成できます。表18-3に、プッシュおよびポーリング・モードのサーバー状態を表示するために使用されるアイコンを示します(アイコンは実際はアニメーション化されています)。

表18-3 ADSのステータス・インジケータで使用されるアイコン

アイコン

プッシュ・モード

プル・モード

サーバーへの最初の接続試行時。

サーバーへの最初の接続試行時。

最初の接続が正常に確立されたとき。

最初の接続が正常に確立されたときおよび接続が再確立されたとき。

サーバーに再接続するための後続の試行が行われたとき。

すべてのポーリング・リクエスト前。

接続を確立または再確立できないとき。

構成された数のポーリング試行が失敗したとき。

statusIndicatorコンポーネントをページにドロップした後で、コンポーネントで使用される実際のイメージ・ファイルを、スキンを使用して変更できます。スキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、18.6項「アイコンを使用したアプリケーション・ステータスの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

ステータス・インジケータ・アイコンを使用する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「ステータス・インジケータ」をページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウを使用して必要な属性を設定します。

ヒント:

属性の設定のヘルプとして、フィールドのドロップダウン・メニューを使用して属性の説明を表示します。

18.7 ビデオ・クリップおよび音声クリップの再生

ADF Facesのmediaコンポーネントを使用すると、アプリケーション・ページにビデオ・クリップや音声クリップを含めることができます。

メディア・コントロールでは、クロス・プラットフォームのメディア表示の複雑な2つの側面(メディアの表示に最適なプレーヤの決定、およびメディア・プレーヤのサイズ変更)を処理します。

ユーザーに表示するプレーヤのサイズとともに、各クリップに適したメディア・プレーヤを指定できます。デフォルトで、ADF Facesでは、メディア・リソースのMIMEタイプを使用して、最適なメディア・プレーヤおよび使用するデフォルトの内部プレーヤ・サイズが決定されますが、コンテンツ・タイプはcontentType属性を使用して指定できます。

ユーザーが使用できるコントロール、およびクリップを自動的に再生するかどうか、連続再生するか指定された回数再生するかなど、その他のプレーヤ機能を指定できます。

18.7.1 音声クリップおよびビデオ・クリップの再生を可能にする方法

mediaコンポーネントをページに追加した後で、デフォルトで使用するメディア・プレーヤ、プレーヤと画面のサイズ、およびコントロールを構成します。クリップを再生するかどうかも構成できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、18.7項「ビデオ・クリップおよび音声クリップの再生」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、18.1.2項「出力コンポーネントの追加機能」を参照してください。

アプリケーション・ページに音声クリップまたはビデオ・クリップを含める手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、「メディア」をページにドラッグ・アンド・ドロップします。

2. 「メディアの挿入」ダイアログで、次の属性を設定します。

- Source: 再生するメディアへのURIを入力します。

- StandbyText: コンテンツのロード中に表示するメッセージを入力します。

3. 「プロパティ」ウィンドウの「共通」セクションを開いて、次のとおりに設定します。

- Player: クリップの再生にデフォルトで使用されるメディア・プレーヤを選択します。Real Player、Windows Media PlayerまたはApple QuickTime Playerから選択できます。
または、ユーザー・エージェントの組込みのコンテンツ・タイプ・マッピングに基づいて、メディア・リソースの再生を開始するリンクをページに作成できます。メディア・コントロールにより、次の手順で、適切なメディア・プレーヤの選択が試行されます。

- コンテンツのプライマリMIMEタイプがイメージの場合は、組込みのユーザー・エージェント・サポートが使用されます。

- player属性でメディア・プレーヤが指定されていて、そのプレーヤをユーザー・エージェントで使用でき、メディア・リソースを表示できる場合は、そのプレーヤが使用されます。

- あるプレーヤがメディア・リソースの再生に最適で、そのプレーヤをユーザー・エージェントで使用できる場合は、そのプレーヤが使用されます。

- ユーザー・エージェントであるプレーヤが特に優先されており、そのプレーヤでメディア・リソースを再生できる場合は、そのプレーヤが使用されます。

- ページに表示されているリンクに接続しているプレーヤが使用されます。

- Autostart: ロード後すぐにクリップの再生を開始する場合はTrueに設定します。

- ContentType: 再生するメディアのMIMEタイプを入力します。これは、使用するプレーヤ、コントロールの構成、および表示サイズの決定に使用されます。

4. 「プロパティ」ウィンドウの「外観」セクションを開いて、次のとおりに設定します。

- Controls: プレーヤに表示するコントロールの量とタイプを選択します。
使用可能なコントロールのセットはプレーヤによって異なるため、実際のコントロールをリストするのではなく、一般的な方法で表示するコントロールのセットを定義します。たとえば、使用可能なすべてのコントロールや、最も一般的に使用されるコントロールをプレーヤに表示することも、コントロールを表示しないこともできます。

たとえば、例18-5では、mediaコンポーネントにall設定が使用されています。

例18-5 メディア・プレーヤのコントロール

<af:media source="/images/myvideo.wmv" controls="all"/>

図18-8に、プレーヤがユーザーに対してどのように表示されるかを示します。

図18-8 すべてのコントロールが表示されたメディア・プレーヤ

有効な値は次のとおりです。

- All: メディア・プレーヤでメディアを再生するための使用可能なすべてのコントロールが表示されます。
この設定を使用すると、使用するメディア・プレーヤによっては、大量の追加領域が必要になります。

- Minimal: メディア・プレーヤでメディアを再生するための最小限のコントロールのセットが表示されます。
この値を使用すると、ユーザーが最も重要なメディア再生コントロールを制御できる一方で、ユーザー・エージェントにおける最低限の追加の領域が占有されます。

- None: メディア・プレーヤにコントロールは表示されず、ポップアップ・メニューなど、その他の方法でコントロールにアクセスすることもできません。
通常、この設定は、メディアの再生に対するユーザーの制御が許可されていないkioskタイプのアプリケーションにのみ使用します。この設定は、通常、再生が自動的に開始される設定、および連続して再生される設定とともに使用されます。

- NoneVisible: メディア・プレーヤにコントロールは表示されませんが、ポップアップ・メニューなど、かわりの方法でコントロールにアクセスできます。
通常、この値は、メディアの再生に対するユーザーの制御は許可されているが、推奨されていないアプリケーションにのみ使用します。none設定同様、この設定は、再生が自動的に開始される設定、および連続して再生される設定とともに使用されます。

- Typical: メディア・プレーヤでメディアを再生するための一般的なコントロールのセットが表示されます。
この値はデフォルトで、ユーザー・エージェントで過度に余分な領域を占有せずに、ユーザーは最も一般的なメディア再生コントロールを制御できるようになります。

- WidthおよびHeight: ピクセル単位で完全な表示(メディアのコンテンツ領域も含むプレーヤ領域全体)のサイズを定義します。

ヒント:

widthおよびheight属性を使用すると、様々なプレーヤおよびプレーヤ・コントロール構成で使用する適切な幅と高さを定義するのが困難なため、予期しない結果が発生することがあります。完全な表示のサイズを定義するかわりに、innerWidthおよびinnerHeight属性を使用して、メディア・コンテンツ領域のサイズを定義できます。

- InnerWidthおよびInnerHeight: メディア・コンテンツ領域のみのサイズをピクセル単位で定義します。クリップのプレーヤ領域に割り当てられた領域を制御するため、これが推奨のスキームです。

ヒント:

メディア・コントロールのサイズを指定しない場合は、メディア・リソースのコンテンツ・タイプで指定されたデフォルトの内部サイズが使用されます。これは音声コンテンツでは問題ありませんが、ビデオ・コンテンツでは、コンテンツの一部が表示されない原因や必要以上に領域を占有する原因になります。

両方のスキームでheightやinnerHeightなどの大きさを指定した場合は、height属性で定義された全体のサイズが使用されます。同様に、widthとinnerWidthの両方を指定すると、width属性が使用されます。

5. 「動作」セクションを開き、Autostartを設定します。デフォルトでは、表示されたコントロールを使用してユーザーが開始するまで、クリップの再生は開始されません。autostart属性をtrueに設定することで、クリップのロードと同時に再生を開始することを指定できます。
PlayCountを、メディアを再生する回数に設定します。デフォルトでは、開始されたらクリップは一度のみ再生されます。コントロールが使用可能な場合には、ユーザーはクリップを再度再生できます。ただし、playCount属性に値を設定することで、クリップを固定回数再生することや、連続して繰り返すことを指定できます。playCount属性を0に設定すると、クリップは連続して再生されます。この属性をその他の数値に設定すると、クリップは指定された回数再生されます。

例18-6に、ページのソースのaf:mediaコンポーネントを示します。このコンポーネントでは、ロードされるとすぐにビデオ・クリップの再生が開始され、ユーザーが停止するまでクリップの再生を継続します。プレーヤには、使用可能なコントロールがすべて表示されます。

例18-6 ビデオ・クリップを連続再生するmediaコンポーネント

<af:media source="/components/images/seattle.wmv" playCount="0"
autostart="true" controls="all"
innerHeight="112" innerWidth="260"
shortDesc="My Video Clip"
standbyText="My video clip is loading"/>

19 ヒント、メッセージおよびヘルプの表示

この章では、shortDesc属性を使用してヒントを表示する方法と、ADF Facesのコンポーネントに対するメッセージを表示する方法を説明します。この章では、ユーザーのために様々なレベルのヘルプ情報を提供する方法も説明します。

この章では、次の項目について説明します。

- 19.1項「ヒントおよびメッセージの表示について」

- 19.2項「コンポーネントのヒントの表示」

- 19.3項「検証および変換用のヒントとエラー・メッセージの表示」

- 19.4項「単一のラベルおよびメッセージを使用したコンポーネントのグループ化」

- 19.5項「コンポーネントへのヘルプの表示」

- 19.6項「様々なメッセージ・タイプの組合せ」

19.1 ヒントおよびメッセージの表示について

ADF Facesでは、様々な方法でアプリケーションに情報テキストを表示できます。精巧なヘルプ・システムだけでなく、簡単なヒント・テキスト、検証および変換のヒント・テキストやエラー・メッセージも作成できます。

図19-1 ADFメッセージング・コンポーネント

ADF Facesの多くのコンポーネントではshortDesc属性がサポートされており、この属性は大部分のコンポーネントで、ユーザーがコンポーネント上にカーソルを置いたときにヒント情報を表示します。図19-2に、ツールバー・ボタンに構成されたヒントを示します。

図19-2 マウスを置いたときにヒントに情報が表示される

ヒントと同様に、ADF Facesのコンポーネントの中にも、たとえばinputTextコンポーネントや選択コンポーネントのように、ポップアップ・ヒント・メッセージや失敗メッセージを表示できるものがあり、検証や変換に使用されます。作成できるメッセージのタイプは2つあります。1つはコンポーネント・レベル・メッセージで、特定のコンポーネントに適用されます。もう1つはグローバル・レベル・メッセージで、特定のページに、またはコンポーネントのグループに適用されます。図19-3に示すヒント・メッセージは、入力日付フィールドに対して構成されています。

図19-3 ヒント・メッセージに入力日付のフォーマットを表示

個々のコンポーネント・インスタンスにメッセージを構成するとともに、アプリケーション全体で再利用可能な情報を提供する個別のヘルプ・システムを作成できます。ヘルプ情報はタイプの異なるプロバイダを使用して作成し、UIコンポーネントからヘルプ・テキストを参照します。次に、ADF Facesでサポートされている3つのタイプのヘルプを示します。

- 定義: 図19-4に示すように、ユーザーがアイコン上にマウスを置くと、ヘルプ・テキストが表示されるヘルプ・アイコン(疑問符が表示された青い丸)を表示します。

図19-4 アイコン上にマウスを置くと表示される定義メッセージ

- 説明: このタイプのヘルプはコンポーネントに応じて、(panelHeaderコンポーネントのように)コンポーネント内に説明テキストを表示するか、図19-5に示すように、ユーザーがコンポーネントをクリックした際に開かれる注意ウィンドウにテキストを表示します。テキストの長さの制限はありません。

図19-5 注意ウィンドウに表示されている説明メッセージ

- 外部URL: 別のブラウザ・ウィンドウで開く、外部アプリケーションに存在するヘルプ・トピックを作成できます。たとえば、図19-6では、説明ヘルプを表示するかわりに、スキンに関するヘルプ・トピックを開くよう構成された、スキン選択のselectOneChoiceコンポーネントが表示されています。ユーザーがselectOneChoiceコンポーネントをクリックすると、ヘルプ・トピックが開きます。

図19-6 新しいウィンドウに開かれている外部URLヘルプ

ヘルプ・システムの作成の詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

19.1.1 メッセージング・コンポーネントのユースケースおよび例

通常、メッセージは、アプリケーションでエラーが発生した場合(ユーザーが互換性のない情報を入力した場合など)に表示されるエラー・メッセージのタイプと、コンポーネントの使用やページでのタスクの完了に関するヒントなどを提供する情報メッセージのタイプに分けられます。

情報メッセージは、単純なツールチップから複雑なヘルプ・システムまで多岐にわたります。ヒントまたは情報を表示するコンポーネントでヘルプ・テキストがサポートされていない場合には、ツールチップを使用する必要があります。ただし、ツールチップ・テキストは簡潔にする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、ヘルプ・テキストの使用を検討してください。

ツールチップは、コンポーネントにshortDesc属性を構成して作成します。これで、ユーザーがコンポーネントにカーソルを置くかコンポーネントをクリックしたときに(たとえばinputTextコンポーネントの場合)、その属性の値がノート・ウィンドウに表示されるようになります(図19-7を参照)。

図19-7 コンポーネントのツールチップ

ツールチップの詳細は、19.2項「コンポーネントのヒントの表示」を参照してください。

エラー・メッセージでは、JSFメッセージングAPIが使用されます。エラー・メッセージには、メッセージが特定コンポーネントにのみ当てはまるコンポーネント・メッセージと、複数のコンポーネントやページ全体に当てはまるグローバル・メッセージの2つのタイプがあります。

デフォルトでは、noteWindowコンポーネントはコンポーネント・エラー・メッセージに使用されます。入力コンポーネントに変換や検証を構成すると、noteWindowコンポーネントに、検証および変換のヒントやエラーが自動的に表示されます。ページにコンポーネントを追加する必要はありません。

たとえば、File Explorerアプリケーションでユーザーが「Help」 > 「Give Feedback」をクリックすると、カスタマ・サービスの担当者が連絡する日時を入力可能なダイアログが表示されます。inputDateコンポーネントにはコンバータが含まれているため、ユーザーがフィールドをクリックすると、図19-8に示すように、予想されるパターンを示すヒントが注意ウィンドウに表示されます。inputDateコンポーネントに最小値または最大値も構成されている場合は、その情報もヒントに表示されます。これらのヒントは、コンバータおよびバリデータにより自動的に表示されます。

図19-8 アタッチされている、メッセージを含むコンバータおよびバリデータ

図19-8に表示されているフィールドにユーザーが入力した日付が正しくない場合は、図19-9に示すようにエラー・メッセージが表示されます。エラー・メッセージは、ヒントともに注意ウィンドウに表示されることに注意してください。

図19-9 注意ウィンドウに表示されている検証および変換のエラー

ADF Facesコンポーネント以外にエラー・メッセージを表示する場合、または注意ウィンドウではなく、インラインでメッセージを表示する場合は、ADF Faces messageコンポーネントを使用します。このコンポーネントを使用するときは、メッセージはコンポーネントの隣に表示されます(図19-10を参照)。

図19-10 messageコンポーネントを使用したメッセージのインラインでの表示

グローバル・メッセージはデフォルトで、図19-11に示すように、ダイアログ内に表示されます。ページにポップアップ・コンポーネントを追加する必要はありません。

図19-11 ポップアップ・ウィンドウに表示されているグローバル・メッセージ

エラー・メッセージをページに直接表示する場合は、messagesコンポーネントを使用します。このコンポーネントを使用すると、図19-12に示すように、ページ上部のリストにメッセージが表示されます。

図19-12 messagesコンポーネントを使用した、ページへのグローバル・メッセージの表示

エラー・メッセージの詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

ツールチップに収まる量を超える情報を表示する必要がある場合は、定義ヘルプを使用します。定義ヘルプを構成すると、大部分のコンポーネントで、そのコンポーネントの隣にヘルプ・アイコンが表示されます。図19-13に示すように、コンポーネント上にマウスが置かれると、ヘルプ・テキストが表示されます。

図19-13 列コンポーネントの定義ヘルプ

定義ヘルプの詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

フィールドレベル・ヘルプを表示する場合は、説明テキストを使用するように入力コンポーネントを構成します。ユーザーがコンポーネントをクリックすると、図19-14に示すように、注意ウィンドウにヘルプ・テキストが表示されます。

図19-14 コンポーネントの説明テキスト

タスクの説明を表示する場合は、コンテナ・コンポーネントに説明ヘルプを構成します。図19-15に示すように、コンポーネントのヘッダーにテキストが表示されます。

図19-15 panelHeaderコンポーネントの説明テキスト

ベスト・プラクティス:

入力コンポーネントの説明テキストは、説明なしでは、通常のユーザーがタスクに失敗する可能性がある場合にのみ使用します。説明テキストを多用すると、ページが指示で煩雑になったり、関連するページ要素が注意ウィンドウで見えにくくなり、ユーザーの注意が散漫になったりします。

複雑なヘルプを作成する必要がある場合は、ヘルプ・アイコンを使用して、URLを介してアクセス可能な外部ヘルプ・システムにリンクできます。

説明および外部ヘルプの詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

19.1.2 メッセージ・コンポーネントのその他の機能

メッセージ・コンポーネントおよびヘルプ機能を実装する前に、ADF Facesのその他の機能を理解しておくと役に立ちます。また、ページにこれらのコンポーネントを追加してから、アイコンを変更するためのスキニング、アクセシビリティ、およびメッセージ・テキストを格納するためのリソース・バンドルの使用などの機能の追加が必要なことに気が付く場合もあります。次に、メッセージ・コンポーネントで使用できるその他の機能へのリンクを示します。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- クライアント・イベント: JavaScriptを使用してヘルプ・トピックを起動する場合は、クライアント・イベントにリスナーを使用します。クライアント側イベントの詳細は、6.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。

- スキニング: メッセージおよびヘルプに表示されるアイコンは、アプリケーションに使用されているスキンによって決まります。アイコンは、新しいスキンを作成することで変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- ローカライゼーション: メッセージに直接テキストを入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

19.2 コンポーネントのヒントの表示

ADF Facesコンポーネントでは、ユーザーがコンポーネント上にマウスを置いた場合、shortDesc属性を使用してヒントが表示されます。入力コンポーネントでは、注意ウィンドウにヒントが表示されます。その他のコンポーネント・タイプでは、標準のヒント・ボックスにヒントが表示されます。このテキストは短くする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、19.5項「コンポーネントへのヘルプの表示」で説明されているように、ヘルプ・テキストの使用を検討してください。

図19-16に、inputTextコンポーネント上にカーソルが置かれた際の様子を示します。

図19-16 inputTextコンポーネントのヒント

図19-17に、showDetailItemコンポーネントに表示されたヒントを示します。

図19-17 showDetailItemコンポーネントのヒント

19.2.1 コンポーネントへのヒントの表示方法

ヒントを表示するには、コンポーネントにshortDesc属性を使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.2項「コンポーネントへのヒントの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、19.1.2項「メッセージ・コンポーネントのその他の機能」を参照してください。

コンポーネントにヒントを定義する手順:

1. 構造ウィンドウで、ヒントを表示するコンポーネントを選択します。

2. 「プロパティ」ウィンドウの「外観」セクションを開き、shortDesc属性の値を入力します。

ヒント:

80文字を超えると、ブラウザによってはヒントが切り捨てられてしまうため、値は80文字未満にする必要があります。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

19.3 検証および変換用のヒントとエラー・メッセージの表示

バリデータおよびコンバータには、関連するフィールドがクリックされた際にユーザーに表示されるデフォルトのヒントがあります。デフォルトのヒントは自動的にノート・ウィンドウに表示されます。コンバータの場合、ヒントは、使用する適切な書式をユーザーに示します。バリデータの場合、ヒントは有効な値を示すために使用されます。

たとえば、図19-18に示すように、File Explorerアプリケーションでは、ユーザーが「カスタマ・サービスに連絡」ページの日付入力フィールドをクリックすると、使用する正しい書式が示されたヒントが表示されます。

図19-18 組込みメッセージのあるバリデータおよびコンバータ

ADF Facesコンポーネントの値が検証に失敗した場合、またはコンバータで変換できない場合は、コンポーネントに結果のFacesMessageインスタンスが表示されます。

たとえば、図19-19に示されているように、コンバータのdateStyle属性に一致しない日付を入力すると、エラー・メッセージが表示されます。

図19-19 実行時の検証エラー

デフォルトのバリデータおよびコンバータのヒントとエラー・メッセージを、1つのコンポーネント・インスタンスに対して、またはすべてのインスタンスに対してグローバルにオーバーライドできます。コンポーネント・インスタンスにカスタム・メッセージを定義するには、表示する詳細なメッセージに属性を設定します。実際の属性は、バリデータまたはコンバータによって異なります。図19-20に表示されている属性の値を入力すると、「プロパティ」ウィンドウに表示される、convertDateTimeコンバータのメッセージがオーバーライドされます。

図19-20 コンバータのメッセージ属性

コンポーネントのすべてのインスタンスで使用されるエラー・メッセージを定義するには、デフォルト・メッセージをオーバーライドするリソース・バンドルにエントリを作成する必要があります。

注意ウィンドウにメッセージを表示しない場合は、messageコンポーネントを使用すると、メッセージがコンポーネントにインラインで表示されます。図19-21に、messageコンポーネントを使用してメッセージがどのように表示されるかを示します。

図19-21 messageコンポーネントを使用したメッセージのインラインでの表示

ADF FacesアプリケーションのJSFページでは、特にポップアップ・ウィンドウへのすべてのグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)の表示を処理するdocumentタグが使用されています。ただし、グローバル・メッセージをページに表示する場合は、messagesコンポーネントを使用します。

注意:

HTMLタグを使用してメッセージの書式を設定するには、メッセージを<html></html>タグで囲む必要があります。次に例を示します。

<html><b>error</b> message details</html>

エラー・メッセージでは、次のHTMLタグを使用できます。

- <span>

- <b>

- <a>

- <i>

- <em>

- <br>

- <hr>

- <li>

- <ol>

- <ul>

- <p>

- <tt>

- <big>

- <small>

- <pre>

19.3.1 コンポーネント・インスタンスへのバリデータおよびコンバータのカスタム・メッセージの定義方法

単一のコンポーネント・インスタンスのデフォルトのバリデータおよびコンバータのメッセージをオーバーライドするには、異なるメッセージ属性に値を設定します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、19.1.2項「メッセージ・コンポーネントのその他の機能」を参照してください。

バリデータまたはコンバータのメッセージを定義する手順:

1. 構造ウィンドウで、エラー・メッセージを作成するコンバータまたはバリデータを選択します。

2. 「プロパティ」ウィンドウの「メッセージ」セクションを開き、メッセージを表示する属性の値を入力します。
値には、{0}、{1}、{2}などのパラメータ・プレースホルダを使用して、動的コンテンツを含めることができます。たとえば、convertDateTimeコンバータのmessageDetailConvertDate属性には、次のパラメータが使用されます。

- {0}: コンポーネントを識別するラベル

- {1}: ユーザーによって入力される値

- {2} : コンポーネントで想定される書式の例

ヒント:

- アプリケーションで双方向または右から左への表示を使用する場合は、想定書式パラメータ{2}をメッセージの先頭に置かないでください。Internet Explorerでは正しく表示されない可能性があるからです。

- 書式パラメータ{1}をメッセージ内に表示することはできるだけ避けてください。ユーザー入力を表示することは、セキュリティ違反とみなされることがあります。

これらのパラメータを使用すると、次のメッセージを作成できます。

The date you have entered in the \"{0}\" field is not using the correct date format. Please enter the date as follows: {2}.

エラー・メッセージは、図19-22のように表示されます。コンバータのType属性の値をパラメータに合せて変更することが必要になる可能性があります。

図19-22 実行時の詳細なメッセージ

ヒント:

メッセージで使用されたパラメータを含むプロパティ・ヘルプを表示するには、ドロップダウン・メニューを使用します。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

注意:

メッセージ・テキストは、FacesMessageオブジェクトの詳細なメッセージ用です。サマリー(メッセージの上部に表示されるテキスト)をオーバーライドする場合は、グローバルにのみ実行できます。詳細は、19.3.2項「コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法」を参照してください。

19.3.2 コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法

messageDetail[XYZ]属性を使用してコンポーネント・インスタンスごとにメッセージの文字列を変更するかわりに、カスタム文字列がすべてのインスタンスに表示されるように文字列をグローバルにオーバーライドできます。グローバル・メッセージは、メッセージ・バンドルのキーと値のペアによって処理されます。サマリー、詳細およびヒント・メッセージをオーバーライドできます。

デフォルトのバリデータまたはコンバータのメッセージをグローバルにオーバーライドする手順:

1. オーバーライドするメッセージのメッセージ・キーを定義するには、付録B「コンバータおよびバリデータ・メッセージのメッセージ・キー」を参照してください。たとえば、入力値が最大の値の長さを超えた場合に表示される詳細メッセージをオーバーライドするには、B.3.8項「af:validateLength」に示すように、キーorg.apache.myfaces.trinidad.validator.LengthValidator. MAXIMUM_detailを使用します。

2. メッセージ・バンドルを作成するか開きます。メッセージ・バンドルを作成する手順は、32.3.1項「リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する方法」を参照してください。

3. メッセージ・バンドルにキー・オーバーライドを追加します。たとえば、入力値の長さに関するメッセージをオーバーライドするには、次のような内容を追加します。

org.apache.myfaces.trinidad.validator.LengthValidator.MAXIMUM_detail: Your value exceeds the limit.

4. メッセージ・バンドルが新規リソース・バンドルである場合は、faces-config.xmlファイルを使用してバンドルをアプリケーションに登録する必要があります。手順は32.3.5項「アプリケーションでのリソース・バンドルの登録方法」を参照してください。ただし、<resource-bundle>タグではなく、<message-bundle>タグを使用します。

19.3.3 コンポーネントのメッセージをインラインで表示する方法

コンポーネントで注意ウィンドウにメッセージを表示するかわりに、messageコンポーネントを使用して、ページにインラインでメッセージを表示できます。messageコンポーネントで正しいメッセージが表示されるようにするには、特定のコンポーネントと関連付けます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、19.1.2項「メッセージ・コンポーネントのその他の機能」を参照してください。

コンポーネントのメッセージをインラインで表示する手順:

1. 構造ウィンドウで、messagesコンポーネントを使用してメッセージを表示するコンポーネントを選択します。まだ設定されていない場合は、コンポーネントのIDを入力します。

2. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「メッセージ」をドラッグし、ページ上のメッセージを表示する場所にドロップします。

3. ドロップダウン・メニューを使用してfor属性に「編集」を選択します。

4. 「プロパティの編集」ダイアログで、messagesコンポーネントでメッセージを表示するコンポーネントを探します。IDの設定されているコンポーネントのみが有効な選択肢です。

注意:

表示されるメッセージ・アイコンとメッセージ・コンテンツは、FacesMessageオブジェクトの作成時に指定されたものに基づきます。messageコンポーネントにmessageTypeまたはmessage属性を設定すると、エラーが発生したかどうかに関係なく、実行時にmessageTypeまたはmessage属性の値が表示されます。これらの属性は、ページのレンダリング時に必ずコンテンツを表示する場合にのみ移入します。

19.3.4 グローバル・メッセージをインラインで表示する方法

グローバル・メッセージをページのポップアップ・ウィンドウに表示するかわりに、messagesコンポーネントを使用してインラインで表示します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、19.1.2項「メッセージ・コンポーネントのその他の機能」を参照してください。

グローバル・メッセージをインラインで表示する手順:

1. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「メッセージ」をドラッグし、ページ上のメッセージを表示する場所にドロップします。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- globalOnly: デフォルトでは、ADF Facesはグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)を表示し、次に個々のコンポーネントのメッセージを表示します。ボックスにグローバル・メッセージのみを表示する場合は、この属性をtrueに設定します。コンポーネント・メッセージは、関連付けられたコンポーネントに引き続き表示されます。

- inline: ページの上部にメッセージを表示する場合にtrueに設定します。そうしない場合、メッセージはダイアログに表示されます。

19.3.5 実行時の処理: メッセージの表示

ADF Facesでは、標準のJSFメッセージングAPIが使用されています。JSFでは、addMessage(java.lang.String clientId, FacesMessage message)メソッドを使用してFacesContextオブジェクトにFacesMessageインスタンスを追加できるようにすることで、メッセージング用の組込みのフレームワークがサポートされています。コンポーネント・レベルのメッセージは、特定のコンポーネントに関連付けられます。この関連付けの基準になるのは、addMessageメソッドに渡されたクライアントIDです。グローバル・レベルのメッセージには、コンポーネントは関連付けられません。addMessageメソッドにクライアントIDは渡されないからです。

EditableValueHolder ADF Facesコンポーネントで変換または検証が失敗すると、FacesContextインスタンスのメッセージ・キューにFacesMessagesオブジェクトが自動的に追加され、コンポーネントのIDが渡されます。これらのメッセージは、コンポーネントの注意ウィンドウに表示されます。ADF Facesコンポーネントには、独自のメッセージを表示できます。タグを追加する必要はありません。

FacesMessagesコンポーネントのみでなく、documentタグも、すべてのグローバルなFacesMessagesオブジェクト(関連付けられているコンポーネントIDがない)の処理および表示を行います。コンポーネント・メッセージと同様に、メッセージを表示するために開発者がタグを追加する必要はありません。グローバル・メッセージ(または複数のコンポーネント・メッセージ)が作成されると、キュー内のすべてのメッセージがポップアップ・ウィンドウに表示されます(図19-23を参照)。

図19-23 documentにより表示されるグローバル・メッセージおよびコンポーネント・メッセージ

ヒント:

ADF Facesには検証および変換用のメッセージがありますが、標準のJSFメッセージングAPIを使用して、キューにFacesMessagesオブジェクトを追加できます。追加すると、ADF Facesにより、メッセージ・レベルに基づいて、次のようなアイコンがメッセージとともに表示されます。

19.4 単一のラベルおよびメッセージを使用したコンポーネントのグループ化

ADF Facesの入力および選択コンポーネントには、デフォルトで、ラベルおよびメッセージの表示用に組込みサポートが用意されています。コンポーネントをグループ化して単一のラベルを使用する場合は、panelLabelAndMessageコンポーネントを使用してコンポーネントをラップします。

たとえば、File Explorerアプリケーションでは、別々のinputTextコンポーネントを4つ(市外局番、市内局番、最後の4桁、および内線のそれぞれに1つずつ)使用して電話番号を収集します。単一のラベルが必要なため、4つのinputTextコンポーネントはpanelLabelAndMessageコンポーネントにラップされ、ラベルの値はそのコンポーネントに設定されます。ただし、内線の入力コンポーネントには追加のラベルが必要なため、outputTextコンポーネントが使用されます。例19-1に、panelLabelAndMessageコンポーネントのJSFコードを示します。

例19-1 単一のラベルおよびヘルプ・トピックの表示が可能なpanelLabelAndMessage

<af:panelLabelAndMessage labelAndAccessKey="#{explorerBundle['help.telephone']}"
helpTopicId="HELP_TELEPHONE_NUMBER"
labelStyle="vertical-align: top;
padding-top: 0.2em;">
<af:inputText autoTab="true" simple="true" maximumLength="3"
columns="3">
<af:convertNumber type="number" integerOnly="true"/>
</af:inputText>
<af:inputText autoTab="true" simple="true" maximumLength="3"
columns="3">
<af:convertNumber type="number" integerOnly="true"/>
</af:inputText>
<af:inputText autoTab="true" simple="true" maximumLength="4"
columns="4">
<af:convertNumber type="number" integerOnly="true"/>
</af:inputText>
<af:outputText value="#{explorerBundle['help.extension']}"/>
<af:inputText simple="true" columns="4">
<af:convertNumber type="number" integerOnly="true"/>
</af:inputText>
</af:panelLabelAndMessage>

図19-24に、panelLabelAndMessageおよびネストしたコンポーネントがブラウザにどのように表示されるかを示します。

図19-24 panelLabelAndMessageコンポーネントの使用例

panelLabelAndMessageコンポーネントには、グループの最後に追加のコンポーネントを表示するために使用できるEndファセットも含まれます。図19-25に、EndファセットにoutputTextコンポーネントが移入されている場合に、電話番号フィールドがどのように表示されるかを示します。

図19-25 panelLabelAndMessageコンポーネント内のEndファセット

panelLabelAndMessageコンポーネント内にpanelGroupLayoutコンポーネントを使用して、必要なレイアウトのコンポーネントをグループ化します。panelGroupLayoutコンポーネントの使用方法の詳細は、9.13項「関連する項目のグループ化」を参照してください。

各入力コンポーネントでsimple属性をtrueに設定し、個々のラベルが表示されないようにします。ただし、メッセージ目的およびアクセシビリティ用の各コンポーネントのラベル属性に値を設定することが必要な場合があります。

ヒント:

複数のpanelLabelAndMessageコンポーネントを連続して使用する必要がある場合には、ラベルが適切に配置されるよう、af:panelFormLayoutコンポーネントにラップします。panelFormLayoutコンポーネントの使用方法の詳細は、9.7項「フォームでのコンテンツの配置」を参照してください。

panelLabelAndMessageコンポーネントを使用して、コンポーネントをグループ化してラップします。panelLabelAndMessageコンポーネントは、通常メッセージやラベルを表示するコンポーネントのみでなく、任意のコンポーネントのラップに使用できます。

19.4.1 単一のラベルおよびメッセージを使用したコンポーネントのグループ化方法

コンポーネントをグループ化し、そのグループに単一のラベルを表示するには、panelLabelAndMessageコンポーネントを使用します。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.4項「単一のラベルおよびメッセージを使用したコンポーネントのグループ化」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、19.1.2項「メッセージ・コンポーネントのその他の機能」を参照してください。

単一のラベルおよびメッセージを使用してフォーム入力コンポーネントを配置する手順:

1. 必要に応じて、入力コンポーネントまたは選択コンポーネントをページに追加します。

各入力および選択コンポーネントに次の設定を行います。

- simple属性をtrueに設定します。

- アクセシビリティの理由から、label属性をコンポーネントのラベルに設定します。

2. 「構造」ウィンドウで、手順1で作成した入力または選択のコンポーネントを選択します。選択内容を右クリックし、「囲む」→「パネル・ラベルとメッセージ」を選択します。

3. panelLabelAndMessageコンポーネントが選択されている状態で、「プロパティ」ウィンドウで次のとおりに設定します。

- label: コンポーネントのグループに表示するラベル・テキストを入力します。

- for: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、子入力コンポーネントのIDを選択します。入力コンポーネントが複数ある場合は、最初のコンポーネントを選択します。
アクセシビリティ要件に一致するように、for属性を最初のinputComponentに設定します。

ネストした入力コンポーネントの1つ以上が必須コンポーネントで、これを示すためにマーカーを表示する場合は、showRequired属性をtrueに設定します。

4. Endファセットにコンテンツを配置するには、必要なコンポーネントをファセットにドラッグ・アンド・ドロップします。
JSPまたはJSPX上のファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、子コンポーネントをコンテナ(たとえばpanelGroupLayoutまたはgroupコンポーネント)の内側にラップする必要があります。Faceletページ上のファセットには、複数のコンポーネントを配置できます。

ヒント:

ファセットがビジュアル・エディタに表示されない場合は、次のようにします。

1. 構造ウィンドウで、panelLabelAndMessageコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ラベルおよびメッセージ」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

19.5 コンポーネントへのヘルプの表示

ADF Facesには、タイプの異なる3つのヘルプを作成および表示できるフレームワークが用意されており、そのコンテンツは、コンポーネントに構成されたテキストではなく、外部ソースから取得されます。コンテンツがコンポーネントに直接構成されず、複数のコンポーネントに使用できるため、ページ作成時間の節約になり、コンテンツが表示されるすべての場所ではなく、1箇所のコンテンツを変更することも可能です。

ヘルプ・メッセージの表示形式は、説明ヘルプ、定義ヘルプおよび外部URLヘルプの3つがあります。

説明ヘルプ

説明ヘルプとは、フォーカスがコンポーネントにあるときにヘルプ・テキストをノート・ウィンドウに表示するものです。図19-26に、ノート・ウィンドウに表示されているヘルプ・メッセージを示します。

図19-26 コンポーネントの説明テキスト

通常、説明ヘルプはそのコンポーネントの使用方法を説明するために使用します。HTMLタグを使用してヘルプ・メッセージの書式を設定することもできますが、すべてのHTMLタグがサポートされているわけではありません(サポートされるHTMLタグについては、af:outputFormattedコンポーネントのタグの説明を参照してください)。図19-27に、ノート・ウィンドウに表示されているHTML書式設定されたヘルプ・メッセージを示します。

図19-27 HTML書式設定された説明ヘルプ

コンポーネントによっては、説明ヘルプがコンポーネント内の説明として表示されることがあります。説明ヘルプが表示される場所は、関連付けられているコンポーネントによって異なります。たとえば、panelHeaderコンポーネントや検索パネル・コンポーネントでは説明ヘルプがヘッダーの中に表示されます(図19-28を参照)。

図19-28 panelHeaderの説明テキスト

表19-1に、説明ヘルプがサポートされているコンポーネントを示します。

表19-1 説明ヘルプがサポートされているコンポーネント

サポートされているコンポーネント

ヘルプの位置

例

入力コンポーネント、色の選択、日付の選択、クイック問合せ

注意ウィンドウ(フォーカスがある場合のみ)

コンポーネントの選択

注意ウィンドウ(マウスが置かれている場合とフォーカスがある場合)

パネル・ヘッダー、パネル・ボックス、問合せ

ヘッダー・テキストの下のテキスト

定義ヘルプ

定義ヘルプは、メッセージ・ボックスに表示される点が標準のヒントに似ています。ただし、ユーザーがコンポーネント上にマウスを置いたときにヘルプそのものが表示されるのではなく、定義ヘルプの場合はヘルプ・アイコン(疑問符付きの青い円)が表示されます。ユーザーがこのアイコンにマウスを置くと、コンテンツが図19-29のように表示されます。

図19-29 コンポーネントの定義テキスト

ヒント・メッセージではHTMLの書式設定がサポートされないことと、ヒント・メッセージの長さは80文字未満でなければならないことに注意してください。古いバージョンのブラウザでは、長いメッセージがサポートされないことがあるからです。表19-2に、定義ヘルプがサポートされるコンポーネントを示します。

表19-2 定義ヘルプがサポートされているコンポーネント

サポートされているコンポーネント

ヘルプ・アイコンの位置

例

すべての入力コンポーネント、選択コンポーネント、色の選択、日付の選択、問合せコンポーネント

ラベルの前。ラベルが存在しない場合は、フィールドの先頭。

パネル・ヘッダー、パネル・ボックス、詳細の表示ヘッダー

ヘッダー・テキストの最後。

パネル・ウィンドウ、ダイアログ

ヘッダーの「閉じる」アイコンの隣。

表およびツリーの列

ヘッダー・テキストの下。

外部URLヘルプ

外部URLヘルプを利用すると、ヘルプのコンテンツが掲載されている既存のWebページにリンクすることができます。ヘルプ・アイコンがクリックされると、Webページが別のブラウザ・ウィンドウで開きます(図19-30を参照)。JavaScriptを使用して、任意のクライアント・ベースのイベントに基づいてヘルプ・ウィンドウを開くこともできます。

図19-30 外部URLヘルプ

JavaScriptを使用して、ヘルプ・アイコンではなく外部ヘルプを開く方法の詳細は、19.5.4項「外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法」を参照してください。

ヘルプ・プロバイダ

ヘルプ・プロバイダとは、アプリケーションのヘルプのテキスト(外部ヘルプの場合はURL)を格納するものであり、META-INF/adf-settings.xmlファイル内で登録されます。ADF Facesでは、次に示すヘルプ・プロバイダが説明ヘルプおよび定義ヘルプに対してサポートされます。

- ResourceBundleHelpProviderヘルプ・プロバイダを使用すると、ヘルプ・コンテンツを保持するリソース・バンドルを作成できます。

- ELHelpProviderヘルプ・プロバイダを使用すると、マップに変換されるXLIFFファイルを作成できます。

- ヘルプ・テキストの文字列のマップが格納されているマネージドBean。

外部URLヘルプでは、getExternalURLメソッドを実装するクラスが使用されます。

ヘルプ・プロバイダの作成の詳細は、19.5.1項「ヘルプ・プロバイダの作成方法」を参照してください。

複数のヘルプ・プロバイダの組合せを使用することや、独自のヘルプ・プロバイダ・クラスを作成することもできます。

ヘルプの作成

ヘルプ・メッセージを作成するには、次の手順を実行します。

1. 説明ヘルプおよび定義ヘルプの場合は、使用するヘルプ・プロバイダのタイプ(リソース・バンドル、XLIFFファイルまたはマネージドBean)を決定してから、必要なアーティファクトを実装します。このヘルプ・プロバイダに実際のヘルプ・テキストが格納されます。詳細は、19.5.1項「ヘルプ・プロバイダの作成方法」を参照してください。

2. 外部ヘルプの場合は、外部コンテンツへのURLが格納される外部ヘルプ・プロバイダを作成する必要があります。詳細は、19.5.1.4項「外部ヘルプ・プロバイダの作成方法」を参照してください。

3. ヘルプ・プロバイダを登録し、一意の接頭辞を指定します。この接頭辞は、このプロバイダのヘルプへのアクセスに使用されます。詳細は、19.5.2項「ヘルプ・プロバイダの登録方法」を参照してください。

4. コンポーネントのhelpTopicId属性を使用して、UIコンポーネントがプロバイダに含まれるヘルプにアクセスできるようにします。helpTopicId属性には、次の情報が格納されます。

- ヘルプ・プロバイダにより使用される接頭辞

- トピック名

詳細は、19.5.3項「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

5. 外部URLヘルプの場合は、ユーザーがヘルプ・アイコンをクリックしたときではなく、イベントへの応答としてヘルプ・ウィンドウを起動することもできます。詳細は、19.5.4項「外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法」を参照してください。

19.5.1 ヘルプ・プロバイダの作成方法

ヘルプ・プロバイダの作成手順は、作成するヘルプ・プロバイダのタイプによって異なります。説明ヘルプおよび定義ヘルプの場合は、リソース・バンドル、XLIFFファイルまたはマネージドBeanを使用できます。外部URLヘルプの場合は、Javaクラスを作成します。カスタム・ヘルプ・プロバイダを作成することもできます。

19.5.1.1 リソース・バンドル・ベースのプロバイダの作成方法

ResourceBundleHelpProviderクラスによって、基本的なHelpProviderインスタンスが作成されます。標準のリソース・バンドル・プロパティ・ファイルにヘルプ・テキストを格納し、ResourceBundleHelpProviderクラスを使用してコンテンツを送信できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

リソース・バンドルベースのヘルプを作成する手順:

1. 各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルを作成します。トピックIDには次の情報が含まれている必要があります。

- このプロバイダで使用される接頭辞(たとえばBUNDLE)。

- トピック名(たとえばPHONE_NUMBER)。

- DEFINITIONなどのヘルプ・タイプ

トピックIDは、たとえばBUNDLE_PHONE_NUMBER_DEFINITIONとなります。

複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。

例19-2に、2つのトピックIDを持つリソース・バンドルのプロパティ・ファイルの例を示します。

例19-2 リソース・バンドル・ヘルプ

BUNDLE_CUST_SERVICE_EMAIL_DEFINITION=For security reasons, we strongly discourage the submission of credit card numbers.
BUNDLE_PHONE_NUMBER_DEFINITION=We only support calling phone numbers in the United States at this time.

2. リソース・バンドルをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。詳細は、19.5.2項「ヘルプ・プロバイダの登録方法」および19.5.3項「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

19.5.1.2 XLIFFプロバイダの作成方法

XLIFF XMLファイルにヘルプ・テキストを格納し、ELHelpProviderクラスを使用してコンテンツを送信できます。このクラスでは、XLIFFファイルが、ヘルプのテキストとして使用される文字列のマップに変換されます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

XLIFFヘルプを作成する手順:

1. <body>タグ内に次の要素を使用して、ヘルプ・テキストを定義するXLIFFファイルを作成します。

- <trans-unit>: トピックIDを入力します。これには、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。たとえば、HELP_PHONE_NUMBER_DEFINITIONです。この例では、HELPがXLIFFファイルへのアクセスに使用される接頭辞となります。PHONE_NUMBERがトピック名で、DEFINITIONがヘルプのタイプです。複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。

- <source>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストを入力します。

- <target>: <trans-unit>要素の直接の子要素として作成し、空白のままにします。この要素は、変換されたヘルプ・テキストの保持に使用されます。

- <note>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストの説明を入力します。

例19-3に、2つのトピックを含むXLIFFファイルの例を示します。

例19-3 XLIFFヘルプ

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
<file source-language="en" original="this" datatype="xml">
<body>
<trans-unit id="HELP_PHONE_NUMBER_DEFINITION">
<source>Phone Number Definition</source>
<target/>
<note>
We only support calling phone numbers in the United States at this time.
</note>
</trans-unit>
<trans-unit id="HELP_CUST_SERVICE_EMAIL_INSTRUCTIONS">
<source>Customer Service Email Instructions</source>
<target/>
<note>
For security reasons, we strongly discourage the submission of credit
card numbers.
</note>
</trans-unit>
</body>
</file>
</xliff>

2. XLIFFファイルをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。詳細は、19.5.2項「ヘルプ・プロバイダの登録方法」および19.5.3項「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

19.5.1.3 マネージドBeanプロバイダの作成方法

マネージドBeanプロバイダを実装するには、マネージドBeanを作成し、ヘルプのテキストとして使用される文字列のマップをその中に格納します。マネージドBeanヘルプ・プロバイダでは、ELHelpProviderクラスを使用してヘルプが送信されます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

マネージドBeanヘルプの作成方法:

1. 文字列のマップを戻すマネージドBeanを作成しますが、例19-4に示すように、いずれもIDおよびヘルプ・トピックのコンテンツです。

例19-4 ヘルプ・テキスト文字列のマップを戻すマネージドBean

public class ELHelpProviderMapDemo
{
public ELHelpProviderMapDemo()
{
}

/* To use the ELHelpProvider, the EL expression must point to a Map, otherwise
* you will get a coerceToType error. */

public Map<String, String> getHelpMap()
{
return _HELP_MAP;
}

static private final Map<String, String> _HELP_MAP =
new HashMap<String, String>();
static
{
_HELP_MAP.put("HELP_CUST_SERVICE_EMAIL_DEFINITION", "For security reasons,
we strongly discourage the submission of credit card numbers");
_HELP_MAP.put("HELP_PHONE_NUMBER_DEFINITION", "We only support calling phone
numbers in the United States at this time");
}

}

最初の文字列には、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。たとえば、HELP_CUST_SERVICE_EMAIL_DEFINITIONです。この例では、HELPがBeanへのアクセスに使用される接頭辞となります。CUST_SERVICE_EMAILがトピック名で、DEFINITIONがヘルプのタイプです。2つ目の文字列はヘルプ・テキストです。複数のヘルプ・プロバイダを使用する場合は、必ずヘルプ・プロバイダのそれぞれに一意の接頭辞を使用してください。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。したがって、同じトピック名が2つの異なるタイプのヘルプに使用されている場合は、両方のタイプのヘルプがUIコンポーネントによって表示されます。

注意:

外部URLヘルプを使用する場合は、ELHelpProviderクラスのサブクラスを作成します。詳細は、19.5.1.4項「外部ヘルプ・プロバイダの作成方法」を参照してください。

2. マネージドBeanをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。詳細は、19.5.2項「ヘルプ・プロバイダの登録方法」および19.5.3項「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

19.5.1.4 外部URLヘルプ・プロバイダを作成する方法

外部URLをヘルプとして使用するには、getExternalURLメソッドを実装する必要があります。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

外部URLヘルプを使用するには

1. getExternalURLメソッドを実装するクラスを作成します。
リソース・バンドル・ベースのヘルプを使用する場合は、getExternalURLメソッドを実装するクラスがResourceBundleHelpProviderクラスを拡張していることを確認してください。

XLIFFベースまたはマネージドBeanベースのヘルプを使用する場合は、getExternalURLメソッドを実装するクラスがELHelpProviderクラスを拡張していることを確認してください。

例19-5に示すDemoHelpProviderクラスは、ResourceBundleHelpProviderクラスを拡張しています。

例19-5 ResourceBundleHelpProviderクラスの拡張

import javax.faces.component.UIComponent;
import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;
import oracle.adf.view.rich.help.ResourceBundleHelpProvider;

public class DemoHelpProvider extends ResourceBundleHelpProvider
{
public DemoHelpProvider()
{
}

@Override
protected String getExternalUrl(FacesContext context, UIComponent component,
String topicId)
{
if (topicId == null)
return null;

if (topicId.contains("HELP_CONTACT_URL"))
{
return "http://www.oracle.com/us/corporate/contact/index.html";
}
else
return null;

if (topicId.contains("HELP_OTN_URL") )
{
return "http://www.oracle.com/technetwork/index.html";
}
else
return null;
}
}

例19-6に示すDemoELHelpProviderクラスは、ELHelpProviderクラスを拡張しています。

例19-6 ELHelpProviderクラスの拡張

import javax.faces.component.UIComponent;
import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;
import oracle.adf.view.rich.help.ResourceBundleHelpProvider;

public class DemoELHelpProvider extends ELHelpProvider
{
public DemoELHelpProvider()
{
}

@Override
protected String getExternalUrl(FacesContext context, UIComponent component,
String topicId)
{
if (topicId == null)
return null;

if (topicId.contains("HELP_CONTACT_URL"))
{
return "http://www.oracle.com/us/corporate/contact/index.html";
}
else
return null;

if (topicId.contains("HELP_OTN_URL") )
{
return "http://www.oracle.com/technetwork/index.html";
}
else
return null;
}
}

例19-5および例19-6では、Oracleのお問合せホーム・ページを開くためにHELP_CONTACT_URLというトピックIDを使用しています。別のURLが返されるようにするには、別のif文を作成します。例19-5および例19-6では、Oracle Technology Networkのホーム・ページを開くためにHELP_OTN_URLというトピックIDを使用しています。

2. クラスをヘルプ・プロバイダとしてadf-settings.xmlファイル内で登録してから、ヘルプを使用するようにADF Facesのコンポーネントを構成します。詳細は、19.5.2項「ヘルプ・プロバイダの登録方法」および19.5.3項「UIコンポーネントからのヘルプ・コンテンツへのアクセス方法」を参照してください。

19.5.1.5 カスタムJavaクラス・ヘルプ・プロバイダの作成方法

ADF Facesヘルプ・プロバイダのいずれかを使用するかわりに、独自のプロバイダを作成します。ヘルプ・プロバイダがアクセスして表示できるファイルに実際のテキストを作成します。Javaクラス・ヘルプ・プロバイダを作成するには、HelpProviderクラスを拡張します。このクラスの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

Javaクラス・ヘルプ・プロバイダを作成する手順:

1. oracle.adf.view.rich.help.HelpProviderを拡張するJavaクラスを作成します。

2. パラメータなしでpublicコンストラクタを作成します。また、ヘルプ・トピックにアクセスして戻すロジックも実装する必要があります。
このクラスは、このプロバイダの登録時にadf-settings.xmlファイルに設定されたプロパティおよび値にアクセスできます。たとえば、すべてのADF Facesプロバイダは、あるプロパティを使用してヘルプ文字列の実際のソースを定義しています。

3. adf-settings.xmlファイル内のプロパティにアクセスするには、String型のプロパティを設定するメソッドを作成します。

次に例を示します。

public void setMyCustomProperty(String arg)

4. プロバイダを登録するには、META-INFノードからadf-settings.xmlファイルを開いて、次の要素を追加します。

- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。アプリケーション内で一意であることが必要です。

注意:

prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

- <help-provider-class>: <help-provider>要素の子要素として作成し、手順1で作成したクラスへの完全修飾クラス・パスを入力します。

- <property>: <help-provider>要素の子要素として作成し、手順3で作成したメソッドの引数として使用されるプロパティの定義に使用されます。

- <property-name>: <property>要素の子要素として作成し、プロパティ名を入力します。

- <value>: <property>要素の子要素として作成し、プロパティ値を入力します。

19.5.2 ヘルプ・プロバイダの登録方法

リソース、XLIFFおよびマネージドBeanのヘルプ・プロバイダ、および外部URLヘルプ・プロバイダの登録はadf-settings.xmlファイル内で行います。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

ヘルプ・プロバイダを登録するには:

1. 「アプリケーション」ウィンドウのMETA-INFノードからadf-settings.xmlファイルを開きます。

2. 「ソース」タブをクリックし、次の要素を追加します。

- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。アプリケーション内で一意であることが必要です。

注意:

prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。

- <help-provider-class>: <help-provider>要素の子要素として作成します。

- リソース・バンドルを使用する場合は、値をoracle.adf.view.rich.help.ResourceBundleHelpProviderと入力します。

- XLIFFファイルを使用する場合は、値をoracle.adf.view.rich.help.ELHelpProviderと入力します。

- マネージドBeanまたは外部URLのプロバイダを使用する場合は、完全修飾クラス・パスを入力します。

注意:

外部URLヘルプの場合は、プロバイダが拡張したクラスがプロバイダ・クラスに反映されている必要があります。

- <property>: <help-provider>要素の子要素として作成します。プロパティは、実際のヘルプ・ソースを定義します。

- <property-name>: <property>要素の子要素として作成し、ソースの名前を入力します。

- <value>: <property>要素の子要素として作成し、ヘルパーの完全修飾クラス名を入力します。たとえば、ADF Facesデモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResourcesです。

- リソース・バンドルを使用する場合は、リソース・バンドルの完全修飾クラス名を入力します。たとえば、ADF Facesデモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResourcesです。

- XLIFFファイルを使用する場合は、解決結果がXLIFFファイルとなるEL式を入力し、adfBundle EL関数の中にラップします。たとえば、#{adfBundle['project1xliff.view.Project1XliffBundle']}です。

- マネージドBeanを使用する場合は、解決結果がマネージドBean上のヘルプ・マップとなるEL式を入力します。

- 外部URLヘルプを使用する場合は、作成したプロバイダ・クラスの完全修飾クラス名を入力します。

例19-7に、adf-settings.xmlファイル内で登録されているリソース・バンドルを示します。

例19-7 ヘルプ・プロバイダとしてのリソース・バンドルの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="HELP_">
<help-provider-class>
oracle.adf.view.rich.help.ResourceBundleHelpProvider
</help-provider-class>
<property>
<property-name>baseName</property-name>
<value>oracle.adfdemo.view.resource.fileExplorer.helpStrings</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

例19-8に、adf-settings.xmlファイル内で登録されているXLIFFファイルを示します。

例19-8 ヘルプ・プロバイダとしてのXLIFFファイルの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="HELP">
<help-provider-class>
oracle.adf.view.rich.help.ELHelpProvider
</help-provider-class>
<property>
<property-name>helpSource</property-name>
<value>#{adfBundle['project1xliff.view.Project1XliffBundle']}</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

例19-9に、adf-settings.xmlファイル内で登録されているBeanを示します。

例19-9 ヘルプ・プロバイダとしてのマネージドBeanの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="HELP_">
<help-provider-class>
oracle.adf.view.rich.help.ELHelpProvider
</help-provider-class>
<property>
<property-name>helpSource</property-name>
<value>#{helpTranslationMap.helpMap}</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

例19-10に、adf-settings.xmlファイル内で登録されている外部ヘルプ・プロバイダを示します。

例19-10 外部URLヘルプ・プロバイダの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="HELP_">
<help-provider-class>
oracle.adf.view.rich.help.ResourceBundleHelpProvider
</help-provider-class>
<property>
<property-name>baseName</property-name>
<value>oracle.adfdemo.view.resource.DemoHelp</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

例19-11に、adf-settings.xmlファイル内1で登録されているカスタム・ヘルプ・プロバイダ・クラスの例を示します。

例19-11 ヘルプ・プロバイダ・クラスの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="MYAPP">
<help-provider-class>
oracle.adfdemo.view.webapp.MyHelpProvider
</help-provider-class>
<property>
<property-name>myCustomProperty</property-name>
<value>someValue</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

19.5.3 UIコンポーネントからのヘルプ・コンテンツへのアクセス方法

コンポーネントのHelpTopicId属性を使用して、ヘルプへのアクセスおよび表示を行います。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

コンポーネントからヘルプにアクセスする手順:

1. 構造ウィンドウで、ヘルプを追加するコンポーネントを選択します。ヘルプがサポートされているコンポーネントのリストは、表19-1および表19-2を参照してください。

2. 「プロパティ」ウィンドウの「外観」セクションを開き、helpTopicId属性の値を入力します。
定義ヘルプおよび説明ヘルプの場合は、この値に、正しいヘルプ・プロバイダにアクセスするための接頭辞とトピック名が含まれている必要があります。ヘルプ・タイプが含まれていてはなりません。その名前で登録されているすべてのヘルプ・タイプが返されて表示されるからです。

次に例を示します。

<af:inputText label="Customer Service E-Mail" helpTopicId="HELP_CUST_SERVICE_EMAIL"/>

この例では、例19-3のXLIFFファイルに定義されている定義ヘルプと説明ヘルプの両方が戻されます。

3. ヘルプがサポートされていないコンポーネントにヘルプを表示する場合は、outputTextコンポーネントを追加してヘルプ・テキストを表示し、次のようにして、そのコンポーネントをヘルプ・プロバイダにバインドできます。

<af:outputFormatted
value="#{adfFacesContext.helpProvider['HELP_CUST_SERVICE_  EMAIL'].instructions}"/>

これは、説明ヘルプ・テキストにアクセスします。

19.5.4 外部ヘルプ・ウィンドウを起動するためのJavaScriptの使用方法

外部URLヘルプを使用する場合は、デフォルトではユーザーがヘルプ・アイコンをクリックしたときにヘルプ・ウィンドウが起動されます。かわりに、特定のコンポーネントのイベントにJavaScriptとクライアント・イベント・リスナーを使用して、ヘルプ・ウィンドウを起動できます。

始める前に:

属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、19.5項「コンポーネントへのヘルプの表示」を参照してください。

JavaScriptを使用して外部ヘルプ・ウィンドウを起動する手順:

1. 特定のURLまたはページの起動に、launchHelp APIを使用するJavaScript関数を作成します。

例19-12に、helpClient.jspxの起動に使用されるlaunchHelp関数を示します。

例19-12 外部ヘルプ・ページを起動するためのJavaScript

<af:resource type="javascript">
function launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>

2. ADF Facesページで、launchHelp関数を呼び出すクライアント・イベントを持つコンポーネントをドラッグ・アンド・ドロップします。このコンポーネントのclientIdをtrueに設定する必要があります。

3. 「コンポーネント」ウィンドウの「操作」パネルから「クライアント・リスナー」を、手順2で作成したコンポーネントに子としてドラッグ・アンド・ドロップします。手順1で作成した関数を起動するclientListenerを構成します。clientListenerタグの使用方法の詳細は、4.4項「クライアント・イベントのリスニング」を参照してください。
例19-13に示すコードは、helpClient.jspxページを起動するためにbuttonコンポーネントのclickイベントを割り当てるのに使用されるものです。

例19-13 外部ヘルプ・ウィンドウの起動に使用されるページ・コード

<af:toolbar id="tb1">
<af:button text="Launch help window" id="ctb1"
icon="/images/happy_computer.gif">
<af:clientListener method="launchHelp" type="click"/>
</af:button>
</af:toolbar>
<af:resource type="javascript">
function launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>

19.6 複数のメッセージ・タイプの組合せ

検証および変換に関するメッセージを表示する入力コンポーネントにヘルプ・メッセージを追加すると、ADF Facesにより、注意ウィンドウ内に次の順序でメッセージが表示されます。

1. 検証および変換のエラー・メッセージ。

2. 検証および変換のヒント。

3. 入力および選択コンポーネントの場合のみ、説明ヘルプ。panelHeaderコンポーネントの場合、説明ヘルプは常にヘッダーの下に表示されます。

4. shortDesc属性の値。

図19-31に、コンバータ、説明ヘルプおよびヒント・メッセージを含むinputDateコンポーネントを示します。

図19-31 一度に表示されている異なるメッセージ・タイプ

20 ナビゲーション・コンポーネントの使用

この章では、ADF Facesのナビゲーション・コンポーネントを使用してWebユーザー・インタフェースをナビゲーション可能にする方法を説明します。ページ階層の作成方法に加えて、ボタンやリンクを使用してナビゲートや機能の呼出しを行う方法についても説明します。この章では、trainコンポーネントを使用してマルチステップ・プロセスの中をナビゲートする方法についても説明します。

この章では、次の項目について説明します。

- 20.1項「ナビゲーション・コンポーネントについて」

- 20.2項「ナビゲーション・コンポーネントの共通機能」

- 20.3項「ボタンおよびリンクのナビゲーション目的での使用」

- 20.4項「リンクに対するブラウザのコンテキスト・メニューの構成」

- 20.5項「ボタンまたはリンクの機能の呼出し目的での使用」

- 20.6項「ページ階層用のナビゲーション・アイテムの使用」

- 20.7項「メニュー・モデルを使用したページ階層の作成」

- 20.8項「単純なナビゲーション階層の作成」

- 20.9項「trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成」

20.1項 ナビゲーション・コンポーネントについて

ナビゲーション・コンポーネントを使用すると、より詳細な情報のドリルダウン、関連ページまたはウィンドウへの移動、およびデータへの特定アクションの実行と同時のナビゲーションが可能になります。ナビゲーション・コンポーネントの一般的な形式はボタンやリンクで、その多くはそれのみで使用できますが、その他のコンポーネントと組み合せないと使用できないものもあります。

一部のコンポーネントは、階層ページをナビゲートし、ページ階層内でのユーザーの現在の場所を追跡するためのタブやブレッドクラムなどの項目をレンダリングします。リンクとボタンをレンダリングするコンポーネントは2つあり、特に、ユーザーに順を追ってマルチステップ・タスクを説明するために使用します。また、buttonコンポーネントやlinkコンポーネントを使用して、部分ページ・リクエストを起動することや、ポップアップ・ダイアログおよびセカンダリ・ウィンドウを実装することもできます(ADF Facesのその他のタグやコンポーネントと組み合せます)。ナビゲーション・コンポーネントは、サーバー側のアクション付きで作成することも、アクションなしで作成することもできます。

図20-1に、ナビゲーションの提供に使用される様々なADF Facesコンポーネントを示します。

図20-1 ADF Facesナビゲーション・コンポーネント

20.1.1 ナビゲーション・コンポーネントのユースケースおよび例

ナビゲーション・コンポーネントの一般的な用途は、別のページやウィンドウにナビゲートする、データに対するアクションを実行する、またはアクションとナビゲートを同時に実行するためのボタンやリンクを作成することです。たとえば、図20-2に示すFile Explorerアプリケーションのメイン・ページにあるbuttonコンポーネントは、スキンの選択後にクリックするとページの表示が更新されるようになっており、linkコンポーネントをクリックするとポップアップ・ウィンドウが開きます。

図20-2 File Explorerアプリケーションのメイン・ページ

File Explorerアプリケーションの上部右端には、4つのグローバル・アプリケーション・リンクがあります。linkコンポーネントを使用すればリンク先にナビゲートできますが、このFile Explorerアプリケーションでは、navigationPaneコンポーネントと子のcommandNavigationItemコンポーネントを使用してリンクを表示しています。これらのリンクは、別の場所に直接ナビゲートするか、ナビゲートの結果としてアクションを実行するようになっています。

また、navigationPaneコンポーネントは、アプリケーション・コンテンツを意味のある構造に編成することが可能で、ユーザーが様々な機能を実行するために、アプリケーションのあらゆるコンテンツ領域内を移動するためのナビゲーション方法も提供します。たとえば、シンプルなHRアプリケーションには、図20-3に示すように、従業員が会社の給付金を確認できるページや、従業員データを表示および作成する管理ページがあります。navigationPaneコンポーネントは、タブ、バー、リストなどを含む構造を表示し、子のcommandNavigationItemコンポーネントはナビゲーション・リンクを表示します。

図20-3 ナビゲーション・タブ、バー、およびリストのリンクが表示されたページ

navigationPaneコンポーネントも、コンポーネントがメニュー・モデル・マネージドBeanにバインドされるメニュー・モデルとともに使用できます。フレームワークにより、各ページの構造に適切な数のナビゲーション・アイテムが生成され、選択対象として表示されるアイテムも追跡されるため、複雑なページ階層の場合は、メニュー・モデルを使用するとより効果的です。

menuBarコンポーネントもメニュー・モデルにバインドし、ページ階層内の様々なレベルをナビゲートするためのメニューやサブメニューを実装できます。Webのショッピング・サイトのほとんどは、体系的なメニューを使用してショッピング領域を分類し、1クリックで階層内の特定のサブカテゴリまたは商品に移動できるようになっています。図20-4に示すように、メニュー・バーにメニュー項目の最初のレベルが一目でわかるように表示されています。メニューの上にマウス・カーソルを置くと、参照および選択するより多くのアイテムのサブメニューがユーザーに表示されます。一般的に、3レベルを超えるメニュー項目は実装しません。

図20-4 3つのメニューが1つのバーにあり、サブメニューが展開されている状態のページ

ページ階層の作成にnavigationPaneとmenuBar (メニュー・モデルにバインド)のどちらを使用するかに関係なく、breadCrumbsコンポーネントと一連の子のcommandNavigationItemコンポーネントを使用して、ページ階層内でのユーザーの現在の場所を視覚的に示すことができます。図20-5に示すように、breadCrumbsコンポーネントには、ルート・ページから始まり現在のページ(常に最後のリンク)までの一行のテキスト・リンクが表示されます。メニュー・モデルを使用してページ階層を作成した場合、breadCrumbsコンポーネントを同じメニュー・モデル・マネージドBeanにバインドし、フレームワークによりリンクが動的に生成されるようにすることが可能です。

図20-5 横方向のブレッドクラム・リンクが表示されたページ

trainコンポーネントを使用すると、ユーザーは、マルチステップ・プロセスのどの段階であるかを簡単に確認し、そのプロセス全体をナビゲートすることもできるようになります。図20-6に示すように、trainButtonBarコンポーネントは、「Back」および「Next」ボタンの形式で、trainプロセスに追加のナビゲーションを提供します。

図20-6 ADF FacesのtrainおよびtrainButtonBarのデモ・ページ

20.1.2 ナビゲーション・コンポーネントのその他の機能

ナビゲーション・コンポーネントを実装する前に、ADF Facesのその他の機能を理解しておくと役に立ちます。また、ページにこれらのコンポーネントを追加してから、アクセシビリティやローカライゼーションなどの機能の追加が必要なことに気が付く場合もあります。次に、ナビゲーション・コンポーネントで使用できるその他の機能へのリンクを示します。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- イベント: コンポーネントはサーバー側とクライアント側両方のイベントを起動します。アプリケーションでは、これらへの応答としてなんらかのロジックを実行できます。詳細は、第6章「イベントの処理」を参照してください。

- 部分ページ・レンダリング: ADF Facesのナビゲーション・コンポーネントを使用して、ページ上のコンポーネントの部分レンダリングをトリガーできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- アクセシビリティ: ナビゲーション・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- ローカライゼーション: ラベルに直接テキストを入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、テキスト文字列の翻訳を管理できます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- スキン: スキンを変更することで、ナビゲーション・コンポーネントのルック・アンド・フィールドを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

20.2 ナビゲーション・コンポーネントの共通機能

JSFアプリケーション同様、ADF Facesコンポーネントを使用するアプリケーションには、(それのみ、またはその他のナビゲーション・コンポーネント内で使用される)ボタンやリンクがクリックされた場合に、次に表示するページを選択する一連のルールがあります。ルールは、アプリケーションの構成リソース・ファイル(faces-config.xml)にJSFナビゲーション・ルールおよびケースを追加することで定義します。

JSFでは、結果の文字列は、ページ・ナビゲーションの実行に使用するナビゲーション・ルールの選択に使用されます。javax.faces.component.ActionSourceインタフェースを実装するADF Facesのナビゲーション・コンポーネントでは、ユーザーがコンポーネントをアクティブ化するとActionEventイベントが生成されます。JSF NavigationHandlerおよびデフォルトのActionListenerメカニズムでは、アクティブ化されたコンポーネントの結果文字列を使用して、一連のナビゲーション・ルールで一致するものが検出されます。JSFで一致が検出されると、対応するページが選択され、レスポンスのレンダリング・フェーズで選択したページがレンダリングされます。JSFライフサイクルの詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。また、ADF Facesアプリケーションでのナビゲーションでは部分ページ・レンダリングも使用できます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

20.3 ボタンおよびリンクのナビゲーション目的での使用

ADF Facesにはbuttonコンポーネントとlinkコンポーネントがあり、これらをナビゲーションに使用できます。実際のユースケースに応じて、別の場所に直接ナビゲートする、リクエストを送信する、およびActionEventイベントを起動するように、これらのコンポーネントを構成できます。

buttonコンポーネントとlinkコンポーネントに加えて、ADF Facesにはメニュー内部で使用するための特殊なコンポーネントもあります(goMenuItemとcommandMenuItem)。詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

buttonコンポーネントとlinkコンポーネントではイメージをレンダリングでき、さらにテキストを表示することもできます(図20-7および図20-8を参照)。iconPosition属性に値を設定することで、オプションのテキストに対するイメージの位置を決定できます。また、ユーザーがアイコンにカーソルを置いた場合、またはアイコンが押された場合や無効化された場合のために、別々のアイコンを設定できます。使用するイメージを指定するには、icon属性の値を設定します。buttonコンポーネントとlinkコンポーネントは、コンポーネント内にレンダリングするよう指定されたイメージを収容するのに必要なピクセル数まで拡張します。イメージが指定されていない場合は、Webアプリケーションのスキン内でそのコンポーネントに対して指定された最小サイズを使用してコンポーネントがレンダリングされます。

図20-7に、buttonコンポーネントに対して構成可能な様々なオプションを示します。

図20-7 ADF Facesのbuttonコンポーネント

図20-8に、linkコンポーネントに対して構成可能な様々なオプションを示します。

図20-8 ADF Facesのlinkコンポーネント

ADF Facesのtoolbarコンポーネントを使用すると、さらに機能を追加できます。たとえば、popupファセットを使用して、buttonコンポーネントからポップアップ・メニューを開きます。詳細は、16.3項「ツールバーの使用方法」を参照してください。

buttonコンポーネントおよびlinkコンポーネントの動作は、印刷または電子メール用にページを簡略化モードで出力するときは異なります。linkコンポーネントは印刷や電子メールのモードでも表示されますが、リンクは機能しません。buttonコンポーネントは、印刷または電子メールのための簡略化モードでページを出力するときはレンダリングされません。電子メールおよび印刷の出力モードの詳細は、第37章「異なる出力モードの使用方法」を参照してください。

リンクをレンダリングするアクション・コンポーネントが右クリックされたときにブラウザのコンテキスト・メニューを起動できるように、アプリケーションを構成できます。アクション・コンポーネントによってレンダリングされたリンクを右クリックしたエンド・ユーザーがブラウザのコンテキスト・メニューを使用して実行するアクションは、開発者の観点からは実行してほしくないものである可能性があります(たとえば、リンクを新しいウィンドウで開く)。詳細は、20.4項「リンクに対するブラウザのコンテキスト・メニューの構成」を参照してください。

エンド・ユーザーがページから移動しようとしたが、そのページでのデータがまだコミットされていない場合に、警告メッセージを表示することができます。checkUncommittedDataBehaviorコンポーネントを、immediate属性がtrueに設定されているアクション・コンポーネントに子として追加します。ユーザーがナビゲートしないことを選択すると、子イベントは取り消されます。checkUncommittedDataBehaviorコンポーネントを、af:buttonコンポーネントやaf:linkコンポーネントに子として追加できます。エンド・ユーザーに警告メッセージを表示するには、9.2.5項「documentタグの構成方法」で説明されているように、ページにコミットされていないデータが含まれていて、documentタグのuncommittedDataWarning属性がonに設定されている必要があります。

注意:

コミットされていないデータについて別の方法で警告メッセージを表示するには、documentタグのuncommittedDataWarningタグをonに設定して、ページでADF Controllerバインド・タスク・フローをレンダリングします。このタスク・フローを、criticalとして構成しておきます。『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の暗黙的セーブポイントの有効化方法に関する項を参照してください。

20.3.1 ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法

一般的に、buttonやlinkのようなアクション・コンポーネントは、ページ・ナビゲーションを実行するため、およびサーバー側処理を実行するために使用します。

始める前に:

アクション・コンポーネントの属性が機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

アクション・コンポーネントを作成して使用する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、使用するアクション・コンポーネントをJSFページにドラッグ・アンド・ドロップします。具体的には、次のいずれかをドラッグ・アンド・ドロップします。

- ボタン: buttonコンポーネントを作成する場合。

- リンク: linkコンポーネントを作成する場合。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次のとおりに設定します。

- テキスト: 表示するテキストを指定します。

ヒント:

かわりに、textAndAccessKey属性を使用して、ボタンまたはリンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、33.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

- Icon: イメージ・ファイルのURIに設定します(コンポーネントの内側にアイコンをレンダリングする場合)。アイコンをレンダリングする場合は、「外観」セクションのhoverIcon、disabledIcon、depressedIconおよびiconPositionの値も設定します。

ヒント:

text属性(またはtextAndAccessKey属性)かicon属性、あるいはその両方を使用できます。

- IconPosition: アイコンを指定した場合は、テキストを基準としてアイコンの位置を指定できます。指定するには、ドロップダウン・リストから値を選択します。

- <default> (leading): アイコンをテキストの前にレンダリングします。

- trailing: アイコンをテキストの後にレンダリングします。

- top: アイコンをテキストの上にレンダリングします。

- bottom: アイコンをテキストの下にレンダリングします。

- 選択済: trueに設定すると、ページがレンダリングされたときにこのコンポーネントは選択された状態で表示されます。

- アクション: 結果文字列に設定するか、メソッド式に設定します。この式で参照するバッキングBeanアクション・メソッドから、論理結果のStringが返されるようにしてください。ページ間のナビゲーションを構成する方法の詳細は、3.3項「ページ・フローの定義」を参照してください。
デフォルトのJSF ActionListenerメカニズムでは、結果の文字列を使用して適切なJSFナビゲーション・ルールが選択され、レスポンスのレンダリング・フェーズに使用するページがJSF NavigationHandlerに通知されます。マネージドBeanメソッドを使用してダイアログを開く方法の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。JSFアプリケーションでの結果文字列およびナビゲーションの詳細は、Java EE 6のチュートリアル(http://docs.oracle.com/javaee/index.html)を参照してください。

ヒント:

結果を返すハンドラにバインドされている場合は、ナビゲーションにactionListener属性を使用することもできます。通常、この属性はナビゲーションではなく、ユーザー・インタフェース・ロジックの処理にのみ使用する必要があります。

たとえば、File Explorerアプリケーションの「検索」パネルの「検索」ボタンにはナビゲート先はありません。かわりに、検索が実行されます。actionListener属性には、次の値が指定されています。

actionListener="#{explorer.navigatorManager.searchNavigator.
searchForFileItem}"

この式は、実際に検索を実行するメソッドに評価されます。

3. 「動作」セクションを開き、次の設定を行います。

- Disabled: ドロップダウン・リストからtrueを選択すると、コンポーネントは非対話型のボタンまたはリンクとして表示されます。

- PartialSubmit: ドロップダウン・リストからtrueを選択すると、コンポーネントがアクティブ化されるたびに部分ページ要求が発行されます。詳細は、8.2項「部分トリガーの使用」を参照してください。

- Immediate: ドロップダウン・リストからtrueを選択すると、処理の検証とモデル更新のフェーズはスキップされます。コンポーネントのアクション・リスナー(存在する場合)およびデフォルトのJSF ActionListenerハンドラは、JSFライフサイクルのリクエスト値の適用フェーズの最後に実行されます。詳細は、5.2項「immediate属性の使用」を参照してください。

4. immediate属性をtrueに設定した場合は(手順3を参照)、af:checkUncommittedDataBehaviorコンポーネントをアクション・コンポーネントに子として追加すると、ページ上のデータがコミットされていないときにユーザーへの警告メッセージを表示できます。「コンポーネント」ウィンドウの「操作」パネルで、「動作」グループから「未コミット・データの確認動作」をドラッグし、手順1で追加したアクション・コンポーネントの子としてドロップします。

注意:

9.2.5項「documentタグの構成方法」で説明されているように、documentタグのuncommittedDataWarning属性をonに設定しておく必要もあります。

ボタンやリンクを使用してセカンダリ・ウィンドウを開くこともできます。それには、属性useWindow、windowHeight、windowWidth、launchListenerおよびreturnListenerを使用します。セカンダリ・ウィンドウを開く方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のADF Facesのダイアログ・フレームワークをバインド・タスク・フローのかわりに使用する方法に関する項を参照してください。

ボタンやリンクを使用して、JavaScriptコードを書かずにポップアップを起動する方法は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

20.3.2 ボタンおよびリンクをActionEventの配信なしでナビゲーションに使用する方法

buttonコンポーネントやlinkコンポーネントを使用して、ActionEventイベントを配信せずに直接ページ・ナビゲーションを実行することができます。

始める前に:

buttonコンポーネントおよびlinkコンポーネントの属性が機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

ActionEventを配信せずにナビゲートするボタンおよびリンクを作成する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルから、使用するコンポーネントをJSFページにドラッグ・アンド・ドロップします。具体的には、次のいずれかをドラッグ・アンド・ドロップします。

- ボタン: buttonコンポーネントを作成する場合。

- リンク: linkコンポーネントを作成する場合。

2. 「プロパティ」ウィンドウの「共通」セクションを開いて、次のとおりに設定します。

- テキスト: 表示するテキストを指定します。

ヒント:

かわりに、textAndAccessKey属性を使用して、ボタンまたはリンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、33.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

- Icon: イメージ・ファイルのURIに設定します(コンポーネントの内側にアイコンをレンダリングする場合)。アイコンをレンダリングする場合は、「外観」セクションのhoverIcon、disabledIcon、depressedIconおよびiconPositionの値も設定します。

ヒント:

text属性(またはtextAndAccessKey属性)かicon属性、あるいはその両方を使用できます。

- IconPosition: アイコンを指定した場合は、テキストを基準としてアイコンの位置を指定できます。指定するには、ドロップダウン・リストから値を選択します。

- <default> (leading): アイコンをテキストの前にレンダリングします。

- trailing: アイコンをテキストの後にレンダリングします。

- top: アイコンをテキストの上にレンダリングします。

- bottom: アイコンをテキストの下にレンダリングします。

- 選択済: trueに設定すると、ページがレンダリングされたときにこのコンポーネントは選択された状態で表示されます。

- 宛先: ナビゲート先のページのURIに設定します。
たとえば、OracleのWebサイトにナビゲートするには次のとおりに設定します。

destination="http://www.oracle.com"

- TargetFrame: 新しいページを表示する場所を指定する値を、ドロップダウン・リストから選択します。

- _blank: リンクにより、ドキュメントは新しいウィンドウに開かれます。

- _parent: リンクにより、ドキュメントは親ウィンドウに開かれます。たとえば、リンクがダイアログに表示された場合、結果のページは親ウィンドウにレンダリングされます。

- _self: リンクにより、ドキュメントは同じページまたはリージョンに開かれます。

- _top: リンクにより、ページ全体が置き換えられて、ドキュメントはウィンドウ全体に開かれます。

3. 「動作」セクションを開いて「Disabled」ドロップダウン・リストからtrueを選択すると、コンポーネントは非対話型のボタンまたはリンクとして表示されます。

20.3.3 部分ページ・ナビゲーションの使用に関する必知事項

8.5項「部分ページ・ナビゲーションの使用について」で説明されているように、部分ページ・レンダリング・リクエストを使用してナビゲーションがトリガーされるように、ADF Facesアプリケーションを構成できます。部分ページ・ナビゲーションが有効化されていると、次のコンポーネントで、GETリクエストの部分ページ・ナビゲーションが自動的にサポートされます。

- af:button

- af:link

- af:goMenuItem (af:menuおよびaf:menuBar内で使用)

- af:commandNavigationItem (af:navigationPane内で使用)

唯一の要件は、サポートされているコンポーネントのdestination属性の値が、アプリケーション・コンテキスト・ルートの相対URLであり、/で始まっていることです。たとえば/faces/myPage.jsfで、facesはweb.xml内で定義されているアプリケーションのサーブレットにマッピングされているURL、myPage.jsfはナビゲート先のページです。部分ページ・ナビゲーションでURLのハッシュ(#)部分が使用されるため、ページ内のアンカーへのナビゲーションにはハッシュ部分を使用できません。

サポートされているコンポーネントのtargetFrame属性が、新しいウィンドウでリンクを開くように設定されている場合、フレームワークは自動的にページ全体のナビゲーションに戻ります。

20.4 リンクに対するブラウザのコンテキスト・メニューの構成

実行時にリンクをレンダリングするアクション・コンポーネントを使用して、エンド・ユーザーにアクションを起動させることができます。さらに、ADF Facesフレームワークで、そのアクション・コンポーネントのコンテキスト・メニューがエンド・ユーザーのブラウザにレンダリングされるように、アプリケーションを構成することもできます。デフォルトでは、ADF Facesフレームワークではこのコンテキスト・メニューは無効化されます。destination属性の値が設定されていないときに、ADF Facesフレームワークによってこのコンテキスト・メニューが無効化されるのは、アクション・コンポーネントで指定されたものとは異なるアクションがコンテキスト・メニューのメニュー・オプションによって起動される可能性があるからです(たとえば、リンクを新しいウィンドウで開く)。この動作を構成できるコンポーネントは次のとおりです。

- af:link

- af:commandMenuItem (af:menuBarコンポーネント内で使用)

- af:commandNavigationItem (destination属性に値が指定されていない場合、ADF Facesフレームワークにより、次のシナリオでブラウザのコンテキスト・メニューが有効化されます)

- af:trainコンポーネント内で、af:commandNavigationItemによってレンダリングされる2つのアンカーの場合

- af:breadCrumbsコンポーネント内で、af:commandNavigationItemによってレンダリングされる場合

- af:navigationPaneコンポーネント(タブ、バー、ボタン、選択、リストなど、任意のヒント)内で、af:commandNavigationItemによってレンダリングされる場合

- af:panelTabbed: タブおよびオーバーフロー・インジケータ

- af:panelAccordion: 公開リンクおよびオーバーフロー・インジケータ

移動先を指定し、アクションを起動しないコンポーネントには、この動作を構成できません。たとえば、af:commandNavigationItemコンポーネントのdestination属性に値を指定し、action属性には指定しない場合です。

20.4.1 コマンド・リンクへのブラウザ・コンテキスト・メニューの構成方法

アプリケーションのweb.xmlファイルにあるoracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONコンテキスト・パラメータの値をnoに設定します。

始める前に:

どのアクション・コンポーネントに対してこの機能を構成できるかを理解していると役に立ちます。詳細は、20.4項「リンクに対するブラウザのコンテキスト・メニューの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

コマンド・リンクにブラウザ・コンテキスト・メニューを構成する手順:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを開いてweb.xmlをダブルクリックします。

2. 概要エディタで、「アプリケーション」ナビゲーション・タブをクリックしてから、「コンテキスト初期化パラメータ」表の横にある「追加」アイコンをクリックしてoracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONパラメータのエントリを追加し、このパラメータをnoに設定します。

3. 変更を保存して、web.xmlファイルを閉じます。

20.4.2 コマンド・リンクにブラウザのコンテキスト・メニューを構成する場合の処理

20.4.1項「コマンド・リンクへのブラウザのコンテキスト・メニューの構成方法」に説明されている手順に従った場合、例20-1に示すように、JDeveloperにより、web.xmlファイルに値が記述されます。

例20-1 ブラウザのコンテキスト・メニューを構成するためのコンテキスト・パラメータ

<context-param>
<param-name>oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSION</param-name>
<param-value>no</param-value>
</context-param>

アプリケーションのweb.xmlファイルにおけるADF Facesの構成オプションの詳細は、A.2項「web.xmlでの構成」を参照してください。

実行時に、エンド・ユーザーは、特定のコンポーネントによってレンダリングされたリンクを右クリックすると、ブラウザのコンテキスト・メニューを起動できます(20.4項「リンクに対するブラウザのコンテキスト・メニューの構成」を参照)。

20.5 ボタンまたはリンクの機能の呼出し目的での使用

アクション・コンポーネントをナビゲーションに使用する機能に加えて、ADF Facesはリスナー・タグも備えており、アクション・コンポーネントとともに使用してアクション・イベントの起動時に特定の機能を実行することができます。次に、ADF Facesに含まれるリスナー・タグを示します。

- exportCollectionActionListener: table、treeおよびtreeTableコンポーネントから、Excelスプレッドシートにデータをエクスポートするために使用します。詳細は、12.12項「表、ツリーまたはツリー表からのデータのエクスポート」を参照してください。

- fileDownloadActionListener: サーバーからローカル・ハード・ドライブへのファイルのダウンロードを開始するために使用します。詳細は、20.5.1項「ファイルをダウンロードするためのアクション・コンポーネントの使用方法」を参照してください。

- resetListener: 送信した値をリセットするために使用します。ただし、データ・モデルの状態は変更されません。詳細は、20.5.2項「入力フィールドをリセットするためのアクション・コンポーネントの使用方法」を参照してください。入力コンポーネントがポップアップ内にレンダリングされる場合は、15.7項「ポップアップの入力フィールドのリセット」を参照してください。
入力コンポーネントを以前の状態、つまりサーバーへの部分的または完全な送信が成功している状態にリセットする場合は、「リセット」ボタンを使用できます。詳細は、11.2.3項「フォームをリセットするためのボタンの追加方法」を参照してください。

20.5.1 ファイルをダウンロードするためのアクション・コンポーネントの使用方法

ユーザーがファイルをダウンロードできるようにするには、ボタンなどのアクション・コンポーネントを作成し、fileDownloadActionListenerタグに関連付けます。ユーザーがそのコンポーネントを選択またはクリックすると、ポップアップ・ダイアログが表示され、ここでユーザーがダウンロードの様々なオプションを選択できます(図20-9を参照)。

図20-9 ファイルのダウンロード・ダイアログ

fileDownloadActionListenerタグを使用すると、アクション・コンポーネント(たとえば、ボタン、リンク、メニュー項目)からエンド・ユーザーにファイルの内容を送信できるようになります。このタグを使用すると、コンテンツ・タイプまたはファイル名を指定することもできます。fileDownloadActionListenerタグを使用すると、アクション・コンポーネントのpartialSubmit属性に設定した値は、レンダリング時に無視されます。fileDownloadActionListenerタグは、コンテキストに基づいて、アクション・コンポーネントが起動する送信のタイプを決定します。アプリケーションのJSFポートレット内でfileDownloadActionListenerタグを使用すると、アクション・コンポーネントにより部分送信(partialSubmit="true")が起動されます。ADF Facesサーブレットを使用するアプリケーション内にfileDownloadActionListenerタグを使用すると、アクション・コンポーネントにより完全送信(partialSubmit="false")が起動されます。

ヒント:

ファイルをサーバーにアップロードする方法の詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。

コンテンツがブラウザに送信された後、そのコンテンツが表示または保存される方法は、エンド・ユーザーがダイアログで選択したオプションにより異なります。エンド・ユーザーが「次で開く」オプションを選択した場合、そのファイル・タイプに関連付けられているアプリケーションが起動されてコンテンツが表示されます。たとえば、テキスト・ファイルの場合はメモ帳アプリケーションが起動されます。エンド・ユーザーがディスクに保存オプションを選択した場合は、ブラウザによっては、ファイル名およびコンテンツを格納する場所を選択するためのポップアップ・ダイアログが表示されます。

例20-2に示すボタンのタグでは、fileDownloadActionListenerタグを使用して、hello.txtという名前のファイルをユーザーにダウンロードします。

例20-2 ボタンおよびfileDownloadActionListenerタグを使用したファイルのダウンロード

<af:button value="Say Hello">
<af:fileDownloadActionListener filename="hello.txt"
contentType="text/plain; charset=utf-8"
method="#{bean.sayHello}"/>
</af:button>

例20-3に、ファイルのダウンロード処理に使用されるマネージドBeanメソッドを示します。

例20-3 ファイルのダウンロード処理に使用されるマネージドBeanメソッド

public void sayHello(FacesContext context, OutputStream out) throws IOException{
OutputStreamWriter w = new OutputStreamWriter(out, "UTF-8");
w.write("Hi there!");
. . .
}

アプリケーションのJSFポートレット内からfileDownloadActionListenerタグを使用すると、表20-1に説明されているパラメータを、アプリケーションのweb.xmlファイルにオプションで追加し、ファイルのサイズや一時的な場所のオプションをダウンロード中に構成できます。

表20-1 ポートレット内にfileDownloadActionListenerを使用するためにweb.xmlファイルに追加するパラメータ

パラメータ名

データ型

説明

oracle.adf.view.rich.portal.FILE_DOWNLOAD_MAX_MEM

Integer

セッション中にfileDownloadActionListenerタグが格納できるファイルの最大サイズをKB単位で指定します。ファイルが指定した最大サイズを超えると、アプリケーションにより、FILE_DOWNLOAD_TEMP_DIRに指定された場所にあるハード・ドライブへのファイルの保存が試行されます。

web.xmlファイルのこのパラメータに値を指定しない場合は、デフォルトで100KBに設定されます。

oracle.adf.view.rich.portal.FILE_DOWNLOAD_MAX_DISK_SPACE

Integer

fileDownloadActionListenerタグがダウンロードできるファイルの最大サイズをKB単位で指定します。ファイルのサイズがこの値を超えると、例外が発生して、サーバーのログ・ファイルにログ・メッセージが記録されます。

web.xmlファイルのこのパラメータに値を指定しない場合は、デフォルトで2000に設定されます。

oracle.adf.view.rich.portal.FILE_DOWNLOAD_TEMP_DIR

String

ダウンロード時にファイルを格納する一時的な場所を指定します。値を指定しない場合は、デフォルトで、java.io.tempDirに指定されたディレクトリに設定されます。

web.xmlファイルの構成の詳細は、A.2項「web.xmlでの構成」を参照してください。JSFポートレットの作成方法の詳細は、『Oracle Fusion Middleware Oracle WebCenter開発者ガイド』を参照してください。

始める前に:

コンポーネントの属性が機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.5項「ボタンまたはリンクの機能の呼出し目的での使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

次のタスクを完了する必要があります。

アクション・コンポーネントを作成します。手順は20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

ファイルのダウンロード・メカニズムを作成する手順:

1. 「コンポーネント」ウィンドウの「操作」パネルの「リスナー」グループから、「ファイル・ダウンロード・アクション・リスナー」をアクション・コンポーネントに子としてドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- ContentType: ファイルのMIMEタイプを指定します。たとえば、text/plain、text/csv、application/pdfなどです。

- Filename: オブジェクトに対して提案するファイル名を指定します。ファイル名を指定すると、通常は「ファイルの保存」ダイアログが表示されますが、最終的にはブラウザにより異なります。名前を指定しない場合、通常、コンテンツはブラウザにインライン表示されます(可能な場合)。

- Method: ファイルの内容をダウンロードするメソッドを指定します。methodには、FacesContextオブジェクトおよびOutputStreamオブジェクトの2つの引数を指定できます。OutputStreamオブジェクトは自動的に閉じられるため、このmethodの唯一の目的は、すべてのバイトをOutputStreamオブジェクトに書き込むことです。

たとえば、buttonコンポーネントでfileDownloadActionListenerタグを使用する場合のJSFページ内のエントリは、次のようになります。

<af:button text="Load File">
<af:fileDownloadActionListener contentType="text/plain"
filename="MyFile.txt"
method="#(mybean.LoadMyFile"/>
</af:button>

20.5.2 入力フィールドをリセットするためのアクション・コンポーネントの使用方法

resetListenerタグをアクション・コンポーネントと組み合せて使用すると、入力値をリセットできます。エンド・ユーザーがアクション・コンポーネントを起動したときに、すべての入力値がnullまたは空にリセットされます。入力コンポーネントを以前の状態、つまりサーバーへの部分的または完全な送信が成功している状態にリセットする場合は、「リセット」ボタンを使用する必要があります。詳細は、11.2.3項「フォームをリセットするためのボタンの追加方法」を参照してください。

resetListenerタグを使用して、ポップアップにレンダリングされる入力コンポーネントをリセットする場合は、popupコンポーネントのresetEditableValuesプロパティの値も設定する必要があります。このユースケースの詳細は、15.7項「ポップアップの入力フィールドのリセット」を参照してください。

始める前に:

アクション・コンポーネントの属性が機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.5項「ボタンまたはリンクの機能の呼出し目的での使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

次のタスクを完了する必要があります。

アクション・コンポーネントを作成します。手順は20.3項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

リセット・リスナー・タグを使用する手順:

1. 「コンポーネント」ウィンドウの「操作」パネルの「リスナー」グループから、リセット・リスナーをドラッグし、作成済のアクション・コンポーネントの中にドロップします。

2. 「リセット・リスナーの挿入」ダイアログで、どのタイプのイベントへの応答としてresetListenerタグをアクティブにするかを指定します。たとえば、actionと入力すると、resetListenerタグはアクション・コンポーネントのactionListener属性によって返されたactionEventに反応します。
「リセット・リスナーの挿入」ダイアログで「ヘルプ」をクリックして、サポートされる値のリストを表示します。

20.6 ページ階層用のナビゲーション・アイテムの使用

注意:

アプリケーションでFusionテクノロジ・スタックをADF Controllerとともに使用する場合は、ADFタスク・フローとXMLMenuModel実装を使用してアプリケーションのページ階層のナビゲーション・システムを作成してください。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のタスク・フローを使用したページ階層の作成に関する項を参照してください。

アプリケーションはツリー式階層に関連付けて編成されたページで構成されます。ユーザーは、リンクのパスをドリルダウンして、ページ上の特定の情報にアクセスします。たとえば、図20-10は、トップレベル・ノードであるHomeの下に3つのレベルのノードがある単純なページ階層を示しています。トップレベル・ノードは、ルートの親ページを表しています。第1レベルのノードであるBenefitsおよびEmployee Dataは、より詳細な情報を含む第2レベルの子ノード(InsuranceやView Employeeなど)に関する汎用情報が含まれる親ページを表しています。Insuranceノードも親ノードで、第3レベルの子ノードであるHealthとDentalに関する汎用情報が含まれています。ページ階層の各ノード(ルートのHomeノードを除く)は、同時に親ノードにも子ノードにもなることができ、ページ階層の各ノードは1つのページに対応しています。

図20-10 BenefitsおよびEmployeeページ階層

ページ階層のナビゲーションは、親子のリンクに従います。たとえば、Healthの情報を表示するには、ユーザーはBenefitsページからドリルダウンを開始し、2つの選択肢(一方がHealth)が用意されているInsuranceページに移動します。Homeから始まり、Healthで終わる選択したリンクのパスは、ツリーのフォーカス・パスと呼ばれます。

直接の親子のナビゲーションのみでなく、レベル間または親間のナビゲーションも可能です。たとえば、Dentalページから、ユーザーは第2レベルのPaid Time Offページに移動することも、第1レベルのBenefitsページまたはEmployee Dataページに移動することもできます。

図20-10に示すように、階層内のどのノードにもリンクされていないが、トップレベルのHomeノードと同じレベルにあるHelpノードは、グローバル・ノードです。グローバル・ノードは、階層内のどのページからもアクセスできるグローバル・ページ(「ヘルプ」ページなど)を表します。

ページ階層をナビゲートするためのWebユーザー・インタフェースで使用される一般的なウィジェットは、タブ、バー、リスト、グローバル・リンクで、すべてnavigationPaneコンポーネントを使用して作成できます。図20-11は、図20-10に示した階層をnavigationPaneおよびその他のコンポーネントを使用してレンダリングする方法の例です。

図20-11 レンダリングされた「Benefits」および「Employee Data」ページ

「Benefits」および「Employee Data」ページのタブがある図20-11に示すように、第1レベルのノードとして、一般的にタブが使用されます。InsuranceおよびPaid Time Offなどの第2レベルのノードはバーとして、HealthおよびDentalなどの第3レベルのノードはリストとしてレンダリングされます。ただし、タブは、第1および第2レベルのノードの両方に使用できます。(グローバル・ノードを表す)グローバル・リンクは、テキスト・リンクとしてレンダリングされます。図20-11で、Homeおよび「ヘルプ」グローバル・リンクはテキスト・リンクとしてレンダリングされています。

第1、第2、第3レベルのノードまたはグローバル・ノードのいずれであるかにかかわらず、1つのnavigationPaneコンポーネントは、1レベルのノードに対応します。navigationPaneコンポーネントがレベルにレンダリングするように構成されているアイテムのタイプに関係なく、必ずcommandNavigationItemコンポーネントを使用してレベル内のアイテムを表します。

navigationPaneコンポーネントは、ナビゲーション用のタブ、バー、リストおよびグローバル・リンクをレンダリングするだけです。図20-16や図20-17に示すような、位置指定やページ背景のビジュアルなスタイル設定を行うには、decorativeBoxコンポーネントを第1レベルのnavigationPaneコンポーネントの親として使用します。decorativeBoxコンポーネントは、テーマおよびスキニング・キーを使用して、その様々なファセットの枠および色を制御します。たとえば、デフォルトのテーマを使用する場合、decorativeBoxコンポーネント本体は白、枠は青で、左上隅は丸くなります。ミディアム・テーマを使用する場合、本体は中間色の青になります。テーマおよびスキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ヒント:

ページ階層を作成するには、階層内の各ページで同じレイアウトおよびルック・アンド・フィールを使用する必要があるため、ナビゲーション・コンポーネントの配置場所やスタイルを決定するためにテンプレートの使用を検討してください。詳細は、10.3項「ページ・テンプレートの使用」を参照してください。

単純な階層の各ページで、まず一連のnavigationPaneコンポーネントを使用して階層の各レベルを表します。その後、各レベルのそれぞれのリンクに対して、navigationPaneコンポーネントの直接の子として、commandNavigationItemコンポーネントを追加します。たとえば、図20-11に示されているような健康保険のページを作成するには、まず、ページに表示されている各レベルにnavigationPaneコンポーネントを使用します。この場合は、グローバル・リンク、第1レベルのノード、第2レベルのノード、第3レベルのノードにそれぞれ1つずつです。その後、個々のリンクを表すために、commandNavigationItemコンポーネントをnavigationPaneコンポーネントのそれぞれに対して子として追加する必要があります(たとえば、第3レベルのnavigationPaneコンポーネントにcommandNavigationItem子コンポーネントを2つ追加して、第3レベルのリスト・アイテム2つを表します)。図20-12に示すように「Benefits」ページを作成した場合は、navigationPaneコンポーネントを3つ(グローバル、第1、第2の各レベルに1つずつ)のみ追加し、このページに表示されるリンクにcommandNavigationItemコンポーネントのみを追加します。

図20-12 第1レベルのページ

大規模なページ階層では、このプロセスは非常に時間がかかり、ミスも発生しやすくなります。大規模な階層の場合は、各ページに別々のcommandNavigationItemコンポーネントをそれぞれ作成するのではなく、XMLMenuModel実装およびマネージドBeanを使用して、ページのナビゲーション・アイテムを動的に生成することをお薦めします。メタデータ・ファイルとともに使用するXMLMenuModelクラスには、各ページに適切な数の階層レベルを生成するためのすべての情報と、各レベルに属するナビゲーション・アイテムが含まれます。

navigationPaneコンポーネント内に複数のcommandNavigationItemコンポーネントを使用し、各ページで現在の項目を選択済としてマーキングするかわりに、各navigationPaneコンポーネントを宣言的に同じXMLMenuModel実装にバインドし、nodeStampファセットにcommandNavigationItemコンポーネントを1つ使用してナビゲーション・アイテムを指定します。commandNavigationItemコンポーネントは、navigationPaneコンポーネントのスタンプとして機能し、XMLMenuModelオブジェクトに保持されている(各レベルの)ノードのナビゲーション・アイテムにスタンプを設定します。

また、menuBarコンポーネントをXMLMenuModel実装とともに使用し、ページ階層をナビゲートするためにメニュー項目にスタンプを設定することもできます。

注意:

アプリケーションの変更の反映に使用できるメニュー(「Open」および「Delete」コマンドが含まれる「File」メニューなど)を作成する場合は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

どのページでも、ユーザーの現在の位置をページ階層全体との関連で表示するには、一連のcommandNavigationItemコンポーネントまたは1つのcommandNavigationItemコンポーネントを含むbreadCrumbsコンポーネントをnodeStampとして使用し、現在のページ(フォーカス・パスの現在のノード)からルート・ページへ戻るリンクのパスを指定します。

XMLMenuModelを使用したナビゲーション階層の作成の詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。ナビゲーション階層の手動による作成の詳細は、20.8項「単純なナビゲーション階層の作成」を参照してください。

20.6.1 ページ階層用のナビゲーション・ケースの作成方法

ページ階層へのナビゲーション・アイテムの作成にメニュー・モデルを使用するか、手動でナビゲーション・アイテムを作成するかに関係なく、JSFナビゲーション・モデルは、デフォルトのActionListenerメカニズムを介し、ユーザーがナビゲーション・アイテムを選択する際に、ナビゲート先のページの選択に使用されます。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.6項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

ページ階層用にナビゲーション・ケースを作成する手順:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを展開し、faces-config.xmlをダブルクリックします。

2. ページ階層のすべてのノードのナビゲーション・ケースが含まれるグローバルなJSFナビゲーション・ルールを1つ作成します。
たとえば、図20-10に表示されているページ階層には、10個のノードがあります(これにはグローバルのHelpノードも含まれます)。この場合、例20-4に示すように、faces-config.xmlファイルの1つのグローバル・ナビゲーション・ルール内に10のナビゲーション・ケースを作成します。

各ナビゲーション・ケースに、一意の結果文字列と、指定された文字列に一致する結果値がナビゲーション・システムによって返された場合に表示するJSFページへのパスを指定します。

例20-4 faces-config.xml内のページ階層のグローバル・ナビゲーション・ルール

<navigation-rule>
<navigation-case>
<from-outcome>goHome</from-outcome>
<to-view-id>/home.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHelp</from-outcome>
<to-view-id>/globalhelp.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goEmp</from-outcome>
<to-view-id>/empdata.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goBene</from-outcome>
<to-view-id>/benefits.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goIns</from-outcome>
<to-view-id>/insurance.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goPto</from-outcome>
<to-view-id>/pto.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goView</from-outcome>
<to-view-id>/viewdata.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goCreate</from-outcome>
<to-view-id>/createemp.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHealth</from-outcome>
<to-view-id>/health.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goDental</from-outcome>
<to-view-id>/dental.jsf</to-view-id>
</navigation-case>
</navigation-rule>

JDeveloperにおけるナビゲーション・ケースの作成方法の詳細は、3.3項「ページ・フローの定義」を参照してください。

20.7 メニュー・モデルを使用したページ階層の作成

注意:

アプリケーションでFusionテクノロジ・スタックまたはADF Controllerを使用する場合は、ADFタスク・フローとXMLMenuModel実装を使用してアプリケーションのページ階層のナビゲーション・システムを作成してください。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のタスク・フローを使用したページ階層の作成に関する項を参照してください。

20.6項「ページ階層用のナビゲーション・アイテムの使用」に、複数のcommandNavigationItem子コンポーネントを含むnavigationPaneコンポーネントを使用して、非常に単純なページ階層用のナビゲーション・アイテムを作成する方法が説明されています。より複雑なページ階層で同じ方法を使用すると時間がかかり、ミスが起こりやすくなります。ナビゲーションを可能にするすべての項目を作成するために、複数のJSFページのnavigationPaneおよびbreadCrumbsコンポーネントに個々のcommandNavigationItemコンポーネントを手動で挿入し構成するのは、非効率的で単調な作業です。各項目について正確なselectedステータスを管理したり、現在のページからルート・ページに戻るブレッドクラム・リンクをたどって追跡するのも困難です。

より複雑なページ階層の場合(および単純なページ階層の場合でも)、ナビゲーション・システムを作成するより効率的な方法は、メニュー・モデルを使用することです。メニュー・モデルは、特別なツリー・モデルです。ツリー・モデルは、行キーで索引付けされた行のコレクションです。ツリーでは、現在行に子の行を含めることができます(ツリー・モデルの詳細は、12.6項「ツリーへのデータの表示」を参照してください)。メニュー・モデルは、現在フォーカス(フォーカス・ノード)があるノードのrowKeyを取得できるツリー・モデルです。メニュー・モデルにはページ・ナビゲーションの特別な情報はなく、ツリーにアクセスするノードに対する要件もありません。

XMLMenuModelクラスは、ナビゲーション・ツリー・モデルからメニュー・モデルを作成します。ただし、XMLMenuModelクラスには、XMLメタデータにナビゲーションの階層ツリーを定義できる追加のメソッドがあります。(他のADF Facesのメニュー・モデル・クラスの1つを使用している場合のように)Javaクラスを作成し多数のマネージドBeanを構成してメニュー・モデルを定義および作成するかわりに、XMLMenuModelクラスでメニュー・モデルを作成する際に必要なすべてのノード情報を含む1つ以上のXMLMenuModelメタデータ・ファイルを作成します。

ヒント:

navigationPaneコンポーネントとpanelTabbedコンポーネントを混同しないでください。panelTabbedコンポーネントは、複数のタブ付きコンテンツ領域の表示に使用します。これらの領域は、非表示にするか表示するかを設定できます(9.10項「パネルにおけるコンテンツの表示または非表示」を参照)。ただし、panelTabbedコンポーネントはナビゲーション・モデルにはバインドできず、ページ内からすべてのコンテンツにアクセスできる必要があるため、適用性は制限されています。

メニュー・モデルを使用してページ階層を作成する手順:

- ページ階層にJSFナビゲーション・ルールおよびナビゲーション・ケースを作成します。20.6.1項「ページ階層用のナビゲーション・ケースの作成方法」を参照してください。

- XMLMenuModelメタデータを作成します。20.7.1項「メニュー・モデル・メタデータの作成方法」を参照してください。

- XMLMenuModelクラスにマネージドBeanを構成します。このマネージドBeanは、アプリケーションにより階層の作成に使用されます。この構成は、JDeveloperで「ADFメニュー・モデルの作成」ダイアログを使用してXMLMenuModelメタデータ・ファイルを作成する際に、自動的に行われます。20.7.2項「ADFメニュー・モデルの作成ウィザードを使用する場合の処理」を参照してください。

- 各階層ノード(グローバル・ノードも含む)にJSFページを作成します。

ヒント:

通常、各レベルの項目(グローバル項目およびブレッドクラムを含む)に対するファセットが含まれるページ・テンプレートを使用して、各JSFページを作成します。たとえば、グローバル項目を表すnavigationPaneコンポーネントはnavigationGlobalという名前のファセットでラップし、第1レベルのタブを表すnavigationPaneコンポーネントはnavigation1という名前のファセットでラップします。ページ・テンプレートの作成の詳細は、第10章「フラグメント、ページ・テンプレート、コンポーネントの作成および再利用」を参照してください。

- 各ページで、navigationPaneおよびbreadCrumbsコンポーネントをXMLMenuModelクラスにバインドします。20.7.3項「メニュー・モデルへのnavigationPaneコンポーネントのバインド方法」および20.7.4項「メニュー・モデルでのbreadCrumbsコンポーネントの使用方法」を参照してください。menuBarコンポーネントをバインドするには、20.7.5項「メニュー・モデルでのmenuBarコンポーネントの使用方法」を参照してください。

20.7.1 メニュー・モデル・メタデータの作成方法

XMLMenuModelメタデータ・ファイルは、XML形式によるページ階層用のナビゲーション・メニューの表現です。1つ以上のXMLMenuModelメタデータ・ファイルを使用して、ページ階層全体を表すことが可能です。XMLMenuModelメタデータ・ファイルでは、ページ階層が、ファイルのルート要素であるmenu要素内に説明されています。各XMLMenuModelメタデータ・ファイルにはmenu要素が必要で、各ファイルで使用できるmenu要素は1つのみです。

XMLMenuModelメタデータ・ファイルまたは階層のその他の要素は、項目ノード、グループ・ノードおよび共有ノードで構成されています。項目ノードは、階層のナビゲート可能なノード(またはページ)を表します。たとえば、図20-13に示すような階層を作成するとします。

図20-13 サンプルのページ階層

階層の各ノードにユーザーがナビゲートできる独自のページを作成する場合は、各ページのメタデータ・ファイルに項目ノードを作成します。親ノードに子ノードをネストさせて階層を作成します。ただし、Employee Dataノードにはページが必要ないが、ユーザーが直接View Employeeページにナビゲートできるようにするとします。グループ・ノードを使用して「Employee Data」ページを表し、グループ・ノードのidref属性を使用して、エンド・ユーザーが「Employee Data」タブをクリックすると開かれるページ(「View Employee」ページ)を参照します。グループ・ノードを使用すると、単に子ノードの集約であるノード用にページを作成せずに階層を維持できます。

例20-5に示すXMLMenuModelメタデータ・ファイルでは、図20-13に示すページ階層全体を、主に項目ノードを使用し、グループ・ノードも1つ使用して定義しています。

例20-5 XMLMenuModelメタデータ・ファイルのサンプル1

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<itemNode id="in01" focusViewId="/home.jsf" label="Home" action="goHome">
<itemNode id="in1" focusViewId="/benefits.jsf" action="goBene"
label="Benefits">
<itemNode id="in11" focusViewId="/insurance.jsf" action="goIns"
label="Insurance">
<itemNode id="in111" focusViewId="/health.jsf" action="goHealth"
label="Health"/>
<itemNode id="in112" focusViewId="/dental.jsf" action="goDental"
label="Dental"/>
</itemNode>
<itemNode id="in12" focusViewId="/pto.jsf" action="goPto"
label="Paid Time Off">
<itemNode id="in121" focusViewId="/vacation.jsf"
action="goVacation" label="Vacation"/>
<itemNode id="in122" focusViewId="/sick.jsf" action="goSick"
label="Sick Pay"/>
</itemNode>
</itemNode>
<groupNode id="gn2" idref="newEmp" label="Employee Data">
<itemNode id="in21" focusViewId="/createemp.jsf" action="goCreate"
label="Create New Employee"/>
<itemNode id="in22" focusViewId="/viewdata.jsf" action="goView"
label="View Data"/>
</groupNode>
</itemNode>
<itemNode id="in02" focusViewId="/globalhelp.jsf" action="goHelp"
label="Help"/>
<itemNode id="in03" focusViewId="/preferences.jsf" action="goPref"
label="Preferences"/>
</menu>

ルートのmenu要素内では、menu要素の直接の子であればどのノードでもグローバル・ノードになります。たとえば、例20-5のコードには、Home、Help、Preferencesの3つのグローバル・ノードが示されています。

共有ノードを使用して、メニュー・モデルをネストさせることも可能です。階層内にサブ・ツリー(たとえば「Benefits」ツリー)がある場合にこの方法を使用すると、ページ階層の保守が容易になります。たとえば、(例20-6に示すように)Benefitsツリー全体を独自のメニュー・モデル・メタデータ・ファイルとして作成できるため、アプリケーション全体でメニュー・モデルを再利用できます。

例20-6 Benefits XMLMenuModelメタデータ・ファイル

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<itemNode id="in1" focusViewId="/benefits.jsf" action="goBene"
label="Benefits">
<itemNode id="in11" focusViewId="/insurance.jsf" action="goIns"
label="Insurance">
<itemNode id="in111" focusViewId="/health.jsf" action="goHealth"
label="Health"/>
<itemNode id="in112" focusViewId="/dental.jsf" action="goDental"
label="Dental"/>
</itemNode>
<itemNode id="in12" focusViewId="/pto.jsf" action="goPto"
label="Paid Time Off">
<itemNode id="in121" focusViewId="/vacation.jsf"
action="goVacation" label="Vacation"/>
<itemNode id="in122" focusViewId="/sick.jsf" action="goSick"
label="Sick Pay"/>
</itemNode>
</itemNode>
</menu>

独立したメニュー・モデルとしてノードを作成したら、そのれらのノードを使用する必要がある別のノード内で共有ノードを使用して、Benefitsメニュー・モデルを参照します。

例20-7に示すXMLMenuModelメタデータ・ファイルでは、図20-13に示したのと同じページ階層を、項目ノード、共有ノード1個およびグループ・ノード1個を使用して定義しています。

例20-7 XMLMenuModelメタデータ・ファイルのサンプル2

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<itemNode id="in01" focusViewId="/home.jsf" label="Home" action="goHome">
<sharedNode ref="#{benefits_menu}/>
<groupNode id="gn2" idref="newEmp" label="Employee Data">
<itemNode id="in21" focusViewId="/createemp.jsf" action="goCreate"
label="Create New Employee"/>
<itemNode id="in22" focusViewId="/viewdata.jsf" action="goView"
label="View Data"/>
</groupNode>
</itemNode>
<itemNode id="in02" focusViewId="/globalhelp.jsf" action="goHelp"
label="Help"/>
<itemNode id="in03" focusViewId="/preferences.jsf" action="goPref"
label="Preferences"/>
</menu>

sharedNode要素は、Benefits XMLMenuModelメタデータ・ファイル用に構成されているマネージドBeanを参照します。「ADFメニュー・モデルの作成」ウィザードを使用してメタデータ・ファイルを作成する場合はいつでも、JDeveloperにより、マネージドBean構成が自動的に追加されます。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

XMLMenuModelメタデータを作成する手順:

1. 「アプリケーション」ウィンドウで、どのプロジェクトのXMLMenuModelメタデータ・ファイルを作成するかを選択します。WEB-INFノードを開き、faces-config.xmlを右クリックして「ADFメニュー・モデルの作成」を選択します。

注意:

アプリケーションでADFコントローラが使用されている場合は、このメニュー・オプションを使用できません。かわりに、バインド・タスク・フローを使用して階層を作成できます。『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のタスク・フローを使用したページ階層の作成に関する項を参照してください。

2. 「ADFメニュー・モデルの作成」ダイアログで、XMLMenuModelメタデータ・ファイルのファイル名(root_menuなど)を入力します。

ヒント:

複数のXMLMenuModelメタデータ・ファイルを使用してページ階層を定義する場合は、root_menuという名前は最上位(ルート)のメタデータ・ファイルのみに使用してください。このファイルの中で、他のサブメニュー・メタデータ・ファイルを参照します。

3. メタデータ・ファイルのディレクトリを入力します。JDeveloperのデフォルトでは、XMLMenuModelメタデータ・ファイルはアプリケーションのWEB-INFノードに保存されます。
例20-8に示すように、「OK」をクリックすると、JDeveloperにより、空のXMLMenuModelメタデータ・ファイルがソース・エディタに表示されます。

例20-8 空のXMLMenuModelメタデータ・ファイル

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu"></menu>

JDeveloperによって自動的にfaces-config.xmlに追加されるマネージドBean構成の詳細は、20.7.2項「ADFメニュー・モデルの作成ウィザードを使用する場合の処理」を参照してください。

4. 「構造」ウィンドウでmenuノードを選択し、「プロパティ」ウィンドウで情報を入力します。
表20-2に、menu要素に指定できる属性を示します。

表20-2 menu要素の属性

属性

説明

resourceBundle

オプション。実行時にナビゲーション・アイテムのラベル(表示可能なテキスト)に使用するリソース・バンドルです。org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundleなどです。

var

リソース・バンドルを使用している場合は、ナビゲーション・アイテム・ラベルのEL式のバンドルの参照に使用するIDを指定します。#{bundle.somelabel}などです。リソース・バンドルを使用するXMLMenuModelメタデータ・ファイルのサンプルは、例20-9を参照してください。

xmlns

必須。http://myfaces.apache.org/trinidad/menuに設定します。

例20-9に、ナビゲーション・アイテムのラベルのリソース・バンドルにアクセスするためにEL式を使用する、サンプルのXMLMenuModelメタデータ・コードを示します。

例20-9 リソース・バンドルを使用したXMLMenuModel

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu"
resourceBundle="org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundle"
var="bundle">
<itemNode id="in1" label="#{bundle.somelabel1}" ../>
<itemNode id="in2" label="#{bundle.somelabel2}" ../>
</menu>

注意:

sharedNode要素を使用してサブメニューを作成するとともに、ナビゲーション・アイテムのラベルにリソース・バンドルを使用する場合は、共有メニュー・モデルにおいてルートmenu要素のvar属性に同じ値が使用される可能性があります。XMLMenuModelクラスでは、解析中に各リソース・バンドルに一意のハッシュ・キーが割り当てられていることを確認することにより、この可能性に対応します。

リソース・バンドルの使用方法の詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

5. 「構造」ウィンドウで、menuを右クリックして「menuの中に挿入」を選択してから、目的の要素(itemNode、groupNodeまたはsharedNode)をポップアップ・メニューから選択して(図20-14を参照)階層内のノードに追加します。

図20-14 menuに要素を挿入するためのポップアップ・メニュー

要素は次のいずれかです。

- itemNode: ユーザーによる選択時にナビゲーションを実行するノードを指定します。

- groupNode: グループの子コンポーネントで、groupNode自体はナビゲーションを行いません。子ノードは、itemNodeまたは別のgroupNodeにすることができます。
たとえば、Employee Dataノードにはページが必要ないが、ユーザーが直接View Employeeページにナビゲートできるようにするとします。必要な子ノードのid属性をグループ・ノードのidref属性の値として指定することで、グループ・ノードを使用して「Employee Data」ページを表します。グループ・ノードを使用すると、単に子ノードの集約であるノード用にページを作成せずに階層を維持できます。

- sharedNode: 別のXMLMenuModelインスタンスを参照します。sharedNode要素は真のノードではなく、ナビゲーションの実行もノード自体へのレンダリングも行われません。
sharedNode要素は、階層内の任意の場所に挿入できます。たとえば、例20-10に示されているコードでは、sharedNode要素により、第1レベルのEmployee Dataノードと同じレベルにサブメニューが追加されています。

例20-10 sharedNodeのサンプル・コード

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu"
<itemNode id="in0" label="Home" ..>
<sharedNode ref="#{shared_menu}"/>
<itemNode id="in1" label="Employee Data" ../>
</itemNode>
<itemNode id="in01" label="Help" ../>
</menu>

XMLMenuModelメタデータ・ファイルを作成すると、図20-15に示すように、メニュー・メタデータのインデント・レベルが構造ウィンドウに表示されるツリー構造に正確に反映されます。

図20-15 構造ウィンドウのXMLMenuModelメタデータのツリー構造

6. ノードの作成に使用されている各要素のプロパティを「プロパティ」ウィンドウで設定します。itemNode要素は表20-3、groupNode要素は表20-4、sharedNode要素は表20-5の説明を参照してください。

表20-3 itemNode要素の属性

属性

説明

action

結果文字列、または結果文字列を返すELメソッド・バインディング式を指定します。どちらの場合も、結果文字列は、faces-config.xmlファイルに構成されているように、そのノードのナビゲーション・ケースに対するfrom-outcome値に一致する必要があります。

destination

ノードが選択されたときにナビゲートするページのURIを指定します(例: http://www.oracle.com)。ナビゲート先がJSFページの場合、URIは/facesで開始する必要があります。

または、そのURIに評価されるELメソッド式を指定します。

actionおよびdestinationの両方が指定されている場合は、actionよりdestinationが優先されます。

focusViewId

必須。ノードのナビゲーション結果に一致するページのURI。つまり、faces-config.xmlファイルに指定されているそのノードのナビゲーション・ケースのto-view-id値。

たとえば、ノードのアクション結果が/page_one.jsfへのナビゲートである場合は(faces-config.xmlファイルで構成されます)、focusViewIdも/page_one.jsfであることが必要です。

focusViewIdは、ナビゲーションは実行しません。ページ・ナビゲーションは、actionまたはdestination属性によって行われます。ただし、XMLMenuModelが現在のフォーカス・パスを確認するためにfocusViewIdが必要です。

id

必須。ノードの一意の識別子を指定します。

例20-5に示されているように、各itemNodeのIDにinXを使用することをお薦めします。ここで、inXはin1、in11、in111、in2、in21、in 211などです。

label

ノードに表示するラベル・テキストを指定します。#{bundle.somelabel}など、リソース・バンドルの文字列に対するEL式も使用できます。このbundleは、ルートmenu要素のvar属性の値に一致する必要があります。

groupNode要素には、直接ナビゲーションを実行するactionまたはdestination属性はありませんが、(actionまたはdestination属性のある)子のitemNodeを直接示すか、itemNode要素に到達するまで、子ノードのいずれかを示す子のgroupNodeを間接的に示すことにより、アクション結果または宛先のURIを含む子ノードを示します。ナビゲーションは、その後、アクション結果またはそのitemNode要素の宛先のURIから決定されます。

例20-11に示されているgroupNodeのコードを例にとります。実行時、ユーザーがgroupNode id="gn1"、groupNode id="gn11"またはitemNode id="in1"をクリックすると、到達した最初のitemNode (つまり、itemNode id="id1")に指定されているように、ナビゲーション結果はgoToSubTabOneになります。表20-4に、groupNode要素を使用する際に指定する必要のある属性を示します。

例20-11 groupNode要素

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns:"http://myfaces.apache.org/trinidad/menu">
<groupNode id="gn1" idref="gn11" label="GLOBAL_TAB_0">
<groupNode id="gn11" idref="in1" label="PRIMARY_TAB_0">
<itemNode id="in1" label="LEVEL2_TAB_0" action="goToSubTabOne"
focusViewId="/menuDemo/subtab1.jsf"/>
<itemNode id="in2" label="LEVEL2_TAB_1" action="goToSubTabTwo"
focusViewId="/menuDemo/subtab2.jsf"/>
</groupNode>
<itemNode id="in3" label="PRIMARY_TAB_1" focusViewId="/menuDemo/tab2.jsf"
destination="/faces/menuDemo/tab2.jsf"/>
</groupNode>
<itemNode id="gin1" label="GLOBAL_TAB_1" action="goToGlobalOne"
focusViewId="/menuDemo/global1.jsf"/>
<itemNode id="gin2" label="GLOBAL_TAB_2"
destination="/faces/menuDemo/global2.jsf"
focusViewId="/menuDemo/global2.jsf"/>
</menu>

表20-4 groupNode要素の属性

属性

説明

id

グループ・ノードの一意の識別子。

例20-11に示されているように、各groupNodeのIDにgnXを使用することをお薦めします。ここで、gnXはgn1、gn2などです。

idref

子ノードのID (itemNodeまたは別のgroupNode)を指定します。子ノードとしてgroupNodeを追加する場合、その子は別のgroupNodeなどを参照できますが、最終的には、子のitemNodeは最後の子として参照する必要があります。

idref属性には、空白で区切って複数の子IDを指定でき、IDはリストされた順序で処理されます。

label

グループ・ノードに表示するラベル・テキストを指定します。リソース・バンドルの文字列へのEL式(#{bundle.somelabel}など)にすることもできます。

表20-5 sharedNode要素の属性

属性

説明

ref

faces-config.xmlファイルに構成されているように、別のXMLMenuModelクラスのマネージドBean名(#{shared_menu}など)を指定します。

実行時に、参照ナビゲーション・メニューが作成され、メイン(ルート)のメニューにサブメニューとして挿入されてレンダリングされます。

20.7.2 「ADFメニュー・モデルの作成」ウィザードを使用する場合の処理

「ADFメニュー・モデルの作成」ウィザードを使用してXMLMenuModelメタデータ・ファイルを作成する場合、マネージドBean名として指定したメタデータ・ファイル名を使用して、JDeveloperによりfaces-config.xmlファイルのメニュー・メタデータ・ファイルにマネージドBeanが自動的に構成されます。

例20-12に、XMLMenuModelメタデータ・ファイルの構成が1つ含まれるfaces-config.xmlファイルの一部を示します。JDeveloperでは、デフォルトで、oracle.adf.view.rich.model.MDSMenuModelクラスがマネージドBeanクラスとして使用され、必須で変更できないrequestはマネージドBeanスコープとして使用されます。

例20-12 faces-config.xml内のXMLMenuModelのマネージドBean構成

<managed-bean>
<managed-bean-name>root_menu</managed-bean-name>
<managed-bean-class>oracle.adf.view.
rich.model.MDSMenuModel</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<managed-property>
<property-name>createHiddenNodes</property-name>
<value>false</value>
</managed-property>
<managed-property>
<property-name>source</property-name>
<property-class>java.lang.String</property-class>
<value>/WEB-INF/root_menu.xml</value>
</managed-property>
</managed-bean>

また、XMLMenuModelのマネージドBeanに、次のマネージド・プロパティが追加されます。

- createHiddenNodes: trueの場合、コンポーネントのrendered属性がfalseの場合でも、階層ノードを作成する必要があることを指定します。createHiddenNodes値は、取得されて、メニュー・メタデータ・ソース・ファイルが開かれて解析されると使用可能になります。これにより、実際のコンポーネントをレンダリングする必要がない場合でも、階層全体を作成できます。

- source: 使用するメニュー・メタデータ・ソース・ファイル(/WEB-INF/root_menu.xmlなど)を指定します。

注意:

createHiddenNodesプロパティは、sourceプロパティの前に配置する必要があります。JDeveloperによってマネージドBeanが自動的に設定される際は、このように配置されます。sourceマネージド・プロパティからメニューのXMLメタデータを適切に解析および作成するには、XMLMenuModelマネージドBeanにcreateHiddenNodes値が事前に設定されている必要があります。

ウィザードを使用してプロジェクトに作成する各XMLMenuModelメタデータ・ファイルに対し、JDeveloperにより、faces-config.xmlファイルにマネージドBeanが構成されます。たとえば、(例20-10に示すように)別のXMLMenuModelメタデータ・ファイルを参照するために、XMLMenuModelにsharedNode要素を使用すると、2つのメタデータ・ファイルが作成されます。また、例20-13に示すように、JDeveloperにより、faces-config.xmlファイルに2つのマネージドBean構成(1つ目はメイン(ルート)メニュー・モデル用、2つ目のマネージドBeanは共有(参照)メニュー・モデル用)が追加されています。

例20-13 faces-config.xml内の共有メニュー・モデルのマネージドBean

<!-- managed bean for referenced, shared menu model -->
<managed-bean>
<managed-bean-name>shared_menu</managed-bean-name>
<managed-bean-class>
<managed-bean-class>oracle.adf.view.
rich.model.MDSMenuModel</managed-bean-class>
</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<managed-property>
<property-name>createHiddenNodes</property-name>
<value>false</value>
</managed-property>
<managed-property>
<property-name>source</property-name>
<property-class>java.lang.String</property-class>
<value>/WEB-INF/shared_menu.xml</value>
</managed-property>
</managed-bean>

つまり、XMLMenuModelメタデータ・ファイルに共有ノードを使用すると、faces-config.xmlファイルには、ルート・メニュー・モデルのマネージドBeanと、共有ノードを介して参照される任意のメニュー・モデル用のメニュー・モデルのマネージドBeanが含まれます。

20.7.3 メニュー・モデルへのnavigationPaneコンポーネントのバインド方法

ページ階層の各ノードは1つのJSFページに対応します。各ページで、XMLMenuModelメタデータ・ファイルに定義したナビゲーション・アイテム(グローバル・アイテムも含む)の各レベルにnavigationPaneコンポーネントを1つ使用します。レベルは、ゼロから始まるインデックスの番号によって決定されます。メタデータ・ファイルのグローバル・ノード(つまり、例20-5に示すように、menu要素の直接の子ノード)で始まり、level属性値は0 (ゼロ)で、次のレベル(通常はタブ)は1、その次のレベル(通常はバー)は2というように続きます。たとえば、図20-13と例20-5に示すようなページ階層の場合は、3つのnavigationPaneコンポーネントをHomeなどのページで使用し(Homeノードの下の3レベルのナビゲーション用)、さらに1つのnavigationPaneコンポーネントをグローバル・ノード用に使用します。

ヒント:

メニュー・モデルにより、動的に階層(各navigationPaneコンポーネントに表示されるリンク)が決定され、フォーカス・パスの現在のノードが選択済として設定されるため、事実上、各ページに同じコードを再利用できます。実行する必要があるのは、ページのドキュメント・タイトルの変更と、そのページに表示する特定のページ・コンテンツの追加のみです。

コードが似ているため、navigationPaneコンポーネントを含むファセットのみが存在する単一のページ・フラグメントを作成し、ページのドキュメント・タイトルの変更やページ・コンテンツの追加を行う各ページにそのフラグメントを追加できます。

20.8.1項「単純なページ階層の作成方法」で説明しているように、hint属性を使用して、各階層レベルに使用するナビゲーション・アイテムのタイプ(buttons、tabs、barなど)を指定します。ただし、複数のcommandNavigationItemコンポーネントを手動で追加してナビゲーション・アイテムを指定するのではなく、例20-14に示すように、各navigationPaneコンポーネントをXMLMenuModelマネージドBeanにバインドし、各navigationPaneコンポーネントのnodeStampファセットにcommandNavigationItemコンポーネントを1つのみ挿入します。

例20-14 XMLMenuModelマネージドBeanにバインドされたnavigationPaneコンポーネント

<af:navigationPane var="menuNode" value="#{root_menu}" level="0"
hint="buttons">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"
icon="#{menuNode.icon}"
destination="#{menuNode.destination}"
visible="#{menuNode.visible}"
rendered="#{menuNode.rendered}"/>
</f:facet>
</af:navigationPane>

XMLMenuModelマネージドBeanとともに使用するnodeStampファセットと単一のcommandNavigationItemコンポーネントにより、次の操作が実行されます。

- レベル内のナビゲーション・アイテムの適切な数がスタンプ設定されます。

- 正しいラベル・テキストとその他のプロパティが、メタデータに定義されているとおりに表示されます。たとえば、EL式#{menuNode.label}によりナビゲーション・アイテムに使用する適切なラベル・テキストが取得され、#{menuNode.doAction}は同じ項目に定義されているアクション結果に評価されます。

- フォーカス・パスの現在の項目が選択済とマークされます。commandNavigationItemコンポーネントにはselected属性は指定できません。

注意:

特定の階層レベル(第3レベルのリストなど)のXMLMenuModelオブジェクトにノード情報がない場合、ページにはそのレベルのnavigationPaneコンポーネントのコードが含まれていても、ADF Facesではページにそれらの項目は表示されません。

ナビゲーション・アイテムのスタイルを設定する場合は、decorativeBoxコンポーネントを作成します。作成するには、「コンポーネント」ウィンドウの「レイアウト」パネルから「装飾ボックス」をJSFページにドラッグ・アンド・ドロップします。テーマを設定して、タブの表示方法を決定します。有効な値は次のとおりです。

- default

- light

- medium

- dark

値はそれぞれ、コンポーネントのテーマ値が指定されたときにADFスキンによってアプリケーションに適用されるルック・アンド・フィールを表します。テーマをどのように表示するかを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

メニュー・モデルにnavigationPaneコンポーネントをバインドする手順:

1. 階層のレベルごとに、「コンポーネント」ウィンドウの「レイアウト」パネルの「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・ペイン」をJSFページにドラッグ・アンド・ドロップします。
たとえば、図20-13の階層のようなページを作成するには、JSFページにnavigationPaneコンポーネントを4つドラッグ・アンド・ドロップします。

2. navigationPaneコンポーネントのそれぞれについて、「プロパティ」ウィンドウの「共通」セクションを開いて、次に示すナビゲーション・アイテムのタイプの1つを「ヒント」ドロップダウン・リストで選択します。これによって、navigationPaneをどのように表示するかが決まります。

- bar: バーで分割されたナビゲーション・アイテムを表示します。図20-17の「Insurance」および「Paid Time Off」リンクなどがこれに当たります。

- buttons: グローバル領域のバーで分割されたナビゲーション・アイテムを表示します。図20-17の「Home」および「Help」リンクなどがこれに当たります。

- choice: 関連付けられたドロップダウン・アイコンがクリックされると、ポップアップ・リストにナビゲーション・アイテムが表示されます。navigationPaneコンポーネントのicon属性に値を含める必要があり、title属性を使用してドロップダウン・リストにラベルを関連付けることができます。

- list: ナビゲーション・アイテムが箇条書きリストで表示されます。図20-17の「Health」および「Dental」リンクなどがこれに当たります。

- tabs: ナビゲーション・アイテムがタブで表示されます。図20-17の「Benefits」および「Employee Data」タブなどがこれに当たります。

3. 「レベル」フィールドに、XMLMenuModelメタデータ・ファイルでのメタデータのレベルを表す数値を入力します。level属性は、ゼロから始まるインデックスの番号です。メタデータ・ファイルのグローバル・ノード(つまり、例20-5に示すように、menu要素の直接の子ノード)で始まり、level属性値は0 (ゼロ)で、次のレベル(通常はタブ)は1、その次のレベル(通常はバー)は2というように続きます。
commandNavigationItemコンポーネントは、親のnavigationPaneコンポーネントのlevel属性を介して、メタデータ・ファイルからメタデータを取得することができます。デフォルトでは、level属性の値を指定しない場合は0 (ゼロ)が使用されます。つまり、navigationPaneコンポーネントのメタデータはmenu要素の下の最初のレベルから取得され、これがcommandNavigationItemコンポーネントによるレンダリングに使用されます。

4. 「プロパティ」ウィンドウの「データ」セクションを開いて、次のとおりに設定します。

- Value: faces-config.xmlファイル内でルートXMLMenuModelクラスに対して構成されている、メニュー・モデル・マネージドBeanに設定します。

注意:

value属性が参照できるのは、ルート・メニュー・モデルと共有ノードによって参照されるメニュー・モデルです。value属性で共有ノードを参照した場合、faces-config.xmlファイルには、メニュー・モデル・メタデータ・ファイルのルート・メニュー・モデル定義に使用される名前とは異なるマネージドBean名を使用した新しいマネージドBeanエントリが必要です。これにより、value属性で参照可能なルート・メニュー・モデルに共有ノードのメニュー・モデルがプロモートされます。

- Var: commandNavigationItemコンポーネントに必要なデータをメニュー・モデルから取得するのに使用するテキストを設定します。
実行時に階層が作成されて各ノードにスタンプが設定されると、EL式を使用して特定可能なvar属性に現在のノードのデータがコピーされます。varプロパティを使用して、このプロパティに使用する名前をEL式に指定します。

ヒント:

ページまたはアプリケーションのすべてのnavigationPaneコンポーネントのvar属性に同じ値を使用します。

5. 「コンポーネント」ウィンドウの「レイアウト」パネルの「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・アイテム」をnavigationPaneコンポーネントのnodeStampファセットにドラッグ・アンド・ドロップします。

6. (必要な情報が含まれるメタデータを持つ)メニュー・モデルを参照するEL式を使用して、対応する値がメタデータに保持される残りの属性に値を設定します。手順4で、値がメタデータで保持されている対応するitemNode要素の名前とともに、親のnavigationPaneコンポーネントに設定したvar属性の値を使用してこれらの値にアクセスします。表20-6に、対応する値がメタデータにあるナビゲーション・アイテムの属性を示します。

表20-6 ナビゲーション・アイテムの属性および関連付けられたメニュー・モデルの属性

ナビゲーション・アイテムの属性

関連付けられたメニュー・モデル要素の属性

text

label

action

doAction

icon

icon

destination

destination

visible

visible

rendered

rendered

たとえば、親のnavigationPaneコンポーネントのvar属性をmenuNodeに設定した場合、action属性の値のEL式として#{menuNode.doAction}を使用します。これは、各ノードのメタデータに設定されているactionプロパティに解決されます。例20-15に、4レベルの階層ノードがあるメニュー・モデルにバインドするためのJSFコードを示します。

例20-15 XMLMenuModelへのバインド

<af:form>
<af:navigationPane hint="buttons" level="0" value="#{root_menu}"
var="menuNode">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"
icon="#{menuNode.icon}"
destination="#{menuNode.destination}"/>
</f:facet>
</af:navigationPane>
<af:navigationPane hint="tabs" level="1" value="#{root_menu}"
var="menuNode">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"
icon="#{menuNode.icon}"
destination="#{menuNode.destination}"/>
</f:facet>
</af:navigationPane>
<af:navigationPane hint="bar" level="2" value="#{root_menu}"
var="menuNode">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"
icon="#{menuNode.icon}"
destination="#{menuNode.destination}"/>
</f:facet>
</af:navigationPane>
<af:navigationPane hint="list" level="3" value="#{root_menu}"
var="menuNode">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"
icon="#{menuNode.icon}"
destination="#{menuNode.destination}"/>
</f:facet>
</af:navigationPane>
</af:form>

注意:

ユーザーがナビゲーション・タブを閉じられるようにする方法の詳細は、20.8.3項「ナビゲーション・タブの削除に関する必知事項」を参照してください。

20.7.4 メニュー・モデルでのbreadCrumbsコンポーネントの使用方法

メニュー・モデルを使用したブレッドクラムの作成は、ページ階層の作成に似ています。commandNavigationItemコンポーネントにスタンプを設定するnodeStampファセットを含むbreadCrumbsコンポーネントは、モデルのデータとともに使用します。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

メニュー・モデルを使用したブレッドクラムの作成手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルの「位置」グループから、「ブレッドクラム」をJSFページにドラッグ・アンド・ドロップします。

2. デフォルトでは、ブレッドクラム・リンクは横に並べて表示されます。レイアウトを縦に変更するには、「プロパティ」ウィンドウの「共通」セクションを開いて「向き」ドロップダウン・リストからverticalを選択します。

3. 「プロパティ」ウィンドウの「データ」セクションを開いて、次のとおりに設定します。

- Value: faces-config.xmlファイル内で構成されている、ルートXMLMenuModelマネージドBeanに設定します。これが、navigationPaneコンポーネントがバインドされるのと同じBeanです。

注意:

value属性が参照できるのは、共有ノードを介して参照されるメニュー・モデルではなく、ルート・メニュー・モデルのみです。たとえば、(例20-10に示されているように)メインのXMLMenuModel要素に共有ノードを使用している場合は、JDeveloperにより、その共有ノードにマネージドBean構成が作成され、共有モデルを使用するルートXMLMenuModel Beanも作成されます。共有モデルのマネージドBeanは、起動時にメニュー・ツリーが解析されると、ルート・メニュー・モデルのマネージドBeanに自動的に組み込まれます。

- Var: commandNavigationItemコンポーネントに必要なデータをメニュー・モデルから取得するのに使用するテキストを設定します。
実行時に階層が作成されて各ノードにスタンプが設定されると、EL式を使用して特定可能なvar属性に現在のノードのデータがコピーされます。varプロパティを使用して、このプロパティに使用する名前をEL式に指定します。

ヒント:

ページまたはアプリケーションのnavigationPaneコンポーネントで実行したように、breadCrumbsコンポーネントのvar属性に同じ値を使用できます。

4. 「コンポーネント」ウィンドウの「レイアウト」パネルの「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・アイテム」をドラッグしてbreadCrumbsコンポーネントのnodeStampファセットの中にドロップします。

注意:

breadCrumbsコンポーネントのnodeStampファセットは、breadCrumbsコンポーネントのvalue属性に指定されたメニュー・モデルに応じて、表示するリンクを決定します。breadCrumbsコンポーネントのvalue属性に、レンダリングするメニュー・モデルを指定しない場合は、実行時にリンクが表示されません。スタンプ設定が不要なためメニュー・モデルを使用しない場合は、breadCrumbsコンポーネントにnodeStampファセットを使用しないでください。

5. (必要な情報が含まれるメタデータを持つ)メニュー・モデルを参照するEL式を使用して、対応する値がメタデータに保持される残りの属性に値を設定します。手順3で、値がメタデータで保持されている対応するitemNode要素の名前とともに、親のbreadCrumbsコンポーネントに設定したvar属性の値を使用してこれらの値にアクセスします。表20-6に、対応する値がメタデータにあるナビゲーション・アイテムの属性を示します。
たとえば、breadCrumbsコンポーネントのvar属性をmenuNodeに設定した場合、action属性の値のEL式として#{menuNode.doAction}を使用します。これは、各ノードのメタデータに設定されているactionプロパティに解決されます。

例20-16 XMLMenuModelにバインドされたbreadCrumbsコンポーネント

<af:breadCrumbs var="menuNode" value="#{root_menu}">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"/>
</f:facet>
</af:breadCrumbs>

20.7.5 メニュー・モデルでのmenuBarコンポーネントの使用方法

第16章「メニュー、ツールバーおよびツールボックスの使用方法」で説明されているように、menuBarおよびmenuコンポーネントは、通常、アプリケーションで変更やアクションを実行するためにユーザーがクリックするメニューの編成および作成に使用されます。可能な場合は、menuBarコンポーネントをXMLMenuModel実装やマネージドBeanとともに使用し、ページ階層を作成します。breadCrumbsまたはnavigationPaneコンポーネント同様、menuBarがルートXMLMenuModelマネージドBeanにバインドされている場合は、nodeStampファセットにcommandNavigationItemコンポーネントを1つ使用して、ページ階層をナビゲートするためのメニュー項目を動的に作成します。

Webサイトのページ階層を表すのに、タブ・ナビゲーション・システム(navigationPaneコンポーネントまたはpanelTabbedコンポーネントを使用)では不十分である場合は、menuBarコンポーネントを使用してナビゲーション・バーにメニューおよびサブメニューを表示します。たとえば、ユーザーが参照するショッピング・カテゴリが多数あるWebストア・アプリケーションでは、すべてのカテゴリやサブカテゴリをタブ、サブタブ、バーおよびリストにレンダリングするのではなく、トップレベルのメニューをバーに横方向に配置することをお薦めします。menuBarがメニュー・モデルにバインドされている場合、サブメニューは、ユーザーがトップレベルのメニューまたはサブメニュー項目にカーソルを置いた場合にのみ表示されます。この配置により画面の表示領域を削減できるだけでなく、ユーザーも階層のトップから最も下のレベルまで、ワンクリックで簡単にナビゲートできます。

メニュー・モデルにバインドされていないmenuBarコンポーネントとは異なり、メニュー・モデルにバインドされているmenuBarは連結の解除ができず、ツールバーに使用することもできません。また、menuBarが同じページのメニュー・モデルにバインドされているナビゲーション・タブを使用しないでください。どちらも使用する必要がある場合は、menuBarコンポーネントを必ずナビゲーション・タブの上に配置してください。ただし、breadCrumbsコンポーネントが、ブレッドクラム・リンクを表示するページの同じモデルにバインドされている場合は、メニュー・モデルにバインドされているmenuBarを使用できます。

メニュー・バーのスタイルを設定する場合は、decorativeBoxコンポーネントを作成します。作成するには、「コンポーネント」ウィンドウの「レイアウト」パネルから「装飾ボックス」をJSFページにドラッグ・アンド・ドロップします。テーマを設定して、タブの表示方法を決定します。有効な値は次のとおりです。

- default

- light

- medium

- dark

値はそれぞれ、コンポーネントのテーマ値が指定されたときにADFスキンによってアプリケーションに適用されるルック・アンド・フィールを表します。テーマをどのように表示するかを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

メニュー・モデルを使用した横方向のメニュー・バーを作成する手順:

1. 「コンポーネント」ウィンドウの「メニューおよびツールバー」パネルから、「メニュー・バー」をJSFページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、「メニュー・モデル」セクションを開いて次の値を設定します。

- Value: faces-config.xmlファイル内で構成されている、ルートXMLMenuModelマネージドBeanに設定します。これが、breadCrumbsコンポーネントがバインドされるのと同じBeanです。

注意:

value属性が参照できるのは、共有ノードを介して参照されるメニュー・モデルではなく、ルート・メニュー・モデルのみです。たとえば、(例20-10に示されているように)メインのXMLMenuModel要素に共有ノードを使用している場合は、JDeveloperにより、その共有ノードにマネージドBean構成が作成され、共有モデルを使用するルートXMLMenuModel Beanも作成されます。共有モデルのマネージドBeanは、起動時にメニュー・ツリーが解析されると、ルート・メニュー・モデルのマネージドBeanに自動的に組み込まれます。

- Var: commandNavigationItemコンポーネントに必要なデータをメニュー・モデルから取得するのに使用するテキストを設定します。
実行時に階層が作成されて各ノードにスタンプが設定されると、EL式を使用して特定可能なvar属性に現在のノードのデータがコピーされます。varプロパティを使用して、このプロパティに使用する名前をEL式に指定します。

ヒント:

ページまたはアプリケーションのbreadCrumbsコンポーネントで実行したように、menuBarコンポーネントのvar属性に同じ値を使用できます。

3. 「コンポーネント」ウィンドウの「レイアウト」パネルの「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・アイテム」をmenuBarコンポーネントのnodeStampファセットにドラッグ・アンド・ドロップします。

注意:

menuBarコンポーネントのnodeStampファセットは、menuBarコンポーネントのvalue属性に指定されたメニュー・モデルに応じて、表示するリンクを決定します。menuBarコンポーネントのvalue属性に、レンダリングするメニュー・モデルを指定しない場合は、実行時にメニュー項目が表示されません。

4. (必要な情報が含まれるメタデータを持つ)メニュー・モデルを参照するEL式を使用して、対応する値がメタデータに保持される残りの属性に値を設定します。手順2で、値がメタデータで保持されている対応するitemNode要素の名前とともに、親のmenuBarコンポーネントに設定したvar属性の値を使用してこれらの値にアクセスします。表20-6に、対応する値がメタデータにあるナビゲーション・アイテムの属性を示します。
たとえば、menuBarコンポーネントのvar属性をmenuNodeに設定した場合、action属性の値のEL式として#{menuNode.doAction}を使用します。これは、各ノードのメタデータに設定されているactionプロパティに解決されます。

例20-17 XMLMenuModelにバインドされたmenuBarコンポーネント

<af:menuBar var="menuNode" value="#{root_menu}">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"/>
</f:facet>
</af:menuBar>

20.7.6 実行時に行われる処理: メニュー・モデルによるページ階層の作成方法

メニュー・モデルにバインドされたコンポーネント(navigationPane、breadCrumbsまたはmenuBar)のvalue属性は、XMLMenuModel要素のマネージドBeanを参照します。そのマネージドBeanがリクエストされると、次の処理が実行されます。

- faces-config.xmlファイルのmanaged-property要素に指定されているように、XMLMenuModelクラスのsetSource()メソッドが、モデルのメタデータの場所を使用してコールされます。

- パーサー(SAXParser)が、メタデータへのInputStreamオブジェクトを使用できるようになります。ナビゲーション・アイテムのメタデータが解析され、MenuContentHandlerメソッドへのコールが実行されます。

- MenuContentHandlerにより、次のようにして、ナビゲーション・メニューのツリー構造がListオブジェクトとして作成されます。

- メタデータ内のノードの処理が開始される際に、startElement()メソッドがコールされます。

- ノードの処理の終了時に、endElement()メソッドがコールされます。

- 各ノードが処理されると、メニュー・モデルのページ階層を構成するナビゲーション・メニュー・ノードのListが作成されます。

- ナビゲーション・メニュー・ノードのリストから、TreeModelオブジェクトが作成されます。

- TreeModelオブジェクトからXMLMenuModelオブジェクトが作成されます。

groupNode要素のidref属性に複数の子IDがある場合は、次の処理が実行されます。

- IDはリストされている順序で処理されます。現在のIDで子ノードが検出されない場合は次のIDが使用され、これが繰り返されます。

- idrefリストの現在のIDに一致する子ノードが検出されると、そのノードでは、rendered属性がtrueに設定されていること、disabled属性がfalseに設定されていること、readOnly属性がfalseに設定されていること、およびvisible属性がtrueに設定されていることが確認されます。条件のいずれかが一致しない場合は、idrefリストの次のIDが使用され、これが繰り返されます。

- 条件に一致する最初の子ノードは、アクション結果または宛先のURIの取得に使用されます。条件に一致する子ノードが検出されない場合は、エラーが記録されます。ただし、UIにはエラーは表示されません。

- 条件に一致する最初の子ノードが別のgroupNode要素の場合、処理はその子に続行されます。処理は、actionまたはdestination属性を含むitemNode要素が出現すると止まります。

- itemNode要素にaction属性がある場合は、ユーザーの選択によりPOSTアクションが開始され、アクション結果を介してナビゲーションが実行されます。itemNode要素にdestination属性がある場合は、ユーザーの選択によりGETアクションが開始され、destination値を使用して直接ナビゲーションが実行されます。

XMLMenuModelクラスには、ナビゲーション・メニュー・システムを使用してナビゲートすると、ナビゲーション・メニューの項目(タブやバーなど)が適切に強調表示および有効にされるモデルがあります。モデルはlabel、doAction、およびナビゲーション・アイテムの動的な生成に使用されるその他のプロパティの値でもインスタンス化されます。

XMLMenuModelクラスではレンダリングは行われません。モデルにバインドされたコンポーネントでは、コールからgetFocusRowKey()メソッドへの戻り値を使用して、レベルのナビゲーション・メニュー項目がページにレンダリングされます。

メニュー・モデルにバインドされたコンポーネントのnodeStampファセットに格納されたcommandNavigationItemコンポーネントは、各ナビゲーション・アイテムのラベル・テキストおよびアクション結果を表示します。nodeStampファセットがスタンプ設定されるたびに、現在のナビゲーション・アイテムのデータが到達可能なELプロパティにコピーされます。その名前は、nodeStampファセットを格納するnavigationPaneコンポーネントのvar属性によって定義されます。nodeStampは、到達可能なELプロパティからさらにプロパティを取得して、各アイテムのデータを表示します。ナビゲーション・メニューがレンダリングを完了すると、このプロパティは削除されます(または元の値に戻されます)。ユーザーがナビゲーション・アイテムを選択すると、デフォルトのJSF actionListenerメカニズムでは、アクション結果文字列または宛先URIを使用してページ・ナビゲーションを処理します。

nodeStampファセットとともに、XMLMenuModelクラスも、ナビゲーション・アイテムを選択されたものとしてレンダリングするかどうかを制御します。前述のように、XMLMenuModelオブジェクトは、各ノードのviewId属性情報を含むツリー・モデルから作成されます。XMLMenuModelクラスには、どのページにフォーカスを置くかを決定するメソッドgetFocusRowKey()があり、ノードにフォーカス・パスがある場合は、選択されたものとして自動的にノードをレンダリングします。最も単純なgetFocusRowKey()メソッドでは、次の内容が実行されます。

- 現在のviewId属性が取得されます。

- 重複するviewId値の解決に使用される内部マップのID、およびメニュー・モデルの作成時にツリーをトラバースすることにより作成されたviewIdFocusPathMapオブジェクトのIDと、viewId属性の値が比較されます。

- 現在のviewId属性があるノードへのフォーカス・パスが返されるか、現在のviewId属性値が検出されない場合にはnullが返されます。

ノードのviewId属性は、フォーカスrowKeyオブジェクトの特定に使用されます。モデルの各項目には、現在のrowKeyオブジェクトに基づいてスタンプが設定されます。ユーザーがナビゲートして現在のviewId属性が変更されると、モデルのフォーカス・パスも変更されて、新しいナビゲーション・アイテムのセットがアクセスされます。

20.7.7 カスタム属性の使用に関する必知事項

作成したカスタム属性を表示できるのはitemNode要素のみです。itemNode要素を追加してカスタム属性の値にアクセスできるようにするには、次のようにしてメニュー・モデルからツリーを取得する必要があります。

- メニュー・モデルのgetWrappedData()メソッドをコールします。

- getFocusRowKey()メソッドをコールして、現在のフォーカス・パスを取得します。

- このフォーカス・パスを使用してツリーをトラバースし、フォーカス・パスのノードのリストを返します。

- getCustomProperty() APIをコールし、カスタム属性に関してこれらのノードを1つ以上テストします。

例20-18に、必要なコードの例を示します。

例20-18 XMLMenuModelからのカスタム属性へのアクセス

/**
* Returns the nodes corresponding to a focus path
*
* @param tree
* @param focusPath
*/
public List getNodesFromFocusPath(TreeModel tree, ArrayList focusPath)
{
if (focusPath == null || focusPath.size() == 0)
return null;

// Clone the focusPath cause we remove elements
ArrayList fp = (ArrayList) focusPath.clone();

// List of nodes to return
List nodeList = new ArrayList<Object>(fp.size());

// Convert String rowkey to int and point to the
// node (row) corresponding to this index
int targetNodeIdx = Integer.parseInt((String)fp.get(0));
tree.setRowIndex(targetNodeIdx);

// Get the node
Object node = tree.getRowData()

// put the Node in the List
nodeList.add(node);

// Remove the 0th rowkey from the focus path
// leaving the remaining focus path
fp.remove(0);

// traverse into children
if (   fp.size() > 0
&& tree.isContainer()
&& !tree.isContainerEmpty()
)
{
tree.enterContainer();

// get list of nodes in remaining focusPath
List childList = getNodesFromFocusPath(tree, fp);

// Add this list to the nodeList
nodeList.addAll(childList);

tree.exitContainer();
}

return nodeList;
}

public String getElementLabel(XMLMenuModel model, Object myVal, String myProp)
{
TreeModel tree = model.getWrappedData();

Object node = findNodeByPropertyValue(tree, myVal, myProp);

FacesContext context = FacesContext.getCurrentInstance();
PropertyResolver resolver = context.getApplication().getPropertyResolver();

String label = (String) resolver.getValue(node, _LABEL_ATTR);

return label;
}

public Object findNodeByPropertyValue(TreeModel tree, Object myVal, String myProp)
{
FacesContext context = FacesContext.getCurrentInstance();
PropertyResolver resolver = context.getApplication().getPropertyResolver();

for ( int i = 0; i < tree.getRowCount(); i++)
{
tree.setRowIndex(i);

// Get a node
Object node = tree.getRowData();

// Get the value of the attribute of the node
Obect propVal = resolver.getValue(node, myProp);

if (propVal == myVal)
{
return node;
}

if (tree.isContainer() && !tree.isContainerEmpty())
{
tree.enterContainer();
node = findNodeByPropertyValue(tree, myVal, myProp);

if (node != null)
return node;

tree.exitContainer();
}guap
}
return null;
}

20.8 単純なナビゲーション階層の作成

注意:

アプリケーション階層が複雑で、深くネストされたページが含まれている場合は、メニュー・モデルを使用したナビゲーション・システムの作成がより効率的です。詳細は、20.7項「メニュー・モデルを使用したページ階層の作成」を参照してください。

20.6項「ページ階層へのナビゲーション・アイテムの使用」では、トップレベルのルート・ノードであるHomeの下に3つのレベルのリンクがある単純なページ階層について説明しています。図20-16および図20-17は、navigationPaneコンポーネントおよび個々のcommandNavigationItemコンポーネントを使用して図20-10に示すページ階層のビューを作成した場合に、ユーザー・インタフェースがどのように表示されるかを表す例です。

図20-16 View Employeeページから使用可能なナビゲーション・アイテム

手動で階層を作成する場合には、各ページのフォーカス・パス(ページが存在する階層内の正確な場所)を確認し、各ページに必要なnavigationPaneとcommandNavigationItemコンポーネントの正確な数、ならびにユーザーがページを表示した際に選択済として構成する必要があるコンポーネントを確認します。たとえば、「View Employee」ページが表示されている図20-16では、navigationPaneコンポーネントが3つ必要です。第1レベルのタブに加え、「Employee Data」の第2レベルの子のバーのみが必要で、「Employee Data」タブおよび「View Employee」バーのみが選択済としてレンダリングされます。

同様に、「Health」ページが表示されている図20-17では、「Benefits」の子のバーのみが必要で、「Benefits」タブと「Insurance」バーを選択済として構成する必要があります。また、このページには、「Insurance」の下に子ノードを作成しますが、ページの端に縦方向のリストとして表示させることが可能です。縦方向のリストにある「Health」アイテムは選択済として構成され、「Health」ページのコンテンツは、縦方向のリストの右側である中央部分に表示されます。

図20-17 「Health」ページから使用可能なナビゲーション・アイテム

使用するナビゲーション・アイテムのタイプ(タブ、バー、リストなど)に関係なく、navigationPaneコンポーネントを使用して階層リンクの1レベルを表し、各navigationPaneコンポーネント内の一連のcommandNavigationItem子コンポーネントにより、実際のナビゲーション・アイテムが提供されます。たとえば、図20-17において、第1レベルのタブ(「Benefits」と「Employee Data」)の実際のリンク、第2レベルのバー(「Insurance」と「Paid Time Off」)、およびリストの「Health」と「Dental」のリンクはそれぞれ、commandNavigationItemコンポーネントにより表示されます。バーの下に、現在のページのフォーカス・パスを示すブレッドクラム・リンクを表示するには、必要な数のcommandNavigationItem子コンポーネントを含むbreadCrumbsコンポーネントを使用します。

20.8.1 単純なページ階層の作成方法

ナビゲーション階層に含まれるページ数が少なく、階層があまり深くない場合は、階層を手動で作成することもできます。これには、ナビゲーション・ルールおよびナビゲーション・ケースの作成、navigationPaneコンポーネントを使用した階層の作成、およびcommandNavigationItemコンポーネントを使用したリンクの作成が含まれます。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.8項「単純なナビゲーション階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

手動でナビゲーション階層を作成する手順:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを展開し、faces-config.xmlをダブルクリックします。

2. ソース・エディタで、グローバルなJSFナビゲーション・ルールを1つ作成し、この中で、ページ階層のすべてのノード(つまりページ)のナビゲーション・ケースを指定します。

たとえば、図20-10に表示されているページ階層には、10個のノードがあります(これにはグローバルのHelpノードも含まれます)。この場合、例20-19に示すように、faces-config.xmlファイルの1つのグローバル・ナビゲーション・ルール内に10のナビゲーション・ケースを作成します。

各ナビゲーション・ケースに、一意の結果文字列と、指定された文字列に一致する結果値がナビゲーション・システムによって返された場合に表示するJSFページへのパスを指定します。

例20-19 faces-config.xml内のページ階層のグローバル・ナビゲーション・ルール

<navigation-rule>
<navigation-case>
<from-outcome>goHome</from-outcome>
<to-view-id>/home.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHelp</from-outcome>
<to-view-id>/globalhelp.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goEmp</from-outcome>
<to-view-id>/empdata.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goBene</from-outcome>
<to-view-id>/benefits.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goIns</from-outcome>
<to-view-id>/insurance.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goPto</from-outcome>
<to-view-id>/pto.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goView</from-outcome>
<to-view-id>/viewdata.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goCreate</from-outcome>
<to-view-id>/createemp.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHealth</from-outcome>
<to-view-id>/health.jsf</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goDental</from-outcome>
<to-view-id>/dental.jsf</to-view-id>
</navigation-case>
</navigation-rule>

JDeveloperにおけるナビゲーション・ケースの作成方法の詳細は、3.3項「ページ・フローの定義」を参照してください。

3. すべての階層ノードにJSFページを作成します。ナビゲーション・タブのスタイルを設定する場合は、decorativeBoxコンポーネントを作成します。作成するには、「コンポーネント」ウィンドウの「レイアウト」パネルから「装飾ボックス」を各ページにドラッグ・アンド・ドロップします。テーマを設定して、タブの表示方法を決定します。有効な値は次のとおりです。

- default

- light

- medium

- dark

値はそれぞれ、コンポーネントのテーマ値が指定されたときにADFスキンによってアプリケーションに適用されるルック・アンド・フィールを表します。テーマをどのように表示するかを変更できます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。ページ・テンプレートを使用してJSFページの位置設定やビジュアルなスタイル設定を行うには、10.3項「ページ・テンプレートの使用」を参照してください。

4. 「コンポーネント」ウィンドウの「レイアウト」パネルの「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・ペイン」を各ページにドラッグ・アンド・ドロップします。navigationPaneコンポーネントを、ページの階層の各レベルにドラッグ・アンド・ドロップします。
たとえば、図20-17のような「Health」ページを作成するには、navigationPaneコンポーネントを4つドラッグ・アンド・ドロップします。Healthページでは、すでにページのルック・アンド・フィールを作成するためのレイアウト・コンポーネントが含まれているテンプレートの特定の領域に、コンポーネントをドロップします。

5. navigationPaneコンポーネントのそれぞれについて、「プロパティ」ウィンドウの「共通」セクションを開いて、次に示すナビゲーション・アイテムのタイプの1つを「ヒント」ドロップダウン・リストで選択します。これによって、navigationPaneコンポーネントをどのように表示するかが決まります。

- bar: バーで分割されたナビゲーション・アイテムを表示します。図20-17の「Insurance」および「Paid Time Off」リンクなどがこれに当たります。

- buttons: グローバル領域のバーで分割されたナビゲーション・アイテムを表示します。図20-17の「Home」および「Help」リンクなどがこれに当たります。

- choice: 関連付けられたドロップダウン・アイコンがクリックされると、ポップアップ・リストにナビゲーション・アイテムが表示されます。navigationPaneコンポーネントのicon属性に値を含める必要があり、title属性を使用してドロップダウン・リストにラベルを関連付けることができます。

- list: ナビゲーション・アイテムが箇条書きリストで表示されます。図20-17の「Health」および「Dental」リンクなどがこれに当たります。

- tabs: ナビゲーション・アイテムがタブで表示されます。図20-17の「Benefits」および「Employee Data」タブなどがこれに当たります。

6. navigationPaneコンポーネントのそれぞれについて、様々なリンクを表すのに必要な数のcommandNavigationItemコンポーネントを追加します。追加するには、「コンポーネント」ウィンドウの「レイアウト」パネルにある「対話型コンテナおよびヘッダー」グループから、「ナビゲーション・アイテム」をドラッグ・アンド・ドロップします。必要な各リンクのnavigationPaneコンポーネントの子として、「ナビゲーション・アイテム」をドロップします。
たとえば、図20-17のような「Health」ページを作成するには、各navigationPaneコンポーネントに2つずつ、合計8つのcommandNavigationItemコンポーネントを使用します。

パフォーマンスのヒント:

実行時、使用可能なブラウザの領域が、ナビゲーション・ペインのタブやバーのコンテンツ、またはブレッドクラムのコンテンツの表示に必要な領域より少ない場合、表示されていない項目をユーザーが選択して表示できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。navigationPaneまたはbreadCrumbsコンポーネント内の子コンポーネントの数、および子の複雑さが、オーバーフローの項目のパフォーマンスに影響します。可能な場合は、オーバーフローしないように、navigationPaneまたはbreadCrumbsコンポーネントのサイズを設定する必要があります。

7. 各commandNavigationItemコンポーネントで、ナビゲーションを必要なページに設定します。「プロパティ」ウィンドウで、「共通」セクションを開き、「アクション」フィールドで、アクションの静的な結果文字列を指定するか、EL式を使用してアクション・メソッドを参照します。文字列を使用する場合は、手順2で作成したページのナビゲーション・ルールに設定されたナビゲーション・メタデータに一致する必要があります。メソッドを参照する場合は、必要な文字列がそのメソッドにより返される必要があります。

8. 「プロパティ」ウィンドウの「動作」セクションを開きます。ページがレンダリングされた直後にcommandNavigationItemコンポーネントを選択された状態で表示するには、「選択済」ドロップダウン・リストからtrueを選択し、そのようにしない場合はfalseを選択します。
実行時、ナビゲーション・アイテムがユーザーに選択されている場合は、そのコンポーネントのselected属性がselected="true"に変更され、外観を変更してアイテムが選択済であることをユーザーに示します。たとえば、図20-17では、「Benefits」タブ、「Insurance」バー、および「Health」リスト・アイテムが、背景色またはフォント・スタイルの変更によって選択済として表示されます。選択済のステータスを表示するためにコードを記述する必要はありません。属性値がtrueの場合は、アイテムのcommandNavigationItemコンポーネントのselected属性により、選択済のステータスの有効化が処理されます。

例20-20に、現在のページが「Health」の場合に使用可能なナビゲーション・アイテムの生成に使用されるコードを示します。HealthページはBenefitsページを経由してInsuranceページからアクセスされているため、これらの3つのリンクのcommandNavigationItemコンポーネントではselected="true"です。

例20-20 1つのページに個々のナビゲーション・アイテムを使用したサンプル・コード

<af:navigationPane hint="buttons">
<af:commandNavigationItem text="Home" action="goHome"/>
<af:commandNavigationItem text="Help" action="goHelp"/>
</af:navigationPane>
...
<af:navigationPane hint="tabs">
<af:commandNavigationItem text="Benefits" action="goBene"
selected="true"/>
<af:commandNavigationItem text="Employee Data" action="goEmp"/>
</af:navigationPane>
...
<af:navigationPane hint="bar">
<af:commandNavigationItem text="Insurance" action="goIns"
selected="true"/>
<af:commandNavigationItem text="Paid Time Off" action="goPto"/>
</af:navigationPane>
...
<af:navigationPane hint="list">
<af:commandNavigationItem text="Health" action="goHealth"
selected="true"/>
<af:commandNavigationItem text="Dental" action="goDental"/>
</af:navigationPane>

選択済の状態をプログラムで変更するには、バッキングBeanメソッドを記述してアクション・イベントを処理する必要があります。その後、例20-21に示すように、commandNavigationItemコンポーネントのactionListener属性のメソッドを参照します。

例20-21 選択済の状態を変更するためのactionListenerの使用

<!--  JSF Page Code ----->
<af:navigationPane hint="tabs">
<af:commandNavigationItem text="Benefits"
actionListener="#{myBean.navigationItemAction}"
partialSubmit="true"../>
.
</af:navigationPane>

<!-- Managed Bean Code ----->
public void navigationItemAction(ActionEvent event)
{
UIComponent actionItem = event.getComponent();
UIComponent parent = actionItem.getParent();
while (! (parent instanceof UIXNavigationHierarchy) )
{
parent = parent.getParent();
if (parent == null)
{
System.err.println(
"Unexpected component hierarchy, no UIXNavigationHierarchy found.");
return;
}
}

List<UIComponent> children = parent.getChildren();
for (UIComponent child : children)
{
FacesBean childFacesBean = ((UIXComponent) child).getFacesBean();
FacesBean.Type type = childFacesBean.getType();
PropertyKey selectedKey = type.findKey("selected");
if (selectedKey != null)
{
childFacesBean.setProperty(selectedKey, child==actionItem);
}
}
RequestContext adfContext = RequestContext.getCurrentInstance();
adfContext.addPartialTarget(parent);
}

20.8.2 breadCrumbsコンポーネントの使用方法

図20-16および図20-17の両方で、ページ階層におけるユーザーの現在の位置は、現在のページからルート・ページに戻るリンクのパスで示されています。ブレッドクラムとも呼ばれるリンクのパスは、2番目のバーの下、垂直のリスト(存在する場合)の上に表示されます。そのようなリンクのパスを作成するには、一連のcommandNavigationItemコンポーネントを子として含むbreadCrumbsコンポーネントを使用します。

始める前に:

ナビゲーション・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.8項「単純なナビゲーション階層の作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

手動でブレッドクラムを作成する手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルの「位置」グループから、「ブレッドクラム」をJSFページにドラッグ・アンド・ドロップします。

2. デフォルトでは、ブレッドクラム・リンクは水平に表示されます。レイアウトを縦に変更するには、「プロパティ」ウィンドウの「共通」セクションを開いて「向き」ドロップダウン・リストからverticalを選択します。

3. ブレッドクラム内のリンクごとに、commandNavigationItemコンポーネントを作成します。作成するには、「コンポーネント」ウィンドウの「レイアウト」パネルにある「対話型コンテナおよびヘッダー」グループから「ナビゲーション・アイテム」をbreadCrumbsコンポーネントに子としてドラッグ・アンド・ドロップします。最後の項目が現在のページを表します。

ヒント:

レンダラまたはクライアントのデバイス・タイプによっては、ブレッドクラムの最後のリンクが表示されない場合がありますが、commandNavigationItemコンポーネントを追加する必要があります。最後のブレッドクラム・リンクを表示するクライアントでは、現在のページに対応しているため、リンクは常に自動的に無効にされます。

4. 各commandNavigationItemコンポーネント(最後を除く)で、ナビゲーションを必要なページに設定します。「プロパティ」ウィンドウで、「共通」セクションを開き、「アクション」フィールドで、アクションの静的な結果文字列を指定するか、EL式を使用してアクション・メソッドを参照します。文字列を使用する場合は、手順2で作成した、ページのナビゲーション・ルール内で設定されているナビゲーション・メタデータに一致している必要があります(20.8.1項「単純なページ階層の作成方法」を参照)。メソッドを参照する場合は、必要な文字列をそのメソッドが返す必要があります。

たとえば、図20-17の「Health」ページに表示されているブレッドクラムを作成するには、commandNavigationItemコンポーネントを4つドラッグ・アンド・ドロップします(例20-22を参照)。

例20-22 個々の子commandNavigationItemのあるbreadCrumbsコンポーネント

<af:breadCrumbs>
<af:commandNavigationItem text="Home" action="goHome"/>
<af:commandNavigationItem text="Benefits" action="goBene"/>
<af:commandNavigationItem text="Insurance" action="goIns"/>
<af:commandNavigationItem text="Health"/>
</af:breadCrumbs>

20.8.3 ナビゲーション・タブの削除に関する必知事項

hint属性の値がtabsのnavigationPaneコンポーネントは、個々のタブを閉じられるように構成できます。これは、すべてのタブを閉じる、最後のタブを除いてすべて閉じる、またはタブを閉じないように構成できます。ナビゲーション・タブを削除するように構成されているときは、マウス・カーソルがタブの上に置かれると、閉じるアイコン(たとえば「X」)が各タブの端に表示されます。

hint="tabs"の場合にnavigationPaneコンポーネントでのタブの削除を有効化するには、次のようにします。

- navigationPane hint="tabs"のitemRemoval属性をallまたはallExceptLastに設定します。allExceptLastに設定されている場合は、1つを除くすべてのタブが閉じられます。これは、ユーザーがタブを閉じ、タブが1つのみ残ると、その最後の1つのタブは閉じられないことを意味します。

- タブの削除を実行するにはハンドラを実装します。ユーザーがタブを閉じると、タイプがremoveのItemEventが起動されます。このイベントの処理と実際のタブの削除、およびその他の必要な機能(警告ダイアログの表示や子コンポーネントの処理方法など)には、開発者が作成するコードで行う必要があります。イベントの詳細は、第6章「イベントの処理」を参照してください。ポップアップ・ダイアログおよびウィンドウの使用方法の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- commandNavigationItemコンポーネントのitemListener属性で、解決結果がハンドラ・メソッドとなるEL式を設定します。このハンドラ・メソッドが、実際のタブの削除を処理します(例20-23を参照)。

例20-23 タブ・アイテムを削除するためのitemListenerの使用

<!---- JSF Page Code ----->
<af:navigationPane hint="tabs" itemRemoval="all">
<af:commandNavigationItem text="Benefits" partialSubmit="true"
itemListener="#{closebean.handleCloseTabItem}"/>
...
</af:navigationPane>

// Managed Bean Code
import oracle.adf.view.rich.event.ItemEvent;
...
public void handleCloseTabItem(ItemEvent itemEvent)
{
if (itemEvent.getType().equals(ItemEvent.Type.remove))
{
Object item = itemEvent.getSource();
if (item instanceof RichCommandNavigationItem)
{
RichCommandNavigationItem tabItem = (RichCommandNavigationItem) item;
tabItem.setVisible(false);
// do other desired functionality here ...
}
}
}

20.8.4 ナビゲーション・タブのサイズに関する必知事項

デフォルトでは、navigationPaneコンポーネントのhint属性の値がtabsに設定されている場合にこのコンポーネントによってレンダリングされるタブのサイズは、ラベルとして使用されているテキストの長さによって決まります。このようなタブのサイズを設定するには、次に示すnavigationPaneコンポーネントの属性を構成します。

- maxTabSize: サイズをピクセル単位で設定します。タブのサイズがこれよりも大きくなることはありません。

- minTabSize: サイズをピクセル単位で設定します。タブのサイズがこれよりも小さくなることはありません。

- truncationStyle: ellipsisに設定すると、maxTabSizeに基づいて収まらないテキストを切り捨てた後に、省略記号が表示されます。noneに設定した場合は、テキストがタブに収まらないときにテキストの切捨てのみが行われます。

20.8.5 圧縮レイアウトのナビゲーション・タブに関する必知事項

内蔵のオーバーフロー・インジケータが表示されるのは、アプリケーション・ウィンドウが圧縮レイアウトの場合です。つまり、アプリケーション・ウィンドウの幅は、すべてのナビゲーション・タブを表示するのに十分ではありません。図20-18に示すように、ユーザーは、このようなオーバーフロー・インジケータによってレンダリングされたドロップダウン・リストで、移動先のナビゲーション・アイテムを選択できます。

図20-18 圧縮レイアウトのnavigationPaneコンポーネントのオーバーフロー・インジケータ

図20-18に示すようにオーバーフロー・インジケータを表示する(デフォルトの動作)かわりに、navigationPaneコンポーネントの-tr-layout-typeスキニング・キーを構成すると、コンポーネントによってコンベア・ベルトがレンダリングされるようになります。ユーザーはこのベルトを左右にスクロールすると、非表示になっているタブを表示できます。また、-tr-layout-typeスキニング・キーを構成すると、すべてのナビゲーション・タブが1つのドロップダウン・リストの中にレンダリングされます(図20-19を参照)。この構成は、navigationPaneコンポーネントのhint属性がtabsに設定されている場合にのみ有効です。navigationPaneコンポーネントのhint属性が別の値に設定されている場合は、-tr-layout-typeスキニング・キーをデフォルト値(overflow)に設定してください。

例20-24に、アプリケーションのADFスキン・ファイルの-tr-layout-typeスキニング・キーを構成して、navigationPaneおよびpanelTabbedコンポーネントにコンベア・ベルトをレンダリングする方法を示します。スキニングの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

例20-24 -tr-layout-typeスキニング・キーの構成によるコンベア・ベルトのレンダリング

af|panelTabbed,
af|navigationPane {
-tr-layout-type: conveyor;
}

図20-19に、圧縮レイアウトでコンベア・ベルトをレンダリングするnavigationPaneコンポーネントを示します。

図20-19 圧縮レイアウトのnavigationPaneコンポーネントのコンベア・ベルト

20.9 trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成

注意:

アプリケーションでFusionテクノロジ・スタックまたはADF Controllerを使用する場合は、ADFタスク・フローを使用してアプリケーションのページ階層のナビゲーション・システムを作成してください。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のバインド・タスク・フローでのトレイン・コンポーネントの使用に関する項を参照してください。

ユーザーが特定の順序で表示する必要のある一連のページがある場合は、各ページにtrainコンポーネントを使用して、マルチステップ・プロセスをガイドする一連のナビゲーション・アイテムを表示することを検討してください。図20-20に、ページ上でレンダリングされたtrainコンポーネントの外観の例を示します。trainコンポーネントはマルチステップ・プロセスのステップ数を表示するだけでなく、プロセス全体との関連における現在のステップの位置も示します。

図20-20 trainコンポーネントによってレンダリングされたナビゲーション・アイテム

trainコンポーネントは、トレイン・ストップとして表される構成済の各手順を、すべてのストップが線でつながった状態でレンダリングします。各トレイン・ストップにはイメージ(四角いブロックなど)があり、そのイメージの下にラベルがあります。

各トレイン・ストップは、マルチステップ・プロセスの1つの手順または1ページに対応します。ユーザーは、イメージまたはラベルをクリックして新しいページを表示し、トレイン・ストップをナビゲートします。一般的に、トレイン・ストップは順番にたどる必要があります。つまり、ユーザーは最初に手順1にアクセスし、手順2に移動し、次に手順3というように移動します。ユーザーがまだ手順2に到達していないときに手順3にジャンプすることはできません。また、トレイン・ストップは、エンド・ユーザーがストップを順番に表示しなくてもよいように構成することも可能です。トレイン・ストップをこの方法で構成する場合は、直接表示できるすべてのトレイン・ストップが有効化されます。

図20-20に示すように、trainコンポーネントには、トレイン・ストップ用に少なくとも4つのスタイルが用意されています。ユーザーが表示している現在のストップは、トレイン・ストップのラベルが太字フォント・スタイルで示され、ストップには異なるイメージが使用されます。現在のストップより前の表示済のストップは、ラベルのフォントとイメージが異なる色で示されます。現在のストップの直後のストップは、有効化されて表示されます。表示されていないその他のストップは、グレー表示されます。

トレイン・ストップにはサブトレインを入れることができます。つまり、アクション・コンポーネント(たとえばbuttonコンポーネント)によって子のマルチステップ・プロセスを親ストップから開始し、サブプロセスの完了後に正しい親ストップに戻るように構成することができます。3番目のストップに2つのストップを含むサブプロセス・トレインがあるとします。ユーザーがサブプロセス・トレインの1番目のストップにナビゲートすると、図20-21に示すように、ADF Facesにより、サブプロセス・トレインの前後に親トレインを表すアイコンが表示されます。

図20-21 サブトレインの最初と最後の親トレインのアイコン

trainコンポーネントにtrainButtonBarコンポーネントを使用して、図20-22に示すように、「Back」および「Next」ボタンという形で、trainに追加のナビゲーション・アイテムを指定できます。これらの「Back」および「Next」ボタンを使用した場合、ユーザーは現在のストップから前後のトレイン・ストップにのみナビゲートできます。trainButtonBarコンポーネントは、trainコンポーネントなしでも使用できます。たとえば、表示されないストップがある場合、いくつかの条件付きロジックに基づいて、ストップを表示せずに「Back」および「Next」ボタンのみを表示することが必要な場合があります。

図20-22 trainButtonBarコンポーネントによりレンダリングされたナビゲーション・ボタン

どちらのtrainコンポーネントも、value属性をタイプorg.apache.myfaces.trinidad.model.MenuModelのトレイン・モデルにバインドすることで機能します。トレイン・メニュー・モデルには、次の処理に必要な情報が含まれています。

- 特定のトレイン動作の制御(トレインによりユーザーがどのようにトレイン・ストップを前進してマルチステップ・プロセスを完了するか)

- トレイン・ストップ・ラベルを含むトレイン・ストップおよび各ストップのステータスの動的な生成(現在ストップは選択、完了、未完了または無効のいずれの状態であるか)

注意:

ADFモデル・レイヤーおよびADFコントローラを使用しているアプリケーションでは、このナビゲーションおよび表示は異なる方法で設定および処理されています。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のバインド・タスク・フローでのトレイン・コンポーネントの使用に関する項を参照してください。

つまり、トレインのメニュー・モデルは、MenuModel抽象クラスを拡張することによって実装され、この抽象クラスはTreeModelクラスを拡張します(詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照)。MenuModelオブジェクトは、ページやアプリケーションのメニュー構造を表すことも、ページの階層やフローに含まれるストップを表すこともあります。

MenuModelクラスのインスタンスは特殊なTreeModelオブジェクトであるため、TreeModelオブジェクト内のノードはトレイン・ストップを表すことができます。trainコンポーネント内のトレイン・ストップを表すノード・インスタンスは、タイプTrainStopModelにすることも、任意のオブジェクト(TrainStopModelオブジェクトと同じEL構造を提供する場合)にすることもできます。ただし、TrainStopModelクラスは、結果、およびストップのラベルやimmediate、disabled、visited属性の状態を取得するために、関連するすべてのメソッドを公開する便利なインタフェースです。

MenuModelクラスは、ツリーのどの部分で現在のトレイン・ストップ(ページ)がフォーカスされているかを示すこともできます。MenuModelクラスのgetFocusRowKey()メソッドは、現在のviewIdのフォーカス・ページのrowKeyオブジェクトを返します。trainのメニュー・モデル実装にも固有のトレイン動作があります。この動作は、MenuModel抽象クラス、または便利なProcessMenuModelクラスを拡張することで実装できます。これらのどちらのクラスも次のパッケージから派生しています。

org.apache.myfaces.trinidad.model

トレイン動作は、現在のトレイン・ストップを表示している間に、ユーザーがトレインのその他のどのストップを表示できるかを制御します。

トレイン・ストップ・モデルを作成するには、TrainStopModel抽象クラスを拡張して抽象メソッドを実装することも、同じメソッド・シグネチャを使用して独自のクラスを作成することもできます。作成するクラスではrowDataオブジェクトを返す必要があります。このクラスのインスタンスは、(MenuModel実装の)基礎となるコレクションのrowDataオブジェクトを表します。

メニュー・モデルへのtrainコンポーネントのバインドは、value属性を使用して、XMLMenuModelクラスにnavigationPaneコンポーネントをバインドするのに似ています(20.7.3項「メニュー・モデルへのnavigationPaneコンポーネントのバインド方法」で説明されています)。ただし、TrainStopModel実装がrowDataオブジェクトを表している場合は、トレイン・ストップの作成に、nodeStampファセットとそのcommandNavigationItemコンポーネントを使用する必要はありません。ADF Facesにより、実行時にnodeStampファセットおよびcommandNavigationItemコンポーネントが動的に作成され、トレイン・ストップ・モデルのメソッドがcommandNavigationItemコンポーネントの適切なプロパティに自動的にバインドされます。例20-25に、トレインの簡略化されたバインディングを示します。

ヒント:

様々な場所のトレイン・ストップの情報を照合する必要がある場合は、nodeStampファセットおよびそれらのトレイン・ストップを表す個々のcommandNavigationItemコンポーネントを手動で作成する必要があります。詳細は、20.9.3項「JSFページでのトレイン・モデルへのバインド方法」を参照してください。

例20-25 簡略化されたトレイン・モデル・バインディング

<af:train value="#{simpleTrainModel}"/>

トレイン・モデルのMenuModel実装には、特定のトレイン動作が必要です。トレイン動作は、現在表示されているページに基づいてユーザーがアクセスできるページをどのように制御するかを定義します。ADF Facesでは、Plus OneおよびMax Visitedという2つのトレイン動作がサポートされています。

トレインに5つのページまたは5つのストップがあり、ユーザーはページ1からページ4まで順番にナビゲート済であるとします。ユーザーは現在、ページ4を表示しています。ここでは、トレイン・モデルに実装されているトレイン動作に応じて、ユーザーは次に進むことができます。

- Plus One動作: ユーザーはページ3またはページ5に移動できます。

- Max Visited動作: ユーザーはページ1から3(前に表示済)と、順序の次のページであるページ5を表示できます。ユーザーがページ2に移動した場合、ユーザーが表示できる次のページは、ページ1、3、または4です。順序の中で表示された最大のトレイン・ストップはページ4であるため、ユーザーはページ5を表示できません。

マルチステップ・プロセスのすべてのページにトレインを定義および使用する手順:

- トレインにJSFナビゲーション・ルールおよびナビゲーション・ケースを作成します。トレインのナビゲーション・ルールおよびそのナビゲーション・ケースの作成方法は、20.8.1項「単純なページ階層の作成方法」に似ています。グローバル・ナビゲーション・ルールを1つ作成し、この中で、トレイン内のすべてのトレイン・ストップのナビゲーション・ケースを指定します。

注意:

各トレイン・ストップが個別のページで、クライアント・ブラウザのURLがそれぞれの新しいページを参照するように設定する場合は、JSFナビゲーション・ルール内に定義する各ナビゲーション・ケースのredirect要素の値をtrueに設定します。部分ページ・レンダリングを有効化すると、別のURLが表示されます。redirect要素の詳細は、JavaServer Facesの仕様を参照してください。部分ページ・レンダリングの詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- 特定のトレイン動作を実装するトレイン・モデルを作成し、スタンプを設定するためのトレイン・ストップ項目を指定します。これには、トレイン・ストップ・モデル・クラスおよびメニュー・モデル・クラスの作成が含まれます。詳細は、20.9.1項「トレイン・モデルの作成方法」を参照してください。

- トレイン・モデルにマネージドBeanを構成します。詳細は、20.9.2項「トレイン・モデルへのマネージドBeanの構成方法」を参照してください。

- 各トレイン・ストップにJSFページを作成します。

- 各ページで、トレイン・モデルにtrainコンポーネントをバインドします。20.9.3項「JSFページでのトレイン・モデルへのバインド方法」を参照してください。trainButtonBarコンポーネントを同じトレイン・モデルにバインドすることもでき、このようにするとトレイン用のナビゲーション・ボタンをさらに表示できます。

20.9.1 トレイン・モデルの作成方法

トレイン・メニュー・モデルを定義するには、次のものを作成します。

- トレイン・ストップをレンダリングするためのデータを提供するトレイン・ストップ・モデル

- 特に、現在のトレイン・ストップを表示している間にユーザーがトレインのどのストップを表示できるか、どのストップを無効にする必要があるか、またはトレインを順番にナビゲートする必要があるかを制御する特定のトレイン動作(Max VisitedまたはPlus Oneなど)が指定されたMenuModel実装

ADF Facesを使用すると、次のような追加のpublicクラスが用意されているため、トレイン・メニュー・モデルの定義がより簡単になります。

- トレイン・ストップ・モデルを実装するための抽象クラスTrainStopModel。

- Max VisitedおよびPlus One動作を実装するクラスProcessMenuModelおよびProcessUtils。

ユーザーは、MenuModelをオーバーライドして独自のカスタム・トレイン動作を実装することも、既存のProcessMenuModelを拡張して特殊な動作を作成することもできます。

トレイン・モデル・クラスの例として、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.nav.richパッケージを参照してください。

始める前に:

トレイン・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.9項「trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

トレイン・モデルを作成する手順:

1. トレイン・ストップ・モデル・クラスを作成します。トレイン・ストップ・モデル・オブジェクトには、各トレイン・ストップにスタンプを設定するための行データが保持されます。作成するトレイン・ストップ・モデル実装では、トレインの各ストップのプロパティを設定および取得し、トレイン・ストップのレンダリングに必要なメソッドを定義する必要があります。トレイン・ストップのプロパティは、commandNavigationItemコンポーネントのプロパティに対応します。このため、例20-25に示すように、簡略化されたバインディングを使用できます。
または、抽象クラスTrainStopModelを拡張して、サブクラスの抽象メソッドを実装できます。

ELにより自動的にバインドされるcommandNavigationItemコンポーネントのプロパティを次に示します。

- action: 静的なアクション結果、またはアクション結果を返すアクション・メソッドへの参照。結果は、JSFのデフォルトのActionListenerメカニズムを介して、ページ・ナビゲーションに使用されます。

- disabled: トレイン・ストップを非対話型とするかどうかを示すブール値。使用するトレイン動作が、このプロパティ値に影響することに注意してください。詳細は、手順2を参照してください。

- immediate: データ検証を実行する必要があるかどうかを決定するブール値。使用するトレイン動作が、このプロパティ値に影響することに注意してください。詳細は、手順2を参照してください。

- messageType: トレイン・ストップ・イメージ上のメッセージ・アラート・アイコンを指定する値。使用可能な値は、none、error、warning、infoおよびcompleteです。メッセージの詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- shortDesc: クライアント・ユーザー・エージェントにより、トレイン・ストップのツールチップ・ヘルプ・テキストの表示に一般的に使用される値。

- showRequired: 必要な値がそのトレイン・ストップ・ページに含まれていることを示すために、トレイン・ストップの隣にアスタリスクを表示するかどうかを決定するブール値。

- textAndAccessKey: トレイン・ストップに表示するラベル・テキストと、使用するアクセス・キーの両方を設定する単一の値。

- visited: トレイン・ストップがすでに表示済であるかどうかを示すブール値。使用するトレイン動作が、このプロパティ値に影響することに注意してください。詳細は、手順2を参照してください。

2. MenuModelクラスに基づいてクラスを作成し、トレイン・モデルの構成を簡略化します。

トレイン・モデルのMenuModel実装には、特定のトレイン動作が必要です。org.apache.myfaces.trinidad.modelパッケージのProcessMenuModelクラスは、Plus OneおよびMax Visitedという2つのトレイン動作をサポートするMenuModelクラスの参照実装です。トレイン・モデルにトレイン動作を実装するには、ProcessMenuModelクラスを拡張するか独自のクラスを作成できます。

トレイン・モデル・クラスで、getFocusRowKey()メソッド(MenuModelクラスを参照)をオーバーライドし、トレイン動作(ProcessMenuModelクラスおよびProcessUtilsクラスを参照)を実装します。

ProcessMenuModelクラスに指定されているトレイン動作は、commandNavigationItemコンポーネントのvisited、immediate、およびdisabledプロパティに影響があります。

visited属性をtrueに設定するのは、トレインのそのページが表示済の場合のみです。ProcessMenuModelクラスでは、visited属性の値の決定に次のロジックが使用されます。

- Max Visited: max visitedストップとは、現在のセッション内でユーザーがアクセス済のストップのうち、最も先にあるものです。visited属性は、ストップがmax visitedストップよりも前であるか、max visitedストップそのものである場合にtrueに設定されます。

- Plus One: Plus Oneストップでは、表示された最も進んでいるストップは追跡されません。現在のストップ、または現在のストップの前のストップでは、visited属性がtrueに設定されます。

現在のページのデータを検証する必要がない場合は、immediate属性をtrueに設定する必要があります。前述のPlus One動作のページ4に、検証が必要なデータがあるとします。ページ4に進んでページ2に戻った場合、ページ5に進むためにユーザーは後からページ4に戻る必要があります。これは、ページ4からページ1、2または3に戻る場合はページ4のデータを検証する必要はないが、ページ5に進む場合にはデータを検証する必要があることを意味します。immediate属性がどのように機能するかの詳細は、5.2項「immediate属性の使用」を参照してください。

ProcessMenuModelクラスでは、immediate属性の値の決定に次のロジックが使用されます。

- Plus One: immediate属性は、前のステップに対してはtrueに設定され、それ以外に対してはfalseに設定されます。

- Max Visited: 現在のページと、表示した最大ページが同じである場合、動作はPlus Oneシナリオと同じです。現在のページが表示された最大ページよりも前にある場合、immediate属性はfalseに設定されます。

注意:

ADFモデル・レイヤーを使用するアプリケーションでは、ページ定義ファイルのpageDefinition要素で、trueに設定されている場合に、ページのデータ検証をスキップする属性(SkipValidation)がサポートされています。データ検証を起動せずに、ユーザーがページからナビゲートできるようにするには、SkipValidationをtrueに設定します。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のpageNamePageDef.xmlを参照してください。

disabled属性をtrueに設定するのは、現在のページからそのページに移動できない場合のみです。ProcessMenuModelクラスでは、disabled属性の値の決定に次のロジックが使用されます。

- Plus One: 次に使用可能なページより先のページでは、disabled属性がtrueになります。

- Max Visited: 現在のストップと、表示した最大ページが同じである場合、動作はPlus One動作と同じです。現在のページが表示された最大ページよりも前にある場合、表示された最大ページより先のページではdisabledがtrueに設定されます。

ADF Facesのデフォルトでは、Max Visited動作が使用されるのはnull以外のmaxPathKey値がトレイン・モデルに渡されたときです。これは、この動作をサポートするために開発者が作成するマネージドBeanによって決定されます(詳細は、20.9.2項「トレイン・モデルへのマネージドBeanの構成方法」を参照してください)。maxPathKey値がnullの場合には、Plus One動作が使用されます。

20.9.2 トレイン・モデルへのマネージドBeanの構成方法

Arraylistオブジェクトに個々のトレイン・ストップを収集するには、トレイン・モデルにマネージドBeanを使用しますが、これはtrainコンポーネントのvalue属性にバインドするためにメニュー・モデルに挿入されるツリー・モデルになります。モデルへの挿入に適切な値でBeanをインスタンス化し、トレイン内の各トレイン・ストップまたはページにマネージドBeanも構成する必要があります。

始める前に:

トレイン・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.9項「trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

トレイン・モデルにマネージドBeanを構成する手順:

1. インストール時に設定する必要のあるプロパティ値が含まれるマネージドBeanをトレインの各ストップに構成し、ArrayListに渡すトレイン・ストップを作成します。
トレイン・ストップに子のサブプロセス・トレインがある場合は、各サブプロセス・トレイン・ストップにもマネージドBeanが必要です。

各Beanは、20.9.1項「トレイン・モデルの作成方法」で作成されたトレイン・ストップ・モデル・クラスのインスタンスである必要があります。例20-26に、faces-config.xmlファイル内のトレイン・ストップのためのサンプルのマネージドBeanコードを示します。

例20-26 すべてのトレイン・ストップのマネージドBean

<!-- First train stop -->
<managed-bean>
<managed-bean-name>train1</managed-bean-name>
<managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>viewId</property-name>
<value>/train.jsf</value>
</managed-property>
<managed-property>
<property-name>outcome</property-name>
<value>guide.train</value>
</managed-property>
<managed-property>
<property-name>label</property-name>
<value>First Step</value>
</managed-property>
<managed-property>
<property-name>model</property-name>
<value>trainMenuModel</value>
</managed-property>
</managed-bean>
...
<!-- Second train stop -->
<managed-bean>
<managed-bean-name>train2</managed-bean-name>
<managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>viewId</property-name>
<value>/train2.jsf</value>
</managed-property>
<managed-property>
<property-name>outcome</property-name>
<value>guide.train2</value>
</managed-property>
<managed-property>
<property-name>label</property-name>
<value>Second Step</value>
</managed-property>
<managed-property>
<property-name>model</property-name>
<value>trainMenuModel</value>
</managed-property>
</managed-bean>
...
<!-- And so on -->
...

マネージド・プロパティにより、トレイン・ストップ・モデル・オブジェクト(20.9.1項「トレイン・モデルの作成方法」の手順1で作成されたクラス)に値が設定されます。

viewId値は、ユーザーがトレイン・ストップをクリックした場合にナビゲートされるページへのパスおよびファイル名です。

outcomeプロパティ値は、JSFナビゲーション・ケースに一致するアクション結果文字列です。デフォルトのJSF ActionListenerメカニズムは、トレイン・ストップが選択された際のナビゲート先のビューとしてトレイン・ストップに関連付けられたページの選択に使用されます。

labelプロパティ値は、トレイン・ストップ・イメージの下に表示されるトレイン・ストップのラベル・テキストです。値は静的にすることも、リソース・バンドルの文字列に評価されるEL式にすることもできます。

modelプロパティ値は、トレイン・モデルのマネージドBean名です(例20-30を参照)。

トレイン・ストップに子のサブプロセス・トレインがある場合には、例20-27に示すように、マネージドBean構成にも、値式(#{train4a}など)でサブプロセス・トレイン・ストップのマネージドBean名をリストするプロパティ(childrenなど)を指定する必要があります。

例20-27 子のサブプロセス・トレインを含むトレイン・ストップのマネージドBean

<managed-bean>
<managed-bean-name>train4</managed-bean-name>
<managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>viewId</property-name>
<value>/train4.jsf</value>
</managed-property>
<managed-property>
<property-name>outcome</property-name>
<value>guide.train4</value>
</managed-property>
<managed-property>
<property-name>label</property-name>
<value>Fourth Step</value>
</managed-property>
<managed-property>
<property-name>children</property-name>
<list-entries>
<value-class>project1.DemoTrainStopModel</value-class>
<value>#{train4a}</value>
<value>#{train4b}</value>
<value>#{train4c}</value>
</list-entries>
</managed-property>
<managed-property>
<property-name>model</property-name>
<value>trainMenuModel</value>
</managed-property>
</managed-bean>

2. ArrayListオブジェクトのインスタンスであるマネージドBeanを構成し、トレイン・ツリー・モデルに渡すトレイン・ストップのリストを作成します。
例20-28に、トレイン・ストップのリストを作成するためのサンプルのマネージドBeanコードを示します。

例20-28 トレイン・リストのマネージドBean

<managed-bean>
<managed-bean-name>trainList</managed-bean-name>
<managed-bean-class>
java.util.ArrayList
</managed-bean-class>
<managed-bean-scope>
none
</managed-bean-scope>
<list-entries>
<value-class>project1.DemoTrainStopModel</value-class>
<value>#{train1}</value>
<value>#{train2}</value>
<value>#{train3}</value>
<value>#{train4}</value>
<value>#{train5}</value>
</list-entries>
</managed-bean>

list-entries要素には、トレインにストップが表示される順序でリストされた値式(#{train1}など)のトレイン・ストップ(サブプロセス・トレイン・ストップを除く)のマネージドBean名が含まれます。

3. マネージドBeanを構成して、トレイン・リストからトレイン・ツリー・モデルを作成します。
トレイン・ツリー・モデルは、サブプロセス・トレインのリストも含む、トレイン・リスト全体をラップします。トレイン・モデルのマネージドBeanは、子のサブプロセス・トレインのリストを表すプロパティ名と同一であるchildProperty値を使用して、インスタンス化する必要があります(例20-27を参照)。

例20-29 トレイン・ツリー・モデルのマネージドBean

<managed-bean>
<managed-bean-name>trainTree</managed-bean-name>
<managed-bean-class>
org.apache.myfaces.trinidad.model.ChildPropertyTreeModel
</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
<managed-property>
<property-name>childProperty</property-name>
<value>children</value>
</managed-property>
<managed-property>
<property-name>wrappedData</property-name>
<value>#{trainList}</value>
</managed-property>
</managed-bean>

childPropertyプロパティには、サブプロセス・トレインのある各トレイン・ストップの子のリスト・エントリの取得に使用するプロパティ名を定義します。

wrappedDataプロパティ値は、ステップ2でマネージドBeanにより作成された、ラップするトレイン・リスト・インスタンスです。

4. マネージドBeanを構成して、トレイン・ツリー・モデルからトレイン・モデルを作成します。
これが、各ページのtrainコンポーネントがバインドされるBeanです。トレイン・モデルは、トレイン・ツリー・モデルをラップします。トレイン・モデルのマネージドBeanは、トレイン・ストップに関連付けられたページを表すプロパティ名と同一であるviewIdProperty値を使用して、インスタンス化する必要があります。

例20-30に、トレイン・モデルのサンプルのマネージドBeanコードを示します。

例20-30 トレイン・モデルのマネージドBean

<managed-bean>
<managed-bean-name>trainMenuModel</managed-bean-name>
<managed-bean-class>
org.apache.myfaces.trinidad.model.ProcessMenuModel
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
<managed-property>
<property-name>viewIdProperty</property-name>
<value>viewId</value>
</managed-property>
<managed-property>
<property-name>wrappedData</property-name>
<value>#{trainTree}</value>
</managed-property>
<!-- to enable plusOne behavior instead, comment out the maxPathKey property -->
<managed-property>
<property-name>maxPathKey</property-name>
<value>TRAIN_DEMO_MAX_PATH_KEY</value>
</managed-property>
</managed-bean>

viewIdPropertyプロパティ値は、ユーザーがトレイン・ストップをクリックした場合にナビゲートされるページの指定に使用されるプロパティに設定されます。

wrappedDataプロパティ値は、ステップ3でマネージドBeanにより作成された、ラップするトレイン・ツリー・インスタンスです。

maxPathKeyプロパティ値は、Max Visitedトレイン動作を使用するためにトレイン・モデルに渡される値です。ADF Facesでは、トレイン・モデルにnull以外のmaxPathKey値が渡されるとMax Visited動作が使用されます。maxPathKey値がnullの場合には、Plus One動作が使用されます。

20.9.3 JSFページでのトレイン・モデルへのバインド方法

トレインの各ストップは、1つのJSFページに対応します。各ページに、trainコンポーネント、およびオプションでtrainButtonBarコンポーネントを1つずつ使用し、ユーザーがトレインを移動できるようにするボタンを作成します。

始める前に:

トレイン・コンポーネントの属性が、機能にどのように影響するかを理解しておくと役に立ちます。詳細は、20.9項「trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、20.1.2項「ナビゲーション・コンポーネントのその他の機能」を参照してください。

トレイン・コンポーネントをトレイン・モデルにバインドする手順:

1. 「コンポーネント」ウィンドウの「一般コントロール」パネルの「位置」グループから、「トレイン」をJSFページにドラッグ・アンド・ドロップします。オプションで、「トレイン・ボタン・バー」をドラッグ・アンド・ドロップします。

2. コンポーネントをバインドします。トレイン・モデルのMenuModel実装が、public抽象クラスoracle.adf.view.rich.model.TrainStopModelと同様にrowDataオブジェクトを返す場合は、簡略化された形態のトレイン・バインディングをtrainコンポーネントで使用できます(例20-31を参照)。

例20-31 メニュー・モデルにバインドされたtrainコンポーネントの簡略化された実装

<af:train value="#{trainMenuModel}"/>
<af:trainButtonBar value="#{trainMenuModel}"/>

trainMenuModel EL式は、トレイン・モデルのマネージドBean名です(例20-30を参照)。

簡略化されたバインディングを使用できない場合は、トレイン値をトレイン・モデルBeanにバインドし、トレインにnodeStampファセットを手動で追加する必要があります。さらに、例20-32に示すように、そのトレインにcommandNavigationItemコンポーネントを追加します。

例20-32 トレイン・ストップにバインドされたcommandNavigationItemコンポーネント

<af:train value="#{aTrainMenuModel}" var="stop">
<f:facet name="nodeStamp">
<af:commandNavigationItem
text="#{stop.label}"
action="#{stop.outcome}"
...
</af:commandNavigationItem>
</f:facet>
</af:train>

21 実行時のコンポーネントの決定

この章では、ADF Faces dynamicComponentをフォームや表とともに使用する方法と、これをサポートするためのAttributesModelを作成する方法を説明します。アプリケーションでFusionテクノロジ・スタック全体を使用する場合は、モデルは自動的に作成されるので、データ・コントロールを使用して動的コンポーネントを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた基本的なページの作成」および「ADFによるデータバインドされた表の作成」の章を参照してください。

この章は次の項で構成されています。

- 21.1項「実行時のコンポーネントの決定について」

- 21.2項「動的コンポーネントのモデルの作成」

- 21.3項「動的コンポーネントをフォームとしてページに追加する」

- 21.4項「動的コンポーネントを表としてページに追加する」

- 21.5項「動的コンポーネントでの検証および変換の使用」

- 21.6項「動的および静的のコンポーネントの同時使用」

21.1 実行時のコンポーネントの決定について

実行時にどのコンポーネントが必要になるかを、開発時に特定できないこともあります。たとえば、ビジネス・オブジェクトが保持する属性が有効であるのは特定の条件のときに限られており、その属性が必要なときにのみ表示されるようにしたい場合です。標準のコンポーネントを使用するときは、特定のフィールドを表示するかどうかを判定するために、複雑なロジックが必要になる可能性があります。

動的インタフェースが必要になるもう1つの例は、複数のページで同じデータ・ソースが使用されている場合です。オブジェクトの属性が変更される可能性が高い場合は、そのオブジェクトにバインドされているすべてのページに変更を加えることが必要になります。

ADF Facesには動的コンポーネントがあり(af:dynamicComponent)、どのコンポーネントを表示するか、およびその値を、実行時に決定することができます。このコンポーネントによって表示されるのは、レンダリングされたインスタンスそれぞれの、必要な属性のみです。さらに、関連付けられたビジネス・サービスに変更が加えられたときは、その変更が動的コンポーネントによって反映されるので、UIコードの変更は必要ありません。

動的コンポーネントは、フォームまたは表として使用できます。実行時に、必要なコンポーネントがフォームまたは表の中で、動的コンポーネントのかわりにレンダリングされます。どのコンポーネントがレンダリングされるかは、属性のデータ型に基づいて決定されます。たとえば、属性がString型の場合は、inputTextコンポーネントが使用されます。Date型の場合は、inputDateコンポーネントが使用されます。次に示すコンポーネントが動的コンポーネントでサポートされます。

- inputText

- inputDate

- inputListOfValues

- selectOneChoice

- selectManyChoice

- selectOneListbox

- selectManyListbox

- selectOneRadio

- selectBooleanRadio

- selectBooleanCheckbox

- selectManyCheckbox

フォームの場合は、動的コンポーネントはイテレータ・コンポーネントの中にラップされます。コレクションベース・コンポーネントと同様に、イテレータはコレクション全体にバインドされます。この場合のコレクションとは、AttributesModelオブジェクトの属性の中のコレクションです。イテレータは、モデルの各インスタンスのスタンプ処理を行い、現在のインスタンスのデータをvar属性にコピーします。動的コンポーネントは、各インスタンスのこのvar値にattributeModel属性を使用してアクセスし、その情報に基づいて、使用するコンポーネントのタイプとその構成方法および値を決定します。

たとえば、フォームを作成して従業員のデータを表示するとします(図21-1を参照)。

図21-1 動的コンポーネントを使用して作成されたフォーム

AttributesModelを作成し、表示する属性それぞれの情報をこの中に保持します。さらに、各インスタンスの値にアクセスする手段も作成します。その後で、この動的コンポーネントのみを使用してフォームを作成します(例21-1を参照)。

例21-1 フォームで使用されている動的コンポーネント

<af:panelFormLayout id="pf1">
<af:iterator value="#{TestDynCompBean.attributesModel.attributes}"
var="attr" id="dyit1">
<af:dynamicComponent value="#{TestDynCompBean.value[attr.name]}" id="dyipt3"
attributeModel="#{attr}"/>
</af:iterator>
</af:panelFormLayout>

静的な表の場合は、個々の列およびその列の中のコンポーネントが、設計時に静的にページ内で定義されます。動的な表の場合は、列の数とその列の中のコンポーネントの両方が実行時に動的に、次に示すコンポーネントを使用して定義されます。

- af:table: 表を定義します。値を取得する方法も、var属性を使用して定義されます(詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください)。

- af:iterator: 属性のコレクションを定義します。列1個と、各列の中のコンポーネント1個が属性ごとに作成されます。

- af:column: 列を定義します。この列は、属性ごとに1回スタンプされます。イテレータ内に属性が10個ある場合は、列は10個となり、すべての列が同じ列定義からスタンプされます。

- af:dynamicComponent: その列のコンポーネントを定義します。型や値などはその属性から取得されます。

例21-2に、表で使用されている動的コンポーネントを示します。

例21-2 表で使用されている動的コンポーネント

<af:table value="#{TestDynCompBean.values}" var="row"
varStatus="vs" rowSelection="single"
id="t1" width="100%">
<af:iterator value="#{TestDynCompBean.attributesModel.attributes}" id="itr1"
var="col">
<af:column headerText="#{col.label}" id="c1">
<af:dynamicComponent value="#{row[col.name]}"
attributeModel="#{col}" id="dc1"/>
</af:column>
</af:iterator>
</af:table>

動的コンポーネントを使用して、属性のグルーピングを作成することもできます。たとえば、動的コンポーネントを使用して作成するフォームに、従業員1人の属性を表示するとします。従業員情報(氏名、給与など)を1つのグループにまとめて、部署情報(部署名、部署番号など)を別のグループにまとめます。「Employee Info」というカテゴリと、「Department Info」というカテゴリを作成します。AttributesModelの中で、Employeeオブジェクトの属性を各カテゴリに割り当てます。これらのカテゴリは、AttributesModelオブジェクトのhierarchicalAttributesプロパティの中に保持されます。

グループをページ上で作成するには、ファセット2個を持つスイッチャ・コンポーネントを使用します。最初のファセットは、カテゴリの1つに属するすべての属性を処理し、2つ目のファセットは「フラット」グループ(つまり、どのカテゴリにも属していない属性)を処理します。

グループを使用するときは、メイン・イテレータはAttributesModelのattributesプロパティではなくhierarchicalAttributesプロパティにバインドされます。このプロパティで、ルート・レベルの属性が定義されます。イテレータがコレクションの内容を反復処理するときに、カテゴリの値はattrという名前の変数で保持されます。最初のグループでは、イテレータは変数attrにバインドされ、この反復処理を行い、ディスクリプタ(そのカテゴリに属する子属性のリスト)の値を変数nestedAttrで保持します。子動的コンポーネントは、この変数にアクセスして、レコードごとに表示するコンポーネントのタイプと値を特定します(例21-3を参照)。

例21-3 グループで使用されている動的コンポーネント

<af:panelFormLayout id="pf1">
<af:iterator value="#{TestDynCompBean.attributesModel.hierarchicalAttributes}"
var="attr" id="dyit1">
<af:switcher id="sw" facetName="#{attr.descriptorType}"
defaultFacet="ATTRIBUTE">
<f:facet name="GROUP">
<af:group id="gg" title="#{attr.label}">
<af:outputText value="#{attr.label}" id="ot2"/>
<af:iterator id="it2" value="#{attr.descriptors}" var="nestedAttr">
<af:dynamicComponent
value="#{TestDynCompBean.value[nestedAttr.name]}" id="ndync1"
attributeModel="#{nestedAttr}" />
</af:iterator>
</af:group>
</f:facet>
<f:facet name="ATTRIBUTE">
<af:dynamicComponent value="#{TestDynCompBean.value[attr.name]}"
id="iinerit1" attributeModel="#{attr}"/>
</f:facet>
</af:switcher>
</af:iterator>
</af:panelFormLayout>

メイン・イテレータは、attributeModel内のルート・レベル属性を反復処理します。ルート属性のうち、どのグループにも属していないもの(つまり、Attributeタイプのルート属性)については、その属性に対応する動的コンポーネントがATTRIBUTEファセット内に作成されます。ルート属性のうち、その下に属性があるもの(つまり、Groupタイプのルート属性)については、その属性がGROUPファセットに追加されます。そのファセットの中で、別のイテレータがそのグループ内の標準属性のそれぞれを反復処理し、標準属性のそれぞれに基づいて動的コンポーネントを作成します。

21.2 動的コンポーネントのモデルの作成

AttributesModelクラスは属性のコレクションであり、各属性はBaseAttributeDescriptorオブジェクトによって表現されます。このオブジェクトはメタデータを保持しており、動的コンポーネントはこのメタデータを使用してデータの表示方法を決定します。たとえば、コンポーネントのタイプ、名前、ラベル、説明です。開発者は、BaseAttributeDescriptorクラスおよびAttributesModelクラスを拡張して、動的コンポーネントに必要なデータを提供する必要があります。

グループを動的コンポーネントとともに使用する場合は、GroupAttributeDescriptorオブジェクトも作成する必要があります。

21.2.1 グループのないモデルの作成方法

モデルを作成するには、BaseAttributeDescriptorオブジェクト、AttributesModelオブジェクトおよびマネージドBeanをページ用に作成する必要があります。動的コンポーネントとイテレータは、これらを使用して属性のデータとメタデータにアクセスします。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

モデルを作成する手順:

1. 属性の各プロパティを記述する、属性定義クラスを作成します。このメタデータが、動的コンポーネントによってどのデータを表示するか、およびどのように構成するかを決定するときに使用されます。たとえば、この定義クラスには、属性の次に示すプロパティの取得メソッドがあると考えられます。

- name

- label

- dataType

属性定義クラスの例は、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentPageDefクラスのTestAttributeDef内部クラスを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

2. 各属性を定義する、別のクラスを作成します。この定義には、手順1で作成した定義クラスを使用します。このクラスは、各属性を定義してから、そのメタデータが入力された状態で属性のリストを返す必要があります。
たとえば、Employeeオブジェクトの属性としては次のものが考えられます。

- Ename

- Empno

- Deptname

- Deptno

- Manager

例21-4に、属性定義の作成方法の例を示します。これには、手順1で作成されたメタデータが使用されています。

例21-4 属性定義の例

public void addAttributeDef (String name, String label, Class dataType) {
TestAttributeDef attributeDef = new TestAttributeDef(name, label, dataType);
_attributes.put(name, attributeDef);
}

例21-5は、Employeeオブジェクトの属性のリストを、属性定義が入力された状態で返す方法を示します。

例21-5 属性の定義

public void setupAttributes()
{
_attributes = new HashMap<String, TestAttributeDef>();
addAttributeDef("Ename", "Employee Name", null, "Name", 10, 20, String.class);
addAttributeDef("Empno", "Employee Number", null,
"Employee Number", 10, 20, Number.class);
addAttributeDef("Deptname", "Department Name", null, "Department Name", 10, 20, String.class);
addAttributeDef("Deptno", "Department Number", null, "Department Number", 10, 20, Number.class);
addAttributeDef("Manager", "Manager", null, "Manager", 10, 20, Number.class);
}

属性定義クラス全体の例は、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentPageDefクラスを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

3. BaseAttributeDescriptorオブジェクトのためのクラスを作成します。このクラスは、BaseAttributeDescriptorクラスを拡張する必要があります。また、各属性のメタデータ・プロパティにアクセスする必要があります。例21-6に、NameおよびDataTypeを返す方法の例を示します。

例21-6 属性定義へのアクセス

public class TestAttributeDescriptor extends BaseAttributeDescriptor {
public TestAttributeDescriptor(TestAttributeDef attributeDef) {
_attributeDef = attributeDef;
}

public Object getId() {
return getName();
}

public String getName() {
return _attributeDef.getName();
}

public Class getDataType() {
return _attributeDef.getDataType();
}

完全な例については、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentBeanマネージドBeanのTestAttributeDescriptor内部クラスを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

4. AttributesModelクラスを拡張するクラスを作成します。このクラスでは、属性をBaseAttributeDescriptorオブジェクトからリストとして作成する必要があります。

例21-7 AttributesModelの作成

public class TestAttributesModel extends AttributesModel {
public TestAttributesModel() {
_flatAttributes = new ArrayList<BaseAttributeDescriptor>();
}

public List<BaseAttributeDescriptor> getAttributes() {
return _flatAttributes;
private void _setupAttributesFromDefinition() {
Map<String, List<BaseAttributeDescriptor>>();
List<TestDynamicComponentPageDef.TestAttributeDef> attributeList = _pageDef.getAttributeDefs();
. . .
for (TestDynamicComponentPageDef.TestAttributeDef demoAttrDef : attributeList) {
TestAttributeDescriptor attrDesc = new TestAttributeDescriptor(demoAttrDef);
_flatAttributes.add(attrDesc);
}

}
}

完全な例は、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentBeanマネージドBeanのTestAttributesModel内部クラスを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

5. マネージドBeanを作成します。このマネージドBeanは、ページのAttributesModelオブジェクトを、値を設定した状態で返す必要があります。また、そのページに必要なロジックがある場合は、そのロジックを実行する必要があります。たとえば、動的コンポーネントをフォームの中で使用する場合に、ユーザーが前後のレコードに移動できるようにするには、そのロジックを開発者が用意する必要があります。例21-8に示すコードは、AttributesModelを返すものであり、さらに前後のレコードにアクセスするためのロジックをActionイベントを使用して定義しています。

例21-8 動的コンポーネントのマネージドBeanのコード

public class TestDynamicComponentBean {
public TestDynamicComponentBean() {
_attrsModel = new TestAttributesModel();
}

public AttributesModel getAttributesModel() {
return _attrsModel;
}

public Map[] getValues() {
return _DATA;
}
public Map getValue() {
return _DATA[currentRowIndex];
}

public void next(ActionEvent actionEvent) {
if (currentRowIndex < _DATA.length - 1)
currentRowIndex++;
}

public boolean getNextEnabled() {
return (currentRowIndex < (_DATA.length - 1));
}

public void previous(ActionEvent actionEvent) {
if (currentRowIndex > 0)
currentRowIndex--;
}

public boolean getPreviousEnabled() {
return currentRowIndex > 0;
}

完全な例(マネージドBeanによってAttributesModelのデータが設定される方法を含む)は、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentBeanマネージドBeanを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

21.2.2 グループを使用するモデルの作成方法

グループを動的コンポーネントとともに使用する場合は、GroupAttributeDescriptorオブジェクトも作成する必要があります。このオブジェクトが、グループ情報に必要なメタデータを保持します。たとえば、グループに属する属性のリストです。開発者は、イテレータおよび動的コンポーネントによってグループを表示するために必要となるロジックも用意する必要があります。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

グループを使用するモデルを作成する手順:

1. 21.2.1項「グループのないモデルの作成方法」の手順1の説明に従って、属性定義クラスを作成します。ただし、categoryの属性定義をStringとして指定します。このカテゴリが、グループの定義に使用されます。

2. 属性を作成するときに、カテゴリを必要とする属性に対してカテゴリの値を割り当てます。たとえば、「Employee Personal」という値をEmpname属性およびEmpno属性に割り当てて、「Department Info」という値をDeptno属性およびDeptname属性に割り当てます。

3. categoryをBaseAttributeDescriptorクラスの一部とするために、getメソッドを用意します。ただし、このgetメソッドのシグネチャはgetGroupNameとしてください。例21-9に、getメソッドのコーディング例を示します。

例21-9 カテゴリのgetメソッドにはgroupNameを使用

public String getGroupName() {
return _attributeDef.getCategory();
}

4. GroupAttributeDescriptorオブジェクトのクラスを作成します。このクラスは、GroupAttributeDescriptorを拡張します。このオブジェクトは、グループの名前と、グループ内の属性のリストを保持します。例21-10に、GroupAttributeDescriptorクラスを示します。

例21-10 GroupAttributeDescriptorオブジェクトのクラス

public class TestGroupAttributeDescriptor extends GroupAttributeDescriptor {
public TestGroupAttributeDescriptor(String groupName, List<BaseAttributeDescriptor> attributeList) {
_groupName = groupName;
_flatAttributes = attributeList;
}

@Override
public String getName() {
return _groupName;
}

public List<? extends Descriptor> getDescriptors() {
return _flatAttributes;
}

public String getDescription() {
return "This is a group";
}

public String getLabel() {
return _groupName;
}

private List<BaseAttributeDescriptor> _flatAttributes;
private String _groupName;

}

5. 作成するAttributesModelクラスの中で、グループを表すhierarchicalAttributesを追加します。このようにするには、たとえばBaseAttributeDescriptorオブジェクトを調べるロジックを追加し、このオブジェクトにグループ名が格納されている場合に、その名前をhierarchicalAttributesオブジェクトに追加します。例21-11に、このロジックのコーディング例を示します。

例21-11 グループをhierarchicalAttributesに追加するロジック

for (TestDynamicComponentPageDef.TestAttributeDef demoAttrDef : attributeList) {
TestAttributeDescriptor attrDesc = new TestAttributeDescriptor(demoAttrDef);
_flatAttributes.add(attrDesc);
String groupName = attrDesc.getGroupName();
if (groupName != null && !groupName.isEmpty()) {
List<BaseAttributeDescriptor> list = groupMap.get(groupName);
if (list == null) {
list = new ArrayList<BaseAttributeDescriptor>();
groupMap.put(groupName, list);
}
list.add(attrDesc);
} else {
_hierAttributes.add(attrDesc);
}
}

for (String groupName : groupMap.keySet()) {
TestGroupAttributeDescriptor groupMetadata =
new TestGroupAttributeDescriptor(groupName, groupMap.get(groupName));
_hierAttributes.add(groupMetadata);
}
}

完全な例は、oracle.adfdemo.view.feature.rich.dynamicFacesパッケージのTestDynamicComponentBeanマネージドBeanのTestAttributesModel内部クラスを参照してください。このパッケージは、ADF Facesアプリケーションの「アプリケーション・ソース」ディレクトリにあります。

21.3 動的コンポーネントをフォームとしてページに追加する

動的コンポーネントをフォームの中で使用するときは、イテレータを組み込む必要があります。このイテレータがAttributesModelにアクセスして属性とその定義を取得します。動的コンポーネントは、このイテレータによってスタンプ・アウトされた各インスタンスの情報を取得して、どのコンポーネントを使用するか、およびどのように構成するかを特定します。

フォーム内の属性をグループ化する場合は、ファセット2個を持つスイッチャ・コンポーネントも使用する必要があります。ファセットの1つは、グループを対応する属性とともに表示するものであり、もう1つのファセットはどのグループにも属していない属性を表示します。

21.3.1 動的コンポーネントをグループなしでフォームとしてページに追加する方法

動的コンポーネントをフォームの中で使用するには、panelFormLayoutコンポーネント、イテレータおよびその動的コンポーネントを使用します。フォーム内のレコード間をナビゲートできるようにする場合は、ボタンも使用する必要があります。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

動的コンポーネントをグループなしでフォームとしてページに追加する手順:

1. panelFormLayoutコンポーネントを作成します。手順は9.7項「フォームでのコンテンツの配置」を参照してください。

2. 「コンポーネント」ウィンドウの「操作」パネルから、「イテレータ」をpanelFormLayoutコンポーネントに子としてドラッグ・アンド・ドロップします。

3. 「プロパティ」ウィンドウで次のとおりに設定します。

- Value: EL式を指定します。この式を解決した結果がAttributesModelオブジェクトのattributesプロパティとなる必要があります。次に例を示します。

#{TestDynCompBean.attributesModel.attributes}"

- Var: モデルの属性へのアクセスに使用できるString。例: attr

4. 「コンポーネント」ウィンドウから、「動的コンポーネント」をiteratorコンポーネントに子としてドラッグ・アンド・ドロップします。

5. 「プロパティ」ウィンドウで次のとおりに設定します。

- AttributeModel: EL式を指定します。この式を解決した結果は、イテレータ用に作成された変数となる必要があります。たとえば#{attr}です。

- Value: EL式を指定します。この式を解決した結果は、AttributesModelオブジェクトの各属性名となる必要があります。次に例を示します。

#{TestDynCompBean.value[attr.name]}"

6. レコード間を移動するためのロジックを用意する場合は、ボタンをpanelGroupLayoutコンポーネントの中で追加し、アクション・イベントを使用して前後のレコードにアクセスします。ボタンの使用方法の詳細は、20.3.1項「ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法」を参照してください。
例21-12に示すボタンのactionListener属性は、マネージドBeanのロジックにバインドされており、このロジックによってモデル内のレコード間をナビゲートします。

例21-12 ボタンを使用してAttributesModel内のレコード間をナビゲートする

<af:panelGroupLayout layout="horizontal" id="pgl2">
<af:button text="Previous" id="cb2" actionListener="#{TestDynCompBean.previous}"
disabled="#{!TestDynCompBean.previousEnabled}"/>
<af:button text="Next" id="cb1" actionListener="#{TestDynCompBean.next}"
disabled="#{!TestDynCompBean.nextEnabled}"/>
</af:panelGroupLayout>

例21-13に、対応するマネージドBeanコードを示します。

例21-13 動的コンポーネントの次レコードにアクセスするためのマネージドBeanコード

public Map[] getValues() {
return _DATA;
}

public Map getValue() {
return _DATA[currentRowIndex];
}

public void next(ActionEvent actionEvent) {
if (currentRowIndex < _DATA.length - 1)
currentRowIndex++;
}

public boolean getNextEnabled() {
return (currentRowIndex < (_DATA.length - 1));
}

21.3.2 動的コンポーネントをグループ付きでフォームとしてページに追加する方法

フォーム上の属性を動的コンポーネントを使用してグループ化するときは、グループに属する属性をフォーム上のある部分に配置し、どのグループにも属していない属性を別の部分に配置する必要があります。スイッチャ・コンポーネントのファセットを使用して、この2つを分離します。

スイッチャ・コンポーネントは、イテレータ・コンポーネントの子です。ただし、このイテレータは、AttributesModelの属性にバインドされるのではなく、モデルのhierarchicalAttributesにバインドされ、オブジェクトを自身の変数内に格納します。スイッチャのファセット内にある別のイテレータが、このhierarchicalAttributesオブジェクトの中にあるディスクリプタにバインドされます。このイテレータから、動的コンポーネントの情報が取得されます。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

動的コンポーネントをグループ付きでフォームとしてページに追加する手順:

1. panelFormLayoutコンポーネントを作成します。手順は9.7項「フォームでのコンテンツの配置」を参照してください。

2. 「コンポーネント」ウィンドウの「操作」パネルから、「イテレータ」をpanelFormLayoutコンポーネントに子としてドラッグ・アンド・ドロップします。

3. 「プロパティ」ウィンドウで、次を設定します。

- Value: EL式を指定します。この式を解決した結果がAttributesModelオブジェクトのhierarchicalAttributesプロパティとなる必要があります。次に例を示します。

#{TestDynCompBean.attributesModel.hierarchicalAttributes}"

- Var: モデルの属性へのアクセスに使用できるString。例: attr

4. 「スイッチャ」をiteratorコンポーネントに子としてドラッグ・アンド・ドロップします。

5. 「プロパティ」ウィンドウで、次を設定します。

- FacetName: EL式を入力します。この式を解決した結果は、親イテレータの変数によって返される値のdescriptorTypeプロパティとなる必要があります。次に例を示します。

#{attr.descriptorType}

- DefaultFacet: #{attr.descriptorType}によって返されず、定義済ファセットのどれにも一致しない属性を保持するファセットの名前。たとえば、ATTRIBUTEです。

6. 「構造」ウィンドウで、スイッチャ・コンポーネントを右クリックして「スイッチャの中に挿入」→「ファセット」を選択します。

7. 「ファセットの挿入」ダイアログで、ファセットの名前をGROUPと入力します。作成されたファセットには、グループに属する属性が格納されます。

8. 「コンポーネント」ウィンドウの「テキストおよび選択」パネルから、「出力テキスト」をドラッグ・アンド・ドロップします。このコンポーネントによってグループ名が表示されます。

9. 「プロパティ」ウィンドウで、「値」を、返されるグループのlabelプロパティにバインドします。これには、親イテレータの変数を使用します。たとえば、#{attr.label}です。

10. 「イテレータ」をoutputTextコンポーネントに子としてドラッグ・アンド・ドロップします。このイテレータは各グループ内の属性を反復処理するものであり、動的コンポーネントはこのイテレータを使用してコンポーネントおよび値を表示します。

11. 「プロパティ」ウィンドウで、次を設定します。

- Value: EL式を入力します。この式を解決した結果は、最初のイテレータによってその変数を使用して返されるディスクリプタ・オブジェクトとなる必要があります。たとえば、#{attr.descriptors}です。

- Var: ディスクリプタ内の属性へのアクセスに使用できるString。例: nestedAttr

12. 「動的コンポーネント」を2つ目のイテレータに子としてドラッグ・アンド・ドロップします。

13. 「プロパティ」ウィンドウで次のとおりに設定します。

- AttributeModel: EL式を入力します。この式を解決した結果は、2つ目のイテレータ用に作成された変数となる必要があります。たとえば、#{nestedAttr}です。

- Value: EL式を指定します。この式を解決した結果は、2つ目のイテレータによって返される各属性名となる必要があります。次に例を示します。

#{TestDynCompBean.value[nestedAttr.name]}

14. 「構造」ウィンドウで、outputTextコンポーネントとiteratorコンポーネントを選択して右クリックし、「囲む」を選択します。「囲む」ダイアログで、「グループ」を選択して「OK」をクリックします。
「プロパティ」ウィンドウで、「タイトル」を、最初のイテレータによって返されるグループのラベル・プロパティにバインドします。たとえば、#{attr.label}です。

15. 別のファセットを、スイッチャ・コンポーネントに子としてドラッグ・アンド・ドロップします。このファセットの名前を「ATTRIBUTE」と入力します。

16. 別の「動的コンポーネント」をATTRIBUTEファセットに子としてドラッグ・アンド・ドロップし、次のとおりに設定します。

- AttributeModel: EL式を指定します。この式を解決した結果は、メイン・イテレータ用に作成された変数となる必要があります。たとえば#{attr}です。

- Value: EL式を指定します。この式を解決した結果は、メイン・イテレータによって返される各属性名となる必要があります。次に例を示します。

#{TestDynCompBean.value[attr.name]}

21.4 動的コンポーネントを表としてページに追加する

動的コンポーネントを表の中で使用するときは、表の列をイテレータの中にラップする必要があります。このイテレータがAttributesModelにアクセスして属性とその定義を取得します。この情報を使用して、列のヘッダー・テキストが決定されます。動的コンポーネントは、イテレータによってスタンプ・アウトされた属性インスタンスごとに情報を取得して、どのコンポーネントを使用するか、およびどのように構成するかを特定すると同時に、表の変数を使用して、どのデータを表示するかを決定します。

表内の属性をグループ化する場合は、ファセットを2つ持つスイッチャ・コンポーネントも使用する必要があります。ファセットの1つは、グループを対応する属性とともに表示するものであり、もう1つのファセットはどのグループにも属していない属性を表示します。

21.4.1 動的コンポーネントをグループなしで表としてページに追加する方法

動的コンポーネントを表の中で使用するには、表コンポーネントをデータにバインドします。columnコンポーネントのかわりに、イテレータが表の動的な子となり、このイテレータはAttributesModelのattributesプロパティにバインドされます。列は、このイテレータの子です。動的コンポーネントは、列の子です。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

動的コンポーネントをグループなしで表としてページに追加する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「表」をドラッグ・アンド・ドロップし、表のデータにバインドします。
表の詳細は、12.3項「表へのデータの表示」を参照してください。

2. 「構造」ウィンドウで、自動的に作成された列コンポーネントとその内容を削除します。後の手順で、列を手動で追加します。

3. 「コンポーネント」ウィンドウの「操作」パネルから、「イテレータ」をtableコンポーネントに子としてドラッグ・アンド・ドロップします。

4. 「プロパティ」ウィンドウで次のとおりに設定します。

- Value: EL式を指定します。この式を解決した結果がAttributesModelオブジェクトのattributesプロパティとなる必要があります。次に例を示します。

#{TestDynCompBean.attributesModel.attributes}"

- Var: モデルの属性へのアクセスに使用できるString。例: col

5. 「コンポーネント」ウィンドウから、「列」をイテレータ・コンポーネントに子としてドラッグ・アンド・ドロップします。「プロパティ」ウィンドウで、HeaderTextを、イテレータによって返される属性のlabelプロパティにバインドします。たとえば、#{col.label}です。

6. 「コンポーネント」ウィンドウから、「動的コンポーネント」をcolumnコンポーネントに子としてドラッグ・アンド・ドロップします。

7. 「プロパティ」ウィンドウで次のとおりに設定します。

- AttributeModel: EL式を指定します。この式を解決した結果は、イテレータ用に作成された変数となる必要があります。たとえば#{col}です。

- Value: EL式を指定します。この式を解決した結果は、AttributesModelオブジェクトの各属性名となる必要があります。これは、行ごとにスタンプ・アウトされる必要があるため、表コンポーネントから返される値にこれをバインドする必要があります。たとえば、#{row[col.name]}です。

21.4.2 動的コンポーネントをグループ付きで表としてページに追加する方法

表の中の属性を動的コンポーネントを使用してグループ化するときは、グループが親列として表示されます。図21-2に示すEmployeeオブジェクトの特定の属性は、「Employee Personal」グループおよび「Department Info」グループに属しています。

図21-2 グループを使用する動的コンポーネントを持つ表

スイッチャ・コンポーネントを使用して、グループに属している属性とそうでない属性とを分離します。ただし、このメイン・イテレータは、AttributesModelの属性にバインドされるのではなく、モデルのhierarchicalAttributesにバインドされ、オブジェクトを自身の変数内に格納します。スイッチャのファセット内にある別のイテレータが、このhierarchicalAttributesオブジェクトの中にあるディスクリプタにバインドされます。このイテレータから動的コンポーネントの情報が取得されて、コンポーネントに属性のグループを表示できるようになります。

AttributeModelのhierarchicalAttributesによって、AttributeModelのルート・レベルの属性が定義されます。ルート・レベルの属性が通常の属性である場合、つまりその属性のタイプがATTRIBUTEである場合は、この属性はどのグループにも属しておらず、表ではその属性に対して1つの列がレンダリングされます。ルート・レベルの属性がグループ化された属性である場合、つまり属性のタイプがGROUPである場合は、このグループに属している通常の属性のリストが存在します。ファセット内のイテレータは、このグループを反復処理し、そのグループの中の各属性は列としてスタンプされます。たとえば、「Employee Personal」はGROUPタイプの属性であり、この中には通常の属性が3つあります。「Employee Number」、「Name」および「Salary」です(図21-2を参照)。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

動的コンポーネントをグループ付きで表としてページに追加する手順:

1. 「コンポーネント」ウィンドウの「データ・ビュー」パネルから、「表」をドラッグ・アンド・ドロップします。「ADF Faces表の作成」ダイアログで、「データを今すぐバインド」を選択します。「表データ・コレクション」の「参照」をクリックして「表データ・コレクションの選択」ダイアログを開きます。モデル用に作成したマネージドBeanのvaluesプロパティを選択します。
表の詳細は、12.3項「表へのデータの表示」を参照してください。

2. 「構造」ウィンドウで、自動的に作成された列コンポーネントとその内容を削除します。後の手順で、列を手動で追加します。

3. 「コンポーネント」ウィンドウの「操作」パネルから、「イテレータ」をtableコンポーネントに子としてドラッグ・アンド・ドロップします。

4. 「プロパティ」ウィンドウで次のとおりに設定します。

- Value: EL式を指定します。この式を解決した結果がAttributesModelオブジェクトのhierarchicalAttributesプロパティとなる必要があります。次に例を示します。

#{TestDynCompBean.attributesModel.heirarchicalAttributes}"

- Var: モデルの属性へのアクセスに使用できるString。例: column

5. 「コンポーネント」ウィンドウから、「列」をイテレータ・コンポーネントに子としてドラッグ・アンド・ドロップします。「プロパティ」ウィンドウで、HeaderTextを、イテレータによって返されるグループのlabelプロパティにバインドします。たとえば、#{column.label}です。

6. 「スイッチャ」をcolumnコンポーネントに子としてドラッグ・アンド・ドロップします。

7. 「プロパティ」ウィンドウで、次を設定します。

- FacetName: EL式を指定します。この式を解決した結果は、親イテレータの変数によって返される値のdescriptorTypeプロパティとなる必要があります。次に例を示します。

#{column.descriptorType}

- DefaultFacet: どのグループにも属していない属性を保持するファセットの名前。たとえばATTRIBUTEです。

8. 「構造」ウィンドウで、スイッチャ・コンポーネントを右クリックして「スイッチャの中に挿入」→「ファセット」を選択します。

9. 「ファセットの挿入」ダイアログで、ファセットの名前をGROUPと入力します。作成されたファセットには、グループに属する属性が格納されます。

10. 「イテレータ」を、GROUP facetコンポーネントに子としてドラッグ・アンド・ドロップします。このイテレータは各グループ内の属性を反復処理するものであり、動的コンポーネントはこのイテレータを使用してコンポーネントおよび値を表示します。

11. 「プロパティ」ウィンドウで、次を設定します。

- Value: EL式を指定します。この式を解決した結果は、最初のイテレータによってイテレータの変数を使用して返されるDescriptorオブジェクトとなる必要があります。たとえば、#{column.descriptors}です。

- Var: ディスクリプタ内の属性へのアクセスに使用できるString。例: nestedCol

12. 「列」をイテレータ・コンポーネントに子としてドラッグ・アンド・ドロップします。「プロパティ」ウィンドウで、HeaderTextを、親イテレータによって返される属性のlabelプロパティにバインドします。たとえば、#{nestedCol.label}です。

13. 「動的コンポーネント」を2つ目のイテレータに子としてドラッグ・アンド・ドロップします。

14. 「プロパティ」ウィンドウで次のとおりに設定します。

- AttributeModel: EL式を指定します。この式を解決した結果は、2つ目のイテレータ用に作成された変数となる必要があります。たとえば、#{nestedCol}です。

- Value: EL式を指定します。この式を解決した結果は、2つ目のイテレータによって返される各属性名となる必要があります。次に例を示します。

#{row[nestedCol.name]}

15. 別の「ファセット」を、スイッチャ・コンポーネントに子としてドラッグ・アンド・ドロップします。このファセットの名前を「ATTRIBUTE」と入力します。

16. 別の「動的コンポーネント」をATTRIBUTEファセットに子としてドラッグ・アンド・ドロップし、次のとおりに設定します。

- AttributeModel: EL式を指定します。この式を解決した結果は、メイン・イテレータ用に作成された変数となる必要があります。たとえば#{column}です。

- Value: EL式を指定します。この式を解決した結果は、メイン・イテレータによって返される各属性名となる必要があります。次に例を示します。

#{row[column.name]}

21.5 動的コンポーネントでの検証および変換の使用

変換および検証を動的コンポーネントに追加するには、必要なコンバータまたはバリデータのタグを追加し、どの属性を検証または変換するかを指定します。enabled属性のかわりに、動的コンポーネントではdisabled属性が使用されます。

始める前に

動的コンポーネントによって表示されるものがどのように決定されるかを理解しておくと役立ちます。詳細は、21.1項「実行時の動的コンポーネントの決定について」を参照してください。

バリデータまたはコンバータを動的コンポーネントとともに使用する手順:

1. 「コンポーネント」ウィンドウの「操作」パネルから、必要なコンバータまたはバリデータを動的コンポーネントに子としてドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウの「その他」セクションで、「無効」フィールドにマウスを置いたときに表示されるアイコンをクリックして「式ビルダー」を選択します。

3. 式ビルダーで、解決した結果が属性となる式を入力し、必要なパターンを指定します。例21-14に2つのコンバータとバリデータを示します。これらは、動的コンポーネントによって表現される様々な属性に使用されるものの例です。DateTimeコンバータはHiredate属性に対して実行され、NumberコンバータはSal属性に対して実行され、LengthバリデータはJob属性に対して実行され、LongRangeバリデータはSal属性に対して実行されます。

例21-14 動的コンポーネントの検証と変換

<af:dynamicComponent value="#{DynCompBean.value[attr.name]}"
attributeModel="#{attr}" id="dc1"/>
<af:convertDateTime disabled="#{attr.name == 'Hiredate' ? false : true}"
pattern="yyyy/MM/dd"/>
<af:convertNumber disabled="#{attr.name == 'Sal' ? false : true}"
pattern="#,###,###" />
<af:validateLength disabled="#{attr.name == 'Job' ? false : true}"
maximum="10" hintMaximum="maxmum length is 10"/>
<af:validateLongRange disabled="#{attr.name == 'Sal' ? false : true}"
minimum="1000"/>
</af:dynamicComponent>

21.6 動的および静的のコンポーネントの同時使用

動的フォームを作成することは、実質的には動的にレンダリングされるコンポーネントのブロックを作成することです。静的コンポーネントをこのコンポーネントのブロックの前または後に配置できますが、静的コンポーネントをそのブロックの中に配置することはできません。

このような制約はありますが、多数の動的および静的のコンポーネントを使用して複雑なフォームを作成できます。また、静的コンポーネントを、詳細なレベルの動的コンポーネントどうしの間に配置することもできます。

たとえば、フォームに名前と住所の情報を、英語と日本語の両方で表示する必要があるとします。この例では、日本語の情報は動的コンポーネントを使用して表示し、英語の情報は静的コンポーネントで表示するとします。図21-3に、フィールドの配置の例を示します。動的な日本語コンテンツを、静的コンテンツの後に表示しています。

図21-3 動的コンポーネントを静的コンポーネントの後に配置できる

例21-15に、このフォームを作成する方法の例を示します。静的なinputTextコンポーネントと動的コンポーネントを使用して、NameグループおよびAddressグループの属性にアクセスします。

例21-15 静的コンポーネントの後に動的コンポーネント

<panelFormLayout ... >
<af:group title="Name">
<af:inputText value="#{myBean.firstName} id="it1" label="First Name"/>
<af:inputText value="#{myBean.middleName} id="it2" label="Middle Name"/>
<af:inputText value="#{myBean.lastName} id="it3" label="Last Name"/>
<af:iterator
value="#{DynCompBean.attributesModel.hierarchicalAttributes("Name")}"
var="attr" id="iter1">
<af:dynamicComponent id="dc1"
value="#{DynCompBean.value[attr.name]}"
attributeModel="#{attr}"/>
</af:iterator>
</af:group>
<af:group title="Address">
<af:inputText value="#{myBean.streetAddress}" id="it4"
label="Street Address"/>
<af:inputText value="#{myBean.City.inputValue}" id="it5" label="City"/>
<af:inputText value="#{myBean.State.inputValue}" id="it6" label="State"/>
<af:iterator
value="#{DynCompBean.attributesModel.hierarchicalAttributes("Address")}"
var="attr" id="iter1">
<af:dynamicComponent id="dc1"
value="#{DynCompBean[attr.name].inputValue}"
attributeModel="#{attr}"/>
</af:iterator>
</af:group>
</panelFormLayout>

次に、日本語の名前および住所の情報を英語の情報と分離させるかわりに、図21-4に示すように交互に表示するとします。

図21-4 動的コンポーネントを静的コンポーネントとともに配置できる

この場合は、動的コンポーネントの中でグループを使用するかわりに、必要な属性のみ(つまり、全部の属性ではありません)にアクセスします(例21-16を参照)。

例21-16 動的コンポーネントと静的コンポーネント

<af:group title="Name">
<af:inputText value="#{myBean.firstName} id="it1" label="First Name"/>
<af:iterator value="#{DynCompBean.attributesModel.attributes("Japanese First Name")}"
var="attr" id="iter1">
<af:dynamicComponent id="dc1" value="#{DynCompBean.value[attr.name]}"
attributeModel="#{attr}"/>
</af:iterator>
<af:inputText value="#{myBean.middleName} id="it2" label="Middle Name"/>
<af:inputText value="#{myBean.lastName} id="it3" label="Last Name"/>
<af:iterator value="#{DynCompBean.attributesModel.attributes("Japanese Last Name")}"
var="attr" id="iter1">
<af:dynamicComponent id="dc1" value="#{DynCompBean.value[attr.name]}"
attributeModel="#{attr}"/>
</af:iterator>
</af:group>
<af:group title="Address">
<af:inputText value="#{myBean.streetAddress}" id="it4" label="Street Address"/>
<af:iterator value="#{DynCompBean.attributesModel.attributes("Japanese Street Address")}"
var="attr" id="iter1">
<af:dynamicComponent id="dc1" value="#{DynCompBean.value[attr.name]}"
attributeModel="#{attr}"/>
</af:iterator>
. . .
</af:group>

第V部

ADFデータ視覚化コンポーネントの使用

第V部には、次の章が含まれています。

- 第22章「ADFデータ視覚化コンポーネントの概要」

- 第23章「グラフ・コンポーネントの使用方法」

- 第24章「ゲージ・コンポーネントの使用方法」

- 第25章「ピボット・テーブル・コンポーネントの使用方法」

- 第26章「ガント・チャート・コンポーネントの使用方法」

- 第27章「時系列コンポーネントの使用方法」

- 第28章「マップ・コンポーネントの使用方法」

- 第29章「階層ビューア・コンポーネントの使用方法」

- 第30章「ツリーマップおよびサンバースト・コンポーネントについて」

22 ADFデータ視覚化コンポーネントの概要

この章では、インタラクティブなADF Facesコンポーネントの表現力が高いセットであるADFデータ視覚化コンポーネントについて説明します。コンポーネント全般およびその他のADF Facesコンポーネントとの共有機能についても焦点を当てます。この部の他の章では、各コンポーネントの作成およびカスタマイズ方法について説明します。

この章では、次の項目について説明します。

- 22.1項「ADFデータ視覚化コンポーネントについて」

- 22.2項「データ視覚化コンポーネントの共通機能」

- 22.3項「ADFデータ視覚化コンポーネントへのデータの指定」

22.1 ADFデータ視覚化コンポーネントについて

ADFデータ視覚化コンポーネントには、データの表示および分析を行うための非常にグラフィカルな表形式の機能が用意されています。このコンポーネントでは、次の機能が提供されます。

- ADFデータ・コントロールの使用をサポートするADF Facesのフル・コンポーネントです。

- データ・コントロール・パネル、JSFビジュアル・エディタ、「プロパティ」ウィンドウおよび「コンポーネント」ウィンドウを使用した宣言設計時作成が提供されます。

- 各コンポーネントに、ライブ・データ・プレビューが用意されています。この機能により、ページをコンパイルおよび実行することなく、設計の効果を確認できるため、非常に有用です。

データ視覚化コンポーネントには、グラフ、ゲージ、ピボット・テーブルとピボット・フィルタ・バー、地理マップ、テーマ・マップ、ガント・チャート、時系列、階層ビューア、ツリーマップおよびサンバーストがあります。

接頭辞dvt:は、各ゲージ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。

22.1.1 グラフ・コンポーネントのユースケースおよび例

グラフ・コンポーネントには、棒グラフ、円グラフ、折れ線グラフ、散布図、株価チャートなど、50種類以上のグラフを作成する機能が用意されています。このコンポーネントでは、複数軸の複数データ・ポイントを様々な方法で評価できます。たとえば、一群のグラフにより、あるグループからの結果と他のグループからの結果の比較が容易になります。

グラフ・コンポーネントでは次の種類のグラフを作成できます。

- 面グラフ(areaGraph): データが塗りつぶされた面として表されるグラフを作成します。面グラフを使用して、過去12か月の売上げなど、ある期間の傾向を示します。面グラフでは、1つの軸上に最低2グループのデータが必要です。軸には、月などの時間の経過を表すラベルが付けられることがよくあります。

- 棒グラフ(barGraph): データが一連の縦棒として表されるグラフを作成します。ある期間の傾向の確認や、複数の地域での異なる製品区分の売上げなど、同一時点での項目の比較に使用します。

- 棒(横)グラフ(horizontalBarGraph): Y軸に沿って棒を横向きに表示するグラフを作成します。傾向の表示や値の比較に使用できる向きを持たせるために使用します。

- バブル・グラフ(bubbleGraph): データが円形のデータ・マーカー(バブル)の位置とサイズで表されるグラフを作成します。3種類の値の相関関係を示す場合(データ項目が多数で全体の関係を表示する場合は特に)に使用します。たとえば、バブル・グラフを使用して、従業員の給与(X軸)、経験年数(Y軸)と生産性(バブルのサイズ)をプロットします。このようなグラフでは、生産性を給与および経験と比較して調べることができます。

- 組合せグラフ(comboGraph): 異なる種類のデータ・マーカー(棒、線または面)を使用して異なる種類のデータ項目を表すグラフを作成します。棒と線、棒と面、線と面あるいは3つすべての組合せの比較に使用します。

- ファンネル・グラフ(funnelGraph): プロセスのステップに関連するデータを視覚的に表すグラフを作成します。ステップは、横向きの円柱に対する縦向きのスライスとして表されます。特定のステップ(スライス)の実際の値がそのスライスの割当てに近づいた分、スライスが塗りつぶされます。通常、ファンネル・グラフには、時間などのステージ値に対する実績値と目標値が必要です。たとえば、このコンポーネントを使用して、プロセス(販売ルートなど)がステージ(会計年度の四半期)の目標に達するかどうかを確認します。

- 折れ線グラフ(lineGraph): データが線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとして表されるグラフを作成します。折れ線グラフには、グループ内のメンバーごとに最低2つのポイントを表すデータが必要です。たとえば、月ごとの折れ線グラフには最低2か月必要です。通常、特定の色の線は、アメリカ、ヨーロッパ、アジアなどのデータの各グループに関連付けられています。同一期間の項目の比較に使用します。

- パレート・グラフ(paretoGraph): データが棒と棒の累積割合を示すパーセンテージ線で表されるグラフを作成します。各棒は、交通事故の原因など、異なる不具合の原因を表します。棒は、発生件数の多いものから少ないものの順に並べられます。パレート・グラフは常に二重Yグラフで、1つ目のY軸は棒が表す値に対応し、2つ目のY軸は0%から100%を表し、累積割合の値に対応します。パレート・グラフを使用して、不具合の原因を特定し、比較します。

- 円グラフ(pieGraph): 1つのグループのデータが円のセクションとして表され、円が切り分けられたパイのように見えるグラフを作成します。各製品ラインからの収益など、全体に対する各部分の関係の表示に使用します。

- レーダー・グラフ(radarGraph): 円状の折れ線グラフとして表されるグラフを作成します。過去3年間の月ごとの売上げなどの周期的に起こるパターンを表す場合に使用します。

- 散布図/極グラフ(scatterGraph): データが、データ・マーカーの位置によって表されるグラフを作成します。散布図を使用して、上位製品の売上げとコストなど、異なる2種類のデータの相関関係を表す場合に使用します。散布図は、多数の項目間の全体的な関連性を示す場合に特に有用です。

- スパークチャート(sparkChart): 傾向や変化を多くの場合、表の列内やテキスト行中で表す簡単な縮小グラフを作成します。スパークチャートは、限られた機能やフォーマット・オプションで、できるだけ多くのデータを表示する簡単なデザインです。

- 株価チャート(stockGraph): データが株の高値、安値および終値を示すグラフを作成します。各株価マーカーで3つの異なる値を表示します。

図22-1に、次のものが表示されているアプリケーション・ダッシュボードを示します。

- 参照線のある棒グラフおよび参照線のない棒グラフ

- 円グラフ

図22-1 棒グラフおよび円グラフが表示されているダッシュボード

図22-2に、多数のグラフ・タイプの例が表示されているアプリケーション・ダッシュボードを示します。

図22-2 複数のグラフ・タイプが表示されているダッシュボード

図22-3に、表の列で売上げ傾向を表示する折れ線スパークチャートを示します。

図22-3 売上げ傾向のスパークチャート

その他のユースケースおよび例などの詳細は、第23章「グラフ・コンポーネントの使用方法」を参照してください。

22.1.2 ゲージ・コンポーネントのユースケースおよび例

ゲージ(gauge)・コンポーネントでは、データのグラフィカル表現をレンダリングします。グラフとは異なり、ゲージでは1つのデータ・ポイントにフォーカスして、そのポイントを最小、最大およびしきい値インジケータと比較して調べ、問題のある領域を特定します。

1つのゲージ・コンポーネントでは、使用されるデータに応じて、1つのゲージまたはゲージ・セットを作成できます。

このコンポーネントでは次の種類のゲージを作成できます。

- ダイアル・ゲージ: 180度の弧に沿ってメトリック値を示すゲージを作成します。このタイプのゲージには、通常、ゲージがプロットしている値を指す、線または矢印の形のインジケータがあります。

- ステータス・メーター・ゲージ:横長の矩形のバーに沿ってタスクの進度または測定値のレベルを示すゲージを作成します。内側の矩形は、外側の矩形に表示された範囲に対する現在の測定値のレベルを示します。

- ステータス・メーター・ゲージ(垂直):縦長の矩形のバーに沿ってタスクの進度または測定値のレベルを示すゲージを作成します。

- LED(電光表示)ゲージ:重要業績評価指標(KPI)などの測定値をグラフィカルに表すゲージを作成します。LEDゲージには、よい(上矢印)、普通(左または右矢印)、悪い(下矢印)を示す矢印など、数種のグラフィクスが使用できます。

ゲージのしきい値はいくつでも指定できます。ただし、一部のLEDゲージ(矢印または三角形のインジケータを持つものなど)では、指し示す有効な方向の数が限られているため、サポートされるしきい値の数にかぎりがあります。矢印または三角形のインジケータの場合、しきい値の最大数は3です。

図22-4に、倉庫の在庫レベルを表示する、しきい値付きダイアル・ゲージのセットを示します。

図22-4 しきい値付きダイアル・ゲージ・セット

図22-5に、しきい値付きステータス・メーター・ゲージ・セットとして表示される同じデータを示します。

図22-5 しきい値付きステータス・メーター・ゲージ・セット

その他のユースケースおよび例などの詳細は、第24章「ゲージ・コンポーネントの使用方法」を参照してください。

22.1.3 ピボット・テーブルのユースケースおよび例

ピボット・テーブル(pivotTable)では、行または列での複数層のデータ・ラベルをサポートするグリッドを作成します。オプションのピボット・フィルタ・バー(pivotFilterBar)をピボット・テーブルと関連付けることで、行または列のエッジで表示されないデータをフィルタ処理できます。行セットなどの適切なデータ・コントロールにバインドされている場合、このコンポーネントでは、グリッド・データの小計と合計を生成するオプションや、実行時のドリル操作もサポートされます。

ピボット・テーブルでは、あるエッジ(行または列)またはピボット・フィルタ・バー(ページ・エッジ)から別のエッジにデータ・ラベルを切り替え、データの表示を変えることができます。たとえば、ピボット・テーブルで最初は、地域内の製品の合計売上げデータを行エッジに表示し、列エッジで年ごとに分類しているとします。実行時に地域と年を切り替えると、数年間の製品の合計売上げデータが、地域ごとに分類されて表示されます。

ピボット・テーブルでは、横方向と縦方向のスクロール、ヘッダーとセルの書式設定およびドラッグ・アンド・ドロップ・ピボットがサポートされています。ピボット・テーブルでは、実行時の行の昇順および降順のグループ・ソートもサポートされます。図22-6に、ピボット・フィルタ・バーのあるピボット・テーブルの例を示します。

図22-6 ピボット・フィルタ・バーのあるピボット・テーブル

その他のユースケースおよび例などの詳細は、第25章「ピボット・テーブル・コンポーネントの使用方法」を参照してください。

22.1.4 地理マップのユースケースおよび例

地理マップ(map)では、Oracle ADFにOracle Spatialの機能が提供されます。このコンポーネントでは、ビジネス・データをマップ上に表し、1つのマップ上に複数層の情報を重ね合せることができます。このコンポーネントでは、色テーマ、グラフ・テーマ(棒または円グラフ)および点テーマの同時表示がサポートされます。各タイプのテーマはいくつでも作成でき、マップ・ツールバーを使用して、実行時にテーマを選択できます。

地理マップの例として、各州での製品の人気を色の濃さで示す色テーマ、倉庫の在庫レベルを示す円グラフ・テーマおよび各倉庫の正確な位置を示す点テーマを使用した、アメリカの基準となるマップを考えてみます。この3つの全テーマをアメリカ合衆国の地図に重ね合せると、特定の地域で商品の人気度に応じた十分な在庫があるかどうかを簡単に評価できます。図22-7に、色テーマ、円グラフ・テーマおよび点テーマを使用した地理マップを示します。

図22-7 色テーマ、円グラフ・テーマおよび点テーマを使用した地理マップ

その他のユースケースおよび例などの詳細は、第28章「マップ・コンポーネントの使用方法」を参照してください。

22.1.5 テーマ・マップ・コンポーネントのユースケースおよび例

テーマ・マップ(thematicMap)コンポーネントでは、ビジネス・データを定型化された地域内のパターンまたは関連付けられたマーカーとして表し、マップ・ビューア・サービスへの接続は必要ありません。テーマ・マップでは、地理マップでの地理的な詳細なしで、データに焦点を合せます。テーマ・マップは、米国、世界をはじめ、世界の大陸や地域(EMEAやAPACなど)などのあらかじめ作成された基準となるマップとともにパッケージ化されています。テーマ・マップ・コンポーネントでは、基準となるマップを表示するためのマップ・サービスは必要ありません。

たとえば、図22-8に表示されているように、州マップ・レイヤーを備えた基準となる米国のマップを使用して、倉庫と顧客の位置を表示できます(色を使用して高比率、中比率および低比率を示すことが可能)。この例では、データ・バインドされた凡例など、テーマ・マップのデフォルト機能が示されています。

図22-8 倉庫と顧客の比率を表示するテーマ・マップ

その他のユースケースおよび例などの詳細は、第28章「マップ・コンポーネントの使用方法」を参照してください。

22.1.6 ガント・チャート・コンポーネントのユースケースおよび例

ガント・チャートは(横軸を時間とする)横棒グラフの一種で、リソースまたはタスクが、開始と終了が明確なタイム・フレームに示され、プロジェクトの計画や進捗管理に使用されます。

ガント・チャートは、2つのADFのツリー表とスプリッタの組合せで構成されます。左側の表にはタスクまたはリソースのリストが含まれ、右側の表は1つの列で構成され、特定期間の進捗がグラフ表示されます。

3種類のガント・コンポーネントがあります。

- プロジェクト・ガント(projectGantt): タスクを縦に示し、横方向の時間軸にタスクの期間を棒で示すガント・チャートを作成します。

- リソース使用率ガント(resourceUtilizationGantt): リソースが割当てを上回っているか下回っているかをグラフィカルに示すガント・チャートを作成します。リソースを縦に示し、横方向の時間軸にその割当てとキャパシティ(オプション)を示します。

- スケジュール・ガント(schedulingGantt): リソース管理を示し、手動のスケジュール表をベースにしたガント・チャートを作成します。リソースを縦方向に、対応するアクティビティを横方向の時間軸に表示します。

図22-9 に、スタッフ・リソースとスケジュールを表示したプロジェクト・ガントを示します。

図22-9 プロジェクト・ガント・チャート

その他のユースケースおよび例などの詳細は、第26章「ガント・チャート・コンポーネントの使用方法」を参照してください。

22.1.7 時系列コンポーネントのユースケースおよび例

時系列は、時間軸に沿った時系列アイテムとしてのイベントの表示、時系列に表示可能な期間に対応する移動可能な概要ウィンドウ、および時系列の時間増分全体を示した概要時間軸で構成されます。表示可能な時間範囲は、水平方向のズーム制御を使用して変更できます。イベントに対応する各時系列アイテムは、関連付けられた情報やアクションを表示し、時間軸への引出線と概要時間軸内のマーカーで表されます。

たとえば、図22-10の時系列は、従業員の雇用日を時間順に表示するように構成されています。この例では、各イベントを表す時系列アイテムに、イメージとラベル付きテキストを使用して従業員に関する情報を表示しています。概要ウィンドウは、時系列アイテムを表示する時間範囲を定義します。このウィンドウは、ズーム・コントロールを変更するか、ウィンドウの端の位置を変更して拡大または縮小することでサイズを調整できます。選択が構成されている場合は、時系列アイテム、引出線、および概要パネルのイベント・マーカーが強調表示されます。

図22-10 従業員の雇用日の時系列

2つの時系列を使用して最大2系列のイベントを比較できます。図22-11に、10年間にわたる2人の従業員の変化のイベントを比較した2つの時系列を示します。時系列イベントは、3年を超える期間を表す概要ウィンドウに四半期単位の時間軸を使用して表示されています。概要時間軸の赤い線は現在の日付を示しています。

図22-11 従業員の変化イベントを比較した2つの時系列

その他のユースケースおよび例などの詳細は、第27章「時系列コンポーネントの使用方法」を参照してください。

22.1.8 階層ビューア・コンポーネントのユースケースおよび例

階層ビューア(hierarchyViewer)は、階層データが図中のリンクされたノードのセットとして表示されるコンポーネントです。ノードおよびリンクは、データの要素および関係に対応します。このコンポーネントでは、パンおよびズーム操作、ノードの展開および縮小、ノード内での簡単なADF Facesコンポーネントのレンダリング、そして階層ビューア・データの検索がサポートされています。階層ビューアの一般的な用途は、図22-12に示すような組織図を表示することです。

図22-12 階層ビューアによる組織図

その他のユースケースおよび例などの詳細は、第29章「階層ビューア・コンポーネントの使用方法」を参照してください。

22.1.9 ツリーマップおよびサンバースト・コンポーネントのユースケースおよび例

treemapおよびsunburstコンポーネントは、数量的な階層データを、サイズと色で視覚的に表された2つのディメンションで表示します。ツリーマップおよびサンバーストでは、nodeと呼ばれる形を使用して、階層内のデータを表します。たとえば、ツリーマップまたはサンバーストを使用して地域の四半期ごとの売上げを表示し、売上げ傾向を特定する場合は、ノードのサイズで各地域の売上げ高を示し、ノードの色でその地域の売上げが四半期で増えたか減ったかを示すことができます。

ツリーマップはノードをネストした矩形のセットとして表示します。ツリーのブランチごとに1つの矩形が割り当てられ、そこにサブブランチを表すより小さな矩形が並べられます。

図22-13に、米国の人口調査データを地域ごとにグループ化して表示し、色の属性で平均所得水準を表したツリーマップを示します。人口の多い州は人口の少ない州より大きなノードで表示されます。

図22-13 米国の人口調査データを地域別に表示したツリーマップ

サンバーストは、ノードを矩形レイアウトではなく、放射状に表示し、階層のトップを中心に、深いレベルになると中心から離れて表示します。図22-14に、サンバーストで表示した同じ国勢調査データを示します。

図22-14 米国の人口調査データを地域別に表示したサンバースト

ツリーマップとサンバーストでは、何千ものデータ・ポイントを比較的小さな空間領域に表示できます。各ノードの相対サイズが全体に対する重要度を表しているため、これらのコンポーネントは大規模な階層データ・セットで傾向を特定する場合に適しています。情報の追加ディメンションを表すために、色も使用できます。

階層の1つのレイヤーでサイズと色を使用してデータの2つのメトリックを表示することが主な目的の場合は、ツリーマップを使用します。階層のすべてのレベルでのメトリックを表示する場合、かわりにサンバーストを使用します。エンド・ユーザーが階層を横断してデータの重要な部分を重点的に表示できるように、ドリルを有効にできます。

ツリーマップの情報、およびアプリケーションでのこれらの使用方法の詳細は、第30章「ツリーマップおよびサンバースト・コンポーネントについて」を参照してください。

22.1.10 データ視覚化コンポーネントの追加機能

データ視覚化コンポーネントをデータ・バインドする前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんデータ視覚化コンポーネントをページに追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。データ視覚化コンポーネントで使用されるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: データ視覚化コンポーネントをリフレッシュして、ページの別のコンポーネントで実行されたアクションに基づく新しいデータを表示できます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: ユーザーは実行時にデータ視覚化コンポーネントの表示を変更できますが、ユーザーがカスタマイズできるようにアプリケーションを構成していないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: データ視覚化コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- スキンおよびスタイル: アプリケーションに適用するADFスキンを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)を使用してCSSスタイル・プロパティを直接適用することにより、データ視覚化コンポーネントの外観をカスタマイズできます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- プレースホルダ・データ・コントロール: 最終的にページのデータ視覚化コンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールの使用を検討します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「プレースホルダ・データ・コントロールを使用したページの設計」の章を参照してください。

22.2 データ視覚化コンポーネントの共通機能

データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、コンポーネントを表示するために使用されるイメージ・フォーマット、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。これらのコンポーネントを使用する前に、この共有機能と、その構成方法を理解することが重要です。

22.2.1 コンテンツの配信

ゲージ、グラフ、ガント・チャート、階層ビューア、ピボット・テーブル、サンバースト、テーマ・マップ、時系列およびツリーマップを含むデータ視覚化コンポーネントは、データ・ソースからのデータ配信方法について構成できます。データは、レンダリング直後、データが使用可能になり次第、またはコンポーネントのシェルがレンダリングされた後の遅延フェッチのいずれかで、コンポーネントに配信できます。デフォルトでは、地理マップを除くすべてのデータ視覚化コンポーネントで、コンテンツが使用可能なときにデータ・ソースから配信されるようになっています。これらのコンポーネントのcontentDelivery属性は、デフォルトでwhenAvailableに設定されています。

ガント・チャート、階層ビューア、ピボット・テーブル、サンバースト、時系列およびツリーマップなど、ツリーまたはツリー表モデルに基づくデータ視覚化コンポーネントは仮想化されており、サーバーでコンポーネント用に存在するすべての行、列またはレベルが、クライアントに配信されて表示されるわけではありません。これらのコンポーネントを構成して、一定の数の行、列またはレベルを一度にデータ・ソースからフェッチします。次の属性を使用して、フェッチ・サイズを構成します。

- ガント・チャート:

- fetchSize: データ・フェッチ・ブロックの行数を指定します。デフォルト値は25です。

- horizontalFetchSize: データがフェッチされる水平データ・ウィンドウのサイズをピクセル数で指定します。このデータ・ウィンドウ内のタスク・バーのみがレンダリングされます。垂直方向への仮想化を実現するfetchSizeとは対照的に、horizontalFetchSizeは水平方向への仮想化を実現します。

- 階層ビューア:

- levelFetchSize: 展開された親ノードごとに、一度にフェッチされて表示される子ノードの数を指定します。階層ビューアに表示される横方向のナビゲーション・コントロールを使用すれば、追加の子ノードをフェッチし、表示できます。デフォルト値は25です。

- ピボット・テーブル:

- rowFetchSize: 1データ・フェッチ・ブロック内の行数を指定します。デフォルト値は25です。

- columnFetchSize: 1データ・フェッチ・ブロック内の列数を指定します。デフォルト値は10です。

- サンバースト:

- displayLevelsChildren: 初期レンダリング中に表示する子レベルの数を指定します。このプロパティは0ベースです。値0は、ルートの下の子レベルが表示されず、ルート自体は表示されることを意味します。デフォルト値は2で、ルートおよび子の最初の2つのレベルが表示されることを意味します。

- 時系列:

- fetchStartTime: データを現時点でフェッチする時間範囲の開始を指定します。

- fetchEndTime: データを現時点でフェッチする時間範囲の終了を指定します。

- ツリーマップ:

- displayLevelsChildren: 初期レンダリング中に表示する子レベルの数を指定します。このプロパティは0ベースです。値0は、ルートの下の子レベルが表示されず、ルート自体は表示されることを意味します。デフォルト値は2で、ルートおよび子の最初の2つのレベルが表示されることを意味します。

遅延配信の場合、ページにこれらのコンポーネントが1つ以上含まれると、そのページでは最初は標準のライフサイクルが実行されます。ただし、最初のリクエスト時にデータがフェッチされるのではなく、特別な個別の部分ページ・レンダリング(PPR)リクエストが実行され、コンポーネントのフェッチ・サイズの値が返されますページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみがコンポーネントに対して実行され、対応するデータのフェッチおよび表示が可能になります。ユーザーのアクションにより後続のデータ・フェッチが実行される場合(別の行セットのためにピボット・テーブル・グリッド内をスクロールするなど)、別のPPRリクエストが実行されます。

コンテンツが使用可能なときに配信されるようにコンテンツ配信を構成すると、フレームワークでは最初のリクエストの間にデータの可用性をチェックし、使用可能であれば、そのデータがコンポーネントに送信されます。使用可能でない場合、データは遅延配信と同じように、別のPPRリクエスト時にロードされます。

パフォーマンスのヒント:

遅延配信は、データ・フェッチがコストの高い(低速な)操作と予想される場合、たとえば低速で待機時間の長いデータベース接続や、Webサービスなどの低速なデータ・ソースからのデータのフェッチなどに使用する必要があります。ページにデータ視覚化コンポーネント以外のコンポーネントが多数含まれている場合にも、遅延配信を使用します。遅延配信を使用すると、データが使用可能になる前に、初期ページのレイアウト・コンポーネントおよびその他のコンポーネントが最初にレンダリングされます。

ページではデータ視覚化コンポーネントが唯一のコンテキストである場合、あるいはコンポーネントから大量のデータが返される見込みがない場合は、即時配信を使用します。この場合、ユーザー・レスポンス時間がより高速で、サーバーCPU利用率がより高ければ、2番目のリクエストはサーバーに移動しないため、レスポンス時間は遅延配信を使用する場合よりも高速になります(または、場合によっては高速に感じます)。ツリーまたはツリー表モデルに基づくコンポーネントの場合、フェッチ・ブロックとして構成された値のみが最初に返されます。遅延配信と同様に、ユーザーのアクションが後続のデータ・フェッチの原因となる場合は、次の行セットが配信されます。

whenAvailable配信では、最初のレンダリング中にデータが使用可能な場合は即時配信を使用し、データが最初に使用可能でない場合には遅延配信に頼るという柔軟性が高まります。

ツリーまたはツリー表に基づくコンポーネントのフェッチ・サイズの設定の詳細は、12.2.2項「コンテンツ配信」を参照してください。

22.2.2 自動部分ページ・レンダリング(PPR)

ADF Facesでは部分ページ・レンダリング(PPR)がサポートされており、ページ上で特定のコンポーネントをレンダリングでき、ページ全体をレンダリングする必要がありません。組込みのPPR機能に加えて、1つのコンポーネントがトリガーとして機能し、別のコンポーネントがリスナーとして機能するように依存関係を設定できるクロスコンポーネント・レンダリングを使用するように、コンポーネントを構成できます。詳細は、8.1項「部分ページ・レンダリングについて」を参照してください。

デフォルトでは、ADFデータ視覚化コンポーネントで自動PPRがサポートされ、バックエンド・ビジネス・ロジックの結果として値が変更されるコンポーネントが自動的に再レンダリングされます。アプリケーションでFusionテクノロジ・スタックを使用する場合、任意のページで自動部分ページ・レンダリング機能を有効にできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の部分ページ・レンダリングとイテレータ・バインディングに関する必知事項を参照してください。

22.2.3 アクティブ・データ・サポート

Fusionテクノロジ・スタックには、アクティブ・データ・サービス(ADS)が含まれ、これはサーバー側のプッシュ・フレームワークで、これによりADF FacesコンポーネントおよびADFデータ視覚化コンポーネントのリアルタイムのデータ更新を提供できます。ADF Facesコンポーネントをデータ・ソースにバインドすると、ADSでは、ブラウザ・クライアントに明示的な更新リクエストを要求することなく、ブラウザ・クライアントにデータ更新をプッシュします。

表22-1に、アクティブ・データをサポートするDVTコンポーネントおよび追加詳細がある場所をリストします。グラフおよびゲージの場合、サポートはグラフおよびゲージ・タイプのサブセットに制限されます。

表22-1 アクティブ・データをサポートするDVTコンポーネント

DVTコンポーネント

コンポーネントの詳細へのリンク

ゲージ

24.6.6項「アクティブ・データを表示するゲージの構成方法」

地理マップ

28.2.4項「マップ点テーマのアクティブ・データ・サポートに関する必知事項」

グラフ

23.6.1項「アクティブ・データを表示するデータ・バインドされたグラフ・コンポーネントの構成方法」

ピボット・テーブルおよびピボット・フィルタ・バー

25.1.2.11項「アクティブ・データ・サポート(ADS)」

サンバースト

30.1.2.16項「アクティブ・データ・サポート(ADS)」

ツリーマップ

30.1.2.16項「アクティブ・データ・サポート(ADS)」

アクティブ・データ・サービスの使用の詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

22.2.4 グラフ、ゲージ、ツリーマップおよびサンバーストのコンテキスト・メニュー

グラフ、ゲージ、ツリーマップおよびサンバースト・コンポーネントに対して、次のコンテキスト・メニュー・ファセットを使用してコンテキスト・メニューを定義できます。

- bodyContextMenu: コンポーネント内の選択不可能な要素で表示されるコンテキスト・メニューを指定します。

- contextMenu: コンポーネント内の選択可能要素で表示されるコンテキスト・メニューを指定します。

- multiSelectContextMenu: コンポーネント内で複数の要素が選択されるときに表示されるコンテキスト・メニューを指定します。

各ファセットでは、1つの子コンポーネントがサポートされます。これらのファセットすべてを機能させるには、特定のグラフやゲージのタイプ用に選択を可能にし、サポートされるようにする必要があります。コンテキスト・メニューは、現在のところFlashおよびHTML5でのみサポートされています。

技術的な制限のために、Flashのレンダリング形式の使用時には、現在のところコンテキスト・メニューのコンテンツはFlash Playerのコンテキスト・メニューを使用して表示されます。このため、Flash Playerにより定義されたいくつかの制限があります。

- Flashでは、コンテキスト・メニューのサブメニューは使用できません。

- Flashでは、カスタム・メニュー項目は15に制限されます。コンポーネントの組込みメニュー項目(円グラフのinteractiveSliceBehaviorメニュー項目など)は、制限に考慮されます。

- Flashでは、メニュー項目がテキストのみに制限されます。ADF Facesメニューで使用可能なアイコンまたはその他のコントロールは、Flashのメニューでは使用できません。

- 各メニュー・キャプションには、最低1つの目に見える文字が含まれている必要があります。制御文字、改行文字およびその他の空白文字は無視されます。キャプションは100文字以内です。

- 別のカスタム項目と同一のメニュー・キャプションは、一致する項目が表示されようとされなかろうと無視されます。メニュー・キャプションは、組込みキャプションまたは既存のカスタム・キャプションと、大文字か小文字か、句読点または空白に関係なく比較されます。

- 単語はカスタム・キャプションを形成するために他の単語とともに使用できますが、次のキャプションは使用でません: 保存、ズーム・イン、ズーム・アウト、100%、すべて表示l、品質、再生、ループ、巻戻し、進む、戻る、ロードされない映画、バージョン情報、印刷、再描画リージョンの表示、デバッガ、元に戻す、切取り、コピー、貼付け、削除、すべて選択、開く、新規ウィンドウで開くおよびリンクのコピー。

- 次の単語は、単独または他の単語とともにカスタム・キャプションで表示できません: Adobe、Macromedia、Flash Playerまたは設定。

さらに、Flashからのコンテキスト・メニュー項目のリクエストは同期コールであるため、コンテキスト・メニューの呼出し時には、ELを評価するサーバー・リクエストは不可能です。選択したオブジェクトによって変わるコンテキスト・メニューを提供するために、コンテキスト・メニューのポップアップでcontentDelivery="lazyUncached"設定が使用される場合は、メニューが事前にフェッチされます。状況により変化するコンテキスト・メニューの場合、これはメニュー定義内のEL式が、異なる選択や通貨の状況により、レンダリング時に繰り返しコールされることを意味します。事前にフェッチされるこれらのコンテキスト・メニューの使用時には、アプリケーションで次のことが認識されている必要があります。

- コンテキスト・メニューをどのように表示するかを定義するために使用されるEL式では、長時間かかるまたは遅いコードは実行されません。これは、actionListenerなど、メニュー項目が選択された後にコールされるaf:commandMenuItem属性には当てはまりません。

- 将来、Flashの制限が解決されれば、Flashのコンテキスト・メニューのかわりにADFのコンテキスト・メニューが表示される可能性があります。アップグレードの互換性を確実にするには、メニューが事前フェッチされる場合、またメニューの呼出し時にEL式が評価される場合のどちらでも、EL式が機能するようなコードを作成する必要があります。アプリケーションが依存するコンポーネントの状態は、selectionとcurrencyのみです。

22.2.5 スクリーン・リーダーのサポート

すべてのデータ視覚化コンポーネントでは、そのコンポーネントについての説明文をサポートする属性が用意されています。スクリーン・リーダー・モードをサポートするには、そのコンポーネントの適切な属性を設定する必要があります。データ視覚化コンポーネントの次の属性を設定します。

- shortDesc属性: すべてのグラフおよびゲージ・コンポーネントに使用します。

- summary 属性: ピボット・テーブル、ガント・チャート、地理およびテーマ・マップ、階層ビューア、サンバースト、時系列およびツリーマップの各コンポーネントに使用します。

22.2.6 アプリケーション・リソース・バンドルのテキスト・リソース

JDeveloperは、抽象クラスjava.util.ResourceBundleを使用してロケール固有のリソースを提供し、ADF Facesおよびデータ視覚化コンポーネントをローカライズしやすいようにサポートします。

データ視覚化コンポーネントには、コンポーネントの一部であるテキストが含まれている場合があり、たとえばaf:tableコンポーネントでは、データの初期ロード中にaf:tableコンポーネントがデータをフェッチしている間、あるいはユーザーが表をスクロールしている間に、リソース文字列af_table.LABEL_FETCHINGが、ブラウザで表示されるメッセージ・テキストに使用されます。JDeveloperでは、これらのテキスト・リソースを28言語に自動的に変換します。これらのテキスト・リソースは、リソース・バンドルで参照されます。イタリア語を使用するようにブラウザを設定した場合、コンポーネント内に含まれるテキストはすべて自動的にイタリア語で表示されます。

text属性を子のgraphTitleコンポーネントで設定して、pieGraphコンポーネントのタイトルを定義する場合など、コンポーネントに追加するテキストには、実際のテキストが含まれているリソース・バンドルを指定して、各ロケール版のリソース・バンドルを作成し、<locale-config>要素を追加して、アプリケーションのfaces-config.xmlファイルにデフォルトおよびサポートされるロケールを定義する必要があります。また、アプリケーションのすべてのページでリソース・バンドルを使用できるようにするには、アプリケーションのfaces-config.xmlファイルに<resource-bundle>要素を追加する必要があります。リソース・バンドルを構成および登録すると、式言語(EL)エディタによりバンドルのキーが表示され、アプリケーション・ページでのバンドルの参照が簡単になります。

ADFコンポーネントに追加するテキストのテキスト・リソースを作成するプロセスを簡略化するために、JDeveloperでは、ビジュアル・エディタの変換可能な文字列に関する、リソース・バンドルの自動同期がサポートされています。ビジュアル・エディタまたは「プロパティ」ウィンドウで直接コンポーネントを編集すると、ベース・リソース・バンドルにテキスト・リソースが自動的に作成されます。詳細は、32.2項「JDeveloperにおける自動リソース・バンドル統合の使用方法」を参照してください。

注意:

データベースから取得されたテキストは変換されません。

タイトルおよびラベルの子コンポーネントのあるデータ視覚化コンポーネントの場合、属性ドロップダウン・リストを使用して「テキスト・リソースの選択」ダイアログを開き、アプリケーション・リソース・バンドルから変換可能な文字列を選択または追加することにより、テキスト・リソースを作成し、リソース・バンドルに追加することもできます。または、「式ビルダー」を選択して、式言語(EL)エディタを開き、実行時にタイトルまたはラベルのために実行される式を作成することができます。

22.3 ADFデータ視覚化コンポーネントへのデータの指定

JDeveloperでは、UI優先開発を使用して任意のデータ視覚化コンポーネントをJSFページに追加し、後からADFデータ・コントロールまたはマネージドBeanを使用して、表示するデータを手動でバインドできます。この場合、「コンポーネント」ウィンドウからページにコンポーネントをドラッグし、「プロパティ」ウィンドウでデータを手動でバインドします。

または、データ優先開発を使用すれば、データ・バインディングを処理するADFデータ・コントロールを使用してコンポーネントを作成できます。この場合、「データ・コントロール」パネルからデータ・コレクションをドラッグし、データ・バインディング・ダイアログに入力してデータの表示を構成します。

たとえば、簡単なUI優先開発を使用してページを設計しているときには、 「コンポーネント」ウィンドウを使用してグラフをJSFページに追加します。ページにグラフ・コンポーネントをドラッグ・アンド・ドロップすると、「グラフの作成」ダイアログに使用可能なグラフ・タイプのカテゴリが説明とともに表示され、グラフの作成を視覚的に支援します。グラフのタイトルおよび凡例のクイックスタート・レイアウトも指定できます。図22-15に、「コンポーネント」ウィンドウから円グラフを作成するときに表示される「円グラフの作成」を示します。

図22-15 「コンポーネント」ウィンドウからのドラッグによる「円グラフの作成」ダイアログ

UI優先開発を使用したデータ視覚化コンポーネントの作成、コンポーネント・データ要件の理解、DVT親コンポーネントおよび子コンポーネントの構成、コンポーネントの外観のカスタマイズ、およびコンポーネントへの特殊効果と双方向性の追加の詳細は、このマニュアルのこの部の次の章を参照してください。

- 第23章「グラフ・コンポーネントの使用方法」

- 第24章「ゲージ・コンポーネントの使用方法」

注意:

グラフとゲージにはtabularDataメソッドがあり、マネージドBeanに格納されたメソッドからCSV(カンマ区切りの値)データを提供できます。

- 第25章「ピボット・テーブル・コンポーネントの使用方法」

- 第26章「ガント・チャート・コンポーネントの使用方法」

- 第27章「時系列コンポーネントの使用方法」

- 第28章「マップ・コンポーネントの使用方法」

- 第29章「階層ビューア・コンポーネントの使用方法」

- 第30章「ツリーマップおよびサンバースト・コンポーネントについて」

データ・コントロール・パネルからデータ・コントロールをドラッグして、グラフの作成およびデータ・バインドもできます。コンポーネント・ギャラリには使用可能なグラフのカテゴリ、タイプおよび説明が表示され、グラフの設計およびクイック・レイアウトの定義が視覚的にサポートされます。図22-16に、データ・コントロールからの折れ線グラフ作成時に表示されるコンポーネント・ギャラリを示します。

図22-16 データ・コントロール・パネルから作成する折れ線グラフのコンポーネント・ギャラリ

図22-17に、データ・コレクション属性をグラフ・コンポーネントにバンドするために使用する「折れ線グラフの作成」ダイアログを示します。

図22-17 「折れ線グラフの作成」データ・バインディング・ダイアログ

すべてのデータ視覚化コンポーネントは、ADFデータ・コントロールのデータ・コレクションにバインドできます。データ・コントロールへのこれらのコンポーネントのデータ・バインドの詳細および例は、次の参照先を参照してください。

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたグラフの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたゲージの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたピボット・テーブルの作成に関する項

注意:

JDeveloperでは、「ピボット・テーブルの作成」ウィザードでピボット・テーブルのデータ・バインドおよび構成のための宣言サポートが提供されます。

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされた地理マップの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたテーマ・マップの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたガント・チャートの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされた時系列の作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされた階層ビューアの作成に関する項

- 『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたツリーマップおよびサンバーストの作成に関する項

23 グラフ・コンポーネントの使用方法

この章では、ADFデータ視覚化コンポーネントのareaGraph、barGraph、horizontalBarGraph、bubbleGraph、comboGraph、funnelGraph、lineGraph、paretoGraph、pieGraph、radarGraph、scatterGraph、sparkChartおよびstockGraphを使用し、簡単なUI優先開発を使用してデータをグラフに表示する方法について説明します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックを使用する場合、データ・コントロールを使用してグラフを作成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたグラフの作成に関する項を参照してください。

この章では、次の項目について説明します。

- 23.1項「グラフ・コンポーネントについて」

- 23.2項「グラフ・コンポーネントの使用方法」

- 23.3項「グラフ表示要素のカスタマイズ」

- 23.4項「グラフ・テキスト、色およびデータ値の書式設定」

- 23.5項「データの系列およびグループの外観のカスタマイズ」

- 23.6項「グラフへのアニメーションの使用」

- 23.7項「インタラクティブな機能のグラフへの追加」

23.1 グラフ・コンポーネントについて

グラフ・コンポーネントには、面グラフ、棒グラフ、バブル・グラフ、組合せグラフ、ファンネル・グラフ、折れ線グラフ、パレート・グラフ、円グラフ、レーダー・グラフ、散布図、スパークチャート、株価チャートなど、50種類以上のグラフを作成する機能が用意されています。このコンポーネントでは、複数軸の複数データ・ポイントを様々な方法で評価できます。たとえば、一群のグラフにより、あるグループからの結果と他のグループからの結果の比較が容易になります。

グラフには、データの系列およびグループが表示されます。系列とグループは、データのグリッドの行と列にたとえることができます。通常、グリッドの行はグラフの系列として表示され、グリッドの列はグラフのグループとして表示されます。

大半のグラフでは、系列は同じ色のマーカーのセットとして表示されます。通常、グラフの凡例に、各系列の識別子と対応する色が表示されます。たとえば、棒グラフで黄色の棒が靴の売上げを示し、緑色の棒がブーツの売上げを示す、などです。

グループの表示は、グラフ・タイプによって異なります。たとえば、集合棒グラフでは、各まとまりがグループです。積上げ棒グラフでは、各積層がグループです。複数円グラフでは、各円がグループです。グループは年などの期間を表す場合もあります。グループが地域などの地理上の場所を表す場合もあります。

グラフ・タイプのデータ要件に応じて、1つのグループに複数のデータ値が必要な場合があります。たとえば、散布図では、データ・マーカーごとに2つの値が必要です。1つ目の値はX軸上のマーカーの位置を決め、2つ目の値はY軸上のマーカーの位置を決めます。

23.1.1 グラフ・コンポーネントのユースケースおよび例

グラフ・コンポーネントには、データを表示するために使用できる13タイプのグラフがあり、合計50種を超えるグラフに1つ以上のバリエーションがあります。JDeveloperは、使用可能なグラフのカテゴリを表示する「コンポーネント」ウィンドウを提供しています。図23-1にグラフの「コンポーネント」ウィンドウを示します。

図23-1 グラフの「コンポーネント」ウィンドウ

「コンポーネント」ウィンドウでグラフのカテゴリを選択すると、JDeveloperで使用可能なグラフ・タイプに関する説明を含むダイアログが表示され、グラフの作成時に視覚的支援が提供されます。図23-2に、「コンポーネント」ウィンドウで棒グラフのカテゴリを選択した場合に使用できる各種棒グラフ・タイプとレイアウトを示します。

図23-2 「棒グラフの作成」ダイアログの棒グラフ・タイプ

グラフには次のタイプがあります。

- 面: データを塗りつぶされた面として表します。面グラフを使用して、過去12か月の売上げなど、ある期間の傾向を示します。面グラフでは、1つの軸上に最低2グループのデータが必要です。軸には、月などの時間の経過を表すラベルが付けられることがよくあります。
面グラフでは、次の種類のデータ値を表します。

- 絶対: 各面マーカーは、一連の(2つ以上の)データ値を結びます。この種のグラフのバリエーションとして、単一Yの絶対面グラフと分割二重Yの絶対面グラフがあります。
分割二重Yグラフでは、描画エリアが2つのセクションに分割され、異なるY軸に割り当てられたデータ・セットは異なる描画エリアに表示されます。

- 積上げ: 面マーカーが積み上げられます。各データ・セットの値は前のセットの値に加算されます。積層のサイズが累積合計を表します。この種のグラフのバリエーションとして、単一Y軸の積上げ面グラフと分割二重Y軸の積上げ面グラフがあります。

- パーセンテージ:面マーカーは、すべてのデータ・セットの累積合計に対する割合を表します。

図23-3に、デフォルトのグラフが選択されて「面グラフの作成」ダイアログに表示されている面グラフ・タイプのバリエーションを示します。

図23-3 面グラフ・タイプのバリエーション

図23-4に、面グラフの例を示します。

図23-4 面グラフの例

- 棒: データを一連の縦棒で表します。棒グラフを使用してある期間の傾向の確認や、複数の地域での異なる製品区分の売上げなど、同一時点での項目の比較を行います。
棒グラフでは、次の種類のデータ値を表します。

- 集合: 棒の各まとまりが1グループのデータを表します。たとえば、データが従業員で分類されている場合、特定の従業員の給与の棒と歩合の棒が1つのまとまりとなります。この種のグラフのバリエーションとして、集合縦棒グラフと集合横棒グラフがあります。集合棒グラフのすべてのバリエーションは、単一Yグラフ、二重Yグラフおよび分割二重Yグラフにできます。

- 積上げ: 各データ・セットの棒が前のデータ・セットに追加されます。積層のサイズがデータの累積合計を表します。この種のグラフのバリエーションとして、積上げ縦棒グラフと積上げ横棒グラフがあります。積上げ棒グラフのすべてのバリエーションは、単一Yグラフ、二重Yグラフおよび分割二重Yグラフにできます。

- パーセンテージ: 棒が積み上げられ、すべてのデータ・セットの累積合計に対する特定のデータ・セットの割合が表されます。パーセンテージ棒グラフは、単一Yグラフにのみできます。

図23-5に、デフォルトのグラフが選択されて「棒グラフの作成」ダイアログに表示されている棒グラフ・タイプのバリエーションを示します。

図23-5 棒グラフ・タイプのバリエーション

図23-6に、棒グラフの例を示します。

図23-6 棒グラフの例

- 横棒: Y軸に沿って棒を横向きに表示します。横棒グラフを使用して向きを持たせて傾向を表示したり、値を比較します。
図23-7に、デフォルトのグラフが選択されて「横棒グラフの作成」ダイアログに表示されている横棒グラフ・タイプのバリエーションを示します。

図23-7 横棒グラフ・タイプのバリエーション

図23-8に、横棒グラフの例を示します。

図23-8 横棒グラフの例

- バブル: 円形のデータ・マーカー(バブル)の位置とサイズでデータを表します。(データ項目が多数で全体の関係を表示する場合は特に)バブル・グラフを使用して3種類の値の相関関係を示します。たとえば、バブル・グラフを使用して、従業員の給与(X軸)、経験年数(Y軸)と生産性(バブルのサイズ)をプロットします。このようなグラフでは、生産性を給与および経験と比較して調べることができます。
図23-9に、デフォルトのグラフが選択されて「バブル・グラフの作成」ダイアログに表示されているバブル・グラフ・タイプのバリエーションを示します。

図23-9 バブル・グラフ・タイプのバリエーション

図23-10に、バブル・グラフの例を示します。

図23-10 バブル・グラフの例

- 組合せ: 異なるタイプのデータ・マーカー(棒、線または面)を使用して、異なる種類のデータ・アイテムを表示するグラフ。組合せグラフを使用して、棒と線、棒と面、線と面あるいは3つすべての組合せを比較します。
図23-11に、デフォルトのグラフが選択されて「組合せグラフの作成」ダイアログに表示されている組合せグラフ・タイプのバリエーションを示します。

図23-11 組合せグラフ・タイプのバリエーション

図23-12に、組合せグラフの例を示します。

図23-12 組合せグラフの例

- ファンネル: プロセスの段階に関連するデータを視覚的に表します。ステップは、横向きの円錐形のセクションに対する縦向きのスライスとして表されます。特定のステップ(スライス)の実際の値がそのスライスの割当てに近づいた分、スライスが塗りつぶされます。通常、ファンネル・グラフには、時間などのステージ値に対する実績値と目標値が必要です。たとえば、ファンネル・グラフを使用して、ファンネルの異なるセクションが販売周期の異なる段階を表すプロセスを表示します。ファンネル・グラフのバリエーションはありません。
図23-13に、ファンネル・グラフの例を示します。

図23-13 ファンネル・グラフの例

- 折れ線: データを線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとして表します。折れ線グラフには、グループ内のメンバーごとに最低2つのポイントを表すデータが必要です。たとえば、月ごとの折れ線グラフには最低2か月必要です。通常、特定の色の線は、アメリカ、ヨーロッパ、アジアなどのデータの各グループに関連付けられています。折れ線グラフを使用して、同一期間の項目を比較します。
折れ線グラフでは、次の種類のデータ値を表します。

- 絶対: 各線セグメントは2つのデータ・ポイントを結びます。この種のグラフでは、軸を単一Y、二重Yおよび分割二重Yにできます。

- 積上げ: 各データ・セットの線が前のデータ・セットに追加されます。積層のサイズがデータの累積合計を表します。この種のグラフでは、軸を単一Y、二重Yおよび分割二重Yにできます。

- パーセンテージ: 線が積み上げられ、各線がすべてのデータ・セットの累積合計に対する特定のデータ・セットの割合を表します。パーセンテージ折れ線グラフは、単一Y軸グラフにのみできます。

図23-14に、デフォルトのグラフが選択されて「折れ線グラフの作成」ダイアログに表示されている折れ線グラフ・タイプのバリエーションを示します。

図23-14 折れ線グラフ・タイプのバリエーション

図23-15に、折れ線グラフの例を示します。

図23-15 折れ線グラフの例

- パレート: 棒と棒の累積割合を示すパーセンテージ線でデータを表します。各棒は、交通事故の原因など、異なる不具合の原因を表します。棒は、発生件数の多いものから少ないものの順に並べられます。パレート・グラフは常に二重Yグラフで、1つ目のY軸は棒が表す値に対応し、2つ目のY軸は0%から100%を表し、累積割合の値に対応します。パレート・グラフを使用して、不具合の原因を特定し、比較します。パレート・グラフにはバリエーションはありません。
図23-16に、パレート・グラフの例を示します。

図23-16 パレート・グラフの例

- 円/ドーナツ: 1つのグループのデータが円のセクションとして表され、円が切り分けられたパイのように見えます。円グラフを使用して、各製品ラインからの収益など、全体に対する各部分の関係を表します。円グラフは、円またはドーナツ型(各円の中心が穴となり、その中に円の合計値が表示される)として表示できます。
図23-17に、デフォルトのグラフが選択されて「円グラフの作成」ダイアログに表示されている円グラフ・タイプのバリエーションを示します。

図23-17 円グラフ・タイプのバリエーション

図23-18に、円グラフの例を示します。

図23-18 円グラフの例

- レーダー: 円形の折れ線グラフとして表されるグラフ。過去3年間の月ごとの売上げなどの周期的に起こるパターンを表す場合に、レーダー・グラフを使用します。レーダー・グラフにはバリエーションはありません。
図23-19に、レーダー・グラフの例を示します。

図23-19 レーダー・グラフの例

- 散布/極: データをデータ・マーカーの位置で表します。散布図を使用して、上位製品の売上げとコストなど、異なる2種類のデータの相関関係を表します。多数の項目の全体的な関係を表す場合は特に散布図を使用します。散布図では、極グラフとして方向性を持ってデータを表示できます。
図23-20に、デフォルトのグラフが選択されて「散布図の作成」ダイアログに表示されている散布図タイプのバリエーションを示します。

図23-20 散布図タイプのバリエーション

図23-21に、散布図の例を示します。

図23-21 散布図の例

- スパークチャート: 傾向や変化を1つのデータ値で表す簡単な縮小グラフで、通常、表の列内や関連テキストの行中に表示されます。スパークチャートには、基本的な条件付きフォーマットがあります。スパークチャートにはラベルが含まれていないため、近くの表の列や周りのテキストによってスパークチャートの内容のコンテキストがわかります。
図23-22に、デフォルトのグラフが選択されて「スパークチャート・グラフの作成」ダイアログに表示されているスパークチャート・グラフ・タイプのバリエーションを示します。

図23-22 スパークチャート・グラフ・タイプのバリエーション

図23-23に、スパークチャートの例を示します。

図23-23 棒スパークチャートの例

- 株価: データを株式の高値、低値および終値として示します。各株価マーカーは、選択された株価チャートの種類に応じて2から4個(オプションの出来高マーカー以外)の異なる値を表します。株式グラフでは、株価を表示し、必要に応じてグラフに1つ以上の株式の取引出来高も表示できます。株価またはローソク足株価チャートが出来高を含む場合、出来高はグラフの下部に棒で表示されます。
ローソク足株価チャートは株価を表し、オプションで1つの株の出来高を表示します。ローソク足株価チャートが出来高を含む場合、出来高はグラフの下部に棒で表示されます。

ローソク足株価チャートでは、始値と終値のうち低い方の値がローソクの下端で示されます。高い方の値がローソクの上端で示されます。終値が始値より高い場合、ローソクは緑色です。始値が終値より高い場合、ローソクは赤色です。

図23-24に、デフォルトのグラフが選択されて「株式グラフの作成」ダイアログに表示されている株式グラフ・タイプのバリエーションを示します。

図23-24 株価チャート・タイプのバリエーション

図23-25に、ローソク足株価チャートの例を示します。

図23-25 ローソク足株価チャートの例

23.1.2 エンド・ユーザー機能およびプレゼンテーション機能

グラフのエンド・ユーザー機能および構成可能なプレゼンテーション機能には、豊富なオプションが揃っています。

23.1.2.1 グラフ・レイアウト

オプションのグラフ・タイトル、サブタイトル、脚注、凡例および軸タイトルの各コンポーネントは、配置や外観をカスタマイズできます。すべてのグラフに存在する描画エリアは、外観をカスタマイズできます。図23-26に、棒グラフ用のこれらのグラフ・コンポーネントのデフォルト表示を示します。

図23-26 グラフ・レイアウト・コンポーネント

23.1.2.2 サイズ設定

グラフは、400 X 300ピクセルのデフォルト・サイズで表示されます。グラフのサイズをカスタマイズしたり、様々なブラウザ・ウィンドウ・サイズに領域がぴったり合うように、動的サイズ変更を指定したりできます。水平または垂直に制限された領域(Webページのサイドバーなど)にグラフが表示される場合、グラフは機能は揃っているものの、簡易表示で表示されます。

23.1.2.3 イメージ形式

グラフでは、HTML5、FlashおよびPNGなどのイメージ形式がサポートされています。デフォルトでは、新しいアプリケーションはHTML5に設定されますが、デフォルトのイメージ形式を変更できます。アプリケーションでFlashを無効にすることや、クライアント・プラットフォームでFlash Playerの動作をカスタマイズすることもできます。

23.1.2.4 データ・マーカー選択

バブル・グラフのバブルや散布図の形状など、グラフではデータ・マーカーの単一または複数の選択を有効にできます。コンテキスト・メニューを表示したり、ユーザーがデータ・マーカーをクリックしたときにプログラムで応答したりするには、選択を有効にする必要があります。

図23-27に、選択が有効な棒グラフを示します。各データ・マーカーは、その上を移動すると強調表示され、マーカーが選択可能であることが視覚的に示されます。

図23-27 選択サポートが有効な棒グラフ

23.1.2.5 コンテキスト・メニュー

グラフでは、次の3タイプのいずれかのファセットを使用する右クリック・コンテキスト・メニューがサポートされます。

- コンポーネント内で選択できない領域に表示されるコンテキスト・メニュー(描画エリアなど)

- 選択可能要素(散布図のマーカーなど)で表示されるコンテキスト・メニュー

- 複数選択可能要素で表示されるコンテキスト・メニュー

図23-28に、散布図で選択されたマーカーに表示されるコンテキスト・メニューを示します。

図23-28 散布図で選択されたマーカーのコンテキスト・メニュー

23.1.2.6 参照面/線およびアラート

グラフは、データ参照面または参照線がグラフの系列または軸に関連付けられるように構成できます。これとは別に、エラーや警告など、個別の記号で強調表示する必要のある追加のデータ・ポイントを定義するように、グラフを構成することができます。図23-29に、グラフのアラート範囲内の棒ごとに警告アラート・アイコンの付いた棒グラフを示します。図には、参照面を変更するためにグラフと関連付けることのできるADF入力範囲スライダも示しています。

図23-29 棒グラフでのアラート

23.1.2.7 系列の非表示および表示

グラフは、グラフ・データ内で表示される1つ以上の系列を非表示にしたり、表示したりするように構成できます。これは、特に複数の系列が表示されている場合、比較や分析のために役立ちます。図23-30に、折れ線グラフでの非表示および表示を示します。非表示系列のデフォルトのアイコンは、空のボックスです。

図23-30 折れ線グラフでの非表示および表示

23.1.2.8 ドリル

データ・バインドされたグラフ内の系列およびグループは、データの集計合計とディテール・ビュー間でドリルアップおよびドリルダウンができるように構成できます。図23-31に、全車の合計販売台数と、メルセデス・ベンツの4タイプのロンドンおよびパリにおける販売台数のディテール・ビューを示します。ドリル・ビューには、アクティブなドリル・アイコンが表示されています。

図23-31 棒グラフでのドリル

23.1.2.9 注釈

注釈は、グラフ・データの重要な値を呼び出すために使用できます。図23-32に、折れ線グラフの注釈の例を示します。

図23-32 折れ線グラフの注釈

23.1.2.10 ポップアップのサポート

グラフ・コンポーネントは、情報を提供したり、エンド・ユーザーからの入力を要求したりするポップアップのダイアログ、ウィンドウおよびメニューが表示されるように構成できます。図23-33に、グラフ内でゲージ・コンポーネントを表示するポップアップを示します。

図23-33 散布図内のポップアップ

23.1.2.11 時間セレクタ

時間軸のあるグラフには、ユーザーが時間軸で時間範囲を選択できる時間セレクタが組み込まれるように構成できます。図23-34に、グラフ内にマスター/ディテール・データを表示するためにユーザーが有効にした時間セレクタを示します。ユーザーが折れ線グラフで時間セレクタを移動すると、棒グラフが変化し、選択した期間のデータが表示されます。

図23-34 折れ線グラフでの時間セレクタ

23.1.2.12 双方向サポート

グラフ用のすべてのイメージ形式で、双方向ロケールがサポートされます。図23-35に、複数の円グラフ内の双方向サポートを示します。

図23-35 複数の円グラフでの双方向サポート

23.1.2.13 ドラッグ・アンド・ドロップ

グラフは、次のドラッグ・アンド・ドロップ操作をサポートするように構成できます。

- グラフ間のドラッグ・アンド・ドロップ

- グラフから別のADFコンポーネントへのドラッグ・アンド・ドロップ

- グラフの描画エリア内での散布/バブル・マーカーのドラッグ

- 別のコンポーネントへの散布/バブル・マーカーのドラッグ

- 複数のマーカーのドラッグ・アンド・ドロップ

23.1.2.14 スクリーン・リーダーのサポート

スクリーン・リーダーでWebページを読む視覚障害のユーザーをサポートするために、そのアプリケーションに対してスクリーン・リーダーが有効であるとき、グラフは自動的にピボット・テーブルに置き換えられます。スクリーン・リーダーでは、グラフ内よりピボット・テーブル内の方がデータのナビゲートや読上げが容易になります。スクリーン・リーダー・モードの有効化の詳細は、33.2項「ADF Facesでのアクセシビリティ・サポートの構成」を参照してください。ADFピボット・テーブルの詳細は、25.1項「ピボット・テーブル・コンポーネントについて」を参照してください。

23.1.3 グラフ・コンポーネントの追加機能

グラフ・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんグラフ・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。グラフ・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、グラフをリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: 有効な場合、ユーザーは実行時にグラフの表示方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: グラフ・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされたグラフを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたグラフの作成に関する項を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

23.2 グラフ・コンポーネントの使用方法

グラフのデータ要件はグラフ・タイプによって異なります。データ要件は次のいずれかです。

- 幾何学的:一部のグラフ・タイプでは、データの表示に特定の数のデータ・ポイントが必要です。たとえば、線には最低2つの点が必要なため、折れ線グラフには最低2グループのデータが必要です。

- 複雑:一部のグラフ・タイプでは、マーカー(グラフで実際にデータを表すコンポーネント)ごとに複数のデータ・ポイントが必要です。たとえば、散布図では、X軸とY軸に沿ってマーカーを置けるよう、グループごとに2つの値が必要です。各グループに必要なデータ・ポイントがグラフに使用したデータにない場合、グラフ・コンポーネントでは可能な範囲でグラフを表示します。

- 論理的:一部のグラフ・タイプでは特定の種類のデータを受容しません。次に例を示します。

- 負のデータ:円グラフまたはパーセンテージ棒グラフ、折れ線グラフ、面グラフには負のデータを渡すことはできません。パーセンテージ・グラフでは負のデータに対するマーカーは表示されません。

- nullまたはゼロのデータ:nullデータに対するマーカーは生成されないため、nullデータのマーカーは表示されません。また、グラフがゼロ・データを受け取り、軸線がゼロにある場合、マーカーは見えません。ただし、軸線がゼロ以外にある場合、ゼロ・マーカーは見えます。

- 不十分なデータ・セット(系列): 二重Yグラフでは、Y軸ごとにデータ・セットが必要です。通常、セットごとに異なる情報を表します。たとえば、Y1軸は特定の国および期間の売上げを表し、Y2軸はすべての国の売上げ合計を表します。Y軸データを1セットのみ渡した場合、グラフは2つの異なるY軸にデータを表示できません。データは1つのY軸に表示されます。

類似するグラフは、類似するデータ要件を共有します。たとえば、面グラフというカテゴリでは、次のようにグラフをグループ分けできます。

- 絶対面グラフ。

- 積上げ面グラフ。

- パーセンテージ面グラフ。

23.2.1 グラフ・タイプのデータ要件

各グラフ・タイプの特定のデータ要件は、次のように定義されています。

- 面グラフ:

- 面グラフには最低2グループのデータが必要です。グループは、すべての面マーカーを通る横軸に沿った位置で表されます。3か月間のデータを示すグラフでは、このグループにJan、FebおよびMarなどのラベルが付けられます。

- 面グラフには1つ以上のデータ系列が必要です。塗りつぶされた領域はデータの系列またはセットを表し、アメリカ、ヨーロッパ、アジアなどの凡例テキストでラベルが付けられます。

- パーセンテージ面グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

- 棒および横棒グラフ:

- パーセンテージ棒グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

- バブル・グラフ:

- 1つのデータ・マーカーにつき最低3つのデータ値が必要です。バブル・グラフの各データ・マーカーは3グループの値を表します。

- マーカーのX軸上の位置を決めるX値。

- マーカーのY軸上の位置を決めるY値。

- マーカーのサイズを決めるZ値。

- 複数グループのデータの場合、バブル・グラフでは3の倍数のデータが必要です。たとえば、特定のバブル・グラフで、Parisに3つ、Tokyoに3つなどのように値が必要です。3つの値の例には、X値が平均寿命、Y値が平均所得、Z値が人口を表す場合などがあります。

注意:

バブル・グラフを見る際、マーカーのツールチップを確認することでデータ・グループを特定できます。ただし、グループを特定することは、データ・マーカーの全体的なパターンをつかむことに比べると重要ではありません。

- 組合せグラフ:

- 組合せグラフには最低2セットのデータが必要です。そうでない場合、異なるマーカー・タイプを表示できません。

- 組合せグラフには最低2グループのデータが必要です。そうでない場合、面マーカーまたは線マーカーをレンダリングできません。

- ファンネル・グラフ:

- ファンネル・グラフには最低2系列(データ・セット)が必要です。これらの2セットのデータは、目標データ値と実績データ値となります。しきい値はグラフの凡例に表示されます。
ファンネル・グラフのもう1つのバリエーションでは、1セットのデータのみが必要で、ここに表示されるデータ値は合計値の割合です。このタイプのファンネル・グラフを作成するには、グラフのfunnelPercentMeasureプロパティをTrueに設定する必要があります。この設定は、グラフ用のXMLで行います。

- ファンネル・グラフでは、最低1グループのデータをステージとして使用する必要があります。

- 折れ線グラフ:

- 線には最低2つの点が必要なため、折れ線グラフには最低2グループのデータが必要です。グループは各色のマーカーで表されます。グループには、月の名前などのティック・ラベルが付けられます。

- パーセンテージ折れ線グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

- パレート・グラフ:

- パレート・グラフには最低2グループのデータが必要です。

- パレート・グラフは負の数値を持つことができません。

- パレート・グラフに複数セットのデータを渡した場合、最初のデータ・セットのみが使用されます。

- パレート・グラフに対するデータの一部としてパーセンテージ値を渡さないでください。グラフは渡されたデータを基にパーセンテージを計算します。

- 円グラフとドーナツ・グラフ:

- 円またはドーナツ・グラフには最低1グループのデータが必要です。データ構造は次のとおりです。

- 各円またはドーナツは1グループのデータを表し、月の名前などのラベルが付きます。1グループのデータのみの場合、複数円または複数ドーナツ・グラフ・タイプを選択しても、1つの円またはドーナツのみが表示されます。また、すべてのデータがゼロのグループがある場合、そのグループに対する円またはドーナツは表示されません。

- データの系列またはセットは、すべて同じ色のスライスで示されます。各データ・セットの凡例テキストが表示されます。たとえば、国別のデータ・セットがある場合、各国の名前が凡例テキストに表示されます。

- 円グラフは負の数値を持つことができません。

- 複数の円グラフには最低2セットのデータが必要です。

- 極グラフ:
極グラフは、方向性のアスペクトを持つ円形の散布図です。極グラフの各マーカーには最低2つのデータ値が必要です。各データ・マーカーは次の値を表します。

- X軸上のマーカーの位置を決めるX値で、円の周りの右回りの位置です。

- Y軸上のマーカーの位置を決めるY値で、グラフの中心からの距離です。

- レーダー・グラフ:
レーダー・グラフには最低3グループのデータが必要です。データ構造は次のとおりです。

- 多角形の辺の数とデータのグループの数は同数です。多角形の各角がグループを表します。

- データの系列またはセットは、線またはすべて同じ色のマーカー、あるいはその両方で示されます。凡例テキストでラベル付けされます。

- 散布図:

- 散布図の各マーカーには最低2つのデータ値が必要です。散布図は単一Y軸または二重Y軸にできます。各データ・マーカーは次の値を表します。

- マーカーのX軸上の位置を決めるX値。

- マーカーのY軸上の位置を決めるY値。

- 複数グループのデータの場合、データは2の倍数である必要があります。

- スパークチャート:

- スパークチャートでは、表のデータやgraphDataModelは使用できません。

- 折れ線、棒および面スパークチャートには、1系列のデータ値が必要です。

- 浮動棒スパークチャートには、2系列のデータ値(フロート・オフセットの系列と棒値の系列)が必要です。

- 株価チャート:

- 株価: 高値-安値-終値

- 各株価マーカーには、高値、安値、終値の順の3つのデータ値のグループが必要です。2日以上の株価データを表示する場合、月曜日に3つのデータ値、火曜日に3つのデータ値のように、データは3の倍数である必要があります。

- データの系列(セット)は、1つの株を表す同じ色のマーカーで示されます。系列はA株のように凡例テキストでラベル付けされます。1つの株のみの場合でも、ローソク足チャートを除き、凡例が表示されます。大半の高値-安値-終値株価チャートの系列は1つのみです。複数の系列を表示し、異なる株の値が重なる場合、株価マーカーによって他の株価マーカーが覆われます。

- 株価: 高値-低値-終値と出来高:

- 各株価マーカーには、高値、安値、終値、出来高の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、データは4の倍数で、月曜日の高値、月曜日の安値、月曜日の終値、月曜日の出来高(他の曜日に続く)の順である必要があります。

- 出来高も表示する高値-安値-終値株価チャートでは、1つの株のみのデータを表示できます。この株のラベルはグラフの凡例に表示されます。

- 株価: 始値-高値-低値-終値

- 各株価マーカーには、始値、高値、安値、終値の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に4つのデータ値、火曜日に4つのデータ値のように、データは4の倍数である必要があります。

- データの系列(セット)は、1つの株を表す同じ色のマーカーで示されます。系列はA株のように凡例テキストでラベル付けされます。1つの株のみの場合でも凡例は表示されます。大半の始値-高値-安値-終値株価チャートの系列は1つのみです。複数の系列を表示し、異なる株の値が重なる場合、株価マーカーによって他の株価マーカーが覆われます。

- 株価: 始値-高値-低値-終値と出来高

- 各株価マーカーには、始値、高値、安値、終値、出来高の順の5つのデータ値のグループが必要です。1日以上の株価データを表示する場合、データは5の倍数で、月曜日の始値、月曜日の高値、月曜日の安値、月曜日の終値、月曜日の出来高(他の曜日に続く)の順である必要があります。

- 出来高も表示する始値-高値-安値-終値株価チャートでは、1つの株のみのデータを表示できます。この株のラベルはグラフの凡例に表示されます。

- ローソク: 始値-終値

- 各株価マーカーには、始値、終値の順の2つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に2つのデータ値、火曜日に2つのデータ値のように、データは2の倍数である必要があります。

- 1つの系列(データのセット)は、1つの株のマーカーで表されます。ローソク足チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されず、グラフのタイトルに系列のラベル(株式名)を示します。

- ローソク: 始値-終値と出来高

- 各株価マーカーには、始値、終値、出来高の順の3つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に3つのデータ値、火曜日に3つのデータ値のように、データは3の倍数である必要があります。

- 1つの系列(データのセット)は、1つの株のマーカーで表されます。ローソク足チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されず、グラフのタイトルに系列のラベル(株式名)を示します。

- ローソク: 始値-高値-低値-終値

- 各株価マーカーには、始値、高値、安値、終値の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に4つのデータ値、火曜日に4つのデータ値のように、データは4の倍数である必要があります。

- 1つの系列(データのセット)は、1つの株のマーカーで表されます。ローソク足チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されず、グラフのタイトルに系列のラベル(株式名)を示します。

- ローソク: 始値-高値-低値-終値と出来高

- 各株価マーカーには、始値、高値、安値、終値、出来高の順の5つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に5つのデータ値、火曜日に5つのデータ値のように、データは5の倍数である必要があります。

- 1つの系列(データのセット)は、1つの株のマーカーで表されます。ローソク足チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されず、グラフのタイトルに系列のラベル(株式名)を示します。

23.2.2 グラフの構成

多くのグラフ・タイプとグラフ・コンポーネントの高い柔軟性のために、グラフには多数のDVTタグがあります。接頭辞dvt:は、各グラフ・タグ名の先頭に付いて、そのタグがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。次のリストに、グラフ・コンポーネントに関連するタグのグループを示します。

- グラフ・コンポーネント・タグ: 13個のグラフ・コンポーネント・タグは、よく使用されるグラフ・タイプを作成する簡便な方法です。それらは、「コンポーネント」ウィンドウにグラフのカテゴリとして、1つ以上のタイプ・バリエーションとともに表示されます。
表23-1では、グラフ・コンポーネント・タグと、そのグラフ・コンポーネントのsubType属性で指定されているバリエーションについて説明しています。

表23-1 グラフ・コンポーネントのタグおよびサブ・タイプ

グラフ・タグ

説明

サブ・タイプ

areaGraph

データを塗りつぶされた面として表します。

AREA_VERT_ABS
AREA_VERT_ABS_SPLIT2Y
AREA_VERT_PERCENT
AREA_VERT_STACK
AREA_VERT_STACK_SPLIT2Y

barGraph

データを一連の縦棒で表します。

BAR_VERT_CLUST
BAR_VERT_CLUST_SPLIT2Y
BAR_VERT_CLUST2Y
BAR_VERT_FLOAT_STACK
BAR_VERT_PERCENT
BAR_VERT_STACK
BAR_VERT_STACK_SPLIT2Y
BAR_VERT_STACK2Y

bubbleGraph

円形のデータ・マーカー(バブル)の位置とサイズでデータを表します。

BUBBLE
BUBBLE_2Y

comboGraph

異なるタイプのデータ・マーカー(棒、線または面)を使用して、異なる種類のデータ・アイテムを表示します。

COMBINATION_VERT_ABS
COMBINATION_VERT_ABS_2Y

funnelGraph

プロセスの段階に関連するデータを視覚的に表します。ステップは、横向きの円錐形のセクションに対する縦向きのスライスとして表されます。

FUNNEL

horizontalBarGraph

データをY軸に沿った横向きの棒として表示します。

BAR_HORIZ_CLUST
BAR_HORIZ_CLUST_SPLIT2Y
BAR_HORIZ_CLUST2Y
BAR_HORIZ_PERCENT
BAR_HORIZ_STACK
BAR_HORIZ_STACK_SPLIT2Y
BAR_HORIZ_STACK2Y

lineGraph

データを線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとして表します。

LINE_VERT_ABS
LINE_VERT_ABS_2Y
LINE_VERT_ABS_SPLIT2Y
LINE_VERT_PERCENT
LINE_VERT_STACK
LINE_VERT_STACK_SPLIT2Y
LINE_VERT_STACK2Y

paretoGraph

棒と棒の累積割合を示すパーセンテージ線でデータを表します。

PARETO

pieGraph

1つのグループのデータが円のセクションとして表され、円が切り分けられたパイのように見えます。円グラフは、円またはドーナツ型(各円の中心が穴となり、その中に円の合計値が表示される)として表示できます。

PIE
PIE_BAR
PIE_MULTI
RING
RING_BAR
RING_MULTI

radarGraph

円形の折れ線グラフとして表されます。

RADAR_LINE

scatterGraph

データをデータ・マーカーの位置で表します。散布図では、極グラフとして方向性を持ってデータを表示できます。

SCATTER
SCATTER_2Y
POLAR

sparkChart

傾向や変化を1つのデータ値で表す簡単な縮小グラフで、通常、表の列内や関連テキストの行中に表示されます。

area
bar
floatingBar
line

stockGraph

株価を表示し、必要に応じてグラフに1つ以上の株式の取引出来高も表示できます。株価またはローソク足株価チャートが出来高を含む場合、出来高はグラフの下部に棒で表示されます。

STOCK_CANDLE
STOCK_CANDLE_VOLUME
STOCK_HILO_CLOSE
STOCK_HILO_CLOSE_VOLUME
STOCK_OHLC_CANDLE
STOCK_OHLC_CANDLE_VOLUME
STOCK_OPEN_HILO_CLOSE
STOCK_VOLUME

- 一般的なグラフの子タグ: これらのタグは、様々なカスタマイズ・オプションを提供するために、大部分のグラフ・コンポーネント・タグでサポートされます。
表23-2は、これらのタグのリストと説明です。

表23-2 一般的なグラフの子タグ

子タグ

説明

animationOnDisplay
animationOnDataChange

グラフのアニメーション効果の構成。

background
graphFont
graphFootnote
graphPlotArea
graphSubTitle
graphTitle

タイトルを含むグラフ要素の外観のカスタマイズ。

attributeFormat

順序軸およびマーカー・ツールチップでカテゴリの属性をフォーマット。

legendArea
legendText
legendTitle

グラフの凡例のカスタマイズ。

markerText
x1Format
y1Format
y2Format
zFormat

各軸関連のマーカーのカスタマイズ。

o1Axis
o1MajorTick
o1TickLabel
o1Title

棒、面、組合せ、折れ線、レーダーおよび株価チャートとともに使用する順序軸(カテゴリ軸)をグループ・ラベルでカスタマイズ。

x1Axis
x1MajorTick
x1TickLabel
x1MinorTick
x1Title

散布図およびバブル・グラフとともに使用するX軸を数値ラベルでカスタマイズ。

y1Axis
y1MajorTick
y1TickLabel
y1MinorTick
y1Title

Y1軸のカスタマイズ。

- 子セット・タグ:これらのタグは、無数の関連するタグのセットをラップします。
表23-3は、これらのタグのリストと説明です。

表23-3 グラフの子セット・タグ

子セット・タグ

説明

alertSet

エラーや警告など、個別の記号で強調表示する必要のある追加データ・ポイントを定義するdvt:alertタグをラップします。

annotationSet

グラフ上に注釈を定義するdvt:annotationタグをラップします。注釈は、グラフ上の特定のデータ・ポイントと関連付けられます。

referenceObjectSet

グラフに対する参照線または参照領域を定義するdvt:referenceObjectタグをラップします。指定したグラフに対して参照オブジェクトをいくつでも定義できます。

seriesSet

グラフ上のデータ・マーカーまたは系列のセットを定義するdvt:seriesタグをラップします。

shapeAttributesSet

グラフのサブコンポーネントに相互作用プロパティを指定するdvt:shapeAttributesタグをラップします。

いずれの場合にも、設計中にまずラッパー・タグを作成し、その後にセット内の各アイテムの関連タグを作成する必要があります。例23-1に、面グラフの2つのアラート・ポイントを定義するアラート・タグのセットを作成する場合のタグのシーケンスを示します。

例23-1 アラート・タグのセットのサンプル・コード

<dvt:areaGraph id="areaGraph1" subType="AREA_VERT_ABS">
<dvt:background>
<dvt:specialEffects/>
</dvt:background>
<dvt:graphPlotArea/>
<dvt:alertSet>
<dvt:alert xValue="Boston" yValue="3.50"
yValueAssignment="Y1AXIS" imageSource="myWarning.gif"/>
<dvt:alert xValue="Boston" yValue="5.50"
yValueAssignment="Y1AXIS" imageSource="myError.gif"/>
</dvt:alertSet>
<dvt:o1Axis/>
<dvt:y1Axis/>
<dvt:legendArea automaticPlacement="AP_NEVER"/>
</dvt:areaGraph>

- グラフ固有の子タグ: これらのタグは、特定のグラフ・タイプまたはグラフの特定部分に使用します。
表23-4は、これらのタグのリストと説明です。

表23-4 グラフ固有の子タグ

子タグ

説明

specialEffects
gradientStopStyle

dvt:background、dvt:legendArea、dvt:graphPlotArea、dvt:graphPieFrame、dvt:series、dvt:referenceObjectまたはdvt:timeSelector子コンポーネントとの組合せでのみグラフに使用されるグラデーション。

sliceLabel
x1TickLabel
y2TickLabel
y1TickLabel
x1Format
y1Format
y2Format
zFormat
stockVolumeFormat

グラフの数値データの値の書式設定。

timeAxisDateFormat
timeSelector

面、棒、組合せ、折れ線および積上げ棒グラフの時間軸のカスタマイズ。

timeSelector

マスター/ディテール・グラフの時間軸上の範囲の選択。

paretoLine
paretoMarker

パレート・グラフのカスタマイズ。

graphPieFrame
slice
sliceLabel

円グラフのカスタマイズ。

sparkItem

スパークチャートのカスタマイズ。

stockMarker
stockVolumeformat
volumeMarker

株価チャートのカスタマイズ。

すべてのタグとその属性の詳細、および有効な値のリストは、DVTタグのドキュメントを参照してください。JDeveloperで特定のグラフ・タグのこのドキュメントにアクセスするには、構造ウィンドウでタグを選択し、[F1]キーを押すか、「ヘルプ」をクリックします。

23.2.3 ページへのグラフの追加方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用してグラフをJSFページに追加します。ページにグラフ・コンポーネントをドラッグ・アンド・ドロップすると、「グラフの作成」ダイアログに使用可能なグラフ・タイプのカテゴリが説明とともに表示され、グラフの作成を視覚的に支援します。グラフのタイトルおよび凡例のクイックスタート・レイアウトも指定できます。図23-36に、デフォルトの縦方向の集合棒グラフ・タイプが選択された棒グラフ用「棒グラフの作成」ダイアログを示します。

図23-36 縦方向の集合棒グラフ用の「棒グラフの作成」ダイアログ

ダイアログが完了して、ページにグラフが追加されると、「プロパティ」ウィンドウを使用して、データ値を指定し、グラフに追加の表示属性を構成できます。

「プロパティ」ウィンドウで、プロパティ・フィールドにマウス・カーソルを合わせると表示されるアイコンをクリックすることで、プロパティの説明や編集オプションを表示できます。図23-37に、棒グラフ・コンポーネントのvalue属性のドロップダウン・メニューを示します。

図23-37 棒グラフ・コンポーネントのValue属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してグラフを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフの作成」の章を参照してください。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにグラフを追加する手順:

1. 「コンポーネント」ウィンドウで、「ADFデータ視覚化」ページの「グラフとゲージ」パネルから希望するグラフのカテゴリをページにドラッグ・アンド・ドロップし、「グラフの作成」ダイアログを開きます。

2. ダイアログを使用して、グラフ・タイプと、グラフ・タイトル、凡例およびラベルの表示用クイック・スタート・レイアウトを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 「OK」をクリックしてグラフをページに追加します。

4. 「プロパティ」ウィンドウで、グラフの属性を確認します。ヘルプ・ボタンを使用して、グラフ・タイプ・コンポーネントの完全なタグ・ドキュメントを表示します。

5. 「共通」セクションを開きます。このセクションを使用して、次の属性を設定します。

- SubType: グラフ・タイプのバリエーションを変更する場合は、属性ドロップダウン・メニューから希望するタイプを選択します。グラフによって有効な値は異なります。
たとえば、棒グラフに対する有効な値は次のとおりです。

- BAR_VERT_CLUST: 縦向きの集合棒グラフ。

- BAR_VERT_CLUST_SPLIT2Y: 集合縦棒分割二重Yグラフ。

- BAR_VERT_CLUST2Y: 集合縦棒二重Yグラフ。

- BAR_VERT_FLOAT_STACK: フローティング積み上げ縦棒グラフ。

- BAR_VERT_PERCENT: パーセント縦棒グラフ。

- BAR_VERT_STACK: 積上げ縦棒グラフ。

- BAR_VERT_STACK_SPLIT2Y: 積上げ縦棒分割二重Yグラフ。

- BAR_VERT_STACK2Y: 積上げ縦棒二重Yグラフ。

6. 「グラフ・データ」セクションを開きます。次のフィールドの値を設定して、グラフのデータ値を指定します。

- Value: EL式を使用してデータ・モデル(DataModelのインスタンス)を指定します。または、メトリック値をJava.lang.NumberオブジェクトまたはStringのいずれかとして設定します。

- TabularValue: または、表形式のデータ・セットをJava.util.Listオブジェクトとして指定します。詳細は、23.2.5項「表形式のデータを使用したグラフの作成方法」を参照してください。

7. 「外観」セクションを開きます。次のフィールドの値を設定して、表示属性を指定します。

- ShortDesc: グラフの目的およびスクリーン・リーダーで使用するための構造の説明を入力します。

- EmptyText: グラフにデータがない場合に表示するエラー・テキストを指定します。

クライアントがサポートしている場合、グラフはクライアントにHTML5イメージ形式で表示されます。グラフのイメージ形式の詳細は、第23.2.6項「グラフのイメージ形式に関する必知事項」を参照してください。

23.2.4 ページにグラフを追加する場合の処理

「グラフの作成」ダイアログを使用してグラフ・コンポーネントをJSFページに挿入すると、グラフのカスタマイズをサポートする子タグのセットが自動的に挿入されます。例23-2に、図23-36のクイック・スタート・レイアウトを選択した棒グラフ用にJSFページに挿入されたコードを示します。

例23-2 グラフのサンプル・コード

<dvt:barGraph id="graph1" subType="BAR_VERT_CLUST">
<dvt:background>
<dvt:specialEffects/>
</dvt:background>
<dvt:graphPlotArea/>
<dvt:seriesSet>
<dvt:series/>
</dvt:seriesSet>
<dvt:o1Axis/>
<dvt:y1Axis/>
<dvt:legendArea automaticPlacement="AP_NEVER"/>
</dvt:barGraph>

ページにグラフ・コンポーネントを挿入した後、ビジュアル・エディタの専用コンテキスト・メニューや「プロパティ」ウィンドウのボタンが使用可能になり、グラフ機能のカスタマイズをサポートします。詳細は、23.2.7項「ビジュアル・エディタおよび「プロパティ」ウィンドウでのグラフの編集」を参照してください。

23.2.5 表形式データを使用したグラフの作成方法

グラフ・コンポーネントにデータのグリッドが使用される場合、グラフが作成されます。グラフ・コンポーネントのtabularData属性には、グリッドの作成やデータの移入にグラフで使用する値のリストを指定できます。表形式のデータを使用してグラフを作成するには、グラフのマネージドBeanのメソッドにデータを格納し、グラフ・コンポーネントのtabularData属性を使用してデータを参照する必要があります。

たとえば、図23-38の表には、2006、2007および2008の3つの列と、ShoesおよびBootsの2つの行があります。このデータから、3年間のブーツと靴の年間売上げを比較するグラフが生成されます。

図23-38 年間売上高の比較

マネージドBeanでは、表形式のデータを含むリストは、グラフに渡すデータ値ごとに3メンバーのObject配列で構成されます。各配列のメンバーは次のように編成される必要があります。

- 1つ目のメンバー(索引0)は、データ値のグリッドの列ラベルです。これは通常Stringです。グラフに時間軸がある場合は、JavaのDate型で指定する必要があります。列ラベルは、通常、グラフのグループを識別します。

- 2つ目のメンバー(索引1)は、データ値のグリッドの行ラベルです。これは通常Stringです。行ラベルはグラフで系列ラベルとして、通常、凡例に表示されます。

- 3つ目のメンバー(索引2)はデータ値で、通常Doubleです。

例23-3に、3年間の靴とブーツの年間売上げを比較するグラフに必要なデータのリストを作成するコードを示します。

例23-3 グラフ用のデータのリストを作成するコード

public List getTabularData()
{
ArrayList list = new ArrayList();
String[] rowLabels  = new String[] {"Boots", "Shoes"};
String[] colLabels  = new String[] {"2006", "2007", "2008"};
Double [] [] values = new Double[][]{
{120000.0, 122000.0, 175000.0},
{90000.0, 110000.0, 150000.0}
};
for (int c = 0; c < colLabels.length; c++)
{
for (int r = 0; r < rowLabels.length; r++)
{
list.add (new Object [] {colLabels[c], rowLabels[r],
new Double (values[r][c])});
}
}
return list;
}

図23-39に、例23-3のメソッドを集合縦棒グラフのtabularData属性に追加した場合にページでレンダリングされるグラフを示します。

図23-39 表形式データを使用して年間売上高を比較する棒グラフ

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

データを供給するメソッドを作成し、それをグラフのマネージドBeanに追加する必要もあります。詳細なヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。

マネージドBeanからのデータを使用するグラフを作成する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「グラフ・データ」セクションを展開します。

3. 「TabularData」属性のドロップダウン・メニューから、「式ビルダー」を選択します。

4. 「式ビルダー」ダイアログで検索ボックスを使用してグラフのマネージドBeanを検索します。

5. マネージドBeanのノードを展開し、表形式データのリストを含むメソッドを選択します。

6. 「OK」をクリックします。
式が作成されます。

たとえば、sampleGraphというマネージドBeanとgetTabularDataというメソッドの場合、式ビルダーによりグラフのtabularData属性の値として、コード#{sampleGraph.tabularData}が生成されます。

23.2.6 グラフのイメージ形式に関する必知事項

グラフでは、HTML5、FlashおよびPNGなどのイメージ形式がサポートされています。使用されるイメージ形式は、アプリケーションの設定およびクライアント環境によって異なります。

次のパラメータを設定または変更することで、特定のイメージ形式を使用するようにアプリケーションを構成できます。

- oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT
このコンテキスト初期化パラメータは、新しいすべてのアプリケーションのweb.xmlに自動的に追加され、デフォルトではHTML5に設定されます。詳細は、A.2.3.28項「グラフとゲージのイメージ形式」を参照してください。

- スキン・スタイル
Skyrosスキンを使用している場合、グラフはHTML5イメージ形式で表示されます。新しいアプリケーションでは、デフォルトでこのスキンが使用されます。スキニングおよびスタイルの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- flash-player-usage
adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定すれば、アプリケーション全体にわたってFlashコンテンツの使用を無効にできます。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

指定したイメージ形式がクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。たとえば、クライアントがHTML5をサポートしていない場合、アプリケーションでは次が使用されます。

- Flash (Flash Playerが使用可能な場合)。

- Portable Network Graphics (PNG)出力形式。PNG出力形式は、グラフの印刷時にも使用されます。静的レンダリングは、PNG出力形式使用時には完全にサポートされますが、次のような一部のインタラクティブ機能は使用できません。

- アニメーション

- コンテキスト・メニュー

- ドラッグ・アンド・ドロップ・ジェスチャ

- 円グラフのスライスのインタラクティブ動作

- 参照オブジェクトのホバー動作

- ポップアップのサポート

- 選択項目

- 系列のロールオーバー動作

23.2.7 ビジュアル・エディタおよび「プロパティ」ウィンドウでのグラフの編集

ビジュアル・エディタおよび「プロパティ」ウィンドウでグラフ・コンポーネントを編集する場合、専用コンテキスト・メニューやボタンが利用でき、グラフ機能のカスタマイズをサポートします。タイトル、凡例エリア、描画エリア、背景、軸ラベルおよびグラフ系列(棒など)の表示といったグラフの子コンポーネントを選択すると、編集を選択できるコンテキスト・メニューが表示されます。図23-40に、ビジュアル・エディタに表示された横棒グラフを示します。

図23-40 ビジュアル・エディタ内の横棒グラフ

ビジュアル・エディタ内のポップアップでは、カスタマイズするグラフ機能の選択を確認します。たとえば、図23-41では、折れ線グラフの描画エリアに表示されたポップアップを示しています。

図23-41 折れ線グラフでのビジュアル・エディタのポップアップ

ビジュアル・エディタでグラフ機能を選択すると、専用の編集コンテキスト・メニューが使用できるようになります。図23-42に示す折れ線グラフの描画エリアのコンテキスト・メニューからは、横のグリッド・マークのデフォルト表示の削除など、様々なオプションを選択できます。コンテキスト・メニューや「プロパティ」ウィンドウのボタンを使用すると、描画エリアの特殊塗りつぶし効果を構成することもできます。グラフ・タグの選択は、ビジュアル・エディタ、「構造」ウィンドウ、「プロパティ」ウィンドウおよびソース・エディタで同期化されます。

図23-42 折れ線グラフの描画エリアのコンテキスト・メニュー

折れ線グラフの構成の詳細は、23.5.3項「グラフでの折れ線の外観の変更」を参照してください。特殊塗りつぶし効果の詳細は、23.4.3項「グラフでのグラデーション特殊効果の使用」を参照してください。

23.3 グラフ表示要素のカスタマイズ

サイズ変更、背景および描画エリアの外観、タイトル、軸、ラベル、凡例およびツールチップなどのグラフの表示要素は構成できます。

23.3.1 グラフのサイズとスタイルの変更

グラフの幅と高さはカスタマイズでき、コンテナのサイズ変更に基づいて動的にサイズ変更することができます。グラフで使用されるスタイルシートを制御することもできます。グラフのこれらの2つの側面は、ともにグラフのinlineStyle属性を使用するという点で関連性があります。

23.3.1.1 グラフが初めて表示される際のサイズの指定方法

dvt:typeGraphタグの属性に値を指定すると、グラフの初期サイズを指定できます。グラフの動的サイズ変更を指定しない場合、初期サイズが、グラフの唯一の表示サイズです。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフが初めて表示される際のサイズを指定する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「スタイル」セクションで、グラフ・タグのInlineStyle属性に値を入力します。
たとえば、幅200ピクセル、高さ200ピクセルのグラフを作成するには、InlineStyle属性にwidth:200px;height:200pxと設定します。

23.3.1.2 グラフの動的サイズ変更の指定方法

JSFページでコンテナのサイズが変更されたときにグラフがサイズ変更されるようにするには、dvt:typeGraphタグの2つの属性のそれぞれに値を入力する必要があります。この機能用に指定する値は、サイズの異なるブラウザ・ウィンドウの領域を使用するグラフ・コンポーネントの作成にも有用です。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフの動的サイズ変更を有効にする手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「動作」セクションで、DynamicResize属性のドロップダウン・リストから値DYNAMIC_SIZEを選択します。

3. 「スタイル」セクションで、InlineStyle属性の幅と高さに、ピクセルの定数または相対的割合を入力します。
たとえば、コンテナの50%の幅で200ピクセルの高さのグラフを作成するには、InlineStyle属性にwidth:50%;height:200pxという設定を使用します。

ベスト・プラクティスのヒント:

100%の幅を指定する場合は、StyleClassをAFStretchWidthに設定します。

23.3.1.3 特定のスタイルシートをグラフに使用する方法

dvt:typeGraphタグに使用できる標準スタイルを選択できます。グラフに使用するカスタム・スタイルシートを指定することもできます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフのスタイルシートを選択する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「スタイル」セクションを展開します。

3. StyleClass属性に、グラフに使用するCSSスタイル・クラスの名前を入力します。

4. プロパティ・エディタで、グラフに使用するCSSスタイル・クラスを選択します。
たとえば、グラフに薄い灰色の背景を設定するには、OraBGGrayLightクラスを選択します。

スタイルシートおよびCSSスタイル・クラスの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

23.3.2 グラフの背景、描画エリアおよびタイトルの変更

グラフでは、使用しているスタイルに基づいて、背景と描画エリアにデフォルト設定が自動的に指定されます。これらの設定は、グラフの子タグを使用してカスタマイズできます。

グラフには、タイトル、サブタイトル、脚注のオプションも指定できます。デフォルトでは、タイトルと脚注にはテキストは指定されていません。この情報を入力する際、テキストに使用するフォントとフォント特性も指定できます。

23.3.2.1 グラフの背景と描画エリアのカスタマイズ方法

グラフの背景と描画エリアに関連する次の箇所をカスタマイズできます。

- 背景:グラフがプロットされる領域。

- 描画エリア:円グラフ以外のすべてのグラフでデータがプロットされるフレーム。描画エリアの最低2つの境界に軸が表示されます。

- 円フレーム:軸を使用しない円グラフがプロットされるフレーム。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフの背景と描画エリアをカスタマイズする手順:

1. グラフの背景をカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでdvt:backgroundノードを右クリックし、「プロパティに移動」を選択します。

2. 背景の塗りつぶしの色を変更するには、FillColor属性のドロップダウンから「編集」を選択し、プロパティ・エディタで使用する色を選択します。

2. 円グラフ以外のグラフの描画エリアをカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでdvt:graphPlotAreaノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、属性ドロップダウン・メニューを使用して、描画エリアのBorderColorおよびFillColor属性に対してカスタマイズする色を選択します。

3. 円グラフの描画エリアをカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでdvt:graphPieFrameノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、属性ドロップダウン・メニューを使用して、描画エリアのBorderColorおよびFillColor属性に対してカスタマイズする色を選択します。

注意:

グラフの背景と描画エリアの色にグラデーション特殊効果を追加してカスタマイズすることもできます。詳細は、23.4.3項「グラフでのグラデーション特殊効果の使用」を参照してください。

23.3.2.2 グラフのタイトルと脚注の指定方法

グラフのタイトル、サブタイトルおよび脚注を指定できます。これらのテキスト・エントリに、グラフの個別の子タグを使用します。これらの各子タグの属性では、テキスト・フィールドの水平方向の位置合せ、テキストの内容と、テキストをレンダリングするかどうかを定義できます。

タイトル、サブタイトルおよび脚注のタグでは、子グラフ・フォント・タグの使用がサポートされ、各テキスト・フィールドに使用するフォント特性を指定できます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフのタイトルと脚注を指定する手順:

1. グラフのタイトルを入力する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「タイトル」を選択します。

2. 「プロパティ」ウィンドウを使用して、dvt:graphTitleタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、「構造」ウィンドウで「dvt:graphTitle」ノードを右クリックし、「タイトルの中に挿入」→「フォント」を選択します。

4. 「プロパティ」ウィンドウを使用して、dvt:graphFontタグの属性に値を指定します。

2. グラフのサブタイトルを入力する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「サブタイトル」を選択します。

2. 「プロパティ」ウィンドウを使用して、dvt:graphSubtitleタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、「構造」ウィンドウで「dvt:graphSubtitle」ノードを右クリックし、「サブタイトルの中に挿入」→「フォント」を選択します。

4. 「プロパティ」ウィンドウを使用して、dvt:graphFontタグの属性に値を指定します。

3. グラフの脚注を入力する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「脚注」を選択します。

2. 「プロパティ」ウィンドウを使用して、dvt:graphFootnoteタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、「構造」ウィンドウで「dvt:graphFootnote」ノードを右クリックし、「脚注の中に挿入」→「フォント」を選択します。

4. 「プロパティ」ウィンドウを使用して、dvt:graphFontタグの属性に値を指定します。

23.3.3 グラフの軸およびラベルのカスタマイズ方法

グラフには次の軸を使用できます。

- 順序軸(o1軸とも呼ばれる):グラフの順序(カテゴリ)軸は、レーティングやステージなどの順序付けされたデータを示したり、異なる都市や異なる製品などの名前のデータを示します。順序軸は、棒グラフ、折れ線グラフ、組合せグラフまたはレーダー・グラフに表示されます。順序軸が水平で時間データを含む場合は、時間軸と呼ばれます。
順序軸の例は、縦棒グラフの描画エリアの下部を横切る線です。この軸上の値は、標示されているデータの程度は示しません。そのかわり、データが属する異なるグループを示します。

- X1軸:X1軸は、グラフの横軸に沿って表示される値を示します。この軸は、グループ・ラベルではなく、一定間隔の数値を持ちます。X軸とも呼ばれます。X1軸は、バブル・グラフおよび散布図で表示されます。

- Y1軸:Y1軸は、第1Y軸です。通常、描画エリアの左側の縦方向の値軸です。一定間隔の数値を持ちます。

- Y2軸:Y2軸は、第2Y軸です。通常、描画エリアの右側の縦軸です。一定間隔の数値を持ちます。

各軸には、カスタマイズをサポートするいくつかのグラフ子タグがあります。次の項で、軸の様々なカスタマイズに使用できるオプションについて説明します。

23.3.3.1 軸のタイトル、外観およびスケーリングの指定方法

次のグラフ子タグで、軸のタイトルと外観のカスタマイズがサポートされます。

- タイトル:軸のタイトルのテキストと位置合せを指定します。dvt:o1Title、dvt:x1Title、dvt:y1Titleおよびdvt:y2Titleのタグがあります。適切なタイトル・タグを使用しないと、軸にタイトルは表示されません。

- 軸: 色、線幅、スケーリング、ティック・マーク間の増分、軸の可視性および特定のグラフ・タイプでのスクロールを制御します。dvt:o1Axis、dvt:x1Axis、dvt:y1Axisおよびdvt:y2Axisのタグがあります。

注意:

順序軸には数値は表示されないため、dvt:o1Axisタグにはスケーリング属性はありません。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

軸のタイトルと外観を指定する手順:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→軸タイプのタイトルを選択します。
たとえば、棒グラフのo1軸のタイトルを設定するには、「棒の中に挿入」→「ADFデータ視覚化」→「O1タイトル」を選択します。

2. 「プロパティ」ウィンドウで、軸のタイトルを入力し、必要に応じてこのタグの他の属性に値を指定します。

3. タイトルのフォント属性を指定する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeTitle」ノードを右クリックし、「タイトルの中に挿入」→「フォント」を選択します。

2. 「プロパティ」ウィンドウで、フォント特性に目的の値を入力します。

23.3.3.2 軸でのスクロールの指定

グラフ軸上のスクロールは、次のグラフ・タイプに対して指定できます。

- dvt:o1Axis、dvt:y1Axisおよびdvt:y2Axisタグの面、棒および折れ線グラフ。

- dvt:x1Axis、dvt:y1Axisおよびdvt:y2Axisタグのバブル・グラフおよび散布図。

デフォルトでは、グラフ軸のscrolling属性はoffに設定されています。scrolling属性には次の値を指定できます。

- off: スクロールは無効です(デフォルト)。

- on: スクロールは有効で、スクロールバーが常に表示されます。

- asNeeded: スクロールは有効ですが、スクロールバーは最初表示されません。グラフでズームすると、スクロールバーが表示され、そのセッション中は表示されたままになります。

- hidden: スクロールは有効ですた、スクロールバーは常に非表示です。ユーザーはパン・スクローリングを使用できます。

23.3.3.3 軸のティック・マークとティック・ラベルの外観の制御方法

ティック・マークは、グラフのスケール上の特定の値を示すために使用されます。次のグラフ子タグで、軸のティック・マークとラベルのカスタマイズがサポートされます。

- 主ティック:軸のティック・マークの色、幅とスタイルを制御します。dvt:o1MajorTick、dvt:x1MajorTick、dvt:y1MajorTickおよびdvt:y2MajorTickのタグがあります。主ティックの増分は、デフォルトでは自動的に計算されますが、majorIncrement属性でティックの段階を指定できます。

- 副ティック: 軸上の副ティック・マークの色、幅およびスタイルを制御します。dvt:x1MinorTick、dvt:y1MinorTickおよびdvt:y2MinorTickのタグがあります。副ティックの増分は、デフォルトでは主ティックの増分の半分ですが、minorIncrement属性でティックの段階を指定できます。副ティックにはラベルは付けられません。

- ティック・ラベル: 主ティックのラベルの向きを制御し、ラベルのフォント特性を指定できます。dvt:o1TickLabel、dvt:x1TickLabel、dvt:y1TickLabelおよびdvt:y2TickLabelのタグがあります。これらのタグは、ラベルのフォント特性を変更するdvt:graphFont子タグを持つこともできます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

順序軸のティック・ラベルの外観を制御する手順:

1. ビジュアル・エディタで、グラフ上の「O1ティック・ラベル」要素を選択します。
または、「構造」ウィンドウで「dvt:o1Axis」ノードを選択し、「プロパティ」ウィンドウでO1軸の構成をクリックし、「値ラベル」を選択することもできます。

2. 「プロパティ」ウィンドウで、次のプロパティに必要な値を入力します:

- TextRotation: ティック・ラベルを読みやすくするために、テキストの回転度数の指定に使用します。

ヒント:

最良の結果を得るには、90度の倍数の回転角度を使用します。他の角度はレンダリング・テクノロジで適切にサポートされず、お薦めできません。

- TickLabelSkipMode: 順序軸上でティック・ラベルを表示するかどうか、およびどのように表示するかの指定に使用します。TLS_MANUALで値を設定すると、必要に応じてtickLabelSkipCount属性を使用してティック・ラベル間に表示するティック・ラベルの数を設定すること、およびtickLabelSkipFirst属性を使用してスキップする最初のティック・ラベルのインデックスを設定することができます。

3. 必要に応じて、「プロパティ」ウィンドウで「フォントの構成」ボタンをクリックし、子のdvt:graphFontタグのプロパティを設定します。

X軸のティック・マークとティック・ラベルの外観を制御する手順:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「X1主ティック」を選択します。

2. 「プロパティ」ウィンドウで、このタグの属性に希望の値を入力し、「ティック・ラベルの構成」ボタンをクリックしてグラフに「X1ティック・ラベル」タグを追加します。

3. 「プロパティ」ウィンドウで、「X1ティック・ラベル」に希望の値を入力し、必要な場合は「フォントの構成」ボタンをクリックしてティック・ラベルのフォント特性を指定します。

4. グラフで副ティックを指定する場合は、次のようにします。

1. 「構造」ウィンドウで、グラフ・ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「X1副ティック」を選択します。

2. 「プロパティ」ウィンドウで、フォント特性に目的の値を入力します。

注意:

tickStyle属性には、GS_NONEまたはGS_AUTOMATIC以外の値を指定する必要があります。

他のグラフの軸のティック・マークの外観を制御する手順は、X軸に対する手順と似ています。ただし、主ティックとラベルのタグをカスタマイズし、カスタマイズする特定の軸に関連付けられた副ティックを挿入します。

23.3.3.4 軸の数値の書式設定

dvt:markerTextタグで、軸の数値の書式を制御できます。dvt:markerTextの子タグ(dvt:x1Format、dvt:y1Formatおよびdvt:y2Format)で特定の軸の数値書式をラップします。

注意:

順序軸には数値は含まれないため、この軸には書式はありません。

これらの軸の数値の書式を設定するには、23.4.4項「グラフのデータ値の書式設定」に示すように、該当する軸に対する子タグを挿入します。

23.3.3.5 データ軸の最小値および最大値の設定方法

Y軸にはdvt:y1Axisとdvt:y2Axisというグラフの子タグがあり、軸の最初の値がサポートされます。二重Yグラフの各Y軸に異なるスケーリングを指定できます。たとえば、Y1軸は売上数量(単位: 100)を表し、Y2軸は売上高(単位: 1000ドル)を表すことができます。

散布図やバブル・グラフなどの一部のグラフには、最小値や最大値も設定可能なdvt:x1Axis子タグが含まれています。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

Y1軸の最初の値を指定する手順:

1. 「構造」ウィンドウで「dvt:y1Axis」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、AxisMinValueフィールドにY1軸の最初の値を入力します。

3. AxisMinAutoScaledフィールドで、属性ドロップダウン・リストから「false」を選択します。
最小値が適用されるようにするには、この属性を設定する必要があります。

Y2軸の最初の値を設定するには、同様の手順を使用しますが、グラフの子としてdvt:y2Axisタグを最初に挿入します。

23.3.4 グラフの凡例のカスタマイズ方法

グラフ・コンポーネントには、凡例をカスタマイズする次の種類の子タグが用意されています。

- グラフに関連する凡例エリアの色、枠、可視性、位置およびスクロール可能性を指定するdvt:legendAreaタグ。

- 凡例の色付けされた各エントリに関連するテキストのフォント特性と位置を指定するdvt:legendTextタグ。

- 凡例エリアのオプションのタイトルとフォント特性を指定するdvt:legendTitleタグ。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

凡例エリア、凡例テキストとタイトルをカスタマイズする手順:

1. 構造ウィンドウでdvt:legendAreaノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウを使用して、このタグの属性に値を指定します。たとえば、凡例エリアには次の属性を指定できます。

- AutomaticPlacementおよびPosition: グラフの右または下部での凡例エリアの自動配置を、デフォルト値AP_ALWAYSで指定します。AP_NEVERでの値の設定には、凡例エリアの配置に使用されるposition属性の値が必要です。

- Scrolling: 使用可能なスペースより大きなスペースが必要な場合、asNeededの値を使用して、汎用エリアでのスクロールを指定します。デフォルトではこの値はoffに設定されています。

- PositionHint: 円グラフ、極グラフおよびレーダー・グラフで、値alignToCenterを使用して、描画エリアの中央方向に凡例の位置を指定します。デフォルトでは、値は、グラフ枠のエッジ方向へ凡例を配置するalignToEdgeに設定されます。

- MaxWidth: 凡例エリアの最大幅をグラフ・エリアのパーセンテージとして指定します。デフォルトでは、この値は空の文字列に設定されており、この場合は幅がグラフの設定値に基づいて自動的に設定されます。
たとえば、凡例の最大幅をグラフ・エリアの50%に設定するには、50%と入力します。

3. 凡例テキストをカスタマイズする場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「凡例テキスト」を選択します。

2. 「プロパティ」ウィンドウを使用して、このタグの属性に値を入力します。

3. 「dvt:legendText」ノードを右クリックし、「凡例テキストの中に挿入」→「フォント」を選択します。

4. 「プロパティ」ウィンドウを使用して、フォント・タグの属性に値を指定します。

4. 凡例のタイトルを入力する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「凡例タイトル」を選択します。

2. 「プロパティ」ウィンドウを使用して、このタグの属性に値を入力します。

3. 「dvt:legendTitle」ノードを右クリックし、「凡例タイトルの中に挿入」→「フォント」を選択します。

4. 「プロパティ」ウィンドウを使用して、フォント・タグの属性に値を指定します。

23.3.5 グラフのツールチップのカスタマイズ

ツールチップは、データ・マーカーのIDや詳細情報を表示するのに便利です。markerTextを表示する領域のない小さいグラフには非常に便利です。タイトル、サブタイトル、脚注、凡例テキスト、注釈などのテキストが切り捨てられている場合は、そのコンポーネントのツールチップがグラフに自動的に表示されます。

ほとんどのグラフで、データ・マーカー上にカーソルを置くと、ツールチップが表示されます。折れ線または面グラフでは、単に線上または面上ではなく、データ・マーカー上、あるいは線または面の隅にカーソルを置く必要があります。

各グラフ・マーカー(棒など)で情報付きのツールチップが表示されるように指定できます。グラフのツールチップのカスタマイズには、次のグラフの属性が使用できます。

- markerTooltipType: マーカー(棒など)に対するツールチップを表示するかどうかを指定し、ツールチップに表示する情報の種類を特定します。テキストのみ、値のみ、あるいはテキストと値の情報を表示できます。特定のグラフ・タイプでは、積上げグラフ・マーカーごとに累積データ値を表示したり、円グラフのスライス・マーカーごとに割合のデータを表示できます。

- seriesTooltipLabelType: 凡例に表示される値のセットごとにツールチップを表示するかどうかを指定します。この属性では、系列ツールチップに表示される情報の種類も制御されます。たとえば、系列全体を示す一般的な語(「製品」など)のテキストを表示するか、系列の特定のメンバーを示す特定の語(特定の製品名など)のテキストを表示するかを選択できます。

注意:

グラフでは、グラフのmarkerTooltipType属性にテキストを含む設定が行われている場合のみ、系列のツールチップ・ラベルが表示されます。

- groupTooltipLabelType: 軸上のデータ・グループに対するツールチップ・ラベルを表示するかどうかを指定します。たとえば、特定の製品の売上げが年ごとまたは四半期ごとにまとめられているとします。グループ全体を示す一般的な語(「時間」など)のテキストを表示するか、グループの各メンバーを示す特定の語(四半期を表すQ1、Q2、Q3、Q4など)のテキストを表示するかを選択できます。

グラフのmarkerTooltipTemplate属性をトークン化された文字列に設定することにより、グラフ内のすべてのマーカー・ツールチップの書式をすばやく設定できます。この属性には1つの文字列を指定でき、これには事前に定義されたトークンのセットをいくつでも含めることができます。次に例を示します。

<dvt:lineGraph markerTooltipTemplate="Template Based Tooltip NEW_LINE SERIES_LABEL GROUP_LABEL NEW_LINE Value: Y_VALUE"/>

表23-5に、サポートされるトークンのリストを示します。

表23-5 markerTooltipTemplate文字列トークン

トークン

説明

NEW_LINE

新しい行を挿入します。

SERIES_LABEL

このマーカーの系列の系列ラベル。

GROUP_LABEL

このマーカーのグループのグループ・ラベル。

X_VALUE

散布図またはバブル・マーカーあるいは連続時間軸マーカーのX値。

Y_VALUE

このマーカーのY値(このマーカーにY値がある場合)。

Z_VALUE

バブル・マーカーのZ値(バブルのサイズ)。

PIE_VALUE

円グラフのスライスの値。

PIE_PERCENT

円グラフのスライスのパーセント値。

ACTUAL_VALUE

ファンネル・セクションの実際の値。

TARGET_VALUE

ファンネル・セクションのターゲット値。

HIGH_VALUE

株価マーカーの高値。

LOW_VALUE

株価マーカーの低値。

CLOSE_VALUE

株価マーカーの終値。

OPEN_VALUE

株価マーカーの始値。

VOLUME_VALUE

株の出来高マーカーの出来高値。

CUM_VALUE

積上げグラフの累積積上げ値。

CUM_PERCENT

積上げパーセント・グラフまたはパレート・グラフの累積パーセント値。

23.4 グラフのテキスト、色およびデータ値の書式設定

すべてのグラフ・タイプに対して、テキスト、色およびデータ値の書式を設定できます。

23.4.1 グラフのテキストの書式設定

次のグラフのサブコンポーネントのテキストを書式設定できます。

- 注釈: dvt:annotationタグのみ。

- 軸のタイトル: dvt:o1Title、dvt:x1Title、dvt:y1Titleおよびdvt:y2Titleタグ。

- 軸のティック・ラベル: dvt:o1TickLabel、dvt:x1TickLabel、dvt:y1TickLabelおよびdvt:y2TickLabelタグ。

- グラフのタイトル: dvt:graphFootnote、dvt:graphSubtitleおよびdvt:graphTitleタグ。

- 凡例: dvt:legendTextタグのみ。

- マーカー: dvt:markerTextタグのみ。

dvt:graphFontタグを、テキストに書式設定する特定のサブコンポーネントの子として使用します。グラフのテキストの書式設定の例としては、23.3.2.2項「グラフのタイトルと脚注の指定方法」を参照してください。

23.4.1.1 スキンを使用したグラフ・フォントの全体的な設定方法

カスケード・スタイル・シート(CSS)を使用してスキンを作成し、アプリケーションでそのスキンを使用するように構成することにより、アプリケーション内のすべてのページにわたり、グラフ・コンポーネントのfont属性を設定できます。グラフ・コンポーネントで使用フォントを定義するスキンを適用することで、アプリケーション内のページは、CSSファイルの変更で簡単に変更できる一貫したスタイルで、より小さく整理されたものになります。

ADFデータ視覚化ツールのスキン・セレクタを使用すれば、グラフ・コンポーネントのフォント・スタイルを定義できます。グラフ・コンポーネントのスキン・セレクタは、次のものがあります。

- af|dvt-graphFootnote

- af|dvt-graphSubtitle

- af|dvt-graphTitle

- af|dvt-o1Title

- af|dvt-x1Title

- af|dvt-y1Title

- af|dvt-y2Title

- af|dvt-pieLabel

- af|dvt-ringTotalLabel

- af|dvt-legendTitle

- af|dvt-legendText

- af|dvt-markerText

- af|dvt-o1TickLabel

- af|dvt-x1TickLabel

- af|dvt-y1TickLabel

- af|dvt-y2TickLabel

- af|dvt-annotation

- af|dvt-sliceLabel

- af|dvt-tooltips

ADFデータ視覚化ツールの汎用スキン・セレクタを使用すれば、複数のグラフ・コンポーネントにわたるfont属性も使用できます。汎用スキン・セレクタ名は:alias擬似クラスで終わり、複数のコンポーネントのスキンに影響を与えます。汎用グラフ・スキン・セレクタには、次のものがあります。

- .AFDvtGraphFont:alias: すべてのグラフ・コンポーネントのfont属性を指定します。

- .AFDvtGraphTitlesFont:alias: すべてのグラフ・タイトル・コンポーネントのfont属性を指定します。

- .AFDvtGraphLabelsFont:alias: すべてのグラフ・ラベル・コンポーネントのfont属性を指定します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

カスタム・スキンを使用してグラフ・フォントを設定する手順:

1. グラフ・サブコンポーネント用に定義されたスキン・スタイル・セレクタを含むアプリケーションに、カスタム・スキンを追加します。次の属性の値を指定できます。

- -tr-font-family: フォント・ファミリ(名前)を指定します。複数のフォントを指定できない場合があります。複数のフォントが指定されている場合、最初のフォントが使用されます。

- -tr-font-size: フォントのサイズを指定します。絶対サイズの単位は次のように定義されます。

- pt: ポイントは、CSS2で使用される標準フォント・サイトで、1ポイントは1/72インチに相当します。

- in: インチで、1インチは72ポイントに相当します。

- cm: センチメートルで、1センチメートルは約28ポイントに相当します。

- mm: ミリメートルで、1ミリメートルは約2.8ポイントに相当します。

- pc: パイカで、1パイカは12ポイントに相当します。

この属性には、次のフォント・サイズ名も使用できます。

- xx-small: 8ポイント

- x-small: 9ポイント

- small: 10ポイント

- medium: 12ポイント

- large: 14ポイント

- x-large: 16ポイント

- xx-large: 18ポイント

- -tr-font-style: フォントのスタイルを指定します。有効な値は、normalまたはitalicです。

- -tr-font-weight: フォントの太さを指定します。有効な値は、normalまたはboldです。

- -tr-text-decoration: 下線強調を描画するかどうかを指定します。有効な値は、noneまたはunderlineです。

- -tr-color: フォントの色を指定します。有効な値は、HTMLおよびCSSの色名です。World Wide Web Consortiumでは、aqua、black、blue、fuchsia、gray、green、lime、maroon、navy、olive、orange (CSS 2.1)、purple、red、silver、teal、whiteおよびyellowの17色を有効色名としています。
この他、3、6または8桁のHEX (アルファ・チャネルは8桁HEXの最初の2桁)、RGBまたはRGBAも使用できます。

たとえば、mySkin.cssファイルのすべてのグラフ・タイトル用フォント・ファミリは次のように指定します。

af|dvt-graphTitle
{
-tr-font-family: Comic Sans MS;
}

カスタム・スキン作成のヘルプが必要な場合は、『Oracle ADFスキン・エディタによるADFスキンの作成』のADFスキン・ファイルの作成に関する項を参照してください。

2. trinidad-config.xmlファイルでカスタム・スキンを使用するようにアプリケーションを構成します。
アプリケーションの構成のヘルプが必要な場合は、『Oracle ADFスキン・エディタによるADFスキンの作成』の「完成したADFスキンのWebアプリケーションへの適用」の章を参照してください。

スタイルおよびスキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

23.4.2 グラフの一部への透明色の指定

グラフの各箇所に関連する子タグにborderTransparentおよびfillTransparent属性を設定することで、これらの箇所で透明色を表示するよう指定できます。デフォルトでは、これらの属性はtrueに設定されています。次のリストに、透明色をサポートするグラフの各部分を示します。

- グラフの背景: dvt:backgroundタグを使用します。この要素には棒は含まれず、borderTransparent属性は適用されません。

- グラフの凡例エリア: dvt:legendAreaタグを使用します。

- グラフの円フレーム: dvt:graphPieFrameタグを使用します。

- グラフの描画エリア: dvt:graphPlotAreaタグを使用します。

23.4.3 グラフでのグラデーション特殊効果の使用

グラデーションは、オブジェクトの色が段階的に変わる特殊効果です。グラデーションの各色は、ストップで表します。最初のストップはストップ0、2番目はストップ1のようになります。特殊効果をサポートするグラフのサブコンポーネントには、特殊効果のストップをいくつでも指定できます。

グラフの次のサブコンポーネントにグラデーション特殊効果を定義できます。

- グラフの背景: dvt:backgroundタグを使用します。

- グラフの描画エリア: dvt:graphPlotAreaタグを使用します。

- グラフの円フレーム: dvt:graphPieFrameタグを使用します。

- 凡例エリア: dvt:legendAreaタグを使用します。

- 系列: dvt:seriesタグを使用します。

注意:

デフォルトでは、グラフの系列グラデーションは、seriesEffect属性でSE_AUTO_GRADIENTの値に設定されており、データ・マーカーはより滑らかな外観で、グラフィックのアンチエイリアス処理が適用されます。カスタム系列グラデーションを指定するには、属性をSE_NONEに設定する必要があります。

- 時間セレクタ: dvt:timeSelectorタグを使用します。

- 参照エリア: dvt:referenceObjectタグを使用します。

グラデーション特殊効果を使用する方法は、この効果がサポートされるグラフの各部分で同じです。

23.4.3.1 グラデーション特殊効果のグラフへの追加方法

特殊効果を追加するグラフのサブコンポーネントごとに、dvt:specialEffectsタグをサブコンポーネントの子タグとして挿入する必要があります(まだ存在しない場合)。たとえば、グラデーションをグラフの描画エリアに追加する場合は、dvt:graphPlotAreaタグの子であるdvt:specialEffectsタグを1つ作成します。

その後、オプションでサブコンポーネントの塗りつぶし色の変化の割合を制御する場合は、コンポーネントの塗りつぶしの色と変化の割合の制御に必要な数のdvt:gradientStopStyleタグを挿入します。このdvt:gradientStopStyleタグは、1つのdvt:specialEffectsタグの子タグとして挿入する必要があります。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラデーション特殊効果をグラフに追加するには:

1. 構造ウィンドウで、グラデーション特殊効果を持たせるコンポーネントに対応するグラフの子ノードを見つけ、必要に応じて開きます。
たとえば、グラデーション特殊効果をグラフの描画エリアに設定するには、dvt:graphPlotAreaノードを見つけて、必要に応じて開きます。

2. 選択した子ノードにdvt:specialEffects子ノードが含まれていない場合は、ノードを右クリックし、「子ノードの中に挿入」→「特殊効果」を選択します。
たとえば、グラデーション特殊効果をグラフの描画エリアに設定するには、dvt:graphPlotAreaを右クリックし、「描画エリアの中に挿入」→「特殊効果」を選択します。

3. 「プロパティ」ウィンドウを使用して、dvt:specialEffectsタグの属性に値を入力します。

1. FillType: FT_GRADIENTを選択します。
GradientDirectionでは、グラデーションの塗りつぶしに使用する変化の方向を選択します。

2. NumStops: グラデーションに使用するストップの数を入力します。

4. オプションで各グラデーション・ストップの色と変化の割合を制御する場合は、「構造」ウィンドウで「dvt:specialEffects」ノードを右クリックし、「特殊効果の中に挿入」→「グラデーション終了スタイル」を選択します。

5. 「プロパティ」ウィンドウを使用して、dvt:gradientStopStyleタグの属性に値を入力します。

1. StopIndex: specialEffectsタグ内に含まれるdvt:gradientStopStyleタグ内の索引としてゼロベースの整数を入力します。

2. GradientStopColor: グラデーション内のこの部分に使用する色を入力します。

3. GradientStopPosition: 指定した停止色のグラデーションでの相対的距離を入力します。グラデーションのスケールは0から100です。0または100が指定されない場合、これらのポイントにはデフォルトの位置が使用されます。

6. 指定するグラデーション・ストップごとに、ステップ4とステップ5を繰り返します。

23.4.3.2 グラデーション特殊効果をグラフに追加する場合の処理

例23-4に、グラデーションの塗りつぶしをグラフの背景に追加し、2つのストップを指定する場合に生成されるXMLコードを示します。

例23-4 グラデーションをグラフの背景に追加する場合に生成されるXMLコード

<dvt:graph>
<dvt:background borderColor="#848284">
<dvt:specialEffects fillType="FT_GRADIENT" gradientDirection="GD_RADIAL"
gradientNumStops="2">
<dvt:gradientStopStyle stopIndex="0" gradientStopPosition="60"
gradientStopColor="FFFFCC"/>
<dvt:gradientStopStyle stopIndex="1" gradientStopPosition="90"
gradientStopColor="FFFF99"/>
</dvt:specialEffects>
</dvt:background>
</dvt:graph>

23.4.4 グラフ内のデータ値の書式設定

データ・コレクション内の属性には、データ値またはデータ値のカテゴリを指定できます。データ値は、棒の高さや散布図のポイントなどのマーカーで表される数値です。データ値のカテゴリは、順序軸ラベルとして表されるメンバーか、またはツールチップ内の追加プロパティとして表示されます。数値属性とカテゴリ属性はどちらも、ADF Facesコンバータ・タグ(数値データ値の場合はaf:convertNumber、カテゴリ・データ値の場合はaf:convertNumber、af:convertDateTimeおよびaf:convertColor)を使用して書式設定できます。

コンバータ・タグの属性で、パーセントの書式設定、数値の位取り、小数部の桁の制御、記号の配置などが行えます。ADF Facesコンバータの詳細は、第7章「入力の検証および変換」を参照してください。

23.4.4.1 カテゴリ・データ値の書式設定方法

グラフ内のカテゴリ・データ値は、グラフのデータ・モデルを定義するページ定義ファイル(<pagename>PageDef.xml)内の名前で表されます。例23-5に、従業員の雇用日およびボーナス・コストのカテゴリ・データ値を表示するグラフがあるページのページ定義ファイル内のXMLコードを示します。

例23-5 ページ定義ファイル内のカテゴリ・データ値名

<graph IterBinding="EmpView1Iterator" id="EmpView1"
xmlns="http://xmlns.oracle.com/adfm/dvt" type="BAR_VERT_CLUST">
<graphDataMap leafOnly="true">
<series>
<data>
<item value="Bonus"/>
</data>
</series>
<groups>
<item value="Hiredate"/>
</groups>
</graphDataMap>
</graph>

書式設定するカテゴリ属性ごとに、dvt:attributeFormatタグを使用して、カテゴリ・データ値の名前を指定し、属性の書式設定時に使用される子コンバータ・タグを指定します。カテゴリ属性の書式設定の指定には、af:convertNumber、af:convertDateTimeおよびaf:convertColorを使用できます。

たとえば、ページ定義ファイル(<pagename>PageDef.xml)で定義されているHiredateおよびBonusのカテゴリ・データ値の書式を設定できます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

ページ定義ファイルで定義されるカテゴリ・データ値の書式設定の手順:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「属性フォーマット」を選択します。

2. 「プロパティ」ウィンドウで、Name属性に情報を入力します。
たとえば、例23-5の雇用日の値を指定するには、Name属性にHiredateを入力します。

3. 「構造」ウィンドウで、指定した属性フォーマット・タグを右クリックし、「属性フォーマットの中に挿入」→「型の変換」を選択します。
たとえば、引き続きHiredateの書式を設定するには、「dvt:attributeFormat」ノードを右クリックして、「属性フォーマットの中に挿入」→「日時の変換」を選択します。

4. 「構造」ウィンドウで「af:convertType」ノードを右クリックし、「プロパティに移動」を選択します。

5. 「プロパティ」ウィンドウを使用して、コンバータの値を入力します。詳細は、第7章「入力の検証および変換」を参照してください。

6. 追加の属性ごとに、手順1から手順5を繰り返します。
たとえば、例23-5のカテゴリ・データ値の書式設定を完了するには、手順1から手順5を繰り返して、属性名にBonusを設定し、af:convertNumberコンバータを追加して、通貨の属性の書式を設定します。

例23-6に、棒グラフのカテゴリ・データ値の書式を設定する場合に生成されるXMLコードを示します。

例23-6 棒グラフのカテゴリ・データ値の書式設定

<dvt:barGraph id="barGraph1" value="#{bindings.EmpView1.graphModel}"
subType="BAR_VERT_CLUST">
<dvt:attributeFormat id="af1" name="Hiredate">
<af:convertDateTime pattern = "yyyy-MM-dd hh:mm:ss a"  timeZone="US/Pacific"/>
</dvt:attributeFormat>
<dvt:attributeFormat id="af2" name="Bonus">
<af:convertNumber type = "currency" currencySymbol = "$"
</dvt:attributeFormat>
</dvt:barGraph

注意:

順序(01)軸上に表示されているカテゴリ・データ属性が1つある場合、グラフには時間軸が表示されます。時間軸には、単一のラベル(「June 27, 2001」など)とは対照的に、階層形式で日付が表示されます。順序軸に単一ラベルを表示するには、時間軸をオフにし(たとえばtimeAxisType="TAT_OFF")、dvt:attributeFormatタグを使用して日付の書式を指定する必要があります。

23.4.4.2 数値データ値の書式設定方法

ADF Faces af:convertNumberタグを使用して、次のgraphタグに関連する数値データ値の書式設定を指定します。

- dvt:sliceLabel

- dvt:stockVolumeFormat

- dvt:x1TickLabel

- dvt:x1Format

- dvt:y1TickLabel

- dvt:y1Format

- dvt:y2TickLabel

- dvt:y2Format

- dvt:zFormat

たとえば、デフォルトでは円グラフは、全体に対する各部分の関係を円のスライスとして表して、各スライスのラベルには各スライスが表す割合が表示されます。定価を決める材料費、労務費および利益などの値として各スライスが表示されるように円グラフを構成できます。スライス内の値を表示し、それに応じて数値の書式を設定するには、dvt:sliceLabelタグのtextType属性を指定します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでに円グラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

円グラフのスライス・ラベルで数値の書式を設定する手順:

1. 「構造」ウィンドウで「dvt:sliceLabel」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、TextType属性のドロップダウン・リストから「LD_VALUE」を選択し、グラフ内の円のスライスが1つの値を表すことを指定します。

3. 「プロパティ」ウィンドウで、「区分ラベルの構成」をクリックし、ドロップダウン・メニューから「数値書式」を選択します。

4. 「プロパティ」ウィンドウで、Type属性のドロップダウン・リストからcurrencyを選択して値を通貨として指定し、CurrencySymbol属性にドル記号($)を入力して通貨記号としてドル記号を使用します。

例23-7に、グラフの区分ラベル内の数値を書式設定する場合に生成されるXMLコードを示します。

例23-7 円グラフの区分ラベルでの数値の書式設定

<pieGraph>
...
<dvt:sliceLabel textType="LD_VALUE">
<af:convertNumber type="currency" currencySymbol="$"/>
</dvt:sliceLabel>
...
</pieGraph>

ADF Faces af:convertNumberタグを使用すれば、グラフのマーカー・テキスト内の数値の書式も設定できます。

たとえば、グラフの各軸のマーカー・テキストに異なる書式を指定できます。この手順では、af:convertNumberタグを使用してdvt:y1axisのマーカー・テキストを書式設定します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフのY1軸に関連付けられたマーカー・テキストの数値データ値の書式を設定する手順:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「マーカー・テキスト」を選択します。

2. 「プロパティ」ウィンドウで、必要に応じてdvt:markerTextの属性に値を入力します。たとえば、グラフ内のテキストを表示するために、Rendered属性にtrueを選択します。

3. 「プロパティ」ウィンドウで、「マーカーの構成」をクリックし、「Y1フォーマット」を選択します。

4. 「プロパティ」ウィンドウで、必要に応じてdvt:y1Format属性に必要な値を入力します。

5. 「プロパティ」ウィンドウで、「数値書式の構成」をクリックし、af:convertNumberタグの属性に必要な値を指定します。たとえば、マーカー・テキストの後にパーセント記号を配置するには、Type属性にpercent値を選択します。

例23-8に、グラフのY1軸のマーカー・テキストの数値を書式設定する場合に生成されるXMLコードを示します。この例では、数値の後にパーセント記号が続き、マーカーの上にテキストが表示されるよう指定します。たとえば、棒グラフの場合、棒の上にテキストが表示されます。

例23-8 グラフのマーカー・テキストの数値の書式設定

<dvt:barGraph>
<dvt:markerText rendered="true" markerTextPlace="MTP_OUTSIDE_MAX">
<dvt:y1Format>
<af:convertNumber type="percent"/>
</dvt:y1Format>
</dvt:markerText>
</dvt:barGraph>

注意:

円グラフのスライスのラベルのtextType属性がパーセント(LD_PERCENT)に、またはグラフ・ツールチップのmarkerTooltipType属性がパーセント(MTT_PERCENT_XXX)に設定されている場合、子のaf:convertNumberタグは、使用されていれば、そのtype属性のpercentに自動的に設定されます。af:convertNumberがpercentに強制的に指定されると、グラフではパターン属性が消去されます。これは、グラフでパーセントの書式設定が強制されると、パターンが無視されることを意味します。これは、円、パレート、ファンネルおよび棒、折れ線または面パーセント・グラフに当てはまります。

23.4.4.3 自動位取りおよび精度に関する必知事項

コンパクトできれいな表示を実現するために、グラフでは、軸ラベル、マーカー・テキストおよびツールチップに表示される値のスケールおよび精度が自動的に決まります。たとえば、40,000の値は40Kと書式設定され、0.230546は小数点以下2桁の0.23として表示されます。

af:convertNumberが指定されている場合でも、自動書式設定は行われます。af:convertNumber子タグをサポートするグラフ・タグには、グラフの自動数値書式設定の制御に使用できるscaling属性およびautoPrecision属性があります。デフォルトでは、これらの属性値はscaling="auto"およびautoPrecision="on"に設定されています。af:convertNumberで指定される小数部の桁の設定(minFractionDigits、maxFractionDigitsまたはpatternなど)は、autoPrecisionがoffに設定されていないかぎり無視されます。

23.5 データの系列およびグループの外観のカスタマイズ

データの系列およびグループの外観を色、スタイル、表示についてカスタマイズできます。折れ線グラフの線、円グラフのスライス、バブル・グラフおよび散布図グラフのマーカーの外観もカスタマイズできます。グラフに参照線も追加できます。

23.5.1 グラフ・データ値の色、スタイルおよび表示の変更

ほとんどのグラフ・タイプで、グラフの棒、折れ線、面、ポイントおよびスライスとして表されるデータ値のセットごとにエントリが凡例に表示されます。このエントリは関連するデータ値のセットを識別し、グラフ内でのセットの色を示します。たとえば、棒グラフでは、黄色の棒を使用して靴の売上げを示し、緑色の棒を使用してブーツの売上げを示します。グラフ・コンポーネントでは、関連のデータ値の各セットを系列として参照します。

グラフでは、データ値の各セットに異なる色が自動的に割り当てられます。塗りつぶしや枠の色などの各系列に割り当てられた色はカスタマイズできます。一部のグラフ・タイプでは、グラフの凡例で系列の非表示または表示により、グラフ内のデータ値の表示をフィルタ処理できます。

特定のグラフ・タイプでは、折れ線グラフの線の幅やスタイルなどの追加属性を、実線、点線、ダッシュ線などの選択肢で指定できます。詳細は、23.5.3項「グラフでの線の外観の変更」を参照してください。

散布図の場合、データ値の相互依存関係を表すために、データ・マーカーの形状や色を系列と区別することができます。詳細は、23.5.5項「散布図の系列マーカー・データ値のカスタマイズ」を参照してください。

グラフ内の各系列の色にグラデーション特殊効果を追加してカスタマイズすることもできます。詳細は、23.4.3項「グラフでのグラデーション特殊効果の使用」を参照してください。

23.5.1.1 個々の系列アイテムの色とスタイルの指定方法

1つのdvt:seriesSetタグを使用して、グラフの個々のdvt:seriesタグをすべてラップし、グラフ・データ・マーカーの色およびスタイルの属性を設定します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフの系列アイテムに色とスタイルを指定する手順:

1. 構造ウィンドウでグラフ・ノードの「dvt:seriesSet」子タグを右クリックし、「プロパティに移動」を選択します。

2. 必要に応じて、「プロパティ」ウィンドウを使用してdvt:seriesSetタグの属性に値を指定します。
このタグの属性によって、セット内のすべての系列タグのデフォルト設定が決まります。ただし、指定した系列のこの設定を、dvt:seriesタグの対応する属性に値を入力することでオーバーライドできます。

3. 構造ウィンドウで、dvt:seriesSetノードを開きます。

4. 「構造」ウィンドウで、「dvt:series node」を右クリックし、「プロパティに移動」を選択します。
最初のdvt:seriesタグが「グラフ・バインディングの作成」ダイアログに表示される最初の系列を表します。

5. 「プロパティ」ウィンドウを使用して、dvt:seriesタグに必要な色およびその他の特性を指定します。

6. 追加の系列アイテムを構成するには、「構造」ウィンドウで、「seriesSet」ノードを右クリックし、「系列セットの中に挿入」→「系列」を選択します。

7. 「プロパティ」ウィンドウを使用して、dvt:seriesタグに必要な色およびその他の特性を指定します。

8. 系列アイテムごとに、ステップ6とステップ7を繰り返します。

23.5.1.2 系列アイテムの非表示および表示を有効にする方法

面、棒、バブル、組合せ、折れ線、円、レーダーおよび散布図のグラフ・タイプについては、実行時にグラフ内の系列の非表示または表示を有効にできます。グラフでは少なくとも1系列を表示する必要がありますが、ユーザーは対応する凡例アイテムをクリックすることにより、データの表示をフィルタ処理できます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

系列アイテムの非表示および表示を有効にする手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「外観」属性カテゴリの「系列」セクションで、グラフのHideAndShowBehavior属性を設定します。有効な値は、次のとおりです。

- none: デフォルト値で、系列の非表示および表示の動作は無効です。

- withRescale: 見える系列のみが表示されるようにグラフのサイズを変更します。

- withoutRescale: 系列は非表示なりますが、グラフのサイズは変わりません。

23.5.2 円グラフの外観の変更

円グラフの外観をカスタマイズできます。また、円グラフの1つのスライスを他のスライスから切り離すよう指定できます。

23.5.2.1 円グラフ全体の外観のカスタマイズ方法

円グラフの外観は、グラフ・タグ内に次の子タグを挿入することでカスタマイズできます。

- dvt:pieFeelerタグ: 円グラフのスライスからスライス・ラベルへ延びる線(引出線と呼ばれる)の色を指定します。

- dvt:sliceタグ: 円グラフのスライスのラベルの位置を指定します。

- dvt:sliceLabelタグ: 円グラフまたはドーナツ・グラフの各スライスを説明するラベルの特性を指定します。各スライスはデータ値を表します。このタグのtextType属性を使用して、スライス・ラベルにテキストのみを表示するか、割合のみを表示するか、テキストと割合を表示するかを示します。数値を書式設定する場合またはフォント特性を指定する場合は、dvt:sliceLabelタグ内にdvt:graphFontおよびaf:convertNumberタグを追加します。

円スライスをアニメーション化することもでき、これによりユーザーは、スライスをクリックしてそれらを切り離すことや、オプションを含むコンテキスト・メニューを表示して、円グラフ内のすべてのスライスを開くことまたは閉じることができます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

円グラフ全体の外観をカスタマイズする手順:

1. 円グラフに子タグを追加するには、「構造」ウィンドウで「dvt:pieGraph」ノードを右クリックし、「円の中に挿入」→「ADFデータ視覚化」→「円引出線」または「区分」または「区分ラベル」を選択します。

2. 「プロパティ」ウィンドウを使用して、必要に応じて属性に値を設定します。プロパティのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 円グラフのスライスをアニメーション化するには、「プロパティ」ウィンドウで、dvt:pieGraphタグのInteractiveSliceBehavior属性を設定します。次の値の組合せが有効です。

- none: インタラクティブなスライスの動作は無効です。

- explode: ユーザーは円グラフのスライスをクリックして切り離すことができます。

- explodeAll: コンテキスト・メニューに「すべて開く」および「すべて閉じる」のオプションを追加します。

たとえば、次のコードで、ユーザーが円グラフ内のスライスを切り離すことができ、またコンテキスト・メニューを表示して、グラフ内のすべてのスライスを開くこと、または閉じることができるように指定できます:

<dvt:pieGraph interactiveSliceBehavior="explode explodeAll"/>

注意:

interactiveSliceBehavior属性がFlashイメージ形式でのみ使用可能であるのに対し、pieSliceExplode属性はすべてのイメージ形式で使用可能です。

23.5.2.2 円グラフのスライスの切離しのカスタマイズ方法

円グラフで1つのスライスが他のスライスから切り離されている場合、この表示は円グラフのスライスの切離しと呼ばれます。1つのスライスを切り離すのはそのスライスを強調表示するためで、グラフ内で最も大きい分量が割り当てられていることもあります。

円グラフのスライスは、グラフの凡例で示されるデータのセットです。したがって、スライスは円グラフの系列アイテムです。

始める前に:

23.5.1.1項「個々の系列アイテムの色とスタイルの指定方法」の手順に従い、個々の系列アイテムをラップする系列セットを作成します。

円グラフで1つのスライスをカスタマイズする手順:

1. 「構造」ウィンドウで、「dvt:seriesSet」ノードを展開し、円から切り離す円スライスを表す「dvt:series」ノードを見つけます。

2. dvt:seriesノードを右クリックして、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウの「共通」セクションで、PieSliceExplode属性を0と100の間の値に設定します。100が使用できる最大の切離し距離です。

23.5.3 グラフでの線の外観の変更

グラフのdvt:seriesSet子の属性を使用して、グラフの線の外観を変更できます。

23.5.3.1 グラフでのデータ線またはデータ・マーカーの表示

折れ線、組合せまたはレーダー・グラフには、データ線またはデータ・マーカーを表示できます。データ線ではなく、マーカーを表示する場合、マーカーが凡例に自動的に表示されます。

「プロパティ」ウィンドウで、dvt:seriesSetタグの次の属性を設定して、データ線またはデータ・マーカーを表示します。

- LineDisplayed: グラフにデータ線を表示するかどうかを指定します。次の値を設定できます。

- trueは、グラフにデータ線が表示されることを示します。

- falseは、グラフにデータ線ではなく、マーカーが表示されることを示します。

- MarkerDisplayed: グラフにマーカーまたはデータ線を表示するかどうかを指定します。次の値を設定できます。

- trueは、グラフにマーカーが表示されることを示します。

- falseは、グラフにデータ線が表示されることを示します。

注意:

lineDisplayed属性とmarkerDisplayed属性の両方にfalseを設定しないでください。

23.5.3.2 グラフ系列の線の外観の変更

次のリストで説明するように、dvt:seriesSetタグとdvt:seriesタグを使用して線の外観をカスタマイズできます。

- dvt:seriesSetタグで次の属性に値を指定すると、タグ内のすべてのdvt:seriesタグに作用します。

- defaultMarkerShape: 折れ線グラフ、散布図、極グラフ、バブル・グラフおよび組合せグラフにのみ使用されます。系列セット内のすべての系列のデフォルト・マーカーの形状を示します。

- defaultMarkerType: 組合せグラフおよび折れ線グラフにのみ使用されます。有効な値は、MT_AREA、MT_BAR、MT_MARKERおよびMT_DEFAULTです。

- dvt:seriesタグで、次の線属性を使用して個々の系列の設定を指定できます。

- lineWidth: 線の幅をピクセルで指定します。

- lineStyle: グラフで実線、点線、ダッシュ線、ダッシュと点の組合せの線のいずれを使用するかを指定します。

dvt:seriesSetタグとdvt:seriesタグの使用の詳細は、23.5.1.1項「個々の系列アイテムの色とスタイルの指定方法」の手順を参照してください。

23.5.4 パレート・グラフのカスタマイズ方法

パレート・グラフは、一連の棒を使用して不具合の原因を示します。棒は値の大きい方から小さい方に順に並べられます。パレート線は、グラフのすべての棒の合計値に対する棒の累積割合を示します。線は常に100%で終わります。

パレート線とパレート・マーカーは、次のグラフの子タグを使用してカスタマイズできます。

- dvt:paretoLineタグ: 色、線幅と線のスタイル(実線、ダッシュ線、点線、ダッシュと点の組合せなど)を指定できます。

- dvt:paretoMarkerタグ: パレート・マーカーの形状を指定できます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにパレート・グラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

パレート・グラフをカスタマイズする手順:

1. 構造ウィンドウでdvt:paretoLineノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、Color、WidthまたはLineStyle属性に値を指定します。

3. 構造ウィンドウでdvt:paretoMarkerノードを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、MarkerShape属性に値を選択します。

23.5.5 散布図の系列マーカー・データ値のカスタマイズ

散布図では、1系列の関連データ値は、データ・マーカーの形状と色で表されます。データ値の相互依存関係を表すために、データ・マーカーの形状や色を系列と区別することができます。

たとえば、図23-43に、Product属性やBrand属性をまとめて使用して、データ・マーカーの形や色で表される系列を決定する散布図を示します。

図23-43 系列マーカーのある散布図

行ヘッダーの属性を使用して、デフォルト系列の指定をオーバーライドできます。図23-44に、Brand属性のデータ値が形にマップされ、Product属性が色にマップされて表示される散布図を示します。

図23-44 系列アイテム・マーカーのある散布図

次の属性を使用して、散布図の系列マーカー・データ値をカスタマイズします。

- markerShapeAttribute: マーカーの形状を設定するために使用する行ヘッダー属性名を指定します。この属性が指定されていない場合、グラフにはデフォルトのインデックス・ベース系列のマーカーの形状が表示されます。

- markerColorAttribute: マーカーの色を設定するために使用する行ヘッダー属性名を指定します。この属性が指定されていない場合、グラフにはデフォルトのインデックス・ベース系列のマーカーの色が表示されます。

たとえば、次のコードを使用して、ProductとBrandを散布図の別の系列アイテム・マーカーとして指定します。

<dvt:scatterGraph id="scatter" markerColorAttribute="Product" markerShapeAttribute="Brand" value="#{bindings.View1.graphModel}"/>

dvt:scatterGraphノードの「プロパティ」ウィンドウの「拡張」セクションで、markerShapeAttributeおよびmarkerColorAttributeを設定することもできます。

23.5.6 グラフ・マーカーの形状のカスタマイズ

折れ線グラフ、散布図、極グラフ、組合せグラフおよびバブル・グラフのマーカーの形状は、グラフseriesコンポーネントのmarkerShape属性で指定します。デフォルトでは、折れ線グラフ、散布図、極グラフまたは組合せグラフのマーカーの形状は、四角、円、ひし形、プラス記号および三角形で循環して各系列に割り当てられます。markerShapeのデフォルト値はMS_AUTOMATICです。

seriesコンポーネントのmarkerShape属性に次のいずれかの値を設定することで、あらかじめ作成されたグラフ・マーカーの形状を指定できます。

- MS_NONE: 系列マーカーを使用しません。

- MS_AUTOMATIC: デフォルト設定です。デフォルトのマーカーを使用します。

- MS_SQUARE: 四角いマーカーの指定に使用します。

- MS_CIRCLE: 円のマーカーの指定に使用します。

- MS_DIAMOND: ひし形のマーカーの指定に使用します。

- MS_PLUS: プラス記号のマーカーの指定に使用します。

- MS_TRIANGLE_DOWN: 下向きの三角形のマーカーの指定に使用します。

- MS_TRIANGLE_UP: 上向きの三角形のマーカーの指定に使用します。

- MS_HUMAN: 人型のマーカーの指定に使用します。markerSizeを指定すると、人型のマーカーは幅がmarkerSizeの値と一致するようにスケール調整されます。

カスタム・グラフ・マーカーの場合、shapePath属性を使用してSVGファイルのパスを指定すると、事前定義の形状のかわりに表示されます。次に例を示します。

<dvt:series shapePath="/resources/shapes/house.svg" />

マーカーの形状は、ADFスキン内のCSSスタイル・プロパティを使用して指定することもできます。グラフ・スタイルのプロパティを使用すれば、事前定義のマーカーの形状は上書きでき、カスタム・マーカーのSVGファイルのパスは、shapePath属性を使用せずに定義できます。スタイル・プロパティを使用する場合、事前定義とカスタムの両方の形状の定義にseriesコンポーネントのshape属性が使用されます。

その形状の汎用またはコンポーネント固有のスタイル・プロパティがADFスキンで指定されている場合、事前定義の形状は上書きされます。たとえば、グラフ・コンポーネントのスタイル・プロパティで次のようにnewCircle.svgファイルを指定することにより、事前定義のcircle形状を上書きできます。

af|dvt-graph::shape-circle{
-tr-path: url(/resources/path/newCircle.svg);
}

JSFページでは、seriesコンポーネントのshape属性が次のように設定されます。

<dvt:series id="s1" shape="circle"/>

seriesコンポーネントのshape属性でカスタム形状を指定するには、形状スタイル・プロパティ名でcustomの接頭辞を使用する必要があります。たとえば、カスタム形状がcustomNameという名前の場合、ADFスキン・ファイルで汎用の.AFDVTShapeCustomName:aliasスタイル・プロパティか、次のようにSVGファイルを指す-tr-pathプロパティを指定したグラフ固有のaf|dvt-graph::shape-customNameのいずれかを定義する必要があります。

af|dvt-graph::shape-customName{
-tr-path: url(/resources/path/newCShape.svg);
}

JSFページでは、マーカー・コンポーネントの形状属性は次のように設定されます。

<dvt:series id="s1" shape="customName"/>

スキンおよびスタイル・プロパティの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

23.5.7 参照線または領域のグラフへの追加

参照線および領域は、系列や軸の数や関連付けにかかわらず、常に表示する、ロールオーバーのみに表示する、または表示しない設定が可能です。

系列(グラフの凡例で1つの色で表示されるデータ値のセット)に関連付けられる参照線を作成できます。参照線付きの系列が複数ある場合、カーソルを系列マーカーまたは対応する系列凡例アイテム上に移動したときのみ参照線が表示されます。これは、複数の参照線はユーザーにとって紛らわしいからです。

軸に関連付ける参照領域を作成することもできます。通常、これらの領域はY軸に関連付けられます。複数の参照領域がある場合、カーソルを関連する軸上に移動すると、これらの領域も表示されます。

実行時までアプリケーションで必要な参照線と領域の数がわからない場合、参照線と領域を実行時に動的に作成することができます。

たとえば、グラフに表示されている値を参照するために、棒グラフに領域を追加できます。図23-45に、グラフの高い値と低い値に対する2つの参照領域がある棒グラフを示します。

図23-45 参照領域のある棒グラフ

23.5.7.1 設計時に参照線または領域を作成する方法

参照線も参照領域も、次のタグを使用して作成されます。

- referenceObjectSet: このグラフの参照線または参照領域のすべての参照オブジェクト・タグをラップします。

- referenceObject: タグが参照線を表すか、参照領域を表すかを示し、タグの特性を指定します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

設計時に参照線または領域をグラフに追加する手順:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「参照オブジェクト・セット」を選択します。

2. dvt:referenceObjectSetノードを右クリックして、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、特定の軸に関連付けられている参照領域を定義する場合、適切な軸を表示するための値または軸の属性(displayX1、displayY1またはdisplayY2)の値を指定します。
値RO_DISPLAY_AUTOMATICは、関連付けられている軸上にマウスが移動したときにのみ参照領域が表示されるようにします。これを選択すると、複数の参照領域が同時に表示されて混乱を招くことがなくなります。

オプションで、参照領域にグラデーション特殊効果を適用できます。詳細は、23.4.3項「グラフでのグラデーション特殊効果の使用」を参照してください。

4. 参照線を定義する場合、線を表示するための値を指定します。
値RO_DISPLAY_AUTOMATICは、カーソルが系列アイテム(棒など)またはグラフの凡例の対応する下位列エントリの上に移動したときにのみ参照線が表示されるようにします。これを選択すると、複数の系列の参照線が一度に表示されて混乱を招くことがなくなります。

5. 「構造」ウィンドウで、dvt:referenceObjectSetノードを右クリックし、「参照オブジェクト・セットの中に挿入」→「参照オブジェクト」を選択します。

6. dvt:referenceObjectノードを右クリックして、「プロパティに移動」を選択します。

7. 「プロパティ」ウィンドウで、以下を実行します。

1. 「共通」セクションで、参照オブジェクトのIndex属性に値を指定し、参照オブジェクトのType属性にRO_LINEまたはRO_AREAを指定し、Association属性に関連付けるオブジェクト(参照線の場合は系列、参照領域の場合は特定の軸)を指定します。また、DisplayedInLegend属性を使用してオブジェクトを凡例に表示するかどうかを指定し、凡例に表示するテキストがある場合はこれを指定します。

2. 参照線を作成する場合、「参照線」セクションで線に関連する属性に値を指定します。これには、線の値および線が関連付けられる系列の系列番号の指定も含まれます。系列番号は、グラフ・データ・バインディング・ダイアログに系列が表示される順番のことです。

3. 参照領域を作成する場合、指定した軸の参照領域を示す高低の値を「参照面」セクションで指定します。

4. 必要に応じて追加の属性を構成します。
たとえば、Color属性のドロップダウン・メニューを使用して参照線または参照領域の色を入力します。詳細なヘルプを参照するには、[F1]を押すか、「ヘルプ」をクリックします。

23.5.7.2 設計時に参照線または領域を作成する場合の処理

設計時に参照線または領域を作成すると、JSFページのグラフのXML内にXMLコードが生成されます。参照オブジェクト(線も領域も)は、dvt:referenceObjectSetタグでラップされます。例23-9に、図23-45の棒グラフに関連付けられた2つの参照領域のコードを示します。

例23-9 グラフの参照線と領域のXMLコード

<dvt:barGraph shortDesc="Graph" id="bg1">
<dvt:referenceObjectSet>
<dvt:referenceObject type="RO_AREA" association="Y1AXIS"
location="RO_BACK" color="#55FFFF00"
lowValue="10" highValue="30"
displayedInLegend="true" text="Low">
<dvt:specialEffects fillType="FT_GRADIENT"
gradientDirection="GD_DOWN"
gradientNumStops="2">
<dvt:gradientStopStyle stopIndex="0" gradientStopPosition="0"
gradientStopColor="#FFFF00"/>
<dvt:gradientStopStyle stopIndex="1"
gradientStopPosition="100"
gradientStopColor="#FF0000"/>
</dvt:specialEffects>
</dvt:referenceObject>
<dvt:referenceObject type="RO_LINE" association="Y1AXIS"
location="RO_BACK" color="#99cc66"
lineValue="50"
displayedInLegend="true" text="High"/>
</dvt:referenceObjectSet>
</dvt:barGraph>

23.5.7.3 参照線または領域の動的作成方法

参照オブジェクトを実行時に動的に作成する場合、referenceObjectSetタグのみを使用します。このタグのreferenceObjectMap属性に、子コンポーネント参照オブジェクトのマップを作成するコードへのメソッド参照を設定します。このマップを作成するメソッドは、マネージドBeanに格納する必要があります。

例23-10に、参照線を動的に作成するメソッドを作成するためのサンプル・コードを示します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

参照線または領域を動的に作成する手順:

1. マネージドBeanを作成して、実行時に動的に作成する子コンポーネント参照オブジェクトのマップを作成します。詳細なヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. 「構造」ウィンドウで、グラフ・ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「参照オブジェクト・セット」を選択します。

3. dvt:referenceObjectSetノードを右クリックして、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、ReferenceObjectMap属性に、子コンポーネント参照オブジェクトのマップを作成するコードへのメソッド参照を指定します。
たとえば、例23-10に示されている(sampleGraph)マネージドBeanとgetReferenceObjectMapListメソッドの場合、属性にreferenceObjectMap="#{sampleGraph.referenceObjectMapList}"という値を設定します。

例23-10 子参照オブジェクトのマップのコード

Managed bean sampleGraph.java :
public Map getReferenceObjectMapList() {
HashMap map = new HashMap();
ReferenceObject referenceObject = new ReferenceObject();
referenceObject.setIndex(1);
referenceObject.setColor(Color.red);
referenceObject.setLineValue(30);
referenceObject.setLineWidth(3);
map.put(new Integer(1), referenceObject);
return map;
}

23.6 グラフへのアニメーションの使用

グラフ・コンポーネントは、グラフ・コンポーネントの初期表示のスライドショー遷移、部分ページ・リフレッシュ(PPR)イベントのスライドショー遷移など、アニメーション効果をサポートしています。アニメーション効果は、グラフのanimationOnDisplayおよびanimationOnDataChangeプロパティに次の値を指定します。

- none (デフォルト)

- alphaFade

- conveyorFromLeft

- conveyorFromRight

- cubeToLeft

- cubeToRight

- flipLeft

- flipRight

- slideToLeft

- slideToRight

- transitionToLeft

- transitionToRight

- zoom

アニメーション効果は、アクティブ・データをサポートするグラフ・タイプでアクティブ・データを使用して実行することもできます。アクティブ・データ・サービス(ADS)では、ADFモデル・レイヤーを使用して、ADF Facesコンポーネントをアクティブ・データ・ソースにバインドできます。このためには、Fusionテクノロジ・スタックを使用し、コンポーネントとバインディングを構成して、コンポーネントがソースで更新されたデータを表示できるようにする必要があります。あるいは、あらかじめ決められた間隔で変更のデータ・ソースをポーリングするようにアプリケーションを構成することもできます。詳細は、23.6.1項「アクティブ・データを表示するデータ・バインドされたグラフ・コンポーネントの構成方法」を参照してください。

23.6.1 アクティブ・データを表示するデータ・バインドされたグラフ・コンポーネントの構成方法

アクティブ・データ・サービスは、次のグラフ・タイプに対しサポートされます。

表23-6 アクティブ・データをサポートするグラフ・コンポーネント

グラフ・コンポーネント

グラフ・タグ

サブタイプ

3Dサポートの有無

面

dvt:areaGraph

AREA_VERT_ABS

いいえ

棒

dvt:barGraph

BAR_VERT_CLUST(矩形バー形状のみ)

BAR_VERT_STACK(矩形バー形状のみ)

はい

バブル

dvt:bubbleGraph

BUBBLE

いいえ

組合せ

dvt:comboGraph

COMBINATION_VERT_ABS(矩形バー形状のみ)

いいえ

折れ線

dvt:lineGraph

LINE_VERT_ABS

いいえ

円

dvt:pieGraph

PIE

はい

散布

dvt:scatterGraph

SCATTER

いいえ

アクティブ・データ・サービスを使用するには、データが変更されたときにイベントを公開するデータ・ソースが必要であり、それらのイベントに反応するビジネス・サービスと、それらのサービスを表示するための関連のデータ・コントロールを作成する必要があります。ADSおよびアプリケーションの構成の詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

データ・バインドされたグラフを構成し、対応するページ定義ファイルでバインディング要素に値を設定することによってアクティブ・データを表示します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにデータ・バインドされたグラフを追加します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

- データ変更時にイベントを発行するデータ・ソース、関連するビジネス・サービスおよびデータ・コントロールを作成します。詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

アクティブ・データを表示するデータ・バインドされたグラフを構成する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「ページ定義に移動」を選択してページの関連するページ定義ファイルを開きます。

2. ページ定義ファイルの構造ウィンドウで、コンポーネントにバインドされた属性を表すノードを選択します。

3. 「プロパティ」ウィンドウで、ChangeEventPolicy属性にpushを選択します。

23.6.2 グラフのアニメーション効果の指定

アニメーションを使用するグラフの「プロパティ」ウィンドウで、次の属性を設定します。

- animationOnDisplay: オプション。適用する初期レンダリング効果のタイプの指定に使用します。有効な値は次のとおりです。

- none (デフォルト): 初期レンダリング効果を表示しません。

- auto: グラフ・タイプに基づいて自動的に選択された初期レンダリング効果を適用します。

- alphaFade

- conveyorFromLeftまたはconveyorFromRight

- cubeToLeftまたはcubeToRight

- flipLeftまたはflipRight

- slideToLeftまたはslideToRight

- transitionToLeftまたはtransitionToRight

- zoom

- animationOnDataChange: オプション。適用するデータ変化のアニメーションでデータ・タイプの指定に使用します。有効な値はグラフ・タイプにより異なります。有効な値を以下に示します。

- none: データ変更のアニメーション効果は適用されません。

- activeData(デフォルト): アクティブ・データ・サービス(ADS)のデータ変更のアニメーション・イベントが適用されます。グラフ・タイプがアクティブ・データをサポートする場合、これがデフォルト値です。

- auto: 部分ページ・リフレッシュ(PPR)およびADSデータ変更アニメーション・イベントを適用します。

- alphaFade

- conveyorFromLeftまたはconveyorFromRight

- cubeToLeftまたはcubeToRight

- flipLeftまたはflipRight

- slideToLeftまたはslideToRight

- transitionToLeftまたはtransitionToRight

- zoom

- animationDuration: アニメーション効果をミリ秒で指定するために使用します。

- animationIndicators: 表示するデータ変化のインジケータのタイプを指定するために使用します。有効な値は次のとおりです。

- none: データ変更のインジケータは表示されません。

- all(デフォルト): すべてのデータ変更のインジケータを表示します。

- animationUpColor: データ値が増加したことを示すために使用するRGB16色の指定に使用します。

- animationDownColor: データ値が減少したことを示すために使用するRGB16色の指定に使用します。

23.7 インタラクティブな機能のグラフへの追加

マーカーと凡例の淡色表示、ズームとスクロール、ドリル、インタラクティブな時間軸、注釈とアラート、ドラッグ・アンド・ドロップ、ポップアップ、選択サポート、コンテキスト・メニューなどのインタラクティブ機能をグラフに追加できます。

23.7.1 マーカーと凡例の淡色表示の追加方法

マーカーには線、棒、面、散布マーカー、バブルおよび円グラフのスライスが含まれます。特定のデータのセット内の1つのデータ・マーカーまたはグラフの凡例の対応するエントリの上にカーソルを移動すると、そのセットのすべてのデータ・マーカーが強調表示されるようにすることができます。強調表示効果は、セットの他のデータ・マーカーを淡色表示することによって視覚的に実現します。たとえば、棒グラフに4つの製品(P1、P2、P3、P4)の月ごとの売上げを表示する場合、製品P2の1月にカーソルを移動すると、P2のすべての棒が強調表示され、P1、P3およびP4の棒は淡色表示されます。

グラフでは特定のデータのセットのすべてのデータ・マーカー(P2のすべての棒など)を系列として参照するため、系列内のデータ・マーカーを強調表示する機能は、グラフの系列ロールオーバー動作機能の一部です。

系列ロールオーバー動作は、棒グラフ、折れ線グラフ、面グラフ、円グラフ、散布図、極グラフ、レーダー・グラフおよびバブル・グラフでのみ使用できます。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

系列内のすべてのデータ・マーカーを淡色表示する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「外観」セクションのSeriesRolloverBehaviorフィールドで、属性ドロップダウン・リストを使用してRB_DIMを選択します。

23.7.2 ズームとスクロール・レベルの変更に対応する方法

23.3.3.2項「軸でのスクロールの指定」の説明に従い、1つ以上のグラフ軸でスクロールを構成すると、ズームが有効になります。

グラフでズームおよびスクロール・レベルが変更されたときに実行されるカスタム・コードを指定できます。たとえば、メソッドを記述して、ズームされる軸およびズームされた軸の現在の範囲を決定できます。

このメソッドは、ZoomEventまたはScrollEventを入力として受け入れるマネージドBeanに格納します。例23-11に、グラフのズームおよびスクロール・イベントを処理するメソッドを作成するためのサンプル・コードを示します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフでのズームとスクロールに対応するカスタム動作を指定する手順:

1. マネージドBeanを作成し、ズームおよびスクロール・イベントに応答するメソッドを追加します。詳細なヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。
たとえば、例23-11のサンプル・コードを使用するには、sampleGraphという名前のマネージドBeanを作成し、例のメソッドを追加します。

2. 「プロパティ」ウィンドウで、まだ有効にしていない場合は、メソッドで管理される軸のスクロールを構成します。
たとえば、例23-11のサンプル・コードを使用する場合は、dvt:o1Axisノードのスクロールを有効にします。スクロールの構成の詳細は、23.3.3.2項「軸でのスクロールの指定」を参照してください。

3. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、「動作」セクションを展開し、次の一方または両方を実行します。

- ZoomListenerフィールドに、マネージドBeanに格納したメソッドへの参照を指定します。
たとえば、setZoomメソッドがsampleGraphマネージドBeanに格納されている場合、"#{sampleGraph.setZoom}"という設定になります。

- ScrollListenerフィールドに、マネージドBeanに格納したメソッドへの参照を指定します。
たとえば、setScrollメソッドがsampleGraphマネージドBeanに格納されている場合、"#{sampleGraph.setScroll}"という設定になります。

例23-11 ズームとスクロールを設定するためのサンプル・コード

Managed bean sampleGraph.java:
public void setZoom(ZoomEvent event) {
System.out.println("Start Group: " + event.getAxisStartGroup(ZoomEvent.O1AXIS));
System.out.println("Group Count: " + event.getAxisGroupCount(ZoomEvent.O1AXIS));
System.out.println("Start Group Label: " + event.getAxisStartGroupLabel(ZoomEvent.O1AXIS));
}
public void setScroll(ScrollEvent event) {
System.out.println("End Group Label: " + event.getAxisEndGroupLabel(ScrollEvent.O1AXIS));
System.out.println("Axis Min: " + event.getAxisMin(ScrollEvent.O1AXIS));
System.out.println("Axis Max: " + event.getAxisMax(ScrollEvent.O1AXIS));
}

23.7.3 インタラクティブな時間軸のグラフへの追加

時間データを表示する相対的範囲と明示的範囲を定義できます。また、時間セレクタを追加して、ユーザーが時間軸上で時間範囲を選択できるようにすることもできます。

23.7.3.1 時間データを表示する相対的範囲の定義方法

時間データを表示する単純な相対範囲(過去7日間など)を定義できます。これによって、新しいデータ・ポイントがアクティブ・データ・グラフの表示に追加され、古いデータがグラフの左端からはみ出ることになります。相対時間範囲の指定は、アクティブ・データ・グラフでの使用に限定されません。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

時間値に基づいて軸を表示するグラフがページにある必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

時間データを表示する相対範囲を指定する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」セクションを展開し、次の属性に値を指定します。

1. TimeRangeMode: 相対範囲を時間範囲の終わりに適用する(最後の7日間など)か、始めに適用する(最初の7日間など)かに応じて、値TRM_RELATIVE_LASTまたはTRM_RELATIVE_FIRSTを指定します。

2. TimeRelativeRange: 相対範囲をミリ秒で指定します。
たとえば、7日間の範囲を指定する場合は、日数(7)に1日をミリ秒にした数(86400000)を掛けた、604800000となります。

23.7.3.2 時間データを表示する明示的範囲の定義方法

時間データを表示する明示的範囲(3月15日から3月25日など)を定義できます。この例では、開始と終了の値に指定されていないため、年、時間、分および秒にはデフォルト値が使用されます。

明示的範囲の開始日および終了日を指定するためのメソッドを、グラフのマネージドBeanに格納します。

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- マネージドBeanに、時間範囲の開始日と終了日を返すメソッドを作成します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。
例23-12に、時間範囲の開始日と終了日を返す2つのサンプル・メソッドを示します。

例23-12 明示的時間範囲の開始日と終了日を設定するサンプル・コード

// Add the following imports to your bean
import java.util.Date;
import java.util.Calendar;
import java.util.GregorianCalendar;

// Add the following variables to your bean
private static Calendar cal1 = new GregorianCalendar (2011,0,2);
private static Calendar cal2 = new GregorianCalendar (2011,0,4);
private static Date m_startDate = cal1.getTime();
private static Date m_endDate = cal2.getTime();

// Add the following methods to your bean
public Date getStartDate(){
return m_startDate;
}
public Date getEndDate(){
return m_endDate;
}

- 時間値に基づいて軸を表示するグラフをページに作成します。詳細は、第23.2.3項「ページへのグラフの追加方法」を参照してください。

時間データを表示する明示的範囲を指定する手順:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」セクションを展開し、次の属性に値を指定します。

1. TimeRangeMode: 属性のドロップダウン・メニューからTRM_EXPLICITを選択します。

2. TimeRangeStart: 時間範囲の開始日を返すメソッドへの参照を指定します。
たとえば、timeAxisSampleという名前のマネージドBeanと、例23-12で参照されているgetStartDate()メソッドの場合は、初期日付に#{timeAxisSample.startDate}と入力します。

3. TimeRangeEnd: 時間範囲の終了日を返すメソッドへの参照を指定します。

23.7.3.3 グラフへの時間セレクタの追加方法

時間軸を表示するように構成されているグラフには、時間セレクタを追加できます。時間セレクタを使用すると、ユーザーは時間軸でデータの範囲を選択できます。通常、時間セレクタは、ディテールが時間セレクタの日付範囲に基づいて表示される、マスター/ディテール・グラフで使用されます。

グラフに時間セレクタを追加するには、グラフにdvt:timeSelectorコンポーネントを追加し、マネージドBeanまたはバッキングBeanに範囲の開始日と終了日を返すためのメソッドを追加します。マスター/ディテール・グラフを構成する場合は、ユーザーが時間セレクタを移動したときにディテール・グラフを更新するためのリスナーを時間セレクタに追加します。

図23-46に、時間セレクタを使用するように構成されたマスター/ディテール・グラフの簡単な例を示します。ユーザーがマスター・グラフで時間セレクタを別の日付範囲に移動すると、棒グラフの表示が自動的に更新されます。

図23-46 マスター/ディテール・グラフの時間セレクタ

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- 時間値に基づいて軸を表示するグラフをページに作成します。詳細は、第23.2.3項「ページへのグラフの追加方法」を参照してください。
面、棒、折れ線、組合せの各グラフおよび株価チャートには、列ラベルにオブジェクト・タイプがjava.util.Dateの日付が指定された場合に、時間軸が表示されます。時間セレクタを使用するには、日付を昇順でソートし、日、週、月などの一定の間隔を使用するようにします。

たとえば、図23-46の折れ線グラフでは、o1軸に販売日付を、系列に総売上げを使用しています。図23-47に、サンプル・データを示します。

図23-47 時間セレクタの例のサンプル・データ

- マスター/ディテール・グラフを構成する場合は、ディテールが時間セレクタの開始日と終了日に基づいて表示されるグラフを作成します。
たとえば、図23-46の棒グラフでもo1軸に販売日付が使用されていますが、総売上げに加えて純売上げのデータも表示されています。

- マネージドBeanまたはバッキングBeanに、時間範囲の開始日と終了日を返すメソッドを作成します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。
例23-13に、時間セレクタの時間範囲の開始日と終了日を返す2つのサンプル・メソッドを示します。

例23-13 時間セレクタの開始日と終了日を返すサンプル・メソッド

// Include these imports in your bean
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;

// Add these variables to your bean
private static Calendar cal1 = new GregorianCalendar (2011,0,2);
private static Calendar cal2 = new GregorianCalendar (2011,0,4);
private static Date m_startDate = cal1.getTime();
private static Date m_endDate = cal2.getTime();

// Add these methods to your bean
public Date getTimeAxisStartDate() {
return m_startDate;
}
public Date getTimeAxisEndDate() {
return m_endDate;
}

- オプションで、マネージドBeanに時間セレクタのリスナー用のメソッドを追加します。
例23-14に、図23-46に表示されている時間セレクタのサンプル・リスナーを示します。

例23-14 時間セレクタのリスナーのサンプル・コード

// Include these imports in your bean
import java.util.Date;
import java.util.Calendar;
import java.util.GregorianCalendar;
import oracle.adf.view.faces.bi.event.TimeSelectorEvent;
import javax.faces.event.AbortProcessingException;

// Add this method to your bean
public void processTimeSelectorEvent(TimeSelectorEvent event) throws AbortProcessingException
{
Date startDate = new Date(event.getStartDate().getTime());
Date endDate = new Date(event.getEndDate().getTime());
if (graph2 != null)
{
graph2.setTimeRangeStart(startDate);
graph2.setTimeRangeEnd(endDate);
}
}

この例では、graph2変数はページのバッキングBeanでUIGraphとして宣言されています。ユーザーがマスター・グラフで時間セレクタの範囲を変更すると、リスナーのコードによってディテール・グラフに新しい時間範囲が設定されます。

グラフに時間セレクタを追加するには:

1. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「時間セレクタ」を選択します。

2. dvt:timeSelectorノードを右クリックして、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、次の属性に値を入力します。

- ExplicitStart: 時間範囲の初期の開始日を返すメソッドへの参照を指定します。
たとえば、timeSelectorDemoという名前のBeanと、例23-13で参照されているgetTimeAxisStartDate()メソッドの場合は、初期日付に#{timeSelectorDemo.timeAxisStartDate}と入力します。

- ExplicitEnd: 時間範囲の初期の終了日を返すメソッドへの参照を指定します。

- Mode: 属性のドロップダウン・リストから「EXPLICIT」を選択して、時間セレクタの表示を有効にします。デフォルトでは、この属性はOFFに設定されています。

- FillColor: 属性のドロップダウン・リストから、時間セレクタの塗りつぶしの色を選択します。

- 時間セレクタの背後にデータ・ポイントを表示するには、「透明度」スライダを使用して100%未満の値を選択します。
たとえば、「透明度」スライダを53%に設定すると、図23-46の時間セレクタが複製されます。これにより、塗りつぶしの色の値が6桁の16進数値から8桁の値に変更されます。最初の2桁は、塗りつぶしの色の透明度を表します。デフォルトでは、塗りつぶしの色は#000000に設定されており、時間セレクタの塗りつぶしの色は不透明です。

- オプションで透明色を有効にするには、FillTransparentドロップダウン・リストからtrueを選択します。
FillTransparentとBorderTransparentをtrueに設定すると、時間セレクタは表示されなくなりますが、ユーザーはこれを選択できます。

- BorderColor: 属性のドロップダウン・リストから、時間セレクタの枠線の色を選択します。

- オプションで透明色を有効にするには、BorderTransparentドロップダウン・リストからtrueを選択します。

- オプションで、「TimeSelectorListener」フィールドに、時間セレクタのリスナーを返すメソッドへの参照を指定します。
たとえば、timeSelectorDemoという名前のBeanと、例23-14で参照されているprocessTimeSelectorEventメソッドの場合は、時間セレクタのリスナーに#{timeSelectorDemo.processTimeSelectorEvent}と入力します。

例23-15に、時間セレクタの例に対応するJSFページのコードを示します。

例23-15 JSFページの時間セレクタのコード

<dvt:timeSelector explicitStart="#{timeSelectorDemo.timeAxisStartDate}"
explicitEnd="#{timeSelectorDemo.timeAxisEndDate}"
fillColor="#88c6d6ff" borderColor="#a5c6ff" mode="EXPLICIT"
timeSelectorListener="#{timeSelectorDemo.processTimeSelectorEvent}"/>

4. ディテール・グラフを作成した場合は、ディテール・グラフが明示的な時間範囲を使用するように更新し、時間セレクタが変更されると時間範囲が更新されるように構成します。

1. 構造ウィンドウで、ディテール・グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。

3. TimeRangeMode属性のドロップダウン・リストからTRM_EXPLICITを選択します。

4. 「TimeRangeStart」フィールドに、時間範囲の開始時間を返すメソッドへの参照を指定します。
たとえば、timeSelectorDemoという名前のBeanと、例23-13で参照されているgetTimeAxisStartDate()メソッドの場合は、初期日付に#{timeSelectorDemo.timeAxisStartDate}と入力します。

5. 「TimeRangeEnd」フィールドに、時間範囲の終了時間を返すメソッドへの参照を指定します。

6. 「プロパティ」ウィンドウで、「動作」セクションを展開します。

7. PartialTriggersフィールドにマスター・グラフのIDを入力して、ユーザーが時間セレクタの範囲を変更したときにディテール・グラフを更新できるようにします。
たとえば、図23-46の折れ線グラフのIDを参照する場合は、::graph1と入力します。また、PartialTriggersのドロップダウン・メニューから「編集」を選択して、部分トリガーを選択することもできます。

23.7.4 アラートおよび注釈のグラフへの追加

アラートは、エラーや警告など、個別の記号で強調表示する必要のあるデータ・ポイントをグラフ上に定義します。アイコンはアラートの場所を示します。カーソルをアラート・アイコン上に移動すると、そのアラートのテキストが表示されます。

注釈は、カーソルがデータ値上に移動するときに情報を提供するために、グラフ上のデータ値に関連付けられています。

23.7.4.1 グラフへのアラートの追加方法

アラートは、dvt:alertタグを使用してグラフにいくつでも定義できます。アラートはグラフ・タグの子であるdvt:alertSetタグにラップされます。アラートごとに、イメージ・ソース(imageSource)、およびアラートを表示するX軸または順序軸(xValue)とY軸(yValue)上の場所を指定する必要があります。グラフでY2軸を使用する場合、YValueAssignment属性を使用してyValueをY2軸に関連付けることができます。ユーザーがアラートにマウス・カーソルを合わせたときに表示されるテキストも指定できます。

例23-16に、折れ線グラフに表示されるアラートのコードを示します。この例では、alertBeanマネージドBeanでxValueおよびyValue属性が定義されています。実行時に、ユーザーは、スピン・ボックスまたは日付セレクタを変更することで、両方の軸上のアラートの場所を変更できます。

例23-16 グラフ・アラートのサンプル・コード

<af:panelGroupLayout>
<af:outputText value="Use spin box and date selector to change alert location."
id="ot2"/>
<af:panelGroupLayout id="pgl2" layout="horizontal">
<dvt:lineGraph id="graph1"
subType="LINE_VERT_ABS"
tabularData="#{alertBean.lineList}"
timeAxisType="TAT_MIXED_FREQUENCY_STRICT"
partialTriggers="::al1 ::yValue"
shortDesc="Line Graph">
<dvt:graphTitle text="Line Graph"/>
<dvt:alertSet>
<dvt:alert xValue="#{alertBean.alertDate}"
yValue="#{alertBean.alertYValue}"
imageSource="#{resource['images:alert_icon.png']}"
text="Alert Example"/>
</dvt:alertSet>
<dvt:graphFootnote text="Alerts assigned to location and date"/>
</dvt:lineGraph>
<af:panelGroupLayout layout="vertical" id="pgl8">
<af:inputDate label="Date" id="al1" value="#{alertBean.alertDate}"
autoSubmit="true"/>
<af:inputNumberSpinbox label="Y Value" id="yValue"
value="#{alertBean.alertYValue}"
autoSubmit="true" stepSize="10"/>
</af:panelGroupLayout>
</af:panelGroupLayout>

「プロパティ」ウィンドウで、アラートの場所属性に値を指定します。xValue属性には、string、doubleまたはdate型の値を指定できます。yValueには、double型の値を指定する必要があります。

xValueがdate型の場合、グラフのマネージドBeanでアラートのxValueを設定するメソッドを定義する必要があります。例23-17に、表形式データのサンプル配列を作成し、ユーザーの選択に合わせてアラートの日付および値を変更するアラートのメソッドを定義するコードを示します。表形式データの詳細は、23.2.5項「表形式データを使用したグラフの作成方法」を参照してください。マネージドBeanのヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。

例23-17 グラフ・アラートのサンプル・マネージドBean

import java.util.Date;
import java.util.ArrayList;
import java.util.Random;
import java.util.List;
import java.util.Calendar;
import java.util.GregorianCalendar;

public class alertBean {
private List m_lineList;
private Double m_alertYValue;
private static Calendar cal1 = new GregorianCalendar (2010,0,1);
private static Calendar cal2 = new GregorianCalendar (2010,0,1);
private Date m_date;
public alertBean(){
m_alertYValue = new Double(100);
m_date = cal1.getTime();
Random random = new Random();
m_lineList = new ArrayList();
Date newDate = cal2.getTime();
for (int i = 0; i < 100; i ++){
double number = random.nextDouble() * 20+90;
m_lineList.add(new Object[]{"Group "+i,"Series 1", newDate});
m_lineList.add(new Object[]{"Group' "+i,"Series 1",
new Double(number)});
newDate = new Date(newDate.getTime() + 86400000);
}
}
public List getLineList(){
return m_lineList;
}
public Date getAlertDate(){
return m_date;
}
public void setAlertDate(Date date){
m_date = date;
}
public Double getAlertYValue(){
return m_alertYValue;
}
public void setAlertYValue(Double value){
m_alertYValue = value;
}
}

図23-48に、アプリケーション起動時にレンダリングされる初期ページを示します。日付を変更すると、またはY軸に異なる値を入力すると、アラートが新しい場所に移動します。

図23-48 カスタマイズ可能なアラートの場所を備えた折れ線グラフ

始める前に:

グラフの属性やグラフの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

ページにすでにグラフが存在している必要があります。ない場合は、この章の指示に従ってグラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

グラフにアラートを追加する手順:

1. オプションで、マネージドBeanを作成し、アラート値を設定および取得するコードを追加します。詳細なヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。
たとえば、図23-48に表示されているアラートを複製するには、例23-17のコードを使用してpopupSample.javaという名前のマネージドBeanを作成します。

2. 「構造」ウィンドウで、「dvt:typeGraph」ノードを右クリックし、「グラフ・タイプの中に挿入」→「ADFデータ視覚化」→「アラート・セット」を選択します。

3. 「dvt:alert」ノードを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで次の属性を設定します。

- ImageSource: 既存イメージを選択する属性のドロップダウン・メニューを使用して、アラートのアイコンへのパスを指定するか、「編集」を選択して新しいイメージをアプリケーションに追加します。

- Text: アイコンにマウス・ポインタを合わせたときにツールチップに表示されるオプションのテキストを指定します。

- XValue: X軸または順序軸の値を指定します。オプションで、属性のドロップダウン・メニューを使用してEL式ビルダーにアクセスし、アラートのxValueを設定するメソッドを選択します。
たとえば、例23-17のalertBeanマネージドBeanおよびsetAlertDateメソッドでは、xValueを値#{alertBean.alertDate}に設定します。

- YValue: Y軸の値を指定します。オプションで、属性のドロップダウン・メニューを使用してEL式ビルダーにアクセスし、アラートのyValueを設定するメソッドを選択します。
たとえば、例23-17のalertBeanマネージドBeanおよびsetAlertYValueメソッドでは、yValueを値#{alertBean.alertDate}に設定します。

- YValueAssignment: yValue属性に関連付ける軸を指定します。有効な値は、Y1AXIS(デフォルト)またはY2AXIS(構成済の場合)です。
例23-17のマネージドBeanの例では、yValueがY1AXISに関連付けられるため、デフォルトを変更する必要はありません。

5. アラートを追加するには、新しいアラートごとに「構造」ウィンドウで「dvt:alertSet」を右クリックし、「アラート・セットの中に挿入」→「アラート」を選択します。

6. ステップ3とステップ4を繰り返して新しいアラートを構成します。

23.7.4.2 グラフへの注釈の追加

1つのグラフにはdvt:annotationタグを使用していくつでも注釈を定義でき、複数の注釈を1つのデータ値に関連付けることができます。注釈は、グラフ・タグの子であるdvt:annotationSetタグにラップされます。

注釈に関連付けられたデータ・マーカーは、dvt:annotationタグの次の属性を使用して定義されます。

- series: グラフの系列のゼロベースの索引を指定します。ほとんどのグラフでは、各系列が同じ色のマーカー・セットとして表示されます。たとえば、複数円グラフでは、黄色の各区分が靴の売上を表し、緑の各区分がブーツの売上を表す場合があります。棒グラフでは、黄色の棒がすべて靴の売上を表し、緑の棒がブーツの売上を表す場合があります。

- group: グラフのグループのゼロベースの索引を指定します。グループの表示は、グラフ・タイプによって異なります。集合棒グラフでは、棒の各集合が1つのグループになります。積上げ棒グラフでは、各積層がグループです。複数円グラフでは、各円がグループです。

例23-18に、面グラフの注釈のセットを示します。

例23-18 注釈のセットのサンプル・コード

<dvt:areaGraph>
<dvt:annotationSet>
<dvt:annotation series="0" group="0" text="annotation #1"/>
<dvt:annotation series="0" group="7" fillColor="#55FFFF00"
borderColor="#55FF0000" text="second annotation"/>
</dvt:annotationSet>
</dvt:areaGraph>

グラフの描画エリアでは次の属性を使用して注釈の位置を制御できます。

- position: 注釈に使用する配置のタイプを指定します。有効な値は次のとおりです。

- dataValue(デフォルト): seriesおよびgroup属性で定義されるデータ値で注釈を配置します。他の注釈との重なりは避けられます。

- absolute: X軸とY軸の両方があるグラフのxValueとyValueにより定義された正確な位置に注釈を配置します。他の注釈との重なりは避けられません。

- percentage: X軸とY軸の両方があるグラフの描画エリアの0から100のパーセンテージとしてxValueとyValueを使用して定義された正確な位置に注釈を配置します。他の注釈との重なりは避けられません。

- xValue: 注釈を配置するX値を指定します。この設定は、注釈のpositionがabsoluteまたはpercentageの場合にのみ適用されます。

- yValue: 注釈を配置するY値を指定します。この設定は、注釈のpositionがabsoluteまたはpercentageの場合にのみ適用されます。

- horizontalAlignment: 注釈の水平配置を指定します。この設定は、注釈のposition属性がabsoluteまたはpercentageの場合にのみ適用されます。有効な値は、LEFT (デフォルト)、CENTER、LEADINGまたはRIGHTです。

- verticalAlignment: 注釈の垂直配置を指定します。この設定は、注釈のposition属性がabsoluteまたはpercentageの場合にのみ適用されます。有効な値は、CENTER (デフォルト)、TOPまたはBOTTOMです。

23.7.5 ドリル可能なグラフの作成

アプリケーションでFusionテクノロジ・スタックが使用される場合、ドリル可能なグラフを作成できます。ドリル可能なグラフはADFデータ・コントロールにバインドされ、面、線またはマーカーで表示されるデータの詳細なビューを表示します。グラフをドリル可能にするには、<type>GraphコンポーネントのdrillingEnabled属性をtrueに設定します。デフォルト値はfalseです。

また、グラフのページ定義ファイルを更新してドリル階層を定義し、集計データの表示方法を指定する必要があります。データ・バインドされたグラフへのドリル・サポートの追加の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたグラフの作成に関する項を参照してください。

23.7.6 グラフへのドラッグ・アンド・ドロップの追加

ADF Facesフレームワークには、ページ上の場所から別の場所へアイテムをドラッグ・アンド・ドロップする機能があります。バブル・グラフと散布図は、子のaf:dragSourceコンポーネントを追加し構成することにより、マーカーをグラフの描画エリアのある位置から別の位置へ移動できるドラック・ソースとして構成できます。X位置およびY位置を備えたすべてのデータ軸グラフをドロップ・ターゲットとして構成できます。たとえば、子af:dropTargetコンポーネントを追加および構成することで、棒グラフにバブル・グラフ・マーカーを挿入できます。

23.7.6.1 グラフにドラッグ・アンド・ドロップを追加する方法

グラフは、次の操作をサポートするように構成できます。

- グラフ間のドラッグ

- グラフから別のADFコンポーネントへのドラッグ

- グラフの描画エリア内での散布/バブル・マーカーのドラッグ

- 別のコンポーネントへの散布/バブル・マーカーのドラッグ

- 複数のマーカーのドラッグ

たとえば、バブル・グラフ内のデータ・マーカーをドラッグして表ビューでそれらの値を表示したり、逆に、表からバブル・グラフで表示するためにデータ値をドラッグしたりできます。図23-49に、ドラッグ元として構成されたバブル・グラフと、この機能を果たすためのドロップ・ターゲットを示します。

図23-49 ドラッグ元としてのバブル・グラフとドロップ・ターゲット

マネージドBeanでドラッグ・アンド・ドロップ・イベントに応答するメソッドを定義します。例23-19に、図23-49で使用されているドラッグ・アンド・ドロップ・リスナーを追加するためのサンプル・コードを示します。マネージドBeanの使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

例23-19 ドラッグ・アンド・ドロップ・ターゲットを処理するためのマネージドBeanのサンプル

public class dragAndDrop {
public DnDAction fromGraphDropListener(DropEvent event) {
// Get the ComponentHandle from the transferable
Transferable transferable = event.getTransferable();
GraphSelectionSet selectionSet =  transferable.getData(GraphSelectionSet.class);
// Now change each marker based on the DropEvent's proposed action
DnDAction proposedAction = event.getProposedAction();
for(GraphSelection selection : selectionSet) {
Employee emp = findEmployee(m_graphList, selection);
if(emp == null)
return DnDAction.NONE;
if(proposedAction == DnDAction.COPY) {
m_tableModel.add(new Employee("Copy of " + emp.getName(), emp));
}
else if(proposedAction == DnDAction.LINK) {
m_tableModel.add(new Employee("Link to " + emp.getName(), emp));
}
else if(proposedAction == DnDAction.MOVE) {
m_graphList.remove(emp);
m_tableModel.add(emp);
}
}
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return proposedAction;
}
public DnDAction fromTableDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<RowKeySet> dataFlavor = DataFlavor.getDataFlavor(RowKeySet.class, "fromTable");
RowKeySet set = transferable.getData(dataFlavor);
Employee emp = null;
if(set != null && !set.isEmpty()) {
int index = (Integer) set.iterator().next();
emp = m_tableModel.get(index);
}
if(emp == null)
return DnDAction.NONE;
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
m_graphList.add(emp);
}
else if(proposedAction == DnDAction.LINK) {
m_graphList.add(emp);
}
else if(proposedAction == DnDAction.MOVE) {
m_graphList.add(emp);
m_tableModel.remove(emp);
}
else
return DnDAction.NONE;
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return event.getProposedAction();
}

始める前に:

グラフの属性やグラフの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにバブル・グラフを作成します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。

- ドラッグ・ソースおよびドロップ・ターゲットとして表コンポーネントを作成および構成します。例23-20に、表作成のサンプル・コードを示します。表作成の詳細は、第12章「表へのデータの表示」を参照してください。ドラッグ・ソースおよびドロップ・ターゲットの作成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

例23-20 表のドラッグ元およびドロップ・ターゲットのサンプル・コード

<af:table id="table" value="#{dragAndDrop.tableModel}"
var="row" width="420" inlineStyle=" height:300px;"
columnStretching="last">
<af:dragSource actions="COPY MOVE LINK" defaultAction="MOVE"
discriminant="fromTable"/>
<af:dropTarget dropListener="#{dragAndDrop.fromGraphDropListener}"
actions="COPY MOVE LINK">
<af:dataFlavor
flavorClass="oracle.adf.view.faces.bi.component.graph.GraphSelectionSet"
discriminant="fromGraph"/>
</af:dropTarget>
<af:column headerText="Name" id="c1">
<af:outputText value="#{row.name}" id="ot5"/>
</af:column>
<af:column headerText="Performance" id="c2">
<af:outputText value="#{row.performance}" id="ot6"/>
</af:column>
<af:column headerText="Salary" id="c3">
<af:outputText value="#{row.salary}" id="ot7"/>
</af:column>
<af:column headerText="Experience" id="c4">
<af:outputText value="#{row.experience}" id="ot8"/>
</af:column>
</af:table>

- マネージドBeanでドラッグ・アンド・ドロップ・イベントに応答するメソッドを作成します。例23-19に、ドラッグ・アンド・ドロップ・イベントを処理するためのサンプル・コードを示します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

バブル・グラフにドラッグ・アンド・ドロップを追加する手順:

1. 「構造」ウィンドウで「dvt:bubbleGraph」コンポーネントを右クリックし、「バブルの中に挿入」→「ADF Faces」→「ドラッグ元」を選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- Actions: このドラッグ元でサポートされるドラッグ・アンド・ドロップ・アクションを指定します。アクションは、使用可能な値(COPY、LINKまたはMOVE)をどの順序でも、空白区切りですべて大文字のリストにする必要があります。デフォルト値はCOPYです。

- DefaultAction: このドラッグ元でサポートされるデフォルトのドラッグ・アンド・ドロップ・アクションを指定します。指定可能なアクションは、COPY、LINKまたはMOVEです。

- Discriminant: このドラッグ元により生成されるデフォルトのデータ・フレーバの識別値を指定します。識別値は、このドラッグ元からのドラッグを識別するために使用されます。ドラッグ・アンド・ドロップは、互換性のあるドラッグ元とドロップ・ターゲット間でのみ実行できることに注意してください。識別値は、互換性維持の目的で使用されます。デフォルトのドラッグ・ソースによって生成されるデータ・フレーバの識別値は、ドロップ・ターゲットの許容データ・フレーバの許容識別値と一致する必要があります。

3. 「構造」ウィンドウで「dvt:bubbleGraph」ノードを右クリックし、「バブルの中に挿入」→「ADF Faces」→「ドロップ・ターゲット」を選択します。

4. 「ドロップ・ターゲットの挿入」ダイアログで、コンポーネントでドロップが発生したときに呼び出されるoracle.adf.view.rich.event.DropEventメソッドへの参照を評価するEL式として「DropListener」を指定します。
例23-21に、図23-49のバブル・グラフにドラッグ・アンド・ドロップ操作を追加するためのサンプル・コードを示します。この例で使用されているDropListenerを指定するには、#{dragAndDrop.fromTableDropListener}と入力します。

例23-21 バブル・グラフのドラッグ・アンド・ドロップのサンプル・コード

<dvt:bubbleGraph shortDesc="Graph" dataSelection="multiple"
markerTooltipTemplate="GROUP_LABEL NEW_LINEPerformance: X_VALUE
NEW_LINESalary: Y_VALUE NEW_LINEExperience: Z_VALUE"
value="#{dragAndDrop.graphModel}" id="bg1">
<dvt:x1Title text="Performance"/>
<dvt:y1Title text="Salary"/>
<dvt:x1Axis axisMaxValue="120" axisMaxAutoScaled="false"/>
<dvt:y1Axis axisMaxValue="120000" axisMaxAutoScaled="false"/>
<dvt:legendArea rendered="false"/>
<af:dragSource actions="COPY MOVE LINK" defaultAction="MOVE"
discriminant="fromGraph"/>
<af:dropTarget actions="COPY MOVE LINK"
dropListener="#{dragAndDrop.fromTableDropListener}">
<af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"
discriminant="fromTable"/>
</af:dropTarget>
</dvt:bubbleGraph>

5. 「データ・フレーバの挿入」ダイアログで、このdataFlavorの完全修飾Javaクラス名であるflavorClassを指定します。ドロップがこのdataFlavorを含むとき、ドロップ・ターゲットではdataFlavorを使用して、このJavaタイプを持つドロップからオブジェクトを取得することが保証されます。
たとえば、例23-21で使用されているflavorClassを指定するには、org.apache.myfaces.trinidad.model.RowKeySetと入力します。

23.7.6.2 グラフへのドラッグ・アンド・ドロップの追加に関する必知事項

図23-49のグラフおよび表データは、グラフおよび表のvalue属性で指定されています。この例では、マネージドBeanに簡単なEmployeeクラスを設定するためのコードが含まれます。グラフおよび表へのデータの指定の詳細は、22.3項「ADFデータ視覚化コンポーネントへのデータの指定」を参照してください。

例で使用されているEmployeeクラスおよびサンプル・メソッドを作成するマネージドBeanの完全バージョンは、F.2項を参照してください。

グラフでのドラッグ・アンド・ドロップの構成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

23.7.7 グラフへのポップアップの追加方法

グラフの子コンポーネントseriesSetは、情報を提供したり、エンド・ユーザーからの入力を要求したりするポップアップのダイアログ、ウィンドウおよびメニューが表示されるように構成できます。af:popupコンポーネントを他のADF Facesコンポーネントで使用すると、セカンダリ・ウィンドウでの情報の表示および非表示、追加データの入力、コンテキスト・メニューなどの機能の呼出しを、エンド・ユーザーに許可する機能を構成できます。

ADF Facesのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。af:showPopupBehaviorタグは宣言的ソリューションとなるため、popupコンポーネントを開くためのJavaScriptの作成や、スクリプトのpopupコンポーネントへの登録の必要がありません。これらのコンポーネントの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

たとえば、ノート・ウィンドウで情報を表示するポップアップを散布図の系列内のデータ・マーカーと関連付けることができます。図23-50に、データ・マーカーをクリックして、ノート・ウィンドウに特定のマーカーに関するデータを示すゲージを表示した散布図を示します。

図23-50 散布図のデータ・マーカー・ポップアップ・ノート・ウィンドウ

始める前に:

グラフの属性やグラフの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにグラフを追加します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。
図23-50のゲージ・ポップアップの例を複製するには、散布図を作成します。

- グラフの系列でデータ・ポイントが参照するポップアップ・コンポーネントを作成します。図23-50に、図23-50に表示されているグラフ系列のデータ・ポイントをユーザーがクリックすると参照されるポップアップのサンプル・コードを示します。

例23-22 グラフ・データ・マーカー・ポップアップ・ウィンドウのサンプル・コード

<af:popup id="graphPopup" launcherVar="source"
eventContext="launcher"
clientComponent="true" contentDelivery="lazyUncached">
<af:setPropertyListener from="#{source.seriesKey}"
to="#{popupSample.seriesKey}" type="popupFetch"/>
<af:setPropertyListener from="#{source.groupKeys}"
to="#{popupSample.groupKeys}" type="popupFetch"/>
<af:panelWindow title="Graph Popup" id="pw1">
<dvt:gauge shortDesc="Gauge" value="#{popupSample.gaugeValue}"
gaugeType="DIAL" animationOnDisplay="auto"
inlineStyle="width:150px;height:120px;" minValue="0"
maxValue="100" contentDelivery="immediate" id="g3">
<dvt:bottomLabel text="Sales" position="LP_NONE"/>
<dvt:metricLabel position="LP_NONE"/>
<dvt:thresholdSet>
<dvt:threshold thresholdMaxValue="#{popupSample.quotaValue}"
text="Under Quota"/>
<dvt:threshold fillColor="#84AE31" text="Above Quota"/>
</dvt:thresholdSet>
<dvt:indicator useThresholdFillColor="true"/>
<dvt:tickLabel content="TC_MIN_MAX TC_INCREMENTS"/>
<dvt:tickMark content="TC_NONE" majorTickCount="5"/>
</dvt:gauge>
</af:panelWindow>
</af:popup>

- マネージドBeanにメソッドを追加して、ポップアップ要求に応答するリスナー・メソッドを定義します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。
例23-23に、ゲージ・ポップアップの例のポップアップ要求に応答するために使用するサンプル・コードを示します。この例では、散布図でデフォルトのデータ値が使用されています。グラフへのデータの指定の詳細は、22.3項「ADFデータ視覚化コンポーネントへのデータの指定」を参照してください。

例23-23 グラフ・データ・マーカー・ポップアップのマネージドBeanのサンプル・コード

import java.util.List;
import java.util.Set;
import oracle.adf.view.faces.bi.component.gauge.UIGauge;
import oracle.adf.view.faces.bi.component.graph.UIGraph;
import oracle.adf.view.faces.bi.model.KeyMap;
import oracle.dss.graph.DataType;
public class popupSample {
private UIGraph m_graph;
private UIGauge m_gauge;
private KeyMap m_seriesKey;
private List<KeyMap> m_groupKeys;
public UIGraph getGraph() {
if(m_graph == null)
m_graph = new UIGraph();
return m_graph;
}
public void setGraph(UIGraph graph) { m_graph = graph; }
public UIGauge getGauge() {
if(m_gauge == null)
m_gauge = new UIGauge();
return m_gauge;
}
public void setGauge(UIGauge gauge) { m_gauge = gauge;}
public KeyMap getSeriesKey() { return m_seriesKey; }

public void setSeriesKey(KeyMap key) { m_seriesKey = key; }
public List<KeyMap> getGroupKeys() { return m_groupKeys; }
public void setGroupKeys(List<KeyMap> keys) { m_groupKeys = keys; }
private int m_gaugeValue = 0;
public int getGaugeValue() {
// Reestablish context
m_graph.setDataKey(m_seriesKey, m_groupKeys);
// Fetch the x value
Object val = m_graph.getDataValue(DataType.X_VALUE);
if(val instanceof Number) {
Number number = (Number) val;
m_gaugeValue = (int) number.doubleValue();
}
return m_gaugeValue;
}
private int m_quotaValue = 0;
public int getQuotaValue() {
// Reestablish context
m_graph.setDataKey(m_seriesKey, m_groupKeys);
// Fetch the y value
Object val = m_graph.getDataValue(DataType.Y_VALUE);
if(val instanceof Number) {
Number number = (Number) val;
m_quotaValue = (int) number.doubleValue();
}
return m_quotaValue;
}
}

グラフの系列セットにポップアップを追加する手順:

1. 「構造」ウィンドウで、グラフの子の「dvt:seriesSet」コンポーネントを右クリックし、「系列セットの中に挿入」→「ポップアップ表示動作」を選択します。

2. af:showPopupBehaviorノードを右クリックし、 「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで次の属性を設定します。

- PopupId: 包含するコンポーネントに関連するポップアップのIDを入力します。コロン1つで始まるIDは、コロンを除いた後、絶対値として扱われます。
たとえば、例23-22のゲージ・ポップアップを参照するには、::graphPopupと入力します。

- TriggerType: 表示されるポップアップをトリガーするイベント・タイプを入力します。グラフのseriesSetコンポーネントの有効な値は、action、clickおよびmouseHoverです。
たとえば、ゲージ・ポップアップの例を続行するには、clickと入力します。

- Align: ドロップダウン・リストから、ポップアップをどのようにseriesSetコンポーネントと位置合せするかを選択します。
この属性にはデフォルト設定がありませんが、この属性は通常必須です。ただし、ポップアップ・タイプがaf:panelWindowまたはaf:dialogの場合、この属性は設定する必要ありません。これらのタイプのポップアップは、ドラッグ・アンド・ドロップを使用して手動で再配置可能であり、デフォルトでブラウザ・ウィンドウの中央に開きます。

ゲージ・ポップアップの例を続行するには、ゲージ・ポップアップの例でaf:panelWindowタイプを使用するため、このフィールドは空白のままにします。

- AlignID: 位置合せするポップアップに関連するコンポーネントのIDを入力します。コロン1つで始まるIDは、コロンを除いた後、絶対値として扱われます。
ポップアップ・タイプがaf:panelWindowまたはaf:dialog以外の場合、この属性も通常必須です。ゲージ・ポップアップの例を続行するには、このフィールドは空白のままにします。

例23-24に、ポップアップ・コンポーネントをグラフの系列セットに関連付けるためのサンプル・コードを示します。

例23-24 系列セット・コンポーネントに関連付けられたポップアップのサンプル・コード

<dvt:scatterGraph dataSelection="single"
shortDesc="Scatter Graph with Click Popup"
binding="#{popupSample.graph}"
inlineStyle="width:500px;height:350px;" id="g2">
<dvt:seriesSet defaultMarkerShape="MS_HUMAN">
<af:showPopupBehavior triggerType="click" popupId="::graphPopup"/>
</dvt:seriesSet>
<dvt:x1Title text="Sales in Millions"/>
<dvt:y1Title text="Quota in Millions"/>
<dvt:graphTitle text="Sales Performance"/>
<dvt:graphSubtitle text="FY08"/>
</dvt:scatterGraph>

23.7.8 グラフのデータ・マーカー選択サポートの追加

選択サポートを追加して、ユーザーがグラフのデータ・マーカーを1つ以上選択したときにプログラムで応答します。

たとえば、図23-51に、単一および複数選択をサポートし、選択されたシリーズの情報を出力する棒グラフを示します。複数の選択を行うには、キーボードの[Ctrl]を押しながら複数のデータ・マーカーを選択します。

図23-51 複数選択サポートを表示する棒グラフ

23.7.8.1 グラフへの選択サポートの追加方法

選択サポートを追加するには、SelectionEventを処理して必要なロジックを実行するリスナーを、マネージドBean内に作成します。その後、グラフのdataSelection属性で選択サポートを有効にして、グラフのselectionListener属性をリスナーにバインドします。

例23-25に、選択状態を書式設定された文字列として図23-51の棒グラフの下に表示して返すマネージドBeanを作成するためのサンプル・コードを示します。

例23-25 グラフの選択サポート用マネージドBeanの例

import java.util.List;
import java.util.Set;
import oracle.adf.view.faces.bi.component.graph.DataSelection;
import oracle.adf.view.faces.bi.component.graph.GraphSelection;
import oracle.adf.view.faces.bi.event.graph.SelectionEvent;
import oracle.adf.view.faces.bi.model.KeyMap;

public class graphSelection {
public void selectionListener(SelectionEvent selectionEvent) {
StringBuilder eventInfo = new StringBuilder();
Set<? extends GraphSelection> selectionSet = selectionEvent.getGraphSelection();
eventInfo.append(convertSelectionStateToString(selectionSet));

// Store on the selection string
m_selectionInfo = eventInfo.toString();
}

/**
* Returns the selection state as a formatted String with one selected data point per line.
* @param selectionSet
* @return
*/
public static String convertSelectionStateToString(Set<? extends GraphSelection> selectionSet) {
StringBuilder selectionState = new StringBuilder();
for(GraphSelection selection: selectionSet) {
if(selection instanceof DataSelection) {
DataSelection ds = (DataSelection) selection;
Set seriesKeySet = ds.getSeriesKey().keySet();
for(Object key : seriesKeySet) {
selectionState.append(key).append(": ").append(ds.getSeriesKey().get((String)key));
}

List<KeyMap> groupKeys = ds.getGroupKeys();
for(KeyMap groupKey : groupKeys) {
Set groupKeySet = groupKey.keySet();
for(Object key : groupKeySet) {
selectionState.append("; ").append(key).append(": ").append(groupKey.get((String)key));
}
}

selectionState.append("<br>");
}
}

return selectionState.toString();
}

private String m_selectionInfo = "Select a marker to see information here.  Multiple objects can be selected by holding CTRL while selecting.";
public String getSelectionInfo() {
return m_selectionInfo;
}
}

例23-26に、複数選択サポート用のJDeveloperページを構成し、グラフのselectionListener属性を選択リスナーにバインドするためのサンプル・コードを示します。このサンプルでは、af:outputFormattedコンポーネントを使用して、選択された情報をページに表示しています。

例23-26 ページにグラフの選択サポートを構成するためのコード・サンプル

<af:panelGroupLayout id="pgl1">
<dvt:barGraph id="graph1" subType="BAR_VERT_CLUST" shortDesc="BarGraph"
selectionListener="#{graphSelection.selectionListener}"
dataSelection="multiple">
<dvt:background>
<dvt:specialEffects/>
</dvt:background>
<dvt:graphPlotArea/>
<dvt:seriesSet>
<dvt:series/>
</dvt:seriesSet>
<dvt:o1Axis/>
<dvt:y1Axis/>
<dvt:legendArea automaticPlacement="AP_NEVER"/>
</dvt:barGraph>
<af:outputFormatted id="selectionText"
inlineStyle="font-size:120.0%;"
partialTriggers="graph1"
value="#{graphSelection.selectionInfo}"/>
</af:panelGroupLayout>

始める前に:

グラフの属性やグラフの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、23.2.2項「グラフの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解しておくことをお薦めします。詳細は、23.1.3項「グラフ・コンポーネントの追加機能」を参照してください。

また、ADF Facesのイベント処理について理解しておくことをお薦めします。詳細は、第6章「イベント処理」を参照してください。

次のタスクを完了する必要があります。

- ページにグラフを追加します。詳細は、23.2.3項「ページへのグラフの追加方法」を参照してください。
この項の複数選択サポートの例と同じ構成を行う場合は、棒グラフを作成します。

- マネージドBeanにメソッドを追加して、選択イベントに応答するリスナー・メソッドを定義します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

グラフに選択サポートを追加するには:

1. 「構造」ウィンドウで「dvt:typeGraph」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを展開し、次の属性の値を指定します。

1. DataSelection: singleまたはmultipleを指定して、単一または複数のデータ・マーカーの選択サポートを有効にします。デフォルトはnoneで、選択はデフォルトでは有効になっていません。

2. SelectionListener: 選択リスナーへの参照を指定します。
たとえば、graphSelection.javaという名前のマネージドBeanでselectionListenerメソッドを指定するには、SelectionListenerフィールドに#{graphSelection.selectionListener}と入力します。

3. 必要に応じて追加の構成を行います。
たとえば、この項の複数選択の例を複製するには、ページに次のコードを追加します。

<af:outputFormatted id="selectionText"
inlineStyle="font-size:120.0%;"
partialTriggers="graph1" value="#{graphSelection.selectionInfo}"/>

23.7.8.2 グラフのデータ・マーカー選択に関する必知事項

選択リスナーはグラフのデータ・マーカーのみに対するクリック・イベントに応答します。

JDeveloperには、グラフの他のコンポーネントのクリック・イベントに応答できるclickListenerリスナーもあります。ただし、クリック・リスナーでは、単一選択サポートのみが提供され、ホバーとクリックのフィードバックがselectionListenerリスナーの場合とは異なります。また、新しいコンポーネントではclickListener属性を利用できないことからも、一般的はこのリスナーより選択リスナーの使用をお薦めします。

23.7.9 グラフのコンテキスト・メニューの構成

コンテキスト・メニューは、次のコンテキスト・メニュー・ファセットを使用して、グラフ・コンポーネント用に定義できます。

- bodyContextMenu: グラフ・コンポーネントの選択できない要素に表示されるコンテキスト・メニューを指定します。

- contextMenu: グラフ・コンポーネント内の選択可能要素で表示されるコンテキスト・メニューを指定します。

- multiSelectContextMenu: グラフ・コンポーネント内で複数の要素が選択されるときに表示されるコンテキスト・メニューを指定します。

JSPまたはJSPXページの各ファセットでは、1つの子コンポーネントがサポートされます。Faceletは、複数の子コンポーネントをサポートします。これらのファセットすべてを機能させるには、特定のグラフ・タイプ用に選択を有効にし、サポートされるようにする必要があります。コンテキスト・メニューは、現在のところFlashでのみサポートされています。

技術的な制限のために、Flashのレンダリング形式の使用時には、現在のところコンテキスト・メニューのコンテンツはFlash Playerのコンテキスト・メニューを使用して表示されます。このため、Flash Playerにより定義されたいくつかの制限があります。詳細は、22.2.4項「グラフ、ゲージ、ツリーマップおよびサンバーストのコンテキスト・メニュー」を参照してください。

たとえば、図23-52は、カスタム・メニュー項目が表示された散布図のコンテキスト・メニューを示しています。

図23-52 散布図のカスタム・コンテキスト・メニュー

例23-27に、散布図のコンテキスト・メニューを構成するためのサンプル・コードを示します。

例23-27 散布図のコンテキスト・メニューのサンプル・コード

<dvt:scatterGraph binding="#{contextMenu.graph}" subType="SCATTER"
dataSelection="multiple" id="graph" shortDesc="ScatterGraph">
<f:facet name="contextMenu">
<af:popup contentDelivery="lazyUncached" id="p1">
<af:menu id="m1">
<af:commandMenuItem text="Show Details"
actionListener="#{contextMenu.menuItemListener}"
id="cmi1"/>
<af:group id="g1">
<af:commandMenuItem text="Add Task for #{contextMenu.currentSeriesId}"
actionListener="#{contextMenu.menuItemListener}"
id="cmi2"/>
<af:commandMenuItem text="Add Task"
actionListener="#{contextMenu.menuItemListener}"
id="cmi3"/>
<af:commandMenuItem text="Add Notes"
actionListener="#{contextMenu.menuItemListener}"
id="cmi4"/>
</af:group>
</af:menu>
</af:popup>
</f:facet>
<f:facet name="bodyContextMenu">
<af:popup contentDelivery="immediate" id="p2">
<af:menu id="m2">
<af:goMenuItem text="www.oracle.com"
destination="http://www.oracle.com"
id="gmi1"/>
</af:menu>
</af:popup>
</f:facet>
<f:facet name="multiSelectContextMenu">
<af:popup contentDelivery="lazyUncached" id="p3">
<af:menu id="m3">
<af:commandMenuItem text="Compare Selected Objects"
actionListener="#{contextMenu.menuItemListener}"
id="cmi5"/>
</af:menu>
</af:popup>
</f:facet>
</dvt:scatterGraph>

例23-28に、カスタム・コンテキスト・メニューを作成するマネージドBeanのサンプル・コードを示します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

例23-28 カスタム・コンテキスト・メニューを作成するためのマネージドBean

import java.util.Set;
import javax.faces.component.UIComponent;
import javax.faces.event.ActionEvent;
import oracle.adf.view.faces.bi.component.graph.DataSelection;
import oracle.adf.view.faces.bi.component.graph.GraphSelection;
import oracle.adf.view.faces.bi.component.graph.UIGraph;
import oracle.adf.view.faces.bi.model.KeyMap;
import oracle.adf.view.rich.component.rich.nav.RichCommandMenuItem;
import oracle.adf.view.rich.component.rich.output.RichOutputFormatted;
import org.apache.myfaces.trinidad.context.RequestContext;

public class ContextMenu {
private RichOutputFormatted m_outputFormatted;
public RichOutputFormatted getOutputFormatted() {
if(m_outputFormatted == null)
m_outputFormatted = new RichOutputFormatted();
return m_outputFormatted;
}
public void setOutputFormatted(RichOutputFormatted text) {
m_outputFormatted = text;
}
private String m_status = "Click Menu Item for Status";
public String getStatus() {
return m_status;
}
private UIGraph m_graph;
public UIGraph getGraph() {
if(m_graph == null)
m_graph = new UIGraph();
return m_graph;
}
public void setGraph(UIGraph graph) {
m_graph = graph;
}
public String getCurrentSeriesId() {
if(m_graph != null) {
Set<? extends GraphSelection> set = m_graph.getSelection();
if(set != null && !set.isEmpty()) {
GraphSelection selection = set.iterator().next();
if(selection instanceof DataSelection) {
DataSelection dataSelection = (DataSelection) selection;
KeyMap seriesKey = dataSelection.getSeriesKey();
Set seriesKeySet = seriesKey.keySet();
for(Object key : seriesKeySet) {
return seriesKey.get((String)key);
}
}
}
}
return null;
}
/**
* Called when a commandMenuItem is clicked.  Updates the outputText with information about the menu item clicked.
* @param actionEvent
*/
public void menuItemListener(ActionEvent actionEvent) {
UIComponent component = actionEvent.getComponent();
if(component instanceof RichCommandMenuItem) {
RichCommandMenuItem cmi = (RichCommandMenuItem) component;
// Add the text of the item into the status message
StringBuilder s = new StringBuilder();
s.append("You clicked on \"").append(cmi.getText()).append("\".  <br><br>");
// If graph data is selected, add that too
Set<? extends GraphSelection> selectionSet = m_graph.getSelection();
if(!selectionSet.isEmpty()) {
// Write out the selection state
s.append("The current graph selection is: <br>");
s.append(SelectionSample.convertSelectionStateToString(selectionSet));
}
m_status = s.toString();
RequestContext.getCurrentInstance().addPartialTarget(m_outputFormatted);
}
}
}

前述の例のマネージドBeanは、例23-29に表示されるSelectionSampleクラスを呼び出します。

例23-29 カスタム・コンテキスト・メニューのSelectionSampleクラスのマネージドBean

import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import javax.faces.model.SelectItem;
import oracle.adf.view.faces.bi.component.graph.DataSelection;
import oracle.adf.view.faces.bi.component.graph.GraphSelection;
import oracle.adf.view.faces.bi.event.graph.SelectionEvent;
import oracle.adf.view.faces.bi.model.KeyMap;
public class SelectionSample {
public void selectionListener(SelectionEvent selectionEvent) {
StringBuilder eventInfo = new StringBuilder();
Set<? extends GraphSelection> selectionSet =
selectionEvent.getGraphSelection();
eventInfo.append(convertSelectionStateToString(selectionSet));
// Store on the selection string
m_selectionInfo = eventInfo.toString();
}
/**
* Returns selection state formatted with one selected data point per line.
* @param selectionSet
* @return
*/
public static String convertSelectionStateToString
(Set<? extends GraphSelection> selectionSet) {
StringBuilder selectionState = new StringBuilder();
for(GraphSelection selection: selectionSet) {
if(selection instanceof DataSelection) {
DataSelection ds = (DataSelection) selection;
Set seriesKeySet = ds.getSeriesKey().keySet();
for(Object key : seriesKeySet) {
selectionState.append(key).append(": ").
append(ds.getSeriesKey().get((String)key));
}
List<KeyMap> groupKeys = ds.getGroupKeys();
for(KeyMap groupKey : groupKeys) {
Set groupKeySet = groupKey.keySet();
for(Object key : groupKeySet) {
selectionState.append("; ").append(key).append(": ").
append(groupKey.get((String)key));
}
}
selectionState.append("<br>");
}
}
return selectionState.toString();
}
private String m_selectionInfo = "Select a marker to see information here.";
public String getSelectionInfo() {
return m_selectionInfo;
}
private String graphType = "bubbleGraph";
public String getGraphType() {
return graphType;
}
public void setGraphType(String type) {
graphType = type;
}
private List graphList;
public List getGraphList() {
graphList = new ArrayList();
SelectItem graph = new SelectItem("bubbleGraph", "Bubble Graph");
graphList.add(graph);
graph = new SelectItem("scatterGraph", "Scatter Graph");
graphList.add(graph);
return graphList;
}
}

24 ゲージ・コンポーネントの使用方法

この章では、ADFデータ視覚化コンポーネントのgaugeを使用し、簡単なUI優先開発を使用してゲージでデータを表示する方法について説明します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してゲージを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフおよびゲージ・コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 24.1項「ゲージ・コンポーネントについて」

- 24.2項「ゲージ・コンポーネントの使用方法」

- 24.3項「ゲージ表示要素の構成」

- 24.4項「ゲージ・スタイル要素の書式設定」

- 24.5項「ゲージの数値データ値の書式設定」

- 24.6項「ゲージの特殊効果およびアニメーションの追加」

- 24.7項「ゲージのカスタム形状の使用方法」

24.1 ゲージ・コンポーネントについて

ゲージは、売上高、在庫レベル、温度または速度など量を示すための計測器です。ゲージには通常1つのデータ値が表示され、多くの場合グラフより効果的です。ゲージでは、色を使用して許容範囲または非許容範囲などの状態情報を表示できます。たとえば、ゲージ値軸では、赤、黄、緑の色の範囲を示して、低、中、高の状態を表す場合があります。多くのデータ値を一目で比較する必要がある場合、表のセル内や、縦、横あるいはグリッドのレイアウトで、ゲージ・セットとして複数のゲージを表示することができます。

ベスト・プラクティスのヒント:

しきい値のテキスト値や現在値など、複数のデータ値が必要な場合は、リストや表コンポーネントの方がゲージより適していることがあります。

ゲージ・コンポーネントには、ダイアル、ステータス・メーター、垂直ステータス・メーターおよびLEDの4種類のゲージ・タイプがあります。どのゲージ・タイプでも、タイトル、下部ラベル、データ・ラベルおよび凡例を表示できます。

24.1.1 ゲージ・コンポーネントのユースケースおよび例

ゲージは通常、1つのデータ・ポイントを表示するために使用されます。ゲージ・コンポーネントでは、次のタイプのゲージがサポートされています。

- ダイアル: 構成可能な弧の値軸に沿ってメトリックを示します。これはデフォルトのゲージ・タイプです。ダイアル・ゲージは、単一のゲージ、しきい値付きのゲージ、またはダイアル・ゲージのセットとして表示できます。
図24-1に、初心者用スキー・ブーツの在庫レベルが許容範囲内にあることを示すしきい値付きダイアル・ゲージを示します。

図24-1 しきい値付きダイアル・ゲージ

- ステータス・メーター: 矩形の水平バーに沿ってタスクの進捗状況または測定値のレベルを示します。内側の矩形は、外側の矩形に表示された範囲に対する現在の測定値のレベルを示します。ステータス・メーター・ゲージは、単一のゲージ、しきい値付きゲージまたはステータス・メーター・ゲージのセットとして表示できます。
図24-2に、バニー・ブーツの在庫レベルを、ステータス・メーター・ゲージを使用して示します。

図24-2 しきい値付きステータス・メーター・ゲージ

- ステータス・メーター(垂直): 垂直の矩形のバーに沿ってタスクの進捗状況または測定値のレベルを示します。垂直ステータス・メーター・ゲージは、単一のゲージ、しきい値付きゲージまたはステータス・メーター・ゲージのセットとして表示できます。
図24-3に、バニー・ブーツの在庫レベルを、垂直ステータス・メーター・ゲージを使用して示します。

図24-3 しきい値付き垂直ステータス・メーター・ゲージ

- LED(発行ダイオード): キー・パフォーマンス・インジケータ(KPI)などの測定値をグラフィカルに表します。LEDゲージには、ステータスを示すために色を使用する円形または矩形、カラー・インジケータに加えて、よい(上向き)、普通(左または右向き)または悪い(下向き)の状態を示す三角形または矢印など、数種のグラフィックスが使用できます。LEDゲージは、ゲージ・セットとしても表示できます。
図24-4に、LEDバブル・インジケータを使用したバニー・ブーツの在庫レベルを示します。色を使用してステータスが示されています。

図24-4 LEDバブル・ゲージ

図24-5に、LED矢印を使用した同じ在庫レベルを示します。

図24-5 LED矢印ゲージ

すべてのゲージ・タイプは、ビルトイン・グリッド・レイアウトにゲージ・セットとして表示できます。関連アイテムのグループの個々の値を表示する場合、ゲージ・セットが便利です。図24-6に、3都市での業績測定値を比較するゲージ・セットを示します。

図24-6 都市間の業績を比較するゲージ・セット

水平ステータス・メーターとLEDゲージは、ユーザーがラベル、リンク、アイコンなどの関連情報とともに見て比較できる表セル内での表示に適しています。図24-7に、各国の人口密度を、2010年の最高人口とともに比較する表を示します。

図24-7 表に表示された水平ステータス・メーター・ゲージ

24.1.2 ゲージ・コンポーネントのエンド・ユーザー機能およびプレゼンテーション機能

ゲージをどのように使用し、どのようにカスタマイズできるかを理解するには、次の要素と機能について復習すると役に立ちます。

- 表示要素には、次のものがあります。

- ゲージおよびゲージ・セットの背景

- ゲージ・フレーム

- ダイアル・ゲージ描画エリア

- インジケータとインジケータ・バー

- ゲージの上部、下部およびメトリック・ラベル

- しきい値とラベル

- 凡例

- ティック・マークとティック・ラベル

- ツールチップ: ユーザーが描画エリア、インジケータまたはしきい値リージョンにカーソルを合せると、文脈に即した情報のツールチップが自動的に表示されます。図24-8に、ダイアル・ゲージのインジケータ・ツールチップを示します。

図24-8 ダイアル・ゲージのインジケータ・ツールチップ

24.1.3 ゲージ・コンポーネントの追加機能

ゲージ・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんゲージ・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。ゲージ・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、ゲージをリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: ユーザーが実行時にゲージの表示方法を変更できるようになっている場合、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: ゲージ・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- スキンおよびスタイル: アプリケーションに適用するADFを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)を使用してCSSスタイル・プロパティを直接適用することにより、ゲージ・コンポーネントの外観をカスタマイズできます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされたゲージを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフおよびゲージ・コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

24.2 ゲージ・コンポーネントの使用方法

ゲージでは、次の種類のデータ値を表します。

- メトリック:ゲージがプロットする値。この値は、「プロパティ」ウィンドウで「ゲージ・データ」属性カテゴリの静的データとして指定できます。データ・コントロールまたはgaugeタグのtabularData属性を使用して指定することもできます。これは、ゲージで唯一の必須データです。指定されるメトリック値の数は、ゲージ・セットに1つのゲージを表示するか、一連のゲージを表示するかに影響します。

- 最小および最大:ゲージの値軸で最小点と最大点を示すオプションの値。この値は、データ・コレクションからの動的データとして指定できます。これらは、gaugeタグの「プロパティ」ウィンドウで、「ゲージ・データ」属性カテゴリの静的データとしても指定できます。

- しきい値:データ・コレクションからの動的データとして指定可能なオプションの値で、ゲージの値軸で許容範囲を示します。「プロパティ」ウィンドウで、ゲージしきい値タグを使用して、これらの値を静的データとして指定することもできます。詳細は、24.3.1項「ゲージしきい値の構成方法」を参照してください。

24.2.1 ゲージの構成

gaugeコンポーネントのプロパティはゲージを作成するのに十分ですが、子コンポーネントまたはサポートされているファセットを追加し構成することで、ゲージまたはゲージ・セットの表示および動作をさらにカスタマイズできます。接頭辞dvt:は、各ゲージ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。ゲージの子コンポーネントとサポートされているファセットを次のエリアで構成できます。

- ゲージ表示要素:

- ゲージの背景(gaugeBackground)およびゲージ・セットの背景(gaugeSetBackground): ゲージまたはゲージ・セットの後ろの境界のあるエリア。

- ゲージ・フレーム(gaugeFrame): ダイアル・ゲージの描画エリアを囲む装飾的なフレームのことです。

- 描画エリア(gaugePlotArea): ゲージのメトリック値のグラフィカルな表現を示します。

- インジケータ(indicator): ダイアル・ゲージにプロットされた値を示し、通常、線または矢印の形をしています。

- インジケータ・バー(indicatorBar): ステータス・メーター・ゲージの内側の矩形。

- インジケータ・ベース(indicatorBase): ダイアル・ゲージの線形または針形のインジケータの円形ベース。

- ゲージ・ラベル:

- 上部ラベル(topLabel): ゲージの上または内側に表示されるゲージ・タイトルを示します。このラベルの上部ラベル・フレーム(upperLabelFrame)を構成して、境界の色と塗りつぶりの色を指定できます。このフレームを使用する場合は、デフォルトのタイトル・セパレータを無効にします。

- 下部ラベル(bottomLabel): ゲージの下または内側に表示されるオプションのラベルのことです。デフォルトでは、データ行のラベルを表示します。このラベルの下部ラベル・フレーム(lowerLabelFrame)を構成して、境界の色と塗りつぶりの色を指定できます。

- メトリック・ラベル(metricLabel): ゲージにテキストでプロットされるメトリックの値を示します。

- しきい値と凡例: しきい値セット(thresholdSet)を使用して、ゲージのメトリックのしきい値セクション(しきい値)を指定します。ゲージのしきい値はいくつでも作成できます。
凡例には、各しきい値の色と名前または範囲とともに、しきい値セットの説明が表示されます。凡例要素には、凡例エリア(gaugeLegendArea)、テキスト(gaugeLegendText)およびタイトル(gaugeLegendTitle)があります。

- ティック・マーク(tickMark): ゲージの値軸上のマークのことです。一定の間隔で最小値から最大値までを示し、しきい値も示します。ティック・マークにより、主増分(ティック・マーク・ラベル(tickLabel)を含む場合もある)または副増分を指定できます。

- コンテキスト・メニュー(bodyContextMenuファセット): このファセットを使用して、コンポーネント内の非選択可能オブジェクトを右クリックするとJSPまたはJSPXページに表示されるコンテキスト・メニューを含む1つのaf:popupコンポーネントをサポートします。コンテキスト・メニューを表示するには、af:popupにaf:menuが含まれている必要があります。Faceletページのファセットは複数のaf:popupコンポーネントをサポートしています。

- データ値: カテゴリおよび数値データ値を標準のADFコンバータにより書式設定します。詳細は、24.5項「ゲージの数値データ値の書式設定」を参照してください。

- 相互作用: 形状属性セット(shapeAttributesSet)を使用して、ゲージの子要素の動作プロパティを構成します。たとえば、ゲージの描画エリアのaltテキストは、ユーザーが実行時にそのエリアにマウスを移動したときにツールチップとして表示できます。詳細は、24.6.3項「ゲージへの相互作用の追加方法」を参照してください。

- カスタム形状: ゲージ用に事前に作成された一連のカスタム・スタイルを使用するか、customShapesPath属性を設定して出力用に使用されるベクトル・グラフィックス・ファイルを指定できます。詳細は、24.7項「ゲージのカスタム形状の使用方法」を参照してください。

- イメージ形式: ゲージでは、HTML5、FlashおよびPNGなどのイメージ形式がサポートされています。デフォルトでは、新しいアプリケーションのゲージはHTML5で表示されますが、デフォルトのイメージ形式を変更できます。アプリケーションでFlashを無効にしたり、クライアント・プラットフォームで動作をカスタマイズすることもできます。詳細は、24.2.5項「ゲージのイメージ形式に関する必知事項」を参照してください。

24.2.2 ページへのゲージの追加方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用してゲージをJSFページに追加します。ページにゲージ・コンポーネントをドラッグ・アンド・ドロップすると、「ゲージの作成」ダイアログに使用可能なゲージ・タイプのカテゴリが説明とともに表示され、ゲージの作成を視覚的に支援します。ゲージのタイトルおよび凡例のクイックスタート・レイアウトも指定できます。図24-9に、ダイアル・ゲージ・タイプが選択された「ゲージの作成」ダイアログを示します。

図24-9 ゲージの「ゲージの作成」ダイアログ

ダイアログを完了し、ページにゲージが追加された後、「プロパティ」ウィンドウを使用してデータ値を指定すること、およびゲージに追加の表示属性を構成することができます。

「プロパティ」ウィンドウで、プロパティ・フィールドにマウス・カーソルを合わせると表示されるアイコンをクリックすることで、プロパティの説明や編集オプションを表示できます。図24-10に、ゲージ・コンポーネントのvalue属性の「プロパティ」メニューを示します。

図24-10 ゲージ・コンポーネントのValue属性の「プロパティ」メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してゲージを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフおよびゲージ・コンポーネントの作成」の章を参照してください。

始める前に:

ゲージの属性やゲージの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにゲージを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「グラフとゲージ」パネルから「ゲージ」をページにドラッグ・アンド・ドロップして、「コンポーネント」ウィンドウで「ゲージの作成」ダイアログを開きます。

2. ダイアログを使用してゲージのカテゴリおよびタイプと、ゲージ・タイトル、凡例およびラベルの表示用クイック・スタート・レイアウトを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 「ゲージの作成」ダイアログで、「OK」をクリックしてページにゲージを追加します。

4. 「プロパティ」ウィンドウで、ゲージまたはゲージ・セットの属性を確認します。「コンポーネント・ヘルプ」ボタンを使用して、gaugeコンポーネントの完全なタグ・ドキュメントを表示します。

5. 「ゲージ・データ」セクションを開きます。次のフィールドの値を設定して、ゲージのデータ値を指定します。

- Value: 単一ゲージの場合は、EL式を使用してデータ・モデルを指定します。指定できるのは、データ・コントロールの1つの属性か、DataModelの1つのインスタンスです。または、メトリック数値をJava.lang.NumberオブジェクトまたはStringのいずれかとして設定します。

- TabularData: ゲージ・セットの場合、表形式のデータ・セットをJava.util.Listオブジェクトとして指定します。詳細は、24.2.4項「表形式のデータを使用したゲージの作成方法」を参照してください。

- MinValueおよびMaxValue: オプションで、ゲージ軸の最小値および最大値を設定します。指定しない場合、これらの値は自動的に設定されます。

6. 「外観」セクションを開きます。次のフィールドの値を設定して、表示属性を指定します。

- LedStyle: LEDゲージの形状を変更する場合は、ドロップダウン・リストを使用して、有効な値であるLS_DOT、LS_ARROW、LS_RECTANGLE、LS_TRIANGLEのいずれかを選択します。カスタム・イメージを指定する場合は、LS_CUSTOM値も使用できます。

- ThresholdDialStyle: ダイアル・ゲージのしきい値のデフォルト・スタイル(TDS_SEGMENTS)を変更する場合は、ドロップダウン・リストを使用して、有効な値のTDS_PIE_FILL、TDS_RING_FILLのいずれかを選択します。

- AngleExtent: ダイアル・ゲージで標準の220度の弧以外の角度でスイープする度数の範囲の指定に使用します。

- CustomShapesPath: カスタム形状定義ファイルのパスの指定に使用します。詳細は、24.7項「ゲージのカスタム形状の使用方法」を参照してください。

- ShortDesc: ゲージの説明を入力します。この説明は、スクリーン・リーダーのユーザーがアクセスします。

- AnimationOnDisplay、AnimationOnDataChange、AnimationDuration (アニメーション・サブセクション): これらの属性の1つ以上を使用して、ゲージのアニメーション効果を設定します。詳細は、24.6.4項「ゲージへのアニメーションの使用」を参照してください。

クライアントがサポートしている場合、ゲージはクライアントにHTML5イメージ形式で表示されます。ゲージのイメージ形式の詳細は、第24.2.5項「ゲージのイメージ形式に関する必知事項」を参照してください。

24.2.3 ページにゲージを追加する場合の処理

「コンポーネント」ウィンドウを使用してゲージ・コンポーネントをJSFページに挿入すると、ゲージのカスタマイズをサポートする子タグのセットが自動的に挿入されます。例24-1に、クイック・スタート・レイアウトを備えたダイアル・ゲージのJSFページに挿入されたコードを示します。このレイアウトは、図24-9の「ゲージの作成」ダイアログで選択したレイアウトです。

例24-1 ゲージのサンプル・コード

<dvt:gauge id="gauge1" gaugeType="DIAL">
<dvt:gaugeBackground>
<dvt:specialEffects/>
</dvt:gaugeBackground>
<dvt:gaugeFrame/>
<dvt:indicator/>
<dvt:indicatorBase/>
<dvt:gaugePlotArea/>
<dvt:tickLabel/>
<dvt:tickMark/>
<dvt:topLabel/>
<dvt:bottomLabel/>
<dvt:metricLabel position="LP_WITH_BOTTOM_LABEL"/>
</dvt:gauge>

24.2.4 表形式データを使用したゲージの作成方法

ゲージ・コンポーネントにデータのグリッドが使用される場合、ゲージ・セットが作成されます。ゲージ・コンポーネントのtabularData属性には、グリッドの作成やデータの移入にゲージで使用する値のリストを指定できます。表形式のデータを使用してゲージを作成するには、ゲージのマネージドBeanのメソッドにデータを格納し、ゲージ・コンポーネントのtabularData属性を使用してデータを参照する必要があります。マネージドBeanの作成と使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

tabularData属性でメトリック値のみを指定すると、グリッド内の各値は個別のゲージによって表されます。この場合、しきい値、最小値または最大値は、「プロパティ」ウィンドウを使用して指定する必要があります。

たとえば、図24-11の表には、Quota、Sales、Margin、CostsおよびUnitsの5つの列と、London、ParisおよびNew Yorkの3つの行があります。このデータから、各行に5つのゲージのあるゲージ・セット(図24-6のゲージ・セットと同様)が生成され、売上げなどの値を3都市で比較できます。

図24-11 年間実績の比較

マネージドBeanでは、表形式のデータのリストの構造は、ゲージに渡すデータ値ごとに3メンバーのObject配列で構成されます。各配列のメンバーは次のように編成される必要があります。

- 1つ目のメンバー(索引0)は、データ値のグリッドの列ラベルです。これは通常Stringです。

- 2つ目のメンバー(索引1)は、データ値のグリッドの行ラベルです。これは通常Stringです。

- 3つ目のメンバー(索引2)はデータ値で、通常Doubleです。

例24-2に、図24-11に表示された3都市の年間実績を比較するゲージに必要な表形式データのリストを作成するマネージドBeanメソッド内のコードを示します。

例24-2 年間実績の表形式データのリストを作成するためのマネージドBeanメソッド

public List getGaugeData()
{
ArrayList list = new ArrayList();
String[] rowLabels  = new String[] {"London", "Paris", "New York"};
String[] colLabels  = new String[] {"Quota", "Sales", "Margin", "Costs", "Units"};
double [] [] values = new double[][]{
{20, 90, 135},
{50, 20, 80},
{130, 140, 150},
{70, 80, 90},
{110, 120, 130}
};
for (int c = 0; c < colLabels.length; c++)
{
for (int r = 0; r < rowLabels.length; r++)
{
list.add (new Object [] {colLabels[c], rowLabels[r],
new Double (values [c][r])});
}
}
return list;
}

メトリック値としきい値、最小値および最大値を指定するには、データ仕様を使用して、ゲージのvalue属性でデータの列または行を設定します。

たとえば、図24-12のデータでは、2都市のメトリック値と最小値、最大値およびしきい値が提供されています。このデータにより、希望する仕様によって販売実績を比較する2つのゲージのセットが作成されます。

図24-12 仕様による販売実績の比較

図24-12に表示されている2都市の販売実績を仕様により比較するゲージには、表形式データのリストが必要です。例24-3に、この表形式データのリストを作成するマネージドBeanメソッド内のコードを示します。

例24-3 販売実績の表形式データのリストを作成するためのマネージドBeanメソッド

public GaugeDataModel getGaugeData()
{
// Set up values for data source
Object[] colLabels = { "Sales", "Min", "Max", "Quota", "Target" };
Object[] rowLabels = { "Boston", "Chicago" };
Double[][] values = { {40.0, 60.0}, {0.0,0.0}, {100.0,80.0}, {30.0,35.0}, {50.0,70.0} };
LocalXMLDataSource dataSource =
new LocalXMLDataSource(colLabels, rowLabels, values);
// Set up values for data specification
DataSpecification dataSpec = new DataSpecification();
dataSpec.setMetric("Sales");
dataSpec.setMinimum ("Min");
dataSpec.setMaximum ("Max");
ArrayList threshdata = new ArrayList ();
threshdata.add ("Quota");
threshdata.add ("Target");
dataSpec.setThresholds(threshdata);
return new GaugeDataModel(dataSource, dataSpec);
}

図24-13に、図24-12のメソッドをダイアル・ゲージ・セットに追加した場合にページでレンダリングされるゲージ・セットを示します。

図24-13 データ仕様を使用して販売実績を比較するゲージ・セット

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージ・セットが存在している必要があります。ない場合は、この章の指示に従ってゲージ・セットを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

マネージドBeanからの表形式データを使用してゲージ・セットを作成する手順:

1. 表形式データを作成するメソッドをゲージのマネージドBeanに追加します。詳細なヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、「ゲージ・データ」セクションを展開します。

4. TabularDataまたはValue属性のドロップダウン・メニューから、「式ビルダー」を選択します。

5. マネージドBeanノードを見つけ、展開します。

6. 表形式データのリストを作成するメソッドを選択し、「OK」をクリックします。
式が作成されます。

たとえば、マネージドBeanの名前がsampleGaugeで、表形式データのリストを作成するメソッドの名前がgetGaugeDataの場合、gaugeコンポーネントのtabularData属性の値として#{sampleGauge.gaugeData}というコードが式ビルダーで生成されます。

7. 「プロパティ」ウィンドウを使用して、ゲージの目的のプロパティを構成します。
たとえば、例24-2のサンプル・メソッドを使用して、各行に5つのゲージを表示するゲージ・セットを作成した場合、「共通」セクションのGaugeSetColumnCountを5に設定します。

24.2.5 ゲージのイメージ形式に関する必知事項

ゲージでは、HTML5、FlashおよびPNGなどのイメージ形式がサポートされています。使用されるイメージ形式は、アプリケーションの設定およびクライアント環境によって異なります。

次のパラメータを設定または変更することで、特定のイメージ形式を使用するようにアプリケーションを構成できます。

- oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT
このコンテキスト初期化パラメータは、新しいすべてのアプリケーションのweb.xmlに自動的に追加され、デフォルトではHTML5に設定されます。詳細は、A.2.3.28項「グラフとゲージのイメージ形式」を参照してください。

- スキン・スタイル
Skyrosスキンを使用している場合、ゲージはHTML5イメージ形式で表示されます。新しいアプリケーションでは、デフォルトでこのスキンが使用されます。スキニングおよびスタイルの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- flash-player-usage
adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定すれば、アプリケーション全体にわたってFlashコンテンツの使用を無効にできます。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

指定したイメージ形式がクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。たとえば、クライアントがHTML5をサポートしていない場合、アプリケーションでは次が使用されます。

- Flash (Flash Playerが使用可能な場合)。

- Portable Network Graphics (PNG)出力形式。PNG出力形式は、ゲージの印刷時にも使用されます。静的レンダリングは、PNG出力形式使用時には完全にサポートされますが、次のような一部のインタラクティブ機能は使用できません。

- アニメーション

- コンテキスト・メニュー

- ポップアップのサポート

- 相互作用力

ゲージ用のすべてのイメージ形式で、双方向ロケールがサポートされます。双方向文字、ラベル位置、凡例表示、ゲージ・セット表示などのテキスト文字列がサポートされます。

24.2.6 表へのゲージの追加方法

表のセル内にゲージを表示して、ユーザーがゲージを関連情報と一緒に見て比較できるようにすることができます。ADF tableコンポーネントの直下の子は、columnコンポーネントであることが必要です。表示されるそれぞれの列コンポーネントは、表の個別の列として表示されます。列コンポーネントには、コンテンツやイメージの表示、またはその他の機能の提供に使用されるコンポーネントが含まれます。

各列の子コンポーネントは、その列の各行のデータを表示します。列では、子コンポーネントは行ごとには作成されませんが、表では各行のレンダリングにスタンプ設定機能が使用されます。各子には、行ごとに一度スタンプが設定され、これがすべての行に対して繰り返されます。各行にスタンプが設定されると、現在行のデータが、EL式を使用して特定可能なプロパティにコピーされます。このプロパティに使用する名前を、表のvarプロパティを使用して指定します。表のレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

例24-4に、図24-7に示されているOracle ADF表コンポーネントでゲージを表示するためのサンプル・コードを示します。この例では、表のvarプロパティがtestvarであり、表の値はgaugeDataという名前のマネージドBeanに格納されます。ゲージのメトリックは、valueフィールドで#{testvar.density}に設定されています。

例24-4 表の列にスタンプ設定されたゲージ・コンポーネント

<af:table summary="table" value="#{gaugeData.gaugeTableData}" var="testvar"
rowBandingInterval="0" id="t1" columnStretching="last"
inlineStyle="height:400px" styleClass="AFStretchWidth">
<af:column rowHeader="true" sortable="false" headerText="Country"
align="center" id="c1" width="120"
inlineStyle="font-weight:bold; font-size: 12px;">
<af:outputText value="#{testvar.name}" id="ot1"/>
</af:column>
<af:column sortable="true" headerText="Density (1/km^2)"
align="center" id="c2" width="300"
sortProperty="density">
<dvt:gauge shortDesc="Gauge" id="gauge77" gaugeType="STATUSMETER"
dynamicResize="DYNAMIC_SIZE"
value="#{testvar.density}"
inlineStyle="height:22px" styleClass="AFStretchWidth"
minValue="0.0" maxValue="1200.0">
<dvt:indicatorBar/>
<dvt:thresholdSet>
<dvt:threshold fillColor="#00aa00" thresholdMaxValue="300"/>
<dvt:threshold fillColor="#ffcc00" thresholdMaxValue="700"/>
<dvt:threshold fillColor="#cc2255"/>
</dvt:thresholdSet>
<dvt:topLabel position="LP_NONE"/>
<dvt:bottomLabel position="LP_NONE"/>
<dvt:metricLabel position="LP_NONE"/>
</dvt:gauge>
</af:column>
<af:column sortable="false" width="100" inlineStyle="font-size: 12px;"
headerText="Population" align="center" id="c3">
<af:outputText value="#{testvar.population}" id="ot3">
<af:convertNumber type="number" pattern="#,##0"/>
</af:outputText>
</af:column>
<af:column sortable="false" width="100" inlineStyle="font-size: 12px;"
headerText="Percent with world population" align="center" id="c4">
<af:outputText value="#{testvar.percent}" id="ot4">
<af:convertNumber type="percent" pattern="#.00%"/>
</af:outputText>
</af:column>
</af:table>

例24-5に、gaugeDataマネージドBeanのサンプル・コードを示します。この例では、クラスはGaugeTableDataという名前です。

例24-5 表のゲージのマネージドBeanコードの例

public class GaugeTableData {
private List<CountryData> _gaugeTableData;
public GaugeTableData() {
ArrayList<CountryData> list = new ArrayList<CountryData>(11);
list.add(new CountryData("China", 1338134000,139.434));
list.add(new CountryData("India", 1182276000, 359.654));
list.add(new CountryData("USA", 309527000,32.145));
list.add(new CountryData("Indonesia", 231369500,121.481));
list.add(new CountryData("Brazil", 193087500, 22.676));
list.add(new CountryData("Pakistan", 169784000, 211.19));
list.add(new CountryData("Bangladesh", 162221000,1126.55));
list.add(new CountryData("Nigeria", 154729000, 167.498));
list.add(new CountryData("Russia", 141927000,8.301));
list.add(new CountryData("Japan", 127380000,337.097));
list.add(new CountryData("Mexico", 107550500,54.923));
_gaugeTableData = list;
}
public List<CountryData> getGaugeTableData(){
return _gaugeTableData;
}
public static class CountryData {
private String _name;
private long _population;
private double _percent;
private double _density;
private static long worldPopulation = 6697254000L;
public CountryData(String name, int population, double density) {
_name = name;
_population = population;
_density = density;
_percent = (double)population / (double)worldPopulation;
}
public String getName() {
return _name;
}
public double getPercent() {
return _percent;
}
public long getPopulation() {
return _population;
}
public double getDensity() {
return _density;
}
}
}

表のセルでゲージを構成する場合、次のガイドラインを使用して、操作性を改善します。

- 水平ステータス・メーター、ダイアルまたはLEDゲージを使用します。垂直ステータス・メーターの使用は避けます。これは、垂直ステータス・メーターに対応するために、表の行の縦の長さが非常に長くなるためです。

- 読みやすさを維持しながらも、ゲージはできるだけ小さくします。

- スペースを最大限に利用するには、ゲージ・タイトルや下部ラベルを使用するかわりに、表の列や行のヘッダーを使用してゲージを説明します。

- 1列または1行につき1タイプのゲージのみを使用し、同じ軸値としきい値を使用します。

- 列には水平のステータス・メーターを、行または列にはダイアル・ゲージおよびLEDゲージを表示します。

- 表示するゲージが多すぎるとユーザーはスクロールしないと全部を見られなくなるので避けます。

アプリケーションでFusionテクノロジ・スタックを使用する場合、データ・コントロールを使用してデータ・バインドされたADF表を作成すること、および表作成中にゲージを追加することができます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフおよびゲージ・コンポーネントの作成」の章を参照してください。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

次のタスクを実行する必要があります。

1. 表およびゲージのデータを含むマネージドBeanを作成します。
図24-7に表示されている表を複製するには、gaugeDataという名前のマネージドBeanを作成し、例24-5のコードを追加します。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. ADF表を作成します。
例24-4に、図24-7の表を表示するために使用するコードを示します。デフォルトでは、ゲージ・コンポーネントは、表作成中にオプションとしてリストされません。ゲージを有効なコンポーネントとして含む列を構成します。表にゲージを追加する場合、コンポーネントを削除します。

表作成のヘルプが必要な場合は、12.3.4項「ページへの表の表示方法」を参照してください。

表にゲージを追加する手順:

1. 「構造」ウィンドウで、「af:table」ノードを展開します。

2. ゲージに置き換えるコンポーネントを右クリックし、「削除」を選択します。
たとえば、af:outputTextを使用するように表の列を構成していた場合、それを右クリックし、「削除」を選択します。

3. ゲージを含める列を右クリックし、「列の中に挿入」→「ADFデータ視覚化」→「ゲージ」を選択します。

4. 「ゲージの作成」ダイアログで、ゲージ・タイプおよびラベルを含まないクイック・スタート・レイアウトを選択します。
図24-14に、図24-7に表示されているゲージの「ゲージの作成」ダイアログを示します。

図24-14 表内の水平ステータス・メーターの「ゲージの作成」ダイアログ

5. 「OK」をクリックして表にゲージを追加します。

6. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

7. 「プロパティ」ウィンドウの「値」フィールドに、ゲージに表示するメトリック値を入力します。
たとえば、図24-7のゲージで使用されている値にゲージを設定するには、#{testvar.density}と入力します。

8. しきい値を含むクイック・スタート・レイアウトを選択した場合、「プロパティ」ウィンドウで、各しきい値の値を入力します。
しきい値の構成のヘルプが必要な場合は、24.3.1項「ゲージしきい値の構成方法」を参照してください。

9. 必要に応じてゲージ・スタイル要素を書式設定します。
たとえば、例24-4のサンプル・コードでは、高さとサイズの値が以下に設定されます。

inlineStyle="height:22px" styleClass="AFStretchWidth"

ゲージ・スタイル要素の構成のヘルプが必要な場合は、24.4項「ゲージ・スタイル要素の書式設定」を参照してください。

24.3 ゲージ表示要素の構成

しきい値、ラベル、インジケータ、ティック・マークなど、ゲージの表示要素をカスタマイズできます。

24.3.1 ゲージしきい値の構成方法

しきい値は、特定の範囲の値を強調表示するゲージの数値データ値です。しきい値はゲージの最小値と最大値の間の値である必要があります。しきい値で識別された範囲は、他の範囲と異なる色で塗りつぶされます。

ゲージがデータ・バインドされている場合、ゲージのデータ・コレクションでしきい値の動的値を指定できます。しきい値の動的値の使用の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたグラフおよびゲージ・コンポーネントの作成」の章を参照してください。

ゲージを作成したら、ゲージ内にthreshold子コンポーネントをいくつでもラップできるthresholdSet子コンポーネントを構成することで、静的しきい値も指定できます。しきい値がデータ・コレクションとthresholdコンポーネントの両方で指定された場合、ゲージはthresholdコンポーネントの値を受け入れます。しきい値セットに凡例を追加して、ユーザーにしきい値の定義を視覚的に示すこともできます。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

「ゲージの作成」ダイアログで、しきい値付きのゲージ・タイプを使用してゲージを作成する場合、dvt:thresholdSetコンポーネントとdvt:thresholdコンポーネントの子が、「構造」ウィンドウでdvt:gaugeコンポーネントに自動的に追加されます。

凡例を含むクイック・スタート・レイアウトを選択した場合、dvt:gaugeLegendTitleおよびdvt:gaugeLegendAreaも、「構造」ウィンドウでdvt:gaugeコンポーネントに自動的に追加されます。

静的しきい値をゲージに追加する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→「しきい値セット」を選択します。

2. 「dvt:thresholdSet」コンポーネントを右クリックし、「しきい値セットの中に挿入」→「しきい値」を選択します。

3. 「プロパティ」ウィンドウで次の属性を設定します。

- ThresholdMaxValue: 構成中のしきい値セクションの最大値を指定します。値として整数またはEL式を使用できます。

注意:

最終しきい値の場合、最終しきい値のThresholdMaxValue属性に入力した値に関係なく、ゲージの最大値がしきい値の最大値として使用されます。

- FillColorおよびBorderColor: オプションで、構成中のしきい値セクションに塗りつぶしの色と枠線の色をそれぞれRGB値で指定します。色を不透明から透明に変更することもできます。詳細は、24.4.2項「ゲージ要素の透明度の指定」を参照してください。

- Text: オプションで、このしきい値を識別するために凡例で表示されるテキストを指定します。テキストをテキスト・リソースにバインドすることもできます。テキストの書式設定の詳細は、24.4.3項「ゲージ・テキストの書式設定方法」を参照してください。テキスト・リソースの詳細は、24.4.4項「ゲージのテキスト・リソースの指定方法」を参照してください。

4. ステップ2とステップ3を繰り返して、ゲージの各しきい値を最小値から最大値まで作成します。

注意:

ゲージには任意の数のしきい値を追加できます。ただし、矢印ゲージや三角形LEDゲージは、それらが指し示す3つの方向のみのしきい値をサポートします。

オプションの凡例をゲージのしきい値セットに追加する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→「凡例エリア」を選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- 位置: ゲージを基準とした凡例の位置を指定します。
デフォルトでは、凡例の位置はLAP_BOTTOMに設定され、凡例はゲージの下に表示されます。凡例をゲージの左、右または上に表示するには、LAP_LEFT、LAP_RIGHTまたはLAP_TOPをそれぞれ使用します。

- BorderColorおよびFillColor: オプションで、凡例の境界の色と塗りつぶりの色を設定します。
16進表記でRGB値を指定するか(たとえば、#000000)、属性のドロップダウン・メニューから「編集」を選択して、「境界プロパティの編集」ダイアログで色を設定します。

3. 凡例にタイトルを追加する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→「凡例タイトル」を選択します。

2. 「dvt:gaugeLegendTitle」コンポーネントを右クリックし、「プロパティに移動」を選択します。

3. 「テキスト」フィールドに凡例のタイトルを入力します。

4. 凡例テキストを構成する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→「凡例テキスト」を選択します。

2. 「dvt:gaugeLegendText」コンポーネントを右クリックし、「プロパティに移動」を選択します。

3. MinLengthフィールドに、表示するテキストの最小長を指定します。使用可能なスペースにテキストを収めるためにテキストを切り捨てる必要がある場合、この長さに切り捨てられます。

4. NumberTypeフィールドで、属性のドロップダウン・メニューを使用して、凡例の数値タイプをNT_PERCENT(デフォルト)またはNT_NUMBERに設定します。

注意:

minLengthを定義するには、またはデフォルトのnumberTypeをNT_NUMBERに変更するには、gaugeLegendTextコンポーネントのみ必要です。

24.3.2 ゲージ・ラベルのカスタマイズ方法

デフォルトでは、ゲージに、子コンポーネントmetricLabel、topLabelおよびbottomLabelを使用して、メトリック・ラベルとオプションの上部ラベルおよび下部ラベルが表示されます。各ラベルの表示および配置のカスタマイズや、オプションの上部および下部ゲージ・ラベルのフレームの塗りつぶしや枠線の色の制御ができます。

上部または下部ラベルで表されるカテゴリ・データ値も、attributeFormatタグとADF Facesコンバータ・タグを使用して、パーセントの書式設定、数値の位取り、小数部の桁の制御、記号の配置などのカスタマイズができます。詳細は、24.5.1項「ゲージの数値データ値の書式設定方法」を参照してください。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、ゲージの子ラベル・コンポーネントがgaugeコンポーネントに自動的に追加されます。各ゲージ・ラベルのデフォルトの位置(ある場合)は、「ゲージの作成」ダイアログでのクイック・スタート・レイアウト・オプションの選択に基づいて、コンポーネントのposition属性で指定されます。

ゲージ・ラベルをカスタマイズする手順:

1. 構造ウィンドウで、構成するゲージ・ラベル・コンポーネント(dvt:metricLabel、dvt:topLabelまたはdvt:bottomLabel)を選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- Position: ゲージ・ラベルの位置(ある場合)の指定に使用します。有効な値は、次のとおりです。

- LP_NONE: ラベルは表示されません。

- LP_INSIDE_GAUGE: ラベルはゲージの描画エリア内に表示されます。ラベルはゲージの水平方向に中央揃えされます。この値に設定すると、上部および下部ラベルは描画エリア内で垂直方向にも中央揃えされます。これは、LEDゲージに適した選択です。

- LP_INSIDE_GAUGE_RIGHTおよびLP_INSIDE_GAUGE_LEFT: メトリック・ラベルは、描画エリアの右または左に表示されます。

- LP_ABOVE_GAUGE: 上部ラベルのデフォルト値です。ゲージの上にラベルを表示します。

- LP_BELOW_GAUGE: 下部ラベルのデフォルト値です。ゲージの下にラベルを表示します。下部ラベルとメトリック・ラベルの両方の位置をこの値に設定した場合、どちらのラベルもゲージの下に表示されます。ただし、下位ラベルはメトリック・ラベルの上に表示されます。

- LP_WITH_BOTTOM_LABEL: メトリック・ラベルのデフォルト値です。ラベルを下部ラベルの横に表示します。

- Text: 上部または下部ラベルに表示されるテキスト。属性メニューで、表示するテキストを入力するか、ダイアログで「テキスト・リソースの選択」を選択して、テキストをアプリケーション・テキスト・リソースに関連付けます。詳細は、24.4.4項「ゲージのテキスト・リソースの指定方法」を参照してください。

- NumberType、ScalingおよびAutoPrecision: メトリック・ラベルに対してのみ使用可能です。これらの属性を使用して、ゲージでの数値データ値の表示を構成します。詳細は、24.5.2項「自動位取りおよび精度に関する必知事項」を参照してください。

3. ゲージ・ラベルで使用するテキスト・フォントを構成する場合は、次のようにします。

1. 「構造」ウィンドウで、構成するゲージの子ラベル・コンポーネント(dvt:metricLabel、dvt:topLabelまたはdvt:bottomLabel)を右クリックし、「ラベルの中に挿入」→「ADFデータ視覚化」→「フォント」を選択します。

2. 「dvt:gaugeFont」ノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、フォントの属性を設定します。詳細は、24.4.3項「ゲージ・テキストの書式設定方法」を参照してください。

4. 上部または下部ゲージ・ラベルの周りのフレームを構成する場合は、次のようにします。

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「上のラベル・フレーム」または「下のラベル・フレーム」と選択します。

2. 「dvt:upperLabelFrame」または「dvt:lowerLabelFrame」を右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、構成するラベル・フレームのFillColorおよびBorderColor属性にRGB値を指定します。色を不透明から透明に変更することもできます。詳細は、24.4.2項「ゲージ要素の透明度の指定」を参照してください。

24.3.3 ゲージ・インジケータおよびティック・マークのカスタマイズ方法

ゲージでは、グラフィックを使用して正確なゲージ値を示します。デフォルトでは、ゲージに子コンポーネントindicatorを使用してダイアル・ゲージの線が表示され、子コンポーネントindicatorBarを使用してステータス・メーターまたは垂直ステータス・メーター・ゲージ内にバーが表示されます。子コンポーネントindicatorBaseは、ダイアル・ゲージのすべてのインジケータの円形ベースの塗りつぶしプロパティを設定するために使用されます。ゲージ・インジケータの外観はカスタマイズできます。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、ゲージの子インジケータ・コンポーネントが、「ゲージの作成」ダイアログで選択したゲージ・タイプに基づき、gaugeコンポーネントに自動的に追加されます。LEDゲージにはインジケータはありません。

ゲージ・インジケータの外観をカスタマイズする手順:

- ダイアル・ゲージ・インジケータの場合は、次のようにします。

1. 構造ウィンドウでdvt:indicatorノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- Type: インジケータの種類(線(デフォルト)、塗りつぶしまたは針)を指定します。

- BorderColor: インジケータの枠の色を指定します。

- FillColor: インジケータの塗りつぶしの色を指定します。

- UseThresholdFillColor: インジケータが指すしきい値領域の色が、インジケータの指定した色をオーバーライドするかどうかを指定します。

3. 「構造」ウィンドウで「dvt:indicatorBase」を右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで次の属性を設定します。

- レンダリング済: インジケータ・ベースが表示されるかどうかを示します。デフォルト値はtrueです。

- BorderColor: インジケータの枠の色を指定します。

- FillColor: インジケータの塗りつぶしの色を指定します。

- ステータス・メーターおよび垂直ステータス・メーター・ゲージの場合は、次のようにします。

1. 構造ウィンドウで「dvt:indicatorBar」コンポーネントを選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- BorderColor: インジケータの枠の色を指定します。

- FillColor: インジケータの塗りつぶしの色を指定します。

注意:

インジケータ・バーが指すしきい値領域の色がインジケータの指定した色をオーバーライドするように指定する場合、ゲージにindicatorコンポーネントを追加し、そのUseThresholdFillColor属性をtrueに設定します。

ティック・マークは、ダイアル、ステータス・メーターおよび垂直ステータス・メーター・ゲージのゲージ値軸に沿って表示される増分マークです。LEDゲージにはティック・マークはありません。デフォルトでは、主および副ティック・マークの表示、スペース、色を指定するゲージの子のtickMarkコンポーネントを使用して、ゲージにティック・マークが表示されます。

ゲージの子のtickLabelコンポーネントでは、主ティック・ラベルを指定し、ラベルの位置(ゲージの内側か外側か)とティック・ラベルに表示される数値の書式を指定します。副ティック・マークにはラベルは付けられません。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、ゲージの子のティック・マークおよびティック・マーク・ラベル・コンポーネントが、「ゲージの作成」ダイアログでの選択に基づき、gaugeコンポーネントに自動的に追加されます。LEDゲージにはティック・マークはありません。

ゲージのティック・マークとティック・ラベルをカスタマイズする手順:

1. ゲージのティック・マークをカスタマイズするには、「構造」ウィンドウで「dvt:tickMark」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、次の属性に値を設定します。

- MajorIncrementおよびMinorIncrement: 2つの主ティック・マーカーおよび2つの副ティック・マーカー間の距離をそれぞれ設定します。どちらかの属性の値がゼロ未満の場合、ティック・マークは表示されません。

- MajorTickColorおよびMinorTickColor: 主ティック・マークおよび副ティック・マークの16進数カラーをそれぞれ設定します。

- Content:ゲージ・セット内のどこにティック・マークを表示するかを指定します。有効値は、スペースまたはカンマで区切られた次の値の任意の組合せです。

- TC_INCREMENTS: 増分ごとのティック・マークを表示します。

- TC_MAJOR_TICK: 最小値、最大値および増分値のティック・マークを表示します。

- TC_MIN_MAX: 最小値および最大値のティック・マークを表示します。

- TC_METRIC: 実際のメトリック値のティック・マークを表示します。

- TC_NONE: ティック・マークを表示しません。

- TC_THRESHOLD: しきい値のティック・マークを表示します。

Contentに値を指定しない場合、ティック・マーク表示はデフォルトでTC_MIN_MAX TC_INCREMENTSに設定され、最小値、増分値および最大値に対してティック・マークが表示されます。

3. ゲージのティック・ラベルをカスタマイズするには、「構造」ウィンドウで「dvt:tickLabel」ノードを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、次の属性に値を設定します。

- Position: デフォルトで、ダイアル・ゲージにはゲージがゲージ・フレーム内に完全に含まれる場合に見やすくするため、内側のティック・ラベルが表示されます。ティック・ラベルは描画エリア内にあるため、ティック・ラベルの長さはこの領域に合うように制限される必要があります。この属性の値をデフォルトのTLP_INTERIORからTLP_EXTERIORに設定することで、外側のラベルを使用するようにゲージをカスタマイズできます。

- Content: ゲージのどのティック・マークでラベルを使用するかを指定します。有効値は、スペースまたはカンマで区切られた次の値の任意の組合せです。

- TC_INCREMENTS: 増分ごとのティック・ラベルを表示します。

- TC_MAJOR_TICK: 最小値、最大値および増分値のティック・ラベルを表示します。

- TC_MIN_MAX: 最小値および最大値のティック・ラベルを表示します。

- TC_METRIC: 実際のメトリック値のティック・ラベルを表示します。

- TC_NONE: ティック・ラベルを表示しません。

- TC_THRESHOLD: しきい値のティック・ラベルを表示します。

Contentに値を指定しない場合、ティック・ラベル表示はデフォルトでTC_MAJOR_TICKに設定され、最小値、増分値および最大値に対してティック・ラベルが表示されます。

- NumberType、ScalingおよびAutoPrecision: メトリックおよびティック・ラベルに対してのみ使用可能です。これらの属性を使用して、ゲージでの数値データ値の表示を構成します。詳細は、24.5.1項「ゲージの数値データ値の書式設定方法」を参照してください。

24.4 ゲージ・スタイル要素の書式設定

初期サイズまたはゲージを変更するためにゲージのスタイルをカスタマイズしたり、ゲージの表示領域にぴったり合うように動的サイズ変更を指定したり、スタイル要素を適用したりできます。テキストの書式設定およびテキスト・リソース、ゲージ内の透明度も使用できます。

24.4.1 ゲージ・サイズの変更方法およびCSSスタイルの適用方法

ゲージは、200 X 200ピクセルのデフォルト・サイズで表示されます。ゲージのサイズをカスタマイズしたり、様々なブラウザ・ウィンドウ・サイズに領域がぴったり合うように、動的サイズ変更を指定したりできます。水平または垂直に制限された領域(Webページのサイドバーなど)にゲージが表示される場合、ゲージは小さいイメージ・サイズで表示されます。機能は揃っていますが、イメージの小さい簡易表示になります。

ゲージの幅と高さはカスタマイズでき、コンテナのサイズ変更に基づいて動的にサイズ変更することができます。ゲージのこれらの2つの側面は、ともにゲージのinlineStyle属性を使用するという点で関連性があります。

active、focus、hover、linkおよびvisitedなどのCSSスタイルを適用して、ゲージに使用できます。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージのサイズを指定する手順:

1. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「スタイル」セクションを展開します。「InlineStyle」属性でゲージの初期サイズを指定します。ゲージの動的サイズ変更を指定しない場合、初期サイズが、ゲージの唯一の表示サイズです。たとえば、次のようになります。

width:200px;height:200px

ゲージの動的サイズ変更を指定する場合、固定数のピクセル、または幅と高さの両方の相対的パーセントを入力できます。たとえば、コンテナの50%の幅で200ピクセルの高さのゲージを作成するには、InlineStyle属性に次のように設定します。

width:50%;height:200px

ベスト・プラクティスのヒント:

inlineStyle属性に100%の幅を指定するかわりに、styleClass属性をAFStretchWidthに設定します。

3. ゲージに動的サイズ変更を指定する場合、「動作」セクションを開きます。DynamicResize属性のドロップダウン・リストから、「DYNAMIC_SIZE」を選択します。

ゲージにCSSスタイルを適用する手順:

1. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「スタイル」セクションを展開し、StyleClassフィールドにスタイル・クラスの名前を入力します。
CSSスタイルの適用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

24.4.2 ゲージ要素の透明度の指定

ゲージの様々な要素がデフォルトの不透明な色のかわりに透明な色を表示するように、それらの要素に関連するゲージの子コンポーネントでborderColor属性およびfillColor属性を設定することで指定できます。これらの色プロパティには、6桁または8桁のRGB16進数値を指定できます。8桁値を使用する場合、最初の2桁が透明度を表します。たとえば、00FFFFFFの値を使用して透明度を設定できます。

borderColor属性またはfillColor属性をサポートするゲージの子コンポーネントならば、透明に設定できます。透明度をサポートするゲージの子コンポーネントの例は、次のとおりです。

- gaugeBackground

- gaugeFrame

- gaugePlotArea

- gaugeLegendArea

24.4.3 ゲージ・テキストの書式設定方法

ゲージ内のタイトルやラベルを表すゲージの子コンポーネントのいずれに対しても、gaugeFontコンポーネントを子として使用して、ゲージ内のテキストの書式を設定できます。

- bottomLabel

- metricLabel

- gaugeLegendText

- gaugeLegendTitle

- tickLabel

- topLabel

gaugeFontコンポーネントの属性により、ゲージの子要素に対して次のフォント属性を指定できます。

- name: フォント名(San Serifなど)を指定します。

- size: フォント・サイズをピクセル単位で(11など)指定します。

- color: フォントの色を指定します。この色プロパティには、6桁または8桁のRGB16進数値を指定できます。8桁値を使用する場合、最初の2桁が透明度を表します。たとえば、00FFFFFFの値を使用して透明度を設定できます。

- bold: フォントが太字かどうかを指定します。デフォルト値はFALSEです。

- italic: テキストがイタリックかどうかを指定します。デフォルト値はFALSEです。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、タイトルまたはラベルのゲージの子コンポーネントが、「ゲージの作成」ダイアログでの選択に基づき、gaugeコンポーネントに自動的に追加されます。

ゲージ・タイトルまたはラベル・コンポーネントのテキスト・フォントを指定する手順:

1. 「構造」ウィンドウで、タイトルまたはラベルのゲージの子コンポーネントを右クリックし、「タイトルの中に挿入」または「ラベルの中に挿入」→「フォント」を選択します。
たとえば、ゲージのメトリック・ラベルのテキスト・フォントを指定するには、「メトリック・ラベルの中に挿入」→「フォント」を選択します。そのコンポーネントが使用できない場合は、「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→ゲージの子のタイトルまたはラベル・コンポーネントを選択します。

2. 「dvt:gaugeFont」ノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、1つ以上のdvt:gaugeFontコンポーネント属性に値を設定します。「ヘルプ」をクリックするか、[F1]を押すと、dvt:gaugeFontコンポーネントの完全なタグ・ドキュメントが表示されます。

カスケード・スタイル・シート(CSS)を使用してスキンを作成し、アプリケーションでそのスキンを使用するように構成することにより、アプリケーション内のすべてのページにわたり、ゲージ・コンポーネントのフォント属性も設定できます。ゲージ・コンポーネントで使用フォントを定義するスキンを適用することで、アプリケーション内のページは、CSSファイルの変更で簡単に変更できる一貫したスタイルで、より小さく整理されたものになります。詳細は、24.4.5項「スキンを使用してゲージ・スタイルをグローバルに設定する方法」を参照してください。

24.4.4 ゲージのテキスト・リソースの指定方法

JDeveloperは、抽象クラスjava.util.ResourceBundleを使用してロケール固有のリソースを提供し、データ視覚化コンポーネントをローカライズしやすいようにサポートします。ゲージでタイトルおよびラベルを表すそれらのゲージの子コンポーネントに対して、アプリケーション・リソース・バンドルで参照されるテキスト・リソースを関連付けることができます。詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージ・タイトルまたはラベル・コンポーネントのテキスト・リソースを指定する手順:

1. 「構造」ウィンドウで、ゲージの子ラベルまたはタイトル・コンポーネントを選択し、「プロパティに移動」を選択します。
たとえば、ゲージの上部ラベルのプロパティにアクセスするには、「dvt:topLabel」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウのtext属性のメニューで、「テキスト・リソースの選択」を選択します。

3. 「テキスト・リソースの選択」ダイアログで、コンポーネント・テキストをテキスト・リソースに関連付けます。
ダイアログのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

24.4.5 スキンを使用してゲージ・スタイルをグローバルに設定する方法

カスケード・スタイル・シート(CSS)を使用してスキンを作成し、アプリケーションでそのスキンを使用するように構成することにより、アプリケーション内のすべてのページにわたり、ゲージ・コンポーネントのフォント属性およびその他のスタイル属性をグローバルに設定できます。ゲージ・コンポーネントで使用されるスタイルを定義するスキンを適用することで、アプリケーション内のページは、CSSファイルの変更で簡単に変更できる一貫したスタイルで、より小さく整理されたものになります。

ADFデータ視覚化ツール・スキン・セレクタを使用して、ゲージ・コンポーネントのスタイルを定義できます。スタイルの設定をサポートするゲージ・コンポーネントのスキン・セレクタには、次のものがあります。

- af|dvt-gauge

- af|dvt-bottomLabel

- af|dvt-gaugeBackground

- af|dvt-gaugeFrame

- af|dvt-gaugeSetBackground

- af|dvt-indicator

- af|dvt-indicatorBar

- af|dvt-indicatorBase

- af|dvt-gaugeLegendArea

- af|dvt-gaugeLegendText

- af|dvt-gaugeLegendTitle

- af|dvt-lowerLabelFrame

- af|dvt-metricLabel

- af|dvt-gaugePlotArea

- af|dvt-threshold

- af|dvt-tickLabel

- af|dvt-tickMark

- af|dvt-topLabel

- af|dvt-upperLabelFrame

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

カスタム・スキンを使用してゲージ・スタイルを設定する手順:

1. ゲージ・サブコンポーネント用に定義されたスキン・スタイル・セレクタを含むアプリケーションに、カスタム・スキンを追加します。
たとえば、mySkin.cssファイルのすべての上部ラベル用フォント・ファミリは次のように指定します。

af|dvt-topLabel
{
-tr-font-family:SansSerif;
}

カスタム・スキン作成のヘルプが必要な場合は、『Oracle ADFスキン・エディタによるADFスキンの作成』のADFスキン・ファイルの作成に関する項を参照してください。

2. カスタム・スキンを使用するようにtrinidad-config.xmlファイルでアプリケーションを構成します。
アプリケーションの構成のヘルプが必要な場合は、『Oracle ADFスキン・エディタによるADFスキンの作成』の「完成したADFスキンのWebアプリケーションへの適用」の章を参照してください。

スタイルおよびスキンの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

24.5 ゲージの数値データ値の書式設定

metricLabel、tickLabel、gaugeLegendTextなど、ゲージの子コンポーネントにより、ゲージの数値データ値が表示されます。各コンポーネントには、numberType属性があり、値自体を表示するか、値が表す割合を表示するかを指定できます。数値の書式設定としては、これで十分な場合もあります。

ゲージ・メトリックまたはティック・ラベル値の書式をさらに設定する場合は、ADF Faces標準コンバータaf:convertNumberを使用できます。たとえば、値を通貨として表示したり、特定の小数設定を表示したりできます。

24.5.1 ゲージの数値データ値の書式設定方法

ゲージで表示されるメトリックは数値データ値です。これらの値には、特定の書式設定のルールを適用できます。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、構成可能なデータ値を表示するゲージの子コンポーネントが、「ゲージの作成」ダイアログでの選択に基づき、gaugeコンポーネントに自動的に追加されます。

ゲージの数値データ値の書式を設定する手順:

1. 「構造」ウィンドウで、構成するデータ値を表示するゲージの子コンポーネント(dvt:metricLabel、dvt:tickLabelまたはdvt:gaugeLegendText)を選択し、「プロパティに移動」を選択します。
コンポーネントが使用不可の場合、「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→(「メトリック・ラベル」、「ティック・ラベル」または「凡例テキスト」)を選択します。

2. 「プロパティ」ウィンドウで、データ値を値としてではなくパーセンテージとして表示する場合、コンポーネントのNumberType属性をNT_PERCENTに設定します。

3. ゲージ・メトリックまたはティック・ラベルで表示されるデータ値に追加の書式設定を指定する場合は、次のようにします。

1. 「構造」ウィンドウで、「dvt:metricLabel」または「dvt:tickLabel」を右クリックし、「メトリック・ラベルの中に挿入」または「ティック・ラベルの中に挿入」→「数値の変換」を選択します。

2. 「af:convertNumber」ノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、af:convertNumberコンポーネントの属性の値を指定して、追加の書式設定を行います。「ヘルプ」をクリックするか、[F1]を押すと、af:convertNumberコンポーネントの完全なタグ・ドキュメントが表示されます。

注意:

メトリックまたはティック・ラベルのnumberType属性がパーセント(NT_PERCENT)に設定されている場合、子のaf:convertNumberタグ(使用されている場合)は、そのtype属性に対して自動的にpercentに設定されます。af:convertNumberがpercentに強制的に指定されると、ゲージではpattern属性が消去されます。これは、ゲージでパーセントの書式設定が強制されると、パターンが無視されることを意味します。

24.5.2 自動位取りおよび精度に関する必知事項

コンパクトできれいな表示を実現するために、ゲージでは、メトリック・ラベルおよびティック・ラベルに表示される値の位取りおよび精度が自動的に決まります。たとえば、40,000の値は40Kと書式設定され、0.230546は小数点以下2桁の0.23として表示されます。

af:convertNumberが指定されている場合でも、自動書式設定は行われます。af:convertNumber子タグをサポートするゲージ・タグには、scalingやautoPrecision属性があり、これらの属性を使用して、ゲージの自動数値書式設定を制御できます。デフォルトでは、これらの属性値はscaling="auto"およびautoPrecision="on"に設定されています。af:convertNumberで指定される小数部の桁の設定(minFractionDigits、maxFractionDigitsまたはpatternなど)は、autoPrecisionがoffに設定されていないかぎり無視されます。

24.6 ゲージの特殊効果およびアニメーションの追加

ゲージの特定部分へのグラデーション効果の適用、ゲージへの相互作用の追加、ゲージへのアニメーションの使用、ゲージでのアクティブ・データのサポートなどの特殊機能をゲージに追加できます。

24.6.1 グラデーション特殊効果のゲージへの追加方法

グラデーションは、オブジェクトの色が段階的に変わる特殊効果です。グラデーションの各色は、ストップで表します。最初のストップはストップ0、2番目はストップ1のようになります。特殊効果をサポートするゲージの子コンポーネントに、特殊効果のストップの数を指定する必要があります。

ゲージの次の子コンポーネントにグラデーション特殊効果を定義できます。

- gaugeBackground

- gaugeSetBackground

- gaugePlotArea

- gaugeFrame

- gaugeLegendArea

- lowerLabelFrame

- upperLabelFrame

- indicator

- indicatorBar

- indicatorBase

- threshold

特殊効果を追加するゲージの子コンポーネントごとに、子のspecialEffectsコンポーネントを挿入する必要があります。たとえば、グラデーションをゲージの背景に追加する場合、backgroundコンポーネントに子のspecialEffectsコンポーネントタグを1つ追加します。specialEffectsコンポーネントのfillType属性もFT_GRADIENTに設定する必要があります。

その後、オプションで子コンポーネントの塗りつぶし色の変化の割合を制御する場合は、コンポーネントの塗りつぶしの色と変化の割合の制御に必要な数のgradientStopStyleコンポーネントを追加します。gradientStopStyleコンポーネントが子コンポーネントとしてspecialEffectsコンポーネントに追加されます。

グラデーション特殊効果の定義に使用する方法は、この効果がサポートされるゲージの各子コンポーネントで同じです。この手順は、グラデーション特殊効果をゲージに追加する方法を定義します。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

注意:

ページにゲージを追加すると、ゲージの子コンポーネントが、「ゲージの作成」ダイアログで選択したゲージ・タイプに基づき、gaugeコンポーネントに自動的に追加されます。

グラデーション特殊効果をゲージに追加する手順:

1. 「構造」ウィンドウで、グラデーション特殊効果をサポートするノード(たとえば、dvt:gaugeBackground)を選択し、必要な場合は展開して子ノードを表示します。

2. 選択したノードの子にdvt:specialEffectsコンポーネントが含まれない場合、ノードを右クリックし、「ノードの中に挿入」→「特殊効果」を選択します。

3. dvt:specialEffectsノードを右クリックして、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで次の属性を設定します。

- FillType: ドロップダウン・リストから「FT_GRADIENT」を選択します。

- GradientDirection: ドロップダウン・リストから、グラデーションの塗りつぶしに使用する変化の方向を選択します。デフォルト値はGD_RIGHTです。

- NumStops: グラデーションに使用するストップの数を入力します。

5. 必要に応じて、「プロパティ」ウィンドウで「グラデーション終了の構成」をクリックして、最初のグラデーション・ストップの色および変化率を制御します。

6. 「プロパティ」ウィンドウで次の属性を設定します。

- StopIndex: コンポーネントの索引としてゼロベースの整数を入力します。

- GradientStopColor: グラデーションに沿ってこの特殊ポイントで使用する色のRGB値を指定します。色を不透明から透明に変更することもできます。詳細は、24.4.2項「ゲージ要素の透明度の指定」を参照してください。

- GradientStopPosition: 指定した停止色のグラデーションでの相対的距離を入力します。グラデーションのスケールは0から100です。0または100が指定されない場合、これらのポイントにはデフォルトの位置が使用されます。

7. 追加のグラデーション・ストップを構成する場合は、「構造」ウィンドウで「dvt:specialEffects」コンポーネントを右クリックし、「特殊効果の中に挿入」→「グラデーション終了スタイル」を選択します。

8. 構成するグラデーション・ストップごとに、ステップ5からステップ7を繰り返します。

24.6.2 グラデーション特殊効果をゲージに追加する場合の処理

ゲージの背景にグラデーションの塗りつぶしを追加し、2つのストップを指定して、ストップごとに色および変化の率を構成すると、XMLコードが生成されます。例24-6に、生成されるXMLコードを示します。

例24-6 グラデーションをゲージの背景に追加する場合に生成されるXMLコード

<dvt:gauge>
<dvt:gaugeBackground borderColor="#848284">
<dvt:specialEffects fillType="FT_GRADIENT" gradientDirection="GD_RADIAL">
<dvt:gradientStopStyle stopIndex="0" gradientStopPosition="60"
gradientStopColor="FFFFCC"/>
<dvt:gradientStopStyle stopIndex="1" gradientStopPosition="90"
gradientStopColor="FFFF99"/>
</dvt:specialEffects>
</dvt:gaugeBackground>
</dvt:gauge>

24.6.3 ゲージへの相互作用の追加方法

ゲージでの相互作用には、ゲージの指定した部分をハイパーリンクなどのHTML属性、またはユーザーがカーソルをゲージのその部分に移動するなどのJavaScriptイベントと関連付ける必要があります。たとえば、ゲージ・インジケータはハイバーリンクと関連付けることができ、ゲージ・インジケータのツールチップは、ユーザーがインジケータをクリックすると「インジケータ」から「インジケータがクリックされました」に変えることもできます。

ゲージの子のshapeAttributesSetコンポーネントにラップされている1つ以上のshapeAttributesコンポーネントで、相互作用プロパティを指定します。相互作用は、shapeAttributesコンポーネントのcomponent属性、HTML属性またはJavaScriptイベントで指定されているように、ゲージのサブコンポーネントを結び付けます。各shapeAttributesコンポーネントが機能するには、サブコンポーネントおよび少なくとも1つの属性が含まれている必要があります。

shapeAttributesコンポーネントのcomponent属性で指定されているゲージ・サブコンポーネントの有効な値は、次のとおりです。

- GAUGE_BOTTOMLABEL: ゲージの下のラベル

- GAUGE_INDICATOR: ゲージのインジケータ

- GAUGE_LEGENDAREA: ゲージの凡例エリア

- GAUGE_LEGENDTEXT: 凡例エリアのテキスト・ラベル

- GAUGE_METRICLABEL: メトリック値を示すラベル

- GAUGE_TOPLABEL: ゲージの上のラベル

- GAUGE_PLOTAREA: ゲージの内側のエリア

- GAUGE_THRESHOLD: ゲージのしきい値のエリア

ゲージのサブコンポーネントと関連付けられた相互作用属性は、次のいずれかです。

- 動作属性: onClick、onMouseMove、onKeyDownなどの属性、または接頭辞onが付き、JavaScriptコードまたはJavaScriptコードを値として返すマネージドBeanへの参照を含む文字列をとる任意の属性などの属性。値がマネージドBeanメソッドの場合、メソッドは入力パラメータとしてサブコンポーネント・ハンドルをとります。

- 共通属性: 文字列か値として文字列を返すマネージドBeanをとるalt、href、nohref、target、titleおよびtabindixなどのHTML属性。値は属性に応じて文字列またはブール値を指定できます。その他の属性は、クリック・イベントを制御するclickable、clickActionおよびclickListenerや、サブコンポーネントを参照するidなど、相互作用の基本的な設定を制御します。

たとえば、例24-7は、ユーザーがインジケータをクリックすると、インジケータのツールチップが「インジケータ」から「インジケータがクリックされました」に変わり、ユーザーが実行時にマウスをラベルに移動すると、ゲージのメトリック・ラベルのツールチップに「メトリック・ラベル」と表示されるダイアル・ゲージのコードを示しています。

例24-7 ゲージのshapeAttributesコンポーネントのサンプル・コード

<dvt:gauge>
<dvt:shapeAttributesSet>
<dvt:shapeAttributes component="GAUGE_INDICATOR" alt="Indicator"
onClick="document.title="onClick";"/>
<dvt:shapeAttributes component="GAUGE_METRICLABEL" alt="Metric Label"
onMouseMove="document.title="onMouseMove";"/>
</dvt:shapeAttributesSet>
</dvt:gauge>

相互作用属性の値を返すマネージドBeanメソッドを使用することもできます。例24-8に、マネージドBeanのサンプル・コードを示します。

例24-8 マネージドBeanのサンプル・コード

public String alt(oracle.dss.dataView.ComponentHandle handle) {
return handle.getName(); }
public String onClick(oracle.dss.dataView.ComponentHandle handle) {
return ("document.title=\"onClick\";"); }
public String onMouseMove(oracle.dss.dataView.ComponentHandle handle) {
return ("document.title=\"onMouseMove\";"); }

例24-9に、shapeAttributesコンポーネントのマネージドBeanを参照するためのサンプル・コードを示します。

例24-9 マネージドBeanを参照するゲージのshapeAttributesコンポーネント

<dvt:gauge>
<dvt:shapeAttributesSet>
<dvt:shapeAttributes component="GAUGE_INDICATOR" alt="#{sampleGauge.alt}"
onClick="#{sampleGauge.onClick}"/>
<dvt:shapeAttributes component="GAUGE_METRICLABEL"
alt="#{sampleGauge.alt}"
onMouseMove="#{sampleGauge.onMouseMove}"/>
</dvt:shapeAttributesSet>
</dvt:gauge>

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

マネージドBeanがJDeveloperでどのように使用されるかを理解しておくと役立ちます。詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージ・サブコンポーネントに相互作用を追加する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ゲージの中に挿入」→「ADFデータ視覚化」→「形状属性セット」を選択します。

2. 「dvt:shapeAttributesSet」ノードを右クリックし、「形状属性セットの中に挿入」→「形状属性」を選択します。

3. 「dvt:shapeAttributes」ノードを右クリックして、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、「共通」セクションを展開します。Component属性に対し、ドロップダウン・リストを使用して、相互作用を追加するゲージ・サブコンポーネントを選択します。
たとえば、ゲージのインジケータに相互作用を追加するには、「コンポーネント」ドロップダウン・リストから「GAUGE_INDICATOR」を選択します。

5. このセクションでその他の属性を1つ以上設定し、サブコンポーネントの相互作用プロパティを指定します。

注意:

このセクションでは、属性で属性ドロップダウン・メニューを使用して、マネージドBeanへの参照を作成する際に、「メソッド式ビルダー」ダイアログを選択することができます。一部の属性については、「編集」→「プロパティの編集」を選択して、ドロップダウン・リストから使用可能なマネージドBeanを選択することも、「新規」を選択して、「マネージドBeanの作成」ダイアログを使用してマネージドBeanを作成することもできます。

6. 「動作」セクションを開きます。このセクションを使用して、接頭辞onが付き、JavaScriptコードまたはJavaScriptコードを値として返すマネージドBeanへの参照を含む文字列をとるこれらの属性を1つ以上設定します。

7. ゲージ・サブコンポーネントに追加の相互作用効果を構成する場合は、サブコンポーネントごとにステップ2からステップ6を繰り返します。

24.6.4 ゲージへのアニメーションの使用

初期表示で、またはデータの変更を示すために、ゲージ(ゲージ・セットではない)をアニメーション化できます。アニメーション効果は、ゲージのanimationOnDisplayおよびanimationOnDataChangeプロパティで指定します。たとえば、ダイアル・ゲージ・インジケータは、初期表示や、データ値の増減時に色を変えることができます。図24-15に、各しきい値レベルでデータの変化をアニメーションで表示するダイアル・インジケータの付いたダイアル・ゲージを示します。

図24-15 アニメーションを使用したダイアル・ゲージ

アニメーション効果は、アクティブ・データを使用して実行することもできます。アクティブ・データ・サービス(ADS)では、ADFモデル・レイヤーを使用して、ADF Facesコンポーネントをアクティブ・データ・ソースにバインドできます。このためには、コンポーネントとバインディングを構成して、コンポーネントがソースで更新されたデータを表示できるようにする必要があります。あるいは、あらかじめ決められた間隔で変更のデータ・ソースをポーリングするようにアプリケーションを構成することもできます。

24.6.5 ゲージのアニメーション効果の指定方法

ゲージのアニメーション効果は、初期表示、または部分ページ・レンダリング(PPR)またはアクティブ・データ・サービス(ADS)に関連付けられたデータ変更で設定できます。PPRの詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。ADSの詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Facesコンポーネントを使用して追加できる機能について理解しておくことをお薦めします。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージのアニメーション効果を指定する手順:

1. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、必要に応じて「外観」セクションを展開します。「アニメーション」サブセクションを使用して、次の属性を設定します。

- AnimationOnDisplay: 適用する初期レンダリング効果のタイプの指定に使用します。有効な値は次のとおりです。

- NONE: (デフォルト)初期レンダリング効果は表示されません。

- AUTO: グラフ・タイプまたはゲージ・タイプに基づいて自動的に選択された初期レンダリング効果が適用されます。

- AnimationOnDataChange: 適用するデータ変化のアニメーションでデータ・タイプの指定に使用します。有効な値は次のとおりです。

- NONE: データ変更のアニメーション効果は適用されません。

- AUTO: (デフォルト)アクティブ・データ・サービス(ADS)のデータ変化のアニメーション・イベントが適用されます。ADSの詳細は、24.6.6項「アクティブ・データを表示するためのゲージの構成方法」を参照してください。

- ON: 部分ページ・リフレッシュ(PPR)データ変化のアニメーション・イベントを適用します。この設定を使用して、所定の間隔で変更のデータ・ソースをポーリングするように、アプリケーションを構成します。

- AnimationDuration: アニメーション効果をミリ秒で指定するために使用します。デフォルト値は1000です。

24.6.5.1 スキニングおよびゲージのアニメーション効果に関する必知事項

カスケード・スタイル・シート(CSS)を使用してスキンを作成することで、ADFデータ視覚化ツールのスキン・セレクタを使用して、アプリケーション内のすべてのページに対してアニメーション効果およびスタイルをグローバルに定義できます。アニメーションを定義するスキンを適用することで、アプリケーション内のページは、CSSファイルの変更で簡単に変更できる一貫したスタイルで、より小さく整理されたものになります。

例24-10に、アニメーション効果を定義するスキニング・キーの使用例を示します。

例24-10 アニメーション効果を定義するスキニング・キーの使用

af:dvt-gauge
{
-tr-animation-duration:500;
-tr-animation-indicators:auto;
-tr-animation-on-data-change:on;
-tr-animation-on-display:auto;
}

スキニングおよびスタイルの使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

24.6.6 アクティブ・データを表示するゲージの構成方法

アクティブ・データ・サービス(ADS)を使用したアニメーション効果は、ダイアル・メーター・ゲージ・タイプおよびステータス・メーター・ゲージ・タイプに追加できます。ADSでは、ADFモデル・レイヤーを使用して、ADF Facesコンポーネントをアクティブ・データ・ソースにバインドできます。このためには、コンポーネントとバインディングを構成して、コンポーネントがデータ・ソースで更新されたデータを表示できるようにする必要があります。ADSの詳細およびアプリケーションの構成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アクティブ・データ・サービスの使用」の章を参照してください。

データ・バインドされたゲージを構成し、対応するページ定義ファイルでバインディング要素に値を設定することによってアクティブ・データを表示します。

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Facesコンポーネントを使用して追加できる機能について理解しておくことをお薦めします。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

データが変更されたときにイベントを公開するデータ・ソースが必要であり、それらのイベントに反応するビジネス・サービスと、それらのサービスを表示するための関連のデータ・コントロールを作成しておく必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「アクティブ・データ・サービスの使用」の章を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

アクティブ・データを表示するデータ・バインドされたゲージを構成する手順:

1. 「構造」ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「ページ定義に移動」を選択します。

2. 「構造」ウィンドウで「バインディング」を展開し、コンポーネントの属性バインディングを表すノードを選択します。

3. 「プロパティ」ウィンドウで「拡張」セクションを展開し、ChangeEventPolicy属性のドロップダウン・リストから「プッシュ」を選択します。

24.7 ゲージのカスタム形状の使用方法

ゲージ・コンポーネントには、事前作成されたカスタム形状スタイルのセットが用意されています。ゲージのカスタム形状を作成するために、グラフィック・ファイルを作成して使用することもできます。ゲージ・コンポーネントのcustomShapesPath属性を設定して、使用可能なカスタム形状を使用するか、出力に使用するグラフィックに加工されるベクトル・グラフィック・ファイルを指定します。

24.7.1 事前作成されたカスタム形状スタイルの使用方法

事前作成されたカスタム形状スタイルのセットから選択して、ゲージのカスタム形状を指定できます。カスタム形状スタイルは、次のとおりです。

- 角丸矩形

- 完全な円

- 立体的な円

図24-16に、カスタム形状スタイルを適用して表示されたダイアル・ゲージを示します。

図24-16 カスタム形状スタイルを使用したダイアル・ゲージ

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージにカスタム形状スタイルを適用する手順:

1. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを展開し、CustomShapesPath属性のドロップダウン・リストからカスタム形状スタイルを選択します。有効な値は、Rounded Rectangle、Full CircleおよびBeveled Circleです。

24.7.2 カスタム形状グラフィック・ファイルの使用方法

描画エリアやティック・マークなど、ゲージのコンポーネントの回転およびサイズ変更のための要件があるため、カスタム形状グラフィック・ファイルを作成する場合は、ベクター・グラフィック・ファイルが必要です。スケーラブル・ベクター・グラフィック(SVG)が、ゲージのカスタム形状作成のためのファイル形式としてサポートされています。

ゲージを設計してSVGファイルにエクスポートしたら、ゲージの形状およびコンポーネントを識別し、スケールおよび位置設定し、処理に使用されるその他のメタデータを指定するための情報を設計者は追加できます。

SVGファイルで、ゲージ・コンポーネントはIDを使用して識別されます。たとえば、<polygon id="indicator"/>と指定されたSVGファイルは、indicatorコンポーネントに多角形形状を使用するものと解釈されます。複数の形状を指定してコンポーネントに必要なビジュアルを作成するには、IDをid="indicator_0"、id="indicator_1"およびid="indicator_2"に変更できます。

表24-1に、ゲージ・コンポーネントIDとその説明を示します。

表24-1 カスタム形状のゲージ・コンポーネントID

ID

説明

indicator

ゲージによって表される値を指します。指定されていない場合、ゲージではアプリケーションで指定されたインジケータが使用されます。

ダイアル・ゲージでは、形状が適切に回転されるように、上を示して(90度)indicatorを指定する必要があります。

ステータス・メーター・ゲージでは、インジケータを完全に指定する必要があり、ゲージはメトリック値を指すようにトリミングされます。

indicatorBase

ダイアル・ゲージの場合は、indicatorコンポーネントの下部に表示されるオブジェクトを指します。indicatorCenterを指定せずに指定すると、indicatorBaseがindicatorCenterとして扱われます。

gaugeFrame

plotAreaを視覚的に表現するためのオプションのコンポーネントです。renderedプロパティを設定することによって、アプリケーションで有効化または無効化できます。ユーザーがデフォルト・ゲージであるplotAreaを使用する場合に主に使用されます。plotAreaが指定されていないと、ゲージによってデフォルトのplotAreaがplotAreaBounds内に挿入されます。カスタムplotAreaまたはtickMarkを作成せずにゲージの外観を変更する簡便な方法です。

lowerLabelFrame

位置がLP_BELOW_GAUGEのときにbottomLabelを含むフレームを指し、ユーザーはこのフレームの外観をカスタマイズできます。カスタム形状ファイルにある場合、ゲージによってlowerLabelFrameは他のゲージ・コンポーネントと同じ相対位置に置かれます。

plotArea

ダイアル・ゲージの場合は、インジケータが移動する円形エリアを指します。

ステータス・メーター・ゲージの場合は、インジケータが含まれるエリアを指します。

LEDゲージの場合は、LEDの塗りつぶし色で塗りつぶされないグラフィックが含まれるエリアを指します。

plotAreaが指定されていない場合、ゲージによってデフォルトのplotAreaが描画されます。ティック・マークを描画するには、plotAreaの仕様にtickMarkPathまたはティック・マークのセットも必要です。

tickMark

ゲージの増分の定義に使用します。tickMarkPathなしでティック・マークのセットを指定すると、ゲージではplotArea上で表示される正確な場所にティック・マークが使用されます。この場合、ティック・マークが同じ増分で表示されるかどうかはユーザーが確認する必要があります。tickMarkPathが指定されると、ゲージでは単一のtickMarkが受け入れられ、ダイアルに対して90度で、tickMarkPathに沿ってtickMarkを回転させ、位置が指定されます。

upperLabelFrame

位置がLP_ABOVE_GAUGEの場合にtopLabelを含むフレームを指します。upperLabelFrameを設定すると、ユーザーはフレームの外観をカスタマイズできます。カスタム形状ファイルにある場合、ゲージによってupperLabelFrameは他のゲージ・コンポーネントと同じ相対位置に置かれます。

表24-2に、内部計算に使用され、ゲージにはレンダリングされないメタデータIDとその説明を示します。

表24-2 カスタム形状のメタデータID

ID

説明

indicatorBarBounds

インジケータ・バーの最小範囲および最大範囲を含むボックスを指定します。指定されていない場合、バウンディング・ボックスは入力ファイルで指定されたとおり、インジケータ全体に広がります。

indicatorCenter

ダイアル・ゲージ内で回転するインジケータの回転の中央を指定します。このIDを持つ形状の中央がインジケータの中央とみなされます。指定されていない場合、180度のダイアル・ゲージでは描画エリアの下端の中央、N度のダイアル・ゲージでは描画エリアの中央とみなされます。

ledFillArea

適切なしきい値の色で塗りつぶされる必要のあるLEDゲージの領域を指定します。指定されていない場合、グラフィック・ファイルで指定されたplotArea形状全体が、しきい値の色で塗りつぶされます。

lowerLabelFrameTextBox

複雑なlowerLabelFrame形状では、lowerLabelFrameTextBoxとして設定可能な矩形が指定されます。このボックスでは、lowerLabelFrame内の下位ラベルの位置が決定されます。

plotAreaBounds

plotAreaのバウンディング・ボックスを指定します。このファイルでplotAreaが指定されていない場合は、ゲージの描画エリアに描画するため、ゲージにバウンディング・ボックスが必要です。指定されていない場合、gaugeFrame自体のバウンディング・ボックスがこの目的に使用されます。

thresholdFillArea

しきい値の色で塗りつぶされる領域を定義します。

ダイアル・ゲージの場合は、indicatorCenterから弧をスイープして塗りつぶされるthresholdFillAreaが指定されます。

ステータス・メーター・ゲージの場合は、ステータス・メーター・ゲージの向きに基づいて塗りつぶされるthresholdFillAreaが指定されます。

tickMarkPath

ティック・マークを描画するパスを定義します。これが指定されていない場合、ゲージはカスタム描画エリアでティック・マークを描画する場所を計算する必要があり、ゲージはmajorTickCountを変更することができません。

upperLabelFrameTextBox

複雑なupperLabelFrame形状では、upperLabelFrameTextBoxとして設定可能な矩形が指定されます。このボックスでは、upperLabelFrame内の topLabelの位置が決定されます。

例24-11に、ゲージのコンポーネントにカスタム形状を指定する場合に使用するサンプルSVGファイルを示します。

例24-11 ゲージのカスタム形状に使用するサンプルSVGファイル

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
version="1.0">

<rect width="264.72726" height="179.18887" rx="8.2879562"
ry="10.368411" x="152.76225" y="202.13995"
style="fill:#c83737;fill-opacity:1;stroke:none"
id="gaugeFrame"/>
<rect width="263.09058" height="42.581127" rx="3.0565372"
ry="3.414634" x="155.11697" y="392.35468"
fill="#c83737"
id="lowerLabelFrame" />
<rect width="241.79999" height="120.13961"
x="164.2415" y="215.94714"
style="fill:#ffeeaa"
id="plotAreaBounds"/>
<rect width="74.516975" height="44.101883"
rx="2.6630435" ry="3.5365853"
x="247.883" y="325.4415"
style="fill:#ffd5d5;fill-opacity:1;stroke:none"
id="indicatorBase"/>
<rect width="6.0830183" height="98.849045" rx="2.6630435"
ry="2.2987804" x="282.86035" y="237.23772"
style="fill:#00aa00;fill-opacity:1;stroke:none"
id="indicator"/>
</svg>

始める前に:

ゲージの属性やゲージの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、24.2.1項「ゲージの構成」を参照してください。

他のADF Faces機能を使用して追加できる他の機能について理解しておくことをお薦めします。詳細は、24.1.3項「ゲージ・コンポーネントの追加機能」を参照してください。

ページにすでにゲージが存在している必要があります。ない場合は、この章の指示に従ってゲージを作成します。詳細は、24.2.2項「ページへのゲージの追加方法」を参照してください。

ゲージの既存のカスタム形状グラフィック・ファイルを使用する手順:

1. アプリケーションにSVGファイルをインポートし、その場所をメモします。
ファイルのインポートについてのヘルプが必要な場合は、『Oracle Jdeveloperによるアプリケーションの開発』のアプリケーションおよびプロジェクトの管理に関する項を参照してください。

2. 構造ウィンドウで「dvt:gauge」コンポーネントを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで「外観」セクションを開きます。

4. CustomShapesPath属性のドロップダウン・メニューから、「式ビルダー」を選択し、ゲージのカスタム形状を指定するために使用するSVGファイルへの相対パスを入力します。
たとえば、プロジェクト構造のWeb Contentディレクトリの下位のImagesディレクトリにファイルをインポートした場合、CustomShapesPathフィールドに次のパスを入力します。

Images/customShapesFile.svg

24.7.3 サポートされているSVG機能に関する必知事項

使用可能なカスタム形状では、次のSVG機能がサポートされています。

- 変換

- パス

- 基本的な形状

- 塗りつぶしとストローク・ペインティング

- 線形および放射状のグラデーション

カスタム形状によってサポートされていないSVG機能には次のものがあります。

- ユニット識別子: ユニット識別子がない場合は、すべての座標と長さを指定する必要があり、単位はピクセルとみなされます。特定の単位では使用されるディスプレイに基づいてサイズが異なるため、パーサーでユニット識別子はサポートされていません。たとえば、異なるディスプレイでは1インチに対応するピクセル数が異なる場合があります。この唯一の例外がグラデーション調整でパーセンテージとして指定できます。

- テキスト: ゲージ上のすべてのテキストはデータとみなされ、タグまたはデータ・バインディングを使用して指定される必要があります。

- ペイントの指定: サポートされているオプションはnone、6桁の16進数、およびグラデーションへの<uri>参照です。

- 塗りつぶしのプロパティ: fill-rule属性はサポートされていません。

- ストロークのプロパティ: stroke-linecap、stroke-linejoin、stroke-miterlimit、stroke-disarrayおよびstroke-opacity属性はサポートされていません。

- 線形および放射状のグラデーション: gradientUnits、gradientTransform、spreadMethodおよびxlink:hrefはサポートされていません。また、放射状のグラデーションに関するr属性、fx属性およびfy属性はサポートされていません。

- 楕円弧および範囲外のパラメータ: rx、ryおよびx-axis-rotが小さすぎて解が得られない場合、正確に1つの解が得られるまで楕円を均等に拡大する必要があります。SVGパーサーはこれをサポートしていません。

- 一般エラーの条件: SVG入力は、正しい形式でエラーがないものと予想されます。SVGパーサーでは、エラー・チェックや、正しい形式でないファイルのエラー・リカバリは実行されず、ファイルでエラーが発生すると解析を停止します。

25 ピボット・テーブル・コンポーネントの使用方法

この章では、ADFデータ可視化コンポーネントのpivotTableおよびpivotFilterBarを使用し、簡単なUI優先開発を使用してピボット・テーブルにデータを表示する方法について説明します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックを使用する場合、データ・コントロールを使用してピボット・テーブルを作成することもできます。JDeveloperには、データ・バインディングとピボット・テーブルの構成用のウィザードがあります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 25.1項「ピボット・テーブル・コンポーネントについて」

- 25.2項「ピボット・テーブル・コンポーネントの使用方法」

- 25.3項「ヘッダーおよびデータ・セルのスタンプの構成」

- 25.4項「ピボット・フィルタ・バーの使用方法」

- 25.5項「ピボット・テーブルへの相互作用の追加」

- 25.6項「CellFormatによるピボット・テーブルのセルのコンテンツの書式設定」

25.1 ピボット・テーブル・コンポーネントについて

ピボット・テーブルでは、グリッド・レイアウトにデータが表示されます。このグリッド・レイアウトには、階層的にネストされた行ヘッダー・セルおよび列ヘッダー・セルの無制限のレイヤーが備わっています。表計算ソフトウェア同様、ピボット・テーブルでは、グリッド・データの小計と合計を自動的に生成するオプションが用意されています。

ピボット・テーブルでは、ユーザーは、行または列ヘッダー・データ・ラベルおよび関連するデータ・レイヤーを、行または列エッジ上のある場所から別の場所へピボット処理、つまり再配置することで、データの表示を変えることができます。これにより、インタラクティブな分析がサポートされます。

ピボット・フィルタ・バーは、ピボット・テーブルの行または列エッジの1つで表示されない層にあるピボット・テーブル・データをユーザーがフィルタ処理できるように、ピボット・テーブルに追加できるコンポーネントです。ユーザーは、ピボット・フィルタ・バーと関連付けられたピボット・テーブルの間でこれらのレイヤーをドラッグ・アンド・ドロップして、データのビューを変更することもできます。ピボット・フィルタ・バーを使用して、グラフ内のデータのグラフィカル表示を変更することもできます。

25.1.1 ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントのユースケースおよび例

ピボット・テーブルには、行および列によるデータのグリッドが表示されます。図25-1に、行と列に複数の属性がネストするピボット・テーブルを示します。

図25-1 複数の行および列を持つ売上げピボット・テーブル

ピボット・テーブル・データ・セルでは、スパークチャート、ゲージおよびグラフなどの他のデータ表示コンポーネントをサポートします。図25-2に、長期にわたるデータの傾向を表すスパークチャートがデータ・セルに表示されたピボット・テーブルを示します。

図25-2 データ・セルにスパークチャートが表示されたピボット・テーブル

図25-3に、データ・セルにグラフがスタンプされたピボット・テーブルを示します。

図25-3 データ・セルにグラフがスタンプされたピボット・テーブル

ピボット・テーブルのヘッダーおよびデータ・セルは、イメージ、アイコンまたはリンクの表示や、ストップライトおよび条件付き書式設定の表示のためにカスタマイズできます。図25-4に、売上げ実績のレベルを表示するための条件付き書式設定を使用したピボット・テーブルを示します。

図25-4 データ・セルの条件付き書式設定

ピボット・フィルタ・バーは、ピボット・テーブルの行エッジまたは列エッジで表示されないレイヤーにあるピボット・テーブル・データをユーザーがフィルタ処理できるように、ピボット・テーブルに関連付けられるコンポーネントです。ユーザーは、ピボット・フィルタ・バーと関連付けられたピボット・テーブルの間でこれらのレイヤーをドラッグ・アンド・ドロップして、データのビューを変更することもできます。図25-5に、ピボット・テーブルに関連付けられたピボット・フィルタ・バーを示します。

図25-5 ピボット・テーブルに関連付けられたピボット・フィルタ・バー・コンポーネント

ピボット・フィルタ・バーを使用して、ピボット・テーブルに関連付けられているグラフ内のデータの表示を変更することもできます。図25-6に、ピボット・テーブルとグラフに同時に表示されている四半期の売上げデータのフィルタ処理されたビューを示します。

図25-6 ピボット・テーブルおよびグラフに関連付けられたピボット・フィルタ・バー

25.1.2 ピボット・テーブル・コンポーネントのエンド・ユーザー機能およびプレゼンテーション機能

ADFデータ視覚化ピボット・テーブル・コンポーネントには、ピボット処理、列のソートや、1つ以上の行、列またはセルの選択後、選択対象でアプリケーション定義のアクションを実行するなど、エンド・ユーザー用の一連の機能が用意されています。また、階層的にネストされた行ヘッダー・セルおよび列ヘッダー・セルの無制限のレイヤーなど、一連のプレゼンテーション機能も備わっています。

25.1.2.1 ピボット・フィルタ・バー

ピボット・テーブルのデータ・フィルタ処理能力は、オプションのピボット・フィルタ・バーにより強化できます。ピボット・テーブルの行エッジまたは列エッジですでに表示されなくなったゼロ以上のデータのレイヤーは、ページ・エッジでは表示されます。図25-31に、ピボット・テーブルに表示されるデータのフィルタ処理に使用可能な四半期および月のレイヤーを含むピボット・フィルタ・バーを示します。

図25-7 データ・レイヤー・フィルタを持つピボット・フィルタ・バー

25.1.2.2 ピボット処理

ピボット・テーブル内の任意のレイヤーを同じエッジ上の異なる位置、反対側のエッジ、または関連付けられたピボット・フィルタ・バー(ある場合)へドラッグして、ピボット・テーブル内のデータのビューを変更できます。ピボット・フィルタ・バーの任意のレイヤーを、ピボット・フィルタ・バー内の異なる位置や、ピボット・テーブルの行または列エッジにドラッグできます。この操作はピボット処理と呼ばれ、デフォルトで有効になっています。

マウスをレイヤーに移動すると、レイヤーのピボット・ハンドルとオプションのピボット・ラベルが表示されます。マウスをピボット・ハンドルに移動すると、カーソルが4点矢印のドラッグ・カーソルに変わります。次にこのハンドルを使用して、レイヤーを新しい場所へドラッグできます。行エッジのレイヤー上にカーソルを置くと、図25-8に示すとおり、そのレイヤーの上にピボット・ハンドルが表示されます。

図25-8 行エッジでのピボット・ハンドルの表示

カーソルを列エッジのレイヤーに移動すると、ピボット・ハンドルが図25-9に示すようにそのレイヤーの左に表示されます。

図25-9 列エッジ上のピボット・ハンドルの表示

図25-8で時間(年)レイヤーのピボット・ハンドルを行エッジから列エッジの尺度(売上げ)レイヤーと販路レイヤーの間にドラッグすると、ピボット・テーブルは図25-10に示すように変わります。

図25-10 年のピボット後の売上げピボット・テーブル

ピボットはピボット・ラベルおよびピボットを無効にするようにカスタマイズできます。両方を無効にすると、レイヤーにマウスを移動してもピボット・ハンドルは表示されません。

25.1.2.3 データ・セルの編集

ピボット・テーブルには、読取り専用のデータ・セルと編集可能なデータ・セルの両方を含めることができます。編集可能なセルは、入力コンポーネント(たとえば、af:inputTextまたはaf:comboBox)を含むセルです。編集可能なセルを含むピボット・テーブルが最初に表示されるとき、最初のデータ・セルが選択されていて、ピボット・テーブルが編集のために開いています。ユーザーは、セルをクリックすることでピボット・テーブル内のどこでも編集を開始して、セル値を編集または上書きできます。ユーザーは、編集可能なセルでクリックすることで、セル内の特定の場所を指定し、矢印キーを使用してそのセル内で移動できます。編集可能なセル上で実行された編集は、[Esc]を押せば元に戻すことができます。

注意:

[Esc]キーを押しても、値リスト・コンポーネント(af:inputComboboxListOfValuesなど)で選択した値は元に戻りません。これは、ドロップダウンを閉じると、ただちに値が送信されるためです。

図25-11に、直接編集のために開かれたピボット・テーブルのデータ・セルを示します。

図25-11 直接編集のために開かれたデータ・セル

ドロップダウン・リストの編集のために選択されたデータ・セルは、図25-12で示すように表示されます。

図25-12 ドロップダウン・リストの編集のために開かれたデータ・セル

編集モードの間は、[Tab]または[Enter]キーを使用して、ピボット・テーブルのデータ・セル内を移動できます。現在選択されているセルの下または上のセルに迅速に移動するには、[Ctrl]キーを押しながら矢印キーを使用します。移動に[Enter]キーを使用するとき、アクティブ・リンクを含むセルに対して、アクティブ・リンクが自動的に開始されます。[Tab]または[Shift]+[Tab]を使用して移動するとき、複数の編集可能コンポーネントを含むデータ・セルは、同じセルのaf:inputDateとデータ・ピッカーの両方の場合のように、[Tab]で各編集可能コンポーネントが順々に強調表示されます。ピボット・テーブルの最終列までタブで移動すると、次の行の最初の列が強調表示され、ピボット・テーブルで最初の列まで[Shift]を押しながらタブ移動すると、前の行の最終列が強調表示されます。

編集モードを開始すると、ユーザーは編集モードを維持したまま、読取り専用データ・セルから編集可能データ・セルまで移動できます。編集可能セルが選択されている間、新規セルでの編集を有効にすることなく、元のセルでの編集を保持しつつ、[Ctrl]または[Shift]を押しながらクリックして別のセルを選択できます。

注意:

キューブ内のセルのセットに値を一時的または完全に書き戻す操作(書戻しと呼ばれる)を行うには、ピボット・テーブルが書戻し操作をサポートするデータ・コントロールまたはデータ・モデルにバインドされている必要があります。ピボット・テーブルの行セット・ベースのデータ・コントロールは、書戻し操作をサポートするキューブに変換されます。

25.1.2.4 データおよびヘッダーのソート

ピボット・テーブルでは、ピボット・テーブル内のデータのソートがサポートされています。ソートが有効な場合、ユーザーが列ヘッダーの最も内側のレイヤーにマウスを移動すると、昇順ソートと降順ソートのアイコンが表示されます。デフォルトでは、pivotTableコンポーネントのsortMode属性はgroupedに設定されており、行エッジの最も内側から2番目のレイヤーによってグループ化されたデータを効果的にソートします。図25-13では、World Sales列内のデータが降順にソートされています。ここでは、各年内の製品がグループ化され、それによっても降順にソートされています。

図25-13 ピボット・テーブルの昇順および降順ソート・アイコン

コンテキスト・メニュー・オプションを使用して、列および行ヘッダーを基準にデータ表示をソートすることもできます。列または行ヘッダーでソート順を設定すると、そのレイヤー内のすべての列および行も同様にソートされます。図25-14に示すピボット・テーブルでは、US City列ヘッダーが左から右にソートされており、ソート順を右から左に変更するためのコンテキスト・メニュー・オプションがあります。

図25-14 ピボット・テーブルの列ヘッダーのソート

図25-15に示すピボット・テーブルでは、Car行ヘッダーが下から上にソートされており、ソートを上から下に変更するためのコンテキスト・メニュー・オプションがあります。

図25-15 ピボット・テーブルの行ヘッダーのソート

25.1.2.5 ドリル

ピボット・テーブルでは、ドリルの挿入およびドリルのフィルタの2種類のドリルがサポートされています。ドリルの挿入では、展開操作により、兄弟および集計データを保持しながら、詳細なデータを表示します。ドリルのフィルタでは、展開操作により、兄弟および集計データはフィルタで除外され、詳細データのみが表示されます。

たとえば、図25-16および図25-17は、各年の製品データを表示するためにドリルがどのように使用されるかを示しており、2007年の総売上高52,500の内訳が、テントの25,500とカヌーの27,000であることを表しています。この合計は、すべての年のすべての売上高の総計128,172に寄与しています。図25-16に、ドリルの挿入を使用して詳細な数値とともに合計数52,500が表示されたピボット・テーブルを示します。他の年のデータとすべての年の総計も利用できます。

図25-16 ドリルの挿入が有効になっているピボット・テーブル

図25-17に、ドリルのフィルタを使用して詳細な数値のみが表示されたピボット・テーブルを示します。その他の年の数値とすべての年の総計がフィルタで除外されています。

図25-17 ドリルのフィルタが有効になっているピボット・テーブル

実行時には、両タイプのドリルの親属性表示ラベルでドリル・アイコンが有効になります。

ピボット操作を行わない場合、ドリル操作はセッション中はそのままです。ただし、親属性からドリル操作した子属性をピボット操作する場合、Oracle MDS (Metadata Services)カスタマイズを使用して任意の動作を構成できます。MDSを使用したカスタマイズ可能アプリケーションの作成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「MDSによるアプリケーションのカスタマイズ」の章を参照してください。

25.1.2.6 スクロールおよびページ・コントロール

ピボット・テーブルでは、パフォーマンスを維持しながら、大規模なデータ・セットをサポートするために、オンデマンド・データ・スクロールがサポートされています。ピボット・テーブルでスクロールにより表示されるデータのみがロードされます。ユーザーが垂直または水平にスクロールすると、スクロールで表示されたデータがピボット・テーブルの一部にフェッチされ、不要になったデータは廃棄されます。図25-18に、オンデマンド・データ・スクロールを使用して大規模なデータ・セットを表示するピボット・テーブルを示します。

図25-18 ピボット・テーブルのオンデマンド・データ・スクロール

デスクトップ・アプリケーションやタッチ装置のモバイル・ブラウザに対しては、ピボット・テーブルの大規模なデータ・セットのナビゲーション用に、スクロールバーのかわりにページ・コントロールを構成できます。たとえば、図25-19に示すように、列のページ・コントロールはピボット・テーブルの上部に、行のページ・コントロールはピボット・テーブルの下部に表示されます。

図25-19 ピボット・テーブルの列と行のページ・コントロール

最初に表示される行または列データ・セルあるいはヘッダー・レイヤーを指定することで、ピボット・テーブルの初期表示をカスタマイズできます。最初に表示されるデータの行および列を指定するには、startRowおよびstartColumn属性を使用します。最初に表示される行またはヘッダー・レイヤーを指定するには、rowHeaderStartLayerおよびcolumnHeaderStartLayer属性を使用します。ピボット・テーブルの初期表示に基づき、これらの属性設定に対しスクロールバーまたはページ・コントロールが自動的に配置されます。

25.1.2.7 永続ヘッダー・レイヤー

各行ヘッダー・レイヤーの上および各列ヘッダー・レイヤーの横に表示されるラベルが常に表示されるようにピボット・テーブルを構成できます。これは、大規模なデータ・セットの表示時に、列および行ヘッダー・ラベルをデータとともに表示し続ける場合に便利です。pivotTableコンポーネントで行および列ヘッダー・ラベルの永続表示を構成するには、layerLabelMode属性をrenderedに設定します。

25.1.2.8 大規模データ・セットの分割ビュー

大規模データ・セットを表示するピボット・テーブルを構成して、ユーザー定義のデータ分割ビューをサポートできます。分割ビューでは、ピボット・テーブルは、垂直方向、水平方向またはその両方の方向の複数のペインに分割され、表内で並んでいない行または列を並べて表示できます。リスナーが有効化されている場合、ピボット・テーブルに分割が正常に追加された後、またはピボット・テーブルから分割が正常に削除された後、リスナーに通知が送信されます。たとえば、週をスクロールする間、集計レベルの年情報を年の最後に同時に表示することが必要な場合があります。

デフォルトでは、データのビューを分割または分割解除するオプションは、ピボット・テーブルのヘッダーまたはデータ・セルのコンテキスト・メニューから使用できます。ユーザーは、列、行またはその両方を分割して、ピボット・テーブルの表示可能ペインを定義できます。各ペインに割り当てられる使用可能スペースの部分は、「分割表示」コマンドを呼び出したときのセルのスクロール位置により決まります。

列のみ分割するには、2番目のペインの最初の列にする列の列ヘッダー・セルを選択し、コンテキスト・メニューで「分割表示」を選択します。図25-20に、ピボット・テーブル・データの列のみ分割されたビューを示します。

図25-20 ピボット・テーブル・データの列のみ分割されたビュー

行のみ分割するには、2番目のペインの最初の行にする行の行ヘッダー・セルを選択し、コンテキスト・メニューで「分割表示」を選択します。図25-21に、ピボット・テーブル・データの行のみ分割されたビューを示します。

図25-21 ピボット・テーブル・データの行のみ分割されたビュー

行と列の両方を分割するには、最後のペインの最初のセルにするデータ・セルを選択し、コンテキスト・メニューで「分割表示」を選択します。図25-22に、ピボット・テーブル・データの行および列が分割されたビューを示します。

図25-22 ピボット・テーブル・データの行および列が分割されたビュー

ピボット・テーブルを分割ビューから元の構成に戻すには、例25-0に示されているように、いずれかのセルを選択し、コンテキスト・メニューで「連続表示」を選択します。

図25-23 ピボット・テーブルの「連続表示」コマンド

25.1.2.9 サイズ設定

ピボット・テーブルのデフォルト・サイズは、横300ピクセル、縦300ピクセルです。ピボット・テーブルでは、ピボット・テーブルが最初に表示されたときに使用できるスペース内で、行、列およびレイヤーのサイズを自動設定します。行、列またはレイヤーのサイズは、行セパレータ、列セパレータまたはレイヤー・セパレータを新しい位置にドラッグすることで、実行時に変更できます。行または列ヘッダーで、サイズを変更する行、列またはレイヤーと、次の行、列またはレイヤーとの間のセパレータ上にカーソルを置きます。カーソルが両方向の矢印に変わったら、行、列またはレイヤーの点線のセパレータをクリックして目的の位置にドラッグします。図25-24に、両方向の矢印および点線のサイズ変更インジケータを示します。

図25-24 ピボット・テーブルのサイズ変更インジケータ

行、列またはレイヤーのサイズを変更すると、ピボット操作を実行するまで新しいサイズが維持されます。ピボット操作後、新しいサイズはクリアされ、ピボット・テーブルの行、列およびレイヤーは元のサイズに戻ります。

ピボット操作を行わない場合、セッション中は新しいサイズのままになります。ただし、これらのサイズはMDS (メタデータ・サービス)のカスタマイズでは保存できません。

25.1.2.10 ヘッダー・セルの折返し

デフォルトでは、ヘッダー・セル・ラベル内のテキストは、ヘッダー・セルのデフォルト・サイズよりも長い場合でも折り返されません。長いヘッダー・ラベルについて、headerCellコンポーネントのwhitespace属性をnormalに設定することで、折返しを有効にできます。デフォルト値はnoWrapです。図25-10に示されているピボット・テーブルは、行ヘッダー・セルが折り返され、Protective Gearとそのドリル処理されたBlack Hawk Knee PadsおよびBlack Hawk Elbow Padsヘッダー・セルの長いテキスト・ラベルがすべて表示されています。

図25-25 ピボット・テーブルのヘッダー・セルの折返し

25.1.2.11 ADS(アクティブ・データ・サポート)

ピボット・テーブルとピボット・フィルタ・バーは、アクティブ・データ・イベントが受け取られたときにPPR(部分ページ・リフレッシュ)リクエストを送ることによりADSをサポートします。PPR応答により、ピボット・テーブルおよびピボット・フィルタ・バーの値は次のように更新されます。

- ADSイベントの結果が、1つ以上の既存のピボット・テーブル・データ・セルの値の更新の場合、値はただちに更新されます。

- ADSイベントの結果が、1つ以上の行または列の挿入または削除の場合、ピボット・テーブル全体がリフレッシュされ、変更が表示されます。

- ADSは、データ・セルの単一のスタンプ設定されたaf:outputTextコンポーネントに対してのみサポートされます。

- ピボット操作などピボット・テーブルの操作中にイベントが到着した場合、操作の完了後にイベントを適用できるようにするために、イベントはバッファに格納されます。ただし、ピボット操作でフェッチされたデータよりもイベントが古い場合は除きます。この場合、イベントは破棄されます。

アクティブ・データ・サービスの使用の詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

25.1.3 ピボット・テーブル・コンポーネントの追加機能

ピボット・テーブル・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんピボット・テーブル・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。ピボット・テーブル・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、ピボット・テーブルでヘッダー・セル、データ・セルまたはピボット・テーブル全体をリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: 有効な場合、ユーザーは実行時にピボット・テーブルの表示方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントにはデフォルトでアクセス可能です。ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントを含むアプリケーション・ページにスクリーン・リーダー・ユーザーがアクセスできるように構成できます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- スキンおよびスタイル: アプリケーションに適用するADFを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)を使用してCSSスタイル・プロパティを直接適用することにより、ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの外観をカスタマイズできます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- コンテンツ配信: コンポーネントのレンダリング直後、またはコンポーネントがレンダリングされた後の別のリクエストで、データ・ソースからデータをフェッチするように、contentDelivery属性を使用してピボット・テーブルおよびピボット・フィルタ・バーを構成できます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされたピボット・テーブルを作成できます。JDeveloperには、データ・バインディングとピボット・テーブルの構成用のウィザードがあります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「プレースホルダ・データ・コントロールを使用したページの設計」の章を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、イメージ形式、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

25.2 ピボット・テーブル・コンポーネントの使用方法

pivotTableコンポーネントを使用するには、データを定義し、ピボット・テーブルをページに追加し、JDeveloperで追加の構成を完了します。

25.2.1 ピボット・テーブルのデータ要件

行セット(フラット・ファイル)データ・コレクションを使用して、データをピボット・テーブルに提供できます。ピボット・テーブル・コンポーネントでは、データ・モデルを使用してデータが表示および操作されます。この特定のデータ・モデルはoracle.adf.view.faces.bi.model.DataModelです。

ピボット・テーブルを使用する場合、JDeveloperでvalue属性を設定する必要があります。UI優先開発を使用する場合、value属性の値を、ピボット・テーブルのデータ・モデルまたはクラスおよびマネージドBeanに格納する必要があります。

25.2.2 ピボット・テーブルの構成

ピボット・テーブル(pivotTable)コンポーネントには、2つの子コンポーネント、ヘッダー・セル(headerCell)およびデータ・セル(dataCell)があります。ピボット・フィルタ・バー(pivotFilterBar)は、ピボット・テーブルと関連付けることができる兄弟コンポーネントです。接頭辞dvt:は、各ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。

ピボット・テーブルでは、グリッド・レイアウトにデータが表示されます。このグリッド・レイアウトには、階層的にネストされた行ヘッダー・セルおよび列ヘッダー・セルの無制限のレイヤーが備わっています。図25-26に、電子機器の売上げを示すピボット・テーブルとそれに関連付けられたピボット・フィルタ・バーを示します。

図25-26 電子機器売上げピボット・テーブル

ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントは、図25-26の電子機器売上げピボット・テーブルを使用して、次の用語で定義されます。

- エッジ: ピボット・テーブル内の軸で、次のものがあります。

- 行エッジ: ピボット・テーブル本体の左から右への表示の左または右にある縦軸。図25-26では、行エッジに製品カテゴリと製品の2つのレイヤーがあり、ピボット・テーブルの各行は、特定のカテゴリと特定の製品の組合せを表しています。

- 列エッジ: ピボット・テーブルの本体の上にある横軸。図25-26では、列エッジには、尺度と米国の州の2つのレイヤーがあり、ピボット・テーブルの各列は、特定の尺度の値と特定の地理的位置(米国の州)の組合せを表しています。

- ページ・エッジ: ピボット・フィルタ・バーによって表されるエッジで、そのレイヤーは行および列エッジのレイヤーによりフィルタ処理やピボット処理ができます。

- レイヤー: 1つのエッジに表示される、ネストされた属性。図25-26では、列エッジに尺度と地理的位置(売上げと米国の州)の2つのレイヤーが表示されています。行エッジには、カテゴリと製品(製品カテゴリと製品)の2つのレイヤーが表示されています。

- ヘッダー・セル: 行または列に表示されているデータを識別するラベル。行ヘッダー・セルは行エッジ上に、列ヘッダー・セルは列エッジ上に表示されます。サンプルでは、ヘッダー・セルにCell Phones、iPod Speakers、SalesおよびColoradoが表示されています。

- データ・セル: ヘッダー情報ではなく、データ値を含むピボット・テーブル内のセル。サンプルでは、最初のデータ・セルに、1,499.99という値が含まれています。

- QDR (修飾データ参照): 行、列または個々のセルに対する完全修飾データ参照。たとえば、図25-26では、ピボット・テーブル内の最初のセルのQDRに次の情報が含まれる必要があります。

- カテゴリ=Audio Video

- 製品=iPod Nano 1Gb

- 尺度: Sales

- 地理=Colorado

同様に、ピボット・テーブルの最初の行のQDRは、「iPod Nano 1Gb」ヘッダー・セルのQDRでもあり、次の情報が含まれています。

- カテゴリ=Audio Video

- 製品=iPod Nano 1Gb

最後に、「Sales」ヘッダー・セルのQDRには、次の情報が含まれています。

- 尺度: Sales

25.2.3 ページへのピボット・テーブルの追加方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用してピボット・テーブルをページに追加します。ページにピボット・テーブルが追加されると、「プロパティ」ウィンドウを使用して、データ値を指定し、ピボット・テーブルに追加の表示属性を構成できます。

「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図25-27に、ピボット・テーブル・コンポーネントのvalue属性のドロップダウン・メニューを示します。

図25-27 ピボット・テーブル・コンポーネントの「値」属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してピボット・テーブルを作成でき、バインドが自動的に行われます。JDeveloperには、データ・バインディングとピボット・テーブルの構成用のウィザードがあります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの作成」の章を参照してください。

始める前に:

ピボット・テーブルの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、25.2.2項「ピボット・テーブルの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、25.1.3項「ピボット・テーブル・コンポーネントの追加機能」を参照してください。

ページにピボット・テーブルを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「ピボット・テーブル」パネルからピボット・テーブルをページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、ピボット・テーブルの属性を確認します。ヘルプ・ボタンを使用して、pivotTableコンポーネントの完全なタグ・ドキュメントを表示します。

3. 「データ」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Value: ピボット・テーブルをバインドするオブジェクトのEL式を指定します。oracle.adf.view.faces.bi.model.DataModelのインスタンスを使用可能です。

- VarおよびvarStatus: スタンプされたdataCellコンポーネントおよびheaderCellコンポーネントのセル・データにアクセスする変数の指定に使用します。詳細は、25.3.1項「varおよびvarStatusプロパティの使用方法」を参照してください。

4. 「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- LayerLabelMode: 各行ヘッダー・レイヤーの上および各列ヘッダー・レイヤーの横に表示されるラベルが常に表示されるようにピボット・テーブルを構成する場合に使用します。pivotTableコンポーネントで行および列ヘッダー・ラベルの永続表示を構成するには、属性をrenderedに設定します。デフォルト値はhiddenです。

- PivotLabelVisible: ピボット・ハンドル上にラベルを表示するかどうかを指定します。デフォルト値はtrueです。

- PreferredColumnHeaderHeightおよびPreferredRowHeaderWidth: 列ヘッダーの高さおよび行ヘッダーの幅をパーセントで指定する場合(25%、33.3%)に、必要に応じて使用します。

- Sizing: ピボット・テーブルのサイズを幅と高さでどのように決めるかの指定に使用します。デフォルト値はfixedで、このとき、親コンポーネントにより子が拡大される場合には、ピボット・テーブルは親に基づきサイズ設定され、また親コンポーネントにより子が拡大されない場合には、ピボット・テーブルは、デフォルト・スキン、スタイル・クラスまたはインライン・スタイルの幅および高さのCSSプロパティに基づきサイズ設定されます。
この属性はautoに設定することもでき、このとき、親が子を拡大する場合には、ピボット・テーブルはfixed属性と同じ方法でサイズ設定されます。親が子を拡大しない場合で、コンテンツがピボット・テーブルよりも小さい場合には、ピボット・テーブルはそのコンテンツのサイズに縮小されます。

幅=コンテンツの幅とデフォルトの幅のうち小さい方、および

高さ=コンテンツの高さとデフォルトの高さのうち小さい方

ここで、デフォルトの幅およびデフォルトの高さは、デフォルト・スキン、スタイル・クラスまたはインライン・スタイルの幅および高さのCSSプロパティです。

注意:

この属性をautoに設定すると、ピボット・テーブルのフレームは最初にピボット・テーブルのデフォルト・サイズで表示された後、コンテンツのサイズに合せて再調整されます。そのため、ピボット・テーブルを表示するページは、最初に表示された後、レイアウトが変更される場合があります。

- StatusBarRendered: ピボット・テーブルのステータス・バーを表示するかどうかの指定に使用します。デフォルト値はfalseです。

- EmptyText: 空のピボット・テーブルを説明するために使用するテキストを入力します。このテキストがHTMLタグで囲まれている場合は、書式設定が行われます。

- Summary: ピボット・テーブルの目的およびスクリーン・リーダーで使用する場合の構造の説明を入力します。

- DataFormatおよびHeaderFormat: ヘッダー・セルおよびデータ・セルのスタンプを宣言によりスタイル設定する非推奨のストラテジですが、これらの属性を使用して、データ・セルおよびヘッダー・セルのコンテンツをカスタマイズする書式設定ルールを作成できます。詳細は、25.6項「CellFormatによるピボット・テーブルのセルのコンテンツの書式設定」を参照してください。

5. 「動作」セクションを開きます。このセクションを使用して、次の属性を設定します。

- PivotEnabled: エンド・ユーザーたピボット・テーブル内でデータのビューを再配置できるかどうかを指定します。デフォルト値はtrueです。

- ColumnFetchSizeおよびRowFetchSize: データ・フェッチ・ブロック内の列および行数の指定に使用します。列のデフォルト値は10、行のデフォルト値は25です。これらは変更可能です。

- ContentDelivery: データ・ソースからピボット・テーブルへのコンテンツの配信方法を指定する場合に使用します。デフォルトでは、データが使用可能になったらただちにピボット・テーブルにデータが配信されます(whenAvailable)。また、レンダリングに基づきただちに配信すること(immediate)、またはコンポーネントのシェルがレンダリングされた後の遅延フェッチに基づき配信すること(lazy)ができます。ピボット・テーブルへのコンテンツの配信の詳細は、22.2.1項「コンテンツの配信」を参照してください。

6. 「構造」ウィンドウで、「dvt:pivotTable」ノードを右クリックし、「ピボット・テーブルの中に挿入」→「ヘッダー・セル」を選択します。

7. 「構造」ウィンドウで、「dvt:pivotTable」ノードを右クリックし、「ピボット・テーブルの中に挿入」→「データ・セル」を選択します。

25.2.4 ピボット・テーブルの表示サイズおよびスタイルの構成

inlineStyleまたはstyleClass属性を使用して、ピボット・テーブル、ピボット・フィルタ・バー、ヘッダー・セルおよびデータ・セルのサイズおよびスタイルを構成できます。どちらの属性も、dvt:pivotTable、dvt:pivotFilterBar、dvt:headerCellまたはdvt:dataCellコンポーネントの「プロパティ」ウィンドウの「スタイル」セクションで使用できます。これらの属性を使用して、フォント、境界線、およびバックグラウンド要素など、スタイルに関する機能をカスタマイズできます。

スタイル属性を使用してヘッダー・セルおよびデータ・セル子コンポーネントを構成することもできます。例25-1に、データ・セルaf:outputTextおよびaf:inputTextのinlineStyleおよびcontentStyle属性を使用したカスタムCSSスタイルを示します。

例25-1 データ・セルのCSSスタイルのサンプル・コード

<dvt:pivotTable id="goodPT"
value="#{richPivotTableModel.dataModel}"
var="cellData"
varStatus="cellStatus">

<dvt:dataCell id="dc1">
<af:switcher id="sw1" facetName="#{richPivotTableModel.stampFacet}">
<f:facet name="outputText">
<af:outputText id="ot1" value="#{cellData.dataValue}"
inlineStyle="#{myBean.textStyle}"/>
</f:facet>
<f:facet name="inputText">
<af:inputText id="ot2" value="#{cellData.dataValue}"
contentStyle="#{myBean.textStyle}" />
</f:facet>
</af:switcher>
</dvt:dataCell>
</dvt:pivotTable>

ピボット・テーブルおよびピボット・フィルタ・バーは、データ・セル、ヘッダー・セル、データ・ラベル、ヘッダー・ラベル、ピボット・アイコンおよびソート・アイコンの表示の多くの側面をカスタマイズするためのスキニングもサポートしています。

ピボット・テーブルのスキニング・キーの完全なリストについては、Oracle Fusion Middleware Oracle ADF Facesスキン・セレクタ・データ視覚化ツール・タグ・リファレンスを参照してください。スキニングとスタイルを使用したアプリケーションのカスタマイズの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ピボット・テーブルを含むページには、サイズまたはスタイルを変更する機能に制限がある場合があります。ページ・レイアウトの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

25.2.5 ページにピボット・テーブルを追加する場合の処理

「コンポーネント」ウィンドウを使用してピボット・テーブル・コンポーネントをJSFページに挿入すると、基本のピボット・テーブル・タグが次のようにソース・コードに追加されます。

<dvt:pivotTable id="pt1"/>

これをまだ行っていない場合、「コンポーネント」ウィンドウを使用してヘッダー・セルおよびデータ・セルを挿入できます。スタンプを通じてセルのコンテンツを構成します。詳細は、25.3項「ヘッダーおよびデータ・セルのスタンプの構成」を参照してください。

「ピボット・テーブルの作成」ウィザードでは、ピボット・テーブルのデータ・バインディングおよび構成のための宣言をサポートしています。ウィザードのページは次のことができます。

- ピボット・テーブルの初期レイアウトの指定

- ピボット・フィルタ・バーの関連付けおよび構成

- データ・レイヤーの代替ラベルを指定

- ドリルの挿入またはフィルタの構成

- データ値の集計の定義

- カテゴリおよびデータのソートの構成

- ピボット・テーブルのライブ・データ・プレビューの表示

詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの作成」の章を参照してください。

25.2.6 大規模なデータ・セットの表示について

ADF Faces Webアプリケーションを開発している場合、ピボット・テーブルではデフォルトで、フェッチしているデータのサイズを超えるデータを表示するために垂直または水平のスクロールバーが使用されます。また、図25-19に示されているように、ユーザーが特定の行のページにジャンプできる垂直または水平ページ・コントロールを構成できます。ページ・コントロールを構成するには、pivotTableコンポーネントのscrollPolicy属性をpageに設定します。

デフォルトでは、ピボット・テーブルがモバイル・デバイスでレンダリングされる場合、フェッチされるデータのサイズを超える行を表示するためにページ・コントロールが使用されます。モバイル・デバイスにピボット・テーブルを表示するには、以下を行う必要があります。

- ピボット・テーブル・コンポーネントをフロー・コンテナ(つまり、子を拡大しないコンポーネント)の中に配置します。フロー・コンテナ・コンポーネントの詳細は、第9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- scrollPolicy属性をauto(ページがデスクトップ・デバイスでも実行される場合)、またはpage(ページがモバイル・デバイスのみで実行される場合)に設定します。

ピボット・テーブルがフロー・コンテナの中にない場合、または属性が正しく設定されていない場合は、ページではなくスクロールバーが表示されます。

25.2.7 タッチ装置でのピボット・テーブルに関する必知事項

ADF Facesフレームワークは、Safariなどのモバイル・ブラウザで実行するように最適化されています。フレームワークは、タッチ装置上のモバイル・ブラウザがページをリクエストすると認識し、モバイル・デバイスに適用可能なJavaScriptとピア・コードのみを提供します。ただし、標準ADF Faces Webアプリケーションはモバイル・ブラウザで実行されますが、ユーザーの対話が異なり、スクリーン・サイズが制限されるため、アプリケーションをモバイル・ブラウザで実行する必要がある場合、タッチ装置に固有のバージョンのページを作成する必要があります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

25.3 ヘッダーおよびデータ・セルのスタンプの構成

ピボット・テーブル・コンポーネントの直下の子は、headerCellまたはdataCellコンポーネントのいずれかであることが必要です。ピボット・テーブルには、1つのheaderCellコンポーネントと1つのdataCellコンポーネントを含めることができます。これらのコンポーネントにより、スタンプによるセル・コンテンツのカスタマイズが可能になります。スタンプを使用すると、ピボット・テーブルではヘッダー・セルまたはデータ・セルごとに子コンポーネントが作成されません。正確に言うと、コンポーネントのコンテンツは、セルごとに1回、繰り返しレンダリング(スタンプ)されます。

ヘッダー・セルまたはデータ・セルがスタンプされるたびに、現在のセルの値がvarプロパティにコピーされ、そのセルの追加データはvarStatusプロパティにコピーされます。これらのプロパティには、ヘッダーまたはデータ・セル・コンポーネント内のEL式でアクセスでき、たとえば、スタンプされたaf:outputTextコンポーネントにセル値を渡します。ピボット・テーブルのレンダリングが完了したら、varおよびvarStatusプロパティは削除されるか前の値に戻ります。

25.3.1 varおよびvarStatusプロパティの使用方法

ピボット・テーブルのvarおよびvarStatusプロパティは、スタンプされたdataCellおよびheaderCellコンポーネント内のセル・データにアクセスするために使用されます。varプロパティは、ピボット・テーブルのデータ・セル・スタンプを参照するために使用されるEL式変数を指定します。スタンプされたdataCellまたはheaderCellコンポーネントでは、varプロパティを参照し、メタデータ・キーワードを後に続ける必要があります。

表25-1に、行セット・データ・モデルのデータ・セル用にサポートされているメタデータ・キーワードを示します。

表25-1 データ・セル用にサポートされているメタデータ・キーワード

キーワード

説明

dataValue

最も頻繁に役立つキーワード。現在のセルにデータ値Objectを返します。オブジェクトのアクセス可能なフィールドをEL式により指定するために、dataValue.fieldNameの設定を使用します。

dataCubeMaxおよびdataCubeMin

キューブ内の値全体にわたるセルの尺度に、最大および最小のそれぞれの数値を返します。

dataIsTotal

このセルが集計の場合、ブール値trueを返します。

dataAggregates

セルが集計の場合、列のList<String,Object>、および特定のセルの集計を構成するセル(非集計)を表す値ペアを返します。

aggregateCollection

セルが集計の場合、列のList<String,Object>、およびセルの集計値を構成するキューブ内の値ペアを返します。aggregateCollectionはポストキューブ、dataAggregatesはポストキューブでないことに注意してください。

dataRow

元の行マッピングのデータ・オブジェクトに、属性名からMap<String,Object>を返します。dataRow.foo (fooは行セット属性(列)名の1つ)のように使用します。

dataTypeColumn

値の取得先の行セット属性の名前を表す文字列を返します。

dataRowKey

行データ・モデルのADFモデル行キーを返します。

dataKeyPath

ADFモデル・キー・パス・オブジェクトを返します。

表25-2に、行セット・データ・モデルのヘッダー・セル用にサポートされているメタデータ・キーワードを示します。

表25-2 ヘッダー・セル用にサポートされているメタデータ・キーワード

キーワード

説明

dataValue

最も頻繁に役立つキーワード。現在のセルにデータ値Objectを返します。オブジェクトのアクセス可能なフィールドをEL式により指定するために、dataValue.fieldNameの設定を使用します。

value

ヘッダー・セルの文字列値を返します。キューブ・データ・モデルでも使用できます。

label

ヘッダー・セルの文字列ラベルを返します。キューブ・データ・モデルでも使用できます。

isTotal

ヘッダー・セルが集計を表す場合、ブール値trueを返します。

drillState

現在のヘッダー・セルのドリルの状態を表す整数値を返します(該当する場合)。0はドリル不可能、1はドリル可能、2はドリル済を示します。キューブ・データ・モデルでも使用できます。

memberMetadataColumn

ヘッダー・セルの文字列属性列を返します。

layerName

ヘッダー・セルを含むレイヤーの名前を表す文字列を返します。

layerLabel

このヘッダー・セルを含むレイヤーのラベル(ある場合)を表す文字列を返します。layerNameに戻る可能性があります。

オプションのvarStatusプロパティは、コンポーネントの状態に関するコンテキスト情報を提供するために使用されるEL式変数を指定します。スタンプされたdataCellまたはheaderCellコンポーネントでは、varStatusプロパティを参照し、次のいずれかを後に続ける必要があります。

- members: dataCellコンポーネントに対してのみ有効です。現在のデータ・セルと同じ行または列に対応するヘッダー・セルへのアクセスを提供します。

- model: このコンポーネントのDataModelを返します。

- cellIndex: このコンポーネントのセル索引を返します。

- cellKey: このコンポーネントのセル・キーを返します。

例25-2に、varおよびvarStatusを使用して、スタンプされたデータ・セルからデータにアクセスするためのサンプル・コードを示します。この例では、varおよびvarStatusを使用して、ヘッダー・セルのスタンプに基づきピボット・テーブルを書式設定する方法も示します。

例25-2 varおよびvarStatusプロパティを使用するためのサンプル・コード

<dvt:pivotTable
id="pivotTable3"
value="#{pivotTableMemberFormatting.dataModel}"
var="cellData"
varStatus="cellStatus">
<dvt:headerCell>
<af:switcher
facetname="O___b_cellData_layerName__b__"
defaultFacet="Other">
<f:facet name="Product">
<af:outputText id="ot1"
value="#{cellData.dataValue}"
inlineStyle="color:#{(cellData.dataValue == 'Canoes' ?
'red' : 'blue')};"/>
</f:facet>
<f:facet name="Other">
<af:outputText id="ot2" value="#{cellData.dataValue}"/>
</f:facet>
</af:switcher>
</dvt:headerCell>

<dvt:dataCell>
<af:outputText id="ot3" value="#{cellData.dataValue}"
inlineStyle="color:#{(cellStatus.members.Product.dataValue ==
'Canoes' ? 'red' : 'blue')};"/>
</dvt:dataCell>
</dvt:pivotTable>

サンプル・コードでは、各データ・セル値プロパティを使用する場合の構文を次のように説明しています。

- var: [varプロパティ].[データ・セル・メタデータ・キーワード]
サンプル・コードでは、af:outputTextの値は、現在のセルの値の#{cellData.dataValue}に設定されています。

- varStatus: [varStatusプロパティ].[メンバー].[レイヤー名].[ヘッダー・セルのメタデータのキーワード]
データ・セル・コンポーネント値は、ピボット・テーブルのvarStatus (cellStatus)とその後に続くmembers(現在のデータ・セルと同じ行または列に対応したヘッダー・セルにアクセスするため)、目的のヘッダー・セルを含むレイヤー名(Product)、ヘッダー・セル・メタデータ・キーワードdataValueを参照します。

図25-28に、サンプル・コードから生成されるピボット・テーブルを示します。

図25-28 ヘッダー・セルのスタンプに基づき書式設定されたピボット・テーブル

varおよびvarStatusを使用して、ピボット・テーブルにスパークチャートおよびゲージをスタンプすることもできます。例25-3に、データ・セルにスタンプされたスパークチャートを使用するサンプル・コードを示します。結果のピボット・テーブルは、図25-2に示しています。

例25-3 データ・セルにスパークチャートをスタンプする場合のサンプル・コード

<dvt:pivotTable id="pivotTable1"
value="#{pivotTableSparkChart.dataModel}"
var="cellData"
varStatus="cellStatus">
<dvt:dataCell>
<af:switcher id="s2"
facetname="O___b_cellData_dataIsTotal__b__"
defaultFacet="false">
<f:facet name="true">
<dvt:sparkChart id="sc1" shortDesc="Spark Chart"
highMarkerColor="#008200"
lowMarkerColor="#ff0000">
<af:iterator id="i1"
value="#{cellData.aggregateCollection}"
var="sparks" >
<dvt:sparkItem id="si1"
value="#{sparks.dataValue}"/>
</af:iterator>
</dvt:sparkChart>
</f:facet>
<f:facet name="false">
<af:outputText id="ot1" value="#{cellData.dataValue}"/>
</f:facet>
</af:switcher>
</dvt:dataCell>

<dvt:headerCell>
<af:switcher id="s3"
facetname="O___b_cellData_isTotal__b__"
defaultFacet="false">
<f:facet name="true">
<af:outputText id="ot2" value="Trend"/>
</f:facet>
<f:facet name="false">
<af:outputText id="ot3" value="#{cellData.dataValue}"/>
</f:facet>
</af:switcher>
</dvt:headerCell>
</dvt:pivotTable>

例25-4に、データ・セルでゲージを使用する場合のサンプル・コードを示します。結果のピボット・テーブルは、図25-3に表示されています。

例25-4 データ・セルにゲージをスタンプする場合のサンプル・コード

<dvt:pivotTable
id="pivotTable2"
value="#{pivotTableGauge.dataModel}"
var="cellData"
varStatus="cellStatus">
<dvt:dataCell>
<dvt:gauge id="g1" shortDesc="Gauge"
imageWidth="80" imageHeight="80" imageFormat="PNG_STAMPED"
value="#{cellData.dataValue}"
minValue="#{cellData.dataCubeMin}"
maxValue="#{cellData.dataCubeMax}"/>
</dvt:dataCell>
</dvt:pivotTable>

25.3.2 ヘッダーおよびデータ・セルのスタンプの構成方法

ヘッダー・セルまたはデータ・セルでは、一部のタイプの子コンポーネントのみがサポートされます。たとえば、各ヘッダー・セルには読取り専用コンポーネントを含めることができます。アクティビティのないすべてのコンポーネント、およびEditableValueHolderまたはActionSourceインタフェースを実装する大半のコンポーネントなど、特定の読取り専用または入力のコンポーネントを各データ・セルに含めることができます。

ヘッダー・セルおよびデータ・セルに含まれるのは、1つの子コンポーネントのみです。複数の子が必要な場合は、別のコンポーネントにラップする必要があります。レイアウトが必要ない場合は、af:groupを使用することができ、レイアウトを追加せずに単に子をレンダリングするので、結果的に軽量になります。レイアウトが必要な場合は、かわりにaf:panelGroupLayoutのようなレイアウト・コンポーネントを使用できます。詳細は、9.13項「関連する項目のグループ化」を参照してください。

データ・セルの編集は、dataCellの子コンポーネントとして入力コンポーネントを使用することによって有効になります。実行時に、ピボット・テーブルのセルをクリックすることで編集するセルを開くことができます。詳細は、25.1.2.3項「データ・セルの編集」を参照してください。

例25-5に、af:switcherを使用してヘッダー・セルのスタンプ設定を構成し、レイヤー名によりスタンプされるコンポーネントのタイプを変更する(つまり、地理、販路などの異なるコンテンツ)サンプル・コードを示します。例では、headerCellの子として使用できるコンポーネントも説明しています。

例25-5 ヘッダー・セルのスタンプのサンプル・コード

<dvt:pivotTable id="goodPT"
inlineStyle="width:100%;height:600px;"
binding="#{editor.component}"
contentDelivery="immediate"
value="#{pivotTableHeaderCellDemo.dataModel}"
headerFormat="#{pivotTableHeaderCellDemo.getHeaderFormat}"
dataFormat="#{pivotTableHeaderCellDemo.getDataFormat}"
var="cellData"
varStatus="cellStatus"
summary="pivot table">
<dvt:headerCell id="goodHC>
<af:switcher id="sw" facetName="#{cellData.layerName}" defaultFacet="Other">
<f:facet name="Geography">
<af:group id="g1">
<af:icon id="idicon11" name="info" shortDesc="Icon" />
<af:outputText  value="#{cellData.dataValue}" id="ot11"
shortDesc="#{cellData.dataValue}" />
</af:group>
</f:facet>
<f:facet name="Channel">
<af:group id="g2">
<af:panelGroupLayout id="pgl2" layout="vertical">
<af:link shortDesc="Sample Link"
icon="/images/pivotTableCSVDemo/smily-normal.gif"
hoverIcon="/images/pivotTableCSVDemo/smily-glasses.gif"
id="cil1"/>
<af:outputText  value="#{cellData.dataValue}" id="ot1" />
</af:group>
<af:button text="Go to Tag Guide page" immediate="true"
action="guide" id="cb1"/>
</af:panelGroupLayout>
</f:facet>
<f:facet name="Product">
<af:panelGroupLayout id="pgl3" layout="vertical">
<af:outputText value="#{cellData.dataValue}" id="ot12" />
<af:button text="Go to Tag Guide page" immediate="true"
action="guide" id="cb2"/>
</af:panelGroupLayout>
</f:facet>
<f:facet name="Other">
<af:link text="#{cellData.dataValue}"
shortDesc="#{cellData.dataValue}" immediate="true"
action="guide" id="idlink11"/>
</f:facet>
</af:switcher>
</dvt:headerCell>
</dvt:pivotTable>

図25-29に、サンプル・コードの結果のピボット・テーブルを示します。

図25-29 ピボット・テーブルのヘッダー・セルのスタンプ

例25-6に、af:switcherを使用してヘッダー・セルのスタンプを構成し、尺度によりスタンプされるコンポーネントのタイプを変更する(つまり、売上げ、重量などの異なるコンテンツ)サンプル・コードを示します。例では、dataCellの子として使用できるコンポーネントも説明しています。

例25-6 データ・セルのスタンプ設定のサンプル・コード

<dvt:pivotTable id="goodPT" var="cellData" varStatus="cellStatus">
<dvt:dataCell>
<af:switcher id="sw" facetName="#{cellStatus.members.MeasDim.value}"
defaultFacet="Other">
<f:facet name="Sales">
<af:inputText id="idinputtext1" value="#{cellData.dataValue}"   />
</f:facet>
<f:facet name="Units">
<af:inputText id="idinputtext2" value="#{cellData.dataValue}"   >
<af:validateLength maximum="6" minimum="2" />
</af:inputText>
</f:facet>
<f:facet name="Weight">
<af:outputText id="idoutputtext1" value="#{cellData.dataValue}" />
</f:facet>
<f:facet name="Color">
<af:selectOneChoice id="idselectonechoice"
value="#{cellData.dataValue}" label="Color">
<af:selectItem label="red" value="red" shortDesc="shortDesc sample"/>
<af:selectItem label="coffee" value="coffee"
shortDesc="Sample shortDesc text"/>
<af:selectItem label="milk" value="milk"
shortDesc="Another shortDesc sample"/>
</af:selectOneChoice>
</f:facet>
<f:facet name="Available">
<af:selectBooleanCheckbox id="idselectbooleancheckbox"
label="Availability" text="Item Available"
autoSubmit="true"
value="#{cellData.dataValue}"/>
</f:facet>
<f:facet name="Supply Date">
<af:inputDate id="idinputdate1" value="#{cellData.dataValue}"
label="Change Date:" simple="true" >
<af:validateDateTimeRange maximum="2020-12-31" minimum="1980-12-31" />
</af:inputDate>
</f:facet>
<f:facet name="Link">
<af:link text="#{cellData.dataValue}" immediate="true"
action="guide" id="idlink"/>
</f:facet>
<f:facet name="Size">
<af:inputComboboxListOfValues label="Size"id="idInputComboboxListOfValues"
value="#{cellData.dataValue}"
searchDesc="Search Size"
model="#{pivotTableEditBean.listOfValuesModel}"
columns="3"   />
</f:facet>
<f:facet name="Other">
<af:outputText id="idoutputtext2" value="#{cellData.dataValue}"   />
</f:facet>
</af:switcher>
</dvt:dataCell>
</dvt:pivotTable>

図25-30に、サンプル・コードの結果のピボット・テーブルを示します。

図25-30 ピボット・テーブルのデータ・セルのスタンプ

始める前に:

ピボット・テーブルの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、25.2.2項「ピボット・テーブルの構成」を参照してください。

ページにすでにピボット・テーブルが存在している必要があります。ない場合は、この章の指示に従ってピボット・テーブルを作成します。詳細は、25.2.3項「ページへのピボット・テーブルの追加方法」を参照してください。

ヘッダーまたはデータ・セルのスタンプの追加および構成の手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「ヘッダー・セル」または「データ・セル」をビジュアル・エディタのピボット・テーブルにドラッグ・アンド・ドロップします。

2. 「構造」ウィンドウで「dvt:headerCell」または「dvt:dataCell」を右クリックし、「ヘッダー・セルの中に挿入」または「データ・セルの中に挿入」→ADFデータ視覚化コンポーネントまたは「ADF Faces」を選択します。

3. 「アイテムの挿入」ダイアログで、ヘッダーまたはデータ・セルにスタンプするコンポーネントを選択します。

4. 「構造」ウィンドウで、挿入したコンポーネントを選択し、「プロパティ」ウィンドウでコンポーネントの属性を設定します。

25.4 ピボット・フィルタ・バーの使用方法

ピボット・フィルタ・バーを追加することにより、ピボット・テーブルでのデータ・フィルタ処理能力を強化できます。ピボット・テーブルの行エッジまたは列エッジですでに表示されなくなったゼロ以上のデータのレイヤーは、ページ・エッジでは表示されます。図25-31に、ピボット・テーブルに表示されるデータのフィルタ処理に使用可能な四半期および月のレイヤーを含むピボット・フィルタ・バーを示します。

図25-31 データ・レイヤー・フィルタを持つピボット・フィルタ・バー

行、列またはページ・エッジ間でレイヤーをピボットすることにより、ピボット・テーブルでのデータの表示を変更することもできます。目的に応じてエッジ間でレイヤーをドラッグするには、ピボット・ハンドルを使用します。図25-32に、Channelデータ・レイヤーをページ・エッジに対してピボットして変更されたピボット・テーブルとピボット・フィルタ・バーを示します。

図25-32 ピボット後のピボット・テーブルおよびピボット・フィルタ・バー

inlineStyle属性、styleClass属性およびスキニング・キーを使用して、ピボット・フィルタ・バーのスタイルを設定できます。詳細は、25.2.4項「ピボット・テーブルの表示サイズおよびスタイルの構成」を参照してください。

25.4.1 ピボット・テーブルでのピボット・フィルタ・バーの使用方法

データ・モデルと関連プロパティが、ピボット・フィルタ・バー・コンポーネントpivotFilterBarとピボット・テーブル・コンポーネントpivotTableの両方と連携するように構成することで、後者のコンポーネントと連携する前者のコンポーネントを使用できます。例25-7に、ピボット・フィルタ・バーをピボット・テーブルと関連付ける場合のサンプル・コードを示します。

例25-7 ピボット・フィルタ・バーのサンプル・コード

<dvt:pivotFilterBar id="pf1" value="#{binding.pt.pivotFilterBarModel}"
modelName="pt1Model"/>
<dvt:pivotTable id="pt1" value="#{binding.pt.dataModel}"  modelName="pt1Model"
partialTriggers="pf1"/>

ピボット・フィルタ・バーは、次のどの方法でもピボット・テーブルに関連付けることができます。

- データ・コントロール・パネルを使用してピボット・テーブルを作成します。
データ・コントロール・パネルからデータ・コレクションをドラッグして、ページ上にピボット・テーブルを作成する場合、「ピボット・テーブルの作成」ウィザードの「表示属性の選択」ページで、ピボット・テーブルと関連付けるピボット・フィルタ・バーを作成するためのオプションが表示されます。ページ・エッジでデータ・レイヤーを表すゼロ以上の属性を指定することを選択できます。データ・モデルおよび関連付けられたプロパティは自動的に構成されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたピボット・テーブルの作成に関する項を参照してください。

- データにバインドされたピボット・テーブルにピボット・フィルタ・バーを追加します。
「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「ピボット・テーブル」パネルから、データ・コレクションにバインドされているpivotTable要素の隣のpivotFilterBar要素をドラッグでき、データ・バインディングが自動的に行われます。

- データにバインドされていないピボット・テーブルにピボット・フィルタ・バーを追加します。
「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「ピボット・テーブル」パネルから、データ・コレクションにバインドされていないpivotTable要素の隣のpivotFilterBar要素をドラッグできます。この場合、ピボット・フィルタ・バーがピボット・テーブルと連係するように、データ・モデルと関連プロパティを構成する必要があります。

25.4.2 グラフでのピボット・フィルタ・バーの使用方法

ピボット・フィルタ・バーを使用して、グラフ内のデータのグラフィカル表示をフィルタ処理できます。たとえば、図25-6に示されているように、ピボット・テーブルとグラフの両方に表示されている四半期の売上げデータのフィルタ処理されたビューを表示できます。

ピボット・フィルタ・バーをトリガーとして、ピボット・テーブルおよびグラフをターゲットとして構成するには、部分ページ・レンダリング(PPR)を使用します。PPRがトリガーされると、ターゲットとして構成されているコンポーネントが再レンダリングされます。コンポーネントは、partialTriggers属性をトリガー・コンポーネントの相対IDに設定することで、ターゲットとして構成します。相対IDの詳細は、4.8項「ページでのクライアント・コンポーネントの検索」を参照してください。PPRの詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

例25-8に、図25-6に示されているように、ピボット・テーブルおよびグラフとピボット・フィルタ・バーを使用するためのサンプル・コードを示します。

例25-8 ピボット・フィルタ・バーpartialTriggersのサンプル・コード

<dvt:pivotFilterBar id="pfb1" binding="#{editor.component}"
value="#{pivotFilterBar.queryDescriptor}" modelName="model1"
styleClass="AFStretchWidth"/>
<af:panelGroupLayout layout="horizontal" id="pgl2">
<f:facet name="separator" >
<af:separator id="s2"/>
</f:facet>
<af:spacer width="25px" id="s3"/>
<dvt:pivotTable id="pt1" inlineStyle="width:400px" partialTriggers="::pfb1"
value="#{pivotFilterBar.dataModel}" modelName="model1"
summary="Quarterly Sales Pivot Table"/>
<af:spacer width="50px" id="s4"/>
<dvt:barGraph id="bar1" partialTriggers="::pfb1 ::pt1"
value="#{pivotFilterBar.dataModel}" shortDesc="Quarterly Sales
Bar Graph"/>
</af:panelGroupLayout>

25.5 ピボット・テーブルへの相互作用の追加

ピボット・テーブルおよびピボット・フィルタ・バーは、選択、スプレッドシートへのエクスポート、印刷可能モードでの表示などのユーザー操作をサポートしています。

25.5.1 ピボット・テーブルでの選択の使用方法

ピボット・テーブルでの選択により、ユーザーはピボット・テーブルで複数のセルを選択できます。行ヘッダー、列ヘッダーまたはデータ・セルを含めて3つの領域のいずれか1つのみを一度に選択できます。

現在選択されているセルに基づいて、アプリケーションはコンテキスト・メニューのカスタマイズされたコンテンツの表示などの機能を実装できます。例25-9に、現在選択されているヘッダー・セルを取得するためのサンプル・コードを示します。

例25-9 選択されているヘッダー・セルを取得するためのサンプル・コード

UIPivotTable pt = getPivotTable()
if (pt == null)
return null;
HeaderCellSelectionSet headerCells = null;
if (pt.getSelection().getColumnHeaderCells().size() > 0) {
headerCells = pt.getSelection().getColumnHeaderCells();
} else if (pt.getSelection().getRowHeaderCells().size() > 0) {
headerCells = pt.getSelection().getRowHeaderCells();
}

実行時に、データ・セルを選択すると、図25-11に示されているように、そのセルが強調表示されます。

図25-33 選択されたデータ・セル

25.5.2 部分ページ・レンダリングの使用方法

部分ページ・レンダリング(PPR)により、ピボット・テーブル、データ・セルおよびヘッダー・セルを更新できます。たとえば、チェックボックスによりトリガーされた場合、ピボット・テーブルに合計を表示できます。PPRでは、ページ上の個々のコンポーネントが再レンダリングされ、ページ全体をリフレッシュする必要がありません。PPRの詳細は、第8章「部分ページ・レンダリングについて」を参照してください。

注意:

デフォルトでは、ADFピボット・テーブルで自動PPRがサポートされ、バック・ビジネス・ロジックの結果として値が変更されるコンポーネントが自動的に再レンダリングされます。アプリケーションでFusionテクノロジ・スタックを使用する場合、任意のページで自動部分ページ・レンダリング機能を有効にできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の部分ページ・レンダリングとイテレータ・バインディングに関する必知事項を参照してください。

別のコンポーネントで発生したイベントに基づいてコンポーネントを再レンダリングするには、どのコンポーネントがトリガーかを宣言する必要があります。partialTriggers属性を使用してピボット・テーブルの部分更新をトリガーするコンポーネントのIDのリストを提供します。ピボット・テーブルはトリガー・コンポーネントをリスニングし、いずれかのトリガー・コンポーネントがなんらかの更新を発生させるイベントを受信すると、ピボット・テーブルも更新されます。

例25-10に、チェック・ボックスがトリガーされたときに、合計を表示することによってピボット・テーブルを更新するサンプル・コードを示します。トリガー・コンポーネントはIDをpartialTriggers値として使用します。

例25-10 ピボット・テーブルの部分更新

<dvt:pivotTable id="goodPT"
value="#{richPivotTableModel.dataModel}"
partialTriggers="showTotals"/>

<af:selectBooleanCheckbox id="showTotals" autoSubmit="true" label="Show Totals"
value="#{richPivotTableModel.totalsEnabled}"/>

25.5.3 ピボット・テーブルからのエクスポート

ピボット・テーブルからMicrosoft Excelスプレッドシートにデータをエクスポートできます。ボタンやリンクなどのアクション・ソースを作成し、exportPivotTableDataコンポーネントを追加して、エクスポートするデータに関連付けます。ピボット・テーブル全体がエクスポートされるように、またはユーザーが選択した行、列またはデータ・セルのみがエクスポートされるようにコンポーネントを構成できます。たとえば、図25-34は、ユーザーがデータをExcelスプレッドシートにエクスポートできるコマンド・ボタン・コンポーネントがあるピボット・テーブルを示しています。

図25-34 Excelへのエクスポート・ボタンがあるピボット・テーブル

実行時に、ユーザーがボタンをクリックすると、デフォルトでは、すべての行および列がコンポーネントのfilename属性で指定されたファイルに書き込まれたExcel形式でエクスポートされます。または、exportedData属性をselectedに設定することにより、ユーザー選択のみがエクスポートされるように、exportPivotTableDataコンポーネントを構成できます。例25-11に、Excelへのエクスポートボタンのサンプル・コードを示します。

例25-11 Excelへのエクスポート・ボタンのサンプル・コード

<dvt:pivotTable id="pivotTableToExport"
binding="#{editor.component}"
contentDelivery="immediate"
value="#{pivotTableExport.dataModel}" summary="pivot table"/>

<h:panelGrid id="pfl" columns="2" cellpadding="3">
<af:button text="Export All" id="exportAll">
<dvt:exportPivotTableData exportedId="pivotTableToExport" type="excelHTML"
exportedData="all" filename="all.xls"
title="All pivotTable data"/>
</af:button>
<af:button text="Export Selected" id="exportSelected">
<dvt:exportPivotTableData exportedId="pivotTableToExport" type="excelHTML"
exportedData="selected" filename="selected.xls"
title="Selected pivotTable data"/>
</af:button>
</h:panelGrid>

図25-35に、「すべてのエクスポート」ボタンをクリックしたときの結果のExcelスプレッドシートを示します。

図25-35 Excelスプレッドシートへのピボット・テーブルのエクスポート

注意:

ファイルがファイル拡張子で指定されたフォーマットとは異なることを示す警告がExcelに表示されることがあります。この警告は無視して問題ありません。

25.5.4 印刷可能ページでのピボット・テーブルの表示

ADF Facesでは、印刷用の簡略化されたモードで、ADF Faces WebアプリケーションからJSFページを出力できます。たとえば、ユーザーがページ(またはページの一部)を印刷できるようにし、一方でWebブラウザでレンダリングされているとおりにページを印刷するのではなく、スクロールバーやボタンなど、印刷ページに必要ないアイテムを削除することが望ましい場合があります。このような出力用に簡略化されたページを作成する場合の詳細は、第37章「様々な出力モードの使用」を参照してください。

印刷可能モードで出力するJSFページにピボット・テーブルとピボット・フィルタ・バーが表示されている場合は、次のようになります。

- ピボット・テーブルのすべてのデータ・セルが表示されます。

- セルの選択や行または列のサイズ変更など、限定されたクライアント操作がサポートされます。

- ピボット、ドリルおよびソート操作はサポートされません。

- 行や列のサイズ変更機能も含めて、コンテキスト・メニューはサポートされません。

- ピボット・フィルタ・バーに表示されるピボット・テーブル・データのフィルタが構成されている場合、フィルタは表示されても、コンテンツは変化しません。

25.6 CellFormatによるピボット・テーブルのセルのコンテンツの書式設定

非推奨のストラテジですが、ヘッダー・セルおよびデータ・セルのスタンプを宣言によりスタイル設定するかわりに、CellFormatメソッド式を使用できます。inlinineStyleおよびstyleClass属性の使用方法の詳細については。詳細は、25.2.4項「ピボット・テーブルの表示サイズおよびスタイルの構成」を参照してください。

ピボット・テーブルのすべてのセルは、ヘッダー・セルまたはデータ・セルのいずれかです。セルをレンダリングする前、ピボット・テーブルではメソッド式がコールされます。pivotTableコンポーネントの次の属性にメソッド式を指定することで、ピボット・テーブルのヘッダー・セルとデータ・セルのコンテンツをカスタマイズできます。

- ヘッダー・セルには、次のいずれかの属性を使用します。

- headerFormat: ヘッダー・セルのコンテンツをカスタマイズする書式設定ルールの作成に使用します。

- headerFormatManager: アプリケーションのピボット・テーブルのヘッダー・セルの書式設定ルールに、カスタムの状態保存を指定する必要がある場合にのみ使用します。

- データ・セルには、次のいずれかの属性を使用します。

- dataFormat: データ・セルのコンテンツをカスタマイズする書式設定ルールの作成に使用します。

- dataFormatManager: アプリケーションのピボット・テーブルのデータ・セルの書式設定ルールに、カスタムの状態保存を指定する必要がある場合にのみ使用します。

25.6.1 データ・セルに対するCellFormatオブジェクトの使用方法

データ・セルのコンテンツのカスタマイズを指定するには、oracle.dss.adf.view.faces.bi.component.pivotTable.CellFormatのインスタンスを返すメソッド式をコーディングする必要があります。

CellFormatオブジェクトのインスタンスにより、セルのCSSスタイルを変更する引数を指定できます。たとえば、この引数を使用して、セルの背景色を変更します。

- コンバータ: javax.faces.convert.Converterのインスタンスで、セルのRAW値の数値、日付またはテキストの書式設定に使用されます。

- CSSスタイル: セルのCSSスタイルの変更に使用されます。たとえば、この引数を使用して、セルの背景色を変更します。

- CSSテキスト・スタイル: セルのテキストのCSSスタイルの変更に使用されます。たとえば、この引数を使用してテキストをボールドに設定します。

- 新規のRAW値: データ・モデルから返されたセルの基礎となる値の変更に使用されます。たとえば、州名の略記をフル・ネームに変更するよう選択できます。このケースでは、略記NYがNew Yorkに変更されます。

データ・セルにCellFormatオブジェクトのインスタンスを作成する手順:

1. 書式設定するデータ・セルに対し、oracle.adf.view.faces.bi.component.pivotTable.DataCellContextオブジェクトを作成します。DataCellContextメソッドは、コンストラクタに次のパラメータを必要とします。

- model: ピボット・テーブルで使用されるdataModelの名前。

- row: 操作対象のデータ・セルを含むゼロベースの行を指定する整数。

- column: 書式設定対象のデータ・セルを含むゼロベースの列を指定する整数。

- qdr: 書式設定対象のデータ・セルの完全修飾参照であるQDR。

- value: 書式設定対象のデータ・セルの値を含むjava.lang.Object。

2. ピボット・テーブルのdataFormat属性のメソッド式にDataCellContextを渡します。

3. メソッド式に、ピボット・テーブルのデータ・セルに適用する書式を指定するコードを記述します。このメソッド式はCellFormatオブジェクトを返す必要があります。

25.6.2 セルの書式設定の指定

ヘッダーおよびデータ・セルの書式設定スタイルを適用することで、ピボット・テーブルで表示されるデータの様々な面を強調できます。図25-36に、製品および製品カテゴリについて生成された売上げ合計のピボット・テーブルを示します。このピボット・テーブルでは、合計を含む行で、網掛けの背景に対してテキストが表示されます(スタイルの変更)。この変更は、ピボット・テーブルの行ヘッダー・セルとデータ・セルの両方に表示されます。合計の行ヘッダーには、「Sales Total」というテキストが含まれています。

ピボット・テーブルには、データ・セルのストップライト書式設定と条件付き書式設定も示されています。詳細は、25.6.3項「CellFormatを使用したストップライトおよび条件付き書式設定の構成」を参照してください。

図25-36 製品カテゴリごとの売上げデータ

例25-12に、売上げ合計に必要で、ストップライトの書式設定には必要ないカスタム書式を作成するサンプル・コードを示します。この例には、dvt:pivotTableタグのdataFormat属性とheaderFormat属性の両方にメソッド式のコードが含まれています。ピボット・テーブルにストップライトの書式設定も含める場合は、例25-13のコードを含めます。

例25-12 ピボット・テーブルでスタイルを変更するサンプル・コード

public CellFormat getDataFormat(DataCellContext cxt)
{
CellFormat cellFormat = new CellFormat(null, null, null);
QDR qdr = cxt.getQDR();
//Obtain a reference to the product category column.
Object productCateg = qdr.getDimMember("ProductCategory");
//Obtain a reference to the product column.
Object product = qdr.getDimMember("ProductId");

if (productCateg != null && productCateg.toString().equals("Sales Total"))
{
cellFormat.setStyle("background-color:#C0C0C0");
}
else if (product != null && product.toString().equals("Sales Total")
{
cellFormat.setStyle("background-color:#C0C0C0");
}
return cellFormat;
}

public CellFormat getHeaderFormat(HeaderCellContext cxt)
{
if (cxt.getValue() != null)
{
String header = cxt.getValue().toString();
if (header.equals("Sales Total"))
{
return new CellFormat(null, "background-color:#C0C0C0");
}
}
return null;
}

25.6.3 CellFormatを使用したストップライトおよび条件付き書式設定の構成

ピボット・テーブルのセルのストップライト書式設定と条件付き書式設定は、セルのコンテンツをカスタマイズする一例です。この種のカスタマイズでは、ユーザーはストップライト書式設定に関連付ける高値と低値を指定するようアプリケーションから要求されることがあります。通常、3つの色が次のように使用されます。

- 高値以上の値は緑に色付けされ、問題がないことを示します。

- 高値と低値の間の値は黄色に色付けされ、高度な基準に達していないことが警告されます。

- 低値以下の値は赤に色付けされ、最低限許容されるレベルに達していないことを示します。

図25-36に、最低限、許容範囲および基準以下の州の売上げに対するストップライト書式設定付きのデータ・セルを示します。

例25-13に、合計を表示しないピボット・テーブルでストップライト書式設定を行うコードを示します。合計を表示するピボット・テーブルでストップライト書式設定を行う場合は、(合計の行を扱う)例25-12のコードとストップライト書式設定と条件付き書式設定のコードを組み合せます。

例25-13 ストップライト書式設定と条件付き書式設定のサンプル・コード

public CellFormat getDataFormat(DataCellContext cxt)
{
//Use low and high values provided by the application.
double low = m_rangeValues.getMinimum().doubleValue() * 100;
double high = m_rangeValues.getMaximum().doubleValue() * 100;

CellFormat cellFormat = new CellFormat(null, null, null);

// Create stoplight format
if (isStoplightingEnabled())
{
String color = null;
Object value = cxt.getValue();
if (value != null && value instanceof Number)
{
double dVal = ((Number)value).doubleValue();
if (dVal <= low)
{
color = "background-color:" + ColorUtils.colorToHTML(m_belowColor) + ";";
}
else if (dVal > low && dVal <= high)
{
color = "background-color:" + ColorUtils.colorToHTML(m_goodColor) + ";";
}
else if (dVal > high)
{
color = "background-color:" + ColorUtils.colorToHTML(m_aboveColor) + ";";
}
}
cellFormat.setStyle(color);
}
return cellFormat;
}

26 ガント・チャート・コンポーネントの使用方法

この章では、ADFデータ可視化コンポーネントのprojectGantt、resourceUtilizationGanttおよびschedulingGanttを使用し、簡単なUI優先開発を使用してガント・チャートにデータを表示する方法を説明します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでテクノロジ・スタックを使用する場合、データ・コントロールを使用してガント・チャートを作成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 26.1項「ガント・チャート・コンポーネントについて」

- 26.2項「ガント・チャート・コンポーネントの使用方法」

- 26.3項「ガント・チャートのタスクおよびリソースのカスタマイズ」

- 26.4項「ガント・チャートの表示要素のカスタマイズ」

- 26.5項「ガント・チャートへのインタラクティブ機能の追加」

26.1 ガント・チャート・コンポーネントについて

ガント・チャートは横棒グラフの一種で、プロジェクトの計画および進捗管理に使用します。リソースまたはタスクを、開始と終了が明確なタイム・フレームに示します。ガント・チャート・コンポーネントは、ガント・チャートを表に表示する領域と、ガント・チャートをグラフィカルに表示する領域の2つの領域で構成され、その間にサイズ変更スプリッタがあります。表とチャートの領域は、同じデータと選択モデルを共有し、2つの領域間でスクロール、行の展開および縮小がサポートされ、同期化されます。

実行時に、ガント・チャートでは表領域にデータの入力、行の展開および縮小、列の表示および非表示、行へのナビゲート、および列のソートおよび合計の表示などの対話機能がユーザーに提供されます。表領域で、ユーザーはタスクを新しい日付にドラッグし、複数のタスクを選択して依存性を作成し、タスクの日付を拡張または縮小できます。ガント・チャートのツールバーは、データの表示の変更またはフィルタ処理、およびタスクの作成、削除、切取り、コピーおよび貼付けなどのユーザー操作のサポートに使用します。

ガント・チャートの領域は、両方ともADF Facesのツリー表コンポーネントに基づいています。行の仮想化など、ADFツリー表の詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

ADF Ganttチャート・コンポーネントには、プロジェクト・ガント・チャート(projectGantt)、リソース使用率ガント・チャート(resourceUtlizationGantt)およびスケジュール・ガント・チャート(schedulingGantt)があります。

26.1.1 ガント・チャート・コンポーネントのユースケースおよび例

ガント・チャートには、次のタイプがあります。

- プロジェクト・ガント・チャート: プロジェクト・ガント・チャートはプロジェクト管理に使用されます。このチャートでは、タスクを縦にリストし、横向きの予定表に各タスクの期間を棒で示します。図26-1に示すように各タスクを別の線で示します。

図26-1 ソフトウェア・アプリケーション用プロジェクト・ガント・チャート

- リソース使用率ガント・チャート: リソース使用率ガント・チャートでは、リソースのメトリック、たとえばリソースが割当てを上回っているか下回っているかをグラフィカルに示します。リソースを縦に示し、横方向の時間軸に割当てとキャパシティなどのメトリックを示します。図26-2に、指定した期間の特定の開発者リソースに割り当てられ、利用されている時間を表示するリソース使用率ガント・チャートを示します。

図26-2 ソフトウェア・アプリケーション用リソース使用率ガント・チャート

リソース使用率ガント・チャートのメトリックが積上げ棒または横線として表示されるように構成することもできます。図26-3に示すリソース使用率ガント・チャートでは、2つのメトリックとして利用された時間を示す積上げ棒、割り当てられた時間を示す縦棒、およびチャートを通過するしきい値メトリックを示す横線が表示されています。

図26-3 積上げ棒および段付きの線として表示されているリソース・メトリック

- スケジュール・ガント・チャート: スケジュール・ガント・チャートはリソースのスケジュールに使用されます。このチャートは手動のスケジュール表をベースにし、リソースを縦に表示し、対応するアクティビティを横方向の時間軸に表示します。リソースの例には、人、機械、部屋などがあります。スケジュール・ガント・チャートでは、図26-4に示すように、リソースに割り当てられている全タスクが1つの線で示されます。

図26-4 ソフトウェア・アプリケーション用スケジュール・ガント・チャート

26.1.2 エンド・ユーザー機能およびプレゼンテーション機能

ガント・チャートをどのように使用し、どのようにカスタマイズできるかを理解するには、次の要素と機能について復習すると役に立ちます。

26.1.2.1 ガント・チャートの領域

ガント・チャートは、次の2つの領域で構成されます。

- ガント・チャート・データ属性を表の列に表示する表領域。表領域には最低1つの列が必要ですが、必要な数の列に属性を定義できます。表領域には、データ・バインドされたガント・チャートの作成時に定義したすべての列がデフォルトで表示されます。ただし、これらの列の1つ以上を選択して非表示にすることもできます。

- ガント・チャート・データの棒グラフを横方向の時間軸に沿って表示するチャート領域。時間軸にはズーム用の主設定と副設定があります。主設定はより大きな時間単位用で、副設定はより小さな時間単位用です。

たとえば、図26-4では、スケジュール・ガント・チャートの表領域には、タスク名およびリソースの列が含まれており、チャート領域では、月内の週を示す時間軸においてタスクがグラフ化されています。

図26-5 プロジェクト・ガント・チャート領域

26.1.2.2 情報パネル

オプションの情報パネルには、選択したタスクに関するテキスト、または選択したリソースに関するメトリックを表示する情報領域と、ガント・チャートの下の領域にタスク・タイプを表示するオプションの凡例の両方が表示されます。情報パネルを有効にするには、ガント・チャートの凡例を構成する必要があります。図26-6に、図26-4のスケジュール・ガント・チャートの情報パネルを示します。このパネルには、チャート領域で選択したタスクに関する情報、およびガント・チャートの凡例が含まれています。

図26-6 スケジュール・ガント・チャートの情報パネル

26.1.2.3 ツールバー

ユーザーは、ガント・チャートのツールバーを使用して、ガント・チャートを操作できます。ツールバーはデフォルトでガント・チャートに表示されます。

ツールバーは、次の2つのセクションで構成されます。

- メニュー・バー:ツールバーの左側の部分には、ガント・チャートに対するメニューのセットが含まれます。各ガント・チャート・タイプには、デフォルトのオプションのセットがあります。図26-7に、ガント・チャートにデフォルトで表示されるメニュー・バーを示します。メニュー・バーの可視性を変更すること、およびメニュー項目をカスタマイズすることができます。

図26-7 ガント・チャートのサンプル・メニュー・バー

デフォルトでは、ガント・チャートの「表示」メニューの項目は、次の1つ以上の操作をサポートしています。

- 表領域での列の可視性の構成。

- 表領域での階層データの表示の展開および縮小。

- チャート領域でのタスク間の依存性行の非表示と表示の切り替え。

- ガント・チャートの凡例の非表示と表示の切り替え。

- ガント・チャートでの特定日付の指定。図26-8に、「表示」メニューの「日付へ移動」ダイアログを示します。

図26-8 「日付へ移動」ダイアログ

- ガント・チャートのタイム・スケールの変更。図26-9に、「表示」メニューの「タイム・スケール」ダイアログを示します。

図26-9 「タイム・スケール」ダイアログ

注意:

メニュー・バーの「表示」メニューの項目では、それらの項目を機能させるためのアプリケーション・コードを記述する必要はありません。ただし、他のメニューで使用する項目にはアプリケーション・コードが必要です。

- ツールバー・ボタン:ツールバーの右側の部分には、ガント・チャートを操作するためのアクション・ボタンのセットが表示されます。各ガント・チャート・タイプには、デフォルトのオプションのセットがあります。図26-10に、プロジェクト・ガント・チャートのサンプル・ツールバーを示します。

図26-10 プロジェクト・ガント・チャートのサンプル・ツールバー

注意:

右から左への表示を使用するロケールでは、方向アイコンが逆の順番で表示されます。

ツールバーを使用して、ガント・チャートでの時間表示を変更できます。時間軸にズーム・インおよびズーム・アウトして、異なる時間単位でチャート領域を表示できます。

ズームして合せる特殊な機能を使用すると、グラフをスクロールする必要なく、チャート領域で表示可能な時間の量を選択することもできます。「表示」メニューのガント・チャートのタイム・スケールは、選択した日付に合わせて自動的に調整されます。図26-11に、プロジェクト・ガント・チャートで展開された「ズームしてあわせる」ツールバー・オプションを示します。

図26-11 「ズームしてあわせる」ツールバー・オプション

26.1.2.4 スクロール、ズームおよびパン

ガント・チャートの設計により、表領域とチャート領域の横方向のスクロールを別々に行えます。これは、表領域で特定のタスクまたはリソース情報を保持しつつ、チャート領域でスクロールして複数期間の情報を得る場合に特に有用です。

スクロールバーのかわりとして、ユーザーが複数ページのガント・チャートを選択およびナビゲートできる水平ページ・コントロールを表示することもできます。図26-12に、水平ページ・コントロールが構成されたリソース使用率ガント・チャートを示します。

図26-12 リソース使用率ガント・チャートのページ・コントロール

ユーザーは、ツールバーのズーム・コントロールに加えて、[Ctrl]キーを押しながらマウスのスクロール・ホイールを使用することでも、ガント・チャートのタイム・スケールにズーム・インおよびズーム・アウトできます。複数のレベルを一度にズームする際、ユーザーが現在のレベルを把握できるように、ツールチップが表示されます。これは特にユーザーがクリック機能のないスクロール・ホイールを使用する場合に便利です。

プロジェクトおよびスケジュール・ガント・チャートでは、ユーザーはカーソルを使用してチャート領域を縦横にドラッグすることにより、チャート領域パンすることができます。移動カーソルは、ユーザーがタスク以外のチャート領域内をクリックすると表示されます。

またガント・チャートには、2つの領域間の垂直スペースで使用できるアイコンを使用して、表の表示を縮小および拡張するユーザー・オプションもあります。

26.1.2.5 依存関係の表示

タスク間の依存関係が指定されている場合、プロジェクトおよびスケジュール・ガント・チャートでは、チャート領域に依存関係線をオプションで表示できます。依存関係線を表示するオプションは、「表示」メニューの項目として使用できます。さらに、プロジェクト・ガント・チャートでは、依存関係のあるタスクの開始時または終了時にドロップダウン・メニューを使用して、先行タスクまたは後続タスクのメニュー・オプションとして依存関係を表示できます。図26-13に、依存関係を線、メニュー項目として表示するオプション、または依存関係を表示しないオプションを含む、プロジェクト・ガント・チャートの「表示」メニューを示します。

図26-13 プロジェクト・ガント・チャートの「依存性の表示」オプション

図26-14に、後続タスクおよび先行タスクの依存関係タスク・メニュー項目を含むプロジェクト・ガント・チャートを示します。

図26-14 プロジェクト・ガント・チャートの依存関係タスクのメニュー項目

26.1.2.6 コンテキスト・メニュー

ガント・チャートの表領域またはチャート領域を右クリックすると、メニュー項目の標準セットを含むコンテキスト・メニューが表示されます。tablePopupMenuファセットまたはchartPopupMenuファセットを使用して独自のメニュー項目のセットを使用できます。詳細は、26.4.6項「ガント・チャートのコンテキスト・メニューのカスタマイズ」を参照してください。

図26-15に、スケジュール・ガント・チャートのタスクのプロパティに対して表示されるカスタム・コンテキスト・メニュー項目を示します。

図26-15 タスクのカスタム・コンテキスト・メニュー

26.1.2.7 行の選択

rowSelection属性を使用して、ガント・チャートのチャート領域で、選択が行なし、単一行または複数行になるように構成できます。プロジェクト・ガント・チャートのタスク、あるいはスケジュールまたはリソース使用率ガント・チャートのリソースを選択できます。この設定により、選択したタスクまたはリソースに対してロジックを実行できます。たとえば、ユーザーがリソースを選択し、そのリソースに基づきカレンダを表示できるようにすることが必要な場合があります。

表領域で選択されている行が変更されると、コンポーネントにより選択イベントがトリガーされます。このイベントにより、どの行が選択または選択解除されたか報告されます。コンポーネントにより選択が宣言的に処理される際、選択された行でロジックを実行する必要がある場合は、それらの行にアクセスしてロジックを実行するコードを実装する必要があります。これは、マネージドBeanの選択リスナー・メソッドで実行できます。詳細は、26.5.1項「選択されたタスクまたはリソースでのアクションの実行」を参照してください。

注意:

複数の選択を実行できるようにコンポーネントを構成した場合、ユーザーが行を1つ選択し、[Shift]キーを押して別の行を選択すると、間にあるすべての行が選択されます。この選択は、選択が複数のデータ・フェッチ・ブロックにまたがる場合でも保持されます。同様に、[Ctrl]キーを使用して、隣接していない行を選択することもできます。

たとえば、一度に25行のみフェッチするようにガント・チャートの表領域が構成されている場合、ユーザーが100行選択すると、フレームワークにより選択が追跡されます。

26.1.2.8 タスクの編集

プロジェクトおよびスケジュール・ガント・チャートでは、ユーザーは、チャート領域で編集可能タスクのタスク・バーを移動またはサイズ変更できます。編集可能タスクにカーソルを合わせると、移動カーソルが表示され、カーソルの位置に関する情報がポップアップします。チャート内のタスクを再配置するには、関連する開始日および終了日を含むタスク・バーをクリックしてドラッグします。タスクの開始日または終了日が編集可能の場合、タスク・バーの先頭または末尾に両方向の矢印が表示されます。日付をクリックして、目的の場所までドラッグします。図26-16に、プロジェクト・ガント・チャート内の編集可能タスクの移動カーソルおよびサイズ変更カーソルを示します。

図26-16 編集可能タスク・バーの移動カーソルおよびサイズ変更カーソル

26.1.2.9 サーバー側イベント

ユーザー操作にデータの変更が含まれる場合、ガント・チャートでは、イベント処理およびデータ・モデルの更新を実行することで変更が処理されます。ガント・チャートに対し検証が構成されている場合、検証により、送信されたデータが基本要件を満たしていること(たとえば、日付が有効で休日の期間に該当しないことなど)が確認されます。検証に失敗すると、データ・モデルの更新が省略され、エラー・メッセージが返されます。

ガント・チャートのサーバー側イベントが開始されると、変更に関する検証された情報を含むイベントが登録されたリスナーに送信されます。リスナーは基礎となるデータ・モデルを更新します。カスタマイズされたイベント・ハンドラは、ガント・チャート・コンポーネントのdataChangeListener属性でメソッド・バインディング式を指定することによって登録できます。

ガント・チャートによってサポートされるサーバー側イベントには、次のものが含まれます。

- ガント・チャート表領域における表のセルのデータ更新

- タスクの作成、更新、削除、移動、切取り、コピー、貼付け、インデント、アウトデント

- タスク・バーを1つの行から別の行にドラッグすることによるリソースの再割当て

- 別の日付へのタスク・バーのドラッグ

- タスクの期間の延長

- タスクのリンク付けまたはリンク解除

- ガント・チャート表領域での単一の行または複数の行の選択

- ユーザー・アクションを元に戻すまたはやり直し

- タスク・バーのダブルクリック

ユーザーはツールバーからドロップダウン・リストを使用してガント・チャートのデータをフィルタ処理できます。カスタム・フィルタを作成できます。

26.1.2.10 印刷

ガント・チャートには、ApacheまたはXML Publisherと連動してPDFファイルを生成し、印刷する機能が用意されています。詳細は、26.5.4項「ガント・チャートの印刷」を参照してください。

26.1.2.11 コンテンツの配信

ガント・チャートにデータ・ソースからどのようにデータを配信するかを構成できます。データは、レンダリング直後、データが使用可能になり次第、またはコンポーネントのシェルがレンダリングされた後の遅延フェッチのいずれかで、ガント・チャートに配信できます。データ・ソースが使用可能の場合、ガント・チャートは、デフォルトで、データ・ソースからのコンテンツの配信をサポートします。contentDelivery属性は、デフォルトでwhenAvailableに設定されています。

ガント・チャートは仮想化されています。つまり、サーバーの一部のデータのみがクライアントに配信され、表示されます。日付に関連する値に基づいて、データ・ソースから特定数の行または列を一度にフェッチするようにガント・チャートを構成できます。フェッチ・サイズを構成するには、fetchSizeおよびhorizontalFetchSizeを使用します。

26.1.3 ガント・チャート・コンポーネントの追加機能

ガント・チャート・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんガント・チャート・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。ガント・チャート・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、ガント・チャートをリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: ユーザーは実行時にガント・チャートの表示方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: ガント・チャート・コンポーネントにはデフォルトでアクセス可能です。アプリケーション・ページにスクリーン・リーダー・ユーザーがアクセスできるようにすることが可能です。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- Excelにエクスポート: af:exportCollectionActionListenerを使用してプロジェクト・ガント・チャートの表領域をエクスポートできます。詳細は、12.12項「表、ツリーまたはツリー表からのデータのエクスポート」を参照してください。

- コンテンツ配信: ガント・チャートの表領域を、contentDelivery属性を使用して、データ・ソースから特定の行数を一度にフェッチするように構成できます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- 自動データ・バインディング: アプリケーションでテクノロジ・スタックを使用する場合、ADFビジネス・コンポーネントの構成方法に基づいて、自動的にバインドされたガント・チャートを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「プレースホルダ・データ・コントロールを使用したページの設計」の章を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、イメージ形式、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

26.2 ガント・チャート・コンポーネントの使用方法

ガント・チャートのデータ・モデルは、ツリー(階層)モデル、あるいは行セットまたはオブジェクトのフラット・リストを含むコレクション・モデルのいずれかです。ガント・チャートをデータ・コントロールにバインドする場合、データ・コントロールのコレクションをガント・チャートのノード定義へマップする方法を指定します。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

26.2.1 プロジェクト・ガント・チャートのデータ

プロジェクト・ガント・チャートのデータ・モデルは、階層式のデータをサポートし、TreeModelを使用して基礎となるリストのデータにアクセスします。使用される特定のモデル・クラスはorg.apache.myfaces.trinidad.model.TreeModelです。

TreeModelによって返されるオブジェクトのコレクションには、最低限、次のプロパティが必要です。

- taskId: タスクのID

- startTime: タスクの開始時期

- endTime: タスクの終了時期

(オプション)オブジェクトにoracle.adf.view.faces.bi.model.Taskインタフェースを実装して、ガント・チャートに正しいプロパティが提供されていることを確認できます。

ADFデータ・コントロールにデータをバインドする場合、プロジェクト・ガント・チャートでは、次のノード定義を使用できます。

- タスク・ノード:タスクのコレクションを表します。タスク・ノード定義には、次のタイプのオプション・アクセッサがあります。

- subTask(プロジェクト・ガント・チャートにのみ使用可能)

- splitTask

- 分割タスク・ノード:分割タスクのコレクションを表します。分割タスク・ノード定義にはアクセッサはありません。

- 依存性ノード:タスクの依存性のコレクションを表します。依存性ノード定義には、アクセッサはありません。

- 再帰タスク・ノード:再帰タスクのコレクションを表します。再帰タスク・ノード定義には、アクセッサはありません。

表26-1に、プロジェクト・ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表26-1 プロジェクト・ガントのデータ・オブジェクト・キー

データ・オブジェクト・キー

日付型と説明

actualEnd

Date。標準タスクおよびマイルストン・タスクの実際の終了時期。

actualStart

Date。標準タスクおよびマイルストン・タスクの実際の開始時期。

completedThrough

Date。標準タスクおよびサマリー・タスクの完了。

critical

Boolean。タスクがすべてのタスクに対してクリティカルかどうかを指定します。

依存性(ノード)

タスクの依存性のリスト。依存性のデータ・オブジェクト・キーには次のものが含まれる。

- fromId: 依存性が開始するタスクのID。

- toId: 依存性が終了するタスクのID。

- type: 依存性のタイプ。有効な値は、start-start、start-finish、finish-finish、finish-start、start-before、start-together、finish-afterおよびfinish-togetherです。

editsAllowed

Boolean。チャート領域でタスク・バーを編集可能にするかどうかを指定します。

endTime(必須)

Date。すべてのタスクの終了時期。

icon1

String。すべてのタスクのタスク・バーに関連付けられる1番目のアイコン。アイコンは、その他の属性に応じて変わる可能性があります。

icon2

String。すべてのタスクのタスク・バーに関連付けられる2番目のアイコン。

icon3

String。すべてのタスクのタスク・バーに関連付けられる3番目のアイコン。

iconPlacement

String。すべてのタスクのタスク・バーでのアイコンの配置。有効な値はleft (デフォルト)、right、inside、start、end、innerLeft、innerRight、innerCenter、innerStart、innerEndです。

isContainer

Boolean。ノード定義がコンテナかどうかを指定します。

label

String。すべてのタスクのタスク・バーに関連付けられるラベル。

labelPlacement

String。すべてのタスクのタスク・バーでのラベルの配置。有効な値はleft (デフォルト)、right、inside、start、end、innerLeft、innerRight、innerCenter、innerStart、innerEndです。

percentComplete

Integer。標準タスクおよびサマリー・タスクが完了した割合。

再帰タスク(ノード)

すべてのタスクに関する再帰タスクのリスト。

分割タスク(ノード)

すべてのタスクに関する連続的な時系列のないタスクのリスト。

startTime(必須)

Date。すべてのタスクの開始時期。

サブタスク(ノード)

すべてのタスクに関するサブタスクのオプションのリスト。

taskId(必須)

String。すべてのタスクの一意の識別子。

type

Sting。すべてのタスクに関するタスクのタイプ。

26.2.2 リソース使用率ガント・チャートのデータ

リソース使用率ガント・チャートのデータ・モデルは、階層式のデータをサポートし、TreeModelを使用して基礎となるリストのデータにアクセスします。使用される特定のモデル・クラスはorg.apache.myfaces.trinidad.model.TreeModelです。

TreeModelによって返されるオブジェクトのコレクションには、最低限、次のプロパティが必要です。

- resourceId: タスクのID。

- timeBuckets: このリソースの時間バケット・オブジェクトのコレクション。

(オプション)オブジェクトにoracle.adf.view.faces.bi.model.Resourceインタフェースを実装して、ガント・チャートに正しいプロパティが提供されていることを確認できます。

timeBucketsプロパティによって返されるオブジェクトのコレクションには、次のプロパティも必要です。

- time: 時間バケットによって表される日付。

- values: このリソースのメトリックのリスト。

ADFデータ・コントロールにデータをバインドする場合、リソース使用率ガント・チャートでは、次のノード定義を使用できます。

- リソース・ノード:リソースのコレクションを表します。リソース・ノード定義には、現在のリソースのサブリソースのコレクションを返すsubResourcesオプション・アクセッサがあります。

- 時間バケット・ノード:メトリックが定義された時間スロットのコレクションを表します。

- 時間バケット詳細ノード: 時間バケット・ノードのオプションの子アクセッサで、時間バケットの他のメトリック値とともにレンダリングされる行のコレクションを表します。

表26-2に、リソース使用率ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表26-2 リソース使用率ガントのデータ・オブジェクト・キー

データ・オブジェクト・キー

データ型と説明

label

String。タスク・バーに関連付けられるラベル。

labelAlign

String。タスク・バーでのラベルの配置。有効な値は、top (デフォルト)とinsideです。

resourceId(必須)

String。リソースの一意の識別子。

timeBuckets(必須)

List。リソースに関連付けられるタスクのリスト。

timeBucketDetail

List。リソースに関連する属性のリスト。

time(必須)

Date。時間バケットの開始時期。

values(必須)

Double。メトリックの値。

26.2.3 スケジュール・ガント・チャートのデータ

スケジュール・ガント・チャートのデータ・モデルは、階層式のデータをサポートし、TreeModelを使用して基礎となるリストのデータにアクセスします。使用される特定のモデル・クラスはorg.apache.myfaces.trinidad.model.TreeModelです。

TreeModelによって返されるオブジェクトのコレクションには、最低限、次のプロパティが必要です。

- resourceId: タスクのID。

- tasks: このリソースのタスク・オブジェクトのコレクション。

(オプション)オブジェクトにoracle.adf.view.faces.bi.model.ResourceTaskインタフェースを実装して、ガント・チャートに正しいプロパティが提供されていることを確認できます。

tasksプロパティによって返されるオブジェクトのコレクションには、次のプロパティも必要です。

- taskId: タスクのID

- startTime: タスクの開始時期

- endTime: タスクの終了時期

ADFデータ・コントロールにデータをバインドする場合、スケジュール・ガント・チャートでは、次のノード定義を使用できます。リソース・ノードには、次のタイプのアクセッサがあります。

- subResources: 現在のリソースのサブリソースのコレクションを返します。このアクセッサはオプションです。

- tasks: 現在のリソースのタスクのコレクションを返します。このアクセッサは必須です。タスクに、splitTaskアクセッサを含めることができます。

表26-3に、スケジュール・ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表26-3 スケジュール・ガント・チャートのデータ・オブジェクト・キー

データ・オブジェクト・キー

データ型と説明

依存性(ノード)

タスクの依存性のリスト。依存性のデータ・オブジェクト・キーには次のものが含まれる。

- fromId: 依存性が開始するタスクのID。

- toId: 依存性が終了するタスクのID。

- type: 依存性のタイプ。有効な値は、start-start、start-finish、finish-finish、finish-start、start-before、start-together、finish-afterおよびfinish-togetherです。

endTime(必須)

Date。すべてのタスクの終了時期。

icon1

String。すべてのタスクのタスク・バーに関連付けられる1番目のアイコン。アイコンは、その他の属性に応じて変わる可能性があります。

icon2

String。すべてのタスクのタスク・バーに関連付けられる2番目のアイコン。

icon3

String。すべてのタスクのタスク・バーに関連付けられる3番目のアイコン。

iconPlacement

String。すべてのタスクのタスク・バーでのアイコンの配置。有効な値は、left (デフォルト)、right、inside、inside_left、inside_rightおよびinside_centerです。右から左への表示を使用するロケールでは、startおよびend値もサポートされます。

isContainer

Boolean。ノード定義がコンテナかどうかを指定します。

label

String。すべてのタスクのタスク・バーに関連付けられるラベル。

labelPlacement

String。すべてのタスクのタスク・バーでのラベルの配置。有効な値は、left (デフォルト)、right、inside、inside_left、inside_rightおよびinside_centerです。右から左への表示を使用するロケールでは、startおよびend値もサポートされます。

再帰タスク(ノード)

すべてのタスクに関する再帰タスクのリスト。

resourceId(必須)

String。リソースの一意の識別子。

分割タスク(ノード)

すべてのタスクに関する連続的な時系列のないタスクのコレクション。

startTime(必須)

Date。すべてのタスクの開始時期。

startupTime

Date。タスクの開始前の起動時期。

タスク(ノード)(必須)

リソースに関連付けられるタスクのリスト。

taskId(必須)

String。すべてのタスクに関するタスクの一意の識別子。

taskType

String。すべてのタスクに関するタスクのタイプ。

workingDaysOfTheWeek

Object。その週の営業日のリスト。

workingEndTime

Date。リソースの作業終了時間。

workingStartTime

Date。リソースの作業開始時間。

26.2.4 ガント・チャートのタスクおよびリソース

プロジェクト・ガント・チャートおよびスケジュール・ガント・チャートでは、チャート領域でのタスクのレンダリング方法を説明する書式設定プロパティのセットが指定された事前定義済タスクが使用されます。すべてのサポートされるタスクには一意の識別子が必要です。次のリストで、サポートされるタスクとガント・チャートでの外観を説明します。

- 標準:基本的なタスク・タイプ。プレーンな横棒でタスクの開始時期、終了時期および期間を示します。

- サマリー:サブタスクのグループの開始日と終了日。サマリー・タスクは移動や伸長できません。サブタスクの日付が変更された場合、アプリケーションで、サマリー・タスクの開始日と終了日をかわりに再計算する必要があります。サマリー・タスクはプロジェクト・ガント・チャートにのみ使用できます。

- マイルストン:ガント・チャートの特定の日付。マイルストン・タスクに関連付けられる日付は1つのみです。マイルストン・タスクは伸長できませんが、移動できます。マイルストン・タスクはプロジェクト・ガント・チャートにのみ使用できます。

- 再帰:ガント・チャートで繰り返されるタスクで、各インスタンスには独自の開始日および終了日が含まれます。個々の再帰タスクにはオプションでサブタイプを含めることができます。個々の再帰タスクのその他すべてのプロパティには、そのタスクが一部となっているタスクのプロパティが使用されます。ただし、個々の再帰タスクにサブタイプがある場合は、このサブタイプがタスク・タイプをオーバーライドします。

- 分割:2つの横棒に分割されたタスクで、通常は線でつながっています。棒の間の時間は、移動時間または停止時間によるアイドル時間を表します。

- スケジュール済:スケジュール・ガント・チャートの基本的なタスク・タイプ。このタスク・タイプはタスクの開始時期、終了時期および期間、および指定されている場合は起動時期を示します。

標準タスク、サマリー・タスクおよびマイルストン・タスクでは、タスクの外観およびアクティビティを変更する追加の属性がサポートされています。次にこれらのスタイル属性を示します。

- percentComplete、completedThrough: タスクの完了度を示す追加の棒グラフが描画されます。これは標準タスク・タイプおよびサマリー・タスク・タイプに適用されます。

- critical: 棒グラフの色が赤に変更され、クリティカルとしてマークされます。これは標準タスク・タイプ、サマリー・タスク・タイプおよびマイルストン・タスク・タイプに適用されます。

- actualStartおよびactualEnd: これらの属性が指定されると、1つの棒グラフではなく2つの棒グラフが描画されます。1つの棒グラフはベース開始日およびベース終了日を示し、もう1つの棒グラフは実際の開始日および終了日を示します。これは標準タスク・タイプおよびマイルストン・タスク・タイプに適用されます。

図26-17に、プロジェクト・ガント・チャートの一般的なタスク・タイプを表示する凡例を示します。

図26-17 プロジェクト・ガント・チャートのタスク・タイプ用凡例

リソース使用率ガント・チャートでは、縦方向にリソースがグラフィカルに表示され、横方向の時間軸に割当てや容量などのメトリックが表示されます。時間バケットでタスクに対して表示されるメトリックは、TaskbarFormatクラスでの指定に従いレンダリングされます。タスクのメトリックとして、次の3つのタイプのいずれかを使用できます。

- BAR(デフォルト): 縦棒としてタスクをレンダリングします。

- STACKED: 前のバーにバーを積み上げる形式でタスクをレンダリングします。

- STEPPED_LINE: 横線としてタスクをレンダリングします。

26.2.5 ガント・チャートの構成

各ガント・チャート・タグ名が接頭辞dvt:で始まる3つのガント・チャート・コンポーネントは、タグがADF Data Visualization Tools (DVT)タグ・ライブラリの1つであることを示します。

- projectGantt

- resourceUtilizationGantt

- schedulingGantt

すべてのガント・チャート・コンポーネントが、ガント・チャートの情報パネルにオプションの凡例を提供するための子タグganttLegendをサポートしています。一部のメニュー・バーおよびツールバーの機能は、ガントの凡例が指定されているかどうかによって使用できる場合とできない場合があります。

ガント・チャート表領域では、ADF Faces af:columnタグを使用して、ヘッダー・テキスト、アイコンおよびデータの位置合せ、列の幅、および列にバインドされたデータを指定できます。データを階層構造で表示するには、nodeStampファセットで階層の要素の1次識別子を指定します。たとえば、"Task Name"列をプロジェクト・ガント・チャートのnodeStampファセットとして使用することもできます。例26-1に、"Task Name"をnodeStampファセットとして使用し、Resource、Start DateおよびEnd Dateの列を持つプロジェクト・ガント・チャートのサンプル・コードを示します。

例26-1 プロジェクト・ガント・チャートの列のサンプル・コード

<dvt:projectGantt id="projectChart1" startTime="2008-04-12"
endTime="2009-04-12"
value="#{project.model}"
var="task">
<f:facet name="major">
<dvt:timeAxis scale="months"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="weeks"/>
</f:facet>
<f:facet name="nodeStamp">
<af:column headerText="Task Name">
<af:outputText value="#{task.taskName}"/>
</af:column>
</f:facet>
<af:column headerText="Resource">
<af:outputText value="#{task.resourceName}"/>
</af:column>
<af:column headerText="Start Date">
<af:outputText value="#{task.startTime}"/>
</af:column>
<af:column headerText="End Date">
<af:outputText value="#{task.endTime}"/>
</af:column>
</dvt:projectGantt>

nodeStampファセットに加え、他のファセットもガント・チャート・コンポーネントによってカスタマイズに使用されます。表26-4に、ガント・チャート・コンポーネントによってサポートされているファセットを示します。

表26-4 ガント・チャート・コンポーネントによってサポートされているファセット

chartPopupMenu

チャート領域のポップアップ・メニューに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:popupコンポーネントである必要があります。

customPanel

タスク・プロパティ・ダイアログの「カスタム」タブに表示されるコントロールの識別に使用するコンポーネントを指定します。

major

主時間軸の識別に使用するコンポーネントを指定します。dvt:timeAxisコンポーネントである必要があります。

menuBar

ガント・メニュー・バーに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:menuコンポーネントである必要があります。

minor

副時間軸の識別に使用するコンポーネントを指定します。dvt:timeAxisコンポーネントである必要があります。

nodeStamp

ガント・チャートの各要素のスタンプ設定に使用するコンポーネントを指定します。アクティビティのないすべてのコンポーネント、およびEditableValueHolderまたはActionSourceインタフェースを実装する大半のコンポーネントなど、特定のタイプのコンポーネントのみがサポートされます。af:columnコンポーネントである必要があります。

tablePopupMenu

表領域のポップアップ・メニューに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:popupコンポーネントである必要があります。

toolbar

ガント・ツールバーに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:toolbarコンポーネントを指定する必要があります。

26.2.6 ページへのガント・チャートの追加方法

簡単なUI優先開発を使用してページを設計している場合、「コンポーネント」ウィンドウを使用して、プロジェクト、リソース使用率またはスケジュール・ガント・チャート・コンポーネントをJSFページにドラッグ・アンド・ドロップします。

ページにガント・チャートが追加された後、「プロパティ」ウィンドウを使用してデータ値を指定すること、およびガント・チャートの追加の表示属性を構成することができます。

「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図26-18に、プロジェクト・ガント・チャート・コンポーネントのstartTime属性のドロップダウン・メニューを示します。

図26-18 プロジェクト・ガント・チャートのstartTime属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してガント・チャートを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、ガント・チャート・パネルから「プロジェクト」、「リソース使用率」または「スケジュール」ガント・チャートをページにドラッグ・アンド・ドロップし、「ガント・チャートの作成」ダイアログを開きます。
オプションで、そのダイアログの「データを今すぐバインド」を選択して、ガント・チャートで表示するデータを表すADFデータ・コントロールかADFマネージドBeanを入力するか、そこに移動しするかして、ガント・チャートをバインドします。このオプションを選択すると、ダイアログのデータ・バインディングのフィールドが編集のために使用可能になります。そうでなければ、「OK」をクリックして、ページにコンポーネントを追加します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

2. 「プロパティ」ウィンドウで、ガント・チャートの属性を確認します。ヘルプ・ボタンを使用して、projectGantt、resourceUtilizationGanttまたはschedulingGanttコンポーネントの完全なタグ・ドキュメントを表示します。

3. 「共通」セクションを開きます。このセクションを使用して、次の属性を設定します。

- StartTime: ガント・チャートの期間のレンダリングに使用する開始時期。

- EndTime: ガント・チャートの期間のレンダリングに使用する終了時期。

4. 「ガント・データ」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Value: EL式を使用してデータ・モデル(org.apache.myfaces.trinidad.model.TreeModelのタイプ)を指定します。

- Var: ガント・チャート・データ・コレクションの各要素の参照に使用される変数を指定します。このコンポーネントのレンダリングが完了すると、この変数は削除されるか、その前の値に戻ります。

5. 「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- RowBandingInterval: 色のバンディングの目的で、連続する何行で行グループを形成するかを指定します。デフォルトでは、これは0に設定されており、すべての行が同じ背景色で表示されます。別の色を使用する場合は、これを1に設定します。

- ShowMenuBar: ガント・チャートにメニュー・バーを表示するかどうかを指定します。この属性をfalseに設定すると、menuBarファセットで指定されたカスタム・メニュー・バー項目も非表示になります。

- ShowToolbar: ガント・チャートにツールバーを表示するかどうかを指定します。この属性をfalseに設定するとtoolbarファセットで指定したカスタム・ツールバー・ボタンも非表示になります。

- Summary: ガント・チャートの説明を入力します。この説明は、スクリーン・リーダーのユーザーがアクセスします。

6. 「動作」セクションを開きます。このセクションを使用して、次の属性を設定します。

- InitiallyExpandAll: すべての行を最初に展開するかどうかを指定します。

- FetchSize: 1データ・フェッチ・ブロック内の行数の指定に使用します。デフォルト値は25行です。ガント・チャートへのコンテンツの配信の詳細は、22.2.1項「コンテンツの配信」を参照してください。

- FeaturesOff: 実行時に無効にするエンド・ユーザー機能の空白区切りリストを入力します。有効な値は、ガント・チャートのタイプによって異なります。

7. 「その他」セクションを開きます。このセクションを使用して、次の属性を設定します。

- RowSelection: ガント・チャートのチャート領域で、選択が行なし、単一行または複数行になるように構成するために使用します。

26.2.7 ページにガント・チャートを追加する場合の処理

「コンポーネント」ウィンドウを使用してガント・チャートを作成すると、JDeveloperによりJSFページにコードが挿入されます。例26-2に、プロジェクト・ガント・チャートに対してJSFページで挿入されるコードを示します。

例26-2 プロジェクト・ガント・チャートのサンプル・コード

<dvt:projectGantt startTime="2011-03-20" endTime="2011-06-19" var="row" id="pg1">
<f:facet name="major">
<dvt:timeAxis scale="weeks" id="ta5"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="days" id="ta6"/>
</f:facet>
<f:facet name="nodeStamp">
<af:column sortable="false" headerText="col1" id="c11">
<af:outputText value="#{row.col1}" id="ot11"/>
</af:column>
</f:facet>
<af:column sortable="false" headerText="col2" id="c12">
<af:outputText value="#{row.col2}" id="ot12"/>
</af:column>
<af:column sortable="false" headerText="col3" id="c13">
<af:outputText value="#{row.col3}" id="ot13"/>
</af:column>
<af:column sortable="false" headerText="col4" id="c14">
<af:outputText value="#{row.col4}" id="ot14"/>
</af:column>
<af:column sortable="false" headerText="col5" id="c15">
<af:outputText value="#{row.col5}" id="ot15"/>
</af:column>
</dvt:projectGantt>

26.3 ガント・チャートのタスクおよびリソースのカスタマイズ

JSFページにガント・チャートを追加した後、新しいタスク・タイプを作成すること、積上げ棒または水平線としてタスクが表示されるように構成すること、およびタスクの属性の詳細を表示することができます。

26.3.1 新しいタスク・タイプの作成

タスク・タイプは、視覚的にはガント・チャートのチャート領域の棒として表されます。新しいタスク・タイプは、次の3つのいずれかの方法で作成できます。

- JSFページまたは個別のCSSファイルでのタスク・タイプ・スタイル・プロパティの定義。

- TaskbarFormatオブジェクトの定義およびtaskbarFormatManagerによるオブジェクトの登録。

- 関連付けられたTaskbarFormatオブジェクトの取得およびsetメソッドを使用したそのプロパティの更新による、事前定義されたタスク・タイプのプロパティの変更。

TaskBarFormatオブジェクトでは次のプロパティが公開されます。

- 塗りつぶしの色

- 塗りつぶしのイメージ・パターン

- 枠の色

- マイルストン・タスクに使用されるイメージ

- サマリー・タスクの開始と終了に使用されるイメージ

分割タスクまたは再帰タスクなど、複数の棒のあるタスクでは、プロパティは個々の棒に定義されます。

例26-3に、JSFページでカスタム・タスク・タイプのプロパティを定義するサンプル・コードを示します。

例26-3 カスタム・タスク・タイプのプロパティを定義するサンプル・コード

<af:document>
<f:facet name="metaContainer">
<f:verbatim>
<![CDATA[
<style type="text/css">
.onhold
{
background-image:url('images/Bar_Image.png');
background-repeat:repeat-x;
height:13px;
border:solid 1px #000000;
}
</style>
]]>
</f:verbatim>
</f:facet>

例26-4に、TaskbarFormatオブジェクトで塗りつぶしの色と枠の色を定義し、taskbarFormatManagerにオブジェクトを登録するサンプル・コードを示します。

例26-4 TaskbarFormat Managerを使用して登録されたカスタムTaskbarFormatオブジェクト

TaskbarFormat _custom = new TaskbarFormat("Task on hold", null, "onhold", null);
//        _gantt.getTaskbarFormatManager().registerTaskbarFormat("FormatId", _custom);
TaskbarFormat _custom = new TaskbarFormat("Task on hold", "#FF00FF", null, "#00FFDD", 13);
//    _gantt.getTaskbarFormatManager().registerTaskbarFormat("FormatId", _custom);

26.3.2 リソース使用率ガント・チャートでの積上げ棒の構成

リソース使用率ガント・チャートでは、指定した期間にリソースに割り当てられ使用されている単位が時間バケットに表示されます。デフォルトでは、これらの単位は、チャート領域で縦棒としてレンダリングされます。2つ以上の棒が積み上げられるようにグラフィカル表示を構成することもできます。たとえば、図26-3のリソース使用率ガント・チャートでは、AVAILABLEリソース・メトリック棒の隣の縦棒にRUNおよびSETUPリソース・メトリックが積み上げられています。

リソース使用率ガント・チャートで積上げ棒を構成するには、setDisplayAs()メソッドを使用してTaskbarFormatオブジェクトを更新します。STACK表示を指定すると、前のメトリックにメトリックが積み上げられる形式でタスクがレンダリングされます。例26-5に、RUNメトリックが前のメトリックであるSETUPの上に積み上げられるように構成するマネージドBeanを示します。

例26-5 積上げ棒を構成するためのサンプル・コード

public class ResourceUtilizationGantt
{
private TreeModel m_model;
public String[] getMetrics()
{
return new String[]{"SETUP", "RUN", "AVAILABLE"};
}

public TaskbarFormatManager getTaskbarFormatManager()
{
TaskbarFormatManager _manager = new TaskbarFormatManager();
TaskbarFormat _format = TaskbarFormat.getInstance("Run Hours",
UIResourceUtilizationGantt.MIDNIGHT_BLUE_FORMAT);
_format.setStacked(true);

_manager.registerTaskbarFormat("SETUP", TaskbarFormat.getInstance("Setup
Hours", UIResourceUtilizationGantt.BRICK_RED_FORMAT));
_manager.registerTaskbarFormat("RUN", _format);
_manager.registerTaskbarFormat("AVAILABLE",
TaskbarFormat.getInstance("Available Hours",
UIResourceUtilizationGantt.TEAL_FORMAT));
return _manager;
}

26.3.3 リソース容量線の構成

リソース使用率ガント・チャートのチャート領域で、リソース・メトリックを縦棒として表示することに加え、チャート領域でメトリックが横線として表示されるように構成できます。これは、リソースのしきい値レベルなど、容量メトリックを表示する場合に便利です。

たとえば、図26-3に示されているリソース使用率ガント・チャートには、積上げRUNおよびSETUPメトリック、およびALLOCATEDメトリック棒に対して、しきい値メトリックを表示する容量線があります。

リソース使用率ガント・チャートでリソース容量線を構成するには、setDisplayAs()メソッドを使用してTaskbarFormatオブジェクトを更新します。STEPPED_LINE表示を指定すると、縦棒の上に水平線が表示され各メトリックを通過するという形式でタスクがレンダリングされます。例26-6に、リソース・メトリックTHRESHOLDが縦棒メトリックを通過するように構成するマネージドBeanを示します。

例26-6 リソース容量線を構成するためのサンプル・コード

public class ResourceUtilizationGanttSteppedLine
{
private TreeModel m_model;
public String[] getMetrics()
{
return new String[]{"SETUP", "RUN", "AVAILABLE", "THRESHOLD"};
}
public TaskbarFormatManager getTaskbarFormatManager()
{
TaskbarFormatManager _manager = new TaskbarFormatManager();
TaskbarFormat _format = TaskbarFormat.getInstance("Run Hours",
UIResourceUtilizationGantt.MIDNIGHT_BLUE_FORMAT);
_format.setStacked(true);

_manager.registerTaskbarFormat("SETUP", TaskbarFormat.getInstance("Setup
Hours", UIResourceUtilizationGantt.BRICK_RED_FORMAT));
_manager.registerTaskbarFormat("RUN", _format);
_manager.registerTaskbarFormat("AVAILABLE",
TaskbarFormat.getInstance("Available Hours",
UIResourceUtilizationGantt.TEAL_FORMAT));

MetricFormat _threshold = new MetricFormat("threshold", "#FF0000", null,
"#FF0000", MetricFormat.Display.STEPPED_LINE);
_manager.registerTaskbarFormat("THRESHOLD", _threshold);
return _manager;
}

26.3.4 リソース属性の詳細の表示

デフォルトでは、リソース使用率ガント・チャートの時間バケットには、固定サイズのメトリックが表示されます。たとえば、図26-19のガント・チャートでは、会社のリソースの表に対し、積上げRUNおよびSETUPメトリック、およびALLOCATEDメトリック棒が表示されています。

リソースに関連する属性により時間バケット・メトリックの詳細を取得することが必要な場合があります。たとえば、図26-19のリソース使用率ガント・チャートでは、各製品に使用された時間の実際の値によってBUDGETメトリックの詳細値が示されています。

図26-19 リソース使用率ガント・チャートのメトリック属性の詳細

リソースの属性詳細の表示を構成するには、ページ定義ファイルに子timeBucketDetailsアクセッサを追加する必要があります。例26-7に、ページ定義ファイルにアクセッサを追加するためのサンプル・コードを示します。

例26-7 ページ定義ファイルのサンプル・コード

<nodeDefinition DefName="model.GanttRugResourceAppView" type="Resources">
<AttrNames>
<Item Value="ResourceId" type="resourceId"/>
</AttrNames>
<Accessors>
<Item Value="GanttRugTimebucketAppView" type="timeBuckets"/>
</Accessors>
</nodeDefinition>
<nodeDefinition type="TimeBuckets" DefName="model.GanttRugTimebucketAppView">
<AttrNames>
<Item type="time" Value="StartDate"/>
<Item type="metric" Value="Budget"/>
</AttrNames>
<Accessors>
<Item Value="GanttRugProductAppView" type="timeBucketDetails"/>
</Accessors>
</nodeDefinition>
<nodeDefinition type="TimeBucketDetails">
<AttrNames>
<Item type="metric" Value="Actual"/>
<Item type="format" Value="Product"/>
</AttrNames>
</nodeDefinition>

リソース使用率ガント・チャートでリソースの属性詳細を構成するには、setDisplayAs()メソッドを使用してTaskbarFormatオブジェクトを更新します。例26-8に、BUDGETリソース棒に対し属性詳細メトリックを構成するマネージドBeanを示します。

例26-8 メトリック属性の詳細を構成するためのサンプル・コード

public class ResourceUtilizationGanttAttributeDetail
{
private TreeModel m_model;

public String[] getMetrics()
{
return new String[] {};
}

public TaskbarFormatManager getTaskbarFormatManager()
{
TaskbarFormatManager _manager = new TaskbarFormatManager();

_manager.registerTaskbarFormat("Wilson",
TaskbarFormat.getInstance("Wilson",
UIResourceUtilizationGantt.MIDNIGHT_BLUE_FORMAT));
_manager.registerTaskbarFormat("Umbro", TaskbarFormat.getInstance("Umbro",
UIResourceUtilizationGantt.BRICK_RED_FORMAT));
_manager.registerTaskbarFormat("Rbk", TaskbarFormat.getInstance("Rbk",
UIResourceUtilizationGantt.LAVENDER_FORMAT));
_manager.registerTaskbarFormat("Puma", TaskbarFormat.getInstance("Puma",
UIResourceUtilizationGantt.TEAL_FORMAT));
...
return _manager;
}

public TreeModel getModel()
{
if (m_model == null)
m_model =
SampleModelFactory.getResourceUtilizationGanttAttributeDetailModel();

return m_model;
}
}

26.4 ガント・チャートの表示要素のカスタマイズ

ガント・チャートをカスタマイズして、休日を表示すること、ユーザー操作機能をオフにすること、時間軸を指定すること、ガント・チャートの凡例を追加およびカスタマイズすること、ツールバーおよびコンテキスト・メニューをカスタマイズすること、およびカスタム・データ・フィルタを構成することができます。

26.4.1 ガント・チャートでの休日の指定

ガント・チャートで休日を指定できます。休日は、デフォルトでは影付きのグレーで表示されますが、休日に使用するカスタム・カラーを選択できます。

26.4.1.1 曜日を休日として指定する方法

特定の曜日が毎週の休業日である場合、その曜日を休業日のカテゴリとして指定できます。

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートが存在する必要があります。存在しない場合は、この章の指示に従い、ガント・チャートを作成します。詳細は、26.2.6項「ページへのガント・チャートの追加方法」を参照してください。

曜日を休日として指定する手順:

1. 「構造」ウィンドウで、ガント・チャート・コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「外観」カテゴリで、NonWorkingDaysOfWeekフィールドに、各週の休日として指定する曜日の文字列を入力します。たとえば、土曜日と日曜日を休日として指定するには、"sat sun"と入力します。
または、バッキングBeanにメソッドを作成し、プログラムで休日を指定することもできます。たとえば、バッキングBeanのgetNonWorkingDaysOfWeekという名前のメソッドにコードを入れる場合、nonWorkingDaysOfWeek属性の設定は、"#{myBackingBean.nonWorkingDays}"になります。例26-9に、バッキングBeanのサンプル・コードを示します。

例26-9 休日を指定するためのバッキングBean

public int[] getNonWorkingDaysOfWeek(){  if (locale == Locale.EN_US
return new int[] {Calendar.SATURDAY, Calendar.SUNDAY};  else    .......}

3. オプションで、NonWorkingDaysColorフィールドにカスタム・カラーを指定します。この属性に指定する値は、16進の色の文字列です。

26.4.1.2 特定の日付を休日として指定する方法

個々の曜日では不十分な場合、ガント・チャートで特定の日付を休日として入力できます。

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートが存在する必要があります。存在しない場合は、この章の指示に従い、ガント・チャートを作成します。詳細は、26.2.6項「ページへのガント・チャートの追加方法」を参照してください。

特定の日付を休日として指定する手順:

1. 「構造」ウィンドウで、ガント・チャート・コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」属性カテゴリを選択します。

3. nonWorkingDaysフィールドに、休日として指定する日付の文字列を入力します。たとえば、"2008-07-04 2008-11-28 2008-12-25"です。
または、バッキングBeanにメソッドを作成し、プログラムで休日を指定して、柔軟性を高めることもできます。たとえば、バッキングBeanのgetNonWorkingDaysという名前のメソッドにコードを入れる場合、nonWorkingDays属性の設定は、"#{myBackingBean.nonWorkingDays}"になります。

4. オプションで、nonWorkingDaysColorフィールドにカスタム・カラーを指定します。この属性に指定する値は、16進の色の文字列です。

26.4.2 ガント・チャート機能に読取り専用の値を適用する方法

ガント・チャートとユーザーとの対話は、featuresOffプロパティで読取り専用の値を指定するように設定することでカスタマイズして無効にすることができます。表26-5に、ガント・チャート・タイプの有効な値と無効にされた機能を示します。

表26-5 読取り専用属性の有効な値

値

無効にされる機能

asListMenu

すべてのガント・チャートの「リストとして表示」メニュー項目。

asHierMenu

すべてのガント・チャートの「階層として表示」メニュー項目。

clipboard

すべてのガント・チャートのタスクの切取り、コピーおよび貼付け。

clipboardMenu

すべてのガント・チャートの「切取り」、「コピー」および「貼付け」メニュー項目。

clipboardToolbar

すべてのガント・チャートの「切取り」、「コピー」および「貼付け」ツールバー項目。

clipboardRightMenu

すべてのガント・チャートの「切取り」、「コピー」および「貼付け」右メニュー項目。

collapseAllBelowMenu

すべてのガント・チャートの「下をすべて縮小」メニュー項目。

collapseAllMenu

すべてのガント・チャートの「すべて縮小」メニュー項目。

columnsMenu

すべてのガント・チャートの「列」メニュー項目。

createResourceMenu

リソース使用率およびスケジュール・ガント・チャートの「リソースの作成」メニュー項目。

createResourceMT

リソース使用率およびスケジュール・ガント・チャートの「リソースの作成」メニュー項目およびツールバー項目。

createResourceToolbar

リソース使用率およびスケジュール・ガント・チャートの「リソースの作成」ツールバー項目。

createTaskMenu

プロジェクトおよびスケジュール・ガント・チャートの「タスクの作成」メニュー。

createTaskMT

プロジェクトおよびスケジュール・ガント・チャートの「タスクの作成」メニューおよびツールバー。

createTaskToolbar

プロジェクトおよびスケジュール・ガント・チャートの「タスクの作成」ツールバー。

deleteMenu

プロジェクトおよびスケジュール・ガント・チャートの「削除」メニュー項目。

deleteMenu

プロジェクトおよびスケジュール・ガント・チャートの「削除」メニュー、右メニューおよびツールバー項目。

deleteRightMenu

プロジェクトおよびスケジュール・ガント・チャートの「削除」右メニュー項目。

deleteToolbar

プロジェクトおよびスケジュール・ガント・チャートの「削除」ツールバー項目。

dependencyLines

プロジェクトおよびスケジュール・ガント・チャートの依存関係線の表示および非表示。これには、プロジェクト・ガント・チャートの「依存性」メニュー・オプションが含まれます。

edit

すべてのガント・チャートのデータ・モデルへの変更。

editMenu

すべてのガント・チャートの「編集」メニュー項目。

expandAllBelowMenu

すべてのガント・チャートの「下をすべて展開」メニュー項目。

expandAllMenu

すべてのガント・チャートの「すべて展開」メニュー項目。

expandMenu

すべてのガント・チャートの「展開」メニュー項目。

filter

すべてのガント・チャートのツールバーのデータ・フィルタ操作の非表示。

goToDateMenu

すべてのガント・チャートの「日付へ移動」メニュー項目。

indenting

プロジェクトおよびスケジュール・ガント・チャートのタスクのインデントおよびアウトデント。

indentingMenu

「インデント」および「アウトデント」メニュー項目: プロジェクト・ガント・チャートのタスク、およびスケジュール・ガント・チャートとリソース使用率ガント・チャートのリソース。

indentingMenus

すべてのガント・チャートの「インデント」および「アウトデント」メニュー、ツールバーおよび右メニュー項目。

indentingRightMenu

すべてのガント・チャートの「インデント」および「アウトデント」右メニュー項目。

indentingToolbar

すべてのガント・チャートの「インデント」および「アウトデント」ツールバー項目。

legend

すべてのガント・チャートの凡例およびタスク情報の非表示および表示。

legendMenu

すべてのガント・チャートの「凡例の非表示」および「凡例の表示」メニュー項目。

legendToolbar

すべてのガント・チャートの「凡例の非表示」および「凡例の表示」ツールバー項目。

linking

プロジェクトおよびスケジュール・ガント・チャートのタスクのリンクおよびリンク解除。

linkingMenu

プロジェクトおよびスケジュール・ガント・チャートの「リンク」および「リンク解除」メニュー項目。

linkingMenus

プロジェクトおよびスケジュール・ガント・チャートの「リンク」および「リンク解除」メニュー、右メニューおよびツールバー項目。

linkingRightMenu

プロジェクトおよびスケジュール・ガント・チャートの「リンク」および「リンク解除」右メニュー項目。

linkingToolbar

プロジェクトおよびスケジュール・ガント・チャートの「リンク」および「リンク解除」ツールバー項目。

listPaneMenu

すべてのガント・チャートの「リスト・ペイン」メニュー項目。

print

すべてのガント・チャートの印刷タスク。

printMenu

すべてのガント・チャートの「印刷」メニュー項目。

printToolbar

すべてのガント・チャートの「印刷」ツールバー項目。

properties

すべてのガント￥チャートのプロパティ・ダイアログを表示します。

propertiesMenu

すべてのガント・チャートの「プロパティ」メニュー項目。

propertiesRightMenu

すべてのガント・チャートの「プロパティ」右メニュー項目。

resourceMenu

リソース使用率およびスケジュール・ガント・チャートの「リソース」メニュー項目。

snapToMenu

スケジュール・ガント・チャートの「スナップ」メニュー項目。

snapToRightMenu

スケジュール・ガント・チャートの「スナップ」右メニュー項目。

split

プロジェクト・ガント・チャートのタスクの分割およびマージ。

splittingMenu

プロジェクト・ガント・チャートの「分割」および「マージ」メニュー項目。

splittingMenus

プロジェクト・ガント・チャートの「分割」および「マージ」メニュー、右メニューおよびツールバー項目。

splittingRightMenu

プロジェクト・ガント・チャートの「分割」および「マージ」右メニュー項目。

splittingToolbar

プロジェクト・ガント・チャートの「分割」および「マージ」ツールバー項目。

taskMenu

プロジェクトおよびスケジュール・ガントの「タスク」メニュー。

timeAxisMenu

すべてのガント・チャートの「時間軸」メニュー項目。

timeBucketMenu

リソース使用率ガント・チャートの「時間バケット」メニュー項目。

undo

すべてのガント・チャートの元に戻すおよびやり直しタスク。

undoMenu

すべてのガント・チャートの「元に戻す」および「やり直し」メニュー項目。

updateResourceMenu

スケジュール・ガント・チャートの「リソースの更新」メニュー項目。

updateTaskMenu

プロジェクトおよびスケジュール・ガント・チャートの「タスクの更新」メニュー項目。

updateTaskMT

プロジェクトおよびスケジュール・ガントの「タスク編集の更新」項目、「タスクの更新」ツールバー項目および右メニュー項目。

updateTaskRightMenu

プロジェクトおよびスケジュール・ガント・チャートの「タスクの更新」右メニュー項目。

updateTaskToolbar

プロジェクトおよびスケジュール・ガント・チャートの「タスクの更新」ツールバー項目。

undoToolbar

すべてのガント・チャートの「元に戻す」および「やり直し」ツールバー項目。

view

すべてのガント・チャートでのリストとして表示、階層として表示、列、展開および縮小タスク。

viewMenu

すべてのガント・チャートの「表示」メニュー項目。

zoom

すべてのガント・チャートのズーム・レベルへの変更。

zoomToolbar

すべてのガント・チャートの「ズーム」メニュー項目。

zoomToToolbar

すべてのガント・チャートの「ズームしてあわせる」メニュー・ツールバー項目。

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートが存在する必要があります。存在しない場合は、この章の指示に従い、ガント・チャートを作成します。詳細は、26.2.6項「ページへのガント・チャートの追加方法」を参照してください。

ガント・チャート機能に読取り専用の値を設定する手順:

1. 構造ウィンドウでガント・チャートのノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「動作」属性カテゴリで、featuresOff属性に1つ以上の文字列値を入力して、無効にするガント・チャート機能を指定します。
たとえば、データ・モデル編集、印刷またはガント・チャートのズーム・レベル変更のためのユーザーとの対話を無効にするには、featuresOff属性をedit print zoomのように設定します。

または、バッキングBeanにメソッドを作成し、プログラムで機能を無効にすることもできます。たとえば、バッキングBeanのwhatToTurnOffという名前のメソッドにコードを入れる場合、featuresOff属性の設定は、"#{BackingBean.whatToTurnOff}"になります。

26.4.3 ガント・チャートの時間軸のカスタマイズ方法

各ガント・チャートは、主時間軸と副時間軸を使用して作成されます。各時間軸には、時間のレベルを主または副で示すファセットがあります。すべてのガント・チャートのデフォルトの時間軸設定は次のとおりです。

- 主時間軸: 週

- 副時間軸: 日

時間軸の設定をカスタマイズできます。ただし、主軸は副軸より高い時間レベルに設定する必要があります。次に、dvt:timeAxisコンポーネントのscaleの設定値を高いものから順にリストします。

- twoyears

- year

- halfyears

- quarters

- twomonths

- months

- twoweeks

- weeks

- days

- sixhours

- threehours

- hours

- halfhours

- quarterhours

例26-26に、monthsを主時間軸、weeksを副時間軸として使用するように、ガント・チャートの時間軸を設定するサンプル・コードを示します。

例26-10 monthsとweeksに設定したガント・チャートの時間軸

<f:facet name="major">
<dvt:timeAxis scale="months"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="weeks"/>
</f:facet>

主軸および副軸に指定した時間単位は、ガント・チャートの初期表示にのみ適用されます。実行時に、ユーザーは時間軸をズーム・インまたはズーム・アウトして別のレベルの時間単位で表示できます。

ガント・チャートのカスタム時間軸を作成し、その軸をdvt:timeAxisのscale属性で指定できます。カスタム時間軸は、実行時に「タイム・スケール」ダイアログに追加されます。

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートが存在する必要があります。存在しない場合は、この章の指示に従い、ガント・チャートを作成します。詳細は、26.2.6項「ページへのガント・チャートの追加方法」を参照してください。

カスタム時間軸を作成し使用する手順:

1. CustomTimescale.javaインタフェースを実装して、時間軸を作成するためにgetNextDate(Date currentDate)メソッドをループでコールします。例26-11に、インタフェースのサンプル・コードを示します。

例26-11 カスタム日付を作成するインタフェース

public interface CustomTimescale
{
public String getScaleName();
public Date getPreviousDate(Date ganttStartDate);
public Date getNextDate(Date currentDate);
public String getLabel(Date date);
}

2. 構造ウィンドウでガント・チャートのノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウの「その他」属性カテゴリで、「CustomTimeScales」属性に、カスタム時間軸にインタフェースの実装を登録します。
customTimeScales属性の値は、java.util.Mapオブジェクトです。指定したマップ・オブジェクトには、キー/値のペアが含まれます。キーはタイム・スケール名(fiveyears)で、値はCustomTimeScale.javaインタフェースの実装です。次に例を示します。

customTimesScales="#{project.customTimescales}"

4. また「プロパティ」ウィンドウで、主時間軸および副時間軸のScale属性を設定し、カスタム時間軸にズームするためのZoomOrder属性を指定します。例26-12に、threeyears副時間軸とfiveyears主時間軸を設定するためのサンプル・コードを示します。

例26-12 カスタム時間軸

<f:facet name="major">
<dvt:timeAxis scale="fiveyears" id="ta1" zoomOrder="fiveyears threeyears years halfyears quarters months weeks days hours"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="threeyears" id="ta2"/>
</f:facet>

26.4.4 ガント・チャートの凡例の作成およびカスタマイズ

オプションのガント・チャートの凡例サブコンポーネントには、選択されたタスクまたは選択された時間バケットに関するメトリックに関する詳細情報が表示される領域、およびガント・チャートの各タスク・タイプを表すために使用される記号および色コード・バーが含まれています。実行時に、ツールバー・ボタンを使用して情報パネルを表示または非表示にできます。

凡例エリアを用意するには、ガント・チャート・タグの子としてganttLegendタグを追加する必要があります。凡例エリアのコンテンツは、taskbarFormatManagerで登録された各タスク・タイプのプロパティに基づいて自動的に生成されます。

ガント・チャートの凡例タグでkeys属性およびlabel属性を使用してタスクまたは時間バケットが選択された場合に表示される情報をカスタマイズできます。keys属性では、表示する値の取得に使用されるデータ・オブジェクト・キーを指定し、labels属性には、キーで取得した値に対応するラベルが含まれる必要があります。これらの属性が指定されていないと、凡例で情報パネルの領域全体が使用されます。

ガント・チャートの凡例タグでiconKeys属性およびiconLabels属性を使用して、凡例にアイコンを追加することもできます。アイコンのサイズが大きすぎる場合は、自動的に縦横12ピクセルにサイズ変更されます。

例26-13に、プロジェクト・ガント・チャートの凡例に保留中タスクに関する情報を表示するサンプル・コードを示します。

例26-13 ガント・チャートの凡例の追加

<dvt:projectGantt var="task">
<dvt:ganttLegend id="gl" keys="TaskName StartTime EndTime" labels="Name Start Finish" icons="images/wait.png" iconLabels="OnHold"/>
</dvt:projectGantt>

26.4.5 ガント・チャートのツールバーのカスタマイズ

ガント・チャート・ツールバー・サブコンポーネントを使用すると、ガント・チャートの操作を実行できます。ツールバーの左側の部分には、各ガント・チャート・タイプに対するデフォルトのメニュー・オプション・セットを含むメニュー・バーがあります。ツールバーの右側の部分には、各ガント・チャート・タイプを操作するためのデフォルトのアクション・ボタンのセットが表示されます。

ガント・チャートのmenuファセットおよびtoolbarファセットを使用することによって、独自のメニュー項目およびツールバー・ボタンを使用できます。ガント・チャートでは、新しいメニュー項目と標準の項目がマージされます。例26-14に、新しいメニュー項目を指定するサンプル・コードを示します。

例26-14 カスタム・メニュー項目のサンプル・コード

<dvt:projectGantt var="task">
<f:facet name=”menuBar”>
<af:menu text=”My Menu”>
<af:commandMenuItem text="Add..." />
<af:commandMenuItem text="Create.." />
</af:menu>
</f:facet>
</dvt:projectGantt>

例26-15に、新しいツールバー・ボタンを指定するサンプル・コードを示します。

例26-15 カスタム・ツールバー・ボタンのサンプル・コード

<dvt:schedulingGantt var="task">
<f:facet name="toolbar">
<af:toolbar>
<af:button text="Custom" disabled="true"/>
</af:toolbar>
</dvt:schedulingGantt>

メニュー・バーおよびツールバー・ボタンで開始されるアクションは、登録されたリスナー、DataChangeListenerを使用してガント・チャート・コンポーネント上で処理されます。たとえば、ユーザーがツールバーで削除ボタンを押すと、削除に選択されたタスクのIDを持つDataChangeEventがサーバー上で開始されます。登録されたリスナーがタスクの実際の削除を行い、ガント・チャート・データ・モデルは更新された情報を使用して更新されます。

ガント・チャート・タグでdataChangeListener属性を使用してメソッド・バインディングを指定することによってDataChangeListenerを登録できます。たとえば、バッキングBeanのhandleDataChangeという名前のメソッドにコードを入れる場合、dataChangeListener属性の設定は、"#{myBackingBean.handleDataChange}"になります。

例26-16に、バッキングBeanのサンプル・コードを示します。

例26-16 データ変更を処理するためのバッキングBean

public void handleDataChanged(DataChangeEvent evt)
{
if (DataChangeEvent.DELETE == evt.getActionType())
…………
}

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してガント・チャートを作成できます。デフォルトでは、dataChangeListenerには自動的にイベントが提供されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ変更イベント処理に関する必知事項を参照してください。

26.4.6 ガント・チャートのポップアップ・メニューのカスタマイズ

ユーザーがガント・チャートの表領域またはチャート領域を右クリックすると、ガント・チャートを操作するポップアップ・メニューが表示されます。各領域に標準のオプションのセットが提供されます。

ガント・チャートのtablePopupMenuファセットおよびchartPopupMenuファセットを使用することによって、独自のメニュー項目を使用できます。ガント・チャートでは、新しいメニュー項目と標準の項目がマージされます。例26-17に、表領域のポップアップ・メニューにカスタム・メニュー項目を指定するサンプル・コードを示します。

例26-17 カスタム・ポップアップ・メニュー項目のサンプル・コード

<dvt:projectGantt startTime="#{test.startTime}" endTime="#{test.endTime}"
value="#{test.treeModel}" var="task">

<f:facet name="tablePopupMenu">
<af:popup>
<af:commandMenuItem text="Custom" disabled="true"/>
</af:popup>
</f:facet>
</dvt:projectGantt>

実行時にポップアップ・メニューを動的に変更することもできます。例26-18に、プロジェクト・ガント・チャートのチャート領域で選択したタスクに基づいてタスク・バーでカスタム・コンテキスト・メニューを更新するサンプル・コードを示します。

例26-18 動的ポップアップ・メニュー項目のサンプル・コード

<dvt:projectGantt var="task"
taskSelectionListener="#{backing.handleTaskSelected}">
<f:facet name="chartPopupMenu">
<af:popup id="p1" contentDelivery="lazyUncached">
<af:menu>
</af:menu>
</af:popup>
</f:facet>
</dvt:projectGantt>

handleTaskSelectedメソッドは、バッキングBeanで指定されます。例26-19に、バッキングBeanのサンプル・コードを示します。

例26-19 タスク選択を処理するためのバッキングBean

public void handleTaskSelected(TaskSelectionEvent evt)
{
JUCtrlHierNodeBinding _task = (JUCtrlHierNodeBinding)evt.getTask();
String _type = _task.getAttribute("TaskType");

RichPopup _popup = m_gantt.getFacet("chartPopupMenu");
if (_popup != null)
{
RichMenu _menu = (RichMenu)_popup.getChildren().get(0);
_menu.getChildren().clear();
if ("Summary".equals(_type))
{
RichCommandMenuItem _item = new RichCommandMenuItem();
_item.setId("i1");
_item.setText("Custom Action 1");
_menu.getChildren().add(_item);                          }
else if ("Normal".equals(_type))
{
RichCommandMenuItem _item = new RichCommandMenuItem();
_item.setId("i1");
_item.setText("Custom Action 2");
_menu.getChildren().add(_item);                          }
}
}

af:popupコンポーネントの使用方法の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

26.4.7 カスタム・データ・フィルタの指定方法

ツールバーからデータ・フィルタ・ドロップダウン・リストを使用してガント・チャートのデータ表示を変更できます。ガント・チャートではFilterManagerを使用して、すべての事前定義済およびユーザー指定のデータ・フィルタを管理できます。フィルタ・オブジェクトには次の情報が含まれます。

- フィルタの一意のID

- ドロップダウン・リストにフィルタを表示するためのラベル

- フィルタが選択されたときに起動するオプションのJavaScriptメソッド

フィルタ・オブジェクトを作成し、FilterManagerでaddFilterメソッドを使用してオブジェクトを登録して独自のフィルタを定義できます。例26-20に、FilterManagerを使用してResourceフィルタ・オブジェクトを登録するサンプル・コードを示します。

例26-20 FilterManagerを使用して登録されたカスタム・フィルタ・オブジェクト

FilterManager _manager = m_gantt.getFilterManager();

// ID for filter display label   javascript callback (optional)
_manager.addFilter((new Filter(RESOURCE_FILTER, "Resource...", "showResourceDialog")));

ユーザーがフィルタを選択すると、フィルタ・ロジックを実行する、登録されたFilterListenerにFilterEventが送信されます。リスナーの登録には、ガント・チャート・コンポーネントのfilterListener属性が使用されます。アプリケーションによって実装されると、データ・モデルが更新され、ガント・チャート・コンポーネントにフィルタ処理された結果が表示されます。例26-21に、FilterListenerのサンプル・コードを示します。

例26-21 カスタム・フィルタのFilterListener

public void handleFilter(FilterEvent event)
{
String _type = event.getType();
if (FilterEvent.ALL_TASKS.equals(_type))
{
// update the gantt model as appropriate
}
}

始める前に:

ガント・チャートの属性やガント・チャートの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、26.2.5項「ガント・チャートの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、26.1.3項「ガント・チャート・コンポーネントの追加機能」を参照してください。

ページにガント・チャートが存在する必要があります。存在しない場合は、この章の指示に従い、ガント・チャートを作成します。詳細は、26.2.6項「ページへのガント・チャートの追加方法」を参照してください。

カスタム・データ・フィルタを指定する手順:

1. 「構造」ウィンドウで、ガント・チャート・コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「動作」カテゴリのFilterListenerフィールドに、定義したFilterListenerを参照するメソッドを入力します。"#{project.handleFilter}"などです。

26.5 ガント・チャートへのインタラクティブ機能の追加

スクロールバー、同期スクロールのかわりとしてページ・コントロールを追加する、タスク・バーにダブルクリック・イベントを追加する、ガント・チャートを印刷するなど、ガント・チャートにインタラクティブ機能を追加できます。

26.5.1 選択したタスクまたはリソースでのアクションの実行

ガント・チャートでは、ユーザーは、タスクまたはリソースを表すガント・チャートの表領域で1つ以上の行を選択し、それらの行に対しアクションを実行できます。ガント・チャートの選択状態が変更されると、選択イベントがトリガーされます。selectionEventイベントは、選択解除された行と選択された行をレポートします。

ガント・チャートで選択イベントをリスニングするために、selectionListener属性を使用することで、またはaddselectionListener()メソッドを使用してガント・チャートにリスナーを追加することで、ガント・チャートにリスナーを登録できます。これにより、リスナーは選択された行にアクセスし、それらの行に対してアクションを実行できます。

現在の選択内容(選択された1つ以上の行)はRowKeySetオブジェクトであり、このオブジェクトは、ガント・チャートに対しgetSelectedRowKeys()メソッドをコールして取得します。プログラムを使用して選択内容を変更するには、次のいずれかを実行します。

- RowKeySetオブジェクトでrowKeyオブジェクトを追加するか、rowKeyオブジェクトを削除します。

- ガント・チャートに対しsetRowIndex()またはsetRowKey()メソッドをコールして、特定の行を現在行にします。その後、RowKeySetオブジェクトに対してadd()またはremove()メソッドをコールして、その行を選択内容に追加するか、選択内容から削除できます。

例26-22に表の一部を示します(この部分では、ユーザーが複数の行を選択し、「削除」ボタンをクリックしてそれらの行を削除できます)。アクション・リスナーは、mybeanマネージドBeanのperformDeleteメソッドにバインドされます。

例26-22 行の選択

<af:table binding="#{mybean.table}" rowselection="multiple" ...>
...
</af:table>
<af:button text="Delete" actionListener="#{mybean.performDelete}"/>

例26-23に、選択されたすべての行を反復し、それぞれにmarkForDeletionメソッドをコールするアクション・メソッドperformDeleteを示します。

例26-23 rowKeyオブジェクトの使用

public void performDelete(ActionEvent action)
{
UIXTable table = getTable();
Iterator selection = table.getSelectedRowKeys().iterator();
Object oldKey = table.getRowKey();
try
{
while(selection.hasNext())
{
Object rowKey = selection.next();
table.setRowKey(rowKey);
MyRowImpl row = (MyRowImpl) table.getRowData();
//custom method exposed on an implementation of Row interface.
row.markForDeletion();
}
}
finally
{
// restore the old key:
table.setRowKey(oldKey);
}
}

26.5.2 ガント・チャートでのページ・コントロールの使用方法

ガント・チャートの表領域では、デスクトップ・アプリケーションとタッチ装置のモバイル・ブラウザの両方に対して、横のスクロール機能のかわりにページ・コントロールを使用できます。このコントロールは、データ・フェッチ・サイズを超える行が存在し、かつコンポーネントがそれを含むレイアウト・コンポーネントによって拡大されない場合にのみ使用できます。ページ・コントロールは、図26-20に示すように、表領域のフッターとして表示されます。

図26-20 ガント・チャートのページ・コントロール

ADF Faces Webアプリケーションを開発する場合、ガント・チャートの表領域では、フェッチ対象のデータのサイズを超える列を表示するために、横のスクロールバーがデフォルトで使用されます。schedulingGantt、projectGanttまたはresourceUtilizationGanttコンポーネントの表領域に、かわりにページ・コントロールを構成するには、scrollPolicy属性をpageに設定します。次に例を示します。

scrollPolicy="page"

ただし、標準ADF Faces Webアプリケーションはモバイル・ブラウザで動作しますが、ユーザーの操作が異なり、スクリーン・サイズが制限されるため、アプリケーションをモバイル・ブラウザで実行する必要がある場合は、タッチ装置に固有のバージョンのページを作成する必要があります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

デフォルトでは、モバイル・デバイスにレンダリングする場合、ガント・チャートの表領域には、ユーザーが特定の行のページにジャンプできるページ・コントロールが表示されます。モバイル・デバイスに表示するすべてのガント・チャートには、次の処理が必要です。

- ガント・チャート・コンポーネントをフロー・コンテナ(つまり、子を拡大しないコンポーネント)の中に配置します。フロー・コンテナ・コンポーネントの詳細は、第9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- scrollPolicy属性をauto(ページがデスクトップ・デバイスでも実行される場合)、またはpage(ページがモバイル・デバイスのみで実行される場合)に設定します。

ガント・チャートがフロー・コンテナの中にない場合、または属性が正しく設定されていない場合は、ページではなくスクロールバーが表示されます。

26.5.3 ガント・チャート間の同期スクロールの構成

2つのガント・チャートのチャート側間で横方向の同期スクロールを構成できます。たとえば、図26-21に示されているように、プロジェクト・ガント・チャートとリソース使用率ガント・チャートのスクロールバーを同期して、同じプロジェクトのタスクとリソースが表示されるようにすることが必要な場合があります。

図26-21 ガント・チャート間で同期されたスクロール

ガント・チャート間で同期されたスクロールを構成するには、af:clientListenerコンポーネントを使用して、スクロール対象のガント・チャートのチャート側でchartHorizontalScrollイベントをリスニングし、他のガント・チャートでスクロール位置を設定します。

この例では、インラインJavaScriptを使用して、af:resourceタグ内で同期スクロールのためのメソッドを定義しています。例26-24に、同期スクロール・メソッドのコードを示します。詳細は、4.2項「JavaScriptのページへの追加」を参照してください。

例26-24 同期スクロール・メソッドのサンプル・コード

<af:resource type="javascript">
var gantt1ScrollStart = null;
var gantt2ScrollStart = null;
//called when the top gantt component is scrolled
function handleTopScroll(event)
{
var eventScrollStart = event.getScrollStart();
if (gantt2ScrollStart == null || gantt2ScrollStart == eventScrollStart)
{
// clear synced gantt scroll start
gantt2ScrollStart = null;
// find the corresponding gantt component
var gantt = AdfPage.PAGE.findComponent("demo:gantt2");
if (gantt1ScrollStart != event.getScrollStart())
{
// set the scrollStart position of the synced gantt to match the
event's value
var scrollStart = gantt.getChartScrollStart();
if (scrollStart != eventScrollStart)
{
//save the scrollStart value to stop feedback
gantt1ScrollStart = eventScrollStart;
gantt.setChartScrollStart(eventScrollStart);
}
}
}
event.cancel();
}

// called when the bottom gantt component is scrolled
function handleBottomScroll(event)
{
var eventScrollStart = event.getScrollStart();
if (gantt1ScrollStart == null || gantt1ScrollStart == eventScrollStart)
{
// clear synced gantt scroll start
gantt1ScrollStart = null;
// find the corresponding gantt component
var gantt = AdfPage.PAGE.findComponent("demo:gantt1");
if (gantt2ScrollStart != event.getScrollStart())
{
// set the scrollStart position of the synced gantt to match the
event's value
var scrollStart = gantt.getChartScrollStart();
if (scrollStart != eventScrollStart)
{
//save the scrollStart value to stop feedback
gantt2ScrollStart = eventScrollStart;
gantt.setChartScrollStart(eventScrollStart);
}
}
}
event.cancel();
}
</af:resource

例26-25に示されている両方のガント・チャートのコードでは、ガント・チャートのchartHorizontalScrollタイプのscrollEventをリスニングするclientListenerを指定し、例26-24のaf:resourceコンポーネントで定義されているhandleTopScrollメソッドおよびhandleBottomScrollメソッドを呼び出しています。

例26-25 ガント・チャートで同期スクロールを使用するためのJSFページのサンプル・コード

<dvt:projectGantt id="gantt1" var="task" startTime="2008-04-22"
endTime="2008-09-31" inlineStyle="height:400px;"
value="#{projectGantt.model}"
tooltipKeys="#{projectGantt.tooltipKeys}"
tooltipKeyLabels="#{projectGantt.tooltipLabels}"
summary="Project Gantt">
<f:facet name="major">
<dvt:timeAxis scale="weeks" id="ta1"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="days" id="ta2"/>
</f:facet>
<f:facet name="nodeStamp">
<af:column headerText="Task Name" id="c1">
<af:outputText value="#{task.taskName}" id="ot1"/>
</af:column>
</f:facet>
<af:column headerText="Resource" id="c2">
<af:outputText value="#{task.resourceName}" id="ot2"/>
</af:column>
<af:column headerText="Start Date" id="c3">
<af:outputText value="#{task.startTime}" id="ot3"/>
</af:column>
<af:column headerText="End Date" id="c4">
<af:outputText value="#{task.endTime}" id="ot4"/>
</af:column>
<dvt:ganttLegend keys="#{projectGantt.legendKeys}"
labels="#{projectGantt.legendLabels}"
id="gl1"/>
<af:clientListener type="chartHorizontalScroll" method="handleTopScroll"/>
</dvt:projectGantt>
<dvt:schedulingGantt id="gantt2" startTime="2006-12-21 01:00"
endTime="2006-12-22 23:00"
value="#{schedulingGantt.model}" var="resourceObj"
inlineStyle="height:400px;"
tooltipKeyLabels="#{schedulingGantt.tooltipLabels}"
tooltipKeys="#{schedulingGantt.tooltipKeys}"
summary="Scheduling Gantt Demo">
<f:facet name="major">
<dvt:timeAxis scale="days" id="ta3"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="hours" id="ta4"/>
</f:facet>
<f:facet name="nodeStamp">
<af:column headerText="Employee Name" id="c5">
<af:outputText value="#{resourceObj.resourceName}" id="ot5"/>
</af:column>
</f:facet>
<af:column headerText="Department" id="c6">
<af:outputText value="#{resourceObj.department}" id="ot6"/>
</af:column>
<dvt:ganttLegend keys="#{schedulingGantt.legendKeys}"
labels="#{schedulingGantt.legendLabels}"
id="gl2"/>
<af:clientListener type="chartHorizontalScroll" method="handleBottomScroll"/>
</dvt:schedulingGantt>

26.5.4 ガント・チャートの印刷

ADFのガント・チャートには、書式設定されたオブジェクト(FO)を生成できるヘルパー・クラス(GanttPrinter)が用意されており、ApacheまたはXML Publisherと連動してPDFファイルが生成されます。

26.5.4.1 印刷オプション

通常、GanttPrinterクラスでは、ガント・チャートのコンテンツが画面に表示されたとおりに印刷されます。たとえば、ガント・チャートで凡例を非表示にすると、凡例は印刷されません。同様に、「表示」メニューの「リスト・ペイン」セクションで列を選択解除した場合、その列はガント・チャートで非表示となり、列の可視性印刷オプションを利用しないかぎり、印刷にも表示されません。

GanttPrinterクラスでは、次の印刷オプションが使用できます。

- 列の可視性: setColumnVisibleメソッドでは、ガント・チャートのリスト領域の個々の列を印刷出力に表示するかどうかを制御できます。
たとえば、ガント・チャートのリスト領域の最初の列を非表示にするには、_printer.setColumnVisible(o, false);というコードを使用します。メソッドの最初のパラメータはゼロベースの列の索引で、2番目のパラメータは印刷されたガント・チャートに列を表示するかどうかを示します。

- マージン: GanttPrinterのsetMarginメソッドでは、次のコードで示すように、上、下、左および右マージンをピクセルで指定できます。ここで、_printerはGanttPrinterクラスのインスタンスです。
_printer.setMargin(25, 16, 66, 66);

- ページ・サイズ: GanttPrinterのsetPageSizeメソッドでは、次のコードで示すように、印刷されたページの高さと幅をピクセルで指定できます。ここで、_printerはGanttPrinterのインスタンスです。
_printer.setPageSize (440, 600);

- 期間: GanttPrinterクラスのsetStartTimeおよびsetEndTimeでは、印刷するガント・チャートの期間を指定できます。
例26-26に、ガント・チャートの特定期間を印刷対象として設定するサンプル・コードを示します。startDateとendDateは対象の日付を表す変数で、_printerはGanttPrinterクラスのインスタンスです。

例26-26 ガント・チャートを印刷するための期間オプションを設定するコード

_printer.setStartTime(startDate);
_printer.setEndTime(endDate);

26.5.4.2 印刷イベントを処理するアクション・リスナー

ガント・チャートのツールバーには印刷ボタンがあり、印刷アクションが開始されます。ガント・チャートを印刷するには、印刷イベントを処理するActionListenerを作成する必要があります。ActionListenerのコードには、次のプロセスを含める必要があります。

1. サーブレットの出力ストリームへのアクセス。

2. FOの生成。このプロセスには、GanttPrinterのインスタンスの作成と、使用する印刷オプションのコードの記述が含まれます。

3. PDFの生成。

例26-27に、印刷イベントを処理するActionListenerのコードを示します。このリスナーには、GanttPrinterヘルパー・クラスで使用できるすべての印刷オプションの設定が含まれます。

例26-27 ガント・チャートの印刷イベントを処理するサンプルActionListener

public void handleAction(GanttActionEvent evt)
{
if (GanttActionEvent.PRINT == evt.getActionType())
{
FacesContext _context = FacesContext.getCurrentInstance();
ServletResponse _response = (ServletResponse)
_context.getExternalContext().getResponse();
_response.setContentType("application/pdf");
ServletOutputStream _sos = _response.getOutputStream();
// Generate FO.
GanttPrinter _printer = new GanttPrinter(m_gantt);
// Set column visibility by column index.
_printer.setColumnVisible(0, false);
// Set start and end date.
_printer.setStartTime(startDate);
_printer.setEndTime(endDate);
// Set top, bottom, left, and right margins in pixels.
_printer.setMargin(25, 16, 66, 66);
// Set height and width in pixels.
_printer.setPageSize(440, 660);
File _file = File.createTempFile("gantt", "fo");
OutputStream _out = new FileOutputStream(_file);
_printer.print(_out);
_out.close();
// generate PDF.
FOProcessor _processor = new FOProcessor();
_processor.setData(new FileInputStream(_file),"UTF-8"));
_processor.setOutputFormat(FOProcessor.FORMAT_PDF);
_processor.setOutput(_sos);
_processor.generate();
_context.responseComplete();
response.setHeader("Cache-Control", "no-cache");
}
}

26.5.5 タスク・バーへのダブルクリック・イベントの追加

ガント・チャート・コンポーネントでは、タスク・バーのダブルクリック・イベントがサポートされています。たとえば、ポップアップ・ウィンドウでタスクに関する詳細な情報が表示されるように設定できます。図26-22に、タスク・バーにダブルクリック・イベントを使用するプロジェクト・ガント・チャートを示します。

図26-22 ダブルクリック・イベントを使用したタスク・バー

例26-28に、タスク・バーにダブルクリック・イベントを追加するサンプル・コードを示します。

例26-28 ダブルクリック・イベントのサンプル・コード

<dvt:projectGantt id="projectGanttDoubleClick"
startTime="2008-04-01" endTime="2008-09-30"
value="#{projectGanttDoubleClick.model}"
var="task"
doubleClickListener="#{projectGanttDoubleClick.handleDoubleClick}">
</dvt:projectGantt>

たとえば、次のようにバッキングBeanでhandleDoubleClickメソッドを実装します。

public void handleDoubleClick(DoubleClick event)

26.5.6 ドロップ・ターゲットまたはドラッグ・ソースとしてのガント・チャートの使用

ユーザーがコレクションからアイテム(表から行など)をドラッグし、ツリーなどの別のコレクション・コンポーネントにドロップできるドラッグ・アンド・ドロップ機能を追加できます。プロジェクト・ガント・チャート・コンポーネントおよびスケジュール・ガント・チャート・コンポーネントは、ADFの表またはツリー表コンポーネントのドラッグ・ソースおよびドロップ・ターゲットとして有効にできます。リソース使用率ガント・チャート・コンポーネントは、ドロップ・ターゲットとしてのみ有効にできます。

アプリケーションでは、af:collectionDragSource動作タグまたはaf:collectionDropTarget動作タグをガント・タグの子として追加して、ドラッグ・ソースまたはドロップ・ターゲットとしてガント・チャート・コンポーネントを登録する必要があります。たとえば、af:collectionDragSourceを使用して、プロジェクト・ガント・チャート・タスクが表領域から別の表にドラッグされたときに起動されるドロップ・リスナーを登録できます。図26-23に、表領域からタスクの表にドラッグされるタスクがあるプロジェクト・ガント・チャートを示します。

図26-23 ドラッグ元としてのプロジェクト・ガント・チャート

表26-29に、プロジェクト・ガント・チャートにドラッグ・アンド・ドロップ機能を追加するサンプル・コードを示します。

例26-29 ドラッグ・アンド・ドロップ機能を追加するサンプル・コード

<dvt:projectGantt id="projectGanttDragSource"
startTime="2008-04-01" endTime="2008-09-30"
value="#{projectGanttDragSource.model}"
var="task"
summary="Project Gantt Drag Source Demo">
<f:facet name="major">
<dvt:timeAxis scale="months" id="ta1"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="weeks" id="ta2"/>
</f:facet>
<af:collectionDragSource actions="COPY MOVE" modelName="treeModel"/>
<f:facet name="nodeStamp">
<af:column headerText="Task Name" id="c1">
<af:outputText value="#{task.taskName}" id="ot1"/>
</af:column>
</f:facet>
<af:column headerText="Resource" id="c2">
<af:outputText value="#{task.resourceName}" id="ot2"/>
</af:column>
<af:column headerText="Start Date" id="c3">
<af:outputText value="#{task.startTime}" id="ot3"/>
</af:column>
<af:column headerText="End Date" id="c4">
<af:outputText value="#{task.endTime}" id="ot4"/>
</af:column>
</dvt:projectGantt>

例26-30に、ドロップ・イベントを処理するリスナー・メソッドのサンプル・コードを示します。

例26-30 コレクションのdropListenerのイベント・ハンドラ・コード

public DnDAction onTableDrop(DropEvent evt)
{
Transferable _transferable = evt.getTransferable();

// Get the drag source, which is a row key, to identify which row has been dragged.
RowKeySetImpl _rowKey = (RowKeySetImpl)_transferable.getTransferData(DataFlavor.ROW_KEY_SET_FLAVOR).getData();

// Set the row key on the table model (source) to get the data.
// m_tableModel is the model for the Table (the drag source).
object _key = _rowKey.iterator().next();
m_tableModel.setRowKey(_key);

// See on which resource this is dropped (specific for scheduling Gantt chart).
String _resourceId = _transferable.getData(String.class);
Resource _resource = findResourceById(_resourceId);

// See on what time slot did this dropped.
Date _date = _transferable.getData(Date.class);

// Add code to update your model here.

// Refresh the table and the Gantt chart.
RequestContext.getCurrentInstance().addPartialTarget(_evt.getDragComponent());
RequestContext.getCurrentInstance().addPartialTarget(m_gantt);

// Indicate the drop is successful.
return DnDAction.COPY;
}

コレクションのドラッグ・アンド・ドロップ機能の追加の詳細は、36.4項「コレクションのドラッグ・アンド・ドロップ機能の追加」を参照してください。

27 時系列コンポーネントの使用

この章では、ADFデータ視覚化のtimelineコンポーネントを使用し、簡単なUI優先開発を使用してデータを表示する方法について説明します。データ要件、タグ構造、およびコンポーネントの概観と動作をカスタマイズするためのオプションの定義についても説明します。

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して時系列を作成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 27.1項「時系列コンポーネントについて」

- 27.2項「時系列コンポーネントの使用」

- 27.3項「時系列コンポーネントへのデータの追加」

- 27.4項「時系列表示要素のカスタマイズ」

- 27.5項「インタラクティブ機能の時系列への追加」

27.1 時系列コンポーネントについて

対話型のデータ視覚化ツールであるtimelineを使用すると、ユーザーはイベントを時間順に表示して、定義された時間範囲内で時間を進めたり戻したりできます。各イベントは時系列アイテムとして表され、単純なADFコンポーネントを使用してテキストやイメージなどの情報を表示したり、リンクなどのアクションを提供したりします。2つの時系列を構成して2系列のイベントを表示し、関連する情報を並べて比較することもできます。

時系列コンポーネントでは、関連付けられた時系列アイテムのグループ(共通の雇用日など)やアクティビティのグループ(多数ある従業員用書類の記入完了など)を開いたり、閉じたりできます。また、時系列コンポーネントでは、時間範囲を調整して表示を変更し、ズーム・インやズーム・アウトを行う機能もサポートします。

27.1.1 時系列のユースケースと例

時系列は、時間軸に沿った時系列アイテムとしてのイベントの表示、時系列に表示可能な期間に対応する移動可能な概要ウィンドウ、および時系列の時間増分全体を示した概要時間軸で構成されます。表示可能な時間範囲は、水平方向のズーム制御を使用して変更できます。イベントに対応する各時系列アイテムは、関連付けられた情報やアクションを表示し、時間軸への引出線と概要時間軸内のマーカーで表されます。

たとえば、図27-1の時系列は、Summit DVTの例における従業員の雇用日を時間順に表示するように構成されています。この例では、各イベントを表す時系列アイテムに、イメージとラベル付きテキストを使用して従業員に関する情報を表示しています。概要ウィンドウは、時系列アイテムを表示する時間範囲を定義します。このウィンドウは、ズーム・コントロールを変更するか、ウィンドウの端の位置を変更して拡大または縮小することでサイズを調整できます。選択が構成されている場合は、時系列アイテム、引出線、および概要パネルのイベント・マーカーが強調表示されます。

図27-1 従業員の雇用日の時系列

2つの時系列を使用して最大2系列のイベントを比較できます。図27-2に、10年間にわたる2人の従業員の変化のイベントを比較した2つの時系列を示します。時系列イベントは、3年を超える期間を表す概要ウィンドウに四半期単位の時間軸を使用して表示されています。現在の日付は、概要時間軸の線で示されます。

図27-2 従業員の変化イベントを比較した2つの時系列

27.1.2 エンド・ユーザー機能およびプレゼンテーション機能

時系列をどのように使用し、どのようにカスタマイズできるかを理解するには、次の要素と機能について理解すると役に立ちます。

27.1.2.1 レイアウト・オプション

デフォルトでは、時系列は水平方向に表示され、イベントは水平の時間軸と概要パネルに沿ってレイアウトされます。このレイアウトを垂直方向に変更して、イベントが垂直の時間軸と概要パネルに沿って表示されるようにできます。水平方向の場合は時系列アイテムが画面で互いに重ならないように指定できますが、この構成を垂直方向のアイテムに適用できません。図27-3に、水平方向の時系列と、同じ時系列を垂直方向にしたものとの比較を示します。

図27-3 水平方向と垂直方向の時系列

27.1.2.2 時系列アイテムの選択

時系列に表示される各イベントは、時系列アイテムとして表示されます。時系列アイテムには、イメージ、テキスト、テキスト・ラベルなどのデータ表示コンポーネントや、リンク、ボタン、メニューなどのアクションを含めることができます。イベントは、引出線で時系列の時間軸内の日付に結び付けられます。イベントは、概要パネル内に、構成可能なマーカーとして示されます。

デフォルトでは、時系列アイテムは実行時の選択に対応するようには構成されていません。構成を行うことで、単一または複数の時系列アイテムの選択が可能になります。実行時には、イベント、引出線、および概要パネル内のマーカーが強調表示されます。

27.1.2.3 時系列のグループ化とソート

共通の日付を持つ時系列アイテムをグループとして表示し、実行時にそのグループを開いたり閉じたりできるように構成できます。デフォルトでは、閉じた表示に、グループ内のアイテム数を示す数値カウンタが表示されます。グループ化された時系列アイテムの任意の場所をクリックすると、閉じた表示の全アイテムが開き、時系列内をクリックすると開いた表示が閉じます。図27-4に、カウンタを持つ時系列アイテムが開いた表示になる様子を示します。

図27-4 時系列のグループ・カウンタと開かれた表示

デフォルトの水平方向の時系列では、概要パネルは時系列の下部に表示されます。概要パネルには、時系列に表示可能な期間に対応する移動可能な概要ウィンドウ、および時系列の時間増分全体を示す概要時間軸で構成されます。

27.1.2.4ドラッグ・アンド・ドロップのサポート

時系列コンポーネントは、表など、別のコレクション・コンポーネントとの間のドラッグ・アンド・ドロップ操作をサポートします。図27-5に、ドロップ・ターゲットおよびドラッグ元として構成された時系列を示します。ユーザーが表のいずれかの行を時系列にドラッグすると、属性が時系列アイテムとして表示されます。また、時系列アイテムを選択して表にドラッグすれば、属性を行に表示できます。

図27-5 ドロップ・ターゲットおよびドラッグ元として構成された時系列

27.1.2.5 コンテンツの配信

時系列にデータ・ソースからどのようにデータを配信するかを構成できます。データは、レンダリング時にデータが使用可能になり次第、または、コンポーネントのシェルがレンダリングされた後の遅延フェッチのいずれかで、時系列に配信できます。時系列では、デフォルトで、使用可能になり次第すぐのデータ・ソースからのコンテンツ配信がサポートされます。contentDelivery属性は、デフォルトでwhenAvailableに設定されています。

時系列は仮想化されています。つまり、サーバーのすべてのデータがクライアントに配信され、表示されるわけではありません。日付に関連する値に基づいて、一度に特定の数の行または列をデータ・ソースからフェッチするように時系列を構成できます。フェッチ・サイズを構成するには、fetchStartTimeおよびfetchEndTimeを使用してください。

27.1.2.6 時系列のイメージ形式

時系列では、HTML5、FlashおよびPortable Network Graphics (PNG)のイメージ形式がサポートされます。すべてのイメージ形式で、右から左への表示を使用するロケールがサポートされます。

デフォルトでは、時系列はクライアント・ブラウザでサポートされている最良の出力形式で表示されます。最良の出力形式をクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。たとえば、クライアントがHTML5をサポートしていない場合、アプリケーションでは次が使用されます。

- Flash (Flash Playerが使用可能な場合)
アプリケーション全体でFlashコンテンツの使用を制御するには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

- PNG出力形式
静的レンダリング、たとえば、Flash表示パンおよびズーム状態の保持は、印刷可能なPNG出力形式使用時には完全にサポートされますが、次のような一部の対話機能は使用できません。

- アニメーション

- コンテキスト・メニュー

- ドラッグ・アンド・ドロップ・ジェスチャ

- ポップアップのサポート

- 選択項目

27.1.2.7 印刷可能または電子メール送信可能なページの時系列表示

ADF Facesでは、印刷または電子メール用の簡略化されたモードで、ADF Faces WebアプリケーションからJSFページを出力できます。たとえば、ユーザーがページ(またはページの一部)を印刷できるようにし、一方でWebブラウザでレンダリングされているとおりにページを印刷するのではなく、スクロールバーやボタンなど、印刷ページに必要ないアイテムを削除することが望ましい場合があります。ページが電子メールで送信される場合は、電子メール・クライアントが正しく表示できるようにページを簡略化する必要があります。このような出力用に簡略化されたページを作成する場合の詳細は、第37章「様々な出力モードの使用」を参照してください。

印刷可能または電子メール送信可能なページに出力されるJSFページに時系列が表示された場合:

- 現在時系列に表示されているイベントのみがコンテンツに含まれます。

- 電子メール・モードでは、イベントは表として表示されます。

- 印刷モードでは、時系列の概要はレンダリングされません。

27.1.3 時系列コンポーネントの追加機能

timelineコンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったん時系列をページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。timelineコンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、時系列をリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: 有効になっている場合、ユーザーは実行時の時系列の表示方法を変更できます。アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: デフォルトでは、時系列コンポーネントはアクセス可能です。時系列コンポーネントのあるアプリケーション・ページを、スクリーン・リーダーのユーザーがアクセスできるように構成できます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- コンテンツ配信: contentDelivery属性を使用して時系列を構成することにより、コンポーネントのレンダリング直後に、またはコンポーネントがレンダリングされた後の別のリクエストで、データ・ソースからデータをフェッチするようにできます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされた時系列を作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

さらに、各データ視覚化コンポーネントには、コンテンツの配信方法、自動部分ページ・レンダリング(PPR)、データの表示および編集方法など、同じ機能が多くあります。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

27.2 時系列コンポーネントの使用

UI優先開発でtimelineコンポーネントを使用するには、データを定義し、ページに時系列を追加して、JDeveloperで追加の構成を行います。

27.2.1 時系列コンポーネントのデータ要件

timelineコンポーネントのデータ・レイヤーは、子であるtimelineSeriesコンポーネントで指定されます。基礎となるソースからデータにアクセスするモデルを使用して、時系列の系列を少なくとも1つ(2つの時系列の場合は2つまで)指定する必要があります。使用する具体的なモデル・クラスは、org.apache.myfaces.trinidad.model.CollectionModelのインスタンスです。このクラスは、JSF DataModelクラスを拡張し、行キーのサポートを追加します。DataModelクラスでは、行は索引によって完全に識別されます。ただし、基になるデータが変更された場合に問題を回避するために、CollectionModelクラスが索引ではなく行キーに基づいています。

java.util.List、java.util.ArrayList、javax.faces.model.DataModelなど、別のモデル・インスタンスも使用できます。時系列の系列コンポーネントにより、インスタンスは自動的にCollectionModelクラスに変換されますが、機能は追加されません。CollectionModelクラスの詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

時系列を使用するには、JDeveloperでtimelineSeriesコンポーネントに次の属性が設定されている必要があります。

- value: 時系列で表現されるデータ・モデルを参照するEL式。

- var: レンダリング・フェーズで時系列コレクションの各要素を参照するために使用される変数の名前。この変数は、レンダリングが完了すると削除されるか、初期値に戻ります。

timelineSeriesコンポーネントの直下の子は、多くとも1つのtimelineItemコンポーネントである必要があります。このコンポーネントにより、スタンプ設定によるイベント・コンテンツのカスタマイズが可能になります。スタンプ設定を使用すると、時系列内に示されるイベントごとには子コンポーネントが作成されなくなります。コンポーネントのコンテンツは、時系列内に表示される各イベントのように、時系列アイテムごとに1回ずつ、繰り返しレンダリング(スタンプ設定)されます。

時系列アイテムがスタンプ設定されるたびに、現在のアイテムに対応する値がvarプロパティにコピーされ、オプションで、そのアイテムの追加データがvarStatusプロパティにコピーされます。これらのプロパティには、時系列アイテム・コンポーネント内のEL式でアクセスし、スタンプ設定されたaf:outputTextコンポーネントにアイテム値を渡したりできます。時系列のレンダリングが完了したら、varおよびvarStatusプロパティは削除されるか前の値に戻ります。

value、var、およびオプションのvarStatus属性の値は、時系列のデータ・モデル内、または、UI優先開発を使用している場合はクラスおよびマネージドBean内に、格納する必要があります。

例27-1に、アプリケーションにTimelineCBBeanマネージドBeanを追加するコードのサンプルを示します。このマネージドBeanは、データを含むクラスまたはBeanを参照し、オプションで、時系列をカスタマイズするその他のメソッドを追加します。ArrayListクラスで指定されているデータ・セットのリスト・アイテムがすべてこの例に含まれているわけではありません。

例27-1 時系列データを指定するためのマネージドBeanの例

//imports needed by methods
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.Iterator;
import java.util.Set;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.SessionScoped;
import javax.faces.bean.RequestScoped;
import javax.faces.component.behavior.ClientBehavior;
import javax.faces.component.behavior.ClientBehaviorHint;
import javax.faces.event.AjaxBehaviorEvent;
import oracle.adf.view.faces.bi.component.timeline.UITimelineSeries;
import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.ModelUtils;
import org.apache.myfaces.trinidad.model.RowKeySet;
@ManagedBean(name="cb")
public class TimelineCBBean
{
private CollectionModel m_model;
public TimelineCBBean()
{
super();
}
public CollectionModel getModel()
{
if (m_model != null)
return m_model;
ArrayList _list = new ArrayList(10);
_list.add(new EmpEvent("0", parseDate("01.13.2010"), "Oracle Application
Express", "se198AyXcsk", null));
_list.add(new EmpEvent("1", parseDate("01.27.2010"), "Larry Ellison on the
Sun-Oracle Close", "ylNgcD2Ay6M", null));
...

m_model = ModelUtils.toCollectionModel(_list);
return m_model;
}
public void handleKey(AjaxBehaviorEvent event)
{
ClientBehavior _behavior = (ClientBehavior)event.getBehavior();
Set<ClientBehaviorHint> _hints = _behavior.getHints();
UITimelineSeries _series =
(UITimelineSeries)event.getComponent().findComponent("ts1");
if (_series == null)
return;
RowKeySet _rowKeySet = _series.getSelectedRowKeys();
Iterator _iterator = _rowKeySet.iterator();
ArrayList _list = (ArrayList)m_model.getWrappedData();
while (_iterator.hasNext())
{
Object _rowKey = _iterator.next();
Object _event = m_model.getRowData(_rowKey);
_list.remove(_event);
}
}
private static Date parseDate(String date)
{
Date ret = null;
try
{
ret = s_format.parse(date);
}
catch (ParseException e)
{
e.printStackTrace();
}
return ret;
}
static DateFormat s_format = new SimpleDateFormat("MM.dd.yyyy");

このマネージドBeanの例で提供されているのは、図27-6に示す従業員のプレゼンテーションの時系列用のデータ・モデルです。TimelineCBBeanの完全なソース・コードは、ADF Facesデモ・アプリケーション内にあります。デモ・アプリケーションの詳細は、第2章「ADF Facesデモ・アプリケーション」を参照してください。

図27-6 従業員のプレゼンテーションの時系列

27.2.2 時系列の構成

時系列コンポーネントには構成可能な属性と子コンポーネントがあり、これらを追加または変更することにより、時系列の表示や動作をカスタマイズできます。接頭辞dvt:は、各時系列コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。

時系列の子コンポーネント、属性、およびサポートされているファセットを、次のエリアで構成できます。

- 時系列コンポーネント(timeline): 時系列の子コンポーネントとファセットをラップする親コンポーネントです。

- 時系列の系列(timelineSeries): 時系列コンポーネントの直下の子で、時系列のデータ・レイヤーの指定に使用されます。時系列内に少なくとも1つの系列を指定する必要があります。追加の系列をあと1つまで指定して、時系列間の比較に使用できます。
時系列の系列コンポーネントは、次のようなコンテキスト・メニューの構成に使用できるファセットをサポートします。

- bodyContextMenu: 時系列コンポーネント内の選択不可能な要素に表示されるコンテキスト・メニューを指定します。

- contextMenu: 時系列コンポーネントの選択可能な要素に表示されるコンテキスト・メニューを指定します。

- 時系列アイテム(timelineItem): timelineSeriesの子で、時系列内のイベントを表します。このコンポーネントは、af:outputText、af:image、af:panelGroupLayoutなど、多くのADF Facesコンポーネントの使用をサポートします。

- マーカー(marker): 概要パネルでイベントを表す、構成可能な形状です。各属性は、timelineItemコンポーネントの指定されたoverviewItemファセットの子で指定されます。

- 時間軸(timeAxis): timelineの子で、時間軸、および概要時間軸の指定に使用されるtimelineOverviewの指定に使用されます。

- 時系列概要(timelineOverview): 時系列のすべての系列の全イベントの大局的な表示に使用されるオプションのコンポーネントです。ユーザーは、ズーム制御を使用して時系列をスクロールできます。

27.2.3 ページへの時系列の追加方法

UI優先開発を使用してページを設計する場合は、コンポーネント・ウィンドウを使用して時系列をJSFページに追加します。時系列コンポーネントをページにドラッグ・アンド・ドロップすると、時系列のアーティファクトとソース・コードがビジュアル・エディタに追加され、構造ウィンドウにタグ構造が追加されます。

ページに時系列を追加したら、「プロパティ」ウィンドウを使用してデータ値を指定し、表示属性を構成できます。「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図27-7に、時系列のendTime属性のドロップダウン・メニューを示します。

図27-7 時系列のendTime属性の値

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して時系列を作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータ・バインドされたグラフのドリル用の構成方法に関する項を参照してください。

始める前に:

時系列の属性や時系列の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、第27.2.2項「時系列の構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、第27.1.3項「時系列コンポーネントの追加機能」を参照してください。

ページに時系列を追加するには:

1. 「コンポーネント」ウィンドウで、「ADFデータ視覚化」ページの「ガント」セクションから、Timelineコンポーネントをページにドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウに、時系列の属性を表示します。ヘルプ・ボタンを使用して、timelineコンポーネントの完全なタグ・ドキュメントを表示します。

3. 「外観」セクションを開き、次の属性の値を入力します。

- EndTime: 時系列の時間範囲に使用する終了日をyyyy-mm-dd形式で入力します。時系列に表示するデータ・コレクション内に含めるイベントの終了日を選択します。デフォルトでは、この属性には現在の日付が使用されます。

- StartTime: 時系列の時間範囲に使用する開始日をyyyy-mm-dd形式で入力します。時系列に表示するデータ・コレクション内に含めるイベントの開始日を選択します。デフォルトでは、この属性には現在の日付が使用されます。

4. オプションで、次の属性の値を入力します。

- Orientation: 属性のドロップダウン・メニューを使用して、デフォルトのレイアウトをhorizontalからverticalに変更します。
時系列の向きのサンプル・イメージについては、第27.1.2.1項「レイアウト・オプション」を参照してください。

- ItemPosition: 垂直方向の時系列を使用する場合は、デフォルトで、時系列に使用可能なスペース内で時系列アイテムが縦に重複しません。デフォルト値は、noOverlapです。垂直方向の場合、この属性は水平に並ぶ時系列アイテムの表示には適用されません。
属性値randomを使用すると、時系列に使用可能なスペース内に時系列アイテムが垂直にランダムでレイアウトされるように指定できます。

- Summary: 時系列の目的およびスクリーン・リーダーをサポートするための構造の概要を入力します。

- TimeZone: 時系列に使用するタイムゾーンを入力します。設定されていない場合は、AdfFacesContextから値が特定されます。

5. 「動作」セクションを開き、次の属性の値を入力します。

- ItemSelection: ドロップダウン・リストを使用して、時系列内の時系列アイテムを選択可能にするかどうかを指定します。有効な値は、single (デフォルト)、multipleまたはnoneです。2つの時系列の場合、この設定は時系列の両方の系列に適用されます。

- SortData: 時系列のイベントのソートを、時系列でイベントの時刻に基づいて自動的に行うか、時系列がバインドされているデータ・モデルにより手動で行うかの設定に使用します。有効な値は、auto (デフォルト)またはnoneです。

- FetchStartTimeとFetchEndTime: これらの属性を使用して、データ・ソースからコンテンツを配信するときに使用される開始日と終了日を指定します。

6. 時系列の時間軸を指定するには、次のようにします。

1. 構造ウィンドウでtimelineノードを右クリックして、「時系列の中に挿入」→「時間軸」と選択します。

2. 「時間軸の挿入」ダイアログで、時系列の時間軸に使用するスケールを入力します。有効な値は、twoyears、years、quarters、twomonths、months、twoweeks、weeks、days、sixhours、threehours、hours、halfhoursおよびquarterhoursです。

7. 時系列に時系列概要を追加するには、次のようにします。

1. 構造ウィンドウでtimelineノードを右クリックして、「時系列の中に挿入」→「時系列概要」と選択します。

2. 構造ウィンドウでtimelineOverviewノードを右クリックして、「時系列概要の中に挿入」→「時間軸」と選択します。

3. 「時間軸の挿入」ダイアログで、時系列の概要時間軸の表示に使用するスケールを入力します。有効な値は、twoyears、years、quarters、twomonths、months、twoweeks、weeks、days、sixhours、threehours、hours、halfhoursおよびquarterhoursです。

27.2.4 ページに時系列を追加する場合の処理

JDeveloperでは、「プロパティ」ウィンドウで追加の属性を設定せずに、「コンポーネント」ウィンドウからJSFページに時系列をドラッグ・アンド・ドロップすると、単一のタグのみが生成されます。例27-2に、生成されるコードを示します。

例27-2 UI優先開発における時系列のサンプル・コード

<dvt:timeline
startTime="2012-06-27" endTime="2012-06-27" id="t1"/>

時系列を作成するときに、「データ・コントロール」パネルを使用してデータ・コントロールにデータをバインドする場合は、JDeveloperにより、データ・モデルに基づいてコードが生成されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データ・バインドされたガント・チャートおよび時系列コンポーネントの作成」の章を参照してください。

27.3 時系列コンポーネントへのデータの追加

時系列コンポーネントには、属性を表示するためのコレクション・データ・モデルが必要です。たとえば、図27-6に示す従業員のプレゼンテーションの時系列を作成するには、条件を満たす日付値とイベントに関する詳細を含むデータ・モデルを指定する必要があります。

27.3.1 時系列へのデータの追加方法

UI優先開発を使用して時系列にデータを追加するには、クラス、マネージドBeanおよびメソッド(モデルを作成し、JDeveloperのクラス、Beanおよびメソッドを参照する)を作成します。

始める前に:

時系列の属性や時系列の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、第27.2.2項「時系列の構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、第27.1.3項「時系列コンポーネントの追加機能」を参照してください。

ページに時系列を追加します。ページへの時系列の追加の詳細は、第27.2.3項「ページへの時系列の追加方法」を参照してください。また、時系列の開始時間および終了時間が使用するデータ・モデルと一致していることを確認してください。

時系列のデータ・モデルを定義するクラスとマネージドBeanを作成し、時系列のデータを指定します。詳細と例は、第27.2.1項「時系列コンポーネントのデータ要件」を参照してください。クラス作成のヘルプは、『Oracle Jdeveloperによるアプリケーションの開発』の「Javaコードの使用」の章を参照してください。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

UI優先開発で時系列にデータを追加するには:

1. 構造ウィンドウでtimelineノードを右クリックして、「時系列の中に挿入」→「時系列の系列」と選択します。

2. timelineSeriesノードを右クリックして、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、「共通」セクションを開き、次の属性を設定します。

- Value: 時系列をバインドするモデルのEL式を指定します。これは、org.apache.myfaces.trinidad.model.CollectionModelのインスタンスである必要があります。

注意:

java.util.List、array、javax.faces.model.DataModelなど、別のモデル・インスタンスも使用できます。インスタンスは時系列コンポーネントにより自動的にCollectionModelに変換されます。

たとえば、時系列をインスタンス化するために作成したマネージドBeanを参照します。従業員のプレゼンテーションの例では、時系列のマネージドBeanはcbという名前で、データは時系列が参照されたときにインスタンス化されています。この従業員プレゼンテーションの例のデータを時系列で使用するには、EL式の「Value」フィールドに#{cb.Model}と入力します。

EL式の作成のヘルプについては、第3.5.1項「EL式の作成方法」を参照してください。

- Var: レンダリング・フェーズで時系列コレクションの各要素を参照するために使用される変数の名前を入力します。この変数は、レンダリングが完了すると削除されるか、初期値に戻ります。
たとえば、従業員プレゼンテーションの例のデータの各要素を参照するには、「Var」フィールドにevtと入力します。

- VarStatus: オプションとして、レンダリング・フェーズの変数の名前を入力し、コレクション・モデルやループ・カウンタ情報など、コンポーネントの状態に関するコンテキスト情報にアクセスします。この変数は、レンダリングが完了すると削除されるか、初期値に戻ります。

4. 構造ウィンドウでtimelineSeriesノードを右クリックし、「時系列の系列の中に挿入」→「時系列アイテム」と選択して、スタンプ設定によって時系列の系列データを表示するコンポーネントを追加します。

5. dvt:timelineItemの「プロパティ」ウィンドウで、「共通」セクションを開き、次の値を入力します。

- Value: 時系列上にアイテムとして表示する日付に関連付けられた値を参照するEL式を入力します。たとえば、日付に関連付けられた従業員プレゼンテーションのコレクションでは、プレゼンテーション日付を時系列アイテムとして表示できます。
たとえば、従業員のプレゼンテーションのデータ・ソースを参照するには、#{evt.date}と入力します。

- Group: オプションで、共通の日付を持つ時系列アイテムをグループとして表示し、実行時にそのグループを開いたり閉じたりできるように構成できます。デフォルトでは、閉じた表示に、グループ内のアイテム数を示す数値カウンタが表示されます。

6. 時系列アイテムに時系列アイテムのデータ・コレクションの属性を表示するように構成するには、次のようにします。

1. 構造ウィンドウのコンテキスト・メニューを使用してコンポーネントを挿入し、時系列アイテムのレイアウトを定義します。

2. 「プロパティ」ウィンドウを使用して、時系列アイテムのコンテンツと表示属性を指定します。value属性には、データ・コレクションの行を参照するEL式を使用します。
たとえば、例27-3で強調表示されているコードは、図27-6の従業員プレゼンテーションの時系列でスタンプ設定される時系列アイテムのコンポーネント構造と属性定義を示しています。

7. 時系列概要に表示される時系列アイテムを表すマーカーを構成するには、次のようにします。

1. 構造ウィンドウでoverviewItemファセットを右クリックして、「f:facet-overviewItemの中に挿入」→「マーカー」と選択します。

2. 「プロパティ」ウィンドウで、形状、サイズおよび塗りつぶし色を指定する値を必要に応じて設定します。

注意:

時系列アイテムのレイアウトとコンテンツは多くの方法で指定できます。詳細は、第27.4.1項「時系列アイテムのカスタマイズ」を参照してください。

例27-3 データにバインドされた時系列のコード・サンプル

<dvt:timeline id="tl1" startTime="2010-01-01" endTime="2011-12-31"
inlineStyle="width:1000px;height:500px" itemSelection="single">
<dvt:timelineSeries id="ts1" var="evt" value="#{cb.model}">
<dvt:timelineItem id="ti1" value="#{evt.date}">
<af:panelGroupLayout id="pg1" layout="horizontal">
<af:image id="img1" inlineStyle="width:30px;height:30px"
source="/resources/images/timeline/employment.png"/>
<af:spacer width="3"/>
<af:panelGroupLayout id="pg2" layout="vertical">
<af:outputText id="ot1" inlineStyle="color:#084B8A"
value="#{evt.description}" noWrap="true"/>
<af:outputText id="ot2" value="#{evt.date}" inlineStyle="color:#6e6e6e"
noWrap="true">
<af:convertDateTime dateStyle="medium"/>
</af:outputText>
</af:panelGroupLayout>
</af:panelGroupLayout>
</dvt:timelineItem>
</dvt:timelineSeries>
<dvt:timeAxis id="ta1" scale="weeks"/>
<dvt:timelineOverview id="ov1">
<dvt:timeAxis id="ta2" scale="years"/>
</dvt:timelineOverview>
<f:ajax event="keyUp" execute="@this" listener="#{cb.handleKey}"/>
</dvt:timeline>

27.3.2 2つの時系列のデータの構成に関する必知事項

時系列の系列を1つまで追加して2つの時系列を構成し、2系列のイベントを比較できます。別のtimelineSeriesコンポーネントを追加、構成する場合も、手順は同じです。

27.3.3 時系列へのデータの追加に関する必知事項

この章の例では、クラスとマネージドBeanを使用して時系列にデータを提供しています。アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して時系列を作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされたガント・チャートおよび時系列の作成」の章を参照してください。

また、最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合は、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

27.4 時系列表示要素のカスタマイズ

時系列アイテムを構成して、時系列にカスタムのタイム・スケールを追加できます。

27.4.1 時系列アイテムのカスタマイズ

時系列アイテムは、時系列に表示されるイベントを表します。timelineItemコンポーネントは、情報を表示し、イベントに関連付けられたアクションを指定するために、次のADFコンポーネントをサポートします。

- レイアウト・コンポーネントには、af:panelFormLayout、af:panelGroupLayout、af:separator、af:showDetailItemおよびaf:spacerがあります。これらのコンポーネントの使用方法の詳細は、第9章「Webページ上のコンテンツの編成」を参照してださい。

- メニュー・コンポーネントaf:menu。これらのコンポーネントの詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

- 出力コンポーネントには、af:outputFormattedとaf:outputTextがあります。これらのコンポーネントの詳細は、第18章「出力コンポーネントの使用」を参照してください。

- メッセージ・コンポーネントaf:outputLabelMessage。このコンポーネントの詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- ナビゲーション・コンポーネントaf:buttonおよびaf:link。これらのコンポーネントの詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

- イメージ・コンポーネントaf:image。af:imageコンポーネントの使用方法の詳細は、第18.4項「イメージの表示」を参照してください。

- af:showPopupBehavior:af:showPopupBehaviorコンポーネントの使用方法の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

時系列アイテムは、構成可能な形状として時系列概要に表示されます。時系列アイテムのマーカーには、次の属性を指定できます。

- fillColor: マーカー形状の色です。有効な値は、16進数のRGB色です。

- opacity: マーカーの塗りつぶし色の不透明度です。有効な値の範囲は、0パーセント(透明)から100パーセント(不透明)です。

- shape: 選択された時系列の各系列の値に対応する概要マーカーの形状です。有効な値は、事前に作成された7つの形状である、circle (デフォルト)、diamond、human、plus、square、triangleDown、triangleUpのいずれかです。この属性は、垂直方向の時系列ではサポートされません。

- scaleXおよびscaleY: scaleX (水平)およびscaleY (垂直)のスケール係数です。有効な値はパーセンテージの数字です。マーカーが大きすぎる場合は、JDeveloperにより、時系列の概要領域に合せて自動的にマーカーのサイズが変更されます。これらの属性は、垂直方向の時系列ではサポートされません。

27.4.2 時系列へのカスタム・タイム・スケールの追加方法

時系列と概要の軸にカスタム・タイム・スケールを作成できます。カスタム・タイム・スケールは、dvt:timeAxisのscale属性で構成します。

始める前に:

時系列の属性や時系列の子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、第27.2.2項「時系列の構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、第27.1.3項「時系列コンポーネントの追加機能」を参照してください。

ページにすでに時系列が存在している必要があります。ない場合は、この章の説明に従って時系列を作成します。詳細は、第27.2.3項「ページへの時系列の追加方法」を参照してください。

カスタム時間軸を作成し使用する手順:

1. CustomTimescale.javaインタフェースを実装して、時間軸を作成するためにgetNextDate(Date currentDate)メソッドをループでコールします。例27-4に、インタフェースのサンプル・コードを示します。

例27-4 カスタム日付を作成するインタフェース

public interface CustomTimescale
{
public String getScaleName();
public Date getPreviousDate(Date timelineStartDate);
public Date getNextDate(Date currentDate);
public String getLabel(Date date);
}

2. 構造ウィンドウでtimelineノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウの「拡張」カテゴリで、CustomTimeScales属性に、カスタム時間軸のインタフェースの実装を登録します。
customTimeScales属性の値は、java.util.Mapオブジェクトです。指定したマップ・オブジェクトには、キー/値のペアが含まれます。キーはタイム・スケール名(fiveyears)で、値はCustomTimeScale.javaインタフェースの実装です。次に例を示します。

customTimesScales="#{timeline.customTimescales}"

4. 時間軸または概要時間軸でカスタム・タイム・スケールを使用するには、構造ウィンドウでdvt:timeAxisノードを右クリックし、「プロパティ」ウィンドウでカスタム・タイム・スケール名を入力します。
例27-5に、時間軸にthreeyearsを、概要時間軸にfiveyearsを設定するサンプル・コードを示します。

例27-5 カスタム時間軸

<dvt:timeline>
<dvt:timeAxis id="ta1" scale="threeyears"/>
<dvt:timelineOverview id="ov1">
<dvt:timeAxis id="ta2" scale="fiveyears"/>
</dvt:timelineOverview>
</dvt:timeline>

27.5 インタラクティブ機能の時系列への追加

時系列に、ポップアップのサポート、カスタム・コンテキスト・メニュー、ドラッグ・アンド・ドロップ操作などのインタラクティブ機能を追加できます。

27.5.1 時系列アイテムへのポップアップの追加方法

時系列timelineItemコンポーネントは、情報を提供したり、エンド・ユーザーからの入力を要求したりするポップアップのダイアログ、ウィンドウおよびメニューが表示されるように構成できます。af:popupコンポーネントを他のADF Facesコンポーネントで使用すると、セカンダリ・ウィンドウでの情報の表示および非表示、追加データの入力、コンテキスト・メニューなどの機能の呼出しを、エンド・ユーザーに許可する機能を構成できます。

ADF Facesのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。af:showPopupBehaviorタグは宣言的ソリューションとなるため、popupコンポーネントを開くためのJavaScriptの作成や、スクリプトのpopupコンポーネントへの登録の必要がありません。これらのコンポーネントの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

27.5.2 時系列のコンテキスト・メニューの構成方法

次のコンテキスト・メニュー・ファセットを使用して、時系列のコンテキスト・メニューを定義します。

- bodyContextMenu: 時系列コンポーネント内の選択不可能な要素に表示されるコンテキスト・メニューを指定します。

- contextMenu: 時系列コンポーネントの選択可能な要素に表示されるコンテキスト・メニューを指定します。

JSPまたはJSPXページの各ファセットでは、1つの子コンポーネントがサポートされます。これらのファセットを機能させるには、時系列のプロパティで選択が有効になっている必要があります。コンテキスト・メニューは、現在のところFlashでのみサポートされています。

af:popupコンポーネント内のaf:menuコンポーネントを使用してコンテキスト・メニューを作成します。ついで、指定されたトリガーに基づき、別のコンポーネントからコンテキスト・メニュー・ポップアップを起動できます。コンテキスト・メニューの構成の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

27.5.3 時系列へのドラッグ・アンド・ドロップの追加方法

時系列は、ページ上のコレクション・コンポーネントとの間のドロップ・ターゲットまたはドラッグ元として構成できます。たとえば、図27-5に示すように、1つのコレクションからアイテム(表の行など)をドラッグして時系列にドロップしたり、時系列からイベントをドラッグして表にドロップしたりできます。

時系列にドロップ・サポートを追加するには、timelineコンポーネントにaf:dropTargetタグを追加し、時系列がサポートするデータ・フレーバを組み込みます。ドロップ・イベントに応答する時系列のマネージドBeanにdropListenerメソッドを追加します。

時系列からコレクション・コンポーネントへのドラッグ・サポートを追加するには、timelineコンポーネントにaf:dragSourceタグを追加し、ドラッグを受ける側のコンポーネントにaf:collectionDropTargetタグを追加します。ドラッグを受ける側のコンポーネントには、org.apache.myfaces.trinidad.model.RowKeySetデータ・フレーバをaf:collectionDropTargetの子として組み込み、ドロップ・イベントに応答するためのdropListenerメソッドも定義します。

例27-6に、図27-5に示すADF Facesデモ・アプリケーションのJSFページのサンプル・コードを示します。af:tableコンポーネントの詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

例27-6 時系列のドロップ・ターゲットとドラッグ元のサンプル・コード

<dvt:timeline id="tl1" startTime="2010-01-01" endTime="2011-12-31"
inlineStyle="width:800px;height:400px" itemSelection="single">
<f:attribute name="horizontalFetchSizeOverride" value="3000"/>
<dvt:timelineSeries id="ts1" var="evt" value="#{dnd.timelineModel}">
<dvt:timelineItem id="ti1" value="#{evt.date}" group="#{evt.group}">
<af:panelGroupLayout id="pg1" layout="horizontal">
<af:image id="img1" inlineStyle="width:30px;height:30px"
source="/resources/images/timeline/employment.png"/>
<af:spacer width="3"/>
<af:panelGroupLayout id="pg2" layout="vertical">
<af:outputText id="ot1" inlineStyle="color:#084B8A"
value="#{evt.description}" noWrap="true"/>
<af:outputText id="ot2" value="#{evt.date}"
inlineStyle="color:#6e6e6e" noWrap="true">
<af:convertDateTime dateStyle="medium"/>
</af:outputText>
</af:panelGroupLayout>
</af:panelGroupLayout>
</dvt:timelineItem>
<af:dragSource actions="COPY" discriminant="model"/>
<af:dropTarget actions="COPY" dropListener="#{dnd.handleDropOnTimeline}">
<af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"
discriminant="model2"/>
</af:dropTarget>
</dvt:timelineSeries>
<dvt:timeAxis id="ta1" scale="weeks"/>
<dvt:timelineOverview id="ov1">
<dvt:timeAxis id="ta2" scale="years"/>
</dvt:timelineOverview
</dvt:timeline>
<af:table var="row" value="#{dnd.tableModel}" rowSelection="single"
inlineStyle="width:370px;height:400px">
<af:column headerText="ID" width="20">
<af:outputText value="#{row.id}"/>
</af:column>
<af:column headerText="Event" width="340">
<af:outputText value="#{row.description}"/>
</af:column>
<af:dragSource actions="COPY" discriminant="model2"/>
<af:collectionDropTarget actions="COPY" modelName="model"
dropListener="#{dnd.handleDropOnTable}"/>
</af:table>

この例のデータ・モデルは、TimelineDnDBeanマネージドBeanにArrayListクラスを使用して定義されています。このクラス、およびこれをサポートするEmpEventクラスのソース・コードは、ADF Facesデモ・アプリケーション内にあります。デモ・アプリケーションの詳細は、第2章「ADF Facesデモ・アプリケーション」を参照してください。

始める前に:

時系列の属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、第27.2.2項「時系列の構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、第27.1.3項「時系列コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページに時系列を追加します。詳細は、第27.2.3項「ページへの時系列の追加方法」を参照してください。

- 時系列アイテムをドラッグ元として構成していて、ページへのコンポーネントの追加時に時系列をデータ・コントロールにバインドしていない場合は、データを時系列に追加します。UI優先開発を使用してデータを時系列に追加する場合の詳細は、第27.3.1項「時系列へのデータの追加方法」を参照してください。

- ドラッグ・アンド・ドロップをサポートするのに必要な追加コンポーネントを作成します。
たとえば、ドラッグ元またはドロップ・ターゲットとして表を使用する場合は、ページに表を追加する必要があります。

時系列にドラッグ・アンド・ドロップ・サポートを追加するには:

1. 構造ウィンドウでtimelineコンポーネントを右クリックして、「時系列の中に挿入」→「ドロップ・ターゲット」と選択します。

2. 「ドロップ・ターゲットの挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選択し、時系列のマネージドBeanにドロップ・リスナー・メソッドを追加します。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、dndというマネージドBeanにhandleDropOnTimeline()というメソッドを追加するには、「編集」を選択し、ドロップダウン・メニューから「dnd」を選択して、「メソッド」フィールドの右にある「新規」をクリックし、handleDropOnTimeline()メソッドを作成します。

例27-7に、図27-5に表示されている時系列のサンプル・ドロップ・リスナーと、それをサポートするメソッドを示します。

例27-7 時系列のサンプル・ドロップ・リスナー

// imports needed by methods
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.SessionScoped;
import javax.faces.bean.RequestScoped;
import oracle.adf.view.rich.datatransfer.DataFlavor;
import oracle.adf.view.rich.datatransfer.Transferable;
import oracle.adf.view.rich.dnd.DnDAction;
import oracle.adf.view.rich.event.DropEvent;
import org.apache.myfaces.trinidad.context.RequestContext;
import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.ModelUtils;
import org.apache.myfaces.trinidad.model.RowKeySet;
// drop listener
public DnDAction handleDropOnTimeline(DropEvent event)
{
Date _date = (Date)event.getDropSite();
Transferable _transferable = event.getTransferable();
RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR);
Object _rowKey = _rowKeySet.iterator().next();
EmpEvent _event = (EmpEvent)m_tableModel.getRowData(_rowKey);
_event.setDate(_date);
orderInsert(_event);
RequestContext.getCurrentInstance().addPartialTarget
(event.getDragComponent());
return DnDAction.COPY;
}
private void orderInsert(EmpEvent event)
{
int _index = -1;
ArrayList _list = (ArrayList)m_timelineModel.getWrappedData();
for (int i=0; i<_list.size(); i++)
{
EmpEvent _current = (EmpEvent)_list.get(i);
if (event.getDate().before(_current.getDate()))
{
_index = i;
break;
}
}
if (_index == -1)
_list.add(event);
else
_list.add(_index, event);
ArrayList _list2 = (ArrayList)m_tableModel.getWrappedData();
_list2.remove(event);
}

3. 「OK」をクリックし、「データ・フレーバの挿入」ダイアログに、org.apache.myfaces.trinidad.model.RowKeySetを入力します。

4. 構造ウィンドウでaf:dropTargetコンポーネントを右クリックし、「プロパティに移動」を選択して、「プロパティ」ウィンドウで次の属性を設定します。

- Actions: ドロップ・ターゲットが受け入れる操作をスペース区切りのリストで入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。

- Discriminant: ドロップ・ターゲットとドラッグ元が互換性のために共有するモデル名を指定します。この属性の値は、手順5で時系列からドラッグを受けるコレクション・コンポーネントに設定する、dragSourceコンポーネントのdiscriminant属性の値に一致する必要があります。

5. 別のコレクション・コンポーネントを時系列へのドロップのドラッグ元として構成するには、次のようにします。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグをドラッグのソースとなるコンポーネントの子としてドラッグ・アンド・ドロップします。
たとえば、「ドラッグ元」のタグをaf:tableコンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、コンポーネントの「Actions」フィールドに、ドロップ・ターゲットが受け入れる操作をスペース区切りのリストで入力します。

3. コンポーネントの「Discriminant」フィールドに、ドロップ・ターゲットとドラッグ元が互換性のために共有するモデル名を指定します。

6. 時系列をドラッグ元として構成するには、「コンポーネント」ウィンドウの「操作」パネルから、「ドラッグ元」のタグを時系列の子としてドラッグ・アンド・ドロップします。

7. 構造ウィンドウでaf:dragSourceコンポーネントを右クリックし、「プロパティに移動」を選択して、「プロパティ」ウィンドウで次の属性を設定します。

- Actions: コレクション・ドロップ・ターゲット・コンポーネントが受け入れる操作をスペース区切りのリストで入力します。

- Discriminant: ドラッグ元とコレクション・ドロップ・ターゲットが互換性のために共有するモデル名を指定します。この属性の値は、手順8で時系列からドラッグを受けるコレクション・コンポーネントに設定する、af:collectionDropTargetコンポーネントのmodelName属性の値に一致する必要があります。

8. 別のコレクション・コンポーネントを時系列からのドロップのドロップ・ターゲットとして構成するには、次のようにします。

1. 「コンポーネント」ウィンドウの「操作」パネルで、「コレクション・ドロップ・ターゲット」を、ドロップを受けるコンポーネントにドラッグ・アンド・ドロップします。
たとえば、「コレクション・ドロップ・ターゲット」を、ドロップの結果を表示するaf:tableコンポーネントの子としてドラッグ・アンド・ドロップします。

2. ドロップ・ターゲットを挿入ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して編集を選び、ドロップ・リスナー・メソッドを適切なマネージドBeanに追加してください。
例27-8に、図27-5に表示されている時系列のサンプル・ドロップ・リスナーを示します。この例は例27-7で使用されたものと同じインポートとヘルパー・メソッドを使用しており、それらはここには含まれていません。

例27-8 時系列をドラッグ元として使用する表のサンプル・ドロップ・リスナー

//Drop Listener
public DnDAction handleDropOnTable(DropEvent event)
{
Integer _dropSite = (Integer)event.getDropSite();
Transferable _transferable = event.getTransferable();
RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR);
Object _rowKey = _rowKeySet.iterator().next();
EmpEvent _event = (EmpEvent)m_timelineModel.getRowData(_rowKey);
ArrayList _list = (ArrayList)m_tableModel.getWrappedData();
_list.add(_dropSite.intValue(), _event);
ArrayList _list2 = (ArrayList)m_timelineModel.getWrappedData();
_list2.remove(_event);
RequestContext.getCurrentInstance().addPartialTarget
(event.getDragComponent());
return DnDAction.COPY;
}
private static Date parseDate(String date)
{
Date ret = null;
try
{
ret = s_format.parse(date);
}
catch (ParseException e)
{
e.printStackTrace();
}
return ret;
}

3. 「OK」をクリックし、「データ・フレーバの挿入」ダイアログに、org.apache.myfaces.trinidad.model.RowKeySetを入力します。

4. 構造ウィンドウでaf:dropTargetコンポーネントを右クリックし、「プロパティに移動」を選択します。

5. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。

6. 「ModelName」フィールドに、コレクションのモデルを定義します。modelName属性の値は、互換性の目的でドラッグ元の特定に使用されるStringオブジェクトです。この属性の値は、手順7で設定したaf:dragSourceコンポーネントのdiscriminant属性の値に一致する必要があります。

ADF FacesまたはADFデータ視覚化コンポーネントのドラッグ・アンド・ドロップの構成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

28 マップ・コンポーネントの使用方法

この章では、ADF Facesデータ可視化マップおよびthematicMapコンポーネントを使い、地理マップとテーマ・マップでデータを単純UI優先開発を使用して表示する方法を記述します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して、地理マップのテーマ、テーマ・マップの領域、ポイント・データ・レイヤーを作成し、データを表示することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた地理マップおよびテーマ・マップ・コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 28.1項「マップ・コンポーネントについて」

- 28.2項「地理マップ・コンポーネントの使用方法」

- 28.3項「地理マップ表示属性のカスタマイズ」

- 28.4項「地理マップ・テーマのカスタマイズ」

- 28.5項「地理マップへのツールバーの追加」

- 28.6項「テーマ・マップ・コンポーネントの使用方法」

- 28.7項「テーマ・マップ表示属性のカスタマイズ」

- 28.8項「インタラクティブ機能の時系列への追加」

28.1 マップ・コンポーネントについて

地理マップでは、1つのマップに重ね合せた1つ以上のインタラクティブな情報レイヤー(テーマ)でビジネス・データを表します。地理マップには、リモートのOracle Application Server (AS) MapViewerサービスのURL、およびアドレス・データを経度と緯度に変換する必要がある場合はオプションでジオコーダ・サービスのURLを含む構成が必要です。

テーマ・マップでは、ビジネス・データをスタイル設定されたエリア内にパターンまたは関連付けられたマーカーとして表し、Oracle MapViewerサービスへの接続は必要ありません。テーマ・マップでは、地理マップでの地理的な詳細なしで、データに焦点を合せます。

28.1.1 マップ・コンポーネントのユースケースおよび例

地理マップもテーマ・マップもデータを表示するために設計されています。違いは、地理マップでは、道路または川などの詳細付きで最上の状態で表示されるデータに重点を置き、そのためOracle MapViewerサービスや、オプションでジオコーダ・サービスに対して構成をする必要がある点です。テーマ・マップでは、地理的詳細の見た目がごちゃごちゃした状態をなくした、データの傾向またはパターンに重点を置くため、Oracle MapViewerやジオコーダ・サービスに対する構成は不要です。

地図マップでは、各種のマップ・テーマがサポートされており、それらはそれぞれデータ・コレクションにバインドする必要があります。次の種類のマップ・テーマが使用できます。

- 色:地域に適用されます。たとえば、ある地域の州の人口を表したり、地域の州での製品の人気を表す色のレンジを色テーマで指定できます。地理マップには、異なるズーム・レベルで表示される複数の色テーマを使用できます。たとえば、色テーマはズーム・レベル1から5では州の人口を表し、ズーム・レベル6から10では郡の収入中央値を表すことができます。

- 点:マップ内で個々の緯度および経度の位置を表示します。たとえば、点テーマで倉庫の場所をマップに示します。表示するポイントのスタイルをカスタマイズする場合、倉庫のセット内の在庫の種類(電気製品、家庭用品、園芸用品)を区別するためにそれぞれ異なるイメージを使用するよう選択できます。

- グラフ:任意の数の円グラフ・テーマと棒グラフ・テーマを作成します。ただし、一度に表示できるグラフ・テーマは1つのみです。マップ・ツールバーの「表示」メニューからテーマを選択します。グラフ・テーマでは、州や郡など特定の地域に関連する統計を表示できます。たとえば、グラフ・テーマで州でのいくつかの製品の売上げの値を表示できます。

図28-1に、色、ポイントおよびグラフ・テーマを使用した地理マップを示します。

図28-1 色、点および円グラフ・テーマを使用した米国南西部の地理マップ

図28-2に、カスタマイズした棒グラフ・テーマを使用した地図マップを示します。

図28-2 カスタム棒グラフ・テーマを使用した地理マップ

テーマ・マップでは、地理的位置に関連付けられたデータの傾向またはパターンが表示されます。データは、たとえばデータ値に基づいた塗りつぶし色を使用したり、マーカーをリージョンに関連付けたり、あるいはその両方により、リージョンごとにスタイル設定されます。

図28-3に、米国の州ごとの失業率を表示するテーマ・マップを示します。マップには、失業率が2.0-4.0パーセントの州が複数選択されている状態が表示されています。

図28-3 米国の失業率のテーマ・マップ

図28-4に、南米の主要都市の規模の段階的シンボルを表示するテーマ・マップを示します。

図28-4 南米の都市を規模別に示したテーマ・マップ

28.1.2 マップのエンド・ユーザー機能およびプレゼンテーション機能

ADFデータ視覚化マップおよびテーマ・マップ・コンポーネントには、パンおよびズーム、凡例表示などのエンド・ユーザー用の一連の機能が用意されています。また、状態管理などの一連のプレゼンテーション機能も備わっています。

28.1.2.1 地理マップのエンド・ユーザー機能およびプレゼンテーション機能

地理マップをどのように使用し、どのようにカスタマイズできるかを理解するには、次の要素と機能について復習すると役に立ちます。

- ビューポート: 地理マップおよびそのプレゼンテーション機能用のコンテナ。デフォルトのサイズは600 x 375ピクセルで、カスタマイズ可能です。

- 基準となるマップ: 背景の地理データ、ズーム・レベルと、国、都市、道路などのアイテムの外観と存在。デフォルトでは、地理マップはリモートのOracle MapViewerサービスから基準となるマップを使用します。基準となるマップには、たとえば、オフィス・ビルのフロア・マップなど、MapViewerおよびMap Builderを使用して構成できる任意のイメージを使用できます。

- ズーム制御: マップの左上隅にレンダリングされるパン・アイコンとズーム・スライダ。図28-5に、最小に縮小された(ズーム・レベルが0に設定された)マップのズーム制御を示します。ゼロではマップ全体が表示されます。
ズーム制御の位置と初期設定は、mapコンポーネントでカスタマイズできます。マップのツールバーにある「表示」メニューにより、ズーム制御の表示を指定できます。デフォルトでは、マップの初期ズーム・レベルは0に設定されています。

図28-5 マップのズーム制御

- パン・アイコン: ズーム制御の上部にある(東西南北、北東、北西、南東および南西を指す矢印の付いた)アイコン。このアイコンを使用して、特定の方向にマップ全体を移動できます。

- ズーム・スライダ: 大縮尺ズーム用のサム付きスライダと1レベルのズーム用のアイコン。プラスのアイコンを使用して一度に1レベルズーム・インし、マイナスのアイコンを使用して一度に1レベルズーム・アウトします。サムがスライダの下部にある場合、ズーム・レベルはゼロです。

- スケール: マップの左下隅の情報パネルの下、コピーライトの上に表示される2つの横方向のバー。図28-6に、スケールを示します。上のバーはマイル(mi)を表し、下のバーはキロメートル(km)を表します。マイル・バーの上およびキロメートル・バーの下には、[距離] [単位]の形式でラベルが表示されます。ズーム・レベルの変更やマップのパンに応じて、バーの長さと距離の値が変わります。

図28-6 マップの情報パネル、スケールおよびコピーライト

- 情報パネル:スケールの上の左下隅に緯度と経度を表示します。図28-6に、情報パネルを示します。デフォルトでは、情報パネルは表示されません。このパネルは、「表示」メニューから、またはツールバー上の「情報」ボタンをクリックして表示できます。

- 測定パネル:現在使用しているツールバーのツールに応じて、距離、領域、半径のいずれかが表示されます。[ラベル] [値] [単位]の形式で、情報パネルの右にテキストが表示されます。図28-7に、距離測定の測定パネルを示します。領域測定および半径測定は、適切なラベルを使用して同様に表示されます。

図28-7 マップの情報パネルの横にある測定パネル

次のツールによって、測定パネルに情報が示されます。

- 領域測定:「面」、「長方形選択」または「マルチポイント選択」ツールがアクティブの場合にのみ表示されます。

- 距離測定:「距離」ツールがアクティブの場合にのみ表示されます。

- 半径測定:「円形選択」ツールがアクティブの場合にのみ表示されます。

- コピーライト: マップの左下隅に表示され、mapコンポーネントでカスタマイズできるテキストが含まれます。

- 概要マップ: 図28-8に示すような、メイン・マップの縮小表示で構成されます。このマップは、メイン・マップの右下隅に表示され、パン・ツールまたはパン・アイコンを使用せずにメイン・マップの表示領域を変更できます。

図28-8 概要マップ

次のアイテムは、概要マップの一部です。

- レチクル: メイン・マップの縮小表示内を移動できる小さなウィンドウとして表示されます。縮小マップ内の網線の位置によって、メイン・マップの表示可能領域が決まります。網線を移動すると、メイン・マップが自動的に更新されます。

- 「表示/非表示」アイコン:概要マップが表示されている場合、左上隅に表示されます。「表示/非表示」アイコンをクリックすると、概要マップが非表示になり、アイコンのみがメイン・マップの右下隅に表示されます。

- ツールバー: マップおよびマップのテーマの表示を調整するユーザー制御を提供するためにマップと関連して表示されます。
ツールバーには、次の要素が次に示す順で含まれています。

- 表示: 表示するテーマの制御、表示する特定のテーマの選択、ズーム制御、凡例、情報パネルおよび凡例を表示するかどうかの決定を行います。図28-9に、「表示」メニューのサンプルを示します。

図28-9 マップの「表示」メニュー

「表示」メニューの「テーマ」オプションを選択すると、複数のテーマがある場合に地理マップを構成するためのダイアログが開きます。図28-10に、マップの「テーマ」ダイアログのサンプルを示します。

図28-10 マップの「テーマ」ダイアログ

- ツールバーのボタン: 地理マップと対話する次のユーザー制御を提供します。

- パン: ビュー内でのドラッグ・アンド・ドロップ操作により、マップをパンするために使用します。

- ズーム: マップ・ビューでのズーム・インまたはズーム・アウトに使用します。

- 選択: マップ上の定形(矩形、円形または多角形)領域または点を選択するために使用します。選択内のテーマは強調表示されます。

- 測定: マップの距離およびエリアの測定ツールの非表示または表示を切り替えるために使用します。

- 凡例: マップの凡例の非表示または表示を切り替えるために使用します。

- 情報パネル: マップの情報パネルの非表示または表示を切り替えるために使用します。

図28-11に、マップのツールバー・ボタンによってサポートされる機能を示します。

図28-11 マップのツールバー・ボタンの機能

28.1.2.2 テーマ・マップのエンド・ユーザー機能およびプレゼンテーション機能

テーマ・マップをどのように使用し、どのようにカスタマイズできるかを理解するには、次の要素と機能について復習すると役に立ちます。

- ビューポート: テーマ・マップおよびそのプレゼンテーション機能用のコンテナ。デフォルトのサイズは600 x 375ピクセルで、カスタマイズ可能です。

- ベース・マップ: 背景の地理上のエリア。それぞれの基準となるマップには、いくつかのリージョンのセットと、点として示される都市の固定セットが1つ含まれます。リージョンまたは都市の1つのセットはレイヤーと呼ばれます。一度に表示できるのは1つの基準となるマップと1つのレイヤーのみですが、ドリルが有効な場合は例外です。テーマ・マップ用に事前に作成された基準となるマップには次のものがあります。

- 米国

- 米国およびカナダ

- 世界

- アフリカ

- アジア

- ヨーロッパ

- 北米

- 中米

- 南米

- アジア太平洋(APAC)

- ヨーロッパ、中東およびアフリカ(EMEA)

- 世界のリージョン

- エリア・レイヤーとラベル: それぞれの基準となるマップには、地理的階層でレベルを表すいくつかのリージョンが含まれています。たとえば、米国マップでは、階層は国→州→郡です。階層関係ではリージョン内のドリルをサポートしています。表示されるとき、基準となるマップに関連付けられた都市は、データ・ポイントとして表示されます。デフォルトでは、1つのエリア・レイヤー内の各リージョンには、カスタマイズ可能なラベルが表示されます。
テーマ・マップでは、1つ以上のカスタム・エリア・レイヤー、既存のエリア・レイヤーまたは別のカスタム・リージョンのいずれかに基づく名前付きのリージョン・グループがサポートされます。カスタム・リージョンは、基準となるマップの地理階層に自然にぴったり収まります。たとえば、郡レイヤーに基づくカスタム・エリア・レイヤーは、階層内で米国の州と米国の郡との間に表示されます。

- データ・レイヤー: 各テーマ・マップのデータ・レイヤーは、データ・コレクションにバインドされ、データをエリアまたはマーカー、もしくはその両方として表します。マップ・レイヤーには、一度に1つのデータ・レイヤーのみ表示できるのに対し、データ・マーカーは複数を同時に表示できます。データ・レイヤーには、次の2種類があります。

- エリア・データ・レイヤー: 地理エリア、あるいは経度と緯度またはX座標とY座標としてマップの位置に関連付けられた点により定義されたエリア。データは、色と塗りつぶしパターンまたはマーカー、もしくはその両方でスタイル設定します。

- ポイント・データ・レイヤー: 経度と緯度またはX座標とY座標としてマップの位置に関連付けられた点の位置。データは、thematicMapコンポーネントで使用可能な形状、カスタム形状、またはグラフィック・ファイルを使用して、マーカーまたはイメージで表されます。

- コントロール・パネル: ユーザーが次の操作を制御できるようにするオプション・ツールです。

- パンおよびズーム制御: マップをパンさせ、マップをビュー内でズームし中央揃えするために使用します。

- ズームしてあわせる: ビューポート内でマップの全表示を中央揃えしてぴったり合せるために使用します。

- ズーム・ボタン: テーマ・マップのビュー上でズーム・インまたはズーム・アウトするために使用します。

- コントロール・パネルの表示/非表示ボタン: コントロール・パネルの表示または非表示の切り替えに使用します。

- リセット・ボタン: テーマ・マップでドリルが有効な場合に使用可能です。マップをリセットして、リージョンでドリルがない状態で表示するために使用します。

- ドリル・ボタン: テーマ・マップでドリルが有効な場合に使用可能です。上または下を指す矢印を使用して、マップ・リージョン内でドリル・アップ・またはドリル・ダウンします。

図28-12に、マップでのドリルが有効なコントロール・パネルを示します。

図28-12 ドリルが有効なコントロール・パネル

- コンテキスト・メニュー: デフォルトでは、テーマ・マップにビューポートの背景、マップ・リージョンおよびデータ・マーカーのコンテキスト・メニューが表示されます。カスタム・コンテキスト・メニューの項目は、デフォルトのメニューに追加できます。
図28-13に、マップ・ビューポートのデフォルトのコンテキスト・メニューを示します。データ・マーカーにも同じメニュー項目が使用できます。

図28-13 マップ・ビューポートの背景のコンテキスト・メニュー

図28-14に、マップ・リージョンのコンテキスト・メニューを示します。

図28-14 マップ・リージョンのコンテキスト・メニュー

- 状態の管理: デフォルトでは、テーマ・マップに加えられた表示の変更(中央揃え、ズーム、選択およびドリルなど)の状態は、数セッションにわたり持続し、印刷にも引き継がれます。

- イメージ形式: デフォルトでは、テーマ・マップはクライアント・ブラウザでサポートされる最良の出力形式で表示されます。最良の出力形式をクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。テーマ・マップでは、HTML5、FlashおよびPortable Network Graphics (PNG)のイメージ形式がサポートされます。すべてのイメージ形式で、右から左への表示を使用するロケールがサポートされます。

- 印刷: テーマ・マップは、マップ内のズームまたはパンの状態を維持したまま、PNG出力形式を使用して印刷されます。

- アニメーション: デフォルトでは、テーマ・マップは、マップに関連付けられたデータが変更されるときや、リージョンがマップでドリルされるときに、マップの初期レンダリング上でアニメーション化されます。

- ドリル: 有効な場合、地理的階層の次のレイヤーのドリルが表示されます。たとえば、ある州リージョンをダブルクリックすると、その州内の郡が表示されます。ドリルが有効な場合、ドリル・アイコンがコントロール・パネルに追加されます。

- ドラッグ・アンド・ドロップ: マップは、これらの操作をサポートするように構成できます。

- 選択したマップ・リージョンまたはデータ・マーカーを、別のページ・コンポーネントにドラッグします。

- データ・マーカーをマップ上のある場所から別の場所に移動します。

- データ要素を別ページ・コンポーネントからマップ・リージョンまたはデータ・マーカーにドラッグします。

- 機能の無効化: マップのズーム、ズームして合せる、パンなどのエンド・ユーザー機能は、テーマ・マップで無効にできます。無効にした場合、コントロールはコントロール・パネルから削除されます。

- ツールチップ: デフォルトでは、テーマ・マップのツールチップにより、カーソルをマップ上で移動した場合、ユーザーはマップの位置や関連付けられたデータの方向に導かれます。

28.1.3 マップ・コンポーネントの追加機能

マップ・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんマップ・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。マップ・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、マップをリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: 有効な場合、ユーザーは実行時にマップの表示方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: デフォルトでは、地理マップおよびテーマ・マップ・コンポーネントはアクセス可能です。アプリケーション・ページを、スクリーン・リーダーからアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- スキンおよびスタイル: アプリケーションに適用するADFを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)を使用してCSSスタイル・プロパティを直接適用することにより、ゲージ・コンポーネントの外観をカスタマイズできます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- コンテンツ配信: テーマ・マップ・エリアおよび点データ・レイヤーを、contentDelivery属性を使用して、データ・ソースから特定の行数をフェッチするように構成できます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされたマップを作成できます。詳細は、『Oracle ADF FacesによるWebユーザー・インタフェースの開発』の「データバインドされた地理マップおよびテーマ・マップ・コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「プレースホルダ・データ・コントロールを使用したページの設計」の章を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、イメージ形式、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

28.2 地理マップ・コンポーネントの使用方法

マップを作成する際、管理者がOracle SpatialのMap Builderツールを使用してすでに構成してある基準となるマップを選択するよう求められます。構成時、マップの管理者は、マップでサポートされるズーム・レベルを定義します。このレベルによって、地理マップのズーム機能も決まります。

管理者は、Map Builderツールを使用して、事前定義のマップ・テーマを作成することもできます。たとえば、事前定義のテーマでは、地域を示すために特定の色を使用することがあります。地理マップ・コンポーネントで、これらの事前定義マップ・テーマを選択できますが、テーマは基準となるマップの一部であるため、変更はできません。

基準となるマップは、地理マップ・コンポーネントを使用して情報のインタラクティブ・テーマ・レイヤーを構築する背景となります。テーマは必要に応じていくつでも作成できますが、最低1つはマップ・テーマを定義する必要があります。

地理マップには次のデータ要件があります。

- マップ構成の要件:

- Map Viewer URL:Oracle Application Server MapViewerサービスのURLを指定する必要があります。このサービスは、ADF地理マップ・コンポーネントのレイヤーの背景である、基準となるマップの実行に必要です。OracleAS MapViewerは、Oracle Spatialで管理される空間データを使用してマップをレンダリングするプログラミング・ツールです。URLは次のとおりです。

http://elocation.oracle.com/mapviewer

- ジオコーダURL:住所を座標に変換する場合、ジオコーダのURLを地理マップに指定する必要があります。ジオコーダは、住所をマッピング用の経緯度座標に変換するWebサービスです。URLは次のとおりです。

http://elocation.oracle.com/geocoder/gcserver

- 基準となるマップ:OracleAS MapViewerのMap Builderツールで作成された基準となるマップが必要です。この基準となるマップは、マップ・テーマが要望どおりに機能する詳細レベルで多角形を定義する必要があります。たとえば、特定の地域の各州にグラフを作成するために使用する円グラフ・テーマまたは棒グラフ・テーマがある場合、特定のズーム・レベルでこれらのすべての州に多角形を定義する基準となるマップを持つ必要があります。1つの多角形には1つのグラフのみを表示できます。

- マップ・テーマ: マップ・テーマはそれぞれ1つのデータ・コレクションにバインドする必要があります。データ・コレクションには、基準となるマップの同様の情報にバインド可能な位置情報が含まれる必要があります。

28.2.1 地理マップ・コンポーネントの構成

地理マップには、親コンポーネント、マップ子コンポーネントおよびマップ・テーマを変更するコンポーネントがあります。接頭辞dvt:は、各マップ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。次のマップ・コンポーネントを構成できます。

- マップ(map): マップのメイン・コンポーネント。他のデータ視覚化コンポーネントと異なり、マップ・コンポーネントはデータにバインドされません。かわりに、すべてのマップ・テーマ子コンポーネントが、個々にデータ・コレクションにバインドされます。マップ・コンポーネントには、基準となるマップのID、Oracle Application Server MapViewerサービスを実行しているリモート・サーバーのURL、住所をマッピング用の経緯度座標に変換するジオコーダWebサービスのURLなどのマップに関する一般的な情報が含まれます。
マップ・コンポーネントでは、次のマップ子コンポーネントをサポートしています。

- 色テーマ(mapColorTheme): データ・コレクションにバインドするマップ・レイヤー。色テーマは、基準となるマップ上のリージョンを識別するために使用できます。

- 点テーマ(mapPointTheme): データ・コレクションにバインドするマップ・レイヤー。点テーマで、マップ上の個々の位置が識別されます。
特定のデータ値範囲に属する点を表すイメージをカスタマイズする場合に、オプションで、子マップ点スタイル・コンポーネント(mapPointStyleItem)を使用できます。複数のイメージを定義するには、各イメージのコンポーネントを作成し、関連付けるデータ値の範囲とイメージを指定します。

- 棒グラフ・テーマ(mapBarGraphTheme): データ・コレクションにバインドするマップ・レイヤー。このテーマでは、地点に棒グラフが表示され、その地点に関連する複数のデータ値を表します。たとえば、このタグを使用して、倉庫の位置に在庫レベルを示すグラフを表示します。
マップ棒グラフの棒の色をカスタマイズする場合は、オプションで、マップ棒グラフ・シリーズ・セット・コンポーネント(mapBarSeriesSet)を使用して、マップ棒グラフ・シリーズ・コンポーネント(mapBarSeriesItem)をラップします。各マップ棒グラフ・コンポーネントで、マップ棒グラフの1つの棒の色がカスタマイズされます。

- 円グラフ・テーマ(mapPieGraphTheme): データ・コレクションにバインドするマップ・レイヤー。このテーマでは、特定の地点に円グラフが表示され、その地点の複数の値を表します。たとえば、このタグを使用して、倉庫の位置に在庫レベルを示すグラフを表示します。
マップ円グラフのスライスの色をカスタマイズする場合は、オプションでマップ円スライス・セット・コンポーネント(mapPieSliceSet)を使用して、マップ円スライス・コンポーネント(mapPieSliceItem)をラップします。各マップ円スライス・コンポーネントで、マップ円グラフの1スライスの色がカスタマイズされます。

- 事前定義のグラフ・テーマ(predefinedTheme): データベースにマップ・メタデータとともに格納されているマップ管理者ツールを使用して定義されるマップ・レイヤー。事前定義のテーマ・タグは、独自のカスタムOracle AS MapViewerインスタンスがあり、MapViewerで直接レンダリングできる大きいデータセットを表示する必要がある場合に使用します。

- マップの凡例(mapLegend): マップを作成すると、自動的に作成されます。このコンポーネントを使用してマップの凡例をカスタマイズします。

- 概要マップ(mapOverview): マップを作成すると、自動的に作成されます。このタグを使用して、マップの右下隅に表示される概要マップをカスタマイズできます。

- ツールバー(mapToolbar): マップを含むJSFページの任意の位置にマップ・ツールバーを配置する親コンポーネント。このツールバーには、ツールバーに関連付けられているマップを指すmapID属性が含まれます。ツールバーによって、マップの凡例を表示する機能、選択や距離の測定を行う機能などのマップとの実行時の重要な相互作用が実行されます。マップ・ツールバー・タグには子コンポーネントはありません。

28.2.2 ページへの地理マップの追加方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用して地理マップをJSFページに追加します。ページに地理マップ・コンポーネントをドラッグ・アンド・ドロップすると、Oracle MapViewerサービスと、オプションでジオコーダ・サービスを構成するように要求されます。

構成を完了して、ページに地理マップが追加されると、「プロパティ」ウィンドウを使用して、マップに追加の表示属性を構成できます。

「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図に、テーマ・マップ・コンポーネントmapServerConfigId属性のドロップダウン・メニューを示します。

図28-15 地理マップMapServerConfigId属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して地理マップを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた地理マップの作成」の章を参照してください。

始める前に:

地理マップの属性や地理マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、28.1.3項「マップ・コンポーネントの追加機能」を参照してください。

ページに地理マップを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「マップ」パネルから「地理マップ」をページにドラッグ・アンド・ドロップし、「地理マップの作成」ダイアログを開きます。ダイアログの「マップ」ページを使用して、次の2つの方法のいずれかで「マップ構成」を指定します。

- ドロップダウン・リストを使用して、使用可能な構成を選択します。

- 「追加」アイコンをクリックして、「地理マップ構成の作成」ダイアログを開きます。
ダイアログで「MapViewer URL」と「ジオコーダURL」をそれぞれのドロップダウン・リストから指定するか、「追加」アイコンをクリックしてそれぞれのURLに対して「URL接続の作成」ダイアログを開きます。

注意:

Oracle AS MapViewerサービスには次のURLを使用します: http://elocation.oracle.com/mapviewer

Oracle AS Geocoderサービスには次のURLを使用します: http://elocation.oracle.com/geocoder/gcserver

ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。各ダイアログで構成の作成を完了すると、その設定が「地理マップの作成」ダイアログに反映されます。図28-16に、指定を完了したダイアログのサンプルを示します。

図28-16 「地理マップの作成」ダイアログの「マップ」ページ

2. 必要に応じて、マップの「プレビュー」コントロール・パネルを使用して、基準となるマップの中央揃えおよびズームのレベルを調整します。「リフレッシュ」をクリックすると、「開始X」(中央のX座標)、「開始Y」(中央のY座標)および「ズーム・レベル」(初期ズーム・レベル)の値が更新されます。ヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

注意:

必要に応じて、「地理マップの作成」ダイアログの「テーマ」ページを使用して、マップ上でデータを表示するための色、点、棒グラフまたは円グラフ・テーマを追加し構成します。

「データ・コントロール」パネルとテーマ・バインディング・ダイアログを使用して地理マップを作成すると、データ・バインディングが自動的に作成されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた地理マップおよびテーマ・マップの作成」の章を参照してください。

3. 「プロパティ」ウィンドウに、地理マップの属性を表示します。ヘルプ・ボタンを使用して、mapコンポーネントの完全なタグ・ドキュメントを表示します。

4. 「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- ShowScaleBar: マップ・スケール・バーの表示の指定に使用します。デフォルト値はfalseです。

- ZoomBarPosition: マップ・ズーム・バーの位置の指定に使用します。デフォルト値は、マップの左側に配置する「左」です。その他の有効値は、マップの右側に配置する「右」と、ズーム・バーを表示しない「none」です。

- AutoZoomThemeId: マップ・ビューおよびズーム・レベルが初期マップ表示上で中央揃えされるテーマのIDの指定に使用します。「AutoZoomStrategy」で設定された値は、マップでどのように中央およびズーム・レベルが調整されるかを決めるために使用されます。

- ShowInfoArea: 情報エリアの表示の指定に使用します。デフォルト値はtrueです。

- MapZoom: 地理マップの初期ズーム・レベルの指定に使用します。ズーム・レベルは、ベース・マップの一部としてマップ・キャッシュ・インスタンスで定義されます。

- Unit: 地理マップで使用する測定単位の指定に使用します。デフォルト値は「マイル」です。この属性は「メートル」に設定することもできます。

- 「選択」サブセクション: 面(矩形、円形、多角形)および点の外観選択ツールの定義には、このサブセクションの属性を使用します。詳細は、28.3.3項「マップ選択のカスタマイズおよび使用方法」を参照してください。

5. 「その他」セクションを開きます。このセクションを使用して、次の属性を設定します。

- AutoZoomStrategy: マップの中心とズーム・レベルがどのように調整されるかの指定に使用します。「AutoZoomStrategy」値が「MAXZOOM」(デフォルト)に設定されている場合、マップは最大レベルまでズームされ、「AutoZoomThemeId」内のすべてのオブジェクトが表示されます。「AutoZoomStrategy」が「CENTERATZOOMLEVEL」に設定されている場合、マップの中心がAutoZoomThemeId内のテーマに設定され、「MapZoom」属性の値が開始ズーム・レベルとして使用されます。

- Summary: 地理マップの説明を入力します。この説明は、スクリーン・リーダーのユーザーがアクセスします。

28.2.3 ページに地理マップを追加する場合の処理

「コンポーネント」ウィンドウを使用してページに地理マップを追加すると、JDeveloperによりJSFページにコードが追加されます。例28-1に、JSFページに追加されるコードを示します。

例28-1 JSFページに追加された地理マップ

<dvt:map startingY="46.06" startingX="-78.67" mapZoom="1"
mapServerConfigId="mapConfig2"
baseMapName="ELOCATION_MERCATOR.WORLD_MAP"
inlineStyle="width:600px; height:375px;" id="m2">
<f:facet name="rtPopup"/>
<f:facet name="popup"/>
</dvt:map>

注意:

JDeveloperにより、2つのポップアップ・ファセットが自動的に挿入されます。rtPopupファセットでは、右クリックaf:menu用の単一子コンポーネントがサポートされます。popupファセットでは、左クリックaf:dialogまたはaf:noteWindow用の単一の子コンポーネントがサポートされます。ポップアップ・コンポーネントの構成の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

次に、ADFデータ・コントロール・パネルおよびテーマ・バインディング・ダイアログを使用して、データを色、点、円グラフまたは棒グラフ・テーマで表示するように、地理マップを構成できます。地理マップへのデータ表示方法の構成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた地理マップおよびテーマ・マップの作成」の章を参照してください。

28.2.4 マップ点テーマのアクティブ・データ・サポートに関する必知事項

地理マップ点テーマは、アクティブ・データ・イベントが受け取られたときにPPR(部分ページ・リフレッシュ)リクエストを送ることによりアクティブ・データ・サポート(ADS)をサポートします。PPRのレスポンスにより、次のように点テーマの値が更新されます。

- 更新イベントについては、点は新しい値に更新されます。緯度/経度の変更がある場合、点は新しい場所に移動します。

- 削除イベントについては、点は点テーマから削除されます。

- 挿入イベントについては、変更データで送信された経度/緯度に対応する新しい点が作成され、基準となるマップに表示されます。

ADSの使用の詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

28.3 地理マップ表示属性のカスタマイズ

マップのサイズ、マップの中心およびマップ・サイズのズームの設定、ズーム方法、選択リージョンの外観、およびマップの凡例の表示などの地理表示属性をカスタマイズできます。

28.3.1 マップ・サイズの調整方法

dvt:mapタグのinlineStyle属性を使用して、マップの幅と高さを制御できます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップのサイズを調整する手順:

1. 構造ウィンドウで「dvt:map」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「スタイル」セクションを展開します。「InlineStyle」属性でマップの初期サイズを指定します。
たとえば、幅600ピクセルおよび高さ400ピクセルを指定するには、次の設定を使用します。

width:600px;height:400px

ページの使用可能な幅および高さの半分を使用するマップの場合、次の設定を使用します。

width:50%;height:50%

ベスト・プラクティスのヒント:

inlineStyle属性に100%の幅を指定するかわりに、styleClass属性をAFStretchWidthに設定します。

28.3.2 マップ・ズーム制御のストラテジの指定方法

初期ズーム・レベル、開始位置、初期マップ・テーマおよびズーム方法の地理マップ表示属性をカスタマイズできます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、少なくとも1つのマップの色、点、円グラフまたは棒グラフ・テーマがすでに構成されている必要があります。

マップの初期ズームおよび開始位置を制御する手順:

1. 構造ウィンドウで「dvt:map」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- AutoZoomThemeID: 表示される最初のテーマのIDを入力します。

- ZoomBarStrategy: 「AutoZoomThemeId」のすべてのオブジェクトが表示される最大レベルまでズーム・ダウンするようマップに指示するデフォルト値「MAXZOOM」を選択するか、「AutoZoomThemeId」のテーマを中心とし、ズーム・レベルを「MapZoom」属性の値に設定するようマップに指示する「CENTERATZOOMLEVEL」を選択します。

- マップの開始位置を変更するには、「StartingX」と「StartingY」にそれぞれ緯度と経度を入力します。

- MapZoom: マップの初期ズーム・レベルを入力します。この設定は、ズーム・バー・ストラテジCENTERATZOOMLEVELに必要です。

注意:

autoZoomThemeIDプロパティはmapZoomで設定されたプロパティより優先されます。

28.3.3 マップ選択のカスタマイズおよび使用方法

地理マップには、データを色、円グラフおよび棒グラフのテーマで表示するマップ・エリア用の選択ツールが用意されています。デフォルトでは、選択ツールはマップ・ツールバー上にあり、長方形、円形、多角形または点の選択オプションが含まれています。図28-17に、1つの色テーマでマップ内の1つのエリアを選択するための多角形ツールの使用例を示します。

図28-17 マップの多角形選択ツール

ユーザーが、mapToolbar上の長方形ツール、円形ツール、多角形ツールまたはポイント・ツールを使用して、colorTheme、barGraphThemeおよびpieGraphThemeで選択するときの選択ツールで使用される属性をカスタマイズできます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、少なくとも1つのマップの色、点、円グラフまたは棒グラフ・テーマがすでに構成されている必要があります。

マップ選択ツール属性をカスタマイズする手順:

1. 構造ウィンドウで「dvt:map」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- SelectionFillColor: 選択されたリージョンに適用する塗りつぶしの色の指定に使用します。有効な値はRGB 16進数です。たとえば、黒を指定するには、color="#000000"とします。デフォルト値は#49E0F6です。

- SelectionStrokeColor: 選択されたリージョンに適用する線の色の指定に使用します。有効な値はRGB 16進数です。たとえば、デフォルトの色の黒を指定するには、color="#000000"とします。

- SelectionOpacity: 選択されたリージョンに適用する塗りつぶしの色の不透明度の指定に使用します。有効な値の範囲は0から100で、0は100%の透明、100は不透明です。デフォルト値は40です。

エンド・ユーザーが選択ツールをクリックし、そのツールを使用してマップ上のあるエリアを強調表示すると、そのエリア内のデータ値は、表などの別のUI要素内に表示するか、選択リスナーを使用して、情報パネル内で合計することができます。

図28-18に、赤の色で縁取られたエリア内で州が選択されているマップを示します。このエリアの関連情報は、関連付けられた表に表示されています。

図28-18 選択されたマップ・エリアと表データの表示

長方形選択ツールなどのマップ選択ツールによって選択されたマップ・エリアに関連付けられている値を合計する選択リスナーを使用できます。合計はマップの下の領域に表示されます。バッキングBeanメソッド内で引数にMapSelectionEventをとるクラスを指定する必要があります。例28-2に、バッキングBeanのサンプル・コードを示します。

例28-2 選択リスナー用のバッキングBeanのサンプル・コード

package view;
import java.util.Iterator;
import oracle.adf.view.faces.bi.component.geoMap.DataContent;
import oracle.adf.view.faces.bi.event.MapSelectionEvent;
public class SelectionListener {
private double m_total = 0.0;
public SelectionListener() {
}
public void processSelection(MapSelectionEvent mapSelectionEvent) {
// Add event code here...
m_total = 0.0;
Iterator selIterator = mapSelectionEvent.getIterator();
while (selIterator.hasNext())
{
DataContent dataContent = (DataContent) selIterator.next();
if (dataContent.getValues() != null)
{
Double allData[] = dataContent.getValues();
m_total += allData[0];
}
}
}
public double getTotal () {
return m_total;
}
public void setTotal (double total) {
m_total = total;
}
}

マップの選択値を合計する選択リスナーを設定する手順:

1. 構造ウィンドウで「dvt:map」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを展開します。SelectionListener属性に、バッキングBeanを指すメソッド参照を入力します。次に例を示します。

#{eventBean.processSelection}

28.3.4 マップの凡例をカスタマイズする方法

マップの凡例は、マップのテーマ・データをシンボルとラベルの組合せで説明します。凡例はデフォルトで、マップの初期表示上のポップアップに表示され、マップのツールバーを追加して構成すると、ユーザーが凡例のツールバー・ボタンをクリックしたときに、マップの凡例がウィンドウに表示されるようにすることができます。複数のテーマを構成すると、テーマごとに凡例を表示するために、ドロップダウン・リストを使用できます。図28-19に、複数のテーマの1つの凡例が表示されたマップを示します。

図28-19 地理マップ・テーマの凡例表示

注意:

凡例ツールバー・ボタンを使用可能にするには、マップにツールバーを追加して構成する必要があります。詳細は、28.5項「地理マップへのツールバーの追加」を参照してください。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、少なくとも1つのマップの色、点、円グラフまたは棒グラフ・テーマがすでに構成されている必要があります。

マップの凡例をカスタマイズする手順:

1. 構造ウィンドウで、dvt:mapコンポーネントを右クリックし、「地理マップの中に挿入」→「凡例」を選択します。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。このセクションで、次の属性を設定します。

- InitialShown: マップの初期表示上のポップアップにマップの凡例を表示するかどうかの指定に使用します。デフォルト値はtrueです。

- Width: 凡例の幅を入力します。デフォルト値は200pxです。

- Height: 凡例の高さを入力します。デフォルト値は150pxです。

- PointThemeLabel: 凡例でマップの点テーマに使用するラベルを入力します。すべての点テーマがドロップダウン・リストの1つのオプションとして表示されます。デフォルト値は「点テーマ」です。

- NumberOfColumns: 凡例の色マップ・テーマの色を表示するために使用する列の数を入力します。
たとえば、色テーマで15種類の色を指定し、この属性の値を3に設定すると、そのテーマの凡例には5つの行が表示され、各行に3つの列が表示されます。

28.4 地理マップ・テーマのカスタマイズ

それぞれの地理マップ・テーマ、色、点、円グラフおよび棒グラフは、マップ・テーマ・バインディング・ダイアログ、テーマ・タグの属性またはテーマ・タグの子タグのいずれか1つ以上を使用してカスタマイズできます。

28.4.1 テーマのズーム・レベルのカスタマイズ方法

すべてのマップ・テーマについて、基準となるマップの関連するズーム・レベルに合うズーム・レベルがテーマで指定されていることを確認する必要があります。たとえば、基準となるマップで6から8のズーム・レベルでのみ郡が表示される場合、郡ごとのポイントまたはグラフを表示するテーマには、6から8のズーム・レベルのみを適用します。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、少なくとも1つのマップの色、点、円グラフまたは棒グラフ・テーマがすでに構成されている必要があります。

マップ・テーマのズーム・レベルをカスタマイズする手順:

1. 構造ウィンドウでカスタマイズするdvt:mapColorTheme、dvt:mapPointTheme、dvt:mapBarGraphThemeまたはdvt:mapPieGraphThemeコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。「MinZoom」および「MaxZoom」属性には、希望する低ズーム値と高ズーム値をそれぞれ入力します。

28.4.2 マップ・テーマのラベルのカスタマイズ方法

テーマが凡例または「表示」メニュー、テーマ選択ダイアログに表示される際、デフォルトでは、マップ・テーマのID属性がラベルとして使用されます。shortLabelおよびmenuLabel属性を使用してテーマのタイプ(色、点、棒グラフまたは円グラフ)とデータ(人口、売上げ、在庫など)の両方がわかるラベルを作成し、使用可能なテーマをユーザーが簡単に認識できるようにマップ・テーマ・ラベルをカスタマイズできます。

これらの属性を使用してテーマのタイプ(色、点、棒グラフまたは円グラフ)とデータ(人口、売上げ、在庫など)の両方がわかるラベルを作成し、使用可能なテーマをユーザーが簡単に認識できるようにします。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、少なくとも1つのマップの色、点、円グラフまたは棒グラフ・テーマがすでに構成されている必要があります。

マップ・テーマのラベルをカスタマイズする手順:

1. 構造ウィンドウでカスタマイズするdvt:mapColorTheme、dvt:mapPointTheme、dvt:mapBarGraphThemeまたはdvt:mapPieGraphThemeコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- ShortLabel: マップ凡例に表示される際のテーマのレベルの指定に使用します。

- MenuLabel: 「表示」メニューのテーマ選択ダイアログでのテーマのラベルの指定に使用します。

たとえば、人口に応じてニュー・イングランドの州を色付けする色テーマの場合、次のテキストを入力します。

shortLabel="Color - Population, NE Region"

28.4.3 色マップ・テーマのカスタマイズ方法

色マップ・テーマを作成する際、背景レイヤーに使用する色をカスタマイズできます。最小レンジと最大レンジに関連付ける色を指定し、テーマに使用する色レンジの数を指定できます。たとえば、色がマップ上の人口と関連する場合、人口が最も少ないエリアには最小色が表示され、人口が最も多いエリアには最大色が表示されます。最小色と最大色の間の色のグラデーションが、これらの値の間のレンジに表示されます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、1つのマップの色テーマがすでに構成されている必要があります。

色マップ・テーマの色をカスタマイズする手順:

1. 構造ウィンドウで「dvt:mapColorTheme」コンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「テーマ・データ」セクションを開きます。このセクションを使用して、次の属性を設定します。

- データ値の最小レンジと最大レンジに関連付けられているデフォルト色を変更する場合は、MinColor属性とMaxColor属性の色をそれぞれ選択します。

- このテーマのデフォルトの色レンジの数を変更する場合は、BucketCount属性の整数を変更します。

たとえば、<dvt:mapColorTheme minColor="#000000" maxColor= "#ffffff" bucketCount="5"/>の場合、5つのバケットの色は#000000、#444444、#888888、#bbbbbb、#ffffffになります。

または、各バケットの色を指定できます。複数のバケットの色を指定するには、mapColorThemeのColorList属性に、属性への色配列をバインドするか、セミコロンで区切った文字列を使用します。色はRGB16進数を使用して指定できます。

たとえば、値がcolorList="#ff0000;#00ff00;#0000ff"の場合、最初のバケットの値は赤、2番目のバケットの値は緑、3番目のバケットの値は青になります。

28.4.4 点テーマの点のイメージのカスタマイズ方法

マップの点テーマでは、デフォルトのイメージを使用して各ポイントが示されます。ただし、マップの点テーマで使用するカスタム・イメージごとにmapPointStyleItemコンポーネントを使用すれば、1つの点テーマに複数のカスタム・イメージを指定し、各イメージが表すデータ値の範囲を指定できます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、1つのマップの点テーマがすでに構成されている必要があります。

マップ点テーマのポイントのイメージをカスタマイズする手順:

1. 構造ウィンドウで、dvt:mapPointThemeコンポーネントを右クリックし、「マップ点テーマの中に挿入」→「点スタイルのアイテム」を選択します。

2. 「プロパティ」ウィンドウで「共通」セクションを開きます。このセクションを使用して、次の属性を設定します。

- ImageURL: マップでこのカスタム・イメージに対するデータ値の範囲内のポイントに表示するイメージ・ファイルのパスの指定に使用します。または、属性ドロップダウン・メニューから「編集」を選択して、イメージ・ファイルに移動するためのダイアログを開くことができます。

- MaxValueおよびMinValue: それぞれの属性に最小値と最大値を入力して、このカスタム・イメージが表すデータ値の範囲の指定に使用します。

- Id: 定義するカスタム・イメージの一意の識別子を入力します。

- ShortLabel: このタグで表される範囲内のポイント上にユーザーがカーソルを置いたときに実際のデータ値の前に表示される説明テキストの指定に使用します。
たとえば、最小データ値範囲内のカスタム・ポイントに、次のテキストを入力します。

Low Inventory

- HoverURL: オプションで、エンド・ユーザーがマップ上のイメージにマウスを移動したときに使用する別のイメージのパスを指定します。

- SelectedURL: オプションで、エンド・ユーザーがマップ上のイメージを選択したときに使用する別イメージのパスを指定します。

3. 点テーマに対して作成するカスタム・イメージごとにステップ2を繰り返します。

28.4.5 マップのポイント・イメージをカスタマイズする場合の処理

点テーマに対するデータ値の範囲を表すカスタム・イメージの指定に点スタイル・アイテム・コンポーネントを使用すると、子mapPointStyleItemタグが親mapPointThemeタグ内で定義されます。例28-3に、各倉庫ポイントの在庫の範囲を表す3つのカスタム・ポイント・イメージを持つマップ点テーマに対し、JSFページに生成されるコードを示します。

最初の点スタイル設定(ps0)は、500を超えない値に適用されます。この点スタイルでは、非常に少ない在庫用のイメージを表示し、対応するツールチップ情報が示されます。

2番目の点スタイル設定(ps1)は、500から1000の値に適用されます。この点スタイルでは、少ない在庫用のイメージを表示し、対応するツールチップ情報が示されます。

最後の点スタイル設定(ps2)は、1000から1600の値に適用されます。この点スタイルでは、多い在庫用のイメージを表示し、対応するツールチップ情報が示されます。

例28-3 カスタム・ポイント・イメージを使用するマップ点テーマのコード

<dvt:map id="map1"
...
<dvt:mapPointTheme id="mapPointTheme1"
shortLabel="Warehouse Inventory"
value="{bindings.WarehouseStockLevelsByProduct1.geoMapModel}">
<dvt:mapPointStyleItem id="ps0" minValue="0"
maxValue="500"
imageURL="/images/low.png"
selectedImageURL="/images/lowSelected.png"
shortLabel="Very Low Inventory"/>
<dvt:mapPointStyleItem id="ps1" minValue="500"
maxValue="1000"
imageURL="/images/medium.png"
selectedImageURL="/images/mediumSelected.png"
shortLabel="Low Inventory"/>
<dvt:mapPointStyleItem id="ps2" minValue="1000"
maxValue="1600"
imageURL="/images/regularGreen.png"
selectedImageURL="/images/regularGreenSelected.png"
shortLabel="High Inventory"/>
</dvt:mapPointTheme>
</dvt:map>

28.4.6 棒グラフ・テーマの棒のカスタマイズ方法

マップ棒グラフ・テーマを作成すると、デフォルトの色がグラフの棒に割り当てられます。棒の色はカスタマイズできます。1つのmapBarSeriesSetタグを使用して、棒グラフ・テーマのすべてのmapBarSeriesItemタグをラップし、グラフ内の棒ごとにmapBarSeriesItemタグを挿入します。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、1つのマップの棒グラフ・テーマがすでに構成されている必要があります。

マップ棒グラフ・テーマの棒の色をカスタマイズする手順:

1. 構造ウィンドウで「dvt:mapBarGraphTheme」タグを右クリックし、「棒グラフ・テーマの中に挿入」→マップ棒グラフ系列セットを選択します。
このタグに設定する属性はありません。個々の棒系列アイテムのタグのラップに使用されます。

2. 構造ウィンドウで「dvt:mapBarSeriesSet」タグを右クリックし、「棒系列の設定の中に挿入」→マップ棒グラフ系列アイテムと選択します。

3. 「プロパティ」ウィンドウで次の属性を設定します。

- Id: 棒グラフ系列アイテムの一意のIDを入力します。

- Color: 棒に使用する一意の色を入力します。有効な値は、RGB16進数色です。または、属性ドロップダウン・メニューから「編集」を選択して、「プロパティの編集: 色」ダイアログを開くことができます。

4. グラフ内の棒ごとにステップ3を繰り返します。

注意:

グラフ内の棒の順序を見つけ、変更するには、mapBarGraphThemeコンポーネントの「編集」アイコンをクリックして、「棒グラフ・マップ・テーマ・バインディングの編集」ダイアログを調べます。このダイアログの「系列属性」列のエントリの順序で、グラフに表示される棒の順序が決まります。既存の系列を選択した後、矢印アイコン(「上」、「下」、「一番上」、「一番下」)を使用して系列の順序を変更するか、「削除」アイコンを使用して系列を削除します。

28.4.7 マップ棒グラフ・テーマの棒をカスタマイズする場合の処理

「棒グラフ・マップ・テーマ・バインディングの編集」ダイアログを使用してマップ棒グラフ・テーマ内の棒をカスタマイズすると、棒の順序にはダイアログの「系列属性」列のエントリの順序が反映されます。例28-4に、マップ棒グラフの棒をカスタマイズする場合にJSFページに生成されるサンプル・ソース・コードを示します。

例28-4 マップ棒グラフの棒をカスタマイズする場合のコード

<dvt:map
...
<dvt:mapBarGraphTheme
...
<dvt:mapBarSeriesSet>
<dvt:mapBarSeriesItem color="#333399" id="bar1"/>
<dvt:mapBarSeriesItem color="#0000ff" id="bar2"/>
</dvt:mapBarSeriesSet>
</dvt:mapBarGraphTheme>
</dvt:map>

28.4.8 円グラフ・テーマのスライスのカスタマイズ方法

マップ円グラフ・テーマを作成すると、デフォルトの色がグラフのスライスに割り当てられます。スライスの色はカスタマイズできます。1つのmapPieSliceSetタグを使用して、円グラフ・テーマのすべてのmapPieSliceItemタグをラップし、グラフ内のスライスごとにmapPieSliceItemタグを挿入します。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップでデータを表示するために、1つのマップの円グラフ・テーマがすでに構成されている必要があります。

マップ円グラフ・テーマのスライスの色をカスタマイズする手順:

1. 構造ウィンドウでdvt:mapPieGraphThemeタグを右クリックし、「円グラフ・テーマの中に挿入」→「円グラフの区分の設定」を選択します。
このタグに設定する属性はありません。個々の円グラフ・アイテムのタグのラップに使用されます。

2. 構造ウィンドウで「dvt:mapPieSliceSet」ノードを右クリックし、「マップ円スライス設定の中に挿入」→「円グラフの区分のアイテム」を選択します。

3. 「プロパティ」ウィンドウで次の属性を設定します。

- ID: 円スライス・アイテムの一意のIDを入力します。

- 色: 円スライスに使用する一意の色を入力します。有効な値は、RGB16進数色です。または、属性ドロップダウン・メニューから「編集」を選択して、「プロパティの編集: 色」ダイアログを開くことができます。

4. グラフ内の円スライスごとにステップ3を繰り返します。

注意:

グラフ内のスライスの順序を見つけ、変更するには、mapPieGraphThemeコンポーネントの「編集」アイコンをクリックして、「円グラフ・マップ・テーマ・バインディングの編集」ダイアログを調べます。このダイアログの「円グラフの区分の属性」列のエントリの順序で、グラフに表示されるスライスの順序が決まります。既存の円スライスを選択した後、矢印アイコン(「上」、「下」、「一番上」、「一番下」)を使用してスライスの順序を変更するか、「削除」アイコンを使用してスライスを削除します。

28.4.9 マップ円グラフ・テーマのスライスをカスタマイズする場合の処理

「円グラフ・マップ・テーマ・バインディングの編集」ダイアログを使用してマップ円グラフ・テーマ内のスライスをカスタマイズすると、スライスの順序にはダイアログの「円グラフの区分の属性」列のエントリの順序が反映されます。例28-5に、マップ円グラフのスライスをカスタマイズする場合にJSFページに生成されるサンプル・コードを示します。

例28-5 マップ円グラフのスライスをカスタマイズする場合のコード

<dvt:map
...
<dvt:mapPieGraphTheme
...
<dvt:mapPieSliceSet>
<dvt:mapPieSliceItem color="#ffffff" id="slice1"/>
<dvt:mapPieSliceItem color="#ffff00" id="slice2"/>
<dvt:mapPieSliceItem color="#ff0000" id="slice3"/>
</dvt:mapPieSliceSet>
</dvt:mapPieGraphTheme>
</dvt:map>

28.5 地理マップへのツールバーの追加

地理マップを作成する際、凡例と情報パネルの表示やテーマの選択(同じタイプの複数のテーマがある場合)を行ったり、距離測定、領域測定または選択ツールを使用したりするために、マップ・ツールバーを追加し構成することもできます。図28-20に、マップ・ツールバーを示します。

図28-20 地理マップ・ツールバー

ツールバーの機能の詳細は、28.1.2.1項「地理マップのエンド・ユーザー機能およびプレゼンテーション機能」を参照してください。

28.5.1 ツールバーのマップへの追加方法

マップ・ツールバーは別のコンポーネントで、JSFページでマップの上にも下にも配置できます。

始める前に:

マップの属性やマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.2.1項「地理マップ・コンポーネントの構成」を参照してください。

ページにすでにマップが存在している必要があります。ない場合は、この章の指示に従ってマップを作成します。詳細は、28.2.2項「ページへの地理マップの追加方法」を参照してください。

マップ・ツールバーを追加し構成する手順:

1. 構造ウィンドウで「dvt:map」ノードを右クリックし、「地理マップの前に挿入」または「地理マップの後ろに挿入」→「ADFデータ視覚化」を選択して、ADFデータ視覚化アイテム・ダイアログを開きます。

2. ダイアログで、「ツールバー」を選択して、「マップ・ツールバーの作成」ダイアログを開きます。

3. ダイアログのドロップダウン・リストから、このツールバーが動作するマップのIDを選択し、「OK」をクリックします。

4. 「プロパティ」ウィンドウで「共通」セクションを開きます。このセクションで、次の属性を設定します。

- ShowDistanceTools: ツールバー上で距離ツールを使用可能にするかどうかの指定に使用します。デフォルト値はtrueです。

- ShowSelectThemeDialog: ツールバーの「表示」メニューで「テーマの選択」ダイアログを使用可能にするかどうかの指定に使用します。デフォルト値はtrueです。

- ShowSelectThemeMenuItem: ツールバーの「表示」メニューで「テーマの選択」オプションを使用可能にするかどうかの指定に使用します。デフォルト値はtrueです。

- ShowSelectionTools: ツールバーでエリア長方形、円形、多角形またはポイント・ツールなどの選択ツールを使用可能にするかどうかの指定に使用します。デフォルト値はtrueです。

- ShowViewMenu: ツールバーで「表示」メニューを使用可能にするかどうかの指定に使用します。デフォルトはtrueです。

- ShowZoomTools: ツールバーでズーム・インおよびズーム・アウト・ツールを使用可能にするかどうかの指定に使用します。デフォルトはtrueです。

28.5.2 ツールバーをマップに追加する場合の処理

ツールバーをマップに追加すると、次のようになります。

- JSFページのマップの上または下に、指定したとおりツールバーが表示されます。デフォルトでは、1つ以上のツールの可視性を変更しないかぎり、ツールバーにはすべてのツールが含まれます。

- ソース・コードが生成され、JSFページでマップのコードの上または下に表示されます。

例28-6に、IDがmap_usのマップに関連付けられているツールバーのサンプル・コードを示します。例では、マップのコードの位置を示しています。

例28-6 マップ・ツールバーに対して生成されるコード

<af:form>
<dvt:mapToolbar mapId="map_us" id="T1"/>
<dvt:map  id="map_us"
...
</dvt:map>
</af:form>

28.6 テーマ・マップ・コンポーネントの使用方法

テーマ・マップでデータを表示するには、名前付きのデータ・コレクションが必要です。データ・コレクションとは、データ・モデルでのデータ・オブジェクトのセット(行セット)を意味します。データ・コレクション内の各オブジェクトは、データ・モデル内の特定の構造化データ・アイテムを示します。

28.6.1 テーマ・マップの構成

テーマ・マップには、基準となる地理マップを指定する親コンポーネントと、色、パターンまたはマーカー、あるいはその両方でマップ・リージョンのスタイルを設定する、またはマップに凡例を追加するために使用される子コンポーネントがあります。接頭辞dvt:は、各テーマ・マップ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。次のマップ・コンポーネントを構成できます。

- テーマ・マップ・コンポーネント(thematicMap): データが表示される基準となるマップの指定に使用されるメインのテーマ・マップ・コンポーネント。テーマ・マップは、米国、世界をはじめ、世界の大陸や地域(EMEAやAPACなど)などのあらかじめ作成された基準となるマップとともにパッケージ化されています。テーマ・マップ・コンポーネントでは、基準となるマップを表示するためのマップ・サービスは必要ありません。

- レイヤー(areaLayer): 基準となるマップで表示されるレイヤーの指定に使用します。各areaLayerコンポーネントは、単一のレイヤー、たとえば、基準となるUSAマップ内の国または州を参照し、areaLayerタグが存在するマップ・レイヤーのみが表示されます。次にレイヤー内にデータ・レイヤーをネストすることにより、データが1つのレイヤーに関連付けられます。areaLayer子タグは、面データ・レイヤー(areaDataLayer)と点データ・レイヤー(pointDataLayer)です。

- 面データ・レイヤー(areaDataLayer): マップ・レイヤーをデータ・コレクションに関連付けるために使用します。スタンプを使用すれば、データ・モデル内の各データ行をスタイル(色またはパターンなど)、マーカー(円形または四角形など)、またはイメージにより識別できます。

注意:

スタンプを使用すると、テーマ・マップではエリア、マーカーまたはイメージごとに子コンポーネントが作成されません。むしろ、コンポーネントのコンテンツは、データ・コレクションの行など、データ属性ごとに1回、繰り返しレンダリングされるか、スタンプされます。

子コンポーネントにスタンプが設定されるたびに、現在のコンポーネントのデータがEL式のデータ・レイヤー・コンポーネントによって使用されるvarプロパティにコピーされます。テーマ・マップのレンダリングが完了したら、varプロパティは削除されるか前の値に戻ります。

データ・レイヤーの位置は、直下の子areaLocationタグによって識別されます。このコンポーネントでは、マップ・レイヤー内の名前付きのリージョンまたはエリアの場所を指定します。子タグ内でareaLocationタグにスタイル設定できる3種類のデータには、次のものがあります。

- 面(area): スタイル属性(塗りつぶし色、パターンまたは不透明度など)をマップの地理的リージョンにスタンプ・アウトするために使用します。

- マーカー(marker): マップ上のデータ・ポイントに関連付けられた組込み形状またはカスタム形状をスタンプ・アウトするために使用します。マーカーは、基礎となるデータに基づいて色やパターンなどの異なるスタイル属性によりカスタマイズできます。

- イメージ(af:image): マップの地理的リージョンに関連付けられたイメージをスタンプ・アウトするために使用します。

注意:

areaタグまたはmarkerタグにスタイル属性を直接指定するかわりに、子attributeGroupsタグを使用して、データ・セットのカテゴリ定義に基づきスタイル属性タイプを自動的に生成することができます。areaタグまたはmarkerタグとattributeGroupsタグの両方で、同じスタイル属性が設定されている場合は、attributeGroupsスタイル・タイプが優先されます。

注意:

areaまたはmarkerタグで表されている数値の書式を設定でき、たとえば、af:convertNumberタグを使用することで、通貨の書式を適用できます。詳細は、28.7.3項「エリアおよびマーカー・ラベルでの数値データ値の書式設定方法」を参照してください。

図28-21に、テーマ・マップのデータ・レイヤーを構成するための基本的なタグ構造を示します。

図28-21 テーマ・マップ・エリア・データ・レイヤーのタグ構造

- ポイント・データ・レイヤー(pointDataLayer): マップを特定のデータ・ポイントに、またはマップ・レイヤーをデータ・コレクションに関連付けるために使用します。データ・ポイントは、マップ・レイヤー内の名前付きポイント(米国マップ内の都市など)、または経度と緯度により、指定できます。スタンプを使用すれば、データ・モデル内の各ポイントは、マーカー(円形や四角形、またはイメージ)により識別できます。

注意:

スタンプを使用すると、テーマ・マップではマーカーまたはイメージごとに子コンポーネントが作成されません。むしろ、コンポーネントのコンテンツは、データ・コレクションの行など、データ属性ごとに1回、繰り返しレンダリングされるか、スタンプされます。

子コンポーネントにスタンプが設定されるたびに、現在のコンポーネントのデータがEL式のポイント・レイヤー・コンポーネントによって使用されるvarプロパティにコピーされます。テーマ・マップのレンダリングが完了したら、varプロパティは削除されるか前の値に戻ります。

ポイント・レイヤーの位置は、直下の子pointLocationタグで識別されます。位置は、経度と緯度を指定するように構成したり、マップ・レイヤー内の名前付きエリアの位置によって構成したりできます。子タグ内でpointLocationタグにスタイル設定できる2種類のデータには、次のものがあります。

- マーカー(marker): マップ上のデータ・ポイントに関連付けられた組込み形状またはカスタム形状をスタンプ・アウトするために使用します。マーカーは、基礎となるデータに基づいて色やパターンなどの異なるスタイル属性によりカスタマイズできます。

- イメージ(af:image): マップの地理的リージョンに関連付けられたイメージをスタンプ・アウトするために使用します。

注意:

markerタグにスタイル属性を直接指定するかわりに、子attributeGroupsタグを使用して、データ・セットのカテゴリ定義に基づきスタイル属性タイプを自動的に生成することができます。markerタグとattributeGroupsタグの両方で、同じスタイル属性が設定されている場合は、attributeGroupsスタイル・タイプが優先されます。

注意:

markerタグで表されている数値の書式を設定でき、たとえば、af:convertNumberタグを使用することで、通貨の書式を適用できます。詳細は、28.7.3項「エリアおよびマーカー・ラベルでの数値データ値の書式設定方法」を参照してください。

図28-22に、テーマ・マップのポイント・データ・レイヤーを構成するための基本的なタグ構造を示します。

図28-22 テーマ・マップ・ポイント・データ・レイヤーを構成するためのタグ構造

ポイント・データ・レイヤーがテーマ・マップ・コンポーネントの直接の子として構成されている場合、データ・ポイントは常にグローバル・ポイント・レイヤーとして表示されます。ポイント・レイヤーがマップ・レイヤー内にネストされている場合、データ・ポイントは、そのマップ・レイヤーが表示されているときにのみ表示されます。

図28-23に、ポイント・データ・レイヤーをネストするためのタグ構造を示します。この図では、ポイント・データ・レイヤーpd1は、statesレイヤーが表示される場合にのみ表示されます。ポイント・データ・レイヤーpd2は、常に表示されます。

図28-23 テーマ・マップ・ポイント・データ・レイヤーをネストするためのタグ構造

- カスタム・レイヤー(customAreaLayer): 独立したリージョン・データから新規のマップ・レイヤーを作成し、新規に作成されたレイヤーをレイヤー階層に挿入するために使用します。カスタム・レイヤーは、事前定義のマップ・レイヤーを開き、下位レベルのリージョンを集約することで作成され、カスタム・レイヤー内に新規のリージョンが形成されます。カスタム・マップ・レイヤーを定義すると、他のマップ・レイヤーと同じように使用されます。
子customAreaコンポーネントを使用して、事前に定義された基準となるマップから、新しいエリアを形成するために集約されるリージョンを指定します。

- カテゴリ属性(attributeGroups): データ・セット内のカテゴリ・データ値に基づいて色または形状などのスタイル属性値を生成するために使用します。
テーマ・マップ内のすべてのエリアまたはマーカーにわたるデフォルトのスタンプを構成する別の方法として、areaまたはmarkerコンポーネントの子attributeGroupsタグを使用して、データ・セット内のカテゴリ・グループに基づいてスタイル属性タイプを自動的に生成します。areaタグまたはmarkerタグとattributeGroupsタグの両方で、同じスタイル属性が設定されている場合は、attributeGroupsスタイル・タイプが優先されます。

データ・モデルでグループ化の基準となる列を表す属性に基づき、attributeGroupsコンポーネントにより、データ内の一意の値またはグループごとにスタイル値を生成できます。attributeGroupsタグのtypeプロパティにより、スタイル属性のタイプが指定され、それに対して値が作成されます。areaコンポーネントに対してサポートされているタイプは、color、patternおよびopacityです。markerコンポーネントに対してサポートされているタイプは、color、shape、pattern、opacity、scaleXおよびscaleYです。これらのタイプは、一意のデータ値ごとに複数のスタイル・プロパティを生成するために、スペース区切りのリストにまとめることができます。

生成されるデフォルトのスタイル値は、ADFスキンのCSSスタイル・プロパティを使用して定義されます。各attributeGroupsタイプには、ADFスキンで定義されたデフォルトのランプがあり、索引ベースのセレクタを目的の値に設定することによりカスタマイズできます。

データの表示でより精細な詳細レベルを実現するために、attributeGroupsコンポーネントで指定されたグループ化のルールを、次の子コンポーネントで定義される2つのタイプのルールによりオーバーライドできます。

- 一致ルール(attributeMatchRule): データが特定の値に一致する場合、属性を置き換えるために使用します。

- 例外ルール(attributeExceptionRule): 特定のブール条件が満たされる場合に、属性値を別の値に置き換えるために使用します。

注意:

attributeMatchRuleタグおよびattributeExceptionRuleタグでは、子f:attributeタグを使用してオーバーライド値が定義され、nameプロパティにより属性のタイプ(色または形状)が、valueプロパティにより使用するオーバーライド値(赤または正方形など)が定義されます。attributeGroupsタグのvalueプロパティがattributeMatchRuleのグループ・プロパティの値をオーバーライドする場合、子f:attributeのスタイル値が、デフォルト・ランプの次の値のかわりにそのデータのグループに割り当てられます。

f:attributeタグのnameプロパティは、attributeGroupsタグ・グループ化ルールのタイプにリストされている属性の1つに一致する必要があります。オーバーライドにより指定された値が、attributeGroupsによって返された事前作成のランプ内にもある場合、その値はオーバーライドでのみ使用され、事前作成のランプではスキップされます。

- 凡例(legend): シンボルとラベルのペアにスタイル設定されたマップのデータの説明の表を表示するために使用します。凡例コンポーネントでは、色、形状、カスタム形状、塗りつぶしパターン、不透明度およびイメージのシンボルをサポートしています。

- 汎用セクション(legendSection): マップ内で表示するデータのスタイルを設定するためにスタンプされる、テーマ・マップのarea、marker、attributeGroupsまたはaf:imageコンポーネントを指す1つ以上のセクションを使用します。attributeGroupsコンポーネントからの汎用アイテムにより、エリアまたはマーカーの属性タイプを異なるセクションに分けられます。

- 汎用グループ(showLegendGroup): 汎用セクション・コンポーネントを含む公開可能なセクションを作成するために使用します。

28.6.2 事前作成された基準となるマップに関する必知事項

テーマ・マップ・コンポーネント用に用意されている基準となる各マップには、一連のリージョンを表す事前に作成された複数のマップ・レイヤーがあります。たとえば、基準となるworldマップには、continents用のマップ・レイヤーとcountries用の別のレイヤーが含まれています。下位レベルのマップ・レイヤーのリージョンは、集約されて地理的階層内の次のレベルを構成します。マップ・レイヤーは、areaLayerコンポーネントのlayer属性で指定されます。それぞれのベース・マップには、いくつかのリージョンのセットと、都市の固定セットが1つ含まれます。

表28-1に、基準となる各マップ用の有効なマップ・レイヤーを示します。

表28-1 事前に作成された基準となるマップとレイヤー

基準となるマップ

レイヤー

usa

country, states, counties

world

continents, countries

worldRegions

regions, countries

africa、asia、australia、europe、northAmerica、southAmerica

continents, countries

apac、emea、latinAmerica、usaAndCanada

regions、countries、cities

データ・コレクションをテーマ・マップにバインドする際、データが表示される基準となるマップからリージョンのマップ位置IDを使用してエリアまたはポイント・データの位置を指定する列を、データ・モデルに指定する必要があります。エリアの位置はareaLocationコンポーネントのname属性で指定され、ポイントの位置は、type属性がpointNameに設定されている場合、pointLocationコンポーネントのpointName属性で指定されます。

事前作成されたマップ・レイヤーごとに、すべてのテーマ・マップの基準となるマップの位置IDを記載したカンマ区切りの値(CSV)ファイルをダウンロードできます。これらのリンクは、areaLocationコンポーネントのname属性のタグ・ドキュメントで検索します。データ視覚化コンポーネントのタグ・ドキュメントにアクセスするには、構造ウィンドウで該当のコンポーネントを選択し、「プロパティ」でヘルプ・ボタンをクリックします。

詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の基準となるマップの位置IDに関する必知事項に関する項を参照してください。

28.6.3 レイヤー・ブラウザの使用方法

JDeveloperには、マップ・レイヤー、データ・レイヤーの構築や、テーマ・マップでデータを表示するためのエリアおよびマーカーのスタイル設定の開発を容易にするツールとして、レイヤー・ブラウザが用意されています。レイヤー・ブラウザは、ビジュアル・エディタ内のテーマ・マップの一番上に表示され、位置やサイズを変更できます。表示されていない場合は、マップ内で右クリックし、「レイヤー・ブラウザを開く」を選択します。

レイヤー・ブラウザでは、テーマ・マップとその階層マップ・レイヤーおよびコンポーネントの論理的構造を視覚的に表します。レイヤー・ブラウザでのコンポーネントの選択は、「プロパティ」ウィンドウ、「構造」ウィンドウおよびページのソース・コードでの選択と調整されます。

レイヤー・ブラウザのツールバーには、次の操作用のコントロールが表示されます。

- 追加: テーマ・マップにコンポーネントを追加して構成し、ソース・コードを追加するマップ・レイヤー、データ・レイヤー、エリアまたはマーカーの作成ダイアログを開くためのドロップダウン・メニューが表示されます。メニューの選択肢は、テーマ・マップの正しい構造を維持するためのものです。

- 編集: コンポーネントの設定を変更し、テーマ・マップのソース・コードを変更するために、データ・レイヤー、エリアまたはマーカーのバインディング・ダイアログを開きます。

- 削除: 選択したマップ・レイヤー、データ・レイヤー、エリアまたはマーカーをテーマ・マップ構造とソース・コードから削除します。

レイヤー・ブラウザには、階層構造に示された各コンポのIDが表示されます。コンポーネントには、一意の連続的に番号が付けられたid値が自動的に割り当てられます。マップ・レイヤー(areaLayer)には、al1、al2、al3などが割り当てられます。カスタム・レイヤー(customAreaLayer)には、cal1、cal2、cal3が割り当てられ、areaLayerコンポーネントにより連続的な順序で参照されます。エリア(areaDataLayer)およびポイント(pointDataLayer)コンポーネントを含むデータ・レイヤーには、dl1、dl2、dl3などが割り当てられます。ポイント・レイヤー(pointDataLayer)は、テーマ・マップの直接の子として追加されると、グローバル・ポイント・レイヤーとなり、テーマ・マップに常に表示されます。マーカー(marker)には、m1、m2、m3などが割り当てられます。エリア(area)には、a1、a2、a3などが割り当てられます。

図28-23に、テーマ・マップの階層構造を表示したレイヤー・ブラウザを示します。

図28-24 テーマ・マップ・レイヤー・ブラウザ

28.6.4 ページへのテーマ・マップの追加方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用してテーマ・マップをJSFページに追加します。ページにテーマ・マップ・コンポーネントをドラッグ・アンド・ドロップすると、コンポーネント・ギャラリに使用可能な基準となるマップ、事前に作成されたリージョン・レイヤーおよびカスタム・レイヤー・オプションが表示され、テーマ・マップの作成時に視覚的に支援します。図28-25に、基準となる米国のマップと州レイヤーが選択されたテーマ・マップのコンポーネント・ギャラリを示します。

図28-25 テーマ・マップのコンポーネント・ギャラリ

ダイアログが完了して、ページにテーマ・マップが追加されると、「プロパティ」ウィンドウを使用して、データ値を指定し、マップに追加の表示属性を構成できます。

「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図28-26に、テーマ・マップ・コンポーネントtooloTipDisplay属性のドロップダウン・メニューを示します。

図28-26 テーマ・マップToolTipDisplay属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してテーマ・マップを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされたテーマ・マップの作成に関する項を参照してください。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、28.1.3項「マップ・コンポーネントの追加機能」を参照してください。

ページにテーマ・マップを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「マップ」パネルから「テーマ・マップ」をページにドラッグ・アンド・ドロップし、「コンポーネント・ギャラリ」で「テーマ・マップの作成」ダイアログを開きます。
ダイアログを使用して、事前に作成されたマップの階層で、テーマ・マップで表示する基準となるマップとレイヤーを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

2. 「プロパティ」ウィンドウに、テーマ・マップの属性を表示します。ヘルプ・ボタンを使用して、thematicMapコンポーネントの完全なタグ・ドキュメントを表示します。

3. 「共通」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Basemap: コンポーネント・ギャラリで選択された基準となるマップを変更する場合は、ドロップダウン・リストを使用して、有効な値usa、world、africa、asia、australia、europe、northAmerica、southAmerica、apac、emea、latinAmerica、usaAndCanadaまたはworldRegionsから選択します。

- Map Layers: 「プロパティ」ウィンドウ内に表示されるダイアログを使用して、テーマ・マップで表示する追加のマップ・レイヤーを追加します。たとえば、基準となる米国のマップには、国、州、郡、都市(ポイント)のレイヤーとカスタム・レイヤーが含まれています。「追加」アイコンに関連付けられたドロップダウン・リストを使用して、事前に定義された地理的階層に使用可能なマップ・レイヤーを追加、カスタム・マップ・レイヤーを作成して階層に挿入、または基準となるマップにグローバル・ポイント・レイヤーを追加します。「削除」アイコンを使用して、テーマ・マップで表示しないレイヤーを削除します。図28-27は、thematicMapコンポーネントの「プロパティ」ウィンドウに強調表示されたマップ・レイヤー・ダイアログを示しています。

図28-27 「プロパティ」ウィンドウのマップ・レイヤー・ダイアログ

または、レイヤー・ブラウザを使用して、テーマ・マップにマップ・レイヤーを追加できます。詳細は、28.6.3項「レイヤー・ブラウザの使用方法」を参照してください。

4. 「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- TooltipDisplay: デフォルト(auto)では、ユーザーがマップ上でカーソルを移動すると、テーマ・マップに事前作成されたマップ・ラベルを使用してツールチップが自動的に表示されます。データが使用可能な場合、areaまたはmarkerコンポーネント・スタンプのshortDesc属性にラベルが連結されます。その他の有効な値には、ツールチップの表示を無効にするnoneと、スタンプからのデータのみを表示し、基準となるマップの事前に作成されたラベルを含めないshortDescがあります。詳細は、28.7項「テーマ・マップ表示属性のカスタマイズ」を参照します。

- 「アニメーション」サブセクション: このサブセクションのアニメーション属性を使用して、テーマ・マップのアニメーションを構成します。詳細は、28.8.3項「アニメーション効果の構成方法」を参照してください。

5. 「動作」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Drilling: テーマ・マップ・レイヤー間でデータ・ビューのドリルを有効にするために使用します。ドロップダウン・リストから「オン」を選択して、ドリルを有効にします。デフォルト値は「オフ」です。

- MaintainDrill: 新しいエリアをドリルするときに、以前にドリルしたエリアのドリル状態を維持するために、オプションのtrue値を指定するために使用します。デフォルト値はfalseです。

- DrillBehavior: ドリル対象のエリアでオプションのzoomToFit効果を指定するために使用します。デフォルト値はnoneです。

- ControlPanelBehavior: ドロップダウン・リストを使用して、テーマ・マップ・コントロール・パネルの表示を選択します。デフォルト値は、非表示/表示ボタンのみを表示するinitCollapsedです。その他の有効な値は、hiddenとinitExpandedです。

- FeaturesOff: 実行時に無効にするエンド・ユーザー機能の空白区切りリストを入力します。有効な値は、pan、zoomおよびzoomToFitです。デフォルト値は指定なしです。

6. 「その他」カテゴリを開きます。「サマリー」属性に、テーマ・マップの説明を入力します。この説明は、スクリーン・リーダーのユーザーがアクセスします。

28.6.5 ページにテーマ・マップを追加する場合の処理

「コンポーネント」ウィンドウを使用してテーマ・マップを作成すると、JDeveloperによりJSFページにコードが挿入されます。例28-7に、JSFページに挿入されるコードを示します。

例28-7 JSFページ内のテーマ・マップ・コード

<dvt:thematicMap basemap="usa" id="tm1">
<dvt:areaLayer layer="states" id="al1"/>
</dvt:thematicMap>

レイヤー・ブラウザには、テーマ・マップの階層構造が表示されます。図28-28に、「コンポーネント」ウィンドウを使用してテーマ・マップを作成した後のレイヤー・ブラウザを示します。

図28-28 テーマ・マップ・レイヤー・ブラウザ

次に、ADFデータ・コントロール・パネルおよびテーマ・バインディング・ダイアログを使用して、データをスタイル設定したエリアまたはマーカーで表示するように、テーマ・マップを構成できます。テーマ・マップへのデータ表示方法の構成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされたテーマ・マップの作成に関する項を参照してください。

28.6.6 テーマ・マップのイメージ形式に関する必知事項

テーマ・マップでは、HTML5、FlashおよびPortable Network Graphics (PNG)のイメージ形式がサポートされます。すべてのイメージ形式で、右から左への表示を使用するロケールがサポートされます。

デフォルトでは、テーマ・マップはクライアント・ブラウザでサポートされる最良の出力形式で表示されます。最良の出力形式をクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。たとえば、クライアントがHTML5をサポートしていない場合、アプリケーションでは次が使用されます。

- Flash (Flash Playerが使用可能な場合)
アプリケーション全体でFlashコンテンツの使用を制御するには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

- PNG出力形式
静的レンダリング、たとえば、Flash表示パンおよびズーム状態の保持は、印刷可能なPNG出力形式使用時には完全にサポートされますが、次のような一部の対話機能は使用できません。

- アニメーション

- コンテキスト・メニュー

- ドラッグ・アンド・ドロップ・ジェスチャ

- ポップアップのサポート

- 選択項目

28.7 テーマ・マップ表示属性のカスタマイズ

事前に作成されたマップ・レイヤー・ラベルや、テーマ・マップのデータ値をスタンプ・アウトするエリアおよびマーカー・コンポーネントのラベルなど、テーマ・マップのラベルの表示属性をカスタマイズできます。特殊な書式設定(通貨やパーセンテージなど)が必要なデータ値は、特殊記号や小数点を表示するように構成できます。ユーザーがカーソルをマップ上で移動したときにデータを表示するためのツールチップを構成することもできます。

28.7.1 テーマ・マップ・ラベルのカスタマイズ方法

デフォルトでは、事前に作成された基準となるマップの各マップ・レイヤーの各リージョンには、短いタイプと長いタイプのラベル(たとえば、基準となるworldマップのcountriesレイヤーでのBRAとBrazil)があります。マップ・レイヤーは、layer属性のareaLayerコンポーネントで、たとえば次のように指定されます。

<dvt:areaLayer id="al1" layer="countries">

注意:

ラベルは、マップ・レイヤーの名前付きリージョン内にちょうど収まる場合にのみ表示されます。ラベルがリージョン内に納まらない場合は、基準となるマップのそのレイヤーに対してかわりのラベル位置を決める引出し線が指定されていないと表示されません。事前作成のusaマップのみ、statesレイヤー外のラベル用の引出し線があります。

図28-29に、基準となるeuropeマップとusaマップのデフォルトのラベルを示します。

図28-29 基準となるヨーロッパと米国のマップのデフォルトのラベル

基準となるマップで提供されている表示およびスタイル用のデフォルトのラベルはカスタマイズできます。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

マップ・レイヤー・ラベルをカスタマイズする手順:

1. 構造ウィンドウでラベルのカスタマイズを行うマップ・レイヤーを表すdvt:areaLayerコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」セクションを開いて次の属性を設定します。

- LabelDisplay: ドロップダウン・リストを使用して、事前に作成された基準となるマップのレイヤー用ラベルをどのように表示するかを選択します。有効な値は、リージョンに十分なスペースがある場合にラベルを表示するauto (デフォルト)と、基準となるマップのこのレイヤーのすべてのリージョン用のラベルを表示するon、およびラベルの表示を無効にするoffです。

- LabelStyle: ラベル・フォント用に使用するフォント関連のCSSスタイルを入力します。

- LabelType: ドロップダウン・リストを使用して、事前に作成された基準となるマップの表示するラベルを選択します。有効な値は、基準となるマップで定義されている短いラベルを表示するshort (デフォルト)(TXなど)、および基準となるマップで定義されている長いラベルを表示するlong (Texasなど)です。

スタイル属性(塗りつぶしの色、パターンまたは不透明度など)をマップの地理的リージョンにスタンプ・アウトするareaコンポーネントと、データ・ポイントと関連付けられた組込みまたはカスタムの形状をマップにスタンプ・アウトするmarkerコンポーネントの属性を指定することにより、基準となるマップ内のデフォルトのラベルをオーバーライドすることもできます。

エリアおよびマーカーのラベルをカスタマイズする手順:

1. 構造ウィンドウで、ラベルをカスタマイズするスタンプを表すdvt:areaコンポーネントまたはdvt:markerコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「その他」セクションを開いて次の属性を設定します。

- LabelDisplay: ドロップダウン・リストを使用して、「オン」を選択し、「value」属性に表示されるテキストを表示します。

- Value: 「LabelDisplay」が「オン」に設定されている場合に、エリアまたはマーカー・ラベル用に使用するテキストを入力します。

- LabelStyle: エリアまたはマーカーのラベル・フォント用に使用するフォント関連のCSSスタイルを入力します。

- LabelPosition: マーカー・ラベルにのみ使用可能です。ドロップダウン・リストを使用して、指定した値のラベルが表示されるマーカーに対する位置を選択します。有効な値は、「中央揃え」 (デフォルト)、「上詰め」および「下詰め」です。

注意:

マーカーがリージョンにareaDataLayerのpointLocationに対する子コンポーネントとして表示され、そのマーカーにラベルがある場合、基準となるマップのリージョンに関連付けられているラベルは表示されません。

- ShortDesc: エリアまたはマーカー・スタンプ用に使用する短い説明を入力します。この値は、ユーザーがカーソルをエリアまたはマーカーの上へ移動したときに表示されるツールチップに使用されます。詳細は、28.7.2項「データを表示するツールチップの構成方法」

28.7.2 データを表示するツールチップの構成方法

デフォルトでは、ユーザーがマップ上でカーソルを移動すると、テーマ・マップにマップ・レイヤー・ラベルを使用してツールチップが自動的に表示されます。データが使用可能な場合、areaまたはmarkerコンポーネント・スタンプの値にラベルが連結されます。使用可能なデータのみを表示するように、ツールチップを構成することもできます。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

データを表示するツールチップを構成する手順:

1. 構造ウィンドウでdvt:thematicMapコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。TooltipDisplay属性には、エリアまたはマーカー・スタンプの値に連結されたラベルを表示する場合は「auto」を、値のみを表示する場合は「shortDesc」を選択します。

3. 構造ウィンドウで、ツールチップにデータを表示するスタンプを表すdvt:areaコンポーネントまたはdvt:markerコンポーネントを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、「その他」セクションを開きます。「ShortDesc」属性には、ツールチップで表示する値を入力します。たとえば、エリア・コンポーネントのvalue属性が#{row.data}の場合、同じ値をshortDesc属性に使用します。

28.7.3 エリアおよびマーカー・ラベルでの数値データ値の書式設定方法

テーマ・マップのareaおよびmarkerコンポーネントでは、ラベルに数値データ値(ドル値またはパーセンテージなど)を表示できます。エリアおよびマーカー・ラベルは、コンポーネントのvalue属性で指定されます。数値データ値の書式は、標準のADFコンバータaf:convertNumberをエリアまたはマーカー・コンポーネントの子として追加するか、コンバータをEL式によりコンポーネント上で直接指定することで設定できます。コンバータと子af:convertNumberタグの両方が指定されている場合、子タグのプロパティが優先されます。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

テーマ・マップでエリアまたはマーカー・ラベルがすでに構成されている必要があります。ない場合は、この章の指示に従ってエリアまたはマーカー・ラベルをカスタマイズします。詳細は、28.7.1項「テーマ・マップ・ラベルのカスタマイズ方法」を参照してください。

エリアまたはマーカー・ラベルで数値データ値の書式を設定する手順:

1. 構造ウィンドウで、書式を設定するスタンプを表すdvt:areaまたはdvt:markerコンポーネントを右クリックし、「エリアの中に挿入」または「マーカーの中に挿入」→「数値の変換」を選択します。

2. 「プロパティ」ウィンドウで、af:convertNumberコンポーネントの属性の値を指定して、通知の書式設定を行います。ヘルプ・ボタンを使用して、af:convertNumberコンポーネントの完全なタグ・ドキュメントを表示します。

例28-8に、エリアおよびマーカー・ラベルの数値データ値の書式を設定するためのサンプル・コードを示します。

例28-8 エリアおよびマーカー数値データ値の書式設定用のサンプル・コード

...
<dvt:area id="a2" labelDisplay="on" value="#{mapBean.value}" >
<af:convertNumber id="cn1" type="currency"/>
</dvt:area>
<dvt:marker id="m2" labelDisplay="on" value="#{mapBean.value}" >
<af:convertNumber id="cn1" type="currency"/>
</dvt:marker>
...

または、EL式によりエリアまたはマーカー・コンポーネントに直接コンバータを指定します。次に例を示します。

<dvt:marker id="m1" labelDisplay="on" value="#{mapBean.value}"
converter="#{mapBean.myConverter}"/>

28.8 インタラクティブ機能のテーマ・マップへの追加

テーマ・マップでは、選択およびアクションイベント、ドリル、ポップアップ、アニメーションおよびドラッグ・アンド・ドロップ操作などの相互作用機能がサポートされています。

28.8.1 テーマ・マップで選択およびアクション・イベントを構成する方法

ユーザーが複数のデータ・レイヤーにわたり1つ以上のエリアまたはマーカーを選択できるように、テーマ・マップ・コンポーネントを構成することができます。デフォルトでは、選択は無効です。

areaDataLayerおよびpointDataLayerコンポーネントで選択を構成すると、1つ以上のエリアまたはマーカー・スタンプの選択ができるようになります。

選択を有効にすると、エリアまたはマーカー・スタンプを、出力テキストの表示や別のページへの移動などのカスタム・イベントを指定するためのアクション・リスナーで構成することができます。ADFアクション・イベントの詳細は、第6章「イベントの処理」を参照してください。

図28-30に、人のマーカーをクリックすると出力テキストが表示され、円形のマーカーをクリックすると別のJSFページに移動するように構成されたテーマ・マップを示します。

図28-30 テーマ・マップのアクション・イベント

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

テーマ・マップでデータを表示するために、エリアまたはマーカーを1つ持つデータ・レイヤーがすでに構成されている必要があります。

選択およびアクション・イベントを構成する手順:

1. 構造ウィンドウでdvt:areaDataLayerまたはdvt:pointDataLayerコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを展開します。「SelectionMode」属性には、エリアまたはマーカーの1回の選択を可能にする場合は「single」を、エリアまたはマーカーの複数の選択を可能にする場合は「multiple」を選択します。

3. 構造ウィンドウで、アクション・イベントを構成するスタンプを表すdvt:area componentコンポーネントまたはdvt:markerコンポーネントを右クリックし、「プロパティに移動」を選択します。

4. 「プロパティ」ウィンドウで、「動作」セクションを展開します。このセクションで、次の属性を設定します。

- Action: コンポーネントによって送信されるアクション・メソッド、またはアクションの静的な結果に対する参照を入力します。たとえば、mapActionなどです。

- ActionListener: アクション・リスナーに対するメソッド参照を入力します。たとえば、#{tmapEventBean.processClick}などです。

例25-9に、アクション・イベントを起動するようにマーカーを構成するためのサンプル・コードを示します。

例28-9 テーマ・マップのマーカー・アクション・イベントのサンプル・コード

<f:facet name="center">
<dvt:thematicMap id="thematicMap"
imageFormat="flash" basemap="usa"
inlineStyle="width:98%;height:95%;"
summary="Thematic map showing action events">
<dvt:areaLayer id="areaLayer" layer="states"
labelDisplay="off">
<dvt:areaDataLayer id="dataLayer"
contentDelivery="immediate"
value="#{tmapBean.colorModel}"
var="row"
varStatus="rowStatus"
selectionMode="single">
<dvt:areaLocation id="dataLoc"
name="#{row.name}">
<dvt:marker id="marker1"
shape="human" scaleX="3"
scaleY="3"
fillColor="#666699"
actionListener="#{tmapEventBean.processClick}"
rendered="#{row.category == 'category1'}"
shortDesc="Human shape"/>
<dvt:marker id="marker2"
shape="circle"
scaleX="2" scaleY="2"
fillColor="#006666"
action="mapAction"
rendered="#{row.category == 'category2'}"
shortDesc="Circle shape"/>
</dvt:areaLocation>
</dvt:areaDataLayer>
</dvt:areaLayer
</dvt:thematicMap>
</f:facet>
<f:facet name="end">
<af:outputText value="#{tmapEventBean.clickString}"
id="ot1"
partialTriggers="thematicMap:areaLayer:dataLayer:marker1"/>
</f:facet>

宣言的マスターディテール処理(テーマ・マップの関連データを表などのページ上の別のUIコンポーネントに表示するなど)のための選択リスナーを持つエリアまたはポイント・データ・レイヤーを構成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のマスター/ディテール関係の構成に関する必知事項に関する必知事項を参照してください。

28.8.2 テーマ・マップ・エリアおよびマーカーにポップアップを追加する方法

テーマ・マップのareaおよびmarkerコンポーネントは、情報を提供したり、エンド・ユーザーからの入力を要求したりするポップアップのダイアログ、ウィンドウおよびメニューが表示されるように構成できます。af:popupコンポーネントを他のADF Facesコンポーネントで使用すると、セカンダリ・ウィンドウでの情報の表示および非表示、追加データの入力、コンテキスト・メニューなどの機能の呼出しを、エンド・ユーザーに許可する機能を構成できます。

ADF Facesのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。af:showPopupBehaviorタグは宣言的ソリューションとなるため、popupコンポーネントを開くためのJavaScriptの作成や、スクリプトのpopupコンポーネントへの登録の必要がありません。これらのコンポーネントの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

たとえば、ダイアログまたはノート・ウィンドウで情報を表示するポップアップを、テーマ・マップのエリアまたはマーカーと関連付けることができます。図28-31には、選挙結果に関するデータのダイアログを表示するためにクリックされたテーマ・マップ・エリア(テキサス)と、特定の場所に関するデータのノート・ウィンドウを表示するマーカー(人)上にあるカーソルが示されています。

図28-31 エリア・ダイアログとマーカー・ノート・ウィンドウ

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

テーマ・マップのエリアまたはマーカー・コンポーネントで参照するポップアップ・コンポーネントを作成しておく必要があります。例28-10に、エリア・スタンプをクリックすると参照されるダイアログのサンプル・コードを示します。

例28-10 エリア・ダイアログ・ポップアップのサンプル・コード

<af:popup id="pop1" contentDelivery="lazyUncached" launcherVar="source"
eventContext="launcher">
<af:setPropertyListener from="#{tmapPopupBean.colorModel.rowData}"
to="#{tmapPopupBean.source}"
type="popupFetch"/>
<af:dialog id="nw1" modal="false" type="none"
title="Results - #{tmapPopupBean.source.fullName}">
<af:panelGroupLayout id="pgl6">
<af:panelGroupLayout id="pgl7" layout="horizontal"
halign="center">
<af:outputText value="Candidate 1" id="ot2"
inlineStyle="color:#{tmapPopupBean.strColor2};
font-size:medium;"/>
<af:spacer width="50" height="10" id="spacer1"/>
<af:outputText value="Candidate 2" id="ot1"
inlineStyle="color:#{tmapPopupBean.strColor1};
font-size:medium;"/>
</af:panelGroupLayout>
<af:panelGroupLayout id="pgl5" layout="horizontal"
halign="center">
<dvt:pieGraph id="graph1" subType="PIE"
inlineStyle="height:250.0px;width:250.0px"
tabularData="#{tmapPopupBean.graphData[tmapPopupBean.source]}"
imageFormat="PNG">
<dvt:background fillTransparent="true"/>
<dvt:graphPieFrame fillTransparent="true"/>
<dvt:seriesSet>
<dvt:series index="0" color="#{tmapPopupBean.color1}"/>
<dvt:series index="1" color="#{tmapPopupBean.color2}"/>
</dvt:seriesSet>
<dvt:sliceLabel rendered="true">
<dvt:graphFont id="graphFont1" size="14"/>
</dvt:sliceLabel>
<dvt:pieLabel rendered="false"/>
<dvt:legendArea rendered="false"/>
</dvt:pieGraph>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:dialog>
</af:popup>

例28-11に、ユーザーがマウスをマーカー・スタンプ上に移動すると参照されるノート・ウィンドウのサンプル・コードを示します。

例28-11 マーカー・ノート・ウィンドウのサンプル・コード

<af:popup id="pop2" contentDelivery="lazyUncached" launcherVar="source"
eventContext="launcher">
<af:setPropertyListener from="#{tmapPopupBean.pointModel.rowData}"
to="#{tmapPopupBean.noteSource}"
type="popupFetch"/>
<af:noteWindow id="nw2">
<af:panelGroupLayout id="pgl8" halign="center" layout="vertical">
<af:outputText value="Latitude: #{tmapPopupBean.noteSource.latitude}"
id="ot4"/>
<af:outputText value="Longitude: #{tmapPopupBean.noteSource.longitude}"
id="ot5"/>
</af:panelGroupLayout>
</af:noteWindow>
</af:popup>

ポップアップ・コンポーネントの詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

エリアまたはマーカーにポップアップを追加する手順:

1. 構造ウィンドウでdvt:areaまたはdvt:markerコンポーネントを右クリックし、「エリアの中に挿入」または「マーカーの中に挿入」→「ポップアップ表示動作」を選択します。

2. 「プロパティ」ウィンドウで次の属性を設定します。

- PopupId: エリアまたはマーカー・コンポーネントによって参照されるポップアップのIDを入力します。コロン1つで始まるIDは、コロンを除いた後、絶対値として扱われます。

- TriggerType: 表示されるポップアップをトリガーするイベント・タイプを入力します。テーマ・マップのエリアまたはマーカー・コンポーネントの有効な値は、action、clickおよびmouseHoverです。

- Align: ドロップダウン・リストから、ポップアップをどのようにエリアまたはマーカー・コンポーネントと位置合せするかを選択します。

- AlignID: ポップアップと関連付けられたエリアまたはマーカー・コンポーネントのIDを入力します。コロン1つで始まるIDは、コロンを除いた後、絶対値として扱われます。

例28-12に、ポップアップ・コンポーネントをテーマ・マップ内のエリアおよびマーカー・スタンプに追加するためのサンプル・コードを示します。

例28-12 エリアおよびマーカー・コンポーネントに関連付けられたポップアップ

<dvt:thematicMap id="thematicMap" imageFormat="flash
basemap="usa" summary="Thematic map showing voting data in US">
<dvt:legend label="Legend">
<dvt:showLegendGroup label="Voting Majority">
<dvt:legendSection source="areaLayer:dataLayer:area1"/>
</dvt:showLegendGroup>
<dvt:legendSection source="areaLayer:pointLayer:marker1"/>
</dvt:legend>
<dvt:areaLayer id="areaLayer" layer="states">
<dvt:areaDataLayer id="dataLayer" contentDelivery="immediate"
value="#{tmapPopupBean.colorModel}"
var="row" varStatus="rowStatus">
<dvt:areaLocation id="areaLoc" name="#{row.name}">
<dvt:area id="area1"
fillColor="#{row.value > 50 ? tmapPopupBean.color1 :
tmapPopupBean.color2}"
<f:attribute name="legendLabel" value="#{row.value > 50 ? 'Candidate 2' :
'Candidate 1'}" />
<af:showPopupBehavior triggerType="click"
popupId="::::pop1"
alignId="area1"
align="endAfter"/>
</dvt:area>
</dvt:areaLocation>
</dvt:areaDataLayer>
<dvt:pointDataLayer id="pointLayer"
value="#{tmapPopupBean.pointModel}" var="row"
varStatus="rowStatus"
contentDelivery="immediate">
<dvt:pointLocation id="pointLoc" type="pointXY"
pointX="#{row.longitude}"
pointY="#{row.latitude}">
<dvt:marker id="marker1" shape="human" fillColor="#FF9900"
scaleX="3" scaleY="3"
<f:attribute name="legendLabel" value="Location of Interest" />
<af:showPopupBehavior triggerType="mouseHover"
alignId="marker1"
popupId="::::pop2"
align="endAfter"/>
</dvt:marker>
</dvt:pointLocation>
</dvt:pointDataLayer>
</dvt:areaLayer>
</dvt:thematicMap>

28.8.3 アニメーション効果の構成方法

デフォルトでは、テーマ・マップは、マップに関連付けられたデータが変更されるときや、リージョンがマップでドリルされるときに、マップの初期レンダリング上でアニメーション化されます。各アニメーション・イベントのデフォルト設定はカスタマイズできます。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

テーマ・マップでアニメーション効果をカスタマイズする手順:

1. 構造ウィンドウでthematicMapコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- AnimationDuration: アニメーションの継続時間をミリ秒単位で入力します。デフォルト値は1000です。

- AnimationOnDisplay: ドロップダウン・リストを使用して、テーマ・マップの初期表示上のアニメーション効果を選択します。デフォルト値は「zoom」です。

- AnimationOnDrill: ドロップダウン・リストを使用して、マップ・レイヤーが下位レベルへドリルされるときのアニメーション効果を選択します。デフォルト値は「alphaFade」です。

- AnimationOnMapChange: ドロップダウン・リストを使用して、エリアまたはポイント・データ・レイヤーの値が変更されたとき、または基準となるマップが変更されたときのアニメーション効果を選択します。デフォルト値は指定なしです。

表28-2に、サポートされているマップ・イベントごとに使用可能なアニメーション効果を示します。

表28-2 テーマ・マップのアニメーション効果

アニメーション効果

AnimationOnDisplay

AnimationOnDrill

AnimationOnMapChange

none

x

x

x

alphaFade

x

x

x

conveyorFromLeft

x

x

conveyorFromRight

x

x

cubeToLeft

x

x

cubeToRight

x

x

flipLeft

x

x

flipRight

x

x

slideToLeft

x

x

slideToRight

x

x

transitionToLeft

x

x

transitionToRight

x

x

zoom

x

x

28.8.4 テーマ・マップ・コンポーネントにドラッグ・アンド・ドロップを追加する方法

ADF Facesフレームワークには、ページ上の場所から別の場所へアイテムをドラッグ・アンド・ドロップする機能があります。テーマ・マップでは、子af:dragSourceコンポーネントを追加し構成することにより、areaおよびmarkerコンポーネントをドラッグ元として、子af:dropTargetコンポーネントを追加し構成することにより、areaLayerコンポーネントをドラッグ・ターゲットとして使用することができます。たとえば、米国マップ内のある州の人口を表すエリアをドラッグし、それを表にドロップしてそのデータを表示することができます。

始める前に:

テーマ・マップの属性やテーマ・マップの子コンポーネントが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、28.6.1項「テーマ・マップの構成」を参照してください。

ページにすでにテーマ・マップが存在している必要があります。ない場合は、この章の指示に従ってテーマ・マップを作成します。詳細は、28.6.4項「ページにテーマ・マップを追加する方法」を参照してください。

エリアまたはマーカーをドラッグ元として使用する手順:

1. 構造ウィンドウで、ドラッグ元として構成するareaまたはmarkerコンポーネントを右クリックし、「エリアの中に挿入」または「マーカーの中に挿入」→「ドラッグ元」を選択します。

2. 「プロパティ」ウィンドウで、「actions」属性を指定します。

例28-13に、エリアをドラッグ元として追加し構成するためのサンプル・コードを示します。

例28-13 ドラッグ元としてのエリアのサンプル・コード

<dvt:area id="area" fillColor="#{tmapTargetActualBean.colorObj}"
shortDesc="#{tmapTargetActualBean.tooltip}">
<af:dragSource actions="COPY" discriminant="DnDDemoModel"/>
</dvt:area>

マップ・レイヤーをドラップ・ターゲットとして使用する手順:

1. 構造ウィンドウで、ドラッグ・ターゲットとして構成するareaLayerコンポーネントを右クリックし、「エリア・レイヤーの中に挿入」→「ドロップ・ターゲット」を選択します。

2. イベントを処理するマネージドBeanでメソッドとして評価されるdropListenerの式を入力します。

3. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

例28-14に、マップ・レイヤーをドロップ・ターゲットとして追加し構成するためのサンプル・コードを示します。

例28-14 ドロップ・ターゲットとしてのエリア・レイヤーのサンプル・コード

<dvt:areaLayer id="areaLayer" layer="states">
<af:dropTarget actions="COPY"
dropListener="#{TestDropHandler.handleCollectionFireDrop}">
<af:dataFlavor flavorClass="java.util.Collection"/>
</af:dropTarget>
</dvt:areaLayer>

ドラッグ・アンド・ドロップ機能の追加の詳細は、36.5項「コンポーネントのドラッグ・アンド・ドロップ機能の追加」を参照してください。

29 階層ビューア・コンポーネントの使用方法

この章では、ADFデータ視覚化のhierarchyViewerコンポーネントを使用し、簡単なUI優先開発を使用して、階層ビューアでデータを表示する方法について説明します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して階層ビューアを作成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 29.1項「階層ビューア・コンポーネントについて」

- 29.2項「階層ビューア・コンポーネントの使用方法」

- 29.3項「階層ビューアでのノードの管理」

- 29.4項「パネル・カードの使用」

- 29.5項「階層ビューアでのナビゲーションの構成」

- 29.6項「階層ビューアの外観のカスタマイズ」

- 29.7項「階層ビューア・コンポーネントへの対話性の追加」

- 29.8項「階層ビューアへの検索の追加」

29.1 階層ビューア・コンポーネントについて

階層ビューアは、階層データを表示するために使用されます。階層データにはデータ内にマスター/ディテール関係が含まれています。たとえば、組織内の従業員間の関係に関する情報が含まれるデータ・コレクションから、組織図をレンダリングする階層ビューアを作成することもできます。

階層ビューアでは、ノードと呼ばれる形状を使用して、階層内のデータを参照します。ノードの形状とコンテンツは、ノードの視覚的レイアウトと同様に構成可能です。ノードは、1つのパネル・カード内に複数のビューを表示できます。

29.1.1 階層ビューアのユースケースおよび例

階層ビューアは、階層データおよびマスター/ディテール関係を視覚的に表示します。図29-1に、コントロール・パネル、多数のノードおよびノードを接続するリンクを含む実行時の階層ビューア・コンポーネントのセグメントを示します。ノードにはaf:showDetailItem要素を使用して複数セットのデータを表示するパネル・カードが含まれます。

図29-1 コントロール・パネルとノードが表示された階層ビューア・コンポーネント

29.1.2 エンド・ユーザー機能およびプレゼンテーション機能

ADFデータ視覚化階層ビューア・コンポーネントには、パンやズーム、レイアウト・ビューの変更など、エンド・ユーザー用の一連の機能が用意されています。また、ノード形状、線、ラベルの変更などの一連のプレゼンテーション機能も備わっています。

29.1.2.1 レイアウト

コンポーネントをページに挿入する際、データ・コレクションを階層ビューア・コンポーネントにバインドする場合はデータ・コントロールから、コンポーネントを挿入し後からデータにバインドする場合は「コンポーネント」ウィンドウから、階層ビューアの初期レイアウトを定義できます。階層ビューア内のノードのレイアウトは構成可能で、レイアウトには次のタイプがあります。

- 上から下の垂直方向
図29-2に、上から下の垂直方向レイアウトの例を示します。

図29-2 階層ビューアの上から下の垂直方向レイアウト

- 下から上の垂直方向

- 左から右の水平方向
図29-3に、左から右の水平方向レイアウトの例を示します。

図29-3 階層ビューアの左から右の水平方向レイアウト

- 右から左の水平方向

- ロケールによって方向が決まる水平方向

- ツリー、インデントされたツリー
図29-4に、ツリー・レイアウトの例を示します。

図29-4 階層ビューアのツリー・レイアウト

- ルート・ノードが中央に配置され、後続の子レベルがそれぞれの親ノードから外側に向かって広がる放射状

- ルート・ノードが中央に配置され、すべてのリーフ・ノードが同心円に配置され、親ノードは円の内側に配置される円形
図29-5に、円形レイアウトの例を示します。

図29-5 階層ビューアの円形レイアウト

29.1.2.2 ナビゲーション

実行時に、ノードにはユーザーにノード間のナビゲートを可能にし、デフォルトで他のノードを表示または非表示にできるコントロールが含まれます。

実行時に、エンド・ユーザーはパネル・カードが参照するコンテンツを動的に切り替えるノードのコントロールを使用します。

実行時に、ユーザーがsetAnchorListenerプロパティに指定された値を持つ別のノードをダブルクリックすると、そのノードがアンカー・ノードになります。

実行時に、ユーザーがマウスを76%未満のズーム・レベルでノードに移動すると、100%のズーム・レベルでノードのコンテンツを表示するホバー・ウィンドウが自動的に表示され、ユーザーはズーム・レベルに関係なく、すべての情報を見ることができます。ホバー・ウィンドウ上のコントロールはアクティブです。

29.1.2.3 ティルト・パン

有効な場合、大量のノードがある階層ビューアを一度に1ページ目を通すかわりに、ユーザーはティルト・パン効果を開始して、階層ビューアをアニメーション化することで、階層ビューアのノードからノードへと飛んでいくように見ることができます。ビューの端に向かう動きに設定すると、効果は端にある最後のノードに到達するまで自動的に継続します。図29-6に、ビューの端に到達したティルト・パン効果を示します。

図29-6 階層ビューアのティルト・パン効果

ティルト・パン効果を使用するには、まずノードのコンテンツのビューが満足できるものになるように、階層ビューでのズーム・レベルを調整する必要があります。次のどの方法でも、効果を開始できます。

- コントロール・パネルでパン・コントロールを使用するときにクリック・アンド・ドラッグして、短期間の通常パンの後にティルト・パンを開始します。

- ビューをビューポートの幅の3分の1までクリック・アンド・ドラッグします。

- ビューの端の近くでカーソルをクリック・アンド・ホールドして、その方向へのティルト・パンを開始します。

ティルト・パン効果が開始されると、ビュー内でマウスを移動させて、ビューでのパンの方向を変更できます。ティルト・パンを終了するには、マウス・ボタンを離します。

29.1.2.4 コントロール・パネル

階層ビューアのコントロール・パネルには、ユーザーが実行時に階層ビューア・コンポーネントの位置および外観を操作するためのツールがあります。デフォルトで、図29-7に示すとおり、階層ビューア・コンポーネントの左上隅に非表示状態で表示されます。

図29-7 非表示状態のコントロール・パネル

ユーザーは、図29-7に示すコントロール・パネルの非表示/表示ボタンをクリックして、コントロール・パネルを非表示にするか、展開します。図29-8に、展開されたコントロール・パネルを示します。

図29-8 表示状態のコントロール・パネル

表29-1では、コントロール・パネルのコントロールでユーザーに提供される機能を説明します。階層ビューア・コンポーネントに追加データを表示するaf:showDetailItem要素を持つパネル・カードが含まれている場合、パネル・セレクタは自動的に有効になります。階層ビューア・コンポーネントで次のいずれかのレイアウトが使用されていると、レイアウト・セレクタが自動的に表示されます。

- 上から下の垂直方向

- 左から右の水平方向

- ツリー

- 放射

- 円

表29-1 コントロール・パネルの要素

コントロール

名前

説明

パン制御

ユーザーはビューポート内の階層ビューア・コンポーネントを再配置できます。

ズームしてあわせる

ユーザーはビューポート内にすべてのノードが表示されるように、階層ビューア・コンポーネントにズームできます。

ズーム制御

ユーザーは、階層ビューア・コンポーネントにズームできます。

非表示/表示

コントロール・パネルを表示または非表示にします。

パネル・セレクタ

パネル・カードを構成した場合は、定義したaf:showDetailItem要素のリストを表示します。ユーザーはパネル・セレクタを使用して、すべてのノードを同じパネルに一度に表示できます。

レイアウト・セレクタ

レイアウトの選択を可能にします。ユーザーは、階層ビューア・コンポーネントのレイアウトを定義したレイアウトからコンポーネントによって提示される別のレイアウト・オプションの1つに変更できます。

29.1.2.5 印刷

階層ビューアは、ブラウザのHTMLビューを使用して印刷されます。

29.1.2.6 双方向サポート

階層ビューアでは、ノード・コンテンツでの双方向テキスト、検索パネルおよび検索結果の表示がサポートされています。双方向テキストとは、右から左(RTL)と左から右(LTR)の両方の方向性のテキストを含むテキストです。一般に、アラビア語やヘブライ語などの異なるタイプのアルファベットのテキストが含まれます。

階層ビューアでは、1つのノード・ビューから次のノード・ビューへパネル・カードをめくったり、コントロール・パネルや検索パネルの要素が定義されている場合はそれらの位置を切り替えるのにも双方向が提供されています。

29.1.2.7 状態の管理

階層ビューアは、ノードの選択、展開、横方向移動などのユーザー・アクションに関する状態管理をサポートします。ユーザーがノードを選択または展開したり、同じ親内で左または右に移動して、次のノード・セットを表示する場合、タブ付パネルのように、移動後にページに戻ると、その状態は維持されます。状態管理は、disclosedRowKeys、selectedRowKeys、layoutなどの階層ビューア属性でサポートされます。

29.1.3 階層ビューア・コンポーネントの追加機能

階層ビューア・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったん階層ビューア・コンポーネントをページ追加すると、検証やアクセシビリティなどの機能を追加する必要があることに気付く場合があります。階層ビューア・コンポーネントで使用できるその他の機能へのリンクは、次のとおりです。

- 部分ページ・レンダリング: 他のコンポーネントで実行されたアクションに基づく新しいデータをページ上に表示するために、階層ビューアをリフレッシュできます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: ユーザーは実行時の階層ビューアの表示方法を変更できます。アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- アクセシビリティ: 階層ビューア・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- コンテンツ配信: 階層ビューアを、contentDelivery属性を使用して、データ・ソースから特定の行数を一度にフェッチするように構成できます。詳細は、12.2.2項「コンテンツの配信」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックが使用されている場合、ADFビジネス・コンポーネントの構成に基づいて、自動的にバインドされた階層ビューアを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「プレースホルダ・データ・コントロールを使用したページの設計」の章を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、イメージ形式、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

29.2 階層ビューア・コンポーネントの使用方法

階層ビューア・コンポーネントには、1つ以上のディテール・コレクションと1つのマスター・ディテール・コレクションとの間にマスター/ディテール関係が存在するデータ・コレクションが必要です。階層ビューア・コンポーネントでは、ADF Faces treeコンポーネントと同じデータ・モデルが使用されます。データ・コレクションをまずADF Faces treeコンポーネントにバインドすることによって、データ・コレクションを階層ビューア・コンポーネントにバインドできるかどうかテストできます。ADF Faces treeコンポーネントを使用してデータ・コレクションをナビゲートできれば、階層ビューア・コンポーネントにバインドすることができます。

JSFページに階層ビューア・コンポーネントを追加すると、JDeveloperによりJSFページのページ定義ファイルにツリー・バインディングが追加されます。ツリー・バインディングを使用したマスター/ディテール・データの表示の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のツリーを使用したマスター/ディテール・オブジェクトの表示に関する項を参照してください。

ユーザーが階層ビューア・コンポーネントのルート・ノードから下方向にナビゲートできるようにするには、階層ビューア・コンポーネントでノードにバインドするデータ・コレクションに再帰的アクセッサが含まれている必要があります。階層ビューア・コンポーネントのナビゲーションの詳細は、29.5項「階層ビューアでのナビゲーションの構成」を参照してください。

29.2.1 階層ビューア・コンポーネントの構成

JDeveloperでは、「コンポーネント」ウィンドウからJSFページにコンポーネントをドラッグ・アンド・ドロップする場合、または『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップ、およびサブバースト・コンポーネントの作成」の章での説明のとおり、「階層ビューアの作成」ダイアログを使用して階層ビューア・コンポーネントを作成する場合、JSFページに次の要素が生成されます。

- 階層ビューア(hierarchyViewer): ノードおよびリンク要素をラップします。

- ノード(node): ノードは階層のデータを参照する形状です(たとえば、組織の従業員またはネットワークのコンピュータ)。表示するデータを参照するnode要素の子要素を構成します。node要素は、様々なズーム・レベル(100%、75%、50%および25%)でコンテンツを表示する1つ以上のf:facet要素の使用をサポートします。f:facet要素は、ADFデータ視覚化panelCardコンポーネントに加えてaf:outputText、af:imageおよびaf:panelGroupLayoutなどの多数のADF Facesコンポーネントの使用をサポートします。
実行時に、ノードにはユーザーにノード間のナビゲートを可能にし、デフォルトで他のノードを表示または非表示にできるコントロールが含まれます。ノード・コンテンツの指定とズーム・レベルの定義の詳細は、29.3.1項「ノード・コンテンツの指定方法」を参照してください。

- リンク(link): 1つのノードを別のノードに接続するlink要素の属性の値を設定します。リンクの外観のカスタマイズ方法およびラベルの追加方法の詳細は、29.6.4項「リンクおよびラベルの表示の構成方法」を参照してください。

- パネル・カード(panelCard): ノード要素によって参照される複数セットのコンテンツを、たとえばコンテンツを水平にスライドしたり、ノードを反転したりするなど、アニメーションを使用して、動的に切り替える方法を提供します。
ズーム・レベルごとのf:facetタグでは、コンテンツが指定したズーム・レベルで表示されるように定義する1つ以上のaf:showDetailItem要素を含むdvt:panelCard要素をサポートします。実行時に、エンド・ユーザーはaf:showDetailItem要素が参照するコンテンツを動的に切り替えるノードのコントロールを使用します。詳細は、29.4項「パネル・カードの使用方法」を参照してください。

注意:

他の要素とは異なり、dvt:panelCard要素は、「コンポーネント」ウィンドウを使用して階層ビューアを作成するときにデフォルトのクイック・レイアウト・オプションを選択すると生成されません。

29.2.2 ページへの階層ビューアの追加方法

JSFページに階層ビューアを追加するには、「コンポーネント」ウィンドウを使用します。ページに階層ビューア・コンポーネントをドラッグ・アンド・ドロップすると、「階層ビューアの作成」ダイアログがコンポーネント・ギャラリに使用可能な階層ビューア・レイアウトのカテゴリを説明とともに表示し、階層ビューアの作成時に視覚的に支援します。図29-9に、上から下の垂直方向レイアウト・タイプが選択された階層ビューアの「階層ビューアの作成」ダイアログを示します。

図29-9 「階層ビューアの作成」ダイアログ

階層ビューア・レイアウトを選択して、ページに階層ビューアが追加されると、「プロパティ」ウィンドウを使用して、データ値を指定し、階層ビューアに追加の表示属性を構成できます。または、作成中にデータのバインドを選択し、「プロパティ」ウィンドウを使用して追加の表示属性を構成できます。

「プロパティ」ウィンドウで、プロパティ・フィールドにマウス・カーソルを合わせると表示されるアイコンをクリックすることで、プロパティの説明や編集オプションを表示できます。図29-10に、階層ビューア・コンポーネントのValue属性のドロップダウン・メニューを示します。

図29-10 階層ビューアのValue属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用して階層ビューアを作成でき、バインドが行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

始める前に:

階層ビューアの属性や階層の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページに階層ビューアを追加する手順:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「階層ビューア」パネルから「階層ビューア」をページにドラッグ・アンド・ドロップし、「階層ビューアの作成」ダイアログを開きます。
ダイアログを使用して、階層ビューアのレイアウト・タイプを選択します。ダイアログのヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

2. 「階層ビューアの作成」ダイアログで、「OK」をクリックして階層ビューアをページに追加します。
オプションで、そのダイアログを使用して「データを今すぐバインド」を選択し、ツリーマップに表示するデータを表すADFデータ・コントロールをナビゲートして、階層ビューアをバインドします。このオプションを選択すると、ダイアログのデータ・バインディングのフィールドが編集のために使用可能になります。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 「プロパティ」ウィンドウに、階層ビューアの属性を表示します。ヘルプ・ボタンを使用して、hierarchyViewerコンポーネントの完全なタグ・ドキュメントを表示します。

4. 「共通」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Layout:階層ビューアの階層のレイアウトを指定します。有効な値の説明と図は、29.1.2.1項「レイアウト」を参照してください。

- 祖先のレベル (サブメニューの表示): 初期レンダリングで表示する祖先レベルの数を指定するdisplayLevelsAncestor属性の設定に使用します。このプロパティはゼロから始まります。値0は、ルートの上の祖先レベルが表示されないことを意味します。デフォルト値は0です。

- 子孫のレベル (サブメニューの表示): 初期レンダリングで表示する子孫レベルの数を指定するdisplayLevelsChildren属性の設定に使用します。このプロパティはゼロから始まります。値0は、ルートの下の子レベルが表示されず、ルート自体は表示されることを意味します。デフォルト値は1で、ルートおよび子の最初のレベルが表示されることを意味します。

注意:

disclosedRowKeys属性を使用して、初期のレンダリングの間に表示する子レベルの数を指定することもできます。disclosedRowKeysとdisplayLevelsChildrenの属性を両方指定すると、disclosedRowKeys属性がdisplayLevelsChildrenよりも優先されます。

- レベル当たりのノード (サブメニューを表示): 展開された親ノードごとに一度にフェッチされ、表示される子ノードの数を指定するlevelFetchSize属性の設定に使用します。階層ビューアに表示される横方向のナビゲーション・コントロールを使用すれば、追加の子ノードをフェッチし、表示できます。デフォルト値は25です。

5. 「階層ビューア・データ」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Value: 階層ビューアのデータ・モデルを指定し、javax.faces.TreeModelのインスタンスにすることができます。

- Var: 階層ビューア・データ・コレクションの各要素の参照に使用される変数を指定します。このコンポーネントのレンダリングが完了すると、この変数は削除されるか、その前の値に戻ります。

6. 「外観」セクションを開きます。このセクションを使用して、次の属性を設定します。

- Summary:階層ビューアの説明を入力します。この説明は、スクリーン・リーダーのユーザーがアクセスします。

- EmptyText:階層ビューアにデータが表示されない場合に表示するテキストを指定します。

7. 「動作」セクションを開きます。このセクションを使用して、次の属性を設定します。

- ControlPanelBehavior:コントロール・パネルの動作を指定します。詳細は、29.6.3項「コントロール・パネルの表示の構成方法」を参照してください。

- Panning: パンの動作を指定します。デフォルト値は、クリック・アンド・ドラッグ・パンに対するdefaultです。自動3Dティルト・パンが有効なクリック・アンド・ドラッグ・パンのティルト値も指定できます。

29.2.3 ページに階層ビューアを追加する場合の処理

「階層ビューアの作成」ダイアログを使用して階層ビューア・コンポーネントをJSFページに挿入すると、階層ビューアのカスタマイズをサポートする子タグのセットが自動的に挿入されます。

階層ビューア・コンポーネントでは、af:panelGroupLayout、af:spacerおよびaf:separatorなどの要素を使用して、ノードでコンテンツをどのように表示するかを定義します。例29-1に、「コンポーネント」ウィンドウから挿入してコンポーネントを作成する場合に生成されるコードを示します。例では、階層ビューアの要素関連のコードが強調表示されています。

例29-1 階層ビューアのサンプル・コード

<dvt:hierarchyViewer id="hv1" layout="hier_vert_top" styleClass="AFStretchWidth">
<dvt:link linkType="orthogonalRounded" id="l1"/>
<dvt:node width="233" height="330" id="n1">
<f:facet name="zoom100">
<af:panelGroupLayout layout="vertical"
styleClass="AFStretchWidth AFHVNodeStretchHeight AFHVNodePadding"
id="pgl1">
<af:panelGroupLayout layout="horizontal" id="pgl2">
<af:panelGroupLayout styleClass="AFHVNodeImageSize" id="pgl3">
<af:image source="#{null}" styleClass="AFHVNodeImageSize" id="i1"/>
</af:panelGroupLayout>
<af:spacer width="5" height="5" id="s1"/>
<af:panelGroupLayout layout="vertical" id="pgl4">
<af:outputText value=" attribute value1
styleClass="AFHVNodeTitleTextStyle" id="ot1"/>
<af:outputText value=" attribute value2"
styleClass="AFHVNodeSubtitleTextStyle" id="ot2"/>
<af:outputText value=" attribute value3"
styleClass="AFHVNodeTextStyle" id="ot3"/>
</af:panelGroupLayout>
</af:panelGroupLayout>
<af:spacer height="5" id="s2"/>
<af:separator id="s3"/>
<af:spacer height="5" id="s4"/>
<dvt:panelCard effect="slide_horz" styleClass="AFHVNodePadding" id="pc1">
<af:showDetailItem text="first group title " id="sdi1">
<af:panelFormLayout styleClass="AFStretchWidth AFHVNodeStretchHeight AFHVNodePadding"
id="pfl1">
<af:panelLabelAndMessage label="attribute label4"
styleClass="AFHVPanelCardLabelStyle" id="plam1">
<af:outputText value="attribute value4"
styleClass="AFHVPanelCardTextStyle" id="ot4"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label5"
styleClass="AFHVPanelCardLabelStyle" id="plam2">
<af:outputText value="attribute value5"
styleClass="AFHVPanelCardTextStyle" id="ot5"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label6"
styleClass="AFHVPanelCardLabelStyle" id="plam3">
<af:outputText value="attribute value6"
styleClass="AFHVPanelCardTextStyle" id="ot6"/>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:showDetailItem>
<af:showDetailItem text="second group title " id="sdi2">
<af:panelFormLayout styleClass="AFStretchWidth AFHVNodeStretchHeight AFHVNodePadding"
id="pfl2">
<af:panelLabelAndMessage label="attribute label7"
styleClass="AFHVPanelCardLabelStyle" id="plam4">
<af:outputText value="attribute value7"
styleClass="AFHVPanelCardTextStyle" id="ot7"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label8"
styleClass="AFHVPanelCardLabelStyle" id="plam5">
<af:outputText value="attribute value8"
styleClass="AFHVPanelCardTextStyle" id="ot8"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label9"
styleClass="AFHVPanelCardLabelStyle" id="plam6">
<af:outputText value="attribute value9"
styleClass="AFHVPanelCardTextStyle" id="ot9"/>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:showDetailItem>
</dvt:panelCard>
</af:panelGroupLayout>
</f:facet>
</dvt:node>
</dvt:hierarchyViewer>

29.2.4 階層ビューアのレンダリングとHTMLに関する必知事項

デフォルトでは、階層ビューア・コンポーネントのレンダリングはFlash Playerで行われます。Flash 10以上がクライアントで使用できない場合や印刷が目的の場合、階層ビューアはHTMLでレンダリングされます。HTMLレンダリングはFlashレンダリングにできるだけ似るように行われますが、多少違いがあります。通例、階層ビューアの表示および機能は、次の例外を除いてサポートされます。

- 分離ノードおよびリストア・ノードは使用できません。

- ノードの形状は長方形に制限されます。

- リンクの場合、リンクの終点コネクタはサポートされません。リンク・タイプは直交に制限され、リンク・スタイルは実線に制限されます。

- コントロール・パネルの場合、パネル・カードはすべて切り替えることができません。パンはスクロール・バーに制限され、ズームおよびズーム・フィットは4つのズーム・ファセットに制限されます。

- 検索はサポートされません。

- メール可能なページはサポートされません。

- ノードの詳細を示すホバー・ウィンドウはサポートされません。

29.3 階層ビューアでのノードの管理

ノードは、実行時に階層ビューア・コンポーネントの個々の要素を示す形状です。階層ビューア・コンポーネントの個々の要素の例には、組織図の従業員またはネットワーク・ダイアグラムのコンピュータが含まれます。デフォルトで、階層ビューア・コンポーネントの各ノードには、ユーザーが次のことを実行できるコントロールが含まれています。

- 階層ビューア・コンポーネントの他のノードへのナビゲート。
各ノードの上部には、1つのボタン(「分離」または「リストア」)が含まれています。「分離」ボタンを使用すると、選択したノードと表示されている子への階層を一時的に減らすことができます。「リストア」をクリックすると階層が元の表示に戻ります。

- 階層ビューア・コンポーネントで現在選択されているノードの子ノードの表示または非表示。
各ノードの下部に、表示/非表示ボタンが表示されます。これらのアイコンの1つをクリックすると、ノードに子がある場合はそれが表示または非表示になり、コンポーネントはRowDisclosureEventイベントを生成します。このイベントに対応する処理を実行するには、 af:treeコンポーネントと同じ方法でカスタムのrowDisclosureListenerメソッドを登録します。詳細は、12.6.4項「プログラムを使用したノードの開閉に関する必知事項」を参照してください。

階層ビューア・コンポーネントで参照するノードの様々な情報セットを表示するためにパネル・カードを使用する場合、ノードの下部にあるコントロールにより、ユーザーはアクティブ・ノードで情報セットを変更できます。詳細は、29.4項「パネル・カードの使用方法」を参照してください。

図29-11に、エンド・ユーザーがアンカー・ノードとしてノードを分離し、子ノードを表示し、アクティブ・ノードで様々なセットの情報を表示するためにノードを変更することができるコントロール付きのノードの例を示します。ノードのコントロールの構成方法の詳細は、29.3.2項「ノードのコントロールの構成方法」を参照してください。

図29-11 階層ビューア・ノードのコントロール

29.3.1 ノード・コンテンツの指定方法

ノードには、ノードにナビゲートして、ノードを表示また非表示にできるコントロールがデフォルトで含まれますが、階層ビューア・コンポーネントを作成するときに、クイック・スタート・レイアウトを使用していないかぎり、デフォルトでノードにコンテンツは含まれません。実行時にノードによってレンダリングされるコンテンツを定義する必要があります。『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」の章で説明されているように、データ・バインディングと階層ビューア・コンポーネントを関連付けると、ノード・コンテンツを指定できます。マネージドBeanに格納されているコンテンツを指定することもできます。

デフォルトで、作成する階層ビューア・コンポーネントにはズーム・レベル100%のファセット要素を1つ持つノードが1つ作成されます。

<f:facet name="zoom100"/>

次のズーム・レベルを使用して、さらに3つのファセット要素のインスタンスを階層ビューア・コンポーネントに挿入できます。

- 25%: zoom25

- 50%: zoom50

- 75%: zoom75

これらのズーム・レベル定義を使用して、階層ビューアがズーム・アウトされてより多くのノードが表示され、各ノードで使用可能な表示スペースが少ない場合に、ノード・コンテンツの読みやすさを改善します。1つ以上のファセット要素内で使用可能なデータ・コレクションのサブセットを定義できます。たとえば、名前、場所および番号など、会社の部署に関するデータを参照するノード属性を持つデータ・コレクションがある場合、部署の名前と番号のノード属性を参照する、ズーム・レベル50%のファセット要素を指定できます。

実行時に、ユーザーがマウスを76%未満の任意のズーム・レベルでノードに移動すると、100%のズーム・レベルでノードのコンテンツを表示するホバー・ウィンドウが自動的に表示され、ユーザーはズーム・レベルに関係なく、すべての情報を見ることができます。ホバー・ウィンドウ上のコントロールはアクティブです。

挿入する各ファセット要素は、他のコンポーネントの参照に使用できます。次のADF Facesコンポーネントから1つ以上を使用して、階層ビューア・コンポーネントのノードにコンテンツを定義できます。ノード・コンポーネント・ファセットでは、次のコンポーネントをサポートしています。

- レイアウト・コンポーネントには、af:panelFormLayout、af:panelGroupLayout、af:separator、af:showDetailItemおよびaf:spacerがあります。これらのコンポーネントの使用方法の詳細は、第9章「Webページ上のコンテンツの編成」を参照してださい。

- メニュー・コンポーネントには、af:menuとaf:menuItemがあります。これらのコンポーネントの詳細は、第16章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

- 出力コンポーネントには、af:outputFormattedとaf:outputTextがあります。これらのコンポーネントの詳細は、第18章「出力コンポーネントの使用」を参照してください。

- メッセージ・コンポーネントaf:panelLabelAndMessage。このコンポーネントの詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- ナビゲーション・コンポーネントaf:button、af:linkおよびaf:commandMenuItem。これらのコンポーネントの詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

- イメージ・コンポーネントaf:image。af:imageコンポーネントの使用方法の詳細は、29.6.2項「階層ビューアにイメージを含める方法」を参照してください。

- af:showPopupBehavior:。af:showPopupBehaviorコンポーネントの使用方法の詳細は、29.7.2項「ポップアップ・ウィンドウを起動するための階層ビューアの構成」を参照してください。

- 階層ビューア子コンポーネントdvt:panelCard: dvt:panelCardコンポーネントの使用方法の詳細は、29.4項「パネル・カードの使用方法」を参照してください。

注意:

サポートされていないコンポーネントには、設計時にフラグが付けられています。

デフォルトでは、階層ビューア・コンポーネントのレンダリングはFlash Playerで行われ、印刷目的ではHTMLで行われます。このため、ノード・コンテンツとして指定したADF Facesコンポーネントの一部のプロパティがサポートできないことから、コンポーネントは予想どおりにはレンダリングされません。詳細は、29.2.4項「階層ビューアのレンダリングとHTMLに関する必知事項」を参照してください。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューア・コンポーネントにノードを追加する手順:

1. 構造ウィンドウで、dvt:hierarchyViewerコンポーネントを右クリックし、「階層ビューアの中に挿入」→「ノード」を選択します。
次のエントリがJSFページに表示されます。

<dvt:node>
<f:facet name="zoom100"/>
</dvt:node>

2. 構造ウィンドウでdvt:nodeノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、適切なプロパティを構成します。
たとえば、ノード・コンポーネントをアクセッサと関連付けるには、Typeプロパティの値を設定します。model.HvtestViewをノードに関連付けると、JSFページに次のコードが表示されます。

<dvt:node type="model.HvtestView"/>

詳細は、29.3.3項「アクセッサのノード定義の指定」を参照してください。

29.3.2 ノードのコントロールの構成方法

ノード・コンポーネント(node)では、リストア、分離、表示または非表示などのコントロールを実行時に表示するかどうかを決定できる多くのプロパティが公開されます。実行時のノードのサイズと形状を決定するプロパティも公開されます。

始める前に:

階層ビューアの属性や階層の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューア・ノードがあるはずです。ない場合は、この章の指示に従って階層ビューアにノードを追加します。詳細は、第29.3.1項「ノード・コンテンツの指定方法」を参照してください。

ノードにコントロールを構成する手順:

1. 構造ウィンドウでdvt:nodeノードを右クリックし、「プロパティに移動」を選択します。

2. 表29-2に説明されているとおり、「プロパティ」ウィンドウの「外観」セクションでノードのプロパティを構成します。

表29-2 ノード構成プロパティ

これを行うには:

プロパティに設定する値:

表示または非表示コントロールをノードに表示するかしないかを構成します。

showExpandChildrenをFalseに設定して、コントロールを非表示にします。デフォルトでは、このプロパティはTrueに設定されています。

リストアまたは分離コントロールをノードに表示するかしないかを構成します。

showIsolateプロパティをFalseに設定してノード上のこれらのコントロールを非表示にします。デフォルトでは、このプロパティはtrueに設定されています。

「上へナビゲート」コントロールをノードに表示するかどうかを構成します。

showNavigateUpプロパティをFalseに設定してノード上のこのコントロールを非表示にします。デフォルトでは、このプロパティはtrueに設定されています。

showNavigateUpプロパティをtrueに設定した場合は、コントロールをレンダリングするには29.5.1項「階層ビューアでの上方向へのナビゲーションの構成方法」での説明のとおり、階層ビューア・コンポーネントのnavigateUpListenerプロパティにも値を設定する必要があります。

ノードの高さと幅を構成します。

widthプロパティおよびheightプロパティの値を設定します。

ノードの形状を選択します。

「図形」ドロップダウン・リストから値を選択します。使用可能な値は次のとおりです。

- ellipse

- rect

- roundedRect (デフォルト)

3. 「プロパティ」ウィンドウの「スタイル」セクションのプロパティの構成の詳細は、31.2項「コンポーネントのスタイル・プロパティの変更」を参照してください。

ホバー・ディテール・ウィンドウは、ズーム・レベルが76%未満のときにノード上をカーソルが移動すると自動的に表示され、そのノードに設定されるshape属性が反映されます。たとえば、shape属性がroundedRectのノードでは、図29-12に示したものと同じ属性のホバー・ウィンドウが表示されます。

76-100%のズーム・レベルでないノードをホバーしているとき、ディテール・ウィンドウの表示を無効化できます。詳細は、29.6.5項「ホバー・ディテール・ウィンドウの無効化の方法」を参照してください。

図29-12 階層ビューア・ノードでのホバー・ウィンドウ

29.3.3 アクセッサのノード定義の指定

デフォルトで、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューアの作成」の章での説明のとおり、「階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」ダイアログを使用して、階層ビューア・コンポーネントを作成する場合は、ノード・コンポーネントをアクセッサと関連付けます。「階層ビューアの作成」ダイアログでは、ノード・コンポーネントのtypeプロパティが特定のアクセッサに設定されます。

ノード・コンポーネントのtypeプロパティを構成して、指定された1つ以上のアクセッサを使用できます。あるいは、29.3.4項「ノード定義と特定のデータ行のセットとの関連付け」での説明のとおり、アクセッサ間でノード定義を使用するようにノード・コンポーネントのrenderedプロパティを構成できます。階層ビューア・コンポーネントで特定のデータ行にどのノード定義を使用するかを決定する場合、最初にtypeプロパティの一致があるかどうかを確認します。

- typeプロパティが一致し、renderedプロパティ値がtrue (デフォルト)の場合、階層ビューア・コンポーネントでは、ノード定義を使用します。

- typeプロパティが一致しない場合、階層ビューア・コンポーネントでは、ノード定義のrenderedプロパティの値がtrueと評価されるノードのうち最初のものを使用します。renderedプロパティの評価の結果は、typeには影響しません。

29.3.4 ノード定義と特定のデータ行のセットとの関連付け

ノード・コンポーネントのrenderedプロパティを使用して、ノードを特定のデータ行のセットまたは単一データ行と関連付けることができます。renderedプロパティでは、ブール値を使用して、trueまたはfalseに評価してノード定義に関連付けるデータ行を決定するEL式を記述できます。たとえば、肩書に基づくデータをノードに表示するとします。ノード・コンポーネントのrenderedプロパティに対して、肩書が指定した値(この例ではCEO)と一致する場合にtrueと評価する次の疑似EL式のようなEL式を記述します。

rendered="#{node.title == 'CEO'}"

ノード・コンポーネントのrenderedプロパティをこのように使用する場合は、そのノード・コンポーネントのtypeプロパティの値は定義しません。

注意:

階層ビューアでは、renderedプロパティがtrueと評価されるノードのうち最初のものを使用します。階層ビューアのノード定義の順序は重要です。

29.3.5 アンカー・ノードの祖先レベルの指定方法

階層ビューア・コンポーネントのアンカー・ノードは、ツリー・バインディングによって返される階層のルートです。ユースケースによって、ルート・ノードを複数にすることができます(1人以上のマネージャのいる組織図をレンダリングする階層ビューア・コンポーネントなど)。実行時に階層ビューア・コンポーネントをレンダリングすると、フォーカスのあるノードがアンカー・ノードになります。実行時に、ユーザーがsetAnchorListenerプロパティに指定された値を持つ別のノードをダブルクリックすると、そのノードがアンカー・ノードになります。

階層ビューアを構成して、アンカー・ノードの上に1つ以上のレベル(祖先レベル)を表示することができます。たとえば、ある会社の従業員を検索する場合、その従業員の上の管理職の系統を表示できます。displayLevelsAncestorプロパティを使用して、祖先レベルを指定します。

始める前に:

階層ビューアの属性や階層の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアをページに追加します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

アンカー・ノードの祖先レベル数を指定する手順:

1. 構造ウィンドウで「dvt:hierarchyViewer」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウの「共通」セクションを開きます。

3. 実行時に、アンカー・ノードの上に表示する祖先ノードのレベル数を、祖先レベル・フィールドで指定します。
たとえば、アンカー・ノードの祖先レベルの数に2を入力すると、JSFページに次のエントリが表示されます。

displayLevelsAncestor="2"

4. JSFページへの変更を保存します。

29.4 パネル・カードの使用

パネル・カード・コンポーネントを階層ビューア・コンポーネントとともに使用して、階層ビューア・コンポーネントが参照するノードに異なる情報のセットを保持できます。パネル・カード・コンポーネントには、ノード要素内の領域で、1つ以上のaf:showDetailItem要素を含めることができます。

各af:showDetailItem要素がコンテンツの1セットを参照します。たとえば、組織図をレンダリングする階層ビューア・コンポーネントに組織内の従業員のノードを含めることができます。このノードには、1つのaf:showDetailItem要素、および給与情報を参照するもう1つのaf:showDetailItem要素を使用して連絡先情報を参照するパネル・カード・コンポーネントを含めることができます。

パネル・カード・コンポーネントには、実行時に1つのaf:showDetailItem要素によって参照されるコンテンツが表示されます。パネル・カード・コンポーネントによって、ナビゲーション・ボタン、およびユーザーがaf:showDetailItem要素によって参照されるデータのセット間の切替えを行えるようにする他のコントロールがレンダリングされます。ユーザーがデータの異なったセット間で切替えを行えるようにするコントロールは、オプションの遷移効果を使用して構成できます。たとえば、パネル・カードがaf:showDetailItem要素によって参照されるデータのセットと、別のaf:showDetailItem要素によって参照される別のデータのセットとの間を水平にスライドするように構成できます。

29.4.1 パネル・カードの作成方法

パネル・カード・コンポーネントは、JSFページの構造ウィンドウでFacet zoom要素を選択した場合に表示されるポップアップ・メニューを使用して、階層ビューア・コンポーネントをレンダリングするJSFページに挿入できます。

始める前に:

階層ビューアの属性や階層の子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

パネル・カードを作成する手順:

1. 構造ウィンドウで、パネル・カードを作成するノード内のズーム・レベルを右クリックします。
f:facet - zoom100などを選択します。

2. 選択したファセットにpanelGroupLayoutコンポーネントが含まれない場合、「zoomLevelの中に挿入」→「パネル・グループ・レイアウト」を選択してパネル・カードのコンテナを作成します。

3. 「プロパティ」ウィンドウを使用してパネル・グループ・レイアウトのプロパティを構成します。
パネル・グループ・レイアウト・コンポーネントの構成方法の詳細は、9.13.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

4. 構造ウィンドウでaf:panelGroupLayoutノードを右クリックして、「パネル・グループ・レイアウトの中に挿入」→「パネル・カード」と選択します。

5. 「プロパティ」ウィンドウを使用してパネル・カードのプロパティを構成します。
たとえば、パネル・カード・コンポーネントの「拡張」プロパティで、「効果」プロパティに値を設定し、パネル・カード上のコンテンツ間で遷移するときに使用する効果を指定します。有効な値は次のとおりです。

- slideHorz (デフォルト)
一方から新しいコンテンツがスライドして表示され、古いコンテンツが反対側にスライドして消えていきます。

- immediate
コンテンツは遷移効果なしで直ちに表示されます。

- flipHorz
showDetailItemがめくれて新しいコンテンツが表示されます。

- nodeFlipHorz
ノード全体がめくれて、新しいコンテンツが表示されます。

- cubeRotateHorz
showDetailItemがキューブの表面にあるかのように回転して新しいコンテンツが表示されます。

- nodeCubeRotateHorz
ノード全体がキューブの表面にあるかのように回転して新しいコンテンツが表示されます。

注意:

この他に、slide_horz、flip_horz、node_flip_horz、cube_rotate_horz、node_cube_rotate_horzも有効です。これらの値は、大文字小文字混在の値を優先するため非推奨ですが、古いコードやドキュメントには残っている場合もあります。

6. 構造ウィンドウで、dvt:panelCardを右クリックし、「パネル・カードの中に挿入」→「詳細アイテムの表示」を選択します。

7. 「プロパティ」ウィンドウを使用してaf:showDetailItem要素のプロパティを構成します。「プロパティ」ウィンドウのヘルプを表示するには、「ヘルプ」をクリックするか[F1]を押してください。

8. 希望するコンテンツを表示するために、af:showDetailItem要素に要素を追加します。構造ウィンドウでaf:showDetailItemを右クリックし、挿入する要素を選択します。

たとえば、階層ビューアで組織図をレンダリングする場合、従業員のIDを表示する要素を追加します。構造ウィンドウで、af:showDetailItemを右クリックし、「詳細アイテムの表示の中に挿入」→「ADF Faces」→「出力テキスト」を選択します。

9. 「プロパティ」ウィンドウを使用して、手順8でaf:showDetailItem要素に追加した要素のプロパティを構成します。「プロパティ」ウィンドウのヘルプを表示するには、「ヘルプ」をクリックするか[F1]を押してください。

10. パネル・カードに表示させたいコンテンツの各セットにつき、ステップ6からステップ9を繰り返します。

29.4.2 実行時の処理: パネル・カード・コンポーネントのレンダリング方法

実行時に、ノードが表示され、パネル・カード・コンポーネントが1つ表示されます。ユーザーはパネル・カードの下部にあるナビゲーション・ボタンをクリックして、パネル・カードのaf:showDetailItem子要素のいずれかによって参照されるコンテンツの次のセットにナビゲートできます。

図29-13に、2つの異なるaf:showDetailItem子要素が異なる情報のセット(ContactとAddress)を参照するパネル・カード・コンポーネントのあるノードを示します。この例のコントロールには、パネル・カードの中をスライドするための矢印と、表示するパネル・カードを直接選択するためのボタンがあります。両方のコントロール・オプションにツールチップが表示されています。

図29-13 パネル・カードを使用した実行時のノードの表示

29.5 階層ビューアでのナビゲーションの構成

デフォルトで、階層ビューア・コンポーネントのルート・ノードと内部ノードには下方向へのナビゲーションが構成されています。階層ビューア・コンポーネントで上方向へのナビゲーションを行い、ユーザーが同じレベルのノード間をナビゲートしたときに表示されるノードの数を決定できるように構成することができます。

ノード・タイプの詳細は、29.3項「階層ビューアでのノードの管理」を参照してください。

29.5.1 階層ビューアでの上方向へのナビゲーションの構成方法

階層ビューア・コンポーネントの上方へのナビゲーションを構成する場合、階層ビューア・コンポーネントのnavigateUpListenerプロパティの値を構成します。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューア・コンポーネントの上方向へのナビゲーションを構成する手順:

1. 構造ウィンドウで「dvt:hierarchyViewer」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを開き、ユーザーが新しいアンカー・ノードに上へナビゲートした場合に階層ビューアが新しいアンカー・ノードを参照するようにデータ・モデルを更新するメソッドを指定する、階層ビューア・コンポーネントのnavigateUpListenerプロパティの「上へナビゲート」フィールドに値を書き込みます。
値の指定にヘルプが必要な場合は、「上へナビゲート」ドロップダウン・メニューから「メソッド式ビルダー」を選び、メソッド式ビルダー・ダイアログに入ります。「メソッド式ビルダー」ダイアログでのヘルプには、「ヘルプ」をクリックするか、[F1]を押してください。

3. ページを保存します。

29.5.2 階層ビューアでの同レベル・ナビゲーションの構成方法

階層ビューア・コンポーネントのノード間の同レベル・ナビゲーションはデフォルトで有効にされています。階層ビューア・コンポーネントを構成して、一度に表示するノードの数を決定できます。これを行うと、ユーザーに次のナビゲートを可能にするコントロールが表示されます。

- 左または右にナビゲートして、次のノードのセットを表示

- 使用可能なノードのコレクションで最初または最後のノードのセットにナビゲート

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューア・コンポーネントの同レベル・ナビゲーションを構成する手順:

1. 構造ウィンドウで「dvt:hierarchyViewer」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「共通」セクションを開き、実行時に表示するノードの数をレベルごとのノード数フィールド(levelFetchSize)で指定します。
たとえば、ノードの数に3を入力すると、JSFページに次のエントリが表示されます。

levelFetchSize="3"

3. ページを保存します。

29.5.3 階層ビューアで同レベル・ナビゲーションを構成する場合の処理

実行時に、階層ビューア・コンポーネントのlevelFetchSizeプロパティの値として指定したノードの数が、階層ビューア・コンポーネントによってレンダリングされます。階層ビューア・コンポーネントは、ユーザーが次のことを実行できるコントロールもレンダリングします。

- 左または右にナビゲートして、次のノードのセットを表示

- 使用可能なノードのコレクションで最初または最後のノードのセットにナビゲート

図29-14に、levelFetchSize="3"の場合の実行時の例を示します。図29-14の丸で囲まれている領域に示すように、ユーザーがコントロール上にマウスを移動させると、ユーザーにノードの最後のセットへのナビゲートを可能にするコントロールが表示されます。

図29-14 同レベル・ナビゲーションを使用した階層ビューア・コンポーネント

29.6 階層ビューアの外観のカスタマイズ

階層ビューア・コンポーネントのサイズおよび外観(イメージの追加、コンロトール・パネルの表示の構成、リンクおよびラベルのカスタマイズなど)をカスタマイズできます。

階層ビューア・コンポーネントの外観は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」での説明のとおり、スキンおよびコンポーネント・スタイル属性を変更することによって変更できます。

29.6.1 階層ビューアのサイズの調整方法

inlineStyle属性とstyleClass属性を使用して、階層ビューアのサイズとスタイルを構成できます。どちらの属性も、dvt:hierarchyViewerあるいはdvt:nodeコンポーネントの「プロパティ」ウィンドウの「スタイル」セクションで使用可能です。これらの属性を使用して、フォント、境界線、およびバックグラウンド要素など、スタイルに関する機能をカスタマイズできます。

styleClass属性は、一連のインライン・スタイルのグループ化に使用されるCSSスタイル・クラス・セレクタです。スタイル・クラスは実行時にスタイル・クラスに評価されるEL式を使用して定義できます。ADFパブリック・スタイル・クラスを指定することもできます。たとえば、AFHVNodeImageSizeを使用して、階層ビューア内に合うようにイメージのサイズを設定できます。

inlineStyle属性は、セミコロンで区切られたCSSスタイルのリストで、個々のスタイル属性を設定できます。たとえば、color:blue;font-style:italicを指定してaf:outputTextコンポーネントの色とフォント・スタイルを変更できます。

styleClass属性とinlineStyle属性の使用方法の詳細は、31.2項「コンポーネントのスタイル・プロパティの変更」を参照してください。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューアのサイズまたはスタイルを調整する手順:

1. 階層ビューア・コンポーネントを含むJSFページの構造ウィンドウで、dvt:hierarchyViewerノードを右クリックし、「プロパティに移動」を選びます。

2. インライン・スタイルを使用して階層ビューアのサイズまたはスタイルを調整するには、「プロパティ」ウィンドウで「スタイル」セクションを開き、InlineStyleプロパティに次の値を指定します。

- width
パーセント(%)またはピクセル(px)で値を記述します。widthのデフォルト値は100%です。

- height
パーセント(%)またはピクセル(px)で値を記述します。heightのデフォルト値は600pxです。

InlineStyleプロパティに入力する最終値には、次の例に示す構文を使用する必要があります。

width:100%;height:600px;

3. スタイル・クラスを使用して階層ビューアのサイズまたはスタイルを調整するには、「プロパティ」ウィンドウでStyleClassプロパティに値を指定します。
たとえば、階層ビューアの高さに100%を指定するには、StyleClassにAFStretchHeightと入力します。

4. JSFページへの変更を保存します。

29.6.1.1 スキニングとhierarchyViewerコンポーネントに関する必知事項

階層ビューアは、コンポーネントのトップ・レベルのみでなく、ノード、ボタンおよびリンクについても、色やフォント・スタイルをカスタマイズするためのスキニングもサポートします。さらに、スキニングを使用して、ユーザーがマウスを置いた場合やナビゲーション・ボタンを押したときの階層ビューアのスタイルを定義できます。

例29-2に、ユーザーがパネル・カードのナビゲーション・ボタンを選択したときに枠の色を表示するように構成された階層ビューアのスキニング・キーを示します。

例29-2 選択されたときにパネル・カード・ナビゲーション・ボタンを変えるスキニング・キー

af|dvt-panelCard::navigation-button:active
{
-tr-border-color:#000000;
}

階層ビューアのスキニング・キーの完全なリストについては、Oracle Fusion Middleware Oracle ADF Facesスキン・セレクタ・データ視覚化ツール・タグ・リファレンスを参照してください。スキニングとスタイルを使用したアプリケーションのカスタマイズの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

階層ビューアを含むページには、サイズあるいはスタイルを変更する機能に制約のある場合があります。ページ・レイアウトの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

29.6.2 階層ビューアにイメージを含める方法

実行時に階層ビューア・コンポーネントのノードがイメージに表示されるように階層ビューア・コンポーネントを構成できます。これは、組織図に画像を表示するような場合に便利です。ソース属性を希望するイメージのURLにバインドしたaf:imageコンポーネントを挿入します。次のサンプル・コードでイメージをレンダリングします。

<af:panelGroupLayout>
<af:image source="/person_id=#{node.PersonId}"
shortDesc="Employee Image"
styleClass=AFHVNodeImageSize"/>
</af:panelGroupLayout>

af:panelGroupLayoutコンポーネントの詳細は、9.13.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

29.6.3 コントロール・パネルの表示の構成方法

コントロール・パネルを別の位置に表示されるように構成することはできませんが、階層ビューア・コンポーネントを実行時にレンダリングする際に次の動作を行うように構成することはできます。

- 開いたまたは表示状態での表示

- 閉じたまたは非表示状態での表示

- ユーザーに対して非表示

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

コントロール・パネルの表示を構成する手順:

1. 構造ウィンドウで「dvt:hierarchyViewer」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」セクションを開き、「ControlPanelBehavior」ドロップダウン・リストから次の値のいずれかを選択します。

- hidden
実行時にコントロール・パネルを表示しない場合は、この値を選択します。

- initCollapsed
これがデフォルト値です。コントロール・パネルは、実行時に閉じたまたは非表示状態で表示されます。

- initExpanded
実行時にコントロール・パネルを開いたまたは表示状態で表示する場合は、この値を選択します。

3. JSFページへの変更を保存します。

29.6.4 リンクおよびラベルの表示を構成する方法

階層ビューアでは、ノード間の関係がノードを結ぶ線によって表されます。リンクは、ラベルが含まれるように構成できます。図29-15に、階層ビューアでのリンクとラベルを示します。

図29-15 階層ビューアのリンクとラベル

リンクとラベルの外観は、階層ビューアでdvt:link要素のプロパティを設定することでカスタマイズできます。図29-16に、linkStyle属性に設定されたdashDot値とのリンクを示します。

図29-16 破線と点線のリンク・スタイルのリンク

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

リンクおよびラベルの表示をカスタマイズする手順:

1. 構造ウィンドウで「dvt:link」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、次の属性を設定して、階層ビューア内のノード間のリンクの外観を希望するようにカスタマイズします。

- LinkStyle: リンクのスタイル(点線または破線など)を設定します。

- LinkColor: リンクの色を設定します。

- LinkWidth: リンクの幅をピクセル単位で設定します。

- LinkType: リンクのタイプ(直線または1つの直角にぴったり合う滑らかな曲線など)を設定します。

- EndConnectorType: リンク接続エンドのスタイルをnone (デフォルト)またはarrowOpenに設定します。

3. 「プロパティ」ウィンドウで、リンクに関連付けられたラベルのテキストをLabelプロパティに入力します。
または、子ノードに基づいてリンク・ラベルをスタンプ・アウトするEL式を指定します。たとえば、ノードのvar属性がリンクと関連付けられた子ノードを参照する次のようなEL式を記述します。

label="{node.relationship}"

EL式作成の詳細は、3.5項「EL式の作成」を参照してください。

4. また必要に応じて、「プロパティ」ウィンドウで、Renderedプロパティを使用して、ノード間の特定の関係のリンクをスタンプします。このプロパティにはブール値を指定するため、リンクが関係を表すかどうかを決定するtrueまたはfalseに評価されるEL式を記述できます。たとえば、関係のレポートに基づいてリンクを表示するとします。リンク・コンポーネントのRenderedプロパティに対して、関係が指定した値(この例ではCONSULTANT)と一致する場合にtrueと評価する次のEL式のようなEL式を記述します。

rendered="#{node.relationship == "CEO"}

29.6.5 ホバー・ディテール・ウィンドウの無効化の方法

デフォルトでは、ズーム・レベルが76%未満のとき、ホバー・ウィンドウが自動的に表示されます。ユーザーの階層ビューアがポップアップを使用している場合、ホバー・ウィンドウはそのポップアップ表示と干渉する可能性があります。階層ビューアのdetailWindow属性を使用して、ホバー・ウィンドウの表示を消すことができます。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューアのホバー・ウィンドウを無効化するには:

1. 構造ウィンドウで「dvt:hierarchyViewer」を右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「動作」セクションを開き、DetailWindowドロップダウン・リストから次の値の1つを選択します。

- default
これがデフォルト値です。ホバー・ウィンドウは、常時有効化されます。

- none
ホバー・ウィンドウを有効化しない場合はこの値を選択してください。

29.7 階層ビューア・コンポーネントへの対話性の追加

階層ビューア・コンポーネントを構成して、ポップアップ・ウィンドウを起動し、機能およびOracle Fusion Webアプリケーションの他のページからのデータが示されたメニューの表示またはドラッグ・アンド・ドロップ機能のサポートを行います。

29.7.1 ノード選択アクションを構成する方法

デフォルトでは、階層ビューアのノードを実行時にクリックして、ノードを選択します。dvt:nodeコンポーネントでclickBehavior属性を設定することにより、この相互作用をカスタマイズできます。このプロパティの有効な値は次のとおりです。

- focus: ノードはフォーカスされ、クリックすると選択されます(デフォルト)。

- expandCollapse: 子ノード要素は、現在の展開状態に応じて、展開または縮小されます。

- isolateRestore: ノードは、現在の状態に応じて、分離またはリストアされます。

- none: ノードをクリックしても何も起こりません。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

ノード選択アクションを構成する手順:

1. 構造ウィンドウでdvt:nodeノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを開き、属性のドロップダウン・リストからClickBehaviorを選択します。

3. JSFページへの変更を保存します。

29.7.2 ポップアップ・ウィンドウを起動するための階層ビューアの構成

af:showPopupBehaviorタグの値を指定し、コマンド・コンポーネント(af:buttonなど)から起動することにより、階層ビューア・ノードからポップアップ・ウィンドウを起動できます。階層ビューア・コンポーネントのノードのf:facet要素内で、ポップアップを起動するコマンド・コンポーネントをネストする必要があります。このシナリオで使用されるaf:showPopupBehaviorタグのtriggerTypeプロパティは、次の値のみをサポートします。

- action

- mouseHover

たとえば、図29-17は、ノード内のHR Detailリンクから起動されたモーダル・ポップアップを示しています。例29-3に、ポップアップを作成するサンプル・コードを示します。

図29-17 階層ビューア・ノードのモーダル・ポップアップ

例29-3 ポップアップを作成するサンプル・コード

<af:popup id="popupDialog" contentDelivery="lazyUncached" eventContext="launcher"
launcherVar="source">
<af:setPropertyListener from="#{source.currentRowData}"
to="#{myBean.selectedEmployee}" type="popupFetch"/>
<af:dialog title="Employee HR Detail">
<af:panelFormLayout>
<af:panelLabelAndMessage label="Name" >
<af:outputText value="#{myBean.selectedEmployee.firstName} #{myBean.selectedEmployee.lastName}"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="Offical Title" >
<af:outputText  value="#{myBean.selectedEmployee.officalTitle}"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="HR Manager Id" >
<af:outputText value="#{myBean.selectedEmployee.hrMgrPersonId}"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="HR Rep Id" >
<af:outputText value="#{myBean.selectedEmployee.hrRepPersonId}"/>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:dialog>
</af:popup>

例29-4に、階層ビューア・コンポーネントからポップアップを起動するサンプル・コードを示します。簡潔にするために、<af:panelGroupLayout>、<af:spacer>および<af:separator>などの要素は、サンプル・コードには含まれていません。

例29-4 階層ビューア・コンポーネントからポップアップを起動するサンプル・コード

<f:facet name="zoom100">
...
<dvt:panelCard effect="slideHorz"
...
<af:showDetailItem text="Contact "
...
<af:button text="Show HR Detail"
inlineStyle="font-size:14px;color:#383A47"
id = bu1>
<af:showPopupBehavior popupId="::popupDialog" triggerType="action"
align="endAfter" alignId="bu1" />
</af:button>
</showDetailItem>
</dvt:panelCard>
</f:facet>

af:showPopupBehaviorタグの使用方法の詳細は、15.3項「ポップアップの宣言的な呼出し」を参照してください。

29.7.3 階層ビューアのドラッグ・アンド・ドロップの構成

階層ビューアは、次のドラッグ・アンド・ドロップのシナリオをサポートします。

- 階層ビューア内で、1つ以上のノードをドラッグ・アンド・ドロップします

- 階層ビューアから1つ以上のノードを別のコンポーネントにドラッグします

- 別のコンポーネントから階層ビューアに1つ以上のアイテムをドラッグします

図29-18に、その中でのドラッグ・アンド・ドロップを可能とするように構成した階層ビューアを示します。この例では、ノードをクリックし0.5秒を超えて保持すると、バックグラウンドにドラッグして階層内の別のルートにしたり、別のノードにドラッグしてそのノードの子として追加したりすることができます。

図29-18 ノード・ドラッグを示す階層ビューア

図29-19に、階層ビューアのバックグラウンドへのドラッグの結果を示します。Nancy Greenとその部下は、今は階層における新しいツリーとして示されます。

図29-19 バックグラウンドへのノード・ドラッグ後の階層ビューア

ノードを別のノードにドラッグすると、ドラッグされたノードとその子は、ターゲット・ノードの子となる。図29-20に、Nina Evansのデータを含むノードへのドラッグの結果を示します。Nancy Greenとその部下は、今はNina Evansの部下として示されます。

図29-20 別のノードへのノード・ドラッグ後の階層ビューア

図29-21に、af:outputFormattedコンポーネントとの間のドラッグやドロップを可能とするように構成された、同じ階層ビューアの例を示します。この例では、ユーザーは1つ以上のノードをドロップ・テキストにドラッグでき、かつテキストは変化して、ユーザーがどのノードをドラッグし、どの操作を実行したかを示します。ユーザーがドラッグ・テキストから階層ビューア・ノードかバックグラウンドにドラッグした場合、テキストは変化して、テキストがどこでドラッグされ、どの操作が実行されたかを示します。

図29-21 別のコンポーネントへのドラッグ・アンド・ドロップを可能とするように構成した階層ビューア

図29-22に、ユーザーがNina EvansとJames Marlowのデータを含むノードをドロップ・テキストにドラッグした後の、同じ階層ビューアを示します。

図29-22 複数ノードのドラッグの後の階層ビューア

ユーザーがドラッグ・テキストから階層ビューア・ノードかバックグラウンドにドラッグした場合、テキストは変化して、テキストがどこでドラッグされ、どの操作が実行されたかを示します。図29-23に、ユーザーがテキストを階層ビューアのバックグラウンドへドラッグした後の、同じ階層ビューアを示します。

図29-23 階層ビューア・バックグラウンドへのテキスト・ドラッグ後の階層ビューア

29.7.3.1 階層ビューアのドラッグ・アンド・ドロップの構成方法

階層ビューアにドラッグのサポートを追加するには(これによりコンポーネントや他の階層ビューアがそこからノードのドラッグが可能となりますが)、af:dragSourceタグを階層ビューアに付加し、af:dropTargetタグをドラッグを受け取るコンポーネントに追加します。ドラッグを受け取るコンポーネントはorg.apache.myfaces.trinidad.model.RowKeySetデータ・フレーバをaf:dropTargetの子として含み、かつドロップ・イベントへの応答のため、dropListenerメソッドを定義する必要があります。

階層ビューアにドロップのサポートを追加するには(これによりコンポーネントや他の階層ビューアがそこへのアイテムのドラッグが可能となりますが)、af:dropTargetタグを階層ビューアに追加し、その階層ビューアがサポートするデータ・フレーバを含めます。dropListenerメソッドを、ドロップ・イベントに応答するマネージドBeanに追加します。

次の手順は、図29-21に示すaf:outputFormattedコンポーネントの、単一のドラッグ・ソースあるいはドロップ・ターゲットとして、階層を設定する方法を示します。ADF FacesまたはADFデータ視覚化コンポーネントのドラッグ・アンド・ドロップの構成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページに階層ビューアを追加します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

- ドラッグ・アンド・ドロップをサポートするのに必要な追加コンポーネントを作成します。
たとえば、図29-21の中のページはaf:panelGroupLayoutコンポーネントを使用し、このコンポーネントはaf:outputFormattedとaf:panelListコンポーネントを含み、ユーザーに手順を提供します。このページはまたaf:panelSplitterコンポーネントを使用して、ドラッグ・アンド・ドロップaf:outputFormattedコンポーネント・テキストを階層ビューアから分割します。

例29-5に、追加コンポーネントの、完了したページ・セクションを示します。階層ビューアの詳細は省略されています。

例29-5 階層ビューアのドラッグ・アンド・ドロップ例のサンプル・コード

<af:panelStretchLayout id="psl1" topHeight="auto" endWidth="auto">
<f:facet name="top">
<af:panelGroupLayout id="pgl2" layout="horizontal">
<af:spacer width="10px" id="s8"/>
<af:panelGroupLayout id="pgl14">
<af:outputFormatted value="Hierarchy Viewer Drag and Drop Example"
id="of4" inlineStyle="font-size:small;
font-weight:bold;"/>
<af:panelList id="pl1"
inlineStyle="font-size:x-small;">
<af:outputFormatted value="Click and hold on a node for more than one-half second to initiate the drag. Use Ctrl+Click to select multiple nodes."
id="of1" inlineStyle="font-size:x-small;"/>
<af:outputFormatted value="Drag one or more nodes from the hierarchy viewer to the drop text. The text will change to show which node(s) you dragged and the operation performed."
id="of2" inlineStyle="font-size:x-small;"/>
<af:outputFormatted value="Drag the drag text to one of the hierarchy viewer nodes or background. The text will change to show where you dropped it and the operation performed."
id="of3" inlineStyle="font-size:x-small;"/>
</af:panelList>
</af:panelGroupLayout>
</af:panelGroupLayout>
</f:facet>
<f:facet name="center">
<af:panelSplitter id="ps1" orientation="horizontal" splitterPosition="125"
positionedFromEnd="false" styleClass="AFStretchWidth">
<f:facet name="first">
<af:panelSplitter id="ps2" orientation="vertical">
<f:facet name="first">
<af:panelGroupLayout id="pgl3" layout="vertical">
<af:separator id="s1"/>
<af:outputFormatted value="#{hvBean.dropText}"
clientComponent="true"
inlineStyle="font-size:small; font-weight:bold;"
id="of5">
<af:dropTarget actions="COPY MOVE LINK"
dropListener="#{hvBean.fromDropListener}">
<af:dataFlavor
flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"/>
</af:dropTarget>
</af:outputFormatted>
<af:spacer width="200" id="s11"/>
<af:separator id="s3"/>
</af:panelGroupLayout>
</f:facet>
<f:facet name="second">
<af:panelGroupLayout id="pgl1">
<af:separator id="s12"/>
<af:outputFormatted value="#{hvBean.dragText}"
clientComponent="true"
inlineStyle="font-size:small; font-weight:bold;" id="of6">
<af:componentDragSource/>
</af:outputFormatted>
<af:separator id="s10"/>
</af:panelGroupLayout>
</f:facet>
</af:panelSplitter>
</f:facet>
<f:facet name="second">
<dvt:hierarchyViewer id="shv" styleClass="AFStretchWidth"
controlPanelBehavior="initExpanded"
var="node" detailWindow="none"
value="#{XMLParser.employees}"
contentDelivery="immediate"
summary="HV Drag and Drop Sample"
navigateUpListener="#{XMLParser.doNavigateUp}">
<af:dragSource actions="COPY MOVE LINK" defaultAction="MOVE"/>
<af:dropTarget actions="COPY MOVE LINK"
dropListener="#{hvBean.toDropListener}">
<af:dataFlavor flavorClass="java.lang.Object"/>
</af:dropTarget>
<dvt:link linkType="orthogonalRounded" id="l1"/>
<dvt:node width="233" height="330"
setAnchorListener="#{XMLParser.doSetAnchor}" id="n1"
showNavigateUp="#{node.topNode == false}"
showExpandChildren="#{node.hasChildren}">
<f:facet name="zoom100">
< remaining hierarchy viewer contents omitted >
</dvt:hierarchyViewer>
</f:facet>
</af:panelSplitter>
</f:facet>
</af:panelStretchLayout>

af:outputFormattedコンポーネントについての追加情報は、第18章「出力コンポーネントの使用」を参照してください。af:panelGroupLayoutコンポーネンントや他のページ・レイアウト・コンポーネントに関するヘルプについては、第9章「Webページ上のコンテンツの編集」を参照してください。

階層ビューアのドラッグ・アンド・ドロップを構成するには:

1. 階層ビューアをドロップ・ターゲットとして構成するには、「コンポーネント」ウィンドウで、「操作」パネルから、「ドロップ・ターゲット」タグをドラッグし、階層ビューアの子としてドロップします。

2. 「ドロップ・ターゲットを挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選び、ドロップ・リスナー・メソッドを階層ビューアのマネージドBeanに追加してください。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、toDropListener()という名前のメソッドをhvBeanという名前のマネージドBeanに追加するには、編集を選び、ドロップダウン・メニューからhvBeanを選択し、新規を「メソッド」フィールドの右でクリックして、toDropListener()メソッドを作成します。

例29-6はサンプルのドロップ・リスナーと図29-21で示される階層ビューアのサポート・メソッドを示します。

例29-6 階層ビューアのサンプル・ドロップ・リスナー

// imports needed by methods
import java.util.Map;
import oracle.adf.view.rich.dnd.DnDAction;
import oracle.adf.view.rich.event.DropEvent;
import oracle.adf.view.rich.datatransfer.DataFlavor;
import oracle.adf.view.rich.datatransfer.Transferable;
import org.apache.myfaces.trinidad.context.RequestContext;
import org.apache.myfaces.trinidad.render.ClientRowKeyManager;
import javax.faces.context.FacesContext;
import oracle.adf.view.faces.bi.component.hierarchyViewer.UIHierarchyViewer;
import javax.faces.component.UIComponent;
// variables need by methods
private String dragText = "Drag this text onto a node or the hierarchy viewer background";
// drop listener
public DnDAction toDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<Object> dataFlavor = DataFlavor.getDataFlavor(Object.class);
Object transferableObj = transferable.getData(dataFlavor);
if(transferableObj == null)
return DnDAction.NONE;
// Build up the string that reports the drop information
StringBuilder sb = new StringBuilder();
// Start with the proposed action
sb.append("Drag Operation: ");
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
sb.append("Copy<br>");
}
else if(proposedAction == DnDAction.LINK) {
sb.append("Link<br>");
}
else if(proposedAction == DnDAction.MOVE) {
sb.append("Move<br>");
}
// Then add the rowKeys of the nodes that were dragged
UIComponent dropComponent = event.getDropComponent();
Object dropSite = event.getDropSite();
if(dropSite instanceof Map) {
String clientRowKey = (String) ((Map) dropSite).get("clientRowKey");
Object rowKey = getRowKey(dropComponent, clientRowKey);
sb.append("Drop Site: ");
if(rowKey != null) {
sb.append("Node: ");
sb.append(getLabel(dropComponent, rowKey));
}
else {
sb.append("Background");
}
}
// Update the output text
this._dragText = sb.toString();
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return event.getProposedAction();
}
private String getLabel(UIComponent component, Object rowKey) {
if(component instanceof UIHierarchyViewer) {
UIHierarchyViewer hv = (UIHierarchyViewer) component;
Employee rowData = (Employee) hv.getRowData(rowKey);
return rowData.getFirstName() + " " + rowData.getLastName();
}
return null;
}
private Object getRowKey(UIComponent component, String clientRowKey) {
if(component instanceof UIHierarchyViewer) {
UIHierarchyViewer hv = (UIHierarchyViewer) component;
ClientRowKeyManager crkm = hv.getClientRowKeyManager();
return crkm.getRowKey(FacesContext.getCurrentInstance(), component, clientRowKey);
}
return null;
}
public String getDragText() {
return _dragText;
}

注意:

このメソッドは、階層ビューアの属性を定義するEmployeeクラスを参照しています。ユーザーの階層ビューアが異なるクラスを使用している場合、かわりにそのクラスの名前を置き換えてください。

この例で使用されているEmployeeクラスのソース・コードを見る場合、そのソース・コードやADF Facesのデモ・アプリケーションのソース・コードを見つけることができます。デモ・アプリケーションの詳細は、第2章「ADF Facesデモ・アプリケーション」を参照してください。

3. 「OK」をクリックして、「データ・フレーバの挿入」ダイアログに入ります。

4. 「データ・フレーバの挿入」ダイアログで、ドロップ・ターゲットが受け入れるオブジェクトを入れます。または、ドロップダウン・メニューを使用してオブジェクトの階層をナビゲートし、希望するオブジェクトを選択します。
たとえば、af:outputFormattedコンポーネントがテキストを階層ビューアにドラッグできるようにするには、java.lang.Objectを「データ・フレーバの挿入」ダイアログに入力します。

5. 構造ウィンドウでaf:dropTargetノードを右クリックし、「プロパティに移動」を選択します。

6. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

7. 階層ビューアをドロップ・ターゲットとして使用するには、次を実行します。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグをドラッグのソースとなるコンポーネントの子としてドラッグ・アンド・ドロップします。
たとえば、「ドラッグ元」をaf:outputFormattedコンポーネントの子としてドラッグ・アンド・ドロップします。

2. 構造ウィンドウでaf:dragSourceノードを右クリックし、「プロパティに移動」を選択します。

3. コンポーネントの「値」フィールドでは、手順2でドロップ・リスナーで階層ビューアに作成したパブリック変数を参照します。
たとえば、toDropListener()という名前のドロップ・リスナーとdropTextという名前の変数には、コンポーネントの「値」フィールドに、次を入力します。

#{hvBean.dropText}

8. 階層ビューアをドラッグ・ソースとして構成するには、「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグを、階層ビューアの子としてドラッグ・アンド・ドロップします。

9. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

10. ドラッグ・ソースがサポートするデフォルトのアクションを指定するには、DefaultAction属性のドロップダウン・メニューを使用して、「コピー」,、「移動」または「リンク」を選択します。
図29-21におけるドラッグ・アンド・ドロップの例での階層ビューアは、移動をデフォルトのアクションとして使用しています。

11. 他のコンポーネントを階層ビューアからのドラッグのドロップ・ターゲットとするには、以下を実行します。

1. 「コンポーネント」ウィンドウで、「Operations」パネルから、「ドロップ・ターゲット」を、ドロップを受け取るコンポーネント上にドラッグ・アンド・ドロップします。
たとえば、図29-21におけるドラッグ・アンド・ドロップの例のページは、ドロップの結果を表示するaf:outputFormattedコンポーネントを含んでいます。

2. 「ドロップ・ターゲットの挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選び、ドロップ・リスナー・メソッドを適切なマネージドBeanに追加してください。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、fromDropListener()という名前のメソッドをhvBeanという名前のマネージドBeanに追加するには、編集を選び、ドロップダウン・メニューからhvBeanを選択し、新規を「メソッド」フィールドの右でクリックして、fromDropListener()メソッドを作成します。

例29-7は、図29-21に表示される階層ビューアのサンプル・ドロップ・リスナーを示します。この例は同じインポートとヘルパー・メソッドを使用しており、それらはここには含まれていません。

例29-7 階層ビューアをドラッグ・ソースとして使用するコンポーネントのサンプル・ドロップ・リスナー

// Additional import needed for listener
import org.apache.myfaces.trinidad.model.RowKeySet;
// Variables needed by method
private String dropText = "Drop a node here";
// Drop listener
public DnDAction fromDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<RowKeySet> dataFlavor = DataFlavor.getDataFlavor(RowKeySet.class);
RowKeySet rowKeySet = transferable.getData(dataFlavor);
if(rowKeySet == null || rowKeySet.getSize() <= 0)
return DnDAction.NONE;
// Build up the string that reports the drop information
StringBuilder sb = new StringBuilder();
// Start with the proposed action
sb.append("Drag Operation: ");
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
sb.append("Copy<br>");
}
else if(proposedAction == DnDAction.LINK) {
sb.append("Link<br>");
}
else if(proposedAction == DnDAction.MOVE) {
sb.append("Move<br>");
}
// Then add the rowKeys of the nodes that were dragged
sb.append("Nodes: ");
UIComponent dragComponent = event.getDragComponent();
for(Object rowKey : rowKeySet) {
sb.append(getLabel(dragComponent, rowKey));
sb.append(", ");
}
// Remove the trailing ,
sb.setLength(sb.length()-2);
// Update the output text
this.dropText = sb.toString();
RequestContext.getCurrentInstance().addPartialTarget(event.getDropComponent());
return event.getProposedAction();
}

3. 「OK」をクリックして、「データ・フレーバの挿入」ダイアログに入ります。

4. 「データ・フレーバの挿入」ダイアログで、org.apache.myfaces.trinidad.model.RowKeySetを入力します。
たとえば、af:outputFormattedコンポーネントがテキストを階層ビューアにドラッグできるようにするには、org.apache.myfaces.trinidad.model.RowKeySetを「データ・フレーバの挿入」ダイアログに入力します。

5. 構造ウィンドウでaf:dropTargetノードを右クリックし、「プロパティに移動」を選択します。

6. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

7. コンポーネントの値のフィールドでは、ステップ2でドロップ・リスナーでツリーマップあるいはサンバーストに作成したパブリック変数を参照します。
たとえば、fromDropListener()という名前のドロップ・リスナーとdragTextという名前の変数には、コンポーネントの値フィールドに、次を入力します。

#{hvBean.dragText}

29.7.3.2 階層ビューアのドラッグ・アンド・ドロップに関する必知事項

ノードをドラッグする機能を、そのdraggable属性をnoと設定することで、無効化できます。

29.8 階層ビューアへの検索の追加

階層ビューアの検索機能では、階層ビューアのデータ構造を調べ、スクロール可能なリストに一致を提示します。ユーザーは、検索結果をダブルクリックすると、一致するノードを階層ビューアのアンカー・ノードとして表示できます。有効な場合、階層ビューアの右上隅に検索パネルが表示され、結果は検索パネルの下に表示されます。図29-24に、検索パネルのサンプルを示します。

図29-24 階層ビューアの検索パネル

図29-25に、検索結果のサンプルを示します。

図29-25 階層ビューアの検索結果のサンプル

29.8.1 階層ビューアでの検索の構成方法

検索を有効にするには、dvt:searchタグをdvt:hierarchyViewerタグの子として追加し、結果の処理方法を指定するには、dvt:searchResultsをdvt:searchの子として追加します。

階層ビューアでの検索は、検索可能な属性、または階層ビューア・データ・モデルの基礎であるデータ・コレクションの列に基づいています。Oracle ADFのデータ・コントロールで定義されている問合せ結果コレクションを使用して、JDeveloperではこれが宣言的タスクになります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の階層ビューアでのデータ・バインドされた検索の構成方法に関する項を参照してください。

始める前に:

階層ビューアの属性や階層ビューアの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、29.2.1項「階層ビューア・コンポーネントの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、29.1.3項「階層ビューア・コンポーネントの追加機能」を参照してください。

ページ上にすでに階層ビューアがあるはずです。ない場合は、この章の指示に従って階層ビューアを作成します。詳細は、29.2.2項「ページへの階層ビューアの追加方法」を参照してください。

階層ビューアでの検索を構成する手段:

1. 構造ウィンドウで、dvt:hierarchyViewerコンポーネントを右クリックし、「階層ビューアの中に挿入」→「検索」を選択します。

2. 「プロパティ」ウィンドウで、次の属性を設定して検索機能を構成します。

- Value: 検索テキストを保持する変数を指定します。

- ActionListener: 検索を実行するためにコールされるリスナーを入力します。

- InitialBehavior: 検索パネルの初期表示を指定します。有効な値は、最初縮小された状態のinitCollapsed、最初開かれた状態のinitExpanded、またはビューから完全に隠すhiddenです。

3. オプションで、af:queryコンポーネントを使用して階層ビューア・コンポーネントの外で拡張検索を開始するコンポーネントを構成するには:

1. 構造ウィンドウで、「dvt:search」ノードを展開します。

2. 「af:commandLink」ノードを右クリックし、 「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、「af:commandLink」ノードを使用して目的のプロパティを構成します。
たとえば、拡張検索に対して「Advanced」を表示するテキストを変更するには、Text属性の値を入力します。

4. 拡張検索オプションをユーザーに表示するポップアップを追加するには、構造ウィンドウで、「af:commandLink」ノードをクリックして、「コマンド・リンクの中に挿入」→「ADF Faces」→「ポップアップ表示動作」を選択します。

5. ポップアップの構成を終了するには、af:popupコンポーネントをページに追加してaf:queryコンポーネントが検索を実行するように構成します。
ポップアップの構成方法のヘルプを参照するには、15.3項「ポップアップの宣言的な呼出し」を参照してください。queryコンポーネントの詳細は、14.4項「queryコンポーネントの使用方法」を参照してください。

4. 構造ウィンドウで「dvt:search」ノードを右クリックし、「検索の中に挿入」→「検索結果」を選択します。

5. 「プロパティ」ウィンドウで、次の属性を設定して検索結果の表示を構成します。

- Value: 検索結果のデータ・モデルを指定します。これは、oracle.adf.view.faces.bi.model.DataModelのインスタンスである必要があります。

- Var: 階層ビューア・コレクションの各要素の参照に使用されるEL変数の名前を入力します。このコンポーネントのレンダリングが完了すると、この変数は削除されるか、その前の値に戻ります。

- VarStatus: varStatus情報の参照に使用されるEL変数の名前を入力します。このコンポーネントのレンダリングが完了すると、この変数は削除されるか、その前の値に戻ります。

- ResultListener: 検索結果の1行が選択された後コールされるアクション・リスナーに対する参照を指定します。

- EmptyText: 結果が返されなかった場合に表示されるテキストを指定します。

- FetchSize: 一度にフェッチされる結果の行数を指定します。

6. 構造ウィンドウでdvt:searchResultsノードを右クリックし、「検索結果の中」を選択します。

7. 「プロパティ」ウィンドウで次の属性を設定し、検索結果ノードを結果モデルから対応する階層ビューア・モデルにマップします。

- From: 値のソース(定数またはEL式)を指定します。

- To: 値のターゲットを指定します。

- Type: actionを値として選択します。

8. 構造ウィンドウで、検索結果にスタンプを設定するコンポーネントを次のように指定します。

- 検索結果を折り返すには、「f:facet-content」ノードを右クリックして、「ファセットの中に挿入」→「ADF Faces」→「パネル・グループ・レイアウト」を選択します。

- 検索結果を表示するには、ADF Faces出力コンポーネントをaf:panelGroupLayoutノードの中に挿入して検索結果を表示します。
たとえば、出力テキストを表示するには、「af:panelGroupLayout」を右クリックして「パネル・グループ・レイアウトの中に挿入」→「出力テキスト 」を選択します。

2つのaf:outputText要素を挿入して構成すると次の出力が表示されます。

<af:outputText value="#{resultRow.Lastname} " id="ot1"
inlineStyle="color:blue;"/>
<af:outputText value="#{resultRow.Firstname}" id="ot2"/>

スタンプされた各行では、dvt:searchResultsタグのvar属性を使用して、現在の行を参照します。

例29-8に、階層ビューアでの検索を構成するためのサンプル・コードを示します。

例29-8 階層ビューアの検索のサンプル・コード

<dvt:hierarchyViewer>
... hierarchy viewer details omitted
<dvt:search id="searchId" value="#{bindings.lastNameParam.inputValue}"
actionListener="#{bindings.ExecuteWithParams1.execute}">
<f:facet name="end">
<af:commandLink text="Advanced">
<af:showPopupBehavior popupId="::mypop" triggerType="action"/>
</af:commandLink>
</f:facet>
<dvt:searchResults id="searchResultId"
emptyText="#{bindings.searchResult1.viewable ? 'No match.' : 'Access Denied.'}"
fetchSize="25"
value="#{bindings.searchResult1.collectionModel}"
resultListener="#{bindings.ExecuteWithParams.execute}"
var="resultRow">
<af:setPropertyListener from="#{resultRow.Id}"
to="#{bindings.employeeId.inputValue}"
type="action"/>
<f:facet name="content">
<af:panelGroupLayout layout="horizontal">
<af:outputText value="#{resultRow.Lastname} " id="ot1"
inlineStyle="color:blue;"/>
<af:outputText value="#{resultRow.Firstname}" id="ot2"/>
</af:panelGroupLayout>
</f:facet>
</dvt:searchResults>
</dvt:search>
</dvt:hierarchyViewer>

29.8.2 階層ビューアでの検索の構成に関する必知事項

検索結果スタンプにより、最も外側のコンテナに指定されたサイズで、af:panelGroupLayoutが表示されます。デフォルトでは、このサイズは100×30ピクセルです。検索結果表示でサイズを調整する必要がある場合は、af:panelGroupLayoutのInlineStyle属性を構成します。詳細は、9.13.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

30ツリーマップとサンバースト・コンポーネントの使用

この章では、ADF データ可視化ツリーマップおよびサンバースト・コンポーネントを使い、ツリーマップとサンバーストで階層データを単純UI-first開発を使用して表示する方法を記述します。この章では、データ要件、タグ構造、およびコンポーネントの見え方や動作をカスタマイズするためのオプションを定義します。

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してツリーマップやサンバーストを作成することもできます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」の章を参照してください。

この章では、次の項目について説明します。

- 30.1項「ツリーマップとサンバースト・コンポーネントについて」

- 30.2項「ツリーマップとサンバースト・コンポーネントの使用」

- 30.3項「ツリーマップとサンバースト・コンポーネントへのデータの追加」

- 30.4項「ツリーマップとサンバーストの表示要素のカスタマイズ」

- 30.5項「ツリーマップとサンバーストヘの対話機能の追加」

30.1 ツリーマップとサンバースト・コンポーネントについて

ツリーマップとサンバーストを使用して、定量的な階層データをサイズと色により視覚的に表現し、2つの次元にまたがり表示します。ツリーマップおよびサンバーストでは、nodeと呼ばれる形を使用して、階層内のデータを表します。

たとえば、ツリーマップまたはサンバーストを使用して地域の四半期ごとの売上げを表示し、売上げ傾向を特定する場合は、ノードのサイズで各地域の売上げ高を示し、ノードの色でその地域の売上げが四半期で増えたか減ったかを示すことができます。ノードの外観とコンテンツは、階層の各レベルで構成可能です。

30.1.1 ツリーマップとサンバーストの使用ケースと例

ツリーマップはノードをネストした矩形のセットとして表示します。ツリーのブランチごとに1つの矩形が割り当てられ、そこにサブブランチを表すより小さな矩形が並べられます。図30-1は、地域別にグループ化した米国の国勢調査データを示し、色属性が所得の中間値レベルを示すのに使用されています。人口の多い州は人口の少ない州より大きなノードで表示されます。

図30-1 米国の地域別人口と所得の中間値を表示するツリーマップ

サンバーストは、ノードを矩形レイアウトではなく、放射状に表示し、階層のトップを中心に、深いレベルになると中心から離れて表示します。図30-2に、サンバーストで表示した同じ国勢調査データを示します。

図30-2 米国の地域別人口と所得の中間値を表示するサンバースト

ツリーマップとサンバーストのいずれも、数千のデータ・ポイントを比較的小さな空間領域に表示できます。各ノードの相対サイズが全体に対する重要度を表しているため、これらのコンポーネントは大規模な階層データ・セットで傾向を特定する場合に適しています。色もまた、情報に追加される次元の表現に使用できます。

階層の1つのレイヤーでサイズと色を使用してデータの2つのメトリックを表示することが主な目的の場合は、ツリーマップを使用します。階層のすべてのレベルでのメトリックを表示する場合、かわりにサンバーストを使用します。エンド・ユーザーが階層を横断してデータの重要な部分を重点的に表示できるように、ドリルを有効にできます。

アプリケーションが小さいデータ・セットを使用する場合、あるいはノード間の親子関係を強調する場合、ツリー、ツリー表あるいは階層ビューア・コンポーネントの使用を考えます。ツリーやツリー表の詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。階層ビューアの使用については、第29章「階層ビューア・コンポーネントの使用方法」を参照してください。

30.1.2ツリーマップとサンバーストのエンド・ユーザー機能およびプレゼンテーション機能

ADFデータ可視化ツールのツリーマップおよびサンバースト・コンポーネントは、ドリル、グループ化およびフィルタリングなど、エンド・ユーザー向けの幅広い機能を提供します。これらはまた、レイアウトのバリエーション、凡例の表示、およびカスタマイズ可能な色やラベル・スタイルなど、幅広いプレゼンテーション機能を提供します。

ツリーマップやサンバースト・コンポーネントの使用やカスタマイズには、次の機能やコンポーネントの理解が役立ちます。

30.1.2.1 ツリーマップとサンバーストのレイアウト

ページにコンポーネントを挿入する際(「データ・コントロール」パネルからデータ・コレクションとtreemapまたはsunburstコンポーネントをバインドするか、「コンポーネント」ウィンドウからコンポーネントを挿入して後からデータにバインドする)、ツリーマップあるいはサンバーストの初期レイアウトを定義できます。

サンバースト・コンポーネントには、図30-2に示す、1つのレイアウトしかありません。

ツリーマップ・コンポーネントのノードのレイアウトは構成可能で、次のタイプのレイアウトが含まれます。

- 正方形、ノードは可能なかぎり正方形となるように配置されます。
正方形レイアウトはユーザーが最も容易にノードの相対的なサイズが比較できるように最適化され、レイアウトは図30-1に示すように表示されます。

- スライスとダイス水平、ノードは最初ツリーマップの幅方向に沿い水平に配置され、ついで高さ方向に垂直に配置されます。
このレイアウトはノードの相対的な順序が一定に保たれるので、アニメーション用に最適化されます。図30-3は、スライスとダイス水平レイアウトでの、米国の国勢調査のサンプル・データを表示します。

図30-3 スライスとダイス水平レイアウトでの、米国国勢データを表示するツリーマップ

- スライスとダイス垂直、ノードは最初ツリーマップの高さ方向に沿い垂直に配置され、ついで幅方向に水平に配置されます。
このレイアウトも、ノードの相対的な順序が一定に保たれるので、アニメーション用に最適化されます。図30-4は、スライスとダイス垂直レイアウトでの、米国の国勢調査のサンプル・データを表示します。

図30-4 スライスとダイス垂直レイアウトでの、米国国勢データを表示するツリーマップ

30.1.2.2 属性グループ

ツリーマップとサンバーストは、データ・セット内での一意なグループの色などのスタイル属性値を生成するため、dvt:attributeGroupsタグの使用をサポートします。

ツリーマップとサンバーストにおいては、データの値が表示される色を決めます。どちらのコンポーネントも、連続的なデータをグラデーションから色を選択して表示し、ノードはデータの値に基づき徐々に色を変化させます。図30-1のツリーマップでは、データの値の範囲として所得の中間値を表示するのにグラデーションを使用しています。

離散データについても、ツリーマップとサンバーストはデータの値に基づき特定の色を表示します。図30-5は、所得の中間値の高低の区別に2色を使用して、米国の国勢調査の同じ人口データを示しています。

図30-5 離散属性グループを表示するツリーマップ

凡例サポートとノードの色とパターンのカスタマイズを容易にするために、属性グループの使用は必須です。

30.1.2.3 凡例サポート

ツリーマップとサンバーストは凡例をコンポーネントの下に表示し、サイズと色をコントロールしているデータのタイプを視覚的にわかりやすくします。コンポーネントが所得レベルなどの条件に基づき色を指定するのに属性グループを使用する場合、凡例は使用される色を表示し、各色がどの値を表現しているかを示すこともできます。

図30-5のツリーマップは、離散属性グループを使用するツリーマップの凡例を示します。凡例により、平均所得の高低を示すのにどの色が使用されているかの判断が容易になります。

Iツリーマップが連続属性グループを使用する場合、凡例はグラデーションとして使用される色を表示します。図30-1のツリーマップは、平均所得レベルを示すのに連続属性グループを使用するツリーマップの凡例を示します。

30.1.2.4 パターンのサポート

ツリーマップとサンバーストは、子ノードのfillPattern属性に値が指定されたとき、パターンを表示します。パターンは白のバックグラウンドで描かれ、fillColorの値がフォアグラウンドの色を決めます。

図30-6に、塗りつぶしパターンの組合せとして構成されたサンバーストを示します。

図30-6 塗りつぶしパターンを示すサンバースト

30.1.2.5 ノード選択のサポート

ツリーマップとサンバーストは、ユーザーによる1つ以上のノードへのクリックに反応して選択されたノードについての情報を表示する機能をサポートします。

図30-7に、複数選択サポートのために構成されたツリーマップを示します。

図30-7 複数選択サポートを示すツリーマップ

30.1.2.6 ツールチップのサポート

ツリーマップとサンバーストは、ユーザーがノード上でマウスを動かすとノードの追加情報を表示する機能をサポートします。

図30-8に、ユーザーがアラスカのノード上でマウスを動かしたときに表示されるツールチップを示します。

図30-8 ツールチップを表示するツリーマップ

ツールチップにより、視覚表示からでは明白ではない可能性のあるデータについての情報を、ユーザーは見ることができるようになります。ツールチップをツリーマップやサンバースト上に構成することは、コンポーネントの空間制約性の観点から推奨されます。

30.1.2.7 ポップアップのサポート

ツリーマップとサンバーストのコンポーネントは、ユーザーがノード上をマウスでクリックしたりホバーしたときに、情報を提供したり、入力を要求したりするポップアップのダイアログ、ウィンドウおよびメニューが表示されるように構成できます。図30-9に、ユーザーがツリーマップ・ノードの1つの上でマウスをホバーさせたときに表示される、ポップアップのサンプルを示します。

図30-9 マウス・ホバーによるツリーマップ・ポップアップ

図30-10に、ユーザーがサンバースト・ノードの1つの上でマウスをクリックしたときに表示される類似のポップアップ・ウィンドウを示します。

図30-10 マウス・クリックによるサンバースト・ポップアップ

30.1.2.8 コンテキスト・メニュー

ツリーマップとサンバーストは、コンテキスト・メニューを表示して選択されたノードについての追加情報を提供する機能をサポートします。図30-11に、ユーザーがサンバースト・ノードの1つの上で右クリックしたときに表示されるコンテキスト・メニューを示します。

図30-11 サンバースト・コンテキスト・メニュー

30.1.2.9 ドリルのサポート

ツリーマップおよびサンバースト・コンポーネントはドリルをサポートして、階層をナビゲートしノードについてのより詳細な情報を表示します。

図30-12に、ユーザーが図30-5のWest Regionのヘッダー・テキストをクリックしたときに表示されるツリーマップを示します。ユーザーは、United States > West Regionのブレッドクラム・リンクをクリックすることで、階層を上方にナビゲート・バックできます。

図30-12 グループ・ノード・ヘッダーでドリルしたツリーマップ

ユーザーは、図30-13に示すように、ノードをダブルクリックして階層のルートに設定することもできます。

図30-13 ノードでドリルしたツリーマップ

サンバースト上でドリルをするには、ユーザーはサンバースト上のノードをクリックし、図30-14に示すように階層のルートに設定します。ユーザーは、United States > West Regionのブレッドクラム・リンクをクリックするか、シフト・キーを押してWest Regionノードをダブルクリックすることにより、階層を上方にナビゲート・バックできます。

図30-14 ノード上でドリルしたサンバースト

サンバーストには、選択したノードの子を開いたり閉じたりする機能もあります。ユーザーは、開くノード上でマウスを動かしたときに現れる開くアイコンをクリックします。子を閉じるには、ユーザーは「縮小」アイコンをクリックします。

図30-15に、非同期ドリルのために構成されたサンバーストを示します。

図30-15 非同期ドリルのために構成されたサンバースト

30.1.2.10 その他のノード・サポート

ツリーマップおよびサンバースト・コンポーネントには、大きなコントリビュータとの比較において、ユーザーのデータ・モデルが多数の小さいコントリビュータを含む場合、データを集計する機能があります。

図30-16に、図30-5で表示された国勢調査ツリーマップに、その他のノードを構成したものを示します。この例では、South Atlantic地域のSouth Carolina、Delaware、West VirginiaおよびDistrict of Columbiaノードは、その他のノードとして表現されます。

図30-16 その他のノードを表示するツリーマップ

30.1.2.11ドラッグ・アンド・ドロップのサポート

ツリーマップおよびサンバーストのコンポーネントは、ドロップ・ソース、およびドロップ・ターゲットのいずれとしても、ドラッグ・アンド・ドロップをサポートします。

図30-17に、ドラッグ・ソースとして構成されたツリーマップを示します。ユーザーがノードの1つを右のテキストにドラッグすると、テキストはどのノードがドラッグされたかを反映して変化します。

図30-17 ドラッグ・ソースとして構成されたツリーマップ

図30-18に、ドロップ・ターゲットとして構成されたツリーマップを示します。ユーザーが右のテキストをノードの1つにドラッグすると、テキストはどのノードがテキストを受け取ったかを反映して変化します。

図30-18 ドロップ・ターゲットとして構成されたツリーマップ

30.1.2.12 ソートのサポート

ツリーマップおよびサンバースト・コンポーネントは、同じ親のノードをサイズによりソートして表示する機能をサポートしています。この機能はノードの比較を容易にするので、ユーザーのデータ・モデルがソートされていない場合に有用です。

図30-19にソートされたツリーマップを示します。ノードはサイズが減少する方向に配置され、どの地域が最も大きな人口を有するかがわかりやすくなります。

図30-19 ソートされたツリーマップ

注意:

ツリーマップはスライスとダイスのレイアウトにおいてのみソートをサポートします。

30.1.2.13 ツリーマップとサンバーストのイメージ形式

ツリーマップとサンバーストは、次のイメージ形式、すなわちHTML5、Flash、およびPNG (Portable Network Graphics)をサポートします。

デフォルトで、ツリーマップとサンバーストはクライアントのブラウザがサポートする、最良の出力形式で表示します。最良の出力形式をクライアントで使用できない場合、アプリケーションでは使用可能な形式がデフォルトになります。たとえば、クライアントがHTML5をサポートしていない場合、アプリケーションでは次が使用されます。

- Flash (Flash Playerが使用可能な場合)。
アプリケーション全体でFlashコンテンツの使用を制御するには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

- PNG出力形式。静的レンダリングは、PNG出力形式使用時には完全にサポートされますが、次のような一部のインタラクティブ機能は使用できません。

- アニメーション

- コンテキスト・メニュー

- ドラッグ・アンド・ドロップ・ジェスチャ

- ポップアップのサポート

- 選択項目

30.1.2.14 拡張ノード・コンテンツ

ツリーマップとサンバーストは、テキスト・ラベル内には通常入らないコンテンツを追加するため、ノード上にコンテンツ・ファセットを提供します。サンバーストでは、拡張コンテンツはルート・ノードに表示されます。ツリーマップでは、拡張コンテンツはリーフ・ノードに表示されます。

図30-20に、ルート・ノード上に拡張ノードを使用するサンバーストの例を示します。この例では、ルート・ノードはノード・テキストに加え、イメージとタイトルを表示します。

図30-20 拡張ルート・ノード・コンテンツを表示するサンバースト

図30-21に、拡張ノード・コンテンツを使用するツリーマップの例を示します。

図30-21 拡張ルート・ノード・コンテンツを表示するツリーマップ

注意:

拡張ノード・コンポーネントは、af:outputText、af:panelGroupLayout、af:spacerおよびaf:imageに限られます。拡張ノード・コンテンツの構成の詳細は、30.4.7項「ツリーマップとサンバーストの拡張ノード・コンテンツの構成」を参照してください。

30.1.2.15 印刷とメールのサポート

ADF Facesでは、印刷または電子メール用の簡略化されたモードで、ADF Faces WebアプリケーションからJSFページを出力できます。たとえば、ユーザーがページ(またはページの一部)を印刷できるようにし、ただしWebブラウザでレンダリングされているとおりにページを印刷するのではなく、スクロール・バーやボタンなど、印刷ページに必要ないアイテムを削除することができます。ページが電子メールで送信される場合は、電子メール・クライアントが正しく表示できるようにページを簡略化する必要があります。このような出力用に簡略化されたページを作成する場合の詳細は、第37章「様々な出力モードの使用」を参照してください。

30.1.2.16 ADS(アクティブ・データ・サポート)

ツリーマップとサンバーストは、アクティブ・データ・イベントが受け取られたときにPPR(部分ページ・リフレッシュ)リクエストを送ることによりADSをサポートします。PPRのレスポンスにより、コンポーネントが更新され、必要に応じて変更がアニメーション化されます。次のADSイベントがサポートされます。

- ノード・サイズの更新

- ノードの色の更新

- ノード・ラベルの更新

- ノードの挿入

- ノードの削除

- 拡張ノード・コンテンツ変更

アクティブ・データ・サービスの使用の詳細は、第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」を参照してください。

30.1.2.17 独立性のサポート(ツリーマップのみ)

ツリーマップは、表示されたデータのグループ内での比較にフォーカスするため、独立性をサポートします。ユーザーは、グループ・ヘッダー上でマウスを動かしたときに現れる「分離」アイコンをクリックし、グループを最大化します。

図30-22に、ユーザーがSouth Atlanticのグループ・ヘッダー上でマウスを動かしたときに現れる「分離」アイコンを示します。

図30-22 ツリーマップのグループ・ヘッダー上に表示される「分離」アイコン

図30-23に、ユーザーが図30-22のSouth Atlantic地区で「分離」アイコンをクリックしたときに表示されるツリーマップを示します。

ツリーマップを元の表示に戻すには、ユーザーは「リストア」アイコンをクリックします。

図30-23 グループで分離したツリーマップ

30.1.2.18 ツリーマップ・グループ・ノード・ヘッダーのカスタマイズ(ツリーマップのみ)

ツリーマップが複数レベルで表示されるとき、親レベルはグループ・ヘッダーで表示されます。デフォルトでは、グループ・ヘッダーは白のバックグラウンドで表示され、グループのタイトルは、左から右モードのときは左側揃えで配置され黒のテキストで表示されます。

図30-24に、ノード・ヘッダーのあるツリーマップの一部を示します。この例では、South RegionとSouth Atlanticのヘッダーは、デフォルト形式で形式化されている。

図30-24 デフォルトノード・ヘッダー形式を示すツリーマップ

ヘッダーをカスタマイズしてノードの色を使用したり、テキストの配置を変更したり、またフォントをカスタマイズしたりすることができます。

図30-25に、ノードの色を使用し、タイトルを中央に配置し、またフォントのサイズと色を変更するように形式化されたノード・ヘッダーを有する同じツリーマップを示します。

図30-25 形式されたグループ・ノード・ヘッダーを示すツリーマップ

この例では、所得レベルが$50,000より低いときはツリーマップ・ノードが赤で表示され、所得レベルが$50,000より高いときはツリーマップ・ノードが青で表示されます。各ノードの色の計算で使用されたものと同じルールから色が計算されるので、South Atlanticのノード・ヘッダーは青で表示されます。このケースでは、South Atlanticの区画に含まれる全ノードの所得レベルは$50,000より高いです。しかしながら、South Regionのノード・ヘッダーは、West South CentralおよびEast South Centralの区画も含むので、赤で表示されます。このケースでは、South Regionに含まれる全ノードの所得レベルは$50,000より低いです。

30.1.3 ツリーマップおよびサンバースト・コンポーネントの追加機能

ツリーマップやサンバースト・コンポーネントを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。また、ページにツリーマップまたはサンバーストを追加すると、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。ツリーマップおよびサンバースト・コンポーネントで使用できる他の機能へのリンクを次に示します。

- 部分ページ・レンダリング: ツリーマップまたはサンバーストをリフレッシュして、ページの別のコンポーネントで実行されたアクションに基づく新しいデータを表示できます。詳細は、第8章「部分ページ・コンテンツの再レンダリング」を参照してください。

- パーソナライズ: 有効化すると、ユーザーはツリーマップあるいはサンバーストの表示方法を実行中に変更できます。アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- スキンおよびスタイル: アプリケーションに適用するADFを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)を使用してCSSスタイル・プロパティを直接適用することにより、ピボット・テーブルおよびピボット・フィルタ・バー・コンポーネントの外観をカスタマイズできます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- アクセシビリティ: ツリーマップあるいはサンバースト・コンポーネントをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- タッチ装置: ADF Facesアプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- 自動データ・バインディング: アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADFビジネス・コンポーネントがどのように構成されているかに基づいて、自動的にバインドされたツリーマップおよびサンバーストを作成できます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「データバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成」の章を参照してください。

注意:

最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

さらに、データ視覚化コンポーネントでは、データの配信方法、自動部分ページ・レンダリング(PPR)、そしてデータの表示および編集方法など、同じ機能の大部分が共有されています。詳細は、22.2項「データ視覚化コンポーネントの共通機能」を参照してください。

30.2ツリーマップおよびサンバースト・コンポーネントの使用

ツリーマップおよびサンバースト・コンポーネントを使用するには、データを定義し、ツリーマップあるいはサンバーストをページに追加し、JDeveloperにおける追加の構成を完成させます。

30.2.1 ツリーマップとサンバーストのデータ要件

ツリーマップおよびサンバースト・コンポーネントには、1つ以上のディテール・コレクションと1つのマスター・ディテール・コレクションとの間にマスター/ディテール関係が存在するデータ・コレクションが必要です。どちらのコンポーネントも、ADF Faces ツリー・コンポーネントと同じデータ・モデルを使用します。ツリー・コンポーネントの詳細は、12.6項「ツリーでのデータの表示」を参照してください。

ツリーマップとサンバーストは、次の属性をJDeveloperに設定する必要があります。

- value:ノードのサイズ

- fillColor:ノードの色

- label:ノードのテキスト識別子

valueおよびlabel属性の値は、ツリーマップあるいはサンバーストのデータ・モデルに保存する必要があり、UI-first開発を使用の場合は、クラスまたはマネージドBeanに保存する必要があります。fillColor値は、データ・モデル、クラスおよびマネージドBeanで指定するか、「プロパティ」ウィンドウで宣言的に指定できます。

図30-26に、図30-1の中のツリーマップを生成するのに使用されるデータのサブセットを示します。これは、図30-2でサンバーストを生成するのに使用された同じデータです。

図30-26 ツリーマップとサンバーストのサンプル・データ

この例では、United Statesはルート・ノードで、以下3つの子レベルがあります。すなわち、region、divisionおよびstateです。

ツリーマップあるいはサンバーストの構成を正常に行うには、データが次のルールに従うことを確認してください。

- 各子ノードは、親ノードを1つのみ持つことができます。

- レベルをスキップすることはできません。

ツリーマップあるいはサンバーストのモデルをUI-first開発において作成するには、クラスとマネージドBeanを使用してツリー・ノードとツリー・モデルを定義し、ツリーにデータを移入し、かつツリーマップあるいはサンバースト構成の必要に応じ、追加のメソッドを追加します。

ツリーマップとサンバースト人口調査データの例で使用されるクラスおよびマネージドBeanを定義するサンプル・コードについては、F.3.1項「ツリーマップおよびサンバースト人口調査データ例のサンプル・コード」を参照してください。

30.2.2ツリーマップ・コンポーネントの使用

ツリーマップ・コンポーネントを使用するには、ツリーマップをページに追加し、JDeveloperにおける追加の構成を完成させます。

30.2.2.1ツリーマップの構成

ツリーマップ・コンポーネントは、ツリーマップの表示や動作をカスタマイズするために追加したり修正したりすることのできる構成可能な属性や子コンポーネントを持ちます。接頭辞dvt:は、各ツリーマップ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。

ツリーマップの子コンポーネント、属性およびサポートされているファセットを次のエリアで構成できます。

- ツリーマップ(dvt:treemap): ツリーマップ・ノードを折り返します。次の属性を構成してツリーマップの表示をコントロールします。

- ラベル: colorLabelおよびsizeLabel属性を使用してツリーマップの色とサイズのメトリックを特定します。ツリーマップには、これらのラベルが凡例表示に必要です。

- 凡例ソース(legendSource): この属性を、属性グループで構成されたツリーマップでの凡例表示に使用します。属性グループのIDを指定します。

- 子レベルの表示(displayLevelsChildren): 表示する子レベルの数を指定します。デフォルトでは、ツリーマップはルートと最初の2つの子レベルを表示します。

- アニメーション: animationOnDisplay属性を使用して初期のアニメーションをコントロールし、animationOnDataChange属性を使用してその後のアニメーションをコントロールします。アニメーション期間をデフォルトの500ミリ秒から変更するには、animationDuration属性を修正します。

- 空テキスト(emptyText): emptyText属性を使用して、ツリーマップ・ノードにデータが含まれない場合に表示するテキストを指定します。

- グループ・ギャップ(groupGaps): グループ間で表示するギャップを指定します。デフォルトでは、この属性はouterに設定されており、ツリーマップは外部ノード間のギャップのみを表示します。この属性をnoneに設定してすべてのギャップを取り除くことも、あるいはこの属性をallに設定してすべてのグループ間にギャップを追加することもできます。

- ソート(sorting): ツリーマップでスライスとダイスのレイアウトを使用する場合は、同じ親を持つ全ノードを、サイズが小さくなる方向にソートするのにこの属性を使用します。

- その他のグループ: otherThreshold、otherColorおよびotherPattern属性を使用して、子のデータをその他のノ－ドに集計します。

- ツリーマップ・ノード(dvt:treemapNode): ツリーマップ・コンポーネントの子。このタグはツリーマップの各ノードのサイズと色を定義し、データ・モデルでの各行にスタンプされます。行によりスタンプを変更する場合、ADF Faces af:switcherコンポーネントを使用し、各行にツリーマップ・ノードを挿入します。次の属性を構成してノードの表示をコントロールします。

- value (必須): ツリーマップ・ノードの値を指定します。この値はツリーマップ内のノードの相対的なサイズを決定します。

- fillColor (必須): ノードの塗りつぶしの色をRGB16進で指定します。この値は、ツリーマップを正しく表示するのにも必要です。

- fillPattern: オプションとして使用する塗りつぶしパターンを指定します。パターンは白のバックグラウンドで描かれ、フォアグラウンドの色はfillColor属性で指定された色を使用します。

- groupLabelDisplay: グループ・ラベルを表示する場所を指定します。デフォルトでは、この属性はheaderに設定されており、ラベルをグループ・ヘッダー上に表示します。これをoffに設定してラベル表示を消したり、nodeに設定してラベルをノード内に表示することもできます。

- label: ノードのラベルを指定します。

- labelDisplay: ノード・ラベルを表示する場所を指定します。デフォルトでは、この属性はnodeに設定され、ラベルをノード内部に表示しますが、offに設定してラベルの表示を消すこともできます。
labelHalign、labelStyleおよびlabelValign属性を設定することにより、ラベル表示をさらにカスタマイズできます。

- ツリーマップ・ノード・ヘッダー(dvt:treemapNodeHeader): ツリーマップ・ノードのオプションとしての子。この属性を追加して、次のノード・ヘッダーの属性を構成します。

- isolate: デフォルトでは、この属性はonに設定されていますが、offに設定して独立性のサポートを無効化することができます。

- labelStyle: フォント・スタイルを指定します。

- useNodeColor: デフォルトでは、この属性はoffに設定されています。ノードの色をヘッダーに表示するには、これをonに設定します。

- titleHalign: ヘッダーの中でタイトルを表示する場所を指定します。デフォルトではこの値はstartに設定され、左から右モードではタイトルを左揃えに配置し、右から左モードでは右揃えに配置します。

- 属性グループ(dvt:attributeGroup): ツリーマップ・ノードのオプションとしての子。この属性を追加し、fillColorおよびfillPatternの値を、データ・セットのカテゴリのバケットや連続的な種別に基づき自動的に生成します。

- サポートされるファセット: ツリーマップあるいはツリーマップ・ノードのオプションとしての子。ツリーマップ・コンポーネントはポップアップ・コンポーネントの表示のためにファセットをサポートし、ツリーマップのノード・コンポーネントは、ツリーマップ・ノードのラベルが十分でない場合に詳細を追加するための、コンテンツ・ファセットをサポートします。

ツリーマップは、他のDVTコンポーネントと同じ機能およびタグの多くも共有します。ツリーマップ・タグの完全なリストについては、Oracle ADF Facesデータ可視化ツール・タグ・リファレンスを参照してください。ツリーマップ・コンポーネントの追加機能の詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

30.2.2.2 ツリーマップをページに追加する方法

簡単なUI優先開発を使用してページを設計する場合は、「コンポーネント」ウィンドウを使用してツリーマップをJSFに追加してください。ツリーマップ・コンポーネントをページにドラッグ・アンド・ドロップすると、「ツリーマップの作成」ダイアログが表示されます。図30-27に、「ツリーマップの作成」ダイアログを示します。

図30-27 UI-First開発を使用する「ツリーマップの作成」ダイアログ

「OK」をクリックすると、ページにツリーマップが追加され、「プロパティ」ウィンドウを使用してデータ値を指定し、追加の表示属性を構成できます。または、作成の間にデータのバインドを選択でき、ダイアログを使用して関連するノード・データの構成ができます。

「プロパティ」ウィンドウで、プロパティ・フィールドにマウス・カーソルを合わせると表示されるアイコンをクリックすることで、プロパティの説明や編集オプションを表示できます。図30-28に、ツリーマップのvalue属性のドロップダウン・メニューを示します。

図30-28 ツリーマップの値の属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してツリーマップを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップを追加するには:

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「共通」パネルからツリーマップをページにドラッグ・アンド・ドロップし、「ツリーマップの作成」ダイアログを開きます。

2. 「ツリーマップの作成」ダイアログで、OKをクリックし、ツリーマップをページに追加します。
オプションで、そのダイアログを使用してデータを今すぐバインドを選択し、ツリーマップに表示するデータを表すADFデータ・コントロールをナビゲートして、ツリーマップをバインドします。このオプションを選択すると、ダイアログのデータ・バインディングのフィールドが編集のために使用可能になります。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 「プロパティ」ウィンドウに、ツリーマップの属性を表示します。ヘルプ・ボタンを使用して、ツリーマップ・コンポーネントのタグの完全なドキュメントを表示します。

4. 外観の項を開き、次の属性の値を入力します。

- レイアウト: この属性のドロップダウン・メニューを使用して、デフォルトのレイアウトをsquarifiedからsliceAndDiceHorizontalまたはsliceAndDiceVerticalに変更します。
ツリーマップ・レイアウトのサンプル・イメージについては、30.1.2.1項「ツリーマップとサンバーストのレイアウト」を参照してください。

- サマリー ツリーマップの目的およびスクリーン・リーダーで使用する場合の構造のサマリーを入力します。

30.2.2.3 ツリーマップをページに追加した場合の処理内容

「コンポーネント」ウィンドウからツリーマップをJSFページにドラッグ・アンド・ドロップし、生成中にデータ・バインドを選択しなかった場合は、JDeveloperはタグの最小セットしか生成しません。例30-1に、生成されるコードを示します。

例30-1 UI-First開発におけるツリーマップのサンプル・コード

<dvt:treemap id="t1">
<dvt:treemapNode id="tn1"/>
</dvt:treemap>

ツリーマップの作成時にデータとデータ・コントロールのバインドを選択した場合、JDeveloperはデータ・モデルに基づきコードを生成します。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

30.2.3 サンバースト・コンポーネントの使用

サンバースト・コンポーネントを使用するには、をサンバーストページに追加し、JDeveloperにおける追加の構成を完成させます。

30.2.3.1 サンバーストの構成

サンバースト・コンポーネントは、ツリーマップの表示や動作をカスタマイズするために追加したり修正したりすることのできる構成可能な属性や子コンポーネントを持ちます。接頭辞dvt:は、各ツリーマップ・コンポーネント名の先頭に付いて、そのコンポーネントがADFデータ視覚化ツール(DVT)のタグ・ライブラリに属することを示します。

サンバーストの子コンポーネント、属性およびサポートされているファセットを次のエリアで構成できます。

- サンバースト(dvt:sunburst): サンバースト・ノードを折り返します。次の属性を構成してサンバーストの表示をコントロールします。

- ラベル: colorLabelおよびsizeLabel属性を使用してサンバーストの色とサイズのメトリックを特定します。サンバーストには、これらのラベルが凡例表示に必要です。

- 凡例ソース(legendSource): この属性を、属性グループで構成されたサンバーストでの凡例表示に使用します。属性グループのIDを指定します。

- 子レベルの表示(displayLevelsChildren): 表示する子レベルの数を指定します。デフォルトでは、サンバーストはルートと最初の2つの子レベルを表示します。

- アニメーション: animationOnDisplay属性を使用して初期のアニメーションをコントロールし、animationOnDataChange属性を使用してその後のアニメーションをコントロールします。アニメーション期間をデフォルトの500ミリ秒から変更するには、animationDuration属性を修正します。

- ローテーション (rotation): クライアント側のサンバーストのローテーションを可能にするのにこの属性を使用します。

- 開始角度(startAngle): サンバーストの開始角度を指定します。

- 空テキスト(emptyText): emptyText属性を使用して、サンバースト・ノードにデータが含まれない場合に表示するテキストを指定します。

- ソート(sorting): ツリーマップでスライスとダイスのレイアウトを使用する場合は、同じ親を持つ全ノードを、サイズが小さくなる方向にソートするのにこの属性を使用します。

- その他のグループ: otherThreshold、otherColorおよびotherPattern属性を使用して、子のデータをその他のノ－ドに集計します。

- サンバースト・ノード(dvt:sunburstNode): サンバースト・コンポーネントの子。このタグはサンバーストの各ノードのサイズと色を定義し、データ・モデルでの各行にスタンプされます。行によりスタンプを変更する場合、ADF Faces af:switcherコンポーネントを使用し、各行にサンバースト・ノードを挿入します。次の属性を構成してノードの表示をコントロールします。

- value (必須): サンバースト・ノードの値を指定します。この値はサンバースト内のノードの相対的なサイズを決定します。

- fillColor (必須): ノードの塗りつぶしの色をRGB16進で指定します。この値は、サンバーストを正しく表示するのにも必要です。

- fillPattern: オプションとして使用する塗りつぶしパターンを指定します。パターンは白のバックグラウンドで描かれ、フォアグラウンドの色はfillColor属性で指定された色を使用します。

- label: ノードのラベルを指定します。

- labelDisplay: ノード・ラベルがどのようにを表示されるかを指定します。デフォルトでは、この属性はrotatedに設定され、ラベルをノード内部でローテーションして表示しますが、offに設定してラベルの表示を消したり、onに設定してノード内部で水平のラベルを表示したりすることもできます。

注意:

ローテーションしたテキストは、すべてのクライアント・テクノロジでサポートされているわけではありません。特に、ローテーションしたテキストは、Flashのイメージ形式を使用するクライアントでサポートされません。

- 属性グループ(dvt:attributeGroup): サンバースト・ノードのオプションとしての子。この属性を追加し、fillColorおよびfillPatternの値を、データ・セットのカテゴリのバケットや連続的な種別に基づき自動的に生成します。

- サポートされるファセット: サンバーストあるいはサンバースト・ノードのオプションとしての子。サンバースト・コンポーネントはポップアップ・コンポーネントの表示のためにファセットをサポートし、サンバーストのノード・コンポーネントは、サンバースト・ノードのラベルが十分でない場合に詳細を追加するための、コンテンツ・ファセットをサポートします。

サンバーストは、他のDVTコンポーネントと同じ機能およびタグの多くも共有します。サンバースト・タグの完全なリストについては、Oracle ADF Facesデータ可視化ツール・タグ・リファレンスを参照してください。サンバースト・コンポーネントの追加機能の詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

30.2.3.2 サンバーストをページに追加する方法

簡単なUI優先開発を使用してページを設計しているときには、「コンポーネント」ウィンドウを使用してサンバーストをJSFページに追加します。サンバースト・コンポーネントをページにドラッグ・アンド・ドロップすると、「サンバーストの作成」ダイアログが表示されます。図30-29に、「サンバーストの作成」ダイアログを示します。

図30-29 UI-First開発を使用する「サンバーストの作成」ダイアログ

「OK」クリックすると、ページにサンバーストが追加され、「プロパティ」ウィンドウを使用してデータ値を指定し、追加の表示属性を構成できます。または、作成の間にデータのバインドを選択でき、ダイアログを使用して関連するノード・データの構成ができます。

「プロパティ」ウィンドウで、各属性フィールドのドロップダウン・メニューを使用して、プロパティの説明、およびEL式ビルダーまたはその他の専用ダイアログの表示などのオプションを表示できます。図30-30に、サンバーストのvalue属性のドロップダウン・メニューを示します。

図30-30 サンバーストの値の属性のドロップダウン・メニュー

注意:

アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してサンバーストを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

始める前に:

サンバーストの属性やサンバーストの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにサンバーストを追加するには、

1. 「コンポーネント」ウィンドウの「ADFデータ視覚化」ページで、「共通」パネルからサンバースト・コンポーネントをページにドラッグ・アンド・ドロップし、「サンバーストの作成」ダイアログを開きます。

2. 「サンバーストの作成」ダイアログで、OKをクリックし、サンバーストをページに追加します。
オプションで、そのダイアログを使用して「データを今すぐバインド」を選択し、サンバーストに表示するデータを表すADFデータ・コントロールにナビゲートして、サンバーストをバインドします。このオプションを選択すると、ダイアログのデータ・バインディングのフィールドが編集のために使用可能になります。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

3. 「プロパティ」ウィンドウに、サンバーストの属性を表示します。ヘルプ・ボタンを使用して、sunburstコンポーネントの完全なタグ・ドキュメントを表示します。

4. その他の項を開き、次の属性の値を設定します。

- サマリー サンバーストの目的およびスクリーン・リーダーで使用する場合の構造を説明するテキストを入力します。または、属性のドロップダウン・メニューからテキスト・リソースの選択あるいは式ビルダーを選び、テキスト・リソースまたはEL式を選択します。

- ローテーション: ドロップダウン・メニューを使用して、サンバーストでローテーションを可能にするかどうかを指定します。デフォルトでは、この属性はonに設定されていますが、offに設定してローテーションのサポートを無効化することもできます。または、属性のドロップダウン・メニューから式ビルダーを選び、ローテーションを設定するEL式を作成します。

- StartAngle: サンバーストの開始角度を入力します。デフォルトでは、この角度は90に設定されていますが、0から360までの任意の値を入力できます。または、属性のドロップダウン・メニューから式ビルダーを選び、開始角度を設定するEL式を作成します。

30.2.3.3 ページへのサンバースト追加時の処理内容

「コンポーネント」ウィンドウからサンバーストをJSFページにドラッグ・アンド・ドロップし、生成中にデータ・バインドを選択しなかった場合は、JDeveloperはタグの最小セットしか生成しません。例30-2に、生成されるコードを示します。

例30-2 UI-First開発におけるサンバーストのサンプル・コード

<dvt:sunburst id="s1">
<dvt:sunburstNode id="sn1"/>
</dvt:sunburst>

サンバーストの作成時にデータとデータ・コントロールのバインドを選択した場合、JDeveloperはデータ・モデルに基づきコードを生成します。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

30.3 ツリーマップとサンバースト・コンポーネントへのデータの追加

UI-first開発を使用してツリーマップあるいはサンバーストにデータを追加するには、ツリー・モデルを作成してJDeveloperにおけるクラス、Beanあるいはメソッドを参照する、クラス、マネージドBean、およびメソッドを作成します。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

30.3.1 ツリーマップあるいはサンバースト・コンポーネントへのデータの追加方法

ツリーマップとサンバーストは同じデータ・モデルを使用しているので、ツリーマップとサンバーストにデータを追加するプロセスは類似しています。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップあるいはサンバーストを追加します。ページにツリーマップを追加する際のヘルプについては、30.2.2.2項「ツリーマップのページへの追加方法」を参照してください。ページにサンバーストを追加する際のヘルプについては、30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

UI-first開発においてツリーマップあるいはサンバースト・コンポーネントにデータを追加するには:

1. ツリーマップのツリー・モデルを定義しツリーマップにデータを供給するクラスおよびマネージドBeanを作成します。その他の詳細および例については、30.2.1項「ツリーマップとサンバーストのデータ要件」を参照してください。クラス作成のヘルプは、『Oracle Jdeveloperによるアプリケーションの開発』の「Javaコードの使用」の章を参照してください。マネージドBeanの詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

2. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、「外観」セクションで、DisplayLevelsChildren属性に値を入力し、ツリーマップに表示される子レベルの数を変更します。デフォルトでは、この値は2に設定されています。
たとえば、国勢調査データの例におけるツリーマップとサンバーストは、地域、地区および州の表現に3つの子レベルを持ち、この例を複製するには、この値を3に設定します。

4. 共通の項で、次の属性を設定します。

- Value: オブジェクトをツリーマップあるいはサンバーストのどちらにバインドするかを示すEL式を指定します。これは、org.apache.myfaces.trinidad.model.TreeModelのインスタンスである必要があります。
たとえば、ツリーマップあるいはサンバーストをインスタンス化するために作成したマネージドBeanを参照します。国勢調査のデータの例では、ツリーマップのマネージドBeanはtreemapと名付けられ、国勢調査のデータはそのツリーマップが参照されたときにインスタンス化されます。国勢調査のデータの例をツリーマップで使用するには、以下をEL式のValueフィールドに入力します。#{treemap.censusData}。

EL式の作成のヘルプについては、第3.5.1項「EL式の作成方法」を参照してください。

- Var: レンダリング・フェーズの間に使用される変数の名前を入力し、ツリーマップ・コレクションの各要素を参照します。この変数は、レンダリングが完了すると削除されるか、初期値に戻ります。
たとえば、国勢調査のデータの例での各要素を参照するため、rowをVarフィールドに入力します。

- VarStatus: オプションとして、レンダリング・フェーズの変数の名前を入力し、コレクション・モデルやループ・カウンタ情報など、コンポーネントの状態に関するコンテキスト情報にアクセスします。この変数は、レンダリングが完了すると削除されるか、初期値に戻ります。

5. 構造ウィンドウでdvt:treemapNodeノードまたはdvt:sunburstNodeを右クリックし、プロパティに移動を選択します。

6. 共通の項でValue属性のドロップダウン・メニューを使し、式ビルダーを選択してください。

7. 「式ビルダー」ダイアログで、ツリーマップあるいはサンバースト・ノードのサイズ・データを参照するEL式を作成し、このとき、ノードのサイズを戻すために作成したコンポーネントやメソッドの作成の際にVar属性に指定した変数を使用します。
たとえば、国勢調査のデータの例では、Var属性はrowと名付けられ、m_size変数に保存され、TreeNodeクラスのgetSize()メソッドにより返されます。これを、例F-3「ツリーマップあるいはサンバーストのツリー・ノード作成のためのコード・サンプル」に示します。国勢調査のデータの例におけるサイズ・データを参照するには、次の式を作成します。#{row.size}。

8. 「プロパティ」ウィンドウで、「外観」の項を開き、次の属性の値を入力します。

- FillColor: ノードの塗りつぶしの色を指定します。色をRGB16進で入力するか、属性のドロップダウン・メニューを使用して式ビルダーを選び、EL式を作成することができます。
たとえば、#FF0000を入力すればノード塗りつぶしの色を赤に設定できます。しかしながら、ツリーマップまたはサンバースト・ノードに、色メトリックに基づいた色変更をすることがあります。図30-1「米国の地域別人口と所得中央値を表示するツリーマップ」の国勢調査のデータの例では、塗りつぶしの色は所得データから計算されます。

例30-3に、国勢調査のデータ例使用したサンプルのメソッドを示します。式ビルダーでこのサンプルを参照するには、次の式を作成します。#{row.color}。

例30-3 ツリーマップあるいはサンバーストのノードの塗りつぶしの色を設定するサンプルのメソッド

import java.awt.Color;

private static Color getColor(double value, double min, double max) {
double percent = Math.max((value - min) / max, 0);
if(percent > 0.5) {
double modifier = (percent - 0.5) * 2;
return new Color((int)(modifier*102), (int)(modifier*153), (int)(modifier*51));
}
else {
double modifier = percent *2;
return new Color((int)(modifier*204), (int)(modifier*51), 0);
}
}

- Label: ノードのラベルを指定します。テキストを入力するか、属性のドロップダウン・メニューを使用して式ビルダーを選び、EL式を作成できます。
たとえば、国勢調査のデータの例では、ラベル表示のためにノード・データを文字列に変換するメソッドを使用しています。convertToString ()メソッドについては、例F-5「国勢調査データのツリーマップ設定のためのマネージドBeanの例」を参照してください。TreeNodeクラスはconvertToString()メソッドからの出力を使用し、ラベル表示に使用されるtext変数を設定します。式ビルダーでこのサンプルを参照するには、次の式を作成します。#{row.text}。

注意:

属性グループを使用してfillColorおよびlabel属性を設定することもできます。属性グループの使用はオプションですが、ツリーマップまたはサンバーストの色やパターンを所得の高低などの条件に基づいて変更する場合、使用する必要があります。属性グループの構成の詳細は、30.4.3.1項「ツリーマップおよびサンバーストの離散属性グループの構成方法」を参照してください。

30.3.2 ツリーマップおよびサンバーストへのデータ追加に関する必知事項

この章の例では、データをツリーマップおよびサンバーストに入力するのにクラスおよびマネージドBeanを使用します。アプリケーションでFusionテクノロジ・スタックが使用される場合、データ・コントロールを使用してサンバーストを作成でき、バインドが自動的に行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のデータバインドされた階層ビューア、ツリーマップおよびサンバースト・コンポーネントの作成に関する項を参照してください。

また、最終的にページのUIコンポーネントでADFデータ・バインディングが使用されることがわかっていても、データ・コントロールの準備ができる前にページを開発する必要がある場合は、手動でコンポーネントをバインドするのではなく、プレースホルダ・データ・コントロールを使用します。プレースホルダ・データ・コントロールを使用すると、開発済データ・コントロールを使用した場合と同じ宣言的な開発が行われます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のプレースホルダ・データ・コントロールを使用したページの設計に関する項を参照してください。

30.4 ツリーマップとサンバーストの表示要素のカスタマイズ

ツリーマップとサンバーストの表示要素は構成が可能で、これにはパターン、属性グループ、凡例、ラベル、アニメーション、小さいデータ・コントリビュータの集計、スキニング、サイジング、およびノードのサイズによる順序付けが含まれます。

30.4.1 ツリーマップとサンバーストの表示サイズとスタイルの構成

ツリーマップおよびサンバーストのサイズおよびスタイルを、inlineStyleあるいはstyleClass属性を使用して構成できます。どちらの属性も、「プロパティ」ウィンドウの「スタイル」セクションで、dvt:treemapあるいはdvt:sunburstコンポーネントで使用可能です。これらの属性を使用して、フォント、境界線、およびバックグラウンド要素など、スタイルに関する機能をカスタマイズできます。

ツリーマップとサンバーストは、コンポーネントのトップ・レベルだけでなく、ノード、ノード・ヘッダー、およびツリーマップを分離したりサンバーストを開いたり閉じたりするのに使用するアイコンについても、色やフォント・スタイルをカスタマイズするためのスキニングもサポートします。ユーザーがノードやノード・ヘッダーをマウスでホバーしたり選択したりしたときの、ツリーマップあるいはサンバーストのノード、あるいはツリーマップのノード・ヘッダーについて、スタイルを定義するためにもスキニングを使用できます。ノードやノード・ヘッダーがドリル可能である場合は、ユーザーがノードやノード・ヘッダーをマウスでホバーしたり選択したりしたときのスタイルを定義するためにスキニングを使用できます。

例30-4は、ユーザーがノードを選択したときにノードのテキストそれを太字で表示するように構成されたサンバーストのスキニング・キーを示します。

例30-4 ノードが選択されたときにフォントの重みを変えるスキニング・キー

af|dvt-sunburstNode::selected
{
-tr-font-weight: bold;
}

ツリーマップとサンバーストのスキニング・キーの完全なリストについては、Oracle Fusion Middleware Oracle ADF Facesスキン・セレクタ・データ視覚化ツール・タグ・リファレンスを参照してください。スキニングとスタイルを使用したアプリケーションのカスタマイズの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ツリーマップあるいはサンバーストを含むページには、サイズあるいはスタイルを変更する機能に制約のある場合があります。ページ・レイアウトの詳細は、第9章「Webページ上のコンテンツの編成」を参照してください。

30.4.2 パターン表示の構成

ツリーマップあるいはサンバースト・ノードがパターンを表示するように構成できます。利用可能なパターンは以下です。

- none (デフォルト)

- smallChecker

- smallCrosshatch

- smallDiagonalLeft

- smallDiagonalRight

- smallDiamond

- smallTriangle

- largeChecker

- largeCrosshatch

- largeDiagonalLeft

- largeDiagonalRight

- largeDiamond

- largeTriangle

ツリーマップあるいはサンバースト・ノードでのパターン表示を構成するには、fillPattern属性をdvt:treemapNodeあるいはdvt:sunburstNodeノード上で指定します。離散属性グループを使用して塗りつぶしパターンを指定することもできます。離散属性グループの詳細は、30.4.3.1項「ツリーマップおよびサンバーストの離散属性グループの構成方法」を参照してください。

30.4.3 ツリーマップとサンバーストの属性グループ

データ・セットのカテゴリ分類に基づいて色または形状などのスタイル属性値を生成するために属性グループを使用します。ツリーマップおよびサンバーストは、子ノードの色やパターンの設定のため、離散および連続の両方の属性グループをサポートします。

色やパターンを所得レベルの高低などの所定の条件に依存させたい場合には、離散属性グループを使用します。色を高低値の間で徐々に変化させたい場合には、連続属性グループを使用します。

30.4.3.1 ツリーマップとサンバーストの離散属性グループの構成方法

dvt:attributeGroupsタグをユーザーのツリーマップあるいはサンバーストに追加し、色またはパターンが表示される条件を定義することにより、離散属性グループを構成します。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

ツリーマップあるいはサンバーストの離散属性グループを構成するには、

1. 構造ウィンドウで「dvt:treemapNode」または「dvt:sunburstNode」ノードを右クリックし、「コンポーネント・ノードの中に挿入」→「属性グループ」を選択します。
たとえば、ツリーマップの離散属性グループを構成するには、「dvt:treemapNode」ノードを右クリックし、「ツリーマップ・ノードの中に挿入」→「属性グループ」を選択します。

2. dvt:attributeGroups要素を右クリックし、プロパティに移動を選択します。

3. 「プロパティ」ウィンドウで「外観」セクションを開きます。

4. Value属性のドロップダウン・メニューから、式ビルダーを選択し、色表示をコントロールする色メトリックと条件を参照する式を作成します。
たとえば、図30-5に示すように所得レベルの中間値が$50,000より高いか低いかでツリーマップに異なる色を表示させたい場合は、Valueフィールドに次の式と類似の式を作成します。

#{row.income > 50000}

EL式の作成のヘルプについては、第3.5.1項「EL式の作成方法」を参照してください。

5. Label属性のドロップダウン・メニューから、式ビルダーを選択し、離散色あるいはパターンが表すものを説明する凡例の式を作成します。
たとえば、色が所得レベルの中間値の高低を表すことをユーザーに知らせるには、次の式と類似の式をLabelフィールドに作成します。

#{row.income > 50000 ? 'High Income' : 'Low Income'}

6. タイプ属性のドロップダウン・メニューから、編集を選択します。

7. 「属性の編集」ダイアログから、色、パターン、あるいは両方を選び、OKをクリックします。
色とパターンの両方を選び、即時にページを作成する場合、ツリーマップあるいはサンバーストは離散属性グループにデフォルトの色およびパターンを使用します。

例30-31に、国勢調査のデータ例で,デフォルトの色とパターンを受け入れた場合に表示されるツリーマップを示します。

図30-31 デフォルトの色とパターンのツリーマップ離散属性グループ

8. オプションとして、属性グループのデフォルトの色を変更するには、以下を実行します。

1. 構造ウィンドウでdvt:attributeGroups要素を右クリックし、「属性グループの中に挿入」→属性合致ルールを選択します。

dvt:attributeMatchRuleタグは、データが所定の条件に合致したときに属性を置き換えるのに使用されます。国勢調査データの例では、この条件は$50,000より高い所得の中間値です。

2. dvt:attributeMatchRule要素を右クリックし、プロパティに移動を選択します。

3. 「グループ」フィールドで、条件がTrueのときにその色を表示する場合はtrueを入力し、条件がFalseのときにその色を表示する場合はfalseを入力します。
たとえば、国勢調査データの例で所得の中間値が50000より高いときに表示する色を選ぶには、trueを入力します。

4. 構造ウィンドウでdvt:attributeMatchRule要素を右クリックし、「一致ルールの中に挿入」→「属性」を選択します。

5. 「属性を挿入」ダイアログで、colorを「名前」フィールドに入力し、色を「値」フィールドに入力し、「OK」をクリックします。

値のフィールドは、6桁のRGB16進値を受け入れます。たとえば、値を緑に設定するには、valueフィールドに以下を入力します。#00AA00。

6. 残りの半分の条件についてデフォルトの色を変更する場合、ステップ1からステップ5を繰り返します。
たとえば、所得が50000より低い場合に表示する色を定義する別の合致ルールを定義し、Groupフィールドをfalseに設定します。

9. オプションとして、属性グループのデフォルトのパターンを変更するには、以下を実行します。

1. 構造ウィンドウでdvt:attributeGroups要素を右クリックし、「属性グループの中に挿入」→属性合致ルールを選択します。

2. dvt:attributeMatchRule要素を右クリックし、プロパティに移動を選択します。

3. 「グループ」フィールドで、条件がTrueのときにそのパターンを表示する場合はtrueを入力し、条件がFalseのときにそのパターンを表示する場合はfalseを入力します。

4. 構造ウィンドウでdvt:attributeMatchRule要素を右クリックし、「属性一致ルールの中に挿入」→「属性」を選択します。

5. 「属性の挿入」ダイアログで、patternを「Name」フィールドに入力し、サポートされているパターンを「Value」フィールドに入力し、「OK」をクリックします。

たとえば、「Value」フィールドにsmallDiamondを入力し、パターンを小ダイヤモンドにします。利用可能なパターンのリストついては、30.4.2.項「パターン表示の構成」を参照してください。

6. 残りの半分の条件についてデフォルトの色を変更する場合、ステップ1からステップ5を繰り返します。
たとえば、所得が50000より低い場合に表示する色を定義する別の合致ルールを定義し、Groupフィールドをfalseに設定します。

例30-5に、図30-5「離散属性グループを表示するツリーマップ」で示したツリーマップで離散属性グループを構成した場合のJSFページ上のコードを示します。

例30-5 離散属性グループのJSFページ上のサンプル・コード

<dvt:treemap id="t1" summary="SampleTreemap" value="#{treemap.censusData}"
var="row" colorLabel="Median Household Income" sizeLabel="Population"
displayLevelsChildren="3" emptyText="No Data to Display"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}">
<dvt:attributeGroups id="ag1" value="#{row.income > 50000}"
label="#{row.income > 50000 ? 'High Income' : 'Low Income'}"
type="color">
<dvt:attributeMatchRule id="amr1" group="true">
<f:attribute name="color" value="#00AA00"/>
</dvt:attributeMatchRule>
<dvt:attributeMatchRule id="amr2" group="false">
<f:attribute name="color" value="#AA0000"/>
</dvt:attributeMatchRule>
</dvt:attributeGroups>
<f:facet name="content"/>
</dvt:treemapNode>
</dvt:treemap>

30.4.3.2 ツリーマップとサンバーストの連続属性グループの構成方法

dvt:attributeGroupsタグをユーザーのツリーマップあるいはサンバーストに追加し、データの範囲の最小および最大レベルで表示される色を定義することにより、連続属性グループを構成します。属性グループはデータを使用してデータ範囲を決め対応する値で凡例にラベルを表示しますが、異なる範囲やラベルを使用するように属性グループを構成することもできます。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

ツリーマップあるいはサンバーストの連続属性グループを構成するには、

1. 構造ウィンドウで「dvt:treemapNode」または「dvt:sunburstNode」ノードを右クリックし、「コンポーネント・ノードの中に挿入」→「属性グループ」を選択します。
たとえば、ツリーマップの連続属性グループを構成するには、dvt:treemapNodeノードを右クリックし、「ツリーマップ・ノードの中に挿入」→「属性グループ」を選択します。

2. dvt:attributeGroups要素を右クリックし、プロパティに移動を選択します。

3. 「プロパティ」ウィンドウで「外観」セクションを開きます。

4. 「値」属性のドロップダウン・メニューから、「式ビルダー」を選択し、色メトリックを参照する式を入力します。
たとえば、国勢調査の例から所得データを返すEL式を指定するには、「式ビルダー」を選び、次の値をValueフィールドに入力します。#{row.income}。EL式の作成のヘルプについては、第3.5.1項「EL式の作成方法」を参照してください。

5. 「タイプ」フィールドには、colorを入力します。

6. 「属性タイプ」フィールドでは、属性のドロップダウン・メニューを使用して、continuousを選択します。

7. オプションとして、次の最小あるいは最大の範囲、およびラベルに値を設定します。

- MinValue: 範囲の最小の境界を入力します。または、属性のドロップダウン・メニューから式ビルダーを選び、最小の境界を返す式を入力します。
たとえば、35000をMinValueフィールドに入力し、範囲の低い方の境界を35,000に設定します。

- MaxValue: 範囲の最大の境界を入力します。または、属性のドロップダウン・メニューから式ビルダーを選び、最大の境界を返す式を入力します。

- MinLabel: 凡例で表示する最小値のラベルを入力します。または、属性のドロップダウン・メニューからテキスト・リソースの選択あるいは式ビルダーを選び、テキスト・リソースまたはEL式を選択します。
たとえば、$35000をMinLabelフィールドに入力し、凡例に表示されるラベルを$35000に設定します。

- MaxLabel: 凡例で表示する最大値のラベルを入力します。または、属性のドロップダウン・メニューからテキスト・リソースの選択あるいは式ビルダーを選び、テキスト・リソースまたはEL式を選択します。

8. 最小および最大の境界で使用される色を定義するには、以下を実行します。

1. 構造ウィンドウでdvt:attributeGroups要素を右クリックし、「属性グループの中に挿入」→「属性」を選択します。

2. 「属性を挿入」ダイアログでcolor1を最小の境界の名前と値に入力し、OKをクリックします。
値のフィールドは、6桁のRGB16進値を受け入れます。たとえば、最小の境界の値を黒に設定するには(この色は図30-1の属性グループで使用された色)、valueフィールドに以下を入力します。#000000。

3. 構造ウィンドウでdvt:attributeGroups要素を右クリックし、「属性グループの中に挿入」→「属性」を選択します。

4. 「属性を挿入」ダイアログでcolor2を最大の境界の名前と値に入力し、OKをクリックします。
値のフィールドは、6桁のRGB16進値を受け入れます。たとえば、最大の境界の値を薄い緑に設定するには(この色は図30-1の属性グループで使用された色)、valueフィールドに以下を入力します。#00AA00。

図30-0に、図30-1に示した連続属性グループを構成した場合のJSFページ上のコードを示します。

例30-6 連続属性グループのJSFページ上のサンプル・コード

<dvt:treemap id="t1" summary="SampleTreemap" value="#{treemap.censusData}"
var="row" colorLabel="Median Household Income" sizeLabel="Population"
displayLevelsChildren="3" emptyText="No Data to Display"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}">
<dvt:attributeGroups id="ag1" value="#{row.income}" type="color"
attributeType="continuous" minValue="35000"
maxValue="70000" minLabel="$35000" maxLabel="$70000">
<f:attribute name="color1" value="#000000"/>
<f:attribute name="color2" value="#00AA00"/>
</dvt:attributeGroups>
<f:facet name="content"/>
</dvt:treemapNode>
</dvt:treemap>

30.4.3.3 属性グループの構成に関する必知事項

Otherノードを使用して表示のためにノードを集計する場合、Otherノードは構成された属性グループの色やパターンを使用しません。詳細は、30.4.5.2項「ツリーマップおよびサンバーストのその他のノードの構成に関する必知事項」を参照してください。

30.4.4 ツリーマップとサンバーストの凡例の構成方法

次の属性の値を指定すると、凡例は自動的に表示されます。

- sizeLabel: コンポーネントのサイズ・メトリックを説明するテキストを指定します。または、属性のドロップダウン・メニューから「テキスト・リソースの選択」または「式ビルダー」を選択し、テキスト・リソースまたはEL式を選択します。

- colorLabel: コンポーネントの色メトリックを説明するテキストを指定します。または、属性のドロップダウン・メニューから「テキスト・リソースの選択」または「式ビルダー」を選択し、テキスト・リソースまたはEL式を選択します。

- legendSource: オプションとして、ツリーマップあるいはサンバーストの表示で使用される属性グループのIDを指定します。
ユーザーのツリーマップあるいはサンバーストが属性グループを使用しない場合は、凡例の表示はユーザーがサイズと色ラベルに指定したテキスト記述に限定されます。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

ツリーマップあるいはサンバーストの凡例を構成するには、

1. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。

3. SizeLabelフィールドに、サイズ・メトリックを説明するために凡例が表示するテキストを入力します。
たとえば、人口をSizeLabelフィールドに入力し、ツリーマップあるいはサンバーストのノードのサイズは人口に基づいていることを示します。

ドロップダウン・メニューを使用して、テキスト・リソース、あるいは「式ビルダー」ダイアログからEL式を選択します。たとえば、国勢調査の例からサイズを返すEL式を指定するには、式ビルダーを選び、次の値をSizeLabelフィールドに入力します。#{row.size}。EL式の作成のヘルプについては、第3.5.1項「EL式の作成方法」を参照してください。

4. ColorLabelフィールドに、色メトリックを説明するために凡例が表示するテキストを入力します。
たとえば、家計所得の中間値をColorLabelフィールドに入力し、ツリーマップあるいはサンバーストのノードのサイズは人口に基づいていることを示します。

またはドロップダウン・メニューを使用してテキスト・リソースを入力するか、式ビルダーから式を選択します。たとえば、国勢調査の例から色を返すEL式を指定するには、式ビルダーを選び、次の値をColorLabelフィールドに入力します。#{color.size}。

5. ユーザーのツリーマップあるいはサンバーストが属性グループを使用する場合は、次のようにattributeGroupsコンポーネントのIDを参照します。

1. LegendSource属性のドロップダウン・メニューから、編集を選択します。

2. 「プロパティの編集 - LegendSource」ダイアログで、各コンポーネントを開き、attributeGroupsコンポーネントを見つけます。

3. attributeGroupsコンポーネントを選び、OKをクリックします。

30.4.5 ツリーマップとサンバーストのその他のノードの構成

その他のノードを、小さなデータ・セットを1つの大きなセットに集計し、比較を容易にするのに使用します。

30.4.5.1 ツリーマップとサンバーストのその他のノードの構成方法

ツリーマップのその他のノードを、次の属性の値を設定して構成します。

- OtherThreshold: その下でノードがその他のノードに集計される、親ノードのパーセンテージを指定します。有効な値は0から1の範囲です。
たとえば、0.1の値により、親の10%未満のすべてのノードがその他のノードに集計されます。図30-16では、otherThresholdは.08すなわち8パーセントに設定され、これによりSouth Carolina、Delaware、West VirginiaおよびDistrict of ColumbiaノードをSouth Atlantic地域に集計します。

この値を.1あるいは10%に増やすと、Marylandノードが集計に追加されます。図30-32に、otherThreshold属性が.1に設定された、同じツリーマップを示します。

図30-32 otherThresholdが10パーセントに設定されたその他のノードを表示するツリーマップ

- OtherColor: 現在のその他のノードに含まれるすべてのノードのRowKeySetを受け取り、その他のノードの色のStringを返すメソッドへの参照を指定します。
たとえば、国勢調査のデータの例では、その他のノードに含まれる全ノードの所得の中間値を計算するメソッドを使用しています。家計所得の中間値が50,000未満の場合は、メソッドは低所得を表示するのに使用された、ツリーマップの集計されなかったノードと同じ色の値を返します。その他のノード上の色が図30-32でどのように変化し、Marylandノードがその他のノードに含まれるとき、高い所得の中間値を反映するかに注意してください。

例30-7に、国勢調査のデータ例で所得の中間値に基づきotherColorの値を指定するサンプルのメソッドを示します。

例30-7 ツリーマップのotherColorの値を設定するサンプルのメソッド

import org.apache.myfaces.trinidad.model.RowKeySet;
import org.apache.myfaces.trinidad.model.TreeModel;

public String otherColor(RowKeySet set) {
// The color should be the mean income of the contained regions.  Note that it should actually
// be the median, but we can't calculate that with the available information.
TreeModel tree = getCensusRootData();
// Loop through and get the population + average income
double population = 0;
double average = 0;
for(Object rowKey : set) {
CensusData.CensusTreeNode item = (CensusData.CensusTreeNode) tree.getRowData(rowKey);
population += item.getSize().doubleValue();
average += item.getSize().doubleValue() * item.getIncome();
}
// Calculate the average
average = average / population;
// Match the attr groups used by the demos
return average > 50000 ? "#CC3300" : "#003366";
}

- OtherPattern: オプションで、現在のその他のノードに含まれるすべてのノードのRowKeySetを受け取り、その他のノードのパターンのStringを返すメソッドへの参照を指定します。
例30-8に、その他のノードの塗りつぶしパターンをsmallDiamondに設定するメソッドのサンプル・コードを示します。

例30-8 ツリーマップあるいはサンバーストのotherPatternの値を設定するサンプル・メソッド

import org.apache.myfaces.trinidad.model.RowKeySet;
public String otherPattern(RowKeySet rowKeySet) {
return "smallDiamond";
}

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- 現在のその他のノードに含まれるすべてのノードのRowKeySetを受け取り、その他のノードの色のStringを返すメソッドを作成します。
米国国勢調査のデータの例を使用するには、例30-7のサンプル・メソッドをマネージドBeanに追加します。

マネージドBeanについてのヘルプが必要な場合、3.6項「マネージドBeanの作成と使用」を参照してください。

- オプションとして、現在のその他のノードに含まれるすべてのノードのRowKeySetを受け取り、その他のノードのパターンのStringを返すメソッドを作成します。
米国国勢調査のデータの例を使用するには、例30-8のサンプル・メソッドをマネージドBeanに追加します。

otherColorノードをツリーマップあるいはサンバーストに追加するには、

1. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「その他」セクションを開き、次の属性の値を入力します。

- OtherThreshold: 集計の対象とするノードのパーセンテージを、0から1の間の値で入力します。

- OtherColor: ドロップダウン・メニューから編集を選び、マネージドBeanとotherColor属性を設定するメソッドを選択します。
たとえば、treemapという名前のマネージドBeanとotherColorという名前のメソッドには、OtherColorフィールドに、以下を入力します。#{treemap.otherColor}。

- OtherPattern: ドロップダウン・メニューから編集を選び、マネージドBeanとotherPattern属性を設定するメソッドを選択します。
たとえば、treemapという名前のマネージドBeanとotherPatternという名前のメソッドには、OtherPatternフィールドに、以下を入力します。#{treemap.otherPattern}。

30.4.5.2 ツリーマップおよびサンバーストのその他のノードの構成に関する必知事項

その他のノードは個々のノードの集計であるため、子、属性グループ、選択、ツールチップ、およびポップアップ・サポートを管理するとき、他のツリーマップおよびサンバ－ストの子ノードとは、動作が異なります。特に、次の相違点を知っておく必要があります。

- 子ノード: 集計されたノードの子は表示されません。

- その他のノード表示と属性グループ: 色やパターンの指定に属性グループを使用している場合、その色やパターンはその他のノード上には表示されません。その他のノードに属性グループと同じ色やパターンを表示する場合、表示する色やパターンを返すメソッドをマネージドBeanに作成する必要があります。

- 選択の動作: その他のノードは、ノード選択サポートをデフォルト値の複数選択から単一ノード選択に変更している場合、選択できません。

- ツールチップ: ツールチップはその他のノード内のノードの数を表示し、カスタマイズできません。

- ポップアップ: デフォルトでは、ポップアップはその他のノード上に表示されません。
ユーザーがノード上でポップアップを立ち上げると、そのノードはコンポーネント(とそのモデル)上で現在となり、アプリケーションによるコンテキストの決定が可能になります。ツリーマップとサンバーストは、af:showPopupBehaviorタグをコンテキスト決定のために使用しますが、このタグは複数のノードを現在にすることをサポートしていません。ツリーマップあるいはサンバーストにその他のノード上でポップアップを表示させたい場合は、getPopupContext()メソッドをUITreemapまたはUISunburstコンポーネント上で呼ぶメソッドをマネージドBean内に作成し、集計されたノードのコンテキストを決定する必要があります。

30.4.6 ツリーマップとサンバーストのソートの構成

ソートは、ユーザーのツリーマップかサンバーストがその他のノードを使用する場合は、デフォルトで有効化されています。そうでない場合は、dvt:treemapあるいはdvt:sunburst sorting属性を、「プロパティ」ウィンドウでonに設定して有効化する必要があります。

ツリーマップはスライスとダイスのレイアウトにおいてのみソートをサポートします。

30.4.7 ツリーマップとサンバーストの拡張ノード・コンテンツの構成

ツリーマップあるいはサンバースト・ノード上のコンテンツ・ファセットを定義することにより、拡張ノード・コンテンツを構成します。

ツリーマップとサンバーストのいずれも、次のOracleアプリケーション開発フレームワーク・タグをサポートします。

- af:image

- af:outputText

- af:panelGroupLayout

- af:spacer

レイアウト上の理由により単一の子しかサポートされず、複数の子コンポーネントを折り返すには、af:panelGroupLayoutを使用する必要があります。このファセット内のコンポーネントには、対話型の動作もサポートされません。

30.4.7.1 拡張ノード・コンテンツをツリーマップに追加する方法

dvt:treemapNodeノード上でcontentファセットを定義することにより、ツリーマップ上の拡張ノード・コンテンツを構成します。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップを追加します。詳細は、30.2.2.2項「ページにツリーマップを追加する方法」を参照してください。

拡張ノード・コンテンツをツリーマップに追加するには、

1. 構造ウィンドウで、dvt:treemapNodeを開きます。

2. ファセットを構造ウィンドウで構成するには、f:facet - contentノードを右クリックし、「f:facet - contentの中に挿入」に次の1つを選びます。

- イメージ

- 出力テキスト

- パネル・グループ・レイアウト

- スペーサ
1つ以上のコンポーネントを挿入するには、パネル・グループ・レイアウトを選び、ユーザーのアプリケーションの必要に応じてイメージ、出力テキスト、あるいはスペーサを追加します。パネル・グループ・レイアウト構成に関するヘルプについては、9.13.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

イメージおよび出力テキスト構成上のヘルプについては、第18章「出力コンポーネントの使用方法」を参照してください。

30.4.7.2 拡張ノード・コンテンツをサンバーストに追加する方法

dvt:sunburstNodeノード上でrootContentファセットを定義することにより、ツリーマップ上の拡張ノード・コンテンツを構成します。

始める前に:

サンバーストの属性やサンバーストの子タグが機能に影響を与える可能性について理解しておくと役立ちます。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにサンバーストを追加します。詳細は、30.2.3.2項「ページにサンバーストを追加する方法」を参照してください。

拡張ノード・コンテンツをサンバーストに追加するには、

1. 構造ウィンドウで、dvt:sunburstノードを展開します。

2. ファセットを構造ウィンドウで構成するには、f:facet - contentノードを右クリックし、「f:facet - rootContentの中に挿入」に次の1つを選びます。

- イメージ

- 出力テキスト

- パネル・グループ・レイアウト

- スペーサ
1つ以上のコンポーネントを挿入するには、パネル・グループ・レイアウトを選び、ユーザーのアプリケーションの必要に応じてイメージ、出力テキスト、あるいはスペーサを追加します。パネル・グループ・レイアウト構成に関するヘルプについては、9.13.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

イメージおよび出力テキスト構成上のヘルプについては、第18章「出力コンポーネントの使用方法」を参照してください。

30.4.7.3 ツリーマップ上の拡張ノード・コンテンツの構成に関する必知事項

ツリーマップはサイズと色を使用してデータの2つの次元を表示するように作られています。ノード・コンテンツは、ラベルやイメージなどにより、ツリーマップ・ノードを特定するのに使用するべきであり、データの多くの追加の次元を表示するのに依存すべきではありません。アプリケーションでは、ツリーマップ・ノードのようなアスペクト・レシオや小サイズの問題がないので、追加のコンテンツにはポップアップの使用を考えます。

30.4.8 ツリーマップとサンバーストでのアニメーションの構成方法

ツリーマップとサンバーストは、複数のタイプのアニメーションをサポートします。デフォルトではアニメーションは表示されませんが、アニメーションをツリーマップあるいはサンバーストに、最初に表示されるときに追加できます。コンポーネント上でデータ変更が発生したとき、アニメーション効果のカスタマイズができます。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

ツリーマップあるいはサンバーストにアニメーション効果を追加するには、

1. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「外観」の項を開き、次の属性の値を入力します。

- AnimationDuration: アニメーションの継続時間をミリ秒単位で指定します。デフォルト値は500です。データ変更については、アニメーションは段階別に発生し、アニメーションの各段階でデフォルトの値は500です。

- AnimationDisplay: ドロップダウン・メニューを使用し、コンポーネントが最初にレンダリングされたときに適用するアニメーションのタイプを指定します。デフォルトでは、noneに設定されています。

- AnimationOnDataChange: ドロップダウン・メニューを使用し、ツリーマップかサンバーストでデータが変更されたときに適用するアニメーションのタイプを指定します。デフォルトでは、アクティブ・データ・サービスのデータ変更イベントのため、activeDataに設定されています。
ツリーマップおよびサンバーストでは、部分ページ・リフレッシュおよびアクティブ・データ・サービス・イベントの両方にアニメーションを適用するので、autoタイプが推奨されます。

表30-1に、サポートされているアニメーション効果のリストを示します。

表30-1 ツリーマップとサンバーストのアニメーション効果

アニメーション効果

AnimationOnDisplay

AnimationOnDataChange

none

x

x

activeData

x

alphaFade

x

x

auto

x

cubeToLeft

x (ツリーマップのみ)

cubeToRight

x (ツリーマップのみ)

fan

x (サンバーストのみ)

flipLeft

x (サンバーストのみ)

flipRight

x (サンバーストのみ)

slideToLeft

x

slideToRight

x

transitionToLeft

x

transitionToRight

x

zoom

x

x

30.4.9 ツリーマップとサンバーストでのラベルの構成

ツリーマップとサンバーストは、次の要素についてラベル表示のカスタマイズをサポートします。

- colorLabelおよびsizeLabel: これらのラベルは凡例表示に使用されます。これらのラベルの構成の詳細は、30.4.4項「ツリーマップおよびサンバーストの凡例の構成方法」を参照してください。

- treemapNodeHeader: ツリーマップ・ノード・ヘッダーに表示されるタイトルは構成可能です。ツリーマップ・ノード・ヘッダー・タイトルのカスタマイズの構成の詳細は、30.4.10項「ツリーマップ・ノード・ヘッダーとグループ・ギャップ表示の構成」を参照してください。

- ノード・ラベル: ツリーマップとサンバーストの両方で、ノード・ラベルのサイズ、スタイルおよび表示を構成できます。レイアウトの違いにより、構成のオプションがコンポーネント間でわずかに異なります。

30.4.9.1 ツリーマップ・リーフ・ノード・ラベルの構成方法

ツリーマップ・ノード上のラベル属性を定義することにより、ツリーマップ・ノード・ラベルを構成します。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップを追加します。詳細は、30.2.2.2項「ページにツリーマップを追加する方法」を参照してください。

ツリーマップ・リーフ・ノードを構成するには:

1. 構造ウィンドウで、dvt:treemapNodeノードを右クリックし、プロパティに移動を選択します。

2. 「プロパティ」ウィンドウで、「外観」の項を開き、次の属性の値を入力します。

- ラベルの表示: ドロップダウン・メニューを使用して、ラベルをリーフ・ノード上で表示するかどうかを指定します。デフォルトはnodeで、ラベルをリーフ・ノードの内部に表示します。ラベル表示を消すには、offを選択します。

- LabelHalign: ドロップダウン・メニューを使用して、ノード内に表示されるラベルの水平方向の配置を指定します。デフォルトの値はcenterです。左から右モードではタイトルを左揃えに配置し、右から左モードでは右揃えに配置するには、この値をstartに設定します。この値をendに設定し、左から右モードではタイトルを右揃えに配置し、右から左モードでは左揃えに配置することもできます。

- LabelValign: ドロップダウン・メニューを使用して、ノード内に表示されるラベルの垂直方向の配置を指定します。デフォルトの値はcenterです。これを、topあるいはbottomに変更できます。

- LabelStyle: ヘッダー内に表示されるラベルのフォント・スタイルを指定します。この属性は、font-sizeやcolorなど、CSSスタイル属性を受け入れます。
たとえば、タイトルのサイズを14ピクセルに変え、色を白に変えるには、次の値をLabelStyleに入力します。

font-size:14px;color: #FFFFFF

CSS属性の完全なリストについては、次のアドレスのWorld Wide Web ConsortiumのWebサイトを参照してください。

http://www.w3.org/TR/CSS21/

- GroupLabelDisplay: ドロップダウン・メニューを使用して、グループ・ノードのラベル表示の動作を指定します。デフォルトの値はheaderで、グループ・ノード・ラベルをノード・ヘッダーに表示します。これをoffに設定でき、またnodeに設定してラベルをノード内に表示することもできます。

30.4.9.2 サンバースト・ノード・ラベルの構成方法

サンバースト・ノード上のラベル属性を設定することにより、サンバースト・ノード・ラベルを構成します。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにサンバーストを追加します。詳細は、30.2.3.2項「ページにサンバーストを追加する方法」を参照してください。

サンバースト・ノード・ラベルを構成するには、

1. 構造ウィンドウで、dvt:sunburstNodeノードを右クリックし、プロパティに移動を選択します。

2. 「プロパティ」ウィンドウで、「外観」の項を開き、次の属性の値を入力します。

- LabelStyle: ヘッダー内に表示されるラベルのフォント・スタイルを指定します。この属性は、font-sizeやcolorなど、CSSスタイル属性を受け入れます。
たとえば、タイトルのサイズを14ピクセルに変え、色を白に変えるには、次の値をLabelStyleに入力します。

font-size:14px;color: #FFFFFF

CSS属性の完全なリストについては、次のアドレスのWorld Wide Web ConsortiumのWebサイトを参照してください。

http://www.w3.org/TR/CSS21/

- LabelDisplay: ドロップダウン・メニューを使用して、ノードのラベル表示を指定します。デフォルトの値はrotatedで、クライアント環境がローテートしたテキストをサポートしていれば、ノード内でローテートしたラベルを表示します。これをoffに設定してラベル表示を消したり、onに設定してノード内でラベルを水平に表示することもできます。

注意:

labelDisplay属性がrotatedに設定され、クライアントの環境がローテートしたテキストをサポートしていない場合は、サンバーストはノード内でラベルを水平に表示します。

30.4.10 ツリーマップ・ノード・ヘッダーとグループ・ギャップの構成

ツリーマップのノード・ヘッダーは、ツリーマップに2つ以上の子レベルがあるときは、デフォルトでいつでも表示されます。デフォルトの表示を変更する場合、ノード・ヘッダーを構成します。

グループ・ギャップは、外部グループのノード間で、デフォルトで表示されます。ノード間でのグループ・ギャップの表示方法を変更する場合、グループ・ギャップを構成します。

30.4.10.1 ツリーマップ・ノード・ヘッダーの構成方法

dvt:treemapNodeHeader要素をツリーマップ・ノードに追加し、次の属性の値を設定することにより、ツリーマップのノード・ヘッダーを構成します。

- labelStyle: ヘッダー内に表示されるラベルのフォント・スタイルを指定します。この属性は、font-sizeやcolorなど、CSSスタイル属性を受け入れます。
CSS属性の完全なリストについては、次のアドレスのWorld Wide Web ConsortiumのWebサイトを参照してください。

http://www.w3.org/TR/CSS21/

- titleHalign: ヘッダーのタイトルの水平方向の配置を指定します。デフォルトではこの属性はstartに設定され、左から右モードではタイトルを左揃えに配置し、右から左モードでは右揃えに配置します。この属性をcenterに設定してタイトルを中央に配置したり、endに設定して、左から右モードではタイトルを右揃えに配置し、右から左モードでは左揃えに配置することができます。

- useNodeColor: ヘッダーに親ノードのノード色を使用させるには、これをonに設定します。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップを追加します。詳細は、30.2.2.2項「ページにツリーマップを追加する方法」を参照してください。

- コンポーネントをページに追加したときにツリーマップとデータ・コントロールをバインドしなかった場合は、データをツリーマップに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

ツリーマップ・ノード・ヘッダーを構成するには、

1. 構造ウィンドウで、dvt:treemapNodeノードを右クリックし、「dvt:treemapNodeの中に挿入」→ツリーマップ・ノード・ヘッダーを選択します。

2. dvt:treemapNodeHeaderノードを右クリックし、プロパティに移動を選択します。

3. 「プロパティ」ウィンドウで、次の属性の値を入力します。

- LabelStyle: ノード・ヘッダー・タイトルのスタイルを入力します。
たとえば、タイトルのサイズを14ピクセルに変え、色を白に変えるには、次の値をLabelStyleに入力します。

font-size:14px;color: #FFFFFF

- TitleHalign: この属性のドロップダウン・メニューを使用してデフォルトの配置をcenterまたはendに変更します。デフォルトではこの属性はstartに設定され、左から右モードではタイトルを左揃えに配置し、右から左モードでは右揃えに配置します。

- UseNodeColor: この属性のドロップダウン・メニューを使用してデフォルトをonに変更します。

30.4.10.2 ツリーマップ・ノード・ヘッダーに関する必知事項

ヘッダーでのノードの色の使用を選択すると、使用されるノードの色は、そのノードがツリーマップの最下レベルであった場合にツリーマップに表示されたものになります。

ツリーマップが全階層レベルで同じ色スキームを使用している場合は、ヘッダーにノードの色を使用することで、有用な情報が提供できます。しかしながら、階層の異なるレベルに異なる色スキームを指定した場合は、ノードの色の使用はあまり意味がありません。

30.4.10.3 ツリーマップ・グループ・ギャップのカスタマイズ方法

ノード間に表示されるグループ・ギャップを、groupGaps属性の値を設定することによりカスタマイズします。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップを追加します。詳細は、30.2.2.2項「ページにツリーマップを追加する方法」を参照してください。

ツリーマップ・グループ・ギャップの表示をカスタマイズするには、

1. 構造ウィンドウでdvt:treemapを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「外観」セクションを開きます。

3. 「グループ・ギャップ」ドロップダウン・メニューを使用して、グループ・ギャップ表示の値を選択します。有効な値は次のとおりです。

- outer (デフォルト): ギャップは外部のグループのノード間に表示されます。

- all: ギャップはすべてのグループのノード間に表示されます。

- none: ギャップはグループのノード間に表示されません。

30.5 ツリーマップとサンバーストヘの対話機能の追加

ツリーマップには対話機能が追加可能で、これには、ツールチップ、ポップアップ、選択サポート、コンテキスト・メニュー、およびドリルが含まれます。ツリーマップは、グループ・ノードの独立性もサポートします。

30.5.1 ツリーマップとサンバーストのツールチップの構成

dvt:treemapNodeあるいはdvt:sunburstNode shortDesc属性の値を指定することにより、ツールチップを定義します。この属性に単純テキストを指定することも、あるいはツリーマップやサンバーストからデータを取り出してノードについての追加情報を表示するEL式を指定することもできます。

図30-33に、サンバースト・ノードの1つの名前とサイズを表示しているサンバーストを示します。

図30-33 サンバースト・ツールチップ

ノードのラベルとサイズ・データの詳細を表示するツールチップを構成するには、EL式のlabelおよびsize属性を参照します。EL式はそのメソッドを参照するマネージドBeanから、labelおよびsize属性の設定のために、データを引き出します。

たとえば、米国の国勢調査の例でのラベルとサイズの属性に値を指定するには、以下をJDeveloperのshortDesc属性に入力します。

#{row.text}<br/>#{row.size}

30.5.2 ツリーマップとサンバーストのポップアップの構成

ツリーマップあるいはサンバーストのポップアップを、af:popupおよびaf:showPopupBehaviorタグを使用して定義します。

af:popupコンポーネントをツリーマップおよびサンバースト・コンポーネントで使用すると、セカンダリ・ウィンドウでの情報の表示および非表示、追加データの入力、コンテキスト・メニューなどの機能の呼出しを、エンド・ユーザーに許可する機能を構成できます。30.5.4項「ツリーマップおよびサンバーストのコンテキスト・メニューの構成」を参照し、af:popupコンポーネントを使用してコンテキスト・メニューを表示する方法を確認してください。

30.5.2.1 ツリーマップおよびサンバースト・コンポーネントへのポップアップの追加方法

ADF Facesのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。af:showPopupBehaviorタグは宣言的ソリューションとなるため、ポップアップ・コンポーネントを開くためのJavaScriptの作成や、スクリプトのポップアップ・コンポーネントへの登録の必要がありません。この項では、af:showPopupBehaviorを使用してポップアップを表示するようにサンバーストあるいはツリーマップ・コンポーネントを構成する例を提示します。

af:showPopupBehaviorおよびaf:popupタグを使用してポップアップを構成するには、af:popupコンポーネントと関連メソッドを定義し、af:showPopupBehaviorタグをdvt:treemapNodeあるいはdvt:sunburstNodeコンポーネントの子として挿入し、af:showPopupBehaviorコンポーネントのタグをトリガー・タイプに構成し、af:popupコンポーネントのid属性を参照します。

図30-34に、ユーザーがツリーマップ上でマウスをホバーさせたときに短いメッセージとツリーマップ・ノードの名前を表示するように構成されたツリーマップを示します。

図30-34 マウス・ホバーでポップアップを示すツリーマップ

例30-9に、ポップアップを宣言するページ上のコードを示します。

例30-9 マウス・ホバーによるツリーマップ・ポップアップのサンプル・コード

<af:group id="g1">
<af:outputText value="Hover on a node to show a popup."
inlineStyle="font-size:medium;" id="ot1"/>
<af:panelGroupLayout layout="horizontal" id="pgl1">
<dvt:treemap id="treemap" value="#{treemap.censusData}" var="row"
inlineStyle="width:450px; height:350px;"
summary="Treemap Popup"
displayLevelsChildren="3">
<dvt:treemapNode id="tn1" value="#{row.size}" fillColor="#{row.color}
label="#{row.text}">
<af:showPopupBehavior popupId="::noteWindowPopup"
triggerType="mouseHover"/>
</dvt:treemapNode>
</dvt:treemap>
</af:panelGroupLayout>
<af:popup childCreation="deferred" autoCancel="disabled"
id="noteWindowPopup" launcherVar="source" eventContext="launcher"
clientComponent="true" contentDelivery="lazyUncached">
<af:setListener from="#{source.currentRowData.text}"
to="#{treemap.noteWindowMessage}" type="popupFetch"/>
<af:noteWindow id="nw1">
<af:outputFormatted value="Hello from #{treemap.noteWindowMessage}" id="of8"/>
</af:noteWindow>
</af:popup>
</af:group>

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- ADF Faces popupコンポーネントをページに追加し、ポップアップに表示させたいメニュー、ダイアログ、あるいはウィンドウを挿入します。
たとえば、図30-34のポップアップは、"Hello from Texas"メッセージを表示するため、ノート・ウィンドウを使用しています。この例を使用するには、ADF Faces noteWindowコンポーネントをpopupコンポーネント内部に挿入し、ADF Faces outputFormattedコンポーネントをノート・ウィンドウの内部に挿入します。サンプル・コードを例30-9に示します。

この例のポップアップは、ノート・ウィンドウでの使用のためにツリーマップからデータを取得するADF Faces setListenerコンポーネントも含みます。この例では、データは現在のノードのテキスト属性(source.currentRowData.text)から取得され、ツリーマップのマネージドBeanのnoteWindowMessage文字列変数に保存されます。この例を使用するには、例30-10に示されるコードをツリーマップBeanに追加します。

例30-10 noteWindowMessage変数をツリーマップ・マネージドBeanに追加するコード部分

private String noteWindowMessage = null;

public void setNoteWindowMessage(String noteWindowMessage) {
this.noteWindowMessage = noteWindowMessage;
}
public String getNoteWindowMessage() {
return noteWindowMessage;
}

マネージドBeanについてヘルプが必要な場合は、3.6項「マネージドBeanの作成と使用」を参照してください。ダイアログ、メニューおよびウィンドウ表示のためのポップアップ・ウィンドウ使用の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- 選択を表示するのに必要な追加コンポーネントを作成します。
たとえば、図30-34のページは、ポップアップの表示のためにユーザーにノード上をホバーするように促すaf:outputTextコンポーネントを使用しています。af:outputTextコンポーネント構成の詳細は、18.2項「出力テキストおよび書式設定された出力テキストの表示」を参照してください。

ツリーマップあるいはサンバーストにポップアップを追加するには、

1. 構造ウィンドウで「dvt:treemapNode」または「dvt:sunburstNode」ノードを右クリックし、「コンポーネント・ノードの中に挿入」→「ポップアップ表示動作」を選択します。
たとえば、ツリーマップにポップアップを追加するには、dvt:treemapNodeノードを右クリックし、「ツリーマップ・ノードの中に挿入」→「ポップアップ表示動作」を選択します。

2. af:showPopupBehaviorノードを右クリックし、 「プロパティに移動」を選択します。

3. 「プロパティ」ウィンドウで、次の属性の値を入力します。

- TriggerType: ポップアップをトリガーするアクションの値を入力します。有効な値は、clickおよびmouseHoverです。

- PopupId: ポップアップ・コンポーネントのIDを参照します。IDを直接入力するか、属性のドロップダウン・メニューを使用して「編集」を選択し、「プロパティの編集 - PopupId」ダイアログでIDを選択できます。
たとえば、国勢調査のデータの例でポップアップを参照するには、次の値をPopupIdに入力します。::noteWindowPopup。

30.5.2.2 ツリーマップおよびサンバースト・コンポーネントへのポップアップの追加に関する必知事項

ツリーマップとサンバーストは、現在clickおよびmouseHoverのトリガー・タイプのみをサポートしています。

ポップアップはその他のノード上には表示されません。詳細は、30.4.5.2項「ツリーマップおよびサンバーストのその他のノードの構成に関する必知事項」を参照してください。

30.5.3 ツリーマップとサンバーストの選択サポートの構成

ツリーマップおよびサンバースト・コンポーネントは、単一および複数ノードの選択をサポートしています。コンポーネントで複数の選択が許可されている場合、ユーザーは[Ctrl]を押しながらクリックする操作で複数のノードを選択できます。

30.5.3.1 ツリーマップおよびサンバースト・コンポーネントへの選択サポートの追加方法

ユーザーがノードを選択、あるいは選択解除すると、ツリーマップあるいはサンバースト・コンポーネントは、selectionEventイベントを起動します。選択されたノードに基づいてツリー・コンポーネントで後処理を実行する、カスタムのselectionListenerインスタンスを登録できます。

図30-35に、カスタムの選択リスナーを使用するように構成されたサンバーストの簡単な例を示します。ユーザーが単一あるいは複数の選択をすると、コンソ－ルは選択されたノードの名前、および選択に追加あるいは除外されたノードの数を表示します。

図30-35 カスタムの選択リスナーを示すサンバースト

例30-11に、ユーザーのクリックに反応してコンソールへの出力を生成するのに使用するselectionListenerメソッドを示します。このメソッドをサンバーストのマネージドBeanまたはバッキングBeanに格納します。

例30-11 サンバーストのselectionListenerメソッドのコード・サンプル

import javax.faces.component.UIComponent;
import oracle.adf.view.faces.bi.component.sunburst.UISunburst;
import org.apache.myfaces.trinidad.event.SelectionEvent;
import org.apache.myfaces.trinidad.model.RowKeySet;

public void selectionListener(SelectionEvent event) {
UIComponent component = event.getComponent();
if(component instanceof UISunburst) {
UISunburst sunburst = (UISunburst) component;
StringBuilder s = new StringBuilder();
// Get the selected row keys and print
RowKeySet selectedRowKeys = sunburst.getSelectedRowKeys();
System.out.println(selectedRowKeys.size() + " Nodes Currently Selected:");
if (selectedRowKeys != null) {
for (Object rowKey : selectedRowKeys) {
TreeNode rowData = (TreeNode)sunburst.getRowData (rowKey);
s.append (rowData.getText()).append(", ");
}
if (s.length() > 0)
s.setLength (s.length() - 2);
System.out.println(s);
}
// Get the row keys that were just added to the selection
RowKeySet addedRowKeys = event.getAddedSet();
System.out.println(addedRowKeys.size() + " Nodes Added");
// Get the row keys that were just removed from the selection
RowKeySet removedRowKeys = event.getRemovedSet();
System.out.println(removedRowKeys.size() + " Nodes Removed");
}
}

選択リスナー・メソッドをツリーマップあるいはサンバースト・コンポーネントのselectionListener属性で宣言し、選択を表示する追加のコンポーネントをJSFページに追加します。この項の例では、リスナーは出力をコンソールに単に表示しているだけで、ユーザーに選択を促すプロンプトのみがページに追加されています。例30-12に、サンバーストの設定に使用されたページの一部を示します。selectionListener属性が、太字のフォントでハイライトされています。

例30-12 選択リスナーを宣言するサンバーストのサンプル・ページ

<af:panelGroupLayout id="pgl12">
<af:group id="g5">
<af:outputText value="Click on a node to make a selection. Use Ctrl-click for multiple nodes."
inlineStyle="font-size:large;" id="ot3"/>
<dvt:sunburst id="s1" summary="SampleSunburst"
value="#{sunburst.censusData}"
var="row"
colorLabel="Income"
sizeLabel="Population" displayLevelsChildren="3"
selectionListener="#{sunburst.selectionListener}">
<dvt:sunburstNode id="sn1" value="#{row.size}" fillColor="#{row.color}"
label="#{row.text}"
shortDesc="#{row.text}&lt;br/>#{row.size}"/>
</dvt:sunburst>
</af:group>
</af:panelGroupLayout>

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- selectionListenerを定義するメソッドを作成し、選択状態を返し、それをツリーマップあるいはサンバースト・コンポーネントのマネージドあるいはバッキングBeanに保存します。
同じ国勢調査データの例を使用するには、例のコードをsunburstと名付けられたマネージドBeanにコピーします。マネージドBeanについてのヘルプが必要な場合、3.6項「マネージドBeanの作成と使用」を参照してください。

- 選択を表示するのに必要な追加コンポーネントを作成します。
たとえば、図30-35のページは、選択を行うためにユーザーにノードのクリックを促すaf:outputTextコンポーネントを使用しています。af:outputTextコンポーネント構成の詳細は、18.2項「出力テキストおよび書式設定された出力テキストの表示」を参照してください。

ツリーマップあるいはサンバーストに選択サポートを追加するには、

1. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」の項を開き、次の属性を設定します。

- NodeSelection: 単一ノードのみの選択サポートを有効化するには、singleに設定します。デフォルトでは複数選択が有効化されています。

- SelectionListener: ユーザーがノードをクリックしたときにコールされるメソッドの名前を入力します。
たとえば、sunburstという名前のマネージドBeanとselectionListenerという名前のメソッドには、SelectionListenerフィールドに、以下を入力します。#{sunburst.selectionListener}。

30.5.3.2 ツリーマップおよびサンバーストへの選択サポートの追加に関する必知事項

ツリーマップとサンバーストはツリー・コンポーネントと同じデータ・モデルを使用しているので、選択イベントはorg.apache.myfaces.trinidad.event.SelectionEventライブラリで定義されます。ツリー・モデルにおける選択サポートの詳細は、12.6.3項「実行時の処理内容: ツリー・コンポーネント・イベント」を参照してください。

JDeveloperにおけるイベント処理の詳細は、第6章「イベント処理」を参照してください。

30.5.4 ツリーマップとサンバーストのコンテキスト・メニューの構成

ツリーマップとサンバーストのいずれも、ユーザーがノードを右クリックしたときにコンテキスト・メニューを表示するように構成できます。

30.5.4.1 ツリーマップとサンバーストのコンテキスト・メニューの構成方法

ツリーマップおよびサンバーストのコンテキスト・メニューを、これらのコンテキスト・メニュー・ファセットを使用して定義します。

- bodyContextMenu: ツリーマップまたはサンバースト・コンポーネント内の選択不可の要素上に表示されるコンテキスト・メニューを指定します。

- contextMenu: ツリーマップまたはサンバースト・コンポーネント内の選択可能要素上に表示されるコンテキスト・メニューを指定します。

- multiSelectContextMenu: ツリーマップまたはサンバースト・コンポーネント内で複数の要素が選択されるときに表示されるコンテキスト・メニューを指定します。

JSPまたはJSPXページの各ファセットでは、1つの子コンポーネントがサポートされます。Faceletは、複数の子コンポーネントをサポートします。これらすべてのファセットが機能するためには、ツリーマップあるいはサンバーストのプロパティで、選択が有効化されている必要があります。コンテキスト・メニューは、現在のところFlashでのみサポートされています。

af:popupコンポーネント内のaf:menuコンポーネントを使用してコンテキスト・メニューを作成します。ついで、指定されたトリガーに基づき、別のコンポーネントからコンテキスト・メニュー・ポップアップを起動できます。コンテキスト・メニューの構成の詳細は、第15章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

図30-36に、ユーザーがツリーマップの地域、地区、あるいはノードの1つを右クリックしたときにコンテキスト・メニューを表示するように、contextMenuファセットを使用して構成されたサンプルのツリーマップを示します。

図30-36 ツリーマップ・コンテキスト・メニュー

ユーザーがView Details for Midwest Regionを選択すると、アプリケーションはMidwest Regionノードについての追加情報を提供できます。

図30-37に、ユーザーがMidwest Regionの詳細を見る選択をしたあとで、ツリーマップの下に表示されるテキスト出力を示します。この例では、出力はユーザーがクリックしたものを検証するだけですが、このコンテキスト・メニューはMidwest Regionについての追加詳細の提示にも使用できます。

図30-37 クリック後のコンテキスト・メニューのサンプル出力

例30-13に、例のツリーマップとコンテキスト・メニューを構成するのに使用したサンプル・コードを示します。

例30-13 ツリーマップ・コンテキスト・メニューのコード・サンプル

<af:group id="g1">
<af:outputFormatted value="Right click to display context menu." id="of1"/>
<dvt:treemap id="t1" displayLevelsChildren="3" summary="Sample Treemap"
var="row" value="#{treemap.censusData}"
binding="#{treemapContextMenu.treemap}">
<dvt:treemapNode id="tn1" value="#{row.size}" fillColor="#{row.color}"
label="#{row.text}"/>
<f:facet name="contextMenu">
<af:popup id="p1" contentDelivery="lazyUncached">
<af:menu text="menu 1" id="m1">
<af:commandMenuItem text="View Details for #{treemapContextMenu.selectionState}"
id="cmi1"
actionListener="#{treemapContextMenu.menuItemListener}"/>
<af:group id="g2">
<af:commandMenuItem text="Add Task" id="cmi2"
actionListener="#{treemapContextMenu.menuItemListener}"/>
<af:commandMenuItem text="Add Notes" id="cmi3"
actionListener="#{treemapContextMenu.menuItemListener}"/>
</af:group>
</af:menu>
</af:popup>
</f:facet>
</dvt:treemap>
<af:outputFormatted value="#{treemapContextMenu.status}" id="of2"
clientComponent="true"
binding="#{treemapContextMenu.outputFormatted}"/>
</af:group>

この例では、メソッドがツリーマップを設定し、選択状態を返し、コンテキスト・メニュー上のユーザー・クリックに反応する、treemapContextMenuという名前のバッキングBeanを使用しています。この例も、ツリーマップのデータ設定に、30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」で説明されたものと同じクラスとメソッドを使用しています。例30-14に、ContextMenuSampleクラスのコードを示します。

例30-14 ContextMenuSampleクラスのコード

import javax.faces.component.UIComponent;
import javax.faces.event.ActionEvent;
import oracle.adf.view.faces.bi.component.treemap.UITreemap;
import oracle.adf.view.rich.component.rich.nav.RichCommandMenuItem;
import oracle.adf.view.rich.component.rich.output.RichOutputFormatted;
import org.apache.myfaces.trinidad.context.RequestContext;

public class ContextMenuSample {
private UITreemap treemap;
private String status;
private RichOutputFormatted outputFormatted;
public ContextMenuSample() {
}
public void setTreemap(UITreemap treemap) {
this.treemap = treemap;
}
public UITreemap getTreemap() {
return treemap;
}
public String getSelectionState() {
if (treemap != null) {
return TreemapSample.convertToString(treemap.getSelectedRowKeys(), treemap);
} else
return null;
}
public String getStatus() {
return status;
}
public void setOutputFormatted(RichOutputFormatted outputFormatted) {
this.outputFormatted = outputFormatted;
}
public RichOutputFormatted getOutputFormatted() {
return outputFormatted;
}
/**
* Called when a commandMenuItem is clicked.  Updates the outputText with information about the menu item clicked.
* @param actionEvent
*/
public void menuItemListener(ActionEvent actionEvent) {
UIComponent component = actionEvent.getComponent();
if (component instanceof RichCommandMenuItem) {
RichCommandMenuItem cmi = (RichCommandMenuItem)component;
// Add the text of the item into the status message
StringBuilder s = new StringBuilder();
s.append("You clicked on \"").append(cmi.getText()).append("\".  <br><br>");
this.status = s.toString();
// Update the status text component
RequestContext.getCurrentInstance().addPartialTarget(this.outputFormatted);
}
}
}

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- actionListenerを定義し選択状態を返すマネージドBeanを作成します。
同じ国勢調査データの例を使用するには、例30-14「ContextMenuSampleクラス・コード」の例のコードをtreemapContextMenuと名付けられたバッキングBeanにコピーします。マネージドBeanについてのヘルプが必要な場合、3.6項「マネージドBeanの作成と使用」を参照してください。

- コンテキスト・メニューをサポートするのに必要な追加コンポーネントを作成します。
たとえば、図30-36のページは、コンテキスト・メニューの表示のためにユーザーに右クリックを促すaf:outputTextコンポーネントを使用しています。ユーザーがカスタムのコンテキスト・メニュー項目を選択したとき、ページはaf:outputFormattedコンポーネントを使用して、ユーザーがどのノードを選択したかを確認するメッセージを表示します。

追加コンポーネントの構成に必要な詳細は、例30-14のコード・サンプルを参照してください。af:outputTextおよびaf:outputFormattedコンポーネントの詳細は、18.2項「出力テキストおよび書式設定された出力テキストの表示」を参照してください。

ツリーマップあるいはサンバーストにコンテキスト・メニューを追加するには、

1. ユーザーのアプリケーションがバッキングBeanを使用している場合は、以下を実行します。

1. 構造ウィンドウで「dvt:treemap」または「dvt:sunburst」ノードを右クリックし、「プロパティに移動」を選択します。

2. 拡張の項を開いてバインディング属性の値を入力し、ツリーマップをコンテキスト・メニューのためのメソッドを含むマネージドBeanと関連付けます。または、属性のドロップダウン・メニューから編集を選び、既存のBeanとメソッドを、作成または選択します。

バインディング属性は、ツリーマップを設定するコードを含んでいるので、国勢調査のデータの例に必要です。しかしながら、これはまた、30.3.1項「ツリーマップあるいはサンバースト・コンポーネントへのデータの追加方法」で説明されたものと同じクラスとメソッドからのデータとメソッドを使用しています。たとえば、treemapContextMenuという名前のバッキングBeanに、以下を「バインディング」フィールドに入力します。#{treemapContextMenu.treemap}。

2. 構造ウィンドウでdvt:treemapまたはdvt:sunburstノードを右クリックし、「ツリーマップの中に挿入」または「サンバーストの中に挿入」を選択します。

3. 「ファセットの挿入」ダイアログで、作成するコンテキスト・メニューのタイプに相当するファセットの名前を入力します。
たとえば、contextMenuファセットを定義するには、以下を名前フィールドに入力します。contextMenu。

4. 「OK」をクリックします。
ファセットは、dvt:treemapノードまたはdvt:sunburstノードの子として作成されます。

5. 構造ウィンドウでf:facet - context menuノードを右クリックし、「ファセットの中に挿入」→「ADF Faces」→「ポップアップ」を選択します。

6. af:popupノードを右クリックし、プロパティに移動を選択します。

7. 「プロパティ」ウィンドウで、次のプロパティを設定します。

- ContentDelivery: これをLazyUncachedに設定します。

- AutoCancel: これを、<default> enabledに設定します。

- ChildCreation: これを、<default> immediateに設定します。

8. 構造ウィンドウでaf:popupノードを右クリックし、「ポップアップの中に挿入」→「メニュー」を選択します。

9. 構造ウィンドウでaf:menuノードを右クリックし、「メニューの中に挿入」→「メニュー・アイテム」を選択してメニュー・アイテムを作成します。

10. af:commandMenuItemノードを右クリックし、 プロパティに移動を選択します。

11. 「プロパティ」ウィンドウで、「共通」の項を開き、次のプロパティを設定します。

- Text: メニューに表示するテキストを入力します。
たとえば、国勢調査のデータの例を複製するには、次の値をTextフィールドに入力します。View Details for #{treemapContextMenu.selectionState}。

- ActionListener: ユーザーがメニュー項目を選択したときにコールされるメソッドの名前を入力ます。
たとえば、treemapContextMenuという名前のマネージドBeanとmenuItemListenerという名前のメソッドには、ActionListenerフィールドに、以下を入力します。#{treemapContextMenu.menuItemListener}。

12. コンテキスト・メニューに表示させたい各メニュー項目につき、ステップ9とステップ11を繰り返します。

ヒント:

関連するメニュー項目をグループ化するには、ADF Faces af:groupコンポーネントをaf:commandMenuItemの前後で、例30-13に示すように折り返します。af:groupコンポーネントの詳細は、9.13項「関連する項目のグループ化」を参照してください。

13. 追加のコンテキスト・メニュー・ファセットを構成するには、ステップ2からステップ12を繰り返します。

30.5.4.2 ツリーマップおよびサンバーストのコンテキスト・メニューの構成に関する必知事項

コンテキスト・メニューはHTML5とFlashイメージ形式でのみサポートされています。コンテキスト・メニューがFlashでレンダリングされる場合、コンテキスト・メニューはFlash Playerのコンテキスト・メニューを使用します。このため、ポップアップ・メニューにはいくつかの制限があります。Flashとポップアップ・メニューの詳細は、22.2.4項「グラフ、ゲージ、ツリーマップおよびサンバーストのコンテキスト・メニュー」を参照してください。

30.5.5 ツリーマップとサンバーストのドリル・サポートの構成

ドリル・サポートは、ユーザーがコンポーネントのグループ・ヘッダーをクリックするか、各ノードをダブルクリックすることにより、ツリーマップあるいはサンバーストの階層をナビゲートすることを可能にします。

30.5.5.1 ツリーマップとサンバーストのドリル・サポートの構成方法

ドリル・サポートをツリーマップあるいはサンバーストのノードのdrilling属性により有効化します。

JDeveloperには、ドリルをサポートするのに必要なコードが含まれています。しかしながら、ノードがドリルされているときに、アプリケーションに他のタスクを実行させる場合があります。追加のタスクを実行するメソッドを定義し、それをドリル・リスナーとして、ツリーマップあるいはサンバーストのマネージドあるいはバッキングBeanに追加できます。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- ドリル・リスナーを追加する場合、リスナーを定義するメソッドを作成し、それをツリーマップあるいはサンバーストのマネージドあるいはバッキングBeanに追加します。
イベント処理の詳細は、第6章「イベント処理」を参照してください。Beanについてのヘルプが必要な場合、3.6項「マネージドBeanの作成と使用」を参照してください。

ツリーマップあるいはサンバーストにドリル・サポートを追加するには、

1. 構造ウィンドウでdvt:treemapNodeまたはdvt:sunburstNodeノードを右クリックし、プロパティに移動を選択します。

2. 「プロパティ」ウィンドウで、「拡張」の項を開き、「ドリル」属性のドロップダウン・リストを使用して 「ドリル」属性を次の値の1つに設定します。

- replace: ユーザーがノードをダブルクリックして、ツリーマップあるいはサンバーストの新しいルートに設定することを可能にします。

- insert (サンバーストのみ): ユーザーがノードの子を開いたり閉じたりすることを可能にします。

- insertAndReplace (サンバーストのみ): ユーザーがノードをダブルクリックして階層のルートに設定したり、ノードの子を開いたり閉じたりするすることを可能にします。

3. ユーザーのアプリケーションがドリル・リスナーを含んでいる場合は、以下を実行します。

1. 構造ウィンドウでdvt:treemapを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで、「動作」セクションを展開します。

3. ドリル・リスナー属性のドロップダウン・メニューから、編集を選択します。

4. 「属性の編集」ダイアログで、検索ボックスを使用してツリーマップのマネージドBeanを検索します。

5. マネージドBeanのノードを開き、ドリル・リスナーを含むメソッドを選択します。

6. OKをクリックします。
式が作成されます。

たとえば、sampleTreemapというマネージドBeanとsampleDrillListenerというメソッドの場合、式ビルダーによりドリル・リスナーの値として、コード#{sampleTreemap.sampleDrillListener}が生成されます。

30.5.5.2 ツリーマップとドリル・サポートに関する必知事項

ドリルは、表示可能なデータの追加のレイヤーがある場合に推奨されます。独立性とは異なり、ツリー・モデルから追加のデータをフェッチするのは、サーバー側の操作です。すでに表示されているグループ・データにフォーカスするには、ツリーマップの分離機能を使用します。詳細は、30.5.7項「独立性のサポートの構成(ツリーマップのみ)」を参照してください。

30.5.6 ツリーマップおよびサンバーストへのドラッグ・アンド・ドロップの追加方法

ツリーマップおよびサンバーストを、ページ上でサポートされたコンポーネント間のドラッグ・アンド・ドロップ操作のドラッグ・ソース、およびドロップ・ターゲットとして構成できます。

ツリーマップあるいはサンバーストにドラッグのサポートを追加するには、af:dragSourceタグをツリーマップに追加し、af:dropTargetタグをドラッグを受け取るコンポーネントに追加します。ドラッグを受け取るコンポーネントはorg.apache.myfaces.trinidad.model.RowKeySetデータ・フレーバをaf:dropTargetの子として含み、かつドロップ・イベントへの応答のため、dropListenerメソッドを定義する必要があります。

ツリーマップあるいはサンバーストにドロップのサポートを追加するには、af:dropTargetタグをツリーマップあるいはサンバーストに追加し、そのツリーマップあるいはサンバーストがサポートするデータ・フレーバを含めます。dropListenerメソッドを、ドロップ・イベントに応答するツリーマップあるいはサンバーストのマネージドBeanに追加します。

次の手順は、ツリーマップあるいはサンバーストを単一のドラッグ・ソースあるいはドロップ・ターゲットとして設定する方法を示します。ADF FacesまたはADFデータ視覚化コンポーネントのドラッグ・アンド・ドロップの構成の詳細は、第36章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

始める前に:

ツリーマップおよびサンバーストの属性や子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。ツリーマップの属性と子タグの構成の詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。サンバーストの属性と子タグの構成の詳細は、30.2.3.1項「サンバーストの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

- ページにツリーマップあるいはサンバーストを追加します。詳細は、30.2.2.2項「ツリーマップのページへの追加方法」または30.2.3.2項「サンバーストのページへの追加方法」を参照してください。

- コンポーネントをデータに追加したときにツリーマップあるいはサンバーストとデータ・コントロールをバインドしなかった場合は、データをツリーマップあるいはサンバーストに追加します。UI-first開発を使用してのツリーマップまたはサンバーストへのデータ追加の詳細は、第30.3項「ツリーマップおよびサンバースト・コンポーネントへのデータの追加」を参照してください。

- ドラッグ・アンド・ドロップをサポートするのに必要な追加コンポーネントを作成します。
たとえば、図30-17のページは、ツリーマップ・ノードを指示されたテキストにドラッグするようユーザーに促すaf:outputTextコンポーネントを使用しています。ユーザーがノードをテキストにドラッグしたとき、ページはaf:outputFormattedコンポーネントを使用して、ユーザーがどのノードをドラッグしたかを確認するメッセージを表示します。

例30-15に、完成したページのサンプル・コードを示します。af:outputTextおよびaf:outputFormattedコンポーネントの詳細は、18.2項「出力テキストおよび書式設定された出力テキストの表示」を参照してください。

例30-15 ツリーマップのドラッグ・ソース例のサンプル・コード

<af:group id="g1">
<af:panelGroupLayout id="pgl2" layout="horizontal">
<af:outputText value="Drag Source Demo" inlineStyle="font-size:large;" id="ot2"/>
<af:spacer width="10" height="10" id="s1"/>
<af:outputText value="Drag a Treemap Node to the Text" id="ot1"/>
</af:panelGroupLayout>
<af:panelGroupLayout id="pgl3" layout="horizontal">
<dvt:treemap id="t1" value="#{treemap.censusData}" var="row"
displayLevelsChildren="3"
colorLabel="Median Household Income"
sizeLabel="Population" summary="Discrete Treemap"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}"
shortDesc="#{row.text}&lt;br/>Population: #{row.size}&lt;br/>Income: #{row.income}">
<dvt:attributeGroups id="ag1" value="#{row.income > 50000}"
label="#{row.income > 50000 ? 'High Income' : 'Low Income'}"
type="color"/>
</dvt:treemapNode>
<af:dragSource defaultAction="MOVE" actions="COPY MOVE LINK"/>
</dvt:treemap>
<af:spacer width="20" id="s2"/>
<af:outputFormatted value="#{treemap.dropText}" id="of1">
<af:dropTarget dropListener="#{treemap.fromDropListener}">
<af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"/>
</af:dropTarget>
</af:outputFormatted>
</af:panelGroupLayout>
</af:group>

例30-16に、図30-18のページのサンプル・コードを示します。この例では、ツリーマップはドロップ・ターゲットとして構成されています。

例30-16 ツリーマップのドロップ・ターゲット例のサンプル・コード

<af:group id="g1">
<af:panelGroupLayout id="pgl4" layout="horizontal">
<af:outputText value="Drop Target Demo" inlineStyle="font-size:large;"/>
<af:spacer width="10" id="s2"/>
<af:outputText value="Drag From the Text to the Treemap" id="ot1"/>
</af:panelGroupLayout>
<af:panelGroupLayout id="pgl3" layout="horizontal">
<dvt:treemap id="t1" value="#{treemap.censusData}" var="row"
displayLevelsChildren="3"
colorLabel="Median Household Income"
sizeLabel="Population" summary="Discrete Treemap"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}"
shortDesc="#{row.text}&lt;br/>Population: #{row.size}&lt;br/>Income: #{row.income}">
<dvt:attributeGroups id="ag1" value="#{row.income > 50000}"
label="#{row.income > 50000 ? 'High Income' : 'Low Income'}"
type="color"/>
</dvt:treemapNode>
<af:dropTarget dropListener="#{treemap.toDropListener}"
actions="MOVE COPY LINK">
<af:dataFlavor flavorClass="java.lang.Object"/>
</af:dropTarget>
</dvt:treemap>
<af:spacer width="20" id="s1"/>
<af:outputFormatted value="#{treemap.dragText}" id="of1"
clientComponent="true">
<af:componentDragSource/>
</af:outputFormatted>
</af:panelGroupLayout>
</af:group>

ツリーマップあるいはサンバーストにドラッグ・アンド・ドロップ・サポートを追加するには、

1. ツリーマップあるいはサンバーストをドロップ・ターゲットとして構成するには、「コンポーネント」ウィンドウで、「操作」パネルから、「ドロップ・ターゲット」をドラッグし、ツリーマップあるいはサンバースト・コンポーネントの子としてドロップします。

2. 「ドロップ・ターゲットを挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選び、ドロップ・リスナー・メソッドをツリーマップあるいはサンバーストのマネージドBeanに追加してください。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、toDropListener()という名前のメソッドをtreemapという名前のマネージドBeanに追加するには、編集を選び、ドロップダウン・メニューからtreemapを選択し、新規を「メソッド」フィールドの右でクリックして、toDropListener()メソッドを作成します。

例30-17はサンプルのドロップ・リスナーと図30-18に表示されるツリーマップのサポート・メソッドを示します。

例30-17 ツリーマップのサンプル・ドロップ・リスナー

// imports needed by methods
import java.util.Map;
import oracle.adf.view.rich.dnd.DnDAction;
import oracle.adf.view.rich.event.DropEvent;
import oracle.adf.view.rich.datatransfer.DataFlavor;
import oracle.adf.view.rich.datatransfer.Transferable;
import org.apache.myfaces.trinidad.context.RequestContext;
import org.apache.myfaces.trinidad.render.ClientRowKeyManager;
import javax.faces.context.FacesContext;
import oracle.adf.view.faces.bi.component.treemap.UITreemap;
import javax.faces.component.UIComponent;
// variables need by methods
private String dragText = "Drag this text onto a node";
// drop listener
public DnDAction toDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<Object> dataFlavor = DataFlavor.getDataFlavor(Object.class);
Object transferableObj = transferable.getData(dataFlavor);
if(transferableObj == null)
return DnDAction.NONE;
// Build up the string that reports the drop information
StringBuilder sb = new StringBuilder();
// Start with the proposed action
sb.append("Drag Operation: ");
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
sb.append("Copy<br>");
}
else if(proposedAction == DnDAction.LINK) {
sb.append("Link<br>");
}
else if(proposedAction == DnDAction.MOVE) {
sb.append("Move<br>");
}
// Then add the rowKeys of the nodes that were dragged
UIComponent dropComponent = event.getDropComponent();
Object dropSite = event.getDropSite();
if(dropSite instanceof Map) {
String clientRowKey = (String) ((Map) dropSite).get("clientRowKey");
Object rowKey = getRowKey(dropComponent, clientRowKey);
if(rowKey != null) {
sb.append("Drop Site: ");
sb.append(getLabel(dropComponent, rowKey));
}
}
// Update the output text
this.dragText = sb.toString();
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return event.getProposedAction();
}

public String getDragText() {
return dragText;
}

private String getLabel(UIComponent component, Object rowKey) {
if(component instanceof UITreemap) {
UITreemap treemap = (UITreemap) component;
TreeNode rowData = (TreeNode) treemap.getRowData(rowKey);
return rowData.getText();
}
return null;
}

private Object getRowKey(UIComponent component, String clientRowKey) {
if(component instanceof UITreemap) {
UITreemap treemap = (UITreemap) component;
ClientRowKeyManager crkm = treemap.getClientRowKeyManager();
return crkm.getRowKey(FacesContext.getCurrentInstance(), component, clientRowKey);
}
return null;
}

3. 「OK」をクリックして、「データ・フレーバの挿入」ダイアログに入力します。

4. 「データ・フレーバの挿入」ダイアログで、ドロップ・ターゲットが受け入れるオブジェクトを入れます。または、ドロップダウン・メニューを使用してオブジェクトの階層をナビゲートし、希望するオブジェクトを選択します。
たとえば、af:outputFormattedコンポーネントがテキストをツリーマップにドラッグできるようにするには、java.lang.Objectを「データ・フレーバの挿入」ダイアログに入力します。

5. 構造ウィンドウでaf:dropTargetノードを右クリックし、「プロパティに移動」を選択します。

6. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

7. ツリーマップあるいはサンバーストをドロップ・ターゲットとして使用するには、以下を実行します。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグをドラッグのソースとなるコンポーネントの子としてドラッグ・アンド・ドロップします。
たとえば、「ドラッグ元」をaf:outputFormattedコンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、コンポーネントの「値」のフィールドに、ステップ2でドロップ・リスナーでツリーマップあるいはサンバーストに作成したパブリック変数を参照します。
たとえば、toDropListener()という名前のドロップ・リスナーとdropTextという名前の変数には、コンポーネントの「値」フィールドに、次を入力します。

#{treemap.dropText}

8. ツリーマップあるいはサンバーストをドラッグ・ソースとして構成するには、「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグを、ツリーマップあるいはサンバーストの子としてドラッグ・アンド・ドロップします。

9. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

10. ドラッグ・ソースがサポートするデフォルトのアクションを指定するには、DefaultAction属性のドロップダウン・メニューを使用して、「コピー」,、「移動」または「リンク」を選択します。
図30-17「ドラッグ・ソースとして構成されたツリーマップ」におけるドラッグ・アンド・ドロップの例でのツリーマップは、移動をデフォルトのアクションとして使用しています。

11. 他のコンポーネントをツリーマップまたはサンバーストからのドラッグのドロップ・ターゲットとするには、以下を実行します。

1. 「コンポーネント」ウィンドウで、「Operations」パネルから、「ドロップ・ターゲット」を、ドロップを受け取るコンポーネント上にドラッグ・アンド・ドロップします。
たとえば、図30-18「ドロップ・ターゲットとして構成されたツリーマップ」におけるドラッグ・アンド・ドロップの例のページは、ドロップの結果を表示するaf:outputFormattedコンポーネントを含んでいます。

2. 「ドロップ・ターゲットの挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選び、ドロップ・リスナー・メソッドを適切なマネージドBeanに追加してください。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、fromDropListener()という名前のメソッドをtreemapという名前のマネージドBeanに追加するには、編集を選び、ドロップダウン・メニューからtreemapを選択し、新規を「メソッド」フィールドの右でクリックして、fromDropListener()メソッドを作成します。

例30-18に、図30-17に表示されるツリーマップのサンプル・ドロップ・リスナーを示します。この例は例30-17で使用されたものと同じインポートとヘルパー・メソッドを使用しており、それらはここには含まれていません。

例30-18 ツリーマップをドラッグ・ソースとして使用するコンポーネントのサンプル・ドロップ・リスナー

// Additional import needed for listener
import org.apache.myfaces.trinidad.model.RowKeySet;
// Variables needed by method
private String dropText = "Drop a node here";
// Drop listener
public DnDAction fromDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<RowKeySet> dataFlavor = DataFlavor.getDataFlavor(RowKeySet.class);
RowKeySet rowKeySet = transferable.getData(dataFlavor);
if(rowKeySet == null || rowKeySet.getSize() <= 0)
return DnDAction.NONE;
// Build up the string that reports the drop information
StringBuilder sb = new StringBuilder();
// Start with the proposed action
sb.append("Drag Operation: ");
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
sb.append("Copy<br>");
}
else if(proposedAction == DnDAction.LINK) {
sb.append("Link<br>");
}
else if(proposedAction == DnDAction.MOVE) {
sb.append("Move<br>");
}
// Then add the rowKeys of the nodes that were dragged
sb.append("Nodes: ");
UIComponent dragComponent = event.getDragComponent();
for(Object rowKey : rowKeySet) {
sb.append(getLabel(dragComponent, rowKey));
sb.append(", ");
}
// Remove the trailing ,
sb.setLength(sb.length()-2);
// Update the output text
this.dropText = sb.toString();
RequestContext.getCurrentInstance().addPartialTarget(event.getDropComponent());
return event.getProposedAction();
}

3. 「OK」をクリックして、「データ・フレーバの挿入」ダイアログに入力します。

4. 「データ・フレーバの挿入」ダイアログで、org.apache.myfaces.trinidad.model.RowKeySetを入力します。
たとえば、af:outputFormattedコンポーネントがテキストをツリーマップにドラッグできるようにするには、org.apache.myfaces.trinidad.model.RowKeySetを「データ・フレーバの挿入」ダイアログに入力します。

5. 構造ウィンドウでaf:dropTargetノードを右クリックし、「プロパティに移動」を選択します。

6. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
たとえば、「アクション」フィールドに次を入力し、すべての操作を可能にします。

COPY MOVE LINK

7. コンポーネントの「値」のフィールドでは、ステップ2でドロップ・リスナーでツリーマップあるいはサンバーストに作成したパブリック変数を参照します。
たとえば、fromDropListener()という名前のドロップ・リスナーとdragTextという名前の変数には、コンポーネントの値フィールドに、次を入力します。

#{treemap.dragText}

30.5.7 独立性サポートの構成(ツリーマップのみ)

独立性は、ユーザーがグループ・ヘッダーをクリックしてグループ・データの表示を最大化することを可能にします。独立性の機能は、グループ・ヘッダーが表示されているとき、デフォルトで有効化されます。

30.5.7.1 独立性サポートを無効化する方法

独立性を無効化する場合、dvt:treemapNodeHeaderノードのIsolate属性をoffに設定します。

始める前に:

ツリーマップの属性やツリーマップの子タグが機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、30.2.2.1項「ツリーマップの構成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、30.1.3項「ツリーマップおよびサンバースト・コンポーネントの追加機能」を参照してください。

ページにツリーマップを追加します。詳細は、30.2.2.2項「ページにツリーマップを追加する方法」を参照してください。

ツリーマップ・ノード・ヘッダーをツリーマップに追加します。詳細は、30.4.10.1項「ツリーマップ・ノード・ヘッダーを構成する方法」を参照してください。

ツリーマップ・グループでの独立性サポートを無効化するには、

1. 「構造」ウィンドウで、dvt:treemapNodeノードを開きます。

2. dvt:treemapNodeHeaderノードを右クリックし、プロパティに移動を選択します。

3. 「プロパティ」ウィンドウで、「拡張」セクションを開きます。

4. 分離属性のドロップダウン・メニューから、オフを選択します。

5. ツリーマップに複数のノードがある場合は、ステップ1からステップ4を繰り返し、各ノードの独立性サポートを無効化します。

30.5.7.2 ツリーマップと独立性サポートに関する必知事項

独立性はクライアント側の操作で、ユーザーがすでに表示されているデータにフォーカスすることを可能にします。ツリーマップに複数の子レベルがあり、ユーザーに未表示のレベルへのアクセスをさせたい場合は、かわりにドリルを使用します。ドリル・サポートの追加については、30.5.5.1項「ツリーマップおよびサンバーストのドリル・サポートの構成方法」を参照してください。

第VI部

ビューの完成

第VI部の内容は次のとおりです。

- 第31章「スタイルおよびスキンを使用した外観のカスタマイズ」

- 第32章「ページの国際化およびローカライズ」

- 第33章「アクセス可能なADF Facesページの開発」

- 第34章「カスタムADF Facesコンポーネントの作成」

- 第35章「JSFページでのユーザー・カスタマイズの許可」

- 第36章「ドラッグ・アンド・ドロップ機能の追加」

- 第37章「様々な出力モードの使用方法」

- 第38章「非同期バックエンドでのアクティブ・データ・サービスの使用方法」

31 スタイルおよびスキンを使用した外観のカスタマイズ

この章では、コンポーネントのスタイル属性を変更またはADFスキンを使用することにより、ADFアプリケーションの外観をカスタマイズする方法を説明します。エンド・ユーザーが実行時にアプリケーションのADFスキンを変更できるようにする方法の詳細の他に、ADFスキンの作成に使用できるツールであるADFスキン・エディタについても説明します。

この章では、次の項目について説明します。

- 31.1項「スタイルおよびスキンを使用した外観のカスタマイズについて」

- 31.2項「コンポーネントのスタイル・プロパティの変更」

- 31.3項「エンド・ユーザーによるアプリケーションのADFスキン変更の許可」

31.1 スタイルおよびスキンを使用した外観のカスタマイズについて

アプリケーションに適用するADFスキンを使用するか、スタイル関連のプロパティ(styleClassまたはinlineStyle)がコンポーネントで公開されている場合は、CSSスタイル・プロパティを直接ADF FacesまたはADFデータ視覚化コンポーネントに適用することにより、ADF FacesおよびADFデータ視覚化コンポーネントの外観をカスタマイズできます。後者を選択すると、アプリケーションのそのコンポーネント用のADFスキンで定義されたスタイル・プロパティをオーバーライドすることになります。アプリケーション中のすべてのコンポーネントに対してではなく、あるページで1つコンポーネントの1インスタンスのスタイルを変更する場合、あるいはプログラムでスタイルを条件付きで設定する場合には、これを実行します。たとえば、ある特定の条件においてのみテキストが赤色で表示されるように設定する場合などです。詳細は、31.2項「コンポーネントのスタイル・プロパティの変更」を参照してください。

ADFスキンは、CSSファイルの1種で、ここでCSSスタイル・プロパティを、外観をカスタマイズするコンポーネントのカスケード・スタイル・シート(CSS)仕様に基づいて定義します。ADFスキンでは、特定のコンポーネントやコンポーネントのグループに対してCSSスタイル・プロパティを適用する方法を決めるルールを定義します。エンド・ユーザーのブラウザでは、これらのルールが解釈され、ブラウザのデフォルトの設定がオーバーライドされます。図31-1および図31-2では、ADFスキンを適用した結果、アプリケーションに表示されるADF FacesおよびADFデータ視覚化コンポーネントの外観がどうなったかを示しています。図31-1に、simple ADFスキンを適用したFile Explorerアプリケーションのページを示します。

図31-1 simpleスキンを使用した索引ページ

図31-2に、skyros ADFスキンを適用した同じアプリケーションの同じページを示します。

図31-2 skyrosスキンを使用した索引ページ

File Explorerアプリケーションには、アプリケーションの外観をカスタマイズするためにいくつかのADFスキンが用意されています。これらのADFスキンとFile Explorerアプリケーションのソース・ファイルを表示できます。詳細は、2.1項「ADF Facesデモ・アプリケーションについて」を参照してください。

このガイドでは、CSSの概念については説明しません。公式仕様など、スタイルシートの広範な情報は、次に示すWorld Wide Web ConsortiumのWebサイトを参照してください。

http://www.w3.org/

ADFスキンの作成、変更またはアプリケーションへの適用の方法についても、このガイドでは説明していません。詳細は、『Oracle ADFスキン・エディタによるADFスキンの作成』を参照してください。

複数のADFスキンを作成する場合、エンド・ユーザーがアプリケーションで使用する好みのADFスキンを選択するように、アプリケーションを構成できます。詳細は、31.3項「エンド・ユーザーによるアプリケーションのADFスキン変更の許可」を参照してください。

31.1.1 外観のカスタマイズのユースケースおよび例

様々な目的のために、ADFスキンをカスタマイズできます。たとえば、図31-3に示すように、エンド・ユーザーがADF Faces tableコンポーネントでレンダリングされたデータ行を選択すると、アプリケーションによりその行が強調表示され、フィードバックが提供されるように、ADFスキンのプロパティを定義できます。

図31-3 ADF表コンポーネントでのADFスキン・プロパティ

ADFスキン・プロパティを使用して、CSSのみでは指定できない、またはコンポーネントのプロパティに依存していて、その結果、CSSを使用して定義できない動作や外観を定義します。たとえば、ADF Facesでは、ブラウザでのアニメーションをサポートしていますが、CSS 3アニメーションは使用できません。アニメーションの継続時間を構成する場合、ADFスキン・プロパティを使用して行います。例31-1に、ADFスキン・プロパティにより、ADF Faces carouselコンポーネントでスピン・アニメーションが500ミリ秒間表示されるように継続時間がどのように定義されるかを示します。

例31-1 ADFスキン・プロパティを使用したスピン・アニメーションの長さの指定

af|carousel {
-tr-spin-animation-duration: 500;
}

31.1.2 外観のカスタマイズの追加機能

アプリケーションの外観のカスタマイズを決定する前に、その他のADF Faces機能とADF Faces以外の機能を理解しておくと役に立ちます。次のリンクでは、知っておくと役に立つ詳細情報を提供しています。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- 国際化およびローカライズ: アプリケーションに適用するために作成するADFスキンは、ADF Facesページを国際化およびローカライズするためのプロセスの一部としてカスタマイズできます。このプロセスの詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- アクセシビリティ: アプリケーションに適用するために作成するADFスキンは、ADF Facesをアクセス可能にするためのプロセスの一部としてカスタマイズできます。このプロセスの詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

31.2 コンポーネントのスタイル・プロパティの変更

コンポーネントのスタイル関連のプロパティのinlineStyleおよびstyleClass(どちらもルートDOM要素上でレンダリング)を変更することにより、コンポーネントのルック・アンド・フィールを設計時に調整できます。設計時に指定したスタイル関連プロパティ(inlineStyleまたはstyleClass)は、コンポーネントの特定のインスタンスに対してアプリケーションのADFスキンで指定された対応するスタイルをオーバーライドします。コンポーネントのinlineStyleプロパティに指定した値は、styleClass属性に設定された値をオーバーライドします。

inlineStyle属性は、CSSスタイルのセミコロンで区切られた文字列で、background-color:red; color:blue; font-style:italic; padding:3pxのように、個々の属性を設定できます。styleClass属性は、一連のインライン・スタイルのグループ化に使用されるCSSスタイル・クラス・セレクタです。スタイル・クラスは、.AFInstructionTextなどのADFパブリック・スタイル・クラスを使用して定義でき、af:outputTextコンポーネントに表示されるテキストのすべてのプロパティを設定します。

特定のセレクタの場合、カスタム・コンポーネントのスタイル・プロパティはレンダラのクラスを作成することにより取得できます。詳細は、34.4.7項「レンダラのクラスの作成方法」を参照してください。

警告:

コンポーネントを拡大するためにスタイルを使用しないでください。拡大を目的としたスタイルの使用は宣言的でなく、多くの場合、異なるWebブラウザ間で動作の一貫性がなくなります。かわりに、ADF Facesフレームワークに用意されているジオメトリ管理を使用して、コンポーネントを拡大できます。レイアウトおよび拡大の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

31.2.1 インライン・スタイルの設定方法

inlineStyle属性を定義して、コンポーネントにインライン・スタイルを設定します。インライン・スタイルは、コンポーネントのインスタンス用コンポーネントのスタイルの指定に使用できます。詳細は、9.4項「コンテンツをページ全体に拡大するための設定」を参照してください。

始める前に:

inlineStyle属性が他の属性とどのように関連しているかについて理解しておくと役立ちます。詳細は、31.2項「コンポーネントのスタイル・プロパティの変更」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、31.1.2項「外観のカスタマイズの追加機能」を参照してください。

インライン・スタイルを設定する手順:

1. JSFページで、インライン・スタイルを設定するコンポーネントを選択します。

2. 「プロパティ」ウィンドウで「スタイル」セクションを展開し、使用するインライン・スタイルをインライン・スタイル・フィールドに入力します。
または、図31-4に示すように、ドロップダウン・リストから必要なスタイル機能を選択できます。

図31-4 inlineStyle属性の設定

JDeveloperにより、コンポーネントの対応するコードがJSFページに追加されます。例31-2に、inlineStyle属性が指定されたaf:outputTextコンポーネントのソースを示します。

例31-2 ページ・ソースのinlineStyle

<af:outputText value="outputText1" id="ot1"
inlineStyle="color:Red; text-decoration:overline;"/>

3. inlineStyle属性自体にEL式を使用して、インライン・スタイル属性を条件付きで設定できます。たとえば、アクションがまだ完了していない場合に日付を赤で表示するには、例31-3のようなコードを使用できます。

例31-3 inlineStyle属性の設定に使用されるEL式

<af:outputText value="#{row.assignedDate eq
null?res['srsearch.unassignedMessage']:row.assignedDate}"
inlineStyle="#{row.assignedDate eq null?'color:rgb(255,0,0);':''}"
id="ot3"/>

4. ADF Facesコンポーネントには、ルートDOM要素に登録されていないスタイル設定には使用できない、その他のスタイル属性もあります。たとえば、af:inputTextコンポーネントの場合、例31-4に示すように、contentStyleプロパティを使用して要素のテキストを設定します。

例31-4 contentStyleプロパティの使用

<af:inputText value="outputText1"
contentStyle="color:Red;" id="it1"/>

31.2.2 スタイル・クラスの設定方法

スタイル・クラスを使用して、コンポーネントのスタイルを定義できます。スタイル・クラスは、一連のインライン・スタイルをグループ化するために作成します。スタイル・クラスを参照するには、styleClass属性を使用します。

始める前に:

styleClass属性が他の属性とどのように関連しているかについて理解しておくと役立ちます。詳細は、31.2項「コンポーネントのスタイル・プロパティの変更」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、31.1.2項「外観のカスタマイズの追加機能」を参照してください。

スタイル・クラスを使用してスタイルを設定する手順:

1. JSFページで、スタイルを定義するコンポーネントを選択します。

2. 「プロパティ」ウィンドウで「スタイル」セクションを展開し、コンポーネントで使用するスタイル・クラスの名前を「StyleClass」フィールドに入力します。
例31-5に、ページ・ソースに使用されているスタイル・クラスの例を示します。

例31-5 スタイル・クラスを使用するためのページ・ソース

<af:outputText value="Text with a style class"
styleClass="overdue"  id="ot4"/>

3. styleClass属性にEL式を使用して、スタイル属性を条件付きで設定できます。たとえば、アクションがまだ完了していない場合に日付を赤で表示するには、例31-3のようなコードを使用できます。

31.3 エンド・ユーザーによるアプリケーションのADFスキン変更の許可

エンド・ユーザーが他のADFスキンを選択できるように、アプリケーションを構成できます。エンド・ユーザーが必要により適したADFスキンを使用して、アプリケーションのページをレンダリングできるようにする場合に、この機能を構成します。たとえば、アプリケーションで、ユーザーのブラウザが日本語のときに、日本のロケール固有の特徴を持つADFスキンを使用する場合などです。別の例としては、障害を持つユーザーにとってアプリケーションのページをよりアクセスしやすいものにするために構成されたADFスキンをアプリケーションで使用する場合があります。

図31-5では、コンポーネント(af:commandMenuItemなど)を構成して、エンド・ユーザーが実行時にアプリケーションで使用されるADFスキンを変更できるようにすることで、この機能をどのように実装するかを示しています。JSFページ上のコンポーネントを構成して、後からtrinidad-configファイルのskin-familyプロパティにより評価されるscope値を設定します。

図31-5 アプリケーションのADFスキンの変更

31.3.1 エンド・ユーザーによるアプリケーションのADFスキン変更を許可する方法

trinidad-configファイルのskin-familyプロパティの値の更新を可能にするコンポーネントを公開することにより、エンド・ユーザーがアプリケーションのADFスキンを変更できるようにします。

始める前に:

加えた変更が機能にどのような影響を与えるかについて理解しておくと役立ちます。詳細は、31.3項「エンド・ユーザーによるアプリケーションのADFスキン変更の許可」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、31.1.2項「外観のカスタマイズの追加機能」を参照してください。

エンド・ユーザーにアプリケーションのADFスキンの変更を許可する手順:

1. スキン・ファミリの設定に使用するコンポーネントを構成するメインのJSFページを開きます。

2. 図31-5のように、エンド・ユーザーが実行時に多数の使用可能なADFスキンの1つを選択できるようにする多数のコンポーネント(af:commandMenuItemコンポーネントなど)を構成します。
例31-6に、図31-5のように、エンド・ユーザーが実行時に使用可能なADFスキンを選択できるようにするaf:commandMenuItemコンポーネントの構成方法を示します。各af:commandMenuItemコンポーネントにより、actionListener属性の値を指定します。エンド・ユーザーがメニュー項目をクリックすると、この属性でactionEventがskinsというマネージドBean上のメソッド(skinMenuAction)に渡されます。

例31-6 コンポーネントを使用したスキン・ファミリの設定

<af:menu text="Change Skin" id="skins" binding="#{backing_ChangeSkin.skins}">
<af:commandMenuItem id="skin1" text="skyros" type="radio"
actionListener="#{skins.skinMenuAction}"
selected="#{skins.skinFamily=='skyros'}"/>
<af:commandMenuItem id="skin3" text="fusion" type="radio"
actionListener="#{skins.skinMenuAction}"
selected="#{skins.skinFamily=='fusion'}"/>
<af:commandMenuItem id="skin4" text="fusion-projector" type="radio"
actionListener="#{skins.skinMenuAction}"
selected="#{skins.skinFamily=='fusion-projector'}"/>
<af:commandMenuItem id="skin5" text="simple" type="radio"
actionListener="#{skins.skinMenuAction}"
selected="#{skins.skinFamily=='simple'}"/>
<af:commandMenuItem id="skin6" text="skin1" type="radio"
actionListener="#{skins.skinMenuAction}"
selected="#{skins.skinFamily=='skin1'}"/>
</af:menu>

3. エンド・ユーザーにより選択されたADFスキンの値を格納するために、skinsというマネージドBean上にメソッド(skinMenuActionなど)を記述します。例31-7に、エンド・ユーザーが選択した値をとり、それをマネージドBean内のskinFamilyの値の設定に使用するメソッドを示します。例31-7内のメソッドでは、skinFamilyの値を設定した後、ページを再ロードするメソッドも呼び出します。

例31-7 ADFスキンを変更するためのマネージドBeanのメソッド

public void skinMenuAction(ActionEvent ae)
{
RichCommandMenuItem menuItem = (RichCommandMenuItem)ae.getComponent();

// Invoke another managed bean method to set the value of skinFamily
setSkinFamily(menuItem.getText());

// Invoke a method to reload the page. The application reloads the page
// using the newly selected ADF skin.
reloadThePage();
}

4. 「アプリケーション」ウィンドウで、trinidad-config.xmlファイルをダブルクリックします。

5. trinidad-config.xmlファイルで、EL式を記述してスキン・ファミリを動的に評価します。
<skin-family>#{skins.skinFamily}</skin-family>

31.3.2 実行時の処理: エンド・ユーザーによるアプリケーションのADFスキンの変更方法

実行時に、エンド・ユーザーは公開されたコンポーネントを使用して、別のADFスキンを選択します。例31-6では、これは多数のaf:commandMenuItemコンポーネントの1つです。このコンポーネントは、エンド・ユーザーが選択した値をマネージドBeanに発行し、次にこれがマネージドBeanのプロパティ(skinFamily)の値を設定します。実行時に、trinidad-configファイルの<skin-family>プロパティでは、EL式を使用してマネージドBeanから値を読み取ります。

32 ページの国際化およびローカライズ

この章では、ADFアプリケーションを様々なロケールおよび国際的なユーザー環境で使用できるように構成する方法について説明します。JDeveloperで自動的にリソース・バンドルを作成する機能、リソース・バンドルおよびロケールを手動で定義する方法およびアプリケーションのADF Facesのローカリゼーション・プロパティの構成方法などの主要な機能についても説明します。

この章では、次の項目について説明します。

- 32.1項「ADF Facesページの国際化およびローカライズについて」

- 32.2項「JDeveloperにおける自動リソース・バンドル統合の使用」

- 32.3項「リソース・バンドルおよびロケールの手動による定義」

- 32.4項「エンド・ユーザーが実行時にロケールを指定するためのページの構成」

- 32.5項「ADF Facesのオプションのローカライゼーション・プロパティの構成」

32.1 ADF Facesページの国際化およびローカライズについて

国際化は、特定地域の言語と文化に適応しやすくするための、製品の設計および開発のプロセスです。ローカライゼーションは、テキストを変換し、ロケール固有のコンポーネントを追加することで、特定地域の言語または文化に製品を適応させるプロセスです。上手くローカライズされたアプリケーションは、その地域で開発されたように見えます。JDeveloperは、抽象クラスjava.util.ResourceBundleを使用してロケール固有のリソースを提供し、ADF Facesコンポーネントをローカライズしやすいようにサポートします。

複数の国のユーザーがアプリケーションを表示する場合、ユーザーのブラウザの言語設定に対応する適切な言語が表示されるよう、様々なロケールを使用できるようにJSFページまたはアプリケーションを構成できます。たとえば、ページがイタリアで表示されるとわかっている場合、ユーザーのブラウザがイタリア語を使用するように設定されているときにはブラウザ・ページ内のテキスト文字列がイタリア語で表示されるように、ページをローカライズできます。

ADF Facesコンポーネントには、コンポーネントの一部であるテキストが含まれている場合があり、たとえばaf:tableコンポーネントではリソース文字列af_table.LABEL_FETCHINGが、ブラウザで表示されるメッセージ・テキスト用に使用され、一方af:tableコンポーネントでは、データの初期ロード中またはユーザーが表をスクロール中に、データがフェッチされます。JDeveloperでは、これらのテキスト・リソースを28言語に自動的に変換します。これらのテキスト・リソースは、リソース・バンドルで参照されます。faces-config.xmlファイルの<supported-locale>要素を指定して、アプリケーションでサポートする言語ごとにサポートを有効にする必要があります。たとえば、イタリア語を使用するようにブラウザを設定し、faces-config.xmlファイルに<supported-locale>it</supported-locale>を追加した場合、コンポーネント内に含まれるテキストはすべて自動的にイタリア語で表示されます。詳細は、32.3.4項「アプリケーションへのロケールの登録方法」を参照してください。

text属性を設定してaf:buttonコンポーネントのラベルを定義する場合など、コンポーネントに追加するテキストには、実際のテキストが含まれているリソース・バンドルを指定して、各ロケール版のリソース・バンドルを作成し、<locale-config>要素を追加して、アプリケーションのfaces-config.xmlファイルにデフォルトおよびサポートされるロケールを定義する必要があります。また、アプリケーションのすべてのページでリソース・バンドルを使用できるようにするには、アプリケーションのfaces-config.xmlファイルに<resource-bundle>要素を追加する必要があります。一度リソース・バンドルを構成および登録すると、式ビルダーにそのバンドルのキーが表示されるため、アプリケーション・ページ内でバンドルを参照しやすくなります。

ADF Facesコンポーネントに追加するテキストのテキスト・リソースを作成するプロセスを簡略化するために、JDeveloperでは、ビジュアル・エディタの変換可能な文字列に関する、リソース・バンドルの自動同期がサポートされています。ビジュアル・エディタまたは「プロパティ」ウィンドウで直接コンポーネントを編集すると、ベース・リソース・バンドルにテキスト・リソースが自動的に作成されます。詳細は、32.2項「JDeveloperにおける自動リソース・バンドル統合の使用方法」を参照してください。

注意:

データベースから取得されたテキストは変換されません。このドキュメントでは、静的テキストのローカライズ方法については説明しますが、データベース内に格納されているテキストのローカライズ方法については説明しません。

32.1.1 ページの国際化およびローカライズのユースケースおよび例

たとえば、「My Purchase Requests」というタイトルのパネル・ボックスがあるとします。My Purchase Requestsという文字列をaf:panelBoxコンポーネントのtext属性の値として設定するのではなく、text属性の値をUIResourcesリソース・バンドル内のキーにバインドします。例32-1に示すように、UIResourcesリソース・バンドルは、アプリケーションのfaces-config.xmlファイルに登録されます。

例32-1 JSF構成ファイルのリソース・バンドル要素

<resource-bundle>
<base-name>resources.UIResources</base-name>
<var>res</var>
</resource-bundle>

リソース・バンドルには、EL式に使用可能な変数名(この場合はres)が提供されます。例32-2に示すように、ページでは、af:panelBoxコンポーネントのtext属性が、そのリソース・バンドル内のmyDemo.pageTitleキーにバインドされます。

例32-2 リソース・バンドルを参照するコンポーネント・テキスト

<af:panelBox text="#{res['myDemo.pageTitle']}"
....
id="pb1">

UIResourcesリソース・バンドル内には、アプリケーションの各ページに表示されるすべての静的テキスト、メッセージのテキスト、グローバル・テキスト(汎用ラベルなど)に対する英語のエントリがあります。例32-3に、myDemoページのキーを示します。

例32-3 英語で表示されるmyDemoページのリソース・バンドル・キー

#myDemo Screen
myDemo.pageTitle=My Purchase Requests
myDemo.menubar.openLink=Open Requests
myDemo.menubar.pendingLink=Requests Awaiting customer
myDemo.menubar.closedLink=Closed Requests
myDemo.menubar.allRequests=All Requests
myDemo.menubar.newLink=Create New Purchase Request
myDemo.selectAnd=Select and
myDemo.buttonbar.view=View
myDemo.buttonbar.edit=Edit

バナー・イメージのテキストおよびデータベースから取得されたデータは変換されないことに注意してください。

例32-4に、イタリア語ロケール・バージョンのリソース・バンドル(UIResources_it)を示します。選択ファセットのタイトルに対するエントリがないのに、「Select」が自動的に「Seleziona」に変換されていることに注意してください。これは、このテキストがADF Facestableコンポーネントの選択ファセットの一部になっているためです。

例32-4 イタリア語で表示されるmyDemoページのリソース・バンドル・キー

#myDemo Screen
myDemo.pageTitle=Miei Ticket
myDemo.menubar.openLink=Ticket Aperti
myDemo.menubar.pendingLink=Ticket in Attesa del Cliente
myDemo.menubar.closedLink=Ticket Risolti
myDemo.menubar.allRequests=Tutti i Ticket
myDemo.menubar.newLink=Creare Nuovo Ticket
myDemo.selectAnd=Seleziona e
myDemo.buttonbar.view=Vedere Dettagli
myDemo.buttonbar.edit=Aggiorna

32.1.2 ページの国際化およびローカライズの追加機能

アプリケーションを国際化またはローカライズする前に、その他のADF Faces機能を理解しておくと役に立ちます。また、いったんアプリケーションを国際化またはローカライズすると、アクセシビリティなどの機能を追加したり、ADF Facesコンポーネントを右から左にレンダリングしたりする必要があることに気付く場合があります。使用できるその他の機能へのリンクは、次のとおりです。

- テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。

- 擬似クラス: ADFスキンでは、特定の地域でのアプリケーションのレンダリングを変更するために使用できる多数の擬似クラスをサポートしています。たとえば、:rtl擬似クラスでは、ADF Facesコンポーネントを右から左へレンダリングします。これは、アプリケーションをアラビア語やヘブライ語など、右から左へ読む言語にローカライズする場合に便利です。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- アクセシビリティ: アプリケーション内のページをアクセス可能にできます。詳細は、第33章「アクセス可能なADF Facesページの開発」を参照してください。

- グローバル・リソース文字列: デフォルトのリソース・バンドルには、ADF Facesコンポーネントでサポートされるグローバル・リソース文字列と、個々のコンポーネントに固有のリソース文字列が格納されています。これらのリソース文字列の詳細は、Oracle ADF Facesスキン・セレクタ・タグ・リファレンスを参照してください。

32.2 JDeveloperにおける自動リソース・バンドル統合の使用

ビジュアル・エディタでADF Facesコンポーネントを編集する際、JDeveloperでは、デフォルトのリソース・バンドルへのテキスト・リソースの自動作成がサポートされています。ユーザー定義の文字列を静的な値として処理するには、32.2.1項「リソース・バンドル・オプションの設定方法」で説明されているように、「プロジェクト・プロパティ」ダイアログで「バンドルの自動同期化」チェック・ボックスを選択解除します。

自動リソース・バンドル統合は、ページまたはプロジェクトごとに1つのリソース・バンドルをサポートするように構成できます。

図32-1に示される「テキスト・リソースの選択」ダイアログを使用して変換可能なテキスト文字列を編集できます。このダイアログは、「プロパティ」ウィンドウで、変換可能なプロパティのプロパティ・フィールドにポインタを置くと表示されるアイコンをクリックして、ポップアップ・メニューから「テキスト・リソースの選択」を選択するとアクセスできます。このダイアログの使用方法の詳細は、第32.2.3項「JDeveloper生成リソース・バンドルでのエントリの作成方法」を参照してください。

図32-1 「テキスト・リソースの選択」ダイアログ

32.2.1 リソース・バンドル・オプションの設定方法

プロジェクトのリソース・バンドル・オプションは、「プロジェクト・プロパティ」ダイアログで設定できます。

始める前に:

JDeveloperでリソース・バンドルがどのように管理されるかを理解しておくと役立ちます。詳細は、32.2項「JDeveloperにおける自動リソース・バンドル統合の使用方法」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

プロジェクトにリソース・バンドル・オプションを設定する方法:

1. 「アプリケーション」ウィンドウで、プロジェクトをダブルクリックします。

2. 図32-2に示すように、「プロジェクト・プロパティ」ダイアログで、「リソース・バンドル」を選択してリソース・バンドル・オプションを表示します。

図32-2 「プロジェクト・プロパティ」の「リソース・バンドル」ダイアログ

3. JDeveloperにより自動的にデフォルトのリソース・ファイルが生成されるようにする場合は、「バンドルの自動同期化」を選択します。

4. 次に示すいずれかのリソース・バンドル・ファイル・オプションを選択します。

- 1プロジェクト当たり1バンドル - <ProjectName>.propertiesという名前のファイルに構成されます。

- 1ファイル当たり1バンドル - named <FileName>.propertiesという名前のファイルに構成されます。

5. ドロップダウン・リストからリソース・バンドル・タイプを選択します。

- リスト・リソース・バンドル

- プロパティ・バンドル

- XML Localization Interchange File Format (XLIFF)バンドル

6. 「OK」をクリックします。

32.2.2 リソース・バンドル・オプションを設定する場合の処理

JDeveloperでは、図32-2に示すように、「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプションのパートで行った選択に基づいて、特定のタイプの1つ以上のリソース・バンドルが生成されます。図32-1で示す「テキスト・リソースの選択」ダイアログを初めて呼び出したときに、リソース・バンドルが生成されます。

たとえば、「1プロジェクト当たり1バンドル」チェック・ボックスを選択し、「リソース・バンドル・タイプ」ドロップダウン・リストから「リスト・リソース・バンドル」値を選択するとします。初めて「テキスト・リソースの選択」ダイアログを呼び出すと、JDeveloperではそのプロジェクト用に1つのリソース・バンドルが生成されます。生成されたリソース・バンドルは、「プロジェクト・プロパティ」ダイアログのデフォルトのプロジェクト・バンドル名をとったJavaクラスです(ViewControllerBundle.javaなど)。

JDeveloperでは、「XMLローカライズ交換ファイル形式(XLIFF)バンドル」オプションを選択した場合は.xlfファイルとしてリソース・バンドルが、「プロパティ・バンドル」オプションを選択した場合は.propertiesファイルが生成されます。

デフォルトでは、JDeveloperにより、プロジェクトの「アプリケーション・ソース」ディレクトリの「view」サブディレクトリに、生成されたリソース・バンドルが作成されます。

32.2.3 JDeveloper生成リソース・バンドルでのエントリの作成方法

JDeveloperでは、「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプションのパートで選択した値に基づいて、1つ以上のリソース・バンドルが生成されます。「Properties」ウィンドウのコンポーネント・プロパティから「テキスト・リソースの選択」ダイアログを初めて呼び出したときに、リソース・バンドルが生成されます。

JDeveloperでは、「テキスト・リソースの選択」ダイアログで入力した値に基づいて、リソース・バンドルにキー値のペアが記述されます。また、リソース・バンドルから既存のキー値のペアを選択して、コンポーネントのランタイム表示値をレンダリングすることもできます。

始める前に:

JDeveloperでリソース・バンドルがどのように管理されるかを理解しておくと役立ちます。詳細は、32.2項「JDeveloperにおける自動リソース・バンドル統合の使用方法」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

JDeveloperで生成されたリソース・バンドルでエントリを作成する手順:

1. JSFページで、ランタイム値を記述するコンポーネントを選択します。
たとえば、af:inputTextコンポーネントを選択します。

2. リソース・バンドルに新しいエントリを作成するには、「プロパティ」ウィンドウで、プロパティ・フィールドにポインタを置くと表示されるアイコンをクリックしたときに表示されるポップアップ・メニューから「テキスト・リソースの選択」を選択します。
ポップアップ・メニューの「テキスト・リソースの選択」エントリは、テキスト・リソースをサポートするプロパティに対してのみ表示されます。たとえば、af:inputTextコンポーネントの「ラベル」プロパティです。

3. 実行時に「表示値」入力フィールドに表示する値を、図32-1に示すように記述します。
JDeveloperにより、「キー」入力フィールドに値が生成されます。

4. 必要に応じて、「説明」入力フィールドに説明を記述します。

注意:

JDeveloperでは、「表示値」入力フィールドに入力した値と一致するテキスト・リソースが存在する場合、「一致するテキスト・リソース」フィールドに一致するテキスト・リソースが表示されます。

5. 「保存して選択」をクリックします。

32.2.4 JDeveloper生成リソース・バンドルでエントリを生成する場合の処理

JDeveloperでは、「テキスト・リソースの選択」ダイアログで定義したキー値のペアをリソース・バンドルに記述します。「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプションのパートで選択するオプションにより、JDeveloperでキー値のペアが記述されるリソース・バンドルのタイプが決まります。詳細は、32.2.2項「リソース・バンドル・オプションを設定する場合の処理」を参照してください。

リソース・バンドル・エントリを定義したコンポーネント・プロパティでは、EL式を使用して、実行時にリソース・バンドルから値を取得します。たとえば、af:inputTextコンポーネントの「ラベル」プロパティは、次の式に似たEL式を参照します。

#{viewcontrollerBundle.Label1}

viewcontrollerBundleはリソース・バンドルを参照し、Label1はランタイム値のキーです。

32.3 リソース・バンドルおよびロケールの手動による定義

リソース・バンドルには多数の名前の付いたリソースが含まれており、名前付きリソースのデータ型はStringです。バンドルに親バンドルがある場合があります。リソースがバンドル内に見つからない場合、親バンドルでリソースが検索されます。リソース・バンドルは、Javaクラス、プロパティ・ファイルまたはXLIFFファイルのいずれかです。抽象クラスjava.util.ResourceBundleには次の2つのサブクラスがあります。

- java.util.PropertyResourceBundle

- java.util.ListResourceBundle

java.util.PropertyResourceBundleはプロパティ・ファイルに格納され、これは変換可能なテキストが含まれるプレーン・テキスト・ファイルです。プロパティ・ファイルには、Stringオブジェクトについてのみ値を含めることができます。他のタイプのオブジェクトを格納する必要がある場合、かわりにjava.util.ListResourceBundleクラスを使用する必要があります。

XLIFFの使用の詳細は、http://docs.oasis-open.org/xliff/xliff-core/xliff-core.htmlを参照してください。

他のロケールのサポートを追加するには、キーの値をローカライズ済の値で置き換え、言語コード(必須)と、国コードおよび名前の識別子としてのバリアント(オプション)を付加したプロパティ・ファイル(たとえば、UIResources_it.properties)を保存します。

java.util.ListResourceBundleクラスでは、リソースが名前/値の配列で管理されます。各java.util.ListResourceBundleクラスはJavaクラス・ファイル内に含まれます。ロケール固有のオブジェクトをjava.util.ListResourceBundleクラスに格納できます。追加ロケールのサポートを加えるには、ベース・クラスからサブクラスを作成し、それをロケールまたは言語の拡張子の付いたファイルに保存して、それを変換し、クラス・ファイルにコンパイルします。

ResourceBundleクラスはフレキシブルです。最初にロケール固有のStringオブジェクトをjava.util.PropertyResourceBundleファイルに挿入した場合でも、後でそれらのオブジェクトをListResourceBundleクラスに移動できます。キーを検出するためのコールでは、java.util.ListResourceBundleクラスおよびjava.util.PropertyResourceBundleファイルの両方が検索されるため、コードに影響はありません。

プロパティよりもクラスの方が優先されます。このため、クラス・ファイルとプロパティ・ファイルの両方に同じ言語に対するキーが存在する場合、クラス・ファイル内の値がユーザーに表示されます。また、ロードするバンドルを決定するための検索アルゴリズムは次のとおりです。

1. (ベース・クラス)+(特定の言語)+(特定の国)+(特定のバリアント)

2. (ベース・クラス)+(特定の言語)+(特定の国)

3. (ベース・クラス)+(特定の言語)

4. (ベース・クラス)+(デフォルトの言語)+(デフォルトの国)+(デフォルトのバリアント)

5. (ベース・クラス)+(デフォルトの言語)+(デフォルトの国)

6. (ベース・クラス)+(デフォルトの言語)

たとえば、ユーザーのブラウザがイタリア語ロケールに設定されていて、アプリケーションのデフォルト・ロケールが米語の場合、アプリケーションでは最も近いものを検出するために、次の順序で検索が実行されます。

1. it_IT

2. it

3. en_US

4. en

5. ベース・クラス・バンドル

ヒント:

バンドルのロードに使用されたgetBundleメソッドは、ベース・クラス・バンドルを返す前に、デフォルトのロケール・クラスを検索します。一致するものが見つからなかった場合は、MissingResourceExceptionエラーがスローされます。接尾辞のないベース・クラスが、デフォルトとして常に存在している必要があります。そうでない場合は一致が検出されず、例外がスローされます。

コンポーネント自体に含まれていないテキスト文字列がすべて含まれたベース・リソース・バンドルを作成する必要があります。このバンドルは、アプリケーションのデフォルト言語で作成する必要があります。リソース・バンドルは、プロパティ・ファイル、XLIFFファイルまたはJavaクラスとして作成できます。リソース・バンドル・ファイルを作成したら、「リソース・バンドルの編集」ダイアログを使用してファイルを編集できます。

32.3.1 リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する方法

リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成できます。

始める前に:

どのタイプのリソース・バンドルを作成できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する手順:

1. 「アプリケーション」ウィンドウでリソース・バンドル・ファイルを置きたい場所を右クリックし、「新規」→「ギャラリから」を選択します。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、ベース・ファイルと同じディレクトリにファイルを保存してください。

2. 「新規ギャラリ」で、「一般」、「ファイル」の順に選択し、「OK」をクリックします。

3. 「ファイルの作成」で、プロパティ・ファイルを使用するファイルには表記規則<name><_lang>.propertiesを使用して、XLIFFファイルを使用するファイルには表記規則<name><_lang>.xlfを使用して、ファイルの名前を入力します。<_lang>接尾辞(ドイツ語では_deなど)は翻訳したファイルに付けられ、元となる言語では省略されます。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、ファイル名にISO 639の小文字の言語コードを追加する必要があります。たとえば、UIResourcesバンドルのイタリア語バージョンは、UIResources_it.propertiesになります。複数の国で1つの言語を使用する場合は、ISO 3166の大文字の国コードを追加できます(たとえば、スイスの場合はit_CH)。また、オプションの非標準バリアント(たとえば、プラットフォームや地域の情報を提供するバリアント)を追加することもできます。

ベース・リソース・バンドルを作成する場合は、コードを追加しないでください。

4. ファイルにコンテンツを入力します。キーと値のペアを入力することで、コンテンツを手動で入力できます。32.3.3項「リソース・バンドル・ファイルの編集方法」で説明されているように、「リソース・バンドルの編集」ダイアログを使用してキーと値のペアを入力できます。

- プロパティ・ファイルを作成している場合は、このバンドルの静的テキストの文字列ごとに、キーと値を作成します。キーは、文字列の一意の識別子です。値は、バンドルの言語でのテキスト文字列です。ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、このバージョン内に存在しないキーは、ベース・クラスから値を継承します。

注意:

非ASCII文字はすべてUnicodeエスケープにするか、コンパイル時のエンコーディングを明示的に指定する必要があります。たとえば、次のように指定します。

javac -encoding ISO8859_5 UIResources_it.java

たとえば、myDemoページのタイトルのキーと値は、次のようになります。

myDemo.pageTitle=My Purchase Requests

- XLIFFファイルを作成している場合は、キーと値のペアごとに適切なタグを入力します。次に例を示します。

<?xml version="1.0" encoding="windows-1252" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
<file source-language="en" original="myResources" datatype="xml">
<body>
<trans-unit id="NAME">
<source>Name</source>
<target/>
<note>Name of employee</note>
</trans-unit>
<trans-unit id="HOME_ADDRESS">
<source>Home Address</source>
<target/>
<note>Adress of employee</note>
</trans-unit>
<trans-unit id="OFFICE_ADDRESS">
<source>Office Address</source>
<target/>
<note>Office building </note>
</trans-unit>
</body>
</file>
</xliff>

5. すべての値を入力したら、「OK」をクリックします。

32.3.2 リソース・バンドルをJavaクラスとして作成する方法

リソース・バンドルをJavaクラスとして作成できます。

始める前に:

どのタイプのリソース・バンドルを作成できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

リソース・バンドルをJavaクラスとして作成する手順:

1. 「アプリケーション」ウィンドウでファイルを置きたい場所を右クリックし、「新規」→「ギャラリから」を選択します。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、これをベース・ファイルと同じディレクトリに保存する必要があります。

2. 「新規ギャラリ」で、「一般」、「Javaクラス」の順に選択し、「OK」をクリックします。

3. 「Javaクラスの作成」ダイアログで、クラスの名前とパッケージを入力します。クラスはjava.util.ListResourceBundleを拡張している必要があります。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、クラス名にISO 639の小文字の言語コードを追加する必要があります。たとえば、UIResourcesバンドルのイタリア語バージョンは、UIResources_it.javaになります。複数の国で1つの言語を使用する場合は、ISO 3166の大文字の国コードを追加できます(たとえば、スイスの場合はit_CH)。また、オプションの非標準バリアント(たとえば、プラットフォームや地域の情報を提供するバリアント)を追加することもできます。

ベース・リソース・バンドルを作成する場合は、コードを追加しないでください。

4. キーと値のペアの配列を返すgetContents()メソッドを実装します。適切な値を使用して、バンドルのキーの配列を作成します。または、32.3.3項「リソース・バンドル・ファイルの編集方法」で説明されているように、「リソース・バンドルの編集」ダイアログを使用して自動的にコードを生成します。 例32-5に、ベース・リソース・バンドルのJavaクラスのサンプルを示します。

注意:

キーはStringオブジェクトであることが必要です。ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、このバージョン内に存在しないキーは、ベース・クラスから値を継承します。

例32-5 ベース・リソース・バンドルのJavaクラス

package sample;

import java.util.ListResourceBundle;

public class MyResources extends ListResourceBundle {

@Override
protected Object[][] getContents() {
return contents;
}

static final Object[][] contents {
{"button_Search", "Search"},
{"button_Reset", "Reset"}
};
}

32.3.3 リソース・バンドル・ファイルの編集方法

リソース・バンドル・プロパティ・ファイル、XLIFFファイルまたはJavaクラス・ファイルを作成したら、ソース・エディタを使用して編集できます。

始める前に:

どのタイプのリソース・バンドルを定義し編集できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

リソース・バンドルの作成後に編集する手順:

1. メイン・メニューから「アプリケーション」→「リソース・バンドルの編集」を選択します。

2. 「リソース・バンドルの編集」ダイアログで、図32-3に示されているように、「リソース・バンドル」ドロップダウン・リストから編集するリソース・バンドル・ファイルを選択するか、編集するリソース・バンドル・ファイルが「リソース・バンドル」ドロップダウン・リストに表示されない場合は、「検索」アイコンをクリックして、「リソース・バンドルの選択」ダイアログを起動します。

図32-3 「リソース・バンドルの編集」ダイアログ

3. 「リソース・バンドルの選択」ダイアログで、「ファイル・タイプ」ドロップダウン・リストからファイル・タイプを選択します。図32-4に示すように、編集するリソース・バンドルに移動します。「OK」をクリックします。

図32-4 「リソース・バンドルの選択」ダイアログ

4. 「リソース・バンドルの編集」ダイアログで、図32-5に示すように、「追加」アイコンをクリックしてキーと値のペアを追加します。完了したら「OK」をクリックします。

図32-5 リソース・バンドルへの値の追加

32.3.4 アプリケーションへのロケールの登録方法

アプリケーションでサポートするロケールを、アプリケーションのfaces-config.xmlファイルに登録する必要があります。

始める前に:

リソース・バンドルを手動でどのように管理できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

アプリケーションのロケールを登録する手順:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを展開し、faces-config.xmlをダブルクリックします。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 概要エディタで、「アプリケーション」ナビゲーション・タブをクリックします。

4. 図32-6に示されているとおり、「アプリケーション」ページの「ロケール構成」セクションで「追加」をクリックしてロケールのコードを追加します。

図32-6 faces-config.xmlへのロケールの追加

ロケールを追加したら、faces-config.xmlファイルのコードは次のようになります。

<locale-config>
<default-locale>en</default-locale>
<supported-locale>ar</supported-locale>
<supported-locale>ca</supported-locale>
<supported-locale>cs</supported-locale>
<supported-locale>da</supported-locale>
<supported-locale>de</supported-locale>
<supported-locale>zh_Ch</supported-locale>
</locale-config>

32.3.5 アプリケーションへのリソース・バンドルの登録方法

アプリケーションで使用するリソース・バンドルを、アプリケーションのfaces-config.xmlファイルに登録する必要があります。

始める前に:

リソース・バンドルを手動でどのように管理できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

リソース・バンドルを登録するには:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを展開し、faces-config.xmlをダブルクリックします。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 概要エディタで、「アプリケーション」ナビゲーション・タブをクリックします。

4. 「アプリケーション」ページの「リソース・バンドル」セクションで、「追加」をクリックして、図32-7に示すように、アプリケーションにより使用されるメッセージが含まれたベース・バンドルの完全修飾名およびEL式でバンドルの参照に使用できる変数名を入力します。

図32-7 faces-config.xmlへのリソース・バンドルの追加

リソース・バンドルを追加したら、faces-config.xmlファイルのコードは次のようになります。

<resource-bundle>
<base-name>oracle.summit.SummitADF</base-name>
<var>res</var>
</resource-bundle>

32.3.6 アプリケーションでのリソース・バンドルの使用方法

ページ・エンコーディングとレスポンス・エンコーディングを、サポートされているすべての言語に設定し、リソース・バンドルにバインドします。

始める前に:

リソース・バンドルを手動でどのように管理できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

ページ上でベース・リソース・バンドルを使用する手順:

1. ページがJSPドキュメントの場合は、ページ・エンコーディングとレスポンス・エンコーディングを、サポートされているすべての言語のスーパーセットに設定します。エンコーディングが設定されていない場合、ページ・エンコーディングはデフォルトで、ページ・ディレクティブのcontentType属性を使用して設定されたレスポンス・エンコーディングの値に設定されます。例32-6に、サンプル・ページのエンコーディングを示します。

例32-6 ページおよびレスポンスのエンコーディング

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>

2. <resource-bundle>要素用にfaces-config.xmlファイルに定義されている変数を使用して、ページ上に表示される静的テキストの文字列を表すすべての属性を、リソース・バンドル内の適切なキーにバインドします。例32-7に、myDemoページの「View」ボタンのコードを示します。

例32-7 リソース・バンドルへのバインド

<af:button text="#{res['myDemo.buttonbar.view']}"
. . . />

ヒント:

次の構文をソース・エディタに入力すると、JDeveloperでは、リソース・バンドル内の文字列に解決されるキーのドロップダウン・リストが表示されます。

<af:button text="#{res.

ドロップダウン・リストからキーを選択すると、JDeveloperによりEL式が完成されます。

3. adfBundleキーワードを使用して、特定のリソース・バンドルのリソース文字列をJSFページのEL式として解決することもできます。
使用書式は#{adfBundle[ bundleID ] [ resource_Key ]}で、bundleIDは完全修飾バンドルID (project.EmpMsgBundleなど)、resource_Keyはバンドル内のリソース・キー(Deptno_LABELなど)です。例32-8では、特定のリソース・バンドルのリソース文字列をボタンのテキストの指定に使用するために、adfBundleがどのように使用されるかを示しています。

例32-8 adfBundleを使用したバインド

<af:button text="#{adfBundle['project.EmpMsgBundle'] ['Deptno_LABEL']}"

32.3.7 ADFスキンおよびコントロールのヒントに関する必知事項

ADFスキンを使用する場合で、そのスキンのカスタム・リソース・バンドルを作成した場合は、そのリソース・バンドルのローカライズ・バージョンも作成する必要があります。同様に、コントロール・ヒントを使用してテキストを設定するアプリケーションの場合は、そのテキストに対して生成されたリソース・バンドルのローカライズ済バージョンを作成する必要があります。

32.3.8 カスタマイズ可能アプリケーションでのリソース・バンドルのオーバーライドに関する必知事項

オーバーライド・バンドルは、Oracle Metadata Services (MDS)フレームワークを使用して開発するカスタマイズ可能なアプリケーションで使用するベース・リソース・バンドルとは異なるキーと値のペアを持つリソース・バンドルです。オーバーライド・バンドルを作成する場合は、ベース・リソース・バンドルのオーバーライドをサポートするように、アプリケーションのadf-config.xmlファイルを構成する必要があります。たとえば、oracle.demo.CustAppUIBundleという名前のベース・リソース・バンドルがある場合、例32-9に示すように、アプリケーションのadf-config.xmlファイルのエントリを構成します。オーバーライド済としてマークされると、そのバンドルのカスタマイズはすべて、カスタマイズ可能なアプリケーションのオーバーライド・バンドルに格納されます。オーバーライド・バンドルは、JDeveloperのデフォルト・ロールおよびカスタマイズ可能なアプリケーションの両方で維持されます。このオーバーライド・バンドルを2つの場所で管理する必要性を回避するために、次のことをお薦めします。

- JDeveloperのデフォルト・ロールを使用してベース・リソース・バンドルから別のリソース・バンドルを作成する

- カスタマイズ可能なアプリケーションでオーバーライドするキーと値のペアを、ベース・リソース・バンドルからこの別のリソース・バンドルに追加する

カスタマイズ可能なアプリケーションで、これらのキーと値のペアを、別のリソース・バンドルから選択します。これにより、カスタマイズ可能なアプリケーションのオーバーライド・バンドルに新しいキーと値のペアが追加されないこと、カスタマイズ可能なアプリケーションのみがこのオーバーライド・バンドルを使用することが保証されます。

例32-9 adf-config.xmlファイルのオーバーライド・バンドルのエントリ

<?xml version="1.0" encoding="UTF-8" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
xmlns:config="http://xmlns.oracle.com/bc4j/configuration"
xmlns:adf="http://xmlns.oracle.com/adf/config/properties">
...
<adf-resourcebundle-config xmlns="http://xmlns.oracle.com/adf/resourcebundle/config">
<applicationBundleName>oracle/app.../xliffBundle/FusionAppsOverrideBundle</applicationBundleName>
<bundleList>
<bundleId override="true">oracle.demo.CustAppUIBundle</bundleId>
</bundleList>
</adf-resourcebundle-config>
</adf-config>

adf-config.xmlファイルの詳細は、A.4項「adf-config.xmlでの構成」を参照してください。MDSを使用したカスタマイズ可能なアプリケーション作成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「MDSを使用したアプリケーションのカスタマイズ」の章を参照してください。

32.4 エンド・ユーザーが実行時にロケールを指定するためのページの構成

エンド・ユーザーのブラウザのロケール設定によりランタイム・ロケールが決まるデフォルトの動作ではなく、エンド・ユーザーが実行時にロケールを指定できるように、アプリケーションを構成することができます。アプリケーションで、エンド・ユーザーが好みのロケールを指定し、それらの設定を保存できるようにする場合は、この機能を実装します。

32.4.1 エンド・ユーザーがロケールを指定するようにページを構成する方法

新規のページを作成するか、既存のページを開きます。それを次のように構成します。

- ロケール情報を格納するためにバッキングBeanを参照

- バッキングBean内のロケール情報を更新するために、エンド・ユーザーが実行時にコントロールを呼び出すことが可能

- f:viewタグのlocale属性によりバッキングBeanを参照

始める前に:

使用可能な構成オプションを理解しておくと役立ちます。詳細は、32.4項「エンド・ユーザーが実行時にロケールを指定するためのページの構成」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

エンド・ユーザーがロケールを指定するようにページを構成する手順:

1. ロケール情報を格納するためのバッキングBeanでページを作成します。
詳細は、3.4.1項「JSFページの作成方法」を参照してください。

2. エンド・ユーザーがロケールの変更に使用できるコントロール(selectOneChoiceコンポーネントなど)を指定します。
たとえば、「コンポーネント」ウィンドウで、「テキストおよび選択」パネルから、「選択」コンポーネントをドラッグし、ページにドロップします。

3. 例32-10に示すように、ロケール値が格納されているバッキングBeanにコントロールをバインドします。

例32-10 ロケールを選択するコンポーネント

<af:selectOneChoice label="Select Locale"
binding="#{backingBeanScope.backing_changeLocale.soc1}"
id="soc1">
<af:selectItem label="French" value="FR"
binding="#{backingBeanScope.backing_changeLocale.si1}"
id="si1"/>
...
</af:selectOneChoice>

4. f:viewタグのlocale属性をバッキングBean内のロケール値にバインドします。

1. JSFページの構造ウィンドウで「f:view」タグを右クリックし、「プロパティに移動」を選択します。

2. 「プロパティ」ウィンドウで「共通」セクションを展開し、「ロケール」フィールドにポインタを置くと表示されるアイコンをクリックしたときに表示されるポップアップ・メニューから「式ビルダー」を選択します。

3. 式ビルダーで、図32-8に示すように、バッキングBean内のロケール値にバインドします。

図32-8 locale属性をバッキングBeanにバインドする式ビルダー

5. ページを保存します。

32.4.2 ロケールを指定するためにページを構成する場合の処理

JDeveloperでは、ロケールの変更に使用するコマンド・コンポーネントのバッキングBeanに対する参照が生成されます。例32-11に、selectOneChoiceコンポーネントを使用する例を示します。

例32-11 バッキングBeanを参照するselectOneChoiceコンポーネント

<af:selectOneChoice label="Select Locale"
binding="#{backingBeanScope.backing_changeLocale.soc1}"
id="soc1">
<af:selectItem label="French" value="FR"
binding="#{backingBeanScope.backing_changeLocale.si1}"
id="si1"/>
...
</af:selectOneChoice>

JDeveloperでは、そのページのバッキングBeanでの必須メソッドも生成されます。例32-12に、例32-11に対応するバッキングBeanの抜粋を示します。

例32-12 ロケールを変更するためのバッキングBeanのメソッド

package view.backing;

...
import oracle.adf.view.rich.component.rich.input.RichSelectOneChoice;

public class ChangeLocale {
...
...
private RichSelectOneChoice soc1;
...

...

...
public void setD2(RichDocument d2) {
this.d2 = d2;
}

...

public void setSoc1(RichSelectOneChoice soc1) {
this.soc1 = soc1;
}

public RichSelectOneChoice getSoc1() {
return soc1;
}

public void setSi1(RichSelectItem si1) {
this.si1 = si1;
}
...
}

32.4.3 実行時の処理: エンド・ユーザーによるロケールの指定方法

実行時に、エンド・ユーザーは、アプリケーションのロケールを変更するように構成されたコマンド・コンポーネントを呼び出します。バッキングBeanには、更新されたロケール情報が格納されます。f:viewタグのlocale属性がバッキングBeanを参照するページは、エンド・ユーザーによって指定されたロケールを使用してレンダリングされます。

エンド・ユーザーによって指定されたロケールは、アプリケーションに登録される必要があります。ロケールおよび関連のリソース・バンドルの指定の詳細は、32.3.4項「アプリケーションへのロケールの登録方法」を参照してください。

32.5 ADF Facesのオプションのローカライゼーション・プロパティの構成

ADF Facesでは、テキスト変換の他に、通貨コードなど、その他のタイプの変換や、双方向レンダリングのサポート(BiDiサポート)も自動的に提供されます。アプリケーションは、ユーザーの選択したロケールに基づいて、自動的に適切に表示されます。ただし、trinidad-config.xmlファイル内でアプリケーションの次のローカライズ設定を手動で設定することもできます。

- <currency-code>: コンバータで通貨コードが指定されていない通貨コードのフォーマットに、oracle.adf.view.faces.converter.NumberConverterで使用されるデフォルトのISO 4217通貨コードを定義します。

- <number-grouping-separator>: 数値の桁区切りに使用される文字(カンマなど)を定義します。ADF Facesでは現在のロケールから区切り文字が自動的に導出されますが、この要素に値を指定して、デフォルトをオーバーライドできます。設定した場合、この値が、解析およびフォーマット時に、oracle.adf.view.faces.converter.NumberConverterで使用されます。

- <decimal-separator>: 小数点(ピリオド、カンマなど)に使用されるセパレータを定義します。ADF Facesでは現在のロケールから区切り文字が自動的に導出されますが、この要素に値を指定して、デフォルトをオーバーライドできます。設定した場合、この値が、解析およびフォーマット時に、oracle.adf.view.faces.converter.NumberConverterで使用されます。

- <right-to-left>: ページにテキストが表示される方向を定義します。ADF Facesでは、双方向レンダリングがサポートされ、現在のロケールからレンダリング方向が自動的に導出されますが、trueまたはfalseの値を使用して、デフォルトのページ・レンダリング方向を明示的に設定できます。

- <formatting-locale>: 選択されたロケールに適切な日付および数値の書式を定義します。デフォルトで、ADF Facesは、ローカライズされたテキストに使用されているロケールと同じロケールの日付と数値の書式を設定します。日付と数値を別のロケールで書式設定する場合、IANA形式のロケール(ja、fr-CAなど)を使用できます。この要素の内容は、IANA文字列を指すEL式またはjava.util.Localeオブジェクトです。

- 日付を処理して表示するためのタイムゾーンと、2桁のみの年を解析するための年オフセットを設定するには、次の要素を使用します。

- <time-zone>: ADF Facesは、値が設定されない場合、アプリケーションで使用されるタイムゾーンをデフォルトで使用します。必要な場合は、TimeZoneと評価されるEL式を使用できます。この値は、文字列をDateに変換する際にorg.apache.myfaces.trinidad.converter.DateTimeConverterで使用されます。

- <two-digit-year-start>: この値は、グレゴリオ暦の年で指定します。org.apache.myfaces.trinidad.converter.DateTimeConverterで使用されて、文字列をDateに変換します。この要素は、値が設定されない場合、デフォルトで1950年に設定されます。必要な場合は、静的整数値またはIntegerオブジェクトと評価されるEL式を使用できます。

trinidad-config.xmlファイルで構成できる要素の詳細は、A.6項「trinidad-config.xmlでの構成」を参照してください。

32.5.1 オプションのローカライゼーション・プロパティの構成方法

アプリケーションのtrinidad-config.xmlファイルに要素を入力することで、オプションのローカライゼーション・プロパティを構成できます。

始める前に:

どのオプション・ローカライズ・プロパティを変更できるかを理解しておくと役立ちます。詳細は、32.3項「リソース・バンドルおよびロケールの手動による定義」を参照してください。

他のOracle ADF機能を使用して追加できる機能を理解しておくことも役立ちます。詳細は、32.1.2項「ページの国際化およびローカライズの追加機能」を参照してください。

オプションのローカライゼーション・プロパティを構成する手順:

1. 「アプリケーション」ウィンドウで、WEB-INFノードを展開し、trinidad-config.xmlをダブルクリックします。

2. 「コンポーネント」ウィンドウの「トリニダード構成要素」ページで、構成するローカライゼーション要素を<trinidad-config>にドラッグ・アンド・ドロップします。

3. 目的の値を入力します。

例32-13に、オプションのローカライゼーション要素すべてが設定されたtrinidad-config.xmlファイルのサンプルを示します。

例32-13 通貨コードおよび数値と小数点のセパレータの構成

<!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>

<!-- Set the number grouping separator to period for German -->
<!-- and comma for all other languages -->
<number-grouping-separator>
#{view.locale.language=='de' ? '.' : ','}
</number-grouping-separator>

<!-- Set the decimal separator to comma for German -->
<!-- and period for all other languages -->
<decimal-separator>
#{view.locale.language=='de' ? ',' : '.'}
</decimal-separator>

<!-- Render the page right-to-left for Arabic -->
<!-- and left-to-right for all other languages -->
<right-to-left>
#{view.locale.language=='ar' ? 'true' : 'false'}
</right-to-left>

<formatting-locale>
#{request.locale}
</formatting-locale>

<!-- Set the time zone to Pacific Daylight Savings Time -->
<time-zone>PDT</time-zone>

33 アクセス可能なADF Facesページの開発

この章では、<accessibility-mode>および<accessibility-profile>要素でtrinidad-config.xmlを構成することによって、ADF Facesコンポーネントにアクセシビリティのサポートを追加する方法を説明します。この章では、部分ページ・レンダリング、スクリプト、スタイル、特定ページおよびナビゲーション構造を使用するADFページのアクセシビリティ・ガイドラインについても説明されています。

この章では、次の項目について説明します。

- 33.1項「ADF Facesでのアクセシビリティ・サポートについて」

- 33.2項「ADF Facesでのアクセシビリティ・サポートの構成」

- 33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」

- 33.4項「アクセス可能なページの作成」

- 33.5項「アクセシビリティ監査ルールの実行」

33.1 ADF Facesでのアクセシビリティ・サポートについて

アクセシビリティとは、弱視や全盲、難聴またはその他の身体的な制限などの障害を持つユーザーが、アプリケーションを使用できるようにすることです。つまり、マウスなし(キーボードのみ)で使用でき、全盲または弱視のユーザーはスクリーン・リーダーを使用でき、音、色またはアニメーションやタイミングに依存せずに使用できるアプリケーションを作成することです。

ADF Facesのユーザー・インタフェース・コンポーネントには、視覚的および身体的な障害のあるユーザーのために、組込みのアクセシビリティ・サポートが用意されています。スクリーン・リーダーのような非視覚的なメディアへのレンダリングを行うWebブラウザなどのユーザー・エージェントにより、コンポーネントのテキスト説明が読み上げられ、障害を持つユーザーに有益な情報が提供されます。

コンポーネントのADF Facesのアクセシビリティ・ガイドライン、ページやナビゲーション構造は便利ですが、アクセシビリティ標準に関する理解を深めることや、支援技術を使用したアクセシビリティのテスト実行のかわりにはなりません。

アクセス・キー・サポートは、キーボードのみを使用してコンポーネントやリンクにアクセスする代替の方法を提供します。ADF Facesのアクセシビリティ監査ルールにより、アクセス可能なHTMLマークアップを使用して、アクセス可能なイメージ、表、フレーム、フォーム、エラー・メッセージおよびポップアップ・ウィンドウの作成が指示されます。クライアント側のスクリプト、特に非同期のJavaScriptおよびXML (AJAX)を使用した場合に生じていたフレームワークとプラットフォームのさらなる問題は、オラクル社のアクセシビリティ・ストラテジで対応しています。

Oracleソフトウェアには、米国の508条およびWeb Content Accessibility Guidelines (WCAG) 1.0 AA標準が適用されています。これらの標準の解釈は、http://www.oracle.com/accessibility/standards.htmlで入手できます。

33.1.1 ADF Facesアクセシビリティ・サポートのユースケースおよび例

ADF Facesには、スクリーン・リーダー、高コントラスト・モードおよび大きいフォント・モードの3タイプのアプリケーション・アクセシビリティ・サポートが用意されています。図33-1に、ドロップダウン・メニューのアクセシビリティ・オプションの例を示します。ユーザーは、3つのオプションすべての組合せを必要に応じて選択できます。

図33-1 アクセシビリティ・サポート・オプションが表示されたドロップダウン・メニュー

図33-2に、スクリーン・リーダー・モードのアクセシビリティ・オプションの例を示します。

図33-2 スクリーン・モードのアクセシビリティ・サポート・オプションが表示されたドロップダウン・メニュー

33.1.2 ADFページでのアクセシビリティ・サポートの追加情報

アプリケーションをアクセス可能にする前に、その他のADF Faces機能を理解しておくことも役に立ちます。アクセシビリティと連係するその他の機能へのリンクは、次のとおりです。

- 国際化およびローカライズ: アプリケーションに適用するために作成するADFスキンは、ADF Facesページを国際化およびローカライズするためのプロセスの一部としてカスタマイズできます。このプロセスの詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

- キーボードのショートカット: ポインティング・デバイスのかわりにキーボード・ショートカットを使用してページでの移動を行えます。キーボード・ショートカットをアクセシビリティとともに使用する方法の詳細は、付録C「キーボード・ショートカット」を参照してください。

33.2 ADF Facesでのアクセシビリティ・サポートの構成

ADF Facesには、2つのレベルのアプリケーション・アクセシビリティ・サポートが、<accessibility-mode>要素を使用してtrinidad-config.xmlファイルに構成されています。<accessibility-mode>に使用可能な値は次のとおりです。

- default: デフォルトでは、ADF Facesにより、豊富なユーザー・インタフェース相互作用を持ち、キーボードからもアクセスできるコンポーネントが生成されます。デフォルト・モードでは、スクリーン・リーダーはすべてのADF Facesコンポーネントにアクセスできるとはかぎりません。視覚障害のあるユーザーがスクリーン・リーダーを使用している場合、screenReaderモードを使用してください。

- screenReader: ADF Facesにより、スクリーン・リーダーと使用するために最適化されるコンポーネントが生成されます。screenReaderモードにより、視覚障害を持つユーザー向けの表示が容易になりますが、目の見える(視覚障害のない)ユーザーにとっては表示の品質が低下します。

図33-3は、デフォルト・モードとスクリーン・リーダー・モードの表コンポーネントを表示します。

図33-3 スクリーン・リーダー・モードの表コンポーネント

ユーザーが目的のタイプのアクセシビリティ・サポートを必要に応じて選択できるように、アプリケーションで前述のアクセシビリティ・サポート間の切り替え機能を提供してください。

@accessibility-profile要素を使用すれば、スタイルシートでより細かいアクセシビリティ・プリファレンスを定義でき、またtrinidad-config.xmlファイルでアクセシビリティ・プロファイル・オプションを指定することもできます。オプションは、high-contrast、large-fontsまたはその両方です。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

<accessibility-profile>に使用可能な値は次のとおりです。

- high-contrast: ADF Facesでは高コントラストに適した視覚的コンテンツを生成できます。高コントラスト・モードは、高コントラスト機能を有効にしているオペレーティング・システムまたはブラウザとの互換性をADF Facesアプリケーションに持たせることを目的としています。たとえば、ADF Facesでは、高コントラスト・モードでの背景イメージおよび背景色の使用を変更し、視覚情報の損失を防ぎます。ADF Faces高コントラスト・モードは、ブラウザまたはオペレーティング・システムの高コントラスト・モードと組み合せて使用するとより効果的です。一部のユーザーには、高コントラスト・モードを大きいフォント・モードと一緒に使用しても効果的です。
図33-4に、高コントラスト・モードのshowDetailHeaderコンポーネントを示します。

図33-4 高コントラスト・モードのshowDetailHeaderコンポーネント

- large-fonts: ADF Facesではブラウザ・ズームに適したコンテンツを生成できます。デフォルト・モードでは、大部分のテキストおよび多くのコンテナでは固定フォント・サイズで、一貫した定義済の外観を提供します。大きいフォント・モードでは、テキストおよびコンテナはスケーラブル・フォント・サイズです。これによって、ADF Facesはより大きいフォント・サイズが設定されているブラウザと互換性を持ち、ブラウザのズーム機能に対応できます。大きいフォント・モードまたはブラウザのズーム機能を使用していない場合は、大きいフォント・モードを無効にする必要があります。一部のユーザーには、高コントラスト・モードを大きいフォント・モードと一緒に使用しても効果的です。
図33-5に、大きいフォント・モードのnavigationPaneコンポーネントを示します。

図33-5 大きいフォント・モードのnavigationPaneコンポーネント

図33-6に、標準モードと大きいフォント・モードでのテキストのフォント・サイズを示します。

図33-6 標準モードと大きいフォント・モードでのテキスト

注意:

<accessibility-mode>および<accessibility-profile>要素は、ユーザー固有のプリファレンスを含むセッション・スコープ・マネージドBeanにELバインドする必要があります。

33.2.1 サインインでのアクセシビリティ・サポート・ガイドライン

アプリケーションを開発する際、アプリケーションのサインイン後に、ユーザーにアクセシビリティの選択オプションを提供することをお薦めします。サインイン・アクセシビリティの流れは、次に説明するように、初めてのユーザーの場合は3つのページ、2回目以降のユーザーの場合は2つのページで構成されます。

1. サインイン・ページ

2. アクセシビリティ・モード選択ページ(初めてのユーザーには必須)

3. アプリケーションのホームページ

アクセシビリティのオプションは、初めてのユーザーと、後続の認証で省略しないことを選択したユーザーに対して表示されます。たとえば、次のオプションのあるページまたはダイアログを提供できます。

- ヒント・テキスト: アクセシビリティのオプションについての簡単な情報を提供します。

- チェック・ボックス

- スクリーン・リーダー: スクリーン・リーダーと使用するために最適化されるADF Facesコンポーネントを生成します。

- 高コントラスト: 高コントラストに適した視覚的コンテンツを生成します。

- 大きいフォント: ブラウザのズームに適したコンテンツを生成します。

- これらのオプションを再び表示しない: サインイン後にアクセシビリティのオプションを表示しません。

- 「続行」ボタン: アプリケーションのホームページに移動します。

図33-7に、アクセシビリティのオプションが表示されたページを示します。

図33-7 サインイン後のアクセシビリティのオプション

ユーザーがこれらのオプションを再び表示しないを選択して、サインイン時にアクセシビリティのオプションを表示しないことを選択した場合、ユーザーをアクセシビリティのオプションに移動させるためのページまたはダイアログを提供する必要もあります。たとえば、アプリケーションのユーザー設定ページなどです。図33-8に、アクセシビリティのオプションが表示された「プリファレンス」ページを示します。

図33-8 ユーザー設定ページのアクセシビリティのオプション

アプリケーションには、アクセシビリティ・モード選択ページと製品固有のホームページとの間で設定された追加の認証セキュリティがある場合があります。

33.2.2 trinidad-config.xmlにおけるアクセシビリティ・サポートの構成方法

JDeveloperで、ADF FacesコンポーネントをJSFページへ初めて追加すると、trinidad-config.xmlの基礎ファイルが/WEB-INFディレクトリに自動的に作成されます。ファイルは、JSF式言語(EL)または静的値を使用して要素プロパティを定義できる単純なXML構造です。ファイル内の要素の順序は関係ありません。XMLファイルを直接編集するか、構造ウィンドウを使用することで、アクセシビリティ・サポートを構成できます。

始める前に:

ADF Facesのアクセシビリティ・サポートについて理解しておくと役立ちます。詳細は、33.2項「ADF Facesでのアクセシビリティ・サポートの構成」を参照してください。その他のADF Faces機能を使用して追加できる機能について理解しておくことも役に立ちます。詳細は、33.1.2項「ADFページでのアクセシビリティ・サポートの追加情報」を参照してください。

trinidad-config.xmlでアクセシビリティ・サポートを構成する手順:

1. 「アプリケーション」ウィンドウで、trinidad-config.xmlをダブルクリックします。

2. XMLエディタで、要素名<accessibility-mode>およびアクセシビリティ・サポートの値(default、screenReaderまたはinaccessible)を入力します。次に例を示します。

<accessibility-mode>screenReader</accessibility-mode>

このコードでは、アプリケーションのアクセシビリティ・サポートがスクリーン・リーダー・モードに設定されています。

3. 要素名<accessibility-profile>およびアクセシビリティ・プロファイル値(high-contrast、large-fonts)を入力します。
次に例を示します。

<!-- Enable both high-contrast and large-fonts content -->
<accessibility-profile>high-contrast large-fonts</accessibility-profile>

このコードでは、アプリケーションのプロファイル・サポートが、high-contrastおよびlarge-fontsの両方を使用するように設定されています。図33-9は、JDeveloperでのtrinidad-config.xmlファイルを示しています。

図33-9 JDeveloperでのtrinidad-config.xml

または、構造ウィンドウを使用して値を入力できます。

1. 「アプリケーション」ウィンドウで、trinidad-config.xmlファイルを選択します。

2. 構造ウィンドウで、XMLファイルのルート要素を右クリックして「trinidad-configの中に挿入」→「参照」メニュー項目を選択します。

3. 「アイテムの挿入」ダイアログで、項目名(accessibility-modeまたはaccessibility-profile)を選択して「OK」をクリックします。

4. 構造ウィンドウで新しく挿入された要素が選択された状態で、「プロパティ」ウィンドウを開き、値を入力するかドロップダウン・リストから選択します。

trinidad-config.xmlファイルの構成後、プログラムから、あるいはJSF EL式を使用してプロパティ値を取得できます。

たとえば、次のコードでは、アクセシビリティ・モードが明示的に設定されていない場合は、何も返されません。

String mode=ADFFacesContext.getCurrentInstance().getAccessibilityMode;

このEL式の例では、アクセシビリティ・モードが明示的に設定されていない場合は、NULL値が返されます。

<af:outputText value="*#{requestContext.accessibilityMode}"/>

アクセシビリティ選択オプションは、アプリケーションのサインイン時またはアプリケーションのユーザー・プリファレンス・ページで設定できます。詳細は、33.2.1項「サインイン時のアクセシビリティ・サポート・ガイドライン」を参照してください。

33.3 コンポーネント・レベルのアクセシビリティ・プロパティの指定

コンポーネント固有のアクセシビリティのガイドラインは、33.3.1項「ADF Facesコンポーネントのアクセシビリティ・ガイドライン」に説明されています。ガイドラインには、関連のプロパティの説明が例やヒントとともに含まれています。ADF Facesのアクセシビリティ・ルールに準拠していることを監査する方法の詳細は、33.5項「アクセシビリティ監査ルールの実行」を参照してください。

af:inputText、af:buttonおよびaf:linkなど、ADF Facesの入力、コマンドおよび実行コンポーネントに対するアクセス・キー・サポートには、ラベルの定義およびキーボード・ショートカットの指定が含まれます。[Tab]キーを使用してWebアプリケーションのあるコントロールから次のコントロールへ移動することが可能ですが、キーボード・ショートカットはより便利で効率的です。

コンポーネントのアクセス・キーを指定するには、コンポーネントのaccessKey属性を、コンポーネントに簡単にアクセスするために使用するキーボード文字(またはニーモニック)に設定します。「プロパティ」ウィンドウまたはページのソースでは、&ampエンコーディングを使用して属性を設定できます。

同じアクセス・キーを複数のコンポーネントにバインドできます。同じアクセス・キーが同一ページ内の複数の場所に表示される場合、レンダリング・エージェントは同じキーでアクセスできるコンポーネントを巡回します。つまり、アクセス・キーが押されるたびに、フォーカスがコンポーネント間を移動します。最後のコンポーネントに到達すると、フォーカスは最初のコンポーネントに戻ります。

af:buttonおよびaf:linkコンポーネントでアクセス・キーを使用すると、一部のブラウザではアクセス・キーがすぐにアクティブ化されます。ブラウザによっては、ページの2つ以上の実行コンポーネントに同じアクセス・キーが割り当てられている場合、同じアクセス・キーでアクセスできるコンポーネントを巡回せずに、最初のコンポーネントがアクティブ化されます。

アクセス可能なページおよびナビゲーション構造を開発するには、33.4項「アクセス可能なページの作成」で説明されている追加のアクセシビリティ・ガイドラインに従います。

33.3.1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

アクセス可能なADF Facesコンポーネントを開発するには、コンポーネントのタグのドキュメントおよび表33-1に説明されているガイドラインに従います。表33-1にリストされていないコンポーネントには、アクセシビリティ・ガイドラインはありません。

注意:

アクセシビリティ・ガイドラインでlabelプロパティが参照される場合、可能な場合はlabelAndAccessKeyプロパティが使用され、これが推奨オプションです。

特に記載がないかぎり、次のようにして、ADF Facesの入力および選択のコントロールにもラベルを設定できます。

- af:outputLabelコンポーネントにforプロパティを指定

- af:panelLabelAndMessageコンポーネントにforプロパティを指定

表33-1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

コンポーネント

ガイドライン

af:activeImage

shortDescプロパティを指定します。

イメージを修飾目的のみで使用し、伝える情報がない場合は、shortDescを空の文字列に設定します。

af:chooseColor

すべてのaf:chooseColorコンポーネントに、af:chooseColorコンポーネントを指すchooseIdプロパティを含むaf:inputColorコンポーネントが1つ以上存在する必要があります。

af:chooseDate

すべてのaf:chooseDateコンポーネントに、af:chooseDateコンポーネントを指すchooseIdプロパティを含むaf:inputDateコンポーネントが1つ以上存在する必要があります。

af:column

headerTextプロパティを指定するか、ヘッダー・ファセットを指定します。

表で、rowHeaderをtrueまたはunstyledに設定することにより、1つ以上の列コンポーネントを行ヘッダーとして指定する必要があります。必ずrowHeader列に一意のテキスト値を指定し、入力コンポーネントを含む列が行ヘッダーとして割り当てられないようにします。

子入力コンポーネントごとに、Simple属性をtrueに設定し、その入力コンポーネントにラベルが割り当てられていることを確認します。リッチ・モードでは、ラベルは表示されませんが、スクリーン・リーダー・モードでは、スクリーン・リーダー・ソフトウェアによって読み上げられます。

列のヘルプ情報を提供する場合は、helpTopicIdを使用します。

列にフィルタを設定するためにフィルタ・ファセットを使用する場合、そのフィルタ・コンポーネントにラベルが割り当てられていることを確認します。

af:button

af:link

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります(アイコンとともに使用)。テキストにはコンポーネントによってアクティブにされるアクションまたは宛先を指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。textまたはtextAndAccessKeyプロパティが存在する場合は、コンポーネントのラベルとしてそれらを使用します。アイコンのみのボタンまたはリンクの場合は、shortDescがコンポーネントのラベルになります。一意のボタンまたはリンクには、一意のテキストを指定する必要があります。

af:commandMenuItem

af:commandNavigationItem

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。

通常、textまたはtextAndAccessKeyプロパティは、コンポーネントのラベルとして使用されます。一意のボタンおよびリンクには、一意のテキストを指定する必要があります。

af:dialog

af:document

titleプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:goMenuItem

textプロパティを指定します。テキストは、ユーザーが移動するリンク先を指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。同じ場所に移動する複数のリンクには同じテキストを使用し、一意のリンクには一意のテキストを使用する必要があります。

通常、textまたはtextAndAccessKeyプロパティは、コンポーネントのラベルとして使用されます。一意のボタンおよびリンクには、一意のテキストを指定する必要があります。

af:icon

shortDescプロパティを指定します。アイコンを装飾目的のみで使用し、伝える情報がない場合は、shortDescを空の文字列に設定します。

af:image

shortDescプロパティを指定します。イメージを修飾目的のみで使用し、伝える情報がない場合は、shortDescを空の文字列に設定します。

複雑な説明が必要なイメージには、longDescURLプロパティを使用します。たとえば、グラフには、グラフを構成するすべての詳細を含む説明ファイルが必要です。

af:inlineFrame

shortDescプロパティを指定します。

af:inputColor

af:inputComboboxListOfValues

af:inputDate

af:inputFile

af:inputListOfValues

af:inputNumberSlider

af:inputNumberSpinbox

af:inputRangeSlider

af:inputText

labelプロパティを指定します。

af:inputComboboxListOfValuesおよびaf:inputListOfValuesコンポーネントには、searchDescも指定する必要があります。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:outputFormatted

valueプロパティに有効なHTMLを指定する必要があります。

af:outputLabel

valueまたはvalueAndAccessKeyプロパティを指定します。

af:panelBox

af:panelHeader

textプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:panelLabelAndMessage

labelまたはlabelAndAccessKeyプロパティを指定します。ADF Facesの入力または選択コントロールへのラベル設定にこのコンポーネント使用する場合は、forプロパティを指定する必要があります。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:panelSplitter

af:panelStretchLayout

33.4.4項「ページ構造およびナビゲーションの使用方法」を参照してください。

af:panelWindow

titleプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:poll

コンテンツを更新するためにポーリングを使用する場合は、エンド・ユーザーが間隔を制御できるようにするか、ポーリングではなく更新を明示的に開始できるようにします。

af:query

次のプロパティを指定します。

- headerText

- addFieldsButtonAccessKey

- addFieldsButtonText

- resetButtonAccessKey

- resetButtonText

- saveButtonAccessKey

- saveButtonText

- searchButtonAccessKey

- searchButtonText

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:quickQuery

labelおよびsearchDescプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:region

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:richTextEditor

labelプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:selectBooleanCheckbox

af:selectBooleanRadio

text、textAndAccessKeyまたはlabelのいずれかのプロパティが指定されている必要があります。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:selectItem

labelプロパティを指定します。af:outputLabelおよびaf:panelMessageAndLabelコンポーネントのfor属性を使用しても、かわりにはなりません。

af:selectManyCheckbox

af:selectManyChoice

af:selectManyListbox

af:selectManyShuttle

af:selectOneChoice

af:selectOneListbox

af:selectOneRadio

af:selectOrderShuttle

labelプロパティを指定します。

af:selectManyShuttleおよびaf:selectOrderShuttleコンポーネントには、leadingHeaderおよびtrailingHeaderプロパティを指定する必要があります。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:showDetailHeader

textプロパティを指定します。

ヘルプ情報を提供する場合は、helpTopicIdを使用します。

af:showDetailItem

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。

af:showPopupBehavior

triggerTypeプロパティを指定します。

mouseHover、mouseMove、mouseOverおよびmouseOutのトリガー・タイプは、スクリーン・リーダー・モードでは非表示なります。したがって、スクリーン・リーダー・モードでは、これらのトリガー・タイプのコンテンツへの別のアクセス方法を提供する必要があります。

af:table

af:treeTable

summaryプロパティを指定します。サマリーでは、表の目的を説明する必要があります。

すべての表の列に列ヘッダーを作成する必要があります。

スクリーン・リーダー・モードでは、af:column内の入力コンポーネントにラベルが指定されている場合、ADF Facesによりその入力コンポーネントのアプリケーション指定のラベルに行情報が自動的に挿入されます。通常は、アプリケーション指定のラベルは列ヘッダー・テキストと一致し、挿入された行情報とともに、入力コンポーネントごとに一意のIDを提供します。

33.3.2 スクリーン・リーダー・モードでのADF Faces表コンポーネントの使用方法

WebアプリケーションでADF Faces表コンポーネントを使用している場合、1つの列をスクリーン・リーダー・モード用の行ヘッダーとして指定する必要があります。その行ヘッダーは、スクリーン・リーダー・ソフトウェアによって、エンド・ユーザーが選択した行を告げるために使用されます。通常は、複数の選択ができる行ヘッダーとして1つの列が使用されますが、行ヘッダーとして複数の列をマークすることもできます。複数の列を行ヘッダーとしてマークすると、それらは表の初期列として表示され、固定されます。

場合によっては、表示目的で、行ヘッダーを表示しないこともあります。そのような場合には、表の1つの列をrowHeader属性がunstyledに設定されているように定義する必要があります。スクリーン・リーダー・モードでは、unstyled行ヘッダーを持つ表またはツリー表コンポーネントは、displayIndexが0に設定された開始位置に移動し、固定されます。デフォルト・モードでは、unstyled行ヘッダー列を持つ表またはツリー表は、開始位置に移動せず、固定されずに、行ヘッダーのCSSスタイルなしでレンダリングされます。

33.3.3 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

アクセス可能なADFデータ視覚化コンポーネントを開発するには、表33-2で説明されているアクセシビリティ・ガイドラインに従います。リストされていないコンポーネントには、アクセシビリティ・ガイドラインはありません。

表33-2 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

コンポーネント

ガイドライン

dvt:projectGantt

dvt:resourceUtilization
Gantt

dvt:schedulingGantt

summaryプロパティを指定します。summaryでは、ガント・チャート・コンポーネントの目的を記述する必要があります。

dvt:gauge

shortDescプロパティを指定します。プロパティでは、ゲージの目的を説明する必要があります。

dvt:areaGraph

dvt:barGraph

dvt:horizontalBarGraph

dvt:bubbleGraph

dvt:comboGraph

dvt:funnelGraph

dvt:lineGraph

dvt:paretoGraph

dvt:pieGraph

dvt:radarGraph

dvt:scatterGraph

dvt:stockGraph

shortDescプロパティを指定します。shortDescプロパティでは、グラフの目的を説明する必要があります。

スクリーン・リーダー・モードの場合、ピボット・テーブルのインスタンスがグラフ・コンポーネントのかわりになるため、エンド・ユーザーは標準カーソル・キーを使用して、データ内を移動できます。

スクリーン・モードでは、グラフ・コンポーネントの次の視覚化機能はサポートされません。

- 部分ページ・レンダリング時のデータ変更アニメーション。

- ズームとスクロール。ピボット・テーブルではスクロールがサポートされています。

- 単純グラフ・タグでのseriesRolloverBehaviorおよびhideAndShowBehaviorプロパティ。

- 円グラフでのinteractiveSliceBehaviorプロパティ。

- データ・マーカーの形状および色の精密制御で、次のものがあります。

- Series子タグでの宣言的プロパティ

- 散布図上の宣言的markerShapeおよびmarkerColorプロパティ

- コールバックAPI

- バッキングBeanの条件付き書式設定ルール

- バブル・グラフおよび散布図のマーカー・アンダーレイ

スクリーン・モードでは、グラフ・コンポーネントの次の対話機能はサポートされません。

- コンテキスト・メニュー・ファセット

- ポップアップ

- <dvt:timeSelector>子タグによるTimeSelector機能

- 単純グラフ・タグのdrillingEnabledプロパティ

- ShapeAttributesサポート、およびすべてのグラフ・コンポーネントからのきめ細かいマウスおよびキー・イベントへのアクセス

- バブル・グラフおよび散布図でのドラッグ・アンド・ドロップ

- バブル・グラフおよび散布図でのDataSelection

- プログラムのTickLabelCallbackサポート

dvt:hierarchyViewer

dvt:sunburst

dvt:treemap

summaryプロパティを指定します。

スクリーン・リーダー・モードの場合、ツリー表コンポーネントのインスタンスがコンポーネントのかわりになるため、エンド・ユーザーは標準カーソル・キーを使用して、データ内を移動できます。

dvt:map

summaryプロパティを指定します。

スクリーン・リーダー・モードの場合、表コンポーネントのインスタンスがグラフィック・マップ・コンポーネントのかわりになるため、エンド・ユーザーは標準カーソル・キーを使用して、データ内を移動できます。

dvt:thematicMap

summaryプロパティを指定します。

スクリーン・リーダー・モードの場合、表コンポーネントのインスタンスが各DataLayerコンポーネントのかわりになるため、エンド・ユーザーは標準カーソル・キーを使用して、データ内を移動できます。

テーマ・マップ・インスタンスに複数のDataLayersが関連付けられている場合、スクリーン・リーダー・モードではドロップダウン・リストもレンダリングされ、エンド・ユーザーは対応する表インスタンス間で切替えができます。

dvt:pivotTable

summaryプロパティを指定します。サマリーでは、時系列コンポーネントの目的を説明する必要があります。

dvt:timeline

summaryプロパティを指定します。サマリーでは、ピボット・テーブル・コンポーネントの目的を説明する必要があります。

dvt:sparkChart

shortDescプロパティを指定します。

33.3.4 ADF Facesコンポーネントのアクセス・キーの定義方法

アクセス・キーを定義するコンポーネントの「プロパティ」ウィンドウで、accessKey属性フィールドにニーモニック文字を入力します。テキスト、ラベル、値およびニーモニック文字を同時に設定する場合は、関連する属性フィールドのニーモニック文字の前にアンパサンド(&)文字を使用します。

始める前に:

コンポーネント・レベルのアクセシビリティ・ガイドラインについて理解しておくと役立ちます。詳細は、33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」を参照してください。その他のADF Faces機能を使用して追加できる機能について理解しておくことも役に立ちます。詳細は、33.1.2項「ADFページでのアクセシビリティ・サポートの追加情報」を参照してください。

アクセス・キーの定義

ADF Facesの入力、コマンドおよび実行コンポーネントにキーボード文字を指定するには、次の4つの属性のいずれか1つを使用します。

- accessKey: コンポーネントへの簡単なアクセスに使用するニーモニック文字の設定に使用します。コマンド・コンポーネントと移動コンポーネントの場合、属性によって指定される文字は、インスタンス・コンポーネントのtext属性の中に存在する必要があり、ない場合は、ADF Facesではコンポーネントにアクセス・キーがないことを視覚的に示す表示は行われません。
例33-1に、af:linkコンポーネントのアクセス・キーを文字hに設定するコードを示します。Internet Explorerで、ユーザーが[ALT]+[H]キーを押すと、コンポーネントのテキスト値にフォーカスが移動します。[ALT]キーは、すべてのWebブラウザアクセス・キーとして機能するわけではないことに注意してください。ブラウザのショートカット・キーを知るには、ブラウザのドキュメントを参照してください。

例33-1 定義されているaccessKey属性

<af:link text="Home" accessKey="h">

- textAndAccessKey: アンパサンド(&)文字を使用して、コンポーネントのテキストとニーモニック文字を同時に設定する場合に使用します。JSPXファイルでは、従来のアンパサンド表記は&amp;です。JSPファイルでは、アンパサンド表記は単純に&です。「プロパティ」ウィンドウで必要なのは、&文字のみです。
例33-2に、ボタン・テキストをHomeに指定し、アンパサンド文字の直後の文字であるHを、af:buttonコンポーネントのアクセス・キーに設定するコードを示します。

例33-2 定義されているtextAndAccessKey属性

<af:button textAndAccessKey="&amp;Home"/>

- labelAndAccessKey: 従来のアンパサンド表記を使用して、入力コンポーネントのlabel属性およびアクセス・キーを同時に設定する場合に使用します。
例33-3に、ラベルをDateに指定し、アンパサンド文字の直後の文字であるaを、af:selectInputDateコンポーネントのアクセス・キーに設定するコードを示します。

例33-3 定義されているlabelAndAccessKey属性

<af:inputSelectDate value="Choose date" labelAndAccessKey="D&amp;ate"/>

- valueAndAccessKey: 従来のアンパサンド表記を使用して、value属性およびアクセス・キーを同時に設定する場合に使用します。
例33-4に、ラベルをSelect Dateに指定し、アンパサンド文字の直後の文字であるeを、af:outputLabelコンポーネントのアクセス・キーに設定するコードを示します。

例33-4 定義されているvalueAndAccessKey属性

<af:outputLabel for="someid" valueAndAccessKey="Select Dat&amp;e"/>
<af:inputText simple="true" id="someid"/>

アクセス・キー修飾子は、ブラウザおよびプラットフォームによって異なります。すでにブラウザのメニュー・ショートカットとして定義されているアクセス・キーを割り当てると、ADF Facesコンポーネントのアクセス・キーが優先されます。詳細は、特定ブラウザのドキュメントを参照してください。

一部のブラウザでは、空白をアクセス・キーとして使用する場合は、コンポーネントのラベルまたはテキスト・ラベルで空白をビジュアルに表現する方法がないため、[Alt]+[Space]または[Alt]+スペースバーがアクセス・キーであるという情報をユーザーに提供する必要があります。そのようなブラウザの場合は、shortDesc属性を使用してコンポーネントのツールチップにテキストを指定できます。

33.3.5 ローカライズされたラベルおよびアクセス・キーの定義方法

異なる言語で表示する必要のあるラベルおよびアクセス・キーは、必要に応じて様々な言語バージョンの表示が可能なリソース・バンドルに格納できます。JSF 1.2で使用可能なJSF構成ファイルに<resource-bundle>要素を使用すると、各ページにf:loadBundleタグを使用せずに、アプリケーションのすべてのページに対してリソース・バンドルを使用可能にできます。

始める前に:

コンポーネント・レベルのアクセシビリティ・ガイドラインについて理解しておくと役立ちます。詳細は、33.3項「コンポーネント・レベルのアクセシビリティ・プロパティの指定」を参照してください。その他のADF Faces機能を使用して追加できる機能について理解しておくことも役に立ちます。詳細は、33.1.2項「ADFページでのアクセシビリティ・サポートの追加情報」を参照してください。

ローカライズされたラベルおよびアクセス・キーを定義する手順:

1. リソース・バンドルを単純な.propertiesファイルとして作成し、ラベルおよびアクセス・キーの各言語バージョンを保持します。詳細は、32.3.1項「リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する手順」を参照してください。

2. faces-config.xmlファイルに<locale-config>要素を追加し、アプリケーションのデフォルトおよびサポートされるロケールを定義します。詳細は、32.3.4項「アプリケーションへのロケールの登録方法」を参照してください。

3. 各リソース・バンドルの静的テキストの文字列ごとに、キーと値を作成します。キーは、文字列の一意の識別子です。値は、バンドルの言語でのテキスト文字列です。各値で、アクセス・キーとして定義する文字の前にアンパサンド(&またはamp)を配置します。
たとえば、次のコードでは、UIStrings.propertiesベース・リソース・バンドルの「Edit」ボタン・フィールドのラベルおよびアクセス・キーが、「Edit」と定義されています。

srlist.buttonbar.edit=&Edit

イタリア語のリソース・バンドルUIStrings_it.propertiesでは、次のコードにより、変換可能なラベルおよびアクセス・キーが「Aggiorna」と指定されています。

srlist.buttonbar.edit=A&ggiorna

4. アプリケーションのfaces-config.xmlファイルに<resource-bundle>要素を追加します。例33-5に、リソース・バンドルに対するJSF構成ファイルのエントリを示します。

例33-5 JSF構成ファイルのリソース・バンドル

<resource-bundle>
<var>res</var>
<base-name>resources.UIStrings</base-name>
</resource-bundle>

リソース・バンドルを使用するようにアプリケーションを設定すると、リソース・バンドル・キーが式言語(EL)エディタに表示され、宣言的に割り当てられるようになります。

次の例では、UIコンポーネントがリソース・バンドルにアクセスしています。

<af:outputText value="#{res['login.date']}"/

詳細は、第32章「ページの国際化およびローカライズ」を参照してください。

33.4 アクセス可能なページの作成

コンポーネント・レベルのアクセシビリティ・ガイドラインに加えて、アプリケーションの設計時には、ページ・レベルのアクセシビリティ・ガイドラインにも従う必要があります。コンポーネント・レベルのガイドラインでコンポーネントの使用方法が決まるのに対して、ページ・レベルのアクセシビリティ・ガイドラインは、全体として、アプリケーションの全体的な設計および機能により関係があります。

ページ・レベルのアクセシビリティ・ガイドラインには次のものがあります。

- 部分ページ・レンダリングの使用

- スクリプトの使用

- スタイルの使用

- ページ構造およびナビゲーションの使用

- WAI-ARIAランドマーク・リージョンの使用

アプリケーション・ページの設計時には、表33-3で説明されている一般的なアクセシビリティ・ガイドラインに従う必要があります。

表33-3 一般的なアクセシビリティ・ガイドライン

ガイドライン

アクション

Raw HTMLコンテンツを使用しない

できれば、Raw HTMLコンテンツの使用を避けます。Raw HTMLコンテンツが必要な場合は、af:outputFormattedを使用し、そのコンテンツが有効であることを確認します。

サイトのコンテンツに適した最も明確で簡単な言語を使用する

アプリケーション全体での言語の明確さおよび簡潔さを確保します。

キーボードによるドラッグ・アンド・ドロップの代替方法を提供する

ドラッグ・アンド・ドロップ操作を使用するすべての機能を、キーボードでアクセス可能なインタフェース(「切取り」、「コピー」および「貼付け」メニュー項目など)でも、公開する必要があります。

アクセシビリティ・モードへのアクセスを提供する

ADF Facesでは、次のアクセシビリティ・モードが公開されています。

- デフォルト

- スクリーン・リーダー - スクリーン・リーダーのユーザー用に最適化

必要に応じて、エンド・ユーザーがスクリーン・リーダーを選択できるように、Webアプリケーションを設計する必要があります。ADF Facesでのスクリーン・リーダー・モードの構成の詳細は、33.2項「ADF Facesでのアクセシビリティ・サポートの構成」を参照してください。

Webアプリケーションの設計時には、追加のアクセシビリティ・モード(高コントラスト・アクセシビリティ・モードや大きいフォント・モードなど)の追加が必要になる場合があリます。

アクセシビリティ標準を復習する

関連のアクセシビリティ標準(Web Content Accessibility Guidelinesなど)について知っている必要があります。ADF Facesフレームワークおよびコンポーネントにより、実装詳細の多くが隠されていますが、これらのガイドラインに精通してください。

リンクの目的を説明するテキストを記述する

リンクの目的が一般にユーザーにとって不明瞭な場合を除き、各リンクの目的を、リンク・テキストのみから、またはリンク・テキストとプログラムで指定されたリンク・コンテキストから確認できるようにします。

サイトの一般的なレイアウト(サイト・マップまたは目次など)についての情報を提供する

サイト・レイアウトの要件が必ず満たされるようにします。

ページを見つけるための複数の方法を提供する

ページのアクセス要件が、アプリケーション全体で必ず満たされるようにします。プロセス、またはプロセス内のステップの結果であるページは除外できます。

隣り合ったリンク間を視覚的に分離する

隣り合うリンクが視覚的に分離されるようにし、空白を含む1つのリンクが複数のリンクとして表示されないようにします。

ADF以外のコンテンツにアクセシビリティ・サポートを提供する

ページ内のADF Faces以外のコンテンツがアクセス可能になるようにします。コンテンツは、他のOracle製品またはサードパーティの製品のものでもかまいません。

外部ドキュメントに対するアクセシビリティ・サポートを提供する

外部ドキュメント(WordドキュメントやPDFファイルなど)にアクセス可能になるようにします。ドキュメントはその製品によって生成されるか、製品に付属のものである可能性があり、最低1つのアクセス可能バージョンが必要です。

この項およびそのサブセクションで説明されているガイドラインは、セクション508のガイドラインとWebコンテンツ・アクセシビリティ・ガイドラインを組み合せたOracleグローバルHTMLアクセシビリティ・ガイドラインに従っています。ADF Facesコンポーネントはいくつかのアクセシビリティ・ガイドラインを暗黙的に満たしているため、開発者の負担が軽くなります。たとえば、ADF Facesではすべてのページにlang属性をレンダリングし、ADF Facesコンポーネントによってレンダリングされたすべてヘッダーでは、適切なHTMLヘッダー要素が使用されます。

33.4.1 部分ページ・レンダリングの使用方法

スクリーン・リーダーでは、部分ページ・リクエストで全ページの再読上げは実行されません。部分ページ・レンダリング(PPR)を使用する際は、表33-4で説明されているガイドラインに従う必要があります。

表33-4 部分ページ・レンダリングのアクセシビリティ・ガイドライン

ガイドライン

アクション

後ろの部分的なページ変更を優先する

部分ページ・レンダリングにより、スクリーン・リーダー・ソフトウェアではページを部分的アクションを起動したコンポーネントから読み上げます。したがって、ターゲット・コンポーネントは、部分リクエストを起動するコンポーネントの後に配置する必要があり、このようにしないと、更新したターゲットがスクリーン・リーダーに読み上げられません。

たとえば、最も一般的なPPRのユースケースは、マスター/ディテール・ユーザー・インタフェースで、マスター・コンポーネントで値を選択すると、ディテール・コンポーネントのページの一部が置き換えられます。このような場合、ドキュメントの順番において、マスター・コンポーネントが常にディテール・コンポーネントの前にあることが必要です。

部分的なページ変更のガイダンスを提供する

スクリーン・リーダーやスクリーン・マグニファイアのユーザーには、部分ページ・レンダリング・アクティビティの結果、どのコンテンツが変更されたかを正確に特定するのが難しい場合があります。ページ内のキー・コンポーネント間の関係を識別するインライン・テキスト説明という形で、説明を用意すると役に立ちます。たとえば、マスター/ディテール・シナリオでは、インライン・テキストで、マスター・コンポーネント上の行が更新されると、ディテール・コンポーネントも更新されることを説明します。または、ヘルプ・トピックがページの構造やコンポーネント間の関係を説明します。

33.4.2 スクリプトの使用方法

クライアント側スクリプトは、宣言的ソリューションがあるアプリケーションの問題に使用するべきではないため、最小限にする必要があります。

部分ページ・スクリプトを使用する際は、表33-5で説明されているガイドラインに従う必要があります。

表33-5 スクリプトのアクセシビリティ・ガイドライン

ガイドライン

アクション

スクリプトを最小限に維持する

クライアント側のスクリプトを避けます。

コンポーネントDocument Object Model (DOM)と直接対話しない

ADF Facesコンポーネントは、DOMが変更されると、スクリーン・リーダーと自動的に同期します。DOMとの直接の通信は許可されていません。

JavaScriptのタイムアウトを使用しない

スクリーン・リーダーは、JavaScriptのsetTimeout()またはsetInterval() APIを使用して実装されたタイムアウトへのレスポンスとして行われた変更を確実に追跡するわけではありません。これらのメソッドをコールしないでください。

キーボードで同等のものを提供する

マウスの入力デバイスを使用できないユーザーもいます。たとえば、キーボードしか使用できないユーザー、または代替の入力デバイスや音声認識ソフトウェアなどのテクノロジを使用するユーザーもいます。クライアント側リスナーを使用して機能を追加する場合、その機能には、デバイスに関係なくアクセスできるようにします。事実上、これは次のことを意味します。

- すべての機能にキーボード・イベントを使用してアクセスできる必要があります。

- マウスオーバーまたはマウスアウトよりクリック・イベントを優先する必要があります。

- マウスオーバーまたはマウスアウト・イベントは、クリック・イベントにより追加として使用可能になるようにします。

フォーカス変更をしない

フォーカスを変更すると、コンテキストが変わるため、スクリーン・リーダーのユーザーが混乱する可能性があります。フォーカスの変更、特にフォーカス・イベントに対しての変更を避けるようにアプリケーションを設計します。また、標準のタブ移動が中断されるため、フォーカス変更に応じてポップアップ・ウィンドウが表示されないように設定してください。

ポップアップ・トリガーを明示的に指定する

スクリーン・リーダーは、インライン・ポップアップの起動に自動的には応答しません。スクリーン・リーダー・モードの際に、スクリーン・リーダー・ソフトウェアがポップアップ・コンテンツを読み上げるよう強制するため、ポップアップ・ウィンドウが開かれた直後に、ADF Facesフレームワークによりキーボード・フォーカスがそのウィンドウに明示的に移動されます。リンクやボタンなどの明示的なポップアップ・トリガーを用意するか、キーボードやスクリーン・リーダーでアクセスできるその他の方法で同じ情報を使用できる必要があります。

埋込みオブジェクトのテキスト説明を提供する

各埋込みオブジェクトに、必ず適切なテキスト説明を関連付けるようにします。OBJECT要素ではtitle属性を、APPLET要素ではalt属性を指定する必要があります。

af:mediaの監査ルールを検証するために、監査レポートを実行します。

必須のプラグインをダウンロードするリンクを提供する

ADF Facesでは、Java、FlashまたはPDFなどのプラグインを使用しません。アプリケーションで必要となるプラグイン用の適切なリンクが確実に提供されるようにする必要があります。

プラグイン用のアクセス可能なコンテンツを提供する

アプレットやプラグインによって送られるすべてのコンテンツがアクセス可能であることを確認するか、同等のコンテンツにアクセスするかわりの方法を提供します。

イベント・ハンドラの入力デバイス依存を避ける

コンテンツの理解やアプリケーション操作に不可欠ではないイベント(マウスのロールオーバーによる画像の切替えなど)を除いて、イベント・ハンドラが入力デバイスに依存しないようにします。

スクリプト・ガイドラインに加えて、いくつかのプログラミング・ガイドラインも提供する必要があります。これらのガイドラインの多くは、ADF Facesに暗黙的に採用されており、それらを実装するためのアクションは必要ありません。プログラミング・ガイドラインは、表33-6に示されています。

表33-6 アプリケーション・プログラミングのアクセシビリティ・ガイドライン

ガイドライン

アクション

マークアップを使用したページのリダイレクトを避ける

アクションは必要ありません。ADF Facesではページのリダイレクトにマークアップを使用しません。

各ページのDOCTYPEを指定する

アクションは必要ありません。ADF Facesでは、ページごとにDOCTYPEが指定されます。

絵や図のレンダリングにASCII文字の使用を避ける

アプリケーションにアスキーアート(文字絵)が含まれないようにします。

アプリケーション開発者向けのドキュメントでアクセシビリティを使用するものとして定義されているプラットフォームの機能を中断しない

アクションは必要ありません。ADF Facesでは、ADF Facesコンポーネントで生成されたコンテンツによりプラットフォームのアクセシビリティ機能が中断されないようにします。

他のコンポーネントの外観を制御するコンポーネントについて説明する

他のコンポーネントを制御するADF Facesコンポーネントが正しく説明されるようにします。他のコンポーネントに対する制御には、他のコンポーネントの有効化または無効化、非表示または表示、あるいはデフォルト値の変更などがあります。

常に整形式のHTMLコードを使用する

アクションは必要ありません。ADF Facesには、コンポーネントにより整形式のHTMLコードが生成されるようにする役割があります。

非推奨のHTML要素を使用しない

アクションは必要ありません。ADF Facesには、コンポーネントで非推奨のHTML要素が使用されないようにする役割があります。

セクションのヘッダーが非常にわかりやすく、ヘッダー要素H1からH6までが使用されていることを確認する

アクションは必要ありません。ADF Facesコンポーネントによってレンダリングされたすべてヘッダーでは、適切なHTMLヘッダー要素が使用されます。

リスト・コンテンツに適切なHTMLリスト要素が使用されるようにする

アクションは必要ありません。ADF Facesコンポーネントによってレンダリングされるすべてのリストでは、適切なHTMLリスト要素(OL、UL、LI、DL、DTおよびDDなど)が使用されます。

引用は適切な要素でマークする

引用はQまたはBLOCKQUOTE要素を使用して適切にマークされるようにします。インデントなどの効果の書式設定に引用マークアップを使用しないでください。

HTML要素上のlang属性により各ページの一次自然言語を識別する

アクションは必要ありません。ADF Facesでは、すべてのページでlang属性をレンダリングします。

すべてのフォーム要素にマークアップを使用してラベルが関連付けられているようにする

監査レポートを実行します。「コンポーネントにラベルが付いていることを確認してください。」監査ルールが欠落しているラベルについて警告します。

各FRAME要素またはIFRAME要素に一意のタイトルを付ける

監査レポートを実行します。「コンポーネントに短い説明があることを確認してください。」監査ルールが、af:inlineFrameにshortDescタイトルが付いていないときに警告します。

ADF Faces af:inlineFrameでは、longDescにアクセスできません。

フレーム各ページにタイトルを付ける

監査レポートを実行します。「コンポーネントにタイトルがあることを確認してください。」監査ルールは、af:documentにtitle属性がない場合に警告します。

ポップアップ・ウィンドウが開くと必ずフォーカスされ、閉じるとフォーカスが論理的な場所に戻るようにする

ADF Facesコンポーネントによって提供されるポップアップ・ウィンドウは、常に明示的なユーザー処理に応じて表示されます。ADF Facesでは、フォーカスが起動時に正しくポップアップ・ウィンドウに移動し、終了時に元に戻るようにもします。ただし、af:clientListenerまたはaf:showPopupBehaviorにより手動で起動されたポップアップ・ウィンドウの場合、ポップアップ・ウィンドウが明示的なユーザー処理に応じて起動されたことを確認する必要があります。

33.4.3 スタイルの使用方法

ADF Facesコンポーネントはすでにスタイルが設定されており、変更の必要はありません。カスケード・スタイル・シート(CSS)を使用してADF Facesコンポーネントのデフォルトの外観を直接変更する場合、表33-7で説明されているガイドラインに従う必要があります。

表33-7 アクセシビリティのスタイル・ガイドライン

ガイドライン

アクション

CSSの使用を最小限に維持する

すでにスタイルが設定されているので、CSSを直接ADFコンポーネントに指定する必要はありません。

コンポーネントのデフォルトの外観をオーバーライドしない

コンポーネントのデフォルトの外観をオーバーライドする場合、アクセシビリティへの影響を意識してください。CSSを使用してコンポーネントの外観を変更すると、アクセシビリティに影響する可能性があります。たとえば、色を変更すると色の対比の問題が発生します。

拡大縮小が可能なサイズ単位を使用する

CSSを使用してサイズを指定する場合は、絶対単位ではなく、フォント・サイズに対して拡大縮小が可能なサイズ単位を使用します。たとえば、pxではなく、em、exまたは%の単位を使用します。弱視のユーザーはフォント・サイズを拡大することがあり、高さが固定または絶対に制限されているコンテンツが欠ける原因になるため、CSSを使用して高さを指定する場合は特に重要です。ブラウザのズームに最も適合する大きいフォント・モードでこれを行うことが重要です。

CSSの位置設定は使用しない

CSSの位置設定は、拡大されたレイアウト・コンポーネントの位置設定の場合にのみ使用してください。それ以外にはCSSの位置設定を使用しないでください。

画面のレイアウトおよび表示の変更にはスタイル・シートを使用する

アクションは必要ありません。ADF Facesでは、レイアウトの実装にスタイル・シートのある構造要素が使用されます。

すべてのページにわたって均一の表示のスタイルを作成する

アクションは必要ありません。ADF Facesでは、そのスキニング・アーキテクチャにより均一の表示スタイルを提供します。

情報の伝達または処理の指示に色やフォント・スタイルを使用しない

情報伝達、処理の指示、レスポンスの要求または視覚的要素の区別の唯一の視覚的手段として、色またはフォント・スタイルが使用されないようにしてください。

33.4.4 ページ構造およびナビゲーションの使用方法

ページ構造およびナビゲーション・ツールを使用する際は、表33-8で説明されているガイドラインに従う必要があります。

表33-8 ページ構造およびナビゲーションのスタイル・ガイドライン

ガイドライン

アクション

レイアウトにaf:panelSplitterを使用する

ジオメトリ管理レイアウトを実装する際、af:panelSplitterを使用するとユーザーは次のことができます。

- 必要に応じて領域を再配分できます。

- すぐに使用しないコンテンツを非表示にするか閉じることができます。
af:panelStretchLayoutを使用する予定の場合、該当する場合はかわりにaf:panelStretchLayoutを使用する必要があります。

これらのページ構造の特性はすべてのユーザーにとって便利で、特に、弱視のユーザーやスクリーン・リーダーを使用するユーザーの役に立ちます。

たとえば、ページ上部にあるクロム・ナビゲーション・バーは、af:panelStretchLayoutコンポーネントのtopファセット内ではなく、垂直のaf:panelSplitterコンポーネントのfirstファセット内に配置する必要があります。これにより、ユーザーは、バーが使用する領域を減らすことや、すべてを非表示にすることができます。同様に、左、中央または右ペインがあるレイアウトでは、水平のスプリッタを使用してペインをレイアウトします。

フロー・レイアウト・コンテンツのスクロールを有効にする

フロー・レイアウト・コンテンツ(af:panelSplitterまたはaf:panelStretchLayoutなど、ジオメトリ管理される親コンポーネント内のレイアウト・コントロールなど)をネストさせる際には、layout="scroll"が指定されたaf:panelGroupLayoutでフロー・レイアウト・コンテンツをラップします。これにより、コンテンツが収まらないほどにフォント・サイズが拡大された場合に、スクロールバーが表示されます。これを実行しないと、コンテンツの欠落や切捨ての原因になります。

ページ構造の識別にはヘッダー・ベースのコンポーネントを使用する

HTMLヘッダー要素は、画面の可読性において重要な役割を果します。通常、スクリーン・リーダーを使用すると、HTMLヘッダー全体を調査または移動して、ユーザーはページの全体的な構造を理解できます。次のコンポーネントを含め、HTMLヘッダーのコンテンツをレンダリングするコンポーネントを介して、ページの主要部分を確認します。

- af:panelHeader

- af:showDetailHeader

- af:panelAccordionのaf:showDetailItem(ペインの各アコーディオンによりタイトル領域のHTMLヘッダーがレンダリングされます。)

ページ位置の識別にはaf:breadCrumbsを使用する

アクセシビリティ標準では、ユーザーがWebサイトまたはアプリケーション内での位置を確認できる必要があります。af:breadCrumbsを使用するとこれを実現できます。

スキップ・リンク・ターゲットの指定にはaf:skipLinkTargetを使用する

af:skipLinkTargetタグは、ページの初めで自動的にskip linkを生成する方法を提供します。これはスクリーン・リーダーとキーボードのどちらのユーザーにとっても役立ち、すべてのページで繰り返されるページレベルのクロムをスキップできるので便利です。af:skipLinkTargetタグをページ・テンプレートごとに1回指定する必要があります。

複数のページで繰り返されるナビゲーション・メカニズムの一貫性を維持する

ADF Facesナビゲーション・コンポーネントを使用することで、ナビゲーションの一貫性を確保します。

繰り返されるコンテンツをスキップするための方法を提供する

ページの先頭で繰り返されるコンテンツ(ナビゲーション・リンクなど)がある場合、繰り返されるコンテンツをスキップするためにaf:skipLinkTargetが使用されていることを確認します。

33.4.5 イメージおよび表の使用方法

イメージを使用する際は、表33-9で説明されているガイドラインに従う必要があります。

表33-9 イメージのスタイル・ガイドライン

ガイドライン

アクション

装飾用でないイメージのalt属性に説明を指定する

監査レポートを実行します。「コンポーネントに短い説明があることを確認してください。」監査ルールが、shortDesc属性がないことを警告します。shortDesc値は必ず意味のあるものにします。

装飾的なイメージ(スペーサ・イメージなど)では必ずalt=""属性を指定する

監査レポートを実行します。「コンポーネントに短い説明があることを確認してください。」監査ルールが、shortDesc属性がないことを警告します。shortDesc値は必ず意味のあるものにします。

グラフなどの複雑なイメージのalt属性に説明を指定する

複雑なaf:imageコンポーネントにはlongDesc属性が指定されていることを確認します。

スクリーン・リーダー・モードでは、グラフを表などのアクセス可能なコンポーネントに置き換えることを検討してもかまいません。

録音され同期化されたメディア(ビデオなど)にかわる音声またはテキストによる手段を提供する

適切な音声またはテキストの代替手段が提供されていることを確認します。

録音され同期化されたメディアにキャプションを付ける

適切なキャプションが付いていることを確認します。同期化されたメディアがテキストの代替手段で、明確なラベルが付いている場合、キャプションは不要です。

表を使用する際は、表33-10で説明されているガイドラインに従う必要があります。

表33-10 表のスタイル・ガイドライン

ガイドライン

アクション

常に表内の行または列にヘッダーを付ける

ADF Facesの表ベースのコンポーネントでは、行または列ヘッダー・データの適切なHTMLマークアップが用意されています。

監査レポートを実行します。「表の列にヘッダーがあることを確認してください。」監査ルールは、列ヘッダー・データがない場合に警告します。データまたはレイアウト表を作成するtrh:tableLayoutを使用するアプリケーションには、そのような表がすべてのOracleアクセシビリティ・ガイドラインに準拠していることを確認する役割があります。

summary属性またはCAPTION要素を使用して各表コンポーネントに説明を付ける

監査レポートを実行します。「表にサマリーがあることを確認してください。」監査ルールが、データ表にサマリー属性がない場合に警告します。

レイアウト表にTH要素が使用されていないことを確認する

アクションは必要ありません。ADF Facesでは、レイアウト・コンポーネントによりレイアウト表にTHが使用されていないことを確認します。

レイアウト表でsummary=""が指定され、CAPTION要素がないことを確認する

アクションは必要ありません。ADF Facesでは、レイアウト・コンポーネントでレイアウト表に空のサマリーが生成されることを確認します。

レイアウト表で正しい読上げ順序を指定する

アクションは必要ありません。ADF Facesでは、生成するすべてのレイアウト表で読上げ順序が正しいことを確認します。

33.4.6 WAI-ARIAランドマーク・リージョンの使用方法

WAI-ARIA標準では、ページの異なるセクションが異なるランドマーク・リージョンとして定義されます。WAI-ARIAロールとともに、それらが高度なページ構造についての情報を伝え、ランドマーク領域全体にわたる移動を容易にします。これは特に、スクリーン・リーダーなどの支援技術のユーザーにとって便利です。

ADF Facesには、表33-11に示すように、いくつかのレイアウト・コンポーネント用のランドマーク属性が含まれています。

表33-11 ランドマーク属性のあるADF Facesコンポーネント

コンポーネント

属性

decorativeBox

topLandmark

centerLandmark

panelGroupLayout

landmark

panelSplitter

firstLandmark

secondLandmark

panelStretchLayout

topLandmark

startLandmark

centerLandmark

endLandmark

bottomLandmark

これらの属性には、次のようなWAI-ARIAランドマーク・ロールのいずれかを設定できます。

- banner

- complimentary

- contentinfo

- main

- navigation

- search

ランドマーク関連の属性のいずれかが設定されている場合、ADF Facesでは指定された値でロール属性をレンダリングします。

33.5 アクセシビリティ監査ルールの実行

JDeveloperには、ADF Facesのアクセシビリティ監査ルールが用意されており、33.3.1項「ADF Facesコンポーネントのアクセシビリティ・ガイドライン」で説明されている、多くの一般的な要件に準拠しているかどうかが調査および報告されます。

33.5.1 コード監査プロファイルの作成方法

「プリファレンス」ダイアログから監査プロファイルを作成できます。

始める前に:

アクセシビリティ監査ルールについて理解しておくと役立ちます。詳細は、33.5項「アクセシビリティ監査ルールの実行」を参照してください。その他のADF Faces機能を使用して追加できる機能について理解しておくことも役に立ちます。詳細は、33.1.2項「ADFページでのアクセシビリティ・サポートの追加情報」を参照してください。

監査プロファイルを作成する手順:

1. メイン・メニューから、「ツール」→「プリファレンス」を選択します。

2. 「プリファレンス」ダイアログで、「監査」→「プロファイル」を選択します。

3. 「監査: プロファイル」ダイアログで、すべてのチェック・ボックスの選択を解除してから、「Application Development Framework (ADF)」→「ADF Faces」→「アクセシビリティ」チェック・ボックスを選択します。

4. 「別名保存」をクリックし、プロファイルに一意の名前を付けて保存します。
図33-10に、アクセシビリティ監査プロファイルを作成するための「監査: プロファイル」ダイアログの設定を示します。

図33-10 ADF Facesアクセシビリティの監査プロファイルの設定

5. 「OK」をクリックします。

33.5.2 監査レポートの実行方法

監査レポートの実行では、監査プロファイルの作成および実行が必要です。

始める前に:

アクセシビリティ監査ルールについて理解しておくと役立ちます。詳細は、33.5項「アクセシビリティ監査ルールの実行」を参照してください。その他のADF Faces機能を使用して追加できる機能について理解しておくことも役に立ちます。詳細は、33.1.2項「ADFページでのアクセシビリティ・サポートの追加情報」を参照してください。

監査レポートを実行する手順:

1. メイン・メニューから「ビルド」→「監査」ターゲットを選択します。

2. 「監査」ダイアログで、「プロファイル」ドロップダウン・メニューから、作成したADF Facesアクセシビリティ監査プロファイルを選択します。

図33-11 監査レポートを実行するための監査ダイアログ

3. 「実行」をクリックして、レポートを生成します。

監査レポートの結果は、ログ・ウィンドウに表示されます。レポート生成が完了したら、「ログ」ウィンドウ・ツールバーにある「エクスポート」アイコンをクリックして、レポートをHTMLファイルにエクスポートできます。

34 カスタムADF Facesコンポーネントの作成

この章では、カスタムADF Facesコンポーネントの作成方法を説明します。

この章では、次の項目について説明します。

- 34.1項「カスタムADF Facesコンポーネントについて」

- 34.2項「ワークスペースと基礎ファイルの設定」

- 34.3項「クライアント側の開発」

- 34.4項「サーバー側の開発」

- 34.5項「コンポーネント・ライブラリのデプロイ」

- 34.6項「アプリケーションへのカスタム・コンポーネントの追加」

34.1 カスタムADF Facesコンポーネントについて

ADF Facesコンポーネント・ライブラリには、ユーザー要件の大部分をカバーするUIコンポーネントの包括的なセットが用意されています。ただし、アプリケーションに固有のカスタム・リッチ・コンポーネントを作成する必要がある場合があります。カスタム・リッチ・コンポーネントによって、カスタム動作が可能になり、アプリケーションのニーズに最適なアクションを実行できます。

注意:

カスタムJSF Faceletコンポーネントの作成については、多くの本、記事、WebサイトおよびJavaServer Facesの仕様で取り上げられているため、このガイドでは説明しません。この章では、ADF Facesコンポーネントの作成方法を説明します。

JSFテクノロジは、コンポーネントとその他のフレームワーク部分を自己登録できるように構築されています。コアJSFランタイムでは、Webアプリケーションの起動時にクラス・パスのすべてのJARファイルを検査することで、自己登録が行われます。/META-INF/faces-config.xmlファイルにJSFアーティファクトが含まれるすべてのJARファイルがロードされます。そのため、カスタムADF FacesコンポーネントをJARファイルにパッケージ化し、Webプロジェクトに簡単に追加できます。

各ADF Facesコンポーネントにはサーバー側コンポーネントがあり、クライアント側コンポーネントがある場合もあります。サーバーでは、JSP用に、レンダー・キットによって、マークアップ言語とJavaScriptの複雑な組合せを調整するためのベースが提供されます。サーバー側フレームワークではカスタム・ライフサイクルも追加され、部分ページ・コンポーネント・レンダリングのAPIフックを利用できます。クライアントでは、ADF Facesにより、様々な重要なタスクを処理する構造化されたJavaScriptフレームワークが提供されます。それらのタスクには、部分ページ・レンダリングを使用した状態の同期化が含まれます。ADF Facesアーキテクチャの詳細は、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。

ADF Facesコンポーネントは、Apache MyFaces Trinidadコンポーネント・ライブラリから導出されます。このため、カスタムADF Facesコンポーネントを作成するときに拡張するクラスの多くは、実際にはMyFaces Trinidadのクラスとなります。ADF Facesの履歴(その発展を含む)の詳細は、第1章「ADF Facesの概要」を参照してください。

JSPコンポーネントとJSFコンポーネントの間にApplicationクラスがあります。タグ・ライブラリでは、applicationオブジェクトに対してファクトリ・メソッドが使用され、componentTypeと呼ばれるニーモニックを使用して具体的なコンポーネント・インスタンスがインスタンス化されます。

コンポーネントでは独自のマークアップをレンダリングできますが、これがベスト・プラクティスであるとは考えられていません。プレゼンテーションのレンダリングの戦略に焦点を当てたレンダー・キットを定義する方法をお薦めします。コンポーネントは、レンダー・キットに対してファクトリ・メソッドを使用して、特定のコンポーネントに関連付けられているレンダラを取得します。コンポーネントがFaceletを使用するアプリケーションで消費される場合、コンポーネント・ハンドラによってそのコンポーネントが作成されます。

作成するすべてのカスタム・コンポーネントでは、機能面に加え、その他のADF Facesコンポーネントで正しく表示されるようにするために、ADF Facesスキンを使用する必要があります。スキンを使用するには、コンポーネントのスキニング・キーとプロパティを作成して登録する必要があります。この章では、カスタム・コンポーネントのスキンの作成方法および登録方法のみ説明します。一般的なスキンの使用方法および作成方法の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ヒント:

ADF Facesコンポーネントを使用するには、skyrosスキンは簡単なスキンから継承するので、カスタム・コンポーネントは少なくとも簡単なADF Facesスキンを使用する必要があります。また、コンポーネントをOracle WebCenter Portalアプリケーションで使用する可能性がある場合は、使用するスキンはsimple.portletスキンにも登録する必要があります。

34.1.1 JDeveloperを使用したカスタム・コンポーネントの開発

ADF Facesコンポーネントは、クライアント側リソースとサーバー側リソースの両方で構成されています。クライアント側には、クライアント・コンポーネント、コンポーネント・ピア(コンポーネント・プレゼンタ)、およびクライアント・コンポーネントに関連付けられているすべてのイベントがあります。

サーバー側には、サーバー・コンポーネント、サーバー・コンポーネント・イベントおよびイベント・リスナーがあります。また、コンポーネント・レンダラ、コンポーネントJSPタグ、コンポジット・リソース・ローダー、JavaScriptリソース・ローダーおよびリソース・バンドルもあります。

コンポーネントには、いくつかの構成ファイルおよびサポート・ファイルもあります。これらのクラス、JavaScriptおよび構成ファイルは一緒に1つのJARファイルにパッケージ化され、ライブラリとしてアプリケーションにインポートして、他のコンポーネントと同様に使用できます。

JDeveloperを使用して、カスタム・コンポーネントを開発するアプリケーション・ワークスペースおよびプロジェクトを設定できます。ワークスペースおよびプロジェクトを作成したら、カスタム・コンポーネントを構成する必須のクラス、JavaScriptファイルおよび構成ファイルに対して、基礎作業ファイルを追加します。開発時には、カスタム・コンポーネントに固有のそれらのファイルをそれぞれ編集し、ファイルにコードを追加します。

開発プロセスは次のとおりです。

1. 開発の環境として、アプリケーション、ワークスペースおよびプロジェクトを作成します。これには、ライブラリ依存性の追加、XMLスキーマの登録が含まれます。コンポーネントは、そのコンポーネントを使用する予定があるアプリケーションには作成しないでください。

2. JARファイルにコンポーネントをパッケージ化するためのデプロイメント・プロファイルを作成します。

3. 次の基礎構成ファイルとサポート・ファイルを作成します。

- faces-config.xml: コンポーネントで使用される多くのアーティファクトを登録するために使用します。

- trinidad-skins.xml: コンポーネントが使用するスキンを登録するために使用します。

- Cascading Style Sheet: スキンのスタイル・プロパティを定義するために使用します。

- レンダー・キット・リソース・ローダー: コンポーネントで必要とされるすべてのリソースをアプリケーションでロードできるようにします。

- adf-js-features.xml: コンポーネントをJavaScriptパーティションの一部にできます。パーティションの詳細は、4.9項「JavaScriptライブラリのパーティション化」を参照してください。

- JSPタグ・ライブラリ・ディスクリプタ(TLD) (JSP用): JSFページで使用するタグを定義します。

- コンポーネント・ハンドラ(Facelet用): コンポーネントのレンダリングに使用するハンドラを定義します。

4. 次のクライアント側JavaScriptファイルを作成します。

- クライアント・コンポーネント: クライアントのコンポーネントとその属性を表します。

- クライアント・ピア: コンポーネントのDocument Object Model (DOM)を管理します。

- クライアント・イベント: クライアントでの処理を起動し、オプションでサーバーに処理を伝播します。

5. 次のサーバー側Javaファイルを作成します。

- サーバー・コンポーネント・クラス: サーバーのコンポーネントを表します。

- サーバー・イベント・リスナー・クラス: イベントをリスニングして、応答します。

- サーバー・イベント・クラス: サーバーのイベントを起動します。

- サーバー・レンダラ・クラス: コンポーネントの表示を決定します。

- リソース・バンドル・クラス: コンポーネントで使用されるテキスト文字列を定義します。

6. JavaScriptおよびJavaコードをテストおよびデバッグして、コンポーネントの開発をさらに進めます。JDeveloperデバッガを使用して、ブレークポイントを設定し、コードを段階的に開発できます。Javaロギング機能を使用して、コンポーネントの実行をトレースすることもできます。

7. JARファイルにコンポーネントをデプロイします。

8. コンポーネントをアプリケーションに追加してテストします。

表34-1には、カスタム・コンポーネントのクライアント側およびサーバー側コンポーネントのアーティファクトがリストされています。この表には構成ファイルおよびサポート・ファイルは含まれていません。

表34-1 カスタム・コンポーネントのクライアント側およびサーバー側アーティファクト

クライアント

サーバー

コンポーネント・クラス:

oracle.component_package.js.component.prefixComponent_name.js

拡張:

oracle.adf.view.js.component.AdfUIObject.js

コンポーネント:

oracle.<component_package>.faces.component.<Component_name>.java

拡張:

org.apache.myfaces.trinidad.component.UIXObject.java

イベント:

oracle.<component_package>.js.event.<prefix><Event_name>.js

拡張:

oracle.adf.view.js.component.AdfComponentEvent.js

イベント:

oracle.<component_package>.faces.event.<Event_name>.java

拡張:

javax.faces.event.FacesEvent.java

イベント・リスナー:

oracle.<component_package>.faces.event<Listener_name>

拡張:

com.faces.event.FacesListener

コンポーネント・ピア:

com.<component_package>.js.component.<prefix><Peer_name>Peer.js

拡張:

oracle.adf.view.js.laf.rich.AdfRichUIPeer.js.js

コンポーネント・レンダラ:

com.<component_package>.faces.render.<Renderer_name>.java

拡張:

oracle.adf.view.rich.render.RichRenderer.java

コンポーネントJSPタグ(JSP専用):

com.<component_package>.faces.taglib.<Tagname_name>Tag.java

拡張:

javax.faces.webapp.UIComponentELTag.java

コンポジット・リソース・ローダー:

com.<component_package>.faces.resource.<Loader_name>ResourceLoader.java

拡張:

org.myfaces.trinidad.resource.RegxResourceLoader.java

JavaScriptリソース・ローダー:

com.<component_package>.faces.resource.<Script_Loader_name>ResourceLoader.java

拡張:

org.myfaces.trinidad.resource.AggregateingResourceLoader.java

リソース・バンドル:

com.<component_package>.faces.resource.<Bundle_name>Bundle.java

拡張:

java.util.ListResouceBundle.java

34.1.2 カスタム・コンポーネントの例

カスタム・コンポーネントの作成について説明するために、手順全体でtagPaneという名前のカスタム・コンポーネントを例として使用します。tagPaneカスタム・コンポーネントは、再利用の目的で作成されます。tagPaneのプレゼンテーションは、既存の様々なコンポーネントを使用して実装可能ですが、単一のカスタム・コンポーネントを作成するとページ開発者の作業が単純化されます。この場合、コンポーネント開発者とページ開発者間の生産性においてトレードオフが生じることがあります。この特定のビューを複数回作成する必要がある場合、開発チームはコード行を減らし、ビジネス・プロセスの自動化タスクを単純化することで、コストを削減できます。

tagPaneコンポーネントは、ファイル・セットに対する一連のタグとその出現の重み付けを表示します。最も頻繁に使用されるタグは最大フォント・サイズで表示され、最も使用されないタグは最小フォント・サイズで表示されます。各タグはイベントをトリガーするリンクでもあり、トリガーされたイベントはサーバーに伝播されます。サーバーでは、そのタグを含むすべてのファイルが表に表示されます。図34-1に、tagPaneコンポーネントがFile Explorerアプリケーションの「検索」ペインの下に追加された場合にどのように表示されるかを示します。

図34-1 カスタムtagPaneコンポーネント

tagPaneコンポーネントは、Java Mapコレクションのタグのコレクションを受け取ります。マップのキーはタグ名です。値はタグに割り当てられた重みです。File Explorerアプリケーションでは、重みはタグの出現回数であり、多くの場合、タグに関連付けられているファイル数です。タグ名はリンクのボディ・テキストに表示され、名前の表示に使用されるフォント・サイズが重みを表します。各タグのフォント・サイズは、ファイル・セット内のすべてのタグに割り当てられている重みの最大と最小に基づき、最大フォント・サイズと最小フォント・サイズ内で相対的に計算されます。これらの機能を実行するには、tagPaneカスタム・コンポーネントにクライアント側とサーバー側の両方の動作を設定する必要があります。

サーバー側では、コンポーネントはHTMLハイパーリンクをレンダリングすることでタグのマップを表示します。基本的なマークアップ・レンダリングはサーバー側で実行されます。コンポーネントには、ユーザーによるリンクのクリックを処理し、関連ファイルを表示するためのカスタム・イベントを定義します。これらのサーバー側の動作は、値式およびメソッド式を使用して定義します。

たとえば、tagPaneコンポーネントには次のものが含まれます。

- タグのMap<String, Number>コレクションを設定するtagプロパティ。

- タグのリンクをクリックしたときにサーバーで起動されるtagSelectionListenerメソッド・バインディング・イベント。

- 重みの降順で左から右に一連のタグを表示する、またはアルファベットの昇順にタグのリンクを表示するためのorderByプロパティ。

各タグをその重み(出現回数)に比例したフォント・サイズで表示するために、フォント・サイズはインライン・スタイルを使用して制御されます。ただし、各タグとコンポーネントのルート・マークアップ・ノードもスタイル・クラスを使用します。

例34-1に、tagPaneコンポーネントのJSFページでの使用方法を示します。

例34-1 JSFページのtagPaneカスタム・コンポーネント・タグ

<acme:tagPane id="tagPane" tags="#{explorer.navigatorManager.tagNavigator.tags}"
tagSelectListener="#{explorer.navigatorManager.tagNavigator.onTagSelect}"
orderBy="alpha"
partialTriggers="tagCountLabel"/>

tagPaneコンポーネントは、他のADF Facesコンポーネントとともに使用される必要があるため、同じスキンを使用する必要があります。そのため、すべてのスタイル設定は、Cascading Style Sheet (CSS)および対応するスキン・セレクタを使用して実現されます。たとえば、tagPaneコンポーネントでは、ルート要素を指定し、リンクのコンテナのスタイルおよびハイパーリンクの表示方法を定義するために、スキン・セレクタが必要です。例34-2に、tagPaneコンポーネントのCSSファイル内のスタイル・セレクタのサンプル・セットを示します。

例34-2 サンプル・カスタム・コンポーネントのCSSスタイル・セレクタ

acme|tagPane     - root element
acme|tagPane::content - container for the links
acme|tagPane::tag - tag hyperlink

サーバー側のカスタム・コンポーネントに必要なHTMLコードを指定する必要がある場合もあります。

例34-3に、tagPaneコンポーネントで使用されるHTMLのサーバー側のコードを示します。

例34-3 サーバー側のHTMLコード

<div class=" acme|tagPane">
<span class=" acme|tagPane::content ">
<a class=" acme|tagPane::tag" href="#" style="font-size:9px;">Tag1</a>
<a class=" acme|tagPane::tag" href="#" style="font-size:10px;">Tag2</a>
</span>
</div>

クライアント側のコンポーネントには、クライアント側の動作を定義する、対応するJavaScriptコンポーネントとコンポーネント・ピアが必要です。DOMとのすべての対話は、ピアを使用して行われます(詳細は、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください)。コンポーネント・ピアでは、タグ名を囲むハイパーリンクのクリックがリスニングされます。リンクがクリックされると、ピアによってクライアント側でカスタム・イベントが発生し、そのイベントがサーバー側に伝播されて、追加処理されます。

表34-2には、tagPaneコンポーネントのクライアント側とサーバー側のアーティファクトがリストされています。表34-1のネーミング規則を参照すると、component_packageはcom.adfdemo.acme、prefixはAcmeです。

表34-2 tagPaneカスタム・コンポーネントのクライアント側およびサーバー側アーティファクト

クライアント

サーバー

コンポーネント:

com.adfdemo.acme.js.component.AcmeTagPane.js

拡張:

oracle.adf.view.js.component.AdfUIObject.js

コンポーネント

com.adfdemo.acme.faces.component.TagPane.java

拡張:

org.apache.myfaces.trinidad.component.UIXObject.java

イベント:

com.adfdemo.acme.js.event.AcmeTagSelectEvent.js

拡張:

oracle.adf.view.js.component.AdfComponentEvent.js

イベント:

com.adfdemo.acme.faces.event.TagSelectEvent.java

拡張:

javax.faces.event.FacesEvent.java

イベント・リスナー:

com.adfdemo.acme.faces.event.SelectListener

拡張:

com.faces.event.FacesListener

コンポーネント・ピア:

com.adfdemo.acme.js.component.AcmeTagPanePeer.js

拡張:

oracle.adf.view.js.laf.rich.AdfRichUIPeer.js

コンポーネント・レンダラ:

com.adfdemo.acme.faces.render.TagPaneRenderer.java

拡張:

oracle.adf.view.rich.render.RichRenderer.java

コンポーネントJSPタグ:

oracle.adfdemo.acme.faces.taglib.TagPaneTag.java

拡張:

javax.faces.webapp.UIComponentELTag.java

コンポジット・リソース・ローダー:

oracle.adfdemo.acme.faces.resource.AcmeResourceLoader.java

拡張:

org.myfaces.trinidad.resource.RegxResourceLoader.java

JavaScriptリソース・ローダー:

oracle.adfdemo.acme.faces.resource.ScriptsResourceLoader.java

拡張:

org.myfaces.trinidad.resource.AggregateingResourceLoader.java

リソース・バンドル:

oracle.adfdemo.acme.faces.resource.AcmeSimpleDesktopBundle.java

拡張:

java.util.ListResouceBundle.java

これらのアーティファクトの一部のサンプル・コードは、F.4項「サンプル」を参照してください。

34.2 ワークスペースと基礎ファイルの設定

JDeveloperを使用して、カスタム・コンポーネントを開発するためのアプリケーションおよびプロジェクトを設定します。スケルトン・プロジェクトを作成すると、JARファイルにコンポーネントをパッケージ化するためのデプロイメント・プロファイルを追加できます。

開発の初期段階では、開発を可能にするための基礎構成ファイルとサポート・ファイルを作成します。これらのファイルはプロセス中に追加および編集することもできます。次の構成ファイルを作成します。

- META-INF/faces-config.xml: すべてのJSFベースのアプリケーションに必要な構成ファイルです。最終的にコンポーネントがインポートされるアプリケーションで、コンポーネントがfaces-config.xmlファイルを使用する間は、開発でこの構成ファイルが必要になります。

- META-INF/trinidad-skins.xml: コンポーネントが使用できるスキンの構成情報です。新規コンポーネントを含めるために、ADF Facesによって提供される簡単なスキンを拡張します。

- META-INF/package_directory/styles/skinName.css: コンポーネントをスキンするために必要なスタイル・メタデータです。

- META-INF/servlets/resources/name.resources: コンポーネントJARファイルからスタイルシートとイメージをロードするレンダー・キット・リソース・ローダーです。リソース・ローダーは、Webアプリケーションのリソース・サーブレットによって集約され、リソース・サーブレットを構成するために使用されます。サーブレットでリソース・ローダー・ファイルを見つけるには、ファイルをMETA-INF/servlets/resourcesディレクトリに配置する必要があります。

- META-INF/adf-js-features.xml: 機能を定義するために使用する構成ファイルです。通常、定義には、コンポーネント名またはコンポーネントが提供する機能の説明、およびクライアント側のコンポーネントを実装するために使用するファイルが含まれます。

- META-INF/prefix_name.tld (JSP用): コンポーネントのタグ定義ライブラリです。使用WebアプリケーションでJSPを使用している場合、カスタム・コンポーネントに定義済のTLDが必要です。TLDファイルは、faces-config.xmlおよびtrinidad-skins.xmlファイルとともにMETA-INFディレクトリにあります。

- META-INF/prefix_name.taglib.xml (Facelet用): 使用アプリケーションがFaceletを使用する場合のコンポーネントのタグ・ライブラリ定義です。このファイルではコンポーネントのハンドラを定義します。

たとえば、tagPaneコンポーネントには次の構成ファイルが必要です。

- META-INF/faces-config.xml

- META-INF/trinidad-skins.xml

- META-INF/acme/styles/acme-simple-desktop.css

- META-INF/servlets/resources/acme.resources

- META-INF/acme.tld

- META-INF/acme.taglib.xml

- META-INF/adf-js-features.xml

ファイルがJDeveloperに設定されたら、ファイルにコンテンツを追加します。次に、クライアント側のファイルとサーバー側のファイルを作成します。詳細は、34.3項「クライアント側の開発」および34.4項「サーバー側の開発」を参照してください。

34.2.1 JDeveloperカスタム・コンポーネント環境の設定方法

この章では、ユーザーがJDeveloperの使用経験があり、アプリケーションの作成およびデプロイに伴う手順に精通していると仮定しています。JDeveloperを使用したアプリケーションの作成の詳細は、第3章「ADF FacesとJDeveloperの概要」を参照してください。デプロイの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「Fusion Webアプリケーションの開発」の章を参照してください。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

JDeveloperでカスタム・コンポーネントの開発環境を設定する手順:

1. コンポーネントの開発コンテナとして機能するアプリケーションを作成します。JDeveloperを使用して、ワークスペースおよびプロジェクトを作成します。アプリケーション作成の手順は、3.2項「アプリケーション・ワークスペースの作成」を参照してください。アプリケーション・テンプレートを選択する場合は、「汎用アプリケーション」テンプレートを選択します。

注意:

他のアプリケーション・テンプレートを選択したり、他のテクノロジをアプリケーションに追加したりしないでください。カスタム・コンポーネントはJARファイルにパッケージ化されるため、Webアプリケーションに固有のテンプレートを使用するときまたはWebテクノロジを追加するときに、デフォルトでJDeveloperによって作成されるpublic_htmlのような不要なフォルダを作成する必要はありません。かわりに、XMLスキーマから基礎構成ファイルを作成します。

2. 新しいデプロイメント・プロファイルを作成し、プロジェクトをJARファイルとしてデプロイできるようにします。

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「デプロイメント・プロファイル」→「ADFライブラリのJARファイル」を選択して、「OK」をクリックします。

3. 「デプロイメント・プロファイルの作成」ダイアログで、「デプロイメント・プロファイル名」に名前を入力します。たとえば、tagPaneコンポーネントの場合は、adf-richclient-demo-acmeを使用します。

4. 「JARデプロイメント・プロファイルのプロパティの編集」ダイアログで、「OK」をクリックします。

3. 「プロジェクト・プロパティ」ダイアログで、ライブラリ依存性を追加します。

1. 左ペインで「ライブラリとクラスパス」を選択します。

2. 「ライブラリの追加」をクリックします。

3. 「ライブラリの追加」ダイアログで、ADF Faces Runtime 11、Faceletランタイム(Faceletを使用する場合)、JSF 2.1およびJRF Runtimeを選択して、「OK」をクリックします。

4. 「OK」をクリックして、「プロジェクト・プロパティ」ダイアログを閉じます。

4. XMLスキーマを登録します。
カスタム・コンポーネントには、複数のXML構成ファイルが必要です。JDeveloperを使用して、それらの構成ファイルに関連付けられているXMLスキーマを登録できます。faces-config.xml、trinidad-skins.xmlおよびtrinidad-config.xmlの3つの構成ファイルのスキーマを追加する必要があります。これらのスキーマを事前登録することにより、マークアップ構造の詳細を理解できなくても、テンプレートXML構成ファイルを作成できます。スキーマの名前と場所は、JDeveloperのベース・インストールによって想定されます。

1. 「ツール」→「設定」を選択します。「設定」ダイアログの左ペインで「XMLスキーマ」を選択し、「追加」をクリックします。

2. 表34-3に示すように、「スキーマの追加」ダイアログで「参照」をクリックして、JDeveloperビルドに含まれているXMLスキーマに移動します。

注意:

「スキーマの追加」ダイアログでは、「拡張子」が.xmlに設定されていることを確認してください。拡張子をXSDに変更すると、後でXMLファイルを作成するときに、作成したXMLスキーマを使用できなくなります。

表34-3 XMLスキーマの場所

XML構成ファイル

スキーマの場所

/META-INF/faces-config.xml

JDeveloper_Home/jdeveloper/modules/oracle.jsf_1.2.9/glassfish.jsf_1.2.9jar!/com/sun/faces/web-facesconfig_1_2.xsd

/META-INF/trinidad-skins.xml

JDeveloper_Home/jdeveloper/modules/oralce.adf.view_11.1.1/trinidad-impl.jar!/org/apache/myfaces/trinidadinternal/ui/laf/xml/schemas/skin/trinidad-skins.xsd

/META-INF/trinidad-config.xml

JDeveloper_Home/jdeveloper/modules/oracle.adf.view_11.1.1/trinidad-api.jar!/trinidad-config.xsd

/META-INF/adf-js-features.xml

JDeveloper_Home/jdeveloper/modules/oracle.adf.view_11.1.1/adf-richclient-api-ll.jar!/adf-js-features.xsd

34.2.2 Faces構成ファイルの追加方法

カスタム・コンポーネントは使用アプリケーションのfaces-config.xmlファイルに登録されますが、開発中は、ワークスペースにfaces-config.xmlファイルが必要です。

注意:

JDeveloperの宣言ウィザードやダイアログを使用してfaces-config.xmlファイルを作成しないでください。これらの宣言メソッドは、Webアプリケーションの作成を前提としており、カスタム・コンポーネント・アプリケーションに不要なアーティファクトが追加されます。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

カスタム・コンポーネントのfaces-config.xmlファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」の「一般」を展開し、「XML」を選択してから「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

3. 「XMLスキーマからXMLを作成」ダイアログで、次のように設定します。

- XMLファイル: faces-config.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

4. 次の内容を入力します。

- ターゲット・ネームスペース: http://java.sun.com/xml/ns/javaeeを選択します。

- ルート要素: faces-configを選択します。

他のフィールドはデフォルトのままにして、「終了」をクリックします。

新しいファイルがXMLエディタで自動的に開きます。

5. ファイルの最初の行の後に次のスキーマ情報を追加します。

<?xml version="1.0" encoding="US-ASCII"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">

スキーマを追加することで、より多くのWYSIWYGツール・サポートを得られます。

34.2.3 MyFaces Trinidadスキン構成ファイルの追加方法

MyFaces Trinidadスキン・ファイルを追加して、コンポーネントのスタイルを定義するために使用するコンポーネントのCSSファイルを登録します。

カスタム・コンポーネントのtrinidad-skins.xmlファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」の「一般」を展開し、「XML」を選択してから「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

3. 「XMLスキーマからXMLを作成」ダイアログで、次のように設定します。

- XMLファイル: trinidad-skins.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

4. 次の内容を入力します。

- ターゲット・ネームスペース: http://myfaces.apache.org/trinidad/skinを選択します。

- ルート要素: skinsを選択します。

- 「終了」をクリックします。新しいファイルがXMLエディタで自動的に開きます。

34.2.4 Cascading Style Sheetの追加方法

Cascading Style Sheetを追加して、コンポーネントのスタイルを定義します。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

カスタム・コンポーネントのCascading Style Sheetを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「すべてのアイテム」をクリックし、「ファイル」を選択して、「OK」をクリックします。

3. 「ファイルの作成」ダイアログで、次のように設定します。

- ファイル名、たとえばacme-simple-desktop.cssを入力します。

- \src\META-INF\component_prefix\stylesを「ディレクトリ」エントリの終わりに追加します(component_prefixはコンポーネント・ライブラリで使用される接頭辞です)。たとえば、tagPaneコンポーネントの場合、acmeが接頭辞であるため、追加する文字列は\META-INF\acme\stylesになります。

34.2.5 リソース・キット・ローダーの追加方法

空のファイルを作成し、カスタム・リソース・ローダーへの完全修飾クラス・パスを追加します。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

カスタム・コンポーネントのリソース・ローダーを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「すべてのアイテム」をクリックし、「ファイル」を選択して、「OK」をクリックします。

3. 「ファイルの作成」ダイアログで、次のように設定します。

- 「ファイル名」にcomponent_prefix.resourcesを入力し、component_prefixはコンポーネント・ライブラリで使用される接頭辞になります。たとえば、tagPaneコンポーネントの場合、acmeが接頭辞であるため、入力する文字列はacme.resourcesになります。

- ディレクトリ・エントリの最後に\src\META-INF\sevlets\resources\を追加します。

34.2.6 JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法

JSFページを使用するにはJSP TLDファイルが必要です。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

カスタム・コンポーネントのJavaServer Pages TLDファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」でWeb Tierノードを展開し、「JSP」、「JSPタグ・ライブラリ」の順に選択し、「OK」をクリックします。

3. 「JavaServer Pageタグ・ライブラリ作成」ダイアログで「デプロイ可能」を選択し、「次へ」をクリックします。

4. 次の内容を入力します。

- タグ・ライブラリ・ディスクリプタのバージョン: 2.1を選択します。

- 短縮名: 名前。たとえば、tagPaneコンポーネントの場合、acmeと入力します。

- タグ・ライブラリのバージョン: タグ・ライブラリのバージョン。たとえば、1.0などです。

- タグ・ライブラリURI: タグ・ライブラリのURIを入力します。たとえば、tagPaneコンポーネントの場合、http://oracle.adfdemo.acmeと入力します。

- タグ・ライブラリ情報: タグ・ライブラリの追加情報または説明を入力します。

5. 「次へ」をクリックし、オプションで追加のタグ・ライブラリ情報を入力して、「終了」をクリックします。

34.2.7 JavaScriptライブラリ機能構成ファイルの追加方法

機能ファイルを追加して、カスタム・コンポーネントに関連付けられているJavaScriptファイルを定義します。クライアント・コンポーネント、クライアント・ピアおよびクライアント・イベントのファイルが含まれます。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

カスタム・コンポーネントのadf-js-features.xmlファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」の「一般」を展開し、「XML」を選択してから「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

3. 「XMLスキーマからXMLを作成」ダイアログで、次のように設定します。

- XMLファイル: adf-js-features.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

4. 次のように設定します。

- ターゲット・ネームスペース: http://xmlns.oracle.com/adf/faces/featureを選択します。

- ルート要素: featuresを選択します。

- 「終了」をクリックします。新しいファイルがXMLエディタで自動的に開きます。

34.2.8 Faceletタグ・ライブラリ構成ファイルの追加方法

使用アプリケーションでFaceletを使用する場合、そのコンポーネントにハンドラを定義する必要があります。

始める前に:

カスタムADF Facesコンポーネントに必要なワークスペースおよび基礎ファイルについて理解しておくと役立ちます。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

Faceletタグ・ライブラリ・ファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

3. 「XMLファイルの作成」ダイアログで、次の入力を行います。

- ファイル名: prefix_name.taglib.xmlを入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

4. 例34-4に示すコードをコピーし、貼り付けます。

例34-4 Faceletタグ・ライブラリ構成ファイルのコード

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE facelet-taglib
PUBLIC "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN" "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">
<facelet-taglib xmlns="http://java.sun.com/JSF/Facelet">

<namespace>http://xmlns.oracle.adfdemo/acme</namespace>

<tag>
<tag-name>tagPane</tag-name>
<handler-class>
oracle.adfinternal.view.faces.facelets.rich.RichComponentHandler
</handler-class>
</tag>
</facelet-taglib>

5. 太字で示したネームスペースとタグ名のコードをアプリケーションに適したコードに置き換えます。

34.3 クライアント側の開発

JDeveloperワークスペースおよび構成ファイルを作成すると、クライアント側のJavaScriptファイルを作成およびコーディングできます。クライアント側の開発が終了したら、34.4項「サーバー側の開発」で説明されているように、サーバー側のファイルを作成します。

ベスト・プラクティス:

JavaScriptライブラリにはネームスペースがないため、カスタム・コンポーネントのすべてのJavaScriptオブジェクト名は、同じ接頭辞を使用して作成する必要があります。サーバー側のJavaパッケージ名では名前の競合が回避されるため、サーバー側では同じ接頭辞を使用する必要はありません。たとえば、tagPaneコンポーネントの場合、クライアント側のJavaScriptオブジェクト名すべてに接頭辞acmeを付けます。

クライアント・コンポーネントは、対応するDOM要素内で定義されていないプロパティの状態を保持します。これらのプロパティは、clientIdを使用して関連するDOM要素にバインドされます。clientIdによって、ページを表すコンポーネント・ツリーにサーバー側コンポーネントが一意に定義されます。DOM要素では、Id属性内にclientIdが保持されます。

注意:

ベスト・プラクティスおよび一貫性の点から、各JavaScriptオブジェクトはそれぞれの独自のソース・ファイルに配置してください。

クライアント側コンポーネントの開発では、コンポーネント、ピアおよびコンポーネント・イベントのJavaScriptファイルを作成する必要があります。

クライアント・コンポーネントに加えて、クライアント側のイベントも定義する必要があります。tagPaneコンポーネントのクライアント側のイベントは、ユーザーが3つのファイル・タイプのいずれかをクリックすると起動して、サーバーに伝播されます。サーバーに渡されたクライアント・イベントは、ターゲット・サーバー側のコンポーネントが適切なアクションを実行できるようにキューイングされます。

さらに、カスタム・コンポーネントにはクライアント・ピアが必要です。ピアはコンポーネント・プレゼンタです。ピアは、クライアント・コンポーネントと関連するDOM要素間のリンクとして機能します。クライアント・ピアによってクライアントの動作が追加されます。ピアは、登録メソッドを使用してコンポーネントにバインドする必要があります。

クライアント・コンポーネントに関連付けられているピアは、コンポーネントのclientIdを使用してDOM要素にバインドされます。ピアには、ステートフルとステートレスの2つのタイプがあります。

- 一部の複雑なクライアント・コンポーネントでは、ピアで状態を保持する必要があるため、ステートフル・ピアを使用する必要があります。このタイプのピアは、常にDOM要素にバインドされます。ステートフル・ピアよりも、ステートレス・ピアの方が一般的です。

- ステートレス・ピアでは状態は保持されないので、1つのピアを複数のコンポーネントにバインドできます。クライアントのフットプリントが削減されるため、ステートレス・ピアはパフォーマンスの点では最適なオプションです。このタイプのピアでは、コンポーネントへのコンテンツの遅延配信が実行されます。

ピアでは、DOMイベントを動的に登録およびリスニングすることで、コンポーネントに動作が追加されます。概念的には、ピアの機能はマネージドBeanの役割と似ています。ただし、サーバー側コンポーネントはビュー・モデル(#{backingbean.callback})にバインドされますが、クライアント・コンポーネントはELを使用してピアにはバインドされません。ピアは、InitSubclass (AdfRichUIPeer.addComponentEventHandlers("click"))コールバック・メソッドでクライアント・コンポーネント・イベントに登録されます。コールバックでは、ネーミング規則(<Peer>.prototype.HandleComponent<Event>)を使用することが前提となっています。ピアでは、サーバー側コンポーネントがマネージドBeanへのELバインディングを使用してリンクを処理する、DOMイベント・コールバックが管理されます。クライアント側アーキテクチャ(ピアを含む)の詳細は、4.1項「ADF Facesアーキテクチャの使用について」を参照してください。

次の項では、カスタム・コンポーネント開発テンプレート環境がすでに設定されていると仮定しています。この開発環境には、アプリケーション・ワークスペース、プロジェクトおよびデプロイメント・プロファイルの設定、およびスキーマの登録が含まれます。まだ設定していない場合は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

34.3.1 コンポーネントのJavaScriptファイルの作成方法

JDeveloperを使用して、コンポーネントのJavaScriptファイルを作成します。その中に、コンポーネントのコンポーネント・タイプを定義します。

始める前に:

カスタムADF Facesコンポーネントのクライアント側の開発について理解しておくと役立ちます。詳細は、34.3項「クライアント側の開発」を参照してください。

ワークスペースを設定し、構成ファイルを作成しておく必要もあります。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

コンポーネントのJavaScriptファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」→「JavaScriptファイル」を選択して、「OK」をクリックします。

3. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagPane.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、コンポーネントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adfrichclient-demo-acme\src\oracle\adfdemo\acme\js\componentと入力します。

4. JavaScriptファイルのエディタで、コンポーネント・コードを追加して、コンポーネント・タイプを定義します。例34-5に、tagPaneコンポーネントで使用されるコードを示します。

例34-5 tagPaneコンポーネントのJavaScript

AdfUIComponents.createComponentClass(
"AcmeTagPane",
{
componentType:"oracle.adfdemo.acme.TagPane",superclass:AdfUIObject
}
);

34.3.2 イベントのJavaScriptファイルの作成方法

JDeveloperを使用して、イベントのJavaScriptファイルを作成します。イベントが起動されたとき(マウス・クリックなど)に必要な機能を実行するためのコードをJavaScriptに追加します。

始める前に:

カスタムADF Facesコンポーネントのクライアント側の開発について理解しておくと役立ちます。詳細は、34.3項「クライアント側の開発」を参照してください。

ワークスペースを設定し、構成ファイルを作成しておく必要もあります。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

イベントのJavaScriptを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」→「JavaScriptファイル」を選択して、「OK」をクリックします。

3. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側イベントの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagSelectEvent.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、イベントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adf-richclient-demo-acme\src\oracle\adfdemo\acme\js\eventと入力します。

4. JavaScriptファイルのエディタで、イベント・コードを追加します。tagPaneコンポーネントに追加されるイベント・コードを示す例は、第F.4.1項「JavaScriptのイベント・コード」を参照してください。

34.3.3 ピアのJavaScriptファイルの作成方法

JDeveloperを使用して、ピアのJavaScriptファイルを作成します。コードを追加してピアを登録し、コンポーネントにバインドします。

始める前に:

カスタムADF Facesコンポーネントのクライアント側の開発について理解しておくと役立ちます。詳細は、34.3項「クライアント側の開発」を参照してください。

コンポーネント用のJavaScriptファイルも作成しておく必要があります。詳細は、34.3.1項「コンポーネントのJavaScriptファイルの作成方法」を参照してください。

ピアのJavaScriptファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」→「JavaScriptファイル」を選択して、「OK」をクリックします。

3. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側ピアの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagPanePeer.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、イベントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adf-richclient-demo-acme\src\oracle\adfdemo\acme\js\componentと入力します。

4. JavaScriptファイルのエディタで、ピアのコードを追加します。このコードで、ピアを作成し、DOMに関するイベント処理を追加し、ピアをコンポーネントに登録する必要があります。例34-6に、tagPaneコンポーネントに追加されるコードを示します。

例34-6 tagPaneのJavaScriptピア

AdfRichUIPeer.createPeerClass(AdfRichUIPeer, "AcmeTagPanePeer", true);
AcmeTagPanePeer.InitSubclass = function()
{
AdfLogger.LOGGER.logMessage(AdfLogger.FINEST,
"AcmeTagPanePeer.InitSubclass()");
AdfRichUIPeer.addComponentEventHandlers(this,
AdfUIInputEvent.CLICK_EVENT_TYPE);
}

AcmeTagPanePeer.prototype.HandleComponentClick = function(componentEvent)
{
AdfLogger.LOGGER.logMessage(AdfLogger.FINEST, "AcmeTagPanePeer.HandleComponentClick(componentEvent)");
// if the left mouse button was pressed
if (componentEvent.isLeftButtonPressed())
{
// find component for the peer
var component = this.getComponent();
AdfAssert.assertPrototype(component, AcmeTagPane);
// find the native dom element for the click event
var target = componentEvent.getNativeEventTarget();
if (target && target.tagName == "A")
{
AdfLogger.LOGGER.logMessage(AdfLogger.FINEST, "File type element (A)
found: " + componentEvent.toString());
var tag = target.firstChild.nodeValue;
AdfAssert.assertString(tag);

AdfLogger.LOGGER.logMessage(AdfLogger.FINEST, "tag :" + tag);
// fire a select event
AcmeTagSelectEvent.queue(component, tag);
//cancel the native dom onclick to prevent browser actions based on the
//'#' hyperlink. The event is of type AdfIEUIInputEvent. This event
//will cancle the native dom event by calling
//AdfAgent.AGENT.preventDefault(Event)
componentEvent.cancel();
}
// event has dom node
}
}
// Register the peer with the component. This bit of script must
// be invoked after the AcmeTagPane and AcmeTagSelectEvent objects
// are created. This is enforced by the ordering of the script files
// in the
oracle.asfdemo.acme.faces.resource.AcmeResourceLoader.
AcmeScriptsResourceLoader.AdfPage.PAGE.getLookAndFeel()
.registerPeerConstructor("oracle.adfdemo.acme.TagPane",
"AcmeTagPanePeer");

34.3.4 JavaScriptライブラリ機能構成ファイルへのカスタム・コンポーネントの追加方法

コンポーネントのすべてのJavaScriptファイルを作成すると、そのコンポーネントを作成したadf-js-features.xmlファイルに追加できます。

始める前に:

カスタムADF Facesコンポーネントのクライアント側の開発について理解しておくと役立ちます。詳細は、34.3項「クライアント側の開発」を参照してください。

コンポーネント用のJavaScriptファイルも作成しておく必要があります。詳細は、34.3.1項「コンポーネントのJavaScriptファイルの作成方法」を参照してください。

カスタム・コンポーネントをJavaScriptライブラリ機能構成ファイルに追加する手順:

4.9.1項「JavaScript機能の作成方法」に記述されている手順に従い、XMLファイルがすでに作成されている場合は、その手順を省略します。例34-7に、tagPaneコンポーネントで使用されるadf-js-features.xmlファイルを示します。

例34-7 tagPaneコンポーネントのadf-js-features.xmlファイル

<?xml version="1.0" encoding="UTF-8" ?>
<features xmlns="http://xmlns.oracle.com/adf/faces/feature">
<feature>
<feature-name>AcmeTagPane</feature-name>
<feature-class>
oracle/adfdemo/acme/js/component/AcmeTagPane.js
</feature-class>
<feature-class>
oracle/adfdemo/acme/js/event/AcmeTagSelectEvent.js
</feature-class>
<feature-class>
oracle/adfdemo/acme/js/component/AcmeTagPanePeer.js
</feature-class>
</feature>
</features>

34.4 サーバー側の開発

サーバー側の開発には、次のものに対するJavaクラスの作成が含まれます。

- イベント・リスナー: このクラスは、イベントをリスニングして、そのイベントを処理するための処理ロジックを起動します。

- イベント: 関連付けられたリスナーでロジックを起動するためのイベントを作成します。

- コンポーネント: このクラスは、コンポーネントの動作を定義するプロパティを保持します。

- リソース・バンドル: このクラスは、コンポーネントのテキスト文字列を保持します。

- レンダラ: このクラスは、クライアントでのコンポーネントの表示方法を決定します。

- リソース・ローダー: このクラスは、スキニングに必要なイメージがコンポーネントに含まれている場合のみ必要です。

これらのクラスを作成したら、コンポーネント・クラスおよびレンダラ・クラスをfaces-config.xmlファイルに追加します。そして、34.2項「ワークスペースと基礎ファイルの設定」で作成を開始した構成ファイルを完成させます。

34.4.1 イベント・リスナーのクラスの作成方法

ADF FacesイベントAPIには、イベントを処理するためのイベント・リスナー・インタフェースが必要です。カスタム・コンポーネントにはイベントに対する依存性があり、イベントにはイベント・リスナー・インタフェースに対する依存性があります。Javaのimport文に、これらの依存性を反映させる必要があります。コンポーネントのcomponentTypeも定義する必要があります。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

ワークスペースを設定し、構成ファイルを作成しておく必要もあります。詳細は、34.2項「ワークスペースと基礎ファイルの設定」を参照してください。

EventListenerクラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Interface」の順に選択して、「OK」をクリックします。

3. 「Javaインタフェース・ファイルの作成」ダイアログで、次のように設定します。

- 名前: リスナーの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagSelectListenerと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.eventと入力します。

4. Javaファイルのエディタで、次を追加します。

- リスナーでjavax.faces.event.FacesListenerインタフェースを拡張します。

- import文を追加して、FacesListenerクラス、およびイベントが依存するすべてのクラスをインポートします。

- 新規イベントを処理するメソッド・シグネチャを追加します。実際のイベントを作成していない場合でも、ここで入力しておけば、後で入力する必要がなくなります。

例34-8に、tagPaneイベント・リスナーのコードを示します。

例34-8 tagPaneイベント・リスナーのJavaコード

package oracle.adfdemo.acme.faces.event;

import javax.faces.event.AbortProcessingException;
import javax.faces.event.FacesListener;

public interface TagSelectListener
extends FacesListener
{
/**
* <p>Process the {@link TagSelectEvent}.</p>
* @param event fired on click of a tag link
* @throws AbortProcessingException error processing {@link TagSelectEvent}
*/
public void processTagSelect(TagSelectEvent event)
throws AbortProcessingException;
}

34.4.2 イベントのクラスの作成方法

34.3.2項「イベントのJavaScriptファイルの作成方法」で作成したJavaScriptイベントに対応するサーバー側のイベントを作成する必要があります。サーバー側のJSFイベントは、リクエスト値の適用ライフサイクル・フェーズ中にコンポーネントによりキューに入れられます。イベントは、レスポンスのレンダリング・フェーズ以外のすべてのフェーズの後にUIViewRootクラスまで伝播されます。キューイングされたイベントは、関連付けられたコンポーネントにブロードキャストされます。

サーバー側のJavaコンポーネントでは、サーバー側のイベントを呼び出す必要があるため、最初にイベント・ソース・ファイルを作成して、コンパイル依存性を解決する必要があります。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

イベント・リスナー・クラスも作成しておく必要があります。詳細は、34.4.1項「イベント・リスナーのクラスの作成方法」を参照してください。

サーバー側イベント・クラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Javaクラス」の順に選択して、「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: イベントの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagSelectEventと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.eventと入力します。

- 拡張: イベント・クラスで拡張するクラスの名前を入力します。この名前は通常、javax.faces.event.FacesEventです。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

例34-9に、イベント・クラスのコードを示します。

例34-9 tagPaneイベントのJavaコード

package oracle.adfdemo.acme.faces.event;
import javax.faces.component.UIComponent;
import javax.faces.event.FacesEvent;
import javax.faces.event.FacesListener;

public class TagSelectEvent
extends FacesEvent
{
/**
* <p>Tag selected on the client.</p>
*/
private String tag = null;
/**
* <p>Overloade constructor passing the <code>source</code>
* {@link oracle.adfdemo.acme.faces.component.TagPane} component and the
* selected <code>tag</code>.
* </p>
* @param source component firing the event
* @param tag selected tag link type
*/
public TagSelectEvent(UIComponent source,
String tag)
{
super(source);
this.tag = tag;
}

/**
* <p>Returns <code>true</code> if the <code>facesListener</code> is a
* {@link TagSelectListener}.</p>
*
* @param facesListener listener to be evaluated
* @return <code>true</code>
* if <code>facesListener</code> instancof {@link TagSelectListener}
*/
public boolean isAppropriateListener(FacesListener facesListener)
{
return (facesListener instanceof TagSelectListener);
}
/**
* <p>Delegates to the <code>processTagSelect</code>
* method of a <code>FacesListener</code>
* implementing the {@link TagSelectListener} interface.
*
* @param facesListener target listener realizing {@link TagSelectListener}
*/
public void processListener(FacesListener facesListener)
{
((TagSelectListener) facesListener).processTagSelect(this);
}
/**
* @return the tag that was selected triggering this event
*/
public String getTag()
{
return tag;
}
}

34.4.3 コンポーネントの作成

JSFコンポーネントは、プロパティの状態ホルダーであると言えます。それらのプロパティでは、レンダリングの動作、およびコンポーネントがユーザー・インタフェース・アクションにどのように応答するかを定義します。コンポーネント・クラスを開発する場合、必要なプロパティのタイプを識別する必要があります。また、MyFaces Trinidadフレームワークから拡張される基本コンポーネントも定義します。たとえば、tagPaneコンポーネントは、MyFaces TrinidadのUIXObjectを拡張します。

大部分のコンポーネントには、実装する必要があるプロパティが複数あります。ベース・クラスから継承されるプロパティもあれば、ADF Facesフレームワークに必須のプロパティもあります。他のプロパティはベスト・プラクティスであるため、必要となります。また、一部のプロパティは、カスタム・コンポーネントの機能に固有のものです。

たとえば、tagPaneコンポーネントには、表34-4に示されているプロパティがあります。

表34-4 tagPaneカスタム・コンポーネントのコンポーネント・プロパティ

元

プロパティ

データ型

説明

継承

id

String.class

コンポーネントの識別子。

rendererType

String.class

コンポーネント・レンダラとして登録されている論理識別子。

rendered

Boolean.class

コンポーネントがレンダリングされているかどうかを判断するTrueまたはFalseのフラグ。

binding

ValueExpression.class

マネージドBeanにコンポーネント・インスタンスを格納するバインディング値式。

ADF Facesフレームワーク

clientComponent

Boolean.class

クライアント側コンポーネントが生成されるかどうかを判断するTrueまたはFalseのフラグ。

clientListeners

ClientListenerSet.class

コンポーネントのクライアント・リスナーを登録するバインディング式。

clientAttributes

Set.class

コンポーネントのclient属性。この属性は、サーバー側のJSFコンポーネントとクライアント側の対応するコンポーネントの両方に追加されます。

ベスト・プラクティス

inlineStyle

String.class

ルート・コンポーネントのclass属性に適用されるCSSスタイル。

styleClass

String.class

コンポーネントのclass属性に追加されるCSSスタイル。

visible

Boolean.class

コンポーネントの可視性が戻されるかどうかを示すTrueまたはFalseのフラグ。visibleプロパティは、renderedプロパティとは異なります。visible属性は、コンポーネントのCSSルートのCSSスタイルに影響します。

partialTriggers

String[].class

部分的なページの更新をトリガーする必要があるコンポーネントのID。

tagPaneに固有

tags

Map.class

重み付けされたタグのマップ。キーによって、タグ名と値が数値で表されます。Map<String.Number>。

orderBy

String.class

タグがレンダリングされる順序。有効な列挙は、alphaおよびweightです。

tagSelectListener

MethodExpression.class

oracle.adfdemo.acme.faces.event.TagSelectEventタイプの単一のパラメータを指定するnewselectListenerメソッド・バインディング式。このバンディングは、タグの1つをクリックしたことでクライアント側のoracle.adfdemo.acme.js.event.AcmeTagSelectEvent.jsイベントがキューイングされると、実行されます。

ADF FacesおよびMyFaces Trinidadコンポーネント・ライブラリは、他のライブラリとは異なる定義がされます。JSFコンポーネントには、attributesと呼ばれるコレクションがあり、MAPインタフェースを介したコンポーネント・プロパティへのアクセスを提供します(JavaのシンプルなBean仕様を使用)。このコレクションは、コンポーネントのプロパティに対応しない値のペアも保持します。この概念は、属性の透過性と呼ばれます。JSFランタイム(MyFaces TrinidadおよびJSF参照実装の両方)では、JavaリフレクションAPIを使用してこの概念が実装されます。

My Faces Trinidadでは、JavaリフレクションAPIを使用しない独自の内部コレクションが定義されます。この違いは、ベース実装よりも効率的であることを意味します。MyFaces Trinidadのソリューションでは、コンポーネント・プロパティに関するより多くのメタデータが収集されます。このメタデータによって状態プロパティが宣言され、ベース・クラスによって、ベース・クラス内にStateHolderインタフェースを完全に実装できます。

My Faces Trinidadでは、org.apache.trinidad.component.UIXComponentクラスによってjavax.faces.component.UIComponentクラスが拡張され、その後に完全なコンポーネント階層が拡張されます。コード・メンテナンスを容易にするために、フレームワークには構成ファイルとテンプレートに基づいてコードを生成する戦略が用意されています。

このコンポーネント戦略は、開発の点におけるトレードオフとなります。プロパティを定義するには、より多くのコーディングが必要となりますが、コンポーネントごとにStateHolderインタフェースの2つのメソッド(saveState、restoreState)をコーディングする必要はありません。

注意:

カスタム・コンポーネントを、ADF Facesの実装パッケージから拡張しないでください。これらの実装は固有のものであり、変更される可能性があります。

34.4.4 コンポーネントのクラスの作成方法

JDeveloperを使用して、コンポーネントのJavaファイルを作成します。プロパティ情報を保持するType Beanを作成し、各プロパティのPropertyKeyを定義します。次に、private属性のアクセッサを生成します。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。作成するクラスについても理解する必要があります。詳細は、34.4.3項「コンポーネントの作成」を参照してください。

イベント・クラスも作成しておく必要があります。詳細は、34.4.2項「イベントのクラスの作成方法」を参照してください。

コンポーネント・クラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」→「Javaクラス」を選択して「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.componentと入力します。

- 拡張: コンポーネント・クラスで拡張するクラスの名前を入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.component.UIXObjectと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

4. ソース・エディタで、コンポーネント・プロパティ情報を含むType Beanを作成します。この静的クラス属性によって、スーパークラス内の同じ名前を持つ属性がシャドウされます。type属性は、コンポーネント・クラスごとに一度定義されます。Typeコンストラクタを介して、スーパークラスType Beanに参照が渡され、プロパティ情報がコピーされます。たとえば、tagPaneクラスには次のコンストラクタが含まれます。

static public final FacesBean.Type TYPE = new FacesBean.Type(UIXObject.TYPE);

5. プロパティごとに、プロパティ状態へのアクセスに使用される静的PropertyKeyを定義します。TYPE参照を使用して、新規属性を登録します。クラス参照を使用して、プロパティ・タイプを指定します。コンポーネントのデータ型は、コンポーネント・プロパティと対応している必要があります。状態情報を指定できるようにするregisterKeyメソッドの別のオーバーロードもあります。デフォルトでは、プロパティはpersistentであるとみなされます。例34-10に、tagPaneコンポーネントのPropertyKeyメソッドを示します。

例34-10 PropertyKeyの定義

/**
* <p>Custom CSS applied to the style attribute of the root markup node.</p>
*/
static public final PropertyKey INLINE_STYLE_KEY =
TYPE.registerKey("inlineStyle", String.class);
/**
* <p>Custom CSS class to the class attribute of the root markup node.</p>
*/
static public final PropertyKey STYLE_CLASS_KEY =
TYPE.registerKey("styleClass", String.class);

6. エディタ内で右クリックし、「アクセッサの生成」を選択します。「アクセッサの生成」ダイアログで「すべて選択」をクリックして、スコープがPublicに設定されていることを確認し、「OK」をクリックします。これで、JDeveloperでprivate属性のgetメソッドおよびsetメソッドを生成できます。
その後、private属性を削除して、getProperty(PropertyKey)およびgetProperty(PropertyKey)へのコールで置き換えます。

例34-11に、private属性を置き換えた後のコードを示します。

例34-11 コンポーネントのプロパティ

public void setInlineStyle(String newinlineStyle)
{
// inlineStyle = newinlineStyle;
setProperty(INLINE_STYLE_KEY, newinlineStyle);
}
/**
* <p>CSS value applied to the root component's style attribute.</p>
*
* @return newinlineStyle CSS custom style text
*/
public String getInlineStyle()
{
// return inlineStyle;
return (String) getProperty(INLINE_STYLE_KEY);
}

7. コンポーネントの特定の機能を実行するには、メソッドをオーバーライドする必要がある場合があります。たとえば、コンポーネントが部分ページ・レンダリング(PPR)に関与できるようにするには、例34-12に示すように、getBeanTypeメソッドをオーバーライドする必要があります。

例34-12 オーバーライド・メソッド

/**
* <p>Exposes the <code>FacesBean.Type</code> for this class through a protected
* method.  This method is called but the <code>UIComponentBase</code> superclass
* to setup the components <code>ValueMap</code> which is the container for the
* <code>attributes</code> collection.</p>
*
* @return <code>TagPane.TYPE</code> static property
*/
@Override
protected FacesBean.Type getBeanType()
{
return TYPE;
}

コンポーネントで拡張するクラスや、オーバーライドに必要になる可能性のあるメソッドの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

tagPaneコンポーネントの場合、コンポーネントはクライアント・コンポーネントから起動されるイベントで動作する必要があります。ソース・コンポーネントへの参照は、パラメータとしてイベントのコンストラクタに渡されます。

tagPaneコンポーネントの場合、仮パラメータを使用して渡されたイベントがTagSelectEventであるかどうかが、broadcastメソッドによって確認されます。そうである場合、broadcastメソッドによって、tagSelectListener属性に保持されているメソッド式が呼び出されます。

大部分のイベントには、イベントを起動するライフサイクル・フェーズを指定するimmediateブール・プロパティがあります。immediate属性がtrueの場合、イベントは値の適用フェーズで処理され、falseの場合は、アプリケーションの起動フェーズで処理されます。詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

例34-13に、tagPaneコンポーネントのオーバーライドされるbroadcastメソッドを示します。

例34-13 tagPaneコンポーネントのbroadcastメソッド

/**
* @param facesEvent faces event
* @throws AbortProcessingException exception during processing
*/
@Override
public void broadcast(FacesEvent facesEvent)
throws AbortProcessingException
{
// notify the bound TagSelectListener
if (facesEvent instanceof TagSelectEvent)
{
TagSelectEvent event = (TagSelectEvent) facesEvent;
// utility method found in UIXComponentBase for invoking method event
// expressions
broadcastToMethodExpression(event, getTagSelectListener());
}
super.broadcast(facesEvent);
}

Javaクラスの例は、第F.4.3項「コンポーネント・クラスのコード例」を参照してください。

34.4.5 faces-config.xmlファイルへのコンポーネントの追加方法

コンポーネント・クラスを作成したら、コンポーネントを/META-INF/faces-config.xmlファイルに追加して登録します。JARプロジェクトにパッケージされているFaces構成ファイルにコンポーネントを定義することで、Webアプリケーションの起動時に、JSFランタイムによってコンポーネントが自動的に認識されます。

コンポーネントを登録するには、アプリケーション・ファクトリによりコンポーネントのインスタンスのインスタンス化に使用される論理名であるコンポーネント・タイプを入力します。たとえば、tagPaneコンポーネントのタイプはoracle.adfdemo.acme.TagPaneです。コンポーネントの完全修飾クラス・パス(oracle.adfdemo.acme.faces.component.TagPaneなど)も追加する必要があります。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。作成するクラスについても理解する必要があります。詳細は、34.4.3項「コンポーネントの作成」を参照してください。

コンポーネント・クラスも作成しておく必要があります。詳細は、34.4.4項「コンポーネントのクラスの作成方法」を参照してください。

カスタム・コンポーネントを登録する手順:

1. 「アプリケーション」ウィンドウで、faces-config.xmlファイルをダブルクリックします。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 概要エディタで「コンポーネント」ナビゲーション・タブをクリックして、「追加」アイコンをクリックします。

4. コンポーネントのタイプとクラスを入力します。

5. オプションで、任意の属性、プロパティまたはファセットを追加します。

例34-14に、faces-config.xmlファイルに定義されているtagPaneコンポーネントを示します。

例34-14 faces-config.xmlファイルに追加されたtagPaneコンポーネント

<?xml version="1.0" encoding="UTF-8" ?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">
<application>
</application>

<component>
<component-type>oracle.adfdemo.acme.TagPane</component-type>
<component-class>oracle.adfdemo.acme.faces.component.TagPane
</component-class>
</component>

34.4.6 リソース・バンドルのクラスの作成方法

リソース・バンドルは、コンポーネントの情報(ラベルやメッセージのテキストなど)、およびアプリケーションでロケールの切替えが許可されている場合に使用される翻訳されたテキストを格納するために使用されます。スキンでも、コンポーネントのテキストを保持するためにリソース・バンドルが使用されます。カスタム・コンポーネントでは少なくとも簡単なスキンを使用する必要があるため、少なくともそのスキンのリソース・バンドルを作成する必要があります。カスタム・コンポーネントの場合は、リソース・バンドルのJavaファイルを作成します。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ヒント:

リソースのプロパティ・ファイルを使用することもできます。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。作成するクラスについても理解する必要があります。詳細は、34.4.3項「コンポーネントの作成」を参照してください。

コンポーネントも登録しておく必要があります。詳細は、34.4.5項「faces-config.xmlファイルへのコンポーネントの追加方法」を参照してください。

リソース・バンドル・クラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Javaクラス」の順に選択して、「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: リソース・バンドルの名前を入力します。名前には、使用するスキンを反映させる必要があります。たとえば、サンプル・コンポーネントの場合、AcmeSimpleDesktopBundleと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、サンプル・コンポーネントの場合、oracle.adfdemo.acme.faces.resourceと入力します。

- 拡張: リソース・バンドルの場合、java.util.ListResourceBundleと入力する必要があります。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

4. 必要に応じてキーを追加し、テキストを定義します。スキンのリソース・バンドル作成の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。
例34-15に、tagPaneコンポーネントのリソース・バンドル・コードを示します。

例34-15 tagPaneのリソース・バンドルのJavaコード

package oracle.adfdemo.acme.faces.resource;
import java.util.ListResourceBundle;
/**
* <p>Holds properties used by the components bundled in the jar project.
* This bundle is part of the trinidad component skin that is configured
* in the "/META-INF/trinidad-skins.xml" file. Component Renderers
* will use the <code>RenderingContext</code> to lookup a key by calling
* the <code>getTranslatedString(key)</code> method.</p>
*/
public class AcmeSimpleDesktopBundle
extends ListResourceBundle
{
/**
* <p>Returns a two dimensional object array that represents a resource bundle
. * The first
* element of each pair is the key and the second the value.</p>
*
* @return an array of value pairs
*/
protected Object[][] getContents()
{
return new Object[][]
{
{"AcmeTagPane_tag_title","Tag Weight: {0}"}
};
}
}

5. 簡単なデスクトップ・スキンおよび他の必要なスキンのリソース・バンドルを登録するには、/META-INF/trinidad-skins.xmlファイルをダブルクリックして開き、次のように設定します。

1. 構造ウィンドウで、skin-additionを選択します。

2. 「プロパティ」ウィンドウで、スキンIDを入力します。簡単なスキンIDの場合、simple.desktopと入力します。

3. 構造ウィンドウで「skin-addition」を右クリックし、「skin-additionの中に挿入」→「bundle-name」を選択します。

4. 「プロパティ」ウィンドウで、作成したリソース・バンドルの完全修飾名を入力します。

注意:

JDeveloperでは、translation-source要素とbundle-name要素はコメントとして追加されます。別のbundle-name要素を宣言的に作成するかわりに、生成済の要素にbundle-name値を手動で入力してから、コメント・タグを削除することもできます。

例34-16に、tagPaneリソース・バンドルを簡単なスキンに登録するためのコードを示します(この後の手順でstyle-sheet-name要素値を追加します)。

例34-16 リソース・バンドルのスキンへの登録

<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin-addition>
<skin-id>simple.desktop</skin-id>
<style-sheet-name></style-sheet-name>
<bundle-name>
oracle.adfdemo.acme.faces.resource.AcmeSimpleDesktopBundle
</bundle-name>
</skin-addition>
</skins>

34.4.7 レンダラのクラスの作成方法

ADF Facesコンポーネントでは、コンポーネントの機能はコンポーネント・クラスに委任され、使用アプリケーションがJSPを使用する場合、コンポーネントの表示はレンダラに委任されます。デフォルトでは、ADF Facesのすべてのタグが、関連付けられたコンポーネント・クラスとHTMLレンダラを結合し、HTMLレンダー・キットの一部になっています。ADF Facesには、デスクトップおよびPDAデバイスの両方に表示できるように、HTMLレンダー・キットが含まれています。

レンダラは、ファミリとレンダラ・タイプによってレンダー・キットで修飾されます。ファミリはコンポーネントの一般カテゴリであり、スーパークラスに定義されているファミリと同じにする必要があります。コンポーネントは継承によってメソッドを取得するため、コンポーネント内のgetFamily()メソッドをオーバーライドする必要はありません。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。作成するクラスについても理解する必要があります。詳細は、34.4.3項「コンポーネントの作成」を参照してください。

リソース・バンドルも作成しておく必要があります。詳細は、34.4.6項「リソース・バンドルのクラスの作成方法」を参照してください。

レンダラ・クラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Javaクラス」の順に選択して、「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: レンダラの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneRendererと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.renderと入力します。

- 拡張: oracle.adf.view.rich.render.RichRendererと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

4. 必要な機能を追加します。RichRenderクラスで使用可能なメソッドおよびフィールドの詳細は、Oracle ADF Faces Java APIリファレンスを参照してください。

注意:

スキニング機能には、コンポーネントのレンダリング中に、指定されたCSSセレクタのCSSスタイル・プロパティの取得に使用できるAPIが用意されています。このAPIは、設定されているスタイリングに基づいて、条件付きのレンダリングを行う必要がある場合に便利です。詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces Trinidad JavadocのRenderingContext#getStylesおよびStyles#getSelectorStyleMapを参照してください。

注意:

DOM構造で拡大がサポートされている場合、コンポーネントがコンポーネント・ツリーで唯一のビジュアル・ルート・コンポーネントであり、ドキュメント・コンポーネントが拡大できるように構成されていれば、そのコンポーネントをブラウザのビューポートいっぱいに自動的に拡大できます(詳細は、9.2.5項「documentタグの構成方法」を参照してください)。

コンポーネントを自動的に拡大させるには、RichRenderer.getPrependedInlineStyle()をオーバーライドし、getVisualRootStretchingStyles(context, rc, component, client, bean)に戻します。

このメソッドでは、コンポーネントがビジュアル・ルート・コンポーネントでない場合にはNULLを返し、ビジュアル・ルート・コンポーネントである場合は、DIVをブラウザのビューポートいっぱいに拡大するスタイルのStringを返します。

レンダラ・クラスの完全な例は、F.4.4項「レンダラ・クラス」を参照してください。

34.4.8 faces-config.xmlファイルへのレンダラの追加方法

レンダラを作成したら、faces-config.xml構成ファイルを使用して登録します。カスタム・コンポーネントを他のADF Facesコンポーネントと組み合せて機能させる場合、そのADF Facesコンポーネントが使用しているのと同じレンダー・キットIDを使用する必要があります。

ヒント:

JSFでレンダー・キットを定義できる最も高いレベルはビュー・ルートです。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

レンダー・キットおよびレンダラも作成しておく必要があります。詳細は、34.4.7項「レンダラのクラスの作成方法」を参照してください。

レンダー・キットおよびレンダラを登録する手順:

1. 「アプリケーション」ウィンドウで、faces-config.xmlファイルをダブルクリックします。

2. エディタ・ウィンドウで「概要」タブを選択して、「レンダー・キット」ナビゲーション・タブを選択します。

3. 「レンダー・キット」の「追加」アイコンをクリックして、レンダー・キットIDにoracle.adf.richと入力します。

4. 「レンダラ」の「追加」アイコンをクリックしてレンダラを登録し、次のように設定します。

- ファミリ: コンポーネントで拡張するクラスを入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.Objectと入力します。

- タイプ: コンポーネントのタイプを入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.TagPaneと入力します。これは、レンダラ・タイプと一致している必要があります。

- クラス: 34.4.7項「レンダラのクラスの作成方法」で作成したレンダラの完全修飾クラス・パスを入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.render.TagPaneRendererを入力します。

例34-17に、tagPaneコンポーネントのレンダー・キットおよびレンダラの登録を示します。

例34-17 faces-config.xmlファイルに追加されたtagPaneのレンダラ

<render-kit>
<render-kit-id>oracle.adf.rich</render-kit-id>
<renderer>
<component-family>org.apache.myfaces.trinidad.Object</component-family>
<renderer-type>oracle.adfdemo.acme.TagPane</renderer-type>
<renderer-class>oracle.adfdemo.acme.faces.render.TagPaneRenderer
</renderer-class>
</renderer>
</render-kit>

34.4.9 JSPタグ・プロパティの作成方法

JSPページでコンポーネントを使用するには、カスタム・コンポーネントをインスタンス化するカスタム・タグを作成します。レンダリングのタスクを実際に実行するのはコンポーネントのレンダラであるため、JSPタグはレンダリングには関係ありません。JSF 1.1では、JSPタグを作成し、コンポーネント・ツリーに追加すると、そのタグによってコンポーネント上でレンダリングが起動されます。非JSF/JSPタグで同じレスポンス・ライターに書込みが行われていたために、これが問題の原因となりました。インターリーブのタイミングが、独自の子コンポーネントをレンダリングしたコンポーネントに対してうまく合いませんでした。

注意:

Faceletを使用するアプリケーションでは、コンポーネントのインスタンス化にハンドラを使用します。詳細は、34.2.8項「Faceletタグ・ライブラリ構成ファイルの追加方法」を参照してください。

JSF 1.2、Java EE 5 (Servlet 2.5、JSP 2.1)のターゲットでは、JSPの問題の大部分は修正されています。JSF/JSPコンポーネントは、コンポーネントの作成のみを行うコンポーネント・ファクトリとして機能します。これは、レンダリング・レスポンス・フェーズが2つの手順に分割されていることを意味します。コンポーネント・ツリーの作成時にコンポーネントがレンダリングされるかわりに、まずコンポーネント・ツリーが作成されてからそのツリーがレンダリングされます。この機能は、ビュー全体がJSFコンポーネントによって表されるようにすることで可能になっています。JSF/JSP以外では、暗黙的にJSF Verbatimコンポーネントとなるマークアップが生成されます。

JSF 1.2におけるこのような仕組みの変更の結果として、カスタムJSPタグによってjavax.faces.webapp.UIComponentELTagクラスが拡張されます。JSPタグのencodeBegin、encodeChildrenおよびencodeEndメソッドは非推奨となっています。これらのメソッドは、以前はコンポーネントへの対応するコールを行っていました。JSF 1.2ではビュー・ルートでレンダリングが行われるため、すべての機能はdoStartTagメソッドおよびdoEndTagメソッドで実行できます。MyFaces Trinidadには、使用できるこのベース・クラス独自のバージョンがあります。org.apache.myfaces.Trinidad.webapp.UIComponentELTagがコンポーネントのプロパティ・バッグにフックされ、JSPのコーディングが単純化されます。

タグ・クラスには、コンポーネントのプロパティの作成が含まれます。タグ・プロパティは慎重に選択する必要があります。一部のプロパティはタグの実装では無視できても、TLD属性として必要な場合があります。

次の3つの属性は、スーパークラスによって実装され、Java継承を介して多くのコンポーネントで共有されます。

- id

- binding

- rendered

id属性はスーパークラスjavax.faces.webapp.UIComponentTagBaseによって実装されるため、id属性は実装しないでください。スーパークラスjavax.faces.webapp.UIComponentELTagによって、bindingとrenderedという2つの属性が実装されます。そのため、この2つの属性をタグ・クラスに追加する必要はありません。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

この項のこれまでの手順をこの時点までに完了しておくことも必要です。

JSPタグを追加する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Javaクラス」の順に選択して、「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: タグの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneTagと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.taglibと入力します。

- クラス: org.apache.myfaces.trinidad.webapp.UIXComponentELTagと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

4. ソース・エディタで、すべての属性をファイルに追加します。
例34-18に、TagPaneTagクラスの属性のコードを示します。

例34-18 TagPaneTagクラスの属性

public class TagPaneTag
extends UIXComponentELTag
{
private ValueExpression _partialTriggers = null;
private ValueExpression _visible = null;
private ValueExpression _inlineStyle = null;
private ValueExpression _styleClass = null;
private ValueExpression _tags = null;
private ValueExpression _orderBy = null;
private MethodExpression _tagSelectListener = null;

5. 属性のアクセッサ・メソッドを宣言的に生成するには、ソース・エディタでファイルを右クリックして、「アクセッサの生成」を選択します。

6. 「アクセッサの生成」ダイアログで「すべて選択」をクリックして、スコープをpublicに設定し、「OK」をクリックします。

7. レンダー・タイプとコンポーネント・タイプをクラスに追加します。コンポーネント・タイプは、アプリケーションのファクトリ・メソッド、createComponent(componentType)を使用してコンポーネントをインスタンス化するためにスーパークラスによって使用されます。
例34-19に、コンポーネント・タイプとレンダー・タイプがいずれもoracle.adfdemo.acme.TagPaneであるTagPaneTagクラスのコードを示します。

例34-19 TagPaneTagクラスのコンポーネント・タイプとレンダー・タイプ

public String getComponentType()
{
return COMPONENT_TYPE;
}
public String getRendererType()
{
return RENDERER_TYPE;
}

/**
* <p>This component's type, <code>oracle.adfdemo.acme.TagPane</code></p>
*/
static public final String COMPONENT_TYPE =
"oracle.adfdemo.acme.TagPane";
/**
* <p>Logical name given to the registered renderer for this component.</p>
*/
static public final String RENDERER_TYPE = "oracle.adfdemo.acme.TagPane";

8. 単一の仮パラメータのタイプFacesBeanを持つスーパークラスからsetPropertiesメソッドをオーバーライドします。これは、ベースUIComponentELTagのMyFaces Trinidadバージョンですが、コンポーネント参照のかわりにコンポーネントの状態ホルダーが渡されます。setPropertiesメソッドの役割は、JSPタグ属性値をコンポーネントにプッシュすることです。
例34-20に、tagPaneTagクラスのオーバーライド・メソッドを示します。

例34-20 TagPaneTagクラスのsetPropertiesメソッドのオーバーライド

@Override
protected void setProperties(FacesBean facesBean) {
super.setProperties(facesBean);

setStringArrayProperty(facesBean, TagPane.PARTIAL_TRIGGERS_KEY,
_partialTriggers);
setProperty(facesBean, TagPane.VISIBLE_KEY, _visible);
setProperty(facesBean, TagPane.INLINE_STYLE_KEY, _inlineStyle);
setProperty(facesBean, TagPane.STYLE_CLASS_KEY, _styleClass);
setProperty(facesBean, TagPane.TAGS_KEY, _tags);
setProperty(facesBean, TagPane.ORDER_BY_KEY, _orderBy);
facesBean.setProperty(TagPane.TAG_SELECT_LISTENER_KEY,
_tagSelectListener);

}

34.4.10 タグ・ライブラリ・ディスクリプタの構成方法

タグ・ライブラリ・ディスクリプタ(TLD)は、Javaクラスの詳細をJSPコンパイル・エンジンとIDEツールに提供します(Faceletを使用するアプリケーションではTLDは使用されません)。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

この項のこれまでの手順をこの時点までに完了し、タグ・ライブラリをURIに明確に関連付け、バージョンを割当て、それに名前を指定しておくことも必要です。この手順は、34.2.6項「JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法」でタグ・ライブラリ・スタブ・ファイルを作成したときに実行されている必要があります。

TLDを構成する手順:

1. 「ファイル」メニューから、「開く」 を選択します。アプリケーションの/src/META-INFディレクトリに移動し、作成したTLDファイルをダブルクリックして開きます。

2. 「コンポーネント」ウィンドウの「XML」ページで、tag要素をドラッグ・アンド・ドロップします。

3. 「タグの挿入」ダイアログで、次のように設定します。

- name: コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、tagPaneと入力します。

- body-content: JSPと入力します。

- tag-class: 省略ボタンをクリックして、コンポーネントのタグ・クラス・ファイルに移動します。

4. 各属性を定義します。各属性に対して次のように設定します。

1. 構造ウィンドウでtag要素を右クリックし、「tagの中に挿入」→「属性」を選択します。

2. 「属性の挿入」ダイアログで、名前の値を入力します。この名前はタグ・クラスで指定した名前と同一にする必要があります。

3. 構造ウィンドウで属性を選択し、「プロパティ」ウィンドウで属性の値を設定します。
各属性に定義する要素は3タイプあります。<id>要素は単純な文字列です。追加の属性は、deferred-value属性またはdeferred-method属性となります。これらにより、式を遅れて(deferred)評価できます。これで、JSPとJSFで同じELエンジンを共有するようになったため、コンパイル済のELをコンポーネントに直接渡すことができます。

tagPaneコンポーネントのTLDの例は、F.4.2項「タグ・ライブラリ・ディスクリプタ・ファイルのコード例」を参照してください。

34.4.11 リソース・ローダーの作成方法

リソース・ローダーは、カスタム・コンポーネントにコンポーネントのスキニングに必要なイメージ・ファイルがある場合にのみ必要です。イメージ・ファイルはJARプロジェクトにパッケージされているため、コンポーネント・ライブラリの使用者は、自分のWebプロジェクトのクラス・パスにJARファイルを含め、Webデプロイ・ディスクリプタ・ファイル(web.xml)にいくつかのエントリを追加することが必要になります。ADF Facesフレームワークでは、イメージの配信にリソース・サーブレットが使用されます。このサーブレットをweb.xmlファイルに登録してから、リソース・ローダー・クラスを作成する必要があります。コンポーネント・ライブラリには、リソース・サーブレットにより自動ローディングされるリソース・ローダーが必要です。サーブレットのためにURLパターン・フォルダ・マッピングを作成すると、これがカスタム・コンポーネント・ライブラリ内でのリソースの検索および識別に使用されます。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

この項のこれまでの手順をこの時点までに完了しておくことも必要です。

リソース・ローダー・クラスを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトを右クリックし、「新規」→「ギャラリから」を選択します。

2. 「新規ギャラリ」で、「一般」を展開し、「Java」、「Javaクラス」の順に選択して、「OK」をクリックします。

3. 「Javaクラス・ファイルの作成」ダイアログで、次のように設定します。

- 名前: リソース・ローダーの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeResourceLoaderと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.resourcesと入力します。

- 拡張: タグで拡張するクラスの名前を入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.resource.RegexResourceLoaderと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

4. ソース・エディタで、より具体的なリソース・ローダーにマップされる正規表現を登録します。たとえば、イメージ・ディレクトリの下にあるイメージ・リソースにマップする式を作成できます。
例34-21に、カスタム・コンポーネントJARファイルの/META-INFディレクトリと相対的な場所にある/acme/images/ディレクトリにマップするtagPaneコンポーネントの式を示します。登録すると、カスタム・コンポーネントのイメージは/META-INF/acme/imagesの下に配置されます。

例34-21 tagPaneコンポーネントのリソース・ローダー

public class AcmeResourceLoader
extends RegexResourceLoader
{
public AcmeResourceLoader()
{
// any resource in "/acme/" with the following suffixes will be
// loaded from the base folder of "META-INF".
// The servlet pattern match "/acme/*" should exist under "META-INF".
// For example URL : context-root/acme/images/type1.gif
//      map to: META-INF/acme/images/type1.gif
register("(/.*\\.(jpg|gif|png|jpeg))",
new ClassLoaderResourceLoader("META-INF"));

5. /META-INF/servlet/resources/name.resourcesファイルを開いてライブラリ・リソース・ローダーを登録し、URIパターンにバインドされているリソース・ローダー・クラスの完全修飾名を追加します。
MyFaces Trinidad ResourceServletでは、サーブレット・コンテキストを使用して、Webアプリケーションのクラス・パス内のすべてのJARファイルをスキャンします。サーブレットでは、Webデプロイメント・ディスクリプタで独自のURIマッピングを調べ、このリソース・ファイルの場所を明確に表します。このファイルには、URIパターンにバインドされたJavaクラスの完全修飾名を含める必要があります。起動時に、ResourceServletでは、FacesServletによりfaces-config.xmlファイルが検索され、使用されるのと同様に、このファイルを検索し使用します。

tagPaneコンポーネントの場合、acme.resourcesファイルには、コンポジット・リソース・ローダーのための次のエントリが含まれます。

oracle.adfdemo.acme.faces.resource.AcmeResourceLoader

34.4.12 MyFaces Trinidad Cascading Style Sheetの作成方法

スキンはCSS 3.0構文に基づくスタイルシートで、アプリケーション全体用に1箇所で指定されます。各ページのスタイルシートを挿入するかわりに、アプリケーション全体に対して1つ以上のスキンを使用します。各コンポーネントで自動的に、スキンで記述されているスタイルが使用されます。設計時のコードの変更は必要ありません。

ADF Facesコンポーネントはすべてスキンを使用します。デフォルトのスキンはSkyrosスキンです。カスタム・コンポーネントは、他のADF Facesコンポーネントとともに使用されるため、既存のADF Facesスキンにスタイル・セレクタを追加します。Skyrosスキンは、簡単なスキンからスタイルを継承するので、セレクタを簡単なスキンに追加するだけで、すべてのスキンでそのセレクタを使用できるようになります。ただし、スキンごとにセレクタのスタイルを変えたい場合があります。そのようなスタイルは、作成したCSSファイルに設定します。このファイルは、コンポーネントが使用されるアプリケーションの他のCSSスタイルとマージされます。

スキンで使用されるテキストは、リソース・バンドル内で定義されます。カスタム・リソース・バンドルを作成してテキストを作成し、表示するテキストを宣言します。カスタム・リソース・バンドルを作成した後、スキンにそれを登録します。リソース・バンドルとCSSを組み合せることで、コンポーネントで複数のロケールをサポートするためのメソッドが提供されます。

作成した/META-INF/trinidad-skins.xmlファイルは、CSSファイルおよびリソース・バンドルをADF Facesスキンに登録するために使用されます。

始める前に:

カスタムADF Facesコンポーネントのサーバー側の開発について理解しておくと役立ちます。詳細は、34.4項「サーバー側の開発」を参照してください。

この項のこれまでの手順をこの時点までに完了しておくことも必要です。

コンポーネントのスタイルを作成する手順:

1. 34.2.4項「カスケーディング・スタイル・シートの追加方法」で作成したCSSファイルを開きます。

2. コンポーネントのルート・スタイル・セレクタを定義します。このスタイルは、コンポーネントを確立する<DIV>要素と関連付けられます。

3. 必要に応じてその他のスタイル・セレクタを追加します。例34-22に、tagPaneコンポーネントのCSSファイルを示します。

例34-22 tagPaneコンポーネントのCSSファイル

acme|tagPane          -  root element
acme|tagPane::content -  container for the links
acme|tagPane::tag - tag hyperlink

スキンで使用されるCSSコンポーネントの作成の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

4. コンポーネントに必要なリソース・バンドルをすべて作成します。

5. CSSをADF Facesスキンに登録するには、/META-INF/trinidad-skins.xmlファイルを開きます。

6. 構造ウィンドウで「skin-addition」要素を選択し、「プロパティ」ウィンドウで次のように設定します。

- skin-id: カスタム・コンポーネント・セレクタを追加するADF Facesスキンを入力します。セレクタとADF Facesコンポーネントとの互換性を得るには、少なくともsimple.desktopスキンにセレクタを登録する必要があります。

注意:

コンポーネントがOracle WebCenter Portalアプリケーションで使用される可能性がある場合は、simple.portletスキンにもセレクタを登録する必要があります。スキンはPDA (simple.pdaなど)でも使用可能です。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- style-sheet-name: ドロップダウン・リストを使用して「編集」を選択し、作成したCSSファイルに移動します。

7. リソース・バンドルを作成している場合は、バンドルの完全修飾パスを<bundle-name>要素の値として追加します。
例34-23に、tagPaneコンポーネントのコードを示します。

例34-23 tagPaneのtrinidad-skins.xmlコード

<?xml version="1.0" encoding="UTF-8" ?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin-addition>
<skin-id>simple.desktop</skin-id>
<style-sheet-name>acme/styles/acme-simple-desktop.css</style-sheet-name>
<bundle-name>oracle.adfdemo.acme.faces.resource.AcmeSimpleDesktopBundle
</bundle-name>
</skin-addition>
</skins>

8. カスタム・コンポーネントで使用するイメージのイメージ・フォルダを追加します。このフォルダは、META-INFディレクトリの下にある必要があります。カスタム・コンポーネントで使用するすべてのイメージをこのフォルダに配置します。
tagPaneの場合、イメージ・フォルダは/META-INF/acme/imagesです。

34.5 コンポーネント・ライブラリのデプロイ

カスタム・コンポーネント・ライブラリを作成したら、Webアプリケーションで使用できるデプロイ可能なアーティファクトを作成する必要があります。

34.5.1 コンポーネント・ライブラリのデプロイ方法

Javaアーカイブ(JAR)ファイルを作成できるようにするには、作成した多くのリソースを追加して、プロジェクトのデプロイメント・プロファイルを更新する必要があります。

始める前に:

34.3項「クライアント側の開発」で説明されているように、コンポーネントのクライアント側のファイルを作成しておく必要があり、34.4項「サーバー側の開発」で説明されているように、サーバー側のファイルも作成しておく必要があります。

デプロイメントのJARファイルを作成する手順:

1. 「アプリケーション」ウィンドウで、プロジェクトをダブルクリックします。

2. 「プロジェクト・プロパティ」ダイアログの左ペインで、「コンパイラ」を選択します。

3. 右側では、デプロイされるすべてのファイル・タイプが「ファイル・タイプの出力ディレクトリへのコピー」テキスト・フィールドにリストされていることを確認します。

注意:

ファイル・タイプの中には、.cssや.jsなど、デフォルトでは含まれていないものもあります。これらは追加が必要になります。

4. 左ペインで、「デプロイ」を選択します。

5. 右側の「Deployment Profiles」で、「ADFライブラリのJARファイル」を選択して、「編集」をクリックします。

6. 左ペインで、「JARオプション」を選択します。

7. ADFライブラリのJARファイルを格納するためのデフォルトのディレクトリ・パスを確認するか、新規パスを入力します。「Manifestファイルを含める」が選択されていることを確認して、「OK」をクリックします。

8. デプロイするには、プロジェクトを右クリックし、ポップアップ・メニューから「デプロイ」→「Project_name」を選択します。デフォルトでは、プロジェクト・ディレクトリ内のデプロイメント・ディレクトリにJARファイルがデプロイされます。

34.6 アプリケーションへのカスタム・コンポーネントの追加

コンポーネントを作成し、ADFライブラリを作成すると、そのコンポーネントを別のアプリケーションにインポートして使用できるようになります。ただし、開発中のアプリケーションでコンポーネントを使用する前には、テスト・アプリケーションで使用してコンポーネントが予想どおりに機能することを確認する必要があります。テストするには、カスタム・ライブラリをテスト・アプリケーションにインポートします。手順の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のADFライブラリ・コンポーネントのプロジェクトへの追加に関する項を参照してください。

ライブラリを追加したら、Webデプロイメント・ディスクリプタを構成して、リソース・サーブレット・マッピングを追加します。コンポーネントを使用してテスト・アプリケーションを実行すると、コンポーネントのデバッグが必要であることがわかる場合があります。そのため、プロジェクトに対してロギングとアサーションを有効にしておくと役立ちます。

ヒント:

ライブラリをアプリケーションにインポートすると、JDeveloperの「コンポーネント」ウィンドウにカスタム・コンポーネントを表示できます。

34.6.1 Webデプロイメント・ディスクリプタの構成方法

コンポーネント・リソース・ローダーは、サーブレット・リソース・マッピングを前提とするように構成されています(たとえば、tagPaneコンポーネントの場合、マッピングはacmeです)。そのため、想定されるリソース・サーブレット・マッピングを使用アプリケーションのweb.xmlファイルに追加する必要があります。

デフォルトでは、MyFaces Trinidadのスキニングでは、CSS 3をCSS 2に正規化するときに、CSSクラスが圧縮されます。コンポーネントのデバッグ時にはこの圧縮を無効にします。本番のデプロイメントでは、この設定を無効に切り替えます。

始める前に:

アプリケーションへのカスタム・コンポーネントの追加について理解しておくと役立ちます。詳細は、34.6項「アプリケーションへのカスタム・コンポーネントの追加」を参照してください。

web.xmlファイルを構成する手順:

1. 「アプリケーション」ウィンドウで、web.xmlファイルをダブルクリックします。

2. 概要エディタで、「サーブレット」ナビゲーション・タブをクリックします。

3. 「追加」アイコンをクリックして表に新しい行を追加します。次の内容を入力します。

- 名前: resourcesと入力します。

- サーブレット・クラス: org.apache.myfaces.trinidad.webapp.ResourceServletと入力します。

4. 表の下で、「サーブレット・マッピング」ナビゲーション・タブをクリックします。

5. 「追加」アイコンをクリックして表に新しいサーブレット・マッピングのための新しい行を追加します。URIの接頭辞を入力します。この接頭辞で始まるリソースは、サーブレットによって処理されます。たとえば、tagPaneコンポーネントの場合、接頭辞/acme/*と入力します。

6. スタイルシートの圧縮を無効にする手順:

1. 「アプリケーション」を選択します。

2. 「コンテキスト初期化パラメータ」の「追加」アイコンをクリックします。

3. 「名前」にorg.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSIONと入力し、「値」にtrueと入力します。

34.6.2 JavaScriptロギングとアサーションを有効にする方法

JavaScriptデバッグは難しいタスクです。この動的言語の型確認なしでのデバッグを助けるために、ADF Faces JavaScriptライブラリには、Javaロギングに似たロギング・メカニズムが用意されています。クライアント・スクリプトをより型保証されたスクリプトにするアサーション・ストラテジもあります。これらの機能はいずれも、web.xmlファイルの構成パラメータを使用して有効にします。ロギング・ルーチンとアサーション・ルーチンはブラウザ固有です。クライアントJavaScriptライブラリでは、Gecko、Internet Explorer、OperaおよびSafariバージョンのブラウザ・エージェントがサポートされます。詳細は、A.2.3.4項「リソース・デバッグ・モード」を参照してください。

始める前に:

アプリケーションへのカスタム・コンポーネントの追加について理解しておくと役立ちます。詳細は、34.6項「アプリケーションへのカスタム・コンポーネントの追加」を参照してください。

デプロイメント・ディスクリプタも構成しておく必要があります。詳細は、34.6.1項「Webデプロイメント・ディスクリプタの構成方法」を参照してください。

ロギングとアサーションを有効にする手順:

1. 「アプリケーション」ウィンドウで、web.xmlファイルをダブルクリックします。

2. 概要エディタで、「アプリケーション」ナビゲーション・タブをクリックします。

3. 「アプリケーション」ページで、「コンテキスト初期化パラメータ」の「追加」アイコンをクリックします。

4. 「コンテキスト初期化パラメータ」表に次のパラメータを追加してデバッグを有効にします。

- 名前: org.apache.myfaces.trinidad.resource.DEBUG

- 値: true

この設定により、MyFaces Trinidadで、JavaScriptのようなリソースに対してキャッシュ・ヘッダーが設定されなくなります。ブラウザでのリソースのキャッシングも行われなくなります。

5. 次のパラメータを追加して、クライアント側JavaScriptのデバッグ・レベルを設定します。

- 名前: oracle.adf.view.rich.LOGGER_LEVEL

- 値: ALL

有効な値は、OFF、SEVERE、WARNING、INFO、CONFIG、FINE、FINER、FINESTぉよびALLです。デフォルトは、OFFです。

6. 次のパラメータを追加して、クライアント側のスクリプト・アサーションを有効にします。

- 名前: oracle.adf.view.rich.ASSERT_ENABLED

- 値: true

この設定はロギングと連携して機能します。このスイッチを有効に切り替えると、デバッグ情報がブラウザで使用可能になります。アサーションとロギングの表示は、ブラウザによって異なります。Internet Explorerの場合、子ブラウザ・ウィンドウがアクティブ・ウィンドウと並んで表示されます。FireFoxにFire Bugプラグインをインストールしている場合、デバッグ情報はFire Bugコンソールから使用できます。

34.6.3 JSFページへのカスタム・コンポーネントの追加方法

始める前に:

アプリケーションへのカスタム・コンポーネントの追加について理解しておくと役立ちます。詳細は、34.6項「アプリケーションへのカスタム・コンポーネントの追加」を参照してください。

デプロイメント・ディスクリプタも構成しておく必要があります。詳細は、34.6.1項「Webデプロイメント・ディスクリプタの構成方法」を参照してください。

カスタム・コンポーネントをJSFページに追加する手順:

1. アプリケーション・ナビゲータで、JSPページをダブルクリックします。

2. ソース・エディタで、ルート・タグにTLDネームスペースを追加します。
たとえば、tagPaneコンポーネントの場合、タグ・ライブラリのURIはhttp://adf-richclient-demo-acmeなので、次の内容を追加します。

xmlns:acme="http://oracle.adfdemo.acme"

3. ページにカスタム・コンポーネントを追加するには、「コンポーネント」ウィンドウを使用します。属性を設定するには「プロパティ」ウィンドウを使用します。

ヒント:

JDeveloper以外でアプリケーションを開発している場合は、ページ上でTLDの短縮名とコンポーネント名を使用します。また、属性の任意の値を追加します。たとえば、tagPaneの場合、次の内容を追加します。

<acme:tagPane>
<visible="true">
<orderBy="alpha">
<tagSelectionListener=#(tagBean.onTagSelect)
</tagPane>

34.6.4 tagPaneカスタム・コンポーネントの使用に関する必知事項

この章の説明に従ってtagPaneコンポーネントを作成し、アプリケーションで使用する場合、バッキングBeanを使用して、カスタム・コンポーネントをアプリケーション・コンポーネントにバインドする必要があります。

例34-24に、tagPaneコンポーネントをFile Explorerアプリケーションにバインドするために使用されるバッキングBeanのコードを示します。

例34-24 tagPaneカスタム・コンポーネントのバッキングBeanロジック

public Map<String, Number> getTags()
{
if (_tags == null)
{
_tags = new TreeMap<String, Number>();
List<FileItem> nameToFileItems = feBean.getDataFactory().getFileItemList();
_doDeepTagCollection(_tags, nameToFileItems);
}
return _tags;
}
public void onTagSelect(TagSelectEvent event)
{
_selectedTag = event.getTag();
CriteriaFileItemFilter criteria = new CriteriaFileItemFilter(_selectedTag);
List<FileItem> nameToFileItems =    _feBean.getDataFactory().getFileItemList();
if (_selectedTagFileItemList == null) {
_selectedTagFileItemList = new ArrayList<FileItem>();
else {
_selectedTagFileItemList.clear();
}
_doDeepTagSearch(criteria, _selectedTagFileItemList, nameToFileItems);
_selectedTagResultsTableModel = new SortableModel(_selectedTagFileItemList);

}

35 JSFページでのユーザー・カスタマイズの許可

この章では、実行時に特定のUIにユーザーが行った変更をセッションの間永続させる方法について説明します。

また、変更が永続データ・リポジトリ内で永続されるようにアプリケーションを構成することもできます。そのように構成することで、アプリケーションを再度使用するときに変更内容が残っていることになります。この永続性を許可するには、完全Fusionテクノロジ・スタックの一部であるOracle Metadata Service (MDS)を使用する必要があります。MDSおよび完全Fusionスタックを使用することで、次の追加の永続性機能も提供されます。

- 追加の属性値の永続

- 検索条件の永続

- UIのドラッグ・アンド・ドロップ操作の結果の永続

- 実行時のページ上のコンポーネントの並替え

- 実行時のページのコンポーネントおよびファセットの追加と削除

Oracle MDSの詳細と使用手順は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「実行時のユーザーによるカスタマイズの許可」の章を参照してください。

この章では、次の項目について説明します。

- 35.1項「ユーザー・カスタマイズについて」

- 35.2項「セッション変更永続性の実装」

35.1 ユーザー・カスタマイズについて

多くのADF Facesコンポーネントで、ユーザーは実行時にコンポーネントの表示を変更できます。たとえば、ユーザーは、panelSplitterコンポーネントのスプリッタの位置を変更したり、パネルに詳細コンテンツを表示するかどうかを変更できます。デフォルトでは、これらの変更はページ・リクエストの間有効です。ユーザーがページを終了して再度表示すると、コンポーネントはデフォルトの構成で表示されます。ただし、変更がユーザーのセッションの間永続するようアプリケーションを構成できます。このようにすると、ユーザーがアプリケーションを終了するまで、変更されたままになります。

表35-1に、デフォルトのパーソナライズ機能を提供するコンポーネントごとの変更を示します。

表35-1 暗黙的に永続する属性値

コンポーネント

属性

実行時の効果

panelBox

showDetail

showDetailHeader

showDetailItem

disclosed

ユーザーは、ヘッダーのアイコンを使用してコンテンツを表示または非表示にできます。ユーザーの直近のアクションに基づいて、詳細コンテンツが表示または非表示になります。

showDetailItem (panelAccordionコンポーネントで使用)

flex

複数のshowDetailItemコンポーネントの高さは、それぞれのflex属性の相対値によって決まります。大きいflex値が設定されているshowDetailItemコンポーネントは、小さい値が設定されているコンポーネントよりも高くなります。これらの比率を変更でき、新しい値は永続します。

showDetailItem (panelAccordionコンポーネントで使用)

inflexibleHeight

ユーザーはパネルのサイズを変更でき、そのサイズは保持されます。

panelSplitter

collapsed

ユーザーはスプリッタのいずれかの面を閉じることができます。閉じられた状態は、ユーザーによる最終の構成として保持されます。

panelSplitter

splitterPosition

パネルのスプリッタの位置が、ユーザーによって最後に移動された位置のままになります。

richTextEditor

editMode

エディタは、ユーザーが最後に選択したモード(WYSIWYGまたはソース)で表示されます。

calendar

activeDay

現在の表示でアクティブとみなされる日は、アクティブな日のままになります。

calendar

view

現在アクティビティを表示しているビュー(日、週、月またはリスト)が保持されます。

panelWindow

dialog

contentHeight

ユーザーは、panelWindowまたはdialogポップアップ・コンポーネントの高さを変更でき、その高さは保持されます。

panelWindow

dialog

contentWidth

ユーザーは、panelWindowまたはdialogポップアップ・コンポーネントの幅を変更でき、その幅は保持されます。

button

link

windowHeight

インライン・ポップアップ・ダイアログがADF Facesダイアトグ・フレームワークまたはADFタスクフローを使用して起動された場合、ユーザーが手動でダイアログのサイズを変更すると、ダイアログを起動したコマンド・コンポーネント上の関連のwindowHeight値も変更され、保持されます。この機能は、インライン・ダイアログにのみ適用され、ブラウザ・ウィンドウ・ダイアログには適用されません。

button

link

windowWidth

インライン・ポップアップ・ダイアログがADF Facesダイアトグ・フレームワークまたはADFタスクフローを使用して起動された場合、ユーザーが手動でダイアログのサイズを変更すると、ダイアログを起動したコマンド・コンポーネント上の関連のwindowWidth値も変更され、保持されます。この機能は、インライン・ダイアログにのみ適用され、ブラウザ・ウィンドウ・ダイアログには適用されません。

column

displayIndex

ADF Facesの列は、ユーザーが実行時に並べ替えることができます。displayIndex属性によって、列の順序が決まります。(デフォルトでは、各列の値は-1に設定され、データ・ソースと同じ順序で列が表示されます)。ユーザーが列を移動すると、新しい順序を反映するよう各列の値が変更されます。これらの新しい値は永続します。

column

frozen

ADF Facesの列は、スクロールされないように固定できます。列のfrozen属性をtrueに設定すると、その列の前のすべての列(displayIndex値に基づく)がスクロールしません。panelCollectionコンポーネントで表を使用する場合、ユーザーが列を固定できるボタンが表示されるようにその表を構成できます。詳細は、12.3.4項「ページへの表の表示方法」を参照してください。

column

noWrap

列のコンテンツを折り返すかどうかを指定します。ユーザーがこの属性値を変更できるようにするコードを作成する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるポップアップ・メニューを作成します。

column

selected

選択された列は、ユーザーが最後に選択した列に基づきます。

column

visible

ユーザーの直近のアクションに基づいて、列が表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるポップアップ・メニューを作成します。

column

width

列の幅が、ユーザーが最後に設定したサイズのままになります。

table

filterVisible

ADF Facesの表には、ユーザーが属性値で表の行をフィルタ処理できるコンポーネントを含めることができます。フィルタを使用するよう構成されている表では、ユーザーの直近のアクションに基づいて、フィルタは表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるボタンを作成します。

dvt:areaGraph

dvt:barGraph

dvt:bubbleGraph

dvt:comboGraph

dvt:horizontal
BarGraph

dvt:lineGraph

dvt:scatterGraph

timeRangeMode

グラフの時間軸上に表示されるデータの時間範囲は、すべてのデータ視覚化グラフ・コンポーネントに指定できます。デフォルトでは、すべてのデータが表示されます。時間範囲は、最後または最初のデータ・ポイントからの相対的時間範囲、または明示的時間範囲にも設定できます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、グラフの時間範囲を選択するためのドロップダウン・リストを作成できます。

dvt:ganttLegend

visible

データ視覚化プロジェクトの凡例、リソース使用率およびスケジュール・ガント・チャート・コンポーネントは、情報パネル内で表示されるかされないかのいずれかです。ユーザーがこの属性値を変更できるように(汎用を表示するための非表示および表示のボタン)コードを記述することが必要になります。

dvt:hierarchyViewer

layout

データ視覚化階層ビューア・コンポーネントでは、上から下への垂直、ツリー、円、放射など、9つの階層レイアウト・オプションをサポートしています。ユーザーは、マップ・コントロール・パネルでレイアウトを変更でき、最後に選択されたレイアウトが保持されます。

dvt:map

mapZoom

このデータ視覚化地理マップ・コンポーネント属性では、マップの初期ズーム・レベルを指定します。ズーム・レベルは、ベース・マップの一部としてマップ・キャッシュ・インスタンスで定義されます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。

dvt:map

srid

このデータ視覚化地理マップコンポーネント属性では、startingXおよびstartingYによって定義されるマップの中心位置や、点テーマのすべての点を含む、マップの全座標のsrid(空間参照ID)を指定します。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。

dvt:map

startingX、startingY

このデータ視覚化地理マップ・コンポーネント属性では、マップの中心位置のXおよびY座標を指定します。座標のsridはsrid属性で指定します。srid属性が指定されていない場合、その値はマップの中心位置の経度であると想定されます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。

dvt:projectGantt

dvt:resource
UtilizationGantt

dvt:schedulingGantt

splitterPosition

パネルのスプリッタの位置が、ユーザーによって最後に移動された位置のままになります。

dvt:timeAxis

scale

プロジェクト、リソース使用率およびスケジュールのガント・チャートのデータ視覚化コンポーネントでは、ガント・チャートの主時間軸および副時間軸の指定にこのファセットを使用します。タイム・スケール(twoyears、year、halfyears、quarters、twomonths、months、weeks、twoweeks、days、sixhours、threehours、hours、halfhours、quarterhours)は、ユーザーがメニュー・バーの「表示」メニューを使用することで設定でき、その選択は保持されます。このコンポーネント値には、カスタム・タイム・スケールも指定できます。

dvt:timeSelector

explicitStart、explicitEnd

データ視覚化の面、棒、コンボ、折れ線、散布およびバブルの各グラフ・コンポーネントでは、この子タグ属性を使用して、タイム・セレクタの開始および終了日付を明示的に指定します。この属性では、値バインディングのみがサポートされています。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。

35.1.1 ユーザー・カスタマイズのユースケースおよび例

アプリケーションは、表35-1に示した属性の値をユーザー・セッション中ずっと保持できるように構成できます。たとえば、アプリケーションに表が含まれており、ユーザーが列の幅をコンテンツが1行ですべて表示されるように調整するとします。セッションの変更永続性を使用するようにアプリケーションを構成すると、ユーザーがそのページから去り、次に戻ったときに、列の幅は以前の設定のままで開かれます。

注意:

追加機能の場合、変更が永続データ・リポジトリで保持されるようにアプリケーションを構成でき、その結果、変更はそのユーザーに対して複数のセッションにわたり持続します。この永続的な持続性を可能にするには、フルFusionテクノロジ・スタックを使用する必要があります。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「実行時のユーザーによるカスタマイズの許可」の章を参照してください。

35.2 セッション変更永続性の実装

ユーザーによるセッションへの変更をアプリケーションで永続させるには、カスタマイズが有効になるようプロジェクトを構成する必要があります。

35.2.1 セッション変更永続性の実装方法

web.xmlファイルでのカスタマイズが有効になるようアプリケーションを構成します。

セッション変更永続性を実装する手順:

1. 「アプリケーション」ウィンドウで、Webプロジェクトをダブルクリックします。

2. 「プロジェクト・プロパティ」ダイアログで、「ADFビュー」ノードを選択します。

3. 「ADFビュー」ページで、「ユーザー・カスタマイズの有効化」チェック・ボックスをアクティブにし、「セッションの継続時間」ラジオ・ボタンを選択して、「OK」をクリックします

35.2.2 変更永続性を使用するようアプリケーションを構成する場合の処理

セッションへの変更を保存するよう選択すると、JDeveloperでCHANGE_PERSISTENCEコンテキスト・パラメータがweb.xmlファイルに追加され、値がsessionに設定されます。このコンテキスト・パラメータでは、永続性の処理に使用されるChangeManagerクラスが登録されます。例35-1に、web.xmlファイルのコンテキスト・パラメータを示します。

例35-1 変更の永続に使用されるweb.xmlのコンテキスト・パラメータ

<context-param>
<param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
<param-value>session</param-value>
</context-param>

35.2.3 実行時の処理: 変更をどのように永続させるか

セッションへの変更を永続させるようアプリケーションを構成している場合、ビューIDに従って索引付けされたデータ構造内のセッション変数に変更が記録されます。RENDER_RESPONSE JSFフェーズが開始する前に、指定されたコンポーネントに対する変更がタグ・アクション・クラスで検索され、追加されたときと同じ順序で変更が適用されます。つまり、セッションの間に登録された変更は、同じセッションの後続のリクエストでのみ適用されます。

35.2.4 テンプレートおよび領域での変更永続性の使用に関する必知事項

セッション永続性を使用すると、変更は特定のセッションのviewIdに対して、コンポーネントで記録されリストアされます。その結果、その変更がフラグメントまたはページのテンプレートに属するコンポーネントで適用されると、ページでそのフラグメントまたはテンプレートが使用される範囲でのみ適用されます。そのフラグメントまたはテンプレートが使用されるすべてのページに及ぶわけではありません。たとえば、プロジェクトにpageOne.jsfおよびpageTwo.jsf JSFページがあり、どちらにもregion.jsffページ・フラグメントで定義されているフラグメントが含まれていて、さらにはshowDetailコンポーネントが含まれているとします。pageOne.jsf JSFページがレンダリングされ、showDetailコンポーネント上のdisclosed属性が変更されると、暗黙的な属性変更が記録され、pageOne.jsfページに対してのみ適用されます。ユーザーがpageTwo.jsfページに移動した場合、属性の変更は適用されません。

36 ドラッグ・アンド・ドロップ機能の追加

この章では、ユーザーが属性やオブジェクトの値をコンポーネントから別のコンポーネントにドラッグしたり、コンポーネントをドラッグ・アンド・ドロップしたりできるようにするドラッグ・アンド・ドロップ機能を、ページに追加する方法について説明します。属性、オブジェクト、コレクション、コンポーネント、カレンダおよびサポートされるDVTコンポーネントのドラッグ・アンド・ドロップ機能を追加する方法を説明します。panelDashboard コンポーネントにドラッグ・アンド・ドロップ機能を追加する方法についても説明します。

この章では、次の項目について説明します。

- 36.1項「ドラッグ・アンド・ドロップ機能について」

- 36.2項「属性のドラッグ・アンド・ドロップ機能の追加」

- 36.3項「オブジェクトのドラッグ・アンド・ドロップ機能の追加」

- 36.4項「コレクションのドラッグ・アンド・ドロップ機能の追加」

- 36.5項「コンポーネントのドラッグ・アンド・ドロップ機能の追加」

- 36.6項「panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加」

- 36.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」

- 36.8項「DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加」

36.1 ドラッグ・アンド・ドロップ機能について

ADF Facesフレームワークには、ページ上の場所から別の場所へアイテムをドラッグ・アンド・ドロップする機能があります。ほとんどの場合、ドラッグ・アンド・ドロップは、ソースおよびターゲットに適切なタグを追加し、マネージドBeanにコードを実装することにより、簡単に実装できます。ドラッグ・アンド・ドロップにより、ユーザーはWebアプリケーションでは当然期待されるGUI経験を体感できます。たとえば、File Explorerアプリケーションでは、図36-1で示すように、ファイルを「表」タブからドラッグし、別のディレクトリ・フォルダにドロップできます。

図36-1 File Explorerアプリケーションでのドラッグ・アンド・ドロップ

このシナリオでは、オブジェクトを実際にコレクション(Folder0)からドラッグし、別のコレクション(Folder2)にドロップしています。これは、多数サポートされているドラッグ・アンド・ドロップ・シナリオの1つです。ADF Facesでは、次のシナリオがサポートされています。

- 属性値をコンポーネント・インスタンスからドラッグして、別のインスタンスへコピーします。たとえば、ユーザーはoutputTextコンポーネントをinputTextコンポーネントにドラッグでき、その結果、outputTextコンポーネントのvalue属性がinputTextコンポーネントのvalue属性の値になります。

- オブジェクトの値をドラッグし、別のオブジェクトの値になるようにドロップします。たとえば、ユーザーはoutputTextコンポーネントを別のoutputTextコンポーネントにドラッグでき、その結果、Stringオブジェクトの配列になり、後者のoutputTextコンポーネントのtext属性に値が移入されます。

- 図36-1に示すように、コレクションからオブジェクトをドラッグし、別のコレクションにドロップします。

- コンポーネントをページ上の場所から別の場所にドラッグします。たとえば、ユーザーは既存のpanelBoxコンポーネントをpanelGridコンポーネント内の新規の場所にドラッグできます。

- カレンダ内のアクティビティをある開始時刻または開始日から別の時刻または日付にドラッグします。

- コンポーネントをpanelDashboardコンポーネントへ、または同コンポーネントからドラッグします。

- DVT散布図またはバブル・グラフのマーカーをドラッグして値を変更します。

- オブジェクトをDVTガント・チャートから別のコンポーネントにドラッグします。

- DVTツリーマップとサンバースト・コンポーネントからノードをドラッグするか、DVTツリーマップとサンバースト・コンポーネントへオブジェクトをドロップします。

- 1つ以上のノードをDVT階層ビューア内でドラッグ・アンド・ドロップ、1つ以上のノードを階層ビューアから別のコンポーネントへドラッグ、あるいは1つ以上のコンポーネントから階層ビューアへドラッグします。

- DVT時系列からイベントをドラッグし、表などのコレクション・コンポーネントにドロップするか、時間ベースのイベントの表から行をドラッグして時系列にドロップします。

ユーザーがソースをクリックしてドラッグし始めると、ブラウザにはドラッグされている要素がマウス・ポインタにアタッチされたゴースト要素として表示されます。ゴースト要素が有効なターゲット上に移動すると、そのターゲット・コンポーネントにはなんらかのフィードバック(強調表示され、カーソルが変化してターゲットが有効であることを示すなど)が現れます。ユーザーがゴースト要素を無効なターゲットにドラッグすると、カーソルが変わり、そのターゲットが有効でないことを示します。

属性値をドラッグするとき、ユーザーはターゲットに対して値のコピーしかできません。他のすべてのドラッグ・アンド・ドロップ・シナリオの場合、ドロップ時に要素は、コピー(コピー・アンド・ペースト)、移動(カット・アンド・ペースト)またはリンク(リンクが実際のファイル・オブジェクトの参照となるディレクトリ内のファイルへのショートカットを作成)できます。

ドラッグされ値を含むコンポーネントは、ソースと呼ばれます。ドロップを受け入れるコンポーネントは、ターゲットと呼ばれます。ソースおよびターゲット・コンポーネントに子として特定のタグを使用し、フレームワークにドロップを許可するように指示します。表36-1に、様々なドラッグ・アンド・ドロップのシナリオ、有効なソースおよびターゲット、そのシナリオで使用するように関連付けられたタグを示しています。

表36-1 ドラッグ・アンド・ドロップのシナリオ

シナリオ

ソース

ターゲット

属性値のドラッグ

コンポーネント上の属性値

別のコンポーネント上の属性値(同じオブジェクト型である場合)

タグ:
attributeDragSource

タグ:
attributeDropTarget

オブジェクトをコンポーネントから別のコンポーネントへドラッグ

すべてのコンポーネント

すべてのコンポーネント

タグ:
attributeDragSource

タグ:
dropTarget

アイテムをコレクションからドラッグして別のコレクションにドロップ

table、treeおよびtreeTableコンポーネント

table、treeおよびtreeTableコンポーネント

タグ:
dragSource

タグ:
collectionDropTarget

コンポーネントをコンテナから別のコンテナへドラッグ

すべてのコンポーネント

すべてのコンポーネント

タグ:
componentDragSource

タグ:
dropTarget

カレンダ・アクティビティをある開始時刻または開始日から別の時刻または日付にドラッグ

calendarActivityオブジェクト

calendarコンポーネント

Tag:
不要

タグ:
calendarDropTarget

panelBoxコンポーネントをpanelDashboardコンポーネントにドラッグ

panelBoxコンポーネント

panelDashboardコンポーネント

タグ:
componentDragSource

タグ:
dataFlavor

panelBoxコンポーネントをpanelDashboardコンポーネントからドラッグ

panelDashboardコンポーネント内のpanelBoxコンポーネント

すべてのコンポーネント

タグ:
componentDragSource

タグ:
dropTarget

DVTグラフ内のマーカーをドラッグ

graphコンポーネント

graphコンポーネント

タグ:
dragSource

タグ:
dropTarget

DVTガント・チャートからオブジェクトをドラッグし、別のコンポーネントにドロップ

ガント・チャート

すべてのコンポーネント

タグ:
dragSource

タグ:
dropTarget

DVT階層ビューア、サンバースト、またはツリーマップからノードをドラッグし、別のコンポーネントにドロップします

階層ビューア, サンバースト、またはツリーマップコンポーネント

すべてのコンポーネント

タグ:
dragSource

タグ:
dropTarget

時系列からイベントをドラッグしてコレクション・コンポーネントにドロップします

timelineコンポーネント

table、treeおよびtreeTableコンポーネント

タグ:
dragSource

タグ:
collectionDropTarget

ターゲットにドロップできるオブジェクトの型は、dataFlavorタグを追加することで制限でいます。これは、ターゲットでは1つのオブジェクト型しか受け入れられないのに、ソースが多数の異なる型の1つである場合に役立ちます。dataFlavorタグでは、ターゲットで複数のソースまたは複数の型を含む可能性のあるソースからオブジェクトを受け入れることができるよう、複数の型を設定することもできます。ドロップが成功するためには、ターゲットとソースの両方にdataFlavorタグがあり、dataFlavorが識別値とともにカプセル化するJavaタイプがソースとターゲットの間で同一でなければなりません。

注意:

ドラッグ・アンド・ドロップ機能は、ウィンドウ間ではサポートされていません。ウィンドウ境界を越えるドラッグは取り消されます。ポップアップ・ウィンドウとポップアップのベース・ページとの間のドラッグ・アンド・ドロップ機能はサポートされています。

また、ドラッグ・アンド・ドロップ機能はアクセスできないため、ドラッグ・アンド・ドロップを実行するために使用できるキーボード・ストロークがありません。したがって、アプリケーションですべての機能をアクセス可能にすることが求められる場合、このロジックを提供する必要があります。たとえば、ページでユーザーに、オブジェクトを選択する方法と、選択したオブジェクトを移動できるようにする「移動」ボタンまたはメニュー項目を提供する場合もあります。

36.1.1 ドラッグ・アンド・ドロップの追加機能

ドラッグ・アンド・ドロップを実装する前に、その他のADF Faces機能を理解しておくと役に立ちます。ドラッグ・アンド・ドロップの実装に役立つ他の項へのリンクは、次のとおりです。

- マネージドBean: コードにマネージドBeanを使用している可能性があります。マネージドBeanの使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

- イベント: 表およびツリー・コンポーネントでは、なんらかのロジックを実行することにより、アプリケーションを反応させることができるサーバー側およびクライアント側の両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。

36.2 属性のドラッグ・アンド・ドロップ機能の追加

属性のドラッグ・アンド・ドロップ機能は、あるコンポーネントの属性をターゲットとして定義し、別のコンポーネントの属性をソースとして定義して追加します。

注意:

ターゲットとソースの属性値は同じデータ型である必要があります。たとえば、ソースとターゲットの両方がString型の場合、属性のドラッグ・アンド・ドロップが使用可能です。どちらも数値型の場合は、両方で同じコンバータを使用します。

36.2.1 ドラッグ・アンド・ドロップ機能の追加方法

JSFページにすでにあるターゲットとソースのコンポーネントをドラッグ・アンド・ドロップできます。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.2項「属性のドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

属性のドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「属性ドロップ・ターゲット」をページのターゲット・コンポーネントに子としてドラッグ・アンド・ドロップします。

2. 「属性ドロップ・ターゲットの挿入」ダイアログで「属性」ドロップダウンを使用して、ドラッグ・アンド・ドロップ・アクションによる移入先の属性を選択します。このドロップダウン・リストには、ターゲット・コンポーネントの有効な属性がすべて表示されます。

3. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「属性ドラッグ元」をターゲットに値を提供するコンポーネントに子としてドラッグ・アンド・ドロップします。

4. 「属性ドラッグ元の挿入」ダイアログで、「属性」ドロップダウンを使用して、ターゲット属性への移入に使用される値の属性を選択します。このドロップダウン・リストには、ソース・コンポーネントの有効な属性がすべて表示されます。

36.3 オブジェクトのドラッグ・アンド・ドロップ機能の追加

ユーザーが属性値以外をドラッグできるようにする場合、またはあるコンポーネントから別のコンポーネントへ属性をコピーする以外の操作をユーザーができるようにする場合、dropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます。ドロップ・ターゲットとドラッグ・ソースが複数ある場合のために、識別値を使用して有効な組合せを制限できます。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。

たとえば、図36-2に示すように、Stringsの配列を持つoutputTextコンポーネントがあり、ユーザーがoutputTextコンポーネントをpanelBoxコンポーネントにドラッグできるようにして、panelBoxにStringの配列を表示させるとします。

図36-2 配列オブジェクトのドラッグ・アンド・ドロップ

outputTextコンポーネントにはattributeDragSourceタグが含まれます。ただし、String値の配列をoutputTextコンポーネントからドラッグしたいので、ターゲットのoutputTextコンポーネントでattributeDropTargetタグではなくdropTargetタグを使用する必要があります。また、dataFlavorタグを使用してarrayオブジェクトのみがターゲットで受け入れられるようにします。

dataFlavorタグの識別値の定義もできます。同じオブジェクト型の2つのターゲットと2つのソースがある場合に、これは有用です。識別値を作成することで、各ターゲットで有効なソースのみが受け入れられることが保証されます。たとえば、EMPLOYEEオブジェクトを受け入れるTargetAとTargetBの2つのターゲットがあるとします。EMPLOYEEオブジェクトのソースも2つあるとします。TargetAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つEMPLOYEEソースのみが受け入れられます。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはTransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはTransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。このリスナーの詳細は、36.8項「DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加」の手順で説明します。

36.3.1 単一オブジェクトのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、まず、コンポーネントをドラッグ・アンド・ドロップ・アクションのターゲットとして定義するタグをコンポーネントに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.3項「オブジェクトのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

次のタスクを完了する必要があります。

ページにソースおよびターゲット・コンポーネントを作成します。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「ドロップ・ターゲット」をドラッグし、ページのターゲット・コンポーネントに子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ5で作成)に評価される式を入力します。

マネージドBeanの使用の詳細は、3.6項「マネージドBeanの作成と使用」を参照してください。

ヒント:

clientDropListener属性を挿入して、クライアントでドロップを捕捉することもできます。詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

3. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップ可能なオブジェクトのクラス(java.lang.Objectなど)を入力します。この選択は、dataFlavorタグを作成するために使用され、このタグにより、ターゲットにドロップできるオブジェクトの型(StringやDateオブジェクトなど)が決まります。1つのドロップ・ターゲットに複数のdataFlavorタグを使用し、ドロップ・ターゲットでこれらの型のいずれも受け入れるようにすることができます。

ヒント:

DataFlavorタグに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

4. 構造ウィンドウで、dropTargetタグを選択します。「プロパティ」ウィンドウで、actions属性の値を選択します。これによって、ドロップ・ターゲットでサポートされるアクションが定義されます。有効な値は、COPY(コピーして貼付け)、MOVE(切り取って貼付け)およびLINK(コピーしてリンクとして貼付け)です。

MOVE COPY

アクションが指定されない場合、デフォルトはCOPYです。

例36-1に、panelBoxコンポーネントに挿入され、配列オブジェクトをドロップ・ターゲットとするdropTargetコンポーネントのコードを示します。アクションが定義されていないため、許可されるアクションはCOPYのみであることに注意してください。

例36-1 dropTargetタグのコード

<af:panelBox text="PanelBox2">
<f:facet name="toolbar"/>
<af:dropTarget dropListener="#{myBean.handleDrop}">
<af:dataFlavor flavorClass="java.lang.Object[]"/>
</af:dropTarget>
</af:panelBox>

5. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)作成します。

このメソッドでは、パラメータとしてDropEventイベントをとり、DnDActionオブジェクトを返す必要があり、これはソースをドロップするときに実行されるアクションです。有効な戻り値は、DnDAction.COPY、DnDAction.MOVEおよびDnDAction.LINKで、ステップ4でターゲット属性を定義したときに設定されたものです。このメソッドでは、DropEventイベントをチェックし、ドロップを受け入れるかどうか判断する必要があります。ドロップを受け入れる場合、メソッドではドロップを実行し、実行したDnDActionオブジェクトを返します。そうでない場合は、ドロップが拒否されたことを示すDnDAction.NONEを返します。

このメソッドでは、各dataFlavorオブジェクトの存在も優先順に確認される必要があります。

ヒント:

ターゲットに複数のdataFlavorオブジェクトが定義されている場合、Transferable.getSuitableTransferData()メソッドを使用できます。このメソッドでは、Transferableオブジェクトで使用可能なTransferDataオブジェクトのListが適合性の高いものから順に返されます。

DataFlavorオブジェクトでは、ドロップされるデータの型(java.lang.Objectなど)が定義されます。これは、手順3で作成したJSPのDataFlavorタグでの定義と同じである必要があります。

ヒント:

DataFlavorオブジェクトに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

DataFlavorオブジェクトではポリモフィズムがサポートされるため、ドロップ・ターゲットでjava.util.Listが受け入れられる場合、Transferableオブジェクトにjava.util.ArrayListを含むドロップは正常終了します。同様に、この機能ではArraysとListsとの間の自動変換もサポートされます。

ドラッグ・アンド・ドロップ・フレームワークで、サーバーのDataFlavorオブジェクトをクライアント・コンポーネントで表す方法がわからない場合、すべてのドロップがクライアントで正常終了するようドロップ・ターゲットが構成されます。

例36-2に、イベント・ハンドラ・メソッドがコールするプライベート・メソッドを示します(イベント・ハンドラそのものは何もしませんが、このメソッドをコールします。このメソッドには、panelBoxコンポーネントでoutputTextコンポーネントの値となるStringパラメータも必要です)。このメソッドでは、イベント・ペイロードから配列オブジェクトをコピーし、そのイベントを開始したコンポーネントに割り当てます。

例36-2 dropListenerのイベント・ハンドラ・コード

public DnDAction handleDrop(DropEvent dropEvent)
{
Transferable dropTransferable = dropEvent.getTransferable();
Object[] drinks = dropTransferable.getData(DataFlavor.OBJECT_ARRAY_FLAVOR);

if (drinks != null)
{
UIComponent dropComponent = dropEvent.getDropComponent();

// Update the specified property of the drop component with the Object[] dropped
dropComponent.getAttributes().put("value", Arrays.toString(drinks));

return DnDAction.COPY;
}
else
{
return DnDAction.NONE;
}
}

この例では、ドロップ・コンポーネントはpanelBoxコンポーネントです。panelBoxにはvalue属性がないので、panelBoxのtext属性を設定するには次のメソッドを呼び出す必要があります。

dropComponent.getAttributes().put("text", Arrays.toString(drinks));

6. 「コンポーネント」ウィンドウの「操作」パネルから、「クライアント属性」をドラッグし、ページのソース・コンポーネントに子としてドロップします。
このタグは、イベントに対するソースのペイロードの定義に使用されます。「プロパティ」ウィンドウで、clientAttributeタグに次を定義します。

- 名前: ペイロードの名前を入力します。

- 値: ペイロードの値と評価されるEL式を入力します。飲み物を例とすると、これは異なる飲み物の値を含むArrayに解決されます。

7. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「属性ドラッグ元」をドラッグし、ページのソース・コンポーネントに子としてドロップします。
「属性ドラッグ元の挿入」ダイアログで、前述の手順で作成したclientAttributeタグに定義するnameをドロップダウン・リストから選択します。これにより、clientAttributeタグの値がソースのペイロードになります。例36-3に、ドラッグ・アンド・ドロップ操作のソースであるoutputTextコンポーネントのコードを示します。

例36-3 ドラッグ・ソースのコード

<af:outputText value="Drag to see drinks">
<af:clientAttribute name="drinks" value="#{myBean.drinks}"/>
<af:attributeDragSource attribute="drinks"/>
</af:outputText>

36.3.2 実行時の処理: キーボード修飾子の使用方法

ドラッグ・アンド・ドロップ操作時、ユーザーはキーボードのキーを押して(キーボード修飾子と呼ばれます)、ドラッグ・アンド・ドロップで行われるアクションを選択できます。ドラッグ・アンド・ドロップ・フレームワークでは、次のキーボード修飾子がサポートされます。

- [Shift]: MOVE

- [Ctrl]: COPY

- [Ctrl]+[Shift]: LINK

ユーザーがドラッグ・アンド・ドロップ操作を行うと、ドロップ・ターゲットで、まず、ドラッグ・ソースのデータ形式の値が受け入れ可能かどうかを判断します。ソースとターゲットがコレクションの場合、次に、フレームワークでドラッグ・ソースとドロップ・ターゲットとの間で可能なアクションの論理積を求め、論理積のアクション(COPY、MOVEまたはLINKのうち1つ)をこの順に実行します。有効なアクションが1つのみの場合、そのアクションが実行されます。複数のアクションが可能で、ユーザーのキーボード修飾子がそのうちの1つに合致する場合、それが実行されます。キーボード修飾子が使用されない、あるいはキーボード修飾子と可能なアクションが合致しない場合、可能なアクションのセットからCOPY、MOVE、LINKがこの順にフレームワークで選択されます。

たとえば、COPYとMOVEをサポートするドロップ・ターゲットがあるとします。まず、ドロップ・ターゲットでは、ドラッグ・ソースが有効なデータ・フレーバであることを確認します。次に、ユーザーがドロップを実行したときに、どのアクションを実行するかを判断します。この例では、セットはCOPYとMOVEです。ユーザーがドラッグ中に[Shift]キーを押し続けると(MOVEのキーボード修飾子)、フレームワークではMOVEアクションが選択されます。ユーザーがドラッグ中に[Shift]キーを押し続ける以外のことをしている場合、修飾子キーが選択されていないときはCOPYがデフォルトであるため(順番の1番目)、アクションはCOPYになります。ユーザーが[Ctrl]キーを押している場合は、その修飾子はCOPYと一致し、その結果COPYが実行されます。ユーザーが[Ctrl]キーと[Shift]キーを押していた場合、その修飾子は許可されたアクションの論理積のセットにはないLINKアクションと一致するため、アクションはやはりCOPYになります。

注意:

JavaとJavaScriptとの間のラウンドトリップで情報が失われるため、ドロップでのデータが見込みとは異なる型の場合があります。たとえば、すべての数値型はdoubleオブジェクトとして、charオブジェクトはStringオブジェクトとして、ListオブジェクトとArrayオブジェクトはListオブジェクトとして、その他の大部分のオブジェクトはMapオブジェクトとして表されます。詳細は、6.4.3項「データのマーシャリングとアンマーシャリングに関する必知事項」を参照してください。

36.3.3 ClientDropListenerの使用に関する必知事項

dropTargetタグにはclientDropListener属性が含まれており、この属性によりクライアントでドロップ・イベントを処理するJavaScriptを参照できます。クライアント・ハンドラはパラメータをとることはなく、AdfDnDContextアクションを返します。たとえば、メソッドがAdfDnDContext.ACTION_NONEを返すと、ドロップ操作は取り消され、サーバーでコールされません。メソッドがAdfDnDContext.ACTION_COPYを返すと、コピー操作が許可され、dropListenerが存在する場合には、それを実行するコールがサーバーで発生します。

たとえば、ドロップ・イベントの起動時にメッセージをログ出力するとします。メッセージの出力を処理し、サーバー・リスナーが起動されるよう適切なアクションを返すクライアント・ハンドラを作成します。例36-4に、メッセージの出力にロガーを使用するクライアント・ハンドラを示します。

例36-4 clientDropListenerハンドラ

<script>
/**
* Shows a message.
*/
function showMessage()
{
AdfLogger.LOGGER.logMessage(AdfLogger.ALL, "clientDropListener handler,
copying...");
return AdfDnDContext.ACTION_COPY;
}
</script>

36.4 コレクションのドラッグ・アンド・ドロップ機能の追加

ユーザーは、collectionDropTargetおよびdragSourceタグを使用して、コレクションからアイテム(表から行など)をドラッグし、ツリーなどの別のコレクション・コンポーネントにドロップできるドラッグ・アンド・ドロップ機能を追加します。たとえば、File Explorerアプリケーションでは、ユーザーは、ディレクトリの内容を表示する表からディレクトリ・ツリーのフォルダにファイルをドラッグできます。図36-3に、Folder0ディレクトリの内容を表示する表からFolder3ディレクトリにドラッグされるFile0.docオブジェクトを示します。ドロップが完了すると、オブジェクトはFolder3を構成するコレクションの一部になります。

図36-3 File Explorerアプリケーションでのドラッグ・アンド・ドロップ機能

単一オブジェクトのドラッグ・アンド・ドロップ同様、コレクションに対しドロップによりコピー、移動またはコピーしてリンクとして貼り付ける(あるいは3つを組み合せる)ことができ、dataFlavorタグを使用してターゲットでの受け入れ対象を限定できます。

ターゲット・ソースがコレクションで、移動動作がサポートされている場合、dragDropEndListener属性のメソッドを実装して、ソース・コンポーネントから参照し、ドラッグ・アンド・ドロップ操作後のコレクションのクリーン・アップに使用することもできます。詳細は、36.4.2項「dragDropEndListenerに関する必知事項」を参照してください。

36.4.1 コレクションのドラッグ・アンド・ドロップ機能の追加方法

コレクションのドラッグ・アンド・ドロップ機能を追加するには、dropTargetタグを使用するかわりにcollectionDropTargetタグを使用します。その後、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装する必要があります。次に、dragSourceタグを使用して、ドラッグ・アンド・ドロップ操作のソースを定義します。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.4項「コレクションのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

次のタスクを完了する必要があります。

ページにソースおよびターゲット・コンポーネントを作成します。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「コレクション・ドロップ・ターゲット 」をドラッグし、ページのターゲット・コレクション・コンポーネントに子としてドロップします。

2. 「コレクション・ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ4で作成)に評価される式をdropListener属性に入力します。

3. 「プロパティ」ウィンドウで、次を設定します。

- actions: ドラッグ・アンド・ドロップ操作時にソースで行われるアクションを選択します。
アクションが指定されない場合、デフォルトはCOPYです。

- modelName: コレクションのモデルを定義します。
modelName属性の値は、互換性のためにドラッグ・ソースの識別に使用されるStringオブジェクトです。この属性の値は、ステップ6で使用するdragSourceタグのdiscriminant属性の値と一致させる必要があります。つまり、これは任意の名前で、ターゲットとソースが同じmodelName値や識別値を共有する場合に役立ちます。

4. ステップ2でEL式に挿入されたマネージドBeanに、ドロップ・イベントのハンドラを実装します。

このメソッドでは、DropEventイベントをパラメータとして使用し、DnDActionを返す必要があります。このメソッドでは、DropEventを使用して、 Transferableオブジェクトを取得し、そこからRowKeySet (ドラッグのために選択された行)を取得します。Transferableオブジェクトから取得したCollectionModelを使用して、実際のrowDataを取得し、ドロップを完了することができます。メソッドでは次にDropEventをチェックして、ドロップを受け入れるかどうかを判断します。メソッドでドロップを受け入れる場合は、ドロップを実行して、実行したDnDAction (DnDAction.COPY、DnDAction.MOVEまたはDnDAction.LINK)を返し、受け入れない場合は、DnDAction.NONEを返して、ドロップが拒否されたことを示します。

例36-5に、2つの表の間での行のコピーを処理するcollectionDropTargetデモに使用されるCollectionDnd.javaマネージドBeanのイベント・ハンドラ・メソッドを示します。

例36-5 コレクションのdropListenerのイベント・ハンドラ・コード

public DnDAction handleDrop(DropEvent dropEvent)
{
return _handleDrop(dropEvent, getTargetValues(), "DnDDemoModel");
}
private DnDAction _handleDrop(DropEvent dropEvent,
ArrayList<DnDDemoData> targetValues,
String discriminator)
{
Transferable transferable = dropEvent.getTransferable();
// The data in the transferable is the row key for the dragged component.
DataFlavor<RowKeySet> rowKeySetFlavor =
DataFlavor.getDataFlavor(RowKeySet.class, discriminator);
RowKeySet rowKeySet = transferable.getData(rowKeySetFlavor);
if (rowKeySet != null)
{
// Get the model for the dragged component.
CollectionModel dragModel = transferable.getData(CollectionModel.class);
if (dragModel != null)
{
// Set the row key for this model using the row key from the transferable.
Object currKey = rowKeySet.iterator().next();
dragModel.setRowKey(currKey);

// And now get the actual data from the dragged model.
// Note this won't work in a region.
//Need to change this to use collectionModel data flavor.
DnDDemoData dnDDemoData = (DnDDemoData)dragModel.getRowData();

// Put the dragged data into the target model directly.
// Note that if you wanted validation/business rules on the drop,
// this would be different.
// getTargetValues() is the target collection used by the target component
if (dropEvent.getProposedAction() == DnDAction.LINK)
dnDDemoData = DnDDemoData.addALink(dnDDemoData);
targetValues.add(dnDDemoData);
}
return dropEvent.getProposedAction();
}
else
{
return DnDAction.NONE;
}
}

5. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「ドラッグ元」をドラッグし、ソース・コンポーネントに子としてドロップします。

6. dragSourceタグを選択して、「プロパティ」ウィンドウでactions、discriminantおよび任意のdragDropEndListenerをターゲットに対して構成済として設定します。たとえば、dragSourceタグは次のようになります。

<af:dragSource actions="MOVE" discriminant="DnDDemoModel
dragDropEndListener="#{collectionDnD.endListener}"/>

36.4.2 dragDropEndListenerに関する必知事項

ドロップ・イベントの後でソース・コレクションをクリーンアップする必要がある場合が考えられます。たとえば、ドラッグで移動を行った場合、移動した項目がコレクションの一部ではなくなるように、ソース・コンポーネントをクリーンアップする必要があることがあります。

dragSourceタグには、ドラッグ・アンド・ドロップ操作の終了後のロジックを含むハンドラを登録できるdragDropEndListener属性が含まれます。

たとえば、ドラッグ・アンド・ドロップでオブジェクトを移動する場合、ドロップの正常終了後にソース・コンポーネントからオブジェクトを物理的に削除する必要があります。例36-6に、dragDropEndListener属性のハンドラを示します。

例36-6 dragDropEndListenerのハンドラ

public void endListener(DropEvent dropEvent)
{
Transferable transferable = dropEvent.getTransferable();

// The data in the transferrable is the row key for the dragged component.
DataFlavor<RowKeySet> rowKeySetFlavor =
DataFlavor.getDataFlavor(RowKeySet.class, "DnDDemoModel");
RowKeySet rowKeySet = transferable.getData(rowKeySetFlavor);
if (rowKeySet != null)
{
Integer currKey = (Integer)rowKeySet.iterator().next();

// Remove the dragged data from the source model directly.
// getSourceValues() represents a collection object used by the source
// component
Object removed = getSourceValues().remove(currKey.intValue());
}
// Need to add the drag source table so it gets redrawn.
// The drag source component needs to be partially refreshed explicitly, while
// drop target component automatically refreshed and displayed.
AdfFacesContext.getCurrentInstance().addPartialTarget(dropEvent.getDragComponent());

36.5 コンポーネントのドラッグ・アンド・ドロップ機能の追加

ある親から別の親へのコンポーネントの移動を可能にしたり、親コンポーネントの子コンポーネントの並替えを可能にしたりできます。例として、図36-4に、panelGridコンポーネントの最初の子で最後に移動される暗色のpanelBoxコンポーネントを示します。

図36-4 コンポーネント間のドラッグ・アンド・ドロップ機能

注意:

panelDashboardコンポーネントでのコンポーネントの出し入れを行う場合、そのコンポーネント固有のプロシージャを使用する必要があります。詳細は、36.6項「panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加」を参照してください。

36.5.1 コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

コンポーネントに対するドラッグ・アンド・ドロップ機能の追加は、オブジェクトに対するものと同様です。ただし、attributeDragSourceタグを使用するかわりにcomponentDragSourceタグを使用します。オブジェクトまたはコレクションのドラッグ・アンド・ドロップ同様、dropListenerハンドラを実装する必要もあります。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.5項「コンポーネントのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「ドロップ・ターゲット」をドラッグし、ページのターゲット・コンポーネントに子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ4で作成)に評価される式を入力します。

3. dropTargetタグを選択した状態のまま、「プロパティ」ウィンドウでaction属性に有効なアクション・セットを選択します。

4. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

メソッドでドロップを受け入れる場合は、ドロップを実行して、実行したDnDAction (DnDAction.COPY、DnDAction.MOVEまたはDnDAction.LINK)を返し、受け入れない場合は、DnDAction.NONEを返して、ドロップが拒否されたことを示します。

このハンドラ・メソッドでは、DropEventイベントを使用してTransferableオブジェクトとそのデータを取得し、移動またはコピーを完了して、必要に応じてコンポーネントを並べ替えます。ドロップを完了したら、メソッドでは実行したDnDActionを返します。そうでない場合は、ドロップが拒否されたことを示すDnDAction.NONEを返します。

例36-7に、デモ・アプリケーションのcomponentDragSource JSFページで使用されるDemoDropHandler.javaマネージドBeanのhandleComponentMoveイベント・ハンドラを示します。

例36-7 コンポーネントの移動を処理するdropListenerのイベント・ハンドラ・コード

public DnDAction handleComponentMove(DropEvent dropEvent)
{
Transferable dropTransferable = dropEvent.getTransferable();
UIComponent movedComponent =  dropTransferable.getData
(DataFlavor.UICOMPONENT_FLAVOR);
if ((movedComponent != null) &&
DnDAction.MOVE.equals(dropEvent.getProposedAction()))
{
UIComponent dropComponent = dropEvent.getDropComponent();
UIComponent dropParent = dropComponent.getParent();
UIComponent movedParent = movedComponent.getParent();
UIComponent rootParent = null;
ComponentChange change = null;

// Build the new list of IDs, placing the moved component after the dropped
//component.
String movedLayoutId = movedParent.getId();
String dropLayoutId = dropComponent.getId();

List<String> reorderedIdList = new
ArrayList<String>(dropParent.getChildCount());

for (UIComponent currChild : dropParent.getChildren())
{
String currId = currChild.getId();

if (!currId.equals(movedLayoutId))
{
if(!movedLayoutIdFound && currId.equals(dropLayoutId))
reorderedIdList.add(movedLayoutId);
reorderedIdList.add(currId);
if(movedLayoutIdFound && currId.equals(dropLayoutId))
reorderedIdList.add(movedLayoutId);
}
else
movedLayoutIdFound = true;
}

change = new ReorderChildrenComponentChange(reorderedIdList);
rootParent = dropParent;
ChangeManager cm = RequestContext.getCurrentInstance().getChangeManager();

// add the change
cm.addComponentChange(FacesContext.getCurrentInstance(),rootParent, change);

// apply the change to the component tree immediately
change.changeComponent(rootParent);

// redraw the shared parent
AdfFacesContext.getCurrentInstance().addPartialTarget(rootParent);

return DnDAction.MOVE;
}
else
{
return DnDAction.NONE;
}
}

5. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「コンポーネント・ドラッグ元」をドラッグし、ページのソース・コンポーネントに子としてドロップします。
たとえば、componentDragSourceタグは次のようになります。

<af:componentDragSource discriminant="col2"/>

36.6 panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加

デフォルトで、panelDashboardコンポーネントではそれ自体の内部でのコンポーネントのドラッグ・アンド・ドロップがサポートされています。つまり、panelDashboardコンポーネントでは、リスナーを実装したり、追加のタグを使用したりする必要なしに、内部のコンポーネントを並べ替えることができます。ただし、panelDashboardコンポーネントにコンポーネントをドラッグ、またはpanelDashboardコンポーネントからコンポーネントをドラッグできるようにする場合は、タグを使用し、リスナーを実装する必要があります。コンポーネントのドラッグ・アンド・ドロップをするため、panelDashboardへのドラッグの際には、componentDragSourceタグを使用します。ただし、panelDashboardではすでにドロップ・ターゲットになることがサポートされているため、dropTargetタグを使用する必要はありません。かわりに、識別値の付いたdataFlavorを使用する必要があります。タグおよび識別値は、フレームワークにそのドロップが外部コンポーネントからのものであることを知らせます。

panelDashboardからのコンポーネントのドラッグは、他のコンポーネントのドラッグ・アンド・ドロップとほとんど同じです。ターゲットにはdropTargetタグを、ソースにはcomponentDragSourceタグを使用します。ただし、dataFlavorタグと識別値も使用する必要があります。

36.6.1 a panelDashboardコンポーネントへのドラッグ・アンド・ドロップ機能の追加方法

panelDashboardコンポーネントには、ダッシュボード内のpanelBoxコンポーネントの並替えに使用するドラッグ・アンド・ドロップ機能が組み込まれているため、dropTargetタグを使用する必要はありませんが、識別値の付いたdataFlavorタグを使用し、dropListenerを実装する必要があります。その実装では、コンポーネントの並替えを処理する必要があります。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.6項「panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

始める前に:

1. panelDashboardコンポーネントを作成します。詳細は、9.8項「ダッシュボードでのコンテンツの配置」を参照してください。

2. panelBoxコンポーネントを含むpanelDashboardの外にもう1つのコンポーネントを作成します。panelBoxコンポーネントの詳細は、9.9.3項「panelBoxコンポーネントの使用方法」を参照してください。

panelDashboardコンポーネントにドラッグ・アンド・ドロップ機能を追加する手順:

1. 構造ウィンドウで、ターゲット・コンポーネントとなる「panelDashboard」コンポーネントを選択します。

2. 「プロパティ」ウィンドウで、「DropListener」に、マネージドBean上でドロップ・イベントを処理するメソッド(このコードはステップ6で作成)として評価される式を入力します。

3. 「コンポーネント」ウィンドウの「ドラッグ・アンド・ドロップ」グループで、「データ・フレーバ」をドラッグし、panelDashboardコンポーネントに子としてドロップします。

4. 「データ・フレーバの挿入」ダイアログで、javax.faces.component.UIComponentを入力します。

5. 「プロパティ」ウィンドウで、Discriminantを、panelDashboardコンポーネントへのドラッグを許可されたコンポーネントを識別する一意の名前(dragIntoDashboardなど)に設定します。

6. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループで、「コンポーネント・ドラッグ元」をドラッグし、ソース・コンポーネントになるpanelBoxコンポーネントの子としてドロップします。

7. 「プロパティ」ウィンドウで、「Discriminant」をステップ5で「panelDashboard」上の「Discriminant」に入力したのと同じ値になるように設定します。

36.6.2 panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の追加方法

panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の実装は、識別値付きのdataFlavorタグを使用する必要があることを除けば、その他のコンポーネントの標準のドラッグ・アンド・ドロップ機能と同様です。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.6項「panelDashboardコンポーネントでのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

panelDashboardコンポーネントからドラッグ・アンド・ドロップ機能を追加する方法:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「ドロップ・ターゲット」をドラッグし、ターゲット・コンポーネントに子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ5で作成)に評価される式を入力し、javax.faces.component.UIComponentを「FlavorClass」として入力します。

3. dropTargetタグを選択した状態のまま、「プロパティ」ウィンドウでaction属性の値としてMOVEを選択します。

4. 構造ウィンドウで、「dataFlavor」タグを選択し、「プロパティ」ウィンドウで、「Discriminant」をこのコンポーネントへのドラッグを許可されたpanelBoxコンポーネントを識別する一意の名前(dragOutOfDashboardなど)に設定します。

5. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

このハンドラ・メソッドでは、DropEventイベントを使用してTransferableオブジェクトとそのデータを取得し、移動を完了して、必要に応じてコンポーネントを並べ替えます。ドロップを完了したら、メソッドではNONEのDnDActionを返します。

dashboardComponent.prepareOptimizedEncodingOfDeletedChild()メソッドを使用して、panelBoxコンポーネントの削除をアニメーション化できます。

例36-8に、デモ・アプリケーションでdashboard JSFページにより使用されるoracle.adfdemo.view.layout.DemoDashboardBean.javaマネージドBeanでのhandleSideBarDropイベント・ハンドラおよびヘルパー・メソッドを示します。

例36-8 panelDashboardからpanelBoxを移動するdropListenerのイベント・ハンドラのコード

public DnDAction handleSideBarDrop(DropEvent e)
{
UIComponent dragComponent = e.getDragComponent();
UIComponent dragParent    = dragComponent.getParent();
// Ensure that the drag source is one of the items from the dashboard:
if (dragParent.equals(_getDashboard()))
{
_minimize(dragComponent);
}
return DnDAction.NONE; // the client is already updated, so no need to redraw it again
}

private void _minimize(UIComponent panelBoxToMinimize)
{
// Make this panelBox non-rendered:
panelBoxToMinimize.setRendered(false);

// If the dashboard is showing, let's perform an optimized render so the whole dashboard doesn't
// have to be re-encoded.
// If the dashboard is hidden (because the panelBox is maximized), we will not do an optimized
// encode since we need to draw the whole thing.
if (_maximizedPanelKey == null)
{
int deleteIndex = 0;
RichPanelDashboard dashboard = _getDashboard();
List<UIComponent> children = dashboard.getChildren();
for (UIComponent child : children)
{
if (child.equals(panelBoxToMinimize))
{
dashboard.prepareOptimizedEncodingOfDeletedChild(
FacesContext.getCurrentInstance(),
deleteIndex);
break;
}
if (child.isRendered())
{
// Only count rendered children since that's all that the panelDashboard can see:
deleteIndex++;
}
}
}
RequestContext rc = RequestContext.getCurrentInstance();
if (_maximizedPanelKey != null)
{
// Exit maximized mode:
_maximizedPanelKey = null;
UIXSwitcher switcher = _getSwitcher();
switcher.setFacetName("restored");
rc.addPartialTarget(switcher);
}
// Redraw the side bar so that we can update the colors of the opened items:
rc.addPartialTarget(_getSideBarContainer());
}

6. 「コンポーネント」ウィンドウで、「操作」パネルから、「コンポーネント・ドラッグ元」を、panelDashboardコンポーネント内のソースとなるpanelBoxコンポーネントの子としてドラッグ・アンド・ドロップします。

7. 「プロパティ」ウィンドウで、「Discriminant」をステップ4でターゲット・コンポーネントのdataFlavorタグ上の「Discriminant」に入力したのと同じ値になるように設定します。

36.7 Calendarへのドラッグ・アンド・ドロップ機能の追加

Calendarには、ユーザーがアクティビティのハンドルをドラッグして終了時間を変更できる機能が含まれています。ただし、ユーザーがアクティビティを別の開始時間、さらには別の日にドラッグ・アンド・ドロップできるようにする場合は、ドラッグ・アンド・ドロップ機能を実装します。ドラッグ・アンド・ドロップを使用すると、アクティビティを移動できるだけでなく、コピーすることもできます。

36.7.1 Calendarへのドラッグ・アンド・ドロップ機能の追加方法

calendarDropTargetタグを使用して、ドラッグ・アンド・ドロップ機能を追加します。コレクションをドラッグ・アンド・ドロップするのと異なり、ソース・タグの必要はなく、アクティビティの移動はターゲット(アクティビティの移動先のオブジェクト、この場合はカレンダ)の役割です。ソース(移動またはコピーされるアイテム)がカレンダ内のアクティビティである場合、calendarDropTargetタグのみを使用します。タグでは、TransferableオブジェクトはCalendarActivityオブジェクトになります。

ただし、Calendarの外からオブジェクトをドラッグ・アンド・ドロップすることもできます。この操作を有効にする場合は、ソース・オブジェクト(calendarActivityオブジェクト以外のオブジェクト)をドロップできるように構成されているdataFlavorタグを使用します。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、36.1.1項「ドラッグ・アンド・ドロップの追加機能」を参照してください。

Calendarにドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルの「ドラッグ・アンド・ドロップ」グループから、「カレンダ・ドロップ・ターゲット」をドラッグし、calendarコンポーネントに子としてドロップします。

2. 「Calendarドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッドに対して評価されるdropListener属性の式を入力します(このコードは手順4で作成)。

3. 「プロパティ」ウィンドウで、「処理」を設定します。この値で、アクティビティ(または他のソース)の移動、コピー、リンクとしてコピー、またはこの3つの任意の組合せを実行できるかどうかが決まります。アクションを指定しない場合、デフォルトはCOPYです。

4. ステップ2でEL式に挿入されたマネージドBeanに、ドロップ・イベントのハンドラを実装します。

このメソッドでは、DropEventイベントをパラメータとして使用し、DnDActionを返す必要があります。DnDActionは、ソースをドロップするときに実行されるアクションです。有効な戻り値は、COPY、MOVEおよびLINKで、ステップ3でactions属性を定義するときに設定されます。このメソッドでは、DropEventを使用してTransferableオブジェクトを取得し、そこからドラッグされたデータ内のCalendarModelオブジェクトにアクセスし、そこから実際のデータのアクセスします。その結果、リスナーではそのデータをソースのモデルに追加してから、実行したDnDAction (DnDAction.COPY、DnDAction.MOVEまたはDnDAction.LINK)を返し、そうでない場合は、DnDAction.NONE返して、ドロップが拒否されたことを示します。

ドロップ・イベントのドロップ・サイトは、oracle.adf.view.rich.dnd.CalendarDropSiteクラスのインスタンスです。Calendarのドラッグ・アンド・ドロップ・ハンドラの例は、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.calendar.rich.DemoCalendarBeanマネージドBeanのhandleDropメソッドを参照してください。

5. アクティビティのソースがカレンダの外部にある場合は、「データ・フレーバ」をドラッグし、子として「calendarDropTarget」タグにドロップします。このタグにより、ターゲットにドロップできるオブジェクトの型(StringやDateオブジェクトなど)が決まります。1つのドロップ・ターゲットに複数のdataFlavorタグを使用し、ドロップ・ターゲットでこれらの型のいずれも受け入れるようにすることができます。

6. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップ可能なオブジェクトのクラス(java.lang.Objectなど)を入力します。

ヒント:

dataFlavorタグに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

36.7.2 Calendarのドラッグ・アンド・ドロップに関する必知事項

Calendar内のドラッグ・アンド・ドロップ・アクティビティの場合、ユーザーは表示内でのみドラッグ・アンド・ドロップを行うことができます。つまり、ユーザーは、日表示内の1つの時間スロットから別の時間スロットにアクティビティをドラッグできますが、日表示からアクティビティを切り取り、月表示に貼り付けることはできません。

ユーザーが日表示または週表示でアクティビティをドラッグ・アンド・ドロップしている場合、Calendarでは30分ごとにドロップ・サイトがマークされます。日表示では、終日のアクティビティまたは複数日のアクティビティは移動できません。

週表示では、終日のアクティビティおよび複数日のアクティビティを移動できますが、その他の終日のスロットにのみドロップできます。つまり、終日のアクティビティを、開始時間と終了時間が設定されているアクティビティには変更できません。月表示では、終日のアクティビティおよび複数日のアクティビティを任意の日に移動できます。

36.8 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加

次のDVTコンポーネントのドラッグ・アンド・ドロップ機能を構成できます。

- バブル・グラフと散布図

- ガント・チャート

- 階層ビューア

- サンバースト

- テーマ・マップ

- 時系列

- ツリーマップ

DVTコンポーネントは基本的に、他のADF Facesコンポーネントのドラッグ・アンド・ドロップと同じプロセスを使用します。ただし、DVTコンポーネントではコンポーネントからドラッグしてドロップできる項目に制約がある場合があります。

オブジェクトまたはコレクションのドラッグ・アンド・ドロップ同様、dropListenerハンドラを実装する必要もあります。ドロップ・イベントのオブジェクトはTransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはTransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。

36.8.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加

DVTバブル・グラフおよび散布図のドラッグ・アンド・ドロップを構成でき、それにより、ユーザーはマーカーを再配置することで、マーカーの値を変更できます。ユーザーがグラフでドラッグ・アンド・ドロップできるようにする場合、dragSourceタグとdropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます(この場合はGraphSelectionSetオブジェクト)。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。

たとえば、bubbleGraphコンポーネントがあり、図36-5で示すように、従業員の職能評定を調整するために、ユーザーが人型のマーカーをドラッグできるようにします。

図36-5 オブジェクトのドラッグ・アンド・ドロップ

bubbleGraphコンポーネントには、dragSourceタグとdropTargetタグの両方が含まれます。また、dataFlavorタグを使用して、ドロップされるオブジェクトの型を決めます。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはTransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはTransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。

36.8.1.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、まずソース・タグとターゲット・タグをグラフに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。実行時の処理の詳細は、36.3.2項「実行時の処理: キーボード修飾子の使用方法」を参照してください。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドロップ・ターゲット」タグをドラッグし、子としてグラフ・コンポーネントにドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ6で作成)に評価される式を入力します。

3. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップできるオブジェクトのクラス、oracle.adf.view.faces.bi.component.graph.GraphSelectionSetを入力します。このエントリは、dataFlavorタグを作成するために使用され、このタグにより、ターゲットにドロップできるオブジェクトの型が決まります。

4. 「プロパティ」ウィンドウで、必要に応じて識別値の値を設定します。識別値は、ターゲットにドロップできるソースを判断するために使用される任意の文字列です。たとえば、どちらもGraphSelectionSetオブジェクトを受け入れるGraphAとGraphBの2つのグラフがあるとします。GraphSelectionSetオブジェクトの2つのソースもあるとします。GraphAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つGraphSelectionSetソースのみが受け入れられます。

5. 構造ウィンドウで、dropTargetタグを選択します。「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY(コピーして貼付け)、MOVE(切り取って貼付け)またはLINK(コピーしてリンクとして貼付け)です。I値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
たとえば、図36-5で人のマーカーを別の値に変更するには、ドロップ・ターゲットの「処理」フィールドはMOVEに設定されます。

6. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」をドラッグし、子としてグラフ・コンポーネントにドロップします。

7. 構造ウィンドウで、dragSourceタグを選択します。「プロパティ」ウィンドウにおいて、「処理」フィールドに、ドラッグ元がサポートする操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しないと、ドラッグ元はCOPYを使用します。dataFlavorタグに設定されているように、必要な識別値を追加します。
たとえば、図36-5で人のマーカーを別の値に変更するには、ドラッグ元の「処理」フィールドはMOVEに設定されます。

8. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)作成します。
このメソッドでは、パラメータとしてDropEventイベントをとり、DnDActionオブジェクトを返す必要があり、これはソースをドロップするときに実行されるアクションです(この例ではDnDAction.MOVE)。このメソッドでは、DropEventイベントをチェックし、ドロップを受け入れるかどうか判断する必要があります。ドロップを受け入れる場合、メソッドではドロップを実行し、実行したDnDActionオブジェクトを返します。そうでない場合は、ドロップが拒否されたことを示すDnDAction.NONEを返します。このメソッドでは、dataFlavorオブジェクトの存在も確認する必要があります(この例ではoracle.adf.view.faces.bi.component.graph.GraphSelectionSet)。

36.8.2 DVTガント・チャートのドラッグ・アンド・ドロップ機能の追加

ユーザーがガント・チャートとその他のコンポーネントとの間でドラッグ・アンド・ドロップできるようにする場合、dragSourceタグとdropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。projectGanttおよびschedulingGanttコンポーネントでは、ドラッグ・アンド・ドロップ機能がサポートされています。

たとえば、図36-6に示すように、projectGanttコンポーネントがあり、ユーザーが時間バケットをtreeTableコンポーネントにドラッグできるようにして、そのコンポーネントに時間バケットについての情報を表示させるとします。

図36-6 オブジェクトのドラッグ・アンド・ドロップ

projectGanttコンポーネントにはdragSourceタグが含まれます。ユーザーは、表示された出力テキストのString値のみでなく、オブジェクト全体をドラッグするため、attributeDropTargetタグのかわりにdropTargetタグを使用します。

また、dataFlavorタグを使用して、ドロップされるオブジェクトの型を決めます。このタグでは、識別値を定義できます。同じオブジェクト型の2つのターゲットと2つのソースがある場合に、これは有用です。識別値を作成することで、各ターゲットで有効なソースのみが受け入れられることが保証されます。たとえば、TaskDragInfoオブジェクトを受け入れるTargetAとTargetBの2つのターゲットがあるとします。TaskDragInfoブジェクトのソースも2つあるとします。TargetAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つTaskDragInfoソースのみが受け入れられます。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはTransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはTransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。

36.8.2.1 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、まず、コンポーネントをドラッグ・アンド・ドロップ・アクションのターゲットとして定義するタグをコンポーネントに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。実行時に行われる処理の詳細は、36.3.2項「実行時の処理: キーボード修飾子の使用方法」を参照してください。clientDropListener属性の使用方法の詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドロップ・ターゲット」タグをドラッグし、子としてターゲット・コンポーネントにドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ6で作成)に評価される式を入力します。

ヒント:

clientDropListener属性を挿入して、クライアントでドロップを捕捉することもできます。詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

3. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップ可能なオブジェクトのクラス(java.lang.Objectなど)を入力します。この選択は、dataFlavorタグを作成するために使用され、このタグにより、ターゲットにドロップできるオブジェクトの型が決まります。1つのドロップ・ターゲットに複数のdataFlavorタグを使用し、ドロップ・ターゲットでこれらの型のいずれも受け入れるようにすることができます。

ヒント:

DataFlavorタグに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

4. 「プロパティ」ウィンドウで、必要に応じて識別値の値を設定します。識別値は、dataFlavorで指定されたタイプのどのソースがソースとして受け入れられるかを判断するために使用される任意の文字列です。

5. 構造ウィンドウで、dropTargetタグを選択します。「プロパティ」ウィンドウで、「処理」の値を選択します。これによって、ドロップ・ターゲットでサポートされるアクションが定義されます。有効な値は、COPY(コピーして貼付け)、MOVE(切り取って貼付け)およびLINK(コピーしてリンクとして貼付け)です。

MOVE COPY

アクションが指定されない場合、デフォルトはCOPYです。

例36-9に、ドロップ・ソースとしてTaskDragInfoオブジェクトをとるdropTargetコンポーネントのコードを示します。actions属性の値としてCOPYが設定されているため、それが許可される唯一のアクションになります。

例36-9 dropTargetタグのJSPコード

<af:treeTable id="treeTableDropTarget"
var="task" value="#{projectGanttDragSource.treeTableModel}">
<f:facet name="nodeStamp">
<af:column headerText="Task Name">
<af:outputText value="#{task.taskName}"/>
</af:column>
</f:facet>
<af:column headerText="Resource">
<af:outputText value="#{task.resourceName}"/>
</af:column>
<af:column headerText="Start Date">
<af:outputText value="#{task.startTime}"/>
</af:column>
<af:column headerText="End Date">
<af:outputText value="#{task.endTime}"/>
</af:column>
<af:dropTarget actions="COPY"
dropListener="#{projectGanttDragSource.onTableDrop}">
<af:dataFlavor flavorClass=
"oracle.adf.view.faces.bi.component.gantt.TaskDragInfo"/>
</af:dropTarget>
</af:treeTable>

6. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)作成します。

このメソッドでは、パラメータとしてDropEventイベントをとり、DnDActionオブジェクトを返す必要があり、これはソースをドロップするときに実行されるアクションです。有効な戻り値は、DnDAction.COPY、DnDAction.MOVEおよびDnDAction.LINKで、ステップ5でターゲット属性を定義したときに設定されたものです。このメソッドでは、DropEventイベントをチェックし、ドロップを受け入れるかどうか判断する必要があります。ドロップを受け入れる場合、メソッドではドロップを実行し、実行したDnDActionオブジェクトを返します。そうでない場合は、ドロップが拒否されたことを示すDnDAction.NONEを返します。

このメソッドでは、各dataFlavorオブジェクトの存在も優先順に確認される必要があります。

ヒント:

ターゲットに複数のdataFlavorオブジェクトが定義されている場合、Transferable.getSuitableTransferData()メソッドを使用できます。このメソッドでは、Transferableオブジェクトで使用可能なTransferDataオブジェクトのListが適合性の高いものから順に返されます。

DataFlavorオブジェクトでは、ドロップされるデータの型(java.lang.Objectなど)が定義されます。これは、手順3で作成したJSPのDataFlavorタグでの定義と同じである必要があります。

ヒント:

DataFlavorオブジェクトに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

DataFlavorオブジェクトではポリモフィズムがサポートされるため、ドロップ・ターゲットでjava.util.Listが受け入れられる場合、Transferableオブジェクトにjava.util.ArrayListを含むドロップは正常終了します。同様に、この機能ではArraysとListsとの間の自動変換もサポートされます。

ドラッグ・アンド・ドロップ・フレームワークで、サーバーのDataFlavorオブジェクトをクライアント・コンポーネントで表す方法がわからない場合、すべてのドロップがクライアントで正常終了するようドロップ・ターゲットが構成されます。

例36-10に、イベント・ペイロードからTaskDragInfoオブジェクトをコピーし、そのイベントを開始したコンポーネントに割り当てるハンドラ・メソッドを示します。

例36-10 dropListenerのイベント・ハンドラ・コード

public DnDAction onTableDrop(DropEvent evt)
{
// retrieve the information about the task dragged
DataFlavor<TaskDragInfo> _flv = DataFlavor.getDataFlavor(TaskDragInfo.class, null);
Transferable _transferable = evt.getTransferable();

// if there is no data in the Transferable, then the drop is unsuccessful
TaskDragInfo _info = _transferable.getData(_flv);
if (_info == null)
return DnDAction.NONE;

// find the task
Task _draggedTask = findTask(_info.getTaskId());
if (_draggedTask != null) {
// process the dragged task here and indicate the drop is successful by returning DnDAction.COPY
return DnDAction.COPY;
}
else
return DnDAction.NONE;
}

7. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」をドラッグし、子としてソース・コンポーネントにドロップします。

8. dragSourceタグを選択している場合、「プロパティ」ウィンドウで、ターゲットに構成される、許容処理と必要な識別値を設定します。

36.8.3 DVT階層ビューア、サンバースト、およびツリーマップにドラッグ・アンド・ドロップ機能を追加する

階層ビューア、サンバースト、およびツリーマップを、ページ上でサポートされたコンポーネント間のドラッグ・アンド・ドロップ操作のドラッグ・ソース、およびドロップ・ターゲットとして構成できます。

36.8.3.1 DVT階層ビューアのドラッグ・アンド・ドロップの例

階層ビューアは、次のドラッグ・アンド・ドロップ操作をサポートします。

- 階層ビューア内で、1つ以上のノードをドラッグ・アンド・ドロップします

- 階層ビューアから1つ以上のノードを別のコンポーネントにドラッグします

- 別のコンポーネントから階層ビューアに1つ以上のアイテムをドラッグします

図36-7に、その中でのドラッグ・アンド・ドロップを可能とするように構成した階層ビューアを示します。ノードをクリックし0.5秒を超えて保持すると、バックグラウンドにドラッグして階層内の別のルートにしたり、別のノードにドラッグしてそのノードの子として追加したりすることができます。

図36-7 ノード・ドラッグを示す階層ビューア

この例では、ノードを別のノードにドラッグすると、ドラッグされたノードとその子は、ターゲット・ノードの子となります。図36-8に、Nina Evansのデータを含むノードへのドラッグの結果を示します。Nancy Greenとその部下は、今はNina Evansの部下として示されます。

図36-8 別のノードへのノード・ドラッグ後の階層ビューア

36.8.3.2 DVTサンバーストのドラッグ・アンド・ドロップの例

サンバーストは、1つ以上のノードの別コンポーネントへのドラッグをサポートします。ドラッグのペイロードは、org.apache.myfaces.trinidad.model.RowKeySetです。サンバーストが別のオブジェクトからのドロップを受け入れるように構成することもできます。

図36-9に、それからaf:outputFormattedコンポーネントへのドラッグを可能とするように構成されたサンバーストを示します。サンバーストが複数選択が可能なように構成されている場合、ユーザーは複数のノードをCtrl+D操作でドラッグできます。

図36-9 ドラッグ・ソースとして構成されたサンバースト

36.8.3.3 DVTツリーマップのドラッグ・アンド・ドロップの例

ツリーマップは、1つ以上のノードの別コンポーネントへのドラッグをサポートします。ドラッグのペイロードは、org.apache.myfaces.trinidad.model.RowKeySetです。ツリーマップが別のオブジェクトからのドロップを受け入れるように構成することもできます。

図36-10に、ドロップ・ターゲットとして構成されたツリーマップを示します。この例では、ドラッグ・ソースはaf:outputFormattedコンポーネントです。

図36-10 ドロップ・ターゲットとして構成されたツリーマップ

36.8.3.4 DVT階層ビューア、サンバースト、またはツリーマップ・コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップの機能を追加するには、第一に、サポート対象のDVTコンポーネントに、ドラッグ・アンド・ドロップ・アクションのターゲットとしてそれを定義しているタグを追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。実行時に行われる処理の詳細は、36.3.2項「実行時の処理: キーボード修飾子の使用方法」を参照してください。clientDropListener属性の使用方法の詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.1項「ドラッグ・アンド・ドロップ機能について」を参照してください。

次のタスクを実行する必要があります。

- DVTコンポーネントをユーザーのページに加えます。
DVTコンポーネント作成時のヘルプについては、第22章「ADFデータ視覚化コンポーネントの概要」を参照してください。

- DVTコンポーネントへのドロップを可能にする予定であれば、ドラッグ・ソースとするコンポーネントをページに加えます。
他のADF Facesコンポーネント追加の詳細は、第1.3項「ADF Facesコンポーネント」を参照してください。

- DVTコンポーネントから別のコンポーネントヘのドラッグを可能にする予定であれば、ドロップ・ターゲットとするコンポーネントをページに加えます。

DVT階層ビューア、サンバースト、あるいはツリーマップ・コンポーネントにドラッグ・アンド・ドロップ機能を追加するには:

1. DVTコンポーネントをドロップ・ターゲットとして構成するには、次を実行します。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドロップ・ターゲット」タグをドラッグし、ドラッグ・アンド・ドロップをサポートするDVTコンポーネントの子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBean上のドロップ・リスナー・メソッド(このコードはステップ6で作成)に評価される式を入力します。

ヒント:

clientDropListener属性を挿入して、クライアントでドロップを捕捉することもできます。詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

3. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップ可能なオブジェクトのクラス(java.lang.Objectなど)を入力します。この選択は、dataFlavorタグを作成するために使用され、このタグにより、ターゲットにドロップできるオブジェクトの型が決まります。1つのドロップ・ターゲットに複数のdataFlavorタグを使用し、ドロップ・ターゲットでこれらの型のいずれも受け入れるようにすることができます。

ヒント:

DataFlavorタグに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

4. 「プロパティ」ウィンドウで、必要に応じて識別値の値を設定します。識別値は、ターゲットにドロップできるソースを判断するために使用される任意の文字列です。たとえば、どちらもjava.lang.Objectを受け入れる2つのツリーマップ、ツリーマップAとツリーマップBがあるとします。ソースも2つあり、どちらもjava.lang.Objectオブジェクトです。GraphAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つjava.lang.Objectソースのみが受け入れられます。

5. 構造ウィンドウで、dropTargetタグを選択します。「プロパティ」ウィンドウで、「処理」の値を選択します。これによって、ドロップ・ターゲットでサポートされるアクションが定義されます。有効な値は、COPY(コピーして貼付け)、MOVE(切り取って貼付け)およびLINK(コピーしてリンクとして貼付け)です。

MOVE COPY

アクションが指定されない場合、デフォルトはCOPYです。

例36-11に、java.lang.Objectをドラッグ・ソースとして受け入れるツリーマップ・コンポーネントのコードを示します。「処理」の値としてCOPYが設定されているため、それが許可される唯一のアクションになります。

例36-11 DVTツリーマップ・コンポーネントのdropTargetタグのJSPコード

<dvt:treemap id="t1" value="#{treemap.censusData}" var="row"
displayLevelsChildren="3" colorLabel="Median Household Income
sizeLabel="Population" summary="Treemap Configured as Drag Source"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}">
<dvt:attributeGroups id="ag1" value="#{row.income > 50000}"
label="#{row.income > 50000 ? 'High Income' : 'Low Income'}"
type="color"/>
</dvt:treemapNode>
<af:dropTarget dropListener="#{treemap.toDropListener}"
actions="COPY">
<af:dataFlavor flavorClass="java.lang.Object"/>
</af:dropTarget>
</dvt:treemap>

6. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)作成します。

このメソッドでは、パラメータとしてDropEventイベントをとり、DnDActionオブジェクトを返す必要があり、これはソースをドロップするときに実行されるアクションです。有効な戻り値は、DnDAction.COPY、DnDAction.MOVEおよびDnDAction.LINKで、ステップ5でターゲット属性を定義したときに設定されたものです。このメソッドでは、DropEventイベントをチェックし、ドロップを受け入れるかどうか判断する必要があります。ドロップを受け入れる場合、メソッドではドロップを実行し、実行したDnDActionオブジェクトを返します。そうでない場合は、ドロップが拒否されたことを示すDnDAction.NONEを返します。

このメソッドでは、各dataFlavorオブジェクトの存在も優先順に確認される必要があります。

ヒント:

ターゲットに複数のdataFlavorオブジェクトが定義されている場合、Transferable.getSuitableTransferData()メソッドを使用できます。このメソッドでは、Transferableオブジェクトで使用可能なTransferDataオブジェクトのListが適合性の高いものから順に返されます。

DataFlavorオブジェクトでは、ドロップされるデータの型(java.lang.Objectなど)が定義されます。これは、手順3で作成したJSPのDataFlavorタグでの定義と同じである必要があります。

ヒント:

DataFlavorオブジェクトに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

DataFlavorオブジェクトではポリモフィズムがサポートされるため、ドロップ・ターゲットでjava.util.Listが受け入れられる場合、Transferableオブジェクトにjava.util.ArrayListを含むドロップは正常終了します。同様に、この機能ではArraysとListsとの間の自動変換もサポートされます。

ドラッグ・アンド・ドロップ・フレームワークで、サーバーのDataFlavorオブジェクトをクライアント・コンポーネントで表す方法がわからない場合、すべてのドロップがクライアントで正常終了するようドロップ・ターゲットが構成されます。

例36-12に、イベント・ペイロードからjava.lang.Objectオブジェクトをコピーして、イベントを開始したコンポーネントに割り当てるハンドラ・メソッドを示します。

例36-12 DVTツリーマップのサンプル・ドロップ・リスナー

// imports needed by methods
import java.util.Map;
import oracle.adf.view.rich.dnd.DnDAction;
import oracle.adf.view.rich.event.DropEvent;
import oracle.adf.view.rich.datatransfer.DataFlavor;
import oracle.adf.view.rich.datatransfer.Transferable;
import org.apache.myfaces.trinidad.context.RequestContext;
import org.apache.myfaces.trinidad.render.ClientRowKeyManager;
import javax.faces.context.FacesContext;
import oracle.adf.view.faces.bi.component.treemap.UITreemap;
import javax.faces.component.UIComponent;
// variables need by methods
private String dragText = "Drag this text onto a node";
// drop listener
public DnDAction toDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<Object> dataFlavor = DataFlavor.getDataFlavor(Object.class);
Object transferableObj = transferable.getData(dataFlavor);
if(transferableObj == null)
return DnDAction.NONE;
// Build up the string that reports the drop information
StringBuilder sb = new StringBuilder();
// Start with the proposed action
sb.append("Drag Operation: ");
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
sb.append("Copy<br>");
}
else if(proposedAction == DnDAction.LINK) {
sb.append("Link<br>");
}
else if(proposedAction == DnDAction.MOVE) {
sb.append("Move<br>");
}
// Then add the rowKeys of the nodes that were dragged
UIComponent dropComponent = event.getDropComponent();
Object dropSite = event.getDropSite();
if(dropSite instanceof Map) {
String clientRowKey = (String) ((Map) dropSite).get("clientRowKey");
Object rowKey = getRowKey(dropComponent, clientRowKey);
if(rowKey != null) {
sb.append("Drop Site: ");
sb.append(getLabel(dropComponent, rowKey));
}
}
// Update the output text
this.dragText = sb.toString();
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return event.getProposedAction();
}

public String getDragText() {
return dragText;
}

private String getLabel(UIComponent component, Object rowKey) {
if(component instanceof UITreemap) {
UITreemap treemap = (UITreemap) component;
TreeNode rowData = (TreeNode) treemap.getRowData(rowKey);
return rowData.getText();
}
return null;
}

private Object getRowKey(UIComponent component, String clientRowKey) {
if(component instanceof UITreemap) {
UITreemap treemap = (UITreemap) component;
ClientRowKeyManager crkm = treemap.getClientRowKeyManager();
return crkm.getRowKey(FacesContext.getCurrentInstance(), component, clientRowKey);
}
return null;
}

2. DVTコンポーネントをドラッグ・ソースとして構成するには、次を実行します。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」をドラッグし、子としてDVTコンポーネントにドロップします。

2. dragSourceタグを選択している場合、「プロパティ」ウィンドウで、ターゲットに構成される、許容処理と必要な識別値を設定します。

例36-13に、ドラッグ・ソースとして構成された、ツリーマップのJSPコードを示します。すべてのアクション(COPY、MOVEおよびLINK)が許されることに注意します。

例36-13 DVTツリーマップのdragSourceタグのJSPサンプル・コード

<dvt:treemap id="t1" value="#{treemap.censusData}" var="row"
displayLevelsChildren="3" colorLabel="Median Household Income
sizeLabel="Population" summary="Treemap Configured as Drag Source"
legendSource="ag1">
<dvt:treemapNode id="tn1" value="#{row.size}" label="#{row.text}">
<dvt:attributeGroups id="ag1" value="#{row.income > 50000}"
label="#{row.income > 50000 ? 'High Income' : 'Low Income'}"
type="color"/>
</dvt:treemapNode>
<af:dragSource defaultAction="MOVE" actions="COPY MOVE LINK"/>
</dvt:treemap>

3. DVTコンポーネントを別のコンポーネントからのドラッグを可能とするドロップ・ターゲットとして使用するには、「コンポーネント」ウィンドウで、「操作」パネルから「ドラッグ元」を、ドラッグのソースとなるコンポーネントの子としてドラッグ・アンド・ドロップします。
たとえば、ドラッグ元をaf:outputFormattedコンポーネントの子としてドラッグ・アンド・ドロップし、ツリーマップに関するノード情報を表示します。dragSourceタグを選択している場合、「プロパティ」ウィンドウで、許容処理とターゲットに必要な識別値を設定します。

4. DVTコンポーネントを別のサポートされたDVTやADF Facesのコンポーネントのドラッグ・ソースとして追加するには、以下を実行します。

1. 「コンポーネント」ウィンドウで、「Operations」パネルから、「ドロップ・ターゲット」を、ドロップを受け取るコンポーネント上にドラッグ・アンド・ドロップします。
たとえば、ドロップ・ターゲットをツリー表コンポーネント上にドラッグ・アンド・ドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、コンポーネントがDVTコンポーネントのドロップへの対応に使用するドロップ・リスナーの名前を入れます。
サンプルのリスナーについては、この章の例を参照してください。

3. 「データ・フレーバの挿入」ダイアログで、ドロップ・ターゲットが受け入れるオブジェクトを入れます。または、ドロップダウン・メニューを使用してオブジェクトの階層をナビゲートし、希望するオブジェクトを選択します。
たとえば、ユーザーがツリーマップ・ノードをtreeTableコンポーネントにドラッグし、そのコンポーネントにツリーマップについての情報を表示できるようにする場合、org.apache.myfaces.trinidad.model.RowKeySetをデータ・フレーバに入れます。

4. 構造ウィンドウでaf:dropTargetコンポーネントを右クリックし、「プロパティに移動」を選択します。

5. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。許容値は、COPY、MOVEまたはLINKです。I値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。
例36-14に、ツリーマップからのドラッグを可能なように構成したaf:outputFormattedコンポーネントのサンプル・コードを示します。

例36-14 ツリーマップからaf:outputFormattedコンポーネントへデータをドラッグするJSPサンプル・コード

<af:outputFormatted value="#{treemap.dropText}" id="of1">
<af:dropTarget dropListener="#{treemap.fromDropListener}">
<af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"/>
</af:dropTarget>
</af:outputFormatted>

36.8.4 時系列コンポーネントのドラッグ・アンド・ドロップ機能の追加

時系列は、ページ上のコレクション・コンポーネントとの間のドロップ・ターゲットまたはドラッグ元として構成できます。たとえば、1つのコレクションからアイテム(表の行など)をドラッグして時系列にドロップしたり、時系列からイベントをドラッグして表にドロップしたりできます。

図36-11に、時系列内のイベントと表の行との間でドラッグ・アンド・ドロップができるように構成された時系列を示します。

図36-11 表との間のドラッグ・アンド・ドロップ用に構成された時系列

ドラッグ・アンド・ドロップの機能を追加するには、第一に、サポート対象のDVTコンポーネントに、ドラッグ・アンド・ドロップ・アクションのターゲットとしてそれを定義しているタグを追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。実行時に行われる処理の詳細は、36.3.2項「実行時の処理: キーボード修飾子の使用方法」を参照してください。clientDropListener属性の使用方法の詳細は、36.3.3項「ClientDropListenerの使用に関する必知事項」を参照してください。

始める前に:

ドラッグ・アンド・ドロップ機能について理解しておくと役立ちます。詳細は、36.1項「ドラッグ・アンド・ドロップ機能について」を参照してください。

次のタスクを実行する必要があります。

- DVTコンポーネントをユーザーのページに加えます。
DVTコンポーネント作成時のヘルプについては、第22章「ADFデータ視覚化コンポーネントの概要」を参照してください。

- DVTコンポーネントへのドロップを可能にする予定であれば、ドラッグ・ソースとするコンポーネントをページに加えます。
他のADF Facesコンポーネント追加の詳細は、第1.3項「ADF Facesコンポーネント」を参照してください。

- DVTコンポーネントから別のコンポーネントヘのドラッグを可能にする予定であれば、ドロップ・ターゲットとするコンポーネントをページに加えます。

時系列にドラッグ・アンド・ドロップ・サポートを追加するには:

1. 構造ウィンドウでtimelineコンポーネントを右クリックして、「時系列の中に挿入」→「ドロップ・ターゲット」と選択します。

2. 「ドロップ・ターゲットの挿入」ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して「編集」を選択し、時系列のマネージドBeanにドロップ・リスナー・メソッドを追加します。または、ドロップダウン・メニューを使用して式ビルダーを選び、ドロップ・リスナーのEL式を入力してください。
たとえば、dndというマネージドBeanにhandleDropOnTimeline()というメソッドを追加するには、「編集」を選択し、ドロップダウン・メニューから「dnd」を選択して、「メソッド」フィールドの右にある「新規」をクリックし、handleDropOnTimeline()メソッドを作成します。

例36-15に、図36-11に表示されている時系列のサンプル・ドロップ・リスナーと、それをサポートするメソッドを示します。

例36-15 時系列のサンプル・ドロップ・リスナー

// imports needed by methods
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.SessionScoped;
import javax.faces.bean.RequestScoped;
import oracle.adf.view.rich.datatransfer.DataFlavor;
import oracle.adf.view.rich.datatransfer.Transferable;
import oracle.adf.view.rich.dnd.DnDAction;
import oracle.adf.view.rich.event.DropEvent;
import org.apache.myfaces.trinidad.context.RequestContext;
import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.ModelUtils;
import org.apache.myfaces.trinidad.model.RowKeySet;
// drop listener
public DnDAction handleDropOnTimeline(DropEvent event)
{
Date _date = (Date)event.getDropSite();
Transferable _transferable = event.getTransferable();
RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR);
Object _rowKey = _rowKeySet.iterator().next();
EmpEvent _event = (EmpEvent)m_tableModel.getRowData(_rowKey);
_event.setDate(_date);
orderInsert(_event);
RequestContext.getCurrentInstance().addPartialTarget
(event.getDragComponent());
return DnDAction.COPY;
}
private void orderInsert(EmpEvent event)
{
int _index = -1;
ArrayList _list = (ArrayList)m_timelineModel.getWrappedData();
for (int i=0; i<_list.size(); i++)
{
EmpEvent _current = (EmpEvent)_list.get(i);
if (event.getDate().before(_current.getDate()))
{
_index = i;
break;
}
}
if (_index == -1)
_list.add(event);
else
_list.add(_index, event);
ArrayList _list2 = (ArrayList)m_tableModel.getWrappedData();
_list2.remove(event);
}

3. 「OK」をクリックし、「データ・フレーバの挿入」ダイアログに、org.apache.myfaces.trinidad.model.RowKeySetを入力します。

4. 構造ウィンドウでaf:dropTargetコンポーネントを右クリックし、「プロパティに移動」を選択して、「プロパティ」ウィンドウで次の属性を設定します。

- Actions: ドロップ・ターゲットが受け入れる操作をスペース区切りのリストで入力します。許容値は、COPY、MOVEまたはLINKです。値を指定しない場合、ドロップ・ターゲットはCOPYを使用します。

- Discriminant: ドロップ・ターゲットとドラッグ元が互換性のために共有するモデル名を指定します。この属性の値は、時系列からドラッグを受けるコレクション・コンポーネントに設定する、af:dragSourceコンポーネントのdiscriminant属性の値に一致する必要があります。

5. 別のコレクション・コンポーネントを時系列へのドロップのドラッグ元として構成するには、次のようにします。

1. 「コンポーネント」ウィンドウで、「操作」パネルから、「ドラッグ元」タグをドラッグのソースとなるコンポーネントの子としてドラッグ・アンド・ドロップします。
たとえば、「ドラッグ元」のタグをaf:tableコンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「プロパティ」ウィンドウで、コンポーネントの「Actions」フィールドに、ドロップ・ターゲットが受け入れる操作をスペース区切りのリストで入力します。

3. コンポーネントの「Discriminant」フィールドに、ドロップ・ターゲットとドラッグ元が互換性のために共有するモデル名を指定します。

6. 時系列をドラッグ元として構成するには、「コンポーネント」ウィンドウの「操作」パネルから、「ドラッグ元」のタグを時系列の子としてドラッグ・アンド・ドロップします。

7. 構造ウィンドウでaf:dragSourceコンポーネントを右クリックし、「プロパティに移動」を選択して、「プロパティ」ウィンドウで次の属性を設定します。

- Actions: コレクション・ドロップ・ターゲット・コンポーネントが受け入れる操作をスペース区切りのリストで入力します。

- Discriminant: ドラッグ元とコレクション・ドロップ・ターゲットが互換性のために共有するモデル名を指定します。この属性の値は、時系列からドラッグを受けるコレクション・コンポーネントに設定する、af:collectionDropTargetコンポーネントのmodelName属性の値に一致する必要があります。

8. 別のコレクション・コンポーネントを時系列からのドロップのドロップ・ターゲットとして構成するには、次のようにします。

1. 「コンポーネント」ウィンドウの「操作」パネルで、「コレクション・ドロップ・ターゲット」を、ドロップを受けるコンポーネントにドラッグ・アンド・ドロップします。
たとえば、「コレクション・ドロップ・ターゲット」を、ドロップの結果を表示するaf:tableコンポーネントの子としてドラッグ・アンド・ドロップします。

2. ドロップ・ターゲットを挿入ダイアログで、ドロップ・リスナーの名前を入力するか、ドロップダウン・メニューを使用して編集を選び、ドロップ・リスナー・メソッドを適切なマネージドBeanに追加してください。
例36-16に、図36-11に表示されている時系列のサンプル・ドロップ・リスナーを示します。この例は例36-15で使用されたものと同じインポートとヘルパー・メソッドを使用しており、それらはここには含まれていません。

例36-16 時系列をドラッグ元として使用する表のサンプル・ドロップ・リスナー

//Drop Listener
public DnDAction handleDropOnTable(DropEvent event)
{
Integer _dropSite = (Integer)event.getDropSite();
Transferable _transferable = event.getTransferable();
RowKeySet _rowKeySet = _transferable.getData(DataFlavor.ROW_KEY_SET_FLAVOR);
Object _rowKey = _rowKeySet.iterator().next();
EmpEvent _event = (EmpEvent)m_timelineModel.getRowData(_rowKey);
ArrayList _list = (ArrayList)m_tableModel.getWrappedData();
_list.add(_dropSite.intValue(), _event);
ArrayList _list2 = (ArrayList)m_timelineModel.getWrappedData();
_list2.remove(_event);
RequestContext.getCurrentInstance().addPartialTarget
(event.getDragComponent());
return DnDAction.COPY;
}
private static Date parseDate(String date)
{
Date ret = null;
try
{
ret = s_format.parse(date);
}
catch (ParseException e)
{
e.printStackTrace();
}
return ret;
}

3. 「OK」をクリックし、「データ・フレーバの挿入」ダイアログに、org.apache.myfaces.trinidad.model.RowKeySetを入力します。

4. 構造ウィンドウでaf:dropTargetコンポーネントを右クリックし、「プロパティに移動」を選択します。

5. 「プロパティ」ウィンドウにおいて、「アクション」フィールドに、ドロップ・ターゲットが受け入れる操作のリストを、空白で区切って入力します。

6. 「ModelName」フィールドに、コレクションのモデルを定義します。modelName属性の値は、互換性の目的でドラッグ元の特定に使用されるStringオブジェクトです。この属性の値は、af:dragSourceコンポーネントのdiscriminant属性の値に一致する必要があります。

例36-17に、図36-11に示すADF Facesデモ・アプリケーションのJSFページのサンプル・コードを示します。af:tableコンポーネントの詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

例36-17 時系列のドロップ・ターゲットとドラッグ元のサンプル・コード

<dvt:timeline id="tl1" startTime="2010-01-01" endTime="2011-12-31"
inlineStyle="width:800px;height:400px" itemSelection="single">
<f:attribute name="horizontalFetchSizeOverride" value="3000"/>
<dvt:timelineSeries id="ts1" var="evt" value="#{dnd.timelineModel}">
<dvt:timelineItem id="ti1" value="#{evt.date}" group="#{evt.group}">
<af:panelGroupLayout id="pg1" layout="horizontal">
<af:image id="img1" inlineStyle="width:30px;height:30px"
source="/resources/images/timeline/employment.png"/>
<af:spacer width="3"/>
<af:panelGroupLayout id="pg2" layout="vertical">
<af:outputText id="ot1" inlineStyle="color:#084B8A"
value="#{evt.description}" noWrap="true"/>
<af:outputText id="ot2" value="#{evt.date}"
inlineStyle="color:#6e6e6e" noWrap="true">
<af:convertDateTime dateStyle="medium"/>
</af:outputText>
</af:panelGroupLayout>
</af:panelGroupLayout>
</dvt:timelineItem>
<af:dragSource actions="COPY" discriminant="model"/>
<af:dropTarget actions="COPY" dropListener="#{dnd.handleDropOnTimeline}">
<af:dataFlavor flavorClass="org.apache.myfaces.trinidad.model.RowKeySet"
discriminant="model2"/>
</af:dropTarget>
</dvt:timelineSeries>
<dvt:timeAxis id="ta1" scale="weeks"/>
<dvt:timelineOverview id="ov1">
<dvt:timeAxis id="ta2" scale="years"/>
</dvt:timelineOverview
</dvt:timeline>
<af:table var="row" value="#{dnd.tableModel}" rowSelection="single"
inlineStyle="width:370px;height:400px">
<af:column headerText="ID" width="20">
<af:outputText value="#{row.id}"/>
</af:column>
<af:column headerText="Event" width="340">
<af:outputText value="#{row.description}"/>
</af:column>
<af:dragSource actions="COPY" discriminant="model2"/>
<af:collectionDropTarget actions="COPY" modelName="model"
dropListener="#{dnd.handleDropOnTable}"/>
</af:table>

37 異なる出力モードの使用方法

この章では、印刷や電子メールに適したモードでページを表示するためのADF Facesの使用方法ついて説明します。トピックには、showPrintablePageBehaviorタグを使用してページを印刷する方法および要求パラメータorg.apache.myfaces.trinidad.agent.email=trueを使用して電子メール送信可能なページを作成する方法が含まれます。

この章では、次の項目について説明します。

- 37.1項「異なる出力モードの使用方法について」

- 37.2項「印刷用のページの表示」

- 37.3項「電子メール送信可能なページの作成」

37.1 異なる出力モードの使用方法について

ADF Facesでは、ページを印刷または電子メール用に簡略化されたモードで出力できます。たとえば、ユーザーがページ(またはページの一部)を印刷できるようにし、ただしWebブラウザでレンダリングされているとおりにページを印刷するのではなく、スクロール・バーやボタンなど、印刷ページに必要ないアイテムを削除することができます。ページが電子メールで送信される場合は、電子メール・クライアントが正しく表示できるようにページを簡略化する必要があります。

注意:

デフォルトでは、ADF Facesフレームワークによりアプリケーションが検索エンジンによってクロール中であると検出されると、クローラ用に電子メール用のページに似た簡略化された形式でページが出力されます。Web Crawlerの専用コンテンツを生成する場合、ELでアクセス可能なAgentインタフェースを使用して、サイトをクロール中であるエージェントを検出し、次のように指定したリンクへエージェンを転送します。

<c:if test="#{requestContext.agent.type ==  'webcrawler'}">
<af:link text="This Link is rendered only for web crawlers"
destination="http://www.newPage.com"/>
</c:if>

詳細は、『Trinidad Javadoc』を参照してください。

印刷可能なページを表示するために、ADF FacesにはshowPrintablePageBehaviorタグがあり、コマンド・コンポーネントとともに使用すると、ユーザーはブラウザに簡略バージョンのビューを表示して、それを印刷できます。

メールに対応する場合、ADF Facesでは、Microsoft Outlook 2007、Mozilla Thunderbird 10.0.5、あるいはGmail電子メール・クライアントのいずれかの表示に適したページへの変換に使用できるAPIが提供されます。

ヒント:

現行の出力モード(emailまたはprintable)には、AdfFacesContextから入ることができます。このコンテキストはELでアクセスできるため、ELを使用してJSPページの出力モードにバインドできます。たとえば、次の式を使用して、現行モードがemailでない場合にのみ、図がレンダリングされるようにします。

<af:activeImage source="/images/stockChart.gif" rendered="#{adfFacesContext.outputMode != "email"}"/>

現行モードはAdfFacesContext.getOutputMode()を使用して確認できます。

37.1.1 出力モードのユースケース

大分部のWebページは、印刷または電子メールに適していませんが、ユーザーにはその機能が必要な場合があります。たとえば、File Explorerアプリケーションでは、buttonコンポーネントを、図37-1に示すように、表が含まれているpanelCollectionコンポーネントのツールバー内に配置できます。

図37-1 ページの一部を印刷するためのボタン

ユーザーがボタンをクリックすると、ページが新規のウィンドウ(ブラウザによってはタブ)に、図37-2のように簡略化された形で表示されます。

図37-2 ページの印刷可能なバージョン

表の内容のみが印刷用に表示されます。タブ、ツールバー、スクロール・バーなどの関係ないコンポーネントはすべてレンダリングされません。

アプリケーション内のページを電子メールで送信することが必要になる場合があります。たとえば、Web上で作成された注文書は、多くの場合、セッションの最後に購入者に電子メールで送信されます。しかし、電子メール・クライアントでWebブラウザへのレンダリングに使用される外部スタイルシートがサポートされていないために、正しくレンダリングされないという理由で、同じページを電子メールで送信できません。

図37-3に示すように、発注書が表示されたページがあるとします。

図37-3 発注書のWebページ

ユーザーが上部の「電子メール可能なページ」リンクをクリックすると、actionListenerメソッドまたは別のサービスによりorg.apache.myfaces.trinidad.agent.email=trueが現行のURLに追加され、ページが電子メールで送信されます。図37-4に、メール・クライアントに表示されるページを示します。

図37-4 メール・クライアントのページ

37.2 印刷用ページの表示

ADF Facesフレームワークを使用すると、showPrintablePageBehaviorタグをコマンド・コンポーネントの子として置く場合に、印刷に適したバージョンのページを印刷できます。クリックすると、フレームワークは、printableBehaviorタグに対する親のコンポーネントから始まるコンポーネント・ツリーを、panelSplitter、panelAccordionまたはpopupコンポーネント、あるいはツリーのルート(いずれか早い方)に到達するまで上っていきます。ツリーはそこからレンダリングされます。さらに、印刷バージョンに必要のない一部のコンポーネント(ボタン、タブ、スクロールバーなど)は省略されます。

コマンド・コンポーネントがクリックされると、アクション・イベントは取り消されます。かわりに、サーバーに対して、ページの印刷可能なバージョンが要求されます。

37.2.1 showPrintablePageBehaviorタグの使用方法

showPrintablePageBehaviorタグは、コマンド・コンポーネントの直接の子として使用されます。

始める前に:

コンポーネントが印刷送信可能なページでどのように表示されるかについて理解しておくと役立ちます。詳細は、37.2項「印刷用のページの表示」を参照してください。

showPrintablePageBehaviorタグを使用する手順:

1. レイアウト・コンポーネントのいずれかで、印刷するコンテンツを含むファセットにコマンド・コンポーネントを追加します。手順の詳細は、20.3.1項「ボタンおよびリンクをナビゲーションとActionEventの配信に使用する方法」を参照してください。

注意:

ユーザーがページ全体を印刷できるようにレイアウト・コンポーネントの外にshowPrintablePageBehaviorコンポーネントを挿入できますが、印刷結果がレイアウトとおおまかにしか一致せず、一部のコンテンツが表示されない場合があります。そのため、ユーザーがファセットの全コンテンツを印刷できるようにするには、ユーザーが通常印刷するコンテンツを含むファセットにコマンド・コンポーネントとshowPrintablePageBehaviorコンポーネントを配置することが重要です。複数のファセットで印刷をサポートする必要がある場合は、各ファセットにコマンド・コンポーネントを1つとshowPrintablePageBehaviorタグを挿入します。すべてのコンテンツを印刷するには、ユーザーは一度に1つのファセットで印刷コマンドを実行する必要があります。

2. 「コンポーネント」ウィンドウで、「操作」パネルから、「印刷可能なページの表示動作」をドラッグし、子としてコマンド・コンポーネントにドロップします。

37.3 電子メール送信可能なページの作成

アプリケーション内のページを電子メールで送信することが必要になる場合があります。たとえば、Web上で作成された注文書は、多くの場合、セッションの最後に購入者に電子メールで送信されます。しかし、電子メール・クライアントでWebブラウザへのレンダリングに使用される外部スタイルシートがサポートされていないために、正しくレンダリングされないという理由で、同じページを電子メールで送信できません。

ADF Facesフレームワークでは、JSFページの自動変換が行われるため、Microsoft Outlook 2007、Mozilla Thunderbird 10.0.5、およびGmailメール・クライアントで正しくレンダリングされます。

すべてのコンポーネントが電子メール・クライアントでレンダリングできるとはかぎりません。次のコンポーネントは変換できるため、電子メール・クライアントで正しくレンダリングできます。

- document

- panelHeader

- panelFormLayout

- panelGroupLayout

- panelList

- spacer

- showDetailHeader

- inputText (readOnlyとしてレンダリング)

- inputComboBoxListOfValues (readOnlyとしてレンダリング)

- inputNumberSlider (readOnlyとしてレンダリング)

- inputNumberSpinbox (readOnlyとしてレンダリング)

- inputRangeSlider (readOnlyとしてレンダリング)

- outputText

- selectOneChoice (readOnlyとしてレンダリング)

- panelLabelAndMessage

- image

- tree

- table

- treeTable

- column

- link(テキストとしてレンダリング)

電子メール送信可能なページでは、table内のすべての行とtreeTable内のすべてのノードは、各ノードがページ内で制限まで展開された状態でレンダリングされます。表示するデフォルトの行数は50です。ビュー・オブジェクトが取得する行数の最大値は、データ・レイヤー(MaxFetchSizeプロパティで)、あるいはアプリケーション・レイヤー(adf-config.xmlに指定されるrowLimitプロパティで)によって制限されます。rowLimitプロパティは、アプリケーション内のすべてのビュー・オブジェクト問合せのグローバルな上限です。MaxFetchSizeが指定された場合、そのビュー・オブジェクトについてはrowLimitは無視されます。電子メール送信可能なページでは、表示する行数の最大値を表属性rowsを使用して指定することもできます。rowsの値は、MaxFetchSizeまたはrowLimitの定義された値より小さい場合のみ使用されます。treeおよびtreeTableでは、nonScrollableRowsを使用して表示する行数を制限します。

37.3.1 電子メール送信可能なページの作成方法

電子メールで送信されるページのURLにリクエスト・パラメータに追加することにより、ADF Facesフレームワークに対して、ページを電子メール・クライアントでレンダリングするために変換することを通知します。

始める前に:

コンポーネントが電子メール送信可能なページでどのように表示されるかについて理解しておくと役立ちます。詳細は、37.3項「電子メール送信可能なページの作成」

電子メール送信可能なページを作成する手順:

1. 電子メールで送信するページにコマンド・コンポーネントを挿入します。詳細は、第20章「ナビゲーション・コンポーネントの使用」を参照してください。

2. マネージドBeanで、現行のURLにorg.apache.myfaces.trinidad.agent.email=trueを追加し、ページを電子メールで送信するactionListenerメソッドまたは別のサービスを作成します。

ヒント:

メールをオフラインで表示できるようにするには、次のリクエスト・パラメータを、メール送信するページのURLに追加します。

org.apache.myfaces.trinidad.agent.email=true&oracle.adf.view.rich.render.emailContentType=multipart/related

フレームワークは、HTMLをMIME (multipart/related)に変換し、メールがオフラインで表示されるようにイメージを埋め込みます。

3. コマンド・コンポーネントを選択し、「プロパティ」ウィンドウで、「ActionListener」の値としてメソッドまたはサービスを設定します。

37.3.2 電子メール・クライアントでのページのレンダリングのテスト方法

ページの開発を完了する前に、電子メール・クライアントでページがどのようにレンダリングされるかをテストすることもできます。これはButtonコンポーネントを使用すれば簡単にできます。

電子メール送信可能なページをテストする手順:

1. 「コンポーネント」ウィンドウで、「一般コントロール」パネルから、「ボタン」をページ上のどこかにドラッグ・アンド・ドロップします。

2. 「設計」タブで「ボタン」を右クリックし、次に「共通」セクションで「宛先」をページの名前にorg.apache.myfaces.trinidad.agent.email=trueを足したものに設定します。
たとえば、ページの名前がmyPageの場合、宛先属性の値は次のようになります。

myPage.jspx?org.apache.myfaces.trinidad.agent.email=true

図37-5 宛先属性の設定

3. ページを右クリックし、「実行」を選択して、デフォルトのブラウザでページを実行します。
アプリケーションを初めて実行し、新しいドメインを統合WebLogic Serverで開始する際に、「デフォルト・ドメインの作成」ダイアログが表示されます。ダイアログを使用して新しいドメインの管理者パスワードを定義します。入力するパスワードは8文字以上の長さで、アルファベット以外の文字を1つ以上使用する必要があります。

4. ブラウザでページが表示されたら、ページに追加した「ボタン」をクリックします。これでブラウザに再びページが表示されますが、電子メール・クライアントで処理できるページに変換されています。

5. ブラウザで、ページのソースを表示します。たとえば、Mozilla Firefoxでは、「表示」→「ページのソース」を選択します。ソース全体を選択してコピーします。

6. 電子メール・クライアントで新規メッセージを作成します。ページのソースをメッセージに貼り付け、それを自分宛てに送信します。

ヒント:

HTMLコードを貼り付けているので、電子メール本体にそのHTMLを挿入するための挿入コマンドを使用することが必要になります。たとえば、Thunderbirdでは、「挿入」→「HTML」を選択します。

7. 必要に応じて、特にページの電子メール・バージョン用に、エージェントを使用してスキンを作成します。例37-1に、電子メールでレンダリングされる表の枠線をどのように指定するかを示しています。

例37-1 電子メール送信可能なページのスキン

af|table {
border: 1px solid #636661;
}

@agent email {
af|table
{border:none}
}

af|table::column-resize-indicator {
border-right: 2px dashed #979991;
}

スキンの作成の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

37.3.3 実行時の処理: ADF FacesでJSFページがどのようにして電子メール送信可能なページに変換されるか

ADF Facesフレームワークがレンダー・レスポンス・フェーズでリクエスト・パラメータorg.apache.myfaces.trinidad.agent.email=trueを受信する場合、関連するフェーズ・リスナーは、フレームワークに次の操作の実行を通知する内部フラグを設定します。

- HTMLからすべてのJavaScriptを削除します。

- ページにすべてのCSSを追加しますが、ページに含まれているコンポーネントに対してのみです。

- HTMLからCSSリンクを削除します。

- すべての相対リンクを絶対リンクに変換します。

- 絶対URLを持つイメージをレンダリングします。

また、パラメータoracle.adf.view.rich.render.emailContentType=multipart/relatedを追加する場合、フレームワークは、HTMLからMIME (multipart/related)に変換し、メールがオフラインで表示されるようにイメージを埋め込みます。リクエスト・パラメータは全体で次のようになります。

org.apache.myfaces.trinidad.agent.email=true&oracle.adf.view.rich.render.emailContentType=multipart/related

38 非同期バックエンドでのアクティブ・データ・サービスの使用方法

この章では、ADF Facesコンポーネントに対してリアルタイムのデータ更新を行うために、アクティブ・データ・サービス(ADS)に非同期バックエンドを登録する方法を説明します。

この章では、次の項目について説明します。

- 38.1項「アクティブ・データ・サービスについて」

- 38.2項「アクティブ・データ・サービスを使用するためのプロセスの概要」

- 38.3項「マネージドBeanでのActiveModelインタフェースの実装」

- 38.4項「読取り一貫性の維持に関する必知事項」

- 38.5項「アクティブ・データ・サービスへのイベント渡し」

- 38.6項「データ更新イベント・リスナーの登録」

- 38.7項「アクティブ・データを表示するためのADFコンポーネントの構成」

38.1 アクティブ・データ・サービスについて

Fusionテクノロジ・スタックには、アクティブ・データ・サービス(ADS)が含まれ、これはサーバー側のプッシュ・フレームワークで、これによりADF Facesコンポーネントのリアルタイムのデータ更新を提供できます。ADF Facesコンポーネントをデータ・ソースにバインドすると、ADSでは、ブラウザ・クライアントに明示的な更新リクエストを要求することなく、ブラウザ・クライアントにデータ更新をプッシュします。たとえば、ADFデータ・コントロールの属性にバインドされた表があり、その属性値はサーバー上で定期的に変化するため、表には更新された値が表示されるようにします。ActiveModelインタフェースを実装し、バックエンドからコンポーネントにデータ・イベントを通知するためのイベント・リスナーとして登録すると、変更されたデータが、図38-1に示すように、強調表示された新規の値でコンポーネントにより再レンダリングされます。

図38-1 更新されたデータを強調表示で示す表

38.1.1 アクティブ・データ・サービスのユースケースおよび例

ADSの使用は、自動部分ページ・レンダリング(PPR)の使用にかわる方法で、ADF FacesコンポーネントにバインドされたADFデータ・コントロールに関連付けられているビジネス・ロジックの結果として、バックエンドで変化するデータを再レンダリングします。自動PPRではサーバーにリクエストを送信する必要があるのに対し(通常はユーザーによって開始される)、ADSでは、サーバーにデータが到着すると、変更されたデータがデータ・ストアからプッシュされるようにします。また、PPRに対して、ADSでは、コンポーネントによりコンポーネント全体ではなく、変更されたデータのみを再レンダリングするようにできます。これにより、アプリケーションが定期的に変化するデータに対処する必要があるという場合には、ADSは理想的です。

この機能を使用するには、ADSを使用するようにアプリケーションを構成する必要があります。アプリケーション・サービスでADSがサポートされていない場合、ソースのデータが更新されたらコンポーネントでそれを表示できるように、サービスのプロキシを作成する必要もあります。

どのADF FacesページでもADSを使用できます。ただし、アクティブ・データを処理するように構成できるのは、次のADF Facesコンポーネントのみです。

- activeImage

- activeOutputText

- table
アクティブ・データが使用される表はサポートされないことに注意してください。表が実行時にフィルタ処理されると、アクティブ・データは表示できません。現在のところ、ADSでは、outputTextコンポーネントが列に含まれたtableコンポーネントをサポートしていますが、他のコンポーネントは表の列内でサポートされていません。

- tree

- treeTable

- 22.2.3項「アクティブ・データ・サポート」で特定される、graph、gauge、mapPointTheme、pivotTable、pivotFilterBar、sunburstおよびtreemapの各ADFデータ視覚化コンポーネント
ADSは、すべてのグラフ・コンポーネント・タイプに対してアクティブ・データをサポートするわけではありません。サポートされるグラフ・タイプのリストについては、23.6.1項「アクティブ・データを表示するグラフ・コンポーネントの構成方法」を参照してください。

アクティブ・データ・サービス・フレームワークと構成に関する重要な情報の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

38.2 アクティブ・データ・サービスを使用するためのプロセスの概要

ADSを使用するために、必要に応じてアプリケーションを構成して、データ転送の方法やその他のパフォーマンス・オプションを決定することができます。

始める前に:

次のタスクを実行します。

- アクティブ・データ・イベントをデータ・ソースから非同期で起動するロジックを実装します。たとえば、このロジックは、データベースを更新するビジネス・プロセスや、JMSから通知されるJMSクライアントです。

- アクティブ・データ・フレームワークでは複雑なビジネス・ロジック、またはユーザー・プロファイルやセキュリティなどのADFランタイム・コンテキストが必要な変換はサポートしません。たとえば、フレームワークではADFコンテキスト・ロケール依存の値を変換し、ロケール固有の値を返すことはできません。かわりに、データ変更イベントを発行する前に、データ・ソースにこれを処理させる必要があります。

- ユーザーがADF Facesページをアプリケーション用に構成されたADSで実行できるようになるには、その前にWebブラウザのポップアップ・ブロッカを無効にする必要があります。ポップアップ・ブロッカが有効になっているWebブラウザでは、アクティブ・データはサポートされません。

アクティブ・データ・サービスを使用する手順:

1. 必要に応じて、データ転送モードを決定し、待機しきい値や再接続情報など、その他の構成も設定するようにADSを構成します。ADSの構成はadf-config.xmlファイルで行われます。
ADSの構成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

2. オプションで、サーブレットのパラメータを構成し、ユーザーの非アクティブによりタイムアウトとなるまでのアクティブ・セッションの継続時間を指定します。クライアント側のサーブレットのタイムアウト・パラメータの構成は、web.xmlファイルで行われる。
サーブレット・タイムアウト・パラメータの構成の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』を参照してください。

3. ActiveModelインタフェースを実装し、バックエンドからのアクティブ・データ・イベントのリスナーとして登録するバッキングBeanを作成します。

4. イベント・オブジェクトをADSフレームワークに渡すようにBaseActiveDataModel APIを拡張するクラスを作成します。

5. バックエンドからのデータ変更イベントのデータ変更リスナーを登録します。

6. Webページで、プッシュされたデータを取得し表示するためのADFコンポーネントを実装するマネージドBeanを指定する式を追加して、プッシュされたデータを取得し表示するADF Facesコンポーネントを構成します。

38.3 マネージドBeanでのActiveModelインタフェースの実装

プロパティとしてアクティブ・モデル実装を含むバッキングBeanを作成します。このクラスでは、JSFモデルをラップするのにADSデコレータ・クラスを使用します。このクラスでは、データをADSフレームワークにプッシュするバックエンドからのコールバックも実装されます。

次のADSデコレータ・クラスのいずれかをサブクラスとして持つJavaクラスを作成する必要があります。

- ActiveCollectionModelDecoratorクラス

- ActiveDataModelDecoratorクラス(グラフと使用)

- ActiveGeoMapDataModelDecoratorクラス

- ActiveGaugeDataModelDecoratorクラス

これらのクラスは、アクティブ・データ機能をActiveDataModelのデフォルトの実装に委任するラッパー・クラスです。ActiveDataModelクラスは、データ変更イベントをリスニングし、イベント・マネージャと対話します。

特に、ActiveModelインタフェースを実装するときには、次のことを完了します。

- JSFモデル・インタフェースをラップします。たとえば、ActiveCollectionModelDecoratorクラスでCollectionModelクラスをラップします。

- データ・ソースからのデータ変更イベントに基づいて、アクティブ・データ・イベントを生成します。

ActiveModelインタフェースを実装するには、データの送信先で、それ自体がアクティブ・データ・ソースのリスナーとして登録されるモデルを取得するJavaクラスに、メソッドを実装する必要があります(例38-1を参照)。

1. コンポーネントに適したデコレータ・クラスを拡張するJavaクラスを作成します。
例38-1に、ActiveCollectionModelDecoratorを拡張するStockManagerクラスを示します。このクラスでは、データがADF Faces tableコンポーネント用に表示されます。

2. ActiveDataModelクラスを返すデコレータ・クラスのメソッドを実装し、スカラー・モデルを返すメソッドを実装します。
例38-1に、既存の非同期バックエンドに登録するgetCollectionModel()メソッドの実装を示しています。メッソッドにより、バックエンドから在庫コレクションのリストが返されます。

3. アクティブ・モデル上でデータを挿入または更新するために使用できるアプリケーション固有のイベントを作成するメソッドを実装します。
例38-1に示すバックエンドからのonStockUpdate()コールバック・メソッドでは、アクティブ・モデル(ActiveStockModelのインスタンス)を使用して、データをADF FacesコンポーネントにプッシュするActiveDataUpdateEventオブジェクトを作成します。

例38-1 デコレータ・クラスの拡張

package sample.oracle.ads;

import java.util.List;
import sample.backend.IBackendListener;
import sample.bean.StockBean;
import sample.oracle.model.ActiveStockModel;

import oracle.adf.view.rich.event.ActiveDataEntry;
import oracle.adf.view.rich.event.ActiveDataUpdateEvent;
import oracle.adf.view.rich.model.ActiveCollectionModelDecorator;
import oracle.adf.view.rich.model.ActiveDataModel;

import oracle.adfinternal.view.faces.activedata.ActiveDataEventUtil;

import org.apache.myfaces.trinidad.model.CollectionModel;
import org.apache.myfaces.trinidad.model.SortableModel;

// 1. This example wraps the existing collection model in the page and implements
//    the ActiveDataModel interface to enable ADS for the page.

public StockManager extends ActiveCollectionModelDecorator implements
IBackendListener
{
// 2. Implement methods from ADF ActiveCollectionModelDecorator class to
//    return the model.
@Override
public ActiveDataModel getActiveDataModel()
{
return stockModel;
}

@Override
protected CollectionModel getCollectionModel()
{
if(collectionModel == null)
{
// connect to a backend system to get a Collection
List<StockBean> stocks = FacesUtil.loadBackEnd().getStocks();
// make the collection become a (Trinidad) CollectionModel
collectionModel = new SortableModel(stocks);
}

return collectionModel;
}

// 3. Implement a callback method to create active data events and deliver to
//    the ADS framework.

/**
* Callback from the backend to push new data to the decorator.
* The decorator itself notifies the ADS system that there was a data change.
*
* @param key the rowKey of the updated Stock
* @param updatedStock the updated stock object
*/
@Override
public void onStockUpdate(Integer rowKey, StockBean stock)
{
ActiveStockModel asm = getActiveStockModel();

// start the preparation for the ADS update
asm.prepareDataChange();

// Create an ADS event, using an _internal_ util.
// This class is not part of the API
ActiveDataUpdateEvent event = ActiveDataEventUtil.buildActiveDataUpdateEvent(
ActiveDataEntry.ChangeType.UPDATE, // type
asm.getCurrentChangeCount(), // changeCount
new Object[] {rowKey}, // rowKey
null, //insertKey, null as we don't insert stuff
new String[] {"value"}, // attribute/property name that changes
new Object[] { stock.getValue()}  // the payload for the above attribute
);

// Deliver the new Event object to the ADS framework
asm.notifyDataChange(event);

}

/**
* Typesafe caller for getActiveDataModel()
* @return
*/
protected ActiveStockModel getActiveStockModel()
{
return (ActiveStockModel) getActiveDataModel();
}

// properties
private CollectionModel collectionModel; // see getCollectionModel()...
private ActiveStockModel stockModel = new ActiveStockModel();
}

クラスをマネージドBeanとしてfaces-config.xmlファイルに登録します。例38-2では、StockManagerBeanの登録を示しています。マネージドBeanを定義することにより、ADF Facesコンポーネントの値プロパティの式でそのマネージドBeanを指定できます。

例38-2 マネージドBeanとして登録

...
<managed-bean>
<managed-bean-name>stockManager</managed-bean-name>
<managed-bean-class>
oracle.afdemo.view.feature.rich.StockManager
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

38.4 読取り一貫性の維持に関する必知事項

アクティブ・データを使用するということは、コンポーネントに2つのデータ・ソース(アクティブ・データ・フィードと標準データ・フェッチ)があることを意味します。このため、アプリケーションでは読取り一貫性が確保されるようにする必要があります。

たとえば、ページに表が含まれ、その表でアクティブ・データが有効になっているとします。表には、データを更新する2つの配信方法(通常の表データ・フェッチとアクティブ・データ・プッシュ)があります。たとえば、バックエンド・データがfooからbar、fredに変わるとします。これらの変更ごとに、アクティブ・データ・イベントが起動されます。イベントがブラウザに到達する前に表がリフレッシュされると、標準データ・フェッチにより常に最新データが取得されるため、表にはfredと表示されます。しかしその場合、アクティブ・データ・イベントにはさらに時間がかかるため、リフレッシュ後にデータ変更イベントによりfooがブラウザに着信し、表では表示が一時期fredのかわりにfooに更新されることになります。したがって、読取り一貫性を維持する方法を実装する必要があるのです。

読取り一貫性を実現するために、ActiveDataModelには、データのタイムスタンプを効果的に記録する変更カウントの概念があります。データ・フェッチとアクティブ・データ・プッシュのどちらも、このchangeCountオブジェクトを単調にカウントを増やすことで維持する必要があるため、返されたデータのchangeCountが現在のカウントより低い場合は、アクティブ・イベントにより廃棄される可能性があります。例38-3は、ActiveDataModelクラスの実装を使用して、読取り一貫性を維持する方法を示しています。

38.5 アクティブ・データ・サービスへのイベント渡し

マネージドBeanで作成されたイベントを渡すために、BaseActiveDataModelクラスを拡張するクラスを作成する必要があります。ActiveDataModelクラスは、データ変更イベントをリスニングし、イベント・マネージャと対話します。具体的には、実装するメソッドで次のことを行います。

- 必要に応じて、アクティブ・データおよびActiveDataModelオブジェクトを開始および停止し、データ・ソースに対するリスナーの登録および登録取消しを行います。

- イベント・マネージャからリスナーを管理し、アクティブ・データ・イベントをイベント・マネージャにプッシュします。

例38-3に、オブジェクトをfireActiveDataUpdate()メソッドに入れることで、モデルのnotifyDataChange()メソッドでEventオブジェクトをADSフレームワークに渡す方法を示します。

例38-3 ADSへのイベント・オブジェクト渡し

import java.util.Collection;

import java.util.concurrent.atomic.AtomicInteger;

import oracle.adf.view.rich.activedata.BaseActiveDataModel;
import oracle.adf.view.rich.event.ActiveDataUpdateEvent;

public class ActiveStockModel extends BaseActiveDataModel
{

// -------------- API from BaseActiveDataModel ----------

@Override
protected void startActiveData(Collection<Object> rowKeys,
int startChangeCount)
{
/* We don't do anything here as there is no need for it in this example.
* You could use a listenerCount to see if the maximum allowed listerners
* are already attached. You could register listeners here.
*/
}

@Override
protected void stopActiveData(Collection<Object> rowKeys)
{
// same as above... no need to disconnect here
}

@Override
public int getCurrentChangeCount()
{
return changeCounter.get();
}

// -------------- Custom API -----------

/**
* Increment the change counter.
*/
public void prepareDataChange()
{
changeCounter.incrementAndGet();
}

/**
* Deliver an ActiveDataUpdateEvent object to the ADS framework.
*
* @param event the ActiveDataUpdateEvent object
*/
public void notifyDataChange(ActiveDataUpdateEvent event)
{
// Delegate to internal fireActiveDataUpdate() method.
fireActiveDataUpdate(event);
}

// properties
private final AtomicInteger changeCounter = new AtomicInteger();
}

38.6 データ更新イベント・リスナーの登録

バックエンドからのデータ変更イベントに対するデータ変更リスナーを登録する必要があります。例38-4では、リスナーBeanStockBackEndSystemがfaces-config.xmlファイルに登録されます。この例では、リスナーをバックエンドに挿入するために式言語が使用されています。

例38-4 データ更新イベント・リスナーの登録

...
<managed-bean>
<managed-bean-name>backend</managed-bean-name>
<managed-bean-class>
oracle.afdemo.backend.StockBackEndSystem
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
<managed-property>
<property-name>listener</property-name>
<value>#{stockManager}</value>
</managed-property>
</managed-bean>

38.7 アクティブ・データを表示するためのADFコンポーネントの構成

コレクションベースのデータを表示するADFコンポーネントは、ADSを使用するように構成でき、ビュー・レイヤーで特別な設定は必要ありません。リスナーを登録すると、ADSを使用してデータをビュー・レイヤーに流すことができます。たとえば、JSPXページでtableコンポーネントを使用して、リスナーを登録しているバックエンド・ソースからの在庫の更新を表示するとします。

例38-5に、プッシュされたデータを受信するためにtable コンポーネントのvalue属性で使用される式言語を示します。

例38-5 アクティブ・データの表示

...
<f:view>
<af:document id="d1">
<af:form id="f1">
<af:panelStretchLayout topHeight="50px" id="psl1">
<f:facet name="top">
<af:outputText value="Oracle ADF Faces goes Push!" id="ot1"/>
</f:facet>
<f:facet name="center">
<!-- id="af_twocol_left_full_header_splitandstretched"  -->
<af:decorativeBox theme="dark" id="db2">
<f:facet name="center">
<af:panelSplitter orientation="horizontal"
splitterPosition="100" id="ps1">
<f:facet name="first">
<af:outputText value="Some content here." id="menu"/>
</f:facet>
<f:facet name="second">
<af:decorativeBox theme="medium" id="db1">
<f:facet name="center">
<af:table value="#{stockManager}" var="row"
rowBandingInterval="0"
id="table1" emptyText="No data...">
<af:column sortable="false" headerText="Name"
id="column1">
<af:outputText value="#{row.name}" id="outputText1"/>
</af:column>
<af:column sortable="false"
headerText="Value...." id="column2">
<af:outputText value="#{row.value}"
id="outputText2" />
</af:column>
</af:table>
</f:facet>
</af:decorativeBox>
</f:facet>
</af:panelSplitter>
</f:facet>
</af:decorativeBox>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>

第VII部

付録

第VII部は、次の付録で構成されます。

- 付録A「ADF Facesの構成」

- 付録B「コンバータおよびバリデータ・メッセージのメッセージ・キー」

- 付録C「キーボード・ショートカット」

- 付録E「クイック・スタート・レイアウト・テーマ」

- 付録F「コード・サンプル」

- 付録G「ADF Facesのトラブルシューティング」

A ADF Facesの構成

この付録では、JSFおよびADF Facesの機能を各種XML構成ファイルで構成する方法、RequestContext APIを使用してADF Faces構成値を取得する方法、およびJavaScriptのパーティション化の使用方法について説明します。

この付録には次の項が含まれます:

- A.1項「ADF Facesの構成について」

- A.2項「web.xmlでの構成」

- A.3項「faces-config.xmlでの構成」

- A.4項「adf-config.xmlでの構成」

- A.5項「adf-settings.xmlでの構成」

- A.6項「trinidad-config.xmlでの構成」

- A.7項「trinidad-skins.xmlでの構成」

- A.8項「RequestContext EL暗黙オブジェクトの使用」

- A.9項「パフォーマンス・チューニング」

A.1 ADF Facesの構成について

JSF Webアプリケーションには、特定の構成ファイルのセット(web.xmlおよびfaces-config.xml)が必要です。ADF Facesアプリケーションでは、構成情報がadf-config.xmlファイルおよびadf-settings.xmlファイルにも格納されます。ADF FacesはMyFaces Trinidadと同じコード・ベースを共有するため、UIにADF Facesコンポーネントを使用するJSFアプリケーションでは、trinidad-config.xmlファイル(オプションでtrinidad-skins.xmlファイル)も含める必要があります。TrinidadとADF Facesとの関係の詳細は、第1章「ADF Facesの概要」を参照してください。

A.2 web.xmlでの構成

JSFアプリケーションの構成の一部は、Java EEアプリケーション・デプロイメント・ディスクリプタ(web.xml)の内容で決まります。/WEB-INFディレクトリにあるweb.xmlファイルでは、サーバーが認識する必要のあるアプリケーションに関するすべての情報(JDeveloperで自動的に割り当てられる、あるいはアプリケーションのデプロイ時にシステム管理者によって割り当てられるルート・コンテキスト・パス以外)を定義する必要があります。web.xmlファイルでの典型的なランタイム設定には、初期化パラメータ、カスタム・タグ・ライブラリの場所およびセキュリティ設定があります。

ADF Facesを使用するすべてのアプリケーションに対する次の設定がweb.xmlファイルで構成されます。

- clientに設定されたjavax.faces.STATE_SAVING_METHODコンテキスト・パラメータ

- MyFaces Trinidadフィルタおよびマッピング

- MyFacesTrinidadリソース・サーブレットおよびマッピング

- JSFサーブレットおよびマッピング

注意:

ADF Facesコンポーネントをアプリケーションで最初に使用した際に、JDeveloperで、必要なADF Faces構成がweb.xmlファイルに自動的に追加されます。

必要な要素の詳細は、A.2.2項「web.xmlに必要な要素に関する必知事項」を参照してください。

web.xmlのADF Faces関連のオプションの構成要素の詳細は、A.2.3項「web.xmlのADF Facesコンテキスト・パラメータに関する必知事項」を参照してください。

ADF Faces以外のweb.xmlの構成の詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』を参照してください。

A.2.1 web.xmlでのJSFとADF Facesの構成方法

JDeveloperでJSFテクノロジを使用するプロジェクトを作成すると、デフォルト・サーブレットとマッピング要素を使用して、web.xmlの基礎ファイルが/WEB-INFディレクトリに作成されます。

プロジェクトでADF Facesコンポーネントを使用(ライブラリをインポートするだけでなく、コンポーネント・タグをページで使用)する場合、JDeveloperで、デフォルトJSF構成要素だけでなく、次のものもweb.xmlに自動的に追加されます。

- MyFaces TrinidadフィルタおよびMyFaces Trinidadリソース・サーブレットに関連する構成要素

- clientの値を持つjavax.faces.STATE_SAVING_METHODコンテキスト・パラメータ

アプリケーションでJSFフラグメントを使用するよう選択した場合、アプリケーションで.jsffファイルを認識および解釈するためのJSP構成要素が、JDeveloperで自動的に追加されます。

例A-1に、JSF、ADF Facesおよび.jsffファイルを使用する場合にJDeveloperで追加されるデフォルト要素を持つweb.xmlファイルを示します。

JSFおよびADF Facesの処理に必要なweb.xml構成要素の詳細は、A.2.2項「web.xmlに必要な要素に関する必知事項」を参照してください。

例A-1 生成されるweb.xmlファイル

<?xml version = '1.0' encoding = 'windows-1252'?><web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee">
<description>Empty web.xml file for Web Application</description>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>35</session-timeout>
</session-config>
<mime-mapping>
<extension>html</extension>
<mime-type>text/html</mime-type>
</mime-mapping>
<mime-mapping>
<extension>txt</extension>
<mime-type>text/plain</mime-type>
</mime-mapping>
</web-app>

注意:

データバインドされたWebページの作成にADFデータ・コントロールを使用する場合、アプリケーション・バインディング・コンテナのADFバインディング・フィルタとサーブレット・コンテキスト・パラメータがweb.xmlファイルに追加されます。

ADF Facesの構成オプションは、<context-param>要素を使用してweb.xmlに設定されます。

web.xmlにADF Faces構成要素を追加する手順:

1. 「アプリケーション」ウィンドウで、web.xmlをダブルクリックしてファイルを概要エディタで開きます。
概要エディタを使用してエントリを宣言的に追加または編集すると、JDeveloperでweb.xmlファイルが自動的に更新されます。

2. web.xmlファイルのXMLコードを直接編集するには、エディタ・ウィンドウの下部の「ソース」をクリックします。
XMLエディタで要素を編集すると、JDeveloperで変更が概要エディタに反映されます。

追加できるコンテキスト・パラメータの一覧は、A.2.3項「web.xmlのADF Facesコンテキスト・パラメータに関する必知事項」を参照してください。

A.2.2 web.xmlに必要な要素に関する必知事項

web.xmlに必要なJSFおよびADF Facesに関するアプリケーション全体の構成要素は次のとおりです。

- コンテキスト・パラメータjavax.faces.STATE_SAVING_METHOD: アプリケーションのビューの状態の格納場所を指定します。デフォルトでは、この値はclientであり、アプリケーションのビュー状態がブラウザ・クライアントに格納されます。clientに設定した場合、ADF Facesでトークンベースのクライアント側の状態保存が自動的に使用されます。デフォルトの15を使用するかわりに、使用するトークンの数を指定できます。状態保存コンテキスト・パラメータの詳細は、A.2.3項「web.xmlのADF Facesコンテキスト・パラメータに関する必知事項」を参照してください。

- MyFaces Trinidadフィルタおよびマッピング: 部分的にRequestContextオブジェクトを構成することで、ADF Facesが適切に初期化されていることを保証するサーブレット・フィルタである、MyFaces Trinidadフィルタorg.apache.myfaces.trinidad.webapp.TrinidadFilterをインストールします。TrinidadFilterは、ファイル・アップロードも処理します。フィルタ・マッピングは、JSFサーブレットのシンボリック名をMyFaces Trinidadフィルタにマップします。フォワードおよびリクエスト・ディスパッチャは、MyFaces Trinidadフィルタに転送中のその他のフィルタに必要です。

ヒント:

アプリケーションで複数のフィルタを使用する場合、フィルタを実行順にweb.xmlファイルに必ずリストします。実行時、このファイルにリストされた順にフィルタがコールされます。

- MyFaces Trinidadリソース・サーブレットおよびマッピング: リソース・ローダーに委任することでWebアプリケーション・リソース(イメージ、スタイルシート、JavaScriptライブラリ)を処理する、MyFaces Trinidadリソース・サーブレットorg.apache.myfaces.trinidad.webapp.ResourceServletをインストールします。サーブレット・マッピングは、MyFaces Trinidadリソース・サーブレットのシンボリック名をURLパターンにマップします。JDeveloperではデフォルトで、MyFaces Trinidad Coreには/adf/*が、ADF Facesには/afr/*が使用されます。

- JSFサーブレットおよびマッピング(JSFページを作成する場合、またはADF Facesコンポーネントにテンプレートを使用する場合に追加): JSFサーブレットservlet javax.faces.webapp.FacesServletでは、JSFを使用してユーザー・インタフェースを作成するWebアプリケーションのリクエスト処理ライフサイクルが管理されます。マッピングでは、JSFサーブレットのシンボリック名が、パス接頭辞または拡張子接尾辞パターンを使用するURLパターンにマップされます。
デフォルトでは、次のコードに示すように、パス接頭辞/faces/*がJDeveloperで使用されます。

<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>

たとえば、Webページがindex.jspxの場合、URL http://localhost:8080/MyDemo/faces/index.jspxが送信されると、このURLによってJSFサーブレットがアクティブ化されます。JSFサーブレットでfaces接頭辞が取り除かれ、/MyDemo/index.jspxファイルがロードされます。

A.2.3 web.xmlのADF Facesコンテキスト・パラメータに関する必知事項

ADF Facesの構成オプションは、<context-param>要素を使用してweb.xmlに定義されます。次に例を示します。

<context-param>
<param-name>oracle.adf.view.rich.LOGGER_LEVEL</param-name>
<param-value>ALL</param-value>
</context-param>

ADF Facesでは、次のコンテキスト・パラメータがサポートされています。

A.2.3.1 状態保存

次の状態保存コンテキスト・パラメータを指定できます。

- org.apache.myfaces.trinidad.CLIENT_STATE_METHOD: クライアント側状態保存がjavax.faces.STATE_SAVING_METHODを使用して有効になっている場合、使用するクライアント側状態保存のタイプを指定します。CLIENT_STATE_METHODの値は次のとおりです。

- token: (デフォルト)ページの状態はセッションに格納しますが、トークンはクライアントに永続させます。HttpSessionオブジェクトに格納されている状態のブロックを識別するシンプル・トークンは、クライアントに格納されます。これにより、複数回表示される同一ページがADF Facesで明確になります。フェイルオーバーがサポートされます。

- all: すべての状態情報がクライアントの(場合によっては非常に大きい)非表示のフォーム・フィールドに格納されます。これは、HttpSessionを使用しない開発者にとって有用です。

パフォーマンスのヒント:

ただし、すべての状態情報を格納するとサイズが大きくなる可能性があることから、クライアント側状態保存をtokenに設定してください。

- org.apache.myfaces.trinidad.CLIENT_STATE_MAX_TOKENS: トークンベースのクライアント側の状態保存が有効化されている場合に、ユーザーごとに一度に保存できるトークンの数を指定します。デフォルトは15です。トークンがこの数を超えると、表示頻度の最も低いページの状態が失われるため、「戻る」ボタンを頻繁に使用するユーザーや、同時に複数のウィンドウを開いているユーザーが影響を受けます。フレームへの依存度が高いHTMLアプリケーションを作成する場合は、この値を増やすことができます。

- org.apache.myfaces.trinidad.COMPRESS_VIEW_STATE: セッションで状態保存をグローバルに圧縮するかどうかを指定します。各ユーザー・セッションには、ライブ・メモリーを大量に消費する複数のpageStateオブジェクトが含まれていることがあり、その場合はパフォーマンスに影響があります。このオーバーヘッドは、セッション・レプリケーションの実行時に、クラスタリングではるかに大きな問題になる可能性があります。デフォルトはoffです。

A.2.3.2 デバッギング

次のデバッグ・コンテキスト・パラメータを指定できます。

- org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT: ADF Facesでは、クライアントへ配信するJavaScriptの曖昧化がデフォルトで行われ、同時にコメントと空白が取り除かれます。これにより、ADF Faces JavaScriptのダウンロード・サイズが大幅に削減されますが、JavaScriptのデバッグが複雑にもなります。アプリケーションの開発時に曖昧化を無効にするには、trueに設定します。アプリケーションのデプロイ時には、falseに設定します。

- org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION: このパラメータは、デフォルトではfalseに設定されます。trueに設定した場合、ADF FacesでJSFファイルとCSSファイルの更新日付が自動的に確認され、ファイルに変更があった場合、保存されている状態が破棄されます。

パフォーマンスのヒント:

trueの場合、このCHECK_FILE_MODIFICATIONパラメータにより、アプリケーションのデプロイ時には不要となるオーバーヘッドが追加されます。アプリケーションを実行環境にデプロイする場合はfalseに設定します。

- oracle.adf.view.rich.LOGGER_LEVEL: このパラメータでは、デフォルト・レンダー・キットがoracle.adf.richの場合、JavaScriptロギングを有効にします。デフォルトは、OFFです。JavaScriptロギングを有効にする場合、SEVERE、WARNING、INFO、CONFIG、FINE、FINER、FINEST、ALLのいずれかのレベルを使用します。

パフォーマンスのヒント:

JavaScriptロギングはパフォーマンスに影響します。実行環境では、この値はOFFに設定します。

- oracle.adf.view.rich.REQUEST_ID_TRACING: このパラメータは、エンド・ユーザー・レポートをサーバー側のログの対応するエントリに関連付けることで、失敗した部分ページ・レンダリング(PPR)リクエストの診断に使用されます。これは、サーバー・ログの一意のECIF番号をPPR URLに追加することで実行されます。このパラメータは、デフォルトではoffに設定されています。診断機能をアクティブ化するには、パラメータをPPRに設定します。

A.2.3.3 ファイルのアップロード

次のファイル・アップロード・コンテキスト・パラメータを指定できます。

- org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY: 1回のリクエストでアップロード・ファイルを格納するために使用できる最大メモリー容量を指定します。デフォルトは100KBです。

- org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE: アップロードしたファイルを格納する1つのリクエストで使用されるディスク領域の最大サイズを指定します。デフォルトは2000KBです。

- org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR: ファイルのアップロード時に一時ファイルを格納するディレクトリを指定します。デフォルトは、ユーザーの一時ディレクトリです。

注意:

ファイル・アップロードの初期化パラメータは、デフォルトのUploadedFileProcessorのみで処理されます。デフォルト・プロセッサをカスタムUploadedFileProcessor実装で置き換える場合、パラメータは処理されません。

A.2.3.4 リソース・デバッグ・モード

次の内容を指定できます。

- org.apache.myfaces.trinidad.resource.DEBUG: リソース・デバッグ・モードが有効かどうかを指定します。デフォルトは、falseです。リソース・デバッグ・モードを有効にする場合、trueに設定します。有効な場合、リソース(JavaScriptライブラリ、イメージ、CSSなど)がキャッシュ可能なことがブラウザで認識されるよう、ADF FacesによってHTTPレスポンス・ヘッダーが設定されます。

ヒント:

リソース・デバッグ・モードを有効にした後、ブラウザのキャッシュをクリアして、ブラウザでリソースの最新バージョンがロードされるようにします。

パフォーマンスのヒント:

本番環境では、このパラメータは削除するか、falseに設定します。

A.2.3.5 ユーザー・カスタマイズ

セッション変更永続性の有効化および使用の詳細は、第35章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

A.2.3.6 Real User Experience Insightに対するアプリケーションの有効化

Real User Experience Insight (RUEI)はWebベースのユーティリティで、ネットワークからリクエストされる、またはネットワークで生成される実際のユーザーのトラフィックに対してレポートを作成します。ネットワーク・インフラストラクチャの最も重要となるポイントで、ページやトランザクションのレスポンス時間を測定します。セッション診断情報を使用すれば、根本原因分析を実行できます。

RUEIでは、実際のユーザー体験に基づいてサーバーおよびネットワーク時間を表示し、キー・パフォーマンス・インディケータ(KPI)とサービス・レベル合意(SLA)を監視し、定義済のターゲットに違反するインシデントが発生した場合にアラート通知をトリガーすることが可能です。ページ・コンテンツ、サイト・エラー、およびトランザクションの機能要件に関するチェックを実施できます。この情報を使用することで、業務面、技術面から運用を検証できます。RUEIで認識されるすべての項目の可用性、スループットおよびトラフィックに関して、カスタム・アラートを設定することもできます。

web.xmlファイルにパラメータを追加して、その値をtrueに設定し、RUEIでoracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDERを有効にするかどうかを指定します。デフォルトでは、このパラメータは設定されていないかfalseに設定されています。

RUEIの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のReal User Experience Insightに対するアプリケーションの有効化に関する項を参照してください。

A.2.3.7 アサーション

oracle.adf.view.rich.ASSERT_ENABLEDパラメータを使用して、ADF Faces内でアサーションを使用するかどうかを指定できます。デフォルトは、falseです。アサーションを有効にするにはtrueに設定します。

パフォーマンスのヒント:

アサーションはパフォーマンスに影響します。実行時環境では、この値はfalseに設定します。

A.2.3.8 ダイアログ接頭辞

ダイアログを起動する接頭辞を変更するには、org.apache.myfaces.trinidad.DIALOG_NAVIGATION_PREFIXパラメータを設定します。

デフォルトはdialog:で、ダイアログを起動するJSFナビゲーション・ルールの結果の冒頭に使用されます(dialog:errorなど)。

A.2.3.9 CSSクラス名の圧縮

org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSIONパラメータを設定して、スキニング・キーのCSSクラス名の圧縮を決定できます。

デフォルトは、falseです。圧縮を無効にする場合、trueに設定します。

パフォーマンスのヒント:

圧縮はパフォーマンスに影響します。本番環境では、このパラメータをfalseに設定します。

A.2.3.10 アプリケーションに複数のADFスキンがある場合のキャッシュの制御

スキニング・フレームワークは、アプリケーションがリクエストする各スキンの生成されたCSSファイルに関する情報をメモリーにキャッシュします。アプリケーションで異なるスキンが多数使用される場合は、これがパフォーマンスに影響します。org.apache.myfaces.trinidad.skin.MAX_SKINS_CACHEDパラメータの値として、メモリーに情報をキャッシュするスキンの最大数を指定します。このパラメータのデフォルト値は20です。

A.2.3.11 テストの自動化

oracle.adf.view.rich.automation.ENABLEDパラメータをtrueに設定し、コンポーネントID属性がnullの場合、自動テストの際、IDがnullでないようコンポーネントのtestIdが使用されます。testIdはタグのみの属性です。JavaコンポーネントAPIの一部ではありません。このコンテキスト・パラメータで有効化されるのはテスト自動化のインフラストラクチャのみであり、テスト自体は開始されません。テストを開始するには、オープン・ソースのSelenium IDEのようなツールが必要になります。

注意:

テスト自動化コンテキスト・パラメータをtrueに設定すると、oracle.adf.view.rich.security.FRAME_BUSTINGコンテキスト・パラメータはneverに設定された場合と同じように動作します。フレームバスティングを無効にした場合のセキュリティの結果として、ユーザーのアプリケーションのページは悪質なWebサイトからのクリックジャックに対して脆弱になります。このため、テスト自動化の使用を開発環境またはステージング環境に限定し、本番環境でテスト自動化を有効にしないでください。詳細は、A.2.3.18項「フレームバスティング」を参照してください。

また、テスト自動化を有効化することによって、実行中のアプリケーションでアサーションが有効になります。使用しているアプリケーションで予想外のコンポーネント動作が発生し、新規アサーションの失敗エラーが表示されるようになったら、アプリケーション・コンポーネントの実装の詳細を調べる必要があります。たとえば、応答のなくなったユーザー・アクションなど、ポップアップ・ダイアログ関連の問題が発見されることは珍しいことではありません。

テスト自動化を有効にした後でのみアサーション失敗エラーを生成する既知のコーディング・エラーが表示されます。

- ユーザーのコンポーネントでは、もはやページ定義ファイルに存在しないADFイテレータ・バインディングを参照します。アサーションが有効になっていない場合、このエラーは表示されず、存在していないイテレータを参照するコンポーネントはレンダリングしません。

- ユーザーのコンポーネントは、レンダリングしないように定義されている部分トリガー・コンポーネントです(属性がrendered="false"に設定されています)。たとえば、レンダリングされた属性の使用によってアサーション失敗エラーが発生します。

<af:button  id="hiddenBtn" rendered="false" text="Test"/>
<af:table var="row" id="t1"  partialTriggers="::hiddenBtn">

このエラーの回避策として、rendered="false"ではなく、visible="false"に設定された属性を使用します。

- ユーザーのコンポーネントは、イベントが適切なコンポーネント・ハンドラに到達できないようにするネスト化階層によって構成されています。たとえば、次のネスト化は正しくありません。

<af:commandLink
<af:showPopupBehavior
<af:image
<af:clientListener

したがって、次のように書き直す必要があります。

<af:commandLink
<af:image
<af:showPopupBehavior
<af:clientListener

システム管理者は、コマンドライン・フラグ-Doracle.adf.view.rich.automation.ENABLED=trueを指定してサーバーを起動することにより、スタンドアロンのOracle WebLogic Serverのレベルでテスト自動化を有効にできます。テスト自動化を有効にしてアプリケーション・サーバー・インスタンスでアプリケーションを実行すると、デプロイされたアプリケーションのweb.xmlファイルのコンテキスト・パラメータの設定がオーバーライドされます。

A.2.3.12 UIViewRootキャッシング

UIViewRootキャッシングを有効化または無効化するには、org.apache.myfaces.trinidad.CACHE_VIEW_ROOTパラメータを使用します。トークンのクライアント側状態保存が有効化されている場合、各トークンを使用してUIViewRootツリー全体をキャッシュすることにより、MyFaces Trinidadで更なる最適化が行われます。(これは、スレッドの安全性やセッションのフェイルオーバーには影響しないことに注意してください。)UIViewRootツリーを再インスタンス化する必要がなく、ポストバックの処理スピードが大幅に速くなるため、これはAJAX集中型システムにとって重要な最適化です。

キャッシングを有効にするには、org.apache.myfaces.trinidad.CACHE_VIEW_ROOTパラメータをtrueに設定します。これがデフォルトです。キャッシングを無効にするには、パラメータをfalseに設定します。

注意:

この種のキャッシングは、一部のJSFテクノロジと干渉することが認識されています。特に、Apache MyFaces Tomahawk saveStateコンポーネントが機能せず、Faceletのテンプレート・テキストが二重に表示される場合があります。

A.2.3.13 テーマと色調スタイル

oracle.adf.view.rich.tonalstyles.ENABLEDパラメータは後方互換性のためにまだ使用可能ですが、パラメータをfalseに設定し、.AFDarkTone、.AFMediumTone、.AFLightToneおよび.AFDefaultToneの色調スタイル・クラスの置換えスタイルとしてテーマを使用します。テーマは色調スタイルより作成しやすく、依存するセレクタが少ない上に、CSS包含セレクタも使用されません。このため、不具合が起こりにくくなります。1つのCSSファイル内のセレクタ数に対する制限により、色調スタイルおよびテーマの両方を、同じアプリケーションでサポートすることはできません。

A.2.3.14 部分ページ・レンダリング

部分ページ・レンダリング(PPR)最適化を有効化および無効化するには、org.apache.myfaces.trinidad.PPR_OPTIMIZATIONパラメータを使用します。このパラメータは、デフォルトではoffに設定されています。パフォーマンスとPPRの効率を向上するにはonに設定します。

A.2.3.15 部分ページ・ナビゲーション

oracle.adf.view.rich.pprNavigation.OPTIONSパラメータを使用して、部分ページ・ナビゲーションを有効化および無効化します。デフォルトでは、値はoffです。部分ページ・ナビゲーションでは、アプリケーション全体で同じベース・ページを使用し、単にページ本体のコンテンツを各ナビゲーションに置き換えます。このプロセスにより、ページが新しくなるたびにJavaScriptライブラリとスタイル・シートを再ロードする必要がなく、パフォーマンスが向上します。詳細は、8.5項「部分ページ・ナビゲーションの使用」を参照してください。

有効な値は次のとおりです。

- on: アプリケーションのPPRナビゲーションを有効にします。

注意:

パラメータを有効にする場合、ナビゲーションに含まれるコマンド・コンポーネントのpartialSubmit属性をtrueに設定する必要があります。partialSubmitの詳細は、6.1.1項「イベントおよび部分ページ・レンダリング」を参照してください。

- off: アプリケーションのPPRナビゲーションを無効にします。

- onWithForcePPR: コマンド・コンポーネントでのアクションの結果としてナビゲーションが行われる場合、コンポーネントのpartialSubmit属性がtrueに設定されている場合と同様に、アクションは常にPPRを使用して配信されます。partialSubmitの詳細は、6.1.1項「イベントおよび部分ページ・レンダリング」を参照してください。コンポーネントのpartialSubmitがすでにtrueに設定されている場合、フレームワークでの処理はありません。partialSubmitがtrueに設定されていない場合、ドキュメント全体がリフレッシュされ、古いページ・リフレッシュ動作が保持されます。アクション・コンポーネントにナビゲーションが含まれない場合も、ドキュメント全体がリフレッシュされます。

A.2.3.16 ポストバック・ペイロード・サイズの最適化

デフォルトでは、PPRではすべてのフィールドがサーバーに戻されます。遅延時間が長く帯域幅の低いネットワーク上のアプリケーションでは、このためにパフォーマンスが低下する場合があります。

oracle.adf.view.rich.POSTBACK_PAYLOAD_TYPEパラメータを使用して、ADF Facesの編集可能なコンポーネントの値が最後のリクエスト以後に変更されている場合のみ戻すようにアプリケーションを構成します。

有効な値は次のとおりです。

- full: すべてのフィールドが戻されます(デフォルト)。

- dirty: 最後のリクエスト以後に変更されている編集可能なコンポーネントの値のみ戻されます。ただし、次のものは常に戻されます。

- 変換または検証に失敗したコンポーネントの値

- サード・パーティのコンポーネントの値

- リクエスト・スコープまたはバッキングBeanスコープの値にバインドされているコンポーネントの値

- af:codeEditor、af:richTextEditor、af:inputFileコンポーネントの値

注意:

dirtyを選択すると、すべてのADF Faces編集可能コンポーネントに対してクライアント・コンポーネントが作成されます。これにより、レスポンス・ペイロード・サイズが若干大きくなります。

A.2.3.17 JavaScriptのパーティション化

oracle.adf.view.rich.libraryPartitioning.DISABLEDパラメータを使用して、JavaScriptのパーティション化の有効/無効を切り替えます。デフォルトでは、値はfalse(有効)です。JavaScriptのパーティション化を使用すると、ページのクライアント・コンポーネントによって必要とされるJavaScriptのみをダウンロードできます。

有効な値は次のとおりです。

- false: JavaScriptのパーティション化が有効にされています(デフォルト)。

- true: JavaScriptのパーティション化は無効です。

JavaScriptのパーティション化の使用および構成の詳細は、4.9項「JavaScriptライブラリのパーティション化」を参照してください。

A.2.3.18 フレームバスティング

アプリケーションでフレームバスティングを使用するには、org.apache.myfaces.trinidad.security.FRAME_BUSTINGコンテキスト・パラメータを使用します。フレームバスティングは、悪意のあるWebサイトが別のドメインのページをフレームに引き出して偽のページで覆い隠し、元のページの一部のみが表示されるようにしたり、クリックジャックされたページ(ボタンなど)が表示されるようにするクリックジャックを防ぐ方法です。ユーザーがボタンをクリックすると、実際はクリックジャックされたページでボタンをクリックしているため、予期しない結果になります。

たとえば、DomainAに存在するWebベースの電子メール・アプリケーションに対して、IFrameを使用してDomainAの電子メール・アプリケーションのページを指すページを作成してDomainBのWebサイトでページをクリックジャックするとします。2つのページを組み合せて、DomainBから引き出されたページがIFrameでページの大部分を占めるようにして、アカウントのすべての電子メールを削除するボタンのみが表示されるようにします。実際に電子メール・アプリケーション内で操作していることを認識していないユーザーがボタンをクリックすると、意図せずにすべての電子メールが削除されることになります。

フレームバスティングは次のJavaScriptを使用して、アプリケーションのページがフレーム内で実行されるのをブロックし、クリックジャックを防ぎます。

top.location.href = location.href;

パラメータをalwaysに設定して、アプリケーションがフレームバスティングを使用するように構成すると、フレームでページの実行が試行されるたびに、ユーザーにはページがリダイレクトされているというアラートが表示され、ページが最上位であることを定義するJavaScriptコードが実行され、ページのフレーム内での実行が却下されます。

アプリケーションでフレームを使用する必要がある場合は、パラメータの値をdifferentOriginに設定できます。この設定では、フレームの派生元が親ページと異なる場合のみ、フレームバスティングが実行されます。これがデフォルトの設定です。

注意:

ページの派生元はドメイン名、アプリケーション・レイヤー・プロトコル、およびほとんどのブラウザではスクリプトを実行しているHTMLドキュメントのTCPポートを使用して定義されます。これらの値がすべて完全に同一である場合にのみ、ページは同じドメインから派生したとみなされます。

たとえば、次のページは、ポート番号が違うため派生元のチェックに失敗します。

- http://www.example.com:8888/dir/page.html

- http://www.example.com:7777/dir/page.html

たとえば、DomainApage2ページを含むフレームを使用するアプリケーションにDomainApage1という名前のページがあるとします。外部のDomainBpage1がDomainApage1ページのクリックジャックを試行するとします。結果は次のようなウィンドウ階層になります。

- DomainBpage1

- DomainApage1

- DomainApage2

アプリケーションでdifferentOriginにフレームバスティングが設定されていれば、フレームワークは親ウィンドウ階層をたどって、任意の祖先ウィンドウが別のドメインから引き出されているかどうかを判断できます。DoaminBpage1は別のドメインから派生しているため、DomainApage1ページに対してフレームバスティングJavaScriptコードが実行され、トップレベル・ウィンドウが表示されます。DomainApage2は同じドメインから派生しているため、DomainApage1はフレーム内での実行が許可されます。

有効な値は次のとおりです。

- always: フレームでの実行が試行されると常にエラーが表示されリダイレクトします。

- differentOrigin: 別のドメインから派生したページでフレームの実行が試行される場合のみ、エラーが表示されリダイレクトします(デフォルト)。

- never: 任意の派生元ドメインの任意のフレームでページを実行できます。

注意:

ADF Facesページの場合、次のコンテキスト・パラメータのいずれかをtrueに設定すると、このコンテキスト・パラメータは無視され、neverに設定した場合と同様に動作します。

- org.apache.myfaces.trinidad.util.
ExternalContextUtils.isPortlet

- oracle.adf.view.rich.automation.ENABLED

これはMyFaces Trinidadパラメータであるため、これらのページにも使用できます。My Faces Trinidadアプリケーションにおけるこのパラメータの使用の詳細は、MyFaces Trinidadドキュメントを参照してください。

A.2.3.19 バージョン番号情報

oracle.adf.view.rich.versionString.HIDDENパラメータを使用し、バージョン情報をページのHTML上に表示するかどうかを決めます。パラメータがfalseに設定されると、ADF FacesページのHTMLには、ADF Facesのバージョン、および例A-2に示すページの作成に使用される他のコンポーネントの情報が含まれます。

例A-2 HTMLにおけるバージョン情報

</body><!--Created by Oracle ADF (ADF Faces API -
11.1.1.4.0/ADF Faces Implementation - 11.1.1.4.0, RCF-revision: 39851 (branch:
faces-1003-11.1.1.4.0, plugins: 1.2.3), Trinidad-revision: 1051544 (branch:
1.2.12.3-branch, plugins: 1.2.10), build: adf-faces-rt_101221_0830, libNum:
0355 powered by JavaServer Faces API 1.2 Sun Sep 26 03:21:43 EDT 2010
(1.2)), accessibility (mode:null, contrast:standard, size:medium),
skin:customSkin.desktop (CustomSkin)--></html>

このバージョン情報を非表示にするため、パラメータをtrueに設定します。これがデフォルトです。

注意:

本番環境においては、セキュリティ問題を回避するため、このパラメータをtrueに設定します。開発環境においてデバッグ目的でのみ、falseと設定します。

A.2.3.20 自動生成されたコンポーネントIDの抑制

プログラムでaf:outputTextまたはaf:outputFormattedコンポーネントを部分ターゲットとして(addPartialTarget()へのコールを使用して)追加する際は、autoに設定されたoracle.adf.view.rich.SUPPRESS_IDSコンテキスト・パラメータを使用します。

デフォルトでは、このパラメータはexplicitに設定されているため、次のいずれかに当てはまる場合を除き、自動生成されたコンポーネントIDと明示的に設定されたコンポーネントIDの両方を抑制することでコンテンツ・サイズが削減されています。

- コンポーネントのpartialTriggers属性が設定されている場合

- clientComponentがtrueに設定されている場合

addPartialTarget()へのコールでは、partialTriggers属性が設定されておらず、部分ページ・レンダリングは成功しません。これらのコンポーネントの自動生成されたコンポーネントIDのみを抑制する場合は、パラメータをautoに設定します。

A.2.3.21 ADF Facesキャッシング・フィルタ

ADF Facesキャッシング・フィルタ(ACF)は、イメージ、スタイルシート、.pdfや.zipファイルといったドキュメントなどの静的アプリケーション・オブジェクトのキャッシング(または圧縮、あるいはその両方)を有効にすることで、Webアプリケーションのパフォーマンスを上げる場合に使用可能なJava EEサーブレット・フィルタです。これらのオブジェクトは、Oracle Web CacheやOracle Traffic Directorなどの外部Webキャッシュまたはブラウザ・キャッシュでキャッシュされます。コンテンツのキャッシュ可能性は、主に、Webキャッシュ管理者が定義するURLベースのルールで決まります。アプリケーション管理者または作成者はACFを使用して、adf-config.xmlファイルに直接キャッシング・ルールを定義できます。キャッシング・ルールの定義方法の詳細は、A.4.2項「ADF Faces Caching Filterへのキャッシング・ルールの定義」を参照してください。

ADF Facesタグ・ライブラリJARには、.js、.css、イメージ・ファイル・タイプなどの共通リソース・タイプのデフォルトのキャッシング・ルールが含まれます。これらの固定ルールはadf-settings.xmlファイルに定義されており、アプリケーションのデプロイ中やデプロイ後には変更できません。ルールが競合する場合は、アプリケーション開発者によってadf-config.xmlに定義されているキャッシング・ルールが優先されます。adf-settings.xmlの設定の詳細は、A.5.2項「adf-settings.xmlの要素に関する必知事項」を参照してください。

Webキャッシュを介したWebアプリケーションへのすべてのトラフィックをルーティングするには、Webキャッシュ管理者がOracle Web CacheおよびOracle Traffic Directorを構成する必要があります。Oracle Web CacheまたはOracle Traffic Directorをインストールしていない場合、<agent-caching>子要素がtrueに設定されていれば、adf-config.xmlに定義されたキャッシング・ルールがブラウザのキャッシュに適用されます。ACFがURLリクエスト・パスに含まれるように構成するには、web.xmlファイルに、次のサーブレット・フィルタ定義を追加します。

- ACFフィルタ・クラス: adf-config.xmlに定義されているルールにURLの一致を実行するクラスを指定します。

- ACFフィルタ・マッピング: adf-config.xmlに定義されているキャッシング・ルールに一致するURLパターンを定義します。

例A-3に、ACFサーブレット定義のサンプルを示します。

例A-3 ACFサーブレット定義

<!- Servlet Filter definition ->x
<filter>
<filter-name>ACF</filter-name>
<filter-class>oracle.adf.view.rich.webapp.AdfFacesCachingFilter</filter-class>
</filter>
<!- servlet filter mapping definition ->
<filter-mapping>
<filter-name>ACF</filter-name>
<url-pattern>*</url-pattern>
</filter-mapping>

注意:

アプリケーションに定義されている一連のフィルタの中で、ACFサーブレット・フィルタを最初のフィルタにする必要があります。

A.2.3.22 コマンド・リンクへのネイティブのブラウザ・コンテキスト・メニューの構成

リンクをレンダリングするADF Facesコマンド・コンポーネントのコンテキスト・メニューの提供を、エンド・ユーザーのブラウザで有効化または無効化するには、oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONコンテキスト・パラメータを使用します。コンテキスト・メニューにより、コマンド・コンポーネントに指定されている別のアクション(新しいウィンドウにリンクを開くなど)を起動するメニュー・オプションが提供されます。

このパラメータはデフォルトでyesに設定されているため、ADF Facesコマンド・コンポーネントのコンテキスト・メニューはレンダリングされません。パラメータをnoに設定すると抑制を無効化することができ、ネイティブのブラウザ・コンテキスト・メニューが表示されます。この機能を構成できるADF Facesコマンド・コンポーネントの詳細は、参照してください。

A.2.3.23 Internet Explorer互換性ビュー・モード

ADF Facesアプリケーションを、Microsoft Internet Explorerの互換モードで実行すると、予測できない動作を引き起こす可能性があります。デフォルトでは、ユーザーがADF Facesアプリケーションにアクセスし、Internet Explorerブラウザが互換性モードに設定されている場合、ADF Facesはユーザーにこのモードの無効化を求めるアラートを表示します。

oracle.adf.view.rich.HIDE_UNSUPPORTED_BROWSER_ALERTSコンテキスト・パラメータをIECompatibilityModesに設定して、ユーザーにこのメッセージを非表示にします。

注意:

このメッセージが非表示見になっていても、oracle.adf.view.rich.LOGGER_LEVELパラメータがWARNINGかより詳細レベルに設定されている場合は、警告レベルのログ・メッセージがJavaScriptログにレポートされます。詳細は、A.2.3.2項「デバッグ」を参照してください。

A.2.3.24 セッション・タイムアウトの警告

警告ダイアログが表示されるセッション・タイムアウトまでの秒数を設定するには、oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_TIMEOUTコンテキスト・パラメータを使用します。警告が表示された場合、ユーザーにはセッションを延長する機会が与えられます。セッションが延長されない場合、ユーザーにタイムアウトを通知する最終警告ダイアログが表示されます。このダイアログが表示された場合、ダイアログの下のページのコンテンツは表示されなくなります。セッションの期限が切れると、アプリケーションのセキュリティ構成に応じて、ユーザーはログイン・ページにリダイレクトされます。

このパラメータのデフォルト値は120秒です。WARNING_BEFORE_TIMEOUTが120秒より少ない値に設定されている場合、ページにクライアントの状態保存が使用されている場合またはセッションが無効化されている場合は、機能が無効化されます。

例A-4に、セッションがタイムアウトする120秒前に警告ダイアログを表示する構成を示します。

例A-4 セッション・タイムアウトの警告の構成

<context-param>
<param-name>oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_
TIMEOUT</param-name>
<param-value>120</param-value>
</context-param>

A.2.3.25 HTTPストリーミングにおけるJSPタグの実行

JSPページの処理中に、HTTPストリーミング・リクエストでのJSPタグの実行を有効化または無効化するには、oracle.adf.view.rich.tag.SKIP_EXECUTIONパラメータを使用します。Faceletsの処理は含まれません。

デフォルトでは、このパラメータはstreamingに設定されており、ストリーミング・リクエスト中のJSPタグの実行はスキップされます。ストリーミング・リクエストにタグの実行が必要な場合に、リクエストごとにJSPタグを実行するには、パラメータをoffに設定します。

A.2.3.26 クリーンなURL

ADF FacesはURLパラメータを使用して、ウィンドウIDや状態などの情報を保持します。しかし、実際に同じURLがある場合、URLパラメータのために検索エンジンではURLの認識が妨げられ、分析できなくなります。URLパラメータのために、ブックマークを付けることもできなくなります。

デフォルトでは、ADF Facesは、HTML5履歴管理APIを使用して、これらの内部的に使用される動的URLパラメータを削除します。このAPIを使用できない場合、セッションのCookieが使用されます。

コンテキスト・パラメータoracle.adf.view.rich.prettyURL.OPTIONSを使用して、URLパラメータを削除する方法を手動で構成することもできます。パラメータが削除されないように、パラメータをoffに設定します。HTML5履歴管理APIを使用する場合にのみ、パラメータをuseHistoryApiに設定します。ブラウザがこのAPIをサポートしていない場合、パラメータは削除されません。セッションのCookieを使用してパラメータを削除する場合は、パラメータをuseCookiesに設定します。ブラウザがCookieをサポートしていない場合、パラメータは削除されません。

A.2.3.27 ページのロード中スプラッシュ画面

図A-1に示すように、ページがロードしているときにデフォルトで表示されるスプラッシュ画面の有効または無効を切り替えるには、oracle.adf.view.rich.SPLASH_SCREENパラメータを使用します。

図A-1 ADF Facesスプラッシュ画面

このパラメータは、デフォルトでonに設定されています。スプラッシュ画面が表示されないようにするには、offに設定します。

A.2.3.28 グラフとゲージのイメージ形式

グラフ・コンポーネントとゲージ・コンポーネントのデフォルトの出力形式をHTML5に変更するには、oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMATパラメータを追加します。

<context-param>
<param-name>oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMAT</param-name>
<param-value>HTML5</param-value>
</context-param>

デフォルトでは、このパラメータはすべての新しいアプリケーションに追加されます。有効な値はHTML5(デフォルト)およびFLASHです。

A.2.3.29 レイアウトと表コンポーネントの形状管理

特定のレイアウト・コンポーネントや表がどのように拡大処理されるかをグローバルにコントロールする場合、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータを追加します。

特定のレイアウト・コンポーネント(af:decorativeBox, af:panelAccordion, af:panelDashboard, af:panelStretchLayout, af:panelSplitter, af:panelTabbed)が拡大できるかどうかは、dimensionsFrom属性の値に基づきます。これらのコンポーネントのデフォルトの設定はparentで、これはコンポーネンントのサイズが次の順序で決まることを意味します。

- inlineStyle属性から。

- inlineStyleに値がない場合は、サイズは親コンテナにより決まります(すなわち、コンポーネントは拡大します)。

- 親コンテナが構成されていないか、その子を拡大できない場合は、サイズがスキンによって決定されます。

しかし、コンポーネントが常にautoをdimensionsFrom属性の値として使用することをユーザーが望む場合は(すなわち、コンポーネントはその親コンポーネントが子の拡大を可能としている場合は拡大し、そうでない場合は、コンポーネントのサイズはその子コンポーネントに基づく)、ユーザーはoracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータをautoに設定できます。ユーザーはまた個々のコンポーネントにdimensionsFrom属性を使用して、この設定をオーバーライドすることができます。

表でも同様に、autoHeightRows属性が表が拡大するかどうかを決めます。デフォルトでは-1に設定されており、これは、表のサイズはフェッチされた行の数に基づくことを意味します。しかし、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータがautoに設定されている場合、表は親コンポーネントが拡大を可能としている場合は拡大し、そうでない場合は、表のfetchSize属性で決まる行の数になります。

デフォルトでは、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータはlegacyに設定されており、これは、コンポーネントはその標準のデフォルトの値を使用することを意味します。

親コンポーネントが拡大を可能にしている時にレイアウト・コンポーネントと表の両方が常に拡大することを望む場合は、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータをautoに設定します。

A.2.3.30 表におけるスクロールバーの動作

iOSオペレーティング・システムで、表でスクロールを使用するように構成すると、デフォルトではコンテンツの上にマウスを置いたときのみスクロールバーが表示されます。それ以外の場合は、非表示のままです。その他のオペレーティング・システムでは、デフォルトではスクロールバーは常に表示されます。oracle.adf.view.rich.table.scrollbarBehaviorコンテキスト・パラメータを使用して、すべてのオペレーティング・システムでマウスオーバーするまでスクロールバーを表示しないようにできます。

図A-2に、スクロールバーが非表示の表を示します。

図A-2 スクロールバーが非表示

図A-3は、同じ表でユーザーが表の上にマウスを置いたところで、スクロールバーが表示されています。

図A-3 スクロールバー表示

スクロールバーの表示方法をグローバルに制御するには、oracle.adf.view.rich.table.scrollbarBehaviorを追加します。値をoverlayに設定すると、マウスオーバーが起きるまでスクロールバーは表示されません。値をdefaultに設定するとスクロールバーが常に表示されます。

注意:

oracle.adf.view.rich.table.scrollbarBehaviorパラメータは、値としてEL式も受け付けます。

A.2.3.31 本番プロジェクト・ステージ

次の場合は、javax.faces.PROJECT_STAGEコンテキスト・パラメータを使用します。

- XMLで明示的に構成されていない場合はデフォルト値を強制

- 本番環境で不適切な値が設定されている場合に警告を生成

デフォルトでは、パラメータはPRODUCTIONに設定されます。次に例を示します。

<param-value>PRODUCTION</param-value>

実行時にApplication.getProjectStage()を呼び出すことにより、構成されている値をアプリケーション・オブジェクトに問い合わせることができます。Productionステージで次のいずれかのパラメータがONに設定されている場合、警告が生成されます。

- oracle.adf.view.rich.ASSERT_ENABLED

- oracle.adf.view.rich.automation.ENABLED (web.xml内またはシステム・プロパティとして設定)

また、FALSEに設定されている場合に警告を生成するTrinidadおよびADF Facesパラメータには次のものが含まれます。

- org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT

- org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

- org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION

- org.apache.myfaces.trinidad.resource.DEBUG

- <debug-output> (trinidad-config.xmlファイルから)

注意:

TrinidadパラメータがXMLを介して設定されている場合は追加の警告が生成されます。

org.apache.myfaces.trinidad.CLIENT_ID_CACHING Systemプロパティが無効になっている場合にも警告が生成されます。

A.2.4 web.xmlのその他のコンテキスト・パラメータに関する必知事項

アプリケーション全体に関わるその他のオプションのコンテキスト・パラメータは次のとおりです。

- javax.faces.CONFIG_FILE: JSFアプリケーション構成リソース・ファイルへのパスを指定します。次のコードに示すとおり、値には、アプリケーション・コンテキストの相対パスのカンマ区切りリストを使用します。アプリケーションで複数のJSF構成ファイルを使用する場合、このパラメータを設定します。

<context-param>
<param-name>javax.faces.CONFIG_FILES</param-name>
<param-value>
/WEB-INF/faces-config1.xml,/WEB-INF/faces-config2.xml
</param-value>
</context-param>

- javax.faces.DEFAULT_SUFFIX: JSFコンポーネントを含むJSPページのファイル拡張子(接尾辞)を指定します。デフォルト値は.jspです。

注意:

JSFサーブレットに対する接頭辞マッピング(/facesなど)を使用する場合、このパラメータ値は無視されます。これはデフォルトで行われます。

- javax.faces.LIFECYCLE_ID: javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE定数によるデフォルト設定以外のライフサイクル識別子を指定します。

注意:

LIFECYCLE_IDを他の値に設定すると、ADF Facesが機能しません。

- org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION: 実行時の変更の表示に、JSPファイルとCSSファイルで再起動が必要かどうかを指定します。デフォルトではfalseに設定されています。サーバーを再起動せずに変更を表示できるようにする場合は、trueに設定します。

A.3 faces-config.xmlでの構成

JSF構成ファイルには、JSFアプリケーションのリソース(カスタム・バリデータ、マネージドBeanなど)を登録し、ページ間のナビゲーション・ルールをすべて定義します。JSF構成ファイル名は、アプリケーションで任意の名前にできますが、通常、faces-config.xmlファイルです。小規模なアプリケーションには、通常faces-config.xmlファイルが1つ含まれます。

アプリケーションでADF Facesコンポーネントを使用する場合、JDeveloperにより、必要な構成要素がfaces-config.xmlに自動で追加されます。faces-config.xmlファイルの詳細は、Java EE 6チュートリアル(http://download.oracle.com/javaee/index.html)を参照してください。

A.3.1 faces-config.xmlでのADF Facesの構成方法

JDeveloperでJSFテクノロジを使用するプロジェクトを作成すると、空のfaces-config.xmlファイルが/WEB-INFディレクトリに作成されます。JSFテクノロジを使用するアプリケーション・テンプレート(Java EE Webアプリケーション・テンプレートなど)を基に、新規アプリケーション・ワークスペースを作成した場合も、空のfaces-config.xmlファイルが自動的に追加されます。詳細は、3.2項「アプリケーション・ワークスペースの作成」を参照してください。

アプリケーションでADF Facesコンポーネントを使用する場合、ADFデフォルト・レンダー・キットIDをoracle.adf.richに設定する必要があります。JSFページへのADF Facesコンポーネントの最初の挿入時、またはFusionテンプレートを使用して作成されたアプリケーション・ワークスペースへの最初のJSFページの追加時、例A-5に示すとおり、ADFコンポーネントのデフォルト・レンダー・キットがfaces-config.xmlファイルにJDeveloperで自動的に挿入されます。

例A-5 faces-config.xmlでのADFデフォルト・レンダー・キット構成

<?xml version="1.0" encoding="windows-1252"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">
<application>
<default-render-kit-id>oracle.adf.rich</default-render-kit-id>
</application>
</faces-config>

通常、次のものをfaces-config.xmlで構成します。

- メッセージ・バンドル、サポートされているロケールなどのアプリケーション・リソース

- ページ間のナビゲーション・ルール

- カスタム・バリデータおよびコンバータ

- データを保持および処理、UIイベントの処理およびビジネス・ロジックの実行用マネージドBean

注意:

アプリケーションでADF Controllerを使用する場合、これらの項目はadfc-config.xmlファイルで構成されます。詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』の「ADFタスク・フローの概説」の章を参照してください。

JDeveloperでは、宣言的概要エディタを使用してfaces-config.xmlファイルを変更できます。JSF構成要素に精通している場合は、XMLエディタを使用してコードを直接編集できます。

faces-config.xmlを編集する手順:

1. 「アプリケーション」ウィンドウで、faces-config.xmlをダブルクリックしてファイルを概要エディタで開きます。
概要エディタを使用してマネージドBeanやバリデータなどを宣言的に追加すると、JDeveloperでfaces-config.xmlファイルが自動的に更新されます。

2. faces-config.xmlのXMLコードを直接編集するには、エディタ・ウィンドウの下部の「ソース」をクリックします。
XMLエディタで要素を編集すると、JDeveloperで変更が概要エディタに反映されます。

ヒント:

JSFでは、1つのfaces-config.xmlファイルに複数の<application>要素を使用できます。JSF構成エディタの「概要」モードでは、ファイルの最初の<application>インスタンスの編集のみが許可されます。その他の<application>要素については、XMLエディタを使用してファイルを直接編集する必要があります。

A.4 adf-config.xmlでの構成

adf-config.xmlファイルは、セキュリティ、キャッシュ、変更永続性などのアプリケーション全体の機能の構成に使用されます。他のOracleコンポーネントもこのファイルでプロパティを構成します。

A.4.1 adf-config.xmlでのADF Facesの構成方法

アプリケーションの構成を行う前に、まず、adf-config.xmlファイルを作成する必要があります。その後、アプリケーションで使用するアプリケーション全体のOracle ADF機能の構成を追加できます。

始める前に:

プロジェクト用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

adf-config.xmlを作成および編集する手順:

1. プロジェクト用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

2. 「アプリケーション」ウィンドウで、META-INFノードを右クリックし、「新規」を選択します。

3. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

4. 「XMLファイルの作成」ダイアログで、ファイル名としてadf-config.xmlを入力してMETA-INFディレクトリに保存します。

5. ソース・エディタで、生成されたコードを例A-6のコードに置き換えます。

例A-6 adf-config.xmlファイルのXML

<?xml version="1.0" encoding="utf-8" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
xmlns:ads="http://xmlns.oracle.com/adf/activedata/config">

</adf-config>

6. これで、使用する機能の構成に必要な要素を追加できます。

A.4.2 ADF Faces Caching Filterへのキャッシング・ルールの定義

ADF Faces Caching Filter (ACF)のキャッシング・ルールは、Webアプリケーションの.adf/META-INFディレクトリにあるadf-config.xmlファイルに定義されています。これらのURLの一致ルールに対して、ACFがリクエスト・パスに含まれるように構成する必要があります。ACFサーブレット・フィルタ定義の追加方法の詳細は、A.2.3.21項「ADF Facesキャッシング・フィルタ」を参照してください。

1つ以上のキャッシング・ルールの単一のルート要素は<caching-rules>で、ネームスペースhttp://xmlns.oracle.com/adf/faces/configに<adf-faces-config>要素の子として構成されます。

<caching-rule>要素は各キャッシング・ルールを定義し、構成ファイルにリストされている順序で検証されます。例A-7に、adf-config.xmlでキャッシング・ルールを定義する構文を示します。

例A-7 ACFキャッシング・ルールの構文

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
<caching-rules xmlns="http://xmlns.oracle.com/adf/faces/rich/acf">
<caching-rule id="cache-rule1">
<cache>true|false</cache>
<duration>3600</duration>
<agent-caching>true|false</agent-caching>
<agent-duration>4800</agent-duration>
<compress>true|false</compress>
<cache-key-pattern>....</cache-key-pattern>
<search-key>
<key>key1</key>
<key>key2</key>
</search-key>
<varyBy>
<vary-element>
<vary-name><cookieName>|<headerName></vary-name>
<vary-type>cookie|header</vary-type>
</vary-element>
</varyBy>
</caching-rule>
</caching-rules>
</adf-faces-config>
</adf-config>

各キャッシング・ルールは、<caching-rule>要素に定義されます。オプションのid属性を定義して、ルールの場所をサポートできます。表A-1に、アプリケーションのオブジェクトをキャッシュまたは圧縮するためのパラメータの定義に使用される<caching-rule>子要素を説明します。

表A-1 AFCキャッシング・ルールの要素および属性

ルール要素の子

属性の説明および値

<cache>

オブジェクトをWebキャッシュにキャッシュする必要があるかどうかを指定します。値をfalseにするとオブジェクトはキャッシュされません。デフォルトはtrueです。

<duration>

オブジェクトがWebキャッシュにキャッシュされる期間を秒単位で定義します。デフォルトは300秒です。

<agent-caching>

Webキャッシュがない場合にブラウザ・キャッシュを使用するには、trueの値を指定します。

<agent-duration>

オブジェクトがブラウザ・キャッシュにキャッシュされる期間を秒単位で定義します。デフォルトは-1です。<agent-caching>がtrueで<agent-duration>が定義されていない場合は、<duration>の値がかわりに使用されます。

<compress>

Webキャッシュにキャッシュされたオブジェクトを圧縮する必要があるかどうかを指定します。デフォルト値はtrueです。

<cache-key-pattern>

ルールに一致するURLを決定します。リクエストURLのファイル拡張子またはパス接頭辞に、<cache-key-pattern>要素を1つのみ定義する必要があります。*.の値で始まる<cache-key-pattern>の値はファイル拡張子マッピングとして使用され、その他はパス接頭辞マッピングとして使用されます。

<search-key>
<key>

キャッシュされたオブジェクトにタグ付けされている検索キーを定義します。各<caching-rule>に、子の<key>要素が1つ以上ある<search-key>要素を1つ定義できます。検索キーの値は、キャッシュされたコンテンツの無効化に使用されます。アプリケーションに関連するすべてのリソースを識別するために、デフォルトの<search-key>が、実行時にアプリケーションのコンテキスト・ルートに追加されます。

<varyBy>
<vary-element>
<vary-name>
<vary-type>

Webキャッシュにキャッシュされたオブジェクトのバージョニングに使用されます。<varyBy>要素には、キャッシュされたオブジェクトをバージョニングするためのパラメータを定義する<vary-element>要素を1つ以上指定できます。静的リソースの大部分には、この定義は不要です。

各<vary-element>は、次の内容で定義されます。

- <vary-name>: 有効な値は、cookieName (Cookieの名前で、この値によってレスポンスが変わる)か、headerName (HTTPヘッダーの名前で、この値によって、Webキャッシュにキャッシュされたオブジェクトのバージョンが決定される)です。

- <vary-type>: 有効な値はcookieまたはheaderです。

Webキャッシュにより、リクエスト・パラメータが自動的にバージョニングされます。リクエスト・パラメータに基づき、オブジェクトの複数のバージョンがWebキャッシュに格納されます。

A.4.3 コンポーネント出力形式としてのFlashの構成

アプリケーションではデフォルトで、各コンポーネントに指定されている出力形式が使用されます。たとえば、ADFデータ視覚化コンポーネントを使用するアプリケーションは、アニメーションと対話効果をWebブラウザに表示するFlash出力形式を指定します。コンポーネントの出力形式がFlashで、AppleのiOSオペレーティング・システムのように、ユーザーのプラットフォームでFlash Playerがサポートされていない場合は、出力形式は使用可能な最善のフォールバックに自動的にダウングレードされます。

adf-config.xmlにflash-player-usageコンテキスト・パラメータを設定することで、アプリケーション全体のFlashコンテンツの使用を構成できます。有効な設定は次のとおりです。

- downgrade: 出力形式がFlashで、Flash Playerを使用できない場合に、使用可能な最善のフォールバックにダウングレードすることを指定します。ユーザーは、Flash Playerのダウンロードを要求されません。

- disable: アプリケーション全体におけるFlashの使用の無効化を指定します。クライアントでFlash Playerを使用できるかどうかに関係なく、すべてのコンポーネントがFlash以外でレンダリングされます。

例A-8に、adf-config.xmlでFlashをアプリケーション全体で無効にするための構文を示します。

例A-8 adf-config.xmlで無効化されるFlash

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
<flash-player-usage>disabled</flash-player-usage>
</adf-faces-config></adf-config>

コンテキスト・パラメータでは、EL式の値もサポートされています。このため、アプリケーションの異なる部分や、それぞれのユーザーでプリファレンスに基づいて、Flashを有効化するか無効化するかをアプリケーションで選択することが可能です。

A.4.4 コンテンツ配信ネットワークの使用

コンテンツ配信ネットワーク(CDN)では、ネットワークでのコンテンツへのアクセスがさらに効率的になることで、Webアプリケーションのパフォーマンスが向上します。アプリケーションでは、様々なCDN構成を使用してユーザー・エクスペリエンスを最適化できます。CDNを介してすべてのリクエストをルーティングする構成がよく利用されるようになっています。CDNは、クライアントとアプリケーションとの間のプロキシとして機能します。CDN固有の構成ツールを使用して、キャッシングや圧縮のルールを指定できます。

また、CDNからルーティングされるリクエストを制限する方法もあります。たとえば、予備リソース(イメージ、JavaScriptライブラリ、スタイルシートなど)のリクエストのみをCDNに誘導し、アプリケーション生成HTMLコンテンツのリクエストを直接処理できます。この場合、相対リソースURIを、CDNで処理されるホストを指し示す絶対URIに変換する必要があります。

たとえば、アプリケーション定義のイメージが、imagesというローカル・ディレクトリに保存されるとします。イメージを参照するコードは、例A-9のようになります。

例A-9 デフォルトのイメージ参照

<af:image source="/images/logo.png"
shortDesc="My Company Logo"
id="i1"/>

例A-10に示すように、イメージをCDNから取得するには、CDNのイメージ・ソースの絶対URIを明示的に指定する方法があります。

例A-10 絶対URIを使用したCDNからのイメージ参照

<af:image source="http://mycdn.com/images/logo.png"
shortDesc="My Company Logo"
id="i1"/>

この方法では、アプリケーションの多くの場所(すべてのイメージ参照の可能性がある)を更新する必要があるため、ページ間でCDNベースURIが重複してしまうマイナス面があります。これにより、CDN使用の有効/無効が切り替えられたり、CDNから別の極めて困難なCDNに切り替えられたりする可能性があります。

あるいは、例A-11に示すように、リソース関連属性をELでバインドする方法もあります。

例A-11 CDNベースURIへのELバインディング

<af:image source="#{preferences.baseUri}/logo.png"
shortDesc="My Company Logo"
id="i1"/>

この方法では、CDNベースURIを1箇所(マネージドBeanなど)で指定できます。ただし、コンテンツ全体で正しいEL式を使用することは、アプリケーション開発者の負担になります。

ADF Facesでは、アプリケーション全体で(直接またはEL式を介して)CDNの場所の参照を繰り返すのではなく、リソースURIを変更する一元管理メカニズムが用意されています。このメカニズムを使用すると、1つ以上の接頭辞(ベース・リソースURI)をリソースに指定できます。これらのベース・リソースURIは、ネームスペースhttp://xmlns.oracle.com/adf/rewrite/configの下にある、アプリケーションのadf-config.xmlファイルで定義されます。

たとえば、例A-12では、イメージ・ディレクトリのすべてのpngイメージが、http://mycdn.com接頭辞を含めて書き換えられるように指定されています。

例A-12 adf-config.xmlでのCDN接頭辞の指定

<adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">
<resource-uris>
<base-resource-uri uri="http://mycdn.com/">
<match-pattern>^/.*/images/.*\.png$</match-pattern>
</base-resource-uri>
</resource-uris>
</adf-uri-rewrite-config>

<match-pattern>要素で指定された正規表現(^/.*/images/.*\.png$)は、アプリケーションでレンダリングされるすべてのリソースURIに対してテストされます。一致するURIは、<base-resource-uri>要素のURI属性で指定された接頭辞を含めるように変換されます。

この解決方法では、アプリケーション定義のリソースURIのみでなく、ADF Faces自体で使用されるURIの変更にも使用できるというメリットがあります。このタスクを簡略化するために、ADF Facesでは、正規表現のかわりに<match-alias>要素で使用できるエイリアスの小規模セットを公開します。

たとえば、例A-13の構成では、http://mycdn.com/接頭辞を、ADF Facesコンポーネントで定義されるすべてのイメージに適用しています。

例A-13 イメージへの接頭辞の追加

<adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">
<resource-uris>
<base-resource-uri uri="http://mycdn.com/">
<match-alias>af:images</match-alias>
</base-resource-uri>
</resource-uris>
</adf-uri-rewrite-config>

<match-pattern>要素で指定した正規表現とは異なり、<match-alias>で使用されるエイリアスは、アプリケーション定義のリソースと一致しません。そのため、たとえば、前述の構成のaf:imagesエイリアスの場合、ADF Facesコンポーネントで定義されるイメージ(ADF Facesに付属のデフォルトの背景イメージやアイコン)に接頭辞が付けられます。アプリケーションに明示的にバンドルされるイメージに接頭辞は付きません。

af:imagesエイリアスの他に、ADF Facesスキン(スタイルシート)、JavaScriptライブラリおよびリソース・ドキュメントを対象とするエイリアスも提供されます。

CDNのURIを設定する手順:

1. adf-config.xmlファイルを作成するか開きます(詳細は、A.4.1項「adf-config.xmlでのADF Facesの構成方法」を参照)。

2. 概要エディタで「表示」ナビゲーション・タブをクリックします。

3. 「表示」ページの「コンテンツ配信ネットワーク(CDN)」セクションで、「追加」アイコンをクリックして「ベース・リソースURI」表に新しい行を追加します。

4. 新しい行の「URI」列で、CDNのURIを入力します。これは、指定リソースのURI全体の作成に使用されます。URIがセキュアな場合は、必要に応じて、「セキュアなURI」列にたとえば「https://」などの接頭辞を入力します。

これらのエントリにより、<base-resource-uri>要素が作成されます。

5. 複数のWebアプリケーション間でリソースを共有し、各Webアプリケーションが独自のコンテキスト・パスを持つ場合は、リソースの共有コピーにアプリケーション固有のセグメントを含めることはできません。
書き換えられたURIでアプリケーションに固有のコンテキスト・パスを削除する場合は、「リライト中に出力コンテキスト・パスを削除」を選択します。

6. CDNにホストさせる別名があれば選択します。次のエイリアスが使用可能です。

- af:coreScripts: ADF FacesのJavaScriptライブラリ(旧リリースで使用)

- af:documents: ADF FacesのHTMLリソース(blank.htmlなど)。

- af:images: ADF FacesおよびTrinidadのイメージ・リソース

- af:scripts: ADF FacesのブートおよびコアJavaScriptライブラリ

- af:skins: スキン生成スタイルシート

これらの選択により、<match-alias>要素が作成されます。

7. 書き換えられたURIをアプリケーション固有のリソースで使用するには、各リソース・タイプの正規表現を使用してパターンを作成します。「追加」アイコンをクリックして正規表現をたとえば次のように入力します。

^/.*/images/.*\.png$

注意:

すべての属性値は、ELにバインドされます。ただし、ELにバインドされた属性の評価は一度のみです(解析時)。

これらのエントリにより、<match-pattern>要素が作成されます。

表現はレンダリングされるリソースURIに対してテストされます。一致するものが見つかった場合、リソースURIに手順4で作成したベース・リソースURIで指定されるURIが接頭辞として使用されます。各ベース・リソースURIに対して複数のパターンを定義できます。

ヒント:

実行時のオーバーヘッドを最小限に抑えるために、リソースURIの書換えの結果がキャッシュされることに注意してください。過度のキャッシュを防ぐには、パターン表現の対象を、静的リソースのみにします。動的に生成されるデータ中心リソース(バインドされていない問合せパラメータ値から生成されるリソースなど)は、ベース・リソースURIメカニズムを使用して書き換えないでください。

一致要素に指定された値は、ExteralContext.encodeResourceURL()を通過するすべてのURIと比較されます。URIが一致した場合、囲んでいる<base-resource-uri>要素で指定された接頭辞が適用されます。

例A-14に、CDNを使用するように構成されるアプリケーションを示します。

例A-14 CDN URI要素

<adf-uri-rewrite-config xmlns="http://xmlns.oracle.com/adf/rewrite/config">
<resource-uris>
<base-resource-uri uri="http://mycdn.com/"
secure-uri="https://mycdn.com"
output-context-path="remove">
<match-pattern>^/.*/images/.*\.png$</match-pattern>
<match-pattern>^/.*\.png\?ln=images$</match-pattern>
<match-alias>af:documents</match-alias>
<match-alias>af:scripts</match-alias>
</base-resource-uri>
</resource-uris>
</adf-uri-rewrite-config>

A.4.4.1 スキン・スタイルシートおよびCDNに関する必知事項

af:skinsエイリアスを使用して、CDNを指し示すようにスキン・スタイルシートを書き換えることができますが(CDNはアプリケーション・サーバーにリクエストをプロキシするように構成される)、アプリケーションがクラスタまたはロードバランスされた環境(あるいはその両方)で実行している場合、問題が生じることがあります。

スキン・スタイルシートは、包含ページ・コンテンツをレンダリングしたサーバーに生成されて格納されます。CDNを介してスタイルシート・リクエストをルーティングすることで、サーバー・アフィニティが失われる可能性があります(たとえば、CDNが別のドメインで機能する場合、セッションCookieが失われます)。その結果、スタイルシート・リクエストは、リクエストしたスタイルシートをまだ生成していないサーバーにルーティングされます。このような場合、スタイルシート・リクエストは正常に完了しません。

ロードバランス環境またはクラスタ化環境(あるいはその両方)で起こる可能性のある失敗を回避するには、Cookieまたはセッション・アフィニティが失われる場合、スキン・スタイルシートURIを書き換えないでください。

A.4.4.2 リソース・ファイルのCDN用の準備に関する必知事項

スキン・スタイル・シートおよびJavaScriptパーティション・ファイルは実行時に動的に生成されます。これらのリソースをCDNのサーバーに移動する必要がある場合は、MyFaces TrinidadおよびADF Facesの両方をツールとして使用し、これらのファイルを事前生成して保存し、静的サイトにアップロードできます。

スキン・スタイル・シートを事前生成するには、Trinidad事前生成サービスを使用します。詳細は、http://myfaces.apache.org/trinidad/のTrinidad開発者ガイドのスキニングに関する章を参照してください。

JavaScriptパーティション・ファイルを事前生成するには、ADF Faces JavaScriptライブラリ事前生成サービスを使用します。

ADF Faces JavaScriptライブラリ事前生成サービスを使用するには:

1. システム・プロパティを使用してサービスを有効にします。

- プロジェクトをダブルクリックします。「プロジェクト・プロパティ」ダイアログで、「実行/デバッグ」を選択して「編集」をクリックします。

- 「起動設定」を選択し、「Javaオプション」フィールドに-Doracle.adf.view.rich.libraryPartitioning.PREGENERATION_SERVICE=onと入力します。

注意:

oracle.adf.view.rich.libraryPartitioning.PREGENERATION_SERVICEがonに設定されている場合、アプリケーション内の他のすべての(事前生成以外の)リクエストは失敗します。これは、これらのファイルを事前生成する場合のみonに設定してください。

2. 生成されたファイルを保持するディレクトリを設定する、別のシステム・プロパティを設定します。「Javaオプション」フィールドに、-Doracle.adf.view.rich.libraryPartitioning.PREGENERATION_SERVICE_TARGET_DIRECTORY=/home/user/outputと入力します。
ディレクトリを設定しないと、ファイルはアプリケーションの一時ディレクトリに保存されます。

3. /-adf-pregenerate-js-partitionsビューIDにリクエストを送信します。このリクエストは、生成されるファイルを制限するための次のオプションのパラメータを取ることができます。

- accessibility:

- screenReader

- default(これがデフォルトです)

- optimization:

- none

- simple(これがデフォルトです)

- automation:

- enabled

- disabled (これがデフォルトです)

たとえば、次のリクエストにより、screenReaderと、単純なJavaScript最適化が適用され自動化が無効になったデフォルトのアクセシビリティ・モードのバリアントの両方が生成されます。

/root/faces/-adf-pregenerate-js-partitions?accessibility=screenReader&accessibility=default

A.5 adf-settings.xmlでの構成

adf-settings.xmlファイルには、ADF Facesヘルプ・プロバイダやキャッシング/圧縮ルールなどのプロジェクトレベルおよびライブラリレベルの設定が含まれます。adf-settings.xmlファイルの構成設定は固定で、アプリケーションのデプロイ時やデプロイ後に変更できません。アプリケーションには複数のadf-settings.xmlファイルがある場合があります。ADF設定ファイルのユーザーは、これらの構成の内容をマージする必要があります。

A.5.1 adf-settings.xmlでのADF Facesの構成方法

アプリケーションの構成を行う前に、まず、adf-settings.xmlファイルを作成する必要があります。その後、アプリケーションで使用するプロジェクトの機能の構成を追加できます。このファイルでの構成の詳細は、A.5.2項「adf-settings.xmlの要素に関する必知事項」を参照してください。

adf-settings.xmlを作成および編集する手順:

1. adf-settings.xmlファイルはMETA-INFディレクトリに存在する必要があります。ディレクトリを作成する場所は、adf-settings.xmlファイルを使用するプロジェクトのデプロイ時の計画によって異なります。

- プロジェクトをアプリケーションのEARファイルでデプロイする場合、META-INFディレクトリを/application_name/.adfディレクトリに作成します。

- プロジェクトにadf-settings.xmlファイルへの依存性があり、アプリケーションと別にデプロイされる可能性がある場合(たとえば、ADFライブラリでデプロイされるバインドされたタスク・フローなど)、META-INFディレクトリをビュー・プロジェクトの/srcディレクトリに作成します。

ヒント:

アプリケーションでOracle ADFモデルを使用している場合、META-INFディレクトリを/adfmsrcディレクトリに作成できます。

2. JDeveloperで、「ファイル」→「新規」の順に選択します。

3. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

4. ソース・エディタで汎用コードを例A-15に示すコードに置き換えます。Webアプリケーション・ルートに対する正しい設定を使用します。

例A-15 adf-settings.xmlファイルのXML

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings"
xmlns:wap="http://xmlns.oracle.com/adf/share/http/config" >
<wap:adf-web-config xmlns="http://xmlns.oracle.com/adf/share/http/config">
<web-app-root rootName="myroot" />
</wap:adf-web-config>
</adf-settings>

5. これで、使用する機能の構成に必要な要素を追加できます。詳細は、A.5.2項「adf-settings.xmlの要素に関する必知事項」を参照してください。

6. 手順1で作成したMETA-INFディレクトリに、ファイルをadf-settings.xmlとして保存します。

A.5.2 adf-settings.xmlの要素に関する必知事項

adf-settings.xmlファイルでは次の構成要素がサポートされています。

A.5.2.1 ヘルプ・システム

次の要素を使用して、ヘルプ・システムで使用されるヘルプ・プロバイダを登録します。

- <adf-faces-config>: ADF Faces固有の構成をグループにまとめる親要素。

- <prefix-characters>: ヘルプ・プロバイダで、特定の接頭辞で始まるヘルプ・トピックIDにのみヘルプ・トピックを提供する場合、その接頭辞を指定します。接頭辞を使用しない場合は、省略できます。

- <help-provider-class>: ヘルプ・プロバイダ・クラス。

- <custom-property>および<property-value>: ヘルプ・プロバイダ・クラスで受け入れるパラメータを定義するプロパティ要素。

例A-16に、登録されたヘルプ・プロバイダの例を示します。このケースでは、アプリケーションのヘルプ・プロバイダは1つのみのため、接頭辞を含める必要がありません。

例A-16 ヘルプ・プロバイダの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="MYAPP">
<help-provider-class>
oracle.adfdemo.view.webapp.MyHelpProvider
</help-provider-class>
<property>
<property-name>myCustomProperty</property-name>
<value>someValue</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

A.5.2.2 キャッシング・ルール

アプリケーション固有のライブラリおよびJARには、ファイルのキャッシングまたは圧縮(あるいはその両方)を必要とする様々なリソースが含まれています。ライブラリまたはJARファイルが複数ある場合は、アプリケーションに、一致URLに基づいて様々なキャッシング・ルールを含む1つ以上のadf-setting.xmlファイルが存在することがあります。キャッシング・ルールは、実行時に順序付けられたリストにマージされます。リソースに対するリクエストが複数のキャッシング・ルールに一致する場合は、リストでの順序が先のルールが優先されます。

ADF Faces JARファイルには、.js、.cssおよびイメージ・ファイル・タイプなどの共通リソース・タイプのデフォルトのキャッシング・ルールが含まれています。これらの固定ルールはadf-settings.xmlファイルに定義されており、アプリケーションのデプロイ中やデプロイ後には変更できません。アプリケーション開発者は、adf-config.xmlファイルにアプリケーション・キャッシング・ルールを定義でき、このルールはadf-settings.xmlに定義されるルールより優先されます。例A-17に、ADF Faces JARのadf-settings.xmlファイルを示します。

例A-17 ADF Facesのadf-settings.xmlファイル

<adf-settings>
<adf-faces-settings>
<caching-rules>
<caching-rule id="cache css">
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.css</cache-key-pattern>
</caching-rule>
<caching-rule id="cache js">
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.js</cache-key-pattern>
</caching-rule>
<caching-rule id="cache png">
<compress>false</compress>
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.png</cache-key-pattern>
</caching-rule>
<caching-rule id="cache jpg">
<compress>false</compress>
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.jpg</cache-key-pattern>
</caching-rule>
<caching-rule id="cache jpeg">
<compress>false</compress>
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.jpeg</cache-key-pattern>
</caching-rule>
<caching-rule id="cache gif">
<compress>false</compress>
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.gif</cache-key-pattern>
</caching-rule>
<caching-rule id="cache html">
<compress>true</compress>
<duration>99999</duration>
<agent-caching>true</agent-caching>
<cache-key-pattern>*.html</cache-key-pattern>
</caching-rule>
</caching-rules>
</adf-faces-settings>
</adf-settings>

A.6 trinidad-config.xmlでの構成

ADF Facesコンポーネントを使用してJSFアプリケーションを作成する場合、ADF Facesの機能(スキン・ファミリ、ページ・アクセシビリティ・サポートのレベルなど)をtrinidad-config.xmlファイルで構成します。faces-config.xml同様、trinidad-config.xmlは、JSF式言語(EL)または静的値を使用して要素プロパティを定義できる単純なXML構造を持ちます。

注意:

システム・プロパティでorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATIONを使用するように設定することで、高可用性テストのサポートを構成することもできます。詳細は、A.6.3項「システム・プロパティの構成に関する必知事項」を参照してください。

A.6.1 trinidad-config.xmlでのADF Facesの機能の構成方法

JDeveloperで、ADF FacesコンポーネントをJSFページへ初めて追加すると、trinidad-config.xmlの基礎ファイルが/WEB-INFディレクトリに自動的に作成されます。例A-18に、trinidad-config.xmlの基礎ファイルを示します。

例A-18 JDeveloperによって作成されるtrinidad-config.xml基礎ファイル

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://xmlns.oracle.com/trinidad/config">

<skin-family>skyros</skin-family>
<skin-version>v1</skin-version>

</trinidad-config>

デフォルトでは、JDeveloperはADF Facesを使用するJSFアプリケーションのskyrosスキン・ファミリを構成します。これをfusion、simpleに変更することも、カスタム・スキンを使用することもできます。カスタム・スキンを使用する場合は、trinidad-skins.xml構成ファイルを作成し、カスタム・スキンを使用するようtrinidad-config.xmlを変更します。カスタム・スキンの作成の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズの概要」を参照してください。

通常、次のものをtrinidad-config.xmlファイルで構成します。

- ページ・アニメーション

- ページ・アクセシビリティ・サポートのレベル

- タイムゾーン

- 拡張デバッグ出力

- Oracle Help for the Web (OHW)のURL

ファイルのアップロードに使用するカスタム・ファイル・アップロード・プロセッサの登録もできます。

JDeveloperでは、XMLエディタを使用してtrinidad-config.xmlを変更できます。

trinidad-config.xmlを編集する手順:

1. 「アプリケーション」ウィンドウで、trinidad-config.xmlをダブルクリックします。

2. XMLエディタで、XMLエディタに直接コードを入力することも、構造ウィンドウを使用して要素を追加することもできます。構造ウィンドウを使用するには次のようにします。

1. 構造ウィンドウで要素を右クリックして「前に挿入」または「後ろに挿入」を選択し、挿入する要素を選択します。

2. 構造ウィンドウで新しく挿入された要素をダブルクリックします。「プロパティ」ウィンドウで、値を入力するかドロップダウン・リストから選択します。
ほとんどの場合、JSF EL式(#{view.locale.language=='en' ? 'minimal' : 'skyros'}など)、あるいは静的値(たとえば、<debug-output>true</debug-output>)を入れることができます。EL式は、リクエストごとに動的に再評価され、適切なオブジェクト(ブール・オブジェクトなど)を戻す必要があります。

使用できる構成要素のリストは、A.6.2項「trinidad-config.xmlの要素に関する必知事項」を参照してください。

trinidad-config.xmlファイルの構成後、プログラムから、あるいはJSF EL式を使用してプロパティ値を取得できます。詳細は、A.8項「RequestContext EL暗黙オブジェクトの使用」を参照してください。

A.6.2 trinidad-config.xmlの要素に関する必知事項

すべてのtrinidad-config.xmlファイルは、http://myfaces.apache.org/trinidad/config XMLネームスペースの<trinidad-config>要素で始まる必要があります。<trinidad-config>内の要素の順序は任意です。要素のインスタンスを複数含めることができます。

A.6.2.1 アニメーションの有効化

一部のADF Facesコンポーネントでは、レンダリング時にアニメーションが使用されます。たとえば、ツリーおよびツリー表でノードを展開および縮小する際、アニメーションが使用されます。次のコンポーネントでレンダリング時にアニメーションが使用されます。

- ファセットを公開および非公開にする場合の表の詳細ファセット

- ノードを展開および縮小する際のツリーおよびツリー表

- メニュー

- ポップアップ・セレクタ

- ダイアログ

- ノート・ウィンドウおよびメッセージの表示

使用されるアニメーションのタイプとタイミングは、アプリケーションのスキンの一部として構成されます。詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

animation-enabled要素はtrueまたはfalseに設定できます。また、trueまたはfalseに解決されるEL式を使用できます。デフォルトで、animation-enabledはtrueに設定されています。

注意:

アニメーションを有効化すると、パフォーマンスに影響します。詳細は、『パフォーマンスのチューニング』の「Oracleアプリケーション開発フレームワークのパフォーマンスのチューニング」の章を参照してください。

A.6.2.2 スキン・ファミリ

A.6.1項「trinidad-config.xmlでのADF Facesの機能の構成方法」での説明のとおり、JDeveloperでは、ADF Facesを使用するJSFアプリケーションにskyrosスキン・ファミリがデフォルトで使用されます。<skin-family>の値をfusion、simpleに変更することも、カスタム・スキン定義に変更することもできます。カスタム・スキンの作成および使用の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズの概要」を参照してください。

次のコードに示すように、スキン・ファミリ値にEL式を使用できます。

<skin-family>#{prefs.proxy.skinFamily}</skin-family>

A.6.2.3 タイムゾーンおよび年

日付を処理して表示するためのタイムゾーンと、2桁のみの年を解析するための年オフセットを設定するには、次の要素を使用します。

- <time-zone>: 値が設定されていない場合、ADF Facesではデフォルトで、アプリケーション・サーバーで使用されているタイムゾーンが使用されます。必要な場合は、TimeZoneと評価されるEL式を使用できます。この値は、文字列をDateに変換する際にorg.apache.myfaces.trinidad.converter.DateTimeConverterで使用されます。

- <two-digit-year-start>: この値は、グレゴリオ暦の年で指定します。org.apache.myfaces.trinidad.converter.DateTimeConverterで使用されて、2ケタの年のStringから日付を作成するための100年の範囲を決定します。結果のDateはtwo-digit-year-startとtwo-digit-year-start + 100の間にあります。この要素は、値が設定されない場合、デフォルトで1950年に設定されます。必要な場合は、静的整数値またはIntegerオブジェクトに評価されるEL式を使用できます。
たとえば、値が指定されていない場合は、100年の範囲はデフォルトで[1950, 2050]になり、日付01/01/10は01/01/2010に解決されます。

A.6.2.4 拡張デバッグ出力

デフォルトでは、<debug-output>要素はfalseです。<debug-output>をtrueに設定すると、ADF Facesでデバッグ出力が拡張されます。デバッグ出力に次の機能が追加されます。

- 自動インデント

- HTMLのブロックを処理したコンポーネントを識別するコメント。

- 対応していない要素、1つの要素内での同じ属性の繰り返しの使用またはその他の不適切なマークアップの問題の検出。

- 一般的なHTMLエラー(他の<form>タグ内の<form>タグ、無効な場所に使用されている<tr>タグや<td>タグなど)の検出。

パフォーマンスのヒント:

デバッグはパフォーマンスに影響します。本番環境ではこのパラメータをfalseに設定します。

A.6.2.5 ページ・アクセシビリティ・レベル

<accessibility-mode>を使用して、アプリケーションでのアクセシビリティ・サポートのレベルを定義します。サポートされている値は次のとおりです。

- default: 出力でアクセシビリティ機能がサポートされます。

- inaccessible: 出力サイズを最適化するため、アクセシビリティ固有の構成要素は削除されます。

- screenReader: スクリーン・リーダーを使用する際の動作を改善するために、アクセシビリティ固有の構成が追加されます。

注意:

スクリーン・リーダー・モードは、他のユーザーには使用しにくくなる場合があります。たとえば、アクセシビリティ・モードがスクリーン・リーダー・モードに設定されていると、アクセス・キーは表示されません。

<accessibility-profile>を使用して、アプリケーションで使用する色のコントラストやフォント・サイズを構成します。サポートされている値は次のとおりです。

- high-contrast: デフォルト・コントラストではなく高コントラストを使用してアプリケーションが表示されます。

- large-fonts: デフォルト・サイズのフォントではなく大きいフォントを使用してアプリケーションが表示されます。

複数の設定を使用するには、値を空白で区切ります。

A.6.2.6 言語読取り方向

ADF Facesのデフォルトのページ・レンダリング方向は、ブラウザで使用されている言語に基づきます。しかし、次のコードに示すように、Booleanオブジェクトに評価されるEL式、あるいはtrueまたはfalseを使用して<right-to-left>要素にデフォルト・ページ・レンダリング方向を明示的に設定できます。

<!-- Render the page right-to-left for Arabic -->
<!-- and left-to-right for all other languages -->
<right-to-left>
#{view.locale.language=='ar' ? 'true' : 'false'}
</right-to-left>

A.6.2.7 通貨コードおよび数値の桁/小数点の区切り文字

通貨フィールドの書式設定に使用する通貨コードを指定する場合、および数値の桁と小数点に使用する区切り記号を定義する場合、次の要素を使用します。

- <currency-code>: コンバータで明示的に通貨コードが指定されていない通貨フィールドの書式設定に、org.apache.myfaces.trinidad.converter.NumberConverterで使用されるデフォルトのISO 4217通貨コードを定義します。静的値またはStringオブジェクトと評価されるEL式を使用します。次に例を示します。

<!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>

- <number-grouping-separator>: 数値の桁区切りに使用される文字(カンマなど)を定義します。ADF Facesでは現在のロケールから区切り文字が自動的に導出されますが、この要素に値を指定して、デフォルトをオーバーライドできます。静的値またはCharacterオブジェクトと評価されるEL式を使用できます。設定されている場合、この値が、解析および書式設定時にorg.apache.myfaces.trinidad.converter.NumberConverterクラスで使用されます。
たとえば、アプリケーションでドイツ語が使用されている期間に数値グループ区切りを設定する場合は、次のコードを使用します。

<!-- Set the number grouping separator to period for German -->
<!-- and comma for all other languages -->
<number-grouping-separator>
#{view.locale.language=='de' ? '.' : ','}
</number-grouping-separator>

- <decimal-separator>: 小数点に使用されるセパレータ(たとえば、ピリオドやカンマなど)を定義します。ADF Facesでは現在のロケールから区切り文字が自動的に導出されますが、この要素に値を指定して、デフォルトをオーバーライドできます。静的値またはCharacterオブジェクトと評価されるEL式を使用できます。設定されている場合、この値が、解析および書式設定時にorg.apache.mtfaces.trinidad.converter.NumberConverterクラスで使用されます。
たとえば、アプリケーションでドイツ語が使用されている際に小数区切りをカンマに設定する場合は、次のコードを使用します。

<!-- Set the decimal separator to comma for German -->
<!-- and period for all other languages -->
<decimal-separator>
#{view.locale.language=='de' ? ',' : '.'}
</decimal-separator>

A.6.2.8 日付と数値ロケールの書式設定

ADF FacesおよびMyFaces Trinidadは、デフォルトでは、ローカライズされたテキストに使用されているのと同じロケール(デフォルトではブラウザのロケール)で、日付(週の最初の曜日も)と数値を書式設定します。ただし、その他のロケールで日付と数値を書式設定する場合は、IANA形式のコード(ja、fr-CAなど)を値とする<formatting-locale>要素を使用できます。この要素の内容は、IANA文字列を指すEL式またはjava.util.Localeオブジェクトです。

A.6.2.9 出力モード

ADF Facesで使用される出力モードを変更するには、次のいずれかの値を使用して<output-mode>要素を設定します。

- default: デフォルト・ページ出力モード(通常、表示)。

- printable: 印刷可能ページに適した出力モード。

- email: ページのコンテンツを電子メールするのに適した出力モード。

A.6.2.10 アクティブなPageFlowScopeインスタンスの数

ADF Facesのデフォルトでは、アクティブなPageFlowScopeインスタンスの最大数が常に15に設定されます。この数を変更するには、<page-flow-scope-lifetime>要素を使用します。その他の要素とは違い、静的な値を使用する必要があり、EL式はサポートされていません。

A.6.2.11 ファイルのアップロード

ファイルのアップロード・パラメータはweb.xmlに構成できますが、trinidad-config.xmlにファイルのアップロード・パラメータを構成すると、値の設定を変更するために実行時の検証が可能なEL式がサポートされるという利点があります。次の要素がサポートされています。

- <uploaded-file-processor>: このパラメータは、org.apache.myfaces.trinidad.webapp.UploadedFileProcessorインスタンスを実装するクラスの名前にする必要がありますが、このインスタンスにより、個々のアップロード・ファイルが着信リクエストから取得される際に処理され、そのコンテンツを残りのリクエストで使用できるようになります。ほとんどの開発者とっては、デフォルトのUploadedFileProcessorで十分ですが、大規模ファイルのアップロードをサポートする必要のあるアプリケーションでは、リクエスト中にApache Trinidadで一時記憶域を処理するかわりに、ファイルをただちに最終的な宛先に格納することでパフォーマンスが向上します。

- <uploaded-file-max-memory>: ディスクへのデータの書込みが開始されるまでに、ファイルのアップロード・プロセス中に使用されるメモリーの最大量を設定するために使用します。この設定は、web.xmlのorg.apache.myfaces.trinidad.UPLOAD_MAX_MEMORYの設定を直接オーバーライドします。この値は、ハードコードすることも、Longオブジェクトを戻すEL式を使用して明示的に構成することも可能です。

- <uploaded-file-max-disk-space>: EOFExceptionがスローされるまでに、アップロード・ファイルが使用できるディスク領域の最大量を設定するために使用します。この設定は、web.xmlのorg.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACEの設定を直接オーバーライドします。この値は、ハードコードすることも、Longオブジェクトを戻すEL式を使用して明示的に構成することも可能です。

- <uploaded-file-max-disk-space>: アップロード・ファイルが格納されるデフォルトの場所を変更するために使用します。この設定は、web.xmlのorg.apache.myfaces.trinidad.UPLOAD_TEMP_DIRの設定を直接オーバーライドします。この値は、ハードコードすることも、Stringオブジェクトを戻すEL式を使用して明示的に構成することも可能です。

A.6.2.12 カスタム・ファイル・アップロード・プロセッサ

大半のアプリケーションでは、ADF Facesで用意されているデフォルトのUploadedFileProcessorインスタンスを置き換える必要はありません。しかし、アプリケーションで非常に大きなファイルのアップロードをサポートする必要がある場合、またはファイルのアップロードに大きく依存する場合、デフォルト・プロセッサをカスタムUploadedFileProcessor実装で置き換えることができます。

たとえば、ADF Facesでリクエスト時に一時格納を処理するかわりに、最終的な格納場所にファイルを即座に格納する実装を使用することにより、パフォーマンスを向上させることができます。デフォルト・プロセッサを置き換えるには、次のコードに示すように、<uploaded-file-processor>要素を使用してカスタム実装を指定します。

<uploaded-file-processor>
com.mycompany.faces.myUploadedFileProcessor
</uploaded-file-processor>

A.6.2.13 クライアント側検証および変換

ADF Facesのバリデータとコンバータでは、サーバー側の検証および変換と同様に、クライアント側の検証および変換がサポートされます。ADF Facesのクライアント側のバリデータおよびコンバータは、サーバー側のバリデータおよびコンバータと同じように動作しますが、クライアントではJavaScriptが使用されます。

JavaScript対応のバリデータとコンバータは、フォームの送信時にクライアントで実行されるため、サーバーへのラウンドトリップなしにエラーが捕捉されます。

リッチ・クライアント版のADF Facesでは、<client-validation-disabled>構成要素はサポートされていません。つまり、ADF Facesアプリケーションでは、クライアント側検証と変換を無効にできません。

A.6.3 システム・プロパティの構成に関する必知事項

Trinidad構成オプションの一部は、システム・プロパティによって設定されます。高可用性テストをサポートするには、org.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATIONを使用します。システム・プロパティで、次のものを含む、大/小文字が区別されないカンマ区切りの一連の値を渡します。

- NONE: 状態のシリアライズ・チェックは実行されません(デフォルト)。

- ALL: 使用可能なすべてのテストを実行します(NONEが優先されるため、NONEも指定されている場合は除きます)。

- SESSION: シリアライズ可能なオブジェクトのみがセッション・マップに配置されていることをテストするために、ExternalContextにより戻されたセッション・マップをラップし、オブジェクトがシリアライズ可能でない場合はCastCastExceptionをスローします。

- TREE: 状態保存中にコンポーネントの状態のシリアライズを積極的に試行し、シリアライズに失敗した場合は例外をスローします。

- COMPONENT: 問題のあるコンポーネント(遅い)を識別するために、状態保存中に、各コンポーネント・サブツリーの状態のシリアライズを積極的に試行します。

- PROPERTY: 問題のあるプロパティ(遅い)を識別するために、状態保存中に、各プロパティ値のシリアライズを積極的に試行します。

たとえば、セッションとJSFの状態がシリアライズ可能な場合は、システム・プロパティを次のように設定することで、テスターが検証を開始します。

-Dorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION=session,tree

JSFの状態のシリアライズが検出された場合は、次のように、コンポーネントとプロパティのフラグが有効化された状態でテストが再実行されます。

-Dorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION=all

A.7 trinidad-skins.xmlでの構成

JDeveloperでは、ADF Facesコンポーネントを使用してJSFページを作成する場合、skyrosスキン・ファミリがデフォルトで使用されます。A.6.1項「trinidad-config.xmlでのADF Faces機能の構成方法」で説明されているように、スキン・ファミリは、trinidad-config.xmlファイルに構成されています。アプリケーションでカスタム・スキンを使用する場合は、アプリケーションへのカスタム・スキンの登録に使用するtrinidad-skins.xmlファイルを作成します。

カスタム・スキンの作成の詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズの概要」を参照してください。

A.8 RequestContext EL暗黙オブジェクトの使用

ADF Facesでは、EL暗黙オブジェクトrequestContextを使用して、trinidad-config.xmlファイルで定義されている構成プロパティから値を取得できます。requestContext暗黙オブジェクトはorg.apache.myfaces.trinidad.context.RequestContextクラスのインスタンスで、java.util.Mapタイプのいくつかのプロパティを公開して、JSF EL式によるコンテキスト・オブジェクト・プロパティ値の取得を可能にします。

たとえば、EL式#{requestContext}はRequestContextオブジェクト自体を返し、EL式#{requestContext.skinFamily}は、<skin-family>要素の値をtrinidad-config.xmlファイルから返します。

EL式を使用して、コンポーネント属性値をrequestContext暗黙オブジェクトのプロパティにバインドすることもできます。たとえば、次のEL式では、<currency-code>プロパティがJSF ConvertNumberコンポーネントのcurrencyCode属性値にバインドされています。

<af:outputText>
<f:convertNumber currencyCode="#{requestContext.currencyCode}"/>
</af:outputText>

次に示す、requestContext暗黙的オブジェクト・プロパティを使用できます。

- requestContext.accessibilityMode: <accessibility-mode>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.agent: リクエストを行っているクライアント・エージェントを示し、レンダリングされた出力を表示するオブジェクトを返します。agentオブジェクトのプロパティは次のとおりです。

- agentName: エージェント・ブラウザの正規の名前(gecko、ieなど)。

- agentVersion: エージェント・ブラウザのバージョン番号。

- capabilities: 現在のクライアント・リクエストに対する機能名(高さ、幅など)とその値をマップします。

- hardwareMakeModel: ハードウェア・メーカーとモデルの正規の名前(nokia6600、sonyericssonP900など)。

- platformName: プラットフォームの正規の名前(ppc、windows、macなど)。

- platformVersion: プラットフォームのバージョン番号。

- type: エージェント・タイプ(desktop、pda、phoneなど)。

- requestContext.clientValidationDisabled: <client-validation-disabled>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.colorPalette: カラー・パレット名をキーとし、カラー・パレットを結果として返すMapを返します。各カラー・パレットは、java.awt.Colorオブジェクトの配列です。4つの標準カラー・パレットへのアクセスを提供します。

- web216: 216のWebセーフ・カラー

- default49: 全透明のエントリを1つ含む49色のパレット

- opaque40: 全透明のエントリを含まない49色のパレット

- default80: 全透明のエントリを1つ含む80色のパレット

- requestContext.currencyCode: <currency-code>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.debugOutput: <debug-output>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.decimalSeparator: <decimal-separator>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.formatter: 再帰的Map構造を使用してメッセージを書式設定するMapオブジェクトを返します。最初のキーはメッセージの書式設定マスクで、2番目のキーはメッセージの最初のパラメータです。

- requestContext.helpSystem: ヘルプ・システム・プロパティをキーとして受け入れ、URLを結果として返すMapオブジェクトを返します。たとえば、EL式#{requestContext.helpSystem['frontPage']}は、ヘルプ・システムのフロント・ページへのURLを返します。trinidad-config.xmlファイルに<oracle-help-servlet-url>要素を構成してあることを前提とします。

- requestContext.helpTopic: トピック名をキーとして受け入れ、URLを結果として返すMapオブジェクトを返します。たとえば、EL式#{requestContext.helpTopic['foo']}は、ヘルプ・トピックfooへのURLを返します。trinidad-config.xmlファイルに<oracle-help-servlet-url>要素を構成してあることを前提とします。

- requestContext.numberGroupingSeparator: <number-grouping-separator>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.oracleHelpServletUrl: <oracle-help-servlet-url>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.outputMode: <output-mode>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.pageFlowScope: pageFlowScopeオブジェクトでのオブジェクトのマップを返します。

- requestContext.rightToLeft: <right-to-left>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.skinFamily: <skin-family>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.timeZone: <time-zone>要素の値をtrinidad-config.xmlファイルから返します。

- requestContext.twoDigitYearStart: <two-digit-year-start>要素の値をtrinidad-config.xmlファイルから返します。

プロパティの完全なリストについては、Oracle ADF Faces Java APIリファレンスのorg.apache.myfaces.trinidad.context.RequestContextを参照してください。

注意:

リクエストごとに、org.apache.myfaces.trinidad.context.RequestContextクラスのインスタンスが1つ存在します。RequestContextクラスは、JSF FacesContextクラスを拡張しません。

構成プロパティをプログラムで取得するには、次のコードに示すように、まず、静的getCurrentInstance()メソッドをコールしてRequestContextオブジェクトのインスタンスを取得し、目的のプロパティを取得するメソッドをコールします。

RequestContext context = RequestContext.getCurrentInstance();

// Get the time-zone property
TimeZone zone = context.getTimeZone();

// Get the right-to-left property
if (context.isRightToLeft())
{
.
.
.
}

A.9 パフォーマンス・チューニング

『パフォーマンスのチューニング』の「Oracle Application Development Frameworkのパフォーマンス・チューニング」の章には、特定の構成オプションに関連するパフォーマンスのヒントに加え、パフォーマンス・チューニングに関する詳細も記載されています。

B コンバータおよびバリデータ・メッセージのメッセージ・キー

この付録では、ADF Facesのコンバータおよびバリデータのすべてのメッセージ・キーおよびメッセージ・セッター・メソッドをリストします。

この章では、次の項目について説明します。

- B.1項「ADF Facesのデフォルト・メッセージについて」

- B.2項「メッセージ・キーおよびセッター・メソッド」

- B.3項「コンバータおよびバリデータのメッセージ・キーおよびセッター・メソッド」

B.1 ADF Facesのデフォルト・メッセージについて

FacesMessageクラスでは、サマリー・メッセージと詳細メッセージの両方がサポートされます。規則は次のとおりです。

- サマリー・メッセージはメイン・キーに対して定義されます。キー値の形式は、classname.MSG_KEYです。

- 詳細メッセージの形式は、classname.MSG_KEY_detailです。

簡単に言うと、詳細メッセージをオーバーライドするには、適切なクラスのセッター・メソッドを使用するか、必要なメッセージ・キーを使用してリソース・バンドルに置き換えるメッセージを入力します。

メッセージ文字列をインスタンスごとに変更するかわりに、メッセージ文字列をグローバルにオーバーライドすることもできます。カスタム文字列がすべてのインスタンスで使用可能になるよう、メッセージ・バンドルを使用します。コンバータおよびバリデータのデフォルトのエラー・メッセージをグローバルにオーバーライドする方法の詳細は、19.3.2項「コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法」を参照してください。

ユーザーが入力した値やメッセージ用のコンポーネントのラベルなどの関連する詳細の指定に、詳細メッセージではプレースホルダが使用されます。プレースホルダ識別子の一般的な順序は次のとおりです。

- コンポーネント・ラベル

- 入力値(存在する場合)

- 最小値(存在する場合)

- 最大値(存在する場合)

- パターン(存在する場合)

また、メッセージ・バンドルを使用して、アプリケーション・レベルでメッセージ文字列をグローバルに設定することも可能です。詳細は、19.3.2項「コンポーネントの全インスタンスのバリデータおよびコンバータのカスタム・メッセージの定義方法」を参照してください。

B.2 メッセージ・キーおよびセッター・メソッド

ADF Facesの各コンバータおよびバリデータについて、次の情報が提供されます。

- メッセージのオーバーライドに使用できるsetメソッド。

- リソース・バンドルで独自のメッセージの識別に使用できるメッセージ・キー。

- 入力値やパターンなどの詳細を含むプレースホルダのメッセージでの使用方法。

B.3 コンバータおよびバリデータのメッセージ・キーおよびセッター・メソッド

次のサブセクションでは、すべてのADF Facesコンバータおよびバリデータの詳細メッセージのリファレンスの詳細を説明します。

B.3.1 af:convertColor

色の値を表す文字列とjava.awt.Colorオブジェクトとの間の変換を行います。変換に使用されるパターンのセットはオーバーライドできます。

色の変換: 入力値はパターン・セットに基づく色に変換できません

setメソッド:

setMessageDetailConvert(java.lang.String convertBothMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.ColorConverter.CONVERT_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 色の例

B.3.2 af:convertDateTime

パターンとスタイル・セットに基づき、文字列とjava.util.Dateとの間の変換を行います。

日時の変換: typeがbothに設定されている場合、日付オブジェクトに変換できない日時の値

setメソッド:

setMessageDetailConvertBoth(java.lang.String convertBothMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.DateTimeConverter.CONVERT_BOTH_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータで想定されている書式の例
日にちの変換: パターンやセカンダリ・パターンが設定されている場合、またはtypeがdateに設定されている場合は、入力値を日にちに変換できません

setメソッド:

setMessageDetailConvertDate(java.lang.String convertDateMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.DateTimeConverter.CONVERT_DATE_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータで想定されている書式の例
日にちの変換: パターンやセカンダリ・パターンが設定されている場合、またはtypeがtimeに設定されている場合は、入力値を日にちに変換できません

setメソッド:

setMessageDetailConvertTime(java.lang.String convertTimeMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.DateTimeConverter.CONVERT_TIME_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータで想定されている書式の例

B.3.3 af:convertNumber

javax.faces.convert.NumberConverter標準JSFクラスの拡張が提供されます。コンバータでは、デフォルトNumberConverterのすべての標準機能が提供され、オブジェクトへの変換は厳密です。

数値の変換: パターン・セットに基づき、入力値はNumberに変換できません

setメソッド:

setMessageDetailConvertPattern(java.lang.String convertPatternMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_PATTERN_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 指定された変換パターン
数値の変換: typeがnumberに設定されている場合、およびpatternがnullか設定されていない場合は、入力値を数値に変換できません

setメソッド:

setMessageDetailConvertNumber(java.lang.String convertNumberMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_NUMBER_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
数値の変換: typeがcurrencyに設定されている場合、およびpatternがnullか設定されていない場合は、入力値を数値に変換できません

setメソッド:

setMessageDetailConvertCurrency(java.lang.String convertCurrencyMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_CURRENCY_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
数値の変換: typeがpercentに設定されている場合、およびpatternがnullか設定されていない場合は、入力値を数値に変換できません

setメソッド:

setMessageDetailConvertPercent(java.lang.String convertPercentMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_PERCENT_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値

B.3.4 af:validateByteLength

エンコード時に文字列のバイト数が検証されます。

バイト長の検証: 入力値が最大バイト長を超えています

setメソッド:

setMessageDetailMaximum(java.lang.String maximumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.ByteLengthValidator.MAXIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 最大長

B.3.5 af:validateDateRestriction

特定の制限に対して日付が有効かどうかが検証されます。

日付制限の検証 - 無効な日付: invalidDateがinvalidDaysのリスト内にある場合、入力値は無効です

setメソッド:

setMessageDetailInvalidDays(java.lang.String invalidDays)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateRestrictionValidator.WEEKDAY_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 無効な日付
日付制限の検証 - 無効な曜日: 値がinvalidDaysOfWeekに指定される曜日のいずれかである場合、入力値は無効です

setメソッド:

setMessageDetailInvalidDaysOfWeek(java.lang.String invalidDaysOfWeek)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateRestrictionValidator.DAY_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 無効な曜日
日付制限の検証 - 無効な月: 値にinvalidMonthsに指定された月がある場合、入力値は無効です

setメソッド:

setMessageDetailInvalidMonths(java.lang.String invalidMonths)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateRestrictionValidator.MONTH_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 無効な月

B.3.6 af:validateDateTimeRange

入力された日付が、指定された範囲内かどうかが検証されます。

日付時間範囲の検証: 入力値が、設定されたmaximum値を超えています

setメソッド:

setMessageDetailMaximum(java.lang.String maximumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateTimeRangeValidator.MAXIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 日付の最大値
日付時間範囲の検証: 入力値が、設定されたminimum値を下回っています

setメソッド:

setMessageDetailMinimum(java.lang.String minimumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateTimeRangeValidator.MINIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 日付の最小値
日付時間範囲の検証: minimumおよびmaximumが設定されていますが、入力値がその範囲を超えています

setメソッド:

setMessageDetailNotInRange(java.lang.String notInRangeMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DateTimeRangeValidator.NOT_IN_RANGE_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 日付の最小値
{3} 日付の最大値

B.3.7 af:validateDoubleRange

入力された値が、指定された範囲内かどうかが検証されます。

Double範囲の検証: 入力値が、設定されたmaximum値を超えています

setメソッド:

setMessageDetailMaximum(java.lang.String maximumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DoubleRangeValidator.MAXIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 値の最大値
Double範囲の検証: 入力値が、設定されたminimum値を下回っています

setメソッド:

setMessageDetailMinimum(java.lang.String minimumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DoubleRangeValidator.MINIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 値の最小値
Double範囲の検証: minimumおよびmaximumが設定されていますが、入力値がその範囲を超えています

setメソッド:

setMessageDetailNotInRange(java.lang.String notInRangeMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.DoubleRangeValidator.NOT_IN_RANGE_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 値の最小値
{3} 値の最大値

B.3.8 af:validateLength

入力された値が、指定された範囲内かどうかが検証されます。

長さの検証: 入力値が、設定されたmaximum値を超えています

setメソッド:

setMessageDetailMaximum(java.lang.String maximumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.LengthValidator.MAXIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 最大長
長さの検証: 入力値が、設定されたminimum値を下回っています

setメソッド:

setMessageDetailMinimum(java.lang.String minimumMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.LengthValidator.MINIMUM_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 最小長
長さの検証: minimumおよびmaximumが設定されていますが、入力値がその範囲を超えています

setメソッド:

setMessageDetailNotInRange(java.lang.String notInRangeMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.LengthValidator.NOT_IN_RANGE_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 最小長
{3} 最大長

B.3.9 af:validateRegExp

Javaの正規表現構文を使用した式を検証します。

正規表現の検証: 入力値が指定されたパターンと一致しません。

setメソッド:

setMessageDetailNoMatch(java.lang.String noMatchMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.validator.RegExpValidator.NO_MATCH_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} 想定されているパターン

C キーボード・ショートカット

この付録では、ポインティング・デバイスのかわりに使用できるキーボード・ショートカットについて説明します。

この付録には次の項が含まれます:

- C.1項「キーボード・ショートカットについて」

- C.2項「タブのトラバース」

- C.3項「ショートカット・キー」

- C.4項「デフォルトのカーソルまたはフォーカスの配置」

- C.5項「[Enter]キー」

C.1 キーボード・ショートカットについて

ポインティング・デバイスのかわりにキーボード・ショートカットを使用してページのナビゲートを行えます。ADF Facesアプリケーションで提供されるキーボード・ショートカットには次の5つのタイプがあります。

- [Tab]キーおよび[Shift]+[Tab]キーを使用したタブのトラバース: 画面上のUI要素間でフォーカスを移動します。

- アクセラレータ・キー(ホット・キー): メニューおよびページ・ナビゲーションを省略し、操作を直接実行します([Ctrl]+[C]によるコピーなど)。

- アクセス・キー: [Alt]+[F]で「ファイル」メニューに移動するなど、フォーカスを特定のUI要素に移動します。

- デフォルトのカーソル/フォーカスの位置: 1つのコンポーネントに初期フォーカスされているため、キーボード・ユーザーはあまり移動せずにページとの対話操作を開始できます。

- [Enter]キー: カーソルが特定のフィールドに置かれたり、フォーカスがリンクまたはボタンに置かれるとアクションが起動されます。

キーボード・ショートカットはアクセシビリティには必要ありません。ユーザーはキーボード・ショートカットなしで、[Tab]や矢印キーを使用して、アプリケーションのすべての部分および機能に移動できる必要があります。キーボード・ショートカットは、機能に迅速にアクセスするための追加の方法を提供するものです。

C.2 タブのトラバース

タブのトラバースを使用すると、ユーザーはページ上の様々なUI要素にフォーカスを移動できます。

タブのトラバースによって、つまり[Tab]キーを使用して次のコントロールに移動し、[Shift]+[Tab]を使用して前のコントロールに移動することで、ページのすべてのアクティブな要素にアクセスできます。多くの場合、コントロールにフォーカスがあるときに[Enter]を押すとアクションを開始できます。

複雑なコンポーネントでは、[Tab]キーを使用してコンポーネントにフォーカスを置いた後で、矢印キーを使用して移動する場合もあります。

C.2.1 ページでのタブのトラバース順序

デフォルトのタブのトラバースの順序は、図C-1に示すように左から右、上から下です。2列のフォーム・レイアウトのタブのトラバースは、このパターンには従わず、列パターンに従って行われます。最下部に到達すると、タブの順序は上部から再度繰り返されます。

図C-1 ページでのタブのトラバース順序

結果のページの管理が難しくなりすぎて、1つのアプリケーションおよびアプリケーション間で、ページ全体のユーザー操作に一貫性がなくなる可能性があるため、タブのトラバース順序の管理にカスタム・コードを使用しないようにしてください。

ユーザーのキーボード・ナビゲーションの効率を向上するには、ドキュメントにinitialFocusId属性を設定する必要があります。アクセシビリティを目的として、skipLinkTargetを定義し、コンテンツ関連タブの最初のストップに直接移動するskip navigationリンクをページ上部に含める必要もあります。

C.2.2 表でのタブのトラバース順序

表でのタブのトラバースは、あるセルから別のセルへ順番に移動するために、ユーザーが[Tab]キーを押した場合に、行全体の独自のナビゲーション・パターンを確立します。ユーザーが[Enter]を押すと、フォーカスが次の行に移り、同じパターンに従います。ナビゲーション順序は、前の行と同じように、同じ列内で開始して終了します。

図C-2に、表におけるタブのトラバース順序の例を示します。

図C-2 表でのタブのトラバース順序

図C-2で、ユーザーは次のように行を移動しました。

1. ユーザーが「inputText」列のセルをクリックし、そのセルがフォーカスされ、編集可能になりました。
[Tab]キーを使用して移動したため、「inputText」列がナビゲーション・パターンの開始列と認識されました。

2. ユーザーが[Tab]キーを押し、フォーカスが同じ行の「* Required field」列のセルに移動しました。

3. ユーザーが[Tab]キーを押し、フォーカスが同じ行の「inputComboListOf」列のセルに移動しました。

4. ユーザーが[Enter]キーを押し、フォーカスが次の行の「inputText」列に移動しました。
ユーザーが編集可能なフィールドで[Enter]キーを押すと、フォーカスが次の行の編集可能な最初のフィールドに移動し、最初に押された[Tab]キーのセットに基づいてナビゲーション・パターンが設定され、このパターンは後続の行でも継承されます。

注意:

あるセルから別のセルへの移動に矢印キーを使用した場合、ナビゲーション・パターンは認識されません。

C.3 ショートカット・キー

ADF Facesには、特定アプリケーションへの固有のキーボード・ショートカットの作成を可能にするコンポーネント属性だけでなく、それ自体に様々なキーボード・ショートカットが用意されています。ADF Facesでは、アクセラレータ・キーとアクセス・キーという2つのタイプに、コンポーネントのショートカット・キーが分類されます。

C.3.1 アクセラレータ・キー

アクセラレータ・キーを使用すると、メニューやページのナビゲーションを経由せずにアクションを直接実行できます。アクセラレータ・キーは、ホット・キーと呼ばれることもあります。Internet ExplorerなどのWindowsアプリケーションには、[Ctrl]+[O]で開く、[Ctrl]+[P]で印刷などの共通のアクセラレータ・キーがあります。

アクセラレータ・キーは、キーを1回押す([Enter]および[Esc])またはキーの組合せ([Ctrl]+[A]など)によって、アクティブになるとすぐにアクションが開始します。キーの組合せはメタ・キーと実行キーで構成されます。[Ctrl](Macintoshキーボードでは[Command])、[Alt](Macintoshキーボードでは[Option])または[Shift]をメタ・キーにすることができます。実行キーはメタ・キーと組み合せて押されるキーです。

ADF Facesの一部のコンポーネントには、独自のアクセラレータ・キーが組み込まれています。たとえば、[Ctrl]+[Alt]+[M]は、コンテキスト・メニューを開くアクセラレータ・キーです。独自のアクセラレータ・キーが組み込まれているADF Facesコンポーネントの詳細は、コンポーネント・タグのドキュメントを参照してください。

ADF Facesでは、図C-3に示すように、特定のメニュー項目に対してカスタムのアクセラレータ・キーを作成することも可能です。メニューを開くと、割り当てられたすべてのメニューのアクセラレータ・キーが表示され、通常モードでもスクリーン・リーダー・モードでも使用できます。

図C-3 メニューのアクセラレータ・キー

アクセラレータ・キーを定義する際には、次のガイドラインに従う必要があります。

- アクセラレータ・キーはアクションを直接実行するため、ユーザーがアクセラレータ・キーを気付かずに押すと、データが失われたり、不適切なデータが入力されたりする可能性があります。ユーザーのエラーが発生する可能性を低くするため、アクセラレータ・キーは慎重に、アプリケーション全体で頻繁および繰り返し使用される機能にのみ使用する必要があります。原則として、アクセラレータ・キーを設定するのは使用可能な機能の25%未満にしてください。

- ADF Facesがサポートされたブラウザのメニューで使用されるアクセラレータ・キーを、カスタムのアクセラレータ・キーでオーバーライドすることはできず(ADF Facesでサポートされるオペレーティング・システムとブラウザについては、ブラウザおよびシステム要件を参照)、スクリーン・リーダーなどの支援技術で使用されるアクセラレータ・キーをオーバーライドすることもできません。

- カスタム・メニューのアクセラレータ・キーは、常にキーの組合せになります。メタ・キーには、[Ctrl]、[Ctrl]+[Shift]または[Ctrl]+[Alt]を使用できます。[Ctrl]および[Ctrl]+[Shift]はブラウザでよく使用されるため、メタキーには[Ctrl]+[Alt]が最もよく使用されます。実行キーは、印刷可能な文字である必要があります(ASCIIコード33から126)。

- カスタム・メニューのアクセラレータ・キーは、一意であることが必要です。1つのページ内の異なるコンポーネントで同じアクセラレータが使用されていると、ブラウザがそのアクセラレータでどのアクションが実行されるかを予測するのが常に困難になります。

注意:

Windowsの場合、ユーザーは[Ctrl]+[Alt]+文字キーの順番をアプリケーションのデスクトップ・ショートカットに割り当てることができます。この場合、このキー割当てがブラウザレベルのキーのキー割当てをオーバーライドします。ただし、この機能はめったに使用されないため通常は無視されます。

一部のADF Facesコンポーネントには、コンポーネントにフォーカスがあるときに適用されるアクセラレータ・キーが組み込まれています。そのうちの一部はページレベルのコンポーネントに予約されていますが、その他はそのコンポーネントがページに使用されていなければメニューに割り当てることができます。表C-1に、ページレベルのADF Facesコンポーネントにすでに組み込まれているアクセラレータ・キーをリストします。これらのアクセラレータ・キーは使用しないでください。

表C-1 ページレベルのコンポーネントに予約されたアクセラレータ・キー

アクセラレータ・キー

使用箇所

機能

[Ctrl]+[Alt]+[W]

[Ctrl]+[Shift]+[W]

ポップアップ

メッセージング

2次ウィンドウ

開いているポップアップ間でフォーカスを切り替えます。

[Ctrl]+[Alt]+[P]

スプリッタ

スプリッタ・バーにフォーカスを移動します。

同じページにページレベル・コンポーネントとして存在し、アクセラレータ・キーが同一の場合は、メニュー・コマンドが優先されます。このため、同じページに関連コンポーネントも表示される場合は、表C-3および表C-8にリストされているアクセラレータ・キーをメニューで使用するのは避ける必要があります。

C.3.2 アクセス・キー

アクセス・キーは、ADF FacesコンポーネントのaccessKeyプロパティで定義されており、フォーカスを特定のUI要素に移動します。

アクセス・キーにより、カーソルまたは選択のフォーカスを特定のインタフェース・コンポーネントに移動できます。定義可能なフォーカスのあるページ上の各コンポーネントは、タブのトラバース([Tab]および[Shift]+[Tab]を使用)でアクセスできますが、アクセス・キーを使用すると、頻繁に使用されるコンポーネントに迅速にアクセスできます。アクセス・キーはページ内で一意であることが必要です。

アクセス・キーをトリガーした結果は、関連付けられた要素およびブラウザによって異なります。

- ボタン: FirefoxおよびInternet Explorerでアクセス・キーを使用すると、コンポーネントにフォーカスが移動して直接アクションが実行されます。Internet Explorer 7のアクセス・キーは、コンポーネントにフォーカスしますが、アクションを実行しないことに注意してください。

- リンク: Firefoxでアクセス・キーを使用すると、コンポーネントにフォーカスが移動して直接リンクにナビゲートします。Internet Explorerでアクセス・キーを使用した場合は、フォーカスがリンクに移動するだけです。

- その他の要素: どちらのブラウザでアクセス・キーを使用した場合も、フォーカスが要素に移動するだけです。チェック・ボックス・コンポーネントの場合、アクセス・キーはチェック・ボックスの選択を切り替えます。オプション・ボタンでは、アクセス・キーは、オプション・ボタンの選択を実行します。

オペレーティング・システムが異なり、ブラウザが異なると、アクセス・キーも変わることに注意してください。アクセス・キーおよびその動作の詳細は、ブラウザのドキュメントを参照する必要があります。表C-2に、いくつかの一般的なブラウザのボタン・コンポーネントおよびアンカー・コンポーネントのアクセス・キーの組合せをリストします。

表C-2 様々なブラウザのアクセス・キー

ブラウザ

オペレーティング・システム

キーの組合せ

アクション

Google Chrome

Linux

[Alt]+ニーモニック

クリック

Google Chrome

Mac OS X

[Control]+[Option]+ニーモニック

クリック

Google Chrome

Windows

[Alt]+ニーモニック

クリック

Mozilla Firefox

Linux

[Alt]+[Shift]+ニーモニック

クリック

Mozilla Firefox

Mac OS X

[Ctrl]+ニーモニック

クリック

Mozilla Firefox

Windows

[Alt]+[Shift]+ニーモニック

クリック

Microsoft Internet Explorer 7

Windows

[Alt]+ニーモニック

フォーカスの設定

Microsoft Internet Explorer 8

Windows

[Alt]+ニーモニック

クリックまたはフォーカスの設定

Apple Safari

Windows

[Alt]+ニーモニック

クリック

Apple Safari

Mac OS X

[Control]+[Option]+ニーモニック

クリック

注意:

- バージョンの異なるブラウザでは、同じアクセス・キーでも動作が異なる場合があります。たとえば、Internet Explorer 7のボタン・コンポーネントに[Alt]+ニーモニックを使用すると、コンポーネントにフォーカスが設定されますが、Internet Explorer 8ではクリック・アクションがトリガーされます。

- Firefoxの場合、アクセス・キーの組合せを使用する際にコンポーネントのデフォルトの動作を変更するには、accessibility.accesskeycausesactivationユーザー・プリファレンスの構成設定を変更します。

- Buttonという名前の一部のADF Facesコンポーネントでは、HTMLのボタン要素が使用されません。たとえば、af:buttonでは、アンカーHTML要素が使用されます。

ニーモニックがコンポーネント・ラベルまたはプロンプトのテキストに存在する場合(メニュー名、ボタンのラベルまたはテキスト・ボックスのプロンプトなど)、図C-4に示すように下線付き文字としてインタフェースに表示されます。文字がラベルまたはプロンプトのテキストの一部でない場合は、インタフェースに表示されません。

図C-4 アクセス・キー

アクセス・キーを定義する際には、次のガイドラインに従う必要があります。

- アクセス・キーは、使用頻度の高いボタンおよびその他のコンポーネントに使用します。保存や取消などの共通するアクションに、クロスアプリケーションの標準的なキー割当てを設定できます。これらの各ボタンには保存はS、取消はCなど、各言語で標準的なニーモニック文字が割り当てられます。

- 1つの文字または記号は、1つのページのアクションの単一のインスタンスにのみ割り当てることができます。1つのページに、同じニーモニックを使用するボタンのインスタンスが複数あると、ユーザーがどのボタンでアクセス・キーが起動されるかわからなくなる可能性があります。

- アクセス・キーで開始されるフォーカス変更には、マウスでの直接処理(ボタンをクリックする)など、別の操作が必要になります。

- ニーモニックは句読点や記号ではなく英数字にする必要があり、常に大文字と小文字は区別されません。ニーモニックには、数字より文字を使用することをお薦めします。

- Internet Explorerでは、アプリケーションのアクセス・キーがブラウザ固有のメニュー・アクセス・キー(「ファイル」メニューの[Alt]+[F]など)をオーバーライドするため、習慣的にブラウザのアクセス・キーを使用するユーザーにユーザビリティの問題が生じる場合があります。このため、ADF Facesがサポートされたブラウザでは、トップレベルのアクセス・キーと競合するアクセス・キーの使用を避ける必要があります(Windows XP用英語版Internet Explorerでは、[Alt]+[F]、[E]、[V]、[A]、[T]または[H]など)。

- 特定のコンポーネントにアクセス・キーを割り当てる必要があります。アクセス・キーの文字を選択する場合に、重要な考慮事項がいくつかあります。

- 学習容易性: ラベルに下線付き文字を使用することで、ユーザーにはどの文字がアクセス・キーかが明確に示されますが、ラベルを見なくてもユーザーが簡単に覚えられるような文字を選択してください。たとえば、YesのYのようなラベルの最初の文字、またはNextのxのようにラベルを読み上げたときに強く発音される文字です。

- 一貫性: 複数ページで同じコマンドには同じアクセス・キーを使用することをお薦めします。ただし、同じコマンド・ラベルが1つのページに複数回表示されたり、そのページでより頻繁に使用される別のコマンドに同じアクセス・キーが使用されている場合があるため、これは常に可能とはかぎりません。

- 翻訳: ラベルを翻訳すると英語でアクセス・キーに使用されている文字が翻訳に存在しない場合があります。開発者は、ローカライゼーション部門と連携して、翻訳後のコンポーネント・ラベルにかわりのアクセス・キーが存在することを確認する必要があります。たとえば、英語ではNextボタンにニーモニック文字xを割り当てることができますが、ラベルをフランス語でSuivantesに翻訳すると、この文字はラベルには表示されません。どの文字が使用可能かによって、Sまたはv(またはSuivantesという単語の中で割当てがされていないその他の文字)などのかわりの文字を翻訳された用語に割り当てる必要があります。

注意:

翻訳上の理由により、アクセス・キーはラベルの一部として指定する必要があります。たとえば、CancelというラベルをCというアクセス・キーでレンダリングする場合は、accessKeyプロパティでCを使用するのではなく、textAndAccessKeyプロパティで&Cancelを使用してください(ここでアンパサンドはニーモニックを示します)。製品スイートではサポートされる各言語内でアクセス・キーが重複しないこと、および明示的に意図する場合を除き、サポートされる各ブラウザ内のアクセス・キーをオーバーライドしないことを確認する必要があります。

C.3.3 一般的なコンポーネントのショートカット・キー

表C-3に、メニュー、メニュー・バー、複数選択の選択リスト、複数選択のリスト・ボックスなどの一般的なコンポーネントに割り当てられたショートカット・キーをリストします。

表C-3 一般的なコンポーネントに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Enter]

[Space]

すべてのコンポーネント

コンポーネントをアクティブ化するか、またはフォーカスの配置されたコンポーネント要素をアクティブ化します。

[Tab]

[Shift]+[Tab]

すべてのコンポーネント

ThematicMap、GraphおよびGaugeなどのFlashコンポーネント

フォーカスを次の、または前の編集可能なコンポーネントに移動します。

[Ctrl]+[A]

すべてのコンポーネント

すべてを選択します。

[Alt]+[↓]

複数選択の選択肢リスト

複数選択のリスト・ボックス

リストを開きます。

矢印キーを使用して移動し、[Enter]または[Space]を押して選択します。

[Ctrl]+[Shift]+[Home]

[Ctrl]+[Shift]+[End]

複数選択の選択肢リスト

複数選択のリスト・ボックス

すべての項目を一番上から現在の選択箇所まで選択するか、すべての項目を現在の選択箇所から一番下まで選択します。

[←]

[→]

メニュー・バー

スプリッタ

入力数値スライダ

入力範囲スライダ

入力数値スピンボックス

メニュー・バーの異なるメニューにフォーカスを移動します。

フォーカス時にスプリッタを左右に移動します。

入力数値スライダまたは入力範囲スライダのフォーカス時にスライダを左右に移動します。

入力数値スピンボックスのフォーカス時に値を増分または減分します。

[↑]

[↓]

メニュー

スプリッタ

入力数値スライダ

入力範囲スライダ

メニュー内の異なるメニュー項目にフォーカスを移動します。

フォーカス時にスプリッタを上下に移動します。

入力数値スライダまたは入力範囲スライダのフォーカス時にスライダを上下に移動します。

C.3.4 ウィジェットのショートカット・キー

表C-4に、表示コントロール、階層コントロール、ドロップダウン・リストなどの一般的なウィジェットに割り当てられたショートカット・キーを示します。

表C-4 一般的なウィジェットに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Enter]

[↓][↑]

表示コントロール

閉じている表示コントロールを開くか、または開いている表示コントロールを閉じます。

表示コントロールとは、表示または非表示にできる追加のコンテンツがあることを示すアイコンです。

[Ctrl]+[Alt]+[R]

アクティブ・データ

スクリーン・リーダー・モードの場合、「アクティブ・データ」ダイアログが開きます。ページにアクティブ・データがある場合のみ適用されます。

[Ctrl]+[Shift]+[^]

階層コントロール

階層ビューアの場合、階層ポップアップが開きます。

[Alt]+[↓]

ドロップダウン・リスト

ドロップダウン・リストを開きます。

[Enter]

ドロップダウン・リスト

ドロップダウン・リストのフォーカスされているオプションを選択します。

[Ctrl]+[A]

複数選択のリスト・ボックス

すべてのオプションを選択します。

[Ctrl]+[Shift]+[Home]

複数選択のリスト・ボックス

最初のオプションから現在のオプションまでのすべてのオプションを選択します。

[Ctrl]+[Shift]+[End]

複数選択のリスト・ボックス

現在のオプションから最後のオプションまでのすべてのオプションを選択します。

[Ctrl]+[Alt]+[M]

各種コンポーネント

カレンダや表などの、ポップアップ・メニューをサポートするコンポーネントで、ポップアップ・メニューを開きます。

[Ctrl]+[Shift]+[W]

[Ctrl]+[Alt]+[W]

各種コンポーネント

開いている連結解除可能メニューの間で切り替えます。

[Ctrl]+[Alt]+[P]

スプリッタ

フォーカスを次のスプリッタ・コンポーネントに移動します。

[Enter]

スプリッタ

スプリッタがフォーカスされている場合、分割セクションを閉じた状態から開いた状態に切り替えます。

[Ctrl]+[Alt]+[F4]

[Tab]

タブが削除できる場合は削除します。

C.3.5 スクリーン・リーダー・モードのショートカット・キー

スクリーン・リーダー・モードでは、ADF Facesコンポーネントは、アクセシビリティを向上するためにデフォルト・モードとは異なる方法でレンダリングされることがあります。たとえば、ツリー・コンポーネントには、行ごとにツリー・ノードを選択できるラジオ・コントロールの追加列が含まれます。

図C-5および図C-6は、デフォルト・モードとスクリーン・リーダー・モードのClickToEditデモ・アプリケーションを表示します。スクリーン・リーダー・モードでは、行選択のラジオ・コントロールの追加列に注意してください。

図C-5 デフォルト・モードのClicktoEditデモ・アプリケーション

図C-6 スクリーン・リーダー・モードのClicktoEditデモ・アプリケーション

C.3.6 リッチ・テキスト・エディタ・コンポーネントのショートカット・キー

表C-5に、リッチ・テキスト・エディタ・コンポーネントに割り当てられたショートカット・キーを示します。通常モードでは、ツールバーのすべてのコントロールがリッチ・テキスト・エディタ領域の一番上に表示されます。

表C-5 リッチ・テキスト・エディタ・コンポーネントに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Ctrl]+[B]

リッチ・テキスト・エディタ

太字

[Ctrl]+[I]

リッチ・テキスト・エディタ

イタリック体

[Ctrl]+[U]

リッチ・テキスト・エディタ

下線

[Ctrl]+[5]

リッチ・テキスト・エディタ

取消し線

[Ctrl]+[E]

リッチ・テキスト・エディタ

中央揃え

[Ctrl]+[J]

リッチ・テキスト・エディタ

両端揃え

[Ctrl]+[L]

リッチ・テキスト・エディタ

左揃え

[Ctrl]+[R]

リッチ・テキスト・エディタ

右揃え

[Ctrl]+[H]

リッチ・テキスト・エディタ

ハイパーリンクの作成

[Ctrl]+[M]

リッチ・テキスト・エディタ

インデントの増加

[Ctrl]+[Shift]+[M]

リッチ・テキスト・エディタ

インデントの減少

[Ctrl]+[Shift]+[H]

リッチ・テキスト・エディタ

ハイパーリンクの削除

[Ctrl]+[Shift]+[L]

リッチ・テキスト・エディタ

箇条書きリスト

[Ctrl]+[Alt]+[L]

リッチ・テキスト・エディタ

番号付きリスト

[Ctrl]+[Shift]+[S]

リッチ・テキスト・エディタ

テキスト・スタイルのクリア

[Ctrl]+[Alt]+[-]

リッチ・テキスト・エディタ

下付き

[Ctrl]+[Alt]+[+]

リッチ・テキスト・エディタ

上付き

[Ctrl]+[Alt]+[R]

リッチ・テキスト・エディタ

リッチ・テキスト編集モードの有効化

[Ctrl]+[Alt]+[C]

リッチ・テキスト・エディタ

ソース・コード編集モードの有効化

[Ctrl]+[Y]

リッチ・テキスト・エディタ

やり直し

[Ctrl]+[Z]

リッチ・テキスト・エディタ

元に戻す

スクリーン・リーダー・モードでは、リッチ・テキスト・エディタ・コンポーネントにはエディタのみが表示され、ツールバー・コントロールは表示されません。スクリーン・リーダー・モードで適用されるリッチ・テキスト・エディタのショートカット・キーはありません。

C.3.7 表、ツリーおよびツリー表コンポーネントのショートカット・キー

表C-6に、通常のリッチ・モードで表、ツリーおよびツリー表に割り当てられたショートカット・キーを示します。スクリーン・リーダー・モードでのこれらのコンポーネントのショートカット・キーは、表C-7にまとめてあります。詳細は、第12章「表、ツリー、およびその他のコレクションベースのコンポーネントの使用」を参照してください。

表C-6 表、ツリーおよびツリー表コンポーネントに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Tab]

[Shift]+[Tab]

表

ツリー表

フォーカスを次の、または前のセルあるいは編集可能なコンポーネントに移動します。

表で、セル内の次または前の編集可能なコンテンツに左から右の方向にナビゲートします。表の行の最後のセルにフォーカスが配置されている場合、[Tab]キーを使用して次の行の最初の編集可能なセルにフォーカスを移動できます。同様に、[Shift]+[Tab]を使用して前の行にフォーカスを移動できます。

[Ctrl]+[A]

表

ツリー表

列ヘッダー、行ヘッダーおよびデータ領域を含むすべてのコンポーネントを選択します。

[Ctrl]+[Alt]+[M]

表

ツリー

ツリー表

コンテキスト・メニューを起動します。

コンテキスト・メニューは、[Ctrl]+[Alt]+[B]を押しても起動できます。

[Ctrl]+[Shift]+[^]

ツリー

ツリー表

1レベル上げます。

[Enter]

[Shift]+[Enter]

表

ツリー

ツリー表

列の次の編集可能なセルまたは前の編集可能なセルに移動します。

表で、セル内の次または前の編集可能なコンテンツに上から下の方向にナビゲートします。

列ヘッダーにフォーカスが配置されている場合、表データを昇順にソートします。もう一度[Enter]を押すと、列を降順にソートします。

フィルタ・セルにフォーカスが配置されている場合、表のフィルタを実行します。

表で、ユーザーが[Tab]キーを使用して1つのセルから他のセルへナビゲートしてから[Enter]を押すと、同じナビゲーション・パターンに従うためにフォーカスを次の行に移動します。詳細は、C.2.2項「表でのタブのトラバース順序」を参照してください。

[←]

[→]

表

ツリー表

フォーカスを移動します。

表で、編集可能なコンポーネントにフォーカスがある場合、テキスト・カーソルを移動します。

[↑]

[↓]

表

ツリー表

フォーカスを移動します。

行が選択されている場合、フォーカスを前の行または次の行に移動します。行が選択されていない場合、表を1行分上または下にスクロールします。

表で、複数オプションをサポートする編集可能なコンポーネント(selectOneChoiceおよびinputNumberSpinBoxなど)にフォーカスがある場合、選択されたオプションをスクロールします。

最初の行が選択されている場合、フォーカスを列ヘッダーに移動します。

編集可能な表で、ユーザーが編集可能なコンポーネント(テキスト・ボックスまたはチェック・ボックスなど)、ボタンまたはリンク・コンポーネントをクリックすると、フォーカスがセル内のコンポーネントに設定されます。上下矢印キーを使用してナビゲーションするには、フォーカスが編集可能なコンポーネントからセルに移動する必要があります。フォーカスを移動するには、ユーザーは同じセルの背景(または同じ行の任意のセル)を再度クリックする必要があります。

注意: selectionEventDelayが有効化されている場合、キーボード・ナビゲーション中の行選択は300ms遅らされており、不要な行選択を起こさないキーボード・ナビゲーションを可能にしている。

[Ctrl]+[↑]

[Ctrl]+[↓]

表

フォーカスを移動します。

編集モードの場合、現在の行で行った変更を送信し、前の行または次の行に移動します。

クリックして編集できる表で、複数オプションをサポートする編集可能なコンポーネント(selectOneChoiceおよびinputNumberSpinBoxなど)にフォーカスがある場合、選択されたオプションをスクロールします。

[Ctrl]+[←]

[Ctrl]+[→]

表

フォーカスを移動します。

編集モードで、編集可能なコンポーネントにフォーカスがある場合、テキスト・カーソルを移動します。

[Shift]+[←]

[Shift]+[→]

表

ツリー表

フォーカスを移動して選択に追加します。

[Ctrl]+[Shift]+[←]

[Ctrl]+[Shift]+[→]

表

ツリー表

選択列を左または右に移動します。

[Shift]+[↑]

[Shift]+[↓]

表

ツリー表

ツリー

複数行を選択します。

[Page Up]

[Page Down]

表

ツリー表

行が選択されている場合、スクロールして次または前のページの同じ行を選択します。

行が選択されていない場合、1ページ分スクロールします。

[Alt]+[Page Up]

[Alt]+[Page Down]

表

ツリー表

表を水平方向に右または左にスクロールします。

[Space]

[Ctrl]+[Space]

表

ツリー

ツリー表

ノードを選択します。

複数のノードを選択または削除するには、[Ctrl]+[Space]を押します。

[Shift]+[Space]

表

ツリー表

複数行を選択します。

[Esc]

表

ツリー表

選択を解除します。

セルにフォーカスが配置されている場合、クリック編集モードを終了し、セルの値が元の値に戻り、フォーカスがセルに戻ります。[Esc]キーをもう一度押すと、フォーカスが行ヘッダーに移動します。

F2

表

ツリー表

行のクリック編集モードをアクティブ化します。[F2]をもう一度押すと、セル・ナビゲーション・モードが無効になります。

C.3.8 スクリーン・リーダー・モードにおける表、ツリーおよびツリー表コンポーネントのショートカット・キー

表C-7に、スクリーン・リーダー・モードでツリー、表およびツリー表コンポーネントに割り当てられたショートカット・キーを示します。

表C-7 スクリーン・リーダー・モードでコンポーネントに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Space]

表

ツリー

ツリー表

コンポーネントを選択します。ノードを選択するには、[Tab]を押してフォーカスをコンポーネントまたはそのラジオ・コントロールに移動します。コンポーネントにフォーカスが配置されているときに[Space]を押します。

[Space]は複数選択にも使用できます。

選択されたコンポーネントに対して[Space]を押すと、選択が解除されます。

[Enter]

表

ツリー

列ヘッダーにフォーカスが配置されている場合、列を昇順にソートします。もう一度[Enter]を押すと、列を降順にソートします。

ツリーの公開アイコンにフォーカスが配置されている場合、そのノードを開くか、または閉じます。

フィルタ・セルにフォーカスが配置されている場合、表のフィルタを実行します。

[Tab]

[Shift]+[Tab]

表

フォーカスを次の、または前のセルあるいは編集可能なコンポーネントに移動します。

[↑]

[↓]

[←]

[→]

表

フォーカスを移動します。

[Ctrl]+[Shift]+[←]

[Ctrl]+[Shift]+[→]

表

ツリー表

選択列を左または右に移動します。

[Shift]+[←]

[Shift]+[→]

表

ツリー表

選択された列のサイズを左または右から25ピクセル分変更します。

[Ctrl]+[Shift]+[^]

ツリー

階層セレクタ・アイコンにフォーカスが配置されている場合、階層セレクタ・ポップアップが表示されます。

[Ctrl]+[Alt]+[M]

[Ctrl]+[Alt]+[B]

表

ツリー

ツリー表

本体コンテキスト・メニューを起動します。

スクリーン・リーダー・モードでは、ツリー・コンポーネントには、行ごとにツリー・ノードを選択できるラジオ・コントロールの追加列が含まれます。ツリーの次の列には、ツリー・ノード自体が含まれます。開くことができるノードには、オープンまたはクローズ状態を示す公開リンクがあります。クローズ状態の公開リンクを開くと、より多くのツリー・ノードが表示され、ページ上で移動できるようになります。

注意:

スクリーン・リーダー・モードでは、表およびツリー表コンポーネントにおいて次の機能はサポートされません。

- クリック編集モード

- 最初の行から現在の行まで、または現在の行から最後の行までのすべての行の選択

- すべての行の選択

- すべての列の選択の解除

C.3.9 ADFデータ視覚化コンポーネントのショートカット

表C-8に、ガント・チャート、ADF階層ビューア・コンポーネント、ADF地理マップなどのADFデータ視覚化コンポーネントに割り当てられたショートカット・キーを示します。ADFデータ視覚化コンポーネントの詳細は、第22章「ADFデータ視覚化コンポーネントの概要」を参照してください。

表C-8 ADFデータ視覚化コンポーネントに割り当てられたショートカット

ショートカット・キー

コンポーネント

機能

[←]

[→]

すべてのガント・チャート・タイプのリスト・リージョン

プロジェクト・ガントのチャート・リージョン

スケジュール・ガントのチャート・リージョン

リソース使用率ガントのチャート・リージョン

ADF地理マップ

ADF階層ビューア - ノード

ピボット・テーブル

ピボット・フィルタ・バー

フォーカスを移動します。

スケジュール・ガントのチャート・リージョンにフォーカスが配置されている場合、矢印キーのナビゲーションで現在の行の前または次のタスク・バーを選択します。

リソース使用率ガントの時間バケットにフォーカスが配置されている場合、矢印キーのナビゲーションで現在の行の前または次の時間バケットを選択します。

ADF地理マップにフォーカスが配置されている場合、矢印キーのナビゲーションで左または右に少しずつパンします。[Home]または[End]キーを押すと大きくパンします。

ADF階層ビューアのノード・コンポーネントにフォーカスが配置されている場合、[Ctrl]+矢印キーを押して、コンポーネントを選択せずにフォーカスを左右に移動します。

矢印キーを使用して編集可能ピボット・テーブルのセルを移動する場合、次のセルに移動する前に、フォーカスの配置されている各セルが編集用にアクティブ化され、ナビゲーションの速度が遅くなります。フォーカスの配置されているセルの編集モードを解除してナビゲーションを高速化するには、[Esc]キーを押します。セルを編集するには、[F2]または[Enter]キーを押します。

ピボット・テーブルのデータ・セルにフォーカスが配置されている場合、[Ctrl]+[←]を押して対応する行ヘッダー・セルに移動します。ロケールが双方向の場合(アラビア語など)、[Ctrl]+[→]を押して対応する行ヘッダー・セルに移動します。

[↑]

[↓]

すべてのガント・チャート・タイプのリスト・リージョン

プロジェクト・ガントのチャート・リージョン

スケジュール・ガントのチャート・リージョン

リソース使用率ガントのチャート・リージョン

ADF地理マップ

ADF階層ビューア - ノード

ピボット・テーブル

ピボット・フィルタ・バー

フォーカスを移動します。

プロジェクト・ガントのチャート・リージョンにフォーカスが配置されている場合、矢印キーのナビゲーションで前または次の行を選択します。

スケジュール・ガントのチャート・リージョンのタスク・バーにフォーカスが配置されている場合、矢印キーのナビゲーションで前の行または次の行の最初のタスク・バーを選択します。

リソース使用率ガントの時間バケットにフォーカスが配置されている場合、矢印キーのナビゲーションで前の行または次の行の時間バケットを選択します。

ADF地理マップ・コンポーネントにフォーカスが配置されている場合、矢印キーのナビゲーションで上または下に少しずつパンします。

ADF階層ビューアのノード・コンポーネントにフォーカスが配置されている場合、[Ctrl]+矢印キーを押して、コンポーネントを選択せずにフォーカスを上下に移動します。

矢印キーを使用して編集可能ピボット・テーブルのセルを移動する場合、次のセルに移動する前に、フォーカスの配置されている各セルが編集用にアクティブ化され、ナビゲーションの速度が遅くなります。フォーカスの配置されているセルの編集モードを解除してナビゲーションを高速化するには、[Esc]キーを押します。セルを編集するには、[F2]または[Enter]キーを押します。

ピボット・テーブルのデータ・セルにフォーカスが配置されている場合、[Ctrl]+[↑]を押して対応する列ヘッダー・セルに移動します。

[Page Up]

[Page Down]

ADF地理マップ

ADF階層ビューア - ダイアグラム

ADF地理マップ・コンポーネントにフォーカスが配置されている場合、ページ・キーのナビゲーションで上または下に大きくパンします。

ADF階層ビューアのダイアグラムにフォーカスが配置されている場合、[Page Up]または[Page Down]キーを押したままにして、上または下に続けてパンします。[Ctrl]+[Page Up]または[Ctrl]+[Page Down]を押して、左または右に続けてパンします。

[+]

ADF地理マップ

ADF階層ビューア - ダイアグラム

ズーム・レベルを上げます。

ADF階層ビューアのダイアグラムにフォーカスが配置されている場合、数字キーの[1]から[5]を押すことで、10%から100%までズームできます。[0]を押すと、使用可能な領域内に収まるようにダイアグラムがズームします。

[-]

ADF地理マップ

ADF階層ビューア - ダイアグラム

ズーム・レベルを下げます。

ADF階層ビューアのダイアグラムにフォーカスが配置されている場合、数字キーの[1]から[5]を押すことで、10%から100%までズームできます。[0]を押すと、使用可能な領域内に収まるようにダイアグラムがズームします。

[Ctrl]+[Alt]+[M]

すべてのガント・チャート・タイプ

ピボット・テーブル

ピボット・フィルタ・バー

コンテキスト・メニューを起動します。

[Home]

ADF階層ビューア - ノード

現在のレベルの最初のノードにフォーカスを移動します。

[End]

ADF階層ビューア - ノード

現在のレベルの最後のノードにフォーカスを移動します。

[Ctrl]+[Home]

ADF階層ビューア - ノード

フォーカスを移動してルート・ノードを選択します。

<

ADF階層ビューア - ノード

アクティブなノードの前のパネルに切り替えます。

[>]

ADF階層ビューア - ノード

アクティブなノードの次のパネルに切り替えます。

[Ctrl]+[/]

ADF階層ビューア - ノード

すべてのノードを同期してアクティブなノードのパネルを表示します。

[Ctrl]+[Shift]+[^]

ADF階層ビューア - ノード

1レベル上げます。

[Ctrl]+[/]

ADF階層ビューア - ノード

コンテンツ・パネルを切り替えます。

[Ctrl]+[Alt]+[0]

ADF階層ビューア - ダイアグラム

アクティブなノードを中央に配置してダイアグラムを100%までズームします。

[Tab]

ADF階層ビューア - ノード

ピボット・テーブル

ピボット・フィルタ・バー

要素間でフォーカスを移動します。

[Esc]

ADF階層ビューア - ノード

格納ノードにフォーカスを戻します。

検索パネルにフォーカスが配置されている場合、パネルを閉じます。

ノード上にカーソルを合せたときに表示される「詳細」ウィンドウを閉じます。

[Space]

ADF階層ビューア - ノード

ピボット・テーブル

ピボット・フィルタ・バー

アクティブなノードを選択します。[Ctrl]+[Space]を押して、アクティブなノードの選択を切り替えたり、複数のノードを選択します。

[Enter]

ADF階層ビューア - ノード

ピボット・テーブル

ピボット・フィルタ・バー

アクティブなノードを分離して選択します。[Shift]+[Enter]を押してノードの状態を切り替えます。

[/]

ADF階層ビューア - ノード

コントロール・パネルを切り替えます。

[Ctrl]+[F]

ADF階層ビューア - ノード

ADF階層ビューア・コンポーネントが検索機能をサポートするように構成されている場合、検索パネルが開きます。

[Ctrl]+[Alt]+[1]から[Ctrl]+[Alt]+[5]

ADF階層ビューア - ノード

ダイアグラムのレイアウトを切り替えます。

[Shift]+[Alt]+矢印キー

ピボット・テーブル

ピボット・フィルタ・バー

行、列またはフィルタ・レイヤーを新しい場所にピボットすることで、レイアウトを変更します。[Shift]+[Alt]+矢印キーを使用して次の操作を実行します。

- ヘッダー・レイヤーが選択されている場合、ビジュアル・フィードバックを提供してピボット操作の移動可能先を示します。

- 異なる移動先の場所を選択します。

- 選択されたヘッダー・レイヤーを指定された移動先に移動するか入れ替えます。

一部のADFデータ視覚化コンポーネントは、メニュー・バー、ツールバー、コンテキスト・メニューまたは組込みの「タスク・プロパティ」ダイアログ・ボックスを通じて、エンド・ユーザーに共通の機能を提供します。これらの機能は、表示と非表示を切り替えたり、置換することができます。機能を非表示にするか、置換する場合、それらの機能に代替キーボード・アクセシビリティを割り当てる必要があります。

スクリーン・リーダー・モードでは、ADFデータ視覚化コンポーネントは、表C-9に示されているとおり、他のアクセス可能なコンポーネントで置換されます。

表C-9 スクリーン・リーダー・モードでのデータ視覚化コンポーネントの代替ADFコンポーネント

ADFデータ視覚化コンポーネント

代替コンポーネント

各ガント・タイプのチャート・リージョン

ハイパーリンク

[Tab]キーを使用してチャート・リージョン内でフォーカスを移動します。[Enter]または[Esc]キーを使用して、対応する「プロパティ」ダイアログ・ボックスを起動または終了します。

ADF地理マップ

表

標準のキーボード・ショートカットを使用して、表C-6に示されているとおり、データ間を移動します。

ADF地理マップ・インスタンスがデータにバインドされた複数のテーマを参照する場合、ドロップダウン・リストも、対応する表インスタンス間で切り替えられるようにレンダリングされます。

階層ビューア

ツリー表

標準のキーボード・ショートカットを使用して、表C-6に示されているとおり、データ間を移動します。

スクリーン・リーダー・モードでは、ピボット・テーブルとピボット・フィルタ・バーによって、ヘッダー・レイヤーとフィルタそれぞれに対して追加のアイコンがレンダリングされます。スクリーン・リーダー・ソフトウェアのエンド・ユーザーは、[Tab]キーを使用してこれらのアイコン間でフォーカスを移動し、[Enter]を押すことで指定したピボット操作を実行できます。

C.3.10 カレンダ・コンポーネントのショートカット・キー

カレンダ・コンポーネントには、日ビュー、週ビュー、月ビュー、リスト・ビューの複数のビューがあります。リスト・ビューはスクリーン・リーダー・モードで表示されます。

表C-10に、カレンダ・コンポーネントに割り当てられたショートカット・キーを示します。

表C-10 カレンダ・コンポーネントに割り当てられたショートカット・キー

ショートカット・キー

コンポーネント

機能

[Tab]

[Shift]+[Tab]

カレンダ

フォーカスを移動します。

フォーカスがカレンダ・ツールバーにある場合は、「日」、「週」、「月」、「リスト」、「下に検索」ボタン、「上に検索」ボタン、「今日」ボタンの中でフォーカスが移動します。

日ビューでは、その日のアクティビティの中でフォーカスが移動します。

週ビューおよび月ビューでは、「月日」ヘッダー・ラベル内でのみフォーカスが移動します。アクティビティ(その他nのリンク)および「月日」ヘッダー・ラベルを移動するには、矢印キーを使用します。

月ビューでは、フォーカスが週の最後の「月日」ヘッダー・ラベルにある場合、フォーカスが次の週の「月日」ヘッダー・ラベルに移動します。

リスト・ビューでは、日、およびその日のアクティビティ内でフォーカスが移動します。

[←]

[→]

カレンダ

フォーカスを移動します。

日ビューでは、[→]および[←]ではフォーカスは移動しません。

週ビューでは、フォーカスがアクティビティにある場合、前または次の日の最初のアクティビティにフォーカスが移動します。前または次の日にアクティビティがない場合は、日ヘッダーにフォーカスが移動します。

月ビューでは、次の操作が行われます。

- フォーカスが「月日」ヘッダー・ラベルにある場合、前または次の日のラベルにフォーカスが移動します。
月の第1週の最終日のラベルにフォーカスがある場合、[→]でその月の第2週の初日のラベルにフォーカスが移動します。月の最終日のラベルにフォーカスがある場合、[→]では何も起こりません。

- フォーカスがアクティビティにある場合、前または次の日の次のアクティビティにフォーカスが移動します。
前または次の日にアクティビティがない場合は、「月日」ラベルにフォーカスが移動します。週の最終日のアクティビティにフォーカスがある場合、[→]では何も起こりません。

- フォーカスがその他nのリンクにある場合は、次のその他nのリンクにフォーカスが移動します(存在する場合)。
隣接するその他nのリンクが存在しない場合、その日の最後のアクティビティにフォーカスが移動します。週の初めまたは最後の日にその他nのリンクが存在する場合、[←]または[→]では何も起こりません。

[↑]

[↓]

カレンダ

フォーカスを移動します。

日ビューでは、アクティビティの中でフォーカスが移動します。アクティビティが競合し、同じ時間帯に表示される場合、[↓]ではフォーカスが右に移動し、[↑]では左に移動します。

週ビューでは、その日のアクティビティの中でフォーカスが移動します。その日の最初のアクティビティにフォーカスがある場合、[↑]で日ヘッダーにフォーカスが移動します。日ヘッダーにフォーカスがある場合、[↓]でその日の最初のアクティビティにフォーカスが移動します。その日にアクティビティがない場合、[↓]では何も起こりません。

月ビューでは、その日のアクティビティの中でフォーカスが移動します。

- その日の最初のアクティビティにフォーカスがある場合、[↑]で「月日」ヘッダー・ラベルにフォーカスが移動します。

- 「月日」ヘッダー・ラベルにフォーカスがある場合、[↑]で上にあるその日の最後のアクティビティにフォーカスが移動します。

- 月の最終週の日の最後のアクティビティにフォーカスがある場合、[↓]では何も起こりません。

- 月の第1週の月ヘッダーの日ラベルにフォーカスがある場合、[↑]では何も起こりません。

[Ctrl]+[Alt]+[M]

カレンダ

コンテキスト・メニューを起動します。

コンテキスト・メニューは、[Ctrl]+[Alt]+[B]を押しても起動できます。

注意:

月または週のアクティビティを矢印を使用して移動する場合、終日アクティビティが開始される日の中でユーザーが移動するときにのみ、終日アクティビティにフォーカスが移動します。それ以外の場合、終日アクティビティはスキップされます。

C.3.11 スクリーン・リーダー・モードでのカレンダ・コンポーネントのショートカット・キー

スクリーン・リーダー・モードでは、カレンダ・コンポーネントにリスト・ビューがレンダリングされます。表C-11に、スクリーン・リーダー・モードでカレンダ・コンポーネントに割り当てられているショートカット・キーをリストします。

表C-11 スクリーン・リーダー・モードでカレンダ・コンポーネントに割り当てられているショートカット・キー

ショートカット・キー

コンポーネント

機能

[Tab]

[Shift]+[Tab]

カレンダ

フォーカスを次の、または前のセルあるいは編集可能なコンポーネントに移動します。

[↑]

[↓]

[←]

[→]

カレンダ

フォーカスを移動します。

C.4 デフォルトのカーソルまたはフォーカスの配置

デフォルト・カーソルによって、1つのコンポーネントに初期フォーカスされているため、キーボード・ユーザーはあまり移動せずにページとの対話操作を開始できます。

フォーカスとは、ユーザーが[Tab]キーまたはアクセス・キーを押したときに、ページ内を移動する選択領域のことです。フォーカスがデータの入力が可能なフィールドに移動すると、フィールドにはカーソルが表示されます。フィールドにすでにデータが含まれている場合は、そのデータが強調表示されます。また、一部のコントロールを使用した後(値リスト(LOV)や日時ピッカーなど)、カーソルまたはフォーカスの配置はコンポーネントによって事前定義された特定の場所に移動します。

標準的なADF Facesページのロード中、フォーカスはページ上で最初のフォーカス可能なコンポーネント、つまり編集可能なウィジェットまたはナビゲーション・コンポーネント上に表示されます。そのページにフォーカス可能な要素がない場合、フォーカスはブラウザのアドレス・フィールドに表示されます。

デフォルト・カーソルおよびフォーカスの配置を定義する際には、次のガイドラインに従う必要があります。

- ADF Facesアプリケーションでは、キーボード・ユーザーがページの上部でUI要素をタブで移動せずに、コンテンツ領域に直接アクセスできるように、大半のページでデフォルトのカーソルまたはフォーカスを配置する必要があります。

- ページがロードされたら、デフォルト以外の別のコンポーネントにフォーカスを設定できます。ページにデータ入力の共通の開始点がある場合、ユーザーがキーボードやマウスであまり移動せずにデータ入力を開始できるように、デフォルトのフォーカスまたはカーソルの位置を変更できます。そうでない場合、ページのロード後に、キーボード・ユーザー(特にスクリーン・リーダー・ユーザー)が位置を把握するのが難しくなるため、これは行わないでください。

C.5 [Enter]キー

[Enter]キーは、カーソルが特定のフィールドにある場合や、フォーカスがリンクまたはボタンにある場合にアクションを起動します。ログイン・フォームやダイアログなどで共通のコミット・ボタンをアクティブ化する場合に[Enter]キーを使用します。

多くのコンポーネントに、[Enter]キーのビルトインのアクションが設定されています。次のような例があります。

- フォーカスがリンクまたはボタンにある場合、[Enter]キーにより、リンクにナビゲートされるかアクションが起動されます。

- カーソルが問合せ検索リージョン、クイック問合せ検索または例による問合せ(QBE)フィールドにある場合、[Enter]キーにより検索が実行されます。

- 表では、[Enter]キーで下のセルにフォーカスが移動し、[Shift]+[Enter]を押すと上のセルにフォーカスが移動します。フォーカスが移動すると、現在のセルが読取り専用モードに戻ります。

D ADF Facesを使用したタッチ装置のWebアプリケーションの作成

この付録では、タッチ装置のWebベースのアプリケーションを実装する方法について説明します。

この付録には次の項が含まれます:

- D.1項「ADF Facesを使用したタッチ装置のWebアプリケーションの作成の概要」

- D.2項「タッチ装置上のモバイル・ブラウザでのADF Facesの動作」

- D.3項「モバイル・ブラウザでADF Facesコンポーネントを使用する場合のベスト・プラクティス」

D.1 ADF Facesを使用したタッチ装置のWebアプリケーションの作成の概要

ADF Facesフレームワークは、Safariなどのモバイル・ブラウザで実行するように最適化されています。フレームワークは、タッチ装置上のモバイル・ブラウザがページをリクエストすると認識し、モバイル・デバイスに適用可能なJavaScriptとピア・コードのみを提供します。ただし、標準ADF Faces Webアプリケーションはモバイル・ブラウザで実行されますが、ユーザーの対話が異なり、スクリーン・サイズが制限されるため、アプリケーションをモバイル・ブラウザで実行する必要がある場合、タッチ装置に固有のバージョンのページを作成する必要があります。

この付録では、タッチ装置上のモバイル・ブラウザでのADF Facesの機能と、タッチ装置専用のWebページを実装するためのベスト・プラクティスについて説明します。

D.2 タッチ装置上のモバイル・ブラウザでのADF Facesの動作

タッチ装置では、ユーザーはマウスをクリックするかわりに画面にタッチします。ネイティブ・ブラウザは、これらのタッチ・イベントをマウス・イベントに変換して処理します。ADF Facesでは、コンポーネント・ピアが変換を処理します。タッチ・デバイスとデスクトップ・デバイスとの変換の相違の処理方法を改善するために、ADF Facesでは、変換が必要なコンポーネントごとに、タッチ・デバイス固有のピアとデスクトップ固有のピアの両方を提供しています(ピアの詳細は、第4.1項「ADF Facesアーキテクチャの使用について」を参照)。

これらのピアにより、コンポーネントは装置に固有のイベントを処理できます。たとえば、デスクトップのピアは、マウス・オーバー・イベントやマウス・アウト・イベントを処理し、タッチ装置のピアは、タッチ開始イベントとタッチ終了イベントを処理します。基本のピアは、共通の対話をすべて処理します。この区別によって、どちらの装置でも処理が最適化されます(タッチ・イベントの詳細は、表6-3「ADF Facesクライアント・イベント」を参照)。

タッチ装置のピアでは、タッチ固有のジェスチャを使用して、デスクトップでの対話をシミュレートするロジックが提供されます。表D-1に、デスクトップのジェスチャとタッチ装置のジェスチャの対応状況を示します。

表D-1 サポートされるモバイル・ブラウザのユーザー・ジェスチャ

マウスによる対話

タッチ・ジェスチャ

視覚状況

例

クリック

タップ

マウス・ダウン

ボタンを実行

選択

タップ

選択済

表の行を選択

複数を選択

タップでオブジェクトを選択、タップで別のオブジェクトを選択、選択済オブジェクトのタップで選択解除

選択済

複数のグラフ・バーを選択

簡単なインタフェースでのドラッグ・アンド・ドロップ

指で指す+ドラッグ

マウス・ダウン

スライダ・サムまたはスプリッタをドラッグ

ドラッグ・アンド・ドロップとデータ・チップの両方が必要な場合のドラッグ・アンド・ドロップ

指で指す+短く保留+ドラッグ

マウス・ダウン

ガント・チャートでタスク・バーを移動

カーソルを置いてデータ・チップを表示

指で指す+保留

カーソルを置く(マウスオーバー)

グラフのデータ・チップを表示

カーソルを置いてポップアップを表示

指で指す+保留

カーソルを置く(マウスオーバー)

カレンダからポップアップを表示

クリックしてポップアップを閉じる

ポップアップの外をタップ

マウス・クリック

ポップアップの外をクリックして閉じる

グラフにデータ・カーソルを配置

指で指す+保留

カーソルを置く

グラフのX軸に沿ってトレースし、Y軸の交差地点でデータ値をチップに表示。

右クリックでコンテキスト・メニューを起動

指で指す+保留または指で指す+保留+指を上げる(別の指で指す+保留ジェスチャとのジェスチャの競合がある場合)

グラフまたはカレンダ・アクティビティのコンテキスト・メニューを表示。指を上げた場合のコンテキスト・メニューの例: グラフ: 指で指す+保留=データ・チップ、指を上げる=コンテキスト・メニュー。グラフ(バブル): 指で指す+保留+移動=ドラッグ・アンド・ドロップ、指を上げる=コンテキスト・メニュー。ガント(タスク・バー): 指で指す+保留=データ・チップ、指で指す+保留+移動=ドラッグ・アンド・ドロップ、指を上げる=コンテキスト・メニュー

パン

1本の指でスワイプ(他のジェスチャとの競合がない場合)。それ以外の場合は、2本の指でスワイプ

有効

マップのパン

ズーム・イン/ズーム・アウト

2回タップ(ブラウザのズーム)。最大化の状態では、ピンチ・イン/ピンチ・アウトでズームを実行可能

有効

ブラウザ画面をズーム

グラフまたはマップをズーム

ダブルクリックで階層ビューア・コンポーネントにアンカーを設定

2回タップ。

setAnchorListenerに値がある場合、ノードがツリーのルートになります。値が設定されない場合、2回タップすると、ブラウザがズームされます。

階層内でノードを2回タップすると、それがルート・ノードになります。

階層ビューア・コンポーネントで分離アイコンをクリック

ノードをタップしてから、分離アイコンをタップ

パネル・カードが分離された状態

カードの上部をタップしてから、分離アイコンをタップすると、そのカードと直接レポートのみが表示されます。

階層ビューア・コンポーネントで折りたたみアイコンをクリック

カードを上にスワイプ

パネル・カードが折りたたまれた状態

パネル・カードの折りたたみ

階層ビューア・コンポーネントで展開アイコンをクリック

カードを下にスワイプ

パネル・カードが展開された状態

折りたたまれたパネル・カードを展開。

カーソルを置いて、階層ビューアのポップアップ・ボタンを表示

カードをタップ

ポップアップ・ボタンが表示された状態

カードをタップして、ポップアップ・ボタンを表示

階層ビューア・コンポーネントで右矢印ボタンまたは左矢印ボタンをクリック

カードを左または右にスワイプ

パネル・カードの切替え

左にスワイプして住所を表示、または右にスワイプしてコンテンツを表示。

ナビゲーション・ボタンをクリックして、階層を横方向に移動

横方向ナビゲーション行で左または右にスワイプするか、矢印をタップするか、タッチして短く保留で指を上げてナビゲーション・ボタンを表示

階層をトラバース

ルート・ノードの子孫を表示。

最大化アイコンを1回タップ

コンポーネントを最大化

最大化アイコンを2回タップするか、階層ビューアの背景を2回タブで移動

コンポーネントを最大化し、ズームで調整

円、長方形、ポリゴン・ツールをマップで使用して、領域をドラッグおよび選択

指で指す、形を描画

選択済

指で、マップ上の領域を選択

マップで測定ツールを使用して、開始点と終了点をクリック

測定ツールをタップ、指で指す、線を描画

描画された線と計算された距離が表示された状態

指で測定ツールを選択し、タップしてA点を選択、B点までの線を描画

マップでエリア・ツールを使用して、開始点と終了点をクリック

エリア・ツールをタップ、指で指す、線を描画

描画された線と計算されたエリアが表示された状態

指でエリア・ツールを選択、タップしてA点を選択、B点までの線を描画など。

さらに最適化するために、タッチ装置のJavaScriptがデスクトップのJavaScriptと区別されるようにADF FacesはJavaScriptをパーティション化します。ページをレンダリングすると、必要なJavaScriptのみがダウンロードされます。また、タッチ装置が検出されると、タッチ装置に固有のCSSコンテンツがページに送信されます。たとえば、タッチ装置では、シャトル・コンポーネントのアイテムにチェック・ボックスが表示されるため、ユーザーは簡単にアイテムを選択できます。デスクトップ装置では、チェック・ボックスは表示されません。

デバイス固有のピア、JavaScriptおよびCSSを使用すると、コンポーネントはデスクトップ装置とタッチ装置で別々に機能します。表D-2に、その違いを示します。

表D-2 モバイル・ブラウザでのコンポーネントの相違

コンポーネント

機能

デスクトップ・コンポーネントとの相違

selectManyShuttleおよびselectOrderShuttle

選択項目

選択ボックスが表示され、ユーザーは移動するアイテムを選択できます。

table

選択項目

行をタップして選択し、再度タップしてその行の選択を解除します。選択する行をタップすることで、複数の行を簡単に選択できます。つまり、2番目の行を選択しても、最初の行の選択が自動で解除されるわけではありません。

table

スクロール

表コンポーネントには、スクロールバーのかわりにページ番号が付けられており、次に示すように、ユーザーが行の特定のページにジャンプできるフッターが表示されます。

1ページの行数はfetchSize属性によって決まります。

ADF Facesダイアログ・フレームワーク

Windows

ダイアログ・フレームワークの起動に使用されるコマンド・コンポーネントで、windowEmbedStyle属性がwindow(別のウィンドウを起動)に設定されている場合、ADF Facesはこの値をオーバーライドしてinlineDocumentに設定するため、ダイアログはかわりに親ウィンドウ内にインラインで起動されます。

menu

連結解除可能メニュー

連結解除可能メニューはサポートされません。detachable属性は無視されます。

inlineFrame

ジオメトリ管理

タッチ装置では、iFrameコンポーネントはディメンションを無視し、常にそのコンテンツと同じ高さになります。そのため、inlineFrameがその親によってストレッチされる場合、スクロール・バーはタッチ装置で使用されないため、コンテンツは切り捨てられます。

inlineFrameがその親によってストレッチされる場合、40ピクセルのパディングとオーバーフローがインライン・スタイルに追加されます。

各種コンポーネント

アイコン、ボタンおよびリンク

アイコンとボタンは比較的大きく、リンク間のスペースは、指に対応するように比較的大きくなっています。

一部のタッチ装置ではFlashがサポートされないため、ADF Facesコンポーネントでは、アニメーションの遷移などにHTML5が使用されます。この規格によって、コンポーネントはすべての装置で表示されます。

D.3 モバイル・ブラウザでADF Facesコンポーネントを使用する場合のベスト・プラクティス

アプリケーションがタッチ装置で動作することがわかれば、その装置に固有のページを作成する作業がベスト・プラクティスになります。例D-1と同様のコードを使用すると、アプリケーションが動作する装置を決定し、その装置に正しいページを提供できます。

例D-1 プラットフォームの決定

public boolean isMobilePlatform()
{
RequestContext context = RequestContext.getCurrentInstance();
Agent agent = context.getAgent();

return
Agent.TYPE_PDA.equals(agent.getType()) ||
Agent.TYPE_PHONE.equals(agent.getType()) ||
(
Agent.AGENT_WEBKIT.equals(agent.getAgentName()) &&
(
// iPad/iPhone/iPod touch will come in as a desktop type and an iphone platform:
"iphone".equalsIgnoreCase(agent.getPlatformName())
)
);
}

タッチ装置アプリケーションはほとんどのADF Facesコンポーネントを使用できますが、タッチ装置上では、特定の機能が制限されるか失敗することがあります。表D-3に、タッチ装置のアプリケーションの開発で従うベスト・プラクティスを示します。

表D-3 モバイル・ブラウザでのADF Facesコンポーネントのベスト・プラクティス

コンポーネント/機能

ベスト・プラクティス

ジオメトリ管理

oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS web.xmlパラメータをauto.に設定します。

この設定により、ページは拡大せずにスクロールするようになります。詳細は、A.2.3.29項「レイアウトと表コンポーネントの形状管理」を参照してください。

部分ページ・ナビゲーション

部分ページ・ナビゲーションを使用すると、ページ間でJavaScriptなどのクライアント・コードをダウンロードする必要がないため、パフォーマンスが向上します。詳細は、8.5項「部分ページ・ナビゲーションの使用」を参照してください。

ナビゲーション

コンテンツの各部分への直接アクセスを提供します。適切なルールでは、1つのページに多くの領域を使用してスプリッタで分割するのではなく、ページごとに1つのタスクのみが使用されます。たとえば、左ペインのツリーでpanleSplitterを使用してナビゲートするのではなく、リストベースのナビゲーション・モデルを提供します。

documentタグ

大きなアイコン(通常は129x129ピクセル)を参照するようにdocumentタグを構成できます。詳細は、9.2.5項「documentタグの構成方法」を参照してください。

表

デフォルトでは、タブレット・デバイスでレンダリングする場合、表にはユーザーが行の特定のページにジャンプできるフッターが表示されます。タブレット・デバイスですべての表を表示するには、次のようにしてください。

- 表コンポーネントをフロー・コンテナ(つまり、子を拡張しないコンポーネント)の中に配置してください。

- autoHeightRows属性を0に設定してください。この表の最初の行の説明にあるように、oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONSパラメータをautoに設定するのがより良いです。

- scrollPolicy属性をautoに(ページがデスクトップ・デバイスでも実行される場合)、またはpageに(ページがタブレットのみで実行される場合)設定してください。

表がフロー・コンテナの中にない場合、または属性が正しく設定されていない場合は、ページのかわりにスクロールバーが表示されます。

表の属性の詳細は、12.3.2項「表の書式設定」を参照してください。スクロールするレイアウトと表の詳細は、12.2.7項「表、ツリー、およびツリー、表のコンポーネントの形状管理」を参照してください。

E クイック・スタート・レイアウト・テーマ

この付録では、各クイック・スタート・レイアウトへのテーマの適用を選択した場合に、どのような影響があるかを示します。ADF Facesには、ページ全体のレイアウトを定義する際に使用可能なコンポーネントが多数用意されています。JDeveloperには、これらのコンポーネントを使用した事前定義済のクイック・スタート・レイアウトが含まれており、すばやく簡単に正しくレイアウトを構築できます。1列、2列、または3列のレイアウトから選択できます。選択されたクイック・レイアウトへのテーマの適用を選択すると、クイック・スタート・レイアウトで使用されている一部のコンポーネントに色とスタイルが追加されます。

図E-1および図E-2に、テーマを適用した場合と適用しない場合のレイアウトをそれぞれ示します。テーマの詳細は、第31章「スタイルおよびスキンを使用した外観のカスタマイズの概要」を参照してください。

図E-1 テーマを適用した場合と適用しない場合のクイック・スタート・レイアウト

図E-2 テーマを適用した場合と適用しない場合のクイック・スタート・レイアウト

F コード・サンプル

この付録では、このガイド全体の項で参照されている、完全な長さのコード・サンプルを示します。

この付録には次の項が含まれます:

- 第F.1項「サンプル」

- 第F.2項「サンプル」

- 第F.3項「サンプル」

- 第F.4項「サンプル」

F.1 第4章「ADF Facesのクライアント・サイド・アーキテクチャの使用」のサンプル

次に、ADF Facesアーキテクチャを使用する場合のコード例を示します。

F.1.1 adf-js-partitions.xmlファイル

デフォルトのADF Facesのadf-js-partitions.xmlファイルには、独自のパーティション・ファイルを作成してオーバーライドできるパーティションがあります。詳細は、第4.9項「JavaScriptライブラリのパーティション化」を参照してください。例F-1に、デフォルトのADF Facesのadf-js-partitions.xmlファイルを示します。

例F-1 デフォルトのadf-js-partitions.xmlファイル

<?xml version="1.0" encoding="utf-8"?>

<partitions xmlns="http://xmlns.oracle.com/adf/faces/partition">

<partition>
<partition-name>boot</partition-name>
<feature>AdfBootstrap</feature>
</partition>

<partition>
<partition-name>core</partition-name>

<feature>AdfCore</feature>

<!-- Behavioral component super classes -->
<feature>AdfUIChoose</feature>
<feature>AdfUICollection</feature>
<feature>AdfUICommand</feature>
<feature>AdfUIDialog</feature>
<feature>AdfUIDocument</feature>
<feature>AdfUIEditableValue</feature>
<feature>AdfUIForm</feature>
<feature>AdfUIGo</feature>
<feature>AdfUIInput</feature>
<feature>AdfUIObject</feature>
<feature>AdfUIOutput</feature>
<feature>AdfUIPanel</feature>
<feature>AdfUIPopup</feature>
<feature>AdfUISelectBoolean</feature>
<feature>AdfUISelectInput</feature>
<feature>AdfUISelectOne</feature>
<feature>AdfUISelectMany</feature>
<feature>AdfUIShowDetail</feature>
<feature>AdfUISubform</feature>
<feature>AdfUIValue</feature>

<!-- These are all so common that we group them with core -->
<feature>AdfRichDocument</feature>
<feature>AdfRichForm</feature>
<feature>AdfRichPopup</feature>
<feature>AdfRichSubform</feature>
<feature>AdfRichCommandButton</feature>
<feature>AdfRichCommandLink</feature>

<!--
Dialog is currently on every page for messaging.  No use
in putting these in a separate partition.
-->
<feature>AdfRichPanelWindow</feature>
<feature>AdfRichDialog</feature>

<!-- af:showPopupBehavior is so small/common, belongs in core -->
<feature>AdfShowPopupBehavior</feature>
</partition>

<partition>
<partition-name>accordion</partition-name>
<feature>AdfRichPanelAccordion</feature>
</partition>

<partition>
<partition-name>border</partition-name>
<feature>AdfRichPanelBorderLayout</feature>
</partition>

<partition>
<partition-name>box</partition-name>
<feature>AdfRichPanelBox</feature>
</partition>

<partition>
<partition-name>calendar</partition-name>
<feature>AdfUICalendar</feature>
<feature>AdfRichCalendar</feature>
<feature>AdfCalendarDragSource</feature>
<feature>AdfCalendarDropTarget</feature>
</partition>

<partition>
<partition-name>collection</partition-name>
<feature>AdfUIDecorateCollection</feature>
<feature>AdfRichPanelCollection</feature>
</partition>

<partition>
<partition-name>color</partition-name>
<feature>AdfRichChooseColor</feature>
<feature>AdfRichInputColor</feature>
</partition>

<partition>
<partition-name>date</partition-name>
<feature>AdfRichChooseDate</feature>
<feature>AdfRichInputDate</feature>
</partition>

<partition>
<partition-name>declarativeComponent</partition-name>
<feature>AdfUIInclude</feature>
<feature>AdfUIDeclarativeComponent</feature>
<feature>AdfRichDeclarativeComponent</feature>
</partition>

<partition>
<partition-name>detail</partition-name>
<feature>AdfRichShowDetail</feature>
</partition>

<partition>
<partition-name>dnd</partition-name>
<feature>AdfDragAndDrop</feature>
<feature>AdfCollectionDragSource</feature>
<feature>AdfStampedDropTarget</feature>
<feature>AdfCollectionDropTarget</feature>
<feature>AdfAttributeDragSource</feature>
<feature>AdfAttributeDropTarget</feature>
<feature>AdfComponentDragSource</feature>
<feature>AdfDropTarget</feature>
</partition>

<partition>
<partition-name>detailitem</partition-name>
<feature>AdfRichShowDetailItem</feature>
</partition>

<partition>
<partition-name>file</partition-name>
<feature>AdfRichInputFile</feature>
</partition>

<partition>
<partition-name>form</partition-name>
<feature>AdfRichPanelFormLayout</feature>
<feature>AdfRichPanelLabelAndMessage</feature>
</partition>

<partition>
<partition-name>format</partition-name>
<feature>AdfRichOutputFormatted</feature>
</partition>

<partition>
<partition-name>frame</partition-name>
<feature>AdfRichInlineFrame</feature>
</partition>

<partition>
<partition-name>header</partition-name>
<feature>AdfRichPanelHeader</feature>
<feature>AdfRichShowDetailHeader</feature>
</partition>

<partition>
<partition-name>imagelink</partition-name>
<feature>AdfRichCommandImageLink</feature>
</partition>

<partition>
<partition-name>iedit</partition-name>
<feature>AdfInlineEditing</feature>
</partition>

<partition>
<partition-name>input</partition-name>
<feature>AdfRichInputText</feature>
<feature>AdfInsertTextBehavior</feature>
</partition>

<partition>
<partition-name>label</partition-name>
<feature>AdfRichOutputLabel</feature>
</partition>

<partition>
<partition-name>list</partition-name>
<feature>AdfRichPanelList</feature>
</partition>

<partition>
<partition-name>lov</partition-name>
<feature>AdfUIInputPopup</feature>
<feature>AdfRichInputComboboxListOfValues</feature>
<feature>AdfRichInputListOfValues</feature>
</partition>

<partition>
<partition-name>media</partition-name>
<feature>AdfRichMedia</feature>
</partition>

<partition>
<partition-name>message</partition-name>
<feature>AdfUIMessage</feature>
<feature>AdfUIMessages</feature>
<feature>AdfRichMessage</feature>
<feature>AdfRichMessages</feature>
</partition>

<partition>
<partition-name>menu</partition-name>
<feature>AdfRichCommandMenuItem</feature>
<feature>AdfRichGoMenuItem</feature>
<feature>AdfRichMenuBar</feature>
<feature>AdfRichMenu</feature>
</partition>

<partition>
<partition-name>nav</partition-name>
<feature>AdfUINavigationPath</feature>
<feature>AdfUINavigationLevel</feature>
<feature>AdfRichBreadCrumbs</feature>
<feature>AdfRichCommandNavigationItem</feature>
<feature>AdfRichNavigationPane</feature>
</partition>

<partition>
<partition-name>note</partition-name>
<feature>AdfRichNoteWindow</feature>
</partition>

<partition>
<partition-name>poll</partition-name>
<feature>AdfUIPoll</feature>
<feature>AdfRichPoll</feature>
</partition>

<partition>
<partition-name>progress</partition-name>
<feature>AdfUIProgress</feature>
<feature>AdfRichProgressIndicator</feature>
</partition>

<partition>
<partition-name>print</partition-name>
<feature>AdfShowPrintablePageBehavior</feature>
</partition>

<partition>
<partition-name>scrollComponentIntoView</partition-name>
<feature>AdfScrollComponentIntoViewBehavior</feature>
</partition>

<partition>
<partition-name>query</partition-name>
<feature>AdfUIQuery</feature>
<feature>AdfRichQuery</feature>
<feature>AdfRichQuickQuery</feature>
</partition>

<partition>
<partition-name>region</partition-name>
<feature>AdfUIRegion</feature>
<feature>AdfRichRegion</feature>
</partition>

<partition>
<partition-name>reset</partition-name>
<feature>AdfUIReset</feature>
<feature>AdfRichResetButton</feature>
</partition>

<partition>
<partition-name>rte</partition-name>
<feature>AdfRichTextEditor</feature>
<feature>AdfRichTextEditorInsertBehavior</feature>
</partition>

<partition>
<partition-name>select</partition-name>

<feature>AdfRichSelectBooleanCheckbox</feature>
<feature>AdfRichSelectBooleanRadio</feature>
<feature>AdfRichSelectManyCheckbox</feature>
<feature>AdfRichSelectOneRadio</feature>
</partition>

<partition>
<partition-name>selectmanychoice</partition-name>
<feature>AdfRichSelectManyChoice</feature>
</partition>

<partition>
<partition-name>selectmanylistbox</partition-name>
<feature>AdfRichSelectManyListbox</feature>
</partition>

<partition>
<partition-name>selectonechoice</partition-name>
<feature>AdfRichSelectOneChoice</feature>
</partition>

<partition>
<partition-name>selectonelistbox</partition-name>
<feature>AdfRichSelectOneListbox</feature>
</partition>

<partition>
<partition-name>shuttle</partition-name>
<feature>AdfUISelectOrder</feature>
<feature>AdfRichSelectManyShuttle</feature>
<feature>AdfRichSelectOrderShuttle</feature>
</partition>

<partition>
<partition-name>slide</partition-name>
<feature>AdfRichInputNumberSlider</feature>
<feature>AdfRichInputRangeSlider</feature>
</partition>

<partition>
<partition-name>spin</partition-name>
<feature>AdfRichInputNumberSpinbox</feature>
</partition>

<partition>
<partition-name>status</partition-name>
<feature>AdfRichStatusIndicator</feature>
</partition>

<partition>
<partition-name>stretch</partition-name>
<feature>AdfRichDecorativeBox</feature>
<feature>AdfRichPanelSplitter</feature>
<feature>AdfRichPanelStretchLayout</feature>
<feature>AdfRichPanelDashboard</feature>
<feature>AdfPanelDashboardBehavior</feature>
<feature>AdfDashboardDropTarget</feature>
</partition>

<partition>
<partition-name>tabbed</partition-name>
<feature>AdfUIShowOne</feature>
<feature>AdfRichPanelTabbed</feature>
</partition>

<partition>
<partition-name>table</partition-name>
<feature>AdfUIIterator</feature>
<feature>AdfUITable</feature>
<feature>AdfUITable2</feature>
<feature>AdfUIColumn</feature>
<feature>AdfRichColumn</feature>
<feature>AdfRichTable</feature>
</partition>

<partition>
<partition-name>toolbar</partition-name>
<feature>AdfRichCommandToolbarButton</feature>
<feature>AdfRichToolbar</feature>
</partition>

<partition>
<partition-name>toolbox</partition-name>
<feature>AdfRichToolbox</feature>
</partition>

<partition>
<partition-name>train</partition-name>
<feature>AdfUIProcess</feature>
<feature>AdfRichCommandTrainStop</feature>
<feature>AdfRichTrainButtonBar</feature>
<feature>AdfRichTrain</feature>
</partition>

<partition>
<partition-name>tree</partition-name>
<feature>AdfUITree</feature>
<feature>AdfUITreeTable</feature>
<feature>AdfRichTree</feature>
<feature>AdfRichTreeTable</feature>
</partition>

<!--
Some components which typically do have client-side representation,
but small enough that we might as well download in a single partition
in the event that any of these are needed.
-->
<partition>
<partition-name>uncommon</partition-name>
<feature>AdfRichGoButton</feature>
<feature>AdfRichIcon</feature>
<feature>AdfRichImage</feature>
<feature>AdfRichOutputText</feature>
<feature>AdfRichPanelGroupLayout</feature>
<feature>AdfRichSeparator</feature>
<feature>AdfRichSpacer</feature>
<feature>AdfRichGoLink</feature>
</partition>

<partition>
<partition-name>eum</partition-name>
<feature>AdfEndUserMonitoring</feature>
</partition>

<partition>
<partition-name>ads</partition-name>
<feature>AdfActiveDataService</feature>
</partition>

<partition>
<partition-name>automation</partition-name>
<feature>AdfAutomationTest</feature>
</partition>

</partitions>

F.2 第23章「グラフ・コンポーネントの使用方法」のサンプル

次のサンプル・コードは、Employeeクラス、サンプル・データおよび23.7.6項「グラフへのドラッグ・アンド・ドロップの追加」で参照されるドラッグ・アンド・ドロップ・メソッドを作成します。

例F-2 グラフのドラッグ・アンド・ドロップのサンプルのdragAndDropマネージドBean

public class dragAndDrop {
private Random m_random = new Random(23);
// Simple class to represent employee data
public static class Employee {
public final String name;
private int performance;
private int potential;
private double salary;
private double bonus;
private int experience;
public Employee(String name, Random r) {
this.name = name;
this.performance = r.nextInt(100);
this.potential = r.nextInt(100);
this.salary = r.nextInt(100000);
this.bonus = r.nextInt(50000);
this.experience = r.nextInt(20);
}
// Returns a copy of the employee with a new name
public Employee(String name, Employee e) {
this.name = name;
this.performance = e.performance;
this.potential = e.potential;
this.salary = e.salary;
this.bonus = e.bonus;
this.experience = e.experience;
}
public String getName() {return name;}
public int getPerformance() { return performance; }
public int getPotential() { return potential; }
public void setSalary(double salary) { this.salary = salary; }
public double getSalary() { return salary; }
public void setBonus(double bonus) { this.bonus = bonus; }
public double getBonus() { return bonus; }
public int getExperience() { return experience; }
}
// Returns the employee represented by the selection
private Employee findEmployee(List<Employee> list, GraphSelection selection) {
if(!(selection instanceof DataSelection))
return null;
List<KeyMap> groupKeys = ((DataSelection)selection).getGroupKeys();
for(KeyMap groupKey : groupKeys) {
Set groupKeySet = groupKey.keySet();
for(Object key : groupKeySet) {
// Find the employee
String name = groupKey.get((String)key);
Employee emp = findEmployee(list, name);
if(emp != null) {
return emp;
}
}
}
return null;
}
private Employee findEmployee(List<Employee> list, String name) {
for(Employee emp : list) {
if(name.equals(emp.name))
return emp;
}
return null;
}
// Converts the list of employees to a bubble data model
private static DataModel createBubbleDataModel(List<Employee> employees) {
Object[][] data = new Object[employees.size()*3][1];
Object[] colLabels = new Object[employees.size()*3];
Object[] rowLabels = {"Employees"};
for(int i=0; i<employees.size(); i++) {
Employee emp = employees.get(i);
data[i*3][0] = emp.performance;
data[i*3+1][0] = emp.salary;
data[i*3+2][0] = emp.experience;
colLabels[i*3] = emp.name;
colLabels[i*3+1] = emp.name + "1";
colLabels[i*3+2] = emp.name + "2";
}
LocalXMLDataSource dataSource = new LocalXMLDataSource(colLabels, rowLabels, data);
return new GraphDataModel(dataSource);
}
protected List<Employee> m_graphList = this.setEmployeeList();
public List<Employee> setEmployeeList(){
List<Employee> em_graphList = new ArrayList<Employee>();
em_graphList.add(new Employee("Dan", m_random));
em_graphList.add(new Employee("Ben", m_random));
em_graphList.add(new Employee("Dave", m_random));
em_graphList.add(new Employee("Chris", m_random));
em_graphList.add(new Employee("Frank", m_random));
em_graphList.add(new Employee("Jill", m_random));
em_graphList.add(new Employee("Ray", m_random));
return em_graphList;
}
public DataModel getGraphModel() {
if(m_graphList == null) {
setEmployeeList();
}
return createBubbleDataModel(m_graphList);
}
protected List<Employee> m_tableModel = this.setTableModelList();
public List<Employee> setTableModelList(){
List<Employee> em_tableModel = new ArrayList<Employee>();
em_tableModel.add(new Employee("Brad", m_random));
em_tableModel.add(new Employee("Derrick", m_random));
em_tableModel.add(new Employee("Matt", m_random));
return em_tableModel;
}
public List getTableModel() {
if(m_tableModel == null) {
setTableModelList();
}
return m_tableModel;
}
public DnDAction fromGraphDropListener(DropEvent event) {
// Get the ComponentHandle from the transferable
Transferable transferable = event.getTransferable();
GraphSelectionSet selectionSet = transferable.getData(GraphSelectionSet.class);
// Now change each marker based on the DropEvent's proposed action
DnDAction proposedAction = event.getProposedAction();
for(GraphSelection selection : selectionSet) {
Employee emp = findEmployee(m_graphList, selection);
if(emp == null)
return DnDAction.NONE;
if(proposedAction == DnDAction.COPY) {
m_tableModel.add(new Employee("Copy of " + emp.getName(), emp));
}
else if(proposedAction == DnDAction.LINK) {
m_tableModel.add(new Employee("Link to " + emp.getName(), emp));
}
else if(proposedAction == DnDAction.MOVE) {
m_graphList.remove(emp);
m_tableModel.add(emp);
}
}
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return proposedAction;
}
public DnDAction fromTableDropListener(DropEvent event) {
Transferable transferable = event.getTransferable();
DataFlavor<RowKeySet> dataFlavor = DataFlavor.getDataFlavor(RowKeySet.class, "fromTable");
RowKeySet set = transferable.getData(dataFlavor);
Employee emp = null;
if(set != null && !set.isEmpty()) {
int index = (Integer) set.iterator().next();
emp = m_tableModel.get(index);
}
if(emp == null)
return DnDAction.NONE;
DnDAction proposedAction = event.getProposedAction();
if(proposedAction == DnDAction.COPY) {
m_graphList.add(emp);
}
else if(proposedAction == DnDAction.LINK) {
m_graphList.add(emp);
}
else if(proposedAction == DnDAction.MOVE) {
m_graphList.add(emp);
m_tableModel.remove(emp);
}
else
return DnDAction.NONE;
RequestContext.getCurrentInstance().addPartialTarget(event.getDragComponent());
return event.getProposedAction();
}

F.3 第30章「ツリーマップおよびサンバースト・コンポーネントの使用」のサンプル

次は、ツリーマップとサンバースト・コンポーネントを作成するサンプル・コードです。

F.3.1 ツリーマップおよびサンバースト人口調査データ例のサンプル・コード

ツリーマップあるいはサンバーストをUI優先開発を使用して作成するには、クラスとマネージドBeanを使用してツリー・ノードとツリー・モデルを定義し、ツリーにデータを移入し、かつツリーマップあるいはサンバースト構成の必要に応じ、追加のメソッドを追加します。

例F-3に、国勢調査のデータ例でのツリー・ノードを定義するコードのサンプルを示します。ラベル、サイズ、および色についての必要な設定は、パラメータとしてツリー・ノードに渡されます。

例F-3 ツリーマップあるいはサンバーストのツリー・ノードを作成するコード・サンプル

import java.awt.Color;
import java.util.ArrayList;
import java.util.List;

public class TreeNode {
private final String m_text;
private final Number m_size;
private final Color m_color;
private final List<TreeNode> m_children = new ArrayList<TreeNode>();

public TreeNode(String text, Number size, Color color) {
m_text = text;
m_size = size;
m_color = color;
}
public String getText() {
return m_text;
}
public Number getSize() {
return m_size;
}
public Color getColor() {
return m_color;
}
public void addChild(TreeNode child) {
m_children.add(child);
}
public void addChildren(List<TreeNode> children) {
m_children.addAll(children);
}
public List<TreeNode> getChildren() {
return m_children;
}
@Override
public String toString() {
return m_text + ": " + m_color + " " + Math.round(m_size.doubleValue());
}
}

UI優先開発におけるツリーマップあるいはサンバーストにデータを供給するには、クラスあるいはマネージドBeanをユーザーのアプリケーションに追加します。アプリケーションは例F-3のツリー・ノードを展開し、そこにデータを移入します。ツリー・モデルを設定するクラスは、org.apache.myfaces.trinidad.model.TreeModelクラスの実装にする必要があります。ツリー・モデルを定義したら、org.apache.myfaces.trinidad.model.ChildPropertyTreeModelを実装するメソッドを作成してツリー・モデルを完成させます。

例F-4は、国勢データの例において、ルートと子ノードの構造を設定し、子レベルにデータを移入し、ノードの色およびサイズを定義するサンプル・クラスを示します。

例F-4 ツリーマップおよびサンバースト用に国勢調査データ・モデルを作成するコード・サンプル

import java.awt.Color;

import java.util.ArrayList;
import java.util.List;

import org.apache.myfaces.trinidad.model.ChildPropertyTreeModel;
import org.apache.myfaces.trinidad.model.TreeModel;

public class CensusData {

public static TreeModel getUnitedStatesData() {
return getModel(ROOT);
}

public static TreeModel getRegionWestData() {
return getModel(REGION_W);
}

public static TreeModel getRegionNortheastData() {
return getModel(REGION_NE);
}

public static TreeModel getRegionMidwestData() {
return getModel(REGION_MW);
}

public static TreeModel getRegionSouthData() {
return getModel(REGION_S);
}

public static TreeModel getDivisionPacificData() {
return getModel(DIVISION_P);
}

private static TreeModel getModel(DataItem rootItem) {
TreeNode root = getTreeNode(rootItem);
return new ChildPropertyTreeModel(root, "children");
}

private static TreeNode getTreeNode(DataItem dataItem)
{
// Create the node itself
TreeNode node = new CensusTreeNode(dataItem.getName(),
dataItem.getPopulation(),
getColor(dataItem.getIncome(), MIN_INCOME, MAX_INCOME),
dataItem.getIncome());

// Create its children
List<TreeNode> children = new ArrayList<TreeNode>();
for(DataItem childItem : dataItem.children) {
children.add(getTreeNode(childItem));
}

// Add the children and return
node.addChildren(children);
return node;
}

private static Color getColor(double value, double min, double max) {
double percent = Math.max((value - min) / max, 0);
if(percent > 0.5) {
double modifier = (percent - 0.5) * 2;
return new Color((int)(modifier*102), (int)(modifier*153), (int)(modifier*51));
}
else {
double modifier = percent *2;
return new Color((int)(modifier*204), (int)(modifier*51), 0);
}
}

public static class DataItem {
private final String name;
private final int population;
private final int income;
private final List<DataItem> children;

public DataItem(String name, int population, int income) {
this.name = name;
this.population = population;
this.income = income;
this.children = new ArrayList<DataItem>();
}

public void addChild(DataItem child) {
this.children.add(child);
}

public String getName() {
return name;
}

public int getPopulation() {
return population;
}

public int getIncome() {
return income;
}

public List<CensusData.DataItem> getChildren() {
return children;
}
}

private static final int MIN_INCOME = 0;
private static final int MAX_INCOME = 70000;

private static final DataItem ROOT = new DataItem("United States", 301461533, 51425);

private static final DataItem REGION_NE = new DataItem("Northeast Region", 54906297, 57208);
private static final DataItem REGION_MW = new DataItem("Midwest Region", 66336038, 49932);
private static final DataItem REGION_S = new DataItem("South Region", 110450832, 47204);
private static final DataItem REGION_W = new DataItem("West Region", 69768366, 56171);

private static final DataItem DIVISION_NE = new DataItem("New England", 14315257, 61511);
private static final DataItem DIVISION_MA = new DataItem("Middle Atlantic", 40591040, 55726);
private static final DataItem DIVISION_ENC = new DataItem("East North Central", 46277998, 50156);
private static final DataItem DIVISION_WNC = new DataItem("West North Central", 20058040, 49443);
private static final DataItem DIVISION_SA = new DataItem("South Atlantic", 57805475, 50188);
private static final DataItem DIVISION_ESC = new DataItem("East South Central", 17966553, 41130);
private static final DataItem DIVISION_WSC = new DataItem("West South Central", 34678804, 45608);
private static final DataItem DIVISION_M = new DataItem("Mountain", 21303294, 51504);
private static final DataItem DIVISION_P = new DataItem("Pacific", 48465072, 58735);

static {
// Set up the regions
ROOT.addChild(REGION_NE);
ROOT.addChild(REGION_MW);
ROOT.addChild(REGION_S);
ROOT.addChild(REGION_W);

// Set up the divisions
REGION_NE.addChild(DIVISION_NE);
REGION_NE.addChild(DIVISION_MA);
REGION_MW.addChild(DIVISION_ENC);
REGION_MW.addChild(DIVISION_WNC);
REGION_S.addChild(DIVISION_SA);
REGION_S.addChild(DIVISION_ESC);
REGION_S.addChild(DIVISION_WSC);
REGION_W.addChild(DIVISION_M);
REGION_W.addChild(DIVISION_P);

// Set up the states
DIVISION_NE.addChild(new DataItem("Connecticut", 3494487, 67721));
DIVISION_NE.addChild(new DataItem("Maine", 1316380, 46541));
DIVISION_NE.addChild(new DataItem("Massachusetts", 6511176, 64496));
DIVISION_NE.addChild(new DataItem("New Hampshire", 1315419, 63033));
DIVISION_NE.addChild(new DataItem("Rhode Island", 1057381, 55569));
DIVISION_NE.addChild(new DataItem("Vermont", 620414, 51284));

DIVISION_MA.addChild(new DataItem("New Jersey", 8650548, 68981));
DIVISION_MA.addChild(new DataItem("New York", 19423896, 55233));
DIVISION_MA.addChild(new DataItem("Pennsylvania", 12516596, 49737));

DIVISION_ENC.addChild(new DataItem("Indiana", 6342469, 47465));
DIVISION_ENC.addChild(new DataItem("Illinois", 12785043, 55222));
DIVISION_ENC.addChild(new DataItem("Michigan", 10039208, 48700));
DIVISION_ENC.addChild(new DataItem("Ohio", 11511858, 47144));
DIVISION_ENC.addChild(new DataItem("Wisconsin", 5599420, 51569));

DIVISION_WNC.addChild(new DataItem("Iowa", 2978880, 48052));
DIVISION_WNC.addChild(new DataItem("Kansas", 2777835, 48394));
DIVISION_WNC.addChild(new DataItem("Minnesota", 5188581, 57007));
DIVISION_WNC.addChild(new DataItem("Missouri", 5904382, 46005));
DIVISION_WNC.addChild(new DataItem("Nebraska", 1772124, 47995));
DIVISION_WNC.addChild(new DataItem("North Dakota", 639725, 45140));
DIVISION_WNC.addChild(new DataItem("South Dakota", 796513, 44828));

DIVISION_SA.addChild(new DataItem("Delaware", 863832, 57618));
DIVISION_SA.addChild(new DataItem("District of Columbia", 588433, 56519));
DIVISION_SA.addChild(new DataItem("Florida", 18222420, 47450));
DIVISION_SA.addChild(new DataItem("Georgia", 9497667, 49466));
DIVISION_SA.addChild(new DataItem("Maryland", 5637418, 69475));
DIVISION_SA.addChild(new DataItem("North Carolina", 9045705, 45069));
DIVISION_SA.addChild(new DataItem("South Carolina", 4416867, 43572));
DIVISION_SA.addChild(new DataItem("Virginia", 7721730, 60316));
DIVISION_SA.addChild(new DataItem("West Virginia", 1811403, 37356));

DIVISION_ESC.addChild(new DataItem("Alabama", 4633360, 41216));
DIVISION_ESC.addChild(new DataItem("Kentucky", 4252000, 41197));
DIVISION_ESC.addChild(new DataItem("Mississippi", 2922240, 36796));
DIVISION_ESC.addChild(new DataItem("Tennessee", 6158953, 42943));

DIVISION_WSC.addChild(new DataItem("Arkansas", 2838143, 38542));
DIVISION_WSC.addChild(new DataItem("Louisiana", 4411546, 42167));
DIVISION_WSC.addChild(new DataItem("Oklahoma", 3610073, 41861));
DIVISION_WSC.addChild(new DataItem("Texas", 23819042, 48199));

DIVISION_M.addChild(new DataItem("Arizona", 6324865, 50296));
DIVISION_M.addChild(new DataItem("Colorado", 4843211, 56222));
DIVISION_M.addChild(new DataItem("Idaho", 1492573, 46183));
DIVISION_M.addChild(new DataItem("Montana", 956257, 43089));
DIVISION_M.addChild(new DataItem("Nevada", 2545763, 55585));
DIVISION_M.addChild(new DataItem("New Mexico", 1964860, 42742));
DIVISION_M.addChild(new DataItem("Utah", 2651816, 55642));
DIVISION_M.addChild(new DataItem("Wyoming", 523949, 51990));

DIVISION_P.addChild(new DataItem("Alaska", 683142, 64635));
DIVISION_P.addChild(new DataItem("California", 36308527, 60392));
DIVISION_P.addChild(new DataItem("Hawaii", 1280241, 64661));
DIVISION_P.addChild(new DataItem("Oregon", 3727407, 49033));
DIVISION_P.addChild(new DataItem("Washington", 6465755, 56384));
}

public static class CensusTreeNode extends TreeNode {
private int income;

public CensusTreeNode(String text, Number size, Color color, int income) {
super(text, size, color);
this.income = income;
}

public int getIncome() {
return income;
}
}
}

最後に、UI-first開発におけるツリー・モデルを完成するには、マネージドBeanを、データを含むクラスまたはBeanを参照するユーザーのアプリケーションに加え、オプションとして、ツリーマップあるいはサンバーストのカスタマイズのために他のメソッドを追加します。

例F-5に、国勢調査のツリーマップをインスタンス化し、それに国勢調査データを移入するコードのサンプルを示します。この例はまた、ツリーマップのノードの行データをラベル表示のための文字列に変換するサンプル・メソッド(convertToString)を含んでいます。

例F-5 国勢調査データのツリーマップ設定のためのマネージドBeanの例

import org.apache.myfaces.trinidad.component.UIXHierarchy;
import org.apache.myfaces.trinidad.model.RowKeySet;
import org.apache.myfaces.trinidad.model.TreeModel;
import oracle.adf.view.faces.bi.component.treemap.UITreemap;

public class SampleTreemap {
// Data Model Attrs
private TreeModel currentModel;
private final CensusData censusData = new CensusData();
private String censusRoot = "United States";
private UITreemap treemap;

public TreeModel getCensusRootData() {
return censusData.getUnitedStatesData();
}
public TreeModel getCensusData() {
if ("West Region".equals(censusRoot))
return censusData.getRegionWestData();
else if ("South Region".equals(censusRoot))
return censusData.getRegionSouthData();
else if ("Midwest Region".equals(censusRoot))
return censusData.getRegionMidwestData();
else if ("Northeast Region".equals(censusRoot))
return censusData.getRegionNortheastData();
else if ("Pacific Division".equals(censusRoot))
return censusData.getDivisionPacificData();
else
return censusData.getUnitedStatesData();
}
public TreeModel getData() {
// Return cached data model if available
if(currentModel != null)
return currentModel;
currentModel = getCensusData();
return currentModel;
}
public void setCensusRoot(String censusRoot) {
this.censusRoot = censusRoot;
}
public String getCensusRoot() {
return censusRoot;
}
//Converts the rowKeySet into a string of node text labels.
public static String convertToString(RowKeySet rowKeySet, UIXHierarchy hierarchy) {
StringBuilder s = new StringBuilder();
if (rowKeySet != null) {
for (Object rowKey : rowKeySet) {
TreeNode rowData = (TreeNode)hierarchy.getRowData(rowKey);
s.append(rowData.getText()).append(", ");
}
// Remove the trailing comma
if (s.length() > 0)
s.setLength(s.length() - 2);
}
return s.toString();
}
public void setTreemap(UITreemap treemap) {
this.treemap = treemap;
}
public UITreemap getTreemap() {
return treemap;
}
}

両方のコンポーネントは同じツリー・モデルを使用するため、サンバースト国勢調査の例を設定するコードはほとんど同一です。例は、F.3.2項「サンバースト・マネージドBeanのサンプル・コード」を参照してください。

F.3.2 サンバースト・マネージドBeanのサンプル・コード

次のサンプル・コードは、国勢調査サンバーストをインスタンス化し、それに国勢調査データを移入します。この例はまた、サンバーストのノードの行データをラベル表示のための文字列に変換するサンプル・メソッド(convertToString)を含んでいます。

例F-6 国勢調査データのサンバースト設定のためのマネージドBeanの例

import oracle.adf.view.faces.bi.component.sunburst.UISunburst;
import org.apache.myfaces.trinidad.component.UIXHierarchy;
import org.apache.myfaces.trinidad.model.RowKeySet;
import org.apache.myfaces.trinidad.model.TreeModel;

public class SunburstSample {
// Components
private UISunburst sunburst;
// Attributes
private TreeModel currentModel;
private final CensusData censusData = new CensusData();
private String censusRoot = "United States";

public TreeModel getCensusRootData() {
return censusData.getUnitedStatesData();
}
public TreeModel getCensusData() {
if ("West Region".equals(censusRoot))
return censusData.getRegionWestData();
else if ("South Region".equals(censusRoot))
return censusData.getRegionSouthData();
else if ("Midwest Region".equals(censusRoot))
return censusData.getRegionMidwestData();
else if ("Northeast Region".equals(censusRoot))
return censusData.getRegionNortheastData();
else if ("Pacific Division".equals(censusRoot))
return censusData.getDivisionPacificData();
else
return censusData.getUnitedStatesData();
}
public TreeModel getData() {
// Return cached data model if available
if(currentModel != null)
return currentModel;
currentModel = getCensusData();
return currentModel;
}
public void setCensusRoot(String censusRoot) {
this.censusRoot = censusRoot;
}
public String getCensusRoot() {
return censusRoot;
}
public static String convertToString(RowKeySet rowKeySet, UIXHierarchy hierarchy) {
StringBuilder s = new StringBuilder();
if (rowKeySet != null) {
for (Object rowKey : rowKeySet) {
TreeNode rowData = (TreeNode)hierarchy.getRowData(rowKey);
s.append(rowData.getText()).append(", ");
}
// Remove the trailing comma
if (s.length() > 0)
s.setLength(s.length() - 2);
}
return s.toString();
}
public void setSunburst(UISunburst sunburst) {
this.sunburst = sunburst;
}
public UISunburst getSunburst() {
return sunburst;
}
}

F.4 第34章「カスタムADF Facesコンポーネントの作成」のサンプル

次に、カスタム・コンポーネントを作成するコード例を示します。

F.4.1 JavaScriptのイベント・コード

カスタム・コンポーネントの作成時には、マウス・クリックなどのイベントが起動された場合に必要な機能を実行するコードをJavaScriptで記述する必要があります。例F-7に、tagPaneコンポーネントに追加できるイベント・コードを示します。

例F-7 tagPaneイベントのJavaScript

/**
* Fires a select type event to the server for the source component
* when a tag is clicked.
*/
function AcmeTagSelectEvent(source, tag)
{
AdfAssert.assertPrototype(source, AdfUIComponent);
AdfAssert.assertString(tag); this.Init(source, tag);
}
// make AcmeTagSelectEvent a subclass of AdfComponentEvent

AdfObject.createSubclass(AcmeTagSelectEvent, AdfComponentEvent);
/**
* The event type
*/
AcmeTagSelectEvent.SELECT_EVENT_TYPE = "tagSelect";
/**
* Event Object constructor
*/
AcmeTagSelectEvent.prototype.Init = function(source, tag)
{
AdfAssert.assertPrototype(source, AdfUIComponent);
AdfAssert.assertString(tag);
this._tag = tag;
AcmeTagSelectEvent.superclass.Init.call(this, source, AcmeTagSelectEvent.SELECT_EVENT_TYPE);}
/**
* Indicates this event should be sent to the server
*/
AcmeTagSelectEvent.prototype.propagatesToServer = function()
{
return true;
}
/**
* Override of AddMarshalledProperties to add parameters * sent server side.
*/
AcmeTagSelectEvent.prototype.AddMarshalledProperties = function( properties)
{
properties.tag = this._tag;

}
/**
* Convenient method for queue a AcmeTagSelectEvent.
*/
AcmeTagSelectEvent.queue = function(component, tag)
{
AdfAssert.assertPrototype(component, AdfUIComponent);
AdfAssert.assertString(tag);
AdfLogger.LOGGER.logMessage(AdfLogger.FINEST,     "AcmeTagSelectEvent.queue(component, tag)");
new AcmeTagSelectEvent(component, tag).queue(true);
}
/**
* returns the selected file type
*/
AcmeTagSelectEvent.prototype.getTag = function()
{
return this._tag;}
/**
* returns a debug string
*/
AcmeTagSelectEvent.prototype.toDebugString = function()
{
var superString = AcmeTagSelectEvent.superclass.toDebugString.call(this);
return superString.substring(0, superString.length - 1)
+     ", tag="
+ this._tag     + "]";
}
/*
*
* Make sure that this event only invokes immediate validators
* on the client.
*/
AcmeTagSelectEvent.prototype.isImmediate = function()
{
return true;
}

F.4.2 タグ・ライブラリ・ディスクリプタ・ファイルのコード例

カスタム・コンポーネントの作成時には、Javaクラスの詳細をJSPコンパイル・エンジンとIDEツールに提供する、タグ・ライブラリ・ディスクリプタ(TLD)ファイルを作成する必要があります。例F-8に、tagPaneコンポーネントを定義するTLDファイルの例を示します。

例F-8 tagPaneのacme.tldタグ・ライブラリ・ディスクリプタ・コード

<?xml version = '1.0' encoding = 'windows-1252'?>
<taglib xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd"
version="2.1" xmlns="http://java.sun.com/xml/ns/javaee">
<description>Acme Corporation JSF components</description>
<display-name>acme</display-name>
<tlib-version>1.0</tlib-version>
<short-name>acme</short-name>
<uri>http://oracle.adfdemo.acme</uri>
<tag>
<description>
</description>
<name>tagPane</name>
<tag-class>oracle.adfdemo.acme.faces.taglib.TagPaneTag</tag-class>
<body-content>JSP</body-content>
<attribute>
<name>id</name>
<rtexprvalue>true</rtexprvalue>
</attribute>
<attribute>
<name>rendered</name>
<deferred-value>
<type>boolean</type>
</deferred-value>
</attribute>
<attribute>
<name>tagSelectListener</name>
<deferred-method>
<method-signature>void
</method-signature>
myMethod(oracle.adfdemo.acme.faces.event.TagSelectEvent)
</deferred-method>
</attribute>
<attribute>
<name>visible</name>
<deferred-value>
<type>boolean</type>
</deferred-value>
</attribute>
<attribute>
<name>partialTriggers</name>
<deferred-value>
</deferred-value>
</attribute>
<attribute>
<name>inlineStyle</name>
<deferred-value/>
</attribute>
<attribute>
<name>inlineClass</name>
<deferred-value/>
</attribute>
<attribute>
<name>tags</name>
<deferred-value/>
</attribute>
<attribute>
<name>binding</name>
<deferred-value/>
</attribute>
<attribute>
<name>orderBy</name>
<deferred-value/>
</attribute>
</tag>
</taglib>

F.4.3 コンポーネント・クラスのコード例

カスタム・コンポーネントを作成する場合は、プロパティ情報とアクセッサを含むJavaクラスを作成する必要があります。例F-9に、サンプルのTagPaneコンポーネントの作成に使用するコードを示します。

例F-9 TagPaneコンポーネント・クラス

package oracle.adfdemo.acme.faces.component;

import java.util.Map;
import java.util.Set;

import javax.el.MethodExpression;

import javax.faces.event.AbortProcessingException;
import javax.faces.event.FacesEvent;

import oracle.adf.view.rich.event.ClientListenerSet;

import oracle.adfdemo.acme.faces.event.TagSelectEvent;
import oracle.adfdemo.acme.faces.event.TagSelectListener;

import org.apache.myfaces.trinidad.bean.FacesBean;
import org.apache.myfaces.trinidad.bean.PropertyKey;
import org.apache.myfaces.trinidad.component.UIXObject;

public class TagPane
extends UIXObject
{

/**
* <p>Establishes a <code>Type</code> bean that contains JSF component property
* information.  This static public final property <code>TYPE</code> shadows a
* property with the same name in the super class.  The <code>TYPE</code>
* attribute is defined once pre JSF component class.  The factory method call to
* <code>FacesBean.Type</code> passes the super class reference
* <code>UIXObject.TYPE</code> which copies down property information defined in
* the super type.</p>
*/
static public final FacesBean.Type TYPE =
new FacesBean.Type(UIXObject.TYPE);

/**
* <p>Custom CSS applied to the style attribute of the root markup node.</p>
*/
static public final PropertyKey INLINE_STYLE_KEY =
TYPE.registerKey("inlineStyle", String.class);

/**
* <p>Custom CSS class to the class attribute of the root markup node.</p>
*/
static public final PropertyKey STYLE_CLASS_KEY =
TYPE.registerKey("styleClass", String.class);

/**
* <p>Key used to identify the <code>visible</code> property that
* is of type <code>Boolean.class</code>.</p>
*/
static public final PropertyKey VISIBLE_KEY =
TYPE.registerKey("visible", Boolean.class, Boolean.TRUE);

/**
* <p>Key used to identify the <code>partialTriggers</code> property that
* is of type <code>String[].class</code>.</p>
*/
static public final PropertyKey PARTIAL_TRIGGERS_KEY =
TYPE.registerKey("partialTriggers", String[].class);

/**
* <p>Key used to identify the <code>tagSelectListener</code> property that
* is of type <code>MethodExpression.class</code>.</p>
*/
static public final PropertyKey TAG_SELECT_LISTENER_KEY =
TYPE.registerKey("tagSelectListener", MethodExpression.class);

/**
* <p>Key used to identity the <code>clientComponent</code> flag that
* is of type <code>Boolean.class</code>.</p>
*/
static public final PropertyKey CLIENT_COMPONENT_KEY =
TYPE.registerKey("clientComponent", Boolean.class);

/**
* <p>Key use to identity the <code>clientListeners</code> property
* that is a collection class of <code>ClientListenerSet.class</code>.</p>
*/
static public final PropertyKey CLIENT_LISTENERS_KEY =
TYPE.registerKey("clientListeners", ClientListenerSet.class,
PropertyKey.CAP_NOT_BOUND);

/**
* <p>Key used to identify the <code>clientAttributes</code> property this
* is a set of type <code>PropertyKey.CAP_NOT_BOUND</code>.</p>
*/
static public final PropertyKey CLIENT_ATTRIBUTES_KEY =
TYPE.registerKey("clientAttributes", Set.class,
PropertyKey.CAP_NOT_BOUND);

/**
* <p>Key used to identify the <code>tags</code> property that
* is of type <code>Map.class</code>.</p>
*/
static public final PropertyKey TAGS_KEY =
TYPE.registerKey("tags", Map.class);

/**
* <p>Key used to identify the <code>orderBy</code> property that
* is of type <code>String.class</code>.</p>
*/
static public final PropertyKey ORDER_BY_KEY =
TYPE.registerKey("orderBy", String.class);

/**
* <p>The constructor calls the super classes overloaded constructor passing
* the <code>rendererType</code>.
*/
public TagPane()
{
// Pass the renderer type to the super class.
super(RENDERER_TYPE);

// requires a client component by default
setBooleanProperty(CLIENT_COMPONENT_KEY, Boolean.TRUE);
}

/**
* @param newpartialTriggers array of render dependent client ids
*/
public void setPartialTriggers(String[] newpartialTriggers)
{
setProperty(PARTIAL_TRIGGERS_KEY, newpartialTriggers);
}

/**
* @return array of render dependent client ids
*/
public String[] getPartialTriggers()
{
return (String[]) getProperty(PARTIAL_TRIGGERS_KEY);
}

/**
* <p>Sets client listeners that provide specialized behaviors such as
* drag-and-drop.
* You can subscribe to any client event using the event type and method.
* For example, we could add a client listener for our custom client event
* <code>oracle.adfdemo.acme.js.event.TagSelectEvent</code>.
* </p>
* <pre>
*     &lt;acme:tagPane tags="#{bean.tags}"&gt;
*         &lt;clientListener type="tagSelect" method="onClickType" /&gt;
*     &lt;\acme:tagPane&gt;
* </pre>
*
* <p>In the fragment above, the method "onClickType" is a JavaScript function that
* has a single event parameter.</p>
*
* <per>
*    function onClickType(event) {
*       alter("You clicked on tag: " + event.getTag());
*    }
* </per>
*
* @param newclientListeners  client listener collection
*/
public void setClientListeners(ClientListenerSet newclientListeners)
{
setProperty(CLIENT_LISTENERS_KEY, newclientListeners);
}

/**
* <p>Returns client listeners that provide specialized behaviors such as
* drag-and-drop.</p>
*
* @return client listener set
*/
public ClientListenerSet getClientListeners()
{
return (ClientListenerSet) getProperty(CLIENT_LISTENERS_KEY);
}

/**
* <p>Sets attributes on the client component,
* <code>oracle.adfdemo.acme.js.event.AcmeTagPane.js</code> that can be used by
* <code>ClientListners</code>.  The state is actually managed by the
* component.  This collection is a <code>Set</code> of client attribute names
* that are also server component properties.
* <br/><br/>
* Client attributes must be set using the <code>setClientAttribute</code> JSP tag.
* Consider the following:
* <pre>
*     &lt;acme:tagPane targetFolder="somefolder"&gt;
*         &lt;clientListener type="tagSelect" method="onClickType" /&gt;
*         &lt;clientAttribute name="whoareyou" method="While E. Coyote" /&gt;
*     &lt;\acme:tagPane&gt;
* </pre>
*
* <p>In the fragment above, the method "onClickType" is a JavaScript function that
* has a single event parameter.</p>
*
* <per>
*    function onClickType(event) {
*       alter(event.getSource().getProperty("whoareyou")
*           + " clicked on tag: " + event.getTag());
*    }
* </per>
*
* @param newclientAttributes a set of client attribute names
*/
public void setClientAttributes(Set newclientAttributes)
{
setProperty(CLIENT_ATTRIBUTES_KEY, newclientAttributes);
}

/**
* <p><code>Set</code> of client component attribute names.  The state
* is also kept in the server side component's <code>attributes</code> Map.</p>
*
* @return colleciton of unique client component attribute names
*/
public Set getClientAttributes()
{
return (Set) getProperty(CLIENT_ATTRIBUTES_KEY);
}

/**
* <p>Sets the <code>newselectListener</code> method binding
* expression that expects a single parameter of type {@link
* oracle.adfdemo.acme.faces.event.TagSelectEvent}.
* This binding will be when the client-side
* <code>oracle.adfdemo.acme.js.event.AcmeTagSelectEvent.js</code>
* is queued from clicking on one of the <code>tag</code>s.</p>
*
* @param newselectListener invokes a {@link oracle.adfdemo.acme.faces.event.TagSelectEvent} method expression
*/
public void setTagSelectListener(MethodExpression newselectListener)
{
setProperty(TAG_SELECT_LISTENER_KEY, newselectListener);
}

/**
* <p>Returns a method binding expression that is fired when the client-side
* <code>oracle.adfdemo.acme.js.event.AcmeTagSelectEvent.js</code> is
* queued.</p>
*
* @return invokes a {@link oracle.adfdemo.acme.faces.event.TagSelectEvent}
* method expression
*/
public MethodExpression getTagSelectListener()
{
return (MethodExpression) getProperty(TAG_SELECT_LISTENER_KEY);
}

/**
* <p>Method for adding a listener implementing {@link
* oracle.adfdemo.acme.faces.event.TagSelectListener}.</p>
*
* @param listener tag select listener
*/
public void addTagSelectListener(TagSelectListener listener)
{
addFacesListener(listener);
}

/**
* <p>Removes a {@link oracle.adfdemo.acme.faces.event.TagSelectListener}
* listener.</p>
*
* @param listener tag select listener
*/
final public void removeSelectListener(TagSelectListener listener)
{
removeFacesListener(listener);
}

/**
* <p>Returns an array of attached {@link
* oracle.adfdemo.acme.faces.event.TagSelectListener} listeners.</p>
*
* @return  an array of attached select listeners.
*/
final public TagSelectListener[] getSelectListeners()
{
return (TagSelectListener[]) getFacesListeners(TagSelectListener.class);
}

/**
* <p>Exposes the <code>FacesBean.Type</code> for this class through a protected
* method.  This method is called but the <code>UIComponentBase</code> super
* class to setup the components <code>ValueMap</code> which is the container
* for the <code>attributes</code> colleciton.</p>
*
* @return <code>FolderSummary.TYPE</code> static property
*/
@Override
protected FacesBean.Type getBeanType()
{
return TYPE;
}

/**
* <p>
* </p>
*
* @param facesEvent faces event
* @throws AbortProcessingException exception during processing
*/
@Override
public void broadcast(FacesEvent facesEvent)
throws AbortProcessingException
{

// notify the bound TagSelectListener
if (facesEvent instanceof TagSelectEvent)
{
TagSelectEvent event = (TagSelectEvent) facesEvent;

// utility method found in UIXComponentBase for invoking method event
// expressions
broadcastToMethodExpression(event, getTagSelectListener());
}

super.broadcast(facesEvent);
}

/**
* <p>CSS value applied to the root component's style attribute.</p>
*
* @param newinlineStyle CSS custom style text
*/
public void setInlineStyle(String newinlineStyle)
{
// inlineStyle = newinlineStyle;
setProperty(INLINE_STYLE_KEY, newinlineStyle);
}

/**
* <p>CSS value applied to the root component's style attribute.</p>
*
* @return newinlineStyle CSS custom style text
*/
public String getInlineStyle()
{
// return inlineStyle;
return (String) getProperty(INLINE_STYLE_KEY);
}

/**
* <p>CSS style class added to the components class attribute.</p>
* @param newstyleClass custom class style attribute
*/
public void setStyleClass(String newstyleClass)
{
setProperty(STYLE_CLASS_KEY, newstyleClass);
}

/**
* <p>CSS style class added to the components class attribute.</p>
* @return newstyleClass custom class style attribute
*/
public String getStyleClass()
{
return (String) getProperty(STYLE_CLASS_KEY);
}

/**
* <p>Sets the visibility of the component.  The visibility
* is not the same as <code>rendered</code>.  The <code>visible</code>
* attribute effects the CSS style on the CSS root of the component.
* </p>
*
* @param newvisible <code>true</code> if the markup is not hidden in the
* browser
*/
public void setVisible(boolean newvisible)
{
setBooleanProperty(VISIBLE_KEY, newvisible);
}

/**
* <p>Returns the visibility of the component.  The visibility
* is not the same as <code>rendered</code>.  The <code>visible</code>
* attribute effects the CSS style on the CSS root of the component.
* </p>
*
* @return <code>true</code> if the markup is not hidden in the browser
*/
public boolean isVisible()
{
return getBooleanProperty(VISIBLE_KEY, Boolean.TRUE);
}

/**
* <p>This component's type, <code>oracle.adfdemo.acme.TagPane</code></p>
*/
static public final String COMPONENT_TYPE =
"oracle.adfdemo.acme.TagPane";

/**
* <p>Logical name given to the registered renderer for this component.</p>
*/
static public final String RENDERER_TYPE = "oracle.adfdemo.acme.TagPane";

/**
* <p>Sets a Map of weighted tags.  The key represents the tag name
* and the value a number.</p>
*
* @param newtags tags to be rendered
*/
public void setTags(Map<String, Number> newtags)
{
setProperty(TAGS_KEY, newtags);
}

/**
* <p>Gets a Map of weighted tags.  The key represents the tag name
* and the value a number.</p>
*
* @return newtags tags to be rendered
*/
public Map<String, Number> getTags()
{
return (Map<String, Number>) getProperty(TAGS_KEY);
}

/**
* <p>Sets the order that the tags are rendered.
* The valid enumerations are "alpha" and "weight".</p>
*
* @param neworderBy order by enumeration
*/
public void setOrderBy(String neworderBy)
{
setProperty(ORDER_BY_KEY, neworderBy);
}

/**
* <p>Gets the order that the tags are rendered.
* The valid enumerations are "alpha" and "weight".</p>
*
* @return order by enumeration
*/
public String getOrderBy()
{
return (String) getProperty(ORDER_BY_KEY);
}

static {
// register the new TYPE by family and rendererType
TYPE.lockAndRegister(UIXObject.COMPONENT_FAMILY, RENDERER_TYPE);
}

}

F.4.4 レンダラ・クラスのコード例

レンダラ・クラスはコンポーネントの表示を制御します。例F-10に、カスタムTagPaneコンポーネントのレンダラ・クラスを示します。

例F-10 レンダラ・クラス

package oracle.adfdemo.acme.faces.render;

import java.io.IOException;

import java.text.MessageFormat;

import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.logging.Logger;

import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.context.ResponseWriter;

import oracle.adf.view.rich.render.ClientComponent;
import oracle.adf.view.rich.render.ClientEvent;
import oracle.adf.view.rich.render.ClientMetadata;
import oracle.adf.view.rich.render.RichRenderer;

import oracle.adfdemo.acme.faces.component.TagPane;
import oracle.adfdemo.acme.faces.event.TagSelectEvent;

import org.apache.myfaces.trinidad.bean.FacesBean;
import org.apache.myfaces.trinidad.bean.PropertyKey;
import org.apache.myfaces.trinidad.context.RenderingContext;

/**
* <p>Renderer for {@link oracle.adfdemo.acme.faces.component.TagPane}
* component.</p>
*/
public class TagPaneRenderer
extends RichRenderer
{

/**
* <p>Java Logger instance.</p>
*/
private static final Logger _LOG =
Logger.getLogger(TagPaneRenderer.class.getName());

/**
* <p>No-args constructor passes the <code>TagPane.TYPE</code> to the
* base class.  The type bean is used to extend the component properties
* meta-data by invoking <code>findTypeConstants</code>.</p>
*/
public TagPaneRenderer()
{
super(TagPane.TYPE);
}

/**
* <p>Invoked by the base class, this is the hook to perform the markup
* rendering for the {@link oracle.adfdemo.acme.faces.component.TagPane}.
* </p>
*
* @param context faces context
* @param arc rendering context
* @param component {@link oracle.adfdemo.acme.faces.component.TagPane}
* @param client server-side state for the client component
* @param bean state holder for the TagPane component
* @throws IOException error rendering markup
*/
protected void encodeAll(FacesContext context, RenderingContext arc,
UIComponent component, ClientComponent client,
FacesBean bean)
throws IOException
{

//defines this attribute to be pushed to the client component
//this attribute is not secured so its value will prorogate
//to the server when modified from the client
client.addProperty(_ORDER_BY_KEY, bean.getProperty(_ORDER_BY_KEY));

ResponseWriter writer = context.getResponseWriter();

writer.startElement("div", component);

// write the client id for the component
renderId(context, component);

// add the component root style attribute; factors in the inline and class
// style component properties
renderRootStyleAttributes(context, arc, client, bean,
getDefaultStyleClass(context, arc, bean));

writer.startElement("span", component);

// writes the style class attribute using a skinning key;  the key
// will need to be normalized and compressed
renderStyleClass(context, arc, TagPaneRenderer._TAG_CONTENT_STYLE_KEY);

_renderTags(context, component, arc, bean);

writer.endElement("span");

writer.endElement("div");

}

/**
* <p>Renders the <code>tags</code> as anchored links ordered by
* tag or tag weight.  The tag weight is converted into a font that is
* evenly distributed between the <code>MAXIMUM_FONT_SIZE</code> and the
* <code>MINIMUM_FONT_SIZE</code> based on the tag's weight.</p>
*
* @param context faces context
* @param component {@link oracle.adfdemo.acme.faces.component.TagPane}
* @param arc rendering context
* @param bean state holder for {@link oracle.adfdemo.acme.faces.component.TagPane}
* @throws IOException error during rendering tags
*/
private void _renderTags(FacesContext context, UIComponent component,
RenderingContext arc, FacesBean bean)
throws IOException
{
Map<String, Number> tags = _getTags(bean);
if (tags.isEmpty())
{
return; // no work to do
}

// Calculates a font size for each tag.  The font size will be based on the
// weight of the tag and the size proportional to the range of font sizes.
Map<String, Integer> fontSizes =
_computeFontSize(tags, _getMaximumFontSize(arc),
_getMinimumFontSize(arc));

// create a list from the map's entry set.
List<Map.Entry<String, Number>> entries =
new ArrayList<Map.Entry<String, Number>>(tags.entrySet());

//collocation sequence determined by the orderBy property
Collections.sort(entries, _getComparator(bean));

ResponseWriter writer = context.getResponseWriter();

//for each tag, write an anchored tag.  The font size is explicitly set
//using a inline style.
for (Map.Entry<String, Number> entry: entries)
{
// start a hyperlink for each tag
writer.startElement("a", component);

// render the class style for the link
renderStyleClass(context, arc, TagPaneRenderer._TAG_STYLE_KEY);

writer.writeAttribute("href", "#", null);

//font size is calculated from the _computeFontSize call above
//the _getFontSizeStyle substitutes the font size parameter into the style
String style = _getFontSizeStyle(fontSizes.get(entry.getKey()));

//set the font size using an inline style
writer.writeAttribute("style", style, null);

//insert the tag weight into the title string
String title = _getTitleStyle(entry.getValue().doubleValue(), arc);

// write the title string attribute to the hyperlink
writer.writeAttribute("title", title, null);

//write body of the tag; the description of the link will
//be the name of the tag
writer.writeText(entry.getKey(), null);

//end the hyperlink
writer.endElement("a");

// write a small spacer between anchored tags
renderSpacer(context, arc, "2px", "2px");
}

}

/**
* <p>Substitutes the tag's <code>weight</code> into the pattern defined by
* the <code>AcmeTagPane_tag_title</code> resource key.</p>
* @param weight tag weight
* @param arc rendering context
* @return formatted title attribute for the anchored tag
*/
private String _getTitleStyle(double weight, RenderingContext arc)
{
// title attribute template from the resource bundle
MessageFormat titleFormat =
new MessageFormat(arc.getTranslatedString("AcmeTagPane_tag_title"));

return titleFormat.format(new Object[]
{ weight });
}

/**
* <p>Substitutes the <code>size</code> into the style pattern defined by
* the <code>_FONT_INLINESTYLE_FORMAT</code>.</p>
* @param size font size
* @return inline style defining the font size
*/
private String _getFontSizeStyle(int size)
{
return _FONT_INLINESTYLE_FORMAT.format(new Object[]
{ size });
}

/**
* <p>Returns the default constructor for our client-side component,
* <code>oracle.adfdemo.acme.js.component.AcmeTagPane.js</code></p>
*
* @return client-side component name
*/
protected String getClientConstructor()
{
return _CLIENT_COMPONENT;
}

/**
* <p>Retrieves a hint on if and when a component must be sent down to the
* client.</p>
*
* @return the client component type
*/
@Override
protected ClientComponent.Type getDefaultClientComponentType()
{
return ClientComponent.Type.CREATE_WITH_REQUIRED_ATTRS;
}

/**
* <p>Retrieves the style class to apply to the root element,
* <code>_ROOT_STYLE_KEY</code>.</p>
*
* @param context the FacesContext
* @param arc the RenderingContext
* @param bean the FacesBean of the component to render
* @return the root element's style class
*/
@Override
protected String getDefaultStyleClass(FacesContext context,
RenderingContext arc,
FacesBean bean)
{
return TagPaneRenderer._ROOT_STYLE_KEY;
}

/**
* <p>Returns the weighted tag map from the component's state holder
* properties bag using the <code>_TAGS_KEY</code>.</p>
*
* @param bean state holder for {@link
* oracle.adfdemo.acme.faces.component.TagPane}
* @return map of weighted tags
*/
private Map<String, Number> _getTags(FacesBean bean)
{
Map<String, Number> tags =
(Map<String, Number>) bean.getProperty(_TAGS_KEY);
if (tags == null)
{
tags = Collections.emptyMap();
}

return tags;
}

/**
* <p>Looks at the {@link oracle.adfdemo.acme.faces.component.TagPane}'s
* <code>orderBy</code> property and returns a corresponding
* <code>Comparator</code>.  The default is to sort descending by weight.
* If <code>orderBy</code> equals "alpha", the order is sorted ascending
* by the tag.</p>
*
* @param bean state holder for the {@link
*oracle.adfdemo.acme.faces.component.TagPane}
* @return comparator to sort the <code>tags</code>
*/
private Comparator<Map.Entry<String, Number>> _getComparator(FacesBean bean)
{
String orderBy = (String) bean.getProperty(_ORDER_BY_KEY);
if (orderBy != null && orderBy.equalsIgnoreCase("alpha"))
{
return _sortAscByTag;
}

return this._sortDescByWeight;
}

/**
* <p>This method is called from the <code>RichRenderer</code>'s implementation
* of the <code>decode</code> method.  Within this method we will check to see
* if there are any custom client events,
* <code>oracle.adfdemo.acme.js.event.AcmeTagSelectEvent</code>.
* If a client event is present, we will queue a corresponding server-side faces
* event, {@link oracle.adfdemo.acme.faces.event.TagSelectEvent}.  This event is
* targeted for the apply request values phase so the response will be completed
*  if a client event is found.
* </p>
*
* @param facesContext faces context
* @param component {@link oracle.adfdemo.acme.faces.component.TagPane}
* component
* @param clientId unique component identifier
*/
@Override
public void decodeInternal(FacesContext facesContext,
UIComponent component, String clientId)
{

super.decodeInternal(facesContext, component, clientId);

// look for a client event of type "tagSelect"
ClientEvent clientEvent =
this.getClientEvent(facesContext, clientId, _CLIENT_SELECT_EVENT_TYPE);
if (clientEvent != null)
{
// extract the tag from the client event
String tag =
(String) clientEvent.getParameters().get(TagPaneRenderer._CLIENT_SELECT_EVENT_TAG_PARAM);

_LOG.finest("Found SelectEvent with tag of " +
(tag != null? tag: "null"));

// Instantiate a corresponding server side event
TagSelectEvent event = new TagSelectEvent(component, tag);

// push the event up to the view root
event.queue();

// this event is an assumed immediate meaning that we will stop the
//lifecycle after
// the apply request values phase and short-circuit to render response.
// there doesn't seem to be a good reason for this component to participate
// in the process validations phase.  that is why we are going to jump to
// the render response phase.
facesContext.renderResponse();
}

}

/**
* <p>This method is called from the base constructor.  The callback gives
* opportunity to add client characteristics to the server-side component
* properties that become  client-side component properties.</p>
*
* @param type <code>FacesBean.TYPE</code>
* @param metadata client specific extension to the <code>FacesBean.Type</code>
*/
@Override
protected void findTypeConstants(FacesBean.Type type,
ClientMetadata metadata)
{
super.findTypeConstants(type, metadata);

_TAGS_KEY = type.findKey("tags");
metadata.addSecureProperty(_TAGS_KEY);

_ORDER_BY_KEY = type.findKey("orderBy");

}

/**
* <p>Calculates a proportional font weight for each of the <code>tags</code>
* based on the weight of the tag entry.  The weight of each entry is
* determined by the value of the <code>Map.Entry</code>.  The computed font
* weight for each item will be between the <code>maxFontSize</code> and
* <code>minFontSize</code>. Tags that have the same weight will be
* displayed using the same font.</p>
*
* @param tags weighted tags
* @param maxFontSize maximum font weight
* @param minFontSize minimum font weight
* @return Lookup map that contains the tag name as the key and the value
* is the computed font size.
*/
private Map<String, Integer> _computeFontSize(Map<String, Number> tags,
double maxFontSize,
double minFontSize)
{

double maxWeight = 0; // max weight
double minWeight = 0; // min weight

// find the min and max in the tag weight set
for (Map.Entry<String, Number> entry: tags.entrySet())
{
// first time set the min to the first entry
if (minWeight == 0)
{
minWeight = entry.getValue().doubleValue();
}

maxWeight = Math.max(maxWeight, entry.getValue().doubleValue());
minWeight = Math.min(minWeight, entry.getValue().doubleValue());
}

//target map where the key is the tag and the value the font size
Map<String, Integer> fontSizeMap = new TreeMap<String, Integer>();

// for each entry, calculate a font size adding to the target
// map by tag name
for (Map.Entry<String, Number> entry: tags.entrySet())
{

double weight = entry.getValue().doubleValue();
double percentTotaWeight =
(weight - (minWeight - 1d)) / ((maxWeight + 1d));
double fontSize =
(percentTotaWeight * ((maxFontSize + 1d) - minFontSize)) +
(minFontSize - 1d);

//add to the xref map
fontSizeMap.put(entry.getKey(), (int) Math.round(fontSize));

}

return fontSizeMap;
}

/**
* <p>Returns the minimum font size that will be used as the lower limit when
* assigning each unique tag weight a font size.  The value will be pulled from
* the skinning key "acme|tagPane-tr-minimum-font-size".  If the
* key is not found or the value is not an integer, the
* <code>_DEFAULT_MINIMUM_FONT_SIZE</code> will be used.</p>
*
* @param arc Rendering context
* @return max font size assigned to a tag
*/
private int _getMinimumFontSize(RenderingContext arc)
{
int size = _DEFAULT_MINIMUM_FONT_SIZE;
String fontSize = (String)
arc.getSkin().getProperty(_MINIMUM_FONT_SIZE_PROPERTY);
if (fontSize != null)
{
try
{
size = Integer.parseInt(fontSize);
}
catch (NumberFormatException e)
{
_LOG.warning("The \"" + _MINIMUM_FONT_SIZE_PROPERTY +
"\" skin property " +
"is not defined or is not a valid integer. " +
"Using default minimum font size: " + size);
}
}
return size;
}

/**
* <p>Returns the maximum font size that will be used as the upper limit when
* assigning each unique tag weight a font size.  The value will be pulled from
* the skinning key "acme|tagPane-tr-maximum-font-size".  If the
* key is not found or the value is not an integer, the
* <code>_DEFAULT_MAXIMUM_FONT_SIZE</code> will be used.</p>
*
* @param arc Rendering context
* @return max font size assigned to a tag
*/
private int _getMaximumFontSize(RenderingContext arc)
{
int size = _DEFAULT_MAXIMUM_FONT_SIZE;
String fontSize = (String)
arc.getSkin().getProperty(_MAXIMUM_FONT_SIZE_PROPERTY);
if (fontSize != null)
{
try
{
size = Integer.parseInt(fontSize);
}
catch (NumberFormatException e)
{
_LOG.warning("The \"" + _MAXIMUM_FONT_SIZE_PROPERTY +
"\" skin property " +
"is not defined or is not a valid integer. " +
"Using default maximum font size: " + size);
}
}
return size;
}

/**
* <p>Sorts the <code>tags.entrySet</code> by map value in descending order
* and by map key in ascending.
* </p>
*/
private Comparator<Map.Entry<String, Number>> _sortDescByWeight =
new Comparator<Map.Entry<String, Number>>()
{
public int compare(Map.Entry<String, Number> o1,
Map.Entry<String, Number> o2)
{
double value1 = o1.getValue().doubleValue();
double value2 = o2.getValue().doubleValue();
if (value1 > value2)
{
return -1;
}
else if (value1 < value2)
{
return 1;
}
else
{
// sort by value DESC, key ASC
return o1.getKey().compareTo(o2.getKey());
}
}
};

/**
* <p>Sorts the <code>tags.entrySet</code> by the key in ascending order.
* </p>
*/
private Comparator<Map.Entry<String, Number>> _sortAscByTag =
new Comparator<Map.Entry<String, Number>>()
{
public int compare(Map.Entry<String, Number> o1,
Map.Entry<String, Number> o2)
{
return o1.getKey().compareTo(o2.getKey());
}
};

/**
* <p>Default maximum font size for rendered tags (20).</p>
*/
private static final int _DEFAULT_MAXIMUM_FONT_SIZE = 20;

/**
* <p>Minimum font size for rendered tags (2).</p>
*/
private static final int _DEFAULT_MINIMUM_FONT_SIZE = 8;

/**
* <p>The client event type for
* <code>oracle.adfdemo.acme.js.event.AcmeTagSelectEvent.js</code>.
* This constant will correspond to <code>AcmeTagSelectEvent.SELECT_EVENT_
* TYPE</code>.</p>
*/
private static final String _CLIENT_SELECT_EVENT_TYPE = "tagSelect";

/**
* <p>The tag parameter name on the
* <code>oracle.asfdemo.acme.js.event.AcmeTagSelectEvent.js</code>.
* The tag reports one of the weighted tags the user has click on.  The
* <code>AddMarshalledProperties</code> function is where this parameter is
* prepared to be sent to the server where it is intercepted by the
* <code>oracle.adfinternal.view.faces.context.RichPhaseListener</code> and
* unmarshaled into a <code>oracle.adf.view.rich.render.ClientEvent</code>.
* </p>
*
*/
private static final String _CLIENT_SELECT_EVENT_TAG_PARAM = "tag";

/**
* <p>The root skinning key <code>acme|tagPane</code>.</p>
*/
private static final String _ROOT_STYLE_KEY = "acme|tagPane";

/**
* <p>The maximum font size skinning key
* <code>acme|tagPane-tr-maximum-font-size</code>.</p>
*/
private static final String _MAXIMUM_FONT_SIZE_PROPERTY =
_ROOT_STYLE_KEY + "-tr-maximum-font-size";

/**
* <p>The minimum font size skinning key
* <code>acme|tagPane-tr-minimum-font-size</code>.</p>
*/
private static final String _MINIMUM_FONT_SIZE_PROPERTY =
_ROOT_STYLE_KEY + "-tr-minimum-font-size";

/**
* <p>TagPane content skinning key <code>acme|tagPane::content</code>.</p>
*/
private static final String _TAG_CONTENT_STYLE_KEY =
"acme|tagPane::content";

/**
* <p>Tag link skinning key <code>acme|tagPane::tag</code>.</p>
*/
private static final String _TAG_STYLE_KEY = "acme|tagPane::tag";

/**
* <p>The <code>tags</code> property key from the <code>TagPane.TYPE</code>.</p>
*/
private static PropertyKey _TAGS_KEY = null;

/**
* <p>The <code>orderBy</code> property key from the
* <code>TagPane.TYPE</code>.</p>
*/
private static PropertyKey _ORDER_BY_KEY = null;

/**
* <p>The Corresponding JavaScript component,
* <code>oracle.adfdemo.acme.js.component.AcmeTagPane.js</code>.</p>
*/
private static final String _CLIENT_COMPONENT = "AcmeTagPane";

/**
* <p>Pattern used to build the inline style that specifies the font
* size for a tag.  Pixels units are assumed.</p>
*/
private static final MessageFormat _FONT_INLINESTYLE_FORMAT =
new MessageFormat("font-size:{0}px;");

}

G ADF Facesのトラブルシューティング

この付録では、ADF FacesフレームワークとADF Facesコンポーネントを使用してアプリケーション・ユーザー・インタフェースを設計する際に生じる可能性のある一般的な問題について説明し、その解決方法を解説しています。

この付録には次の項が含まれます:

- 第G.1項「ADF Facesのトラブルシューティングの概要」

- 第G.2項「ADFアプリケーションのビュー・レイヤーのトラブルシューティングの開始」

- 第G.3項「一般的な問題の解決」

- 第G.4項「My Oracle Supportを使用したその他のトラブルシューティング情報」

表示される可能性のあるエラー・メッセージの詳細は、この章およびエラー・メッセージを参照してください。

G.1 ADF Facesのトラブルシューティングの概要

この項では、この章の情報を使用する際のガイドラインとプロセスを示します。次のガイドラインおよびプロセスに従うことで、作業の焦点を問題解決に絞り、問題解決までの時間を短縮できます。

ガイドライン

この章の説明を使用する際に、次のベスト・プラクティスに留意してください。

- この章の解決策を実行した後すぐに、このトラブルシューティング情報を利用するきっかけとなった失敗したタスクを再試行します。再試行してもタスクが失敗する場合、この章に記載されている他の解決策を実行し、再度失敗したタスクを実行します。このプロセスを問題が解決するまで繰り返します。

- 実行した解決策、確認された現象およびトラブルシューティング中に収集したデータを記録しておきます。この章の情報を使用しても問題が解決されずサービス・リクエストを記録することになった場合、これらの情報があると迅速な問題解決につながります。

プロセス

この章の情報を利用する場合は、表G-1に概要を示したプロセスに従ってください。特定の項の情報でも問題を解決できない場合は、このプロセスの次のステップに進んでください。

表G-1 この章の情報を利用するプロセス

手順

使用する項

目的

1

第G.2項

ADFアプリケーションのビュー・レイヤーのトラブルシューティングを開始します。この項に示す手順によって、幅広い問題に迅速に対応できます。

2

第G.3項

ADFアプリケーションのビュー・レイヤーに関する問題別トラブルシューティングの手順を実行します。この項では、次の内容について説明します。

- 問題の考えられる原因

- それぞれの考えられる原因に対応する解決策

3

第G.4項

My Oracle Supportを使用してその他のトラブルシューティング情報を取得します。My Oracle Support Webサイトから、ナレッジ・ベース記事、コミュニティ・フォーラム、ディスカッション・ページへのリンクを含むいくつかの有益なトラブルシューティング・リソースにアクセスできます。

4

第G.4項

この章とMy Oracle Supportの情報では問題を解決できない場合に、サービス・リクエストを記録します。サービス・リクエストを記録するには、https://support.oracle.comのMy Oracle Supportを使用できます。

G.2 ADFアプリケーションのビュー・レイヤーのトラブルシューティングの開始

Oracle ADFの組込みエラー・メッセージによって、アプリケーションのどのレイヤーが問題の原因となっているかを判別できます。エラー・メッセージはトラブルシューティングの開始点であり、Web上で特定のエラー・メッセージを調べることもできます。ADFビジネス・コンポーネントのモデル・レイヤーから発生するエラー・メッセージにはJBO接頭辞が付きます。これらは、ADF Facesビュー・レイヤーも含めて他のすべてのADFレイヤー・コンポーネントと同様に、Javaエラー・メッセージとして、Oracleパッケージとともに表示されます。

レイヤーを特定できたら、診断ツールを実行することもできます。また、ログ・ファイルを表示して記録されたエラーがないか確認することもできます。エラー・メッセージは「エラー・メッセージ」で検索できます。また、Oracle Technology Networkの技術フォーラムで、エラー・メッセージ関連のディスカッションを検索することもできます。Oracle ADFのコンポーネント・レイヤーには、それぞれ専用のフォーラムが設定されています。Oracle Technology Network(https://forums.oracle.com/forums/main.jspa?categoryID=84)の開発ツール・リストの下にあるJDeveloperおよびOracle ADFのフォーラム・ホームページにアクセスしてください。

トラブルシューティングを開始する前に、エラーを簡単に検索できるようにADFアプリケーションを構成しておく必要があります。表G-2では、トラブルシューティング用にADFアプリケーションのビュー・レイヤーを構成する際の設定の概要を示しています。

表G-2 ADF Facesトラブルシューティング最適化の構成オプション

構成に関する推奨事項

説明

デバッグ出力を有効化します。

デバッグ出力を有効化するには、trinidad-config.xmlファイルで次のように設定します。

<adf-faces-config xmlns=
"http://xmlns.oracle.com/adf/view/faces/config">
<debug-output>true</debug-output>
<skin-family>oracle</skin-family>
</adf-faces-config>

WebブラウザでのHTMLマークアップの可読性を次のように改善します。

- 出力の行折返しとインデントを行います。

- 正しく指定されていない要素やその他の一般的なHTMLエラー(指定の正しくない要素など)を検出し、強調表示します。

- HTMLの各ブロックを生成したADF Facesコンポーネントの識別に役立つコメントをブラウザ・ページに追加します。

コンテンツ圧縮を無効化します。

コンテンツ圧縮を無効化するには、web.xmlファイルで次のように設定します。

<context-param>
<param-name>
org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION
</param-name>
<param-value>true</param-value>
</context-param>

元の圧縮されていないスタイルを強制的に使用して、可読性を改善します。

コンテンツ圧縮を無効にしないかぎり、CSSスタイル名とスタイルは圧縮されて表示されるため、読み取りにくいことがあります。

JavaScript圧縮を無効化します。

JavaScript圧縮を無効化するには、web.xmlファイルで次のように設定します。

<context-param>
<param-name>
org.apache.myfaces.trinidad.DEBUG_JAVA_SCRIPT
</param-name>
<param-value>true</param-value>
</context-param>

通常は曖昧化されているJavaScriptをソースとして圧縮されない状態で表示できるようにします。

クライアント・サイドのアサートを有効化します。

クライアント・サイドのアサートを有効化するには、web.xmlファイルで次のように設定します。

<context-param>
<param-name>
oracle.adf.view.rich.ASSERT_ENABLED
</param-name>
<param-value>true</param-value>
</context-param>

予期しない状態の警告をブラウザ・コンソールに出力できるようにします。

クライアント・サイドのロギングを有効化します。

クライアント・サイドのロギングを有効化するには、web.xmlファイルで次のように設定します。

<context-param>
<param-name>
oracle.adf.view.rich.ASSERT_ENABLED
</param-name>
<param-value>true</param-value>
</context-param>

ログ・メッセージをブラウザ・コンソールに出力できるようにします。

クライアント・サイドのロギングを有効にしないかぎり、ログ・メッセージはクライアントに報告されません。

より詳細なサーバー・サイドのロギングを有効化します。

より詳細なサーバー・サイドのロギングを有効化し、アプリケーション・サーバーをシャットダウンし、次の設定をlogging.xmlファイルに入力して、サーバーを再起動します。

<logger name="oracle.adf.faces” level=”CONFIG"/>

または

次のWLSTコマンドを使用します。

setLogLevel(logger="oracle.adf” level=”CONFIG”, addLogger=1)

または

Oracle Enterprise Manager Fusion Middleware Controlで、構成ページを使用してoracle.adf、oracle.adfinternalおよびoracle.jboをレベルCONFIGに設定します。

より詳細なログ・メッセージをブラウザ・コンソールに出力できるようにします。

サーバー・サイドのロギングをログ・レベルCONFIGまたはそれ以上で構成しないと、有益な診断メッセージは報告されないことがあります。

使用可能なログ・レベルの設定は、SEVERE、WARNING、INFO、CONFIG、FINE、FINER、FINEST、ALLです。CONFIGレベル以上の設定をお薦めします。デフォルトはSEVEREです。

HTTPキャッシュ・ヘッダーを無効化します。

HTTPキャッシュ・ヘッダーを無効化するには、web.xmlファイルで次のように設定します。

<context-param>
<param-name>
org.apache.myfaces.trinidad.resource.DEBUG
</param-name>
<param-value>true</param-value>
</context-param>

パッチ適用済リソースのリロードを強制します。

HTTPキャッシュ・ヘッダーが無効化されないかぎり、ブラウザはリソースをキャッシュして、リソースへの高速アクセスを可能にします。

設定を変更した後で、ブラウザのキャッシュをクリアしてリソースのリロードを強制します。

G.3 一般的な問題の解決

この項では、一般的な障害と解決策について説明します。

G.3.1 アプリケーションで予期しない白い背景が表示される

ADFアプリケーションは、デフォルト・スキンとして簡単な、または最小限のルック・アンド・フィールを表示します。デフォルト・スキンの背景は白で表示されます。

原因

スキンのJARファイルがすべてのアプリケーションに対して正しくデプロイされているとはかぎりません。

解決策

この問題を解決するには、次のようにします。

1. スキンのJARファイルがすべてのアプリケーションに対してデプロイされているか確認してください。

2. 『Oracle ADFスキン・エディタによるADFスキンの作成』のWebアプリケーションへのADFスキンの適用に関する項の説明に従って、プロファイル・オプションでのスキンのスペルが間違っていないことを確認してください。

G.3.2 アプリケーションに予想されるイメージがない

スキン・アプリケーションは、イメージ・ファイルを含むJARファイルとしてパッケージ化されている必要があります。

原因

スキンのJARファイルが正しくパッケージ化されていません。

解決策

この問題を解決するには、次のようにします。

1. スキン・アプリケーションの作成時に正しいターゲット・アプリケーションのバージョンが指定されたか確認してください。

2. 『ADFスキン・エディタによるADFスキンの作成』のADFスキンのADFライブラリJARへのパッケージ化に関する項の説明に従って、スキン・アプリケーションを再パッケージ化し、JARファイルを新規に作成してください。

G.3.3 ADFスキンが適切にレンダリングしない

作成したADFスキンで定義されたスタイル・プロパティでは、ブラウザで予想どおりにレンダリングされません。

原因

すべてのADFスキン・セレクタがカスタマイズできるとはかぎりません。有効でないセレクタをカスタマイズすると、アプリケーションで予期しない動作や一貫性のない動作が発生する場合があります。

解決策

この問題を解決するには、次のようにします。

1. コンテキスト初期化パラメータの設定をweb.xmlファイルで確認します。CHECK_FILE_MODIFICATIONパラメータをtrueに設定した場合、ADFスキンに加えたすべての変更がすぐに表示されるわけではありません。アイコンとADFスキンのプロパティに加えた変更を表示するには、Webアプリケーションを再起動する必要があります。

2. 『ADFスキン・エディタによるADFスキンの作成』のADFスキンでの変更のテストに関する項の説明に従って、有効なADFスキン・セレクタ、擬似要素および擬似クラスのみをカスタマイズしたことを確認してください。

G.3.4 データ視覚化コンポーネントが予想どおりに表示できない

様々なADF DVTコンポーネントはFlashに依存して正しく表示できるため、プラットフォームやブラウザでFlashがサポートされていないと、アプリケーションでDVTコンポーネントの視覚的な要素を表示できない場合があります。

原因

すべてのプラットフォームとブラウザでFlashがサポートされているわけではありません。このため、アプリケーションは使用可能な最善のフォールバックに強制的にダウングレードされます。プラットフォームがサポートされていない場合、アプリケーションでは、adf-config.xmlファイルのflash-player-usageの設定に従って表示されます。

解決策

この問題を解決するには、ブラウザに使用可能な最新のFlashバージョンを再インストールしてください。

G.3.5 高可用性アプリケーションでNotSerializableExceptionが表示される

クラスタ環境で実行するアプリケーションを設計している場合は、1つのリクエストよりも長い寿命のマネージドBeanがすべてシリアライズ可能であることを確認する必要があります。

原因

Fusion Webアプリケーションをクラスタ環境で実行する場合は、アプリケーションの状態の一部がシリアル化され、各リクエストの終わりに別のサーバーまたはデータ・ストアにコピーされるため、クラスタ内の他のサーバーがこの状態を利用できるようになります。具体的には、セッション・スコープ、ページ・フロー・スコープおよびビュー・スコープに格納されているBeanは、シリアライズ可能である必要があります(これらのBeanはjava.io.Serializableインタフェースを実装しています)。

解決策

この問題を解決するには、次のようにします。

1. サーバーのチェックを有効にして、セッション属性でシリアライズ不能な状態コンテンツが検出されないようにします。このチェックは、デフォルトでは、実行時のオーバーヘッドを軽減するために無効になっています。シリアライズ・チェックは、Javaサーバーのシステム・プロパティorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATIONによってサポートされます。次に示すJavaシステム・プロパティは、アプリケーション・サーバーの起動時に指定する必要があります。

2. 高可用性をテストするには、まず次のシステム・プロパティを使用してアプリケーション・サーバーを起動し、セッションおよびJSFの状態がシリアライズ可能であることを確認します。
-Dorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION=session,tree

3. 次のようにbeansオプションを追加して、該当するマップのシリアライズ可能なオブジェクトのシリアライズされたコンテンツがリクエスト中に変更された場合に、そのオブジェクトがダーティとマークされたことをチェックします。
-Dorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION=session,tree,beans

4. JSFの状態がシリアライズ不能であることが検出された場合は、次のシステム・プロパティを使用してアプリケーション・サーバーを再起動し、コンポーネントとプロパティのフラグを有効にしてからテストを再実行します。
-Dorg.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION=all

G.3.6 すべてのWebブラウザで問題を再現できない

アプリケーションをMicrosoft Windows Internet Explorerで実行して問題を検証していますが、Mozilla Firefoxでアプリケーションを実行するときに、問題が再現されません。このような問題は視覚的な性質ものであることが多く、たとえば、Webページで領域を区切る余分の空白が意図せずに表示されることがあります。

原因

設定はブラウザ間で異なるため、アプリケーションの表示方法に違いが生じることがあります。

解決策

この問題を解決するには、次のようにします。

1. ブラウザのセキュリティ設定をチェックして、構成が間違っていないことを確認してください。たとえば、JavaScript、XML HTTPまたはポップアップを無効にしていないことを確認してください。

2. Internet Explorerが互換性モードで実行していないことを確認してください。「現在の互換性の設定はサポートされていません」というダイアログが表示された場合は、ブラウザの「ツール」メニューで互換性モードを無効にしてください。

3. JavaScriptエラーが表示される場合は、ブラウザの不具合の可能性が高いです。ただし、ADF Faces固有のJavaScriptエラーであることも考えられます。

G.3.7 アプリケーションにコンテンツがない

アプリケーション・ページで、コンテンツが予想されている領域が空で表示されることがあります。

原因

この原因は、アプリケーションの設計によって異なります。たとえば、アプリケーションで実施している権限により、アプリケーションでのコンテンツの表示が無意識に妨害されていることがあります。または、ポートレットを使用しているとき、ポートレット・サーバーがダウンしている可能性もあります。

解決策

この問題を解決するには、次のようにします。

1. 例外がないかログ・ファイルをチェックしてください。ログ・レベルをSEVEREよりも下位のレベルに変更することをお薦めします。Oracle Fusion Middlewareのロギング機能の詳細は、『Oracle Fusion Middlewareの管理』の「ログ・ファイルと診断データの管理」の章を参照してください。

2. Oracle WebLogic Server管理コンソール・オンライン・ヘルプのサーバー・パフォーマンスの監視に関する項の説明に従って、スタック・スレッドを検索してください。スタック・スレッドが見つかった場合は、スレッド・スタック・ダンプを調べてください。

3. 部分ページ・レンダリング(PPR)でHTTP 403または404エラーが見られる場合は、不具合の可能性が高いです。

G.3.8 ブラウザでADF_Faces-60098エラーが表示される

アプリケーションから予期しない場所でランタイム例外が返され、これは処理されません。

原因

ADF Facesはライフサイクルのあるフェーズで未処理の例外を受け取り、リクエスト処理を中止します。

解決策

この問題を解決するには、次のようにします。

1. これは、アプリケーションのロジック・エラーの可能性が高いです。

2. サーバー・ロードとアプリケーションが不適切な状態でないことを確認してください。

G.3.9 ブラウザでHTTP 404または500のエラーが表示される

アプリケーションは予期されるページに移動せず、HTTP 404のファイルが見つからないエラー、またはHTTP 500の内部サーバー・エラーが表示されます。

原因

この原因は、アプリケーション・サーバーまでトレースできる場合があります。

解決策

この問題を解決するには、次のようにします。

1. Oracle WebLogic Server管理コンソール・オンライン・ヘルプでサーバー・パフォーマンスの監視に関する項およびサーバーの構成のオーバーロードに関する項の説明に従って、アプリケーション・サーバーが実行中であり、アプリケーションが不適切な状態ではないことを確認してください。

2. ハング・スレッドがないかチェックします。

G.3.10 ブラウザでページ間の移動ができない

アプリケーションでは、予期しているターゲットWebページへ移動して、そのページを開くことができません。

原因

この原因はアプリケーションの設計によって異なったり、アプリケーション・サーバーまでトレースできる場合があります。

解決策

この問題を解決するには、次のようにします。

1. 第G.3.8項「ブラウザでADF_Faces-60098エラーが表示される」の説明に従って、ADF Facesのライフサイクル・スレッドに固有の未処理例外がないかチェックしてください。

2. 第G.3.9項「ブラウザでHTTP 404または500のエラーが表示される」の説明に従って、HTTP 404または505のエラーを検索してください。

G.4 My Oracle Supportを使用したその他のトラブルシューティング情報

Oracle Fusion Middlewareの問題の解決にMy Oracle Support (以前のMetaLink)を使用できます。My Oracle Supportには、次のような有用なトラブルシューティング・リソースが含まれています。

- ナレッジ・ベース記事

- コミュニティ・フォーラムとディスカッション

- パッチとアップグレード

- 動作保証情報

注意:

My Oracle Supportを使用してサービス・リクエストを記録することもできます。

My Oracle Supportにはhttps://support.oracle.comからアクセスできます。

オラクル社の法律上の注意点について

コピーライトについて

Copyright © 1994-2014, Oracle and/or its affiliates.All rights reserved.

商標と登録商標について

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

制限付権利

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション（人的傷害を発生させる可能性があるアプリケーションを含む）への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性（redundancy）、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

ドラフトのアルファ版およびベータ版ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。オラクル社およびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。