formaldehyde

Formaldehyde

What

React form creation/validation/population. Supports top-down rendering with input population. Keeps the immutable data structures mindset.

Why

We needed something elegant for creating forms and inputs that self populate, require no state, and at a input AND form levels, have easy use for validation.

How

Install

$ npm i formaldehyde

# CreateUserForm.js
import React from 'react';
import { Form, Input, SubmitButton } from 'formaldehyde';

export default class CreateUserForm extends React.Component {
  onSuccess (result) {
    // if there is no action on the Form or if it returns nothing, this gets called immiediately
    // otherwise if the action returns a promise, it will wait for it to finish
    // the result is the result of the promise.
    this.props.navigate(result.id);
  }

  onFormValidate (model) { // this function returns an array of errors.
    const errors = [];
    if (!model.agree) {
      errors.push('You need to agree to the terms');
    }
    return errors;
  }

  render () {
    return (
      <Form action={ this.props.action } onSuccess={ ::this.onSuccess } validateForm={ ::this.onFormValidate } model={ {} } showValidationErrors>
        <p>
          <Input type="text" name="full_name" placeholder="Full Name" required />
        </p>
        <p>
          <Input type="checkbox" name="agree" /> 
        </p>
        <p>
          <SubmitButton className="button">Create User</SubmitButton>
        </p>
      </Form>
    );
  }
}

How do input's get their data?

The built-in formaldehyde inputs use their name prop to get data off of the Form's model prop object.

So if <Form model={{ product: { name:'formaldehyde' } }}> has a child Input that looks like <Input name="product.name" /> it will get the model's product.name, "formaldehyde". It will pre-populate the input with that data as well as use that to set the model when it is being submitted.

How do I make my own custom input?

Since Formaldehyde uses React Context, you will need to implement registering the component, unregistering it, and getting the data from your component when its about to be submitted or validated.

  static contextTypes = {
    registerFormControl: PropTypes.func.isRequired,
    unregisterFormControl: PropTypes.func.isRequired,
  };

We will register the component on componentDidMount and unregister on componentWillUnmount. Here is an example of the most simple way to handle it.

export default class MyIput extends React.Component {

  static contextTypes = {
    registerFormControl: PropTypes.func.isRequired,
    unregisterFormControl: PropTypes.func.isRequired,
  };

  constructor (...args) {
    super(...args);
    this.state = {};
  }

  componentDidMount () {
    this.context.registerFormControl(this);
    if (this.props.autofocus) {
      this.refs.input.focus();
    }
  }

  componentWillUnmount () {
    this.context.unregisterFormControl(this);
  }
}

Now we will need to implement the method getValue that the Form will use to gather the data, remember it will automatically read the prop name passed to your custom input.

export default class MyIput extends React.Component {
  static contextTypes = {
    registerFormControl: PropTypes.func.isRequired,
    unregisterFormControl: PropTypes.func.isRequired,
  };

  constructor (...args) {
    super(...args);
    this.state = {};
  }

  componentDidMount () {
    this.context.registerFormControl(this);
    if (this.props.autofocus) {
      this.refs.input.focus();
    }
  }

  componentWillUnmount () {
    this.context.unregisterFormControl(this);
  }

  getValue () {
    return this.state.value; // getValue is automatically invoked after being register when the Form is submitted.
  }
}

Okay, how do I pre-populate my data from the model, because I'm editing an existing model!

So we have another context call back we can use. getFormModelValue(name).

export default class MyIput extends React.Component {
  static contextTypes = {
    registerFormControl: PropTypes.func.isRequired,
    unregisterFormControl: PropTypes.func.isRequired,
  };

  constructor (props, context) {
    super(props, context);
    this.state = {
      value: context.getFormModelValue(props.name), // preload
    };
  }

  componentDidMount () {
    this.context.registerFormControl(this);
    if (this.props.autofocus) {
      this.refs.input.focus();
    }
  }

  componentWillUnmount () {
    this.context.unregisterFormControl(this);
  }

  getValue () {
    return this.state.value; // getValue is automatically invoked after being register when the Form is submitted.
  }
}

Now this is a simplified way to do it, you will need to intercept updated componentWillReceiveProps to re-set state, or in our case, we don't really use state for our inputs. Checkout the Input.js code for how that is handled without state.