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:

| Type | Description | Example | | ---- |------------ | ------- | | text (default) | A text string | Hello World | | number | A number | 7.2 | | blob | Can be any type. Doesn't really have validation | { a: 'b' } | | email | An email address | [email protected] | | alphanum | A combination of numbers and letters | ABC123 | | ip | A valid ip address | 21.34.106.99 | | uri | A complete URL | http://www.abc.com/index.html |

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

| Option | Description | Autocorrects? | fieldTypes | | ------ | ----------- | ------------- | ---------- | | required | is this value required | No | all | | default | the default value | N/A | all | | min | the min value (number fieldType) or min string length | (for numbers) | all | | max | the max value (number fieldType) or max string length | Yes | all | | greater | number must be greater than the value | Yes | number | | less | number must be lest than the value | Yes | number | | length | absolute string length | No | text | | regex | string must match provided regular expression | No | text | | integer | enforces the number must be an integer (no decimals) | Yes | number | | precision | the number must have fewer decimal points than this | Yes | number | step | the amount jump when clicking the up and down chevrons | N/A | number

Selectors

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

| Selector | Input | Description | | -------- | ----- | ----------- | | value | state | Returns the current value for the field. | | error | state | Returns an error if the data is invalid and the whenToValidate event has triggered. | isInvalid | state | Is the data currently invalid (reguardless of the whenToValidate flag) | isDirty | state | has the value changed from the source/default value | changeAction | value to change to | an action that can be dispatched to update the field's value | | resetAction | none | action to dispatch to reset the stored value of the field | state | state | pulls all the data needed to display the field into an object | handlers | dispatch | pulls all the event handlers needed to react to the field into an object

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:

| Selector | Input | Description | | -------- | ----- | ----------- | | state | state | returns the full state of all the form's fields | handlers | dispatch | returns all the handlers of all the form's fields | export | state | prepares data for an external service, listing all the current values | isInvalid | state | is true if any field is invalid (reguardless of the whenToValidate flag) | isDirty | state | is true if any field is dirty | resetActions | the full list of reset actions that should be triggered to reset the form

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?");
}