Skip to main content

Forms (Backend)

Forms have multiple thing to setup:

Frontend:

  • Template (PHP)
  • Validation (JS)
  • Submission (JS)

Backend:

  • Validation (PHP)
  • Submission (PHP)

Note: This page outlines the backend of the forms process, the frontend docs are here

Quick Start​

Just open Blank and duplicate the existing form:

  • Backend (PHP): src/inc/api/api-forms.php

Note: In the new WP Blank we separated the API files per feature, so if you are looking for this file in an older project try searching for src/inc/api/callbacks.php.

Change the name and id of the form.

Backend​

Make sure you have an API route setup to handle POST request at API_URL/forms/slug. This comes by default in wp-blank. This is usually in src/inc/api/endpoints.php.

The second part is to make sure your callback uses FxForm. Look inside src/inc/api/callbacks.php and check that it's being used.

Next, check to make sure CONSTANTS.API_URL and CONSTANTS.API_NONCE are available on the window (JS). To do this, type window.CONSTANTS.API_URL in the console.

Finally, check src/inc/fx-enqueue.php to make sure they are 'localized', it will look like so..

wp_localize_script('fx-scripts', 'CONSTANTS', [
    'API_URL' => get_site_url() . '/wp-json/' . API_BASE . API_VERSION,
    'API_NONCE' => wp_create_nonce(API_NONCE),
]);

To create a new form, make a new file src/inc/forms/form-{slug}.

Note: API_BASE and API_VERSION come from fx-constants.php

FxForm​

The FxForm class gives you a few helpful methods to validate and process forms on the backend.

The form can be customised using Wordpress filters and actions.

It is recommended that you process forms using the WP-API and have a custom endpoint to handle forms. You can then simple init the class and check each form with one function.

Example​


add_filter('fx_form_fields_contact', 'fx_form_fields_contact', 10, 1);
add_filter('fx_form_options_contact', 'fx_form_options_contact', 10, 1);

// Optional filters/actions
add_filter('fx_form_email_body_contact', 'fx_form_email_body_contact', 10, 2);
add_action('fx_form_submit_contact', 'fx_form_submit_contact', 10, 1);

function fx_form_fields_contact($fx_form) {
    return [
        ['name', 'string', true],
        ['email', 'email', true],
    ];
}

function fx_form_options_contact($fx_form) {
    return [
        'to' => ['client@domain.com'],
        'subject' => 'Website contact',
    ];
}

function fx_form_submit_contact($fx_form) {
    // Do something after submitting
}

function fx_form_email_body_contact($current_body, $fx_form) {
    // Customise the email body
    return $current_body;
}

$fx_form = new FxForm('contact', [
    'name' => 'My name',
    'email' => 'user@domain.com',
]);

if ($fx_form->validate()) {
    $fx_form->submit();
}

// Get response
$response_data = $fx_form->get_response();

API reference​

contructor​

Create a new instance of FxForm.

Description​

$fx_form = new FxForm($name: string, $data: Array): FxForm;

validate​

Validate the data against form inputs, returns true if valid. Validation errors will be available via get_response.

Description​

$fx_form->validate(): boolean

submit​

Submitting the form. This includes sending an email if the to and subject options have been set.

Description​

$fx_form->submit(): void

set_options​

Update the form options directly.

Description​

$fx_form->set_options($options: [[key: string]: any]): void

get_response​

Get the response from the form.

Description​

$fx_form->get_response(): FormResponse

// A form response has the following type definition:
FormResponse = {
    success: boolean,
    errors: null | string[],
    message?: string
}

Filter reference​

Wordpress filters are used to override default form behaviour.

fx_form_fields_{name}​

Set the fields of the form on construction. The callback method receives the form instance and should return an Array of fields, see fields for more information.

Description​

add_filter('fx_form_fields_{name}', 'fx_form_fields_{name}', 10, 1);

fx_form_options_{name}​

Set the options of the form on construction. The callback method receives the form instance and should return an Array of options, see options for more information.

Description​

add_filter('fx_form_options_{name}', 'fx_form_options_{name}', 10, 1);

fx_form_email_body_{name}​

Modify the email body. The callback method receives the current message and form instance, it should return a html string.

Separating out form data​

To deconstruct the $fx_form data and isolate form field values, you can use the following approach:

$data = $fx_form->data;

$name = $data['name'];
$phone = $data['phone'];
$email = $data['email'];
$message = sprintf(
    'Some message here with name: %s, phone: %s and email: %s',
    $name,
    $phone,
    $email
);

return $message;

Description​

add_filter('fx_form_email_body_{name}', 'fx_form_email_body_{name}', 10, 2);

Action reference​

Wordpress actions are used to hook into steps of the form process.

fx_form_submit_{name}​

Callback after the form is submitted. The callback methods receives the form instance.

Description​

add_action('fx_form_submit_{name}', 'fx_form_submit_{name}', 10, 1);

Fields​

The fields array should be structured like so:

// Form fields have the following type definition:
FormFields = [name: string, type: string, required: bool][];

// Example:
$fields = [
    ['name', 'string', true],
    ['email', 'email', true],
    ['message', 'string', false],
    ['confirm', 'bool', true],
];

Where each array is an input. The type parameter can be either string, number or bool and is used to convert the data to the correct type. Radio inputs are not currently supported by this setup, use a select field instead where possible.

Options​

The form options describe how it sends emails on submit. An email will be sent only if to and subject have been set.

// Form options have the following type definition:
FormOptions = {
    to: null | string[],
    from: null | string,
    subject: string,
    headers: string[],
};

// Example:
$options = [
    'to' => ['to@domain.com'],
    'subject' => 'Website contact',
]

Where each array is an input. The type parameter can be either string, number or bool and is used to convert the data to the correct type.

Note: at its core, FxForm uses wp_mail to send the form and it is a requirement that each form has a subject and a message passed to it in order to send.

Last updated on