flux-form

    5.0.0 • Public • Published

    flux-form

    Flux form is a helper for managing forms with flux

    import fluxForm from 'flux-form'
    import { Dispatcher } from 'flux'
     
    const dispatcher = new Dispatcher()
     
    const form = fluxForm('MyForm', dispatcher, {
      fields: [
        'name',
        'email',
      ],
     
      state: UserStore.getState(),
    })

    fluxForm will return a form object which contains all the fields you defined, a save action, a cancel action, and the current form's state.

    class SampleFormComponent extends React.Component {
      render() {
        return (
          <div>
            <label>
              Name
              <input {...form.props.name} />
            </label>
     
            <label>
              Email
              <input {...form.props.email} />
            </label>
     
            <input type="button" onClick={form.save} />
          </div>
        )
      }
    }

    ...form.props.name will add all of the props for the field name onto the input. The two important props are value which contains the current value, and onChange which is a function handler that sets the value.

    Flux Form is meant to be bare bones and generic in that you can build adapters on top of it so it works with your favorite flavor of flux.

    For example, we can have an Alt specific form utility which creates a store that you can connect your React component to.

    Validation

    You can provide basic validation that can be triggered manually and also runs automatically whenever the form is saved.

    const form = fluxForm('MyForm', dispatcher, {
      fields: [
        'username',
        'password',
      ],
     
      validators: {
        // you can asynchronously validate a field by returning a promise
        // for example, you can validate that the username is not taken here
        // by making an API call and rejecting the Promise
        username(data) {
          return new Promise((resolve, reject) {
            xhr.post('/validateUsername', { user: data }, (res) => {
              if (res.statusCode === 200) {
                resolve()
              } else {
                reject(res.responseText)
              }
            })
          })
        },
     
        // you throw an error if it does not pass validation
        password(data) {
          if (data.length <= 6) {
            throw new Error('Password must be longer than 6 characters')
          }
        },
      },
    })

    The validation can be triggered and it returns a Promise. You can also pass in a node-style callback if you prefer.

    form.validate().then((state) => {
      // the successful state of the form
    }, (errors) => {
      // a key value pair of errors
      // for example:
      // {
      //   password: 'Password must be longer than 6 characters',
      // }
    })

    You can also validate specific fields by passing in an Array to validate.

    form.validate(function (err, state) {
      // do something with err or state
    }, ['username'])

    Normalization

    Form fields are normalized either manually or automatically when saving.

    const form = fluxForm('MyForm', dispatcher, {
      fields: [
        'phone',
      ],
     
      output: {
        // some really crappy normalization lol
        phone(data) {
          // take the phone number and format it so it is without dashes and parens
          // and then add a +1 at the beginning
          return '+1' + String(data).replace(/[ |(|)|-]/g, '')
        },
      },
    })

    To trigger a normalization

    form.normalize()

    Focus

    focus and blur actions are called whenever an element receives focus or is blurred.

    Saving

    In order to save your form state which will trigger validation and normalization you can call save on your form object.

    const form = fluxForm('MyForm', dispatcher, {
      fields: [
        'address',
        'city',
        'country',
      ],
    })
     
    form.save().then((state) => {
    })

    Save returns a promise but you can also pass it a node-style callback.

    Action Creators

    Flux form works by firing off flux actions with the dispatcher you've provided. The actions are dispatched in FSA format.

    The following actions are provided

    • saved
    • canceled
    • changed
    • validationFailed
    • focused
    • blurred

    You use getActionCreators in order to get the action creators. Action creators are functions which return an FSA compliant payload ready to be dispatched. Each action creator has an id field which is the string that you can use in your store in order to handle the dispatch.

    import { getActionCreators } from 'flux-form'
     
    const { saved } = getActionCreators('MyForm')
     
    // sample usage
    alt.dispatch(saved('foobar')) // { type: 'MyForm/saved', payload: 'foobar' }

    Flux form will automatically dispatch change events, saved, focus, etc, which you can then listen to yourself in order to keep track of state separately or in order to sync items.

    Keywords

    Install

    npm i flux-form

    DownloadsWeekly Downloads

    0

    Version

    5.0.0

    License

    MIT

    Last publish

    Collaborators

    • goatslacker