Skip to main content

Forms (Frontend)

Forms have multiple thing to setup:

Frontend:

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

Backend:

  • Validation (PHP)
  • Submission (PHP)

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

Fortunately there are a couple of things including in Fx Classes and Blank to help with creating new forms

Prerequisites​

  • fx-classes >= v3.1.0

Quick Start​

Just open Blank and duplicate one of the existing forms:

  • Template (PHP): src/templates/components/contact-form.php
  • Frontend (JS) Validation/Submission: src/assets/js/components/ContactForm.js

Change the name and id of the form in each file.

Frontend​

You can build your form however you want, but the only requirement is that the form name attribute matches that in the backend. The name attribute is used to submit the form to window.CONSTANTS.API_URL/form/:name, which is then used to determine how the form is handled.

Some optional, but recommended form elements are a message element and repeat button.

After setting up your template, you need to add some JS to validate and submit your form. This is made simple with the Form Class included in WP Blank. It will handle submission, validation, errors & success messages and repeat submissions. See the example below on how to setup a new form.

Note that the repeat button and message is optional.

Example​

Template

<form action="#" method="post" name="contact" id="contact-form">
    <div class="form-group ignore">
        <input type="text" name="ignore" autocomplete="false" />
    </div>
    <div class="form-group">
        <label for="name" class="form__label">Name</label>
        <input type="text" name="name" id="name" class="form__input" required="" />
    </div>
    <div class="form-group">
        <button type="submit" class="form__submit btn">Submit</button>
    </div>

    <div class="form__message"></div>
    <button type="button" class="form__repeat-button btn--icognito">Submit another message.</button>
</form>

Javascript

// src/components/ContactForm.js
import Form from './Form';

const contactForm = new Form(document.getElementById('contact-form'));

Options​

When setting up a form you can alter some default behaviour and messages. In most cases you will not need to pass these through, but a common example would be a newsletter signup, where the url would be different.

// src/components/ContactForm.js
import Form from './Form';

const options = {
    url: '/some/custom/endpoint', // defaults to window.CONSTANTS.API_URL/form/:name
    dynamicInputs: false,
    validateResponse(res) {
      return Boolean(res.success);
    },
    // You can pass any setting from jQuery.ajax, it will be passed on
    // http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings
};
const messages = {
    success: 'Thanks! Your message has been sent.',
    error: 'Oops! Something went wrong.',
};

const contactForm = new Form(document.getElementById('contact-form'), options, message);

options.dynamicInputs​

Default: false

Enable this option if you form adds or removes inputs dynamically.

This will ensure all inputs are validated before submission.

options.validateResponse​

Default: (res) => res.success

Use this to validate the API response.

You may need to change this if you are using another API url and the response shape is different.

Validation​

Frontend form validation is basic by default, any input with the required attribute will validated for a 'truthy' value.

To add your own frontend validation, use the Form.addCustomValidator method.

addCustomValidator(name: string, input => ({ valid: boolean, message: string }))

You can add as many custom validators as you want. Just give it an input name and validation callback. The callback receives the input node and should return an Object containing valid and message properties.

Example

<form action="#" method="post" name="contact" id="contact-form">
    <input type="tel" name="phone" class="form__input" required="" />
</form>
import Form from './Form';

const contactForm = new Form(document.getElementById('contact-form'));

contactForm.addCustomValidator('phone', (input) => {
    const value = input.value;
    return {
        valid: value && value.length > 8,
        message: 'Please enter a valid phone number',
    };
});

Methods​

Form.onSuccess​

If you need to do something after the form submits, you can use the onSuccess callback.

Example

import Form from './Form';

const contactForm = new Form(document.getElementById('contact-form'));

contactForm.onSuccess = () => {
  ga.send('event', 'Form submitted', window.location.href);
};

See the FxForm docs on how to setup your form for backend validation and submissions.

Last updated on