flux-form
v5.0.0
Published
Manage your forms with flux, any flux
Downloads
18
Readme
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.