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

この章では、ADF Facesクライアント側アーキテクチャの概要を説明します。

この章の内容は次のとおりです。

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

• JavaScriptのページへの追加

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

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

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

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

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

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

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

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

ADF Facesは、ブラウザ固有のDocument Object Model (DOM) APIをラップする複雑なクライアント側アーキテクチャを公開し、内部フレームワークで使用されるクライアント側JavaScriptオブジェクトとしてADF Facesコンポーネントをレンダリングします。これを、ADF Facesコンポーネント開発者やADF Facesアプリケーション開発者が使用します。

ADF Facesは、JavaServer Facesアーキテクチャを拡張し、標準のサーバー中心モデルの上にクライアント側フレームワークを追加しています。ADF Facesコンポーネントの大部分は、リクエストのためにサーバー側で生成されるHTMLにレンダリングされます。また、ADF Facesでは、クライアント側コンポーネントとイベント・モデルを使用してクライアントに到達できるようにコンポーネントを実装できます。

ADF Facesフレームワークには、JavaScriptを使用するために通常必要な機能の多くがすでに含まれています。多くの場合、JavaScriptを使用しなくても、リッチなコンポーネント機能を宣言的に実現できます。ただし、クライアント側イベントに対するカスタム処理など、独自のJavaScriptを追加する必要がある場合があります。このような場合は、クライアント側フレームワークを使用できます。

最も多く対話対象となるJavaScriptクラスはAdfUIComponentとそのサブクラスです。このクラスのインスタンスは、サーバー側コンポーネントのクライアント側表現です。クライアント側コンポーネントは、イベント処理がサポートされる簡単なプロパティ・コンテナとみなすことができます。クライアント側コンポーネントは、主に、アプリケーション開発者とフレームワーク自体の両方に対するAPI規定を公開することでページに動作を追加するためにあります。たとえば、クライアントでのボタンの状態の切替えを可能にするのは、この規定です。

各クライアント・コンポーネントには、プロパティ(キーと値のペア)のセットと、サポートされている各イベント・タイプ用のリスナーのリストがあります。すべてのADF Faces JavaScriptクラスは、他のJavaScriptライブラリと名前が競合しないようAdfで始まります。たとえば、RichButtonはAdfButtonを持ち、RichDocumentはAdfRichDocumentを持つなどです。

クライアント側JavaScriptレイヤーでは、クライアント・コンポーネントは主にフレームワークおよび開発者にAPI規定を提供するために存在します。クライアント・コンポーネントは、状態を格納し、APIを提供するためにのみ存在するため、DOM (Document Object Model)と直接対話しません。DOMとのすべての対話は、ピアと呼ばれる媒介を使用して行われます。ピアでは、Javaレンダラによって生成されたDOMと対話し、状態の更新とユーザーとの対話へのレスポンスが処理されます。

ピアでは、この他に次のような多くの処理が行われます。

• DOMの初期化とクリーンアップ

• DOMのイベント処理

• ジオメトリ管理

• 部分ページ・レスポンスの処理

• 子の可視性の変更の処理

この分離により、コンポーネントおよびアプリケーション開発者がコンポーネントのDOM実装の変更から隔離され、コンポーネント(たとえば、Flashコンポーネント)がHTML DOMで実装されているかどうかをアプリケーションが知る必要もまったくなくなります。

大部分のコンポーネントベースのフレームワーク同様、JSFのコンポーネント・モデルに固有の特性は、コンポーネントはネストして階層(通常コンポーネント・ツリーと呼ばれる)を形成できるということです。これは、親コンポーネントで子が追跡され、コンポーネント・ツリーをたどって特定のコンポーネントの子孫をすべて見つけることができるということです。コンポーネント・ツリー全体はサーバーにあり、ADF Facesクライアント側コンポーネント・ツリーにはあまり移入されません。

パフォーマンスを最適化するために、クライアント・コンポーネントは、clientListenerハンドラが登録されているため、またはページ開発者がクライアント側のコンポーネントと対話する必要があり、クライアント・コンポーネントを使用可能として構成したため必要になった場合にのみ存在します。例外的なケースを除き、クライアント・フレームワークを理解する必要はありません。アーキテクチャ機能の大部分は、コードを作成せずに宣言的に使用できます。

たとえば、フレームワークでは、各サーバー側コンポーネントに対応するクライアント・コンポーネントをすべて作成するわけではないため、クライアント版のコンポーネント・インスタンスが必要な場合もあります。「クライアント側コンポーネントのインスタンス化」に、これを宣言的に行う方法が説明されています。JDeveloperの「プロパティ」ウィンドウを使用して、「レンダリングおよび可視性の理解」で説明されている、コンポーネントをレンダリングするかどうか、あるいは非表示にするかどうかを決めるプロパティを設定します。

注意:

既存のサーバー側コンポーネントに対応しないJavaScriptコンポーネントが存在することも可能です。たとえば、一部のADF Facesコンポーネントでは、ポップアップ・コンテンツが必要なクライアント側動作を持ちます。これらのコンポーネントでは、サーバー側Java RichPopupコンポーネントが存在しなくても、AdfRichPopup JavaScriptコンポーネントを作成できます。

その他の機能では、ADF Faces JavaScript APIの使用が必要な場合があります。たとえば、「ページでのクライアント・コンポーネントの検索」では、APIを使用して特定のクライアント側コンポーネントを探す方法を説明し、「クライアントでのコンポーネント・プロパティへのアクセス」では、特定のプロパティにアクセスする方法を説明しています。

JavaScriptを多用したフレームワークに共通する問題は、大規模なJavaScriptコード・ベースをクライアントに送信する最良の方法を決定することです。すべてのコードが単一のJavaScriptライブラリにある場合はダウンロード時間が長くなりますが、JavaScriptを多くのライブラリに分割しすぎると、ラウンドトリップが大量になります。この問題を軽減するために、ADF FacesではJavaScriptコードがパーティションに集約されます。JavaScriptライブラリ・パーティションには、コンポーネントのコードまたは通常一緒に使用される機能、あるいはその両方が含まれています。「JavaScriptライブラリのパーティション化」を参照してください。

JavaScriptのページへの追加

ADF Facesは、アプリケーション開発者がクライアント側の開発ユースケースを実装するために使用するJavaScript APIを公開します。ADF FacesビューでJavaScriptを使用するには、JavaScriptコードをページ・ソースに追加するか、外部ライブラリ・ファイルでコードを参照します。

インラインJavaScriptをページに直接追加するか、JavaScriptライブラリをページにインポートできます。ライブラリをインポートする場合は、ページ・コンテンツ・サイズが削減され、ライブラリをページ間で共有でき、ブラウザによってキャッシュできます。可能な場合には必ずJavaScriptライブラリをインポートする必要があります。インラインJavaScriptは、ページ固有の小さなスクリプトが必要な場合にのみ使用します。

パフォーマンスのヒント:

インラインJavaScriptは、レスポンス・ペイロード・サイズを増加させる可能性があり、ブラウザにまったくキャッシュされないため、ブラウザのレンダリングをブロックすることがあります。インラインJavaScriptを使用するかわりに、すべてのスクリプトをJavaScriptライブラリに配置することを検討してください。

インラインJavaScriptを使用する必要がある場合、必要とするページにのみこれを含めます。ただし、ほとんどのページで同じJavaScriptコードが使用されている場合、スクリプトを含めることを検討するか、テンプレートにライブラリをインポートしてください。

JavaScriptコード・ライブラリが非常に大きくなった場合、ライブラリを内容に応じて分割し、(テンプレートに配置しないで)ページで必要な部分のみを含めることに注意してください。この方法で、ブラウザ・キャッシュが使用され、ページのHTMLコンテンツが小さくなるため、パフォーマンスが向上します。

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

JavaScriptをページに作成し、clientListenerタグを使用して呼び出します。

始める前に:

ページへのJavaScriptの追加に関する知識が役立つ場合があります。詳細は、「JavaScriptのページへの追加」を参照してください。

インラインのJavaScriptを使用する手順:

1. 太字で示すコードを追加して、MyFaces Trinidadタグ・ライブラリをページのルート要素に追加します。

   <f:view xmlns:f="http://java.sun.com/jsf/core"
           xmlns:h="http://java.sun.com/jsf/html"
           xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
           xmlns:trh="http://myfaces.apache.org/trinidad/html">
   

2. 「コンポーネント」ウィンドウのレイアウト・パネルにあるCore Structureグループの中のリソースをページ上にドラッグ・アンド・ドロップします。

   注意:

   ページまたはテンプレートにf:verbatimタグを使用してJavaScriptを指定しないでください。

3. 「リソースの挿入」ダイアログで、ドロップダウン・メニューから「JavaScript」を選択し、「OK」をクリックします。
4. ページの<af:resource>タグ内にJavaScriptを作成します。

   たとえば、次のようなJSFページにsayHelloファンクションを含めることができます。

   <af:resource>
     function sayHello()
     {
       alert("Hello, world!")
     }
   </af:resource>
   

5. 「構造」ウィンドウで、JavaScriptを起動するコンポーネントを右クリックし、「コンポーネントの中に挿入」→「ADF Facesコア」→「クライアント・リスナー」を選択します。
6. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドにJavaScript関数の名前を入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

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

af:resourceタグを使用して、ページからJavaScriptライブラリにアクセスします。このタグは、documentタグのmetaContainerファセットの内部に含める必要があります。

始める前に:

ページへのJavaScriptの追加に関する知識が役立つ場合があります。詳細は、「JavaScriptのページへの追加」を参照してください。

ページからJavaScriptライブラリにアクセスする手順:

1. documentタグの下に、次の太字で示すコードを追加し、JavaScriptライブラリが含まれるディレクトリへの相対パスに/mySourceDirectoryを置き換えます。

   <af:document>
     <f:facet name="metaContainer">
       <af:resource source="/mySourceDirectory"/>
     </facet>
     <af:form></af:form>
   </af:document>
   

2. 「構造」ウィンドウで、JavaScriptを起動するコンポーネントを右クリックし、「コンポーネントの中に挿入」→「ADF Facesコア」→「クライアント・リスナー」を選択します。
3. 「クライアント・リスナーの挿入」ダイアログで「メソッド」フィールドに関数の名前を入力します。タイプ・フィールドで、関数を起動するイベント・タイプを選択します。

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

JavaScriptでクライアント・コンポーネントにアクセスする必要がある場合、リスナーのコンテキストで行われ、イベントのソース・コンポーネントにアクセスする必要がある場合がしばしばあります。getSource()メソッドを使用してクライアント・コンポーネントを取得します。次の例に、名前を表示するためにソース・クライアント・コンポーネントにアクセスするsayHello関数を示します。

function sayHello(actionEvent)
{
  var component=actionEvent.getSource();
  
  //Get the ID for the component
  var id=component.getId();

  alert("Hello from "+id);
}

クライアント・イベント・ソースへのアクセスの詳細は、「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。クライアント側プロパティへのアクセスの詳細は、「クライアントでのコンポーネント・プロパティへのアクセス」を参照してください。実行時のクライアント・イベントの処理の詳細は、「実行時の処理: クライアント側イベントの機能の仕方」を参照してください。

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

ADF Facesフレームワークは、自動的にJavaScriptオブジェクトのインスタンス化を処理します。クライアント・コンポーネントとの対話をサポートし、コンポーネントがクライアント側インスタンスを保持するように開発者が手動で構成する際に便利です。

デフォルトでは、フレームワークでは、どのコンポーネントが、対応するクライアント側コンポーネント・インスタンスを持つかについて保証されません。クライアント上のコンポーネントと対話するには、通常はclientListenerハンドラを登録します。登録されているclientListenerハンドラがコンポーネントにある場合、コンポーネントはクライアント側表現を自動的に持ちます。clientComponent属性をtrueに設定して、コンポーネントがクライアントで使用できるよう明示的に構成することもできます。

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

clientComponent属性を使用してクライアント側インスタンスを持つようにコンポーネントを手動で構成できます。

パフォーマンスのヒント:

クライアントのコンポーネントとプログラムで対話する場合にのみclientComponentをtrueに設定します。

注意:

フレームワークが独自に使用するためにクライアント・コンポーネントを作成する場合、そのクライアント・コンポーネントにはその時点でフレームワークが必要とする情報のみ含まれます。たとえば、一部の属性は使用可能でない場合があります。

始める前に:

クライアント側インスタンスに関する知識が役立つ場合があります。「クライアント側コンポーネントのインスタンス化」を参照してください。

クライアント側インスタンスのコンポーネントを構成する手順:

1. 「構造」ウィンドウで、クライアント側インスタンスを必要とするコンポーネントを選択します。
2. 「プロパティ」ウィンドウでClientSideをtrueに設定します。

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

clientComponent属性をtrueに設定すると、コンポーネントのAdfUIComponentクラスのインスタンスがフレームワークで作成されます。このクラスでは、クライアント側で操作できるAPIが提供され、基本的なプロパティ・アクセッサ・メソッド(getProperty()、setProperty()など)、イベント・リスナーの登録およびイベント配信関連のAPIも提供されます。フレームワークには、プロパティ固有のアクセッサ・メソッド(getText()、setText()など)を公開するレンダラ固有のサブクラス(AdfRichOutputTextなど)も用意されています。これらのアクセッサ・メソッドは、AdfUIComponentクラスのgetProperty()およびsetProperty()メソッドをラップするのみのラッパーで、コーディングが簡便になるよう用意されています。

たとえば、sayHello関数から値(表示するテキスト)を取得するoutputTextコンポーネントがページにあるとします。この関数は、値を設定するためにoutputTextコンポーネントにアクセスできる必要があります。次のJSFページ・コードに示すように、これが機能するには、クライアント側バージョンのoutputTextコンポーネントがある必要があります。outputTextコンポーネントにid値があり、clientComponent属性がtrueに設定されていることに注意してください。また、値はJavaScriptで設定されるため、例には値がないことにも注意してください。

<af:button text="Say Hello">
  <af:clientListener method="sayHello" type="action"/>
</af:button>

<af:outputText id="greeting" value="" clientComponent="true">

outputTextにクライアント側表現があるため、JavaScriptでこれを見つけて使用できます。

注意:

クライアント・リスナーがない場合やclientComponent属性がtrueに設定されていない場合でも、ADF Facesフレームワークは自身の目的のためにクライアント・コンポーネントを作成することがあります。ただし、これらのクライアント・コンポーネントは完全に機能しない場合があります。

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

ADF Facesクライアント・コンポーネント・オブジェクトは、af:clientListenerタグを追加することによって作成できます。これはクライアント側リスナー・スクリプトを登録して、特定のイベント・タイプが発生するときに実行させる、宣言的な方法です。クライアント・リスナーは、プログラム的に作成されたコンポーネント、または独自に使用するために作成されたコンポーネントに適用でき、JSFページからのナビゲートも制御できます。

従来のJSFアプリケーションでは、クライアントでイベントを処理する場合、DOMレベルのイベントをリスニングする必要があります。ただし、これらの実装は移植可能な形式で配信されません。ADF Facesのクライアント側イベント・モデルはJSFイベント・モデルと似ていますが、クライアントで実装されます。クライアント側イベント・モデルはDOMの要約で、コンポーネントレベルのイベント・モデルとライフサイクルが提供され、サーバーから独立して実行されます。このため、ボタンのclickイベントをリスニングする必要がありません。かわりに、キーまたはマウスのイベントで発生するAdfActionEventイベントをリスニングできます。

クライアントによって送信されるイベントはすべてAdfBaseEventクラスのサブクラスです。各クライアント・イベントには、イベントをトリガーしたコンポーネントであるソースがあります。イベントには、イベントをリスニングするリスナーを判断するタイプ(actionまたはdialogなど)もあります。クライアント・リスナーは、af:clientListenerタグを使用してコンポーネントに宣言的に登録します。

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

af:clientListenerタグを使用して、クライアント・イベントに対して対応するJavascriptをコールします。たとえば、クリックされたら"Hello World"アラートを表示する必要のあるボタンがあるとします。最初に、アラートを表示することでイベントに応答するJavaScript関数を作成する必要があります。次に、その関数を呼び出すクライアント・リスナーをコンポーネントに追加します。

始める前に:

クライアント・イベント処理に関する知識が役立つ場合があります。「クライアント・イベントのリスニング」を参照してください。

クライアント・イベントをリスニングする手順:

1. JavaScript関数を実装します。たとえば、アラートを表示するには、次に示すJavaScript関数を作成できます。

   function sayHello(event)
     {
       alert("Hello, world!")
     }
   

2. 「コンポーネント」ウィンドウで、「操作」パネルの「リスナー」グループから「クライアント・リスナー」を、イベントを発生させる子としてコンポーネントにドラッグ・アンド・ドロップします。

   ステップ1で作成した関数と、リスナーが応答する必要のあるアクションのタイプを入力します。次の例に、sayHello関数のリスナーに対して作成するコードを示します。

   <af:button text="Say Hello">
     <af:clientListener method="sayHello" type="action"/>
   </af:button>
   

ヒント

ボタンにクライアント・リスナーが登録されているため、フレームワークで、クライアント版のコンポーネントが自動的に作成されます。

クライアント版のコンポーネントがあるため、ボタンがクリックされると、AdfActionクライアント・イベントが起動されます。AdfActionイベントをリスニングするようclientListenerタグが構成されているため、sayHello関数が実行されます。クライアント側イベントの詳細は、「ADF Facesクライアント・イベントに対するJavaScriptの使用」を参照してください。

ADFクライアント・リスナーをJSFページからの移動の制御に使用する方法

ADF FacesアプリケーションでJSFページを表示するブラウザを閉じようとするときに、ネイティブ・ブラウザの確認ダイアログを表示してナビゲーションを確認することにより、ページからの移動を制御できます。このタイプのイベントを処理するために、af:documentコンポーネンはタイプbeforeunloadのADFクライアント・リスナーの呼出しをサポートし、ADF Facesアプリケーションが、一部のブラウザで問題の原因となる可能性のある、実行順序の未定義にならないようにします。特に、このタイプのナビゲーション・イベントを、window.addEventListener("beforeunload", function(e) {...}などのブラウザのネイティブのbeforeunloadハンドラを使用して処理しないでください。

Oracle ADFのonbeforeunloadイベントのサポートを使用して、af:documentコンポーネントでイベント・ハンドラをコールするクライアント・イベント・リスナーを定義できます。ADFイベント・ハンドラは現在のページから離れるまたはリロードが発生する前に呼び出され、ユーザーはADF Facesフレームワークの実行の中で完全な終了をキャンセルすることができます。ユーザーがページからの移動を継続する場合、ブラウザによりwindow.unloadイベントが発生し、ADF Facesアプリケーションは終了します。

たとえば、クライアント・リスナーはブラウザのネイティブのbeforeunloadハンドラ用のハンドラの動作と似たような方法でADF beforeunloadイベントを処理でき、ユーザーに終了のキャンセルを求める文字列を返す必要があります。

...
<af:document>
   <af:resource type="javascript">
   function myBeforeUnload(beforeunloadEvent)
   {
     return "Are you sure that you want to leave?"
   }
   </af:resource>
   <af:clientListener type="beforeunload" method="myBeforeUnload"/>

ADF beforeunloadハンドラが呼び出されたとき、未定義以外の値が返されると、現在のページから実際に移動するのかどうかを尋ねる、ブラウザ制御の警告ダイアログが表示されます。ブラウザによっては、返される文字列は、警告ダイアログの一部として表示されることがあります。警告メッセージは、ハンドラに渡されたADF beforeunloadオブジェクトでsetWarningMessageメソッドを呼び出すことによっても設定できます。

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

ADF Facesは、JavaServer Facesアーキテクチャを拡張し、標準のサーバー中心モデルの上にクライアント側フレームワークを追加しています。JavaScriptを使用すると、クライアントでコンポーネント属性プロパティを取得または設定できます。

コンポーネントの各組込みプロパティには、簡易アクセッサ・メソッドがコンポーネント・クラスに用意されています。たとえば、クライアント・コンポーネントでgetValue()メソッドをコールし、サーバーで使用されたのと同じ値を受け取ることができます。

注意:

ADF Faces内のブール・プロパティを含むすべてのクライアント・プロパティでgetXyz関数命名規則を使用します。ブール・プロパティのisXyz命名規則は使用されません。

定数もクラス・オブジェクトのプロパティ名に使用できます。たとえば、styleClassを使用するかわりにAdfRichDialog.STYLE_CLASS定数を使用できます。

注意:

一部のJavaScript実行環境では、文字列をコーディングすると呼出しのたびにオブジェクトを割り当てる必要があるため、JavaScriptでは、文字列をコーディングするよりも定数を参照する方が効率的です。

コンポーネントのプロパティが変更されると、最終的な結果として、コンポーネントのDOMが新しい状態を反映するように更新されます。場合によっては、サーバーへのラウンドトリップは発生しません。このプロセスにおけるコンポーネントのロールはかなり限られています。新しいプロパティ値を格納してから、変更をピアに通知するだけです。ピアには、新しいコンポーネント状態を反映するようにDOMを更新するロジックが含まれます。

注意:

すべてのプロパティの変更が、クライアント側のピアを使用して処理されるわけではありません。一部のプロパティ変更はサーバーに伝播され、PPRを使用してコンポーネントがレンダリングされます。

クライアントに設定されるほとんどのプロパティ値は、サーバーとの自動同期が行われる原因になります(ただし、一部の複合Javaオブジェクトはクライアントにまったく送信されません)。ただし、これとは異なる動作をするセキュア・プロパティと分離プロパティの2種類のプロパティがあります。

セキュア・プロパティは、クライアントにまったく設定できないプロパティです。たとえば、悪意のあるクライアントでJavaScriptを使用してLinkコンポーネントのimmediateフラグがtrueに設定されるとします。この変更がサーバーに伝播された結果、サーバー側の検証が省略され、セキュリティ・ホールとなる可能性があります(immediateプロパティの使用の詳細は、「immediate属性の使用」を参照してください)。つまり、immediateプロパティはセキュア・プロパティです。JavaScriptからセキュア・プロパティの設定を試みると失敗します。「無効化されたプロパティを非保護にする方法」を参照してください。

ADF Facesでは、disabledプロパティを非保護にできるように構成できます。この機能は、JavaScriptを使用してボタンを有効および無効にする必要がある場合に役立ちます。ADF Facesセキュア・クライアントプロパティのリストは、「セキュア・クライアント・プロパティ」を参照してください。

分離プロパティは、クライアントで設定できるがサーバーに伝播することはできないプロパティです。これらのプロパティには、サーバーのライフサイクルに依存しないクライアント上のライフサイクルがあります。たとえば、クライアント・フォーム入力コンポーネント(AdfRichInputTextなど)には、JavaのEditableValueHolderコンポーネントのようにsubmittedValueプロパティがあります。ただし、このプロパティの設定はサーバーに直接影響しません。この場合、標準のフォーム送信手法によって、送信された値のサーバーでの更新を処理します。

プロパティは、分離とセキュアの両方にすることができます。実際には、このようなプロパティはクライアント上で分離プロパティのように動作します。これらはクライアントで設定できますが、サーバーには送信されません。ただし、サーバーではセキュア・プロパティとして動作するため、クライアントがこれらを設定しようとすると拒否されます。

セキュア・クライアント・プロパティ

セキュア・プロパティは、クライアントでは設定できず、セキュリティ・ホールを防ぐプロパティです。表4-1に、クライアント・コンポーネントのセキュア・プロパティを示します。

表4-1 セキュア・クライアント・プロパティ

コンポーネント	セキュア・プロパティ
AdfRichChooseColor	colorData
AdfRichComboboxListOfValue	disabled readOnly
AdfRichCommandButton	disabled readOnly blocking
AdfRichCommandImageLink	blocking disabled partialSubmit
AdfRichCommandLink	readOnly
AdfRichDialog	dialogListener
AdfRichDocument	failedConnectionText
AdfRichInputColor	disabled readOnly colorData
AdfRichInputDate	disabled readOnly valuePassThru
AdfRichInputFile	disabled readOnly
AdfRichInputListOfValues	disabled readOnly
AdfRichInputNumberSlider	disabled readOnly
AdfRichInputNumberSplinBox	disabled readOnly maximum minimum stepSize
AdfRichInputRangeSlider	disabled readOnly
AdfRichInputText	disabled readOnly secret
AdfRichPopUp	launchPopupListener model returnPopupListener returnPopupDataListener createPopupId
AdfRichUIQuery	conjunctionReadOnly model queryListener queryOperationListener
AdfRichSelectBooleanCheckbox	disabled readOnly
AdfRichSelectBooleanRadio	disabled readOnly
AdfRichSelectManyCheckbox	disabled readOnly valuePassThru
AdfRichSelectManyChoice	disabled readOnly valuePassThru
AdfRichSelectManyListBox	disabled readOnly valuePassThru
AdfRichSelectManyShuttle	disabled readOnly valuePassThru
AdfRichSelectOneChoice	disabled readOnly valuePassThru
AdfRichSelectOneListBox	disabled readOnly valuePassThru
AdfRichSelectOneRadio	disabled readOnly valuePassThru
AdfRichSelectOrderShuttle	disabled readOnly valuePassThru
AdfRichUITable	filterModel
AdfRichTextEditor	disabled readOnly
AdfUIChart	chartDrillDownListener
AdfUIColumn	sortProperty
AdfUICommand	actionExpression returnListener launchListener immediate
AdfUIComponentRef	componentType
AdfUIEditableValueBase	immediate valid required localValueSet submittedValue requiredMessageDetail
AdfUIMessage.js	for
AdfUINavigationLevel	level
AdfUINavigationTree	rowDisclosureListener startLevel immediate
AdfUIPage	rowDisclosureListener immediate
AdfUIPoll	immediate pollListener
AdfUIProgress	immediate
AdfUISelectBoolean	selected
AdfUISelectInput	actionExpression returnListener
AdfUISelectRange	immediate rangeChangeListener
AdfUIShowDetailBase	immediate disclosureListener
AdfUISingleStep	selectedStep maxStep
AdfUISubform	default
AdfUITableBase	rowDisclosureListener selectionListener immediate sortListener rangeChangeListener showAll
AdfUITreeBase	immediate rowDisclosureListener selectionListener focusRowKey focusListener
AdfUITreeTable	rangeChangeListener
AdfUIValueBase	converter

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

ADF Facesフレームワークには、基礎となるADFUIComponent.setProperty関数をコールして適切なプロパティ名を渡す便利なsetXYZ関数が用意されています(詳細は、Oracle ADF Faces JavaScript APIリファレンスを参照してください)。次のコードに、setProperty関数を使用して、値が変更されたときにinputTextコンポーネントのbackgroundcolorプロパティを赤に設定する方法を示します。

<af:form>
  <af:resource type="javascript">
    function color(event) {
        var inputComponent = event.getSource();
        inputComponent.setproperty("inlineStyle", "background-color:Red");
    }
  </af:resource>
  <af:outputText id="it" label="label">
    <af:clientListener method="color" type="valueChange"/>
  </af:inputText>
</af:form>

これらの関数を使用してプロパティの値を変更できます。分離プロパティまたはセキュア・プロパティでないかぎり、値はサーバー上でも変更されます。

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

クライアントでsetProperty()関数をコールすると、プロパティが新しい値に設定され、同時にPropertyChangeEventイベントが古い値と新しい値を使用して起動されます(値が異なる場合)。また、プロパティを設定すると、コンポーネントが自身を再レンダリングする場合があります。

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

デフォルトでは、無効化されたプロパティは保護されたプロパティです。つまり、JavaScriptを使用してそれをクライアント上に設定することはできません。ただし、disabledプロパティを非保護に設定するには、unsecuredプロパティを使用します。disabledプロパティを非保護にする必要のあるコンポーネントのコードに、このプロパティとdisabledの値を手動で追加する必要があります。たとえば、disabledプロパティを非保護にする必要のあるボタンのコードは次のようになります。

<af:button text="commandButton 1" id="cb1" unsecure="disabled"/>

disabled属性が保護状態の場合、アプリケーションはdisabled属性により、アクション・イベントを配布する必要がないときには配布されないようにできます。disabled属性を非保護にすると、サーバーはそのdisabled属性を正しいものとして信頼できなくなります。このため、ユーザーはactionListenersを使用して同等のチェックを実行する必要があります。

たとえば、支出承認ページがあり、そのページで特定のマネージャが$200未満の請求書のみ承認できるようにするとします。そのため、現在のユーザーが請求書の承認を許可されていないかぎり、承認ボタンを無効にする必要があります。disabled属性を非保護にしないと、承認ボタンは、サーバーへのラウンドトリップが発生するまで無効のままになります。現在のユーザーが経費を承認できるかどうかはロジックが決定します。つまり、レンダリングのときに、ボタンが現在のユーザーに対して正しく表示されないことがあります。ページがロードされる際に、ボタンを正しく表示するには、unsecure属性をdisabledに設定し、クライアント上でJavaScriptを使用してボタンを無効にするかどうか決定します。ただし、この場合は、任意のJavaScript(制御できない悪意のあるJavaScriptを含む)が同じことを行う可能性があります。

悪意のあるJavaScriptを回避するには、ボタンにactionListenerを使用してサーバー上でロジックを実行します。サーバーにロジックを追加すると、無効な属性を変更してはならない場合に、それが変更されません。支出承認の例では、承認を実行する前にJavaScriptを使用して金額が$200以下であることをチェックし、また、ボタンにactionListenerを使用して現在のマネージャに適切な支出権限があることを再度チェックする必要があります。

同様に、アプリケーションを実行時に変更できるようにし、ユーザーがunsecureまたはdisabled属性、あるいはその両方を編集できるようにする場合は、サーバーとのラウンドトリップが発生した場合と同じロジックがアプリケーションによって実行されるようにする必要があります。

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

プロパティの値をサーバーに常に配信して同期することは望ましくない場合があります。たとえば、フォームにinputTextコンポーネントがあり、ユーザーがコンポーネントの1つで値を変更したらすぐに、変更済インジケータを表示するとします。この操作を行うには、JavaScriptを使用して、valueChangeEventイベントが配信されたらクライアント・コンポーネントのchanged属性をtrueに設定します。また、ユーザーがページを送信した場合は、その時点で値が保存されるため、変更済インジケータを表示しません。

次のように、JavaScriptを使用して、valueChangeEventが配信されたらchanged属性をtrueに設定します。

<af:form>
  <af:resource type="javascript">
    function changed(event) {
        var inputComponent = event.getSource();
        inputComponent.setChanged(true);
    }
  </af:resource>
  <af:inputText id="it" label="label">
    <af:clientListener method="changed" type="valueChange"/>
  </af:inputText>
  <af:button text="Submit"/>
</af:form>

コンポーネントのすべてのプロパティは一般にサーバーと同期されるため、この例を使用すると、changed属性の値(true)はサーバーにも送信されます。このため、変更済インジケータは引き続き表示されます。

値がサーバーに保存されたときにインジケータを表示しないようにするには、次のいずれかの代替方法を使用できます。

• イベント・リスナーを使用して、ロジックをクライアントからサーバーに移動します。次に示すように、この代替方法は、valueChangeEventイベントなど、サーバーに配信されるイベントがある場合に使用します。

  <af:form>
    <af:inputText label="label"
                  autoSubmit="true"
                  changed="#{test.changed}"
                  valueChangeListener="#{test.valueChange}"/>
    <af:button text="Submit" />
  </af:form>
  

  次の例に、対応するマネージドBeanコードを示します。

  import javax.faces.event.ValueChangeEvent;
  import oracle.adf.view.rich.context.AdfFacesContext;
   
  public class TestBean {
      public TestBean() {}
      
      public void valueChange(ValueChangeEvent valueChangeEvent) 
      {
        setChanged(true);
        AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
        adfFacesContext.addPartialTarget(valueChangeEvent.getComponent());   
        FacesContext.getCurrentInstance().renderResponse();
      }
      
      public void setChanged(boolean changed) 
      {
          _changed = changed;
      }
   
      public boolean isChanged() 
      {
          return _changed;
      }    
      private boolean _changed;
  }

• 次に示すように、カスタム・サーバー・イベントとserverListenerタグを呼び出すJavaScriptを使用して、ロジックをサーバーに移動します。この方法は、配信されるイベントがない場合に使用します。

  <af:form>
    <af:resource type="javascript">
      function changed(event) 
      {
        var inputComponent = event.getSource();
        AdfCustomEvent.queue(inputComponent, "myCustomEvent", null, true);
      }
    </af:resource>
    <af:inputText label="label" changed="#{test2.changed}">
      <af:serverListener type="myCustomEvent"
                         method="#{test2.doCustomEvent}"/>
      <af:clientListener method="changed" type="valueChange"/>
    </af:inputText>
    <af:button text="Submit"/>
  </af:form>
  

  次の例に、マネージドBeanコードを示します。

  package test;
   
  import javax.faces.context.FacesContext;
   
  import oracle.adf.view.rich.context.AdfFacesContext;
  import oracle.adf.view.rich.render.ClientEvent;
   
  public class Test2Bean
  {
    public Test2Bean()
    {
    }
   
    public void doCustomEvent(ClientEvent event)
    {
      setChanged(true);
      AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
      adfFacesContext.addPartialTarget(event.getComponent()); 
      FacesContext.getCurrentInstance().renderResponse();
    }
   
    public void setChanged(boolean changed)
    {
      _changed = changed;
    }
   
    public boolean isChanged()
    {
      return _changed;
    }
    private boolean _changed;
   
  }

• クライアント・コンポーネントでchanged属性をtrueに設定し、これがサーバーに伝播されますが、その後コマンド・コンポーネントでactionListenerを使用して、changed属性をfalseに戻します。次に、JSFコードを示します。

  <af:form>
    <af:resource type="javascript">
      function changed(event) {
        var inputComponent = event.getSource();
        inputComponent.setChanged(true);
      }
    </af:resource>
    <af:inputText binding="#{test3.input}" label="label">
      <af:clientListener method="changed" type="valueChange"/>
    </af:inputText>
    <af:button text="Submit" actionListener="#{test3.clear}"/>
  </af:form>
  

  次のサンプルで、対応するマネージドBeanコードを示します。

  package test;
   
  import javax.faces.event.ActionEvent;
   
  import oracle.adf.view.rich.component.rich.input.RichInputText;
   
  public class Test3Bean
  {
    public Test3Bean()
    {
    }
    
    public void clear(ActionEvent actionEvent)
    {
      _input.setChanged(false);
    }
   
    public void setInput(RichInputText input)
    {
      _input = input;
    }
   
    public RichInputText getInput()
    {
      return _input;
    }  
    
    private RichInputText _input;
  }

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

ADF Facesで、ボーナス属性はサーバーからクライアントへ値を返すために使用されます。JDeveloperの「コンポーネント」ウィンドウを使用して、コンポーネントにボーナス属性を作成できます。

組込みプロパティ以外の情報をクライアントに送信する必要がある場合もあります。これは、ボーナス属性を使用して行えます。ボーナス属性は、clientAttributeタグを使用してコンポーネントに追加できる追加属性です。パフォーマンス上の理由から、クライアントに送信されるボーナス属性は、clientAttributeで指定されたもののみです。

clientAttributeタグでは、サーバー側コンポーネントの属性マップに追加される名前と値のペアを指定します。サーバー側属性マップの移入に加えて、clientAttributeタグを使用すると、ボーナス属性がクライアントに送信され、AdfUIComponent.getProperty("bonusAttributeName")メソッドを使用してアクセスできます。

フレームワークで、属性値のクライアントへのマーシャリングが行われます。マーシャリング・レイヤーで、文字列、ブール、数値、日付、配列、マップなど、各オブジェクト型のマーシャリングがサポートされます。マーシャリングの詳細は、「データのマーシャリングとアンマーシャリングに関する必知事項」を参照してください。

パフォーマンスのヒント:

マーシャリングによる過度のオーバーヘッドを防ぐため、クライアント側ボーナス属性を多用しないでください。

注意:

clientAttributeタグは、(アプリケーションで定義される)ボーナス属性にのみ使用します。クライアントで標準のコンポーネント属性にアクセスする必要がある場合、clientAttributeタグを使用するのではなく、clientComponent属性をtrueに設定します。「クライアント側コンポーネントのインスタンス化」を参照してください。

ボーナス属性の作成方法

「コンポーネント」ウィンドウを使用してコンポーネントにボーナス属性を追加できます。

始める前に:

ボーナス属性に関する知識が役立つ場合があります。「クライアント側コンポーネントに対するボーナス属性の使用」を参照してください。

ボーナス属性を作成する手順:

1. 「構造」ウィンドウで、ボーナス属性を追加するコンポーネントを選択します。
2. 「コンポーネント」ウィンドウで、「操作」パネルから「クライアント属性」をコンポーネントに子としてドラッグ・アンド・ドロップします。
3. 「プロパティ」ウィンドウで、名前属性と値属性を設定します。

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

クライアント側ボーナス属性は、サーバーからクライアントへ自動的に配信されますが、その逆は行われません。つまり、クライアントでのボーナス属性の変更または設定は、サーバーに反映されません。既知(ボーナス以外)の属性のみ、クライアントからサーバーへ同期がとられます。アプリケーションで定義されたデータをサーバーに送り返す必要がある場合、カスタム・イベントを作成します。「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。

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

ADF Facesコンポーネントの表示(レンダリング)と非表示は、他のコンポーネントの値に応じて、ページ上で動的に切り替えることができます。JSFツリーの一部にし、そのコンポーネントのHTMLコードを生成するには、コンポーネントの属性プロパティをtrueまたはfalseに設定する必要があります。

すべてのADF Faces表示コンポーネントには、コンポーネントをページに表示してユーザーに見えるようにするかどうかに関係するrenderedとvisibleの2つの属性があります。

rendered属性のセマンティクは非常に厳密です。renderedがfalseに設定されている場合、サーバーへのラウンドトリップなしにコンポーネントをクライアントで表示することはできません。ページのコンテンツの動的な表示/非表示をサポートするために、フレームワークにはvisible属性が追加されています。falseに設定されている場合、コンポーネントのマークアップはクライアントで使用可能ですが、コンポーネントは表示されません。したがって、setVisible(true)またはsetVisible(false)メソッドをコールすると、JavaからのコールであろうとJavaScriptからのコールであろうと、コンポーネントがブラウザ内で表示または非表示になります(renderedがtrueに設定されている場合)。ただし、visibleは単純にDOMのコンテンツを表示および非表示にするため、renderedを使用した場合と常に同じ視覚的変化を提供するとはかぎりません。

パフォーマンスのヒント:

JavaScriptなど、サーバーへのラウンドトリップなしに可視性を切り替える必要がある場合にのみvisible属性をfalseに設定します。非表示のコンポーネントも、検証を含むコンポーネント・ライフサイクルを経過します。

クライアントでのみ可視性を切り替える必要がない場合は、かわりにrendered属性をfalseに設定します。コンポーネントをレンダリングしない(表示しないのではなく)場合、コンポーネントはクライアント側表現を持たず、コンポーネント・ライフサイクルを経過しないため、サーバーのパフォーマンスとクライアントのレスポンス時間が向上します。

次の例に、2つのoutputTextコンポーネントを示します。一度にその一方のみがレンダリングされます。最初のoutputTextコンポーネントは、値がinputTextコンポーネントに入力されなかった場合にレンダリングされます。2番目のoutputTextコンポーネントは、値が入力されたときにレンダリングされます。

<af:panelGroupLayout layout="horizontal">
  <af:inputText label="Input some text" id="input"
                value="#{myBean.inputValue}"/>
  <af:button text="Enter"/>
</af:panelGroupLayout>
<af:panelGroupLayout layout="horizontal">
  <af:outputLabel value="You entered:"/>
  <af:outputText value="No text entered" id="output1"
                 rendered="#{myBean.inputValue==null}"/>
  <af:outputText value="#{myBean.inputValue}"
                 rendered="#{myBean.inputValue !=null}"/>
</af:panelGroupLayout>

コンポーネントがクライアントでレンダリングされる場合、visibleプロパティを使用してコンポーネントをページに表示したり、非表示にできます。

次の例に、前述の例と同じ機能を示しますが、この例ではvisible属性を使用して、どのコンポーネントが表示されるのか決定します(rendered属性はデフォルトでtrueに設定されるため、明示的に設定する必要はありません)。

<af:panelGroupLayout layout="horizontal">
  <af:inputText label="Input some text" id="input"
                value="#{myBean.inputValue}"/>
  <af:button text="Enter"/>
</af:panelGroupLayout>
<af:panelGroupLayout layout="horizontal">
  <af:outputLabel value="You entered:"/>
  <af:outputText value="No text entered" id="output1"
                 visible="#{myBean.inputValue==null}"/>
  <af:outputText value="#{myBean.inputValue}"
                 visible="#{myBean.inputValue !=null}"/>
</af:panelGroupLayout>

ただし、visible属性のかわりにrendered属性を使用することは、サーバー側でのパフォーマンスを向上させるため、次のJavaScriptコードで示すように、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)
    }
    
 }
   

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

コンポーネントのvisible属性を切り替えられる条件付きJavaScript関数を作成できます。

始める前に:

コンポーネントの表示方法に関する知識が役立つ場合があります。「レンダリングおよび可視性の理解」を参照してください。

可視性を設定する手順:

1. 可視性を切り替えるJavaScriptを作成します。例4-1に、値がない場合にoutputTextコンポーネントの可視性を有効にし、そうでない場合は別のoutputTextコンポーネントの可視性を有効にするスクリプトを示します。
2. JavaScript関数で必要なコンポーネントごとに、「プロパティ」ウィンドウで「拡張」セクションを開き、ClientComponent属性をtrueに設定します。これによって、JavaScriptで使用されるクライアント・コンポーネントが作成されます。
3. 可視性を切り替えるコンポーネントのvisible属性をfalseに設定します。

次の例に、JavaScriptを使用した可視性の切替えに使用されるページ・コード全体を示します。

例4-1 可視性の設定のJavaScript

<f:view>
<af:resource>
  function showText() 
  {
      var output1 = AdfUIComponent.findComponent("output1")
      var output2 = AdfUIComponent.findComponent("output2")
      var input = AdfUIComponent.findComponent("input")
      
      if (input.value == "")
      {
      output1.setVisible(true);
      }
      else 
      {
      output2.setVisible(true)
      }
      
  }
</af:resource>
<af:document>
  <af:form>
    <af:panelGroupLayout layout="horizontal"> 
      <af:inputText label="Input some text" id="input"
                    value="#{myBean.inputValue}" clientComponent="true"
                    immediate="true"/>
      <af:button text="Enter" clientComponent="true">
        <af:clientListener method="showText" type="action"/>
      </af:button>
    </af:panelGroupLayout>
    <af:panelGroupLayout layout="horizontal">
       <af:outputLabel value="You entered:" clientComponent="false"/>
       <af:outputText value="No text entered" id="output1"
                      visible="false" clientComponent="true"/>
       <af:outputText value="#{myBean.inputValue}" id="output2"
                      visible="false" clientComponent="true"/>
    </af:panelGroupLayout>
  </af:form>
 </af:document>
</f:view>

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

コンポーネントの親のvisible属性がfalseに設定されている場合、visible属性がtrueに設定されている子コンポーネントにisVisible関数が実行されると、子が表示されていなくてもtrueが返されます。たとえば、outputTextコンポーネントを子として含むpanelGroupLayoutコンポーネントがあり、panelGroupLayoutコンポーネントのvisible属性はfalseに設定され、outputTextコンポーネントのvisible属性はデフォルトのまま(true)とします。クライアントでは、panelGroupLayoutコンポーネントもoutputTextコンポーネントも表示されませんが、isVisible関数がoutputTextコンポーネントに実行されると、trueが返されます。

このため、フレームワークにはisShowing()関数が用意されています。この関数は、コンポーネントのvisible属性がfalseに設定されている場合、またはコンポーネントの親のvisibleがfalseに設定されている場合、falseを返します。

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

イベントのソースではないクライアント・コンポーネントを検索する必要がある場合、AdfUIComponent.findComponent(expr)メソッドを使用できます。このメソッドはJSFのUIComponent.findComponent()メソッドと似ており、指定した検索式に合致するIDを使用してUIComponentオブジェクトを検索して返します。

AdfUIComponent.findComponent(expr)メソッドは、サーバーではなくクライアントでのみ機能します。

次の例に、コンポーネントのIDを使用してoutputTextコンポーネントを検索するsayHello関数を示します。

function sayHello(actionEvent)
{
  var buttonComponent=actionEvent.getSource();
  
  //Find the client component for the "greeting" af:outputText
  var greetingComponent=buttonComponent.findComponent("greeting");

  //Set the value for the outputText component
  greetingComponent.setValue("Hello World")
}

ADF Facesには、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドもあります。このメソッドは、IDの文字列をハードコーディングする場合に使用します。クライアントIDがコンポーネントから取得される場合は、AdfUIComponent.findComponent(expr)を使用します。

注意:

似たような名前のAdfPage.PAGE.findComponent(clientId)というメソッドもありますが、この関数は、リリース間で変わる可能性のある実装固有の識別子を使用し、ページ作成者は使用しません。

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

見つける必要があるコンポーネントがネーミング・コンテナ(pageTemplate、subform、tableおよびtreeなど)であるコンポーネントにある場合は、AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)メソッドを使用するかわりに、AdfUIComponent.findComponent(expr)メソッドを使用します。絶対式も相対式も使用できます。

ヒント

コンポーネントがネーミング・コンテナかどうかは、コンポーネント・タグのドキュメントを確認して判断できます。タグのドキュメントには、コンポーネントがネーミング・コンテナかどうかが示されています。

絶対式は次のように作成されます。

":" + (namingContainersToJumpUp * ":") + some ending portion of the clientIdOfComponentToFind

たとえば、myTemplateテンプレートを使用するページのID r1のリージョンに含まれるID pc1のパネル・コレクション・コンポーネント内にあるID t1の表を検索するには、次の文字列を使用できます。

:myTemplate:r1:pc1:t1

または、両方のコンポーネント(検索を実行するコンポーネントと検索されるコンポーネント)が同じNamingContainerコンポーネントを階層のどこかで共有する場合は、相対パスを使用して、検索を実行するコンポーネントとの相対で検索を実行できます。相対パスには、たとえば、次のように複数のNamingContainer.SEPARATOR_CHAR文字を先頭に含めることができます。

":" + clientIdOfComponentToFind

前述の例で、検索元のコンポーネントが表と同じリージョンにある場合、次を使用できます。

::somePanelCollection:someTable

ヒント

ネーミング・コンテナをフォルダと考え、clientIdをファイル・パスと考えます。フォルダとファイルの場合、連続する2つのピリオドとスラッシュ (../)を使用して階層の上位のフォルダに移動します。これは、複数のコロン(:)文字がfindComponent()式で果たす役割と同じです。先頭の単一のコロン(:)は、ファイル・パスが、ファイル構造のルートからの絶対パスであることを意味します。式の先頭に複数のコロン( :)文字がある場合、最初のコロンは無視され、他のコロンは考慮されます。コロン(:)文字当たり1セットのピリオドとスラッシュ( ../)が考慮されます。

AdfPage.findComponentByAbsoluteId()メソッドを使用する場合、パスは常に絶対パスであるため、先頭のコロンは不要です。

絶対パスを使用するか相対パスを使用するかを決める際、次の点に注意します。

• 検索対象のコンポーネントが常に同じネーミング・コンテナ内あることがわかっている場合は、絶対パスを使用します。

• 検索元のコンポーネントと検索対象のコンポーネントの相対的位置が常に同じであることがわかっている場合は、相対パスを使用します。

クライアントにはgetChildren()関数もgetFacet()関数もありません。かわりに、すべての子コンポーネントとファセット(つまり、すべての子孫)にアクセスするAdfUIComponent.visitChildren()関数が用意されています。ADF Facesはスパース・コンポーネント・ツリー(クライアント・コンポーネントが必要に応じて作成されるツリー)であるため、getParent()メソッドがクライアントで返すコンポーネントは、サーバー上の実際の親ではない場合があります(先祖である可能性はあります)。同様に、クライアント上に直接の子として出現するコンポーネントは、任意の子孫である可能性があります。Java APIリファレンスfor Oracle ADF Facesを参照してください。

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

ADF FacesのJavaScriptパーティション化機能では、ADFコンポーネントからの個々のJavaScriptファイルを大きいコレクションに集約し、それによってダウンロードの数を減らすことができます。ADF Facesで提供されるデフォルトのパーティションを使用するか、アプリケーションの必要に応じてJavaScriptパーティションを作成/構成することができます。

JavaScriptを多用したフレームワークに共通する問題は、大規模なJavaScriptコード・ベースをクライアントに送信する最良の方法を決定することです。極端な方法は、すべてのコードを1つのJavaScriptライブラリにバンドリングすることで、この方法ではダウンロード時間が長くなります。逆の極端な方法はJavaScriptコードを多数の小さなJavaScriptライブラリに分割することで、この方法ではラウンドトリップ数が大きくなります。どちらの方法でも初期ページをロードするためのユーザーの待ち時間が不必要に長くなります。

この問題を軽減するために、ADF FacesではJavaScriptコードがパーティションに集約されます。JavaScriptライブラリ・パーティションには、コンポーネントのコードまたは通常一緒に使用される機能、あるいはその両方が含まれています。ADF Facesではデフォルトで、ダウンロード・サイズ合計とラウンドトリップ数合計のバランスを取ることを意図したパーティション化が行われます。

ADF Facesのライブラリ・パーティション化戦略の利点の1つは、構成可能であることです。アプリケーションによって使用するコンポーネントおよび機能が異なるため、ADF Facesのデフォルトのパーティション化がすべてのアプリケーションに最適であるとはかぎりません。このため、ADF FacesのJavaScriptライブラリのパーティション化はアプリケーションごとにカスタマイズ可能になっています。このようなパーティション化により、アプリケーション開発者はJavaScriptライブラリのフットプリントをアプリケーションの要件に合せて調整できます。

ADF Facesは、そのコンポーネントのJavaScriptファイルをJavaScript機能にグループ化します。JavaScript機能は、その機能を記述する論理識別子に関連付けられたJavaScriptファイルのコレクションです。たとえば、panelStretchLayoutクライアント・コンポーネントは、次の2つのJavaScriptファイルで構成されます。

• oracle/adf/view/js/component/rich/layout/ AdfRichPanelStretchLayout.js

• oracle/adfinternal/view/js/laf/dhtml/rich/ AdfDhtmlPanelStretchLayoutPeer.js

これらの2つのファイルは、AdfRichPanelStretchLayout機能にグループ化されます。

JavaScriptの機能は、さらにJavaScriptパーティションにグループ分けされます。JavaScriptパーティションを使用すると、ダウンロード・サイズとラウンドトリップの数に影響を与える目的で、JavaScriptの機能を、より大きなまとまりに分けることができます。たとえば、panelStretchLayoutコンポーネントはpanelSplitterコンポーネントとともに使用されることが多いため、この2つのコンポーネントの機能は、その子をストレッチできるADF Facesレイアウト・コンポーネントと一緒にストレッチ・パーティションにまとめられます。実行時、ページをロードすると、フレームワークはページで使用されるコンポーネントを決定し、そこから、必要な機能を決定します(機能名は、コンポーネントのコンストラクタ名と同じ)。これらの機能が含まれるパーティションのみがダウンロードされます。

機能およびパーティションは、構成ファイルを使用して定義されます。ADF Facesには、デフォルトの機能およびパーティション構成ファイルが含まれています。独自の実装を作成することでデフォルトのパーティションを上書きできます。

デフォルトでJavaScriptのパーティション化は有効にされています。アプリケーションでJavaScriptのパーティション化を使用するかどうかは、web.xmlファイルのコンテキスト・パラメータによって決定されます。「JavaScriptのパーティション化」を参照してください。

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

adf-js-partitions.xmlファイルを作成してから機能にエントリを追加することでJavaScriptパーティションを作成できます。

注意:

ADF Facesには、デフォルトのadf-js-partitions.xmlファイルがあります(「adf-js-partitions.xmlファイル」を参照)。パーティションの構成を変更する場合は、独自の完全なadf-js-partitions.xmlファイルを作成する必要があります。実行時にフレームワークは、そのファイルのWEB-INFディレクトリを検索します。見つからない場合は、デフォルトのパーティション・ファイルがロードされます。

始める前に:

JavaScriptのパーティション化の動作に関する知識が役立つ場合があります。詳細は、「JavaScriptライブラリのパーティション化」を参照してください。

JavaScriptパーティションを作成する手順:

1. 「アプリケーション」ウィンドウで、「WEB-INF」を右クリックして「新規」→「ギャラリから」を選択します。
2. 「新規ギャラリ」で、「一般」を展開し、「XML」→「XMLドキュメント」を選択して、「OK」をクリックします。

   ヒント

   「一般」ノードが表示されない場合、ギャラリの上部の「すべてのテクノロジ」タブをクリックします。

3. 「XMLファイルの作成」ダイアログで、ファイル名をadf-js-partitions.xmlとしてWEB-INFディレクトリに保存します。
4. ソース・エディタで、生成されたコードを次のコードに置き換えます。

   <?xml version="1.0" encoding="utf-8" ?>
   <partitions xmlns="http://xmlns.oracle.com/adf/faces/partition">
    
   </partitions>
   

5. 次の要素を追加すると、関連する機能とともにパーティションが移入されます。

   • partitions: 構成ファイルのルート要素です。

   • partition: partitions要素の子として作成されます。この要素には1つのpartition-name子要素および1つ以上のfeature要素が含まれている必要があります。

   • partition-name: partition要素の子として作成されます。パーティションの名前を指定します。この値は、このパーティションのJavaScriptライブラリに一意のURLを作成するために使用されます。

   • feature: partition要素の子として作成されます。このパーティションに含める機能を指定します。複数のfeature要素がある場合もあります。

   ヒント

   adf-js-features.xmlファイルで構成され、パーティションに表示されない機能は、独自のパーティションに存在するものとして扱われます。

   次の例に、AdfRichTree機能およびAdfRichTreeTable機能を含むtreeパーティションのpartition要素を示します。

   <partition>
     <partition-name>tree</partition-name>
     <feature>AdfUITree</feature>
     <feature>AdfUITreeTable</feature>
     <feature>AdfRichTree</feature>
     <feature>AdfRichTreeTable</feature>
   </partition>

実行時の処理: 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ドキュメントの末尾直前でレンダリングされます。