カスタム・コンポーネントおよびウィジェットの作成

HATS には、ホスト画面のエレメントを認識するホスト・コンポーネントと、この認識されたエレメントをレンダリングするウィジェットのセットが用意されています。デフォルト設定が要求通りにコンポーネントを認識しない場合やウィジェットをレンダリングしない場合、コンポーネントおよびウィジェットの設定を変更できます。HATS が提供するコンポーネント、ウィジェット、および設定がニーズに合わない場合は、独自のカスタム・コンポーネントまたはウィジェットを作成するか、既存のホスト・コンポーネントまたはウィジェットを変更することができます。HATS コンポーネントが認識しないホスト画面のエレメントを認識するために独自のホスト・コンポーネントを作成することもできます。また、Web ページでのエレメントの表示方法を変更するために独自のウィジェットを作成することもできます。以下のセクションでは、カスタム・ホスト・コンポーネントおよびウィジェットの作成方法について説明します。詳しくは、付録A. HATS Toolkit のファイルを参照してください。

注:
  1. HATS は、HATS アプリケーションにカスタム・コンポーネントまたはウィジェットを追加する際、クラス・ローダー・ポリシーを自動的に更新します。これにより、HATS アプリケーションのデフォルト WAR クラス・ローダー・ポリシーが、「アプリケーションの単一クラス・ローダー」に更新されます。
  2. 双方向コード・ページを使用している場合は、ウィジェットおよびその他の表示エレメントを制御できます。HATS 双方向 API の使用を参照してください。

HATS のコンポーネント・タグおよび属性

HATS は、HATS Toolkit の変換構成中に行われるホスト・コンポーネントとウィジェットの選択を反映した JavaServer Pages (JSP) ページを作成します (また、.jsp ファイルに情報を書き込みます)。HATS は、この構成を <HATS:Component> タグの一連の属性として書き込みます。<HATS:Component> タグは、ホスト・コンポーネントを定義し、ウィジェット出力を指定するコードを呼び出します。HATS プロジェクトの変換を表示または編集するには、「HATS プロジェクト」ビューでプロジェクトを展開し、「Web コンテンツ/変換 (Web Content/Transformations)」の中を参照します。

この JSP コードの例は、<HATS:Component> タグのフォーマットを示しています。

<HATS:Component type="<fully qualified component class name>" 
   widget="<fully qualified widget class name>" 
   row="1" col="1" erow="24" ecol="80" componentSettings="" widgetSettings="" 
   textReplacement=""  />

<HATS:Component> タグの属性データにより、ホスト・コンポーネントとウィジェットのクラスが何を呼び出し、ウィジェットをどのように HTML 出力で表示するのかが決定されます。<HATS:Component> タグの type 属性は、選択されたホスト画面コンポーネントを認識する際に使用するコンポーネント認識クラスを指定します。widget 属性は、HTML 出力を生成する際に使用するレンダリング・クラスを指定します。次のリストに、その他の属性を示します。

row
ホスト・コンポーネント認識の開始行の位置。
col
ホスト・コンポーネント認識の開始カラムの位置。
erow
ホスト・コンポーネント認識の終了行の位置。ホスト画面上の最後の行を示すには、-1 を指定します。
ecol
ホスト・コンポーネント認識の終了カラムの位置。ホスト画面上の最後の列を示すには、-1 を指定します。
componentSettings
コンポーネント・クラスに送信された一連のキーおよび値の組。componentSettings 値を指定する場合、key:value の形式で指定してください。複数の key:value を指定する場合は、分割垂直バー ( | ) で区切ってください。例: <.. componentSettings="key1:value1|key2:value2" ... >。

componentSettings 属性は、コンポーネントの拡張カスタマイズに使用できます。リスト全体を引用符で囲みます。例えば、コマンド行がトークンに ==> の代わりに >>> を使用した場合、このコンポーネント設定値をここで渡すことができます。

widgetSettings
ウィジェット・クラスに送信された一連のキーおよび値の組。widgetSettings 値を指定する場合、key:value の形式で指定してください。複数の key:value 組を指定する場合は、分割垂直バー ( | ) で区切ってください。リスト全体を引用符で囲みます。例:<... widgetSettings="key1:value1|key2:value2" ... >。

widgetSettings 属性は、ウィジェットの拡張カスタマイズに使用できます。例えば、一定のカラム数を含んだテーブルが必要な場合、ここでウィジェット設定を渡すことができます。

textReplacement
コンポーネントの使用でのテキスト置換の定義設定。テキスト置換の属性はプロジェクト・レベルのテキスト置換の定義と同じです。属性の説明については、<replace> タグを参照してください。

テキスト置換を定義する際、特殊文字を置換する場合は、以下の設定を使用する必要があります。

@vb.
| (分割垂直バー)
@cm.
, (コンマ)
@dq.
" (二重引用符)
@lt.
< (より小さい)
@gt.
> (より大きい)
@eq.
= (等号)

例えば、ABC というストリングを "ABC" というストリングに置換するには、次のようにテキスト置換を指定します。

textreplacement="ABC=@dq.ABC@dq." 

HATS は次の手順に従って、JSP ページで検出した各 <HATS:Component> タグを処理します。

  1. HATS は、タグの type 属性によって指定されたコンポーネントのインスタンスの生成を試みます。この属性に指定できるのは、HATS によって提供されるコンポーネント、またはユーザーによって作成されたコンポーネントの完全修飾クラス名です。
    注:
    ユーザーが com.company.division.product.MyComponent などの完全修飾パスを指定する必要があります。HATS Toolkit でカスタム・コンポーネントを処理できるようにするには、WEB-INF/classes ディレクトリーまたは WEB-INF/lib ディレクトリー内の jar ファイルにクラス・ファイルを置きます。必要に応じて、プロジェクトのソース・ディレクトリーにソース (.java) ファイルをインポートできます。カスタム・コンポーネントをテストし、HATS Toolkit でそれを処理しない場合は、WebSphere® Application Server へのインストール時に、HATS アプリケーションが .jar ファイルを使用できるようにする必要があります。
  2. HATS は、タグの ウィジェット 属性によって指定された ウィジェット オブジェクトのインスタンスの生成を試みます。
    注:
    com.company.division.product.MyWidget のように、完全修飾パスを指定する必要があります。HATS Toolkit でカスタム・ウィジェットを処理できるようにするには、WEB-INF/classes ディレクトリーまたは WEB-INF/lib ディレクトリー内の jar ファイルにクラス・ファイルを置きます。必要に応じて、プロジェクトのソース・ディレクトリーにソース (.java) ファイルをインポートできます。カスタム・ウィジェットをテストし、HATS Toolkit でそれを処理しない場合は、WebSphere Application Server へのインストール時に、HATS アプリケーションが jar ファイルを使用できるようにする必要があります。
  3. HATS は、コンポーネント・オブジェクトの recognize() メソッドを呼び出します。

    各コンポーネントには、recognize() メソッドの異なるインプリメンテーションがあります。recognize() メソッドは、パターン認識論理やホスト画面データの位置指定を実行します。コンポーネント・クラスは、com.ibm.hats.transform.ComponentElement オブジェクトの配列を戻します。この配列は、指定された設定で指定された領域においてこのコンポーネントが認識した内容を論理的に表したものです。

  4. HATS は、コンポーネント・オブジェクトの recognize() メソッドによって戻される配列内の各 ComponentElement オブジェクトで doTextReplacement() メソッドを呼び出すことによって、テキスト置換を実行します。
  5. HATS は、ウィジェットの drawHTML() メソッドを呼び出します。適当な drawHTML() メソッドが見つからない場合は、ウィジェットの draw() メソッドが呼び出されます。このメソッドは、コンポーネントによって戻されるコンポーネント・エレメント配列内の各コンポーネント・エレメントにおける連結された toString() 呼び出しだけを戻します (サブクラスによってオーバーライドされない場合)。

    drawHTML() メソッドは、コンポーネント・エレメントの配列を HTML 出力形式でレンダリングします。drawHTML() メソッドは、提供されたコンポーネント・エレメント配列のレンダリングを含む StringBuffer オブジェクトを戻すことによってこれを実行します。コンポーネントに使用したウィジェットによって、コンポーネント・エレメントがレンダリングされる方法が決まります。また、2 つのウィジェットが同じタイプの入力データを使用することができます。例えば、Link ウィジェットと Button ウィジェットはどちらも同じタイプの入力データを使用しますが、それぞれの drawHTML() メソッドは異なる HTML コンテンツを生成します。

図 1 に、ホスト画面の領域からコンポーネントやウィジェットを経由して Web ページへ流れるデータのフローを示します。

図 1. ホスト画面から Web ページまでのデータのフロー
ホスト画面から Web ページまでのデータのフロー

カスタム・ホスト・コンポーネントの作成

HATS は「コンポーネントの作成 (Create Component)」ウィザードを提供しており、カスタム・コンポーネントの作成を支援します。いくつかの方法でウィザードを開始できます。

「コンポーネントの作成 (Create Component)」ウィザードには 2 つのパネルがあります。最初のパネルでは、プロジェクト名、新規コンポーネント名、コンポーネントの Java™ パッケージ名を入力します。 オプションで、新規コンポーネントによって使用される設定の構成用の GUI パネルを定義できるスタブ・メソッドを組み込むためのチェック・ボックスを選択することができます (詳しくは、カスタム・コンポーネントおよびウィジェットの設定に対する HATS Toolkit のサポートを参照)。2 番目のパネルでは、HATS Toolkit で新規コンポーネント名として表示する名前を入力し、そのコンポーネントに関連付けるウィジェットを選択します。ウィジェットの関連付けはウィザードを完了するうえで必須ではありません。コンポーネントとウィジェットの関連は後で定義することができます。コンポーネントとウィジェットの関連付けについての詳細は、コンポーネントまたはウィジェットの登録を参照してください。

次のセクションでは、ウィザードが提供するカスタム・コンポーネントの必須エレメントについて説明します。

チェック・ボックスを選択し HATS Toolkit グラフィカル・ユーザー・インターフェースのサポート・メソッドを組み込んだ場合は、コンポーネントの設定変更が可能になると共に、「コンポーネントの作成」ウィザードで以下のメソッドが追加されます。

カスタム・コンポーネントのサポートに必要なメソッドの詳細については、カスタム・コンポーネントおよびウィジェットの設定に対する HATS Toolkit のサポートを参照してください。

注:
デフォルト・レンダリング内でコンポーネントを正しく機能させるには、コンポーネント・エレメントを戻す前に、コンポーネントが戻す各コンポーネント・エレメントで使用された領域 (処理されたホスト画面の領域) を設定する必要があります。これによって、デフォルト・レンダリングは、ホスト・コンポーネントによってこの画面領域が使用 (処理) されたため再び処理すべきではないということを認識します。使用された領域を設定するには、次のメソッドを使用します。
public void setConsumedRegion(BlockScreenRegion region)
ComponentElement クラスの詳細については、HATS API 資料を参照してください。

コンポーネント・クラスの拡張

HATS はホスト・コンポーネント・クラスの番号を提供します。ComponentWidget.xml ファイル内にあるすべてのホスト・コンポーネントのクラスは、新規コンポーネント用に作成された .java ファイル内のステートメント public class MyCustomComponent extends Component を既存コンポーネントのクラス名で置換することによって拡張できます。例えば、次のように設定されます。

public class MyCustomComponent 
             extends com.ibm.hats.transform.components.CommandLineComponent

注:
双方向コンポーネントは com.ibm.hats.transform.components.BIDI パッケージに保管されています。コンポーネントの双方向クラスの名前は、通常のコンポーネントの名前と同じですが、例えば com.ibm.hats.transform.components.BIDI.CommandLineComponentBIDI のように最後に「BIDI」が付きます。

各 HATS コンポーネントは、recognize() メソッドでホスト画面のエレメントの認識を実行します。ホスト・コンポーネントを拡張し、必要とする特定の認識タスクを実施するには、次のアプローチのいずれかを使用できます。

HATS は、<HATS:Component> タグの type 属性設定に基づいて、カスタム・コンポーネントのインスタンスを生成します。

ComponentWidget.xml ファイルを編集するには、HATS Toolkit の「ナビゲーター」タブをクリックします。 ComponentWidget.xml ファイルは、プロジェクトの 「ナビゲーター」ビューの下部に表示されます。ComponentWidget.xml ファイルの詳細については、コンポーネントまたはウィジェットの登録を参照してください。

カスタム HTML ウィジェットの作成

HATS は「ウィジェットの作成 (Create Widget)」ウィザードを提供しており、カスタム・ウィジェットの作成を支援します。いくつかの方法でウィザードを開始できます。

「ウィジェットの作成」ウィザードには 2 つのパネルがあります。最初のパネルでは、プロジェクト名、新規ウィジェット名、ウィジェットの Java パッケージ名を入力します。 オプションで、新規ウィジェットによって使用される設定の構成用の GUI パネルを定義できるスタブ・メソッドを組み込むためのチェック・ボックスを選択することができます (詳しくは、カスタム・コンポーネントおよびウィジェットの設定に対する HATS Toolkit のサポートを参照)。 2 番目のパネルでは、HATS Toolkit で新規ウィジェット名として表示する名前を入力し、そのウィジェットに関連付けるコンポーネントを選択します。

このウィザードにより、以下のカスタム・ウィジェットの必須エレメントが提供されます。

チェック・ボックスを選択し HATS Toolkit グラフィカル・ユーザー・インターフェースのサポート・メソッドを組み込んだ場合は、ウィジェットの設定変更が可能になると共に、「ウィジェットの作成」ウィザードで以下のメソッドが追加されます。

カスタム・ウィジェットのサポートに必要なメソッドの詳細については、カスタム・コンポーネントおよびウィジェットの設定に対する HATS Toolkit のサポートを参照してください。

ウィジェット・クラスの拡張

HATS はウィジェット・クラスの番号を提供します。次のコンポーネントを置換して ComponentWidget.xml ファイル内にあるウィジェットのクラスを拡張できます。

public class MyCustomWidget extends Widget implements HTMLRenderer

作成された .java ファイル内のこのウィジェットを、次のような既存のウィジェットのクラス名を持つ新規ウィジェットと置換します。

public class MyCustomWidget extends 
  com.ibm.hats.transform.widgets.FieldWidget            

注:
双方向ウィジェットは com.ibm.hats.transform.widgets.BIDI パッケージに保管されています。ウィジェットの双方向クラスの名前は、通常のウィジェットの名前と同じですが、例えば次のように最後に「BIDI」が付きます。
com.ibm.hats.transform.widgets.BIDI.FieldWidgetBIDI

既存ウィジェットを変更する場合は、既存ウィジェット・クラスの 1 つを拡張し、その drawHTML メソッドをオーバーライドする必要があります。ウィジェットのインターフェースとメソッドの詳細については、HATS API 資料を参照してください。

HATS は、<HATS:Component> タグのウィジェット属性設定に基づいて、カスタム・ウィジェットのインスタンスを生成します。

ウィジェットとグローバル規則

入力フィールドを表すウィジェットは、入力フィールドが HATS グローバル規則によってすでに処理されているかどうかを確認します。ホスト画面が受信されると、HATS はそこから、その HATS アプリケーションに対して定義されたグローバル規則と一致するホスト・コンポーネントを検索します。入力フィールドが HATS グローバル規則によってすでに処理されているかどうかをウィジェットが確認する際、入力フィールドが処理されていない場合、呼び出しはヌルを戻します。入力フィールドがグローバル規則に従ってすでに処理されている場合、この呼び出しは、グローバル規則によって入力フィールドから変換された変換フラグメントを戻します。ウィジェットは、コンポーネント・エレメントを処理するのではなく、フラグメントを出力しなければなりません。Web アプリケーション用の例を以下に示します。

String ruleReplacement = 
		RenderingRulesEngine.processMatchingElement(componentElement, contextAttributes);
if (ruleReplacement != null) {
		buffer.append(ruleReplacement);
} else {
    .
    .
    .
}

ウィジェットの drawHTML() メソッドに上記の例を追加してください。

コンポーネントまたはウィジェットの登録

カスタム・コンポーネントおよびウィジェットを ComponentWidget.xml ファイルに登録すると、HATS Toolkit で使用可能になります。例えば、「ホスト・コンポーネントを挿入」ウィザードで使用できます。

ホスト・コンポーネントを、特定のウィジェットにマップする必要があります。カスタム・ホスト・コンポーネントは、既存のウィジェットまたはカスタム・ウィジェットのいずれにもマップすることができます。カスタム・コンポーネントやウィジェットの「作成」ウィザードは、ユーザーのカスタム・コンポーネントとウィジェットを ComponentWidget.xml ファイルに登録し、コンポーネントとウィジェットを関連付けます。カスタム・コンポーネントとウィジェットを関連付けずにウィザードを使用した場合、ComponentWidget.xml ファイルを編集し、関連を追加する必要があります。ComponentWidget.xml ファイルを編集するには、HATS Toolkit の「ナビゲーター」タブをクリックします。 ComponentWidget.xml ファイルは、プロジェクトの 「ナビゲーター」ビューの下部に表示されます。

注:
登録後にカスタム・コンポーネントまたはウィジェットを削除する場合、コンポーネントやウィジェットのソース・コードをプロジェクトのソース・フォルダーから削除するだけでは完全に除去することはできません。レジストリー内ではなお参照されており、プログラマチックに除去する方法はありません。ComponentWidget.xml ファイルを編集してレジストリーから除去し、そのコンポーネントまたはウィジェットへの参照を削除する必要があります。

次に、HATS が提供するフィールド・テーブル・コンポーネントおよび関連ウィジェットの 1 つ、垂直バー・グラフ・ウィジェットを表示する ComponentWidget.xml ファイルの例を示します。

<ComponentWidgetList>
  <components>
    <component className="com.ibm.hats.transform.components.FieldTableComponent" 
							displayName="Field table" image="table.gif"> 
      <associatedWidgets> 
        <widget className="com.ibm.hats.transform.widgets.VerticalBarGraphWidget"/> 
      </associatedWidgets> 
    </component>
  </components>


  <widgets>
    <widget className="com.ibm.hats.transform.widgets.VerticalBarGraphWidget" 
							displayName="Vertical graph" image="verticalBarGraph.gif" />
  </widgets>
</ComponentWidgetList> 

ご覧のように、このファイルには、コンポーネントとウィジェットの 2 つのセクションがあります。

コンポーネント・セクションには、登録されたコンポーネントの全リストが含まれています。カスタム・コンポーネントを登録し、HATS Toolkit で使用可能にするには、<component> タグと関連の <widget> タグを ComponentWidget.xml ファイルに追加します。className、displayName、および関連ウィジェットを指定する必要があります。

className
ホスト画面のエレメントを認識するコードを含む Java クラスを示します。通常、クラス名の形式は myCompany.myOrg.ClassName です。
displayName
カスタム・コンポーネントの既知名と、HATS Toolkit でそれがどのようにコンポーネントのリストに表示されるかを示します。この名前は、登録済みのコンポーネント間で固有である必要があります。カスタム・コンポーネントの displayName の形式は、単純なストリングです。スペースは、displayName に使用できます。
image
image 属性は、HATS Toolkit での表示用に使用するコンポーネントのイメージを示します。
ウィジェット
このコンポーネントに関連付けられたウィジェットを識別します。関連付けられた各ウィジェットには、個別の <widget> タグが必要です。コンポーネントの <widget> タグはすべて、<associatedWidgets> タグおよび、その </associatedWidgets> 終了タグの中で定義される必要があります。<associatedWidgets> タグ内の <widget> タグには、className 属性のみがあり、これはウィジェットをコンポーネントにリンクするコードを含む Java クラスを識別します。通常、クラス名の形式は myCompany.myOrg.ClassName です。

ウィジェット・セクションには、登録されたウィジェットの全リストが含まれています。ウィジェットを登録し、コンポーネントにリンクし、HATS Toolkit で使用可能にするには、<widget> タグを ComponentWidget.xml ファイルに追加します。className および displayName を指定する必要があります。

className
ウィジェットをレンダリングするコードを含む Java クラスを識別します。通常、クラス名の形式は myCompany.myOrg.ClassName です。
displayName
カスタム・ウィジェットの既知名と、HATS Toolkit でウィジェットのリストに表示される方法を識別します。この名前は、登録済みウィジェットの中で一意である必要があります。カスタム・ウィジェットの displayName の形式は、単純なストリングです。スペースは、displayName に使用できません。ただし、スペースの代わりに下線 ( _ ) を使用することができます。

カスタム・コンポーネントおよびウィジェットの設定に対する HATS Toolkit のサポート

カスタム・コンポーネントおよびカスタム・ウィジェットの設定の変更に GUI サポートを提供できます。この GUI は、作成したカスタム・コンポーネントまたはカスタム・ウィジェットを他の開発者が使用する場合か、または HATS Toolkit で使用可能なプレビュー機能を使用して、設定の異なる組み合わせのテストを簡単に行う場合に役立ちます。基本コンポーネントおよびウィジェット・クラスにより、ICustomPropertySupplier インターフェースがインプリメントされます。このインターフェースを使用すれば、コンポーネントまたはウィジェットによる HATS Toolkit への設定情報の提供ができます。この情報は、コンポーネントまたはウィジェットの設定を変更できるパネルのレンダリングに使用されます。すべての設定をこの GUI で公開する必要はありません。

getCustomProperties() メソッドは、HCustomProperty でカスタマイズ可能なプロパティー・オブジェクトのベクトルを戻します。各 HCustomProperty オブジェクトは、コンポーネントまたはウィジェットの設定を表します。 HATS Toolkit は、各 HCustomProperty オブジェクトをそのタイプに基づいてレンダリングします。例えば、HCustomProperty.TYPE_BOOLEAN タイプのオブジェクトは、GUI のチェック・ボックスとしてレンダリングされます。

以下のサンプル・コードは、ウィジェットがその 3 つの設定 (mySetting1、mySetting2、および mySetting3) に対してどのように GUI サポートを提供できるのかを示しています。

// Returns the number of settings panels (property pages) to be contributed 
//by this widget.  The returned value must be greater than or equal to 1 if 
//custom properties will be supplied via the getCustomProperties() method.  
public int getPropertyPageCount() {
         return 1;     
}

// Returns a Vector (list) of custom properties to be displayed in the GUI 
//panel for this component or widget.     
public Vector getCustomProperties(int iPageNumber, Properties properties, 
         ResourceBundle bundle) {
         Vector props = new Vector();          

// Constructs a boolean property that will be rendered as a checkbox         
HCustomProperty prop1 = HCustomProperty.new_Boolean("mySetting1", 
                "Enable some boolean setting", false, null, null);         
props.add(prop1); 

// Constructs a string property that will be rendered as a text field         
HCustomProperty prop2 = HCustomProperty.new_String("mySetting2", 
                "Some string value setting", false, null,
                 null, null, null);         
props.add(prop2);          

// Constructs an enumeration property that will be rendered as a drop-down         
HCustomProperty prop3 = HCustomProperty.new_Enumeration("mySetting3", 
                 "Some enumerated value setting", false,
                 new String[] { "A", "B", "C" }, new String[] 
                 { "Option A", "Option B", "Option C" }, null, null, null);
props.add(prop3);          

return props;     }
ウィジェット GUI

カスタム・コンポーネントまたはウィジェットのユーザーによって指定された値が、コンポーネントの recognize() メソッドに渡された componentSettings プロパティー・オブジェクト、またはウィジェットのコンストラクターに渡された widgetSettings プロパティー・オブジェクト内で使用可能になります。 getCustomProperties() メソッドは、設定用のデフォルト値を収集するために実行時に呼び出される可能性があります。

これらのメソッドの引数および使用法については、HATS API 資料の HCustomProperty クラスの項を参照してください。