イベントの記述方法

コラボフォーム JavaScript APIを利用する際のイベントの記述方法について説明します。

イベントの記述方法

コラボフォームのフォーム画面で発生する様々なイベントをイベントハンドラー関数により検知し、指定したカスタマイズ処理を実行することができます。

関数

collaboform.events.on(eventName, function(data));

引数

引数名	指定する値	必須	説明
eventName	文字列または文字列の配列	必須	対象のイベント名、もしくはイベント名の配列を指定します。配列を指定した場合は、配列で指定された全てのイベントが対象となります。
handler	function(data)	必須	イベント発生時に実行されるハンドラーを指定します。「data」 オブジェクトには、イベントのデータが返ります

記述例

// フォーム入力画面を開いた際のイベント
collaboform.events.on('form.show', function(data) { });

// 確認ボタンが押された際のイベント
collaboform.events.on('form.confirm', function(data) { });

// 複数のイベントに同じハンドラーを登録する（配列指定）
collaboform.events.on(['form.confirm', 'form.submit'], function(data) { });

イベントハンドラー共通の戻り値

イベントハンドラーに渡される 「data」 オブジェクトの共通プロパティです。
イベントによっては、下記の共通プロパティに加えイベント独自のプロパティが返されます。

プロパティ名	説明	タイプ
event_name	発生したイベント名	string
parts	パーツ値情報	object
parts_id	変更されたパーツのID ※「form.<パーツID>.change」 イベント時のみ取得可能	string
row_index	行インデックス ※明細に配置したパーツの変更イベント時のみ取得可能 ※1行目の場合は 「1」 が返ります。	number
table_id	テーブル ID ※明細に配置したパーツの変更イベント時のみ取得可能 ※コラボフォームでは「tbl_1」固定	string

イベントオブジェクト内の partsプロパティには、下記のパーツ情報オブジェクトが格納されます。

parts オブジェクトの例

parts: {
    fid1: {
        'value': 'これはサンプルです',
        'type': 'text',
        'enabled': true,
        'display': true,
    },
    fid2: {
        'value': '選択肢A',
        'type': 'list',
        'enabled': true,
        'display': true,
    }
}

parts オブジェクトのプロパティ

プロパティ	説明	型
value	パーツの値	any
type	パーツのタイプ	string
enabled	パーツが入力可能であれば 「true」、不可であれば 「false」	boolean
display	パーツが表示状態であれば 「true」、非表示であれば 「false」	boolean

補足

• イベントハンドラー内の処理でpartsオブジェクトのvalue値を書き換えると、その変更がフォームに反映されます。
• 画面表示時にパーツが表示されている場合は、イベントハンドラー内の処理でparts オブジェクトのdisplay値を書き換えて、パーツの表示/非表示を変更することができます。

制限事項

• コラボフォームに対応していないパーツ（時刻パーツ・画像パーツ）はpartsオブジェクトに含まれません。（イベントの操作対象外です）
• 「parts」オブジェクトの「enabled」値は取得のみ可能です。enabled値を設定してパーツの有効/無効状態を変更することはできません。
• 「form.confirm.show」「form.submit」およびフォーム詳細画面（form.view）では、partsオブジェクトのvalue値を書き換えてパーツ値の変更を行うことはできません。
• カスタムJavaScriptファイルはフォーム画面のDOMが確定する前に読み込まれます。イベントハンドラーの外に処理を記述すると、フォームの要素がまだ存在しないため正常に動作しない場合があります。