タグ ライブラリ記述子の作成

以下の節では、タグ ライブラリ記述子（TLD）ファイルを作成する方法について説明します。

• タグ ライブラリ記述子の概要

• タグ ライブラリ記述子の記述

• タグ ライブラリ記述子のサンプル

 

---

タグ ライブラリ記述子の概要

タグ ライブラリを使用すると、開発者は関連する機能を持つタグを 1 つにまとめることができます。タグ ライブラリには、タグ拡張を記述し、それらを Java クラスに関連付けるタグ ライブラリ記述子（TLD）ファイルが必要となります。TLD は、WebLogic Server とオーサリング ツールが拡張機能に関する情報を取得するために使用されます。TLD ファイルは、XML 表記法で記述します。

タグ ライブラリ記述子の構文は文書型定義（DTD）に指定されており、 http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd で入手できます。

 

---

タグ ライブラリ記述子の記述

タグ ライブラリ記述子ファイル内の要素は、この DTD に定義されている順序で並べます。この順序付けは、以下に示す手順で使用されます。TLD 要素がこの順序どおりに並べられていない場合、XML パーサは例外を送出します。

TLD の本体は、<taglib> ... </taglib> 要素の中にネストされた要素を含んでいます。これらのネストされた要素についても次の手順で説明します。このドキュメントでは、見やすくするためにネストされた要素はその親要素からインデントされていますが、TLD ではインデント処理は必要ありません。

タグ ライブラリ記述子のサンプルの例では、code という新しいタグを宣言します。このタグの機能は、Java クラスの weblogic.taglib.quote.CodeTag によって実装されます。

タグ ライブラリ記述子を作成するには、次の手順に従います。

1. テキスト ファイルを作成して、適切な名前と拡張子 .tld を付け、JSP を持つ Web アプリケーションの WEB-INF ディレクトリに置きます。WEB-INF ディレクトリの内容は非公開で、WebLogic Server によって HTTP を介して提供されません。

2. 次のヘッダを追加します。

   <!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.
    //DTD JSP Tag Library 1.1//EN" "web-jsptaglib_1_1.dtd">

3. TLD のコンテンツを、<taglib> 要素の中に埋めこみます。コンテンツには、タグ ライブラリに関する情報を含む要素と、各タグを定義する要素が含まれます。次に例を示します。

   <taglib>
     ... taglib 記述子の本体 ...
   </taglib>

4. タグ ライブラリを指定します。

   <tlib-version>version_number</tlib-version>

   （必須）タグ ライブラリのバージョン番号。

   <jsp-version>version_number</jsp-version>

   （必須）このタグ ライブラリが機能するために必要な JSP 仕様のバージョン（番号）を記述します。デフォルトは 1.2 です。

   <shortname>TagLibraryName</shortname>

   （必須）タグ ライブラリに短縮名を割り当てます。この要素は、WebLogic Server では使用されません。

   <uri>unique_string</uri>

   （必須）このバージョンのタグ ライブラリをユニークに識別するパブリックな URI を定義します。

   <display-name>display_name</display-name>

   （省略可能）ツールによって表示される短縮名を指定します。

   <smallicon>icon.jpg</smallicon>

   （省略可能）小さいアイコン（16x16）の画像が含まれるファイルの名前を指定します。ファイル名はタグ ライブラリ内の相対パスです。画像は JPEG または GIF 形式で、ファイル名はそれぞれ「.jpg」または「.gif」というサフィックスで終わる必要があります。アイコンはツールによって使用されます。

   <largeicon>icon.jpg</uri>

   （省略可能）大きいアイコン（32x32）の画像が含まれるファイルの名前を指定します。ファイル名はタグ ライブラリ内の相対パスです。画像は JPEG または GIF 形式で、ファイル名はそれぞれ「.jpg」または「.gif」というサフィックスで終わる必要があります。アイコンはツールによって使用されます。

   <description>...text...</description>

   （必須）タグ ライブラリについて説明する任意のテキスト文字列を定義します。

   <validator>unique_string</validator>

   （省略可能）このタグでスクリプト変数の情報を定義します。1 つまたは複数の変数のサブ要素を持つべきタグに null 以外のオブジェクトを返させるための変換時エラーを提供する TagExtraInfo クラスです。

   <listener>unique_string</listener>

   （省略可能）自動的にインスタンス化および登録される任意のイベント リスナ オブジェクトを定義します。

5. タグ ライブラリ バリデータを定義します（省略可能）。

   <validator>

   バリデータの最上位要素。

   <validator-class>my.validator</validator-class>

   （必須）検証を実行する Java クラス。

   <init-param>

   （省略可能）バリデータ クラスの初期化パラメータを定義します。

   <param-name>param</param-name>

   このパラメータの名前を定義します。

   <param-value>value</param-value>

   このパラメータの値を定義します。

6. タグを定義します。

   タグ ライブラリに新しいタグを定義するには、それぞれ別個の <tag> 要素を使用します。<tag> 要素には、以下のネスト タグを埋め込むことができます。

   <name>tag_name</name>

   （必須）タグの名前を指定します。JSP ファイルのタグを参照するときに、次のように「:」という記号の後に使用します。

   <mytaglib:tag_name>

   詳細については、JSP でのカスタム タグの使い方を参照してください。

   <tag-class>package.class.name</tag-class>

   （必須）このタグの機能を実装するタグ ハンドラ クラスを宣言します。そのクラスの完全修飾パッケージ名を指定します。

   クラス ファイルは、WEB-INF\classes ディレクトリの下に、パッケージ名を反映したディレクトリ構造に従って配置します。タグ ライブラリ jar ファイルにクラスをパッケージすることもできます。詳細については、JSP タグ ライブラリを JAR ファイルとしてデプロイするを参照してください。

   <teiclass>package.class.name</teiclass>

   （省略可能）このタグによって導入されるスクリプト変数を記述する TagExtraInfo のサブクラスを宣言します。タグが新しいスクリプト変数を定義しない場合、この要素は使われません。そのクラスの完全修飾パッケージ名を指定します。このクラスに含まれるタグの属性を検証できます。

   クラス ファイルは、Web アプリケーションの WEB-INF\classes ディレクトリの下に、パッケージ名を反映したディレクトリ構造に従って配置します。タグ ライブラリ jar ファイルにクラスをパッケージすることもできます。詳細については、JSP タグ ライブラリを JAR ファイルとしてデプロイするを参照してください。

   <body-content>tagdependent | JSP | empty</body-content>

   （省略可能）タグ本体のコンテンツを定義します。

   empty を指定すると、タグは JSP ページ内で空タグ フォーマットで使用されます。たとえば、<taglib:tagname/> というように使用されます。

   JSP を指定すると、タグのコンテンツは JSP として解釈され、タグは本体付きフォーマットで使用しなければなりません。次に例を示します。

   <taglib:tagname>...</taglib:tagname>.

   tagdependent を指定すると、タグは本体のコンテンツを JSP 以外のもの（たとえば SQL 文）であると解釈します。

   <bodycontent> 要素が定義されていない場合、デフォルト値は JSP となります。

   <attribute>

   （省略可能） JSP ページ内のタグ要素に指定できる属性の名前を定義します。次に例を示します。

   <taglib:mytag myAttribute="myAttributeValue">

   タグに指定できる属性を定義するには、それぞれ別個の <attribute> 要素を使用します。タグ属性を使用すると、JSP 作成者はタグの動作を変更できます。

   <name>myAttribute</name>

   <required>true | false</required>

   （省略可能）この属性が JSP ページの中でオプションとして使用されるかどうかを定義します。

   ここで定義しない場合、デフォルトは false、つまりその属性は省略可能となります。

   true が指定され、その属性が JSP ページの中で使用されない場合、変換時エラーが発生します。

   <rtexprvalue>true | false</rtexprvalue>

   （省略可能）この属性の値としてスクリプトレット式を指定して、要求時にそれを動的に計算できるようにするかどうかを定義します。

   この要素を指定しない場合、デフォルトとして false が使用されます。

   </attribute>

7. スクリプト変数を定義します（省略可能）。

   <tag>

   要素内にスクリプト変数を定義できます。

   <variable>

   変数の宣言の最上位要素。

   <name-given>someName</name-given>

   変数の名前を定義します。使用する属性から名前を定義できます。

   <name-from-attribute>attrName</name-from-attribute>

   attrName の値を使用して変数の名前を指定します。

   <variable-class>some.java.type</variable-class>

   この変数の Java タイプ。

   <declare>true</declare>

   （省略可能）true に設定する場合、変数が定義されることを示します。

   <scope>AT_BEGIN</scope>

   スクリプト変数のスコープ。有効なオプションは以下のとおりです。

   NESTED（変数はタグ本体の内部でのみ使用できます）

   AT_BEGIN（変数は本体を実行する直前に定義されます）

   AT_END（変数は本体を実行した直後に定義されます）

   </variable>

 

---

タグ ライブラリ記述子のサンプル

以下にタグ ライブラリ記述子のサンプルを示します。

コード リスト 3-1 タグ ライブラリ記述子（tld）のサンプル

<taglib>

  <tlib-version>1.0</tlib-version>
  <jsp-version>1.1</jsp-version>
  <short-name>quote</short-name>
  <uri>tag lib version id</uri>
  <description>
     このタグ ライブラリには、HTML のコンテンツをフォーマットするのに有効な
     タグ拡張がいくつか含まれています。 
  </description>

  <tag>
    <name>code</name>
    <tag-class>weblogic.taglib.quote.CodeTag</tag-class>
    <body-content>tagdependent</body-content>
    <attribute>
      <name>fontAttributes</name>
    </attribute>
    <attribute>
      <name>commentColor</name>
    </attribute>
    <attribute>
      <name>quoteColor</name>
    </attribute>
  </tag>

</taglib>