The React Forms Processor allows you to create a form where updates in one field can change the attributes of another without requiring you to write the code to implement that relationship.
Note: This project uses the new React Context API, so you are required to use at least version 16.3 of React.
For example, if you have one field that is only visible when another has a certain value (i.e. a checkbox being checked), then you can define this through a simple specification. You can configure when fields are visible, disabled, required and if their value should be included in the overall form value based on other field values.
Contents
Install React Forms Processor
- Core engine:
yarn add react-forms-processor
- Atlaskit renderer:
yarn add react-forms-processor-atlaskit
You can import and use the Form and FormFragment components from the core module, but you should also import and use the FormButton component from the Atlaskit renderer.
For example:
<Form defaultFields={myFieldsDefinition}
renderer={atlaskitRenderer}
optionsHandler={myCustomOptionsHandler}>
<FormButton label="Save" onClick={value => doSomethingWithTheFormValue()}/>
</Form>
You can also split across fragments:
<Form renderer={atlaskitRenderer}
optionsHandler={myCustomOptionsHandler}>
<FormFragment defaultFields={definition1} />
<FormFragment defaultFields={definition2} />
<FormButton label="Save" onClick={value => doSomethingWithTheFormValue()}/>
</Form>
External links
Validation
The validity of all fields determines the form's overall validity state:
- If a required field is empty, then the form is invalid.
- If the value of a field fails to pass the declared validation rules, then the form is invalid.
- Invalid fields that are not visible do not affect form validity.
Defined validation rules
The React Forms Processor has rules for the following:
- Regular Expression (regex) matching
- Minimum and maximum character length
- Minimum and maximum numerical range
Note: In future releases, Celigo will add more validators along with the ability to provide a custom validation handler.
Declare static options
You can declare static options for a field in its definition. You can provide the form component with an options handler function that allows you to return options for a field that might be related to the value of other fields. This enables you to return promises of options if you're fetching them via an XHR request.
Note: In future releases, Celigo will expand this functionality to allow you to define URLs to retrieve options from.
Available fields
The React Forms Processor abstracts the logic of forms processing away from the rendering implementation. The processor includes an Atlaskit renderer, but Celigo's development team will add more renderers in the future. You can also write you own by matching a field type to a React field implementation and mapping the properties provided. You can use any fields available in another library or write your own custom fields.
The fields that are currently available in the Atlaskit renderer are:
- text
- textarea
- checkbox
- select
- multiselect
- radiogroup
Field layout
You can build a form from multiple fragments that each have their own definition, but the form aggregates those definitions. This means that you can split each field across multiple tabs or collapsible sections. The ID of each field is used in the DOM, so you can write custom CSS selectors for fine-grained control over a field's position and appearance. You can also place button components anywhere within the context of a form.
Define fields
A field is a simple JavaScript object. The current set of attributes you can use in that object are:
| Attribute | Description |
| id | A unique ID for the field. |
| name | The attribute that the field value will be assigned to. You can share this attribute with multiple fields. |
| type | The type of field. Renderers use this attribute to map the field to a specific field component. |
| defaultValue | An initial value for the field. |
| label | The label for the field. |
| description | A description of the field. |
| placeholder | Placeholder text for fields that support placeholder text functionality. |
| required | Determines if a value for the field is required or optional. |
| visible | Whether or not the field can be seen by an end user. |
| disabled | Whether or not the field is disabled. |
| trimValue | Whether or not leading and trailing whitespace should be trimmed from the value. |
| visibleWhen | Rules that define when the field should be visible. |
| requiredWhen | Rules that define when a value for the field must be provided. |
| disabledWhen | Rules that define when the field is disabled. |
| options | A static list of options for fields that support options. You can provide dynamic options through a function handler passed as a property to the form. |
| omitWhenHidden | Indicates whether the field value should be included in the form value when the field is hidden. |
| omitWhenValueIs | Possible values of the field that should not be included in the form value. |
| useChangesAsValues | When multiple options can be set as values, this sets the changes as values rather than the final list of options. |
| valueDelimiter | When multiple options can be set as values, this converts the array into a string delimited by this value. |
| addedSuffix | When using changes as values, this string is appended to the name for the added values. |
| removedSuffix | When using changes as values, this string is appended to the name for the removed values. |
| misc | Any else. |
Note: You can build and render forms dynamically in an application because you can declaratively define the forms. For an example, see the React Forms Processor demo.
Comments
4 comments
Testing comment flow - 149 Tues - React forms proc article
Testing comment flow - 445 Wed - react article
Testing comment flow - 804 thurs - react article
Testing comment flow - 1038 thurs - react article
Please sign in to leave a comment.