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コンポーネントでは、ユーザーは2つの異なる方法で入力する項目を選択できます。1つは単純なドロップダウン・リストで、もう1つはinputListOfValuesコンポーネントでできるのと同じ検索です。図11-4に、リストがinputComboboxListOfValuesコンポーネントによってどのように表示されるかを示します。

図11-4 従業員名のリストが表示されたinputComboboxListOfValues

inputComboboxListOfValuesによりリストが表示されています

inputComboboxListOfValuesコンポーネントのドロップダウン・リストには、次の内容を表示できます。

完全なリスト: 図11-4に示したように、ListOfValuesModel.getItems()メソッドにより項目の完全なリストが戻されます。
お気に入りリスト: ListOfValuesModel.getRecentItems()メソッドにより、最近選択された項目のリストが戻されます。
検索リンク: ポップアップの「検索および選択」ダイアログが開かれるリンク。リンクは、ドロップダウン・リストのスクロール可能なリージョンにはありません。
customActionsファセット: その他のコンテンツを追加するためのファセット。通常、1つ以上のcommandLinkコンポーネントが含まれます。ポップアップ・ダイアログの起動など、目的のアクションを実行するには、commandLinkにロジックを実装してください。

inputListOfValuesコンポーネントのポップアップ・ダイアログや、inputComboboxListOfValuesコンポーネントのオプションの検索ポップアップ・ダイアログにも、新規レコードを作成する機能があります。inputListOfValuesコンポーネントの場合、コンポーネントにcreatePopupId属性が設定されていると、commandToolbarButtonを含むtoolbarコンポーネントが作成アイコンとともに表示されます。図11-5に示すように、実行時に、LOVポップアップ・ダイアログにcommandToolbarButtonコンポーネントが表示されます。

図11-5 ポップアップ・ダイアログのツールバーにある作成アイコン

ユーザーが「作成」ボタンをクリックすると、新規レコードの作成に使用できるポップアップ・ダイアログが表示されます。inputComboboxListOfValuesの場合は、ツールバーではなく、ダイアログ下部のcustomActionsファセットに「作成」というラベルのcommandLinkが表示されます。このリンクにより、ユーザーが新規レコードを作成できるポップアップが起動されます。どちらの場合も、実際に新規レコードを作成するためのコードを入力する必要があります。

ヒント:

独自の作成機能を作成するかわりに、Oracle ADF Business ComponentsおよびADFデータ・バインディングを使用できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「入力表の作成」を参照してください。

問合せコンポーネント同様、LOVコンポーネントもデータ・モデルに依存して機能を提供しています。このデータ・モデルは ListOfValuesModelクラスです。このモデルでは、値リストの表示に表モデルが使用され、問合せモデルにアクセスしてリストの検索を実行することも可能です。LOVコンポーネントを使用するには、指定されたインタフェースをListOfValuesModelに実装する必要があります。

ヒント:

独自のListOfValuesModelクラスを作成するかわりに、Oracle 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-6に、ListOfValuesモデルのクラス図を示します。

図11-6 ListOfValuesモデルのクラス図

ListOfValuesモデルおよび関連するイベントを作成する手順:

図11-6に示す各インタフェース・クラスの実装を作成します。表11-1にAPIを説明します。

表11-1 ListOfValuesモデルのAPI

メソッド	機能
`autoCompleteValue()`	コンポーネントで`autoSubmit`がtrueに設定されている場合、検索アイコンがクリックされるか、値が変更されてユーザーが[Tab]を使用して入力フィールドから移動するとコールされます。このメソッドにより、ダイアログを開くか、値をオートコンプリートするかが決定されます。このメソッドにより、フィルタ処理されたオブジェクトのリストが戻されます。
`valueSelected(value)`	値が「検索および選択」ダイアログから選択されて、「OK」ボタンがクリックされた場合にコールされます。このメソッドにより、モデルは選択された値に基づいてモデルを更新できます。
`isAutoCompleteEnabled()`	オートコンプリートを有効化するかどうかを決定するためにブールが戻されます。
`getTableModel()`	`TableModel`クラスの実装が戻されます。「検索および選択」ダイアログの表は、これに基づいて作成されます。
`getItems()`および`getRecentItems()`	コンボボックス・ドロップダウンに表示する`items`および`recentItems`リストが戻されます。`inputComboboxListOfValues`コンポーネントでのみ有効です。`inputListOfValues`コンポーネントにはnullが戻されます。
`getQueryModel()`および`getQueryDescriptor()`	「検索および選択」ダイアログに作成される`query`コンポーネントに基づいて`queryModel`が戻されます。
`performQuery()`	`query`コンポーネントの検索ボタンがクリックされるとコールされます。

ListOfValuesモデルの例として、ADF FacesアプリケーションのApplication Sourcesディレクトリにある、oracle.adfdemo.view.lovパッケージのDemoLOVBeanおよびDemoComboboxLOVBeanクラスを参照してください。

inputListOfValuesコンポーネントの場合は、リストの移入に使用された属性にアクセスするマネージドBean（LOVモデルの作成に使用されたものと同じマネージドBeanでもかまいません）にロジックを指定します。inputComboboxListOfValuesコンポーネントでは、getItems()およびgetRecentItems()メソッドを使用してリストが戻されます。
InputListOfValuesコンポーネントに使用される「検索および選択」ポップアップ・ダイアログの場合、またはInputComboboxListOfValuesコンポーネントに「検索および選択」ポップアップ・ダイアログを使用する場合は、ListOfValuesModel.autoCompleteValue()およびListOfValuesModel.valueSelected()メソッドを実装します。これらのメソッドによりポップアップ・ダイアログが開かれ、コンポーネントに選択された値が適用されます。

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

inputListOfValuesコンポーネントでは、11.2項「ListOfValuesデータ・モデルの作成」に記載されているように、項目のリストにアクセスするために実装したListOfValuesモデルが使用されます。モデルに検索APIも実装すると、コンポーネントでは、ユーザーがリスト内の値を検索することもできるようになります。

inputListOfValuesコンポーネントを追加する手順:

コンポーネント・パレットからページに値リストの入力コンポーネントをドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。
- model: 11.2項「ListOfValuesデータ・モデルの作成」で作成したように、ListOfValuesModel実装に解決されるEL式を入力します。
- value: 11.2項「ListOfValuesデータ・モデルの作成」で作成したように、リストへの移入に使用された属性値に解決されるEL式を入力します。
「外観」セクションを開き、次の属性値を設定します。
- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。
- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。
このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。
「動作」セクションを開き、次の属性値を設定します。
- autoSubmit: 該当するアクション（クリックやテキストの変更など）が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。
- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。これにより、定義したポップアップ・ダイアログにバインドされたcommandToolbarButtonコンポーネントを含む表の上にtoolbarコンポーネントが表示されます。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。
- launchPopupListener: ポップアップの起動時に追加の機能を提供するために実装するlaunchPopupListenerに解決されるEL式を入力します。
- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerコンポーネントに解決されるEL式を入力します。
このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。
ユーザーが新しい項目を作成できるようにする場合は、手順4で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。

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

inputComboboxListOfValuesコンポーネントを使用すると、ユーザーはドロップダウン・リストから値を選択し、inputListOfValuesコンポーネントと同じように、ページのLOVフィールドおよび可能な場合はその他のフィールドに移入できます。ただし、リストの値を完全なリストとして表示することや、最近参照した値ごとに表示することも可能になります。問合せAPIを実装していれば、11.2項「ListOfValuesデータ・モデルの作成」で説明されているように、ポップアップ・ダイアログで検索を実行するようにコンポーネントを構成することもできます。

inputComboboxListOfValuesコンポーネントを追加する手順:

コンポーネント・パレットからページにコンボボックス値リストの入力コンポーネントをドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。
- model: 11.2項「ListOfValuesデータ・モデルの作成」で作成したように、ListOfValuesModel実装に解決されるEL式を入力します。
- value: 11.2項「ListOfValuesデータ・モデルの作成」で作成したように、リストへの移入に使用された属性値に解決されるEL式を入力します。
「外観」セクションを開き、次の属性値を設定します。
- popupTitle: 「検索および選択」ポップアップ・ダイアログのタイトルを指定します。
- searchDesc: マウスが置かれた際にコンポーネントのヒントとして表示するテキストを入力します。
このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。
「動作」セクションを開き、次の属性値を設定します。
- autoSubmit: 該当するアクション（クリックやテキストの変更など）が実行された場合に、含まれているフォームがコンポーネントにより自動的に送信されるようにするにはtrueに設定します。これにより、オートコンプリートが機能します。
- createPopupId: リストに新規オブジェクトを作成するために使用されたポップアップ・ダイアログを実装した場合は、そのポップアップ・コンポーネントのIDを指定します。これにより、定義したダイアログにバインドされたcommandToolbarButtonコンポーネントを含む表の上にtoolbarコンポーネントが表示されます。ポップアップにダイアログを追加した場合は、表をリフレッシュするタイミングが自動的に決定されます。ポップアップにダイアログを追加しなかった場合、表は常にリフレッシュされます。
- launchPopupListener: ポップアップ・ダイアログが開かれる際に追加の機能を提供するために実装するlaunchPopupListenerハンドラに解決されるEL式を入力します。
- returnPopupListener: 値が戻された場合に追加の機能を提供するために実装するreturnPopupListenerハンドラに解決されるEL式を入力します。
このセクションの残りの属性は、その他の入力コンポーネントと同じ方法で移入できます。詳細は、9.3項「inputTextコンポーネントの使用方法」を参照してください。
ユーザーが新しい項目を作成できるようにする場合は、手順5で指定されたIDを使用してポップアップ・ダイアログを作成します。詳細は、第13章「ポップアップ・ダイアログ、メニューおよびウィンドウの使用方法」を参照してください。