2.2.5 FragmentContainer

Ajaxフレームワーク UI部品リファレンス

目次索引

2.2.5 FragmentContainer

FragmentContainerは、画面情報(コンテナ)を別ファイルで指定する部品です。
ViewContainerは子要素として同一ファイル内にHTML要素を記述するのに対して、FragmentContainerは別ファイルに記述します。

FragmentContainer内のHTML(以降、フラグメントHTMLと呼びます)は、activateメソッドを呼び出したタイミングで非同期通信によるデータの取得処理が開始されます。なお、フラグメントHTMLは、単体のHTMLとしてDTDに適合していません。
取得後のフラグメントHTMLは、FragmentContainerを記述したHTML(以降、コンテナHTMLと呼びます)に挿入されて、データが反映されます。

用途の例を以下に示します。

初期化処理の高速化
TabPanelやViewStackと組み合わせて、コンテナの内容を遅延読込みさせます。
分散開発
開発資産(ファイル)が分割されるので、分散して開発できます。

■記述形式

<div rcf:type="FragmentContainer" rcf:src="fragment.jsp" ... ></div>

子要素は指定できません。

[図: FragmentContainerの利用イメージ]

フラグメントHTMLは、通常のHTMLと同様に、UI部品、<script>タグを利用したJavaScript変数、JavaScript関数などを利用できます。

コンテナHTMLとフラグメントHTML間の変数名および関数名の参照可否を、以下に示します。

		参照先(TO)
		コンテナHTML内		フラグメントHTML内
		グローバル	ローカル	グローバル	ローカル
参照元 (FROM)	コンテナHTML内	可	可	可	不可
参照元 (FROM)	フラグメントHTML内	可	可	可	不可

フラグメントHTMLのイベントハンドラ(rcf:onXXXXや通常のonXXX)は、フラグメントHTML内の変数名(関数名)のローカル変数(ローカル関数)を参照できません。この場合、未定義変数(関数)を参照した場合と同じ動作になります。
- ローカル変数(関数)の例
  var i = 1 (var f = func(..){..})
- グローバル変数(関数)の例
  i = 1 (f = func(..){..})
フラグメントHTML内のグローバル変数(関数)は、コンテナHTMLからも参照できます。このため、複数のフラグメントHTMLを利用する場合、名前の管理に注意してください。
フラグメントHTML、コンテナHTMLで変数名(関数名)が一意になるようにしてください。
rcf:widthおよびrcf:heightが指定された場合、activate前から画面領域を指定されたサイズを確保します。
フラグメントHTMLの構造をJSPで作成することもできます。ただし、JSP拡張タグおよびJSPスクリプトレットと混在させることはできません。混在した場合の動作は保証されません。

■プロパティ

表の項目の意味は、“表の項目の意味”を参照してください。

名前	データ型	説明	省略	省略値	属性指定	更新	部分更新
src	String	フラグメントHTMLを取得するURLを指定します。 HTTPメソッドはGET固定です。コンテナ側HTMLとフラグメントHTMLを提供するサーバは必ず同じにします。 URLに、日本語などの2バイト文字を含めることはできません。 URLには、クエリ文字列およびURLリライティングで用いるセションIDを付加することができます。詳細は、“ユーザーズガイド”を参照してください。	不可	－	値	不可	不可
showStatus	Boolean	activate前のFragmentContainerの状態(初期化直後、ロード中、エラーなど)の表示/非表示を指定します。 true:表示する false:表示しない	可	true	値	不可	不可
statusIconImage	Object	正常系activate前の状態、および異常系状態のアイコンイメージを指定します。詳細は、“statusIconImageプロパティ”を参照してください。	可	標準の画像	値	不可	不可
timeout	Number	フラグメントHTMLの取得開始から取得完了までの最大待ち時間を指定します。単位は、ミリ秒です。 1より小さい数値を指定した場合は、エラーとなります。タイムアウトの場合は、FragmentErrorEventが発生します。	可	60000(60秒)	値	不可	不可

ViewContainerのプロパティも指定できます。詳細は、“ViewContainer”を参照してください。
部品共通のプロパティも指定できます。詳細は、“画面部品共通プロパティ”を参照してください。

statusIconImageプロパティ

statusIconImageプロパティは、以下のプロパティを持つ連想配列で指定します。

プロパティ名	データ型	説明
normal	String	画像のURL文字列(正常系activate前に表示するアイコン) このプロパティが存在しない場合、デフォルトのアイコンを利用します。
error	String	画像のURL文字列(request/activateでエラーが起こった場合のアイコン) このプロパティが存在しない場合、デフォルトのアイコンを利用します。

それぞれのURLには、クエリ文字列およびURLリライティングで用いるセションIDを付加することができます。詳細は、“ユーザーズガイド”を参照してください。

■スタイルプロパティ

パーツ名	プレフィックス	クラス名	使用可能なスタイル
部品全体	なし	rcf-FragmentContainer	サイズカラーボーダーパディングオーバーフロー

詳細は、“スタイルプロパティ”を参照してください。

■イベントリスナ

名前	説明	イベントオブジェクト
onStateChange	フラグメントHTMLのダウンロード中や、有効化(可視化)処理中など、FragmentContainerの状態が変化したときに呼ばれます。	FragmentStateChangeEvent
onFragmentError	フラグメントHTMLダウンロード処理や、有効化(可視化)処理が異常終了したときに呼ばれます。	FragmentErrorEvent

部品共通のイベントリスナもあります。詳細は、“画面部品共通イベントリスナ”を参照してください。なお、activateが完了する前は、画面部品共通イベントリスナは、利用できません。

■JavaScript API

■activateメソッド

メソッド	activate()
引数	なし
戻り値	なし
説明	フラグメントHTMLの有効化(可視化)処理を行います。同じFragmentContainerに対する2度目以降のactivate呼出しは、何もせず復帰します。“FragmentContainerの正常系状態とAPIの関係”を参照してください。

■requestメソッド

メソッド	request()
引数	なし
戻り値	なし
説明	srcプロパティで指定されたフラグメントHTMLの取得を開始します。このメソッドは、取得開始(HTTPリクエスト送信)と同時に復帰します。同じFragmentContainerに対する2度目以降のrequestメソッド呼出しは、何もせず復帰します。“FragmentContainerの正常系状態とAPIの関係”を参照してください。

■isActivateCalledメソッド

メソッド	isActivateCalled()
引数	なし
戻り値	true:呼出しあり false:呼出しなし
説明	過去にactivateメソッド呼出しを行ったかどうかを返します。

■isRequestCalledメソッド

メソッド	isRequestCalled()
引数	なし
戻り値	true:取得要求あり false:取得要求なし
説明	フラグメントHTMLの取得要求を出したかどうかを返します。(requestメソッド、activateメソッドを呼ぶとtrueになります。)

部品共通のJavaScript APIもあります。部品共通のJavaScript APIは、“画面部品共通JavaScript API”を参照してください。

FragmentContainerの正常系状態とAPIの関係

上記の状態が遷移するとき、FragmentContainerはFragmentStateChangeEventを送出します。

オレンジ色の状態は、エラーとなる可能性がある状態です。これらの状態でエラーとなった場合は、このコンテナはエラー状態になります。また、timeout状態に遷移したときも、同じくエラー状態になります。

FragmentContainerは、正常な状態からエラー状態に遷移するとき、FragmentErrorEventを送出します。また、rcf:showStatus=true(デフォルト値)の場合は、インジケータアイコンが、エラーアイコンに変わります。

一度エラー状態になったコンテナは、正常状態に戻せません。

activateについて
FragmentContainerのactivate()を実行すると、非同期で有効化処理が行われます。そのため、以下のように2つのFragmentContainerのactivateを連続して実行した場合、fc1の有効化が先に完了することは保証されません。

<script type="text/javascript">
//<![CDATA[
    :
   fc1.activate();
   fc2.activate();
     :

//]]>
</script>

フラグメントHTMLに記述されている部品の呼出し
FragmentContainerの有効化が完了する前に、フラグメントHTMLに記述された部品のAPIや部品に対するイベントの登録を行うと、部品が存在していないため、エラーになります。イベントの登録は、必ずFragmentContainerの有効化の完了(activated)のあとに行ってください。
以下は、フラグメントHTMLに記述された部品に対してイベント定義を行う例です。

<head>
    :
<script type="text/javascript">
//<![CDATA[
        //フラグメントコンテナのフラグメントHTMLに含まれる部品のイベント定義
        var fragment1events = {
           button1: {...}
        };

        //  フラグメントコンテナ1の状態変化に対するイベントリスナ
        function fcStateChange(stateChangeEvent) {
          switch (stateChangeEvent.state) {
             case 'activated':
               //↓コンテナ内部品の初期化(activate)が完了した場合の処理
               //↓フラグメントHTMLに含まれる部品のイベント定義を登録
               rcf.event.EventRegistrar.registerEvents(fragment1events,'fragment1events');
               break;
          }
        }

        // フラグメントコンテナ1のイベント定義
        var fragmentContainerEvent = {
           //↓フラグメントコンテナ1の状態変化に対するイベントリスナ登録
           fragmentContainer1      : { statechange: fcStateChange }
        }

        RCF.addInitializedListener(function(eventObject) {
           //フラグメントコンテナ1のイベント定義を登録
           rcf.event.EventRegistrar.registerEvents(fragmentContainerEvent, 'fragmentContainer');

           //フラグメントコンテナ1のactivate
           fragmentContainer1.activate();
        });

//]]>
</script>
  :
</head>
<body>
  :
  // フラグメントコンテナ1
<div rcf:type="FragmentContainer" rcf:src="sample-fc.jsp" rcf:id="fragmentContainer1"></div>
  :
</body>

上記の例では、RCF.addInitializedListenerでフラグメントコンテナ1のactivateを行う前に、フラグメントコンテナ1のイベント定義(fragmentContainerEvent)を登録しています。フラグメントコンテナ1のイベント定義では、statuschangeイベントに対するイベントリスナ(fcStatusChange)が定義されています。fcStatusChange関数では、フラグメントコンテナの状態が有効化完了(activated)になったら、フラグメントコンテナ1のフラグメントHTMLに含まれる部品のイベント定義を登録しています。

■補足事項

FragmentContainerは、ViewStackやTabPanelと組み合わせて利用することができます。
FragmentContainerを単体で使用した場合、activate完了後は、通常の<div>タグと同様に表示されます。
フラグメントHTMLは、HTMLのボディに追加されます。そのため、HTMLのヘッダに記述する要素を、フラグメントHTMLに記述することはできません。

目次索引