diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/about.adoc b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/about.adoc new file mode 100644 index 0000000..5ed4850 --- /dev/null +++ b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/about.adoc @@ -0,0 +1,13 @@ +[[mdc_entitylisting]] +== 汎用検索（EntityListing） + +MDC汎用検索（EntityListing）はエンティティに対して、エンドユーザーが自分自身で抽出項目やフィルター条件を指定してデータを検索・抽出する機能を提供しています。 +システム管理者が定期的なデータ抽出作業用の定型フィルター条件を作成することも可能です。 + +.検索条件の動的指定 +登録されているエンティティに対して、抽出項目（Select）やフィルター条件（Where）を画面上で自由に指定することができます。 +集計関数、結果の絞り込み（HAVING）、重複除外（DISTINCT）、ソート条件も画面上で指定可能です。 + +.検索結果のファイル出力 +検索結果をCSVファイルやExcelファイルに出力（ダウンロード）することが可能です。 +ダウンロード時にはファイルタイプ、文字コード、コード値出力のオプションを指定できます。 diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_custom_setting.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_custom_setting.png new file mode 100644 index 0000000..531bb7c Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_custom_setting.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_default_setting.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_default_setting.png new file mode 100644 index 0000000..1c36bae Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_default_setting.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_aggregate.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_aggregate.png new file mode 100644 index 0000000..1fefe86 Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_aggregate.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_download.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_download.png new file mode 100644 index 0000000..ef7be64 Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_download.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_reference.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_reference.png new file mode 100644 index 0000000..6466adc Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_reference.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_select.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_select.png new file mode 100644 index 0000000..73c913b Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_entity_select.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_filter.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_filter.png new file mode 100644 index 0000000..e83728b Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_filter.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_reference_expand.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_reference_expand.png new file mode 100644 index 0000000..22364ae Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_reference_expand.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_result.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_result.png new file mode 100644 index 0000000..1b7bb1a Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_result.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_dialog.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_dialog.png new file mode 100644 index 0000000..1f92d36 Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_dialog.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_inline.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_inline.png new file mode 100644 index 0000000..77bd570 Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_resultfilter_inline.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_selectitem.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_selectitem.png new file mode 100644 index 0000000..ee43819 Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_ope_selectitem.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_structure.png b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_structure.png new file mode 100644 index 0000000..449ce2b Binary files /dev/null and b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/images/mdc_entitylisting_structure.png differ diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/index.adoc b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/index.adoc new file mode 100644 index 0000000..abaa2f5 --- /dev/null +++ b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/index.adoc @@ -0,0 +1,10 @@ += 汎用検索（Entity Listing） +:_hreflang-path: developerguide/materialdesigncomponents/entitylisting/index.html +:_relative-root-path: ../../../ +:_menu-title-ee-only: true + +include::about.adoc[] + +include::operationguide.adoc[] + +include::setting.adoc[] diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/operationguide.adoc b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/operationguide.adoc new file mode 100644 index 0000000..5c8c2c6 --- /dev/null +++ b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/operationguide.adoc @@ -0,0 +1,351 @@ +[[mdc_entitylisting_operationguide]] +== 操作説明 + +=== 画面構成 + +MDC EntityListingの画面は、以下の3つの主要エリアで構成されています。 + +image::images/mdc_entitylisting_structure.png[] + +.A.タイトルエリア +EntityListingの画面タイトルが表示されます。EntityListingメタデータで `DisplayName` が設定されている場合はその名称が、未設定の場合はデフォルトの表示名（リスト）が表示されます。 + +.B.プロパティ選択エリア +画面左側に表示されるエリアです。エンティティの選択と、そのエンティティが持つプロパティの一覧が表示されます。プロパティをクリックまたはドラッグ&ドロップして、抽出項目やフィルター条件に追加します。 + +.C.検索条件・検索結果エリア +画面右側に表示されるエリアです。抽出項目、フィルター条件、結果の絞り込み、検索結果から重複行を除くの設定、検索実行、検索結果の表示を行います。 + + +=== 画面操作 + +[[mdc_entitylisting_ope_entityselect]] +==== データアイテム選択 +.エンティティ選択 +エンティティをドロップダウンから選択します。選択すると `アイテム` 部分にプロパティが表示されます。 + +image::images/mdc_entitylisting_ope_entity_select.png[] + +NOTE: 選択可能なエンティティやプロパティはEntityListingメタデータで指定することが可能です。EntityListingメタデータを利用しない場合は、エンティティ権限の設定により参照可能なエンティティやプロパティが表示されます。 + +.プロパティ選択 +`抽出項目` を設定したい場合は、アイテムをダブルクリックするか、 `抽出項目` 領域にドラッグ&ドロップすることで追加されます。 + +`フィルター条件` に追加したい場合は、フィルター条件下部の「アイテムをドロップしてください」という領域にドラッグ&ドロップすることで追加されます。 + +プロパティがReferenceプロパティの場合は、左に右向き「▼」が表示されます。 +このアイテムをクリックすることでReference対象エンティティのプロパティが表示されます。 + +image::images/mdc_entitylisting_ope_reference_expand.png[] + +[[mdc_entitylisting_ope_selectitem]] +==== 抽出項目設定 + +抽出項目エリアでは、検索結果として取得するプロパティを管理します。 + +image::images/mdc_entitylisting_ope_selectitem.png[] + +.列の並び替え +抽出項目の列の順番はドラッグ&ドロップで並びかえることが可能です。 + +.抽出項目の削除 +各抽出項目のチップ上にある「×」アイコンをクリックすることで、抽出項目から削除できます。 + +.集計関数設定 +抽出項目に対して、集計関数を指定することが可能です。 集計関数として利用できる関数は、ドロップされたアイテムのデータ型によって決まります。 + +image::images/mdc_entitylisting_ope_aggregate.png[] + +[cols="2,2,5a", options="header"] +|=== +|関数名|集計関数|説明 + +|通常|NONE|集計を行わず、プロパティの値をそのまま取得します（デフォルト）。 + +|カウント|COUNT|対象レコードの件数を取得します。 + +|重複を省いてカウント|COUNT_DISTINCT|重複を除いたレコードの件数を取得します。 + +|合計|SUM|数値プロパティの合計値を計算します。（数値型・集計項目のみ） + +|平均|AVG|数値プロパティの平均値を計算します。（数値型・集計項目のみ） + +|最大|MAX|プロパティの最大値を取得します。（日付型・数値型・集計項目のみ） + +|最小|MIN|プロパティの最小値を取得します。（日付型・数値型・集計項目のみ） + +|母標準偏差|STDDEV_POP|数値プロパティの母標準偏差を計算します。（数値型・集計項目のみ） + +|標本標準偏差|STDDEV_SAMP|数値プロパティの標本標準偏差を計算します。（数値型・集計項目のみ） + +|母分散|VAR_POP|数値プロパティの母分散を計算します。（数値型・集計項目のみ） + +|標本分散|VAR_SAMP|数値プロパティの標本分散を計算します。（数値型・集計項目のみ） + +|最頻値|MODE|プロパティの中で最も多く出現する値（最頻値）を取得します。（日付型・数値型・集計項目のみ） + +|中央値|MEDIAN|数値プロパティの中央値を計算します。（日付型・数値型・集計項目のみ） + +|文字列連結|LISTAGG|プロパティの値をカンマ区切りで連結した文字列を取得します。 + +|重複を省いて文字列連結|LISTAGG_DISTINCT|重複を除いたプロパティの値をカンマ区切りで連結した文字列を取得します。 +|=== + +.表示設定 +抽出項目チップをクリックすると、検索結果一覧の表示設定を変更するメニューが開きます。以下の設定が可能です。 + +* 配置設定 + +左寄せ、中央寄せ、右寄せを設定します。 +数値型のプロパティは、デフォルトで「右寄せ」が設定されます。 +その他の型はデフォルトで「左寄せ」になります。 + +* 列幅設定 + +検索結果の表示列幅を100px〜500pxの範囲で設定します。デフォルトは150pxです。 + +* 数値フォーマット設定（数値型・集計項目のみ） + +数値をフォーマット（カンマ区切り）表示するかを設定します。 +数値型のプロパティまたは数値結果を返す集計関数（カウント、合計、平均等）が設定されている場合に選択可能です。 +未指定の場合、<> の `formatNumberWithComma` が `true` の場合にのみフォーマット表示されます。 `formatNumberWithComma` が `true` の場合で、フォーマット表示したくない場合は、「フォーマットしない」を選択する必要があります。 + +NOTE: 多重度が1より大きいプロパティ、およびLongText型のプロパティは、抽出項目設定を行うことができません。 +[[mdc_entitylisting_ope_filter]] +==== フィルター条件 + +フィルター条件エリアでは、検索時の絞り込み条件を指定します。 + +image::images/mdc_entitylisting_ope_filter.png[] + +[[mdc_entitylisting_ope_filter_row]] +===== 条件行の構成 + +フィルター条件エリアに追加された各条件行では以下の項目を設定します。 + +[cols="1,5a", options="header"] +|=== +|項目|説明 + +|項番 +|条件行の番号です。条件式で参照する際に使用します。 + +|プロパティ名 +|フィルター対象のプロパティ名が表示されます。 + +|演算子 +|絞り込みに使用する演算子を選択します。 +利用可能な演算子はプロパティのデータ型によって決まります。詳細は下記の演算子一覧を参照してください。 + +|値 +|絞り込み値を入力します。 + +|削除ボタン +|「×」ボタンをクリックすることで、その条件行を削除します。 +|=== + +フィルター条件として指定可能な演算子は、プロパティのデータ型によって異なります。 + +[cols="1,4a", options="header"] +|=== +|演算子|説明 + +|等しい|指定した値と等しいデータを検索します。 + +|等しくない|指定した値と等しくないデータを検索します。 + +|前方一致|指定した値で始まるデータを検索します。 + +|後方一致|指定した値で終わるデータを検索します。 + +|含む|指定した値を含むデータを検索します。 + +|含まない|指定した値を含まないデータを検索します。 + +|いずれかと等しい|指定した複数の値のいずれかと等しいデータを検索します。 + +|より小さい|指定した値より小さいデータを検索します。 + +|より大きい|指定した値より大きいデータを検索します。 + +|以下|指定した値以下のデータを検索します。 + +|以上|指定した値以上のデータを検索します。 + +|範囲|指定したFromからToの範囲内のデータを検索します。 + +|日付相対範囲|定義済みの相対期間でDate型プロパティを検索します。 + +|日時相対範囲|定義済みの相対期間でDateTime型プロパティを検索します。 + +|値が設定されている|値がNULLでないデータを検索します。 + +|値が設定されていない|値がNULLのデータを検索します。 +|=== + +各データ型で利用できる演算子は以下のとおりです。 + +[cols="1,6a", options="header"] +|=== +|データ型|利用可能な演算子 + +|String|等しい, 等しくない, 前方一致, 後方一致, 含む, 含まない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|AutoNumber|等しい, 等しくない, 前方一致, 後方一致, 含む, 含まない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|Integer / Decimal / Float|等しい, 等しくない, 前方一致, 後方一致, 含む, 含まない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|Boolean|等しい, 等しくない, 値が設定されている, 値が設定されていない + +|Date|等しい, 等しくない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 日付相対範囲, 値が設定されている, 値が設定されていない + +|DateTime|等しい, 等しくない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 日時相対範囲, 値が設定されている, 値が設定されていない + +|Time|等しい, 等しくない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|Select|等しい, 等しくない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|Reference|等しい, 等しくない, いずれかと等しい, 値が設定されている, 値が設定されていない + +|LongText|等しい, 等しくない, 前方一致, 後方一致, 含む, 含まない, いずれかと等しい, より小さい, より大きい, 以下, 以上, 範囲, 値が設定されている, 値が設定されていない + +|Expression|内部のエディタ型に準じる + +|Binary|等しい, 等しくない, 前方一致, 後方一致, 含む, 含まない, 値が設定されている, 値が設定されていない +|=== + +NOTE: LongText型プロパティをフィルター条件として利用するには、 <> の `remainInlineText` を `true` に設定する必要があります。 + +[[mdc_entitylisting_ope_filter_expression]] +===== フィルター条件式 + +フィルターに条件が1つでも追加されると、 `条件式` の入力エリアが表示されます。 +この条件式には各フィルターの組み合わせ条件を指定することができます。 + +`${フィルタの行番号}` で対象の条件を指定します。 + +※ 条件式には、カッコ、AND、OR、NOT を利用することができます。 + +フィルター条件式が未指定の場合は、同一プロパティはOR条件として、他プロパティに対してはAND条件として検索します。 + +.例：条件式の指定例 +フィルター条件として以下を指定した場合、 +---- +1. 販売ステータス = '準備中' +2. 販売ステータス = '販売中' +3. 在庫数 < 500 +4. 在庫数 < 100 +---- + +条件式が未指定の場合は以下の条件で検索されます。 +---- + ( 販売ステータス = '準備中' OR 販売ステータス = '販売中' ) AND ( 在庫数 < 500 OR 在庫数 < 100 ) +---- + +条件式に以下を指定した場合、 +---- +($1 and $3) or ($2 and $4) +---- +以下の条件で検索されます。 +---- + ( 販売ステータス = '準備中' AND 在庫数 < 500 ) OR ( 販売ステータス = '販売中' AND 在庫数 < 100 ) +---- + +[[mdc_entitylisting_ope_resultfilter]] +==== 結果の絞り込み（HAVING条件） + +抽出項目に集計関数が指定されている場合、結果の絞り込みを設定することが可能です。 +結果の絞り込みはSQLのHAVING句に相当し、集計結果に対する条件を指定します。 + +NOTE: 結果の絞り込みは、集計関数が設定された抽出項目が1件以上存在する場合にのみ利用できます。 + +EntityListingメタデータの `to edit the narrowing condition, as dialog` の設定により、入力方式が異なります。 + +ダイアログモード（デフォルト）:: +「絞り込み」ボタンをクリックすると、結果の絞り込み条件を指定するダイアログが表示されます。 ++ +image::images/mdc_entitylisting_ope_resultfilter_dialog.png[] ++ +ダイアログ上部には現在設定されている抽出項目がチップとして一覧表示されます。 +チップをクリックすると絞り込み条件の行として追加されます。 ++ +追加された条件行の構成はフィルター条件と同一です（<>を参照）。ただし「プロパティ名」欄には抽出項目名（集計関数が設定されている場合はその関数名も含む）が表示されます。 +「確定」ボタンをクリックして絞り込み条件を適用します。 + +直接編集モード:: +フィルター条件の下に、結果の絞り込みエリアが直接表示されます。 +抽出項目エリアの抽出項目チップを **クリック** すると絞り込み条件の行として直接追加されます。 ++ +image::images/mdc_entitylisting_ope_resultfilter_inline.png[] ++ +追加された条件行の構成はフィルター条件と同一です（<>を参照）。ただし「プロパティ名」欄には抽出項目名（集計関数が設定されている場合はその関数名も含む）が表示されます。 + +結果の絞り込みでもフィルター条件と同様に条件式を利用することが可能です（条件式の記法については<>を参照してください）。 + +[[mdc_entitylisting_ope_distinct]] +==== 重複除外（DISTINCT） + +検索結果から重複行を除外する場合は、検索条件エリアの `検索結果から重複行を除く` チェックボックスをONにします。 + +[[mdc_entitylisting_ope_search]] +==== 検索の実行 + +検索条件を設定後、 `検索` ボタンをクリックすることで検索を実行します。 + +[[mdc_entitylisting_ope_result]] +==== 検索結果一覧 + +検索結果はテーブル形式で表示されます。 + +image::images/mdc_entitylisting_ope_result.png[] + +.ソート +検索結果一覧のヘッダー列をクリックすると、その列で昇順・降順のソートを切り替えることができます。 + +.ページング +検索結果の件数がページ表示件数を超えた場合にページングが表示されます。 +ページ番号をクリックすると該当ページの検索結果が表示されます。 +ページ表示件数は<> の `entityListingSearchLimit` で変更可能です（デフォルト：10件）。 + +.エンティティ参照 +`抽出項目` にオブジェクトID（`oid`）が含まれている場合、検索結果に参照リンクが表示されます。 +リンクをクリックすることで、エンティティの参照画面がダイアログで表示されます。 + +image::images/mdc_entitylisting_ope_entity_reference.png[] + +※ 対象エンティティの `OID` プロパティをカスタマイズしている場合、 `OID` プロパティが1つのみであれば、その項目に対してもリンクが表示されます。複数項目を利用して `OID` プロパティを指定している場合（複合指定）は、リンク表示されません。 + +※EntityListingメタデータを定義することで、 `name` プロパティに対してもリンクを表示することが可能です（<> の `show reference dialog from name property` を参照）。 + +※ EntityListingメタデータを定義することで、参照時のView指定や編集可能とするかの設定が可能です。デフォルトでは `default` Viewで `編集可` として動作します。 + +.ユーザープロパティの表示 +エンティティの「作成者」、「更新者」、「ロックユーザー」などのユーザー関連プロパティは、EntityListingメタデータの設定により名前で表示することが可能です。 +`handle inherited user property as name` を有効にすると、フィルター条件にはUserエンティティを選択して指定でき、検索結果やファイル出力には名前が出力されます（ソートはOIDで比較します）。 + +[[mdc_entitylisting_ope_download]] +==== ファイルダウンロード + +検索条件エリアの `ダウンロード` ボタンをクリックすると、ファイルダウンロードダイアログが表示されます。 + +image::images/mdc_entitylisting_ope_download.png[] + +ダイアログでは以下のオプションが指定可能です。 + +[cols="1,5a", options="header"] +|=== +|設定項目|説明 + +|ファイルタイプ +|EntityListingメタデータの `File type` が `SPECIFY` の場合に表示されます。 +CSVまたはExcelのいずれかを選択します。 +`SPECIFY` 以外の場合は、メタデータの設定に従い自動でファイルタイプが決定されます。 + +メタデータの `File type` が未指定の場合は、<> の `entityListingFileSupportType` によって動作します。 + +|コード値でダウンロード +|チェックを入れると、Select型プロパティの値を表示名ではなくコード値で出力します。 + +|文字コード +|CSVファイルダウンロード時の文字コードを選択します。Excelファイルの場合はこの設定は無視されます。 + +選択可能な文字コードは<> の `csvDownloadCharacterCode` で設定します。 +|=== + +NOTE: ダウンロードボタンの表示はEntityListingメタデータの `can file download` で制御します。 + diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/setting.adoc b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/setting.adoc new file mode 100644 index 0000000..5f52a50 --- /dev/null +++ b/developerguide/src/docs/asciidoc/materialdesigncomponents/entitylisting/setting.adoc @@ -0,0 +1,616 @@ +[[mdc_entitylisting_management]] +== EntityListingの管理 + +[[mdc_entitylisting_create]] +=== EntityListingの作成 + +EntityListingアイコンを右クリックして、「MDC EntityListingを作成する」を選択してください。 + +[[mdc_entitylisting_setting]] +=== 設定 + +メタデータを定義しなくてもEntityListing機能自体は実行することが可能です。 + +ただし、ユーザーによって利用可能なエンティティやプロパティを制御したい場合には、EntityListingメタデータを作成します。 + +EntityListingメタデータが1つでも登録されている場合は、メニューのパラメータに必ず `defName` を指定してください。 + +[[mdc_entitylisting_defaultsetting]] +==== Default Setting + +ここでの設定は、下のCustom Settingを設定していないエンティティに対してデフォルトで適用される設定です。 + +image::images/mdc_entitylisting_default_setting.png[] + +[cols="1,5a", options="header"] +|=== +|設定項目|設定値 + +|exclude mtp entities +|選択可能なエンティティから「mtp.*」を除外します。 +下のCustom Settingでエンティティを1つでも選択している場合は、そちらが優先されます。 + +|exclude inherited properties +|選択可能なプロパティとして継承プロパティを除外します。 +下のCustom Settingでエンティティ別にプロパティ設定をしている場合は、そちらが優先されます。 +選択した場合、オブジェクトIDが選択可能なプロパティとして選択できなくなるため、エンティティの参照画面が開けなくなります。 +（エンティティ定義でOIDプロパティを独自指定している場合は可能です） + +|to edit the narrowing condition, as dialog +|抽出項目に集計関数がある場合に利用可能な絞り込み条件（HAVING条件）の指定方法を設定します。 + +ダイアログモードの場合:: +絞り込みボタンが表示され、クリックで結果の絞り込みを行うダイアログを表示 + +直接編集モードの場合:: +フィルター条件の下に絞り込み対象を指定する領域を表示 + +|handle inherited user property as name +|エンティティの「作成者」、「更新者」、「ロックユーザー」を名前で扱います。 +フィルター条件に指定する場合は、Userエンティティを選択します。 +検索結果、ファイルには名前が出力されます（ただしソートはOIDで比較します）。 + +|display user name in privileged execution +| `handle inherited user property as name` がチェックされている場合、ユーザー名を特権実行で取得します。 +それによりユーザー情報のEntity、またはユーザー名のプロパティに参照権限が無いユーザーでもユーザー名を表示することが可能です。 + +|show reference dialog for edit mode +|エンティティの参照画面を開く際に編集可能モードで開くかを指定します。 + +下のCustom Settingでエンティティ別に設定をしている場合は、そちらが優先されます。 + +|show reference dialog from name property +|抽出項目として「name」プロパティを指定した際に、参照画面のリンクを表示するかを指定します。 + +下のCustom Settingでエンティティ別に設定をしている場合は、そちらが優先されます。 + +|can file download +|条件編集画面で「ダウンロード」ボタンを利用できるかを指定します。 + +|use property name in file header +|ファイルヘッダに表示名ではなくプロパティ名を出力します。 + +|File type +|ダウンロードで利用するファイル形式を指定します。 + +CSV:: +CSVファイルを利用します。 + +EXCEL:: +EXCELファイルを利用します。 + +SPECIFY:: +CSVファイルかEXCELファイルのどちらを利用するかを画面で選択します。 + +未指定の場合は、<> の `entityListingFileSupportType` によって動作します。 + +|file multiple format +|ファイルダウンロード時の多重度が複数のプロパティの出力形式を指定します。 + +Each Column:: +多重度の数分別々の列に出力します。 + +One Column:: +1つの列にカンマ区切りでまとめて出力します。 + +One Column Fill Null:: +1つの列にカンマ区切りでまとめて出力します。 +登録データが多重度分保存されていない場合にも多重度分空を補完します。 + +|File Name Format +|ファイルダウンロード時のファイル名をGroovyTemplate書式を利用して指定します。詳細は<>を参照してください。 + +|Custom ViewScript +|EntityListing画面内に埋め込むカスタムコンテンツを設定できます。 +`Template Interpret Type` の設定により、HTML、VUE_SFC、VUE_SFC_LIKE形式で定義できます。 +詳細は<>を参照してください。 + +|Query interrupter class name +|実際に検索が実行される直前に、実行するEQLをカスタマイズするためのクラスを指定します。 +詳細は<>を参照してください。 + +|=== + +[[mdc_el_filenameformat]] +===== File Name Format + +ファイルダウンロード時のファイル名をGroovyTemplate書式を利用して指定します。 +フォーマットが指定されている場合、ボタンタイトルに「(*)」が表示されます。 +また、/とスペースについては、_（アンダースコア）に変換します。 + +利用可能なバインド変数は、編集ダイアログの「Notes」を参照してください。 + +.（例）ファイル名の後ろに出力時の時間を付加する。 +[source,groovy] +---- +${csvName}_${yyyy}${MM}${dd}${HH}${mm}${ss} +---- + +[[mdc_el_customviewscript]] +===== Custom ViewScript + +EntityListing画面内にカスタムコンテンツを埋め込むことが可能です。 + +HTMLやスクリプト、Vue.jsのSFC形式（単一ファイルコンポーネント形式）などでカスタムコンテンツを記述できます。 + +カスタムコンテンツは検索結果エリアの下部に表示されます。 + +Custom ViewScriptダイアログでは以下の設定を行います。 + +[cols="1,5a", options="header"] +|=== +|設定項目|設定値 + +|Template Interpret Type +|記述されたスクリプトの解釈タイプです。以下の３つから選択できます。 + +HTML:: HTMLとして解釈します。HTMLやスクリプトの記述が可能です。 +VUE_SFC:: Vue.jsのSFC形式（単一ファイルコンポーネント形式）で記述されたコンポーネントとして解釈します。 +VUE_SFC_LIKE:: Vue.jsのランタイムを用いてコンポーネントとして解釈します。MDCでは、Vue.jsのランタイムに加えてコンパイラもバンドルしており、Vue.jsのテンプレート構文を利用することが可能です。 + +|ComponentName +|コンポーネント名を設定します。コンポーネント名は、英文字とハイフン(-)のみを利用したパスカルケースでの命名を推奨します。 +`Template Interpret Type` が `VUE_SFC_LIKE` の場合、コンポーネント名の指定は必須です。 `Template Interpret Type` が `VUE_SFC` でコンポーネント名が未入力の場合、自動でランダムなコンポーネント名を割り当てます。 + +|Script +|スクリプト編集画面を表示してGroovyTemplateの文法に従って記述します。 +詳細は<<../../customizing/index.adoc#groovytemplate, GroovyTemplate>>を参照してください。 + +|Precompile VUE_SFC format template +|Vue.jsのSFC形式のテンプレートをプリコンパイルするかを指定します。 `Template Interpret Type` が `VUE_SFC` であり、Vue.jsのSFC形式のテンプレートを定義保存時にプリコンパイルしておきたい場合にチェックします。プリコンパイルしておくことで、コンポーネントの初期化処理を高速化できます。 + +[NOTE] +==== +プリコンパイルの注意点:: +- プリコンパイルを実行したい場合には、 `ComponentName` の指定が必須となります。 +- `Script` に記述したGroovyTemplateは、EntityListing定義保存時に実行されてプリコンパイルされるため、リクエスト情報やセッション情報、ユーザー固有情報などを使用しないように注意してください。 +==== +|=== + +.VUE_SFC形式、VUE_SFC_LIKE形式の場合のコンポーネントとのデータ受け渡し（props/emit） + +以下のデータがpropsとしてコンポーネントに引き渡されます。 +==== +contextMap:: コンテキストマップ。リアクティブな空のMapオブジェクト。 + +コンテキストマップにデータを格納することで、複数のパーツ（コンポーネント）間でリアクティブにデータを共有することが可能です。 +==== + + +[[mdc_entitylisting_queryinterceptor]] +===== Query Interceptor + +パフォーマンス改善などの目的で、実際に検索を行う直前のEQLをカスタマイズすることが可能です。 +以下のEntityListingQueryInterceptorを実装したJavaクラスまたはUtilityClassを指定します。 + +==== +org.iplass.mtp.mdc.view.entitylisting.EntityListingQueryInterceptor +==== + +EntityListingの検索では、ページング制御のための件数取得と実際のデータ検索の2回EQLが実行されます。 +EntityListingQueryInterceptorではこのEQL実行直前にカスタム処理を追加することができます。 + +.処理一覧 +[cols="1,1,1,3a",options="header"] +|=== +|メソッド +|引数 +|戻り値 +|処理内容 + +|beforeCount +|EntityListingQueryContext +|void +|件数取得前処理を行います。 +contextのQueryを変更することで、件数取得条件をカスタマイズできます。 + +|beforeSearch +|EntityListingQueryContext +|void +|検索前処理を行います。 +contextのQueryを変更することで、検索条件をカスタマイズできます。 + +.2+|afterSearch +|Object[] +.2+|void +.2+|検索後処理を行います。afterSearchでは1レコード毎に処理が呼ばれます。 +dataを変更することで、検索結果をカスタマイズできます。 +|EntityListingQueryContext +|=== + +.EntityListingQueryInterceptorの実装例 +[source,java] +---- +package sample.entitylisting; + +import org.iplass.mtp.entity.query.Query; +import org.iplass.mtp.entity.query.hint.CacheHint; +import org.iplass.mtp.entity.query.hint.CacheHint.CacheScope; +import org.iplass.mtp.entity.query.hint.TimeoutHint; +import org.iplass.mtp.mdc.view.entitylisting.EntityListingQueryContext; + +// 実装するIF定義 +import org.iplass.mtp.mdc.view.entitylisting.EntityListingQueryInterceptor; + +// サンプル用 +import org.iplass.mtp.auth.User; + +public class SampleQueryInterceptor implements EntityListingQueryInterceptor { + + // beforeCountとbeforeSearchで渡されるEntityListingQueryContextは同一インスタンスではありません + + @Override + public void beforeCount(EntityListingQueryContext context) { + + // QueryContextからQueryを取得 + Query query = context.getQuery(); + + // (例)Queryに対してCacheHintを指定 + query.hint(new CacheHint(CacheScope.GLOBAL, 60)); + + System.out.println("interrupt result:" + query.toString()); + + // (例)Entity権限における限定条件の除外設定 + setWithoutConditionReferenceName(context); + } + + @Override + public void beforeSearch(EntityListingQueryContext context) { + + // QueryContextからQueryを取得 + Query query = context.getQuery(); + + // (例)Queryに対してCacheHint、TimeoutHintを指定 + query.hint(new CacheHint(CacheScope.GLOBAL, 60)) + .hint(new TimeoutHint(120)); + + System.out.println("interrupt result:" + query.toString()); + + // EntityListingQueryContextからはEntityListing定義名、エンティティ名も取得可能 + System.out.println("target entity listing definition name:" + + context.getCondition().getDefinitionName()); + System.out.println("target entity definition name:" + + context.getCondition().getEntityName()); + + // (例)Entity権限における限定条件の除外設定 + setWithoutConditionReferenceName(context); + } + + @Override + public void afterSearch(Object[] data, EntityListingQueryContext context) { + + // (例)Userエンティティに対してメールアドレスを検索された場合、値を置き換える + if (context.getCondition().getEntityName().equals(User.DEFINITION_NAME)) { + // ここでdata配列の値を加工して検索結果をカスタマイズ + // 例：特定のインデックスのデータをマスキング + } + } + + /** + * Entity権限における限定条件の除外設定 + */ + private void setWithoutConditionReferenceName(EntityListingQueryContext context) { + + // EntityListingQueryContextに対してWithoutConditionReferenceNameとして + // Entity権限における限定条件を除外するプロパティを指定することができる + + // EntityListingは対象Entityを選択可能なためデフォルト設定のInterceptorで処理する場合はEntity名をチェック + // Entity別にInterceptorを定義している場合は特にチェック不要 + + // 対象EntityがUserの場合 + if (context.getCondition().getEntityName().equals(User.DEFINITION_NAME)) { + // groupsとrankのEntity権限における限定条件を除外 + context.setWithoutConditionReferenceName(User.GROUPS, User.RANK); + } + } + +} +---- + + +[[mdc_entitylisting_customsetting]] +==== Custom Setting + +Default Settingではなく、エンティティ個別に設定を行いたい場合に指定します。 + +image::images/mdc_entitylisting_custom_setting.png[] + +[cols="1,5a", options="header"] +|=== +|設定項目|設定値 + +|Target +|参照可能なエンティティを選択します。対象外のエンティティを参照しようとした場合は権限エラーとなります。 +1つも選択されていない場合は、Default Settingの `exclude mtp entities` 設定により対象を決定します。 + +|DisRoot +| `Target` 指定されたエンティティのうち、エンティティの選択リストから除外したいエンティティを選択します。 +他エンティティの参照先としてのみ検索を許可する場合に指定します。 + +|Custom +|個別に `Entity Custom Setting` が設定されている場合に「Y」が表示されます。 + +|=== + +個別にプロパティなどを絞り込みたい場合は、対象のエンティティをダブルクリックしてください。 +右側にエンティティごとの設定項目が表示されます。 + +グリッド下部のボタンで一括操作が行えます。 + +[cols="1,4a", options="header"] +|=== +|ボタン|説明 +|Select All|全エンティティを対象として選択します。 +|Deselect All|全エンティティの選択を解除します。 +|Deselect mtp|「mtp.*」エンティティの選択を解除します。 +|=== + +[[mdc_entitylisting_entitycustomsetting]] +==== Entity Custom Setting + +エンティティ個別の設定項目です。Custom Settingでエンティティをダブルクリックすることで表示されます。 + +[cols="1,5a", options="header"] +|=== +|設定項目|設定値 + +|exclude inherited properties +|選択可能なプロパティとして継承プロパティを除外します。 +下のプロパティ選択部分で1件でも選択されている場合は、そちらが優先されます。 + +|handle inherited user property as name +|エンティティの「作成者」、「更新者」、「ロックユーザー」を名前で扱います。 + +|display user name in privileged execution +| `handle inherited user property as name` がチェックされている場合、ユーザー名を特権実行で取得します。 +それによりユーザー情報のEntity、またはユーザー名のプロパティに参照権限が無いユーザーでもユーザー名を表示することが可能です。 + +|show reference dialog for edit mode +|エンティティの参照画面を開く際に編集可能モードで開くかを指定します。 + +|show reference dialog from name property +|抽出項目として「name」プロパティを指定した際に、参照画面のリンクを表示するかを指定します。 + +|View Name +|エンティティの参照画面を開く際のView名をGroovyTemplate書式を利用して指定します。 +詳細は<>を参照してください。 + +|File Name Format +|ファイルダウンロード時のファイル名をGroovyTemplate書式を利用して指定します。 +「Default Setting」と同様です。 + +|Without Condition Reference +|Entity権限における限定条件を適用せずに検索を実行する参照先プロパティ名を設定します。特権実行する場合、または `Query interrupter class name` の設定がある場合はそちらが優先されます。 + +|Query interrupter class name +|実際に検索が実行される直前に、実行するEQLをカスタマイズするためのクラスを指定します。 +未指定の場合は「Default Setting」の設定が有効になります。 +詳細は<>を参照してください。 + +|Propertyリスト +|選択可能としたいプロパティをチェックしてください。 + +|=== + + +[[mdc_el_viewname]] +===== View Nameの指定 + +エンティティの参照画面を開く際のView名をGroovyTemplate書式を利用して指定します。 +値が設定されている場合、ボタンタイトルに「(*)」が表示されます。 + +利用可能なバインド変数は、編集ダイアログの「Notes」を参照してください。 + +.（例）文字列直接指定 +[source,groovy] +---- +opeView +---- + +.（例）GroovyTemplate指定 +[source,groovy] +---- +<%@import org.iplass.mtp.entity.Entity %> + +<% +def viewName = "XXXXXXXXX"; +%> + +${viewName} +---- + +検索結果のリンク表示時には、表示対象データのOIDが「oid」としてバインドされています。 +フィルター条件としてReferenceを指定した場合の参照時はOIDはバインドされません。 + +[[mdc_entitylisting_display]] +=== 表示方法 + +==== メニューへの登録 + +MDC EntityListing画面を表示するには、メニューにActionMenuItemを登録します。 + +ActionMenuItemに以下の設定を行ってください。 + +[cols="1,5a", options="header"] +|=== +|項目|設定値 + +|Name|管理しやすいように設定してください。 +|DisplayName|メニューの表示名になります。 +|Execute Action| `mdc/entitylisting/view` を指定してください。 +|Parameter| `defName=XXX&entityName=XXX` + +defName:: 作成したEntityListingメタデータ名を指定します。 +entityName:: 初期表示時に選択したいエンティティ名を指定します。defNameには表示可能なエンティティを指定する必要があります。 + +|=== + +NOTE: EntityListingメタデータが1つでも登録されている場合は、パラメータに `defName` を指定する必要があります。 + +=== EntityListing関連のサービス設定 +[[mdc_entitylisting_service_config]] +==== MdcConfigService + +MdcConfigServiceのEntityListing関連の設定一覧です。 + +[cols="1,1,4a", options="header"] +|=== +|設定項目|デフォルト値|説明 + +|entityListingSearchLimit +|10 +|EntityListingの検索結果のページ表示件数。 +1ページあたりに表示するデータ件数を指定します。 + +|entityListingFileSupportType +|CSV +|EntityListingのデフォルトのサポートファイルタイプ。 +EntityListingメタデータの `File type` が未指定の場合に適用されます。 + +設定値: `CSV` , `EXCEL` , `SPECIFY` + +|entityListingFileDownloadWithFooter +|false +|EntityListingのファイルダウンロードでフッターを出力するかを指定します。 + +|entityListingFileDownloadFooter +|（空文字） +|EntityListingのファイルダウンロードで出力するフッター文言を指定します。 +`entityListingFileDownloadWithFooter` が `true` の場合に有効です。 + +|formatNumberWithComma +|true +|数値プロパティの値をカンマでフォーマット表示するかを指定します。 +EntityListingの検索結果およびファイルダウンロードで数値のカンマ区切り表示に影響します。 + +抽出項目の「数値フォーマット設定」が未指定の場合にこの設定が適用されます。 + +|csvDownloadCharacterCode +|UTF-8 +|CSVファイルダウンロード時に選択可能な文字コードの一覧を指定します。 +複数指定（additional="true"）することで、ダウンロードダイアログに複数の文字コードが表示されます。 + +|relativeRanges +|（未設定） +|フィルター条件の日付相対範囲（RD）や日時相対範囲（RDT）で使用するカスタム相対範囲を定義します。 +詳細は<>を参照してください。 + +|=== + +[[mdc_entitylisting_relativerange]] +===== カスタム相対範囲 + +フィルター条件の日付相対範囲（RD）や日時相対範囲（RDT）で使用するカスタム相対範囲を定義できます。 +カスタム相対範囲はmdc-service-config.xmlの `MdcRelativeRangeService` で設定します。 + +.mdc-service-config.xmlでの設定例 +[source,xml] +---- + + org.iplass.mtp.mdc.view.entitylisting.range.MdcRelativeRangeService + org.iplass.mtp.mdc.view.entitylisting.range.MdcRelativeRangeService + + + + + + + + + + + + + + +---- + +[cols="1,5a", options="header"] +|=== +|設定項目|設定値 + +|relativeRangeName +|カスタム相対範囲の識別名。フィルター条件の内部パラメータとして使用されます。 + +|displayLabel +|画面に表示するデフォルトの表示ラベル。 + +|localizedDisplayLabel +|ロケールごとの表示ラベルを設定します。 `locale` と `displayLabel` のペアで定義します。 + +|converter +| `MdcRelativeRangeConverter` インターフェースを実装したクラスを指定します。 +フィルター条件に選択された相対範囲名から、実際の日付範囲（From/To）に変換するロジックを実装します。 +|=== + +`MdcRelativeRangeConverter` は以下のメソッドを実装する必要があります。 + +[cols="1,5a", options="header"] +|=== +|メソッド|説明 + +|Condition createCondition(String propertyName, Date sysDate) +|フィルター条件に変換します。 + +`propertyName` はフィルター対象のプロパティ名、 `sysDate` はシステム日付（ `java.sql.Date` ）です。 + +返却値は `org.iplass.mtp.entity.query.condition.Condition` のサブクラスを返します。 +|=== + +.MdcRelativeRangeConverterの実装例（今月範囲） +[source,java] +---- +package com.example; + +import java.sql.Date; +import java.time.LocalDate; + +import org.iplass.mtp.entity.query.condition.Condition; +import org.iplass.mtp.entity.query.condition.predicate.Between; +import org.iplass.mtp.mdc.view.entitylisting.range.MdcRelativeRangeConverter; + +/** + * 今月の日付範囲を返すカスタム相対範囲コンバーター。 + */ +public class ThisMonthRangeConverter implements MdcRelativeRangeConverter { + + @Override + public Condition createCondition(String propertyName, Date sysDate) { + LocalDate local = sysDate.toLocalDate(); + + // 月初日 + Date from = Date.valueOf(local.withDayOfMonth(1)); + + // 月末日 + Date to = Date.valueOf(local.withDayOfMonth(local.lengthOfMonth())); + + return new Between(propertyName, from, to); + } +} +---- + +上記の実装クラスは、mdc-service-config.xmlの `converter` プロパティに指定します。 + +[source,xml] +---- + +---- + +[[mdc_entitylisting_property_service_config]] +==== PropertyService + +PropertyServiceのEntityListing関連の設定一覧です。 + +[cols="1,1,4a", options="header"] +|=== +|設定項目|デフォルト値|説明 + +|remainInlineText +|false +|LongText型プロパティをフィルター条件として利用する場合は `true` に設定する必要があります。 + +`false` （デフォルト）の場合、LongText型プロパティはフィルター条件の対象外となります。 + +|=== + +.mtp-service-config.xmlでの設定例 +[source,xml] +---- + + org.iplass.mtp.impl.entity.property.PropertyService + + +---- diff --git a/developerguide/src/docs/asciidoc/materialdesigncomponents/index.adoc b/developerguide/src/docs/asciidoc/materialdesigncomponents/index.adoc index 1fb2065..adb8093 100644 --- a/developerguide/src/docs/asciidoc/materialdesigncomponents/index.adoc +++ b/developerguide/src/docs/asciidoc/materialdesigncomponents/index.adoc @@ -31,6 +31,9 @@ MDCモジュールにおけるカレンダー画面の設定です。単一ま == <<./aggregation/index.adoc#, Aggregation>> MDCモジュールにおける定型集計画面の設定です。予め設定された集計方式、検索条件を元に、データの集計やグラフ表示を行います。単純集計とクロス集計をサポートしています。 +== <<./entitylisting/index.adoc#, EntityListing>> +MDCモジュールにおける汎用検索画面の設定です。検索画面上で抽出項目やフィルター条件や絞り込みを動的に指定し、エンティティを柔軟に検索できます。 + == <<./mdcauth/index.adoc#, 権限制御>> MDC機能に対する権限制御Utilityの提供や、EntityViewの管理設定によるView単位での参照制御をすることができます。