メインコンテンツまでスキップ

Pro の開発者向け情報

Form Plant Pro が追加する PHP フック・JavaScript イベントと、保存されるデータの形をまとめます。無料版のフック全般については PHP フックリファレンス と JavaScript カスタマイズ を参照してください。

PHP フィルター / アクション​

フック種類引数内容
fplant_pro_features_enabledfilterbool $enabledこのサイトで Pro 機能を動かすかどうか
fplant_pro_reception_closed_htmlfilterstring $html, array $form, string $state, string $context受付を締め切っているときに、フォームの代わりに出力する HTML
fplant_pro_reception_donotcachepagefilterbool $prevent, array $form, string $context受付制御のあるフォームを含むページをページキャッシュから除外するか (既定 true)
fplant_pro_reception_nowfilterDateTimeImmutable $now受付制御が使う「現在時刻」
fplant_pro_license_changedaction—ライセンスの有効化 / 解除の直後に実行されます

$state は before (受付開始前) / after (受付終了) / full (定員到達) / login (ログインが必要) のいずれか、$context は shortcode / iframe / rest のいずれかです。

例: ステージング環境では Pro 機能を止める​

add_filter( 'fplant_pro_features_enabled', function ( $enabled ) {
    if ( defined( 'WP_ENVIRONMENT_TYPE' ) && 'staging' === WP_ENVIRONMENT_TYPE ) {
        return false;
    }
    return $enabled;
} );

例: 締め切ったフォームの代わりに別の案内を出す​

add_filter( 'fplant_pro_reception_closed_html', function ( $html, $form, $state, $context ) {
    if ( 'full' === $state && 123 === (int) $form['id'] ) {
        return '<div class="notice">' . do_shortcode( '[fplant id="456"]' ) . '</div>';
    }
    return $html;
}, 10, 4 );
ページキャッシュ

fplant_pro_reception_donotcachepage に false を返すと、受付制御のあるフォームを含むページがキャッシュ対象に戻ります。締め切った後も古いフォームが表示され続ける可能性がありますが、送信そのものはサーバー側で止まります。

JavaScript イベント​

いずれも <form> 要素 (行の操作はグループ / リピーターのラッパー) から バブリングして 発生します。

イベントdetail発生タイミング
fplant:conditionalChange{ formId, fieldName, visible }条件分岐で項目の表示状態が変わったとき
fplant:beforePageChange{ formId, from, to, total, direction }ページ移動の直前。preventDefault() で中止できます
fplant:pageChange{ formId, from, to, total, direction }ページ移動の直後
fplant:rowAdded{ field, index, row }リピーターの行が追加されたとき
fplant:rowRemoved{ field, index }リピーターの行が削除されたとき

from / to / index は 0 始まりです。direction は next / prev / jump のいずれかで、jump はエラーのあるページへ自動移動したときに使われます。

例: ステップの到達を計測する​

document.addEventListener('fplant:pageChange', function (e) {
  gtag('event', 'form_step', {
    form_id: e.detail.formId,
    step: e.detail.to + 1,
    total: e.detail.total
  });
});

例: 行の追加時に初期値を入れる​

document.addEventListener('fplant:rowAdded', function (e) {
  if (e.detail.field !== 'members') {
    return;
  }
  const input = e.detail.row.querySelector('input[name$="[qty]"]');
  if (input && !input.value) {
    input.value = '1';
  }
});

保存されるデータの形​

フォーム定義​

Pro の設定は、無料版のフォームデータの中に次のキーで保存されます。

キー場所内容
pro_conditional各フィールド項目の表示条件
pro_conditional_emailssettings通知メールの送信条件・宛先の振り分け
pro_conditional_actionssettings条件付き完了アクション
pro_pagessettingsページ分割の設定
pro_receptionsettings受付制御の設定
sub_fields / min_rows / max_rows / group_layout / group_columnsグループ / リピーターのフィールド組の定義

受付件数は、フォームの投稿メタ _fplant_pro_reception_count に整数で保存されます (フォーム設定の中ではありません)。

送信データ​

グループは 1 つのオブジェクト、リピーターは行の配列として保存されます。

{
  "members": [
    {
      "fullname__family": "山田",
      "fullname__given": "太郎",
      "email": "taro@example.com",
      "birth": "1990-04-01",
      "doc": { "filename": "a_x7Kp2Q.pdf", "url": "https://…", "file": "/…", "type": "application/pdf" }
    }
  ],
  "contact_pref": { "method": "email", "times": ["午前", "夕方"] }
}
  • 定義済みのサブフィールドのキーは 必ずすべて存在 します (未入力は空文字)
  • 値は文字列が原則です。例外は 複数選択 (文字列の配列) と ファイル (ファイル情報の配列) の 2 つです
  • 氏名・フリガナ・住所は <サブフィールド名>__<パーツ名> のフラットなキーに展開されます (family / given / middle、postal_code / prefecture / city / street / building など)
  • 0 行のリピーターは空配列 [] として保存されます
  • 送信ごとにそのときのフィールド定義が保存され、表示にはそちらが使われます (後からフォームを編集しても過去の送信データの表示は変わりません)

HTML テンプレートでの記述​

機能書き方
条件分岐項目を囲む要素に data-fplant-field="フィールド名" を付ける
グループ / リピーター[fplant_field name="members"] で組全体を出力。確認画面では [fplant_value name="members"]
ページ分割[fplant_field name="page_break_1"] を区切りの位置に。進捗表示の位置は <div class="fplant-pro-progress"></div>

詳しくは各機能のページと 入力画面 HTML テンプレート を参照してください。

無料版側の拡張ポイント​

Pro は無料版が公開しているフック・API の上に実装されています。Pro 向けに無料版 1.5.2 で追加された公開 API (フィールド単位のクライアント検証・バリデーションエラーのイベント・フォーム出力の差し替え・送信の最終ゲートなど) も、Pro を使わない拡張で利用できます。一覧は PHP フックリファレンス と JavaScript カスタマイズ を参照してください。