Skip to content
espar form espar form espar form DOCS

コールバック

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_callback: function() {
                // 入力画面が表示されて準備完了した直後の独自処理
                console.log("input_ready");
            },
            submit_success_callback: function() {
                // 送信が成功で終わった直後の処理
                console.log("success");
            }
        }
    }
</script>

コールバック関数仕様

espar form では以下のコールバックが使用できます。

コールバック概要
input_ready_callback入力画面準備完了時に呼び出されるコールバック
confirm_ready_callback確認画面が表示され準備が整ったタイミングで呼び出されるコールバック
validation_success_callbackバリデーション成功直後に呼び出されるコールバック
validation_failure_callbackバリデーションエラー発生直後に呼び出されるコールバック
submit_success_callback送信成功後、完了画面の初期化が終わった時に呼び出されるコールバック
submit_failure_callback送信失敗後、エラー表示が整った時に呼び出されるコールバック
back_clicked_callback確認画面の戻るボタンクリック時に呼び出されるコールバック
confirm_clicked_callback確認ボタンクリック時に呼び出されるコールバック
submit_clicked_callback送信ボタンクリック時に呼び出されるコールバック

input_ready_callback

引数

なし

呼び出しタイミング

  • フォームのトークンが正常に取得された後
  • ボタンが有効化され、ユーザーの入力を受け付ける準備が完了した時

confirm_ready_callback

引数

なし

呼び出しタイミング

  • バリデーションが成功し確認画面が表示された後
  • 設定されたスクロール処理（top_on_confirm や scroll_on_confirm）が終了した後

validation_success_callback

引数

なし

呼び出しタイミング

  • フォームバリデーションが成功した直後
  • フォーム送信処理または確認画面への遷移が始まる前

備考

戻り値で false を返すと、以降の送信処理や画面遷移をキャンセルできます。確認画面を挟まずに独自処理へ遷移させたい場合などに利用します。

validation_failure_callback

引数

なし

呼び出しタイミング

  • フォームバリデーションが失敗した後
  • バリデーションエラーのUIが表示された後

備考

入力項目で指定された入力チェッククラスの条件が満たされない場合、エラー文言を表示した直後に validation_failure_callback が呼び出されます。コールバック内で espar_form.フォームID.validation_errors を参照すると、エラーとなった要素の配列を得られます。以下は使用例です。

validation_failure_callback: function () {
    $.each(espar_form.espf.validation_errors, function (i, e) {
        console.log(e);
    });
}

submit_success_callback

引数

formId (文字列)
  • 送信されたフォームのID
  • 例 : "espf"
status (文字列)
  • jQuery の Ajax ステータス文字列
  • 例 : 成功時は "success"
response (オブジェクト)
  • サーバーから返されたレスポンスを JSON パースした結果
  • 例 : {"status":201,"message":"ok"}
services (オブジェクト または undefined)
  • espar form 管理画面の「外部APIのレスポンスボディを返す」のチェックボックスがONで、外部サービス連携が設定・実行された場合にのみ利用可能 (参考:APIのレスポンスボディを返す)
  • 外部サービスごとのレスポンスをまとめたオブジェクト。以下はデータベース連携のGoogleスプレッドシートと、API連携のRestAPIを使用した例 
    {
        "google_sheets": {
            "status": 200,
            "body": {
                "customerName": "田中太郎",
                "sheetUrl": "https://example.com/sheets/..."
            }
        },
        "external_api": {
            "status": 200,
            "body": {
                "message": "ok"
            },
        }
    }
  • 外部サービスとの連携が行われなかった場合は undefined
  • オブジェクト中のキーは設定した連携サービス名。現在は以下に対応
    キー例サービス連携
    kintonekintone
    google_sheetsGoogle スプレッドシート
    external_apiRestAPI
  • サービスごとの値は { status, body, error } を含むオブジェクト
    • status (数値 または undefined): サービス側レスポンスの HTTP ステータスコード
    • body (オブジェクト / 文字列): レスポンスボディ。JSON 文字列の場合は自動的にパースされ、パース失敗時は文字列のまま渡される
    • error (文字列 / オブジェクト / undefined): サービス側エラー情報。存在する場合のみ設定される

呼び出しタイミング

  • フォーム送信が成功し、完了画面の表示項目初期化が完了した後
  • 外部 API 連携がある場合は、その結果が反映された後

使用例

業務システムへデータ転送を行い、システムで付与されたID番号をフォーム側に表示する例

services引数からexternal_apiオブジェクトを取得し、システム側のAPIが返すレスポンスボディ(JSON)のticketIdを取得して表示

var espar_form = {
  // ...(省略)...
  submit_success_callback: function (formId, status, response, services) {
    var externalApi = services && services.external_api;
    if (!externalApi) return;


    if (externalApi.status === 201) {
      console.log('RestAPI 連携が完了しました:', externalApi.body);
      if (externalApi.body && externalApi.body.ticketId) {
        document.getElementById('ticket-id').textContent = externalApi.body.ticketId;
      }
    } else {
      console.error('RestAPI 連携でエラーが発生しました:', externalApi.status, externalApi.error || externalApi.body);
      // 必要に応じてユーザー向けメッセージを表示
      alert('外部システムへの連携に失敗しました。時間をおいて再度お試しください。');
    }
  }
};

Googleスプレッドシートに連携して、登録の成否をログ出力し、また入力者の名前情報を画面に表示する例

services 引数から google_sheets オブジェクトを取得し、HTTP ステータスによってログを分岐。成功時はレスポンスボディの customerName を完了メッセージに差し込み表示

var espar_form = {
  // ...(省略)...
  submit_success_callback: function (formId, status, response, services) {
    var spreadsheet = services && services.google_sheets;
    if (spreadsheet) {
      if (spreadsheet.status >= 200 && spreadsheet.status < 300) {
        console.log('スプレッドシート連携で登録に成功しました:', spreadsheet.body);
        // 例: 連携先から返却された値を画面に反映
        if (spreadsheet.body && spreadsheet.body.customerName) {
          document.getElementById('msg').textContent = spreadsheet.body.customerName + ' さんの登録が完了しました。';
        }
      } else {
        console.error('スプレッドシート連携での登録に失敗しました:', spreadsheet.status, spreadsheet.error || spreadsheet.body);
      }
    }
  }
};

submit_failure_callback

引数

formId (文字列)
  • 送信に失敗したフォームのID。
status (文字列)
  • 失敗の種類を示すステータス文字列
  • 例: "timeout", "error", "abort", "parseerror" など
errorString (文字列)
  • エラーメッセージまたは説明文
  • HTTP エラーが発生した場合、errorString には HTTP ステータスのテキスト部分（例: "Not Found", "Internal Server Error"）が渡される
  • HTTP/2 の場合は空文字列になることがある

呼び出しタイミング

  • フォーム送信が HTTP エラー等で失敗した後
  • 失敗時のUI更新が完了した後、リダイレクト処理より前

使用例

submit_failure_callback: function (formId, status, errorString) {
    console.error('送信失敗:', formId, status, errorString);
}

back_clicked_callback

引数

なし

呼び出しタイミング

  • 戻るボタンがクリックされた時
  • 確認画面から入力画面へ戻る前

備考

戻り値で false を返すと、標準の戻る処理をキャンセルできます。

confirm_clicked_callback

引数

なし

呼び出しタイミング

  • 確認ボタンがクリックされた時
  • 最終的なフォーム送信前

備考

戻り値で false を返すと、確認処理をキャンセルできます。

submit_clicked_callback

引数

なし

呼び出しタイミング

  • 送信ボタンがクリックされた直後
  • バリデーション実行前
  • ボタンが無効化された後

備考

戻り値で false を返すと送信処理をキャンセルできます。