JavaScript Customization

English version coming soon

This page has not been fully translated yet. See the Japanese version for the full reference and examples.

Form Plant supports two client-side extension points:

• Custom validators — a callback API for per-field validation
• Lifecycle events — CustomEvents fired at each step of the form

JavaScript is for UX, not security

JS validation gives instant feedback in the browser, but DevTools can bypass it. Always pair it with PHP-side Validation Hooks for trustworthy validation.

Where It Works

Embed method	Custom validator API	Lifecycle events
Page / shortcode	Yes	Yes
iframe embed	No	Yes (limited)
JavaScript embed	No	Yes (limited)

fplant.addValidator() and the fplant:validateField event are only available when the form is rendered directly on a WordPress page.

Loading Your Custom JS

Enqueue your script with fplant-form as a dependency:

function my_fplant_custom_scripts() {
    wp_enqueue_script(
        'my-fplant-custom',
        get_stylesheet_directory_uri() . '/js/my-fplant-custom.js',
        array( 'fplant-form' ),
        '1.0.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'my_fplant_custom_scripts' );

Custom Validator API

window.fplant.addValidator('email', function (value, fieldName, formData) {
  if (value && !value.endsWith('@example.com')) {
    return 'Only @example.com addresses are accepted';
  }
  return ''; // empty string = success
});

Return an error message string to mark the field invalid. Return '', null, or undefined to mark it valid. Use fplant.removeValidator(fieldName, callback) (or omit the callback to clear all validators on that field) to remove.

Lifecycle Events

All events fire on the .fplant-form element and bubble to document.

Event	Cancelable	Fires
fplant:init	no	Form initialized
fplant:validateField	yes	After each field's validation (page embed only)
fplant:beforeSubmit	yes	After validation, before submit request
fplant:error	no	Validation error displayed
fplant:loading	no	Loading state changed (detail.loading: boolean)
fplant:confirmationShow	no	Confirmation screen shown
fplant:confirmationHide	no	Returned from confirmation to input screen
fplant:success	no	Submission succeeded
fplant:submitError	no	Server returned an error after submit

Cancelable events stop the default action when you call e.preventDefault().

Example: Confirm Before Submitting

var form = document.querySelector('.fplant-form');
form.addEventListener('fplant:beforeSubmit', function (e) {
  if (!confirm('Send this form?')) {
    e.preventDefault();
  }
});

Example: Custom Error via fplant:validateField

form.addEventListener('fplant:validateField', function (e) {
  if (e.detail.fieldName === 'email') {
    var value = e.detail.value;
    if (value && value.indexOf('@company.co.jp') === -1) {
      e.detail.errorMessage = 'Use your company email (@company.co.jp)';
      e.preventDefault();
    }
  }
});

Set e.detail.errorMessage and call e.preventDefault() — both are required.

Notes

• Error messages are rendered via textContent, so they're XSS-safe.
• Exceptions thrown inside addValidator() callbacks are swallowed silently; add your own error handling during development.
• Register listeners after DOMContentLoaded, or use document since events bubble.

iframe / JavaScript Embed Limitations

• fplant:validateField does not fire (no client-side validation in embedded forms)
• window.fplant.addValidator() / removeValidator() are unavailable
• fplant:beforeSubmit detail contains only formId (no formData)
• fplant:confirmationShow detail contains only formId (no confirmationEl)