JavaScript

XPAC exposes two different JavaScript surfaces, and it is worth knowing which one you need before you write anything.

The first is listed in full in the hook reference — every JavaScript hook is generated from its applyFilters() call site, with its arguments. This page covers the second, which is not generated because it is not a hook: it is an object on an element, and it is the only way to drive a form or a popup from outside.

Getting your script on the page

Enqueue against the handle you want to run after. The handles are stable:

add_action('wp_enqueue_scripts', function () {
	wp_enqueue_script(
		'my-form-extras',
		plugins_url('my-form-extras.js', __FILE__),
		['xp-form-view-script'],
		'1.0.0',
		true
	);
});

Forms

The lifecycle

A form is initialised once. The interface is attached first, then two events announce it, in this order:

Listen on document unless you already hold the element. A form inserted later — by a popup, a router, an AJAX load — fires xpacFormInitialize too, and never fires xpacFormsReady a second time.

document.addEventListener('xpacFormInitialize', (event) => {
	const form = event.detail.form;

	form.xpacForm.callbacks.registerSuccessCallback(() => {
		console.log('submitted', form.xpacForm.utils.getId());
	});
});

To initialise a form the bundle has not seen — one you built and inserted yourself — call window.initializeXpacForm(formElement). It is a no-op on an element that is not .xp-block-form or that already has an interface.

form.xpacForm

Five namespaces. Everything a submission does can be observed or changed through them.

config

config.setOption(name, value) and config.getOption(name, fallback) hold per-form settings. setOption will not overwrite a name that is already set, so the first writer wins.

window.xpacForms

Read-only data printed once per page, before the form bundle, the first time a form renders. It is deep-frozen, so nothing can change it in the browser.

Add-ons put their own front-end data here through the xpac_forms_inline_js_data filter — Turnstile and reCAPTCHA their site keys, Stripe its publishable key. The keys above are merged in afterwards and cannot be replaced.

Popups

template.xpacPopup

Every popup template element carries an interface. It is attached before the element's initialize event fires, which is the point to register a checker.

Both checkers receive (rule, template). Every registered open checker has to return truthy for the popup to open — one false is enough to hold it back.

document.addEventListener('initialize', (event) => {
	const template = event.target;

	if (!template.xpacPopup) {
		return;
	}

	template.xpacPopup.registerOpenChecker(
		() => !document.body.classList.contains('checkout-in-progress')
	);
}, true);

The listener is capturing because initialize is dispatched on the template element and does not bubble.

Events

Four events, each fired twice: once on the template element and once on document.

The document copy adds template to the detail, since a document listener has no other way to tell which popup it is hearing about. requested is true when the open came from an explicit request — a Popup Selector block or a trigger — rather than from a display rule matching.

Listen on document for anything site-wide, and on the element when you already have it. Do not listen for both, or you will handle every popup twice.

Editor filters

Both plugins run their editor UI through @wordpress/hooks, so an add-on adds a panel or changes a field without touching the plugin.

Five more run on the front end rather than in the editor: xpac-popups-triggers, xpac-popups-animation, xpac-popups-is-modal, xpac-popups-is-conversion and xpac-popups-conversion-selector.

Each one's arguments, defaults and call site are in the hook reference.

import { addFilter } from '@wordpress/hooks';

addFilter('xpac-forms-form-panels', 'my-plugin/panels', (panels) => [
	...panels,
	{ name: 'my-panel', title: 'My panel', Component: MyPanel },
]);