(MS 動作仕様)
TOP ver.6.4 (ja-JP)
# MS 基本ガイド
## 目次
- [1. MS 動作概要](#1-ms-)
- [2. データ取得仕様](#2-)
- [3. MS 各種設定定義(旧:デザイン定義)](#3-ms-)
- [3.1.フォーマット](#3-1-)
- [3.2.デフォルト定義](#3-2-)
- [3.3. 言語設定](#3-2-)
- [3.3.1 言語設定: <語彙>](#3-3-1-)
- [3.3.2 言語設定: 言語コードの記法](#3-3-2-)
- [3.3.3 言語設定: ページ言語の判定](#3-3-3-)
- [3.3.4 言語設定: ページ言語の動的変更](#3-3-4-)
- [3.3.5 言語設定: テキストの登録](#3-3-5-)
- [3.3.6 言語設定: テキストの選択 (1) 基本ルール](#3-3-6-1-)
- [3.3.7 言語設定: テキストの選択 (2) 選択例](#3-3-7-2-)
- [3.4. フリーワード検索設定](#3-4-)
- [3.4.1 フリーワード検索: 表示位置](#3-4-1-)
- [3.4.2 フリーワード検索: 検索タイミング](#3-4-2-)
- [3.4.3 フリーワード検索: AND/OR/FORMULA 切り替え](#3-4-3-and-or-formula-)
- [3.5. 各種検索設定](#3-5-)
- [3.5.1 各種検索設定: 検索件数](#3-5-1-)
- [3.6. 各種操作設定](#3-6-)
- [3.6.1 各種操作設定: 上限件数](#3-6-1-)
## 1. MS 動作概要
- 下表の３種類のTSVファイルを元にサービスが構築される。
- UIは、MSコンポーネントタグをHTMLの任意の位置に記述することでMSの各UI機能を実現する。
| No | 項目 | 内容 |
|:--:|:--------------------------------------|:-------------------------------------------------------------|
| 1 | 各種設定定義(旧:デザイン定義)TSV | 各種言語テキストや、MS機能全般のカスタマイズ定義。 |
| 2 | 属性定義TSV | アイテムデータの各属性に関する仕様定義。 |
| 3 | アイテムデータTSV | MSで検索対象とするアイテムのマスターデータ。 |
## 2. データ取得仕様
| No | 項目 | 内容 |
|:--:|:--------------------------------------|:-----------------------|
| 1 | データ取得時IPアドレス | 不特定。 |
| 2 | 各種設定定義TSV URL/ファイル名 | 任意のURL/ファイル名。HTTP(S)。Basic認証可 |
| 3 | 属性定義TSV URL/ファイル名 | 任意のURL/ファイル名。HTTP(S)。Basic認証可 |
| 4 | アイテムデータ定義TSV URL/ファイル名 | 任意のURL/ファイル名。HTTP(S)。Basic認証可 |
## 3. MS 各種設定定義(旧:デザイン定義)
***(概要)*** *各種設定定義(旧称:デザイン定義)で、 下表の項目を設定することにより、MSの機能をカスタマイズ出来る。*
### 3.1.フォーマット
***(概要)*** *各種設定定義(旧称:デザイン定義)のTSV形式は以下の通り。*
| No | カラム | 内容 | 備考 |
|:--:|:---------------------------------|:-----------------------------------------------------------------------------------------------------------------------------|
| 1 | key | 設定キー | 設定対象項目のキーを指定する。有効なキーについては、下表参照。 |
| 2 | value | 設定値 | 設定値を指定する。 |
| 3 | option | オプション指定 | 同一キーの設定が複数行ある場合、通常後のものが優先となるが、オプションカラムに '!important' を指定するとその設定を優先する。 |
*オプションカラムに '!important' が指定された同一キーの行が複数ある場合は、後のものが優先されます。
*各種設定定義TSVの実例は、[3.2.デフォルト定義](#3-2-) の項目を参照。
### 3.2. デフォルト定義
***(概要)*** *各種設定定義(旧称:デザイン定義)では以下の定義がデフォルトで適用されている。*
デフォルトで定義されている内容には、15言語分のテキスト等を含んでおり、特段の設定を行わなくても、MSの基本機能を利用できる様になっている。
カスタムの各種設定定義TSVに、下記デフォルト定義内の項目と同一のキーの項目がある場合、当該項目の設定値は、カスタム定義の内容で上書きされる。
- https://c.marsflagms.com/resources/ms/v.6.4/data/commons-settings/common-settings.tsv
### 3.3. 言語設定
***(概要)*** *MSコンポーネント中で各言語別テキストがどの様に選択・表示されるかを示す。*
- MSコンポーネント中で表示されるテキスト内容を、言語別に切り替える機能がMSには備わっている。
- 例えば、検索ボタンに、ページ言語が日本語であれば「検索」、英語であれば「Search」と表示させることができる。
#### 3.3.1 言語設定: <語彙>
*本文書で使用する言語設定に関する語彙について記述する。*
| No | 語句 | 意味 |
|:--:|:-----------------------|:------------------------------------------------------------------------------------------------------|
| 1 | 言語コード | ページ言語やテキスト言語を指定する値。(例: `en`, `ja`, `ja-JP`, ...) |
| 2 | ページ言語 | 現在のページの言語。ページ言語に合わせて、表示するテキストが選択される。 |
| 3 | テキスト | ボタンやメッセージ等で表示する文字列のこと。 |
| 4 | テキスト言語 | 各テキストの言語。テキスト登録時に言語コードを指定した場合はその言語、指定していない場合は英語(en)。 |
| 5 | テキスト選択 | ページ言語とテキスト言語を比較して、表示するテキストが選択される。 |
#### 3.3.2 言語設定: 言語コードの記法
*ページ言語やテキスト言語の指定時の、言語コードの記法について、記述する。*
- 言語コードは、`(言語)-(国/地域)-(詳細区分1)-(詳細区分2)` の構造で任意に指定できる。
- 例: `ja`, `ja-JP`, `ja-JP-MARSFLAG` , `ja-JP-MARSFLAG-Support`, ...
- 言語指定に関する仕様の[RFC5646](https://www.ietf.org/rfc/bcp/bcp47.txt)と類似の仕様ですが、 `-` で区切られた各パートの文字数制限等は有りません。
#### 3.3.3 言語設定: ページ言語の判定
*ページの言語は以下の優先順で判定される。*
| No | 項目キー |
|:--:|:-------------------------------------------------------------------------------------------------------------------------------|
| 1 | MS Client API `GALFSRAM.MS.public.setPageLang(langCode)` で指定した言語コード |
| 2 | MSスクリプト(ms-entry.min.js)を読み込む `<script>`タグの `data-system--lang`属性 |
| 3 | `<html>` タグの `lang`属性 |
| 4 | デフォルト: 英語(en) |
* 判定されたページ言語を元に、言語別テキストが選択されるルールは、[3.3.6 言語設定: テキストの選択 (1) 基本ルール](#3-3-6-1-) に記載の仕様による。
#### 3.3.4 言語設定: ページ言語の動的変更
*ページ言語は MS Client API `GALFSRAM.MS.public.setPageLang(langCode)` によって、動的に変更できる。*
- パラメータ `langCode` には、言語コードを `en`, `en-US` の様に指定する。
*現在のページ言語は MS Client API `GALFSRAM.MS.public.getPageLang()` によって、動的に取得できる。*
#### 3.3.5 言語設定: テキストの登録
*テキストは各種設定定義TSVに [3.1.フォーマット](#3-1-) に記載のフォーマットで定義することにより登録する。*
- 例として、「検索結果:」のタイトル部分のテキストである `search_result_title` テキストの設定サンプルを示す。
| No | key (設定キー) | (言語指定) | (使用国例) | value (設定値) |
|:--:|:------------------------------------------------|:----------------------------------|:---------------------------------|:-------------------------------------|
| 1 | search_result_title | - | - | RESULTS : |
| 2 | ja:search_result_title | 日本語 | 日本 | 検索結果 : |
| 3 | en:search_result_title | 英語 | 米国、英国 | Results : |
| 4 | zh:search_result_title | 中国語 | 中国 | 搜索结果 : |
| 5 | ko:search_result_title | 韓国語 | 韓国 | 재정렬 : |
| 6 | es:search_result_title | スペイン語 | スペイン、メキシコ、アルゼンチン | resultado: |
| 7 | pt:search_result_title | ポルトガル語 | ポルトガル、ブラジル | resultado: |
| 8 | fr:search_result_title | フランス語 | フランス、カナダ、ベルギー | Résultat : |
| 9 | de:search_result_title | ドイツ語 | ドイツ、ベルギー | Ergebnis: |
| 10 | ru:search_result_title | ロシア語 | ロシア | Результат: |
| 11 | th:search_result_title | タイ語 | タイ | ผล: |
| 12 | vi:search_result_title | ベトナム語 | ベトナム | Kết quả : |
| 13 | hi:search_result_title | ヒンディー語 | インド | परिणाम : |
| 14 | bn:search_result_title | ベンガル語 | バングラデシュ | ফলাফল: |
| 15 | ur:search_result_title | ウルドゥー語 | パキスタン | نتیجہ: |
| 16 | jv:search_result_title | ジャワ語 | インドネシア | Asil : |
| 17 | ja-JP:search_result_title | 日本語(日本) | - | 検索結果(日本) : |
| 18 | ja-JP-MARSFLAG:search_result_title | 日本語(日本) MARSFLAG | - | 検索結果(日本:MARSFLAG) : |
| 19 | ja-JP-MARSFLAG-Support:search_result_title | 日本語(日本) MARSFLAG:サポート | - | 検索結果(日本:MARSFLAG:サポート) : |
- 上表内容を登録するTSV記載例は以下となる。
```
key value option
search_result_title RESULTS :
ja:search_result_title 検索結果 :
en:search_result_title Results :
zh:search_result_title 搜索结果 :
ko:search_result_title 재정렬 :
es:search_result_title resultado:
pt:search_result_title resultado:
fr:search_result_title Résultat :
de:search_result_title Ergebnis:
ru:search_result_title Результат:
th:search_result_title ผล:
vi:search_result_title Kết quả :
hi:search_result_title परिणाम :
bn:search_result_title ফলাফল:
ur:search_result_title نتیجہ:
jv:search_result_title Asil :
ja-JP:search_result_title 検索結果(日本) :
ja-JP-MARSFLAG:search_result_title 検索結果(日本:MARSFLAG) :
ja-JP-MARSFLAG-Support:search_result_title 検索結果(日本:MARSFLAG:サポート) :
```
#### 3.3.6 言語設定: テキストの選択 (1) 基本ルール
*テキストは、ページ言語と登録されているテキストの言語とを比較して、ページ言語に対して最も適切なテキストが選択される。*
| No | ルール |
|:--:|:-------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | ページ言語指定の `(言語)-(国/地域)-(詳細区分1)-(詳細区分2)` の部分と言語指定が一致するテキスト項目を選択。 |
| 2 | ページ言語指定の `(言語)-(国/地域)-(詳細区分1)` の部分と言語指定が一致するテキスト項目を選択。 |
| 3 | ページ言語指定の `(言語)-(国/地域)` の部分と言語指定が一致するテキスト項目を選択。 |
| 4 | ページ言語指定の `(言語)` の部分と言語指定が一致するテキスト項目を選択。 |
| 5 | ここまでで一致するテキストが見つからない場合は、言語指定のないテキスト項目を選択。 |
* ページ言語は、[3.3.3 言語設定: ページ言語の判定](#3-3-3-) に記載の仕様で判定される。
* 1-4)のフェーズの補足
- 1-4)のフェーズは、ページ言語指定の各パートが末尾から削除されながら言語指定が一致するテキスト項目が選択されることを示している。
- 例えば、ページ言語が `ja-JP-MARSFLAG` の場合、テキスト項目の中から、`ja-JP-MARSFLAG` -> `ja-JP` -> `ja` の優先順で言語指定付きテキスト項目が選択される。
- この様なパート削除がテキスト選択時に行われるのはページ言語側のみで、テキスト項目側の言語指定パートが削除されることはない。
- よって、ページ言語が `ja-JP-MARSFLAG` の場合、言語指定が `ja-JP-ZZ`、`ja-ZZ` 等のテキスト項目が選択されることはない。
#### 3.3.7 言語設定: テキストの選択 (2) 選択例
*[3.3.5 言語設定: テキストの登録](#3-3-5-)の例の設定がされている前提で、 `search_result_title` として表示されるテキスト例を下表に示す。
| No | ページ言語指定 | 選択されるテキストキー | 表示テキスト例 | テキスト言語選択過程 [ページ言語] => (テキスト言語候補1) -> (テキスト言語候補2)...|
|:--:|:----------------------------------------------------------------------------|:----------------------------------------------------------------------------------|
| 1 | 無指定: デフォルト(en) | **en**:search_result_title | Results : | [en] => (en:選択) |
| 2 | en | **en**:search_result_title | Results : | [en] => (en:選択) |
| 3 | en-US | **en**:search_result_title | Results : | [en-US] => (en-US:非存在) -> (en:選択) |
| 4 | en-US-Gov | **en**:search_result_title | Results : | [en-US-Gov] => (en-US-Gov:非存在) -> (en-US:非存在) -> (en:選択) |
| 5 | zz | search_result_title | RESULTS : | [zz] => (zz:非存在) -> (<言語無指定>:選択) |
| 6 | ja | ja:search_result_title | 検索結果 : | [ja] => (ja:選択) |
| 7 | ja-JP | ja-JP:search_result_title | 検索結果(日本) : | [ja-JP] => (ja-JP:選択) |
| 8 | ja-ZZ | ja:search_result_title | 検索結果 : | [ja-JP] => (ja-JP:非存在) -> (ja:選択) |
| 9 | ja-JP-MARSFLAG | ja-JP-MARSFLAG:search_result_title | 検索結果(日本:MARSFLAG) : | [ja-JP-MARSFLAG] => (ja-JP-MARSFLAG:選択) |
| 10 | ja-JP-ZZ | ja-JP-ZZ:search_result_title | 検索結果(日本) : | [ja-JP-ZZ] => (ja-JP-ZZ:非存在) -> (ja-JP:選択) |
| 11 | ja-JP-MARSFLAG-Support | ja-JP-MARSFLAG-Support:search_result_title | 検索結果(日本:MARSFLAG:サポート) : | [ja-JP-MARSFLAG-Support] => (ja-JP-MARSFLAG-Support:非存在) -> (ja-JP-MARSFLAG:選択) |
| 12 | ja-JP-MARSFLAG-ZZ | ja-JP-MARSFLAG-ZZ:search_result_title | 検索結果(日本:MARSFLAG) : | [ja-JP-MARSFLAG-ZZ] => (ja-JP-MARSFLAG-ZZ:非存在) -> (ja-JP-MARSFLAG:選択) |
| 13 | ja-ZZ-ZZ-ZZ | ja-ZZ-ZZ-ZZ:search_result_title | 検索結果 : | [ja-ZZ-ZZ-ZZ] => (ja-ZZ-ZZ-ZZ:非存在) -> (ja-ZZ-ZZ:非存在) -> (ja-ZZ:非存在) -> (ja:選択) |
### 3.4. フリーワード検索設定
#### 3.4.1 フリーワード検索: 表示位置
***(概要)*** *検索条件一括表示コンポーネントの中でのフリーワード検索コンポーネントの表示位置を変更することができる。デフォルトでは先頭に表示される。*
| No | 項目キー | 型 | デフォルト値 | 内容 |
|:--:|:---------------------------------|:---------|:--------------|:-----------------------------------------------------------------|
| 1 | search_condition_freeword_first | Integer | 1 | 1:先頭に表示。0:先頭に表示しない。 |
| 2 | search_condition_freeword_last | Integer | 0 | 1:末尾に表示。0:末尾に表示しない。 |
| 3 | search_condition_freeword_order | Number | - | 他属性の `search_condition_order` と比較して表示位置を決定する。 |
#### 3.4.2 フリーワード検索: 検索タイミング
***(概要)*** *フリーワード条件における検索タイミングを設定できる。デフォルトでは検索語句入力後の、Enterキー押下時、検索ボタン押下時に検索が発動する。*
***(重要!)*** *下表 `auto`, `realtime` 設定は、検索回数が増加する為、 **追加のオプション契約が必要です** 。通常は、デフォルトで利用下さい。*
| No | 項目キー | 型 | 設定値 | 内容 |
|:--:|:-----------------------------------------------|:---------|:-----------|:------------------------------------------------------------------------------------|
| 1 | search_condition_freeword_method | String | - | <デフォルト>: Enterキー押下時、検索ボタン押下時。 |
| 2 | <同上> | String | `auto` | 入力ボックスのonchangeイベント発生時(日本語入力では変換確定時等)。 |
| 3 | <同上> | String | `realtime` | 入力ボックスを随時チェックして変化を検知した時(日本語入力の未変換時にも発生)。 |
上表の設定で、 `realtime` を設定する場合は、下表の設定により、入力ボックスのチェック間隔を調整できる。
| No | 項目キー | 型 | デフォルト値 | 内容 |
|:--:|:-----------------------------------------------|:---------|:-------------|:-----------------------------------------------------------------|
| 1 | search_condition_freeword_realtime_interval_ms | Integer | 600 | 入力ボックスのチェック間隔。 |
#### 3.4.3 フリーワード検索: AND/OR/FORMULA 切り替え]
***(概要)*** *フリーワード条件におけるスペース区切りの各単語の扱いを設定する。*
| No | 項目キー | 型 | 設定値 | 内容 |
|:--:|:-----------------------------------------------|:---------|:-----------|:----------------------------------------------------------------------------------------------------|
| 1 | search_condition_freeword_operator | String | `AND` | <デフォルト>: `apple orange` で検索すると、`apple` かつ `orange` 両方を含むアイテムがヒットする。 |
| 2 | <同上> | String | `OR` | `apple orange` で検索すると、`apple` または `orange` どちらかを含むアイテムがヒットする。 |
| 3 | <同上> | String | `FORMULA` | `apple AND orange` で検索すると*AND条件*、 `apple OR orange` と検索すると*OR条件*で検索する。 |
### 3.5. 各種検索設定
#### 3.5.1 各種検索設定: 検索件数
***(概要)*** *1ページ毎の最大表示件数を指定する。*
| No | 項目キー | 型 | デフォルト値 | 内容 |
|:--:|:---------------------------------|:---------|:--------------|:-----------------------------------------------------------------|
| 1 | search_result_items_per_page | Integer | 20 | 1ページ当たりの検索結果表示件数。 |
#### 3.5.2 各種検索設定: 検索結果並び順
***(概要)*** *デフォルトの検索結果並び順を指定する。*
| No | 項目キー | 型 | デフォルト値 | 内容 |
|:--:|:---------------------------------|:---------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------|
| 1 | search_order_base_1 | String | ordering:asc | 優先順1位の並び順指定。`属性キー`:`方向` の形で指定する。 Ex) `item_id:asc` (item_idの昇順), `item_price:desc` (item_priceの降順) |
| 2 | search_order_base_2 | String | - | 優先順2位の並び順指定。`属性キー`:`方向` の形で指定する。 Ex) `item_id:asc` (item_idの昇順), `item_price:desc` (item_priceの降順) |
| 3 | search_order_base_3 | String | - | 優先順3位の並び順指定。`属性キー`:`方向` の形で指定する。 Ex) `item_id:asc` (item_idの昇順), `item_price:desc` (item_priceの降順) |
| 4 | `search_order_base_<数値>` | String | - | 優先順<数値>位の並び順指定。<数値>に指定可能なのは、1〜10。 |
※ `search_order_base_1` にはデフォルト値(ordering:asc)が設定されていますが、任意に上書きして設定変更可能です。
### 3.6 各種操作設定
#### 3.6.1 各種操作設定: 上限件数
| No | 項目キー | 型 | デフォルト値 | 内容 |
|:--:|:---------------------------------|:---------|:--------------|:----------------------------------------------------------|
| 1 | search_compare_item_max | Integer | 10 | 検索結果画面から比較対象として選択できるアイテム数の上限 |
| 2 | compare_pdf_item_max | Integer | 10 | 比較画面で、PDF出力できるアイテム数の上限 |
| 3 | compare_csv_item_max | Integer | 10 | 比較画面で、CSV出力できるアイテム数の上限 |
| 4 | compare_excel_item_max | Integer | 10 | 比較画面で、Excel出力できるアイテム数の上限 |
| 5 | compare_print_item_max | Integer | 10 | 比較画面で、印刷出力できるアイテム数の上限 |
## 改訂履歴
- 2023.01.16: [3.6. 各種操作設定](#3-6-) 追加
- 2023.01.16: [3.5. 各種検索設定](#3-5-) 追加