コンポーネント・オブジェクト

JavaServer Faces (JSF) コンポーネントは、 追加の入出力機能およびビジュアル機能を 提供して、HTML DOM オブジェクトを拡張します。

JSF コンポーネント・オブジェクトの使用

オリジナルのタグ機能は、 コンポーネントによって、できるだけ多く保持されています。 これらによって、新規タイプのタグが提供されます。 例えば、日付ピッカーは <input type="datepicker"> タグと 見なすことができます。 このタグで作成されるオブジェクトによって、 入力タグのサイズ、CSS 属性、1 行表示、 タブ順序、z-order、言語特性、およびイベントが維持されます。

通常は、コンポーネントによって、 入力タグ、div、またはそのいずれかが拡張されます。 他のコンポーネント (例えば、メニュー項目) を ビルドするためには、若干数のコンポーネントを使用します。

コンポーネントのほとんどは、ページに可視要素を追加します。 例えば、カレンダー・コンポーネントは、 ページにカレンダーを描画します。 コンポーネントの可視要素は、CSS クラスのセットを介して制御されます。 通常、このクラスはコンポーネントの外観を定義しますが、 コンポーネント内の特定の要素の外観を 定義することもあります。

JSF コンポーネント・オブジェクトを使用するには、次のようにします。
  1. オブジェクトのスタイルを設定するには、CSS をページに追加します。 例えば、次のようにします。
    <style>
    .button1, .button1_moused {
        width:100px;
        height:21px;
    }
    .button1_Label, .button1_Label_moused {
        font-family:sans-serif;
        color:black;
        font-size:14px;
        text-align:left;
        margin-left: 24px;
    }
    </style>
  2. 振る舞いを適用するタグを、ページ内に追加します。 例えば、次のようにします。
    <input type="submit" class="MenuBar_button2b" id="form1:button2" alt="New" title="New" value="New" />
  3. DOM オブジェクトにコンポーネントを与えます。 例えば、次のようにします。
    <script>
        hX.addComponent("form1:button2", new hX.JSFImage("normal:img/search-button.gif", 
        "moused:img/search-button-moused.gif", "label:New"));
    </script>
この例では、 イメージ・コンポーネントによって、入力タグが変更されます。 テキスト付きのイメージが表示され、 マウス操作で表示内容を変更します。

コンポーネントの作成/検索を行う hx 呼び出し

それぞれのコンポーネント は、Javascript コンストラクターを使用して構成 され、addComponent 呼び出しを介してページに追加されます。

hX_5.addComponent ("id", new hX_5.JSFName(attributes)); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

name

JSF コンポーネントの名前。

属性

コンマで区切られた属性のリスト。 各属性は、属性名と値から成る引用符付きストリングになっており、 コロンで区切られています (例: "label:MyLabel")。

注: DOM オブジェクトには、 コンポーネントを 1 つだけ与えることができます。

一部のコンポーネント (例えばメニュー・バー) には、 サブコンポーネントが含まれています。 サブコンポーネントを構成するには、次のようにします。

hX_5.addSubComponent ("parent-id", "id", new hX_5.JSFName(attributes), position);

parent-id

このサブコンポーネントの親である JSF コンポーネントの ID。

id

コンポーネントが付加される HTML タグの ID。

name

JSF コンポーネントの名前。

属性

コンマで区切られた属性のリスト。 各属性は、属性名と値から成る引用符付きストリングになっており、 コロンで区切られています (例: "label:MyLabel")。

position

同じ親を持つ他のサブコンポーネントに相対する、 このサブコンポーネントの位置。 省略した場合、サブコンポーネントが追加されます。

以下の構文を使って、 サブコンポーネントをまとめて追加することもできます。

hX_5.addSubComponent ("parent-id", [ new hX_5.JSFName(attributes), ... ]); 各部の意味は次のとおりです。

parent-id

このサブコンポーネントの親である JSF コンポーネントの ID。

name

JSF コンポーネントの名前。

属性

コンマで区切られた属性のリスト。 各属性は、属性名と値から成る引用符付きストリングになっており、 コロンで区切られています (例: "label:MyLabel")。

サブコンポーネントを削除するには、次のようにします。

var x = hX_5.removeSubComponent("parent-id", "id"); 各部の意味は次のとおりです。

parent-id

このサブコンポーネントの親である JSF コンポーネントの ID。

id

コンポーネントが付加される HTML タグの ID。

特定のコンポーネント・オブジェクトを取得するには、次のようにします。

var o = hX_5.getComponentById("id"); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

returns

コンバーターの JavaScript™ オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

DOM オブジェクト内の すべてのコンポーネント (例えば、div 内のタグに与えられた すべてのコンポーネント) を取得するには、次のようにします。

var a = hX_5.getComponentsInId("id"); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

returns

コンバーターの JavaScript オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

サブコンポーネント・オブジェクトを取得するには、次のようにします。

var o = hX_5.getSubComponentById("id"); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

returns

コンバーターの JavaScript オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

サブコンポーネントの親を取得するには、次のようにします。

var x = hX_5.getParentComponentById("id"); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

returns

コンバーターの JavaScript オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

コンポーネントにおける共通 API 呼び出し

コンポーネントまたはサブコンポーネントの 属性を変更するには、次のようにします。

c.setAttribute("arg"); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

arg

JSF 属性/値のストリング。

コンポーネントまたはサブコンポーネントの属性を取得するには、 次のようにします。

var x = c.getAttribute("argname"); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

argname

属性名を含むストリング。

returns

コンバーターの JavaScript オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

基本タグの属性またはプロパティーに行った 変更内容が反映されるように、 コンポーネントを再描画するには、次のようにします。 属性またはプロパティーを変更する場合に、 使用してください。

var x = c.redraw(); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

アクティブな UI 要素を コンポーネント内でリリースする (例えば、 コンポーネント内でボタンを選択解除する) には、 次のようにします。

var x = c.uirelease(); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

コンポーネントの値を設定するには、次のようにします。 入力タグがベースになるコンポーネントの場合は、 入力タグの値属性の設定と同じ作業になります。 ただし、入力される値が有効であることを 確認する (つまり、変換および検証が行われる) 点が異なります。

var x = c.setValue("string"); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

string

変換されるストリング

コンポーネントの値を取得するには、次のようにします。 入力タグがベースになるコンポーネントの場合は、 入力タグの値属性の取得と同じ作業になります。 ただし、ストリング以外のものに値をキャストできる点が異なります。

var x = c.getValue(boolean); 各部の意味は次のとおりです。

c

コンポーネント・オブジェクト。

boolean

該当する型の JS オブジェクトに、戻り値をキャストします。

returns

コンバーターの JavaScript オブジェクトの型 (数値、日付/時刻、またはストリング)。 変換できない場合は、null が戻され、lastError が設定されます。

基礎となるオブジェクトでの変更への応答

コンポーネントによって、HTML DOM の 基本オブジェクトを変更します。 例えば、日付ピッカーによって入力タグを変更します。 プログラマチックな変更が 基本タグに加えられる場合 (例えば、タグを使用不可にする)、 コンポーネントが変更内容を取得して、変更を反映します。

例えば、基本タグを使用不可にすると、 コンポーネントも使用不可となります。 ブラウザーの制限やコンポーネント実装の制限のために、 変更内容の取得および反映が行われないこともあります。 基本タグが変更された場合、 コンポーネントが変更内容を取得していなければ、 変更が行われたことを、 ユーザーがコンポーネントに通知する必要があります。 この作業は、 コンポーネントの再描画機能を 呼び出すことによって行います。
 // html タグを取得して、使用不可にします
var obj = document.getElementById("form1:text1");
obj.disabled = true;
 // コンポーネントに変更を認知させます
var c = hX_5.getComponentById("form1:text1");
c.redraw();

基本オブジェクト・スタイルに対して、 直接的 (スタイル・プロパティーを設定) または 間接的 (CSS ルールを変更) に行われた変更は、取得されません。 これらの場合には、ユーザーが再描画を 呼び出す必要がありますので、注意してください。

基本オブジェクトの特定の属性 またはプロパティーについては、変更できない場合があります。 こうした制限はまれにしか起きませんが、 その場合はコンポーネントの文書に記載されます。 通常、こうした制限は値に固有のものとなります。 例えば、コンポーネントをプロポーショナル・サイズから 絶対サイズへ変更することはできません。

表 1. コンポーネント・オブジェクト

コンポーネント

説明

JSFCalendar 入力フィールドを、 ミニ・カレンダーに変更します (日付の選択に使用できます)。
JSFColorPicker 入力フィールドを、 コンボ・ボックスに変更します (色の選択に使用します)。
JSFDataTable 垂直スクロール、 選択などといった JSF DataTable 拡張機能用の、 クライアント・サイドの相互作用を管理します。
JSFDatePicker ミニ・カレンダー (日付の選択に使用できます) を ポップアップ表示するボタンが組み込まれるように、 入力フィールドを変更します。
JSFDialog div を、モーダル/モードレス・ダイアログ・ボックスに変更します。
JSFImage 複数のイメージまたはテキストを組み込めるように、 または複数の状態 (normal、mouse-overed、depressed、disabled) を持てるように、 あるいはその両方が実現されるように、ボタンまたはイメージを変更します。
JSFMenu div を、メニュー またはツリー状のメニュー (メニュー・バー) に変更します。
JSFMenuItem (サブコンポーネント) メニュー内の要素。
JSFProgressBar div を進行状況表示バーに変更します。
JSFSection div を、縮小/拡張が可能なセクションに変更します。
JSFSlider スライダー (フィールドの値の選択に使用できます) を 表示するボタンが組み込まれるように、入力フィールドを変更します。
JSFSpinner スピナー・ボタンのペア (指定された間隔で フィールド値を増分または減分するために使用できます) が組み込まれるように、入力フィールドを変更します。
JSFTwistie HTML イベント・ハンドラーに、バインド機能またはアクションを提供します。
関連概念
JSF ウィジェット・ライブラリー (JWL)

フィードバック