cerebral-form

#Cerebral Form

##Philosophy: The inputs are first class citizens, not the "form". You determine where their state lives, and what forms, if any, they connect to.

##Known Issue: If one input needs to be re-validated after another input changes, that can work via the "linkTo" option. The linkTo option currently only supports just 1 linked input per input.

##Usage: npm i -S cerebral-form

import InputWrapper from 'cerebral-form/InputWrapper'; //The wrapper is for react only, but could easily be ported to another UI lib
var MyInput = InputWrapper(function MyInput (props) {
  return (
        <input {...props}>
        </input>
    );
},{
  path: ['path','you','choose'], //the **only** required property. Input state is stored at this path
  form: 'form1', //or  ['form1','form2'] register the input with one or more forms
  validation: {
    'isEmail': "Please provide a valid email", //name and message of desired validation
    'userDefined': "This field must match another user defined field"
    'validationWithOptions': {
    	anything: 'canGoHere'
    	message: "This field must match another user defined field"
    }
  },
  asyncValidation: 'isNonGmail', //can only register 1 async validation per form
  validateImmediately: false, //by setting this to false, validation will only occur after the element has been visited, instead of on every change
  linkTo: ['anotherInput'] //re-run the validation for the input at path ['anotherInput'] whenever this element is modified
})

A list of available props available to the input are:

• onChange: function onChange()
• onBlur: function onBlur()
• value: "hahah"
• completed: false //false unless default value provided
• errors: { isEmail: "Please provide a valid email" }
• hasError: false
• visited: false
• checked: false

##Checking if a form has been completed:

import {formCompleted} from 'cerebral-form'; //this is a cerebral computed function
@Cerebral(formCompleted: formCompleted('form1')}) //use it like a normal computed function, passing the name of the form

##Hooking up the module + setting up validation:

import CerebralForm from 'cerebral-form';
import validator from 'validator'; 
controller.modules({
	cerebralForm: CerebralForm({
		validation: { //define simple validations here
			...validator, //use an external library like "validator" for many built in validations
			isEmail: function (value, state, options) { //define your own validations as well
				if (value.indexOf('@') > -1) {
					return true //no error
				} else {
					return false //error
				}
			}, 
			userDefined: function (value, state, options) {
				if (value === state.get('userDefinedString')) { //access any other values withing the state tree
					return true
				} else {
					return false
				}
			}
			validationWithOptions: function (value, state, options) {
				console.log(options.anything)
				// "canGoHere"
				return true;
			}
		},
		asyncValidation: { //define async validations here as cerebral action chains
			isNonGmail: [
		        [function({
		          input, output
		        }) {
		          //fake talking to backend
		          setTimeout(function() {
		            if (input.value.indexOf('gmail') > -1) {
		              output({
		                asyncError: {
		                  message: 'The email ' + input.value + ' cannot have gmail in the name'
		                }
		              })
		            } else {
		              output()
		            }
		          }, 300)
		        }]
		      ]
		}
	}),
});