Add-ons

Similar to any code module, the plugin follows its own lifecycle. It commences by initializing its core components. Subsequently, the plugin triggers the xpac_forms_init action, a crucial step serving as the launchpad for all add-ons. It is imperative for add-ons to utilize this action as their starting point since, at this stage, the form plugin is fully initialized and can seamlessly interact with the add-ons. The xpac_forms_init action is triggered during the WordPress native init action.

Registering form block

Initially, the Forms post type supports only a limited set of block types—both custom and core—meaning only specific block types are accessible through the inserter. Nonetheless, it offers a user-friendly public interface to register any block type within the form. This allows for effortless inclusion of additional block types in the inserter for the form post type by simply invoking a single method: \XPACGroup\Plugin\XPACForms\Core\Blocks::registerFormBlock
This method should be used during/after xpac_forms_init action.

This method expects to receive 2 arguments:

• string $block_name Registered block type name.
• array $config Optional configuration array, which describes the block behavior.

Configuration array has the following structure:

• A boolean form_only key, which instructs the form to exclude the block everywhere except for the form post-type screens. Default: true.
• A boolean is_changeable key, which instructs the form that the block should behave as a changeable block, i.e. user can interact with it and change its value, etc, such as the input field. Default: false. In case of truthy value, consider using the following optional keys:
  • A boolean is_selectable key, which instructs the form that the block contains a changeable field that has choices support, such as radio, select, etc. Default: false.
  • A non-empty string confirmable_as key, which instructs the form that the block contains a changeable field that might be confirmed with the “Confirmation” field block. The value of this key will be used as the type attribute of the input field of the “Confirmation” block, i.e. text, email, url, password, etc.
  • The numerical array rules – validation rules to use for the backend validation of the field. The validation rules section provides detailed information about validation rules. Each item of this array must either be a subclass of the \XPACGroup\Plugin\XPACForms\Rules\Rule or an associative array with 2 keys:
    • rule – the class name of the validation rule class – a subclass of the \XPACGroup\Plugin\XPACForms\Rules\Rule class
    • options – an array of options that will be passed as the second argument to the rule class

/* Register core block */
\XPACGroup\Plugin\XPACForms\Core\Blocks::registerFormBlock('core/audio');

/* Register custom block type as unchangeable */
\XPACGroup\Plugin\XPACForms\Core\Blocks::registerFormBlock(
    'my-namespace/my-block-name'
);

/* Changeable, confirmable as email, required custom block */
\XPACGroup\Plugin\XPACForms\Core\Blocks::registerFormBlock(
    'my-namespace/my-block-name',
    [
        'is_changeable' => true,
        'is_selectable' => false,
        'confirmable_as' => 'email',
        'rules'      => [
            \XPACGroup\Plugin\XPACForms\Rules\Required::class,
            [
                 'rule' => 'MyCustomRuleClassName',
                 'options' => [
                      'option1' => 'value1',
                      'option2' => 'value2'
                 ]
            ]
        ]
    ]
);

By default, the field values of the custom blocks registered to the form that have enabled changeable support would be treated as text fields. However, it is possible to instruct the form to change this behavior via the xpac_forms_{$BLOCK_TYPE}_field_type dynamic hook, where the $BLOCK_TYPE is the block name. The callbacks hooked to this filter will receive the current field type as an input argument and should return the updated type, such as email, phone, URL, etc.

function set_block_field_type($type) {
	return 'email';
}
add_filter('xpac_forms_my-addon/custom-block_field_type', 'set_block_field_type');

Register form settings

The settings of each form are stored in a single meta field as a serialized array. Addons have a possibility to register additional settings to that meta field as well using 2 special filters:

1. The xpac_forms_post_meta_schema filter is designed to provide the possibility to register additional meta field structures to the meta field.

function edit_post_meta_schema($schema) {
	$schema['my_addon_key'] = [
		'type'       => 'object',
		'properties' => [
			'my_addon_value_1'        => [
				'type' => 'boolean'
			],
			'my_addon_value_2'        => [
				'type' => 'string'
			],
		]
	];

	return $schema;
}
add_filter(
	'xpac_forms_post_meta_schema', 
	'edit_post_meta_schema'
);

2. The xpac_forms_post_meta_default_values filter is designed to provide the possibility to set default values for the newly registered meta fields.

function edit_post_meta_default_values($values) {
	$values['my_addon_key'] = [
		'my_addon_value_1' => 'defaut_value_1',
		'my_addon_value_2' => 'defaut_value_2'
	];

	return $values;
}
add_filter(
	'xpac_forms_post_meta_default_values',
	'edit_post_meta_default_values'
);

Register Plugin Settings

Similar to any plugin, XPAC Forms comes with its own settings and offers an API for add-ons to seamlessly integrate their settings into the plugin. The plugin settings are crafted using React JS and WordPress (Gutenberg)’s native components, ensuring a lightweight and modular approach. Each module of the addon is designed to seamlessly integrate with and extend the plugin’s functionality.

To register settings, addons must utilize the xpac_forms_settings_structure filter by hooking into it and providing their specific settings structure. This structure will be displayed on the form settings page. Callbacks attached to the xpac_forms_settings_structure filter should expect the existing settings structure as an input parameter. Addons must add their custom settings to this input parameter and return the modified result, adhering to the standard filter callback methodology.

Each module is considered an independent ‘page’. When multiple modules register settings, a tabbed approach is employed. This means that the settings for each module will be presented in their own distinct tab. The configuration for module settings follows an associative array structure, as detailed below:

example:

function my_addon_register_settings($structure) {
	// Addon settings structure declaration
	$my_addon_settings_structure = [
		'name'      => 'my_addon_id',
		'title'     => __('My Addon', 'textdomain'),
		'pageTitle' => __('My Addon Settings', 'textdomain'),
		'priority'  => 1000,
		'fields'    => []
	];
	
	// Add addon settings structure to plugin settings
	$structure[] = $my_addon_settings_structure;
	
	// Return updated structure
	return $structure;
}
add_filter('xpac_forms_settings_structure', 'my_addon_register_settings');

Each field item within the module fields array is itself an associative array with the following configuration:

There are multiple basic field types already implemented in the settings API:

If the provided list does not include the preferred field type, there is an option to register custom field types with the settings API.

Backend validation rules