florm

form
=========
Form validation and serialization.

##Installation
``
npm install florm
`

##Usage

####Init

Pass either a node reference or a selector pointing to a form to the constructor, along with an optional options dictionary.

`
var Florm = require('florm');
var form = Florm('#comment_form', options);
`

####Options

`
{
'fieldErrorClasses': ['comment_form_error'],
'formErrorClasses': ['comment_form_errors],
'formErrorContainer': '#form_errors',
'submit': true,
}
`

* fieldErrorClasses should be an array of class names to add to errors applied to individual fields. Empty by default.

* formErrorClasses should be an array of class names to add to form wide errors. Empty by default.

* formErrorContainer should be a selector pointing to an element to append form wide errors. Empty by default.

* submit should be a boolean. True by default.

Field errors are errors that correspond to individual input fields.

Form errors are form wide errors, or errors that depend on multiple fields. 'The passwords do not match' is an example of a form error.

Submit indicates whether the validation and submission process should be automated. If submit is true, form validation will occur automatically when the form element recieves a submit event. If validation passes, the serialized data will be passed to the function passed to form.success. If it fails, the error dictionary returned from form.validate and the serialized form will be passed to the function in form.fail if it has beend defined, and to form.errors if not.

####Serialization

`
var form_data = form.serialize();
`

form.serialize() returns a serialized representation of the form. Input values are mapped to properties that correspond to the 'name' attribute of the input.

Example form:

`








`

Would serialize to:

`
{ text: 'This is a comment', username: 'fergus' }
`

####Add validation

`
form.validate(function(attrs) {
var errors = {};
if (!attrs.text.trim()) {
errors['text'] = 'Please enter a comment.';
} else if (attrs.username.length > 60) {
errors['username'] = 'Username length cannot exceed 60 characters.';
}
return errors;
});
`

The function passed to validate will recieve a serialized representation of the form as it's only parameter. It must return a dictionary with each property set to the corresponding input's name attribute. Use '__all__' to indicate a form error.

####Add a success callback

Add a function to call after form validation has successfully completed. It will recieve a fully serialized representation of the form.

`
form.success(function(data) {
var url = this.element.action;
ff.http.json.post(url, data, function(response) {
addToUI(response);
});
});
`

####Add a fail callback

Add a function to call after form validation has failed. It will recieve any errors returned from form.validate(), and a fully serialized representation of the form. If a fail callback is not provided, form.errors will be called instead, passing the errors.

`
form.fail(function(errors, serializedForm) {
form.errors(errors)
});
`

Other methods
=========

By default, Florm will automatically override the submit event of the form element it is attached to. If you'd like more control over the process, the following methods are also available. Remember to pass `{'submit': false}` in options.


####Submit the form

`
form.element.addEventListener('submit', function(event) {
form.submit();
});
`

The submit method triggers validation. If validate returns a populated dictionary, the fail method will be called. Otherwise, the success method will be called.

####Apply errors

Florm.errors is a method that applies errors to form inputs. Given the following 'errors' dictionary:

`
{ text: 'Please enter a comment.' }
`


It will query the form for an element with the 'name' attribute set to text, and insert an error after it in the following form:


`
{{errors[property]}}
`

e.g.

`
Please enter a comment.
`

Will be inserted into the dom after the following input:

`

`

form.Errors will be called automatically as part of the validation process, unless a form.fail method has been set. This can be overcome by calling form.errors(errors) from within the form.fail function.

####Clear the form

`
form.clear();
`
The clear method removes any errors within the form, as well as resetting each input.

####Clear errors

`
form.clearErrors();
``
clearErrors removes errors from within the form, without resetting inputs.