3.1. 前処理を実装する¶
前処理を実装するには、デザイナで作成する画面で必要となる情報はなにか?を決めなければいけません。 必要な情報は、デザイナの変数タブ「入力」 ( $input ) で定義します。 $input にはキー名、型、そして構造をプロパティとして定義します。
前処理では、このプロパティにセットする値を生成する処理を実装していきます。 一つの前処理だけでは処理が複雑になる場合、複数の前処理プログラムに分割して実装します。
前処理に外部から値を渡したい場合、送信元からクエリパラメータやリクエストボディとして送信してください。クエリパラメータの例を リクエストパラメータの解析 で説明します。
3.1.1. 前処理の実装方式¶
前処理には以下の3つの実装方式があります。
- Java の前処理クラスを実装する
- JavaScript(スクリプト開発モデル)の前処理スクリプトを実装する
- IM-LogicDesigner のフローを定義する
前処理はルーティングに紐付けられます。
前処理はコンテンツに依存しないので、複数のコンテンツに共通の前処理を指定できます。 一方で、コンテンツを編集する機能であるデザイナやプレビュー画面で前処理を実行することはできません。
コラム
JavaScript(スクリプト開発モデル)による前処理プログラムの実装は、2019 Winter(Xanadu)から可能です。
3.1.2. 前処理の実行順序と引数¶
ルーティングに指定した URL にアクセスすると、前処理が指定された順に実行されます。 前処理が実行されると、引数としていくつかの値が渡されます。
- パス
- リクエストのパス
- パス変数
- コンテンツ情報
- コンテンツの情報
- 解析済みリクエストパラメータ情報
- リクエストパラメータの解析 で説明します。
- リクエストオブジェクト
- 生のリクエストオブジェクト(Java の前処理クラス、JavaScript の前処理スクリプトで取得できます。IM-LogicDesigner のフロー定義では取得できません)
3.1.3. リクエストパラメータの解析¶
ルーティングに指定した URL に対してパラメータを送信すると、前処理で受信できます。 単純な key-value 形式だけでなく、構造を持ったパラメータも送信できます。
キーを . (ピリオド)でつなげると、Map として解析されます。 [] をつけると、配列として解析されます。
http://<host>:<port>/<contextPath>/<ルーティングに定義したURL>?parameter1=value1
¶meter2.property1=prop_value1¶meter2.property2=prop_value2&array1[0]=foo&array1[1]=bar
(幅の都合上改行していますが、本来は1行です。)
のようなリクエストは、
{
"parameter1": "value1",
"parameter2": {
"property1": "prop_value1",
"property2": "prop_value2"
},
"array1": [
"foo",
"bar"
]
}
のような形に変換され、解析済みリクエストパラメータとして取得できます。
Java の前処理プログラムの場合は
public Map<String, Object> execute(final BMContentPreprocessorContext context) throws BloomMakerException {
final String parameter1 = (String) context.getParsedRequestParameters().get("parameter1");
final Map<String, String> parameter2 = (Map<String, String>) context.getParsedRequestParameters().get("parameter2");
final String[] array1 = (String[]) context.getParsedRequestParameters().get("array1");
のように取得できます。
JavaScript の前処理プログラムの場合は
function execute(context) {
let parameter1 = context.parsedRequestParameters.parameter1;
let parameter2 = context.parsedRequestParameters.parameter2;
let array1 = context.parsedRequestParameters.array1;
のように取得できます。
IM-LogicDesigner のフロー定義の場合は
のように定義すると、後続の処理で入力から値を取得できます。 入力のルートにある request は、フロー定義でパラメータを受けとる で説明する解析済みリクエストパラメータ情報を表します。
3.1.4. フロー定義でパラメータを受けとる¶
フロー定義で様々な入力を取得するには、入出力定義の入力に次のようなキーを持つ object や string を定義します。
パス
- キー名:path
- 型:string
パス変数
- キー名:variables
- 型:object
コンテンツ情報
- キー名:content
- 型:object
解析済みリクエストパラメータ情報
- キー名:request
- 型:object
型が object のものは、 リクエストパラメータの解析 のフロー定義のように必要なプロパティを定義します。
コラム
フロー定義の出力を定義する際、デザイナの変数タブの「入力」( $input ) で JSON エディタの値をコピーし、フロー定義の JSON 入力に貼り付けるとキー名と構造を正確に定義できます。
キー名の誤字は見つけづらい場合がありますので、ぜひ JSON エディタ、JSON 入力をご利用ください。
3.1.5. 複数の前処理¶
複数の前処理が指定された場合、同じキーに対して値をセットすることがあります。 その場合、ルーティングに指定された順に前処理が実行され、同じキーに対して値を上書きしていきます。 後に実行された前処理の結果が最終的な結果として扱われます。
3.1.6. 前処理の返却値¶
前処理の結果は、Java では Map<String, Object> の形で、JavaScript では Object の形で、IM-LogicDesigner のフローでは object として返します。 上述の通り、すべての前処理の結果がまとめられ、コンテンツの実行画面に渡されます。 コンテンツの実行画面では、変数の入力 ( $input ) として取得できます。
3.1.7. エラー処理¶
前処理の実行中にエラーが発生した場合、処理を中断し、エラー画面へ遷移させることができます。
3.1.7.1. 前処理専用のエラー画面に遷移する¶
以下のような実装を行います。
- Java
- jp.co.intra_mart.foundation.bloommaker.exception.BloomMakerPreprocessException をスローする
- JavaScript
- Error をスローする
- IM-LogicDesigner
- エラー終了で終了する
それぞれのエラーにメッセージを指定すると、そのメッセージがエラー画面に表示されます。
コラム
前処理専用のエラー画面に遷移させるのは、2020 Spring(Yorkshire)から可能です。
注意
前処理専用のエラー画面に遷移できるようにするため、2020 Spring(Yorkshire)で仕様の変更を行いました。
以下の場合に該当する場合、指定したエラーメッセージが画面に表示されます。 エラーメッセージに内部情報などを指定していると、意図せぬ情報が漏洩する可能性がありますので注意してください。
- 2019 Winter(Xanadu)以前のバージョンで JavaScript または IM-LogicDesigner で前処理を実装した
- JavaScript で Error をスローする、IM-LogicDesigner のエラー終了で終了する際に、エラーメッセージを指定した
3.1.7.2. 標準のエラー画面に遷移する¶
Java に限り、以下のような実装を行うと intra-mart Accel Platform 標準のエラーページへ遷移します。この場合、エラーメッセージを画面に表示することはできません。
- Java
- jp.co.intra_mart.foundation.bloommaker.exception.BloomMakerException をスローする
注意
2019 Winter(Xanadu)以前のバージョンでは、JavaScript で Error をスローする、IM-LogicDesigner のエラー終了で終了するように実装した場合でも、標準のエラー画面に遷移します。