immutable-core-model-form

Immutable Core Model Form provides a Class for defining forms for Immutable Core Models.

Immutable Core Model Form instances are constructed with defaults based on the schema of the Immutable Core Model the form is for. These defaults can then be overriden to customize the form.

Native async/await

Immutable Core Model Form requires Node.js v7.6.0 or greater with native async/await support.

Creating a Form From a Model

const ImmutableCoreModel = require('immutable-core-model')
const ImmutableCoreModelForm = require('immutable-core-model-form')

var addressModel = new ImmutableCoreModel({
    name: 'address',
    properties: {
        addressCountry: {
            default: 'US',
            title: 'Country',
            type: 'string',
        },
        addressLocality: {
            title: 'City',
            type: 'string',
        },
        addressRegion: {
            enum: ['AL', 'AK', 'AZ'],
            title: 'State',
            type: 'string',
        },
        firstName: {
            type: 'string',
        },
        lastName: {
            type: 'string',
        },
        postalCode: {
            errors: {
                pattern: '5 digit ZIP code required',
            },
            pattern: '^\\d{5}$',
            title: 'ZIP Code',
            type: 'string',
        },
        streetAddress: {
            type: 'string',
        },
    },
    required: [
        'addressCountry',
        'addressLocality',
        'addressRegion',
        'firstName',
        'lastName',
        'postalCode',
        'streetAddress',
    ],
})

var addressForm = new ImmutableCoreModelForm({
    fields: [
        ['firstName', 'lastName'],
        'streetAddress',
        [
            {
                property: 'addressLocality',
                unit: '3-5',
            },
            {
                property: 'addressRegion',
                unit: '1-5',
            },
            {
                property: 'postalCode',
                unit: '1-5',
            },
        ],
        {
            property: 'addressCountry',
            inputType: 'hidden',
        },
    ],
    model: fooModel,
})

In this example an address model is created with property names based on Schema.org Postal Address.

The enum, default, description, title and type from the JSON Schema for the model will be used to populate default form options.

Fields

The fields array contains field specifications in the order that they will be presented in the from.

A field can be specified as either the name of the model property that the field maps to or an object that contains the property along with other configuration options.

A field group can be specified by providing an array value for the field. This array must consist of either string property names or object field specifications.

Creating a From Without a Model

var registerForm = new ImmutableCoreModelForm({
    fields: [
        {
            inputType: 'text',
            name: 'firstName'
            placeholder: 'First Name',
            required: true,
        },
        {
            inputType: 'text',
            name: 'lastName'
            placeholder: 'Last Name',
            required: true,
        },
        {
            inputType: 'text',
            name: 'email'
            placeholder: 'Email',
            required: true,
        },
        {
            inputType: 'password',
            name: 'password'
            placeholder: 'Password',
            required: true,
        },
    ],
    method: 'post',
    submit: {
        title: 'Register',
    },
})

Form Properties

name | description | ----------------|--------------------------------------------------------------| action | action property for form element - url form will submit to | fields | list of form fields may be field or sub-list of fields | id | id property for form element | enctype | enctype property for form element | method | method property for form element | submit | object with submit properties - if false will not render | submit.title | text value for submit button |

Field Types

name | ----------------| checkbox | color | hidden | password | select | text |

Field Properties

name | description | ----------------|--------------------------------------------------------------| description | description that will be shown in help tooltip | id | input id property, needed to link label to input | inputSize | size property for input | label | text that will be shown as label - false for no label | name | input name property | pattern | regex pattern for validating input value | placeholder | placeholder to display in input - false for none | readonly | make input read only | required | make input required |

Units

The unit option is used by the default Immutable App form view to set the grid units that a field in a field group occupies. Immutable App uses Pure CSS Grids.

If the unit option is not specified then it will be defaulted to 1-n where n is the number of fields in the field group.

Creating a form instance from a record

addressForm.newInstance({record: record})

When the newInstance method is called with a model instance a form instance with values populated from the existing model will be returned.

Creating a form instance from input and errors

addressForm.newInstance({
    errors: errors,
    input: input,
})

If form submission results in errors then newInstance can be called with the form input and errors to create a new form instance with correct values and error messages populated.