Ajaxフレームワーク UI部品リファレンス
目次 索引 前ページ次ページ
第2章 画面部品> 2.2 コンテナ部品

2.2.5 FragmentContainer

FragmentContainerは、画面情報(コンテナ)を別ファイルで指定する部品です。

ViewContainerは子要素として同一ファイル内にHTML要素を記述するのに対して、FragmentContainerは別ファイルに記述します。

FragmentContainer内のHTML(以降、フラグメントHTMLと呼びます)は、activateメソッドを呼び出したタイミングで非同期通信によるデータの取得処理が開始されます。ここでは、activateメソッドまたはreloadメソッドを実行してFragmentContainer内の部品が利用可能な状態となることを有効化(可視化)と呼び、また、activateメソッドの実行以前の状態、またはunloadメソッドにより部品が利用不可の状態になることを無効化と呼びます。なお、フラグメントHTMLは、単体のHTMLとしてDTDに適合していません。
取得後のフラグメントHTMLは、FragmentContainerを記述したHTML(以降、コンテナHTMLと呼びます)に挿入されて、データが反映されます。

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

■記述形式

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


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

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

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

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

　

参照先(TO)

コンテナHTML内

フラグメントHTML内

グローバル

ローカル

グローバル

ローカル

参照元
(FROM)

コンテナHTML内

可

可

可

不可

フラグメントHTML内

可

可

可

不可

■プロパティ

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

名前

データ型

説明

省略

省略値

属性指定

更新

部分更新

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になります。)

■unloadメソッド

メソッド

unload()

引数

なし

戻り値

なし

説明

対象となるFragmentContainerをアンロードし、無効化します。
本メソッドを利用する場合、フラグメントHTML上の部品のIDは省略できません。

■reloadメソッド

メソッド

reload()

引数

なし

戻り値

なし

説明

対象となるFragmentContainerをリロードし、有効化します。
なお、一度もactivateされていないFragmentContainerは、activateを実行し、有効化します。
本メソッドを利用する場合、フラグメントHTML上の部品のIDは省略できません。

部品共通の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[
        //FragmentContainerのフラグメントHTMLに含まれる部品のイベント定義
        var fragment1events = {
           button1: {...}
        };

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

        // FragmentContainer1のイベント定義
        var fragmentContainerEvent = {
           //↓FragmentContainer1の状態変化に対するイベントリスナ登録
           fragmentContainer1      : { statechange: fcStateChange }
        }

        RCF.addInitializedListener(function(eventObject) {
           //FragmentContainer1のイベント定義を登録
           rcf.event.EventRegistrar.registerEvents(fragmentContainerEvent, 'fragmentContainer');

           //FragmentContainer1のactivate
           fragmentContainer1.activate();
        });

//]]>
</script>
...
</head>
<body>
...
  // FragmentContainer1
<div rcf:type="FragmentContainer" rcf:src="sample-fc.jsp" rcf:id="fragmentContainer1"></div>
...
</body>

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

アンロード・リロード

アンロード・リロードの機能は、Internet Explorerでだけ利用できます。

アンロード
FragmentContainerのアンロードは、有効化されているFragmentContainerに対して、FragmentContainer上の部品を削除することで無効化し、フラグメントHTMLの内容を表示しないようにします。
リロード
FragmentContainerのリロードは、いったんアンロードされて無効化されているFragmentContainerに対して、部品を再構築することで有効化し、フラグメントHTMLの内容を表示できるようにします。

アンロード・リロードの機能を使うことにより、例えば、複数のタブパネルに、それぞれFragmentContainerが配置され、そのFragmentContainer上に画面部品、機能部品、および一般HTML部品を配置するコンテンツがある場合、選択されているタブパネル(FragmentContainer上の部品)だけを有効化し、当面必要のないタブパネル(FragmentContainer上の部品)は無効化することができるようになります。
このように操作に必要のないFragmentContainerを無効化し、操作に必要なFragmentContainerだけを有効化することで、全体としてのメモリ使用量を抑えることができます。

以下は、TabPanelのタブ上に定義されているFragmentContainerをアンロード・リロードする例です。

<head>
...
<script type="text/javascript">
//<![CDATA[
      var current_index = 0;
      var counter_view  = 0;
      var tabPanelIndex = { selectedIndex : counter_view }
      var eventTabPanel = {
            tabPanel1 : { selectedindexchange : reload_fragmentContainer }
      }
      function reload_fragmentContainer(eventObject){
          var next_index = eventObject.index;  // 選択されたTabPanelのindex
          var fc_prev = null;
          var fc_next = null;
          if ( current_index == 0 ) {
              fc_prev = fc0;
          } else if ( current_index == 1 ) {
              fc_prev = fc1;
          }
          if ( next_index == 0 ) {
              fc_next = fc0;
          } else if ( next_index == 1 ) {
              fc_next = fc1;
          }
          current_index = next_index;
          fc_prev.unload();  // 現在のFragmentContainerのアンロード
          fc_next.reload();  // 選択されたFragmentContainerのリロード
      }
      RCF.addInitializedListener(function() {
        rcf.event.EventRegistrar.registerEvents(eventTabPanel, 'myevent');
        fc0.activate();
      });
//]]>
</script>
...
</head>
<body>
  <div rcf:type="Model" rcf:id="modelTabPanel" rcf:object="tabPanelIndex" ></div>
  <div rcf:type="TabPanel" rcf:selectedIndex="{modelTabPanel.selectedIndex}" rcf:id="tabPanel1" rcf:width="auto">
    <div rcf:type="FragmentContainer" rcf:id="fc0" rc:src="fc0.html"></div>
    <div rcf:type="FragmentContainer" rcf:id="fc1" rcf:src="fc1.html"></div>
  </div>
</body>
</html>


■補足事項

目次 索引 前ページ次ページ
Copyright 2008 FUJITSU LIMITED