4.12. 共通ライブラリが提供するJSP Tag Library と EL Functions

4.12.1. Overview

共通ライブラリでは、JSPの実装をサポートする機能として、 以下に示すJSP Tag Library と EL Functionsを提供している。

4.12.1.1. JSP Tag Library

共通ライブラリから提供しているJSP Tag Libraryを以下に示す。

項番
タグ名
概要
<t:pagination> ページネーションリンクを出力する。
<t:messagesPanel> 処理結果メッセージを出力する。
<t:transaction> トランザクショントークンをhidden項目として出力する。

4.12.1.2. EL Functions

共通ライブラリから提供しているEL Functionsを以下に示す。

XSS対策関連

項番
関数名
概要
f:h() 指定されたオブジェクトを文字列に変換し、変換した文字列内のHTML特殊文字をエスケープする。
f:js() 指定された文字列内のJavaScript特殊文字をエスケープする。
f:hjs() 指定された文字列内のJavaScript特殊文字をエスケープ後、HTML特殊文字をエスケープする。(f:h(f:js())のショートカット関数)

URL関連

項番
関数名
概要
f:query() 指定されたオブジェクトから、UTF-8でURLエンコーディングされたクエリ文字列を生成する。
f:u() 指定された文字列をUTF-8でURLエンコーディングする。

DOM関連

項番
関数名
概要
f:link() 指定されたURLにジャンプするハイパーリンク(<a>タグ)を生成する。
f:br() 指定された文字列内の改行コードを<br />タグに変換する。

ユーティリティ

項番
関数名
概要
f:cut() 指定された文字列から、指定された文字数を抜き出す。

4.12.2. How to use

共通ライブラリから提供している JSP Tag Library と EL関数の使用方法を以下に示す。 なお、他の章で使用方法の説明があるものについては、該当箇所へのハイパーリンクを貼っている。


4.12.2.1. <t:pagination>

<t:pagination>タグは、 ページ検索の結果(org.springframework.data.domain.Page)に格納されている情報を参照して、 ページネーションリンクを出力するJSP Tag Libraryである。

ページネーション機能の説明及び本タグの使用方法は、「ページネーション」の以下の節を参照されたい。


4.12.2.2. <t:messagesPanel>

<t:messagesPanel>タグは、 処理結果メッセージ(org.terasoluna.gfw.common.message.ResultMessageや例外が保持するメッセージなど)を出力するJSP Tag Libraryである。

本タグの使用方法は、「メッセージ管理」の以下の節を参照されたい。


4.12.2.3. <t:transaction>

<t:transaction>タグは、トランザクショントークンをhidden項目(<input type="hidden">")として出力するJSP Tag Libraryである。

トランザクショントークンチェック機能の説明及び本タグの使用方法は、「二重送信防止」の以下の節を参照されたい。

Note

本タグは、HTML標準の<form>タグを使用する際にトランザクショントークンをサーバに送信するために使用する。

Spring Framework提供の<form:form>タグ(JSP Tag Library)を使用する際は、 共通ライブラリから提供しているorg.terasoluna.gfw.web.token.transaction.TransactionTokenRequestDataValueProcessorが自動でトランザクショントークンを埋め込む仕組みになっているため、 本タグを使用する必要はない。


4.12.2.4. f:h()

f:h()は、引数に指定されたオブジェクトを文字列に変換し、変換した文字列内のHTML特殊文字をエスケープするEL Functionである。

HTML特殊文字とエスケープ仕様については、「Output Escaping」を参照されたい。

4.12.2.4.1. f:h() 関数仕様

引数

項番 型 説明
java.lang.Object HTML特殊文字が含まれる可能性があるオブジェクト

Note

指定されたオブジェクトは、

  • 配列の場合は、java.util.Arrays#toStringメソッド
  • 配列以外の場合は、指定されたオブジェクトの toStringメソッド

を使用して文字列に変換される。

戻り値

項番 型 説明
java.lang.String

HTMLエスケープ後の文字列

引数で指定されたオブジェクトがnullの場合は、空文字("")を返却する。

4.12.2.4.2. f:h() 使用方法

f:h()の使用方法については、「出力値をf:h()関数でエスケープする例」を参照されたい。


4.12.2.5. f:js()

f:js()は、引数に指定された文字列内のJavaScript特殊文字をエスケープするEL Functionである。

JavaScript特殊文字とエスケープ仕様については、「JavaScript Escaping」を参照されたい。

4.12.2.5.1. f:js() 関数仕様

引数

項番 型 説明
java.lang.String JavaScript特殊文字が含まれる可能性がある文字列

戻り値

項番 型 説明
java.lang.String

JavaScriptエスケープ後の文字列

引数で指定された文字列がnullの場合は、空文字("")を返却する。

4.12.2.5.2. f:js() 使用方法

f:js()の使用方法については、「出力値をf:js()関数でエスケープする例」を参照されたい。


4.12.2.6. f:hjs()

f:hjs()は、引数に指定された文字列内のJavaScript特殊文字をエスケープした後に、 HTML特殊文字をエスケープするEL Function(f:h(f:js())のショートカット関数)である。

  • 本関数の用途については、「Event handler Escaping」を参照されたい。
  • JavaScript特殊文字とエスケープ仕様については、「JavaScript Escaping」を参照されたい。
  • HTML特殊文字とエスケープ仕様については、「Output Escaping」を参照されたい。

4.12.2.6.1. f:hjs() 関数仕様

引数

項番 型 説明
java.lang.String JavaScript特殊文字又はHTML特殊文字が含まれる可能性がある文字列

戻り値

項番 型 説明
java.lang.String

JavaScript及びHTMLエスケープ後の文字列

引数で指定された文字列がnullの場合は、空文字("")を返却する。

4.12.2.6.2. f:hjs() 使用方法

f:hjs()の使用方法については、「出力値をf:hjs()関数でエスケープする例」を参照されたい。


4.12.2.7. f:query()

f:query()は、引数に指定されたJavaBean(フォームオブジェクト)又はjava.util.Mapオブジェクトから、 クエリ文字列を生成するEL Functionである。 クエリ文字列内のパラメータ名とパラメータ値は、UTF-8でURLエンコーディングされる。

URLエンコーディング仕様を以下に示す。

本関数では、クエリ文字列のパラメータ名とパラメータ値に対して、RFC 3986ベースのURLエンコーディングを行う。 RFC 3986では、クエリ文字列のパート以下のように定義している。

../../_images/TagLibAndELFunctionsRFC3986UriSyntax.png
  • query = *( pchar / “/” / “?” )
  • pchar = unreserved / pct-encoded / sub-delims / “:” / “@”
  • unreserved = ALPHA / DIGIT / “-” / “.” / “_” / “~”
  • sub-delims = “!” / “$” / “&” / “'” / “(” / “)” / “*” / “+” / “,” / “;” / “=”
  • pct-encoded = “%” HEXDIG HEXDIG

本関数では、クエリ文字列として使用できる文字のうち、

  • “=” (パラメータ名とパラメータ値のセパレータ文字)
  • “&” (複数のパラメータを扱う場合のセパレータ文字)
  • “+” (HTMLのformからサブミットした時に半角スペースを表す文字)

をpct-encoded形式の文字列にエンコーディングする。

Warning

Spring Framework 4までは、クエリ文字列として使用できる文字のうち(“=”, “&”, “+”)の3文字をSpring Frameworkがエンコーディングしていたが、 Spring Framework 5から、クエリ文字列のエンコードを行うorg.springframework.web.util.UriComponentsBuilderや org.springframework.web.util.UriUtils.encodeQueryParamメソッドの仕様が変更され、”+”はエンコーディング対象外となった。

共通ライブラリのf:query(), f:u()では、内部で上記の仕様変更されたクラスを利用しているが、 独自に”+”をエンコーディングすることで仕様変更の影響を受けないようにしている。

ガイドラインでは紹介していないが、上記の仕様変更されたクラスを直接利用してqueryを含むURIを生成しているアプリケーションでは、 “+” がエンコーディング対象外となったことによる影響を受ける可能性がある為、注意すること。 なお、UriComponentsBuilderでは、クエリパラメータに含まれるunreserved文字以外をエンコーディングする機能を提供している為、 当機能を用いる事でクエリパラメータに含まれる “+” のエンコーディングは可能である。 UriComponentsBuilderを利用してURIをエンコーディングする方法については、Spring Framework Documentation -URI Encoding-を参照されたい。

4.12.2.7.1. f:query() 関数仕様

引数

項番 型 説明
java.lang.Object

クエリ文字列の生成元となるオブジェクト(JavaBean又はMap)

JavaBeanを指定した場合はプロパティ名がリクエストパラメータ名となり、Mapを指定した場合はキー名がリクエストパラメータとなる。

JavaBeanのプロパティ及びMapの値としてサポートしている型は以下の通りである。

  • Iterableインタフェースの実装クラス
  • 配列
  • Mapインタフェースの実装クラス
  • JavaBean
  • シンプル型 (DefaultFormattingConversionServiceを使ってString型へ変換可能なクラス)

terasoluna-gfw-web 5.0.1.RELEASEより、ネスト構造をもつJavaBean及びMapを指定できるように改善されている。

Note

指定されたオブジェクトのシンプル型のプロパティ値は、 org.springframework.format.support.DefaultFormattingConversionServiceの convertメソッドを使用して文字列に変換される。 ConversionServiceについては、 Spring Framework Documentation -Spring Type Conversion-を参照されたい。

戻り値

項番 型 説明
java.lang.String

引数で指定されたオブジェクトを元に生成したクエリ文字列(UTF-8でURLエンコーディング済みの文字列)

引数で指定されたオブジェクトが、JavaBean又はMap以外の場合は、空文字("")を返却する。

Note

クエリ文字列への変換ルール

f:query()は、Spring Web MVCのバインディング処理(WebDataBinder)で扱うことができる形式に変換している。 具体的には以下のルールでクエリ文字列に変換している。

[リクエストパラメータ名]

条件 パラメータ名の変換仕様 変換例
プロパティの型がIterableの実装クラス又は配列の場合 プロパティ名 + [要素位置] status[0]=accepting
プロパティの型がIterableの実装クラス又は配列で値の要素が空の場合、および型がBooleanで値がnullの場合
プロパティ名
([要素位置]は付与しない)
 status=
プロパティの型がMapの実装クラスの場合 プロパティ名 + [Mapのキー名] status[accepting]=Accepting Order
プロパティの型(Iterable、配列、Mapの要素型)がJavaBeanの場合 プロパティ名を”.” (ドット)でつなげた値
mainContract.name=xxx
subContracts[0].name=xxx
プロパティの型がシンプル型の場合 プロパティ名 userId=xxx
プロパティの値がnullの場合(プロパティの型がBooleanの場合を除く) “_” (アンダースコア) + プロパティ名
_mainContract.name=
_status[0]=
_status[accepting]=

[リクエストパラメータ値]

条件 パラメータ値の変換仕様 変換例
プロパティの値がnullの場合(プロパティの型がBooleanの場合を除く) ブランク文字列 _userId=
プロパティの型がIterableの実装クラス又は配列で値の要素が空の場合、および型がBooleanで値がnullの場合 ブランク文字列 status=
プロパティの値がnullでない場合 DefaultFormattingConversionServiceを使ってString型へ変換した値 targetDate=20150801

Spring Web MVCのバインディング処理(WebDataBinder)のデフォルト設定では「”_” (アンダースコア) + プロパティ名」のリクエストパラメータが送信された場合、 List、配列、Mapに対してはそれぞれに対応する空のオブジェクトをバインドし、boolean及びBoolean型のプロパティに対してはBoolean型のfalseをバインドする。 詳細はWebDataBinder#getEmptyValueのJavadocを参照されたい。

terasoluna-gfw-web 5.6.0.RELEASEからは、Boolean型プロパティでnullがfalseに変換されてしまうことを防ぐため「”_” (アンダースコア) + プロパティ名」のリクエストパラメータを送信しないよう改善されている。

4.12.2.7.2. f:query() 使用方法

f:query()の使用方法については、「ページリンクで検索条件を引き継ぐ」を参照されたい。 ここでは、ページネーションリンクを使用してページを切り替える際に、検索条件を引き継ぐ際の手段として、本関数を使用している。 また、関数の仕様と注意点についても記載しているので、これについても一読されたい。


4.12.2.8. f:u()

f:u()は、引数に指定された文字列をUTF-8でURLエンコーディングするEL Functionである。

本関数は、クエリ文字列内のパラメータ値に設定する値をURLエンコーディングするために用意している。 URLエンコーディング仕様は、「f:query()」を参照されたい。

4.12.2.8.1. f:u() 関数仕様

引数

項番 型 説明
java.lang.String URLエンコードが必要な文字が含まれる可能性がある文字列

戻り値

項番 型 説明
java.lang.String

URLエンコード後の文字列

引数で指定された文字列がnullの場合は、空文字("")を返却する。

4.12.2.8.2. f:u() 使用方法

<div id="url">
    <a href="https://search.yahoo.com/search?p=${f:u(bean.searchString)}">  <!-- (1) -->
        Go to Yahoo Search
    </a>
</div>
項番 説明
(1)
 上記例では、本関数を使用してURLエンコードした値を検索サイトのリクエストパラメータに設定している。

4.12.2.10. f:br()

f:br()は、引数に指定された文字列内の改行コード（CRLF, LF, CR）を<br />タグに変換するEL Functionである。

Tip

改行コードを含む文字列をブラウザ上の表示として改行する場合は、改行コードを<br />タグに変換する必要がある。

例えば、入力画面のテキストエリア(<textarea>)で入力された文字列を、 確認画面や完了画面などで入力された状態のまま表示する際に、本関数を使用するとよい。

4.12.2.10.1. f:br() 関数仕様

引数

項番 型 説明
java.lang.String 改行コードが含まれる可能性がある文字列

戻り値

項番 型 説明
java.lang.String

変換後の文字列

引数で指定された文字列がnullの場合は、空文字("")を返却する。

4.12.2.10.2. f:br() 使用方法

<div id="text">
    ${f:br(f:h(bean.text))}">  <!-- (1) -->
</div>
項番 説明
(1)
 引数で指定された文字列内の改行コードを<br />タグに変換することで、ブラウザ上の表示を改行する。

Note

文字列を画面上に表示する際は、「XSS対策」としてHTML特殊文字をエスケープする必要がある。

f:br()関数を使用して改行コードを<br />タグに変換する場合は、 上記例のように、HTML特殊文字をエスケープした文字列をf:br()の引数として渡す必要がある。

f:br()を使用して改行コードを<br />タグに変換した文字列を、 f:h()関数の引数に渡すと、<br />という文字がブラウザ上に表示されてしまうため、 関数を呼び出す順番に注意すること。


4.12.2.11. f:cut()

f:cut()は、引数に指定された文字列の先頭から、引数で指定された文字数までの文字列を切り出すEL Functionである。

4.12.2.11.1. f:cut() 関数仕様

引数

項番 型 説明
java.lang.String 切り出し元となる文字列
int 切り出す文字数

戻り値

項番 型 説明
java.lang.String

切り出した文字列(指定された文字数を超えている部分が破棄された文字列)

引数で指定された文字列がnullの場合は、空文字("")を返却する。

4.12.2.11.2. f:cut() 使用方法

<div id="cut">
    ${f:h(f:cut(bean.originText, 5))}  <!-- (1) -->
</div>
項番 説明
(1)
上記例では、引数に指定した文字列の先頭5文字を切り出して、画面上に表示している。

Note

切り出した文字列を画面上に表示する際は、「XSS対策」としてHTML特殊文字をエスケープする必要がある。 上記例では、f:h()関数を使用してエスケープしている。