@airglow/prefab-form v0.8.0

Prefab-Form

A custom Prefab for dealing with forms and form elements. The basic Value Prefab let's you set and get the value. The FormField prefab adds in bells and whistles like validation.

Installation

npm install --save @airglow/prefab @airglow/prefab-form

Getting Started

To add Form Prefabs, you simply need to import the prefab somewhere in your code:

import '@airglow/prefab-form';

Now you're ready to go.

FormField Prefabs

You may choose to use the FormField Prefabs directly:

import prefab from '@airglow/prefab';

export default prefab({
  toppings: {
    type: 'formField',
    defaultValue: 'cheese',
    required: true,
    whenToValidate: 'blur'
  },
  size: {
    type: 'formField',
    fieldType: 'number',
    defaultValue: 2,
    max: 15,
    autocorrect: 'immediate'
  }
});

Here we're creating two FormField Prefabs. One is a text field and one is a number field. Let's go into details on the various configuration options for the form fields.

fieldType

The following lists the supported values for fieldType:

whenToValidate

You may use the whenToValidate option when configuring your form fields to determine when you want validation to occur.

The following are valid options for whenToValidate:

• always: will always show validation errors, even before editing
• focus: will show validation errors as soon as an element is clicked on
• blur: will show validation errors after clicking outside the elemeent
• submit: only starts showing validation errors once the user submits the form
• never: never show validation errors

Errors will be passed when selecting your form fields if there is a validation error and the whenToValidate event has occured.

autocorrect

When enabled, your form fields can attept to autocorrect invalid values. For example, if the maximum number for a field is 30 and a user enters 35, the value will change to 30 if autocorrect is enabled.

The following are valid options for autocorrect:

• disabled: never autocorrect
• enabled: autocorrects on a blur event
• immediate: autocorrects as the field recieves input.

sourceSelector

Defines a selector that should be called to get the current (undirty) data for the form. The selector will get the current state passed in:

export default prefab({
  quantity: {
    type: 'formField',
    sourceSelector: state => state.originalData.quantity,
  }
});

Aditional Options

Selectors

The a FormField prefab provdies a bunch of different selectors you can pass into your views:

Form

The Form Prefab is a convientient way to group a set of FormField Prefabs together:

import prefab from '@airglow/prefab';

export default prefab({
  pizzaOrder: {
    fields: {
      toppings: {
        defaultValue: 'cheese',
        required: true,
        whenToValidate: 'blur'
      },
      size: {
        fieldType: 'number',
        defaultValue: 2,
        max: 15,
        autocorrect: 'immediate'
      }
    }
  }
});

Field Names

To avoid name conflicts, inside your store, the form field data will be stored at <FORM NAME>#<FIELD_NAME>.

When selecting data for the view, the fields will be <FIELD_NAME>Field, unless you provide a fieldName property in the FormField's config.

When exporting data, the field will just be <FIELD_NAME>, unless you provide an externalName property in the FormField's config.

Form Options

The whenToValidate, autocorrect, and sourceSelector options can be provided in the Form's config. All FormFields will default to these values unless an override is provided.

For sourceSelector you'll need to return the full source in an object like:

export default prefab({
  pizzaOrder: {
    fields: {
      toppings: { },
      size: {
        fieldType: 'number'
      }
    }
  },
  sourceSelector: state => ({ toppings: 'cheese', size: 'M' })
});

localKeys

When preparing the data for the server, all fields will be included in the resulting object. You may use the localKeys option to provide an array of fields to omit. For example: localKeys: [id].

Form Selectors

The Form provides a few selectors that map all of the child selectors:

hasAnyDirty

There is a utility that let's you see if there are any dirty forms anywhere in the system. This is useful for latching onto browser navigation events and prompt with a "Unsaved Data! Are you sure want to leave?" sort of dialog.

import { hasAnyDirtyForms } from '@airglow/prefab-form';

if (hasAnyDirtyForms(state)) {
  console.alert("Unsaved Data! Are you sure want to leave?");
}