付録 - 技術仕様

A. 確認画面の自動生成

入力画面に [フォームID]-b-confirm クラスが指定された確認ボタンが存在すると、espar form は解析したフォームの内容から確認画面を自動生成します。自動生成時は、自然な確認画面になるように様々な表示加工処理が行われています。以下に、自動生成時の表示上の加工について仕様を示します。

確認画面の自動生成時に行っていること（共通）

入力要素(input, select, textarea)は非表示にする（inner style sheet で display: none; を自動指定する）
入力要素の class は全て引き継ぐ
入力要素の直後に以下の内容の span 要素を自動的に追加する

<span class="[フォームID]-c-[入力要素のname値]">[入力値]</span>

確認画面の自動生成時に行っていること（入力要素ごと）

<form>タグ内の要素ごとによって、以下のような処理を行っています。

■ パスワード入力フィールド : <input type=“password”>

パスワードが見えてしまうのを避けるため、入力文字を入力された文字数の *（アスタリスク）に置換して表示

■ テキストエリア : <textarea>

改行コードを <br /> に置換して表示

■ <input type=“checkbox”> , <input type=“radio”>

選択した項目に対応する <label for=“”> のテキストを , (カンマ) で区切って並べて表示
区切り文字は , (カンマ) がデフォルト (変更可。詳細はグローバルオブジェクトの delimiter の解説を参照のこと)

■ <select>

選択した <option> 項目のテキストを , (カンマ) で区切って並べて表示
, (カンマ) 以外に変更可。以下の指定があればそれを採用する
- グローバルオブジェクトに定義された delimiter_[name値] の文字列
- グローバルオブジェクトに定義された delimiter の文字列

B. グローバルオブジェクト

グローバルオブジェクト espar_form の全仕様を以下に示します。(2018.10.09現在)

グローバルオブジェクト espar_form の全要素

espar_form: {
    "フォームID" : {
        // ホスト毎に指定された40桁の英数字文字列。必須
        api_key: "APIキー",

        // デバッグ表示をするかどうか、またその出力レベル
        debug: true,
        log_level: "INFO",

        // 複数入力項目を確認画面で表示するときのデリミタ（全項目用と個別項目用）        
        delimiter: ",",
        delimiter_プロパティ名: "<br>",

        // 送信完了画面にフォームを表示し続けるかを定義
        keep_displayed: false,

        // 各種コールバック
        input_ready_callback: function() {...},
        confirm_ready_callback: function() {...},
        validation_failure_callback: function() {...},
        submit_success_callback: function() {...},
        submit_failure_callback:    function() {...},

        // バリデーションエラーが起こった箇所を示す配列
        validation_errors: Array(),

        // フォーム設定をリロードするための関数（espar-form エンジンが追加する）
        reload_form_config: function()
    },

    // ２つ目以降のフォーム
    "esparフォームID2": {
        ...
    }
}

各要素の説明

要素	必須	説明
フォームID	○	espfで始まる任意の文字列。esparフォームオブジェクトに対するキー。 <form>タグに指定したclass属性に一致している必要がある
api_key	○	弊社より指定したAPIキー。40桁の英数字。ホスト名毎に異なる一位の値
debug		true指定でコンソールログにデバッグ情報を表示
log_level		debugがtrueの時のみ有効。デバッグ情報のレベルを指定する。詳しくは応用編4 - デバッグとテストを参照のこと
delimiter		チェックボックスや複数選択リストボックスの値を確認画面に表示する時に使用フォーム内の全ての複数要素に適用。複数の被選択項目の区切り文字
delimiter_[name値]		上記と同じ機能だが、適用する入力要素を明示的に指定する時に仕様する指定したい要素のname属性の値を指定する
keep_displayed		送信完了時に直前の入力内容確認内容を表示し続ける時にtrueを指定。未指定時はfalse
input_ready_callback		入力画面が表示されきって準備が完了した直後のコールバック関数
confirm_ready_callback		確認画面が表示されきって準備が完了した直後のコールバック関数
validation_failure_callback		入力項目にエラーがあった時にエラーを表示した直後
submit_success_callback		送信が成功して完了した直後のコールバック関数
submit_failure_callback		送信が失敗で終わった直後のコールバック関数
validation_errors		入力項目にエラーがあった時にエラー発生箇所の配列
reload_form_config		フォームの要素が動的に変化した直後に呼び出す必要のある関数。フォーム要素を再評価する関数を格納するプレースホルダとして機能する。フォームの要素が動的に変化しない場合は宣言不要

C. コールバック

espar form では、[入力]→[確認]→[完了] の画面遷移の各段階で独自の処理を挿入できるコールバックを使用できます。

コールバックの種類

コールバック関数名	コールバックが呼ばれるタイミング
input_ready_callback	入力画面が表示されきって準備が完了した直後
confirm_ready_callback	確認画面が表示されきって準備が完了した直後
validation_failure_callback	入力項目にエラーがあった時にエラーを表示した直後
submit_success_callback	送信が成功して完了した直後
submit_failure_callback	送信が失敗で終わった直後

コールバックの使用方法

専用埋め込みコード中のグローバルオブジェクト espar_form を、

<script>
    var espar_form = { espf: { api_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } };
</script>

以下のように、コールバック名をキーとした関数を指定します。

<script>
    var espar_form = {
        espf: {
            api_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            submit_success_callback: function() {
                // 送信が成功で終わった直後の処理
                console.log("success");
            }
        }
    }
</script>

複数同時に指定することも可能です。

<script>
    var espar_form = {
        espf: {
            api_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            input_ready: function() {
                // 入力画面が表示されて準備完了した直後の独自処理
                console.log("input_ready");
            },
            submit_success_callback: function() {
                // 送信が成功で終わった直後の処理
                console.log("success");
            }
        }
    }
</script>

コールバック validation_failure_callback について

入力項目で指定された入力チェッククラスの条件が満たされない場合、エラーが発生してエラー文言が表示されます。エラー表示の直後に呼ばれるコールバック関数 validation_failure_callback です。

validation_failure_callback がコールバックで呼ばれた時、グローバルオブジェクト内の validation_erros (espf_form.espf.validation_errors) を参照すると、どの要素でエラーが発生したかを示す配列を得ることができます。以下がその例です。

espf-e-name
espf-e-name-required

name属性がnameの入力要素に必須項目チェックのエラーがある(つまり、必須項目なのに入力されていない)ことを示しています。

D. 動作条件

espar form の動作条件は以下の通りです。

使用ライブラリ


jQuery	1.7以上（3.0系を含む）
jQuery Validation Plugin	1.14.0以上、最新版を推奨 jQuery3.0以上を使用するときは1.16.0以上が必要

対応ブラウザ

使用するjQueryに依存します。詳細は jQuery のサポートブラウザページを御覧下さい。

E. フォーム要素ガイドライン

espar form では、[入力]→[確認]→[完了] の画面遷移を全て自動で行えるよう、各フォーム要素が html の仕様に則って使用されていることを前提としています。

<form>内の各入力要素は、ユーザに入力させる要素特性にあった適切な要素を使用するようにして下さい。以下に入力内容毎にガイドラインを示します。

入力用途	期待する input type や要素
2つ以上の選択肢からただ一つを選択	input type=“radio” または select 要素
はい/いいえなど2つの選択肢からどちらかを選択	input type=“radio” または select 要素
2つ以上の選択肢から複数を選択	input type=“checkbox” または multiple 属性付きの select 要素
パスワード文字列	input type=“password”
複数行のテキスト	textarea要素
送信ボタン	input type=“button” または button