Skip to main content

React Forms Processor

Tom Santiago
  • Updated
Follow

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.

Related articles

Comments

0 comments

Please sign in to leave a comment.