jfb-action-events

JetFormBuilder: action events — when does an action run?

A JFB Form Action doesn't just "run on submit" — it runs on a named event, and the form admin can pick (in the action editor) which event(s) trigger each action instance. Built-in events cover the common cases (form submitted, form validation failed, payment gateway success/failure, conditional state activated). Plugins can register their own events for specialized triggers (inbound webhooks, scheduled CRON, third-party callbacks).

This skill is the companion to jfb-form-action. That one covers the action class itself; this one is the when layer.

API stability note

The Base_Event / Base_Action_Event / Base_Gateway_Event hierarchy, the 'jet-form-builder/event-types' registration filter, the 'jet-form-builder/before-trigger-event' / 'jet-form-builder/after-trigger-event' hooks, and the action-side supported_events() / unsupported_events() / get_required_events() overrides have been stable across JFB 3.x in the source observed. The plugin-version-tested value records last end-to-end verification only.

When to use this skill

• An action should run only on payment callbacks, not on plain submit.
• An action should run on validation failure (e.g. log invalid attempts).
• An action should run on conditional-block state changes.
• The plugin needs a brand-new event type (webhook receiver, scheduled task, custom integration callback).
• The diff/files contain supported_events, unsupported_events, get_required_events, Base_Event, Base_Gateway_Event, 'jet-form-builder/event-types', add_hidden, 'GATEWAY.SUCCESS', 'DEFAULT.REQUIRED'.

Architecture in one paragraph

JFB's Events_Manager holds a registry of event classes (each with a stable get_id() slug). When the form runs, the form handler calls jet_fb_events()->execute( SomeEvent::class ) — this looks up the event, gets its executor, iterates the form's actions, and runs each action whose is_valid_action() returns true. The action's selected events are stored as part of the form's _jf_actions post meta (each action carries an events array). The validation logic in Base_Event::is_valid_action() checks three things in order: (1) is the action explicitly blacklisted from this event via unsupported_events()? (2) is the action explicitly whitelisted via supported_events()? (3) did the user pick this event for this action in the form editor? All three must pass. get_required_events() is the escape hatch that auto-injects events into the action's selection without the user touching anything (used for actions that MUST run on a particular event regardless).