概要   パッケージ  クラス  階層ツリー  非推奨 API  索引  ヘルプ 
 前のパッケージ   次のパッケージ フレームあり    フレームなし    

パッケージ org.apache.struts.taglib.html

"struts-html" タグライブラリには、 HTML を用いた入力フォームなどのユーザインターフェースを動的に生成するのに有用な JSP カスタムタグが含まれています。

参照:
          説明

クラスの概要
BaseFieldTag Convenience base class for the various input tags for text fields.
BaseHandlerTag Base class for tags that render form elements capable of including JavaScript event handlers and/or CSS Style attributes.
BaseInputTag Abstract base class for the various input tags.
BaseTag Renders an HTML element with an href attribute pointing to the absolute location of the enclosing JSP page.
ButtonTag Renders an HTML BUTTON tag within the Struts framework.
CancelTag Tag for input fields of type "cancel".
CheckboxTag Tag for input fields of type "checkbox".
Constants Manifest constants for this package.
ErrorsTag Custom tag that renders error messages if an appropriate request attribute has been created.
FileTag Custom tag for input fields of type "file".
FormTag Custom tag that represents an input form, associated with a bean whose properties correspond to the various fields of the form.
HiddenTag Custom tag for input fields of type "text".
HtmlTag Renders an HTML element with appropriate language attributes if there is a current Locale available in the user's session.
ImageTag Tag for input fields of type "image".
ImgTag Generate an IMG tag to the specified image URI.
LinkTag Generate a URL-encoded hyperlink to the specified URI.
MultiboxTag Tag for input fields of type "checkbox".
OptionsTag Tag for creating multiple <select> options from a collection.
OptionTag Tag for select options.
PasswordTag Custom tag for input fields of type "text".
RadioTag Tag for input fields of type "radio".
ResetTag Tag for input fields of type "reset".
RewriteTag Generate a URL-encoded URI as a string.
SelectTag Custom tag that represents an HTML select element, associated with a bean property specified by our attributes.
SubmitTag Tag for input fields of type "submit".
TextareaTag Custom tag for input fields of type "textarea".
TextTag Custom tag for input fields of type "text".
 

パッケージ org.apache.struts.taglib.html の説明

"struts-html" タグライブラリには、 HTML を用いた入力フォームなどのユーザインターフェースを動的に生成するのに有用な JSP カスタムタグが含まれています。

[イントロダクション] [HTML フォームタグ] [その他の HTML タグ]

イントロダクション

Struts の HTML タグライブラリに含まれるタグは JSP と Web アプリケーションの他のコンポーネントとの橋渡しを行います。 動的な Web アプリケーションでは、ユーザから情報を集めなければならないことが頻繁にあるので、 入力フォームは Struts フレームワークにおいて重要な役割を果たします。 そのため、HTML タグライブラリの大部分は HTML フォームに関するものになります。 それ以外に HTML タグライブラリによって処理される重要なものとしては、 エラーメッセージ、ハイパーリンク、 そして国際化があります。

HTML "form" タグ

これらのタグは全て <html:form> タグの中にネストしていなければなりません。

フォームタグについて

Struts の form タグは標準の HTML フォームタグを出力し、入力フォームを Struts の ActionForm クラスのサブクラスである JavaBean のオブジェクト ( Javadoc を参照 ) と関連付けます。 入力フォーム内のそれぞれのフィールドはフォーム bean のプロパティと対応していなければなりません。 最初、入力フォームには bean の対応するプロパティの値が設定され、 その入力フォームがコントローラサーブレットにサブミットされたとき、ユーザが入力した値が bean に格納されます。

bean の名前とそのクラスはフォームタグのプロパティとして指定することができますが、省略することも可能です。 省略した場合、 struts-config.xml ファイルからロードされた ActionMappings から情報を取得します。もし現在のページが action の input プロパティとして指定されているのであれば、その action の name プロパティが省略された値の代わりに使用され、bean の type プロパティの値もまた、 struts-config.xml のフォーム bean 定義を通じて取得されます。

以下は Struts Example の設定からの抜粋です : 

<action-mappings>
  <!-- Process a user logon -->
  <action path="/logon"
    type="org.apache.struts.example.LogonAction"
    name="logonForm"
    scope="request"
    input="/logon.jsp">
  </action>
  < ... />
</action-mappings>
<form-beans>
  <!-- Logon form bean -->
  <form-bean name="logonForm"
    type="org.apache.struts.example.LogonForm"/>
  < ... />
  </form-beans>
</pre>

この設定が与えられた場合、 logon.jsp における HTML フォームタグはデフォルトで "logonForm" をその name プロパティとして、また、 "org.apache.struts.example.LogonForm" を type プロパティとして使用します。 これにより、設定ファイルを用いてフレームワークコンポーネントの名前空間の管理が行えるようになっています。

もしフォームタグが ( page, request, session, application ) のどのスコープにもフォーム bean を見つけることができなかった場合、指定された type を用いて新しいフォーム bean のインスタンスを生成します。

Struts の ActionForm クラスは標準の reset() メソッドと、 コントローラによって呼び出され、自動的なデータのバリデーションを可能にする validate() メソッドを持っています。フォームのバリデーションについてのより詳しい情報は Users Guide を参照してください。 バリデーションの重要な側面のひとつは、エラーをユーザに通知することです。これは Struts の errors タグによってハンドリングされます。 errors タグについてはこのドキュメントの後の方で議論します。

共通のフォームタグ属性

Struts-HTML タグライブラリのうち、フォーム内の "フィールド"を表すタグにはいくつかの共通の属性があります。 それら共通の属性は、それがどの フィールドタグの中で用いられていても、常に同じ意味を持っています。 これらの属性はまた、実行式を値として受けつける、つまり、スクリプトレットによる値の設定も可能です。 共通の属性は Struts の共通属性、 HTML ナビゲーション属性、 Javascript イベントハンドラ、そして CSS 属性 の4つのカテゴリに分類されます。

Struts の共通属性
name ActionForm bean の名前です。 この入力フィールドの現在の値を書き出す際に、ここで指定されたActionForm bean のプロパティが調べられます。 指定されない場合、このタグをネストしているフォームタグに関連付けられた bean が利用されます。
property リクエストパラメータの名前です。サブミット時に、指定された値を設定して送信されます。
value この要素に用いられるラベルの値です。 この値は指定されたリクエストパラメータの値としてサブミットされます。 [ ( もしあれば ) このタグのボディ部、さもなくば "Click" ]

 

Struts-Bean タグのように、 Struts-HTML タグの property 属性も、単純な、ネストした、そしてインデックス付けされた式を受け付けることができます。 例えば : 

  <html:text property="mailingAddress.street"/>

というタグは、

  getMailingAddress().getStreet()

という表現に対応します。

Struts の、単純な、ネストした、そしてインデックス付けされた式に関するより詳しい情報は、 Struts-Bean Developers Guide を参照してください。

Javascript イベントハンドラ
onblur この要素がフォーカスを失ったときに実行されます。
onchange この要素の値が変更され、そして入力フォーカスを失ったときに実行されます。
onclick この要素がクリックされたときに実行されます。
ondblclick この要素がダブルクリックされたときに実行されます。
onfocus この要素に入力フォーカスが移ったときに実行されます。
onkeydown この要素がフォーカスを持ち、キーが押されたときに実行されます。
onkeypress この要素がフォーカスを持ち、キーが押されて離されたときに実行されます。
onkeyup この要素がフォーカスを持ち、キーが離されたときに実行されます。
onmousedown この要素にマウスポインタがあてられ、マウスボタンが押されたときに実行されます。
onmousemove この要素にマウスポインタがあてられ、マウスポインタが動いたときに実行されます。
onmouseout この要素にあてられていたマウスポインタが要素の外に移動したときに実行されます。
onmouseover この要素にマウスポインタがあてられたときに実行されます。
onmouseup この要素にマウスポインタがあてられ、マウスボタンが離されたときに実行されます。
  "親となる" フォームタグのみで利用可
onreset フォームがリセットされたときに実行されます。
onsubmit フォームがサブミットされたときに実行されます。
 
HTML ナビゲーション属性
accesskey この要素に瞬時にフォーカスを移動させるために用いるキーボードキャラクタです。
tabindex この要素にあたえるタブの順序 ( 昇順の正の整数 ) です。
 
CSS 属性
style この HTML 要素に適用する CSS スタイルです。
styleClass この HTML 要素に適用する CSS スタイルシートの class です。

 

このタグライブラリの有効なタグと、それぞれのタグの有効な属性の完全なリストについての詳細は HTML タグリファレンスを参照してください。

それ以外の HTML タグ

フォーム処理のほかに、Struts-HTML はエラーメッセージの表示や、ハイパーリンクの整備、 そしてアプリケーションの国際化を手助けするいくつかのタグやタグプロパティを提供しています。

エラーメッセージの表示

エラーのハンドリングはどんなアプリケーションにおいても重要な部分を占めます。 そして、エラーの解決には、しばしばユーザの助けが必要となります。 Struts は、国際化機能を提供するために使われているのと同じテクノロジをベースとした、 実行時にユーザにメッセージを伝えるための一般化された方法を提供します。

Web アプリケーションにおいて、エラーメッセージを表示するために入力ページを再利用することはよくあることです。 Struts のエラーメッセージタグは、メッセージを表示したいところに自由に置くことができます。 もし表示待ちのメッセージがない場合、なにも出力されません。

デフォルトでは errors タグは全ての表示待ちメッセージを出力します。 また、メッセージをキューに追加するときにプロパティを指定し、 errors タグの中でそのプロパティを用いてメッセージを参照することも可能です。 その場合、そのプロパティに関するメッセージだけが表示されることになります。 これは、エラーが発生する原因となったフィールドのとなりにメッセージを置きたい場合に有用です。

エラーメッセージは ActionForm の validate メソッドの中でキューに追加されることがよくあります。 下記は Struts Example アプリケーションからの抜粋です。 

  ActionErrors errors = new ActionErrors();
  if ((username == null) || (username.length() < 1))
      errors.add("username", new ActionError("error.username.required"));
  if ((password == null) || (password.length() < 1))
      errors.add("password",
        new ActionError("error.password.required"));

この例では、"username" フィールド用のと "password" フィールド用の、二つのエラーメッセージをキューに追加しています。 単純に、JSP の任意の場所に errors タグを置けば、全てのメッセージを一緒に出力することができます。 

  <body bgcolor="white">
  <html:errors/>

また、指定したエラーメッセージを別の場所に置くこともできます。

  <td align="left">
    <html:text property="username" size="16" maxlength="16"/>
    <html:errors property="username"/>
  </td>
  </tr><tr>
  <td align="left">
    <html:text property="password" size="16" maxlength="16"/>
    <html:errors property="password"/>
  </td>

デフォルトでは実際のエラーメッセージはアプリケーション標準のメッセージリソースから検索されます。 これは、アプリケーションで利用されるエラーメッセージのマスターリストを開発者に提供し、国際化に備えます。 上記のコードの断片では "error.username.required" に対応するメッセージが実行時に検索され、 ユーザに向けて表示されます。 

  error.username.required=<li>Username is required</li>

もっともよくあるのは、エラーメッセージを特別な方法で表示することです。 簡単にメッセージの表示形式を整えるために、メッセージリソースの中で errors.header と errors.footer を指定することができます。 典型的な例として、メッセージを異なる配色で書き出したいとか、 あるいは番号なしリスト中にメッセージが現れるようにセットアップしたい、と思うかもしれません。 errors.header と errors.footer を使用することで、 実際にメッセージが出力されるまでのセットアップのコードを JSP の外部に置くことができます。 

  errors.header=<h3><font color="red">Validation Error</font></h3>
    You must correct the following error(s) before proceeding:<UL>
  errors.footer=</ul><hr>

ハイパーリンクの整備

Web アプリケーションを実装するとき、同一アプリケーション内の他のファイルに対して相対参照を用いることは通常は良い考えです。 しかし、動的なアプリケーションにおいては、コントローラサーブレットはしばしばリクエストされたものとは完全に異なるファイルを返します。 ( リクエストされた "ファイル" は実はコントローラが解釈する action であって、現実に存在するファイルではないということがよくあります。 ) 相対参照はブラウザによって解決されるので、動的なアプリケーションにおいてはうまく機能しないことがしばしばでてきます。

この問題を調整するために、Struts-HTML タグライブラリは <base> タグを提供します。 このタグは、そのページの絶対位置を指し示す href 属性を伴う HTML の <base> 要素を書き出します。

一般に、Struts-HTML の base タグは、他のファイルへの相対参照を用いている JSP の <head> 要素内に置くべきです。 

  <head>
    <html:base/>
  </head>

セッショントラッキング

Java Servlet フレームワークには、セッションを通じてクライアントを追跡するための機能が組み込まれています。 セッションは HTTP のステートレスな性質を補う有用な方法です。 クライアントの追跡はクッキーか URL リライティングのいずれか ( クッキーが有効な場合はクッキーの使用が優先されます ) によってなされます。 Struts は "セッション情報を知っている" ハイパーリンクを容易に作成することのできる3つのタグを提供します。

これらのタグの各々はクッキーがない状態でセッションの状態を維持するために、自動的にURL リライティングを適用します。 ハイパーリンクのために表示されるコンテンツはタグのボディ部から取得され、 ベースとなる URL はタグに与えられたプロパティを基にして計算されます。

通常、指定するハイパーリンクまたは URI は変更されません。 もし、ハイパーリンクまたは URI に動的なパラメータを含めたいのであれば、 それらを JavaBean を通じてタグに渡すことができます。 もし名前が衝突する可能性がある場合、タグが bean を検索するスコープ ( request, page, session, application ) を指定することもできます。

単一の動的なパラメータを渡すには paramId 属性を用いてパラメータ名を指定します。 その後、値を保持している JavaBean の名前を paramName 属性で、 特定のプロパティを paramProperty で、それぞれ指定します。

したがって、次のようなタグは、

   <html:link href="detail.html"
              paramId="target"
              paramName="linkParams"
              paramProperty="target"
              paramScope="request"
   >detail.html</html:link>

次のような表現に対応します。

  <A HREF="detail.html?target=<%= 
    request.getParameter("linkParams").getTarget()
  %>">detail.html</A>

paramScope 属性が省略された場合、全てのスコープ ( request, page, session, application ) が検索されます。

指定された bean 自体が String 型に変換できる値となりうるのであれば、 paramProperty 属性は省略されることもあります。

複数の動的なパラメータを渡すには、それらを java.util.Map の中に格納し、 paramName 属性の値としてマップの名前を用います。 マップにはひとつもしくはそれ以上の paramId と、それに対応する値がなくてはなりません。 マップが処理される際、キーは追加されるクエリパラメータの名前であると解釈され、 各々のキーに関連付けられた値はパラメータの値を表わす String か String の配列でなくてはなりません。 もし String 配列が指定されている場合、同じクエリパラメータ名に対してひとつ以上の値が生成されます。

HTML のセッショントラッキングタグにはいくつかの共通の属性が使用されており、 それらは次のような3つのグループに分類することができます。 これらの属性は全て、( link, rewrite, img ) の3つのタグどれに対しても使用できるというわけではないので、それぞれの属性を使用可能なタグについても示してあります。

 
forward, href および page
forward [ link rewrite ] - この転送先の実際のコンテンツ相対 URI を含むグローバル ActionForward の論理名です。 タグの解説で記述しているように、 このハイパーリンクはクエリパラメータが含まれることによって動的に修正されることがあります。 forward 属性、href 属性、linkName 属性あるいは page 属性のいずれかひとつを必ず指定しなければなりません。
href このハイパーリンクが実行されたときに制御の転送先となる URL です。 タグの解説で記述しているように、 このハイパーリンクはクエリパラメータが含まれることによって動的に修正されることがあります。 forward 属性、href 属性、linkName 属性あるいは page 属性のいずれかひとつを必ず指定しなければなりません。
page このタグによって表示されるイメージの、スラッシュから始まるコンテキスト相対パスです。 このイメージ用に与えられた URL は、任意の必要な URL リライティングに加えて、 link タグ上の page 属性と同じ方法で、自動的にこの Web アプリケーションのコンテキストパスを装います。 page 属性あるいは src 属性のいずれかを指定しなければなりません。

 
linkName, Target および src
linkName [ link ] - このページ内に定義されるアンカー名で、これを指定しておけば、 そのページ内のハイパーリンクでそれを参照することができます。 言いかえると、ここに指定された値は生成された anchor タグ中の name 要素になります。
target [ link img ] - このハイパーリンクによって要求されたリソースが表示されるターゲットとなるウィンドウで、 例えばフレームに分割されたプレゼンテーションなどで指定します。
src [ img ] - タグの解説で記述しているように、このイメージからの転送先となる URL はクエリパラメータが含まれることによって動的に修正されることがあります。 この値は、行われるかもしれない URL リライティング以外では変更されることなく使用されます。 page 属性あるいは src 属性のいずれかを指定しなければなりません。

 
paramId, paramName, paramProperty, paramScope
paramId [ link img ] - 生成される src 属性に動的に追加されるリクエストパラメータの名前です。 その対応する値は paramName 属性と、オプションの paramProperty 属性によって定義され、 さらにオプションで paramScope 属性によって bean を検索するスコープが決定されます。
paramName [ link img ] - paramProperty 属性が指定されていない場合は paramId 属性によって名づけられたリクエストパラメータの値を含んでいる文字列である JSP bean の名前、paramProperty 属性が指定されている場合は String を返すプロパティ用のゲッターを持つ JSP bean の名前です。 JSP bean は、もし paramScope 属性が指定されていれば、その指定されたスコープ内のものに制限されます。
paramProperty [ link img ] - paramName 属性によって指定された bean のプロパティの名前です。 このプロパティ用のゲッターの戻り値は paramId 属性によって名づけられたリクエストパラメータの値を含む String でなければなりません。 リクエストパラメータはこのハイパーリンクまたは src 属性の URL に動的に追加されます。
paramScope [ link img ] - paramName 属性によって指定された bean を検索するスコープです。 指定されない場合、すべてのスコープが検索されます。

 
name, property, scope
name [ link rewrite img ] - property 属性が指定されていない場合、クエリパラメータを表す Map を含む JSP bean の名前、property 属性が指定されている場合は、Map を返すプロパティ用のゲッターを持つ JSP bean の名前です。
property [ link rewrite img ] - name 属性で指定された bean のプロパティの名前で、 その戻り値は src 属性に指定された URL に追加されるクエリパラメータを含んでいる Map でなければなりません。この属性を指定する場合、name 属性を必ず指定する必要があります。
scope [ link rewrite img ] - name 属性によって指定された bean を検索するスコープです。 指定されない場合、すべてのスコープが検索されます。

各々のタグの有効な属性の完全なリストは HTML タグリファレンス を参照してください。

国際化

国際化は適切な場所で、HTML タグによって自動的にサポートされます。

Errors - デフォルトでは、 メッセージ用のテキストはユーザ環境にふさわしい言語を選択したデフォルトのメッセージリソースによって返されます。 bundle 属性を使用することで、別のメッセージリソースを指定することもできます。

HTML - ユーザの現在のロケールオブジェクトが1つある場合、そこから抜き出した language 属性を指定して HTML 要素を書き出します。

image と img - オプションとして、そのバイナリソースと代替文字列の値をメッセージリソースから取得することができます。 これにより、異なるロケールに対して、異なるイメージや代替文字列を提供することができます。 HTML タグリファレンス で タグの altKey、srcKey および bundle 属性を参照してください。

Struts がアプリケーションを国際化するのをどのようにサポートするかの詳細については Users Guide を参照してください。

 

概要   パッケージ  クラス  階層ツリー  非推奨 API  索引  ヘルプ 
 前のパッケージ   次のパッケージ フレームあり    フレームなし    
このドキュメントは、Ja-Jakartaにより訳されました。コメントがある場合は、report@jajakarta.orgまでお願いします。
Copyright (C) 2000-2002 - Apache Software Foundation