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である。

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

ページネーションリンクについては、「ページネーションリンクの表示について」
本タグのパラメータ値については、「JSPタブライブラリのパラメータについて」
本タグを使用したJSPの基本的な実装方法については、「ページネーションリンクの表示」
ページネーションリンクのレイアウトの変更方法については、「レイアウト変更(JSP)」

4.12.2.2. <t:messagesPanel>¶

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

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

本タグを使用したメッセージの表示方法については、「結果メッセージの表示」
本タグのパラメータ値については、「<t:messagesPanel>タグの属性変更」

4.12.2.3. <t:transaction>¶

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

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

トランザクショントークンチェック機能については、「トランザクショントークンチェックの適用」
本タグの使用方法については、「トランザクショントークンチェックのView(JSP/テンプレートHTML)での利用方法」

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()の使用方法については、「出力値をエスケープする例」を参照されたい。

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()の使用方法については、「出力値をエスケープする例」を参照されたい。

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型へ変換可能なクラス)

ネスト構造をもつ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では、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.9. f:link()¶

f:link()は、引数に指定されたURLにジャンプするためのハイパーリンク(<a>タグ)を出力するEL Functionである。

Warning

本関数では、URLエンコーディングや特殊文字のエスケープ処理は行われない点に注意すること。

4.12.2.9.1. f:link() 関数仕様 ¶

引数

項番

型

説明

java.lang.String

リンク先のURL文字列

URL文字列は、HTTP又はHTTPSスキーマのURL形式である必要がある。（e.g : http://hostname:80/terasoluna/global.ex?id=123）

戻り値

項番

型

説明

java.lang.String

引数に指定された文字列を元に生成したハイパーリンク(<a>タグ)

引数に指定された文字列が、

引数で指定された文字列がnullの場合は、空文字("")

HTTP又はHTTPSスキーマのURL形式でない場合は、ハイパーリンクを生成せず入力値の文字列

を返却する。

4.12.2.9.2. f:link() 使用方法 ¶

実装例

<div id="link">
    ${f:link(bean.httpUrl)}  <!-- (1) -->
</div>

出力例

<div id="link">
    <a href="http://terasoluna.org/">http://terasoluna.org/</a>  <!-- (2) -->
</div>

項番	説明
(1)	引数に指定されたURL文字列からハイパーリンクを生成する。
(2)	引数で指定したURL文字列が、`<a>`タグの `href`属性と、ハイパーリンクのリンク名に設定される。

Warning

URLにリクエストパラメータを付加する場合は、リクエストパラメータの値はURLエンコーディングする必要がある。リクエストパラメータを付加する場合は、f:query()関数やf:u()関数を使用して、リクエストパラメータの値を適切にURLエンコーディングすること。

また、戻り値の説明でも記載しているが、引数のURL文字列の形式が適切でない場合は、ハイパーリンクを生成せず入力値の文字列を返却する仕様としている。そのため、引数に指定するURL文字列としてユーザからの入力値を使用する場合は、文字列出力処理と同様のHTML特殊文字のエスケープ処理(XSS対策)が必要になるケースがある。

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()関数を使用してエスケープしている。

Table of Contents

Previous topic

Next topic

This Page

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

4.12.1. Overview ¶

4.12.1.1. JSP Tag Library ¶

4.12.1.2. EL Functions ¶

4.12.2. How to use ¶

4.12.2.2. <t:messagesPanel>¶

4.12.2.3. <t:transaction>¶

4.12.2.4. f:h()¶

4.12.2.4.1. f:h() 関数仕様 ¶

4.12.2.4.2. f:h() 使用方法 ¶

4.12.2.5. f:js()¶

4.12.2.5.1. f:js() 関数仕様 ¶

4.12.2.5.2. f:js() 使用方法 ¶

4.12.2.6. f:hjs()¶

4.12.2.6.1. f:hjs() 関数仕様 ¶

4.12.2.6.2. f:hjs() 使用方法 ¶

4.12.2.7. f:query()¶

4.12.2.7.1. f:query() 関数仕様 ¶

4.12.2.7.2. f:query() 使用方法 ¶

4.12.2.8. f:u()¶

4.12.2.8.1. f:u() 関数仕様 ¶

4.12.2.8.2. f:u() 使用方法 ¶

4.12.2.9. f:link()¶

4.12.2.9.1. f:link() 関数仕様 ¶

4.12.2.9.2. f:link() 使用方法 ¶

4.12.2.10. f:br()¶

4.12.2.10.1. f:br() 関数仕様 ¶

4.12.2.10.2. f:br() 使用方法 ¶

4.12.2.11. f:cut()¶

4.12.2.11.1. f:cut() 関数仕様 ¶

4.12.2.11.2. f:cut() 使用方法 ¶

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

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

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

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

条件	パラメータ名の変換仕様	変換例
プロパティの型が`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`

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