値ピッカーと名前ピッカー

値ピッカーでは、ユーザーはリストから 1 つ以上の値を選択できます。名前ピッカーでは、ユーザーはリストから 1 つ以上の名前を選択できます。値は、関連付けられたコントロールに適用されます。どちらのピッカーも似た機能を持ちます。

ピッカーの使用

ピッカーによってレンダリングされるアイコンをクリックすると、ダイアログがトリガーされます。

ピッカーは、for プロパティによって別のコントロールと関連付けられます。関連付けられたコントロールが値を持つ場合、ピッカーはその値を初期選択値として使用します。ユーザーが [OK] ボタンをクリックしてピッカーダイアログを閉じると、選択された値が、関連付けられたコントロールに適用されます。

ピッカーは、関連付けられたコントロールが 1 つの値を受け入れるかそれとも複数の値を受け入れるかを認識し、それに従って適切な動作を行います。また、ピッカーは必要に応じて、複数の値を区切るための文字も認識します。

ピッカーはさまざまなソースのデータを表示でき、異なるレンダリングを行うことができます。

表示するデータの選択

ピッカーは複合タイプの dataProvider を使用して、選択データにアクセスします。これによって UI とデータが分離され、各種のデータソースを使用できるようになります。各データプロバイダには独自のプロパティセットがあり、これらのプロパティは [すべてのプロパティ] タブで設定できます。

このリストにはデフォルトのプロバイダが表示されます。リストはグローバルベースまたはアプリケーションベースで拡張可能です。

名前ピッカーでも同様に、ユーザーが複数のディレクトリから選択することができます。これは、データプロバイダアグリゲータを使用することで実現されます。データプロバイダアグリゲータは、他の具体的な実装を代理として使用するカスタムデータプロバイダです。以下の例は、Domino® アドレス帳と、現在のデータベース内のビューの両方のデータを示しています。

データプロバイダによって返される値には、オプションのラベルが付いていることがあります。ピッカーはラベルを表示し、値を保管します。

ピッカー UI の設定

値ピッカーにも名前ピッカーにも、デフォルトのレンダリングが用意されています。これは、値ピッカーの場合は基本リストで、名前ピッカーの場合はより複雑なダイアログになります。

dojoType プロパティと dojoAttributes プロパティを使用すると、その他のユーザーインターフェースを割り当てることができます。例えば、以下の値を設定して、チェックボックスダイアログを適用することができます。

入力補完の有効化

typeAhead コントロールをピッカーとともに使用できます。データセットが基本リストであるかカスタムマークアップである場合、ピッカーはそのデータを、入力補完コントロールによる予想内容に適応させます。

入力補完を設定するには、typeAhead コントロールを、ピッカーに関連付けられたコントロールに追加し、以下のプロパティを設定します。

<xp:typeAhead mode="partial" minChars="1" preventFiltering="true">

preventFiltering プロパティを使用すると、入力補完においてデータのフィルタリングがデータプロバイダによって実行されるようになります。これは必須ではありませんが、使用することでコントロールのパフォーマンスが向上します。mode="partial" プロパティを使用すると、入力補完要求が発生した場合に、入力補完コントロールのみがトリガーされるようになります。

入力補完の候補式を指定して、ピッカーからの入力を取得します。

カスタムデータプロバイダの指定

カスタムデータプロバイダを指定することができます。以下のようなことが可能です。

値ピッカー simpleDataProvider に JavaScript を使用する。
データプロバイダの実装により、開発者がサーバーサイド JavaScript を実行できるようになります。JavaScript をシンプルに保つため、このプロバイダはストリング値のみを返し、関連付けられたラベルは返しません。
以下のような JavaScript をコーディングできます。
```
var a = new Array("a","b","c","d","e","f","g","h")
return a
```
valueListSeparator を指定すると、単一ストリングを返すことができます。
```
return "a,b,c,d,e,f,g,h"
```
値/名前ピッカー用の管理 Bean beanXXXPicker を使用する。
この方法を用いると、新しい複合タイプを XPages ランタイムに登録せずに、データプロバイダの全機能を使用できるようになります。この方法を選択できるのは、プロバイダがアプリケーションに固有のものである場合です。
- データの種類に応じて、IValuePickerData または INamePickerData を実装する JavaScript クラスを作成します。デモアプリケーションの SimplePicker クラスを参照してください。
- beanXXXPicker データプロバイダを追加し、このデータプロバイダがご使用の Bean を参照するようにします。クラス名を指定すると、必要に応じてインスタンスが作成されます。Bean のライフサイクルを細かく制御するには、管理 Bean を使用して、その公開名を dataBean プロパティで使用します。

カスタム UI の指定

開発者は、ピッカー用のカスタム UI を指定することができます。これを行うには、新しい dijit を定義するカスタム Dojo モジュールを使用します。この dijit によって、extlib.dijit.TemplateDialog を拡張します。これは必須ではありませんが、この基本クラスを拡張すると、ポップアップダイアログの表示、ブラウザの違いへの対応、いくつかの一般的なイベント (OK や Cancel など) の処理が容易になります。

XPages ランタイムは、実行時に dijit に渡されるパラメータセットを生成します。dijit に渡される代表的なパラメータは以下のとおりです。

dlgTitle: the title of dialog
control: the client id of the associated input text
url: the REST service URL
sources: an optional array of source (directory list)

カスタムピッカーレンダラを使用すると、これを拡張することができます。詳しくは、非常にシンプルな dijit が定義されている PickerCheckbox.js ファイルを参照してください。このファイルでは、REST サービスを呼び出す方法、REST サービスが入力テキストとやり取りする方法、データリストに基づいてチェックボックスを作成する方法が示されています。