Registering form integrations (Pro)

A form integration adds a service to the form editor, such as an email marketing list or a webhook. GenerateBlocks Pro includes Mailchimp, ActiveCampaign, Brevo, ConvertKit, MailerLite and a webhook. You can add your own with generateblocks_pro_register_form_integration().

For the hooks around integrations, see Forms: email, webhooks and integrations. To run your own code on a submission without a service, see Registering form actions.

Jump to

• How integrations are registered
• Arguments
• Callbacks
• Example: a webhook-style service

How integrations are registered

GB Pro — since GenerateBlocks 2.6.

Call generateblocks_pro_register_form_integration( $args ) inside the generateblocks_form_register_integrations action. It returns true when the integration was registered, or false when $args isn’t an array, or id or label is missing. The function is a wrapper for GenerateBlocks_Pro_Form_Integration_Registry::register().

The action runs after the built-in integrations, so registering an id that already exists replaces the built-in one for that request.

To provide the API key for a service yourself, call generateblocks_pro_set_email_integration( $service, $api_key ) inside generateblocks_form_register_email_integrations.

Related: generateblocks_form_register_integrations Guide: Forms

Back to top

Arguments

GB Pro

Argument	Description
id	Required. A unique ID, passed through sanitize_key().
label	Required. The name shown in the form editor.
type	The kind of integration. Default: email.
help	Help text shown in the editor.
connection	How the service is connected. See below.
destination	The list, group or audience a submission goes to. See below.
secondary_destination	An optional second choice, such as a tag. Same keys as destination, but not required by default.
settings_fields	Extra settings fields for the form, as an array of fields. See below.
settings_validate_callback	Callable that validates the form’s settings for this integration. It receives the settings and returns true or a WP_Error.
field_map	Lets editors map form fields to the service’s fields. See below.
supports_name_field	Whether the service takes a name field. Default: false.
supports_double_optin	Whether the service supports double opt-in. Default: false.
default_double_optin	Whether double opt-in is on by default. Default: true.
subscribe_callback	Callable that sends a submission to the service. See Callbacks.

connection

Key	Description
type	api_key, or none (the default). When api_key has no fields, a required password field named api_key is added.
fields	Array of connection fields. Each needs a key and a label. Optional keys are type (default text), help, placeholder, required (default true), test_required, define (the name of a constant that can hold the value) and public.
test_callback	Callable that tests the connection. It receives the saved connection settings.
connected_callback	Callable that reports whether the service is connected.

destination and secondary_destination

Key	Description
label	The label of the select.
empty_label	The empty option’s label. Default: - Select -.
refresh_label	The refresh button’s label. Default: Refresh.
required	Whether a choice is needed. A destination with a label or options callback is required by default.
options_callback	Callable that returns the choices, as an array of { value, label } rows, or plain values.

settings_fields is an array of fields with a key, a label, and optionally type (default text), help, placeholder and required (default true).

field_map takes enabled, label (default Fields), empty_label (default Don't map), refresh_label, depends_on_destination and options_callback. It is enabled when enabled is set or an options_callback is given.

Related: generateblocks_form_register_integrations Guide: Forms

Back to top

Callbacks

GB Pro

subscribe_callback( $sanitized_data, $settings, $context = [] ) sends a submission to the service. Return true on success or a WP_Error.

Argument	Description
$sanitized_data	The sanitized fields. Each field’s value is in its value key.
$settings	The form’s settings for this integration. They include destinationId, emailField (the name of the email field), fieldMap, doubleOptin when supported, and any settings_fields keys.
$context	Request context, such as post_id and page_url.

Related: generateblocks_form_validate_submission Guide: Forms

Back to top

Example: a webhook-style service

GB Pro

This integration asks for a URL in the form’s settings and posts the email address to it.

add_action( 'generateblocks_form_register_integrations', function() {
    generateblocks_pro_register_form_integration( [
        'id'                 => 'my-crm',
        'label'              => __( 'My CRM', 'my-plugin' ),
        'type'               => 'email',
        'settings_fields'    => [
            [
                'key'         => 'url',
                'label'       => __( 'Endpoint URL', 'my-plugin' ),
                'type'        => 'url',
                'placeholder' => 'https://example.com/api/subscribe',
                'required'    => true,
            ],
        ],
        'subscribe_callback' => function( $sanitized_data, $settings, $context = [] ) {
            $email_field = $settings['emailField'] ?? 'email';
            $email       = $sanitized_data[ $email_field ]['value'] ?? '';

            if ( ! is_email( $email ) ) {
                return new WP_Error( 'invalid_email', 'A valid email is required.' );
            }

            $response = wp_remote_post(
                esc_url_raw( $settings['url'] ?? '' ),
                [ 'body' => [ 'email' => $email ] ]
            );

            return is_wp_error( $response ) ? $response : true;
        },
    ] );
} );

Related: Registering form actions Guide: Forms

Back to top