Developer Reference for Pro

The PHP hooks and JavaScript events added by Form Plant Pro, and the shape of the data it stores. For the free plugin's hooks in general, see the PHP Hook Reference and JavaScript Customization.

PHP filters and actions

Hook	Type	Arguments	What it does
`fplant_pro_features_enabled`	filter	`bool $enabled`	Whether Pro features run on this site
`fplant_pro_reception_closed_html`	filter	`string $html`, `array $form`, `string $state`, `string $context`	The markup shown instead of a closed form
`fplant_pro_reception_donotcachepage`	filter	`bool $prevent`, `array $form`, `string $context`	Whether pages containing a form under reception control are excluded from page caches (default `true`)
`fplant_pro_reception_now`	filter	`DateTimeImmutable $now`	The "current time" used by reception control
`fplant_pro_license_changed`	action	—	Fires right after the license is activated or deactivated

$state is one of before, after, full or login; $context is one of shortcode, iframe or rest.

Example: turn Pro features off on staging

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

Example: show something else instead of a closed form

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 );

Page caching

Returning false from fplant_pro_reception_donotcachepage lets pages with a reception-controlled form be cached again. A stale copy of the open form may then be served, but the submission itself is still stopped on the server.

JavaScript events

All of them bubble from the <form> element (row events from the group / repeater wrapper).

Event	`detail`	When it fires
`fplant:conditionalChange`	`{ formId, fieldName, visible }`	A field is shown or hidden by conditional logic
`fplant:beforePageChange`	`{ formId, from, to, total, direction }`	Just before a page change. Cancelable with `preventDefault()`
`fplant:pageChange`	`{ formId, from, to, total, direction }`	Just after a page change
`fplant:rowAdded`	`{ field, index, row }`	A repeater row was added
`fplant:rowRemoved`	`{ field, index }`	A repeater row was removed

from, to and index are zero-based. direction is next, prev or jump; jump is used when the form moves automatically to a page with an error.

Example: track step completion

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

Example: prefill a newly added row

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';
  }
});

Stored data

Form definition

Pro settings are stored inside the free plugin's form data under these keys.

Key	Location	Contents
`pro_conditional`	each field	The field's visibility conditions
`pro_conditional_emails`	`settings`	Email send conditions and recipient routing
`pro_conditional_actions`	`settings`	Conditional completion actions
`pro_pages`	`settings`	Multi-step settings
`pro_reception`	`settings`	Reception control settings
`sub_fields` / `min_rows` / `max_rows` / `group_layout` / `group_columns`	group / repeater field	The definition of the set

The submission count is stored as an integer in the form's post meta _fplant_pro_reception_count (not in the form settings).

Submission data

A group is stored as one object, a repeater as an array of rows.

{
  "members": [
    {
      "fullname__family": "Yamada",
      "fullname__given": "Taro",
      "email": "taro@example.com",
      "birth": "1990-04-01",
      "doc": { "filename": "a_x7Kp2Q.pdf", "url": "https://…", "file": "/…", "type": "application/pdf" }
    }
  ],
  "contact_pref": { "method": "email", "times": ["Morning", "Evening"] }
}

Every defined sub field key is always present (empty string when not filled in)
Values are strings, with two exceptions: multiple selections (array of strings) and files (file info array)
Name, kana and address sub fields are flattened into <sub field name>__<part> keys (family / given / middle, postal_code / prefecture / city / street / building, and so on)
A repeater with no rows is stored as an empty array []
The field definition in effect at submission time is stored with each submission and used for display, so editing the form later does not change how past submissions are shown

In HTML templates

Feature	What to write
Conditional logic	Add `data-fplant-field="<field name>"` to the element wrapping the field
Groups / repeaters	`[fplant_field name="members"]` outputs the whole set; `[fplant_value name="members"]` on the confirmation screen
Multi-step	`[fplant_field name="page_break_1"]` at each break; `<div class="fplant-pro-progress"></div>` where the progress indicator goes

See the page for each feature and the input screen HTML template guide for details.

Extension points in the free plugin

Pro is built on the hooks and APIs published by the free plugin. The public APIs added in free version 1.5.2 for Pro — per-field client-side validation, validation error events, replacing the form output, and a final gate before a submission is stored — are equally usable from your own code. See the PHP Hook Reference and JavaScript Customization.

PHP filters and actions​

Example: turn Pro features off on staging​

Example: show something else instead of a closed form​

JavaScript events​

Example: track step completion​

Example: prefill a newly added row​

Stored data​

Form definition​

Submission data​

In HTML templates​

Extension points in the free plugin​