NOTE: v1.0 adds support for React 16.x, but since the way Mixins work in React 15, this is a fairly substantial rewrite to provide an API that doesn't use Mixins at all.
This repository contains a set of React based forms components which are used within ESnet for our network database application (ESDB), but could be used by any React based project needing to build complex forms.
Our approach is to treat a form as a controlled input, essentially an input with many inputs
(which may have many inputs, and so on...) You maintain your form's state however you want,
you pass that state down into the form as its value prop. If the form is edited, a callback
is called and you can update your form state. When it comes time to save the form, that's up
to you, you always have your form's state. On top of this the form has a schema defining rules.
Therefore, you can also listen to changes in the count of either missing values or errors.
With this information it is simple to control if the user can submit the form as well.
The library is built on Immutable.js, so form state should be passed into the form as an Immutable.Map. This allows efficient operations on your form data, minimizing copying while ensuring safety as the form state is mutated.
While part of defining a form is to specify a schema for your form, you still maintain complete
control over the layout in the form in your render() method, just like any other react app. The
schema and presentation are entirely separate. This React friendly approach makes it easy to build
forms which dynamically change values or structure based on the current state of the form.
This library contains:
- Low level forms control wrappers that communicate errors and missing values to parent components and style themselves appropriately for errors and missing value state. You can write your own in the same way. Supplied standard form controls:
- Textedit
- TextArea
- Checkboxes
- RadioButtons
- Chooser (internally we use react-select)
- TagsEdit (again using react-select)
- DateEdit (react-datepicker)
- A component that lets you define the rules for each field. Each field is specified in a component
- A component that acts as a top level controlled input for all of the form state, to assemble controls together and track state change, errors and missing values and enabling dynamic forms with via a declarative schema
- Higher Order Components:
- for grouping of controls with their labels, required state and editing control
- building lists of forms
- Inline editing
- List editing
The library is build on several other open source libraries, especially:
- react
- immutable.js
- revalidator
- react-bootstrap
- react-select
- react-virtualized
- react-datepicker
Please browse the examples for a feel for the library, or read on to get started.
Install the forms library with npm:
npm install react-dynamic-forms --save
Once installed, you can import the necessary components from the library:
import {Form, Schema, Field, TextEdit, Chooser} from "react-dynamic-forms";
A form will contain:
- Your form's state
- A schema describing the form's fields
- Implementation of render() that specified controls for each form field
- Handling of form changes, missing values and errors
- Submit logic
As the creator of the form, you bring the form's state to the table, either in the form of an initial value or previous state you're loaded up to be edited. The form state will be passed into the form via the value prop, and should be an Immutable.Map. In the examples, we just keep this on this.state, but a flux store or redux would be other options.
const ContactForm = React.createClass({
...
getInitialState() {
return {
value: Immutable.fromJS({
first_name: "Bill",
last_name: "Jones",
email: "[email protected]",
}),
};
},
...
});
A schema is specified using JSX to define the rules and meta data for each form field. As an example, here is a form that will take the first name, last name and email of a contact. The name here is the key for each value, so there would be corresponding keys in the form state (see initialValue above) and in the render of the form controls (see below). We can define also that the email should be of format email and that the first_name and last_name fields are required:
const schema = (
<Schema>
<Field name="first_name" label="First name" required={true} validation={{"type": "string"}} />
<Field name="last_name" label="Last name" required={true} validation={{"type": "string"}} />
<Field name="email" label="Email" validation={{"format": "email"}} />
</Schema>
);
In ESDB, we actually derive the schema from information we get from our server.
We've found from experience that we want a separation between schema and presentation, so instead we lay out the form out in the form component's render() function, just like any other React component, but in a way that we refer to our schema attributes using an field prop on each control.
render() {
...
return (
<Form
name="basic"
schema={schema}
value={this.state.value}
onChange={(fieldName, value) =>
this.setState({ value })}
onMissingCountChange={(fieldName, missing) =>
this.setState({ hasMissing: missing > 0 })}
onErrorCountChange={(fieldName, errors) =>
this.setState({ hasErrors: errors > 0 })}
>
<TextEdit field="first_name" width={300} />
<TextEdit field="last_name" width={300} />
<TextEdit field="email" />
<hr />
<Button className="btn btn-default" onClick={() => handleSubmit()} disabled={disableSubmit} />
</Form>
);
}
});
Things to note here:
- The schema is supplied to the Form with the
schemaprop - The current state of the form is supplied with the
valueprop. - The value is updated by listening to the
onChangecallback. - Value's state is potentially invalid, because it will at times likely reflect that the user has partially filled out a form (i.e. may contain missing values) or has filled out a field with an error. For this reason we listen to
onMissingCountChangeandonErrorCountChangeto keep our form updated with respect to form validity.
Given what you know now, you should be ready to start building a form. Please also see the examples for how you can control the appearance of the form using tags specified in the schema as well as how to create lists.
Within a forked repo, you first need to run:
lerna bootstrap
This will install the development dependencies into your node_modules directory.
You can then start up the test server, as well as automatic source building, by doing:
cd packages/website
npm run start
To build the lib directory, use:
cd packages/react-dynamic-forms
npm run build
Thanks to Chromatic for providing the visual testing platform that help us catch unexpected changes on time.
This code is distributed under a BSD style license, see the LICENSE file for complete information.
ESnet's React Dynamic Forms Library, Copyright (c) 2015-2017, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Technology Transfer Department at [email protected].
NOTICE. This software is owned by the U.S. Department of Energy. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, and perform publicly and display publicly. Beginning five (5) years after the date permission to assert copyright is obtained from the U.S. Department of Energy, and subject to any subsequent five (5) year renewals, the U.S. Government is granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.