# 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では、クエリ文字列のパート以下のように定義している。

- 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>`タグ) 引数に指定された文字列に、URLとして許可していない文字列を指定した場合、以下のとおり動作する。 引数で指定された文字列が`null`の場合は、空文字(`""`)を返却 HTTP又はHTTPSスキームのURL形式でない場合は、ハイパーリンクを生成せず入力値の文字列を返却 RFC 3986で許可していない文字を使用している場合は、ハイパーリンクを生成せず入力値の文字列を返却

#### 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スキームおよびRFC 3986で許可していない文字を指定した場合は、ハイパーリンクを生成せず入力値の文字列を返却する仕様としている。そのため、引数に指定する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()`関数を使用してエスケープしている。