Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド

11g リリース1(11.1.1.6.0)

B52029-06(原本部品番号:B31973-11)

目次

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

はじめに

- 対象読者

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

- 関連ドキュメント

- 表記規則

リリース11.1.1.6.0用のこのガイドでの新しい情報

第I部 ADF Faces概説

1 ADF Facesリッチ・クライアントの概要

- 1.1 ADF Facesリッチ・クライアントの概要

- 1.1.1 ADF Facesの歴史

- 1.1.2 リッチ・クライアント・コンポーネントとしてのADF Faces

- 1.2 ADF Facesコンポーネントのアーキテクチャ

- 1.2.1 クライアント側アーキテクチャ

- 1.2.1.1 クライアント側コンポーネント

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

- 1.2.2 ADF Facesのアーキテクチャ上の機能

- 1.3 ADF Facesコンポーネント

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

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

- 1.4.2 ADF Facesデモ・アプリケーションの使用

- 1.4.3 File Explorerアプリケーションの概要

- 1.4.4 JDeveloperでのソース・コードの表示

2 ADF Faces概説

- 2.1 JDeveloperでの宣言的開発

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

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

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

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

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

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

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

- 2.4.1 JSF JSPページの作成方法

- 2.4.2 JSF JSPページを作成する場合の処理

- 2.4.3 自動コンポーネント・バインディングについて

- 2.4.4 Facelets XHTMLページの作成方法

- 2.4.5 JSF XHTMLページを作成する場合の処理

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

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

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

- 2.4.9 プロパティ・インスペクタを使用する場合の処理

- 2.5 EL式の作成

- 2.5.1 EL式の作成方法

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

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

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

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

- 2.6.3 コンポーネント・バインディングおよびマネージドBeanについて

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

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

3 ADF Facesアーキテクチャの使用

- 3.1 ADF Facesアーキテクチャの使用の概要

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

- 3.3 JavaScriptのページへの追加

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

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

- 3.3.3 クライアント・イベント・ソースへのアクセスについて

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

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

- 3.5.1 ネーミング・コンテナ内のコンポーネントの検索について

- 3.6 ユーザーの現在位置の特定

- 3.6.1 ユーザーの現在位置の特定方法

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

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

- 3.7.2 disabledプロパティを保護しない方法

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

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

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

- 3.8.2 ボーナス属性のマーシャリングについて

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

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

- 3.9.2 VisibleとisShowing関数について

4 ADF FacesによるJSFライフサイクルの使用

- 4.1 JSFライフサイクルおよびADF Facesの概要

- 4.2 immediate属性の使用

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

- 4.3.1 immediate属性と最適化されたライフサイクルの使用について

- 4.3.2 LOVコンポーネントと最適化されたライフサイクルの使用について

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

- 4.5 サブフォームを使用したページでの領域の作成

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

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

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

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

- 4.7.3 実行時の処理: 値の受渡し

5 イベントの処理

- 5.1 イベントおよびイベント処理の概要

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

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

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

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

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

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

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

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

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

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

- 5.3.7 ネーミング・コンテナの使用について

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

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

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

- 5.4.3 データのマーシャリングとアンマーシャリングについて

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

- 5.6 クライアントの動作タグの使用

- 5.6.1 scrollComponentIntoViewBehaviorタグの使用方法

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

- 5.7.1 ポーリング・コンポーネントの使用方法

6 入力の検証および変換

- 6.1 ADF Facesの変換および検証の概要

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

- 6.3 変換の追加

- 6.3.1 標準ADF Facesコンバータを追加する方法

- 6.3.2 標準のADF Facesコンバータでの属性の設定方法

- 6.3.3 実行時の処理

- 6.3.4 oracle.jbo.domainコンバータを追加する方法

- 6.4 カスタムJSFコンバータの作成

- 6.4.1 カスタムJSFコンバータの作成方法

- 6.4.2 カスタム・コンバータを使用する場合の処理

- 6.5 検証の追加

- 6.5.1 検証の追加方法

- 6.5.1.1 ADF Facesの検証の追加

- 6.5.1.2 検証属性の使用

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

- 6.5.2 実行時の処理

- 6.5.3 複数バリデータについて

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

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

- 6.6.2 バッキングBean検証メソッドを作成する場合の処理

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

- 6.6.4 カスタムJSFバリデータを使用する場合の処理

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

- 7.1 部分ページ・レンダリングの概要

- 7.2 部分ページ・レンダリングの宣言的有効化

- 7.2.1 部分ページ・レンダリングを有効にする方法

- 7.2.2 ブラウザの戻るボタンの使用について

- 7.2.3 PPRおよびスクリーン・リーダーについて

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

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

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

- 7.4.2 PPRナビゲーションについて

第III部 ADF Facesコンポーネントの使用

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

- 8.1 Webページ上のコンテンツの編成の概要

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

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

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

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

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

- 8.2.5 documentタグの構成方法

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

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

- 8.3.2 ジオメトリ管理およびpanelStretchLayoutコンポーネントについて

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

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

- 8.4.2 ジオメトリ管理およびpanelSplitterコンポーネントについて

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

- 8.5.1 panelBorderLayoutコンポーネントの使用方法

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

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

- 8.6.2 groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法について

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

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

- 8.7.2 ジオメトリ管理およびpanelDashboardコンポーネントについて

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

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

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

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

- 8.8.4 表示イベントについて

- 8.9 アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示

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

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

- 8.9.3 panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法

- 8.9.4 ジオメトリ管理およびshowDetailItemコンポーネントについて

- 8.9.5 showDetailItem表示イベントについて

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

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

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

- 8.10.3 ジオメトリ管理およびdecorativeBoxコンポーネントについて

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

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

- 8.11.2 リスト階層の作成について

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

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

- 8.12.2 ジオメトリ管理およびpanelGroupLayoutコンポーネントについて

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

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

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

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

- 9.1 入力コンポーネントおよびフォームの概要

- 9.2 formの定義

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

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

- 9.2.3 formへのリセット・ボタンの追加方法

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

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

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

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

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

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

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

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

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

- 9.5.3 inputDateコンポーネントなしのタイム・ゾーンの選択について

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

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

- 9.6.2 SelectManyChoiceコンポーネントのcontentDelivery属性について

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

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

- 9.7.2 選択イベントのクライアント・リスナーの使用方法について

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

- 9.8.1 richTextEditorコンポーネントを追加する方法

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

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

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

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

- 9.9.2 一時的なファイルの格納について

10 表およびツリーの使用

- 10.1 表、ツリーおよびツリー表の概要

- 10.1.1 コンテンツの配信

- 10.1.2 行の選択

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

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

- 10.1.5 クライアントの表、ツリーおよびツリー表コンポーネントへのアクセス

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

- 10.2 表へのデータの表示

- 10.2.1 列および列データ

- 10.2.2 表の書式設定

- 10.2.3 列の書式設定

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

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

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

- 10.2.7 プログラムを使用した表の列のソートの有効化について

- 10.2.8 表の選択された行でのアクションの実行について

- 10.2.9 表の選択コンポーネント値の動的な決定について

- 10.2.10 イテレータ・タグの使用について

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

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

- 10.3.2 実行時の処理: 行データの公開

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

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

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

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

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

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

- 10.5.4 プログラムを使用したノードの開閉について

- 10.5.5 プログラムを使用したノードの選択について

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

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

- 10.7 行を値として渡す

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

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

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

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

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

- 10.10 スタンプ設定を使用するコンポーネントからクライアント上の選択された値へのアクセス

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

- 10.10.2 選択された値へのアクセスについて

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

- 11.1 値リスト・コンポーネントの概要

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

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

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

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

- 12.1 問合せコンポーネントの概要

- 12.2 問合せへのモデルの実装

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

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

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

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

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

- 12.4.1 問合せコンポーネントの追加方法

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

- 13.1 ポップアップ要素の使用の概要

- 13.2 ポップアップ要素の宣言的作成

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

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

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

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

- 13.2.5 実行時の処理: ポップアップ・コンポーネント・イベント

- 13.3 プログラムによるポップアップの起動

- 13.3.1 プログラムによるポップアップの起動方法

- 13.3.2 プログラムでポップアップの起動する場合の処理

- 13.4 ポップアップ要素の起動

- 13.4.1 af:showPopupBehaviorタグの使用方法

- 13.5 コンテキスト情報の表示

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

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

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

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

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

- 14.1 メニュー、ツールバーおよびツールボックスの概要

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

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

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

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

- 14.3.2 実行時の処理: メニュー・バーおよびツールバーのサイズの決定

- 14.3.3 ツールバーについて

15 Calendarアプリケーションの作成

- 15.1 Calendarアプリケーションの作成の概要

- 15.2 Calendarの作成

- 15.2.1 Calendarのクラス

- 15.2.2 Calendarの作成方法

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

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

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

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

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

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

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

- 15.6 Calendarのスタイル設定

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

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

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

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

- 16.1 出力テキスト、イメージ、アイコンおよびメディア・コンポーネントの概要

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

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

- 16.2.2 outputFormattedコンポーネントで使用可能な書式設定コードと文字コードについて

- 16.3 アイコンの表示

- 16.4 イメージの表示

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

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

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

- 16.6.2 カルーセル・コンポーネントおよび他のブラウザについて

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

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

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

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

- 17.1 ヒントおよびメッセージの表示の概要

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

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

- 17.3.1 バリデータおよびコンバータのカスタム・メッセージの定義方法

- 17.3.2 デフォルト・メッセージのグローバルなオーバーライドについて

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

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

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

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

- 17.5.1 リソース・バンドルベースのヘルプの作成方法

- 17.5.2 XLIFFベースのヘルプの作成方法

- 17.5.3 マネージドBeanヘルプの作成方法

- 17.5.4 JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法

- 17.5.5 Javaクラス・ヘルプ・プロバイダの作成方法

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

- 17.5.7 異なるメッセージ・タイプの組合せについて

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

- 18.1 ナビゲーション・コンポーネントの概要

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

- 18.2.1 コマンド・ボタンおよびコマンド・リンクの使用方法

- 18.2.2 実行ボタンおよび実行リンクの使用方法

- 18.3 コマンド・リンクに対するブラウザのポップアップ・メニューの構成

- 18.3.1 コマンド・リンクに対するブラウザのポップアップ・メニューの構成

- 18.3.2 コマンド・リンクに対するブラウザのポップアップ・メニューを構成した場合の処理

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

- 18.4.1 ファイルをダウンロードするためのコマンド・コンポーネントの使用方法

- 18.4.2 入力フィールドをリセットするためのコマンド・コンポーネントの使用方法

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

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

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

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

- 18.6.3 JSFページでのXMLMenuModelへのバインド方法

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

- 18.6.5 実行時の処理

- 18.6.6 カスタム属性の使用について

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

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

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

- 18.7.3 ナビゲーション・タブの削除について

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

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

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

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

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

- 19.1 再利用可能なコンテンツの概要

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

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

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

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

- 19.2.3.1 コンポーネント・パレットによるページ・フラグメントの追加

- 19.2.3.2 アプリケーション・ナビゲータによるページ・フラグメントの追加

- 19.2.4 実行時の処理: ページ・フラグメントの解決

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

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

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

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

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

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

- 19.3.6 ページ・テンプレートおよびネーミング・コンテナについて

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

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

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

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

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

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

- 19.4.6 実行時の処理

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

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

- 19.5.2 実行時の処理: ドキュメント・ヘッダーへのリソースの追加

20 スタイルおよびスキンを使用した外観のカスタマイズ

- 20.1 スキン、スタイル・セレクタおよびスタイル・プロパティの概要

- 20.1.1 ADF Facesスキン

- 20.1.2 スキン・スタイル・セレクタ

- 20.1.3 コンポーネント・スタイル・プロパティ

- 20.2 アプリケーションへのカスタム・スキンの適用

- 20.2.1 アプリケーションへのカスタム・スキンの追加方法

- 20.2.2 カスタム・スキンのためのXMLスキーマ定義ファイルの登録方法

- 20.2.3 カスタム・スキンの登録方法

- 20.2.4 カスタム・スキンを使用するためのアプリケーションの構成方法

- 20.3 スキン・スタイル・プロパティの定義

- 20.3.1 テキストへのスキンの適用方法

- 20.3.2 アイコンへのスキンの適用方法

- 20.3.3 メッセージへのスキンの適用方法

- 20.3.4 コンポーネントへのテーマの適用方法

- 20.3.5 カスタム別名の作成方法

- 20.3.6 スキンを動的に変更するためのコンポーネントの構成方法

- 20.4 コンポーネントのスタイル・プロパティの変更

- 20.4.1 インライン・スタイルの設定方法

- 20.4.2 スタイル・クラスの設定方法

- 20.5 スキンのCSSファイルにおけるURLの参照

- 20.6 カスタム・スキンのバージョニング

- 20.6.1 カスタム・スキンのバージョニング方法

- 20.6.2 カスタム・スキンをバージョニングした場合の処理

- 20.7 JARファイルへのカスタム・スキン・ファイルのデプロイ

21 ページの国際化およびローカライズ

- 21.1 ADF Facesページの国際化およびローカライズの概要

- 21.2 JDeveloperにおける自動リソース・バンドル統合の使用

- 21.2.1 リソース・バンドル・オプションの設定方法

- 21.2.2 リソース・バンドル・オプションを設定した場合の処理

- 21.2.3 JDeveloperで生成されたリソース・バンドルにエントリを作成する方法

- 21.2.4 JDeveloperで生成されたリソース・バンドルにエントリを作成した場合の処理

- 21.3 リソース・バンドルおよびロケールの手動での定義

- 21.3.1 ベース・リソース・バンドルの定義方法

- 21.3.2 リソース・バンドル・ファイルの編集方法

- 21.3.3 アプリケーションへのロケールおよびリソース・バンドルの登録方法

- 21.3.4 アプリケーションでのリソース・バンドルの使用方法

- 21.3.5 カスタム・スキンおよびコントロール・ヒントについて

- 21.3.6 カスタマイズ可能なアプリケーションでのリソース・バンドルのオーバーライドについて

- 21.4 エンド・ユーザーが実行時にロケールを指定するページの構成

- 21.4.1 エンド・ユーザーがロケールを指定するページの構成方法

- 21.4.2 ロケール指定するページを構成した場合の処理

- 21.4.3 エンド・ユーザーがロケールを指定した場合の実行時の処理

- 21.5 ADF Facesのオプションのローカライゼーション・プロパティの構成

- 21.5.1 オプションのローカライゼーション・プロパティの構成方法

22 アクセス可能なADF Facesページの開発

- 22.1 アクセス可能なADF Facesページの概要

- 22.2 アクセシビリティ・プリファレンスの表示

- 22.2.1 trinidad-config.xmlにおけるアクセシビリティ・サポートの構成方法

- 22.3 コンポーネントレベルのアクセシビリティ・プロパティの指定

- 22.3.1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

- 22.3.2 スクリーン・リーダー・モードでのADF Faces表コンポーネントの使用

- 22.3.3 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

- 22.3.4 ADF Facesコンポーネントのアクセス・キーの定義方法

- 22.3.5 ローカライズされたラベルおよびアクセス・キーの定義方法

- 22.4 アクセス可能なページの作成

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

- 22.4.2 スクリプトの使用方法

- 22.4.3 スタイルの使用方法

- 22.4.4 ページ構造およびナビゲーションの使用方法

- 22.4.5 WAI-ARIAランドマーク・リージョンの使用方法

- 22.5 アクセシビリティ監査ルールの実行

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

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

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

- 23.2 ADFデータ視覚化コンポーネントの定義

- 23.2.1 グラフ

- 23.2.2 ゲージ

- 23.2.3 ピボット・テーブル

- 23.2.4 地理マップ

- 23.2.5 ガント・チャート

- 23.2.6 階層ビューア

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

- 23.4 Flashイメージ用カスタム・フォントのダウンロード

24 ADFグラフ・コンポーネントの使用

- 24.1 グラフ・コンポーネントの概要

- 24.2 グラフ・タグの理解

- 24.2.1 グラフ固有のタグ

- 24.2.2 一般的なグラフの子タグ

- 24.2.3 グラフ固有の子タグ

- 24.2.4 子セット・タグ

- 24.3 グラフのデータ要件の理解

- 24.3.1 面グラフのデータ要件

- 24.3.2 棒グラフのデータ要件

- 24.3.3 バブル・グラフのデータ要件

- 24.3.4 組合せグラフのデータ要件

- 24.3.5 ファンネル・グラフのデータ要件

- 24.3.6 折れ線グラフのデータ要件

- 24.3.7 パレート・グラフのデータ要件

- 24.3.8 円グラフのデータ要件

- 24.3.9 極グラフのデータ要件

- 24.3.10 レーダー・グラフのデータ要件

- 24.3.11 散布図のデータ要件

- 24.3.12 スパークチャートのデータ要件

- 24.3.13 株価チャートのデータ要件

- 24.3.13.1 株価チャート: 高値-安値-終値

- 24.3.13.2 株価チャート: 出来高付き高値-安値-終値

- 24.3.13.3 株価チャート: 始値-高値-安値-終値

- 24.3.13.4 株価チャート: 出来高付き始値-高値-安値-終値

- 24.3.13.5 ローソク足株価チャート: 始値-終値

- 24.3.13.6 ローソク足株価チャート: 出来高付き始値-終値

- 24.3.13.7 ローソク足株価チャート: 始値-高値-安値-終値

- 24.3.13.8 株価チャート: 出来高付き始値-高値-安値-終値

- 24.4 グラフの作成

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

- 24.4.1.1 グラフ用の表形式データのマネージドBeanへの格納

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

- 24.4.2 表形式データを使用してグラフを作成する場合の処理

- 24.4.3 グラフのイメージ形式について

- 24.5 グラフ・タイプの変更

- 24.6 グラフの外観のカスタマイズ

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

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

- 24.6.1.2 系列のアイテムの表示/非表示を有効にする方法

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

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

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

- 24.6.2.3 自動スケーリングと精度について

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

- 24.6.3.1 スキンを使用したグラフ・フォントのグローバルな設定方法

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

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

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

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

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

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

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

- 24.6.6 グラフの軸とラベルのカスタマイズ

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

- 24.6.6.2 軸のスクロールの指定方法

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

- 24.6.6.4 軸の数値の書式設定方法

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

- 24.6.7 グラフの凡例のカスタマイズ

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

- 24.7 特定のグラフ・タイプの外観のカスタマイズ

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

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

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

- 24.7.2 グラフの線の外観の変更

- 24.7.2.1 グラフにデータ線またはマーカーを表示する方法

- 24.7.2.2 グラフ系列の線の外観の変更方法

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

- 24.7.4 散布図の系列マーカーのカスタマイズ

- 24.8 特殊な機能のグラフへの追加

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

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

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

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

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

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

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

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

- 24.8.4 グラフへのコンテキスト・メニューの追加

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

- 24.8.4.2 Flashレンダリング形式について

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

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

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

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

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

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

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

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

- 24.9.1 アクティブ・データを表示するグラフ・コンポーネントの構成方法

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

25 ADFゲージ・コンポーネントの使用

- 25.1 ゲージ・コンポーネントの概要

- 25.1.1 ゲージのタイプ

- 25.1.2 ゲージの用語

- 25.2 ゲージのデータ要件の理解

- 25.3 ゲージの作成

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

- 25.3.1.1 ゲージ用の表形式データのマネージドBeanへの格納

- 25.3.1.2 表形式データのリストの構造

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

- 25.3.3 表形式データを使用してゲージを作成する場合の処理

- 25.3.4 ゲージ形式について

- 25.4 ゲージ・タイプのレイアウトおよび外観のカスタマイズ

- 25.4.1 ゲージのタイプの変更方法

- 25.4.2 ゲージ・セットでのゲージのレイアウトの決定方法

- 25.4.3 ゲージのサイズとスタイルの変更

- 25.4.3.1 ゲージの初期表示サイズの指定

- 25.4.3.2 ゲージの動的サイズ変更の指定

- 25.4.3.3 ゲージのカスタム・スタイル・クラスの使用

- 25.4.4 しきい値のゲージへの追加方法

- 25.4.4.1 静的しきい値のゲージへの追加

- 25.4.5 ゲージでの数値の書式設定方法

- 25.4.5.1 ゲージのメトリック・ラベルの数値の書式設定

- 25.4.6 ゲージ・メトリック・ラベルの数値を書式設定する場合の処理

- 25.4.7 自動スケーリングと精度について

- 25.4.8 ゲージでのテキストの書式設定方法

- 25.4.9 N度のダイアルの指定方法

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

- 25.4.10.1 ゲージ・ラベルの位置の制御

- 25.4.10.2 ゲージ・ラベルの色と枠のカスタマイズ

- 25.4.11 インジケータとティック・マークのカスタマイズ方法

- 25.4.11.1 ゲージ・インジケータの外観の制御

- 25.4.11.2 ティック・マークとラベルの指定

- 25.4.11.3 外側のティック・ラベルの作成

- 25.4.12 ゲージの箇所に対する透明色の指定

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

- 25.5.1 ゲージでのグラデーション特殊効果の使用方法

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

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

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

- 25.5.4 ゲージにアニメーションを使用する方法

- 25.5.5 アクティブ・データによるゲージへのアニメーションの使用方法

- 25.5.5.1 アクティブ・データを表示するゲージ・コンポーネントの構成

- 25.5.5.2 アニメーションのゲージへの追加

- 25.6 ゲージでのカスタム形状の使用

- 25.6.1 カスタム形状グラフィック・ファイルの作成方法

- 25.6.2 カスタム形状ファイルの作成方法

- 25.6.3 サポートされているSVG機能について

- 25.6.4 カスタム形状スタイルの設定方法

26 ADFピボット・テーブル・コンポーネントの使用

- 26.1 ADFピボット・テーブル・コンポーネントの概要

- 26.1.1 ピボット・テーブルの要素と用語

- 26.2 ピボット・テーブルのデータ要件の理解

- 26.3 レイヤーのピボット

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

- 26.5 ピボット・テーブルでのソート

- 26.6 ピボット・テーブルのサイズ

- 26.6.1 ピボット・テーブル全体のサイズの設定方法

- 26.6.2 行、列およびレイヤーのサイズを変更する方法

- 26.6.3 行、列およびレイヤーのサイズの変更について

- 26.7 部分ページ・レンダリングによるピボット・テーブルの更新

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

- 26.9 ピボット・テーブルのセルのコンテンツのカスタマイズ

- 26.9.1 データ・セルに対するCellFormatオブジェクトの作成方法

- 26.9.2 CellFormatオブジェクトの作成方法

- 26.9.3 書式とテキスト・スタイルの変更方法

- 26.9.4 ピボット・テーブルでのストップライト書式設定と条件付書式設定の作成方法

- 26.10 ピボット・テーブルのデータ・セルのスタンプ設定および編集

- 26.10.1 データ・セルのカスタム・イメージの指定方法

- 26.10.2 ヘッダー・セルのイメージ、アイコン、リンクおよび読取り専用コンテンツの指定方法

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

- 26.11.1 ピボット・フィルタ・バーとピボット・テーブルを関連付ける方法

27 ADF地理マップ・コンポーネントの使用

- 27.1 地理マップの概要

- 27.1.1 使用可能なマップ・テーマ

- 27.1.2 地理マップの用語

- 27.1.3 地理マップ・コンポーネントのタグ

- 27.1.3.1 地理マップの親タグ

- 27.1.3.2 地理マップの子タグ

- 27.1.3.3 マップ・テーマを変更するタグ

- 27.2 地理マップのデータ要件の理解

- 27.3 マップ・サイズ、ズーム制御および選択領域合計のカスタマイズ

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

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

- 27.3.3 マップの選択値の合計方法

- 27.4 マップ・テーマのカスタマイズ

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

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

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

- 27.4.4 点テーマのポイント・イメージのカスタマイズ方法

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

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

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

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

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

- 27.5 ツールバーのマップへの追加

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

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

28 ADFガント・チャート・コンポーネントの使用

- 28.1 ADFガント・チャート・コンポーネントの概要

- 28.1.1 ガント・チャートのタイプ

- 28.1.2 ガント・チャートの機能領域

- 28.1.3 ガント・チャートのタスクの説明

- 28.2 ガント・チャート・タグとファセットの理解

- 28.3 ガント・チャートのユーザー対話性の理解

- 28.3.1 ガント・チャートでの移動

- 28.3.1.1 リスト領域またはチャート領域のスクロールとパン

- 28.3.1.2 ガント・チャートでの特定の日付への移動方法

- 28.3.1.3 表領域での列の可視性の制御方法

- 28.3.2 階層リストまたはフラット・リストでのデータの表示方法

- 28.3.3 ガント・チャートのタイム・スケールの変更方法

- 28.4 ガント・チャートのデータ要件の理解

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

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

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

- 28.5 ADFガント・チャートの作成

- 28.6 ガント・チャートの凡例、ツールバーおよびポップアップ・メニューのカスタマイズ

- 28.6.1 ガント・チャートの凡例のカスタマイズ方法

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

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

- 28.7 ガント・チャートのタスクとリソースの使用

- 28.7.1 新しいタスク・タイプの作成方法

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

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

- 28.8 休日、読取り専用機能および時間軸の指定

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

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

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

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

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

- 28.8.3.1 カスタム時間軸の作成方法と使用方法

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

- 28.9.1 印刷オプション

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

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

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

- 29.1 階層ビューアの概要

- 29.1.1 階層ビューア・コンポーネントの理解

- 29.1.2 階層ビューアの要素と用語

- 29.1.3 使用可能な階層ビューアのレイアウト・オプション

- 29.1.4 階層ビューアのレンダリングとHTMLについて

- 29.2 階層ビューアのデータ要件

- 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.4.3 階層ビューアで同レベル・ナビゲーションを構成する場合の処理

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

- 29.5.1 3Dティルト・パンの構成方法

- 29.5.2 ノード選択アクションの構成方法

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

- 29.5.4 メニューを起動するための階層ビューア・ノードの構成方法

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

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

- 29.6.2 実行時にパネル・カード・コンポーネントをレンダリングする場合の処理

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

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

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

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

- 29.7.4 リンクとラベルの表示の構成方法

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

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

- 29.8.2 階層ビューアでの検索の構成について

第V部 高度なトピック

30 カスタムADF Facesコンポーネントの作成

- 30.1 カスタムADF Facesコンポーネントの概要

- 30.1.1 JDeveloperを使用したカスタム・コンポーネントの開発

- 30.1.2 カスタム・コンポーネントの例

- 30.2 ワークスペースと基礎ファイルの設定

- 30.2.1 JDeveloperカスタム・コンポーネント環境の設定方法

- 30.2.2 Faces構成ファイルの追加方法

- 30.2.3 MyFaces Trinidadスキン構成ファイルの追加方法

- 30.2.4 Cascading Style Sheetの追加方法

- 30.2.5 リソース・キット・ローダーの追加方法

- 30.2.6 JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法

- 30.2.7 JavaScriptライブラリ機能構成ファイルの追加方法

- 30.2.8 Faceletsタグ・ライブラリ構成ファイルの追加方法

- 30.3 クライアント側の開発

- 30.3.1 コンポーネントのJavaScriptファイルの作成方法

- 30.3.2 イベントのJavaScriptファイルの作成方法

- 30.3.3 ピアのJavaScriptファイルの作成方法

- 30.3.4 JavaScriptライブラリ機能構成ファイルへのカスタム・コンポーネントの追加方法

- 30.4 サーバー側の開発

- 30.4.1 イベント・リスナーのクラスの作成方法

- 30.4.2 イベントのクラスの作成方法

- 30.4.3 コンポーネントの作成

- 30.4.4 コンポーネントのクラスの作成方法

- 30.4.5 faces-config.xmlファイルへのコンポーネントの追加方法

- 30.4.6 リソース・バンドルのクラスの作成方法

- 30.4.7 レンダラのクラスの作成方法

- 30.4.8 faces-config.xmlファイルへのレンダラの追加方法

- 30.4.9 JSPタグ・プロパティの作成方法

- 30.4.10 タグ・ライブラリ・ディスクリプタの構成方法

- 30.4.11 リソース・ローダーの作成方法

- 30.4.12 MyFaces Trinidad Cascading Style Sheetの作成方法

- 30.5 コンポーネント・ライブラリのデプロイ

- 30.6 アプリケーションへのカスタム・コンポーネントの追加

- 30.6.1 Webデプロイメント・ディスクリプタの構成方法

- 30.6.2 JavaScriptロギングとアサーションを有効にする方法

- 30.6.3 JSFページへのカスタム・コンポーネントの追加方法

- 30.6.4 tagPaneカスタム・コンポーネントの使用について

31 JSFページでのユーザー・カスタマイズの許可

- 31.1 ユーザー・カスタマイズの概要

- 31.2 セッション変更永続性の実装

- 31.2.1 セッション変更永続性の実装方法

- 31.2.2 変更永続性を使用するようアプリケーションを構成する場合の処理

- 31.2.3 実行時の処理

- 31.2.4 テンプレートおよび領域での変更永続性の使用について

32 ドラッグ・アンド・ドロップ機能の追加

- 32.1 ドラッグ・アンド・ドロップ機能の概要

- 32.2 属性のドラッグ・アンド・ドロップ機能の追加

- 32.3 オブジェクトのドラッグ・アンド・ドロップ機能の追加

- 32.3.1 単一オブジェクトのドラッグ・アンド・ドロップ機能の追加方法

- 32.3.2 実行時の処理

- 32.3.3 ClientDropListenerの使用について

- 32.4 コレクションのドラッグ・アンド・ドロップ機能の追加

- 32.4.1 コレクションのドラッグ・アンド・ドロップ機能の追加方法

- 32.4.2 dragDropEndListenerについて

- 32.5 コンポーネントのドラッグ・アンド・ドロップ機能の追加

- 32.5.1 コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

- 32.6 panelDashboardコンポーネントに対するドラッグ・アンド・ドロップ機能の追加

- 32.6.1 panelDashboardコンポーネントへのドラッグ・アンド・ドロップ機能の追加方法

- 32.6.2 panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の追加方法

- 32.7 Calendarへのドラッグ・アンド・ドロップ機能の追加

- 32.7.1 Calendarへのドラッグ・アンド・ドロップ機能の追加方法

- 32.7.2 Calendarのドラッグ・アンド・ドロップについて

- 32.8 DVTグラフのドラッグ・アンド・ドロップ機能の追加

- 32.8.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加方法

- 32.9 DVTガント・チャートのドラッグ・アンド・ドロップ機能の追加

- 32.9.1 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加方法

33 様々な出力モードの使用

- 33.1 様々な出力モードの使用の概要

- 33.2 印刷用のページの表示

- 33.2.1 showPrintablePageBehaviorタグの使用方法

- 33.3 メール可能なページの作成

- 33.3.1 メール可能なページの作成方法

- 33.3.2 メール・クライアントでページのレンダリングをテストする方法

- 33.3.3 実行時の処理: ADF FacesによるJSFページからメール可能なページへの変換

第VI部 付録

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 プロファイリング

- A.2.3.7 Faceletサポート

- A.2.3.8 ダイアログ接頭辞

- A.2.3.9 CSSクラス名の圧縮

- A.2.3.10 テストの自動化

- A.2.3.11 UIViewRootキャッシング

- A.2.3.12 テーマと色調スタイル

- A.2.3.13 部分ページ・ナビゲーション

- A.2.3.14 JavaScriptのパーティション化

- A.2.3.15 フレームバスティング

- A.2.3.16 自動生成コンポーネントIDの抑制

- A.2.3.17 ADF Facesキャッシング・フィルタ

- A.2.3.18 コマンド・リンクのネイティブ･ブラウザ・コンテキスト・メニューの構成

- A.2.3.19 セッション・タイムアウトの警告

- A.2.3.20 HTTPストリーミングでのJSPタグ実行

- A.2.3.21 スプラッシュ画面

- A.2.3.22 グラフとゲージのイメージ形式

- 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キャッシング・フィルタのキャッシング・ルールの定義

- A.4.3 コンポーネント出力形式としてのFlashの構成

- A.4.4 コンテンツ配信ネットワークの使用

- A.4.4.1 スキン・スタイルシートおよびCDNについて

- A.4.4.2 JavaScriptおよび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.7 trinidad-skins.xmlでの構成

- A.8 RequestContext EL暗黙オブジェクトの使用

- A.9 JavaScriptライブラリのパーティション化の使用

- A.9.1 JavaScript機能の作成方法

- A.9.2 JavaScriptパーティションの作成方法

- A.9.3 adf-js-partitions.xmlファイルについて

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

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.4 ADFデータ視覚化コンポーネントのアクセラレータ・キー

- C.5 アクセス・キー

- C.6 デフォルトのカーソルまたはフォーカスの配置

- C.7 [Enter]キー

D ADF Facesを使用したタッチ装置のWebアプリケーションの作成

- D.1 ADF Facesを使用したタッチ装置のWebアプリケーションの作成の概要

- D.2 タッチ装置上のモバイル・ブラウザでのADF Facesの動作

- D.3 モバイル・ブラウザでADF Facesコンポーネントを使用する場合のベスト・プラクティス

E クイック・スタート・レイアウト・テーマ

Oracle® Fusion Middleware

Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド

11g リリース1(11.1.1.6.0)

B52029-06(原本部品番号:B31973-11)

2012年3月

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

Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド 11g リリース1 (11.1.1.6.0)

B52029-06

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

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

原本協力者: Poh Lee Tan and Odile Sullivan-Tarazi

原本協力者: ADF Faces development team, 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の登録商標です。

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

はじめに

『Oracle Application Development Framework 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 Fusion Middleware Oracle Application Development FrameworkのためのFusion開発者ガイド』

- 『Oracle Fusion Middleware Oracle Application Development Framework Java EE開発者ガイド』

- 『Oracle Fusion Middleware Oracle Application Development Frameworkのためのデスクトップ統合開発者ガイド』

- Oracle Fusion Middleware Oracle Application Development Frameworkモバイル・ブラウザ開発者ガイド

- 『Oracle Fusion Middleware Oracle Application Development Framework管理者ガイド』

- Oracle JDeveloper 11gオンライン・ヘルプ

- Oracle JDeveloper 11gリリース・ノート(JDeveloper 11gインストール内およびOracle Technology Networkから入手)

- Oracle Fusion Middleware Java API Reference for Oracle ADF Faces

- Oracle Fusion Middleware Java APIリファレンス for Oracle ADF Faces Client JavaScript

- Oracle Fusion Middleware Java API Reference for Oracle ADF Data Visualization Components

- Oracle Fusion Middlewareタグ・リファレンス for Oracle ADF Faces

- Oracle Fusion Middleware Data Visualization Toolsタグ・リファレンス for Oracle ADF Faces

- Oracle Fusion Middlewareタグ・リファレンス for Oracle ADF Facesスキン・セレクタ

- Oracle Fusion Middleware Data Visualization Toolsタグ・リファレンス for Oracle ADFスキン・セレクタ

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

イタリック体

イタリックは、ユーザーが特定の値を指定するプレースホルダ変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

リリース11.1.1.6.0用のこのガイドでの新しい情報

このマニュアルは、リリース11.1.1.6.0の情報でいくつかの部分が更新されています。次の表に、追加または変更された部分をリストします。

このリリースでOracle JDeveloperおよびOracle Application Development Framework(Oracle ADF)に加えられた変更については、Oracle Technology Networkの新機能に関するページ(http://www.oracle.com/technetwork/developer-tools/jdev/overview/index.html)を参照してください。

項

加えられた変更

第3章「ADF Facesアーキテクチャの使用」

3.6項「ユーザーの現在位置の特定」

ユーザーが現在アクセスしているページをプログラムで特定する方法を説明するために追加された項。

第8章「Webページ上のコンテンツの編成」

8.8.2項「showDetailHeaderコンポーネントの使用方法」

新しいheaderLevel属性をドキュメント化するために改訂された項。

8.10.1項「panelHeaderコンポーネントの使用方法」

新しいheaderLevel属性をドキュメント化するために改訂された項。

第10章「表およびツリーの使用」

10.9.1項「表、ツリーまたはツリー表データの外部形式へのエクスポート方法」

detailStampファセットのコンテンツがエクスポートされるかどうかを制御するexportCollectionActionListenerの新しい属性をドキュメント化するために改訂された項。

第16章「出力コンポーネントの使用」

16.6項「カルーセルでのイメージの表示」

カルーセル・コンポーネントのauxiliaryOffset、auxiliaryPopOutおよびauxiliaryScale属性をドキュメント化するために改訂された項。

第20章「スタイルおよびスキンを使用した外観のカスタマイズ」

20.1.1項「ADF Facesスキン」

タッチ・スクリーン・デバイスでアプリケーションがレンダリングされるタイミングの最適化を含む、新しいfusionFx-v1.2スキンを説明するために改訂された項。

20.1.2項「スキン・スタイル・セレクタ」

@agentルールで提供されるようになったタッチ・スクリーン機能のサポートを説明するために改訂された項。

第21章「ページの国際化およびローカライズ」

21.3.6項「カスタマイズ可能なアプリケーションでのリソース・バンドルのオーバーライドについて」

リソース・バンドルをカスタマイズできるように構成する方法を明確にするために追加された項。

第22章「アクセス可能なADF Facesページの開発」

22.2項「アクセシビリティ・プリファレンスの表示」

コンテンツを修正するために改訂された項。

第24章「ADFグラフ・コンポーネントの使用」

24.6.1項「グラフのデータ値の色、スタイルおよび表示の変更」

seriesObjectCount属性を設定する不要なプロシージャを削除するために改訂された項。

24.6.7項「グラフの凡例のカスタマイズ」

新しいpositionHint属性、および双方向ロケールのイメージ・サポートをドキュメント化するために改訂された項。

24.8.4項「グラフへのコンテキスト・メニューの追加」

グラフのポップアップ・メニューの作成方法を説明するために追加された項。

第25章「ADFゲージ・コンポーネントの使用」

25.1項「ゲージ・コンポーネントの概要」

双方向ロケールのイメージ・サポートを含むために改訂された項。

第29章「ADF階層ビューア・コンポーネントの使用」

29.1項「階層ビューアの概要」

次の説明を追加するために改訂された項。

- ナビゲーション中の状態管理

- disclosedRowKeyリスナー

- 階層ビューアの出力

- 双方向テキスト

第33章「様々な出力モードの使用」

33.3.1項「メール可能なページの作成方法」

電子メール・ページをオフラインでレンダリングする方法をドキュメント化するために改訂された項。

付録A「ADF Facesの構成」

A.2.3.17項「ADF Facesキャッシング・フィルタ」

Oracle Traffic Directorのサポートを追加するために改訂された項。

A.2.3.22項「グラフとゲージのイメージ形式」

oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMATパラメータをドキュメントするために追加された項。

A.4.4項「コンテンツ配信ネットワークの使用」

ADF Facesでコンテンツ配信ネットワークを使用する方法をドキュメント化するために追加された項。

付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」

付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」

ADF Facesのタブレット・サポートをドキュメント化するために作成された付録。

第I部

ADF Faces概説

第I部には、次の章が含まれています。

- 第1章「ADF Facesリッチ・クライアントの概要」

- 第2章「ADF Faces概説」

1 ADF Facesリッチ・クライアントの概要

この章では、ADF Facesリッチ・クライアントの概要を、その歴史、フレームワークの機能の概要およびライブラリ内の各コンポーネント・タイプの概要も含めて説明します。このガイドと組み合せて使用できるADF Facesデモ・アプリケーションについても説明します。

この章では、次の項目について説明します。

- 1.1項「ADF Facesリッチ・クライアントの概要」

- 1.2項「ADF Facesコンポーネントのアーキテクチャ」

- 1.3項「ADF Facesコンポーネント」

- 1.4項「ADF Facesデモ・アプリケーション」

1.1 ADF Facesリッチ・クライアントの概要

ADF Facesリッチ・クライアント(ADF Facesとも呼ばれる)は、ビルトインのAsynchronous JavaScript and XML(AJAX)機能を含むJavaServer Faces(JSF)コンポーネントのセットです。AJAXでは、リッチ・クライアント型の機能をブラウザベースのアプリケーションに提供しますが、JSFを使用することでサーバー側制御が提供され、AJAXベースのアプリケーションを実装するためにアプリケーション開発者が記述する必要のある、JavaScriptコードの量が少なくなります。

ADF Facesリッチ・クライアント・フレームワーク(RCF)には、JSFコンポーネントの豊富なセットに加えて、JSF開発モデルに慣れている開発者になじみの深いクライアント側プログラミング・モデルが用意されています。大部分のRCFと標準JSFアプリケーションとの違いはほとんどなく、サーバー・プログラミング・モデルはJavaServer Facesであり、フレームワークではJavaServer Facesライフサイクル、サーバー側コンポーネント・ツリーおよび式言語(EL)が使用されます。ただし、RCFでは、クライアント側プログラミング・モデルと、サーバーに依存せずに実行されるライフサイクルも用意されています。開発者は、JavaScriptからコンポーネントの検索や操作が可能で、たとえば、getプロパティやsetプロパティ、イベントの受取りとキューイングなど、すべてJavaScriptから実行できます。RCFでは、状態に矛盾がないように、コンポーネントの状態の変更が自動的にサーバーと同期され、必要に応じてイベントがサーバーに送信され、追加処理が実行されます。

ADF Facesの詳細について説明する前に、ADF Facesライブラリと、リッチ・インターネット・アプリケーション(RIA)、およびAJAX全般の簡単な歴史について説明します。

1.1.1 ADF Facesの歴史

1990年代、ソフトウェア・ベンダーはインターネット・アプリケーションがデスクトップアプリケーションのように動作する必要があると認識し始め、これらのアプリケーションを構築するためのRIAフレームワークを開発しました。しかし、これらのフレームワークでは、この機能を使用するためにユーザーが独自のプラグインをインストールする必要がありました。Web規格の開発に伴い、Java Webアプリケーションが一般的になり、開発コミュニティ全体で、標準のビュー・レイヤー・フレームワークの必要性が認識され始めました。Java Community Process(JCP)はJava Webアプリケーションの標準ユーザー・インタフェースとしてJSFを開発しました。まだ発展途上段階にあったJSR-127(2001年)から始まり、2004年の最初のリリースを経て、現リリースに至るまで、JSF仕様の定義と仕様の参照実装を作成するためにJCPにコミュニティ(オラクル社を含む)からリソースが結集されました。JSFは現在Java EE規格の一部です。

JSFがエンタープライズJavaビュー・コンポーネントの作成の標準であることで、ベンダーは、規格に準拠したアプリケーション・サーバー上で実行できる、独自のコンポーネントを開発できます。これらのコンポーネントはより高性能になり、開発者はシック・クライアント・アプリケーションのように動作するブラウザ・ベースのRIAを開発できるようにまりました。このようなニーズに対応するため、オラクル社は、JSFの任意のランタイム実装上で使用できる、ADF Facesというコンポーネント・セットを開発しました。ADF Facesには、標準JSFコンポーネントの機能を超えるビルトイン機能を持つ100以上のコンポーネント(データ表、階層型の表、カラー・ピッカー、日付ピッカーなど)のセットが用意されています。以来、オラクル社は、テクノロジやオープン・ソース・コミュニティにコミットしていくという自社の方針に基づいて、ADF Facesコンポーネント・ライブラリのバージョンをApache Software Foundationに寄贈しており、これは現在Apache MyFaces Trinidadと呼ばれています。このコンポーネント・ライブラリは、現在Apache Software Foundationを通じて配布されています。

ADF Facesでは、複雑なコンポーネントの標準セットが提供されただけでなく、AJAXで部分ページ・レンダリングを使用して部分的にリフレッシュできるようにもなりました。AJAXは、非同期JavaScript、動的HTML(DHTML)、XML、およびXmlHttpRequest通信チャネルを組み合せた技術で、これを使用すると、ページ全体の再レンダリングの必要なくサーバーへのリクエストが行えます。ただし、AJAXを使用してのみ構築されたページでは、開発者が大量のJavaScriptを記述する必要があります。

最新バージョンのADF FacesではAJAXを最大限に活用しており、完全機能のフレームワークも用意されているため、開発者はAJAXベースのRIAを、手作業でコーディングするJavaScriptの量を最小限に抑えながら比較的簡単に実装できます。ADF Facesを使用すると、証券アナリストがドラッグ・アンド・ドロップを使用して新しい銘柄記号を表ビューに追加できる証券トレーダのダッシュボード・アプリケーションを構築できるようになり、表ビューは、拡張プッシュ・テクノロジを使用してサーバー・モデルによって更新されます。新たな取引を終了するには、証券トレーダは、現在のページから移動することなく、顧客用に株を新たに購入するプロセスをナビゲートします。ADF Facesにより、開発者はJavaScriptの複雑さやDHTMLのブラウザ間の違いに取り組む必要がなくなります。

1.1.2 リッチ・クライアント・コンポーネントとしてのADF Faces

ADF Facesリッチ・クライアント・フレームワークでは、ドラッグ・アンド・ドロップ、軽量なダイアログ、ナビゲーションとメニューのフレームワーク、包括的なJavaScript APIなどの豊富なRIA機能が用意されています。ライブラリには、階層的なデータ表、ツリー・メニュー、ページ内ダイアログ、アコーディオン・パネル、ディバイダ、ソート可能な表を含む、100を超えるRIAコンポーネントが用意されています。ADF Facesには、動的チャート、グラフ、ゲージ、および基礎となるデータをリアルタイムで表示するその他のグラフィックをレンダリングできるFlashおよびSVG対応のコンポーネントである、視覚化のコンポーネントも用意されています。各コンポーネントには、カスタマイズやスキニングに加えて、国際化とアクセシビリティの機能も用意されています。

これらの機能を実現するために、ADF FacesではリッチJSFレンダー・キットが使用されます。このキットでは、HTMLコンテンツだけでなく、対応するクライアント側のコンポーネントもレンダリングされます。このビルトイン・サポートにより、個々のテクノロジを熟知する必要なくRIAを構築できます。

ADF Facesは、Faceletsライブラリを使用するアプリケーションで使用することもできます。Faceletsは、ビュー用JSPエンジン・テクノロジを使用する際の代替方法となる、JSF中心の宣言XMLビュー定義テクノロジです。ADF Facesのアーキテクチャの詳細は、1.2項「ADF Facesコンポーネントのアーキテクチャ」を参照してください。

ヒント:

ADF FacesをADFモデル・データ・バインディングと組み合せて使用し、ADF Facesコンポーネントをビジネス・レイヤーに宣言的にバインドできます。ADFモデル・データ・バインディングを使用すると、コードの記述が必要な開発タスクのほとんどが宣言的になります。ただし、このガイドでは、ADF Facesコンポーネントの標準JSFアプリケーションでの使用についてのみ説明します。ADF FacesとADFモデルを組み合せた使用の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』を参照してください。

RIAコンポーネントの充実したライブラリに加え、フル機能の開発環境にADF Facesコンポーネントの宣言サポートが組み込まれたJDeveloperも提供され、Webアプリケーションのビュー・レイヤーを簡便に構築できます。JDeveloperには、JSFページをWYSIWYG環境で表示するビジュアル・レイアウト・エディタが含まれています。JDeveloperのコンポーネント・パレットには、各ADF Facesコンポーネントがビジュアル形式で含まれ、ビジュアル・エディタでコンポーネントをページにドラッグ・アンド・ドロップできるため、タグ構文をページに手動で追加する必要がありません。JDeveloperにはモデリング、コーディング、デバッグ、テスト、チューニングおよびデプロイに関する機能が統合されているため、開発ライフサイクル全体で使用できます。JDeveloperの使用の詳細は、第2章「ADF Faces概説」を参照してください。

1.2 ADF Facesコンポーネントのアーキテクチャ

アプリケーション・ロジックの大半がクライアントにあるフレームワークと異なり、ADF Facesではアプリケーション・ロジックが主にサーバーに置かれ、JSFライフサイクルの中で実行されます。Javaデータ・モデルもサーバーに置かれ、ADF Facesフレームワークでコンポーネントの初期レンダリングがサーバーで実行され、ブラウザで直接使用されるHTMLコンテンツが生成されます。HTMLをサーバでレンダリングすることはクライアント側のレンダリングのオーバーヘッドが軽減されることを意味し、複雑なコンポーネントの場合に有効です。

注意:

ADF Facesは標準JSFテクノロジに準拠しているため、このガイドではJSF標準に付加する点、または異なる点を主に説明しています。このため、ADF Facesを使用して開発を始める前に、JSFがどのように機能するかについて、基本的な知識を得ておくことをお薦めします。JSFの詳細は、JavaのWebサイト(http://www.oracle.com/technetwork/java/index.html)を参照してください。

1.2.1 クライアント側アーキテクチャ

非常に多くのオブジェクトが作成されると、JavaScriptのパフォーマンスが低下することがあります。パフォーマンスを向上するために、RCFで、クライアントに存在するコンポーネント・オブジェクトの数とクライアントに送信される属性の数を最小にします。また、フレームワークのコンポーネントを構成するJavaScriptファイルは構成可能なパーティションに格納されており、アプリケーションに必要なJavaScriptのみをロードできます。

1.2.1.1 クライアント側コンポーネント

大部分のコンポーネント・ベースのフレームワーク同様、JSFのコンポーネント・モデルに固有の特性は、コンポーネントはネストして階層(通常コンポーネント・ツリーと呼ばれる)を形成できるということです。これは、親コンポーネントで子が追跡され、コンポーネント・ツリーをたどって特定のコンポーネントの子孫をすべて見つけることができるということです。コンポーネント・ツリー全体は従来どおりサーバーにあり、ADF Facesクライアント側コンポーネント・ツリーにはあまり移入されません。クライアント側コンポーネントは、主に、アプリケーション開発者とフレームワーク自体の両方に対するAPI規定を公開することでページに動作を追加するためにあります。たとえば、クライアントでのボタンの状態の切替えを可能にするのは、この規定です。このため、クライアント側コンポーネントは、クライアントで本当に必要なコンポーネントについてのみ作成され、通常、クライアント表現を持つよう明示的に構成されています。

既存のサーバー側コンポーネントに対応しないJavaScriptコンポーネントが存在することも可能です。たとえば、一部のADF Facesコンポーネントでは、ポップアップ・コンテンツが必要なクライアント側動作を持ちます。Java RichPopupコンポーネントが存在しなくても、これらのコンポーネントでAdfRichPopup JavaScriptコンポーネントを作成できます。

最も多く対話対象となるJavaScriptクラスはAdfUIComponentとそのサブクラスです。このクラスのインスタンスは、サーバー側コンポーネントのクライアント側表現です。各クライアント・コンポーネントには、プロパティ(キーと値のペア)のセットと、サポートされている各イベント・タイプ用のリスナーのリストがあります。すべてのRCF JavaScriptクラスは、他のJavaScriptライブラリと名前が競合しないようAdfで始まります。たとえば、RichCommandButtonはAdfRichCommandButtonを持ち、RichDocumentはAdfRichDocumentを持つなどです。

Java UIComponentオブジェクトはコンポーネントの状態を表し、リスナーを登録したり、プロパティを設定する際に対話対象となりますが、Rendererでは、コンポーネントのかわりにHTMLの生成とポストバックの受信が処理されます。RCFクライアント側JavaScriptレイヤーで、クライアント側コンポーネントはDocument Object Model(DOM)と直製対話しません。DOMとのすべての対話は、ピアと呼ばれる媒介を使用して行われます。ピアでは、Javaレンダラによって生成されたDOMと対話し、状態の更新とユーザーとの対話へのレスポンスが処理されます。

ピアでは、この他に次のような多くの処理が行われます。

- DOMの初期化とクリーンアップ

- DOMのイベント処理

- ジオメトリ管理

- 部分ページ・レスポンスの処理

- 子の可視性の変更の処理

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

JavaScriptを多用したフレームワークに共通する問題は、大規模なJavaScriptコード・ベースをクライアントに送信する最良の方法を決定することです。極端な方法は、すべてのコードを1つのJavaScriptライブラリにバンドリングすることで、この方法ではダウンロード時間が長くなります。逆の極端な方法はJavaScriptコードを多数の小さなJavaScriptライブラリに分割することで、この方法ではラウンドトリップ数が大きくなります。どちらの方法でも初期ページをロードするためのユーザーの待ち時間が不必要に長くなります。

この問題を軽減するために、ADF FacesではJavaScriptコードがパーティションに集約されます。JavaScriptライブラリ・パーティションには、コンポーネントのコードまたは通常一緒に使用される機能、あるいはその両方が含まれています。ADF Facesではデフォルトで、ダウンロード・サイズ合計とラウンドトリップ数合計のバランスを取ることを意図したパーティション化が行われます。

ADF Facesのライブラリ・パーティション化方式の利点の1つは、構成可能であることです。アプリケーションによって使用するコンポーネントおよび機能が異なるため、ADF Facesのデフォルトのパーティション化がすべてのアプリケーションに最適であるとはかぎりません。このため、ADF FacesのJavaScriptライブラリのパーティション化はアプリケーションごとにカスタマイズ可能になっています。このようなパーティション化により、アプリケーション開発者はJavaScriptライブラリのフットプリントをアプリケーションの要件に合せて調整できます。JavaScriptのパーティション化を構成する方法の詳細は、A.9項「JavaScriptライブラリのパーティション化の使用」を参照してください。

1.2.2 ADF Facesのアーキテクチャ上の機能

RCFでは、アプリケーション全体で使用できるアーキテクチャ上の機能が使用できます。たとえば、クライアントで処理が行われるため、ページ全体を再レンダリングする必要がなく、サーバーとの間のデータの交換が少量で済みます。これは、部分ページ・レンダリング(PPR)と呼ばれます。ADF Facesの多くのコンポーネントに、PPR機能がネイティブで実装されています。たとえば、ADF Facesの表コンポーネントには、表のスクロール、列ヘッダーのクリックによる表のソート、1つまたは複数の行の選択マークおよび表の特定の行の拡張などのAJAXスタイルの機能が組み込まれ、すべてサーバーへのラウンドトリップを必要とせずコーディングも不要です。詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

また、RCFでは、標準JSFライフサイクルに機能が追加されています。この例として、クライアント側の値のライフサイクル、1つのページに複数のフォームを使用することの弊害なしに独立して送信可能な領域をページに作成できるサブフォーム・コンポーネント、処理用に送信されるページの部分を限定できる最適化されたライフサイクルなどがあります。詳細は、第4章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

RCFでは、標準JSFイベント・フレームワークが使用されます。ただし、RCFのイベントは、標準JavaScript DOMイベント・モデルを要約したものです。DOMイベント・モデルの要点を共有するイベントもありますが、機能を追加したものもあります。このため、たとえばボタンのclickイベントをリスニングする必要がありません。かわりに、キーまたはマウスのイベントで発生する可能性のあるAdfActionEventイベントをリスニングします。RCFイベントでは、イベントをサーバーに配信するようにも配信しないようにも構成できます。詳細は、第5章「イベントの処理」を参照してください。

ADF Facesの入力コンポーネントには検証機能が組み込まれています。required属性を設定するか、事前作成のADF Facesバリデータを使用することにより、コンポーネントに1つ以上のバリデータを設定します。また、ビジネス・ニーズに応じてカスタム・バリデータを作成することもできます。

ADF Faces入力コンポーネントには変換機能も組み込まれているため、ユーザーは情報を文字列として入力し、アプリケーションで文字列を日付などの他のデータ型に自動的に変換できます。逆に、文字列以外の型として格納したデータを表示および更新用に文字列に変換することもできます。inputDateなどの多くのコンポーネントでは、自動的にこの機能が提供されます。詳細は、第6章「入力の検証および変換」を参照してください。

これらのアーキテクチャ上の機能に加えてRCFでは次のものもサポートされています。

- 完全機能付きクライアント側アーキテクチャ: AJAXタイプの機能をWebアプリケーションに作成するために必要な機能の多くはアーキテクチャのクライアント側にあります。詳細は、第3章「ADF Facesアーキテクチャの使用」を参照してください。

- 再使用: ページ・テンプレートやページ・フラグメント、複数のコンポーネントで構成され、アプリケーション全体で使用できるコンポジット・コンポーネントを作成できます。詳細は、第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」を参照してください。

- スキニング: コンポーネントの外観をグローバルに変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 国際化: ユーザーのロケールに基づいてテキストおよびその他の表示属性を変更できます。詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

- アクセシビリティ: キーボード・ショートカットやテキスト説明を含むアクセシビリティ・サポートを実装できます。詳細は、第22章「アクセス可能なADF Facesページの開発」を参照してください。

- カスタム・コンポーネントの作成: RCFを使用する独自のコンポーネントを作成できます。詳細は、第30章「カスタムADF Facesコンポーネントの作成」を参照してください。

- ユーザー・カスタマイズ: ユーザーが実行時にコンポーネントの特定の表示属性を変更できるようにページを作成できます。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- ドラッグ・アンド・ドロップ: 属性値、コレクションの値または完全なコンポーネントを1つのコンポーネントから別のコンポーネントへドラッグできるように設定できます。詳細は、第32章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

1.3 ADF Facesコンポーネント

ADF Facesコンポーネントは、通常2つのカテゴリに分けられます。レイアウト・コンポーネントは、ページのコンテンツの編成に使用されるコンポーネントです。ページのレイアウトを決めるコンテナとして機能するコンポーネント以外に、ADF Facesレイアウト・コンポーネントには、コンテンツを表示または非表示にできたり、セクション、リストまたは空の領域を提供するインタラクティブなコンテナ・コンポーネントも含めることができます。一部のレイアウト・コンポーネントでは、ページに表示されるコンポーネントのサイズと位置を決めるプロセスであるジオメトリ管理がサポートされます。RCFで、これらのコンポーネントにブラウザのサイズ変更アクティビティが通知され、これによってコンポーネントで子のサイズ変更が可能になります。これによって、特定のコンポーネントを拡大または縮小し、ブラウザの使用可能な領域を満たすことができます。JDeveloperにはビルトインのクイックスタート・レイアウトが用意されており、希望するページの外観に基づいて宣言的にレイアウト・コンポーネントをページに追加できます。レイアウト・コンポーネントとジオメトリ管理の詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。

残りのコンポーネントは、一般的なカテゴリに含まれ、次のサブカテゴリに分けることができます。

- 入力コンポーネント: ユーザーによるデータの入力と、色の選択や日付の選択などのその他の情報の入力を可能にします。ADF Facesには、ユーザーが処理するデータを選択できる簡単なリストやファイル・アップロード・コンポーネントも用意されています。入力コンポーネントの詳細は、第9章「入力コンポーネントの使用およびフォームの定義」を参照してください。

- 表およびツリー・コンポーネント: 表または展開可能なツリー形式で構造化されたデータを表示します。ADF Facesの表には、列データのソート、データのフィルタリング、行の詳細コンテンツの表示/非表示などの機能があります。ツリーには、展開/縮小動作が組み込まれています。ツリー表は、表の機能をツリーのデータ階層機能と組み合せたものです。詳細は、第10章「表およびツリーの使用」を参照してください。

- 値リスト(LOV)コンポーネント: 特定の値の検索やお気に入りとしてマークされている値の表示などの機能を含むモデルによって駆動されるリストからのユーザーによる選択を可能にします。このLOVコンポーネントは、あるオブジェクトの属性の移入に使用されるフィールドが、実際はデータベースの外部キー関係のように他のオブジェクトのリスト内に含まれる場合に有用です。詳細は、第11章「値リスト・コンポーネントの使用方法」を参照してください。

- 問合せコンポーネント: ユーザーによるデータの問合せを可能にします。ADF Facesには、2つの問合せコンポーネントが用意されています。Queryコンポーネントでは、複数の検索条件、条件の動的な追加と削除、選択可能な検索演算子、すべてに一致/いずれかに一致の選択、シード済または保存済の検索、基本または拡張モードおよび検索のパーソナライズがサポートされます。QuickQueryコンポーネントは Queryコンポーネントの簡易版で、1つのアイテム(条件)について検索できます。詳細は、第12章「問合せコンポーネントの使用方法」を参照してください。

- ポップアップ・コンポーネント: ポップアップ・ウィンドウまたはダイアログにデータを表示します。ADF Facesでのダイアログ・フレームワークには、親ページとは別の新しいポップアップ・ブラウザ・ウィンドウに表示されるプロセスのためのページの作成をサポートするインフラストラクチャが用意されています。複数のダイアログで個々の制御フローを持ちます。詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- エクスプローラ式のメニューおよびツールバー: メニュー・バーおよびツールバーの作成を可能にします。ユーザーは、メニューやツールバーを使用して、指定されたオプションのリスト(メニューの場合)またはボタン(ツールバーの場合)を選択し、アプリケーションへ変更を加えることができます。詳細は、第14章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

- カレンダ・コンポーネント: 日、週、月ごとに、またはリスト・ビューでアクティビティを表示します。ユーザーがアクティビティを作成、編集、削除できるポップアップ・コンポーネントを実装できます。詳細は、第15章「Calendarアプリケーションの作成」を参照してください。

- 出力コンポーネント: テキストおよびグラフィックを表示し、ビデオ・クリップおよびミュージック・クリップも再生できます。ADF Facesには、回転するカルーセルでグラフィックを表示できるcarousel出力コンポーネントもあります。詳細は、第16章「出力コンポーネントの使用方法」を参照してください。

- ラベル、ヒントおよびメッセージ: 他のコンポーネントのラベルやマウスを置くと表示されるヒント、エラー・メッセージを表示します。標準JSF入力コンポーネントとは異なり、メッセージをサポートするADF Facesコンポーネントでは独自のメッセージが自動的に表示されます。コンポーネントに状況依存ヘルプなどの情報を表示することもできます。詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- ナビゲーション・コンポーネント: ユーザーのあるページから次のページへの移動を可能にします。ADF Facesナビゲーション・コンポーネントには、ボタンとリンク、および異なるメニューのレベルを介してアクセスされる、より複雑な階層型のページ・フローを作成する機能が含まれます。詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照してください。

- データ視覚化コンポーネント: ユーザーによる複雑なデータのリアルタイム表示および分析を可能にします。ADFデータ視覚化コンポーネントには、グラフ、ゲージ、ピボット・テーブル、地理マップ、ガント・チャートおよび階層ビューアがあり、階層ビューアでは、組織図など、階層的なデータがリンクされたノードのセットとして表示されます。詳細は、第23章「ADFデータ視覚化コンポーネントの概要」を参照してください。

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

ADF Facesには、コンポーネントとアーキテクチャ機能のサンプルを試したり、ソース・コードを表示できるデモ・アプリケーションが含まれています。

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

デモ・アプリケーション(コードおよび実行)を表示するには、JDeveloperをインストールし、アプリケーションをダウンロードしてJDeveloper内で開きます。

ADF Facesデモ・アプリケーションは、Oracle Technology Network(OTN)Webサイトからダウンロードできます。
http://www.oracle.com/technetwork/developer-tools/adf/overview/index-092391.htmlに移動し、ADF Facesリッチ・クライアント・デモのインストールへのリンクをクリックします。表示されたページでは、アプリケーションが含まれているWARファイルをダウンロードする方法の詳細、およびアプリケーションをスタンドアロン・サーバーにデプロイする方法またはJDeveloperに含まれている統合WebLogicサーバーを使用してアプリケーションを実行する方法が説明されています。

アプリケーションをインストールしない場合には、「ADF Faces Rich Client Components Hosted Demo」リンクをクリックして、OTNから直接アプリケーションを実行できます。

1.4.2 ADF Facesデモ・アプリケーションの使用

デモ・アプリケーションには、次のものが含まれています。

- タグ・ガイド: ADF Facesコンポーネント、バリデータ、コンバータと多様なタグのデモ、および属性値の変更のコンポーネントへの影響を確認できるプロパティ・エディタ。図1-1に、selectManyCheckboxコンポーネントのデモを示します。各デモには、関連するタグ・ドキュメントへのリンクが用意されています。

図1-1 タグのデモ

- スキニング: 様々なコンポーネントのスキニングのデモ。たとえば、スタイル・セレクタの変更がコンポーネントの表示に与える影響を確認できます。図1-2に、特定のスタイル・セレクタの設定によって影響を受けるinputNumberSpinboxコンポーネントを示します。

図1-2 スキニングのデモ

- 機能デモ: ADFコンポーネントを使用するための様々な方法を紹介する各種ページ。たとえば、File Explorerは、ディレクトリ構造を表示し、ディレクトリとファイルの作成、保存、移動が可能なライブ・データ・モデルを使用したアプリケーションです。このアプリケーションは、図1-3に示すように、実際に動かすことのできるアプリケーションでADF Facesのコンポーネントと機能を紹介するためのものです。File Explorerアプリケーションの詳細は、1.4.3項「File Explorerアプリケーションの概要」を参照してください。

図1-3 File Explorerアプリケーション

その他のページでは、レイアウト・コンポーネント、AJAXポストバック機能、ドラッグ・アンド・ドロップなどのADF Facesの主なアーキテクチャ上の機能を紹介します。図1-4に、AutoSubmit属性と検証を使用するデモを示します。

図1-4 フレームワークのデモ

- ビジュアル・デザイン: コンポーネント・タイプを様々に使用して異なるUIデザインを実現するデモ。図1-5に、ツールバーの異なる外観を得る様子を示します。

図1-5 ツールバーのデザインのデモ

- Styles: インライン・スタイルとコンテンツ・スタイルの設定によってコンポーネントがいかに影響されるかのデモ。図1-6に、panelBoxコンポーネントに適用される異なるスタイルを示します。

図1-6 スタイルのデモ

- 混同されやすいコンポーネント: 同様の機能を提供するコンポーネントの比較。図1-7に、リストを表示する各コンポーネントの違いを示します。

図1-7 混同されやすいコンポーネント

1.4.3 File Explorerアプリケーションの概要

File Explorerは完全に機能するアプリケーションのため、このガイドの多くの項で、重要な点を説明したり、コード・サンプルを示すためにこのアプリケーションが使用されます。File Explorerアプリケーションのソースは、fileExplorerディレクトリにあります。

File Explorerアプリケーションでは、fileExplorerTemplateページ・テンプレートが使用されます。このテンプレートには、アプリケーションの基本的なルック・アンド・フィールを提供する多くのレイアウト・コンポーネントが含まれます。レイアウト・コンポーネントの詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。テンプレートの使用の詳細は、第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」を参照してください。

アプリケーションの左側には、図1-8に示すディレクトリ構造と結果表付きの検索フィールドの2つの領域を持つpanelAccordionコンポーネントが含まれます。

図1-8 ディレクトリ構造パネルと検索パネル

両方の領域とも、展開および縮小できます。ディレクトリ構造は、treeコンポーネントを使用して作成されています。検索領域は、入力コンポーネント、コマンド・ボタンおよびtableコンポーネントを使用して作成されています。panelAccordionコンポーネントの使用の詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。入力コンポーネントの使用の詳細は、第9章「入力コンポーネントの使用およびフォームの定義」を参照してください。コマンド・ボタンの使用の詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照してください。表とツリーの使用の詳細は、第10章「表およびツリーの使用」を参照してください。

File Explorerアプリケーションの右側では、図1-9に示すようにタブ付きペインを使用して表、ツリー表またはリストのいずれかでディレクトリの内容を表示します。

図1-9 タブ付きパネルでのディレクトリの内容

表およびツリー表にはツールバーが組み込まれ、内容の表示方法を操作できます。表のリストでは、ファイルまたはサブディレクトリをディレクトリからドラッグし、別のディレクトリにドロップできます。すべてのタブで、ファイルを右クリックし、ポップアップ・メニューからファイルのプロパティをポップアップ・ウィンドウに表示できます。タブ付きペインの使用の詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。表とツリー表のツールバーの詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。ドラッグ・アンド・ドロップの有効化の詳細は、第32章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。ポップアップ・メニューとポップアップ・ウィンドウの使用の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

File Explorerアプリケーションの上部には、図1-10に示すメニューとツールバーが含まれます。

図1-10 メニューとツールバー

メニュー・オプションでは、ファイルやディレクトリの作成と削除、コンテンツの表示方法の変更を行えます。「ヘルプ」メニューでは、図1-11に示す、ユーザーがダイアログにフィードバックを入力できるヘルプ・システムが開きます。

図1-11 ヘルプ・システム

ヘルプ・システムは、リッチ・テキスト・エディタを含む様々な入力コンポーネントを使用して作成された多くのフォームで構成されています。メニューの詳細は、14.2項「メニュー・バーでのメニューの使用方法」を参照してください。ヘルプ・システムの作成の詳細は、17.5項「コンポーネントへのヘルプの表示」を参照してください。入力コンポーネントの詳細は、第9章「入力コンポーネントの使用およびフォームの定義」を参照してください。

File Explorerのツールバー内には、ディレクトリ構造内を移動できるコントロールと、スキンを変更してアプリケーションのルック・アンド・フィールを変更できるコントロールがあります。図1-12に、簡単なスキンを使用したFile Explorerアプリケーションを示します。

図1-12 簡単なスキンを使用したFile Explorerアプリケーション

ツールバーの詳細は、14.3項「ツールバーの使用方法」を参照してください。スキンの使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

1.4.4 JDeveloperでのソース・コードの表示

ADF Facesデモ・アプリケーションのソース・ファイルはすべて1つのプロジェクト(インストール時に名前を指定して作成)に含まれています。プロジェクトは、アプリケーション・ソースとWebコンテンツの2つのディレクトリに分かれています。アプリケーション・ソースにはoracle.adfdemo.view packageが含まれ、アプリケーション全体に機能を提供するマネージドBeanを含むパッケージが含まれます。

ヒント:

コンポーネント・デモのマネージドBeanは、componentパッケージにあり、File ExplorerアプリケーションのマネージドBeanはexplorerパッケージにあります。

Webコンテンツ・ディレクトリには、JSPXファイル、JavaScriptライブラリ、イメージ、構成ファイルなどのアプリケーションで使用されるすべてのWebリソースが含まれます。

ヒント:

componentsサブディレクトリには、コンポーネント・デモのリソースが含まれます。docsディレクトリには、タグとJavadocのドキュメントが含まれます。fileExplorerディレクトリには、File Explorerアプリケーションのリソースが含まれます。

2 ADF Faces概説

この章では、JDeveloperを使用してADF Facesアプリケーションを宣言的に作成する方法について説明します。

この章では、次の項目について説明します。

- 2.1項「JDeveloperでの宣言的開発」

- 2.2項「アプリケーション・ワークスペースの作成」

- 2.3項「ページ・フローの定義」

- 2.4項「ビュー・ページの作成」

- 2.5項「EL式の作成」

- 2.6項「マネージドBeanの作成と使用」

- 2.7項「ADF Facesソース・コードおよびJavadocの表示」

2.1 JDeveloperでの宣言的開発

JDeveloper 11gをADF、JSFと組み合せて使用すると、EL式の作成や自動コンポーネント・バインディングなどのようにページやマネージドBeanを宣言的に生成できるケースが多くなります。また、ナビゲーションや構成を制御するメタデータなどのXMLメタデータが宣言的に生成されるケースも多くなります。

大まかにとらえると、ADF Facesのビュー・プロジェクトの開発プロセスは次の作業で構成されます。

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

- ページ・フローの設計

- JavaServer Pages(JSP)またはFaceletsページのいずれかを使用したページの設計および作成

- アプリケーションのデプロイ。デプロイの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework管理者ガイド』を参照してください。アプリケーションでADFモデル・レイヤー、ADFコントローラおよびADF Business ComponentsとADF Facesを組み合せて使用している場合は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「Fusion Webアプリケーションのデプロイ」を参照してください。

開発サイクル全体を通じて継続されるタスクとしては、次のものがあります。

- マネージドBeanの作成

- EL式の作成および使用

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

JDeveloperには、デバッグやテストの機能も含まれています。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFコンポーネントのテストとデバッグ」を参照してください。

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

新規アプリケーションを作成する最初のステップは、名前を割り当て、ソース・ファイルを保存するディレクトリを指定することです。JDeveloperに用意されているアプリケーション・テンプレートを使用してアプリケーションを作成すると、ワークスペースの編成と、作成するアプリケーションのタイプに必要な多くの構成ファイルおよびライブラリが自動的にプロジェクトに含められます。

2.2.1 アプリケーション・ワークスペースの作成方法

アプリケーション・ワークスペースの作成には、アプリケーションの作成ウィザードを使用します。

アプリケーションを作成する手順:

1. JDeveloperのメイン・メニューで、「ファイル」→「新規」を選択します。
新規ギャラリが開き、作成するアプリケーション・コンポーネントを選択できます。

2. 「新規ギャラリ」で「一般」ノードを展開し、「アプリケーション」→「Java EE Webアプリケーション」を選択して、「OK」をクリックします。
このテンプレートは、ビューにJSFを使用し、ビジネス・サービスにEnterprise JavaBean(EJB)セッションBeanとJava Persistence API(JPA)エンティティを使用するWebアプリケーションの作成に必要な基礎となります。アプリケーションのビジネス・レイヤー用のファイルとディレクトリはすべて、Modelというデフォルト名のプロジェクトに格納されます。ビュー・レイヤー用のファイルとディレクトリはすべて、ViewControllerというデフォルト名のプロジェクトに格納されます。

注意:

このドキュメントでは、アプリケーションでADF Facesプロジェクトを作成する方法のみを対象とし、使用するビジネス・サービスまたはこれらのサービスへのバインディングについては対象外です。ADFモデル・レイヤー、ADFコントローラおよびADF Business ComponentsとADF Facesを組み合せた使用方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』を参照してください。ADFモデル・レイヤー、EJBおよびJPAとADF Facesを組み合せた使用の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Java EE開発者ガイド』を参照してください。

3. 「Java EE Webアプリケーションの作成」ダイアログで、名前、ディレクトリの場所、および選択したパッケージ接頭辞を設定して、「次へ」をクリックします。

4. 「プロジェクトの名前付け」ページで、Webプロジェクトの名前と場所を必要に応じて変更できます。「プロジェクト・テクノロジ」タブで「ADF Faces」をダブルクリックしてこのテクノロジを選択済ペインに移動します。これによって、必要なライブラリとメタデータ・ファイルがWebプロジェクトに追加されます。「次へ」をクリックします。

5. Java設定の構成ページで、ビュー・レイヤーのパッケージ名、Javaソース・パスおよび出力ディレクトリを必要に応じて変更します。「次へ」をクリックします。

6. 「プロジェクトの名前付け」ページで、Javaプロジェクトの名前と場所を必要に応じて変更できます。Java EEに必要なライブラリとメタデータ・ファイルが、デフォルトでデータ・モデル・プロジェクトにすでに追加されています。「次へ」をクリックします。

7. Java設定の構成ページで、モデル・レイヤーのパッケージ名、Javaソース・パスおよび出力ディレクトリを必要に応じて変更します。「次へ」をクリックします。

8. 必要に応じてEJB設定を構成します。このページのヘルプを表示するには、「ヘルプ」をクリックするか、[F1]キーを押します。「終了」をクリックします。

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

Java EE Webアプリケーション・テンプレートを使用してアプリケーション・ワークスペースを作成すると、アプリケーションのビジネス・サービスに関連するすべてのソース・ファイルを含むModelという名前のプロジェクトがJDeveloperによって作成されます。EJBプロジェクトに必要なライブラリがJDeveloperで自動的に追加されます。たとえば、デフォルトのEJB設定のままの場合、JDeveloperでEJB 3.0ライブラリが追加されます。

ADF Facesビュー・レイヤー用のすべてのソース・ファイルを含むViewControllerという名前のプロジェクトもJDeveloperによって作成されます。アプリケーションに必要なJSFおよびADF構成ファイルは、JDeveloperで自動的に作成されます。また、次のライブラリがJDeveloperでビュー・プロジェクトに追加されます。

- JSF 1.2

- JSTL 1.2

- JSPランタイム

プロジェクトにJSFページを作成すると、ADF Facesおよびその他のランタイム・ライブラリが追加されます。

プロジェクトの作成後、名前を変更できます。図2-1に、新規Java EE Webアプリケーションのワークスペースを示します。

図2-1 ADFアプリケーションの新規ワークスペース

アプリケーションの作成時に選択したオプションに基づいて、JDeveloperで構成ファイルに構成パラメータも設定されます。web.xmlファイルには、JSFアプリケーションの実行に必要な構成が含まれます(ADF Facesに固有の設定は、ADF Facesコンポーネントを使用してJSFページを作成したときに追加されます)。例2-1に、Java EEアプリケーションの新規作成時にJDeveloperによって生成されるweb.xmlファイルを示します。

例2-1 生成されたweb.xmlファイル

<?xml version = '1.0' encoding = 'UTF-8'?><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>
</web-app>

特定のADF Faces機能に必要な構成は、このガイドの別の章で説明されています。たとえば、変更永続性フレームワークを使用するために必要な構成は、第31章「JSFページでのユーザー・カスタマイズの許可」で説明されています。ADF Facesアプリケーションの構成の包括的な情報は、付録A「ADF Facesの構成」を参照してください。

2.3 ページ・フローの定義

アプリケーション・ワークスペース作成後の次のステップは、通常、UIのフローを設計することです。標準JSFアプリケーションの場合と同様に、ADF Facesアプリケーションでは、ページ・フローの定義にナビゲーション・ケースとルールが使用されます。これらの定義は、faces-config.xmlファイルに格納されます。JDeveloperには、アイコンを使用してページ・フローを宣言的に定義できるダイアグラマがあります。

図2-2に、特定の顧客のデータを表示するDisplayCustomerページと、ユーザーが顧客情報を編集できるEditCustomerページの2つのページを含む簡単なページ・フロー用に作成されたナビゲーション・ダイアグラムを示します。ページの表示からページの編集へ進むナビゲーション・ルールと、ページの編集からページの表示へ戻るナビゲーション・ルールが1つずつあります。

図2-2 JDeveloperのナビゲーション・ダイアグラム

注意:

ADFモデル・データ・バインディングおよびADFコントローラを使用する場合、標準JSFナビゲーション・ルールではなく、タスク・フローを使用します。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFタスク・フローの概説」を参照してください。

ベスト・プラクティス:

ADFコントローラはJSFデフォルト・コントローラの拡張です。技術的にはアプリケーションでJSFコントローラとADFコントローラを使用できますが、いずれか一方のみを使用するようにしてください。

JSFアプリケーションでのナビゲーション機能の詳細は、http://www.oracle.com/technetwork/java/index.htmlのJava EE 5チュートリアルを参照してください。

2.3.1 ページ・フローの定義方法

ナビゲーション・ダイアグラマを使用して、JSPまたはJSPXページを使用するページ・フローを宣言的に作成します。ダイアグラマを使用すると、アプリケーションでナビゲーションが機能するために必要なXMLメタデータが、JDeveloperによってfaces-config.xmlファイルに作成されます。

注意:

このダイアグラマでは、JSPおよびJSPXファイルとして作成されるページのみサポートされます。XHTMLページのナビゲーションを作成する必要がある場合は、XMLを手動コーディングする必要があります。

ページ・フローを作成する手順:

1. アプリケーション・ナビゲータで、アプリケーションのfaces-config.xmlファイルをダブルクリックします。これは、デフォルトではWeb Content/WEB-INFノードにあります。

2. エディタ・ウィンドウで、「ダイアグラム」タブをクリックし、ナビゲーション・ダイアグラマを開きます。

3. コンポーネント・パレットが表示されない場合は、メイン・メニューから「表示」→「コンポーネント・パレット」を選択します。デフォルトでは、コンポーネント・パレットはJDeveloperの右上部に表示されます。

4. コンポーネント・パレットでドロップダウン・メニューを使用して「JSFダイアグラム・オブジェクト」を選択します。
コンポーネントが、「コンポーネント」と「注釈」の2つのアコーディオン・パネルに含まれています。図2-3に、JSFナビゲーション・コンポーネントを表示しているコンポーネント・パレットを示します。

図2-3 JDeveloperのコンポーネント・パレット

5. 使用するコンポーネントを選択し、ダイアグラムにドラッグします。
新たに追加されたコンポーネントを使用してJDeveloperでダイアグラムが再描画されます。

ヒント:

「概要」タブをクリックし、ナビゲーション・ルールとナビゲーション・ケースの作成を概要エディタで行うこともできます。概要エディタを使用したナビゲーション作成の詳細は、[F1]キーで参照できます。

また、ソース・エディタでページを直接編集して、faces-config.xmlファイルに手動で要素を追加することもできますソース・エディタにファイルを表示するには、「ソース」タブをクリックします。

アプリケーションのナビゲーションを定義したら、次はページを作成したり、ナビゲーションを使用するコンポーネントを追加したりできます。ページでのナビゲーション・コンポーネントの使用の詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照してください。

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

ページ・フローの作成にダイアグラマを使用すると、JDeveloperで関連するXMLエントリがfaces-config.xmlファイルに作成されます。例2-2に、図2-2に示すナビゲーション・ルール用に生成されたXMLを示します。

例2-2 faces-config.xmlのナビゲーション・ルール

<navigation-rule>
<from-view-id>/DisplayCustomer.jspx</from-view-id>
<navigation-case>
<from-outcome>edit</from-outcome>
<to-view-id>/EditCustomer.jspx</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>

2.4 ビュー・ページの作成

計画段階で作成したページ・フローからページ・アイコンをダブルクリックすると、実際のJSPファイルを作成できます。ADF Facesアプリケーション用のJSPを作成する場合は、*.jspファイルではなく、XMLベースのJSPドキュメント(拡張子*.jspxを使用)の作成を選択できます。

ベスト・プラクティス:

XMLベースのドキュメントの使用には、次の利点があります。

- ページがUIコンポーネント・タグのツリーとして整理されるため、ページの処理が簡素化します。

- Javaコードとコンポーネント・タグの混在を防げます。

- ドキュメント作成やレポート監査のためのページの解析が容易になります。

アプリケーションでJSPではなくFaceletsを使用する場合は、かわりにXHTMLファイルを作成できます。Faceletsは、JSPエンジンを使用する際の代替方法となる、JSF中心の宣言XMLビュー定義テクノロジです。

ベスト・プラクティス:

次のものを利用するには、Faceletsを使用します。

- FaceletsレイヤーはJSF専用に作成されているため、タグのコンパイルおよび実行時のオーバーヘッドの軽減とパフォーマンスの向上が実現します。

- Faceletsは、JSF 2.0の主ビュー定義テクノロジとみなされます。

- さらなるパフォーマンスの向上はFaceletsでしか得られません。

ADF Facesには、ページ全体のレイアウトを定義する際に使用可能なコンポーネントが多数用意されています。JDeveloperには、これらのコンポーネントを使用した事前定義済のクイック・スタート・レイアウトが含まれており、すばやく簡単にレイアウトを正しく構築できます。1列、2列または3列のレイアウトから選択でき、列の動作を指定できます。たとえば、1つの列の幅はロックし、他の列は拡大してブラウザの使用可能な領域を埋めることができます。図2-4に、2番目の列が2つのペインに分割されている2列レイアウトで使用可能なクイック・スタート・レイアウトを示します。レイアウト・コンポーネントの詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。

図2-4 クイック・レイアウト

レイアウト・コンポーネントの追加に加えて、テーマを適用してクイック・レイアウトを選択することもできます。これらのテーマにより、クイック・スタート・レイアウトで使用するコンポーネントの一部に色のスタイルが追加されます。色および色の追加場所を確認するには、付録E「クイック・スタート・レイアウト・テーマ」を参照してください。テーマの詳細は、20.3.4項「コンポーネントへのテーマの適用方法」を参照してください。

同じレイアウトをアプリケーションの多くのページで使用する場合には、ADF Facesでは事前定義済ページ・テンプレートを作成および使用できます。テンプレートを作成する場合、テンプレートの開発者はテンプレートを使用するページのレイアウトを決定する(図2-4に示すようにクイック・レイアウト・デザインから選択するか手動で構築します)だけではなく、すべてのページに表示される静的コンテンツを含めたり、各ページで有効な値に置き換えられるプレースホルダ属性を作成できます。たとえば、ADF FacesにはOracle Three-Column-Layoutテンプレートが含まれています。このテンプレートには、図2-5に示すように、ブランド、ヘッダー、著作権情報などの特定のコンテンツ用の領域が含まれ、静的ロゴおよびビジー状態のアイコンも表示されます。

図2-5 Oracle3列レイアウト・テンプレート

テンプレートにレイアウトなどの変更を加えるたびに、テンプレートを使用するページも自動的に更新されます。テンプレートの作成と使用の詳細は、19.3項「ページ・テンプレートの使用」を参照してください。

JSFページを作成する際、ページに関連するバッキングBeanも作成するよう選択できます。バッキングBeanを使用すると、ページ上のコンポーネントにプログラムからアクセスできます。バッキングBeanとJSF JSPページの使用の詳細は、2.4.3項「自動コンポーネント・バインディングについて」を参照してください。

ベスト・プラクティス:

プログラムからのアクセスや処理が必要なコンポーネントを含むページについてのみバッキングBeanを作成します。リスナーなど、コンポーネント属性のEL式を使用してアクセスする追加機能を提供するのみ場合は、かわりにマネージドBeanを使用します。

ページをモバイル機器で表示可能にすることを選択できます。ページ・ファイルを作成した後は、そのファイルにUIコンポーネントを追加したり、そのページのソースを操作することができます。

2.4.1 JSF JSPページの作成方法

JSF JSPページの作成には、「JSFページの作成」ダイアログを使用します。

JSF JSPページを作成する手順:

1. アプリケーション・ナビゲータで、ページを保存するディレクトリを右クリックし、「新規」を選択ます。「新規ギャラリ」で「Web層」ノードを展開し、「JSF」→「JSFページ」を選択して、「OK」をクリックします。
または

ナビゲーション・ダイアグラムから、まだ作成されていないページのページ・アイコンをダブルクリックします。

2. 「JSFページの作成」ダイアログに従って操作を進めます。ヘルプを参照するには、ダイアログで「ヘルプ」をクリックします。バッキングBeanと関連するバインディングの自動作成に使用できる「ページの実装」オプションの詳細は、2.4.3項「自動コンポーネント・バインディングについて」を参照してください。

2.4.2 JSF JSPページを作成する場合の処理

「JSFページの作成」ダイアログを使用してJSFページを作成すると、JDeveloperによって物理ファイルが作成され、必要なコードがファイル内に追加されます(コンポーネント・ライブラリをインポートし、ページを表示するためのコード)。作成されるコードは、.jspxドキュメントを作成するよう選択したかどうかによって異なります。例2-3に、JDeveloperで最初に作成されたときの.jspxページを示します。

例2-3 JDeveloperで作成された宣言ページ・ソース

<?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:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>
</jsp:root>

クリック・レイアウトのいずれかの使用を選択した場合にも、JDeveloperによってレイアウト表示に必要なコンポーネントが追加されます。例2-4に、2列レイアウトを選択した場合に生成されるコードを示します(1列目はロックされており、2列目はブラウザの利用可能な領域全体に拡大され、テーマの適用も選択します)。

図2-4 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:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document id="d1">
<af:form id="f1">
<af:panelStretchLayout startWidth="100px" id="psl1">
<f:facet name="start"/>
<f:facet name="center">
<!-- id="af_twocol_left_sidebar_stretched"   -->
<af:decorativeBox theme="dark" id="db2">
<f:facet name="center">
<af:decorativeBox theme="medium" id="db1">
<f:facet name="center"/>
</af:decorativeBox>
</f:facet>
</af:decorativeBox>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>
</jsp:root>

ダイアログの「ページの実装」セクションを使用してバッキングBeanを自動作成するよう選択した場合は、そのページ用のバッキングBeanも作成および登録され、既存のコンポーネントがそのBeanにバインドされます。例2-5に、ページのバッキングBean用に作成されたコードを示します。

例2-5 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ランタイム

- Oracle JEWT

- ADF DVT Facesデータバインディング・ランタイム

また、例2-6に示すように、JDeveloperによってエントリがweb.xmlファイルに追加されます。

例2-6 JSF JSPページの作成後のweb.xmlファイルのコード

<?xml version = '1.0' encoding = 'UTF-8'?>
<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">
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<param-name>oracle.adf.view.rich.versionString.HIDDEN</param-name>
<param-value>false</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>
</filter-mapping>
<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.adfinternal.view.faces.bi.renderkit.graph.GraphServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>BIGAUGESERVLET</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.gauge.GaugeServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>MapProxyServlet</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.geoMap.servlet.MapProxyServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>GatewayServlet</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.graph.FlashBridgeServlet
</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>
<servlet-mapping>
<servlet-name>GatewayServlet</servlet-name>
<url-pattern>/flashbridge/*</url-pattern>
</servlet-mapping>
</web-app>

JSF JSPページを作成すると、例2-7のようなADF Facesのデフォルト・レンダー・キット(HTMLクライアントでのコンポーネントの表示に使用)を定義するエントリがJDeveloperによってfaces-config.xmlファイルに作成されます。

例2-7 生成されたfaces-config.xmlファイル

<?xml version="1.0" encoding="UTF-8"?>
<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>

例2-8のようなtrinidad-config.xmlファイルのエントリによって、アプリケーションのユーザー・インタフェース(UI)コンポーネントで使用されるデフォルト・スキンが定義されます。

例2-8 生成されたtrinidad-config.xmlファイル

<?xml version="1.0" encoding="UTF-8"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>fusion</skin-family>
</trinidad-config>

ページがJDeveloperに初めて表示される場合、ビジュアル・エディタ(「設計」タブをクリックしてアクセス)に表示され、WYSIWYG環境でページを見ることができます。「ソース」タブをクリックして、ページのソースをソース・エディタに表示することもできます。JDeveloperの左下部にある構造ウィンドウには、ページが階層形式で表示されます。

2.4.3 自動コンポーネント・バインディングについて

バッキングBeanは、JSPページのUIコンポーネントのロジックとプロパティを含むマネージドBeanです(マネージドBeanの詳細は、2.6項「マネージドBeanの作成と使用」を参照してください)。JSF JSPページを作成する際、「JSFページの作成」ダイアログの「ページの実装」オプションの選択肢の1つを選択してUIコンポーネントを自動的に公開するよう選択すると、JDeveloperでページのバッキングBeanが自動的に作成(または、選択したマネージドBeanが使用)されます。ページに追加するコンポーネントごとに、JDeveloperでそのコンポーネントのBeanプロパティが挿入され、binding属性を使用してコンポーネント・インスタンスとそのプロパティがバインドされて、Beanでコンポーネント・インスタンスを受け入れたり、返すことができます。

自動コンポーネント・バインディングを使用すると、具体的にはJDeveloperで次の処理が行われます。

- JSPまたはJSPXファイルと同じ名前を使用してJavaBeanを作成し、view.backingパッケージに含めます(JDeveloperでバッキングBeanを作成するよう選択した場合)。

- バッキングBeanのマネージドBeanエントリがfaces-config.xmlファイルに作成されます。デフォルトでは、マネージドBeanの名前はbacking_<page_name>で、Beanはrequestスコープを使用します(スコープの詳細は、4.6項「オブジェクト・スコープ・ライフサイクル」を参照)。

注意:

JDeveloperでは、マネージドBeanのプロパティ・エントリはfaces-config.xmlファイルに作成されません。特定のプロパティ値でBeanをインスタンス化する場合、この構成をfaces-config.xmlファイルに手動で行う必要があります。詳細は、A.3.1項「faces-config.xmlでのADF Facesの構成方法」を参照してください。

- 新たに作成または選択されたBeanの場合、JSPにあるコンポーネント・タグごとにプロパティとアクセッサ・メソッドが追加されます。JDeveloperでバインディング属性の値としてEL式を使用し、コンポーネント・タグとそのプロパティがバインドされます。

- ページから削除されたコンポーネントのプロパティとメソッドが削除されます。

JSPページが作成され、コンポーネントが追加された後、ビジュアル・エディタでコンポーネントをダブルクリックして、それらを使用するコンポーネントにメソッド・バインディング式を宣言的に追加できます(これによりエディタが起動し、属性をバインドするマネージドBeanとメソッドを選択できます)。JSPに自動コンポーネント・バインディングが使用されている場合、コンポーネントをダブルクリックすると、コンポーネントがバインドされる可能性のあるスケルトン・メソッドが、ページのバッキングBeanに自動的に作成されます。たとえば、コマンド・ボタン・コンポーネントを追加し、ビジュアル・エディタでこれをダブルクリックすると、「バインドActionプロパティ」ダイアログにページのバッキングBeanと新しいスケルトン・アクション・メソッドが、図2-6に示すように表示されます。

図2-6 「バインドActionプロパティ」ダイアログ

これらのメソッドから選択するか、新しいメソッド名を入力すると、JDeveloperでページのバッキングBeanに新規スケルトン・メソッドが自動的に作成されます。その後、メソッドにロジックを追加する必要があります。

注意:

JSPに自動コンポーネント・バインディングが使用されていない場合、バインディングを作成するには、既存のマネージドBeanを選択するか、新規のバッキングBeanを作成する必要があります。

たとえば、myfile.jspxというファイル名でJSPを作成したとします。JDeveloperによるデフォルトのバッキングBeanの自動作成を選択した場合は、JDeveloperによって、view.backing.Myfile.javaというバッキングBeanが作成され、ViewControllerプロジェクトの\srcディレクトリに配置されます。このバッキングBeanはfaces-config.xmlでマネージドBeanとして構成され、デフォルトのマネージドBean名はbacking_myfileとなります。

例2-9に、自動コンポーネント・バインディングを使用し、form、inputTextおよびcommandButtonコンポーネントを含むJSPのコードを示します。

例2-9 自動コンポーネント・バインディングを使用する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.inputText1}"
id="inputText1"/>
<af:commandButton text="commandButton 1"
binding="#{backing_MyFile.cb1}"
id="cb1"/>
</af:form>
</af:document>
</f:view>

例2-10に、対応するバッキングBeanのコードを示します。

例2-10 自動コンポーネント・バインディングを使用するバッキング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.RichCommandButton;

public class MyFile {
private RichForm f1;
private RichDocument d1;
private RichInputText inputText1;
private RichCommandButton cb1;

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 inputText1) {
this.inputText1 = inputText1;
}

public RichInputText getInputText1() {
return inputText1;
}

public void setCb1(RichCommandButton cb1) {
this.commandButton1 = commandButton1;
}

public RichCommandButton getCb1() {
return cb1;
}

public String cb1_action() {
// Add event code here...
return null;
}
}

例2-11に、ページのバッキングBeanをマネージドBeanとして登録するようfaces-config.xmlファイルに追加されたコードを示します。

例2-11 バッキング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>

また、JSPのバッキングBeanであるJavaファイルを編集する際、メソッド・バインディング・ツールバーがソース・エディタに表示され、選択したページのコンポーネントに適切なメソッドを迅速かつ容易にバインドできます。イベントを選択すると、JDeveloperで図2-7に示すようなイベントのスケルトン・メソッドが作成されます。

図2-7 ソース・エディタでのスケルトン・メソッドの宣言的作成

ページの作成後、自動コンポーネント・バインディングの有効/無効の切替えが可能になり、バッキングBeanを別のJavaクラスに変更することもできます。ビジュアル・エディタでJSPを開き、JDeveloperのメニューから、「設計」→「ページ・プロパティ」を選択します。ここで、「自動バインド」オプションを選択または選択解除し、マネージドBeanのクラスを変更できます。ダイアログの使用の詳細が必要な場合は、「ヘルプ」をクリックします。

注意:

自動バインドを無効にした場合、ページでバインドされている既存のコンポーネントのバインド属性は変わりません。自動バインドを有効にした場合、バインドされているすべての既存のコンポーネントと新たに挿入するコンポーネントが、選択したマネージドBeanにバインドされます。自動バインドが有効で、マネージドBeanの選択を変えた場合、既存のすべてのバインディングと新規バインディングが新しいBeanに切り替わります。

JSPのバッキングBeanには、ページを右クリックして「移動先」を選択し、JSPに関連付けられているBeanのリストからBeanを選択することで、ページ・エディタからいつでもアクセスできます。

2.4.4 Facelets XHTMLページの作成方法

XHTMLファイルを作成するには、「Faceletページの作成」ダイアログを使用します。

XHTMLページを作成する手順:

1. アプリケーション・ナビゲータで、ページを保存するディレクトリを右クリックし、「新規」を選択ます。「新規ギャラリ」でWeb層ノードを展開し、「Facelets」→「Faceletページ」を選択して、「OK」をクリックします。

ヒント:

Faceletsがリストされているテクノロジでない場合は、「新規ギャラリ」の「すべてのテクノロジ」タブをクリックします。

2. 「Faceletページの作成」ダイアログを完了します。ヘルプを参照するには、ダイアログで「ヘルプ」をクリックします。

2.4.5 JSF XHTMLページを作成する場合の処理

「Faceletページの作成」ダイアログを使用してXHTMLページを作成すると、JDeveloperによって物理ファイルが作成され、コンポーネント・ライブラリのインポートとページの表示に必要なコードが追加されます。例2-3に、JDeveloperで最初に作成されたときの.xthmlページを示します。

例2-12 JDeveloperで作成された宣言ページ・ソース

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EE"
"http://www.w3.org/TR/xhtml1/DTD/xhtall-transitional.dtd">
<f:view xmlns="http://www.w3.org/1999/xhtml"
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">
<af:document>
<af:form/>
</af:document>
</f:view>

また、次のライブラリがJDeveloperでビュー・プロジェクトに追加されます。

- Faceletsランタイム

- ADF Facesランタイム11

- ADF Commonランタイム

- ADF DVT Facesランタイム

- Oracle JEWT

- ADF DVT Facesデータバインディング・ランタイム

また、例2-13に示すように、JDeveloperによってエントリがweb.xmlファイルに追加されます。

例2-13 JSF XHTMLページの作成後のweb.xmlファイルのコード

<?xml version = '1.0' encoding = 'UTF-8'?>
<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">
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<param-name>oracle.adf.view.rich.versionString.HIDDEN</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.FACELETS_VIEW_MAPPINGS</param-name>
<param-value>*.xhtml</param-value>
</context-param>
<context-param>
<param-name>facelets.SKIP_XML_INSTRUCTIONS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER</param-name>
<param-value>
org.apache.myfaces.trinidadinternal.facelets.TrinidadFaceletViewHandler
</param-value>
</context-param>
<context-param>
<param-name>facelets.DEVELOPMENT</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>facelets.SKIP_COMMENTS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>facelets.DECORATORS</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator
</param-value>
</context-param>
<context-param>
<param-name>facelets.RESOURCE_RESOLVER</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver
</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>
</filter-mapping>
<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.adfinternal.view.faces.bi.renderkit.graph.GraphServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>BIGAUGESERVLET</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.gauge.GaugeServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>MapProxyServlet</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.geoMap.servlet.MapProxyServlet
</servlet-class>
</servlet>
<servlet>
<servlet-name>GatewayServlet</servlet-name>
<servlet-class>
oracle.adfinternal.view.faces.bi.renderkit.graph.FlashBridgeServlet
</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>
<servlet-mapping>
<servlet-name>GatewayServlet</servlet-name>
<url-pattern>/flashbridge/*</url-pattern>
</servlet-mapping>
</web-app>

例2-14に示すように、ビュー・ハンドラのfaces-config.xmlファイルにもエントリが作成されます。

例2-14 XHTMLページで生成されたfaces-config.xmlファイル

<?xml version="1.0" encoding="UTF-8"?>
<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>

例2-15のようなtrinidad-config.xmlファイルのエントリによって、アプリケーションのユーザー・インタフェース(UI)コンポーネントで使用されるデフォルト・スキンが定義されます。

例2-15 生成されたtrinidad-config.xmlファイル

<?xml version="1.0" encoding="UTF-8"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>fusion</skin-family>
</trinidad-config>

ページがJDeveloperに初めて表示される場合、ビジュアル・エディタ(「設計」タブをクリックしてアクセス)に表示され、WYSIWYG環境でページを見ることができます。「ソース」タブをクリックして、ページのソースをソース・エディタに表示することもできます。JDeveloperの左下部にある構造ウィンドウには、ページが階層形式で表示されます。

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

ページの作成後、コンポーネント・パレットを使用して、コンポーネントをページにドラッグ・アンド・ドロップできます。コンポーネントを追加すると、必要なページ・コードが宣言的に自動追加され、各コンポーネント属性に既定の値が設定されます。

ヒント:

特定のADF Facesコンポーネントの追加および使用の詳細は、第III部「ADF Facesコンポーネントの使用」を参照してください。

注意:

ADF FacesコンポーネントとMyFaces Trinidadコンポーネント(tr:タグ)または他のAJAX対応ライブラリ・コンポーネントは同じページで使用できません。Trinidad HTMLタグ(trh:)はADF Facesコンポーネントと同じページで使用できますが、ブラウザ・レイアウトに問題が生じる場合があります。常にADF Facesコンポーネントのみを使用してレイアウトを実現するように試みてください。

ADF Facesコンポーネントを使用して作成したページと他のコンポーネントを使用して作成したページはアプリケーションに混在できることに注意してください。

ADF Facesコンポーネントをページに追加する手順:

1. アプリケーション・ナビゲータで、JSFページをダブルクリックし、エディタでそれを開きます。

2. コンポーネント・パレットが表示されない場合は、メニューから「表示」→「コンポーネント・パレット」を選択します。デフォルトでは、コンポーネント・パレットはJDeveloperの右上部に表示されます。

3. コンポーネント・パレットでドロップダウン・メニューを使用して「ADF Faces」を選択します。
コンポーネントが、「共通コンポーネント」、「レイアウト」および「操作」の3つのアコーディオン・パネルに含まれています。図2-8に、ADF Facesの共通コンポーネントを表示しているコンポーネント・パレットを示します。

図2-8 JDeveloperのコンポーネント・パレット

4. 使用するコンポーネントを選択し、ページにドラッグします。
新たに追加されたコンポーネントを使用して、JDeveloperでビジュアル・エディタのページが再描画されます。ビジュアル・エディタでは、ページのコンポーネントを直接選択し、ポップアップ・メニューを使用してコンポーネントを追加できます。図2-9に、ビジュアル・エディタのページを示します。

図2-9 ビジュアル・エディタに表示されるページ

ヒント:

コンポーネントをパレットから構造ウィンドウに、またはソース・エディタのコードに直接ドラッグ・アンド・ドロップできます。

ソース・エディタでページを直接編集することで、いつでもコンポーネントを追加できます。ソース・エディタにページを表示するには、ウィンドウ下部の「ソース」タブをクリックします。

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

コンポーネントをコンポーネント・パレットからJSFページにドラッグ・アンド・ドロップすると、対応するコードがJSFページに自動的に追加されます。このコードには、コンポーネントのレンダリングに必要なタグと一部のコンポーネント属性の値が含まれます。例2-16に、入力テキスト・コンポーネントとボタン・コンポーネントをパレットからドロップした場合のコードを示します。

例2-16 JDeveloperでJSFページに宣言的に追加されるタグ

<af:inputText label="Label 1" id="it1"/>
<af:commandButton text="commandButton 1" id="cb"/>

注意:

自動コンポーネント・バインディングを使用するよう選択した場合、ページのバッキングBeanの対応するプロパティに値がバインドされたbinding属性もJDeveloperによって追加されます。詳細は、2.4.3項「自動コンポーネント・バインディングについて」を参照してください。

必須である子コンポーネントを含むコンポーネント(表、リストなど)をドロップすると、JDeveloperでウィザードが起動され、親と各子コンポーネントを定義できます。図2-10に、表コンポーネントと表の子である列コンポーネントの作成に使用する表ウィザードを示します。

図2-10 JDeveloperの表ウィザード

例2-17に、ウィザードを使用して3つの列を持つ表を作成した場合に作成されるコードを示します。各列はデータの表示にoutputTextを使用します。

例2-17 表コンポーネントの宣言コード

<af:table var="row" 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>

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

コンポーネントのページへのドロップ後、プロパティ・インスペクタ(デフォルトではJDeveloperの右下部に表示)を使用して、各コンポーネントの属性値を設定できます。

ヒント:

プロパティ・インスペクタが表示されない場合は、メイン・メニューから「表示」→「プロパティ・インスペクタ」を選択します。

図2-11に、inputTextコンポーネントの属性を表示しているプロパティ・インスペクタを示します。

図2-11 JDeveloperのプロパティ・インスペクタ

プロパティ・インスペクタには、同様のプロパティをグループにしたセクションがあります。たとえば、プロパティ・インスペクタでは、inputTextによく使用される属性は「共通」セクションにまとめられ、コンポーネントの動作に影響するプロパティは「動作」セクションにまとめられています。図2-12に、inputTextコンポーネントのプロパティ・インスペクタの「動作」セクションを示します。

図2-12 プロパティ・インスペクタの「動作」セクション

コンポーネント属性の設定手順:

1. ビジュアル・エディタ、構造ウィンドウ、またはソース・エディタでのタグの直接選択で、コンポーネントを選択します。

2. プロパティ・インスペクタで、設定する属性が含まれるセクションを開きます。

ヒント:

一部の属性は、複数のセクションに表示されます。あるセクションで値を入力または変更すると、他のセクションでもその値が変更されます。インスペクタの最上部の検索フィールドに属性名を入力して、属性を検索できます。

3. フィールドに値を直接入力するか、フィールドにドロップダウン・リストがある場合はそのリストを使用して、値を選択します。フィールドの右側にあるドロップダウンを使用することもできます(値の設定に使用するツールを含むポップアップが起動します)。これらのツールは、特定のプロパティ・エディタ(「編集」を選択して開く)、またはEL式を作成して値を求めるのに使用できる式ビルダー(「式ビルダー」を選択して開く)です。式ビルダーの使用の詳細は、2.5項「EL式の作成」を参照してください。このポップアップには、図2-13のように、プロパティの説明も表示されます。

図2-13 プロパティのツールおよびヘルプ

2.4.9 プロパティ・インスペクタを使用する場合の処理

プロパティ・インスペクタを使用して属性値を設定または変更すると、入力された値に合致するよう、属性のページ・ソースがJDeveloperで自動的に変更されます。

ヒント:

ソース・エディタでページを直接編集することで、いつでも属性値を変更できます。ソース・エディタにページを表示するには、ウィンドウ下部の「ソース」タブをクリックします。

2.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の作成と使用の詳細は、2.6項「マネージドBeanの作成と使用」を参照してください。EL式の詳細は、http://www.oracle.com/technetwork/java/index.htmlのJava EE 5チュートリアルを参照してください。

2.5.1 EL式の作成方法

JDeveloperの式ビルダーを使用してEL式を宣言的に作成できます。ビルダーにはプロパティ・インスペクタからアクセスできます。

式ビルダーの使用手順:

1. プロパティ・インスペクタで変更する属性を特定し、右端のドロップダウン・メニューを使用して「式ビルダー」を選択します。

2. 次の機能を使用して式を作成します。

- 「変数」ツリーを使用して、式に含める項目を選択します。ツリーには階層形式のバインディング・オブジェクトが含まれます。ツリーの各アイコンは、式で使用できる各種タイプのバインディング・オブジェクトを表します。
ツリーの絞り込みには、ドロップダウン・フィルタを使用するか、検索フィールドに検索条件を入力します。ADF Facesで公開されているELでアクセス可能なオブジェクトは、図2-14に示すように、「JSFマネージドBean」ノードの「adfFacesContext」ノードにあります。

図2-14 式ビルダーでのadfFacesContextオブジェクト

ヒント:

これらのオブジェクトの詳細は、ADF FacesのJavadocを参照してください。

ツリーで項目を選択すると、その項目がEL式内の「式」ボックスに移動されます。「式」ボックスに式を直接入力することもできます。

- 演算子ボタンを使用して、式に論理演算子または算術演算子を追加します。

図2-15に、explorerマネージドBeanのlabelプロパティにコンポーネントのラベルの値をバインドする式の作成に使用される「式ビルダー」ダイアログを示します。

図2-15 「式ビルダー」ダイアログ

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

必要なEL式はJDeveloperで作成され、作成されない式は式ビルダーを使用して作成できますが、マネージドBean内でEL式にアクセスしたり、EL式を設定または起動する必要がある場合もあります。

例2-18に、EL式への参照を取得し、適合するオブジェクトを返す(または作成する)方法を示します。

例2-18マネージド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);
}

例2-19に、メソッド式を解決する方法を示します。

例2-19 マネージド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);
}

例2-20に、マネージドBeanで新たにオブジェクトを設定する方法を示します。

例2-20 マネージド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);
}
}

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

マネージドBeanは、様々な構成ファイルを使用してアプリケーションに登録するJavaクラスです。JSFアプリケーションを起動すると、これらの構成ファイルが解析されて、Beanが使用可能になり、EL式での参照やBeanのプロパティおよびメソッドへのアクセスが可能になります。マネージドBeanの最初の参照時にBeanが存在しない場合、マネージドBean作成機能によってBeanのデフォルト・コンストラクタ・メソッドがコールされ、Beanがインスタンス化されます。また、プロパティが宣言されると、宣言されたデフォルトの値が移入されます。

多くの場合、マネージドBeanは、フロントエンドで処理することが最適なイベントやデータ操作を処理します。標準JSFアプリケーションでのマネージドBeanの使用方法の詳細は、http://www.oracle.com/technetwork/java/index.htmlのJava EE 5チュートリアルを参照してください。

ベスト・プラクティス:

たとえば、現在のユーザーで、マネージドBeanを使用して「経理」情報のみを格納します。すべてのアプリケーション・データと処理は、アプリケーションのビジネス・レイヤーのロジックで処理される必要があります。

標準JSFアプリケーションでは、マネージドBeanはfaces-config.xml構成ファイルに登録されます。

注意:

ADFモデル・データ・バインディングおよびADFコントローラを使用する場合は、faces-config.xmlファイルではなく、ADFタスク・フローにマネージドBeanを登録する必要があります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「Fusion WebアプリケーションでのマネージドBeanの使用」を参照してください。

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

faces-config.xmlファイルに概要エディタを使用して、マネージドBeanの作成とJSFアプリケーションへの登録を同時に行えます。

マネージドBeanの作成および登録手順:

1. アプリケーション・ナビゲータで、faces-config.xmlファイルを開きます。

2. エディタ・ウィンドウで、「概要」タブをクリックします。

3. 概要エディタで、「マネージドBean」タブをクリックします。
図2-16に、File Explorerアプリケーションを含むADF Facesのデモで使用されるfaces-config.xmlファイルの場合のエディタを示します。

図2-16 faces-config.xmlファイル内のマネージドBean

4. 「追加」アイコンをクリックして「マネージドBean」表に行を追加します。

5. 「マネージドBeanの作成」ダイアログで値を入力します。ダイアログの使用の詳細が必要な場合は、「ヘルプ」をクリックします。JDeveloperでクラス・ファイルを作成する場合は、「クラスが存在しない場合は生成」オプションを選択します。

注意:

マネージドBeanを登録するスコープまたは値を格納するスコープを決める場合、次の点に注意してください。

- 可能なかぎり、狭いスコープを常に使用するようにします。

- マネージドBeanがコンポーネント・インスタンスを受け取り、返すことにより、コンポーネント・バインディングに参加する場合(つまり、ページのUIコンポーネントがbinding属性を使用してBeanのコンポーネント・プロパティにバインドする場合)は、マネージドBeanをrequestまたはbackingBeanスコープに格納する必要があります。これらのスコープのいずれかに格納できない場合(たとえば、高可用性の理由によりsessionスコープに格納する必要がある場合)は、ComponentReference APIを使用する必要があります。詳細は、2.6.3項「コンポーネント・バインディングおよびマネージドBeanについて」を参照してください。

- sessionスコープは、セッション全体に関連する情報(ユーザー情報やコンテキスト情報など)にのみ、または高可用性の理由により使用します。ページ間で値を渡すためにsessionスコープを使用しないでください。

異なるオブジェクト・スコープの詳細は、4.6項「オブジェクト・スコープ・ライフサイクル」を参照してください。

6. オプションでBeanに管理プロパティを追加できます。Beanがインスタンス化される際、指定した値が管理プロパティに設定されます。「Managed Bean」表でBeanを選択した状態で「新規」アイコンをクリックし、「管理プロパティ」表に行を追加します。プロパティ・インスペクタで、プロパティ名を入力します(他のフィールドはオプションです)。

注意:

このエディタを使用して管理プロパティを宣言できますが、対応するコードはJavaクラスに生成されません。適切なタイプのプライベート・メンバー・フィールドを作成し、コード・エディタのポップアップ・メニューの「アクセッサの生成」メニュー項目を選択して、これらのBeanプロパティに対応するgetおよびsetメソッドを生成することにより、コードを追加する必要があります。

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

マネージドBeanを作成する際、Javaファイルを生成するよう選択すると、指定された名前とデフォルト・コンストラクタを使用してスタブ・クラスが自動的に作成されます。例2-21に、viewパッケージに格納されたMyBeanクラスに追加されるコードを示します。

例2-21 マネージド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要素の追加も行われます。例2-22に、MyBeanクラスに作成されるmanaged-bean要素を示します。

例2-22 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>

2.6.3 コンポーネント・バインディングおよびマネージドBeanについて

マネージドBeanに関する問題を回避するには、Beanでコンポーネント・バインディングを使用する必要がある場合(コンポーネントのbinding属性を使用)、Beanをrequestスコープに格納する必要があります。(アプリケーションでFusionテクノロジ・スタックを使用する場合は、backingBeanスコープに格納する必要があります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のFusion WebアプリケーションでのマネージドBeanの使用に関する項を参照してください。)ただし、BeanをrequestまたはbackingBeanスコープに格納できない状況が発生する場合もあります。たとえば、sessionスコープに格納されているマネージドBeanがあり、クラスタ環境にデプロイできるため、シリアライズ可能なインタフェースを実装する必要があるとします。これらがシリアライズ可能な場合、リクエスト時に変更されるマネージドBeanは、他のサーバーに分散してフェイルオーバーできます。ただし、ADF Facesコンポーネント(一般的にはJSFコンポーネント)はシリアライズできません。このため、シリアライズされたマネージドBeanがコンポーネント・バインディングを使用してコンポーネントにアクセスしようとすると、参照コンポーネントはシリアライズできないため、Beanのシリアライズは失敗します。ADF Facesコンポーネントはスレッド・セーフではないため、シリアライズされたマネージドBeanにバインドされたコンポーネントに関するスレッドの安全性の問題も発生します。

UIコンポーネント・インスタンスへのコンポーネント参照を、requestまたはbackingBeanスコープを使用していないバッキングBeanに格納する必要がある場合は、Trinidad ComponentReference APIを使用して、コンポーネント・インスタンスへの参照を格納する必要があります。UIComponentReference.newUIComponentReference()メソッドでは、現在のページでUIComponentインスタンスを取得するのに使用可能な、シリアライズされた参照オブジェクトが作成されます。例2-23に、マネージドBeanがUIComponentReference APIを使用して検索フィールドの値をどのように取得および設定するかを示します。

例2-23 セッション有効範囲のマネージドBeanによるUIComponentReference APIの使用

...
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を参照してください。

2.7 ADF Facesソース・コードおよびJavadocの表示

ADF Faces Javadocは、JDeveloperから直接表示できます。

クラスのJavadocを表示する手順:

1. メイン・メニューから、「ナビゲート」→「Javadocに移動」を選択します。

2. 「Javadocに移動」ダイアログで、表示するクラス名を入力します。名前が正確にわからない場合、名前を入力し始めると、JDeveloperによって名前が合致するクラスのリストが表示されます。ADF Facesコンポーネントは、oracle.adf.view.richパッケージにあります。

ヒント:

Javaクラス・ファイルでは、カーソルを名前または関数の上に置いて、[Ctrl]を押しながら[D]を押すと、Javadocのクラス名参照またはJavaScript関数コールに直接移動できます。

第II部

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

第II部には、次の章が含まれています。

- 第3章「ADF Facesアーキテクチャの使用」

- 第4章「ADF FacesによるJSFライフサイクルの使用」

- 第5章「イベントの処理」

- 第6章「入力の検証および変換」

- 第7章「部分ページ・コンテンツの再レンダリング」

3 ADF Facesアーキテクチャの使用

この章では、ADF Facesクライアント側アーキテクチャの主な機能について説明します。

この章では、次の項目について説明します。

- 3.1項「ADF Facesアーキテクチャの使用の概要」

- 3.2項「クライアント・イベントのリスニング」

- 3.3項「JavaScriptのページへの追加」

- 3.4項「クライアント側コンポーネントのインスタンス化」

- 3.5項「ページでのクライアント・コンポーネントの検索」

- 3.6項「ユーザーの現在位置の特定」

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

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

- 3.9項「レンダリングおよび可視性の理解」

3.1 ADF Facesアーキテクチャの使用の概要

ADF Facesリッチ・クライアント・フレームワーク(RCF)には、AJAXタイプの機能をWebアプリケーションに作成するために必要な機能が多く用意されており、すべてフレームワークに組み込まれています。RCFの基本は、クライアント側コンポーネント・モデルにあまり移入されないことです。クライアント・コンポーネントは、必要な場合にのみ存在しますが、これは、clientListenerハンドラが登録されている場合、あるいはページ開発者がクライアント側のコンポーネントと対話する必要があり、クライアント・コンポーネントが使用できるように構成してある場合のいずれかです。

クライアント・コンポーネントが存在する主な理由は、フレームワークおよび開発者に対するAPI規定を提供することです。クライアント側コンポーネントは、イベント処理がサポートされる簡単なプロパティ・コンテナとみなすことができます。クライアント・コンポーネントは、状態を格納し、APIを提供するためにのみ存在するため、Document Object Model(DOM)と直接対話しません。DOMとのすべての対話は、ピアと呼ばれる媒介を使用して行われます。フレームワークの内部動作の大部分は、意識する必要がありません。JDeveloperとADF Facesを組み合せて使用すると、アーキテクチャ上の機能の多くを宣言して使用でき、コードを作成する必要がありません。

たとえば、RCFでは、各サーバー側コンポーネントに対応するクライアント・コンポーネントをすべて作成するわけではないため、クライアント版のコンポーネント・インスタンスが必要な場合もあります。3.4項「クライアント側コンポーネントのインスタンス化」に、これを宣言的に行う方法が説明されています。JDeveloperのプロパティ・インスペクタを使用して、3.9項「レンダリングおよび可視性の理解」で説明されている、コンポーネントをレンダリングするかどうか、あるいは非表示にするかどうかを決めるプロパティを設定します。

その他の機能では、ADF Faces JavaScript APIの使用が必要になる場合があります。たとえば、3.5項「ページでのクライアント・コンポーネントの検索」では、APIを使用して特定のクライアント側コンポーネントを検索する方法が説明されており、3.7項「クライアントでのコンポーネント・プロパティへのアクセス」には、特定のプロパティへのアクセス方法が記載されています。

次のRCF機能はより複雑です。このため、個別の章が使用されています。

- ライフサイクルへのADF Facesの追加機能: ADF FacesフレームワークでJSFライフサイクルを拡張し、クライアント側の値のライフサイクルなどの追加機能を提供します。詳細は、第4章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

- イベント処理: ADF FacesはJSFイベント処理手法に準拠しています。また、RCFにはAJAXベースのリッチ・ポストバック(部分ページ・レンダリングと呼ばれる)とクライアント側イベント・モデルが用意されています。詳細は、第5章「イベントの処理」を参照してください。

- 変換および検証: ADF Faces入力コンポーネントには、ユーザー入力の変換および検証の両方の機能が組み込まれています。独自のカスタム・コンバータとバリデータを作成することもできます。詳細は、第6章「入力の検証および変換」を参照してください。

- 部分ページ・レンダリング: 部分ページ・レンダリング(PPR)を使用すると、ページ内の小さい領域を、ページ全体を再描画せずにリフレッシュできます。ADF Facesコンポーネントの多くにPPR機能が組み込まれています。また、あるコンポーネントに対するアクションによって別のコンポーネントが再レンダリングされるようPPRを宣言的に構成することもできます。詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

- ジオメトリ管理: ADF Facesには、レイアウト・コンポーネントが多く用意されており、この多くでコンテンツを使用可能な領域いっぱいに自動的に拡大することでジオメトリ管理をサポートします。詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。

- メッセージおよびヘルプ: RCFには、入力コンポーネントのツールチップ、メッセージおよびヘルプを表示する機能と、アプリケーションのグローバル・メッセージを表示する機能が用意されています。ヘルプ・フレームワークによって、アプリケーション全体で再利用可能なメッセージを作成できます。Javaクラス、マネージドBean、XLIFFファイルまたは標準プロパティ・ファイルを使用してヘルプ・プロバイダを作成したり、HTMLベースの外部ヘルプ・システムにリンクできます。詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 階層型メニュー・モデル: ADF Facesには、階層式のページをナビゲートするためのタブやブレッドクラムなどのアイテムをレンダリングするナビゲーション・コンポーネントが用意されています。RCFで、メタデータ・ファイルとともに使用し、各ページに適切な数の階層レベルを生成するためのすべての情報と、各レベルに属するナビゲーション・アイテムを含むXMLベースのメニュー・モデルが提供されます。詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照してください。

- 再利用可能なコンポーネント: RCFには、アプリケーションの複数のページで使用できる再利用可能な3つのビルディング・ブロックが用意されています(ページ・フラグメントでは、ページの一部(住所入力フォームなど)を作成できます。ページ・テンプレートでは、アプリケーション全体で一貫したルック・アンド・フィールが得られ、更新可能で、テンプレートを使用するすべてのページに変更が自動的に伝播されます。宣言コンポーネントは、開発者が再利用できるコンポジット・コンポーネントで、アプリケーション全体で動作に矛盾がないようにします)。詳細は、第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」を参照してください。

- スキンの適用: RCFでは、ADF Facesコンポーネントで外観の変更に使用するスキンを作成することで、独自のルック・アンド・フィールを作成できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- 国際化およびローカライズ: 異なるロケールを使用するようJSFページまたはアプリケーションを構成し、ユーザーのブラウザの言語設定に基づいて適切な言語を表示できます。詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

- アクセシビリティ: ADF Facesコンポーネントには、ユーザー・エージェント(スクリーン・リーダー、拡大鏡などのビジュアル・メディア以外にレンダリングするWebブラウザ)に対するアクセシビリティ・サポートが組み込まれています。アクセシビリティ・サポートには、ユーザーがキーボードのみを使用してコンポーネントやリンクにアクセスできるアクセス・キー、アクセシブルHTMLマークアップを使用したアクセシブルなイメージ、表、フレーム、フォーム、エラー・メッセージおよびポップアップ・ダイアログの作成手順を提供する監査ルールも含まれます。詳細は、第22章「アクセス可能なADF Facesページの開発」を参照してください。

- ユーザー駆動型パーソナライズ: 多くのADF Facesコンポーネント(panelSplitterなど)で、ユーザーは実行時にコンポーネントの表示を変更できます。デフォルトでは、これらの変更はページ・リクエストの間有効です。ただし、変更がユーザーのセッションの間永続するようアプリケーションを構成できます。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- ドラッグ・アンド・ドロップ機能: RCFで、ユーザーは、ある場所から別の場所へデータを移動(切り取って貼付け)、コピー(コピーして貼付け)およびリンク(コピーしてリンクとして貼付け)できます。ドロップが完了すると、ドロップの受入れ先コンポーネントで部分ページ・レンダリングを使用して再レンダリングが行われます。詳細は、第32章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。

この章の以降の項では、クライアント側フレームワークの使用に焦点を当てます。

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

従来のJSFアプリケーションでは、クライアントでイベントを処理する場合、DOMレベルのイベントをリスニングする必要があります。ただし、これらの実装は移植可能な形式で配信されません。ADF Facesのクライアント側イベント・モデルはJSFイベント・モデルと似ていますが、クライアントで実装されます。クライアント側イベント・モデルはDOMの要約で、コンポーネントレベルのイベント・モデルとライフサイクルが提供され、サーバーから独立して実行されます。このため、ボタンのclickイベントをリスニングする必要がありません。かわりに、キーまたはマウスのイベントで発生するAdfActionEventイベントをリスニングできます。

クライアントによって送信されるイベントはすべてAdfBaseEventクラスのサブクラスです。各クライアント・イベントには、イベントをトリガーしたコンポーネントであるソースがあります。イベントには、イベントをリスニングするリスナーを判断するタイプ(actionまたはdialogなど)もあります。クライアント・リスナーは、af:clientListenerタグを使用してコンポーネントに登録します。

たとえば、クリックされると「Hello World」アラートを表示するボタンがあるとします。例3-1に示すように、まず、イベント・ハンドラを起動するリスナーをボタンに登録します。

例3-1 クライアント・リスナーの登録

<af:commandButton text="Say Hello">
<af:clientListener method="sayHello" type="action"/>
</af:commandButton>

ヒント:

ボタンにクライアント・リスナーが登録されているため、フレームワークで、クライアント版のコンポーネントが自動的に作成されます。

次に、例3-2に示すようなハンドラをJavaScript関数に作成します。

例3-2 JavaScriptイベント・ハンドラ

function sayHello(event)
{
alert("Hello, world!")
}

クライアント版のコンポーネントがあるため、ボタンがクリックされると、AdfActionクライアント・イベントが起動されます。AdfActionイベントをリスニングするようclientListenerタグが構成されているため、sayHello関数が実行されます。クライアント側イベントの詳細は、5.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。

3.3 JavaScriptのページへの追加

JavaScriptをページにインラインで直接追加することも、JavaScriptライブラリをページにインポートすることもできます。ライブラリをインポートすると、ページのコンテンツ・サイズが小さくなり、ライブラリをページ間で共有して、ブラウザでキャッシュできます。可能な場合はJavaScriptライブラリをインポートしてください。インラインのJavaScriptは、小規模でページ固有のスクリプトが必要な場合にのみ使用します。

パフォーマンスのヒント:

必要なページにのみJavaScriptを含めることで、パフォーマンスが向上しますが、これは、テンプレートにJavaScriptが含まれている場合のように、JavaScriptの不要なページでJavaScriptをロードする必要がないためです。ただし、ほとんどのページで同じJavaScriptコードが使用されている場合、テンプレートにライブラリをインポートするスクリプトまたはタグを含めることを検討してください。

ただし、JavaScriptコード・ライブラリが非常に大きくなった場合、ライブラリを内容に応じて分割し、(テンプレートではなく)ページで必要な部分のみを含めることに注意してください。この方法で、ブラウザ・キャッシュが使用され、ページのHTMLコンテンツが小さくなるため、パフォーマンスが向上します。

3.3.1 インラインのJavaScriptの使用方法

インラインのJavaScriptは、JSFアプリケーションと同様に作成および使用します。JavaScriptがページに含まれる場合、clientListenerタグを使用して起動します。

インラインのJavaScriptを使用する手順:

1. 例3-3に太字で示すコードを追加して、MyFaces Trinidadタグ・ライブラリをページのルート要素に追加します。

例3-3 ページでのMyFaces Trinidadタグ・ライブラリ

<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
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. ページにJavaScriptを作成します。
たとえば、例3-2に示すsayHello関数は、例3-4のようにJSFページに含めることができます。

例3-4 インラインのJavaScript

<af:resource>
function sayHello()
{
alert("Hello, world!")
}
</af:resource>

注意:

ページまたはテンプレートにf:verbatimタグを使用してJavaScriptを指定しないでください。

3. 構造ウィンドウで、JavaScriptを起動するコンポーネントを右クリックし、「<コンポーネントの中に挿入」→「ADF Facesコア」→「クライアント・リスナー」を選択します。

4. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドにJavaScript関数の名前を入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

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

af:resourceタグを使用して、ページからJavaScriptライブラリにアクセスします。このタグは、documentタグのmetaContainerファセットの内部に含める必要があります。

ページからJavaScriptライブラリにアクセスする手順:

1. documentタグの下に、例3-5に太字で示すコードを追加し、JavaScriptライブラリが含まれるディレクトリへの相対パスに/mySourceDirectoryを置き換えます。

例3-5 JavaScriptライブラリへのアクセス

<af:document>
<f:facet name="metaContainer">
<af:resource source="/mySourceDirectory"/>
</facet>
<af:form></af:form>
</af:document>

2. 構造ウィンドウで、JavaScriptを起動するコンポーネントを右クリックし、「<コンポーネントの中に挿入」→「ADF Facesコア」→「クライアント・リスナー」を選択します。

3. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドに関数の完全修飾名を入力します。たとえば、sayHello関数がMyScriptsライブラリにある場合、MyScripts.sayHelloと入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

3.3.3 クライアント・イベント・ソースへのアクセスについて

JavaScriptでクライアントにアクセスする必要がある場合、リスナーのコンテキストで行われ、イベントのソース・コンポーネントにアクセスする必要がある場合がしばしばあります。getSource()メソッドを使用してクライアント・コンポーネントを取得します。例3-6に、名前を表示するためにソース・クライアント・コンポーネントにアクセスするsayHello関数を示します。

例3-6 クライアント・イベント・ソースへのアクセス

function sayHello(actionEvent)
{
var component=actionEvent.getSource();

//Get the ID for the component
var id=component.getId

alert("Hello from "+id);
}

クライアント・イベント・ソースへアクセスの詳細は、5.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。クライアント側プロパティへのアクセスの詳細は、3.7項「クライアントでのコンポーネント・プロパティへのアクセス」を参照してください。実行時のクライアント・イベントの処理の詳細は、5.3.6項「実行時の処理: クライアント側イベントの機能の仕方」を参照してください。

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

RCFでは、どのコンポーネントが、対応するクライアント側コンポーネント・インスタンスをデフォルトで持つかについて保証されません。通常、clientListenerハンドラを登録して、クライアント側コンポーネントと対話します。登録されているclientListenerハンドラがコンポーネントにある場合、コンポーネントはクライアント側表現を自動的に持ちます。クライアントの別のコンポーネントにアクセスする必要がある場合、clientComponent属性をtrueに設定して、そのコンポーネントがクライアントで使用できるよう明示的に構成します。

パフォーマンスのヒント:

クライアントのコンポーネントとプログラムで対話する場合にのみclientComponentをtrueに設定します。

clientComponent属性をtrueに設定すると、コンポーネントのAdfUIComponentクラスのインスタンスがフレームワークで作成されます。このクラスでは、クライアント側で使用できるAPIが提供され、基本的なプロパティ・アクセッサ・メソッド(getProperty()、setProperty()など)、イベント・リスナーの登録およびイベント配信関連のAPIが提供されます。フレームワークには、プロパティ固有のアクセッサ・メソッド(getText()、setText()など)を公開するレンダラ固有のサブクラス(AdfRichOutputTextなど)も用意されています。これらのアクセッサ・メソッドは、AdfUIComponentクラスのAccessing Component Properties on the ClientgetProperty()およびsetProperty()メソッドをラップするのみのラッパーで、コーディングが簡便になるよう用意されています。

たとえば、sayHello関数から値(表示するテキスト)を取得するoutputTextコンポーネントがページにあるとします。この関数は、値を設定するためにoutputTextコンポーネントにアクセスできる必要があります。これが機能するには、クライアント側バージョンのoutputTextコンポーネントがある必要があります。例3-7に、JSFページ・コードを示します。outputTextコンポーネントにID値があり、clientComponent属性がtrueに設定されていることに注意してください。また、値はJavaScriptで設定されるため、例には値がないことにも注意してください。

例3-7 コンポーネントの追加

<af:commandButton text="Say Hello">
<af:clientListener method="sayHello" type="action"/>
</af:commandButton>

<af:outputText id="greeting" value="" clientComponent="true">

outputTextにクライアント側表現があるため、JavaScriptでこれを見つけて使用できます。

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

イベントのソースではないクライアント・コンポーネントを検索する必要がある場合、AdfUIComponent.findComponent(expr)メソッドを使用できます。このメソッドはJSFのUIComponent.findComponent()メソッドと似ており、指定した検索式に合致するIDを使用してUIComponentオブジェクトを検索して返します。AdfUIComponent.findComponent(expr)メソッドは、サーバーではなくクライアントでのみ機能します。

例3-8に、コンポーネントのIDを使用してoutputTextコンポーネントを検索するsayHello関数を示します。

例3-8 findComponent()を使用したクライアント・コンポーネントの検索

function sayHello(actionEvent)
{
var component=actionEvent.getSource();

//Find the client component for the "greeting" af:outputText
var greetingComponent=component.findComponent("greeting");

//Set the value for the outputText component
greetingComponent.setValue("Hello World")
}

コンポーネントの完全なIDはわかるが、AdfUIComponent.findComponent(expr)をコールするコンポーネント・インスタンスがない場合、AdfUIComponent.findComponent(expr)メソッドを使用するかわりに、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドを使用できます。AdfPage.PAGEは、ページのコンテキスト・オブジェクトへの静的参照を提供するグローバル・オブジェクトです。ただし、検索対象のコンポーネントがネーミング・コンテナ内にある場合、AdfUIComponent.findComponentを使用する必要があります。詳細は、3.5.1項「ネーミング・コンテナ内のコンポーネントの検索について」を参照してください。

注意:

似たような名前のAdfPage.PAGE.findComponent(clientId)というメソッドもありますが、この関数は、リリース間で変わる可能性のある実装固有の識別子を使用し、ページ作成者は使用しません。

3.5.1 ネーミング・コンテナ内のコンポーネントの検索について

見つける必要があるコンポーネントがネーミング・コンテナ(pageTemplate、subform、tableおよびtreeなど)であるコンポーネントにある場合は、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドを使用するかわりに、AdfUIComponent.findComponent(expr)メソッドを使用します。絶対式も相対式も使用できます。

ヒント:

コンポーネントがネーミング・コンテナかどうかは、コンポーネント・タグのドキュメントを確認して判断できます。タグのドキュメントには、コンポーネントがネーミング・コンテナかどうかが示されています。

絶対式では、NamingContainer.SEPARATOR_CHAR文字を先頭とし、完全修飾されたJSFクライアントID(コンポーネントを含むNamingContainerコンポーネントのすべてのIDが先頭に付けられる)を使用し、次に例を示します。

":" + (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つのコロン(:)は、ファイル・パスがファイル構造のルートからの絶対パスであることを示します。先頭の複数のコロン(:)文字が式の最初にある場合、最初のコロンは無視され、残りのコロンは、各コロン(:)文字がピリオドとスラッシュの1つのセット(../)とみなされます。

絶対パスを使用するか相対パスを使用するかを決める際、次の点に注意します。

- 検索対象のコンポーネントが常に同じネーミング・コンテナ内あることがわかっている場合は、絶対パスを使用します。

- 検索元のコンポーネントと検索対象のコンポーネントの相対的位置が常に同じであることがわかっている場合は、相対パスを使用します。

クライアントにはgetChildren()関数もgetFacet()関数もありません。かわりに、すべての子コンポーネントとファセット(つまり、すべての子孫)にアクセスするAdfUIComponent.visitChildren()関数が用意されています。詳細は、ADF Faces JavaScriptのドキュメントを参照してください。

3.6 ユーザーの現在位置の特定

ADF Facesでは、イベントに関して現在のコンテキスト・ページ情報を返すJavaScript APIが用意されています。AdfPage.prototype.getViewId()関数では、現在表示されているビューの識別子を返します。このIDは、ページ全体のレンダリングまたは部分ページ・ナビゲーションのいずれかが発生すると設定されます。AdfPage.prototype.getComponentsByType(componentType)関数は、指定したコンポーネント・タイプに一致するコンポーネント・インスタンスの配列を返します。

たとえば、アプリケーションにタブ付きのページが含まれており、各タブが複数のリージョンで構成されているとします。各リージョンには、ネストされた他のリージョンも含めることができます。APIを使用すると、例3-9に示すように、ページ全体のviewIdと、ページで現在レンダリングされている各リージョンに表示されているフラグメントのviewIdsの組合せとなる文字列の識別子を返すことができます。

3.6.1 ユーザーの現在位置の特定方法

クライアント側のリージョン・コンポーネントのviewID propertyを取得するには、web.xmlファイルのパラメータを設定して、ユーザー・アクティビティ監視機能を有効にする必要があります。次に、現在のページを構成するviewIdsの文字列表現をビルドするJavaScriptコードを作成します。

コンテキスト識別子を決定する手順:

1. web.xmlファイルをダブルクリックします。

2. ソース・エディタで、oracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDERをtrueに設定します。
このパラメータでは、ExecutionContextProviderサービス・プロバイダが有効であることがADF Facesに通知されます。このサービスでは、クライアント開始のリクエストのユーザー・アクティビティ情報を監視して集約します。

3. oracle.adf.view.rich.automation.ENABLEDをtrueに設定します。
このパラメータにより、すべてのコンポーネントでコンポーネントIDが設定されます。詳細は、A.2.3.10項「テストの自動化」を参照してください。

4. JavaScriptを作成し、コンテキスト識別子をビルドします(JavaScriptの追加の詳細は、3.3項「JavaScriptのページへの追加」を参照)。
例3-9に、リージョンの現在のビューIDを取得するのに使用するJavaScriptを示します。

例3-9 JavaScriptによるviewIdsの取得

/**
* Returns a String identifier comprising the page viewId and viewIds
* of the fragments displayed in each of the displayed regions
*/
TestLibrary.prototype.getCurrentPageInfo = function()
{
var pageIdentifier = null;
var page = AdfPage.PAGE;
if (page)
{
// get the viewId of the page
var viewId = page.getViewId();
// get all region components currently displayed on the page
var regionComponents = page.getComponentsByType("oracle.adf.RichRegion");
var regionViewIds = new Array();
for (var index = 0; index < regionComponents.length; index++)
{
var regionComp = regionComponents[index]);
if (regionComp)
{
regionViewIds.push(regionComp.getProperty("viewId"));
}
}
// construct page identifier
if (viewId != null && regionViewIds.length > 0)
contextId = viewId.concat(regionViewIds.toString());
}
return contextId;
}

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

コンポーネントの各組込みプロパティには、簡易アクセッサ・メソッドがコンポーネント・クラスに用意されています。たとえば、クライアント・コンポーネントでgetValue()メソッドをコールし、サーバーで使用されたのと同じ値を受け取ることができます。

注意:

ブール・プロパティを含む、ADF Facesのすべてのクライアント・プロパティでgetXyz関数ネーミング規則を使用します。ブール・プロパティのisXyzネーミング規則は使用されません。

定数もクラス・オブジェクトのプロパティ名に使用できます。たとえば、styleClassを使用するかわりにAdfRichDialog.STYLE_CLASS定数を使用できます。

注意:

文字列のコーディングは各起動時にオブジェクトの割当てが必要なため、JavaScriptでは定数を参照する方が効率的です。

コンポーネントのプロパティが変更されると、新しい状態が反映されるようコンポーネントのDOMが最終的に更新されますが、サーバーへのラウンドトリップがない場合もあります。この処理でのコンポーネントの役割は非常に限られており、新しいプロパティ値を格納し、ピアに変更を通知するのみです。ピアには、コンポーネントの新しい状態を反映するようDOMを更新するロジックが含まれています。

注意:

すべてのプロパティの変更が、クライアント側のピアを使用して処理されるわけではありません。一部のプロパティ変更はサーバーに伝播され、PPRを使用してコンポーネントが再レンダリングされます。

1.2.2項「ADF Facesのアーキテクチャ上の機能」での説明のとおり、大半のプロパティ値はクライアントで設定されると、サーバーと自動的に同期されます(クライアントにまったく送信されない複雑なJavaオブジェクトもあります)。ただし、これとは異なる動作をするセキュア・プロパティと分離プロパティの2種類のプロパティもあります。

セキュア・プロパティは、クライアントでまったく設定できないプロパティです。たとえば、悪意のあるクライアントでJavaScriptを使用してcommandLinkコンポーネントのimmediateフラグがtrueに設定されるとします。この変更がサーバーに伝播された結果、サーバー側の検証が省略され、セキュリティ・ホールとなる可能性があります(immediateプロパティの使用の詳細は、4.2項「immediate属性の使用」を参照してください)。つまり、immediateプロパティはセキュア・プロパティです。

JavaScriptから他のセキュア・プロパティの設定を試みると失敗します。詳細は、3.7.2項「無効なプロパティを保護しない方法」を参照してください。表3-1に、クライアント・コンポーネントのセキュアなプロパティを示します。

表3-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

rowsByDepth

rangeChangeListener

AdfUIValueBase

converter

ADF Facesでは、保護されなくなるなるように、disabledプロパティを構成できます。これは、JavaScriptを使用してdisableボタンを有効にする必要がある場合に便利です。unsecureプロパティをtrueに設定すると、disabledプロパティ(およびdisabledプロパティのみ)が保護されなくなります。

分離プロパティは、クライアントで設定できるが、サーバーに伝播されないプロパティです。これらのプロパティには、サーバーでのライフサイクルに依存しないクライアントにライフサイクルがあります。たとえば、クライアント・フォーム入力コンポーネント(AdfRichInputTextなど)には、JavaのEditableValueHolderコンポーネントのようにsubmittedValueプロパティがあります。ただし、このプロパティの設定はサーバーに直接影響しません。この場合、標準のフォーム送信手法によって、送信された値のサーバーでの更新を処理します。

プロパティは、分離プロパティとセキュア・プロパティの両方にできます。実際には、このようなプロパティはクライアントで分離プロパティのように機能し、クライアントで設定できますが、サーバーに送信されません。しかし、サーバーでは、クライアントからの設定を受け付けないという点でセキュア・プロパティのように機能します。

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

RCFには、AdfUIComponentsetProperty()関数をコールするためのsetXYZ簡易関数が用意されています。setProperty()関数は次の引数をとります。

- プロパティ名(必須)

- 新しい値(必須)

3.7.2 disabledプロパティを保護しない方法

disabledプロパティが保護されないように設定するには、unsecuredプロパティを使用します。disabledプロパティが保護されないようにするコンポーネントのコードに、このプロパティと、disabledの値を手動で追加する必要があります。たとえば、disabledプロパティが保護されないようにするボタンのコードは、次のとおりです。

<af:commandButton text="commandButton 1" id="cb1" unsecure="disabled"/>

unsecure属性をdisabledに設定すると、悪意のあるJavaScriptによって、disabled属性が知らずに変更される可能性があります。たとえば、経費の承認ページがあり、そのページで、$200未満の請求書のみを特定のマネージャが承認できるようにします。このため、現在のユーザーが請求書の承認を許可されていない場合は、承認ボタンを無効にします。

unsecured属性をdisabledに設定していない場合、承認ボタンは、サーバーへのラウンドトリップが発生するまで無効のままになり、この場合は、現在のユーザーが経費を承認できるかどうかをロジックで決定します。しかし、経費がページにロードされる際に、ボタンを正しく表示する必要があるため、unsecure属性をdisabledに設定します。これで、クライアントでJavaScriptを使用して、ボタンを無効にするかどうかを決定できます。しかし、同じことは、どのJavaScript(制御できない悪意のあるJavaScriptも含む)でも可能です。

このような問題を回避するには、サーバへのラウンドトリップが実行されるのと同様に、同じロジックをアプリケーションで実行する必要があります。経費レポートの承認画面では、$200未満の金額をチェックするJavaScriptを使用できますが、承認ボタンのアクションがサーバでロジックを実行できるようにする必要があります。このロジックをサーバーに追加することにより、disabled属性を変更すべきでない場合は、変更されません。

同様に、実行時にアプリケーションを変更できるようにし、ユーザーがunsecureまたはdisabled属性(あるいはその両方)を潜在的に編集できるようにするには、サーバへのラウンドトリップが実行されるのと同様に、同じロジックをアプリケーションで実行する必要があります。

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

クライアントでsetProperty()関数をコールすると、プロパティが新しい値に設定され、値が異なる場合は、同時にPropertyChangeEventイベントが新しい値を使用して起動されます。また、プロパティを設定すると、コンポーネントが自身を再レンダリングする場合があります。

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

組込みプロパティ以外の情報をクライアントに送信する必要がある場合もあります。これは、ボーナス属性を使用して行えます。ボーナス属性は、clientAttributeタグを使用してコンポーネントに追加できる追加属性です。パフォーマンス上の理由から、クライアントに送信されるボーナス属性は、clientAttributeで指定されたもののみです。

clientAttributeタグで、サーバー側コンポーネントの属性マップに追加される名前と値のペアを指定します。clientAttributeタグを使用すると、サーバー側属性マップへの移入に加え、ボーナス属性のクライアントへの送信も行われます(クライアントではAdfUIComponent.getProperty("bonusAttributeName")メソッドを使用してアクセスできます)。

RCFで、属性値のクライアントへのマーシャリングが行われます。マーシャリング・レイヤーで、文字列、ブール、数値、日付、配列、マップなど、各オブジェクト型のマーシャリングがサポートされます。マーシャリングの詳細は、5.4.3項「データのマーシャリングとアンマーシャリングについて」を参照してください。

パフォーマンスのヒント:

マーシャリングによる過度のオーバーヘッドを防ぐため、クライアント側ボーナス属性を多用しないでください。

注意:

clientAttributeタグは、(アプリケーションで定義される)ボーナス属性にのみ使用します。クライアントで標準のコンポーネント属性にアクセスする必要がある場合、clientAttributeタグを使用するのではなく、clientComponent属性をtrueに設定します。詳細は、3.4項「クライアント側コンポーネントのインスタンス化」を参照してください。

3.8.1 ボーナス属性の作成方法

コンポーネント・パレットを使用して、ボーナス属性をコンポーネントに追加できます。

ボーナス属性を作成する手順:

1. 構造ウィンドウで、ボーナス属性を追加するコンポーネントを選択します。

2. コンポーネント・パレットの「操作」パネルから、「クライアント属性」をコンポーネントの子としてドラッグ・アンド・ドロップします。

3. プロパティ・インスペクタで「名前」と「値」属性を設定します。

3.8.2 ボーナス属性のマーシャリングについて

クライアント側ボーナス属性は、サーバーからクライアントへ自動的に配信されますが、その逆は行われません。つまり、クライアントでのボーナス属性の変更または設定は、サーバーに反映されません。既知(ボーナス以外)の属性のみ、クライアントからサーバーへ同期がとられます。アプリケーションで定義されたデータをサーバーに送り返す必要がある場合、カスタム・イベントを作成します。詳細は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

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

すべてのADF Faces表示コンポーネントには、コンポーネントをページに表示してユーザーに見えるようにするかどうかに関係するrenderedとvisibleの2つの属性があります。

rendered属性のセマンティクは非常に厳密です。renderedがfalseに設定されている場合、サーバーへのラウンドトリップなしにコンポーネントをクライアントで表示することはできません。ページのコンテンツの動的な表示/非表示をサポートするために、RCFにはvisible属性が追加されています。falseに設定されている場合、コンポーネントのマークアップはクライアントで使用可能ですが、コンポーネントは表示されません。したがって、setVisible(true)またはsetVisible(false)メソッドをコールすると、JavaからのコールであろうとJavaScriptからのコールであろうと、コンポーネントがブラウザ内で表示または非表示になります(renderedがtrueに設定されている場合)。

パフォーマンスのヒント:

JavaScriptなど、サーバーへのラウンドトリップなしに可視性を切り替える必要がある場合にのみvisible属性をfalseに設定します。非表示のコンポーネントも、検証を含むコンポーネント・ライフサイクルを経過します。

クライアントでのみ可視性を切り替える必要がない場合、かわりにrendered属性をfalseに設定します。コンポーネントをレンダリングしない(表示しないのではなく)場合、コンポーネントはクライアント側表現を持たず、コンポーネント・ライフサイクルを経過しないため、サーバーのパフォーマンスとクライアントのレスポンス時間が向上します。

例3-10に、2つのoutputTextコンポーネント(一度に1つのみレンダリングが表示)を示します。1つ目のoutputTextコンポーネントは、inputTextコンポーネントに値が入力されなかった場合にレンダリングされます。2つ目のoutputTextコンポーネントは、値が入力された場合にレンダリングされます。

例3-10 レンダリングされる/レンダリングされないコンポーネント

<af:panelGroupLayout layout="horizontal">
<af:inputText label="Input some text" id="input"
value="#{myBean.inputValue}"/>
<af:commandButton 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プロパティを使用してコンポーネントをページに表示したり、非表示にできます。

例3-11に、例3-10と同じ機能を達成する方法を示しますが、この例では、visible属性を使用して表示するコンポーネントを決めます(rendered属性はデフォルトでtrueで、明示的に設定する必要はありません)。

例3-11 表示可能/表示不可能なコンポーネント

<af:panelGroupLayout layout="horizontal">
<af:inputText label="Input some text" id="input"
value="#{myBean.inputValue}"/>
<af:commandButton 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で可視性を処理することもできます。

例3-12に、コンポーネントの可視性を処理するJavaScriptのページ・コードを示します。

例3-12 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)
}

}

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

コンポーネントのvisible属性を切り替えられる条件付きJavaScript関数を作成できます。

可視性を設定する手順:

1. 可視性を切り替えるJavaScriptを作成します。例3-12に、値がない場合にoutputTextコンポーネントの可視性を有効にし、そうでない場合は別のoutputTextコンポーネントの可視性を有効にするスクリプトを示します。

2. JavaScript関数に必要なコンポーネントごとに、プロパティ・インスペクタで拡張セクションを開き、ClientComponent属性をtrueに設定します。これによって、JavaScriptで使用されるクライアント・コンポーネントが作成されます。

3. 可視性を切り替えるコンポーネントのvisible属性をfalseに設定します。

例3-13に、JavaScriptを使用した可視性の切替えに使用されるページ・コード全体を示します。

例3-13 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:commandButton text="Enter" clientComponent="true">
<af:clientListener method="showText" type="action"/>
</af:commandButton>
</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>

3.9.2 VisibleとisShowing関数について

コンポーネントの親のvisible属性がfalseに設定されている場合、visible属性がtrueに設定されている子コンポーネントにisVisible関数が実行されると、子が表示されていなくてもtrueが返されます。たとえば、outputTextコンポーネントを子として含むpanelGroupLayoutコンポーネントがあり、panelGroupLayoutコンポーネントのvisible属性がfalseに設定され、outputTextコンポーネントのvisible属性がデフォルトのまま(true)とします。クライアントでは、panelGroupLayoutコンポーネントもoutputTextコンポーネントも表示されませんが、isVisible関数がoutputTextコンポーネントに実行されると、trueが返されます。

このため、RCFにはisShowing()関数が用意されています。この関数は、コンポーネントのvisible属性がfalseに設定されている場合、またはコンポーネントの親のvisibleがfalseに設定されている場合、falseを返します。

4 ADF FacesによるJSFライフサイクルの使用

この章では、JSFページ・リクエスト・ライフサイクル、ADF Facesのライフサイクルの追加機能、およびアプリケーションでのライフサイクルの最適な使用方法について説明します。

この章では、次の項目について説明します。

- 4.1項「JSFライフサイクルおよびADF Facesの概要」

- 4.2項「immediate属性の使用」

- 4.3項「最適化されたライフサイクルの使用」

- 4.4項「クライアント側ライフサイクルの使用」

- 4.5項「サブフォームを使用したページでの領域の作成」

- 4.6項「オブジェクト・スコープ・ライフサイクル」

- 4.7項「ページ間の値の受渡し」

4.1 JSFライフサイクルおよびADF Facesの概要

ADF Facesリッチ・クライアント・フレームワーク(RCF)はJSFフレームワークの拡張であるため、ADF Facesリッチ・クライアント・フレームワークを使用して構築したアプリケーションでは標準JSFページ・リクエスト・ライフサイクルが使用されます。ただし、ADF Facesフレームワークではライフサイクルが拡張され、クライアント側の値のライフサイクル、1つのページに複数のフォームを使用する弊害(ユーザーの編集内容の消失など)なしに独立して送信可能な領域をページに作成できるサブフォーム・コンポーネント、追加スコープなどの追加機能を提供します。

RCFで提供されるライフサイクルの拡張を十分に理解するには、標準JSFライフサイクルを理解することが重要です。この項では概要のみを説明します。詳細は、http://www.oracle.com/technetwork/java/index.htmlでJSFの仕様を参照してください。

JSFページが送信され、新しいページがリクエストされると、JSFページ・リクエスト・ライフサイクルが起動されます。このライフサイクルでは、ページの値の送信、現在のページでのコンポーネントの検証、ナビゲーション、コンポーネントの結果ページへの表示および状態の保存とリストアが処理されます。JSFライフサイクル・フェーズでは、UIコンポーネント・ツリーを使用してfacesコンポーネントの表示を管理します。このツリーはJSFページのランタイム表現で、ページ内の各UIコンポーネント・タグがツリーのUIコンポーネント・インスタンスに対応します。FacesServletオブジェクトで、JSFアプリケーションのページ・リクエスト・ライフサイクルが管理されます。FacesServletオブジェクトで、リクエスト処理に必要な情報を含み、ライフサイクルを実行するオブジェクトを起動するFacesContextと呼ばれるオブジェクトが作成されます。

図4-1に、ページ・リクエストのJSFライフサイクルを示します。ここに示すとおり、各フェーズの前後でイベントが処理されます。

図4-1 ADF Facesアプリケーションでのページ・リクエストのライフサイクル

JSFアプリケーションでは、ページ・リクエスト・ライフサイクルは次のようになります。

- ビューのリストア:コンポーネント・ツリーが構築されます。これが初めてのレンダリングでない場合(ページがサーバーに送り返された場合)、適切な状態でツリーがリストアされます。これが初めてのレンダリングの場合、コンポーネント・ツリーが作成され、レスポンスのレンダリング・フェーズに移ります。

- リクエスト値の適用: ツリーの各コンポーネントでリクエスト・パラメータから新規の値が(decodeメソッドを使用して)抽出され、ローカルに格納されます。関連するイベントの大半が、後の処理用にキューイングされます。コンポーネントのimmediate属性がtrueに設定されている場合、検証、変換、およびコンポーネントに関連付けられているイベントがこのフェーズで処理されます。詳細は、4.2項「immediate属性の使用」を参照してください。

- 検証の処理: コンポーネントのローカル値が、入力タイプから基礎のデータ型に変換されます。コンバータが失敗した場合、このフェーズが続行されて完了します(残りのすべてのコンバータ、バリデータおよび必要なチェックが実行されます)が、完了時にライフサイクルがレスポンスのレンダリング・フェーズに移ります。
失敗がない場合、コンポーネントのrequired属性が確認されます。値がtrueで、関連付けられているフィールドに値が含まれている場合、関連付けられているバリデータが実行されます。値がtrueで、フィールド値がない場合、このフェーズは完了します(残りのすべてのバリデータが実行されます)が、ライフサイクルがレスポンスのレンダリング・フェーズに移ります。値がfalseの場合、値が入力されていないかぎり(この場合は検証が実行されない)、フェーズが完了します。変換と検証の詳細は、第6章「入力の検証および変換」を参照してください。

このフェーズの最後に、変換後のローカル値が設定され、検証および変換のエラー・メッセージとイベントがFacesContextにキューイングされ、値変更イベントが配信されます。

ヒント:

要約すると、編集可能な入力コンポーネントの検証の処理フェーズでの手順は次のとおりです。

1. コンバータが失敗した場合、必要なチェックとバリデータが実行されません。

2. コンバータは成功したが、必要なチェックが失敗した場合、バリデータが実行されません。

3. コンバータと必要なチェックが成功した場合、すべてのバリデータが実行されます。1つのバリデータが失敗した場合でも、残りのバリデータは実行されます。これは、ユーザーがエラーを修正する際に使用できる、入力されたデータの問題点を可能なかぎりフィードバックするためです。
たとえば、2010年の日付のみを受け入れるdateTimeRangeバリデータがあり、ユーザーが日曜日を選択できないdateRestrictionValidatorバリデータがあるとします。ユーザーがJuly 5, 2009(日曜日)と入力した場合、両方のバリデータが失敗することをフィードバックし、ユーザーが有効な日付を入力する可能性を最大限にします。

- モデル値の更新: コンポーネントの検証済のローカル値がモデルに移され、ローカル・コピーが破棄されます。

- アプリケーションの起動: アプリケーション・レベルのロジック(イベント・ハンドラなど)が実行されます。

- レスポンスのレンダリング: ツリー内のコンポーネントがレンダリングされます。後続のリクエストおよびビューのリストア・フェーズ用に状態情報が保存されます。

ライフサイクルの説明の一環として、ユーザーが日付を入力し、コマンド・ボタンをクリックして入力値を送信する単純な入力テキスト・コンポーネントを持つページを考えてみます。valueChangeListenerメソッドもコンポーネントに登録されています。例4-1に、この例のコードを示します。

例4-1 JSFライフサイクルを説明するためのサンプル・コード

<af:form>
<af:inputText value="#{mybean.date}"
valueChangeListener="#{mybean.valueChangeListener}">
<af:convertDateTime dateStyle="long"/>
</af:inputText>
<af:commandButton text="Save"  actionListener="#{mybean.actionListener}"/>
</af:form>

ユーザーが文字列「June 25, 2005」を入力し、送信ボタンをクリックするとします。図4-2に、値がライフサイクルでどのように受け渡され、各イベントがどの時点で処理されるかを示します。

図4-2 JSFライフサイクルでの値とイベントの例

4.2 immediate属性の使用

immediate属性を使用して、ライフサイクルのリクエスト値の適用フェーズまでコンポーネントの処理を進めることができます。actionSourceコンポーネント(commandButtonなど)がimmediateに設定されている場合、アプリケーションの起動フェーズではなく、リクエスト値の適用フェーズでイベントが配信されます。actionListenerハンドラでレスポンスのレンダリング・フェーズがコールされ、検証およびモデルの更新フェーズが省略されます。

たとえば、「取消」ボタンをimmediateとして構成し、前のページに戻るために使用される文字列をアクションで返すとします(ナビゲーションの詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照)。「取消」ボタンはimmediateに設定されているため、ユーザーが「取消」ボタンをクリックすると、すべての検証が省略され、入力されたデータはモデルに更新されず、図4-3に示されているように、ユーザーは見込みどおりにナビゲートされます。

図4-3 immediateに設定されたコマンド・ボタンのライフサイクル

注意:

ナビゲーションを提供せず、immediateに設定されているコマンド・ボタンは、レスポンスのレンダリング・フェーズに直接進み、検証、モデルの更新、アプリケーションの起動のフェーズは省略され、新しい値はサーバーにプッシュされません。

コマンド・コンポーネントと同様、表示イベントを起動するコンポーネント(showDetailコンポーネントなど)、およびeditableValueHolderコンポーネント(inputTextコンポーネントなどの変更可能な値を保持するコンポーネント)の場合、イベントはリクエスト値の適用フェーズに送られます。ただし、editableValueHolderコンポーネントの場合、フェーズを省略するかわりに、変換、検証およびvalueChangeEventsイベントの配信が、プロセスの検証フェーズの後ではなく、ライフサイクルの前半のリクエスト値の適用フェーズで行われます。ライフサイクルのフェーズは省略されません。

図4-4に、immediate属性がtrueに設定されている入力コンポーネントのライフサイクルを示します。入力コンポーネントは文字列として入力された日付を取得し、コマンド・ボタンがクリックされたときにDateオブジェクトとしてその日付を格納します。

図4-4 入力コンポーネントのimmediate属性

入力コンポーネントのimmediate属性をtrueを設定すると、1つ以上の入力コンポーネントをその他のコンポーネントより前に検証する必要がある場合に役立ちます。これらのコンポーネントの1つで無効なデータが検出されると、同じページの他の入力コンポーネントの検証が省略されるため、ページに表示されるエラー・メッセージの数が削減されます。

パフォーマンスのヒント:

immediate属性をtrueに設定すると、パフォーマンスが向上する場合があります。

- ナビゲーション・トレインを作成し、navigationPaneコンポーネント内にcommandNavigationItemコンポーネントがある場合、immediate属性をtrueに設定し、次のページへの移動時、現在のページ(トレイン・ストップ)からのデータの処理を回避します。詳細は、18.8.1項「トレイン・モデルの作成方法」を参照してください。

- 他の値の前に入力コンポーネント値を検証する必要がある場合、immediate属性をtrueに設定します。ライフサイクルの早い段階でエラーが検出され、その他の処理が行われずに済みます。

別の例として、あるフォームに、検索の実行を起動するように構成されているコマンド・ボタンを使用して文字列の検索に使用される入力コンポーネント、および日付の送信に使用される関連付けられたコマンド・ボタンを使用して日付の入力に使用される別の入力テキスト・コンポーネントが設定されているとします。この例では、検索入力コンポーネントとボタンの両方をimmediateに設定します。これにより、日付入力コンポーネントのコンバータが起動されないため、日付フィールドに無効な文字列が入力されている場合でも、ユーザーは検索を実行できます。また、検索入力テキストがimmediateに設定され、日付入力フィールドでは設定されてないため、検索入力テキストのみ処理されます。両方のフィールドは同じフォーム内にあるため、ユーザーが日付フィールドに有効な日付を入力し、その後、検索を実行して「保存」ボタンをクリックしない場合、検索結果が表示されるときに、入力した値が引き続き表示されます。例4-2に、2つのフィールドと2つのボタンに使用されるコードを示します。

例4-2 immediateを使用する入力コンポーネントとコマンド・コンポーネント

<af:form>
<af:inputText immediate="true" label="Search"  value="#{mybean.search}"
valueChangeListener="#{mybean.searchValueChangeListener}"/>
<af:commandButton 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:commandButton text="save"  actionListener="#{mybean.actionListener}"/>
</af:form>

図4-5に、ユーザーが次のことを行う場合のこのページのライフサイクルを示します。

- binkyを「日付」入力フィールドに入力する(これは有効なエントリではありません)。

- dressを「検索」フィールドに入力する。

- 「検索」ボタンをクリックして、dressの検索を実行する。

- 「保存」ボタンをクリックして、値binkyを日付として保存する。

図4-5 コマンド・コンポーネントと入力コンポーネント両方のimmediate属性

同じページのeditableValueHolderおよびactionSourceコンポーネントにimmediate属性を使用する場合、次の点に注意する必要があります。

- editableValueHolderコンポーネントがimmediateとマークされている場合、モデル値の更新フェーズの前に実行されます。immediateなactionSourceコンポーネントにeditableValueHolderコンポーネントからのデータが必要な場合、editableValueHolderコンポーネントに入力されたデータはモデルの更新フェーズまでモデルで使用できないため、これが問題となる場合もあります。immediateなactionSourceコンポーネントがあり、このコンポーネントでデータが必要な場合、editableValueHolderフィールドのimmediateも設定します。こうすることで、editableValueHolderコンポーネントのgetValueメソッドをコールでき、ローカル値が返されます。モデルにはまだプッシュされていませんが、コンポーネントで使用できます。

- immediateなeditableValueHolderコンポーネントが検証に失敗した場合でも、immediateなactionSourceコンポーネントは実行されます。

immediate属性を使用する手順:

1. JSFページで、immediateにするコンポーネントを選択します。

2. プロパティ・インスペクタで、「動作」セクションを開き、immediate属性をtrueに設定します。

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

ADF Facesには、ページの特定のコンポーネントでのみJSFページ・リクエスト・ライフサイクル(変換と検証を含む)を実行する場合に使用できる最適化されたライフサイクルが用意されています。たとえば、必須属性がtrueに設定されたinputTextコンポーネントがページにあるとします。同じページにラジオ・ボタンがあり、選択すると、図4-6に示すようにoutputTextコンポーネントのテキストをページに表示または非表示します。

図4-6 必須フィールドと自動送信のブール

また、フィールドに必須テキストを入力する前に、ユーザーがラジオ・ボタンを選択できるとします。ラジオ・ボタン・コンポーネントで送信アクションを自動的にトリガーするよう設定し、immediate属性をtrueに設定して、inputTextコンポーネントの前に処理されるようにできますが、valueChangeEventリスナーを追加し、ここでレスポンスのレンダリング・フェーズをコールして、入力テキスト・コンポーネントで検証が実行されないようにする必要もあります。

このコードをリスナーに記述するかわりに、ADF Facesでは、ページに境界を設定してライフサイクルが境界内のコンポーネントでのみ実行されるようにすることができます。境界を判断するために、処理するコンポーネントのルートをフレームワークに通知する必要があります。このコンポーネントは、次の2つの方法で決めることができます。

- コンポーネント: リージョンは、フレームワークで境界が認識されるコンポーネントの1つの例です。リージョン内でトリガーされたイベントに関係なく、リージョン外のコンポーネントでライフサイクルは実行されません。

- イベント: 特定のイベントはルートであるコンポーネントを示します。たとえば、showDetailコンポーネントを展開または縮小(8.8項「コンテンツの動的な表示および非表示」を参照)すると送信される表示イベントは、showDetailコンポーネントがルートであることを示しすため、showDetailコンポーネントおよび子コンポーネントでのみライフサイクルが実行されます。ライフサイクルは、その表示イベントをリスニングするよう構成されているコンポーネントでも実行できます。ルート・コンポーネントのイベントをリスニングするようコンポーネントを構成して処理することは、クロスコンポーネント・リフレッシュと呼ばれます。

クロスコンポーネント・リフレッシュでは、あるコンポーネントからのイベントが別のコンポーネント(ターゲットと呼ばれる)のトリガーとして機能するように依存性を設定できます。トリガー・コンポーネントでイベントが発生すると、ターゲット・コンポーネントと、トリガーおよびターゲットの両方の子コンポーネントでライフサイクルが実行され、これらのコンポーネントのみが再レンダリングされます。これは、部分ページ・レンダリング(PPR)とみなされます。

ラジオ・ボタンの例では、例4-3に示すように、ラジオ・ボタンをトリガーとし、出力テキストを含むpanelGroupLayoutコンポーネントをターゲットとして設定します。

例4-3 クロスコンポーネント・レンダリングの例

<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コンポーネントが両方のラジオ・コンポーネントのターゲットとして設定されているため、イベントが起動されると、selectOneRadio(ルート)、panelGroupLayoutコンポーネント(ルートのターゲット)とその子コンポーネント(outputTextコンポーネント)のみライフサイクルの処理が行われます。outputTextコンポーネントは表示ラジオ・ボタンの選択時にのみレンダリングされるよう構成されているため、ユーザーは、ラジオ・ボタンの上の必須入力フィールドにテキストを入力しなくても、ラジオ・ボタンを選択して出力テキストを表示できます。

ADF FacesフレームワークでのPPRの使用方法とアプリケーションでのPPRの使用方法の詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

4.3.1 immediate属性と最適化されたライフサイクルの使用について

PPRで特定のコンポーネントの検証を回避できない場合があります。たとえば、例4-4に示すように、panelGroupLayoutコンポーネント内にoutputTextコンポーネントのかわりにinputTextコンポーネントを使用し、このrequired属性をtrueに設定するとします。

例4-4 クロスコンポーネントPPRで検証されるpanelGroupコンポーネント内のinputTextコンポーネント

<af:form>
<af:selectBooleanRadio id="show2" autoSubmit="true" text="Show"
value="#{validate.show2}"/>
<af:selectBooleanRadio id="hide2" autoSubmit="true" text="Hide"
value="#{validate.hide2}"/>
<af:panelGroupLayout partialTriggers="show2 hide2">
<af:inputText label="Required Field" required="true"
rendered="#{validate.show2}"/>
</af:panelGroupLayout>
</af:form>

この例では、ライフサイクルはルート(selectOneRadioコンポーネント)、ターゲット(panelGroupLayoutコンポーネント)とターゲットの子(inputTextコンポーネント)で実行されるため、inputTextコンポーネントは検証されます。inputTextコンポーネントが必須としてマークされているため、値がないと、検証が失敗し、エラーがスローされます。エラーのため、ライフサイクルはレスポンスのレンダリング・フェーズに移り、モデルは更新されません。このため、ラジオ・ボタンの値が更新されず、panelGroupLayoutコンポーネントは表示または非表示にできません。

このような場合、ラジオ・ボタンのimmediate属性を使用して検証を省略できます。これにより、inputTextコンポーネントのプロセスの検証フェーズの前にボタンのvalueChangeEventが実行されます。レスポンスのレンダリング・フェーズをコール(その結果、入力コンポーネントの検証を省略)するvalueChangeListenerハンドラ・メソッドを追加し、ラジオ・ボタンと入力コンポーネントに値を設定する必要があります。例4-5に、これを行うJSFコードを示します。

例4-5 immediate属性とvalueChangeListenerの使用

<af:form>
<af:selectOneRadio immediate="true"
valueChangeListener="#{validate.toggle}"
id="show2" autoSubmit="true" text="Show"
value="#{validate.show2}"/>
<af:selectOneRadio id="hide2" autoSubmit="true" text="Hide"
value="#{validate.hide2}"/>
<af:panelGroupLayout partialTriggers="show2 hide2">
<af:inputText label="Required Field" required="true"
rendered="#{validate.show2}"/>
</af:panelGroupLayout>
</af:form>

例4-6に、valueChangeListenerのコードを示します。

例4-6 valueChangeListenerで値を設定し、レスポンスのレンダリングをコール

public void toggle(ValueChangeEvent vce)
{
setShow2(Boolean.TRUE.equals(vce.getNewValue()));
FacesContext.getCurrentInstance().renderResponse();
}

4.3.2 LOVコンポーネントと最適化されたライフサイクルの使用について

inputListOfValuesおよびinputComboBoxListOfValuesコンポーネントでは、4.3.1項「immediate属性と最適化されたライフサイクルの使用について」に説明されている手順は機能しません。次に例を示します。

ユーザーが従業員名を選択するinputListOfValuesコンポーネントと、必須の属性がtrueに設定されているinputTextコンポーネントがあるとします(図4-7に示すように、従業員を選択すると、従業員のIDで更新されます)。

図4-7 LOVコンポーネントで更新される入力コンポーネント

これを達成するには、例4-7に示すように、EmpnoフィールドにEnameフィールドが部分トリガーとして含まれるように設定します。

例4-7

<af:inputListOfValues label="Ename" id="lov0"
value="#{validateLOV.ename}" autoSubmit="true"
immediate="true"
popupTitle="Search and Select: Ename"
searchDesc="Choose a name"
model="#{validateLOV.listOfValuesModel}"
valueChangeListener="#{validateLOV.immediateValueChange}"
validator="#{validateLOV.validate}"/>
<af:inputText label="Empno" value="#{validateLOV.empno}" required="true"
id="lovDependent01" partialTriggers="lov0"/>

4.3.1項「immediate属性と最適化されたライフサイクルの使用について」のラジオ・ボタンおよび入力コンポーネントの例と同様、ライフサイクルはルート(inputListOfValuesコンポーネント)とターゲット(inputTextコンポーネント)の両方で実行されるため、ユーザーが検索アイコンをクリックすると、inputTextコンポーネントが検証されます。図4-8に示すように、inputTextコンポーネントが必須としてマークされているため、値がないと、検証が失敗し、エラーがスローされます。

図4-8 値が必須のためにスローされる検証エラー

ただし、4.3.1項「immediate属性と最適化されたライフサイクルの使用について」で推奨されている解決策(LOVコンポーネントのimmediate属性をtrueに設定し、LOVでValueChangeリスナーを使用する)では、検証エラーは修正されません。LOVコンポーネントでは、ValueChangeEventがキューイングされるのは、LOVコンポーネントの値が変更された場合のみです。このため、ユーザーが検索アイコンをした時点で、ADF LaunchPopupEventはimmediate属性の値に関係なく、アプリケーションの起動フェーズで常にキューイングされるため、ユーザーが検索アイコンをクリックするときにimmediate属性をtrueに設定しても影響はありません。つまり、最適化されたライフサイクルは、ルートおよびターゲット・コンポーネントの両方で通常どおりに実行されるため、入力コンポーネントによって検証エラーがスローされます。

ユーザーが「値リスト」ポップアップから新しい値を選択すると、LOVコンポーネントによって2つのイベントがキューイングされます。1つはValueChangeEventで、コンポーネントの値の変更を通知します。2つ目は、アプリケーションの起動フェーズでキューイングされるReturnPopupEventで、アプリケーション・メソッドで選択を処理できます。これらのイベントは両方とも、LOVが予想どおり動作できるように発生する必要があります。

前述のように、LOVコンポーネントがValueChangeEventをキューイングするのは、ユーザーが新しい値を選択した場合のみです。LOVコンポーネントでimmediate属性をtrueに設定すると、このイベントはリクエスト値の適用フェーズでキューイングされ、新しい値が検証されます。また、LOVコンポーネントでValueChangeListenerメソッドを作成し、その実装でレスポンスのレンダリング・フェーズにジャンプして、入力コンポーネントの検証を回避すると、図4-9に示すように、選択した値はモデルにプッシュされず、アプリケーションの起動フェーズでReturnPopupListenerがコールされることもなく、ターゲット入力コンポーネントが新しい値で更新されることもありません。

図4-9 更新されないモデル

LOVコンポーネントを入力コンポーネントの部分トリガーとして宣言的に設定して、ValueChangeListenerにメソッドを作成するかわりに、ValueChangeEventおよびReturnPopupEventの両方を同じリクエストの一部としてキューイングし、新しく選択した値でターゲット・フィールドをリフレッシュする必要があり、この問題を解決するには、ReturnPopupEventにリスナーを作成する必要があります。このリスナーでは、LOVの部分ターゲットとして入力コンポーネントをプログラムで設定する必要があります。ReturnPopupListenerメソッドが実行されるまで、入力コンポーネントはLOVのターゲットにならないため、LOVのimmediate属性をtrueに設定する必要はなく、このため、ライフサイクルが実行されないので、検証が失敗しますリスナー・メソッドはValueChangeEventではなく、ReturnPopupEventに使用されるため、両方のイベントをキューイングして、モデルを適切に更新できます。

例4-8に、LOVおよびコンポーネントで必要なページ・コードを示します。

例4-8

<af:inputListOfValues label="Ename" id="lov1"
value="#{validateLOV.ename}" autoSubmit="true"
returnPopupListener="#{validate.processReturnPopup}"
Title="Search and Select: Ename" searchDesc="Choose a name"
model="#{validateLOV.listOfValuesModel}"
validator="#{validateLOV.validate}"/>
<af:inputText label="Empno" value="#{validateLOV.empno}" required="true"
id="lovDependent1" binding="#{validate.lovDependent1}"/>

入力コンポーネントでは、そのbinding属性を使用して、インスタンスをバッキングBeanに保存し、リスナー・メソッドからインスタンスにアクセスできます。例4-9に示すように、リスナー・メソッドは入力コンポーネントにアクセスし、LOVの部分ターゲットとして設定します。

例4-9

AdfFacesContext.getCurrentInstance().addPartialTarget(_lovDependent1)

部分ページ・レンダリングのプログラムによる設定の詳細は、7.3項「部分ページ・レンダリングのプログラムによる有効化」を参照してください。

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

ADF Facesフレームワークでは、クライアント側の変換と検証が提供されます。サーバーに送信する必要なく、JavaScriptベースの独自のコンバータとバリデータを作成してページで実行できます。

クライアント側検証を使用できるため、特定のクライアント・イベントがキューイングされると、適切なフォームまたはサブフォームのクライアント検証がトリガーされます(サブフォームの詳細は、4.5項「サブフォームを使用したページでの領域の作成」を参照)。このクライアント検証が失敗した場合(既知のエラー)、通常サーバーに伝播されるイベント(フォームの送信時のコマンド・ボタンのactionEventなど)がサーバーに送られません。イベントが配信されないということは、なにも送信されないということでもあり、クライアント・リスナーはコールされません。これは、サーバーで検証が失敗すると、ライフサイクルがレスポンスのレンダリング・フェーズに移り、キューイングされるがアクション・イベントが配信されず、actionListenerハンドラ・メソッドがコールされないという意味では、サーバー側検証と同様です。

たとえば、ADF Facesで入力コンポーネントにrequired属性を用意し、この検証がクライアントで実行されるとします。この属性をtrueに設定すると、コンポーネントの値がnullの場合、フレームワークでページにエラーが表示され、サーバーへの送信は必要ありません。例4-10に、inputTextコンポーネントのrequired属性をtrueに設定し、actionListener属性がマネージドBeanのメソッドにバインドされているコマンド・ボタンを含むコードを示します。

例4-10 簡単なクライアント側検証の例

<af:form>
<af:inputText id="input1" required="true" value="a"/>
<af:commandButton text="Search" actionListener="#{demoForm.search}"/>
</af:form>

このページを実行した場合、inputTextコンポーネントの値のフィールドをクリアし、フィールドからタブ移動すると、フィールドが赤い縁取りで再表示されます。フィールドをクリックすると、図4-10に示すように、値が必要なことを示すエラー・メッセージが表示されます。サーバーへの送信はなく、エラーの検出とメッセージの生成はすべてクライアントで行われます。

図4-10 クライアント側検証でサーバーへの送信なしにエラーを表示

この例では、値のフィールドをクリアし、「検索」ボタンをクリックすると、必須フィールドが空でエラーが発生するため、ページが送信されず、アクション・イベントも配信されず、アクション・リスナーにバインドされているメソッドは実行されません。検証がサーバーで失敗することがクライアントでわかっている場合は、ページを送信する必要はないため、この処理は必要です。

クライアント側の検証と変換の詳細は、第6章「入力の検証および変換」を参照してください。

4.5 サブフォームを使用したページでの領域の作成

JSF参照実装では、ページの領域を別個に送信する場合、複数のフォームを使用する必要があります。ただし、複数のフォームにはページの状態の複数のコピーが必要なため、送信されないフォームでのユーザーの編集内容が失われる可能性があります。

ADF Facesには、別個に送信可能なページの領域を示すサブフォーム・コンポーネントのサポートが追加されています。サブフォームのコンテンツは、サブフォーム内のコンポーネントでページの送信を行う場合にのみ、検証(または処理)されるため、別のフォーム要素を使用するという妥協をすることなく、検証され、モデルへプッシュされるコンポーネントをきめ細かく制御できます。サブフォームを使用するページの送信時に、ページの状態が一度だけ書き込まれ、すべてのユーザー編集内容が保持されます。

ベスト・プラクティス:

常にページごとに1つのみのformタグを使用します。複数のformタグを使用する必要がある場合は、subformタグを使用します。

サブフォームでは、リクエスト値の適用フェーズが子コンポーネントで常に(ページがサブフォーム外のコンポーネントで送信された場合でも)実行されます。ただし、検証の処理およびモデル値の更新フェーズは省略されます(これは、通常のフォーム・コンポーネントと異なり、送信されない場合、リクエスト値の適用フェーズは実行できません)。サブフォーム外のコンポーネントで送信アクションが行われたときにサブフォームのコンポーネントで検証の処理およびモデル値の更新フェーズを処理できるようにするには、default属性を使用します。サブフォームのdefault属性をtrueに設定すると、他のサブフォームとほぼ同様に動作しますが、ページのどのサブフォームでも適切なイベントが子コンポーネントで発生しない場合、defaultがtrueに設定されているサブフォームは、子コンポーネントの1つで送信が行われた場合と同様に動作します。サブフォームの詳細は、9.2項「formの定義」を参照してください。

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

実行時、ページがデータにアクセスできるオブジェクト・スコープに必要なデータを格納することで、データをページに渡します。スコープによってオブジェクトの存続期間が決まります。オブジェクトをスコープに置くと、EL式を使用してスコープからアクセスできます。たとえば、fooという名前のマネージドBeanを作成し、Beanをリクエスト・スコープに存続させるよう定義するとします。このBeanにアクセスするには、#{requestScope.foo}という式を使用します。

標準JSFアプリケーションには、次の3種類のスコープがあります。

- applicationScope: オブジェクトは、アプリケーションの間使用できます。

- sessionScope: オブジェクトは、セッションの間使用できます。

- requestScope: オブジェクトは、HTTPリクエストが送信されてから、レスポンスがクライアントに返るまでの間使用できます。

標準JSFスコープに加え、ADF Facesには次のスコープが用意されています。

- pageFlowScope: オブジェクトは、ユーザーがあるページから別のページへのナビゲートを続けるかぎり使用できます。ユーザーが新たなブラウザ・ウィンドウを開いてナビゲートを始めた場合、そのウィンドウで別のpageFlowScopeスコープを持ちます。

- backingBeanScope: ページ・フラグメントと宣言コンポーネントのみに対するマネージドBeanに使用します。オブジェクトは、HTTPリクエストが送信されてから、レスポンスがクライアントに返るまでの間使用できます。このスコープは、複数のページ・フラグメントと宣言コンポーネントがページにある場合があり、値の競合を避けるために別々のスコープ・インスタンスに値を保持するために必要です。backingBeanScopeスコープは、ページ・フラグメントまたは宣言コンポーネントに作成されたすべてのマネージドBeanに使用します。

- viewScope: オブジェクトは、現在のビューのIDが変更されるまで使用できます。viewScopeスコープを使用して特定のページの値を保持します。

注意:

これらは標準JSFスコープではないため、EL式には、Beanを参照するためのスコープを明示的に含める必要があります。たとえば、pageFlowScopeスコープからMyBeanマネージドBeanを参照するには、#{pageFlowScope.MyBean}という式になります。

オブジェクト・スコープは、プログラミング言語のグローバル変数およびローカル変数のスコープに相当します。スコープが広いほど、オブジェクトの可用性が高くなります。存続期間の間、これらのオブジェクトで特定のインタフェースの公開、情報の保持および他のオブジェクトへの変数とパラメータの受渡しを行うことができます。たとえば、sessionScopeスコープに定義されているマネージドBeanは、複数のページ・リクエストの間使用できます。しかし、requestScopeスコープに定義されているマネージドBeanは、1つのページ・リクエストの間のみ使用できます。

図4-11に、各タイプのスコープが有効な期間およびページ・フローとの関係を示します。

図4-11 スコープとページ・フローの関係

マネージドBeanを登録するスコープまたは値を格納するスコープを決める場合、可能なかぎり狭いスコープを常に使用するようにします。sessionScopeスコープは、ユーザー情報やコンテキスト情報などのセッション全体に関係する情報にのみ使用します。あるページから別のページへの値の受渡しには、sessionScopeスコープは使用しないようにします。

注意:

フルFusionテクノロジ・スタックを使用している場合、様々な構成ファイルにマネージドBeanを登録するためのオプションがあります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のFusion WebアプリケーションでのマネージドBeanの使用に関する項を参照してください。

4.7 ページ間の値の受渡し

注意:

フルFusionテクノロジ・スタックを使用していて、ADFバインド・タスク・フローのページ間またはADFリージョンとページの間での値の受渡しについての情報が必要な場合は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFタスク・フローの概説」を参照してください。

ADF FacesのpageFlowScopeスコープを使用すると、あるページから別のページへの値の受渡しが簡単になるため、マスター/ディテール・ページをより簡単に開発できます。pageFlowScopeスコープに追加された値は、ユーザーがあるページから別のページにナビゲートしても、自動的に継続して使用可能になり、これは、redirectディレクティブを使用している場合にも当てはまります。ただし、sessionスコープとは異なり、これらの値を表示できるのは、現在のページ・フローまたはプロセス内のみです。ユーザーが新しいブラウザ・ウィンドウを開いてナビゲートを開始すると、その一連のウィンドウは独自のプロセスを持ちます。各ウィンドウに格納された値は独立したままです。

標準JSFスコープに格納されているオブジェクト同様、pageFlowスコープに格納されているオブジェクトもEL式を介してアクセスできます。pageFlowスコープとの唯一の違いは、オブジェクト名にpageFlowScope接頭辞を使用する必要があることです。たとえば、ボタンのラベルをpageFlowスコープに格納されているマネージドBeanで指定し、ボタンが選択されるとBeanのメソッドがコールされるようにする場合は、ページに次のコードを使用します。

<af:commandButton text="#{pageFlowScope.buttonBean.label}"
action="#{pageFlowScope.buttonBean.action}"/>

pageFlowScopeは、Javaコードからアクセスされるjava.util.Mapオブジェクトです。setPropertyListenerタグでスコープにプロパティ値を設定したり、タグがリスニングするイベントも定義できます。たとえば、type属性をactionに設定したsetPropertyListenerタグを使用すると、ナビゲーション前にアクション・ソース(commandButtonなど)で値を設定する宣言的方法が提供されます。pageFlowScopeスコープとsetPropertyListenerタグを組み合せて使用して、バッキングBeanにJavaコードを記述することなく、あるページから別のページへ値を受け渡すことができます。たとえば、setPropertyListenerタグとコマンド・コンポーネントを使用してpageFlowScopeスコープに値を設定するページと、テキスト・コンポーネントでpageFlowScopeスコープを使用して値を取得する別のページを持つことができます。

pageFlowScopeスコープを使用して、ダイアログなどの2つ目のウィンドウ間で値を設定することもできます。commandButtonコンポーネントなどから2つ目のウィンドウを起動する場合、launchEventイベントおよびpageFlowScopeスコープを使用して、親プロセスの値をオーバーライドせずに2つ目のウィンドウとの間で値を受け渡すことができます。

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

pageFlowスコープは、アプリケーションのJavaコード内からアクセスできます。終了したら、スコープを必ずクリアしてください。

注意:

アプリケーションでADFコントローラが使用されている場合は、スコープを手動でクリアする必要はありません。

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();

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

Javaコードを記述せずにpageFlowScopeスコープを使用するには、setPropertyListenerタグとコマンド・コンポーネントを組み合せて使用し、スコープに値を設定します。setPropertyListenerタグでは、リスニングするイベント・タイプを定義するtype属性を使用します。このタイプに合致しないイベントはすべて無視されます。設定後は、ページ・フロー内の別のページからその値にアクセスできます。

ヒント:

(以前のバージョンのADF Facesで使用されていた可能性がある)setActionListenerタグを使用するかわりに、setPropertyListenerタグを使用し、イベント・タイプをactionに設定します。

pageFlowScopeスコープに値を設定する手順:

1. 値の設定元のページで、コンポーネント・パレットを使用してコマンド・コンポーネントを作成します。

2. コンポーネント・パレットの「操作」パネルから、「プロパティ・リスナーの設定」をコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。
または、コンポーネントを右クリックし、「ボタンの中に挿入」→「ADF Faces」→「setPropertyListener」を選択します。

3. 「プロパティ・リスナーの設定の挿入」ダイアログで、「自」フィールドに別のコンポーネントに設定される値を設定します。
たとえば、従業員の名前を格納するMyBeanという名前のマネージドBeanがあり、次のページに値を受け渡すとします。「自」フィールドに#{myBean.empName}と入力します。

4. 「至」フィールドにpageFlowScopeスコープでの値を設定します。

たとえば、「至」フィールドに#{pageFlowScope.empName}と入力します。

5. 「タイプ」ドロップダウン・メニューから「アクション」を選択します。
これによって、リスナーで、コマンド・コンポーネントに関連付けられているアクション・イベントをリスニングできます。

pageFlowScopeスコープから値にアクセスする手順:

1. 値のアクセス元のページに、値を表示するコンポーネントをドロップします。

2. コンポーネントの値を、setPropertyListenerタグで設定したTo値と同じ値に設定します。
たとえば、outputTextコンポーネントで従業員名にアクセスするには、このコンポーネントの値を#{pageFlowScope.empName}に設定します。

4.7.3 実行時の処理: 値の受渡し

setPropertyListenerタグを含むコマンド・コンポーネントをユーザーがクリックすると、リスナーが実行され、To値が解決されて取得され、その後、プロパティとしてpageFlowScopeスコープに格納されます。EL式を使用してそのプロパティにアクセスする後続のページで、式は元のページで設定された値に解決されます。

5 イベントの処理

この章では、サーバーおよびクライアントでのイベントの処理方法について説明します。

この章では、次の項目について説明します。

- 5.1項「イベントおよびイベント処理の概要」

- 5.2項「ADF Facesサーバー・イベントの使用」

- 5.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」

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

- 5.5項「イベント・レスポンス内でのスクリプトの実行」

- 5.6項「クライアントの動作タグの使用」

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

5.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ベースの機能(部分ページ・レンダリング)

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

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

標準JSFイベントとは異なり、ADF FacesイベントではAJAXスタイルの部分ポストバックがサポートされ、部分ページ・レンダリング(PPR)が行えます。フル・ページ・レンダリングのかわりに、ADF Facesのイベントおよびコンポーネントでは、リクエスト時にページの一部のみがリフレッシュされる部分ページ・レンダリングがトリガーされます。

特定のコンポーネントがイベント・ルート・コンポーネントとみなされます。イベント・ルート・コンポーネントによってページでの境界が決まり、その境界内のコンポーネントにのみライフサイクルが実行されます(ライフサイクルのこの機能の詳細は、4.3項「最適化されたライフサイクルの使用」を参照)。イベント・ルート内でイベントが発生すると、ルートの子であるこれらのコンポーネントのみがページでリフレッシュされます。イベント・ルート・コンポーネントの例はポップアップです。ポップアップ内でイベントが発生すると、ポップアップとその子のみが再レンダリングされ、ページ全体は再レンダリングされません。

また、特定のイベントは、特定のコンポーネントがイベント・ルート・コンポーネントであることを示します。たとえば、showDetailコンポーネントを展開または縮小する(8.8項「コンテンツの動的な表示および非表示」を参照)と送信される表示イベントは、showDetailコンポーネントがルートであることを示します。ライフサイクルはshowDetailコンポーネント(および子コンポーネントまたはこれをトリガーとするその他のコンポーネント)でのみ実行され、展開または縮小時にのみが再レンダリングされます。

表5-1に、ADF Facesでのイベント・タイプと、ソース・コンポーネントがイベント・ルートかどうかを示します。

表5-1 イベントとイベントのルート・コンポーネント

イベント・タイプ

コンポーネントのトリガー先

イベント・ルートか

action

すべてのコマンド・コンポーネント

false

dialog

dialog

false

disclosure

showDetail、showDetailHeader

true

disclosure

showDetailItem

true

focus

tree、treeTable

true

launch

すべてのコマンド・コンポーネント

NA

launchPopup

inputListOfValues、inputComboboxListOfValues

true

load

document

NA

poll

poll

true

popupOpened

popup

NA

popupOpening

popup

NA

popupClosed

popup

NA

propertyChange

すべてのコンポーネント

NA

queryEvent

query、quickQuery

true

queryOperation

query、quickQuery

true

rangeChange

table

NA

regionNavigation

region

NA

return

すべてのコマンド・コンポーネント

true

returnPopupData

inputListOfValues、inputComboboxListOfValues

true

returnPopup

inputListOfValues、inputComboboxListOfValues

true

rowDisclosure

tree、treeTable

true

selection

tree、treeTable、table

true

sort

treeTable、table

true

valueChange

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)

true

ヒント:

イベント・ルートを処理したときにイベント・ルートの外部にあるコンポーネントを処理する必要がある場合は、それらのコンポーネントのpartialTrigger属性をイベント・ルート・コンポーネントのIDに設定する必要があります。

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

サーバー側のアクションおよび値変更イベントの他に、ADF Facesコンポーネントでは、クライアント側のアクションおよび値変更イベント、その他のサーバーおよびクライアント・イベントが起動されます。サーバー・コンポーネントとクライアント・コンポーネントの両方で生成されるイベント(選択イベントなど)も、サーバー・コンポーネントでのみ生成されるイベント(起動イベントなど)も、クライアント・コンポーネントでのみ生成されるイベント(ロード・イベントなど)もあります。

デフォルトでは、ほとんどのクライアント・イベントはサーバーに伝播されます。コンポーネントの状態の変更は、状態に矛盾がないよう自動的にサーバーと同期され、必要に応じてイベントがサーバーに送信され、追加処理が実行されます。ただし、イベントが伝播されないように構成できます。

また、サーバー側Javaコンポーネントにクライアント側イベント・リスナーを登録すると、RCFでJavaScriptコンポーネントが必要であるとみなされ、クライアント側コンポーネントが作成されます。

クライアント側JavaScriptイベントのソースはいくつかあります。DOMイベントやプロパティ変更イベントから自動的に導出されることもあれば、他のイベントの処理時に手動で作成することもできます。

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

ADF Facesには、多数のサーバー側イベントが用意されています。表5-2に、サーバーのADF Facesコンポーネントで生成されるイベントと、これをトリガーするコンポーネントを示します。

表5-2 ADF Facesサーバー・イベント

イベント

トリガー元コンポーネント

ActionEvent

すべてのコマンド・コンポーネント

DialogEvent

dialog

DisclosureEvent

showDetail、showDetailHeader、showDetailItem

FocusEvent *

tree、treeTable

LaunchEvent

すべてのコマンド・コンポーネント

LaunchPopupEvent

inputListOfValues、inputComboboxListOfValues

LoadEvent **

document

PollEvent

poll

QueryEvent

query、quickQuery

QueryOperationEvent

query、quickQuery

RangeChangeEvent

table

RegionNavigationEvent

region

ReturnEvent

すべてのコマンド・コンポーネント

ReturnPopupEvent

inputListOfValues、inputComboboxListOfValues

RowDisclosureEvent

tree、treeTable

SelectionEvent

tree、treeTable、table

SortEvent

treeTable、table

ValueChangeEvent

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)

*このフォーカスイベントは、特定のサブツリーがフォーカスされると生成され、クライアント側のキーボード・フォーカス・イベントとは異なります。

**LoadEventイベントは、初期ページの表示後に起動されます(データ・ストリーミング結果が遅れて到着する場合があります)。

すべてのサーバー・イベントには、関連付けられたコンポーネントに対するイベント・リスナーがあります。そのイベントを処理するハンドラを作成し、そのハンドラ・コードをコンポーネントのリスナーと関連付ける必要があります。

たとえば、File Explorerアプリケーションの場合、ユーザーが表の行を選択すると選択イベントが起動されます。表のselectionListener属性は、TableContentView.javaマネージドBeanのtableSelectFileItemハンドラ・メソッドにバインドされているため、このメソッドがイベントに対応して起動されます。

サーバー側イベントを処理する手順:

1. マネージドBean(イベント・リスナーを使用するページの場合はバッキングBean)に、イベント(イベント・タイプ)を唯一のパラメータとし、voidを返すpublicメソッドを作成します。例5-1に、tableSelectFileItemハンドラのコードを示します。(マネージドBeanの作成と使用の詳細は、2.6項「マネージドBeanの作成と使用」を参照してください。)

例5-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とメソッドを選択します。
例5-2に、選択イベント・リスナー・メソッドをtableコンポーネントに登録するサンプル・コードを示します。

例5-2 イベント・リスナー・メソッドの登録

<af:table id="folderTable" var="file"
. . .
rowSelection="single"
selectionListener="#{explorer.tableContentView.tableSelectFileItem}"
. . .
</af:table>

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

大部分のコンポーネントはクライアント側イベントでも使用できます。クライアントでイベントを処理すると、サーバーへのラウンドトリップが不要になります。クライアント側イベントを使用する場合、マネージドBeanにイベント・ハンドラ・コードを含めるかわりに、JavaScriptを使用し、コール元ページにもJavaScriptライブラリにも含めることができます。

デフォルトでは、クライアント・イベントはクライアントでのみ処理されます。ただし、ボタンがクリックされたことを示すAdfActionEventイベントのようにサーバーに配信されるイベント・タイプもあります。コンポーネントの状態に応じてサーバーに配信されるイベントもあります。たとえば、AdfValueChangeEventイベントは、autoSubmit属性がtrueに設定されている場合サーバーに配信されます。追加処理が不要な場合は、イベントのサーバーへの配信を取り消すことができます。ただし、取り消すことができないクライアント・イベントもあります。たとえば、popupOpenedイベント・タイプは、ポップアップ・ウィンドウが開くと配信されるため、このイベントのサーバーへの配信は取り消すことができません。

パフォーマンスのヒント:

イベントのサーバーでの処理が不要な場合、イベントがサーバーに伝播されないよう、処理の最後にイベントを取り消すことを検討してください。詳細は、5.3.5項「イベントがサーバーに伝播されないようにする方法を参照してください。

表5-3に、ADF Facesクライアント・コンポーネントで生成されるイベント、イベントがサーバーに送信されるかどうか、イベントが取消し可能かどうか、およびイベントをトリガーするコンポーネントをリストします。

表5-3ADF Facesクライアント・イベント

イベント・タイプ

イベント・クラス

サーバーへの伝播

取消し可能

トリガー元コンポーネント

action

AdfActionEvent

◎

◎

すべてのコマンド・コンポーネント

dialog

AdfDialogEvent

◎

◎

dialog

ユーザーがダイアログでOKボタンまたは取消しボタンを選択したとき

disclosure

AdfDisclosureEvent

◎

◎

showDetail、showDetailHeader、showDetailItem

公開状態がユーザーによって切り替えられたとき

AdfFocusEvent

◎

◎

tree、treeTable

AdfLaunchPopupEvent

◎

◎

inputListOfValues、inputComboboxListOfValues

inlineFrameLoad

AdfDomComponentEvent

◎

◎

inlineFrame

内部のiframeでloadイベントが起動されたとき。

load

AdfComponentEvent

◎

◎

document

ドキュメントのコンテンツがクライアントで表示された後(PPPナビゲーションが使用されている場合も含む)。onLoad DOMイベントには常に対応しません。

AdfPollEvent

◎

◎

poll

popupOpened

AdfPopupOpenedEvent

×

×

popup

ポップアップ・ウィンドウまたはダイアログが開いた後

popupOpening

AdfPopupOpeningEvent

×

◎

popup

ポップアップ・ウィンドウまたはダイアログが開く前

popupClosed

AdfPopupClosedEvent

×

×

popup

ポップアップ・ウィンドウまたはダイアログが閉じた後

propertyChange

AdfPropertyChangeEvent

×

×

すべてのコンポーネント

query

AdfQueryEvent

◎

◎

query、quickQuery

問合せアクション時(ユーザーが検索アイコンまたは検索ボタンをクリックしたとき)

queryOperation

AdfQueryOperationEvent

◎

◎

query、quickQuery

AdfReturnEvent

◎

◎

すべてのコマンド・コンポーネント

AdfReturnPopupDataEvent

◎

◎

inputListOfValues、inputComboboxListOfValues

AdfReturnPopupEvent

◎

◎

inputListOfValues、inputComboboxListOfValues

rowDisclosure

AdfRowDisclosureEvent

◎

◎

tree、treeTable

行の公開状態が切り替えられたとき

selection

AdfSelectionEvent

◎

◎

tree、treeTable、table

選択状態が変わったとき

sort

AdfSortEvent

◎

◎

treeTable、table

ユーザーが表のデータをソートしたとき

touchStart
touchMove
touchEnd
touchCancel

AdfComponentTouchEvent

×

◎

すべて

valueChange

AdfValueChangeEvent

◎

◎

すべての入力および選択コンポーネント(EditableValueHolderを実装するコンポーネント)

入力または選択コンポーネントの値が変更されたとき

ADF Facesでは、表5-4に示すように、クライアント・キーボードおよびマウス・イベントもサポートします。

表5-4 サポートされるキーボードとマウスのイベント・タイプ

イベント・タイプ

イベントが発生するタイミング

click

ユーザーがコンポーネントをクリックしたとき

dblclick

ユーザーがコンポーネントをダブルクリックしたとき

mousedown

ユーザーがコンポーネント上でマウス・ボタンを押したとき

mouseup

ユーザーがコンポーネント上でマウス・ボタンを離したとき

mousemove

ユーザーがコンポーネント上でマウスを移動したとき

mouseover

コンポーネント内にマウスが移動したとき

mouseout

コンポーネントからマウスが移動したとき

keydown

コンポーネントのフォーカス中にユーザーがキーを押したとき

keyup

コンポーネントのフォーカス中にユーザーがキーを離したとき

keypress

コンポーネントのフォーカス中にキーを押す動作が正常に完了したとき

focus

コンポーネントがキーボード・フォーカスを得たとき

blur

コンポーネントがキーボード・フォーカスを失ったとき

ベスト・プラクティス:

キーボードとマウスのイベントは、AdfBaseEventクラスのAdfUIInputEventサブクラスを使用してネイティブDOMイベントをラップし、DOM本来のイベントへのアクセスだけでなく、キー・コード、マウス座標などを取得するための簡易関数も幅広く提供されます。AdfBaseEventクラスでは、これらのイベントの実装方法のブラウザ間の違いも考慮します。このため、getNativeEvent()メソッドを直接起動するのではなく、AdfUIInputEvent APIを使用する必要があります。

clientListenerタグによって、クライアント側イベント・ハンドラ・スクリプトをコンポーネントに登録する宣言的方法が提供されます。サポートされているクライアント・イベント・タイプが発生すると、スクリプトが起動されます。例5-3に、アクション・イベントに関連付けられているJavaScript関数の例を示します。

例5-3 clientListenerタグ

<af:commandButton id="button0"
text="Do something in response to an action">
<af:clientListener method="someJSMethod" type="action"/>
</af:commandButton>

ヒント:

コンポーネントのJavaScriptプロパティのかわりにclientListenerタグを使用します。

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

クライアント側イベントを使用するには、まず、イベントを処理するJavaScriptを作成する必要があります。次に、clientListenerタグを使用します。

クライアント側イベントを使用する手順:

1. JavaScriptイベント・ハンドラ関数を作成します。JavaScriptの作成の詳細は、3.3項「JavaScriptのページへの追加」を参照してください。この機能内で追加できるのは、次のとおりです。

- ページでのクライアント・コンポーネントの検索
イベント・ハンドラを別のコンポーネントで処理する場合、そのコンポーネントをページで検索する必要があります。たとえば、File Explorerアプリケーションでユーザーが「ヘルプ」メニューのフィードバック・メニュー項目を選択した場合、関連付けられているJavaScript関数でヘルプ・ポップアップ・ダイアログを開くには、このダイアログを検索する必要があります。クライアント・コンポーネントの検索の詳細は、3.5項「ページでのクライアント・コンポーネントの検索」を参照してください。

- イベントの発生元の戻し
ページに複数の同じコンポーネントがある場合、JavaScript関数でイベントを発行したコンポーネントを判断する必要があります。たとえば、同じポップアップ・ダイアログを開くことができる複数のコンポーネントがあり、コール元のコンポーネントと並べてそのダイアログを表示するとします。ポップアップ・ダイアログを並べる場所を決めるには、AdfLaunchPopupEventのソースが認識できる必要があります。詳細は、5.3.2項「イベントの発生元を返す方法」を参照してください。

- クライアント属性の追加
クライアント・イベント・ハンドラでコンポーネントの特定の属性を使用する必要が生じる場合があります。たとえば、File Explorerアプリケーションでユーザーが「ヘルプ」メニューの「バージョン情報」メニュー項目を選択すると、ユーザーがフィードバックを提供できるダイアログが起動します。このダイアログを開いて表示する関数は他のダイアログでも使用され、別個に表示する必要があります。このため、表示するダイアログとダイアログの配置情報を関数で認識できる必要があります。この情報はクライアント属性に保持されます。クライアント属性は、カスタムのサーバー側属性のクライアントへのマーシャリングにも使用できます。詳細は、5.3.3項「イベントのクライアント側属性の使用方法」を参照してください。

- サーバーへの伝播の取消し
表5-3に示すように、一部のコンポーネントではクライアント側イベントがサーバーへ伝播されます。この追加処理が不要な場合、伝播を取り消すことができます。詳細は、5.3.5項「イベントがサーバーに伝播されないようにする方法を参照してください。

2. JavaScript関数の作成後、イベント・メソッドをコールするイベント・リスナーを追加する必要があります。

注意:

また、ADF Facesコンポーネントのすべてのクライアント・イベントもクライアント動作として公開されるため、JSF 2.0クライアント動作タグ(f:ajaxなど)を使用して、クライアント・イベントに応答できます。詳細は、Java EE 6チュートリアル(http://download.oracle.com/javaee/index.html)を参照してください。

1. JavaScriptを起動するコンポーネントを選択し、プロパティ・インスペクタでClientComponentをtrueに設定します。

2. コンポーネント・パレットの「操作」パネルから、「クライアント・リスナー」を、選択したコンポーネントの子としてドラッグ・アンド・ドロップします。

3. 「クライアント・リスナーの挿入」ダイアログでメソッドを入力し、JavaScript関数のタイプを選択します。
clientListenerタグのmethod属性で、対応するイベントが発生したときにコールするJavaScript関数を指定します。JavaScript関数は1つのパラメータ(イベント・オブジェクト)をとる必要があります。

clientListenerタグのtype属性で、action、valueChangeなどのタグでリスニングするクライアント・イベント・タイプを指定します。表5-3に、ADF Facesクライアント・イベントを示します。

clientListenerタグのtype属性では、キーボードおよびマウスのイベントに関連するクライアント・イベント・タイプもサポートされます。表5-4に、キーボードとマウスのイベント・タイプを示します。

例5-4に、Explorer.js JavaScriptファイルのshowHelpFileExplorerPopup関数の起動に使用されるコードを示します。

例5-4 JSFページのclientListenerタグ

<af:commandMenuItem id="feedbackMenuItem"
text="#{explorerBundle['menuitem.feedback']}"
clientComponent="true">
<af:clientListener method="Explorer.showHelpFileExplorerPopup"
type="action"/>
</af:commandMenuItem>

4. コンポーネント・パレットの「操作」パネルからクライアント属性をドラッグして選択したコンポーネントの子としてドロップし、必要な属性を追加します。プロパティ・インスペクタで属性の名前と値を入力します。例5-5に、showAboutFileExplorerPopup関数の属性値の設定に使用されるコードを示します。

例5-5 属性の追加

<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>

注意:

attributeタグ(clientAttributeタグではなく)を使用して、アプリケーション固有の属性やボーナス属性をサーバー・コンポーネントに追加した場合、これらの属性は、対応するクライアント・コンポーネントに含まれません。JSFページでclientAttributeタグを使用すると、サーバーとクライアントの両方で値が使用可能になります。クライアント値のサーバーへのポストバックの詳細は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。ボーナス属性の詳細は、3.8項「クライアント側コンポーネントに対するボーナス属性の使用」を参照してください。

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

JavaScriptメソッドgetSource()は、クライアント・イベントの発生元を返します。たとえば、File Explorerアプリケーションには、例5-6に示すshowAboutFileExplorerPopup関数が含まれており、クライアント属性を使用して値が受け渡され、特定のポップアップ・ダイアログまたはウィンドウの位置合せの設定に複数のイベントで使用できます。関数を使用する各イベントで属性の値が異なる場合があるため、対応する属性値にアクセスできるようイベントの発生元を関数で認識する必要があります(クライアント属性の使用の詳細は、5.3.3項「イベントのクライアント側属性の使用方法」を参照してください)。

例5-6 クライアント・イベントのソース・コンポーネントの検出

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()メソッドがコールされ、現在のフォーカス・イベントを発生したクライアント・コンポーネント(このケースではポップアップ・コンポーネント)が決まります。

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

スクリプトのロジックでコンポーネントになんらかの変更を加える場合があります。これを行うには、イベントによって受け渡される属性値が必要な場合があります。たとえば、File Explorerアプリケーションには、例5-7に示すshowAboutFileExplorerPopup関数が含まれており、クライアント属性を使用して値が受け渡され、特定のポップアップ・コンポーネントの位置合せの設定に使用できます。属性値には、ソース・コンポーネントでgetPropertyメソッドをコールしてアクセスします。

例5-7 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();
}

例5-8に示すように、値はソース・コンポーネントで設定されます。

例5-8 コンポーネントでの属性の設定

<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>

このように属性を使用すると、同じイベントをトリガーする異なるコンポーネントでスクリプトを再利用できます。

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

実行時間が長いイベントの処理中に、ユーザーがUIを操作できないようにする場合があります。たとえば、アプリケーションがボタンを使用して命令を送信し、処理の一部にユーザーのアカウントに対する請求を作成する処理が含まれているとします。ユーザーが不注意でボタンを2回押した場合、そのアカウントは2回請求されることになります。サーバーの処理が完了するまでユーザーの操作をブロックすることで、誤ったクライアント・アクティビティが発生しないようにできます。

ADF Faces JavaScript APIには、AdfBaseEvent.preventUserInput関数が含まれています。preventUserInput関数をコールすると、ブラウザ・ウィンドウ全体がガラス・ペインで覆われ、イベントがサーバーへのラウンドトリップを完了するまで入力できなくなり、イベントの処理中にすべてのユーザー入力を阻止できます。

preventUserInput関数は、カスタム・イベント、カスタム・クライアント・スクリプトで発生したイベント、またはカスタム・クライアント・コンポーネントのピアで発生したイベントでのみ使用できます。また、イベントをサーバーに伝播する必要があります。例5-9に、JavaScriptでpreventUserInputを使用する方法を示します。

例5-9 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);
}

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

一部のクライアント・イベントは、クライアントでの処理が完了すると、デフォルトでサーバーに伝播されます。この伝播が行われないようにすることが必要な状況もあります。たとえば、ボタンがクリックされるとJavaScriptコードを実行するcommandButtonコンポーネントを使用している場合、サーバーにactionListenerイベント・リスナーがなければ、イベントを伝播することはリソースを無駄に消費することになります。サーバーへ伝播されないようにするには、リスナーでイベントのcancel()関数をコールします。cancel()関数がコールされると、isCanceled()関数でtrueが返されます。

例5-10に、伝播を取り消すshowAboutFileExplorerPopup関数を示します。

例5-10 クライアント・イベントのサーバーへの伝播の取消し

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が返されることで示されます(取り消せないイベントは、表5-3で「取消し可能」列に「×」と表示されています)。これは、イベントが完了済の通知で、ブロックできないということを通常意味します。一度取り消したイベントの取消しを無効にすることもできません。

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

イベント処理は、一般にブラウザのネイティブ・イベント・ループから捕捉されます。ページでは、ドキュメントにバブル・アップされるすべてのDOMイベントを受け取り、そのDOMに関連付けられているピアに渡します。ピアでは、DOMイベントをラップするリッチ・クライアントJavaScriptイベント・オブジェクトが作成され、ページに返され、イベントがキューイングされます(ピアとADF Facesアーキテクチャの詳細は、第3章「ADF Facesアーキテクチャの使用」を参照してください)。

各DOMイベントのページでの処理(この結果、通常コンポーネント・イベントがキューイングされる)後、ページのイベント・キューは、通常ブラウザのイベント・ループの最後で空になります。ただし、タイマー起動時にポーリング・イベントを発生するポーリング・コンポーネントなど、ユーザー入力とは無関係にイベントがキューイングされることがあるため、イベントをキューイングすると、ユーザー入力がなくても、イベント・キューを空にするタイマーも起動されます。

イベント・キューは先入れ先出しキューです。イベント・キューを空にするには、ページで各イベント・オブジェクトを捕捉し、イベント・ソースのbroadcast()関数に配信します。このループは、キューが空になるまで続きます。イベントのブロードキャストによって、導出された新規イベントのキューイングが間接的に引き起こされることは非常に理にかなっています(一般的です)。導出されたイベントは、同じループでブロードキャストされます。

イベントがコンポーネントにブロードキャストされると、コンポーネントで次の処理が行われます。

1. イベントをピアのDispatchComponentEventメソッドに配信します。

2. そのイベント・タイプ用に登録されているリスナーにイベントを配信します。

3. イベントをバブルする必要があるかどうかを確認し、必要な場合はバブルを開始します。ほとんどのイベントがバブルされます。例外には、プロパティ変更イベント(キューイングされず、このプロセスにまったく関与しない)やマウスの移動イベント(効率を高めるため)があります。
イベントがバブルされる時、イベントはAdfUIComponentのHandleBubbledEvent関数に配信され、ここからピアのDispatchComponentEvent関数に渡されます。クライアント・イベント・リスナーではなく、ピアがイベントを受け取ることに注意してください。

イベントのバブルは、イベントのstopBubbling()関数をコールしてブロックでき、その後、isBubblingStopped()関数でtrueが返され、バブルが止まります。取消し同様、このコールは元に戻すことはできません。

注意:

イベントを取り消してもバブルは止まりません。イベントの取消しとバブルの停止の両方を行う場合は、両方の関数をコールする必要があります。

4. 前述の処理でイベントが取り消されない場合は、AdfUIComponent.HandleEventメソッドをコールします。このメソッドでは、イベントでのリクエストに応じてイベントがサーバー・イベント・キューに追加されます。

5.3.7 ネーミング・コンテナの使用について

ADF Facesのいくつかのコンポーネントは、pageTemplate、subform、tableおよびtreeなどのNamingContainerコンポーネントです。NamingContainerコンポーネントを含むページでクライアント側APIとイベントを使用する場合、ソース・コンポーネントでfindComponent()メソッドを使用する必要があります。

たとえば、File Explorerアプリケーション内のページのコンポーネントはすべて最終的にはpageTemplateコンポーネント内にあるため、例5-11に示すように、JavaScript関数でgetSource()とfindComponent()メソッドを使用する必要があります。getSource()メソッドはAdfUIComponentクラスにアクセスし、コンポーネントの検出に使用できます。

例5-11 findComponent()メソッドを使用するJavaScript

function showPopup(event)
{
event.cancel();
var source = event.getSource();
var popup = source.findComponent("popup");
popup.show({align:"after_end", alignId:"button"});
}

findComponent()メソッドを使用すると、メソッドを起動したコンポーネントでローカルに検索が開始します。ネーミング・コンテナの使用の詳細は、3.5項「ページでのクライアント・コンポーネントの検索」を参照してください。

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

clientAttributeタグでは、サーバーからクライアントへのボーナス属性の送信はサポートされますが、これらの属性のサーバーへの同期化は行われません。カスタム・データをサーバーに戻すには、AdfCustomEventクラスとserverListenerタグを使用して送信されるカスタム・イベントを使用します。

AdfCustomEvent.queue() JavaScriptメソッドによって、clientComponent属性がtrueに設定されているコンポーネントからカスタム・イベントを起動できます。カスタム・イベント・オブジェクトには、クライアント・イベント・ソースと、イベントに含まれるパラメータのマップに関する情報が含まれます。カスタム・イベントは即時配信(リクエスト値の適用フェーズ中)にも非即時配信(アプリケーションの起動フェーズ中)にも設定できます。

たとえば、File Explorerアプリケーションでは、ユーザーは左側の検索フィールドにファイル名を入力した後、[Enter]キーを押して検索を起動します。例5-12 に示すように、これは、inputTextフィールドに、[Enter]キーが押されると、JavaScript関数を起動するclientListenerが含まれているためです。

例5-12 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}に解決されるメソッドが起動されます。

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

クライアントからサーバーへカスタム・イベントを送信するには、カスタム・イベント・タイプを使用してクライアント・イベントを起動し、バッキングBeanにサーバー・リスナー・メソッドを記述し、このメソッドでカスタム・イベントを処理する必要があります。次に、サーバー・リスナーをコンポーネントに登録します。

カスタム・イベントを送信する手順:

1. イベント・ソース、カスタム・イベント・タイプおよびサーバーに送信するパラメータを指定してAdfCustomEvent.queue()メソッドを使用し、カスタム・イベントを処理するJavaScriptを作成します。
たとえば、[Enter]キーが押されると検索機能を起動するJavaScriptでは、例5-13に示すようなイベント・ソース、カスタム・イベント・タイプとして文字列enterPressedOnSearch、nullパラメータ・マップ、即時パラメータとしてFalseをとるAdfCustomEvent.queueメソッドを使用します。

例5-13 カスタム・イベント用のサンプル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型を返します。例5-14に、別のメソッドをコールして検索を実行し、ナビゲータをリフレッシュするだけのSearchNavigatorViewマネージドBeanに使用されるコードを示します。

例5-14 カスタム・クライアント・イベント用サーバー・リスナー・メソッド

public void searchOnEnter(ClientEvent clientEvent)
{
doRealSearchForFileItem();

// refresh search navigator
this.refresh();
}

注意:

JavaからJavaScriptへの変換では、Numbers、chars、Java Objects、arraysおよび文字列でないCharSequencesの型情報が失われます。このため、サーバーに送信されるオブジェクトが初めはサーバーにある場合、変換が正しく行われるようにするロジックを追加します。5.4.3項「データのマーシャリングとアンマーシャリングについて」を参照してください。

3. コンポーネント・パレットの「操作」パネルからクライアント・リスナーをドラッグしてイベントが発生するコンポーネントの子としてドロップし、clientListenerを登録します。

注意:

カスタム・クライアント・イベントを発生させるコンポーネントでは、クライアント側で生成されたコンポーネントが使用可能になるよう、clientComponent属性をtrueに設定します。

4. 「クライアント・リスナーの挿入」ダイアログでメソッドを入力し、JavaScript関数のタイプを入力します。スクリプトがページに含まれていない場合はライブラリ名を必ず含めます。タイプはカスタム・イベントの識別に使用される任意の文字列が可能で、たとえば、File ExplorerではenterPressedOnSearchが使用されています。

5. コンポーネント・パレットの「操作」パネルからサーバー・リスナーをドラッグしてclientListenerタグの兄弟としてドロップし、サーバー・リスナーを登録します。

6. 「サーバー・リスナーの挿入」ダイアログで、enterPressedOnSearchなどのこのサーバー・リスナーに対する値としてクライアント・リスナーのタイプ値に使用される文字列を入力します。
プロパティ・インスペクタで、2で作成したメソッドに解決される式をmethod属性に入力します。

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

実行時、[Enter]キーを押すなど、ユーザーによってイベントが発生すると、クライアント・リスナー・スクリプトが実行されます。このスクリプトでAdfCustomEvent.queue()メソッドをコールし、指定したイベント・タイプのカスタム・イベントが入力コンポーネントのキューに置かれます。入力コンポーネントに登録されているサーバー・リスナーがカスタム・イベントを受け取り、関連付けられているBeanメソッドが実行されます。

5.4.3 データのマーシャリングとアンマーシャリングについて

マーシャリングとアンマーシャリングとは、プログラミング言語のデータ・オブジェクトをバイト・ストリームに変換し、同じプログラミング言語または別のプログラミング言語にネイティブのデータ・オブジェクトに戻すプロセスです。ADF Facesでは、マーシャリングとアンマーシャリングは、クライアント・エンドのJavaScriptとサーバー・エンドのJavaとの間で適切にやりとりできるようデータを適切な形式に変換することです。クライアントがブラウザベースの場合、JavaScript Object Notation(JSON)およびXMLの2つが一般的なマーシャリング方法です。ADF Facesでは両方の方法を組み合せて使用し、情報は、サーバーからクライアントには主にJSONで、クライアントからサーバーにはXMLで送信されます(JSONの詳細は、http://www.json.orgを参照してください)。

JavaScriptからJavaへ情報を送信する場合、JavaScriptデータ・オブジェクトはXMLに変換され(マーシャリング)、サーバー側で解析してJavaオブジェクトに戻されます(アンマーシャリング)。たとえば、cmdというIDのcommandButtonコンポーネントを含むJSFページを考えてみます。ユーザーがcommandButtonコンポーネントをクリックしたとき、このcommandButtonによってactionEventが発生したことをクライアントからサーバーに通信する必要があります。requestParameterマップで、情報がevent + . + id(idはコンポーネントのID)という形式を使用したキーにマップされます。つまり、commandComponentのrequestParameterマップ・キーは、キーevent.cmdの値として格納されているXML文字列です。

この例でマーシャリング後のXMLフラグメントは次のようになります。

<m xmlns="http:/oracle.com/richClient/comm"><k v="type"><s>action</s></k></m>

例のmは、これがマップにアンマーシャルされることを表します。kはキーであることと、値がString型であることを表します。サーバー側でXMLフラグメントが、type(java.lang.String)をキーとし、action(java.lang.String)を値とする1つのエントリのjava.util.Mapに解析されます。

アンマーシャリングされた情報は、クライアントIDごとにまとめられ、リクエスト・マップに格納されてコンポーネントのデコード時に使用されます。この例では、commandButtonがデコードされるとき、クライアントID(event.cmd)を使用してクライアント・イベントがあるかどうかが確認され、検出された場合はアクションがキューイングされます(デコード動作は、commandButtonコンポーネントのレンダラ階層で実装されます)。

表5-5に、JavaScript型と対応するJava型のマッピングを示します。

表5-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

JavaからJavaScriptへのマーシャリングは、ほとんどの場合JSONを使用して行われます。JSONがJavaScriptでのオブジェクト・リテラル表記法であるため、この種のマーシャリングは明らかです。クライアント・コンポーネントのプロパティは通常JSONでエンコードされます。次の例を考えてみます。

new AdfRichCommandButton('demoTemplate:richComand'
{'partialSubmit':true,'useWindow':false})

2番目の引数({'partialSubmit':true,'useWindow':false})はJSONオブジェクトです。JSONがオブジェクトとして直接JavaScript環境に解析されるため、ブラウザ・エンドでの追加のアンマーシャリング処理が不要です。

表のエンコードでも、JSONを使用してプッシュ・メッセージをクライアントに渡します。エンコードされた1つのプッシュ・メッセージを含むエンベロープの例を次にしまします。

[{'rKey':'0','type':'update','data':[{'val':'Active Data Every Second: on row 0:78','prop':'value','cInd':0},{'val':'Active Data Every Second: on row 0:78','prop':'value','cInd':1}]}]

エンベロープは、1つのオブジェクトのみを含むJavaScript Arrayで、メッセージを表します。このメッセージには、変更のタイプ、データの実際の値などの情報が含まれ、クライアント側の表ピアで使用され、表自体が更新されます。

表5-6に、Java型と対応するJavaScript型のマッピングを示します。

表5-6Javaと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に変換されます。

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

ExtendedRenderKitServiceクラスを使用すると、アクション・メソッド・バインディングの起動後などのイベント・レスポンスにJavaScriptを追加できます。これは、ユーザーにデータベース接続が確立できないことを通知するアラートの送信などの簡単なメッセージの場合もあれば、プログラムからポップアップ・ダイアログを終了させるためのポップアップ・ウィンドウでのhide()などの関数のコールの場合もあります。

たとえば、File ExplorerアプリケーションでユーザーがUpOneFolderナビゲーション・ボタンをクリックしてフォルダ構造を上に移動すると、フォルダ・ペインが再描画されて、選択した親フォルダが表示されます。UpOneFolderボタン・イベントのクリックを受けてHandleUpOneFolder()メソッドがコールされます。ExtendedRenderKitServiceクラスを使用してJavaScriptがレスポンスに追加されます。

例5-15に、actionListener属性が、ボタンがクリックされたときにアクション・イベントを処理するHandleUpOneFolder()ハンドラ・メソッドにバインドされているページのUpOneFolderコードを示します。

例5-15 JavaScriptをレスポンスに追加するメソッドの起動

<af:commandToolbarButton id="upOneFolder"
. . .
actionListener="#{explorer.headerManager.handleUpOneFolder}"/>

例5-16に、ExtendedRenderKitServiceクラスを使用するhandleUpOneFolderメソッドを示します。

例5-16 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();
}

}

5.6 クライアントの動作タグの使用

クライアント側での動作を実装する場合、通常はJavaScriptを記述し、それをクライアント・リスナーとしてコンポーネントに登録する必要がありますが、ADF Facesのクライアント動作タグを使用すると、一般的なクライアント操作を宣言的に実行できます。JavaScriptコードを記述するかわりにこれらのタグを使用して同じ処理を実装すると、ブラウザにダウンロードする必要のあるJavaScriptコードの量が少なくなります。

ADF Facesでは、クライアント・リスナーのかわりに使用できるクライアント動作タグが用意されています。

- panelDashboardBehavior: 応答性を向上させるために、実行時にpanelDasboardコンポーネントに子コンポーネントを挿入できます。詳細は、8.7.1項「panelDashboardコンポーネントの使用方法」を参照してください。

- insertTextBehavior: コマンド・コンポーネントで、inputTextコンポーネントのカーソル位置にテキストを挿入できます。詳細は、9.3.2項「inputTextコンポーネントへのテキストの挿入機能の追加方法」を参照してください。

- richTextEditorInsertBehavior: コマンド・コンポーネントで、richTextEditorコンポーネントのカーソル位置にテキスト(事前フォーマット済テキストを含む)を挿入できます。詳細は、9.8.2項「richTextEditorコンポーネントへのテキストの挿入機能の追加方法」を参照してください。

- showPopupBehavior: コマンド・コンポーネントでポップアップ・コンポーネントを起動できます。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

- showPrintablePageBehavior: コマンド・コンポーネントで、ページの印刷可能版を生成して表示できます。詳細は、33.2項「印刷用のページの表示」を参照してください。

- scrollComponentIntoViewBehavior: クリックして、コマンド・コンポーネントから名前付きのコンポーネントに移動できます。詳細は、5.6.1項「scrollComponentIntoViewBehaviorタグの使用方法」を参照してください。

クライアント動作タグで、サーバー側イベント配信が自動的に取り消されます。したがって、親コンポーネントのactionListenerまたはaction 属性が無視されます。これは無効にすることができません。サーバー側の機能もトリガーする場合は、クライアント側イベントを使用する(5.3項「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照)か、AdfCustomEventおよびaf:serverListenerを使用してサーバー側イベントを配信するクライアント・リスナーを追加します(5.4項「「クライアントからサーバーへのカスタム・イベントの送信」を参照)。

5.6.1 scrollComponentIntoViewBehaviorタグの使用方法

ユーザーがページの特定のコンポーネントに移動できるようにする場合は、scrollComponentIntoViewBehaviorタグを使用します。このアクションは、HTMLのアンカーと似ています。たとえば、commandLinkコンポーネントを使用して、ユーザーがページの特定の部分に移動できるようにできます。richTextEditorおよびinlineFrameコンポーネントの場合は、サブコンポーネントに移動できます。たとえば、図5-1は、そのテキストに多数のセクションがあるrichTextEditorコンポーネントを示しています。エディタの下にあるコマンド・リンクを使用すると、テキストの特定部分に移動できます。

図5-1 エディタのscrollComponentIntoViewBehaviorタグ

ユーザーがスクロールしたコンポーネントにフォーカスを切り替えるためのタグを構成することもできます。

scrollComponentIntoViewBehaviorタグを使用する手順:

1. ユーザーがクリックして、指定されたコンポーネントに移動するコマンド・コンポーネントを作成します。手順は、18.2.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。

2. コンポーネント・パレットの「操作」セクションから、「コンポーネントのビュー内へのスクロール動作」をコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。

3. 「コンポーネントのスクロール表示動作の挿入」ダイアログで、ドロップダウン矢印を使用して「編集」を選択し、移動してユーザーの移動先であるコンポーネントを選択します。

4. 移動後にコンポーネントにフォーカスを設定する場合は、プロパティ・インスペクタで、focus属性をtrueに設定します。

5. richTextEditorまたはinlineFrameコンポーネントの場合は、オプションで、subTargetId属性の値を入力します。このIDは、richTextEditorまたはinlineFrameコンポーネントの値で定義されています。
たとえば、図5-1に示されているscrollComponentIntoViewBehaviorタグのsubTargetId属性の値は、Introductionです。richTextEditorの値は、例5-17に示されているプロパティにバインドされています。Introductionは最初のヘッダーのIDです。

例5-17 プロパティに定義されている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>";

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

ADF Facesでは、pollEventを使用して、指定した間隔でサーバーと通信できるポーリング・コンポーネントが提供されます。たとえば、ポーリング・コンポーネントを使用して、outputTextコンポーネントを更新したり、サーバーにハートビートを配信して、それらのセッションがタイムアウトするのを防ぐことができます。

ポーリング時に必要な処理を実行するのに使用されるpollEventに、リスナーを作成する必要があります。たとえば、ポーリング・コンポーネントを使用してoutputTextコンポーネントの値を更新する場合は、データ・ソースの値をチェックしてからコンポーネントを更新するpollEventListenerメソッドを実装します。

間隔時間を設定し、ポーリング・コンポーネントがそのポーリング・イベントを配信する頻度を決定できます。ページがタイムアウトするまでの時間を設定することもできます。これは、ページでのポーリングによりセッションがタイムアウトしないようにする場合に便利です。リクエストがサーバーに送信されるたびに、セッションのタイムアウト値がページに書き込まれ、セッションをいつタイムアウトするかが決定されます。ポーリング・コンポーネントは(間隔時間に基づいて)サーバーにリクエストを送信し続けるため、セッションがタイムアウトすることはありません。これは、ネットワークの使用とメモリーの両方で非効率になります。

この問題を回避するには、web.xml構成ファイルにoracle.adf.view.rich.poll.TIMEOUTコンテキスト・パラメータを含めます(タイムアウトするまでのページの実行時間を指定します)。キーボードまたはマウスのアクティビティがない場合、ページはタイムアウトできるとみなされます。デフォルトのタイムアウト時間は10分です。このため、ユーザーのアクティビティが10分間ない場合(キーボードやマウスを使用しない時間)は、フレームワークによりポーリングが停止され、その時点から、ページは標準のサーバ側セッション・タイムアウトに入ります(詳細は、A.2.3.19項「セッション・タイムアウトの警告」を参照)。

アプリケーションがタイムアウトした場合、ユーザーがマウスを移動したり、キーボードを再度使用すると、新しいセッション・タイムアウト値がページに書き込まれ、ポーリングが再開します。

ポーリング・コンポーネントのtimeout属性を使用して、特定のページでこのタイムアウトをオーバーライドできます。

5.7.1 ポーリング・コンポーネントの使用方法

ポーリング・コンポーネントを使用する場合、ポーリング・イベントの機能を処理するには、通常ハンドラ・メソッドも作成します。

開始前

属性が機能に与える影響について理解しておくと役立ちます。詳細は、5.7項「ポーリング・イベントを使用したページの更新」を参照してください。

ポーリング・コンポーネントを使用する手順:

1. マネージドBeanで、ポーリング・コンポーネントのハンドラを作成します。マネージドBeanの詳細は、2.6項「マネージドBeanの作成と使用」を参照してください。

2. コンポーネント・パレットの「操作」パネルから、「ポーリング」をドラッグ・アンド・ドロップして、ポーリング・コンポーネントを作成します。

3. プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。

- Interval: ポーリング・イベント間の時間を入力します(ミリ秒)。ポーリングを無効にするには0に設定します。

- PollListener: 手順1のメソッドに評価されるEL式を入力します。

4. web.xmlファイルのグローバル・タイムアウト値をオーバーライドする場合は、「その他」セクションを開き、「タイムアウト」に、ページがポーリングを停止してセッションがタイムアウトするまでの時間(ミリ秒)を設定します。

6 入力の検証および変換

この章では、アプリケーションのADF Faces入力コンポーネントに変換と検証の機能を追加する方法について説明します。エラー(検証によって生じたもの以外も)の処理および表示方法についても説明します。

この章では、次の項目について説明します。

- 6.1項「ADF Facesの変換および検証の概要」

- 6.2項「変換、検証とJSFライフサイクル」

- 6.3項「変換の追加」

- 6.4項「カスタムJSFコンバータの作成」

- 6.5項「検証の追加」

- 6.6項「カスタムJSF検証の作成」

6.1 ADF Facesの変換および検証の概要

ADF Facesの入力コンポーネントでは、変換機能がサポートされます。Webアプリケーションで、int、long、dateなどの様々な型をモデル・レイヤーに格納できます。ただし、クライアント・ブラウザに表示する場合、ユーザー・インタフェースでは、ユーザーが読んだり、変更できる形式でデータを示す必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが日付フィールドを編集してフォームを送信すると、文字列はアプリケーションで必要な型に戻されます。その後、ルールまたは条件に対してデータが検証されます。逆に、String以外の型として格納したデータを表示および更新用にStringに変換することもできます。af:inputDateなどの多くのコンポーネントで、変換機能が自動的に提供されます。

ADF Facesの入力コンポーネントでは、検証機能もサポートされます。入力コンポーネントのrequired属性がtrueに設定されている場合、1つ以上のバリデータ属性を設定したり、ADF Facesバリデータ・コンポーネントを使用できます。また、ビジネス・ニーズに応じてカスタム・バリデータを作成することもできます。

バリデータとコンバータには、ユーザーが関連付けられているフィールドをクリックすると表示されるデフォルトのヒント・メッセージがあります。コンバータの場合、ヒントは、通常、入力値に使用する、指定されたパターンに基づいた適切な形式をユーザーに示します。バリデータの場合、ヒントを使用して、コンポーネントに構成されている検証に基づいた有効な値が示されます。変換または検証に失敗すると、関連付けられたエラー・メッセージがユーザーに表示されます。これらのメッセージはダイアログに表示することも、変換または検証に失敗したコンポーネントと並べてページ自体に表示することもできます。ADF Facesアプリケーションでのメッセージの表示の詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

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

データを持つフォームが送信されると、編集可能なvalue属性がバインドされているUIコンポーネントごとに、リクエスト値がブラウザからサーバーに送信されます。リクエスト値は、JSFのリクエスト値の適用フェーズでデコードされ、デコードされた値はコンポーネントのsumbittedValue属性にローカルに保存されます。値に変換が必要(Stringとして表示されるが、DateTimeオブジェクトとして格納されている場合など)な場合、データは、UIコンポーネントごとに検証の処理フェーズで正しい型に変換されます。

検証または変換に失敗した場合、ライフサイクルはレスポンスのレンダリング・フェーズに進み、対応するエラー・メッセージがページに表示されます。変換および検証が正常に終了すると、モデルの更新フェーズが開始され、変換および検証された値がモデルの更新に使用されます。

検証または変換エラーが起きた場合、検証または変換に失敗したコンポーネントで、関連付けられたエラー・メッセージがキューに置かれ、コンポーネント自身は無効とされます。その後、現在のページがエラー・メッセージを使用して再表示されます。ADF Facesのコンポーネントには、これらのメッセージを宣言的に設定する方法が用意されています。

JSFライフサイクルで使用される変換と検証の方法の詳細は、第4章「ADF FacesによるJSFライフサイクルの使用」を参照してください。

6.3 変換の追加

Webアプリケーションは、モデル・レイヤー内に多くのタイプのデータ(int、long、dateなど)を格納できます。ただし、クライアント・ブラウザに表示する場合、ユーザー・インタフェースでは、ユーザーが読んだり、変更できる形式でデータを示す必要があります。たとえば、フォームの日付フィールドでは、java.util.Dateオブジェクトをmm/dd/yyyy形式のテキスト文字列で表します。ユーザーが日付フィールドを編集してフォームを送信すると、文字列はアプリケーションで必要な型に戻されます。その後、ルールまたは条件に対してデータが検証されます。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

表6-1に、ADF Facesで用意されているコンバータを示します。

表6-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

表6-1のコンバータとは異なり、JavaScript対応のコンバータはtypeが適用されて、標準のコンバータのかわりに使用され、classおよびid属性をオーバーライドします。これらのコンバータには、コンポーネント内にネストできるタグは関連付けられていません。

一部のoracle.jbo.domainデータ型は自動的に変換されます。自動的に処理されない一部のoracle.jbo.domainデータ型では、6.3.4項「oracle.jbo.domainコンバータを追加する方法」の説明に従って、oracle.jbo.domainコンバータをコンポーネントに追加できます。

6.3.1 標準ADF Facesコンバータを追加する方法

UIコンポーネントにコンバータを手動で挿入できます。

タグを持つADF Facesコンバータを追加する手順:

1. 構造ウィンドウで、コンバータを追加するコンポーネントを右クリックします。

2. ポップアップ・メニューで「<UIコンポーネント>の中に挿入」を選択し、ADF Facesコンバータを挿入する場合は「ADF Faces」を、JSFコンバータを挿入する場合は「JSF Core」を選択します。

3. コンバータ・タグ(ConvertDateTimeなど)を選択します。

4. プロパティ・インスペクタで、変換エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
複数のパターンを設定できるADF Facesコンバータもあります。詳細は、6.3.2項「標準のADF Facesコンバータでの属性の設定方法」を参照してください。

ADF Facesでは、変換エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailconvertDateなどの変換エラー・タイプ)に値を設定することにより、変換に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。メッセージの作成の詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

6.3.2 標準のADF Facesコンバータでの属性の設定方法

パターンは、変換で使用可能なデータの形式を指定します。複数のパターンを使用すると、複数の形式を使用できます。たとえば、スラッシュ(/)またはハイフン(-)をセパレータとして使用する日付を入力できます。パターン・マッチングは柔軟性の高いものですが、すべてのコンバータで複数のパターンがサポートされるわけではなく、複数のパターンが必要ない場合もあります。

例6-1に、af:convertColorタグに対する複数パターンの使用を示します。「255-255-000」と「FFFF00」の両方の値が使用可能です。

例6-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>

例6-2に、「6/9/2007」と「2007/9/6」の両方が使用可能なaf:convertDateTimeタグの使用を示します。

例6-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>

例6-3に、type属性がcurrencyに設定されており、$78.57と$078.57を変換の値として使用できるaf:convertNumberタグを示します。

例6-3 通貨属性が設定されているaf:convertNumber

<af:inputText label="type=currency" value="#{validate.currency}">
<af:convertNumber type="currency"/>
</af:inputText>

6.3.3 実行時の処理

ユーザーがコンバータを含むページを送信すると、ADF Facesのvalidate()メソッドでコンバータのgetAsObject()メソッドがコールされ、String値が必要なオブジェクト・タイプに変換されます。アタッチされているコンバータがなく、コンポーネントがモデルのBeanプロパティにバインドされている場合、ADFでモデルのデータ型を確認して適切なコンバータを見つけます。変換に失敗すると、コンポーネントのvalue属性がfalseに設定され、JSFでFacesContextによってメンテナンスされているキューにエラー・メッセージが追加されます。変換が正常終了し、コンポーネントにアタッチされているバリデータがある場合、変換された値がバリデータに渡されます。コンポーネントにアタッチされているバリデータがない場合、変換された値はローカル値として格納され、モデルの更新に後で使用されます。

6.3.4 oracle.jbo.domainコンバータを追加する方法

自動的に処理されない一部のoracle.jbo.domainデータ型では、コンポーネントのoracle.jbo.domainコンバータを参照する必要があります。これらのコンバータは自動的に登録され、タグは不要です。

表6-2に、oracle.jbo.domainデータ型のコンバータのリストを示します。

表6-2 oracle.jbo.domainデータ型のコンバータ

oracle.jbo.domainコンバータ

説明

ordDomainConverter

oracle.jbo.domain.ordデータ型を処理します。

genericDomainConverter

汎用oracle.jbo.domainデータ型を処理します。

oracle.jbo.domainコンバータを追加する場合は、例6-4に示すように、コンバータをconverter属性に追加できます。

例6-4 コンバータ属性を使用したgenericDomainコンバータの追加

<af:inputText  ...  converter="oracle.genericDomain"/>

または、例6-5に示すように、f:converterタグを追加して、converterId属性を使用してコンバータを参照できます。

例6-5 f:converterを使用したgenericDomainコンバータの追加

<af:inputText ...
<f:converter converterId="oracle.genericDomain"/>
</af:inputText>

6.4 カスタムJSFコンバータの作成

特定のビジネス・ニーズに合せて、独自のコンバータを作成できます。サーバー側で実行されるカスタムJSFコンバータを作成してから、クライアント側で実行できるJavaScriptバージョンを作成することもできます。ただし、カスタム・バリデータを作成する場合とは異なり、作成できるのはコンバータ・クラスのみです。変換を提供するためにメソッドをバッキングBeanに追加することはできません。

6.4.1 カスタムJSFコンバータの作成方法

カスタム・コンバータの作成には、getAsObject()およびgetAsString()メソッドを含むConverterインタフェースの実装を作成し、カスタム・コンバータをアプリケーションに登録して、変換用のビジネス・ロジックを記述する必要があります。次に、f:converterタグを使用して、カスタム・コンバータをそのタグのプロパティとして設定するか、または入力コンポーネントのconverter属性を使用して、そのコンバータにバインドできます。

クライアント側バージョンのコンバータを作成することもできます。ADF Facesのクライアント側コンバータは、クライアントでJavaScriptが使用される点以外は、サーバーでの標準JSF変換と同様に機能します。JavaScriptコンバータ・オブジェクトでは、ConverterException例外をスローでき、getAsObject()およびgetAsString()メソッドがサポートされます。

カスタム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){
..
}

これらのクラスの詳細は、APIドキュメントを参照するか、http://download.oracle.com/docs/cd/E17410_01/javaee/index.htmlを参照してください。

2. 必要な変換ロジックを追加します。このロジックでは、javax.faces.convert.ConverterExceptionを使用して適切な例外をスローし、javax.faces.application.FacesMessageを使用して対応するエラー・メッセージを生成します。ConverterインタフェースとFacesMessageエラー・ハンドラの詳細は、javax.faces.convert.ConverterExceptionおよびjavax.faces.application.FacesMessageのAPIドキュメントまたはhttp://download.oracle.com/docs/cd/E17410_01/javaee/index.htmlを参照してください。

3. アプリケーションでクライアントに状態を保存する場合、カスタム・コンバータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照してください。

4. コンバータをfaces-config.xmlファイルに登録します。

- faces-config.xmlファイルを開き、エディタ・ウィンドウで「概要」タブを選択します。faces-config.xmlファイルは、JDeveloperアプリケーション・ナビゲータの<View_Project>/WEB-INFディレクトリにあります。

- ウィンドウで、「コンバータ」を選択し、「新規」をクリックします。コンバータの登録の詳細ヘルプを参照するには、「ヘルプ」をクリックするか、[F1]キーを押します。

コンバータのクライアント版を作成する手順:

- JavaScript版のコンバータを記述し、関連する情報をコンストラクタに渡します。例6-6に、2つのメソッドを持つorg.apache.myfaces.trinidad.convert.ClientConverterインタフェースを実装するコードを示します。1つ目のメソッドはgetClientScript()で、JavaScriptのConverterオブジェクトの実装を返します。2つ目のメソッドはgetClientConversion()で、コンバータ・インスタンスのインスタンス化に使用されるJavaScriptコンストラクタを返します。

例6-6 インタフェース・コンバータ

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){}

TrConverterインタフェースではTrConverterException例外をスローでき、これにはTrFacesMessageエラー・メッセージが含まれます。例6-7にTrFacesMessageのシグネチャを、例6-8にTrFacesExceptionのシグネチャを示します。

例6-7 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
)

例6-8 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

例6-9に、カスタム・コンバータの例(サーバーで実行され、Javaで記述されるSimpleNumberConverter)を示します。カスタム・コンバータはClientConverterインタフェースを実装する必要があります。

例6-9 Javaのカスタム・コンバータSimpleNumberConverter

public class SimpleNumberConverter implements javax.faces.convert.Converter,
org.apache.myfaces.trinidad.convert.ClientConverter
{
public SimpleNumberConverter(boolean isInteger)
{
_isInteger = isInteger;
}

// CONVERTER INTERFACE
public Object getAsObject(FacesContext context, UIComponent component,
String value)
{
// convert to object
}

String getAsString(FacesContext context, UIComponent component, Object value)
{
// convert to string
}
// CLIENTCONVERTER INTERFACE
/**
* Called to retrieve the appropriate client
* conversion code for the node and context.
* For HTML, this will be javascript that will be embedded in a
* script tag. For HTML this method is expected to return a
* constructor of the javascript Converter object
* returned by getClientScript().
*/
public String getClientConversion(FacesContext context, UIComponent component)
{
return "new SimpleNumberConverter(" + Boolean.toString(_isInteger) + ")";
}
public Collection<String> getClientImportNames()
{
// return empty collection
}
public String getClientLibrarySource(FacesContext context)
{
return null;
}

public String getClientScript(FacesContext context, UIComponent component)
{
return null;
}

private boolean _isInteger;
}

例6-10に示すように、クライアントでもカスタム・コンバータのJavaScript実装を作成する必要があります。

Example 6-10 JavaScriptでのSimpleNumberConverterのクライアント側実装

/*** constructor of client side SimpleNumberConverter class*/function SimpleNumberConverter(isInteger){ this._isInteger = isInteger;}// Inherit object properties from base class if desired.SimpleNumberConverter.prototype = new SimpleConverter();SimpleNumberConverter.prototype.getAsString = function(number,label){ // convert to string}SimpleNumberConverter.prototype.getAsObject = function(numberString,label){ // convert to object}

JSFページでカスタム・コンバータを使用する手順:

- コンバータ・クラスを入力コンポーネントのconverter属性にバインドします。

注意:

カスタム・コンバータがアプリケーションで特定のデータ型のクラスの下に登録されると、カスタム・コンバータ・オブジェクトと同じ型の値バインディングがコンポーネント値で参照されるたびに、JSFでそのクラスのコンバータが値の変換に自動的に使用されます。この場合、次のコードに示すように、converter属性を使用してカスタム・コンバータをコンポーネントに登録する必要はありません。

<af:inputText value="#{myBean.myProperty}"/>

myPropertyデータ型は、カスタム・コンバータと同じ型を持ちます。

6.4.2 カスタム・コンバータを使用する場合の処理

カスタム・コンバータを使用すると、アプリケーションではconverter属性で参照されるコンバータ・クラスにアクセスし、必要に応じてgetAsObjectまたはgetAsStringメソッドを実行します。これらのメソッドでは、コンポーネントからのデータにアクセスし、変換ロジックを実行します。

6.5 検証の追加

ユーザーがフィールド内のデータを編集または入力してフォームを送信したときに、設定した規則および条件に対してデータが検証されるように、検証を追加できます。検証に失敗すると、アプリケーションでエラー・メッセージが表示されます。たとえば、図6-1では、af:validateDateTimeRangeコンポーネントによってユーザー入力に対する特定の日付範囲がメッセージ・ヒントに設定されており、無効な値が入力されると、メッセージ・ポップアップ・ウィンドウにエラー・メッセージが表示されます。

図6-1 エラー・メッセージ付き日付範囲バリデータ

クライアント側の検証が必要な場合、ビュー・レイヤーでADF Facesの検証を使用します。ADF Facesに用意されているすべてのバリデータは、クライアント側ピアを持ちます。多くのコンポーネントは、検証を提供する属性を持ちます。詳細は、6.5.1.2項「検証属性の使用を参照してください。また、ADF Facesには、クライアントおよびサーバーの両方で実行できる個別の検証クラスも用意されています。詳細は、6.5.1.3項「ADF Facesバリデータの使用」を参照してください。独自のバリデータを作成することもできます。カスタム・バリデータの詳細は、6.6.3項「カスタムJSFバリデータの作成方法」を参照してください。

6.5.1 検証の追加方法

入力コンポーネントにADF Faces検証を設定すると、エラー・メッセージがページにインラインで、またはポップアップ・ウィンドウに表示されます。検証エラーで作成されたメッセージの表示の詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

6.5.1.1 ADF Facesの検証の追加

デフォルトでは、ADF Facesの構文およびセマンティク検証は、クライアント側とサーバー側の両方で行われます。クライアント側の検証では、バリデータでデータを捕捉および表示し、サーバーへのラウンドトリップは不要です。

ADF Facesでは、次のタイプの検証が提供されます。

- UIコンポーネント属性: ADF Facesの入力コンポーネントに、データの検証に使用できる属性が用意されています。たとえば、値が必須かどうかを指定するには、ADF Facesの入力コンポーネントのrequired属性を使用して簡単な検証を指定できます。required属性をtrueに設定した場合、コンポーネントは値を持つ必要があります。そうでない場合、アプリケーションでエラー・メッセージが表示されます。詳細は、6.5.1.2項「検証属性の使用」を参照してください。

- デフォルトADF Facesバリデータ: JSFフレームワークで提供されるバリデータには、データ範囲の検証、入力されたデータの長さの検証などのよく使用される検証チェックが用意されています。詳細は、6.5.1.3項「ADF Facesバリデータの使用」を参照してください。

- カスタムADF Facesバリデータ: 独自のバリデータを作成し、UIコンポーネントと組み合せて使用するよう選択できます。詳細は、6.6項「カスタムJSF検証の作成」を参照してください。

6.5.1.2 検証属性の使用

ADF FacesのUIコンポーネントの多くは、シンプルな検証を提供する属性を持ちます。たとえば、af:chooseDateコンポーネントはaf:inputDateコンポーネントと組み合せて簡単な日付選択に使用されます。af:chooseDateコンポーネントには、日付値に使用できる最大値と最小値を指定するmaxValue属性とminValue属性があります。

UIコンポーネントのヘルプを参照するには、プロパティ・インスペクタで属性の名前を右クリックし、「ヘルプ」を選択します。

6.5.1.3 ADF Facesバリデータの使用

ADF Facesバリデータは、サーバーまたはクライアントで実行できる個別のクラスです。表6-3に、バリデータとそのロジックを示します。

表6-3 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タグを使用します。カスタム・バリデータの使用方法の詳細は、6.6項「カスタムJSF検証の作成」を参照してください。

ADF Facesバリデータを追加する手順:

1. 構造ウィンドウで、バリデータを追加するコンポーネントを右クリックします。

2. ポップアップ・メニューで「<UIコンポーネント>の中に挿入」を選択し、ADF Facesバリデータを挿入する場合は「ADF Faces」を、JSF参照実装バリデータを挿入する場合は「JSF Core」を選択します。

3. バリデータ・タグ(ValidateDateTimeRangeなど)を選択します。

4. プロパティ・インスペクタで、検証エラー用のメッセージなどの値を属性に設定します。ヘルプを参照するには、属性を右クリックし、「ヘルプ」を選択します。
ADF Facesでは、検証エラー・メッセージの詳細部分をカスタマイズできます。MessageDetailxyz属性(xyzはMessageDetailmaximumなどの検証エラー・タイプ)に値を設定することにより、検証に失敗した場合、デフォルト・メッセージのかわりに、ADF Facesでカスタム・メッセージが表示されます。

6.5.2 実行時の処理

ユーザーがページを送信すると、ADF Facesで送信された値を確認し、null以外の値に対して変換を実行します。変換された値は、validate()メソッドに渡されます。値が空の場合、コンポーネントのrequired属性が確認され、指定されている場合はエラー・メッセージが生成されます。送信された値がnull以外の場合、検証プロセスが続けられ、コンポーネントのすべてのバリデータが宣言順にコールされます。

注意:

ADF Facesでは、クライアント側サポートのある、JSFバリデータの拡張が提供されます。

ADF Faces検証が検証の処理フェーズで実行されます。エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。コンポーネントのすべての検証が終了すると、モデル・レイヤーに制御が移り、モデルの更新の検証フェーズが実行されます。検証の処理フェーズ同様、エラーが発生した場合、コンポーネントが無効化され、関連付けられているメッセージがFacesContextインスタンスのキューに追加されます。

ライフサイクルはレスポンスのレンダリング・フェーズに移り、現在のページが再表示されます。ADF Facesでは、af:messageコンポーネントのinline属性がtrueに設定されていないかぎり、エラーを生成した入力コンポーネントの隣にエラー・アイコンを表示し、ポップアップ・ウィンドウに関連付けられたメッセージを表示します。図6-2に、サーバー側の検証エラーを示します。

図6-2 サーバー側の検証エラー

6.5.3 複数バリデータについて

UIコンポーネントには、バリデータを設定しないことも、複数設定することもできます。コンポーネントのrequired属性を設定し、バリデータを使用することができます。ただし、required属性をtrueに設定し、値がnullまたは長さがゼロの文字列の場合、コンポーネントは無効化され、コンポーネントに登録された他のバリデータはコールされません。

コンポーネントが空でも有効になるケースが存在する場合は、この組合せでは問題があることがあります。たとえば、ページに「Cancel」ボタンが含まれている場合、ユーザーはデータを入力しなくても、そのボタンをクリックすればページを閉じることができるようにする必要があります。このようなケースを処理するには、「Cancel」ボタンのコンポーネントのimmediate属性をtrueに設定します。この属性により、アクションをリクエスト値の適用フェーズで実行できます。デフォルトのJSFアクション・リスナーはFacesContext.renderResponse()をコールするため、アクションの実行時に検証は省略されます。詳細は、第4章「ADF FacesによるJSFライフサイクルの使用」を参照してください。

6.6 カスタムJSF検証の作成

ビジネス・ニーズに合せて独自の検証ロジックを追加できます。1つのページのコンポーネントにカスタム検証ロジックが必要な場合、ページのバッキングBeanに検証メソッドを作成します。

アプリケーション内の様々なページで再利用されるロジックを作成する場合、またはクライアント側で検証を実行できるようにする場合は、JSFバリデータ・クラスを作成します。その後、クライアント側でバリデータを実行できるADF Faces版を作成します。

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

1つのページのコンポーネントにカスタム検証が必要な場合、必要な検証を提供するメソッドをバッキングBeanに作成します。

バッキング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のAPIドキュメントまたはhttp://download.oracle.com/docs/cd/E17410_01/javaee/index.htmlを参照してください。

6.6.2 バッキングBean検証メソッドを作成する場合の処理

検証メソッドを作成すると、選択したマネージドBeanにJDeveloperでスケルトン・メソッドが追加されます。例6-11に、JDeveloperで生成されるコードを示します。

例6-11 検証メソッド用のマネージドBeanのコード

public void inputText_validator(FacesContext facesContext,
UIComponent uiComponent, Object object) {
// Add event code here...
}

入力コンポーネントを含むフォームが送信されると、validator属性がバインドされているメソッドが実行されます。

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

カスタム・バリデータの作成には、インタフェースのValidator実装を作成し、カスタム・バリデータをアプリケーションに登録して、検証用のビジネス・ロジックを記述する必要があります。バリデータ用のタグを作成したり、f:validatorタグおよびカスタム・バリデータをこのタグの属性として使用することもできます。

クライアント側バージョンのバリエータを作成することもできます。ADF Facesのクライアント側検証は、クライアントでJavaScriptが使用される点以外は、サーバーでの標準の検証と同様に機能します。JavaScriptバリデータ・オブジェクトでは、ValidatorExceptions例外をスローでき、validate()メソッドがサポートされます。

カスタムJSFバリデータを作成する手順:

1. javax.faces.validator.Validatorインタフェースを実装するJavaクラスを作成します。Validatorインタフェースを実装するには、実装にpublic no-argsコンストラクタ、属性に対するアクセッサ・メソッドのセットおよびvalidateメソッドを含める必要があります。

public void validate(FacesContext facesContext,
UIComponent uiComponent,
Object object)
throws ValidatorException {
..
}

これらのクラスの詳細は、APIドキュメントを参照するか、http://download.oracle.com/docs/cd/E17410_01/javaee/index.htmlを参照してください。

2. 必要な検証ロジックを追加します。このロジックでは、javax.faces.validate.ValidatorException例外を使用して適切な例外をスローし、javax.faces.application.FacesMessageエラー・メッセージを使用して対応するエラー・メッセージを生成します。ValidatorインタフェースとFacesMessageの詳細は、javax.faces.validate.ValidatorExceptionおよびjavax.faces.application.FacesMessageのAPIドキュメントまたはhttp://download.oracle.com/docs/cd/E17410_01/javaee/index.htmlを参照してください。

3. アプリケーションでクライアントに状態を保存する場合、カスタム・バリデータでSerializableインタフェースまたはStateHolderインタフェースと、StateHolderインタフェースのsaveState(FacesContext)およびrestoreState(FacesContext, Object)メソッドを実装する必要があります。詳細は、Javadocでjavax.faces.componentパッケージのStateHolderインタフェースを参照してください。

4. バリデータをfaces-config.xmlファイルに登録します。

- faces-config.xmlファイルを開き、エディタ・ウィンドウで「概要」タブを選択します。faces-config.xmlは、<View_Project>/WEB-INFディレクトリにあります。

- ウィンドウで、「バリデータ」を選択し、「新規」をクリックします。バリデータの登録の詳細ヘルプを参照するには、「ヘルプ」をクリックするか、[F1]キーを押します。

バリデータのクライアント版を作成する手順:

1. JavaScript版のバリデータを記述し、関連する情報をコンストラクタに渡します。

2. 2つのメソッドを持つorg.apache.myfaces.trinidad.validator.ClientValidatorインタフェースを実装します。1つ目のメソッドはgetClientScript()で、JavaScriptのValidatorオブジェクトの実装を返します。2つ目のメソッドはgetClientValidation()で、バリデータ・インスタンスのインスタンス化に使用されるJavaScriptコンストラクタを返します。
例6-12に、Javaのバリデータを示します。

例6-12 Javaバリデータ

public String getClientValidation(
FacesContext context,
UIComponent component)
{
return ("new SSNValidator('Invalid social security number.','Value \"{1}\"
must start with \"123\".')");
}

Javaバリデータでは、例6-13に示すように、JavaScriptバリデータをコールします。

例6-13 クライアント側JavaScriptバリデータ

function SSNValidator(summary, detail)
{
this._detail = detail;
this._summary = summary;
}

JSFページでカスタム・バリデータを使用する手順:

- JSFページにタグを持つカスタム・バリデータを使用するには、これをコンポーネントのタグ内に手動でネストさせる必要があります。
例6-14に、inputTextコンポーネント内にネストするカスタム・バリデータ・タグを示します。タグ属性を使用して、faces-config.xmlファイルで宣言されたバリデータのプロパティの値を指定していることに注意してください。

例6-14 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. 構造ウィンドウから、検証を追加する入力コンポーネントを右クリックし、「<コンポーネント>の中に挿入」→「ADF Facesコア」→「バリデータ」を選択します。

2. ドロップダウン・リストからバリデータのIDを選択し、「OK」をクリックします。
バリデータのIDをf:validatorタグのプロパティにするコードが、JDeveloperでJSFページに挿入されます。

例6-15に、f:validatorタグを使用するバリデータのJSFページでのコードを示します。

例6-15 JSFページのコンポーネント内にネストするカスタム・バリデータ

<af:inputText id="empnumber" required="true">
<f:validator validatorID="emValidator"/>
</af:inputText>

6.6.4 カスタムJSFバリデータを使用する場合の処理

カスタムJSFバリデータを使用すると、アプリケーションでカスタム・タグまたはf:validatorタグで参照されるバリデータ・クラスにアクセスし、validate()メソッドを実行します。このメソッドでは、現在のFacesContextのコンポーネントからのデータにアクセスし、これに対してロジックを実行して、データが有効かどうかを判断します。バリデータに属性がある場合、この属性にもアクセスされ、検証ルーチンで使用されます。標準バリデータ同様、カスタム検証に失敗すると、関連付けられているメッセージがFacesContextインスタンスのメッセージ・キューに置かれます。

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

この章では、ADF Facesコンポーネントに用意されている部分ページ・レンダリング機能を使用して、ページ全体ではなく、ページの一部を再レンダリングする方法について説明します。

この章では、次の項目について説明します。

- 7.1項「部分ページ・レンダリングの概要」

- 7.2項「部分ページ・レンダリングの宣言的有効化」

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

- 7.4項「部分ページ・ナビゲーションの使用方法」

7.1 部分ページ・レンダリングの概要

Ajax(Asynchronous JavaScript and XML)は、対話型Webアプリケーションを作成するためのWeb開発手法で、Webページ全体を再レンダリングせずに少量のデータを内部的にサーバーと交換するため、Webページのレスポンスが向上します。その結果、Webページの対話性、速度および使い勝手が向上します。

ADF Facesでは、Ajaxの部分ページ・レンダリング動作を実現する機能を部分ページ・レンダリング(PPR)と呼びます。PPRを使用すると、ページ全体を再レンダリングせずにページ上の特定のコンポーネントをレンダリングできます。たとえば、ユーザーが入力コンポーネントで選択または入力した内容を出力コンポーネントで表示したり、コマンド・リンクまたはボタンでによって、ページ全体を再レンダリングせずにページ上の別のコンポーネントを再レンダリングできます。

PPRが機能するには、その中のコンポーネントでのみライフサイクルが実行される境界をページで設定する必要があります。境界を判断するために、処理するコンポーネントのルートをフレームワークに通知する必要があります。ルート・コンポーネントは、次の2つの方法で識別されます。

- イベント: 特定のイベントはルートであるコンポーネントを示します。たとえば、showDetailコンポーネントを展開または縮小する(8.8項「コンテンツの動的な表示および非表示」を参照)と送信される表示イベントは、showDetailコンポーネントがルートであることを示します。showDetailコンポーネントを展開または縮小すると、このコンポーネントでのみライフサイクルが実行されます。ルート・コンポーネントを識別するイベントの他の例には、ツリーのノード展開時の表示イベントまたは表のソート・イベントがあります。

- コンポーネント: 特定のコンポーネントは境界として認識されるため、ルート・コンポーネントになります。たとえば、フレームワークでは、ポップアップ・ダイアログが境界と認識されます。ダイアログ内でトリガーされたイベントに関係なく、ダイアログ外のコンポーネントでライフサイクルは実行されません。ポップアップでのみ実行されます。

ビルトインPPR機能以外に、クロスコンポーネント・レンダリング(あるコンポーネントがトリガーとして機能し、別のコンポーネントがリスナーとして機能するように依存性を設定可能)を使用するようにコンポーネントを構成できます。トリガー・コンポーネントでイベントが発生すると、リスナー・コンポーネントとリスナーの子コンポーネントでのみがライフサイクルが実行され、リスナー・コンポーネントと子のみが再レンダリングされます。クロスコンポーネント・レンダリングは、宣言的に実装できます。ただし、デフォルトでは、トリガー・コンポーネントからのすべてのイベントでPPRが実行されます(表などの一部のコンポーネントでは、イベントのサブセットでのみ部分ターゲットがトリガーされます)。PPRを起動するイベントを厳密に制御する必要がある場合、またはターゲットを決めるロジックを使用する場合は、プログラムでPPRを実装できます。

ヒント:

アプリケーションでFusionテクノロジ・スタックを使用する場合、任意のページで自動部分ページ・レンダリング機能を有効にできます。これによって、バックエンド・ビジネス・ロジックの結果として値が変更されるコンポーネントが自動的に再レンダリングされます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の自動部分ページ・レンダリングに関する項を参照してください。

また、ADF FacesアプリケーションでPPRをナビゲーションに使用できます。標準JSFアプリケーションでは、あるページから次のページへナビゲートすると、新しいページをレンダリングする必要があります。AJAX式のコンポーネントを使用している場合、異なるJavaScriptライブラリとスタイルシートのダウンロードに時間がかかるため、これによってオーバーヘッドが生じる可能性があります。このようなコストのかかるオーバーヘッドを避けるため、ADF Facesアーキテクチャでは、必要に応じてページ全体の遷移をシミュレートできますが、実際は1つのページにいるため、JavaScriptコードとスキン・スタイルを再ロードする必要がありません。

注意:

PPRが機能するには、ブラウザでJavaScriptが有効になっている必要があります。

7.2 部分ページ・レンダリングの宣言的有効化

最も単純なクロスコンポーネント・レンダリングを使用した場合、トリガー・コンポーネントと呼ばれるコンポーネントでイベントが発生すると、ターゲット・コンポーネントと呼ばれるコンポーネントが再レンダリングされます。

たとえば、図7-1に示すように、File Explorerアプリケーションには「検索」パネルに検索結果を表示する表が含まれています。検索ボタンを使用すると、この表(この表のみ)が再レンダリングされます。検索ボタンがトリガーとして構成され、表がターゲットとして構成されています。

図7-1 検索ボタンで再レンダリングされる表

注意:

トリガー・コンポーネントに関連付けられているすべてのイベントではなく、特定のイベントが発生したときのみ、コンポーネントを再レンダリングする場合や、コンポーネントを再レンダリングするかどうかを決定するロジックが必要な場合があります。この場合、プログラムでPPRを有効にします。詳細は、7.3項「部分ページ・レンダリングのプログラムによる有効化」を参照してください。

トリガー・コンポーネントで、PPRリクエストが発生したことをフレームワークに通知する必要があります。コマンド・コンポーネントでは、partialSubmit属性をtrueに設定することでこれを行えます。これを行うと、コマンド・コンポーネントがクリックされるたびに部分ページ・リクエストが発生します。

たとえば、ページにinputTextコンポーネント、commandButtonコンポーネントおよびoutputTextコンポーネントが含まれるとします。ユーザーがinputTextコンポーネントに値を入力してcommandButtonコンポーネントをクリックすると、入力値がoutputTextコンポーネントに反映されます。commandButtonコンポーネントのpartialSubmit属性をtrueに設定します。

ただし、コマンド・コンポーネント以外のコンポーネントでPPRをトリガーできます。ADF Facesの入力コンポーネントと選択コンポーネントには、値が変更されると部分ページ・リクエストを自動的にトリガーする機能があります。この機能を使用するには、入力または選択コンポーネントのautoSubmit属性を使用して、値が入力されて送信されたときに、valueChangeEventイベントが発生するようにします。ターゲット・コンポーネントが設定されているかぎり、フレームワークにPPRを実行するよう通知するのはこのイベントです。前述の例で、commandButtonコンポーネントを削除し、かわりにinputTextコンポーネントのautoSubmit属性をtrueに設定します。値が変更されるたびに、PPRリクエストが起動されます。

ヒント:

入力コンポーネントのautoSubmit属性とコマンド・コンポーネントのpartialSubmit属性は同じものではありません。partialSubmitがtrueに設定されている場合、partialTriggers属性に値を持つコンポーネントのみでライフサイクルが実行されます。autoSubmit属性は、入力コンポーネントと選択コンポーネントで使用され、値が変更されると自動的にフォームを送信するようフレームワークに指示します。ただし、フォームが送信され、autoSubmit属性がtrueに設定されている場合、valueChangeEventイベントが起動され、ライフサイクルはイベントのルートとされているコンポーネントとその子でのみ実行されます。詳細は、4.3項「最適化されたライフサイクルの使用」を参照してください。

PPRがトリガーされると、ターゲットとして構成されているコンポーネントが再レンダリングされます。コンポーネントは、partialTriggers属性をトリガー・コンポーネントの相対IDに設定することで、ターゲットとして構成します。相対IDの詳細は、3.5項「ページでのクライアント・コンポーネントの検索」を参照してください。

たとえば、inputTextコンポーネントに対する変更を受けてoutputTextを更新するには、partialTriggers属性をinputTextコンポーネントの相対IDに設定します。

注意:

コンポーネントのイベントにはデフォルトでPPRをトリガーするものがあり、たとえば、showDetailコンポーネントのdisclosureイベントや表のsortイベントがあります。つまり、partialTriggers属性をそのコンポーネントのIDに設定してターゲットとして構成されているコンポーネントは、この種のイベントが発生すると再レンダリングされます。

注意:

トリガー・コンポーネントがinputLovまたはinputComboBoxLovで、ターゲット・コンポーネントがrequiredに設定された入力コンポーネントの場合は、LOVポップアップが表示されると、検証エラーが入力コンポーネントでスローされます。これを回避するには、プログラムによる部分ページ・レンダリングを使用する必要があります。詳細は、7.3項「部分ページ・レンダリングのプログラムによる有効化」を参照してください。

7.2.1 部分ページ・レンダリングを有効にする方法

別のコンポーネントで発生したイベントに基づいてコンポーネントを再レンダリングするには、どのコンポーネントがトリガーかを宣言する必要があります。

コンポーネントで別のコンポーネントを再レンダリングする手順:

1. 構造ウィンドウで、トリガー・コンポーネント(そのアクションによってPPRが起こるコンポーネント)を選択します。

- プロパティ・インスペクタの「共通」セクションを開き、id属性を設定します(まだ設定されていない場合)。値はそのコンポーネントのネーミング・コンテナ内で一意である必要があります。コンポーネントがネーミング・コンテナ内に含まれていない場合、IDはページで一意である必要があります。ネーミング・コンテナの詳細は、3.5項「ページでのクライアント・コンポーネントの検索」を参照してください。

ヒント:

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コンポーネントを指すように設定する必要があります。

例7-1に、PPRを実行するよう構成されたcommandLinkコンポーネントを示します。

例7-1 部分送信を使用して部分ページ・レンダリングを有効にするコード

<af:commandLink id="deleteFromCart" partialSubmit="true"
actionListener="#{homeBean...}">

例7-2に、例7-1のIDがdeleteFromCartのコマンド・リンクがクリックされると再レンダリングされるoutputTextコンポーネントを示します。

例7-2 他のコンポーネントによってトリガーされる部分ページ・レンダリングのコード

<af:outputText id="estimatedTotalInPopup"
partialTriggers="deleteFromCart"
value="#{shoppingCartBean...}"/>

ヒント:

PPRを使用して、コンポーネントがページで検証されないようにできます。詳細は、4.3項「最適化されたライフサイクルの使用」を参照してください。

7.2.2 ブラウザの戻るボタンの使用について

ADF Facesアプリケーションでは、一部のコンポーネントで(暗黙的に、あるいは部分トリガーをリスニングするよう構成されていて)PPRが使用されるため、ユーザーがブラウザの戻るボタンをクリックしたときの動作は、単にJSFコンポーネントを使用するアプリケーションとは多少異なります。

単にJSFコンポーネントを使用するアプリケーションでは、ユーザーがブラウザの戻るボタンをクリックすると、最後にレンダリングされたときのDocument Object Model(DOM)の状態にページがブラウザによって戻されますが、JavaScriptの状態は、ユーザーが最初にページにアクセスしたときの状態です。

たとえば、ユーザーがPageAにアクセスしたとします。ページのコンポーネントとの対話後、JavaScriptを使用してPPRイベントが発生します。新たなバージョンのこのページをPageA1とします。次に、ユーザーがPageBに移動し、ブラウザの戻るボタンをクリックしてPageAに戻ります。ユーザーにPageA1のDOMが表示されますが、JavaScriptは実行されていないため、ページの一部はPageAのままです。つまり、ページに対する変更が失われています。ページをリフレッシュすると、JavaScriptが実行され、ユーザーはPageA1の状態に戻ります。ADF Facesを使用するアプリケーションでは、リフレッシュが不要になり、フレームワークでビルトイン・サポートが提供されるため、戻るボタンをクリックするとJavaScriptが実行されます。

7.2.3 PPRおよびスクリーン・リーダーについて

スクリーン・リーダーでは、部分ページ・リクエストで全ページの再読込みは実行されません。PPRによって、スクリーン・リーダーは部分ページ・リクエストを起動したコンポーネントから始まるページを読み込みます。ターゲット・コンポーネントは、部分リクエストをトリガーするコンポーネントの後に配置する必要があり、このようにしないと、更新したターゲット・コンポーネントがスクリーン・リーダーに読み込まれません。

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

多くのイベントが関連付けられているカレンダなどのコンポーネントでは、イベントがトリガーされるとPPRが発生し、そのたびにカレンダを部分トリガーとするコンポーネントが再レンダリングされます。ターゲットが特定のイベントでのみ再レンダリングされるようにする場合、またはターゲットが別のロジックに基づいて再レンダリングされるようにする場合、部分ページ・レンダリングをプログラムから有効にします。

たとえば、ADF Facesカレンダ・デモで、モデルにすでに存在しないアクティビティの期間をユーザーが変更しようとする場合は、カレンダをリフレッシュしてアクティビティなしに表示する必要があります(アクティビティの有効な期間が変更された場合は、カレンダが自動的にリフレッシュされます)。この例では、activityDurationChangeEventが起動されるびに、activityDurationChangeListenerメソッドによって、カレンダが部分ターゲットとして設定され、activityオブジェクトがNULLになります。

作業を始める前に、次のようにします。

リスナー・メソッドを含むマネージドBeanを作成します。詳細は、2.6項「マネージドBeanの作成と使用」を参照してください。

PPRをプログラムによって有効にする手順:

1. JSFページで、ターゲット・コンポーネントを選択します。プロパティ・インスペクタで、clientComponentをtrueに設定します。

注意:

clientComponent属性をtrueに設定して、クライアントIDが生成されるようにします。

2. binding属性を使用して、マネージドBeanがターゲット・コンポーネントのインスタンスで動作できるようにします。これは次のように行います。

1. プロパティ・インスペクタで、マネージドBeanでターゲット・コンポーネントに解決するEL式にBindingを設定します。
前述の例では、Bindingを次のように設定できます。

#{myBean.cal1}

cal1はターゲット・コンポーネントのIDになり、この場合は、calendarコンポーネントになります。

2. マネージドBeanで、ターゲット・コンポーネントにgetメソッドおよびsetメソッドを作成します。例7-3に、calendarコンポーネントでマネージドBeanのコードがどのようになるかを示します。

例7-3 UIコンポーネントのgetメソッドおよびsetメソッド

public class MyBean {
private RichCalendar cal1;

public MyBean() {
}

public void setCal1(RichCalendar cal1) {
this.cal1 = cal1;
}

public RichOutputText getCal1() {
return cal1;
}

3. マネージドBeanで、再レンダリングするターゲット・コンポーネントを使用する必要のあるトリガー・コンポーネントのイベントに、リスナー・メソッドを作成します。

addPartialTarget()メソッドを使用して、イベントがトリガーされると部分ターゲット・コンポーネントが再レンダリングされるよう、そのイベントの部分ターゲットとしてコンポーネントを追加します(そのIDを使用)。このメソッドを使用して、再レンダリングするコンポーネントと再レンダリングをトリガーするイベントを関連付けます。

例7-4に、カレンダをターゲットとして追加するActivityDurationChangeEventリスナーを作成する方法を示します。

例7-4 部分ターゲットを使用した再レンダリング

public void activityDurationChangeListener(CalendarActivityDurationChangeEvent ae)
{
CalendarActivity activity = ae.getCalendarActivity();

if (activity == null)
{
// no activity with that id is found in the model
System.out.println("No activity with event " + ae.toString());
setCurrActivity(null);

// Since the user has acted on an activity that couldn't be found,
// ppr the page so that they no longer see the activity
RequestContext adfContext = RequestContext.getCurrentInstance();
adfContext.addPartialTarget(getCal1());
return;
}

DemoCalendarActivity demoActivity = ((DemoCalendarActivity)activity);
TimeZone tz = getTimeZone();
demoActivity.setEndDate(ae.getNewEndDate(), tz);
setCurrActivity(new DemoCalendarActivityBean(demoActivity, tz));
}

4. トリガー・コンポーネントを選択し、プロパティ・インスペクタで、リフレッシュを実行するイベントのリスナーを検索し、手順3で作成したリスナー・メソッドにバインドします。

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

従来のページ全体の遷移のかわりに、部分ページ・レンダリング・リクエストを使用してナビゲーションがトリガーされるように、ADF Facesアプリケーションを構成できます。新しいページは、部分ページ・レンダリングを使用してクライアントに送信されます。部分ページ・ナビゲーションは、デフォルトでは無効になっています。

ブックマークやリフレッシュが行われたときなど、位置を把握しておくために、フレームワークでURLのハッシュ部分を使用します。URLのこの部分には、ブラウザに表示される実際のページが含まれます。

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

部分ページ・ナビゲーションは、web.xmlファイルのoracle.adf.view.rich.pprNavigation.OPTIONSコンテキスト・パラメータをonに設定することで有効にできます。

部分ページ・ナビゲーションを使用する手順:

1. web.xmlファイルをダブルクリックします。

2. ソース・エディタで、oracle.adf.view.rich.prNavigation.OPTIONSパラメータを次のいずれかに変更します。

- on: 部分ページ・ナビゲーションを有効にします。

注意:

パラメータをonにする場合、ナビゲーションに含まれるコマンド・コンポーネントのpartialSubmit属性をtrueに設定する必要があります。

- onWithForcePPR: 部分ページ・ナビゲーションを有効にし、すべてのアクション・イベント(ナビゲーションが行われないアクション・イベントも含む)でPPRチャネルを使用するためのフレームワークを通知します。部分ページ・ナビゲーションでは、PPRチャネルを介してアクション・イベントを送信する必要があるため、このオプションを使用して部分ページ・ナビゲーションを簡単に有効化できます。
部分ページ・ナビゲーションを使用している場合、通常はページのビジュアル・コンテンツのみ再レンダリングされます(ヘッダー・コンテンツはすべてのページで一定のままです)。ただし、ページのアクションがフル・ページ送信を使用するように定義されている場合、およびアクションでナビゲーションが行われない場合も、ドキュメント全体が再レンダリングされます。

7.4.2 PPRナビゲーションについて

PPRナビゲーションを使用する前に、次の点に注意します。

- PPRナビゲーションを使用する場合、このナビゲーションに関連するすべてのページで同じCSSスキンを使用する必要があります。

- PPRナビゲーションでURLのハッシュ部分が使用されるため、ナビゲーションでのページ内のアンカーにハッシュ部分を使用できません。

- 標準のページ・ナビゲーションとは異なり、部分ナビゲーションではJavaScriptグローバル(グローバル・スコープに定義されている変数および関数)はアンロードされません。これが発生するのは、ウィンドウ・オブジェクトが部分ページの遷移でも残るためです。ページ固有のグローバル変数および関数を使用するアプリケーションでは、AdfPage.getPageProperty()メソッドおよびAdfPage.setPageProperty()メソッドを使用して、それらのオブジェクトを格納する必要があります。

第III部

ADF Facesコンポーネントの使用

第III部には、次の章が含まれています。

- 第8章「Webページ上のコンテンツの編成」

- 第9章「入力コンポーネントの使用およびフォームの定義」

- 第10章「表およびツリーの使用」

- 第11章「LOVコンポーネントの使用方法」

- 第12章「問合せコンポーネントの使用方法」

- 第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」

- 第14章「メニュー、ツールバーおよびツールボックスの使用方法」

- 第15章「Calendarアプリケーションの作成」

- 第16章「出力コンポーネントの使用」

- 第17章「ヒント、メッセージおよびヘルプの表示」

- 第18章「ナビゲーション・コンポーネントの使用」

- 第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」

- 第20章「スタイルおよびスキンを使用した外観のカスタマイズ」

- 第21章「ページの国際化およびローカライズ」

- 第22章「アクセス可能なADF Facesページの開発」

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

この章では、ADF Facesのいくつかのレイアウト・コンポーネントを使用して、Webページ上のコンテンツを編成する方法を説明します。

この章では、次の項目について説明します。

- 8.1項「Webページ上のコンテンツの編成の概要」

- 8.2項「ページ・レイアウトの開始」

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

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

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

- 8.6項「フォームでのコンテンツの配置」

- 8.7項「ダッシュボードでのコンテンツの配置」

- 8.8項「コンテンツの動的な表示および非表示」

- 8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」

- 8.10項「静的ボックスの項目の表示」

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

- 8.12項「関連する項目のグループ化」

- 8.13項「空白または線を使用したコンテンツの分割」

8.1 Webページ上のコンテンツの編成の概要

ADF Facesには、その他のコンポーネントをページに配置する際に使用可能なレイアウト・コンポーネントが多数用意されています。通常、これらのコンポーネントを使用してページの作成を開始します。その後、その他の機能(データやボタンのレンダリングなど)を提供するコンポーネントを、ファセット内またはレイアウト・コンポーネントの子コンポーネントとして追加します。

ヒント:

アプリケーション内のページのレイアウトを設計できるページ・テンプレートを作成できます。テンプレートは、アプリケーション内のすべてのページで使用できます。詳細は、第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」を参照してください。

コンテナとして機能するレイアウト・コンポーネントに加え、ADF Facesには、コンテンツの表示や非表示、またはセクション、リスト、空白の表示が可能な対話型のレイアウト・コンポーネントもあります。一部のレイアウト・コンポーネントには、ウィンドウのサイズが変更された場合にブラウザ・ウィンドウに合せてコンテンツが拡大する機能や、拡大するコンポーネント内に配置された場合には拡大する機能などのジオメトリ管理機能もあります。レイアウト・コンポーネントの拡大およびジオメトリ管理機能の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

表8-1では、ADF Facesの各レイアウト・コンポーネントを簡単に説明しています。

表8-1ADF Facesのレイアウト・コンポーネント

コンポーネント

説明

子の拡大

拡大

ページ管理コンポーネント

document

HTMLページの標準の各ルート要素(<html>、<body>および<head>)を作成します。すべてのページにこのコンポーネントを使用する必要があります。詳細は、8.2項「ページ・レイアウトの開始」を参照してください。

X

form

HTMLの<form>要素を作成します。詳細は、8.2項「ページ・レイアウトの開始」を参照してください。

ページ・レイアウト・コンテナ

panelStretchLayout

top、bottom、start、centerおよびendファセットが含まれ、その他のコンポーネントを配置できます。詳細は、8.3項「コンテンツをページ全体に拡大するための設定」を参照してください。

X

X(dimensionsFrom属性がparentに設定されている場合)

panelSplitter

再配置可能な仕切線を使用してリージョンを2つの部分(firstファセットおよびsecondファセット)に分割します。このファセットには別のコンポーネントを配置できます。詳細は、8.4項「スプリッタを使用したサイズ変更可能なペインの作成」を参照してください。

X

X(dimensionsFrom属性がparentに設定されている場合)

panelDashboard

子コンポーネント(通常はpanelBoxコンポーネント)の縦表示を提供します。詳細は、8.7項「ダッシュボードでのコンテンツの配置」を参照してください。

X

X(dimensionsFrom属性がparentに設定されている場合)

panelBorderLayout

子コンポーネントを含めることが可能で、その中央に配置され、枠に沿って12個のファセットも含まれます(追加のコンポーネントを配置可能)。これらは中央部分を囲みます。詳細は、8.5項「事前定義済固定領域へのページ・コンテンツの配置」を参照してください。

panelFormLayout

ラベルやフィールドが縦に並ぶように、inputTextコンポーネントなどの入力フォーム・コントロールを配置します。複数の列をサポートしており、footerファセットが含まれます。詳細は、8.6項「フォームでのコンテンツの配置」を参照してください。

表示/非表示機能のあるコンポーネント

showDetailHeader

ヘッダーの下のコンテンツを表示または非表示にできます。通常、panelHeaderコンポーネントの子として使用されます。詳細は、8.8項「コンテンツの動的な表示および非表示」を参照してください。

X(type属性がstretchに設定されている場合)

X(type属性がstretchに設定されている場合)

showDetailItem

panelAccordionの各ペイン、またはpanelTabbedコンポーネントの各タブのコンテンツを保持するために使用されます。詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。

X(含まれる子コンポーネントが1つのみの場合)

panelBox

子コンポーネントを含めることができるタイトル付きのボックス。toolbarファセットがあります。詳細は、8.8項「コンテンツの動的な表示および非表示」を参照してください。

X

panelAccordion

showDetailItemコンポーネントとともに使用され、開閉が可能なパネルとして表示されます。詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。

X(dimensionsFrom属性がparentに設定されている場合)

panelTabbed

showDetailItemコンポーネントとともに使用され、タブ付きの一連のパネルとして表示されます。詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。

タブとナビゲーション階層を組み合せて使用する場合、たとえば、各タブが他のナビゲーション・アイテムのセットを含む別ページまたはリージョンである場合、かわりにナビゲーション・メニューのnavigationPaneコンポーネントを使用できます。詳細は、18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

X(dimensionsFrom属性がparentに設定されている場合)

showDetail

トグル・アイコンを介してコンテンツを表示または非表示にします。詳細は、8.8項「コンテンツの動的な表示および非表示」を参照してください。

その他のコンテナ

panelHeader

子コンポーネントが含まれ、メッセージ、ツールバーおよびヘルプ・トピックを含むヘッダーを表示します。詳細は、8.10項「静的ボックスの項目の表示」を参照してください。

X(type属性がstretchに設定されている場合)

X(type属性がstretchに設定されている場合)

panelCollection

table、treeおよびtreeTableなどの収集コンポーネントとともに使用され、これらのコンポーネントのメニュー、ツールバーおよびステータス・バーを表示します。詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

X(表、ツリーまたはツリー表が1つのみの場合)

X

decorativeBox

コンテナ・コンポーネントを作成します(このコンポーネントのファセットは、スタイル・テーマを使用して、その子に枠の外観を適用します)。通常、このコンポーネントは、ページの領域間のルック・アンド・フィールの遷移として機能します。たとえば背景色が暗いテンプレートを持つページは、decorativeBoxを使用して、メイン領域の背景色を白にできます。詳細は、8.10項「静的ボックスの項目の表示」を参照してください。

X(中央ファセット内)

X(dimensionsFrom属性がparentに設定されている場合)

inlineFrame

インラインiframeタグを作成します。

X

navigationPane

ナビゲーション階層の1レベルを表す一連のナビゲーション・アイテムを作成します。詳細は、18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

X(タブを表示するように構成されている場合)

panelList

各子コンポーネントをリスト項目として出力し、隣に黒丸をレンダリングします。ネストさせて階層リストを作成できます。詳細は、8.11項「1つ以上の列における箇条書きリストの表示」を参照してください。

panelWindow

ポップアップ・ウィンドウ内に子コンポーネントを表示します。詳細は、13.2項「ポップアップ要素の宣言的作成」を参照してください。

toolbox

子のtoolbarおよびmenuコンポーネントを一緒に表示します。詳細は、14.3項「ツールバーの使用方法」を参照してください。

グループ化コンテナ

panelGroupLayout

子コンポーネントを縦または横にグループ化します。複数のコンポーネントがファセットに含まれる場合にファセットで使用されます。詳細は、8.12項「関連する項目のグループ化」を参照してください。

X(レイアウトがscrollまたはverticalに設定されている場合のみ)

group

グループの親コンポーネントに管理されている場合を除き、レイアウトに関係なく子コンポーネントをグループ化します。複数のコンポーネントがファセットに含まれる場合にファセットで使用されます。詳細は、8.12項「関連する項目のグループ化」を参照してください。

間隔調整コンポーネント

separator

項目間に水平線を作成します。詳細は、8.13項「空白または線を使用したコンテンツの分割」を参照してください。

spacer

空白の領域を作成します。詳細は、8.13項「空白または線を使用したコンテンツの分割」を参照してください。

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

ADF Facesコンポーネントを使用するすべてのJSFページには、viewタグで囲んだdocumentタグが必要です。ページを構成するその他すべてのコンポーネントが、<af:document>および</af:document>の間に入ります。documentタグは、ページ内のその他のコンポーネントを表示できる非表示のページ・インフラストラクチャや、ブラウザのタイトル・テキストをレンダリングします。たとえば、実行時に、documentタグによりクライアント・ページのルート要素が作成されます。HTML出力では、<html>、<head>および<body>などのHTMLページの標準のルート要素が生成されます。

デフォルトでは、documentタグは、使用可能なブラウザの領域を埋めるために拡大可能なコンポーネントを拡大できるように構成されます。また、ページのレンダリング時に特定のコンポーネントにフォーカスする、あるいは失敗した接続のメッセージまたはデータが送信される前のナビゲートに関する警告を表示できるようにタグを構成できます。詳細は、8.2.5項「documentタグの構成方法」を参照してください。

通常、次に使用されるコンポーネントは、ADF Faces formコンポーネントです。このコンポーネントは、ユーザーによるページ・データの操作を可能にするコントロールを含むことができるHTMLのform要素を作成します。

注意:

ページに複数のHTMLフォームを含めることができる場合でも、1ページ当たりのADF Faces formタグは1つのみにしてください。詳細は、8.6項「フォームでのコンテンツの配置」を参照してください。

例8-1に示すように、JDeveloperでは、view、documentおよびformタグを自動的に挿入します。詳細は、2.4項「ビュー・ページの作成」を参照してください。

例8-1 JDeveloperのウィザードで作成された最初のJSFページ

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
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">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document>
<af:form/>
</af:document>
</f:view>
</jsp:root>

これらのタグがページに配置されたら、レイアウト・コンポーネントを使用して、ページ上のその他のコンポーネントをレンダリングする方法と場所を制御できます。その他すべてのコンポーネントを保持するコンポーネントは、ルート・コンポーネントとみなされます。ルート・コンポーネントとして使用するコンポーネントの選択は、含まれているコンポーネントのコンテンツをブラウザ・ウィンドウに合せて拡大されるように表示するか、ウィンドウに収まらないコンテンツにアクセスするためにスクロールバーを使用してコンテンツを移動できるようにするかによって異なります。拡大および配置の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

ヒント:

レイアウトを自分で作成するかわりに、JDeveloperのクイック・レイアウト・テンプレート(正確に構成されたコンポーネントが用意されており、好みのレイアウトでページを表示できます)を使用できます。詳細は、8.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

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

ジオメトリ管理は、ユーザー、親コンポーネントおよび子コンポーネントが、アプリケーション内のコンポーネントの実際のサイズと場所を調整するプロセスです。RCFのジオメトリ管理ソリューションの中核は、サイズ変更通知メカニズムで、ジオメトリ管理に対応しているコンポーネントにブラウザのサイズ変更アクティビティを通知できます。次のシナリオで通知が起動されます。

- ロード: ページ・コンテンツが初めてロードされる場合。最初のサイズ設定が行われます。

- ブラウザのサイズ変更: ブラウザ・ウィンドウのサイズが変更された場合。

- 部分的な置換え: 部分的なページのレンダリングでページの一部が更新された場合。新しく挿入されたすべてのコンポーネントが通知され、必要なジオメトリ管理が実行されます。

- 可視性の変更: 最初は非表示に構成されていたコンポーネントが表示されるようになった場合(最初は非表示であったコンポーネントには通知は送信されません)。

- 明示的なサイズ変更: サイズ変更可能なコンポーネント(panelSplitterなど)がユーザーによってサイズ変更された場合。

コンポーネントがジオメトリ管理に対応しており、子コンポーネントを拡大できる場合には、ルート・コンポーネントはデフォルトで自動的にブラウザの表示可能領域全体に拡大されます。ジオメトリ管理コンポーネントは、panelStretchLayoutおよびpanelSplitterなどです。

注意:

フレームワークでは、ポップアップ・ダイアログ、ポップアップ・ウィンドウまたはインラインではないメッセージは、ルート・コンポーネントとみなされません。formコンポーネントがdocumentコンポーネントの直接の子コンポーネントである場合には、フレームワークにより、formタグ内のビジュアル・ルートの有無が確認されます。ポップアップのサイズ設定の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

ユーザーによりブラウザ・ウィンドウのサイズが変更され、documentコンポーネント内でmaximizedに設定されているルート・ビジュアル・コンポーネントが1つの場合、そのビジュアル・ルート・コンポーネントもブラウザ・ウィンドウに合せてサイズ変更されます。ルート・コンポーネントで子コンポーネントの拡大がサポートされている場合(および、子コンポーネントでも拡大がサポートされている場合)、配置レイアウト領域(子コンポーネントの拡大がサポートされていない領域)に達するまで、コンポーネント階層を下がって子コンポーネントのサイズが再計算されます。拡大を有効化するためにコードを記述する必要はありません。

表8-1に示されているように、それ自体とその子コンポーネントも拡大できるコンポーネントはpanelStretchLayout、panelSplitterおよびpanelDashboardコンポーネントです。また、panelAccordionまたはpanelTabbedコンポーネントの直接の子としてshowDetailItemコンポーネントが使用されている場合は、showDetailItemコンポーネントのコンテンツを拡大できます。そのため、ページのコンテンツをブラウザ・ウィンドウに合せる必要がある場合には、showDetailItemコンポーネントを含むpanelStretchLayout、panelSplitter、panelDashboard、panelAccordionコンポーネント、およびshowDetailItemコンポーネントを含むpanelTabbedコンポーネントをルート・コンポーネントとして使用する必要があります。

たとえば、図8-1に、panelStretchLayoutコンポーネントのcenterファセットに配置された表を示します。表はブラウザ領域に収まるように拡大されています。表全体がブラウザ・ウィンドウに収まらない場合は、表のデータ本体部分にスクロールバーが追加されます。

図8-1 子コンポーネントが拡大されるコンポーネント内の表

図8-2に、子コンポーネントを拡大できないpanelGroupLayoutコンポーネント内にネストしている同じ表を示します(明確にするために、赤の点線の輪郭をpanelGroupLayoutコンポーネントの周囲に配置しています)。表コンポーネントでは、表のプロパティで設定されている一部の列および行のみが表示されています。

図8-2 子コンポーネントが拡大されないコンポーネント内の表

パフォーマンスのヒント:

ジオメトリ管理のコストは、子コンポーネントの複雑さに直接関係しています。そのため、ジオメトリ管理される親コンポーネントに属する子コンポーネントの数はできるだけ少なくなるようにしてください。

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

子コンポーネントを拡大できるコンポーネントを選択しても、実際に拡大されるのは次のコンポーネントのみです。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout(layout属性がscrollまたはverticalに設定されている場合)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

次のレイアウト・コンポーネントは、子コンポーネントを拡大するコンポーネントのファセット内に配置しても拡大できません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout(layout属性がdefaultまたはhorizontalに設定されている場合)

- panelHeader

- panelLabelAndMessage

- panelList

- showDetail

- showDetailHeader

- tableLayout(MyFaces Trinidadコンポーネント)

これらのコンポーネントは拡大されないため、子コンポーネントを拡大するコンポーネントのファセットには配置できません。そのため、子コンポーネントを拡大するコンポーネントのファセット内でこれらのコンポーネントのいずれかを使用する場合は、拡大可能で、子コンポーネントを拡大しないコンポーネントでラップする必要があります。ラップしないと、コンポーネントのレンダリング時に予期しない結果になる場合があります。

たとえば、ページの最初のコンポーネントとしてpanelStretchLayoutがあるとします。次に、拡大するように構成されているpanelSplitterコンポーネントを追加します。さらに、panelSplitterコンポーネントの最初のファセットに、layout属性がscroll(拡大可能)に設定されているpanelGroupLayoutコンポーネントを追加し、その中にpanelCollectionコンポーネント、最後にtableコンポーネントを追加するとします。

panelSplitterの2番目のファセットには、図8-3に示すように、panelCollectionおよびtableコンポーネントのみを追加するとします。子を拡大できるコンポーネントは緑で、拡大できるコンポーネント(子は拡大できない)は青です。

図8-3 ジオメトリ管理コンポーネントを使用したレイアウト

図8-4に示すように、ページが実行されると、panelSplitterコンポーネントに直接配置されているコンポーネントは拡大されているのに対して、panelGroupLayout内のpanelCollectionおよびtableコンポーネントは拡大されません。

図8-4 ページのレイアウトに影響するジオメトリ管理コンポーネント

panelStretchLayoutコンポーネントは子コンポーネントを拡大可能で、panelSplitterコンポーネントも拡大できるように構成されているため、両方が使用可能なブラウザの領域全体に拡大されます。panelSplitterコンポーネントは子コンポーネントを拡大でき、layout属性がscrollに設定された左側のpanelGroupLayoutコンポーネントも、右側のpanelCollectionコンポーネントも拡大可能であるため、両方が使用可能なブラウザの領域全体に拡大されます。ただし、panelCollectionコンポーネントは単一の表を拡大できるのに対し、panelGroupLayoutコンポーネントは子コンポーネントを拡大できません。そのため、親は拡大されていても、左側のpanelCollectionコンポーネントは拡大されません。

ヒント:

拡大できないコンポーネントのリストにあるコンポーネントを、幅を100%に設定して拡大しないでください。予期しない結果になる場合があります。かわりに、拡大するコンポーネントを拡大可能なコンポーネントで囲みます。拡大可能なコンポーネントは、表8-1を参照してください。

左側にtableコンポーネントではなく、panelListコンポーネントを追加するとします。panelCollectionコンポーネント(表のみに使用)は不要なため、panelListコンポーネントを別のコンポーネントでグループ化する場合に、panelGroupLayoutコンポーネントを使用する必要はないとも考えられます。ただし、panelListコンポーネントはpanelSplitterコンポーネントの直接の子になり、また、panelSplitterコンポーネントは子コンポーネントを拡大し、panelListコンポーネントは拡大できないため、(scrollに設定されている)panelGroupLayoutはそのままにして、panelListコンポーネントをpanelGroupLayoutコンポーネントの子として配置する必要があります。

このようにすると、panelSplitterコンポーネント内のpanelGroupLayoutコンポーネントは拡大されますが、panelGroupLayoutコンポーネントはpanelListコンポーネントの拡大を試行しません。panelGroupLayoutコンポーネントは拡大できますが、子コンポーネントを拡大しないため、拡大を行うレイアウトと配置を行うレイアウトとの移行が可能です。

拡大可能だが、子を拡大しないコンポーネントは、遷移コンポーネントとみなされます。遷移コンポーネントは、子を拡大するコンポーネントと拡大しないコンポーネントの間で常に使用する必要があります。

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

新規ギャラリ・ウィザードを使用してJSF JSPページ(またはページ・フラグメント)を作成する場合、様々な事前定義済のクイック・スタート・レイアウトから選択できます。それらのレイアウトの1つを選択すると、JDeveloperによって必要なコンポーネントが追加され、ユーザーが希望する外観と動作が得られるようにそれらのコンポーネントの属性が設定されます。1列、2列および3列の形式から選択できます。それらの形式では、各列に表示する独立したペインの数、およびそれらのペインを拡大可能にするか固定サイズのままにするかを選択できます。図8-5に、2列形式で使用可能な様々なレイアウトを示します。

図8-5 クイック・レイアウト

レイアウト・コンポーネントの追加に加えて、テーマを適用してクイック・レイアウトを選択することもできます。これらのテーマにより、クイック・スタート・レイアウトで使用するコンポーネントの一部に色のスタイルが追加されます。色および色の追加場所を確認するには、付録E「クイック・スタート・レイアウト・テーマ」を参照してください。テーマの詳細は、20.3.4項「コンポーネントへのテーマの適用方法」を参照してください。

クイック・レイアウトを使用すると、時間を節約できるのに加え、レイアウト・コンポーネントが正しく連携して使用されるので希望どおりの結果を得ることができます。クイック・レイアウトを使用したページの作成の詳細は、2.4項「ビュー・ページの作成」を参照してください。

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

ページがすべてのブラウザで予想どおりに表示されるようにするには、ページの作成時にJDeveloperに用意されているクイック・レイアウトの1つを使用します。クイック・レイアウトを使用すると、正しいコンポーネントが使用されて正確に構成されます。詳細は、8.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

ベスト・プラクティス:

レイアウト表示の問題を回避するには、クイック・スタート・レイアウトを使用します。

ただし、自分でレイアウトを作成する場合は、拡大されるコンポーネントと配置されるコンポーネントの両方を含むレイアウトを作成するための次のヒントに従います。

- ジオメトリ管理機能のあるルート・コンポーネント内(showDetailItemを含むpanelStretchLayout、panelSplitter、panelAccordion、またはshowDetailItemを含むpanelTabbed)にページ・コンテンツを配置します。

- パーセント単位で高さの値を指定しないでください。かわりに、拡大がサポートされているコンポーネントや、子コンポーネントを拡大するコンポーネントの外にコンポーネント構造を作成します。

- layout属性がscrollに設定されているpanelGroupLayoutコンポーネントなどの遷移コンポーネントを使用して、拡大可能な構造内に、拡大できないコンポーネントまたは配置が行われるコンポーネントのグループを作成します。このコンポーネントでは拡大がサポートされていますが、子コンポーネントは拡大されないため、拡大されるコンポーネントと配置が行われるコンポーネントの移行が可能です。

- どのWebブラウザでも一貫して機能するわけではないため、拡大できないコンテナまたは配置が行われるコンテナ内で、縦方向の拡大を試行しないでください。

- 親の配置コンポーネントに含まれるコンポーネント(子を拡大しないコンポーネント)の場合は、95%を超える幅を設定しないでください。このようにすると、予期しない結果になることがあります。

- 親コンポーネントが768ピクセル以上の場合は、コンポーネントのstyleClass属性がAFStretchWidthに拡大されるように設定します。このスタイルにより、異なるブラウザおよび親のパディングまたは枠線を考慮して、コンポーネントが親コンテナのほぼ100%まで拡大されます。

- 親コンポーネントが768ピクセル以下の場合は、コンポーネントのstyleClass属性がAFAuxiliaryStretchWidthに拡大されるように設定します。このスタイルにより、異なるブラウザおよび親のパディングまたは枠線を考慮して、コンポーネントが親コンテナのほぼ100%まで拡大されます。

注意:

これら2つの異なるスタイルは、Microsoft Internet Explorer 7によるスクロール・コンテナ内の幅の計算で必要になります(Internet Explorer 8では解決済です)。アプリケーションのアクセスに使用するブラウザのバージョンを管理できない場合は、これらのスタイルを前述ように使用する必要があります。

- positionスタイルは使用しないでください。

- documentタグのmaximized属性がtrueに設定されていることを確認します(これはデフォルトです)。属性の設定の詳細は、8.2.5項「documentタグの構成方法」を参照してください。

この章の残りの部分では、ADF Facesのレイアウト・コンポーネント、およびそれらを使用してページを設計する方法を説明しています。各コンポーネントで拡大が処理される方法の詳細は、それぞれの「ジオメトリ管理について」の項に記載されています。

8.2.5 documentタグの構成方法

documentタグには、ページの動作を制御するために構成できる多数の属性が含まれています。たとえば、ページを初めてレンダリングするときに1つのコンポーネントにフォーカスするようにタグを構成できます。また、ユーザーがページから移動しようとしたときにデータがまだ送信されていない場合に、警告メッセージを表示するようにタグを構成することもできます。アプリケーションの他の部分とは異なる状態保存方式をdocumentで使用するように設定することもできます。

documentタグを構成する手順:

1. 構造ウィンドウで、af:documentノードを選択します。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。

- initialFocusId: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、ページを初めてレンダリングするときにフォーカスするコンポーネントを選択します。
このフォーカスはクライアントで行われるため、選択するコンポーネントには対応するクライアント・コンポーネントが必要です。詳細は、3.4項「クライアント側コンポーネントのインスタンス化」を参照してください。

- maximized: ルート・コンポーネントを拡張して使用可能なすべてのブラウザ領域に合せる場合はtrueに設定します。documentタグのmaximized属性がtrueに設定されていると、フレームワークにより単一のビジュアル・ルート・コンポーネントが検索され、そのコンポーネントが拡大可能な場合は、ブラウザの表示可能領域全体にコンポーネントが拡大されます。これに対応しているコンポーネントは、panelStretchLayoutおよびpanelSplitterです。documentタグのmaximized属性は、デフォルトでtrueに設定されています。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- title: ブラウザのタイトル・バーに表示するテキストを入力します。

3. 「外観」セクションを開き、failedConnectionText属性に、サーバーに接続できない場合に表示するテキストを入力します。

4. 「その他」セクションを開き、次の設定を行います。

- uncommitedDataWarning: データがコミットされていないことがアプリケーションによって検出されたときに、ユーザーに警告メッセージを表示する場合は、onに設定します。警告メッセージは、ユーザーがデータをコミットせずにページを終了しようとする場合、またはサーバーにコミットされていないデータがある場合に表示されます。デフォルトでは、offに設定されています。

- stateSaving: ページに使用する状態保存のタイプに設定します。
ADF Facesアプリケーションの場合は、トークン付きのクライアント状態保存をアプリケーションで使用することをお薦めします(ページ状態がセッションに保存され、トークンがクライアントで永続します)。この設定はアプリケーションにグローバルに反映し、すべてのページで状態がセッションに保存され、状態に関する情報でトークンが永続化されます。

ただし、ページの状態を別の方法で保存したい場合もあります。たとえば、一定時間を超過した後にユーザーがログイン・ページにポストバックしたときに、セッション・タイムアウト・エラーを表示させたくない場合です。ページのstateSaving属性をclientに変更することで、ユーザーがログイン・ページにポストバックする場合に、タイムアウト・エラーは表示されなくなります。

web.xmlのグローバル設定をページの次のいずれかにオーバーライドできます。

- client: トークンを使用せずに、状態がクライアントに完全に保存されます。この設定により、セッションの期限切れのメッセージは表示されなくなります。

- default: ページの状態はweb.xmlの設定に基づきます。

- server: ページの状態はサーバーに保存されます。

状態保存の詳細は、付録A「web.xmlでの構成」を参照してください。

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

コンテンツをページの定義済領域に配置し、ブラウザがサイズ変更されたらコンテンツが拡大されるようにする必要がある場合には、panelStretchLayoutコンポーネントを使用します。panelStretchLayoutコンポーネントは、ファセット内に配置されたコンポーネントが拡大されるコンポーネントの1つです。図8-6に、コンポーネントのファセットを示します。

図8-6 panelStretchLayoutコンポーネントのファセット

注意:

図8-6は、アプリケーションにおける言語の読み方向が左から右に構成されている場合のファセットを示しています。言語の方向が右から左の場合は、startおよびendファセットが入れ替ります。

topおよびbottomファセットの高さを設定すると、含まれるコンポーネントはその高さに合うように拡大されます。同様に、startおよびendファセットの幅を設定すると、それらのファセットに含まれるコンポーネントはその幅まで拡大されます。それらのファセットに配置されているコンポーネントがない場合、ファセットはレンダリングされません。つまり、ファセットは領域を占有しません。設定した領域をファセットで占有し、空白のままにする場合は、spacerコンポーネントを挿入します。8.13項「空白または線を使用したコンテンツの分割」を参照してください。centerファセットの子コンポーネントは、残りの領域に合うよう拡大されます。コンポーネント拡大の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

Topまたはbottomのファセットの高さ、あるいはstartまたはendファセットの幅を設定するかわりに、高さまたは幅をautoに設定できます。これにより、ファセットの子コンポーネントに必要な正確な領域を使用するように、ファセット自体がサイズを設定できます。領域は、Webブラウザがファセットのコンテンツの表示に必要だと判断する領域の量に基づいて割り当てられます。

パフォーマンスのヒント:

値にautoを使用すると、ページのパフォーマンスが低下します。最初に高さまたは幅を設定し、auto属性については慎重に使用してください。

File Explorerアプリケーションでは、テンプレートのルート・コンポーネントとしてpanelStretchLayoutコンポーネントが使用されています。子コンポーネントは、centerおよびbottomファセットにのみ配置されています。そのため、centerファセット内のすべてのコンポーネントは、ウィンドウの幅全体、およびウィンドウの上部から、高さがbottomHeight属性で指定されているbottomファセットの上部までの大きさに合うように拡大されます。例8-2に、fileExplorerTemplateファイルの省略形のコードを示します。

例8-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ピクセルの場所から開始されます。

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

panelStretchLayoutコンポーネントには、直接の子コンポーネントを配置できません。かわりに、ファセット内にコンポーネントを配置します。panelStretchLayoutは、ブラウザに合せて、ファセット内の任意のコンポーネントを拡大するように構成可能なコンポーネントの1つです。panelStretchLayoutコンポーネントはネスト可能です。詳細は、8.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

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を次のいずれかに設定します。

- children: 拡大するかわりに、panelStretchLayoutコンポーネントが子からディメンションを取得します。

注意:

この設定を使用する場合は、topおよびbottomファセットの高さの設定にパーセントを使用することはできません。そうすると、これらのファセットはpanelStretchLayoutコンポーネントのサイズからディメンションを取得しようと試みますが、panelStretchLayoutコンポーネントは高さをコンテンツから取得することになるため、取得できず、循環依存性が発生します。いずれかのファセットにパーセントが使用されている場合は無視され、かわりにデフォルトの50pxが使用されます。

また、この設定を使用している場合は、(たとえば、inlineStyleまたはstyleClass属性から)panelStretchLayoutコンポーネントの高さを設定することはできません。そうすると、panelStretchLayoutの高さと子コンポーネントの高さの間で競合が発生します。

- parent: panelStretchLayoutコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます(panelStretchLayoutコンポーネントが拡大されます)。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: panelStretchLayoutコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてpanelStretchLayoutコンポーネントが拡大されます。親が子を拡大しない場合、panelStretchLayoutコンポーネントのサイズは子コンポーネントのサイズに基づきます。

4. コンポーネントにコンテンツを配置するには、必要なコンポーネントを任意のファセットにドラッグ・アンド・ドロップします。子コンポーネントを拡大する場合には、拡大がサポートされているコンポーネントである必要があります。詳細は、8.3.2項「ジオメトリ管理およびpanelStretchLayoutコンポーネントについて」を参照してください。
ファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、コンテナ・コンポーネント(panelGroupLayoutコンポーネントなど)で子コンポーネントをラップする必要があります。含まれているすべてのコンポーネントを拡大するには、そのコンポーネントも拡大できる必要があります。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelStretchLayoutコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ストレッチ・レイアウト」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

8.3.2 ジオメトリ管理およびpanelStretchLayoutコンポーネントについて

panelStretchLayoutコンポーネントは子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次に、panelStretchLayoutコンポーネントのファセット内で拡大できるコンポーネントを示します。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout(layout属性がscrollまたはverticalに設定されている場合のみ)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

panelStretchLayoutコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout(layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelLabelAndMessage

- panelList

- showDetail

- showDetailHeader

- tableLayout(MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、panelStretchLayoutコンポーネントのファセットに拡大できないコンポーネントに配置する必要がある場合は、拡大できる遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelStretchLayoutコンポーネントのファセット内のpanelBoxコンポーネント(拡大しない)にコンテンツを配置する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをpanelStretchLayoutコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、8.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

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

ユーザーに表示する一意のコンテンツのグループがある場合は、調整可能なスプリッタで区切られた複数のペインを提供できるようにpanelSplitterコンポーネントの使用を検討します。図8-7に示されているように、File ExplorerではpanelSplitterを使用して、ナビゲーション・ツリーとフォルダ・コンテンツを分割しています。ユーザーは、スプリッタをドラッグしてペインのサイズを変更したり、ディレクトリを表示するパネルを閉じることや、元のサイズに戻すこともできます。パネルが閉じている場合は、パネルのコンテンツは表示されず、パネルを元に戻すと、コンテンツが表示されます。

図8-7 panelSplitterを使用してコンテンツを分割しているFile Explorer

panelSplitterコンポーネントを使用すると、調整可能なスプリッタで分割された2つのペインにコンテンツを編成できます。ペインは、(図8-7に示されているスプリッタのように)横に並べることも、縦に並べることもできます。File Explorerアプリケーションでは、別のpanelSplitterコンポーネントを使用して、ページ本体からアプリケーションのヘッダー・コンテンツが分割されます。図8-8に、ヘッダー・コンテンツを表示するために開かれたpanelSplitterコンポーネントを示します(OracleのロゴとFile Explorerの名前が含まれます)。

図8-8 縦に分割されて開かれたpanelSplitter

スプリッタの矢印ボタンをクリックすると、ヘッダー・コンテンツが表示されているパネルが閉じられ、図8-9に示すように、ロゴと名前が表示されなくなります。

図8-9 縦に分割されるpanelSplitterを使用しているFile Explorer

panelSplitterコンポーネントのファセットにコンポーネントを配置します。panelSplitterコンポーネントではジオメトリ管理を使用して、実行時に子コンポーネントを拡大します。つまり、ユーザーがパネルを1つ閉じると、使用可能な領域に合うように別のパネルのコンテンツが明示的にサイズ変更されます。

注意:

ユーザーは、ペインのサイズを変更したり閉じたりして、splitterPositionおよびcollapsed属性の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。変更の永続性の有効化および使用方法の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

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

panelSplitterコンポーネントを使用すると、スプリッタで分割された2つのペインを作成できます。それぞれのスプリッタ・コンポーネントには、firstおよびsecondという2つのファセットがあり、それぞれ第1パネルと第2パネルに対応します。子コンポーネントが存在できるのはファセット内のみです。3つ以上のペインを作成するには、panelSplitterコンポーネントをネストします。

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(すべてデフォルト値)に設定されている場合、図8-10に示されているように、ADF Facesによりスプリッタはstartパネルから200ピクセルの位置に配置されます。

図8-10 startパネルから計測されたスプリッタの位置

positionedFromEnd属性がtrueに設定されている場合、ADF Facesではスプリッタの初期位置はend(またはorientationの値に応じてbottomパネル)から計測されます。図8-11に、endパネルから200ピクセル計測したスプリッタの位置を示します。

図8-11 endパネルから計測されたスプリッタの位置

5. collapsedを設定して、スプリッタを閉じた状態(非表示)にするかどうかを決定します。デフォルトではcollapsed属性はfalseで、どちらのペインも表示されます。ユーザーがスプリッタの矢印ボタンをクリックすると、collapsed属性がtrueに設定され、いずれかのペインが非表示になります。
ADF Facesでは、ユーザーがスプリッタの矢印ボタンをクリックした場合にどちらのパネル(第1パネルまたは第2パネル)を非表示(閉じた状態)にするかを、collapsedおよびpositionedFromEnd属性を使用して決定します。collapsed属性がtrueでpositionedFromEnd属性がfalse,に設定されている場合は、第1パネルが非表示になり、第2パネルが使用可能な領域に合せて拡大されます。collapsed属性がtrueでpositionedFromEnd属性がtrueの場合は、かわりに第2パネルが非表示になります。視覚的には、ボタンの矢印の方向を確認することで、ユーザーはどちらのパネルが閉じるかを判断できます(ユーザーがスプリッタの矢印ボタンをクリックすると、矢印の方向にパネルが閉じます)。

6. デフォルトでは、panelSplitterコンポーネントは、使用可能なブラウザの領域を埋めるために拡大されます。子を拡大しないコンポーネントにpanelSplitterコンポーネントを配置する場合は、panelSplitterコンポーネントの拡大の処理方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントを拡大するかどうかを構成します。これを行うには、「その他」セクションを開き、dimensionsFromを次のいずれかに設定します。

- children: 拡大するかわりに、panelSplitterコンポーネントが子からディメンションを取得します。

注意:

この設定を使用し、orientation属性をverticalに設定すると、collapsibleパネルのコンテンツは子コンポーネントによって決定されず、かわりにsplitterPosition属性の値によって決定されます。他のパネルのサイズは、その子コンポーネントによって決定されます。

また、この設定を使用している場合は、(たとえば、inlineStyleまたはstyleClass属性から)panelSplitterコンポーネントの高さを設定することはできません。そうすると、panelSplitterの高さと子コンポーネントの高さの間で競合が発生します。

- parent: panelSplitterコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: panelSplitterコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてpanelSplitterコンポーネントが拡大されます。親が子を拡大しない場合、panelSplitterコンポーネントのサイズは子コンポーネントのサイズに基づきます。

7. コンポーネントにコンテンツを配置するには、必要なコンポーネントをfirstファセットおよびsecondファセットにドラッグ・アンド・ドロップします。orientationがhorizontalに設定されている場合、firstファセットがleftファセットになります。orientationがverticalに設定されている場合、firstファセットがtopファセットになります。子コンポーネントを拡大する場合には、拡大がサポートされているコンポーネントである必要があります。詳細は、8.4.2項「ジオメトリ管理およびpanelSplitterコンポーネントについて」を参照してください。
ファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、コンテナ・コンポーネントで子コンポーネントをラップする必要があります。含まれているすべてのコンポーネントを拡大するには、そのコンポーネントも拡大できる必要があります。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelSplitterコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・スプリッタ」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

8. 3つ以上のペインを作成するには、別のパネル・スプリッタ・コンポーネントをファセットに挿入し、ネストされたスプリッタ・ペインを作成します(図8-12を参照)。

図8-12 ネストしたpanelSplitterコンポーネント

例8-3に、スプリッタ・コンポーネントをネストする際に、JDeveloperによって生成されるコードを示します。

例8-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スクリプトをアタッチします。クライアント・サイドのイベントの詳細は、第5章「イベントの処理」を参照してください。

8.4.2 ジオメトリ管理およびpanelSplitterコンポーネントについて

panelSplitterコンポーネントは子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次のコンポーネントは、panelSplitterコンポーネントのfirstまたはsecondファセット内で拡大できます。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection

- panelDashboard

- panelGroupLayout(layout属性がscrollまたはverticalに設定されている場合のみ)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

panelSplitterコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout(layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelLabelAndMessage

- panelList

- showDetail

- showDetailHeader

- tableLayout(MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、panelSplitterコンポーネントのファセットに拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelBoxコンポーネントにコンテンツを配置し、panelSplitterコンポーネントのファセットに配置するように設定する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをpanelSplitterコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、8.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

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

panelBorderLayoutコンポーネントでは、ファセットを使用して、ページの事前定義済領域にコンポーネントを配置します。centerファセットではなく、panelBorderレイアウト・コンポーネントに直接の子コンポーネント(索引付きの子とも呼ばれる)を0～n配置します(連続して中央にレンダリングされます)。子コンポーネントはファセットで囲まれます。

図8-13に、panelBorderLayoutコンポーネントのファセットを示します。

図8-13 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コンポーネントを使用することを検討してください。詳細は、8.3項「コンテンツをページ全体に拡大するための設定」を参照してください。

8.5.1 panelBorderLayoutコンポーネントの使用方法

JSFページに使用できるpanelBorderLayoutコンポーネントの数に制限はありません。

panelBorderLayoutコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「パネル枠線レイアウト」をドラッグ・アンド・ドロップします。

2. コンポーネント・パレットから、panelBorderLayoutコンポーネントの子コンポーネントとして、ウィンドウ中央へのコンテンツの表示に使用するコンポーネントをドラッグ・アンド・ドロップします。
子コンポーネントは、挿入した順番で連続して表示されます。他のタイプのレイアウトで子コンポーネントを表示する場合は、panelGroupLayoutコンポーネントにそのコンポーネントをラップします。詳細は、8.12項「関連する項目のグループ化」を参照してください。

3. 中央を囲むコンテンツを配置するには、必要なコンポーネントを各ファセットにドラッグ・アンド・ドロップします。
ファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、コンテナで子コンポーネントをラップします。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelBorderLayoutコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル枠線レイアウト」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

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

panelFormLayoutコンポーネントを使用すると、入力フィールドや選択リスト・フィールドなど、複数のフォーム入力コンポーネントを1つ以上の列に配置できます。File Explorerアプリケーションでは、panelFormLayoutコンポーネントを使用してファイル・プロパティが表示されています。図8-14に示されているように、コンポーネントはラベルが右揃えになるように構成されています。

図8-14 フォーム内の右揃えのラベルおよび左揃えのフィールド

図8-15に、ラベルがフィールドの上に表示されるように構成されているコンポーネントを使用した同じページを示します。

図8-15 フォーム内でフィールドの上に表示されているラベル

panelFormLayoutコンポーネントを構成して、ラベル付きのフィールドを1列以上表示できます。フォームの各フィールドは、panelFormLayoutコンポーネントの子コンポーネントです。必要な行数を設定し、子コンポーネントが行より多い場合、残りの子コンポーネントは新しい列に配置されます。たとえば、25の子コンポーネントがあり、15行表示されるようにコンポーネントを設定した場合、残りの10のコンポーネントは2列目に表示されます。

ただし、それぞれに表示される行数は、構成された行数によってのみ決定されるわけではありません。panelFormLayoutコンポーネントは、デフォルトで、4列以上レンダリングしないように設定されています(PDAアプリケーションの場合は2列)。この値により、実際に行数が決定されます。たとえば、25の子コンポーネントがあり、5行表示するようにコンポーネントを設定し、デフォルトの最大列数を3に設定したままにした場合、5行表示するように設定しても、実際はコンポーネントにより9行表示されます。これは、最大列数が設定された行数をオーバーライドするためです。最大3列のみに設定されているため、すべての子コンポーネントを表示するには9行使用する必要があります。コンポーネントで5行のみが表示されるようにするには、最大列数を5に設定する必要があります。

ADF Facesでは、ブラウザの標準のHTMLフローで決定されたデフォルトのラベル幅およびフィールド幅が使用されます。また、ラベルおよびフィールドに使用する明示的な幅を指定できます。フォーム・レイアウト内の列数にかかわらず、指定する幅はすべてのラベルとフィールドに適用されます。幅は、ピクセル単位の絶対数またはパーセント値を使用して指定します。ラベルの長さが合ない場合は、テキストが折り返されます。

ヒント:

ページが英語以外の言語で表示される場合は、異なる言語および文字で使用するためにラベルに余分な空白を残す必要があります。

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

ページに1つ以上のpanelFormLayoutコンポーネントを使用して、必要なフォーム・レイアウトを作成できます。

panelFormLayoutを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「パネル・フォーム・レイアウト」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いてラベルの位置を設定します。
デフォルトで、子の入力コンポーネントのフィールド・ラベルはフィールドの横に表示されます。フィールドの上にラベルを配置するには、labelAlignment属性をtopに設定します。

注意:

panelFormLayoutコンポーネントを別のpanelFormLayoutコンポーネントにネストすると、ネストされたレイアウトのラベルの位置はtopになります。

3. rowsおよびmaxColumnsを設定して、フォーム内の行および列の数を指定します。
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行で表示されます。

ヒント:

レンダリングされた子コンポーネントが参照するのは、フォームの直接の子コンポーネントのみです。そのため、複数の行をレンダリングするコンポーネント(selectManyCheckboxなど)が子の場合は、そのすべての行がレンダリングされた単一の子とみなされ、別々の列に分割できません。

4. 必要に応じて、fieldWidthおよびlabelWidthを設定します。
ADF Facesでは、ブラウザの標準のHTMLフローで決定されたデフォルトのラベル幅およびフィールド幅が使用されます。また、ラベルおよびフィールドに使用する明示的な幅を指定できます。

panelFormLayoutコンポーネントのlabelWidth属性ではラベルの優先幅を、fieldWidth属性ではフィールドの優先幅を設定できます。

注意:

labelWidthコンポーネントに指定する値は、labelAlignment属性がtopに設定されていて、ラベルがフィールドの上に表示されるレイアウトでは無視されます。

フォーム・レイアウト内の列数にかかわらず、指定する幅はすべてのラベルとフィールドに適用され、列ごとに別々の幅を設定することはできません。幅は、CSS単位(em、pxまたは%など)を使用して指定します。使用する単位は、labelWidthおよびfieldWidth属性の両方で同一にする必要があります。

パーセント値を使用する場合は次のようにします。

- 指定するパーセント幅は、表示される列数に関係なく、panelFormLayoutコンポーネントが占有する幅全体のパーセントです。

- labelWidthおよびfieldWidthのパーセントの合計は、100%になる必要があります。合計が100%未満の場合、幅は100%になるように正規化されます。たとえば、labelWidthを10%に、fieldWidthを30%に設定した場合、実行時にlabelWidthは33%に、fieldWidthは67%になります。

- 一方の幅を明示的に設定してもう一方の幅を指定しない場合(labelWidthのパーセントは指定してfieldWidthは指定しないなど)、指定されていないパーセント幅がADF Facesにより自動的に計算されます。

注意:

フォームに複数の列とフッターが含まれている場合、パーセントの分数分割がサポートされていないWebブラウザでは、メインのフォーム項目とフッター項目の位置の間にわずかにオフセットが生じることがあります。この影響を最小限にするために、labelWidthのパーセントは、列数で均等に分割できるようにしてください。

panelFormLayoutコンポーネントの幅が領域の600ピクセルを占有し、labelWidth属性が50%に設定されているとします。1列に表示される場合、ラベル幅もフィールド幅も300ピクセルになります。2列に表示される場合は、各列が300ピクセルであるため、列の各ラベル幅とフィールド幅は150ピクセルになります。

ラベル・テキストの長さが指定されたラベル幅の1行に収まらない場合は、ADF Facesによりラベル・テキストが自動的に折り返されます。指定されたフィールド幅がpanelFormLayoutコンポーネントに配置した子コンテンツの最低サイズより狭い場合は、子コンテンツの最低サイズがフィールド幅として自動的に使用されます。

注意:

割り当てられた領域よりフィールドが広い場合、ブラウザはフィールドを切り捨てず、ラベル列の領域を使用します。これが原因で、ラベルが予想以上に折り返される可能性があります。この場合は、フィールド・コンテンツの幅を狭くすることを検討してください(inputTextコンポーネントに、幅がより狭いcontentStyleを使用するなど)。

5. 必要な子コンポーネントを挿入します。
通常は、入力テキストやチェック・ボックスを複数選択などのラベル付きのフォーム入力コンポーネント、およびユーザーの入力を可能にするその他の類似のコンポーネントを挿入します。

ヒント:

通常はpanelFormLayoutコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelFormLayoutコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

例8-4に、図8-14に表示されているFile Explorerアプリケーションのproperties.jspxページで使用されているpanelFormLayoutコンポーネントを示します。

例8-4 panelFormLayoutコンポーネント

<af:panelFormLayout rows="5" labelAlignment="top">
<af:inputText value="#{fileItemProperties.type}"
label="#{explorerBundle['fileproperties.type']}"
readOnly="true"/>  <af:inputText value="#{fileItemProperties.location}"
label="#{explorerBundle['fileproperties.currentpath']}"
readOnly="true"/>
<af:inputText value="#{fileItemProperties.size}"
label="#{explorerBundle['fileproperties.size']}"
readOnly="true"/>
<af:inputText value="#{fileItemProperties.contains}"
label="#{explorerBundle['fileproperties.contains']}"
readOnly="true"/>
</af:panelFormLayout>

ヒント:

入力以外のコンポーネント(label属性がない)を使用する場合、またはpanelFormLayoutコンポーネント内の単一のラベルで複数の入力コンポーネントをグループ化する場合は、まずpanelLabelAndMessageコンポーネントにコンポーネントをラップします。panelLabelAndMessageコンポーネントの使用方法の詳細は、17.4項「単一のラベルおよびメッセージを使用したコンポーネントのグループ化」を参照してください。

6. フォーム・レイアウトに意味的に関連する入力コンポーネントをグループ化するには、groupコンポーネントを使用してグループに属するコンポーネントをラップします。groupにコンポーネントを配置すると、panelFormLayoutコンポーネントによりグループの上下に区切り線が引かれます。
groupコンポーネントの使用方法の詳細は、8.6.2項「groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法について」を参照してください。

7. 子の入力コンポーネントの下にコンテンツを追加するには、必要なコンポーネントをfooterファセットに挿入します。
ファセットに使用できる子コンポーネントは1つのみです。footerファセットに複数のコンポーネントを挿入する必要がある場合は、panelGroupLayoutコンポーネントまたはgroupコンポーネントを使用してfooterの子コンポーネントをラップします。例8-5に、panelFormLayoutコンポーネントにpanelGroupLayoutコンポーネントを使用してfooterの子コンポーネントを配置するサンプル・コードを示します。

例8-5 水平に配置されたpanelFormLayoutのfooterの子コンポーネント

<af:panelFormLayout>
<f:facet name="footer">
<af:panelGroupLayout layout="horizontal">
<af:commandButton text="Save"/>
<af:commandButton text="Cancel"/>
<f:facet name="separator">
<af:spacer width="3" height="3"/>
</f:facet>
</af:panelGroupLayout>
</f:facet>
.
.
.
</af:panelFormLayout>

8.6.2 groupコンポーネントをpanelFormLayoutコンポーネントとともに使用する方法について

groupコンポーネント自体は何もレンダリングしませんが、panelFormLayoutコンポーネントの子として使用すると、各groupコンポーネントの子コンポーネントの周辺にセパレータが表示されます。たとえば、panelFormLayoutコンポーネントによって作成されたフォーム・レイアウト内のいくつかの入力フィールドをグループ化するとします。例8-15に、panelFormLayoutコンポーネント内の2セットの子コンポーネントをグループ化するサンプル・コードを示します。

例8-6 panelFormLayoutの子コンポーネントのグループ化

<af:panelFormLayout binding="#{editor.component}" rows="10" labelWidth="33%"
fieldWidth="67%" testId="panelFormLayout1">
<af:inputText columns="5" label="label 1"/>
<af:group>
<af:inputText columns="5" label="grouped 1" shortDesc="This one is secret!"
secret="true"/>
<af:inputText columns="5" label="grouped 2"/>
<af:inputText columns="5" label="grouped 3"/>
</af:group>
<af:inputDate id="df1" label="label 2"/>
<af:panelLabelAndMessage label="label 3" labelStyle="vertical-align: middle;">
<af:commandButton text="Submit"/>
</af:panelLabelAndMessage>
<af:selectOneListbox id="sol" label="label 4" shortDesc="Select One Option">
<af:selectItem label="option 1"/>
<af:selectItem label="option 2"/>
<af:selectItem label="option 3"/>
<af:selectItem label="option 4"/>
</af:selectOneListbox>
<af:selectManyListbox id="rs" label="label 5" shortDesc="Select Option">
<af:selectItem label="option 1"/>
<af:selectItem label="option 2"/>
<af:selectItem label="option 3"/>
<af:selectItem label="option 4"/>oiiiik,
</af:selectManyListbox>
</af:panelFormLayout>

図8-16に示されているように、例8-15のサンプル・コードでは、実行時にpanelFormLayoutコンポーネントにより子コンポーネントの1つ目のgroupの前後に点線のセパレータがレンダリングされます。

図8-16 panelFormLayoutのグループ化されたコンポーネント

8.6項「フォームでのコンテンツの配置」に説明されているように、panelFormLayoutコンポーネントでは特定のコンポーネント属性を使用して、列および行に子コンポーネント(グループ化された子およびグループ化されていない子)を表示する方法を決定します。子コンポーネントを複数列に表示するpanelFormLayoutコンポーネントの関連するコンポーネントをgroupコンポーネントを使用してグループ化すると、groupコンポーネントの子コンポーネントは同じ列に表示され、groupコンポーネント内の子コンポーネントが別々の列に分割されることはありません。

groupコンポーネントで子コンポーネントのレイアウトを設定することはできませんが、基礎となるHTML要素で、groupコンポーネント内の子コンポーネントを必要なレイアウトに設定できます。たとえば、groupコンポーネントの子のボタン・コンポーネントをフォーム・レイアウト内に水平に配置する場合は、panelGroupLayoutコンポーネントを使用してボタンをラップし、panelGroupLayoutコンポーネントのlayout属性をhorizontalに設定します。その後、例8-7に示すように、groupコンポーネントにpanelGroupLayoutコンポーネントを挿入します。

例8-7 groupコンポーネント内のpanelGroupLayout

<af:group>
<af:panelGroupLayout layout="horizontal">
<af:commandButton text="Save" ../>
<af:commandButton text="Cancel" ../>
<f:facet name="separator">
<af:spacer width="3"/>
</f:facet>
</af:panelGroupLayout>
</af:group>

panelFormLayoutコンポーネントのfooterファセットの子コンポーネントをgroupコンポーネントを使用してグループ化する場合は、例8-8に示すように、すべてのgroupコンポーネントおよびグループ化されていないその他の子コンポーネントを、1つのルートgroupコンポーネントに配置する必要があります。

例8-8 ルートgroupコンポーネントが1つ含まれるpanelFormLayoutのfooterファセット

<af:panelFormLayout ...>
<f:facet name="footer">
<!-- One root group component needed -->
<af:group>
<af:outputText value="Footer item 1"/>
<!-- One group -->
<af:group>
<af:outputText value="Group 1 item 1"/>
<af:outputText value="Group 1 item 2"/>
</af:group>
<af:panelGroupLayout layout="horizontal">
<af:commandButton text="Save"/>
<af:commandButton text="Cancel"/>
<f:facet name="separator">
<af:spacer width="3"/>
</f:facet>
</af:panelGroupLayout>
</af:group>
</f:facet>
.
.
.
</af:panelFormLayout>

図8-17に示されているように、panelFormLayoutコンポーネントのグループ化された子コンポーネントと同じように、panelFormLayoutコンポーネントにより、実行時にfooterファセットの各groupコンポーネントの子コンポーネントの周辺に点線のセパレータがレンダリングされます。

図8-17 グループ化されたコンポーネントを含むpanelGroupLayoutのfooter

注意:

panelFormLayoutコンポーネントのfooterファセットでサポートされているのは、2レベルのグループ化されたコンポーネントのみで、footerファセットに3レベル以上ネストしたgroupコンポーネントを配置することはできません。たとえば、次のコードは無効です。

<f:facet name="footer">
<!-- Only one root group -->
<af:group>
<af:outputText value="Footer item 1"/>
<!-- Any number of groups at this level -->
<af:group>
<af:outputText value="Group 1 item 1"/>
<af:outputText value="Group 1 item 2"/>
<!-- But not another nested group. This is illegal. -->
<af:group>
<af:outputText value="Nested Group 1 item 1"/>
<af:outputText value="Nested Group 1 item 2"/>
</af:group>
</af:group>
<af:outputText value="Another footer item"/>
</af:group>
</f:facet>

panelFormLayoutコンポーネントのfooterファセットと本体のどちらにコンポーネントをグループ化しているかにかかわらず、panelFormLayoutコンポーネントかfooterファセットの最初または最後の子がgroupコンポーネントの場合、そのgroupの子コンポーネントの周辺にはセパレータは表示されません。たとえば、例8-9のどちらのコード例でも、実行時に生成される外観は同じです。

例8-9 同じ外観を生成するコード

<!-- Example 1: Group of buttons is last child in root group -->
<f:facet name="footer">
<af:group>
<af:outputText value="Footer text item 1"/>
<af:outputText value="Footer text item 2"/>
<af:group>
<af:inputText label="Nested group item 1"/>
<af:inputText label="Nested group item 2"/>
</af:group>
<af:group>
<af:panelGroupLayout layout="horizontal">
<af:commandButton text="Cancel"/>
<af:commandButton text="Save"/>
</af:panelGroupLayout>
</af:group>
</af:group>
</f:facet>

<!-- Example 2: panelGroupLayout of buttons is last child in root group-->
<f:facet name="footer">
<af:group>
<af:outputText value="Footer text item 1"/>
<af:outputText value="Footer text item 2"/>
<af:group>
<af:inputText label="Nested group item 1"/>
<af:inputText label="Nested group item 2"/>
</af:group>
<af:panelGroupLayout layout="horizontal">
<af:commandButton text="Cancel"/>
<af:commandButton text="Save"/>
</af:panelGroupLayout>
</af:group>
</f:facet>

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

panelDashboardコンポーネントでは、panelFormコンポーネントと同様に、行および列にその子コンポーネントを配置できます。ただし、図8-18に示されているように、panelDashboardの子は、テキスト・コンポーネントではなく、コンテンツを含むpanelBoxコンポーネントです。

図8-18 panelBoxの子コンポーネントを含むpanelDashboard

panelDashboardコンポーネントを追加する場合、コンポーネントに含まれる列数および各行の高さを構成します。ダッシュボードは、子を拡大して構成済の領域を埋めます。すべての子コンポーネントが、指定した列数と行の高さ内に収まらない場合、panelDashboardコンポーネントにスクロールバーが表示されます。

子を拡大するコンポーネントに配置すると、子の数に関係なく、デフォルトでpanelDashboardが親コンテナを埋めるために拡大されます。つまり、ブラウザのサイズがダッシュボードで必要なサイズより大きくなると、ダッシュボードに空白の領域ができる場合があります。

たとえば、dimensionsFrom属性をparentに設定して、サイズを親から継承するようにpanelDashboardを設定したとします。columnsを1に設定し、rowHeightを50pxに設定します。次に、panelBoxコンポーネントを2つ追加します。columnsは1に設定されているため、2行になります。親コンポーネントはpanelStretchLayoutのため、ボックスの高さに関係なく、panelDashboardはpanelStretchLayoutを埋めるために拡大され、図8-19に示すように、余分な領域ができます(境界をわかりやすくするために、ダッシュボードの色をピンクに変更しています)。

図8-19 領域を埋めるために拡大されるpanelDashboard

かわりに、ダッシュボードを拡大しない場合は、子を拡大しないコンポーネントに配置し、その子に基づいてサイズを決定できるようにpanelDashboardを構成できます(dimensionsFrom属性をchildrenに設定)。これにより、子を表示するのに必要な行数と同じ高さになります(rowHeight属性を乗算)。

前述の例で、scrollに設定されたpanelGroupLayoutにダッシュボードをかわりに配置する場合は、rowHeightが50に設定されているため、図8-20に示すように、ブラウザ・ウィンドウのサイズに関係なく、panelDashboardは常に100pxより少し高くなります。

図8-20 拡大しないpanelDashboard

panelDashboardコンポーネントでは、宣言的なドラッグ・アンド・ドロップ動作もサポートされており、ユーザーは子コンポーネントを再配置できます。図8-21に示されているように、ユーザーは、たとえばpanelBox 10をpanelBox 4とpanelBox 5の間に移動できます。ボックスをドロップできる場所にはシャドウが表示されます。

図8-21 panelDashboardのドラッグ・アンド・ドロップ機能

注意:

panelDashboardコンポーネントとの間でコンポーネントをドラッグできるドラッグ・アンド・ドロップ機能を構成することもできます。詳細は、32.6項「panelDashboardコンポーネントに対するドラッグ・アンド・ドロップ機能の追加」を参照してください。

panelDashboardコンポーネントには、子コンポーネントを移動できる機能に加え、APIも用意されており、このAPIにアクセスして、ユーザーが子コンポーネントをレンダリングするかレンダリングしないかを切り替えられるようにし、挿入または削除されているpanelBoxesの外観を提供できます。ダッシュボードでは、部分ページ・レンダリングによって新しい一連の子コンポーネントが再描画されるため、ページ全体を再描画する必要がありません。

panelDashboardBehaviorタグを使用して、コンポーネントのレンダリングの応答性を向上させることができます。このタグを使用すると、コマンド・コンポーネントをアクティブ化し、視覚的な変更をダッシュボードに適用してから、アプリケーション・コードでサーバーのコンポーネント・ツリーを変更できます。アクション・イベントがサーバーに送信される前に、この領域の拡大が行われるため、コマンド・コンポーネントのアクション・リスナーがコンポーネント・ツリーを変更し、ダッシュボードでの挿入の最適化されたエンコーディングを準備している間に、ユーザーはすぐにフィードバックを確認できます。

たとえば、図8-22は、panelSplitterコンポーネントの右パネルで使用されるpanelDashboardコンポーネントを示しています。左パネルにリンクとして表示されているリスト項目は、panelDashboardの各panelBoxコンポーネントを表しています。すべてのpanelBoxコンポーネントが表示されている場合、リンクはすべて非アクティブです。ただし、ユーザーがpanelBoxコンポーネントの1つを削除すると、対応するリンクがアクティブになります。ユーザーはそのリンクをクリックして、panelBoxを再挿入できます。panelDashboardBehaviorタグをcommandLinkコンポーネントとともに使用することで、ユーザーは挿入済ボックスの描画を確認できます。

図8-22 panelDashboardBehaviorタグを使用するcommandLinkコンポーネント

このタグを使用しない場合、アクション・リスナーが処理している間、ユーザーがダッシュボード構造に対する変更を確認できるまで多少の遅延があります。

図8-23は、panelDashboardコンポーネントを使用した実際的な例を示しています。ページの上部にあるリンクの1つを選択すると、ダッシュボードに表示されるpanelBoxesが変わります。ページの左側にある関連リンクをクリックして、panelBoxを追加することもできます。

図8-23 panelDashboardの実際的な例

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

panelDashboardをページに追加すると、ダッシュボードが拡大するかどうかを構成できます。その後、子コンポーネントを追加し、コンポーネントを再配置できるようにする場合は、子コンポーネントにもcomponentDragSourceタグを追加します。コンポーネントの挿入および削除を許可する場合は、アクションを処理するためのリスナーを実装します。panelDashboardBehaviorタグを使用して、panelDashboardコンポーネントでの挿入への応答性を向上させることもできます。

panelDashboardコンポーネントを使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、ページに「パネル・ダッシュボード」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。

3. columnsを、子コンポーネントを表示するために使用する列数に設定します。子コンポーネントは各列に合せて拡大されます。

4. rowHeightを、各行の高さのピクセル数に設定します。子コンポーネントは、この高さまで拡大されます。

5. デフォルトでは、panelDashboardコンポーネントは、使用可能なブラウザの領域を埋めるために拡大されます。子を拡大しないコンポーネントの子としてpanelDashboardコンポーネントをかわりに使用する場合は、panelSplitterコンポーネントの拡大の処理方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントを拡大するかどうかを構成します。これを行うには、「その他」セクションを開き、dimensionsFromを次のいずれかに設定します。

- children: panelDashboardコンポーネントが子からディメンションを取得します。

注意:

この設定を使用している場合は、(たとえば、inlineStyleまたはstyleClass属性から)panelDashboardコンポーネントの高さを設定することはできません。そうすると、panelDashboardの高さと子コンポーネントの高さの間で競合が発生します。

- parent: panelDashboardコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: panelDashboardコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてpanelDashboardコンポーネントが拡大されます。親が子を拡大しない場合、panelDashboardコンポーネントのサイズは子コンポーネントのサイズに基づきます。

6. コンポーネント・パレットから、panelBox子コンポーネントをドラッグ・アンド・ドロップします。

ヒント:

panelDashboardコンポーネントでは、regionコンポーネントも子コンポーネントとしてサポートされています。

7. ユーザーが子コンポーネントを並べ替えられるようにするには、コンポーネント・パレットの「操作」パネルから、「コンポーネント・ドラッグ元」を各子コンポーネントの子としてドラッグ・アンド・ドロップします。

8. コンポーネントを追加および削除できるようにする場合は、マネージドBeanを作成し、子の追加またはドロップ時に子の並替えを行うハンドラ・メソッドを実装します。このイベントはドロップ・イベントとみなされるため、ドラッグ・アンド・ドロップ・フレームワークを使用する必要があります。ドロップ・イベントのハンドラの作成の詳細は、第32章「ドラッグ・アンド・ドロップ機能の追加」を参照してください。
最適化されたライフサイクルを使用するには、ハンドラにpanelDashboardコンポーネントのprepareOptimizedEncodingOfInsertedChild()メソッドをコールさせます。これにより、挿入された子コンポーネントのみがレンダリングのためにダッシュボードから送信されます。

注意:

panelDashboardBehaviorタグを使用する予定の場合は、関連付けられているコマンド・コンポーネントのactionListenerハンドラからこのAPIをコールする必要があります。

9. 手順7でcomponentDragSourceタグを追加した場合、panelDashboardのDropEventハンドラも実装する必要があります。panelDashboardコンポーネントを選択している状態で、「動作」セクションを開き、DropListener属性をハンドラ・メソッドにバインドします。

10. panelDashboardBehaviorタグを使用する場合は、挿入を開始するために使用するコマンド・コンポーネントをドラッグ・アンド・ドロップします。

11. プロパティ・インスペクタで、コンポーネント・ツリーに対する変更を処理するマネージドBeanのハンドラに、コマンド・コンポーネントのactionListenerをバインドします。ハンドラにpanelDashboardコンポーネントのprepareOptimizedEncodingOfInsertedChild()メソッドをコールさせます(これにより、挿入された子コンポーネントのみがダッシュボードから送信されてレンダリングされます)。例8-10に、子コンポーネントの挿入を処理するマネージドBeanのコードを示します。

例8-10 「挿入」ボタンのアクション・リスナー・コード

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ツリーに挿入され、このツリーで、実際のコンポーネントがサーバーから戻されるとレンダリングされます。サーバーで挿入が行われる前に挿入のプレースホルダが追加されるため、ユーザーがページをリロードしても、子が継続的に同じ順序で表示されるように、子コンポーネントの挿入場所を指定する必要があります。

8.7.2 ジオメトリ管理およびpanelDashboardコンポーネントについて

このコンポーネントでは、列数およびrowHeight属性に基づき、子がグリッドに編成されます。panelDashboard内で拡大可能な子コンポーネントは次のとおりです。

- inputText(rows属性が1より大きい数値に設定されており、simple属性がtrueに設定されている場合)

- panelBox

- region

- table(拡大するように構成されている場合)

その他のコンポーネントを子コンポーネントとしてpanelDashboardコンポーネントに配置しようとすると、コンポーネントの階層は無効になります。

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

ユーザーがコンテンツの表示または非表示を選択できるようにすることが必要な場合があります。ユーザー・インタフェースのすべての機能を一度に表示する必要がなければ、ユーザーの意志でインタフェースの一部を表示および非表示にできるコンポーネントを使用して領域を節約できます。

showDetailコンポーネントを使用すると、ユーザーがラベルの下のコンテンツを開いた状態(表示)または閉じた状態(非表示)にすることが可能な切替えアイコン付きのラベルを作成できます。コンテンツが閉じた状態(非表示)の場合、デフォルトのラベルは「表示」で、切替えアイコンにはボックスの中にプラス記号が表示されます。コンテンツが開いた状態(表示)の場合、デフォルトのラベルは「非表示」で、切替えアイコンにはマイナス記号に変わります。

たとえば、File ExplorerアプリケーションのnewFileItemページでは、showDetailコンポーネントを使用してファイル・プロパティを表示および非表示にしています。図8-24に示すように、コンポーネントは、ページが表示されたらプロパティが非表示になるように構成されています。

図8-24 閉じた状態のshowDetail

ユーザーが切替えアイコンをクリックすると、図8-25に示されているようにプロパティが表示されます。

図8-25 開いた状態のshowDetail

表示されているテキストおよび非表示のテキストを表示するために、outputTextコンポーネントより複雑なものを使用する場合は、コンポーネントをshowDetailコンポーネントのpromptファセットに追加できます。表示に設定すると、promptファセットのコンテンツが、表示されているテキストおよび非表示のテキストの値と置き換えられます。showDetailコンポーネントの使用方法は、8.8.1項「showDetailコンポーネントの使用方法」を参照してください。

showDetailコンポーネントと同じように、showDetailHeaderコンポーネントでもコンテンツの表示を切り替えられますが、showDetailHeaderコンポーネントにはヘッダーにラベルと切替えアイコンがあり、メニュー・バー、ツールバーおよびテキスト用のファセットも用意されています。

ヒント:

showDetailHeaderコンポーネントは、表示イベントを処理することを除き、panelHeaderコンポーネントと同じです。panelHeaderコンポーネントの詳細は、8.10項「静的ボックスの項目の表示」を参照してください。

タイトル行のすべてのファセットにすべてを表示する十分な領域がない場合、showDetailHeaderテキストは切り捨てられ、省略記号が表示されます。切り捨てられたテキストの上にマウスを置くと、図8-26に示すように、完全なテキストがツールチップに表示されます。

図8-26 切り捨てられているshowDetailHeaderのテキスト

コンテンツの表示に十分な領域がある場合は、図8-27に示すように、余分な領域がcontextファセットとツールバーの間に配置されます。

図8-27 ツールバーの前に追加される余分な領域

また、showDetailHeaderコンポーネントは、エラー、警告、情報または確認のメッセージとして使用するように構成できます。コンテンツは、ヘッダーの下で表示または非表示になります。たとえば、File ExplorerアプリケーションのnewFileItemページでは、showDetailHeaderコンポーネントを使用して、新しいファイルを作成するためのヘルプを表示しています。図8-25に示されているように、デフォルトではヘルプは表示されません。ユーザーがヘッダーの切替えアイコンをクリックすると、図8-28に示されているようにコンテンツが表示されます。

図8-28 ヘルプの表示に使用されているshowDetailHeaderコンポーネント

showDetailHeaderコンポーネントは、panelHeaderコンポーネントとともに使用して、ページをセクションおよびサブセクションに分割することもできます(コンテンツの一部を非表示にできます)。showDetailHeaderコンポーネントには、ツールバーやメニュー・バー・ファセットなど、多数のファセットが含まれます。これらのファセットは、panelHeaderコンポーネントのものと同じです。panelHeaderコンポーネントの詳細は、8.10項「静的ボックスの項目の表示」を参照してください。

showDetailHeaderコンポーネントをネストさせて、コンテンツの階層を作成できます。ネストされた各コンポーネントのヘッダーは、階層を示すために異なるスタイルになります。図8-29に、ネストした3つのshowDetailHeaderコンポーネントおよびその異なるスタイルを示します。

図8-29 ネストしたshowDetailHeaderコンポーネントにより作成された階層

各ヘッダー・レベルで使用されているスタイルは、showDetailHeaderコンポーネントにスキンを適用することで変更できます。ADF Facesコンポーネントのスキンの詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

注意:

サイズの処理は、デフォルトでヘッダー・コンポーネントの物理包含によって決定されます。つまり、最初のヘッダー・コンポーネントは見出しレベル1としてレンダリングされます。最初のヘッダー・コンポーネントにネストされるヘッダー・コンポーネントは見出しレベル2などとしてレンダリングされます。各ヘッダー・コンポーネントの見出しレベルは、headerLevel属性を使用して手動でオーバーライドできます。

panelBoxコンポーネントは、ヘッダーの下に情報を表示または非表示にできるようにする場合、およびページのその他の情報と分けるためのボックスが必要な場合に使用します。File Explorerアプリケーションでは、図8-30に示すように、properties.jspxページに2つのpanelBoxコンポーネントを使用して、属性およびファイルの履歴を表示します。

図8-30 2つのpanelBoxコンポーネント

図8-31に、「履歴」panelBoxコンポーネントが非表示の状態になっている同じページを示します。

図8-31 非表示のpanelBoxコンポーネント

panelBoxコンポーネントに背景色を設定して、コンテンツをページの残りの部分とさらに区別することができます。2色の組合せ(ランプと呼ばれる)が用意されており、各組合せにはnone、light、mediumおよびdarkの4つの色のレベルがあります。図8-32に図8-30と同じパネル・ボックスを示しますが、下のpanelBoxコンポーネントはcoreランプの中間色が表示されるように構成されています。

図8-32 背景色を使用したパネル・ボックス

panelBoxコンポーネントのサイズは、ピクセル・サイズを明示的に割り当てて設定することも、親に対する割合で設定することもできます。また、タイトルの位置を設定することも、アイコンを追加することもできます。また、panelBoxコンポーネントには、ボックスにツールバーおよびツールバー・ボタンを追加できるtoolbarファセットがあります。

コンテンツの複数の大きな領域を表示および非表示にする必要がある場合は、panelAccordionおよびpanelTabbedコンポーネントの使用を検討してください。詳細は、8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照してください。

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

コンテンツの1セットを表示および非表示にするには、showDetailコンポーネントを使用します。

showDetailコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「詳細の表示」をドラッグ・アンド・ドロップします。

ヒント:

このコンポーネントは、コンポーネント・パレットの「レイアウト」パネルではなく、「共通コンポーネント」パネルに表示されます。

2. プロパティ・インスペクタで、「共通」セクションを開き、必要に応じて属性を設定します。
コンポーネントの子コンポーネントを表示する場合は、disclosedをtrueに設定します。

注意:

コンテンツを表示および非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

disclosedTextを、コンテンツが開いた状態(表示)の場合に切替えアイコンの隣に表示するラベルに設定します。値が指定されない場合、ラベルはデフォルトで「非表示」になります。

undisclosedTextを、コンテンツが閉じた状態(非表示)の場合に切替えアイコンの隣に表示するラベルに設定します。値が指定されない場合、ラベルはデフォルトで「表示」になります。

注意:

disclosedTextには値を指定してundisclosedTextには指定しない場合、ADF Facesにより、開いた状態および閉じた状態の両方にdisclosedTextの値が自動的に使用されます。同様に、undisclosedTextには値を指定してdisclosedTextには指定しない場合、コンテンツが非表示または表示されると、undisclosedTextの値が使用されます。

disclosedTextおよびundisclosedTextに指定されたテキストを使用するかわりに、promptファセットを使用して、切替えアイコンの隣にレンダリングされるコンポーネントを追加できます。

3. 「動作」セクションを開き、ユーザーがコンポーネントのコンテンツを表示または非表示にする際に実行する必要のあるバッキングBeanで、disclosureListenerをdisclosureListenerメソッドに設定します。
表示イベントおよびリスナーの詳細は、8.8.4項「表示イベントについて」を参照してください。

4. コンテンツを追加するには、必要な子コンポーネントをshowDetailコンポーネントに挿入します。

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

showDetailHeaderコンポーネントは、ヘッダーの下にコンテンツを1セット表示する必要がある場合や、表示または非表示にできるメッセージとしてコンテンツを使用する場合に使用します。showDetailHeaderコンポーネントは、コンテンツを非表示にできるようにする場合に、ヘッダーおよびコンテンツの階層を作成する際にも使用できます。

showDetailHeaderコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「ディテール・ヘッダーの表示」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。textを、セクション・ヘッダーのラベルにするテキスト文字列に設定します。

3. iconを、セクション・ヘッダーのアイコンに使用するイメージ・ファイルのURIに設定します。アイコン・イメージはヘッダー・ラベルの前に表示されます。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

4. 特定のメッセージ情報の表示にヘッダーを使用している場合は、messageTypeを次のいずれかの値に設定します。

- confirmation: 指定されたアイコン・イメージが確認アイコン(上に緑のチェックマークが表示されたメモ・ページ)に置き換えられます。

- error: 指定されたアイコン・イメージがエラー・アイコン(中にxがある赤い丸)に置き換えられます。ヘッダー・ラベルも赤に変わります。

- info: 指定されたアイコン・イメージが情報アイコン(中にIがある青い丸)に置き換えられます。

- warning: 指定されたアイコン・イメージが警告アイコン(中に感嘆符がある黄色の三角)に置き換えられます。

- none: デフォルト。icon属性に指定されていないかぎり、アイコンは表示されません。

図8-33に、メッセージ・タイプに使用される各アイコンを示します。

図8-33 メッセージ・タイプに使用されるアイコン

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

5. コンポーネントの子コンポーネントを表示する場合は、disclosedをtrueに設定します。

注意:

コンテンツを表示および非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

6. 「動作」セクションを開き、ユーザーがコンポーネントのコンテンツを表示または非表示にする際に実行する必要のあるバッキングBeanで、disclosureListenerをdisclosureListenerメソッドに設定します。
表示イベントおよびリスナーの詳細は、8.8.4項「表示イベントについて」を参照してください。

7. showDetailHeaderコンポーネントによるジオメトリ管理の処理方法を制御するには、「その他」セクションを開き、「タイプ」を設定します。コンポーネントまたは子を拡大しない場合は、flowに設定します。showDetailHeaderコンポーネントの高さは、その子によってのみ決定されます。それ自体とその子を拡大する場合は(1つの子コンポーネントのみ拡大)場合は、stretchに設定します。showDetailHeaderコンポーネントの親コンポーネントでジオメトリ管理を決定する場合は、デフォルトのままにします。ジオメトリ管理の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

8. ヘッダーにボタンまたはアイコンを追加するには、コンポーネント・パレットの「共通コンポーネント」パネルから、toolbarファセットにtoolbarをドラッグ・アンド・ドロップします。その後、新しく挿入されたtoolbarコンポーネントに、任意の数のcommandToolbarButtonまたはcommandButtonコンポーネントを追加します。toolbarコンポーネントの使用方法の詳細は、14.3項「ツールバーの使用方法」を参照してください。

注意:

panelHeaderコンポーネントでは、ツールバーのオーバーフローはサポートされていません。

9. ヘッダーにメニューを追加するには、menuBarファセットにmenuコンポーネントを挿入します。メニュー作成の詳細は、14.2項「メニュー・バーでのメニューの使用方法」を参照してください。

ヒント:

toolbarファセットにメニューを配置することも、menuファセットにツールバー(およびツールボックス)を配置することも可能です。これらのファセットの主な違いは場所です。toolbarファセットはmenuファセットの前に配置されます。

10. コンポーネントの見出しレベルをオーバーライドするには、headerLevelを目的のレベル(H1、H2などからH6)に設定します。
見出しレベルは、特にスクリーン・リーダー・アプリケーションで使用する場合に、正しいページ構造を決定するのに使用されます。デフォルトで、headerLevelは-1に設定されており、ページの物理的位置に基づいて、ヘッダーでサイズを決定できます。つまり、最初のヘッダー・コンポーネントはH1に設定されます。そのH1コンポーネントにネストされるヘッダー・コンポーネントはH2などに設定されます。

注意:

スクリーン・リーダー・アプリケーションでは、HTMLヘッダー・レベルの割当てを利用して、ページの基本構造を識別します。ヘッダー・コンポーネントおよびヘッダー・レベルの割当てがページで意味をなすようにしてください。

オーバーライド値を使用する場合は、ページの公開可能なセクション内にヘッダーを含めた場合の影響について考慮してください。たとえば、ページに縮小可能な領域がある場合は、領域が縮小および表示されるときに、オーバーライドされた構造が意味を持つようにする必要があります。

11. 見出し階層の構造ではなく、ヘッダー・テキストのサイズのみを変更する場合は、size属性を設定します。
size属性では、ヘッダー・テキストに使用する数値を指定し、スキンをオーバーライドします。最大数値は0で、H1ヘッダー・レベルに対応し、最小数値は5で、H6ヘッダーに対応します。

デフォルトで、size属性は-1です。これは、ADF Facesにより、使用するヘッダー・レベルのスタイルが最上位の親コンポーネントから自動的に計算されることを意味します。ネストされているコンポーネントを使用する場合は、size属性を明示的に設定して、表示する適切なヘッダー・スタイルを取得する必要はありません。

注意:

テキストのスタイルはsize属性を使用して強制できますが(最大のテキストが0の場合)、size属性の値は階層には影響しません。影響を受けるのはテキストのスタイルのみです。

ADF Facesにより使用されるデフォルトのスキンでは、サイズ3以上に使用されるスタイルがサイズ2と同じように表示されます。つまり、サイズ3、4または5のスタイルには違いがなく、すべてサイズ2と同じスタイルで表示されます。これは、カスタム・スキンを作成することで変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

12. セクションまたはサブセクションにコンテンツを追加するには、必要な子コンポーネントをshowDetailHeaderコンポーネントに挿入します。

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

ページには、任意の数のpanelBoxコンポーネントを挿入できます。

panelBoxコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「パネル・ボックス」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「外観」セクションを開き、rampに使用するランプを選択します。
coreランプでは様々な青が使用され、highlightランプでは様々な黄色が使用されます。使用する色は、カスタム・スキンを作成することで変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

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メソッドに設定します。
表示イベントおよびリスナーの詳細は、8.8.4項「表示イベントについて」を参照してください。

8. ツールバー・ボタンを追加するには、コンポーネント・パレットの「共通コンポーネント」パネルから、toolbarファセットにtoolbarをドラッグ・アンド・ドロップします。その後、toolbarコンポーネントに、必要な数のcommandToolbarButtonコンポーネントを挿入します。toolbarおよびcommandToolbarButtonコンポーネントの使用方法の詳細は、14.3項「ツールバーの使用方法」を参照してください。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelBoxコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ボックス」→「ツールバー」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

9. 表示するコンテナにコンテンツを追加するには、必要なコンポーネントをpanelBoxコンポーネントの子コンポーネントとして挿入します。
通常、panelBoxコンポーネントに子コンポーネントを1つ挿入し、その子コンポーネントに表示するコンテンツを挿入します。この子コンポーネントでコンテンツの表示方法を制御できますが、親のpanelBoxコンポーネントは制御できません。

10. panelBoxコンポーネントの幅を変更するには、inlineStyle属性を希望する正確なピクセル・サイズに設定します。または、inlineStyle属性を、panelBoxコンポーネントが含まれる外側の要素の割合に設定します。例8-11に、幅を変更するために使用するコードを示します。

例8-11 inlineStyle属性が設定されたpanelBoxコンポーネント

<af:panelBox inlineStyle="width:50%;" ...>
<!-- child contents here -->
</af:panelBox>

8.8.4 表示イベントについて

showDetail、showDetailHeaderおよびpanelBoxコンポーネントなどのように、組込みのイベント機能のあるADF Facesコンポーネントは、formコンポーネントで囲む必要があります。

これらのコンポーネントのdisclosed属性では、ヘッダーの下のコンテンツを表示(開いた状態)または非表示(閉じた状態)のどちらにするかを指定します。デフォルトではdisclosed属性はtrueで、コンテンツが表示されます。この属性がfalseに設定されていると、コンテンツは非表示になります。コンテンツが開いた状態と閉じた状態を相互に切り替えるためにコードを記述する必要はありません。切替えは、ADF Facesにより自動的に処理されます。

disclosed属性の値は実行時に永続可能であるため、ユーザーがコンテンツを表示または非表示にした場合、ADF Facesでは属性値を変更して保持できるので、その値はユーザーのセッション中その状態のままになります。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

ユーザーが切替えアイコンをクリックしてコンテンツを表示または非表示にすると、コンポーネントからサーバーにorg.apache.myfaces.trinidad.event.DisclosureEventイベントが送信されます。DisclosureEventイベントには、ソース・コンポーネントおよびその状態、つまり表示(開いている)または非表示(閉じている)に関する情報が含まれています。isExpanded()メソッドは、ノードを開く(表示)か閉じる(非表示)かを決定するブール値を返します。コンポーネントにそのコンテンツの表示および非表示のみを行わせる場合は、コードを記述する必要はありません。

ただし、DisclosureEventイベントの特別な処理を実行する場合は、コンポーネントのdisclosureListener属性をバッキングBeanのdisclosureListenerメソッドにバインドできます。ユーザーが表示されているまたは非表示のアイコンをクリックするたびに、DisclosureEventイベントへのレスポンスとしてdisclosureListenerメソッドが起動されます。

例8-12に示されているように、disclosureListenerメソッドは、単一のdisclosureEventイベント・オブジェクトを持つpublicメソッドで、戻りタイプがvoidである必要があります。

例8-12 disclosureListenerメソッド

public void some_disclosureListener(DisclosureEvent disclosureEvent) {
// Add event handling code here
}

コンポーネントのimmediate属性がtrueに設定されている場合以外、DisclosureEventイベントはデフォルトでは、アプリケーションの起動フェーズに送信されます。immediate属性がtrueに設定されている場合、イベントは可能なかぎり早期のフェーズ(通常はリクエスト値の適用フェーズ)で送信されます。

クライアント側のコンポーネントでは、AdfDisclosureEventイベントが起動されます。クライアントのAdfDisclosureEventイベントのイベント・ルートは、イベントのソース・コンポーネントに設定されており、disclosed属性がtrueのパネルに対するイベントのみがサーバーに送信されます。クライアント側のイベントおよびイベント・ルートの詳細は、第5章「イベントの処理」を参照してください。

8.9 アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示

非表示および表示できるコンテンツの複数の領域を表示する必要がある場合は、panelAccordionまたはpanelTabbedコンポーネントを使用できます。どちらのコンポーネントでも、showDetailItemコンポーネントを使用して実際のコンテンツを表示します。

panelAccordionコンポーネントを使用すると、開くことのできる一連のペインを作成できます。ユーザーがいつでも複数のパネルを開いたり、一度に1つのパネルのみを開けるようにできます。複数のパネルを開いている場合は、showDetailItemコンポーネントのヘッダーをドラッグして、パネルの高さを調整できます。

パネルが閉じている場合は、パネル・ヘッダーのみが表示され、パネルが開いている場合は、パネル・ヘッダーの下にパネル・コンテンツが表示されます(panelAccordionコンポーネントのヘッダーまたは展開アイコンをクリックしてペインを開くことができます)。図8-34に示されているように、File ExplorerアプリケーションではpanelAccordionコンポーネントを使用して、「フォルダ」および「検索」ペインを表示しています。

図8-34 panelAccordionペイン

実行時、使用可能なブラウザの領域が、開かれたパネルのコンテンツの表示に必要な領域より少ない場合、表示されていないペインをユーザーが選択して移動できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。図8-35に、「検索」パネルを表示する十分な領域がない場合に、File Explorerアプリケーションの「フォルダ」パネルに表示されるオーバーフロー・アイコン(丸で囲まれている右下のアイコン)を示します。

図8-35 panelAccordionのオーバーフロー・アイコン

ユーザーがオーバーフロー・アイコンをクリックすると、ユーザーが選択してナビゲートするためのオーバーフロー・ポップアップ・メニューが表示されます(図8-36を参照)。

図8-36 panelAccordionのオーバーフロー・ポップアップ・メニュー

図8-37に示すように、ドラッグ・アンド・ドロップしてペインを再配置できるように、panelAccordionを構成することもできます。

図8-37 ドラッグ・アンド・ドロップで並べ替えることができるペイン

順序を変更すると、showDetailItemコンポーネントのdisplayIndex属性も変更され、新しい順序が反映されます。

注意:

オーバーフローの項目を並べ替えることはできません。

panelAccordionコンポーネントの使用方法は、8.9.1項「panelAccordionコンポーネントの使用方法」を参照してください。

panelTabbedコンポーネントを使用すると、タブ付きの一連のペインを作成できます。panelAccordionペインとは異なり、panelTabbedペインは閉じることも開くこともできません。かわりに、ユーザーがタブを選択すると、選択したタブのコンテンツが表示されます。タブは表示領域の上か、表示領域の下、あるいはその両方に表示されます。個々のタブを閉じられるようにpanelTabbedコンポーネントを構成できます。このコンポーネントは、すべてのタブを閉じる、最後のタブを除いてすべて閉じる、またはタブを閉じないように構成できます。タブが閉じられるように構成されている場合、タブの最後にXが表示されます。無効なX(閉じることはできるが、現在無効になっている)が表示されるようにタブを構成することもできます。

各タブのコンテンツを含むshowDetailItemコンポーネントが作成されるタイミングを構成できます。タブの数が少ない場合は、現在表示されているタブに関係なく、panelTabbedコンポーネントが最初に作成されたときに、すべてのshowDetailItemコンポーネントを作成できます。ただし、panelTabbedコンポーネントに多数のshowDetailItemコンポーネントが含まれていると、ページのレンダリングが遅くなる場合があります。パフォーマンスを上げるには、対応するタブが選択された場合にのみshowDetailItemコンポーネントが作成されるように、panelTabbedコンポーネントをかわりに構成します。さらに、ユーザーが異なるタブを選択した場合にshowDetailItemを破棄するか、アクセスするたびに再作成する必要がないように、選択したshowDetailItemコンポーネントをコンポーネント・ツリーに保持するように配信メソッドを構成できます。

File ExplorerアプリケーションではpanelTabbedコンポーネントを使用して、図8-38に示されているように、メインのパネルにコンテンツを表示しています。

図8-38 panelTabbedペイン

panelTabbedコンポーネントの使用方法は、8.9.2項「panelTabbedコンポーネントの使用方法」を参照してください。

ヒント:

タブとナビゲーション階層を組み合せて使用する場合、たとえば、各タブが他のナビゲーション・アイテムのセットを含む別ページまたはリージョンである場合、ナビゲーション・パネル・コンポーネントを使用してナビゲーション・メニューを作成できます。詳細は、18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

panelAccordionおよびpanelTabbedコンポーネントのどちらの場合でも、showDetailItemコンポーネントを1つ使用して各パネルにコンテンツを配置します。たとえば、4つのペインを使用する場合、panelAccordionまたはpanelTabbedコンポーネントのそれぞれにshowDetailItemコンポーネントを4つ挿入します。showDetailItemコンポーネントを使用するには、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。showDetailItemコンポーネントのtoolbarファセットにツールバーを追加でき、そのツールバーはパネルまたはタブが開かれている場合に表示されます。図8-38に、File ExplorerアプリケーションのshowDetailItemコンポーネントで使用されているツールバーを示します。

すべてのタブを表示できない場合、panelTabbedコンポーネントでもオーバーフロー・アイコンがサポートされています。図8-39に、File Explorerアプリケーションのオーバーフロー・アイコンを示します。

図8-39 panelTabbedコンポーネントのオーバーフロー・アイコン

パフォーマンスのヒント:

panelAccordionまたはpanelTabbedコンポーネント内の子コンポーネントの数、および子コンポーネントの複雑さが、オーバーフローのパフォーマンスに影響します。可能な場合は、オーバーフローしないように、panelAccordionまたはpanelTabbedコンポーネントのサイズを設定します。

panelAccordionおよびpanelTabbedコンポーネントのどちらも拡大できるように構成できますが、現在表示されているshowDetailItem子からディメンションをかわりに取得するように構成することもできます。

panelAccordionまたはpanelTabbedコンポーネントを拡大するように構成すると、showDetailItemコンポーネントの子が1つのみである場合は、showDetailItemコンポーネントで1つの子を拡大するように構成することもできます。

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

panelAccordionコンポーネントは、ページ内(一般的にはページの異なる領域)に複数使用したり、ネストさせることができます。panelAccordionコンポーネントを追加したら、各ペインにshowDetailItemを1つ使用して、一連のshowDetailItemコンポーネントを挿入してペインを作成します。次に、各showDetailItemにコンポーネントを挿入して、パネル・コンテンツを配置します。showDetailItemコンポーネントの使用手順は、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

panelAccordionコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「パネル・アコーディオン」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。

3. ユーザーが同時に複数のパネルのコンテンツを開いて参照できるようにする場合は、discloseManyをtrueに設定します。
デフォルト値はfalseです。これは、一度に開くことのできるパネルが1つのみであることを意味します。たとえば、最初にページがロードされた際に、開いているパネルAと閉じているパネルBが1つずつあるとします。一度に開くことのできるパネルは1つのみであるため、ユーザーがパネルBを開くとパネルAが閉じます。

4. ユーザーがすべてのペインを閉じることができるようにする場合は、discloseNoneをtrueに設定します。
デフォルト値はfalseです。これは、必ず1つのパネルが開かれたままになることを意味します。

5. ユーザーがドラッグ・アンド・ドロップしてペインを再配置できるようにする場合は、「その他」セクションを開き、「並替え」をenabledに設定します。デフォルトはdisabledです。

注意:

panelAccordionにshowDetailItemコンポーネント以外のコンポーネントがある場合(手順8を参照)は、これらのコンポーネントをクライアント側のみで並べ替えることができます。したがって、新しい順序は保持されません。

6. デフォルトでは、panelAccordionコンポーネントは、使用可能なブラウザの領域を埋めるために拡大されます。子を拡大しないコンポーネントの子としてpanelAccordionコンポーネントをかわりに使用する場合は、panelAccordionコンポーネントの拡大の処理方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントを拡大するかどうかを構成します。これを行うには、「その他」セクションを開き、dimensionsFromを次のいずれかに設定します。

- children: panelAccordionコンポーネントが、現在表示されているshowDetailItemコンポーネントからディメンションを取得します。

注意:

この設定を使用している場合は、(たとえば、inlineStyleまたはstyleClass属性から)panelAccordionコンポーネントの高さを設定することはできません。そうすると、panelAccordionの高さと子コンポーネントの高さの間で競合が発生します。

同様に、showDetailItemコンポーネントでstretchChildren、flexおよびinflexibleHeight属性を設定すると、サイズを決定するのにpanelAccordionに循環参照が戻されるため、これらの設定を行うことはできません。

- parent: panelAccordionコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: panelAccordionコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてpanelAccordionコンポーネントが拡大されます。親が子を拡大しない場合、panelAccordionコンポーネントのサイズは子コンポーネントのサイズに基づきます。

注意:

panelAccordionを拡大し、またshowDetailItemでコンテンツを拡大する場合は、特定の方法でshowDetailItemを構成する必要があります。詳細は、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

7. デフォルトでは、panelTabbedコンポーネントが作成されると、すべてのshowDetailItem子コンポーネントが作成されます。子が多数の場合は、パフォーマンスを向上するために、タブが選択された場合にのみshowDetailItem子コンポーネントを作成するか、タブが最初に選択された場合にのみshowDetailItem子コンポーネントを作成し、その時点以降、作成されたままになるように、panelTabbedを構成できます。
childCreation属性を使用して、子コンポーネントが作成されるタイミングを構成します。これを行うには、「その他」セクションを開き、childCreationを次のいずれかに設定します。

- immediate: panelTabbedコンポーネントが作成されると、すべてのshowDetailItemコンポーネントが作成されます。

- lazy: showDetailItemコンポーネントは、関連付けられたタブが選択された場合にのみ作成されます。タブが選択されると、showDetailItemコンポーネントはコンポーネント・ツリーで作成されたままになります。

- lazyUncached: showDetailItemコンポーネントは、関連付けられたタブが選択された場合にのみ作成されます。別のタブが選択されると、showDetailItemコンポーネントは破棄されます。

8. デフォルトで、panelAccordionコンポーネントの子コンポーネントとしてshowDetailItemコンポーネントを使用すると、パネルが1つ追加されます。さらにペインを追加するには、panelAccordionコンポーネントにshowDetailItemコンポーネントを挿入します。必要な数だけペインを追加できます。

ヒント:

通常はアコーディオン・パネルの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、アコーディオン・パネルにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

パネルに表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。手順は、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

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

panelTabbedコンポーネントを使用してタブ付きのペインを作成する方法は、panelAccordionコンポーネントを使用したアコーディオン・ペインの作成方法に似ています。panelTabbedコンポーネントを追加した後に、一連のshowDetailItemコンポーネントを挿入して、表示するタブ付きのパネル・コンテンツを配置します。

panelTabbedコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「タブ付きパネル」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。

3. 表示領域のコンテンツの下にタブをレンダリングする場合は、positionをbelowに設定します。
デフォルトでは、値はaboveです。これは、タブが表示領域のコンテンツの上にレンダリングされることを意味します。使用できるその他の値はbothで、この場合、タブは表示領域の上と下にレンダリングされます。

4. ユーザーがタブを閉じられる(削除できる)ようにするには、tabRemovalを設定します。この属性を設定して、すべてのタブの削除、または最後のタブを除くすべてのタブの削除を許可できます。実際に削除するにはハンドラを実装し、関連するshowDetailItemコンポーネントのリスナーを構成する必要があります。これは各showDetailItemコンポーネントでオーバーライドできるため、各タブを削除できないか(閉じるアイコンは表示されません)、閉じるアイコンは無効になります。詳細は、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

5. デフォルトでは、panelTabbedコンポーネントは、使用可能なブラウザの領域を埋めるために拡大されます。子を拡大しないコンポーネントの子としてpanelTabbedコンポーネントをかわりに使用する場合は、panelTabbedコンポーネントの拡大の処理方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントを拡大するかどうかを構成します。これを行うには、「その他」セクションを開き、dimensionsFromを次のいずれかに設定します。

- disclosedChild: panelTabbedコンポーネントが、現在表示されているshowDetailItemコンポーネントからディメンションを取得します。

注意:

この設定を使用している場合は、(たとえば、inlineStyleまたはstyleClass属性から)panelTabbedコンポーネントの高さを設定することはできません。そうすると、panelTabbedの高さと子コンポーネントの高さの間で競合が発生します。

- parent: panelTabbedコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: panelTabbedコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてpanelTabbedコンポーネントが拡大されます。親が子を拡大しない場合、panelTabbedコンポーネントのサイズは子コンポーネントのサイズに基づきます。

6. panelTabbedコンポーネントの子としてshowDetailItemコンポーネントを使用すると、デフォルトでタブ付きパネルが1つ追加されます。さらにペインを追加するには、panelTabbedコンポーネントにshowDetailItemコンポーネントを挿入します。必要な数だけタブ付きのペインを追加できます。

ヒント:

通常はpanelTabbedコンポーネントの直接の子コンポーネントである子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、panelTabbedコンポーネントにもこれらのコンポーネントを直接の子コンポーネントとして使用できます。

パネルに表示するコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。showDetailItemの使用方法の詳細は、8.9.3項「panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法」を参照してください。

8.9.3 panelAccordionまたはpanelTabbedコンポーネントにコンテンツを表示するためのshowDetailItemコンポーネントの使用方法

showDetailItemコンポーネントは、panelAccordionまたはpanelTabbedコンポーネントにのみ挿入します。各showDetailItemコンポーネントは、各アコーディオン・パネルまたはタブ付きパネルに対応します。一般的に、親コンポーネントに2つ以上のshowDetailItemコンポーネントを挿入します。表示する子コンポーネントをshowDetailItemコンポーネントに挿入します。

showDetailItemコンポーネントのdisclosed属性では、対応するアコーディオン・パネルまたはタブのコンテンツを表示(開いた状態)または非表示(閉じた状態)のどちらにするかを指定します。デフォルトではdisclosed属性はfalseで、コンテンツは非表示(閉じた状態)になります。この属性がtrueに設定されていると、コンテンツは表示(開いた状態)されます。コンテンツが開いた状態と閉じた状態を相互に切り替えるためにコードを記述する必要はありません。切替えは、ADF Facesにより自動的に処理されます。

次の手順では、8.9.1項「panelAccordionコンポーネントの使用方法」および8.9.2項「panelTabbedコンポーネントの使用方法」の説明に従って、JSFページにpanelAccordionまたはpanelTabbedコンポーネントをそれぞれ追加済であると仮定しています。

showDetailItemコンポーネントを使用してアコーディオン・パネルまたはタブ付きパネルのコンテンツを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、「詳細アイテムの表示」コンポーネントをドラッグ・アンド・ドロップし、panelAccordionまたはpanelTabbedなどの親コンポーネント内に、showDetailItemコンポーネントを1つ以上挿入します。

2. プロパティ・インスペクタで、「外観」セクションを開きます。

3. textを、このパネルまたはタブに表示するラベルに設定します。

4. ラベルの前にアイコンを追加するには、iconを、使用するイメージ・ファイルのURIに設定します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

5. 拡大するように構成されたpanelAccordionコンポーネント内にshowDetailItemコンポーネントが使用されている場合は、showDetailItemを拡大してから、そのコンテンツを拡大するように構成できますが、showDetailItemコンポーネントの子コンポーネントは1つのみにする必要があります。各showDetailItemコンポーネントにflexおよびsretchChildrenを設定する必要があります。

注意:

panelAccordionを拡大しないように設定(dimensionsFromをchildrenに設定)した場合は、サイズを求めるのに循環参照がpanelAccordionに戻されるため、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により近くのコンテンツが自動的にオーバーフロー・メニューに移動されます(図8-36を参照)。また、パネルのflex値がゼロ以外の場合は、その値が、その他のペインがオーバーフロー・メニューに移動する前に、パネルが縮小される最低の高さになります。

- stretchChildren: firstに設定されている場合、単一の子コンポーネントが拡大されます。ただし、拡大できる子コンポーネントであることが必要です。詳細は、8.9.4項「ジオメトリ管理およびshowDetailItemコンポーネントについて」を参照してください。

たとえば、File Explorerアプリケーションでは、showDetailItemコンポーネントを使用してナビゲータ・パネルにコンテンツが表示されています。両方のナビゲータが開かれている場合「検索」ナビゲータにはより多くの領域が必要なため、flex属性は2に設定され、「フォルダ」ナビゲータのshowDetailItemコンポーネントにはデフォルトのflex値1が使用されています。この設定により、「検索」ナビゲータが開かれている場合は、「フォルダ」ナビゲータより大きくなります。

注意:

File Explorerアプリケーションでは、flex属性に直接値を設定するかわりに、値の決定に使用されるメソッドに解決されるEL式が使用されています。EL式を使用すると、メタデータを使用してモデル情報を指定することを後から決めた場合に、プログラムで値を変更できます。

ユーザーは実行時にパネルの高さを変更できるため、flex属性およびinflexibleHeight属性の値が変更されます。それらの値は、ユーザーのセッション中に変わらないように永続させることができます。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

フレキシブルなアコーディオン・パネル・コンテンツに関する次の追加情報に注意してください。

- ADF Facesでフレキシブルなコンテンツを有効にするには、flex値が0より大きいペイン(showDetailItemコンポーネント)が2つ以上必要です。これは、ADF Facesでは、パネル・コンテンツにどのくらいの領域を割り当てるかの決定に、2つのコンポーネントのflexの割合が使用されているためです。実行時、フレキシブルなコンテンツの表示の結果を確認するには、2つ以上のペインが開かれている必要があります。

- showDetailItemコンポーネントの子コンポーネントが1つのみでflex値がゼロ以外の場合、かつstretchChildren属性がfirstに設定されている場合、ADF Facesにより、panelAccordionコンポーネントのdiscloseMany属性の値にかかわらずその子コンポーネントが拡大されます。

- showDetailItemコンポーネントのflex値がすべて0(ゼロ)で、そのパネル・コンテンツが開かれている場合、開かれているコンテンツがinflexibleに設定されていても、最後に開かれたshowDetailItemコンポーネントのコンテンツは、flex値が1に設定されているかのようにADF Facesによって拡大されますが、これが行われるのはshowDetailItemコンポーネントの子が1つのみで、stretchChildren属性がfirstに設定されている場合のみです。最後に開かれたパネルに複数の子コンポーネントがあるか、stretchChildren属性がnoneに設定されている場合、コンテンツは拡大されません。

flex属性が設定されていても、ジオメトリ管理に関する制限事項があります。詳細は、8.9.4項「ジオメトリ管理およびshowDetailItemコンポーネントについて」を参照してください。

6. 「動作」セクションを開きます。disclosureListenerを、ユーザーがこのパネルまたはタブを選択した場合に実行するバッキングBeanのdisclosureListenerメソッドに設定します。
サーバーの表示イベントおよびイベント・リスナーの詳細は、8.8.4項「表示イベントについて」を参照してください。

7. このパネルまたはタブを無効(ユーザーがペインまたはタブを選択できない状態)にする場合は、disabledをtrueに設定します。

8. このパネルまたはタブの子コンポーネントを表示する場合は、disclosedをtrueに設定します。
disclosed属性は、デフォルトでfalseに設定されています。これは、このパネルまたはタブのコンテンツが非表示になることを意味します。

注意:

disclosedとrendered属性の違いに注意してください。rendered属性の値がfalseの場合、ユーザーはそのアコーディオン・ヘッダー・バーまたはタブ・リンク、およびその対応するコンテンツを使用できません。ただし、disclosed属性がfalseに設定されている場合は、その項目のコンテンツが現在は非表示でも、アコーディオン・ヘッダー・バーまたはタブ・リンクが表示されているため、ユーザーは表示することが可能です。

disclosed属性がtrueに設定されているshowDetailItemコンポーネントがない場合は、ADF Facesにより、最初に有効にされたshowDetailItemコンポーネントのコンテンツが自動的に表示されます(panelAccordionコンポーネントの子で、表示されないペインの設定が行われている場合を除きます)。

注意:

コンテンツを表示または非表示にすることで、ユーザーはdisclosed属性の値を変更できますが、ユーザーがカスタマイズできるようにアプリケーションが構成されていないかぎり、ユーザーがページを終了するとその値は保持されません。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

9. panelAccordionコンポーネントで使用されるshowDetailItemコンポーネントの場合は、「その他」セクションを開き、displayIndexを設定して、showDetailItemコンポーネントが表示される順序が反映されるようにします。ページのコードの順に表示する場合は、デフォルトの-1のままにします。

ヒント:

あるshowDetailItemコンポーネントのdisplayIndexの値が-1で、別のコンポーネントでは正数になっている場合、値が-1のコンポーネントは、ページのコードの表示順に、正数のコンポーネントの後に表示されます。

ヒント:

並べ替えできるようにpanelAccordion親コンポーネントが構成されている場合は、この値を実行時に変更でいます。

10. panelTabbedコンポーネントのタブを削除できるようにする場合は、「その他」セクションを開き、「削除」を次のいずれかに設定します。

- inherit: 削除できるようにpanelTabbed親コンポーネントが構成されている場合は、対応するタブを削除できます。これはデフォルト設定です。

- no: 対応するタブは削除できず、閉じるアイコンも表示されません。

- disabled: 対応するタブに無効な閉じるアイコンが表示されます。

itemListenerを、コンポーネントの実際の削除を処理するハンドラ・メソッドに解決されるEL式に設定します。

11. ツールバー・ボタンをパネル(panelAccordionのみでサポート)に追加するには、コンポーネント・パレットの「共通コンポーネント」パネルから、そのパネルを定義するshowDetailItemコンポーネントのtoolbarファセットに、toolbarを挿入します。その後、toolbarコンポーネントに、必要な数のcommandToolbarButtonコンポーネントを挿入します。toolbarファセットがshowDetailItemコンポーネントにある場合でも、ツールバーおよびボタンをレンダリングするのはpanelAccordionコンポーネントです。toolbarおよびcommandToolbarButtonの使用方法の詳細は、14.3項「ツールバーの使用方法」を参照してください。

注意:

アコーディオン・パネルが閉じている場合、ADF Facesにはツールバーおよびそのボタンは表示されません。ツールバーおよびそのボタンは、パネルが開かれている場合にのみ、パネル・ヘッダーに表示されます。

12. パネルにコンテンツを追加するには、必要な子コンポーネントを各showDetailItemコンポーネントに挿入します。

8.9.4 ジオメトリ管理およびshowDetailItemコンポーネントについて

panelAccordionまたはpanelTabbedコンポーネントは、子コンポーネントの拡大にジオメトリ管理を使用するコンポーネントに配置された場合、どちらも拡大されるように構成できます。ただし、panelAccordionコンポーネントでは、showDetailItemコンポーネントが拡大されるのは、panelAccordionコンポーネントのdiscloseMany属性がtrueに設定されている場合(つまり、フレキシブルでないコンテンツまたはフレキシブルなコンテンツを表示するために複数のペインが開かれる場合)、showDetailItemコンポーネントに含まれる子コンポーネントが1つのみの場合、およびshowDetailItemコンポーネントのstretchChildren属性がfirstに設定されている場合のみです。デフォルトでは、パネル・コンテンツは拡大されません。

次のような場合にはshowDetailItemコンポーネントが拡大されます。

- 含まれる子が1つのみの場合

- stretchChildren属性がfirstに設定されている場合

- 子に幅、高さ、境界およびパディングが設定されていない場合

- 子が拡大可能である場合

前述の項目がすべてtrueの場合、showDetailItemコンポーネントは子コンポーネントを拡大できます。次に、showDetailItemコンポーネント内で拡大可能なコンポーネントを示します。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection

- panelDashboard(拡大するように構成されている場合)

- panelGroupLayout(layout属性がscrollまたはverticalに設定されている場合のみ)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

showDetailItemコンポーネント内に配置した場合、次のコンポーネントは拡大されません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout(layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelLabelAndMessage

- panelList

- tableLayout(MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントの子として配置することはできません。そのため、showDetailItemコンポーネントの子として拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない別のコンポーネントでそのコンポーネントをラップする必要があります。

たとえば、panelListコンポーネントにコンテンツを配置し、showDetailItemコンポーネント内に表示されるようにする場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをshowDetailItemコンポーネントの子として配置し、panelListコンポーネントをそのコンポーネントに配置します。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

8.9.5 showDetailItem表示イベントについて

panelAccordionおよびpanelTabbedコンポーネント内のshowDetailItemコンポーネントでは表示イベントのキューイングがサポートされるため、サーバーおよびクライアントで検証が適切に処理されます。

一般的に、disclosed属性が設定されているコンポーネントの場合、クライアントのAdfDisclosureEventイベントのイベント・ルートは、イベントのソース・コンポーネントに設定されており、disclosed属性がtrueのパネルに対するイベントのみがサーバーに送信されます。ただし、panelTabbedまたはpanelAccordionコンポーネント内に使用されているshowDetailItemコンポーネントの場合、イベント・ルートはpanelTabbedまたはpanelAccordionコンポーネントです(つまり、イベント・ソースの親コンポーネントではなく、イベント・ソース・コンポーネントです)。このため、前に開かれたパネルの値はサーバーに送信されません。

たとえば、panelTabbedまたはpanelAccordionコンポーネント内に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つずつです。

表示イベントの詳細は、8.8.4項「表示イベントについて」を参照してください。

8.10 静的ボックスの項目の表示

panelHeaderコンポーネントは、メッセージの表示や関連するヘルプ・トピックなどのヘッダー・タイプ機能が必要な場合に使用できますが、コンテンツの表示および非表示機能を指定する必要はありません。

ページの異なるルック・アンド・フィールに遷移する必要がある場合は、decorativeBoxコンポーネントを使用できます。decorativeBoxコンポーネントは、テーマおよびスキニング・キーを使用して、その様々なファセットの枠および色を制御します。たとえば、使用しているスキンに応じて、デフォルトのテーマを使用する場合、decorativeBoxコンポーネント本体は白、枠は青で、左上隅は丸くなります。ミディアム・テーマを使用する場合、本体は中間色の青になります。テーマおよびスキンの使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

panelHeaderコンポーネントには、特定タイプのコンポーネント用のファセットや、ヘッダーからヘルプ・トピックを起動する機能があります。次に、panelHeaderコンポーネントでサポートされているファセットを示します。

- context: ヘッダーのヘッダー・テキストの横に情報を表示します。

- help: ヘルプ情報を表示します。下位互換性が必要な場合にのみ使用します。かわりに、panelHeaderコンポーネントではhelpTopicId属性を使用します。

- info: ヘッダー・テキストの下に情報を表示します。右揃えになります。

- legend: ヘルプ・テキストが存在する場合は、ヘルプ・コンテンツの左側でinfoファセットのコンテンツの下に情報が表示されます。ヘルプ・テキストが存在しない場合、legendコンテンツはヘッダーの下に直接レンダリングされます。

- toolbar: メニュー・バーの前にツールバーを表示します。

- menuBar: ツールバーの後ろにメニュー・バーを表示します。

図8-40に、panelHeaderコンポーネントの様々なファセットを示します。

図8-40 panelHeaderおよびそのファセット

タイトル行のすべてのファセットにすべてを表示する十分な領域がない場合、panelHeaderテキストは切り捨てられ、省略記号が表示されます。切り捨てられたテキストの上にマウスを置くと、図8-41に示すように、完全なテキストがツールチップに表示されます。

図8-41 切り捨てられているpanelHeaderのテキスト

コンテンツの表示に十分な領域がある場合は、図8-42に示すように、余分な領域がcontextファセットとツールバーの間に配置されます。

図8-42 ツールバーの前に追加される余分な領域

セクションの階層を表すようにpanelHeadersコンポーネントを構成できます。たとえば、図8-43に示されているように、サブヘッダーのあるメイン・ヘッダーおよびサブヘッダーのあるヘッダー・レベル1を表示できます。

図8-43 panelHeaderコンポーネントを使用したサブセクションの作成

それぞれにpanelHeaderコンポーネントをネストさせてサブセクションを作成します。panelHeaderコンポーネントをネストさせると、階層に応じてヘッダー・テキストが自動的にサイズ調整され、一番外側のpanelHeaderコンポーネントのテキストが最も大きくなります。

注意:

サイズの処理は、デフォルトでヘッダー・コンポーネントの物理包含によって決定されます。つまり、最初のヘッダー・コンポーネントは見出しレベル1としてレンダリングされます。最初のヘッダー・コンポーネントにネストされるヘッダー・コンポーネントは見出しレベル2などとしてレンダリングされます。各ヘッダー・コンポーネントの見出しレベルは、headerLevel属性を使用して手動でオーバーライドできます。

panelHeaderコンポーネントの使用方法の詳細は、8.10.1項「panelHeaderコンポーネントの使用方法」を参照してください。

decorativeBoxコンポーネントには、テーマを使用したスタイル機能が用意されています。topとcenterの2つのファセットがあります。topファセットには色なしの領域が提供され、centerファセットは実際のボックスです。topファセットの高さは、コンポーネントがtopファセットに配置されているかどうかに依存します。ファセットが設定されていると、topHeight属性を使用して、コンテンツが占めるサイズが指定されます。

centerファセットのボックスの色は、使用されているテーマとスキンによって決まります。図8-44に、デフォルトで使用可能な様々なテーマを示します。

図8-44 decorativeBoxコンポーネントで使用されるテーマ

デフォルトでは、decorativeBoxコンポーネントは、親コンポーネントを埋めるために拡大されます。decorativeボックス・コンポーネントが子コンポーネントからディメンションを継承するように構成することもできます。たとえば、図8-45は、親を埋めるために拡大するように構成されたミディアム・テーマのdecorativeBoxと、outputText子コンポーネントのみと同じサイズになるように構成されたdarkテーマのdecorativeBoxを示しています。

図8-45 decorativeBoxによる拡大の可否

スキンを使用して、decorativeBoxコンポーネントのスタイルをさらに制御できます。コンポーネントの次の領域には、スキニング・キーを定義できます。

- top-start

- top

- top-end

- start

- end

- bottom-start

- bottom

- bottom-end

スキンの詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

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

panelHeaderコンポーネントを1つ使用して特定の情報を指定することも、一連のpanelHeaderコンポーネントをネストさせてコンテンツの階層組織を作成することもできます。コンテンツを表示および非表示にできるようにする場合は、かわりにshowDetailHeaderコンポーネントを使用します。詳細は、8.8.2項「showDetailHeaderコンポーネントの使用方法」を参照してください。

panelHeaderコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、ページに「パネル・ヘッダー」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「外観」セクションを開きます。

3. textを、このパネルに表示するラベルに設定します。

4. ラベルの前にアイコンを追加するには、iconを、使用するイメージ・ファイルのURIに設定します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

5. 特定のメッセージ情報の表示にヘッダーを使用している場合は、messageTypeを次のいずれかの値に設定します。

- confirmation: 指定されたアイコン・イメージが確認アイコン(上に緑のチェックマークが表示されたメモ・ページ)に置き換えられます。

- error: 指定されたアイコン・イメージがエラー・アイコン(中にxがある赤い丸)に置き換えられます。ヘッダー・ラベルも赤に変わります。

- info: 指定されたアイコン・イメージが情報アイコン(中にIがある青い丸)に置き換えられます。

- none: デフォルト。アイコンは表示されません。

- warning: 指定されたアイコン・イメージが警告アイコン(中に感嘆符がある黄色の三角)に置き換えられます。

図8-46に、様々なメッセージ・タイプに使用されるアイコンを示します。

図8-46 メッセージ・タイプのアイコン

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

6. ヘッダーにヘルプを表示するには、HelpTopicIdにトピックIDを入力します。ヘルプ・トピックの作成および使用方法の詳細は、17.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と同じように表示されます。つまり、サイズ3、4または5のスタイルには違いがなく、すべてサイズ2と同じスタイルで表示されます。これは、カスタム・スキンを作成することで変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

9. panelHeaderコンポーネントによるジオメトリ管理の処理方法を制御するには、「その他」セクションを開き、「タイプ」を次のいずれかに設定します。ジオメトリ管理の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- flow: コンポーネントは拡大されず、子も拡大しません。panelHeaderコンポーネントの高さは、その子によってのみ決定されます。

- stretch: コンポーネントは拡大され、子コンポーネントも拡大します(拡大される子コンポーネントは1つのみです)。

- default: panelHeaderコンポーネントの親コンポーネントでジオメトリ管理を決定する場合。

10. パネルにツールバー・ボタンを追加するには、toolbarコンポーネントをtoolbarファセットに挿入します。その後、toolbarコンポーネントに、必要な数のcommandToolbarButtonコンポーネントを挿入します。toolbarおよびcommandToolbarButtonの使用方法の詳細は、14.3項「ツールバーの使用方法」を参照してください。

注意:

panelHeaderコンポーネントでは、ツールバーのオーバーフローはサポートされていません。

11. パネルにメニューを追加するには、menuBarファセットにmenuコンポーネントを挿入します。メニュー・バーへのメニュー作成の詳細は、14.2項「メニュー・バーでのメニューの使用方法」を参照してください。

ヒント:

toolbarファセットにメニューを配置することも、menuファセットにツールバー(およびツールボックス)を配置することも可能です。これらのファセットの主な違いは場所です。toolbarファセットはmenuファセットの前に配置されます。

12. 必要に応じて、その他のファセットにコンテンツを追加します。

ヒント:

ビジュアル・エディタに表示されないファセットがある場合は、次のようにします。

1. 構造ウィンドウで、panelHeaderコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ヘッダー」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

13. パネルにコンテンツを追加するには、必要な子コンポーネントをpanelHeaderコンポーネントに挿入します。

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

ページに色付き領域またはボックスを表示するには、decorativeBoxコンポーネントを使用します。このコンポーネントは、タブを表示するように構成されているnavigationPaneコンポーネントのコンテナとして一般に使用されます。詳細は、18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

decorativeBoxコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、ページに「装飾ボックス」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開き、高さの頂点をtopファセットの高さに設定します。

3. テーマを変更するには、「スタイルおよびテーマ」セクションを開き、異なるテーマを選択します。

4. デフォルトでは、decorativeBoxコンポーネントは、使用可能なブラウザの領域を埋めるために拡大されます。子を拡大しないコンポーネントの子としてdecorativeBoxコンポーネントをかわりに使用する場合は、decorativeBoxコンポーネントの拡大の処理方法を変更する必要があります。
dimensionsFrom属性を使用して、コンポーネントを拡大するかどうかを構成します。これを行うには、「その他」セクションを開き、dimensionsFromを次のいずれかに設定します。

- children: decorativeBoxコンポーネントが子からディメンションを取得します。

注意:

この設定を使用する場合は、topファセットの高さの設定にパーセントを使用することはできません。そうすると、topファセットはdecorativeBoxコンポーネントのサイズからディメンションを取得しようと試みますが、decorativeBoxコンポーネントは高さをコンテンツから取得しているため、取得できず、循環依存性が発生します。パーセンテートが使用されている場合は無視され、かわりにデフォルトの50pxが使用されます。

同様に、(たとえば、inlineStyleまたはstyleClass属性から)decorativeBoxの高さを設定することはできません。そうすると、decorativeBoxの高さと子コンポーネントの高さの間で競合が発生します。

- parent: decorativeBoxコンポーネントのサイズは、次の順序で決定されます。

- inlineStyle属性から。

- inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- 親コンテナが構成されていないか、子を拡大できない場合、サイズはスキンで決定されます。

- auto: decorativeBoxコンポーネントの親コンポーネントで子の拡大ができる場合は、親に合せてdecorativeBoxコンポーネントが拡大されます。親が子を拡大しない場合、decorativeBoxコンポーネントのサイズは子コンポーネントのサイズに基づきます。

詳細は、8.10.3項「ジオメトリ管理およびdecorativeBoxコンポーネントについて」を参照してください。

8.10.3 ジオメトリ管理およびdecorativeBoxコンポーネントについて

decorativeBoxコンポーネントは、centerファセットの子コンポーネントを拡大することができ、このコンポーネント自体も拡大できます。次のコンポーネントは、decorativeBoxコンポーネントのcenterファセット内で拡大できます。

- inputText(拡大するように構成されている場合)

- decorativeBox(拡大するように構成されている場合)

- panelAccordion(拡大するように構成されている場合)

- panelBox

- panelCollection

- panelDashboard

- panelGroupLayout(layout属性がscrollまたはverticalに設定されている場合のみ)

- panelSplitter(拡大するように構成されている場合)

- panelStretchLayout(拡大するように構成されている場合)

- panelTabbed(拡大するように構成されている場合)

- region

- table(拡大するように構成されている場合)

- tree(拡大するように構成されている場合)

- treeTable(拡大するように構成されている場合)

decorativeBoxコンポーネントのファセット内に配置した場合、次のコンポーネントは拡大できません。

- panelBorderLayout

- panelFormLayout

- panelGroupLayout(layout属性がdefaultまたはhorizontalに設定されている場合のみ)

- panelHeader

- panelLabelAndMessage

- panelList

- showDetail

- showDetailHeader

- tableLayout(MyFaces Trinidadコンポーネント)

拡大できないコンポーネントを、子コンポーネントを拡大するコンポーネントのファセットに配置することはできません。そのため、decorativeBoxコンポーネントのファセットに拡大できないコンポーネントのいずれかを配置する必要がある場合は、子コンポーネントを拡大しない遷移コンポーネントでそのコンポーネントをラップします。

たとえば、panelBoxコンポーネントにコンテンツを配置し、decorativeBoxコンポーネントのファセットに配置するように設定する場合は、layout属性がscrollに設定されているpanelGroupLayoutコンポーネントをdecorativeBoxコンポーネントのファセットに配置し、panelBoxコンポーネントをそのpanelGroupLayoutコンポーネントに配置します。詳細は、8.2.2項「拡大可能なコンポーネントへのコンポーネントのネスト」を参照してください。

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

panelListコンポーネントは、図8-47に示されているように、それぞれの隣に黒丸が付いた子コンポーネントの垂直のリストを表示するためのレイアウト要素です。rendered属性がtrueに設定されている子コンポーネント、およびvisible属性がtrueに設定されている子コンポーネントのみが、リストの順で表示の対象となります。

注意:

動的データ(JSFバインディングによって実行時に決定されたデータのリストなど)を表示する場合は、9.6項「選択コンポーネントの使用」の説明に従って、選択コンポーネントを使用します。モデル・レイヤーを変更するリストを作成する必要がある場合は、第11章「値リスト・コンポーネントの使用方法」を参照してください。

図8-47 デフォルトの黒丸が付いたpanelListコンポーネント

デフォルトで、黒丸は子コンポーネントのスタイルの設定に使用されます。四角や白丸など、使用できるスタイルは他にもあります。表示する項目のリストが非常に長い場合は、リストを列に分割することもできます。

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

項目のリストを1つ作成するには、panelListコンポーネントを1つ使用します。

panelListコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「パネル・リスト」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開き、listStyle属性を、次のような有効なCSS 2.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

例8-13に、リストのスタイルをcircleに設定するコードを示します。

例8-13 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属性の使用方法の詳細は、8.6項「フォームでのコンテンツの配置」を参照してください。panelListおよびpanelFormLayoutコンポーネントにおける縦表示でのrowsとmaxColumns属性の使用方法は同じです。

8.11.2 リスト階層の作成について

panelListコンポーネントをネストさせて、リスト階層を作成できます。図8-48に示されているように、リスト階層には外部項目と内部項目があり、外部項目に属する内部項目は外部項目の下にインデント表示されます。内部項目の各グループは、ネストした単一のpanelListコンポーネントによって作成されます。

図8-48 ネストしたpanelListコンポーネントを使用して作成された階層リスト

図8-48のようなリスト階層を作成するには、groupコンポーネントを使用して、外部項目とその内部項目の各グループを構成するコンポーネントをラップします。例8-14に、4つの内部項目を持つ外部項目が1つと、2つの内部項目を持つ別の外部項目があるリスト階層の作成方法に関するコードを示します。

例8-14 ネストした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コンポーネントの詳細は、8.12項「関連する項目のグループ化」を参照してください。

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

親コンポーネント内で類似の項目をまとめる必要がある場合は、groupまたはpanelGroupLayoutコンポーネントを使用します。groupコンポーネントは、意味的に関連する子コンポーネントを集約またはグループ化します。panelGroupLayoutコンポーネントとは異なり、groupコンポーネントでは子コンポーネントをレイアウトできません。単独で使用した場合、groupコンポーネントでは何もレンダリングされず、groupコンポーネント内の子コンポーネントのみが実行時にレンダリングされます。

関連するコンポーネントのグループ化には、任意の数のgroupコンポーネントを使用できます。たとえば、panelFormLayoutコンポーネントによって作成されたフォーム・レイアウト内のいくつかの入力フィールドをグループ化するとします。例8-15に、panelFormLayoutコンポーネント内の2セットの子コンポーネントをグループ化するサンプル・コードを示します。

例8-15 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コンポーネントを使用すると、図8-49に示すように、折り返さずに一連の子コンポーネントを縦または横に配置することも、折り返して続けて配置することもできます。layout属性の値により子コンポーネントの配置が決定されます。

図8-49 panelGroupLayoutの配置

すべての配置において、panelGroupLayoutコンポーネントのseparatorファセットを使用して、隣接する子コンポーネントの各ペアを線または空白で区切ることができます。詳細は、8.13項「空白または線を使用したコンテンツの分割」を参照してください。

横のレイアウトを使用する場合は、子コンポーネントを縦または横に並べることもできます。図8-50に示すように、上部の位置を合せて、高いコンポーネントの隣に低いコンポーネントを作成できます。

図8-50 上部の位置を合せた水平レイアウトの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コンポーネントが含まれています。検索条件が非表示で、検索結果が領域に収まらない場合は、図8-51に示すようにスクロールバーがレンダリングされます。

図8-51 panelGroupLayoutを使用してレンダリングされたスクロールバー

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

panelGroupLayoutコンポーネントは、必要なレイアウトにするためにいくつでもネストさせることができます。

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に設定すると、図8-52に示されているように、文字が配置されている架空の線に沿ってテキストの文字が並べられます。そのようなテキスト・コンポーネントでvalignをbottomに設定した場合、bottomの縦の配列ではすべての文字の一番下の部分が同じ架空の線上に配置されるため、結果は見栄えのよい外観にはなりません。

図8-52 テキストのbottomおよびbaselineの縦の位置

注意:

layoutがhorizontalではない場合、halignおよびvalign属性は無視されます。

- scroll: 縦のレイアウトになり、子コンポーネントは縦に並べられ、必要な場合には縦のスクロールバーが表示されます。

- vertical: 縦のレイアウトになり、子コンポーネントは縦に並べられます。

8.12.2 ジオメトリ管理およびpanelGroupLayoutコンポーネントについて

panelGroupLayoutコンポーネントは子コンポーネントを拡大できませんが、panelSplitterまたはpanelStretchLayoutコンポーネントの子で、layout属性がscrollまたはverticalに設定されている場合には拡大できます。

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

コンポーネント間に一定の間隔を設けるために、ページに空白を組み込むことができるため、すべてのコンポーネントが互いに前後左右に近接しているよりも、ページは乱雑に見えなくなります。spacerコンポーネントは、特にこの目的のために用意されたADF Facesコンポーネントです。

heightおよびwidth属性を使用して、縦または横、あるいはその両方の空白をページに組み込むことができます。

height: ページに組み込む縦の空白の量を決定する属性。例8-16に、縦の空白を使用して、2つの長いoutputTextコンポーネントの間に一定の間隔を設けるよう設定されたページを示します。

例8-16 縦の空白

<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>

図8-53に、ブラウザで表示した場合に、spacerコンポーネントがページ出力に及ぼす影響を示します。

図8-53 ブラウザで表示した縦の空白

width属性は、コンポーネント間に組み込む横の空白の量を決定します。例8-17に、2つのコンポーネントの間に横方向の間隔を設けるよう設定されたページのソースの一部を示します。

例8-17 横の空白

<af:outputLabel value="Your credit rating is currently:"/>
<af:spacer width="10"/>
<af:outputText value="Level 8"/>

図8-54に、ブラウザで表示した場合の、横方向の間隔調整コンポーネントの影響を示します。

図8-54 ブラウザで表示した横の空白

separatorコンポーネントを使用すると横線を作成できます。図8-55に、2つのpanelBoxコンポーネント間にseparatorコンポーネントを挿入した場合のproperties.jspxファイルの外観を示します。

図8-55 線を作成するためのseparatorコンポーネントの使用

通常、spacerおよびseparatorコンポーネントは、その他のレイアウト・コンポーネントのファセットに使用します。これにより、分割するコンポーネントに空白または線が表示されます。

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

ページには、必要な数だけspacerコンポーネントを使用できます。

spacerコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「スペーサ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。必要に応じて幅と高さを設定します。

注意:

高さが指定されていて幅が指定されていない場合、ブロック・レベルのHTML要素がレンダリングされ、その近くに新しい行が表示されます。幅が指定されている場合、指定されている高さの値に関係なく、HTML標準を厳密にサポートするユーザー・エージェントに適用可能な行の高さより低くなりません。

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

ページには、必要な数だけseparatorコンポーネントを使用できます。

separatorコンポーネントを作成および使用する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、JSFページに「セパレータ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、必要に応じてプロパティを設定します。

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

この章では、データの入力、値の選択、テキストの編集およびファイルのロードに使用される入力コンポーネントについて説明します。

この章では、次の項目について説明します。

- 9.1項「入力コンポーネントおよびフォームの概要」

- 9.2項「formの定義」

- 9.3項「inputTextコンポーネントの使用方法」

- 9.4項「数値入力コンポーネントの使用方法」

- 9.5項「カラー・チューザおよび日付チューザの使用方法」

- 9.6項「選択コンポーネントの使用方法」

- 9.7項「シャトル・コンポーネントの使用方法」

- 9.8項「richTextEditorコンポーネントの使用方法」

- 9.9項「ファイルのアップロード機能の使用方法」

9.1 入力コンポーネントおよびフォームの概要

入力コンポーネントは、様々な形式のユーザー入力を受け入れます。最も一般的な形式はテキスト、数値、日付および選択リストで、フォーム内に表示され、フォームの送信時に送信されます。入力された値や選択内容は、検証および変換され、さらに処理されます。たとえば、File Explorerアプリケーションには、ユーザーによる新しいファイルの作成が可能なフォームが含まれます。図9-1に示すように、ユーザーは入力コンポーネントを使用して、名前やサイズの入力、権限の選択、キーワードおよび説明の追加を行います。

図9-1 入力コンポーネントを使用したフォーム

テキスト、数値、日付または色の入力に使用される標準の入力コンポーネントに加え、ADF Facesには、その他の機能を持つ入力タイプ・コンポーネントも用意されています。inputFileコンポーネントを使用すると、ユーザーはロードするファイルを参照できます。

richTextEditorコンポーネントには、異なるフォント、サイズ、行揃えおよびその他の編集機能を使用した書式設定可能な、多数の行にわたるリッチ・テキスト入力が用意されています。richTextEditorコンポーネントは、コマンド・コンポーネントとともに使用でき、特定のテキストをコンポーネントに挿入することもできます。挿入テキストは事前にフォーマットできます。また、エディタのツールバーに表示されるボタンをカスタマイズできます。

選択コンポーネントを使用すると、値を入力するかわりに、または値の入力に加えて、ユーザーが項目のリストから選択できるようになります。たとえば、selectOneChoiceコンポーネントを使用すると、ユーザーはドロップダウン・リストから入力内容を選択でき、selectOneRadioコンポーネントを使用すると、ラジオ・ボタンのグループから選択できるようになります。

リストの表示には、選択コンポーネントまたは値リスト(LOV)コンポーネントを使用できます。LOVコンポーネントは、選択リストが大きい場合に使用します。LOVコンポーネントは、ListOfValueModelクラスを使用したモデル駆動型で、APIを使用してプログラムで構成されます。選択リストは、ポップアップ・ウィンドウ内に表示され、問合せパネルが含まれていることもあります。選択リストは単に値の静的リストを表示します。LOVコンポーネントの使用の詳細は、第11章「値リスト・コンポーネントの使用方法」を参照してください。

selectItemコンポーネントは別の選択コンポーネント内で使用され、そのコンポーネントの選択可能な個々の項目を表します。たとえば、selectOneRadioコンポーネントでは、各ラジオ・ボタンにselectItemコンポーネントを使用します。ラジオ・ボタンの選択内容がコーヒー、紅茶、牛乳の場合、コーヒー、紅茶、牛乳のそれぞれにselectItemコンポーネントを使用します。

フォーム・コンポーネントには、その他のコンポーネント用のコンテナがあります。formコンポーネントは、埋め込まれた入力コンポーネントからの値を送信できるリージョンを表します。formコンポーネントをネストさせることはできません。ただし、subformコンポーネントを使用して、form内で個別にコンポーネント値を送信できるサブリージョンを定義することで、さらに柔軟性を高められます。resetButtonコンポーネントを使用すると、ユーザーは、formまたはsubform内の入力値を簡単に以前の状態にリセットできるようになります。

すべての入力および選択コンポーネントは、ValueChangeEventおよびAttributeChangeEventイベントを送信します。対応するイベントに応じて機能を提供するには、valueChangeListenerおよびattributeChangeListenerメソッドを作成します。

すべての入力コンポーネント、選択コンポーネント(selectItemを除く)およびリッチ・テキスト・エディタ・コンポーネントには、changed属性があり、この属性がtrueに設定されていると、valueフィールドの変更時に変更インジケータ・アイコンが表示されます。このインジケータを使用すると、ユーザーは、どの入力値が変更されたか、ページに複数のコンポーネントがある場合に、どのコンポーネントが便利かを簡単に確認できます。デフォルトで、変更インジケータは通常コンポーネントの左側に表示されます。市区町村が入力されて郵便番号が自動的に生成されるなど、別のフィールド値の変更によりフィールドの値が自動的に変更される場合は、郵便番号フィールドにも変更インジケータが表示されます。図9-2に、チェック・ボックスおよび入力コンポーネントに表示された変更済インジケータを示します。

図9-2 2つのコンポーネントの変更済インジケータ

ヒント:

スキンを使用すると、アイコンまたはアイコンの位置を変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

入力コンポーネントの大半は、ラベルのみを表示する機能もあり、コンポーネントにマウスを置くまでは値を変更できると表示されません。ユーザーが値を変更すると、その新しい値は読取り専用として表示されます。図9-3に、アクセス時のみ編集できるように構成されているselectManyChoiceコンポーネントを示します。

図9-3 編集できないと表示される入力コンポーネント

入力コンポーネントにも、ツールチップ、エラーや検証のメッセージ、およびコンテキスト依存ヘルプを表示できます。詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

すべての入力コンポーネントには、プロパティ値を設定または取得するのに使用可能なJavaScriptクライアントAPIがあります。詳細は、ADF Faces JavaScript APIのドキュメントを参照してください。

9.2 formの定義

formは、その他のコンポーネントのコンテナとして機能するコンポーネントです。フォーム内で送信アクションが発生すると、変更された入力値が送信されます。たとえば、入力コンポーネントと選択コンポーネントで構成される入力フォーム、および送信コマンド・ボタンを作成し、すべてをform内に配置できます。ユーザーが複数の入力フィールドに値を入力して送信ボタンをクリックすると、それらの新しい入力値が送信されて処理されます。

JDeveloperでJSFページを作成すると、デフォルトで、ページにformコンポーネントが自動的に挿入されます。ページにコンポーネントを追加すると、formコンポーネント内に挿入されます。

ヒント:

ページにaf:formタグがない状態で、そのページにADF Facesコンポーネントをドラッグ・アンド・ドロップすると、JDeveloperにより、コンポーネントをformコンポーネントで囲むよう要求されます。

例9-1に、2つの入力コンポーネント、およびクリックされると両方の入力値が送信されて処理される送信ボタンを示します。

例9-1 入力コンポーネントのコンテナとしてのADF Facesのform

<af:form>
<af:panelFormLayout>
<af:inputText value="#{myBean.firstName}"
label="#{First Name}"
</af:inputText>
<af:inputText value="#{myBean.lastName}"
label="#{Last Name}"
</af:inputText>
<f:facet name="footer">
<af:commandButton text="Submit"/>
</f:facet>
</af:panelFormLayout>
</af:form>

ページに使用できるformコンポーネントは1つのみであるため、入力値を送信できる個別のリージョンを作成するには、form内にsubformを使用します。リージョンにおいて、subform内の値は、subform内のコンポーネントが値の送信を行う場合にのみ検証および処理されます。また、subform内に別のsubformをネストさせて、値を送信できるネストしたリージョンを作成することもできます。subformの詳細は、4.5項「サブフォームを使用したページでの領域の作成」を参照してください。

例9-2に、それぞれに独自の入力コンポーネントと送信ボタンを含む2つのsubformがあるformを示します。送信ボタンをクリックすると、そのsubform内の入力値のみが送信されて処理されます。

例9-2 form内のADF Facesのsubform

<af:form>
<af:subform>
<af:panelFormLayout>
<af:inputText value="#{myBean.firstName}"
</af:inputText>
<af:inputText value="#{myBean.lastName}"
</af:inputText>
<f:facet name="footer">
<af:commandButton text="Submit"/>
</f:facet>
</af:panelFormLayout>
</af:subform>
<af:subform>
<af:panelFormLayout>
<af:inputText value="#{myBean.primaryPhone}"
</af:inputText>
<af:inputText value="#{myBean.cellPhone}"
</af:inputText>
<f:facet name="footer">
<af:commandButton text="Submit"/>
</f:facet>
</af:panelFormLayout>
</af:subform>
</af:form>

基本的な送信ボタンの他に、form内にその他のコマンド・コンポーネントを追加して、そのform内の任意のフィールドで機能させることができます。ADF Facesには、resetButtonコンポーネントという特殊なコマンド・コンポーネントがあり、これをクリックすると、form内のすべての入力および選択コンポーネントがリセットされます。つまり、値の編集が可能なすべてのコンポーネントが、現在のモデルの値で更新されます。resetButtonコンポーネントでは、検証や変換でエラーがなく、サーバーへの部分的または完全な送信が成功している以前の状態に入力コンポーネントがリセットされ、この点でHTMLのリセットと異なります。たとえば、ユーザーが値Aを入力して送信ボタンをクリックし、値をAからBに変更してresetButtonコンポーネントをクリックすると、値Aがリストアされます。

9.2.1 ページへのformの追加方法

多くの場合、JDeveloperを使用してformコンポーネントを追加します。ただし、手動でのformの追加や、特定の属性値を使用したformの構成が必要な場合があります。

ページにformを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「フォーム」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。ここでは、オプションで次の内容を設定できます。

- defaultCommand: [Enter]キーが押され、form内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。

- usesUpload: formでファイルのアップロードをサポートするかどうかを指定します。ファイルのアップロードの詳細は、9.9項「ファイルのアップロード機能の使用方法」を参照してください。

- targetFrame: 新しいページを表示するかどうかを指定します。使用可能な値は、HTMLのターゲット属性の有効な値です。デフォルトは、_selfです。

9.2.2 ページへのsubformの追加方法

ページのセクションで値を個別に送信できることが必要な場合は、formコンポーネント内にsubformコンポーネントを追加する必要があります。

ページにsubformを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、formコンポーネントの子として、ページに「サブ・フォーム」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタを使用して、次の設定を行います。

- default: subformで値を送信済であると仮定するかどうかを指定します。デフォルト値falseに設定すると、その他のsubformコンポーネントが送信されていない場合にのみ、そのsubformコンポーネントは送信済とみなされます。trueに設定すると、そのsubformコンポーネントは値を送信済とみなされます。

ヒント:

subformは、その子またはファセットのいずれかによって、リクエスト値の適用フェーズよりも後のフェーズ(decode()よりも後)でイベントがキューイングされると、発行済とみなされます。ライフサイクル・フェーズの詳細は、第4章「ADF FacesによるJSFライフサイクルの使用」を参照してください。

- default Command: [Enter]キーが押され、subform内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。

9.2.3 formへのリセット・ボタンの追加方法

formまたはsubformに、resetButtonコンポーネントを追加できます。リセット・ボタンは、そのformまたはsubform内のコンポーネントでのみ機能します。

ページにリセット・ボタンを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「Reset Button」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタを使用して、次の設定を行います。

- text: ボタンのテキスト・ラベルを指定します。

- disabled: ボタンを無効にするかどうかを指定します。たとえば、ボタンを無効化する必要のある特定の状況を判断するEL式を入力できます。

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

ピッカー、スライダ、スピン・ボックスなど、入力コンポーネントには多くのバリエーションがありますが、inputTextコンポーネントは、値入力のための基本的な入力コンポーネントです。inputTextコンポーネントは、1行の入力フィールドとして定義することも、rows属性を1より大きい値に設定してテキスト領域として定義することもできます。ただし、複数行のテキスト入力を作成する場合は、9.8項「richTextEditorコンポーネントの使用方法」で説明されているように、richTextEditorコンポーネントの使用を検討します。

secret属性をtrueに設定することで、パスワードなどの入力値を非表示にできます。その他のADF Facesコンポーネントと同じように、inputTextコンポーネントではラベル、テキストおよびメッセージがサポートされています。このコンポーネントをラベルなしで表示する場合は、simple属性をtrueに設定します。図9-4に、1行のinputTextコンポーネントを示します。

図9-4 1行のinputTextコンポーネント

rows属性を使用すると、inputTextコンポーネントに複数行のテキストを表示できます。rows属性を1より大きい数に設定し、simple属性をtrueに設定すると、dimensionsFrom属性を使用して、inputTextコンポーネントがそのコンテナに合うように拡大されるように構成できます。コンポーネントが拡大される方法の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。図9-6に、複数行のinputTextコンポーネントを示します。

複数のinputTextコンポーネントを追加して、入力フォームを作成できます。図9-5に、3つのinputTextコンポーネントと「発行」コマンド・ボタンを使用した入力フォームを示します。

図9-5 inputTextコンポーネントで作成したフォーム

コマンド・コンポーネントと連携して、inputTextコンポーネントに特定のテキストを挿入するinsertTextBehaviorタグも構成できます。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoiceコンポーネントで選択したリスト項目など)を指定できます。たとえば、図9-6は、ユーザーがすでにテキストを入力したinputTextコンポーネントを示しています。

図9-6 テキストが入力済のinputTextコンポーネント

この後、ユーザーがドロップダウン・リストから追加テキストを選択し、コマンド・ボタンをクリックすると、図9-7に示すように、inputTextコンポーネントにそのテキストが表示されます。

図9-7 テキストが挿入済のinputTextコンポーネント

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

第8章「Webページ上のコンテンツの編成」で説明されている任意のレイアウト・コンポーネントに、inputTextコンポーネントを使用できます。

inputTextコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「入力テキスト」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。

- label: ラベルとして使用するテキストを指定するための値を入力します。
使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

- value: コンポーネントの値を指定します。値のELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指していて、それが値の編集が可能なコンポーネントの場合、コンポーネントは読取り専用モードでレンダリングされます。

3. 「外観」セクションを開き、次の設定を行います。

- columns: フィールドに入力可能な最大の文字数を入力し、テキスト・コントロールのサイズを指定します。

- rows: 表示される行数を入力し、テキスト・コントロールの高さを指定します。デフォルト値は1で、1行の入力フィールドを生成します。行数は、ブラウザのデフォルトのフォント・サイズに基づいて見積られます。2以上に設定する場合は、wrap属性も設定する必要があります。

- secret: 1行のテキスト・コントロールにのみ適用されるブール値を指定します。trueに設定されている場合、secret属性により、テキストの実際の値がユーザーには非表示になります。

- wrap: 複数行のテキスト・コントロールで使用されるテキストの折返しタイプを指定します。この属性は、1行のコンポーネントでは無視されます。デフォルトでは属性がsoftに設定されており、複数行のテキストは視覚的には折り返されますが、送信される値に改行は含まれません。この属性をoffに設定すると折返しは無効にされ、複数行のテキストは水平にスクロールして表示されます。hardに設定すると、行の折返しに必要な改行がテキストの値に含まれます。

- showRequired: フィールドが必須であることを視覚的に表示するかどうかを指定します。required属性をtrueに設定しても、視覚的な表示が行われることに注意してください。showRequired属性を使用するのは、別のフィールドの値が変更された場合にのみフィールドが必須になるときです。

- changed: フィールドの値が変更された場合に、青丸を表示するかどうかを指定します。これをtrueに設定する場合は、changedDesc属性も設定する必要があります。

- changedDesc: 変更されたアイコン上にマウスが置かれた場合に、ツールチップに表示するテキストを指定します。デフォルトで、テキストは「変更済」です。このテキストは、異なる値を指定することでオーバーライドできます。

- accessKey: フィールドにアクセスするために押すキーを指定します。

- labelAndAccessKey: ラベルとアクセス・キーを別々に指定するかわりに、2つを結合して、アクセス・キーがラベルの一部になるようにします。アクセス・キーとして使用する文字の前にアンパサンド(&)を付けます。
たとえば、フィールドのラベルが「Description」で、Dをアクセス・キーにする場合は、&Descriptionと入力します。

注意:

値はXMLのページ・ソースに格納されるため、アンパサンド(&)文字をエスケープする必要があります。そのため、ソース・ページでは、アンパサンドを意味する文字&amp;を使用して表されます。

- simple: ラベルを表示しない場合にtrueに設定します。

4. 「動作」セクションを開き、次の設定を行います。

- required: 値が必要かどうかを指定します。trueに設定されている場合、値を入力する必要があることをユーザーに知らせるために視覚的に表示されます。値が入力されない場合、例外が発生し、コンポーネントの検証が失敗します。

- readOnly: コントロールを、値の編集が可能なフィールドとして表示するか、出力スタイルのテキスト・コントロールとして表示するかを指定します。

- autoSubmit: 値が変更されたらコンポーネントを自動的に送信するかどうかを指定します。autoSubmit属性の使用の詳細は、4.3項「最適化されたライフサイクルの使用」を参照してください。

- autoTab: 現在のコンポーネントの最大長に達した場合に、フォーカスを次のタブ位置に自動的に移動するかどうかを指定します。

- maximumLength: テキスト・コントロールに入力できる1行当たりの最大文字数を指定します。これには、改行を表す文字も含まれます。0以下に設定されている場合、maximumLength属性は無視されます。Internet Explorerのようなブラウザでは、改行は2文字として扱われます。

- converter: コンバータ・オブジェクトを指定します。詳細は、6.3項「変換の追加」を参照してください。

- validator: EL式を使用して、バリデータ・メソッドへのメソッド参照を指定します。詳細は、6.5項「検証の追加」を参照してください。

5. 「その他」セクションを開き、次の設定を行います。

- dimensionsFrom: inputTextコンポーネントでジオメトリ管理をどのように処理するかを指定します。この属性には、次のいずれかを設定します。

- auto: inputTextコンポーネントの親コンポーネントで子の拡大ができる場合は、rows属性が1より大きい数に設定されており、simple属性がtrueに設定されているかぎり、親コンポーネントに合せてinputTextコンポーネントが拡大されます。親コンポーネントで拡大できない場合は、inputTextコンポーネントがコンテンツからディメンションを取得します。

- content: inputTextコンポーネントがコンポーネント・コンテンツからディメンションを取得します。これはデフォルト設定です。

- parent: inputTextコンポーネントがinlineStyle属性からディメンションを取得します。inlineStyleに値が存在しない場合、サイズは親コンテナによって決定されます。

- editable: コンポーネントを常に編集可能として表示するかどうかを指定します。そのようにする場合は、alwaysを選択します。ユーザーがマウスを置くまで値を読取り専用として表示する場合は、onAccessを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

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

insertTextBehaviorタグは、コマンド・コンポーネントと連携して、inputTextコンポーネントに特定のテキストを挿入します。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoiceコンポーネントで選択したリスト項目など)を指定できます。inputTextコンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてinsertTextBehaviorタグを追加します。

注意:

insertTextBehaviorタグでは、サーバー側イベントの配信が自動的に取り消され、親コマンド・コンポーネントのactionListenerまたはaction属性は無視されます。サーバー側の機能もトリガーする必要がある場合、カスタム・クライアント・リスナーを追加して、サーバー側のイベントを配信する必要があります。詳細は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

開始前

insertTextBehaviorタグを追加する前に、9.3.1項「inputTextコンポーネントの追加方法」の説明に従って、inputTextコンポーネントを作成する必要があります。clientComponent属性をtrueに設定します。

テキスト挿入動作を追加する手順:

1. テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順は、18.2.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。

2. コンポーネント・パレットの「操作」パネルから、「テキストの挿入動作」をコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。

3. テキスト挿入動作ダイアログで、次の内容を入力します。

- for: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するinputTextコンポーネントに移動して選択します。

- value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoiceコンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。例9-3に、ドロップダウン・リストの値または静的テキストの値を挿入できるinputTextコンポーネントのページ・コードを示します。

例9-3 insertTextBehaviorタグの使用

<af:inputText clientComponent="true" id="idInputText" label="String value"
value="#{demoInput.value}" rows="10" columns="60"/>
<af:selectOneChoice id="targetChoice" autoSubmit="true"
value="#{demoInput.choiceInsertText}"
label="Select text to insert">
<af:selectItem label="Some Text." value="Some Text."/>
<af:selectItem label="0123456789" value="0123456789"/>
<af:selectItem label="~!@#$%^*" value="~!@#$%^*"/>
<af:selectItem label="Two Lines" value="\\nLine 1\\nLine 2"/>
</af:selectOneChoice>
<af:commandButton text="Insert Selected Text" id="firstButton"
partialTriggers="targetChoice">
<af:insertTextBehavior for="idInputText"
value="#{demoInput.choiceInsertText}"/>
</af:commandButton>
<af:commandButton text="Insert Static Text">
<af:insertTextBehavior for="idInputText"
value="Some Static Text."/>
</commandButton>

4. デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、プロパティ・インスペクタでinsertTextBehaviorコンポーネントのtriggerType属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。

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

スライダ・コンポーネントを使用すると、スライダ上の位置が値に対応している1つまたは2つのマーカーがあるスライダを作成できます。スライダの値が表示され、一方にはマイナス・アイコンが、もう一方にはプラス・アイコンがあります。ユーザーはマーカーを選択し、スライダ上を移動させて値を選択します。図9-8(水平レイアウト)および図9-9(垂直レイアウト)に示すように、inputNumberSliderコンポーネントにはマーカーが1つあり、ユーザーはスライダから値を1つ選択できます。

図9-8 水平レイアウトのinputNumberSlider

図9-9 垂直レイアウトのinputNumberSlider

図9-10に示すように、inputRangeSliderコンポーネントにはマーカーが2つあり、ユーザーは範囲のエンド・ポイントを選択できます。

図9-10 水平レイアウトのinputRangeSlider

図9-11に示すように、inputNumberSpinboxは、数値用の入力フィールド、および入力フィールドの現在の値を増減させるための上矢印キーと下矢印キーのセットを作成する入力コンポーネントです。

図9-11 inputNumberSpinbox

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

inputNumberSliderまたはinputRangeSliderコンポーネントを追加する際には、表示される数値の範囲と増分を決定できます。

inputNumberSliderまたはinputRangeSliderコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに入力数値スライダまたは範囲入力スライダをドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて、次の属性を設定します(inputRangeSliderコンポーネントの場合は、「データ」セクションも開きます)。

- label: コンポーネントのラベルを指定します。

- minimum: 選択可能な最小値を指定します。この値は、スライダの開始値です。

- maximum: 選択可能な最大値を指定します。この値は、スライダの終了値です。

- minimumIncrement: 最小の増分値を指定します。これは、ユーザーがプラスまたはマイナスのアイコンをクリックすると適用される増分です。

- majorIncrement: 大きい方の2つの目盛り間の距離を指定します。この値では、ラベル付きの値が表示されるようにします。たとえば、図9-10のinputRangeSliderコンポーネントのmajorIncrement値は5.0です。0未満の場合、大きい方の増分値は表示されません。

- minorIncrement: 小さい方の2つの目盛り間の距離を指定します。0未満の場合、小さい方の増分値は表示されません。

- value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

3. 「外観」セクションを開き、「向き」を設定して、コンポーネントを水平または垂直レイアウトのどちらにするかを指定します。この項のその他の属性の詳細は、9.3.1項「inputTextコンポーネントの追加方法」を参照してください。

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

inputNumberSpinboxコンポーネントを使用すると、ユーザーは一連の数値をスクロールして値を選択できるようになります。

inputNumberSpinboxコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「入力数値スピンボックス」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタの「データ」セクションを開き、次の設定を行います。

- value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

- minimum: 入力フィールドで許可される最小値を指定します。

- maximum: 入力フィールドで許可される最大値を指定します。

- stepSize: スピン・ボックスが入力フィールドの数値を増減する際の増分を指定します。

3. 「外観」セクションを開き、属性を設定します。これらの属性設定の詳細は、9.3.1項「inputTextコンポーネントの追加方法」を参照してください。

4. ユーザーがマウスを置くまでスピンボックスの値を読取り専用として表示する場合は、「その他」セクションを開き、「編集可能」をonAccessに設定します。コンポーネントを常に編集可能として表示する場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

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

inputColorコンポーネントを使用すると、色のコードを入力するためのテキスト入力フィールドと、パレットから色を選択するためのボタンを作成できます。デフォルトの色のコード形式は16進の色の形式です。ただし、ColorConverterクラスを使用して書式設定をオーバーライドできます。

デフォルトで、inputColorコンポーネントにより、ユーザーがパレットから色を選択できるようにするchooseColorコンポーネントが開かれます。図9-12に、ポップアップ・ダイアログのchooseColorコンポーネントが含まれるinputColorコンポーネントを示します。

図9-12 ポップアップのchooseColorコンポーネントが含まれるinputColorコンポーネント

inputDateコンポーネントを使用すると、図9-13に示すように、日付を入力するためのテキスト入力フィールドと、ポップアップ・カレンダから日付を選択するためのボタンを作成できます。デフォルトの日付フォーマットは、現在のロケールに適切な省略の日付フォーマットです。たとえば、米語(ENU)のデフォルトの書式はmm/dd/yyです。ただし、この書式は日時コンバータを使用してオーバーライドできます(コンバータの使用方法の詳細は、6.3項「変換の追加」を参照してください)。

図9-13 inputDateコンポーネント

日時コンバータを追加して、日付と時間の両方を表示するように構成すると、ユーザーが時間を入力するための追加のコントロールのある日付ピッカーがモーダル・ダイアログとして表示されます。また、コンバータがタイムゾーンを表示するように構成されている場合、図9-14に示すように、ダイアログ内にタイムゾーン・ドロップダウン・リストが表示されます。

図9-14 日時コンバータが使用されている場合のモーダル・ダイアログ

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

inputColorコンポーネントを使用すると、ユーザーによる入力テキスト・フィールドへの値の入力や、カラー・チューザからの色の選択が可能になります。

inputColorコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「入力色」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。

- label: コンポーネントのラベルを指定します。

- compact: 図9-15に示すように、入力テキスト・フィールドを表示しない場合はtrueに設定します。

図9-15 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オブジェクトのリストであるか、16進の色の文字列であることが必要です。

- defaultColor: #000000など、16進の色のコードを使用してデフォルトの色を指定します。

4. 「外観」セクションを開き、次の属性を設定します。

- width: セルにおける標準のパレットの幅を指定します。有効な値は7、8および11で、colorDataおよびcustomColorData属性の値に対応します。

- customVisible: 「カスタム・カラー」ボタンおよびカスタム・カラー行を表示するかどうかを指定します。trueに設定すると、「カスタム・カラー」ボタンおよびカスタム・カラー行がレンダリングされます。

- defaultVisible: 「デフォルト」ボタンを表示するかどうかを指定します。trueに設定すると、「デフォルト」ボタンがレンダリングされます。「デフォルト」ボタンを使用すると、ユーザーはdefaultColor属性の値として、簡単に色のセットを選択できるようになります。

- lastUsedVisible: 「最終使用」ボタンを表示するかどうかを指定します。trueに設定すると、「最終使用」ボタンがレンダリングされ、ユーザーは前回使用した色を選択できるようになります。

5. 「動作」セクションを開き、次の属性を設定します。

- chooseId: 色の値の選択に使用できるchooseColorコンポーネントのIDを指定します。設定しない場合、inputColorコンポーネントには、chooseColorコンポーネントが使用された独自のデフォルトのポップアップ・ダイアログが使用されます。

6. ユーザーがマウスを置くまでコンポーネントの値を読取り専用として表示する場合は、「その他」セクションを開き、「編集可能」をonAccessに設定します。コンポーネントを常に編集可能として表示する場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

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

inputDateコンポーネントを使用すると、ユーザーは日付の入力または選択を実行できます。

inputDateコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「入力日」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタの「共通」セクションで、次の設定を行います。

- label: コンポーネントのラベルを指定します。

- value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

3. 「データ」セクションを開き、次の属性を設定します。

- 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オブジェクトのリストが生成されます。日付は、指定されたベース・カレンダのコンテキストに存在する必要があります。

パフォーマンスのヒント:

このバインディングには、定期的なラウンドトリップが必要です。特定の曜日(土曜日および日曜日など)のみを無効にする場合は、disableDaysOfWeek属性を使用します。

- disableDaysOfWeek: 各週に無効の状態でレンダリングする必要のある曜日を空白で区切ったリストで指定します。リストには、sun、mon、tue、wed、thu、fri、satの1つ以上の略語を含める必要があります。デフォルトでは、すべての曜日が有効です。

- disableMonths: 各年に無効の状態でレンダリングする必要のある月を空白で区切ったリストで指定します。リストには、jan、feb、mar、apr、may、jun、jul、aug、sep、oct、nov、decの1つ以上の略語を含める必要があります。デフォルトでは、すべての月が有効です。

4. 「動作」セクションを開き、chooseIdを設定します。日付値の選択に使用できるchooseDateコンポーネントのIDを指定します。設定しない場合、inputDateコンポーネントには、chooseDateコンポーネントが使用された独自のポップアップ・ダイアログが使用されます。

5. ユーザーがマウスを置くまでコンポーネントの値を読取り専用として表示する場合は、「その他」セクションを開き、「編集可能」をonAccessに設定します。コンポーネントを常に編集可能として表示する場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

9.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コンポーネントは更新されない場合があります。例9-4では、inputDateコンポーネントへのバインディング属性を使用してバッキングBeanに参照が含まれます。ユーザーが新しいタイム・ゾーンを選択すると、IDが設定され、inputDateのコンバータがコードで取得されてタイム・ゾーンがクリアされます。ページがレンダリングされると、コンバータのタイム・ゾーンのローカル値がNULLになるため、#{demoInput.preferredTimeZone}が評価され、更新されたタイム・ゾーンが取得されます。

例9-4 inputDateとタイム・ゾーンの選択リストの併用

<af:selectOneChoice label="Select a new timezone"
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);
}

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

選択コンポーネントを使用すると、ユーザーは項目のリストやグループから、単一または複数の値を選択できるようになります。ADF Facesには、単純なブール・ラジオ・ボタンから、ユーザーが複数の項目を選択できるリスト・ボックスまで、様々な選択コンポーネントがあります。選択コンポーネント内の項目のリストは、複数のselectItemコンポーネントで構成されています。

selectItemコンポーネントを除くすべての選択コンポーネントは、ValueChangeEventおよびAttributeChangeEventイベントを送信します。selectItemコンポーネントは、AttributeChangeEventイベントのみを送信します。これらのイベント用に、valueChangeListenerハンドラまたはattributeChangeListenerハンドラ(あるいはその両方)を作成する必要があります。

selectBooleanCheckboxコンポーネント値は、オブジェクトではなく常にブールに設定する必要があります。図9-16に示すように、選択された状態と未選択の状態が切り替えられます。

図9-16 selectBooleanCheckboxコンポーネント

selectBooleanRadioコンポーネントではブール選択が表示され、常にブールに設定する必要があります。selectBooleanCheckboxコンポーネントとは異なり、selectBooleanRadioコンポーネントでは、同じgroup属性を使用して、selectBooleanRadioコンポーネントをグループ化できます。

たとえば、ユーザーの年齢が10～18才かどうかを決定するブールと、19～100才かどうかを決定するブールがあるとします。図9-17に示すように、2つのselectBooleanRadioコンポーネントはページの任意の場所に配置できるため、横に並べて配置する必要はありません。同じgroup値を共有しているかぎり、ページ内での物理的な配置にかかわらず、選択は相互に排他的になります。

ヒント:

各selectBooleanRadioコンポーネントは独自のブールにバインドする必要があります。

図9-17 selectBooleanRadioコンポーネント

ユーザーが１つの値を選択できるラジオ・ボタンのリストを作成するには、図9-18に示すように、selectOneRadioコンポーネントを使用します。

図9-18 selectOneRadioコンポーネント

ユーザーが1つ以上の値を選択できるチェック・ボックスのリストを作成するには、図9-19に示すように、selectManyCheckboxコンポーネントを使用します。

図9-19 selectManyCheckboxコンポーネント

selectOneListboxコンポーネントを使用すると、図9-20に示すように、ユーザーは影付きのボックスに表示された項目のリストから値を1つ選択できるコンポーネントを作成できます。

図9-20 selectOneListboxコンポーネント

selectManyListboxコンポーネントは、ユーザーが項目リストから多くの値を選択できるコンポーネントを作成するものです。図9-21に示すように、このコンポーネントには、チェック・ボックスのリストの先頭に表示される「すべて」チェック・ボックスが含まれます。

図9-21 selectManyListboxコンポーネント

selectOneChoiceコンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから値を1つ選択できるメニュー形式のコンポーネントを作成できます。selectOneChoiceコンポーネントは、ドロップダウン・リストの項目が比較的少ない場合に使用します。

ベスト・プラクティス:

多数の項目が必要な場合は、かわりにinputComboboxListOfValuesコンポーネントを使用します。詳細は、第11章「値リスト・コンポーネントの使用方法」を参照してください。

図9-22に、selectOneChoiceコンポーネントを示します。

図9-22 selectOneChoiceコンポーネント

図9-23に示すように、selectOneChoiceコンポーネントは、コンパクト・モードで表示されるように構成できます。コンパクト・モードでは、入力フィールドが小さなアイコンに置き換えられます。

図9-23 コンパクト・モードのselectOneChoiceコンポーネント

ユーザーがアイコンをクリックすると、図9-24に示されているようにドロップダウン・リストが表示されます。

図9-24 コンパクト・モードのselectOneChoiceコンポーネントのリスト

selectManyChoiceコンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから複数の値を選択できるメニュー形式のドロップダウン・コンポーネントを作成できます。このコンポーネントは、選択項目のリストの先頭に表示される「すべて」選択項目を含めるように構成できます。図9-25に示すように、選択肢の数が15より多い場合は、スクロールバーが表示されます。

図9-25 selectManyChoiceコンポーネント

デフォルトでは、ページがレンダリングされる際にselectManyChoiceコンポーネントが構築されると、すべてのselectItem子コンポーネントが構築されます。ただし、リスト項目のアクセス方法が遅いと、パフォーマンスが妨害される場合があります。このような遅延は、ユーザーが項目を選択して、後でアクセスした際に変更しない可能性がある場合に特に問題になります。たとえば、ページに表示する内容をフィルタするのにselectManyChoiceコンポーネントを使用し、selectItem子コンポーネントの値にWebサービスからアクセスするとします。また、ページにアクセスするたびに、ユーザーがその選択を変更しない可能性があるとします。デフォルトでは、ページがレンダリングされるたびに、ユーザーが実際にそれらを表示する必要があるかに関係なく、すべてのselectItemsを構築する必要があります。かわりに、selectManyChoiceコンポーネントのcontentDelivery属性をimmediate(デフォルト)からlazyに変更できます。lazy設定では、ユーザーがドロップダウンをクリックした場合にのみselectItemコンポーネントが構築されます。

immediateおよびlazyの両方で、ユーザーが選択した際に、選択したselectItemコンポーネントの値がフィールドに表示されます。ただし、コンテンツの遅延配信が使用されると、後にアクセスした際に、選択した値がselectItemコンポーネント(これらのコンポーネントの構築が必要)ではなく、lazySelectedLabel属性から取得されます。通常、この属性は、選択した項目を表すStringsの配列を返すメソッドにバインドされます。selectItemコンポーネントは、ユーザーがドロップダウンを使用してそれらを表示または変更するまで構築されません。

selectManyChoiceコンポーネントのlazy配信メソッドの使用には制限があります。selectManyChoiceコンポーネントのコンテンツ配信および制限の詳細は、9.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性について」を参照してください。

次のコンポーネントの場合、コントロールの上にラベルを表示させるには、これらをpanelFormLayoutコンポーネント内に配置します。

- selectOneChoice

- selectOneRadio

- selectOneListbox

- selectManyChoice

- selectManyCheckbox

- selectManyListbox

次のコンポーネントでは、セキュリティ上の理由から、属性disabled、immediate、readOnly、required、requireMessageDetailおよびvalueをクライアント上のJavaScriptから設定することはできません(詳細は、3.7.1項「クライアントでのプロパティ値の設定方法」を参照してください)。

- selectOneChoice

- selectOneRadio

- selectOneListbox

- selectBooleanRadio

- selectBooleanCheckbox

- selectManyChoice

- selectManyCheckbox

- selectManyListbox

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

選択コンポーネントの追加手順は、どのコンポーネントでも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItemコンポーネントを追加して構成します。

選択コンポーネントを使用する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに選択コンポーネントをドラッグ・アンド・ドロップします。

2. selectBooleanCheckboxおよびselectBooleanRadioコンポーネント以外のすべての選択コンポーネントで、マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが開きます。ダイアログの2番目のページで、次のプロパティを設定できます。

- label: リストのラベルを入力します。

- requiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、17.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。

- validator: マネージドBeanの検証メソッドに解決されるEL式を入力します(詳細は、第6章「入力の検証および変換」を参照してください)。

- value: コンポーネントの値を指定します。valueのELバインディングが、setメソッドではなくgetメソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。

注意:

selectBooleanRadioまたはselectBooleanCheckboxコンポーネントを作成しており、value属性の値を入力する場合は、selected属性の値はvalue属性の型安全な別名のため、この値も入力することはできません。両方を使用することはできません。

- valueChangeListener: 値変更イベントを処理するマネージドBeanのリスナーに解決されるEL式を入力します。

3. プロパティ・インスペクタの「外観」セクションを開き、表9-1に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、9.3.1項「inputTextコンポーネントの追加方法」を参照してください。

表9-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. プロパティ・インスペクタの「動作」セクションを開き、表9-2に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、9.3.1項「inputTextコンポーネントの追加方法」を参照してください。

表9-2 選択コンポーネントの動作属性

コンポーネント

属性

ブール選択コンポーネントを除くすべて

valuePassThru: クライアントに値をパススルーするかどうかを指定します。valuePassThruがfalseの場合、この値およびオプションの値は、索引に変換されてからクライアントに送信されます。そのため、valuePassThruがfalseの場合、値またはオプション、あるいはその両方としてカスタム・オブジェクトを使用するときに、独自のコンバータを記述する必要はありません。クライアント側での実際の値を知る必要がある場合は、valuePassThruをtrueに設定できます。これにより、カスタム・コンバータが使用可能な場合は、カスタム・コンバータを使用して、クライアントに値が渡されます。カスタム・コンバータは、カスタム・オブジェクトを使用する場合に必要です。デフォルトは、falseです。

選択コンポーネントがADFモデル・バインディングを使用している場合、この値は無視されます。

selectBooleanRadio

group: 同じgroup値を持つその他すべてのselectBooleanRadioコンポーネントに対して相互に排他的であるグループの名前を入力します。

5. ユーザーがマウスを置くまでselectOneChoiceまたはselectManyChoiceコンポーネントの値を読取り専用として表示する場合は、「その他」セクションを開き、「編集可能」をonAccessに設定します。コンポーネントを常に編集可能として表示する場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

6. ページがレンダリングされるたびにselectManyChoiceのselectItem子コンポーネントを構築しない場合は、次のようにします。

- 選択した項目のラベルを格納し、これらのラベルを文字列の配列としても返すことができるロジックを作成します。

- 「その他」セクションを開き、contentDeliveryをlazyに設定します。

- 選択した項目の配列を返すメソッドにLazySelectedLabelをバインドします。

コンテンツの遅延配信の使用には制限があることに注意してください。selectManyChoiceコンポーネントのコンテンツ配信の詳細は、9.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性について」を参照してください。

7. ブール・コンポーネントの場合は、ブール・コンポーネントの子として、任意の数のselectItemコンポーネントをドラッグ・アンド・ドロップします。これらはリストの項目を表します(その他の選択コンポーネントの場合は、手順2のダイアログにより自動的に追加されます)。

8. selectItemコンポーネントが選択された状態で、プロパティ・インスペクタの「共通」セクションを開き、設定されていない場合はvalue属性に値を入力します。これが送信される値です。

9. 「外観」セクションを開き、設定されていない場合はlabel属性の値を入力します。これがリストに表示されるテキストです。

10. 項目が無効化された状態でリストに表示されるようにする場合は、「動作」セクションを開いて、「無効」をtrueに設定します。

9.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の値をリクエスト・スコープに格納することはできません。ポストバック時に、値属性は、クライアントから返されるものをデコードするのではなく。モデルからアクセスされます。値がリクエスト・スコープに保存されている場合、値は空になります。値はリクエスト・スコープに保存しないでください。

- ポストバック時に、コンバータはコールされません。ポストバックにコンバータを利用している場合は、コンテンツの遅延配信を使用しないでください。

- 画面がレンダリング・モードの場合、contentDelivery属性は無視されます。selectItemコンポーネントは、ページがレンダリングされると常に構築されます。

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

selectManyShuttleおよびselectOrderShuttleコンポーネントを使用すると、ユーザーが一方のリスト・ボックスからもう一方のリスト・ボックスに項目を移動するための2つのリスト・ボックスおよびボタンを作成できます。ユーザーは、先行(Available values)リスト・ボックスと後続(Selected values)リスト・ボックスの間を移動させる単一の項目または複数の項目を選択できます。どちらのコンポーネントでも、コントロールの上にラベルを表示する場合には、それらをpanelFormLayoutコンポーネント内に配置します。

図9-26に、selectManyShuttleコンポーネントを示します。

図9-26 selectManyShuttleコンポーネント

図9-27に示すように、selectOrdershuttleコンポーネントには、ユーザーが「選択した値」リスト・ボックスの値を並べ替えるために使用する上矢印および下矢印ボタンを追加で含めることができます。リストを並べ替えると、ValueChangeEventイベントが送信されます。readOnly属性をtrueに設定した場合は、並べ替える値が、後続リスト(「選択した値」)に表示される選択済の値であることを確認します。

図9-27 selectOrderShuttleコンポーネント

その他のselectManyコンポーネント同様、これらのコンポーネントのvalue属性は、含まれているselectItemコンポーネントのうちの1つの値に対応する値のリストまたは配列であることが必要です。selectItemsの1つの値がリストまたは配列にある場合、その項目は後続リストに表示されます。selectManyListboxコンポーネントはselectManyShuttleに直接変換できるため、valueによってリスト・ボックスに選択される項目が決まるのではなく、selectOrderShuttleコンポーネントの後続リストにどの項目が表示されるかが影響を受けます。

その他の選択コンポーネント同様、項目のリストまたは配列は、selectManyShuttleまたはselectOrderShuttleコンポーネントにネストしているselectItemコンポーネントで構成されています。例9-5に、ユーザーがファイル・タイプのリストから上位5つのファイル・タイプを選択できるselectOrderShuttleコンポーネントのサンプルを示します。

例9-5 selectOrderShuttleのJSFページ・コード

<af:selectOrderShuttle value="#{helpBean.topFive}"
leadingHeader="#{explorerBundle['help.availableFileTypes']}"
trailingHeader="#{explorerBundle['help.top5']}"
simple="true">
<af:selectItem label="XLS"/>
<af:selectItem label="DOC"/>
<af:selectItem label="PPT"/>
<af:selectItem label="PDF"/>
<af:selectItem label="Java"/>
<af:selectItem label="JWS"/>
<af:selectItem label="TXT"/>
<af:selectItem label="HTML"/>
<af:selectItem label="XML"/>
<af:selectItem label="JS"/>
<af:selectItem label="PNG"/>
<af:selectItem label="BMP"/>
<af:selectItem label="GIF"/>
<af:selectItem label="CSS"/>
<af:selectItem label="JPR"/>
<af:selectItem label="JSPX"/>
<f:validator validatorId="shuttle-validator"/>
</af:selectOrderShuttle>

selectOrdershuttleコンポーネントのreorderOnly属性をtrueに設定すると、移動機能が無効にされ、「選択した値」リスト・ボックスのみが表示されます。図9-28に示すように、ユーザーは、リスト・ボックス内の項目の並替えのみを実行できます。

図9-28 並替え専用モードのselectOrderShuttleコンポーネント

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

シャトル・コンポーネントの追加手順は、どちらのコンポーネントも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItemコンポーネントを追加して構成します。

selectManyShuttleまたはselectOrderShuttleコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページにシャトルを複数選択またはオーダー・シャトルを選択をドラッグ・アンド・ドロップします。

2. マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが表示されます。ダイアログの2番目のページでは、次の設定が可能です。

- label: リストのラベルを入力します。

- requiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、17.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属性に値を設定する必要があります。

9.7.2 選択イベントのクライアント・リスナーの使用方法について

項目選択のイベントに対応して処理を実行するJavaScriptコードを作成することで、ユーザーが一方のリストからもう一方のリストに項目を移動する前に、選択されたそれぞれの項目に関する情報をユーザーに提供できます。たとえば、コードで項目に関する追加の情報を取得し、ユーザーが項目を移動するかどうかの選択を支援するポップアップとして表示できます。図9-29に、selectManyShuttleコンポーネントを示します(ユーザーはMeyersを選択しており、ポップアップでこの選択に関する追加の情報が提供されています)。

図9-29 selectionListenerが含まれるselectManyShuttle

この機能は、selectManyShuttleまたはselectOrderShuttleコンポーネントにクライアント・リスナーを追加し、このイベントを処理するJavaScriptメソッドを作成して実装します。JavaScriptコードは、ユーザーがリストから項目を選択すると実行されます。イベントのクライアント・リスナーの使用方法の詳細は、3.2項「クライアント・イベントのリスニング」を参照してください。

選択イベントを処理するシャトル・コンポーネントにクライアント・リスナーを追加する方法:

1. コンポーネント・パレットの「操作」パネルから、「クライアント・リスナー」をシャトル・コンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「クライアント・リスナーの挿入」ダイアログで、「メソッド」フィールドに関数名(次の手順でこの関数を実装します)を入力し、タイプ・ドロップダウンから「propertyChange」を選択します。
たとえば、関数としてshowDetailsを入力した場合、JDeveloperにより、例9-6に太字で示されたコードが入力されます。

例9-6 選択を登録するためのclientListenerの使用

<af:selectManyShuttle value="#{demoInput.manyListValue1}"
valuePassThru="true" ...>
<af:clientListener type="propertyChange" method="showDetails"/>
<af:selectItem label="coffee" value="bean" />
...
</af:selectManyShuttle>

このコードにより、showDetails関数は、プロパティ値が変更されるたびにコールされます。

3. JavaScriptで、前の手順で入力された関数を実装します。この関数により、次の操作が実行されます。

- イベントのソースを取得して、シャトル・コンポーネントを取得します。

- クライアントJavaScript APIコールを使用して、選択した項目の情報を取得します。

例9-7では、AdfShuttleUtils.getLastSelectionChangeをコールして、最後に選択された項目の値が取得されています。

例9-7 選択の処理に使用される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
}
}
}

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

richTextEditorコンポーネントは、書式設定されたテキストを使用できる入力フィールドを提供します。ラベル、テキストおよびメッセージもサポートされています。ユーザーは、フォント名、サイズ、スタイルの変更、順序付けられたリストの作成、およびテキストの両端の調整を実行でき、その他の様々な機能も使用できます。richTextEditorコンポーネントは、HTMLソース・ファイルの編集にも使用できます。2つのコマンド・ボタンを使用して、標準の書式設定されたテキストの編集とHTMLソース・ファイルの編集を相互に切り替えられます。図9-30に、標準のリッチ・テキスト編集モードのリッチ・テキスト・エディタ・コンポーネントを示します。

図9-30 標準の編集モードのrichTextEditorコンポーネント

図9-31に、ソース・コード編集モードのエディタを示します。

図9-31 ソース編集モードの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などに保持されている事前フォーマット済テキストを指定できます。

デフォルトでは、図9-32に示すように、フォントのサイズや太さ、テキストの文字位置、表示モードなどのテキストの多くの要素をrichTextEditorコンポーネントのツールバーで変更できます。

図9-32 richTextEditorコンポーネントのツールバー

図9-33に、カスタマイズされているツールバーを示します。ツールバー・ボタンのほとんどが削除されており、カスタム・ツールバー・ボタンのあるツールバーとメニューが追加されています。

図9-33 カスタマイズされたrichTextEditorのツールバー

9.8.1 richTextEditorコンポーネントを追加する方法

richTextEditorコンポーネントを追加すると、テキストを特定の場所に挿入し、ツールバーもカスタマイズできるように構成できます。詳細は、9.8.2項「richTextEditorコンポーネントへのテキストの挿入機能の追加方法」および9.8.3項「ツールバーのカスタマイズ方法」を参照してください。

richTextEditorコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「リッチ・テキスト・エディタ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタの「共通」セクションを開き、value属性を設定します。

3. 「外観」セクションを開き、次の設定を行います。

- rows: 表示される文字の概数で編集ウィンドウの高さを指定します。

- columns: 表示される文字の概数で編集ウィンドウの幅を指定します。

- label: コンポーネントのラベルを指定します。

4. 「動作」セクションを開き、次の設定を行います。

- editMode: WYSIWYGまたはソース・モードを使用してエディタを表示するかどうかを選択します。

- contentDelivery: コンポーネントが最初にレンダリングされる際に、エディタ内のデータをフェッチするかどうかを指定します。contentDelivery属性の値がimmediateの場合、レンダリングされる際に、データがフェッチされてコンポーネントに表示されます。値がlazyに設定されている場合は、データがフェッチされて後続のリクエスト中にクライアントに送信されます。詳細は、10.1.1項「コンテンツの配信」を参照してください。

ヒント:

richTextEditorコンポーネントの幅は、全幅または100%に設定できます。ただし、これが確実に機能するのは、エディタがジオメトリ管理の親コンポーネントに配置されている場合のみです。panelFormLayoutまたはpanelGroupLayoutなどの配置レイアウト・コンテナに配置されていると、機能しない場合があります。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

9.8.2 richTextEditorコンポーネントへのテキストの挿入機能の追加方法

richTextEditorコンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてrichTextEditorInsertBehaviorタグを追加します。

開始前に

9.3.1項「inputTextコンポーネントの追加方法」の説明に従って、richTextEditorコンポーネントを作成する必要があります。clientComponent属性をtrueに設定します。

テキスト挿入動作を追加する手順:

1. テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順は、18.2.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。

2. コンポーネント・パレットの「操作」パネルから、「リッチ・テキスト・エディタの挿入動作」をコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。

3. リッチ・テキスト・エディタの挿入動作ダイアログで、次の内容を入力します。

- for: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するrichTextEditorコンポーネントに移動して選択します。

- value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoiceコンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。ユーザーに事前フォーマット済テキストを入力させる場合は、そのテキストに解決されるEL式を入力します。たとえば、例9-8は、demoInputマネージドBeanの属性の値としての事前フォーマット済テキストを示しています。

例9-8 マネージド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>";

例9-9に、テキストがrichTextEditorInsertBehaviorタグからどのように参照されるかを示します。

例9-9 richTextEditorInsertBehaviorタグの使用

<af:richTextEditor id="idRichTextEditor" label="Rich text value"
value="#{demoInput.richValue2}"/>
. . .
</af:richTextEditor>
<af:commandButton text="Insert Template Text">
<af:richTextEditorInsertBehavior for="idRichTextEditor"
value="#{demoInput.richInsertValue}"/>
</af:commandButton>

4. デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、triggerType属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。

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

作成するカスタム・ファセットに、追加するツールバーおよびツールバー・ボタンを配置します。次に、含まれている項目の表示方法および表示場所を決定するキーワードとともに、ツールバーの属性からファセットを参照します。

ツールバーをカスタマイズする手順:

1. コンポーネント・パレットのJSFページで、「コア」パネルから、追加するツールバーの各セクションのファセットをドラッグ・アンド・ドロップします。たとえば、図9-33に示されているカスタム・ボタンを追加するには、2つの<f:facet>タグを追加します。各ファセットには、ページに対する一意な名前を付けてください。

ヒント:

ADF Facesの今後のリリースと競合が生じないようにするには、すべてのファセット名をcustomToolbarで開始します。

2. コンポーネント・パレットの「ADF Faces」ページの「共通コンポーネント」パネルから、「ツールバー」を各ファセットにドラッグ・アンド・ドロップして、ツールバー・ボタンおよびその他のコンポーネントを追加し、必要に応じて構成します。ツールバーとツールバー・ボタンの詳細は、ツールバーの使用方法に関する項を参照してください。

3. richTextEditorコンポーネントを選択し、プロパティ・インスペクタの「その他」セクションで、toolboxLayout属性のドロップダウン・アイコンをクリックし、「編集」を選択して「プロパティの編集: 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コンポーネントを追加して、次の名前付きファセット(またはデフォルトのツールバーの次のキーワード)がツールバーに右揃えで表示されるようにします。

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

inputFileコンポーネントを使用すると、ユーザーにファイルのアップロード機能および更新機能を提供できます。このコンポーネントを使用すると、ユーザーはローカル・ファイルを選択して、サーバーの選択可能な場所にアップロードできます。サーバーからユーザーにファイルをダウンロードするには、18.4.1項「ファイルをダウンロードするためのコマンド・コンポーネントの使用方法」を参照してください。

inputFileコンポーネントにより、ファイルのアップロード時に標準のValueChangeEventイベントが送信され、ロード・プロセスが透過的に管理されます。inputFileコンポーネントのvalueプロパティは、ファイルのアップロード時に、org.apache.myfaces.trinidad.model.UploadedFileクラスのインスタンスに設定されます。

アップロード・プロセスを開始するには、図9-34に示すように、コマンド・ボタンなどのアクション・コンポーネントを作成します。

図9-34 inputFileコンポーネント

ファイルがアップロードされ、inputFileの値がnull以外の場合は、最初のロードが成功した後またはその値が初期値として指定された後に、「更新」ボタンを作成できます(図9-35に示されているように、このボタンは「参照」ボタンのかわりに表示されます)。これにより、inputFileコンポーネントの値を変更できます。

図9-35 更新モードのinputFileコンポーネント

readOnlyプロパティをtrueに設定すると、特定のファイルのみをロードできるようにコンポーネントを指定することもできます。図9-36に示すように、このモードでは、指定されたファイルのみをロードできます。

図9-36 読取り専用モードのinputFileコンポーネント

セキュリティ上の理由から、次の属性をクライアントから設定することはできません。

- disabled(unsecureプロパティが設定されている場合)。詳細は、3.7.2項「無効なプロパティを保護しない方法」を参照してください。

- immediate

- readOnly

- requiredMessageDetail

- value

inputFileコンポーネントは、h:formタグまたはaf:formタグのいずれかに配置できますが、いずれの場合も、ファイルのアップロードをサポートできるようにformタグを設定する必要があります。JSFの基本的なHTML h:formを使用する場合は、enctypeをmultipart/form-dataに設定します。これにより、リクエストがマルチパート・リクエストになり、サーバーへのファイルのアップロードがサポートされます。ADF Facesのaf:formタグを使用している場合は、usesUploadをtrueに設定することにより、enctypeをmultipart/form-dataに設定するのと同じ機能が実行され、ファイルのアップロードがサポートされます。

リッチ・クライアント・フレームワークでは、ファイルの一般的なアップロードが実行されます。アップロード後にファイルを処理(たとえば、xmlファイル、pdfファイルなどの処理)するには、actionListenerまたはアクション・メソッドを作成する必要があります。

inputFileコンポーネントのvalueは、org.apache.myfaces.trinidad.model.UploadedFileインタフェースのインスタンスです。このAPIを使用すると、ファイル名、MIMEタイプ、サイズだけでなく、ファイルの実際のバイト・ストリームを取得できます。

注意:

APIを使用して、ファイルのアップロード元に関するパス情報をクライアントから取得することはできません。

アップロードされたファイルは、ファイルとしてファイル・システムだけでなく、メモリーにも格納できますが、この違いがAPIよって表面化されることはありません。フィルタを使用すると、リクエストの完了後、確実にUploadedFileコンテンツがクリーン・アップされます。このため、通常はリクエスト全体でUploadedFileオブジェクトをキャッシュすることはできません。ファイルを保持する必要がある場合は、リクエストが完了する前にファイルを永続記憶域にコピーする必要があります。

たとえば、例9-10に示すように、ファイルを保存するかわりに、マネージドBeanをValueChangeEventイベントへのレスポンスとして使用し、ファイルのアップロードが成功したという内容のメッセージを追加します。

例9-10 アップロード・メッセージを表示するためのvalueChangeListenerの使用

JSF Page Code ----->
<af:form usesUpload="true">
<af:inputFile label="Upload:"
valueChangeListener="#{managedBean.fileUploaded}"/>
<af:commandButton text="Begin"/>
</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()
}
}
}

また、例9-11に示すように、値をマネージドBeanに直接バインドすることでアップロードを処理できます。

例9-11 マネージドBeanへの値のバインド

JSF Page Code ---->
<af:form usesUpload="true">
<af:inputFile label="Upload:" value="#{managedBean.file}"/>
<af:commandButton text="Begin" action="#{managedBean.doUpload}"/>
</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;

}

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

Javaクラスは、inputFileコンポーネントにバインドする必要があります。このクラスにより、アップロードしたファイルの値が含まれます。

inputFileコンポーネントを追加する手順:

1. 入力ファイルの値を保持するJavaクラスを作成します。org.apache.myfaces.trinidad.model.UploadedFileインタフェースのインスタンスであることが必要です。

2. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「入力ファイル」をドラッグ・アンド・ドロップします。

3. valueを手順1で作成したクラスに設定します。

4. ユーザーがマウスを置くまでコンポーネントの値を読取り専用として表示する場合は、「その他」セクションを開き、「編集可能」をonAccessに設定します。コンポーネントを常に編集可能として表示する場合は、alwaysを選択します。値を祖先コンポーネントから継承する場合は、inheritを選択します。

注意:

inheritを選択し、editable値を定義する祖先コンポーネントがない場合は、値alwaysが使用されます。

5. コンポーネント・パレットから、ページにコマンド・コンポーネントをドラッグ・アンド・ドロップします。これは、アップロード・プロセスの開始に使用されます。

6. コマンド・コンポーネントが選択された状態で、actionListener属性を、アップロード後にファイルを処理するリスナーに設定します。

9.9.2 一時的なファイルの格納について

ADF Facesではアップロードされるファイルが(ディスクまたはメモリーに)一時的に格納されるため、アップロード・ファイルでハード・ドライブやメモリーを一杯にしようとするDoS攻撃を未然に防ぐため、デフォルトでは、許容される着信アップロード・リクエストのサイズが制限されています。デフォルトでは、1つのリクエストで最初の100KBがメモリーに格納されます。これが一杯になると、ディスク領域が使用されます。この場合も、デフォルトでは、すべてのファイルに対し、1つのリクエストで2,000KBのディスク領域に制限されます。これらの制限を超えると、フィルタによりEOFExceptionがスローされます。

デフォルトで、ファイルはjava.io.File.createTempFile()が使用する一時ディレクトリに格納され、通常はシステム・プロパティjava.io.tmpdirによって定義されます。一部のアプリケーションには明らかに不十分であるため、例9-12に示すように、3つのサーブレット・コンテキスト初期化パラメータを使用して、これらの値を構成できます。

例9-12 ファイルのアップロード・サイズおよびディレクトリを定義するパラメータ

<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>
<!-- 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クラスを置き換えると、例9-12にリストされているパラメータは無関係になり、デフォルトのUploadedFileProcessorクラスによってのみ処理されます。

<uploaded-file-processor>要素は、oracle.adf.view.rich.webapp.UploadedFileProcessorインタフェースを実装するクラスの名前である必要があります。このAPIにより、個々のアップロード・ファイルが着信リクエストから取得される際に処理され、そのコンテンツを残りのリクエストで使用できるようになります。大部分のアプリケーションは、デフォルトのUploadedFileProcessorクラスで十分ですが、大規模ファイルのアップロードをサポートする必要のあるアプリケーションでは、リクエスト中にADF Facesで一時記憶域を処理するかわりに、ファイルをただちに最終的な宛先に格納することでパフォーマンスを向上させます。

10 表およびツリーの使用

この章では、ADF Facesの表、ツリーおよびツリー表コンポーネントを使用して表およびツリーを表示する方法を説明します。アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表およびツリーを作成できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFによるデータバインドされた表の作成」および「マスター/ディテール・データの表示」の章を参照してください。

この章では、次の項目について説明します。

- 10.1項「表、ツリーおよびツリー表の概要」

- 10.2項「表へのデータの表示」

- 10.3項「表への非表示機能の追加」

- 10.4項「表でのフィルタ処理の有効化」

- 10.5項「ツリーへのデータの表示」

- 10.6項「ツリー表へのデータの表示」

- 10.7項「行を値として渡す」

- 10.8項「表メニュー、ツールバーおよびステータス・バーの表示」

- 10.9項「表、ツリーまたはツリー表からのデータのエクスポート」

- 10.10項「スタンプ設定を使用するコンポーネントからクライアント上の選択された値へのアクセス」

10.1 表、ツリーおよびツリー表の概要

構造化データは、ADF Facesの表コンポーネントを使用して、行と列で構成される表として表示できます。階層データは、ADF Facesのツリー・コンポーネントを使用してツリー構造として表示することも、ADF Facesのツリー表コンポーネントを使用して表形式で表示することもできます。表示される各レコード用に子コンポーネントを含め、それらのコンポーネントを個々のレコードにバインドするかわりに、表、ツリーおよびツリー表コンポーネントが完全なコレクションにバインドされ、各レコードの値にスタンプを設定することにより、1つのコンポーネント(outputTextコンポーネントなど)が繰り返しレンダリングされます。たとえば、表に子の列コンポーネントが2つ含まれるとします。各列には、出力コンポーネントを使用して行の単一の属性値が表示され、4つのレコードが表示されます。データを表示するために、2つの出力コンポーネントの4セットをバインドするかわりに、表自体が4つすべてのレコードのコレクションにバインドされ、1セットの出力コンポーネントが単純に4回スタンプ設定されます。各行にスタンプが設定されると、現在行のデータが表のvar属性にコピーされ、出力コンポーネントが行の正しい値を取得できるようになります。特に、クライアント・コンポーネントでスタンプ設定がどのように機能するかの詳細は、10.1.5項「クライアントの表、ツリーおよびツリー表コンポーネントへのアクセス」を参照してください。

例10-1に、var属性の値がrowである表のJSFコードを示します。値が変数の特定のプロパティにバインドされているため、列の各outputTextコンポーネントにより行のデータが表示されます。

例10-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>

表コンポーネントは単純な表データを表示します。表の各行には、データベースの1行など、コレクションのオブジェクトが1つ表示されます。列コンポーネントは、各オブジェクトの属性の値を表示します。

たとえば、図10-1に示すように、File Explorerアプリケーションの表タブでは、選択されたディレクトリのコンテンツの表示に表が使用されています。表のvalue属性は、File ExplorerデモのtableContentViewマネージドBeanのcontentTableプロパティにバインドされています。

図10-1 File Explorerアプリケーションの表コンポーネント

表コンポーネントは、列のソート、1行以上の選択、選択した行でのアプリケーション定義のアクションの実行など、エンド・ユーザーに様々な機能を提供します。また、グリッド線やバンディング、行ヘッダーと列ヘッダー、列のグループにまたがる列ヘッダー、およびセル内で折り返される値の表示など、多様な表示機能も用意されています。

File Explorerアプリケーションのディレクトリなどの階層データ(親子関係のあるデータ)は、ツリー・コンポーネントを使用して展開可能なツリーとして表示できます。項目は、データの親子の構造をミラー化するノードとして表示されます。トップレベルの各ノードを開いて子ノードを表示し、それを開いて、その子ノードを表示することもできます。開かれた各ノードを閉じて、子ノードを非表示にできます。図10-2に、ツリー・コンポーネントを使用して表示されているFile Explorerアプリケーションのファイル・ディレクトリを示します。

図10-2 File Explorerアプリケーションのツリー・コンポーネント

ツリー表コンポーネントを使用して、階層データも表示できます。ツリー表でも、展開および縮小可能な親子のノードを表示できますが、これは表形式で、ページにノードの属性値がデータの列として表示されます。たとえば、表コンポーネントを使用してディレクトリのコンテンツを表示するだけでなく、File Explorerアプリケーションには、図10-3に示すように、ツリー表コンポーネントを使用してコンテンツを表示する別のタブもあります。

図10-3 File Explorerアプリケーションのツリー表

ツリー・コンポーネント同様、ツリー表コンポーネントも、項目間の親子関係を表示できます。また、表コンポーネントと同じように、ツリー表コンポーネントでも列の項目の属性値を表示できます。ツリー表コンポーネントでも、表コンポーネントで使用可能なほとんどの機能を使用できます。

表、ツリーおよびツリー表をpanelCollectionコンポーネントで囲むことにより、ツールバーおよびステータス・バーを追加できます。上部のパネルには、メニューとメニュー・オプション、ツールバーとツールバー・ボタン、およびステータス・バーなど、メニュー・タイプのコンポーネントを保持するツールバーのみでなく、標準のメニュー・バーも含まれます。デフォルトで追加されているボタンおよびメニューもあります。たとえば、表、ツリーまたはツリー表をpanelCollectionコンポーネントで囲むと、表示メニューを含むツールバーが追加されます。このメニューには、表、ツリーまたはツリー表コンポーネントに固有のメニュー項目が含まれます。

図10-4に、panelCollectionコンポーネントを使用して作成されたツールバー、メニューおよびツールバー・ボタンのあるFile Explorerアプリケーションのツリー表を示します。

図10-4 パネル・コレクションを使用したTreeTable

10.1.1 コンテンツの配信

表、ツリーおよびツリー表コンポーネントは仮想化されており、サーバーのコンポーネントに存在するすべての行がクライアントに配信されて表示されるわけではありません。表、ツリーおよびツリー表を構成して、データ・ソースから一度に一定数の行をフェッチします。レンダリング時にすぐにデータをコンポーネントに配信したり、利用可能な場合は、コンポーネントのシェルがレンダリングされた後に遅延フェッチできます(コンポーネントでは、利用可能な場合はデフォルトでデータがフェッチされます)。

すぐに配信する場合は、最初のリクエスト時にデータがフェッチされます。遅延配信では、ページに表またはツリー・コンポーネントが1つ以上含まれる場合、ページで最初に標準のライフサイクルが実行されます。ただし、最初のリクエスト時にデータがフェッチされるのではなく、特別な個別の部分ページ・レンダリング(PPR)リクエストが実行され、表のフェッチ・サイズの値として設定された行数が戻されます。ページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみがコンポーネントに対して実行され、対応するデータのフェッチおよび表示が可能になります。ユーザーのアクションにより後続のデータ・フェッチが実行される場合(別の行セットのために表をスクロールするなど)、別のPPRリクエストが実行されます。

コンテンツ配信が可能な場合に配信されるように構成した場合、フレームワークは最初のリクエスト時にデータ可能性をチェックし、利用可能な場合は、データを表に送信します。利用できない場合、データは遅延配信でロードされるため、別のPPRリクエスト時にロードされます。

パフォーマンスのヒント:

遅延の程度が高い遅いデータベース接続や、Webサービスなどのデータベース以外のデータ・ソースからのデータのフェッチなど、データ・フェッチで高コスト(遅い)の動作が予想される場合は、遅延配信を使用する必要があります。ページに表、ツリーまたはツリー表以外のコンポーネントが複数含まれる場合も、遅延配信を使用する必要があります。遅延配信を使用すると、データが使用可能になる前に、初期ページのレイアウト・コンポーネントおよびその他のコンポーネントが最初にレンダリングされます。

ページのコンテキストが表、ツリーまたはツリー表のみの場合や、コンポーネントに大規模なデータ・セットが戻される予定がない場合は、即時配信を使用する必要があります。この場合、遅延配信を使用するよりレスポンス時間が早くなりますが(または、単に早いと感じられる場合もあります)、これは、2番目のリクエストがサーバーに送信されないためで、ユーザーのレスポンス時間が早くなり、サーバーのCPU使用率も向上します。ただし、フェッチ・ブロックとして構成された数の行のみが最初に戻されることに注意してください。遅延配信同様、ユーザーのアクションにより後続のデータ・フェッチが実行される場合は、次の行セットが配信されます。

最初のレンダリング時にデータが利用できる場合はすぐに使用し、データが最初に利用できない場合は遅延にフォールバックするなど、可能な場合は配信でさらなる柔軟な操作が可能です。

クライアントに表示されるのは、ブラウザに表示される際にページに収まる行数のみです。ユーザーがコンポーネントを垂直にスクロールすると、行がさらにフェッチされます。コンポーネントを埋めるために1回でクライアントからサーバーにリクエストされる行数は、fetchSize属性により決定されます。デフォルト値は25です。そのため、表の高さが低ければ、フェッチ・サイズ25はコンポーネントを埋めるのに十分です。ただし、コンポーネントの高さが高い場合、サーバーからのデータのリクエストは複数回になります。そのため、fetchSize属性は大きな数に設定しておく必要があります。たとえば、表の高さが600ピクセルで、各行の高さが18ピクセルの場合、表を埋めるのに少なくとも45行必要です。fetchSizeが25の場合、表を埋めるために、表はサーバーに対してリクエストを2回実行する必要があります。この例では、フェッチ・サイズを50に設定します。

ただし、フェッチ・サイズを大きくしすぎると、サーバーとクライアントの両方に影響を与えます。サーバーでは、データ・ソースから必要以上に行がフェッチされ、時間とメモリー使用量が増加します。クライアント側では、それらの行の処理とコンポーネントへのアタッチに時間がかかります。

displayRow属性を使用して、最初に表示されるデータのセットを構成することもできます。デフォルトで、データ・ソースの最初のレコードが一番上の行またはノードに表示され、後続のレコードはそれより下の行またはノードに表示されます。また、ソースの最後のレコードを最初に表示するように、コンポーネントを構成することもできます。この場合、最後のレコードはコンポーネントの下の行またはノードに表示され、ユーザーは上にスクロールして先行するレコードを表示できます。また、選択した行を表示するように、コンポーネントを構成することも可能です。これは、ユーザーが表にナビゲートし、複数のパラメータに基づいて、特定の行がプログラムで選択される場合に便利です。選択された行を表示するように構成した場合、その行は表の先頭に表示され、ユーザーは上または下にスクロールして他の行を表示できます。

10.1.2 行の選択

rowSelection属性を使用して、表、ツリーおよびツリー表で、行なし、単一行または複数行のいずれかになるように選択を構成できます。この設定により、選択された行でロジックを実行できます。たとえば、ユーザーが表の行またはツリーのノードを選択して、選択された行のデータが表示される別のページにナビゲートするコマンド・ボタンをクリックし、その値を編集できるようにするとします。

表、ツリーまたはツリー表の選択した行(またはノード)が変更されると、コンポーネントにより選択イベントが起動されます。このイベントにより、選択解除された行や選択された行が報告されます。コンポーネントにより選択が宣言的に処理される際、選択された行でロジックを実行する必要がある場合は、それらの行にアクセスしてロジックを実行するコードを実装する必要があります。これは、マネージドBeanの選択リスナー・メソッドで実行できます。詳細は、10.2.8項「表の選択された行でのアクションの実行について」を参照してください。

注意:

複数の選択を実行できるようにコンポーネントを構成した場合、ユーザーが行を1つ選択し、[Shift]キーを押して別の行を選択すると、間にあるすべての行が選択されます。この選択は、選択が複数のデータ・フェッチ・ブロックにまたがる場合でも保持されます。同様に、[Ctrl]キーを使用して、隣接していない行を選択することもできます。

たとえば、表が一度に25行のみフェッチするように構成されている場合に、ユーザーが100行選択すると、フレームワークにより選択が追跡されます。

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

表、ツリーまたはツリー表の実際のデータの表示に使用するコンポーネントを選択できます。たとえば、データを読取り専用にする場合は、データの表示にoutputTextコンポーネントを使用します。反対に、データを編集できるようにする場合にはinputTextコンポーネントを使用し、リストから選択する場合にはSelectOneコンポーネントを1つ使用します。これらのコンポーネントはすべて、列コンポーネントの子として配置されるか(表およびツリー表の場合)、nodeStampファセットに配置されます(ツリーの場合)。

値の編集が可能なコンポーネントを使用してデータを表示する場合、表、ツリーまたはツリー表で、すべての行を編集可能として一度に表示するか、現在アクティブな行以外をすべて読取り専用として表示するかを、editingMode属性を使用して選択できます。たとえば、図10-5に、行をすべて編集できる表を示します。ページは、ページに追加されたコンポーネント(inputText、inputDateおよびinputComboBoxListOfValuesコンポーネントなど)を使用してレンダリングされます。

図10-5 すべての行を編集できる表

図10-6に、同じ表(データの表示にinputText、inputDateおよびinputComboBoxListOfValuesコンポーネントを使用)を示しますが、アクティブな行のみに編集可能なコンポーネントを表示するように構成されています。ユーザーは、別の行をクリックして編集可能にできます(一度に編集可能にできるのは1つの行のみ)。ページを作成するために図10-5と同じ入力コンポーネントが使用されていても、編集されていない行のデータの表示に、outputTextコンポーネントが使用されていることに注意してください。これらのコンポーネントが実際にレンダリングされるのは、アクティブな行のみです。

図10-6 表で一度に編集できるのは1行のみ

現在アクティブな行は、表のactiveRowKey属性で決定されます。デフォルトでは、この属性の値は表で最初に表示される行です。表(またはツリーやツリー表)がリフレッシュされると、そのコンポーネントがスクロールされ、アクティブな行が表示されます(まだ表示されていない場合)。ユーザーが行をクリックしてその内容を編集すると、その行はアクティブな行になります。

編集できる行(またはノード)を1つのみにする場合、ユーザーがある行(またはノード)から次の行へ移動し、一度に1行のデータを送信(および検証)すると、表(またはツリーやツリー表)ではPPRが実行されます。すべての行を編集できるようにする場合、現在表示されている行またはノードを超えてスクロールするなど、PPRが実行されるイベントが発生するとデータが送信されます。

注意:

列には、編集可能なコンポーネントを複数使用しないでください。

編集可能なコンポーネントがすべて、クリックして編集するモードで表示されるわけではありません。たとえば、HTMLの入力要素を複数行表示するコンポーネントがこれに当たります。次のコンポーネントが含まれます。

- SelectManyCheckbox

- SelectManyListBox

- SelectOneListBox

- SelectOneRadio

- SelectManyShuttle

パフォーマンスのヒント:

レンダリングおよびポストバック中のパフォーマンスを向上させるには、表での編集を1行のみに構成する必要があります。

一度に編集できる行を1行のみにすると、出力コンポーネントでは生成されるHTMLが入力コンポーネントよりも少ないため、ページがより早く表示されます。また、読取り専用行に対してはクライアント・コンポーネントが作成されません。ユーザーがある行から次の行へ移動すると、表(またはツリーやツリー表)でPPRが実行されるため、その行のデータのみが送信され、その結果、すべてのセルの編集が可能で、表内のすべての行の全データが一度に送信される表よりパフォーマンスが高くなります。編集できる行を1行のみにすると、単一の行のデータのみが検証用に送信されるため、より直感的な検証も可能になり、その行のエラーのみが表示されます。

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

表、ツリーまたはツリー表は、ユーザーのアクションに基づいてポップアップ・ダイアログが表示されるように構成できます。たとえば、ユーザーがセルまたはノード上にマウスを置いた場合に、選択された行の一部のデータが表示されるようにポップアップ・ダイアログを構成できます。ユーザーが表やツリー表の行、またはツリーのノードを右クリックした場合のために、ポップアップ・メニューを作成することも可能です。また、表やツリー表では、ユーザーが特定の行ではなく、表の任意の場所を右クリックした場合のために、ポップアップ・メニューを作成できます。

すべての表、ツリーおよびツリー表には、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ファセットが含まれます。メニューが含まれるポップアップをこのファセットに追加すると、ユーザーが特定の行ではなく、表をクリックした場合に表示されます。

ポップアップ・メニューの作成の詳細は、13.2項「ポップアップ要素の宣言的作成」を参照してください。

10.1.5 クライアントの表、ツリーおよびツリー表コンポーネントへのアクセス

ADF Facesでは、表、ツリーまたはツリー表のコンテンツはサーバーでレンダリングされます。次のような場合には、クライアントがサーバー上のそのコンテンツにアクセスする必要があります。

- クライアント側のアプリケーション・ロジックが、行固有のコンポーネントの状態を読み取る必要がある場合。たとえば、行の選択の変更に応じて、ページ内のその他のコンポーネント(通常はメニュー項目やツールバー・ボタン)の無効化や表示の状態をアプリケーションで更新する必要がある場合です。このロジックは、スタンプ設定されたinputHiddenコンポーネントを使用してクライアントに送信される、行固有のメタデータに依存している場合があります。これを有効化するために、アプリケーションでは、スタンプ設定されたコンポーネントから行固有の属性値を取得できる必要があります。

- クライアント側のアプリケーション・ロジックが、行固有のコンポーネントの状態を変更する必要がある場合。たとえば、表の行にあるスタンプ設定されたコマンド・リンクをクリックすると、同じ行のその他のコンポーネントの状態が更新される場合です。

- イベント処理動作を実装するために、ピアがコンポーネント・インスタンスにアクセスする必要がある場合(ピアの詳細は、3.1項「ADF Facesアーキテクチャの使用の概要」を参照してください)。たとえば、マウスのクリックに対応して、クライアント側のアクション・イベントを配信するには、AdfDhtmlCommandLinkPeerクラスが、イベント・ソースとして機能するコンポーネント・インスタンスを参照する必要があります。コンポーネントにも関連する状態が保持され、これには、disabledまたはpartialSubmitなど、イベント配信動作を制御する属性のみでなく、クライアント・リスナーも含まれます。

リッチ・クライアント・フレームワーク(RCF)では、クライアント側でELがサポートされないのみでなく、クライアントへの表モデル全体の送信もサポートされていないため、クライアント側のコードは、値にアクセスするようスタンプ設定されているコンポーネントに依存できません。各行で同じコンポーネント・インスタンスを再利用するかわりに、各行に新しいJavaScriptクライアント・コンポーネントが作成されます(どの行にもコンポーネントが1つ作成される必要があると仮定しています)。

そのため、クライアント上の行固有のデータにアクセスするには、それ自体がスタンプ設定されたコンポーネントを使用して値にアクセスする必要があります。クライアント側のデータ・モデルを使用せずにこれを実現するには、クライアント側の選択変更リスナーを使用します。詳細な手順は、10.10項「スタンプ設定を使用するコンポーネントからクライアント上の選択された値へのアクセス」を参照してください。

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

デフォルトでは、子を拡大するコンポーネント(panelStretchLayout内部のpanelCollectionコンポーネントなど)に表、ツリーおよびツリー表を配置すると、表、ツリーおよびツリー表が既存の領域全体に合せて拡大されます。ただし、列を表全体に拡大するには、columnStretching属性を使用して、特定の列が未使用の領域全体に拡大されるように指定する必要があります。そうしないと、表は行の数に応じて垂直に拡大されます。図10-7に示すように、列は拡大されません。

図10-7 列以外が拡大される表

子を拡大しないコンポーネントに配置すると(たとえば、panelGroupLayout内部のpanelCollectionコンポーネントでverticalに設定など)、図10-8に示すように、デフォルトで表の幅が300pxに設定されます。

図10-8 拡大されない表

子を拡大しないコンポーネントに表を配置する場合、autoHeightRows属性を使用すると、指定した行数を超えないように表の高さを抑えることができます。この属性を正の整数に設定すると、表の高さは設定した行数で決定されます。この数値がfetchSize属性より大きいと、fetchSize属性の行数のみが返されます。autoHeightRowsを-1(デフォルト)に設定すると、自動サイズ設定を無効にできます。

自動サイズ設定が役立つのは、子を拡大するコンポーネントと拡大しないコンポーネントの両方で同じ表を使用する場合です。たとえば、12行が表示可能な6列の表があるとします。子を拡大するコンポーネントで使用する場合は、表を利用可能な領域全体に拡大します。その表を子を拡大しないコンポーネントで使用する場合は、表の高さを修正できるようにします。ただし、表の高さを設定すると、他のコンポーネントに配置した場合に、その表は拡大されません。この問題を解決するには、autoHeightRows表は行の数に応属性を設定します(拡大するコンポーネントでは無視され、拡大しないコンポーネントでは適用されます)。

10.2 表へのデータの表示

表コンポーネントでは、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 Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』の「ADFによるデータバインドされた表の作成」の章を参照してください。

tableコンポーネントの直接的な子は、columnコンポーネントである必要があります。表示されるそれぞれの列コンポーネントは、表の個別の列として表示されます。列コンポーネントには、コンテンツやイメージの表示、またはその他の機能の提供に使用されるコンポーネントが含まれます。列コンポーネントで使用可能な機能の詳細は、10.2.1項「列および列データ」を参照してください。

各列の子コンポーネントは、その列の各行のデータを表示します。列では、子コンポーネントは行ごとには作成されませんが、表では各行のレンダリングにスタンプ設定機能が使用されます。各子には、行ごとに一度スタンプが設定され、これがすべての行に対して繰り返されます。各行にスタンプが設定されると、現在行のデータが、EL式を使用して特定可能なプロパティにコピーされます。このプロパティに使用する名前を、表のvarプロパティを使用して指定します。表のレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

このスタンプ設定動作のため、一部のコンポーネントが列内で機能しない場合があります。入力および出力コンポーネントなど、大部分のコンポーネントは問題なく機能します。セル内に複数のコンポーネントを使用する必要がある場合は、それらをpanelGroupLayoutコンポーネントでラップします。表内の表など、それ自体がスタンプ機能をサポートしているコンポーネントはサポートされていません。実行時に値が動的に決定されるコンポーネントの使用方法の詳細は、10.2.9項「表の選択コンポーネント値の動的な決定について」を参照してください。

表にdetailStampファセットを使用して、オプションで表示または非表示にできるデータを指定できます。このファセットにコンポーネントを追加すると、表の各行に、展開および縮小するためのアイコンが付いた追加の列が表示されます。ユーザーがアイコンをクリックして開くと、図10-9に示すように、ファセットに追加されたコンポーネントが表示されます。

図10-9 オプションで表示可能な追加のデータ

ユーザーが開かれた状態のアイコンをクリックして閉じると、図10-10に示すように、コンポーネントが非表示になります。

図10-10 追加のデータを非表示にすることも可能

detailStampファセットの使用方法の詳細は、10.3項「表への非表示機能の追加」を参照してください。

10.2.1 列および列データ

列には、データの表示に使用されるコンポーネントが含まれます。前述したように、各項目の表示に必要な子コンポーネントは1つのみで、値は表のレンダリング時にスタンプ設定されます。列をソートすることも、列にフィルタ要素を含めることも可能です。ユーザーがフィルタに値を入力すると、フィルタに入力した値に一致するデータ・セットが戻されます。フィルタは、大文字と小文字を区別する、または大文字と小文字を区別しないように設定できます。これが許可されるように表が構成されている場合、ユーザーは列を並べ替えることもできます。列には、ヘッダー・ファセットとフッター・ファセットの両方があります。ヘッダー・ファセットは、列のヘッダー・テキスト属性のかわりに使用できるため、スタイル設定可能なコンポーネントを使用できます。フッター・ファセットは、列の下部に表示されます。たとえば、図10-11では、フッター・ファセットを使用して、2つの列の下部に合計が表示されています。戻された行数が表示可能な範囲を超えている場合、フッター・ファセットは表示されますが、ユーザーは最後の行までスクロールできます。

図10-11 列のフッター・ファセット

10.2.2 表の書式設定

表コンポーネントには、ユーザーを支援する書式設定や視覚的な補助が多数用意されています。これらの機能を有効にし、どのように表示するかを指定できます。次にこれらの機能を示します。

- 行の選択: デフォルトでは、ユーザーは実行時に行を選択できません。ページのその他の場所または別のページにおいて、行でアクションを実行するために、ユーザーが行を選択できるようにするには、rowSelection属性を設定して、表で行の選択を有効化します。表は、単一の行または複数の行を選択できるように構成できます。選択された行でプログラムを使用してアクションを実行する方法の詳細は、10.2.8項「表の選択された行でのアクションの実行について」を参照してください。

- 表の高さ: 表の高さを絶対的(300ピクセルなど)に設定することも、autoHeightRows属性を使用して、一度に表示する行数に基づいて表の高さを決定することもできます。詳細は、10.1.6項「ジオメトリ管理および表、ツリーまたはツリー表コンポーネント」を参照してください。

注意:

表がpanelSplitterコンポーネントなどのレイアウト管理コンテナに配置されている場合は、コンテナによりサイズ設定され、autoHeightRowsは適用されません。

- グリッド線: デフォルトで、ADF表コンポーネントには、水平および垂直の両方のグリッド線が描画されます。これらは、horizontalGridVisibleおよびverticalGridVisible属性を使用して個別に無効化できます。

- バンディング: columnBandingInterval属性を使用して、行または列のグループが異なる背景色で交互に表示されます。これは、隣り合う行または列のグループを区別する際に役立ちます。デフォルトでは、バンディングは無効化されています。

- 列グループ: 表の列は、列コンポーネントをネストさせることで、列グループにグループ化できます。各グループには、すべての列をリンクする独自の列グループ・ヘッダーを設定できます。

- 編集可能セル: 表へのデータの表示に入力テキスト・コンポーネントを使用する場合は、すべてのセルを編集できるように表を構成することも、ユーザーが明示的にセルをクリックして編集するように構成することもできます。詳細は、10.1.3項「表、ツリーおよびツリー表のデータの編集」を参照してください。

パフォーマンスのヒント:

ユーザーがクリックした場合にのみセルの編集を可能にすると、表は最初はより早くロードされます。これは、表に大量のデータを表示する場合に便利です。

- 列の拡大: 列の幅すべてを合せても表全体に満たない場合は、columnStretching属性を設定し、領域を埋めるために列を拡大するかどうか、拡大する場合はどの列を拡大するかを決定できます。列の最小幅を設定できるため、表の列が多い場合に、拡大を有効にすると、列は設定した最小幅よりも小さくなります。拡大する列ごとに幅の割合を設定し、拡大時に列が占める領域の量を決定できます。

注意:

列の最小幅の合計がビューポートの表示可能な領域以上の場合、表はビューポートの外側まで拡大し、ビューポートの外側にアクセスできるようにスクロールバーが表示されます。

パフォーマンスのヒント:

列の拡大はデフォルトで無効化されています。この機能を有効化すると、複雑な表(データ量の多い表や、列がネストしている表など)に使用した場合には、クライアントのレンダリング時間のパフォーマンスに影響があります。

注意:

ユーザーが表のスクロール可能なデータ本体にアクセスできなくなる可能性が高くなるため、行ヘッダーまたは固定されるように構成された列は拡大されません。

- 列の選択: ユーザーにデータの列の選択を許可できます。行の選択同様、単一の列または複数の列を選択できるように構成できます。columnSelectionListenerを使用して、新しい列がユーザーによって選択された際に起動されるColumnSelectionEventに応答することもできます。このイベントにより、選択解除された列や選択された列が報告されます。

- 列の並替え: ユーザーは、実行時に列ヘッダーをドラッグ・アンド・ドロップして列を並べ替えられます。デフォルトでは、列の並替えが許可されており、panelCollectionコンポーネントのメニュー項目で処理されます。詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

10.2.3 列の書式設定

各列コンポーネントにも、ユーザーを支援する書式設定や視覚的な補助が多数用意されています。これらの機能を有効にし、どのように表示するかを指定できます。次にこれらの機能を示します。

- 列のソート: ユーザーが、指定された列を基準とし、sortable属性を使用して昇順または降順にコンテンツをソートできるよう列を構成できます。列ヘッダーの特別なインジケータにより、ユーザーは列がソート可能であることがわかります。
ユーザーがアイコンをクリックして、前にソートされていない列をソートすると、列のコンテンツは昇順でソートされます。次に同じヘッダーをクリックすると、コンテンツは降順でソートされます。表をソートできるようにするには、基礎となるデータ・モデルでもソートがサポートされている必要があります。詳細は、10.2.7項「プログラムを使用した表の列のソートの有効化について」を参照してください。

- コンテンツの位置合せ: align属性を使用して、列内のコンテンツをstart、end、left、rightまたはcenterに位置合せできます。

ヒント:

アプリケーションで複数の読み方向がサポートされている場合は、leftおよびrightではなく、startおよびendを使用します。

- 列の幅: width属性を使用して、列の幅をピクセル単位の絶対値として指定できます。列が拡大できるように構成すると、幅をパーセントとして設定することもできます。

- 行折返し: noWrap属性を使用し、行を越えて列のコンテンツを折り返すかどうかを定義できます。デフォルトでは、コンテンツは折り返されません。

- 行ヘッダー: rowHeader属性を使用して、一番左の列を行ヘッダーに定義できます。その場合、一番左の列は列ヘッダーと同じ外観でレンダリングされますが、スクロールしてページから見えなくなることはありません。図10-12に、1列目が行ヘッダーとして構成されている場合に、表に部門がどのように表示されるかを示します。

図10-12 表の行ヘッダー

行ヘッダー列の使用を選択し、行を選択できるように表を構成した場合、ユーザーが行の上にマウスを置くと、行ヘッダー列には図10-13に示すような選択矢印が表示されます。

図10-13 行ヘッダーの選択アイコン

複数選択が可能な表の場合、ユーザーがマウスを押して行ヘッダーでドラッグし、隣接する行のブロックを選択できます。また、ユーザーが上下にドラッグすると、表は垂直に自動スクロールされます。

パフォーマンスのヒント:

行ヘッダーを使用すると、表がさらに複雑になり、パフォーマンスに悪影響が発生する場合があります。

ヒント:

列の並替えや列幅の変更など、ユーザーは実行時に表が表示される方法を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

10.2.4 ページへの表の表示方法

「ADF Faces Tableの作成」ダイアログを使用して、JSFページに表を追加できます。このダイアログは、表に必要な各列へのcolumnコンポーネントの追加にも使用できます。また、EL式を使用して基礎となるモデルまたはBeanに表をバインドできます。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表を作成でき、バインディングが実行されます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』の「ADFによるデータバインドされた表の作成」の章を参照してください。

ダイアログを完了して、表と列がページに追加されたら、プロパティ・インスペクタを使用して表または列の追加の属性を構成し、表イベントに対応するためにリスナーを追加できます。表のバインド先となるCollectionModelクラスを実装する必要があります。

ページに表を表示する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、「表」をドラッグ・アンド・ドロップし、「ADF Faces Tableの作成」ダイアログを開きます。
ダイアログを使用して、既存のモデルに表をバインドします。表が有効なモデルにバインドされると、作成される列がダイアログにより自動的に表示されます。ダイアログを使用して列のheaderおよびvalue属性の値を編集し、データの表示に使用されるコンポーネントのタイプを選択します。または、手動で列を構成し、後日バインドすることもできます。ダイアログの使用方法の詳細は、[F1]を押すか「ヘルプ」をクリックします。

2. プロパティ・インスペクタで、「共通」セクションを開きます。すでに表をモデルにバインドしてある場合は、value属性を設定します。このセクションを使用して、表固有の次の属性を設定できます。

- rowSelection: 行を選択可能にする場合に値を設定します。有効な値はnone、single、multipleおよびmultipleNoSelectAllです。

注意:

rowSelection属性がmultipleに設定されており、その表に行ヘッダーも含まれている場合は、行ヘッダーの列ヘッダーをクリックすることにより、すべての行と列を選択できます。ユーザーがすべての列と行を選択できないようにする場合は、rowSelectionをmultipleNoSelectAllに設定します。

選択された行でプログラムを使用してアクションを実行する方法の詳細は、10.2.8項「表の選択された行でのアクションの実行について」を参照してください。

- columnSelection: 列を選択可能にする場合に値を設定します。有効な値はnone、singleおよびmultipleです。

3. 「列」セクションを開きます。「ADF Faces Tableの作成」ダイアログを使用して表をバインドしてある場合、これらの設定を完了する必要があります。このセクションを使用して、表のバインドの変更、各行のデータへのアクセスに使用される変数名の変更、および各列に使用される表示ラベルやコンポーネントの変更を実行できます。

ヒント:

リストされている以外のコンポーネントを使用する場合は、プロパティ・インスペクタで任意のコンポーネントを選択し、それを手動で変更します。

1. 構造ウィンドウで、ダイアログにより作成されたコンポーネントを右クリックします。

2. ポップアップ・メニューから「変換」を選択します。

3. リストから必要なコンポーネントを選択します。プロパティ・インスペクタを使用して、新しいコンポーネントを構成します。

ヒント:

列に複数のコンポーネントを表示する場合は、その他のコンポーネントを手動で追加し、それらをpanelGroupLayoutコンポーネントでラップします。これは次のように行います。

1. 構造ウィンドウで、1つ目のコンポーネントを右クリックし、前に挿入または後に挿入を選択します。挿入するコンポーネントを選択します。

2. デフォルトで、コンポーネントは縦に表示されます。1つの列内に複数のコンポーネントを隣接させて表示するには、[Shift]キーを押して、構造ウィンドウで両方のコンポーネントを選択します。選択内容を右クリックし、「囲む」を選択します。

3. panelGroupLayoutを選択します。

4. 「外観」セクションを開きます。このセクションを使用し、次に示す表固有の属性を設定して、表の外観を設定します。

- width: 表の幅を指定します。割合またはピクセル数で幅を指定できます。デフォルト設定は300ピクセルです。列を拡大するように表を構成する場合(columnStretching属性を使用)は、幅をパーセントに設定する必要があります。

ヒント:

表が、子を拡大するコンポーネントの子である場合、この幅の設定はオーバーライドされ、表はコンテナに合うように自動的に拡大されます。コンポーネントが拡大される方法の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- columnStretching: 列の幅すべてを合せても表全体に満たない場合は、この属性を設定し、領域を埋めるために列を拡大するかどうか、拡大する場合はどの列を拡大するかも決定できます。

注意:

子を拡大するコンポーネントの中に表が配置されている場合、自動的に拡大されるのは表のみです。表に合うように列を拡大する場合、列の拡大は手動で構成する必要があります。

注意:

ユーザーが表のスクロール可能なデータ本体にアクセスできなくなる可能性が高くなるため、行ヘッダーまたは固定されるように構成された列は拡大されません。

パフォーマンスのヒント:

列の拡大はデフォルトで無効化されています。この機能を有効化すると、クライアントにおける複雑な表のレンダリング時間のパフォーマンスに影響する場合があります。

列の拡大を次のいずれかの値に設定できます。

- blank: 空の列を自動的に挿入して拡大する場合に使用します(表の幅全体が行の背景色になります)。

- 具体的な名前が付けられた列: 表に現在ある列を選択して拡大する列にできます。

- last: 最後の列を、ウィンドウ内の使用されていない領域に合せて拡大する場合に使用します。

- none: 何も拡大されないデフォルトのオプションです。パフォーマンスを最適化する場合に使用します。

- multiple: パーセント値がwidth属性に設定されたすべての列は、その他の列がそれらの(拡大されない)幅にレンダリングされると、そのパーセントまで拡大されます。パーセント値は合計で重み付けされます。たとえば、3つの列のwidth属性を50%に設定すると、各列は、それ以外のすべての列がレンダリングされた後の残りの領域の1/3ずつになります。

ヒント:

ユーザーは実行時に列幅の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。変更の永続性の有効化および使用方法の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- horizontalGridVisible: 水平のグリッド線を描画するかどうかを指定します。

- verticalGridVisible: 垂直のグリッド線を描画するかどうかを指定します。

- rowBandingInterval: 色のバンディングの目的で、連続する何行で行グループを形成するかを指定します。デフォルトでは、これは0に設定されており、すべての行が同じ背景色で表示されます。別の色を使用する場合は、これを1に設定します。

- columnBandingInterval: 列のバンディングが行われる間隔を指定します。この値により、表の列バンディングの表示が制御されます。たとえば、columnBandingIntervalが1の場合、表内にバンディングされた列が交互に表示されます。

- filterVisible: 入力されたフィルタ基準に一致する行のみが表示されるように、表にフィルタを追加できます。フィルタ処理を許可するように表を構成する場合、大文字と小文字を区別する、または大文字と小文字を区別しないようにフィルタを設定できます。詳細は、10.4項「表でのフィルタ処理の有効化」を参照してください。

- テキスト属性: アクセシビリティを目的とした表のサマリーや説明だけでなく、行を表示できない場合に表示されるテキストを決定するテキスト文字列を定義できます。

5. 「動作」セクションを開きます。このセクションを使用し、次に示す表固有の属性を設定して、表の動作を構成します。

- disableColumnReordering: デフォルトでは、panelCollectionコンポーネントにデフォルトで含まれるメニュー・オプションを使用して、実行時に列を並べ替えられます。これは、ユーザーが列の順序を変更できないように変更できます。(panelCollectionコンポーネントには、表、ツリーおよびツリー表のデフォルトのメニューとツールバー・ボタンが用意されています。詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。)

注意:

ユーザーは列の順序を変更できますが、アプリケーションがユーザーのカスタマイズを許可するように構成されていないかぎり、ユーザーがページを終了するとそれらの値は保持されません。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

- FetchSize: 各データ・フェッチで戻されるブロックのサイズを設定します。デフォルトは25です。

ヒント:

表に合せるには何行必要であるかを判断するには、表の高さを取得して各行の高さで割ることで、fetchSize属性の値を決定する必要があります。fetchSize属性の値が小さすぎると、表を埋めるためにサーバーと何度もやりとりすることになります。値が大きすぎると、サーバーでは、データ・ソースから必要以上に行がフェッチされ、時間とメモリー使用量が増加します。クライアント側では、それらの行の処理とコンポーネントへのアタッチに時間がかかります。詳細は、10.1.1項「コンテンツの配信」を参照してください。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、コンポーネントのレンダリングと同時にデータがフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中にデータがフェッチされてクライアントに送信されます。属性がwhenAvailable(デフォルト)に設定されている場合は、データが利用可能かどうかレンダラでチェックされます。その場合は、コンテンツはすぐに配信されますそうでない場合は、遅延配信が使用されます。詳細は、10.1.1項「コンテンツの配信」を参照してください。

- autoHeightRows: 使用可能な領域に合せて表で高さのサイズ設定が自動的に行われるようにする場合は、表に表示する最大の行数を指定します。デフォルト値は-1です(何行であっても自動サイズ設定は行われません)。値を0に設定して、fetchSizeと同じ値にすることもできます。

注意:

autoHeightRows属性の設定について、次の点に注意してください。

- inlineStyle属性の高さを指定しても影響を与えることはなく、AutoHeightRowsの値によってオーバーライドされます。

- inlineStyle属性でmin-heightまたはmax-heightを指定することは推奨されず、autoHeightRows属性とは互換性がありません。

- コンポーネントをpanelSplitterのようなレイアウト管理コンポーネントに配置すると、このコンテナによりサイズが指定されます(自動のサイズ指定は発生しません)。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

- displayRow: 最初に表示される際に表に表示する行を指定します。使用可能な値は、表の上部に最初の行を表示する場合はfirst、表の下部に最後の行を表示する場合はlast(ユーザーが先行する行を表示するには上にスクロールする必要があります)、表で最初に選択された行を表示する場合はselectedです。

注意:

この属性が正常に機能するには、表モデルの合計の行数が把握されている必要があります。

- displayRowKey: 最初に表示される際に表に表示する行キーを指定します。値が文字列ではない場合があるため、属性は宣言的にではなくプログラムで設定する必要があります。この属性を指定すると、displayRow属性がオーバーライドされます。

注意:

この属性が正常に機能するには、表モデルの合計の行数が把握されている必要があります。

- editingMode: 編集可能なコンポーネントに、すべての行を編集可能にするか(editAll)、ユーザーが行をクリックした場合に編集可能にするか(clickToEdit)を指定します。詳細は、10.1.3項「表、ツリーおよびツリー表のデータの編集」を参照してください。

ヒント:

clickToEditを選択すると、アクティブな行のみを編集できます。この行は、activeRowKey属性で決定されます。デフォルトでは、表が最初にレンダリングされると、アクティブな行が最初に表示可能な行になります。ユーザーが別の行をクリックすると、その行はアクティブな行になります。この動作は、activeRowKey属性(「その他」セクションにあります)に異なる値を設定することで変更できます。

- contextMenuSelect: ポップアップ・メニューを開くために右クリックする際に、行を選択するかどうかを指定します。trueに設定すると、行が選択されます。ポップアップ・メニューの詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- filterModel: filterVisibleとともに使用します。詳細は、10.4項「表でのフィルタ処理の有効化」を参照してください。

- 様々なリスナー: 表で対応するイベントが起動された場合に実行されるメソッドにリスナーをバインドします(columnSelectionListenerは「その他」セクションにあります)。詳細は、第5章「イベントの処理」を参照してください。

6. 「その他」セクションを開き、次の設定を行います。

- activeRowKey: clickToEditを選択すると、アクティブな行のみを編集できます。この行は、activeRowKey属性で決定されます。デフォルトでは、表が最初にレンダリングされると、アクティブな行が最初に表示可能な行になります。ユーザーが別の行をクリックすると、その行はアクティブな行になります。この動作は、activeRowKey属性に異なる値を設定することで変更できます。

- columnResizing: エンド・ユーザーが実行時に列幅のサイズを変更できるようにするかどうかを指定します。無効に設定されている場合、列の幅はページのレンダリング後に1回設定され、ユーザーはそれらの幅を変更できなくなります。

ヒント:

ユーザーは実行時に列幅の値を変更できますが、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了するとそれらの幅の値は保持されません。変更の永続性の有効化および使用方法の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

7. 構造ウィンドウで列を選択します。プロパティ・インスペクタで、「共通」セクションを開いて、列固有の次の属性を設定します。

- headerText: 列のヘッダーに表示するテキストを指定します。outputTextコンポーネントを含むheaderファセットを追加する場合と等しい出力内容が生成されるため便利です。outputText以外のコンポーネントを使用する場合は、かわりに列のheaderファセットを使用する必要があります(詳細は手順12を参照してください)。headerファセットを追加すると、headerText属性の値は列ヘッダーにレンダリングされません。

- align: この列の位置合せを指定します。左から右への表示では、左揃え、右揃え、中央揃えに、それぞれstart、endおよびcenterが使用されます。表示が左から右であるか右から左であるかに関係なく、左揃えまたは右揃えのセルが必要な場合には、値leftまたはrightを使用できます。デフォルト値はnullで、これはスキンに依存し、行のヘッダー列およびデータ列の対比で異なることを示します。スキンの詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- sortable: 列をソート可能にするかどうかを指定します。ソート可能な列には、クリックするとその列のプロパティで表がソートされるヘッダーがあります。列をソート可能にするには、sortable属性をtrueに設定し、この列のプロパティによるソートが、基礎となるモデルでサポートされている必要があることに注意してください。詳細は、10.2.7項「プログラムを使用した表の列のソートの有効化について」を参照してください。

注意:

列の選択が有効な場合は、列ヘッダーをクリックすると、列がソートされずに選択されます。この場合、昇順/降順のソート・インジケータをクリックすると、列をソートできます。

- filterable: 列をフィルタ処理可能にするかどうかを指定します。フィルタ処理可能な列には、列ヘッダーの上部にフィルタ・フィールドが配置されます。列をフィルタ処理可能にするには、この属性をtrueに設定し、表にfilterModel属性を設定する必要があることに注意してください。リーフ列のみがフィルタ処理可能で、フィルタ・コンポーネントは、列ヘッダーが存在する場合にのみ表示されます。この列のsortProperty属性は、filterModelクラスのfilterProperty属性のキーとして使用する必要があります。

注意:

フィルタ処理が有効化されている(filterable=true)列には、フィルタ基準入力フィールドとして使用する入力コンポーネントを指定できます。これを実行するには、列にフィルタ・ファセットを追加し、入力コンポーネントを追加します。詳細は、10.4項「表でのフィルタ処理の有効化」を参照してください。

8. 「外観」セクションを開きます。このセクションを使用し、次に示す列固有の属性を使用して、列の外観を設定します。

- displayIndex: 列の表示順序索引を指定します。列を並べ替えることが可能で、displayIndex属性に基づいて表に表示されます。displayIndex属性値が設定されていない列は、データ・ソースでの順序に基づいて最後に表示されます。親列の外にある子の列を並べ替えることはできないため、displayIndex属性はトップレベルの列にのみ適用されます。

- width: 列の幅を指定します。

- minimunWidth: 列幅の最低ピクセル数を指定します。ユーザーが列のサイズ変更を試行すると、この最小幅が強制されます。また、列がフレキシブルな場合にも、この最小幅より小さいサイズには縮小されません。ピクセル幅が定義されていて最小幅の方が大きい場合、最小幅は2つのうち小さい方の値になります。デフォルトで、最小幅は10ピクセルです。

- showRequired: 対応する属性にデータが必要な場合に、列ヘッダーにアスタリスクを表示するかどうかを指定します。

- headerNoWrapおよびnoWrap: コンテンツをヘッダーおよび列内で折り返すかどうかを指定します。

- rowHeader: 列を表の行ヘッダーにする場合は、trueに設定します。

パフォーマンスのヒント:

行ヘッダーを使用すると、表がさらに複雑になり、パフォーマンスに悪影響が発生する場合があります。

9. 「動作」セクションを開きます。このセクションを使用し、次に示す列固有の属性を使用して、列の動作を構成します。

- sortProperty: この列によって表示されるプロパティを指定します。これは、フレームワークによって列のデータのソートに使用されるプロパティです。

- frozen: スクロールする際に列がページから見えなくならないように、列を固定するかどうかを指定します。固定列までの表の列は、ヘッダーでロックされ、その他の列とともにスクロールされません。親を固定せずに子の列を単独で固定することはできないため、frozen属性はトップレベルの列にのみ適用されます。

パフォーマンスのヒント:

固定列を使用すると、表がさらに複雑になり、パフォーマンスに悪影響が発生する場合があります。

- selected: trueに設定すると、最初のレンダリング時に列が選択されます。

10. 既存の表に列を追加するには、構造ウィンドウで表を右クリックし、ポップアップ・メニューから「表の中に挿入」→「列」を選択します。

11. 表にファセットを追加するには、表を右クリックして、ポップアップ・メニューからファセット - 表を選択し、追加するファセットのタイプを選択します。その後、ファセットに直接コンポーネントを追加できます。

ヒント:

ファセットに使用できる直接の子は1つのみです。ファセットに複数のコンポーネントを表示する場合は、まずグループ・コンポーネント(panelGroupLayoutなど)を挿入し、次にグループ・コンポーネントの子として複数のコンポーネントを挿入します。

12. 列にファセットを追加するには、列を右クリックして、ポップアップ・メニューからファセット - 列を選択し、追加するファセットのタイプを選択します。その後、ファセットに直接コンポーネントを追加できます。

ヒント:

ファセットに使用できる直接の子は1つのみです。ファセットに複数のコンポーネントを表示する場合は、まずグループ・コンポーネント(panelGroupLayoutなど)を挿入し、次にグループ・コンポーネントの子として複数のコンポーネントを挿入します。

13. 列にコンポーネントを子として追加し、データを表示します。
コンポーネントの値は、表のvar属性および表示する属性の変数値セットにバインドする必要があります。たとえば、File Explorerアプリケーションの表では、var属性の値としてfileが使用されており、1列目に各行のファイル名が表示されています。そのため、ディレクトリ名の表示に使用される出力コンポーネントの値は、#{file.name}です。

ヒント:

列の直接の子が入力コンポーネントの場合は、その幅を列幅に適切な幅に設定してください。幅が親列にとって広すぎる大きさに設定されていると、ブラウザにより、テキスト入力カーソルが必要以上に大きく拡大され、隣接する列を隠してしまう可能性があります。たとえば、inputTextコンポーネントのサイズが80ピクセルで、その親列のサイズが20ピクセルに設定されている場合、その表の入力カーソルは、隣接する列のクリック可能領域を覆ってしまいます。

入力コンポーネントが列の直接の子ではない場合に、サイズが自動的に設定されるようにするには、contentStyle="width:auto"を設定します。

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

JDeveloperを使用してページに表を追加すると、JDeveloperにより、各属性の列のある表が作成されます。表をモデルにバインドすると、列にはモデルの属性が反映されます。まだモデルにバインドしていない場合は、JDeveloperにより、デフォルト値を使用して列が作成されます。表作成ダイアログでの作業中に、または後からプロパティ・インスペクタを使用して、デフォルト値を変更(列の追加/削除、列ヘッダーの変更など)できます。

例10-2に、File Explorerアプリケーション内の表の省略形のページ・コードを示します。

例10-2 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" 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"
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>

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

表を含むページがリクエストされ、コンテンツ配信がlazyに設定されている場合、ページでは最初は標準のライフサイクルが実行されます。ただし、そのリクエスト中にデータがフェッチされるのではなく、独立した特別なPPRリクエストが実行されます。ページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみが実行され、対応するデータがフェッチおよび表示されます。ユーザーのアクションにより後続のデータ・フェッチが実行される場合(表のスクロールなど)、別のPPRリクエストが実行されます。図10-14に、2番目のPPRリクエスト中の表を含むページを示します。

図10-14 2番目のPPRリクエストでデータをフェッチする表

ユーザーがソート可能な列のヘッダーをクリックすると、tableコンポーネントによりSortEventイベントが生成されます。このイベントにはgetSortCriteriaプロパティがあり、それを基にして表をソートする必要のある条件が返されます。表は、基礎となるCollectionModelインスタンスにsetSortCriteria()メソッドをコールしてこのイベントに対応し、登録済の任意のSortListenerインスタンスをコールします。

10.2.7 プログラムを使用した表の列のソートの有効化について

表の列のソートを有効にできるのは、基礎となるモデルでソートがサポートされている場合のみです。モデルがCollectionModelインスタンスの場合は、次のメソッドを実装する必要があります。

public boolean isSortable(String propertyName)
public List getSortCriteria()
public void setSortCriteria(List criteria)

詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocを参照してください。

基礎となるモデルがCollectionModelインスタンスではない場合、tableコンポーネントにより、どのプロパティがソート可能かを判断するために実際のデータが自動的に調査されます。java.lang.Comparableクラスを実装するデータがある列はソート可能です。この自動サポートは、CollectionModelに直接ソートをコーディングする(ソートをSQLのORDER BY句に変換するなど)ほど効率はよくありませんが、小規模なデータ・セットには十分です。

注意:

自動サポートでは、1つの列のみのソートが提供されます。複数列のソートはサポートされていません。

10.2.8 表の選択された行でのアクションの実行について

ユーザーは表の1行以上を選択し、それらの行に対してアクションを実行できます。

表の選択状態が変更されると、表により選択イベントが起動されます。selectionEventイベントは、選択解除された行と選択された行をレポートします。

表の選択イベントをリスニングするには、selectionListener属性を使用するか、addselectionListener()メソッドを使用して表にリスナーを追加して、表にリスナーを登録します。これにより、リスナーは選択された行にアクセスし、それらの行に対してアクションを実行できます。

現在の選択内容(選択された1行または複数の行)はRowKeySetオブジェクトで、表に対してgetSelectedRowKeys()メソッドをコールして取得できます。プログラムを使用して選択内容を変更するには、次のいずれかを実行します。

- RowKeySetオブジェクトにrowKeyオブジェクトを追加するか、RowKeySetオブジェクトから削除します。

- 表に対してsetRowIndex()またはsetRowKey()メソッドをコールして、特定の行を現在行にします。その後、RowKeySetオブジェクトに対してadd()またはremove()メソッドをコールして、その行を選択内容に追加するか、選択内容から削除できます。

例10-3に表の一部を示します(この部分では、ユーザーが複数の行を選択し、「削除」ボタンをクリックしてそれらの行を削除できます)。アクション・リスナーは、mybeanマネージドBeanのperformDeleteメソッドにバインドされます。

例10-3 行の選択

<af:table binding="#{mybean.table}" rowselection="multiple" ...>
...
</af:table>
<af:commandButton text="Delete" actionListener="#{mybean.performDelete}"/>

例10-4に、選択されたすべての行を反復し、それぞれにmarkForDeletionメソッドをコールするアクション・メソッドperformDeleteを示します。

例10-4 rowKeyオブジェクトの使用

public void performDelete(ActionEvent action)
{
UIXTable table = getTable();
Iterator selection = table.getSelectedRowKeys().iterator();
Object oldKey = table.getRowKey();
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();
}
// restore the old key:
table.setRowKey(oldKey);
}

// Binding methods for access to the table.
public void setTable(UIXTable table) { _table = table; }
public UIXTable getTable() { return _table; }
private UIXTable _table;

10.2.9 表の選択コンポーネント値の動的な決定について

表にselectOneコンポーネントを使用する場合がありますが、各行でコンポーネントに異なる選択内容が表示される必要があります。そのため、実行時に項目のリストを動的に決定する必要があります。

個々の項目にスタンプを設定するにはforEachコンポーネントを使用する必要があると考える可能性がありますが、forEachはCollectionModelインスタンスと連携しないため機能しません。また、表で使用されるようなコンポーネント管理のEL変数を使用するEL式にはバインドできません。forEachコンポーネントはJSFタグの実行ステップで関数を実行しますが、表では次に示すコンポーネントのエンコーディング・ステップで実行します。そのため、forEachコンポーネントは表の準備ができる前に実行され、反復関数は実行されません。

selectOneコンポーネントの場合、直接の子はitemsコンポーネントであることが必要です。itemsコンポーネントは行変数(<f:items value="#{row.Items}"/>など)に直接バインドできますが、こうすると、基礎となるモデルを変更できなくなります。

かわりに、例10-5に示すように、項目のリストを作成するマネージドBeanを作成します。

例10-5 項目のリストを戻すマネージド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;
}

例10-6に示すように、ページの1つのコンポーネントからリストにアクセスできます。

例10-6 JSFページからの項目へのアクセス

<af:table var="row">
<af:column>
<af:selectOneChoice value="#{row.myValue}">
<f:Items value="#{page_backing.Items}"/>
</af:selectOneChoice>
</af:column>
</af:table>

10.2.10 イテレータ・タグの使用について

表は使用しないが、同じスタンプ設定機能が必要な場合には、イテレータ・タグを使用できます。たとえば、定期的な表要素のリストを表示し、各要素に対して名前、アトミック番号、記号およびグループを表示するとします。例10-7に示すように、イテレータ・タグを使用できます。

例10-7 イテレータ・タグの使用

<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:inputText label="Element Name" value="#{row.name}"/>
<af:inputText label="Atomic Number" value="#{row.number}"/>
<af:inputText label="Symbol" value="#{row.symbol}"/>
<af:inputText label="Group" value="#{row.group}"/>
</af:iterator>

各子には、必要に応じて何度でもスタンプ設定できます。反復は、first属性で指定された索引から開始され、row属性で指定された索引まで行われます。row属性が0に設定されている場合、反復は基礎となるデータにそれ以上要素がなくなるまで続けられます。

10.3 表への非表示機能の追加

表にdetailStampファセットを使用して、表示または非表示にできるデータを指定できます。このファセットにコンポーネントを追加すると、表に、切替えアイコンが付いた追加の列が表示されます。ユーザーがアイコンをクリックすると、ファセットに追加されたコンポーネントが表示されます。ユーザーが再度切替えアイコンをクリックすると、コンポーネントが非表示になります。図10-15に、コンテンツがdetailStampファセットに追加された際に表示される追加の列を示します。

注意:

detailStampファセットを使用する表がスクリーン・リーダー・モードでレンダリングされると、そのファセットのコンテンツがポップアップ・ウィンドウに表示されます。アクセシビリティの詳細は、第22章「アクセス可能なADF Facesページの開発」を参照してください。

図10-15 detailStampファセットが表示されていない表

図10-16に、1行目のdetailStampファセットが表示されている同じ表を示します。

図10-16 表示されているdetailStampファセット

注意:

列を固定できるように表を設定している場合、detailStampファセットを表示すると固定機能が働かなくなります。つまり、詳細が表示されている間、ユーザーは列を固定できません。

10.3.1 detailStampファセットの使用方法

detailStampファセットを使用するには、表示または非表示にするデータにバインドされているコンポーネントをファセットに挿入します。

detailStampファセットを使用する手順:

1. コンポーネント・パレットで、ファセットに表示するコンポーネントをdetailStampファセット・フォルダにドラッグします。図10-17に、構造ウィンドウのdetailStampファセット・フォルダを示します。

図10-17 構造ウィンドウのdetailStampファセット

ヒント:

構造ウィンドウにファセット・フォルダが表示されない場合は、表を右クリックしてファセット - 表→詳細スタンプを選択します。

2. 表示する属性が現在のレコードに固有の場合は、現在のレコードのデータの表示に表の変数が使用されるように、(単純にコンポーネントが属性にバインドされる)JSFコードを置き換えます。
例10-8に、選択した行の詳細が表示されている図10-16に示されているdetailStampファセットの表示に使用された省略形のコードを示します。

例10-8 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>

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールからdetailStampファセットに属性をドラッグ・アンド・ドロップします。コードを変更する必要はありません。

10.3.2 実行時の処理: 行データの公開

ユーザーが行の詳細を表示または非表示にすると、表によりrowDisclosureEventイベントが生成されます。イベントは、詳細を切り替える(開くまたは閉じる)よう表に通知します。

rowDisclosureEventイベントには関連付けられたリスナーがあります。表のrowDisclosureListener属性は、マネージドBeanのメソッドにバインドできます。このメソッドは、必要な後処理を実行するためのrowDisclosureEventイベントへのレスポンスとして起動されます。

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

値がフィルタに一致する行のみを表に表示するために使用できるフィルタを表に追加できます。有効化されて、表示に設定されている場合、検索可能な各列の上に検索条件入力フィールドが表示されます。

たとえば、図10-18の表は、Location値が1700の行のみを表示するようにフィルタ処理されています。

図10-18 フィルタ処理された表

フィルタ処理された表の検索はQuery-by-Exampleに基づいており、QBEテキストまたは日付入力フィールド書式を使用します。検索基準の変更では>および<=などの演算子の文字を入力できるようにするため、入力バリデータは無効になっています。たとえば、数値列の検索条件として>1500を入力できます。ワイルドカード文字もサポートされています。検索は、大文字と小文字を区別する、または大文字と小文字を区別しないようにできます。列でQBEがサポートされていない場合、検索条件入力フィールドはその列にレンダリングされません。

フィルタ処理機能では、データを表にフィルタ処理するためのモデルが使用されます。表のfilterModel属性オブジェクトは、FilterableQueryDescriptorクラスのインスタンスにバインドする必要があります。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、データ・コントロールを使用して表を作成でき、フィルタ処理が作成されます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』の「ADFによるデータバインドされた表の作成」の章を参照してください。

例10-9では、フィルタ入力フィールドを有効にするために表のfilterVisible属性がtrueに設定されていて、filterModelインスタンスの列を識別するために列にsortProperty属性が設定されています。各列要素では、filterable属性がtrueに設定されています。

例10-9 フィルタ処理が有効にされている表コンポーネント

<af:table value="#{myBean.products}" var="row"
...
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>

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

表にフィルタ処理機能を追加するには、まずフィルタ処理機能を提供するクラスを作成します。次に表をそのクラスにバインドし、フィルタ処理機能を使用するよう表と列を構成します。フィルタ処理機能を使用する表では、headerText属性に値が設定されているか、フィルタ処理される列のheaderファセットにコンポーネントが含まれている必要があります。これにより、フィルタ・コンポーネントが表示されます。また、filterModelクラスではsortProperty属性が使用されるため、列もソート可能に構成されている必要があります。

表にフィルタ処理機能を追加する手順:

1. FilterableQueryDescriptorクラスのサブクラスであるJavaクラスを作成します。このクラスの詳細は、ADF FacesのJavadocを参照してください。

2. 10.2項「表へのデータの表示」で説明されているように、表を作成します。

3. 構造ウィンドウで表を選択し、プロパティ・インスペクタで次の属性を設定します。

- filterVisible: 検索可能な列の上にフィルタ条件入力フィールドを表示する場合はtrueに設定します。

- filterModel: 手順1で作成したFilterableQueryDescriptorクラスのインスタンスにバインドします。

ヒント:

フィルタにinputTextコンポーネント以外のコンポーネント(inputDateコンポーネントなど)を使用する場合は、filterVisibleをtrueに設定するかわりに、filterファセットに必要なコンポーネントを追加できます。これは次のように行います。

1. 構造ウィンドウで、フィルタ処理する列を右クリックし、「af:columnの中に挿入」→「JSF Core」→フィルタ・ファセットを選択します。

2. コンポーネント・パレットから、ファセットにコンポーネントをドラッグ・アンド・ドロップします。

3. コンポーネントの値を、手順1で作成したFilterableQueryDescriptorクラス内の対応する属性に設定します。たとえば、値には、行に使用する変数を考慮する必要があります。

#{af:inputDate label="Select Date" id="name"
value="row.filterCriteria.date"}

4. 構造ウィンドウで表の列を選択し、プロパティ・インスペクタで表の各列に対して次の設定を行います。

- filterable: trueに設定します。

- filterFeatures: caseSensitiveまたはcaseInsensitiveに設定します。指定されない場合、大文字と小文字の区別はモデルによって決定されます。

10.5 ツリーへのデータの表示

ADF Facesのツリー・コンポーネントは、組織図や階層ディレクトリ構造などの階層データを表示します。これらのタイプのデータには、一連のトップレベル・ノードがあり、構造の各要素では、展開してその他の要素を格納できます。たとえば、組織図で、階層の各要素であるそれぞれの従業員には、任意の数の子要素(直属の部下)を含むことができます。ツリー・コンポーネントでは、複数のルート要素がサポートされています。これには、構造を表す形式でデータが表示され、各要素は階層内のレベルを表すために適切なレベルにインデントされ、親に接続されています。ユーザーは階層の一部を展開および縮小できます。図10-19に、File Explorerアプリケーションのディレクトリの表示に使用されるツリーを示します。

図10-19 File Explorerアプリケーションのツリー・コンポーネント

ADF Facesのツリー・コンポーネントでは、基礎となる階層のデータにアクセスするためのモデルを使用します。特定のモデル・クラスはoracle.adf.view.rich.model.TreeModelで、10.2項「表へのデータの表示」で説明されているように、CollectionModelを拡張します。

ツリーをサポートする独自のツリー・モデルを作成する必要があります。ツリー・モデルは行のコレクションです。現在行に子の行が含まれている場合にtrueを返すisContainer()メソッドがあります。現在行の子にアクセスするには、enterContainer()メソッドをコールします。このメソッドをコールすると、TreeModelインスタンスが子の行のコレクションに変わります。親のコレクションに戻すには、exitContainer()メソッドをコールします。

例10-10に示すように、TreeModelクラスの作成時には、oracle.adf.view.rich.model.ChildPropertyTreeModelクラスが便利です。

例10-10 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 Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド』の「マスター/ディテール・データの表示」の章を参照してください。

ツリーは、表の操作と同じような方法で操作できます。次の操作を実行できます。

- ノードを現在のノードにするには、リストへの適切な索引を使用して、ツリーでsetRowIndex()メソッドをコールします。または、適切なrowKeyオブジェクトを使用してsetRowKey()メソッドをコールします。

- 特定のノードにアクセスするには、まずそのノードを現在のノードにしてから、ツリーでgetRowData()メソッドをコールします。

- 展開または縮小されているノードの行にアクセスするには、RowDisclosureEventでgetAddedSetメソッドおよびgetRemovedSetメソッドをコールします。詳細は、10.5.4項「プログラムを使用したノードの開閉について」を参照してください。

- ノードの子コレクションを操作するには、setRowIndex()およびsetRowKey()メソッドをコールする前にenterContainer()メソッドをコールします。その後、exitContainer()メソッドをコールして親ノードに戻します。

- ツリー(任意のレベル)内のノードのrowKeyを指すには、focusRowKey属性を使用します。focusRowKey属性は、ユーザーがノードを右クリックして、「先頭として表示」ポップアップ・メニュー項目(またはpanelCollectionコンポーネントの「先頭として表示」ツールバー・ボタン)を選択すると設定されます。
focusRowKey属性が設定されていると、focusRowKey属性で指定されたノードがツリーのルート・ノードとしてツリーにレンダリングされ、ルート・ノードの横に「階層セレクタ」アイコンが表示されます。「階層セレクタ」アイコンをクリックすると、ツリーのルート・ノードからfocusRowKeyへのパスを示す「階層セレクタ」ダイアログが表示されます。これがどのように表示されるかは、pathStampファセットへのコンポーネントの配置によって決まります。

表と同様、ツリーでも、個々のノードのコンテンツを表示するためにスタンプ設定機能が使用されます。ツリーには、各ノードのデータの表示に使用されるコンポーネントのホルダーであるnodeStampファセットが含まれます。各ノードが一度ずつ、すべてのノードで繰り返しレンダリング(スタンプ設定)されます。各ノードにスタンプが設定されると、現在のノードのデータが、EL式を使用して特定可能なプロパティにコピーされます。このプロパティに使用する名前を、ツリーのvarプロパティを使用して指定します。ツリーのレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。

このスタンプ設定動作のため、ADF Facesツリーで子としてサポートされるのは、特定タイプのコンポーネントのみです。動作が設定されていないすべてのコンポーネントは、大部分がValueHolderまたはActionSourceインタフェースを実装するコンポーネントとしてサポートされています。

例10-11では、ツリーに表示されるデータを識別する変数nodeを使用して各要素のデータを参照しています。nodeStampファセットは、node変数からさらにプロパティを取得して、各要素のデータを表示します。

例10-11 ツリーへのデータの表示

<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コンポーネントの使用方法の詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

10.5.1 ツリーへのデータの表示方法

ツリーを作成するには、ページにツリー・コンポーネントを追加し、表示および動作プロパティを構成します。

ページにツリーを追加する手順:

1. 例10-10に示すように、org.apache.myfaces.trinidad.model.TreeModelクラスを拡張するJavaクラスを作成します。

2. コンポーネント・パレットの「共通コンポーネント」パネルから、「ツリー」をドラッグ・アンド・ドロップし、「ツリーの挿入」ダイアログを開きます。必要に応じてツリーを構成します。ダイアログの使用方法のヘルプを参照するには、「ヘルプ」をクリックするか、[F1]を押します。

3. プロパティ・インスペクタで、「データ」セクションを開いて次の属性を設定します。

- value: ツリーをバインドするオブジェクトのEL式を指定します。手順1で作成したように、org.apache.myfaces.trinidad.model.TreeModelのインスタンスであることが必要です。

- var: 各ノードを表す変数名を指定します。

- varStatus: オプションで、コンポーネントの状態の判断に使用可能な変数を入力します。レンダー・レスポンス・フェーズ中に、ツリーによりモデル行が反復され、各ノードがレンダリングされます。指定された任意のノードに対して、varStatus属性で次の情報を指定します。

- model: CollectionModelインスタンスへの参照

- index: 現在行の索引

- rowKey: 現在のノードの一意キー

4. 「外観」セクションを開き、次の属性を設定します。

- displayRow: 最初に表示される際にツリーに表示するノードを指定します。使用可能な値は、最初のノードを表示する場合はfirst、最後のノードを表示する場合はlast、ツリーの最初に選択されたノードを表示する場合はselectedです。デフォルトは、firstです。

- displayRowKey: 最初に表示される際にツリーに表示する行キーを指定します。この属性はプログラムのみを使用して設定する必要があります。この属性を指定すると、displayRow属性がオーバーライドされます。

- summary: オプションで、ツリーによって表示されるデータのサマリーを入力します。

5. 「動作」セクションを開き、次の属性を設定します。

- initiallyExpanded: コンポーネントが初めてレンダリングされる際に、すべてのノードを開いておく場合はtrueに設定します。

- editingMode: ツリーへのデータの表示に使用された編集可能なコンポーネントで、すべてのノードを編集可能にするか(editAll)、ユーザーがノードをクリックした場合に編集可能にするか(clickToEdit)を指定します。詳細は、10.1.3項「表、ツリーおよびツリー表のデータの編集」を参照してください。

- contextMenuSelect: 右クリックしてポップアップ・メニューを開く際に、ノードを選択するかどうかを決定します。trueに設定すると、ノードが選択されます。ポップアップ・メニューの詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- rowSelection: ノードを選択可能にする場合に値を設定します。有効な値はnone、singleまたはmultipleです。選択されたノードでプログラムを使用してアクションを実行する方法の詳細は、10.5.5項「プログラムを使用したノードの選択について」を参照してください。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、コンポーネントのレンダリングと同時にデータがフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中にデータがフェッチされてクライアントに送信されます。属性がwhenAvailable(デフォルト)に設定されている場合は、データが利用可能かどうかレンダラでチェックされます。その場合は、コンテンツはすぐに配信されますそうでない場合は、遅延配信が使用されます。詳細は、10.1.1項「コンテンツの配信」を参照してください。

- fetchSize: データ・フェッチ・ブロックの行数を指定します。詳細は、10.1.1項「コンテンツの配信」を参照してください。

- selectionListener: オプションで、選択イベントを処理するリスナーにEL式を入力します。詳細は、10.5.5項「プログラムを使用したノードの選択について」を参照してください。

- focusListener: オプションで、フォーカス・イベントを処理するリスナーにEL式を入力します。

- rowDisclosureListener: オプションで、ノードの表示イベントを処理するリスナー・メソッドにEL式を入力します。

6. 「拡張」セクションを開き、次の属性を設定します。

- focusRowKey: オプションで、最初にフォーカスされるノードを入力します。

- disclosedRowKeys: オプションで、ノードの表示を処理するバッキングBeanのメソッドにEL式を入力します。詳細は、10.5.4項「プログラムを使用したノードの開閉について」を参照してください。

- selectedRowKeys: オプションで、最初に選択されるノードのキーを入力します。詳細は、10.5.5項「プログラムを使用したノードの選択について」を参照してください。

7. ツリーの高さのサイズを自動的に設定する場合は、「その他」セクションを開き、AutoHeightRowsをノードの最大値に設定して、スクロール・バーが表示される前に表示します。デフォルト値は-1です(どのような数値であっても自動サイズ設定は行われません)。値を0に設定して、fetchSizeと同じ値にできます。

注意:

autoHeightRows属性の設定について、次の点に注意してください。

- inlineStyle属性の高さを指定しても影響を与えることはなく、AutoHeightRowsの値によってオーバーライドされます。

- inlineStyle属性でmin-heightまたはmax-heightを指定することは推奨されず、autoHeightRows属性とは互換性がありません。

- コンポーネントをpanelSplitterのようなレイアウト管理コンポーネントに配置すると、このコンテナによりサイズが指定されます(自動のサイズ指定は発生しません)。詳細は、10.1.6項「ジオメトリ管理および表、ツリーまたはツリー表コンポーネント」を参照してください。

8. コンポーネントを追加してツリーにデータを表示するには、コンポーネント・パレットからnodeStampファセットに必要なコンポーネントをドラッグします。図10-20に、File Explorerアプリケーションのディレクトリの表示に使用されたツリーのnodeStampファセットを示します。

図10-20 構造ウィンドウのnodeStampファセット

コンポーネントの値は、ツリーのvar属性および表示する属性の変数値セットにバインドする必要があります。たとえば、File Explorerアプリケーションのツリーでは、var属性の値としてfolderが使用されており、各ノードのディレクトリ名が表示されています。そのため、ディレクトリ名の表示に使用される出力コンポーネントの値は、#{folder.name}です。

ヒント:

ファセットに使用できる子コンポーネントは1つのみです。そのため、ノードごとに複数のコンポーネントを使用する場合は、図10-20に示すように、ファセットの直接の子にできるグループ・コンポーネント内にコンポーネントを配置します。

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

ページにツリーを追加すると、JDeveloperによりnodeStampファセットが追加され、ツリーのノードにスタンプが設定されます。例10-12に、File Explorerアプリケーション内のディレクトリ構造を表示するツリーの省略形のコードを示します。

例10-12 JSPページ内の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>

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

ツリーは、階層でのレベルを示すためにノードがインデントされている形式で表示されます。ユーザーはクリックしてノードを開き、子ノードを表示できます。ユーザーは開いた状態のノードをクリックして閉じることもできます。ユーザーがこれらのアイコンのいずれかをクリックすると、コンポーネントによりRowDisclosureEventイベントが生成されます。このイベントに対応する処理を実行するには、カスタムのrowDisclosureListenerメソッドを登録します。詳細は、10.5.4項「プログラムを使用したノードの開閉について」を参照してください。

ユーザーがノードを選択または選択解除すると、ツリー・コンポーネントによりselectionEventイベントが起動されます。選択されたノードに基づいてツリー・コンポーネントで後処理を実行するカスタムのselectionListenerインスタンスを登録できます。詳細は、10.5.5項「プログラムを使用したノードの選択について」を参照してください。

10.5.4 プログラムを使用したノードの開閉について

RowDisclosureEventイベントには、閉じた状態のすべてのノード用のRemovedSetオブジェクトと、開いた状態のすべてのノード用のAddedSetオブジェクトの2つのRowKeySetオブジェクトがあります。コンポーネントは、追加されたセットの全ノードの下位のサブツリーを開き、削除されたセットの全ノードの下位のサブツリーを閉じます。

例10-13に示すように、カスタムのrowDisclosureListenerメソッドは、ツリー・コンポーネントで後処理を実行できます。

例10-13 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}">

例10-14に、行公開イベントを処理するバッキングBeanメソッドを示します。例は、ツリー・ノードの展開を示しています。ツリー・ノードを縮小する場合は、getRemovedSetを使用します。

例10-14 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属性として格納されます。例10-15に示すように、このインスタンスを使用して、階層内のノードの開いた状態または閉じた状態をプログラムで制御できます。RowKeySetインスタンスに含まれるノードは開かれ、その他すべてのノードは閉じられます。addAll()メソッドによりすべての要素がセットに追加され、removeAll()メソッドによりすべてのノードがセットから削除されます。

例10-15 disclosedRowKeys属性を含むツリー・コンポーネント

<af:tree var="node"
inlineStyle="width:90%; height:300px"
id="displayRowTable"
varStatus="vs"
rowselection="single"
disclosedRowKeys="#{treeTableTestData.disclosedRowKeys}"
value="#{treeTableTestData.treeModel}">

例10-16に、公開された行キーを処理するバッキングBeanメソッドを示します。

例10-16 行キーを処理するためのバッキング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;
}

10.5.5 プログラムを使用したノードの選択について

ツリーおよびツリー表コンポーネントを使用すると、単一のノードのみまたは複数のノードを選択できるようになります。コンポーネントで複数の選択が許可されている場合、ユーザーは[Ctrl]を押しながらクリックする操作、および[Shift]を押しながらクリックする操作で複数のノードを選択できます。

ユーザーがノードを選択または選択解除すると、ツリー・コンポーネントによりselectionEventイベントが起動されます。このイベントには、選択解除されたすべてのノード用のRemovedSetオブジェクトと、選択されたすべてのノード用のAddedSetの2つのRowKeySetオブジェクトがあります。

ツリーおよびツリー表コンポーネントは、クラスoracle.adf.view.rich.model.RowKeySetのインスタンスを使用して選択されたノードを追跡します。このインスタンスは、コンポーネントのselectedRowKeys属性として格納されます。このインスタンスを使用して、階層内のノードの選択状態をプログラムで制御できます。RowKeySetインスタンスに含まれるノードは選択されているとみなされ、その他すべてのノードは選択解除されているとみなされます。addAll()メソッドによりすべてのノードがセットに追加され、removeAll()メソッドによりすべてのノードがセットから削除されます。ツリーおよびツリー表ノードの選択は、表の行の選択と同じように機能します。表の行選択のサンプル・コードは、10.2.8項「表の選択された行でのアクションの実行について」を参照してください。

10.6 ツリー表へのデータの表示

ADF Facesのツリー表コンポーネントでは、表形式で階層データが表示されます。ツリー表コンポーネントでは、階層の各ツリー・ノードのデータの列を表示できるため、ツリー表コンポーネントの表示はツリー・コンポーネントの表示より複雑です。コンポーネントには、階層のノードの開閉だけでなく、メイン・ツリー内のサブツリーにフォーカスするメカニズムもあります。図10-21に、File Explorerアプリケーションで使用されるツリー表を示します。ツリー・コンポーネント同様、ツリー表でも、コレクションのファイル間の階層関係を表示できます。また、表コンポーネントと同じように、各ファイルの属性値も表示できます。

図10-21 File Explorerアプリケーションのツリー表

ツリー表コンポーネントの直下の子は、表コンポーネントと同じように、列コンポーネントであることが必要です。表とは異なり、ツリー表コンポーネントには、階層のノードの1次識別子を含む列が配置されるnodeStampファセットがあります。treeTableコンポーネントでは、Treeコンポーネントと同じスタンプ設定動作がサポートされています(詳細は、10.5項「ツリーへのデータの表示」を参照してください)。

たとえば、(図10-21に示す)File Explorerアプリケーションの1次識別子はファイル名です。これは、nodeStampファセットに含まれる列です。タイプや「サイズ」などのその他の列は、1次識別子の属性値を表示し、ツリー表コンポーネントの直接の子です。このツリー表では、nodeStampファセット列の各ノードのデータ、および子の列の各コンポーネントのデータにスタンプを設定するために使用される変数の値としてnodeが使用されています。例10-17に、File Explorerアプリケーション内のツリー表の省略形のコードを示します。

例10-17 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>

ツリー表コンポーネントでは、表とツリーの両方と同じ多くの属性がサポートされています。これらの属性の詳細は、10.2項「表へのデータの表示」および10.5項「ツリーへのデータの表示」を参照してください。

10.6.1 ツリー表へのデータの表示方法

ツリー表を作成するには、ツリー表の挿入ウィザードを使用します。ウィザードが完了したら、プロパティ・インスペクタを使用して、ツリー表の追加の属性を構成します。

ページにツリー表を追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「ツリー表」をドラッグ・アンド・ドロップし、ツリー表の挿入ウィザードを開きます。ウィザードを完了することで表を構成します。ヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

2. プロパティ・インスペクタを使用して、その他の属性を構成します。

ヒント:

ツリー表の属性は、表およびツリー・コンポーネントの属性と同じです。属性の構成の詳細は、10.2.4項「ページへの表の表示方法」および10.5.1項「ツリーへのデータの表示方法」を参照してください。

10.7 行を値として渡す

コレクションから行全体を値として渡すことが必要になる場合があります。これを実行するには、表で行を表すために使用された変数、またはツリーでノードを表すために使用された変数を渡し、pageFlowスコープのプロパティに値として渡します。これにより、別のページでその値にスコープからアクセスできます。setPropertyListenerタグを使用すると、これを実行できます(使用の手順を含め、setPropertyListenerタグの詳細は、4.8項「ページ間の値の受渡し」を参照してください)。

たとえば、例10-18に示すように、従業員が表示された単一選択の表を含むマスター・ページがあり、ユーザーが行を1つ選択してコマンド・ボタンをクリックすると、その行のデータを編集するための新しいページにナビゲートできるようにするとします。EL変数名empは、表の1行(従業員)を表すために使用されます。commandButtonコンポーネントのaction属性値は、ユーザーによる「Employee Detail」ページへのナビゲートを可能にする静的な文字列結果showEmpDetailです。setPropertyListenerタグにはfrom値(変数emp)が使用され、toの値に格納されます。

例10-18 setPropertyListener and 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:commandButton text="Show more details" action="showEmpDetail">
<af:setPropertyListener from="#{emp}"
to="#{pageFlowScope.empDetail}"
type="action"/>
</af:commandButton>
</af:column>
</af:table>

ユーザーが従業員行のコマンド・ボタンをクリックすると、リスナーが実行され、表の現在行(従業員)に対応する#{emp}の値が取得されます。取得された行オブジェクトは、#{pageFlowScope.empDetail} EL式を使用してpageFlowScopeのempDetailプロパティとして格納されます。静的結果によりアクション・イベントが実行され、ユーザーは詳細ページにナビゲートされます。詳細ページでは、例10-19に示すように、outputTextコンポーネントは、pageFlowScope.empDetailオブジェクトから値を取得します。

例10-19 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>

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

panelCollectionコンポーネントを使用して、表、ツリーおよびツリー表にメニュー、ツールバーおよびステータス・バーを追加できます。panelCollectionコンポーネントを使用するには、表、ツリーまたはツリー表コンポーネントをpanelCollectionコンポーネントの直接の子として追加します。panelCollectionコンポーネントには、デフォルトのメニューとツールバー・ボタンが用意されています。

図10-22に、ツリー表コンポーネントを含む、File ExplorerアプリケーションのpanelCollectionコンポーネントを示します。ツールバーには、ツリー表で実行可能なアクション(ノードの開閉など)を提供するメニュー、ユーザーがツリー表を連結解除できるボタン、およびユーザーがツリー表に表示された行を変更できるボタンが含まれます。ツールバーに特定のツールバー項目を表示しないように構成できます。たとえば、ユーザーがツリーまたは表を連結解除できるようにするボタンを無効にできます。メニュー、ツールバーおよびツールバー・ボタンの詳細は、第14章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

図10-22 メニューおよびツールバーのあるツリー表のパネル・コレクション

他のファセットでは、panelCollectionコンポーネントには、メニュー・コンポーネントを保持するmenuファセット、ツールバー・コンポーネント用のtoolbarファセット、別のツールバー・コンポーネント・セット用のsecondaryToolbarファセット、およびステータス項目用のstatusbarファセットが含まれています。

デフォルトのトップレベルのメニューおよびツールバー項目は、panelCollectionコンポーネントの子として使用されているコンポーネントにより異なります。

- 表およびツリー: デフォルトのトップレベルのメニューは表示です。

- 選択可能な列が含まれる表およびツリー表: デフォルトのトップレベルのメニュー項目は表示およびフォーマットです。

- 表およびツリー表: デフォルトのツールバー・メニューは「連結解除」です。

- 選択可能な列が含まれる表およびツリー表: デフォルトのトップレベルのツールバー項目は「固定」、「連結解除」および「折返し」です。

- ツリーおよびツリー表(pathStampファセットが使用されている場合): ツールバー・ボタン「上に移動」、「先頭に移動」および「先頭として表示」も表示されます。

例10-20に、panelCollectionコンポーネントにどのようにメニューおよびツールバーが含まれるかを示します。

例10-20 表、メニューおよびツールバーを含む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:commandToolbarButton shortDesc="Create" icon="/new_ena.png">
</af:commandToolbarButton>
<af:commandToolbarButton shortDesc="Update" icon="/update_ena.png">
</af:commandToolbarButton>
<af:commandToolbarButton shortDesc="Delete" icon="/delete_ena.png">
</af:commandToolbarButton>
</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コンポーネント内で、メニューを連結解除可能にできます。詳細は、14.2項「メニュー・バーでのメニューの使用方法」を参照してください。ユーザーが次の操作をする可能性がある場合は、連結解除メニューの使用を検討してください。

- ページで類似のコマンドを繰り返し実行する場合。

- 大規模な表、ツリー表またはツリーにおいて、異なる行のデータで類似のコマンドを実行する場合。

- 長くて幅の広い表やツリー表、およびツリーでデータを表示する場合。ユーザーは一度クリックすることで、表示または非表示にする列やブランチを選択できます。

- 長くて幅の広い表、ツリー表またはツリーでデータを書式設定する場合。

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

panelCollectionコンポーネントを追加してから、panelCollectionコンポーネントに表、ツリーまたはツリー表を追加します。その後、メニューおよびツールバーを追加および変更できます。

集約表示のコンポーネントを含むpanelCollectionコンポーネントを作成する手順:

1. コンポーネント・パレットの「レイアウト」パネルから、ページに「パネル・コレクション」をドラッグ・アンド・ドロップします。表、ツリーまたはツリー表をそのコンポーネントの子として追加します。
または、ページに表、ツリーまたはツリー表がすでに存在している場合は、コンポーネントを右クリックして「囲む」を選択します。次に「パネル・コレクション」を選択して、panelCollectionコンポーネントでコンポーネントを囲みます。

2. オプションで、特定のツールバーとメニュー項目を無効にして、panelCollectionツールバーをカスタマイズします。これを実行するには、構造ウィンドウでpanelCollectionコンポーネントを選択します。プロパティ・インスペクタで、featuresOff属性を設定します。表10-1に、有効な値およびツールバーへのそれぞれの影響を示します。

表10-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ファセットにメニューをドロップし、同じファセットに「メニュー項目」をドロップしてメニュー・リストを作成します。メニューおよびツールバーの詳細は、第14章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

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

表、ツリーまたはツリー表、またはDVTプロジェクト・ガント・チャートの表領域からデータをMicrosoft Excelのスプレッドシートにエクスポートできます。ユーザーが表をエクスポートできるようにするには、コマンド・ボタンやコマンド・リンクなどのアクション・ソースを作成し、exportCollectionActionListenerコンポーネントを追加して、エクスポートするデータを関連付けます。すべての行がエクスポートされるように、またはユーザーが選択した行のみがエクスポートされるように表を構成できます。

ヒント:

DVTピボット・テーブルからデータをエクスポートすることもできます。詳細は、26.8項「ピボット・テーブルからのエクスポート」を参照してください。

たとえば、図10-23に、ユーザーがExcelのスプレッドシートにデータをエクスポートできるコマンド・ボタン・コンポーネントが含まれるADF Facesデモの表を示します。

図10-23 データをエクスポートするためのコマンド・ボタンがある表

ユーザーがコマンド・コンポーネントをクリックすると、リスナーにより、すべての行のExcelへのエクスポートが処理されます。図10-23に示すように、ユーザーが選択する行のみがエクスポートされるように、exportCollectionActionListenerコンポーネントを構成することも可能です。

注意:

次のものしかエクスポートできません。

- 値ホルダー・コンポーネント(inputやoutputコンポーネントなど)の値。

- selelctOneChoiceおよびselectOneListboxコンポーネントで使用されるselectItemコンポーネントの値(他の選択コンポーネント内のselectItemコンポーネントの値はエクスポートされません)。

- コマンド・コンポーネントのtext属性の値。

- imageおよびiconコンポーネントのshortDesc属性の値。

ブラウザ、およびリスナーの構成によって異なりますが、図10-24に示すように、ユーザーがスプレッドシートを開くか保存することができるダイアログがブラウザによって開かれるか、ブラウザにスプレッドシートが表示されます。たとえば、ユーザーがMicrosoft Internet Explorerでページを表示していて、exportCollectionActionListenerコンポーネントにファイル名が指定されていない場合、ファイルはブラウザに表示されます。Mozilla Firefoxでは、ダイアログが開かれます。

図10-24 Excelへのエクスポート・ダイアログ

ユーザーがファイルの保存を選択した場合、図10-25に示すように、後からExcelで開くことができます。ユーザーがファイルを開くことを選択した場合、その後の動作はブラウザにより異なります。たとえば、ユーザーがMicrosoft Internet Explorerでページを表示している場合、ブラウザ・ウィンドウにスプレッドシートが表示されます。ユーザーがMozilla Firefoxでページを表示している場合は、スプレッドシートがExcelで開かれます。

図10-25 Excelにエクスポートされたデータファイル

注意:

ファイルがファイルの拡張子で指定された形式と異なる旨の警告がExcelで表示される場合があります。この警告は無視して問題ありません。

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

ボタン、リンクまたはメニュー項目などのコマンド・コンポーネントを作成し、そのコンポーネントにexportCollectionActionListenerを追加します。その後、exportCollectionActionListenerコンポーネントのexportedId属性を、データをエクスポートするコレクション・コンポーネントIDに設定して、エクスポートするデータ・コレクションを関連付けます。

作業を始める前に、次のようにします。

ページに表、ツリーまたはツリー表が存在している必要があります。ない場合は、この章の指示に従って表、ツリーまたはツリー表を作成します。たとえば、表を追加するには、10.2項「表へのデータの表示」を参照してください。

ヒント:

ユーザーがエクスポートする行を選択できるようにするには、選択が許可されるよう表を構成します。詳細は、10.2.2項「表の書式設定」を参照してください。

外部形式にコレクション・データをエクスポートする手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ボタンなどのコマンド・コンポーネントをページにドラッグ・アンド・ドロップします。

ヒント:

表、ツリーまたはツリー表にコマンド・コンポーネントのあるツールバーを作成する場合は、コレクション・コンポーネントをpanelCollectionコンポーネントで囲みます。このコンポーネントにより、ツールバー機能が追加されます。詳細は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」を参照してください。

コマンド・コンポーネントのデフォルトのラベルを、意味のある名前(Export to Excelなど)に変更することが必要な場合があります。

2. コンポーネント・パレットの「操作」パネルから、「エクスポート・コレクション・アクション・リスナー」をコマンド・コンポーネントの子としてドラッグします。

3. 「エクスポート・コレクション・アクション・リスナー」ダイアログで、次の設定を行います。

- exportedId: エクスポートする表、ツリーまたはツリー表のIDを指定します。手動で入力するか、ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログを使用して、コンポーネントを選択します。

- type: excelHTMLに設定します。

4. exportCollectionActionListenerコンポーネントが選択された状態で、プロパティ・インスペクタで次の設定を行います。

- filename: エクスポートするコンテンツの選択したファイル名を指定します。この属性を設定すると、通常は「ファイルの保存」ダイアログが表示されますが、最終的にはブラウザにより異なります。この属性を設定しない場合、通常、コンテンツはブラウザにインライン表示されます(可能な場合)。

- title: エクスポートするドキュメントのタイトルを指定します。タイトルが表示されるかどうかや、どのように表示されるかは、Excelに依存します。

- exportedRows: 表のすべての行をエクスポートするか、ユーザーが選択した行のみをエクスポートするかを指定します。表でdetailStampファセットが使用されている場合は、データをエクスポートするかどうかを選択できます(detailStampファセットの詳細は、10.3項「表への非表示機能の追加」を参照してください)。次のいずれかを設定します。

- all: すべての行が自動的に選択され、エクスポートされます。

- selected: ユーザーが選択した行のみがエクスポートされます。

- allWithoutDetails: detailStampファセットのデータを除くすべての行が選択され、エクスポートされます。

- selectedWithoutDetails: ユーザーが選択した行のみがエクスポートされます(detailStampファセットのデータを除く)。

例10-21に、表およびそのexportCollectionActionListenerコンポーネントのコードを示します。exportedId値が、表のid値に設定されていることに注意してください。

例10-21 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:commandButton text="Export To Excel" immediate="true">
<af:exportCollectionActionListener type="excelHTML" exportedId="table"
filename="export.xls" title="ADF Faces Export"/>

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

エクスポートされるデータは、選択したキーの順序ではなく、索引順でエクスポートされています。つまり、選択した行のエクスポートを可能にして、ユーザーが8、4、2(という順序で)行を選択すると、行はExcelに2、4、8という順序でエクスポートされて表示されます。

10.10 スタンプ設定を使用するコンポーネントからクライアント上の選択された値へのアクセス

リッチ・クライアント・フレームワークでは、クライアント側でELがサポートされないのみでなく、クライアントへの表モデル全体の送信もサポートされていないため、JavaScriptを使用してクライアント上の値にアクセスする必要がある場合、クライアント側のコードは、値にアクセスするためにスタンプ設定するコンポーネントに依存できません。各行で同じコンポーネント・インスタンスを再利用するかわりに、完全に解決されるEL式を使用して、各行に新しいJavaScriptコンポーネントが作成されます(どの行にもコンポーネントが1つ作成される必要があると仮定しています)。

そのため、クライアント上の行固有のデータにアクセスするには、それ自体がスタンプ設定されたコンポーネントを使用して値にアクセスする必要があります。クライアント側のデータ・モデルを使用せずにこれを実現するには、クライアント側の選択変更リスナーを使用します。

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

スタンプ設定されたコンポーネントからクライアント上の値にアクセスするには、まずコンポーネントにクライアント表現があることを確認する必要があります。次に、クライアントに選択変更リスナーを登録し、そのリスナー・ハンドルで選択された行を判別して、その行のスタンプ設定された関連するコンポーネントを検索できるようにし、スタンプ設定されたコンポーネントを使用して行固有の名前を判別し、最後に、必要に応じて選択されたデータと通信する必要があります。

スタンプ設定されたコンポーネントから選択された値にアクセスする手順:

1. ページの構造ウィンドウで、スタンプ設定された行に関連付けられたコンポーネントを選択します。たとえば、例10-22の表では、outputTextコンポーネントを使用してスタンプ設定された行が表示されています。

例10-22 スタンプ設定された行に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. コンポーネント・パレットの「操作」パネルから、client Listenerを表の子としてドラッグ・アンド・ドロップします。

3. 「クライアント・リスナーの挿入」ダイアログで、「メソッド」フィールドに関数名(次の手順でこの関数を実装します)を入力し、「タイプ」ドロップダウンからselectionを選択します。
たとえば、関数としてmySelectedRowを入力した場合、JDeveloperにより、例10-23に太字で示されたコードが入力されます。

例10-23 選択を登録するためのclientListenerの使用

<af:table var="row" value="#{data}" rowSelection="single">
<af:clientListener type="selection" method="mySelectedRow"/>
...
</af:table>

このコードにより、mySelectedRow関数は、選択内容が変更されるたびにコールされます。

4. JavaScriptライブラリで、前の手順で入力された関数を実装します。この関数により、次の操作が実行されます。

- 選択された行を把握します。これを行うには、リスナーに渡されるイベント・オブジェクトを使用します。選択イベントの場合、イベント・オブジェクトのタイプはAdfSelectionEventです。このタイプを使用すると、getAddedSet()経由で新たに選択された行キーにアクセスできるようになり、選択された各行キーのプロパティが含まれるPOJSO(プレーンの古いJavaScriptオブジェクト)が返されます。このオブジェクトにアクセスしたら、for inループを使用して行キーを反復できます。たとえば、例10-24のコードでは、最初の行キー(この場合は唯一の行キー)が抽出されます。

例10-24 for inループを使用した行キーの反復

function showSelectedName(event)
{
var firstRowKey;
var addRowKeys=event.getAddedSet();

for(var rowKey in addedRowKeys)
{
firstRowKey=rowKey;
break;
}
}

- 選択済の行に関連付けられているスタンプ設定されたコンポーネントを検索します。クライアント側のコンポーネントAPI AdfUIComponentは、findComponent()メソッドを公開し、このメソッドでは、コンポーネントのIDを取得し、AdfUIComponentインスタンスを検索して返します。スタンプ設定されたコンポーネントを使用する際は、IDだけでなく、行キーも使用してコンポーネントを検索する必要があります。これをサポートするために、AdfUITableクラスには、IDと行キーの両方を取得するfindComponent()のオーバーロードのメソッドが用意されています。
選択イベントの場合、コンポーネントはイベントのソースです。そのため、イベントのソースから表を取得し、その表を使用してIDおよび行キーでインスタンスを検索します。例10-25に、これを示します(この例では、nameStampが表のIDです)。

例10-25 選択された行を指定したスタンプ設定されたコンポーネント・インスタンスの検索

// We need the table to find our 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. コンポーネントを使用するために必要なその他のコードを追加します。スタンプ設定されたコンポーネントを検出したら、その他のコンポーネントの場合と同じように通信できます。たとえば、例10-26に、スタンプ設定されたコンポーネントを使用してname属性の行固有の値(例10-22で示したスタンプ設定された値)を取得し、アラートに名前を表示する方法を示します。

例10-26 スタンプ設定されたコンポーネントの行の名前の取得

if (nameStamp)
{    // This is the row-specific name
var name = nameStamp.getValue();

alert("The selected name is: " + name);
}

例10-27にJavaScriptの全コードを示します。

例10-27 選択された行の値へのアクセスに使用されるJavaScript

function showSelectedName(event)
{
var firstRowKey;
var addedRowKeys = event.getAddedSet();

for (var rowKey in addedRowKeys)
{
firstRowKey = rowKey;
break;
}
// We need the table to find our 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);
}
}

10.10.2 選択された値へのアクセスについて

行キーはサーバーでトークン化され、クライアントの行キーには、サーバーの行キーとの類似点はありません。たとえば、クライアント側のAPI(AdfSelectionEvent.getAddedSet()など)によって処理される行キーのみが有効です。

また、対応する行がスクロールされて画面から見えなくなっていて、クライアントで使用できない場合には、AdfUITable.findComponent(id, rowKey)メソッドによりnullが戻される可能性があることに注意してください。AdfUITable.findComponent()メソッドの戻り値にnullがないか必ず確認してください。

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

この章では、値リスト・コンポーネントを使用して、ユーザーが値を選択できるオブジェクトのモデルドリブン・リストを表示する方法を説明します。

この章では、次の項目について説明します。

- 11.1項「値リスト・コンポーネントの概要」

- 11.2項「ListOfValuesデータ・モデルの作成」

- 11.3項「inputListOfValuesコンポーネントの使用方法」

- 11.4項「inputComboboxListOfValuesコンポーネントの使用方法」

11.1 値リスト・コンポーネントの概要

ADF Facesには、各リスト項目の複数の属性が表示でき、ユーザーがオプションで必要な項目を検索できる値リスト(LOV)入力コンポーネントが2つあります。このLOVコンポーネントは、あるオブジェクトの属性の移入に使用されるフィールドが、実際はデータベースの外部キー関係のように他のオブジェクトのリスト内に含まれる場合に有用です。たとえば、ユーザーが従業員情報を編集できるフォームがあるとします。ユーザーがまず編集する従業員レコードを探す必要のある別のページを用意するかわりに、図11-1に示すように、その検索および選択機能をフォームに組み込むことができます。

図11-1 値リスト入力フィールド

このフォームにおいて、従業員名フィールドは従業員のリストが含まれるLOVです。ユーザーがinputListOfValuesコンポーネントの検索アイコンをクリックすると、図11-2に示すように、「検索および選択」ポップアップ・ダイアログに、ユーザーが従業員を検索できる検索フィールドとともにすべての従業員が表示されます。

図11-2 値リスト・コンポーネントの「検索」ポップアップ・ダイアログ

ユーザーがページに戻ると、図11-3に示すように、その従業員の現在の情報がフォームに表示されます。ユーザーは、データを編集して保存できます。

図11-3 LOVコンポーネントを使用して移入されたフォーム

selectOneChoiceなど、その他のリスト・コンポーネントでも、ユーザーはリストから選択できますが、ポップアップ・ダイアログは含まれず、小規模なリストを対象としています。この章で説明するのは、inputListOfValuesおよびinputComboboxListOfValues LOVコンポーネントのみです。選択コンポーネント、リスト・ボックス・コンポーネントおよびラジオ・ボタンの詳細は、第9章「入力コンポーネントの使用およびフォームの定義」を参照してください。

前述の図に示したように、inputListOfValuesコンポーネントでは、ユーザーが項目を検索して選択できるポップアップ・ダイアログが提供されます。リストは表に表示されます。これに対し、inputComboboxListOfValuesコンポーネントでは、単純なドロップダウン・リストから選択する方法と、inputListOfValuesコンポーネントでできるのと同じ検索方法の2種類の方法で、入力する項目を選択できます。表の列はダイアログの全幅に合せて拡大しません。

searchContentファセットを使用することにより、「検索および選択」ダイアログでレンダリングされるカスタム・コンテンツを作成することもできます。returnPopupDataValue属性を定義し、ユーザーが「検索および選択」ダイアログから項目を選択して、ダイアログを閉じるときの値を使用して、プログラムで設定します。この値は、ReturnPopupEventからreturnPopupListenerの戻り値になります。returnPopupListenerを実装すると、LOVコンポーネント、その依存コンポーネントの値の設定、カスタム・コンテンツの表示などの関数を実行できます。searchContentファセットでは、表、ツリー、inputTextなどのコンポーネントを追加して、カスタム・コンテンツを表示できます。

searchContentファセットとListOfValuesモデルの両方を実装すると、「検索および選択」ダイアログでのレンダリングでsearchContentファセットの実装が優先されます。例11-1に、表コンポーネントを使用してカスタム・コンテンツを表示するためのコードを示します。

例11-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>

readOnly属性がtrueに設定されている場合、入力フィールドは無効になります。readOnlyがfalseに設定されている場合は、どのタイプの入力が許可されるかをeditMode属性で決定します。editModeがselectに設定されている場合は、リストから値を選択する方法でしか値を入力できません。editModeがinputに設定されている場合は、値をタイプして入力することもできます。

LOVコンポーネントを実装すると、ユーザーが値の一部を入力したときに提案される項目のリストを自動的に表示することもできます。たとえば、ユーザーがCaを入力すると、図11-4に示すように、Caに部分的に一致する提案リストが提案項目のリストとして表示されます。

図11-4 LOVの提案項目のリスト

図11-5に示すように、ユーザーはこのリストから項目を選択して、入力フィールドに入力できます。

図11-5 選択した提案項目

af:autoSuggestBehaviorタグをLOVコンポーネント内部に追加し、タグのsuggestItems値を、リストを取得して表示するメソッドに設定して、自動提案動作を追加します。このメソッドはマネージドBeanで作成できます。ADFモデルを使用している場合、このメソッドはデフォルトで実装されます。コンポーネントのautoSubmitプロパティをtrueに設定する必要もあります。

LOVモデルの実装では、リストをさらにフィルタするスマート・リストを実装できます。スマート・リストは両方のLOVコンポーネントで実装できます。ADFモデルを使用している場合は、そのLOVのビュー基準として定義されたスマート・リスト・フィルタをinputComboboxListOfValuesで宣言的に選択できます。スマート・リストが実装されており、自動提案動作も使用されている場合、自動提案ではスマート・リストから最初に検索されます。ユーザーが何もせずに2秒待機すると、自動提案は完全なリストからも検索して結果を追加します。maxSuggestedItems属性では、返す項目の数(-1は完全なリストを示します)を指定します。maxSuggestedItems > 0の場合は、ユーザーがクリックしてLOVの検索および選択ダイアログを起動できるように、「次へ」リンクがレンダリングされます。例11-2に、自動提案動作およびスマート・リストの両方を含むLOVコンポーネントのコードを示します。

例11-2 自動提案動作およびスマート・リスト

<af:autoSuggestBehavior
suggestItems="#{bean.suggestItems}"
smartList="#{bean.smartList}"
maxSuggestedItems="7"/>

図11-6に、リストがinputComboboxListOfValuesコンポーネントによってどのように表示されるかを示します。ポップアップ・ダイアログに問合せパネルが含まれている場合は、「検索」リンクがドロップダウン・リストの下部に表示されます。問合せパネルが使用されていない場合は、「次へ」リンクが表示されます。

図11-6 従業員名のリストが表示されたinputComboboxListOfValues

inputComboboxListOfValuesコンポーネントのドロップダウン・リストには、次の内容を表示できます。

- 完全なリスト: 図11-6に示したように、ListOfValuesModel.getItems()メソッドにより項目の完全なリストが戻されます。

- お気に入りリスト: ListOfValuesModel.getRecentItems()メソッドにより、最近選択された項目のリストが戻されます。

- 検索リンク: ポップアップの「検索および選択」ダイアログが開かれるリンク。リンクは、ドロップダウン・リストのスクロール可能なリージョンにはありません。

- customActionsファセット: その他のコンテンツを追加するためのファセット。通常、1つ以上のcommandLinkコンポーネントが含まれます。ポップアップ・ダイアログの起動など、目的のアクションを実行するには、commandLinkにロジックを実装してください。

行ごとに表示する列の数は、getItemDescriptors()メソッドを使用して、モデルから取得できます。デフォルトではすべての列が表示されます。

inputListOfValuesコンポーネントのポップアップ・ダイアログや、inputComboboxListOfValuesコンポーネントのオプションの検索ポップアップ・ダイアログにも、新規レコードを作成する機能があります。inputListOfValuesコンポーネントの場合、コンポーネントにcreatePopupId属性が設定されていると、commandToolbarButtonを含むtoolbarコンポーネントが作成アイコンとともに表示されます。図11-7に示すように、実行時に、LOVポップアップ・ダイアログにcommandToolbarButtonコンポーネントが表示されます。

図11-7 ポップアップ・ダイアログのツールバーにある作成アイコン

ユーザーが「作成」ボタンをクリックすると、新規レコードの作成に使用できるポップアップ・ダイアログが表示されます。inputComboboxListOfValuesの場合は、ツールバーではなく、ダイアログ下部のcustomActionsファセットに「作成」というラベルのcommandLinkが表示されます。このリンクにより、ユーザーが新規レコードを作成できるポップアップが起動されます。どちらの場合も、実際に新規レコードを作成するためのコードを入力する必要があります。

ヒント:

独自の作成機能を作成するかわりに、ADF Business ComponentsおよびADFデータ・バインディングを使用できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「入力表の作成」を参照してください。

問合せコンポーネント同様、LOVコンポーネントもデータ・モデルに依存して機能を提供しています。このデータ・モデルはListOfValuesModelクラスです。このモデルでは、値リストの表示に表モデルが使用され、問合せモデルにアクセスしてリストの検索を実行することも可能です。LOVコンポーネントを使用するには、指定されたインタフェースをListOfValuesModelに実装する必要があります。

ヒント:

独自のListOfValuesModelクラスを作成するかわりに、ADF Business Componentsを使用して必要な機能を作成できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされた選択リストおよびシャトルの作成」を参照してください。

ユーザーがドリストで項目を選択すると、データは選択された行(各オブジェクトは選択した行のrowDataになります)のオブジェクトのリストとして返されます。オブジェクトのリストは、選択された後キューされるReturnPopupEventで入手できます。

QueryModelクラスも実装する場合は、ユーザーが検索の実行やリストのフィルタ処理に使用できるQueryコンポーネントがポップアップ・ダイアログに含まれます。LOVポップアップ・ダイアログでのQueryコンポーネントの使用に関して、次の点に注意してください。

- 保存済検索機能はサポートされていません。

- ポップアップ・ダイアログのQueryコンポーネントとその機能は、対応するQueryDescriptorクラスに基づいています。

- LOVポップアップ・ダイアログに含めることのできるコンポーネントは、query、toolbarおよびtableのみです。

ユーザーが「検索」ボタンをクリックして検索を開始すると、ListOfValuesModel.performQuery()メソッドが起動され、検索が実行されます。問合せモデルの詳細は、第12章「問合せコンポーネントの使用方法」を参照してください。

どちらのコンポーネントでも、オートコンプリート機能がサポートされているため、ユーザーが値の一部を入力フィールドに入力し、[Tab]を使用してフィールドから移動すると、条件の一部に一致する行がダイアログに移入されます。これを機能させるには、ユーザーが一部を入力した後に[Tab]を使用してフィールドから移動した場合に、入力した値がサーバーに戻されるロジックを実装する必要があります。サーバーでは、モデル実装により、部分的に入力された値を使用してリストがフィルタ処理され、値リストを取得する問合せが実行されます。ADF Facesには、この機能のためのAPIが用意されています。

11.2 ListOfValuesデータ・モデルの作成

LOVコンポーネントを使用するには、ADF FacesのAPIを使用してLOV機能にアクセスするデータ・モデルが必要です。図11-8に、ListOfValuesモデルのクラス図を示します。

図11-8 ListOfValuesモデルのクラス図

ListOfValuesモデルおよび関連するイベントを作成する手順:

1. 図11-8に示す各インタフェース・クラスの実装を作成します。表11-1にAPIを説明します。

表11-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()メソッドを実装します。これらのメソッドによりポップアップ・ダイアログが開かれ、コンポーネントに選択された値が適用されます。

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

inputListOfValuesコンポーネントでは、11.2項「ListOfValuesデータ・モデルの作成」に記載されているように、項目のリストにアクセスするために実装したListOfValuesモデルが使用されます。

作業を始める前に、次のようにします。

ページまたはページ・フラグメントをすでに作成している必要があります。モデルに検索APIも実装すると、コンポーネントでは、ユーザーがリスト内の値を検索することもできるようになります。

inputListOfValuesコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通」パネルから、ページに「入力値リスト」コンポーネントをドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- model: 11.2項「ListOfValuesデータ・モデルの作成」で作成した、ListOfValuesModel実装に解決されるEL式を入力します。

- value: 11.2項「ListOfValuesデータ・モデルの作成」で作成した、リストへの移入に使用された属性値に解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性値を設定します。

- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。

- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。

このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。

4. 「動作」セクションを開き、次の属性値を設定します。

- autoSubmit: 該当するアクション(クリックやテキストの変更など)が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。自動提案動作を追加している場合は、autoSubmitをtrueに設定する必要があります。

- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。これにより、定義したポップアップ・ダイアログにバインドされたcommandToolbarButtonコンポーネントを含む表の上にtoolbarコンポーネントが表示されます。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。

- launchPopupListener: ポップアップの起動時に追加の機能を提供するために実装するlaunchPopupListenerに解決されるEL式を入力します。

- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerコンポーネントに解決されるEL式を入力します。

このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。

5. ユーザーが新しい項目を作成できるようにする場合は、手順4で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

6. コンポーネント・パレットの「操作」パネルから、「自動提案動作」をinputListOfValuesコンポーネントの子としてドラッグ・アンド・ドロップします。

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で実装している場合は、例11-3に示す書式をJSFページのエントリに含める必要があります。

例11-3 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メソッド・シグネチャは、例11-4に示されています。

例11-4 suggestItemsメソッド・シグネチャ

List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
oracle.adf.view.rich.model.AutoSuggestUIHints)

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

inputComboboxListOfValuesコンポーネントを使用すると、ユーザーはドロップダウン・リストから値を選択し、inputListOfValuesコンポーネントと同じように、ページのLOVフィールドおよび可能な場合はその他のフィールドに移入できます。ただし、リストの値を完全なリストとして表示することや、最近参照した値ごとに表示することも可能になります。問合せAPIを実装していれば、11.2項「ListOfValuesデータ・モデルの作成」で説明されているように、ポップアップ・ダイアログで検索を実行するようにコンポーネントを構成することもできます。

作業を始める前に、次のようにします。

ページまたはページ・フラグメントをすでに作成している必要があります。

inputComboboxListOfValuesコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通」パネルから、ページに値の入力コンボボックス・リストをドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- model: 11.2項「ListOfValuesデータ・モデルの作成」で作成した、ListOfValuesModel実装に解決されるEL式を入力します。

- value: 11.2項「ListOfValuesデータ・モデルの作成」で作成した、リストへの移入に使用された属性値に解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性値を設定します。

- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。

- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。

このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。

4. 「動作」セクションを開き、次の属性値を設定します。

- autoSubmit: 該当するアクション(クリックやテキストの変更など)が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。自動提案動作を追加している場合は、autoSubmitをtrueに設定する必要があります。

- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。これにより、定義したダイアログにバインドされたcommandToolbarButtonコンポーネントを含む表の上にtoolbarコンポーネントが表示されます。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。

- launchPopupListener: ポップアップ・ダイアログが開かれる際に追加の機能を提供するために実装するlaunchPopupListenerハンドラに解決されるEL式を入力します。

- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerハンドラに解決されるEL式を入力します。

このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。

5. launchPopupListenerを使用している場合は、LaunchPopupEventクラスのgetPopupType()メソッドを使用して、イベントのソースを区別できます。イベントがLOV検索および選択ダイアログの起動の結果の場合は、getPopupType()によってDROPDOWN_LISTが返され、イベントがダイアログの「検索」ボタンをユーザーがクリックした結果の場合は、SEARCH_DIALOGが返されます。

6. ユーザーが新しい項目を作成できるようにする場合は、手順5で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

7. コンポーネント・パレットの「操作」パネルから、「自動提案動作」をinputComboboxListOfValuesコンポーネンの子としてにドラッグ・アンド・ドロップします。

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で実装している場合は、例11-5に示す書式をJSFページのエントリに含める必要があります。

例11-5 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メソッド・シグネチャは、例11-6に示されています。

例11-6 suggestItemsメソッド・シグネチャ

List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
oracle.adf.view.rich.model.AutoSuggestUIHints)

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

この章では、queryおよびquickQuery検索パネル・コンポーネントの使用方法を説明します。

この章では、次の項目について説明します。

- 12.1項「問合せコンポーネントの概要」

- 12.2項「問合せへのモデルの実装」

- 12.3項「quickQueryコンポーネントの使用方法」

- 12.4項「問合せコンポーネントの使用方法」

12.1 問合せコンポーネントの概要

queryおよびquickQueryコンポーネントは、データ・セットの検索に使用されます。queryコンポーネントには、一連の包括的な検索基準およびコントロールが用意されており、quickQueryコンポーネントは、単一基準での検索に使用できます。

queryコンポーネントでは、次の機能がサポートされています。

- 複数の検索基準に対する選択および検索

- 基準アイテムの動的な追加および削除

- 単一基準に関連付けられている検索演算子の選択

- すべてに一致またはいずれかに一致論理積の選択

- 基本、拡張、コンパクト、簡易または設計モードでの表示

- 保存済検索の作成

- 保存済検索のパーソナライズ

queryコンポーネントの拡張モードを使用すると、デフォルトで、ユーザーは現在表示されている検索に基準アイテムを追加および削除できるようになります。ただし、基本モードで特定の機能を非表示(および拡張モードでのみ表示)にできる独自のQueryModelクラスを実装できます。たとえば、拡張モードでのみ演算子を表示することや、拡張モードでは基本モードより多くの基準を表示することができます。

通常、問合せの結果は表またはツリー表に表示され、queryコンポーネントのresultComponentId属性を使用して識別されます。ただし、その他の出力コンポーネントに結果を表示することもできます。結果を表示するように構成されているコンポーネントは、検索が実行されると自動的にレンダリングされます。

図12-1に、検索条件が3つある拡張モードのqueryコンポーネントを示します。

図12-1 検索条件が3つある問合せコンポーネント

基準がすでに決定されており、ユーザーがそこから選択できるシード済検索を作成することも、ユーザーが基準を追加してそれらの検索を保存できるようにすることも可能です。たとえば、例12-1に従業員のシード済検索を示します。ユーザーは、検索が実行される基準に値を入力できます。また、オペランド(次より大きい、次と等しい、次より小さい)や、論理積(ANDまたはOR問合せを作成する、すべてに一致またはいずれかに一致)も選択できます。ユーザーは「フィールドの追加」ドロップダウン・リストをクリックして1つ以上の基準を追加し、その検索を保存できます。アプリケーションが永続性を使用するように構成されている場合は、それらの検索基準を選択されたオペランドと論理積とともに保存し、指定された検索名を使用して再アクセスできます(永続性の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください)。

quickQueryコンポーネントは、queryコンポーネントを簡略化したバージョンです。ユーザーは、ドロップダウン・リストから選択して、任意の検索可能属性の検索を実行できます。図12-2に、水平レイアウトのquickQueryコンポーネントを示します。

図12-2 水平レイアウトのquickQueryコンポーネント

queryおよびquickQueryコンポーネントのどちらでも、検索の定義および実行にQueryModelクラスが使用されます。ユーザーが実行できるようにする特定の各検索に、関連するQueryModelクラスを作成します。

ヒント:

独自のQueryModel実装を作成するかわりに、必要な機能を提供するADF Business Componentsを使用できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFによるデータバインドされた検索フォームの作成」を参照してください。

QueryModelクラスは、一連の検索基準を定義するQueryDescriptorオブジェクトを管理します。QueryModelクラスでは、QueryDescriptorオブジェクトの作成、削除および更新が行われます。QueryModelクラスでは、シード済検索およびユーザーがパーソナライズした検索の両方の保存済検索も取得されます。詳細は、ADF FacesのJavadocを参照してください。

一連の検索基準アイテムのそれぞれにQueryDescriptorクラスを作成する必要があります。QueryDescriptorクラスでは、各シード済検索の作成に必要な基準および論理積へのアクセスが行われます。また、エンド・ユーザーのアクションに応じた、基準の動的な追加、削除、または追加と削除も実行されます。QueryDescriptorクラスにも、モードや自動実行などの様々なUIヒントがあります。詳細は、ADF FacesのJavadocを参照してください。1つのQueryModelクラスで、複数のQueryDescriptorオブジェクトを管理できます。

ユーザーが新しい保存済検索を作成すると、その保存済検索用に新しいQueryDescriptorオブジェクトが作成されます。ユーザーは、削除、選択、リセットおよび更新など、保存検索で様々な操作を実行できます。検索が実行または変更されると、適切なQueryModelメソッドがコールされて正しいQueryDescriptorオブジェクトが戻されるのみでなく、リクエスト値の適用フェーズ中にQueryOperationEventイベントがブロードキャストされます。このイベントは、JSFライフサイクルのアプリケーションの起動フェーズ中に、QueryOperationListenerハンドラにより使用されます。QueryOperationEventイベントでは、QueryDescriptorオブジェクトが引数として使用され、リスナーに渡されます。ADF Facesには、デフォルトでそのリスナーが実装されています。リスナーで実行される内容の詳細は、表12-2を参照してください。

たとえば、保存済検索の更新は、QueryModelのupdate()メソッドをコールすることで完了します。QueryOperationEventイベントがキューイングされ、更新操作に関連するモデル情報の変更処理を実行するQueryOperationListenerハンドラによって使用されます。

QueryOperationEventイベントを生成する問合せ操作のアクションは、次のとおりです。

- 検索の保存

- 保存済検索の削除

- 基本モードおよび拡張モードの切替え

- 保存済検索のリセット

- 別の保存済検索の選択

- 保存済検索の更新

- 依存基準がある基準の値の更新

AttributeCriterionクラスのhasDependentCriterionメソッドは、基準に依存関係があるかどうかを確認するためにコールできます。デフォルトでは、このメソッドはfalseを返しますが、基準に依存基準がある場合はtrueを返します。その基準の値が変更されると、QueryOperationEventがJSFライフサイクルのモデル値の更新フェーズ用にキューイングされます。モデルには、そのルート基準に入力された値に基づき、依存基準の値を更新するためのリスナーが必要です。

12.2 問合せへのモデルの実装

queryコンポーネントを使用するには、まずQueryModelクラスを作成する必要があります。

ヒント:

quickQueryコンポーネントは、QueryModelクラスを実装せずに使用できます。ただし、マネージドBeanにいくつかのロジックを追加する必要があります。詳細は、12.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

図12-3に、QueryModelクラスのクラス図を示します。

図12-3 QueryModelのクラス図

モデル・クラスを作成する手順:

1. 図12-3に示す各インタフェース・クラスの実装を作成します。QueryModelクラスを1つ実装してから、システムの各シード済検索用の適切な基準(演算子および値)が指定されたQueryDescriptorクラスを実装します。問合せに対する様々なモデル・クラスの実装の例は、ADF Facesのサンプル・アプリケーションのoracle.adfdemo.view.query.richパッケージにあるクラスを参照してください。

注意:

問合せに構成(AttributeCriterion/ConjunctionCriterionを含むConjunctionCriterion 1...nなど)が使用されている場合、この関係が抽象インタフェースによって強制されることはありません。実装で、アソシエーションに構成を使用するかどうか、およびそれらのオブジェクトのライフサイクルをどのように管理するかを決定する必要があります。

2. QueryEventイベント(queryコンポーネントのボタンにより参照される)をリスニングするマネージドBeanに、QueryListenerハンドラ・メソッドを作成します。このリスナーにより、QueryModelの適切なAPIが起動され、問合せが実行されます。例12-1に、検索基準のString表現を構成する基本のQueryListener実装のリスナー・メソッドを示します。このStringは、検索結果として表示されます。

例12-1 QueryListenerハンドラ・メソッド

public void processQuery(QueryEvent event)
{
DemoQueryDescriptor descriptor = (DemoQueryDescriptor) event.getDescriptor();
String sqlString = descriptor.getSavedSearchDef().toString();
setSqlString(sqlString);
}

問合せコンポーネントには、UIXQueryコンポーネントにrefresh()メソッドが含まれます。このメソッドは、モデル定義の変更および問合せコンポーネントをリフレッシュ(そのすべての子を削除して再作成)する必要するがある場合にコールしてください。新しい基準がQueryDescriptorに追加されたり、既存の基準が削除される際に、コンポーネントのサブツリーで想定されるものと異なる基準オブジェクトのコレクションが、基盤となるモデルで返される場合は、このメソッドをコールしてください。このメソッドは、QueryOperationListener、QueryListenerおよびActionListenerですべてコールしてください。問合せコンポーネント自体は、アプリケーションの起動フェーズの終了時にフラッシュされます。このメソッドは、レスポンスのレンダリング・フェーズ中にコールされる場合は実行されません。

実装で完了する必要のある内容をさらにわかりやすくするため、表12-1および表12-2で、図12-4に示されているUIコンポーネントの機能を、対応するインタフェースにマップしています。

図12-4 問合せコンポーネントおよび関連するポップアップ・ダイアログ

表12-1に、queryコンポーネントにレンダリングされたUIアーティファクト、関連するクラス、クラス・プロパティ、およびアーティファクトが使用するメソッドを示します。

表12-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に設定されている場合は、「パーソナライズ」オプションも追加されます。このオプションを選択すると、ユーザーが保存済検索をパーソナライズできる「パーソナライズ」ダイアログが開かれます。ユーザーは、既存の保存済検索を複製または更新できます。

表12-2に、様々なUIアーティファクトの動作と、その動作を実行するために起動される関連するメソッドを示します。

表12-2 UIアーティファクトの動作および関連するメソッド

UIアーティファクト

起動されるクラス・メソッド

生成されるイベント

コメント

7

「削除」アイコン

アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドremoveCriterion()が自動的にコールされます。

ActionEvent

現在のQueryDescriptorオブジェクトから検索フィールドが削除されます。

8

「検索」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中にQueryEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

モデル値の更新フェーズ中に、選択された演算子および検索フィールドに入力された値が、演算子および値コンポーネントに追加されたEL式を使用するモデルに自動的に更新されます(詳細は、12.4.1項「問合せコンポーネントの追加方法」を参照してください)。これらの式により、AttributeCriterionクラスでget/setOperator()、get/setOperators()およびgetValues()メソッドがそれぞれ起動されます。

アプリケーションの起動フェーズ中に、queryコンポーネントに登録されているQueryListenerが起動され、検索が実行されます。

このリスナーを実装する必要があります。

QueryEvent

常にフッターにレンダリングされます(displayMode属性がsimpleに設定されている場合、フッターのコンテンツはレンダリングされません)。

選択演算子と選択された「一致」ラジオ、および各検索フィールドに入力された値を使用して問合せが実行されます(選択が行われない場合はデフォルトが使用されます)。

9

「リセット」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中に、操作タイプQueryOperationEvent.
Operation.RESETでQueryOperationEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドreset()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを元の状態にリセットするには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

検索フィールドが、前に保存されていた状態にリセットされます。

10

「保存」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中に、操作タイプQueryOperationEvent.
Operation.SAVEでQueryOperationEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドcreate()がコールされます。create()メソッドへのコール後に、update()メソッドがコールされ、新しい保存済検索に(ダイアログ内でユーザーにより選択された)ヒントが保存されます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数に基づいて新しいオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

ユーザーにより追加された新しい検索フィールドも含め、現在の保存済検索の設定に基づいて新しい保存済検索が作成されます。

11

「フィールドの追加」ドロップダウン・リスト

アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドaddCriterion()が自動的にコールされます。AttributeDescriptorオブジェクト(名前引数で識別される)に基づいて新しいAttributeCriterionオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。

ActionEvent

既存の保存済検索に、検索フィールドとして属性が追加されます。

12

モード(「基本」または「拡張」)ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中に、操作タイプQueryOperationEvent.
Operation.MODE_CHANGEでQueryOperationEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドchangeMode()がコールされます。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

モード・ボタンをクリックすると、モードが切り替わります。

13

「削除」ボタン

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドdelete()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを削除するには、このメソッドをオーバーライドする必要があります。

ActionEvent

現在使用中でなければ、選択された保存済検索が削除されます。

14

「適用」ボタン

JSFライフサイクルのリクエスト値の適用フェーズ中に、操作タイプQueryOperationEvent.
Operation.UPDATEでQueryOperationEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。

アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドupdate()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数を使用してQueryDescriptorオブジェクトを更新するには、このメソッドをオーバーライドする必要があります。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listener)。

選択された保存済検索に行われた変更が適用されます。

15

「OK」ボタン

「適用」ボタンと同じです。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

選択された保存済検索に行われた変更が適用され、その後ダイアログが終了されます。

16

「取消」ボタン

このアクションにはメソッドが定義されていません。

QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation
Listenerハンドラ)。

ダイアログ内で行われた編集が取り消されます。

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

quickQueryコンポーネントには、検索する属性をユーザーが選択できるドロップダウン・リストが1つ含まれています。使用できる検索可能属性は、モデルの実装またはマネージドBeanから導出されます。ユーザーは、選択した属性またはすべての属性を検索できます。

quickQueryコンポーネントは、queryコンポーネントを使用したより複雑な検索の開始点として使用できます。たとえば、ある属性でクイック問合せ検索を実行して成功した場合、より複雑な検索の続行が必要な場合があります。quickQueryコンポーネントでは、endファセットへのコマンド・コンポーネントの配置を許可することで、これがサポートされており、このファセットは、ユーザーがquickQueryからqueryコンポーネントへの切替えを実行できるマネージドBeanのメソッドにバインドできます。

実行時に選択された基準のタイプに応じて、quickQueryコンポーネントにより、ドロップダウン・リストに検索可能基準がレンダリングされ、次に、属性タイプに基づいて様々な基準フィールドがquickQueryコンポーネントによりレンダリングされます。たとえば、属性タイプがNumberの場合、inputNumberSpinboxコンポーネントがレンダリングされます。問合せに完全なモデルを実装しているかぎり、これらのコンポーネントを追加する必要はありません。マネージドBeanにロジックが設定されていて、完全なモデルが必要ない場合は、手動でquickQueryコンポーネント・アーティファクトを作成します。詳細は、12.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

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

開始前に

QueryModelクラスおよび関連するクラスを実装します。詳細は、12.2項「問合せへのモデルの実装」を参照してください。

quickQueryコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「クイック問合せ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタの「共通」セクションを開き、次の属性を設定します。

- id: コンポーネントの一意のIDを入力します。

- layout: 図12-2に示すように、基準と値が隣接した状態でコンポーネントを水平に表示するか、図12-5に示すように垂直に表示するかを指定します。

図12-5 垂直に表示するよう設定されたquickQueryコンポーネント

- model: 12.2項「問合せへのモデルの実装」で作成した、QueryModelクラスを実装するクラスに評価されるEL式を入力します。

- value: 12.2項「問合せへのモデルの実装」で作成した、QueryDescriptorクラスを実装するクラスに評価されるEL式を入力します。

3. 「動作」セクションを開き、次の属性を設定します。

- conjunctionReadOnly: ユーザーが「いずれかに一致」または「すべてに一致」ラジオ・ボタンを設定できるようにするかどうかを指定します。falseに設定すると、ユーザーは論理積を設定できます。trueに設定すると、ラジオ・ボタンはレンダリングされません。

- queryListener: 12.2項「問合せへのモデルの実装」で作成したQueryListenerハンドラに対して評価されるEL式を入力します。

4. ページに表(または検索結果を表示するその他のコンポーネント)をドラッグ・アンド・ドロップします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

5. ユーザーが「拡張」リンクをクリックしてquickQueryコンポーネントを完全なqueryコンポーネントに切り替えられるようにする場合は、quickQueryコンポーネントのEndファセットにコマンド・コンポーネントを追加し、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示するロジックを実装します。

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

たとえば、検索を実行して結果を返す戻すQueryListenerハンドラを含み、すべての問合せロジックが単純なマネージドBeanに存在する場合、quickQueryコンポーネントはモデルなしで使用できます。完全なquickQueryコンポーネントの作成に必要なコンポーネントは手動で追加およびバインドする必要があります。

quickQueryコンポーネントを追加する手順:

1. マネージドBeanに、ユーザーが検索できる属性を表示するselectOneChoiceコンポーネントのvalueChangeListenerハンドラを作成します。valueChangeListenerハンドラは、検索する属性の選択を処理します。

2. マネージドBeanに、検索を実行するQueryListenerハンドラを作成します。問合せを実行するコンポーネントおよび値の取得に、検索基準値の入力に使用される入力コンポーネントのIDがこのハンドルで使用されます。

3. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「クイック問合せ」をドラッグ・アンド・ドロップします。

4. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- id: コンポーネントの一意のIDを入力します。

- layout: 図12-2に示すように、基準と値が隣接した状態でコンポーネントを水平に表示するか、図12-5に示すように垂直に表示するかを指定します。

5. 「動作」セクションを開いて、QueryListener属性を、手順2で作成したQueryListenerハンドラに解決されるEL式に設定します。

6. コンポーネント・パレットの「共通コンポーネント」パネルから、quickQueryコンポーネントのcriteriaItemsファセットに、「選択肢を1つ選択」をドラッグ・アンド・ドロップします。ダイアログで、ユーザーが検索できる属性のリストに評価されるEL式を入力するか、静的なリストを入力するかを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

7. 構造ウィンドウでcriteriaItemsファセットのselectOneChoiceコンポーネントを選択し、次の属性を設定します。

- simple: コンポーネントのラベルを表示しない場合はtrueに設定します。

- valueChangeListener: 手順1で作成したリスナーに評価されるEL式を入力します。

- autoSubmit: trueに設定します。

8. コンポーネント・パレットから、必要に応じて選択リスト項目を追加します。selectOneChoiceおよびselectItemsコンポーネントの使用方法の詳細は、9.6項「選択コンポーネントの使用方法」を参照してください。

9. コンポーネント・パレットの「共通コンポーネント」パネルから、inputTextコンポーネントをquickQueryコンポーネントの直接の子としてドラッグします。次の属性を設定します。

- simple: ラベルを表示しない場合はtrueに設定します。

- value: ユーザーが入力する値を含むプロパティに評価されるEL式を入力します。

ヒント:

inputTextコンポーネントを追加しない場合は、実行時に、無効化されたinputTextコンポーネントおよび無効化された実行アイコンがレンダリングされます。

10. ユーザーが「拡張」リンクをクリックしてquickQueryコンポーネントを完全なqueryコンポーネントに切り替えられるようにする場合は、quickQueryコンポーネントのEndファセットにコマンド・コンポーネントを追加し、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示するロジックを実装します。

11. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに表(または検索結果を表示するその他のコンポーネント)をドラッグします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

12.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ハンドラを実装する必要があります。

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

queryコンポーネントは、フル機能検索に使用されます。基本および拡張モードがあり、ユーザーはボタンをクリックすることで切り替えることができます。

基本モード問合せの機能は次のとおりです。

- 選択可能な検索条件演算子のドロップダウン・リスト

- ANDまたはOR(すべて一致または一部一致)とともに使用する選択可能なWHERE句

- 保存済(シード済)検索

- パーソナライズされた保存済検索

拡張モードの問合せフォームにも、検索可能属性のリストから選択することで、ユーザーが動的に検索条件を追加できる機能があります。ユーザーは、追加された任意の条件を後から削除できます。

ユーザーは、演算子のドロップダウン・リストから選択して、検索用に問合せを作成できます。入力フィールドは、値リスト(LOV)、数値スピナー、日付チューザ、あるいはその他の入力コンポーネントとして構成されます。

リストの複数項目の選択をサポートするには、モデルでviewCriteriaItemにコントロール・ヒントを表示し、基礎となる属性を、対応する表示オブジェクト内のLOVとして定義する必要があります。ヒントは、複数選択またはin演算子機能を有効または無効にするために使用されます。複数選択が有効になっている場合に、EqualsまたはDoes not equal演算子を選択すると、検索基準フィールドがselectManyChoiceコンポーネントとしてレンダリングされます。ユーザーは、リストから複数の項目を選択できます。

検索基準フィールドのコンポーネントは、基礎となる属性のデータ型、選択されている演算子、および複数選択が有効になっているかどうかによって異なります。たとえば、Contains演算子が選択されているString型の属性の検索フィールドは、表12-3に示されているように、inputTextコンポーネントとしてレンダリングされます。

演算子がEqualsまたはDoes not equalであり、複数選択が有効になっていない場合、コンポーネントは、モデルの「デフォルトのリスト・タイプ」ヒントで指定されているコンポーネントにデフォルトで設定されます。

表12-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データ型の場合にレンダリングされるコンポーネントを、表12-4に示します。

表12-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データ型の場合にレンダリングされるコンポーネントを表12-5に示します。

表12-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の詳細は、第11章「値リスト・コンポーネントの使用方法」を参照してください。

autoSubmitがtrueに設定されている場合、検索基準での値の変更は、すぐにモデルにプッシュされます。問合せコンポーネントは、依存基準がある場合のみ、その基準リストを自動的にフラッシュします。基準インスタンスに依存基準がなく、autoSubmitがtrueに設定されている場合、問合せコンポーネントは部分的にのみリフレッシュされます。

「すべてに一致」または「いずれかに一致」ラジオ・ボタン・グループで、問合せをさらに変更できます。「すべてに一致」を選択すると、基本的にAND関数になります。問合せでは、選択した条件にすべて一致する行のみが返されます。「いずれかに一致」を選択すると、OR関数になります。問合せでは、基準アイテムのいずれか1つに一致するすべての行が返されます。

すべての検索基準の値(null値を含む)を入力して「すべてに一致」または「いずれかに一致」ラジオ・ボタンを選択した後、ユーザーは「検索」ボタンをクリックして問合せを開始できます。問合せ結果は、出力コンポーネントに表示できます。通常、出力コンポーネントは表またはツリー表ですが、resultComponentId属性に指定することで、af:forms、af:outputTextおよび図形など、その他の表示コンポーネントを結果コンポーネントとして関連付けることができます。

「基本」または「拡張」ボタンが有効化および表示されている場合、ユーザーは2つのモードを切り替えられます。各モードでは、そのモードに定義された検索条件のみが表示されます。検索条件フィールドは、基本のみ、拡張のみ、または両方のモードで表示されるように定義できます。

拡張モードでは、コントロール・パネルにも、検索可能属性のポップアップ・リストを表示する「フィールドの追加」ボタンが含まれます。ユーザーがこれらの属性のいずれかを選択すると、動的に生成された検索条件の入力フィールドおよびドロップダウンの演算子のリストが表示されます。すべての検索条件入力フィールドおよび新しく追加されたフィールドの位置は、モデル実装により決定されます。

この新しく作成された検索条件フィールドでも、隣に削除アイコンが表示されます。ユーザーは、後からこのアイコンをクリックして、追加したフィールドを削除できます。初めから定義されていた検索条件フィールドは、削除アイコンがないため、ユーザーが削除することはできません。図12-6に、「Salary」という名前の動的に追加された検索基準フィールドがある拡張モードのqueryコンポーネントを示します。フィールドの隣にある削除アイコン(X)に注目してください。

図12-6 動的に追加された検索規準のある拡張モードの問合せ

ユーザーは、「保存」ボタンをクリックして、入力された検索条件およびモードを保存することもできます。ポップアップ・ダイアログでは、ユーザーは保存済検索に名前を付け、チェック・ボックスを選択してヒントを指定できます。セッションを超えて保存済検索を使用可能にする場合は、永続データ・ストアが必要です。永続性の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

シード済検索は、基本的に、アプリケーション開発者によって作成された保存済検索です。コンポーネントを初期化すると、ユーザーは、そのqueryコンポーネントに関連付けられているシード済検索を選択できるようになります。

ユーザーが作成した保存済検索およびシード済システム検索は、「保存済の検索」ドロップダウン・リストに表示されます。シード済検索とユーザーの保存済検索は、仕切線によって区切られます。

保存済検索およびシード済検索を今後の使用に備えてパーソナライズすることもできます。保存済検索のパーソナライズには、永続データ・ストア機能が必要です。永続性の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

前述のデフォルトの表示の他に、コンパクト・モード、簡易モードまたは設計モードで表示するようにqueryコンポーネントを構成することもできます。コンパクト・モードにはヘッダーや境界がなく、「保存済の検索」ドロップダウン・リストが開くアイコンまたは閉じるアイコンの隣に移動します。図12-7に、コンパクト・モードに設定されている、図12-6と同じqueryコンポーネントを示します。

図12-7 コンパクト・モードの問合せコンポーネント

簡易モードでは、ヘッダーおよびフッターがなく、通常その領域に表示されるボタンもないコンポーネントが表示されます。図12-8に、簡易モードに設定された同じqueryコンポーネントを示します。

図12-8 簡易モードの問合せコンポーネント

設計モードは、外観が簡易モードと同じですが、設計モードは主にQueryDescriptorの設計に使用されます。

queryコンポーネントでは、問合せにコマンド・ボタンなどの追加コンポーネントを追加できるtoolbarおよびfooterファセットがサポートされています。たとえば、quickQueryおよびqueryコンポーネントを切り替えるコマンド・コンポーネントを作成し、それらをtoolbarファセットのツールバーに配置できます。

12.4.1 問合せコンポーネントの追加方法

作業を始める前に、次のようにします。

QueryModelクラスおよび関連するクラスを実装します。詳細は、12.2項「問合せへのモデルの実装」を参照してください。

問合せコンポーネントを追加する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「問合せ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- id: コンポーネントの一意のIDを設定します。

- model: 12.2項「問合せへのモデルの実装」で作成した、QueryModelクラスに解決されるEL式を入力します。

- value: 12.2項「問合せへのモデルの実装」で作成した、QueryDescriptorクラスに解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性を設定します。

- displayMode: コンポーネントをデフォルト・モード、簡易モード、コンパクト・モードまたは設計モードのいずれで表示するかを指定します。

- saveQueryMode: 実行時に保存済検索を表示および使用するかどうかを指定します。ユーザーがすべての保存済検索を表示および編集できるようにする場合は、defaultに設定します。ユーザーは保存済検索を表示および選択できるが、更新できないようにする場合は、readOnlyに設定します。保存済検索を表示しない場合は、hiddenに設定します。

- modeButtonPosition: ユーザーがモードを基本から拡張に切り替えられるボタンをツールバーに表示するか(デフォルト)、footerファセットに表示するかを指定します。

- modeChangeVisible: 基本または拡張の切替えボタンを非表示にする場合は、falseに設定します。

4. 「動作」セクションを開き、次の設定を行います。

- conjunctionReadOnly: 検索がすべての基準に一致(問合せではAND関数を使用)するか、いずれかの基準に一致(問合せではOR関数を使用)するかの決定に、ユーザーがラジオ・ボタンを選択できるようにする場合は、falseに設定します。trueに設定すると、ラジオ・ボタンはレンダリングされません。

- queryListener: 12.2項「問合せへのモデルの実装」で作成した、QueryListenerハンドラに評価されるEL式を入力します。

5. 「その他」セクションを開き、次の設定を行います。

- criterionFeatures: ユーザーが基準にmatchCaseを設定できるように、matchCaseDisplayedを入力します。このオプションは、Stringデータ型でのみ使用できます。

6. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに表(または検索結果を表示するその他のコンポーネント)をドラッグします。表にIDを設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

7. 構造ウィンドウでqueryコンポーネントを選択し、resultComponentIDを表のIDに設定します。

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

この章では、JSFページのダイアログ、メニュー、ウィンドウなど、2次ウィンドウにポップアップ要素を作成および使用する方法について説明します。また、ADF Facesダイアログ・フレームワークを使用して、別のページ・フローを持つダイアログを作成する方法も説明します。

この章では、次の項目について説明します。

- 13.1項「ポップアップ要素の使用の概要」

- 13.2項「ポップアップ要素の宣言的作成」

- 13.3項「プログラムによるポップアップの起動」

- 13.4項「ポップアップ要素の起動」

- 13.5項「コンテキスト情報の表示」

- 13.6項「インライン・ポップアップの自動取消しの制御」

13.1 ポップアップ要素の使用の概要

ADF Facesには、2次ウィンドウの情報を表示および非表示にするための、一連のリッチ・クライアント・コンポーネントが用意されています。popupコンポーネントは非表示のレイアウト・コントロールで、通常は、インライン(同じページに属する)ダイアログ、ウィンドウおよびメニューを表示するために、他のコンポーネントと組み合せて使用されます。

たとえば、図13-1は、dialogコンポーネントをpopupコンポーネントの子として配置することで作成されるダイアログ・ボックスを示しています。ユーザーは、検索条件を入力してから「OK」して、エントリを送信したり、「取消」をクリックまたはダイアログを閉じて、ダイアログを終了できます。

図13-1 af:dialogコンポーネント

また、ポップアップ内のコンポーネントを使用して、別のコンポーネントに関連するコンテキスト情報を表示することもできます。このように構成すると、関連するコンポーネントに小さい正方形が表示されます。マウスをアイコンの上に置くと、図13-2に示すように、アイコンが大きくなり、ノート・アイコンも表示されます。

図13-2 マウスを置くとアイコンが大きくなり、ノートが表示される

ノート・アイコンをクリックすると、関連するポップアップにそのコンテンツが表示されます。

ADF Facesには、親ページとは別にに表示されるプロセス用にページの作成をサポートするダイアログ・フレームワークも用意されています。このフレームワークでは、独自の制御フローを持つ複数のダイアログ・ページがサポートされています。たとえば、あるユーザーが購入を選択した後にWebサイトから離れ、支払いを完了する前に新しいクレジット・カードへの申込みを決定したとします。外部ブラウザ・ウィンドウで、ダイアログ・フレームワークを使用してクレジット・カードのトランザクションが開始されます。クレジット・カードのトランザクションが終了しても、元のページのチェックアウト・トランザクションは終了しません。

このダイアログ・フレームワークは、親ページの一部としてインラインで使用することもできます。これは、ページに独自の制御フローが必要だが、ポップアップ・ブロッカで外部ウィンドウをブロックさせない場合に便利です。

アプリケーションで完全Fusionテクノロジ・スタックを使用している場合、このダイアログ・フレームワークは、ADFタスク・フローで使用できるように、ADF Facesコントローラと統合されています。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のモーダル・ダイアログでのバインド・タスク・フロー実行に関する項を参照してください。

13.2 ポップアップ要素の宣言的作成

表13-1に示すように、dialog、panelWindow、menuおよびnoteWindowコンポーネントは、インライン・ポップアップ要素を表示するために、すべてpopupコンポーネント内で使用できます。popupコンポーネントで子コンポーネントが存在しない場合は、非常にシンプルなインライン・ポップアップが表示されます。

表13-1 popupコンポーネントで使用されるコンポーネント

コンポーネント

実行時に表示

dialog

OK、承諾、拒否および取消しのアクションがアクティブ化された場合に、ダイアログ内に子を表示し、イベントを配信します。詳細は、13.2.1項「ダイアログの作成方法」を参照してください。

panelWindow

ダイアログに似たウィンドウに子を表示しますが、イベントはサポートしません。詳細は、13.2.2項「パネル・ウィンドウの作成方法」を参照してください。

menu

関連するコンポーネントのポップアップ・メニューを表示します。詳細は、13.2.3項「ポップアップ・メニューの作成方法」を参照してください。

noteWindow

特定のUIコンポーネントに関連付けられた読取り専用の情報を表示します。ノート・ウィンドウはヘルプやメッセージの表示に使用され、通常はマウスを置いたり、フォーカスをしたときに表示されます。詳細は、13.2.4項「ノート・ウィンドウの作成方法」を参照してください。

親コンポーネントのないpopupコンポーネント

コンテンツをインラインで表示します。

dialogコンポーネントとpanelWindowコンポーネントはいずれも定義ヘルプがサポートされていますが、ヘルプ・アイコン(疑問符が表示された青い丸)の上にカーソルを移動するとコンテンツが表示されます。詳細は、17.5項「コンポーネントへのヘルプの表示」を参照してください。

通常は、コマンド・コンポーネントとshowPopupBehaviorタグを組み合せて、ポップアップ要素を起動します。showPopupBehaviorタグと、タグで起動されるコンポーネントを関連付けます。このタグでは、ポップアップ要素の位置も制御します(必要な場合)。

showPopupBehaviorタグは、コマンド・コンポーネントのアクション・イベントで使用されるだけでなく、showDetailイベントやselectionイベントなどの他のイベントと組み合せて使用できます。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

デフォルトで、ポップアップ要素のコンテンツは、ポップアップ要素が表示されるまでサーバーから送信されません。このため、開かれた時にポップアップ要素が表示されるスピードと、親ページがレンダリングされるスピードが入れ替わります。ポップアップ要素がロードされると、すぐに表示できるよう、コンテンツはクライアントにおいてデフォルトでキャッシュされます。

popupコンポーネントのcontentDelivery属性を次のいずれかのオプションに設定することで、コンテンツの配信方法を変更できます。

- lazy: 前述のデフォルトの方法。コンテンツは、ポップアップ要素が一度表示されるまでロードされず、ロードされるとキャッシュされます。

- immediate: コンテンツはすぐにページにロードされ、可能なかぎり迅速に表示されます。この方法は、ページが使用されるたびにすべてのユーザーが必ず使用するポップアップ要素に使用します。

- lazyUncached: コンテンツはポップアップ要素が表示されるまでロードされず、ポップアップ要素が表示されるたびにリロードされます。この方法は、失効するか期限切れになる可能性があるデータをポップアップ要素に表示する場合に使用します。

popupコンポーネントのcontentDelivery属性をlazyまたはlazyUncachedに設定した場合は、別のpopupコンポーネントの属性(childCreation)をdeferredに設定することで、popupコンポーネントおよびホストするページのパフォーマンスをさらに最適化できます。これにより、アプリケーションがコンテンツを配信するまで、popupコンポーネントの子コンポーネントの作成が遅延します。childCreation属性のデフォルト値はimmediateです。

13.2.1 ダイアログの作成方法

ダイアログを閉じた場合にイベントを呼び出す必要がある場合は、ダイアログを作成します。dialogコンポーネントをpopupコンポーネントの子として追加すると、他のコンポーネントを追加してデータを表示および収集できます。

デフォルトでは、dialogコンポーネントは次の組合せのボタンで構成できます。

- 「取消」

- 「OK」

- 「OK」および「取消」

- 「はい」および「いいえ」

- 「はい」、「いいえ」および「取消」

- なし

これらのボタンをクリックすると、dialogEventが起動されます。buttonBarファセットを使用すると、他のボタンをダイアログに追加できます。追加するボタンでは、dialogEventは起動されません。かわりに、標準のactionEventが起動されます。追加するボタンでは、partialSubmit属性をtrueに設定することをお薦めします。これにより、actionEventがダイアログ内のコンポーネントでのみ起動されます。ただし、af:popupコンポーネントのautoCancelプロパティの値をdisabledに設定すると、ボタンを追加してpartialSubmit属性をfalseに設定できます。この後者のオプションを選択すると(partialSubmitをfalseに設定)、popupコンポーネントの表示(拡大解釈すると、dialogコンポーネント)が復元される前に、アプリケーションでページが再ロードされ、ページのコンポーネントが初期化されるため、エンド・ユーザーの待機時間が長くなります。af:popupコンポーネントのautoCancelプロパティの値をenabled(デフォルト値)に設定する場合は、コマンド・コンポーネントのpartialSubmit属性をfalseに設定する必要があります。af:popupコンポーネントのautoCancelプロパティの使用の詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

インライン・ダイアログを作成する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「ポップアップ」をドラッグ・アンド・ドロップします。

ヒント:

popupコンポーネントがページのどの場所に表示されるかは、popupの起動に使用されるコンポーネントで導かれるため、これは重要ではありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- contentDelivery: コンテンツがポップアップ内のコンポーネントにどのように配信されるかを選択します。

ヒント:

ダイアログ内の入力コンポーネントの値は、ユーザーがダイアログの「取消」ボタンをクリックしてもリセットされません。ユーザーが次にダイアログを開くと、これらの値はまだ表示されます。この値をサーバーの現在の値に合せるには、contentDelivery属性をlazyUncachedに設定します。

- animate: アニメーションを有効にするには、trueを選択します。アニメーションは、trinidad-config.xmlファイルの構成およびスキン・プロパティ(詳細は、A.6.2.1項「アニメーションの有効化」を参照)によって決定されます。この設定は、falseを選択することでオーバーライドできます。

- launcherVar: 起動コンポーネントの参照に使用する変数を入力します。この変数は、ポップアップまたはその子コンポーネントでのイベント配信中で、eventContextがlauncherに設定されている場合にのみ到達可能です。

- eventContext: 表で選択した行の情報がポップアップ内のダイアログに表示される場合など、ポップアップが複数のオブジェクトで共有されている場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーのコール前にクリックした行が最新の状態になり、その行のデータのみが返されます。詳細は、13.2.5項「実行時の処理: popupコンポーネント・イベント」を参照してください。

3. オプションで、自動取消し動作を決定するには、プロパティ・インスペクタで「その他」セクションを開き、autoCancelプロパティの値を設定します。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

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に設定されている場合、ダイアログは1つの子コンポーネントを拡大します。ただし、拡大できる子コンポーネントであることが必要です。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

注意:

resizeをonまたはstretchChildrenをfirstに設定する場合は、contentWidthおよびcontentHeightも設定する必要があります(手順8を参照)。それ以外の場合、サイズはデフォルトで250x250ピクセルになります。

6. 「外観」セクションを開き、テキスト属性を設定します。
ボタン・テキストとラベルとアクセス・キーを別々に指定するかわりに、2つを結合して、アクセス・キーがボタン・テキストの一部になるようにします。アクセス・キーとして使用する文字の前にアンパサンド(&)を付けます。

たとえば、肯定ボタンのテキストが「OK」で、「OK」のOをアクセス・キーにする場合は、&OKを入力します。

7. 必要に応じて、「動作」セクションを開き、dialogListener属性の値を入力します。値は、イベントを処理するダイアログ・リスナー・メソッドのEL式メソッド参照にしてください。
たとえば、項目の削除を確認するためのダイアログを作成するとします。次に、例13-1に示すdeleteItemメソッドと同様のメソッドをマネージドBeanにメソッドを作成します。このメソッドは、イベントからの結果にアクセスします。結果がyes以外の場合、ダイアログは閉じられます。結果がyes(ユーザーが項目を削除する)場合、メソッドは選択された項目を取得して削除します。

例13-1 項目を削除する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);
}

例13-2に、dialogListener属性がdeleteItemメソッドにどのようにバインドされるかを示します。

例13-2 dialogListener属性のメソッドへのバインド

<af:dialog title="#{explorerBundle['deletepopup.popuptitle']}"
type="yesNo"
dialogListener="#{explorer.headerManager.deleteItem}"
id="d1">

dialogEventは、結果がok、yesまたはnoの場合にのみ伝播されます。これは必要に応じてブロックできます。詳細は、5.3.5項「イベントがサーバーに伝播されないようにする方法を参照してください。

かわりに、ユーザーが「取消」ボタン(または「閉じる」アイコン)をクリックすると、結果がcancelになり、popupCancelクライアント・イベントがpopupコンポーネントで発生し、他のイベント(dialogEventなど)がサーバーにアクセスできなくなります。ただし、popupCancelイベントはサーバーに配信されます。

8. ダイアログに固定サイズを設定する場合、またはresizeをonまたはstretchChildrenをfirstに設定している場合は、「その他」セクションを開き、次の属性を設定します。

- contentHeight: 目的の高さをピクセルで入力します。

- contentWidth: 目的の幅をピクセルで入力します。

ヒント:

ユーザーは実行時に、これらの属性の値を変更できますが(resize属性がonに設定されている場合)、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了すると値は保持されません。変更の永続性の有効化および使用方法の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

注意:

showPopupBehaviorタグのないコマンド・コンポーネントがダイアログの起動に使用されており、そのコンポーネントにwindowHeightおよびwindowWidth属性の値がある場合、コマンド・コンポーネントの値によってcontentHeightおよびcontentWidthの値がオーバーライドされます。showPopupBehaviorタグの詳細は、13.4「ポップアップ要素の起動」を参照してください。

9. 必要に応じて、コマンド・コンポーネントをbuttonBarファセットに追加します。追加されたすべてのコマンド・コンポーネントでpartialSubmit属性をtrueに設定することをお薦めします。ただし、af:popupコンポーネントのautoCancelプロパティの値をdisabledに設定すると、コマンド・コンポーネントのpartialSubmit属性をfalseに設定できます。af:popupコンポーネントのautoCancelプロパティおよびコマンドコンポーネントpartialSubmitプロパティの値では、コマンド・コンポーネントがダイアログをどのように閉じて再ロードするかを決定します。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

ヒント:

ファセットがビジュアル・エディタに表示されない場合は、次のようにします。

1. 構造ウィンドウで、dialogコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - ダイアログ」→「ButtonBar」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

デフォルトでは、追加されたコマンド・コンポーネントはダイアログを閉じません。ダイアログを閉じる処理および必要な処理を管理するハンドラに、コマンド・コンポーネントのactionListenerをバインドする必要があります。たとえば、これを行う方法については、タグのドキュメントを参照してください。

10. コンポーネントを挿入して、ダイアログのデータを表示または収集します。コンポーネントを含めるには、panelGroupLayoutなどのレイアウト・コンポーネントを使用します。

ヒント:

通常は、ダイアログの「取消」ボタンまたは「閉じる」アイコンをクリックすると、inputTextコンポーネントに入力したデータが送信されなくなります。ただし、ダイアログのinputTextコンポーネントでautoSubmit属性をtrueに設定すると、送信が実行されるため、ダイアログの取消し動作がオーバーライドされます。

11. 親ページのロジックを追加し、ポップアップおよびダイアログを起動します。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

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

panelWindowコンポーネントはdialogコンポーネントに似ていますが、ボタンを構成したり、ボタンをファセットに追加することはできません。いくつかのロジックを起動してpanelWindowのデータを処理する必要がある場合は、popupコンポーネントのcancelイベントのリスナーを作成する必要があります。

panelWindowコンポーネントを含むpopupコンポーネントは、formコンポーネント内に含まれる必要があります。

ヒント:

Fusionテクノロジ・スタックを使用するアプリケーションのインライン・ポップアップとしてpanelWindowを使用しており、ダイアログの外観をエミュレートする場合は、panelWindowコンポーネントをpanelStretchLayoutコンポーネントのcenterファセットに配置し、コマンド・ボタンをbottomファセットに配置します。

インライン・ウィンドウを作成する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「ポップアップ」をドラッグ・アンド・ドロップします。

ヒント:

popupコンポーネントがページのどの場所に表示されるかは、ポップアップの起動に使用されるコンポーネントで導かれるため、これは重要ではありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- contentDelivery: コンテンツがポップアップ内のコンポーネントにどのように配信されるかを選択します。

ヒント:

ユーザーがpanelWindowコンポーネントを閉じても、入力コンポーネントの値はリセットされません。ユーザーが次にウィンドウを開くと、これらの値はまだ表示されます。この値をサーバーの現在の値に合せるには、contentDelivery属性をlazyUncachedに設定します。

- animate: アニメーションを有効にするには、trueを選択します。アニメーションは、trinidad-config.xmlファイルの構成およびスキン・プロパティ(詳細は、A.6.2.1項「アニメーションの有効化」を参照)によって決定されます。この設定は、falseを選択することでオーバーライドできます。

- launcherVar: 変数の名前(sourceなど)を入力します。表のvar属性と同様、この変数は、showPopupBehaviorタグを含むコンポーネントに対するリクエスト・スコープの参照を格納するのに使用されます。この変数は、popupまたはその子コンポーネントでのイベント配信中で、eventContextがlauncherに設定されている場合にのみ到達可能です。

- eventContext: 表で選択した行の情報がポップアップ内のウィンドウに表示される場合など、ポップアップが複数のオブジェクトで共有されている場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーのコール前にクリックした行が最新の状態になり、その行のデータのみが返されます。詳細は、13.2.5項「実行時の処理: popupコンポーネント・イベント」を参照してください。

- popupCancelListener: ウィンドウが閉じられたときに起動するロジックでハンドラに評価されるEL式に設定します。

3. オプションで、自動取消し動作を決定するには、プロパティ・インスペクタで「その他」セクションを開き、autoCancelプロパティの値を設定します。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

4. コンポーネント・パレットの「レイアウト」パネルから、「パネル・ウィンドウ」をpopupコンポーネントの直接の子としてドラッグ・アンド・ドロップします。

5. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- modal: ウィンドウをモーダルにするかどうかを選択します。モーダル・ウィンドウでは、ウィンドウが閉じられるまでメイン・ページに戻ることはできません。

- closeIconVisible: 「閉じる」アイコンをウィンドウに表示するかどうかを選択します。

- title: ウィンドウにタイトルとして表示されるテキスト。

- resize: ダイアログのサイズ変更をユーザーに許可するかどうかを選択します。デフォルトはoffです。

- stretchChildren: ウィンドウを埋めるために子コンポーネントを拡大するかどうかを選択します。firstに設定されている場合、ウィンドウは1つの子コンポーネントを拡大します。ただし、拡大できる子コンポーネントであることが必要です。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

注意:

resizeをonまたはstretchChildrenをfirstに設定する場合は、contentWidthおよびcontentHeightも設定する必要があります(手順6を参照)。それ以外の場合、サイズはデフォルトで250x250ピクセルになります。

6. ウィンドウに固定サイズを設定する場合、またはresizeをonまたはstretchChildrenをfirstに設定している場合は、「その他」セクションを開き、次の属性を設定します。

- contentHeight: 目的の高さをピクセルで入力します。

- contentWidth: 目的の幅をピクセルで入力します。

ヒント:

ユーザーは実行時に、これらの属性の値を変更できますが(resize属性がonに設定されている場合)、アプリケーションが変更の永続性を使用するように構成されていないかぎり、ユーザーがページを終了すると値は保持されません。変更の永続性の有効化および使用方法の詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

注意:

showPopupBehaviorタグのないコマンド・コンポーネントがダイアログの起動に使用されており、そのコンポーネントにwindowHeightおよびwindowWidth属性の値がある場合、コマンド・コンポーネントの値によってcontentHeightおよびcontentWidthの値がオーバーライドされます。showPopupBehaviorタグの詳細は、13.4「ポップアップ要素の起動」を参照してください。

7. コンポーネントを挿入して、ウィンドウのデータを表示または収集します。コンポーネントを含めるには、panelGroupLayoutなどのレイアウト・コンポーネントを使用します。

8. 親ページのロジックを追加し、ポップアップおよびパネル・ウィンドウを起動します。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

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

ポップアップ・メニューは、ポップアップ・コンポーネント内のメニュー・コンポーネントを使用して作成します。次に、指定のトリガーに基づいて、別のコンポーネントからポップアップ・メニューのポップアップを起動できます。かわりに、ツールバーのツールバー・ボタンでポップアップ・メニューを起動する場合は、14.3項「ツールバーの使用方法」を参照してください。

インライン・ポップアップ・メニューを作成する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「ポップアップ」をドラッグ・アンド・ドロップします。

ヒント:

ポップアップ・コンポーネントがページのどの場所に表示されるかは、ポップアップの起動に使用されるコンポーネントで導かれるため、これは重要ではありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- contentDelivery: コンテンツがポップアップ内のコンポーネントにどのように配信されるかを決定します。

- animate: アニメーションを有効にするには、trueを選択します。アニメーションは、trinidad-config.xmlファイルの構成およびスキン・プロパティ(詳細は、A.6.2.1項「アニメーションの有効化」を参照)によって決定されます。この設定は、falseを選択することでオーバーライドできます。

- launcherVar: 起動コンポーネントの参照に使用する変数名(sourceなど)を入力します。この変数は、popupまたはその子コンポーネントでのイベント配信中で、eventContextがlauncherに設定されている場合にのみ到達可能です。

- eventContext: 表で選択した行の情報がポップアップ内のメニューに表示される場合など、ポップアップが複数のオブジェクトで共有されている場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーのコール前にクリックした行が最新の状態になり、その行のデータのみが返されます。詳細は、13.2.5項「実行時の処理: popupコンポーネント・イベント」を参照してください。

3. オプションで、自動取消し動作を決定するには、プロパティ・インスペクタで「その他」セクションを開き、autoCancelプロパティの値を設定します。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

4. コンポーネント・パレットから「メニュー」をpopupコンポーネントの直接の子としてドラッグ・アンド・ドロップし、14.2.1項「メニュー・バーのメニューの作成および使用方法」の手順6からの説明に従って、commandMenuItemコンポーネントを使用してメニューをビルドします。

ヒント:

これはポップアップ・メニューのため、14.2.1項「メニュー・バーのメニューの作成および使用方法」の手順1から5の説明に従って、メニュー・バーや複数のメニューを作成する必要はありません。

5. 親ページのロジックを追加し、ポップアップおよびポップアップ・メニューを起動します。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

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

読取り専用のテキストを表示するには、noteWindowコンポーネントを使用します。noteWindowコンポーネントを含むpopupコンポーネントは、formコンポーネント内に含まれる必要があります。

インライン・ウィンドウを作成する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「ポップアップ」をドラッグ・アンド・ドロップします。

ヒント:

ポップアップ・コンポーネントがページのどの場所に表示されるかは、ポップアップの起動に使用されるコンポーネントで導かれるため、これは重要ではありません。ただし、popupコンポーネントはformコンポーネント内にある必要があります。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

- contentDelivery: コンテンツがポップアップ内のコンポーネントにどのように配信されるかを決定します。

- animate: アニメーションを有効にするには、trueを選択します。アニメーションは、trinidad-config.xmlファイルの構成およびスキン・プロパティ(詳細は、A.6.2.1項「アニメーションの有効化」を参照)によって決定されます。この設定は、falseを選択することでオーバーライドできます。

- launcherVar: 起動コンポーネントの参照に使用する変数を入力します。この変数は、popupまたはその子コンポーネントでのイベント配信中で、eventContextがlauncherに設定されている場合にのみ到達可能です。

- eventContext: 表で選択した行の情報がポップアップ内のウィンドウに表示される場合など、ポップアップが複数のオブジェクトで共有されている場合は、launcherに設定します。この属性をlauncherに設定すると、イベント・リスナーのコール前にクリックした行が最新の状態になり、その行のデータのみが返されます。詳細は、13.2.5項「実行時の処理: popupコンポーネント・イベント」を参照してください。

- popupCancelListener: ウィンドウが閉じられたときに起動するロジックでハンドラに評価されるEL式に設定します。

3. オプションで、自動取消し動作を決定するには、プロパティ・インスペクタで「その他」セクションを開き、autoCancelプロパティの値を設定します。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

4. コンポーネント・パレットから、「ノート・ウィンドウ」をpopupコンポーネントの直接の子としてドラッグ・アンド・ドロップします。

5. ウィンドウに表示するテキストを入力する手順:

1. 「ソース」タブをクリックし、ページ・ソース・コードを表示します。

2. 閉じスラッシュ(/)をaf:noteWindowタグから削除します。

3. シンプルHTMLタグを使用して、af:noteWindowタグの下に表示するテキストを入力し、af:noteWindow閉じタグで終了します。

例13-3に、ノート・ウィンドウのテキストを示します。

例13-3 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>

図13-3に、ノートがどのように表示されるかを示します。

図13-3 ノート・ウィンドウに表示されるテキスト

6. オプションで、プロパティ・インスペクタで「その他」セクションを開き、AutoDismissalTimeoutプロパティに秒数を指定します。指定する値により、アプリケーションによってノート・ウィンドウが自動的に閉じられるまでに表示される秒数が決定されます。指定した値によって、デフォルトの自動消去動作がオーバーライドされます。このオーバーライドは、エンド・ユーザーがノート・ウィンドウのコンテンツの上にマウスを移動すると、取り消されますが、これは、この操作により、自動消去動作がノート・ウィンドウのデフォルトの自動消去動作に戻るためです。デフォルトの自動消去動作では、フォーカスが起動元またはポップアップのコンテンツから変更されると、ノート・ウィンドウが閉じられます。

注意:

タイムアウト取消し期間はマウスを置くことでトリガーされ、キーボードの同等の操作は用意されていないため、このプロパティで有効化されたこの機能は使い勝手がよいとは言えません。

7. 親ページのロジックを追加し、ポップアップおよびノート・ウィンドウを起動します。詳細は、13.4項「ポップアップ要素の起動」を参照してください。

13.2.5 実行時の処理: ポップアップ・コンポーネント・イベント

コンテンツがポップアップに配信され、contentDelivery属性がlazyまたはlazyUncachedのいずれかに設定されている場合は、popupFetchサーバー側イベントが起動されます。このイベントには、eventContextとlauncherVarの2つのプロパティがあります。eventContextプロパティでは、ポップアップのコンテキスト(self)またはポップアップを起動したコンポーネント(launcher)から、イベントの配信元のコンテキストを決定します。コンテキストをlauncherに設定することは、ポップアップが複数のコンポーネントで共有されている場合に非常に有効ですが、これは、ポップアップを起動したコンポーネントがポップアップではなく、イベントを起動したかのようにように、フレームワークが動作するためです。launcherVarプロパティは、変数が表内の行のスタンプ設定に使用されるのと同様の方法で、現在のランチャの追跡に使用されます。

たとえば、コマンド・リンクを使用して個人の名前を表示する表の列があるとします。コマンド・リンクにカーソルを合せると、個人の氏名を表示するポップアップnoteWindowが起動されます。このnoteWindowは、表のすべての行で使用されますが、クリックしたコマンドリンクを含む行にのみ氏名を表示する必要があるため、eventContextプロパティを使用して、例13-4に示すように、コンテキストがその行になるようにします。

例13-4 共有ポップアップ要素での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:commandLink text="#{person.firstName}">
<af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/>
</af:commandLink>
</af:column>
</af:table>

変数ソースを使用すると、ソースから値を取得して適用したり、値を設定したりできます。たとえば、表で使用されるpeopleオブジェクトの氏名の値を取得し、例13-5に示すように、setPropertyListenerおよびclientAttributeタグを使用して、ウィンドウで使用されるtestBeanのfullNameプロパティの値として設定できます。

例13-5 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:commandLink text="#{person.firstName}">
<af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/>
<af:clientAttribute name="fullName" value="#{person.fullName}"/>
</af:commandLink>
</af:column>
</af:table>

この例では、launcherVarプロパティ・ソースは、popupFetchイベントを使用して、現在の行の氏名を取得します。setPropertyListenerタグの使用の詳細は、4.7.2項「Javaコードを記述せずにpageFlowScopeスコープを使用する方法」を参照してください。クライアント属性の使用の詳細は、3.8項「クライアント側コンポーネントに対するボーナス属性の使用」を参照してください。showPopupBehaviorタグの詳細は、13.4項「ポップアップ要素の起動」を参照してください。

ポップアップでは、次のクライアント側イベントも起動します。

- popupOpening: ポップアップが起動されると、開始されます。このイベントがクライアント側のリスナーで取り消されると、ポップアップは表示されません。

- popupOpened: ポップアップが表示可能になった後、起動されます。このイベントの使用例には、ポップアップ内デフォルトのフォーカスをオーバーライドする、カスタムのルール作成があります。

- popupCanceled: 自動消去やポップアップ・クライアント・コンポーネントのcancelメソッドの明示的な起動によってポップアップが予期せずに閉じると、起動します。このクライアント側イベントには、対応するサーバー側イベントもあります。

- popupClosed: ポップアップが非表示になるか、ポップアップが予期せずに閉じられると、起動します。このクライアント側イベントには、対応するサーバー側イベントもあります。

「はい」ボタンがクリックされた場合など、ポップアップが肯定条件によって閉じられると、非表示になります。「閉じる」アイコンや「取消」ボタンがクリックされた場合など、ポップアップが自動消去によって閉じられると、取り消されます。どちらのタイプの消去でも、popupClosedクライアント側イベントが発生します。ポップアップを取り消すと、関連するサーバー側イベントを持つクライアント側popupCanceledイベントが発生します。このイベントは、イベントに登録されているリスナーがないかぎり、サーバーに伝播されません。伝播されると、ポップアップの子コンポーネントの処理ができなくなり、送信された値および検証が無視されます。ポップアップが取り消された場合に必要な処理を実行するロジックを含むpopupCanceledイベントのリスナーを作成できます。

クライアント側のイベントに基づいて一部のロジックを起動する場合は、カスタムのクライアント・リスナー・メソッドを作成できます。詳細は、3.2項「クライアント・イベントのリスニング」を参照してください。クライアント・イベントに基づいてサーバー側ロジックを起動する場合は、そのロジックを起動するserverListenerタグを追加できます。詳細は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

13.3 プログラムによるポップアップの起動

コマンド・コンポーネントによって生成されるactionEventに対して、ポップアップをプログラムで表示、非表示または取り消すことができます。この機能は、actionEventをサーバーにすぐに配信する場合に実行するため、サーバー側ロジックを起動して、サーバー側ロジックの起動結果に対してポップアップを表示、非表示または取り消すことができます。

ここで説明するプログラムによるポップアップの起動は、13.2項「ポップアップ要素の宣言的作成」で説明するポップアップの起動方法(showPopupBehaviorタグではactionEventがサーバーにすぐに配信されません)と異なります。

13.2項「ポップアップ要素の宣言的作成」の説明に従い、コンポーネントのいずれか(dialog、panelWindow、menuまたはnoteWindow)をpopupコンポーネント内に配置して、必要なポップアップのタイプを作成します。popupコンポーネントを起動する場合は、適切なコンテキストになるようにする必要があります。これを行う簡単な方法の1つは、例13-6のように、ページのバッキングBeanにバインドします。

例13-6 バッキングBacking Beanへのpopupコンポーネントのバインド

<af:popup id="p1"
binding="#{mybean.popup}"
...
/>

これを実行したら、ポップアップ・バインディングのアクセッサをコールし、コマンド・コンポーネントのactionListener属性を構成して、popupコンポーネントを参照します。

ポップアップを起動、取消し、非表示にするバッキングBeanメソッドのコードを記述します。例13-7に、HINT_LAUNCH_IDヒントを使用して、actionEventが渡されるコマンド・コンポーネントを識別し、p1を使用して、showメソッドを起動するポップアップを参照するshowPopupバッキングBeanメソッドを示します。

例13-7 ポップアップを起動するバッキング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);
}

例13-8に、actionEventに対してポップアップを取り消すバッキングBeanメソッドを示します。

例13-8 ポップアップを取り消すバッキングBeanメソッド

public void cancelPopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.cancel();
}

例13-9に、actionEventに対してpopupを非表示にするバッキングBeanメソッドを示します。

例13-9 ポップアップを非表示にするバッキングBeanメソッド

public void hidePopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.hide();
}

前述の例のp1オブジェクトは、次のパッケージからRichPopupクラスのインスタンスを参照します。

oracle.adf.view.rich.component.rich.RichPopup

RichPopupの詳細は、Oracle Fusion Middleware Java APIリファレンス for Oracle ADF Facesを参照してください。

13.3.1 プログラムによるポップアップの起動方法

ポップアップを表示、取消しまたは非表示にするバッキングBeanメソッドを参照するには、コマンド・コンポーネントのactionListener属性を構成します。

作業を始める前に、次のようにします。

13.2項「ポップアップ要素の宣言的作成」の説明に従い、サーバー側メソッドで起動するポップアップのタイプを作成します。

ポップアップ・コンポーネントをプログラムで起動する場合は、利用可能な構成オプションについて理解しておくと役立ちます。詳細は、13.3項「プログラムによるポップアップの起動」を参照してください。

プログラムでポップアップを起動する手順:

1. コンポーネント・パレットの「一般コントロール」パネルから、JSFページにコマンド・コンポーネントをドラッグ・アンド・ドロップします。

たとえば、「ボタン」コンポーネントです。

2. プロパティ・インスペクタで、「動作」セクションを開いて次の属性を設定します。

- partialSubmit: エンド・ユーザーがコマンド・コンポーネントをクリックした後に、Fusion Webアプリケーションでページ全体をレンダリングしない場合は、trueに設定します。デフォルト値(false)では、エンド・ユーザーがコマンド・コンポーネントを起動した後に、ページ全体がアプリケーションでレンダリングされます。ページのレンダリングの詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

- actionListener: エンド・ユーザーが実行時にコマンドコンポーネントを起動したときに、実行するロジックでバッキングBeanメソッドに評価されるEL式に設定します。

3. 手順1のコマンド・コンポーネントでactionEventが渡されたときに、起動されるバッキングBeanのロジックを記述します。
詳細は、例13-7「ポップアップを起動するバッキングBeanメソッド」、例13-8「ポップアップを取り消すバッキングBeanメソッド」または例13-9「ポップアップを非表示にするバッキングBeanメソッド」を参照してください。

13.3.2 プログラムでポップアップの起動する場合の処理

実行時に、エンド・ユーザーは、サーバ側メソッドを起動するように構成したコマンド・コンポーネントを起動して、ポップアップを表示、取消しまたは非表示にできます。たとえば、図13-4は、popupコンポーネント内部でレンダリングされるpanelWindowコンポーネントを示しています。これは、2つのコマンド・ボタン(「取消」および「非表示」)を公開し、cancelおよびhideメソッドをそれぞれ起動します。エンド・ユーザーは、基礎となるページでtableコンポーネントのSupplierName列にレンダリングされるcommandLinkコンポーネントを起動して、ポップアップを表示します。

図13-4 サーバー側メソッドで起動されるポップアップ・コンポーネント

13.4 ポップアップ要素の起動

ADF Facesリッチ・クライアントのコンポーネントでは、ポップアップの表示または非表示にJavaScriptは不要です。showPopupBehaviorクライアントの動作タグには、宣言的ソリューションが用意されているため、ポップアップを開いたり、スクリプトをコンポーネントに登録するためのJavaScriptを記述する必要はありません。クライアントの動作タグの詳細は、5.6項「クライアントの動作タグの使用」を参照してください。

showPopupBehaviorタグでは、コマンド・コンポーネントのactionEventやshowDetailコンポーネントのdisclosureEventなど、指定したイベントをリスニングします。ただし、showPopupBehaviorタグでは、そのイベントをサーバーに配信する処理も取り消します。したがって、showPopupBehaviorタグがリスニングしているイベントに基づいて、一部のサーバ側ロジックを起動する必要がある場合は、JavaScriptを使用してポップアップを起動するか、5.4項「クライアントからサーバーへのカスタム・イベントの送信」の説明に従ってカスタム・イベントを使用する必要があります。

13.4.1 af:showPopupBehaviorタグの使用方法

showPopupBehaviorタグと、ポップアップ要素を起動するコンポーネント(ダイアログを起動するcommandButtonコンポーネントや、右クリックしたときにポップアップ・メニューを起動するinputTextコンポーネントなど)を組み合せて使用します。

作業を始める前に、次のようにします。

1. ポップアップ・コンポーネントとそのホルダを作成します。

2. ポップアップを起動するコンポーネントを作成します。

showPopupBehaviorタグを使用する手順:

1. コンポーネント・パレットの「操作」パネルから、「ポップアップ表示動作」を、ポップアップ要素の起動に使用されるコンポーネントの子としてドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、PopupId属性のドロップダウン・メニューを使用して、「編集」を選択します。「プロパティの編集: PopuId」ダイアログを使用して、起動するポップアップ・コンポーネントを選択します。

3. 「トリガー・タイプ」ドロップダウン・メニューから、ポップアップを起動するトリガーを選択します。デフォルトはactionで、コマンド・コンポーネントに使用できます。右クリックしたときにポップアップをトリガーするには、contextMenuを使用します。カーソルをコンポーネントの上に置いたときにポップアップをトリガーするには、mouseHoverを使用します。カーソルをコンポーネントから離すと、ポップアップは閉じます。ポップアップをトリガーできるコンポーネントおよびマウス/キーボード・イベントの詳細なリストは、showPopupBehaviorタグのドキュメントを参照してください。

注意:

triggerType属性に選択されるイベントは、サーバーに配信されません。このイベントに基づいて、サーバ側ロジックを起動する必要がある場合は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」の説明に従い、JavaScriptまたはカスタム・イベントを使用してポップアップを起動する必要があります。

4. AlignIdドロップダウンから、「編集」を選択し、「プロパティの編集: AlignId」ダイアログを使用して、ポップアップの位置合せに使用するコンポーネントを選択します。

5. 「位置」ドロップダウン・メニューから、前述の手順で選択したコンポーネントに対するポップアップの相対的な位置を選択します。

注意:

dialogおよびpanelWindowコンポーネントでは、対応するポップアップがユーザーによって移動可能なため、alignIdまたはalign属性は不要です。alignIdを設定すると、手動のドラッグ・アンド・ドロップによるダイアログまたはウィンドウの再配置によって値がオーバーライドされます。AlignIdまたは「位置」に値が入力されていない場合、ダイアログまたはウィンドウはブラウザの中央で開きます。

また、triggerType属性がcontextMenuに設定されている場合、位置合せは常にマウスの位置に基づきます。

例13-10に、ボタン「Click me」がクリックされると、popup1というIDのaf:popupコンポーネントにテキストが表示されるサンプル・コードを示します。

例13-10 commandButtonコンポーネントに関連付けられたshowPopupBehavior

<af:commandButton text="Click me" id="button">
<af:showPopupBehavior popupId="popup1" alignId="button" align="afterEnd"/>
</af:commandButton>

<af:popup id="popup1">
<af:panelGroupLayout layout="vertical">
<af:outputText value="Some"/>
<af:outputText value="popup"/>
<af:outputText value="content"/>
</af:panelGroupLayout>
</af:popup>

例13-10のコードでは、ポップアップ・コンテンツがbuttonというIDで識別されるcommandButtonと位置合せされ、afterEndの位置合せを使用して、図13-5に示すように、ポップアップ要素がボタンの下に配置されます。

図13-5 ボタンおよびポップアップ・コンテンツ

13.5 コンテキスト情報の表示

ページのタスクを完了するのに、ユーザーが詳しい情報を必要としていると考えられるケースがありますが、ページにアクセスするたびに、不必要な情報や、ダイアログを起動して情報を表示する複数のボタンでページを乱雑にしたくなとも考えています。コンポーネントを右クリックして起動したポップアップ要素に情報を配置できますが、その情報をポップアップで利用できるかを知る方法はありません。

contextInfoコンポーネントを使用すると、ポップアップ要素に追加情報を表示し、その追加情報が利用可能であることをユーザーに通知します。contextInfoコンポーネントを、コンテキスト情報をサポートするコンポーネントのコンテキスト・ファセットに配置すると、図13-6に示すように、オレンジ色の小さい正方形がコンポーネントの左上隅に表示されます。

図13-6 正方形が表示されたcontextInfo

ユーザーがカーソルを正方形の上に置くと、図13-7に示すように、ノート・アイコンとツールチップが付いた大きい三角形が表示され、追加情報が利用可能であることが示されます。

図13-7追加情報が利用可能であることを示すcontextInfoコンポーネント

showPopupBehaviorタグはcontextInfoコンポーネントの子のため、図13-8に示すように、ユーザーが情報アイコンをクリックすると、参照されているポップアップが表示されます。

図13-8 contextInfoコンポーネントから起動されたダイアログ

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

showPopupBehaviorコンポーネントをcontextInfoコンポーネントの子として使用することにより、ポップアップコンポーネントと、contextInfoコンポーネントを含むコンポーネントを位置合せできます。

作業を始める前に、次のようにします。

1. contextInfoコンポーネントの親となるコンポーネントを作成します。次のコンポーネントは、contextInfoコンポーネントをサポートしています。

- column

- commandLink

- inputComboboxListOfValues

- inputListOfValues

- inputText

- outputFormatted

- outputText

- selectOneChoice

2. 13.2項「ポップアップ要素の宣言的作成」の説明に従って、表示するポップアップ要素を作成します。

contextInfoコンポーネントを使用する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、追加情報のアイコンを表示するコンポーネントのContextファアセットに、「コンテキスト情報」をドラッグ・アンド・ドロップします。

ヒント:

ファセットがビジュアル・エディタに表示されない場合は、次のようにします。

1. 構造ウィンドウで、outputTextコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - コンポーネント名」→「コンテキスト」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

2. contextInfoコンポーネントが表示されたときに、サーバ側ロジックで実行する必要がある場合は、イベントを処理できるハンドラにcontextInfoListener属性をバインドします。

注意:

showPopupBehaviorタグを使用してポップアップを起動すると、サーバーへのcontextInfoEventの配信が取り消されます。このイベントに基づいて、サーバ側ロジックを起動する必要がある場合は、5.4項「クライアントからサーバーへのカスタム・イベントの送信」の説明に従い、JavaScriptまたはカスタム・イベントを使用してポップアップを起動する必要があります。

3. コンポーネント・パレットの「操作」パネルから、「ポップアップ表示動作」をcontextInfoコンポーネントの子としてドラッグ・アンド・ドロップします。

4. showPopupBehaviorタグをエディタで選択し、13.4.1項「af:showPopupBehaviorタグの使用方法」の説明に従って、プロパティ・インスペクタで属性を設定します。triggerType値の場合は、contextInfoを入力します。

13.6 インライン・ポップアップの自動取消しの制御

af:popupコンポーネントと他のいくつかのコンポーネントを使用すると、インライン・ポップアップを作成できます。つまり、インライン・ウィンドウ、ダイアログおよびポップアップ・メニューです。その他のコンポーネントには次のものがあります。

- インライン・ダイアログを作成するためのダイアログ・コンポーネント
詳細は、13.2.1項「ダイアログの作成方法」を参照してください。

- インライン・ウィンドウを作成するためのpanelWindowコンポーネント
詳細は、13.2.2項「パネル・ウィンドウの作成方法」を参照してください。

- ポップアップ・メニューを作成するためのメニュー・コンポーネント
詳細は、13.2.3項「ポップアップ・メニューの作成方法」を参照してください。

- ノート・ウィンドウを作成するためのnoteWindowコンポーネント
詳細は、13.2.4項「ノート・ウィンドウの作成方法」を参照してください。

デフォルトでは、インライン・ポップアップを定義するメタデータが置き換えられると、Fusion Webアプリケーションによってインライン・ポップアップが自動的に取り消されます。これが発生するシナリオは次のとおりです。

- partialSubmitプロパティがfalseに設定されているコマンド・コンポーネントの起動。このようなコマンド・コンポーネントが起動されると、Fusion Webアプリケーションによってページ全体がレンダリングされます。、これに対し、partialSubmitプロパティがtrueに設定されているコマンド・コンポーネントでは、Fusion Webアプリケーションによって一部のコンテンツがレンダリングされます。ページのレンダリングの詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

- エンド・ユーザーがコンテンツの表示と非表示を切り替えるためのアイコンをレンダリングするコンポーネントは、popupコンポーネントをホストします。例として、showDetailItemおよびpanelTabbedコンポーネントなどがあります。切替えアイコンをレンダリングするコンポーネントの使用の詳細は、8.8項「コンテンツの動的な表示および非表示」を参照してください。

- Fusion Webアプリケーションでインライン・ポップアップが表示されると、フェイルオーバーが発生します。フェイルオーバー時には、Fusion Webアプリケーションによってページ全体が置き換えられます。

インライン・ポップアップ・コンポーネントの自動取消しを無効にすることで、前述のリストに記載されているデフォルトの動作を変更できます。つまり、Fusion Webアプリケーションでは、前述のイベントが発生した場合に、インライン・ポップアップを自動的に取り消しません。かわりに、Fusion Webアプリケーションではインライン・ポップアップをリストアします。

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

インライン・ポップアップの自動取消しは、popupコンポーネントのautoCancelプロパティをdisabledに設定して無効にします。

作業を始める前に、次のようにします。

他のコンポーネントが機能に与える影響について理解しておくと役立ちます。詳細は、13.6項「インライン・ポップアップの自動取消しの制御」を参照してください。

インライン・ポップアップの自動取消しを制御する手順:

1. 構造ウィンドウで、自動取消し動作を構成するaf:popupコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「その他」セクションを開き、autoCancelプロパティのドロップダウン・メニューを使用して、disabledを選択します。

13.6.2 インライン・ポップアップの自動取消しを無効にする場合の処理

JDeveloperでは、例13-11に示すように、af:popupコンポーネントのautoCancelプロパティの値をdisabledに設定します。

例13-11 インライン・ポップアップの自動取消しを無効にするメタデータ

<af:popup id="p1" autoCancel="disabled">
...
</af:popup>

実行時、コマンドを起動してページを再レンダリングする前に、インライン・ポップアップが表示されると、ページのレンダリング後に、Fusion Webアプリケーションによってインライン・ポップアップがリストアされます。

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

この章では、ツール・ボタンを含むメニュー・バーおよびツールバーの作成方法を説明します。

ナビゲーション・メニュー(ページの階層から移動できるメニュー)の詳細は、18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

この章では、次の項目について説明します。

- 14.1項「メニュー、ツールバーおよびツールボックスの概要」

- 14.2項「メニュー・バーでのメニューの使用方法」

- 14.3項「ツールバーの使用方法」

14.1 メニュー、ツールバーおよびツールボックスの概要

ユーザーは、メニューやツールバーを使用して、指定されたオプションのリスト(メニューの場合)から選択したり、ボタン(ツールバーの場合)をクリックしてアプリケーションの変更を実行したりできます。図14-1に示すように、File Explorerアプリケーションには、メニュー・バーとツールバーの両方があります。

図14-1 File Explorerアプリケーションのメニュー・バーおよびツールバー

図14-2に示すように、ユーザーがメニュー・バーのメニュー項目を選択すると、menuコンポーネントにより、メニュー項目のリストが表示されます。

図14-2 File Explorerアプリケーションのメニュー

図14-3に示されているように、メニューはネスト可能です。

図14-3 ネストしたメニュー項目

ツールバーのボタンにより、一部のアクションを起動したり、標準のメニューと同じように動作するポップアップ・メニューを開こともできます。

ツールバーおよびメニュー・バーは、ツールボックスを使用して編成できます。ツールボックスを使用すると、同じ行にあるツールバーの相対的なサイズや、複数レイヤーのツールバーおよびメニュー・バーを垂直方向に定義できます。

注意:

表にメニューおよびツールバーを作成する場合は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」に説明されている手順に従ってください。

コンポーネントのポップアップ・メニュー(コンポーネントを右クリックすると起動するメニュー)を作成する場合は、13.2.3項「ポップアップ・メニューの作成方法」に説明されている手順に従ってください。

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

メニュー・バー項目(File Explorerアプリケーションの「ファイル」など)を含むバーのレンダリングには、menuBarコンポーネントを使用します。メニュー・バーの各項目は、垂直のメニューが配置されるmenuコンポーネントによりレンダリングされます。垂直の各メニューには、アプリケーションの操作を起動できるcommandMenuItemコンポーネントのリストが含まれます。メニュー・コンポーネント内にメニュー・コンポーネントをネストさせて、サブメニューを作成できます。図14-4に、メニューの作成に使用されている様々なコンポーネントを示します。

図14-4メニューの作成に使用されているコンポーネント

toolboxで囲むことにより、複数のメニュー・バーを使用できます。これらをtoolboxで囲むことにより、メニュー・バーが積み重なり、toolboxの最初のメニュー・バーが上に表示され、最後のメニュー・バーが下に表示されます。単一のtoolbox行に複数のメニューを使用する場合(toolbox内にグループ化する)は、どのメニュー・バーに最も領域を使用するかをflex属性で決定します。

メニュー・バーを(縦ではなく)横に並べて表示する場合は、groupコンポーネント内に配置します。

ヒント:

toolboxコンポーネントを使用して、メニュー・バーとツールバーをグループ化することや、複数のメニュー・バーをグループ化することが可能です。同じ行のメニュー・バーとツールバーをグループ化するには、groupコンポーネントを使用します。

メニュー・バー内では、メニュー・バーがその親コンテナと常に同じ大きさになるように、1つのコンポーネントを拡大するよう設定できます。たとえば、図14-5では、無効なGMIメニューおよびコンポーネント・ガイドボタンの間に配置されているspacerコンポーネントを拡大するようにメニュー・バーが設定されています。ウィンドウのサイズが変更されると、メニュー・バーが常に親と同じ幅になるように、spacerコンポーネントが拡大または縮小します。このようなspacerコンポーネントを使用することにより、spacerの右側のコンポーネントはメニューバー内で右に揃えられます。

図14-5 spacerコンポーネントの拡大および縮小

メニュー・バー内のすべてのコンポーネントが表示できないようなサイズにウィンドウが変更された場合は、図14-6の矢印カーソルで示すように、オーバーフロー・アイコンが表示されます。

図14-6 メニュー・バーのオーバーフロー・アイコン

オーバーフロー・アイコンをクリックすると、図14-7に示すように、残りのコンポーネントがポップアップ・ウィンドウに表示されます。

図14-7 オーバーフロー・ポップアップ・ウィンドウ内のmenuコンポーネント

メニューおよびサブメニューは、ブラウザ・ウィンドウ上で連結解除して移動できるように設定できます。図14-8に、連結解除できるように構成された「ファイル」メニューの「新規作成」サブメニューを示します。メニューの上部には、連結解除が可能であることを示すバーがレンダリングされています。

図14-8 連結解除可能メニュー

ユーザーは、連結解除可能メニューをブラウザ内の任意の場所にドラッグできます。図14-9に示すように、マウス・ボタンを離すと、そのメニューはユーザーが閉じるまでアプリケーション上に残ります。

図14-9 移動している連結解除可能メニュー

ヒント:

ユーザーが次の操作をする可能性がある場合は、連結解除可能メニューの使用を検討してください。

- ページで類似のコマンドを繰り返し実行する場合。

- 大規模な表、ツリー表またはツリーにおいて、異なる行のデータで類似のコマンドを実行する場合。

- 長くて幅の広い表やツリー表、またはツリーでデータを表示する場合。ユーザーは一度クリックすることで、表示または非表示にする列やブランチを選択できます。

- 長くて幅の広い表、ツリー表またはツリーでデータを書式設定する場合。

menuおよびcommandMenuItemコンポーネントのそれぞれに、アイコン・イメージを含めることができます。図14-10に、削除アイコンを表示するよう構成された「削除」メニュー項目を示します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用します。このアイコンの意味は、アクセシビリティが確保された方法で指定する必要があります。

図14-10 メニューで使用されているアイコン

commandMenuItemコンポーネントは、メニュー項目が選択された際の表示を変更できる特別なタイプに構成できます。たとえば、項目が選択された際に、ラベルの隣にチェックマークまたはラジオ・ボタンが表示されるようにcommandMenuItemコンポーネントを構成できます。図14-11に、選択時にチェックマークを使用するよう構成された「フォルダ」メニュー項目を含む「表示」メニューを示します。「表」、「ツリー表」および「リスト」メニュー項目はラジオ・ボタンとして構成されており、ユーザーは1つのグループのみ選択できます。

図14-11 選択されたメニュー項目を示す四角形アイコンおよびラジオ・ボタン

commandMenuItemコンポーネントは、反意語を含むように構成することもできます。反意語は、ユーザーがメニュー項目を選択すると別のテキストを表示します。図14-12に、(この例のFile Explorerアプリケーションに追加された)「編集」メニューの「元に戻す」メニュー項目を示します。

図14-12 File Explorerアプリケーションの「編集」メニュー

「元に戻す」メニュー項目のcommandMenuItemコンポーネントが反意語になり、代替テキストが表示されるようにように構成することで、ユーザーが「元に戻す」を選択して、メニューに戻ると、図14-13に示すように、メニュー項目に反意語「リストア」が表示されます。

図14-13 反意語のメニュー項目

ユーザーがメニュー項目を選択するとアクションが発生するため、commandMenuItemコンポーネントのactionまたはactionListener属性を、必要な機能を実行するメソッドにバインドする必要があります。

メニューには、commandMenuItemコンポーネントの他、1つ以上のgoMenuItemコンポーネントを含めることもできます。ActionEventイベントを配信せずにページ・ナビゲーションを直接実行するという点で、goLinkコンポーネントと似ているナビゲーション・コンポーネントがあります。図14-14に、外部のwebサイトにナビゲートするために使用される3つのgoMenuItemコンポーネントを示します。

図14-14 goMenuItemコンポーネントを使用できるメニュー

メニュー・バーから起動されるメニューのみでなく、ユーザーがUIコンポーネントを右クリックした場合や、ユーザーがコマンド・コンポーネントをクリックした場合に起動されるポップアップ・メニューも作成できます。詳細は、13.2.3項「ポップアップ・メニューの作成方法」を参照してください。

注意:

ADF Facesには、ユーザーが現行ページの印刷可能バージョンを表示できる埋込み機能を持つボタンが用意されています。メニューおよびメニュー・バーは、これらのページにはレンダリングされません。詳細は、5.6項「クライアントの動作タグの使用」を参照してください。

デフォルトで、メニューのコンテンツは、ページがレンダリングされるとすぐに送信されます。メニューに多数の子(複数のmenuおよびcommandMenuItemコンポーネント)を作成する予定の場合は、コンテンツの遅延配信を使用するようメニューを構成できます。これは、メニューがアクセスされるまで、子コンポーネントがサーバーから取得されないことを意味します。

注意:

ポップアップ・メニューとして使用されるメニューのコンテンツ配信は、メニュー自体ではなく、親のポップアップ・ダイアログにより決定されます。

主にアプリケーション全体におけるナビゲーションを可能にするメニューで、アプリケーションの選択項目に対する変更には使用されないメニューも作成できます。このタイプのメニューを作成するには、18.6項「メニュー・モデルを使用したページ階層の作成」を参照してください。

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

メニューを作成するには、まず、メニューが表示されるメニュー・バーを作成する必要があります。その後、必要に応じてmenuおよびcommandMenuItemコンポーネントを追加および構成します。

注意:

表にメニューを作成する場合は、10.8項「表メニュー、ツールバーおよびステータス・バーの表示」に説明されている手順に従ってください。

メニュー・バーのメニューを作成および使用する手順:

1. 複数のメニュー・バーまたはツールバーとメニュー・バーの組合せを使用する場合は、コンポーネント・パレットの「レイアウト」パネルから「ツールボックス」コンポーネントをドラッグ・アンド・ドロップして、toolboxコンポーネントを作成します。

ヒント:

panelHeader、showDetailHeaderおよびshowDetailItemコンポーネントでは、セクション・ヘッダーおよびアコーディオン・パネル・ヘッダーにtoolboxやtoolbarを追加するためのtoolbarファセットがサポートされています。

2. コンポーネント・パレットの「共通コンポーネント」パネルから「パネル・メニュー・バー」をドラッグ・アンド・ドロップして、メニュー・バーを作成します。toolboxコンポーネントを使用している場合は、「パネル・メニュー・バー」をtoolboxコンポーネントの直接の子としてドロップする必要があります。

ヒント:

通常はtoolboxの直接の子である子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、toolboxにもこれらのコンポーネントを直接の子として使用できます。toolboxの詳細は、14.3項「ツールバーの使用方法」を参照してください。

3. toolbox内で複数のメニュー・バーをグループ化する場合は、メニュー・バーごとに「外観」セクションを開き、flex属性を設定して、各メニュー・バーの相対的なサイズを決定します。flex属性に指定された数が大きいほど、toolboxは長くなります。例14-5に示すメニュー・バーのセットでは、menubar2が最も長く、menubar4が次に長くなり、残りのメニュー・バーは、flex属性が設定されていないため、同じサイズでmenubar4よりも短くなります。

例14-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コンポーネントのサイズを設定する必要があります。詳細は、14.3.2項「実行時の処理: メニュー・バーおよびツールバーのサイズの決定」を参照してください。

ヒント:

groupコンポーネントを使用して、同じ行に表示するメニュー・バー(またはメニュー・バーとツールバー)をグループ化できます。groupコンポーネントを使用しない場合、メニュー・バーは次の行に表示されます。

flex属性の機能の詳細は、14.3.2項「実行時の処理: メニュー・バーおよびツールバーのサイズの決定」を参照してください。

4. コンポーネント・パレットから「メニュー」をドラッグし、menuBarコンポーネントの子としてドロップして、メニュー・バーに必要な数だけmenuコンポーネントを挿入します。
「メニュー項目」をドラッグ・アンド・ドロップして、メニュー・バーに直接commandMenuItemコンポーネントを挿入することもできます。これにより、ツールバー・ボタンと同じようにレンダリングされるcommandMenuItemコンポーネントが作成されます。

ヒント:

通常はメニュー・バーの直接の子である子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、メニュー・バーにもこららのコンポーネントを直接の子として使用できます。

5. 各menuコンポーネントに対し、プロパティ・インスペクタの「外観」セクションを開いて、次の属性を設定します。

- text: メニューのラベル・テキストを入力します。アクセス・キー(キーボードを使用してメニューにアクセスする際に使用する文字)も表示する場合は、この属性は空にして、かわりにtextAndAccessKeyに値を入力します。

- textAndAccessKey: 従来のアンパサンド表記を使用して、メニュー・ラベルとアクセス・キーを入力します。たとえば、&amp;Fileではメニュー・ラベルが「File」に設定され、同時に、メニュー・アクセス・キーが文字Fに設定されます。アクセス・キーおよびアンバサンド表記の詳細は、22.3項「コンポーネントレベルのアクセシビリティ・プロパティの指定」を参照してください。

- icon: ドロップダウン・リストを使用して、アイコンを選択します。アイコンがメニューに表示されない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用する必要があります。このアイコンの意味は、アクセシビリティが確保された別の方法で指定する必要があります。

6. メニューを連結解除可能にする場合(図14-8を参照)は、プロパティ・インスペクタで「動作」セクションを開き、detachable属性をtrueに設定します。実行時、ユーザーはメニューをドラッグして連結を解除し、画面の任意の場所にドロップできます(図14-9を参照)。

7. メニューでコンテンツの遅延配信を使用する場合は、プロパティ・インスペクタで「その他」セクションを開き、contentDelivery属性をlazyに設定します。

注意:

コンテンツの遅延配信を使用する場合、メニューのコンテンツはメニューがアクセスされるまで把握されないため、子のcommandMenuItemコンポーネントに設定されているアクセラレータが機能しなくなります。メニューでアクセラレータをサポートする必要がある場合は、contentDeliveryをimmediateに設定しておく必要があります。

注意:

メニューがポップアップ・ダイアログまたはウィンドウ内で使用される場合、ポップアップ・ダイアログまたはウィンドウによりメニューのコンテンツ配信が決定されるため、contentDeliveryはimmediateに設定されたままにします。

8. ナビゲーションとともになんらかのアクションを起動するメニュー項目を作成するには、コンポーネント・パレットから「MenuItem」をmenuコンポーネントの子としてドラッグ・アンド・ドロップし、commandMenuItemコンポーネントを作成します。一連のcommandMenuItemコンポーネントを作成して、垂直メニューの項目を定義します。
必要な場合には、commandMenuItemコンポーネントをgroupコンポーネント内でラップし、項目をグループとして表示できます。例14-2に、「フォルダ」および「検索」メニュー項目を1つ目のグループに、「表」、「ツリー表」および「リスト」メニュー項目を2つ目のグループにグループ化し、「リフレッシュ」メニュー項目を単独で最後に配置するために簡略化されたコードを示します。

例14-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>

図14-15に、メニューがどのように表示されるかを示します。

図14-15 メニューのグループ化されたcommandMenuItemコンポーネント

ヒント:

デフォルトでは、メニューに表示できるのは14項目のみです。メニューに15項目以上追加すると、残りの項目へのアクセスに使用するスクロールバーとともに、最初の14項目が表示されます。表示される項目の数を変更する場合は、af|menu {-tr-visible-items}スキニング・キーを編集します。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

既存のmenuコンポーネントに別のmenuコンポーネントを挿入して、サブメニューを作成できます(図14-3を参照)。

ヒント:

通常はメニューの直接の子である子コンポーネントをiteratorおよびswitcherコンポーネントにラップすれば、メニューにもこれらのコンポーネントを直接の子として使用できます。

9. 各commandMenuItemコンポーネントに対し、プロパティ・インスペクタの「共通」セクションを開いて、次の属性を設定します。

- type: メニュー項目のタイプを指定します。メニュー項目のタイプが指定されると、ADF Facesにより、ビジュアルなインジケータ(ラジオ・ボタンなど)および動作の切替えがメニュー項目に追加されます。実行時に、ユーザーがタイプ(default以外)の指定されたメニュー項目を選択すると、ADF Facesにより、ビジュアルなインジケータまたはメニュー項目ラベルが切り替えられます。次に示す使用可能なtype値のいずれかを使用します。

- check: デフォルトのFusionFXスキンでは、メニュー項目ラベルの隣の四角形を切り替えます。この四角形は、メニュー項目が選択された場合は無地の青で表示され、選択されない場合はグレーで表示されます。

- radio: メニュー項目ラベルの隣のラジオ・ボタンを切り替えます。ラジオ・ボタンは、メニュー項目が選択された場合は無地の青で表示され、選択されない場合はグレーで表示されます。

- antonym: メニュー項目ラベルが表示されます。メニュー項目が選択されると、(メニュー項目が選択されない場合に表示される)textまたはtextAndAccessKey属性の値で定義されたメニュー項目ではなく、selectedText属性に設定された値が表示されます。このタイプを選択する場合には、selectedTextに値を設定する必要があります。

- default: メニュー項目にはタイプが割り当てられません。選択されているかどうかに関係なく、メニュー項目は同じ方法で表示されます。

- text: メニュー項目のラベル・テキストを入力します。アクセス・キー(キーボードを使用して項目にアクセスする際に使用できる文字)も表示する場合は、この属性は空にして、かわりにtextAndAccessKeyに値を入力します。または、accessKey属性を使用して、アクセス・キーを別に設定することもできます。

- selected: メニュー項目を選択された状態で表示する場合にtrueに設定します。selected属性がサポートされているのはcheck、radioおよびantonymタイプのメニュー項目のみです。

- selectedText: メニュー項目が選択された場合に、このメニュー項目に表示する代替のラベルを設定します。この値は、antonymを除くすべてのタイプで無視されます。

例14-3に、メニュー項目の1つのグループがラジオ・ボタンを使用するように構成され、別のグループは選択されたら青の四角形を表示するよう構成されている「特別」メニューを示します。最後のグループには、最初に表示される際に反意語「開く」になり、「閉じる」に切り替わるよう構成されたメニュー項目が含まれています。

例14-3 commandMenuItemコンポーネントでのtype属性の使用

<af:menu text="Special">
<af:group>
<af:commandMenuItem text="Radio 1" type="radio" selected="true"
<af:commandMenuItem text="Radio 2" type="radio"/>
<af:commandMenuItem text="Radio 3" type="radio">
</af:group>
<af:group>
<af:commandMenuItem text="Check 1" type="check" selected="true"
<af:commandMenuItem text="Check 2" type="check"/>
</af:group>
<af:commandMenuItem text="Open (antonym)" type="antonym"
selectedText="Close (antonym)"/>
</af:menu>

図14-16に、最初にアクセスされた際にメニューがどのように表示されるかを示します。

注意:

デフォルトでは、ADF FacesコンポーネントはFusionFXスキン(チェック・タイプを四角形で表示)を使用します。これは、独自のスキンを作成することで変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

図14-16 type属性を使用したメニュー項目

10. 「外観」セクションを開き、次の属性を設定します。

- icon: ドロップダウン・リストを使用して、アイコンを選択します。アイコンがメニューに表示されない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用する必要があります。このアイコンの意味は、アクセシビリティが確保された別の方法で指定する必要があります。

- accelerator: [Ctrl]+[O]など、項目が選択された場合に、メニュー項目のコマンドをアクティブ化するキーストロークを入力します。図14-3に示すように、ADF Facesではキーストロークが変換され、メニュー項目ラベルの隣にキーストロークのテキスト・バージョン(「Ctrl+O」など)が表示されます。

注意:

コンテンツの遅延配信を使用する場合、メニューのコンテンツはアクセスされるまで把握されないため、子のcommandMenuItemコンポーネントに設定されているアクセラレータが機能しなくなります。メニューでアクセラレータ・キーをサポートする必要がある場合は、contentDelivery属性をimmediateに設定しておく必要があります。

- textAndAccessKey: 従来のアンパサンド表記を使用して、メニュー項目ラベルとアクセス・キーを入力します。たとえば、&amp;Saveではメニュー項目ラベルがSaveに設定され、同時に、メニュー項目アクセス・キーが文字Sに設定されます。アクセス・キーおよびアンバサンド表記の詳細は、22.3項「コンポーネントレベルのアクセシビリティ・プロパティの指定」を参照してください。

11. 「動作」セクションを開き、次の属性を設定します。

- action: メニュー項目が選択された場合に起動される、オブジェクト(マネージドBeanなど)のアクション・メソッドに対して評価されるEL式を使用します。式は、パラメータが指定されず、java.lang.Objectオブジェクトを返すpublicメソッドに対して評価される必要があります。
commandMenuItemコンポーネントによって生成されたアクションのレスポンスとしてナビゲートさせる場合は、EL式を入力するかわりに、静的アクションの結果値をaction属性の値として入力します。partialSubmit属性をfalseに設定するか、リダイレクトを使用する必要があります。アプリケーションにおけるナビゲーションの構成方法の詳細は、2.3項「ページ・フローの定義」を参照してください。

- actionListener: メニュー項目が選択された場合に通知される、アクション・リスナー・メソッドを参照する式を指定します。このメソッドは、action属性にバインドされているメソッドのかわりに使用できるため、action属性ではナビゲーションのみを処理できます。式では、ActionEventパラメータを取るpublicメソッドを評価し、戻り型がvoidである必要があります。

12. 簡単にナビゲート(通常は外部サイトにナビゲート)するメニュー項目を作成するには、コンポーネント・パレットから移動メニュー項目をメニューの子としてドラッグ・アンド・ドロップします。

13. プロパティ・インスペクタで、「その他」セクションを開いて次の属性を設定します。

- destination: リンクのナビゲート先のページのURIを入力します。たとえば、オラクル社のホームページにナビゲートする場合、http://www.oracle.comと入力します。

- icon: ドロップダウン・リストを使用して、アイコンを選択します。アイコンがメニューに表示されない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用する必要があります。このアイコンの意味は、アクセシビリティが確保された別の方法で指定する必要があります。

- targetFrame: ドロップダウン・リストを使用して、新しいページの表示場所を指定します。値は次のとおりです。

- _blank: リンクにより、ドキュメントは新しいウィンドウに開かれます。

- _parent: リンクにより、ドキュメントは親ウィンドウに開かれます。たとえば、リンクがダイアログに表示された場合、結果のページは親ウィンドウにレンダリングされます。

- _self: リンクにより、ドキュメントは同じページまたはリージョンに開かれます。

- _top: リンクにより、ページ全体が置き換えられて、ドキュメントはウィンドウ全体に開かれます。

- text: リンクのテキストを入力します。

ヒント:

かわりに、textAndAccessKey属性を使用して、リンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、22.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

14. メニュー・バーを含む親コンポーネントと同じ幅になるようにメニュー・バーを拡大する場合は、メニュー・バーが親と同じサイズになるように、拡大するメニュー・バー内のコンポーネントのIDにstretchIdを設定します。メニュー・バーのその他のコンポーネントは静的サイズのままですが、その1つのコンポーネントは拡大されます。
また例14-7に示すように、spacerコンポーネントを挿入し、そのコンポーネントIDをメニュー・バーのstretchIdとして設定することでコンポーネントの位置を左右に調整する場合にも、stretchId属性を使用できます。

例14-4 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>

14.3 ツールバーの使用方法

アプリケーションには、メニューのみでなく、アプリケーションの操作の開始に使用するツールバー・ボタンを含むツールバーも作成できます。ボタンには、テキスト、アイコンまたは両方を組み合せて表示できます。ツールバー・ボタンでは、メニューをポップアップ・ウィンドウに開くこともできます。ツールバー・ボタンのみでなく、ドロップダウン・リストなどのその他のUIコンポーネントをツールバーに表示できます。図14-17に、File Explorerアプリケーションのツールバーを示します。

ヒント:

ツールバーには、ツールバー・ボタンではなく、コマンド・ボタンやコマンド・リンク(commandImageLinkなど)を含めることもできます。ただし、ツールバー・ボタンには、ポップアップ・メニューの表示など、追加の機能もあります。ツールバー・ボタンは、toolbarコンポーネントの外でも使用できます。

図14-17 File Explorerアプリケーションのツールバー

toolbarコンポーネントには、inputTextコンポーネント、LOVコンポーネント、選択リスト・コンポーネントおよびコマンド・コンポーネントなど、様々なタイプのコンポーネントを含めることができます。ADF Facesには、ツールバー・ボタンからポップアップ・メニューを表示できるpopupファセットが含まれるcommandToolbarButtonコンポーネントもあります。ポップアップ・ダイアログのみが表示され、アクション・イベントが起動されないようにツールバー・ボタンを構成できます。メニュー同様、groupコンポーネントを使用して、ツールバー上の関連するツールバー・ボタンをグループ化できます。

toolboxで囲むことにより、複数のtoolbarを使用できます。toolboxで囲むことにより、toolbarが積み重なり、ページの最初のtoolbarが上に表示され、最後のtoolbarが下に表示されます。たとえば、図14-17に示すように、File Explorerアプリケーションでは、現在選択されているフォルダ名が「現在場所」ツールバーに表示されています。toolbarを複数使用する際は、toolbarにflex属性を設定し、どのツールバーに最も領域を使用するかを決定できます。この場合は、「現在場所」ツールバーが最も長くなるよう設定されています。

ツールバーを(縦ではなく)横に並べて表示する場合は、groupコンポーネント内に配置します。

ヒント:

toolboxコンポーネントを使用して、メニュー・バーとツールバーをグループ化することや、複数のメニュー・バーをグループ化することが可能です。ツールバーのグループ化同様、groupコンポーネントを使用して、同じ行のメニュー・バーとツールバーをグループ化できます。

toolbar内では、ツールバーがその親コンテナと常に同じ大きさになるように、1つのコンポーネントを拡大するよう設定できます。たとえば、File Explorerアプリケーションでは、現在の場所を表示する下側のツールバーには、選択されたフォルダを表示するコンポーネントが含まれています。このコンポーネントは、ウィンドウのサイズが変更されると拡大するように設定されており、コンポーネントとツールバーは常に親と同じ幅になります。一方、上側のツールバーのコンポーネントは拡大するように設定されていないため、ウィンドウがサイズ変更されてもサイズは変わりません。ウィンドウが、ツールバー内のすべてのコンポーネントを表示できないようなサイズに変更された場合、図14-18の右上端にある矢印カーソルで示すように、ツールバーにはオーバーフロー・アイコンが表示されます。

図14-18 ツールバーのオーバーフロー・アイコン

オーバーフロー・アイコンをクリックすると、図14-19に示すように、残りのコンポーネントがポップアップ・ウィンドウに表示されます。

図14-19 オーバーフロー・ポップアップ・ウィンドウ内のtoolbarコンポーネント

ツールバーでオーバーフローが発生することが予測される場合、オーバーフローで役に立つ特別なレイアウト・ロジックのあるtoolboxにラップすることをお薦めします。

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

ページに1つ以上のtoolbarコンポーネントを使用する場合、またはメニュー・バーとツールバーを一緒に使用する場合は、まず、それらを表示するtoolboxコンポーネントを作成します。その後、ツールバーを作成し、最後にツールバー・ボタンを作成します。

ヒント:

単一のツールバーまたはメニュー・バーでレイアウト上の問題が発生した場合は、toolboxコンポーネントでラップすることを検討してください。これは、このコンポーネントで、オーバーフローやレイアウトの問題を処理できるためです。

ツールバーを作成および使用する手順:

1. 複数のツールバーまたはツールバーとメニュー・バーの組合せを使用する場合は、コンポーネント・パレットの「レイアウト」パネルから「ツールボックス」コンポーネントをドラッグ・アンド・ドロップして、toolboxコンポーネントを作成します。

ヒント:

panelHeader、showDetailHeaderおよびshowDetailItemコンポーネントでは、セクション・ヘッダーおよびアコーディオン・パネル・ヘッダーにtoolboxやtoolbarを追加するためのtoolbarファセットがサポートされています。

2. コンポーネント・パレットの「共通コンポーネント」パネルから、JSFページに「ツールバー」をドラッグ・アンド・ドロップします。toolboxコンポーネントを使用している場合は、「ツールバー」がtoolboxコンポーネントの直接の子であることが必要です。

ヒント:

通常はtoolboxの直接の子である子コンポーネントをiterator、switcherおよびgroupコンポーネントにラップすれば、toolboxにもこれらのコンポーネントを直接の子として使用できます。

3. toolbox内で複数のtoolbarをグループ化する場合は、toolbarごとにtoolbarを選択して、「外観」セクションを開き、flex属性を設定して、各ツールバーの相対的なサイズを決定します。flex属性に指定された数が大きいほど、toolboxは長くなります。例14-5に示すツールバーのセットでは、toolbar2が最も長く、toolbar4が次に長くなり、残りのツールバーは、flex属性が設定されていないため、同じサイズでtoolbar4よりも短くなります。

例14-5 ツールバーの長さを決定するflex属性

<af:toolbox>
<af:toolbar id="toolbar1" flex="0">
<af:commandToolbarButton text="ButtonA"/>
</af:toolbar>
<af:toolbar id="toolbar2" flex="2">
<af:commandToolbarButton text="ButtonB"/>
</af:toolbar>
<af:toolbar id="toolbar3" flex="0">
<af:commandToolbarButton text="ButtonC"/>
</af:toolbar>
<af:toolbar id="toolbar4" flex="1">
<af:commandToolbarButton text="ButtonD"/>
</af:toolbar>
</af:toolbox>

パフォーマンスのヒント:

実行時、使用可能なブラウザの領域が、toolboxのコンテンツの表示に必要な領域より少ない場合、表示されていない項目をユーザーが選択して表示できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。toolboxコンポーネント内の子コンポーネントの数、および子の複雑さが、オーバーフローのパフォーマンスに影響します。可能な場合は、オーバーフローしないように、toolboxコンポーネントのサイズを設定する必要があります。詳細は、14.3.2項「実行時の処理: メニュー・バーおよびツールバーのサイズの決定」を参照してください。

ヒント:

groupコンポーネントを使用して、同じ行に表示するツールバー(またはメニュー・バーとツールバー)をグループ化できます。groupコンポーネントを使用しない場合、ツールバーは次の行に表示されます。

flex属性の機能の詳細は、14.3.2項「実行時の処理: メニュー・バーおよびツールバーのサイズの決定」を参照してください。

4. 必要に応じてtoolbarにコンポーネントを挿入します。ommandToolbarButtonを作成するには、コンポーネント・パレットから「ToolbarButton」をドラッグし、toolbarコンポーネントの直接の子としてドロップします。

ヒント:

groupコンポーネントを使用して、バーの関連するボタンをラップできます。これにより、図14-17のスキンの選択ドロップダウン・リストと「リフレッシュ」ボタンのグループを囲むように、グループ間にセパレータが挿入されます。

通常はtoolbarの直接の子である子コンポーネントをiteratorおよびswitcherコンポーネントにラップすれば、toolbarにもこれらのコンポーネントを直接の子として使用できます。

ヒント:

toolbarには、コマンド・ボタンやリンク、入力コンポーネントおよび選択コンポーネントなど、その他のコンポーネントを配置できます。ただし、拡大することはできません。ツールバーの拡大の詳細は、手順9を参照してください。

ヒント:

アクティブ・データを使用したボタンのvisible属性の変更をサポートする場合(たとえば、データ・ソースからプッシュされているデータによって、ツールバーを表示するか表示しないかを決定する場合)、commandToolbarButtonコンポーネントのかわりに、activeCommandToolbarButtonコンポーネントを使用する必要があります。コンポーネント・パレットから「ツールバー・ボタン(アクティブ)」をドラッグして、activeCommandToolbarButtonコンポーネントを作成します。

5. 各commandToolbarButtonコンポーネントに対し、プロパティ・インスペクタの「共通」セクションを開いて、次の属性を設定します。

- type: ツールバー・ボタンのタイプを指定します。ツールバー・ボタンのタイプを指定すると、ボタンがクリックされた際にアイコンが表示されます。次に示す使用可能なtype値のいずれかを使用します。

- check: 選択されている場合はdepressedIcon値が表示され、選択されていない場合はデフォルトのicon値が表示されます。

- radio: グループ内のその他のツールバー・ボタンとともに使用すると、現在クリックされているボタンが選択されている状態になり、前にクリックされたグループ内のボタンの選択が解除されます。

注意:

タイプをradioに設定する場合は、タイプがradioに設定されている別のツールバー・ボタンを含むgroupタグでツールバー・ボタンをラップする必要があります。

- default: ツールバー・ボタンにはタイプは割り当てられません。

- selected: ツールバー・ボタンが選択されているように表示する場合にtrueに設定します。selected属性がサポートされているのは、チェックマーク・タイプおよびラジオ・タイプのツールバー・ボタンのみです。

- icon: ドロップダウン・リストを使用して、アイコンを選択します。アイコンがメニューに表示されない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

注意:

このアイコンでは代替テキストを指定できないため、アクセシビリティが確保された製品を作成するには、このアイコンを装飾目的でのみ使用する必要があります。このアイコンの意味は、アクセシビリティが確保された別の方法で指定する必要があります。

- text: ツールバー・ボタンのラベルを入力します。

- action: ユーザーがボタンを押した場合に起動される、オブジェクト(マネージドBeanなど)のアクション・メソッドに対して評価されるEL式を使用します。式は、パラメータが指定されず、java.lang.Objectオブジェクトを返すpublicメソッドに対して評価される必要があります。
ボタンによって生成されたアクションのレスポンスとしてナビゲートさせる場合は、EL式を入力するかわりに、静的アクションの結果値をaction属性の値として入力します。partialSubmitをfalseに設定するか、リダイレクトを使用する必要があります。ナビゲーションの構成方法の詳細は、2.3項「ページ・フローの定義」を参照してください。

- actionListener: このボタンを押した場合に通知される、アクション・リスナー・メソッドを参照する式を指定します。このメソッドは、action属性にバインドされているメソッドのかわりに使用できるため、action属性ではナビゲーションのみを処理できます。式では、ActionEventパラメータを取るpublicメソッドを評価し、戻り型がvoidである必要があります。

6. 「外観」セクションを開き、次のプロパティを設定します。

- hoverIcon: ドロップダウン・リストを使用して、マウス・カーソルがツールバー・ボタンの上にある場合に表示するアイコンを選択します。アイコンがメニューにない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

- depressedIcon: ドロップダウン・リストを使用して、ツールバー・ボタンが有効になった場合に表示するアイコンを選択します。アイコンがメニューにない場合は、リストに右側にあるドロップダウン・メニューを使用して、「編集」を選択し、アイコンを参照して選択します。

7. ボタンがクリックされた時にアクション・イベントを起動しない場合は、「動作」セクションを開いて、actionDeliveryをnoneに設定します。これは、ポップアップ・ウィンドウを開くのみのボタンにする場合に便利です。noneに設定している場合は、popupコンポーネントをツールバー・ボタンのpopupファセットに配置する必要がありますが(手順 8を参照)、actionまたはactionListener属性には値を設定できません。標準のコマンド・コンポーネントとして、ボタンでアクション・イベントを起動させる場合は、clientServer属性を設定します。

8. ツールバー・ボタンからポップアップ・メニューが起動されるようにするには、commandToolbarButtonコンポーネントのpopupファセットにmenuコンポーネントを挿入します。詳細は、14.2.1項「メニュー・バーのメニューの作成および使用方法」を参照してください。

9. ツールバーを含む親コンポーネントと同じ幅になるようにツールバーを拡大する場合は、stretchId属性を、拡大するツールバー内のコンポーネントのIDに設定します。ツールバーのその他のコンポーネントは静的サイズのままですが、その1つのコンポーネントは拡大されます。

たとえば、例14-6に示すように、File Explorerアプリケーションで、選択されているフォルダ名を表示するinputTextコンポーネントは拡大し、現在のフォルダという語を表示するoutputTextコンポーネントは静的サイズのままになります。

例14-6 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>

また例14-7に示すように、spacerコンポーネントを挿入し、そのコンポーネントIDをtoolbarのstretchIdとして設定することでコンポーネントの位置を左右に調整する場合にも、stretchId属性を使用できます。

例14-7 toolbarコンポーネントの位置を調整するためのspacerの使用

<af:toolbar flex="1" stretchId="stretch1">
<af:commandToolbarButton text="Forward"
icon="/images/fwdarrow_gray.gif"
disabled="true"></af:commandToolbarButton>
<af:commandToolbarButton icon="/images/uplevel.gif" />

<!-- Insert a stretched spacer to push subsequent buttons to the right -->

<af:spacer id="stretch1" clientComponent="true"/>

<af:commandToolbarButton text="Reports" />
<af:commandToolbarButton id="toggleRefresh"
text="Refresh:OFF" />
</af:toolbar>

14.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項「言語読取り方向」を参照してください。

14.3.3 ツールバーについて

ツールバーは、ツールバーやツールバー・ボタンをセクション・ヘッダーおよびアコーディオン・パネル・ヘッダーに追加するためのtoolbarファセットがあるpanelHeader、showDetailHeader、showDetailItemなどの親コンポーネントによってサポートおよびレンダリングされます。

実行時のツールバーについて、次の点に注意してください。

- ヘッダーが閉じている場合、ツールバーおよびそのボタンはヘッダーに表示されません。ツールバーが表示されるのは、ヘッダーが開いている場合のみです。

- ヘッダーの使用可能な領域がツールバーやそのすべてのボタンに必要な領域より少ない場合、ADF Facesにより、ユーザーがオーバーフロー・リストから非表示のボタンを選択できるオーバーフロー・アイコンが自動的にレンダリングされます。

- ツールバーは、印刷可能ページにはレンダリングされません。

15 Calendarアプリケーションの作成

この章では、ADF Faces calendarコンポーネントを使用して、Calendarアプリケーションを作成する方法について説明します。

この章では、次の項目について説明します。

- 15.1項「Calendarアプリケーションの作成の概要」

- 15.2項「Calendarの作成」

- 15.3項「Calendarコンポーネントの構成」

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

- 15.5項「ツールバーのカスタマイズ」

- 15.6項「Calendarのスタイル設定」

15.1 Calendarアプリケーションの作成の概要

ADF Facesには、特定のプロバイダ(プロバイダとはアクティビティの所有者)用に作成されたアクティビティをデフォルトで日次表示、週表示、月表示またはリスト表示するCalendarコンポーネントが含まれています。図15-1に、いくつかのサンプル・アクティビティがある週表示モードのADF Faces Calendarを示します。

図15-1 週表示を示しているADF Faces Calendar

これらのビューのサブセットのみを表示するようにCalendarを構成できます。たとえば、月表示およびリスト表示を使用するために、Calendarが不要な場合があります。図15-2に示すように、日表示および週表示のみを使用できるように構成できます。日表示および週表示しか使用できないため、ツールバーには日表示と週表示のボタンしか表示されません。

図15-2 週表示と日表示のみを使用するために構成されたCalendar

デフォルトでは、Calendarにはtrinidad-config.xmlファイルに設定されているロケールに基づく日付と時間が表示されます(trinidad-config.xmlでの構成に関する項を参照)。trinidad-config.xmlファイルにロケールが設定されていない場合、ブラウザから送信されたロケールに基づいて表示されます。たとえば、米国のデフォルトでは、週の開始日は日曜日であり、午後2時は2:00 PMと表示されます。フランスのデフォルトでは、開始日は月曜日であり、午後2時は14:00と表示されます。Calendarのタイムゾーンもtrinidad-config.xmlの設定に基づきます。このデフォルトは、Calendarの構成時にオーバーライドできます。詳細は、Calendarコンポーネントの構成に関する項を参照してください。

Calendarは、CalendarModelクラスを使用して、特定の期間のアクティビティを表示します。Calendarのモデル・クラスの独自の実装を作成する必要があります。アプリケーションでFusionテクノロジ・スタックを使用する場合は、アクティビティを表すデータソースに対するADF Business Componentsを作成でき、作成するとモデルが作成されます。その後、Calendarを宣言的に作成でき、そのCalendarは自動的にそのモデルにバインドされます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のADF Faces Calendarコンポーネントの使用に関する項を参照してください。

アプリケーションでFusionテクノロジ・スタックを使用しない場合は、CalendarModelクラスと、関連するCalendarActivityクラスおよびCalendarProviderクラスの独自の実装を作成します。これらのクラスは、抽象メソッドを使用する抽象クラスです。Calendarの実装に適した、メソッドを支援する機能を提供する必要があります。詳細は、Calendarの作成に関する項を参照してください。

Calendarには組込み機能のあるツールバーが含まれています。これを使用すると、表示の変更(日表示、週表示、月表示またはリスト表示間の変更)および前日、翌日、翌週または翌月への移動が可能になり、本日に戻ることもできます。ツールバーは完全にカスタマイズ可能です。表示するボタンやテキストを選択できます。また、ボタンや他のコンポーネントを追加することもできます。詳細は、ツールバーのカスタマイズに関する項を参照してください。

ヒント:

これらのツールバー・ボタンを使用すると、Calendarの属性値が変わります。それらの値がセッション中に変わらないよう、永続するように構成できます。詳細は、第31章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

値が永続され、ユーザーがシステムにログインするたびに使用されるように、アプリケーションを構成することもできます。この永続性が行われるためには、アプリケーションでFusionテクノロジ・スタックを使用する必要があります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「実行時のユーザー・カスタマイズの許可」の章を参照してください。

Calendarコンポーネントには、CalendarModelクラスから返されるアクティビティおよびプロバイダに基づくアクティビティが表示されます。デフォルトでは、Calendarコンポーネントは読取り専用です。つまり、Calendarコンポーネントは返されたアクティビティのみ表示できます。ユーザーがアクティビティを編集、作成および削除できるように、Calendarでサポートされているファセット内に機能を追加できます。特定のイベントが起動されると、それらの対応するファセット内にあるポップアップ・コンポーネントが開き、ユーザーがアクティビティまたはCalendarに対して操作を実行できるようになります。

たとえば、ユーザーがCalendar内のアクティビティをクリックすると、CalendarActivityEventが起動され、ActivityDetailファセットのポップアップ・コンポーネントが開きます。図15-3に示すように、ユーザーがアクティビティを表示および編集できるフォームを含んでいるダイアログ・コンポーネントを使用することもできます。

図15-3 アクティビティを編集するために実装されているダイアログ

イベント、ファセットおよびポップアップ・コンポーネントを使用した追加機能の実装の詳細は、ポップアップ・コンポーネントを使用した機能の追加に関する項を参照してください。

Calendarコンポーネントでは、ADF Facesのドラッグ・アンド・ドロップ・アーキテクチャ機能がサポートされています。ユーザーは、アクティビティをCalendarの異なる領域にドラッグしてコピーまたは移動を行ったり、アクティビティのハンドルをドラッグしてアクティビティの期間を変更したりすることもできます。ドラッグ・アンド・ドロップ機能の追加の詳細は、Calendarへのドラッグ・アンド・ドロップ機能の追加に関する項を参照してください。

デフォルトでは、Calendarは青いランプを使用してアクティビティを表示します。色ランプは、すべてが同じ色相(たとえば青)に基づいている色のグループです。図15-1に示すように、デフォルトのCalendarでは、日次表示で表示される短期間のアクティビティの場合、アクティビティの時間は濃い青の背景色で表示され、アクティビティのタイトルは薄い青の背景色で表示されます。色ランプを変更することで、アクティビティの表示方法をカスタマイズできます。

各アクティビティはプロバイダ、つまり所有者に関連付けられています。図15-4に示すように、複数のプロバイダのアクティビティを表示できるようにCalendarを実装する場合、各プロバイダのアクティビティが異なる色で表示されるようにそれぞれのアクティビティのスタイルを設定できます。

図15-4 様々なプロバイダのアクティビティがある月表示

15.2 Calendarの作成

Calendarコンポーネントをページに追加する前に、ADF Faces Calendarの抽象クラスを拡張するJavaクラスのCalendarで必要なロジックを実装する必要があります。ADF Facesアプリケーションの場合は、マネージドBeanとしてクラスを作成します。クラスを作成すると、Calendarをページに追加できます。

注意:

アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADF Business Componentsを使用してCalendarクラスを実装します。これにより、Calendarコンポーネントを宣言的に作成してバインドできます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のADF Faces Calendarコンポーネントの使用に関する項を参照してください。

ロジックを実装する前に、次の項で説明されているCalendarModelクラスおよびCalendarActivityクラスについて理解しておくと役立ちます。

15.2.1 Calendarのクラス

Calendarコンポーネントは、CalendarModelクラスの実装にバインドする必要があります。CalendarModelクラスには、Calendarのデータが含まれます。このクラスは、次の一連のパラメータに基づき、Calendarアクティビティのコレクションを返します。

- プロバイダID: アクティビティの所有者。たとえば、Calendarが現在セッション中の所有者に関連付けられているアクティビティのみ返すように、またはその他の所有者のアクティビティも返すようにCalendarModelクラスを実装できます。

- 時間範囲: この時間内で開始するすべてのアクティビティが戻るまでの時間の長さ。Calendarの日付の範囲に開始時間は含まれますが、終了時間は含まれません(ハーフオープンとも呼ばれます)。つまり、その範囲にわたるすべてのアクティビティ(開始時間前に開始し、開始時間後かつ終了時間前に終了したアクティビティを含む)が返されることを意味します。

Calendarアクティビティは、Calendar上のオブジェクトを表し、通常は一定の期間にわたります。CalendarActivityクラスは抽象クラスであり、このクラスのメソッドは特定のアクティビティに関する情報を返すために実装できます。

アクティビティは再帰可能で、関連するキーワードを設定でき、特定の時間タイプ(時または分など)に設定できます。アクティビティには開始日と終了日、ロケーション、タイトルおよびタグを設定することもできます。

CalendarProviderクラスは、アクティビティの所有者を表します。プロバイダは、Calendarに対して有効化または無効化できます。

15.2.2 Calendarの作成方法

CalendarModelクラスおよびCalendarActivityクラスの独自の実装を作成し、抽象メソッドを実装してロジックを提供します。

Calendarモデル・クラスを作成する手順:

1. Calendarのロジックを保持するマネージドBeanを作成します。このBeanでは、次のことを行う必要があります。

- oracle.adf.view.rich.model.CalendarModelクラスを拡張する。

- 抽象メソッドを実装する。
CalendarModelクラスの詳細は、ADF Faces Javadocを参照してください。

- Calendarに必要なその他の機能を実装する。たとえば、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.calendar.rich.model.DemoCalendarBeanマネージドBeanにタイムゾーンを設定するロジックを追加します。(デモ・アプリケーションの詳細は、ADF Facesデモ・アプリケーションに関する項を参照)。

マネージドBeanの作成の詳細は、マネージドBeanの作成と使用に関する項を参照してください。

2. アクティビティのロジックを保持するマネージドBeanを作成します。このBeanでは、次のことを行う必要があります。

- oracle.adf.view.rich.model.CalendarActivityクラスを拡張する。

- 抽象メソッドを実装する。

- Calendarに必要なその他の機能を実装する。例として、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.calendar.rich.model.DemoCalendarActivityマネージドBeanを参照してください。

ヒント:

アクティビティの個々のインスタンスにスタイルを設定する場合(たとえば、各プロバイダのアクティビティを異なる色で表示する場合)、getTagsメソッドでアクティビティ・インスタンスを表す文字列を返す必要があります。詳細は、アクティビティのスタイル設定方法に関する項を参照してください。

3. プロバイダの情報とロジックを保持するマネージドBeanを作成します。

- oracle.adf.view.rich.model.CalendarProviderクラスを拡張する。

- 抽象メソッドを実装する。

- プロバイダに必要なその他の機能を実装する。

Calendarコンポーネントを作成する手順:

1. コンポーネント・パレットの「共通コンポーネント」セクションから、CalendarをドラッグしてJSFページにドロップします。

ヒント:

Calendarコンポーネントは、子を拡大する任意の親コンポーネントが拡大できます。Calendarが拡大できないコンポーネントの子コンポーネントである場合、デフォルトの幅と高さが使用されます。実行時にユーザーはこれを拡大できません。ただし、インライン・スタイル属性を使用して、デフォルトの幅と高さをオーバーライドできます。デフォルトの高さと幅の詳細は、Calendarコンポーネントの構成に関する項を参照してください。コンポーネントの拡大の詳細は、ジオメトリ管理およびコンポーネントの拡大に関する項を参照してください。

2. プロパティ・インスペクタの「カレンダ・データ」セクションを開き、CalendarModelクラスを拡張するマネージドBeanに解決されるvalueに対してEL式を入力します。

15.3 Calendarコンポーネントの構成

Calendarの多くの表示属性(週の開始日、1日の始まりに表示する時刻など)を構成します。

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

プロパティ・インスペクタを使用してCalendarを構成します。

Calendarを構成する手順:

1. Calendarコンポーネントを選択した状態で、プロパティ・インスペクタの「共通」セクションを開き、次の設定を行います。

- View: Calendarを表示するときのデフォルトの表示(day、list、monthまたはweek)を選択します。ユーザーは、Calendarのツールバーにある対応するボタンをクリックしてこの値を変更できます。

- StartDayOfWeek: 月表示または週表示の左端に週の開始日として表示される曜日を入力します。設定しない場合、デフォルトはユーザーのロケールに基づきます。有効な値は次のとおりです。

- sun

- mon

- tue

- wed

- thu

- fri

- sat

- StartHour: 日表示および週表示の上部に表示される時間(0が午前0時の24時間形式)を表す数値を入力します。日表示または週表示のCalendarが午前12:01に開始する場合、そのCalendarはstartHour値に自動的にスクロールされ、表示の上部に表示されます。ユーザーは、startHourの値より前に開始したアクティビティを確認するために、いつでもこの時間より前にスクロールできます。

- ListType: リスト表示でアクティビティを表示する方法を選択します。有効な値は次のとおりです。

- day: アクティブな日のアクティビティのみ表示します。

- dayCount: listCount属性の値に基づき、アクティブな日以降を含む日数を表示します。

- month: アクティブな日が属する月のアクティビティをすべて表示します。

- week: アクティブな日が属する週のアクティビティをすべて表示します。

- ListCount: 表示する日のアクティビティ数を入力します(listType属性がdayCountに設定されている場合のみ使用します)。
図15-5に、listTypeがdayCountに設定され、listCount値が7に設定されているリスト表示のCalendarを示します。

図15-5 dayCountタイプを使用したリスト表示

2. プロパティ・インスペクタの「カレンダ・データ」セクションを開き、次の設定を行います。

- ActiveDay: Calendarに表示される日付範囲を決定するために使用される日を設定します。デフォルトでは、アクティブ日はユーザーの今日の日付です。Calendarを初めて開くときのデフォルトのアクティブ日を今日の日付にする場合は、この設定を変更しないでください。
別の日を選択した場合、その日がactiveDay属性の値になります。たとえば、Calendarに初めてアクセスする場合、現在の日付(2009年2月6日)がアクティブ日になります。月表示には2月が表示されます。「次へ」ボタンを使用して次の月にスクロールすると、アクティブ日は2009年3月6日になります。

- TimeZone: Calendarのタイムゾーンを設定します。設定しない場合、値はAdfFacesContextから取得されます。有効な値はjava.util.TimeZoneオブジェクトです。

3. プロパティ・インスペクタの「その他」セクションを開き、AvailableViewsを設定します。値は、次のうちの1つ、または組み合せて設定できます。

- month

- week

- day

- list

- all

複数の値を入力する場合、値と値の間に空白を入力します。たとえば、Calendarに日表示と週表示を使用する場合、次のように入力します。

day week

注意:

allが入力された場合、リストから除外されているものがあるかどうかに関係なく、すべての表示を使用できます。

対応するボタンが、リストに表示される順序で自動的にツールバーに表示されます。

使用できる表示としてdayを入力しない場合、アクティビティはリスト表示および週表示のリンクとして表示されるのではなく、プレーン・テキストとして表示されます(allを入力しない場合も同様です)。

注意:

monthを入力して、allを入力しない場合は、月表示で特定の日のタスクのオーバーフローを処理するために、dayも入力する必要があります。

4. ユーザーが既存のアクティビティのハンドルをドラッグして、そのアクティビティの期間を拡張または縮小できるようにする場合は、CalendarActivityDurationChangeListenerのハンドラを実装します。このハンドラには、アクティビティの終了時間を変更する機能を含める必要があります。ユーザーがアクティビティを移動し、開始時間および終了時間を変更できるようにするには、ドラッグ・アンド・ドロップ機能を実装します。詳細は、Calendarへのドラッグ・アンド・ドロップ機能の追加に関する項を参照してください。

これで、次の機能を追加できます。

- ユーザーがポップアップ・コンポーネントを使用してアクティビティを作成、編集および削除できるようになります。詳細は、ポップアップ・コンポーネントを使用した機能の追加に関する項を参照してください。

- ユーザーがCalendar上でアクティビティを移動できるようになります。詳細は、Calendarへのドラッグ・アンド・ドロップ機能の追加に関する項を参照してください。

- ツールバーのツールバー・ボタンを変更または追加します。詳細は、ツールバーのカスタマイズに関する項を参照してください。

- Calendarとイベントの外観を変更します。詳細は、Calendarのスタイル設定に関する項を参照してください。

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

Calendarには、必要な追加の機能(アクティビティの編集と追加など)を簡単に実装するための方法を提供するファセットと連携して使用される2つのイベントがあります。その2つのイベントとは、CalendarActivityEvent(アクションがアクティビティで発生した場合に起動されます)とCalendarEvent(アクションがCalendar自体で発生した場合に起動されます)です。追加機能を提供するこれらのイベントの使用の詳細は、ポップアップ・コンポーネントを使用した機能の追加に関する項を参照してください。

Calendarでは、特定の変更が発生したときに起動されるイベントもサポートされています。ユーザーが、アクティビティが表示されるボックスをドラッグして、アクティビティの期間を変更すると、CalendarActivityDurationChangeEventが起動されます。コンポーネントによって表示属性の値が変更されると(たとえば、view属性がmonthからdayに変更された場合)、常にCalendarDisplayChangeEventが起動されます。

CalendarDisplayChangeEventが起動されると、Calendarコンポーネントは部分ページ・レンダリング(PPR)のターゲットとしてコンポーネント自体を追加し、Calendarをすぐにリフレッシュできるようにします。これは、Calendarでは、プログラムを使用して表示が変更された場合、Calendarを再レンダリングする必要があることが前提となっているためです。たとえば、view属性をdayからmonthに変更した場合、Calendarは自動的に再レンダリングされます。

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

ユーザーがアクティビティに対して操作を行うと、CalendarActivityEventが起動されます。このイベントは、ユーザーの操作に基づいて、ファセットに含まれているポップアップ・コンポーネントを表示します。たとえば、ユーザーがアクティビティを右クリックすると、CalendarActivityEventにより、activityContextMenuのポップアップ・コンポーネントが表示されます。イベントはサーバーにも配信され、サーバーでは構成済のリスナーがそのイベントに対する処理を実行できます。ユーザーがファセット用のポップアップ・コンポーネントを作成します(または、ポップアップ・コンポーネントを使用しない場合、サーバー側のリスナーを実装します)。これらのポップアップ・コンポーネントおよびファセットで、ユーザーがアクティビティを作成、削除および編集できる機能、およびCalendarのインスタンスを構成できる機能を実装できます。

表15-1に、イベントを起動する様々なユーザー・アクション、起動されるイベント、およびイベントが起動されたときにファセットのコンテンツを表示する関連のファセットを示します。このテーブルには、ポップアップ・コンポーネント内で使用する必要のあるコンポーネントも示されています。ポップアップ・コンポーネントおよび関連のコンポーネントは、関連リスナーのハンドラで実装された機能とともにファセット内に作成します。表のファセットのいずれにもポップアップ・コンポーネントを挿入しない場合、関連のイベントがサーバーに配信されます。サーバーで、そのイベントのハンドラを実装することによってイベントを処理できます。

表15-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

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

機能を追加するには、関連ファセット内にポップアップ・コンポーネントと関連コンポーネントを作成します。

ポップアップ・コンポーネントを使用して機能を追加する手順:

1. 図15-6に示すように、構造ウィンドウでaf:calendarコンポーネント・ノードを開き、Calendarファセットを表示します。

図15-6 構造ウィンドウ内のCalendarファセット

2. 表15-1に基づき、機能を提供するユーザー・アクションに対応するポップアップ・コンポーネントをファセットに作成します。たとえば、アクティビティをクリックして[Del]キーを押すことで、ユーザーがアクティビティを削除できるようにする場合は、activityDeleteファセットにポップアップ・ダイアログを追加します。
ポップアップ・コンポーネントを追加するには、構造ウィンドウのファセットを右クリックして、「facetNameの中に挿入」→ 「componentName」の順に選択します。

ポップアップ・コンポーネントの作成の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

例15-1に、activityDeleteファセットで使用されるダイアログ・ポップアップ・コンポーネントのJSFコードを示します。

例15-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:outputText value="NOTE: This popup is for demo purposes only,
it is not part of the built in functionality of the calendar."/>
<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>

図15-7に、ユーザーがアクティビティをクリックして[Del]キーを押したときに、ダイアログがどのように表示されるかを示します。

図15-7 アクティビティの削除ダイアログ

3. calendarActivityListenerに必要なロジックを実装します。たとえば、activityDeleteFacetのダイアログを実装している場合、現在のアクティビティを保存できるロジックをcalendarActivityListenerに実装します。それによって、(次の手順で)ダイアログ・リスナーにロジックを実装したときに削除するアクティビティがわかります。例15-2に、ADF Facesデモ・アプリケーションのcalendar.jspxページのcalendarActivityListenerを示します。

例15-2 calendarActivityLIstenerハンドラ

public void activityListener(CalendarActivityEvent ae)
{

CalendarActivity activity = ae.getCalendarActivity();

if (activity == null)
{
// no activity with that id is found in the model
System.out.println("No activity with event " + ae.toString());
setCurrActivity(null);
return;
}

System.out.println("providerId is " + activity.getProviderId());
System.out.println("activityId is " + activity.getId());

setCurrActivity(new DemoCalendarActivityBean((DemoCalendarActivity)activity, getTimeZone()))

4. ポップアップ・イベントのハンドラにポップアップ・コンポーネントのロジックを実装します。たとえば、「削除」ダイアログの場合、ダイアログが閉じたときに実際のアクティビティを削除するdialogListenerのハンドラを実装します。ダイアログおよび他のポップアップ・コンポーネントの作成の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

15.5 ツールバーのカスタマイズ

デフォルトでは、Calendarのツールバーを使用すると、表示を日、週、月およびリスト間で変更したり、表示内の次の項目または前の項目に移動したり、当日に移動したりすることができ、現在の表示のテキスト説明も表示できます。たとえば、図15-8に示すように、日表示の場合はアクティブ日を表示できます。

図15-8 日表示のCalendarのツールバー

図15-9に、カスタマイズされているツールバーを示します。このツールバーには、一番上のツールバーに右揃えされているボタンおよび2番目のツールバーのボタンを含め、ツールバー・ボタンが追加されています。

図15-9 カスタマイズされたCalendarのツールバー

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

作成するカスタム・ファセットに、追加するツールバーおよびツールバー・ボタンを配置します。次に、含まれている項目の表示方法および表示場所を決定するキーワードとともに、ツールバーの属性からファセットを参照します。

ツールバーをカスタマイズする手順:

1. コンポーネント・パレットのJSFページで、「コア」パネルから、追加するツールバーの各セクションのファセットをドラッグ・アンド・ドロップします。たとえば、図15-9に示されているカスタム・ボタンを追加するには、4つのファセット・タグを追加します。各ファセットには、ページに対する一意な名前を付けてください。

ヒント:

ADF Facesの今後のリリースと競合が生じないようにするには、すべてのファセット名をcustomToolbarで開始します。たとえば、図15-9に示されている「位置合せ」ボタンを含むツールバーのセクションは、customToolbarAlignファセットです。

2. コンポーネント・パレットのADF Facesページで、「共通コンポーネント」パネルからツールバーを各ファセットにドラッグ・アンド・ドロップし、ツールバー・ボタンを追加して、必要に応じてボタンとツールバーを構成します。ツールバーとツールバー・ボタンの詳細は、ツールバーの使用方法に関する項を参照してください。

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コンポーネントを追加して、次の名前付きファセット(またはデフォルトのツールバーの次のキーワード)がツールバーに右揃えで表示されるようにします。図15-9に表示されるツールバーのtoolboxLayout属性の値、およびcustomToolbarAlignファセットに配置されているツールバーを、例15-3に示します。customToolbarBoldファセットに表示されているツールバー・ボタンは、stretchキーワードがファセットの前に指定されているため、ツールバー内で右揃えで表示されています。

例15-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:commandToolbarButton id="alignLeft" shortDesc="align left"
icon="/images/alignleft16.png" type="radio"
selected="true"/>
<af:commandToolbarButton id="alignCenter" shortDesc="align center"
icon="/images/aligncenter16.png" type="radio"
selected="false"/>
<af:commandToolbarButton id="alignRight" shortDesc="align right"
icon="/images/alignright16.png" type="radio"
selected="false"/>
</af:toolbar>
</f:facet>
. . .
</af:calendar>

15.6 Calendarのスタイル設定

他のADF Facesコンポーネントと同様、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」で説明されているように、Calendarコンポーネントもスタイル設定できます。ただし、標準のスタイル設定の手順とともに、Calendarコンポーネントには、Calendarのインスタンスのスタイル設定をより簡単にする特別な属性があります。それらの属性は次のとおりです。

- activityStyles: 各アクティビティ・インスタンスを個々にスタイル設定できます。たとえば、異なるプロバイダに属しているアクティビティを別の色で表示できます。

- dateCustomizer: 月表示の日にCalendar日以外の文字列を表示できます。たとえば、図15-10に示されているように、カウントダウン・タイプまたはカウントアップ・タイプの数値を表示できます。この属性を使用すると、日のヘッダーの空白部分に文字列を追加できます。

図15-10 Calendarのカスタマイズ済の日付表示

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

activityStyles属性は、InstanceStylesオブジェクトを使用して、アクティビティの特定のインスタンスをスタイル設定します。InstanceStylesクラスは、スキニング・キーに基づくインスタンスごとのインライン・スタイルを提供します。

activityStyles属性は、特定のプロバイダに属しているアクティビティを特定の色を使用して表示するために最もよく使用されます。たとえば、図15-11に示されているCalendarは、異なる3つのプロバイダに属しているアクティビティを示しています。プロバイダのアクティビティを表すために使用されている色は、左のペインで変更できます。activityStyles属性は、アクティビティが関連付けられているプロバイダに基づき、各アクティビティに表示される色を決定するために使用します。

図15-11 プロバイダごとに異なる色を表示するようにスタイル設定されているアクティビティ

このCalendarでは、単一の色を使用するかわりに、色の範囲が使用されています。これは、色ランプと呼ばれます。色ランプは、色ファミリ内の色のセットであり、アクティビティの様々な状態を表します。たとえば、T.F.のアクティビティでは青いランプを使用しています。期間が1日以内のアクティビティは、青色の中間色のテキストで表示されます。複数日にまたがるアクティビティは、青色の中間色のボックスに白いテキストで表示されます。濃い青は開始時間の背景色で、薄い青はタイトルの背景色です。これら3つの異なる青は、すべて青い色ランプの一部です。

CalendarActivityRampクラスは、InstanceStylesのサブクラスであり、代表的な色を取得して(たとえば、T.F.のアクティビティには青が選択されています)、Calendarで各アクティビティを表示するために使用する正しい色ランプを返すことができます。

activityStyles属性は、mapオブジェクトにバインドする必要があります。マップ・キーは、アクティビティに対するgetTagsメソッドから返されるセットです。InstanceStylesオブジェクトのマップ値は、ほとんどの場合CalendarActivityRampのインスタンスです。このInstanceStylesオブジェクトはスキンニング・キーを取り込み、各アクティビティのスタイルを返します。

アクティビティをスタイル設定する手順:

1. CalendarActivityクラスで、getTagsメソッドを使用して文字列セットを返します。この文字列は、返された文字列を特定のスタイルにマップするためにactivityStyles属性によって使用されます。たとえば、図15-11に示すように異なる色ランプを異なるプロバイダに使用する場合は、文字列を各プロバイダに返す必要があります。この場合、現在のユーザーに属するアクティビティはMeを返し、L.E.に属するアクティビティはLEを返し、T.F.に属するアクティビティはTFを返します。CalendarActivityクラスの実装の詳細は、Calendarの作成方法に関する項を参照してください。

2. キーがgetTagsメソッドから返された文字列であり、値がInstanceStylesオブジェクト(CalendarActivityRampインスタンスなど)であるマップを作成します。
たとえば、図15-11に示すように異なる色ランプを使用する場合は、表15-2に示されている値を使用してマップを作成できます。

表15-2 activityStyles属性のマップ

キー(文字列セット)

値(InstanceStylesオブジェクト)

{"Me"}

CalendarActivityRamp.getActivityRamp(CalendarActivityRamp.RampKey.RED)

{"LE"}

CalendarActivityRamp.getActivityRamp (CalendarActivityRamp.RampKey.ORANGE)

{"TF"}

CalendarActivityRamp.getActivityRamp (CalendarActivityRamp.RampKey.BLUE)

3. 構造ウィンドウでCalendarコンポーネントを選択し、プロパティ・インスペクタでactivityStyles属性をマップにバインドします。

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

各アクティビティに対するCalendarのレンダリング中、レンダラはCalendarActivity.getTagsメソッドをコールして文字列セットを取得します。次に、文字列セットはactivityStyles属性にバインドされているマップに渡され、InstanceStylesオブジェクトが返されます(CalendarActivityRampの場合もあります)。

次の例を参照してください。

- 文字列セット{"Me"}が渡された場合、赤のCalendarActivityRampが返されます。

- 文字列セット{"LE"}が渡された場合、オレンジのCalendarActivityRampが返されます。

- 文字列セット{"TF"}が渡された場合、青のCalendarActivityRampが返されます。

15.6.3 日付のカスタマイズ方法

月表示の日のヘッダーに日付の数値文字列以外の内容を表示する場合、dateCustomizer属性を、日付に表示する内容を決定するDateCustomizerクラスの実装にバインドできます。

日付文字列をカスタマイズする手順:

1. oracle.adf.view.rich.util.DateCustomizerクラスのサブクラスを作成します。このサブクラスは、次のスキニング・キーを使用して、表示する内容を決定します。

- af|calendar::month-grid-cell-header-misc: 月表示の日のヘッダーの左側に表示する内容を決定します。

- af|calendar::month-grid-cell-header-day-link: 日付に表示する文字列を決定します。
例15-4に、DemoDateCustomizerクラスを示します。このクラスでは、週の初日に週番号が表示され、その月の日のかわりに、図15-10に示すように特定の日までのカウントダウン数値が表示されます。

例15-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属性をバインドします。

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

この章では、ADF Facesコンポーネントを使用して出力テキスト、イメージおよびアイコンを表示する方法と、ユーザーがビデオ・クリップや音声クリップを再生できるコンポーネントの使用方法を説明します。

この章では、次の項目について説明します。

- 16.1項「出力テキスト、イメージ、アイコンおよびメディア・コンポーネントの概要」

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

- 16.3項「アイコンの表示」

- 16.4項「イメージの表示」

- 16.5項「リンクとしてのイメージの使用」

- 16.6項「カルーセルでのイメージの表示」

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

- 16.8項「ビデオ・クリップおよび音声クリップの再生」

16.1 出力テキスト、イメージ、アイコンおよびメディア・コンポーネントの概要

ADF Facesには、テキスト、アイコン、イメージを表示するためのコンポーネント、およびJSFページで音声クリップやビデオ・クリップを再生するためのコンポーネントが用意されています。

読取り専用テキストは、outputTextまたはoutputFormattedコンポーネントを使用して表示できます。outputFormattedコンポーネントを使用すると、限られたHTMLマークアップのセットをコンポーネントの値に追加でき、テキストの簡単な書式設定が可能になります。

多くのADF Facesコンポーネントには、アイコンを関連付けできます。たとえば、メニューでは、各メニュー項目にアイコンを関連付けできます。それぞれのアイコンに使用するイメージは、そのメニュー項目コンポーネント自体のicon属性の値として識別します。アイコンがサポートされているコンポーネントへのアイコン追加の詳細と手順は、それぞれのコンポーネントの章で説明されています。コンポーネント内で使用できるアイコンに加えて、ADF Facesにはメッセージを表示する際に使用されるアイコンもあります。これらのアイコンは、メッセージの外でも使用できます。

ページにイメージを表示するには、imageコンポーネントを使用します。イメージを使用して、リンク(イメージ・マップを含む)として使用することも、サーバーのステータスを表すために使用することもできます。カルーセルにイメージのコレクションを表示できます。これにより、ユーザーは、コレクションを回転して各イメージを表示できます。

メディア・コンポーネントは、音声クリップやビデオ・クリップを再生できます。これらのコンポーネントには、ページでの項目の表示方法を定義するための属性があります。

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

ページに出力テキストを表示するためのADF Facesコンポーネントは2つあります。outputTextは書式設定されていないテキストを表示し、outputFormattedはテキストを表示して限られた範囲の書式設定オプションを設定できます。

明示的に指定されたシンプル・テキストや、リソース・バンドルまたはBeanからのシンプル・テキストを表示するには、outputTextコンポーネントを使用します。valueプロパティの値として表示されるようにテキストを定義します。次に例を示します。

<af:outputText value="The submitted value was: "/>

例16-1に、2つのoutputTextコンポーネントを示します。1つ目では表示されるテキストが明示的に指定され、2つ目ではマネージドBeanからテキストが取得され、表示可能なテキスト値に値が変換されます(変換の詳細は、変換の追加に関する項を参照してください)。

例16-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の特殊文字をエスケープするかどうかを指定できます。デフォルトでは、特殊文字はエスケープされます。

例16-2に、2つのoutputTextコンポーネントを示します。1つ目ではescape属性にデフォルト値trueが使用され、2つ目では属性がfalseに設定されています。

例16-2 escapeプロパティ・セットを使用しているoutputTextと使用していないoutputText

<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"/>
<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"
escape="false"/>

図16-1に、異なる2つのescape属性の設定をブラウザで表示した場合の結果の違いを示します。

図16-1 escape属性を使用した出力テキスト

絶対に必要な場合以外、escape属性はfalseに設定しないでください。限られた数のHTMLタグを使用できるoutputFormattedコンポーネントを使用することをお薦めします。

outputFormattedコンポーネントでも、outputTextコンポーネント同様、valueプロパティに指定されたテキストが表示されますが、値にHTMLタグを含めることができます。値の一部のみを特定の方法で書式設定する場合は、outputFormattedコンポーネントの書式設定機能を使用します。コンポーネント値全体に同じスタイル設定を使用する必要がある場合は、値にHTMLを使用するかわりに、コンポーネント全体にスタイルを適用します。コンポーネントのすべてのインスタンスを特定の方法で書式設定する場合は、カスタム・スキンを作成する必要があります。インライン・スタイルの使用方法およびスキンの作成方法の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

例16-3に、値の一部のみが太字で表示されるoutputFormattedコンポーネントを示します。

例16-3 一部のテキストを太字にするoutputFormattedの使用

<af:outputFormatted value="&lt;b>This is in bold.&lt;/b> This is not bold"/>

図16-2に、コンポーネントによりテキストがどのように表示されるかを示します。

図16-2 outputFormattedコンポーネントを使用して書式設定されたテキスト

16.2.1 出力テキストの表示方法

出力テキストを表示する前に、値の一部を特別な方法で書式設定するかどうかを確認します。

出力テキストを表示する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「出力テキスト」をドラッグ・アンド・ドロップします。outputFormattedコンポーネントを作成するには、コンポーネント・パレットから書式設定された出力をドラッグ・アンド・ドロップします。

ヒント:

値の一部に特別な書式設定を適用する場合は、outputFormattedコンポーネントを使用します。

ヒント:

アクティブ・データを使用したコンポーネントのテキストの変更をサポートする場合(たとえば、データソースからプッシュされているデータによって、表示されるテキストを決定する場合)、outputTextコンポーネントのかわりに、activeOutputTextコンポーネントを使用する必要があります。コンポーネント・パレットから「出力テキスト(アクティブ)」をドラッグして、activeOutputTextコンポーネントを作成します。

2. プロパティ・インスペクタの「共通」パネルを開き、value属性を表示する値に設定します。outputFormattedコンポーネントを使用している場合は、表16-1および表16-2の説明に従い、HTML書式設定コードを使用して必要に応じてテキストを書式設定します。
outputFormattedコンポーネントではstyleUsage属性もサポートされています。この属性値により、テキストに次に示す事前定義済のスタイルが適用されます。

- inContextBranding

- instruction

- pageStamp

図16-3に、styleUsage値によりコンポーネントにどのようなスタイルが適用されるかを示します。

図16-3 styleUsage属性の値

注意:

styleUsageおよびstyleClass属性の両方が設定されている場合は、styleClass属性が優先されます。

16.2.2 outputFormattedコンポーネントで使用可能な書式設定コードと文字コードについて

特定の書式設定コードと文字コードのみを使用できます。表16-1に、outputFormattedコンポーネントの値の書式設定に使用可能な書式設定コードをリストします。

表16-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>

アンカー

表16-2に、値の特殊文字を表示するための文字コードをリストします。

表16-2 af:outputFormatted値で使用するための文字コード

文字コード

文字

&lt;

次より小さい

&gt;

次より大きい

&amp;

アンパサンド

&reg;

登録商標

&copy;

コピーライト

&nbsp;

改行なしの空白

&quot;

二重引用符

属性class、styleおよびsizeは、href構成と同様に、outputFormattedコンポーネントのvalue属性でも使用できます。その他すべてのHTMLタグは無視されます。

注意:

セキュリティ上の理由から、出力値ではJavaScriptはサポートされていません。

16.3 アイコンの表示

ADF Facesには、図16-4に示されているように、メッセージ・コンポーネントで使用される一連のアイコンが用意されています。

図16-4 ADF Facesのアイコン

アイコンをメッセージ・コンポーネントの外に表示する必要がある場合は、iconコンポーネントを使用し、表示するアイコン・タイプの名前を指定します。

注意:

アイコンに使用されるイメージは、アプリケーションで使用されているスキンによって決定されます。イメージを変更する場合は、カスタム・スキンを作成します。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ADF Facesアプリケーションでメッセージを使用すると、アイコンが自動的に追加されます。メッセージ・コンポーネントに追加する必要はありません。ただし、アイコンをメッセージ・コンポーネントの外に使用できます。アプリケーションのスキンに定義されている標準アイコンのいずれかを表示するには、iconコンポーネントを使用します。

標準アイコンを表示する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「アイコン」をドラッグ・アンド・ドロップします。

2. 図16-4に示されているように、「共通」セクションを開き、Nameをアイコン機能の名前に設定します。たとえば、中に白いXがある赤い丸を表示する場合は、Nameをerrorに設定します。

3. 「外観」セクションを開き、ShortDescをアイコンの代替テキストとして表示するテキストに設定します。

16.4 イメージの表示

ページにイメージを表示するには、imageコンポーネントを使用し、source属性をファイルが存在するURIに設定します。imageコンポーネントでは、イメージの詳細な説明へのリンクを提供することで、アクセシビリティの説明テキストもサポートされています。

imageコンポーネントは、リンクとして使用することも、イメージ・マップを含めることもできますが、goLinkコンポーネント内に配置する必要があります。詳細は、リンクとしてのイメージの使用に関する項を参照してください。

イメージを表示する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「イメージ」をドラッグ・アンド・ドロップします。

ヒント:

アクティブ・データを使用したイメージのsource属性の変更をサポートする場合(たとえば、データソースからプッシュされているデータによって、表示されるイメージを決定する場合)、imageコンポーネントのかわりに、activeImageコンポーネントを使用する必要があります。コンポーネント・パレットから「イメージ(アクティブ)」をドラッグして、activeImageコンポーネントを作成します。

2. 「イメージの挿入」ダイアログで、次の設定を行います。

- ShortDesc: イメージの代替テキストとして使用するテキストに設定します。

- Source: イメージ・ファイルへのURIを入力します。

3. イメージのより長い説明を指定する場合は、プロパティ・インスペクタで、LongDescURL属性をその情報が存在するURIに設定します。

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

ADF Facesには、オプションのテキストとともにイメージをリンクとしてレンダリングするcommandImageLinkコンポーネントがあります。ユーザーがアイコンにマウスを置いた場合や、アイコンが押された場合または無効化された場合に、別々のアイコンを設定できます。commandImageLinkコンポーネントの詳細は、ボタンおよびリンクのナビゲーション目的での使用に関する項を参照してください。

指定されたURIへのナビゲーションにイメージを使用する場合は、イメージをgoLinkコンポーネントで囲み、必要な場合はイメージ・マップにリンクします。

イメージは、1つ以上の移動先へのgoLinkコンポーネントとして使用できます。単一の移動先への単純なリンクとしてイメージを使用する場合は、goLinkコンポーネントを使用してイメージを囲み、goLinkコンポーネントのdestination属性をリンクの移動先のURIに設定します。

グラフィックの異なる領域が別々のURIにナビゲートするグラフィカルなナビゲーション・メニューとしてイメージを使用している場合は、imageコンポーネントをgoLinkコンポーネントで囲み、イメージに対するサーバー側のイメージ・マップを作成します。

1つ以上のgoLinkコンポーネントとしてイメージを使用する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「実行リンク」をドラッグ・アンド・ドロップします。

2. goLinkコンポーネントの子として、「イメージ」をドラッグ・アンド・ドロップします。

3. 「イメージの挿入」ダイアログで、次の設定を行います。

- ShortDesc: イメージの代替テキストとして使用するテキストに設定します。

- Source: イメージ・ファイルへのURIを入力します。

4. イメージの異なる領域を別々の移動先にリンクさせる場合は、次のようにします。

- イメージのイメージ・マップを作成し、サーバーに保存します。

- プロパティ・インスペクタで、ImageMapType属性をserverに設定します。

- goLinkコンポーネントを選択し、プロパティ・インスペクタで、Destinationをサーバーのイメージ・マップのURIに設定します。

5. イメージ全体を単一の移動先にリンクする場合は、goLinkコンポーネントを選択し、移動先のURIをDestinationの値として入力します。

16.6 カルーセルでのイメージの表示

図16-5に示すように、動くカルーセルにイメージを表示できます。ユーザーは、下部にあるスライダを使用するか、補助イメージの1つをクリックして、前面にあるイメージを変更し、特定のイメージを前面に表示します。

図16-5 ADF Facesのカルーセル

デフォルトで、カルーセルは水平に表示されます。水平方向のカルーセル内にあるオブジェクトは中央揃えで配置され、カルーセル自体はコンテナで水平に配置されます。

参照カード・ファイルの表示など、必要に応じて、垂直に表示されるようにカルーセルを構成できます。デフォルトでは、図16-6に示すように、垂直方向のカルーセル内にあるオブジェクトは中央揃えで配置され、カルーセル自体は垂直に配置されます。カルーセルの位置属性を使用して、位置を変更できます。

図16-6 垂直のカルーセル・コンポーネント

ベスト・プラクティス:

一般的に、カルーセルは、子(panelSplitterまたはpanelStretchLayoutなど)を拡大する親コンポーネントに配置する必要があります。子を拡大するコンポーネントにカルーセルを配置しない場合、カルーセルはデフォルトの大きさ(幅500px、高さ300px)で表示されます。この大きさは変更できます。

図16-5に示すように、カルーセル・コンポーネントは循環モードで表示できます。また、図16-7に示すように、現在のイメージのみを表示するようにカルーセルを構成できます。

図16-7 1つのイメージのみを表示するカルーセル

イメージ全体を参照するために使用するコントロールを構成することもできます。次の項目に移動する矢印や前の項目に移動する矢印があり、複数のイメージにまたがるスライダ(図16-5を参照)を表示できます。また、次の項目に移動するボタンや前の項目に移動するボタン(図16-7を参照)も表示できます。あるいは、次の項目に移動するボタンや前の項目に移動するボタンをスライダ・カウンタ(図16-8を参照)とともに表示できます。

図16-8 スライダ・カウンタのある、次の項目や前の項目に移動するボタン

デフォルトでは、カルーセルが循環モードで表示するように構成されている場合、補助アイテム(現在、中央に表示されていないアイテム)にポインタを置くと、そのアイテムが枠で囲まれ選択可能であることが示されます(この枠は、アプリケーションがFusion FX v1.2以降のスキンを使用している場合にのみ、表示されることに注意してください)。図16-9に示すように、アイテムが移動し、最大サイズで表示されるように、カルーセルを構成できます。

図16-9 マウスを置いた場所に移動する補助アイテム

循環モードに設定した場合、イメージ間のスペースも構成できます。また、補助イメージのサイズも構成できます。デフォルトでは、イメージ間のスペースは先行イメージのサイズの0.45倍に設定されています。この結果、隣合うイメージは重なります。図16-5に示すように、先行イメージの0.8倍になるように、補助イメージのサイズは0.8に設定されています。この設定を変更すると、カルーセルの外観を変更できます。たとえば、カルーセルをスライドのように表示させる場合、イメージ間のスペースを1.1に設定し、補助アイテムのサイズは1に設定します。これによって、図16-10に示すように、補助アイテムはすべて同じサイズになります。

図16-10 スライドのように表示されるカルーセルの構成

子のcarouselItemコンポーネントは、カルーセルにオブジェクトおよびオブジェクトのタイトルを表示します。表示する各オブジェクトにcarouselItemコンポーネントを作成し、これらのコンポーネントを各オブジェクトにバインドするかわりに、carouselコンポーネントを完全なコレクションにバインドします。次に、コンポーネントは、ツリーが各データ行にスタンプ設定するのと同様に、各アイテムの値をスタンプ設定して、1つのcarouselItemコンポーネントを繰り返しレンダリングします。各アイテムがスタンプ設定されると、現在のアイテムのデータが、carouselコンポーネントのvar属性を使用するEL式によって対応可能なプロパティにコピーされます。カルーセルのレンダリングが完了したら、このプロパティは削除されるか前の値に戻ります。カルーセルにはnodeStampファセットが含まれます。これは、各アイテムのテキストと短い説明を表示するために使用されるcarouselItemコンポーネントのホルダーであり、各アイテムに表示されるイメージに対する親コンポーネントでもあります。

たとえば、図16-5に示されたADF FacesデモのcarouselItem JSFページには、各ADF Facesコンポーネントのイメージを表示するcarouselコンポーネントが含まれています。demoCarouselItem (CarouselBean.java)マネージドBeanには、これらのコンポーネントすべてのリストが含まれています。carouselコンポーネントの値属性は、このリストが存在するBeanのitemsプロパティにバインドされます。カルーセルのコンポーネントのvar属性は、表示する各アイテムの値を保持するために使用されます。carouselItemコンポーネントとimageコンポーネントの両方がこれを使用し、各アイテムの正しい値を取得します。例16-4に、カルーセルのJSFページ・コードを示します。カルーセルでのスタンプの動作の詳細は、ツリーへのデータの表示に関する項を参照してください。

例16-4 カルーセル・コンポーネントの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コンポーネントは子コンポーネントのみを拡大します。carouselItem内に1つのimageコンポーネントを配置する場合、アイテムに割り当てられた場所の大きさに合うように、イメージが拡大されます(ユーザーがカルーセルを動かすと、寸法が大きくなったり小さくなったりします)。

ベスト・プラクティス:

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 Business Componentsを作成でき、作成するとモデルが作成されます。その後、カルーセルを宣言的に作成でき、そのカルーセルは自動的にそのモデルにバインドされます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のADF Facesカルーセル・コンポーネントの使用に関する項を参照してください。

カルーセル・コンポーネントは仮想化されており、サーバーのコンポーネントに対して使用可能なすべてのアイテムがクライアントに配信されて表示されるわけではありません。カルーセルを構成して、データソースから一度に一定数の行をフェッチします。レンダリング時にすぐにデータをコンポーネントに配信することも、コンポーネントのシェルがレンダリングされた後に遅延フェッチすることもできます。デフォルトでは、カルーセルは最初のリクエストに対して遅延フェッチを行います。ページにこれらのコンポーネントが1つ以上含まれる場合、ページでは最初は標準のライフサイクルが実行されます。ただし、最初のリクエスト中にデータをフェッチするカルーセルのかわりに、特定の個別の部分ページ・レンダリング(PPR)・リクエストがコンポーネントで実行され、カルーセルのフェッチ・サイズの値として設定されたアイテム数が返されます。ページのレンダリング直後であるため、レンダー・レスポンス・フェーズのみがカルーセルに対して実行され、対応するデータのフェッチおよび表示が可能になります。後続のデータ・フェッチが発生した場合(別のイメージ・セットのカルーセルを回転させた場合など)、別のPPRリクエストが実行されます。

パフォーマンスのヒント:

ページにカルーセル以外のコンポーネントが複数含まれる場合は、遅延配信を使用する必要があります。遅延配信を使用すると、データが使用可能になる前に、初期ページのレイアウト・コンポーネントおよびその他のコンポーネントが最初にレンダリングされます。

カルーセルがページで唯一のコンテキストである場合か、カルーセルが多数のアイテムを戻すことを想定されていない場合、即時配信を使用します。この場合、遅延配信を使用する場合よりも、レスポンス時間は早くなります(または、単に速いと感じられるだけの場合もあります)。2番目のリクエストがサーバーに送信されないため、ユーザーのレスポンス時間が速くなり、サーバーのCPU使用率も向上します。ただし、フェッチ・ブロックとして構成されたアイテムの数のみが最初に返されることに注意してください。遅延配信と同様に、ユーザーのアクションにより後続のデータ・フェッチが実行される場合は、次のアイテム・セットが配信されます。

スライダ・コントロールを使用すると、コレクションを移動できます。通常、スライダのサムは総オブジェクト数の中の現在のオブジェクト番号(たとえば、20個中の6番目など)を表示します。総オブジェクト数が大きすぎて計算できない場合、スライダのサムは現在のオブジェクト番号のみを表示します。たとえば、カルーセルが会社の従業員ディレクトリに使用される場合などです。デフォルトでは、ディレクトリで全従業員の顔写真を表示する場合、時間をかけてデータベースを呼び出さなければ、正確に94,409名の従業員のデータがシステム内に存在することを把握できません。

カルーセルと連携して、他のコンポーネントを使用できます。たとえば、ツールバーやメニュー・バーを追加し、これらにボタンやメニュー項目を追加できます。これにより、ユーザーは現在のオブジェクトに対してアクションを実行できます。

16.6.1 カルーセルの作成方法

カルーセルを作成するには、まず、表示するイメージが含まれるデータ・モデルを作成する必要があります。次に、carouselコンポーネントをそのモデルにバインドし、carouselItemコンポーネントをカルーセルのnodeStampファセットに挿入します。最後に、imageコンポーネント(または、imageコンポーネントが含まれる他のコンポーネント)を子としてcarouselItemコンポーネントに挿入します。

カルーセルを作成する手順:

1. 表示するイメージのコレクションを提供するデータ・モデルを作成します。データ・モデルは、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クラスを参照してください。

2. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「カルーセル」をドラッグ・アンド・ドロップします。

3. プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。

- Orientation: デフォルトで、カルーセルは水平に表示されます。図16-6に示すように、垂直に表示する場合、verticalを選択します。horizontalに設定した場合、halign属性を使用して、アイテムの配置を構成する必要があります。verticalに設定した場合、valign属性を使用して、アイテムの配置を設定します。

- Halign: 垂直のカルーセルにアイテムをどのように表示するかを指定します。有効な値は次のとおりです。

- Center: 中央に揃うようにアイテムを配置します。これはデフォルト設定です。

- End: 右端が揃うようにアイテムを配置します(ブラウザが左から右に表記する言語を表示している場合)。

- Start: 左端が揃うようにアイテムを配置します(ブラウザが左から右に表記する言語を表示している場合)。

- Valign: 水平のカルーセルにアイテムをどのように表示するかを指定します。有効な値は次のとおりです。

- Bottom: 下端が揃うようにアイテムを配置します。

- Middle: 中央に揃うようにアイテムを配置します。これはデフォルト設定です。

- Top: 上端が揃うようにアイテムを配置します。

- Value: カルーセルをモデルにバインドします。

4. 「データ」セクションを開いて次の設定を行います。

- Var: 個々のアイテム・データにアクセスするために、ELで使用される変数を入力します。

- VarStatus: カルーセルのステータスにアクセスするために、ELで使用される変数を入力します。varStatusの共通プロパティは、次のとおりです。

- model: このコンポーネントのCollectionModelを返します。

- index: ゼロベースのアイテム索引を返します。

5. 「外観」セクションを開き、アイテムが返されない場合に表示するテキストにEmptyTextを設定します。リソース・バンドルを使用する場合は、ドロップダウン・メニューを使用して「テキスト・リソースの選択」を選択します。

6. 「動作」セクションを開き、次の設定を行います。

- FetchSize: 各データ・フェッチで戻されるブロックのサイズを設定します。

- ContentDelivery: データを送信するタイミングを指定します。contentDelivery属性がimmediateに設定されている場合、カルーセルのレンダリングと同時にアイテムがフェッチされます。contentDelivery属性がlazyに設定されている場合は、後続のリクエスト中にアイテムがフェッチされてクライアントに送信されます。

- CarouselSpinListener: カルーセルの回転が実行されたときにロジックの実行が必要な場合、カルーセルの回転を処理するハンドラ・メソッドにバインドします。例16-5に、回転が実行されたときに詳細パネルを再描画するCarouselBeanのハンドラ・メソッドを示します。

例16-5 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: 先行イメージからどのくらいイメージが離れているかを決定する数値を設定します。デフォルト値は0.45です。

- AuxiliaryPopOut: hoverを設定すると、補助イメージにマウスを置いたときに補助イメージが最大サイズでレンダリングされます。デフォルトはoffです。

- AuxiliaryScale: 先行イメージと比較した各イメージのサイズを決定する数値を設定します。1に設定すると、すべてのイメージが同じサイズになります。1より小さい値を設定すると、各イメージは少しずつ小さくなり、1より大きい値を設定すると、大きくなります。デフォルトでは、設定は0.8です。各イメージは先行イメージの80%の大きさになります。

- ControlArea: カルーセルのイメージ全体を参照するために使用するコントロールを指定します。有効な値は次のとおりです。

- full: スライダは現在のイメージよりも大きくなり、次の項目に移動するボタンと前の項目に移動するボタンを表示します。

- small: スライダのサイズは現在のイメージのサイズになり、次の項目に移動するボタンと前の項目に移動するボタンを表示します。

- compact: 次の項目に移動するボタンと前の項目に移動するボタンのみが表示されます。

- none: スライダおよびコントロールは表示されません。

- DisplayItems: 複数のイメージをカルーセルに表示するには、circularを選択します。一度に1つのイメージをカルーセルに表示するには、oneByOneを選択します。

9. コンポーネント・パレットから「カルーセル・アイテム」をCarouselコンポーネントのnodeStampファセットにドラッグします。
カルーセルのvar属性に設定された変数の値を使用して、CarouselItemコンポーネントの属性をデータ・モデルのプロパティにバインドします。たとえば、例16-4のカルーセルは、var属性の値としてitemを使用しています。したがって、carouselItemのtext属性の値はitem.titleとなります(titleが、データ・モデルのカルーセル・アイテムに使用するテキストにアクセスするために使用するプロパティである場合)。

10. コンポーネント・パレットからイメージをドラッグし、carouselItemに子としてドロップします。
カルーセルのvar属性に設定された変数の値を使用して、imageコンポーネントの属性をデータ・モデルのプロパティにバインドします。たとえば、例16-4のカルーセルは、var属性の値としてitemを使用しています。したがって、imageのsource属性の値はitem.urlとなります(urlが、イメージへのアクセスに使用するプロパティである場合)。

さらに多くの機能が必要な場合、イメージ・コンポーネントを他のコンポーネントで囲むことができます。たとえば、図16-11に、イメージがpanelGroupLayoutコンポーネントに囲まれていて、clientListenerを使用しJavaScript関数を呼び出し、メニューとナビゲーション・バーを表示するカルーセルを示します。

図16-11 カルーセルでの複雑なレイアウトの使用

例16-6に、対応するページ・コードを示します。

例16-6 カルーセルの複雑なレイアウト

<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:commandImageLink . . .
/>
<af:outputText id="pageInfo" value="Page 1 of 1"/>
<af:commandImageLink . . .
/>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:panelGroupLayout>
</af:carouselItem>

パフォーマンスのヒント:

カルーセルの構造が単純であれば、処理が速くなります。

16.6.2 カルーセル・コンポーネントおよび他のブラウザについて

一部のブラウザでは、カルーセルのアイテムの外観に凝った装飾が施されるものがあります。たとえば、SafariとGoogle Chromeでは、カルーセルのアイテムのまわりに繊細な影が表示され、図16-12に示すように、現在のアイテム以外のアイテムに明るいオーバーレイが適用されていて、この補助アイテムが現在のアイテムではないことを示しています。

図16-12 Google Chromeに表示されたカルーセル・コンポーネント

図16-13に、Internet Explorerで表示された同じコンポーネントを示します。

図16-13 Microsoft Internet Explorerに表示されたカルーセル・コンポーネント

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

ADF Facesには、サーバー・アクティビティを示すために使用できるstatusIndicatorコンポーネントが用意されています。表示される内容は、アプリケーションが使用しているスキンおよびサーバーの構成方法によって異なります。デフォルトでは、次のものが表示されます。

- アプリケーションが標準のデータ転送サービスを使用するように構成されている場合、データ転送中に次のアニメーション化されたスピニング・アイコンが表示されます。

サーバーがビジーではない場合、次のアイコンが表示されます。

- アプリケーションがアクティブ・データ・サービス(ADS)を使用するように構成されている場合、ステータス・インジケータに表示される内容は、ADSがどのように構成されているかによって異なります。

注意:

ADSを使用すると、アプリケーションをアクティブ・データ・ソースにバインドできます。ADSを使用するには、Fusionテクノロジ・スタックを使用する必要があります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アクティブ・データ・サービスの使用」を参照してください。

ADSはデータをモデルにプッシュするように構成できます。または、指定した間隔で、アプリケーションがデータをポーリングするように構成することもできます。表16-3に、プッシュ・モードおよびポーリング・モードのサーバー状態を表示するために使用されるアイコンを示します(アイコンは実際はアニメーション化されています)。

表16-3 ADSのステータス・インジケータで使用されるアイコン

アイコン

プッシュ・モード

プル・モード

サーバーへの最初の接続試行時。

サーバーへの最初の接続試行時。

最初の接続が正常に確立されたとき。

最初の接続が正常に確立されたとき、および接続が再接続されたとき。

サーバーに再接続するための後続の試行が行われたとき。

すべてのポーリング・リクエストの前。

接続を確立または再確立できないとき。

構成された回数のポーリング試行が失敗したとき。

ステータス・インジケータ・コンポーネントをページにドロップすると、スキンを使用して、コンポーネントで使用される実際のイメージ・ファイルを変更できます。スキンの使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ステータス・インジケータ・アイコンを使用する手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「ステータス・インジケータ」をドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタを使用して、必要な属性を設定します。

ヒント:

属性の設定のヘルプとして、フィールドのドロップダウン・メニューを使用して、属性の説明を表示します。

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

ADF Facesのmediaコンポーネントを使用すると、アプリケーション・ページにビデオ・クリップや音声クリップを含めることができます。

メディア・コントロールでは、クロス・プラットフォームのメディア表示の複雑な2つの側面(メディアの表示に最適なプレーヤの決定、およびメディア・プレーヤのサイズ変更)を処理します。

ユーザーに表示するプレーヤのサイズとともに、各クリップに適したメディア・プレーヤを指定できます。デフォルトで、ADF Facesでは、メディア・リソースのMIMEタイプを使用して、最適なメディア・プレーヤおよび使用するデフォルトの内部プレーヤ・サイズが決定されますが、コンテンツ・タイプはcontentType属性を使用して指定できます。

ユーザーが使用できるコントロール、およびクリップを自動的に再生するかどうか、連続再生するか指定された回数再生するかなど、その他のプレーヤ機能を指定できます。

16.8.1 音声クリップおよびビデオ・クリップの再生方法

ページにmediaコンポーネントを追加したら、デフォルトで使用するメディア・プレーヤ、プレーヤと画面のサイズ、コントロールおよびクリップをリプレイするかどうかを構成できます。

アプリケーション・ページに音声クリップまたはビデオ・クリップを含める手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「メディア」をドラッグ・アンド・ドロップします。

2. 「メディアの挿入」ダイアログで、次の属性を設定します。

- Source: 再生するメディアへのURIを入力します。

- StandbyText: コンテンツのロード中に表示するメッセージを入力します。

3. プロパティ・インスペクタの「共通」セクションを開き、次の属性を設定します。

- Player: クリップの再生にデフォルトで使用されるメディア・プレーヤを選択します。Real Player、Windows Media PlayerまたはApple QuickTime Playerから選択できます。
または、ユーザー・エージェントの組込みのコンテンツ・タイプ・マッピングに基づいて、メディア・リソースの再生を開始するリンクをページに作成できます。メディア・コントロールにより、次の手順で、適切なメディア・プレーヤの選択が試行されます。

- コンテンツのプライマリMIMEタイプがイメージの場合は、組込みのユーザー・エージェント・サポートが使用されます。

- player属性でメディア・プレーヤが指定されていて、そのプレーヤをユーザー・エージェントで使用でき、メディア・リソースを表示できる場合は、そのプレーヤが使用されます。

- あるプレーヤがメディア・リソースの再生に最適で、そのプレーヤをユーザー・エージェントで使用できる場合は、そのプレーヤが使用されます。

- ユーザー・エージェントであるプレーヤが特に優先されており、そのプレーヤでメディア・リソースを再生できる場合は、そのプレーヤが使用されます。

- ページに表示されているリンクに接続しているプレーヤが使用されます。

- Autostart: ロード後すぐにクリップの再生を開始する場合はTrueを設定します。

- ContentType: 再生するメディアのMIMEタイプを入力します。これは、使用するプレーヤ、コントロールの構成、および表示サイズの決定に使用されます。

4. プロパティ・インスペクタの「外観」セクションを開き、次の設定を行います。

- Controls: 次のようにして、プレーヤに表示するコントロールの量とタイプを選択します。
使用可能なコントロールのセットはプレーヤによって異なるため、実際のコントロールをリストするのではなく、一般的な方法で表示するコントロールのセットを定義します。たとえば、使用可能なすべてのコントロールや、最も一般的に使用されるコントロールをプレーヤに表示することも、コントロールを表示しないこともできます。

たとえば、例16-7では、mediaコンポーネントにall設定が使用されています。

例16-7 メディア・プレーヤのコントロール

<af:media source="/images/myvideo.wmv" controls="all"/>

図16-14に、プレーヤがユーザーに対してどのように表示されるかを示します。

図16-14 すべてのコントロールが表示されたメディア・プレーヤ

次の値が有効です。

- 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に設定すると、クリップは連続して再生されます。この属性をその他の数値に設定すると、クリップは指定された回数再生されます。

例16-8に、ページのソースのaf:mediaコンポーネントを示します。このコンポーネントでは、ロードされるとすぐにビデオ・クリップの再生が開始され、ユーザーが停止するまで連続して再生されます。プレーヤには、使用可能なコントロールがすべて表示されます。

例16-8 ビデオ・クリップを連続再生する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"/>

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

この章では、ADF Facesコンポーネントにヒントおよびメッセージを定義および表示する方法と、様々なレベルのヘルプ情報をユーザーに提供する方法を説明します。

この章では、次の項目について説明します。

- 17.1項「ヒントおよびメッセージの表示の概要」

- 17.2項「コンポーネントのヒントの表示」

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

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

- 17.5項「コンポーネントへのヘルプの表示」

17.1 ヒントおよびメッセージの表示の概要

ADF Facesでは、様々な方法でアプリケーションに情報テキストを表示できます。精巧なヘルプ・システムだけでなく、簡単なヒント・テキスト、検証および変換のヒント・テキストやエラー・メッセージも作成できます。

多くのADF Facesコンポーネントでは、shortDesc属性がサポートされています。この属性は、ユーザーがコンポーネントの上にカーソルを置いたときに、ほとんどのコンポーネントにヒント情報を表示します。図17-1に、ツールバー・ボタンに構成されているヒントを示します。ヒントの作成の詳細は、コンポーネントのヒントの表示に関する項を参照してください。

図17-1 情報を表示するヒント

ヒントと同様に、EditableValueHolderコンポーネント(inputTextコンポーネントまたは選択コンポーネントなど)も、検証および変換に使用するヒントを表示できます。検証または変換を構成すると、デフォルトのヒントにより注意ウィンドウが自動的に表示されます(詳細は、第6章「入力の検証および変換」を参照してください)。たとえば、ユーザーがFile Explorerアプリケーションの「ヘルプ」→フィードバックを報告をクリックしたとき、ダイアログに、技術サポートが連絡する日時を入力できる場所が表示されます。inputDateコンポーネントにはコンバータが含まれているため、ユーザーがフィールドをクリックすると、図17-2に示すように、予想されるパターンを示すヒントが注意ウィンドウに表示されます。inputDateコンポーネントに最小値または最大値も構成されている場合は、その情報もヒントに表示されます。これらのヒントは、コンバータおよびバリデータにより自動的に表示されます。

図17-2 アタッチされている、メッセージを含むコンバータおよびバリデータ

ADF Facesでは、標準のJSFメッセージングAPIが使用されます。JSFでは、addMessage(java.lang.String clientId, FacesMessage message)メソッドを使用して、FacesMessageインスタンスをFacesContextオブジェクトに追加できるようにすることで、メッセージング用の組込みフレームワークがサポートされています。通常、作成されるメッセージは2種類です。1つは、コンポーネント・レベルのメッセージで、これはaddMessageメソッドに渡された任意のクライアントIDに基づいて特定のコンポーネントに関連付けられています。もう1つは、グローバル・レベルのメッセージで、これは、クライアントIDがaddMessageメソッドに渡されなかったため、コンポーネントに関連付けられていません。変換または検証がEditableValueHolderのADF Facesコンポーネントで失敗した場合、FacesMessagesオブジェクトがFacesContextインスタンスのメッセージ・キューに自動的に追加され、そのコンポーネントのIDが渡されます。これらのメッセージは、コンポーネントの注意ウィンドウに表示されます。ADF Facesコンポーネントは、独自のメッセージを表示できます。タグに追加する必要はありません。

たとえば、図17-2に表示されているフィールドにユーザーが不適切な日付を入力した場合、図17-3に示すようにエラー・メッセージが表示されます。エラー・メッセージは、ヒントともに注意ウィンドウに表示されることに注意してください。

図17-3 注意ウィンドウに表示されている検証および変換のエラー

ADF Facesコンポーネント以外にメッセージを表示する場合、または注意ウィンドウではなく、インラインでメッセージを表示する場合は、ADF Faces messageコンポーネントを使用します。

FacesMessagesコンポーネントのみでなく、documentタグも、すべてのグローバルなFacesMessagesオブジェクト(関連付けられているコンポーネントIDがない)の処理および表示を行います。コンポーネント・メッセージと同じように、表示するメッセージにタグを追加する必要はありません。グローバル・メッセージ(または3つ以上のコンポーネント・メッセージ)が作成されると、図17-4に示すように、キューのすべてのメッセージがポップアップ・ウィンドウに表示されます。

図17-4 documentにより表示されるグローバル・メッセージおよびコンポーネント・メッセージ

ただし、ポップアップ・ウィンドウではなく、ページにメッセージを表示する場合は、ADF Faces messagesコンポーネントを使用できます。コンポーネントのヒントおよびメッセージ表示の詳細は、検証および変換用のヒントとエラー・メッセージの表示に関する項を参照してください。

ヒント:

ADF Facesには検証および変換用のメッセージがありますが、標準のJSFメッセージングAPIを使用して、キューにFacesMessagesオブジェクトを追加できます。追加すると、ADF Facesにより、メッセージ・レベルに基づいて、次のようなアイコンがメッセージとともに表示されます。

コンポーネントごとに独自のメッセージを表示するかわりに、panelLabelAndMessageコンポーネントを使用してコンポーネントをグループ化し、1つの領域にメッセージを表示できます。コンポーネントをグループ化する必要がある場合に便利です。たとえば、File Explorerアプリケーションには、ユーザーが電話番号を入力するpanelLabelAndMessageコンポーネントが使用されています。電話番号入力フィールドは、実際には3つの別々のinputTextコンポーネントです。panelLabelAndMessageコンポーネントに、3つのinputTextコンポーネントがラップされています。それぞれに独自のラベルおよびメッセージを表示するかわりに、図17-3に示すように、3つのコンポーネントにはラベルとメッセージが1つずつあります。詳細は、単一のラベルおよびメッセージを使用したコンポーネントのグループ化に関する項を参照してください。

個々のコンポーネント・インスタンスのメッセージを構成するかわりに、アプリケーション全体で再利用可能な情報を提供する別々のヘルプ・システムを作成できます。ヘルプ情報は異なるタイプのプロバイダを使用して作成し、UIコンポーネントからヘルプ・テキストを参照します。次に、ADF Facesにサポートされている3つのタイプのヘルプを示します。

- 定義: 図17-5に示すように、ユーザーがアイコン上にマウスを置くと、ヘルプ・テキストが表示されるヘルプ・アイコン(疑問符が表示された青い丸)を表示します。

図17-5 アイコン上にマウスを置くと表示される定義メッセージ

- 説明: このタイプのヘルプはコンポーネントに応じて、(panelHeaderコンポーネントのように)コンポーネント内に説明テキストを表示するか、図17-6に示すように、ユーザーがコンポーネントをクリックした際に開かれる注意ウィンドウにテキストを表示します。テキストは任意の長さにできます。

図17-6 注意ウィンドウに表示されている説明メッセージ

- 外部URL: 外部アプリケーションに存在するヘルプ・トピックを作成できます。これは、別のブラウザ・ウィンドウで開きます。たとえば、図17-7に、説明ヘルプを表示するかわりに、スキンに関するヘルプ・トピックを開くように構成された、スキン選択のselectOneChoiceコンポーネントを示します。ユーザーがヘルプ・アイコンをクリックすると、ヘルプ・トピックが開きます。

図17-7 新しいウィンドウに開かれている外部URLヘルプ

ヘルプ・システムの作成の詳細は、コンポーネントへのヘルプの表示に関する項を参照してください。

17.2 コンポーネントのヒントの表示

ADF Facesコンポーネントでは、ユーザーがコンポーネント上にマウスを置いた場合、shortDesc属性を使用してヒントが表示されます。入力コンポーネントでは、注意ウィンドウにヒントが表示されます。その他のコンポーネント・タイプでは、標準のヒント・ボックスにヒントが表示されます。このテキストは短くする必要があります。より詳細な情報を表示する必要がある場合、または多数のコンポーネント・インスタンス間でテキストが再利用される場合は、コンポーネントへのヘルプの表示に関する項で説明されているように、ヘルプ・テキストの使用を検討してください。

図17-8に、inputTextコンポーネント上にカーソルが置かれた際の様子を示します。

図17-8 inputTextコンポーネントのヒント

図17-9に、showDetailItemコンポーネントに表示されたヒントを示します。

図17-9 showDetailItemコンポーネントのヒント

コンポーネントにヒントを定義する手順:

1. 構造ウィンドウで、ヒントを表示するコンポーネントを選択します。

2. プロパティ・インスペクタで、「外観」セクションを開き、shortDesc属性に値を入力します。

ヒント:

80文字を超えると、ブラウザによってはヒントが切り捨てられてしまうため、値は80文字未満にする必要があります。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

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

バリデータおよびコンバータには、関連するフィールドがクリックされた際にユーザーに表示されるデフォルトのヒントがあります。コンバータの場合、ヒントは、使用する適切な書式をユーザーに示します。バリデータの場合、ヒントは有効な値を示すために使用されます。

たとえば、図17-10に示すように、File Explorerアプリケーションでは、ユーザーがカスタマ・サービスに連絡ページの日付入力フィールドをクリックすると、使用する正しい書式が示されたヒントが表示されます。

図17-10 組込みメッセージのあるバリデータおよびコンバータ

ADF Facesコンポーネントの値が検証に失敗した場合、またはコンバータで変換できない場合は、コンポーネントに結果のFacesMessageインスタンスが表示されます。

たとえば、図17-11に示されているように、コンバータのdateStyle属性に一致しない日付を入力すると、エラー・メッセージが表示されます。

図17-11 実行時の検証エラー

デフォルトのバリデータおよびコンバータのヒントとエラー・メッセージをオーバーライドできます。ADF Facesの各バリデータおよびコンバータ・コンポーネントには、ユーザーに表示する詳細なメッセージの定義に使用できる属性があります。実際の属性は、バリデータまたはコンバータによって異なります。図17-12に、プロパティ・インスペクタに表示されているconvertDateTimeコンバータのメッセージをオーバーライドするために移入できる属性を示します。

図17-12 コンバータのメッセージ属性

注意ウィンドウにメッセージを表示しない場合は、messageコンポーネントを使用すると、メッセージがコンポーネントにインラインで表示されます。図17-13に、messageコンポーネントを使用してメッセージがどのように表示されるかを示します。

図17-13 messageコンポーネントを使用したメッセージのインラインでの表示

ADF FacesアプリケーションのJSFページでは、特にポップアップ・ウィンドウへのすべてのグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)の表示を処理するdocumentタグが使用されています。ただし、グローバル・メッセージをページに表示する場合は、messagesコンポーネントを使用します。

17.3.1 バリデータおよびコンバータのカスタム・メッセージの定義方法

デフォルトのバリデータおよびコンバータのメッセージをオーバーライドするには、異なるメッセージ属性に値を設定します。

バリデータまたはコンバータのメッセージを定義する手順:

1. 構造ウィンドウで、エラー・メッセージを作成するコンバータまたはバリデータを選択します。

注意:

オーバーライドできるのは、ADF Facesコンポーネントのメッセージのみです。ADF Faces以外のコンポーネント(f:validatorコンポーネントなど)にメッセージを作成する場合は、messageコンポーネントを使用します。詳細は、コンポーネントのメッセージをインラインで表示する方法に関する項を参照してください。

2. プロパティ・インスペクタで、「メッセージ」セクションを開き、メッセージを指定する属性の値を入力します。
値には、{0}、{1}、{2}などのパラメータ・プレースホルダを使用して、動的コンテンツを含めることができます。たとえば、convertDateTimeコンバータのmessageDetailConvertDate属性には、次のパラメータが使用されます。

- {0}: コンポーネントを識別するラベル

- {1}: ユーザーによって入力される値

- {2}: コンポーネントで想定される書式の例

これらのパラメータを使用して、次のメッセージを作成できます。

{1} is not using the correct date format. Please enter the date as follows: {2}.

エラー・メッセージは、図17-14のように表示されます。

図17-14 実行時の詳細なメッセージ

ヒント:

ドロップダウン・メニューを使用して、プロパティ・ヘルプを表示します。これには、メッセージが受け取ったパラメータが含まれています。

使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

注意:

メッセージ・テキストは、FacesMessageオブジェクトの詳細なメッセージ用です。サマリー(メッセージの上部に表示されるテキスト)をオーバーライドする場合は、グローバルにのみ実行できます。詳細は、デフォルト・メッセージのグローバルなオーバーライドに関する項を参照してください。

17.3.2 デフォルト・メッセージのグローバルなオーバーライドについて

messageDetail[XYZ]属性を使用してコンポーネント・インスタンスごとにメッセージの文字列を変更するかわりに、文字列がすべてのインスタンスに表示されるようにグローバルにオーバーライドします。グローバルにオーバーライドするには、メッセージのキーおよび使用するメッセージ・テキストがコンテンツに含まれるメッセージ・バンドルを作成します。

メッセージ・バンドルは、変換用のリソース・バンドルを作成して使用するのと同じ方法で、Javaクラスまたはプロパティ・ファイルを使用して作成および使用します。手順および詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

メッセージ・キーの情報は、付録B「コンバータおよびバリデータ・メッセージのメッセージ・キー」を参照してください。

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

コンポーネントで注意ウィンドウにメッセージを表示するかわりに、messageコンポーネントを使用して、ページにインラインでメッセージを表示できます。messageコンポーネントで正しいメッセージが表示されるようにするには、特定のコンポーネントと関連付けます。

コンポーネントのメッセージをインラインで表示する手順:

1. 構造ウィンドウで、messagesコンポーネントを使用してメッセージを表示するコンポーネントを選択します。設定されていない場合、コンポーネントのIDを入力します。

2. コンポーネント・パレットの「共通コンポーネント」パネルから、「メッセージ」をドラッグし、ページのメッセージを表示する場所にドロップします。

3. for属性のドロップダウン・メニューを使用して、「編集」を選択します。

4. 「プロパティの編集」ダイアログで、messagesコンポーネントでメッセージを表示するコンポーネントを探します。IDの設定されているコンポーネントのみが有効な選択肢です。

注意:

表示されるメッセージ・アイコンとメッセージ・コンテンツは、FacesMessageオブジェクトの作成時に指定されたものに基づきます。messageコンポーネントにmessageTypeまたはmessage属性を設定すると、エラーが発生したかどうかに関係なく、実行時にmessageTypeまたはmessage属性の値が表示されます。これらの属性は、ページのレンダリング時に必ずコンテンツを表示する場合にのみ移入します。

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

グローバル・メッセージをページのポップアップ・ウィンドウに表示するかわりに、messagesコンポーネントを使用してインラインで表示します。

1. コンポーネント・パレットの「共通コンポーネント」パネルから、「メッセージ」をドラッグし、メッセージを表示するページにドロップします。

2. プロパティ・インスペクタで次の属性を設定します。

- globalOnly: デフォルトでは、ADF Facesはグローバル・メッセージ(コンポーネントに関連付けられていないメッセージ)を表示し、次に個々のコンポーネントのメッセージを表示します。ボックスにグローバル・メッセージのみを表示する場合は、この属性をtrueに設定します。コンポーネント・メッセージは、関連付けられたコンポーネントに引き続き表示されます。

- inline: ページの上部にメッセージを表示する場合にtrueに設定します。設定しない場合、メッセージはダイアログに表示されます。

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

ADF Facesの入力および選択コンポーネントには、デフォルトで、ラベルおよびメッセージの表示用に組込みサポートが用意されています。コンポーネントをグループ化して単一のラベルを使用する場合は、panelLabelAndMessageコンポーネントを使用してコンポーネントをラップします。

たとえば、File Explorerアプリケーションは、4つの別々のinputTextコンポーネントを使用して電話番号を収集します。それぞれ、市外局番、電話局、最後の4桁および内線番号用です。単一のラベルが必要なため、4つのinputTextコンポーネントはpanelLabelAndMessageコンポーネントにラップされ、ラベルの値はそのコンポーネントに設定されます。ただし、内線番号の入力コンポーネントには追加のラベルが必要なため、outputTextコンポーネントが使用されます。例17-1に、panelLabelAndMessageコンポーネントのJSFコードを示します。

例17-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>

図17-15に、panelLabelAndMessageおよびネストしたコンポーネントがブラウザにどのように表示されるかを示します。

図17-15 panelLabelAndMessageコンポーネントの使用例

panelLabelAndMessageコンポーネントには、グループの最後に追加のコンポーネントを表示するために使用できるEndファセットも含まれます。図17-16に、EndファセットにoutputTextコンポーネントが移入されている場合に、電話番号フィールドがどのように表示されるかを示します。

図17-16 panelLabelAndMessageコンポーネント内のEndファセット

panelLabelAndMessageコンポーネント内にpanelGroupLayoutコンポーネントを使用して、必要なレイアウトのコンポーネントをグループ化します。panelGroupLayoutコンポーネントの使用方法の詳細は、関連する項目のグループ化に関する項を参照してください。

各入力コンポーネントでsimple属性をtrueに設定し、個々のラベルが表示されないようにします。ただし、メッセージ目的およびアクセシビリティ用の各コンポーネントのラベル属性に値を設定することが必要な場合があります。

ヒント:

複数のpanelLabelAndMessageコンポーネントを連続して使用する必要がある場合には、ラベルが適切に配置されるよう、af:panelFormLayoutコンポーネントにラップします。panelFormLayoutコンポーネントの使用方法の詳細は、フォームでのコンテンツの配置に関する項を参照してください。

panelLabelAndMessageコンポーネントを使用して、コンポーネントをグループ化してラップします。panelLabelAndMessageコンポーネントは、通常メッセージやラベルを表示するコンポーネントのみでなく、任意のコンポーネントのラップに使用できます。

単一のラベルおよびメッセージを使用してフォーム入力コンポーネントを配置する手順:

1. 必要に応じて、入力コンポーネントまたは選択コンポーネントをページに追加します。

各入力および選択コンポーネントに次の設定を行います。

- simple属性をtrueに設定します。

- アクセシビリティの理由から、label属性をコンポーネントのラベルに設定します。

2. 構造ウィンドウで、手順1で作成した入力コンポーネントまたは選択コンポーネントを選択します。選択内容を右クリックし、「囲む」→「パネル・ラベルとメッセージ」を選択します。

3. panelLabelAndMessageコンポーネントが選択された状態で、プロパティ・インスペクタにおいて次の属性を設定します。

- label: コンポーネントのグループに表示するラベル・テキストを入力します。

- for: ドロップダウン・メニューを使用して「編集」を選択します。「プロパティの編集」ダイアログで、子入力コンポーネントのIDを選択します。入力コンポーネントが複数ある場合は、最初のコンポーネントを選択します。
アクセシビリティ要件に一致するように、for属性を最初のinputComponentに設定します。

ネストした入力コンポーネントの1つ以上が必須コンポーネントで、これを示すためにマーカーを表示する場合は、showRequired属性をtrueに設定します。

4. Endファセットにコンテンツを配置するには、必要なコンポーネントをファセットにドラッグ・アンド・ドロップします。
ファセットに配置できる子コンポーネントは1つのみであるため、複数の子コンポーネントを追加する場合は、panelGroupLayoutまたはgroupコンポーネントなどのコンテナで子コンポーネントをラップする必要があります。

ヒント:

ファセットがビジュアル・エディタに表示されない場合は、次のようにします。

1. 構造ウィンドウで、panelLabelAndMessageコンポーネントを右クリックします。

2. ポップアップ・メニューから、「ファセット - パネル・ラベルおよびメッセージ」→「facet name」を選択します。ページで使用されているファセットは、ファセット名の前にチェックマークが表示されます。

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

ADF Facesでは、異なる3つのタイプのヘルプを作成および表示できるフレームワークを提供します。これらのヘルプはコンポーネントで構成したテキストではなく、コンテンツが外部ソースから取得されます。コンポーネントに直接構成されていないため、コンテンツは複数のコンポーネントで使用できます。これにより、ページを作成する時間が節約でき、コンテンツが表示されるすべての場所ではなく、1箇所でコンテンツを変更できます。

ADF Facesにより提供される1つ目のタイプの外部ヘルプは、定義ヘルプです。標準のヒント同様、コンテンツはメッセージ・ボックスに表示されます。ただし、ユーザーがコンポーネント上にマウスを置いた場合に表示されるのではなく、定義ヘルプではヘルプ・アイコン(疑問符が表示された青い丸)が表示されます。ユーザーがアイコン上にマウスを置くと、図17-17に示すようにコンテンツが表示されます。

図17-17 コンポーネントの定義テキスト

表17-1に、定義ヘルプがサポートされているコンポーネントを示します。

表17-1 定義ヘルプがサポートされているコンポーネント

サポートされているコンポーネント

ヘルプ・アイコンの位置

例

すべての入力コンポーネント、選択コンポーネント、色の選択、日付の選択、問合せコンポーネント

ラベルの前。ラベルが存在しない場合は、フィールドの先頭。

パネル・ヘッダー、パネル・ボックス、詳細の表示ヘッダー

ヘッダー・テキストの最後。

パネル・ウィンドウ、ダイアログ

ヘッダーの「閉じる」アイコンの隣。

表およびツリーの列

ヘッダー・テキストの下。

2つ目のタイプのヘルプは説明ヘルプです。説明ヘルプが表示される場所は、関連付けられているコンポーネントによって異なります。panelHeaderおよび検索パネル・コンポーネントでは、ヘッダー内に説明ヘルプが表示されます。図17-18に、図17-17に示されている、通常は定義ヘルプとして表示されるテキストが、panelHeaderコンポーネント内で説明ヘルプとしてどのように表示されるかを示します。

図17-18 panelHeaderの説明テキスト

説明ヘルプがサポートされているその他すべてのコンポーネントでは、図17-19に示すように、注意ウィンドウにテキストが表示されます。ヘルプ・アイコンは表示されないことに注意してください。

図17-19 コンポーネントの説明テキスト

表17-2に、説明ヘルプがサポートされているコンポーネントを示します。

表17-2 説明ヘルプがサポートされているコンポーネント

サポートされているコンポーネント

ヘルプの位置

例

入力コンポーネント、色の選択、日付の選択、クイック問合せ

注意ウィンドウ(フォーカスがある場合のみ)

コンポーネントの選択

注意ウィンドウ(マウスが置かれている場合とフォーカスがある場合)

パネル・ヘッダー、パネル・ボックス、問合せ

ヘッダー・テキストの下のテキスト

最後のタイプのヘルプは外部URLヘルプです。外部アプリケーションのWebページのURLを指定します。ヘルプ・アイコンがクリックされると、図17-20.に示すように、Webページが別のブラウザ・ウィンドウで開きます。ヘルプ・アイコンをクリックするのではなく、JavaScriptを使用すると、任意のクライアント・ベースのイベントに基づいたヘルプ・ウィンドウを開くことができます。

図17-20 外部URLヘルプ

ADF Facesには、様々なヘルプ・プロバイダがあります。ResourceBundleHelpProviderヘルプ・プロバイダを使用すると、ヘルプ・コンテンツを保持するリソース・バンドルを作成できます。ELHelpProviderヘルプ・プロバイダを使用すると、マップに変換されるXLIFFファイルの作成、またはヘルプ・テキスト文字列のマップが含まれるマネージドBeanの作成が可能です。異なるヘルプ・プロバイダを組み合せて使用することもできます。また、独自のヘルプ・プロバイダ・クラスの作成も可能です。

アプリケーションにヘルプを作成するには、次のようにします。

- 使用するヘルプ・プロバイダを決定し、必要なアーティファクトを実装します。

- プロバイダのヘルプへのアクセスに使用する接頭辞を指定して、ヘルプ・プロバイダを登録します。各ヘルプ・プロバイダには一意の接頭辞があり、識別子として使用されます。プロバイダが登録されている接頭辞で始まるヘルプ・トピックIDに対してのみヘルプを生成するために、特定のプロバイダがコールされます。

- コンポーネントのhelpTopicId属性を使用して、UIコンポーネントがプロバイダに含まれるヘルプにアクセスできるようにします。helpTopicId属性には、次の情報が含まれています。

- ヘルプ・プロバイダにより使用される接頭辞

- トピック名

たとえば、図17-19に示されているinputTextコンポーネントのhelpTopicId属性の値はRBHELP_FILE_NAMEです。ここで、RBHELPはリソース・バンドル・ヘルプ・プロバイダの接頭辞で、FILE_NAMEはヘルプ・トピック名です。

17.5.1 リソース・バンドルベースのヘルプの作成方法

標準のリソース・バンドル・プロパティ・ファイルにヘルプ・テキストを格納し、ResourceBundleHelpProviderクラスを使用してコンテンツを送信できます。

リソース・バンドルベースのヘルプを作成する手順:

1. 各ヘルプ・トピックのトピックIDおよびヘルプ・テキストを含むプロパティ・ファイルを作成します。トピックIDには次の情報が含まれている必要があります。

- RBHELPなど、プロバイダにより使用される接頭辞

- TELEPHONE_NUMBERなどのトピック名

- DEFINITIONなどのヘルプ・タイプ

たとえば、トピックIDはRBHELP_TELEPHONE_NUMBER_DEFINITIONのようになります。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-2を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。

例17-2に、3つのトピックがあるリソース・バンドルの例を示します。

例17-2 リソース・バンドル・ヘルプ

RBHELP_CUST_SERVICE_EMAIL_DEFINITION=For security reasons,
we strongly discourage the submission of credit card numbers.
RBHELP_TELEPHONE_NUMBER_DEFINITION=We only support calling telephone numbers
in the United States at this time.
RBHELP_TELEPHONE_NUMBER_INSTRUCTIONS=Enter a telephone number.

注意:

外部URLのヘルプ・タイプを使用する場合は、ResourceBundleHelpProviderクラスのサブクラスを作成します。詳細は、手順3を参照してください。

2. adf-settings.xmlファイルにヘルプ・プロバイダとしてリソース・バンドルを登録します(存在しない場合にadf-settings.xmlファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xmlファイルを開き、「ソース」タブをクリックして、次の要素を追加します。

- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意であり、リソース・バンドルに使用されている接頭辞に一致する必要があります。

注意:

prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。

- <help-provider-class>: <help-provider>要素の子要素として作成し、oracle.adf.view.rich.help.ResourceBundleHelpProviderを入力します。

- <property>: <help-provider>要素の子要素として作成します。プロパティは、実際のヘルプ・ソースを定義します。

- <property-name>: <property>要素の子要素として作成し、baseNameなど、ソースの名前を入力します。

- <value>: <property>要素の子要素として作成し、リソース・バンドルの完全修飾クラス名を入力します。たとえば、ADF Facesデモ・アプリケーションで使用されるリソース・バンドルの修飾クラス名はoracle.adfdemo.view.resource.DemoResourcesです。

例17-3に、例17-2のリソース・バンドルが、adf-settings.xmlファイルにどのように登録されているかを示します。

例17-3 ヘルプ・プロバイダとしてのリソース・バンドルの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="RBHELP_">
<help-provider-class>
oracle.adf.view.rich.help.ResourceBundleHelpProvider
</help-provider-class>
<property>
<property-name>baseName</property-name>
<value>oracle.adfdemo.view.resource.DemoResources</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>

3. 外部URLヘルプを使用する場合は、ResourceBundleHelpProviderクラスを拡張し、getExternalUrlメソッドも実装する必要があります。例17-4に、メソッドの例を示します。

例17-4 getExternalURLメソッドのオーバーライド

protected String getExternalUrl(FacesContext context, UIComponent component,
String topicId)
{
if (topicId == null)
return null;
if (topicId.contains("TOPICID_ALL") ||
topicId.contains("TOPICID_DEFN_URL") ||
topicId.contains("TOPICID_INSTR_URL") ||
topicId.contains("TOPICID_URL"))
return http://www.myURL.com;
else
return null;
}

例17-4では、メソッドのすべてのトピックで同じURLが返されます。異なるURLを返すには、if文を個別に作成する必要があります。

ヘルプ・アイコンから起動されるのではなく、コンポーネントのクライアント・イベントに基づいて起動される外部ウィンドウが必要な場合、JavaScript関数を使用します。詳細は、JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法に関する項を参照してください。

17.5.2 XLIFFベースのヘルプの作成方法

XLIFF XMLファイルにヘルプ・テキストを格納し、ELHelpProviderクラスを使用してコンテンツを送信できます。このクラスでは、XLIFFファイルが、ヘルプのテキストとして使用される文字列のマップに変換されます。

XLIFFヘルプを作成する手順:

1. <body>タグ内に次の要素を使用して、ヘルプ・テキストを定義するXLIFFファイルを作成します。

- <trans-unit>: トピックIDを入力します。このIDには、XLIFFHELP_CREDIT_CARD_DEFINITIONのように、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。この例で、XLIFFHELPはXLIFFファイルへのアクセスに使用される接頭辞になります。CREDIT_CARDはトピック名で、DEFINITIONはヘルプ・タイプです。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-5を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。

- <source>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストを入力します。

- <target>: <trans-unit>要素の直接の子要素として作成し、空白のままにします。これは翻訳済テキストを保持するために使用されます。

- <note>: <trans-unit>要素の直接の子要素として作成し、ヘルプ・テキストの説明を入力します。

例17-5に、2つのトピックを含むXLIFFファイルの例を示します。

例17-5 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="XLIFF_CREDIT_CARD_DEFINITION">
<source>Credit Card Definition</source>
<target/>
<note>Credit Card definition text.</note>
</trans-unit>
<trans-unit id="XLIFF_CREDIT_CARD_INSTRUCTIONS">
<source>Credit Card Instructions</source>
<target/>
<note>Credit card instruction text.</note>
</trans-unit>
</body>
</file>
</xliff>

2. adf-settings.xmlファイルにヘルプ・プロバイダとしてXLIFFを登録します(存在しない場合にadf-settings.xmlファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xmlファイルを開き、次の要素を追加します。

- <help-provider>: prefix属性を使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。これは、アプリケーション内で一意であり、XLIFFファイルに使用されている接頭辞に一致する必要があります。

注意:

prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。

- <help-provider-class>: <help-provider>要素の子要素として作成し、oracle.adf.view.rich.help.ELHelpProviderを入力します。

- <property>: <help-provider>要素の子要素として作成します。プロパティ値は、実際のヘルプ・ソースを定義します。

- <property-name>: <property>要素の子要素として作成し、helpSourceなど、ヘルプの名前を入力します。

- <value>: <property>要素の子要素として作成し、#{adfBundle['project1xliff.view.Project1XliffBundle']}のように、adfBundle EL関数でラップされた、XLIFFファイルに解決されるEL式を入力します。

例17-6に、例17-5のXLIFFファイルが、adf-settings.xmlファイルにどのように登録されているかを示します。

例17-6 ヘルプ・プロバイダとしてのXLIFFファイルの登録

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="XLIFF">
<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>

17.5.3 マネージドBeanヘルプの作成方法

マネージドBeanヘルプを実装するには、ヘルプのテキストとして使用される文字列のマップを含むマネージドBeanを作成します。マネージドBeanヘルプ・プロバイダでは、ELHelpProviderクラスを使用してヘルプが送信されます。

マネージドBeanヘルプの作成方法:

1. 文字列のマップを戻すマネージドBeanを作成します。例17-7に示すように、いずれもIDおよびヘルプ・トピックのコンテンツです。

例17-7 ヘルプ・テキスト文字列のマップを戻すマネージド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("MAPHELP_CREDIT_CARD_DEFINITION",
"Map value for credit card definition");
_HELP_MAP.put("MAPHELP_CREDIT_CARD_INSTRUCTIONS",
"Map value for credit card instructions");
_HELP_MAP.put("MAPHELP_SHOPPING_DEFINITION",
"Map value for shopping definition");
_HELP_MAP.put("MAPHELP_SHOPPING_INSTRUCTIONS",
"Map value for shopping instructions");
}

}

最初の文字列には、MAPHELP_CREDIT_CARD_DEFINITIONなどのように、接頭辞、トピック名およびヘルプ・タイプが含まれている必要があります。この例で、MAPHELPはBeanへのアクセスに使用される接頭辞になります。CREDIT_CARDはトピック名で、DEFINITIONはヘルプ・タイプです。2つ目の文字列はヘルプ・テキストです。

注意:

ヘルプ・プロバイダが登録されているすべての接頭辞は一意であることが必要です。また、別の接頭辞と同じ文字で接頭辞を開始することはできません。たとえば、AABおよびACの2つの接頭辞にヘルプ・プロバイダが登録されている場合、AABC、A、AA、AC、ACBという接頭辞はすべて無効で、登録時に例外がスローされます。ただし、AAD、ABなどは有効です。

UIコンポーネントはトピック名に基づいてヘルプ・コンテンツにアクセスします。そのため、2つの異なるヘルプ・タイプに同じトピック名を使用すると(例17-7を参照)、UIコンポーネントにより、両方のヘルプ・タイプが表示されます。

注意:

外部URLヘルプを使用する場合は、ELHelpProviderクラスのサブクラスを作成します。詳細は、手順4を参照してください。

2. faces-config.xmlファイルにマネージドBeanを登録します。例17-8に、例17-7に示されていて、faces-config.xmlファイルに登録されているBeanを示します。

例17-8 faces-config.xmlファイルでのマネージドBeanの登録

<managed-bean>
<managed-bean-name>helpTranslationMap</managed-bean-name>
<managed-bean-class>
oracle.adfdemo.view.webapp.ELHelpProviderMapDemo
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>

マネージドBeanの使用および登録の詳細は、マネージドBeanの作成と使用に関する項を参照してください。

3. adf-settings.xmlファイルにヘルプ・プロバイダとしてマネージドBeanを登録します(存在しない場合にadf-settings.xmlファイルを作成する方法の詳細は、A.5.1項「adf-settings.xmlでのADF Facesの構成方法」を参照してください)。
プロバイダを登録するには、adf-settings.xmlファイルを開き、次の要素を追加します。

- <help-provider>: prefix属性を作成および使用して、UIコンポーネントがこのヘルプ・プロバイダにアクセスする際に使用する接頭辞を定義します。アプリケーション内で一意であることが必要です。

注意:

prefix属性がないか、空である場合、そのヘルプ・プロバイダは、特別なデフォルトのヘルプ・プロバイダとして登録されます。これは、その他のどのヘルプ・プロバイダとも一致しないヘルプ・トピックIDのヘルプの生成に使用されます。許可されるデフォルトのヘルプ・プロバイダは1つのみです。

- <help-provider-class>: <help-provider>要素の子要素として作成し、手順1で作成したクラスへの完全修飾クラス・パスを入力します。

- <property>: <help-provider>要素の子要素として作成します。プロパティは、マネージドBeanのヘルプ文字列のマップを定義します。

- <property-name>: <property>要素の子要素として作成し、helpSourceなど、プロパティ名を入力します。

- <value>: <property>要素の子要素として作成し、マネージドBeanのヘルプ・マップに解決されるEL式を入力します。

例17-9に、例17-8のBeanが、adf-settings.xmlファイルにどのように登録されているかを示します。

例17-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="MAPHELP_">
<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>

4. マネージドBeanプロバイダに外部URLヘルプを使用する場合は、ELHelpProviderクラスを拡張し、getExternalUrlメソッドを実装する必要があります。例17-10に、メソッドの例を示します。

例17-10 getExternalURLメソッドのオーバーライド

protected String getExternalUrl(FacesContext context, UIComponent component,
String topicId)
{
if (topicId == null)
return null;
if (topicId.contains("TOPICID_ALL") ||
topicId.contains("TOPICID_DEFN_URL") ||
topicId.contains("TOPICID_INSTR_URL") ||
topicId.contains("TOPICID_URL"))
return http://www.myURL.com;
else
return null;
}

例17-10では、メソッドのすべてのトピックで同じURLが返されます。異なるURLを返すには、if文を個別に作成する必要があります。

ヘルプ・アイコンから起動されるのではなく、コンポーネントのクライアント・イベントに基づいて起動される外部ウィンドウが必要な場合、JavaScript関数を使用します。詳細は、JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法に関する項を参照してください。

17.5.4 JavaScriptを使用して外部ヘルプ・ウィンドウを起動する方法

外部URLヘルプを使用する場合、デフォルトでは、ユーザーはヘルプ・アイコンをクリックして、ヘルプ・ウィンドウを起動します。かわりに、JavaScriptおよびクライアント・イベント・リスナーを使用すると、特定のコンポーネントのイベントがヘルプ・ウィンドウを起動できます。

JavaScriptを使用して外部ヘルプ・ウィンドウを起動する手順:

1. launchHelp APIを使用して特定のURLまたはページを起動するJavaScript関数を作成します。

例17-11に、helpClient.jspxを起動するために使用されるlaunchHelp関数を示します。

例17-11 外部ヘルプ・ページを起動するJavaScript

<af:resource type="javascript">
function launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>

2. クライアント・イベントによって関数が起動されるコンポーネントをドラッグ・アンド・ドロップします。このコンポーネントのclientIdをtrueに設定する必要があります。

3. コンポーネント・パレットの「操作」パネルから、手順2で作成したコンポーネントに、「クライアント・リスナー」を子としてドラッグ・アンド・ドロップします。clientListenerを構成して、手順1で作成した関数を起動します。clientListenerタグの使用の詳細は、クライアント・イベントのリスニングに関する項を参照してください。
例17-12に、commandToolbarButtonコンポーネントのクリック・イベントによってhelpClient.jspxページが起動されるように使用されるコードを示します。

例17-12 外部ヘルプ・ウィンドウを起動するために使用されるページ・コード

<af:toolbar id="tb1">
<af:commandToolbarButton text="Launch help window" id="ctb1"
icon="/images/happy_computer.gif">
<af:clientListener method="launchHelp" type="click"/>
</af:commandToolbarButton>
</af:toolbar>
<af:resource type="javascript">
function launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>

17.5.5 Javaクラス・ヘルプ・プロバイダの作成方法

ADF Facesヘルプ・プロバイダのいずれかを使用するかわりに、独自のプロバイダを作成します。ヘルプ・プロバイダがアクセスして表示できるファイルに実際のテキストを作成します。Javaクラス・ヘルプ・プロバイダを作成するには、HelpProviderクラスを拡張します。このクラスの詳細は、ADF FacesのJavadocを参照してください。

Javaクラス・ヘルプ・プロバイダを作成する手順:

1. oracle.adf.view.rich.help.HelpProviderを拡張するJavaクラスを作成します。

2. パラメータなしでpublicコンストラクタを作成します。また、ヘルプ・トピックにアクセスして戻すロジックも実装する必要があります。

3. このクラスは、このプロバイダの登録時にadf-settings.xmlファイルに設定されたプロパティおよび値にアクセスできます。たとえば、すべてのADF Facesプロバイダでは、プロパティを使用して、ヘルプ文字列の実際のソースが定義されます。adf-settings.xmlファイルのプロパティにアクセスするには、Stringであるプロパティを設定するメソッドを作成します。次に例を示します。

public void setMyCustomProperty(String arg)

4. プロバイダを登録するには、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>要素の子要素として作成し、プロパティ値を入力します。

例17-13に、adf-settings.xmlファイルに登録されているヘルプ・プロバイダ・クラスの例を示します。

例17-13 ヘルプ・プロバイダ・クラスの登録

<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>

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

コンポーネントのHelpTopicId属性を使用して、ヘルプへのアクセスおよび表示を行います。

コンポーネントからヘルプにアクセスする手順:

1. 構造ウィンドウで、ヘルプを追加するコンポーネントを選択します。ヘルプがサポートされているコンポーネントのリストは、表17-1および表17-2を参照してください。

2. プロパティ・インスペクタで、「外観」セクションを開き、helpTopicId属性に値を入力します。これには、適切なヘルプ・プロバイダおよびトピック名にアクセスする接頭辞が含まれている必要があります。次に示すように、その名前で登録されているすべてのヘルプ・タイプが戻されて表示されるため、ヘルプ・タイプは含めません。

<af:inputText label="Credit Card" helpTopicId="XLIFF_CREDIT_CARD"/>

この例では、例17-5のXLIFFファイルに定義されている定義ヘルプと説明ヘルプの両方が戻されます。

3. ヘルプがサポートされていないコンポーネントにヘルプを表示する場合は、outputTextコンポーネントを追加してヘルプ・テキストを表示し、次のようにして、そのコンポーネントをヘルプ・プロバイダにバインドできます。

<af:outputFormatted
value="#{adfFacesContext.helpProvider['XLIFF_CREDIT_CARD'].instructions}"/>

これは、説明ヘルプ・テキストにアクセスします。

17.5.7 異なるメッセージ・タイプの組合せについて

検証および変換に関するメッセージを表示する入力コンポーネントにヘルプ・メッセージを追加すると、ADF Facesにより、注意ウィンドウ内に次の順序でメッセージが表示されます。

1. 検証および変換のエラー・メッセージ。

2. 検証および変換のヒント。

3. 入力および選択コンポーネントの場合のみ、説明ヘルプ。panelHeaderコンポーネントの場合、説明ヘルプは常にヘッダーの下に表示されます。

4. shortDesc属性の値。

図17-21に、コンバータ、説明ヘルプおよびヒント・メッセージを含むinputDateコンポーネントを示します。

図17-21 一度に表示されている異なるメッセージ・タイプ

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

この章では、commandButton、navigationPaneおよびtrainなど、ADF Facesのナビゲーション・コンポーネントを使用して、Webユーザー・インタフェースでのナビゲーションを実現する方法を説明します。

この章では、次の項目について説明します。

- 18.1項「ナビゲーション・コンポーネントの概要」

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

- 18.3項「コマンド・リンクに対するブラウザのポップアップ・メニューの構成」

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

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

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

- 18.7項「単純なナビゲーション階層の作成」

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

18.1 ナビゲーション・コンポーネントの概要

JSFアプリケーション同様、ADF Facesコンポーネントを使用するアプリケーションには、ボタンやリンク(またはその他のナビゲーション・コンポーネント)がクリックされた場合に、次に表示するページを選択する一連のルールがあります。ルールは、アプリケーションの構成リソース・ファイル(faces-config.xml)にJSFナビゲーション・ルールおよびケースを追加することで定義します。

JSFでは、結果の文字列は、ページ・ナビゲーションの実行に使用するナビゲーション・ルールの選択に使用されます。javax.faces.component.ActionSourceインタフェースを実装するADF Facesのナビゲーション・コンポーネントでは、ユーザーがコンポーネントをアクティブ化するとActionEventイベントが生成されます。JSF NavigationHandlerおよびデフォルトのActionListenerメカニズムでは、アクティブ化されたコンポーネントの結果文字列を使用して、一連のナビゲーション・ルールで一致するものが検出されます。JSFで一致が検出されると、対応するページが選択され、レスポンスのレンダリング・フェーズで選択したページがレンダリングされます。JSFライフサイクルの詳細は、第4章「JSFおよびADF Facesのライフサイクルの使用」を参照してください。また、ADF Facesアプリケーションのナビゲーションでは、部分ページ・レンダリングが使用される場合があります。詳細は、部分ページ・ナビゲーションの使用に関する項を参照してください。

次に、ADF Facesのコマンド・コンポーネントに含まれるものを示します。

- サーバー側のアクションの有無にかかわらず、別の場所にナビゲートするためのボタンおよびリンク・コンポーネント。18.2項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください。

- 階層ページをナビゲートするためのタブおよびブレッドクラムなどの項目をレンダリングするコンポーネント。18.5項「ページ階層用のナビゲーション・アイテムの使用」を参照してください。

- マルチステップ・プロセスをナビゲートするためのtrainコンポーネント。18.8項「trainコンポーネントを使用したマルチステップ・プロセス用のナビゲーション・アイテムの作成」を参照してください。

ナビゲーションにコマンド・コンポーネントを使用するのに加え、ADF Facesには、アクション・イベントの起動時に特定の機能を実行するためにコマンド・コンポーネントとともに使用できるリスナー・タグも含まれています。詳細は、18.4項「ボタンまたはリンクの機能の呼出し目的での使用」を参照してください。

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

ADF Facesのボタンおよびリンクには、コマンド・コンポーネント(commandButton、commandLink、commandImageLink)、および実行コンポーネント(goButton、goImageLink、goLink)が含まれます。コマンド・コンポーネントと実行コンポーネントの主な違いは、コマンド・コンポーネントはリクエストを送信してActionEventイベントを起動するのに対し、実行コンポーネントはアクションを配信せずに直接別の場所に移動する点です。図18-11に示すように、レンダリングされたコマンド・コンポーネントと実行コンポーネントは視覚的に同じように見えます。

図18-1 コマンド・コンポーネントおよび実行コンポーネント

ヒント:

ADF Facesには、メニューやツールバー内で使用できる特殊なコマンド・コンポーネントも用意されています。詳細は、第14章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

commandImageLinkおよびgoImageLinkコンポーネントは、図18-2に示すように、オプションのテキストとともにイメージをリンクとしてレンダリングします。iconPosition属性の値を設定して、オプションのテキストに関連するイメージの位置を指定できます。さらに、ユーザーがアイコンにカーソルを置いた場合や、アイコンが押された場合または無効化された場合に、別々のアイコンを設定できます。

図18-2 コマンド・イメージ・リンクと実行イメージ・リンク

ADF Facesには、ツールバー・ボタンからポップアップ・メニューを開くことができるpopupファセットなど、その他の機能を提供するツールバー・ボタンもあります。詳細は、14.3項「ツールバーの使用方法」を参照してください。

リンクをレンダリングするコマンド・コンポーネントをエンド・ユーザーが右クリックしたときに、ブラウザのポップアップ・メニューを起動できるように、アプリケーションを構成できます。コマンド・コンポーネントによってレンダリングされたリンクを右クリックするエンド・ユーザーは、ブラウザのポップアップ・メニューを使用して、ユーザーが起動する必要のないアクションを起動することがあります(たとえば、新しいウィンドウでリンクを開くなど)。詳細は、コマンド・リンクに対するブラウザのポップアップ・メニューの構成に関する項を参照してください。

コミットされていないデータを含むページからユーザーが移動しようとする場合、ユーザーに警告メッセージを表示できます。immediate属性にtrueを設定したコマンド・コンポーネントに、checkUncommittedDataBehaviorコンポーネントを子として追加します。ユーザーが移動しないことを選択した場合、クライアント・イベントが取り消されます。次のコンポーネントにcheckUncommittedDataBehaviorコンポーネントを子として追加できます。

- af:commandButton

- af:commandLink

- af:commandImageLink

- af:commandToolbarButton

- af:activeCommandToolbarButton

警告メッセージがエンド・ユーザーに表示されるために、ページにはコミットされていないデータが含まれている必要があります。また、documentタグの構成方法に関する項で説明されているように、documentタグのuncommittedDataWarning属性をonに設定する必要もあります。

注意:

documentタグのuncommittedDataWarningタグをonに設定し、criticalとして構成されているタスク・フローにバインドされているADFコントローラを、ページでレンダリングする場合にも、コミットされていないデータがあれば、警告メッセージが表示されます。『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の暗黙的セーブポイントを有効化する方法に関する項を参照してください。

18.2.1 コマンド・ボタンおよびコマンド・リンクの使用方法

通常、commandButton、commandLinkおよびcommandImageLinkコンポーネントは、ページ・ナビゲーションおよびサーバー側の処理を実行するために使用します。

コマンド・コンポーネントを作成および使用する手順:

1. コンポーネント・パレットからJSFページに「Button」をドラッグ・アンド・ドロップして、commandButtonコンポーネントを作成します。「リンク」をドラッグ・アンド・ドロップして、commandLinkコンポーネントを作成します。「イメージ・リンク」をドラッグ・アンド・ドロップして、commandImageLinkコンポーネントを作成します。

2. プロパティ・インスペクタで、「共通」セクションを開き、text属性を設定します。

ヒント:

かわりに、textAndAccessKey属性を使用して、ボタンまたはリンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、22.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

3. icon属性を、commandButtonまたはcommandImageLinkコンポーネント内に使用するイメージ・ファイルのURIに設定します(commandLinkではサポートされていません)。commandImageLinkコンポーネントの場合は、hoverIcon、disabledIconおよびdepressedIcon属性を設定することも可能です。

ヒント:

text属性(またはtextAndAccessKey属性)かicon属性、あるいはその両方を使用できます。

4. 結果の文字列、または論理結果のStringを返すバッキングBeanのアクション・メソッドを参照するメソッド式に、action属性を設定します。ページ間のナビゲーションを構成する方法の詳細は、2.3項「ページ・フローの定義」を参照してください。
デフォルトのJSF ActionListenerメカニズムでは、結果の文字列を使用して適切なJSFナビゲーション・ルールが選択され、レスポンスのレンダリング・フェーズに使用するページがJSF NavigationHandlerに通知されます。マネージドBeanメソッドを使用してダイアログを開く方法の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。JSFアプリケーションでの結果の文字列およびナビゲーションの詳細は、http://download.oracle.com/javaee/index.htmlでJava EE 6チュートリアルを参照してください。

ヒント:

結果を返すハンドラにバインドされている場合は、ナビゲーションにactionListener属性を使用することもできます。通常、この属性はナビゲーションではなく、ユーザー・インタフェース・ロジックの処理にのみ使用する必要があります。

たとえば、File Explorerアプリケーションの「検索」パネルの「検索」ボタンにはナビゲート先はありません。かわりに、検索の実行に使用されます。actionListener属性には、次の値が指定されています。

actionListener="#{explorer.navigatorManager.searchNavigator.
searchForFileItem}"

この式は、実際に検索を実行するメソッドに評価されます。

5. コンポーネントを対話型ではないボタンまたはリンクとして表示する場合は、「動作」セクションを開いて、disabled属性をtrueに設定します。

6. コンポーネントがアクティブ化されるたびに部分ページ・リクエストが起動されるように、partialSubmit属性をtrueに設定します。詳細は、7.2項「部分ページ・レンダリングの宣言的有効化」を参照してください。

7. 検証の処理およびモデルの更新フェーズをスキップする場合は、immediate属性をtrueに設定します。コンポーネントのアクション・リスナー(存在する場合)およびデフォルトのJSF ActionListenerハンドラは、JSFライフサイクルのリクエスト値の適用フェーズの最後に実行されます。詳細は、4.2項「immediate属性の使用」を参照してください。

8. オプションで、手順7に示されているように、immediate属性をtrueに設定した場合、af:checkUncommittedDataBehaviorコンポーネントを子としてコマンド・コンポーネントに追加すると、ページにコミットされていないデータが含まれているときに警告メッセージをユーザーに表示できます。コンポーネント・パレットの「操作」パネルの「動作」セクションから「未コミット・データの確認動作」をドラッグして、手順1で追加したコマンド・コンポーネントの子として、これをドロップします。

注意:

また、documentタグの構成方法に関する項で説明されているように、documentタグのuncommittedDataWarning属性をonに設定する必要もあります。

コマンド・ボタンおよびリンクも、useWindow、windowHeight、windowWidth、launchListenerおよびreturnListenerの属性を使用して、2次ウィンドウを開くために使用できます。2次ウィンドウを開く方法の詳細は、第18章「ナビゲーション・コンポーネントの使用」を参照してください。

18.2.2 実行ボタンおよび実行リンクの使用方法

goButton、goImageLinkおよびgoLinkコンポーネントは、ActionEventイベントを配信せずに、ページ・ナビゲーションを直接実行するために使用します。

実行ボタンおよび実行リンクを作成および使用する手順:

1. コンポーネント・パレットからJSFページに実行ボタンをドラッグ・アンド・ドロップして、goButtonコンポーネントを作成します。移動リンクをドラッグ・アンド・ドロップして、goLinkコンポーネントを作成します。「実行イメージ・リンク」をドラッグ・アンド・ドロップして、goImageLinkコンポーネントを作成します。

2. goButtonまたはgoLinkコンポーネントを作成した場合、プロパティ・インスペクタで「共通」セクションを開き、text属性を設定します。goImageLinkコンポーネントを作成した場合、「その他」セクションでtext属性を設定します。

ヒント:

かわりに、textAndAccessKey属性を使用して、ボタンまたはリンクに使用するラベルおよびアクセス・キーを定義する単一の値を指定できます。アクセス・キーの定義方法の詳細は、22.3.4項「ADF Facesコンポーネントのアクセス・キーの定義方法」を参照してください。

3. icon属性を、goButtonまたはgoImageLinkコンポーネント内に使用するイメージ・ファイルのURIに設定します(goLinkではサポートされていません)。goImageLinkコンポーネントの場合は、hoverIcon、disabledIcon、depressedIconおよびiconPosition属性を設定することも可能です。
iconPosition属性では、leading(デフォルト)およびtrailingの2つの値がサポートされています。テキストの前にアイコンをレンダリングするには、leadingに設定します。テキストの後ろにアイコンをレンダリングするには、trailingに設定します。

ヒント:

text属性(またはtextAndAccessKey属性)かicon属性、あるいはその両方を使用できます。

4. destination属性を、リンクのナビゲート先のページのURIに設定します。
たとえば、File Explorerアプリケーションのpopups.jspxファイルのgoLinkコンポーネントには、destination属性に次のEL式が設定されています。

destination="http://www.oracle.com"

5. targetFrame属性を設定して、新しいページの表示場所を指定します。使用できる値は次のとおりです。

- _blank: リンクにより、ドキュメントは新しいウィンドウに開かれます。

- _parent: リンクにより、ドキュメントは親ウィンドウに開かれます。たとえば、リンクがダイアログに表示された場合、結果のページは親ウィンドウにレンダリングされます。

- _self: リンクにより、ドキュメントは同じページまたはリージョンに開かれます。

- _top: リンクにより、ページ全体が置き換えられて、ドキュメントはウィンドウ全体に開かれます。

6. コンポーネントを対話型ではないボタンまたはリンクとして表示する場合は、「動作」セクションを開いて、disabled属性をtrueに設定します。「その他」セクションで、goImageLinkコンポーネントのdisabled属性を設定します。

18.3 コマンド・リンクに対するブラウザのポップアップ・メニューの構成

実行時にリンクをレンダリングするコマンド・コンポーネントを使用すると、エンド・ユーザーがアクションを起動できます。さらに、ADF Facesフレームワークで、エンド・ユーザーのブラウザがこれらのコマンド・コンポーネントのポップアップ・メニューをレンダリングできるように、アプリケーションを構成できます。ポップアップ・メニューは、コマンド・コンポーネントで指定されたリンクに対して、異なるアクション(たとえば、新しいウィンドウでリンクを開くなど)を起動するメニュー・オプションを表示することができます。この動作を構成できるコンポーネントは、次のとおりです。

- af:commandLink

- af:commandImageLink

- af:commandMenuItem (スタンドアロンまたはaf:menuBarコンポーネント内)

- af:commandNavigationItem (destination属性に値が指定されていない場合、ADF Facesフレームワークでは、次のシナリオでブラウザのポップアップ・メニューが有効になります。)

- af:commandNavigationItemがaf:trainコンポーネント内でレンダリングする2つのアンカー用

- af:commandNavigationItemがaf:breadCrumbsコンポーネント内でレンダリングされる場合

- af:commandNavigationItemがaf:navigationPaneコンポーネント(ヒントが付くタブ、バー、ボタン、選択肢、リスト)内でレンダリングされる場合

- af:panelTabbed: タブおよびオーバーフロー・インジケータ

- af:panelAccordion: 公開リンクおよびオーバーフロー・インジケータ

宛先を指定してアクションを起動しないコンポーネントに、この動作を構成できません。これらのコンポーネントの例には、次のものが含まれます。

- af:goLink

- af:goImageLink

- af:commandNavigationItem (ここでは、destination属性に値を指定し、action属性に値を指定しません)

18.3.1 コマンド・リンクに対するブラウザのポップアップ・メニューの構成

アプリケーションのweb.xmlファイルのoracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONコンテキスト・パラメータの値をnoに設定します。

作業を始める前に、次のようにします。

この機能をどのコマンド・コンポーネントに構成するかを理解します。詳細は、コマンド・リンクに対するブラウザのポップアップ・メニューの構成に関する項を参照してください。

コマンド・リンクにブラウザのポップアップ・メニューを構成する手順:

1. アプリケーション・ナビゲータで、「web.xml」をダブルクリックし、ファイルを開きます。
デフォルトでは、JDeveloperは概要エディタのweb.xmlファイルを開きます。

2. コンテキスト初期化パラメータ・テーブルに、oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONパラメータのエントリを追加し、これをnoに設定します。

3. 変更を保存して、web.xmlファイルを閉じます。

18.3.2 コマンド・リンクに対するブラウザのポップアップ・メニューを構成した場合の処理

コマンド・リンクに対するブラウザのポップアップ・メニューの構成に関する項で説明された手順を実行すると、例18-1に示すように、JDeveloperではweb.xmlファイルに値が書き込まれます。

例18-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構成オプションの詳細は、web.xmlでの構成に関する項を参照してください。

コマンド・リンクに対するブラウザのポップアップ・メニューの構成に関する項で説明されているように、エンド・ユーザーは、実行時に特定のコンポーネントによってレンダリングされたリンク上で右クリックして、ブラウザのポップアップ・メニューを起動できます。

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

ナビゲーションにコマンド・コンポーネントを使用するのに加え、ADF Facesには、アクション・イベントの起動時に特定の機能を実行するためにコマンド・コンポーネントとともに使用できるリスナー・タグも含まれています。次に、ADF Facesに含まれるリスナー・タグを示します。

- exportCollectionActionListener: ADF FacesアプリケーションからExcelのスプレッドシートにデータをエクスポートするために使用します。詳細は、10.9項「表、ツリーまたはツリー表からのデータのエクスポート」を参照してください。

- fileDownloadActionListener: サーバーからローカル・コンピュータへのファイルのダウンロードを開始するために使用します。詳細は、18.4.1項「ファイルをダウンロードするためのコマンド・コンポーネントの使用方法」を参照してください。

- resetActionListener: 送信した値をリセットするために使用します。ただし、データ・モデルの状態は変更されません。詳細は、18.4.2項「入力フィールドをリセットするためのコマンド・コンポーネントの使用方法」を参照してください。入力コンポーネントを以前の状態、つまりサーバーへの部分的または完全な送信が成功している状態にリセットする場合は、「リセット」ボタンを使用できます。詳細は、9.2.3項「formへの「リセット」ボタンの追加方法」を参照してください。

18.4.1 ファイルをダウンロードするためのコマンド・コンポーネントの使用方法

コマンド・ボタンなどのアクション・コンポーネントを作成し、fileDownloadActionListenerタグに関連付けることで、ユーザーがファイルをダウンロードする機能を作成できます。ユーザーがアクション・コンポーネントを選択またはクリックすると、図18-3に示すように、ユーザーが異なるダウンロード・オプションを選択できるポップアップ・ダイアログが表示されます。

図18-3 ファイルのダウンロード・ダイアログ

コマンド・ボタン、コマンド・リンクまたはメニュー項目などのアクション・コンポーネントにより、プログラムを使用してファイルのコンテンツがユーザーに送信されるよう、fileDownloadActionListenerタグは宣言的に使用します。特定のコンテンツ・タイプまたはファイル名を宣言することもできます。ファイルのダウンロードは、XMLHttp AJAXリクエストではなく通常のリクエストで処理する必要があるため、サポートされている場合は、親コンポーネントのpartialSubmit属性をfalseに設定する必要があります。

ヒント:

サーバーへのファイルのアップロードの詳細は、9.9項「ファイルのアップロード機能の使用方法」を参照してください。

コンテンツがブラウザに送信された後、そのコンテンツが表示または保存される方法は、ダイアログで選択したオプションにより異なります。プログラムで開くオプションを選択した場合、そのファイル・タイプに関連付けられているアプリケーションが起動されてコンテンツが表示されます。たとえば、テキスト・ファイルの場合はメモ帳アプリケーションが起動されます。ディスクに保存オプションを選択した場合は、ブラウザによっては、ファイル名およびコンテンツを格納する場所を選択するためのポップアップ・ダイアログが表示されます。

例18-2に、ユーザーにファイル・コンテンツ「Hi there!」をダウンロードするためにfileDownloadActionListenerタグを使用するコマンド・ボタンのタグを示します。

例18-2 コマンド・ボタンおよびfileDownloadActionListenerタグを使用したファイルのダウンロード

<af:commandButton value="Say Hello">
<af:fileDownloadActionListener filename="hello.txt"
contentType="text/plain; charset=utf-8"
method="#{bean.sayHello}"/>
</af:commandButton>

例18-3に、ファイルのダウンロード処理に使用されるマネージドBeanメソッドを示します。

例18-3 ファイルのダウンロード処理に使用されるマネージドBeanメソッド

public void sayHello(FacesContext context, OutputStream out) throws IOException{
OutputStreamWriter w = new OutputStreamWriter(out, "UTF-8");
w.write("Hi there!");
. . .
}

ファイルのダウンロード・メカニズムを作成する手順:

1. コンポーネント・パレットからページにアクション・コンポーネントをドラッグ・アンド・ドロップします(アクション・コンポーネントの詳細は、18.2項「ボタンおよびリンクのナビゲーション目的での使用」を参照してください)。

2. コンポーネント・パレットの「操作」セクションを開き、ファイルのダウンロード・アクション・リスナー・タグをアクション・コンポーネントの子としてドラッグ・アンド・ドロップします。

3. プロパティ・インスペクタで次の属性を設定します。

- contentType: text/plain、text/csv、application/pdfなど、ファイルのMIMEタイプを指定します。

- filename: オブジェクトの選択したファイル名を指定します。ファイル名を指定すると、通常は「ファイルの保存」ダイアログが表示されますが、最終的にはブラウザにより異なります。名前を指定しない場合、通常、コンテンツはブラウザにインライン表示されます(可能な場合)。

- method: ファイル・コンテンツのダウンロードに使用されるメソッドを指定します。methodには、FacesContextオブジェクトおよびOutputStreamオブジェクトの2つの引数を指定できます。OutputStreamオブジェクトは自動的に閉じられるため、このmethodの唯一の目的は、すべてのバイトをOutputStreamオブジェクトに書き込むことです。

たとえば、コマンド・ボタンのコードは次のようになります。

<af:commandButton text="Load File">
<af:fileDownloadActionListener contentType="text/plain"
filename="MyFile.txt"
method="#(mybean.LoadMyFile"/>
</af:commandButton>

18.4.2 入力フィールドをリセットするためのコマンド・コンポーネントの使用方法

resetActionListenerタグとコマンド・コンポーネントを組み合せて使用すると、入力値をリセットできます。すべての値は、nullまたは空に戻されます。入力コンポーネントを以前の状態、つまりサーバーへの部分的または完全な送信が成功している状態にリセットする場合は、「リセット」ボタンを使用する必要があります。詳細は、9.2.3項「formへの「リセット」ボタンの追加方法」を参照してください。

リセット・タグを使用する手順:

1. 18.2項「ボタンおよびリンクのナビゲーション目的での使用」の説明に従い、コマンド・コンポーネントを作成します。

2. コンポーネント・パレットからリセット・アクション・リスナーをコマンド・コンポーネントの子としてドラッグ・アンド・ドロップします。

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

注意:

アプリケーションにADFコントローラを含むFusionテクノロジ・スタックが使用されている場合は、ADFタスク・フローおよびXMLMenuModel実装を使用して、アプリケーションのページ階層にナビゲーション・システムを作成します。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ階層の作成」を参照してください。

アプリケーションはツリー式階層に関連付けて編成されたページで構成されます。ユーザーは、リンクのパスをドリルダウンして、ページ上の特定の情報にアクセスします。たとえば、図18-4に、トップレベルのHomeノードの下に3レベルのノードを持つ単純なページ階層を示します。トップレベルのノードは、ルート親ページを表します。第1レベルのノードのBenefitsおよびEmployee Dataは、第2レベルの子ノード(InsuranceやView Employeeなど)の一般情報を含む親ページを表します。この子ノードには、より具体的な情報が含まれます。その中のInsuranceノードは、第3レベルの子ノードのHealthおよびDentalの一般情報を含む親ノードでもあります。ページ階層の各ノード(ルートHomeノードは除く)は、同時に親ノードでもあり、子ノードでもあります。ページ階層の各ノードはページに対応しています。

図18-4 BenefitsおよびEmployeeページ階層

ページ階層のナビゲーションは、親子のリンクに従います。たとえば、Healthの情報を表示するには、ユーザーはBenefitsページからドリルダウンを開始し、2つの選択肢(一方がHealth)が用意されているInsuranceページに移動します。「Home」から始まり、「Health」で終わる選択済リンクのパスは、ツリーのフォーカス・パスと呼ばれます。

直接の親子のナビゲーションのみでなく、レベル間または親間のナビゲーションも可能です。たとえば、Dentalページから、ユーザーは第2レベルのPaid Time Offページに移動することも、第1レベルのBenefitsページまたはEmployee Dataページに移動することもできます。

図18-4に示すように、階層内のどのノードにもリンクされていないが、トップレベルのHomeノードと同じレベルにあるHelpノードは、グローバル・ノードです。グローバル・ノードは、階層内のどのページからもアクセスできるグローバル・ページ(「ヘルプ」ページなど)を表します。

ページ階層のWebユーザー・インタフェースで使用される一般的なウィジェットは、タブ、バー、グローバル・リンクで、すべてnavigationPaneコンポーネントを使用して作成できます。図18-5に、navigationPaneおよびその他のコンポーネントを使用してレンダリングされた図18-4の階層を示します。

図18-5 レンダリングされたBenefitsおよびEmployeeページ

図18-5に示すように、通常、タブは第1レベルのノードとして使用されます。ここでは、BenefitsおよびEmployee Detailページのタブがあります。InsuranceおよびPaid Time Offなどの第2レベルのノードはバーとして、HealthおよびDentalなどの第3レベルのノードはリストとしてレンダリングされます。ただし、タブは、第1および第2レベルのノードの両方に使用できます。(グローバル・ノードを表す)グローバル・リンクは、テキスト・リンクとしてレンダリングされます。図18-5で、Homeおよび「ヘルプ」グローバル・リンクはテキスト・リンクとしてレンダリングされています。

第1、第2、第3レベルのノードまたはグローバル・ノードのいずれであるかにかかわらず、1つのnavigationPaneコンポーネントは、1レベルのノードに対応します。ナビゲーション・アイテムのタイプに関係なく、navigationPaneコンポーネントはレベルに対してレンダリングするよう構成されており、navigationPaneコンポーネント内の各項目を表すには、必ずcommandNavigationItemコンポーネントを使用します。

navigationPaneコンポーネントは、ナビゲーション用のタブ、バー、リストおよびグローバル・リンクをレンダリングするだけです。図18-10や図18-11に示されているような、位置指定やページ背景のビジュアルなスタイル設定を行うには、decorativeBoxコンポーネントを第1レベルのnavigationPaneコンポーネントの親として使用します。decorativeBoxコンポーネントは、テーマおよびスキニング・キーを使用して、その様々なファセットの枠および色を制御します。たとえば、デフォルトのテーマを使用する場合、decorativeBoxコンポーネント本体は白、枠は青で、左上隅は丸くなります。ミディアム・テーマを使用する場合、本体は中間色の青になります。テーマおよびスキンの使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ヒント:

ページ階層を作成するには、階層内の各ページで同じレイアウトおよびルック・アンド・フィールを使用する必要があるため、ナビゲーション・コンポーネントの配置場所やスタイルを決定するためにテンプレートの使用を検討してください。詳細は、19.3項「ページ・テンプレートの使用」を参照してください。

より単純な階層の各ページのために一連のnavigationPaneコンポーネントを使用し、階層の各レベルを表します。次に、各レベルの各リンクに、commandNavigationItemコンポーネントをnavigationPaneコンポーネントの直接の子として追加します。たとえば、図18-5に示すように、Health insuranceページを作成するには、まず、ページに表示された各レベルに対してnavigationPaneコンポーネントを使用します。この場合、使用するのは、グローバル・リンク、第1レベルのノード、第2レベルのノード、第3レベルのノードの4つのレベルです。個々のリンクを表示するには、各navigationPaneコンポーネントにcommandNavigationItemコンポーネントを子として追加する必要があります。図18-6に示すように、Benefitsページを作成していた場合、3つのnavigationPaneコンポーネント(グローバル、第1、第2レベルの3つのレベル)のみを作成します。次に、このページから表示されるリンク用にcommandNavigationItemコンポーネントを作成します。

図18-6 第1レベルのページ

大規模な階層では、このプロセスは非常に時間がかかり、ミスも発生しやすくなります。大規模な階層の場合は、各ページに別々のcommandNavigationItemコンポーネントをそれぞれ作成するのではなく、XMLMenuModel実装およびマネージドBeanを使用して、ページのナビゲーション・アイテムを動的に生成することをお薦めします。メタデータ・ファイルとともに使用するXMLMenuModelクラスには、各ページに適切な数の階層レベルを生成するためのすべての情報と、各レベルに属するナビゲーション・アイテムが含まれます。navigationPaneコンポーネント内に複数のcommandNavigationItemコンポーネントを使用し、各ページで現在の項目を選択済としてマーキングするかわりに、各navigationPaneコンポーネントを宣言的に同じXMLMenuModel実装にバインドし、nodeStampファセットにcommandNavigationItemコンポーネントを1つ使用してナビゲーション・アイテムを指定します。commandNavigationItemコンポーネントは、navigationPaneコンポーネントのスタンプとして機能し、XMLMenuModelオブジェクトに保持されている(各レベルの)ノードのナビゲーション・アイテムにスタンプを設定します。デフォルトのActionListenerメカニズムを使用したJSFナビゲーション・モデルを使用して、ユーザーがナビゲーション・アイテムを選択した時のナビゲート先のページが選択されます。メニュー・モデルの詳細は、18.6項「メニュー・モデルを使用したページ階層の作成」を参照してください。

どのページでも、ユーザーの現在の位置をページ階層全体との関連で表示するには、一連のcommandNavigationItemコンポーネントまたは1つのcommandNavigationItemコンポーネントを含むbreadCrumbsコンポーネントをnodeStampとして使用し、現在のページ(フォーカス・パスの現在のノード)からルート・ページへ戻るリンクのパスを指定します。

XMLMenuModelを使用したナビゲーション階層の作成の詳細は、18.6項「メニュー・モデルを使用したページ階層の作成」を参照してください。ナビゲーション階層の手動による作成の詳細は、18.7項「単純なナビゲーション階層の作成」を参照してください。

注意:

アプリケーションの変更の反映に使用できるメニュー(「Open」および「Delete」コマンドが含まれる「File」メニューなど)を作成する場合は、第14章「メニュー、ツールバーおよびツールボックスの使用方法」を参照してください。

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

注意:

アプリケーションにFusionテクノロジ・スタックまたはADFコントローラが使用されている場合は、ADFタスク・フローおよびXMLMenuModel実装を使用して、アプリケーションのページ階層にナビゲーション・システムを作成します。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ階層の作成」を参照してください。

18.5項「ページ階層用のナビゲーション・アイテムの使用」に、複数のcommandNavigationItem子コンポーネントを含むnavigationPaneコンポーネントを使用して、非常に単純なページ階層用のナビゲーション・メニューを作成する方法が説明されています。より複雑なページ階層で同じ方法を使用すると時間がかかり、ミスが起こりやすくなります。ナビゲーションを可能にするすべての項目を作成するために、複数のJSFページのnavigationPaneおよびbreadCrumbsコンポーネントに個々のcommandNavigationItemコンポーネントを手動で挿入し構成するのは、非効率的で単調な作業です。各項目について正確なselectedステータスを管理したり、現在のページからルート・ページに戻るブレッドクラム・リンクをたどって追跡するのも困難です。

より複雑なページ階層の場合(および単純なページ階層の場合でも)、ナビゲーション・メニューを作成するより効率的な方法は、メニュー・モデルを使用することです。メニュー・モデルは、特別な種類のツリー・モデルです。ツリー・モデルは、行キーで索引付けされた行のコレクションです。ツリーでは、現在行に子の行を含めることができます(ツリー・モデルの詳細は、10.5項「ツリーへのデータの表示」を参照してください)。メニュー・モデルは、現在フォーカス(フォーカス・ノード)があるノードのrowKeyを取得できるツリー・モデルです。メニュー・モデルにはページ・ナビゲーションの特別な情報はなく、ツリーにアクセスするノードに対する要件もありません。

XMLMenuModelクラスは、ナビゲーション・ツリー・モデルからメニュー・モデルを作成します。ただし、XMLMenuModelクラスには、XMLメタデータにナビゲーションの階層ツリーを定義できる追加のメソッドがあります。(他のADF Facesのメニュー・モデル・クラスの1つを使用している場合のように)Javaクラスを作成し多数のマネージドBeanを構成してメニュー・モデルを定義および作成するかわりに、XMLMenuModelクラスでメニュー・モデルを作成する際に必要なすべてのノード情報を含む1つ以上のXMLMenuModelメタデータ・ファイルを作成します。

パフォーマンスのヒント:

メニュー・モデルを含むnavigationPaneコンポーネントを使用すると、ユーザーがタブを切り替えるたびにフル・ページ・リフレッシュが実行されます。かわりに、panelTabbedコンポーネントを使用できます(8.9項「アコーディオン・パネルおよびタブ付きのパネルにおけるコンテンツの表示または非表示」を参照)。このコンポーネントでは、タブ付きコンテンツの部分ページ・レンダリングがサポートされています。ただし、ナビゲーション・モデルにはバインドできず、ページ内からすべてのコンテンツにアクセスできる必要があるため、適用性は制限されています。

メニュー・モデルを使用してページ階層を作成する手順:

- ページ階層のJSFナビゲーション・ルールおよびナビゲーション・ケースを作成し、XMLMenuModelメタデータを作成します。18.6.1項「メニュー・モデル・メタデータの作成方法」を参照してください。

- XMLMenuModelクラスにマネージドBeanを構成します。このマネージドBeanは、アプリケーションにより階層の作成に使用されます。この構成は、JDeveloperで「ADFメニュー・モデルの作成」ダイアログを使用してXMLMenuModelメタデータ・ファイルを作成する際に、自動的に行われます。18.6.2項「ADFメニュー・モデルの作成ウィザードを使用する場合の処理」を参照してください。

- 各階層ノード(グローバル・ノードも含む)にJSFページを作成します。

ヒント:

通常、各レベルの項目(グローバル項目およびブレッドクラムを含む)に対するファセットが含まれるページ・テンプレートを使用して、各JSFページを作成します。たとえば、グローバル項目を表すnavigationPaneコンポーネントはnavigationGlobalという名前のファセットでラップし、第1レベルのタブを表すnavigationPaneコンポーネントはnavigation1という名前のファセットでラップします。ページ・テンプレートの作成の詳細は、第19章「フラグメント、ページ、テンプレート、コンポーネントの作成および再利用」を参照してください。

- 各ページで、navigationPaneおよびbreadCrumbsコンポーネントをXMLMenuModelクラスにバインドします。18.6.3項「JSFページでのXMLMenuModelへのバインド方法」および18.6.4項「breadCrumbsコンポーネントの使用方法」を参照してください。

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

XMLMenuModelメタデータ・ファイルは、XML形式によるページ階層用のナビゲーション・メニューの表現です。XMLMenuModelメタデータ・ファイルでは、ページ階層全体が、ファイルのルート要素であるmenu要素内に説明されています。各XMLMenuModelメタデータ・ファイルにはmenu要素が必要で、使用できるmenu要素は1つのみです。

階層の残りのノードは、項目ノード、グループ・ノードおよび共有ノードで構成されています。項目ノードは、階層のナビゲート可能なノード(またはページ)を表します。たとえば、図18-7に示すような階層を作成するとします。

図18-7 サンプルのページ階層

階層の各ノードにユーザーがナビゲートできる独自のページを作成する場合は、各ページのメタデータに項目ノードを作成します。親ノードに子ノードをネストさせて階層を作成します。ただし、Employee Dataノードにはページが必要ないが、ユーザーが直接View Employeeページにナビゲートできるようにするとします。次に、グループ・ノードを使用して、Employee Dataページを表し、グループ・ノードのidref属性を使用して、エンド・ユーザーがEmployee Dataタブをクリックしたときに開くページ(View Employeeページ)を参照します。グループ・ノードを使用すると、単に子ノードの集約であるノード用にページを作成せずに階層を維持できます。

共有ノードを使用して、メニュー・モデルをネストすることもできます。この方法は、ページ階層が維持しやすくなるため、階層にサブツリー(たとえば、Benefitsツリーなど)がある場合にお薦めします。たとえば、アプリケーション全体で再利用できるように、Benefitsツリー全体を独自のモデルとして作成するとします。それぞれに使用するためにノードを作成するかわりに、別のメニューとして一度ノードを作成し、異なる階層内で、共有ノードを使用すると、Benefitsメニュー・モデルを参照できます。

例18-4に、図18-7に示されているページ階層を定義するための、XMLMenuModelメタデータ・ファイルを示します。

例18-4 XMLMenuModelメタデータ・ファイルのサンプル

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<itemNode id="Home" focusViewId="/home.jspx" label="Home" action="goHome">
<itemNode id="benefits" focusViewId="/benefits.jspx" action="goBene"
label="Benefits">
<itemNode id="insurance" focusViewId="/insurance.jspx" action="goIns"
label="Insurance">
<itemNode id="health" focusViewId="/health.jspx" action="goHealth"
label="Health"/>
<itemNode id="dental" focusViewId="/dental.jspx" action="goDental"
label="Dental"/>
</itemNode>
<itemNode id="pto" focusViewId="/pto.jspx" action="goPto"
label="Paid Time Off">
<itemNode id="vacation" focusViewId="/vacation.jspx"
action="goVacation" label="Vacation"/>
<itemNode id="sick" focusViewId="/sick.jspx" action="goSick"
label="Sick Pay"/>
</itemNode>
</itemNode>
<groupNode id="empData" idref="newEmp" label="Employee Data">
<itemNode id="newEmp" focusViewId="/createemp.jspx" action="goCreate"
label="Create New Employee"/>
<itemNode id="viewdata" focusViewId="/viewdata.jspx" action="goView"
label="View Data"/>
</groupNode>
</itemNode>
<itemNode id="Help" focusViewId="/globalhelp.jspx" action="goHelp"
label="Help"/>
<itemNode id="Preferences" focusViewId="/preferences.jspx" action="goPref"
label="Preferences"/>
</menu>

ルートのmenu要素内において、グローバル・ノードは、menu要素の直接の子である任意のタイプのノードです。つまり、menu要素の下の第1レベルの要素はグローバル・ノードです。たとえば、例18-4のコードに、Home、HelpおよびPreferencesの3つのグローバル・ノードが示されています。第1レベルの子ノード内に、ノードをネストさせて、さらに多くのレベルのナビゲーションを提供できます。たとえば、例18-4のコードでは、Homeの下にBenefitsとEmployee Dataの2つの第2レベルのノードが示されています。Benefits内では、InsuranceおよびPaid Time Offの2つの第3レベルのノードとその他のノードがあります。

JDeveloperでは、ADFメニュー・モデルの作成ウィザードを提供することで、XMLMenuModelクラス用のメタデータの作成が簡略化されています。

XMLMenuModelメタデータを作成する手順:

1. ページ階層のすべてのノードのナビゲーション・ケースが含まれるグローバルなJSFナビゲーション・ルールを1つ作成します。
たとえば、図18-4に示されているページ階層には、グローバルのHelpノードを含む10のノードがあります。この場合、例18-5に示すように、faces-config.xmlファイルの1つのグローバル・ナビゲーション・ルール内に10のナビゲーション・ケースを作成します。

各ナビゲーション・ケースに、一意の結果文字列と、指定された文字列に一致する結果値がナビゲーション・システムによって返された場合に表示するJSFページへのパスを指定します。

例18-5 faces-config.xml内のページ階層のグローバル・ナビゲーション・ルール

<navigation-rule>
<navigation-case>
<from-outcome>goHome</from-outcome>
<to-view-id>/home.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHelp</from-outcome>
<to-view-id>/globalhelp.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goEmp</from-outcome>
<to-view-id>/empdata.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goBene</from-outcome>
<to-view-id>/benefits.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goIns</from-outcome>
<to-view-id>/insurance.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goPto</from-outcome>
<to-view-id>/pto.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goView</from-outcome>
<to-view-id>/viewdata.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goCreate</from-outcome>
<to-view-id>/createemp.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHealth</from-outcome>
<to-view-id>/health.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goDental</from-outcome>
<to-view-id>/dental.jspx</to-view-id>
</navigation-case>
...
</navigation-rule>

JDeveloperにおけるナビゲーション・ケースの作成方法の詳細は、2.3項「ページ・フローの定義」を参照してください。

2. アプリケーション・ナビゲータで、XMLMenuModelメタデータ・ファイルを作成するプロジェクトを探します。プロジェクトの「Webコンテンツ - WEB-INF」フォルダで、faces-config.xmlファイルを右クリックし、ポップアップ・メニューから「ADFメニューの作成」を選択します。

注意:

アプリケーションでADFコントローラが使用されている場合は、このメニュー・オプションを使用できません。かわりに、バインド・タスク・フローを使用して階層を作成できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ階層の作成」を参照してください。

3. 「ADFメニュー・モデルの作成」ダイアログで、XMLMenuModelメタデータ・ファイルのファイル名(root_menuなど)を入力します。

4. メタデータ・ファイルのディレクトリを入力します。JDeveloperにより、デフォルトで、アプリケーションのWEB-INFディレクトリにXMLMenuModelメタデータ・ファイルが保存されます。
「OK」をクリックすると、JDeveloperにより自動的に次の操作が行われます。

- 手順3で指定した名前がマネージドBean名として使用され、faces-config.xmlファイルにモデルのマネージドBeanが作成されます。

- マネージドBeanのsourceマネージド・プロパティの値が、手順3で指定した/WEB-INF/root_menu.xmlなどのXMLMenuModelメタデータ・ファイルに設定されます。

- 例18-6に示すように、ソース・ファイル(/WEB-INF/root_menu.xml)が、空のXMLMenuModelメタデータ・ファイルとしてソース・エディタに表示されます。

例18-6 空のXMLMenuModelメタデータ・ファイル

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu"></menu>

JDeveloperにより自動的に追加されるマネージドBean構成の詳細は、18.6.2項「ADFメニュー・モデルの作成ウィザードを使用する場合の処理」を参照してください。

5. 構造ウィンドウでmenuノードを選択し、プロパティ・インスペクタに適切な情報を入力します。
表18-1に、menu要素に指定できる属性を示します。

表18-1 menu要素の属性

属性

説明

resourceBundle

オプション。これは、実行時のナビゲーション・アイテムのラベル(表示されるテキスト)に使用するためのリソース・バンドルです。たとえば、org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundleなどです。

var

リソース・バンドルを使用している場合は、ナビゲーション・アイテム・ラベルのEL式のバンドルの参照に使用するIDを指定します。#{bundle.somelabel}などです。リソース・バンドルを使用するXMLMenuModelメタデータ・ファイルのサンプルは、例18-7を参照してください。

xmlns

必須。http://myfaces.apache.org/trinidad/menuに設定します。

例18-7に、ナビゲーション・アイテムのラベルのリソース・バンドルにアクセスするためにEL式を使用する、サンプルのXMLMenuModelメタデータ・コードを示します。

例18-7 リソース・バンドルを使用した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クラスでは、解析中に各リソース・バンドルに一意のハッシュ・キーが割り当てられていることを確認することにより、この可能性に対応します。

リソース・バンドルの使用方法の詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

6. 構造ウィンドウで、必要に応じてitemNode、groupNodeまたはsharedNodeを使用して、階層のノードに必要な要素を追加します。まず、menuを右クリックして「menuの中に挿入」を選択し、図18-8に示されているように、ポップアップ・メニューから必要な要素を選択します。

図18-8 menuに要素を挿入するためのポップアップ・メニュー

要素は次のいずれかです。

- itemNode: ユーザーによる選択時にナビゲーションを実行するノードを指定します。

- groupNode: 子コンポーネントをグループ化します。groupNode自体にナビゲーション機能はありません。子ノードは、itemNodeまたは他のgroupNodeです。
たとえば、Employee Dataノードにはページが必要ないが、ユーザーが直接View Employeeページにナビゲートできるようにするとします。その場合は、グループ・ノードを使用し、目的の子ノードのid属性をグループ・ノードのidref属性として指定することによって、Employee Dataページを表します。グループ・ノードを使用すると、単に子ノードの集約であるノード用にページを作成せずに階層を維持できます。

- sharedNode: 他のXMLMenuModelインスタンスを参照します。sharedNode要素は真のノードではなく、ナビゲーションの実行もノード自体へのレンダリングも行われません。
sharedNode要素は、階層内の任意の場所に挿入できます。たとえば、例18-8に示されているコードでは、sharedNode要素によりグローバル・ノードと同じレベルにサブメニューが追加されています。

例18-8 sharedNodeのサンプル・コード

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu"
<itemNode id="in1" label="Home" ../>
<sharedNode ref="#{shared_menu}"/>
<itemNode id="in6" label="Help" ../>
</menu>

XMLMenuModelメタデータ・ファイルを作成すると、図18-9に示すように、メニュー・メタデータのインデント・レベルが構造ウィンドウに表示されるツリー構造に正確に反映されます。

図18-9 構造ウィンドウのXMLMenuModelメタデータのツリー構造

7. ノードの作成に使用されている各要素に、プロパティ・インスペクタでプロパティを設定します。itemNode要素は表18-2に、groupNode要素は表18-3に、sharedNode要素は表18-4に説明されています。

表18-2 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値。

たとえば、ノードのアクション結果が(faces-config.xmlファイルに構成されているように)/page_one.jspxにナビゲートする場合は、focusViewIdも/page_one.jspxであることが必要です。

focusViewIdは、ナビゲーションは実行しません。ページ・ナビゲーションは、actionまたはdestination属性によって行われます。ただし、XMLMenuModelが現在のフォーカス・パスを確認するためにfocusViewIdが必要です。

id

必須。ノードの一意の識別子を指定します。

例18-4に示されているように、各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から決定されます。

例18-9に示されているgroupNodeのコードを例にとります。実行時にユーザーがgroupNode id="gn1"、groupNode id="gn11"またはitemNode id="in1"をクリックすると、最初に到達したitemNode(itemNode id="id1")で指定されているように、ナビゲーションの結果は"goToSubTabOne"になります。表18-3に、groupNode要素を使用する際に指定する必要のある属性を示します。

例18-9 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.jspx"/>
<itemNode id="in2" label="LEVEL2_TAB_1" action="goToSubTabTwo"
focusViewId="/menuDemo/subtab2.jspx"/>
</groupNode>
<itemNode id="in3" label="PRIMARY_TAB_1" focusViewId="/menuDemo/tab2.jspx"
destination="/faces/menuDemo/tab2.jspx"/>
</groupNode>
<itemNode id="gin1" label="GLOBAL_TAB_1" action="goToGlobalOne"
focusViewId="/menuDemo/global1.jspx"/>
<itemNode id="gin2" label="GLOBAL_TAB_2"
destination="/faces/menuDemo/global2.jspx"
focusViewId="/menuDemo/global2.jspx"/>
</menu>

表18-3 groupNode要素の属性

属性

説明

id

グループ・ノードの一意の識別子。

例18-4に示されているように、各groupNodeのIDにgnXを使用することをお薦めします。ここで、gnXはgn1、gn2などです。

idref

子ノードのID(itemNodeまたは別のgroupNode)を指定します。子ノードとしてgroupNodeを追加する場合、その子は別のgroupNodeなどを参照できますが、最終的には、子のitemNodeは最後の子として参照する必要があります。

idref属性には、空白で区切って複数の子IDを指定でき、IDはリストされた順序で処理されます。

label

グループ・ノードに表示するラベル・テキストを指定します。リソース・バンドルの文字列へのEL式(#{bundle.somelabel}など)にすることもできます。

表18-4 sharedNode要素の属性

属性

説明

ref

faces-config.xmlファイルに構成されているように、別のXMLMenuModelクラスのマネージドBean名(#{shared_menu}など)を指定します。

実行時に、参照ナビゲーション・メニューが作成され、メイン(ルート)のメニューにサブメニューとして挿入されてレンダリングされます。

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

ADFメニュー・モデルの作成ウィザードを使用してXMLMenuModelメタデータ・ファイルを作成する場合、マネージドBean名として指定したメタデータ・ファイル名を使用して、JDeveloperによりfaces-config.xmlファイルのメタデータ・ファイルにマネージドBeanが自動的に構成されます。

例18-10に、XMLMenuModelメタデータ・ファイルの構成が1つ含まれるfaces-config.xmlファイルの一部を示します。JDeveloperでは、デフォルトで、oracle.adf.view.rich.model.MDSMenuModelクラスがマネージドBeanクラスとして使用され、必須で変更できないrequestはマネージドBeanスコープとして使用されます。

例18-10 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値は、取得されて、ソース・メニュー・メタデータ・ファイルが開かれて解析されると使用可能になります。これにより、実際のコンポーネントをレンダリングする必要がない場合でも、階層全体を作成できます。
createHiddenNodesプロパティは、sourceプロパティの前に配置する必要があります。JDeveloperによってマネージドBeanが自動的に設定される際は、このように配置されます。sourceマネージド・プロパティからメニューのXMLメタデータを適切に解析および作成するには、この値がXMLMenuModelマネージドBeanに事前に設定されている必要があります。

- source: 使用するソース・メタデータ・ファイルを指定します。

ウィザードを使用してプロジェクトに作成される各XMLMenuModelメタデータ・ファイルに対して、JDeveloperではfaces-config.xmlファイルにマネージドBeanが構成されます。たとえば、XMLMenuModelでsharedNode要素を使用して、別のXMLMenuModelメタデータ・ファイルを使用する場合(例18-8を参照)、2つのメタデータ・ファイルを作成します。JDeveloperにより、faces-config.xmlファイルに2つのマネージドBean構成が追加されます。例18-11に示すように、1つはメイン(ルート)のメニュー・モデル用で、もう1つのマネージドBeanは共有(参照)メニュー・モデル用です。

例18-11 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>true</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が含まれます。

18.6.3 JSFページでのXMLMenuModelへのバインド方法

ページ階層の各ノードは1つのJSFページに対応します。各ページで、グローバル・アイテムを含め、XMLMenuModelメタデータ・ファイルで定義済の各レベルのナビゲーション・アイテムにnavigationPaneコンポーネントを1つ使用します。レベルはゼロベースの索引の番号によって定義されます。メタデータ・ファイルのグローバル・ノード(すなわち、例18-4で示されているように、menu要素の下の直接の子ノード)から始まり、level属性値は0(ゼロ)で、次のレベル(通常はタブ)は1、その次のレベル(通常はバー)は2、などのように続きます。たとえば、図18-7および例18-4に示すようなページ階層がある場合、(Homeノードの下の3つのレベルのナビゲーションに)Homeなどのページで3つのnavigationPaneコンポーネントを使用し、グローバル・ノードにnavigationPaneコンポーネントをもう1つ使用します。

ヒント:

メニュー・モデルにより、動的に階層(各navigationPaneコンポーネントに表示されるリンク)が決定され、フォーカス・パスの現在のノードが選択済として設定されるため、事実上、各ページに同じコードを再利用できます。実行する必要があるのは、ページのドキュメント・タイトルの変更と、そのページに表示する特定のページ・コンテンツの追加のみです。

コードが似ているため、navigationPaneコンポーネントを含むファセットのみが存在する単一のページ・フラグメントを作成し、ページのドキュメント・タイトルの変更やページ・コンテンツの追加を行う各ページにそのフラグメントを追加できます。

18.7.1項「単純なページ階層の作成方法」で説明されているように、各階層レベルに使用するナビゲーション・アイテムのタイプ(buttons、tabsまたはbarなど)を指定するにはhint属性を使用します。ただし、複数のcommandNavigationItemコンポーネントを手動で追加してナビゲーション・アイテムを指定するのではなく、例18-12に示すように、各navigationPaneコンポーネントをXMLMenuModelマネージドBeanにバインドし、各navigationPaneコンポーネントのnodeStampファセットにcommandNavigationItemコンポーネントを1つのみ挿入します。

例18-12 XMLMenuModelマネージドBeanにバインドされたnavigationPaneコンポーネント

<af:navigationPane var="menuNode" value="#{root_menu}" level="1"
hint="tabs">
<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ではページにそれらの項目は表示されません。

XMLMenuModelマネージドBeanにバインドする手順:

1. メニュー・タブのスタイルを設定する場合は、コンポーネント・パレットのレイアウト・セクションから装飾ボックスをJSFページにドラッグ・アンド・ドロップして、decorativeBoxコンポーネントを作成します。テーマを設定して、タブの表示方法を決定します。有効な値は次のとおりです。

- default: 本体は白で、枠は青です。左上隅は丸くなります。

- light: 本体は薄い青です。左上隅は丸くなります。

- medium: 本体は中間色の青です。左上隅は丸くなります。

- dark: 本体は濃い青です。左上隅は丸くなります。

テーマの表示方法は変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

2. コンポーネント・パレットからJSFページにナビゲーション・ペインをドラッグ・アンド・ドロップして、navigationPaneコンポーネントを作成します。階層の各レベルにnavigationPaneコンポーネントを追加します。

ヒント:

ナビゲーション・ペイン・コンポーネントは、コンポーネント・パレットのレイアウト・ペインにあります。

たとえば、図18-5の階層のようなページを作成するには、navigationPaneコンポーネントを4つドラッグ・アンド・ドロップします。

3. プロパティ・インスペクタで「共通」セクションを開き、各navigationPaneコンポーネントのhint属性を次に示すナビゲーション・アイテムのいずれかのタイプに設定して、navigationPaneで次のものをどのように表示するかを決定します。

- bar: バーで分割されたナビゲーション・アイテムを表示します。図18-11のInsuranceおよびPaid Time Offリンクなどがこれに当たります。

- buttons: グローバル領域のバーで分割されたナビゲーション・アイテムを表示します。図18-11のHomeおよび「ヘルプ」リンクなどがこれに当たります。

- choice: 関連付けられたドロップダウン・アイコンがクリックされたときに、ポップアップ・リストにナビゲーション・アイテムを表示します。navigationPaneコンポーネントのicon属性に値を含める必要があります。これにより、title属性を使用して、ラベルをドロップダウン・リストを関連付けることができます。

- list: ナビゲーション・アイテムを箇条書きリストで表示します。図18-11のHealthおよびDentalリンクなどがこれに当たります。

- tabs: ナビゲーション・アイテムをタブで表示します。図18-11のBenefitsおよびEmployee Dataタブなどがこれに当たります。

4. XMLMenuModelメタデータ・ファイルの適切なレベルのメタデータを指すように、level属性を設定します。level属性はゼロベースの索引の番号によって定義されます。メタデータ・ファイルのグローバル・ノード(すなわち、例18-4で示されているように、menu要素の下の直接の子ノード)から始まり、level属性値は0(ゼロ)で、次のレベル(通常はタブ)は1、その次のレベル(通常はバー)は2、などのように続きます。
commandNavigationItemコンポーネントは、親navigationPaneコンポーネントのlevel属性を介して、メタデータ・ファイルからそのメタデータを取得できます。level属性値を指定しない場合は、デフォルトで0(ゼロ)が使用されます。これは、navigationPaneコンポーネントでは、commandNavigationItemコンポーネントによってレンダリングされるmenu要素の下の第1レベルからメタデータが取得されるということです。

5. プロパティ・インスペクタで、「データ」セクションを開きます。value属性を、faces-config.xmlファイルのルートXMLMenuModelクラスに構成されているメニュー・モデルのマネージドBeanに設定します。

注意:

value属性は、ルート・メニュー・モデル、および共有ノードによって参照されるメニュー・モデルを参照できます。値属性で共有ノードを参照する場合、faces-config.xmlファイルは、メニュー・モデル・メタデータ・ファイルのルート・メニュー・モデル定義で使用されるものではなく、異なるマネージドBeanの名前の新しいマネージドBeanエントリを含む必要があります。これにより、共有ノードのメニュー・モデルが、値属性で参照できるルート・メニュー・モデルにプロモートされます。

6. var属性を、メニュー・モデルから必要なデータを取得するためにcommandNavigationItemコンポーネントで使用するテキストに設定します。

実行時に階層が作成されて各ノードにスタンプが設定されると、EL式を使用して特定可能なvar属性に現在のノードのデータがコピーされます。varプロパティを使用して、このプロパティに使用する名前をEL式に指定します。

ヒント:

ページまたはアプリケーションのすべてのnavigationPaneコンポーネントのvar属性に同じ値を使用します。

7. navigationPaneコンポーネントのnodeStampファセットに、コンポーネント・パレットから「ナビゲーション・アイテム」をドラッグ・アンド・ドロップします。

8. (必要な情報が含まれるメタデータを持つ)メニュー・モデルを参照するEL式を使用して、対応する値がメタデータに保持される残りの属性に値を設定します。手順6で、値がメタデータで保持されている対応するitemNode要素の名前とともに、親のnavigationPaneコンポーネントに設定したvar属性の値を使用してこれらの値にアクセスします。表18-5に、対応する値がメタデータにあるナビゲーション・アイテムの属性を示します。

表18-5 ナビゲーション・アイテムの属性および関連付けられたメニュー・モデルの属性

ナビゲーション・アイテムの属性

関連付けられたメニュー・モデル要素の属性

text

label

action

doAction

icon

icon

destination

destination

visible

visible

rendered

rendered

たとえば、親のnavigationPaneコンポーネントのvar属性をmenuNodeに設定した場合、action属性の値のEL式として#{menuNode.doAction}コンポーネントを使用します。これは、各ノードのメタデータに設定されているactionプロパティに解決されます。例18-13に、HRの例のメニュー・モデルにバインドするためのJSFコードを示します。

例18-13 XMLモデルへのバインド

<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>

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

メニュー・モデルを使用したブレッドクラムの作成は、ページ階層の作成に似ています。commandNavigationItemコンポーネントにスタンプを設定するnodeStampファセットを含むbreadCrumbsコンポーネントは、モデルのデータとともに使用します。

ブレッドクラムを作成する手順:

1. コンポーネント・パレットからJSFページにブレッド・クラム・コンポーネントをドラッグ・アンド・ドロップして、breadCrumbsコンポーネントを作成します。

2. デフォルトでは、ブレッドクラム・リンクは水平に表示されます。レイアウトが垂直になるように変更するには、プロパティ・インスペクタで、「共通」セクションを開き、orientation属性をverticalに設定します。

3. プロパティ・インスペクタで、「データ」セクションを開きます。faces-config.xmlファイルに構成されているように、value属性をルート・メニュー・モデルのマネージドBeanに設定します。これが、navigationPaneコンポーネントがバインドされるのと同じBeanです。

注意:

value属性が参照できるのは、共有ノードを介して参照されるメニュー・モデルではなく、ルート・メニュー・モデルのみです。たとえば、(例18-8に示されているように)メインのXMLMenuModel要素に共有ノードを使用している場合は、JDeveloperにより、その共有ノードにマネージドBean構成が作成され、共有モデルを使用するルートXMLMenuModel Beanも作成されます。共有モデルのマネージドBeanは、起動時にメニュー・ツリーが解析されると、ルート・メニュー・モデルのマネージドBeanに自動的に組み込まれます。

4. var属性を、メニュー・モデルから必要なデータを取得するためにcommandNavigationItemコンポーネントで使用するテキストに設定します。

実行時に階層が作成されて各ノードにスタンプが設定されると、EL式を使用して特定可能なvar属性に現在のノードのデータがコピーされます。varプロパティを使用して、このプロパティに使用する名前をEL式に指定します。

ヒント:

ページまたはアプリケーションのnavigationPaneコンポーネントで実行したように、breadCrumbsコンポーネントのvar属性に同じ値を使用できます。

5. コンポーネント・パレットから「ナビゲーション・アイテム」をドラッグ・アンド・ドロップし、breadCrumbsコンポーネントのnodeStampファセットに、子としてcommandNavigationItemコンポーネントを1つ追加します。

注意:

breadCrumbsコンポーネントのnodeStampファセットが、breadCrumbsコンポーネントのvalue属性に指定するメニュー・モデルに従って表示されるリンクを決定します。breadCrumbsコンポーネントのvalue属性に対して、レンダリングするメニュー・モデルを指定しない場合、実行時にリンクは表示されません。スタンプが不要のためメニュー・モデルを使用しない場合、nodeStampファセットをbreadCrumbsコンポーネントに使用しないでください。

6. (必要な情報が含まれるメタデータを持つ)メニュー・モデルを参照するEL式を使用して、対応する値がメタデータに保持される残りの属性に値を設定します。手順4で、値がメタデータで保持されている対応するitemNode要素の名前とともに、親のbreadCrumbsコンポーネントに設定したvar属性の値を使用してこれらの値にアクセスします。表18-5に、対応する値がメタデータにあるナビゲーション・アイテムの属性を示します。
たとえば、breadCrumbsコンポーネントのvar属性をmenuNodeに設定した場合、action属性の値のEL式として#{menuNode.doActionコンポーネントを使用します。これは、各ノードのメタデータに設定されているactionプロパティに解決されます。

例18-14 MenuModelにバインドされたbreadCrumbsコンポーネント

<af:breadCrumbs var="menuNode" value="#{root_menu}">
<f:facet name="nodeStamp">
<af:commandNavigationItem text="#{menuNode.label}"
action="#{menuNode.doAction}"/>
</f:facet>
</af:breadCrumbs>

18.6.5 実行時の処理

navigationPaneコンポーネントの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クラスではレンダリングは行われません。navigationPaneコンポーネントでは、コールからgetFocusRowKey()メソッドへの戻り値を使用して、レベルのナビゲーション・メニュー・アイテムがページにレンダリングされます。

navigationPaneコンポーネントのnodeStampファセットの中のcommandNavigationItemコンポーネントは、各ナビゲーション・アイテムのラベル・テキストおよびアクション結果を提供します。nodeStampファセットにスタンプが設定されるたびに、現在のナビゲーション・アイテムのデータが、ELに到達可能なプロパティにコピーされます。このプロパティの名前は、nodeStampファセットを含むnavigationPaneコンポーネントのvar属性によって定義されます。nodeStampは、ELに到達可能なプロパティから詳細なプロパティを取得して、各アイテムのデータを表示します。ナビゲーション・メニューがレンダリングを完了すると、このプロパティは削除されます(または元の値に戻されます)。ユーザーがナビゲーション・アイテムを選択すると、デフォルトのJSF actionListenerメカニズムで、アクション結果文字列または宛先URIを使用して、ページ・ナビゲーションを処理します。

XMLMenuModelクラスは、nodeStampファセットとともに、ナビゲーション・アイテムを選択済としてレンダリングするかどうかを制御します。前述のように、XMLMenuModelオブジェクトは、各ノードのviewId属性情報が含まれたツリー・モデルから作成されます。XMLMenuModelクラスには、getFocusRowKey()メソッドがあります。このメソッドは、フォーカスされているページを判別し、ノードがフォーカス・パスにあれば選択済として自動的にノードをレンダリングします。最も単純な形式のgetFocusRowKey()メソッドは、次のような処理を実行します。

- 現在のviewId属性が取得されます。

- 重複するviewId値の解決に使用される内部マップのID、およびメニュー・モデルの作成時にツリーをトラバースすることにより作成されたviewIdFocusPathMapオブジェクトのIDと、viewId属性の値が比較されます。

- 現在のviewId属性があるノードへのフォーカス・パスが返されるか、現在のviewId属性値が検出されない場合にはnullが返されます。

ノードのviewId属性は、フォーカスrowKeyオブジェクトの特定に使用されます。モデルの各項目には、現在のrowKeyオブジェクトに基づいてスタンプが設定されます。ユーザーがナビゲートして現在のviewId属性が変更されると、モデルのフォーカス・パスも変更されて、新しいナビゲーション・アイテムのセットがアクセスされます。

18.6.6 カスタム属性の使用について

作成したカスタム属性を表示できるのはitemNode要素のみです。itemNode要素を追加してカスタム属性の値にアクセスできるようにするには、次のようにしてメニュー・モデルからツリーを取得する必要があります。

- メニュー・モデルのgetWrappedData()メソッドをコールします。

- getFocusRowKey()メソッドをコールして、現在のフォーカス・パスを取得します。

- このフォーカス・パスを使用してツリーをトラバースし、フォーカス・パスのノードのリストを返します。

- getCustomProperty() APIをコールし、カスタム属性に関してこれらのノードを1つ以上テストします。

例18-15に、必要なコードの例を示します。

例18-15 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;
}

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

図18-10および図18-11に、navigationPaneコンポーネントおよび個々のcommandNavigationItemコンポーネントを使用して、図18-4に示すページ階層のビューを作成した場合に、ユーザー・インタフェースがどのように表示されるかの例を示します。

図18-10 View Employeeページから使用可能なナビゲーション・アイテム

手動で階層を作成する場合には、各ページのフォーカス・パス(ページが存在する階層内の正確な場所)を確認し、各ページに必要なnavigationPanesとcommandNavigationItemコンポーネントの正確な数、ならびにユーザーがページを表示した際に各コンポーネントを選択済として構成する必要があるかどうかを決定する必要があります。たとえば、Employee Dataページが表示されている図18-10では、必要なものはEmployee Dataの子のバーのみで、Employee Dataタブは選択済としてレンダリングされています。

Healthページを表示している図18-11でも同様に、Benefitsでは子のバーのみが必要であり、Benefitsタブを選択済として構成する必要があります。このページではさらに、Insuranceの下に子ノードを作成します。これは、ページの横に垂直のリストとして表示されます。ページのコンテンツが中央に(垂直のリストの右側)に表示されます。

図18-11 Healthページから使用可能なナビゲーション・アイテム

使用するナビゲーション・アイテムのタイプ(タブやバーなど)に関係なく、各navigationPaneコンポーネント内の一連のcommandNavigationItem子コンポーネントにより、実際のナビゲーション・アイテムが提供されます。たとえば、図18-11では、Employee Dataタブへの実際のリンク、InsuranceとPaid Time Offバー、およびリストのHealthとDentalリンクは、それぞれcommandNavigationItemコンポーネントによって表されています。

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

ナビゲーション階層に含まれるページ数が少なく、階層があまり深くない場合は、手動で作成することを選択できます。これには、ナビゲーション・メタデータの作成、navigationPaneコンポーネントを使用した階層の作成、およびcommandNavigationItemコンポーネントを使用したリンクの作成が含まれます。

手動でナビゲーション階層を作成する手順:

1. ページ階層のすべてのノード(ページ)のナビゲーション・ケースが含まれるグローバルなJSFナビゲーション・ルールを1つ作成します。

たとえば、図18-4に示されているページ階層には、グローバルのHelpノードを含む10のノードがあります。この場合、例18-16に示すように、faces-config.xmlファイルの1つのグローバル・ナビゲーション・ルール内に10のナビゲーション・ケースを作成します。

各ナビゲーション・ケースに、一意の結果文字列と、指定された文字列に一致する結果値がナビゲーション・システムによって返された場合に表示するJSFページへのパスを指定します。

例18-16 faces-config.xml内のページ階層のグローバル・ナビゲーション・ルール

<navigation-rule>
<navigation-case>
<from-outcome>goHome</from-outcome>
<to-view-id>/home.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHelp</from-outcome>
<to-view-id>/globalhelp.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goEmp</from-outcome>
<to-view-id>/empdata.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goBene</from-outcome>
<to-view-id>/benefits.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goIns</from-outcome>
<to-view-id>/insurance.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goPto</from-outcome>
<to-view-id>/pto.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goView</from-outcome>
<to-view-id>/viewdata.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goCreate</from-outcome>
<to-view-id>/createemp.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goHealth</from-outcome>
<to-view-id>/health.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>goDental</from-outcome>
<to-view-id>/dental.jspx</to-view-id>
</navigation-case>
</navigation-rule>

JDeveloperにおけるナビゲーション・ケースの作成方法の詳細は、2.3項「ページ・フローの定義」を参照してください。

2. メニュー・タブのスタイルを設定する場合は、コンポーネント・パレットのレイアウト・セクションから装飾ボックスをJSFページにドラッグ・アンド・ドロップして、decorativeBoxコンポーネントを作成します。テーマを設定して、タブの表示方法を決定します。有効な値は次のとおりです。

- default: 本体は白で、枠は青です。左上隅は丸くなります。

- light: 本体は薄い青です。左上隅は丸くなります。

- medium: 本体は中間色の青です。左上隅は丸くなります。

- dark: 本体は濃い青です。左上隅は丸くなります。

テーマの表示方法は変更できます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

3. コンポーネント・パレットのレイアウト・セクションからナビゲーション・ペインをdecorativeBoxコンポーネントの子としてドラッグ・アンド・ドロップして、navigationPaneコンポーネントを作成します。階層の各レベルにnavigationPaneコンポーネントを追加します。
たとえば、図18-11のようなHealthページを作成するには、4つのnavigationPaneコンポーネントをドラッグ・アンド・ドロップします。Healthページでは、すでにページのルック・アンド・フィールを作成するためのレイアウト・コンポーネントが含まれているテンプレートの特定の領域に、コンポーネントをドロップします。

4. プロパティ・インスペクタで「共通」セクションを開き、各navigationPaneコンポーネントのhint属性を次に示すナビゲーション・アイテムのいずれかのタイプに設定して、navigationPaneコンポーネントをどのように表示するかを決定します。

- bar: バーで分割されたナビゲーション・アイテムを表示します。図18-11のInsuranceおよびPaid Time Offリンクなどがこれに当たります。

- buttons: グローバル領域のバーで分割されたナビゲーション・アイテムを表示します。図18-11のHomeおよび「ヘルプ」リンクなどがこれに当たります。

- choice: 関連付けられたドロップダウン・アイコンがクリックされたときに、ポップアップ・リストにナビゲーション・アイテムを表示します。navigationPaneコンポーネントのicon属性に値を含める必要があります。これにより、title属性を使用して、ラベルをドロップダウン・リストを関連付けることができます。

- list: ナビゲーション・アイテムを箇条書きリストで表示します。図18-11のHealthおよびDentalリンクなどがこれに当たります。

- tabs: ナビゲーション・アイテムをタブで表示します。図18-11のBenefitsおよびEmployee Dataタブなどがこれに当たります。

5. コンポーネント・パレットの「共通コンポーネント」セクションから「ナビゲーション・アイテム」をドラッグ・アンド・ドロップし、異なるリンクを表示するために必要なcommandNavigationItemコンポーネントを、各navigtaionPaneコンポーネントに追加します。必要な各リンクのnavigationPaneコンポーネントの子として、「ナビゲーション・アイテム」をドロップします。
たとえば、図18-11のようなHealthページを作成するには、各navigationPaneコンポーネントに2つずつ、合計6つのcommandNavigationItemコンポーネントを使用します。

パフォーマンスのヒント:

実行時、使用可能なブラウザの領域が、ナビゲーション・ペインのタブやバーのコンテンツ、またはブレッドクラムのコンテンツの表示に必要な領域より少ない場合、表示されていない項目をユーザーが選択して表示できるオーバーフロー・アイコンがADF Facesにより自動的に表示されます。navigationPaneまたはbreadCrumbsコンポーネント内の子コンポーネントの数、および子の複雑さが、オーバーフローの項目のパフォーマンスに影響します。可能な場合は、オーバーフローしないように、navigationPaneまたはbreadCrumbsコンポーネントのサイズを設定する必要があります。

6. 各commandNavigationItemコンポーネントで、ナビゲーションを必要なページに設定します。プロパティ・インスペクタで、「共通」セクションを開き、アクションの静的な結果文字列を指定するか、EL式を使用し、actionプロパティを介してアクション・メソッドを参照します。文字列を使用する場合は、手順1で作成したページのナビゲーション・ルールに設定されたナビゲーション・メタデータに一致する必要があります。メソッドを参照する場合は、必要な文字列がそのメソッドにより返される必要があります。

7. プロパティ・インスペクタで、「動作」セクションを開いてselected属性を設定します。ページが最初にレンダリングされれたときに、commandNavigationItemコンポーネントを選択済として表示するには、この属性をtrueにします。表示しない場合は、falseにします。
実行時に、ユーザーがナビゲーション・アイテムを選択すると、コンポーネントのselected属性が選択済に変更され、ユーザーに、アイテムが選択済であることを示すために、表示が変更されます。たとえば、図18-11で、Benefitsタブ、Insuranceバー、Healthリスト・アイテムが、背景の色またはフォント・スタイルのいずれかの変更によって、選択済として表示されます。選択済ステータスを示すコードを記述する必要はありません。この属性値がtrueになると、このアイテムに対する、commandNavigationItemコンポーネントのselected属性によって、選択済ステータスが有効になります。

図18-17に、現在のページがHealthの場合に使用可能なナビゲーション・アイテムの生成に使用されるコードを示します。HealthページはBenefitsページを経由してInsuranceページからアクセスされているため、これらの3つのリンクのcommandNavigationItemコンポーネントではselected="true"です。

例18-17 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>

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

図18-10および図18-11の両方で、ページ階層におけるユーザーの現在の位置は、現在のページからルート・ページに戻るリンクのパスで示されています。ブレッドクラムとも呼ばれるリンクのパスは、2番目のバーの下、垂直のリスト(存在する場合)の上に表示されます。そのようなリンクのパスを作成するには、一連のcommandNavigationItemコンポーネントを子として含むbreadCrumbsコンポーネントを使用します。

ブレッドクラムを作成する手順:

1. コンポーネント・パレットからJSFページにブレッド・クラム・コンポーネントをドラッグ・アンド・ドロップして、breadCrumbsコンポーネントを作成します。

2. デフォルトでは、ブレッドクラム・リンクは水平に表示されます。レイアウトが垂直になるように変更するには、プロパティ・インスペクタで、「共通」セクションを開き、orientation属性をverticalに設定します。

3. ブレッドクラムの各リンクに、コンポーネント・パレットからbreadCrumbsコンポーネントの子として「ナビゲーション・アイテム」をドラッグ・アンド・ドロップし、commandNavigationItemコンポーネントを作成します。最後の項目が現在のページを表します。

ヒント:

レンダラまたはクライアントのデバイス・タイプによっては、ブレッドクラムの最後のリンクが表示されない場合がありますが、commandNavigationItemコンポーネントを追加する必要があります。最後のブレッドクラム・リンクを表示するクライアントでは、現在のページに対応しているため、リンクは常に自動的に無効にされます。

4. 各commandNavigationItemコンポーネント(最後を除く)で、ナビゲーションを必要なページに設定します。プロパティ・インスペクタで、「共通」セクションを開き、アクションの静的な結果文字列を指定するか、EL式を使用し、actionプロパティを介してアクション・メソッドを参照します。文字列を使用する場合は、手順1で作成したページのナビゲーション・ルールに設定されたナビゲーション・メタデータに一致する必要があります。メソッドを参照する場合は、必要な文字列がそのメソッドにより返される必要があります。

たとえば、図18-11のHealthページのようにブレッドクラムを作成するには、例18-18に示すように、4つのnavigationPaneコンポーネントをドラッグ・アンド・ドロップします。

例18-18 個々の子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>

注意:

同様に、個々のcommandNavigationItemコンポーネントを使用するかわりに、breadCrumbsコンポーネントのvalue属性をXMLMenuModel実装にバインドし、breadCrumbsコンポーネントのnodeStampファセットにcommandNavigationItemコンポーネントの1つ使用して、ページの項目にスタンプを設定することもできます。XMLMenuModelクラスの詳細は、18.6項「メニュー・モデルを使用したページ階層の作成」を参照してください。

18.7.3 ナビゲーション・タブの削除について

個々のタブを閉じられるように、hint属性の値がtabsであるnavigationPaneコンポーネントを構成できます。このコンポーネントは、すべてのタブを閉じる、最後のタブを除いてすべて閉じる、またはタブを閉じないように設定できます。ナビゲーション・タブが削除されるように構成された場合、マウス・カーソルがタブの上に置かれると、「閉じる」アイコン(たとえば、Xなど)が各タブの端に表示されます。

hint="tabs"を設定した場合にnavigationPaneコンポーネントでタブの削除を有効にするには、次の手順を実行する必要があります。

- navigationPane hint="tabs"のitemRemoval属性をallまたはallExceptLastに設定します。allExceptLastに設定すると、1つのタブ以外すべてのタブを閉じることができます。これは、ユーザーがタブを閉じると、タブが1つしか残っていない場合は、その最後のタブは閉じることができません。

- タブの削除を実行するハンドラを実装します。ユーザーがタブを閉じると、タイプremoveのItemEventが起動されます。コードでは、このイベント、タブの削除および他の必要な機能(たとえば、警告ダイアログの表示や子コンポーネントの処理など)を処理する必要があります。イベントの詳細は、第5章「イベントの処理」を参照してください。ポップアップ・ダイアログおよびウィンドウの使用の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

- commandNavigationItemコンポーネントのitemListener属性をEL式に設定します。この式は、例18-19に示すように、実際のタブの削除を処理するハンドラ・メソッドに解決されます。

例18-19 タブ・アイテムを削除するために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 ...
}
}
}

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

注意:

アプリケーションにFusionテクノロジ・スタックまたはADFコントローラが使用されている場合は、ADFタスク・フローを使用して、アプリケーションのページ階層にナビゲーション・システムを作成します。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「トレインの作成」を参照してください。

ユーザーが特定の順序で表示する必要のある一連のページがある場合は、各ページにtrainコンポーネントを使用して、マルチステップ・プロセスをガイドする一連のナビゲーション・アイテムを表示することを検討してください。図18-12に、レンダリングされたtrainコンポーネントがページでどのように表示されるかの例を示します。trainはマルチステップ・プロセスのステップ数を表示するだけでなく、プロセス全体との関連における現在のステップの位置も示します。

図18-12 trainコンポーネントによりレンダリングされたナビゲーション・アイテム

trainコンポーネントにより、トレイン・ストップとして表示される構成済の各ステップがレンダリングされます。すべてのストップは線で結ばれています。各トレイン・ストップには下にラベルのあるイメージ(四角いブロックなど)があります。

各トレイン・ストップは、マルチステップ・プロセスの1つのステップまたは1つのページに対応します。ユーザーは、イメージやラベルをクリックして、トレイン・ストップをナビゲートします。これによって、新しいページが表示されます。通常、トレイン・ストップは順に表示する必要があります。すなわち、ユーザーは、ステップ1から開始して、ステップ2、ステップ3へと移動する必要があり、ステップ2に移動していない場合は、ステップ3に移動できません。

図18-12に示すように、trainコンポーネントは、トレイン・ストップに少なくとも4つのスタイルを提供します。ユーザーが表示している現在のストップは、トレイン・ストップのラベルでは太字のフォント・スタイルで示され、そのストップに異なるイメージが使用されます。現在のストップの前に表示したストップは、異なるラベルのフォント色とイメージ色で示されます。現在のストップのすぐ後に表示される次のストップは表示が有効になり、まだ表示されていない他のストップはグレー表示になっています。

トレイン・ストップはサブトレインを含むことができます。すなわち、コマンド・コンポーネント(たとえば、commandButtonコンポーネントなど)を構成して、親ストップから子のマルチステップ・プロセスを開始し、サブプロセスの終了後、適切な親ストップに戻ります。3番目のストップに2つのストップを含むサブプロセス・トレインがあるとします。ユーザーがサブプロセス・トレインの1番目のストップにナビゲートすると、図18-13に示すように、ADF Facesにより、サブプロセス・トレインの前後に親トレインを表すアイコンが表示されます。

図18-13 サブトレインの最初と最後の親トレインのアイコン

trainコンポーネントにtrainButtonBarコンポーネントを使用して、図18-14に示すように、「戻る」および「次へ」ボタンという形で、trainに追加のナビゲーション・アイテムを指定できます。これらの「戻る」および「次へ」ボタンを使用した場合、ユーザーは現在のストップから前後のトレイン・ストップにのみナビゲートできます。trainButtonBarコンポーネントは、trainコンポーネントなしでも使用できます。たとえば、表示されないストップがある場合、いくつかの条件付きロジックに基づいて、ストップを表示せずに「戻る」および「次へ」ボタンのみを表示することが必要な場合があります。

図18-14 trainButtonBarコンポーネントによりレンダリングされたナビゲーション・ボタン

どちらのtrainコンポーネントも、value属性をタイプorg.apache.myfaces.trinidad.model.MenuModelのトレイン・モデルにバインドすることで機能します。トレイン・メニュー・モデルには、次の処理に必要な情報が含まれています。

- 特定のトレイン動作の制御(トレインによりユーザーがどのようにトレイン・ストップを前進してマルチステップ・プロセスを完了するか)

- トレイン・ストップ・ラベルを含むトレイン・ストップおよび各ストップのステータスの動的な生成(現在ストップは選択、完了、未完了または無効のいずれの状態であるか)

注意:

ADFモデル・レイヤーおよびADFコントローラを使用しているアプリケーションでは、このナビゲーションおよび表示は異なる方法で設定および処理されています。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「トレインの作成」を参照してください。

つまり、トレインのメニュー・モデルは、続いてTreeModelクラスを拡張するMenuModel抽象クラスを拡張することで実装されます(詳細は、第10章「表およびツリーの使用」を参照してください)。MenuModelオブジェクトは、ページやアプリケーションのメニュー構造を表すことも、ページの階層やフローに含まれるストップを表すこともあります。

MenuModelクラスのインスタンスは特別な種類のTreeModelオブジェクトなので、TreeModelオブジェクトのノードはトレインのストップを表すことができます。trainコンポーネント内でトレイン・ストップを表すノード・インスタンスはTrainStopModelタイプにすることができます。また、TrainStopModelオブジェクトと同じEL構造を提供するかぎり、任意のオブジェクトにすることもできます。ただし、TrainStopModelクラスでは、ストップのラベルやimmediate、disabledおよびvisited属性の状態だけでなく、結果を取得するメソッドも公開されます。

MenuModelクラスは、ツリーのどの部分で現在のトレイン・ストップ(ページ)がフォーカスされているかを示すこともできます。MenuModelクラスのgetFocusRowKey()メソッドは、現在のviewIdのフォーカス・ページのrowKeyオブジェクトを返します。トレインのメニュー・モデル実装には、org.apache.myfaces.trinidad.model.ProcessMenuModelクラスを拡張することで作成できる固有のトレイン動作も必要です。トレイン動作は、現在のトレイン・ストップを表示している間に、ユーザーがトレインのどのストップを表示できるかを制御します。

トレイン・ストップ・モデルを作成するには、TrainStopModel抽象クラスを拡張して抽象メソッドを実装するか、同じメソッド・シグネチャを使用して独自のクラスを作成することができます。作成するクラスではrowDataオブジェクトを返す必要があります。

トレイン・メニュー・モデルへのtrainコンポーネントのバインドは、XMLMenuModelクラスへのnavigationPaneコンポーネントのバインドに似ています(詳細は、18.6.3項「JSFページでのXMLMenuModelへのバインド方法」で説明されています)。ただし、TrainStopModelの実装でrowDataオブジェクトが戻される場合は、各ストップにcommandNavigationItemコンポーネントを提供する必要はありません。ADF Facesにより、実行時にnodeStampファセットおよびcommandNavigationItemコンポーネントが動的に作成され、トレイン・ストップ・モデルのメソッドがcommandNavigationItemコンポーネントの適切なプロパティに自動的にバインドされます。例18-20に、トレインの簡略化されたバインディングを示します。

ヒント:

様々な場所のトレイン・ストップの情報を照合する必要がある場合は、nodeStampファセットおよびそれらのトレイン・ストップを表す個々のcommandNavigationItemコンポーネントを手動で作成する必要があります。詳細は、18.8.3項「JSFページでのトレイン・モデルへのバインド方法」を参照してください。

例18-20 簡略化されたトレイン・モデル・バインディング

<af:train value="#{simpleTrainModel}"/>

トレイン・モデルのMenuModel実装には、特定のトレイン動作が必要です。トレイン動作は、現在表示されているページに基づいてユーザーがアクセスできるページをどのように制御するかを定義します。ADF Facesでは、Plus OneおよびMax Visitedという2つのトレイン動作がサポートされています。

トレインに5つのページまたは5つのストップがあり、ユーザーはページ1からページ4まで順番にナビゲート済であるとします。ページ4でユーザーはページ2に戻ります。ここでは、トレイン・モデルで使用されているトレイン動作に応じて、ユーザーは次に進むことができます。

Max Visitedでは、ユーザーは現在のページ2からページ1に戻ることも、ページ3に進むことも、ページ4に移動することもできます。つまり、Max Visitedを使用すると、ユーザーは前のページに戻ることも、すでに表示した最も先のページまで進むこともできます。ページ5はまだ表示されていないため、ユーザーはページ2からページ5に移動することはできません。

同じ状況で、Plus One動作の場合には、ユーザーはページ3に進むかページ1に戻ることしかできません。つまり、Plus Oneを使用すると、ユーザーは前のページに戻るか、現在のストップの1つ先のストップに進むことができます。ページ4がすでに表示されている場合でも、ユーザーはページ4に移動することはできません。

マルチステップ・プロセスのすべてのページにトレインを定義および使用する手順:

- トレインにJSFナビゲーション・ルールおよびナビゲーション・ケースを作成します。トレインのナビゲーション・ルールおよびナビゲーション・ケースの作成方法は、単純なページ階層の作成方法と同様です。ここで、トレインのすべてのトレイン・ストップに対してナビゲーション・ケースを含むグローバル・ナビゲーション・ルールを1つ作成します。

注意:

各トレイン・ストップが個々のページであり、クライアントのブラウザのURLがそれぞれの新しいページを参照する場合、JSFナビゲーション・ルール内で定義する各ナビゲーション・ケースに対して、redirect要素の値をtrueに設定することがあります。部分ページ・レンダリングを有効にする場合、表示されたURLは異なることがあります。redirect要素の詳細は、JavaServer Facesの仕様を参照してください。部分ページ・レンダリングの詳細は、第7章「部分ページ・コンテンツの再レンダリング」を参照してください。

- 特定のトレイン動作を実装するトレイン・モデルを作成し、スタンプを設定するためのトレイン・ストップ項目を指定します。これには、トレイン・ストップ・モデル・クラスおよびメニュー・モデル・クラスの作成が含まれます。詳細は、18.8.1項「トレイン・モデルの作成方法」を参照してください。

- トレイン・モデルにマネージドBeanを構成します。詳細は、18.8.2項「トレイン・モデルへのマネージドBeanの構成方法」を参照してください。

- 各トレイン・ストップにJSFページを作成します。

- 各ページで、トレイン・モデルにtrainコンポーネントをバインドします。18.8.3項「JSFページでのトレイン・モデルへのバインド方法」を参照してください。レインに追加のナビゲーション・ボタンを指定する場合は、オプションで、同じトレイン・モデルにtrainButtonBarコンポーネントをバインドします。

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

トレイン・メニュー・モデルを定義するには、次のものを作成します。

- トレイン・ストップをレンダリングするためのデータを提供するトレイン・ストップ・モデル

- 特に、現在のトレイン・ストップを表示している間にユーザーがトレインのどのストップを表示できるか、どのストップを無効にする必要があるか、またはトレインを順番にナビゲートする必要があるかを制御する特定のトレイン動作(Max VisitedまたはPlus One)が指定されたMenuModel実装

ADF Facesを使用すると、次のような追加のpublicクラスが用意されているため、トレイン・メニュー・モデルの定義がより簡単になります。

- トレイン・ストップ・モデルを実装するための抽象クラスTrainStopModel

- トレイン・モデルのトレイン動作を実装するためのクラスProcessMenuModelおよびProcessUtils

トレイン・モデル・クラスの例として、ADF Facesデモ・アプリケーションのoracle.adfdemo.view.nav.richパッケージを参照してください。

トレイン・モデルを作成する手順:

1. トレイン・ストップ・モデル・クラスを作成します。トレイン・ストップ・モデル・オブジェクトには、各トレイン・ストップにスタンプを設定するための行データが保持されます。作成するトレイン・ストップ・モデル実装では、トレインの各ストップのプロパティを設定および取得し、トレイン・ストップのレンダリングに必要なメソッドを定義する必要があります。トレイン・ストップのプロパティは、commandNavigationItemコンポーネントのプロパティに対応します。このため、例18-20に示すように、簡略化されたバインディングを使用できます。
または、抽象クラスTrainStopModelを拡張して、サブクラスの抽象メソッドを実装できます。

ELにより自動的にバインドされるcommandNavigationItemコンポーネントのプロパティを次に示します。

- action: 静的なアクション結果、またはアクション結果を返すアクション・メソッドへの参照。結果は、JSFのデフォルトのActionListenerメカニズムを介して、ページ・ナビゲーションに使用されます。

- disabled: トレイン・ストップが非対話型である必要があるかどうかを示すブール値。使用するトレイン動作が、このプロパティ値に影響することに注意してください。詳細は、手順2を参照してください。

- immediate: データ検証を実行する必要があるかどうかを決定するブール値。使用するトレイン動作が、このプロパティ値に影響することに注意してください。詳細は、手順2を参照してください。

- messageType: トレイン・ストップ・イメージ上のメッセージ・アラート・アイコンを指定する値。使用可能な値は、none、error、warning、infoおよびcompleteです。メッセージの詳細は、第17章「ヒント、メッセージおよびヘルプの表示」を参照してください。

- 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ストップは、現在のセッションでユーザーが表示した最も先のストップです。max visitedストップの前にあるか、max visitedストップ自体である場合、visitedはすべてのストップに対してtrueに設定されます。

- Plus One: plus oneストップは、表示した最も先のストップを追跡しません。現在のストップ、または現在のストップの前のストップでは、visited属性がtrueに設定されます。

現在のページのデータを検証する必要がない場合は、immediate属性をtrueに設定する必要があります。前述のPlus One動作のページ4に、検証が必要なデータがあるとします。ページ4に進んでページ2に戻った場合、ページ5に進むためにユーザーは後からページ4に戻る必要があります。これは、ページ4からページ1、2または3に戻る場合はページ4のデータを検証する必要はないが、ページ5に進む場合にはデータを検証する必要があることを意味します。immediate属性がどのように機能するかの詳細は、4.2項「immediate属性の使用」を参照してください。

ProcessMenuModelクラスでは、immediate属性の値の決定に次のロジックが使用されます。

- Plus One: immediate属性は、前のステップに対してはtrueに設定され、それ以外に対してはfalseに設定されます。

- Max Visited: 現在のページと、表示した最大ページが同じである場合、動作はPlus Oneシナリオと同じです。現在のページが表示された最大ページよりも前にある場合、immediate属性はfalseに設定されます。

注意:

ADFモデル・レイヤーを使用するアプリケーションでは、ページ定義ファイルのpageDefinition要素は、ページのデータ検証をスキップする属性(SkipValidation)をサポートします(trueに設定されている場合)。ユーザーがデータ検証を起動しないでページからナビゲートする場合、SkipValidationをtrueに設定します。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のpageNamePageDef.xmlに関する項を参照してください。

disabled属性をtrueに設定するのは、現在のページからそのページに移動できない場合のみです。ProcessMenuModelクラスでは、disabled属性の値の決定に次のロジックが使用されます。

- Plus One: 次に使用可能なページより先のページでは、disabled属性がtrueになります。

- Max Visited: 現在のストップと、表示した最大ページが同じである場合、動作はPlus One動作と同じです。現在のページが表示された最大ページよりも前にある場合、表示された最大ページより先のページではdisabledがtrueに設定されます。

ADF Facesでは、トレイン・モデルにnull以外のmaxPathKey値が渡されると、動作をサポートするために作成するマネージドBeanで決定されているとおりに、デフォルトで、Max Visited動作が使用されます(詳細は、18.8.2項「トレイン・モデルへのマネージドBeanの構成方法」を参照してください)。maxPathKey値がnullの場合には、Plus One動作が使用されます。

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

トレイン・モデルのマネージドBeanを使用して、個々のトレイン・ストップをArraylistオブジェクトにまとめます。これは、トレイン・モデルを作成するためにメニュー・モデルに組み込まれるツリー・モデルになります。モデルに組み込むために適切な値を含むBeanをインスタンス化し、トレインの各トレイン・ストップまたはページにマネージドBeanを構成する必要があります。

トレイン・モデルにマネージドBeanを構成する手順:

1. インストール時に設定する必要のあるプロパティ値が含まれるマネージドBeanをトレインの各ストップに構成し、ArrayListに渡すトレイン・ストップを作成します。
トレイン・ストップに子のサブプロセス・トレインがある場合は、各サブプロセス・トレイン・ストップにもマネージドBeanが必要です。

各Beanは、18.8.1項「トレイン・モデルの作成方法」で作成したトレイン・ストップ・モデル・クラスのインスタンスである必要があります。例18-21に、faces-config.xmlファイルのトレイン・ストップのサンプルのマネージドBeanコードを示します。

例18-21 すべてのトレイン・ストップのマネージド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.jspx</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.jspx</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 -->
.
.
.

マネージド・プロパティにより、トレイン・ストップ・モデル・オブジェクト(18.8.1項「トレイン・モデルの作成方法」の手順1で作成されたクラス)に値が設定されます。

viewId値は、ユーザーがトレイン・ストップをクリックした場合にナビゲートされるページへのパスおよびファイル名です。

outcomeプロパティ値は、JSFナビゲーション・ケースに一致するアクション結果文字列です。デフォルトのJSF ActionListenerメカニズムは、トレイン・ストップが選択された際のナビゲート先のビューとしてトレイン・ストップに関連付けられたページの選択に使用されます。

labelプロパティ値は、トレイン・ストップ・イメージの下に表示されるトレイン・ストップのラベル・テキストです。値は静的にすることも、リソース・バンドルの文字列に評価されるEL式にすることもできます。

modelプロパティ値は、トレイン・モデルのマネージドBean名です(例18-25を参照)。

トレイン・ストップに子のサブプロセス・トレインがある場合には、例18-22に示すように、マネージドBean構成にも、値式(#{train4a}など)でサブプロセス・トレイン・ストップのマネージドBean名をリストするプロパティ(childrenなど)を指定する必要があります。

例18-22 子のサブプロセス・トレインを含むトレイン・ストップのマネージド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.jspx</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を構成し、トレイン・ツリー・モデルに渡すトレイン・ストップのリストを作成します。
例18-23に、トレイン・ストップのリストを作成するためのサンプルのマネージドBeanコードを示します。

例18-23 トレイン・リストのマネージド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値を使用して、インスタンス化する必要があります(例18-22を参照)。

例18-24 トレイン・ツリー・モデルのマネージド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値を使用して、インスタンス化する必要があります。

例18-25に、トレイン・モデルのサンプルのマネージドBeanコードを示します。

例18-25 トレイン・モデルのマネージド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動作が使用されます。

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

トレインの各ストップは、1つのJSFページに対応します。各ページに、trainコンポーネント、およびオプションでtrainButtonBarコンポーネントを1つずつ使用し、ユーザーがトレインを移動できるようにするボタンを作成します。

トレイン・コンポーネントをトレイン・モデルにバインドする手順:

1. コンポーネント・パレットからJSFページに「トレイン」をドラッグ・アンド・ドロップして、trainコンポーネントを作成します。オプションで、「トレイン・ボタン・バー」をドラッグ・アンド・ドロップします。

2. コンポーネントをバインドします。トレイン・モデルのMenuModel実装により、public抽象クラスoracle.adf.view.rich.model.TrainStopModelに似たrowDataオブジェクトが返される場合は、次のコードに示すように、trainコンポーネントにトレイン・バインディングの簡略化されたフォームを使用できます。

<af:train value="#{trainMenuModel}"/>
<af:trainButtonBar value="#{trainMenuModel}"/>

EL式のtrainMenuModelは、トレイン・モデルのマネージドBean名です(例18-25を参照)。

簡略化されたバインディングを使用できない場合は、トレイン値をトレイン・モデルBeanにバインドし、トレインにnodeStampファセットを手動で追加する必要があります。さらに、例18-26に示すように、そのトレインにcommandNavigationItemコンポーネントを追加します。

例18-26 trainコンポーネントをトレイン・モデルのBeanにバインドするメタデータ

<af:train value="#{aTrainMenuModel}" var="stop">
<f:facet name="nodeStamp">
<af:commandNavigationItem
text="#{stop.label}"
action="#{stop.outcome}"
...
</af:commandNavigationItem>
</f:facet>
</af:train>

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

この章では、再利用可能なコンテンツを作成し、それらを使用してJSFページの一部またはページ全体を作成する方法を説明します。

この章では、次の項目について説明します。

- 19.1項「再利用可能なコンテンツの概要」

- 19.2項「ページ・フラグメントの使用」

- 19.3項「ページ・テンプレートの使用」

- 19.4項「宣言コンポーネントの使用」

- 19.5項「ページへのリソースの追加」

19.1 再利用可能なコンテンツの概要

アプリケーションにJSFページを作成する場合、一部のページが複雑で長くなり、編集が込み入って煩雑になることがあります。非常に特有なレイアウトに配置されたコンポーネントのグループが常にページに含まれる場合や、ページの複数の部分で特定のコンポーネントのグループを使用する場合もあります。あるいは、ページの一部またはページ全体を、他の開発者と共有する必要がある場合もあります。どのような場合でも、UIに変更が発生すると、多くの場所とページに変更内容を反映する必要があります。それらすべてのページを作成して維持し、構造やレイアウトの一部またはすべてが一貫していることを確認するのは、非効率的な作業になっていく可能性があります。

個々のUIコンポーネントを使用してページを作成するかわりに、ページのビルディング・ブロックを使用してページの一部またはページ全体を作成できます。ビルティング・ブロックには、頻繁にまたは一般的に使用されるUIコンポーネントが含まれており、アプリケーションの1つ以上のページで使用するための再利用可能なコンテンツを作成できます。アプリケーションに応じて、1つ以上のページに、1つのタイプのみのビルディング・ブロックを使用することも、すべてのタイプを使用することもできます。また、複数のビルディング・ブロックをアプリケーション全体で共有できます。ビルディング・ブロックに変更を加えた場合は、再利用可能なコンテンツを使用しているJSFページも自動的に更新されます。このため、アプリケーションで再利用可能なコンテンツを作成および使用することで、構造とレイアウトが常に一貫したWebユーザー・インタフェースと、スケーラブルで拡張可能なアプリケーションを作成できます。

ADF Facesには、次のタイプの再利用可能なビルディング・ブロックがあります。

- ページ・フラグメント: ページ・フラグメントを使用すると、ページの一部を作成できます。JSFページは、1つ以上のページ・フラグメントで構成されます。たとえば、大規模なJSFページは、複数の小規模なページ・フラグメントに分割するとより簡単にメンテナンスできます。ページ・フラグメントの作成および使用方法の詳細は、ページ・フラグメントの使用に関する項を参照してください。

- ページ・テンプレート: ページ・テンプレートを作成すると、個々のコンポーネントおよびページ・フラグメントを使用して、ページ全体のレイアウトを作成できます。たとえば、複数のJSFページに特定の方法で複数のコンポーネントを繰り返しレイアウトする場合には、それらのページ用にページ・テンプレートを作成することを検討します。ページの作成にページ・テンプレートを使用すると、アプリケーション全体の構造およびレイアウトで常にページの一貫性を保つことができます。ページ・テンプレートの作成および使用方法の詳細は、ページ・テンプレートの使用およびページ・テンプレートに基づくJSFページの作成方法に関する項を参照してください。

- 宣言コンポーネント: 宣言コンポーネント機能を使用すると、個々の既存のUIコンポーネントを、1つ以上のページで宣言的に使用できる再利用可能な1つのコンポジット・コンポーネントにアセンブルできます。たとえば、複数の場所にコンポーネントのグループを挿入する場合、個々のコンポーネントを構成するコンポジット宣言コンポーネントを作成し、その宣言コンポーネントをアプリケーション全体の複数の場所に再利用することを検討します。宣言コンポーネントは、ページ・テンプレートでも使用できます。宣言コンポーネントの作成および使用方法の詳細は、宣言コンポーネントの使用に関する項を参照してください。

ヒント:

アプリケーションにADFコントローラやADFモデル・レイヤーが使用されている場合は、ADFリージョンも使用できます。ADFバインド・タスク・フローとともに使用されるリージョンは、ビジネス・ロジック、プロセス・フローおよびUIコンポーネントのすべてを、アプリケーション全体で再利用可能な1つのパッケージにカプセル化します。ADFバインド・タスク・フローをリージョンとして作成および使用する方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「タスク・フローのリージョンとしての使用」を参照してください。

ページ・テンプレート、宣言コンポーネントおよびリージョンにより、javax.faces.component.NamingContainerインタフェースが実装されます。実行時に、再利用可能なコンテンツを使用するページで、ページ・テンプレート、宣言コンポーネントまたはリージョンによりコンポーネントのサブツリーが作成され、使用ページの単一のJSFコンポーネント・ツリーに挿入されます。使用ページには独自のネーミング・コンテナがあるため、ページに再利用可能なコンテンツを追加する場合、partialTargetsやfindComponent()などのメカニズムを使用する際には、ページに表示される様々なコンポーネントの異なるネーミング・コンテナを考慮する必要があるため、十分に注意してください。ネーミング・コンテナの詳細は、3.5項「ページでのクライアント・コンポーネントの検索」を参照してください。

CSSまたはJavaScriptなどのリソースを含める場合、af:resourceタグを使用して、リソースをページに追加できます。このタグがページ・テンプレートおよび宣言コンポーネントで使用される場合、指定されたリソースがJSP実行時に使用ページに追加されます。詳細は、ページへのリソースの追加に関する項を参照してください。

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

アプリケーションのWebページを作成して短時間で、一部のページが大規模で管理不能になることがあります。複雑なページの作成およびメンテナンスのプロセスを簡略化する1つの方法は、ページ・フラグメントの使用です。

大規模で複雑なページを複数の小規模なページ・フラグメントに分割すると、メンテナンスしやすくなります。ページの設計方法によっては、あるページに作成されたページ・フラグメントを別のページで再利用できます。たとえば、複数ページの異なる部分に同じフォームを使用する場合、フォームにそれらのコンポーネントを含むページ・フラグメントを作成し、それらのページ・フラグメントをいくつかのページに再利用すると便利です。1つ以上の複雑なページにページ・フラグメントをいくつ作成するかの判断は、アプリケーション、ページの一部を複数のページで再利用する程度、および複雑なページを簡略化する要望によって異なります。

ページ・フラグメントは不完全なJSFページです。ADF Facesを使用する完全なJSFページでは、documentタグがf:viewタグで囲まれている必要があります。ページ全体のコンテンツは、documentタグで囲まれます。一方、ページ・フラグメントは完全なページの一部を表し、f:viewまたはdocumentタグを含みません。ページ・フラグメントのコンテンツは、jsp:rootタグで囲まれます。

ページ・フラグメントを使用してJSFページを作成する際には、ページの異なる部分を定義する1つ以上のページ・フラグメントを使用できます。同じページ・フラグメントを、1つのページで複数回使用することも、複数のページで使用することもできます。

注意:

ページのすべてのview部分(フラグメント、宣言コンポーネントおよびメイン・ページ)では、同じリクエスト・スコープが共有されます。このため、1つのページに同じフラグメントまたは宣言コンポーネントを複数回使用すると競合が発生し、そのフラグメントまたはコンポーネントでバッキングBeanが共有されます。スコープの詳細は、オブジェクト・スコープ・ライフサイクルに関する項を参照してください。

たとえば、File Explorerアプリケーションには、次のページ・フラグメントを含むメイン・ページ(index.jspx)が1つ使用されています。

- popups.jspx: アプリケーションで使用されるすべてのポップアップ・コードが含まれます。

- help.jspx: ヘルプ・コンテンツが含まれます。

- header.jspx: アプリケーションのツールバーおよびメニューが含まれます。

- navigators.jspx: アプリケーションのフォルダ階層を表示するツリーが含まれます。

- contentViews.jspx: ナビゲーション・ペインで選択されたフォルダのコンテンツが含まれます。

例19-1に、含まれるheader.jspxページ・フラグメントの省略形のコードを示します。f:viewまたはdocumentタグが含まれていないことに注意してください。

例19-1 header.jspxページ・フラグメント

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
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>
</jsp:root>

JSFページでページ・フラグメントを使用するには、index.jspxページの省略形のコードである例19-2に示すように、ページ・フラグメント・コンテンツを使用するページの部分に、jsp:includeタグを挿入し、必要なページ・フラグメント・ファイルを指定します。

例19-2 フラグメントを含むFile Explorerの索引JSFページ

<?xml version='1.0' encoding='utf-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
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>
</jsp:root>

ページ・フラグメントを変更すると、ページ・フラグメントを使用するページが自動的に変更内容で更新されます。ページ・フラグメントから作成されたページでは、レイアウトを変更すると、ページ・フラグメントを変更するだけでは不十分なことがあります。ページ・フラグメントを使用するすべてのページを変更する必要があります。

注意:

使用ページでADFモデル・データ・バインディングが使用されている場合、含まれるページ・フラグメントでは、使用するページのバインディング・コンテナが使用されます。ADFの無制限タスク・フローの一部として作成されたページ・フラグメントにのみ、独自のバインディング・コンテナを使用できます。ADFの無制限タスク・フローの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFタスク・フローの概説」を参照してください。

例19-3に示すように、完全なJSFページ同様、ページ・フラグメントもページ・テンプレートをベースにすることができます。ページ・テンプレートの作成および適用方法の詳細は、19.3項「ページ・テンプレートの使用」および19.3.3項「ページ・テンプレートに基づくJSFページの作成方法」を参照してください。

例19-3 テンプレートに基づくページ・フラグメント

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:f="http://java.sun.com/jsf/core">
<af:pageTemplate viewId="/someTemplateDefinition.jspx">
.
.
.
</af:pageTemplate>
</jsp:root>

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

ページ・フラグメントは、f:viewまたはdocumentタグをしない点以外は、JSFページと同様です。JSFページ・フラグメントの作成ウィザードを使用して、ページ・フラグメントを作成できます。ウィザードを使用してページ・フラグメントを作成すると、JDeveloperでは、ページ・フラグメント・ファイルに拡張子.jsffが使用されます。ウィザードを使用しない場合、.jspxをファイル拡張子として使用できます(File Explorerアプリケーションと同様)。JDeveloperのアプリケーション・ナビゲータでの作業時に完全なJSFページとページ・フラグメントをすばやく区別できる以外に、.jsffを使用する特別な理由はありません。

ページ・フラグメントを作成する手順:

1. アプリケーション・ナビゲータで、ページ・フラグメントを作成および格納するフォルダを右クリックし、「新規」を選択します。

2. 「カテゴリ」ツリーで「JSF」ノードを選択し、「項目」ペインで「JSFページ・フラグメント」を選択して「OK」をクリックします。

3. ページ・フラグメント・ファイルの名前を入力します。

4. ページ・フラグメント用のデフォルトのディレクトリをそのまま使用するか、新しい場所を選択します。
JDeveloperでは、デフォルトで、ファイルシステム内のプロジェクトの/public_htmlディレクトリにページ・フラグメントが保存されます。たとえば、デフォルトのディレクトリを/public_html/fragmentsに変更できます。

5. テンプレートまたはクイック・スタート・レイアウトを使用して、フラグメントを事前に設計できます。

- ページ・テンプレートに基づいたページ・フラグメントを作成する場合、「ページ・テンプレート」ラジオ・ボタンを選択し、ドロップダウン・リストからテンプレート名を選択します。ページ・テンプレートの使用方法の詳細は、ページ・テンプレートに基づくJSFページの作成方法に関する項を参照してください。

- クイック・スタート・レイアウトを使用する場合は、「クイック・スタート・レイアウト」ラジオ・ボタンを選択し、「参照」をクリックして、フラグメントで使用するレイアウトを選択します。クイック・スタート・レイアウトには、特定の動作および外観を得るために必要な正確に構成されたレイアウト・コンポーネントが用意されています。詳細は、8.2.3項「クイック・スタート・レイアウトの使用」を参照してください。

ページ・フラグメントの作成が完了すると、JDeveloperにより、ビジュアル・エディタにページ・フラグメント・ファイルが表示されます。

6. ページ・フラグメントのコンテンツを定義するには、ページにコンポーネント・パレットから必要なコンポーネントをドラッグ・アンド・ドロップします。
table、panelHeaderまたはf:facetなど、任意のADF Facesコンポーネントまたは標準のJSFコンポーネントを使用できます。

例19-4に、menuコンポーネントを含むページ・フラグメントの例を示します。

例19-4 ページ・フラグメントのサンプル

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<!-- 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>
</jsp:root>

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

JDeveloperでは、ページ・フラグメント・ファイルが通常のJSFページと異なるファイル拡張子を使用するので、アプリケーションで.jsffファイルを認識および解釈するために、構成エントリがweb.xmlファイルに追加されます。例19-5に、.jsffファイルで必要なweb.xmlの構成エントリを示します。これは、ウィザードを使用して最初にページ・フラグメントを作成したときに、JDeveloperによって追加されます。

例19-5 .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ドキュメントとして解析される必要があります。

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

JSFページでページを使用するには、コンポーネント・パレットまたはアプリケーション・ナビゲータのいずれかを使用して、ページを追加します。

19.2.3.1 コンポーネント・パレットによるページ・フラグメントの追加

jsp:includeタグを使用して目的のページ・フラグメント・ファイルを含めることができます。

コンポーネント・パレットを使用してページ・フラグメントを追加する手順:

1. コンポーネント・パレットでドロップダウン・メニューを使用して「JSP」を選択します。

2. コンポーネント・パレットから「インクルード」をドラッグ・アンド・ドロップして、jsp:includeタグを追加します。

3. 「インクルードの挿入」ダイアログでドロップダウン・リストを使用して、含めるJSFページを選択します。オプションで、ページが含まれる前にバッファをフラッシュするかどうかを選択します。詳細は、ダイアログの「ヘルプ」をクリックしてください。

19.2.3.2 アプリケーション・ナビゲータによるページ・フラグメントの追加

ページ・フラグメントをページに直接ドラッグ・アンド・ドロップできます。

アプリケーション・ナビゲータを使用してページ・フラグメントを追加する手順:

1. アプリケーション・ナビゲータで、ページ・フラグメントをページにドラッグ・アンド・ドロップします。

2. 「Subview要素追加の確認」ダイアログで、「はい」をクリックします。

19.2.4 実行時の処理: ページ・フラグメントの解決

組込みページを含むページが実行されると、JSFツリー・コンポーネントの作成時に、jsp:includeタグによりビューIDが検証され、親ページのjsp:includeタグの場所にコンテンツが動的に追加されます。コンポーネント・ツリーが作成されると、フラグメントは親ページの一部になります。

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

ページ・テンプレートでは、ページの特定の属性値など、ページ・レイアウト全体を定義できます。テンプレートを使用してページを作成すると、すべてのページで定義済のレイアウトが継承されます。テンプレートのレイアウトを変更すると、そのテンプレートを使用するすべてのページにレイアウトの変更が自動的に反映されます。テンプレートのレイアウトは、自分で作成することも、多数あるクイック・レイアウト設計の1つを使用して作成することもできます。これらの事前定義済レイアウトを使用すると、必要なレイアウトの外観および動作を実装するために必要となる適切なコンポーネントが自動的に挿入されて構成されます。たとえば、1つの列の幅はロックし、他の列は拡大してブラウザの使用可能な領域を埋めることができます。図19-1に、2番目の列が2つのペインに分割されている2列レイアウトで使用可能なクイック・レイアウトを示します。レイアウト・コンポーネントの詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。

図19-1 クイック・レイアウト

アプリケーションにページ・テンプレートを使用するには、まず、ページ・テンプレート定義を作成します。ページ・テンプレートにはXMLコンテンツが埋め込まれているため、ページ・テンプレート定義は、XML構文で記述されたJSFドキュメント(ファイル拡張子は.jspx)である必要があります。ページのすべてのコンポーネントをf:viewタグで囲む必要のある通常のJSFページとは対照的に、ページ・テンプレート定義にはf:viewタグを含めることができず、ルート・タグとしてpageTemplateDefが必要です。テンプレートを使用するテンプレートまたはページのどちらにもdocumentタグが含まれている必要がありますが、どちらもそのタグを含めることができません(JDeveloperにより、デフォルトで使用ページにdocumentタグが追加されます)。

ページ・テンプレートには、固定コンテンツ領域および動的コンテンツ領域を作成できます。たとえば、「Help」ボタンを必ずページ上部の右端に配置する場合、そのボタンをテンプレート・レイアウトに定義すれば、ページ作成者がそのテンプレートを使用してページを作成する際に、「Help」ボタンを追加および構成する必要はありません。一方、動的コンテンツ領域は、ページ作成者がテンプレートの定義済のファセット内にコンテンツを追加することや、作成中のページのタイプに固有のプロパティ値を設定することが可能なテンプレートの領域です。

ページ・テンプレートの完全な説明は、2つのセクションがあるpageTemplateDefタグ内に定義されています。セクションのうちの1つはxmlContentタグにあり、これには、テンプレートのサポートされているコンテンツ領域(ファセットで定義済)および使用可能なプロパティ(属性として定義済)を記述する、すべてのページ・テンプレート・コンポーネント・メタデータが含まれています。2つ目のセクション(xmlContentタグの外)は、テンプレートの実際のページ・レイアウトを構成するすべてのコンポーネントが定義される場所です。レイアウト・セクションのコンポーネントは、ページ・テンプレートのコンテンツをレンダリングするために使用するJSFコンポーネントのサブツリーを提供します。

ファセットは、ページ上のコンテンツのプレースホルダとして機能します。テンプレートを使用するページでは、ページ作成者がテンプレートにコンテンツを挿入できるのは、すでに定義済の名前付きファセットに対してのみです。これは、ページ・テンプレートを設計する際には、各名前付きファセットのfacet要素を使用して、xmlContentタグ内に使用可能なすべてのファセットを定義する必要があることを意味します。ページ・テンプレート定義のレイアウト・セクションで、様々なコンポーネントを使用してテンプレート・レイアウトを作成する場合には、facetRefタグを使用して、ページ作成者がテンプレートにコンテンツを挿入できるそれらのコンポーネント内の名前付きファセットを参照します。

たとえば、fileExplorerTemplateテンプレートには、例19-6に示すように、コピーライト情報用のファセット、およびアプリケーション情報用の別のファセットが含まれます。

例19-6 テンプレートのファセット定義

<facet>  <description>
<![CDATA[Area to put a commandLink 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>

例19-7に示されているテンプレートのレイアウト・セクションでは、セルにappCopyrightファセットへの参照が含まれる表と、appAboutファセットへの参照が含まれる別のファセットがpanelGroupLayoutコンポーネントに含まれています。これは、ページ開発者がコンテンツの配置を許可される場所です。

例19-7 ページ・テンプレート内のファセット参照

<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>

注意:

実行時にコンポーネントIDの競合を回避するには、ページ・テンプレート定義のレイアウト・セクションにおける各名前付きファセットの参照を一度のみにします。つまり、同じテンプレート定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

pageTemplateDefタグは、ページ・テンプレート定義に必要なすべての情報およびコンポーネントを記述しますが、ページ・テンプレートを使用するJSFページでは、pageTemplateタグを使用して、ページ・テンプレート定義を参照します。例19-7に、index.jspxページがfileExplorerTemplateテンプレートを参照し、テンプレートの属性に値を指定して、テンプレートのファセット定義内にコンテンツを配置する方法を示します。

設計時、テンプレートを使用するページ開発者は、例19-8に示すように、f:facetタグを使用してappCopyrightファセットにコンテンツを挿入できます。

例19-8 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要素の情報は、テンプレートへの受渡しに使用可能なページ属性、およびテンプレート・プロパティを設定または変更するために、それらの属性を使用できるテンプレートの場所の指定に使用されます。

ページ・テンプレートでそのテンプレート自体の属性を参照する場合には、pageTemplateDefタグに、テンプレートに定義された各属性を参照するためのEL変数名が含まれるvar属性が必要です。たとえば、fileExplorerTemplateテンプレートでは、pageTemplateDefタグのvarの値はattrsに設定されています。テンプレートのレイアウト・セクションで、ページ作成者が独自の値の指定や、デフォルト値の変更を実行できるそれらのコンポーネント属性に、#{attrs.someAttributeName}などのEL式を使用します。

たとえば、fileExplorerTemplateテンプレート定義ではヘッダー・サイズの属性が定義されますが、例19-9に示すように、デフォルトのint値である100ピクセルが設定されています。

例19-9 ページ・テンプレートの属性の定義

<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式が示すように、指定された属性値はテンプレートの適切な部分に置き換えられます。

ヒント:

ページ・テンプレートのリソース・バンドルを定義すると、テンプレートを使用するページでもリソース・バンドルを使用できるようになります。リソース・バンドルの使用の詳細は、リソース・バンドルおよびロケールの手動での定義に関する項を参照してください。

単純なページ・テンプレートの場合、レイアウト・セクション全体のすべてのコンポーネントをページ・テンプレート定義ファイルに配置するだけでかまいません。より複雑なページ・テンプレートの場合は、メンテナンスしやすいようレイアウト・セクションを複数の小規模なフラグメント・ファイルに分割し、jsp:includeタグを使用して、様々なフラグメント・ファイルを組み入れて連携させます。

ページ・テンプレートのレイアウト・セクションを複数の小さなフラグメント・ファイルに分割する場合、すべてのページ・テンプレート・コンポーネント・メタデータをメインのページ・テンプレート定義ファイルのxmlContentタグに含める必要があります。pageTemplateDefタグ内にxmlContentタグは1つのみ存在できます。フラグメント・ファイルにページ・テンプレート・コンポーネント・メタデータを含めることはできません。フラグメント・ファイルには、ページ・テンプレート・レイアウト・コンポーネントの一部のみを含めることができます。

注意:

ページ・テンプレートを、その他のページ・テンプレートにネストさせることはできません。

テンプレートに、CSSに定義されているカスタム・スタイルまたはJavaScriptなどのリソースが必要な場合は、af:resourceタグを使用して、使用ページにそれらのリソースを含める必要があります。詳細は、ページへのリソースの追加に関する項を参照してください。

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

JDeveloperでページ・テンプレート定義の作成を簡略化するには、JSFページ・テンプレートの作成ウィザードを使用します。これによって、名前付きファセットおよび属性を宣言的に追加して、テンプレート・コンポーネント・メタデータ・セクションを作成できます。メタデータ・コードの作成だけでなく、JDeveloperでは、プロジェクトで作成するすべてのページ・テンプレートを追跡するpagetemplate-metadata.xmlファイルの作成および変更も行われます。

パフォーマンスのヒント:

ページ・テンプレートはすべてのアプリケーション・ページで使用される可能性があるため、共通のオーバーヘッドを回避できるよう最適化する必要があります。オーバーヘッドの一例は、ボックスなどの丸い角で、オーバーヘッドはかなり大きいです。これをテンプレートに追加することは、各ページにオーバーヘッドを追加することになります。

ページ・テンプレート定義を作成する手順:

1. アプリケーション・ナビゲータで、ページ・テンプレートを作成および格納するフォルダを右クリックし、「新規」を選択します。

2. 「カテゴリ」ツリーで「JSF」ノードを選択し、「項目」ペインで「JSFページ・テンプレート」を選択して「OK」をクリックします。

3. ページ・テンプレート定義の名前を入力します。ページ・テンプレート定義にはXMLコンテンツが埋め込まれているため、ページ・テンプレート定義は、XMLドキュメント(ファイル拡張子は.jspx)である必要があります。

パフォーマンスのヒント:

サーバー側、ネットワーク・トラフィックおよびクライアント処理に影響があるため、長い名前にしないでください。

4. テンプレート定義用のディレクトリ名をそのまま使用するか、新しい場所を選択します。

5. ページ・テンプレート定義のページ・テンプレート名を入力します。

6. 事前定義済のクイック・レイアウトのいずれかを使用する場合は、「クイック・スタート・レイアウトの使用」を選択し、「参照」をクリックして、使用するレイアウトを選択します。

7. 名前付きファセットを追加するには、「ファセット定義」タブをクリックし、「追加」アイコンをクリックします。
ファセットは、ページ・テンプレートの事前定義済領域で、テンプレートを使用してページを作成する際にコンテンツを挿入できます。各ファセットには一意の名前が必要です。たとえば、ページのメインのコンテンツ領域にはmainというファセットを、ページのブランド領域にはbrandingというファセットを定義できます。

8. 属性を追加するには、「属性」タブをクリックし、「追加」アイコンをクリックします。
属性はUIコンポーネント属性で、テンプレートを使用してページを作成する際にページに渡すことができます。各属性には名前とクラス・タイプが必要です。属性(手順12で構成するコンポーネントの属性など)を使用するものは、そのタイプを使用できる必要があります。デフォルト値を割り当て、「必須」チェック・ボックスを選択することで、値が必須であることを指定できます。

9. ページ・テンプレート・コンテンツにADFモデル・データ・バインディングが使用されている場合は、「関連ADFmページ定義の作成」チェック・ボックスを選択し、「モデル・パラメータ」をクリックして1つ以上のモデル・パラメータを追加します。モデル・パラメータおよびADFモデル・データ・バインディングの使用方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ・テンプレートの使用」を参照してください。
ウィザードを完了すると、JDeveloperにより、ビジュアル・エディタにページ・テンプレート定義ファイルが表示されます。例19-10に、ウィザードを使用してページ・テンプレート定義のメタデータを定義する際に、JDeveloperにより追加されるコードを示します。このコードは、ソース・エディタで表示できます。

ヒント:

テンプレートを作成したら、構造ウィンドウでpageTemplateDefタグを選択するか、プロパティ・インスペクタを使用してファセットおよび属性を追加できます。

注意:

テンプレート・コンポーネント・メタデータのファセット名や属性名を変更または削除する場合は、そのテンプレートを使用するJSFページのみでなく、テンプレート定義のレイアウト・セクションで参照されているファセットや属性名を手動で変更または削除する必要があります。

例19-10 ページ・テンプレート定義のコンポーネント・メタデータ

<af:pageTemplateDef var="attrs">
<af:xmlContent>
<component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
<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>

10. コンポーネント・パレットからコンポーネントをドラッグし、ビジュアル・エディタのページにドロップします。
ページ・テンプレートを使用するJSFページですでに使用されているため、ページ・テンプレート定義のレイアウト・セクション(またはレイアウト・セクションの一部を含むフラグメント・ファイル)では、f:viewタグを使用できません。

ベスト・プラクティスのヒント:

テンプレートには、documentまたはformタグを使用しないでください。理論上、テンプレート定義にdocumentおよびformタグを使用できますが、そうすると使用ページで使用できなくなります。ページ・テンプレートはページ・フラグメントに使用できるため、別のページに使用され、これらのタグが使用ページに含まれることになります。

レイアウト・セクションには、コンポーネントをいくつでも追加できます。クイック・スタート・レイアウトを使用しない場合、通常は、panelStretchLayoutまたはpanelGroupLayoutなどのパネル・コンポーネントを追加してから、そのパネル・コンポーネントにレイアウトを定義するコンポーネントを追加します。詳細は、第8章「Webページ上のコンテンツの編成」を参照してください。

宣言コンポーネントおよびデータ・バインドされたコンポーネントは、レイアウト・セクションで使用されます。宣言コンポーネントの使用の詳細は、宣言コンポーネントの使用に関する項を参照してください。ページ・テンプレート内のデータ・バインドされたコンポーネントの使用方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のページ・テンプレートの使用に関する項を参照してください。

11. ページ作成者がテンプレートを使用してコンテンツを挿入できる(レイアウト・セクション内の)コンポーネントで、コンポーネント・パレットからFacetRefをドラッグして、ページの必要な場所にドロップします。
たとえば、ページ・テンプレートのメインのコンテンツ領域にmainファセットを定義した場合、panelStretchLayoutコンポーネントのcenterファセットにfacetRefタグを子として追加し、mainファセットを参照します。設計時、ページ作成者がmainファセットにコンテンツをドロップすると、そのコンテンツはテンプレートに定義されているように、ページの適切な場所に配置されます。

適切な名前付きファセットを参照するためにfacetRefタグを使用すると、JDeveloperにより「facetRefの挿入」ダイアログが表示されます。そのダイアログで、ドロップダウン・リストからファセット名を選択するか、ファセット名を入力します。ページ・テンプレート定義ファイルのコンポーネント・メタデータにまだ定義されていないファセット名を入力すると、JDeveloperにより、xmlContentタグ内のコンポーネント・メタデータに新しいファセット定義用のエントリが自動的に追加されます。

注意:

ページ・テンプレート定義のレイアウト・セクションで、各ファセットを参照できるのは一度のみです。つまり、同じテンプレート定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

12. ページ・テンプレートのどこに属性を使用するかを指定するには、ページ・テンプレートのvar属性値を使用して、レイアウト・セクションの適切なコンポーネントにある関連する属性を参照します。

pageTemplateDefタグのvar属性では、ページ・テンプレートの独自の属性へのアクセスに使用するEL変数名を指定します。例19-10に示すように、JDeveloperにより使用されるvarのデフォルト値はattrsです。

たとえば、title属性を定義し、panelHeaderコンポーネントを追加した場合は、次のコードに示すように、panelHeaderコンポーネントのtext値にEL式#{attrs.title}を使用して、titleの値を参照します。

<af:panelHeader text="#{attrs.title}">

13. テンプレート・レイアウトに別のファイルを指定するには、次のコードに示すように、subviewタグでラップされたjsp:includeタグを使用してフラグメント・ファイルを参照します。

<f:subview id="secondaryDecoration">
<jsp:include page="fileExplorerSecondaryDecoration.jspx"/>
</f:subview>

指定されたフラグメント・ファイルも、階層の先頭にjsp:rootのみを含むXMLドキュメントである必要があります。フラグメントの使用方法の詳細は、JSFページでのページ・フラグメントの使用方法に関する項を参照してください。

コンポーネントにテンプレート・レイアウトを定義する複数のフラグメント・ファイルを作成し、ページ・テンプレート定義にフラグメント・ファイルを指定することにより、大規模なテンプレート・ファイルをメンテナンスしやすい小規模なファイルに分割できます。

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

注意:

ページ・テンプレートのコンポーネントにADFモデル・データ・バインディングが使用されている場合、またはテンプレートの作成時にADFページ定義を関連付けることを選択した場合は、JDeveloperにより、ADFモデルに関連するファイルおよびフォルダが自動的に作成されます。ページ・テンプレートおよびADFモデル・データ・バインディングとともに使用されるファイルの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ・テンプレートの使用」を参照してください。

初めてウィザードを使用してプロジェクトにJSFページ・テンプレートを作成する際には、ファイルシステムの/ViewController/src/META-INFディレクトリに格納されるpagetemplate-metadata.xmlファイルが自動的に作成されます。

ウィザードを使用して定義する各ページ・テンプレートに対して、JDeveloperにより、ページ・テンプレート定義ファイル(sampleTemplateDef1.jspxなど)が作成され、pagetemplate-metadata.xmlファイルにエントリが追加されます。例19-11に、pagetemplate-metadata.xmlファイルの例を示します。

例19-11 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ページを作成する場合、およびページ・テンプレート定義を含むプロジェクトをデプロイする場合に、使用可能なページ・テンプレートを判断するために使用されます。

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

通常、JSFページは、ページ・テンプレート定義が作成および格納されているのと同じプロジェクトに作成します。テンプレートに基づくページを作成するのと同じプロジェクトにページ・テンプレートが存在しない場合は、まず、ページ・テンプレート・プロジェクトをADFライブラリJARにデプロイします。プロジェクトのデプロイの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アプリケーション・コンポーネントの再利用」を参照してください。ページ・テンプレート・プロジェクトをデプロイすると、アプリケーションで作業している他の開発者とページ・テンプレートを共有できます。

注意:

テンプレートにjsp:includeタグが使用されている場合は、ADFライブラリにデプロイして別のアプリケーションで再利用することはできません。

ページ・テンプレートを使用して、JSFページまたはページ・フラグメントを作成できます。後からページ・テンプレートのレイアウト・セクションを変更すると、そのテンプレートを使用するすべてのページまたはページ・フラグメントがレイアウトの変更内容で自動的に更新されます。

テンプレートを使用するページで、pageTemplateタグの前後にコンテンツを追加できます。一般的に、pageTemplateタグはページに1つのみ使用しますが、複数使用することに対する制限はありません。

JDeveloperでは、JSFページの作成ウィザード、またはJSFページ・フラグメントの作成ウィザードにテンプレートの選択オプションが用意されているため、ページ・テンプレートに基づくJSFページの作成が簡略化されます。

ページ・テンプレートに基づくJSFページまたはページ・フラグメントを作成する手順:

1. JSF JSPページの作成方法に関する項の手順に従って、「JSFページの作成」ダイアログを開きます。ダイアログで、「ページ・テンプレートの使用」ドロップダウン・リストから使用するページ・テンプレートを選択します。

ヒント:

選択できるのは、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 Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』を参照してください。

4. 構造ウィンドウで、af:pageTemplateを選択します。これにより、プロパティ・インスペクタに、ページ・テンプレート定義に事前に定義されているすべての属性が表示されます。事前定義済の属性にはデフォルト値があります。
事前定義済の属性に静的値を割り当てることも、EL式(#{myBean.somevalue}など)を使用することもできます。属性に値を入力すると、JDeveloperによりコードにf:attributeタグが追加され、(存在する場合は)属性のデフォルト値が割り当てた値に置き換えられます(例19-12を参照)。

実行時、デフォルトまたは割り当てられた属性値が、属性名を参照するEL式(#{attrs.someAttributeName}など)によってページ・テンプレート定義に指定されているように、テンプレートの適切な部分に使用または表示されます。

注意:

事前定義済のテンプレート定義属性のみでなく、Id、ValueおよびViewIdなど、pageTemplateタグのその他の属性もプロパティ・インスペクタに表示されます。

pageTemplateタグのViewId属性では、実行時に使用ページで使用するために、ページ・テンプレート定義ファイルを指定します。ウィザードを使用して、テンプレートに基づくJSFページを作成する場合、JDeveloperでは、適切な値を持つViewId属性が自動的に割り当てられます。ViewId属性値は削除できません。削除すると、ランタイム・エラーが発生します。テンプレートに基づいたページの一部がレンダリングされなくなります。

5. CSSまたはJavaScriptなどのリソースを含めるには、af:resourceタグを使用する必要があります。詳細は、ページへのリソースの追加に関する項を参照してください。

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

テンプレートを使用してページを作成すると、JDeveloperにより、例19-12に示すように、ページ・テンプレート定義を参照するpageTemplateタグが挿入されます。テンプレートのファセットに追加されるコンポーネントでは、ファセットの参照にf:facetタグが使用されます。指定した属性値はすべて、f:attributeタグに表示されます。

例19-12 ページ・テンプレートを参照するJSFページ

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=windows-1252"/>
<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>

19.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 Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ページ・テンプレートの使用」を参照してください。

19.3.6 ページ・テンプレートおよびネーミング・コンテナについて

pageTemplateコンポーネントは、(テンプレート定義の直接のコンテンツであるか、jsp:includeアクションを使用して含められるフラグメント・コンテンツであるかに関係なく)テンプレートのすべてのコンテンツのネーミング・コンテナとして機能します。テンプレートに基づくページのクライアント側のイベントを処理している場合、コンポーネントを特定するコードを使用する際には、テンプレートのIDを指定する必要があります。詳細は、ネーミング・コンテナの使用に関する項を参照してください。

19.4 宣言コンポーネントの使用

宣言コンポーネントは、その他の既存のADF Facesコンポーネントで構成される再利用可能なコンポジットUIコンポーネントです。様々な状況で、同じコンポーネントを繰り返し再利用しているとします。一般的に使用されるUI要素を繰り返しコピーして貼り付けるかわりに、それらのコンポーネントを構成する宣言コンポーネントを定義し、そのコンポジット宣言コンポーネントを複数の場所またはページに再利用できます。

注意:

ページのすべてのview部分(フラグメント、宣言コンポーネントおよびメイン・ページ)では、同じリクエスト・スコープが共有されます。このため、1つのページに同じフラグメントまたは宣言コンポーネントを複数回使用する場合や、バッキングBeanが共有される場合に競合が発生する可能性があります。スコープの詳細は、オブジェクト・スコープ・ライフサイクルに関する項を参照してください。

アプリケーションに宣言コンポーネントを使用するには、まず、XML構文で記述されたJSFドキュメントであるXMLベースの宣言コンポーネント定義(ファイル拡張子は.jspx)を作成します。宣言コンポーネントJSFファイルには、f:viewおよびdocumentタグが含まれず、ルート・タグとしてcomponentDefが必要です。

宣言コンポーネントの完全な説明は、2つのセクション内に定義されています。1つのセクションはxmlContentで、宣言コンポーネントのサポートされているコンテンツ領域を説明するすべてのページ・テンプレート・コンポーネント・メタデータが含まれています。宣言コンポーネントのメタデータには次のものが含まれます。

- ファセット: ファセットは、宣言コンポーネントを構成する個々のコンポーネントに配置されるコンテンツに対してプレースホルダとして機能します。各コンポーネントは1つのファセットを参照します。ページの設計者が宣言コンポーネントを使用する場合、コンテンツをファセットに挿入します。このファセットにより、コンテンツをコンポーネントに挿入できるようになります。

ヒント:

ファセットは、宣言コンポーネント内でコンテンツを含むことのできる唯一の領域です。つまり、JSFページに使用した場合、宣言コンポーネントに子がない可能性もあります。コンテンツが必要なすべての領域にファセットを作成します。

- 属性: 個々のコンポーネントに属性を移入するために値を使用できる属性を定義します。たとえば、宣言コンポーネントにpanelHeaderコンポーネントが使用されている場合に、Titleという名前の属性を作成するとします。次に、Title属性の値が、panelHeaderコンポーネントのtext属性の値として使用されるように宣言コンポーネントを設計します。ユーザーがオーバーライドできる属性にデフォルト値を指定できます。

ヒント:

宣言コンポーネントのユーザーは、個々のコンポーネントに直接属性を設定できないため、ユーザーによる設定またはデフォルト値のオーバーライドが可能なすべての属性に、必ず属性を作成する必要があります。

また、宣言コンポーネントでクライアント側の属性(attributeDragSourceなど)を使用できるようにする場合は、その属性を作成し、宣言コンポーネントで使用される適切なコンポーネントに子として含める必要があります。詳細は、宣言コンポーネントの作成方法に関する項を参照してください。

- メソッド: 組み込まれるコンポーネントのいずれかにあるプロパティをバインドできるメソッドを定義できます。たとえば、宣言コンポーネントにボタンが含まれる場合、メソッド名およびシグネチャを宣言し、actionListener属性をその宣言済メソッドにバインドできます。ページ開発者が宣言コンポーネントを使用する際には、コンポーネントに必要なロジックが含まれるマネージドBeanのメソッドにリバインドします。
たとえば、宣言コンポーネントに、actionEventメソッドを起動する必要があるボタンが含まれるとします。シグネチャvoid method(javax.faces.event.ActionEvent)を使用するmethod1という名前の宣言メソッドを作成します。次に、ボタンのactionListener属性を、宣言済メソッドにバインドします。ページ開発者が宣言コンポーネントを使用する際には、JDeveloperにより、同じシグネチャを使用するバッキングBeanにメソッドを指定するよう求められます。

- タグ・ライブラリ: すべての宣言コンポーネントは、アプリケーションで使用するためにインポートするタグ・ライブラリに含まれている必要があります。

2つ目のセクション(xmlContentタグの外)は、宣言コンポーネントを構成するすべてのコンポーネントが定義される部分です。各コンポーネントには、コンポーネントへのコンテンツの追加に使用されるファセットへの参照が含まれます。

宣言コンポーネントをプロジェクトで使用するには、最初に宣言コンポーネントをADFライブラリとして含むライブラリをデプロイする必要があります。次に、デプロイ済ADFライブラリJARをプロジェクトのプロパティに追加します。これにより、自動的に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つ。

- toolbarButtonコンポーネントを3つ。それぞれのtext属性は対応するbuttonText属性に、render属性は対応するdisplay属性に、actionListener属性は対応するmethod名にバインドされます。

図19-2に、このような宣言コンポーネントがビジュアル・エディタでどのように表示されるかを示します。

図19-2 ビジュアル・エディタの宣言コンポーネント

ページ開発者が必要な属性またはメソッドを含む宣言コンポーネントをページにドロップすると、値を要求するダイアログが開きます。

開発者がレンダリングされる初めの2つのボタンにのみ値を設定し、出力テキストを含むpanelGroupLayoutコンポーネントを追加した場合、ページは図19-3のようにレンダリングされます。

図19-3 表示される宣言コンポーネント

注意:

宣言コンポーネントのコンポーネント・レイアウトには、フラグメントまたはADFのデータ・バインドされたコンポーネントは使用できません。いくつかのコンポーネントをADFモデル・レイヤーにバインドする必要がある場合は、バインド先のコンポーネント属性用に属性を作成します。宣言コンポーネントのユーザーは、それらの属性をADFモデル・レイヤーに手動でバインドできます。

また、宣言コンポーネントは外部のJARファイルで送信され、参照ファイルを見つけられないため、jsp:includeタグを使用できません。

宣言コンポーネントに、CSSに定義されているカスタム・スタイルまたはJavaScriptなどのリソースが必要な場合は、af:resourceタグを使用して、使用ページにそれらのリソースを含める必要があります。詳細は、ページへのリソースの追加に関する項を参照してください。

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

JDeveloperでは、JSF宣言コンポーネントの作成ウィザードを使用するため、宣言コンポーネント定義の作成が簡略化されます。このウィザードでは、ファセットの作成や宣言コンポーネントの属性およびメソッドの定義を行うことができます。ウィザードでは、宣言コンポーネントのタグ・ライブラリ情報を記述するcomponent-extensionタグにメタデータも作成されます。タグ・ライブラリ・メタデータは、宣言コンポーネントのJSPタグ・ライブラリを作成するために使用されます。

まず、componentDefタグのxmlContentセクション内にあるファセットおよび属性に、テンプレート・コンポーネント・メタデータを追加します。ファセットおよび属性に必要なコンポーネント・メタデータをすべて追加したら、xmlContentの外のセクションに、宣言コンポーネントの実際のレイアウトを定義するコンポーネントを追加します。

ベスト・プラクティスのヒント:

宣言コンポーネントのタグ・ライブラリ定義(TLD)はコンポーネントを使用する前に生成する必要があるため、使用される前にコンポーネントをJARファイルにデプロイする必要があります。宣言コンポーネントのみが含まれるアプリケーションを作成することをお薦めします。これにより、単一ライブラリのすべての宣言コンポーネントをデプロイして、複数のアプリケーションで使用できます。

宣言コンポーネント定義を作成する手順:

1. アプリケーション・ナビゲータで、宣言コンポーネントを作成および格納するフォルダを右クリックし、「新規」を選択します。

2. 「カテゴリ」ツリーで「JSF」ノードを選択し、「項目」ペインで「JSF宣言コンポーネント」を選択して「OK」をクリックします。

3. 宣言コンポーネントの名前およびファイル名を入力します。
指定する名前は、コンポーネント・パレットにおける宣言コンポーネントの表示名、およびコンポーネント・タグ用に生成されたJavaクラスの名前として使用されます。宣言コンポーネントの名前に使用できるのは、SampleNameまたはSampleName1などの英数字のみです。

ファイル名は、宣言コンポーネント定義ファイル(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 Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のFusion WebアプリケーションでのOracle ADFモデルの使用に関する項を参照してください。

また、宣言コンポーネントは外部のJARファイルで送信され、参照ファイルを見つけられないため、jsp:includeタグを使用できません。

12. ページ作成者がコンポーネントを使用してコンテンツを挿入できる(レイアウト・セクション内の)コンポーネントで、facetRefタグを使用して適切な名前付きファセットを参照します。
たとえば、メインのコンテンツ領域にcontentファセットを定義した場合、panelBoxコンポーネントにfacetRefタグを子として追加し、contentファセットを参照します。設計時、ページ開発者がcontentファセットにコンポーネントをドロップすると、そのコンポーネントはpanelBoxコンポーネントに配置されます。

コンポーネント・パレットからFacetRefをドラッグして、ページの目的の場所にドロップすると、JDeveloperにより「FacetRefの挿入」ダイアログが表示されます。そのダイアログで、ドロップダウン・リストからファセット名を選択するか、ファセット名を入力します。定義ファイルのコンポーネント・メタデータにまだ定義されていないファセット名を入力すると、JDeveloperにより、xmlContentタグ内のコンポーネント・メタデータに新しいファセット定義用のエントリが自動的に追加されます。

注意:

各ファセットを参照できるのは一度のみです。つまり、同じ宣言コンポーネント定義には、同じfacetName値を参照するfacetRefタグを複数使用することはできません。

13. 宣言コンポーネントのどこに属性を使用するかを指定するには、プロパティ・インスペクタと式ビルダーを使用して、作成した属性にコンポーネントの属性値をバインドします。

たとえば、title属性を定義し、panelBoxをコンポーネントとして追加した場合は、図19-4に示すように、プロパティ・インスペクタでテキスト属性の隣にあるドロップダウン・メニューを使用して式ビルダーを開きます。

図19-4 プロパティ・インスペクタにおける属性の式ビルダーの起動

式ビルダーで、JSPオブジェクト→「attrs」ノードを開き、プロパティ・インスペクタで属性値に使用する作成済の属性を選択します。たとえば、図19-5に、式ビルダーで選択したtitle属性を示します。「式に挿入」ボタンをクリックして「OK」をクリックし、属性値として式を追加します。

図19-5 式ビルダーに表示されている作成済の属性

14. 宣言コンポーネントのコマンド・ボタンで起動するメソッドを指定するには、そのコンポーネントのactionListener属性の隣にあるドロップダウン・メニューを使用し、「編集」を選択して「プロパティの編集」ダイアログを開きます。このダイアログを使用すると、宣言コンポーネントに作成した宣言メソッドのいずれかを選択できます。
ダイアログで「宣言コンポーネント・メソッド」を選択し、ドロップダウン・リストから宣言メソッドを選択して「OK」をクリックします。

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

JSF宣言コンポーネントの作成ウィザードを初めて使用する際、JDeveloperでは、ユーザーがウィザードに入力した名前を使用してメタデータ・ファイルが作成されます。コンポーネントのすべての定義は、componentDefタグに含まれています。このタグでは2つの属性が使用されます。1つ目はvarで、属性値にアクセスするために個々のコンポーネントにより使用される変数です。デフォルトで、varの値はattrsです。2つ目の属性はcomponentVarで、メソッドにアクセスするために個々のコンポーネントにより使用される変数です。デフォルトで、componentVarの値はcomponentです。

ファセット、属性およびメソッドを説明するメタデータは、xmlContentタグに含まれます。ファセット情報はfacetタグに、属性情報はattributeタグに、メソッド情報はライブラリ情報同様にcomponent-extensionタグに含まれます。例19-13に、図19-2に示されている宣言コンポーネントの省略形のコードを示します。

例19-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>component</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ページのものと同じです。属性またはメソッドに作成したバインドでは、バインドにコンポーネントの変数が使用されます。例19-14に、ツールバーに3つのボタンがあるpanelBoxコンポーネントのコードを示します。facetRefタグがpanelBoxコンポーネントの子であるため、ページ開発者が追加するすべてのコンテンツがpanelBoxコンポーネントの子になることに注意してください。

例19-14 宣言コンポーネント内のコンポーネント

<af:panelBox text="#{attrs.title}" inlineStyle="width:25%;">
<f:facet name="toolbar">
<af:group>
<af:toolbar>
<af:commandToolbarButton text="#{attrs.buttonText1}"
actionListener="#{component.handleMethod1}"
rendered="#{attrs.display1}"/>
<af:commandToolbarButton text="#{attrs.buttonText2}"
rendered="#{attrs.display2}"
actionListener="#{component.handleMethod2}"/>
<af:commandToolbarButton 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ファイルにエントリが追加されます。例19-15に、declarativecomp-metadata.xmlファイルの例を示します。

例19-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>
/dcomponentLib1
</taglib-uri>
<taglib-prefix>
dc
</taglib-prefix>
</declarativecomp-taglib>
</declarativeCompDefs>

注意:

アプリケーション・ナビゲータで宣言コンポーネントの名前の変更または削除を実行すると、JDeveloperにより、ファイルシステムの宣言コンポーネント定義ファイルの名前の変更または削除が行われますが、declarativecomp-metadata.xmlファイルの宣言コンポーネント・エントリを手動で変更または削除し、その宣言コンポーネントを使用するJSFページを更新または削除する必要があります。

declarativecomp-metadata.xmlファイルには、プロジェクトに作成したすべての宣言コンポーネントの名前、パスおよびタグ・ライブラリの情報が含まれます。プロジェクトのデプロイ時には、JDeveloperによりメタデータが使用され、宣言コンポーネントのJSPタグ・ライブラリおよびJavaクラスが作成されます。

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

宣言コンポーネントを表示するには、タグ・ライブラリ定義(TLD)が必要です。プロジェクトをデプロイすると、JDeveloperにより自動的にTLDが生成されます。このため、宣言コンポーネントを使用するには、まず、宣言コンポーネントを含むプロジェクトをデプロイする必要があります。これは、プロジェクトに宣言コンポーネントを使用する前、または他の開発者と宣言コンポーネントを共有する前に、ADFライブラリJARに宣言コンポーネント定義プロジェクトをデプロイする必要があることを意味します。プロジェクトをADFライブラリJARにデプロイする方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

簡単に説明すると、宣言コンポーネント定義を含むプロジェクトをデプロイすると、JDeveloperにより次の項目がADFライブラリJARに追加されます。

- 各宣言コンポーネント定義(つまり、各componentDefコンポーネント)用のコンポーネント・タグ・クラス(componentDef1Tag.classなど)

- プロジェクトdeclarativecomp-metadata.xmlファイルの情報を使用した、宣言コンポーネント用の1つ以上のJSP TLDファイル

使用プロジェクトで宣言コンポーネントを使用するには、デプロイ済のADFライブラリJARをプロジェクトのプロパティに追加します。ADFライブラリJARを追加する方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アプリケーション・コンポーネントの再利用」の章を参照してください。デプロイ済のJARを追加すると、JDeveloperにより、プロジェクトのプロパティに(再利用可能な宣言コンポーネントを含む)1つ以上のJSPタグ・ライブラリが自動的に挿入され、コンポーネント・パレットに表示されます。

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

JDeveloperで、コンポーネント・パレットからコンポーネントを選択およびドラッグし、ページの目的の場所にドロップして、その他のUIコンポーネントと同じように宣言コンポーネントをJSFページに追加します。宣言コンポーネントは、そのユーザー独自のタグ・ライブラリ用のパレットのページに表示されます。例19-6に、宣言コンポーネントを含むライブラリのコンポーネント・パレットのページを示します。

図19-6 宣言コンポーネントが表示されたコンポーネント・パレット

必要な属性を含む宣言コンポーネントをページにドラッグすると、定義済の属性に値を入力できるダイアログが開きます。

宣言コンポーネントをページに追加したら、宣言メソッドをマネージドBeanの実際のメソッドに手動でバインドする必要があります。

次の手順を実行する前に、宣言コンポーネントを使用するJSFページを作成中のプロジェクトに、宣言コンポーネントを含むADFライブラリJARを追加しておく必要があります。ADFライブラリJARを追加する方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アプリケーション・コンポーネントの再利用」の章を参照してください。

JSFページで宣言コンポーネントを使用する手順:

1. アプリケーション・ナビゲータで、JSFページ(またはJSFページ・テンプレート)をダブルクリックし、ビジュアル・エディタで開きます。

2. コンポーネント・パレットで、ドロップダウン・リストから、宣言コンポーネント・タグ・ライブラリの名前を選択します。ページに必要な宣言コンポーネントをドラッグ・アンド・ドロップします。同じページに同じ宣言コンポーネントを複数回追加できます。
宣言コンポーネント定義に必須属性が含まれる場合は、JDeveloperにより、挿入する宣言コンポーネントの必須の値を入力するためのダイアログが開かれます。

注意:

属性の値としてADFモデル・レイヤー・バインディングを使用する場合は、式ビルダーを使用してこれらのバインディングを手動で作成し、必要なバインディング・プロパティを特定します。

3. コンポーネント・パレットからテンプレートのファセットにコンポーネントをドラッグ・アンド・ドロップして、コンポーネントを追加します。構造ウィンドウで、宣言コンポーネントの要素(たとえば、dc:myPanelBoxなど)が表示されるまで、構造を展開します。ここで、dcはタグ・ライブラリの接頭辞で、myPanelBoxは宣言コンポーネント名です。
その下に、宣言コンポーネント定義に定義されているファセット(f:facet - contentなど)があります。これらのファセットにコンポーネントを追加します。

コンテンツを直接宣言コンポーネントに追加できません。コンテンツをドロップできるのは名前付きファセットに対してのみです。ファセットにドロップできるコンポーネントのタイプは、宣言コンポーネント定義のfacetRefタグの場所によって異なります。たとえば、宣言コンポーネント定義のtableの子になるようにfacetRefを定義した場合、tableがcolumnの子のみを受け入れるため、ファセットにドロップできるのはcolumnコンポーネントのみです。

注意:

宣言コンポーネントの直接の子として配置できるコンポーネントはありません。宣言コンポーネントに表示するコンテンツはすべて、宣言コンポーネントのファセットに配置する必要があります。

4. 構造ウィンドウで、宣言コンポーネント要素(dc:myPanelBoxなど)を再度選択します。プロパティ・インスペクタに、宣言コンポーネント定義に事前に定義したすべての属性およびメソッド(titleなど)が表示されます。属性にはデフォルト値があります。
属性に静的値を割り当てることも、EL式(#{myBean.somevalue}など)を使用することもできます。どのメソッドも、宣言コンポーネントに定義されている宣言済メソッドと同じシグネチャを使用するメソッドにバインドする必要があります。

実行時、属性名を参照するEL式(#{attrs.someAttributeName}など)によって宣言コンポーネント定義に指定されているとおりに、属性値が適切な部分に表示されます。

5. CSSまたはJavaScriptなどのリソースを含める必要がある場合は、af:resourceタグを使用してそれらのリソースを含める必要があります。詳細は、ページへのリソースの追加に関する項を参照してください。

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

ページに宣言コンポーネントを追加したら、宣言コンポーネント定義のコンポーネント・レイアウト・セクションに定義されているコンポーネントによってレンダリングされるコンテンツとともに、コンポーネントの定義済ファセットが名前付きのボックスとしてビジュアル・エディタに表示されます。

その他のUIコンポーネントと同じように、ページに初めて宣言コンポーネントを追加すると、次に示すように、JDeveloperにより、宣言コンポーネント・タグ・ライブラリの名前空間および接頭辞がページのjsp:rootタグに追加されます。

<jsp:root xmlns:dc="/dcomponentLib1: ..>

この例で、dcはタグ・ライブラリの接頭辞で、/dcomponentLib1は名前空間です。

JDeveloperにより、ページに宣言コンポーネントのタグが追加されます。タグには、コンポーネントの追加時にダイアログに設定したように、コンポーネントの属性値が含まれます。例19-16に、3つのoutputFormattedコンポーネントが含まれ、ユーザーがpanelGroupLayoutコンポーネントを追加したMyPanelBox宣言コンポーネントのコードを示します。

例19-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>

19.4.6 実行時の処理

宣言コンポーネントを使用するJSFページが実行されると、次の処理が行われます。

- 使用ページの宣言コンポーネント・タグにより、宣言コンポーネント・タグ・クラスと、宣言コンポーネントのメタデータおよびレイアウトを含む定義ファイルが特定されます。

- componentDefタグのレイアウト・セクションに定義されたコンポーネント・サブツリーがインスタンス化され、ページの宣言コンポーネント・タグで識別される場所にある使用ページのコンポーネント・ツリーに挿入されます。

- componentDefタグにより、宣言コンポーネントが内部的に独自の属性を参照できるように、var属性の値が設定されます。宣言コンポーネントにより設定されるのは属性値のみで、それらの値はランタイムによりcomponentDefタグに定義されている属性にマップされます。

- 宣言コンポーネント・メタデータを使用して、宣言コンポーネントにより属性にデフォルト値が適用され、必要な値が確認されます。

- 使用ページにより、ファセット・コンテンツがfacetタグを使用して宣言コンポーネントに渡されます。各facetタグのファセット・コンテンツは、componentDefタグのレイアウト・セクションにある対応するfacetRefタグで指定されているように、宣言コンポーネントの適切な場所に挿入されます。

19.5 ページへのリソースの追加

af:resourceタグを使用して、CSSまたはJavaScriptをページ、ページ・テンプレートまたは宣言コンポーネントに追加する必要があります。リソースは(HTML head要素にある)ページのみに追加できるため、このタグはページ・テンプレートおよび宣言コンポーネントに有用です。このタグをページ・テンプレートおよび宣言コンポーネントで使用する場合、リソースはJSP実行時に使用ページに追加されます。このタグを使用しない場合、スタイル・タグやリンク・タグを使用する場合はいつも、ブラウザでは、ページ・テンプレートおよび宣言コンポーネントを使用するページのレイアウトの再設定が必要になることがあります。リソースは、ページ・リクエストの間、ページに追加できますが、ドキュメント・コンポーネントがレンダリングされる前に追加する必要があります。

リソース・タグはPPRを使用して追加できます。PPR中は、次の要件が適用されます。

- URLリソースは、ページに追加される前にクライアント上で比較されます。これにより、複製は追加されません。

- CSSリソースは、PPRナビゲーション中にページから削除されます。新しいページには新しいCSSリソースがあります。

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

af:resourceタグを使用してリソースの場所を定義します。その後、使用ページのドキュメント・ヘッダーにリソースが追加されます。

リソースを追加する手順:

1. コンポーネント・パレットの「操作」セクションから、使用ページの任意の場所に「リソース」タグをドラッグ・アンド・ドロップします。

2. 「リソースの挿入」ダイアログで、cssまたはjavascriptを選択します。

3. プロパティ・インスペクタで、source属性の値としてリソースのURIを入力します。URIをコンテキストに相対させる必要がある場合は、URIの先頭にフォワード・スラッシュ(/)を1つ付けます。URIをサーバーに相対させる必要がある場合は、URIの先頭にフォワード・スラッシュ(/)を2つ付けます。URIの先頭を1つまたは2つのスラッシュ以外のものにした場合、URIはブラウザのURIの相対的な場所に解決されます。

19.5.2 実行時の処理: ドキュメント・ヘッダーへのリソースの追加

親コンポーネントを作成した場合は、JSPタグの実行中にaf:resourceタグのみを実行できます。これを実行すると、オブジェクトがRichDocumentコンポーネントのセットに追加されます。RichDocumentにより、指定したリソース(CSSまたはJavaScript)が使用ページに追加されます。

20 スタイルおよびスキンを使用した外観のカスタマイズ

この章では、ADF Facesのスキンおよびコンポーネントのスタイル属性を使用してスタイル・プロパティを変更することにより、アプリケーションの外観を変更する方法を説明します。

この章では、次の項目について説明します。

- 20.1項「スキン、スタイル・セレクタおよびスタイル・プロパティの概要」

- 20.2項「アプリケーションへのカスタム・スキンの適用」

- 20.3項「スキン・スタイル・プロパティの定義」

- 20.4項「コンポーネントのスタイル・プロパティの変更」

- 20.5項「スキンのCSSファイルにおけるURLの参照」

- 20.6項「カスタム・スキンのバージョニング」

- 20.7項「JARファイルへのカスタム・スキン・ファイルのデプロイ」

20.1 スキン、スタイル・セレクタおよびスタイル・プロパティの概要

JDeveloperでは、ADF Facesコンポーネントにスタイル情報を適用するためのオプションが2つサポートされています。

- 定義済のスタイル・セレクタを使用してスキンおよびCascading Style Sheet(CSS)を作成し、ADFアプリケーションがそのスキンとスタイルシートを使用するように構成します。

- スタイル・プロパティを使用してスキンCSSからのスタイル情報をオーバーライドし、コンポーネント表示の特定インスタンスを設定します。

ADF Facesコンポーネントでは、コンポーネントの機能はコンポーネント・クラスに、コンポーネントの表示はレンダラに委任されます。デフォルトでは、ADF Facesのすべてのタグが、関連付けられたコンポーネント・クラスとHTMLレンダラを結合し、HTMLレンダー・キットの一部になっています。ADF Facesには、デスクトップおよびPDAの両方に表示できるように、HTMLレンダー・キットが含まれています。ADF Facesレンダラはカスタマイズできません。ただし、スキンを使用してコンポーネントの表示方法をカスタマイズすることはできます。

アプリケーション全体のADF Facesコンポーネントを変更しない場合、ページ上のコンポーネント・インスタンスのスタイルを変更するように選択できます。また、プログラムによって条件付きでスタイルを設定することもできます。たとえば、ある特定の条件においてのみテキストが赤色で表示されるように設定できます。詳細は、20.4項「コンポーネントのスタイル・プロパティの変更」を参照してください。

File Explorerアプリケーションを使用すると、ドロップダウン・リストから複数のスキンを選択できます。File Explorerアプリケーションには、スキンの選択をサポートするためのCSSファイルが複数用意されています。詳細は、1.4.3項「File Explorerアプリケーションの概要」を参照してください。

このガイドでは、CSSの概念については説明しません。公式仕様など、スタイルシートの広範な情報は、次に示すW3CのWebサイトを参照してください。

http://www.w3.org/

注意:

11gリリース2 (11.1.2.0.0)では、ADFスキン・エディタが導入されました。このスタンドアロン製品を使用して、ADF Facesアプリケーションのスキンを視覚的に作成および変更できます。ADFスキン・エディタには、スキンの作成プロセスを簡略化する様々な機能があります。ADFスキン・エディタのインストール方法などの詳細は、http://www.oracle.com/technetwork/developer-tools/adf/downloads/index.htmlで、Oracle ADF 11gのリリース・ダウンロード・ページを参照してください。

20.1.1 ADF Facesスキン

スキンはCSS 3.0構文に基づくスタイルシートで、アプリケーション全体用に1箇所で指定されます。各コンポーネントへのスタイルシートの指定、または各ページへのスタイルシートの挿入を実行するかわりに、アプリケーション全体に対して1つのスキンを作成できます。各コンポーネントでは、スキンに記述されているスタイルが自動的に使用されます。スキンを使用すると、ページの外観を変更するためにJSFページに設計時の変更を加える必要がありません。スキンを使用すると、ADF Facesコンポーネントの外観をグローバルに変更できます。

既存のADF Facesアプリケーションでは、アプリケーションが作成されたときに使用するように構成されたスキンが使用されます。たとえば、Oracle ADF 11g (11.1.1.2.0)を使用してアプリケーションを作成した場合、アプリケーションではfusionスキンが使用されます。後続のリリースで作成したアプリケーションでは、このスキンを拡張するスキンが使用されます。アプリケーションをアップグレードした場合、最初に作成されたときに使用するように構成されたスキンが引き続き使用されます。アプリケーションで別のスキンを使用する場合は、カスタム・スキンを使用するためのアプリケーションの構成方法に関する項で説明されているように、trinidad-config.xmlファイルを編集します。

ADF Facesにより提供されたスキンの1つを拡張して、独自のカスタム・スキンを作成できます。詳細は、アプリケーションへのカスタム・スキンの追加方法に関する項を参照してください。自分で作成したカスタム・スキンをアプリケーションで使用する場合、カスタム・スキンの登録方法に関する項で説明されているように、trinidad-skins.xmlファイルを作成または編集し、さらにtrinidad-config.xmlファイルを編集します。

ADF Facesには、アプリケーションで使用する次のスキンが用意されています。

- simple : 最低限の書式設定のみが含まれています。

- blafplus-medium : 適度な数のスタイル設定が提供されます。このスタイルは、simpleスキンを拡張します。

- blafplus-rich: このスキンは、blafplus-mediumスキンを拡張します。blafplus-mediumスキンよりも多くのスタイルを提供します。たとえば、blafplus-richスキンのグラフィックには角丸があります。

- fusion: ADF Facesコンポーネントのデフォルトのスタイルを定義します。このスキンは、非常に多くのスタイルを提供します。

- fusion-11.1.1.3.0: より明瞭なタブのレンダリングを行う特定のコンポーネントに階層構造を作成するように、fusionスキンを変更します。これらのコンポーネントは、panelTabbed、navigationPane (属性hint="tabs")とdecorativeBoxです。またこのスキンでは、公開されたpanelAccordionコンポーネント・ペインに表示されるテキストを読みやすくするために、このペインのための、より目立たない背景イメージを定義しています。

- fusionFx-v1: このスキンは、fusion-11.1.1.3.0スキンから拡張されます。ADF Facesによって提供されたスキンのいずれかを拡張してカスタム・スキンを作成した場合、trinidad-skins.xmlファイルに登録する必要があります。fusionFx-v1スキンを拡張するには、trinidad-skins.xmlファイルで次の値を使用します。

<skin>
<id>yourSkin.desktop</id>
<family>yourSkinFamily</family>
<extends>fusionFx-v1.desktop</extends>
</skin>

アプリケーションでfusionFx-v1スキンを使用するには、trinidad-config.xmlファイルで次の値を使用します。

<skin-family>fusionFx</skin-family>

fusionFx-v1スキンには、数多くの問題に対応するためのデザインの改善と変更が含まれています。具体的には、これによって次のものが追加されます。

- 特定のブラウザでインライン・ポップアップが表示されたときに、基礎となるフレームのコンテンツが表示されないようにするため、背景色を.AFMaskingFrameグローバル・スタイル・セレクタにします。

- inputComboboxListOfValuesコンポーネントのための、ブールADFスキン・プロパティ-tr-stretch-dropdown-table。このプロパティは、表の列のコンテンツを表示するためにドロップダウン・リスト内の表をストレッチするか、または表の幅をinputComboboxListOfValuesコンポーネント内の入力フィールドの幅に制限するかどうかを指定します。

- inlineFrameコンポーネントは、フレームのコンテンツのロードが完了したことをブラウザが判別するまで、ロード・インジケータとして機能するイメージを表示します。
作成するカスタム・スキンにこの機能を実装できます。af|inlineFrameセレクタにある擬似クラスのbusyとflowを使用すると、このことを行うことができます。inlineFrameコンポーネントが親コンポーネントによってストレッチされない(inlineFrameコンポーネントがフローである)場合にのみ、inlineFrameコンポーネントによってIFrame要素が生成されます。af|inlineFrame:busy:flowを使用して、ロード・インジケータを参照する背景イメージ・スタイルを定義します。親コンポーネントによってinlineFrameコンポーネントがストレッチされる場合、生成されるコンテンツはより複雑になります。この複雑性により、af|inlineFrame::status-iconを使用してコンテンツ・イメージのURLを定義でき、af|inlineFrame::status-icon-styleを使用して、オプションで追加の背景イメージを定義できます。また、これにより、他のコンポーネント・セレクタが使用するイメージを再利用することもできます。たとえば、carouselコンポーネントのaf|carousel::status-iconセレクタとaf|carousel::status-icon-styleセレクタです。スキニング別名を使用して、これらのイメージを再利用します。

次のグローバル・セレクタも、ADFスキンにこの機能を実装している場合に使用できるものとして導入されています。

- .AFBackgroundImageStatus:alias: af|inlineFrame::busy:flowで使用される背景イメージを参照するために使用します。

- .AFStatusIcon:alias: af|carousel::status-iconとaf|inlineFrame::status-iconを参照するために使用します。

- .AFStatusIconStyle:alias: af|carousel::status-icon-styleとaf|inlineFrame::status-icon-styleを参照するために使用します。

リソース・キー(af_inlineFrame.LABEL_FETCHING)は、inlineFrameコンポーネントのロード・アイコンに表示する文字列を定義します。

- fusionFx-v1.1: このスキンはfusionFx-v1スキンから拡張されます。これにより、af:tableコンポーネントでQuery-By-Example (QBE)フィルタをクリアする機能にサポートが追加されます。
ADF Facesによって提供されたスキンのいずれかを拡張してカスタム・スキンを作成した場合、trinidad-skins.xmlファイルに登録する必要があります。fusionFx-v1スキンを拡張するには、trinidad-skins.xmlファイルで次の値を使用します。

<skin>
<id>yourSkin.desktop</id>
<family>yourSkinFamily</family>
<extends>fusionFx-v1.1.desktop</extends>
...
</skin>

アプリケーションでfusionFx-v1.1スキンを使用するには、trinidad-config.xmlファイルで次の値を使用します。

<skin-family>fusionFx</skin-family>
<skin-version>v1.1<skin-version>

- fusionFx-v1.2: このスキンは、fusionFx-v1.1スキンから拡張されます。アプリケーションがタッチ・スクリーン・デバイスでレンダリングされる際の最適化を含め、多数のユーザー・インタフェースの拡張が含まれています。
fusionFx-v1.2スキンを拡張するには、trinidad-skins.xmlファイルで次の値を使用します。

<skin>
<id>yourSkin.desktop</id>
<family>yourSkinFamily</family>
<extends>fusionFx-v1.2.desktop</extends>
...
</skin>

アプリケーションでfusionFx-v1.2スキンを使用するには、trinidad-config.xmlファイルで次の値を使用します。

<skin-family>fusionFx</skin-family>
<skin-version>v1.2<skin-version>

- プロジェクタ・スキン: ADF Facesでは、プロジェクタを使用してデモを行うアプリケーションのスタイルを定義します。各プロジェクタ・スキンでは、卓上プロジェクタ(特に古いモデルのプロジェクタ)を使用して表示した場合にアプリケーションが適切にレンダリングされるように、親スキンの複数の要素を変更します。たとえば、fusion-projectorスキンでは、fusionスキンの複数の要素が変更されます。これらのスキンは、プロジェクタと同じ場所にいる人を対象としている場合に役立ちます。これらは、Web会議を介して、オンラインでアプリケーションを表示する場合には適していない場合があります。ADF Facesではプロジェクタ・スキンを提供しており、これは、Oracle Technology Network(OTN) Webサイトからダウンロードできます。

図20-1に、File Explorerアプリケーションの索引ページに適用されたデフォルトのfusionスキンを示します。

注意:

スキンのスタイルシートの構文は、CSS 3.0仕様に基づいています。ただし、多くのブラウザはまだこのバージョンに準拠していません。実行時、CSSはADF FacesによりCSS 2.0仕様に変換されます。

図20-1 fusionスキンを使用した索引ページ

図20-2でFile Explorerアプリケーションの索引ページに適用されているように、ADF Facesにはsimpleスキンも用意されています。

図20-2 simpleスキンを使用した索引ページ

スキンには、標準のCSSスタイルやレイアウトを設定するよりも多くのオプションがあります。スキンのCSSファイルは、スキン・フレームワークによって処理され、スキン・プロパティとアイコンが抽出されてSkinオブジェクトに登録されます。たとえば、スキニング・フレームワークによりサポートされているルールおよび疑似クラスを使用して、スキン・ファイルをカスタマイズできます。サポートされているルールと擬似クラスには、@platform、@agent、@accessibility-profile、:rtl、@localeなどがあります。詳細は、20.1.2項「スキン・スタイル・セレクタ」を参照してください。

20.1.2 スキン・スタイル・セレクタ

スタイルシート・ルールには、要素を識別するスタイル・セレクタ、およびコンポーネントの外観を説明する一連のスタイル・プロパティが含まれます。ADF Facesコンポーネントには、2つのカテゴリのスキン・スタイル・セレクタがあります。

- グローバル・セレクタ
グローバル・セレクタは、複数のADF Facesコンポーネントのスタイル・プロパティを決定します。グローバル・セレクタ名が:alias疑似クラスで終了する場合、そのセレクタはコンポーネント固有の別のセレクタに含まれていることが多く、複数のコンポーネントのスキンに影響を与えます。たとえば、すべてではなくとも多くの場合、コンポーネントでは.AFDefaultFontFamily:alias定義を使用してフォント・ファミリを指定します。スキンが異なるフォント・ファミリを使用してこのセレクタをオーバーライドすると、その変更は、セレクタ定義にそのセレクタが含まれているすべてのコンポーネントに影響します。例20-1に、アプリケーションのADF Facesコンポーネント用のデフォルト・フォント・ファミリのグローバル・セレクタを示します。

例20-1 デフォルト・フォント・ファミリのグローバル・セレクタ

.AFDefaultFontFamily:alias {
font-family: Tahoma, Verdana, Helvetica, sans-serif;
}

- コンポーネント・セレクタ
コンポーネント固有のセレクタは、スキンを特定のADF Facesコンポーネントに適用できるセレクタです。例20-2に、af:inputTextコンポーネントのコンテンツ領域の背景色が赤に設定されているセレクタを示します。

例20-2 af:inputTextコンポーネントのセレクタ

af|inputText::content {
background-color: red;
}

各カテゴリには、次のタイプのADF Facesスキン・セレクタが1つ以上含まれることがあります。

- 標準セレクタ
標準セレクタは、スタイルを適用できる要素を直接表すセレクタです。たとえば、af|bodyはaf:bodyコンポーネントを表します。このタイプの要素には、CSSスタイル、プロパティおよびアイコンを設定できます。

- 疑似要素を持つセレクタ
疑似要素は、スタイルを適用できるコンポーネントの特定の領域を示すために使用します。疑似要素は、コロン(:)2つで始まり、その後にセレクタが表すコンポーネントの部分が続きます。たとえば、af|chooseDate::days-rowは、カレンダ・グリッド内の日付の外観に関するスタイルとプロパティを提供します。

- アイコン・セレクタ
一部のコンポーネントは、ベース・アイコンのセットを使用して、アイコン(<img>タグ)をレンダリングします。background-image CSSプロパティにエントリが表示されるように、エントリがアイコン用にCSSソース・ファイルに表示されなくても、これらのアイコンにスキンを適用できます。かわりに、アイコンは、レンダラが使用できるようSkinオブジェクトに登録されます。ブラウザが解釈するCSSソース・ファイルにアイコン・セレクタのエントリが表示されないため、アイコン定義用に包含セレクタ定義を作成できません。CSSソース・ファイルのエントリがあるアイテムのみに包含セレクタを作成できます。

アイコン・セレクタは、コンポーネント・セレクタでは-iconによって、グローバル・セレクタではIcon:aliasによって示されます。たとえば、af:inputDateコンポーネントに、セレクタaf|inputDate::changed-iconを使用するスキンを適用できる変更アイコンがあるとします。変更アイコンは、グローバル・セレクタ.AFChangedIcon:aliasが設定されたアイコンを使用して、すべてのコンポーネントに対してグローバルに設定することもできます。詳細は、20.3.2項「アイコンへのスキンの適用方法」を参照してください。

- リソース文字列
ADF Facesコンポーネントによりレンダリングされるテキストは変換可能です。テキストは、スキンが適用されたリソース文字列として抽象化されます。たとえば、「OK」ボタンが構成されている場合、af_dialog.LABEL_OKは、af:dialogコンポーネントのテキスト・ラベルのリソース文字列です。リソース文字列のスキンは、CSSスキン・ファイルではなく、<bundle-name>パラメータを使用するtrinidad-skins.xmlファイルのスキン定義ファイルから参照されるリソース・バンドルにあります。また、ELバインディングに<translation-source>パラメータを使用して、MapまたはResourceBundleを指すこともできます。詳細は、20.3.1項「テキストへのスキンの適用方法」を参照してください。

- スタイル・プロパティが指定されたセレクタ
スキン・スタイル・プロパティを使用すると、アプリケーション全体のコンポーネントのレンダリングをカスタマイズできます。CSSプロパティは、値とともにSkinオブジェクトに格納され、コンポーネントのレンダリング時に使用できます。たとえば、af|breadCrumbs{-tr-show-last-item: false}において、スキン・プロパティ-tr-show-last-itemは、af:breadCrumbsナビゲーション・パスの最後の項目を非表示にするように設定されています。

CSSの仕様では、ほぼすべてのコンポーネントに適用できる:hoverおよび:activeなどの疑似クラスが定義されます。ADF Facesには、特別な機能のための追加の疑似クラスが用意されています。疑似クラスは、クラス定義が続くコロンによってセレクタに示されます。次に、ADF Facesのスタイル・セレクタによって使用される一般的な疑似クラスを示します。

- 別名: :alias疑似クラスは特殊なタイプのクラスで、スキン・ファイルのコードを構成するための構文の補助として役立ちます。たとえば、これを使用して、複数のコンポーネント、またはコンポーネントの複数の部分のスタイルを設定します。独自の別名クラスを作成してから、後で他のセレクタに含めることもできます。たとえば、別名疑似クラス(.AFLabel:alias)を定義できます。ここで、多数のフォーム・コンポーネントにラベル色を定義します。別名疑似クラスに変更を加えると、別名疑似クラスが参照するすべてのコンポーネントに影響を与えます。

af|inputText::label,
af|inputChoice::label,
af|selectOneChoice::label {-tr-rule-ref: ".AFLabel:alias"}
.AFLabel:alias { color: blue }

.AFLabel:alias疑似クラスの色は青に設定されていますが、.AFLabel:aliasを変更するだけで、すべてのコンポーネントのラベル色を赤に変更できます。

.AFLabel:alias {color: red}

詳細は、20.3.5項「カスタム別名の作成方法」を参照してください。

- ドラッグ・アンド・ドロップ: 2つの疑似クラスを使用できます。:drag-sourceは、ドラッグを開始するコンポーネントに適用され、ドラッグが終了したら削除されます。:drop-targetは、現在のドラッグのドロップ先のコンポーネントに適用されます。

- 標準: CSSでは、:hover、:activeおよび:focusなどの疑似クラスは、コンポーネントの状態とみなされます。コンポーネントへのスキンの適用にも、これと同じ考え方が当てはめられます。コンポーネントの状態は、read-onlyまたはdisabledなどです。同じセレクタに状態を組み合せると、すべての状態が満たされた場合にのみセレクタが適用されます。

- 右から左: ブラウザで言語の読み方向が右から左の際に、スタイルまたはアイコンの定義を設定する場合にこの擬似クラスを使用します。その他の典型的なユース・ケースは非対称のイメージです。読み方向が右から左のイメージを使用するスキン・セレクタを設定する際には、イメージを反転する必要があります。セレクタの最後に:rtl疑似クラスを追加し、反転イメージ・ファイルを指すようにします。たとえば、ブラウザの読み方向が右から左に設定されている場合、panelBoxコンポーネントの最後のイメージは、panelBoxStart.pngファイルになります。右から左のpanelBoxの最後のイメージは、反転された左から右へのpanelBoxの最初のイメージと同じです。

af|panelBox::medium af|panelBox::top-end:rtl {
background-image: url(/skins/purple/images/panelBoxStart.png);
width:8px;
height:8px
}

:rtlは、スキン・アイコンへの適用にも使用できます。詳細は、20.3.2項「アイコンへのスキンの適用方法」を参照してください。

- インライン編集: この疑似クラスは、ブラウザで編集するために、コンポーネント・サブツリーがアプリケーションによりアクティブ化される際に適用されます。たとえば、:inline-selectedは、アクティブでインラインでの編集が可能なサブツリーで、現在選択されているコンポーネントに適用される疑似クラスです。

- メッセージ: この疑似クラスは、:fatal、:error、:warning、:confirmationおよび:infoのCSS疑似クラスを使用して、コンポーネント・レベルのメッセージ・スタイルを設定するために使用されます。詳細は、20.3.3項「メッセージへのスキンの適用方法」を参照してください。

セレクタのCSSプロパティをすべてのブラウザ、すべてのプラットフォーム、すべてのロケールおよび両方の読み方向に適用したくない場合があります。たとえば、他のブラウザには必要のないパディングをInternet Explorerに追加する必要がある場合があります。Windowsのフォント・スタイルをその他のプラットフォームのフォント・スタイルとは変えたい場合もあります。特定のユーザー環境用にセレクタをスタイル設定するには、スキニング・フレームワーク・ルールまたは:rtl疑似クラスにスキニング情報を配置します。スキニング・フレームワークは、HTTPリクエスト情報(エージェントやプラットフォームなど)に基づいてスタイルを選択し、ルールのないスタイルとマージさせます。ルールと一致するCSSプロパティは、すべてのルールに該当しないプロパティとマージされます。ユーザーの環境と最も一致する特定のルールが優先されます。現在、スキニング・フレームワークでは、次のルールと疑似クラスがサポートされています。

- @platformおよび@agent
@platformを使用してプラットフォーム・スタイルを、@agentを使用してブラウザ・スタイルを定義します。

プラットフォーム固有のスタイルの設定用にサポートされている値は、windows、macos、linux、solarisおよびppcです。ブラウザ・エージェント固有のスタイルにサポートされている値は、ie、mozilla、gecko、webkit (safariへのマップ)、iceおよびemailです。

次の例では、WindowsおよびLinuxプラットフォームで、af:inputTextコンポーネントのコンテンツ領域の色は、Internet Explorerのバージョン7および8、バージョン1.9のgeckoではピンクに設定されます。

@platform window, linux {
@agent ie and (version: 7) and (version: 8), gecko and (version: 1.9) {
af|inputText::content {background-color:pink
}
}
}

次の構文の例は同じ動作になることに注意してください。

@agent ie and (version: 7.*)
@agent ie and (version: 7)

たとえば、Internet Explorerのバージョン7.0.xのみを指定する場合は、次の構文を使用します。

@agent ie and (version: 7.0)

現在、バージョンの範囲を指定する構文はありません。

@agentルールを使用して、タッチ・スクリーン・デバイスのエージェントに適用するスタイルを指定することもできます。次の例に、この機能を構成するカスタム・スキン・ファイルに記述する構文を示します。

@agent (touchScreen:none) {
/* Styles that should not render on touchscreen devices. */
}

@agent (touchScreen:single) {
/* Styles specific for a touchscreen device with single touch. */
}

@agent (touchScreen:multiple) {
/* Styles specific for a touchscreen with multiple touch. */
}

@agent (touchScreen) {
/* Touchscreen specific styles for all touchscreen devices: both single and multiple touch. */
}

タッチ・スクリーン・デバイスでレンダリングするアプリケーションの作成の詳細は、付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」を参照してください。

- @accessibility-profile
trinidad-config.xmlファイルのhigh-contrastおよびlarge-fontsの各アクセシビリティ・プロファイル設定にスタイルを定義する、@accessibility-profileを定義します。

high-contrast値は、背景色と前景色のコントラストを相互に高める必要がある場合に使用します。large-fonts値は、ユーザーがWebブラウザのテキスト・スケーリング設定を増減できる必要がある場合に使用します。large-fontsを定義してもフォントは大きくなりませんが、固定ピクセル・サイズではなく、スケーラブル・フォントまたはディメンションになります。

<!-- Enable both high-contrast and large-fonts content -->
<accessibility-profile>high-contrast large-fonts</accessibility-profile>

- :rtl
ブラウザで読み方向が右から左の言語を表示する場合は、:rtl疑似クラスを使用してスタイルまたはアイコンの定義を作成します。

- @locale

- -tr-inhibitスキン・プロパティを使用して、スキン・スタイルを抑制します。
-tr-inhibitスキン・プロパティを使用して、ベース・スキンから継承されたCSSプロパティを抑制またはリセットします。たとえば、-tr-inhibit:paddingプロパティは継承されたパディングを削除します。-tr-inhibit:allプロパティを使用すると、継承されたすべてのプロパティが削除(クリア)されます。抑制するプロパティ名は、ベース・スキンのプロパティ名と完全に一致する必要があります。

- -tr-rule-refプロパティを使用してスタイルをマージします。
独自の別名を作成し、-tr-rule-refプロパティを使用して別のスタイル・セレクタと組み合せます。詳細は、20.3.5項「カスタム別名の作成方法」を参照してください。

- -tr-children-themeプロパティを使用して、子コンポーネントのテーマを変更します。
詳細は、コンポーネントへのテーマの適用方法に関する項を参照してください。

例20-3に、最終的なスタイルを提供するために一緒にマージされるCSSファイル内のセレクタをいくつか示します。

例20-3 スタイル・セレクタのマージ

/** For IE and Gecko on Windows, Linux and Solaris, make the color pink. **/
@platform windows, linux, solaris
{
@agent ie, gecko
{
af|inputText::content {background-color:pink}
}
}
af|someComponent {color: red; width: 10px; padding: 4px}

/* For IE, we need to increase the width, so we override the width.
We still want the color and padding; this gets merged in. We want to add
height in IE.  */

@agent ie        {          af|someComponent {width: 25px; height: 10px}        }
/* For IE 7 and 8, we also need some margins.*/
@agent ie (version: 7) and (version: 8)
{
af|someComponent {margin: 5px;}
}

/* For Firefox 3 (Gecko 1.9) use a smaller margin.*/
@agent gecko (version: 1.9)\
{
af|someComponent {margin: 4px;}
}

/* The following selectors are for all platforms and all browsers. */
/* rounded corners on the top-start and top-end */
/* shows how to use :rtl mode pseudo-class. The start image in ltr mode is the */
/* same as the end image in the right-to-left mode. */
af|panelBox::medium af|panelBox::top-start,
af|panelBox::medium af|panelBox::top-end:rtl {
background-image: url(/skins/purple/images/panelBoxStart.png);
width:8px;
height:8px
}

af|panelBox::medium af|panelBox::top-end,
af|panelBox::medium af|panelBox::top-start:rtl {
background-image: url(/skins/purple/images/panelBoxEnd.png);
height: 8px;
width:  8px;
}

ADF Facesコンポーネントへのスキンの適用に使用されるセレクタは、JDeveloperオンライン・ヘルプのFusionのADF Facesコンポーネントのスキン・セレクタに関するトピックおよびFusionのデータの可視化ツール・コンポーネントのスキン・セレクタに関するトピックに定義されています。

コンポーネント・レベルにルック・アンド・フィールを実装する方法として、テーマを適用することもできます。テーマの詳細は、20.3.4項「コンポーネントへのテーマの適用方法」を参照してください。

スキン・スタイル・プロパティの定義方法の詳細は、20.3項「スキン・スタイル・プロパティの定義」を参照してください。

20.1.3 コンポーネント・スタイル・プロパティ

任意のコンポーネントのルック・アンド・フィールは、設計時に、スタイル関連プロパティinlineStyleおよびstyleClassを変更することによって調整できます。この2つのプロパティは、root DOM要素でレンダリングされます。設計時に指定するスタイル関連プロパティは、アプリケーション・スキンまたはコンポーネントの特定インスタンスのCSSに指定されている類似のスタイルをオーバーライドします。

inlineStyle属性は、CSSスタイルのセミコロンで区切られた文字列で、background-color:red; color:blue; font-style:italic; padding:3pxのように、個々の属性を設定できます。styleClass属性は、一連のインライン・スタイルのグループ化に使用されるCSSスタイル・クラス・セレクタです。スタイル・クラスは、.AFInstructionTextなどのADFパブリック・スタイル・クラスを使用して定義でき、af:outputTextコンポーネントに表示されるテキストのすべてのプロパティを設定します。

コンポーネント・スタイル・プロパティの適用方法の詳細は、20.4項「コンポーネントのスタイル・プロパティの変更」を参照してください。

特定のセレクタの場合、レンダラのクラスを作成することによって、カスタム・コンポーネントのスタイル・プロパティを取得できます。詳細は、レンダラのクラスの作成方法に関する項を参照してください。

20.2 アプリケーションへのカスタム・スキンの適用

カスタム・スキンは、企業の希望するルック・アンド・フィールを実現するために、色、フォントおよびADF Facesコンポーネントの一部の場所を変更できます。スキンは、CSSファイルにスタイル・セレクタを定義して作成します。カスタム・スタイルシートを作成したら、アプリケーションの有効なスキンとして登録し、そのスキンを使用するようにアプリケーションを構成します。同じスキン・ファミリ内の複数のADFスキンをバージョニングした場合は、カスタム・スキンのバージョニングに関する項で説明されているように、<skin-version>要素を使用して、アプリケーションが使用する特定のバージョンを指定してください。

デフォルトでは、ADF Facesコンポーネントではfusionスキンが使用されます。カスタム・スキンは、任意のADF Facesスキンfusion、blafplus-rich、blafplus-mediumまたはsimpleを拡張できます。カスタム・スキンを作成するには、拡張するスタイルシートのセレクタをオーバーライドまたは禁止するセレクタをスタイルシートに宣言します。オーバーライドしないように選択したセレクタは、そのスキンで定義されているスタイルを引き続き使用します。

simpleスキンの拡張では、BLAF Plusスキンを拡張する場合ほど、多くのプロパティを禁止する必要はありません。たとえば、BLAF Plusスキンでは、テキスト、背景および枠などのスタイル・プロパティの様々な色が使用されます。simpleスキンでは、特定の色ではなく、.AFDarkBackground:aliasのように:alias疑似クラスが使用されます。色のスキームの変更では、複数の色を指定するコンポーネント・スキン・セレクタの場合より、オーバーライドする必要のあるグローバル・スキン・セレクタの数はかなり少なくなります。

スキンで使用されるテキストは、リソース・バンドル内で定義されます。blafplus-richスキンのセレクタと同様に、このテキストは、カスタム・リソース・バンドルを作成し、変更するテキストのみを宣言することによってオーバーライドできます。カスタム・リソース・バンドルを作成した後、スキンにそれを登録します。

複数のスキンを作成して適用できます。たとえば、Webアプリケーションのバージョン用にスキンを1つ作成し、PDAでアプリケーションが実行されるときに使用するスキンを別に作成します。あるいは、現在のユーザーのブラウザで設定されているロケールに基づいてスキンを変更することもできます。また、af:selectOneChoiceコンポーネントなどのコンポーネントを構成し、ユーザーがスキンを切り替えられるようにできます。

デプロイするアプリケーションにカスタム・スキン・リソースおよび構成ファイルをバンドルできますが、Javaアーカイブ(JAR)ファイルにスキン定義を保存して、デプロイ済アプリケーションにこれを追加することもできます。JARファイルを使用する利点は、ルック・アンド・フィールの一貫性を改善しつつ、アプリケーションとは別にカスタム・スキンを開発およびデプロイできるということと、スキン定義およびイメージ・ファイルを独自のJARファイルに分けて、アプリケーションにデプロイする必要のあるファイル数を減らすことができるということです。

カスタム・スキンをアプリケーションに適用する手順は、次のとおりです。

1. カスタム・スキンをアプリケーションに追加します。詳細は、20.2.1項「アプリケーションへのカスタム・スキンの追加方法」を参照してください。

2. カスタム・スキンを登録します。詳細は、カスタム・スキンのためのXMLスキーマ定義ファイルの登録方法に関する項およびカスタム・スキンの登録方法に関する項を参照してください。

3. カスタム・スキンを使用するようにアプリケーションを構成します。詳細は、20.2.4項「カスタム・スキンを使用するためのアプリケーションの構成方法」を参照してください。

4. JARファイルにカスタム・スキンをデプロイします。詳細は、JARファイルへのカスタム・スキン・ファイルのデプロイに関する項を参照してください。

20.2.1 アプリケーションへのカスタム・スキンの追加方法

アプリケーションにカスタム・スキンを追加するには、JDeveloper内にCSSファイルを作成します。CSSはアプリケーションとともにデプロイするために、JDeveloperによりプロジェクトのソース・ファイルに配置されます。

カスタム・スキンをアプリケーションに追加する手順:

1. JDeveloperで、「CSSレベル3」および「ADF Faces」が選択されていることを確認します。メイン・ツールバーで、「ツール」→「プリファレンス」→「CSSエディタ」を選択します。サポート・レベルにドロップダウン・メニューから「CSSレベル3」を選択し、「サポート対象コンポーネント」に「ADF Faces拡張機能」を選択します。

2. アプリケーション・ナビゲータで、ユーザー・インタフェースのコードが含まれるプロジェクトを右クリックし、ポップアップ・メニューから「新規」を選択します。

3. 「新規ギャラリ」の「カテゴリ」で、「Web層」を開いて「HTML」を選択します。

4. 「CSSファイル」オプションをダブルクリックします。

5. 「Cascading Style Sheetの作成」ダイアログで、CSSの名前とパスを入力します。

6. 「OK」をクリックします。

これで、CSSエディタにCSSを開いて、アプリケーションのスタイルを定義できます。ADF Facesコンポーネントのスタイル・セレクタ設定の詳細は、20.3項「スキン・スタイル・プロパティの定義」を参照してください。

また、Oracle JDeveloperのコンテキスト外にCSSを作成し、スキン・リソースとともにCSSをJARファイルにパッケージ化できます。この推奨オプションの詳細は、JARファイルへのカスタム・スキン・ファイルのデプロイに関する項を参照してください。

20.2.2 カスタム・スキンのためのXMLスキーマ定義ファイルの登録方法

カスタム・スキンの登録方法に関する項で説明されているように、カスタム・スキンを登録する場合、trindidad-skins.xsdファイルをJDeveloperに登録する必要があります。trindidad-skins.xsdファイルでは、カスタム・スキンに有効な要素を定義します。

XMLスキーマ定義ファイルを登録する手順:

1. JDeveloperで、「ツール」→「プリファレンス」の順に選択します。

2. 「プリファレンス」ダイアログの左ペインで「XMLスキーマ」を選択し、「追加」をクリックします。

3. 「スキーマの追加」ダイアログで「参照」をクリックして、使用しているバージョンのJDeveloperに含まれているXMLスキーマに移動します。
XMLスキーマへのディレクトリ・パスは次のようになります。

JDeveloper_Home/jdeveloper/modules/oracle.adf.view_11.1.1/trinidad-impl.jar!/org/apache/myfaces/trinidadinternal/ui/laf/xml/schemas/skin/trinidad-skins.xsd

注意:

「スキーマの追加」ダイアログでは、「拡張子」入力フィールドの値が.xmlであることを確認してください。拡張子を.xsdに変更すると、後でXMLファイルを作成するときに、作成したXMLスキーマを使用できなくなります。

4. 「OK」をクリックします。

20.2.3 カスタム・スキンの登録方法

スキンの登録では、trinidad-skins.xmlという名前のファイルを作成し、スキンのID、ファミリ、場所およびカスタム・リソース・バンドルのいずれかを使用している場合は、このファイルにそれらを識別する値を移入します。

作業を始める前に、次のようにします。

trinidad-skins.xmlファイルに有効な要素を定義するXMLスキーマ定義ファイルを登録します。詳細は、カスタム・スキンのためのXMLスキーマ定義ファイルの登録方法に関する項を参照してください。

カスタム・スキンを登録する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「XML」を選択します。

3. 「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

4. 「XMLスキーマからXMLを作成 - ステップ1/2」ダイアログで次を入力します。

- XMLファイル: trinidad-skins.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

5. 「XMLスキーマを作成 - ステップ2/2」ダイアログで次を入力します。

- ターゲット・ネームスペース: http://myfaces.apache.org/trinidad/skinを選択します。

- ルート要素: skinsを選択します。

- 「終了」をクリックします。新規ファイルは、XMLエディタで自動的に開きます。

6. XMLエディタで、次の要素の値を入力します。

- <id>
スキンには一意のIDが必要です。EL式を使用してスキンIDを参照することもできます。たとえば、ロケールごとに異なるスキンを使用する場合、IDに基づいて適切なスキンを選択するEL式を作成します。fusion.desktopのように、IDの最後にdesktop、.pdaまたは.portletを追加するという規則があります。

- <family>
スキンの特定のファミリを使用するようにアプリケーションを構成できます。これにより、使用されるレンダー・キットを基に、アプリケーションのスキンをグループ化できます。

たとえば、blafplus-rich.desktopスキンおよびblafplus-rich.pdaスキンがrichDemoファミリの一部になるように定義すると、システムにより、render-kit-idに基づいて適切なスキンが自動的に選択されます。

<skin>
<id>richdemo.desktop</id>
<family>richDemo</family>
<extends>blafplus-rich.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/richdemo/richdemo.css</style-sheet-name>
</skin>
<skin>
<id>richdemo.pda</id>
<family>richDemo</family>
<extends>blafplus-rich.pda</extends>
<render-kit-id>pda</render-kit-id>
<style-sheet-name>skins/richdemo/richdemo.css</style-sheet-name>
</skin>

注意:

特定のファミリのスキンで複数のスキンを作成する場合、作成するスキンをバージョニングできます。詳細は、カスタム・スキンのバージョニングに関する項を参照してください。

- <extends>
この要素を使用してカスタム・スキンを拡張します。この要素のデフォルト値はsimple.desktopです。ただし、この要素を使用することで任意のスキンを拡張できます。

たとえば、スキンを拡張し、フォント別名を使用してCSSを作成することで、スキン全体のフォントを簡単に変更できます。たとえば、次のようにしてfusion.desktopファミリを拡張します。

<extends>fusion.desktop</extends>
<style-sheet-name>skins/fod_skin.css</style-sheet-name>

CSSに、スキン全体のフォントを変更するための別名を設定します。

.AFDefaultFontFamily:alias {font-family: Tahoma}.AFDefaultFont:alias {font-size: 16px}

- <render-kit-id>
この値によって、スキンに使用するレンダー・キットが決まります。次のいずれかを入力できます。

- org.apache.myfaces.trinidad.desktop: アプリケーションのデスクトップでのレンダリング時にスキンが自動的に使用されます。

- org.apache.myfaces.trinidad.pda: このスキンは、アプリケーションがPDAにレンダリングされる際に使用されます。

- <style-sheet-name>
カスタム・スタイルシートのURLです。スタイルシート名ファイルは、次の方法でURLオブジェクトとして取得されます。

- サーバーの起動後に変更可能な非静的URLの場合、style-sheet-nameがhttp:、https:、file:、ftp:またはjar:で始まる場合には、new java.new.URL(style-sheet-name)をコールすることでURLが作成されます。そうでない場合、URLは<FacesContext> <ExternalContext> getResource<style-sheet-name>をコールして作成されます。存在しない場合には、URLのパーツを区切るためにスラッシュ(/)が追加されます。たとえば、skins/bigfont/bigfont.cssの間にスラッシュが追加されます。

- まだ取得されていない場合は、<ClassLoader> getResourceを使用して、META-INF/purpleSkin/styles/myPurpleSkin.cssに類似のstyle-sheet-nameの書式でURLが作成されます。URLがこの書式に変換されたら、スタイルシートを含むJARファイル内で検索できます。

- <bundle-name>
スキン用に作成されたリソース・バンドルです。カスタム・バンドルを作成していない場合は、この要素を宣言する必要はありません。詳細は、20.3.1項「テキストへのスキンの適用方法」を参照してください。

注意:

リソース・バンドルのローカライズ済バージョンをすでに作成してある場合、必要な作業はベース・リソース・バンドルを登録することのみです。

- <translation-source>
MapまたはResourceBundleを指すELバインディングです。実行時のスキンの変換をより動的に行う場合は、バンドル名のかわりにこれを使用できます。<bundle-name>タグが優先されます。

例20-4に、mySkinスキンのtrinidad-skins.xmlファイルのエントリを示します。

例20-4 trinidad-skins.xmlファイルのスキンのエントリ

<?xml version="1.0" encoding="ISO-8859-1"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin>
<id>
mySkin.desktop
</id>
<family>
mySkin
</family>
<extends>blafplus-rich.desktop</extends>
<render-kit-id>
org.apache.myfaces.trinidad.desktop
</render-kit-id>
<style-sheet-name>
skins/mySkin/mySkin.css
</style-sheet-name>
<bundle-name>
myBundle
</bundle-name>
<translation-source></translation-source>
</skin>
</skins>

7. ファイルを保存します。

20.2.4 カスタム・スキンを使用するためのアプリケーションの構成方法

trinidad-config.xmlファイル内に、使用するスキン(および必要な場合は、それが使用される条件)を決定する要素を設定します。

注意:

スキンが表示されない場合は、af:documentタグがページに追加されているかどうかを確認してください。af:documentタグによりスキン・フレームワークが初期化され、CSSが作成されてページにリンクされます。

スキンを使用するようにアプリケーションを構成する手順:

1. trinidad-config.xmlファイルを開きます。

2. trinidad-config.xmlファイルに、使用するスキンの<skin-family>要素、および<skin-version>要素(オプション)の値を指定するためのエントリを書き込みます。
例20-5に、mySkinスキン・ファミリを使用するための構成を示します。

例20-5 スキン・ファミリを使用するための構成

<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>mySkin</skin-family>
<skin-version>v2</skin-version>
</trinidad-config>

3. 値を条件付きで設定するには、表示するスキンを決定するために評価できるEL式を入力します。
たとえば、ユーザーのブラウザがドイツのロケールに設定されているときにはドイツ語のスキンを使用し、それ以外のときには英語のスキンを使用する場合、trinidad-config.xmlファイル内に次のように入力します。

<skin-family>#{facesContext.viewRoot.locale.language=='de' ? 'german' : 'english'}</skin-family>

4. ファイルを保存します。

開発中、カスタム・スキンを変更したら、例20-6に示すように、web.xmlファイル・パラメータorg.apache.myfaces.trinidad.CHECK_FILE_MODIFICATIONをtrueに設定することで、サーバーを再起動せずにCSSの変更を確認できます。ただし、アイコンおよびスキン・プロパティの変更を確認するには、サーバーを再起動する必要があります。

例20-6 スキンの変更を確認するためのweb.xmlパラメータ

<context-param>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>true</param-value>
</context-param>

20.3 スキン・スタイル・プロパティの定義

ADF Facesスキン・スタイル・セレクタでは、アプリケーションにカスタムのルック・アンド・フィールを作成するために、コンポーネントにスキンを適用する複数のオプションがサポートされています。表20-1に、af:goButtonコンポーネントのスキン・スタイル・セレクタを説明します。

表20-1 af:goButtonコンポーネントのスタイル・セレクタ

名前

説明

af|goButton

af:goButtonコンポーネントのルート要素のスタイル。:disabledのみでなく、:hover、:activeまたは:focusなどの有効なCSS-2.1疑似クラスを使用して、様々な状態のコンポーネントをスタイル設定できます。Internet Explorer 7(IE7)では、ボタンに対して、:activeおよび:focus疑似クラスが機能しないことに注意してください。また、IE7では、無効化ボタンをスタイル設定できません。同じ方法ですべてのボタン・コンポーネントにスキンを適用するには、.AFButton*:aliasセレクタをショートカットとして使用します。

af|goButton::icon-style

ボタン・アイコンのスタイル(af:goButtonにアイコン属性が設定されている場合)。

af|goButton::access-key

ボタンのテキストのスタイル。.AFButtonAccessKeyStyle:aliasスタイルが含まれます。

図20-3に、af:goButtonコンポーネントおよびコンポーネント・アイコンに、デフォルトのfusionスキンを適用した様子を示します。

図20-3 af:goButtonコンポーネントのデフォルトの外観

図20-4に、カスタム・スキンに次のスタイル・プロパティを設定したことによる、ボタンおよびアイコンの新しい外観を示します。

af|goButton::access-key {color: red;}
af|goButton::icon-style {border: 1px solid black;}

図20-4 カスタム・スキンが適用されたaf:goButtonコンポーネント

デフォルト・スキンにより使用されるADF Facesスキン・スタイル・セレクタは、JDeveloperオンライン・ヘルプの「FusionのADF Facesコンポーネントのスキン・セレクタ」および「Fusionのデータの可視化ツール・コンポーネントのスキン・セレクタ」のトピックに定義されています。これらは、「すべてのオンライン・ヘルプ」→「開発用Oracle ADF Facesアプリケーション」にあります。

JDeveloperでは、CSSファイルの編集中に、コーディングがサポートされます。ファイル・ディレクトリの編集時、またはJSPソース・エディタのADF Facesコンポーネントの編集時に、CSSコード・エディタを起動できます。次のような場合に、コード・サポートを使用できます。

- コード・インサイト

- エラーの強調表示

- スタイルのプレビュー

- リファクタ

- 使用方法の検索

- クイック・コメント

- 書式設定

- 一致タグの強調表示

20.3.1 テキストへのスキンの適用方法

スキンは、CSSファイルを使用してスタイルを決定する他、リソース・バンドルを使用してコンポーネント内のテキストを決定します。ADF Facesコンポーネントがレンダリングするテキストは、リソース文字列として変換および抽象化できます。たとえば、
af_chooseDate.LABEL_SELECT_YEARは、af:chooseDateコンポーネントを使用して年の選択に使用されるフィールド・ラベルのリソース文字列です。すべてのADF Facesスキンでは同じリソース・バンドルが使用されます。

ADF Facesコンポーネントのテキストにスキンを適用するには、カスタム・リソース・バンドルを作成し、デフォルトのリソース文字列値をオーバーライドします。次に、trinidad-skins.xmlファイルのカスタム・リソース・バンドルに<bundle-name>プロパティを設定します。

注意:

ADF Facesコンポーネントでは自動変換がサポートされています。コンポーネントのスキンに使用されるリソース・バンドルは、28の言語に変換されます。ユーザーがドイツ語を使用するようにブラウザを設定した場合、コンポーネント内に含まれるテキストはすべて自動的にドイツ語で表示されます。このため、カスタム・スキン用のリソース・バンドルを作成した場合は、アプリケーションでサポートされる他の言語に対応する、そのバンドルのローカライズ済バージョンも作成する必要があります。

詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

カスタム・リソース・バンドルを作成および登録する手順:

1. JDeveloperで、単純なJavaクラスを新規に作成します。

- アプリケーション・ナビゲータで、ファイルの保存場所を右クリックし、「新規」を選択して「新規ギャラリ」を開きます。

- 「カテゴリ」ツリーで「JAVA」を選択し、「項目」リストで「Javaクラス」を選択します。

- クラスの名前とパッケージを入力します。クラスはjava.util.ListResourceBundleを拡張している必要があります。

2. オーバーライドするキーをバンドルに追加し、必要に応じてテキストを設定します。例20-7に、SkinBundleカスタム・リソース・バンドルを示します。

例20-7 カスタムのSkinBundleに設定されているリソース文字列

public class SkinBundle extends ListResourceBundle {
@Override
public Object[][] getContents() {
return _CONTENTS;
}

static private final Object[][] _CONTENTS = {
{"af_tableSelectMany.SELECT_COLUMN_HEADER", "Select A Lot"},
{"af_tableSelectOne.SELECT_COLUMN_HEADER", "Select Just One"},
{"af_showDetail.DISCLOSED_TIP", "Click to Hide"}
};
}

3. trinidad-skins.xmlファイルの<bundle-name>パラメータにカスタム・リソース・バンドルの名前を設定します。例20-8に、trinidad-skins.xmlファイルのカスタムSkinBundle設定を示します。

例20-8 trinidad-skins.xmlのカスタムSkinBundle設定

<skin>
<id>
purple.desktop
</id>
<family>
purple
</family>
<render-kit-id>
org.apache.myfaces.trinidad.desktop
</render-kit-id>
<style-sheet-name>
skins/purple/purpleSkin.css
</style-sheet-name>
<bundle-name>
org.apache.myfaces.trinidaddemo.resource.SkinBundle
</bundle-name>
</skin>

テキストにスキンを適用する別のオプションでは、<bundle-name>ではなく<translation-source>パラメータを使用します。<translation-source>パラメータは、MapまたはResourceBundleを指すELバインディングです。このオプションの利点は、実行時に使用する任意のロジックに基づいて、変換値を自動的に変更できることです。両方が設定されている場合、<bundle-name>タグが優先されます。例20-9に、バンドル・マップへの<translation-source>パラメータの設定にEL式を使用するコードを示します。

例20-9 カスタム・リソース・バンドル・マップ

public class SkinTranslationMapDemo
{
/* Test a skin's translation-source EL pointing to a Map */
public Map<String, String> getContents()
{
return _CONTENTS;
}

static private final Map<String, String> _CONTENTS = new HashMap<String, String>();
static
{
_CONTENTS.put("af_inputDate.LAUNCH_PICKER_TIP", "Launch PickerMap");
_CONTENTS.put("af_showDetail.DISCLOSED_TIP", "Hide Tip Map");
_CONTENTS.put("af_showDetail.DISCLOSED", "Hide Map");

}
}

例20-10に、trinidad-skins.xmlファイルのリソース・マップへの<translation-source>パラメータの設定を示します。

例20-10 trinidad-skins.xmlに設定されているカスタム・リソース・バンドル・マップ

<skin>
<id>
purple.desktop
</id>
<family>
purple
</family>
<render-kit-id>
org.apache.myfaces.trinidad.desktop
</render-kit-id>
<style-sheet-name>
skins/purple/purpleSkin.css
</style-sheet-name>
<translation-source>
#{skinTranslationMap.resourceBundle}
</translation-source>
</skin>

20.3.2 アイコンへのスキンの適用方法

アイコン・スタイル・セレクタにあるアイコン・イメージへのURLパスを指定することで、ADF Facesコンポーネントに関連付けられているデフォルト・アイコンにスキンを適用できます。

アイコン・セレクタでは、疑似クラス(:hoverなど)のようなCSS構文、および子セレクタやコンポジット・クラス・セレクタは機能しないことに注意してください。

注意:

アイコンのセレクタをオーバーライドする場合、アイコン・イメージへのURLのコンテキスト相対パス(スラッシュ(/)から始まるパス)を使用します。疑問符は使用しません。

また、アイコンの幅と高さを含める必要があります。

例20-11に、アイコンのセレクタを示します。

例20-11 アイコンのセレクタ

.AFErrorIcon:alias {
content:url(/adf/images/error.png);
width:7px; height:18px
}

アイコンとボタンは両方とも、rtl疑似クラスを使用できます。これにより、アプリケーションが右から左へのモードで表示されるときに使用されるアイコンやボタンが定義されます。例20-12に、アイコンに使用されるrtl疑似クラスを示します。

例20-12 rtl疑似クラスを使用するアイコン・セレクタ

.AFErrorIcon:alias:rtl {
content:url(/adf/images/error.png);
width:16px; height:16px
}

20.3.3 メッセージへのスキンの適用方法

特定レベルのメッセージが関連付けられているかどうかに基づいて、ADF Faces入力コンポーネントにスタイルを適用できます。コンポーネントに特定タイプのメッセージが追加されると、そのコンポーネントのスタイルは、新しいステータスを反映するように自動的に変更されます。そのステータスにスタイルが定義されていない場合は、デフォルトのスタイルが使用されます。

関連付けられているメッセージ・レベルに基づいて入力コンポーネントにスタイルを定義するには、コンポーネント定義にスタイル疑似クラスを追加します。たとえば、af:inputTextコンポーネントのコンテンツ・リージョンのベース・スタイルを、背景色が紫になるように定義するには、スタイル・セレクタaf|inputText::content{background-color:purple}を使用します。エラー・メッセージがある場合のコンポーネントのコンテンツ・リージョンを定義するには、スキン・スタイル・セレクタaf|inputText:error::contentを使用します。

有効なメッセージ・プロパティは、:fatal、:error、:warning、:confirmationおよび:infoです。

20.3.4 コンポーネントへのテーマの適用方法

テーマは、コンポーネント・レベルのルック・アンド・フィールを実装する方法です。目的は、ページの一部分にある複数のコンポーネント全体に一貫したルック・アンド・フィールを提供することです。テーマは一般的には、特定領域の外観がそれぞれ異なるJSFページ・テンプレートに使用されます。たとえば、上部のブランド領域に暗い背景色と明るいテキストが使用され、より明るい背景色のナビゲーション・コンポーネントと、明るい背景色のメイン・コンテンツ領域があるページです。

テーマを設定するコンポーネントにより、子コンポーネントにそのテーマが公開されるため、テーマが継承されます。テーマは、次のコンポーネントにより設定(開始または変更)されます。

- af:document

- af:decorativeBox

- af:panelStretchLayout

- af:panelGroupLayout

FusionスキンおよびBLAF Plusスキン(blafplus-richおよびblafplus-medium)では、次のテーマがサポートされています。

- dark

- medium

- light

- none(デフォルト)

JSPXページにおいて、テーマは次に示すように、af:documentコンポーネントによって開始されます。

<af:document theme="dark">
<af:panelTabbed>...</af:panelTabbed>
</af:document>

コンポーネントにテーマを設定するには、CSSファイルのスキン・セレクタにtheme属性を指定します。たとえば、af:panelTabbedコンポーネントのテキストの色をdarkテーマに変更するセレクタは次のとおりです。

af|panelTabbed[theme="dark"] {
color: red;
}

子コンポーネントがJSPXページの親コンポーネントに対する変更を継承しないようにする場合は、CSSファイルで-tr-children-themeプロパティの値を設定します。たとえば、af:panelTabbed子コンポーネントがJSPXページのaf:document親コンポーネントに定義されているdarkテーマを継承しないようにするとします。次のように、CSSファイルの-tr-children-themeプロパティを設定します。

af|panelTabbed::content {
-tr-children-theme: default;
}

デフォルトでは、テーマはコンポーネントやその子コンポーネントには設定されていません。テーマは継承されるため、コンポーネントに設定されていないtheme属性がある場合には、次の値がサポートされます。

- 指定なし: テーマが指定されていない場合、<af:decorativeBox>...のようにテーマが継承されます。

- #{null}: 指定なしの場合と同じように、テーマが継承されます。

- inherit: nullの場合と同じように、テーマが継承されます。

- default: テーマは、コンポーネントおよびその子コンポーネントから削除されます。

- 空の文字列: テーマが空の文字列に設定されている場合は、defaultと同じように動作します。たとえば、<af:decorativeBox theme="">では、コンポーネントおよびその子コンポーネントからテーマが削除されます。

テーマがサポートされ、スタイル・クラスのあるコンポーネントのすべてのHTML要素にテーマが追加されるため、テーマの包含スタイルCSSセレクタは不要です。:ltrおよび:rtlを除いて、すべてのテーマ・セレクタは、必ずセレクタの最後の要素に含まれている必要があります。たとえば、af:breadCrumbsコンポーネントの各ステップにdarkテーマを適用するセレクタは次のとおりです。

af|breadCrumbs::step:disabled[theme="dark"] {
color:#FFFFFF;
}

コンポーネントの背景色が、周囲のテーマ色には不適切な色に設定されている場合、色の不適合が起こる場合があります。たとえば、panelHeaderコンポーネントがdarkテーマに配置されている場合、panelHeaderコンポーネント内のCSSスタイルにより、前景色は変更されずに、コンポーネントの背景色が明るい色に設定されます。その結果、コンポーネントは、明るい背景色で明るい前景色になります。その他多くのコンポーネントも、darkテーマに配置されると、前景色が明るい色に設定されます。

色の不適合が発生した場合は、-tr-children-themeプロパティの値を設定して、親コンポーネントと子コンポーネント間の色の不適合を解決できます。親子関係のないコンポーネントの場合は、コンポーネントのテーマ色を、周囲のテーマ色に対して適切な色に手動で設定できます。これを実行するには、コンポーネントにpanelGroupLayoutまたはpanelStretchLayoutコンポーネントを挿入し、panelGroupLayoutまたはpanelStretchLayoutのテーマを適切な色に設定します。

<af:panelHeader text="Header Level 0">
<af:panelGroupLayout layout="vertical" theme="default">
...
</af:panelGroupLayout>
</af:panelHeader>

20.3.5 カスタム別名の作成方法

独自の別名を作成してから、後で他のセレクタに含めることができます。

カスタム別名を作成する手順:

1. 別名のセレクタ・クラスを作成します。たとえば、マウス・カーソルが置かれたリンクの色を設定するために別名を追加できます。

.MyLinkHoverColor:alias {color: #CC6633;}

2. 別のセレクタに別名を含めるには、既存のセレクタに疑似要素を追加して新しいセレクタを作成し、-tr-rule-ref:selectorプロパティを使用してその別名を参照します。
たとえば、カーソルが置かれたときの色をスタイル設定するためにaf|menuBar::enabled-linkセレクタに対する新規のセレクタを作成してから、カスタム別名を参照できます(例20-13を参照)。

例20-13 新規セレクタ内のカスタム別名の参照

af|menuBar::enabled-link:hover
{
-rt-rule-ref:selector(".MyLinkHoverColor:alias");
}

20.3.6 スキンを動的に変更するためのコンポーネントの構成方法

スキンを動的に変更するようにコンポーネントを構成するには、最初にJSFページでコンポーネントを構成し、後で構成ファイルによる評価が可能なスコープの値を設定する必要があります。次に、この値によって動的に設定されるようにtrinidad-configファイルでスキン・ファミリを構成します。

スキン・ファミリを設定するためにコンポーネントを条件付きで構成する手順:

1. スキン・ファミリの設定に使用されるコンポーネントが含まれるメインのJSFページ(index.jspxまたは類似のファイルなど)を開きます。

2. sessionScopeコンポーネントを使用して、スキン・ファミリが表示されるようにページを構成します。
例20-14は、選択された値を取得し、この値をindex.jspxページにあるsessionScopeコンポーネントのskinFamily属性の値として設定するaf:selectOneChoiceコンポーネントを示しています。

例20-14 コンポーネントを使用したスキン・ファミリの設定

<af:selectOneChoice label="Choose Skin:" value="#{sessionScope.skinFamily}" autoSubmit="true">
<af:selectItem value="blafplus-rich" label="blafplus-rich"/>
<af:selectItem value="blafplus-medium" label="blafplus-medium"/>
<af:selectItem value="simple" label="simple"/>
<af:selectItem value="richDemo" label="richDemo"/>
<af:selectItem value="mySkin" label="mySkin"/>
</af:selectOneChoice>

ページの「リフレッシュ」ボタンにより、ページが再度送信されます。ページがリフレッシュされるたびにEL式が評価され、変更がある場合、新しいスキンを使用してページが再描画されます。

実行時にスキンを変更するためにコンポーネントを条件付きで構成する手順:

trinidad-config.xmlファイルで、EL式を使用してスキン・ファミリを動的に評価します。

<skin-family>#{sessionScope.skinFamily}</skin-family>

20.4 コンポーネントのスタイル・プロパティの変更

ADF Facesコンポーネントでは、Cascading Style Sheet(CSS)仕様に基づいてCSSスタイル・プロパティを使用しています。Cascading Style Sheetには、スタイルを適用する方法を定義するセレクタと宣言からなる規則が含まれます。これらのルールは後にブラウザにより解釈され、ブラウザのデフォルト設定をオーバーライドします。

警告:

コンポーネントを拡大するためにスタイルを使用しないでください。拡大を目的としたスタイルの使用は宣言的でなく、多くの場合、異なるWebブラウザ間で動作の一貫性がなくなります。かわりに、ADF Facesフレームワークに用意されているジオメトリ管理を使用して、コンポーネントを拡大します。レイアウトおよび拡大の詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

20.4.1 インライン・スタイルの設定方法

inlineStyle属性を定義して、コンポーネントにインライン・スタイルを設定します。インライン・スタイルは、コンポーネントのインスタンス用コンポーネントのスタイルの指定に使用できます。詳細は、8.3項「コンテンツをページ全体に拡大するための設定」を参照してください。

インライン・スタイルを設定する手順:

1. コンポーネントのinlineStyle属性を、使用するインライン・スタイルに設定します。

2. スタイルの設定にプロパティ・インスペクタを使用すると、図20-5に示すように、ドロップダウン・リストから必要なスタイル機能を選択できます。

図20-5 inlineStyleの設定

JDeveloperにより、コンポーネントの対応するコードがJSFページに追加されます。例20-15に、inlineStyle属性が指定されたaf:outputTextコンポーネントのソースを示します。

例20-15 ページ・ソースのinlineStyle

<af:outputText value="outputText1"
inlineStyle="color:Red; text-decoration:overline;"/>

3. inlineStyle属性自体にEL式を使用して、インライン・スタイル属性を条件付きで設定できます。たとえば、アクションがまだ完了していない場合に日付を赤で表示するには、例20-16のようなコードを使用できます。

例20-16 inlineStyle属性の設定に使用されるEL式

<af:outputText value="#{row.assignedDate eq
null?res['srsearch.unassignedMessage']:row.assignedDate}"
inlineStyle="#{row.assignedDate eq null?'color:rgb(255,0,0);':''}"/>

4. ADF Facesコンポーネントには、ルートDOM要素に登録されていないスタイル設定には使用できない、その他のスタイル属性もあります。たとえば、af:inputTextコンポーネントの場合、例20-17に示すように、contentStyleプロパティを使用して要素のテキストを設定します。

例20-17 contentStyleプロパティの使用

<af:inputText value="outputText1"
contentStyle="color:Red;"/>

20.4.2 スタイル・クラスの設定方法

スタイル・クラスを使用して、コンポーネントのスタイルを定義できます。スタイル・クラスは、一連のインライン・スタイルをグループ化するために作成します。

スタイル・クラスを使用してスタイルを設定する手順:

1. コンポーネントのstyleClass属性を、使用するスタイル・クラスに設定します。
例20-18に、ページ・ソースに使用されているスタイル・クラスの例を示します。

例20-18 スタイル・クラスを使用するためのページ・ソース

<af:outputText value="Text with a style class"
styleClass="overdue"/>

2. styleClass属性にEL式を使用して、スタイル属性を条件付きで設定できます。たとえば、アクションがまだ完了していない場合に日付を赤で表示するには、例20-16のようなコードを使用できます。

20.5 スキンのCSSファイルにおけるURLの参照

URLは、スキンのCSSファイルから様々なフォーマットで参照できます。サポートされているフォーマットは次のとおりです。

- 絶対
リソースの完全なURLを指定します。たとえば、次のようなフォーマットのURLです。

http://www.mycompany.com/WebApp/Skin/skin1/img/errorIcon.gif

- 相対
URLの先頭が/ではなく、プロトコルが示されていない場合は、相対URLを指定できます。相対URLは、スキンのCSSファイルの場所に基づいています。たとえば、スキンのCSSファイル・ディレクトリがWebApp/Skin/skin1/であり、指定されたURLがimg/errorIcon.gifの場合、最終的なURLは/WebApp/Skin/mySkin/img/errorIcon.gifとなります。

- コンテキスト相対
このURLのフォーマットは、Webアプリケーションのコンテキスト・ルートに対して相対的に解釈されます。コンテキスト相対ルートの先頭は/になります。たとえば、Webアプリケーションのコンテキスト相対ルートが次のとおりであるとします。

/WebApp

このとき、次のURLを指定したとします。

/img/errorIcon.gif

最終的なURLは次のようになります。

/WebApp/img/errorIcon.gif

- サーバー相対
サーバー相対URLは、Webサーバーに対して相対的に解釈されます。これがコンテキスト相対URLと異なるのは、同じWebサーバー上にある別のアプリケーション内のリソースを参照できることです。URLの先頭は//を使用して指定します。たとえば、次のフォーマットでURLを作成します。

//WebApp/Skin/mySkin/img/errorIcon.gif

20.6 カスタム・スキンのバージョニング

<version>要素を使用して、trinidad-skins.xmlファイルでカスタム・スキンのバージョン番号を指定できます。trinidad-skins.xmlファイル内の<family>要素の値が同じであるカスタム・スキンを区別する場合は、この機能を使用します。特定のカスタム・スキンを使用するようにアプリケーションを構成する場合は、アプリケーションへのカスタム・スキンの適用に関する項で説明されているように、trinidad-config.xmlファイルで値を指定して行うことに注意してください。

20.6.1 カスタム・スキンのバージョニング方法

trinidad-skins.xmlファイル内の<version>要素に値を入力して、カスタム・スキンのバージョンを指定します。

カスタム・スキンをバージョニングする手順:

1. アプリケーション・ナビゲータで、trinidad-skins.xmlファイルをダブルクリックします。これは、デフォルトではWeb Content/WEB-INFノードにあります。

2. 構造ウィンドウで、バージョニングするカスタム・スキンのskinノードを右クリックし、「skinの中に挿入」→「version」を選択します。

3. trinidad-config.xmlファイルの<skin-version>要素に値が指定されていない場合に、このバージョンのカスタム・スキンがアプリケーションで使用されるようにするには、アプリケーションへのカスタム・スキンの適用に関する項で説明されているように、バージョンの挿入のためのダイアログで、デフォルト・リストからtrueを選択します。

4. 名前フィールドに値を入力します。たとえば、カスタム・スキンの最初のバージョンである場合はv1と入力します。

5. 「OK」をクリックします。

20.6.2 カスタム・スキンをバージョニングした場合の処理

例20-19に、カスタム・スキンの3つのソース・ファイル(skin1.css、skin2.cssおよびskin3.css)を参照するtrinidad-skins.xmlの例を示します。これらの各カスタム・スキンの<family>要素は同じ値(test)になっています。<version>要素の子要素の値によって、これらのカスタム・スキンがそれぞれ区別されます。実行時に、アプリケーションのtrinidad-config.xmlファイルにおける<skin-family>要素の値としてtestが指定されたアプリケーションでは、skin3を使用します。これは、このカスタム・スキンがtrinidad-skins.xmlファイルでデフォルト・スキンとして構成されているためです(<default>true</default>)。この動作は、アプリケーションへのカスタム・スキンの適用に関する項で説明されているように、trinidad-config.xmlファイル内の<skin-version>要素に値を指定してオーバーライドできます。

例20-19 バージョニングされたカスタム・スキン・ファイルが含まれたtrinidad-skins.xml

<?xml version="1.0" encoding="windows-1252"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin>
<id>skin1.desktop</id>
<family>test</family>
<extends>simple.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/skin1/skin1.css</style-sheet-name>
<version>
<name>v1</name>
</version>
</skin>
<skin>
<id>skin2.desktop</id>
<family>test</family>
<extends>fusionFx-v1.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/skin2/skin2.css</style-sheet-name>
<version>
<name>v2</name>
</version>
</skin>
<skin>
<id>skin3.desktop</id>
<family>test</family>
<extends>fusion.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/skin3/skin3.css</style-sheet-name>
<version>
<default>true</default>
<name>v3</name>
</version>
</skin>
</skins>

20.7 JARファイルへのカスタム・スキン・ファイルのデプロイ

スキン定義をJavaアーカイブ(JAR)ファイルに保存し、デプロイ済アプリケーションに追加することが必要な場合があります。次に、アプリケーションにバンドルする場合と比較して、スキンをJARファイルにパッケージ化することの利点を示します。

- アプリケーションとは別に、スキンをデプロイおよび開発できます。これにより、スキンへの変更の適用が必要な場合に、確認するファイル数を減らすこともできます。一番の利点は、JARファイルに格納されたスキン定義を使用することで、アプリケーションのルック・アンド・フィールの一貫性が高まることです。

- スキン定義とイメージを、それぞれ独自のJARファイルに分割できます。そのため、すべてのアプリケーションに全ファイルをデプロイする必要がないように、イメージ・ベースを別々のJARファイルに分けられます。

JARファイルにスキンをデプロイするには、次のルールに従います。

- スキンを定義し、CSSファイルを参照するtrinidad-skins.xmlファイルは、META-INFディレクトリに内に存在する必要があります。

- すべてのイメージ・リソースおよびCSSファイルも、META-INFディレクトリに配置する必要があります。例20-20に示すように、イメージは、adfルート・ディレクトリ、またはリソース・サーブレットのweb.xmlファイルにマップされている任意のディレクトリ名で始まるディレクトリに存在する必要があります。

- JARファイルは、デプロイするアプリケーションのビュー・レイヤー・プロジェクトのWEB-INF/libディレクトリに配置する必要があります(または、アプリケーション・サーバー・レベルの共有ライブラリを使用する必要があります)。

例20-20 パスが含まれるweb.xmlファイル

<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>

JARファイルにスキンをデプロイする手順:

1. 次のようなディレクトリ構造を作成します。

c:\temp\META-INF\adf\oracle\skin\images
META-INF\skins\fusion.css
META-INF\trinidad-skins.xml

2. META-INFディレクトリのディレクトリがadfで始まることを確認します。imagesディレクトリには、oracleblaf.cssスキン内に使用されたすべてのイメージが含まれます。イメージへのCSS参照のパスは、次のようになります。

af|inputColor::launch-icon:rtl {
content:url(../adf/oracle/skin/images/cfsortl.png);
width: 12; height: 12;
left:-7px;
position:relative;
right:-7px;
top:5px;
}

イメージ・パス../adf/oracle/skin/images/cfsortl.pngの先頭にある2つのピリオドに注意してください。これにより、CSSが存在するMETA-INF/skinディレクトリの1つ上のディレクトリから、META-INFルートの検索を開始できます。

3. trinidad-skins.xmlファイルがMETA-INFディレクトリに存在し、次のような形式でコンテンツが含まれることを確認してください。

<?xml version="1.0" encoding="ISO-8859-1"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin>
<id>richdemo.desktop</id>
<family>richDemo</family>
<extends>fusion.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/richdemo/richdemo.css</style-sheet-name>
</skin>
</skins>

この例では、richDemoファミリのrichdemo.desktopとしてスキンが定義されています。trinidad-skins.xmlファイルには、複数のスキン定義を含めることが可能です。richdemo.cssファイル(またはカスタムのCSSファイル)は、style-sheet-name要素から参照されます。

4. JARファイルを作成するには、c:\tempディレクトリから次のコマンドを発行します。

jar -cvf customSkin.jar META-INF/

5. 結果のcustomSkin.jarファイルを、使用するADFプロジェクトのWEB-INF/libディレクトリにコピーします。ADFプロジェクトのWEB-INFディレクトリにあるtrinidad-skins.xmlファイルを構成します。

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>oracleblaf</skin-family>
</trinidad-config>

スキンは実行時に検出されるため、スキンのファミリ名のコードを記述する必要はありません。

注意:

JARファイルのスキン定義は、JDeveloperのビジュアル・エディタに表示されません。ログ・ウィンドウに、スキン・ファミリが見つからなかったというメッセージが表示されます。このメッセージは無視できます。

21 ページの国際化およびローカライズ

この章では、ユーザーのブラウザの適切な言語でテキストが表示されるように、JSFページまたはアプリケーションを構成する方法を説明します。

この章では、次の項目について説明します。

- 21.1項「ADF Facesページの国際化およびローカライズの概要」

- 21.2項「JDeveloperにおける自動リソース・バンドル統合の使用」

- 21.3項「リソース・バンドルおよびロケールの手動での定義」

- 21.4項「エンド・ユーザーが実行時にロケールを指定するページの構成」

- 21.5項「ADF Facesのオプションのローカライゼーション・プロパティの構成」

21.1 ADF Facesページの国際化およびローカライズの概要

国際化は、特定地域の言語と文化に適応しやすくするための、製品の設計および開発のプロセスです。ローカライズは、テキストを翻訳し、ロケール固有のコンポーネントを追加することで、特定地域の言語または文化に製品を適応するプロセスです。上手くローカライズされたアプリケーションは、その地域で開発されたように見えます。JDeveloperは、抽象クラスjava.util.ResourceBundleを使用してロケール固有のリソースを提供し、ADF Facesコンポーネントをローカライズしやすいようにサポートします。

複数の国のユーザーがアプリケーションを表示する場合、ユーザーのブラウザの言語設定に対応する適切な言語が表示されるよう、様々なロケールを使用できるようにJSFページまたはアプリケーションを構成できます。たとえば、ページがイタリアで表示されるとわかっている場合、ユーザーのブラウザがイタリア語を使用するように設定されているときにはブラウザ・ページ内のテキスト文字列がイタリア語で表示されるように、ページをローカライズできます。

ADF Facesコンポーネントは、コンポーネントの一部であるテキストを含むことがあります。たとえば、データの初期ロード中にテーブルがデータをフェッチしているとき、またはテーブルがスクロールされているときに、af:tableコンポーネントでは、ブラウザで表示されるメッセージ・テキストにリソース文字列af_table.LABEL_FETCHINGが使用されます。JDeveloperでは、これらのテキスト・リソースの28言語への自動変換が提供されます。これらのテキスト・リソースは、リソース・バンドルで参照されます。ユーザーがイタリア語を使用するようにブラウザを設定した場合、コンポーネント内に含まれるテキストはすべて自動的にイタリア語で表示されます。スキンおよびリソース・バンドルの使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

text属性を設定してaf:commandButtonコンポーネントのラベルを定義する場合など、コンポーネントに追加するテキストには、実際のテキストが含まれているリソース・バンドルを指定し、各ロケール版のリソース・バンドルを作成し、<locale-config>要素を追加して、アプリケーションのfaces-config.xmlファイルにデフォルトおよびサポートされるロケールを定義する必要があります。また、アプリケーションのすべてのページでリソース・バンドルを使用できるようにするには、アプリケーションのfaces-config.xmlファイルに<resource-bundle>要素を追加する必要があります。リソース・バンドルを構成および登録すると、式言語(EL)エディタによりバンドルのキーが表示され、アプリケーション・ページでのバンドルの参照が簡単になります。

ADFコンポーネントに追加するテキストのテキスト・リソースを作成するプロセスを簡略化するために、JDeveloperでは、ビジュアル・エディタの変換可能な文字列に関する、リソース・バンドルの自動同期がサポートされています。ビジュアル・エディタまたはプロパティ・インスペクタで直接コンポーネントを編集すると、ベース・リソース・バンドルにテキスト・リソースが自動的に作成されます。

注意:

データベースから取得されたテキストは変換されません。このドキュメントでは、静的テキストのローカライズ方法については説明しますが、データベース内に格納されているテキストのローカライズ方法については説明しません。

たとえば、このページのタイトルが「My Purchase Requests」の場合、af:panelPageコンポーネントのtitle属性の値として「My Purchase Requests」を指定するのではなく、この値をUIResourcesリソース・バンドル内のキーにバインドしています。例21-1に示すように、UIResourcesリソース・バンドルは、アプリケーションのfaces-config.xmlファイルに登録されます。

例21-1 JSF構成ファイルのリソース・バンドル要素

<resource-bundle>
<var>res</var>
<base-name>resources.UIResources</base-name>
</resource-bundle>

リソース・バンドルには、EL式に使用可能な変数名(この場合はres)が提供されます。例21-2に示すように、ページでは、af:panelPageコンポーネントのtitle属性が、そのリソース・バンドル内のmyDemo.pageTitleキーにバインドされます。

例21-2 リソース・バンドルを参照するコンポーネント・テキスト

<af:panelPage text="#{res['myDemo.pageTitle']}"

UIResourcesリソース・バンドル内には、アプリケーションの各ページに表示されるすべての静的テキスト、メッセージのテキスト、グローバル・テキスト(汎用ラベルなど)に対する英語のエントリがあります。例21-3に、myDemoページのキーを示します。

例21-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

バナー・イメージのテキストおよびデータベースから取得されたデータは変換されないことに注意してください。

例21-4に、イタリア語ロケール・バージョンのリソース・バンドル(UIResources_it)を示します。選択ファセットのタイトルに対するエントリがないのに、「Select」が自動的に「Seleziona」に変換されていることに注意してください。これは、このテキストがADF Faces表コンポーネントの選択ファセットの一部になっているためです。

例21-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

21.2 JDeveloperにおける自動リソース・バンドル統合の使用

ビジュアル・エディタでADF Facesコンポーネントを編集する際、JDeveloperでは、デフォルトのリソース・バンドルへのテキスト・リソースの自動作成がデフォルトでサポートされています。ユーザー定義の文字列を静的な値として扱うには、リソース・バンドル・オプションの設定方法に関する項で説明されているように、「プロジェクト・プロパティ」ダイアログで「バンドルの自動同期化」を無効にします。

自動リソース・バンドル統合は、ページまたはプロジェクトごとに1つのリソース・バンドル、または複数の共有バンドルをサポートするように構成できます。

ユーザーは、次のいずれかの方法で変換可能なテキスト文字列を編集できます。

- ビジュアル・エディタで、コンポーネントに直接新しいテキストを入力します。図21-1に示すように、コンポーネントをクリックして、テキスト入力ウィンドウを表示します。

図21-1 コンポーネントへのテキストの追加

- 図21-2に示すように、テキスト入力ウィンドウで「テキスト・リソースの選択」を選択し、「テキスト・リソースの選択」ダイアログを起動します。このダイアログには、コンポーネントを右クリックして「テキスト・リソースの選択」を選択するか、プロパティ・インスペクタで変換可能プロパティの右にあるアイコンをクリックして「テキスト・リソースの選択」を選択することでも起動できます。

図21-2 「テキスト・リソースの選択」ダイアログ

- テキスト入力ウィンドウで、「式ビルダー」を選択して「式ビルダー」ダイアログを起動します。このダイアログは、プロパティ・インスペクタで、変換可能なプロパティの右にあるアイコンをクリックして「式ビルダー」を選択することでも起動できます。

- プロパティ・インスペクタで、変換可能なプロパティに有効な式言語文字列を入力します。

注意:

JDeveloperでは、前述の方法のいずれかを使用して入力したリソース・バンドルのみに文字列が書き込まれます。

21.2.1 リソース・バンドル・オプションの設定方法

プロジェクトの作成後、「プロジェクト・プロパティ」ダイアログにリソース・バンドル・オプションを設定できます。

プロジェクトにリソース・バンドル・オプションを設定する方法:

1. アプリケーション・ナビゲータで、プロジェクトをダブルクリックします。

2. 図21-3に示すように、「プロジェクト・プロパティ」ダイアログで、「リソース・バンドル」を選択してリソース・バンドル・オプションを表示します。

図21-3 「プロジェクト・プロパティ」の「リソース・バンドル」ダイアログ

3. JDeveloperにより自動的にデフォルトのリソース・ファイルが生成されるようにする場合は、「バンドルの自動同期化」を選択します。

4. 次に示すいずれかのリソース・バンドル・ファイル・オプションを選択します。

- 1プロジェクト当たり1バンドル: <ProjectName>.propertiesという名前のファイルに構成されます。

- 1ページ当たり1バンドル: <ProjectName>.propertiesという名前のファイルに構成されます。

- 複数の共有バンドル。

5. ドロップダウン・リストからリソース・バンドル・タイプを選択します。

- XML Localization Interchange File Format(XLIFF)バンドル

- リスト・リソース・バンドル

- プロパティ・バンドル

6. 「OK」をクリックします。

21.2.2 リソース・バンドル・オプションを設定した場合の処理

JDeveloperでは、図 21-3に示されている「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプション部分で選択した内容に基づいて、特定のタイプのリソース・バンドルが1つ以上生成されます。図21-2に示されている「テキスト・リソースの選択」ダイアログを最初に開いたときに、リソース・バンドルが生成されます。

たとえば、「リソース・バンドル・タイプ」ドロップダウン・リストから、「1プロジェクト当たり1バンドル」チェック・ボックスおよび「リスト・リソース・バンドル」値を選択したとします。「テキスト・リソースの選択」ダイアログを最初に開いたとき、JDeveloperでは、プロジェクトにリソース・バンドルが1つ生成されます。生成されたリソース・バンドルは、「プロジェクト・プロパティ」ダイアログのデフォルト・プロジェクト・バンドル名から名付けられたJavaクラスです(たとえば、ViewControllerBundle.javaなど)。

XML Localization Interchange File Format (XLIFF)バンドル・オプションを選択した場合、JDeveloperでは、リソース・バンドルが.xlfファイルとして生成されます。「プロパティ・バンドル」オプションを選択した場合は、.propertiesファイルとして生成されます。

デフォルトでは、JDeveloperにより、プロジェクトのアプリケーション・ソース・ディレクトリのビュー・サブディレクトリに生成済リソース・バンドルが作成されます。

21.2.3 JDeveloperで生成されたリソース・バンドルにエントリを作成する方法

JDeveloperでは、「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプション部分で選択した値に基づいて、リソース・バンドルが1つ以上生成されます。プロパティ・インスペクタのコンポーネント・プロパティから「テキスト・リソースの選択」ダイアログを最初に開いたときに、リソース・バンドルが生成されます。

JDeveloperでは、「テキスト・リソースの選択」ダイアログで入力した値に基づいて、リソース・バンドルにキーと値のペアが書き込まれます。これにより、既存のキーと値のペアをリソース・バンドルから選択して、コンポーネントにランタイム表示値をレンダリングすることもできます。

JDeveloperによって生成されたリソース・バンドルにエントリを作成する手順:

1. JSFページで、ランタイム値を書き込むコンポーネントを選択します。
たとえば、af:inputTextコンポーネントを選択します。

2. プロパティ・インスペクタで、プロパティのドロップダウン・リストを使用して、「テキスト・リソースの選択」を選択し、リソース・バンドルに新規エントリを作成します。
「テキスト・リソースの選択」エントリは、テキスト・リソースをサポートするプロパティのみに対して、ドロップダウン・リストに表示されます。たとえば、af:inputTextコンポーネントのLabelプロパティなどです。

3. 図21-2に示すように、「表示値」入力フィールドで実行時に表示する値を書き込みます。
JDeveloperにより、「キー」入力フィールドの値が生成されます。

4. 必要に応じて、「説明」入力フィールドに説明を書き込みます。

注意:

「表示値」フィールドに入力した値と一致するテキスト・リソースが存在する場合、JDeveloperにより、「一致するテキスト・リソース」フィールドに、一致するテキスト・リソースが表示されます。

5. 「保存して選択」をクリックします。

21.2.4 JDeveloperで生成されたリソース・バンドルにエントリを作成した場合の処理

JDeveloperでは、「テキスト・リソースの選択」ダイアログで定義するキーと値のペアをリソース・バンドルに対して書き込みます。「プロジェクト・プロパティ」ダイアログのリソース・バンドル・オプション部分で選択するオプションにより、JDeveloperがキーと値のペアを書き込むリソース・バンドルのタイプが決まります。詳細は、リソース・バンドル・オプションを設定した場合の処理に関する項を参照してください。

リソース・バンドル・エントリを定義するコンポーネント・プロパティは、EL式を使用して実行時にリソース・バンドルから値を取得します。たとえば、af:inputTextコンポーネントのラベル・プロパティは、次のようにEL式を参照することがあります。

#{viewcontrollerBundle.NAME}

ここで、viewcontrollerBundleはリソース・バンドルを参照します。NAMEはランタイム値のキーです。

21.3 リソース・バンドルおよびロケールの手動での定義

リソース・バンドルには多数の名前付きリソースが含まれます。名前付きリソースのデータ型はStringです。バンドルは、親バンドルを持つことがあります。リソースがバンドルにない場合、親バンドルでリソースが検索されます。リソース・バンドルは、Javaクラス、プロパティ・ファイルまたはXLIFFファイルのいずれかです。抽象クラスjava.util.ResourceBundleには、java.util.PropertyResourceBundleおよびjava.util.ListResourceBundleの2つのサブクラスがあります。ava.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 オブジェクトをava.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エラーがスローされます。接尾辞のないベース・クラスが、デフォルトとして常に存在している必要があります。存在しない場合は一致が検出されず、例外がスローされます。

21.3.1 ベース・リソース・バンドルの定義方法

コンポーネント自体の一部になっていない、すべてのテキスト文字列が含まれたベース・リソース・バンドルを作成する必要があります。このバンドルは、アプリケーションのデフォルト言語で作成する必要があります。リソース・バンドルは、プロパティ・ファイル、XLIFFファイルまたはJavaクラスとして作成できます。リソース・バンドル・ファイルを作成したら、「リソース・バンドルの編集」ダイアログを使用してファイルを編集できます。

リソース・バンドルをプロパティ・ファイルまたはXLIFFファイルとして作成する手順:

1. JDeveloperで、新規ファイルを作成します。

- アプリケーション・ナビゲータで、ファイルの保存場所を右クリックし、ポップアップ・メニューから「新規」を選択して「新規ギャラリ」を開きます。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、ベース・ファイルと同じディレクトリにファイルを保存してください。

- 「カテゴリ」ツリーで「一般」を選択し、「項目」リストで「ファイル」を選択します。「OK」をクリックします。

- 「ファイルの作成」で、プロパティ・ファイルを使用するファイルには表記規則<name><_lang>.propertiesを使用して、XLIFFファイルを使用するファイルには表記規則<name><_lang>.xlfを使用して、ファイルの名前を入力します。<_lang>接尾辞(ドイツ語では_deなど)は翻訳したファイルに付けられ、元となる言語では省略されます。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、ファイル名にISO 639の小文字の言語コードを追加する必要があります。たとえば、UIResourcesバンドルのイタリア語バージョンは、UIResources_it.propertiesになります。複数の国で1つの言語を使用する場合は、ISO 3166の大文字の国コードを追加できます(たとえば、スイスの場合はit_CH)。また、オプションの非標準バリアント(たとえば、プラットフォームや地域の情報を提供するバリアント)を追加することもできます。

ベース・リソース・バンドルを作成する場合は、コードを追加しないでください。

2. ファイルにコンテンツを入力します。キーと値のペアを入力することで、コンテンツを手動で入力できます。21.3.2項「リソース・バンドル・ファイルの編集方法」で説明されているように、「リソース・バンドルの編集」ダイアログを使用してキーと値のペアを入力できます。

- プロパティ・ファイルを作成している場合は、このバンドルの静的テキストの文字列ごとに、キーと値を作成します。キーは、文字列の一意の識別子です。値は、バンドルの言語でのテキスト文字列です。ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、このバージョン内に存在しないキーは、ベース・クラスから値を継承します。

注意:

非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>

3. すべての値を入力したら、「OK」をクリックします。

リソース・バンドルをJavaクラスとして作成する手順:

1. JDeveloperで、新規Javaクラスを作成します。

- アプリケーション・ナビゲータで、ファイルの保存場所を右クリックし、「新規」を選択して「新規ギャラリ」を開きます。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、これをベース・ファイルと同じディレクトリに保存する必要があります。

- 「カテゴリ」ツリーで「一般」を選択し、「項目」リストで「Javaクラス」を選択します。「OK」をクリックします。

- 「Javaクラスの作成」ダイアログで、クラスの名前とパッケージを入力します。クラスはjava.util.ListResourceBundleを拡張している必要があります。

注意:

ベース・リソース・バンドルのローカライズ済バージョンを作成する場合は、クラス名にISO 639の小文字の言語コードを追加する必要があります。たとえば、UIResourcesバンドルのイタリア語バージョンは、UIResources_it.javaになります。複数の国で1つの言語を使用する場合は、ISO 3166の大文字の国コードを追加できます(たとえば、スイスの場合はit_CH)。また、オプションの非標準バリアント(たとえば、プラットフォームや地域の情報を提供するバリアント)を追加することもできます。

ベース・リソース・バンドルを作成する場合は、コードを追加しないでください。

2. キーと値の組の配列を戻すのみのgetContents()メソッドを実装します。適切な値を使用して、バンドルのキーの配列を作成します。または、21.3.2項「リソース・バンドル・ファイルの編集方法」で説明されているように、「Edit Resource Bundles」ダイアログを使用して自動的にコードを生成します。例21-5に、ベース・リソース・バンドルのJavaクラスを示します。

注意:

キーはStringオブジェクトであることが必要です。ベース・リソース・バンドルのローカライズ済バージョンを作成する場合、このバージョン内に存在しないキーは、ベース・クラスから値を継承します。

例21-5 ベース・リソース・バンドルのJavaクラス

package sample;

import java.util.ListResourceBundle;

public class MyResources extends ListResourceBundle {
public Object[][] getContents() {
return contents;
}
static final Object[][] contents {
{"button_Search", Search"},
{"button_Reset", "Reset"},
};
}

21.3.2 リソース・バンドル・ファイルの編集方法

リソース・バンドル・プロパティ・ファイル、XLIFFファイルまたはJavaクラス・ファイルを作成したら、ソース・エディタを使用して編集できます。

リソース・バンドルの作成後に編集する手順:

1. JDeveloperで、メイン・メニューから「アプリケーション」→「リソース・バンドルの編集」を選択します。

2. 「リソース・バンドルの編集」ダイアログで、図21-4に示されているように、「リソース・バンドル」ドロップダウン・リストから編集するリソース・バンドル・ファイルを選択します。または、「検索」アイコンをクリックして、「リソース・バンドルの選択」ダイアログを起動します。

図21-4 「リソース・バンドルの編集」ダイアログ

3. 「リソース・バンドルの選択」ダイアログで、「ファイル・タイプ」ドロップダウン・リストからファイル・タイプを選択します。図21-5に示すように、編集するリソース・バンドルに移動します。「OK」をクリックします。

図21-5 「リソース・バンドルの選択」ダイアログ

4. 「リソース・バンドルの編集」ダイアログで、図21-6に示すように、「追加」アイコンをクリックしてキーと値のペアを追加します。完了したら「OK」をクリックします。

図21-6 リソース・バンドルへの値の追加

21.3.3 アプリケーションのロケールおよびリソース・バンドルの登録方法

アプリケーションで使用されるロケールおよびリソース・バンドルをfaces-config.xmlファイルに登録する必要があります。

アプリケーションのロケールを登録する手順:

1. faces-config.xmlファイルを開き、エディタ・ウィンドウで「概要」タブをクリックします。faces-config.xmlは、<View_Project>/WEB-INFディレクトリにあります。

2. エディタ・ウィンドウ内で「アプリケーション」を選択します。

3. 図21-7に示すように、「ロケール構成」領域で、「追加」をクリックしてプロパティ・インスペクタを開き、ロケール用のコードを追加します。

図21-7 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>

リソース・バンドルを登録する手順:

1. faces-config.xmlファイルを開き、エディタ・ウィンドウで「概要」タブをクリックします。faces-config.xmlは、<View_Project>/WEB-INFディレクトリにあります。

2. エディタ・ウィンドウ内で「アプリケーション」を選択します。

3. 「リソース・バンドル」セクションで、「追加」をクリックしてエディタ入力を有効化します。図21-8に示すように、アプリケーションにより使用されるメッセージが含まれたベース・バンドルの完全修飾名、およびEL式でバンドルの参照に使用できる変数名を入力します。

図21-8 faces-config.xmlへのリソース・バンドルの追加

リソース・バンドルを追加したら、faces-config.xmlファイルのコードは次のようになります。

<resource-bundle>
<base-name>oracle.fodemo.storefront.StoreFrontUIBundle</base-name>
<var>res</var>
</resource-bundle>

21.3.4 アプリケーションでのリソース・バンドルの使用方法

JSF 1.2では、アプリケーションの各ページに、<f:loadBundle>タグを使用してベース・リソース・バンドルをロードする必要はありません。

ページ上でベース・リソース・バンドルを使用する手順:

1. ページ・エンコーディングとレスポンス・エンコーディングを、サポートされているすべての言語のスーパーセットに設定します。エンコーディングが設定されていない場合、ページ・エンコーディングはデフォルトで、ページ・ディレクティブのcontentType属性を使用して設定されたレスポンス・エンコーディングの値に設定されます。例21-6に、サンプル・ページのエンコーディングを示します。

例21-6 ページおよびレスポンスのエンコーディング

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces"
xmlns:afc="http://xmlns.oracle.com/adf/faces/webcache">
<jsp:output omit-xml-declaration="true" doctype-root-element="HTML"
doctype-system="http://www.w3.org/TR/html4/loose.dtd"
doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"/>
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>

ヒント:

デフォルトでは、JDeveloperによりページ・エンコーディングはwindows-1252に設定されます。デフォルトを別のページ・エンコーディングに設定するには、次のようにします。

1. メニューから「ツール」→「設定」を選択します。

2. 左側のペインで「環境」を選択します(まだ選択されていない場合)。

3. 「エンコーディング」を優先されるデフォルトに設定します。

2. <resource-bundle>要素用にfaces-config.xmlファイルに定義されている変数を使用して、ページ上に表示される静的テキストの文字列を表すすべての属性を、リソース・バンドル内の適切なキーにバインドします。例21-7に、myDemoページの「View」ボタンのコードを示します。

例21-7 リソース・バンドルへのバインド

<af:commandButton text="#{res['myDemo.buttonbar.view']}"
. . . />

ヒント:

ソース・エディタで次の構文を入力すると、JDeveloperでは、リソース・バンドルの文字列に解決されるキーのドロップダウン・リストが表示されます。

<af:commandButton text="#{res.

ドロップダウン・リストからキーを選択すると、JDeveloperでは、EL式が完成されます。

3. adfBundleキーワードを使用して、特定のリソース・バンドルのリソース文字列をJSFページのEL式として解決することもできます。
使用する形式は、#{adfBundle[ bundleID ] [ resource_Key ]}です。bundleIDは、project.EmpMsgBundleなどの完全修飾されたバンドルIDで、resource_Keyは、Deptno_LABELなどのバンドルのリソース・キーです。例21-8に、adfBundleを使用して、特定のリソース・バンドルからリソース文字列を持つボタン・テキストを表示する方法を示します。

例21-8 adfBundleを使用したバインディング

<af:commandButton text="#{adfBundle['project.EmpMsgBundle'] ['Deptno_LABEL']}"

21.3.5 カスタム・スキンおよびコントロール・ヒントについて

カスタム・スキンを使用する場合で、そのスキンのカスタム・リソース・バンドルを作成した場合は、そのリソース・バンドルのローカライズ済バージョンも作成する必要があります。同様に、コントロール・ヒントを使用してテキストを設定するアプリケーションの場合は、そのテキストに対して生成されたリソース・バンドルのローカライズ済バージョンを作成する必要があります。

21.3.6 カスタマイズ可能なアプリケーションでのリソース・バンドルのオーバーライドについて

Oracle Metadata Services (MDS)フレームワークを使用して、カスタマイズ可能なアプリケーションを開発し、ベース・リソース・バンドルからキーと値のペアをオーバーライドするリソース・バンドル(オーバーライド・バンドル)を作成する場合、アプリケーションのadf-config.xmlファイルを構成して、ベース・リソース・バンドルのオーバーライドをサポートする必要があります。オーバーライド・バンドルは、カスタマイズ可能なアプリケーションで使用するベース・リソース・バンドルと異なるキーと値のペアが含まれるリソース・バンドルです。たとえば、oracle.demo.CustAppUIBundleという名前のベース・バンドルがある場合、例21-9に示すように、アプリケーションのadf-config.xmlファイルのエントリを構成して、これをオーバーライド可能にします。オーバーライド済としてマークされると、バンドルのカスタマイズがアプリケーションのオーバーライド・バンドルに格納されます。

例21-9 adf-config.xmlファイルのオーバーライド・バンドルのエントリ

<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.xmlファイルの詳細は、adf-config.xmlでの構成に関する項を参照してください。MDSを使用したカスタマイズ可能なアプリケーションの作成の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「MDSを使用したアプリケーションのカスタマイズ」の章を参照してください。

21.4 エンド・ユーザーが実行時にロケールを指定するページの構成

エンド・ユーザーのブラウザのロケール設定が実行時のロケールを決定するデフォルトの動作ではなく、エンド・ユーザーが実行時にロケールを指定できるように、アプリケーションを構成できます。アプリケーションでユーザーが優先するロケールを指定し、その内容を保存する場合、この機能を実装します。

21.4.1 エンド・ユーザーがロケールを指定するページの構成方法

新しいページを作成するか、既存のページを開きます。次のようにこれを構成します。

- ロケール情報を格納するバッキングBeanを参照します。

- バッキングBeanでロケール情報を更新するために、エンド・ユーザーが実行時にコントロールを起動します。

- f:viewタグのlocale属性がバッキングBeanを参照します。

エンド・ユーザーがロケールを指定するページを構成する手順:

1. ロケール情報を格納するバッキングBeanを使用してページを作成します。
詳細は、JSF JSPページを作成する方法に関する項を参照してください。

2. エンド・ユーザーがロケールを変更するために使用できるコントロール(selectOneChoiceコンポーネントなど)を指定します。
たとえば、コンポーネント・パレットの「共通コンポーネント」パネルから、ページに「選択肢を1つ選択」をドラッグ・アンド・ドロップします。

3. 次の例に示すように、ロケール値を格納するバッキングBeanにコントロールをバインドします。

<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. プロパティ・インスペクタで、locale属性の横のドロップダウン・メニューを使用して「式ビルダー」を開きます。

3. 図21-9に示すように、式ビルダーを使用してバッキングBeanのロケール値にバインドします。

図21-9 locale属性をバッキングBeanにバインドする式ビルダー

5. ページを保存します。

21.4.2 ロケール指定するページを構成した場合の処理

JDeveloperでは、ロケールを変更するために使用するコマンド・コンポーネントのバッキングBeanへの参照が生成されます。例21-10に、selectOneChoiceコンポーネントを使用する例を示します。

例21-10 バッキング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で必要なメソッドも生成されます。例21-11に、例21-10にも対応するバッキングBeanの抜粋を示します。

例21-11 ロケールを変更するバッキング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;
}
...
}

21.4.3 エンド・ユーザーがロケールを指定した場合の実行時の処理

実行時に、エンド・ユーザーは、アプリケーションのロケールを変更するように構成したコマンド・コンポーネントを起動します。バッキングBeanには、更新したロケール情報が格納されます。f:viewタグのlocale属性がバッキングBeanを参照するページが、エンド・ユーザーによって指定されたロケールを使用して、レンダリングされます。

エンド・ユーザーによって指定されるロケールは、アプリケーションに登録する必要があります。ロケールおよび関連付けられたリソース・バンドルの指定の詳細は、アプリケーションのロケールおよびリソース・バンドルの登録方法に関する項を参照してください。

21.5 ADF Facesのオプションのローカライゼーション・プロパティの構成

ADF Facesでは、テキスト変換だけでなく、他のタイプ(テキストの向きや通貨コードなど)の変換も自動的に提供されます。アプリケーションにより、ユーザーの選択したロケールに基づいて、自動的に適切に表示されます。ただし、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を使用して、デフォルトのページ・レンダリング方向を明示的に設定できます。

- <time-zone>: 選択されたロケールに適切なタイムゾーンを定義します。ADF Facesでは自動的に、クライアント・ブラウザで使用されているタイムゾーンが使用されます。この値は、oracle.adf.view.faces.converter.DateTimeConverterによってStringからDateへの変換時に使用されます。

- <formatting-locale>: 選択されたロケールに適切な日付および数値の書式を定義します。ADF FacesおよびTrinidadは、デフォルトで、ローカライズされたテキストに使用されているロケールと同じロケールの日付と数値の書式を設定します。日付と数値を別のロケールで書式設定する場合、IANA形式のロケール(ja、fr-CAなど)を使用できます。この要素の内容は、IANA文字列を指すEL式またはjava.util.Localeオブジェクトです。

21.5.1 オプションのローカライゼーション・プロパティの構成方法

trinidad-config.xmlファイルに要素を入力することで、オプションのローカライゼーション・プロパティを構成できます。

オプションのローカライゼーション・プロパティを構成する手順:

1. trinidad-config.xmlファイルを開きます。このファイルは、<View_Project>/WEB-INFディレクトリにあります。

2. コンポーネント・パレットから、ファイルに追加する要素を構造ウィンドウ内にドラッグします。空の要素がページに追加されます。

3. 目的の値を入力します。

例21-12に、オプションのローカライゼーション要素すべてが設定されたtrinidad-config.xmlファイルのサンプルを示します。

例21-12 通貨コードおよび数値と小数点のセパレータの構成

<!-- 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>

22 アクセス可能なADF Facesページの開発

この章では、キーボードのショートカット、およびコンポーネント名や状態に関するテキストの説明を含むアクセシビリティ・サポートを、ADF Facesコンポーネントに追加する方法を説明します。部分ページ・レンダリング、スクリプト、スタイル、特定ページおよびナビゲーション構造を使用するADFページのアクセシビリティ・ガイドラインについても説明されています。

この章では、次の項目について説明します。

- 22.1項「アクセス可能なADF Facesページの概要」

- 22.2項「アクセシビリティ・プリファレンスの表示」

- 22.3項「コンポーネントレベルのアクセシビリティ・プロパティの指定」

- 22.4項「アクセス可能なページの作成」

- 22.5項「アクセシビリティ監査ルールの実行」

22.1 アクセス可能なADF Facesページの概要

アクセシビリティとは、弱視や全盲、難聴またはその他の身体的な制限などの障害を持つユーザーが、アプリケーションを使用できるようにすることです。つまり、マウスなし(キーボードのみ)で使用でき、全盲または弱視のユーザーはスクリーン・リーダーを使用でき、音、色またはアニメーションやタイミングに依存せずに使用できるアプリケーションを作成することです。

Oracleソフトウェアには、米国の508条およびWeb Content Accessibility Guidelines (WCAG) 1.0 AA標準が適用されています。これらの標準は、http://www.oracle.com/accessibility/standards.htmlで解説されています。

クライアント側のスクリプト、特に非同期のJavaScriptおよびXML(AJAX)を使用した場合に生じていたフレームワークとプラットフォームのさらなる問題は、オラクル社のアクセシビリティ・ストラテジで対応しています。

ADF Facesのユーザー・インタフェース・コンポーネントには、視覚的および身体的な障害のあるユーザーのために、組込みのアクセシビリティ・サポートが用意されています。スクリーン・リーダーのような非視覚的なメディアへのレンダリングを行うWebブラウザなどのユーザー・エージェントにより、コンポーネントのテキスト説明が読み上げられ、障害を持つユーザーに有益な情報が提供されます。アクセス・キー・サポートは、キーボードのみを使用してコンポーネントやリンクにアクセスする代替の方法を提供します。ADF Facesのアクセシビリティ監査ルールにより、アクセス可能なHTMLマークアップを使用して、アクセス可能なイメージ、表、フレーム、フォーム、エラー・メッセージおよびポップアップ・ウィンドウの作成が指示されています。

提供されているコンポーネント、ページやナビゲーション構造に対するADF Facesのアクセシビリティ・ガイドラインに従うのは便利ですが、アクセシビリティ標準に関する理解を深めることや、支援技術を使用したアクセシビリティのテスト実行のかわりにはなりません。

22.2 アクセシビリティ・プリファレンスの表示

ADF Facesには、2つのレベルのアプリケーション・アクセシビリティ・サポートが、<accessibility-mode>要素を使用してtrinidad-config.xmlファイルに構成されています。<accessibility-mode>に使用可能な値は次のとおりです。

- default: デフォルトでは、ADF Facesにより、リッチなユーザー・インタフェースでの操作を実行しキーボードから使用できる、コンポーネントが生成されます。デフォルト・モードでは、スクリーン・リーダーはすべてのADF Facesコンポーネントにアクセスできないことに注意してください。視覚的な障害のあるユーザーがスクリーン・リーダーを使用している場合、screenReaderモードを使用することをお薦めします。

- screenReader: ADF Facesは、スクリーン・リーダーを使用するために最適化されるコンポーネントを生成します。screenReaderモードを使用すると、視覚的に障害のあるユーザーへの表示には便利ですが、障害のないユーザーには表示が少なくなります。

必要に応じて、必要なアクセシビリティのサポートのタイプをユーザーが選択できるように、アプリケーションで前述のアクセシビリティのサポート・レベルを切り替える機能を提供することをお薦めします。

@accessibility-profile要素を使用して、スタイルシートでより詳細にアクセシビリティ・プリファレンスを定義することもできます。また、trinidad-config.xmlファイルで、アクセシビリティ・プロファイル・オプション(high-contrastとlarge-fontsのいずれかまたは両方)を指定することもできます。詳細は、ADF Facesスキンに関する項を参照してください。

<accessibility-profile>に使用可能な値は次のとおりです。

- high-contrast: ADF Facesは、高コントラストで見やすいコンテンツを生成できます。高コントラスト・モードは、高コントラスト機能を有効にしているオペレーティング・システムまたはブラウザとの互換性をADF Facesアプリケーションに持たせることを目的としています。たとえば、ADF Facesでは、高コントラスト・モードで背景のイメージおよび背景色の使用を変更して、視覚的な情報が失われないようにします。高コントラスト・モードは、ブラウザまたはオペレーティング・システムの高コントラスト・モードと組み合わせて使用するとより効果的です。また、高コントラスト・モードを大きいフォント・モードと一緒に使用しても効果的な場合があります。

- large-fonts: ADF Facesは、ブラウザの表示を拡大できるコンテンツを生成できます。デフォルト・モードでは、ほとんどのテキストと多数のコンテナのサイズは固定されていて、一貫性のある確定した外観が提供されます。大きいフォント・モードでは、テキストおよびコンテナのサイズは拡大縮小が可能です。これによって、ADF Facesはより大きいフォント・サイズが設定されているブラウザと互換性を持ち、ブラウザのズーム機能に対応することもできます。大きいフォント・モードまたはブラウザのズーム機能を使用していない場合、大きいフォント・モードを無効にする必要があることに注意してください。また、大きいフォント・モードを高コントラスト・モードと一緒に使用しても効果的な場合があります。

注意:

<accessibility-mode>および<accessibility-profile>要素は、ELにより、ユーザー固有のプリファレンスが含まれるセッション有効範囲のマネージドBeanにバインドされる必要があります。

22.2.1 trinidad-config.xmlにおけるアクセシビリティ・サポートの構成方法

JDeveloperで、ADF FacesコンポーネントをJSFページに初めて追加すると、trinidad-config.xmlの基礎ファイルが/WEB-INFディレクトリに自動的に作成されます。ファイルは、JSF式言語(EL)または静的値を使用して要素プロパティを定義できる単純なXML構造です。ファイル内の要素の順序は関係ありません。XMLファイルを直接編集するか、構造ウィンドウを使用することで、アクセシビリティ・サポートを構成できます。

JDeveloperのtrinidad-config.xmlでアクセシビリティ・サポートを構成する手順:

1. 「アプリケーション・ナビゲータ」で、trinidad.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>

このコードは、高コントラストおよび大きいフォントを使用するようにアプリケーションのプロファイル・サポートを設定します。

4. または、構造ウィンドウを使用して、次のように値を入力できます。

1. 「アプリケーション・ナビゲータ」で、trinidad-config.xmlファイルを選択します。

2. 構造ウィンドウで、XMLファイルのルート要素を右クリックして「内部に挿入」メニュー項目を選択し、<accessibility-mode>要素をクリックします。

3. 構造ウィンドウで新しく挿入された要素をダブルクリックし、プロパティ・インスペクタを開きます。値を入力するか、ドロップダウン・リストから1つ選択します。

trinidad-config.xmlファイルの構成後、プログラムから、あるいはJSF EL式を使用してプロパティ値を取得できます。

たとえば、次のコードでは、アクセシビリティ・モードが明示的に設定されていない場合は、何も返されません。

String mode=ADFFacesContext.getCurrentInstance().getAccessibilityMode;

このEL式の例では、アクセシビリティ・モードが明示的に設定されていない場合は、何も返されません。

<af:outputText value="*#{requestContext.accessibilityMode}"/>

22.3 コンポーネントレベルのアクセシビリティ・プロパティの指定

コンポーネント固有のアクセシビリティのガイドラインは、ADF Facesコンポーネントのアクセシビリティ・ガイドラインに関する項に説明されています。ガイドラインには、関連するプロパティの説明が例やヒントとともに記載されています。ADF Facesのアクセシビリティ・ルールに準拠していることを監査する方法の詳細は、アクセシビリティ監査ルールの実行に関する項を参照してください。

af:inputText、af:commandButtonおよびaf:goLinkなど、ADF Facesの入力、コマンドおよび実行コンポーネントに対するアクセス・キー・サポートには、ラベルの定義およびキーボード・ショートカットの指定が含まれています。[Tab]キーを使用してWebアプリケーションのあるコントロールから次のコントロールへ移動することが可能ですが、キーボード・ショートカットはより便利で効率的です。

コンポーネントのアクセス・キーを指定するには、コンポーネントのaccessKey属性を、コンポーネントに簡単にアクセスするために使用するキーボード文字(またはニーモニック)に設定します。属性は、プロパティ・インスペクタ、または&ampエンコーディングを使用してページ・ソースで設定できます。

注意:

アクセシビリティ・モードがscreenReaderモードに設定されている場合は、アクセス・キーは表示されません。詳細は、アクセシビリティ・プリファレンスの表示に関する項を参照してください。

同じアクセス・キーを複数のコンポーネントにバインドできます。同じアクセス・キーが同一ページ内の複数の場所に表示される場合、レンダリング・エージェントは同じキーでアクセスできるコンポーネントを巡回します。つまり、アクセス・キーが押されるたびに、フォーカスがコンポーネント間を移動します。最後のコンポーネントに到達すると、フォーカスは最初のコンポーネントに戻ります。

af:goButtonおよびaf:goLinkコンポーネントでアクセス・キーを使用すると、一部のブラウザではアクセス・キーがすぐにアクティブ化されます。ブラウザによっては、ページの2つ以上の実行コンポーネントに同じアクセス・キーが割り当てられている場合、同じアクセス・キーでアクセスできるコンポーネントを巡回せずに、最初のコンポーネントがアクティブ化されます。

アクセス可能なページおよびナビゲーション構造を開発するには、アクセス可能なページの作成に関する項で説明されている追加のアクセシビリティ・ガイドラインに従います。

22.3.1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

アクセス可能なADF Facesコンポーネントを開発するには、表22-1に説明されているガイドラインに従います。リストされていないコンポーネントには、アクセシビリティ・ガイドラインはありません。

注意:

アクセシビリティ・ガイドラインでlabelプロパティが参照される場合、可能な場合はlabelAndAccessKeプロパティが使用されます。これは推奨オプションです。

特に記載がないかぎり、次のようにして、ADF Facesの入力および選択のコントロールにもラベルを設定できます。

- af:outputLabelコンポーネントにforプロパティを指定

- af:panelLabelAndMessageコンポーネントにforプロパティを指定

表22-1 ADF Facesコンポーネントのアクセシビリティ・ガイドライン

コンポーネント

ガイドライン

af:chooseColor

すべてのaf:chooseColorコンポーネントに、af:chooseColorコンポーネントを指すchooseIdプロパティを含むaf:inputColorコンポーネントが1つ以上存在する必要があります。

af:chooseDate

すべてのaf:chooseDateコンポーネントに、af:chooseDateコンポーネントを指すchooseIdプロパティを含むaf:inputDateコンポーネントが1つ以上存在する必要があります。

af:commandButton

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。テキストは実行するアクションを指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。

af:commandLink

textプロパティを指定します。テキストは、ユーザーが移動するリンク先を指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。同じ場所に移動する複数のリンクには同じテキストを使用し、一意のリンクには一意のテキストを使用する必要があります。

af:commandMenuItem

af:commandNavigationItem

af:comandToolbarButton

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。

af:dialog

af:document

titleプロパティを指定します。

af:goButton

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。テキストは実行するアクションを指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。

af:goLink

textプロパティを指定します。テキストは、ユーザーが移動するリンク先を指定し、コンテキスト外で読んでも意味がわかる必要があります。たとえば、「ここをクリック」ではなく、「索引へ移動」とします。同じ場所に移動する複数のリンクには同じテキストを使用し、一意のリンクには一意のテキストを使用する必要があります。

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も指定する必要があります。

af:outputFormatted

valueプロパティに有効なHTMLを指定する必要があります。

af:outputLabel

ADF Facesの入力または選択コントロールへのラベル設定にこのコンポーネントを使用する場合は、forプロパティを指定する必要があります。

af:panelBox

af:panelHeader

textプロパティを指定します。

af:panelLabelAndMessage

ADF Facesの入力または選択コントロールへのラベル設定にこのコンポーネントを使用する場合は、forプロパティを指定する必要があります。

af:panelSplitter

af:panelStretchLayout

ページ構造およびナビゲーションの使用方法に関する項を参照してください。

af:panelWindow

titleプロパティを指定します。

af:poll

コンテンツを更新するためにポーリングを使用する場合は、エンド・ユーザーが間隔を制御できるようにするか、ポーリングではなく更新を明示的に開始できるようにします。

af:query

次のプロパティを指定します。

- headerText

- addFieldsButtonAccessKey

- addFieldsButtonText

- resetButtonAccessKey

- resetButtonText

- saveButtonAccessKey

- saveButtonText

- searchButtonAccessKey

- searchButtonText

af:quickQuery

searchDescプロパティを指定します。

af:richTextEditor

labelプロパティを指定します。

af:selectBooleanCheckbox

af:selectBooleanRadio

text、textAndAccessKeyまたはlabelのいずれかのプロパティが指定されている必要があります。

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プロパティを指定する必要があります。

af:showDetailHeader

textプロパティを指定します。

af:showDetailItem

text、textAndAccessKeyまたはshortDescのいずれかのプロパティが指定されている必要があります。

af:table

af:treeTable

summaryプロパティを指定します。summaryでは、表の目的を記述する必要があります。表がレイアウト目的で使用されている場合、summaryプロパティに空の文字列を含める必要があります。

すべての表の列に列ヘッダーを作成する必要があります。

22.3.2 スクリーン・リーダー・モードでのADF Faces表コンポーネントの使用

WebアプリケーションでADF Faces表コンポーネントを使用している場合、スクリーン・リーダー・モードの行ヘッダーとして列を指定する必要があります。スクリーン・リーダー・ソフトウェアでは行ヘッダーを使用して、エンド・ユーザーが行を選択したときに行を通知します。通常、1つの列が1つの行ヘッダーとして使用され、これにより複数の選択が可能になりますが、複数の列を複数の行ヘッダーとしてマークできます。複数の列を複数の行ヘッダーとしてマークすると、表の最初の列として表示され、固定されます。

表示のために行ヘッダーが不要な場合があります。この場合、rowHeader属性がunstyledに設定されるように、表の1つの列を定義する必要があります。スクリーン・リーダー・モードでは、unstyled行ヘッダー列を含む表またはツリーの表コンポーネントは開始位置(displayIndexを0に設定)に移動し、固定されます。デフォルト・モードでは、unstyled行ヘッダー列を含む表またはツリー表コンポーネントは開始位置に移動されず、固定されません。行ヘッダーのCSSスタイルなしでレンダリングされます。

22.3.3 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

アクセス可能なADFデータ視覚化コンポーネントを開発するには、表22-2で説明されているアクセシビリティ・ガイドラインに従います。リストされていないコンポーネントには、アクセシビリティ・ガイドラインはありません。

表22-2 ADFデータ視覚化コンポーネントのアクセシビリティ・ガイドライン

コンポーネント

ガイドライン

dvt:projectGantt

dvt:resourceUtilizationGantt

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

summaryプロパティを指定します。

スクリーン・リーダー・モードでは、ツリー表コンポーネントのインスタンスが階層ビューア・コンポーネントを置換します。エンド・ユーザーは標準のカーソル・キーを使用すると、データを移動できます。

dvt:map

summaryプロパティを指定します。

スクリーン・リーダー・モードでは、表コンポーネントのインスタンスがマップ・コンポーネントを置換します。エンド・ユーザーは標準のカーソル・キーを使用すると、データを移動できます。

dvt:pivotTable

summaryプロパティを指定します。summaryでは、ピボット・テーブル・コンポーネントの目的を記述する必要があります。

dvt:sparkChart

shortDescプロパティを指定します。

22.3.4 ADF Facesコンポーネントのアクセス・キーの定義方法

アクセス・キーを定義するコンポーネントのプロパティ・インスペクタで、accessKey属性フィールドにニーモニック文字を入力します。テキスト、ラベル、値およびニーモニック文字を同時に設定する場合は、関連する属性フィールドのニーモニック文字の前にアンパサンド(&)文字を使用します。

ADF Facesの入力、コマンドおよび実行コンポーネントにキーボード文字を指定するには、次の4つの属性のいずれか1つを使用します。

- accessKey: コンポーネントへの簡単なアクセスに使用するニーモニック文字を設定するために使用します。コマンド・コンポーネントと実行コンポーネントの場合、この属性によって指定される文字は、インスタンス・コンポーネントのtext属性の中に存在する必要があります。それ以外の場合、ADF Facesでは、コンポーネントがアクセス・キーを持つ視覚的な表示が行われません。
例22-1に、af:goLinkコンポーネントのアクセス・キーを文字hに設定するコードを示します。ユーザーが[Alt]+[H}キーを押すと、コンポーネントのテキスト値がフォーカスされます。

例22-1 定義されているaccessKey属性

<af:goLink text="Home" accessKey="h">

- textAndAccessKey: アンパサンド(&)文字を使用して、コンポーネントのテキストとニーモニック文字を同時に設定する場合に使用します。JSPXファイルでは、従来のアンパサンド表記は&amp;です。JSPファイルでは、アンパサンド表記は単純に&です。プロパティ・インスペクタでは&のみが必要です。
例22-2に、ボタン・テキストをHomeに指定し、アンパサンド文字の直後の文字であるHを、af:commandButtonコンポーネントのアクセス・キーに設定するコードを示します。

例22-2 定義されているtextAndAccessKey属性

<af:commandButton textAndAccessKey="&amp;Home"/>

- labelAndAccessKey: 従来のアンパサンド表記を使用して、入力コンポーネントのlabel属性およびアクセス・キーを同時に設定する場合に使用します。
例22-3に、ラベルをDateに指定し、アンパサンド文字の直後の文字であるaを、af:selectInputDateコンポーネントのアクセス・キーに設定するコードを示します。

例22-3 定義されているlabelAndAccessKey属性

<af:inputSelectDate value="Choose date" labelAndAccessKey="D&amp;ate"/>

- valueAndAccessKey: 従来のアンパサンド表記を使用して、value属性およびアクセス・キーを同時に設定する場合に使用します。
例22-4に、ラベルをSelect Dateに指定し、アンパサンド文字の直後の文字であるeを、af:outputLabelコンポーネントのアクセス・キーに設定するコードを示します。

例22-4 定義されているvalueAndAccessKey属性

<af:outputLabel for="someid" valueAndAccessKey="Select Dat&amp;e"/>
<af:inputText simple="true" id="someid"/>

アクセス・キー修飾子は、ブラウザおよびプラットフォームによって異なります。すでにブラウザのメニュー・ショートカットとして定義されているアクセス・キーを割り当てると、ADF Facesコンポーネントのアクセス・キーが優先されます。詳細は、特定ブラウザのドキュメントを参照してください。

一部のブラウザでは、空白をアクセス・キーとして使用する場合は、コンポーネントのラベルまたはテキスト・ラベルで空白をビジュアルに表現する方法がないため、[Alt]+[Space]または[Alt]+スペースバーがアクセス・キーであるという情報をユーザーに提供する必要があります。そのようなブラウザの場合は、shortDesc属性を使用してコンポーネントのツールチップにテキストを指定できます。

22.3.5 ローカライズされたラベルおよびアクセス・キーの定義方法

異なる言語で表示する必要のあるラベルおよびアクセス・キーは、必要に応じて様々な言語バージョンの表示が可能なリソース・バンドルに格納できます。JSF 1.2で使用可能なJSF構成ファイルに<resource-bundle>要素を使用すると、すべてのページにf:loadBundleタグを使用せずに、アプリケーションのすべてのページに対してリソース・バンドルを使用可能にできます。

ローカライズされたラベルおよびアクセス・キーを定義する手順:

1. リソース・バンドルをシンプルな.propertiesファイルとして作成し、ラベルおよびアクセス・キーの各言語バージョンを保持します。詳細は、ベース・リソース・バンドルの定義方法に関する項を参照してください。

2. faces-config.xmlファイルに<locale-config>要素を追加し、アプリケーションのデフォルトおよびサポートされるロケールを定義します。詳細は、アプリケーションへのロケールおよびリソース・バンドルの登録方法に関する項を参照してください。

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>要素を追加します。例22-5に、リソース・バンドルに対するJSF構成ファイルのエントリを示します。

例22-5 JSF構成ファイルのリソース・バンドル

<resource-bundle>
<var>res</var>
<base-name>resources.UIStrings</base-name>
</resource-bundle>

リソース・バンドルを使用するようにアプリケーションを設定すると、リソース・バンドル・キーが式言語(EL)エディタに表示され、宣言的に割り当てられるようになります。

次の例では、UIコンポーネントがリソース・バンドルにアクセスしています。

<af:outputText value="#{res['login.date']}"/

詳細は、第21章「ページの国際化およびローカライズ」を参照してください。

22.4 アクセス可能なページの作成

コンポーネントレベルのアクセシビリティ・ガイドラインに加えて、アプリケーションの設計時にはページレベルのアクセシビリティ・ガイドラインにも従う必要があります。コンポーネントレベルのガイドラインでは、コンポーネントの使用方法を決定しますが、ページレベルのアクセシビリティ・ガイドラインでは、アプリケーションの全体としての設計および機能に関連して記述されています。

ページレベルのアクセシビリティ・ガイドの目的は次のとおりです。

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

- スクリプトの使用

- スタイルの使用

- ページ構造およびナビゲーションの使用

- WAI-ARIAランドマーク・リージョンの使用

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

スクリーン・リーダーでは、部分ページ・リクエストで全ページの再読込みは実行されません。部分ページ・レンダリング(PPR)によって、スクリーン・リーダーは、部分アクションを起動したコンポーネントからページの読込みを実行します。したがって、ターゲット・コンポーネントは、部分リクエストを起動するコンポーネントの後に配置します。このようにしないと、更新したターゲットがスクリーン・リーダーに読み込まれません。

たとえば、最も一般的なPPRのユースケースは、マスター/ディテール・ユーザー・インタフェースで、マスター・コンポーネントで値を選択すると、ディテール・コンポーネントのページの一部が置き換えられます。このような場合、ドキュメントの順番において、マスター・コンポーネントが常にディテール・コンポーネントの前にあることが必要です。

スクリーン・リーダーやスクリーン・マグニファイアのユーザーには、部分ページ・レンダリング・アクティビティの結果、どのコンテンツが変更されたかを正確に特定するのが難しい場合があります。ページ内のキー・コンポーネント間の関係を識別するインライン・テキスト説明という形で、説明を用意すると役に立ちます。たとえば、マスター/ディテール・シナリオで、マスター・コンポーネントで行が選択されたため、ディテール・コンポーネントが更新されることを示すテキストがあれば助けになります。または、ページの構造やコンポーネント間の関係を説明するヘルプ・トピックも参考になります。

22.4.2 スクリプトの使用方法

クライアント側スクリプトは、宣言的ソリューションがあるアプリケーションの問題にはお薦めできないため、最低限にする必要があります。

スクリプトを使用する際には、次のアクセシビリティ・ガイドラインに従ってください。

- コンポーネントDOM(Document Object Model)とは直接通信しないでください。
ADF Facesコンポーネントは、DOMが変更されると、スクリーン・リーダーと自動的に同期します。DOMとの直接の通信は許可されていません。

- JavaScriptのタイムアウトは使用しないでください。
スクリーン・リーダーは、JavaScriptのsetTimeout()またはsetInterval() APIを使用して実装されたタイムアウトへのレスポンスとして行われた変更を確実に追跡するわけではありません。これらのメソッドをコールしないでください。

- キーボードに相当するものを用意してください。
マウスを使用できないユーザーもいます。たとえば、キーボードしか使用できないユーザー、または代替の入力デバイスや音声認識ソフトウェアなどのテクノロジを使用するユーザーもいます。クライアント側リスナーを使用して機能を追加する場合、その機能には、デバイスに依存しない方法でアクセスできる必要があります。事実上、これは次のことを意味します。

- すべての機能にキーボード・イベントを使用してアクセスできる必要があります。

- クリック・イベントは、マウスオーバーやマウスアウトよりも優先される必要があります。

- マウスオーバー・イベントまたはマウスアウト・イベントは、クリック・イベントによって使用可能になる必要があります。

- フォーカスを変更しないでください。
フォーカスを変更すると、コンテキストが変更されるため、スクリーン・リーダーのユーザーが混乱する可能性があります。アプリケーションではプログラムによるフォーカスの変更を避け、フォーカス・イベントへのレスポンスとしては実行しないでください。また、標準のタブ移動が中断されるため、フォーカス変更へのレスポンスとしてポップアップ・ウィンドウを表示しないでください。

- ポップアップ・トリガーを明示的に指定してください。
スクリーン・リーダーは、インライン・ポップアップの起動に自動的には応答しません。スクリーン・リーダー・モードの際に、スクリーン・リーダーがポップアップ・コンテンツを読み上げるよう強制するため、ポップアップ・ウィンドウが開かれた直後に、リッチ・クライアント・フレームワークによりキーボード・フォーカスがそのウィンドウに明示的に移動されます。リンクやボタンなどの明示的なポップアップ・トリガーを用意するか、キーボードやスクリーン・リーダーでアクセスできるその他の方法で同じ情報を使用できる必要があります。

22.4.3 スタイルの使用方法

ADF Facesコンポーネントはすでにスタイル設定されています。変更する必要はありません。Cascading Style Sheet(CSS)を使用して直接デフォルトの外観を変更する場合、次のアクセシビリティ・ガイドラインに従う必要があります。

- デフォルトのコンポーネントの外観をオーバーライドする場合、アクセシビリティに影響することに注意してください。
CSSを使用してコンポーネントの外観を変更すると、アクセシビリティに影響する可能性があります。たとえば、色を変更すると色の対比の問題が発生します。

- 拡大縮小が可能なサイズ単位を使用します。
CSSを使用してサイズを指定する場合は、絶対単位ではなく、フォント・サイズに対して拡大縮小が可能なサイズ単位を使用します。たとえば、pxではなく、em、exまたは%の単位を使用します。弱視のユーザーはフォント・サイズを拡大することがあり、高さが固定または絶対に制限されているコンテンツが欠ける原因になるため、CSSを使用して高さを指定する場合は特に重要です。

- CSSの位置設定は使用しないでください。
CSSの位置設定は、拡大されたレイアウト・コンポーネントの位置設定の場合にのみ使用します。それ以外にはCSSの位置設定を使用しないでください。

22.4.4 ページ構造およびナビゲーションの使用方法

ページ構造およびナビゲーション・ツールを使用する際には、次のアクセシビリティ・ガイドラインに従ってください。

- レイアウトの設定には、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を使用するとこれを実現できます。

22.4.5 WAI-ARIAランドマーク・リージョンの使用方法

WAI-ARIA標準では、様々なランドマーク・リージョンとしてページの様々なセクションを定義します。これらは、WAI-ARIAロールとともに、ページの高度な構造についての情報を示し、ランドマーク領域のナビゲーションを容易にします。これは、スクリーン・リーダーなどの支援テクノロジを使用するユーザーに役立ちます。

表22-3に示すように、ADF Facesには、いくつかのレイアウト・コンポーネントのランドマーク属性が含まれています。

表22-3 ランドマーク属性を含む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では、指定した値でロール属性がレンダリングされます。

22.5 アクセシビリティ監査ルールの実行

JDeveloperには、ADF Facesのアクセシビリティ監査ルールが用意されており、ADF Facesコンポーネントのアクセシビリティ・ガイドラインに関する項で説明されている、多くの一般的な要件に準拠しているかどうかが調査および報告されます。監査レポートを実行すると、監査プロファイルが作成されて実行されます。

監査プロファイルを作成する手順:

1. メイン・メニューから、「ツール」→「プリファレンス」を選択します。

2. 「監査: プロファイル」ダイアログで、「ADF Facesアクセス・ルール」を除く、すべてのチェック・ボックスの選択を解除します。

3. 一意の名前でプロファイルを保存して、「OK」をクリックします。

監査レポートを実行する手順:

1. メイン・メニューから「ビルド」→「監査 - target」を選択します。

2. 作成した監査プロファイルをリストから選択します。

3. 「OK」をクリックしてレポートを生成します。

監査レポートの結果は、ログ・ウィンドウに表示されます。レポートが完了したら、ログ・ウィンドウのツールバーにある「エクスポート」アイコンをクリックして、結果をHTMLにエクスポートできます。

第IV部

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

第IV部には、次の章が含まれています。

- 第23章「ADFデータ視覚化コンポーネントの概要」

- 第24章「ADFグラフ・コンポーネントの使用」

- 第25章「ADFゲージ・コンポーネントの使用」

- 第26章「ADFピボット・テーブル・コンポーネントの使用」

- 第27章「ADF地理マップ・コンポーネントの使用」

- 第28章「ADFガント・チャート・コンポーネントの使用」

- 第29章「ADF階層ビューア・コンポーネントの使用」

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

この章では、インタラクティブなADF Facesコンポーネントの表現力が高いセットであるADFデータ視覚化コンポーネントの一般的な特性とフォーカスについて説明します。この部の他の章では、各コンポーネントの作成およびカスタマイズ方法について説明します。

この章では、次の項目について説明します。

- 23.1項「ADFデータ視覚化コンポーネントの概要」

- 23.2項「ADFデータ視覚化コンポーネントの定義」

- 23.3項「ADFデータ視覚化コンポーネントへのデータの指定」

- 23.4項「Flashイメージ用カスタム・フォントのダウンロード」

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

ADFデータ視覚化コンポーネントには、データの表示および分析を行うための非常にグラフィカルな表形式の機能が用意されています。このコンポーネントでは、次の機能が提供されます。

- ADFデータ・コントロールの使用をサポートするADF Facesのフル・コンポーネントです。

- データ・コントロール・パネル、JSFビジュアル・エディタ、プロパティ・インスペクタおよびコンポーネント・パレットを使用して、設計時に宣言的作成を行えます。

- 各コンポーネントに、ライブ・データ・プレビューが用意されています。この機能により、ページをコンパイルおよび実行することなく、設計の効果を確認できるため、非常に有用です。

ADFデータ視覚化コンポーネントのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされたADFデータ視覚化コンポーネントの作成」の章を参照してください。

23.2 ADFデータ視覚化コンポーネントの定義

ADFデータ視覚化コンポーネントには、グラフ、ゲージ、ピボット・テーブル、地理マップ、ガント・チャートおよび階層ビューアがあります。

23.2.1 グラフ

グラフ・コンポーネントには、棒グラフ、円グラフ、折れ線グラフ、散布図、株価チャートなど、50種類以上のグラフを作成する機能が用意されています。このコンポーネントでは、複数軸の複数データ・ポイントを様々な方法で評価できます。たとえば、一群のグラフにより、あるグループからの結果と他のグループからの結果の比較が容易になります。

グラフ・コンポーネントでは次の種類のグラフを作成できます。

- 面グラフ:データが塗りつぶされた領域で表されるグラフを作成します。面グラフを使用して、過去12か月の売上げなど、ある期間の傾向を示します。面グラフでは、1つの軸上に最低2グループのデータが必要です。軸には、月などの時間の経過を表すラベルが付けられることがよくあります。

- 棒グラフ:データが一連の縦棒として表されるグラフを作成します。ある期間の傾向の確認や、複数の地域での異なる製品区分の売上げなど、同一時点での項目の比較に使用します。

- 棒(横)グラフ:Y軸に沿って棒を横向きに表示するグラフを作成します。傾向の表示や値の比較に使用できる向きを持たせるために使用します。

- バブル・グラフ:データが円形のデータ・マーカー(バブル)の位置とサイズで表されるグラフを作成します。3種類の値の相関関係を示す場合(データ項目が多数で全体の関係を表示する場合は特に)に使用します。たとえば、バブル・グラフを使用して、従業員の給与(X軸)、経験年数(Y軸)と生産性(バブルのサイズ)をプロットします。このようなグラフでは、生産性を給与および経験と比較して調べることができます。

- 組合せグラフ:異なる種類のデータ・マーカー(棒、線または面)を使用して異なる種類のデータ項目を表すグラフを作成します。棒と線、棒と面、線と面あるいは3つすべての組合せの比較に使用します。

- ファンネル・グラフ:プロセスのステップに関連するデータを視覚的に表すグラフを作成します。ステップは、横向きの円柱に対する縦向きのスライスとして表されます。特定のステップ(スライス)の実際の値がそのスライスの割当てに近づいた分、スライスが塗りつぶされます。通常、ファンネル・グラフには、時間などのステージ値に対する実績値と目標値が必要です。たとえば、このコンポーネントを使用して、プロセス(販売ルートなど)がステージ(会計年度の四半期)の目標に達するかどうかを確認します。

- 折れ線グラフ: 線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとしてデータを表示するグラフを作成します。折れ線グラフには、グループ内のメンバーごとに最低2つのポイントを表すデータが必要です。たとえば、月ごとの折れ線グラフには最低2か月必要です。通常、特定の色の線は、アメリカ、ヨーロッパ、アジアなどのデータの各グループに関連付けられています。同一期間の項目の比較に使用します。

- パレート・グラフ:データが棒と棒の累積割合を示すパーセンテージ線で表されるグラフを作成します。各棒は、交通事故の原因など、異なる不具合の原因を表します。棒は、発生件数の多いものから少ないものの順に並べられます。パレート・グラフは常に二重Yグラフで、1つ目のY軸は棒が表す値に対応し、2つ目のY軸は0%から100%を表し、累積割合の値に対応します。パレート・グラフを使用して、不具合の原因を特定し、比較します。

- 円グラフ:1つのグループのデータが円のセクションとして表され、円が切り分けられたパイのように見えるグラフを作成します。各製品ラインからの収益など、全体に対する各部分の関係の表示に使用します。

- レーダー・グラフ:円状の折れ線グラフとして表されるグラフを作成します。過去3年間の月ごとの売上げなどの周期的に起こるパターンを表す場合に使用します。

- 散布図/極グラフ:データが、データ・マーカーの位置によって表されるグラフを作成します。散布図を使用して、上位製品の売上げとコストなど、異なる2種類のデータの相関関係を表す場合に使用します。散布図は、多数の項目間の全体的な関連性を示す場合に特に有用です。

- スパークチャート: 傾向や変化を表示する簡単な要約グラフを、表の列やインラインでテキストを付けて作成します。スパークチャートの設計は簡単で、機能や書式設定のオプションは制限され、できるかぎり多くのデータが表示されます。

- 株価チャート: データが株の高値、安値および終値を示すグラフを作成します。各株価マーカーで3つの異なる値を表示します。

JDeveloperでは、データ・コントロール・パネルからデータ・コントロールをドラッグすることで、グラフを作成してデータ・バインドします。コンポーネント・ギャラリには使用可能なグラフのカテゴリ、タイプおよび説明が表示され、グラフの設計およびクイック・レイアウトの定義が視覚的にサポートされます。図23-1に、データ・コントロールからのグラフの作成で表示されるコンポーネント・ギャラリを示します。

グラフのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFグラフの作成に関する項を参照してください。

図23-1 データ・コントロール・パネルからのグラフのコンポーネント・ギャラリ

コンポーネント・パレットからグラフ・コンポーネントをドラッグし、ページにグラフを作成することもできます。この方法では、コンポーネントをデータにバインドする前に、グラフのユーザー・インタフェースを設計できます。図23-2に、コンポーネント・パレットからの円グラフの作成で表示されるコンポーネント・ギャラリを示します。

注意:

スパークチャート・コンポーネントは、コンポーネント・パレットからのみ挿入でき、後からデータにバインドできます。

図23-2 コンポーネント・パレットからの円グラフのコンポーネント・ギャラリ

すべてのグラフで、Flash、SVGおよびPNGレンダリングがサポートされます。グラフ・コンポーネントでは、ズームとスクロールの使用、時間軸の特定の部分を強調表示する調節可能な時間セレクタ・ウィンドウの使用、データ・ポイントの表示をフィルタして強調およびフェードする線および凡例の使用、動的参照線と領域の使用などの初期表示およびデータの変更に対する相互作用がサポートされます。

図23-3に、アプリケーション・ダッシュボードを示します。表示内容は次のとおりです。

- 棒グラフ

- スライスの切離しを使用した円グラフ

図23-3 棒グラフおよび円グラフが表示されているダッシュボード

図23-4にアプリケーション・ダッシュボードを示します。表示内容は時計回りに左上から次のとおりです。

- 時間セレクタ・ウィンドウを持つ平滑線グラフ

- 3D効果とスライスの切離しを使用した円グラフ

- 3D効果を使用した棒グラフ

図23-4 折れ線グラフ、円グラフおよび棒グラフが表示されているダッシュボード

図23-5に、売上げの傾向を表の列に表示する折れ線スパークチャートを示します。

図23-5 売上げ傾向のスパークチャート

23.2.2 ゲージ

ゲージ・コンポーネントでは、データのグラフィカル表現をレンダリングします。グラフとは異なり、ゲージでは1つのデータ・ポイントにフォーカスして、そのポイントを最小、最大およびしきい値インジケータと比較して調べ、問題のある領域を特定します。

1つのゲージ・コンポーネントでは、使用されるデータに応じて、1つのゲージまたはゲージ・セットを作成できます。

このコンポーネントでは次の種類のゲージを作成できます。

- ダイアル・ゲージ: 180度の弧に沿ってメトリック値を示すゲージを作成します。このタイプのゲージには、通常、ゲージがプロットしている値を指す、線または矢印の形のインジケータがあります。

- ステータス・メーター・ゲージ:横長の矩形のバーに沿ってタスクの進度または測定値のレベルを示すゲージを作成します。内側の矩形は、外側の矩形に表示された範囲に対する現在の測定値のレベルを示します。

- ステータス・メーター・ゲージ(垂直):縦長の矩形のバーに沿ってタスクの進度または測定値のレベルを示すゲージを作成します。

- LED(電光表示)ゲージ:重要業績評価指標(KPI)などの測定値をグラフィカルに表すゲージを作成します。LEDゲージには、よい(上矢印)、普通(左または右矢印)、悪い(下矢印)を示す矢印など、数種のグラフィクスが使用できます。

ゲージのしきい値はいくつでも指定できます。ただし、一部のLEDゲージ(矢印や三角形のインジケータを使用するゲージなど)では、それらが示す意味のある方向の数に制限があるため、サポートされるしきい値の数が制限されます。矢印や三角形のインジケータの場合、しきい値の制限は3です。

JDeveloperのコンポーネント・ギャラリには使用可能なゲージのカテゴリ、タイプおよび説明が表示され、ゲージの設計およびクイック・レイアウトの定義が視覚的にサポートされます。図23-6に、ゲージのコンポーネント・ギャラリを示します。

図23-6 ゲージのコンポーネント・ギャラリ

すべてのゲージ・コンポーネントでFlash、SVGおよびPNGレンダリングを使用できます。

図23-7に、倉庫の在庫レベルを表示する、しきい値付きダイアル・ゲージのセットを示します。

図23-7 しきい値付きダイアル・ゲージ・セット

図23-8に、しきい値付きステータス・メーター・ゲージのセットを示します。

図23-8 しきい値付きステータス・メーター・ゲージ・セット

23.2.3 ピボット・テーブル

ピボット・テーブルでは、行または列での複数層のデータ・ラベルをサポートするグリッドを作成します。オプションのピボット・フィルタ・バーをピボット・テーブルと関連付けて、行エッジや列エッジに表示しないデータをフィルタ処理できます。コンポーネントが、行セットなどの適切なデータ・コントロールにバインドされている場合、グリッド・データの小計と合計を生成するオプションと実行時のドリル操作もサポートします。JDeveloperのピボット・テーブルの作成ウィザードでは、ピボット・テーブルのデータバインディングと構成の宣言的なサポートが提供されます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFピボット・テーブルの作成に関する項を参照してください。

ピボット・テーブルでは、あるエッジ(行または列)またはピボット・フィルタ・バー(ページ・エッジ)から別のエッジにデータ・ラベルを入れ替え、データの表示を変えることができます。たとえば、ピボット・テーブルは、年別に列エッジで分類される、製品の売上げデータの合計を行エッジの領域内に最初に表示します。領域と年を実行時に入れ替える場合、領域別に分類される、年内の製品の合計売上げデータで終了します。

ピボット・テーブルでは、横方向と縦方向のスクロール、ヘッダーとセルの書式設定およびドラッグ・アンド・ドロップ・ピボットがサポートされています。ピボット・テーブルでは、実行時の行の昇順および降順のグループ・ソートもサポートされます。図23-9に、ピボット・フィルタ・バーを使用するピボット・テーブルの例を示します。

図23-9 ピボット・フィルタ・バーを使用するピボット・テーブル

23.2.4 地理マップ

地理マップでは、ADFフレームワークにOracle Spatialの機能が提供されます。このコンポーネントでは、ビジネス・データをマップ上に表し、1つのマップ上に複数層の情報を重ね合せることができます。このコンポーネントでは、色テーマ、グラフ・テーマ(棒または円グラフ)および点テーマの同時表示がサポートされます。各タイプのテーマはいくつでも作成でき、マップ・ツールバーを使用して、実行時にテーマを選択できます。

地理マップの例として、各州での製品の人気を色の濃さで示す色テーマ、倉庫の在庫レベルを示す円グラフ・テーマおよび各倉庫の正確な位置を示す点テーマを使用した、アメリカの基準となるマップを考えてみます。この3つの全テーマをアメリカ合衆国の地図に重ね合せると、特定の地域で商品の人気度に応じた十分な在庫があるかどうかを簡単に評価できます。図23-10に、色テーマ、円グラフ・テーマおよび点テーマを使用した地理マップを示します。

図23-10 色テーマ、円グラフ・テーマおよび点テーマを使用した地理マップ

23.2.5 ガント・チャート

ガント・チャートは(横軸を時間とする)横棒グラフの一種で、リソースまたはタスクが、開始と終了が明確なタイム・フレームに示され、プロジェクトの計画や進捗管理に使用されます。

ガント・チャートは、2つのADFのツリー表とスプリッタの組合せで構成されます。左側の表にはタスクまたはリソースのリストが含まれ、右側の表は1つの列で構成され、特定期間の進捗がグラフ表示されます。

3種類のガント・コンポーネントがあります。

- プロジェクト・ガント: タスクを縦に示し、横向きの予定表に各タスクの期間を棒で示すガント・チャートを作成します。

- リソース使用率ガント:リソースが割当てを上回っているか下回っているかをグラフィカルに示すガント・チャートを作成します。リソースを縦に示し、横方向の時間軸にその割当てとキャパシティ(オプション)を示します。

- スケジュール・ガント:リソース管理を示し、手動のスケジュール表をベースにしたガント・チャートを作成します。リソースを縦方向に、対応するアクティビティを横方向の時間軸に表示します。

図23-11 に、スタッフ・リソースとスケジュールを表示したプロジェクト・ガントを示します。

図23-11 プロジェクト・ガント

23.2.6 階層ビューア

階層ビューアは、階層データが図中のリンクされたノードのセットとして表示されるコンポーネントです。ノードおよびリンクは、データの要素および関係に対応します。このコンポーネントでは、パンおよびズーム操作、ノードの展開および折りたたみ、そしてノード内での簡単なADF Facesコンポーネントのレンダリング、階層ビューア・データの検索がサポートされています。階層ビューアの一般的な用途は、図23-12に示すような組織図を表示することです。

図23-12 階層ビューアによる組織図

JDeveloperのコンポーネント・ギャラリには使用可能な階層ビューアのタイプおよび説明が表示され、コンポーネントの設計およびクイック・レイアウトの定義が視覚的にサポートされます。図23-13に、階層ビューアのコンポーネント・ギャラリを示します。

図23-13 階層ビューアのコンポーネント・ギャラリ

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

すべてのデータ視覚化コンポーネントは、ADFデータ・コントロールの行セット・データ・コレクションにバインドできます。これらのコンポーネントのデータ・コントロールへのデータ・バインディングの詳細と例は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされたADFデータ視覚化コンポーネントの作成」の章を参照してください。

グラフとゲージにはtabularDataメソッドがあり、マネージドBeanに格納されたメソッドからCSV(カンマ区切りの値)データを提供できます。

ガント・チャート・コンポーネントでは基本的なツリー・データ・コントロールの使用がサポートされ、タスクとリソースだけでなく、サブタスクとサブリソースにもデータを提供できます。

23.4 Flashイメージ用カスタム・フォントのダウンロード

グラフおよびゲージ・コンポーネントでは、Flashイメージ・タイプを使用してテキストの回転、忠実度の高い表示およびフォントの埋込みを行えます。Flashエンジンは、チャートのXML定義を使用したグラフまたはゲージの表示に使用される、コンパイル済のActionScriptコードを含む事前作成のShockwave Flash(SWF)ファイルです。Flashエンジンはダウンロードして、クライアント・ブラウザに組み込まれているFlash Playerで実行時にインスタンス化します。

表示と印刷が目的の場合、埋込みフォントが使用されます。これらは、クライアントにインストールされないため、編集できません。これらは、Flash Playerでインメモリに使用され、Flash Playerが終了すると、消去されます。埋込みフォントでは、フォントのSWFファイルをダウンロードするサーバーへのラウンドトリップが必要ですが、すべてのクライアントで見た目が変わらず、テキストの回転に対応し、ゆがみやアンチエイリアス処理が最小限に抑えられます。

Oracleでは、必要に応じてFlashイメージで使用されるAlbany WTフォントが提供されます。このフォントには、太字やイタリックなどのプレーン以外の形式はありません。アプリケーションでかわりに使用する各自の埋込みフォントを指定および用意しない場合、Albany WTフォントがデフォルト・フォントのかわりに使用され、Flashでサポートされない特定のアニメーションを装置のフォントでサポートします。

特定のフォントと各SWFファイルは、Flashエンジンに渡される埋込みフォントとしてアプリケーションに追加できます。リストに指定されたフォントがグラフまたはゲージの定義内のテキストまたはラベルで必要になるときまでに、エンジンによってそのフォントが遅延ロードされます。例23-1では、太字とイタリックを組み合せたGeorgiaフォントを定義します。

例23-1 SWFファイル

package
{
import.flash.display.Sprite;
import.flash.text.Font;
public class fGeorgiaBoldItalic extends Srite
(
[Embed (source="c:\\WINDOWS\\Fonts\\GEORGIABI.TTF",
fontName="Georgia Bold Italic",
fontWeight="Bold",
fontStyle="Italic".
mimType="application/x-font-truetype")]
private statis car font1:Class;
public function fGeorgiaBoldItalic() {
Font registerFont(font1);
}
}
}

グラフおよびゲージのフォント属性は次のように設定できます。

- fontEmbedding: 埋込みフォントが使用されるかどうかを定義します。この属性をnoneに設定すると、パフォーマンスが向上する場合があります。

- fontMap: 埋込みに使用されるフォントの実際のマップを含みます。マップには、フォントの名前と、カスタム・フォントSWFファイルの格納場所のURLが含まれます。

24 ADFグラフ・コンポーネントの使用

この章では、ADFグラフ・コンポーネントを使用してデータを表示する方法とグラフのカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 24.1項「グラフ・コンポーネントの概要」

- 24.2項「グラフ・タグの理解」

- 24.3項「グラフのデータ要件の理解」

- 24.4項「グラフの作成」

- 24.5項「グラフ・タイプの変更」

- 24.6項「グラフの外観のカスタマイズ」

- 24.7項「特定のグラフ・タイプの外観のカスタマイズ」

- 24.8項「特殊な機能のグラフへの追加」

- 24.9項「グラフへのアニメーションの使用」

ADFグラフのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFグラフの作成に関する項を参照してください。

24.1 グラフ・コンポーネントの概要

グラフ・コンポーネントには、面グラフ、棒グラフ、バブル・グラフ、組合せグラフ、ファンネル・グラフ、折れ線グラフ、パレート・グラフ、円グラフ、レーダー・グラフ、散布図、スパークチャート、株価チャートなど、50種類以上のグラフを作成する機能が用意されています。このコンポーネントでは、複数軸の複数データ・ポイントを様々な方法で評価できます。たとえば、一群のグラフにより、あるグループからの結果と他のグループからの結果の比較が容易になります。

コンポーネント・ギャラリには使用可能なグラフのカテゴリ、タイプおよび説明が表示され、グラフの作成およびクイック・スタート・レイアウトの指定が視覚的にサポートされます。図24-1に、横棒グラフのコンポーネント・ギャラリを示します。

図24-1 横棒グラフのコンポーネント・ギャラリ

コンポーネント・ギャラリを使用してグラフをJSFページに挿入すると、グラフのカスタマイズをサポートする子タグのセットが自動的に挿入されます。例24-1に、図24-1のコンポーネント・ギャラリでクイック・スタート・レイアウトを選択した横棒グラフのソース・コードを示します。

例24-1 横棒グラフのサンプル・コード

<dvt:horizontalBarGraph id="horizontalBarGraph1"
value="#{bindings.SalesStageDataView1.graphModel}"
subType="BAR_HORIZ_CLUST">
customLayout="CL_NONE"
<dvt:background>
<dvt:specialEffects/>
</dvt:background>
<dvt:graphPlotArea/>
<dvt:seriesSet>
<dvt:series/>
</dvt:seriesSet>
<dvt:o1Axis/>
<dvt:y1Axis/>
<dvt:legendArea automaticPlacement="AP_NEVER" position="LAP_BOTTOM"/>
<dvt:legendTitle text="Legend Title"/>
<dvt:graphSubtitle horizontalAlignment="CENTER" text="Subtitle"/>  <dvt:graphTitle horizontalAlignment="CENTER" text="Title"/>
</dvt:horizontalBarGraph>

図24-2に、図24-1のコンポーネント・ギャラリで作成された横棒グラフのビジュアル・エディタ表示を示します。

図24-2 ビジュアル・エディタの横棒グラフ

ビジュアル・エディタでグラフを編集する場合、タイトル、凡例エリア、描画エリア、背景、軸ラベル、棒の表示などのグラフ・コンポーネントを選択して、編集の選択肢を含むコンテキスト・メニューを表示できます。ビジュアル・エディタでのグラフの編集の詳細は、24.6項「グラフの外観のカスタマイズ」を参照してください。

グラフは、400 X 300ピクセルのデフォルト・サイズで表示されます。ブラウザ・ウィンドウの各種サイズのエリアに合うように、グラフのサイズをカスタマイズしたり、動的なサイズ変更を指定したりすることができます。グラフが縦または横に制限されたエリアで表示される場合(Webページのサイドバーなど)、グラフは十分な機能が装備された状態で表示されますが、表示は簡略化されます。

スクリーン・リーダーでWebページを読み取る視覚障害のユーザーに対応するために、スクリーン・リーダー・モードがアプリケーションに有効な場合、グラフは自動でピボット・テーブルに置き換えられます。スクリーン・リーダーでは、グラフよりもピボット・テーブルの方がデータの移動や読取りが簡単です。スクリーン・リーダー・モードの有効化の詳細は、22.2項「アクセシビリティ・プリファレンスの公開」を参照してください。ADFピボット・テーブルの詳細は、26.1項「ADFピボット・テーブル・コンポーネントの概要」を参照してください。

デフォルトでは、グラフ・コンポーネントの属性imageFormatで指定するように、グラフはFlash Playerを使用して表示されます。あるいは、プラグインがクライアント・マシンで許可されない場合や双方向ロケールのように、ポータブル・ネットワーク・グラフィックス(Portable Network Graphics: PNG)出力形式を使用してグラフを表示することもできます。PNG出力形式を使用する場合、静的レンダリングは十分にサポートされますが、次の特定のインタラクティブ機能は使用できません。

- アニメーション

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

- ドラッグ・アンド・ドロップ・ジェスチャー

- 円グラフのスライスのインタラクティブ動作

- 参照オブジェクトのホバー動作

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

- 選択項目

- 系列のロールオーバー動作

- 時間セレクタ

- ズームとスクロール(クライアント側の実況スクロール)

グラフのイメージ形式はFlashとPNGのどちらの場合も、双方向ロケールをサポートします。図24-3に、Flashイメージ形式で表示される複数の円グラフでの双方向サポートを示します。

図24-3 グラフの双方向サポート

24.2 グラフ・タグの理解

グラフのタイプは数多くあり、グラフ・コンポーネントの柔軟性はかなり高いため、グラフには多くのDVTタグがあります。各グラフ・タグ名の先頭にある接頭辞(dvt:)は、タグがADFデータ視覚化ツール(DVT)タグ・ライブラリの1つであることを示します。次のリストに、グラフ・コンポーネントに関連するタグのグループを示します。

- グラフ固有のタグ:13個のグラフ固有のタグは、よく使用されるグラフ・タイプを作成する簡便な方法です。コンポーネント・ギャラリでは、1つ以上のタイプおよび多様なクイック・スタート・レイアウト・オプションとともにグラフのカテゴリとして表示されます。これらのタグのリストと説明は、24.2.1項「グラフ固有のタグ」を参照してください。

- 一般的なグラフの子タグ:これらのタグは、カスタマイズ用に大部分のグラフ・タイプでサポートされます。これらのタグのリストと説明は、24.2.2項「一般的なグラフの子タグ」を参照してください。

- グラフ・タイプの子タグ:これらのタグは、特定のグラフ・タイプまたはグラフの特定部分に使用します。これらのタグのリストと説明は、24.2.3項「グラフ固有の子タグ」を参照してください。

- 子セット・タグ:これらのタグは、無数の関連するタグのセットをラップします。これらのタグのリストと説明は、24.2.4項「子セット・タグ」を参照してください。

- グラフ・タグ: 使用可能ですが、お薦めの方法ではありません。dvt:graphタグでは、サポートされているグラフ・タイプのグラフのインスタンスを作成できます。特定のグラフ・タイプにのみ有効なグラフ属性と子タグも一部ありますが、グラフ・タグには、グラフ属性の包括的なセットがあり、すべてのグラフ子タグの使用がサポートされます。このため、dvt:graphタグには、グラフ・タイプの選択、グラフのカスタマイズや、あるグラフ・タイプから別のタイプへの変更に対する十分な柔軟性があります。

注意:

JDeveloperでは、コンポーネント・パレットからの宣言的挿入にdvt:graphタグを使用できません。このタグと子タグは、.jspxファイルのソース・コードに入力する必要があります。

すべてのタグとその属性の詳細、および有効な値のリストは、DVTタグのドキュメントを参照してください。JDeveloperで特定のタグのドキュメントにアクセスするには、構造ウィンドウでタグを選択し、[F1]キーを押します。JDeveloperのヘルプでADF Data Visualization Toolsタグ・ライブラリにアクセスするには、オンライン・ヘルプの目次でJavadocとタグ・ライブラリ・リファレンスのノードを開き、「JDeveloperタグ・ライブラリ・リファレンス」トピックのタグ・ライブラリへのリンクをクリックします。

24.2.1 グラフ固有のタグ

グラフ固有のタグは次の13個になります。

- dvt:areaGraph: データが塗りつぶしの領域として表される面グラフをサポートします。面グラフを使用して、過去12か月の売上げなど、ある期間の傾向を示します。面グラフでは、1つの軸上に最低2グループのデータが必要です。軸には、月などの時間の経過を表すラベルが付けられることがよくあります。

- dvt:barGraph: データが一連の縦棒として表される棒グラフをサポートします。棒グラフを使用してある期間の傾向の確認や、複数の地域での異なる製品区分の売上げなど、同一時点での項目の比較を行います。

- dvt:horizontalBarGraph: Y軸に沿って棒を横向きに表示するグラフを作成します。横棒グラフを使用して向きを持たせて傾向を表示したり、値を比較します。

- dvt:bubbleGraph: データが位置と円形のデータ・マーカー(バブル)で表されるグラフを作成します。(データ項目が多数で全体の関係を表示する場合は特に)バブル・グラフを使用して3種類の値の相関関係を示します。たとえば、バブル・グラフを使用して、従業員の給与(X軸)、経験年数(Y軸)と生産性(バブルのサイズ)をプロットします。このようなグラフでは、生産性を給与および経験と比較して調べることができます。

- dvt:comboGraph: 異なる種類のデータ・マーカー(棒、線または面)を使用して異なる種類のデータ項目を表すグラフを作成します。組合せグラフを使用して、棒と線、棒と面、線と面あるいは3つすべての組合せを比較します。

- dvt:funnelGraph: プロセスのステップに関連するデータを視覚的に表すグラフを作成します。ステップは、横向きの円錐形のセクションに対する縦向きのスライスとして表されます。特定のステップ(スライス)の実際の値がそのスライスの割当てに近づいた分、スライスが塗りつぶされます。通常、ファンネル・グラフには、時間などのステージ値に対する実績値と目標値が必要です。たとえば、ファンネル・グラフを使用して、ファンネルの異なるセクションが販売周期の異なる段階を表すプロセスを表示します。

- dvt:lineGraph: データが線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとして表されるグラフを作成します。折れ線グラフには、グループ内のメンバーごとに最低2つのポイントを表すデータが必要です。たとえば、月ごとの折れ線グラフには最低2か月必要です。通常、特定の色の線は、アメリカ、ヨーロッパ、アジアなどのデータの各グループに関連付けられています。折れ線グラフを使用して、同一期間の項目を比較します。

- dvt:paretoGraph: データが棒と棒の累積割合を示すパーセンテージ線で表されるグラフを作成します。各棒は、交通事故の原因など、異なる不具合の原因を表します。棒は、発生件数の多いものから少ないものの順に並べられます。パレート・グラフは常に二重Yグラフで、1つ目のY軸は棒が表す値に対応し、2つ目のY軸は0%から100%を表し、累積割合の値に対応します。パレート・グラフを使用して、不具合の原因を特定し、比較します。

- dvt:pieGraph: 1つのグループのデータが円のセクションとして表され、円が切り分けられたパイのように見えるグラフを作成します。円グラフを使用して、各製品ラインからの収益など、全体に対する各部分の関係を表します。

- dvt:radarGraph: 円状の折れ線グラフとして表されるグラフを作成します。過去3年間の月ごとの売上げなどの周期的に起こるパターンを表す場合に、レーダー・グラフを使用します。

- dvt:scatterGraph: データが、データ・マーカーの位置によって表されるグラフを作成します。散布図を使用して、上位製品の売上げとコストなど、異なる2種類のデータの相関関係を表します。多数の項目の全体的な関係を表す場合は特に散布図を使用します。散布図では、極グラフとして方向性を持ってデータを表示できます。

- dvt:sparkChart: 傾向や変化を1つのデータ値で表示する簡単な要約グラフを作成します。通常は、表の列やインラインで関連するテキストを付けてスタンプされます。スパークチャートには、基本的な条件付書式設定があります。

注意:

このリリースでは、スパークチャートは、コンポーネント・パレットからdvt:sparkChartタグを挿入し、コンポーネントとデータをバインドして作成されます。スパークチャートは、データ・コントロール・パネルでは作成できません。

- dvt:stockGraph: データが株の高値、安値および終値を示すグラフを作成します。各株価マーカーは、選択された株価チャートの種類に応じて2から4個(オプションの出来高マーカー以外)の異なる値を表します。

24.2.2 一般的なグラフの子タグ

一般的なカスタマイズや関連する子タグの種類は次のとおりです。

- グラフに対するアニメーション効果: dvt:animationOnDisplayおよびdvt:animationOnDataChangeタグ。

- カスタム・アイコンでデータ・ポイントを強調表示するアラート: dvt:alertSetおよびdvt:alertタグ。

- 特定のデータ・ポイントに対する注意事項を挿入する注釈: dvt:annotationSetおよびdvt:annotationタグ。

- グラフの外観とタイトル: dvt:background、dvt:graphFont、dvt:graphFootnote、dvt:graphPlotArea、dvt:graphSubtitleおよびdvt:graphTitleタグ。

- 棒、面、線および円グラフのスライス(系列アイテムとも呼ばれる)の色と外観: dvt:seriesSetおよびdvt:seriesタグ。

- 順序軸やマーカー・ツールチップのカテゴリ別属性の書式設定: dvt:attributeFormat。

- 凡例の外観: dvt:legendArea、dvt:legendTextおよびdvt:legendTitleタグ。

- 各軸に関連するマーカーのカスタマイズ: dvt:markerText、dvt:x1Format、dvt:y1Format、dvt:y2Formatおよびdvt:zFormatタグ。

- 参照線および参照領域: dvt:referenceObjectSetおよびdvt:referenceObjectタグ。

- 棒グラフ、面グラフ、組合せグラフ、折れ線グラフ、レーダー・グラフ、株価チャートで使用される順序軸(カテゴリ軸とも呼ばれる)のグループ・ラベルによるカスタマイズ: dvt:o1Axis、dvt:o1MajorTick、dvt:o1TickLabel、dvt:o1Titleタグ。

- 散布図とバブル・グラフで使用されるX軸の数値ラベルによるカスタマイズ: dvt:x1Axis、dvt:x1MajorTick、dvt:x1TickLabel、dvt:x1MinorTick、dvt:x1Titleタグ。

- Y1軸のカスタマイズ: dvt:y1Axis、dvt:y1BaseLine、dvt:y1MajorTick、dvt:y1TickLabel、dvt:y1MinorTickおよびdvt:y1Titleタグ。

- Y2軸のカスタマイズ: dvt:y2Axis、dvt:y2BaseLine、dvt:y2MajorTick、dvt:y2TickLabel、dvt:y2MinorTickおよびdvt:y2Titleタグ。

24.2.3 グラフ固有の子タグ

グラフ固有のカスタマイズや関連する子タグの種類は次のとおりです。

- dvt:background、dvt:legendArea、dvt:graphPlotArea、dvt:graphPieFrame、dvt:series、dvt:referenceObjectまたはdvt:timeSelectorサブコンポーネントとの組合せでのみグラフに使用されるグラデーション: dvt:specialEffectsおよびdvt:gradientStopStyleタグ。

- グラフのサブコンポーネントに対する相互作用の指定: dvt:shapeAttributesSetおよびdvt:shapeAttributesタグ。

- グラフの数値データ値の書式設定: dvt:sliceLabel、dvt:x1TickLabel、dvt:y1TickLabel、dvt:y2TickLabel、dvt:x1Format、dvt:y1Format、dvt:y2Format、dvt:zFormatおよびdvt:stockVolumeFormat。

- 面、棒、組合せ、線、積上げ棒グラフの時間軸のカスタマイズ: dvt:timeAxisDateFormatおよびdvt:timeSelectorタグ。

- マスター/ディテール・グラフの時間軸の範囲の選択: dvt:timeSelectorタグ。

- パレート・グラフ: dvt:paretoLineおよびdvt:paretoMarkerタグ。

- 円グラフ: dvt:graphPieFrame、dvt:pieFeeler、dvt:sliceおよびdvt:sliceLabelタグ。

- スパークチャート: dvt:sparkItemタグでは、スパークチャートのデータが提供されます。

- 株価チャート: dvt:stockMarker、dvt:stockVolumeformatおよびdvt:volumeMarkerタグ。

24.2.4 子セット・タグ

子セット・タグは次のとおりです。

- dvt:alertSetタグ: エラーや警告など、個別の記号で強調表示する必要のある追加データ・ポイントを定義するdvt:alertタグをラップします。

- dvt:annotationSetタグ: グラフ上に注釈を定義するdvt:annotationタグをラップします。注釈は、グラフ上の特定のデータ・ポイントと関連付けられます。

- dvt:referenceObjectSetタグ: グラフに対する参照線または参照領域を定義するdvt:referenceObjectタグをラップします。指定したグラフに対して参照オブジェクトをいくつでも定義できます。

- dvt:seriesSetタグ: グラフ上に一連のデータ・マーカーや系列を定義するdvt:seriesタグをラップします。

- dvt:shapeAttributesSetタグ: グラフのサブコンポーネントに相互作用プロパティを指定するdvt:shapeAttributesタグをラップします。

いずれの場合も、設計時にラッパー・タグを最初に作成し、その後、セット内の各アイテムの関連タグを作成する必要があります。例24-2に、アラート・タグのセットを作成して面グラフの2つのアラート・ポイントを定義する場合のタグの順序を示します。

例24-2 アラート・タグのセットのサンプル・コード

<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>

24.3 グラフのデータ要件の理解

グラフのデータ要件はグラフ・タイプによって異なります。データ要件は次のいずれかです。

- 幾何学的:一部のグラフ・タイプでは、データの表示に特定の数のデータ・ポイントが必要です。たとえば、線には最低2つの点が必要なため、折れ線グラフには最低2グループのデータが必要です。

- 複雑:一部のグラフ・タイプでは、マーカー(グラフで実際にデータを表すコンポーネント)ごとに複数のデータ・ポイントが必要です。たとえば、散布図では、X軸とY軸の交点にマーカーを置けるよう、グループごとに2つの値が必要です。各グループに必要なデータ・ポイントがグラフに使用したデータにない場合、グラフ・コンポーネントでは可能な範囲でグラフを表示します。

- 論理的:一部のグラフ・タイプでは特定の種類のデータを受容しません。次に例を示します。

- 負のデータ:円グラフまたはパーセンテージ棒グラフ、折れ線グラフ、面グラフには負のデータを渡すことはできません。パーセンテージ・グラフでは負のデータに対するマーカーは表示されません。

- nullまたはゼロのデータ:nullデータに対するマーカーは生成されないため、nullデータのマーカーは表示されません。また、グラフがゼロ・データを受け取り、軸線がゼロにある場合、マーカーは見えません。ただし、軸線がゼロ以外にある場合、ゼロ・マーカーは見えます。

- 不十分なデータ・セット(系列): 二重Yグラフでは、Y軸ごとにデータ・セットが必要です。通常、セットごとに異なる情報を表します。たとえば、Y1軸は特定の国および期間の売上げを表し、Y2軸はすべての国の売上げ合計を表します。Y軸データを1セットのみ渡した場合、グラフは2つの異なるY軸にデータを表示できません。データは1つのY軸に表示されます。

類似するグラフは、類似するデータ要件を共有します。たとえば、面グラフというカテゴリでは、次のようにグラフをグループ分けできます。

- 絶対面グラフ。

- 積上げ面グラフ。

- パーセンテージ面グラフ。

24.3.1 面グラフのデータ要件

面グラフは、データが塗りつぶされた領域で表されるグラフです。次の種類の面グラフが使用できます。

- 絶対: 各面マーカーは、一連の(2つ以上の)データ値を結びます。この種のグラフのバリエーションとして、単一Yの絶対面グラフと分割二重Yの絶対面グラフがあります。
分割二重Yグラフでは、描画エリアが2つのセクションに分割され、異なるY軸に割り当てられたデータ・セットは異なる描画エリアに表示されます。

- 積上げ: 面マーカーが積み上げられます。各データ・セットの値は前のセットの値に加算されます。積層のサイズが累積合計を表します。この種のグラフのバリエーションとして、単一Yの積上げ面グラフと分割二重Yの積上げ面グラフがあります。

- パーセンテージ:面マーカーは、すべてのデータ・セットの累積合計に対する割合を表します。

面グラフのデータのガイドラインは次のとおりです。

- 面グラフには最低2グループのデータが必要です。グループは、すべての面マーカーを通る横軸に沿った位置で表されます。3か月間のデータを示すグラフでは、このグループにJan、FebおよびMarなどのラベルが付けられます。

- 面グラフには1つ以上のデータ系列が必要です。塗りつぶされた領域はデータの系列またはセットを表し、アメリカ、ヨーロッパ、アジアなどの凡例テキストでラベルが付けられます。

- パーセンテージ面グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

24.3.2 棒グラフのデータ要件

棒グラフは、データが一連の棒として表されるグラフです。次の種類の棒グラフが使用できます。

- 集合: 棒の各まとまりが1グループのデータを表します。たとえば、データが従業員で分類されている場合、特定の従業員の給与の棒と歩合の棒が1つのまとまりとなります。この種のグラフのバリエーションとして、集合縦棒グラフと集合横棒グラフがあります。集合棒グラフのすべてのバリエーションは、単一Yグラフ、二重Yグラフおよび分割二重Yグラフにできます。

- 積上げ: 各データ・セットの棒が前のデータ・セットに追加されます。積層のサイズがデータの累積合計を表します。この種のグラフのバリエーションとして、積上げ縦棒グラフと積上げ横棒グラフがあります。積上げ棒グラフのすべてのバリエーションは、単一Yグラフ、二重Yグラフおよび分割二重Yグラフにできます。

- パーセンテージ: 棒が積み上げられ、すべてのデータ・セットの累積合計に対する特定のデータ・セットの割合が表されます。パーセンテージ棒グラフは、単一Yグラフにのみできます。

棒グラフのデータのガイドラインは次のとおりです。

- パーセンテージ棒グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

24.3.3 バブル・グラフのデータ要件

バブル・グラフは、データが円形のデータ・マーカー(バブル)の位置とサイズで表されるグラフです。バブル・グラフの各データ・マーカーは3グループの値を表します。

- 1つ目のデータ値はX値です。マーカーのX軸上の位置を決めます。

- 2つ目のデータ値はY値です。マーカーのY軸上の位置を決めます。

- 3つ目のデータ値はZ値です。マーカーのサイズを決めます。

使用可能なバブル・グラフの種類は、単一Yのバブル・グラフと二重Yのバブル・グラフです。

バブル・グラフのデータのガイドラインは次のとおりです。

- バブル・グラフでは、1つのデータ・マーカーにつき最低3つのデータ値が必要です。

- 複数グループのデータの場合、バブル・グラフでは3の倍数のデータが必要です。たとえば、特定のバブル・グラフで、Parisに3つ、Tokyoに3つなどのように値が必要です。3つの値の例には、X値が平均寿命、Y値が平均所得、Z値が人口を表す場合などがあります。

注意:

バブル・グラフを見る際、マーカーのツールチップを確認することでデータ・グループを特定できます。ただし、グループを特定することは、データ・マーカーの全体的なパターンをつかむことに比べると重要ではありません。

24.3.4 組合せグラフのデータ要件

組合せグラフでは異なるタイプのデータ・マーカーを使用して異なるデータ・セットを表示します。使用されるデータ・マーカーは、棒、面および線です。

組合せグラフのデータのガイドラインは次のとおりです。

- 組合せグラフには最低2セットのデータが必要です。そうでない場合、異なるマーカー・タイプを表示できません。

- 組合せグラフには最低2グループのデータが必要です。そうでない場合、面マーカーまたは線マーカーをレンダリングできません。

24.3.5 ファンネル・グラフのデータ要件

ファンネル・グラフは、プロセスのステップに関連するデータを視覚的に表したものです。ファンネルの特定のステップ(スライス)の値がそのスライスの割当てに近付いた分、スライスが塗りつぶされます。ファンネルは目標値、実績値およびレベルを色で表す3次元のチャートをレンダリングします。ファンネル・グラフでは、目標値を100%としてデータを表します。したがって、実績値が50で目標値が200の場合、スライスの25%が塗りつぶされます。

ファンネル・グラフのデータのガイドラインは次のとおりです。

- ファンネル・グラフには2つの系列(データ・セット)が必要です。これらの2セットのデータは、目標データ値と実績データ値となります。しきい値はグラフの凡例に表示されます。
ファンネル・グラフの別のバリエーションの場合、1セットのデータのみで構いません。表示されるデータ値は、合計値のパーセンテージになります。このタイプのファンネル・グラフを作成するには、グラフのfunnelPercentMeasureプロパティをTrueに設定する必要があります。この設定は、グラフのXMLで実行してください。

- ファンネル・グラフでは、最低1グループのデータをステージとして使用する必要があります。

24.3.6 折れ線グラフのデータ要件

折れ線グラフは、データを線、一連のデータ・ポイントまたは線で結ばれたデータ・ポイントとして表します。次の種類の折れ線グラフが使用できます。

- 絶対: 各線セグメントは2つのデータ・ポイントを結びます。この種のグラフでは、軸を単一Y、二重Yおよび分割二重Yにできます。

- 積上げ: 各データ・セットの線が前のデータ・セットに追加されます。積層のサイズがデータの累積合計を表します。この種のグラフでは、軸を単一Y、二重Yおよび分割二重Yにできます。

- パーセンテージ: 線が積み上げられ、各線がすべてのデータ・セットの累積合計に対する特定のデータ・セットの割合を表します。パーセンテージ折れ線グラフは、単一Yグラフにのみできます。

折れ線グラフのデータのガイドラインは次のとおりです。

- 線には最低2つの点が必要なため、折れ線グラフには最低2グループのデータが必要です。グループは各色のマーカーで表されます。グループには、月の名前などのティック・ラベルが付けられます。

- パーセンテージ折れ線グラフは負の数値を持つことができません。

- 二重Yグラフには2セットのデータが必要です。

24.3.7 パレート・グラフのデータ要件

パレート・グラフは、不具合の原因を特定することを目的として設計されています。パレート・グラフでは、一連の棒が異なる不具合の原因を表します。これらの棒は値の大きい方から順に並べられます。線は、グラフのすべての棒の合計値に対する棒の累積割合を示します。線は常に100%で終わります。

パレート・グラフは常に二重Yグラフです。Y1軸は棒が表す値に対応します。Y2軸は累積パーセンテージ値に対応します。

パレート・グラフのデータのガイドラインは次のとおりです。

- パレート・グラフには最低2グループのデータが必要です。

- パレート・グラフは負の数値を持つことができません。

- パレート・グラフに複数セットのデータを渡した場合、最初のデータ・セットのみが使用されます。

- パレート・グラフに対するデータの一部としてパーセンテージ値を渡さないでください。グラフは渡されたデータを基にパーセンテージを計算します。

24.3.8 円グラフのデータ要件

円グラフは、1つ以上の円の扇型円弧としてデータが表され、円がカットされたパイのように見えます。次の種類の円グラフが使用できます。

- 円:各円の中心は埋まっています。円グラフは、1つまたは複数の円で構成されます。

- ドーナツ:各円の中心が空いており、ここにパイの合計値が表示されます。ドーナツ・グラフは、1つまたは複数の輪で構成されます。

円グラフのデータ構造は次のとおりです。

- 各円またはドーナツは1グループのデータを表し、月の名前などのラベルが付きます。1グループのデータのみの場合、複数円または複数ドーナツ・グラフ・タイプを選択しても、1つの円またはドーナツのみが表示されます。また、すべてのデータがゼロのグループがある場合、そのグループに対する円またはドーナツは表示されません。

- データの系列またはセットは、すべて同じ色のスライスで示されます。各データ・セットの凡例テキストが表示されます。たとえば、国別のデータ・セットがある場合、各国の名前が凡例テキストに表示されます。

円グラフのデータのガイドラインは次のとおりです。

- 円グラフは負の数値を持つことができません。

- 複数円グラフには最低2グループのデータが必要です。

24.3.9 極グラフのデータ要件

ポーラー・グラフは、円形の散布図です。極グラフでは、散布図同様、データがデータ・マーカーの位置で表されます。極グラフでは、マーカーが表示される描画エリアは円形です。散布図の詳細は、24.3.11項「散布図のデータ要件」を参照してください。

散布図同様、極グラフは、多数のデータ項目間の全体的な関連性を示す場合に特に有用です。データに方向性がある場合は、散布図ではなく、極グラフを使用してください。

極グラフの各データ・マーカーは2つのデータ値を表します。

- 1つ目のデータ値はX値です。これは、X軸に沿ったマーカーの位置を決定します。時計回りで円の周囲の位置になります。

- 2つ目のデータ値はY値です。これは、Y軸に沿ったマーカーの位置を決定します。グラフの中心からの距離になります。

極グラフのデータのガイドラインでは、各マーカーに最低2つのデータ値が必要です。

24.3.10 レーダー・グラフのデータ要件

レーダー・グラフは、多角形の折れ線グラフで、円形の散布図である極グラフと似ています。過去3年間の月ごとの売上げなどの周期的に起こるパターンを表す場合に、レーダー・グラフを使用します。

レーダー・グラフのデータ構造は次のとおりです。

- 多角形の辺の数とデータのグループの数は同数です。多角形の各角がグループを表します。

- データの系列またはセットは、線またはすべて同じ色のマーカー、あるいはその両方で示されます。凡例テキストでラベル付けされます。

レーダー・グラフのデータのガイドラインとして、最低3グループのデータが必要です。

24.3.11 散布図のデータ要件

散布図は、データをデータ・マーカーの位置で表します。散布図は、多数のデータ・ポイント間の全体的な関連性を示す場合に特に有用です。たとえば、特定の製品の売上げと利益の関連性を調べる場合に散布図を使用できます。

散布図は単一Yまたは二重Yにできます。散布図の各データ・マーカーは2つの値を表します。

- 1つ目のデータ値はX値です。マーカーのX軸上の位置を決めます。

- 2つ目のデータ値はY値です。マーカーのY軸上の位置を決めます。

散布図のデータのガイドラインは次のとおりです。

- 散布図には、マーカーごとに2つのデータ値が必要です。

- 複数グループのデータの場合、データは2の倍数である必要があります。

24.3.12 スパークチャートのデータ要件

スパークチャートは、単一系列のデータ値での傾向や変化の表示に使用されます。これは、簡単な視覚化要約チャートで、テキストを付けて表にスタンプされるか、インラインで使用されるように設計されています。スパークチャートにはラベルがないため、表の隣接する列や周囲のテキストにより、スパークチャートのコンテンツのコンテキストが示されます。

スパークチャートでは、表形式データやgraphDataModelは受け入れられません。スパークチャートのデータのガイドラインは次のとおりです。

- 折れ線スパークチャート、棒スパークチャートおよび面スパークチャートには、単一系列のデータ値が必要です。図24-4に、表の列の折れ線スパークチャートの例を示します。

図24-4 折れ線スパークチャート

- フローティング棒スパークチャートには、データ値の系列がフローティング・オフセットに1つ、棒の値のために1つの合計2つ必要です。図24-5に、表の列内のフローティング棒スパークチャートの例を示します。

図24-5 浮動棒スパークチャート

24.3.13 株価チャートのデータ要件

株価チャートでは、株価を表示し、必要に応じてグラフに1つ以上の株式の取引出来高も表示できます。いずれかの株式またはローソク足株価チャートが出来高を含む場合、出来高はグラフの下部に棒で表示されます。

ローソク足株価チャートは株価を表し、オプションで1つの株の出来高を表示します。ローソク足株価チャートが出来高を含む場合、出来高はグラフの下部に棒で表示されます。

ローソク足株価チャートでは、始値と終値のうち低い方の値がローソクの下端で示されます。高い方の値がローソクの上端で示されます。終値が始値より高い場合、ローソクは緑色です。始値が終値より高い場合、ローソクは赤色です。

24.3.13.1 株価チャート: 高値-安値-終値

高値-安値-終値株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、高値、安値、終値の順の3つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に3つのデータ値、火曜日に3つのデータ値のように、データは3の倍数である必要があります。

- データの系列(セット)は、1つの株を表す同じ色のマーカーで示されます。系列はA株のように凡例テキストでラベル付けされます。ローソク株価チャートを除き、株が1つのみの場合でも凡例は表示されます。大半の高値-安値-終値株価チャートの系列は1つのみです。複数の系列を表示し、異なる株の値が重なる場合、株価マーカーによって他の株価マーカーが覆われます。

24.3.13.2 株価チャート: 出来高付き高値-安値-終値

出来高付き高値-安値-終値株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、高値、安値、終値、出来高の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、データは4の倍数で、月曜日の高値、月曜日の安値、月曜日の終値、月曜日の出来高(他の曜日に続く)の順である必要があります。

- 出来高も表示する高値-安値-終値株価チャートでは、1つの株のみのデータを表示できます。この株のラベルはグラフの凡例に表示されます。

24.3.13.3 株価チャート: 始値-高値-安値-終値

始値-高値-安値-終値株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、高値、安値、終値の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に4つのデータ値、火曜日に4つのデータ値のように、データは4の倍数である必要があります。

- データの系列(セット)は、1つの株を表す同じ色のマーカーで示されます。系列はA株のように凡例テキストでラベル付けされます。1つの株のみの場合でも凡例は表示されます。大半の始値-高値-安値-終値株価チャートの系列は1つのみです。複数の系列を表示し、異なる株の値が重なる場合、株価マーカーによって他の株価マーカーが覆われます。

24.3.13.4 株価チャート: 出来高付き始値-高値-安値-終値

出来高付き始値-高値-安値-終値株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、高値、安値、終値、出来高の順の5つのデータ値のグループが必要です。1日以上の株価データを表示する場合、データは5の倍数で、月曜日の始値、月曜日の高値、月曜日の安値、月曜日の終値、月曜日の出来高(他の曜日に続く)の順である必要があります。

- 出来高も表示する始値-高値-安値-終値株価チャートでは、1つの株のみのデータを表示できます。この株のラベルはグラフの凡例に表示されます。

24.3.13.5 ローソク足株価チャート: 始値-終値

始値-終値ローソク足株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、終値の順の2つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に2つのデータ値、火曜日に2つのデータ値のように、データは2の倍数である必要があります。

- データの系列(セット)は、1つの株のマーカーで示されます。ローソク株価チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されません。系列ラベル(株の名前)をグラフのタイトルに表示する必要があります。

24.3.13.6 ローソク足株価チャート: 出来高付き始値-終値

出来高付き始値-終値ローソク足株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、終値、出来高の順の3つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に3つのデータ値、火曜日に3つのデータ値のように、データは3の倍数である必要があります。

- データの系列(セット)は、1つの株のマーカーで示されます。ローソク株価チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されません。系列ラベル(株の名前)をグラフのタイトルに表示する必要があります。

24.3.13.7 ローソク足株価チャート: 始値-高値-安値-終値

始値-高値-安値-終値ローソク足株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、高値、安値、終値の順の4つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に4つのデータ値、火曜日に4つのデータ値のように、データは4の倍数である必要があります。

- データの系列(セット)は、1つの株のマーカーで示されます。ローソク株価チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されません。系列ラベル(株の名前)をグラフのタイトルに表示する必要があります。

24.3.13.8 株価チャート: 出来高付き始値-高値-安値-終値

出来高付き始値-高値-安値-終値ローソク足株価チャートのデータ要件は次のとおりです。

- 各株価マーカーには、始値、高値、安値、終値、出来高の順の5つのデータ値のグループが必要です。1日以上の株価データを表示する場合、月曜日に5つのデータ値、火曜日に5つのデータ値のように、データは5の倍数である必要があります。

- データの系列(セット)は、1つの株のマーカーで示されます。ローソク株価チャートでは、1つの株のみの値を表示できます。このため、これらのグラフには凡例は表示されません。系列ラベル(株の名前)をグラフのタイトルに表示する必要があります。

24.4 グラフの作成

グラフ・コンポーネントの作成には次のデータソースを使用できます。

- ADFデータ・コントロール: ADFデータ・コントロール・パネルからデータ・コレクションをドラッグ・アンド・ドロップして、データバインドされたグラフを宣言的に作成します。『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFグラフの作成に関する項での説明のとおり、行セット・データを持つデータ・コレクションを使用するグラフを作成できます。

- 階層データ: 階層データを提供するデータ・コントロールからグラフを作成できます。ただし、現在のリリースには、グラフでサポートされる階層データ・コントロールの実装は含まれていません。

- 表形式データ: 24.4.1項「表形式データを使用したグラフの作成方法」に示すとおり、tabularData属性を使用してCSV(カンマ区切りの値)データをグラフに使用できます。

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

表形式データからグラフを作成するプロセスのステップは次のとおりです。

- グラフのマネージドBeanのメソッドでの表形式データの格納。

- マネージドBeanに格納された表形式データを使用するグラフの作成。

24.4.1.1 グラフ用の表形式データのマネージドBeanへの格納

dvt:graphコンポーネントのtabularData属性では、グリッドの作成やデータの移入にグラフで使用するデータのリストを指定できます。このリストを作成するには、グラフのデータの系列とグループの理解およびリストの構造の知識が必要です。

24.4.1.1.1 データの系列およびグループ

グラフには、データの系列およびグループが表示されます。系列とグループは、グリッドの行と列にたとえることができます。通常、グリッドの行はグラフの系列として表示され、グリッドの列はグラフのグループとして表示されます。

大半のグラフでは、系列は同じ色のマーカーのセットとして表示されます。通常、グラフの凡例に、各系列の識別子と対応する色が表示されます。たとえば、棒グラフで黄色の棒が靴の売上げを示し、緑色の棒がブーツの売上げを示す、などです。

グループの表示は、グラフ・タイプによって異なります。集合棒グラフでは、各まとまりがグループです。積上げ棒グラフでは、各積層がグループです。複数円グラフでは、各円がグループです。グループは年などの期間を表す場合もあります。グループが地域などの地理上の場所を表す場合もあります。

グラフ・タイプのデータ要件に応じて、1つのグループに複数のデータ値が必要な場合があります。たとえば、散布図では、データ・マーカーごとに2つの値が必要です。1つ目の値はX軸上のマーカーの位置を決め、2つ目の値はY軸上のマーカーの位置を決めます。

24.4.1.1.2 表形式データのリストの構造

表形式データを含むリストは、グラフに渡すデータ値ごとに3メンバーのObject配列で構成されます。各配列のメンバーは次のように編成される必要があります。

- 1つ目のメンバー(索引0)は、データ値のグリッドの列ラベルです。これは通常Stringです。グラフに時間軸がある場合は、Java Dateです。列ラベルは、通常、グラフのグループを識別します。

- 2つ目のメンバー(索引1)は、データ値のグリッドの行ラベルです。これは通常Stringです。行ラベルはグラフで系列ラベルとして、通常、凡例に表示されます。

- 3つ目のメンバー(索引2)はデータ値で、通常Doubleです。

24.4.1.1.3 データのリストの例

図24-6には、2006、2007および2008の3つの列があります。このグラフにはShoesとBootsの2つの行もあります。このデータから、3年間のブーツと靴の年間売上げを比較するグラフが生成されます。

図24-6 年間売上げの比較

例24-3に、3年間の靴とブーツの年間売上げを比較するグラフに必要なデータのリストを作成するコードを示します。

例24-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, 122000, 175000},
{90000, 110000, 150000}
};
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;
}

24.4.1.2 表形式データを使用したグラフの作成

グラフ・タグのtabularData属性を使用して、マネージドBeanのメソッドに格納されたデータを参照します。

マネージドBeanからのデータを使用するグラフを作成する手順:

1. 構造ウィンドウで、graphノードを右クリックして、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「データ」属性カテゴリで、TabularData属性のドロップダウン・メニューをクリックし、「式ビルダー」を選択します。

3. 次のダイアログから検索ボックスを使用してマネージドBeanを特定します。

4. マネージドBeanのノードを展開し、表形式データのリストを含むメソッドを選択します。

5. 「OK」をクリックします。

式ビルダーでは、選択したマネージドBeanのメソッドを参照するよう、tabularData属性が設定されています。たとえば、sampleGraphという名前のマネージドBeanとgetTabularDataという名前のメソッドの場合、tabularData属性には#(sampleGraph.tabularData)と設定されます。

24.4.2 表形式データを使用してグラフを作成する場合の処理

tabularData属性を参照するリストから取得したデータを持つグラフを作成する場合、デフォルトでは集合縦棒グラフが作成されます。表形式データがそのグラフ・タイプのデータ要件を満たすかぎり、graphType属性の設定を50種類以上のグラフのいずれにも変更できます。dvt:graphタグのその他多数の属性の設定も変更できます。

構造ウィンドウでグラフの子タグをdvt:graphノードにドラッグし、属性に設定を指定することでカスタマイズします。

24.4.3 グラフのイメージ形式について

デフォルトでは、グラフは次のイメージ形式を使用して表示されます。

- サポートされる場合は、HTML5が使用されます。

- それ以外では、Flash Playerが可能な場合はFlashが使用されます。HTML5が十分にサポートされないブラウザの場合、Flashも使用されます。

- それ以外は、プラグインがクライアント・マシンで許可されない場合や双方向ロケールでは、ポータブル・ネットワーク・グラフィックス(Portable Network Graphics: PNG)出力形式などがかわりに使用されます。グラフを印刷する場合は、PNG出力形式も使用されます。PNG出力形式を使用する場合、静的レンダリングは十分にサポートされますが、次の特定のインタラクティブ機能は使用できません。

- アニメーション

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

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

- 相互作用力

web.xmlコンテキスト・パラメータ、oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMATを使用してデフォルトの出力形式を変更できます。アプリケーションにこのコンテキスト・パラメータがあり、イメージ形式が指定されていない場合、デフォルトでHTML5に自動で設定されます。グラフのimageFormat属性を使用して、HTML5を明示的に設定します。たとえば、imageFormat="HTML5"のようになります。ブラウザでHTML5が完全にサポートされない場合は、かわりにFlashまたはPNGイメージが使用されます。詳細は、A.2.3.22項「グラフとゲージのイメージ形式」を参照してください。

アプリケーション全体でFlashコンテンツの使用を無効にするには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

グラフがスタンプによってADF表のセルに表示される場合、グラフのimageFormat属性にはPNG_STAMPED設定が必要です。

24.5 グラフ・タイプの変更

データ・コントロール・パネルまたはコンポーネント・パレットを使用してグラフを挿入する場合、コンポーネント・ギャラリに使用できるグラフのカテゴリ、タイプおよびクイック・スタート・レイアウトのオプションが表示され、そこから選択できます。グラフ・タイプを選択すると、そのグラフのsubType属性が設定されます。ファンネル・グラフとレーダー・グラフ以外のすべてのグラフ・タイプを変更できます。

グラフのタイプを変更する手順:

1. 構造ウィンドウで、graphノードを右クリックして、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「共通」属性カテゴリで、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グラフ。

24.6 グラフの外観のカスタマイズ

大部分のADFグラフ・タイプに、カスタマイズ可能な一般的な機能があります。次のタイプのカスタマイズが、大半のグラフ・タイプでサポートされています。

- グラフのデータ値の色、スタイルおよび表示の変更。詳細は、24.6.1項「グラフのデータ値の色、スタイルおよび表示の変更」を参照してください。

- グラフのカテゴリ・データ値および数値データ値の書式設定。詳細は、24.6.2項「グラフのデータ値の書式設定」を参照してください。

- グラフのテキストの書式設定。詳細は、24.6.3項「グラフのテキストの書式設定」を参照してください。

注意:

JDeveloperでは、無効な色の値を避けるため、グラフ要素で色関連の属性を指定する場合に色の選択ダイアログが用意されています。

ビジュアル・エディタでグラフ・コンポーネントを編集する場合、グラフ機能のカスタマイズに対応するために特殊なコンテキスト・メニューやプロパティ・インスペクタのボタンを利用できます。エディタのポップアップにより、カスタマイズするグラフ機能の選択内容が確認されます。たとえば、図24-7に、折れ線グラフの描画エリアに表示されるポップアップを示します。

図24-7 折れ線グラフのビジュアル・エディタのポップアップ

グラフ機能をビジュアル・エディタで選択すると、特殊な編集コンテキスト・メニューを利用できるようになります。図24-8に、折れ線グラフの描画エリアのコンテキスト・メニューを示します。ここから、横方向グリッド・マークのデフォルトの表示を削除するなどの各種オプションを選択できます。コンテキスト・メニューまたはプロパティ・インスペクタのボタンを使用して、特殊な塗りつぶし効果を描画エリアで構成することもできます。グラフ・タグの選択は、ビジュアル・エディタ、構造ウィンドウ、プロパティ・インスペクタおよびソース・エディタで同期しています。

図24-8 折れ線グラフの描画エリアのコンテキスト・メニュー

折れ線グラフの構成の詳細は、24.7.2項「グラフの線の外観の変更」を参照してください。特殊な塗りつぶし効果の構成の詳細は、24.8.2項「24.8.2項「グラフでのグラデーション特殊効果の使用」を参照してください。

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

ほとんどのグラフ・タイプでは、グラフの棒、線、面、ポイント、スライスとして表されるデータ値の各セットに対するエントリが凡例に表示されます。このエントリは関連するデータ値のセットを識別し、グラフ内でのセットの色を示します。たとえば、棒グラフでは、黄色の棒を使用して靴の売上げを示し、緑色の棒を使用してブーツの売上げを示します。グラフ・コンポーネントでは、関連するデータ値の各セットを系列と呼びます。

グラフでは、データ値の各セットに異なる色が自動的に割り当てられます。塗りつぶしや枠の色などの各系列に割り当てられた色はカスタマイズできます。一部のグラフ・タイプの場合、グラフの凡例の系列の表示または非表示を切り替えて、グラフのデータ値の表示をフィルタ処理することができます。

特定のグラフ・タイプでは、折れ線グラフの線の幅やスタイル(実線、点線、ダッシュ線など)といった特性を追加で指定できます。詳細は、24.7.2項「グラフの線の外観の変更」を参照してください。

散布図の場合、系列のデータ・マーカーの形や色を分けて、データ値の関係を表示することができます。詳細は、24.7.4項「散布図の系列マーカーのカスタマイズ」を参照してください。

グラフ内の各系列の色にグラデーション特殊効果を追加してカスタマイズすることもできます。詳細は、24.8.2項「グラフでのグラデーション特殊効果の使用」を参照してください。

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

1つのdvt:seriesSetタグを使用して、グラフの個々のdvt:seriesタグをすべてラップし、グラフのデータ・マーカーの色とスタイルの属性を設定します。

グラフの系列アイテムに色とスタイルを指定する手順:

1. 構造ウィンドウでグラフのノードのdvt:seriesSet子タグを右クリックし、「プロパティに移動」を選択します。

2. 必要に応じてプロパティ・インスペクタを使用し、dvt:seriesSetタグの属性に値を指定します。
このタグの属性によって、セット内のすべての系列タグのデフォルト設定が決まります。ただし、指定した系列のこの設定を、dvt:seriesタグの対応する属性に値を入力することでオーバーライドできます。

3. 構造ウィンドウでseriesSetノードを右クリックし、「dvt:seriesSetの中に挿入」→「系列」と選択します。
最初のdvt:seriesタグが「グラフ・バインディングの作成」ダイアログに表示される最初の系列を表します。

4. プロパティ・インスペクタを使用して、dvt:seriesタグに、必要に応じて色と他の特性を指定します。

5. 系列アイテムごとに、ステップ3とステップ4を繰り返します。

24.6.1.2 系列のアイテムの表示/非表示を有効にする方法

面グラフ、棒グラフ、バブル・グラフ、組合せグラフ、折れ線グラフ、円グラフ、レーダー・グラフおよび散布図などのグラフ・タイプの場合、グラフの系列の表示または非表示を実行時に有効にすることができます。少なくとも1つの系列をグラフに表示する必要がありますが、ユーザーは、対応する凡例アイテムをクリックしてデータ値の表示をフィルタ処理できます。

系列のアイテムの表示/非表示を有効にする手順:

1. 構造ウィンドウで、graphノードを右クリックして、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「外観」属性カテゴリの「系列」セクションで、グラフのhideAndShowBehavior属性を設定します。有効な値は次のとおりです。

- none: デフォルト値。系列の表示および非表示の動作は有効ではありません。

- withRescale: 表示可能な系列のみを表示するようにグラフのサイズを変更します。

- withoutRescale: 系列を非表示にしますが、グラフのサイズは変更しません。

24.6.2 グラフのデータ値の書式設定

データ・コレクションの属性は、データ値またはデータ値のカテゴリになります。データ値は、棒の高さなどのマーカーまたは散布図のポイントで示される数字です。データ値のカテゴリは、順序軸のラベルとして示されるメンバーになるか、ツールチップの追加プロパティとして表示されます。数値属性とカテゴリ属性の両方の書式を設定するには、数値データ値の場合はaf:convertNumber、カテゴリ・データ値の場合はaf:convertNumber、af:convertDateTime、af:convertColorなどのADF Facesコンバータ・タグを使用します。

コンバータ・タグの属性で、パーセントの書式設定、数値の位取り、小数部の桁の制御、記号の配置などを行えます。ADF Facesコンバータ・タグの詳細は、第6章「入力の検証および変換」を参照してください。

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

グラフのカテゴリ・データ値は、グラフのデータ・モデルを定義するページ定義ファイル(<pagename>PageDef.xml)に名前で表されます。例24-4に、従業員の雇用日とボーナスのカテゴリ・データ値を表示するグラフを含むページのページ定義ファイルのXMLコードを示します。

例24-4 ページ定義ファイルのカテゴリ・データ値の名前

<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を使用して、カテゴリ属性の書式を指定できます。

たとえば、例24-4のページ定義で定義される雇用日とボーナスのカテゴリ・データ値の書式を設定できます。

ページ定義ファイルで定義されるカテゴリ・データ値の書式設定の手順:

1. 構造ウィンドウで棒グラフのタグを右クリックし、「dvt:barGraphの中に挿入」→「ADFデータ視覚化」→「属性フォーマット」と選択します。

2. 「名前」属性の場合は、プロパティ・インスペクタでaf1カテゴリ属性の名前にHiredateと入力します。

3. 構造ウィンドウで、指定した属性フォーマット・タグを右クリックし、「dvt:attributeFormatの中に挿入」→「日時の変換」と選択します。

4. 「パターン」属性には、プロパティ・インスペクタでjava.text.SimpleDateFormatに一致する日付/時間の文字列の書式設定パターンを入力します。「TimeZone」属性には、データ文字列のすべての時間情報を解釈するタイムゾーンを入力します。

5. ボーナス・カテゴリ属性には、手順1～4(af2カテゴリ属性の名前にBonusを設定し、af:convertNumberコンバータを追加して、通貨の属性の書式を設定)を繰り返します。

例24-5に、棒グラフのカテゴリ・データ値の書式を設定する場合に生成されるXMLコードを示します。

例24-5 棒グラフのカテゴリ・データ値の書式設定

<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

注意:

順序(O1)軸に表示するカテゴリ・データ値が1つの場合、グラフには時間軸が表示されます。時間軸には、軸上の単一ラベル(2001年6月27日など)とは対照的に、日付が階層形式で表示されます。順序軸で単一ラベルを表示するには、時間軸を無効にする必要があります。たとえば、timeAxisType="TAT_OFF"とdvt:attributeFormatタグを使用して、日付形式を指定します。

24.6.2.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属性を指定して、スライスで表される値を表示し、それに応じて数値の書式を設定します。

円グラフのスライス・ラベルの数値の書式設定手順:

1. 構造ウィンドウで円グラフのタグのdvt:sliceLabel子タグを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、TextType属性ドロップダウン・リストからLD_VALUEを選択して、グラフの円スライスが値を表すように指定します。

3. プロパティ・インスペクタで、「区分ラベルの構成」をクリックして、ドロップダウン・リストから「数値書式」を選択します。

4. af:convertNumberタグには、プロパティ・インスペクタで、通貨記号にドル記号を使用して通貨の値を指定します。

例24-6に、円グラフのスライス・ラベルの数値データ値を通貨として表示するように設定し、ドル記号を使用する場合に生成されるXMLコードを示します。

例24-6 円グラフのスライス・ラベルの数値データ値の書式設定

<pieGraph>
...
<dvt:sliceLabel textType="LD_Value">
<af:convertNumber type="currency" currencySymbol="$"/>
</dvt:sliceLabel>
...
</pieGraph>

ADF Facesのaf:convertNumberタグを使用して、グラフのマーカー・テキストの数値の書式を設定することもできます。

たとえば、グラフの各軸のマーカー・テキストに異なる書式を指定できます。この手順では、af:convertNumberタグを使用してdvt:y1Formatのマーカー・テキストの書式を設定します。

グラフのY1軸に関連するマーカー・テキストの数値を書式設定する手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「マーカー・テキスト」と選択します。

2. プロパティ・インスペクタで、必要に応じてdvt:markerTextの属性に値を入力します。
たとえば、グラフのテキストを表示するには、rendered属性にtrueを選択します。

3. プロパティ・インスペクタで、「マーカーの構成」をクリックして、「Y1フォーマット」を選択します。

4. プロパティ・インスペクタで、必要に応じてdvt:y1Format属性に値を入力します。

5. プロパティ・インスペクタで、「数値書式の構成」をクリックして、af:convertNumberタグの属性に必要な値を指定します。
たとえば、マーカー・テキストの後にパーセンテージ記号を配置するには、type属性にpercent値を選択します。

例24-7に、グラフのY1軸のマーカー・テキストの数値を書式設定する場合に生成されるXMLコードを示します。この例では、数値の後にパーセンテージ記号が続き、マーカーの上にテキストが表示されるように指定されます。たとえば、棒グラフの場合、棒の上にテキストが表示されます。

例24-7 グラフのマーカー・テキストの数値の書式設定

<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にする場合、グラフではパターン属性が消去されます。つまり、グラフでパーセント書式設定が強制される場合、パターンは無視されます。これは、円グラフ、パレート・グラフ、ファンネル・グラフおよびすべての棒グラフ、折れ線グラフ、または面パーセント・グラフに適用されます。

24.6.2.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に設定する場合を除き、無視されます。

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

次のグラフのサブコンポーネントのテキストを書式設定できます。

- 注釈: 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タグを、テキストに書式設定する特定のサブコンポーネントの子として使用します。グラフのテキストの書式設定の例としては、24.6.5.2項「グラフのタイトルと脚注の指定方法」を参照してください。

24.6.3.1 スキンを使用したグラフ・フォントのグローバルな設定方法

アプリケーションのすべてのページに渡ってグラフ・コンポーネントのfont属性をグローバルに設定するには、カスケード・スタイルシート(CSS)を使用してスキンを構築し、そのスキンを使用するようにアプリケーションを構成します。グラフ・コンポーネントで使用されるフォントを定義するスキンを適用すると、アプリケーションのページ数が減り、さらにまとめられます。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属性を指定します。

カスタム・スキンを使用したグラフ・フォントの設定手順:

1. グラフのサブコンポーネントに定義されたスキン・スタイル・セレクタを含むカスタム・スキンをアプリケーションに追加します。次の属性に値を指定できます。

- -tr-font-family: フォント・ファミリ(名前)を指定します。複数のフォントは使用できません。複数のフォントを指定すると、最初のフォントが使用されます。

- -tr-font-size: フォントのサイズを指定します。絶対サイズの単位は次のように定義されます。

- pt: ポイント - CSS2で使用される標準フォント・サイズ。1ポイントは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の色の名前です。ワールド・ワイド・コンソーシアムには、次の17色の有効な名称が記載されています。aqua、black、blue、fuchsia、gray、green、lime、maroon、navy、olive、orange(CSS 2.1)、purple、red、silver、teal、white、yellow。
3、6または8桁のHEX(8桁のHEXでは、アルファ・チャネルは最初の2桁)、RGBまたはRGBAも使用できます。

たとえば、mySkin.cssファイルでグラフのすべてのタイトルにフォント・ファミリを次のように指定します。

af|dvt-graphTitle,
{
-tr-font-family: Comic Sans MS:
}

2. trinidad-skins.xmlファイルでアプリケーションにカスタム・スキンを登録します。たとえば、mySkin.cssは、デフォルトのblafplus-rich.desktopスタイルシートを拡張します。

<?xml version="1.0" encoding="ISO-8859-1"?>
<skins xmlns="http://myfaces.apache.org/trinidad/skin">
<skin>
<id>mySkinExtends.desktop</id>
<family>mySkinExtends</family>
<extends>blafplus-rich.desktop</extends>
<render-kit-id>org.apache.myfaces.trinidad.desktop</render-kit-id>
<style-sheet-name>skins/mySkin.css</style-sheet-name>
</skin>
</skins>

3. カスタム・スキンを使用するようにtrinidad-config.xmlファイルでアプリケーションを構成します。次に例を示します。

<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family>mySkin</skin-family>
</trinidad-config>

4. カスタム・スキンをjarファイルにパッケージ化して、アプリケーションと一緒にデプロイします。スキンを定義し、CSSファイルを参照するtrinidad-skins.xmlファイルは、META-INFディレクトリに内に存在する必要があります。

アプリケーションへのカスタム・スキンの適用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

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

グラフの幅と高さはカスタマイズでき、コンテナのサイズ変更に基づいて動的にサイズ変更することができます。グラフで使用されるスタイルシートを制御することもできます。グラフのこれらの2つの側面は、ともにグラフのinlineStyle属性を使用するという点で関連性があります。

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

dvt:<type>Graphタグの属性の値を指定すると、グラフの初期サイズを指定できます。グラフの動的サイズ変更を指定しない場合、初期サイズが、グラフの唯一の表示サイズです。

グラフが初めて表示される際のサイズを指定する手順:

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「スタイル」属性カテゴリで、グラフ・タグのInlineStyle属性に値を入力します。次に例を示します。

inlineStyle="width:200px;height:200px"

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

JSFページでコンテナのサイズが変更されたときにグラフがサイズ変更されるようにするには、dvt:<type>Graphタグの2つの属性のそれぞれに値を入力する必要があります。この機能用に指定する値は、サイズの異なるブラウザ・ウィンドウの領域を使用するグラフ・コンポーネントの作成にも有用です。

グラフの動的サイズ変更を有効にする手順:

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「動作」属性カテゴリで、DynamicResize属性に「DYNAMIC_SIZE」を選択します。

3. プロパティ・インスペクタの「スタイル」属性カテゴリで、InlineStyle属性の幅と高さの両方に、ピクセルの定数または相対的割合を入力します。
たとえば、コンテナと同じ幅で200ピクセルの高さのグラフを作成するには、inlineStyle属性に"width:100%;height:200px;"と設定します。

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

dvt:<type>Graphタグに使用できる標準スタイルを選択できます。グラフに使用するカスタム・スタイルシートを指定することもできます。

グラフに特定のスタイルシートを選択する手順:

1. グラフに用意されている標準スタイルシートを使用する場合は、次のようにします。

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. 「外観」属性ウィンドウで、style属性ドロップダウン・リストからスタイルシートを選択します。

2. カスタム・スタイルシートを使用する場合は、プロパティ・インスペクタの「スタイル」属性カテゴリで次の属性を設定します。

1. StyleClass属性に対し、「プロパティ」メニュー選択肢から「編集」を選択し、このゲージに使用するCSSスタイル・クラスを選択します。

2. InlineStyle属性の幅と高さに、ピクセルの定数または相対的割合を入力します。
たとえば、コンテナと同じ幅で200ピクセルの高さのグラフを作成するには、inlineStyle属性に"width:100%;height:200px;"と設定します。

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

グラフでは、使用しているスタイルに基づいて、背景と描画エリアにデフォルト設定が自動的に指定されます。これらの設定は、グラフの子タグを使用してカスタマイズできます。

グラフには、タイトル、サブタイトル、脚注のオプションも指定できます。デフォルトでは、タイトルと脚注にはテキストは指定されていません。この情報を入力する際、テキストに使用するフォントとフォント特性も指定できます。

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

グラフの背景と描画エリアに関連する次の箇所をカスタマイズできます。

- 背景:グラフがプロットされる領域。

- 描画エリア:円グラフ以外のすべてのグラフでデータがプロットされるフレーム。描画エリアの最低2つの境界に軸が表示されます。

- 円フレーム:軸を使用しない円グラフがプロットされるフレーム。

グラフの背景と描画エリアをカスタマイズする手順:

1. グラフの背景をカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「背景色」と選択します。

2. プロパティ・インスペクタを使用して、カスタマイズする属性の色をdvt:backgroundタグに入力します。

2. 円グラフ以外のグラフの描画エリアをカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「描画エリア」と選択します。

2. プロパティ・インスペクタを使用して、カスタマイズする属性の色をdvt:graphPlotAreaタグに入力します。

3. 円グラフの描画エリアをカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「円フレーム」と選択します。

2. プロパティ・インスペクタを使用して、カスタマイズする属性の色をdvt:graphPieFrameタグに入力します。

注意:

グラフの背景と描画エリアの色にグラデーション特殊効果を追加してカスタマイズすることもできます。詳細は、24.8.2項「グラフでのグラデーション特殊効果の使用」を参照してください。

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

グラフのタイトル、サブタイトルおよび脚注を指定できます。これらのテキスト・エントリに、グラフの個別の子タグを使用します。これらの各子タグの属性では、テキスト・フィールドの水平方向の位置合せ、テキストの内容と、テキストをレンダリングするかどうかを定義できます。

タイトル、サブタイトルおよび脚注のタグでは、子グラフ・フォント・タグの使用がサポートされ、各テキスト・フィールドに使用するフォント特性を指定できます。

グラフのタイトルと脚注を指定する手順:

1. グラフのタイトルを入力する場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「グラフ・タイトル」と選択します。

2. プロパティ・インスペクタを使用してdvt:graphTitleタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、構造ウィンドウでdvt:graphTitleノードを右クリックし、「dvt:graphTitleの中に挿入」→「フォント」と選択します。

4. プロパティ・インスペクタを使用してdvt:graphFontタグの属性に値を指定します。

2. グラフのサブタイトルを入力する場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「サブタイトル」と選択します。

2. プロパティ・インスペクタを使用してdvt:graphSubtitleタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、構造ウィンドウでdvt:graphSubtitleノードを右クリックし、「dvt:graphSubtitleの中に挿入」→「フォント」と選択します。

4. プロパティ・インスペクタを使用してdvt:graphFontタグの属性に値を指定します。

3. グラフの脚注を入力する場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「脚注」と選択します。

2. プロパティ・インスペクタを使用してdvt:graphFootnoteタグの属性に値を指定します。

3. テキストに特定のフォント特性を指定する場合は、構造ウィンドウでdvt:graphFootnoteノードを右クリックし、「dvt:graphFootnoteの中に挿入」→「フォント」と選択します。

4. プロパティ・インスペクタを使用してdvt:graphFontタグの属性に値を指定します。

24.6.6 グラフの軸とラベルのカスタマイズ

グラフには次の軸を使用できます。

- 順序軸(o1軸とも呼ばれる):グラフの順序(カテゴリ)軸は、レーティングやステージなどの順序付けされたデータを示したり、異なる都市や異なる製品などの名前のデータを示します。順序軸は、棒グラフ、折れ線グラフ、組合せグラフまたはレーダー・グラフに表示されます。順序軸が水平で時間データを含む場合は、時間軸と呼ばれます。
順序軸の例は、縦棒グラフの描画エリアの下部を横切る線です。この軸上の値は、標示されているデータの程度は示しません。そのかわり、データが属する異なるグループを示します。

- X1軸:X1軸は、グラフの横軸に沿って表示される値を示します。この軸は、グループ・ラベルではなく、一定間隔の数値を持ちます。X軸とも呼ばれます。

- Y1軸:Y1軸は、第1Y軸です。通常、描画エリアの左側の縦方向の値軸です。一定間隔の数値を持ちます。

- Y2軸:Y2軸は、第2Y軸です。通常、描画エリアの右側の縦軸です。一定間隔の数値を持ちます。

各軸には、カスタマイズをサポートするいくつかのグラフ子タグがあります。次の項で、軸の様々なカスタマイズに使用できるオプションについて説明します。

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

次のグラフ子タグで、軸のタイトルと外観のカスタマイズがサポートされます。

- タイトル:軸のタイトルのテキストと位置合せを指定します。dvt:o1Title、dvt:x1Title、dvt:y1Titleおよびdvt:y2Titleのタグがあります。適切なタイトル・タグを使用しないと、軸にタイトルは表示されません。

- 軸: 特定のグラフ・タイプの色、線幅、スケーリング、ティック・マーク間の増分、軸の可視性およびスクロールを制御します。dvt:o1Axis、dvt:x1Axis、dvt:y1Axisおよびdvt:y2Axisのタグがあります。

注意:

順序軸には数値は表示されないため、dvt:o1Axisタグにはスケーリング属性はありません。

X1軸のタイトルと外観を指定する手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「X1タイトル」と選択します。

2. プロパティ・インスペクタで、軸のタイトルを入力し、必要に応じてこのタグの他の属性に値を指定します。

3. タイトルのフォント特性を指定する場合は、次のようにします。

1. 構造ウィンドウでdvt:x1Titleノードを右クリックし、「dvt:x1Titleの中に挿入」→「フォント」と選択します。

2. プロパティ・インスペクタで、フォントの特性に値を入力します。

4. 必要に応じて、構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「X1軸」と選択します。

5. プロパティ・インスペクタで、このタグに値を入力します。

他のグラフの軸のタイトルと外観を制御する手順は、X軸に対する手順と似ています。ただし、カスタマイズする特定の軸に関連するタイトルと軸のタグを挿入します。

24.6.6.2 軸のスクロールの指定方法

次のグラフ・タイプでは、グラフの軸のスクロールを指定できます。

- dvt:o1Axis、dvt:y1Axisおよびdvt:y2Axisタグの場合、面グラフ、棒グラフ、折れ線グラフ。

- dvt:x1Axis、dvt:y1Axisおよびdvt:y2Axisタグの場合、バブル・グラフと散布図。

デフォルトでは、グラフの軸のscrolling属性はoffに設定されています。scrolling属性には次の値を指定できます。

- off: スクロールは無効です(デフォルト)。

- on: スクロールは有効です。スクロール・バーが常に存在します。

- asNeeded: スクロールは有効ですが、スクロール・バーは最初は存在しません。グラフをズームするとスクロール・バーが表示され、セッション中は表示されたままになります。

- hidden: スクロールは有効ですが、スクロール・バーは常に非表示になります。ユーザーはパン・スクロールを使用できます。

24.6.6.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子タグを持つこともできます。

順序軸のティック・ラベルの外観を制御する手順:

1. ビジュアル・エディタで、グラフの「O1ティック・ラベル」要素を選択します。
あるいは、構造ウィンドウでdvt:o1Axis要素を選択してから、プロパティ・インスペクタでo1Axisの構成ボタンをクリックして「値ラベル」を選択します。

2. プロパティ・インスペクタで、必要に応じて次のプロパティに値を入力します。

- TextRotation: ティック・ラベルの判読性を高めるために、テキストの回転角度の指定に使用します。

注意:

最適な結果を得るには、90度の倍数の回転角度を使用します。Flashイメージ・タイプの場合、回転したテキストを90度以外の角度でサポートするには埋込みフォントが必要です。埋込みフォントはすべてのロケールで使用できるわけではありません。

- TickLabelSkipMode: ティック・ラベルが順序軸に表示されるかどうか、またその表示方法の指定に使用します。TLS_MANUALで値を設定する場合、オプションでtickLabelSkipCountを使用して、ティック・ラベルとtickLabelSkipFirstとの間に表示するティック・ラベルの数を設定し、スキップする最初のティック・ラベルの索引を設定できます。

3. 必要に応じて、プロパティ・インスペクタで「フォントの構成」ボタンをクリックして、子タグdvt:graphFontのプロパティを設定します。

X軸のティック・マークとティック・ラベルの外観を制御する手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>の中に挿入」→「ADFデータ視覚化」→「X1主ティック」と選択します。

2. プロパティ・インスペクタで、このタグの属性に目的の値を入力し、「ティック・ラベルの構成」ボタンをクリックして、「X1ティック・ラベル」タグをグラフに追加します。

3. プロパティ・インスペクタで、「X1ティック・ラベル」に目的の値を入力し、必要に応じて「フォントの構成」ボタンをクリックして、ティック・ラベルのフォント特性を指定します。

4. グラフの副ティックを指定する場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「X1副ティック」と選択します。

2. プロパティ・インスペクタで、フォントの特性に値を入力します。

注意:

tickStyle属性の場合、GS_NONEまたはGS_AUTOMATIC以外の値を指定する必要があります。

他のグラフの軸のティック・マークの外観を制御する手順は、X軸に対する手順と似ています。ただし、主ティックとラベルのタグをカスタマイズして、カスタマイズする特定の軸に関連する副ティックを挿入します。

24.6.6.4 軸の数値の書式設定方法

dvt:markerTextタグで、軸の数値の書式を制御できます。dvt:markerTextの子タグ(dvt:x1Format、dvt:y1Formatおよびdvt:y2Format)で特定の軸の数値書式をラップします。

これらの軸の数値を書式設定するには、24.6.2項「グラフのデータ値の書式設定」に示す、適切な軸に対する子タグを挿入します。

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

Y軸にはdvt:y1Axisとdvt:y2Axisというグラフ子タグがあり、軸の最初の値がサポートされます。二重Yグラフの各Y軸に異なるスケーリングを指定できます。たとえば、Y1軸は売上数量(単位: 100)を表し、Y2軸は売上高(単位: 1000ドル)を表すことができます。

散布図やバブル・グラフなどの一部のグラフには、最小値や最大値も設定可能なdvt:x1Axis子タグが含まれています。

Y1軸の最初の値を指定する手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「Y1軸」と選択します。

2. プロパティ・インスペクタで、Y1軸の最初の値をAxisMinValueフィールドに入力します。

3. AxisMinAutoScaledフィールドで、属性ドロップダウン・リストから「false」を選択します。
最小値が適用されるようにするには、この属性を設定する必要があります。

Y2軸の最初の値を設定するには、同様の手順を使用しますが、グラフの子としてdvt:y2Axisタグを挿入します。

24.6.7 グラフの凡例のカスタマイズ

グラフ・コンポーネントには、凡例をカスタマイズする次の種類の子タグが用意されています。

- グラフに関連する凡例エリアの色、枠線、可視性、位置およびスクロール性を指定するdvt:legendAreaタグ。

- 凡例の色付けされた各エントリに関連するテキストのフォント特性と位置を指定するdvt:legendTextタグ。

- 凡例エリアのオプションのタイトルとフォント特性を指定するdvt:legendTitleタグ。

凡例エリア、凡例テキストとタイトルをカスタマイズする手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「凡例エリア」と選択します。

2. プロパティ・インスペクタを使用して、このタグの属性に値を指定します。たとえば、凡例エリアには次の属性を指定できます。

- AutomaticPlacementおよびPosition: グラフの右または下部にある凡例エリアの自動位置設定を、デフォルト値AP_ALWAYSで指定します。値をAP_NEVERで設定するには、凡例エリアの位置設定に使用されるposition属性の値が必要です。

- Scrolling: 値asNeededを使用して、必要な領域が使用可能な領域を超える場合の凡例エリアのスクロールを指定します。デフォルトでは、値はoffに設定されています。

- PositionHint: 値alignToCenterを使用して、描画エリアの中央方向に凡例の位置を指定します。デフォルトでは、値は、グラフ枠のエッジ方向へ凡例を配置するalignToEdgeに設定されます。

3. 凡例テキストをカスタマイズする場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「凡例テキスト」と選択します。

2. プロパティ・インスペクタを使用して、このタグの属性に値を入力します。

3. dvt:legendTextノードを右クリックし、「dvt:legendTextの中に挿入」→「フォント」と選択します。

4. プロパティ・インスペクタを使用して、フォント・タグの属性に値を指定します。

4. 凡例のタイトルを入力する場合は、次のようにします。

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「凡例タイトル」と選択します。

2. プロパティ・インスペクタを使用して、このタグの属性に値を入力します。

3. dvt:legendTextノードを右クリックし、「dvt:legendTitleの中に挿入」→「フォント」と選択します。

4. プロパティ・インスペクタを使用して、フォント・タグの属性に値を指定します。

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

ツールチップは、データ・マーカーのIDや詳細情報を表示するのに便利です。markerTextを表示する領域のない小さいグラフには非常に便利です。タイトル、サブタイトル、脚注、凡例テキストおよび注釈などのテキストが切り捨てられる場合は、そのコンポーネントのツールチップがグラフに自動的に表示されます。

ほとんどのグラフで、データ・マーカー上にカーソルを置くと、ツールチップが表示されます。折れ線グラフまたは面グラフでは、線上や面上のみでなく、線や面のデータ・マーカー上または角にカーソルを移動する必要があります。

各グラフ・マーカー(棒など)が情報付ツールチップを表示するように指定できます。グラフのツールチップのカスタマイズには、次のグラフの属性が使用できます。

- MarkerTooltipType: マーカー(棒など)にツールチップを表示するかどうかを指定し、ツールチップに表示する情報の種類を特定します。テキストのみ、値のみ、あるいはテキストと値の情報を表示できます。特定のグラフ・タイプでは、積上げグラフ・マーカーごとに累積データ値を表示したり、円グラフのスライス・マーカーごとに割合のデータを表示できます。

- SeriesTooltipLabel: 凡例に表示される値のセットごとにツールチップを表示するかどうかを指定します。この属性では、系列ツールチップに表示される情報の種類も制御されます。たとえば、系列全体を示す一般的な語(「製品」など)のテキストを表示するか、系列の特定のメンバーを示す特定の語(特定の製品名など)のテキストを表示するかを選択できます。

注意:

グラフでは、グラフのmarkerTooltipType属性にテキストを含む設定が行われている場合のみ、系列のツールチップ・ラベルが表示されます。

- GroupTooltipLabelType: 軸に沿ってデータ・グループにツールチップ・ラベルを表示するかどうかを指定します。たとえば、特定の製品の売上げが年ごとまたは四半期ごとにまとめられているとします。グループ全体を示す一般的な語(「時間」など)のテキストを表示するか、グループの各メンバーを示す特定の語(四半期を表すQ1、Q2、Q3、Q4など)のテキストを表示するかを選択できます。

グラフのmarkerTooltipTemplate属性をトークン化された文字列に設定することで、グラフ内のすべてのマーカー・ツールチップの書式をすばやく設定できます。属性は、あらかじめ定義されたトークンのセットをいくつでも含めることができる文字列を受け入れます。次に例を示します。

<dvt:lineGraph markerTooltipTemplate="Template Based Tooltip NEW_LINE SERIES_LABEL GROUP_LABEL NEW_LINE Value: Y_VALUE"/>

表24-1で、サポートされるトークンについて説明します。

表24-1 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

積上げパーセント・グラフまたはパレート・グラフの累積パーセンテージ値。

グラフのcustomToolTipCallback属性を使用して、オブジェクトごとに異なるツールチップを指定できます。次に例を示します。

<dvt:graph id="g2" customToolTipCallback="#{customToolTipCallback.callback}"

24.7 特定のグラフ・タイプの外観のカスタマイズ

グラフ・コンポーネントでは、50以上のグラフ・タイプがサポートされます。一部のグラフ属性といくつかの子タグは、特定のグラフ・タイプにのみ関連します。

24.7.1 円グラフの外観の変更

円グラフの外観をカスタマイズできます。また、円グラフの1つのスライスを他のスライスから切り離すよう指定できます。

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

円グラフの外観は、グラフ・タグ内に次の子タグを挿入することでカスタマイズできます。

- dvt:pieFeelerタグ: 円グラフのスライスからスライス・ラベルへ延びる線(引出線と呼ばれる)の色を指定します。

- dvt:sliceタグ: 円グラフのスライスのラベルの位置を指定します。

- dvt:sliceLabelタグ: 円グラフまたはドーナツ・グラフの各スライスを説明するラベルの特性を指定します。各スライスはデータ値を表します。このタグのtextType属性を使用して、スライス・ラベルにテキストのみを表示するか、割合のみを表示するか、テキストと割合を表示するかを示します。数値を書式設定する場合やフォント特性を指定する場合は、dvt:sliceLabelタグ内にdvt:graphFontおよびaf:convertNumberタグを子として追加します。

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

円グラフで1つのスライスが他のスライスから切り離されている場合、この表示は円グラフのスライスの切離しと呼ばれます。1つのスライスを切り離すのはそのスライスを強調表示するためで、グラフ内で最も大きい分量が割り当てられていることもあります。

円グラフのスライスは、グラフの凡例で示されるデータのセットです。したがって、スライスは円グラフの系列アイテムです。

作業を始める前に、次のようにします。

24.6.1.1項「個々の系列アイテムの色とスタイルの指定方法」の手順に従い、個々の系列アイテムをラップする系列セットを作成します。

円グラフの1つのスライスをカスタマイズする手順:

1. 24.6.1.1項「個々の系列アイテムの色とスタイルの指定方法」の手順に従い、個々の系列アイテムをラップする系列セットを作成します。

2. 円グラフの1つのスライスを切り離すには、プロパティ・インスペクタで、円グラフから切り離すスライスを示すseriesタグのPieSliceExplode属性に、0から100の値を設定します。100が、使用できる最大の切離し距離です。

3. 円グラフのスライスにアニメーションを使用するには、プロパティ・インスペクタで、dvt:pieGraphタグのInteractiveSliceBehavior属性を設定します。次の値の任意の組合せが有効です。

- none: インタラクティブなスライスの動作は有効ではありません。

- explode: クリックすると、円グラフのスライスが切り離されます。

- explodeAll: Explode AllおよびUnite Allオプションをコンテキスト・メニューに追加します。

たとえば、次のコードでは、ユーザーが円グラフのスライスを切り離し、コンテキスト・メニューを使用して、グラフのすべてのスライスの切離しや結合を指定できます。

<dvt:pieGraph interactiveSliceBehavior="explode explodeAll"/>

注意:

Flashイメージ形式で使用できる属性はinteractiveSliceBehaviorのみです。また、pieSliceExplode属性は、すべてのイメージ形式で使用できます。

24.7.2 グラフの線の外観の変更

グラフ・タグの子dvt:seriesSetの属性を使用して、グラフの線の外観を変更できます。

24.7.2.1 グラフにデータ線またはマーカーを表示する方法

折れ線グラフ、組合せグラフまたはレーダー・グラフには、データ線またはデータ・マーカーを表示できます。データ線ではなく、マーカーを表示する場合、マーカーが凡例に自動的に表示されます。

プロパティ・インスペクタで、dvt:seriesSetタグの次の属性を設定して、データ線またはデータ・マーカーを表示します。

- LineDisplayed: グラフにデータ線を表示するかどうかを指定します。次の値を設定できます。

- Trueは、グラフにデータ線が表示されることを示します。

- Falseは、グラフにデータ線ではなく、マーカーが表示されることを示します。

- MarkerDisplayed: グラフにマーカーまたはデータ線を表示するかを指定します。次の値を設定できます。

- Trueは、グラフにマーカーが表示されることを示します。

- Falseは、グラフにデータ線が表示されることを示します。

注意:

lineDisplayed属性とmarkerDisplayed属性はどちらもFalseに設定しないでください。

24.7.2.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タグの使用の詳細は、24.6.1.1項「個々の系列アイテムの色とスタイルの指定方法」の手順を参照してください。

24.7.3 パレート・グラフのカスタマイズ

パレート・グラフは、一連の棒を使用して不具合の原因を示します。棒は値の大きい方から小さい方に順に並べられます。パレート線は、グラフのすべての棒の合計値に対する棒の累積割合を示します。線は常に100%で終わります。

パレート線とパレート・マーカーは、次のグラフの子タグを使用してカスタマイズできます。

- dvt:paretoLineタグ: 色、線幅と線のスタイル(実線、ダッシュ線、点線、ダッシュと点の組合せなど)を指定できます。

- dvt:paretoMarkerタグ: パレート・マーカーの形状を指定できます。

パレート・グラフをカスタマイズする手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「パレート線」と選択します。

2. プロパティ・インスペクタで、このタグの属性に値を指定します。

3. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「パレート・マーカー」と選択します。

4. プロパティ・インスペクタで、markerShape属性に値を選択します。

24.7.4 散布図の系列マーカーのカスタマイズ

散布図では、系列の関連データ値は、データ・マーカーの形や色で表されます。系列のマーカーの形や色を分類して、データ値の関係を表示できます。

たとえば、図24-9に、City属性やProduct属性をまとめて使用して、データ・マーカーの形や色で表される系列を決定する散布図を示します。

図24-9 系列マーカーを使用する散布図

行ヘッダー属性を使用して、系列のデフォルトの仕様をオーバーライドできます。図24-10に、City属性のデータ値が形にマップされ、Product属性が色にマップされて表示される散布図を示します。

図24-10 系列アイテム・マーカーを使用する散布図

次の属性を使用して、散布図の系列マーカーをカスタマイズします。

- markerShape: マーカーの色の設定に使用する行ヘッダー属性名を指定します。この属性を指定しない場合、グラフには、デフォルトの索引ベースの系列マーカーの色が表示されます。

- markerColor: マーカーの形の設定に使用する行ヘッダー属性名を指定します。この属性を指定しない場合、グラフには、デフォルトの索引ベースの系列マーカーの形が表示されます。

たとえば、次のコードを使用して、CityおよびProductを個別の系列アイテム・マーカーで指定します。

<dvt:scatterGraph markerColor="Product" markerShape="City" value="#{bindings.View1.graphModel}"/>

24.8 特殊な機能のグラフへの追加

グラフのカスタマイズ機能には、系列に関連する参照線や軸に関連する参照領域を定義する機能、グラデーション特殊効果をグラフの数箇所に追加するオプション、グラフの一部を透明色に設定するオプション、およびグラフでのアラートと注釈の使用などがあります。これらの特別な機能では、グラフのインタラクティブな機能を使用することもできます。

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

参照線および領域は、系列や軸の数や関連付けにかかわらず、常に表示する、ロールオーバーのみに表示する、または表示しない設定が可能です。

系列(グラフの凡例で1つの色で表示されるデータ値のセット)に関連付けられる参照線を作成できます。参照線付きの系列が複数ある場合、カーソルを系列マーカーまたは対応する系列凡例アイテム上に移動したときのみ参照線が表示されます。これは、複数の参照線はユーザーにとって紛らわしいからです。

軸に関連付ける参照領域を作成することもできます。通常、これらの領域はY軸に関連付けられます。複数の参照領域がある場合、カーソルを関連する軸上に移動すると、これらの領域も表示されます。

実行時までアプリケーションで必要な参照線と領域の数がわからない場合、参照線と領域を実行時に動的に作成することができます。

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

参照線も参照領域も、次のタグを使用して作成されます。

- dvt:referenceObjectSet: このグラフの参照線または参照領域のすべての参照オブジェクト・タグをラップします。

- dvt:referenceObject: タグが参照線を表すか、参照領域を表すかを示し、タグの特性を指定します。

設計時に参照線または領域をグラフに追加する手順:

1. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「参照オブジェクト・セット」と選択します。

2. 参照領域(特定の軸に関連付けられている)を定義した場合、適切な軸または軸の属性(displayX1、displayY1またはdisplayY2)に値を指定します。
値RO_DISPLAY_AUTOMATICは、関連付けられている軸上にマウスが移動したときにのみ参照領域が表示されるようにします。これを選択すると、複数の参照領域が一度に表示されて混乱を招くことがなくなります。

オプションで、グラデーション特殊効果を参照領域に適用できます。詳細は、24.8.2.1項「グラデーション特殊効果のグラフへの追加方法」を参照してください。

3. 構造ウィンドウでdvt:referenceObjectSetノードを右クリックし、「dvt:referenceObjectSetの中に挿入」→「参照オブジェクト」と選択します。

4. プロパティ・インスペクタで次のようにします。

1. 「共通」属性カテゴリで、参照オブジェクトのindex属性に値を指定し、参照オブジェクトのtype属性にRO_LINEまたはRO_AREAを指定し、association属性に関連付けるオブジェクト(参照線の場合は系列、参照領域の場合は特定の軸)を指定します。また、displayedInLegend属性を使用してオブジェクトを凡例に表示するかどうかを指定し、凡例に表示するテキストがある場合はこれを指定します。

2. 参照線を作成する場合、線に関連する属性に値を指定します。これには、線が関連付けられる系列の番号の指定も含まれます。系列番号は、グラフ・データ・バインディング・ダイアログに系列が表示される順番のことです。

3. 参照領域を作成する場合、指定した軸の参照領域を示す高低の値を指定します。

5. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

6. プロパティ・インスペクタで「外観」属性カテゴリを選択し、次のようにして参照線と参照領域の表示を制御します。

1. 参照線(系列に関連付けられている)を定義した場合、dvt:seriesノードを開き、displaySeries属性の動作の値を指定します。
値RO_DISPLAY_AUTOMATICは、カーソルが系列アイテム(棒など)またはグラフの凡例の対応する下位列エントリの上に移動したときにのみ参照線が表示されるようにします。これを選択すると、複数の系列の参照線が一度に表示されて混乱を招くことがなくなります。

2. 参照領域(特定の軸に関連付けられている)を定義した場合、参照オブジェクトと適切な軸を関連付けます。

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

設計時に参照線または領域を作成すると、JSFページのグラフのXML内にXMLコードが生成されます。参照オブジェクト(線も領域も)は、dvt:referenceObjectSetタグでラップされます。例24-8に、Y1軸に関連付けられている3つの参照領域、Y2軸に関連付けられている1つの参照領域と、異なる系列に関連付けられている4つの参照線のコードを示します。

例24-8 グラフの参照線と領域のXMLコード

<dvt:barGraph value ="#{sampleGraph.graphDataModel}" graphType="BAR_VERT_CLUST2Y"
imageFormat="FLASH">
<dvt:referenceObjectSet
displayX1="RO_DISPLAY_AUTOMATIC"
displayY2="RO_DISPLAY_AUTOMATIC"
<dvt:referenceObject index="1" type="RO_AREA" association="Y1AXIS"
location="RO_BACK" color="#55FF0000" lowValue="0" highValue="4000"
displayedInLegend="true" text="Low"/>
<dvt:referenceObject index="2" type="RO_AREA" association="Y1AXIS"
location="RO_BACK" color="#55FFFF00"  lowValue="4000" highValue="10000"
displayedInLegend="true" text="Medium"/>
<dvt:referenceObject index="3" type="RO_AREA" association="Y1AXIS"
location="RO_BACK" color="#5500FF00"  lowValue="10000" highValue="18000"
displayedInLegend="true" text="High"/>
<dvt:referenceObject index="4" type="RO_AREA" association="Y2AXIS"
location="RO_FRONT" color="#550000FF" lowValue="300" highValue="700"/>
<dvt:referenceObject index="5" type="RO_LINE" association="SERIES" series="0"
location="RO_FRONT" color="#ffff66" lineValue="5000" lineWidth="3"
lineStyle="LS_SOLID"/>
<dvt:referenceObject index="6" type="RO_LINE" association="SERIES" series="0"
location="RO_FRONT" color="#ffff66" lineValue="16730" lineWidth="3"
lineStyle="LS_SOLID"/>
<dvt:referenceObject index="7" type="RO_LINE" association="SERIES" series="1"
location="RO_BACK" color="#99cc66" lineValue="500" lineWidth="3"
lineStyle="LS_SOLID"/>
<dvt:referenceObject index="8" type="RO_LINE" association="SERIES" series="1"
location="RO_BACK" color="#99cc66" lineValue="1711" lineWidth="3"
lineStyle="LS_SOLID"/>
</dvt:referenceObjectSet>
</dvt:barGraph>

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

参照オブジェクトを実行時に動的に作成する場合、dvt:referenceObjectSetタグのみを使用します。このタグのreferenceObjectMap属性に、子コンポーネント参照オブジェクトのマップを作成するコードへのメソッド参照を設定します。このマップを作成するメソッドは、マネージドBeanに格納する必要があります。

参照線または領域を動的に作成する手順:

1. 実行時に作成する子コンポーネント参照オブジェクトのマップを作成するメソッドを記述します。例24-9に、このメソッドを作成するコードを示します。

2. 構造ウィンドウでグラフのノードを右クリックし、「dvt:<type>Graphの中に挿入」→「ADFデータ視覚化」→「参照オブジェクト・セット」と選択します。

3. プロパティ・インスペクタで、referenceObjectMap属性に、子コンポーネント参照オブジェクトのマップを作成するコードへのメソッド参照を指定します。
たとえば、(sampleGraph)マネージドBeanとgetReferenceObjectMapListメソッドの場合、属性にreferenceObjectMap="#{sampleGraph.referenceObjectMapList}"と設定します。

例24-9 子参照オブジェクトのマップのコード

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;
}

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

グラデーションは、オブジェクトの色が段階的に変わる特殊効果です。グラデーションの各色は、ストップで表します。最初のストップはストップ0、2番目はストップ1のようになります。特殊効果をサポートするグラフのサブコンポーネントには、特殊効果のストップをいくつでも指定できます。

グラフの次のサブコンポーネントにグラデーション特殊効果を定義できます。

- グラフの背景: dvt:backgroundタグを使用します。

- グラフの描画エリア: dvt:graphPlotAreaタグを使用します。

- グラフの円フレーム: dvt:graphPieFrameタグを使用します。

- 凡例エリア: dvt:legendAreaタグを使用します。

- 系列: dvt:seriesタグを使用します。

注意:

デフォルトでは、グラフの系列のグラデーションは、seriesEffect属性の値SE_AUTO_GRADIENTで設定されます。これにより、データ・マーカーの表示は円滑になり、グラフィックのアンチエイリアス処理が適用されます。カスタム系列のグラデーションを指定するには、属性をSE_NONEに設定する必要があります。

- 時間セレクタ: dvt:timeSelectorタグを使用します。

- 参照領域: dvt:referenceObjectタグを使用します。

グラデーション特殊効果を使用する方法は、この効果がサポートされるグラフの各部分で同じです。

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

特殊効果を追加するグラフのサブコンポーネントごとに、dvt:specialEffectsタグをサブコンポーネントの子タグとして挿入する必要があります。たとえば、グラデーションをグラフの背景に追加する場合、dvt:backgroundタグの子であるdvt:specialEffectsタグを1つ作成します。

その後、オプションでサブコンポーネントの塗りつぶし色の変化の割合を制御する場合は、コンポーネントの塗りつぶしの色と変化の割合の制御に必要な数のdvt:gradientStopStyleタグを挿入します。このdvt:gradientStopStyleタグは、1つのdvt:specialEffectsタグの子タグとして挿入する必要があります。

グラデーション特殊効果をグラフの背景に追加する手順:

1. 構造ウィンドウで、グラフ・ノードの子であるdvt:backgroundノードを右クリックし、「dvt:backgroundの中に挿入」→「特殊効果」を選択します。

2. プロパティ・インスペクタを使用してdvt:specialEffectsタグの属性に値を入力します。

1. fillType属性の場合、FT_GRADIENTを選択します。
gradientDirection属性には、グラデーションの塗りつぶしに使用する変化の方向を選択します。

2. numStops属性には、グラデーションに使用するストップの数を入力します。

3. オプションで各グラデーション・ストップの色と変化の割合を制御する場合は、dvt:specialEffectsノードを右クリックし、dvt:specialEffects内に挿入→dvt:gradientStopStyleと選択します。

4. プロパティ・インスペクタを使用してdvt:gradientStopStyleタグの属性に値を入力します。

1. stopIndex属性には、specialEffectsタグ内に含まれるdvt:gradientStopStyleタグ内の索引としてゼロベースの整数を入力します。

2. gradientStopColor属性には、グラデーション内のこの部分に使用する色を入力します。

3. gradientStopPosition属性には、指定したストップ色のグラデーションでの相対距離を入力します。グラデーションのスケールは0から100です。0または100が指定されない場合、これらのポイントにはデフォルトの位置が使用されます。

5. 指定するグラデーション・ストップごとに、ステップ3とステップ4を繰り返します。

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

例24-10に、グラデーションの塗りつぶしをグラフの背景に追加し、2つのストップを指定する場合に生成されるXMLコードを示します。

例24-10 グラデーションをグラフの背景に追加する場合に生成される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>

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

グラフの各箇所に関連する子タグにborderTransparentおよびfillTransparent属性を設定することで、これらの箇所で透明色を表示するよう指定できます。次のリストに、透明色をサポートするグラフの各部分を示します。

- グラフの背景: dvt:backgroundタグを使用します。デフォルトでは、fillTransparent属性はtrueに設定されています。

- グラフの凡例エリア: dvt:legendAreaタグを使用します。

- グラフの円フレーム: dvt:graphPieFrameタグを使用します。

- グラフの描画エリア: dvt:graphPlotAreaタグを使用します。

24.8.4 グラフへのコンテキスト・メニューの追加

グラフは、次の3つのタイプのファセットを使用して、右クリックのコンテキスト・メニューをサポートします。

- コンポーネント内で選択できない領域に表示されるコンテキスト・メニュー(描画エリアなど)

- 選択可能な要素に表示されるコンテキスト・メニュー(散布図のマーカーなど)

- 複数の選択可能な要素に表示されるコンテキスト・メニュー

24.8.4.1 グラフのコンテキスト・メニューの構成方法

次のコンテキスト・メニューのファセットを使用して、グラフ・コンポーネントにコンテキスト・メニューを定義できます。

- bodyContextMenu: グラフ・コンポーネントの選択できない要素に表示されるコンテキスト・メニューを指定します。

- contextMenu: グラフ・コンポーネントの選択可能な要素に表示されるコンテキスト・メニューを指定します。

- multiSelectContextMenu: グラフ・コンポーネントで複数の要素が選択される場合に表示されるコンテキスト・メニューを指定します。

各ファセットは、1つの子コンポーネントをサポートします。これらのファセットがすべて機能するには、特定のグラフ・タイプに対して選択を有効にしてサポートする必要があります。現在、コンテキスト・メニューはFlashでのみサポートされています。

Flashレンダリング形式を使用する場合、技術的な制限があるため、現在、コンテキスト・メニューのコンテンツは、Flash Playerのコンテキスト・メニューを使用して表示されます。このため、Flash Playerで定義されるいくつかの制限が課せられます。詳細は、24.8.4.2項「Flashレンダリング形式について」を参照してください。

たとえば、図24-11に、カスタム・メニュー・アイテムを使用する散布図のコンテキスト・メニューを示します。

図24-11 散布図のカスタム・コンテキスト・メニュー

例24-11に、散布図のコンテキスト・メニューを構成するサンプル・コードを示します。

例24-11 散布図のコンテキスト・メニューのサンプル・コード

<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>

例24-12に、カスタム・コンテキスト・メニューを作成するマネージドBeanのサンプル・コードを示します。マネージドBeanの詳細は、2.6項「マネージドBeanの作成と使用」を参照してください。

例24-12 カスタム・コンテキスト・メニューを作成するマネージド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は、例24-13に表示されるSelectionSampleクラスを呼び出します。このクラスのコードを追加のマネージドBeanに格納します。

例24-13 カスタム・コンテキスト・メニューの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.8.4.2 Flashレンダリング形式について

Flashレンダリング形式を使用する場合、技術的な制限があるため、現在、コンテキスト・メニューのコンテンツは、Flash Playerのコンテキスト・メニューを使用して表示されます。このため、Flash Playerで定義されるいくつかの制限が課せられます。

- Flashでは、コンテキスト・メニューのサブメニューは許可されません。

- Flashでは、カスタム・メニュー・アイテムが15に制限されます。コンポーネントの組込みメニュー・アイテム(円グラフのinteractiveSliceBehaviorメニュー・アイテムなど)は、制限に含まれます。

- Flashでは、メニュー・アイテムはテキストのみに制限されます。ADF Facesメニューで可能なアイコンなどのコントロールは、Flashメニューでは使用できません。

- 各メニュー・キャプションには、1つ以上の表示可能な文字を含める必要があります。制御文字、新しい行、空白文字は無視されます。100文字を超えるキャプションは不可です。

- 一致するアイテムを表示するかどうかを問わず、別のカスタム・アイテムと同一のメニュー・キャプションは無視されます。大文字/小文字、句読点、空白を問わず、メニュー･キャプションは、組込みキャプションまたは既存のカスタム・キャプションと比較されます。

- 次のキャプションは許可されません。ただし、単語同士をつなげて使用して、カスタム・キャプションを作成できます。Save、Zoom In、Zoom Out、100%、Show All、Quality、Play、Loop、Rewind、Forward、Back、Movie not loaded、About、Print、Show Redraw Regions、Debugger、Undo、Cut、Copy、Paste、Delete、Select All、Open、Open in new window、Copy link

- 次の単語は、それ自体または他の単語と一緒にカスタム・キャプションで表示することはできません。Adobe、Macromedia、Flash Player、Settings

さらに、コンテキスト・メニュー・アイテムのFlashのリクエストは同期呼出しであるため、コンテキスト・メニューの開始時に、ELを評価するサーバー・リクエストは使用できません。選択したオブジェクトごとに異なるコンテキスト・メニューを提供するために、コンテキスト・メニューのポップアップでcontentDelivery="lazyUncached"設定が使用される場合、メニューはあらかじめフェッチされます。状態ごとに異なるコンテキスト・メニューの場合、メニュー定義内のEL式がレンダリング時に繰り返し呼び出されます。選択内容と通貨状態は異なります。あらかじめフェッチされたこれらのコンテキスト・メニューを使用する場合、アプリケーションでは次の事項を認識しておく必要があります。

- コンテキスト・メニューの表示方法の決定に使用できるEL式で、長時間のコードや速度が遅いコードを実行しないでください。これは、メニュー・アイテムの選択後に呼ばれるaf:commandMenuItem属性(actionListenerなど)には適用されません。

- 今後、Flashの制限が解決された場合、ADFコンテキスト・メニューがFlashコンテキスト・メニューのかわりに表示されます。アップグレードの互換性を確保するには、メニューがあらかじめフェッチされている場合と、メニューの開始時にEL式が評価される場合の両方でEL式が機能するようにコードを作成する必要があります。アプリケーションが依存するコンポーネントの状態は、selectionとcurrencyのみです。

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

次のような多くのインタラクティブな機能をグラフに追加できます。

- マーカーと凡例の淡色表示
マーカーには線、棒、面、散布マーカー、バブルおよび円グラフのスライスが含まれます。

- ズームとスクロール

- ズームとスクロールのレベルの変更

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

特定のデータのセット内の1つのデータ・マーカーまたはグラフの凡例の対応するエントリの上にカーソルを移動すると、そのセットのすべてのデータ・マーカーが強調表示されるようにすることができます。強調表示効果は、セットの他のデータ・マーカーを淡色表示することによって視覚的に実現します。たとえば、棒グラフに4つの製品(P1、P2、P3、P4)の月ごとの売上げを表示する場合、製品P2の1月にカーソルを移動すると、P2のすべての棒が強調表示され、P1、P3およびP4の棒は淡色表示されます。

グラフでは特定のデータのセットのすべてのデータ・マーカー(P2のすべての棒など)を系列として参照するため、系列内のデータ・マーカーを強調表示する機能は、グラフの系列ロールオーバー動作機能の一部です。

系列ロールオーバー動作は、棒グラフ、折れ線グラフ、面グラフ、円グラフ、散布図、極グラフ、レーダー・グラフおよびバブル・グラフでのみ使用できます。

系列内のすべてのデータ・マーカーを淡色表示する手順:

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. 「外観」属性カテゴリのSeriesRolloverBehaviorフィールドでドロップダウン・リストを使用して「RB_DIM」を選択します。

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

グラフでズームおよびスクロール・レベルが変更されたときに実行されるカスタム・コードを指定できます。マネージドBeanには、入力をZoomEventまたはScrollEventと解釈するメソッドを格納します。このイベントを使用すると、ユーザーはズームされる軸およびズームされた軸の現在の範囲を決定できます。

グラフでのズームとスクロールに対応するカスタム動作を指定する手順:

1. マネージドBeanに、ズームまたはスクロール・イベントがトリガーされたときの動作を実行するカスタム・メソッドを記述します。例24-14に、このメソッドを作成するコードを示します。

2. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

3. 「動作」属性カテゴリを選択し、「拡張」ノードを開いて、次のいずれかあるいは両方を実行します。

- zoomlListenerフィールドに、マネージドBeanに格納したメソッドへの参照を指定します。
たとえば、setZoomメソッドがSampleGraphマネージドBeanに格納されている場合、"#{sampleGraph.zoom)"という設定になります。

- scrollListenerフィールドに、マネージドBeanに格納したメソッドへの参照を指定します。
たとえば、setScrollメソッドがSampleGraphマネージドBeanに格納されている場合、"#{sampleGraph.scroll)"という設定になります。

例24-14 ズームとスクロールを設定するためのサンプル・コード

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));

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

時間データを表示する相対的範囲と明示的範囲を定義できます。

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

時間データを表示する単純な相対範囲(過去7日間など)を定義できます。これによって、新しいデータ・ポイントがアクティブ・データ・グラフの表示に追加され、古いデータがグラフの左端からはみ出ることになります。相対時間範囲の指定は、アクティブ・データ・グラフでの使用に限定されません。

時間データを表示する相対範囲を指定する手順:

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. 「外観」属性カテゴリで、dvt:timeAxisノードを開き、次の属性に値を指定します。

1. timeRangeMode属性に、相対範囲を時間範囲の終わりに適用する(過去7日間など)か、始めに適用する(最初の7日間など)かに応じてTRM_RELATIVE_LASTまたはTRM_RELATIVE_FIRSTの値を指定します。

2. relativeTimeRange属性に、相対範囲をミリ秒で指定します。

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

時間データを表示する明示的範囲(3月15日から3月25日など)を定義できます。この例では、開始と終了の値に指定されていないため、年、時間、分および秒にはデフォルト値が使用されます。

時間データを表示する明示的範囲を指定する手順:

1. 構造ウィンドウで、グラフのノードを右クリックして、「プロパティに移動」を選択します。

2. 「外観」属性カテゴリで、次の属性に値を指定します。

1. timeRangeMode属性に、値TRM_EXPLICITを指定します。

2. timeRangeStart属性に、時間範囲の最初の日付を入力します。

3. timeRangeEnd属性に、時間範囲の最後の日付を入力します。

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

アラートは、エラーや警告など、個別の記号で強調表示する必要のあるデータ値をグラフ上に定義します。アイコンはアラートの場所を示します。カーソルをアラート・アイコン上に移動すると、そのアラートのテキストが表示されます。アラートは、dvt:alertタグを使用してグラフにいくつでも定義できます。アラートはグラフ・タグの子であるdvt:alertSetタグにラップされます。例24-15に、面グラフのアラートのセットを示します。

例24-15 グラフのアラートのセットのサンプル・コード

<dvt:areaGraph>
<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:areaGraph>

注釈は、グラフ上のデータ値と関連付けられ、カーソルをそのデータ値上に置くと、情報が提供されます。注釈は、dvt:annotationタグを使用してグラフにいくつでも定義できます。複数の注釈を、1つのデータ値に関連付けることができます。注釈はグラフ・タグの子であるdvt:annotationSetタグにラップされます。

注釈に関連付けられるデータ・マーカーは、dvt:annotationタグの次の属性を使用して定義されます。

- series: グラフの系列のゼロベースの索引を指定します。ほとんどのグラフでは、各系列が同じ色のマーカー・セットとして表示されます。たとえば、複数円グラフでは、黄色の各区分が靴の売上を表し、緑の各区分がブーツの売上を表す場合があります。棒グラフでは、黄色の棒がすべて靴の売上を表し、緑の棒がブーツの売上を表す場合があります。

- group: グラフのグループのゼロベースの索引を指定します。グループの表示は、グラフ・タイプによって異なります。集合棒グラフでは、棒の各集合が1つのグループになります。積上げ棒グラフでは、各積層がグループです。複数円グラフでは、各円がグループです。

例24-16に、面グラフの注釈のセットを示します。

例24-16 注釈のセットのサンプル・コード

<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: xValueおよびyValueで定義されるグラフ内の正確なポイントに両方の軸とともに注釈を配置します。他の注釈との重複は回避されません。

- percentage: xValueおよびyValueを使用して、グラフの描画エリアのパーセンテージが0から100で定義される正確なポイントに、両方の軸とともに注釈を配置します。他の注釈との重複は回避されません。

- xValue: 注釈を配置するX値を指定します。この設定は、注釈の位置がabsoluteまたはpercentageの場合にのみ適用されます。

- yValue: 注釈を配置するY値を指定します。この設定は、注釈の位置がabsoluteまたはpercentageの場合にのみ適用されます。

- horizontalAlignment: 注釈の横位置を指定します。この設定は、注釈のposition属性がabsoluteまたはpercentageの場合にのみ適用されます。有効な値は、LEFT(デフォルト)、CENTER、LEADINGまたはRIGHTです。

- verticalAlignment: 注釈の縦位置を指定します。この設定は、注釈のposition属性がabsoluteまたはpercentageの場合にのみ適用されます。有効な値は、CENTER(デフォルト)、TOPまたはBOTTOMです。

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

グラフ・コンポーネントdvt:areaGraph、dvt:bubbleGraph、dvt:barGraph、dvt:lineGraph、dvt:comboGraph、dvt:pieGraphおよびdvt:scatterGraphは、グラフ・コンポーネントの初期表示や部分ページ・リフレッシュ(PPR)イベントのスライドショーの遷移などのアニメーション効果をサポートします。アニメーション効果は、グラフのanimationOnDisplayおよびanimationOnDataChangeプロパティで次の値を使用して指定されます。

- alphaFade

- conveyorFromLeft

- conveyorFromRight

- cubeToLeft

- cubeToRight

- flipLeft

- flipRight

- slideToLeft

- slideToRight

- transitionToLeft

- transitionToRight

- zoom

アニメーション効果は、アクティブなデータを使用して実行することもできます。アクティブ・データ・サービス(ADS)では、ADFモデル・レイヤーを使用して、ADF Facesコンポーネントをアクティブ・データ・ソースにバインドできます。このためには、コンポーネントとバインディングを構成して、コンポーネントがソースで更新されたデータを表示できるようにする必要があります。あるいは、あらかじめ決められた間隔で変更のデータ・ソースをポーリングするようにアプリケーションを構成することもできます。

24.9.1 アクティブ・データを表示するグラフ・コンポーネントの構成方法

アクティブ・データ・サービスを使用するには、データの変更時にイベントを公開するデータ・ソースが必要です。さらに、これらのイベントと、そのサービスを表す関連データ・コントロールに対応するビジネス・サービスを作成する必要があります。ADSとアプリケーションの構成の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アクティブ・データ・サービスの使用」の章を参照してください。

データ・バインドされたグラフを構成し、対応するページ定義ファイルでバインディング要素に値を設定することによってアクティブ・データを表示します。

アクティブ・データを表示するグラフを構成する手順:

1. 構造ウィンドウでグラフのノードを選択します。

2. プロパティ・インスペクタで、「ID」フィールドに一意の値を入力します。
識別子を選択しないと、1つ自動的に入力されます。

3. そのページの関連ページ定義ファイルを開きます。

4. ページ定義ファイルの構造ウィンドウで、コンポーネントにバインドされた属性を表すノードを選択します。プロパティ・インスペクタで、ChangeEventPolicy属性にPushを選択します。

24.9.2 グラフのアニメーション効果の指定方法

アニメーションを使用するグラフのプロパティ・インスペクタで、次の属性を設定します。

- animationOnDisplay: オプション。ADSと一緒にまたは単独で、適用する初期レンダリング効果のタイプの指定に使用します。有効な値は次のとおりです。

- 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色の指定に使用します。

25 ADFゲージ・コンポーネントの使用

この章では、データ・バインドされたADFゲージ・コンポーネントを使用してデータを表示する方法とゲージのカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 25.1項「ゲージ・コンポーネントの概要」

- 25.2項「ゲージのデータ要件の理解」

- 25.3項「ゲージの作成」

- 25.4項「ゲージ・タイプのレイアウトおよび外観のカスタマイズ」

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

- 25.6項「ゲージでのカスタム形状の使用」

ゲージのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFゲージの作成に関する項を参照してください。

25.1 ゲージ・コンポーネントの概要

ゲージはデータの問題点を示します。ゲージは通常、1つのデータ・ポイントをプロットし、そのポイントが許容範囲内か許容範囲外かを表します。1つのゲージ・セットに複数のゲージを表示する場合も多くあります。セット内のゲージは通常構成可能なレイアウトのグリッド状の形式で表示されます。

コンポーネント・ギャラリには、使用可能なゲージのカテゴリ、タイプおよび説明が表示され、ゲージの作成およびクイック・スタート・レイアウトの使用が視覚的にサポートされます。図25-1に、ゲージのコンポーネント・ギャラリを示します。

図25-1 ゲージのコンポーネント・ギャラリ

コンポーネント・ギャラリを使用してゲージ・コンポーネントをJSFページに挿入すると、ゲージのカスタマイズをサポートする子タグのセットが自動的に挿入されます。例25-1に、図25-1のコンポーネント・ギャラリでクイック・スタート・レイアウトを選択したダイアル・ゲージ用にJSFページに挿入されたコードを示します。

例25-1 ゲージのサンプル・コード

<dvt:gauge id="gauge2" value="#{bindings.Gaugedemo1View1.gaugeModel}"
gaugeType="DIAL" imageFormat="FLASH">
<dvt:gaugeBackground>
<dvt:specialEffects fillType="FT_GRADIENT">
<dvt:gradientStopStyle/>
</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:thresholdSet>
<dvt:threshold fillColor="#d62800"/>
<dvt:threshold fillColor="#00ff00"/>
</dvt:thresholdSet>
</dvt:gauge>

ゲージは、200 X 200ピクセルのデフォルト・サイズで表示されます。ブラウザ・ウィンドウの各種サイズのエリアに合うように、ゲージのサイズをカスタマイズしたり、動的なサイズ変更を指定したりすることができます。ゲージが縦または横に制限された領域で表示される場合(Webページのサイドバーなど)、ゲージは小さなイメージ・サイズで表示されます。小さなイメージは、十分な機能がありますが、簡略化されて表示されます。

デフォルトでは、ゲージ・コンポーネントの属性imageFormatで指定するように、ゲージはFlash Playerを使用して表示されます。あるいは、プラグインがクライアント・マシンで許可されない場合や双方向ロケールでは、ポータブル・ネットワーク・グラフィックス(Portable Network Graphics: PNG)出力形式を使用してゲージを表示することもできます。PNG出力形式を使用する場合、静的レンダリングは十分にサポートされますが、次の特定のインタラクティブ機能は使用できません。

- アニメーション

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

- ドラッグ・アンド・ドロップ・ジェスチャー

- 円グラフのスライスのインタラクティブ動作

- 参照オブジェクトのホバー動作

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

- 選択項目

- 系列のロールオーバー動作

- 時間セレクタ

- ズームとスクロール(クライアント側の実況スクロール)

ゲージのイメージ形式は、FlashとPNGのどちらの場合も、双方向ロケールをサポートします。双方向文字、ラベル位置、凡例表示、ゲージ・セット表示などのテキスト文字列がサポートされます。

25.1.1 ゲージのタイプ

ゲージ・コンポーネントでは、次のタイプのゲージがサポートされています。

- ダイアル:220度の弧に沿ってメトリックを示します。これはデフォルトのゲージ・タイプです。図25-2に、プラズマ・ハード・ディスク・テレビの在庫レベルが許容範囲内にあることを示すダイアル・ゲージを示します。

図25-2 しきい値付きダイアル・ゲージ

- ステータス・メーター:矩形のバーに沿ってタスクの進度または測定値のレベルを示します。内側の矩形は、外側の矩形に表示された範囲に対する現在の測定値のレベルを示します。図25-3に、プラズマ・ハード・ディスク・テレビの在庫レベルを、ステータス・メーター・ゲージを使用して示します。

図25-3 しきい値付きステータス・メーター・ゲージ

- ステータス・メーター(垂直): 垂直の矩形のバーに沿ってタスクの進度または測定値のレベルを示します。図25-4に、プラズマ・ハード・ディスク・テレビの在庫レベルを、垂直のステータス・メーター・ゲージを使用して示します。

図25-4 しきい値付き垂直ステータス・メーター・ゲージ

- LED(発行ダイオード): キー・パフォーマンス・インジケータ(KPI)などの指標を図示します。LEDゲージには、よい(上矢印)、普通(左または右矢印)、悪い(下矢印)を示す矢印など、数種のグラフィクスが使用できます。図25-5に、プラズマ・ハード・ディスク・テレビの在庫レベルを、LEDバルブ・インジケータを使用して示します。

図25-5 LEDバルブ・ゲージ

図25-6に、同じ在庫レベルを、LED矢印を使用して示します。

図25-6 LED矢印ゲージ

ダイアル・ゲージおよびステータス・メーター・ゲージの場合、ユーザーが描画エリア、インジケータまたはしきい値領域にマウスを合せると、コンテキスト情報のツールチップが自動で表示されます。図25-7に、ダイアル・ゲージのインジケータ・ツールチップを示します。

図25-7 ダイアル・ゲージのインジケータ・ツールチップ

25.1.2 ゲージの用語

ゲージの用語は、ゲージおよびゲージ・セットのカスタマイズ可能な様々な点を示します。ゲージ・コンポーネントには、このカスタマイズ用のオプションを提供する約20の子タグが含まれています。

カスタマイズ可能なゲージの箇所は次のとおりです。

- 全体的なゲージのカスタマイズ:このグループの各項目はゲージの子タグで表されます。

- ゲージ背景色:ゲージの背景の枠の色と塗りつぶしの色を制御します。

- ゲージ・セット背景色:ゲージ・セットの背景の枠の色と塗りつぶしの色を制御します。

- ゲージ・フレーム:ダイアル・ゲージの背景のフレームのことです。

- 描画エリア:ゲージ自体の内側の領域を表します。

- インジケータ:ダイアル・ゲージにプロットされた値を指します。通常、線または矢印の形をしています。

- インジケータ・バー:ステータス・メーター・ゲージの内側の矩形。

- インジケータ・ベース:ダイアル・ゲージの線形または針形のインジケータの円形ベース。

- しきい値セット:ゲージのメトリックのしきい値セクションを指定します。ゲージのしきい値はいくつでも作成できます。

- データ値:これには、メトリック(ゲージがプロットする実際の値)、最小値、最大値、しきい値などがあります。25.2項「ゲージのデータ要件の理解」で、これらの値について説明します。

- ラベル:ゲージでは次の要素がサポートされ、各要素は別個の子タグです。

- 下位ラベル: ゲージの下部または内部に表示されるオプションのラベルのことです。デフォルトでは、データ行のラベルが表示されます。

- 下のラベル・フレーム:下位ラベルを含むフレームの背景と枠の色を制御します。メトリック・ラベルも下のラベル・フレーム(下位ラベルの右)に表示されます。

- メトリック・ラベル:メトリックの値を示し、ゲージにテキストでプロットされます。

- ティック・マーク:ゲージの値軸上のマークのことです。一定の間隔で最小値から最大値までを示し、しきい値も示します。ティック・マークは、ラベルや副増分を含む主増分を指定できます。

- ティック・ラベル: ゲージの主ティック・マークを示すために表示されるテキストを表示します。

- 上位ラベル: ゲージの上部または内部に表示されるラベルのことです。デフォルトでは、ゲージの上に、ラベルと組み合せてタイトル・セパレータが使用されます。デフォルトでは、データ列のラベルが表示されます。

- 上のラベル・フレーム:上位ラベルを囲むフレームの背景と枠のことです。このフレームの枠の色と塗りつぶしの色を指定できます。このフレームを使用する場合は、デフォルトのタイトル・セパレータを無効にします。

- 凡例:ゲージでは、ゲージの凡例の領域、テキストおよびタイトルがサポートされ、各々別の子タグです。

- 形状属性セット:ゲージは、子要素の相互作用プロパティをサポートします。たとえば、ゲージの描画エリアのaltテキストは、実行時に該当のエリアにマウスを置いたときのツールチップとして表示できます。詳細は、25.5.3項「ゲージへの相互作用の追加方法」を参照してください。

25.2 ゲージのデータ要件の理解

ゲージには次の種類のデータ値を使用できます。

- メトリック:ゲージがプロットする値。この値は、プロパティ・インスペクタで「ゲージ・データ」属性カテゴリの静的データとして指定できます。データ・コントロールまたはdvt:gaugeタグのtabularData属性を使用して指定することもできます。これは、ゲージで唯一の必須データです。指定されるメトリック値の数は、ゲージ・セットに1つのゲージを表示するか、一連のゲージを表示するかに影響します。

- 最小および最大:ゲージの値軸で最小点と最大点を示すオプションの値。この値は、データ・コレクションからの動的データとして指定できます。プロパティ・インスペクタでdvt:gaugeタグの「ゲージ・データ」属性カテゴリの静的データとしても指定できます。詳細は、25.4.4項「グラフへのしきい値の追加方法」を参照してください。

- しきい値:データ・コレクションからの動的データとして指定可能なオプションの値で、ゲージの値軸で許容範囲を示します。プロパティ・インスペクタでゲージのしきい値タグを使用して、静的データとしても指定できます。詳細は、25.4.4項「グラフへのしきい値の追加方法」を参照してください。

必須データ要素はメトリック値のみです。その他のデータ値はオプションです。

25.3 ゲージの作成

次のいずれの方法でも、ゲージ・コンポーネントにデータを指定できます。

- ADFデータ・コントロール: ADFデータ・コントロール・パネルからデータ・コレクションをドラッグ・アンド・ドロップして、データ・バインドされたゲージを宣言的に作成します。図25-8に、作成するゲージにメトリック値と、オプションの最小値、最大値およびしきい値を構成する「ゲージの作成」ダイアログ・ボックスを示します。

図25-8 「ゲージの作成」ダイアログ

詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFゲージの作成に関する項を参照してください。

- 表形式データ: dvt:gaugeタグのtabularData属性を使用してCSV(カンマ区切りの値)データをゲージに使用できます。

25.3.1 表形式データを使用したゲージの作成

表形式データからゲージを作成するプロセスのステップは次のとおりです。

- ゲージのマネージドBeanのメソッドでのデータの格納。

- マネージドBeanに格納されたデータを使用するゲージの作成。

25.3.1.1 ゲージ用の表形式データのマネージドBeanへの格納

ゲージ・コンポーネントのtabularData属性には、グリッドの作成やデータの移入にゲージで使用するメトリック値のリストを指定できます。tabularData属性では、メトリック値のみを指定できます。したがって、しきい値、最小値または最大値は、プロパティ・インスペクタを使用して指定する必要があります。

ゲージ・コンポーネントにはゲージの行と列が表示されます。列ラベルとして指定したテキストは、ゲージの上位ラベルに表示されます。行ラベルとして指定したテキストは、ゲージの下位ラベルに表示されます。

25.3.1.2 表形式データのリストの構造

表形式データを含むリストは、ゲージに渡すデータ値ごとに3メンバーのObject配列で構成されます。各配列のメンバーは次のように編成される必要があります。

- 1つ目のメンバー(索引0)は、データ値のグリッドの列ラベルです。これは通常Stringです。

- 2つ目のメンバー(索引1)は、データ値のグリッドの行ラベルです。これは通常Stringです。

- 3つ目のメンバー(索引2)はデータ値で、通常Doubleです。

図25-9には、Quota、Sales、Margin、Costs、Unitsの5つの列があります。例には、London、Paris、New Yorkの3つの行があります。このデータから、各行に5つのゲージのあるゲージ・セットが生成され、売上げなどの値を3都市で比較できます。

図25-9 年間実績の比較

例25-2に、3都市の年間実績を比較するゲージに必要な表形式データのリストを作成するコードを示します。

例25-2 ゲージ用の表形式データのリストを作成するコード

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[][]{
{60, 90, 135},
{50, -100, -150},
{130, 140, 150},
{70, 80, -130},
{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;
}

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

ゲージ・タグのtabularData属性を使用して、マネージドBeanに格納された表形式データを参照します。

マネージドBeanからの表形式データを使用してゲージを作成する手順:

1. コンポーネント・パレットの「ADFデータ視覚化」ページで、「ゲージ」をページにドラッグ・アンド・ドロップします。

2. コンポーネント・ギャラリで、作成するゲージのカテゴリ、タイプおよびクイック・スタート・レイアウト・スタイルを選択します。

3. プロパティ・インスペクタの「ゲージ・データ」カテゴリで、tabularData属性のドロップダウン・メニューから、「式ビルダー」を選択します。

4. 「式ビルダー」ダイアログで検索ボックスを使用してマネージドBeanを検索します。

5. マネージドBeanのノードを展開し、表形式データのリストを作成するメソッドを選択します。

6. 「OK」をクリックします。
式が作成されます。

たとえば、マネージドBeanの名前がsampleGaugeで、表形式データのリストを作成するメソッドの名前がgetGaugeDataの場合、dvt:gaugeタグのtabularData属性の値として#{sampleGauge.gaugeData}というコードが式ビルダーで生成されます。

25.3.3 表形式データを使用してゲージを作成する場合の処理

tabularData属性で参照されるリストから取得したデータを持つゲージ・タグを作成した場合、次のような結果になります。

- ゲージがtabularData属性の設定で生成されます。このゲージのその他の属性の設定にはデフォルト値が使用されます。

- プロパティ・インスペクタでgaugeType属性の設定をDIAL、LED、STATUSMETERまたはVERTICALSTATUSMETERに変更できます。

25.3.4 ゲージ形式について

デフォルトでは、ゲージは次のイメージ形式を使用して表示されます。

- サポートされる場合は、HTML5が使用されます。

- それ以外では、Flash Playerが可能な場合はFlashが使用されます。HTML5が十分にサポートされないブラウザの場合、Flashも使用されます。

- それ以外は、プラグインがクライアント・マシンで許可されない場合や双方向ロケールでは、ポータブル・ネットワーク・グラフィックス(Portable Network Graphics: PNG)出力形式などがかわりに使用されます。グラフを印刷する場合は、PNG出力形式も使用されます。PNG出力形式を使用する場合、静的レンダリングは十分にサポートされますが、次の特定のインタラクティブ機能は使用できません。

- アニメーション

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

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

- 相互作用力

web.xmlコンテキスト・パラメータ、oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMATを使用してデフォルトの出力形式を変更できます。ブラウザでHTML5が十分にサポートされない場合、FlashまたはPNGイメージがかわりに使用されます。詳細は、A.2.3.22項「グラフとゲージのイメージ形式」を参照してください。

アプリケーション全体でFlashコンテンツの使用を無効にするには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。詳細は、A.4.3項「コンポーネント出力形式としてのFlashの構成」を参照してください。

25.4 ゲージ・タイプのレイアウトおよび外観のカスタマイズ

ゲージ・コンポーネントは、次の方法でカスタマイズできます。

- ゲージ・タイプの変更

- ゲージ・セットでのゲージのレイアウトの指定

- ゲージ・サイズとスタイルの変更

- しきい値の追加

- 数値とテキストの書式設定

- N度のダイアル・ゲージの指定

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

- インジケータとティック・マークのカスタマイズ

- ゲージの透明度の指定

25.4.1 ゲージのタイプの変更方法

dvt:gaugeタグのgaugeType属性を使用してゲージのタイプを変更できます。ゲージ・タイプは、ビジュアル・エディタのデフォルト・ゲージに反映されます。

ゲージのタイプの変更手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「ゲージ・タイプ」属性ドロップダウン・リストからゲージ・タイプを選択します。有効な値は、DIAL、LED、STATUSMETERまたはVERTICALSTATUSMETERです。

25.4.2 ゲージ・セットでのゲージのレイアウトの決定方法

単一ゲージには、ゲージ・コンポーネントにバインドされている1行のデータが表示されます。ゲージ・セットでは、データ・コレクションの複数行のデータの各行が1つのゲージに表示されます。

dvt:gaugeタグの属性の値を指定すると、ゲージ・セット内のゲージの場所を指定できます。

ゲージ・セットでのゲージのレイアウトを指定する手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「共通」属性カテゴリを選択します。

3. ゲージ・セットに表示するゲージの列の数を決めるには、gaugeSetColumnCount属性の値を指定します。
ゼロに設定すると、すべてのゲージが1行に表示されます。正の整数で、ゲージが表示される列の数が決まります。-1を設定すると、列の数がデータ・ソースから自動的に決定されます。

4. 列でのゲージの配置を決めるには、gaugeSetDirection属性の値を指定します。
「GSD_ACROSS」を選択した場合、ゲージのデフォルト・レイアウトが使用され、左から右、上から下にゲージが表示されます。GSD_DOWNを選択した場合、ゲージのレイアウトは、上から下、左から右になります。

5. ゲージ・セット内のゲージの位置合せを制御するには、gaugeSetAlignment属性の値を指定します。
この属性のデフォルトは「GSA_NONE」で、使用できる領域がゲージ・セットのゲージ間で均等に分割されます。他のオプションでは、使用可能な領域と、ゲージ・セット内で左から右、上から下に配置するために最適なゲージ・サイズが使用されます。ゲージ・セットの中央にゲージを配置する「GSA_CENTER」も選択できます。

25.4.3 ゲージのサイズとスタイルの変更

ゲージの幅と高さはカスタマイズでき、コンテナのサイズ変更に基づいて動的にサイズ変更することができます。ゲージで使用されるスタイルシートを制御することもできます。ゲージのこれらの2つの側面は、ともにゲージのinlineStyle属性を使用するという点で関連性があります。

25.4.3.1 ゲージの初期表示サイズの指定

dvt:gaugeタグの属性の値を指定すると、ゲージの初期サイズを指定できます。ゲージの動的サイズ変更を指定しない場合、初期サイズが、ゲージの唯一の表示サイズです。

ゲージが初めて表示される際のサイズを指定する手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「スタイル」属性カテゴリで、dvt:gaugeタグのInlineStyle属性に値を入力します。次に例を示します。

inlineStyle="width:200px;height:200px"

25.4.3.2 ゲージの動的サイズ変更の指定

JSFページでのコンテナのサイズが変更されたときにゲージがサイズ変更されるようにするには、dvt:gaugeタグの2つの属性のそれぞれに値を入力する必要があります。この機能用に指定する値は、サイズの異なるブラウザ・ウィンドウの領域を使用するゲージ・コンポーネントの作成にも有用です。

ゲージの動的サイズ変更を有効にする手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「動作」属性カテゴリで、DynamicResize属性にDYNAMIC_SIZEを選択します。

3. プロパティ・インスペクタの「スタイル」属性カテゴリで、InlineStyle属性の幅と高さの両方に、ピクセルの定数または相対的割合を入力します。
たとえば、コンテナと同じ幅で200ピクセルの高さのゲージを作成するには、inlineStyle属性に"width:100%;height:200px;"と設定します。

25.4.3.3 ゲージのカスタム・スタイル・クラスの使用

ゲージに使用するカスタム・スタイル・クラスを指定できます。ただし、幅と高さをinlineStyle属性で指定する必要があります。

ゲージにカスタム・スタイル・クラスを指定する手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「スタイル」属性カテゴリで、StyleClass属性に、「プロパティ」メニュー項目から「編集」を選択し、このゲージに使用するCSSスタイル・クラスを選択します。

3. InlineStyle属性の幅と高さに、ピクセルの定数または相対的割合を入力します。
たとえば、コンテナと同じ幅で200ピクセルの高さのゲージを作成するには、inlineStyle属性に"width:100%;height:200px;"と設定します。

25.4.4 しきい値のゲージへの追加方法

しきい値は、特定の範囲の値を強調表示するゲージのデータ値です。しきい値はゲージの最小値と最大値の間の値である必要があります。しきい値で指定される範囲は、他の範囲と異なる色で色付けされます。

ゲージがデータ・バインドされている場合、ゲージのデータ・コレクションでしきい値の動的値を指定できます。ゲージの作成後、dvt:thresholdSetタグと、個々のdvt:thresholdタグを挿入して静的しきい値を作成できます。しきい値がデータ・コレクションとしきい値タグの両方で指定された場合、ゲージはしきい値タグの値を受け入れます。

25.4.4.1 静的しきい値のゲージへの追加

ゲージのしきい値はいくつでも作成できます。各しきい値は、1つのdvt:thresholdタグで表されます。1つのdvt:thresholdSetタグですべてのしきい値タグをラップする必要があります。

静的しきい値をゲージに追加する手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「しきい値セット」と選択します。
dvt:thresholdSetタグの属性に値を指定する必要はありません。

2. dvt:thresholdSetノードを右クリックし、「dvt:thresholdSetの中に挿入」→「しきい値」と選択します。

3. プロパティ・インスペクタで、このしきい値でカスタマイズする属性の値を入力します。
しきい値に関連するゲージのセクションに、特定の塗りつぶしの色と枠の色を入力できます。しきい値の最大値と、しきい値を示す凡例に表示するテキストも指定できます。

注意:

最終しきい値の場合、最終しきい値のしきい値タグに入力した値に関係なく、ゲージの最大値がしきい値の最大値として使用されます。

4. ステップ2とステップ3を繰り返して、ゲージの各しきい値を最小値から最大値まで作成します。

ゲージには、任意の数のしきい値を追加できます。ただし、矢印ゲージや三角形LEDゲージは、それらが指し示す3つの方向のみのしきい値をサポートします。

25.4.5 ゲージでの数値の書式設定方法

ゲージの場合、dvt:metricLabelおよびdvt:tickLabelタグには、数値の書式設定が必要です。

25.4.5.1 ゲージのメトリック・ラベルの数値の書式設定

メトリック・ラベル・タグには、numberType属性があり、値自体を表示するか、値が表す割合を表示するかを指定できます。数値の書式設定としては、これで十分な場合もあります。

af:convertNumberタグを使用して、メトリック・ラベルの数値の書式を指定することもできます。たとえば、af:convertNumberタグで、データ値を通貨として書式設定したり、正または負の記号を表示できます。

ゲージ・メトリック・ラベルの数値を書式設定する手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→metricLabelと選択します。

2. メトリック値を値ではなく、割合として表示する場合、dvt:metricLabelタグのNumberType属性を「NT_PERCENT」に設定します。

3. メトリック・ラベルの数値にその他の書式を指定する場合は、次のようにします。

1. metricLabelノードを右クリックし、「dvt:metricLabelの中に挿入」→「数値の変換」と選択します。

2. プロパティ・インスペクタで、af:convertNumberタグの属性に値を指定し、その他の書式を指定します。

ゲージのティック・ラベルの数値を書式設定する手順は、メトリック・ラベルの数値を書式設定する手順と似ています。dvt:tickLabelタグをゲージの子タグとして挿入する点が異なります。

注意:

メトリックまたはティック・ラベルのnumberType属性をパーセント(NT_PERCENT)に設定する場合、子タグaf:convertNumber(使用される場合)は、そのtype属性に関して自動的にpercentに設定されます。af:convertNumberを強制的にpercentにする場合、ゲージではパターン属性が消去されます。つまり、ゲージでパーセント書式設定が強制される場合、パターンは無視されます。

25.4.6 ゲージ・メトリック・ラベルの数値を書式設定する場合の処理

ゲージにメトリック・ラベルと数値の書式設定を追加すると、XMLコードが生成されます。例25-3に、生成されるXMLコードのサンプルを示します。

例25-3 メトリック・ラベルの数値を書式設定する場合のXMLコード

<dvt:gauge>
<dvt:metricLabel position="LP_BELOW_GAUGE" numberType="NT_PERCENT">
<af:convertNumber type="percent"/>
</dvt:metricLabel>
</dvt:gauge>

25.4.7 自動スケーリングと精度について

コンパクトで明確な表示を実現するために、ゲージでは、メトリック・ラベルとティック・ラベルに表示する値のスケールと精度が自動的に決定されます。たとえば、値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に設定する場合を除き、無視されます。

25.4.8 ゲージでのテキストの書式設定方法

テキストの書式は、ゲージのタイトルとラベルを表す次のゲージ・タグのいずれかで設定できます。

- dvt:bottomLabel

- dvt:gaugeMetricLabel

- dvt:gaugeLegendText

- dvt:gaugeLegendTitle

- dvt:tickLabel

- dvt:topLabel

ゲージ・ラベルとタイトルのテキストを書式設定する手順は、ゲージ・ラベルまたはタイトルを表す適切な子タグを挿入する点を除き同様です。たとえば、dvt:metricLabelタグでdvt:gaugeFont子タグを使用して、ゲージ・メトリック・ラベルのフォント・サイズ、色、およびテキストが太字かイタリックかを指定できます。

ゲージ・メトリック・ラベルのテキストを書式設定する手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→metricLabelと選択します。

2. metricLabelノードを右クリックし、「dvt:metricLabelの中に挿入」→「フォント」と選択します。

3. プロパティ・インスペクタで、dvt:gaugeFontタグの属性に値を指定し、必要な書式を指定します。

gaugeFontタグを使用してゲージ・メトリック・ラベルのテキストを書式設定する場合、XMLコードが生成されます。例25-4に、生成されるXMLコードのサンプルを示します。

例25-4 ゲージ・メトリック・ラベルのテキストを書式設定する場合に生成されるXMLコード

<dvt:gauge>
<dvt:metricLabel>
<dvt:gaugeFont name="Tahoma" size="11" color="#3C3C3C" bold="true"/>
</dvt:metricLabel>
</dvt:gauge>

25.4.9 N度のダイアルの指定方法

ダイアル・ゲージに標準の220度の弧以外の角度でスイープするゲージを指定できます。angleExtent属性を設定して、ゲージの角度の範囲を指定します。

たとえば、270度のダイアル・ゲージを作成するには、angleExtent属性を<dvt:gauge angleExtent="270"/>のように設定します。

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

ゲージ・ラベルの位置を制御できます。ゲージ・ラベル・フレームの色と枠も制御できます。

25.4.10.1 ゲージ・ラベルの位置の制御

適切なラベル・タグのposition属性を使用して、ラベルをゲージの外側に表示するか、内側に表示するかを指定できます。次のラベル・タグは、dvt:gaugeの子タグとして使用できます。

- dvt:bottomLabel

- dvt:metricLabel

- dvt:topLabel

ゲージ・ラベルの位置を制御する手順は、ゲージ・ラベルを表す適切な子タグを挿入する点を除き同様です。たとえば、dvt:bottomLabel子タグを使用して、ゲージを配置し、ラベル・テキストを指定できます。

下位ラベルの位置を指定する手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「下部ラベル」と選択します。

2. プロパティ・インスペクタで、position属性に対して、ラベルの位置を選択します。

3. text属性に、ラベルに表示するテキストを入力します。

25.4.10.2 ゲージ・ラベルの色と枠のカスタマイズ

上位ラベルと下位ラベルのフレームの塗りつぶしの色と枠の色を制御できます。ゲージの子タグdvt:upperLabelFrameおよびdvt:lowerLabelFrameは、これらのラベルのフレームとして機能します。

上のラベル・フレームの色と枠をカスタマイズする手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「上のラベル・フレーム」と選択します。

2. プロパティ・インスペクタで、borderColor属性とfillColor属性の色を選択します。

同様の手順を使用して、ゲージ・ノードの子としてdvt:bottomLabelタグで、下位ラベル・フレームの色と枠をカスタマイズします。

25.4.11 インジケータとティック・マークのカスタマイズ方法

ゲージのインジケータ、およびティック・マークの位置とラベルのカスタマイズに使用できるオプションが多数あります。

25.4.11.1 ゲージ・インジケータの外観の制御

ゲージのインジケータのカスタマイズには、ゲージの次の子タグを使用できます。

- dvt:indicator: ゲージ・インジケータの針またはステータス・メーター・バーの外観上のプロパティを指定します。次の属性があります。

- borderColor: インジケータの枠の色を指定します。

- fillColor: インジケータの塗りつぶしの色を指定します。

- type: インジケータの種類(線、塗りつぶしまたは針)を指定します。

- useThresholdFillColor: インジケータが指すしきい値領域の色が、インジケータの指定した色をオーバーライドするかどうかを指定します。

- dvt:indicatorBar: ステータス・メーター・ゲージの内側の矩形(バー)の塗りつぶしのプロパティが含まれます。

- dvt:indicatorBase: ダイアル・ゲージの線形または針形のインジケータの円形ベースの塗りつぶしプロパティが含まれます。

ゲージ・インジケータの外観をカスタマイズする手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「インジケータ」と選択します。

2. プロパティ・インスペクタで、属性に値を指定します。

3. ステータス・メーター・ゲージの内側のバーの塗りつぶし属性をカスタマイズする場合は、構造ウィンドウでゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「インジケータ・バー」と選択します。

4. プロパティ・インスペクタで、属性に値を指定します。

5. ダイアル・ゲージの線形スタイル・インジケータの円形ベースをカスタマイズする場合は、構造ウィンドウでゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「インジケータ・ベース」と選択します。

6. プロパティ・インスペクタで、属性に値を指定します。

25.4.11.2 ティック・マークとラベルの指定

ゲージのティック・マークとティック・ラベルをカスタマイズするには、ゲージの次の子タグを使用できます。

- dvt:tickMark: 主ティック・マークおよび副ティック・マークの表示、間隔および色を指定します。主ティック・マークにのみ値ラベルを入れることができます。次の属性があります。

- majorIncrementおよびminorIncrement: 2つの主ティック・マークと2つの副ティック・マークの間の距離をそれぞれ設定します。いずれかの属性の値がゼロ未満の場合、ティック・マークは表示されません。

- majorTickColorおよびminorTickColor: 主ティック・マークと副ティック・マークの16進数の色を設定します。

- content: ゲージ・セット内のどこにティック・マークを表示するかを指定します。有効な値は、空白またはカンマで区切られた次のような組合せです。

- TC_INCREMENTS: 増分ごとのティック・マークを表示します。

- TC_MAJOR_TICK: 最小値、最大値および増分値のティック・マークを表示します。

- TC_MIN_MAX: 最小値および最大値のティック・マークを表示します。

- TC_METRIC: 実際のメトリック値のティック・マークを表示します。

- TC_NONE: ティック・マークを表示しません。

- TC_THRESHOLD: しきい値のティック・マークを表示します。

- dvt:tickLabel: ラベルを持つ主ティック・マークを指定し、ラベルの位置(ゲージの内側か外側か)とティック・ラベルに表示される数値の書式を指定します。

ゲージのティック・マークとティック・ラベルをカスタマイズする手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「ティック・マーク」と選択します。

2. プロパティ・インスペクタで、属性に値を指定します。

3. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「ティック・ラベル」と選択します。

4. プロパティ・インスペクタで、属性に値を指定します。

25.4.11.3 外側のティック・ラベルの作成

デフォルトで、ダイアル・ゲージにはゲージがゲージ・フレーム内に完全に含まれる場合に見やすくするため、内側のティック・ラベルが表示されます。ティック・ラベルは描画エリア内にあるため、ティック・ラベルの長さはこの領域に合うように制限される必要があります。ゲージは外側のラベルを使用してカスタマイズできます。

ゲージで内側のティック・ラベルを作成する手順:

1. 構造ウィンドウで、ゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→「ティック・マーク」と選択します。

2. プロパティ・インスペクタで、Position属性にTLP_POSITIONを選択します。

25.4.12 ゲージの箇所に対する透明色の指定

ゲージの各箇所に関連するゲージ子タグにborderColorおよびfillColor属性を設定することで、ゲージの様々な箇所で透明色を表示するよう指定できます。これらの色プロパティは、6または8 RGBの16進数の値を受け入れます。8桁の値を使用する場合、最初の2桁が透明色を表します。たとえば、値00FFFFFFを使用して透明色を設定できます。

borderColorまたはfillColor属性をサポートするすべてのゲージ子タグを透明色に設定できます。次のリストは、透明色をサポートするゲージの箇所の例です。

- ゲージの背景: dvt:gaugeBackgroundタグを使用します。

- ゲージ・フレーム: dvt:gaugeFrameタグを使用します。

- ゲージの描画エリア: dvt:gaugePlotAreaタグを使用します。

- ゲージの凡例エリア: dvt:gaugeLegendAreaタグを使用します。

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

これらのゲージの機能は、一般的な機能ほど頻繁には使用されません。これらの特殊な機能には、ゲージの特定箇所へのグラデーション効果の適用、ゲージへの相互作用の追加、ゲージへのアニメーションの使用、ゲージでのアクティブ・データのサポートの利用などがあります。

25.5.1 ゲージでのグラデーション特殊効果の使用方法

グラデーションは、オブジェクトの色が段階的に変わる特殊効果です。グラデーションの各色は、ストップで表します。最初のストップはストップ0、2番目はストップ1のようになります。特殊効果をサポートするゲージのサブコンポーネントに、特殊効果のストップの数を指定する必要があります。

ゲージの次のサブコンポーネントにグラデーション特殊効果を定義できます。

- ゲージの背景: dvt:gaugeBackgroundタグを使用します。

- ゲージ・セットの背景: dvt:gaugeSetBackgroundタグを使用します。

- ゲージの描画エリア: dvt:gaugePlotAreaタグを使用します。

- ゲージのフレーム: dvt:gaugeFrameタグを使用します。

- ゲージの凡例エリア: dvt:gaugeLegendAreaタグを使用します。

- 下のラベル・フレーム: dvt:lowerLabelFrameタグを使用します。

- 上のラベル・フレーム: dvt:upperLabelFrameタグを使用します。

- インジケータ: dvt:indicatorタグを使用します。

- インジケータ・バー: dvt:indicatorBarタグを使用します。

- インジケータ・ベース: dvt:indicatorBaseタグを使用します。

- しきい値: dvt:thresholdタグを使用します。

グラデーション特殊効果を使用する方法は、この効果がサポートされるゲージの各部分で同じです。

25.5.1.1 ゲージへのグラデーション特殊効果の追加

特殊効果を追加するゲージのサブコンポーネントごとに、dvt:specialEffectsタグをサブコンポーネントの子タグとして挿入する必要があります。たとえば、グラデーションをゲージの背景に追加する場合、dvt:backgroundタグの子であるdvt:specialEffectsタグを1つ作成します。dvt:specialEffectsタグのfillTypeプロパティをFT_FGRADIENTに設定する必要もあります。

その後、オプションでサブコンポーネントの塗りつぶし色の変化の割合を制御する場合は、コンポーネントの塗りつぶしの色と変化の割合の制御に必要な数のdvt:gradientStopStyleタグを追加します。このdvt:gradientStopStyleタグは、1つのdvt:specialEffectsタグの子タグとして入力する必要があります。

作業を始める前に、次のようにします。

dvt:gaugeBackgroundタグをゲージの子タグとして挿入していない場合は、構造ウィンドウでゲージのノードを右クリックし、「dvt:gaugeの中に挿入」→「ADFデータ視覚化」→ゲージの背景と選択します。

グラデーション特殊効果をゲージの背景に追加する手順:

1. 構造ウィンドウで、背景のゲージ・ノードを右クリックし、「dvt:gaugeBackgroundの中に挿入」→「特殊効果」と選択します。

2. プロパティ・インスペクタを使用してdvt:specialEffectsタグの属性に値を入力します。

1. fillType属性には、FT_GRADIENTを選択します。

2. gradientDirection属性には、グラデーションの塗りつぶしに使用する変化の方向を選択します。

3. numStops属性には、グラデーションに使用するストップの数を入力します。

3. オプションで、各グラデーション・ストップの色と変化の割合を制御する場合は、特殊効果のノードを右クリックし、dvt:specialEffects内に挿入→dvt:gradientStopStyleと選択します。

4. プロパティ・インスペクタを使用してdvt:gradientStopStyleタグの属性に値を入力します。

1. stopIndex属性には、dvt:specialEffectsタグ内に含まれるdvt:gradientStopStyleタグ内の索引としてゼロベースの整数を入力します。

2. gradientStopColor属性には、グラデーション内のこの部分に使用する色を入力します。

3. gradientStopPosition属性には、指定したストップ色のグラデーションでの相対距離を入力します。グラデーションのスケールは0から100です。0または100が指定されない場合、これらのポイントにはデフォルトの位置が使用されます。

5. 指定するグラデーション・ストップごとに、ステップ3とステップ4を繰り返します。

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

グラデーションの塗りつぶしをゲージの背景に追加し、2つのストップを指定する場合、XMLコードが生成されます。例25-5に、生成されるXMLコードを示します。

例25-5 グラデーションをゲージの背景に追加する場合に生成される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>

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

dvt:shapeAttributesSetタグにラップされたdvt:shapeAttributesタグを1つ以上使用して、ゲージのサブコンポーネントで相互作用のプロパティを指定できます。相互作用は、特定のサブコンポーネントとHTML属性またはJavaScriptイベントとの間の接続を提供します。各dvt:shapeAttributesタグが機能するには、そのタグにサブコンポーネントおよび少なくとも1つの属性が含まれている必要があります。

たとえば、例25-6に、ユーザーがインジケータをクリックすると、インジケータのツールチップが「Indicator」から「Indicator is Clicked」に変わり、実行時に該当ラベルの上にマウス・ポインタを置くと、ゲージ・メトリック・ラベルのツールチップに「Metric Label」と表示されるダイアル・ゲージのコードを示します。

例25-6 Gauge 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のメソッドを使用して、属性の値を戻すこともできます。例25-7に、バッキングBeanを参照するサンプル・コードを示し、例25-8に、バッキングBeanのサンプル・コードを示します。

例25-7 バッキング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>

例25-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\";"); }

次のゲージ・サブコンポーネントは、dvt:shapeAttributesタグをサポートします。

- GAUGE_BOTTOMLABEL: ゲージの下のラベル

- GAUGE_INDICATOR: ゲージのインジケータ

- GAUGE_LEGENDAREA: ゲージの凡例エリア

- GAUGE_LEGENDTEXT: 凡例エリアのテキスト・ラベル

- GAUGE_METRICLABEL: メトリック値を示すラベル

- GAUGE_TOPLABEL: ゲージの上のラベル

- GAUGE_PLOTAREA: ゲージの内側のエリア

- GAUGE_THRESHOLD: ゲージのしきい値エリア

25.5.4 ゲージにアニメーションを使用する方法

たとえば、データ値が増減すると、ダイアル・ゲージ・インジケータの色が変わるなどのように、ゲージ(ゲージ・セットではなく)にアニメーションを使用してデータの変化を表示できます。図25-10に、各しきい値レベルでデータの変化をアニメーションで表示するダイアル・インジケータの付いたダイアル・ゲージを示します。

図25-10 アニメーションを使用したダイアル・ゲージ

ゲージにアニメーション効果を設定する属性は次のとおりです。

- animationOnDisplay: 適用する初期レンダリング効果のタイプの指定に使用します。有効な値は次のとおりです。

- NONE: (デフォルト)初期レンダリング効果は表示されません。

- AUTO: グラフ・タイプまたはゲージ・タイプに基づいて自動的に選択された初期レンダリング効果が適用されます。

- animationOnDataChange: 適用するデータ変化のアニメーションでデータ・タイプの指定に使用します。有効な値は次のとおりです。

- NONE: データ変化のアニメーション効果は適用されません。

- AUTO: (デフォルト)アクティブ・データ・サービス(ADS)のデータ変化のアニメーション・イベントが適用されます。ADSの詳細は、25.5.5項「アクティブ・データによるゲージへのアニメーションの使用方法」を参照してください。

- ON: 部分ページ・リフレッシュ(PPR)のデータ変化のアニメーション・イベントが適用されます。この設定を使用して、あらかじめ決められた間隔で変更のデータ・ソースをポーリングするようにアプリケーションを構成します。

25.5.5 アクティブ・データによるゲージへのアニメーションの使用方法

アクティブ・データ・サービス(ADS)を使用したアニメーション効果は、ダイアル・メーター・ゲージ・タイプおよびステータス・メーター・ゲージ・タイプに追加できます。ADSでは、ADFモデル・レイヤーを使用して、ADF Facesコンポーネントをアクティブ・データ・ソースにバインドできます。このためには、コンポーネントとバインディングを構成して、コンポーネントがデータ・ソースで更新されたデータを表示できるようにする必要があります。

作業を始める前に、次のようにします。

アクティブ・データ・サービスを使用するには、次の手順を実行する必要があります。

- データの変更時にイベントを公開するデータ・ソースの保持

- これらのイベントと、そのサービスを表す関連データ・コントロールに対応するビジネス・サービスの作成

ADSとアプリケーションの構成の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「アクティブ・データ・サービスの使用」の章を参照してください。

25.5.5.1 アクティブ・データを表示するゲージ・コンポーネントの構成

データ・バインドされたゲージを構成し、対応するページ定義ファイルでバインディング要素に値を設定することによってアクティブ・データを表示します。

アクティブ・データを表示するゲージを構成する手順:

1. 構造ウィンドウでゲージのノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「ID」フィールドに一意の値を入力します。
識別子を選択しないと、1つ自動的に入力されます。

3. そのページの関連ページ定義ファイルを開きます。

4. ページ定義ファイルの構造ウィンドウで、コンポーネントにバインドされた属性を表すノードを選択します。プロパティ・インスペクタで、ChangeEventPolicy属性にPushを選択します。

25.5.5.2 アニメーションのゲージへの追加

ゲージ・コンポーネントでアクティブ・データが表示されるように構成したら、25.5.4項「ゲージへのアニメーションの使用方法」で定義した属性を使用してアニメーション効果を設定します。

25.6 ゲージでのカスタム形状の使用

ゲージのカスタム形状を作成するには、ゲージのグラフィックを直接指定できます。customShapesPath属性は、出力に使用するグラフィックに処理されるベクター・グラフィック・ファイルを指し示すように設定されます。JDeveloperからも、customShapesPath属性を使用してカスタム形状スタイルのセットを利用できます。

25.6.1 カスタム形状グラフィック・ファイルの作成方法

描画エリアやティック・マークなど、ゲージのコンポーネントの回転およびサイズ変更のための要件があるため、カスタム形状グラフィック・ファイルを作成する場合は、ベクター・グラフィック・ファイルが必要です。スケーラブル・ベクター・グラフィック(SVG)が、ゲージのカスタム形状作成のためのファイル形式としてサポートされています。

設計者は、ゲージを設計してSVGファイルにエクスポートしたら、ゲージの形状およびコンポーネントを識別して、スケールおよび位置設定し、処理に使用されるその他のメタデータを指定するための情報を追加します。

SVGファイルで、ゲージ・コンポーネントはIDを使用して識別されます。たとえば、<polygon id="indicator"/>と指定されたSVGファイルは、indicatorコンポーネントに多角形形状を使用するものと解釈されます。複数の形状を指定してコンポーネントに必要なビジュアルを作成するには、IDをid="indicator_0"、id="indicator_1"およびid="indicator_2"に変更できます。

表25-1に、ゲージ・コンポーネントIDとその説明を示します。

表25-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は他のゲージ・コンポーネントと同じ相対位置に置かれます。

表25-2に、内部計算に使用され、ゲージにはレンダリングされないメタデータIDとその説明を示します。

表25-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の位置が決定されます。

例25-9に、ゲージのコンポーネントにカスタム形状を指定する場合に使用するサンプルSVGファイルを示します。

例25-9 ゲージのカスタム形状に使用するサンプル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>

25.6.2 カスタム形状ファイルの作成方法

ゲージのカスタム形状の指定に使用するSVGファイルを作成したら、そのファイルを指すcustomShapesPath属性を設定します。

カスタム形状ファイルを指定する手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「外観」属性カテゴリで、CustomShapesPath属性に、カスタム形状ファイルへのパスを入力します。たとえば、customShapesPath="/path/customShapesFile.svg"のようになります。

25.6.3 サポートされているSVG機能について

使用可能なカスタム形状では、次のSVG機能がサポートされています。

- 変換

- パス

- 基本的な形状

- 塗りつぶしとストローク・ペインティング

- 線形および放射状のグラデーション

JDeveloperのカスタム形状によってサポートされていない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.6.4 カスタム形状スタイルの設定方法

ゲージへのカスタム形状指定機能以外にも、ゲージ・コンポーネントに使用できる事前作成のカスタム形状スタイルのセットがあります。使用可能なスタイルは次のとおりです。

- 角丸矩形

- 完全な円

- 立体的な円

図25-11に、カスタム形状スタイルを適用して表示されたダイアル・ゲージを示します。

図25-11 カスタム形状スタイルを使用したダイアル・ゲージ

ゲージにカスタム形状スタイルを適用する手順:

1. 構造ウィンドウでdvt:gaugeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「外観」属性カテゴリで、CustomShapesPath属性ドロップダウン・リストからカスタム形状スタイルを選択します。

26 ADFピボット・テーブル・コンポーネントの使用

この章では、データ・バインドされたADFピボット・テーブル・コンポーネントを使用してデータを表示する方法とピボット・テーブルのカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 26.1項「ADFピボット・テーブル・コンポーネントの概要」

- 26.2項「ピボット・テーブルのデータ要件の理解」

- 26.3項「レイヤーのピボット」

- 26.4項「ピボット・テーブルでの選択の使用」

- 26.5項「ピボット・テーブルでのソート」

- 26.6項「ピボット・テーブルのサイズ」

- 26.7項「部分ページ・レンダリングによるピボット・テーブルの更新」

- 26.8項「ピボット・テーブルからのエクスポート」

- 26.9項「ピボット・テーブルのセルのコンテンツのカスタマイズ」

- 26.10項「ピボット・テーブルのデータ・セルのスタンプ設定および編集」

- 26.11項「ピボット・テーブルでのピボット・フィルタ・バーの使用」

ADFピボット・テーブルのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFピボット・テーブルの作成に関する項を参照してください。

26.1 ADFピボット・テーブル・コンポーネントの概要

ADFピボット・テーブル・コンポーネントでは、行および列のグリッド・データを表示します。表計算ソフトウェア同様、このコンポーネントでは、グリッド・データの小計と合計を生成するオプションが用意されています。ピボット・テーブルでは、データ・ラベルや関連するデータ・レイヤーを1つの行エッジまたは列エッジから別のエッジにピボットまたは移動して、データの表示を変えることができるため、インタラクティブな分析がサポートされます。

ピボット・テーブルのインタラクティブな機能は、行ヘッダーと列ヘッダーにネストする複数の属性の表示に基づいています。ドラッグ・アンド・ドロップ操作を使用してこれらの属性のレイアウトを動的に変更できます。

図26-1に、行と列に複数の属性がネストするピボット・テーブルを示します。

図26-1 複数の行および列を持つ売上げピボット・テーブル

ピボット・テーブルは、大規模なデータ・セットに対するオンデマンド・データ・スクロールをサポートします。ピボット・テーブルに表示されているデータのみがロードされます。ユーザーが垂直または水平にスクロールすると、データは新しいピボット・テーブル表示に合せてフェッチまたは破棄されます。図26-2に、オンデマンド・データ・スクロールを使用して大規模なデータ・セットを表示するピボット・テーブルを示します。

図26-2 ピボット・テーブルのオンデマンド・データ・スクロール

ピボット・フィルタ・バーは、ピボット・テーブルに追加可能なコンポーネントで、ピボット・テーブルのいずれかのエッジに表示されないレイヤーのピボット・テーブル・データをフィルタ処理できます。ユーザーは、ピボット・フィルタ・バーと関連するピボット・テーブル間でこれらのレイヤーをドラッグ・アンド・ドロップして、データの表示を変更することもできます。図26-3に、ピボット・テーブルのピボット・フィルタ・バーを示します。

図26-3 ピボット・フィルタ・バー・コンポーネント

26.1.1 ピボット・テーブルの要素と用語

次のピボット・テーブルの用語のリストでは、売上げピボット・テーブルのサンプルとして図26-1を用語の説明に使用します。

- エッジ: ピボット・テーブルの軸。次のエッジがあります。

- 行エッジ: ピボット・テーブル本体の左にある縦軸。図26-1には、行エッジに年と製品の2つのレイヤーがあります。ピボット・テーブルの各行は、特定の年と製品の組合せを表します。

- 列エッジ: ピボット・テーブル本体の上にある横軸。図26-1には、列エッジに尺度、販路、地理の3つのレイヤーがあります。ピボット・テーブルの各列は、特定の測定値(SalesまたはUnits)、特定の販路インジケータ(All Channels)、特定の地理上の位置(WorldまたはBoston)の組合せを表します。

- ページ・エッジ: ピボット・フィルタ・バーで表されるエッジで、そのレイヤーを、行エッジおよび列エッジのレイヤーでフィルタ処理またはピボットすることができます。

- レイヤー: 1つのエッジに表示される、ネストする属性。図26-1では、3つのレイヤーである尺度、販路、地理が列エッジに表示されています。行エッジには、年と製品の2つのレイヤーが表示されています。

- ヘッダー・セル: 行または列に表示されているデータを示すラベル。行ヘッダーのセルは行エッジに表示され、列ヘッダーのセルは列エッジに表示されます。

- データ・セル: ヘッダー情報ではなく、データ値を含むピボット・テーブル内のセル。サンプルでは、最初のデータ・セルに、20,000.000という値が含まれています。

- QDR(修飾データ参照): 行、列または各セルの完全修飾データ参照。たとえば、図26-1では、ピボット・テーブルの最初のデータ・セルのQDRは、次の情報を提供する必要があります。

- 年: 2007

- 製品: Tents

- 尺度: Sales

- 販路: All Channels

- 地理: World

26.2 ピボット・テーブルのデータ要件の理解

ピボット・テーブル・コンポーネントでは、データを表示およびやりとりするモデルを使用します。使用される特定のモデル・クラスはoracle.adf.view.faces.bi.model.DataModelです。

行セット(フラット・ファイル)データ・コレクションを使用して、ピボット・テーブルにデータを提供できます。データ・バインディング処理時、「データ・バインディング」ダイアログでピボット・テーブルの行エッジまたは列エッジの目的の場所に各データ要素をドラッグできます。

データ・バインディング時は、ピボット・テーブルの行と列の小計や合計の指定、実行時のドリルダウン操作の指定、重複レコードの集計方法の定義、初期ソート基準の設定などを行うこともできます。

ADFピボット・テーブルのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFピボット・テーブルの作成に関する項を参照してください。

26.3 レイヤーのピボット

ピボット・テーブルのレイヤーは、同じエッジの別の場所や異なるエッジにドラッグできます。この操作はピボットと呼ばれ、デフォルトで有効になっています。

レイヤー上にカーソルを置くと、レイヤーのピボット・ハンドルとオプションのピボット・ラベルが表示されます。ピボット・ハンドル上にカーソルを置くと、カーソルは4つの先端が付いた矢印のドラッグ・カーソルに変わります。このハンドルを使用して、レイヤーを新しい場所へドラッグできます。行エッジのレイヤー上にカーソルを置くと、図26-4に示すとおり、そのレイヤーの上にピボット・ハンドルが表示されます。

図26-4 行エッジでのピボット・ハンドルの表示

列エッジのレイヤー上にカーソルを置くと、図26-5に示すとおり、そのレイヤーの左にピボット・ハンドルが表示されます。

図26-5 列エッジでのピボット・ハンドルの表示

図26-4で時間(年)のピボット・ハンドルを行エッジから列エッジの尺度(Sales)レイヤーと販路レイヤーの間にドラッグすると、ピボット・テーブルは図26-6に示すように変わります。

図26-6 年をピボットした後の売上げピボット・テーブル

ピボットはピボット・ラベルおよびピボットを無効にするようにカスタマイズできます。

ピボット・テーブルのピボットをカスタマイズする手順:

1. 構造ウィンドウでdvt:pivotTableコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. (オプション)プロパティ・インスペクタの「外観」カテゴリのPivotLabelVisibleフィールドで、ドロップダウン・リストから「false」を選択してピボット・ハンドルのラベルの表示を無効にします。

3. (オプション)プロパティ・インスペクタの「動作」カテゴリのPivotEnabledフィールドで、ドロップダウン・リストから「false」を選択してピボットを無効にします。

26.4 ピボット・テーブルでの選択の使用

ピボット・テーブルで選択すると、ピボット・テーブルの1つ以上のセルを選択できます。行ヘッダー、列ヘッダーまたはデータ・セルを含めて3つの領域のいずれか1つのみを一度に選択できます。

現在選択されているセルに基づいて、アプリケーションはポップアップ・メニューのカスタマイズされたコンテンツの表示などの機能を実装できます。例26-1に、現在選択されているヘッダー・セルを取得するためのサンプル・コードを示します。

例26-1 選択されているヘッダー・セルを取得するためのサンプル・コード

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();
}

実行時にデータ・セルを選択すると、図26-7に示すように、セルが強調表示されます。

図26-7 選択されたデータ・セル

セルをダブルクリックするか、セルを選択して[F2]キーを押すことで、編集可能なデータ・セルが開き編集できます。図26-8に示すように、直接編集する場合に選択したデータ・セルが表示されます。

図26-8 直接編集用に開かれたデータ・セル

図26-9に示すように、ドロップダウン・リストで編集する場合に選択したデータ・セルが表示されます。

図26-9 ドロップダウン・リスト編集用に開かれたデータ・セル

データ・セルの編集の有効化の詳細は、26.10項「ピボット・テーブルのデータ・セルのスタンプと編集」を参照してください。

26.5 ピボット・テーブルでのソート

ピボット・テーブルは、ピボット・テーブル内のデータのソートをサポートしています。ソートが有効な場合、列ヘッダーの最も内側のレイヤー上にカーソルを置くと、昇順および降順のソート・アイコンが表示されます。デフォルトでは、dvt:pivotTableコンポーネントのsortMode属性はgroupedに設定されているため、データは行エッジの最も外側のレイヤーを基準にグループ化されて効率的にソートされます。図26-10に、ピボット・テーブルの「World」売上げ列のソート・アイコンを示します。この場合、データは年の行エッジの最も外側のレイヤーを基準にグループ化されています。

図26-10 ピボット・テーブルの昇順および降順ソート・アイコン

26.6 ピボット・テーブルのサイズ

ピボット・テーブルの作成時、そのピボット・テーブル全体のサイズはデフォルト設定で決まります。ピボット・テーブルでは、全体サイズで使用できる領域内で行、列およびレイヤーのサイズが自動的に決まります。ピボット・テーブル全体のサイズを変更することも、その行、列およびレイヤーのサイズを変更することもできます。

26.6.1 ピボット・テーブル全体のサイズの設定方法

ピボット・テーブルのデフォルト・サイズは、横300ピクセル、縦300ピクセルです。ピクセルを入力するかわりに、横、縦、あるいはその両方にパーセンテージの値を指定できます。このパーセンテージ値は、ピボット・テーブルで使用するページの割当て分を指します。

ピボット・テーブルのデフォルト設定をカスタマイズする手順:

1. ビジュアル・エディタで、ピボット・テーブルを含むページを表示します。

2. 「ソース」をクリックしてJSPXページのXMLコードを表示します。

3. pivotTableタグのinlineStyle属性に、コードinlineStyle="width:value1;height:value2"を入力します。ここで、value1は、ピボット・テーブルの幅の単位タイプを含む整数、value2は、ピボット・テーブルの高さの単位タイプを含む整数です。

例26-2に、表の幅をページ・サイズの50パーセントに、表の高さを400ピクセルに指定するinlineStyle属性の設定を示します。

例26-2 ピボット・テーブルのサイズをカスタマイズするXMLコード

<dvt:pivotTable
.
.
.
inlineStyle="width:50%;height:400px">
</dvt:pivotTable>

26.6.2 行、列およびレイヤーのサイズを変更する方法

ピボット・テーブルは、初期表示の際は、行、列、レイヤーのサイズが自動設定されます。行、列またはレイヤーのサイズは、行セパレータ、列セパレータまたはレイヤー・セパレータを新しい位置にドラッグすることで、実行時に変更できます。

行、列およびレイヤーのサイズを実行時に変更する手順:

1. 行のサイズを変更する場合、次のようにします。

1. 行ヘッダーでサイズを変更する行とその次の行の間のセパレータにカーソルを置きます。

2. カーソルが両方向の矢印に変わったら、行セパレータをクリックして目的の位置にドラッグします。

2. 列のサイズを変更する場合、次のようにします。

1. 列ヘッダーでサイズを変更する列とその次の列の間のセパレータにカーソルを置きます。

2. カーソルが両方向の矢印に変わったら、列セパレータをクリックして目的の位置にドラッグします。

3. レイヤーのサイズを変更する場合、次のようにします。

1. 行または列ヘッダーでサイズを変更するレイヤーとその次のレイヤーの間のセパレータにカーソルを置きます。

2. カーソルが両方向の矢印に変わったら、レイヤー・セパレータをクリックして目的の位置にドラッグします。

26.6.3 行、列およびレイヤーのサイズの変更について

行、列またはレイヤーのサイズを変更した場合、ピボット操作を実行するまで、サイズは新しいサイズのままです。ピボット操作後、新しいサイズはクリアされ、ピボット・テーブルの行、列およびレイヤーは元のサイズに戻ります。

ピボット操作を行わない場合、セッション中は新しいサイズのままになります。ただし、MDS(メタデータ・サービス)のカスタマイズでこれらのサイズを保存することはできません。

26.7 部分ページ・レンダリングによるピボット・テーブルの更新

ピボット・テーブルを更新できます。たとえば、部分ページ・レンダリング(PPR)を使用してチェック・ボックスによってトリガーされるピボット・テーブルの合計を表示できます。PPRを使用すると、ページ全体をリフレッシュせずにページ上の特定のコンポーネントのみをレンダリングできます。PPRの詳細は、第7章「部分ページ・レンダリングの概要」を参照してください。

別のコンポーネントで発生したイベントに基づいてコンポーネントを再レンダリングするには、どのコンポーネントがトリガーかを宣言する必要があります。partialTriggers属性を使用してピボット・テーブルの部分更新をトリガーするコンポーネントのIDのリストを提供します。ピボット・テーブルはトリガー・コンポーネントをリスニングし、いずれかのトリガー・コンポーネントがなんらかの更新を発生させるイベントを受信すると、ピボット・テーブルも更新されます。

例26-3に、チェック・ボックスがトリガーされたときに、合計を表示することによってピボット・テーブルを更新するサンプル・コードを示します。トリガー・コンポーネントはIDをpartialTriggers値として使用します。

例26-3 ピボット・テーブルの部分更新

<dvt:pivotTable id="goodPT"
value="#{richPivotTableModel.dataModel}"
partialTriggers="showTotals"/>

<af:selectBooleanCheckbox id="showTotals" autoSubmit="true" label="Show Totals"
value="#{richPivotTableModel.totalsEnabled}"/>

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

ピボット・テーブルのデータは、Microsoft Excelスプレッドシートにエクスポートできます。コマンド・ボタンやコマンド・リンクなどのアクション・ソースを作成し、dvt:exportPivotTableDataコンポーネントを追加して、エクスポートするデータと関連付けます。ピボット・テーブル全体がエクスポートされるように、またはユーザーが選択した行のみがエクスポートされるようにdvt:exportPivotTableDataコンポーネントを構成できます。たとえば、図26-11に、ユーザーがExcelスプレッドシートにデータをエクスポートできるコマンド・ボタン・コンポーネントが含まれるピボット・テーブルを示します。

図26-11 Excelへのエクスポート・コマンド・ボタンが表示されたピボット・テーブル

ユーザーがコマンド・ボタンをクリックすると、すべての行と列はエクスポートされ、デフォルトでタグのfilename属性に指定されたファイルにExcel形式で書き込まれます。または、ユーザーが選択した行のみがエクスポートされるように、exportedData属性をselectedに設定して、dvt:exportPivotTableDataコンポーネントを構成することも可能です。例26-4に、「Excelにエクスポート」コマンド・ボタンのサンプル・コードを示します。

例26-4 「Excelにエクスポート」コマンド・ボタンのサンプル・コード

<af:commandButton text="Export To Excel" immediate="true">
<dvt:exportPivotTableData type="excelHTML" exportedId="goodPT"
filename="updated_export.xls" title="PivotTable export"/>
</af:commandButton>

図26-12に、結果のExcelスプレッドシートを示します。

図26-12 ピボット・テーブルからExcelスプレッドシートへのエクスポート

注意:

ファイルがファイルの拡張子で指定された形式と異なる旨の警告がExcelで表示される場合があります。この警告は無視して問題ありません。

26.9 ピボット・テーブルのセルのコンテンツのカスタマイズ

ピボット・テーブルのすべてのセルは、ヘッダー・セルまたはデータ・セルのいずれかです。セルをレンダリングする前、ピボット・テーブルではメソッド式がコールされます。dvt:pivotTableタグの次の属性にメソッド式を指定することで、ピボット・テーブルのヘッダー・セルとデータ・セルのコンテンツをカスタマイズできます。

- ヘッダー・セルには、次のいずれかの属性を使用します。

- headerFormat: ヘッダー・セルのコンテンツをカスタマイズする書式設定ルールの作成に使用します。

- headerFormatManager: アプリケーションのピボット・テーブルのヘッダー・セルの書式設定ルールに、カスタムの状態保存を指定する必要がある場合にのみ使用します。

- データ・セルには、次のいずれかの属性を使用します。

- dataFormat: データ・セルのコンテンツをカスタマイズする書式設定ルールの作成に使用します。

- dataFormatManager: アプリケーションのピボット・テーブルのデータ・セルの書式設定ルールに、カスタムの状態保存を指定する必要がある場合にのみ使用します。

26.9.1 データ・セルに対するCellFormatオブジェクトの作成方法

データ・セルのコンテンツのカスタマイズを指定するには、oracle.dss.adf.view.faces.bi.component.pivotTable.CellFormatのインスタンスを返すメソッド式をコーディングする必要があります。

データ・セルに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オブジェクトを返す必要があります。

26.9.2 CellFormatオブジェクトの作成方法

CellFormatオブジェクトのインスタンスには次の引数を指定できます。

- コンバータ: javax.faces.convert.Converterのインスタンス。セルの原値の数値、日付またはテキストの書式設定に使用されます。

- CSSスタイル: セルのCSSスタイルの変更に使用されます。たとえば、この引数を使用して、セルの背景色を変更します。

- CSSテキスト・スタイル: セルのテキストのCSSスタイルの変更に使用されます。たとえば、この引数を使用してテキストをボールドに設定します。

- 新規の原値: データ・モデルから返されるセルの基礎となる値の変更に使用されます。たとえば、州名の略記をフル・ネームに変更するよう選択できます。このケースでは、略記NYがNew Yorkに変更されます。

26.9.3 書式とテキスト・スタイルの変更方法

書式とテキスト・スタイルを適用して、ピボット・テーブルに表示されるデータの特徴を強調表示することができます。図26-13に、製品および製品カテゴリについて生成された売上げ合計のピボット・テーブルを示します。このピボット・テーブルでは、合計を含む行のテキストが太字(テキスト・スタイルの変更)で、背景が影付き(スタイルの変更)で表示されます。この変更は、ピボット・テーブルの行ヘッダー・セルとデータ・セルの両方に表示されます。合計の行ヘッダーには、Sales Totalというテキストが含まれています。

ピボット・テーブルには、データ・セルのストップライト書式設定と条件付き書式設定も示されています。詳細は、26.9.4項「ピボット・テーブルでのストップライト書式設定と条件付書式設定の作成方法」を参照してください。

図26-13 製品カテゴリごとの売上げデータ

例26-5に、ストップライト書式設定ではなく、売上げの合計に必要なカスタム書式を作成するサンプル・コードを示します。この例には、dvt:pivotTableタグのdataFormat属性とheaderFormat属性の両方にメソッド式のコードが含まれています。ピボット・テーブルにストップライト書式設定を含める場合、例26-6のコードを入れることができます。

例26-5 ピボット・テーブルのスタイルおよびテキスト・スタイルを変更するサンプル・コード

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.setTextStyle("font-weight:bold")
cellFormat.setStyle("background-color:#C0C0C0");
}
else if (product != null && product.toString().equals("Sales Total")
{
cellFormat.setTextStyle("font-weight:bold");
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",
"font-weight:bold");
}
}
return null;
}

26.9.4 ピボット・テーブルでのストップライト書式設定と条件付書式設定の作成方法

ピボット・テーブルのセルのストップライト書式設定と条件付き書式設定は、セルのコンテンツをカスタマイズする一例です。この種のカスタマイズでは、ユーザーはストップライト書式設定に関連付ける高値と低値を指定するようアプリケーションから要求されることがあります。通常、3つの色が次のように使用されます。

- 高値以上の値は緑に色付けされ、問題がないことを示します。

- 高値と低値の間の値は黄色に色付けされ、高度な基準に達していないことが警告されます。

- 低値以下の値は赤に色付けされ、最低限許容されるレベルに達していないことを示します。

図26-13に、最低限、許容範囲および基準以下の州の売上げに対するストップライト書式設定付きのデータ・セルを示します。

例26-6に、合計を表示しないピボット・テーブルでストップライト書式設定を行うコードを示します。合計を表示するピボット・テーブルでストップライト書式設定を行う場合は、(合計の行を扱う)例26-5のコードとストップライト書式設定と条件付き書式設定のコードを組み合せます。

例26-6 ストップライト書式設定と条件付き書式設定のサンプル・コード

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.10 ピボット・テーブルのデータ・セルのスタンプ設定および編集

ピボット・テーブル・データ・セルのコンテンツは、dvt:dataCell子コンポーネントを使用してスタンプ設定して、読取り専用コンポーネントまたは入力コンポーネントを各データ・セルに配置できます。スタンプを使用する場合、子コンポーネントは、ピボット・テーブルのすべてのデータ・セルに作成されるわけではありません。正しくは、dvt:dataCellコンポーネントのコンテンツが、ピボット・テーブルの行などのデータ属性ごとに1回、繰り返しレンダリング(スタンプ)されます。アクティビティのないすべてのコンポーネント、およびEditableValueHolderまたはActionSourceインタフェースを実装する大半のコンポーネントなど、特定のタイプのコンポーネントのみがサポートされます。スタンプ設定を使用して、データ・セルのカスタムCSSスタイルを指定することもできます。

子コンポーネントにスタンプが設定されるたびに、現在のセルのデータがEL式のデータ・セル・コンポーネントによって使用されるvarプロパティにコピーされます。ピボット・テーブルのレンダリングが完了したら、varプロパティは削除されるか前の値に戻ります。

データ・セルの編集は、dvt:dataCellの子コンポーネントとして入力コンポーネントを使用することによって有効化されます。ピボット・テーブルでセルをダブルクリックするか、セルを選択して[F2]キーを押すことで、実行時にセルを開いて編集できます。

例26-7に、データ・セルのスタンプ設定のサンプル・コードを示します。

例26-7 データ・セルのスタンプ設定のサンプル・コード

<dvt:pivotTable var="cellData" varStatus="cellStatus">
<dvt:dataCell>
<af:switcher defaultFacet="default" facetName="#{cellStatus.members.MeasDim.value}">
<f:facet name="Sales">
<af:inputText value="#{cellData.dataValue}"   />
</f:facet>
<f:facet name="Weight">
<af:outputText value="#{cellData.dataValue}" inlineStyle="#{cellStatus.cellFormat.textStyle}"/>
</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="default">
<af:outputText  value="#{cellData.dataValue}"   />
</f:facet>
</af:switcher>
</dvt:dataCell>
</dvt:pivotTable>

図26-14に、結果のピボット・テーブルを示します。

図26-14 データ・セルのスタンプ設定を使用したピボット・テーブル

注意:

キューブ内のセルのセットに値を一時的または完全に書き戻す操作(書戻しと呼ばれる)を行うには、ピボット・テーブルが書戻し操作をサポートするデータ・コントロールまたはデータ・モデルにバインドされている必要があります。行セット・ベースのデータ・コントロールはキューブに変換されるため、書戻し操作をサポートできません。

26.10.1 データ・セルのカスタム・イメージの指定方法

データ・セルのスタンプ設定では、dvt:dataCellタグを使用し、af:image、af:iconまたはaf:commandImageLinkを子タグとして使用してデータ・セルのカスタム・イメージを指定できます。例26-8に、ピボット・テーブル・データ・セルで、af:commandImageLinkをカスタム・イメージとして使用するサンプル・コードを示します。

例26-8 データ・セルへのカスタム・イメージの使用

<dvt:pivotTable var="cellData" varStatus="cellStatus">

<!-- This is the default data cell that will be used for all data attributes-->
<dvt:dataCell>
<af:commandImageLink text="Go"
icon="/images/go.gif"
actionListener="#{pivotTableBean.imageLinkClick}"/>
<af:outputText  value="#{cellData.dataValue}"   />
</dvt:dataCell>
</dvt:pivotTable>

イメージに関連するアクションは登録されたリスナー、actionListenerを使用して処理されます。Beanクラスでは、イメージ・リンクがクリックされると呼び出されるメソッドを次のように指定します。

public void imageLinkClick (javax.faces.event.ActionEvent.action)

26.10.2 ヘッダー・セルのイメージ、アイコン、リンクおよび読取り専用コンテンツの指定方法

データ・セルでスタンプ設定を使用する場合と同様に、dvt:headerCell子コンポーネントでヘッダー・セルのコンテンツをカスタマイズして、各ヘッダー・セルに読取り専用コンポーネントを配置できます。af:outputText、af:image、af:icon、af:commandImageLinkおよびaf:commandLinkなどの読取り専用コンポーネントまたは編集不可コンポーネントのみがサポートされます。

例26-9に、ピボット・テーブルのヘッダー・セルで、af:commandImageLinkをカスタム・イメージ、af:iconをカスタム・アイコンとして使用するサンプル・コードを示します。

例26-9 ヘッダー・セルでのカスタム・コンポーネントの使用

<dvt:pivotTable id="goodPT"
binding="#{pivotTableHeaderCellDemo.pivotTable}"
contentDelivery="immediate"
value="#{pivotTableHeaderCellDemo.dataModel}"
var="cellData"
varStatus="cellStatus">
<!-- header cell components -->
<dvt:headerCell>
<af:switcher defaultFacet="default" facetName="#{cellData.layerName}">
<f:facet name="Geography">
<af:outputText  value="#{cellData.label}"
shortDesc="#{cellData.label}"/>
<af:icon name="info" shortDesc="#{cellData.indent}" />
</f:facet>
<f:facet name="Channel">
<af:outputText  value="#{cellData.label}"  />
<af:commandImageLink shortDesc="Sample commandImageLink"
icon="/resources/images/pivotTableCSVDemo/smily-normal.gif"
hoverIcon="/resources/images/pivotTableCSVDemo/smily-glasses.gif"
/>
<af:commandButton text="Go to Tag Guide page" immediate="true"
action="guide" />
</f:facet>

<f:facet name="Product">
<af:outputText  value="#{cellData.label}" />
<af:commandButton text="Go to Tag Guide page" immediate="true"
action="guide" />
</f:facet>

<f:facet name ="default">
<af:commandLink text="#{cellData.label}"
immediate="true" action="guide"/>
</f:facet>
</af:switcher>
</dvt:headerCell>
...
</dvt:pivotTable>

図26-15に、結果のピボット・テーブルを示します。

図26-15 カスタマイズされたヘッダー・セルを含むピボット・テーブル

26.11 ピボット・テーブルでのピボット・フィルタ・バーの使用

ピボット・フィルタ・バーを追加することで、ピボット・テーブルのデータ・フィルタ機能を強化できます。ピボット・テーブルの行エッジまたは列エッジにまだ表示されていないデータのゼロ個以上のレイヤーは、ページ・エッジに表示されます。図26-16に、ピボット・テーブルに表示されるデータのフィルタ処理に使用可能な四半期および月のレイヤーを含むピボット・フィルタ・バーを示します。

図26-16 データ・レイヤー・フィルタを含むピボット・フィルタ・バー

行エッジ、列エッジまたはページ・エッジ間でレイヤーをピボットして、ピボット・テーブルのデータの表示を変更することもできます。必要に応じて、ピボット・ハンドルを使用してエッジ間でレイヤーをドラッグします。図26-17に、販路データ・レイヤーがページ・エッジにピボットされる場合に変更されたピボット・テーブルとピボット・フィルタ・バーを示します。

図26-17 ピボット後のピボット・テーブルとピボット・フィルタ・バー

26.11.1 ピボット・フィルタ・バーとピボット・テーブルを関連付ける方法

ピボット・フィルタ・バー・コンポーネントdvt:pivotFilterBarと、ピボット・テーブル・コンポーネントdvt:pivotTableを関連付けるには、両方のコンポーネントが連携するようにデータ・モデルと関連するプロパティを構成します。図26-10に、ピボット・フィルタ・バーとピボット・テーブルを関連付けるサンプル・コードを示します。

例26-10 ピボット・フィルタ・バーのサンプル・コード

<dvt:pivotFilterBar id="pf1" value="#{binding.pt.pivotFilterBarModel}"
modelName="pt1Model"/>
<dvt:pivotTable id="pt1" value="#{binding.pt.dataModel}"  modelName="pt1Model"
partialTriggers="pf1"/>

次のいずれかの方法で、ピボット・フィルタ・バーとピボット・テーブルを関連付けることができます。

- データ・コントロール・パネルを使用してピボット・テーブルを作成します。
データ・コントロール・パネルのデータ・コレクションをドラッグしてページにピボット・テーブルを作成する場合、ピボット・テーブルの作成ウィザードの「表示属性の選択」ページには、ピボット・テーブルと関連付けるピボット・フィルタ・バーを作成するオプションがあります。ページ・エッジのデータ・レイヤーを表すゼロ個以上の属性を指定するように選択できます。データ・モデルと関連するプロパティは、自動で構成されます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFピボット・テーブルの作成に関する項を参照してください。

- データにバインドされるピボット・テーブルにピボット・フィルタ・バーを追加します。
コンポーネント・パレットの「ADFデータ視覚化」ページで、データ・コレクションにバインドされているdvt:pivotTable要素の上にdvt:pivotFilterBar要素をドラッグできます。このインスタンスでは、ピボット・フィルタ・バーとピボット・テーブルが連携するように、データ・モデルと関連するプロパティを構成する必要があります。

- データにバインドされないピボット・テーブルにピボット・フィルタ・バーを追加します。
コンポーネント・パレットの「ピボット・テーブル」パネルの「ADFデータ視覚化」ページで、データ・コレクションにバインドされていないdvt:pivotTable要素の上にdvt:pivotFilterBar要素をドラッグできます。このインスタンスでは、ピボット・フィルタ・バーとピボット・テーブルが連携するように、データ・モデルと関連するプロパティを構成する必要があります。

27 ADF地理マップ・コンポーネントの使用

この章では、ADF地理マップ・コンポーネントとデータ・バインドされたテーマを使用してデータを表示する方法、およびマップのカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 27.1項「地理マップの概要」

- 27.2項「地理マップのデータ要件の理解」

- 27.3項「マップ・サイズ、ズーム制御および選択領域合計のカスタマイズ」

- 27.4項「マップ・テーマのカスタマイズ」

- 27.5項「ツールバーのマップへの追加」

ADF地理マップ・テーマのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADF地理マップの作成に関する項を参照してください。

27.1 地理マップの概要

地理マップ・コンポーネントは、フレームワーク内でOracle Spatialの機能を提供するデータ視覚化コンポーネントです。このコンポーネントでは、ユーザーはビジネス・データを地理マップ上に表し、1つのマップ上に複数層の情報(テーマと呼ばれる)を重ね合せることができます。

マップを作成する際、管理者がOracle SpatialのMap Builderツールを使用してすでに構成してある基準となるマップを選択するよう求められます。構成時、マップの管理者は、マップでサポートされるズーム・レベルを定義します。このレベルによって、ADF地理マップのズーム機能も決まります。

管理者は、Map Builderツールを使用して、事前定義のマップ・テーマを作成することもできます。たとえば、事前定義のテーマでは、地域を示すために特定の色を使用することがあります。ADF地理マップ・コンポーネントで、これらの事前定義マップ・テーマを選択できますが、テーマは基準となるマップの一部であるため、変更はできません。

基準となるマップは、ADF地理マップ・コンポーネントを使用してJDeveloperで情報のインタラクティブ・レイヤーを構築する背景となります。ADF地理マップには最低1つのレイヤーを定義する必要がありますが、必要な数のレイヤーを作成できます。

27.1.1 使用可能なマップ・テーマ

ADF地理マップには、様々なマップ・テーマがあり、各テーマをデータ・コレクションにバインドする必要があります。図27-1に、複数のテーマを持つマップを示します。次の種類のマップ・テーマが使用できます。

- 色:地域に適用されます。たとえば、ある地域の州の人口を表したり、地域の州での製品の人気を表す色のレンジを色テーマで指定できます。マップには、異なるズーム・レベルで表示される複数のカラー・テーマを使用できます。たとえば、色テーマはズーム・レベル1から5では州の人口を表し、ズーム・レベル6から10では郡の収入中央値を表すことができます。

- 点:マップ内で個々の緯度および経度の位置を表示します。たとえば、点テーマで倉庫の場所をマップに示します。表示するポイントのスタイルをカスタマイズする場合、倉庫のセット内の在庫の種類(電気製品、家庭用品、園芸用品)を区別するためにそれぞれ異なるイメージを使用するよう選択できます。

- グラフ:任意の数の円グラフ・テーマと棒グラフ・テーマを作成します。ただし、一度に表示できるグラフ・テーマは1つのみです。マップ・ツールバーの表示メニューからテーマを選択します。グラフ・テーマでは、州や郡など特定の地域に関連する統計を表示できます。たとえば、グラフ・テーマで州でのいくつかの製品の売上げの値を表示できます。

図27-1 色、点および円グラフ・テーマを使用した米国南西部の地理マップ

27.1.2 地理マップの用語

次のリストで、地理マップで使用される用語を簡単に説明します。

- 基準となるマップ:背景の地理データ、ズーム・レベルと、国、都市、道路などのアイテムの外観とプレゼンスを指定します。基準となるマップには、たとえば、オフィス・ビルのフロア・マップなど、MapViewerおよびMap Builderを使用して構成できる任意のイメージを使用できます。

- ズーム制御:マップの左上隅にレンダリングされるパン・アイコンとズーム・スライダで構成されます。図27-2に、最大にズーム・アウトされた(ズーム・レベルが0に設定された)マップのズーム制御を示します。ゼロではマップ全体が表示されます。
ズーム制御の位置と初期設定は、dvt:mapタグでカスタマイズできます。表示メニュー(サンプル・マップの上のマップ・ツールバーに表示される)で、ズーム制御の可視性を指定します。デフォルトでは、マップの初期ズーム・レベルは0に設定されています。

図27-2 マップのズーム制御

- パン・アイコン:ズーム制御の上部にある(東西南北、北東、北西、南東および南西を指す矢印の付いた)アイコンで構成されます。このアイコンを使用して、特定の方向にマップ全体を移動できます。

- ズーム・スライダー:大規模なズーム用のサム付きスライダーと1レベルのズーム用のアイコンで構成されます。プラスのアイコンを使用して一度に1レベルズーム・インし、マイナスのアイコンを使用して一度に1レベルズーム・アウトします。サムがスライダの最下部にあるとき、ズーム・レベルはゼロです。

- スケール:マップの左下隅の情報パネルの下、コピーライトの上に表示される2つの横方向のバーで構成されます。図27-3に、スケールを示します。上部のバーはマイル(mi)を示し、下部のバーはキロメートル(km)を示します。マイル・バーの上およびキロメートル・バーの下には、[距離] [単位]の形式でラベルが表示されます。バーの長さと距離の値は、ズーム・レベルとマップのパンに応じて変わります。

図27-3 マップの情報パネル、スケールおよびコピーライト

- 情報パネル:スケールの上の左下隅に緯度と経度を表示します。図27-3に、情報パネルを示します。デフォルトでは、情報パネルは表示されません。このパネルは、表示メニューから、あるいはツールバーの「情報」ボタンをクリックして表示できます。

- 測定パネル:現在使用しているツールバーのツールに応じて、距離、領域、半径のいずれかが表示されます。[ラベル] [値] [単位]の形式で、情報パネルの右にテキストが表示されます。図27-4に、距離測定の測定パネルを示します。領域測定および半径測定は、適切なラベルを使用して同様に表示されます。

図27-4 マップの情報パネルの横にある測定パネル

次のツールによって、測定パネルに情報が示されます。

- 領域測定:「面」、「長方形選択」または「マルチポイント選択」ツールがアクティブの場合にのみ表示されます。

- 距離測定:「距離」ツールがアクティブの場合にのみ表示されます。

- 半径測定:「円形選択」ツールがアクティブの場合にのみ表示されます。

- コピーライト: マップの左下隅に表示され、dvt: mapタグでカスタマイズできるテキストが含まれます。

- 概要マップ: 図27-5に示すような、メイン・マップの縮小表示で構成されます。このマップは、メイン・マップの右下隅に表示され、パン・ツールまたはパン・アイコンを使用せずにメイン・マップの表示領域を変更できます。

図27-5 概要マップ

次のアイテムは、概要マップの一部です。

- レチクル:メイン・マップの縮小表示内を移動できる小さなウィンドウとして表示されます。縮小マップ内のレチクルの位置によって、メイン・マップの表示領域が決まります。レチクルを移動すると、メイン・マップが自動的に更新されます。

- 「表示/非表示」アイコン:概要マップが表示されている場合、左上隅に表示されます。「表示/非表示」アイコンをクリックすると、概要マップが非表示になり、アイコンのみがメイン・マップの右下隅に表示されます。

- ツールバー:次の要素が次に示す順に含まれます。

- 表示メニュー:表示するテーマの制御、表示する特定のテーマの選択、ズーム制御、凡例および情報パネルの可視性の決定を行います。

- 「ツールバー」ボタン: マップとの相互作用のツール(パン、ズーム・イン、ズーム・アウト、長方形選択、円形選択、多角形選択、ポイント選択、距離、面、凡例および情報)が含まれます。

27.1.3 地理マップ・コンポーネントのタグ

地理マップには、親タグ、マップ子タグ、およびマップ・テーマを変更するタグがあります。

27.1.3.1 地理マップの親タグ

マップ・コンポーネントには次の親タグがあります。

- マップ・タグdvt:map: メイン・マップ・コンポーネント用親タグ。他のデータ視覚化の親タグとは異なり、マップ・タグはデータにバインドされません。かわりに、すべてのマップ・テーマ子タグが、個々にデータ・コレクションにバインドされます。マップ・タグには、基準となるマップのID、Oracle Application Server MapViewerサービスを実行しているリモート・サーバーのURL、住所をマッピング用の経緯度座標に変換するジオコーダWebサービスのURLなどのマップに関する一般的な情報が含まれます。子タグのリストと説明は、27.1.3.2項「地理マップの子タグ」を参照してください。

- マップ・ツールバーdvt:mapToolbar: マップを含むJSFページの任意の位置にマップ・ツールバーを配置する親タグ。このツールバーには、ツールバーに関連付けられているマップを指すmapID属性が含まれます。ツールバーによって、マップの凡例を表示する機能、選択や距離の測定を行う機能などのマップとの実行時の重要な相互作用が実行されます。マップ・ツールバー・タグには子タグはありません。

27.1.3.2 地理マップの子タグ

dvt:mapタグには、次の子タグがあります。

- 色テーマdvt:mapColorTheme: データ・コレクションにバインドするオプションのマップ・レイヤーの1つ。

- 点テーマdvt:mapPointTheme: データ・コレクションにバインドするオプションのマップ・レイヤーの1つ。点テーマで、マップ上の個々の位置が識別されます。

- 棒グラフ・テーマdvt:mapBarGraphTheme: データ・コレクションにバインドする必要があるオプションのマップ・レイヤーの1つ。このテーマでは、特定の地点に棒グラフが表示され、その地点に関連する複数のデータ値を表します。たとえば、このタグを使用して、倉庫の位置に在庫レベルを示すグラフを表示します。

- 円グラフ・テーマdvt:mapPieGraphTheme: データ・コレクションにバインドする必要があるオプションのマップ・レイヤーの1つ。このテーマでは、特定の地点に円グラフが表示され、その地点の複数の値を表します。たとえば、このタグを使用して、倉庫の位置に在庫レベルを示すグラフを表示します。

- マップ凡例dvt:mapLegend: マップを作成すると、自動的に作成されます。このタグを使用してマップの凡例をカスタマイズします。

- 概要マップdvt:mapOverview: マップを作成すると、自動的に作成されます。このタグを使用して、マップの右下隅に表示される概要マップをカスタマイズできます。

27.1.3.3 マップ・テーマを変更するタグ

次のタグで、様々なマップ・テーマを変更します。

- 点スタイルのアイテムdvt:mapPointStyleItem: dvt:mapPointThemeタグのオプションの子タグ。特定のデータ値の範囲内のポイントを表すイメージをカスタマイズする場合、このタグを使用します。複数のイメージを定義するには、各イメージのタグを作成し、関連付けるデータ値の範囲とイメージを指定します。

- 円グラフのスライス・セットdvt:mapPieSliceSet: dvt:mapPieGraphThemeタグの子。これは、マップの円グラフのスライスの色をカスタマイズする場合にdvt:mapPieSliceItemタグのラップに使用するオプションのタグです。

- 円グラフのスライスのアイテムdvt:mapPieSliceItem: dvt:mapPieSliceSetタグの子。円グラフの各スライス・アイテム・タグで、マップの円グラフの1スライスの色がカスタマイズされます。

- 棒グラフの系列セットdvt:mapBarSeriesSet: dvt:mapBarGraphThemeタグの子。これは、マップの棒グラフの棒の色をカスタマイズする場合にdvt:mapBarSeriesItemタグのラップに使用するオプションのタグです。

- 棒グラフの系列アイテムdvt:mapBarSeriesItem: dvt:mapBarSeriesSetタグの子。棒グラフの各系列アイテム・タグで、マップの棒グラフの1つの棒の色がカスタマイズされます。

27.2 地理マップのデータ要件の理解

次のデータ要件が地理マップに適用されます。

- 構成要件には、次の情報が含まれます。

- Map Viewer URL: Oracle Application Server MapViewerサービスのURLを指定する必要があります。このサービスは、ADF地理マップ・コンポーネントのレイヤーの背景である、基準となるマップの実行に必要です。OracleAS MapViewerは、Oracle Spatialで管理される空間データを使用してマップをレンダリングするプログラミング・ツールです。

- ジオコーダURL: 住所を座標に変換する場合、ジオコーダのURLを地理マップに指定する必要があります。ジオコーダは、住所をマッピング用の経緯度座標に変換するWebサービスです。

- 基準となるマップ: OracleAS MapViewerのMap Builderツールで作成された基準となるマップが必要です。この基準となるマップは、マップ・テーマが要望どおりに機能する詳細レベルで多角形を定義する必要があります。たとえば、特定の地域の各州にグラフを作成するために使用する円グラフ・テーマまたは棒グラフ・テーマがある場合、特定のズーム・レベルでこれらのすべての州に多角形を定義する基準となるマップを持つ必要があります。1つの多角形には1つのグラフのみを表示できます。

- マップ・テーマのデータ・コントロール: 各マップ・テーマはデータ・コントロールにバインドされる必要があります。データ・コントロールには、基準となるマップの同様の情報にバインド可能な位置情報が含まれる必要があります。

27.3 マップ・サイズ、ズーム制御および選択領域合計のカスタマイズ

マップのサイズ、ズーム方法、選択した地域の外観および情報ウィンドウとスケール・バーの初期表示をカスタマイズできます。

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

dvt:mapタグのinlineStyle属性を使用して、マップの幅と高さを制御できます。

マップのサイズを調整する手順:

1. 構造ウィンドウでdvt:mapノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「スタイル」属性カテゴリで、inlineStyle属性に幅と高さを入力します。
たとえば、幅600ピクセル、高さ400ピクセルを指定するには、inlineStyle="width:600px;height:400px"という設定を使用します。

幅はページで使用可能な幅すべてで、高さが400ピクセルの場合、inlineStyle="width:600px;height:400px"という設定を使用します。

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

dvt:mapタグの複数の属性で、初期ズーム・レベル、開始位置、初期マップ・テーマおよびズーム・ストラテジを制御できます。

マップの初期ズームおよび開始位置を制御する手順:

1. 構造ウィンドウでdvt:mapノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「外観」属性カテゴリで、次の属性に値を入力します。

1. AutoZoomThemeIDに、最初に表示されるテーマのIDを入力します。

2. ZoomBarStrategyに、autoZoomThemeIdのすべてのオブジェクトが表示される最大レベルまでズームするようマップに指示するデフォルト値MAXZOOMを選択するか、autoZoomThemeIdのテーマを中心とし、ズーム・レベルをmapZoom属性の値に設定するようマップに指示するCENTERATZOOMLEVELを選択します。

3. マップの開始位置を変更するには、startingXとstartingYにそれぞれ緯度と経度を入力します。

4. MapZoomに、マップの初期ズーム・レベルを入力します。この設定は、ズーム・バー・ストラテジCENTERATZOOMLEVELに必要です。

注意:

autoZoomThemeIDプロパティはmapZoomで設定されたプロパティより優先されます。

27.3.3 マップの選択値の合計方法

長方形選択などのマップ選択ツールによって選択されたマップ領域に関連付けられている値を合計する選択リスナーを使用できます。合計はマップの下の領域に表示されます。バッキングBeanメソッド内で引数にMapSelectionEventをとるクラスを指定します。例27-1に、バッキングBeanのサンプル・コードを示します。

例27-1 選択リスナー用のバッキング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. 構造ウィンドウで地理マップのノードを右クリックし、「プロパティに移動」を選択します。

2. 「動作」属性カテゴリで、SelectionListenerフィールドにバッキングBeanを指すメソッド参照を入力します。次に例を示します。

27.4 マップ・テーマのカスタマイズ

各種マップ・テーマは、マップ・テーマ・バインディング・ダイアログ、テーマ・タグの属性またはテーマ・タグの子タグのいずれか1つ以上を使用してカスタマイズできます。

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

すべてのマップ・テーマについて、基準となるマップの関連するズーム・レベルに合うズーム・レベルがテーマで指定されていることを確認します。たとえば、基準となるマップで6から8のズーム・レベルでのみ郡が表示される場合、郡ごとのポイントまたはグラフを表示するテーマには、6から8のズーム・レベルのみを適用します。

マップ・テーマのズーム・レベルをカスタマイズする手順:

1. 構造ウィンドウで、カスタマイズするマップ・テーマ・タグ(dvt:mapColorTheme、dvt:mapPointTheme、dvt:mapBarGraphThemeまたはdvt:mapPieGraphTheme)を見つけます。

2. タグを右クリックして、「プロパティに移動」を選択します。

3. プロパティ・インスペクタの「外観」属性カテゴリで、MinZoom属性とMaxZoom属性にそれぞれ低ズーム値と高ズーム値を入力します。

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

テーマが凡例またはテーマ選択ダイアログに表示される際、デフォルトでは、マップ・テーマのIDがラベルとして使用されます。ただし、各マップ・テーマ・タグには、テーマのオプション・ラベルとして機能する次の属性があります。

- shortLabel: マップ凡例に表示される際のテーマのレベルを指定します。

- menuLabel: テーマ選択ダイアログでのテーマのラベルを指定します。

これらの属性を使用してテーマのタイプ(色、点、棒グラフまたは円グラフ)とデータ(人口、売上げ、在庫など)の両方がわかるラベルを作成し、使用可能なテーマをユーザーが簡単に認識できるようにします。

マップ・テーマのラベルをカスタマイズする手順:

1. 構造ウィンドウで、カスタマイズするマップ・テーマ・タグを見つけます。

2. タグのノードを右クリックして、「プロパティに移動」を選択します。

3. プロパティ・インスペクタの「外観」属性カテゴリで、shortLabel属性(凡例での表示の場合)およびmenuLabel属性(テーマ選択ダイアログの場合)にテキストを入力します。
たとえば、人口に応じてニュー・イングランドの州を色付けする色テーマの場合、次のテキストを入力します。

shortLabel="Color - Population, NE Region"

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

色マップ・テーマを作成する際、背景レイヤーに使用する色をカスタマイズできます。最小レンジと最大レンジに関連付ける色を指定し、テーマに使用する色レンジの数を指定できます。たとえば、色がマップ上の人口と関連する場合、人口が最も少ないエリアには最小色が表示され、人口が最も多いエリアには最大色が表示されます。最小色と最大色の間の色のグラデーションが、これらの値の間のレンジに表示されます。

色マップ・テーマの色をカスタマイズする手順:

1. 構造ウィンドウでdvt:mapColorThemeノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「テーマ・データ」属性カテゴリで次のようにします。

- データ値の最小レンジと最大レンジに関連付けられているデフォルト色を変更する場合は、MinColor属性とMaxColor属性の色をそれぞれ選択します。

- このテーマのデフォルトの色レンジの数を変更する場合は、bucketCount属性の整数を変更します。

たとえば、<dvt:mapColorTheme minColor="#000000" maxColor= "#ffffff" bucketCount="5"/>の場合、5つのバケットの色は#000000、#444444、#888888、#bbbbbb、#ffffffになります。

または、各バケットの色を指定できます。複数のバケットの色を指定するには、dvt:mapColorThemeのcolorList属性に、属性への色配列をバインドするか、セミコロンで区切った文字列を使用します。色はRGB16進数を使用して指定できます。たとえば、値がcolorList="#ff0000;#00ff00;#0000ff"の場合、最初のバケットの値は赤、2番目のバケットの値は緑、3番目のバケットの値は青になります。

27.4.4 点テーマのポイント・イメージのカスタマイズ方法

マップの点テーマでは、デフォルトのイメージを使用して各ポイントが示されます。ただし、点テーマに複数のカスタム・イメージを指定し、各イメージが表すデータの範囲を指定できます。

マップの点テーマで使用するカスタム・イメージごとにdvt:mapPointStyleItemタグを定義します。

マップ点テーマのポイントのイメージをカスタマイズする手順:

1. 構造ウィンドウでdvt:mapPointThemeノードを右クリックし、「dvt:mapPointThemeの中に挿入」→「点スタイルのアイテム」を選択します。

2. 続く点スタイルのアイテムの挿入ウィザードで、次のようにして、このカスタム・ポイントのデータ値の範囲に対する設定を行います。

1. ウィザードのステップ1(共通プロパティ)で、マップでこのカスタム・イメージに対するデータ値の範囲内のポイントに表示されるイメージのURLを指定する必要があります。

2. ウィザードのステップ2(アドバンスト・プロパティ)で、MaxValueとMinValueのフィールドにこのカスタム・イメージが表すデータ値の範囲を指定します。

3. 「ID」フィールドに、定義するカスタム・イメージの一意の識別子を入力します。

4. 「ショート・ラベル」フィールドに、このタグで表される範囲内のポイント上にユーザーがカーソルを置いたときに実際のデータ値の前に表示されれる説明テキストを指定します。
たとえば、最小データ値範囲内のカスタム・ポイントに、「低在庫」というテキストを入力します。

5. 必要に応じて、ホバー・イメージと選択済イメージに異なるイメージURLを指定します。

6. 「終了」をクリックします。

3. 点テーマに対して作成するカスタム・イメージごとにステップ1とステップ2を繰り返します。

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

点スタイルのアイテムの挿入ウィザードを使用して、点テーマのデータ値の範囲を表すカスタム・イメージを指定する場合、子タグdvt:mapPointStyleItemは、親タグdvt:mapPointTheme内に定義されます。例27-2に、各倉庫ポイントの在庫の範囲を表す3つのカスタム・ポイント・イメージを持つマップ点テーマに対し、JSFページに生成されるコードを示します。

最初の点スタイル設定(ps0)は、500を超えない値に適用されます。この点スタイルでは、非常に少ない在庫用のイメージを表示し、対応するツールチップ情報が示されます。

2番目の点スタイル設定(ps1)は、500から1000の値に適用されます。この点スタイルでは、少ない在庫用のイメージを表示し、対応するツールチップ情報が示されます。

最後の点スタイル設定(ps2)は、1000から1600の値に適用されます。この点スタイルでは、多い在庫用のイメージを表示し、対応するツールチップ情報が示されます。

例27-2 カスタム・ポイント・イメージを使用するマップ点テーマのコード

<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>

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

マップ棒グラフ・テーマを作成すると、デフォルトの色がグラフの棒に割り当てられます。棒の色は、mapBarSeriesSetタグとmapBarSeriesItemタグを使用してカスタマイズできます。

1つのmapBarSeriesSetタグを使用して、棒グラフ・テーマのすべてのmapBarSeriesItemタグをラップし、グラフ内の棒ごとにmapBarSeriesItemタグを挿入します。

マップ棒グラフ・テーマの棒の色をカスタマイズする手順:

1. 構造ウィンドウでdvt:mapBarGraphThemeタグを右クリックし、「dvt:mapBarGraphThemeの中に挿入」→マップの棒系列の設定を選択します。
このタグに設定する属性はありません。個々の棒系列アイテムのタグのラップに使用されます。

2. 構造ウィンドウでdvt:mapBarSeriesSetタグを右クリックし、「dvt:mapBarSeriesSetの中に挿入」→マップの棒系列のアイテムを選択します。

3. プロパティ・インスペクタで、グラフに表示される最初の棒に使用する一意のIDと色を入力します。
グラフ内の棒の順序を調べるには、「棒グラフ・マップ・テーマ・バインディングの編集」ダイアログを確認します。このダイアログの系列の属性列のエントリの順序で、グラフに表示される棒の順序が決まります。たとえば、図27-6では、グラフの最初の棒は「Income2000」を表し、2番目の棒は「Income2005」を表します。

図27-6 「棒グラフ・マップ・テーマ・バインディングの編集」ダイアログ

4. グラフ内の棒ごとにステップ3を繰り返します。

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

「棒グラフ・マップ・テーマ・バインディングの編集」ダイアログを使用して、マップ棒グラフ・テーマの棒をカスタマイズする場合、棒の順序は、ダイアログの「系列属性」列のエントリの順序になります。例27-3に、マップ棒グラフの棒をカスタマイズする場合のサンプルXMLコードを示します。

例27-3 マップ棒グラフの棒をカスタマイズする場合のコード

<dvt:map
.
.
.
<dvt:mapBarGraphTheme
.
.
.
<dvt:mapBarSeriesSet>
<dvt:mapBarSeriesItem color="#333399" id="bar1"/>
<dvt:mapBarSeriesItem color="#0000ff" id="bar2"/>
</dvt:mapBarSeriesSet>
</dvt:mapBarGraphTheme>
</dvt:map>

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

マップ円グラフ・テーマを作成すると、デフォルトの色がグラフのスライスに割り当てられます。スライスの色は、mapPieSlicesSetタグとmapPieSliceItemタグを使用してカスタマイズできます。

1つのmapPieSliceSetタグを使用して、円グラフ・テーマのすべてのmapPieSliceItemタグをラップし、グラフ内のスライスごとにmapPieSliceItemタグを挿入します。

マップ円グラフ・テーマのスライスの色をカスタマイズする手順:

1. 構造ウィンドウでdvt:mapPieGraphThemeタグを右クリックし、「dvt:mapPieGraphThemeの中に挿入」→「円グラフの区分の設定」を選択します。
このタグに設定する属性はありません。個々の円グラフ・アイテムのタグのラップに使用されます。

2. 構造ウィンドウでdvt:mapPieSliceSetノードを右クリックし、「dvt:mapPieSliceSetの中に挿入」→「円グラフの区分のアイテム」を選択します。

3. プロパティ・インスペクタで、グラフに表示される最初のスライスに使用する一意のIDと色を入力します。
グラフ内のスライスの順序を調べるには、「円グラフ・マップ・テーマ・バインディングの編集」ダイアログを確認します。このダイアログの「円グラフの区分の属性」列のエントリの順序で、グラフに表示されるスライスの順序が決まります。たとえば、図27-7では、グラフの最初のスライスは「Sales」を表し、2番目のスライスは「Profit」を表し、3番目のスライスは「Cost」を表します。

図27-7 「円グラフ・マップ・テーマ・バインディングの編集」ダイアログ

4. グラフ内のスライスごとにステップ3を繰り返します。

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

「円グラフ・マップ・テーマ・バインディングの編集」ダイアログを使用して、マップ円グラフ・テーマのスライスをカスタマイズする場合、スライスの順序は、ダイアログの「円グラフの区分の属性」列のエントリの順序になります。例27-4に、マップ円グラフのスライスをカスタマイズする場合にJSFページに生成されるサンプルXMLコードを示します。

例27-4 マップ円グラフのスライスをカスタマイズする場合のコード

<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>

27.5 ツールバーのマップへの追加

凡例と情報パネルの表示やテーマの選択(同じタイプの複数のテーマがある場合)を行ったり、距離測定、領域測定または選択ツールを使用できるようにする場合、ADF地理マップを作成する際、マップ・ツールバーも作成します。

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

マップ・ツールバーはマップとは別のコンポーネントのため、JSFページでマップの上にも下にもツールバーを配置できます。次の手順では、JSFページにマップ・コンポーネントがあるものとします。

マップ・ツールバーを作成する手順:

1. 構造ウィンドウでdvt:mapノードを右クリックし、「dvt:mapの前に挿入」または「dvt:mapの後ろに挿入」→「ADFデータ視覚化」と選択します。

2. ADFデータ視覚化アイテム・ダイアログで、「ツールバー」を選択します。

3. 表示されるツールバーの挿入ウィザードで、このツールバーで操作するマップのIDを入力し、「次へ」をクリックします。

4. ツールバーの一意のIDを入力し、各ツールの可視性を制御する設定を必要に応じて変更します。

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

ツールバーをマップに追加すると、次のようになります。

- JSFページのマップの上または下に、指定したとおりツールバーが表示されます。1つ以上のツールの可視性を変更しないかぎり、ツールバーにはすべてのツールが含まれます。

- XMLコードが生成され、JSFページのマップのコードの上または下に表示されます。

例27-5に、IDがmap_usのマップに関連付けられているツールバーのサンプル・コードを示します。マップのコードの位置も示します。

例27-5 マップ・ツールバーに対して生成されるコード

<af:form>
<dvt:mapToolbar mapId="map_us" id="T1"/>
<dvt:map  id="map_us"
.
.
.
</dvt:map>
</af:form>

28 ADFガント・チャート・コンポーネントの使用

この章では、データ・バインドされたADFガント・チャート・コンポーネントを使用してデータを表示する方法とガント・チャートのカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 28.1項「ADFガント・チャート・コンポーネントの概要」

- 28.2項「ガント・チャート・タグとファセットの理解」

- 28.3項「ガント・チャートのユーザー対話性の理解」

- 28.4項「ガント・チャートのデータ要件の理解」

- 28.5項「ADFガント・チャートの作成」

- 28.6項「ガント・チャートの凡例、ツールバーおよびポップアップ・メニューのカスタマイズ」

- 28.7項「ガント・チャートのタスクとリソースの使用」

- 28.8項「休日、読取り専用機能および時間軸の指定」

- 28.9項「ガント・チャートの印刷」

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

ADFガント・チャートのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFガント・チャートの作成に関する項を参照してください。

28.1 ADFガント・チャート・コンポーネントの概要

ガント・チャートは、横棒グラフの一種で、プロジェクトの計画と追跡に使用します。これには、開始と終了が明確な時間枠にリソースやタスクが表示されます。ADFガント・チャート・コンポーネントは2つの領域で構成されます。1つは、表のガント・チャート・データを表示し、もう1つは、サイズ変更可能なスプリッタを使用して2つの領域間のガント・チャート・データをグラフィカルに表示します。表領域とチャート領域は、2つの領域間で、同じデータと選択モデル、スクロールのサポートと同期、および行の展開と折りたたみを共有します。

実行時に、ガント・チャートでは表領域にデータの入力、行の展開および縮小、列の表示および非表示、行へのナビゲート、および列のソートおよび合計の表示などの対話機能がユーザーに提供されます。表領域で、ユーザーはタスクを新しい日付にドラッグし、複数のタスクを選択して依存性を作成し、タスクの日付を拡張できます。ガント・チャートのツールバーは、データの表示の変更またはフィルタ処理、およびタスクの作成、削除、切取り、コピーおよび貼付けなどのユーザー操作のサポートに使用します。

ガント・チャートの領域は、両方ともADF Facesのツリー表コンポーネントに基づいています。行の仮想化を含むADFのツリー表の詳細は、第10章「表およびツリーの使用」を参照してください。

28.1.1 ガント・チャートのタイプ

ガント・チャートには次のコンポーネントが用意されています。

- プロジェクト・ガント・チャート: プロジェクト・ガント・チャートはプロジェクト管理に使用されます。このチャートでは、タスクを縦にリストし、横向きの予定表に各タスクの期間を棒で示します。図28-1に示すように各タスクを別の線で示します。

図28-1 ソフトウェア・アプリケーション用プロジェクト・ガント・チャート

- リソース使用率ガント・チャート: リソース使用率ガント・チャートでは、リソースのメトリック、たとえばリソースが割当てを上回っているか下回っているかをグラフィカルに示します。リソースを縦に示し、横方向の時間軸に割当てとキャパシティなどのメトリックを示します。図28-2に、指定した期間の特定の開発者リソースに割り当てられ、利用されている時間を表示するリソース使用率ガント・チャートを示します。

図28-2 ソフトウェア・アプリケーション用リソース使用率ガント・チャート

- スケジュール・ガント・チャート: スケジュール・ガント・チャートはリソースのスケジュールに使用されます。このチャートは手動のスケジュール表をベースにし、リソースを縦に表示し、対応するアクティビティを横方向の時間軸に表示します。リソースの例には、人、機械、部屋などがあります。スケジュール・ガント・チャートでは、図28-3に示すように、リソースに割り当てられている全タスクが1つの線で示されます。

図28-3 ソフトウェア・アプリケーション用スケジュール・ガント・チャート

28.1.2 ガント・チャートの機能領域

ガント・チャートは次の機能領域で構成されます。

- 表領域:ガント・チャート・データ属性を表の列に表示します。表領域には最低1つの列が必要ですがガント・チャート・データ・バインディング・ダイアログで必要な数の列に属性を定義できます。
たとえば、図28-1では、表領域に、Name(タスクの)、Priority、Orig.Est.、Curr.Est.、Elapsed(日数)、Remaining(日数)およびResourcesの列が含まれています。

- チャート領域:ガント・チャート・データの棒グラフを横方向の時間軸に沿って表示します。時間軸にはズーム用の主設定と副設定があります。主設定はより大きな時間単位用で、副設定はより小さな時間単位用です。
たとえば、図28-1のチャート領域には、曜日を示す時間軸にタスクが表示されています。

- 情報パネル:情報領域(選択されたタスクまたは選択されたリソースに関するメトリックスに関するテキストを表示)とオプションの凡例(タスク・タイプを表示)を表領域とチャート領域の下に表示します。親ガント・チャート・タグ内に凡例子タグを挿入しないかぎり、ガント・チャートの凡例はないことに注意してください。

- ツールバー:ユーザーのガント・チャートの操作を可能にします。ツールバーはデフォルトでガント・チャートに表示されます。ガント・チャートのプロパティ・インスペクタの「外観」ページでShowToolbar属性を設定することにより、ツールバーの可視性を変更できます。
ツールバーは次のセクションで構成されます。

- メニュー・バー:ツールバーの左側の部分には、ガント・チャートに対するメニューのセットが含まれます。各ガント・チャート・タイプには、デフォルトのオプションのセットがあります。図28-4に、ガント・チャートにデフォルトで表示されるメニュー・バーを示します。ガント・チャートのプロパティ・インスペクタの「外観」ページでShowMenuBar属性を設定することにより、メニュー・バーの可視性を変更できます。menubarファセットを使用してメニュー項目をカスタマイズできます。

注意:

表示メニュー・アイテムが機能するように、アプリケーション・コードを作成する必要はありません。ただし、他のメニューで使用する項目にはアプリケーション・コードが必要です。

図28-4 ガント・チャートのサンプル・メニュー・バー

- ツールバー・ボタン:ツールバーの右側の部分には、ガント・チャートを操作するためのアクション・ボタンのセットが表示されます。各ガント・チャート・タイプには、デフォルトのオプションのセットがあります。図28-5に、プロジェクト・ガント・チャートのサンプル・ツールバーを示します。

図28-5 プロジェクト・ガント・チャートのサンプル・ツールバー

toolbarファセットを使用してツールバー・ボタンをカスタマイズできます。

- ポップアップ・メニュー:ガント・チャート表領域またはチャート領域を右クリックすると、標準のメニュー項目のセットがポップアップ・メニューに表示されます。tablePopupMenuファセットまたはchartPopupMenuファセットを使用して独自のメニュー項目のセットを使用できます。

- 印刷サービス:ガント・チャートには、XML Publisherと連動してPDFファイルを生成し、印刷する機能が用意されています。詳細は、28.9項「ガント・チャートの印刷」を参照してください。

28.1.3 ガント・チャートのタスクの説明

プロジェクト・ガント・チャートおよびスケジュール・ガント・チャートでは、チャート領域でのタスクのレンダリング方法を説明する書式設定プロパティのセットが指定された事前定義済タスクが使用されます。すべてのサポートされるタスクには一意の識別子が必要です。次のリストで、サポートされるタスクとガント・チャートでの外観を説明します。

- 標準:基本的なタスク・タイプ。プレーンな横棒でタスクの開始時期、終了時期および期間を示します。

- サマリー:サブタスクのグループの開始日と終了日。サマリー・タスクは移動や伸長できません。サブタスクの日付が変更された場合、アプリケーションで、サマリー・タスクの開始日と終了日をかわりに再計算する必要があります。サマリー・タスクはプロジェクト・ガント・チャートにのみ使用できます。

- マイルストン:ガント・チャートの特定の日付。マイルストン・タスクに関連付けられる日付は1つのみです。マイルストン・タスクは伸長できませんが、移動できます。マイルストン・タスクはプロジェクト・ガント・チャートにのみ使用できます。

- 再帰:ガント・チャートで繰り返されるタスクで、各インスタンスには独自の開始日および終了日が含まれます。個々の再帰タスクにはオプションでサブタイプを含めることができます。個々の再帰タスクのその他すべてのプロパティには、そのタスクが一部となっているタスクのプロパティが使用されます。ただし、個々の再帰タスクにサブタイプがある場合は、このサブタイプがタスク・タイプをオーバーライドします。

- 分割:2つの横棒に分割されたタスクで、通常は線でつながっています。棒の間の時間は、移動時間または停止時間によるアイドル時間を表します。

- スケジュール済:スケジュール・ガント・チャートの基本的なタスク・タイプ。このタスク・タイプはタスクの開始時期、終了時期および期間、および指定されている場合は起動時期を示します。

標準タスク、サマリー・タスクおよびマイルストン・タスクでは、タスクの外観およびアクティビティを変更する追加の属性がサポートされています。次にこれらのスタイル属性を示します。

- percentComplete、completedThrough: タスクの完了度を示す追加の棒グラフが描画されます。これは標準タスク・タイプおよびサマリー・タスク・タイプに適用されます。

- critical: 棒グラフの色が赤に変更され、クリティカルとしてマークされます。これは標準タスク・タイプ、サマリー・タスク・タイプおよびマイルストン・タスク・タイプに適用されます。

- actualStartおよびactualEnd: これらの属性が指定されると、1つの棒グラフではなく2つの棒グラフが描画されます。1つの棒グラフはベース開始日およびベース終了日を示し、もう1つの棒グラフは実際の開始日および終了日を示します。これは標準タスク・タイプおよびマイルストン・タスク・タイプに適用されます。

図28-6に、プロジェクト・ガント・チャートの一般的なタスク・タイプを表示する凡例を示します。

図28-6 プロジェクト・ガント・チャートのタスク・タイプ用凡例

28.2 ガント・チャート・タグとファセットの理解

各ガント・チャート・タグ名が接頭辞dvt:で始まる3つのガント・チャート・コンポーネントは、タグがADF Data Visualization Tools(DVT)タグ・ライブラリの1つであることを示します。

- dvt:projectGantt

- dvt:resourceUtilizationGantt

- dvt:schedulingGantt

すべてのガント・チャート・コンポーネントが子タグdvt:ganttLegendをサポートして、ガント・チャートの情報パネルにオプションの凡例を提供します。一部のメニュー・バーおよびツールバーの機能は、ガントの凡例が指定されているかどうかによって使用できる場合とできない場合があります。

ガント・チャート表領域では、ADF Faces af:columnタグを使用して、ヘッダー・テキスト、アイコンおよびデータの位置合せ、列の幅、および列にバインドされたデータを指定できます。データを階層構造で表示するには、nodeStampファセットで階層の要素の1次識別子を指定します。たとえば、"Task Name"列をプロジェクト・ガント・チャートのnodeStampファセットとして使用することもできます。例28-1に、"Task Name"をnodeStampファセットとして使用し、Resource、Start DateおよびEnd Dateの列を持つプロジェクト・ガント・チャートのサンプル・コードを示します。

例28-1 プロジェクト・ガント・チャートの列のサンプル・コード

<dvt:projectGantt 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ファセットに加え、他のファセットもガント・チャート・コンポーネントによってカスタマイズに使用されます。表28-1に、ガント・チャート・コンポーネントによってサポートされているファセットを示します。

表28-1 ガント・チャート・コンポーネントによってサポートされているファセット

名前

説明

chartPopupMenu

チャート領域のポップアップ・メニューに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:popupコンポーネントである必要があります。

customPanel

タスク・プロパティ・ダイアログの「カスタム」タブに表示されるコントロールの識別に使用するコンポーネントを指定します。

major

主時間軸の識別に使用するコンポーネントを指定します。dvt:timeAxisコンポーネントである必要があります。

menuBar

ガント・メニュー・バーに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:menuコンポーネントである必要があります。

minor

副時間軸の識別に使用するコンポーネントを指定します。dvt:timeAxisコンポーネントである必要があります。

nodeStamp

ガント・チャートの各要素のスタンプ設定に使用するコンポーネントを指定します。アクティビティのないすべてのコンポーネント、およびEditableValueHolderまたはActionSourceインタフェースを実装する大半のコンポーネントなど、特定のタイプのコンポーネントのみがサポートされます。af:columnコンポーネントである必要があります。

tablePopupMenu

表領域のポップアップ・メニューに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:popupコンポーネントである必要があります。

toolbar

ガント・ツールバーに表示される追加のコントロールの識別に使用するコンポーネントを指定します。af:toobarコンポーネントである必要があります。

すべてのガント・チャート・タグとその属性の詳細、および有効な値のリストは、DVTタグのドキュメントを参照してください。JDeveloperで特定のタグのドキュメントにアクセスするには、構造ウィンドウでタグを選択し、[F1]キーを押します。JDeveloperのヘルプでADF Data Visualization Toolsタグ・ライブラリにアクセスするには、オンライン・ヘルプの目次でJavadocとタグ・ライブラリ・リファレンスのノードを開き、「JDeveloperタグ・ライブラリ・リファレンス」トピックのタグ・ライブラリへのリンクをクリックします。

28.3 ガント・チャートのユーザー対話性の理解

実行時に、ユーザーはガント・チャートでナビゲーションと表示、および表領域またはチャート領域でデータを変更するアクションなど、様々な操作を実行できます。

ユーザーとの対話にデータの変更が伴う場合、ガント・チャートでは検証、イベント処理およびデータ・モデルの更新を実行することによって変更が処理されます。検証では、送信されたデータが基本的な要件を満たしていること、たとえば日付が有効で休日の期間に該当しないことなどが確認できます。検証に失敗すると、データ・モデルの更新が省略され、エラー・メッセージが返されます。

ガント・チャートのサーバー側イベントが開始されると、変更に関する検証された情報を含むイベントが登録されたリスナーに送信されます。リスナーは基礎となるデータ・モデルを更新します。カスタマイズされたイベント・ハンドラは、ガント・チャート・コンポーネントのdataChangeListener属性でメソッド・バインディング式を指定することによって登録できます。

ガント・チャートによってサポートされるサーバー側イベントには、次のものが含まれます。

- ガント・チャート表領域における表のセルのデータ更新

- タスクの作成、更新、削除、移動、切取り、コピー、貼付け、インデント、アウトデント

- タスク・バーを1つの行から別の行にドラッグすることによるリソースの再割当て

- 別の日付へのタスク・バーのドラッグ

- タスクの期間の延長

- タスクのリンク付けまたはリンク解除

- ガント・チャート表領域での単一の行または複数の行の選択

- ユーザー・アクションを元に戻すまたはやり直し

- タスク・バーのダブルクリック

ユーザーはツールバーからドロップダウン・リストを使用してガント・チャートのデータをフィルタ処理できます。カスタム・フィルタを作成できます。

28.3.1 ガント・チャートでの移動

スクロールを使用してガント・チャートの領域を移動したり、チャート領域で特定の日付にアクセスできます。表領域の列を表示するかどうかも制御できます。

28.3.1.1 リスト領域またはチャート領域のスクロールとパン

ガント・チャートの設計により、表領域とチャート領域の横方向のスクロールを別々に行えます。これは、表領域で特定のタスクまたはリソース情報を保持しつつ、チャート領域でスクロールして複数期間の情報を得る場合に特に有用です。

[CTRL]キーを押しながらマウス・スクロール・ホイールを使用して、ガント・チャートのタイム・スケールをズーム・インまたはズーム・アウトすることもできます。

プロジェクトおよびスケジュール・ガント・チャートでは、マウスを使用してチャート領域を縦および横にドラッグすることでその領域をパンすることができます。タスク以外のチャート領域内をクリックすると、移動カーソルが表示されます。

28.3.1.2 ガント・チャートでの特定の日付への移動方法

ガント・チャートのチャート領域で特定の日付に移動できます。

ガント・チャートで特定の日付に移動する手順:

1. 「表示」メニューで、「日付へ移動」を選択します。

2. 「日付に移動」ダイアログで、「日付の選択」アイコンをクリックし、カレンダで日付を選択して、目的の日付を指定します。

3. 「OK」をクリックします。

ガント・チャートのチャート領域は、要求した日付から表示されます。

28.3.1.3 表領域での列の可視性の制御方法

表領域には、データバインドされたガント・チャートの作成時に定義した列がすべて、デフォルトで表示されます。これらの列の1つ以上を選択して非表示にできます。

ガント・チャートの表領域の列の表示を制御する手順:

1. 「表示」メニューから、「リスト・ペイン」を選択します。

2. ポップアップ・メニューから、「列」を選択します。

3. 「列」メニューから、ガント・チャートの表領域に表示しない列の選択を解除します。表領域に表示する列の選択もできます。

注意:

表領域には、最低1つの列を表示する必要があります。

28.3.2 階層リストまたはフラット・リストでのデータの表示方法

ガント・チャートで階層式のデータ・モデルを使用している場合、ガント・チャート・データを折りたたんだ形式または展開した形式で表示できます。

ガント・チャート・データのリストでの表示を制御する手順:

1. 「表示」メニューから、「リスト・ペイン」を選択します。

2. 次のメニューから、「リストとして表示」(展開されたリストの場合)または「階層として表示」(折りたたんだリストの場合)のいずれかを選択します。

28.3.3 ガント・チャートのタイム・スケールの変更方法

ガント・チャートに表示されるタイム・スケールを変更して、チャート領域を異なる時間単位で表示する時間軸をズーム・インおよびズーム・アウトすることができます。チャートをスクロールせずに、チャート領域に表示する時間を選択する特殊なズームフィット機能も使用できます。

時間軸の設定を変更する手順:

1. 「表示」メニューから、「タイム・スケール」を選択します。

2. 続く「タイム・スケール」ダイアログの「時間単位」列で、主軸、副軸、または両方に新しい単位の値を選択します。サンプル・ボックスには、選択する時間単位のサンプル設定が表示されます。図28-7に、「タイム・スケール」ダイアログを示します。

図28-7 「タイム・スケール」ダイアログ

3. 「OK」をクリックします。

時間軸を拡大または縮小する手順:

1. (オプション)より低いレベルの時間単位で時間軸を表示するには、ツールバーで「拡大」アイコンを選択します。

2. (オプション)より高いレベルの時間単位で時間軸を表示するには、ツールバーで「縮小」アイコンを選択します。

3. (オプション)ツールバーのズーム・アイコンの次のボックスで、スクロールなしでチャートに表示する時間を表す期間を選択します。

4. (オプション)スケールを変更する時間軸を右クリックし、サブメニューから使用可能な時間単位を選択します。

28.4 ガント・チャートのデータ要件の理解

ガント・チャートのデータ・モデルは、ツリー(階層)モデル、あるいは行セットまたはオブジェクトのフラット・リストを含むコレクション・モデルのいずれかです。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされたADFガント・チャートの作成に関する項を参照してください。

ガント・チャートをデータ・コントロールにバインドする場合、データ・コントロールのコレクションをガント・チャートのノード定義へマップする方法を指定します。

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

プロジェクト・ガント・チャートのデータ・モデルは、階層式のデータをサポートし、TreeModelを使用して基礎となるリストのデータにアクセスします。使用される特定のモデル・クラスはorg.apache.myfaces.trinidad.model.TreeModelです。

TreeModelによって返されるオブジェクトのコレクションには、最低限、次のプロパティが必要です。

- taskId: タスクのID

- startTime: タスクの開始時期

- endTime: タスクの終了時期

(オプション)オブジェクトにoracle.adf.view.faces.bi.model.Taskインタフェースを実装して、ガント・チャートに正しいプロパティが提供されていることを確認できます。

ADFデータ・コントロールにデータをバインドする場合、プロジェクト・ガント・チャートでは、次のノード定義を使用できます。

- タスク・ノード:タスクのコレクションを表します。タスク・ノード定義には、次のタイプのオプション・アクセッサがあります。

- subTask(プロジェクト・ガント・チャートにのみ使用可能)

- splitTask

- 分割タスク・ノード:分割タスクのコレクションを表します。分割タスク・ノード定義にはアクセッサはありません。

- 依存性ノード:タスクの依存性のコレクションを表します。依存性ノード定義には、アクセッサはありません。

- 再帰タスク・ノード:再帰タスクのコレクションを表します。再帰タスク・ノード定義には、アクセッサはありません。

表28-2に、プロジェクト・ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表28-2 プロジェクト・ガント・チャートのデータ・オブジェクト・キー

データ・オブジェクト・キー

データ型と説明

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です。

endTime(必須)

Date。すべてのタスクの終了時期。

icon1

String。すべてのタスクのタスク・バーに関連付けられる最初のアイコン。アイコンは、他の属性に応じて異なります。

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。すべてのタスクに関するタスクのタイプ。

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

リソース使用率ガント・チャートのデータ・モデルは、階層式のデータをサポートし、TreeModelを使用して基礎となるリストのデータにアクセスします。使用される特定のモデル・クラスはorg.apache.myfaces.trinidad.model.TreeModelです。

TreeModelによって返されるオブジェクトのコレクションには、最低限、次のプロパティが必要です。

- resourceId: タスクのID。

- timeBuckets: このリソースの時間バケット・オブジェクトのコレクション。

(オプション)オブジェクトにoracle.adf.view.faces.bi.model.Resourceインタフェースを実装して、ガント・チャートに正しいプロパティが提供されていることを確認できます。

timeBucketsプロパティによって返されるオブジェクトのコレクションには、次のプロパティも必要です。

- time: 時間バケットによって表される日付。

- values: このリソースのメトリックのリスト。

ADFデータ・コントロールにデータをバインドする場合、リソース使用率ガント・チャートでは、次のノード定義を使用できます。

- リソース・ノード:リソースのコレクションを表します。リソース・ノード定義には、現在のリソースのサブリソースのコレクションを返すsubResourcesオプション・アクセッサがあります。

- 時間バケット・ノード:メトリックが定義された時間スロットのコレクションを表します。

表28-3に、リソース使用率ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表28-3 リソース使用率ガント・チャートのデータ・オブジェクト・キー

データ・オブジェクト・キー

データ型と説明

label

String。タスク・バーに関連付けられるラベル。

labelAlign

String。タスク・バーのラベルの位置。有効な値は、top(デフォルト)およびinsideです。

resourceId(必須)

String。リソースの一意の識別子。

timeBuckets(必須)

List。リソースに関連付けられるタスクのリスト。

time(必須)

Date。時間バケットの開始時期。

values(必須)

Double。メトリックの値。

28.4.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アクセッサを含めることができます。

表28-4に、スケジュール・ガント・チャートのデータ・オブジェクト・キーの完全なリストを示します。

表28-4 スケジュール・ガント・チャートのデータ・オブジェクト・キー

データ・オブジェクト・キー

データ型と説明

依存性(ノード)

タスクの依存性のリスト。依存性のデータ・オブジェクト・キーには次のものが含まれる。

- 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。すべてのタスクのタスク・バーに関連付けられる最初のアイコン。アイコンは、他の属性に応じて異なります。

icon2

String。すべてのタスクのタスク・バーに関連付けられる2番目のアイコン。

icon3

String。すべてのタスクのタスク・バーに関連付けられる3番目のアイコン。

iconPlacement

String。すべてのタスクのタスク・バーのアイコンの位置。有効な値は、left(デフォルト)、right、inside、inside_left、inside_right、inside_centerです。

isContainer

Boolean値。ノード定義がコンテナかどうかを指定します。

label

String。すべてのタスクのタスク・バーに関連付けられるラベル。

labelPlacement

String。すべてのタスクのタスク・バーのラベルの位置。有効な値は、left(デフォルト)、right、inside、inside_left、inside_right、inside_centerです。

再帰タスク(ノード)

すべてのタスクに関する再帰タスクのリスト。

resourceId(必須)

String。リソースの一意の識別子。

分割タスク(ノード)

すべてのタスクに関する連続的な時系列のないタスクのコレクション。

startTime(必須)

Date。すべてのタスクの開始時期。

startupTime

Date。タスクの開始前の起動時期。

タスク(ノード)(必須)

リソースに関連付けられるタスクのリスト。

taskId(必須)

String。すべてのタスクに関するタスクの一意の識別子。

taskType

String。すべてのタスクに関するタスクのタイプ。

workingDaysOfTheWeek

Object。その週の営業日のリスト。

workingEndTime

Date。リソースの作業終了時間。

workingStartTime

Date。リソースの作業開始時間。

28.5 ADFガント・チャートの作成

ADF Faceガント・チャート・コンポーネントの作成には次のデータソースを使用できます。

- ADFデータ・コントロール: ADFデータ・コントロール・パネルからデータ・コレクションをドラッグ・アンド・ドロップして、データ・バインドされたガント・チャートを宣言的に作成します。『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされたADFガント・チャートの作成に関する項での説明のとおり、行セット・データを持つデータ・コレクションを使用するガント・チャートを作成できます。

- データ・モデル: ガント・タグのvalue属性を使用してバッキングBeanメソッドを参照するEL式を提供することによってプログラムでガント・チャートのデータ・モデルを指定します。

28.6 ガント・チャートの凡例、ツールバーおよびポップアップ・メニューのカスタマイズ

ガント・チャートの下に表示される情報パネルおよび凡例、メニュー・バー・オプションおよびツールバー・ボタン、およびガント・チャート表領域およびチャート領域を右クリックすると表示されるポップアップ・メニューなど、デフォルトのガント・チャート機能を変更することができます。

28.6.1 ガント・チャートの凡例のカスタマイズ方法

オプションのガント・チャートの凡例サブコンポーネントには、選択されたタスクまたは選択された時間バケットに関するメトリックに関する詳細情報が表示される領域、およびガント・チャートの各タスク・タイプを表すために使用される記号および色コード・バーが含まれています。実行時に、ツールバー・ボタンを使用して情報パネルを表示または非表示にできます。

凡例エリアを提供するには、ガント・チャート・タグの子としてdvt:ganttLegendタグを追加する必要があります。凡例エリアのコンテンツは、taskbarFormatManagerで登録された各タスク・タイプのプロパティに基づいて自動的に生成されます。

ガント・チャートの凡例タグでkeys属性およびlabels属性を使用してタスクまたは時間バケットが選択された場合に表示される情報をカスタマイズできます。keys属性では、表示する値の取得に使用されるデータ・オブジェクト・キーを指定し、labels属性には、キーで取得した値に対応するラベルが含まれる必要があります。これらの属性が指定されていないと、凡例で情報パネルの領域全体が使用されます。

ガント・チャートの凡例タグでiconKeys属性およびiconLabels属性を使用して、凡例にアイコンを追加することもできます。アイコンのサイズが大きすぎる場合は、自動的に縦横12ピクセルにサイズ変更されます。

例28-2に、プロジェクト・ガント・チャートの凡例に保留中タスクに関する情報を表示するサンプル・コードを示します。

例28-2 ガント・チャートの凡例の追加

<dvt:projectGantt var="task">
<dvt:ganttLegend id="gl" keys="TaskName StartTime EndTime" labels="Name Start Finish" icons="images/wait.png" iconLabels="OnHold"/>
</dvt:projectGantt>

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

ガント・チャート・ツールバー・サブコンポーネントを使用すると、ガント・チャートの操作を実行できます。ツールバーの左側の部分には、各ガント・チャート・タイプに対するデフォルトのメニュー・オプション・セットを含むメニュー・バーがあります。ツールバーの右側の部分には、各ガント・チャート・タイプを操作するためのデフォルトのアクション・ボタンのセットが表示されます。

ガント・チャートのmenuファセットおよびtoolbarファセットを使用することによって、独自のメニュー項目およびツールバー・ボタンを使用できます。ガント・チャートでは、新しいメニュー項目と標準の項目がマージされます。例28-3に、新しいメニュー項目を指定するサンプル・コードを示します。

例28-3 カスタム・メニュー項目のサンプル・コード

<dvt:projectGantt var="task">
<f:facet name=”menus”>
<af:menu text=”My Menu”>
<af:commandMenuItem text="Add..." />
<af:commandMenuItem text="Create.." />
</af:menu>
</f:facet>
</dvt:projectGantt>

例28-4に、新しいツールバー・ボタンを指定するサンプル・コードを示します。

例28-4 カスタム・ツールバー・ボタンのサンプル・コード

<dvt:schedulingGantt var="task">
<f:facet name="toolbar">
<af:toolbar>
<af:commandToolbarButton text="Custom" disabled="true"/>
</af:toolbar>
</dvt:schedulingGantt>

メニュー・バーおよびツールバー・ボタンで開始されるアクションは、登録されたリスナー、DataChangeListenerを使用してガント・チャート・コンポーネント上で処理されます。たとえば、ユーザーがツールバーで削除ボタンを押すと、削除に選択されたタスクのIDを持つDataChangeEventがサーバー上で開始されます。登録されたリスナーがタスクの実際の削除を行い、ガント・チャート・データ・モデルは更新された情報を使用して更新されます。

ガント・チャート・タグでdataChangeListener属性を使用してメソッド・バインディングを指定することによってDataChangeListenerを登録できます。たとえば、バッキングBeanのhandleDataChangeという名前のメソッドにコードを入れる場合、dataChangeListener属性の設定は、"#{myBackingBean.handleDataChange}"になります。

例28-5に、バッキングBeanのサンプル・コードを示します。

例28-5 データ変更を処理するためのバッキングBean

public void handleDataChanged(DataChangeEvent evt)
{
if (DataChangeEvent.DELETE == evt.getActionType())
…………
}

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

ユーザーがガント・チャートの表領域またはチャート領域を右クリックすると、ガント・チャートを操作するポップアップ・メニューが表示されます。各領域に標準のオプションのセットが提供されます。

ガント・チャートのtablePopupMenuファセットおよびchartPopupMenuファセットを使用することによって、独自のメニュー項目を使用できます。ガント・チャートでは、新しいメニュー項目と標準の項目がマージされます。例28-6に、表領域のポップアップ・メニューにカスタム・メニュー項目を指定するサンプル・コードを示します。

例28-6 カスタム・ポップアップ・メニュー項目のサンプル・コード

<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>

実行時にポップアップ・メニューを動的に変更することもできます。例28-7に、プロジェクト・ガント・チャートのチャート領域で選択したタスクに基づいてタスク・バーでカスタム・ポップアップ・メニューを更新するサンプル・コードを示します。

例28-7 動的ポップアップ・メニュー項目のサンプル・コード

<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で指定されます。例28-8に、バッキングBeanのサンプル・コードを示します。

例28-8 タスクの選択内容を処理するためのバッキング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コンポーネントの使用方法の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

28.7 ガント・チャートのタスクとリソースの使用

ガント・チャートのタスクをカスタマイズして新しいタスク・タイプを作成したり、カスタム・データ・フィルタを指定したり、タスク・バーにダブルクリック・イベントを追加したりできます。

28.7.1 新しいタスク・タイプの作成方法

タスク・タイプは、視覚的にはガント・チャートのチャート領域の棒として表されます。新しいタスク・タイプは、次の3つのいずれかの方法で作成できます。

- .jspxファイルまたは別のCSSファイルでのタスク・タイプ・スタイル・プロパティの定義。

- TaskbarFormatオブジェクトの定義およびtaskbarFormatManagerによるオブジェクトの登録。

- 関連付けられたTaskbarFormatオブジェクトの取得およびsetメソッドを使用したそのプロパティの更新による、事前定義されたタスク・タイプのプロパティの変更。

TaskBarFormatオブジェクトでは次のプロパティが公開されます。

- 塗りつぶしの色

- 塗りつぶしのイメージ・パターン

- 枠の色

- マイルストン・タスクに使用されるイメージ

- サマリー・タスクの開始と終了に使用されるイメージ

分割タスクまたは再帰タスクなど、複数の棒のあるタスクでは、プロパティは個々の棒に定義されます。

例28-9に、.jspxファイルでカスタム・タスク・タイプのプロパティを定義するサンプル・コードを示します。

例28-9 カスタム・タスク・タイプのプロパティを定義するサンプル・コード

<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>

ここでは、TaskbarFormatオブジェクトの塗りつぶしの色と枠の色を定義し、taskbarFormatManagerでオブジェクトを登録するサンプル・コードが示されています。

例28-10 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);

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

ツールバーからデータ・フィルタ・ドロップダウン・リストを使用してガント・チャートのデータ表示を変更できます。ガント・チャートではFilterManagerを使用して、すべての事前定義済およびユーザー指定のデータ・フィルタを管理できます。フィルタ・オブジェクトには次の情報が含まれます。

- フィルタの一意のID

- ドロップダウン・リストにフィルタを表示するためのラベル

- フィルタが選択されたときに起動するオプションのJavaScriptメソッド

フィルタ・オブジェクトを作成し、FilterManagerでaddFilterメソッドを使用してオブジェクトを登録して独自のフィルタを定義できます。例28-11に、FilterManagerを使用してResourceフィルタ・オブジェクトを登録するサンプル・コードを示します。

例28-11 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属性が使用されます。アプリケーションによって実装されると、データ・モデルが更新され、ガント・チャート・コンポーネントにフィルタ処理された結果が表示されます。例28-12に、FilterListenerのサンプル・コードを示します。

例28-12 カスタム・フィルタのFilterListener

public void handleFilter(FilterEvent event)
{
String _type = event.getType();
if (FilterEvent.ALL_TASKS.equals(_type))
{
// update the gantt model as appropriate
}
}

カスタム・データ・フィルタを指定する手順:

1. 構造ウィンドウでガント・チャートのノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「動作」カテゴリのFilterListenerフィールドに、定義したFilterListenerを参照するメソッドを入力します。"#{project.handleFilter}"などです。

28.7.3 タスク・バーへのダブルクリック・イベントの追加方法

ガント・チャート・コンポーネントでは、タスク・バーのダブルクリック・イベントがサポートされています。たとえば、ポップアップ・ウィンドウでタスクに関する詳細な情報が表示されるように設定できます。図28-8に、タスク・バーにダブルクリック・イベントを使用するプロジェクト・ガント・チャートを示します。

図28-8 ダブルクリック・イベントを使用したタスク・バー

例28-13に、タスク・バーにダブルクリック・イベントを追加するサンプル・コードを示します。

例28-13 ダブルクリック・イベントのサンプル・コード

<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)

28.8 休日、読取り専用機能および時間軸の指定

休業日を表示したり、ユーザーとの対話機能を無効にしたり、時間軸を指定するようにガント・チャートをカスタマイズしたりできます。

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

ガント・チャートで休日を指定できます。休日は、デフォルトでは影付きのグレーで表示されますが、休日に使用するカスタム・カラーを選択できます。

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

特定の曜日が毎週の休業日である場合、その曜日を休業日のカテゴリとして指定できます。

曜日を休日として指定する手順:

1. 構造ウィンドウでガント・チャートのノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「外観」カテゴリのNonWorkingDaysOfWeekフィールドで、各週の休日として指定する曜日の文字列を入力します。たとえば、土曜日と日曜日を休日として指定するには、"sat sun"と入力します。
または、バッキングBeanにメソッドを作成し、プログラムで休日を指定することもできます。たとえば、バッキングBeanのgetNonWorkingDaysOfWeekという名前のメソッドにコードを入れる場合、nonWorkingDaysOfWeek属性の設定は、"#{myBackingBean.nonWorkingDays}"になります。例28-14に、バッキングBeanのサンプル・コードを示します。

例28-14 休日を指定するためのバッキングBean

public int[] getNonWorkingDaysOfWeek(){  if (locale == Locale.EN_US
return new int[] {Calendar.SATURDAY, Calendar.SUNDAY};  else    .......}

3. オプションで、NonWorkingDaysColorフィールドにカスタム・カラーを指定します。この属性に指定する値は、16進の色の文字列です。

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

個々の曜日では不十分な場合、ガント・チャートで特定の日付を休日として入力できます。

特定の日付を休日として指定する手順:

1. 構造ウィンドウでガント・チャートを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「外観」属性カテゴリを選択します。

3. nonWorkingDaysフィールドに、休日として指定する日付の文字列を入力します。たとえば、"2008-07-04 2008-11-28 2008-12-25"です。
または、バッキングBeanにメソッドを作成し、プログラムで休日を指定して、柔軟性を高めることもできます。たとえば、バッキングBeanのgetNonWorkingDaysという名前のメソッドにコードを入れる場合、nonWorkingDays属性の設定は、"#{myBackingBean.nonWorkingDays}"になります。

4. オプションで、nonWorkingDaysColorフィールドにカスタム・カラーを指定します。この属性に指定する値は、16進の色の文字列です。

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

ガント・チャートとユーザーとの対話は、featuresOffプロパティで読取り専用の値を指定するように設定することでカスタマイズして無効にすることができます。表28-5に、ガント・チャート・タイプの有効な値と無効にされた機能を示します。

表28-5 読取り専用属性の有効な値

値

無効にされる機能

clipboard

すべてのガント・チャートでの切取り、コピーおよび貼付け。

edit

すべてのガント・チャートのデータ・モデルへの変更。

indenting

プロジェクト・ガント・チャートおよびスケジュール・ガント・チャートでのインデントおよびアウトデント・タスク。

legend

すべてのガント・チャートでの凡例およびタスク情報の表示および非表示。

linking

スケジュール・ガント・チャートへのリンク付けおよびリンク解除タスク。

print

すべてのガント・チャートの印刷タスク。

properties

すべてのガント・チャートのプロパティ・ダイアログを表示します。

split

プロジェクト・ガントの分割タスク。

undo

すべてのガント・チャートの元に戻すおよびやり直しタスク。

view

すべてのガント・チャートでのリストとして表示、階層として表示、列、展開および縮小タスク。

zoom

すべてのガント・チャートのズーム・レベルへの変更。

ガント・チャート機能に読取り専用の値を設定する手順:

1. 構造ウィンドウでガント・チャートのノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタの「動作」属性カテゴリで、featuresOff属性に無効にするガント・チャート機能を指定する1つ以上のString値を入力します。
たとえば、データ・モデル編集、印刷またはガント・チャートのズーム・レベル変更のためのユーザーとの対話を無効にするには、featuresOff属性をedit print zoomのように設定します。

または、バッキングBeanにメソッドを作成し、プログラムで機能を無効にすることもできます。たとえば、バッキングBeanのwhatToTurnOffという名前のメソッドにコードを入れる場合、featuresOff属性の設定は、"#{BackingBean.whatToTurnOff}"になります。

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

各ガント・チャートは、主時間軸と副時間軸を使用して作成されます。各時間軸には、時間のレベルを主または副で示すファセットがあります。すべてのガント・チャートのデフォルトの時間軸設定は次のとおりです。

- 主時間軸: 週

- 副時間軸: 日

時間軸の設定をカスタマイズできます。ただし、主軸は副軸より高い時間レベルに設定する必要があります。次に、dvt:timeAxisコンポーネントのscaleの設定値を高いものから順にリストします。

- twoyears

- year

- halfyears

- quarters

- twomonths

- months

- twoweeks

- weeks

- days

- sixhours

- threehours

- hours

- halfhours

- quarterhours

例28-18に、monthsを主時間軸、weeksを副時間軸として使用するガント・チャートの時間軸を設定するサンプル・コードを示します。

例28-15 monthsとweeksに設定したガント・チャートの時間軸

<f:facet name="major">
<dvt:timeAxis scale="months"/>
</f:facet>
<f:facet name="minor">
<dvt:timeAxis scale="weeks"/>
</f:facet>

主軸および副軸に指定した時間単位は、ガント・チャートの初期表示にのみ適用されます。実行時に、ユーザーは時間軸をズーム・インまたはズーム・アウトして別のレベルの時間単位で表示できます。

28.8.3.1 カスタム時間軸の作成方法と使用方法

dvt:timeAxisのscale属性で、ガント・チャートのカスタム時間軸を作成してその軸を指定できます。カスタム時間軸は、実行時に「タイム・スケール」ダイアログに追加されます。

カスタム時間軸を作成して使用する手順:

1. getNextDate(Date currentDate)メソッドを呼び出すCustomTimescale.javaインタフェースをループで実装して時間軸を作成します。例28-16に、インタフェースのサンプル・コードを示します。

例28-16 カスタム日付を作成するインタフェース

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. また、プロパティ・インスペクタで、主時間軸および副時間軸の「スケール」属性を設定し、カスタム・タイム・スケールにズームするようにZoomOrder属性を指定します。例28-17に、threeyearsを副時間軸、fiveyearsを主時間軸として設定するサンプル・コードを示します。

例28-17 カスタム時間軸

<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>

28.9 ガント・チャートの印刷

ADFのガント・チャートには、書式設定されたオブジェクト(FO)を生成するヘルパー・クラス(GanttPrinter)が用意されており、XML Publisherと連動してPDFファイルが生成されます。

28.9.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では、印刷するガント・チャートの期間を指定できます。
例28-18に、ガント・チャートの特定の期間を印刷用に設定するサンプル・コードを示します。startDateとendDateは日付を表す変数で、_printerはGanttPrinterクラスのインスタンスです。

例28-18 ガント・チャートの印刷用に期間オプションを設定するコード

_printer.setStartTime(startDate);
_printer.setEndTime(endDate);

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

ガント・チャートのツールバーには印刷ボタンがあり、印刷アクションが開始されます。ガント・チャートを印刷するには、印刷イベントを処理するActionListenerを作成する必要があります。ActionListenerのコードには、次のプロセスを含める必要があります。

1. サーブレットの出力ストリームへのアクセス。

2. FOの生成。このプロセスには、GanttPrinterのインスタンスの作成と、使用する印刷オプションのコードの記述が含まれます。

3. PDFの生成。

例28-19に、印刷イベントを処理するActionListenerのコードを示します。このリスナーには、GanttPrinterヘルパー・クラスで使用できるすべての印刷オプションの設定が含まれます。

例28-19 ガント・チャートの印刷イベントを処理するサンプル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();
}
}

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

ユーザーがコレクションからアイテム(表から行など)をドラッグし、ツリーなどの別のコレクション・コンポーネントにドロップできるドラッグ・アンド・ドロップ機能を追加できます。プロジェクト・ガント・チャート・コンポーネントおよびスケジュール・ガント・チャート・コンポーネントは、ADFの表またはツリー表コンポーネントのドラッグ・ソースおよびドロップ・ターゲットとして有効にできます。リソース使用率ガント・チャート・コンポーネントは、ドロップ・ターゲットとしてのみ有効にできます。

アプリケーションでは、af:collectionDragSource動作タグまたはaf:collectionDropTarget動作タグをガント・タグの子として追加して、ドラッグ・ソースまたはドロップ・ターゲットとしてガント・チャート・コンポーネントを登録する必要があります。たとえば、af:collectionDragSourceを使用して、プロジェクト・ガント・チャート・タスクが表領域から別の表にドラッグされたときに起動されるドロップ・リスナーを登録し、表領域からタスクの表にドラッグされたタスクのあるプロジェクト・ガント・チャートを表示できます。

図28-9 ドラッグ・ソースとしてのプロジェクト・ガント・チャート

表28-20に、スケジュール・ガント・チャートにドラッグ・アンド・ドロップ機能を追加するサンプル・コードを示します。

例28-20 ドラッグ・アンド・ドロップ機能を追加するサンプル・コード

<dvt:schedulingGantt value="#{test.treeModel}"
.............
<af:schedulingDragSource actions="COPY MOVE" modelName="treeModel"  />
</dvt:projectGantt>

例28-21に、ドロップ・イベントを処理するリスナー・メソッドのサンプル・コードを示します。

例28-21 コレクションの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;
}

コレクションのドラッグ・アンド・ドロップ機能の追加の詳細は、32.4項「コレクションのドラッグ・アンド・ドロップ機能の追加」を参照してください。

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

この章では、ADF階層ビューア・コンポーネントを使用してデータを表示する方法、および階層表示のカスタマイズ・オプションについて説明します。

この章では、次の項目について説明します。

- 29.1項「階層ビューアの概要」

- 29.2項「階層ビューアのデータ要件」

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

- 29.4項「階層ビューアのナビゲート」

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

- 29.6項「パネル・カードの使用」

- 29.7項「階層ビューアの外観のカスタマイズ」

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

ADF階層ビューアのデータ・バインディングの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされた階層ビューアの作成に関する項を参照してください。

29.1 階層ビューアの概要

階層ビューア・コンポーネントは階層データの視覚表示に使用できます。階層データにはデータ内にマスター/ディテール関係が含まれています。たとえば、組織内の従業員間の関係に関する情報が含まれるデータ・コレクションから、組織図をレンダリングする階層ビューア・コンポーネントを作成することもできます。

29.1.1 階層ビューア・コンポーネントの理解

JDeveloperでは、コンポーネント・ギャラリからJSFページにコンポーネントをドラッグ・アンド・ドロップする場合、または『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされた階層ビューアの作成に関する項での説明のとおり、「階層ビューアの作成」ダイアログを使用して階層ビューア・コンポーネントを作成する場合、JSFページに次の要素が生成されます。

- dvt:hierarchyViewer
この要素はdvt:node要素およびdvt:link要素をラップします。

- dvt:node
ノードは階層のデータを参照する形状です(たとえば、組織の従業員またはネットワークのコンピュータ)。表示するデータを参照するdvt:node要素の子要素を構成します。dvt:node要素は、様々なズーム・レベル(100%、75%、50%および25%)でコンテンツを表示する1つ以上のf:facet要素の使用をサポートします。f:facet要素は、ADFデータ視覚化dvt:panelCardコンポーネントに加えてaf:outputText、af:imageおよびaf:panelGroupLayoutなどの多数のADF Facesコンポーネントの使用をサポートします。

実行時に、ノードにはユーザーにノード間のナビゲートを可能にし、デフォルトで他のノードを表示または非表示にできるコントロールが含まれます。ノード・コンテンツの指定とズーム・レベルの定義の詳細は、29.3.1項「ノード・コンテンツの指定方法」を参照してください。

- dvt:link
1つのノードを別のノードに接続するdvt:link要素の属性の値を設定します。リンクの外観のカスタマイズ方法とラベルの追加方法の詳細は、29.7.4項「リンクとラベルの表示の構成方法」を参照してください。

- dvt:panelCard
パネル・カード要素には、アニメーションを使用して(コンテンツを横にスライドしたり、ノードを反転したりするなど)ノード要素ごとに複数のコンテンツ参照セットを動的に切り替えるメソッドがあります。

各ズーム・レベルのf:facetタグは、指定したズーム・レベルで表示するようにコンテンツを定義する1つ以上のaf:showDetailItem要素を含むdvt:panelCard要素の使用をサポートします。実行時に、エンド・ユーザーはaf:showDetailItem要素が参照するコンテンツを動的に切り替えるノードのコントロールを使用します。詳細は、29.6項「パネル・カードの使用」を参照してください。

注意:

他の要素とは異なり、コンポーネント・ギャラリを使用して階層ビュータを作成するときにデフォルトのクイック・レイアウト・オプションを選択した場合、dvt:panelCard要素は生成されません。詳細は、29.1.3項「使用可能な階層ビューアのレイアウト・オプション」を参照してください。

階層ビューア・コンポーネントでは、af:panelGroupLayout、af:spacer、af:separatorなどの要素を使用して、ノードでのコンテンツの表示方法を定義します。例29-1に、コンポーネント・パレットから挿入してコンポーネントを作成する場合に生成されるコードを示します。この例では、階層ビューア要素に関連するコードが強調表示されています。

例29-1 階層ビューアのサンプル・コード

<dvt:hierarchyViewer id="hierarchyViewer1" layout="hier_vert_top"
inlineStyle="width:100%;height:600px;">
<dvt:link linkType="orthogonalRounded" id="l1"/>
<dvt:node width="233" height="330" id="n1">
<f:facet name="zoom100">
<af:panelGroupLayout layout="vertical"
inlineStyle="width:100%;height:100%;padding:5px"
id="pgl2">
<af:panelGroupLayout layout="horizontal" id="pgl3">
<af:panelGroupLayout inlineStyle="width:85px;height:120px"
id="pgl4">
<af:image id="i1"/>
</af:panelGroupLayout>
<af:spacer width="5" height="5" id="s2"/>
<af:panelGroupLayout layout="vertical" id="pgl1">
<af:outputText value=" attribute value1 "
inlineStyle="font-weight:bold;font-size:20px;color:#383A47"
id="ot5"/>
<af:outputText value=" attribute value2"
inlineStyle="font-size:20px;color:#383A47"
id="ot9"/>
<af:outputText value=" attribute value3"
inlineStyle="font-size:11px;font-style:italic;color:#383A47"
id="ot2"/>
</af:panelGroupLayout>
</af:panelGroupLayout>
<af:spacer height="5" id="s1"/>
<af:separator id="s4"/>
<af:spacer height="5" id="s3"/>
<dvt:panelCard effect="slide_horz"
inlineStyle="border-width:1px;border-color:#CCCCCC;
font-size:16px;font-weight:bold;color:#5a6a7a"
id="pc1">
<af:showDetailItem text="first group title "
inlineStyle="font-weight:bold;font-size:16px;color:#5a6a7a"
id="sdi1">
<af:panelFormLayout inlineStyle="width:100%;height:100%;padding:5px"
id="pfl1">
<af:panelLabelAndMessage label="attribute label4"
labelStyle="font-size:14px;color:#5A6A7A" id="plam2">
<af:outputText value="attribute value4"
inlineStyle="font-size:14px;color:#383A47" id="ot3">
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label5"
labelStyle="font-size:14px;color:#5A6A7A" id="plam6">
<af:outputText value="attribute value5"
inlineStyle="font-size:14px;color:#383A47" id="ot8">
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label6"
labelStyle="font-size:14px;color:#5A6A7A" id="plam5">
<af:outputText value="attribute value6"
inlineStyle="font-size:14px;color:#383A47" id="ot6">
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:showDetailItem>
<af:showDetailItem text="second group title "
inlineStyle="font-weight:bold;
font-size:16px;color:#5a6a7a" id=sd12">
<af:panelFormLayout inlineStyle="width:100%;height:100%;padding:5px"
id="pfl2">
<af:panelLabelAndMessage label="attribute label7"
labelStyle="font-size:14px;color:#5A6A7A" id="plam3">
<af:outputText value="attribute value7"
inlineStyle="font-size:14px;color:#383A47" id="ot7"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label8"
labelStyle="font-size:14px;color:#5A6A7A"id="plam4">
<af:outputText value="attribute value8"
inlineStyle="font-size:14px;color:#383A47" id="ot1"/>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="attribute label9"
labelStyle="font-size:14px;color:#5A6A7A" id="plam1">
<af:outputText value="attribute value9"
inlineStyle="font-size:14px;color:#383A47" id="ot4"/>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:showDetailItem>
</dvt:panelCard>
</af:panelGroupLayout>
</f:facet>
</dvt:node>
</dvt:hierarchyViewer>

29.1.2 階層ビューアの要素と用語

階層ビューアは、階層データおよびマスター/ディテール関係を視覚的に表示します。図29-1に、コントロール・パネル、複数のノード、およびノードをつなぐリンクを含む実行時の階層ビューア・コンポーネントのセグメントを示します。

図29-1 コントロール・パネルとノードが表示された階層ビューア・コンポーネント

コントロール・パネルでは、ユーザーが実行時に階層ビューア・コンポーネントの位置と外観を操作できるコントロールが提供されます。デフォルトで、図29-2に示すとおり、階層ビューア・コンポーネントの左上隅に非表示状態で表示されます。

図29-2 非表示状態のコントロール・パネル

コントロール・パネルが別の場所に表示されるように構成することはできません。ユーザーは、図29-2に示すコントロール・パネルを非表示または表示するボタンをクリックして、コントロール・パネルを非表示または表示します。図29-3に、展開されたコントロール・パネルを示します。

図29-3 表示状態のコントロール・パネル

実行時にコントロール・パネルがユーザーに表示されないように階層ビューア・コンポーネントを構成できます。手順の詳細は、29.7.3項「コントロール・パネルの表示の構成方法」を参照してください。

表29-1では、コントロール・パネルのコントロールでユーザーに提供される機能を説明します。パネル・セレクタは、階層ビューア・コンポーネントのノードに、1つ以上のaf:showDetailItem要素を持つdvt:panelCard要素が含まれていると自動的に有効になります。階層ビューア・コンポーネントで次のいずれかのレイアウトが使用されていると、レイアウト・セレクタが自動的に表示されます。

- 垂直方向、上から下

- 水平方向、左から右

- ツリー

- 放射

- 円

階層ビューア・コンポーネントのレイアウトの詳細は、29.1.3項「使用可能な階層ビューアのレイアウト・オプション」を参照してください。

表29-1 コントロール・パネルの要素

コントロール

名前

説明

パン制御

ユーザーはビューポート内の階層ビューア・コンポーネントを再配置できます。

ズームしてあわせる

ユーザーはビューポート内にすべてのノードが表示されるように、階層ビューア・コンポーネントにズームできます。

ズーム制御

ユーザーは、階層ビューア・コンポーネントにズームできます。

非表示/表示

コントロール・パネルを表示または非表示にします。

パネル・セレクタ

定義したノード・パネルのリストが表示されます。ユーザーはパネル・セレクタを使用して、すべてのノードを同じパネルに一度に表示できます。

レイアウト・セレクタ

レイアウトの選択を可能にします。ユーザーは階層ビューア・コンポーネントのレイアウトを、階層ビューア・コンポーネントによって提示されるレイアウト・オプションの1つに定義したレイアウトから変更できます。詳細は、29.1.3項「使用可能な階層ビューアのレイアウト・オプション」を参照してください。

階層ビューアは、ノードの選択、展開、横方向移動に関する状態管理をサポートします。ユーザーがノードを選択または展開したり、同じ親内で左または右に移動して、次のノード・セットを表示する場合、タブ付パネルのように、移動後にページに戻ると、その状態は維持されます。状態管理は、disclosedRowKeys、selectedRowKeys、lateralNavigationRowKeysなどの階層ビューア属性でサポートされます。

階層ビューアは、ノード・コンテンツ、検索パネル、および検索結果の表示で双方向テキストをサポートします。双方向テキストは、両方向のテキスト(右から左(RTL)および左から右(LTR))のテキストを含むテキストです。これは、通常、アラビア語やヘブライ語のスクリプトなどの各種アルファベットが含まれるテキストです。階層ビューアは、あるノード・ビューから次のノード・ビューへのパネル・カードの反転用の双方向サポートも提供します。

29.1.3 使用可能な階層ビューアのレイアウト・オプション

階層ビューアは、コンポーネントのtype属性で指定される次のレイアウトを使用できます。

- hier_vert_top: 上から下への垂直方向

- hier_vert_bottom: 下から上への垂直方向

- hier_horz_left: 左から右への水平方向

- hier_horz_right: 右から左への水平方向

- hier_horz_start: 水平方向。ロケールによって向きが決まります。

- hier_horz_end: 水平方向。ロケールによって向きが決まります。

- tree: ツリー。インデントされたツリー

- radial: 放射状。ルート・ノードが中央に配置され、後続の子レベルがそれぞれの親ノードから外側に向かって放射状に広がります。

- circle: 円。ルート・ノードが中央に配置され、すべてのリーフ・ノードが同心円に配置されるレイアウト。親ノードは円の内側に配置されます。
図29-4に、階層ビューア・コンポーネントの円レイアウトの例を示します。

図29-4 階層ビューアの円レイアウト

ページにコンポーネントを挿入する際(データ・コントロール・パネルからデータ・コレクションと階層ビューア・コンポーネントをバインドするか、コンポーネント・パレットからコンポーネントを挿入して後からデータにバインドする)、階層ビューアの初期レイアウトを定義できます。使用可能なレイアウトは、図29-5に示すように、コンポーネント・ギャラリの「階層ビューア・タイプ」領域に表示されます。

注意:

円レイアウトは、コンポーネント・ギャラリでは使用できません。円レイアウトで階層ビューアを作成するには、プロパティ・インスペクタでdvt:hierarchyViewerタグのtype属性に値circleを指定する必要があります。

図29-5に示す選択のように、コンポーネント・ギャラリの「クイック・スタート・レイアウト」領域では、ノードの複数のコンテンツ・セットをサポートするdvt:panelCard要素の生成を選択することもできます。

図29-5 階層ビューア・コンポーネントのコンポーネント・ギャラリ

29.1.4 階層ビューアのレンダリングとHTMLについて

デフォルトでは、階層ビューア・コンポーネントはFlash Playerでレンダリングします。Flash 10以上がクライアントで使用できない場合や印刷が目的の場合、階層ビューアはHTMLでレンダリングされます。HTMLレンダリングはFlashレンダリングにできるかぎり細かく従いますが、いくつかの相違があります。次の例外を除き、ほとんどの場合、階層ビューアの表示と機能はサポートされます。

- 分離ノードおよびリストア・ノードは使用できません。

- ノードの形状は長方形に制限されます。

- リンクの場合、リンクの終点コネクタはサポートされません。リンク・タイプは直交に制限され、リンク・スタイルは実線に制限されます。

- コントロール・パネルの場合、パネル・カードはすべて切り替えることができません。パンはスクロール・バーに制限され、ズームおよびズーム・フィットは4つのズーム・ファセットに制限されます。

- 検索はサポートされません。

- メール可能なページはサポートされません。

- ノードの詳細を示すホバー・ウィンドウはサポートされません。

29.2 階層ビューアのデータ要件

階層ビューア・コンポーネントには、1つ以上のディテール・コレクションと1つのマスター・ディテール・コレクションとの間にマスター/ディテール関係が存在するデータ・コレクションが必要です。階層ビューア・コンポーネントでは、ADF Faces treeコンポーネントと同じデータ・モデルが使用されます。データ・コレクションをまずADF Faces treeコンポーネントにバインドすることによって、データ・コレクションを階層ビューア・コンポーネントにバインドできるかどうかテストできます。ADF Faces treeコンポーネントを使用してデータ・コレクションをナビゲートできれば、階層ビューア・コンポーネントにバインドすることができます。

JSFページに階層ビューア・コンポーネントを追加すると、JDeveloperによりJSFページのページ定義ファイルにツリー・バインディングが追加されます。ツリー・バインディングでノードにデータを移入する方法の詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のマスター/ディテール・オブジェクトの表示にツリーを使用する方法に関する項を参照してください。

ユーザーが階層ビューア・コンポーネントのルート・ノードから下方向にナビゲートできるようにするには、階層ビューア・コンポーネントでノードにバインドするデータ・コレクションに再帰的アクセッサが含まれている必要があります。階層ビューア・コンポーネントのナビゲートの詳細は、29.4項「階層ビューアのナビゲート」を参照してください。

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

ノードは、実行時に階層ビューア・コンポーネントの個々の要素を示す形状です。階層ビューア・コンポーネントの個々の要素の例には、組織図の従業員またはネットワーク・ダイアグラムのコンピュータが含まれます。デフォルトで、階層ビューア・コンポーネントの各ノードには、ユーザーが次のことを実行できるコントロールが含まれています。

- 階層ビューア・コンポーネントの他のノードへのナビゲート
各ノードの上部には、親ノードを表示するか、階層ビューアのアンカー・ノードとして選択するリストア・ボタンまたは分離ボタンが1つあります。例外は階層ビューア・コンポーネントの最上部のノードで、理由はこのノードには親ノードがなく分離できないからです。

- 階層ビューア・コンポーネントで現在選択されているノードの子ノードの表示または非表示
リーフ・ノードではないすべてのノードの下部には、「表示」または「非表示」ボタンが表示されます。ユーザーがこれらのアイコンのいずれかをクリックすると、コンポーネントによりRowDisclosureEventイベントが生成されます。このイベントに対応する処理を実行するには、 af:treeコンポーネントと同じ方法でカスタムのrowDisclosureListenerメソッドを登録します。詳細は、10.5.4項「プログラムを使用したノードの開閉について」を参照してください。

パネル・カードを使用して、階層ビューア・コンポーネントが参照するノードの様々な情報セットを表示する場合、ノードの下部にあるコントロールにより、アクティブ・ノードの情報セットを変更できます。詳細は、29.6項「パネル・カードの使用」を参照してください。

図29-6に、エンド・ユーザーがアンカー・ノードとしてノードを分離し、子ノードを表示して、アクティブ・ノードの様々な情報セットを表示するようにノードを変更できるコントロールを含むノード例を示します。ノードのコントロールの構成方法の詳細は、29.3.2項「ノードのコントロールの構成方法」を参照してください。

図29-6 ノード・コントロール

基本的なノード・タイプは4つあります。

- ルート・ノードは、階層ビューア・コンポーネントで表示可能な最上ノードです。ルート・ノードは、常にツリー・コンポーネントから返される階層のルートになります。通常、一度に表示されるルート・ノードは1つのみです。ただし、実装するユース・ケースによって、複数のルート・ノードが表示される場合もあります(ファミリ・ツリーの場合など)。

- アンカー・ノードは、階層ビューア・コンポーネントがレンダリングされると必ずフォーカスされるノードです。表示されるアンカー・ノードは常に1つのみです。
ツリー・ノードに子ノードが定義されていて、階層ビューア・コンポーネントのdisplayLevelsAncestorプロパティが0に等しい場合は、アンカー・ノードはルート・ノードと同じになります。実行時に、ユーザーがsetAnchorListenerプロパティに指定された値を持つ別のノードをダブルクリックすると、そのノードがアンカー・ノードになります。子ノードがあるかどうかによって、アンカー・ノードも内部ノードまたはリーフ・ノードにすることができます。アンカー・ノードの指定方法の詳細は、29.3.4項「ノード定義と特定のデータ行セットを関連付ける方法」を参照してください。

アンカー・ノードより上に、1つ以上の祖先レベルを指定できます。詳細は、29.3.5項「アンカー・ノードの祖先レベルの指定方法」を参照してください。

- 内部ノードは、子ノードを持つノードです。

- リーフ・ノードは、子ノードを持たないノードです。

図29-7に、階層ビューア・コンポーネントのレイアウトによって、ノードを別のタイプにする方法を示します。

図29-7 ノード・タイプおよび位置

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

ノードには、ノードにナビゲートして、ノードを表示または非表示にできるコントロールがデフォルトで含まれますが、階層ビューア・コンポーネントを作成するときに、クイック・スタート・レイアウトを使用した場合を除き、ノードにコンテンツはデフォルトで含まれません。実行時にノードによってレンダリングされるコンテンツを定義する必要があります。『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされた階層ビューアの作成に関する項での説明のとおり、データ・バインディングと階層ビューア・コンポーネントを関連付けると、ノード・コンテンツを指定できます。

デフォルトで、作成する階層ビューア・コンポーネントにはズーム・レベル100%のファセット要素を1つ持つノードが1つ作成されます。

<f:facet name="zoom100"/>

次のズーム・レベルを使用して、さらに3つのファセット要素のインスタンスを階層ビューア・コンポーネントに挿入できます。

- 25%: zoom25

- 50%: zoom50

- 75%: zoom75

階層ビューアをズーム・アウトして、表示するノードを増やし、各ノードで利用可能な表示領域を減らす場合、これらのズーム・レベル定義を使用すると、ノード・コンテンツの読みやすさが向上します。1つ以上のファセット要素内で使用可能なデータ・コレクションのサブセットを定義できます。たとえば、名前、場所および数など、会社の部署に関するデータを参照するノード属性を持つデータ・コレクションがある場合、部署の名前と数のノード属性を参照する、ズーム・レベル50%のファセット要素を指定できます。

実行時、どのズーム・レベルでノード上にカーソルを置いても、ズーム・レベル100%でノード・コンテンツを表示するホバー・ウィンドウが自動的に表示されるため、ズーム・レベルに関係なく情報をすべて表示できます。ノードが階層ビューアで選択されている場合、ホバー・ウィンドウ上のコントロールはアクティブです。

挿入する各ファセット要素は、他のコンポーネントの参照に使用できます。次のコンポーネントから1つ以上を使用して、階層ビューア・コンポーネントのノードにコンテンツを定義できます。ノード・コンポーネントのファセットは、次のコンポーネントをサポートします。

- af:commandButton

- af:commandImageLink

- af:commandLink

- af:commandMenuItem

- af:goButton

- af:goLink

- af:image
af:imageコンポーネントの使用方法の詳細は、29.7.2項「階層ビューアにイメージを含める方法」を参照してください。

- af:menu

- af:outputFormatted

- af:outputText

- af:panelFormLayout

- af:panelGroupLayout
panelGroupLayoutコンポーネントの使用方法の詳細は、8.12.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

- af:panelLabelAndMessage

- af:separator

- af:showDetailItem

- af:showPopupBehavior
af:showPopupBehaviorコンポーネントの使用方法の詳細は、29.5.3項「ポップアップ・ウィンドウを起動するための階層ビューアの構成方法」を参照してください。

- af:spacer

- dvt:panelCard
dvt:panelCardコンポーネントの使用方法の詳細は、29.6項「パネル・カードの使用」を参照してください。

注意:

サポートされないコンポーネントは、設計時に反転されます。

階層ビューア・コンポーネントにノードを追加する手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「dvt:hierarchyViewerの中に挿入」→「ノード」を選択します。
次のエントリがJSFページに表示されます。

<dvt:node>
<f:facet name="zoom100"/>
</dvt:node>

2. 構造ウィンドウでdvt:nodeノードを右クリックし、「プロパティに移動」を選択します。

3. プロパティ・インスペクタで、適切なプロパティを構成します。
たとえば、ノード・コンポーネントとアクセッサを関連付けるには、typeプロパティに値を設定します。

<dvt:node type="model.rootEmp model.HvtestView"/>

詳細は、29.3.3項「アクセッサのノード定義の指定方法」を参照してください。

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

ノード・コンポーネント(dvt:node)では、リストア、分離、表示または非表示などのコントロールを実行時に表示するかどうかを決定できる多くのプロパティが公開されます。実行時のノードのサイズと形状を決定するプロパティも公開されます。

ノードにコントロールを構成する手順:

1. 構造ウィンドウでdvt:nodeコンポーネントを右クリックし、「プロパティに移動」を選択します。

2. 表29-2に説明されているとおり、プロパティ・インスペクタの「外観」セクションでdvt:nodeコンポーネントのプロパティを構成します。

表29-2 ノード構成プロパティ

実行する手順

プロパティに設定する値

表示または非表示コントロールをノードに表示するかしないかを構成します。

コントロールを非表示にするには、showExpandChildrenをFalseに設定します。デフォルトでは、このプロパティはTrueに設定されています。

リストアまたは分離コントロールをノードに表示するかしないかを構成します。

ノードでこれらのコントロールを非表示にするには、showNavigateUpプロパティおよびshowIsolateプロパティをFalseに設定します。デフォルトでは、このプロパティはtrueに設定されています。

showNavigateUpプロパティをtrueに設定した場合は、29.4.1項「階層ビューアでの上方向へのナビゲーションの構成方法」での説明のとおり、階層ビューア・コンポーネントのnavigateUpListenerプロパティにも値を設定する必要があります。

ノードの高さと幅を構成します。

widthプロパティおよびheightプロパティの値を設定します。

ノードの形状を選択します。

「図形」ドロップダウン・リストから値を選択します。使用可能な値は次のとおりです。

- ellipse

- rect

- roundedRect(デフォルト)

3. プロパティ・インスペクタの「スタイル」セクションのプロパティの構成の詳細は、20.4項「コンポーネントのスタイル・プロパティの変更」を参照してください。

ホバー・ウィンドウは、ノード上にカーソルを置くと自動的に表示され、そのノードに設定されるshape属性が反映されます。たとえば、ノードのshape属性がroundedRectの場合、図29-8に示すように、ホバー・ウィンドウの属性も同じになります。

図29-8 階層ビューア・ノードのホバー・ウィンドウ

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

デフォルトで、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のデータバインドされた階層ビューアの作成に関する項での説明のとおり、「階層ビューアの作成」ダイアログを使用して、階層ビューア・コンポーネントを作成する場合は、ノード・コンポーネントをアクセッサと関連付けます。「階層ビューアの作成」ダイアログでは、ノード・コンポーネントの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プロパティの値は定義しません。

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

階層ビューア・コンポーネントのアンカー・ノードは、ツリー・バインディングによって返される階層のルートです。ユース・ケースによって、複数のルート・ノードにすることができます(1人以上のマネージャのいる組織図をレンダリングする階層ビューア・コンポーネントなど)。実行時に階層ビューア・コンポーネントをレンダリングすると、フォーカスのあるノードがアンカー・ノードになります。実行時に、ユーザーがsetAnchorListenerプロパティに指定された値を持つ別のノードをダブルクリックすると、そのノードがアンカー・ノードになります。

アンカー・ノードの上のレベル(祖先レベル)を1つ以上表示するように階層ビューアを構成できます。たとえば、企業の従業員を検索する場合、従業員の上の管理チェーンを表示できます。displayLevelsAncestorプロパティを使用して、祖先レベルを指定します。

アンカー・ノードの祖先レベル数を指定する手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、「共通」セクションを開きます。

3. 実行時に、アンカー・ノードの上に表示する祖先ノードのレベル数をdisplayLevelsAncestorプロパティで指定します。
たとえば、アンカー・ノードの祖先レベルの数に2を入力すると、JSFページに次のエントリが表示されます。

displayLevelsAncestor="2"

4. JSFページへの変更を保存します。

29.4 階層ビューアのナビゲート

デフォルトで、階層ビューア・コンポーネントのルート・ノードと内部ノードには下方向へのナビゲーションが構成されています。階層ビューア・コンポーネントで上方向へのナビゲーションを行い、ユーザーが同じレベルのノード間をナビゲートしたときに表示されるノードの数を決定できるように構成することができます。

ノード・タイプの詳細は、29.3項「階層ビューアでのノードの管理」を参照してください。

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

階層ビューア・コンポーネントの上方向ナビゲーションを構成する場合、階層ビューア・コンポーネントのnavigateUpListenerプロパティの値を構成します。

階層ビューア・コンポーネントの上方向へのナビゲーションを構成する手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで「動作」セクションを開きます。ユーザーが新しいアンカー・ノードにナビゲートしたときに、新しいアンカー・ノードを参照するようにデータ・モデルを更新するメソッドを指定する階層ビューア・コンポーネントのnavigateUpListenerの値を記述します。

3. 「OK」をクリックします。

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

階層ビューア・コンポーネントのノード間の同レベル・ナビゲーションはデフォルトで有効にされています。階層ビューア・コンポーネントを構成して、一度に表示するノードの数を決定できます。これを行うと、ユーザーに次のナビゲートを可能にするコントロールが表示されます。

- 左または右にナビゲートして、次のノードのセットを表示

- 使用可能なノードのコレクションで最初または最後のノードのセットにナビゲート

階層ビューア・コンポーネントの同レベル・ナビゲーションを構成する手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで「共通」セクションを開き、実行時に表示するノードの数をレベルごとのノード数フィールド(levelFetchSize)で指定します。
たとえば、ノードの数に3を入力すると、JSFページに次のエントリが表示されます。

levelFetchSize="3"

3. 「OK」をクリックします。

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

実行時に、階層ビューア・コンポーネントのlevelFetchSizeプロパティの値として指定したノードの数が、階層ビューア・コンポーネントによってレンダリングされます。階層ビューア・コンポーネントは、ユーザーが次のことを実行できるコントロールもレンダリングします。

- 左または右にナビゲートして、次のノードのセットを表示

- 使用可能なノードのコレクションで最初または最後のノードのセットにナビゲート

図29-9に、levelFetchSize="3"の場合の実行時の例を示します。図29-9の丸で囲まれている領域に示すように、ユーザーがコントロール上にマウスを移動させると、ユーザーにノードの最後のセットへのナビゲートを可能にするコントロールが表示されます。

図29-9 同レベル・ナビゲーションを使用した階層ビューア・コンポーネント

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

階層ビューア・コンポーネントを構成して、ポップアップ・ウィンドウを起動し、機能およびOracle Fusion Webアプリケーションの他のページからのデータが示されたメニューを表示します。

29.5.1 3Dティルト・パンの構成方法

デフォルトでは、階層ビューアのパンは、コンポーネントをクリックおよびドラッグしてビューを再配置するか、コントロール・パネルのパン制御を使用することで行われます。ノードの数が多い階層ビューアでは、階層ビューアで一度に1ページを参照するのではなく、階層ビューアにアニメーションを使用して階層ビューア・ノードから視覚的に進む3Dティルト・パン効果を開始できます。その効果は、ビューのエッジ方向に開始すると、エッジのノードの終端に達するまで自動的に持続します。図29-10に、ビューのエッジに達したティルト・パン効果を示します。

図29-10 階層ビューアの3Dティルト・パン効果

ティルト・パン効果を使用するには、まずノードのコンテンツの受入れ可能なビューについて、階層ビューでズーム・レベルを調整する必要があります。次の方法で効果を開始できます。

- 定期的なパンを短時間行った後、コントロール・パネルのパン制御でクリックおよびドラッグして、ティルト・パンを開始します。

- ビュー・ポート全域のビューの1/3の距離をクリックおよびドラッグします。

- ビューのエッジ近くでカーソルをクリックしたまま、その方向でティルト・パンを開始します。

ティルト・パン効果が開始すると、ビュー内でカーソルを移動して、ビューからパンの方向を変更できます。ビューのノードを選択してティルト・パンを終了します。

階層ビューアの3Dティルト・パン効果を構成するには、panningプロパティをtiltに設定します。

29.5.2 ノード選択アクションの構成方法

デフォルトでは、実行時に階層ビューアのノードをクリックすると、そのノードが選択されます。この相互作用をカスタマイズするには、dvt:nodeコンポーネントのclickBehavior属性を設定します。このプロパティの有効な値は次のとおりです。

- focus: ノードはフォーカスを受け入れ、クリックすると選択されます(デフォルト)。

- expandCollapse: 子ノードの要素の展開または折りたたみが、その現在の展開状態に応じて行われます。

- isolateRestore: ノードは、その現在の状態に応じて分離またはリストアされます。

- none: ノードをクリックしても何も行われません。

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

階層ビューア・ノードからポップアップ・ウィンドウを起動するには、af:showPopupBehaviorタグの値を指定して、コマンド・コンポーネント(af:commandButtonなど)からポップアップ･ウィンドウを起動します。階層ビューア・コンポーネントのノードのf:facet要素内で、ポップアップを起動するコマンド・コンポーネントをネストする必要があります。このシナリオで使用されるaf:showPopupBehaviorタグのtriggerTypeプロパティでは、次の値のみがをサポートされます。

- action

- mouseHover

たとえば、図29-11に、ノードのHR Detailリンクから起動するモーダル・ポップアップを示します。例29-2に、ポップアップを作成するサンプル・コードを示します。例29-3に、コマンド・コンポーネントからポップアップを起動するサンプル・コードを示します。簡潔にするために<af:panelGroupLayout>、<af:spacer>および<af:separator>などの要素は、サンプル・コードには含まれません。

図29-11 階層ビューア・ノードのモーダル・ポップアップ

例29-2 ポップアップを作成するサンプル・コード

<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-3 コマンド・コンポーネントからポップアップを起動するサンプル・コード

<f:facet name="zoom100">
...
<dvt:panelCard effect="slide_horz"
...
<af:showDetailItem text="Contact "
...
<af:commandLink text="Show HR Detail" inlineStyle="font-size:14px;color:#383A47" >
<af:showPopupBehavior popupId="::popupDialog" triggerType="action"
align="endAfter" alignId="pg1" />
</af:commandLink>
</showDetailItem>
</dvt:panelCard>
</f:facet>

af:showPopupBehaviorタグの使用の詳細は、13.4項「ポップアップ要素の起動」を参照してください。

29.5.4 メニューを起動するための階層ビューア・ノードの構成方法

階層ビューア内でノード・コンポーネント(dvt:node)を構成し、af:menuコンポーネントを使用することによってメニューを起動させることができます。af:menuコンポーネントには1つ以上のaf:commandMenuItem要素を構成できます。階層ビューア・コンポーネント内のノードでは、af:menuコンポーネントのネストはサポートされていません。図29-12に、ノードと関連付けられるコンテキスト・メニューを示します。

図29-12 階層ビューア・ノードのコンテキスト・メニュー

例29-4に、コンテキスト・メニューを作成するサンプル・コードを示します。

例29-4 コンテキスト・メニューのサンプル・コード

<af:popup id="popupDialog" contentDelivery="lazyUncached" >
<af:menu>
<af:commandMenuItem text="Send an IM"/>
<af:commandMenuItem text="Look at details"/>

</af:menu>
</af:popup>

af:menuコンポーネントの使用方法の詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用」を参照してください。

29.6 パネル・カードの使用

パネル・カード・コンポーネントを階層ビューア・コンポーネントとともに使用して、階層ビューア・コンポーネントが参照するノードに異なった情報のセットを保持できます。パネル・カード・コンポーネントは、ノード要素の内側の領域で、1つ以上のaf:showDetailItem要素を含めることができます。

各af:showDetailItem要素がコンテンツの1セットを参照します。たとえば、組織図をレンダリングする階層ビューア・コンポーネントに組織内の従業員のノードを含めることができます。このノードには、1つのaf:showDetailItem要素、および給与情報を参照するもう1つのaf:showDetailItem要素を使用して連絡先情報を参照するパネル・カード・コンポーネントを含めることができます。

パネル・カード・コンポーネントには、実行時に1つのaf:showDetailItem要素によって参照されるコンテンツが表示されます。パネル・カード・コンポーネントによって、ナビゲーション・ボタン、およびユーザーがaf:showDetailItem要素によって参照されるデータのセット間の切替えを行えるようにする他のコントロールがレンダリングされます。ユーザーがデータの異なったセット間で切替えを行えるようにするコントロールは、オプションの遷移効果を使用して構成できます。たとえば、パネル・カードがaf:showDetailItem要素によって参照されるデータのセットと、別のaf:showDetailItem要素によって参照される別のデータのセットとの間を水平にスライドするように構成できます。

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

パネル・カード・コンポーネントは、JSFページの構造ウィンドウでFacet zoom要素を選択した場合に表示されるポップアップ・メニューを使用して、階層ビューア・コンポーネントをレンダリングするJSFページに挿入できます。

パネル・カードを作成する手順:

1. 構造ウィンドウで、パネル・カードを作成するノード内のズーム・レベルを右クリックします。
f:facet - zoom100などを選択します。

2. 「f:facet -zoom100の中に挿入」→「パネル・カード」を選択します。

3. プロパティ・インスペクタを使用して、パネル・カード・コンポーネントのプロパティを構成します。
たとえば、パネル・カード・コンポーネントの「拡張」プロパティで、「効果」プロパティに値を設定します。有効な値は次のとおりです。

- Horizontal Slide(デフォルト)

- Panel Flip

- Node Flip

- No Animation

4. 構造ウィンドウでdvt:panelCardを右クリックし、「dvt:panelCardの中に挿入」→「詳細アイテムの表示」を選択します。

5. 必要に応じて、手順4を繰り返します。

6. プロパティ・インスペクタを使用して、挿入するaf:showDetailItem要素のプロパティを構成します。

29.6.2 実行時にパネル・カード・コンポーネントをレンダリングする場合の処理

実行時に、ノードが表示され、パネル・カード・コンポーネントが1つ表示されます。ユーザーは、パネル・カードの下部にあるナビゲーション・ボタンをクリックして、パネル・カードのaf:showDetailItem子要素のいずれかによって参照されるコンテンツの次のセットにナビゲートできます。

図29-13に、2つの異なる子要素af:showDetailItemが情報の異なるセット(ContactおよびAddress)を参照する場合のパネル・カード・コンポーネントを含むノードを示します。例のコントロールには、パネル・カードをスライドする矢印と、表示するパネル・カードを直接選択するボタンがあります。両方のコントロール・オプションのツールチップの表示。

図29-13 パネル・カードを使用した実行時のノードの表示

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

階層ビューアのコンポーネントのサイズや外観をカスタマイズできます。たとえば、イメージの追加、コントロール・パネルの表示の構成、リンクおよびラベルのカスタマイズなどです。

階層ビューア・コンポーネントの外観は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」での説明のとおり、スキンおよびコンポーネント・スタイル属性を変更することによって変更できます。

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

階層ビューア・コンポーネントのサイズは、プロパティ・インスペクタを使用して、階層ビューア・コンポーネントの属性の数に値を設定することによって調整できます。

階層ビューアのサイズを調整する手順:

1. 階層ビューア・コンポーネントを含むJSFページの構造ウィンドウで、dvt:hierarchyViewerノードを選択します。

2. プロパティ・インスペクタで、InlineStyleプロパティに次の値を記述します。

- width
パーセント(%)またはピクセル(px)で値を記述します。widthのデフォルト値は100%です。

- height
パーセント(%)またはピクセル(px)で値を記述します。heightのデフォルト値は600pxです。

InlineStyleプロパティに入力する最終値には、次の例に示す構文を使用する必要があります。

width:100%;height:600px;

3. JSFページへの変更を保存します。

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

実行時に階層ビューア・コンポーネントのノードがイメージに表示されるように階層ビューア・コンポーネントを構成できます。これは、組織図に画像を表示するような場合に便利です。目的のイメージのURLにバインドされるソース属性を含むaf:imageコンポーネントを挿入します。次のコード例では、イメージがレンダリングされます。

<af:panelGroupLayout>
<af:image source="/person_id=#{node.PersonId}"
inlineStyle="width:64px;height:90px;"/>
</af:panelGroupLayout>

af:panelGroupLayoutコンポーネントの詳細は、8.12.1項「panelGroupLayoutコンポーネントの使用方法」を参照してください。

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

実行時に階層ビューア・コンポーネントによってレンダリングされる場合、コントロール・パネルが次のように機能するように、29.1.2項「階層ビューアの要素と用語」で説明されているとおり、階層ビューア・コンポーネントを構成できます。

- 開いたまたは表示状態での表示

- 閉じたまたは非表示状態での表示

- ユーザーに対して非表示

コントロール・パネルの表示を構成する手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「プロパティに移動」を選択します。

2. 「外観」セクションを開き、ControlPanelBehaviorドロップダウン・リストから次の値のいずれかを選択します。

- hidden
実行時にコントロール・パネルを表示しない場合は、この値を選択します。

- initCollapsed
これがデフォルト値です。コントロール・パネルは、実行時に閉じたまたは非表示状態で表示されます。

- initExpanded
実行時にコントロール・パネルを開いたまたは表示状態で表示する場合は、この値を選択します。

3. JSFページへの変更を保存します。

29.7.4 リンクとラベルの表示の構成方法

階層ビューアでは、ノード間の関係はノードをつなぐ線で表されます。リンクは、ラベルを含めるように構成できます。図29-14に、階層ビューアのリンクとラベルを示します。

図29-14 階層ビューアのリンクとラベル

リンクとラベルの外観をカスタマイズするには、階層ビューアのdvt:link要素のプロパティを設定します。図29-15に、linkStype属性に値dashDotが設定されたリンクを示します。

図29-15 dashDotリンク・スタイルのリンク

リンクとラベルの表示のカスタマイズ手順:

1. 構造ウィンドウでdvt:linkノードを右クリックし、「プロパティに移動」を選択します。

2. プロパティ・インスペクタで、次の属性を設定して、階層ビューアのノード間のリンクの外観を必要に応じてカスタマイズします。

- linkStyle: リンクのスタイルを設定します(点線や破線など)。

- linkColor: リンクの色を設定します。

- linkWidth: リンクの幅をピクセル単位で設定します。

- linkType: リンクのタイプを設定します。1つの直角に適合する直線やなめらかな曲線など。

- endConnectorType: リンク接続の終端のスタイルをnone(デフォルト)またはarrowOpenに設定します。

3. プロパティ・インスペクタで、labelプロパティのリンクに関連付けられるラベルのテキストも入力します。
あるいは、子ノードに基づいてリンク・ラベルをスタンプ・アウトするEL式を指定します。たとえば、ノードのvar属性が、リンクに関連付けられる子ノードを参照する次のようなEL式を記述します。

label="{node.relationship}"

4. 必要に応じて、プロパティ・インスペクタで、renderedプロパティを使用して、ノード間の特定の関係のリンクをスタンプします。リンクが関係を表すかどうかを判別するためにtrueまたはfalseに評価されるEL式を記述できるように、プロパティはブール値を受け入れます。たとえば、レポート作成の関係に基づいて表示するリンクがあるとします。ノード・コンポーネントのrenderedプロパティに対して、関係が指定した値(この例では(CONSULTANT)と一致する場合にtrueと評価する次の疑似EL式のようなEL式を記述します。

rendered="#{node.relationship == "CEO"}

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

階層ビューアの検索機能は、階層ビューアのデータ構造を調べて、スクロール可能なリストで一致を提供します。検索結果をダブルクリックすると、一致するノードを階層ビューアのアンカー・ノードとして表示できます。有効な場合、検索パネルが階層ビューアの右上隅に表示され、結果は検索パネルの下に表示されます。図29-16に、検索パネルのサンプルを示します。

図29-16 階層ビューアの検索パネル

図29-17に、検索結果のサンプルを示します。

図29-17 階層ビューアの検索結果のサンプル

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

検索を有効にするには、dvt:hierarchyViewerタグの子タグとしてdvt:searchタグを追加し、結果の処理方法を指定するには、dvt:searchの子タグとしてdvt:searchResultsを追加します。

階層ビューアでの検索の構成手順:

1. 構造ウィンドウでdvt:hierarchyViewerノードを右クリックし、「dvt:hierarchyViewerの中に挿入」→dvt:searchを選択します。

2. プロパティ・インスペクタで、次の属性を設定して検索機能を構成します。

- value: 検索テキストを保持する変数を指定します。

- actionListener: 検索を実行する場合に呼び出されるリスナーを入力します。

- initialBehavior: 検索パネルが最初に表示される方法を指定します。有効な値は、最初に折りたたむ場合はinitCollapsed、最初に展開する場合はinitExpanded、ビューから完全に非表示にする場合はhiddenになります。

3. 必要に応じて、値がname="end"のf:facetを追加して、階層ビューア･コンポーネントの外部の高度な検索を起動するコンポーネントを指定します。このファセットには、データ・セットの広範囲な検索を起動するコンポーネント(af:commandLinkなど)を1つのみ含める必要があります。詳細は、12.4項「問合せコンポーネントの使用」を参照してください。

4. 構造ウィンドウでdvt:searchノードを右クリックし、「dvt:searchの中に挿入」→dvt:searchResultsを選択します。

5. プロパティ・インスペクタで、次の属性を設定して検索結果の表示を構成します。

- value: 検索結果のデータ・モデルを指定します。これは、oracle.adf.view.faces.bi.model.DataModelのインスタンスにする必要があります。

- var: 階層ビューアのコレクションの各要素を参照するために使用するEL変数の名前を入力します。このコンポーネントのレンダリングが完了すると、この変数は削除されます(またはその前の値に戻ります)。

- varStatus: varStatus情報を参照するために使用するEL変数の名前を入力します。このコンポーネントのレンダリングが完了すると、この変数は削除されます(またはその前の値に戻ります)。

- resultListener: 検索結果の行の選択後に呼び出されるアクション・リスナーの参照を指定します。

- emptyText: 結果が戻されない場合に表示するテキストを指定します。

- fetchSize: 一度にフェッチする結果行の数を指定します。

6. 構造ウィンドウでdvt:searchResultsノードを右クリックし、「dvt:searchResultsの中に挿入」→「ADF Faces」→af:setPropertyListenerと選択します。

7. プロパティ・インスペクタで、次の属性を設定して、結果モデルの検索結果ノードを、対応する階層ビューア・モデルにマップします。

- from: 値のソースを、定数またはEL式で指定します。

- to: 値のターゲットを指定します。

- type: actionを値として選択します。

8. 構造ウィンドウでdvt:searchResultsノードを右クリックし、「dvt:searchResultsの中に挿入」→f:facet(値はname="content")と選択します。

9. 構造ウィンドウでf:facet contentノードを右クリックし、次の手順を実行して、検索結果をスタンプ・アウトするコンポーネントを指定します。

- ADF Facesのaf:panelGroupLayout要素を挿入して、検索結果の出力をラップします。

- ADF Facesの出力コンポーネントを挿入して、検索結果を表示します。次に例を示します。

<af:outputText value="#{resultRow.Lastname} " id="ot1"
inlineStyle="color:blue;"/>
<af:outputText value="#{resultRow.Firstname}" id="ot2"/>

スタンプされたそれぞれの行は、dvt:searchResultsタグのvar属性を使用して現在の行を参照します。

例29-5に、階層ビューアで検索を構成するサンプル・コードを示します。

例29-5 階層ビューアの検索のサンプル・コード

<dvt:hierarchyViewer>
<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 inlineStyle="width:110px;height:20px;">
<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 階層ビューアでの検索の構成について

階層ビューアでの検索は、階層ビューアのデータ・モデルの基準となるデータ・コレクションの検索可能な属性または列に基づきます。Oracle ADFのデータ・コントロールで定義される問合せ結果コレクションを使用すると、JDeveloperでは宣言的なタスクとなります。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の階層ビューアでのデータバインドされた検索の作成方法に関する項を参照してください。

第V部

高度なトピック

第V部には、次の章が含まれています。

- 第30章「カスタムADF Facesコンポーネントの作成」

- 第31章「JSFページでのユーザー・カスタマイズの許可」

- 第32章「ドラッグ・アンド・ドロップ機能の追加」

- 第33章「異なる出力モードの使用」

30 カスタムADF Facesコンポーネントの作成

この章では、カスタムADF Facesリッチ・クライアント・コンポーネントの作成方法を説明します。

この章では、次の項目について説明します。

- 30.1項「カスタムADF Facesコンポーネントの概要」

- 30.2項「ワークスペースと基礎ファイルの設定」

- 30.3項「クライアント側の開発」

- 30.4項「サーバー側の開発」

- 30.5項「コンポーネント・ライブラリのデプロイ」

- 30.6項「アプリケーションへのカスタム・コンポーネントの追加」

30.1 カスタムADF Facesコンポーネントの概要

ADF Facesコンポーネント・ライブラリには、ユーザー要件の大部分をカバーするUIコンポーネントの包括的なセットが用意されています。ただし、アプリケーションに固有のカスタム・リッチ・コンポーネントを作成する必要がある場合があります。カスタム・リッチ・コンポーネントによって、カスタム動作が可能になり、アプリケーションのニーズに最適なアクションを実行できます。

注意:

カスタム標準JSFコンポーネントの作成については、多くの本、記事、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アーキテクチャの詳細は、第3章「ADF Facesアーキテクチャの使用」を参照してください。

ADF Facesコンポーネントは、Apache MyFaces Trinidadコンポーネント・ライブラリから導出されます。このため、カスタムADF Facesコンポーネントを作成するときに拡張するクラスの多くは、実際にはMyFaces Trinidadのクラスとなります。ADF Facesの履歴(その発展を含む)の詳細は、第1章「ADF Facesリッチ・クライアントの概要」を参照してください。

JSPコンポーネントとJSFコンポーネントの間にApplicationクラスがあります。タグ・ライブラリでは、applicationオブジェクトに対してファクトリ・メソッドが使用され、componentTypeと呼ばれるニーモニックを使用して具体的なコンポーネント・インスタンスがインスタンス化されます。

コンポーネントでは独自のマークアップをレンダリングできますが、それがベスト・プラクティスであるとは考えられていません。プレゼンテーションのレンダリングの方法に焦点を当てたレンダー・キットを定義する方法をお薦めします。コンポーネントは、レンダー・キットに対してファクトリ・メソッドを使用して、特定のコンポーネントに関連付けられているレンダラを取得します。コンポーネントがFaceletsを使用するアプリケーションで消費される場合、コンポーネント・ハンドラによって、コンポーネントが作成されます。

作成するすべてのカスタム・コンポーネントでは、機能面に加え、その他のADF Facesコンポーネントで正しく表示されるようにするために、ADF Facesスキンを使用する必要があります。スキンを使用するには、コンポーネントのスキニング・キーとプロパティを作成して登録する必要があります。この章では、カスタム・コンポーネントのスキンの作成方法および登録方法のみ説明します。一般的なスキンの使用方法および作成方法の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

ヒント:

ADF Facesコンポーネントを使用するために、カスタム・コンポーネントでは、簡単なスキンからFusionFX、blafplus-richおよびblafplus-mediumスキンが継承されるため、少なくともADF Facesのsimpleスキンを使用する必要があります。また、コンポーネントをOracle WebCenter Portalアプリケーションで使用する可能性がある場合は、使用するスキンはsimple.portletスキンにも登録する必要があります。

30.1.1 JDeveloperを使用したカスタム・コンポーネントの開発

ADF Facesコンポーネントは、クライアント側リソースとサーバー側リソースの両方で構成されています。クライアント側には、クライアント・コンポーネント、コンポーネント・ピア(コンポーネント・プレゼンタ)、およびクライアント・コンポーネントに関連付けられているすべてのイベントがあります。

サーバー側には、サーバー・コンポーネント、サーバー・コンポーネント・イベントおよびイベント・リスナーがあります。また、コンポーネント・レンダラ、コンポーネントJSPタグ、コンポジット・リソース・ローダー、JavaScriptリソース・ローダーおよびリソース・バンドルもあります。

コンポーネントには、いくつかの構成ファイルとサポート・ファイルもあります。これらのクラス、JavaScriptおよび構成ファイルは、JARファイルにまとめてパッケージ化されているため、ライブラリとしてアプリケーションにインポートして、他のアプリケーションと同様に使用できます。

JDeveloperを使用して、カスタム・コンポーネントを開発するアプリケーション・ワークスペースおよびプロジェクトを設定できます。ワークスペースおよびプロジェクトを作成したら、カスタム・コンポーネントを構成する必須のクラス、JavaScriptファイルおよび構成ファイルに対して、基礎作業ファイルを追加します。開発時には、カスタム・コンポーネントに固有のそれらのファイルをそれぞれ編集し、ファイルにコードを追加します。

開発プロセスは次のとおりです。

1. 開発の環境として、アプリケーション、ワークスペースおよびプロジェクトを作成します。これには、ライブラリ依存性の追加、XMLスキーマの登録が含まれます。コンポーネントは、そのコンポーネントを使用する予定があるアプリケーションには作成しないでください。

2. JARファイルにコンポーネントをパッケージ化するためのデプロイメント・プロファイルを作成します。

3. 次の基礎構成ファイルとサポート・ファイルを作成します。

- faces-config.xml: コンポーネントで使用される多くのアーティファクトを登録するために使用します。

- trinidad-skins.xml: コンポーネントが使用するスキンを登録するために使用します。

- Cascading Style Sheet: スキンのスタイル・プロパティを定義するために使用します。

- レンダー・キット・リソース・ローダー: コンポーネントで必要とされるすべてのリソースをアプリケーションでロードできるようにします。

- adf-js-features.xml: コンポーネントをJavaScriptパーティションの一部にできます。パーティションの詳細は、1.2.1.2項「JavaScriptライブラリのパーティション化」を参照してください。

- JSPタグ・ライブラリ・ディスクリプタ(TLD)(JSPの場合): JSFページで使用するタグを定義します。

- コンポーネント・ハンドラ(Faceletsの場合): コンポーネントのレンダリングに使用されるハンドラを定義します。

4. 次のクライアント側JavaScriptファイルを作成します。

- クライアント・コンポーネント: クライアントのコンポーネントとその属性を表します。

- クライアント・ピア: コンポーネントのDocument Object Model(DOM)を管理します。

- クライアント・イベント: クライアントでの処理を起動し、オプションでサーバーに処理を伝播します。

5. 次のサーバー側Javaファイルを作成します。

- サーバー・コンポーネント・クラス: サーバーのコンポーネントを表します。

- サーバー・イベント・リスナー・クラス: イベントをリスニングして、応答します。

- サーバー・イベント・クラス: サーバーのイベントを起動します。

- サーバー・レンダラ・クラス: コンポーネントの表示を決定します。

- リソース・バンドル・クラス: コンポーネントで使用されるテキスト文字列を定義します。

6. JavaScriptおよびJavaコードをテストおよびデバッグして、コンポーネントの開発をさらに進めます。JDeveloperデバッガを使用して、ブレークポイントを設定し、コードを段階的に開発できます。Javaロギング機能を使用して、コンポーネントの実行をトレースすることもできます。

7. JARファイルにコンポーネントをデプロイします。

8. コンポーネントをアプリケーションに追加してテストします。

表30-1には、カスタム・コンポーネントのクライアント側およびサーバー側コンポーネントのアーティファクトがリストされています。この表には構成ファイルおよびサポート・ファイルは含まれていません。

表30-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

30.1.2 カスタム・コンポーネントの例

カスタム・コンポーネントの作成について説明するために、手順全体でtagPaneという名前のカスタム・コンポーネントを例として使用します。tagPaneカスタム・コンポーネントは、再利用の目的で作成されます。tagPaneのプレゼンテーションは、既存の様々なコンポーネントを使用して実装可能ですが、単一のカスタム・コンポーネントを作成するとページ開発者の作業が単純化されます。この場合、コンポーネント開発者とページ開発者間の生産性においてトレードオフが生じることがあります。この特定のビューを複数回作成する必要がある場合、開発チームはコード行を減らし、ビジネス・プロセスの自動化タスクを単純化することで、コストを削減できます。

tagPaneコンポーネントは、ファイル・セットに対する一連のタグとその出現の重み付けを表示します。最も頻繁に使用されるタグは最大フォント・サイズで表示され、最も使用されないタグは最小フォント・サイズで表示されます。各タグはイベントをトリガーするリンクでもあり、トリガーされたイベントはサーバーに伝播されます。サーバーでは、そのタグを含むすべてのファイルが表に表示されます。図30-1に、tagPaneコンポーネントがFile Explorerアプリケーションの「検索」ペインの下に追加された場合にどのように表示されるかを示します。

図30-1 カスタムtagPaneコンポーネント

tagPaneコンポーネントは、Java Mapコレクションのタグのコレクションを受け取ります。マップのキーはタグ名です。値はタグに割り当てられた重みです。File Explorerアプリケーションでは、重みはタグの出現回数であり、多くの場合、タグに関連付けられているファイル数です。タグ名はリンクのボディ・テキストに表示され、名前の表示に使用されるフォント・サイズが重みを表します。各タグのフォント・サイズは、ファイル・セット内のすべてのタグに割り当てられている重みの最大と最小に基づき、最大フォント・サイズと最小フォント・サイズ内で相対的に計算されます。これらの機能を実行するには、tagPaneカスタム・コンポーネントにクライアント側とサーバー側の両方の動作を設定する必要があります。

サーバー側では、コンポーネントはHTMLハイパーリンクをレンダリングすることでタグのマップを表示します。基本的なマークアップ・レンダリングはサーバー側で実行されます。コンポーネントには、ユーザーによるリンクのクリックを処理し、関連ファイルを表示するためのカスタム・イベントを定義します。これらのサーバー側の動作は、値式およびメソッド式を使用して定義します。

たとえば、tagPaneコンポーネントには次のものが含まれます。

- タグのMap<String, Number>コレクションを設定するtagプロパティ。

- タグのリンクをクリックしたときにサーバーで起動されるtagSelectionListenerメソッド・バインディング・イベント。

- 重みの降順で左から右に一連のタグを表示する、またはアルファベットの昇順にタグのリンクを表示するためのorderByプロパティ。

各タグをその重み(出現回数)に比例したフォント・サイズで表示するために、フォント・サイズはインライン・スタイルを使用して制御されます。ただし、各タグとコンポーネントのルート・マークアップ・ノードもスタイル・クラスを使用します。

例30-1に、tagPaneコンポーネントのJSFページでの使用方法を示します。

例30-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コンポーネントでは、ルート要素を指定し、リンクのコンテナのスタイルおよびハイパーリンクの表示方法を定義するために、スキン・セレクタが必要です。例30-2に、tagPaneコンポーネントのCSSファイル内のスタイル・セレクタのサンプル・セットを示します。

例30-2 サンプル・カスタム・コンポーネントのCSSスタイル・セレクタ

acme|tagPane     - root element
acme|tagPane::content - container for the links
acme|tagPane::tag - tag hyperlink

サーバー側のカスタム・コンポーネントに必要なHTMLコードを指定する必要がある場合もあります。

例30-3に、tagPaneコンポーネントで使用されるHTMLサーバー側のコードを示します。

例30-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とのすべての対話は、ピアを使用して行われます(詳細は、第3章「ADF Facesアーキテクチャの使用」を参照してください)。コンポーネント・ピアでは、タグ名を囲むハイパーリンクのクリックがリスニングされます。リンクがクリックされると、ピアによってクライアント側でカスタム・イベントが発生し、そのイベントがサーバー側に伝播されて、追加処理されます。

表30-2には、tagPaneコンポーネントのクライアント側とサーバー側のアーティファクトがリストされています。表30-1のネーミング規則を参照すると、component_packageはcom.adfdemo.acme、prefixはAcmeです。

表30-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

30.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(Faceletsの場合): 使用アプリケーションでFaceletsを使用する場合のコンポーネントのタグ定義ライブラリです。このファイルは、コンポーネントのハンドラを定義します。

たとえば、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で設定した後、これらにコンテンツを追加します。次に、クライアント側のファイルとサーバー側のファイルを作成します。詳細は、30.3項「クライアント側の開発」および30.4項「サーバー側の開発」を参照してください。

30.2.1 JDeveloperカスタム・コンポーネント環境の設定方法

この章では、ユーザーがJDeveloperの使用経験があり、アプリケーションの作成およびデプロイに伴う手順に精通していると仮定しています。JDeveloperを使用したアプリケーションの作成の詳細は、第2章「ADF Faces概説」を参照してください。デプロイメントの詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「Fusion Webアプリケーションのデプロイ」の章を参照してください。

JDeveloperでカスタム・コンポーネントの開発環境を設定する手順:

1. コンポーネントの開発コンテナとして機能するアプリケーションを作成します。JDeveloperを使用して、ワークスペースおよびプロジェクトを作成します。アプリケーションの作成手順については、2.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、Facelets Runtime(Faceletsを使用する場合)、JSF 1.2、JSP Runtimeを選択して、「OK」をクリックします。

4. 「OK」をクリックして、「プロジェクト・プロパティ」ダイアログを閉じます。

4. XMLスキーマを登録します。
カスタム・コンポーネントには、複数のXML構成ファイルが必要です。JDeveloperを使用して、それらの構成ファイルに関連付けられているXMLスキーマを登録できます。faces-config.xml、trinidad-skins.xmlおよびtrinidad-config.xmlの3つの構成ファイルのスキーマを追加する必要があります。これらのスキーマを事前登録することにより、マークアップ構造の詳細を理解できなくても、テンプレートXML構成ファイルを作成できます。スキーマの名前と場所は、JDeveloperのベース・インストールによって想定されます。

1. 「ツール」→「プリファレンス」を選択します。「設定」ダイアログの左ペインで「XMLスキーマ」を選択し、「追加」をクリックします。

2. 表30-3に示すように、「スキーマの追加」ダイアログで「参照」をクリックして、JDeveloperビルドに含まれているXMLスキーマに移動します。

注意:

「スキーマの追加」ダイアログでは、「拡張子」が.xmlに設定されていることを確認してください。拡張子をXSDに変更すると、後でXMLファイルを作成するときに、作成したXMLスキーマを使用できなくなります。

表30-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

30.2.2 Faces構成ファイルの追加方法

カスタム・コンポーネントは使用アプリケーションのfaces-config.xmlファイルに登録されますが、開発中は、ワークスペースにfaces-config.xmlファイルが必要です。

注意:

JDeveloperの宣言ウィザードやダイアログを使用してfaces-config.xmlファイルを作成しないでください。これらの宣言メソッドは、Webアプリケーションの作成を前提としており、カスタム・コンポーネント・アプリケーションに不要なアーティファクトが追加されます。

カスタム・コンポーネントの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ツール・サポートを得られます。

30.2.3 MyFaces Trinidadスキン構成ファイルの追加方法

MyFaces Trinidadスキン・ファイルを追加して、コンポーネントのスタイルを定義するために使用するコンポーネントのCSSファイルを登録します。

カスタム・コンポーネントのtrinidad-skins.xmlファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「XML」を選択します。

3. 「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

4. XMLスキーマからXMLを作成ダイアログで、次のように設定します。

- XMLファイル: trinidad-skins.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

5. 次の内容を入力します。

- ターゲット・ネームスペース: http://myfaces.apache.org/trinidad/skinを選択します。

- ルート要素: skinsを選択します。

- 「終了」をクリックします。新しいファイルがXMLエディタで自動的に開きます。

30.2.4 Cascading Style Sheetの追加方法

Cascading Style Sheetを追加して、コンポーネントのスタイルを定義します。

カスタム・コンポーネントの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になります。

30.2.5 リソース・キット・ローダーの追加方法

空のファイルを作成し、カスタム・リソース・ローダーへの完全修飾クラスパスを追加します。

カスタム・コンポーネントのリソース・ローダーを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「ファイル」を選択して「OK」をクリックします。

3. 「ファイルの作成」ダイアログで、次のように設定します。

- 「ファイル名」にcomponent_prefix.resourcesと入力します。component_prefixは、コンポーネント・ライブラリで使用される接頭辞です。たとえば、tagPaneコンポーネントの場合、acmeが接頭辞になるため、入力する文字列はacme.resourcesになります。

- ディレクトリ・エントリの最後に\src\META-INF\sevlets\resources\を追加します。

30.2.6 JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法

JSFページを使用するにはJSP TLDファイルが必要です。

カスタム・コンポーネントのJavaServer Pages TLDファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「JSP」を選択します。

3. 「JSPタグ・ライブラリ」を選択し、「OK」をクリックします。

4. 「JavaServer Pageタグ・ライブラリ作成」ダイアログで「デプロイ可能」を選択し、「次へ」をクリックします。

5. 次の内容を入力します。

- タグ・ライブラリ・ディスクリプタのバージョン: 2.1を選択します。

- 短縮名: 名前を入力します。たとえば、tagPaneコンポーネントの場合、acmeと入力します。

- タグ・ライブラリURI: タグ・ライブラリのURIを入力します。たとえば、tagPaneコンポーネントの場合、http://oracle.adfdemo.acmeと入力します。

6. 「次へ」をクリックし、オプションで追加のタグ・ライブラリ情報を入力して、「終了」をクリックします。

30.2.7 JavaScriptライブラリ機能構成ファイルの追加方法

機能ファイルを追加して、カスタム・コンポーネントに関連付けられているJavaScriptファイルを定義します。クライアント・コンポーネント、クライアント・ピアおよびクライアント・イベントのファイルが含まれます。

カスタム・コンポーネントのadf-js-features.xmlファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「XML」を選択します。

3. 右ペインで「XMLスキーマからXMLドキュメント」を選択し、「OK」をクリックします。

4. XMLスキーマからXMLを作成ダイアログで、次のように設定します。

- XMLファイル: adf-js-features.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

- 「登録済のスキーマを使用」を選択して、「次へ」をクリックします。

5. 次のように設定します。

- ターゲット・ネームスペース: http://xmlns.oracle.com/adf/faces/featureを選択します。

- ルート要素: featuresを選択します。

- 「終了」をクリックします。新しいファイルがXMLエディタで自動的に開きます。

30.2.8 Faceletsタグ・ライブラリ構成ファイルの追加方法

使用アプリケーションでFaceletsを使用する場合、コンポーネントにハンドラを定義する必要があります。

Faceletsタグ・ライブラリ・ファイルの作成手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「XML」を選択します。

3. 右ペインで「XMLドキュメント」を選択し、「OK」をクリックします。

4. 「XMLファイルの作成」ダイアログで、次を入力します。

- ファイル名: prefix_name.taglib.xmlと入力します。

- ディレクトリ: ディレクトリ・エントリの最後に\src\META-INFを追加します。

5. 例30-4に示すコードをコピーして貼り付けます。

例30-4 Faceletsタグ・ライブラリ構成ファイルのコード

<?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>

6. 太字のネームスペースとタグ名のコードを、使用するアプリケーションに適したコードで置き換えます。

30.3 クライアント側の開発

JDeveloperワークスペースおよび構成ファイルを作成すると、クライアント側のJavaScriptファイルを作成およびコーディングできます。クライアント側の開発が終了したら、30.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イベント・コールバックが管理されます。クライアント側アーキテクチャ(ピアを含む)の詳細は、3.1項「ADF Facesアーキテクチャの使用の概要」を参照してください。

次の項では、カスタム・コンポーネント開発テンプレート環境がすでに設定されていると仮定しています。この開発環境には、アプリケーション・ワークスペース、プロジェクトおよびデプロイメント・プロファイルの設定、およびスキーマの登録が含まれます。まだ設定していない場合は、30.2項「ワークスペースと基礎ファイルの設定」を参照してください。

30.3.1 コンポーネントのJavaScriptファイルの作成方法

JDeveloperを使用して、コンポーネントのJavaScriptファイルを作成します。JavaScriptファイルに、コンポーネントのコンポーネント・タイプを定義します。

コンポーネントのJavaScriptファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」をクリックします。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」を選択します。

3. 「JavaScriptファイル」を選択し、「OK」をクリックします。

4. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagPane.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、コンポーネントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adfrichclient-demo-acme\src\oracle\adfdemo\acme\js\componentと入力します。

5. エディタでJavaScriptファイルを開き、コンポーネント・コードを追加して、コンポーネント・タイプを定義します。例30-5に、tagPaneコンポーネントで使用されるコードを示します。

例30-5 tagPaneコンポーネントのJavaScript

AdfUIComponents.createComponentClass(
"AcmeTagPane",
{
componentType:"oracle.adfdemo.acme.TagPane",superclass:AdfUIObject
}
);

30.3.2 イベントのJavaScriptファイルの作成方法

JDeveloperを使用して、イベントのJavaScriptファイルを作成します。イベントが起動されたとき(マウス・クリックなど)に必要な機能を実行するためのコードをJavaScriptに追加します。

イベントのJavaScriptを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」を選択します。

3. 「JavaScriptファイル」を選択し、「OK」をクリックします。

4. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側イベントの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagSelectEvent.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、イベントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adf-richclient-demo-acme\src\oracle\adfdemo\acme\js\eventと入力します。

5. エディタでJavaScriptファイルを開き、イベント・コードを追加します。例30-6に、tagPaneコンポーネントに追加されるイベント・コードを示します。

例30-6 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;
}

30.3.3 ピアのJavaScriptファイルの作成方法

JDeveloperを使用して、ピアのJavaScriptファイルを作成します。コードを追加してピアを登録し、コンポーネントにバインドします。

ピアのJavaScriptファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「Web層」を開き、「HTML」を選択します。

3. 「JavaScriptファイル」を選択し、「OK」をクリックします。

4. 「JavaScriptファイルの作成」ダイアログで、次のように設定します。

- ファイル名: クライアント側ピアの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeTagPanePeer.jsと入力します。

ヒント:

ネーミングの競合を回避するために、名前をコンポーネントの接頭辞で開始します。

- ディレクトリ: srcディレクトリの下のサブディレクトリに、イベントのディレクトリ・パスを入力します。たとえば、tagPaneコンポーネントの場合、adf-richclient-demo-acme\src\oracle\adfdemo\acme\js\componentと入力します。

5. エディタでJavaScriptファイルを開き、ピアのコードを追加します。このコードで、ピアを作成し、DOMに関するイベント処理を追加し、ピアをコンポーネントに登録する必要があります。例30-7に、tagPaneコンポーネントに追加されるコードを示します。

例30-7 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");

30.3.4 JavaScriptライブラリ機能構成ファイルへのカスタム・コンポーネントの追加方法

これで、コンポーネントのすべてのJavaScriptファイルを作成しました。作成したコンポーネントをadf-js-features.xmlファイルに追加できます。A.9.1項「JavaScript機能の作成方法」で説明する手順に従う場合、XMLファイルをすでに作成しているため、その作成手順は省略されます。例30-8に、tagPaneコンポーネントに使用されるadf-js-features.xmlファイルを示します。

例30-8 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>

30.4 サーバー側の開発

サーバー側の開発には、次のものに対するJavaクラスの作成が含まれます。

- イベント・リスナー: このクラスは、イベントをリスニングして、そのイベントを処理するための処理ロジックを起動します。

- イベント: 関連付けられたリスナーでロジックを起動するためのイベントを作成します。

- コンポーネント: このクラスは、コンポーネントの動作を定義するプロパティを保持します。

- リソース・バンドル: このクラスは、コンポーネントのテキスト文字列を保持します。

- レンダラ: このクラスは、クライアントでのコンポーネントの表示方法を決定します。

- リソース・ローダー: このクラスは、スキニングに必要なイメージがコンポーネントに含まれている場合のみ必要です。

これらのクラスを作成したら、コンポーネント・クラスおよびレンダラ・クラスをfaces-config.xmlファイルに追加します。その後、30.2項「ワークスペースと基礎ファイルの設定」で開始した構成ファイルを完了させます。

30.4.1 イベント・リスナーのクラスの作成方法

ADF FacesイベントAPIには、イベントを処理するためのイベント・リスナー・インタフェースが必要です。カスタム・コンポーネントにはイベントに対する依存性があり、イベントにはイベント・リスナー・インタフェースに対する依存性があります。Javaのimport文に、これらの依存性を反映させる必要があります。コンポーネントのcomponentTypeも定義する必要があります。

EventListenerクラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaインタフェース」を選択し、「OK」をクリックします。

4. Javaインタフェース・ファイルの作成ダイアログで、次のように設定します。

- 名前: リスナーの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagSelectListenerと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.eventと入力します。

5. エディタでJavaファイルを開き、次の内容を追加します。

- リスナーでjavax.faces.event.FacesListenerインタフェースを拡張します。

- import文を追加して、FacesListenerクラス、およびイベントが依存するすべてのクラスをインポートします。

- 新規イベントを処理するメソッド・シグネチャを追加します。実際のイベントを作成していない場合でも、ここで入力しておけば、後で入力する必要がなくなります。

例30-9に、tagPaneイベント・リスナーのコードを示します。

例30-9 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;
}

30.4.2 イベントのクラスの作成方法

30.3.2項「イベントのJavaScriptファイルの作成方法」で作成したJavaScriptイベントに対応するサーバー側のイベントを作成する必要があります。サーバー側のJSFイベントは、リクエスト値の適用ライフサイクル・フェーズ中にコンポーネントによってキューに入れられます。イベントは、レスポンスのレンダリング・フェーズ以外のすべてのフェーズの後にUIViewRootクラスまで伝播されます。キューイングされたイベントは、関連付けられたコンポーネントにブロードキャストされます。

サーバー側のJavaコンポーネントでは、サーバー側のイベントを呼び出す必要があるため、最初にイベント・ソース・ファイルを作成して、コンパイル依存性を解決する必要があります。

サーバー側イベント・クラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択し、「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: イベントの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagSelectEventと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.eventと入力します。

- 拡張: イベント・クラスで拡張するクラスの名前を入力します。この名前は通常、javax.faces.event.FacesEventです。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

例30-10に、イベント・クラスのコードを示します。

例30-10 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;
}
}

30.4.3 コンポーネントの作成

JSFコンポーネントは、プロパティの状態ホルダーであると言えます。それらのプロパティでは、レンダリングの動作、およびコンポーネントがユーザー・インタフェース・アクションにどのように応答するかを定義します。コンポーネント・クラスを開発する場合、必要なプロパティのタイプを識別する必要があります。また、MyFaces Trinidadフレームワークから拡張される基本コンポーネントも定義します。たとえば、tagPaneコンポーネントは、MyFaces TrinidadのUIXObjectを拡張します。

大部分のコンポーネントには、実装する必要があるプロパティが複数あります。ベース・クラスから継承されるプロパティもあれば、リッチ・クライアント・フレームワークに必須のプロパティもあります。他のプロパティはベスト・プラクティスであるため、必要となります。また、一部のプロパティは、カスタム・コンポーネントの機能に固有のものです。

たとえば、tagPaneコンポーネントには、表30-4に示されているプロパティがあります。

表30-4 tagPaneカスタム・コンポーネントのコンポーネント・プロパティ

元

プロパティ

データ型

説明

継承

id

String.class

コンポーネントの識別子。

rendererType

String.class

コンポーネント・レンダラとして登録されている論理識別子。

rendered

Boolean.class

コンポーネントがレンダリングされているかどうかを判断するTrueまたはFalseのフラグ。

binding

ValueExpression.class

マネージドBeanにコンポーネント・インスタンスを格納するバインディング値式。

リッチ・クライアント・フレームワーク

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の実装パッケージから拡張しないでください。これらの実装は固有のものであり、変更される可能性があります。

30.4.4 コンポーネントのクラスの作成方法

JDeveloperを使用して、コンポーネントのJavaファイルを作成します。プロパティ情報を保持するType Beanを作成し、各プロパティのPropertyKeyを定義します。次に、private属性のアクセッサを生成します。

コンポーネント・クラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択します。「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.componentと入力します。

- 拡張: コンポーネント・クラスで拡張するクラスの名前を入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.component.UIXObjectと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

5. ソース・エディタで、コンポーネント・プロパティ情報を含むType Beanを作成します。この静的クラス属性によって、スーパー・クラス内の同じ名前を持つ属性がシャドウされます。type属性は、コンポーネント・クラスごとに一度定義されます。Typeコンストラクタを介して、スーパー・クラスのType Beanに参照が渡され、プロパティ情報がコピーされます。たとえば、tagPaneクラスには次のコンストラクタが含まれます。

static public final FacesBean.Type TYPE = new FacesBean.Type(UIXObject.TYPE);

6. プロパティごとに、プロパティ状態へのアクセスに使用される静的PropertyKeyを定義します。TYPE参照を使用して、新規属性を登録します。クラス参照を使用して、プロパティ・タイプを指定します。コンポーネントのデータ型は、コンポーネント・プロパティと対応している必要があります。状態情報を指定できるようにするregisterKeyメソッドの別のオーバーロードもあります。デフォルトでは、プロパティはpersistentであるとみなされます。例30-11に、tagPaneコンポーネントのPropertyKeyメソッドを示します。

例30-11 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);

7. エディタ内で右クリックし、「アクセッサの生成」を選択します。「アクセッサの生成」ダイアログで「すべて選択」をクリックして、スコープがPublicに設定されていることを確認し、「OK」をクリックします。これで、JDeveloperでprivate属性のgetメソッドおよびsetメソッドを生成できます。
その後、private属性を削除して、getProperty(PropertyKey)およびgetProperty(PropertyKey)へのコールで置き換えます。

例30-12に、private属性を置き換えた後のコードを示します。

例30-12 コンポーネントのプロパティ

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);
}

8. コンポーネントの特定の機能を実行するには、メソッドをオーバーライドする必要がある場合があります。たとえば、コンポーネントが部分ページ・レンダリング(PPR)に参加できるようにするには、例30-13に示すように、getBeanTypeメソッドをオーバーライドする必要があります。

例30-13

/**
* <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;
}

コンポーネントが展開するクラスや、オーバーライドする必要があるメソッドの詳細は、『ADF Faces JavaDoc』を参照してください。

tagPaneコンポーネントの場合、コンポーネントはクライアント・コンポーネントから起動されるイベントで動作する必要があります。ソース・コンポーネントへの参照は、パラメータとしてイベントのコンストラクタに渡されます。

tagPaneコンポーネントの場合、仮パラメータを使用して渡されたイベントがTagSelectEventであるかどうかが、broadcastメソッドによって確認されます。そうである場合、broadcastメソッドによって、tagSelectListener属性に保持されているメソッド式が呼び出されます。

大部分のイベントには、イベントを起動するライフサイクル・フェーズを指定するimmediateブール・プロパティがあります。immediate属性がtrueの場合、イベントは値の適用フェーズで処理され、falseの場合は、アプリケーションの起動フェーズで処理されます。詳細は、第4章「ADF FacesでのJSFライフサイクルの使用」を参照してください。

例30-14に、tagPaneコンポーネントのオーバーライドされるbroadcastメソッドを示します。

例30-14 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);
}

30.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など)も追加する必要があります。

カスタム・コンポーネントを登録する手順:

1. アプリケーション・ナビゲータで、faces-config.xmlファイルをダブルクリックします。

2. 「概要」タブをクリックして、「コンポーネント」ナビゲーション・タブをクリックします。

3. 「追加」アイコンをクリックして、コンポーネントのタイプとクラスを入力します。

4. オプションで、任意の属性、プロパティまたはファセットを追加します。

例30-15に、faces-config.xmlファイルに定義されているtagPaneコンポーネントを示します。

例30-15 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>

30.4.6 リソース・バンドルのクラスの作成方法

リソース・バンドルは、コンポーネントの情報(ラベルやメッセージのテキストなど)、およびアプリケーションでロケールの切替えが許可されている場合に使用される翻訳されたテキストを格納するために使用されます。スキンでも、コンポーネントのテキストを保持するためにリソース・バンドルが使用されます。カスタム・コンポーネントでは少なくとも簡単なスキンを使用する必要があるため、少なくともそのスキンのリソース・バンドルを作成する必要があります。カスタム・コンポーネントの場合は、リソース・バンドルのJavaファイルを作成します。リソース・バンドル・クラスの詳細は、20.3項「スキン・スタイル・プロパティの定義」を参照してください。

ヒント:

リソースのプロパティ・ファイルを使用することもできます。

リソース・バンドル・クラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択し、「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: リソース・バンドルの名前を入力します。名前には、使用するスキンを反映させる必要があります。たとえば、サンプル・コンポーネントの場合、AcmeSimpleDesktopBundleと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、サンプル・コンポーネントの場合、oracle.adfdemo.acme.faces.resourceと入力します。

- 拡張: リソース・バンドルの場合、java.util.ListResourceBundleと入力する必要があります。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

5. 必要に応じてキーを追加し、テキストを定義します。スキンのリソース・バンドルの作成の詳細は、20.3.1項「テキストへのスキンの適用方法」を参照してください。
例30-16に、tagPaneコンポーネントのリソース・バンドル・コードを示します。

例30-16 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}"}
};
}
}

6. 簡単なデスクトップ・スキンおよび他の必要なスキンのリソース・バンドルを登録するには、/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の値を手動で入力してから、コメント・タグを削除することもできます。

例30-17に、tagPaneリソース・バンドルを簡単なスキンに登録するためのコードを示します(この後の手順でstyle-sheet-name要素値を追加します)。

例30-17 リソース・バンドルのスキンへの登録

<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>

30.4.7 レンダラのクラスの作成方法

ADF Facesコンポーネントでは、コンポーネントの機能はコンポーネント・クラスに、使用アプリケーションでJSPを使用する場合はコンポーネントの表示はレンダラに委任されます。デフォルトでは、ADF Facesのすべてのタグが、関連付けられたコンポーネント・クラスとHTMLレンダラを結合し、HTMLレンダー・キットの一部になっています。ADF Facesには、デスクトップおよびPDAデバイスの両方に表示できるように、HTMLレンダー・キットが含まれています。

レンダラは、ファミリとレンダラ・タイプによってレンダー・キットで修飾されます。ファミリはコンポーネントの一般カテゴリであり、スーパー・クラスに定義されているファミリと同じにする必要があります。コンポーネントは継承によってメソッドを取得するため、コンポーネント内のgetFamily()メソッドをオーバーライドする必要はありません。

レンダラ・クラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択し、「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: レンダラの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneRendererと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.renderと入力します。

- 拡張: oracle.adf.view.rich.render.RichRendererと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

5. 必要な機能を追加します。たとえば、スキン機能では、コンポーネントのレンダリング中に指定のCSSセレクタのCSSスタイル・プロパティの取得に使用できるAPIが提供されます。このAPIは、スタイルの設定内容に基づいて条件付レンダリングを実行する必要がある場合に役立ちます。詳細は、http://myfaces.apache.org/trinidad/trinidad-1_2/trinidad-api/apidocs/index.htmlにあるMyFaces TrinidadのJavadocのRenderingContext#getStylesおよびStyles#getSelectorStyleMapを参照してください。

30.4.8 faces-config.xmlファイルへのレンダラの追加方法

レンダラを作成したら、faces-config.xml構成ファイルを使用して登録します。カスタム・コンポーネントを他のADF Facesコンポーネントと組み合せて機能させる場合、そのADF Facesコンポーネントが使用しているのと同じレンダー・キットIDを使用する必要があります。

ヒント:

JSFでレンダー・キットを定義できる最も高いレベルはビュー・ルートです。

レンダー・キットおよびレンダラを登録する手順:

1. アプリケーション・ナビゲータで、faces-config.xmlファイルをダブルクリックして、エディタで開きます。

2. 「概要」タブをクリックして、「レンダー・キット」ナビゲーション・タブを選択します。

3. 「レンダー・キット」の「追加」アイコンをクリックして、レンダー・キットIDにoracle.adf.richと入力します。

4. 「レンダラ」の「追加」アイコンをクリックしてレンダラを登録し、次のように設定します。

- ファミリ: コンポーネントで拡張するクラスを入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.Objectと入力します。

- Type: コンポーネントのタイプを入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.TagPaneと入力します。これは、レンダラ・タイプと一致している必要があります。

- クラス: 30.4.7項「レンダラのクラスの作成方法」で作成したレンダラの完全修飾クラス・パスを入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.render.TagPaneRendererと入力します。

例30-18に、tagPaneコンポーネントのレンダー・キットおよびレンダラの登録を示します。

例30-18 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>

30.4.9 JSPタグ・プロパティの作成方法

JSPページでコンポーネントを使用するには、カスタム・コンポーネントをインスタンス化するカスタム・タグを作成します。コンポーネントのレンダラは実際に該当タスクを実行するため、JSPタグはレンダラとは関係ありません。JSF 1.1では、JSPタグは、コンポーネントを作成してコンポーネント・ツリーに追加してから、コンポーネントのレンダリングを開始します。これにより、JSF/JSP以外のタグが同じレスポンス・ライターに書き込むため、問題が生じていました。コンポーネントが自身の子コンポーネントをレンダリングした場合、インターリービングのタイミングがうまく機能しませんでした。

注意:

(Faceletsを使用するアプリケーションでは、ハンドラを使用してコンポーネントをインスタンス化します。詳細は、30.2.8「Faceletsタグ・ライブラリ構成ファイルの追加方法」を参照)。

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つの属性をタグ・クラスに追加する必要はありません。

JSPタグを追加する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択し、「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: タグの名前を入力します。たとえば、tagPaneコンポーネントの場合、TagPaneTagと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.taglibと入力します。

- Class: org.apache.myfaces.trinidad.webapp.UIXComponentELTagと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

5. ソース・エディタで、ファイルにすべての属性を追加します。
例30-19に、TagPaneTagクラスの属性のコードを示します。

例30-19 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;

6. 属性のアクセッサ・メソッドを宣言的に生成するには、ソース・エディタでファイルを右クリックして、「アクセッサの生成」を選択します。

7. 「アクセッサの生成」ダイアログで「すべて選択」をクリックして、スコープをpublicに設定し、「OK」をクリックします。

8. レンダー・タイプとコンポーネント・タイプをクラスに追加します。コンポーネント・タイプは、アプリケーションのファクトリ・メソッド、createComponent(componentType)を使用してコンポーネントをインスタンス化するためにスーパー・クラスによって使用されます。
例30-20に、コンポーネント・タイプとレンダー・タイプがいずれもoracle.adfdemo.acme.TagPaneであるTagPaneTagクラスのコードを示します。

例30-20 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";

9. 単一の仮パラメータのタイプFacesBeanを持つスーパー・クラスからsetPropertiesメソッドをオーバーライドします。これは、ベースUIComponentELTagのMyFaces Trinidadバージョンですが、コンポーネント参照のかわりにコンポーネントの状態ホルダーが渡されます。setPropertiesメソッドの役割は、JSPタグ属性値をコンポーネントにプッシュすることです。
例30-21に、tagPaneTagクラスのオーバーライド・メソッドを示します。

例30-21 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);

}

30.4.10 タグ・ライブラリ・ディスクリプタの構成方法

タグ・ライブラリ・ディスクリプタ(TLD)は、Javaクラスの詳細をJSPコンパイル・エンジンとIDEツールに提供します(TLDは、Faceletsを使用するアプリケーションでは使用されません)。

作業を始める前に、次のようにします。

タグ・ライブラリをURIに関連付け、バージョンを割り当てて名前を付けます。この手順は、30.2.6項「JavaServer Pagesタグ・ライブラリ・ディスクリプタ・ファイルの追加方法」でタグ・ライブラリ・スタブ・ファイルを作成したときに実行されている必要があります。

TLDを構成する手順:

1. スケルトンTLDファイルを開きます。

2. コンポーネント・パレットから、tag要素をドラッグ・アンド・ドロップします。

3. 「タグの挿入」ダイアログで、次のように設定します。

- name: コンポーネントの名前を入力します。たとえば、tagPaneコンポーネントの場合、tagPaneと入力します。

- body-content: JSPと入力します。

- tag-class: 省略ボタンをクリックして、コンポーネントのタグ・クラス・ファイルに移動します。

4. 各属性を定義します。各属性に対して次のように設定します。

1. 構造ウィンドウで tag要素を右クリックし、「tag > attributeの中に挿入」と選択します。

2. 「属性の挿入」ダイアログで、名前の値を入力します。この名前はタグ・クラスで指定した名前と同一にする必要があります。

3. 構造ウィンドウで属性を選択し、プロパティ・インスペクタで属性の値を設定します。
各属性に定義する要素は3タイプあります。<id>要素は単純な文字列です。追加の属性は、deferred-value属性またはdeferred-method属性となります。これらにより、式を遅れて(deferred)評価できます。これで、JSPとJSFで同じELエンジンを共有するようになったため、コンパイル済のELをコンポーネントに直接渡すことができます。

例30-22に、tagPaneコンポーネントのTLDを示します。

例30-22 tagPaneのacme.tldタグ・ライブラリ・ディスクリプタ・コード

<?xml version = '1.0' encoding = 'UTF-8'?>
<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>

30.4.11 リソース・ローダーの作成方法

リソース・ローダーは、コンポーネントのスキニングに必要なイメージ・ファイルがカスタム・コンポーネントに含まれている場合のみ必要です。イメージ・ファイルはJARプロジェクトにパッケージ化されているため、コンポーネント・ライブラリのコンシューマは、JARをそのWebプロジェクトのクラス・パスに入れ、いくつかのエントリをそのWebデプロイ・ディスクリプタ・ファイル(web.xml)に追加する必要があります。リッチ・クライアント・フレームワークでは、リソース・サーブレットを使用してイメージが配信されます。web.xmlファイルにこのサーブレットを登録してから、リソース・ローダー・クラスを作成する必要があります。コンポーネント・ライブラリには、リソース・サーブレットで自動ロードされるリソース・ローダーが必要です。サーブレットのURLパターン・フォルダ・マッピングを作成します。これは、カスタム・コンポーネント・ライブラリ内でリソースを見つけて特定する場合に使用されます。

リソース・ローダー・クラスを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトを右クリックし、「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「Java」を選択します。

3. 「Javaクラス」を選択し、「OK」をクリックします。

4. Javaクラス・ファイルの作成ダイアログで、次のように設定します。

- 名前: リソース・ローダーの名前を入力します。たとえば、tagPaneコンポーネントの場合、AcmeResourceLoaderと入力します。

- パッケージ: パッケージの名前を入力します。たとえば、tagPaneコンポーネントの場合、oracle.adfdemo.acme.faces.resourcesと入力します。

- 拡張: タグで拡張するクラスの名前を入力します。たとえば、tagPaneコンポーネントの場合、org.apache.myfaces.trinidad.resource.RegexResourceLoaderと入力します。

- 「オプション属性」セクションで、次のように選択します。

- 「アクセス修飾子」セクションで、「public」を選択します。

- 下部で、「スーパークラスからのコンストラクタ」および「抽象メソッドの実装」を選択します。

5. ソース・エディタで、より具体的なリソース・ローダーにマップされる正規表現を登録します。たとえば、イメージ・ディレクトリの下にあるイメージ・リソースにマップする式を作成できます。
例30-23に、カスタム・コンポーネントJARの/META-INFフォルダと相対的な場所にある/acme/images/ディレクトリにマップするtagPaneコンポーネントの式を示します。登録すると、カスタム・コンポーネントのイメージは/META-INF/acme/imagesの下に配置されます。

例30-23 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"));

6. /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

30.4.12 MyFaces Trinidad Cascading Style Sheetの作成方法

スキンはCSS 3.0構文に基づくスタイルシートで、アプリケーション全体用に1箇所で指定されます。各ページのスタイルシートを挿入するかわりに、アプリケーション全体に対して1つ以上のスキンを使用します。各コンポーネントでは、スキンに記述されているスタイルが自動的に使用されます。設計時のコード変更は必要ありません。

ADF Facesには、アプリケーションで使用するスキンが3つ用意されています。

- blafplus-rich : ADF Facesコンポーネントのデフォルトのスタイルを定義します。このスキンは、blafplus-mediumスキンを拡張します。

- blafplus-medium : 適度な数のスタイル設定が提供されます。このスタイルは、simpleスキンを拡張します。

- simple : 最低限の書式設定のみが含まれています。

スキンには、標準のCSSスタイルやレイアウトを設定するよりも多くのオプションがあります。スキンのCSSファイルは、スキン・フレームワークによって処理され、スキン・プロパティとアイコンが抽出されてSkinオブジェクトに登録されます。スタイルシート・ルールには、要素を識別するスタイル・セレクタ、およびコンポーネントの外観を説明する一連のスタイル・プロパティが含まれます。

ADF Facesコンポーネントはすべてスキンを使用します。デフォルトのスキンは簡単なスキンです。カスタム・コンポーネントは、他のADF Facesコンポーネントとともに使用されるため、既存のADF Facesスキンにスタイル・セレクタを追加します。リッチ・スキンとミディアム・スキンは、簡単なスキンからスタイルを継承するので、セレクタを簡単なスキンに追加するだけで、すべてのスキンでそのセレクタを使用できるようになります。ただし、スキンごとにセレクタのスタイルを変えたい場合があります。そのようなスタイルは、作成したCSSファイルに設定します。このファイルは、コンポーネントが使用されるアプリケーションの他のCSSスタイルとマージされます。

スキンで使用されるテキストは、リソース・バンドル内で定義されます。カスタム・リソース・バンドルを作成してテキストを作成し、表示するテキストを宣言します。カスタム・リソース・バンドルを作成した後、スキンにそれを登録します。リソース・バンドルとCSSを組み合せることで、コンポーネントで複数のロケールをサポートするためのメソッドが提供されます。

作成した/META-INF/trinidad-skins.xmlファイルは、CSSファイルおよびリソース・バンドルをADF Facesスキンに登録するために使用されます。

コンポーネントのスタイルを作成する手順:

1. 30.2.4項「Cascading Style Sheetの追加方法」で作成したCSSファイルを開きます。

2. コンポーネントのルート・スタイル・セレクタを定義します。このスタイルは、コンポーネントを確立する<DIV>要素と関連付けられます。

3. 必要に応じてその他のスタイル・セレクタを追加します。例30-24に、tagPaneコンポーネントのCSSファイルを示します。

例30-24 tagPaneコンポーネントのCSSファイル

acme|tagPane          -  root element
acme|tagPane::content -  container for the links
acme|tagPane::tag - tag hyperlink

スキンで使用される、コンポーネントのCSSの作成の詳細は、20.3項「スキン・スタイル・プロパティの定義」を参照してください。

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など)でも使用可能です。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

- style-sheet-name: ドロップダウン・メニューを使用して「編集」を選択し、作成したCSSファイルに移動します。

7. リソース・バンドルを作成している場合は、バンドルの完全修飾パスを<bundle-name>要素の値として追加します。
例30-25に、tagPaneコンポーネントのコードを示します。

例30-25 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です。

30.5 コンポーネント・ライブラリのデプロイ

カスタム・コンポーネント・ライブラリを作成したら、Webアプリケーションで使用できるデプロイ可能なアーティファクトを作成する必要があります。Javaアーカイブ(JAR)ファイルを作成できるようにするには、作成した多くのリソースを追加して、プロジェクトのデプロイメント・プロファイルを更新する必要があります。

デプロイメントのJARファイルを作成する手順:

1. アプリケーション・ナビゲータで、プロジェクトをダブルクリックし、「プロジェクト・プロパティ」ダイアログを開きます。

2. 左ペインで、「コンパイラ」を選択します。

3. 右側で、デプロイするすべてのファイル・タイプが「ファイル・タイプの出力ディレクトリへのコピー」テキスト・フィールドにリストされるようにします。

注意:

.cssや.jsなどの一部のファイル・タイプは、デフォルトで含まれません。これらを追加する必要があります。

4. 左ペインで、「デプロイ」を選択します。

5. 右側の「Deployment Profiles」で、「ADFライブラリのJARファイル」を選択して、「編集」をクリックします。

6. 左ペインで、「JARオプション」を選択します。

7. ADFライブラリのJARファイルを格納するためのデフォルトのディレクトリ・パスを確認するか、新規パスを入力します。「Manifestファイルを含める」が選択されていることを確認して、「OK」をクリックします。

8. デプロイするには、プロジェクトを右クリックし、ポップアップ・メニューから「デプロイ」→Project_nameを選択します。デフォルトでは、プロジェクト・ディレクトリ内のデプロイメント・ディレクトリにJARファイルがデプロイされます。

30.6 アプリケーションへのカスタム・コンポーネントの追加

コンポーネントを作成し、ADFライブラリを作成すると、そのコンポーネントを別のアプリケーションにインポートして使用できるようになります。ただし、開発中のアプリケーションでコンポーネントを使用する前には、テスト・アプリケーションで使用してコンポーネントが予想どおりに機能することを確認する必要があります。テストするには、カスタム・ライブラリをテスト・アプリケーションにインポートします。手順は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』のプロジェクトへのADFライブラリ・コンポーネントの追加に関する項を参照してください。

ライブラリを追加したら、Webデプロイメント・ディスクリプタを構成して、リソース・サーブレット・マッピングを追加します。コンポーネントを使用してテスト・アプリケーションを実行すると、コンポーネントのデバッグが必要であることがわかる場合があります。そのため、プロジェクトに対してロギングとアサーションを有効にしておくと役立ちます。

ヒント:

ライブラリをアプリケーションにインポートすると、JDeveloperのコンポーネント・パレットにカスタム・コンポーネントを表示できます。

30.6.1 Webデプロイメント・ディスクリプタの構成方法

コンポーネント・リソース・ローダーは、サーブレット・リソース・マッピングを前提とするように構成されています(たとえば、tagPaneコンポーネントの場合、マッピングはacmeです)。そのため、想定されるリソース・サーブレット・マッピングを使用アプリケーションのweb.xmlファイルに追加する必要があります。

デフォルトでは、MyFaces Trinidadのスキニングでは、CSS 3をCSS 2に正規化するときに、CSSクラスが圧縮されます。コンポーネントのデバッグ時にはこの圧縮を無効にします。本番のデプロイメントでは、この設定を無効に切り替えます。

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と入力します。

30.6.2 JavaScriptロギングとアサーションを有効にする方法

JavaScriptデバッグは難しいタスクです。この動的言語の型確認なしでのデバッグをサポートするために、リッチ・クライアントJavaScriptライブラリには、Javaロギングに似たロギング・メカニズムが用意されています。クライアント・スクリプトをより型保証されたスクリプトにするアサーション・ストラテジもあります。これらの機能はいずれも、web.xmlファイルの構成パラメータを使用して有効にします。ロギング・ルーチンとアサーション・ルーチンはブラウザ固有です。クライアントJavaScriptライブラリでは、Gecko、Internet Explorer、OperaおよびSafariバージョンのブラウザ・エージェントがサポートされます。詳細は、A.2.3.4項「リソース・デバッグ・モード」を参照してください。

ロギングとアサーションを有効にする手順:

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コンソールから使用できます。

30.6.3 JSFページへのカスタム・コンポーネントの追加方法

カスタム・コンポーネントをJSFページに追加する手順:

1. ソース・エディタでjspxページを開きます。

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>

30.6.4 tagPaneカスタム・コンポーネントの使用について

この章の説明に従ってtagPaneコンポーネントを作成し、アプリケーションで使用する場合、バッキングBeanを使用して、カスタム・コンポーネントをアプリケーション・コンポーネントにバインドする必要があります。

例30-26に、tagPaneコンポーネントをFile Explorerアプリケーションにバインドするために使用されるバッキングBeanのコードを示します。

例30-26 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);

}

31 JSFページでのユーザー・カスタマイズの許可

この章では、実行時に特定のUIにユーザーが行った変更をセッションの間永続させる方法について説明します。

また、変更が永続データ・リポジトリ内で永続されるようにアプリケーションを構成することもできます。そのように構成することで、アプリケーションを再度使用するときに変更内容が残っていることになります。この永続性を許可するには、完全Fusionテクノロジ・スタックの一部であるOracle Metadata Service(MDS)を使用する必要があります。MDSおよび完全Fusionスタックを使用することで、次の追加の永続性機能も提供されます。

- 追加の属性値の永続

- 検索条件の永続

- UIのドラッグ・アンド・ドロップ操作の結果の永続

- 実行時のページ上のコンポーネントの並替え

- 実行時のページのコンポーネントおよびファセットの追加と削除

Oracle MDSを使用するための詳細および手順は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「実行時のユーザー・カスタマイズの許可」の章を参照してください。

この章では、次の項目について説明します。

- 31.1項「ユーザー・カスタマイズの概要」

- 31.2項「セッション変更永続性の実装」

31.1 ユーザー・カスタマイズの概要

多くのADF Facesコンポーネントで、ユーザーは実行時にコンポーネントの表示を変更できます。たとえば、ユーザーは、panelSplitterコンポーネントのスプリッタの位置を変更したり、パネルに詳細コンテンツを表示するかどうかを変更できます。デフォルトでは、これらの変更はページ・リクエストの間有効です。ユーザーがページを終了して再度表示すると、コンポーネントはデフォルトの構成で表示されます。ただし、変更がユーザーのセッションの間永続するようアプリケーションを構成できます。このようにすると、ユーザーがアプリケーションを終了するまで、変更されたままになります。

表31-1に、デフォルトのパーソナライズ機能を提供するコンポーネントごとの変更を示します。

表31-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ポップアップ・コンポーネントの幅を変更でき、その幅は保持されます。

activeCommandToolbarButton

commandButton

commandImageLink

commandLink

commandMenuItem

commandNavigationItem

commandToolbarButton

windowHeight

ユーザーがpanelWindowまたはdialogコンポーネントのcontentHeight属性の値を変更する場合、コマンド・コンポーネントの関連するwindowHeightの値も変更され、保持されます。

activeCommandToolbarButton

commandButton

commandImageLink

commandLink

commandMenuItem

commandNavigationItem

commandToolbarButton

windowWidth

ユーザーがpanelWindowまたはdialogコンポーネントのcontentWidth属性の値を変更する場合、コマンド・コンポーネントの関連するwindowWidthの値も変更され、保持されます。

column

displayIndex

ADF Faces列は、ユーザーが実行時に並べ替えることができます。displayIndex属性によって、列の順序が決まります。(デフォルトでは、各列の値は-1に設定され、データ・ソースと同じ順序で列が表示されます)。ユーザーが列を移動すると、新しい順序を反映するよう各列の値が変更されます。これらの新しい値は永続します。

column

frozen

ADF Faces列は、スクロールされないように固定できます。列のfrozen属性をtrueに設定すると、その列の前のすべての列(displayIndex値に基づく)がスクロールしません。panelCollectionコンポーネントで表を使用する場合、ユーザーが列を固定できるボタンが表示されるようにその表を構成できます。詳細は、10.2.4項「ページへの表の表示方法」を参照してください。

column

noWrap

列のコンテンツを折り返すかどうかを指定します。ユーザーがこの属性値を変更できるようにするコードを作成する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるポップアップ・メニューを作成します。

column

selected

選択された列は、ユーザーが最後に選択した列に基づきます。

column

visible

ユーザーの直近のアクションに基づいて、列が表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるポップアップ・メニューを作成します。

column

width

列の幅が、ユーザーが最後に設定したサイズのままになります。

table

filterVisible

ADF Facesの表には、ユーザーが属性値で表の行をフィルタ処理できるコンポーネントを含めることができます。フィルタを使用するよう構成されている表では、ユーザーの直近のアクションに基づいて、フィルタは表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値をtrueからfalseに切り替えることができるボタンを作成します。

table

first

この属性は、現在の行範囲の最初の行の索引を表し、表示する行範囲の制御に使用されます。この属性の値は、RangeChangeEventに反応して、またスクリーン・リーダー・モードの場合のみ保持されます。

31.2 セッション変更永続性の実装

ユーザーによるセッションへの変更をアプリケーションで永続させるには、カスタマイズが有効になるようプロジェクトを構成する必要があります。

31.2.1 セッション変更永続性の実装方法

web.xmlファイルでのカスタマイズが有効になるようアプリケーションを構成します。

セッション変更永続性を実装する手順:

1. アプリケーション・ナビゲータで、Webプロジェクトをダブルクリックします。

2. 「プロジェクト・プロパティ」ダイアログで、「ADFビュー」ノードを選択します。

3. 「ADFビュー」ページで、「ユーザー・カスタマイズの有効化」チェック・ボックスをアクティブにし、「セッションの継続時間」ラジオ・ボタンを選択して、「OK」をクリックします。

31.2.2 変更永続性を使用するようアプリケーションを構成する場合の処理

セッションへの変更を保存するよう選択すると、JDeveloperでCHANGE_PERSISTENCEコンテキスト・パラメータがweb.xmlファイルに追加され、値がsessionに設定されます。このコンテキスト・パラメータでは、永続性の処理に使用されるChangeManagerクラスが登録されます。例31-1に、web.xmlファイルのコンテキスト・パラメータを示します。

例31-1 変更の永続に使用されるweb.xmlのコンテキスト・パラメータ

<context-param>
<param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
<param-value>session</param-value>
</context-param>

31.2.3 実行時の処理

セッションへの変更を永続させるようアプリケーションを構成している場合、ビューIDに従って索引付けされたデータ構造内のセッション変数に変更が記録されます。後続の表示またはビューのリストア・フェーズでページがリクエストされるたびに、指定されたコンポーネントに対する変更がタグ・アクション・クラスで検索され、追加されたときと同じ順序で変更が適用されます。つまり、セッションの間に登録された変更は、同じセッションの後続のリクエストでのみ適用されます。

31.2.4 テンプレートおよび領域での変更永続性の使用について

セッション永続性を使用する場合、変更は、指定セッションのviewIdと照合してコンポーネントで記録およびリストアされます。その結果、フラグメントまたはページ・テンプレートに属するコンポーネントで変更が適用される場合、その変更は、フラグメントまたはテンプレートを使用するページの範囲でのみ適用可能です。これは、フラグメントまたはテンプレートを使用するすべてのページが対象となるわけではありません。たとえば、プロジェクトにJSFページpageOne.jspxとpageTwo.jspxがあり、この両方に、region.jsffページ・フラグメントで定義されたフラグメントが含まれるとします(同様にshowDetailコンポーネントを含む)。JSFページpageOne.jspxがレンダリングされ、showDetailコンポーネントのdisclosed属性が変わる場合、暗黙的な属性の変更が記録され、pageOne.jspxページにのみ適用されます。ユーザーがpageTwo.jspxページに移動しても、属性の変更は適用されません。

32 ドラッグ・アンド・ドロップ機能の追加

この章では、ページにドラッグ・アンド・ドロップ機能を追加する方法について説明します。これにより、コンポーネントの属性やオブジェクトの値を別のコンポーネントにドラッグしたり、コンポーネントをドラッグ・アンド・ドロップしたりすることができます。

この章では、次の項目について説明します。

- 32.1項「ドラッグ・アンド・ドロップ機能の概要」

- 32.2項「属性のドラッグ・アンド・ドロップ機能の追加」

- 32.3項「オブジェクトのドラッグ・アンド・ドロップ機能の追加」

- 32.4項「コレクションのドラッグ・アンド・ドロップ機能の追加」

- 32.5項「コンポーネントのドラッグ・アンド・ドロップ機能の追加」

- 32.6項「panelDashboardコンポーネントに対するドラッグ・アンド・ドロップ機能の追加」

- 32.7項「Calendarへのドラッグ・アンド・ドロップ機能の追加」

- 32.8項「DVTグラフのドラッグ・アンド・ドロップ機能の追加」

- 32.9項「DVTガント・チャートのドラッグ・アンド・ドロップ機能の追加」

32.1 ドラッグ・アンド・ドロップ機能の概要

ADF Facesフレームワークでは、1つのページ上で、ある場所から別の場所にアイテムをドラッグ・アンド・ドロップする機能が提供されます。たとえば、ファイル・エクスプローラ・アプリケーションでは、図32-1に示すように、「表」タブからファイルをドラッグして、別のディレクトリのフォルダにドロップできます。

図32-1 ファイル・エクスプローラ・アプリケーションでのドラッグ・アンド・ドロップ

このシナリオでは、あるコレクション(Folder0)のオブジェクトを実際にドラッグして、別のコレクション(Folder3)にドロップします。これは、サポートされている数多くのドラッグ・アンド・ドロップ・シナリオの1つです。ADF Facesでは、次のシナリオがサポートされます。

- あるコンポーネント・インスタンスの属性値をドラッグして、別のインスタンスにコピーします。たとえば、ユーザーはoutputTextコンポーネントをinputTextコンポーネントにドラッグできます。ドラッグすると、outputTextコンポーネントのtext属性の値がinputTextコンポーネントのtext属性の値になります。

- あるオブジェクトの値が別のオブジェクトの値になるように、値をドラッグしてドロップします。たとえば、outputTextコンポーネントを別のoutputTextコンポーネントにドラッグできます。ドラッグすると、Stringオブジェクトの配列が2番目のoutputTextコンポーネントのtext属性に移入されます。

- 図32-1に示すように、あるコレクションのオブジェクトをドラッグして別のコレクションにドロップします。

- 1つのページ上で、ある場所から別の場所にコンポーネントをドラッグします。たとえば、既存のpanelBoxコンポーネントを、panelGridコンポーネント内の新しい場所にドラッグできます。

- カレンダのアクティビティを、ある開始日時から別の開始日時にドラッグします。

- コンポーネントをpanelDashboardコンポーネントに(から)ドラッグします。

- DVT散布図またはバブル・グラフのマーカーをドラッグして、その値を変更します。

- DVTガント・チャートのオブジェクトを別のコンポーネントにドラッグします。

ユーザーがソースをクリックしてドラッグを開始すると、ブラウザには、マウス・ポインタに付属するゴースト要素として、ドラッグする要素が表示されます。ゴースト要素が有効なターゲット上に来ると、ターゲット・コンポーネントには、いくつかのフィードバック(強調表示など)が表示されます。ゴースト要素を無効なターゲット上にドラッグすると、カーソルが変わり、ターゲットが無効であることが示されます。

属性値をドラッグする場合、ターゲットへの値のコピーのみが可能です。他のドラッグ・アンド・ドロップ・シナリオの場合、ドロップでは、要素のコピー(コピーして貼付け)、移動(切り取って貼付け)、リンク(コピーしてリンクとして貼付け(テキストをコピーして実際のURLとして貼付けなど))が可能です。

ドラッグするコンポーネントで、値が含まれるものをソースと呼びます。ドロップを受け入れるコンポーネントをターゲットと呼びます。ドロップの許可をフレームワークに指示する特定のタグを、ソース・コンポーネントとターゲット･コンポーネントの子として使用します。表32-1に、様々なドラッグ・アンド・ドロップのシナリオ、有効なソースとターゲット、該当のシナリオに使用する関連タグを示します。

表32-1 ドラッグ・アンド・ドロップのシナリオ

シナリオ

ソース

ターゲット

属性値のドラッグ

コンポーネントの属性値

別のコンポーネントの属性値(同じオブジェクト・タイプに限る)

タグ:
attributeDragSource

タグ:
attributeDropTarget

あるコンポーネントから別のコンポーネントへのオブジェクトのドラッグ

任意のコンポーネント

任意のコンポーネント

タグ:
attributeDragSource

タグ:
dropTarget

あるコレクションのアイテムをドラッグして別のコレクションにドロップ

table、treeおよびtreeTableコンポーネント

table、treeおよびtreeTableコンポーネント

タグ:
dragSource

タグ:
collectionDropTarget

あるコンテナから別のコンテナへのコンポーネントのドラッグ

任意のコンポーネント

任意のコンポーネント

タグ:
componentDragSource

タグ:
dropTarget

ある開始時間または開始日から別の開始時間または開始日へのカレンダ・アクティビティのドラッグ

calendarActivityオブジェクト

calendarコンポーネント

タグ:
不要

タグ:
calendarDropTarget

panelBoxコンポーネントのpanelDashboardコンポーネントへのドラッグ

panelBoxコンポーネント

panelDashboardコンポーネント

タグ:
componentDragSource

タグ:
dataFlavor

panelBoxコンポーネントのpanelDashboardコンポーネントからのドラッグ

panelDashboardコンポーネントのpanelBoxコンポーネント

任意のコンポーネント

タグ:
componentDragSource

タグ:
dropTarget

DVTグラフのマーカーのドラッグ

graphコンポーネント

graphコンポーネント

タグ:
dragSource

タグ:
dropTarget

DVTガント・チャートのオブジェクトをドラッグして別のコンポーネントにドロップ

ガント・チャート

任意のコンポーネント

タグ:
dragSource

タグ:
dropTarget

ターゲットにドロップできるオブジェクトのタイプを制限するには、dataFlavorタグを追加します。これは、ターゲットで受入れ可能なオブジェクト・タイプを1つのみにする場合に役立ちます。ただし、ソースは各種タイプのうちのいずれかになります。dataFlavorタグでは、ターゲットで複数のソースまたは複数の型を含む可能性のあるソースからオブジェクトを受け入れることができるよう、複数の型を設定することもできます。ドロップが成功するには、ターゲットとソースの両方にdataFlavorタグを含め、値が同じである必要があります。

注意:

ドラッグ・アンド・ドロップ機能は、ウィンドウ間ではサポートされていません。ウィンドウ境界を越えるドラッグは取り消されます。ポップアップ・ウィンドウとポップアップのベース・ページとの間のドラッグ・アンド・ドロップ機能はサポートされています。

ドラッグ・アンド・ドロップ機能は利用できない点にも注意してください。つまり、ドラッグ・アンド・ドロップの実行に使用できるキーボード・ストロークはありません。したがって、アプリケーションですべての機能を利用できるようにする場合、このロジックを備える必要があります。たとえば、使用するページに、オブジェクトを選択するメソッドと、選択したオブジェクトを移動できる移動ボタンやメニュー・アイテムを表示することもできます。

32.2 属性のドラッグ・アンド・ドロップ機能の追加

属性のドラッグ・アンド・ドロップ機能は、あるコンポーネントの属性をターゲットとして定義し、別のコンポーネントの属性をソースとして定義して追加します。

注意:

ターゲットとソースの属性値は同じデータ型である必要があります。

次の手順では、ターゲットとソースのコンポーネントはJSFページにすでにあるものとします。

属性のドラッグ・アンド・ドロップ機能を追加する手順:

1. コンポーネント・パレットの「操作」パネルで、「属性ドロップ・ターゲット」をターゲット・コンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「属性ドロップ・ターゲットの挿入」ダイアログで「属性」ドロップダウンを使用して、ドラッグ・アンド・ドロップ・アクションによる移入先の属性を選択します。このドロップダウン・リストには、ターゲット・コンポーネントの有効な属性がすべて表示されます。

3. ターゲットへの値の代入元のコンポーネントの子として、属性ドラッグ・ソースをコンポーネント・パレットからドラッグ・アンド・ドロップします。

4. 「属性ドラッグ元の挿入」ダイアログで「属性」ドロップダウンを使用して、ターゲット属性への移入に使用される値の属性を選択します。このドロップダウン・リストには、ソース・コンポーネントの有効な属性がすべて表示されます。

32.3 オブジェクトのドラッグ・アンド・ドロップ機能の追加

ユーザーが属性値以外をドラッグできるようにする場合、またはあるコンポーネントから別のコンポーネントへ属性をコピーする以外の操作をユーザーができるようにする場合、dropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます。ドロップ・ターゲットとドラッグ・ソースが複数ある場合のために、識別値を使用して有効な組合せを制限できます。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。

たとえば、図32-6に示すように、outputTextコンポーネントがあり、ユーザーがoutputTextコンポーネントをpanelBoxコンポーネントにドラッグできるようにし、そのコンポーネントにarrayを表示するとします。

図32-2 配列オブジェクトのドラッグ・アンド・ドロップ

outputTextコンポーネントにはattributeDragSourceタグが含まれます。ただし、(属性のString値のみでなく)arrayをドラッグするため、attributeDropTargetタグではなくdropTargetタグを使用する必要があります。また、dataFlavorタグを使用してarrayオブジェクトのみがターゲットで受け入れられるようにします。

dataFlavorタグの識別値の定義もできます。同じオブジェクト型の2つのターゲットと2つのソースがある場合に、これは有用です。識別値を作成することで、各ターゲットで有効なソースのみが受け入れられることが保証されます。たとえば、EMPLOYEEオブジェクトを受け入れるTargetAとTargetBの2つのターゲットがあるとします。EMPLOYEEオブジェクトのソースも2つあるとします。TargetAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つEMPLOYEEソースのみが受け入れられます。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはtransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはtransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。このリスナーの詳細は、32.9.1項「DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加方法」の手順で説明します。

32.3.1 単一オブジェクトのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、まず、コンポーネントをドラッグ・アンド・ドロップ・アクションのターゲットとして定義するタグをコンポーネントに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。

この手順では、ソースとターゲットのコンポーネントはすでにページあるものとします。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. ターゲットを含むJSFページで、コンポーネント・パレットから(「操作」パネルにある)「ドロップ・ターゲット」タグをドラッグ・アンド・ドロップし、dropTargetタグをターゲット・コンポーネントの子として追加します。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ5で作成)に評価される式を入力します。

ヒント:

clientDropListener属性を挿入して、クライアントでドロップを捕捉することもできます。詳細は、32.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です。

例32-1に、panelBoxコンポーネントに挿入され、配列オブジェクトをドロップ・ソースとするdropTargetコンポーネントのコードを示します。アクションが定義されていないため、許可されるアクションはCOPYのみであることに注意してください。

例32-1 dropTargetタグのJSPコード

<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、and 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が受け入れられる場合、転送可能オブジェクトにjava.util.ArrayListを含むドロップは正常終了します。同様に、この機能ではArraysとListsとの間の自動変換もサポートされます。

ドラッグ・アンド・ドロップ・フレームワークで、サーバーのDataFlavorオブジェクトをクライアント・コンポーネントで表す方法がわからない場合、すべてのドロップがクライアントで正常終了するようドロップ・ターゲットが構成されます。

例32-2に、イベント・ハンドラ・メソッドが呼び出すprivateメソッドを示します(イベント・ハンドラ自体はこのメソッドの呼出しのみを行います。このメソッドではpanelBoxコンポーネントのoutputTextコンポーネントの値になるStringパラメータも必要になるため、イベント・ハンドラが必要になります)。このメソッドは、イベント・ペイロードから配列オブジェクトをコピーして、イベントを開始したコンポーネントに割り当てます。

例32-2dropListenerのイベント・ハンドラ・コード

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;
}
}

6. コンポーネント・パレットから(「操作」パネルにある)クライアント属性をドラッグしてclientAttributeタグをソース・コンポーネントの子として追加します。このタグは、イベントに対するソースのペイロードの定義に使用されます。プロパティ・インスペクタで、clientAttributeタグに次の定義を行います。

- 名前: ペイロードの名前を入力します。

- 値: ペイロードの値と評価されるEL式を入力します。飲み物を例とすると、これは異なる飲み物の値を含むArrayに解決されます。

7. ソース・コンポーネントの別の子として、パレットから(「操作」パネルにある)属性ドラッグ・ソースをドラッグ・アンド・ドロップします。「属性ドラッグ・ソースの挿入」ダイアログで、前述の手順で作成したclientAttributeタグに定義するnameをドロップダウン・リストから選択します。これにより、clientAttributeタグの値がソースのペイロードになります。例32-3に、ドラッグ・アンド・ドロップ操作のソースであるoutputTextコンポーネントのコードを示します。

例32-3 ドラッグ・ソースのJSPコード

<af:outputText value="Drag to see drinks">
<af:clientAttribute name="drinks" value="#{myBean.drinks}"/>
<af:attributeDragSource attribute="drinks"/>
</af:outputText>

32.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になります。これは、変更子を選択しない場合のデフォルトがCOPYであるためです(順序の最初)。[Ctrl]キーを押す場合、その変更子はCOPYと一致するためCOPYが実行されます。[Ctrl]+[Shift]キーを押した場合、アクションはCOPYのままです。これは、その変更子が、許可されるアクションの共通セット内にないLINKアクションと一致するためです。

注意:

JavaとJavaScriptとの間のラウンドトリップで情報が失われるため、ドロップでのデータが見込みとは異なる型の場合があります。たとえば、すべての数値型はdoubleオブジェクトとして、charオブジェクトはStringオブジェクトとして、ListオブジェクトとArrayオブジェクトはListオブジェクトとして、その他の大部分のオブジェクトはMapオブジェクトとして表されます。詳細は、5.4.3項「データのマーシャリングとアンマーシャリングについて」を参照してください。

32.3.3 ClientDropListenerの使用について

dropTargetタグには、クライアントでドロップ・イベントを処理するJavaScriptを参照できるclientDropListner属性が含まれます。クライアント・ハンドラは、パラメータを取らず、AdfDnDContextアクションを返します。たとえばメソッドがAdfDnDContext.ACTION_NONEを返すと、ドロップ操作は取り消され、サーバーでコールされません。メソッドがAdfDnDContext.ACTION_COPYを返すと、コピー操作が許可され、dropListenerメソッドが存在する場合には、それを実行するコールがサーバーで発生します。

たとえば、ドロップ・イベントの起動時にメッセージをログ出力するとします。メッセージの出力を処理し、サーバー・リスナーが起動されるよう適切なアクションを返すクライアント・ハンドラを作成します。例32-4に、メッセージの出力にロガーを使用するクライアント・ハンドラを示します。

例32-4 clientDropListenerハンドラ

<script>
/**
* Shows a message.
*/
function showMessage()
{
AdfLogger.LOGGER.logMessage(AdfLogger.ALL, "clientDropListener handler,
copying...");
return AdfDnDContext.ACTION_COPY;
}
</script>

32.4 コレクションのドラッグ・アンド・ドロップ機能の追加

collectionDropTargetおよびdragSourceタグを使用して、ユーザーがコレクションからアイテム(表から行など)をドラッグし、ツリーなどの別のコレクション・コンポーネントにドロップできるドラッグ・アンド・ドロップ機能を追加します。たとえば、File Explorerアプリケーションでは、ユーザーは、ディレクトリの内容を表示する表からディレクトリ・ツリーのフォルダにファイルをドラッグできます。図32-3に、Folder0ディレクトリの内容を表示する表からFolder3ディレクトリにドラッグされるFile0.docオブジェクトを示します。ドロップが完了すると、オブジェクトはFolder3を構成するコレクションの一部になります。

図32-3 ファイル・エクスプローラ・アプリケーションでのドラッグ・アンド・ドロップ機能

単一オブジェクトのドラッグ・アンド・ドロップ同様、ドロップによってコピー、移動またはコピーしてリンクとして貼り付けたり(あるいは3つを組み合せたり)、dataFlavorタグを使用してターゲットでの受け入れ対象を限定できます。

ターゲット・ソースがコレクションで、移動操作をサポートする場合、dragDropEndListener属性のメソッドも実装できます。これは、ソース・コンポーネントから参照され、ドラッグ・アンド・ドロップ操作後のコレクションの削除に使用されます。詳細は、32.4.2項「dragDropEndListenerについて」を参照してください。

32.4.1 コレクションのドラッグ・アンド・ドロップ機能の追加方法

コレクションのドラッグ・アンド・ドロップ機能を追加するには、dropTargetタグを使用するかわりにcollectionDropTargetタグを使用します。その後、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装する必要があります。次に、dragSourceタグを使用して、ドラッグ・アンド・ドロップ操作のソースを定義します。

この手順では、ソースとターゲットのコンポーネントはすでにページあるものとします。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. コンポーネント・パレットからコレクション・ドロップ・ターゲットをドラッグし、collectionDropTargetタグをターゲット・コレクション・コンポーネントの子として追加します。

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を返して、ドロップが拒否されたことを示します。

例32-5に、2つの表の間で行のコピーを処理するcollectionDropTargetデモに使用されるCollectionDnd.javaマネージドBeanのイベント・ハンドラ・メソッドを示します。

例32-5 コレクションのdropListenerのイベント・ハンドラ・コード

public DnDAction handleDrop(DropEvent dropEvent)
{
Transferable transferable = dropEvent.getTransferable();

// The data in the transferable is the row key for the dragged component.
DataFlavor<RowKeySet> rowKeySetFlavor =
DataFlavor.getDataFlavor(RowKeySet.class, "DnDDemoModel");
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.
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().add(dnDDemoData);
}
return dropEvent.getProposedAction();
}
else
{
return DnDAction.NONE;
}
}

5. コンポーネント・パレットの「操作」パネルで、「ドラッグ元」をソース・コンポーネントの子としてドラッグ・アンド・ドロップします。

6. dragSourceタグを選択している場合、プロパティ・インスペクタで、ターゲットに構成される、許容アクションと必要な識別値を設定します。

32.4.2 dragDropEndListenerについて

ドロップ・イベントの後でソース・コレクションをクリーンアップする必要がある場合が考えられます。たとえば、ドラッグで移動を行った場合、移動した項目がコレクションの一部ではなくなるように、ソース・コンポーネントをクリーンアップする必要があることがあります。

dragSourceタグには、ドラッグ・アンド・ドロップ操作の終了後のロジックを含むハンドラを登録できるdragDropEndListener属性が含まれます。

たとえば、ドラッグ・アンド・ドロップでオブジェクトを移動する場合、ドロップの正常終了後にソース・コンポーネントからオブジェクトを物理的に削除する必要があります。例32-6に、dragDropEndListener属性のハンドラを示します。

例32-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 dta from the source model directly.
Object removed = getSource2Values().remove(currKey.intValue());
}
// Need to add the drag source table so it gets redrawn.
AdfFacesContext.getCurrentInstance().addPartialTarget(dropEvent.getDragComponent());

32.5 コンポーネントのドラッグ・アンド・ドロップ機能の追加

ある親から別の親へのコンポーネントの移動を可能にしたり、親コンポーネントの子コンポーネントの並替えを可能にできます。例として、図32-4に、panelGridコンポーネントの最初の子で最後に移動される暗色のpanelBoxコンポーネントを示します。

図32-4 コンポーネント間のドラッグ・アンド・ドロップ機能

注意:

panelDashboardコンポーネントにコンポーネントを移動したり、このコンポーネントから移動したりする場合、該当コンポーネントに固有の手順を使用する必要があります。詳細は、32.6項「panelDashboardコンポーネントに対するドラッグ・アンド・ドロップ機能の追加」を参照してください。

32.5.1 コンポーネントのドラッグ・アンド・ドロップ機能の追加方法

コンポーネントに対するドラッグ・アンド・ドロップ機能の追加は、オブジェクトに対するものと同様です。ただし、attributeDragSourceタグを使用するかわりにcomponentDragSourceタグを使用します。オブジェクトまたはコレクションのドラッグ・アンド・ドロップ同様、dropListenerハンドラを実装する必要もあります。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. コンポーネント・パレットの「操作」パネルで、「ドロップ・ターゲット」をターゲット・コンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ4で作成)に評価される式を入力します。

3. dropTargetタグを選択した状態のまま、プロパティ・インスペクタでaction属性に有効なアクション・セットを選択します。

4. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

このメソッドは、DropEventイベントをパラメータとして取り、DnDActionを返す必要があります。これは、ソースのドロップ時に実行されるアクションです。有効な戻り値は、DnDAction.COPY、DnDAction.MOVE、DnDAction.LINKであり、これらは手順2でターゲット属性を定義したときに設定されています。

このハンドラ・メソッドは、DropEventイベントを使用してtransferableオブジェクトとそのデータを取得してから、移動またはコピーを完了し、コンポーネントの順序を必要に応じて並べ替えます。メソッドがドロップを完了すると、実行されたDnDActionを返します。それ以外の場合、ドロップが拒否されたことを示すDnDAction.NONEを返します。

例32-7に、デモ・アプリケーションのcomponentDragSource JSFページで使用されるDemoDropHandler.javaマネージドBeanのhandleComponentMoveイベント・ハンドラを示します。

例32-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;
ComponentChange change;

// 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))
{
reorderedIdList.add(currId);
if (currId.equals(dropLayoutId))
{
reorderedIdList.add(movedLayoutId);
}
}
}

change = new ReorderChildrenComponentChange(reorderedIdList);
rootParent = dropParent;
// 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タグをソース・コンポーネントに追加します。

32.6 panelDashboardコンポーネントに対するドラッグ・アンド・ドロップ機能の追加

デフォルトでは、panelDashboardコンポーネントは、その中にあるコンポーネントのドラッグ・アンド・ドロップをサポートします。つまり、リスナーを実装したり、追加タグを使用したりせずにpanelDashboardコンポーネント内のコンポーネントを並べ替えることができます。ただし、コンポーネントをpanelDashboardコンポーネントにドラッグできるようにする場合やpanelDashboardコンポーネントからコンポーネントをドラッグできるようにする場合、タグを使用してリスナーを実装する必要があります。コンポーネントをドラッグ・アンド・ドロップするため、panelDashboardにドラッグする場合はcomponentDragSourceタグを使用します。ただし、panelDashboardはドロップ・ターゲットをすでにサポートしているため、dropTargetタグを使用する必要はありません。かわりに、dataFlavorタグと識別値を使用する必要があります。タグと識別値は、ドロップが外部コンポーネントからのものであることをフレームワークに通知します。

panelDashboardからのコンポーネントのドラッグは、他のコンポーネントのドラッグ・アンド・ドロップとほぼ同じです。ターゲットにdropTargetタグを使用し、ソースにcomponentDragSourceタグを使用します。ただし、dataFlavorタグと識別値も使用する必要があります。

32.6.1 panelDashboardコンポーネントへのドラッグ・アンド・ドロップ機能の追加方法

panelDashboardコンポーネントには、ダッシュボード内のpanelBoxコンポーネントの並替えに使用されるドラッグ・アンド・ドロップ機能が組み込まれているため、dropTargetタグは使用できませんが、dataFlavorタグと識別値を使用してdropListenerを実装する必要があります。この実装では、コンポーネントの並替えを処理する必要があります。

作業を始める前に、次のようにします。

1. panelDashboardコンポーネントを作成します。詳細は、8.7項「ダッシュボードでのコンテンツの配置」を参照してください。

2. panelBoxコンポーネントを含むpanelDashboardから別のコンポーネントを作成します。panelBoxコンポーネントの詳細は、8.8.3項「panelBoxコンポーネントの使用方法」を参照してください。

panelDashboardコンポーネントへのドラッグ・アンド・ドロップ機能の追加手順:

1. 構造ウィンドウで、ターゲット・コンポーネントになるpanelDashboardコンポーネントを選択します。

2. プロパティ・インスペクタで、ドロップ・イベント(手順6でこのコードを作成)を処理するマネージドBeanのメソッドに評価される式をDropListenerに入力します。

3. コンポーネント・パレットの「操作」パネルで、「データ・フレーバ」をドラッグし、panelDashboardコンポーネントの子としてドロップします。

4. 「データ・フレーバの挿入」ダイアログで、javax.faces.component.UIComponentと入力します。

5. プロパティ・インスペクタで、panelDashboardコンポーネントにドラッグできるコンポーネント(dragIntoDashboardなど)を識別する識別値を一意の名前に設定します。

6. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

このメソッドは、DropEventイベントをパラメータとして取り、DnDActionのNONEを返す必要があります。これは、panelDashboardがその子コンポーネントの位置を処理するためです。

このハンドラ・メソッドは、dropEvent.getTransferable().getData(DataFlavor.UICOMPONENT_FLAVOR)を使用して、transferableオブジェクトとそのデータを取得します。メソッドがドロップを完了すると、org.apache.myfaces.trinidad.change.ReorderChildrenComponent
Changeメソッドを使用して子の新しい順序を保存し、dropEvent.getDropSiteIndex()メソッドを使用して、ドラッグしたコンポーネントの場所を取得できます。dashboardComponent.prepareOptimizedEncodingOfInsertedChild()メソッドを使用して、コンポーネントのドロップにアニメーションを使用することもできます。

例32-8に、ADF Facesデモ・アプリケーションのJSFページdashboardで使用されるマネージドBeanDemoDashboardBean.javaに対するイベント・ハンドラmoveとヘルパー・メソッドを示します。

例32-8 panelDashboardコンポーネントのDropListenerのハンドラ

public DnDAction move(DropEvent e)
{
UIComponent dropComponent = e.getDropComponent();
UIComponent movedComponent = e.getTransferable().getData(DataFlavor.UICOMPONENT_FLAVOR);
UIComponent movedParent = movedComponent.getParent();
// Ensure that we are handling the re-order of a direct child of the panelDashboard:
if (movedParent.equals(dropComponent) && dropComponent.equals(_dashboard))
{
// Move the already rendered child and redraw the side bar since the insert indexes have
// changed:
_moveDashboardChild(e.getDropSiteIndex(), movedComponent.getId());
}
else
{
// This isn't a re-order but rather the user dropped a minimized side bar item into the
// dashboard, in which case that item should be restored at the specified drop location.
String panelKey = _getAssociatedPanelKey(movedComponent);
if (panelKey != null)
{
UIComponent panelBoxToShow = _dashboard.findComponent(panelKey);
// Make this panelBox rendered:
panelBoxToShow.setRendered(true);

int insertIndex = e.getDropSiteIndex();

// Move the already rendered child and redraw the side bar since the insert indexes have
// changed and because the side bar minimized states are out of date:
_moveDashboardChild(insertIndex, panelKey);

// Let the dashboard know that only the one child should be encoded during the render phase:
_dashboard.prepareOptimizedEncodingOfInsertedChild(
FacesContext.getCurrentInstance(),
insertIndex);
}
}

return DnDAction.NONE; // the client is already updated, so no need to redraw it again
}

private void _moveDashboardChild(int dropIndex, String movedId)
{
// Build the new list of IDs, placing the moved component at the drop index.
List<String> reorderedIdList = new ArrayList<String>(_dashboard.getChildCount());
int index = 0;
boolean added = false;

for (UIComponent currChild : _dashboard.getChildren())
{
if (currChild.isRendered())
{
if (index == dropIndex)
{
reorderedIdList.add(movedId);
added = true;
}

String currId = currChild.getId();
if (currId.equals(movedId) && index < dropIndex)
{
// component is moved later, need to shift the index by 1
dropIndex++;
}

if (!currId.equals(movedId))
{
reorderedIdList.add(currId);
}
index++;
}
}

if (!added)
{
// Added to the very end:
reorderedIdList.add(movedId);
}

// Apply the change to the component tree immediately:
ComponentChange change = new ReorderChildrenComponentChange(reorderedIdList);
change.changeComponent(_dashboard);

// Add the side bar as a partial target since we need to redraw the state of the side bar items
// since their insert indexes are changed and possibly because the side bar minimized states
// are out of date:
RequestContext rc = RequestContext.getCurrentInstance();
rc.addPartialTarget(_sideBarContainer);
}

7. コンポーネント・パレットの「操作」パネルで、「コンポーネント・ドラッグ元」をドラッグし、ソース・コンポーネントになるpanelBoxコンポーネントの子としてドロップします。

8. プロパティ・インスペクタで、識別値を、手順5のpanelDashboardで識別値に入力した値に設定します。

32.6.2 panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の追加方法

panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の実装は、他のコンポーネントの標準ドラッグ・アンド・ドロップ機能と似ています。ただし、dataFlavorタグと識別値を使用する必要がある点を除きます。

panelDashboardコンポーネントからのドラッグ・アンド・ドロップ機能の追加方法:

1. コンポーネント・パレットの「操作」パネルで、「ドロップ・ターゲット」をターゲット・コンポーネントの子としてドラッグ・アンド・ドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードは手順5で作成)に評価される式を入力し、FlavorClassにjavax.faces.component.UIComponentと入力します。

3. dropTargetタグを選択した状態のまま、プロパティ・インスペクタでaction属性の値にMOVEを選択します。

4. 構造ウィンドウでdataFlavorタグを選択し、プロパティ・インスペクタで、このコンポーネントにドラッグできるpanelBoxコンポーネント(dragOutOfDashboardなど)を識別する識別値を一意の名前に設定します。

5. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)dropListener属性に対して作成します。

このハンドラ・メソッドは、DropEventイベントを使用してtransferableオブジェクトとそのデータを取得してから、必要に応じてコンポーネントの移動や並替えを完了します。メソッドがドロップを完了すると、DnDActionのNONEを返します。

dashboardComponent.prepareOptimizedEncodingOfDeletedChild()メソッドを使用して、panelBoxコンポーネントの削除にアニメーションを使用することができます。

例32-9に、デモ・アプリケーションのJSFページdashboardで使用されるマネージドBeanDemoDashboardBean.javaに対するイベント・ハンドラhandleSideBarDropとヘルパー・メソッドを示します。

例32-9 panelDashboardコンポーネントからのpanelBoxの移動を処理するdropListenerのイベント・ハンドラ・コード

public DnDAction handleSideBarDrop(DropEvent e)
{
UIComponent movedComponent = e.getTransferable().getData(DataFlavor.UICOMPONENT_FLAVOR);
UIComponent movedParent = movedComponent.getParent();

// Ensure that the drag source is one of the items from the dashboard:
if (movedParent.equals(_dashboard))
{
_minimize(movedComponent);
}

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;
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;

_switcher.setFacetName("restored");
rc.addPartialTarget(_switcher);
}

// Redraw the side bar so that we can update the colors of the opened items:
rc.addPartialTarget(_sideBarContainer);
}

6. コンポーネント・パレットの「操作」パネルで、「コンポーネント・ドラッグ元」を、panelDashboardコンポーネント内のソース・コンポーネントpanelBoxの子としてドラッグ・アンド・ドロップします。

7. プロパティ・インスペクタで、識別値を、手順4のターゲット・コンポーネントのdataFlavorタグで識別値に入力した値に設定します。

32.7 Calendarへのドラッグ・アンド・ドロップ機能の追加

Calendarには、ユーザーがアクティビティのハンドルをドラッグして終了時間を変更できる機能が含まれています。ただし、ユーザーがアクティビティを別の開始時間、さらには別の日にドラッグ・アンド・ドロップできるようにする場合は、ドラッグ・アンド・ドロップ機能を実装します。ドラッグ・アンド・ドロップを使用すると、アクティビティを移動できるだけでなく、コピーすることもできます。

32.7.1 Calendarへのドラッグ・アンド・ドロップ機能の追加方法

calendarDropTargetタグを使用して、ドラッグ・アンド・ドロップ機能を追加します。コレクションのドラッグ・アンド・ドロップとは異なり、ソース・タグは必要ありません。ターゲット(アクティビティの移動先のオブジェクト、この場合はカレンダ)がアクティビティを移動します。ソース(移動またはコピーの対象となるアイテム)がカレンダ内のアクティビティの場合、calendarDropTargetタグのみを使用します。タグは、転送可能なものがcalendarActivityオブジェクトであると予測します。

ただし、Calendarの外からオブジェクトをドラッグ・アンド・ドロップすることもできます。この操作を有効にする場合は、ソース・オブジェクト(calendarActivityオブジェクト以外のオブジェクト)をドロップできるように構成されているdataFlavorタグを使用します。

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[]のようにクラス名に大カッコ([])を追加します。

32.7.2 Calendarのドラッグ・アンド・ドロップについて

Calendar内のドラッグ・アンド・ドロップ・アクティビティの場合、ユーザーは表示内でのみドラッグ・アンド・ドロップを行うことができます。つまり、ユーザーは、日表示内の1つの時間スロットから別の時間スロットにアクティビティをドラッグできますが、日表示からアクティビティを切り取り、月表示に貼り付けることはできません。

ユーザーが日表示または週表示でアクティビティをドラッグ・アンド・ドロップしている場合、Calendarでは30分ごとにドロップ・サイトがマークされます。日表示では、終日のアクティビティまたは複数日のアクティビティは移動できません。

週表示では、終日のアクティビティおよび複数日のアクティビティを移動できますが、その他の終日のスロットにのみドロップできます。つまり、終日のアクティビティを、開始時間と終了時間が設定されているアクティビティには変更できません。月表示では、終日のアクティビティおよび複数日のアクティビティを任意の日に移動できます。

32.8 DVTグラフのドラッグ・アンド・ドロップ機能の追加

DVTバブル・グラフと散布図のドラッグ・アンド・ドロップを構成できます。これにより、マーカーの値を再配置することでその値を変更できます。グラフでドラッグ・アンド・ドロップできるようにする場合、dragSourceタグとdropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます(この場合はGraphSelectioオブジェクト)。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。

たとえば、図32-6に示すように、scatterGraphコンポーネントがあり、ユーザーが従業員の業績等級を調整する人材用散布図マーカーをドラッグできるようにするとします。

図32-5 オブジェクトのドラッグ・アンド・ドロップ

scatterGraphコンポーネントには、dragSourceとdropTargetタグがどちらも含まれています。また、dataFlavorタグを使用して、ドロップするオブジェクトのタイプを決定します。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはtransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはtransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。

32.8.1 DVTグラフのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、最初にソース・タグとターゲット・タグをグラフに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。実行時の処理の詳細は、32.3.2項「実行時の処理」を参照してください。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. コンポーネント・パレットの「操作」パネルで、「ドロップ・ターゲット」タグをドラッグし、グラフ・コンポーネントの子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ6で作成)に評価される式を入力します。

3. 「データ・フレーバの挿入」ダイアログで、oracle.adf.view.faces.bi.component.graph.GraphSelectionと入力します。これは、ターゲットにドロップできるオブジェクトのクラスです。このエントリを使用して、ターゲットにドロップできるオブジェクトのタイプを決めるdataFlavorタグを作成します。

4. プロパティ・インスペクタで、必要に応じて識別値の値を設定します。識別値は、どのソースをターゲットにドロップできるかを決定する場合に使用される任意の文字列です。たとえば、GraphSelectionオブジェクトを受け入れるGraphAとGraphBの2つのグラフがあるとします。ソースも2つあるとします。どちらもGraphSelectionオブジェクトになります。GraphAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つGraphSelectionソースのみが受け入れられます。

5. 構造ウィンドウで、dropTargetタグを選択します。プロパティ・インスペクタで、「アクション」の値にMOVEを選択します。

6. コンポーネント・パレットの「操作」パネルで、「ドラッグ元」をグラフ・コンポーネントの子としてドラッグ・アンド・ドロップします。

7. dragSourceタグを選択している場合、プロパティ・インスペクタで、dataFlavorタグに構成されるように、許容アクションにMOVEを設定し、必要な識別値を追加します。

8. ステップ2で作成したEL式で参照されるマネージドBeanに、ドラッグ・アンド・ドロップ機能を処理するイベント・ハンドラ・メソッドを(EL式での名前と同じ名前を使用して)作成します。
このメソッドは、DropEventイベントをパラメータとして取り、DnDActionオブジェクトを返します。これは、ソースのドロップ時に実行されるアクションです。この場合はDnDAction.MOVEになります。このメソッドは、DropEventイベントをチェックして、それがドロップを受け入れるかどうかを判断します。メソッドがドロップを受け入れる場合、ドロップを実行して、実行されたDnDActionオブジェクトを返します。それ以外の場合、ドロップが拒否されたことを示すDnDAction.NONEを返します。このメソッドでは、dataFlavorオブジェクト(この場合はoracle.adf.view.faces.bi.component.graph.GraphSelection)の存在も確認する必要があります。

32.9 DVTガント・チャートのドラッグ・アンド・ドロップ機能の追加

ガント・チャートとその他のコンポーネント間でドラッグ・アンド・ドロップできるようにする場合、dragSourceタグとdropTargetタグを使用します。また、DataFlavorオブジェクトを使用して、ドロップ・ターゲットに対して有効なソースのJava型を決めます。ドラッグ・アンド・ドロップ・アクションを受けて必要となる機能の実装も必要です。projectGanttとschedulingGanttのどちらのコンポーネントも、ドラッグ・アンド・ドロップ機能をサポートします。

たとえば、図32-6に示すように、projectGanttコンポーネントがあり、ユーザーがtreeTableコンポーネントに1つのタイムラインをドラッグできるようにし、タイムラインに関する情報がそのコンポーネントに表示されるとします。

図32-6 オブジェクトのドラッグ・アンド・ドロップ

projectGanttコンポーネントには、dragSourceタグが含まれます。ユーザーは、表示される出力テキストのString値のみではなくオブジェクト全体をドラッグするため、attributeDropTargetタグのかわりにdropTargetタグを使用します。

また、dataFlavorタグを使用して、ドロップするオブジェクトのタイプを決定します。このタグでは、識別値を定義できます。同じオブジェクト型の2つのターゲットと2つのソースがある場合に、これは有用です。識別値を作成することで、各ターゲットで有効なソースのみが受け入れられることが保証されます。たとえば、TaskDragInfoオブジェクトを受け入れるTargetAとTargetBの2つのターゲットがあるとします。ソースも2つあるとします。どちらもTaskDragInfoオブジェクトになります。TargetAにalphaという値を使用して識別値を設定することにより、識別値alphaを持つTaskDragInfoソースのみが受け入れられます。

ドロップ・イベントのリスナーも実装する必要があります。ドロップ・イベントのオブジェクトはtransferableと呼ばれ、ドロップのペイロードを含みます。リスナーはtransferableオブジェクトにアクセスし、ここからDataFlavorオブジェクトを使用してオブジェクトがドロップ可能なことを確認します。その後、ドロップ・イベントを使用してターゲット・コンポーネントを取得し、ドロップされたオブジェクトを使用してプロパティを更新します。

32.9.1 DVTコンポーネントのドラッグ・アンド・ドロップ機能の追加方法

ドラッグ・アンド・ドロップ機能を追加するには、まず、コンポーネントをドラッグ・アンド・ドロップ・アクションのターゲットとして定義するタグをコンポーネントに追加します。次に、ドラッグ・アンド・ドロップ・アクションのロジックを処理するイベント・ハンドラ・メソッドを実装します。最後に、ドラッグ・アンド・ドロップのソースを定義します。実行時の処理の詳細は、32.3.2項「実行時の処理」を参照してください。clientDropListener属性の使用の詳細は、32.3.3項「ClientDropListenerの使用について」を参照してください。

ドラッグ・アンド・ドロップ機能を追加する手順:

1. コンポーネント・パレットの「操作」パネルで、「ドロップ・ターゲット」タグをドラッグし、ターゲット・コンポーネントの子としてドロップします。

2. 「ドロップ・ターゲットの挿入」ダイアログで、イベントを処理するマネージドBeanのメソッド(このコードはステップ6で作成)に評価される式を入力します。

ヒント:

clientDropListener属性を挿入して、クライアントでドロップを捕捉することもできます。詳細は、32.3.3項「ClientDropListenerの使用について」を参照してください。

3. 「データ・フレーバの挿入」ダイアログで、ターゲットにドロップ可能なオブジェクトのクラス(java.lang.Objectなど)を入力します。この選択を使用して、ターゲットにドロップできるオブジェクトのタイプを決めるdataFlavorタグを作成します。1つのドロップ・ターゲットに複数のdataFlavorタグを使用し、ドロップ・ターゲットでこれらの型のいずれも受け入れるようにすることができます。

ヒント:

DataFlavorタグに型指定された配列を指定するには、java.lang.Object[]のようにクラス名に大カッコ([])を追加します。

4. プロパティ・インスペクタで、必要に応じて識別値の値を設定します。識別値は任意の文字列で、dataFlavorで指定されるどのタイプのソースがソースとして許容されるかを決める場合に使用されます。

5. 構造ウィンドウで、dropTargetタグを選択します。プロパティ・インスペクタで、「アクション」の値を選択します。これによって、ドロップ・ターゲットでサポートされるアクションが定義されます。有効な値は、COPY(コピーして貼付け)、MOVE(切り取って貼付け)およびLINK(コピーしてリンクとして貼付け)です。

MOVE COPY

アクションが指定されない場合、デフォルトはCOPYです。

例32-10に、TaskDragInfoオブジェクトをドロップ・ソースにするdropTargetコンポーネントのコードを示します。actions属性の値にCOPYが設定されたため、COPYのみが許容されるアクションになることに注意してください。

例32-10 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、and 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が受け入れられる場合、転送可能オブジェクトにjava.util.ArrayListを含むドロップは正常終了します。同様に、この機能ではArraysとListsとの間の自動変換もサポートされます。

ドラッグ・アンド・ドロップ・フレームワークで、サーバーのDataFlavorオブジェクトをクライアント・コンポーネントで表す方法がわからない場合、すべてのドロップがクライアントで正常終了するようドロップ・ターゲットが構成されます。

例32-11に、イベント・ペイロードからTaskDragInfoオブジェクトをコピーして、イベントを開始したコンポーネントに割り当てるハンドラ・メソッドを示します。

例32-11 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タグを選択している場合、プロパティ・インスペクタで、ターゲットに構成される、許容アクションと必要な識別値を設定します。

33 様々な出力モードの使用

この章では、印刷やメール送信に適したモードでページを表示する方法について説明します。

この章では、次の項目について説明します。

- 33.1項「様々な出力モードの使用の概要」

- 33.2項「印刷用のページの表示」

- 33.3項「メール可能なページの作成」

33.1 様々な出力モードの使用の概要

ADF Facesでは、印刷またはメール送信用の簡単なモードでページを出力できます。たとえば、Webブラウザにレンダリングされるようにページを正確に印刷するのではなく、ページ(またはページの一部)を印刷できるようにする場合、印刷するページに不要なアイテム(スクロール・バーやボタンなど)を削除できます。ページをメール送信する場合、メール・クライアントで正しく表示できるようにページを簡略化する必要があります。

注意:

デフォルトでは、ADF Facesフレームワークで、検索エンジンによるアプリケーションのクロールが検出されると、メール可能なページの形式と同様にクローラの簡単な形式でページが出力されます。Webクローラの特殊なコンテンツを生成する場合、EL対応Agentインタフェースを使用すると、エージェントでサイトをクロールするタイミングを検出して、指定のリンクにエージェントを誘導できます。たとえば、次のようになります。

<c:if test="#{requestContext.agent.type ==  'webcrawler'}">
<af:goLink 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 2.0のいずれかの表示に適したページへの変換に使用できるAPIが提供されます。

ヒント:

現在の出力モード(emailまたはprintable)には、AdfFacesContextからアクセスできます。このコンテンツはEL対応のため、ELを使用して、JSPページから出力モードにバインドできます。たとえば、現在のモードがemailではない場合のみ、次の式を使用してグラフィックをレンダリングできます。

<af:activeImage source="/images/stockChart.gif"
rendered="#{adfFacesContext.outputMode != "email"}"/>

現在のモードは、AdfFacesContext.getOutputMode()を使用して決定できます。

33.2 印刷用のページの表示

showPrintablePageBehaviorタグを、コマンド・コンポーネントの子として配置します。クリックすると、フレームワークは、printableBehaviorタグの親のコンポーネントで開始するコンポーネント・ツリーをたどり、panelSplitterまたはpanelAccordion、あるいはツリーのルート(どちらの場合も最初に来る)に達するまで移動します。ツリーはその場所からレンダリングされます。さらに、印刷バージョンで不要なコンポーネント(ボタン、タブ、スクロール・バーなど)は省略されます。

たとえば、ファイル・エクスプローラ・アプリケーションでは、図33-1に示すように、表を含むpanelCollectionコンポーネントのツールバーの内部にcommandButtonコンポーネントを配置できます。

図33-1 ページの印刷部分のボタン

ボタンをクリックすると、図33-2に示すように、ページは簡略化された形式で新しいブラウザ・ウィンドウ(ブラウザによってはタブ)に表示されます。

図33-2 印刷可能なバージョンのページ

印刷の場合、表の内容のみが表示されます。タブ、ツールバー、スクロール・バーなどの余分なコンポーネントはすべてレンダリングされません。

ボタンをクリックすると、actionイベントは取り消されます。かわりに、印刷可能なバージョンのページに関してサーバーへのリクエストが行われます。

33.2.1 showPrintablePageBehaviorタグの使用方法

showPrintablePageBehaviorタグは、コマンド・コンポーネントの直接の子として使用されます。

showPrintablePageBehaviorタグを使用する手順:

1. レイアウト・コンポーネントのいずれかで、印刷するコンテンツを含むファセットにコマンド・コンポーネントを追加します。手順は、18.2.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。

注意:

ユーザーがページ全体を印刷できるようにレイアウト・コンポーネントの外にshowPrintablePageBehaviorコンポーネントを挿入できますが、印刷結果がレイアウトとおおまかにしか一致せず、一部のコンテンツが表示されない場合があります。そのため、ユーザーがファセットの全コンテンツを印刷できるようにするには、ユーザーが通常印刷するコンテンツを含むファセットにコマンド・コンポーネントとshowPrintablePageBehaviorコンポーネントを配置することが重要です。複数のファセットで印刷をサポートする必要がある場合は、各ファセットにコマンド・コンポーネントを1つとshowPrintablePageBehaviorタグを挿入します。すべてのコンテンツを印刷するには、ユーザーは一度に1つのファセットで印刷コマンドを実行する必要があります。

2. コンポーネント・パレットの「操作」パネルで、「印刷可能なページの表示動作」をドラッグし、コマンド・コンポーネントの子としてドロップします。

33.3 メール可能なページの作成

アプリケーションのページをメール送信する必要がある場合があります。たとえば、Web上で作成された注文書は、多くの場合、セッションの最後に購入者に対してメールで送付されます。ただし、メール・クライアントでは、Webブラウザへのレンダリングに使用する外部のスタイルシートに対応していないため、正しくレンダリングされず、同じページをメール送信することができません。

ADF Facesフレームワークでは、JSFページの自動変換が行われるため、Microsoft Outlook 2007およびMozilla Thunderbird 2.0メール・クライアントで正しくレンダリングされます。

すべてのコンポーネントを、メール・クライアントでレンダリングできるわけではありません。次のコンポーネントは変換できるため、メール・クライアントで適切にレンダリングされます。

- document

- panelHeader

- panelFormLayout

- panelGroupLayout

- panelList

- spacer

- showDetailHeader

- inputText(readOnlyとしてレンダリング)

- inputComboBoxListOfValues(readOnlyとしてレンダリング)

- inputNumberSlider(readOnlyとしてレンダリング)

- inputNumberSpinbox(readOnlyとしてレンダリング)

- inputRangeSlider(readOnlyとしてレンダリング)

- outputText

- selectOneChoice(readOnlyとしてレンダリング)

- panelLabelAndMessage

- image

- table

- column

- goLink(テキストとしてレンダリング)

33.3.1 メール可能なページの作成方法

メール・クライアントでレンダリングするページを変換するようにADF Facesフレームワークに通知するには、次のリクエスト・パラメータを、メール送信するページのURLに追加します。

org.apache.myfaces.trinidad.agent.email=true

たとえば、図33-3に示すように、注文書を表示するページがあるとします。

図33-3 注文書のWebページ

上部にあるメール可能なページリンクをクリックすると、actionListenerメソッドまたは別のサービスで、現在のURLにorg.apache.myfaces.trinidad.agent.email=trueを追加してページをメール送信します。図33-4に、メール・クライアントに表示されるページを示します。

図33-4 メール・クライアントのページ

ヒント:

メールをオフラインで表示できるようにするには、次のリクエスト・パラメータを、メール送信するページのURLに追加します。

org.apache.myfaces.trinidad.agent.email=true&oracle.adf.view.rich.render.emailContentType=multipart/related

フレームワークは、HTMLをMIME(multipart/related)に変換し、メールがオフラインで表示されるようにイメージを埋め込みます。

33.3.2 メール・クライアントでページのレンダリングをテストする方法

ページの開発を完了する前に、メール・クライアントでのページのレンダリング方法をテストできます。テストは、goButtonコンポーネントを使用して簡単に実行できます。

メール可能なページのテスト手順:

1. コンポーネント・パレットの「共通コンポーネント」パネルで、ページのいずれかの場所に実行ボタンをドラッグ・アンド・ドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて、ページの名前になる宛先と、org.apache.myfaces.trinidad.agent.email=trueを設定します。
たとえば、ページの名前がmyPageの場合、宛先属性の値は次のようにします。

myPage.jspx?org.apache.myfaces.trinidad.agent.email=true

3. ページを右クリックし、「実行」を選択して、デフォルトのブラウザでページを実行します。
アプリケーションを初めて実行し、新しいドメインを統合WebLogic Serverで開始する際に、「デフォルト・ドメインの構成」ダイアログが表示されます。ダイアログを使用して新しいドメインの管理者パスワードを定義します。入力するパスワードは8文字以上で、数字が含まれている必要があります。

4. ブラウザにページが表示されたら、ページに追加したgoButtonをクリックします。これにより、ブラウザにページが再度表示されますが、そのページは、メール・クライアントで処理できるページに変換されます。

5. ブラウザで、ページのソースを表示します。たとえば、Mozilla Firefoxでは、「表示」→「ページのソース」を選択します。ソース全体を選択してコピーします。

6. メール・クライアントで新規メッセージを作成します。ページ・ソースをメッセージに貼り付けて自分自身に送信します。

ヒント:

HTMLコードを貼り付けているため、おそらく挿入コマンドを使用してメール本文にHTMLを挿入する必要があります。たとえば、Thunderbirdでは、「Insert」→「HTML」を選択します。

7. 必要に応じて、エージェントを使用して、メール・バージョンのページ専用のスキンを作成します。例33-1に、メールでレンダリングされる表に枠を指定する方法を示します。

例33-1 メール可能なページのスキン

af|table {
border: 1px solid #636661;
}

@agent email {
af|table
{border:none}
}

af|table::column-resize-indicator {
border-right: 2px dashed #979991;
}

スキンの作成の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

33.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

第VI部

付録

第VI部には、次の付録が含まれています。

- 付録A「ADF Facesの構成」

- 付録B「コンバータおよびバリデータ・メッセージのメッセージ・キー」

- 付録C「キーボード・ショートカット」

- 付録D「ADF Facesを使用したタッチ装置のWebアプリケーションの作成」

- 付録E「クイック・スタート・レイアウト・テーマ」

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項「JavaScriptライブラリのパーティション化の使用」

A.1 ADF Facesの構成の概要

JSF Webアプリケーションには、特定の構成ファイルのセット(web.xmlおよびfaces-config.xml)が必要です。ADFアプリケーションでは、構成情報が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 Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server』を参照してください。

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コンテキスト・パラメータ

アプリケーションでJSPフラグメントを使用するよう選択した場合、アプリケーションで.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はデフォルトでは概要エディタで開きます。これは、エディタ・ウィンドウの下部の「概要」タブがアクティブなことで示されます。

概要エディタを使用してエントリを宣言的に追加または編集すると、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: アプリケーションのビューの状態の格納場所を指定します。この値はデフォルトではserverで、アプリケーションのビューの状態がサーバーに格納されます。ADF Facesを使用する場合は、javax.faces.STATE_SAVING_METHODをclientに設定し、ビューの状態をブラウザ・クライアントに格納することをお薦めします。clientに設定した場合、ADF Facesでトークンベースのクライアント側の状態保存が自動的に使用されます。デフォルトの15を使用するかわりに、使用するトークンの数を指定できます。状態保存コンテキスト・パラメータの詳細は、A.2.3項「web.xmlのADF Facesコンテキスト・パラメータについて」を参照してください。

- MyFaces Trinidadのフィルタおよびマッピング: MyFaces Trinidadフィルタorg.apache.myfaces.trinidad.webapp.TrinidadFilterをインストールします。これは、RequestContextオブジェクトをある程度設定することで、ADF Facesが適切に初期化されるようにするサーブレット・フィルタです。TrinidadFilterでは、ファイル・アップロードも処理されます。フィルタ・マッピングは、JSFサーブレットのシンボリック名をADF Facesフィルタにマップします。転送ディスパッチャとリクエスト・ディスパッチャは、MyFaces Trinidadフィルタに転送する他のフィルタに必要です。

ヒント:

アプリケーションで複数のフィルタを使用する場合、フィルタを実行順にweb.xmlファイルに必ずリストします。実行時、このファイルにリストされた順にフィルタがコールされます。

- MyFaces Trinidadのリソース・サーブレットとマッピング: MyFaces Trinidadリソース・サーブレットorg.apache.myfaces.trinidad.webapp.ResourceServletをインストールします。これは、リソース・ローダーに委譲することでWebアプリケーション・リソース(イメージ、スタイルシート、JavaScriptライブラリなど)を処理します。サーブレット・マッピングは、MyFaces Trinidadリソース・サーブレットのシンボリック名をURLパターンにマップします。JDeveloperは、デフォルトで/adf/*(MyFaces Trinidad Coreの場合)および/afr/*(ADF Facesの場合)を使用します。

- 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: トークンベースのクライアント側状態保存が有効な場合、ユーザー1人につき一度に格納する必要があるトークンの数を指定します。デフォルトは15です。トークンの数がこの値を超えると、表示頻度の最も低いページの状態が失われるため、「戻る」ボタンを頻繁に使用するユーザーや、同時に複数のウィンドウを開いているユーザーが影響を受けます。フレームへの依存度が高いHTMLアプリケーションを作成する場合は、この値を増やすことができます。

- org.apache.myfaces.trinidad.COMPRESS_VIEW_STATE: セッションでの状態保存をグローバルに圧縮するかどうかを指定します。各ユーザー・セッションには、有効なメモリを大量に消費するpageStateオブジェクトが複数含まれることがあるため、パフォーマンスが影響を受けます。このオーバーヘッドは、セッション・レプリケーションが発生する場合、クラスタリングに関してかなり大きな問題になる可能性があります。デフォルトはoffです。

- org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE: アプリケーション表示キャッシュ(AVC)を有効にします。これにより、ページのUIの初期レンダーの状態をアプリケーションの範囲でキャッシュすることで、スケーラビリティが向上します。ただし、予想外の状態のデバッグやユーザー間の情報漏れに関する問題を回避するには、AVCでアプリケーションのすべてのページを分析してサポートする必要があります。また、サーバーの再起動までページ更新が通知されないため、開発はさらに難しくなり、初期レンダー・パフォーマンスは強化されますが、セッション・サイズは改善されません。

注意:

アプリケーション表示キャッシュは、このリリースではサポートされません。この機能は、コンポーネント・ツリーのレンダリングが原因でコンポーネント・ツリーの構造が一時的に変わるページでは機能しません。これは頻繁に起こることがあるため、USE_APPLICATION_VIEW_CACHEを使用しないでください。

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でJSPファイルと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のいずれかのレベルを使用します。自動プロファイラ・インストルメンテーション・コードが有効(A.2.3.6項「プロファイリング」のoracle.adf.view.rich.profiler.ENABLEDを参照)な場合、INFOに設定します。

パフォーマンスのヒント:

JavaScriptロギングはパフォーマンスに影響します。実行時環境では、この値はOFFに設定します。

A.2.3.3 ファイルのアップロード

次のファイル・アップロード・コンテキスト・パラメータを指定できます。

- org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY: 1回のリクエストでアップロード・ファイルを格納するために使用できる最大メモリー容量を指定します。デフォルトは、100Kです。

- org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE: 1回のリクエストでアップロード・ファイルを格納するために使用できる最大ディスク容量を指定します。デフォルトは、2000Kです。

- 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 アサーション

oracle.adf.view.rich.ASSERT_ENABLEDパラメータを使用して、ADF Faces内でアサーションを使用するかどうかを指定できます。デフォルトは、falseです。アサーションを有効にするにはtrueに設定します。

パフォーマンスのヒント:

アサーションにより、パフォーマンスが影響を受けます。実行時環境では、この値はfalseに設定します。

A.2.3.6 プロファイリング

次のJavaScriptプロファイリング・コンテキスト・パラメータを指定できます。

- oracle.adf.view.rich.profiler.ENABLED: JavaScript Profilerで用意されている自動プロファイラ・インストルメンテーション・コードを使用するかどうかを指定します。デフォルトは、falseです。JavaScriptプロファイルを有効にするにはtrueに設定します。プロファイラが有効な場合、各ページでプロファイラ・データをフェッチするために追加のラウンドトリップが必要になります。デフォルトでは、/WEB-INF/profiler.xml構成ファイルがJDeveloperで使用されます。profiler.xmlの場所をオーバーライドするには、次に説明するROOT_FILEコンテキスト・パラメータを使用します。DEBUG_JAVASCRIPTをtrueに設定し、JavaScriptの曖昧化を無効にする場合もあります。LOGGER_LEVELを最低でもINFOに設定する必要もあります。

- oracle.adf.view.rich.profiler.ROOT_FILE: 自動プロファイラ・インストルメンテーション・コードが有効の場合にロードする初期profiler.xmlファイルを指定します。ROOT_FILEが指定されていない場合、デフォルトでは、/WEB-INF/profiler.xmlファイルがJDeveloperで使用されます。

A.2.3.7 Faceletサポート

FaceletとADF Facesを組み合せて使用する場合、次の指定を行う必要があります。

- org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER: パラメータの値をcom.sun.facelets.FaceletViewHandlerに設定して、FaceletsViewHandlerをインストールします。

- javax.faces.DEFAULT_SUFFIX: パラメータの値を.xhtmlに設定して、Faceletを使用するドキュメントのファイル拡張子に.xhtmlを使用します。

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 テストの自動化

oracle.adf.view.rich.automation.ENABLEDパラメータをtrueに設定し、コンポーネントID属性がnullの場合、自動テストの際、IDがnullでないようコンポーネントのtestId属性が使用されます。testIdは、タグでのみ属性になります。これは、JavaコンポーネントAPIの一部ではありません。

注意:

このコンテキスト・パラメータをtrueに設定すると、oracle.adf.view.rich.security.FRAME_BUSTINGコンテキスト・パラメータはneverに設定された場合と同じように動作します。詳細は、A.2.3.15項「フレームバスティング」を参照してください。

A.2.3.11 UIViewRootキャッシング

UIViewRootキャッシングを有効または無効にするには、org.apache.myfaces.trinidad.CACHE_VIEW_ROOTパラメータを使用します。トークンのクライアント側状態保存が有効な場合、MyFaces Trinidadは、各トークンを含むUIViewRootツリー全体をキャッシュしてさらに最適化を適用できます(これが、スレッド・セーフティやセッション・フェイルオーバーに影響を与えることはありません。)これは、AJAXインテンシブ・システムの主な最適化であり、UIViewRootツリーを再インスタンス化せずに、よりすばやくポストバックを処理できます。

キャッシングを有効にするには、org.apache.myfaces.trinidad.CACHE_VIEW_ROOTパラメータをtrueに設定します。これはデフォルト設定です。キャッシングを無効にするには、パラメータをfalseに設定します。

注意:

この種のキャッシングは、一部のJSFテクノロジと干渉することが認識されています。特に、Apache MyFaces Tomahawk saveStateコンポーネントが機能せず、Faceletのテンプレート・テキストが二重に表示される場合があります。

A.2.3.12 テーマと色調スタイル

色調スタイルの使用をオフまたはオンにするには、oracle.adf.view.rich.tonalstyles.ENABLEDパラメータを使用します。色調スタイル・クラス.AFDarkTone、.AFMediumTone、.AFLightToneおよび.AFDefaultToneは、下位互換性の目的で引き続き使用できますが、テーマは置換スタイルとして提供されます。テーマは色調スタイルより作成しやすく、依存するセレクタが少ない上に、CSS包含セレクタも使用されません。このため、バグが少ない傾向にあります。1つのCSSファイル内のセレクタ数に対する制限により、色調スタイルおよびテーマの両方を、同じアプリケーションでサポートすることはできません。色調スタイルを無効にするには、falseに設定します。

A.2.3.13 部分ページ・ナビゲーション

部分ページ・ナビゲーションの有効/無効を切り替えるには、oracle.adf.view.rich.pprNavigation.OPTIONSパラメータを使用します。デフォルトでは、値はoffです。部分ページ・ナビゲーションでは、アプリケーション全体で同じベース・ページを使用し、単にページ本体のコンテンツを各ナビゲーションに置き換えます。この処理により、ページが新しくなるたびにJavaScriptライブラリとスタイルシートを再ロードする必要がなく、パフォーマンスが向上します。詳細は、7.4項「部分ページ・ナビゲーションの使用」を参照してください。

有効な値は次のとおりです。

- on: アプリケーションのPPRナビゲーションを有効にします。

注意:

パラメータを有効にする場合、ナビゲーションに含まれるコマンド・コンポーネントのpartialSubmit属性をtrueに設定する必要があります。partialSubmitの詳細は、5.1.1項「イベントおよび部分ページ・レンダリング」を参照してください。

- off: アプリケーションのPPRナビゲーションを無効にします。

- onWithForcePPR: コマンド・コンポーネントのアクションでナビゲーションが生じる場合、コンポーネントのpartialSubmitがtrueに設定されているかのように、アクションは常にPPRを使用して提供されます。partialSubmitの詳細は、5.1.1項「イベントおよび部分ページ・レンダリング」を参照してください。コンポーネントですでにpartialSubmitがtrueに設定されている場合、フレームワークは何も実行しません。partialSubmitがtrueに設定されていない場合、ドキュメント全体がリフレッシュされ、古いページのリフレッシュ動作が保持されます。アクション・コンポーネントにナビゲーションが含まれない場合も、ドキュメント全体がリフレッシュされます。

A.2.3.14 JavaScriptのパーティション化

oracle.adf.view.rich.libraryPartitioning.ENABLEDパラメータを使用して、JavaScriptのパーティション化の有効/無効を切り替えます。デフォルトでは、値はtrue(有効)です。JavaScriptのパーティション化を使用すると、ページのクライアント・コンポーネントによって必要とされるJavaScriptのみをダウンロードできます。

有効な値は次のとおりです。

- true: JavaScriptのパーティション化が有効にされています(デフォルト)。

- false: JavaScriptのパーティション化が無効にされています。

JavaScriptのパーティション化の使用および構成の詳細は、A.9項「JavaScriptライブラリのパーティション化の使用」を参照してください。

A.2.3.15 フレームバスティング

アプリケーションでフレームバスティングを使用するには、oracle.adf.view.rich.security.FRAME_BUSTINGコンテキスト・パラメータを使用します。フレームバスティングは、悪意のあるWebサイトが別のドメインのページをフレームに引き出して偽のページで覆い隠し、元のページの一部のみが表示されるようにしたり、クリックジャックされたページ(ボタンなど)が表示されるようにするクリックジャックを防ぐ方法です。ユーザーがボタンをクリックすると、実際はクリックジャックされたページでボタンをクリックしているため、予期しない結果になります。

たとえば、DomainAに存在するWebベースの電子メール・アプリケーションに対して、IFrameを使用してDomainAの電子メール・アプリケーションのページを指すページを作成してDomainBのWebサイトでページをクリックジャックするとします。2つのページを組み合せて、DomainBから引き出されたページがIFrameでページの大部分を占めるようにして、アカウントのすべての電子メールを削除するボタンのみが表示されるようにします。実際に電子メール・アプリケーション内で操作していることを知らないユーザーがボタンをクリックすると、意図せずにすべての電子メールが削除されることになります。

フレームバスティングは次のJavaScriptを使用して、アプリケーションのページがフレーム内で実行されるのをブロックし、クリックジャックを防ぎます。

top.location.href = location.href;

パラメータをalwaysに設定して、アプリケーションがフレームバスティングを使用するように構成すると、フレームでページの実行が試行されるたびに、ユーザーにはページがリダイレクトされているというアラートが表示され、JavaScriptコードが実行されてページが最上位と定義されるため、ページのフレーム内での実行が却下されます。

アプリケーションでフレームを使用する必要がある場合は、パラメータをdifferentDomainに設定できます。この設定ではフレームがアプリケーションとは別のドメインから引き出される場合のみフレームバスティングが使用されます。これがデフォルト設定です。

注意:

ページの起点は、ドメイン名、アプリケーション・レイヤー・プロトコル、ほとんどのブラウザでスクリプトを実行するHTMLドキュメントのTCPポートを使用して定義されます。これらすべての値が厳密に同じ場合のみ、ページは同じドメインから引き出されていると見なされます。

たとえば、DomainApage2ページを含むフレームを使用するアプリケーションにDomainApage1という名前のページがあるとします。外部のDomainBpage1がDomainApage1ページのクリックジャックを試行するとします。結果は次のようなウィンドウ階層になります。

- DomainBpage1

- DomainApage1

- DomainApage2

アプリケーションでdifferentDomainにフレームバスティングが設定されていれば、フレームワークは親ウィンドウ階層をたどって、任意の祖先ウィンドウが別のドメインから引き出されているかを判断できます。DoaminBpage1は別のドメインから引き出されているため、DomainApage1ページに対してフレームバスティングJavaScriptコードが実行され、トップレベル・ウィンドウが表示されます。DomainApage2は同じドメインから引き出されているため、DomainApage1はフレーム内での実行が許可されます。

有効な値は次のとおりです。

- always: フレームでの実行が試行されると常にエラーが表示されリダイレクトします。

- differentDomain: 別のドメインのページでフレームの実行が試行される場合のみ、エラーが表示されリダイレクトします(デフォルト)。

- never: 任意の引き出し元ドメインの任意のフレームでページを実行できます。

注意:

次のコンテキスト・パラメータのいずれかをtrueに設定すると、このコンテキスト・パラメータは無視され、neverに設定した場合と同様に動作します。

- org.apache.myfaces.trinidad.util.
ExternalContextUtils.isPortlet

- oracle.adf.view.rich.automation.ENABLED

A.2.3.16 自動生成コンポーネントIDの抑制

プログラムでaf:outputTextまたはaf:outputFormattedコンポーネントを部分ターゲットとして追加する場合(addPartialTarget()の呼出し)、oracle.adf.view.rich.SUPPRESS_IDSコンテキスト・パラメータをautoに設定します。

デフォルトでは、このパラメータはexplicitに設定されているため、次のいずれかがtrueの場合を除き、自動生成コンポーネントIDおよび明示的に設定されるコンポーネントIDの両方を抑制することで、コンテンツ・サイズが縮小されます。

- コンポーネントのpartialTriggers属性が設定されている。

- clientComponent属性がtrueに設定されている。

addPartialTarget()を呼び出す場合、partialTriggers属性は設定されず、部分ページ・レンダーは成功しません。パラメータをautoに設定すると、このようなコンポーネントの自動生成コンポーネントIDのみを抑制できます。

A.2.3.17 ADF Facesキャッシング・フィルタ

ADF Facesキャッシング・フィルタ(ACF)は、イメージ、スタイルシート、.pdfや.zipファイルといったドキュメントなどの静的アプリケーション・オブジェクトのキャッシング(または圧縮、あるいはその両方)を有効にすることで、Webアプリケーションのパフォーマンスを上げる場合に使用可能なJava EEサーブレット・フィルタです。これらのオブジェクトは、Oracle Web CacheやOracle Traffic Directorなどの外部Webキャッシュまたはブラウザ・キャッシュでキャッシュされます。コンテンツのキャッシュ可能性は、主に、Webキャッシュ管理者が定義するURLベースのルールで決まります。ACFを使用する場合、ADFアプリケーション管理者または作成者は、adf-config.xmlファイルにキャッシング・ルールを直接定義できます。キャッシング・ルールの定義の詳細は、A.4.2項「ADF Facesキャッシング・フィルタのキャッシング・ルールの定義」を参照してください。

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に定義されたキャッシング・ルールがブラウザのキャッシュに適用されます。URLリクエスト・パス内になるようにACFを構成するには、web.xmlファイルで次のサーブレット・フィルタ定義を追加します。

- ACFフィルタ・クラス: adf-config.xmlで定義したルールに一致するURLを実行するクラスを指定します。

- ACFフィルタ・マッピング: adf-config.xmlで定義したキャッシング・ルールに一致するURLパターンを定義します。

例A-2に、ACFサーブレット定義のサンプルを示します。

例A-2 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.18 コマンド・リンクのネイティブ･ブラウザ・コンテキスト・メニューの構成

リンクをレンダリングするADF Facesコマンド・コンポーネントのコンテキスト・メニューを表示するには、oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSIONパラメータを使用してエンド・ユーザーのブラウザの有効または無効を切り替えます。ポップアップ・メニューは、コマンド・コンポーネントで指定されたリンクに対して、異なるアクション(たとえば、新しいウィンドウでリンクを開くなど)を起動するメニュー・オプションを表示することができます。

デフォルトでは、このパラメータはyesに設定されているため、ADF Facesコマンド・コンポーネントのコンテキスト・メニューのレンダリングが抑制されます。パラメータをnoに設定すると、この抑制を無効にして、ネイティブ・ブラウザ・コンテキスト・メニューを表示できます。この機能を構成できるADF Facesコマンド・コンポーネントの詳細は、第18章「コマンド・リンクのブラウザのコンテキスト・メニューの構成」を参照してください。

A.2.3.19 セッション・タイムアウトの警告

リクエストがサーバーに送信されると、セッション・タイムアウト値がページに書き込まれ、セッション・タイムアウト警告の間隔がコンテキスト・パラメータoracle.adf.view.rich.sessionHandling.WARNING_BEFORE_TIMEOUTで定義されます。ユーザーは、警告ダイアログでセッションを延長することができ、セッションの期限が切れてページがリフレッシュされるときに通知が送信されます。アプリケーションのセキュリティ構成に応じて、セッションの期限が切れると、ユーザーはページのログにリダイレクトされます。

警告ダイアログが表示されてからセッション・タイムアウトまでの秒数を設定するには、oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_TIMEOUTコンテキスト・パラメータを使用します。WARNING_BEFORE_TIMEOUTの値が120秒未満の場合、クライアントの状態保存がページに使用されるか、セッションが無効になっている場合、機能は無効になります。セッション・タイムアウト値は、セッションから直接取得されます。

例A-3に、セッションがタイムアウトするまで警告ダイアログが120秒表示される場合の構成を示します。

例A-3 セッション・タイムアウト警告の構成

<context-param>
<param-name>oracle.adf.view.rich.sessionHandling.WARNING_BEFORE_
TIMEOUT</param-name>
<param-value>120</param-value>
</context-param>

このパラメータのデフォルト値は120秒です。セッション・タイムアウトの設定が短すぎる場合にユーザーへの通知が頻繁に行われないようにするには、実際のWARNING_BEFORE_TIMEOUTの値を動的に決定します。この場合、セッション・タイムアウトは、2分を超えるように設定する必要があります。そうしなければ、機能は無効になります。

A.2.3.20 HTTPストリーミングでのJSPタグ実行

JSPページの処理中にHTTPストリーミング・リクエストでのJSPタグ実行の有効または無効を切り替えるには、oracle.adf.view.rich.tag.SKIP_EXECUTIONパラメータを使用します。Faceletの処理は含まれません。

このパラメータは、デフォルトでstreamingに設定されています。JSPタグ実行は、ストリーミング・リクエスト時はスキップされます。タグ実行がストリーミング・リクエストで必要な場合、リクエストごとにJSPタグを実行するには、パラメータをoffに設定します。

A.2.3.21 スプラッシュ画面

図A-1に示すように、ページがロードしているときにデフォルトで表示されるスプラッシュ画面の有効または無効を切り替えるには、oracle.adf.view.rich.SPLASH_SCREENパラメータを使用します。

図A-1

このパラメータは、デフォルトでonに設定されています。スプラッシュ画面が表示されないようにするには、offに設定します。

A.2.3.22 グラフとゲージのイメージ形式

グラフ・コンポーネントとゲージ・コンポーネントのデフォルトの出力形式を変更するには、oracle.adf.view.rich.dvt.DEFAULT_IMAGE_FORMATパラメータを使用します。このコンテキスト・パラメータは、新しいアプリケーションに自動で追加されます。このコンテキスト・パラメータがあり、imageFormat属性(グラフのみ)を指定していないアプリケーションは、デフォルトでHTML5に自動で設定されます。

デフォルトでは、このパラメータはFLASHに設定され、グラフとゲージはFlashプレーヤーを使用して表示されます。プラグインがクライアント・マシンで使用できない場合や双方向ロケールの場合のように、Flashプレーヤーが使用できないときは、パラメータをHTML5に設定することもできます。

A.2.4 web.xmlのその他のコンテキスト・パラメータについて

アプリケーション全体に関わるその他のオプションのコンテキスト・パラメータは次のとおりです。

- javax.faces.CONFIG_FILES: 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ファイルです。小規模なアプリケーションには、通常、1つのfaces-config.xmlファイルがあります。

アプリケーションでADF Facesコンポーネントを使用する場合、JDeveloperでは、必要な構成要素がfaces-config.xmlに自動で追加されます。faces-config.xmlファイルの詳細は、Sun社のWebサイト(http://java.sun.com)の「Java EE 5 tutorial」を参照してください。

A.3.1 faces-config.xmlでのADF Facesの構成方法

JDeveloperでJSFテクノロジを使用するプロジェクトを作成すると、空のfaces-config.xmlファイルが/WEB-INFディレクトリに作成されます。JSFテクノロジを使用するアプリケーション・テンプレート(Java EE Webアプリケーション・テンプレートなど)を基に、新規アプリケーション・ワークスペースを作成した場合も、空のfaces-config.xmlファイルが自動的に追加されます。詳細は、2.2項「アプリケーション・ワークスペースの作成」を参照してください。

アプリケーションでADF Facesコンポーネントを使用する場合、ADFデフォルト・レンダー・キットIDをoracle.adf.richに設定する必要があります。JSFページへのADF Facesコンポーネントの最初の挿入時、またはFusionテンプレートを使用して作成されたアプリケーション・ワークスペースへの最初のJSFページの追加時、例A-4に示すとおり、ADFコンポーネントのデフォルト・レンダー・キットがfaces-config.xmlファイルにJDeveloperで自動的に挿入されます。

例A-4 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>

通常、次のものをtrinidad-config.xmlファイルで構成します。

- メッセージ・バンドル、サポートされているロケールなどのアプリケーション・リソース

- ページ間のナビゲーション・ルール

- カスタム・バリデータおよびコンバータ

- データを保持および処理、UIイベントの処理およびビジネス・ロジックの実行用マネージドBean

注意:

アプリケーションでADFコントローラを使用する場合、これらのアイテムはadfc-config.xmlファイルで構成されます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「タスク・フローの概説」を参照してください。

JDeveloperでは、宣言的概要エディタを使用してfaces-config.xmlファイルを変更できます。JSF構成要素に精通している場合は、XMLエディタを使用してコードを直接編集できます。

faces-config.xmlの編集手順:

1. アプリケーション・ナビゲータで、faces-config.xmlをダブルクリックし、ファイルを開きます。
JDeveloperでは、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ファイルを作成する必要があります。その後、アプリケーションで使用するアプリケーション全体のADF機能の構成を追加できます。

adf-config.xmlの作成と編集手順:

1. プロジェクト用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

2. META-INFディレクトリを右クリックし、「新規」を選択します。

3. 「新規ギャラリ」で「一般」を開き、「XML」→「XMLドキュメント」の順に選択し、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

4. ファイル名にadf-config.xmlと入力し、META-INFディレクトリに保存します。

5. ソース・エディタで、生成されたコードを例A-5のコードに置き換えます。

例A-5 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キャッシング・フィルタのキャッシング・ルールの定義

ADF Facesキャッシング・フィルタ(ACF)のキャッシング・ルールは、Webアプリケーションの.adf/META-INFディレクトリにあるadf-config.xmlファイルで定義されます。これらのURL一致ルールに対してリクエスト・パス内になるようにACFを構成する必要があります。ACFサーブレット・フィルタ定義の詳細は、A.2.3.17項「ADF Facesキャッシング・フィルタ」を参照してください。

1つ以上のキャッシング・ルールの単一ルート要素は、<caching-rules>です。これは、ネームスペースhttp://xmlns.oracle.com/adf/faces/configの<adf-faces-config>要素の子として構成されます。

<caching-rule>要素は各キャッシング・ルールを定義し、それぞれのルールは構成ファイルのリスト順に評価されます。例A-6に、adf-config.xmlでキャッシング・ルールを定義する構文を示します。

例A-6 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キャッシュにキャッシュされたオブジェクトのバージョニングに使用されます。1つの<varyBy>要素には、キャッシュされるオブジェクトのバージョニングのパラメータを定義する<vary-element>要素を1つ以上入れることができます。ほとんどの静的リソースには、この定義は必要ありません。

それぞれの<vary-element>は、次のように定義されます。

- <vary-name>: 有効な値は、値によってレスポンスが異なるCookie名の場合はcookieName、Webキャッシュにキャッシュされるオブジェクトのバージョンが値によって決まるHTTPヘッダー名の場合はheaderNameです。

- <vary-type>: 有効な値は、cookieまたはheaderです。

Webキャッシュは、リクエスト・パラメータを自動でバージョニングします。複数のバージョンのオブジェクトが、リクエスト・パラメータに基づいてWebキャッシュに格納されます。

A.4.3 コンポーネント出力形式としてのFlashの構成

アプリケーションは、デフォルトでコンポーネントごとに指定される出力形式を使用します。たとえば、ADFデータ視覚化コンポーネントは、アニメーションと対話効果をWebブラウザに表示するFlash出力形式を指定します。コンポーネントの出力形式がFlashで、ユーザーのプラットフォームがFlash Playerに対応していない場合(AppleのiOSオペレーティング・システムなど)、出力形式は、最適で利用可能な代替形式に自動でダウングレードされます。

アプリケーション全体でのFlashコンテンツの使用を構成にするには、adf-config.xmlでflash-player-usageコンテキスト・パラメータを設定します。有効な設定は次のとおりです。

- downgrade: 出力形式がFlashであっても、Flash Playerを使用できない場合は、最適で利用可能な代替形式にダウングレードするように指定します。Flash Playerのダウンロードは求められません。

- disable: アプリケーションでのFlashの使用を無効にするように指定します。Flash Playerをクライアントで使用できるかどうかに関係なく、すべてのコンポーネントは、Flash以外のバージョンでレンダリングされます。

例A-7に、adf-config.xmlでFlashをアプリケーション全体で無効にするための構文を示します。

例A-7 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の有効または無効を選択して切り替えることができます。

注意:

以前は、データ視覚化コンポーネントdvt:graphおよびdvt:gaugeは、imageFormat=AUTO"の値を使用していました。値AUTOは非推奨になったため、アプリケーション全体で同じ効果を実現するには、imageFormat="FLASH"を使用し、flash-player-usageコンテキスト・パラメータをdowngradeに設定する必要があります。

A.4.4 コンテンツ配信ネットワークの使用

コンテンツ配信ネットワーク(CDN)では、ネットワークでのコンテンツへのアクセスがさらに効率的になることで、Webアプリケーションのパフォーマンスが向上します。アプリケーションでは、様々なCDN構成を使用してユーザー・エクスペリエンスを最適化できます。CDNを介してすべてのリクエストをルーティングする構成がよく利用されるようになっています。CDNは、クライアントとアプリケーションとの間のプロキシとして機能します。CDN固有の構成ツールを使用して、キャッシングや圧縮のルールを指定できます。

また、CDNからルーティングされるリクエストを制限する方法もあります。たとえば、予備リソース(イメージ、JavaScriptライブラリ、スタイルシートなど)のリクエストのみをCDNに誘導し、アプリケーション生成HTMLコンテンツのリクエストを直接処理できます。この場合、相対リソースURIを、CDNで処理されるホストを指し示す絶対URIに変換する必要があります。

たとえば、アプリケーション定義のイメージが、imagesというローカル・ディレクトリに保存されるとします。イメージを参照するコードは、例A-8のようになります。

例A-8 デフォルトのイメージ参照

<af:image source="/images/logo.png"
shortDesc="My Company Logo"
id="i1"/>

例A-9に示すように、イメージをCDNから取得するには、イメージ・ソースの絶対URIを明示的に指定する方法があります。

例A-9 絶対URIを使用したCDNからのイメージ参照

<af:image source="http://mycdn.com/images/logo.png"
shortDesc="My Company Logo"
id="i1"/>

この方法では、アプリケーションの多くの場所(すべてのイメージ参照の可能性がある)を更新する必要があるため、ページ間でCDNベースURIが重複してしまうマイナス面があります。これにより、CDN使用の有効/無効が切り替えられたり、CDNから別の極めて困難なCDNに切り替えられたりする可能性があります。

あるいは、例A-10に示すように、リソース関連属性をELでバインドする方法もあります。

例A-10 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-11では、イメージ・ディレクトリのすべてのpngイメージが、http://mycdn.com接頭辞を含めて書き換えられるように指定されています。

例A-11 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-12の構成では、http://mycdn.com/接頭辞を、ADF Facesコンポーネントで定義されるすべてのイメージに適用しています。

例A-12

<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. 表A-2に示す要素を使用して、CDNの置換えURIを定義する書換えルールを作成します。

注意:

すべての属性値は、ELにバインドされます。ただし、ELにバインドされた属性の評価は一度のみです(解析時)。

表A-2 CDN URI書換え要素

要素

定義

<adf-uri-rewrite-config>

このxmlnsの値は、http://xmlns.oracle.com/adf/rewrite/configに設定する必要があります。

<resource-uris>

指定リソースのパスを書き換えるルールを定義します。

<base-resource-uri>

書き換えられたパスのベースURIを定義します。<base-resource-uri>要素を複数定義できます。この要素には次の3つの定義があります。

- uri: CDNのURIを設定します。これは、指定リソースのURI全体の作成に使用されます。

- secure-uri: URIがセキュアな場合の接頭辞(https://など)を設定します。

- output-context-path: 書き換えられたURIでアプリケーションに固有のコンテキスト・パスを削除するかどうかを決定します。有効な値は、remove(デフォルト)またはpreserveです。

<match-pattern>

レンダリングされるリソースURIに対してテストされる正規表現。一致が見つかった場合、リソースURIの先頭には、<base-resource-uri>要素で指定されるURIが付けられます。各<base-resource-uri>要素には、複数の<match-pattern>要素を定義できます。

実行時のオーバーヘッドを最小限に抑えるために、リソースURIの書換えの結果がキャッシュされることに注意してください。過度のキャッシュを防ぐには、<match-pattern>正規表現の対象を、静的リソースのみにします。動的に生成されるデータ中心リソース(バインドされていない問合せパラメータ値から生成されるリソースなど)は、ベース・リソースURIメカニズムを使用して書き換えないでください。

<match-alias>

ADF Facesで提供されるリソースのいずれかに一致するエイリアスを定義します。リソースは、次のいずれかになります。

- af:documents: ADF FacesのHTMLリソースに一致します(blank.htmlなど)。

- af:images: ADF FacesおよびTrinidadのイメージ・リソースに一致します。

- af:coreScripts: ADF FacesのブートおよびコアJavaScriptライブラリに一致します。

- af:skins: スキン生成スタイルシートに一致します。

各<base-resource-uri>要素に、複数の<match-alias>要素を定義できます。

一致要素に指定された値は、ExteralContext.encodeResourceURL()を通過するすべてのURIと比較されます。URIが一致した場合、囲んでいる<base-resource-uri>要素で指定された接頭辞が適用されます。

例A-13に、CDNを使用するように構成されるアプリケーションを示します。

例A-13 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"
output-context-path="remove">
<match-pattern>>^/.*/images/.*\.png$</match-pattern>
<match-alias>af:documents</match-alias>
<match-alias>af:coreScripts</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 JavaScriptおよびCDNについて

af:coreScriptsエイリアスを使用して、ADFの「コア」JavaScriptライブラリ(すべてのADFページにあるJavaScript)をCDNに書き換えることができます。また、<match-pattern>の正規表現を使用して、任意(アプリケーション定義など)のJavaScriptライブラリURIを書き換えることができます。ただし、JavaScriptライブラリがページに動的に導入されている場合(部分ページレンダリングの結果など)、いくつかの起源ポリシー制限が適用されます。その結果、クロスオリジン・ホストに書き換えられたJavaScriptライブラリURIはロードに失敗します。JavaScriptライブラリURIの書換えを、af:coreScriptsでり扱われるライブラリに制限し、アプリケーション提供ライブラリが既知の場合も、初期ページ・レンダーの一部(つまり、ライブラリはPPRリクエストの一部として導入されていない)として含まれるように制限する必要があります。

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. プロジェクト用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

2. META-INFディレクトリを右クリックし、ポップアップ・メニューから「新規」を選択します。

3. 「新規ギャラリ」で「一般」を開き、「XML」→「XMLドキュメント」の順に選択し、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

4. ソース・エディタで汎用コードを例A-14に示すコードに置き換えます。Webアプリケーション・ルートに対する正しい設定を使用します。

例A-14 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の要素について」を参照してください。

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-15に、登録されたヘルプ・プロバイダの例を示します。このケースでは、アプリケーションのヘルプ・プロバイダは1つのみのため、接頭辞を含める必要がありません。

例A-15 ヘルプ・プロバイダの登録

<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に基づいて様々なキャッシング・ルールを含めるadf-setting.xmlファイルを1つ以上入れることができます。キャッシング・ルールは、実行時に順序付リストにマージされます。リソースのリクエストが複数のキャッシング・ルールと一致した場合、リストの最初の該当ルールが優先されます。

ADF Faces JARには、.js、.css、イメージ・ファイル・タイプなどの共通リソース・タイプのデフォルトのキャッシング・ルールが含まれます。これらの固定ルールは、adf-settings.xmlファイルで定義されるため、アプリケーションのデプロイ時やデプロイ後に変更することはできません。アプリケーション開発者は、adf-settings.xmlで定義されるルールよりも優先されるadf-config.xmlファイルでアプリケーションのキャッシング・ルールを定義できます。例A-16に、ADF Faces JARのadf-settings.xmlファイルを示します。

例A-16 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構造を持ちます。

A.6.1 trinidad-config.xmlでのADF Facesの機能の構成方法

JDeveloperで、ADF FacesコンポーネントをJSFページへ初めて追加すると、trinidad-config.xmlの基礎ファイルが/WEB-INFディレクトリに自動的に作成されます。例A-17に、trinidad-config.xmlの基礎ファイルを示します。

例A-17 JDeveloperによって作成されるtrinidad-config.xml基礎ファイル

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://xmlns.oracle.com/trinidad/config">

<skin-family>blafplus-rich</skin-family>

</trinidad-config>

JDeveloperでは、ADF Facesを使用するJSFアプリケーションに対して、blafplus-richスキン・ファミリがデフォルトで構成されます。これをblafplus-medium、simpleに変更することも、カスタム・スキンを使用することもできます。カスタム・スキンを使用する場合は、trinidad-skins.xml構成ファイルを作成し、カスタム・スキンを使用するようtrinidad-config.xmlを変更します。カスタム・スキンの作成の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

通常、次のものをtrinidad-config.xmlファイルで構成します。

- ページ・アニメーション

- ページ・アクセシビリティ・サポートのレベル

- タイムゾーン

- 拡張デバッグ出力

- Oracle Help for the Web(OHW)のURL

ファイルのアップロードに使用するカスタム・ファイル・アップロード・プロセッサの登録もできます。

JDeveloperでは、XMLエディタを使用してtrinidad-config.xmlを変更できます。

trinidad-config.xmlの編集手順:

1. アプリケーション・ナビゲータでtrinidad-config.xmlをダブルクリックし、XMLエディタにファイルを開きます。

2. 要素名に精通している場合は、エディタに入力します。そうでない場合は、構造ウィンドウを使用して挿入します。

3. 構造ウィンドウで次のようにします。

1. 前に挿入または後に挿入メニューから選択する要素を右クリックし、挿入する要素をクリックします。

2. 構造ウィンドウで新たに挿入した要素をダブルクリックし、プロパティ・インスペクタで開きます。値を入力するか、ドロップダウン・リストが使用可能な場合はリストから選択します。
大抵の場合、JSF EL式(#{view.locale.language=='en' ? 'minimal' : 'blafplus-rich'}など)または静的値(<debug-output>true</debug-output>など)を入力できます。EL式は、リクエストごとに動的に再評価され、適切なオブジェクト(Booleanオブジェクトなど)を戻す必要があります。

使用できる構成要素のリストは、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コンポーネントでは、レンダリング時にアニメーションが使用されます。たとえば、ツリーおよびツリー表でノードを展開および縮小する際、アニメーションが使用されます。次のコンポーネントでレンダリング時にアニメーションが使用されます。

- ファセットを公開および非公開にする場合の表の詳細ファセット

- ノードを展開および縮小する際のツリーおよびツリー表

- メニュー

- ポップアップ・セレクタ

- ダイアログ

- ノート・ウィンドウおよびメッセージの表示

使用されるアニメーションのタイプとタイミングは、アプリケーションのスキンの一部として構成されます。詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

animation-enabled要素はtrueまたはfalseに設定できます。また、trueまたはfalseに解決されるEL式を使用できます。

注意:

アニメーションを有効にすると、パフォーマンスが影響を受けます。詳細は、『Oracle Fusion Middlewareパフォーマンス・ガイド』のOracleアプリケーション開発フレームワークのパフォーマンスのチューニングに関する項を参照してください。

A.6.2.2 スキン・ファミリ

A.6.1項「trinidad-config.xmlでのADF Facesの機能の構成方法」での説明のとおり、JDeveloperでは、ADF Facesを使用するJSFアプリケーションにblafplus-richスキン・ファミリがデフォルトで使用されます。<skin-family>の値をblafplus-medium、simpleに変更することも、カスタム・スキン定義に変更することもできます。カスタム・スキンの作成および使用の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

次のコードに示すように、スキン・ファミリ値に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で使用されて、文字列をDateに変換します。この要素は、値が設定されない場合、デフォルトで1950年に設定されます。必要な場合は、静的整数値またはIntegerオブジェクトと評価されるEL式を使用できます。

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 カスタム・ファイル・アップロード・プロセッサ

大半のアプリケーションでは、ADF Facesで用意されているデフォルトのUploadedFileProcessorインスタンスを置き換える必要はありません。しかし、アプリケーションで非常に大きなファイルのアップロードをサポートする必要がある場合、またはファイルのアップロードに大きく依存する場合、デフォルト・プロセッサをカスタムUploadedFileProcessor実装で置き換えることができます。

たとえば、ADF Facesでリクエスト時に一時格納を処理するかわりに、最終的な格納場所にファイルを即座に格納する実装を使用することにより、パフォーマンスを向上させることができます。デフォルト・プロセッサを置き換えるには、次のコードに示すように、<uploaded-file-processor>要素を使用してカスタム実装を指定します。

<uploaded-file-processor>
com.mycompany.faces.myUploadedFileProcessor
</uploaded-file-processor>

A.6.2.12 クライアント側検証および変換

ADF Facesのバリデータとコンバータでは、クライアント側の検証および変換とサーバー側の検証および変換がサポートされます。ADF Facesのクライアント側バリデータとコンバータは、クライアントでJavaScriptが使用される以外は、サーバー側バリデータとコンバータと同様に動作します。

JavaScript対応のバリデータとコンバータは、フォームの送信時にクライアントで実行されるため、サーバーへのラウンドトリップなしにエラーが捕捉されます。

リッチ・クライアント版のADF Facesでは、<client-validation-disabled>構成要素はサポートされていません。つまり、ADF Facesアプリケーションでは、クライアント側検証と変換を無効にできません。

A.7 trinidad-skins.xmlでの構成

JDeveloperでは、ADF Facesコンポーネントを使用してJSFページを作成する場合、blafplus-richスキン・ファミリがデフォルトで使用されます。スキン・ファミリは、A.6.1項「trinidad-config.xmlでのADF Facesの機能の構成方法」での説明のとおり、trinidad-config.xmlファイルで構成されます。アプリケーションにカスタム・スキンを使用する場合、アプリケーションへのカスタム・スキンの登録に使用されるtrinidad-skins.xmlファイルを作成します。

カスタム・スキンの作成の詳細は、第20章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

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: 現在のクライアント・リクエストに対する機能名(高さ、幅など)とその値のMapです。

- 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オブジェクトでのオブジェクトのMapを返します。

- 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ファイルから返します。

プロパティの一覧については、『Javadoc』の「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 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レイアウト・コンポーネントと一緒にストレッチ・パーティションにまとめられます。実行時、ページをロードすると、フレームワークはページで使用されるコンポーネントを決定し、そこから、必要な機能を決定します(機能名は、コンポーネントのコンストラクタ名と同じ)。これらの機能が含まれるパーティションのみがダウンロードされます。JavaScriptパーティション化の詳細は、1.2.1.2項「JavaScriptライブラリのパーティション化」を参照してください。

機能およびパーティションは、構成ファイルを使用して定義されます。ADF Facesには、デフォルトの機能およびパーティション構成ファイルが含まれています。独自の実装を作成することでデフォルトのパーティションを上書きできます。カスタムADF Facesコンポーネントを作成する場合、これらのコンポーネントに独自の機能およびパーティション構成ファイルを作成できます。

デフォルトでJavaScriptのパーティション化は有効にされています。アプリケーションでJavaScriptのパーティション化を使用するかどうかは、web.xmlファイルのコンテキスト・パラメータによって決定されます。JavaScriptのパーティション化の有効化および無効化の詳細は、A.2.3.14項「JavaScriptのパーティション化」を参照してください。

A.9.1 JavaScript機能の作成方法

adf-js-features.xml fileファイルを作成してから機能にエントリを追加することでJavaScript機能を作成できます。

注意:

カスタムADF Facesコンポーネントを作成する場合に、JavaScript機能を作成できます。すべての既存のADF Facesコンポーネントには、すでにそれらのコンポーネント向けに作成された機能があり、これらは変更できません。

JavaScript機能を作成する手順:

1. コンポーネント用のMETA-INFディレクトリの作成がまだの場合は、これを作成します。

2. META-INFディレクトリを右クリックし、ポップアップ・メニューから「新規」を選択します。

3. 「新規ギャラリ」で「一般」を開き、「XML」→「XMLドキュメント」の順に選択し、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

4. ファイル名にadf-js-features.xmlと入力し、META-INFディレクトリに保存します。

5. ソース・エディタで、生成されたコードを例A-5のコードに置き換えます。

例A-18 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>

6. 次の要素を追加すると、関連するコンポーネント・ファイルおよび依存性とともに機能が移入されます。

- 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つの機能が同じパーティションになくても、依存するクラスが使用できることを確認できます。

例A-19に、ポップアップ・コンポーネントを使用し、ポップアップ機能への依存性を持つ架空のカスタム・コンポーネントのfeature要素を示します。

例A-19 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>

A.9.2 JavaScriptパーティションの作成方法

adf-js-partitions.xmlファイルを作成してから機能にエントリを追加することでJavaScriptパーティションを作成できます。

注意:

ADF Facesには、デフォルトのadf-js-partitions.xmlファイルがあります(例A-22参照)。パーティションの構成を変更する場合は、独自の完全なadf-js-partitions.xmlファイルを作成する必要があります。実行時にフレームワークは、そのファイルのWEB-INFディレクトリを検索します。見つからない場合は、デフォルトのパーティション・ファイルがロードされます。

JavaScriptパーティションを作成する手順:

1. WEB-INFディレクトリを右クリックし、ポップアップ・メニューから「新規」を選択します。

2. 「新規ギャラリ」で「一般」を開き、「XML」→「XMLドキュメント」の順に選択し、「OK」をクリックします。

ヒント:

「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

3. ファイル名にadf-js-partitions.xmlと入力し、WEB-INFディレクトリに保存します。

4. ソース・エディタで、生成されたコードを例A-5のコードに置き換えます。

例A-20 adf-js-partitions.xmlファイルのXML

<?xml version="1.0" encoding="utf-8" ?>
<adf-js-features xmlns="http://xmlns.oracle.com/adf/faces/partition"

</adf-js-partitions>

5. 次の要素を追加すると、関連する機能とともにパーティションが移入されます。

- partitions: 構成ファイルのルート要素です。

- partition: partitions要素の子として作成されます。この要素には1つのpartition-name子要素および1つ以上のfeature要素が含まれている必要があります。

- partition-name: partition要素の子として作成されます。パーティションの名前を指定します。この値は、このパーティションのJavaScriptライブラリに一意のURLを作成するために使用されます。

- feature: partition要素の子として作成されます。このパーティションに含める機能を指定します。複数のfeature要素がある場合もあります。

ヒント:

adf-js-features.xmlファイルで構成され、パーティションに表示されない機能は、独自のパーティションに存在するものとして扱われます。

例A-21に、AdfRichTree機能およびAdfRichTreeTable機能を含むtreeパーティションのpartition要素を示します。

例A-21 JavaScriptパーティションの構成

<partition>
<partition-name>tree</partition-name>
<feature>AdfUITree</feature>
<feature>AdfUITreeTable</feature>
<feature>AdfRichTree</feature>
<feature>AdfRichTreeTable</feature>
</partition>

A.9.3 adf-js-partitions.xmlファイルについて

ADF Facesのデフォルトのadf-js-partitions.xmlファイルには、独自のパーティション・ファイルを作成することでオーバーライドできるパーティションがあります。詳細は、A.9.2項「JavaScriptパーティションの作成方法」を参照してください。例A-22に、ADF Facesのデフォルトのadf-js-partitions.xmlファイルを示します。

例A-22 デフォルトの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>

A.9.4 実行時の処理: 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ドキュメントの末尾直前でレンダリングされます。

B コンバータおよびバリデータ・メッセージのメッセージ・キー

この付録では、ADF Facesのコンバータおよびバリデータのすべてのメッセージ・キーおよびメッセージ・セッター・メソッドをリストします。

この章では、次の項目について説明します。

- B.1項「ADF Facesのデフォルト・メッセージの概要」

- B.2項「メッセージ・キーおよびセッター・メソッド」

- B.3項「コンバータおよびバリデータのメッセージ・キーおよびセッター・メソッド」

B.1 ADF Facesのデフォルト・メッセージの概要

FacesMessageクラスでは、サマリー・メッセージと詳細メッセージの両方がサポートされます。規則は次のとおりです。

- サマリー・メッセージはメイン・キーに対して定義されます。キー値の形式は、classname.MSG_KEYです。

- 詳細メッセージの形式は、classname.MSG_KEY_detailです。

簡単に言うと、詳細メッセージをオーバーライドするには、適切なクラスのセッター・メソッドを使用するか、必要なメッセージ・キーを使用してリソース・バンドルに置き換えるメッセージを入力します。

ユーザーが入力した値やメッセージ用のコンポーネントのラベルなどの関連する詳細の指定に、詳細メッセージではプレースホルダが使用されます。プレースホルダ識別子の一般的な順序は次のとおりです。

- コンポーネント・ラベル

- 入力値(存在する場合)

- 最小値(存在する場合)

- 最大値(存在する場合)

- パターン(存在する場合)

B.2 メッセージ・キーおよびセッター・メソッド

ADF Facesの各コンバータおよびバリデータについて、次の情報が提供されます。

- メッセージのオーバーライドに使用できるsetメソッド。

- リソース・バンドルで独自のメッセージの識別に使用できるメッセージ・キー。

- 入力値やパターンなどの詳細を含むプレースホルダのメッセージでの使用方法。

B.3 コンバータおよびバリデータのメッセージ・キーおよびセッター・メソッド

この項は、すべてのADF Facesコンバータおよびバリデータの詳細メッセージの詳細のリファレンスです。

B.3.1 af:convertColor

色の値を表す文字列とjava.awt.Colorオブジェクトとの間の変換を行います。変換に使用されるパターンのセットはオーバーライドできます。

色の変換: 入力値はパターン・セットに基づく色に変換できません

setメソッド:

setMessageDetailConvertBoth(java.lang.String convertBothMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.ColorConverter.CONVERT_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータに設定されたdateStyleとtimeStyleに基づく日付と時間の例

B.3.2 af:convertDateTime

パターンとスタイル・セットに基づき、文字列とjava.util.Dateとの間の変換を行います。

日時の変換: typeがbothに設定されている場合、Dateオブジェクトに変換できない日時の値

setメソッド:

setMessageDetailConvertBoth(java.lang.String convertBothMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.DateTimeConverter.CONVERT_BOTH_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータで想定されている書式の例

日付の変換: パターンまたは第2パターンが設定されているか、typeがdateに設定されている場合、入力値はDateに変換できません

setメソッド:

setMessageDetailConvertDate(java.lang.String convertDateMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.DateTimeConverter.CONVERT_DATE_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値
{2} コンバータで想定されている書式の例

日付の変換: パターンまたは第2パターンが設定されているか、typeがdateに設定されている場合、入力値はDateに変換できません

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であるか設定されていない場合、入力値はNumberに変換できません

setメソッド:

setMessageDetailConvertNumber(java.lang.String convertNumberMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_NUMBER_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値

数値の変換: typeがcurrencyに設定され、patternがNULLであるか設定されていない場合、入力値はNumberに変換できません

setメソッド:

setMessageDetailConvertCurrency(java.lang.String convertCurrencyMessageDetail)

メッセージ・キー:

org.apache.myfaces.trinidad.convert.NumberConverter.CONVERT_CURRENCY_detail

プレースホルダ:

{0} コンポーネントを識別するラベル
{1} ユーザーによって入力された値

数値の変換: typeがpercentに設定され、patternがNULLであるか設定されていない場合、入力値はNumberに変換できません

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が設定される場合、入力値は無効です

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項「ADFデータ視覚化コンポーネントのアクセラレータ・キー」

- C.5項「アクセス・キー」

- C.6項「デフォルトのカーソルまたはフォーカスの配置」

- C.7項「[Enter]キー」

C.1 キーボード・ショートカットの概要

ポインティング・デバイスのかわりにキーボード・ショートカットを使用してページのナビゲートを行えます。BLAF Plusアプリケーションで提供されるキーボード・ショートカットには次の5つのタイプがあります。

- [Tab]キーおよび[Shift]+[Tab]キーを使用したタブのトラバース: 画面上のUI要素間でフォーカスを移動します。

- アクセラレータ・キー(ホット・キー): メニューおよびページ・ナビゲーションを省略し、操作を直接実行します([Ctrl]+[C]によるコピーなど)。

- アクセス・キー: [Alt]+[F](Windowsの場合)で「ファイル」メニューに移動するなど、フォーカスを特定のUI要素に移動します。

- カーソル/フォーカスのデフォルトの配置: 1つのコンポーネントに初期フォーカスされているため、キーボード・ユーザーはあまり移動せずにページとの対話操作を開始できます。

- [Enter]キー: カーソルが特定のフィールドに置かれたり、フォーカスがリンクまたはボタンに置かれるとアクションが起動されます。

キーボード・ショートカットはアクセシビリティには必要ありません。ユーザーはキーボード・ショートカットなしで[Tab]キーや矢印キーを使用して、アプリケーションのすべての部分および機能にナビゲートできる必要があります。キーボード・ショートカットは、機能に迅速にアクセスするための追加の方法を提供するものです。

C.2 タブのトラバース

タブのトラバースを使用すると、ユーザーはページ上の様々なUI要素にフォーカスを移動できます。

タブのトラバースによって、つまり[Tab]キーを使用して次のコントロールに移動し、[Shift]+[Tab]を使用して前のコントロールに移動することで、ページのすべてのアクティブな要素にアクセスできます。多くの場合、コントロールにフォーカスがあるときに[Enter]を押すとアクションを開始できます。

複雑なコンポーネントでは、[Tab]キーを使用してコンポーネントにフォーカスを置いた後で、矢印キーを使用してナビゲートする場合もあります。

C.2.1 ページ上のタブのトラバースの順序

デフォルトのタブのトラバースの順序は、図C-1に示すように左から右、上から下です。2列のフォーム・レイアウトのタブのトラバースは、このパターンには従わず、列パターンに従って行われます。最下部に到達すると、タブの順序は上部から再度繰り返されます。

図C-1 ページ上のタブのトラバースの順序

タブのトラバースの順序の管理にカスタム・コードを使用しないようにしてください。結果のページの管理が難しくなりすぎて、1つのアプリケーションおよびアプリケーション間で、ページ全体のユーザー操作に一貫性がなくなる可能性があります。

ユーザーのキーボード・ナビゲーションの効率を向上するには、最初のコンテンツ関連のタブ位置に直接ナビゲートする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 アクセラレータ・キー

アクセラレータ・キーを使用すると、メニューやページのナビゲーションを経由せずにアクションを直接実行できます。アクセラレータ・キーは、ホット・キーと呼ばれることもあります。Internet ExplorerなどのWindowsアプリケーションには、[Ctrl]+[O]で開く、[Ctrl]+[P]で印刷などの共通のアクセラレータ・キーがあります。

アクセラレータ・キーは、キーを1回押す([Enter]および[Esc])またはキーの組合せ([Ctrl]+[A]など)によって、アクティブになるとすぐにアクションが開始します。キーの組合せはメタキーと実行キーで構成されます。メタキーは、[Ctrl](Macintoshキーボードでは[Command])、[Alt](Macintoshキーボードでは[Option]])または[Shift]になります。実行キーはメタキーと組み合せて押されるキーです。

BLAF Plusコンポーネントには、いくつかのビルトイン・アクセラレータ・キーがあります。カスタムのアクセラレータ・キーは、図C-3に示すように、メニューでのみサポートされています。

図C-3 メニューのアクセラレータ・キー

アクセラレータ・キーを定義する場合、次のガイドラインに従う必要があります。

- アクセラレータ・キーでは常に、マウスでの直接処理(ボタンをクリックする、ドラッグ・アンド・ドロップ)など別の操作が必要になります。

- アクセラレータ・キーはアクションを直接実行するため、ユーザーがアクセラレータ・キーを気付かずに押すと、データが失われたり、不適切なデータが入力されたりする可能性があります。ユーザーのエラーが発生する可能性を低くするため、アクセラレータ・キーは慎重に、アプリケーション全体で頻繁および繰り返し使用される機能にのみ使用する必要があります。原則として、アクセラレータ・キーを設定するのは使用可能な機能の25%未満にしてください。

- BLAF Plusがサポートされたブラウザのメニューで使用されるアクセラレータ・キーをカスタムのアクセラレータ・キーでオーバーライドすることはできません(BLAF Plusでサポートされるオペレーティング・システムおよびブラウザについてはブラウザおよびシステム要件を参照)。また、スクリーン・リーダーなどの支援技術で使用されるアクセラレータ・キーをオーバーライドすることもできません。

- カスタム・メニューのアクセラレータ・キーは、常にキーの組合せにする必要があります。メタキーは、[Ctrl]、[Ctrl]+[Shift]または[Ctrl]+[Alt]になります。[Ctrl]および[Ctrl]+[Shift]はブラウザでよく使用されるため、メタキーには[Ctrl]+[Alt]をお薦めします。実行キーは、印刷可能な文字である必要があります(ASCIIコード33から126)。

- カスタム・メニューのアクセラレータ・キーは、ページ全体でグローバルにする必要があります。1つのページの異なるメニューで同じアクセラレータが使用されていると、ブラウザはそのアクセラレータがどのアクションを実行するのかを予測することが常に困難になる場合があります。

注意:

Windowsの場合、ユーザーは[Ctrl]+[Alt]+文字キーの順番をアプリケーションのデスクトップ・ショートカットに割り当てることができます。この場合、このキー割当てがブラウザレベルのキーのキー割当てをオーバーライドします。ただし、この機能はめったに使用されないため通常は無視されます。

一部のBLAF Plusコンポーネントには、コンポーネントにフォーカスがあるときに適用されるビルトイン・アクセラレータ・キーがあります。そのうちの一部はページレベルのコンポーネントに予約されていますが、その他はそのコンポーネントがページに使用されていなければメニューに割り当てることができます。表C-1に、ページレベルのBLAF Plusコンポーネントにすでに組み込まれているアクセラレータ・キーを示します。これらのアクセラレータ・キーは、絶対に使用しないでください。

表C-1 ページレベルのコンポーネントに予約されたアクセラレータ・キー

アクセラレータ・キー

使用箇所

機能

[Ctrl]+[Alt]+[R]

アクティブ・データ

更新されたデータの確認

[Ctrl]+[Alt]+[W]

メニュー

メッセージング

2次ウィンドウ

ポップアップと1次ウィンドウとの間のフォーカスの切替え

[Ctrl]+[Alt]+[P]

スプリッタ

スプリッタ・バーへのフォーカスの移動

メニュー・コマンドは、ページレベルのコンポーネントと同じページ上にある場合に優先され、同じアクセラレータ・キーがあります。このため、関連するコンポーネントも同じページに表示されている場合、表C-2に示されているメニューのアクセラレータ・キーを使用しないでください。

表C-2 オプションのコンポーネントに割り当てられたアクセラレータ・キー

アクセラレータ・キー

コンポーネント

機能

[Ctrl]+[Alt]+[+]

リッチ・テキスト・エディタ

上付き

[Ctrl]+[Alt]+[-]

リッチ・テキスト・エディタ

下付き

[Ctrl]+[/]

階層ビューア

コンテンツ・パネルの切替え

[Ctrl]+[Alt]+[0]. . .[Ctrl]+[Alt]+[5]

階層ビューア

ダイアグラム・レイアウトの切替え

[Ctrl]+[5]

リッチ・テキスト・エディタ

取消し線

[Ctrl]+[A]

ファイルのアップロード

複数選択の選択肢リスト

複数選択のリスト・ボックス

ピボット・テーブル

リッチ・テキスト・エディタ

スピン・ボックス

テキストボックスおよび領域

表

すべて選択

[Ctrl]+[B]

リッチ・テキスト・エディタ

太字

[Ctrl]+[Alt]+[C]

リッチ・テキスト・エディタ

ソース・コード編集の切替え

[Ctrl]+[E]

リッチ・テキスト・エディタ

中央揃え

[Ctrl]+[H]

リッチ・テキスト・エディタ

ハイパーリンクの作成

[Ctrl]+[Shift]+[H]

リッチ・テキスト・エディタ

ハイパーリンクの削除

[Ctrl]+[I]

リッチ・テキスト・エディタ

イタリック体

[Ctrl]+[J]

リッチ・テキスト・エディタ

[Ctrl]+[L]

リッチ・テキスト・エディタ

両端揃え

[Ctrl]+[Shift]+[L]

リッチ・テキスト・エディタ

左揃え

[Ctrl]+[Alt]+[L]

リッチ・テキスト・エディタ

番号付きリスト

[Ctrl]+[M]

リッチ・テキスト・エディタ

インデントの増加

[Ctrl]+[Shift]+[M]

リッチ・テキスト・エディタ

インデントの減少

[Ctrl]+[Alt]+[M]

ガント

ピボット・テーブル

表

ツリー

ツリー表

ポップアップ・メニューの起動

[Ctrl]+[R]

リッチ・テキスト・エディタ

右揃え

[Ctrl]+[Alt]+[R]

リッチ・テキスト・エディタ

リッチ・テキスト編集の切替え

[Ctrl]+[Shift]+[S]

リッチ・テキスト・エディタ

テキスト・スタイルのクリア

[Ctrl]+[U]

リッチ・テキスト・エディタ

下線

[Ctrl]+[Y]

リッチ・テキスト・エディタ

やり直し

[Ctrl]+[Z]

リッチ・テキスト・エディタ

元に戻す

[Ctrl]+[Shift]+[^]

階層ビューア

ツリー

ツリー表

1つ上に移動

[Esc]

表

行のすべての編集の破棄と編集モードの無効化

[Enter]

[Shift]+[Enter]

表

列の次のセルまたは前のセルに移動

C.4 ADFデータ視覚化コンポーネントのアクセラレータ・キー

ADFデータ視覚化コンポーネントは、データを表示および分析するためのグラフィック機能と表機能を提供します。表C-3に、ガント・チャート・コンポーネント、階層ビューア・コンポーネント、ピボット・テーブル・コンポーネント、地理マップ・コンポーネントなどのADFデータ視覚化コンポーネントに割り当てられたアクセラレータ・キーを示します。ADFデータ視覚化コンポーネントの詳細は、第23章「ADFデータ視覚化コンポーネントの概要」を参照してください。

表C-3 ADFデータ視覚化コンポーネントに割り当てられたアクセラレータ・キー

アクセラレータ・キー

コンポーネント

機能

[←]

[→]

すべてのガント・チャート・タイプのリスト・リージョン

プロジェクト・ガントのチャート・リージョン

スケジュール・ガントのチャート・リージョン

リソース使用率ガントのチャート・リージョン

ADF地理マップ

ADF階層ビューア - ノード

ピボット・テーブル

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

フォーカスを移動します。

スケジュール・ガント・コンポーネントのチャート領域にフォーカスが配置されている場合、矢印キーのナビゲーションで現在の行の前または次のタスク・バーを選択します。

リソース使用率ガント・コンポーネントの時間バケットにフォーカスが配置されている場合、矢印キーのナビゲーションで現在の行の前または次の時間バケットを選択します。

ADF地理マップにフォーカスが配置されている場合、矢印キーのナビゲーションで左または右に少しずつパンします。[Home]または[End]キーを押すと大きくパンします。

ADF階層ビューア・コンポーネントのノード・コンポーネントにフォーカスが配置されている場合、[Ctrl]+矢印キーを押して、コンポーネントを選択せずにフォーカスを左右に移動します。

[↑]

[↓]

すべてのガント・チャート・タイプのリスト・リージョン

プロジェクト・ガントのチャート・リージョン

スケジュール・ガントのチャート・リージョン

リソース使用率ガントのチャート・リージョン

ADF地理マップ

ADF階層ビューア - ノード

ピボット・テーブル

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

フォーカスを移動します。

プロジェクト・ガントのチャート・リージョンにフォーカスが配置されている場合、矢印キーのナビゲーションで前または次の行を選択します。

スケジュール・ガント・コンポーネントのチャート領域のタスク・バーにフォーカスが配置されている場合、矢印キーのナビゲーションで前の行または次の行の最初のタスク・バーを選択します。

リソース使用率ガント・コンポーネントの時間バケットにフォーカスが配置されている場合、矢印キーのナビゲーションで前の行または次の行の時間バケットを選択します。

ADF地理マップ・コンポーネントにフォーカスが配置されている場合、矢印キーのナビゲーションで上または下に少しずつパンします。

ADF階層ビューアのノード・コンポーネントにフォーカスが配置されている場合、[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階層ビューア - ノード

ダイアグラムのレイアウトを切り替えます。

[Ctrl]+[Alt]+矢印キー

ピボット・テーブル

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

行、列またはフィルタ・レイヤーを新しい場所にピボットすることで、レイアウトを変更します。[Ctrl]+[Alt]+矢印キーを使用して次の操作を実行します。

- ヘッダー・レイヤーが選択されている場合、ビジュアル・フィードバックを提供してピボット操作の移動可能先を示します。

- 異なる移動先の場所を選択します。

- 選択されたヘッダー・レイヤーを指定された移動先に移動するか入れ替えます。

一部のADFデータ視覚化コンポーネントは、メニュー・バー、ツールバー、コンテキスト・メニューまたは「タスク・プロパティ」ダイアログを通じて共通の機能を提供します。これらの機能は、表示と非表示を切り替えたり、置換することができます。機能を非表示にするか、置換する場合、それらの機能に代替キーボード・アクセシビリティを割り当てる必要があります。

C.5 アクセス・キー

アクセス・キーはフォーカスを特定のUI要素に移動します。

アクセス・キーにより、カーソルまたは選択のフォーカスを特定のインタフェース・コンポーネントに移動できます。定義可能なフォーカスのあるページ上の各コンポーネントは、タブのトラバース([Tab]および[Shift]+[Tab]を使用)でアクセスできますが、アクセス・キーを使用すると、頻繁に使用されるコンポーネントに迅速にアクセスできます。アクセス・キーはページ内で一意であることが必要です。

アクセス・キーを押した結果は、関連付けられた要素およびブラウザによって異なります。

- ボタン: FirefoxおよびInternet Explorerでアクセス・キーを使用すると、コンポーネントにフォーカスが移動して直接アクションが実行されます。Internet Explorer 7でアクセス・キーを使用すると、コンポーネントがフォーカスされますが、アクションは実行されないことに注意してください。

- リンク: Firefoxでアクセス・キーを使用すると、コンポーネントにフォーカスが移動して直接リンクにナビゲートします。Internet Explorerでアクセス・キーを使用した場合は、フォーカスがリンクに移動するだけです。

- その他の要素: どちらのブラウザでアクセス・キーを使用した場合も、フォーカスが要素に移動するだけです。チェック・ボックス・コンポーネントの場合、アクセス・キーによってチェック・ボックスの選択が切り替わります。オプション・ボタンの場合、アクセス・キーによってオプション・ボタンが選択されます。

各種オペレーティング・システムの様々なブラウザでは、アクセス・キーが異なる点に注意してください。アクセス・キーとその動作の詳細は、ブラウザのドキュメントを参照する必要があります。表C-4に、一部の共通ブラウザのボタン・コンポーネントとアンカー・コンポーネントのアクセス・キーの組合せを示します。

表C-4 各種ブラウザのアクセス・キー

ブラウザ

オペレーティング・システム

キーの組合せ

アクション

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

[Control]+ニーモニック

クリック

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ユーザー・プリファレンスの構成設定を変更します。

- 名前がボタンとなっている一部のADF Facesコンポーネントでは、HTMLボタン要素は使用されません。たとえば、af:commandToolbarButtonでは、アンカーHTML要素が使用されます。

ニーモニックがコンポーネント・ラベルまたはプロンプトのテキストに存在する場合(メニュー名、ボタンのラベルまたはテキスト・ボックスのプロンプトなど)、図C-4に示すように下線付き文字としてインタフェースに表示されます。文字がラベルまたはプロンプトのテキストの一部でない場合は、インタフェースに表示されません。

図C-4 アクセス・キー

アクセス・キーを定義する場合、次のガイドラインに従う必要があります。

- アクセス・キーは、使用頻度の高いボタンおよびその他のコンポーネントに使用します。保存や取消などの共通するアクションに、クロスアプリケーションの標準的なキー割当てを設定できます。これらの各ボタンには保存はS、取消はCなど、各言語で標準的なニーモニック文字が割り当てられます。

- 1つの文字または記号は、1つのページのアクションの単一のインスタンスにのみ割り当てることができます。1つのページに、同じニーモニックを使用するボタンのインスタンスが複数あると、ユーザーがどのボタンでアクセス・キーが起動されるかわからなくなる可能性があります。

- アクセス・キーで開始されるフォーカス変更には、マウスでの直接処理(ボタンをクリックする)など、別の操作が必要になります。

- ニーモニックは句読点や記号ではなく英数字にする必要があり、大文字と小文字は常に区別されません。ニーモニックには、数字より文字を使用することをお薦めします。

- Internet Explorerでは、アプリケーションのアクセス・キーがブラウザ固有のメニュー・アクセス・キー(「ファイル」メニューの[Alt]+[F]など)をオーバーライドするため、習慣的にブラウザのアクセス・キーを使用するユーザーにユーザビリティの問題が生じる場合があります。このため、チームはBLAF Plusがサポートされたブラウザでは、トップレベルのメニュー・アクセス・キーと競合するアクセス・キーを使用しないでください(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.6 デフォルトのカーソルまたはフォーカスの配置

デフォルト・カーソルによって、キーボード・ユーザーが冗長なナビゲーションなしにページを操作できるように、コンポーネントに最初のフォーカスが配置されます。

フォーカスとは、ユーザーが[Tab]キーまたはアクセス・キーを押したときに、ページ内を移動する選択領域のことです。フォーカスがデータの入力が可能なフィールドに移動すると、フィールドにはカーソルが表示されます。フィールドにすでにデータが含まれている場合は、そのデータが強調表示されます。また、一部のコントロールを使用した後(値リスト(LOV)や日時ピッカーなど)、カーソルまたはフォーカスの配置はコンポーネントによって事前定義された特定の場所に移動します。

標準的なBLAF Plusページのロード中、フォーカスはページ上で最初のフォーカス可能なコンポーネント、つまり編集可能なウィジェットまたはナビゲーション・コンポーネント上に表示されます。そのページにフォーカス可能な要素がない場合、フォーカスはブラウザのアドレス・フィールドに表示されます。

デフォルトのカーソルおよびフォーカスの配置を定義する場合、次のガイドラインに従う必要があります。

- BLAF Plusアプリケーションでは、キーボード・ユーザーがページの上部でUI要素をタブで移動せずに、コンテンツ領域に直接アクセスできるように、大半のページでデフォルトのカーソルまたはフォーカスの配置を提供する必要があります。

- ページをロードする場合、デフォルト以外のコンポーネントにフォーカスを設定できます。ページにデータ・エントリの共通の開始点がある場合、ユーザーがキーボードやマウスでそれほど移動せずにデータ入力を開始できるようにフォーカスやカーソルのデフォルトの場所を変更できます。それ以外の場合、この操作は行わないでください。ページのロード後にキーボード・ユーザー(特に、スクリーン・リーダー・ユーザー)が自身の正しい位置を定めることがより難しくなるためです。

C.7 [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は、変換が必要なコンポーネントごとに、タッチ装置固有のピアとデスクトップ固有のピアをどちらも提供します(ピアの詳細は、1.2.1.1項「クライアント側のコンポーネント」を参照)。

これらのピアにより、コンポーネントは装置に固有のイベントを処理できます。たとえば、デスクトップのピアは、マウス・オーバー・イベントやマウス・アウト・イベントを処理し、タッチ装置のピアは、タッチ開始イベントとタッチ終了イベントを処理します。基本のピアは、共通の対話をすべて処理します。この区別によって、どちらの装置でも処理が最適化されます(タッチ・イベントの詳細は、表5-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番目の行を選択しても、最初の行の選択が自動で解除されるわけではありません。

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コンポーネントのベスト・プラクティス

コンポーネント/機能

ベスト・プラクティス:

ジオメトリ管理

ページのルート・パネル・コンポーネントの場合、dimensionsFrom属性をchildrenに設定し、その他にdimensionsFrom属性を使用するコンポーネントの場合、この属性を常にautoに設定します。これらの設定により、ページはストレッチではなく自由に動作します。詳細は、8.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。

部分ページ・ナビゲーション

部分ページ・ナビゲーションを使用すると、ページ間でJavaScriptなどのクライアント・コードをダウンロードする必要がないため、パフォーマンスが向上します。詳細は、7.4項「部分ページ・ナビゲーションの使用」を参照してください。

ナビゲーション

コンテンツの各部分への直接アクセスを提供します。適切なルールでは、1つのページに多くの領域を使用してスプリッタで分割するのではなく、ページごとに1つのタスクのみが使用されます。たとえば、左ペインのツリーでpanleSplitterを使用してナビゲートするのではなく、リストベースのナビゲーション・モデルを提供します。

E クイック・スタート・レイアウト・テーマ

この付録では、クイック・スタート・レイアウトにテーマを適用する場合にそれぞれのレイアウトが受ける影響について説明します。ADF Facesには、ページ全体のレイアウトを定義する際に使用可能なコンポーネントが多数用意されています。JDeveloperには、これらのコンポーネントを使用した事前定義済のクイック・スタート・レイアウトが含まれており、すばやく簡単にレイアウトを正しく構築できます。1列、2列または3列のレイアウトから選択できます。選択したクイック・レイアウトにテーマを適用する場合、クイック・スタート・レイアウトで使用されるコンポーネントの一部に色やスタイルが追加されます。

図E-1および図E-2に、テーマを適用した場合と適用しない場合のレイアウトをそれぞれ示します。テーマの詳細は、20.3.4項「コンポーネントへのテーマの適用方法」を参照してください。

図E-1 テーマを適用した場合と適用しない場合のクイック・スタート・レイアウト

図E-2 テーマを適用した場合と適用しない場合のクイック・スタート・レイアウト

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