IM-FormaDesigner / IM-BIS クライアントサイドスクリプトAPIまとめ

## 対象
- intra-mart Accel Platform 2018 Winter調べ
- IM-FormaDesiner / IM-BIS
- カスタムスクリプト（JavaScript）

## 情報元
### 公式ドキュメント IM-BIS仕様書
安心して使えます。intra-mart公式問い合わせ可能。
IM-BIS for Accel Platform IM-BIS 仕様書 クライアントサイドスクリプトAPI
https://www.intra-mart.jp/document/library/bis/public/bis_specification/texts/spec/csjs_script.html

### Developer Site
Developer Siteにしか載っていないAPIです。Developer Site内容については公式サポートの取り扱いにはならないためサポートなしです。
自己責任で使用することになります。間違ったことは書いていない、APIも長年変更がないため大体安心して使えます。
https://www.intra-mart.jp/support/information/texts/infolist/index.html

intra-mart Developer Site Formaでのスクリプト開発生産性向上
https://dev.intra-mart.jp/forma_2/

intra-mart Developer Site Formaボタンアイテムのクリック時に任意の処理を追加するには
https://dev.intra-mart.jp/post-434/

### 非公開
非公開API。もちろんサポートなしなので取り扱い注意。自己責任で使用してください。
ソース読むと変なことは書いてないですし、自分で同じ動きを実現しようとしても似たようなコードになるので非公開でもAPI使っておいたほうが良いケースが多いです。
スマホ版とPC版対応になるのが一番のメリットでしょうか。内部動作実現のために使われているので動きは確かなはず。


# クライアントサイドスクリプトAPI一覧
## 公式ドキュメント IM-BIS仕様書 記載API
#### 概要
| API概要 | API |
| --- | --- |
| 画面アイテム 値取得 | formaItems.%画面アイテムID%.getItemData.%フィールド識別ID%() |
| 画面アイテム 値設定 | formaItems.%画面アイテムID%.setItemData.%フィールド識別ID%(object arg) |

#### 詳細
---
##### <font color="Green">画面アイテム 値取得</font>
<dl>
  <dt><font color="Blue">object</font> formaItems.<font color="Crimson">%画面アイテムID%</font>.getItemData.<font color="Crimson">%フィールド識別ID%</font>()</dt>
  <dd>指定されたフィールド識別IDのコントロールより入力値を取得します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">object</font></dt>
  <dd>画面アイテムIDによって異なる型で取得される。別画面アイテムでの取得方法は公式ドキュメント参照。</dd>
</dl>
```Javascript:画面アイテム値取得
// 画面アイテムID：product_72_textbox
// フィールド識別ID：textbox1
var data = formaItems.product_72_textbox.getItemData.textbox1();
// 結果：戻り値dataにはtextbox1入力値がstring型で入る
```
---
##### <font color="Green">画面アイテム 値設定</font>
<dl>
  <dt><font color="Blue">void</font> formaItems.<font color="Crimson">%画面アイテムID%</font>.setItemData.<font color="Crimson">%フィールド識別ID%</font>(object <font color="Crimson">arg</font>)</dt>
  <dd>指定されたフィールド識別IDのコントロールより入力値を取得します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">arg</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">arg.data</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">arg.data.%フィールド識別ID%</font>：<font color="Gray">string</font></dd>
  <dd>基本はこの形ですが、画面アイテムごとに細かいパラメータは変わってきます。詳しくは公式ドキュメント参照。</dd>
</dl>
```Javascript:画面アイテム値設定
// 画面アイテムID：product_72_textbox
// フィールド識別ID：textbox1
var arg = {};
arg.data = {};
arg.data.textbox1 = 'サンプルテキスト';
formaItems.product_72_textbox.setItemData.textbox1(arg);
// 結果：texbox1にサンプルテキストが設定される
```


##DeveloperSite記載API
#### 概要
| API概要 | API |
| --- | --- |
| 画面アイテム 入力モード変更 | formaItems.%画面アイテムID%.changeInputMode(object controlSetting) |
| ボタン（申請・登録）処理 | sendRegistData() |
| ボタン（一時保存）処理 | sendPreserveData(inputCheckFlag) |
| ボタン（次へ）処理 | sendNextForm() |
| ボタン（戻る）処理 | sendBackForm() |
| ボタン（一覧へ戻る）処理 | sendBack() |

#### 詳細
---
##### <font color="Green">画面アイテム 入力モード変更</font>
<dl>
  <dt><font color="Blue">void</font> formaItems.<font color="Crimson">%画面アイテムID%</font>.changeInputMode(object <font color="Crimson">controlSetting</font>)</dt>
  <dd>入力アイテムの入力不可・入力可状態を切り替えるためのAPI。指定可能なアイテムはIM-BIS仕様書参照</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">controlSetting</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">controlSetting.mode </font>：<font color="Gray">string</font> 入力モード</dd>
  <dd><font color="Crimson">controlSetting.inputId</font>：<font color="Gray">string</font> フィールド識別ID</dd>
  <dd>基本はこの形ですが、画面アイテムごとに細かいパラメータは変わってきます。詳しくはDeveloperSite参照。</dd>
</dl>
```Javascript:画面アイテム入力モード変更
// 画面アイテムID：product_72_textbox
// フィールド識別ID：textbox1
var controlSetting = {};
controlSetting.mode = "invalid"; // 入力可 valid・入力不可 invalid
controlSetting.inputId  = 'textbox1';
formaItems.product_72_textbox.changeInputMode(controlSetting);
// 結果：texbox1が入力不可になる
```
---
##### <font color="Green">ボタン（申請・登録）処理</font>
<dl>
  <dt><font color="Blue">void</font> sendRegistData()</dt>
  <dd>申請・登録処理を呼び出します。申請・登録前に処理を挟むときに使用します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---
##### <font color="Green">ボタン（一時保存）処理</font>
<dl>
  <dt><font color="Blue">bool</font> sendPreserveData(string <font color="Crimson">inputCheckFlag</font>)</dt>
  <dd>一時保存処理を呼び出します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">bool</font></dt>
  <dd><font color="Blue">true</font>：一時保存成功</dd>
  <dd><font color="Blue">false</font>：一時保存失敗</dd>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">inputCheckFlag</font>：<font color="Gray">string</font></dd>
  <dd>'0' ：最低限のチェック </dd>
  <dd>'0'以外 ：入力チェックをフルで実行 </dd>
  <dd>inputCheckFlagが'0'の場合は、数値チェックなどシステムエラーを発生させないための最低限の入力チェックのみが実行されます。</dd>
</dl>
---
##### <font color="Green">ボタン（次へ）処理</font>
<dl>
  <dt><font color="Blue">void</font> sendNextForm()</dt>
  <dd>フォーム遷移設定で指定されている次のフォームへの遷移処理を呼び出します。</dd>
  <dd>子画面遷移については、対象外となります。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---
##### <font color="Green">ボタン（戻る）処理</font>
<dl>
  <dt><font color="Blue">void</font> sendBackForm()</dt>
  <dd>フォーム遷移設定で指定されている一つ前のフォームへの遷移処理を呼び出します。</dd>
  <dd>子画面遷移については、対象外となります。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---
##### <font color="Green">ボタン（一覧へ戻る）処理</font>
<dl>
  <dt><font color="Blue">void</font> sendBack()</dt>
  <dd>一覧画面への遷移処理を呼び出します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---


##非公開API
#### 概要
| API概要 | API |
| --- | --- |
| 入力チェック実行 | inputCheck (inputCheck, temporaryFlag, formId, transitionOrderNo) |
| エラー情報クリア関数 | formaClearError() |
| エラー情報表示 | showErrorInfo(result) |
| 項目エラー表示 | formaItems.%画面アイテムID%.AcceptError(event) |
| 項目エラー表示クリア | formaItems.%画面アイテムID%.ClearError(event) |
| 印刷 | printPage() |
| インジケータ表示 | formaIndicator(target, mode) |
| アラートメッセージ表示 | formaShowMessage(message, detailMessage) |
| グリッドテーブル 列定義取得 | formaItems.product_80_gridtable.getColInfo[tableId] |
| グリッドテーブル 関数式実行 | formaItems.product_80_gridtable.doTableExpression(tableId) |

#### 詳細
---
##### <font color="Green">入力チェック実行</font>
<dl>
  <dt><font color="Blue">bool</font> inputCheck (string <font color="Crimson">inputCheck</font>, bool <font color="Crimson">temporaryFlag</font>, string <font color="Crimson">formId</font>, string <font color="Crimson">transitionOrderNo</font>)</dt>
  <dd>クライアントサイドからサーバーサイド入力チェックを実行し結果を取得します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">bool</font></dt>
  <dd><font color="Blue">true</font>：入力エラーなし</dd>
  <dd><font color="Blue">false</font>：入力エラーあり</dd>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">inputCheck</font>：<font color="Gray">string</font></dd>
  <dd>'0'、引数省略：入力チェックプログラムを動作させない</dd>
  <dd>'0'以外：入力チェックプログラムを動作させる</dd>
  <dd><font color="Crimson">temporaryFlag</font>：<font color="Gray">bool</font></dd>
  <dd>true：一時保存時の入力チェックを実行</dd>
  <dd>false、引数省略：通常保存時の入力チェックを実行</dd>
  <dd><font color="Crimson">formId</font>：<font color="Gray">string</font></dd>
  <dd>入力チェック対象formIdを指定する</dd>
  <dd>省略時、現在form指定</dd>
  <dd><font color="Crimson">transitionOrderNo</font>：<font color="Gray">number</font></dd>
  <dd>画面遷移番号を指定する。省略時現在番号</dd>
</dl>
```Javascript:入力チェック実行
var isError = inputCheck('1');
// 結果：申請・登録処理なしでサーバーサイド入力チェックが行われ、結果がisErrorに返却
```
---
##### <font color="Green">エラー情報クリア</font>
<dl>
  <dt><font color="Blue">void</font> formaClearError()</dt>
  <dd>エラー表示エリアのクリアとコントロールのエラー表示クリア処理を行います。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---
##### <font color="Green">エラー情報表示</font>
<dl>
  <dt><font color="Blue">void</font> showErrorInfo (object <font color="Crimson">result</font>)</dt>
  <dd>入力エラーを表示します。画面上部エラーエリア、各コントロール対象。</dd>
  <dd>エラー有無の判定は行わず、エラーメッセージ表示のみを行います。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">result</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">result.message</font>：<font color="Gray">object</font></dd>
  <dd>画面上部のエラーメッセージ。改行コードを含めると改行表示される。</dd>
  <dd><font color="Crimson">result.errorInfo[type][itemId]</font>：<font color="Gray">array</font></dd>
  <dd>エラー内容。画面アイテムID毎、フィールド識別ID毎の配列となっている</dd>
  <dd>　</dd>
</dl>
---
##### <font color="Green">項目エラー表示</font>
<dl>
  <dt><font color="Blue">void</font> formaItems.<font color="Crimson">%画面アイテムID%</font>.AcceptError(object <font color="Crimson">event</font>)</dt>
  <dd>画面項目エラー表示を行います。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">event</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">event.inputId</font>：<font color="Gray">string</font> フィールド識別ID</dd>
</dl>
```Javascript:項目エラー表示
// 画面アイテムID：product_72_textbox
// フィールド識別ID：textbox1
var event = {};
event.inputId  = 'textbox1';
formaItems.textbox1.AcceptError(event);
// 結果：texbox1が入力エラーありコントロールとして表示される
```
---
##### <font color="Green">項目エラー表示クリア</font>
<dl>
  <dt><font color="Blue">void</font> formaItems.<font color="Crimson">%画面アイテムID%</font>.ClearError(object <font color="Crimson">event</font>)</dt>
  <dd>画面項目エラー表示をクリアします。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">event</font>：<font color="Gray">object</font></dd>
  <dd><font color="Crimson">event.inputId</font>：<font color="Gray">string</font> フィールド識別ID</dd>
</dl>
```Javascript:項目エラー表示クリア
// 画面アイテムID：product_72_textbox
// フィールド識別ID：textbox1
var event = {};
event.inputId  = 'textbox1';
formaItems.textbox1.ClearError(event);
// 結果：texbox1の入力エラー表示がクリアされる
```
---
##### <font color="Green">印刷</font>
<dl>
  <dt><font color="Blue">void</font> printPage()</dt>
  <dd>FormaのPDF出力機能にてフォームをPDF出力します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
</dl>
---
##### <font color="Green">インジケータ表示</font>
<dl>
  <dt><font color="Blue">void</font> formaIndicator(string <font color="Crimson">target</font>, bool <font color="Crimson">mode</font>)</dt>
  <dd>インジケーターのON OFFを行います。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">target</font>：<font color="Gray">string</font> セレクタ</dd> 
  <dd><font color="Crimson">mode</font>：<font color="Gray">bool</font> </dd>
  <dd>true：インジケーターのON</dd>
  <dd>false：インジケーターのOFF</dd>
</dl>
```Javascript:インジケーターのON
formaIndicator($('#form_area'), true);
// 結果：処理中を示すインジケーターが表示される
```

---
##### <font color="Green">アラートメッセージ表示</font>
<dl>
  <dt><font color="Blue">void</font> formaShowMessage(string <font color="Crimson">message</font>, string <font color="Crimson">detailMessage</font>)</dt>
  <dd>アラートメッセージ表示を行います。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">message</font>：<font color="Gray">string</font> メッセージ</dd> 
  <dd><font color="Crimson">detailMessage</font>：<font color="Gray">string</font> 詳細メッセージ</dd>
</dl>
---
##### <font color="Green">グリッドテーブル 列定義取得</font>
<dl>
  <dt><font color="Blue">array</font> formaItems.product_80_gridtable.getColInfo[<font color="Crimson">tableId</font>]</dt>
  <dd>グリッドテーブル 列定義取得を取得します。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">array</font></dt>
  <dd><font color="Blue">array[i]</font>：<font color="Gray">object</font> 列情報</dd>
  <dd><font color="Blue">array[i].inputId</font>：<font color="Gray">string</font> 列のフィールド識別ID</dd>
  <dd><font color="Blue">array[i].inputItemType</font>：<font color="Gray">string</font> 列の画面アイテムID</dd>
  <dd><font color="Blue">array[i].inputFlag</font>：<font color="Gray">string</font> 列の入力可否フラグ</dd>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">tableId</font>：<font color="Gray">string</font> グリッドテーブルID</dd> 
</dl>

```Javascript:グリッドテーブル列定義取得
// テーブル識別ID：gt1
var colInfo = formaItems.product_80_gridtable.getColInfo['gt1'];
// 結果：gt1の列定義情報が取得される
```
---
##### <font color="Green">グリッドテーブル 関数式実行</font>
<dl>
  <dt><font color="Blue">void </font> formaItems.product_80_gridtable.doTableExpression(<font color="Crimson">tableId</font>)</dt>
  <dd>グリッドテーブル内の関数式を再評価します。</dd>
  <dd>グリッドテーブル内コントロールクリア時など関数式が評価されない</dd>
  <dd>タイミングがありますが、これで対処できます。</dd>
  <dd>　</dd>
  <dt>戻り値 <font color="Blue">なし</font></dt>
  <dd>　</dd>
  <dt>パラメータ</dt> 
  <dd><font color="Crimson">tableId</font>：<font color="Gray">string</font> グリッドテーブルID</dd> 
</dl>
```Javascript:グリッドテーブル関数式実行
// テーブル識別ID：gt1
formaItems.product_80_gridtable.doTableExpression('gt1');
// 結果：gt1の関数が再実行される
```
---

##使用例
IM-FormaDesigner / IM-BISで先頭空白行ありセレクトボックス ドリルダウン処理実装
https://qiita.com/doriburu/items/dd578f9276f25c7a984e

IM-FormaDesigner / IM-BIS セレクトボックス Option値をAPIで設定する
https://qiita.com/doriburu/items/639e7104ac33911c0e1c

IM-FormaDesigner クライアントサイドスクリプトで入力チェックエラー時の強調表示をON OFFする
https://qiita.com/doriburu/items/9171c18f28800228191c

##グリッドテーブルと明細テーブルについて
グリッドテーブルはJqgirdを使っている。JqgridのAPIを使って制御する方法もある。
http://www.trirand.com/jqgridwiki/doku.php

明細テーブルはjQueryUI sortableを使っている。これもjQueryUI sortableのAPIを使って制御しても良い。
https://api.jqueryui.com/sortable/

実装例が下記にある
https://qiita.com/doriburu/items/22a41bc287866dbc57a3