reformation-js

A simple library for generating html forms from JSON Schema using React and Bootstrap.

Installation

To install reformation-js:

npm install reformation-js

Form

The Form component is the primary interface for reformation-js.

| Prop | Type | Required | Description | | :--- | :--- | :--- | :--- | | schema | Object | true | A JSON Schema object representing the form you wish to render | | formState | Object | false | A Representation of the current state of the form | | formErrors | Object | false | Form related errors | | onChange | Function | false | A function triggered when a field's value is changed | | header | String | false | Text to be displayed in the header above the form | | validator | AJV Instance | false | Optional instance of modified AJV validator. |

onChange

When data has changed on a field inside of Form the onChanged method will be called with an object with the following format passed in as it's argument:

| Attribute | Description | | :-- | :-- | | path | The JSON Schema path of the data that has changed. | | field | The key of the field that has changed. | | value | The new value of the field. | | event | The original event that triggered the change. |

A Note On validator

AJV is an extremely rich library and has the ability to customize it's behavior. An example of this would be the ability to add your own custom formats. To prevent you from having to chose between Reformation and AJV we allow you to bring your own copy. If you don't wish to bother though, don't worry. Reformation packs it's own vanilla instance of AJV and has you covered!

JSON Schema interpretation

JSON Schema Keywords

Several JSON Schema keywords are used to determine how the form should be renderd.

Keyword: type

Determines what type of field will be rendered. Can be overwritten.

Keyword: title

Will be rendered as the form field's label if present.

Keyword: description

Will be used as a placeholder on a text input if present.

Custom Meta Attributes

reformation-js provides the ability for extra meta data about the form to be embeded in an object in the provided schema by using the attribute formMeta. The following keywords are recognized.

size

Sets the sixe of the input field created.

| Values | | :-- | | xSmall | | small | | medium | | large | | full |

viewAs

Allows control of the field type by overriding the default.

| Values | | :-- | | radioButtons | | textField | | select |

Examples

Rendering a form from a JSON Schema

import React from 'react';
import Form from 'reformation-js';
import 'bootstrap/dist/css/bootstrap.css';
import someValidSchema from './honestlyValidJsonSchema.json';

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      formData: {
        fieldOne: 'default',
        fieldTwo: 'anotherDefault',
      }
    };
    this.handleChange = this.handleChange.bind(this);
  }

  handleChange(data) {
    const {
      formData
    } = this.state;

    const {
      field,
      value,
      event,
    } = data;

    const newFormData = {
      ...formData,
      [field]: value,
    };

    this.setState({
      formData: newFormData
    });
  }

  render() {
    const {
      formData
    } = this.state;

    return (
      <Form
        header="My Amazing Form"
        schema={someValidSchema}
        formState={formData}
      />
    )
  }
};

export default App;

Creating a reducer and action creators using reducerFactory

import { reducerFactory } from 'reformation-js';

const initialState = {
  data: { state: 'NC' },
  errors: {}
};

const namespace = 'simpleForm';

const duckObject = reducerFactory({ namespace, initialState });

const reducer = duckObject.createReducer();

export { actionCreators };
export default reducer;

Passing custom errors to a form

reformation-js accepts custom errors provided by the parent application. These errors can be passed using the formErrors prop and is expected to be an object that mirrors the structure of the forms data with the error message provided in place of the form's data. For example, using the schema below if wanted to provide a custome error message to the street field you would provide a json object with the following form:

{
  "street": "My custom error here."
}

A more complete example is located after the schema.

Example Schema

{
  "title": "Simple Address",
  "type": "object",
  "properties": {
    "street": {
      "type": "string",
      "title": "Physical Address",
      "description": "123 Main Street",
      "formMeta": {
        "size": "small"
      }
    },
    "city": {
      "type": "string",
      "title": "City",
      "description": "Metropolis",
      "formMeta": {
        "size": "small"
      }
    },
    "state": {
      "$ref": "#/definitions/states",
      "formMeta": {
        "size": "xSmall"
      }
    },
    "zipcode": {
      "type": "string",
      "title": "Zip",
      "description": "12345-6789",
      "formMeta": {
        "size": "xSmall"
      }
    }
  },
  "required": ["street", "city", "state", "zipcode"],
  "definitions": {
    "states": {
      "type": "string",
      "title": "State",
      "enum": [
        "Alabama",
        "Alaska",
        "Arizona",
        "Arkansas",
        "California",
        "Colorado",
        "Connecticut",
        "Delaware",
        "District Of Columbia",
        "Florida",
        "Georgia",
        "Guam",
        "Hawaii",
        "Idaho",
        "Illinois",
        "Indiana",
        "Iowa",
        "Kansas",
        "Kentucky",
        "Louisiana",
        "Maine",
        "Maryland",
        "Massachusetts",
        "Michigan",
        "Minnesota",
        "Mississippi",
        "Missouri",
        "Montana",
        "Nebraska",
        "Nevada",
        "New Hampshire",
        "New Jersey",
        "New Mexico",
        "New York",
        "North Carolina",
        "North Dakota",
        "Ohio",
        "Oklahoma",
        "Oregon",
        "Pennsylvania",
        "Rhode Island",
        "South Carolina",
        "South Dakota",
        "Tennessee",
        "Texas",
        "Utah",
        "Vermont",
        "Virgin Islands",
        "Virginia",
        "Washington",
        "West Virginia",
        "Wisconsin",
        "Wyoming"
      ]
    }
  }
}

Example custom error

import React from 'react';
import Form from 'reformation-js';
import 'bootstrap/dist/css/bootstrap.css';
import addressSchema from './addressSchema.json';

const startingFormData = {
  street: '225 N Trade St',
  city: 'Matthews',
  state: 'North Carolina',
  zipcode: '28105-'
};

const formErrors = {
  zipcode: 'Any error you please'
};

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      formData: startingFormData,
      formError: formErrors
    };
    this.handleChange = this.handleChange.bind(this);
  }

  handleChange(data) {
    const {
      formData
    } = this.state;

    const {
      field,
      value,
      event,
    } = data;

    const newFormData = {
      ...formData,
      [field]: value,
    };

    this.setState({
      formData: newFormData
    });
  }

  render() {
    const {
      formData,
      formErrors
    } = this.state;

    return (
      <Form
        header="address"
        schema={addressSchema}
        formState={formData}
        formErrors={formErrors}
        onChange={this.handleChange}
      />
    )
  }
};

reducerFactory

reformation-js includes a helper function exported as reducerFactory to facilitate quick and easy creation of reducer functions to be used with reformation-js. This helper function is in no way a dependency of reformation-js but does provide a convenient way to quickly handle data through the usage of gaearon's excelent redux library.

Arguments

reducerFactory expects exactly two areguments when called:

| Arguments | Type | Description | | :-- | :-- | :-- | | namespace | String | The namespace used to scope action types. | | initialState | Object | Initialization state for the form. |

Output

When called reducerFactory will return an object with the following structure:

| Attribute | Type | Description | | :-- | :-- | :-- | | createReducer | Function | A factory function that will return a new reducer function when called. | | actionTypes | Object | A collection of namespaced action types used by the outputted reducer of createReducer. | | actionCreators | Object | A collection of actionCreators for use of the outputted reducer of createReducer. |

FormFieldFactory

reformation-js includes a helper function to allow it's features to be used on fields that exist outside of the normal layout of the form.

Arguments

FormFieldFactory expects the following arguments when called:

| Arguments | Type | Description | | :-- | :-- | :-- | | schema | Object | The JSON Schema used to describe the form. | | validator | AJV Instance | Optional custom AJV Instance. |

Output

When called FormFieldFactory will return a React component that expects the following props:

| Prop | Type | Description | | :-- | :-- | :-- | | path | String | The path of the field in the JSON Schema object. | | formState | Object | The current state of the form. | | formErrors | Object | The current errors in the form. | | handleChange | Function | A function to be called when a field changes. | | isRequired | Boolean | Boolean indicating if the field is required. |