Skip to content

Latest commit

 

History

History
191 lines (156 loc) · 5.97 KB

Form.md

File metadata and controls

191 lines (156 loc) · 5.97 KB
Raw

@squirrel-forge/ui-form

Back to table of contents

Documentation

Javascript / Form

Table of contents <[ Form ]> Plugins

Table of contents

FormValues

FormValues class - Class for handling form input values.

Class overview

class FormValues {
  static input_info( name, value ) {} // Object
  static convert_from_flat( values ) {} // Object
  constructor( form, includeDisabled = false, debug = null ) {}
  debug : null|Console
  form : HTMLFormElement
  includeDisabled : Boolean
  setAsDefault : Boolean
  get( flat = false, selector = 'input, select, textarea' ) {} // Object
  set( values, flat = false, errors = true ) {} // void
  inputs( field, errors = true ) {} // Array|NodeList
}

For more details check the FormValues source file.

Html5Validator

Html5Validator class - Class for handling form field validation via html5 methods.

Class overview

class Html5Validator {
  constructor( form, fields = 'input, select, textarea', debug = null ) {}
  errorAttribute : string
  reset() {} // void
  data() {} // Html5Validator
  valid( only ) {} // boolean
  errors() {} // null|Object
}

For more details check the Html5Validator source file.

UiFormComponent

UiFormComponent class - Async form component with events and plugins support. The component extends UiComponent from @squirrel-forge/ui-core module.

Component settings

Component settings might be changed or extended through plugins.

const defaults = {

    // Run in async mode, default true
    // @type {boolean}
    async : true,

    // AsyncRequest default options see @squirrel-forge/ui-util for details
    // @type {Object}
    asyncOptions : {},

    // Skip validation code
    // @type {boolean}
    skipValidate : true,

    // Pure HTML5 validation only, no plugins will run
    // @type {boolean}
    validatePureHtml5 : false,

    // Validation report level
    // @type {boolean}
    validateReport : true,

    // Default state
    // @type {string}
    defaultState : 'initialized',

    // Default event
    // @type {string}
    defaultEvent : 'initialized',

    // States that allow the form to be sent
    // @type {Array<string>}
    sendableStates : [ 'initialized' ],

    // Reset the form if async submit encountered an error
    // @type {boolean}
    resetOnError : true,

    // Do only soft reset on error
    // @type {boolean}
    resetOnErrorSoft : true,

    // Add the submit button value to async request if available
    // @type {boolean}
    addSubmitValue : true,

    // Fake/hidden submit button used for internal submit handling
    // @type {string}
    fake : '<button data-ui-form-fake-submit ... />',

    // Dom references
    // @type {Object}
    dom : {

        // Reset buttons
        // @type {string}
        reset : 'button[type="reset"], input[type="reset"]',

        // Submit buttons
        // @type {string}
        submit : 'button:not([type]), button[type="submit"], input[type="submit"]',

        // Fake/hidden internal submit button created through the fake option
        // @type {string}
        fake : '[data-ui-form-fake-submit]',
    }
};

Class overview

class UiFormComponent extends UiComponent {
  static selector : String
  constructor( element, settings = null, plugins = [], extend = [], init = true, debug = null ) {}
  valid : Boolean
  clickedSubmit : null|HTMLButtonElement
  init() {} // void
  bind() {} // void
  bindResets( resets ) {} // void
  bindSubmits( submits ) {} // void
  isValid( report = false ) {} // boolean
  canSubmit() {} // boolean
  submit( silent = false ) {} // boolean
  abortSubmit( reset = true, soft = true ) {} // void
  reset( soft = false ) {} // void
}

For more details check the UiFormComponent source file.

Events

  • submit.click - Fired after submit button click has validated the form, can be prevented with event.preventDefault() and form submission will not continue.
  • before.submit - Fired before any data is sent, can be prevented with event.preventDefault(). You may also prevent submission by calling preventDefault() on the regular form submit event.
  • async.modify - Fired when the async request is ready to be sent, data can be modified, but the sending process cannot be aborted.
  • sending - Fired when form has started to send data.
  • progress - Fired when upload progress is made when sending files.
  • error - Fired when the async request received an error response.
  • success - Fired when the async request received a success response.
  • complete - Always fired after the error or success events.
  • reset - Fired when the UiFormComponent.reset() method is called.

Using the component

For details refer to the settings, class overview and code file mentioned above.

import { UiFormComponent } from '@squirrel-forge/ui-form';

// Will initialize a specific form
UiFormComponent.make( document.querySelector( '.ui-form' ) );

// Will initialize all forms in the current document
UiFormComponent.makeAll();

Component markup

Following markup is required for an async form.

<form is="ui-form" class="ui-form" action="" method="post" enctype="multipart/form-data"></form>

Set a JSON config the following way:

<form data-config='{"option":{"name":true},"optionName":true}'></form>

Set individual config options via following attribute syntax:

<!-- Will resolve to: option.name & optionName = true -->
<form data-option-name="true"></form>

Table of contents <[ Form ]> Plugins