espar form の技術仕様

A. 確認画面の自動生成

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

 

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

  • 入力要素(input, select, textarea)は非表示にする（inner style sheet で display: none; を自動指定する）
  • 入力要素の class は全て引き継ぐ
  • 入力要素の直後に以下の内容の span 要素を自動的に追加する
<span class="[フォームID]-c-[入力要素のname値]">[入力値]</span>

自動生成におけるinput要素要件

input要素には必ず type 属性を指定して下さい。 espar form では input 要素の検出後に type 属性に応じた自動処理を行います。type 属性の指定がない input 要素は、確認画面で入力値が表示されない状態となってしまいます。

 

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

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

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

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

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

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

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

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

■ <select>

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

 

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

導入基礎編で解説した espar form の埋め込みコードは以下のようなものでした。

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

デフォルト表記はシンプルなものですが、espar_form グローバルオブジェクトは espar form を高度に制御することのできる key value を多数備えた巨大なオブジェクトです。グローバルオブジェクト espar_form の全仕様を以下に示します。

 

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

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

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

        // hidden 指定された要素も入力チェックするかどうか
        validate_hidden_element: false,

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

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

        // 各種コールバック
        input_ready_callback: function() {...},         // 入力画面が表示されきった後
        confirm_ready_callback: function() {...},       // 確認画面が表示されきった後
        validation_success_callback: function() {...},  // 入力画面でエラーがなかった時
        validation_failure_callback: function() {...},  // 入力画面でエラーがあった時
        submit_success_callback: function() {...},      // 送信が成功して完了した直後
        submit_failure_callback: function() {...},      // 送信が失敗して終了した直後
        back_clicked_callback: function() {...},        // 確認画面の戻るのクリック直後
        submit_clicked_callback: function() {...},      // 送信ボタンが押された直後
        confirm_clicked_callback: function() {...},     // 確認ボタンが押された直後

        // ページトップヘの自動スクロール
        top_on_confirm: false,
        top_on_success: false,
        top_on_failure: false,

        // 指定要素への自動スクロール
        scroll_on_back: "要素のセレクタ",       // 戻るボタン押下時に指定した要素が最上部になるように画面をスクロールする
        scroll_on_confirm: "要素のセレクタ",     // 確認画面表示時に指定した要素が最上部になるように画面をスクロールする
        scroll_on_success: "要素のセレクタ",     // 送信成功時に指定した要素が最上部になるように画面をスクロールする (submit_success_url 指定時は使用されない）
        scroll_on_failure: "要素のセレクタ",     // 送信失敗時に指定した要素が最上部になるように画面をスクロールする (submit_failure_url 指定時は使用されない）

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

        // バリデーションエラーが発生した時に付与するクラス名
        validation_error_class: "クラス名",

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

        // 送信中を表す indicator アイコンをオーバレイ表示する
        spinner_on_submit: true,

        // 指定イベントの発生でバリデーションを実行する
        validate_on_focusout: true,     // フォーム要素からフォーカスが外れたらバリデーションを実行する
        validate_on_keyup: true         // フォーム要素でキー入力する度にバリデーションを実行する
    },

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

上記の通り espar_form は、フォームIDをキーとする設定オブジェクト列です。デフォルトで指定されている api_key のほか、フォームIDごとに様々な設定が可能です。全設定の詳細を以下に示します。必要なもののみ宣言して使用して下さい。

 

各要素の説明

要素 必須 説明
フォームID ○ espfで始まる任意の文字列。esparフォームオブジェクトに対するキー。
<form>タグに指定したclass属性に一致している必要がある
api_key ○ 弊社より指定したAPIキー。40桁の英数字。ホスト名毎に異なる一位の値
debug true指定でコンソールログにデバッグ情報を表示
config_test ONにすると espar form をコンフィグテストモードで起動する。espar form クラス指定の正誤チェックのいを行い結果をコンソールに出力する。コンフィグモードでは、メール送信は行われないので 本番環境で絶対に true にしない こと
log_level debugがtrueの時のみ有効。デバッグ情報のレベルを指定する。詳しくは 応用編4 - デバッグとテスト を参照のこと
validate_hidden_element input要素等でhiddenを指定されている項目も入力チェックを行う場合にtrueにする。チェックボックスやラジオボタンの見た目をCSSで変更している場合、入力チェックが正しく動作しない場合がある。その時に本フラグをtrueにすること
delimiter チェックボックスや複数選択リストボックスの値を確認画面に表示する時に使用
フォーム内の全ての複数要素に適用。複数の被選択項目の区切り文字
delimiter_[name値] 上記と同じ機能だが、適用する入力要素を明示的に指定する時に仕様する
指定したい要素のname属性の値を指定する
keep_displayed 送信完了時に直前の入力内容確認内容を表示し続ける時にtrueを指定。未指定時はfalse
input_ready_callback 入力画面が表示されきって準備が完了した直後のコールバック関数
confirm_ready_callback 確認画面が表示されきって準備が完了した直後のコールバック関数
validation_success_callback 入力項目にエラーがなかった時に完了画面に遷移する直前。コールバック関数内で明示的に return false; するとボタンクリックイベントをキャンセルできる
validation_failure_callback 入力項目にエラーがあった時にエラーを表示した直後
submit_success_callback 送信が成功して完了した直後のコールバック関数
submit_failure_callback 送信が失敗で終わった直後のコールバック関数
back_clicked_callback 確認画面の戻るボタンがクリックされた直後のコールバック関数。コールバック関数内で明示的に return false; するとボタンクリックイベントをキャンセルできる
submit_clicked_callback 送信ボタンがクリックされた直後のコールバック関数。コールバック関数内で明示的に return false; するとボタンクリックイベントをキャンセルできる
confirm_clicked_callback 確認ボタンがクリックされた直後のコールバック関数。コールバック関数内で明示的に return false; するとボタンクリックイベントをキャンセルできる
top_on_confirm 確認画面でページのトップへスクロールする
タイミングは confirm_ready_callback のコールバック関数を実行する直前
top_on_success 送信に成功したらページのトップへスクロールする
タイミングは submit_success_callback のコールバック関数を実行する直前
top_on_failure 送信に失敗したらページのトップへスクロールする
タイミングは submit_failure_callback のコールバック関数を実行する直前
scroll_on_back 戻るボタン押下時に指定した要素が最上部になるように画面をスクロールする
scroll_on_confirm 確認画面表示時に指定した要素が最上部になるように画面をスクロールする
scroll_on_success 送信成功時に指定した要素が最上部になるように画面をスクロールする (submit_success_url 指定時は使用されない）
scroll_on_failure 送信失敗時に指定した要素が最上部になるように画面をスクロールする (submit_failure_url 指定時は使用されない）
validation_errors 入力項目にエラーがあった時にエラー発生箇所の配列
validation_error_class 入力項目にエラーがあった時に入力項目に自動的に付与されるクラス名
reload_form_config フォームの要素が動的に変化した直後に呼び出す必要のある関数。フォーム要素を再評価する関数を格納するプレースホルダとして機能する。フォームの要素が動的に変化しない場合は宣言不要
spinner_on_submit 送信中を表す indicator アイコンをオーバレイ表示する
validate_on_focusout 送信や確認ボタンクリックではなく、フォーム要素からフォーカスが外れた時にその要素のバリデーションを実行する
validate_on_keyup 送信や確認ボタンクリックではなく、フォーム要素でキー入力される度にその要素のバリデーションを実行する

C. コールバック

B. グローバルオブジェクト に記載の通り、espar form は[入力]→[確認]→[完了] の画面遷移の各段階で使用できるコールバック関数を備えています。独自の JavaScript を書くことでフォームの振る舞いを制御することができます。

 

コールバックの使用方法

専用埋め込みコード中のグローバルオブジェクト 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 では、[入力]→[確認]→[完了] の画面遷移を全て自動で行えるよう、各フォーム要素が 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