@superrb/kunstmaan-addons-form-handler

Kunstmaan Addons Form Handler

A JS form handler for use on the front end of Kunstmaan CMS websites.

Handles the following

• Automatic JS form submission and error handling (for forms with the attribute data-js-submit="true")
• Recaptcha by default
• Support for custom handlers to allow for third-party service integrations or additional validation

## Installation

yarn add @superrb/kunstmaan-addons-form-handler

Usage

import { FormHandler } from '@superrb/kunstmaan-addons-form-handler'

class App {
  // ...

  registerComponents () {
    this.components.formHandler = new FormHandler()
  }

  // ...
}

Custom event handlers

You have the ability to develop your own custom form handlers. See the included Recaptcha handler for an example.

import { Form, FormEventHandler, FormHandler } from '@superrb/kunstmaan-addons-form-handler'

class MyCustomHandler extends FormEventHandler {
  /**
   * @type {string}
   */
  static handlerName = 'MyCustomHandler'

  /**
   * A form name to which this handler applies - the handler is only initialised
   * on forms matching this value. Can also refer to a form group within a form
   *
   * @type {string}
   */
  static formName = 'my_custom_handler'

  /**
   * A regex which is applied to the form name, and in the case of a match,
   * the handler is initialised. Overrides formName above
   *
   * @type {RegExp}
   */
  static formNameRegex = /(_countryCode$|^countryCode$)/

  /**
   * A list of action names, which are handled
   *
   * @see this.handleAction
   *
   * @type {string[]}
   */
  handledActions = [
    'my_custom_action'
  ]

  /**
   * @param {Form} form
   * @param {Field} field
   */
  constructor (form, field) {
    super(form, field)

    // Code here is only run when either this.constructor.formName
    // or this.constructor.formNameRegex results in a match
  }

  /**
   * A handler function which is called when the submit event is fired on the form.
   *
   * The submission process is paused whilst the handler waits for a result,
   * allowing you to use this method to perform further processing before continuing
   *
   * Should return a promise which resolves to a boolean.
   *
   * If value is truthy, then form submission is allowed to continue, otherwise
   * execution is stopped
   *
   * @return {Promise}
   */
  async process() {
    // doSomething()

    return Promise.resolve(true)
  }

  /**
   * A handler function which is called when further actions are requested via
   * the API response.
   *
   * Example API response:
   *
   * {
   * . "success": false,
   *   "action_required": {
   * .   "type": "my_custom_action",
   *     "additional_data": {
   *       "key": "value"
   *     }
   *   }
   * }
   *
   * Should return a promise which resolves to a boolean.
   *
   * If value is truthy, then form submission is allowed to continue, otherwise
   * execution is stopped
   *
   * @return {Promise}
   */
  async handleAction (action) {
    if (!this.handledActions.includes(action.type)) {
      return
    }

    return Promise.resolve(true)
  }
}

Form.customHandlers.push(MyCustomHandler)
const formHandler = new FormHandler()

## Authors

• James Dinsdale (@molovo)

License

• Details on the license can be found here