``\ タグのclassに"error error-[メッセージタイプ]"が付与される。
* - | (2)
- | 結果メッセージのリストが\ ``
``\ タグで出力される。
* - | (3)
- | メッセージIDに対応するメッセージが\ ``MessageSource``\ から解決される。
````\ はclassを付けたHTMLを出力するだけであるため、見栄えは出力されたclassに合わせてCSSでカスタマイズする必要がある(後述する)。
.. note::
\ ``ResultMessages.error().add(ResultMessage.fromText("There are inconsistencies in the data."));``\ というように、
メッセージの本文をハードコードすることもできるが、保守性を高めるため、メッセージキーを使用して\ ``ResultMessage``\ オブジェクトを作成し、
メッセージ本文はプロパティファイルから取得することを推奨する。
|
メッセージのプレースホルダに値を埋める場合は、次のように\ ``add``\ メソッドの第二引数以降に設定すればよい。
.. code-block:: java
ResultMessages messages = ResultMessages.error().add("e.ex.an.8001", 1024);
model.addAttribute(messages);
この場合、\ ````\ タグにより、以下のようなHTMLが出力される。
.. code-block:: html
- Cannot upload, Because the file size must be less than 1,024MB.
\
.. warning:: **terasoluna-gfw-web 1.0.0.RELEASEを使用してプレースホルダに値を埋める場合の注意点**
terasoluna-gfw-web 1.0.0.RELEASEを使用している場合、\ **プレースホルダにユーザの入力値を埋め込むとXSS脆弱性の危険がある。**\
ユーザの入力値にXSS対策が必要な文字が含まれる可能性がある場合は、プレースホルダに値を埋め込まないようにすること。
terasoluna-gfw-web 1.0.1.RELEASE以上を使用している場合は、ユーザの入力値をプレースホルダに埋め込んでもXSS脆弱性は発生しない。
.. note::
\ ``ResourceBundleMessageSource``\ はメッセージを生成する際に\ ``java.text.MessageFormat``\ を使用するため、\ ``1024``\ は
カンマ区切りで\ ``1,024``\ と表示される。カンマが不要な場合は、プロパティファイルには以下のように設定する。
.. code-block:: properties
e.ex.an.8001=Cannot upload, Because the file size must be less than {0,number,#}MB.
詳細は、\ `Javadoc `_\ を参照されたい。
|
以下のように、複数の結果メッセージを設定することもできる。
.. code-block:: java
ResultMessages messages = ResultMessages.error()
.add("e.ex.an.9001")
.add("e.ex.an.8001", 1024);
model.addAttribute(messages);
この場合は、次のようなHTMLが出力される(JSPの変更は、不要である)。
.. code-block:: html
- There are inconsistencies in the data.
- Cannot upload, Because the file size must be less than 1,024MB.
infoメッセージを表示したい場合は、次のように\ ``ResultMessages.info()``\ メソッドで\ ``ResultMessages``\ オブジェクトを作成すればよい。
.. code-block:: java
ResultMessages messages = ResultMessages.info().add("i.ex.an.0001", "XXXX");
model.addAttribute(messages);
以下のようなHTMLが、出力される。
.. code-block:: html
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | メッセージタイプに対応して、出力されるclass名が"alert alert-**info**"に変わっている。
標準では、以下のメッセージタイプが用意されている。
標準のメッセージタイプはCSSフレームワークである\ `Bootstrap `_ の\ `Alertsコンポーネント `_\ に対応しており、\ ````\ のデフォルト設定で利用できる。
.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|p{0.30\linewidth}|
.. list-table::
:header-rows: 1
:widths: 15 30 25 30
* - メッセージタイプ
- \ ``ResultMessages``\ オブジェクトの作成
- デフォルトで出力されるclass名
- 備考
* - | success
- | ``ResultMessages.success()``\
- | alert alert-success
- | \-
* - | info
- | \ ``ResultMessages.info()``\
- | alert alert-info
- | \-
* - | warning
- | \ ``ResultMessages.warning()``\
- | alert alert-warning
- | Bootstrap v3の「alert-warning」に対応するため、5.0.0から追加。
* - | error
- | \ ``ResultMessages.error()``\
- | alert alert-error
- | \-
* - | danger
- | \ ``ResultMessages.danger()``\
- | alert alert-danger
- | \-
* - | primary
- | \ ``ResultMessages.primary()``\
- | alert alert-primary
- | Bootstrap v4の「alert-primary」に対応するため、5.7.0から追加。
* - | secondary
- | \ ``ResultMessages.secondary()``\
- | alert alert-secondary
- | Bootstrap v4の「alert-secondary」に対応するため、5.7.0から追加。
* - | light
- | \ ``ResultMessages.light()``\
- | alert alert-light
- | Bootstrap v4の「alert-light」に対応するため、5.7.0から追加。
* - | dark
- | \ ``ResultMessages.dark()``\
- | alert alert-dark
- | Bootstrap v4の「alert-dark」に対応するため、5.7.0から追加。
メッセージタイプに応じてCSSを定義されたい。以下に、CSSを適用した場合の例を示す。
.. code-block:: css
.alert {
margin-bottom: 15px;
padding: 10px;
border: 1px solid;
border-radius: 4px;
text-shadow: 0 1px 0 #ffffff;
}
.alert-info {
background: #ebf7fd;
color: #2d7091;
border-color: rgba(45, 112, 145, 0.3);
}
.alert-warning {
background: #fffceb;
color: #e28327;
border-color: rgba(226, 131, 39, 0.3);
}
.alert-error {
background: #fff1f0;
color: #d85030;
border-color: rgba(216, 80, 48, 0.3);
}
* \ ``ResultMessages.error().add("e.ex.an.9001")``\ を\ ````\ で出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-error.jpg
:width: 100%
* \ ``ResultMessages.warning().add("w.ex.an.2001")``\ を\ ````\ で出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-warn.jpg
:width: 100%
* \ ``ResultMessages.info().add("i.ex.an.0001", "XXXX")``\ を\ ````\ で出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-info.jpg
:width: 100%
.. warning::
本例では、メッセージキーをハードコードで設定している。しかしながら、保守性を高めるためにも、メッセージキーは、定数クラスにまとめることを推奨する。
:ref:`message-management-messagekeysgen`\ を参照されたい。
結果メッセージの属性名指定
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
| \ ``ResultMessages``\ をModelに追加する場合、基本的には属性名を省略できる。
| ただし、\ ``ResultMessages``\ は一つのメッセージタイプしか表現できない。
| 1画面に異なるメッセージタイプの\ ``ResultMessages``\ を\ **同時に**\ 表示したい場合は、明示的に属性名を指定してModelに設定する必要がある。
* Controller (MessageControllerに追加)
.. code-block:: java
@RequestMapping(value = "showMessages", method = RequestMethod.GET)
public String showMessages(Model model) {
model.addAttribute("messages1",
ResultMessages.warning().add("w.ex.an.2001")); // (1)
model.addAttribute("messages2",
ResultMessages.error().add("e.ex.an.9001")); // (2)
return "message/showMessages";
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | メッセージタイプが"warning"である、\ ``ResultMessages``\ を属性名"messages1"でModelに追加する。
* - | (2)
- | メッセージタイプが"info"である、\ ``ResultMessages``\ を属性名"messages2"でModelに追加する。
* JSP (WEB-INF/views/message/showMessages.jsp)
.. code-block:: jsp
Result Message Example
Result Message
Messages1
Messages2
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | 属性名が"messages1"である\ ``ResultMessages``\ を表示する。
* - | (2)
- | 属性名が"messages2"である\ ``ResultMessages``\ を表示する。
ブラウザで表示すると、以下のように出力される。
.. figure:: ./images_MessageManagement/message-management-multiple-messages.jpg
:width: 80%
業務例外メッセージの表示
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
| \ ``org.terasoluna.gfw.common.exception.BusinessException``\ と\ ``org.terasoluna.gfw.common.exception.ResourceNotFoundException``\ は
| 内部で\ ``ResultMessages``\ を保持している。
| 業務例外メッセージを表示する場合は、Serviceクラスで\ ``ResultMessages``\ を設定した\ ``BusinessException``\ をスローすること。
| Controllerクラスでは\ ``BusinessException``\ をキャッチし、例外中の結果メッセージをModelに追加する。
* Serviceクラス
.. code-block:: java
@Service
@Transactional
public class UserServiceImpl implements UserService {
// omitted
public void create(...) {
// omitted...
if (...) {
// illegal state!
ResultMessages messages = ResultMessages.error()
.add("e.ex.an.9001"); // (1)
throw new BusinessException(messages);
}
}
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | エラーメッセージを\ ``ResultMessages``\ で作成し、\ ``BusinessException``\ に設定する。
* Controllerクラス
.. code-block:: java
@RequestMapping(value = "create", method = RequestMethod.POST)
public String create(@Validated UserForm form, BindingResult result, Model model) {
// omitted
try {
userService.create(user);
} catch (BusinessException e) {
ResultMessages messages = e.getResultMessages(); // (1)
model.addAttribute(messages);
return "user/createForm";
}
// omitted
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``BusinessException``\ が保持する\ ``ResultMessages``\ を取得し、Modelに追加する。
通常、エラーメッセージ表示する場合は、Controllerで\ ``ResultMessages``\ オブジェクトを作成するのではなく、
こちらの方法を使用する。
|
How to extend
--------------------------------------------------------------------------------
独自メッセージタイプを作成する
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| メッセージタイプを追加したい場合の、独自メッセージタイプ作成方法について説明する。
| 通常は、用意されているメッセージタイプのみで十分であるが、採用しているCSSライブラリによっては
| メッセージタイプを追加したい場合がある。例えば"notice"というメッセージタイプを追加する場合を説明する。
| まず、以下のように\ ``org.terasoluna.gfw.common.message.ResultMessageType``\ インタフェースを実装した
| 独自メッセージタイプクラスを作成する。
.. code-block:: java
import org.terasoluna.gfw.common.message.ResultMessageType;
public enum ResultMessageTypes implements ResultMessageType { // (1)
NOTICE("notice");
private ResultMessageTypes(String type) {
this.type = type;
}
private final String type;
@Override
public String getType() { // (2)
return this.type;
}
@Override
public String toString() {
return this.type;
}
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``ResultMessageType``\ インタフェースを実装したEnumを定義する。定数オブジェクトで作成してもよいが、Enumで作成することを推奨する。
* - | (2)
- | \ ``getType``\ の返り値が出力されるCSSのclass名に対応する。
| このメッセージタイプを使用して以下のように\ ``ResultMessages``\ を作成する。
.. code-block:: java
ResultMessages messages = new ResultMessages(ResultMessageTypes.NOTICE) // (1)
.add("w.ex.an.2001");
model.addAttribute(messages);
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``ResultMessages``\ のコンストラクタに対象の\ ``ResultMessageType``\ を指定する。
この場合、\ ```` \ で以下のようなHTMLが出力される。
.. code-block:: html
- The recommended change interval has passed password. Please change your password.
\
.. tip::
拡張方法は、\ ``org.terasoluna.gfw.common.message.StandardResultMessageType``\ が参考になる。
|
Appendix
--------------------------------------------------------------------------------
.. _message-management-messagepanel-attribute:
タグの属性変更
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
\ ````\ タグには、表示形式を変更する属性がいくつか用意されている。
.. tabularcolumns:: |p{0.25\linewidth}|p{0.55\linewidth}|p{0.20\linewidth}|
.. list-table:: \ ````\ タグ 属性一覧
:header-rows: 1
:widths: 25 55 20
* - オプション
- 内容
- defaultの設定値
* - panelElement
- 結果メッセージ表示パネルの要素
- div
* - panelClassName
- 結果メッセージ表示パネルのCSS class名。
- alert
* - panelTypeClassPrefix
- CSS class名の接頭辞
- alert-
* - messagesType
- メッセージタイプ。この属性が設定された場合。設定されたメッセージタイプが\ ``ResultMessages``\ がもつメッセージタイプより優先されて使用される。
-
* - outerElement
- 結果メッセージ一覧を構成するHTMLの外側のタグ
- ul
* - innerElement
- 結果メッセージ一覧を構成するHTMLの内側のタグ
- li
* - disableHtmlEscape
- | HTMLエスケープ処理を無効化するためのフラグ。
| \ ``true``\ を指定する事で、出力するメッセージに対してHTMLエスケープ処理が行われなくなる。
| この属性は、出力するメッセージにHTMLを埋め込むことで、メッセージの装飾などができるようにするために用意している。
| **trueを指定する場合は、XSS対策が必要な文字がメッセージ内に含まれない事が保証されていること。**
|
| terasoluna-gfw-web 1.0.1.RELEASE以上で利用可能な属性である。
- ``false``
例えば、CSSフレームワーク"BlueTrip"では以下のようなCSSが用意されている。
.. code-block:: css
.error,.notice,.success {
padding: .8em;
margin-bottom: 1.6em;
border: 2px solid #ddd;
}
.error {
background: #FBE3E4;
color: #8a1f11;
border-color: #FBC2C4;
}
.notice {
background: #FFF6BF;
color: #514721;
border-color: #FFD324;
}
.success {
background: #E6EFC2;
color: #264409;
border-color: #C6D880;
}
| このCSSを使用したい場合、\ ``...
``\ というようにメッセージが出力されてほしい。
| この場合、\ ````\ タグを以下のように使用すればよい(Controllerは修正不要である)。
.. code-block:: jsp
出力されるHTMLは以下のようになる。
.. code-block:: html
- There are inconsistencies in the data.
ブラウザで表示すると、以下のように出力される。
.. figure:: ./images_MessageManagement/message-management-bluetrip-error.jpg
:width: 80%
メッセージ一覧を表示するために\ ``