Bo$$Key

Bo$$Key is a Redux form library that generates a form reducer and container given a simple specification.

##Overview

1. Installation
2. API

##Installation

npm install --save basquiat 

API

Bo$$Key exports a single function with the following signature: config => [ formReducer, formContainer ]

Configuration

The config Bo$$Key accepts is an object with the following keys:

  {
    component,
    statePath,
    fieldMap,
    hydrate,
    onSubmit,
  }

component

type: React Component

The form component that you want wrapped by Bo$$Key.

Example

 const LoginForm = ({
  email,
  password,
  errors,
  onSubmit,
  processEmailOnChange,
  processEmailOnBlur,
  processPasswordOnChange,
  processPasswordOnBlur,
}) => (
  <form method="POST" onSubmit={onSubmit}>
      <input
          type="text"
          value={email}
          onChange={processEmailOnChange}
          onBlur={processEmailOnBlur}
      />
      
      <p className="form-error">{errors.email}</p>

      <input
          type="password"
          value={password}
          onChange={processPasswordOnChange}
          onBlur={processPasswordOnBlur}
      />
      
      <p className="form-error">{errors.password}</p>

      <button type="submit">Submit</button>
  </form>
)

statePath

type: [String] | String

The statePath specifies where in the Redux tree to find the form's state.

Examples

Simple Example

{
  ...,
  bo$$Form: formState
}

If the Redux tree has the above shape, the correct statePath would be:

"bo$$Form"

Nested Example

{
  ...,
  involedForm: {
    lessInvolvedForm: {
      bo$$Form: formState
  }
}

If the Redux tree has the above shape, the correct statePath would be:

['involvedForm', 'lessInvolvedForm', 'bo$$Form']

fieldMap

type: the fieldMap is a nested object with the following shape:

  {
    fieldName: {
     checks: check | [check],
     streamTransformation: [String],
     blurTransformation: [String],
     inititialValue: Any,
     optional: Boolean
    }
  }

Every key in a field's config is optional. If you don't need to specify anything, simply set the field to null, and it will default to the following configuration:

  fieldName: {
    checks: [requiredCheck],
    initialValue: '',
    optional: false
  }

checks

A check is an array of two functions.

The first function is a predicate that takes the field's value, and asserts a property.

The second function takes the field's name, and returns an error message. If the first function returns false, then the error message returned by the second function is set as the field's error.

You can specify a single check, or an array of checks. If you specify an array of checks, then the error message for the field will be the one produced by the first check to fail.

If you don't specify a field as optional, the requiredField check, which is defined interally is automatically set.

The requiredField check looks something like this:

[
  value => !isEmptyField(value),
  field => `${field} is a required field`
]

Example

const threeToTwenty = [
  [
    value => /^.{3,20}$/.test(value),
    field => `${field} must be 3 to 20 characters`
  ]
];

streamTransformations

Redux Transform is a peer dependency for Bo$$Key.

streamTransformations is an array that specifies the transformations you want to perform to the value onStream (i.e. onChange).

Example

['trim', 'capitalize', 'singleSpace']

blurTransformations

Exactly like streamTransformation, but carried out onBlur. This is especially useful for trimming.

initialValue

Lets you initialize a field's value.

optional

Lets you declare a field as optional

hydrate

hydrate is a function that takes whatever arguments you pass in, and return the slice of formState you want to hydrate.

onSubmit

type: Function | { motive: Function, prepForSubmit: Function shouldDispatch: Boolean }

If you pass a function to onSubmit, it will be treated as the motive function.

If a motive is passed as a prop to the form's component, then that will serve as the motive function. The prop takes precedence over the motive specified in the config object.

  motive: ownProps.motive ? ownProps.motive : onSubmit.motive

motive

motive is the function you want called onSubmit. This is generally the function that will send an AJAX request.

prepForSubmit

prepForSubmit is a function that lets you modify the data that motive is called with.

prepForSubmit defaults to the following:

  (formState, extraArguments = []) => [formState, ...extraArguments]

shouldDispatch

Lets you specify whether the motive should be dispatched or not. shouldDispatch defaults to true.