search

thedersen / backbone.validation

A validation plugin for Backbone.js that validates both your model as well as form input
thedersen.com/projects/backbone-validation
MIT License
1.32k stars 300 forks source link

readme

Backbone.Validation

Version Downlodas Dependencies license Gitter

A validation plugin for Backbone.js that validates both your model as well as form input.

Introduction

Good client side validation is an important part of giving your users a great experience when they visit your site. Backbone provides a validate method, but it is left undefined and it is up to you to override it with your custom validation logic. Too many times I have seen validation implemented as lots of nested ifs and elses. This quickly becomes a big mess. One other thing is that with libraries like Backbone, you hold your state in a Model, and don't tie it to the DOM. Still, when validating your models you probably want to inform your users about errors etc., which means modifying the DOM.

Backbone.Validation tries to solve both these problems. It gives you a simple, extensible way of declaring validation rules on your model, and overrides Backbone's validate method behind the scene. And, it gives you a nice hook where you can implement your own way of showing the error messages to your user.

If you are using node.js on the server you can also reuse your models and validation on the server side. How cool is that?

Backbone.Validation is a bit opinionated, meaning that you have to follow some conventions in order for it to work properly.

Download and source code

You can download the raw source from GitHub, see the annotated source or use the links below for the latest stable version.

Standard builds

AMD builds

Node.js builds

npm install backbone-validation

Bower builds

bower install backbone-validation

Getting started

It's easy to get up and running. You only need to have Backbone (including underscore.js) in your page before including the Backbone.Validation plugin. If you are using the default implementation of the callbacks, you also need to include jQuery.

The plugin is tested with, and should work with the following versions of

Configure validation rules on the Model

To configure your validation rules, simply add a validation property with a property for each attribute you want to validate on your model. The validation rules can either be an object with one of the built-in validators or a combination of two or more of them, or a function where you implement your own custom validation logic.

Validating complex objects is also supported. To configure validation rules for objects, use dot notation in the name of the attribute, e.g 'address.street'.

Example

var SomeModel = Backbone.Model.extend({
  validation: {
    name: {
      required: true
    },
    'address.street': {
      required: true
    },
    'address.zip': {
      length: 4
    },
    age: {
      range: [1, 80]
    },
    email: {
      pattern: 'email'
    },
    someAttribute: function(value) {
      if(value !== 'somevalue') {
        return 'Error message';
      }
    }
  }
});

// validation attribute can also be defined as a function returning a hash
var SomeModel = Backbone.Model.extend({
  validation: function() {
    return {
      name: {
        required: true
      }
    }
  }
});

See the built-in validators section for a list of the validators and patterns that you can use.

Specifying error messages

Backbone.Validation comes with a set of default error messages. If you don't like to use those, you can either override them, or you can specify error messages where you declare validation rules on the model.

You can specify an error message per attribute by adding a msg property like this:

MyModel = Backbone.Model.extend({
  validation: {
    email: {
      required: true,
      pattern: 'email',
      msg: 'Please enter a valid email'
    }
  }
});

Or, you can specify an error message per validator, by adding an array of validators like this:

MyModel = Backbone.Model.extend({
  validation: {
    email: [{
      required: true,
      msg: 'Please enter an email address'
    },{
      pattern: 'email',
      msg: 'Please enter a valid email'
    }]
  }
});

The msg property can also be a function returning a string.

Using form+model validation

The philosophy behind this way of using the plugin, is that you should be able to reuse your validation rules both to validate your model and to validate form input, as well as providing a simple way of notifying users about errors when they are populating forms.

Note that Backbone.Validation does not provide any automatic/two-way binding between your model and the view, that's up you to implement (you can for instance use Backbone.stickit).

Before you can start using form validation, you need to bind your view.

Validation binding

The validation binding code is executed with a call to Backbone.Validation.bind(view). There are several places that it can be called from, depending on your circumstances, but it must be called after your model or collection has been initialized.

// Binding when rendering
var SomeView = Backbone.View.extend({
  render: function(){
    Backbone.Validation.bind(this);
  }
});

// Binding when initializing
var SomeView = Backbone.View.extend({
  initialize: function(){
    Backbone.Validation.bind(this);
  }
});

// Binding from outside a view
var SomeView = Backbone.View.extend({
});
var someView = new SomeView({model: new SomeModel()});
Backbone.Validation.bind(someView);

// Binding to a view with an optional model
var myModel = new Backbone.Model();
var SomeView = Backbone.View.extend({
  initialize: function(){
    Backbone.Validation.bind(this, {
      model: myModel
    });
  }
});

// Binding to a view with an optional collection
var myCollection = new Backbone.Collection();
var SomeView = Backbone.View.extend({
  initialize: function(){
    Backbone.Validation.bind(this, {
      collection: myCollection
    });
  }
});

Binding to view with a model

For this to work, your view must have an instance property named model that holds your model before you perform the binding, or you can pass an optional model in the options as shown in the example above.

When binding to a view with a model, Backbone's validate method on the model is overridden to perform the validation. In addition, the model's isValid method is also overridden to provide some extra functionality.

Binding multiple views to same model

It is possible to bind several views to the same model. This is specially useful in UI structures where forms are made with components that share models.

When the model is validated all associated views with attributes from that model will validate its related elements.

It is also possible to unbind each view separately without affecting other bindings.

Binding to view with a collection

For this to work, your view must have an instance property named collection that holds your collection before you perform the binding, or you can pass an optional collection in the options as shown in the example above.

When binding to a view with a collection, all models in the collection are bound as described previously. When you are adding or removing models from your collection, they are bound/unbound accordingly.

Note that if you add/remove models with the silent flag, they will not be bound/unbound since there is no way of knowing the the collection was modified.

Unbinding

If you want to remove the validation binding, this is done with a call to Backbone.Validation.unbind(view). This removes the validation binding on the model, or all models if you view contains a collection, as well as removing all events hooked up on the collection.

Note that if you are binding to an optional model or collection, you must also specify this when unbinding: Backbone.Validation.unbind(view, {model: boundModel}).

Using model validation

The philosophy behind this way of using the plugin, is to give you an easy way to implement validation across all your models without the need to bind to a view. Of course, if you use this option the callbacks to update the view is not executed, since there is no way of knowing what view a model belongs to.

Validation mix-in

To add validation to your models, mix in the validation on the Model's prototype.

_.extend(Backbone.Model.prototype, Backbone.Validation.mixin);

Using server validation

If you are using node.js on your server, you can also reuse your models and validation on the server. For this to work you must share your models between the server and the client.

var backbone = require('backbone'),
    _ = require('underscore'),
    validation = require('backbone-validation');

_.extend(backbone.Model.prototype, validation.mixin);

Methods

validate

This is called by Backbone when it needs to perform validation. You can also call it manually without any parameters to validate the entire model.

isValid

Check to see if an attribute, an array of attributes or the entire model is valid.

isValid returns undefined when no validation has occurred and the model has validation (except with Backbone v0.9.9 where validation is called from the constructor), otherwise, true or false.

If you don't pass an argument, the properties defined by the attributes bind option will be validated. If no attributes option is used there will be no validation.

var isValid = model.isValid();

If you pass true as an argument, this will force a validation before the result is returned:

var isValid = model.isValid(true);

If you pass the name of an attribute or an array of names, you can check whether or not the attributes are valid:

// Check if name is valid
var isValid = model.isValid('name');

// Check if name and age are valid
var isValid = model.isValid(['name', 'age']);

preValidate

Sometimes it can be useful to check (for instance on each key press) if the input is valid - without changing the model - to perform some sort of live validation. You can execute the set of validators for an attribute, or a hash of attributes, by calling the preValidate method and pass it the name of the attribute and the value to validate, or a hash of attributes.

If the value is not valid, the error message is returned (truthy), otherwise it returns a falsy value.

// Validate one attribute
// The `errorsMessage` returned is a string
var errorMessage = model.preValidate('attributeName', 'Value');

// Validate a hash of attributes
// The errors object returned is a key/value pair of attribute name/error, e.g
// {
//   name: 'Name is required',
//   email: 'Email must be a valid email'
// }
var errors = model.preValidate({name: 'value', email: 'foo@example.com'});

Configuration

Callbacks

The Backbone.Validation.callbacks contains two methods: valid and invalid. These are called after validation of an attribute is performed when using form validation.

The default implementation of invalid tries to look up an element within the view with an name attribute equal to the name of the attribute that is validated. If it finds one, an invalid class is added to the element as well as a data-error attribute with the error message. The valid method removes these if they exists.

The implementation is a bit naïve, so I recommend that you override it with your own implementation

globally:

_.extend(Backbone.Validation.callbacks, {
  valid: function(view, attr, selector) {
    // do something
  },
  invalid: function(view, attr, error, selector) {
    // do something
  }
});

or, per view when binding:

var SomeView = Backbone.View.extend({
  render: function(){
    Backbone.Validation.bind(this, {
      valid: function(view, attr) {
        // do something
      },
      invalid: function(view, attr, error) {
        // do something
      }
    });
  }
});

Selector

Default: name

This configures what selector that will be used to look up a form element in the view. By default it uses name, but if you need to look up elements by class name or id instead, there are two ways to configure this.

You can configure it globally by calling:

Backbone.Validation.configure({
  selector: 'class'
});

Or, you can configure it per view when binding:

Backbone.Validation.bind(this.view, {
  selector: 'class'
});

If you have set the global selector to class, you can of course set the selector to name or id on specific views.

Force update

Default: false

Sometimes it can be useful to update the model with invalid values. Especially when using automatic modelbinding.

You can turn this on globally by calling:

Backbone.Validation.configure({
  forceUpdate: true
});

Or, you can turn it on per view when binding:

Backbone.Validation.bind(this.view, {
  forceUpdate: true
});

Or, you can turn it on for one set operation only (Backbone.VERSION >= 0.9.1 only):

model.set({attr: 'invalidValue'}, {
  forceUpdate: true
});

Note that when switching this on, Backbone's error event is no longer triggered.

Label formatter

Default: sentenceCase

Label formatters determines how an attribute name is transformed before it is displayed in an error message.

There are three options available:

var Model = Backbone.Model.extend({
  validation: {
    someAttribute: {
      required: true
    }
  },

  labels: {
    someAttribute: 'Custom label'
  }
});

To configure which one to use, set the labelFormatter options in configure:

Backbone.Validation.configure({
  labelFormatter: 'label'
});

Attributes

The attributes option passed in Backbone.Validation.bind determines what model attributes must be validated. It can be an array, a function returning an array or an string that points to an registered attribute loader. By default, the 'inputNames' attribute loader is provided. It returns the name attribute of input elements in the view.

Per view when binding:

var SomeView = Backbone.View.extend({
  render: function(){
    Backbone.Validation.bind(this, {
        attributes: function(view) {
          return ['name', 'age']; // only name and age will be validated
        }
      }
    });
  }
});

Set default globally:

Backbone.Validation.configure({
  attributes: 'inputNames' // returns the name attributes of bound view input elements
});

Register an attribute loader:

_.extend(Backbone.Validation.attributeLoaders, {
  myLoader: function(view) {
    // return an array with the attributes to be validated
  }
});

Events

After validation is performed, the model will trigger some events with the result of the validation.

Note that the events reflects the state of the model, not only the current operation. So, if for some reason your model is in an invalid state and you set a value that is valid, validated:invalid will still be triggered, not validated:valid.

The errors object passed with the invalid events is a key/value pair of attribute name/error.

{
  name: 'Name is required',
  email: 'Email must be a valid email'
}

validated

The validated event is triggered after validation is performed, either it was successful or not. isValid is true or false depending on the result of the validation.

model.bind('validated', function(isValid, model, errors) {
  // do something
});

validated:valid

The validated:valid event is triggered after a successful validation is performed.

model.bind('validated:valid', function(model) {
  // do something
});

validated:invalid

The validated:invalid event is triggered after an unsuccessful validation is performed.

model.bind('validated:invalid', function(model, errors) {
  // do something
});

Built-in validators

method validator

Lets you implement a custom function used for validation.

var SomeModel = Backbone.Model.extend({
  validation: {
    name: function(value, attr, computedState) {
      if(value !== 'something') {
        return 'Name is invalid';
      }
    }
  }
});

var SomeModel = Backbone.Model.extend({
  validation: {
    name: {
      fn: function(value, attr, computedState) {
        if(value !== 'something') {
          return 'Name is invalid';
        }
      }
    }
  }
});

named method validator

Lets you implement a custom function used for validation.

var SomeModel = Backbone.Model.extend({
  validation: {
    name: 'validateName'
  },
  validateName: function(value, attr, computedState) {
    if(value !== 'something') {
      return 'Name is invalid';
    }
  }
});

var SomeModel = Backbone.Model.extend({
  validation: {
    name: {
      fn: 'validateName'
    }
  },
  validateName: function(value, attr, computedState) {
    if(value !== 'something') {
      return 'Name is invalid';
    }
  }
});

required

Validates if the attribute is required or not. This can be specified as either a boolean value or a function that returns a boolean value.

var SomeModel = Backbone.Model.extend({
  validation: {
    name: {
      required: true | false
    }
  }
});

var SomeModel = Backbone.Model.extend({
  validation: {
    name: {
      required: function(value, attr, computedState) {
        return true | false;
      }
    }
  }
});

acceptance

Validates that something has to be accepted, e.g. terms of use. true or 'true' are valid.

var SomeModel = Backbone.Model.extend({
  validation: {
    termsOfUse: {
      acceptance: true
    }
  }
});

min

Validates that the value has to be a number and equal to or greater than the min value specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    age: {
      min: 1
    }
  }
});

max

Validates that the value has to be a number and equal to or less than the max value specified.

var SomeModel = Backbone.Model.extend({
  validation: {
      age: {
      max: 100
    }
  }
});

range

Validates that the value has to be a number and equal to or between the two numbers specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    age: {
      range: [1, 10]
    }
  }
});

length

Validates that the value has to be a string with length equal to the length value specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    postalCode: {
      length: 4
    }
  }
});

minLength

Validates that the value has to be a string with length equal to or greater than the min length value specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    password: {
      minLength: 8
    }
  }
});

maxLength

Validates that the value has to be a string with length equal to or less than the max length value specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    password: {
      maxLength: 100
    }
  }
});

rangeLength

Validates that the value has to be a string and equal to or between the two numbers specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    password: {
      rangeLength: [6, 100]
    }
  }
});

oneOf

Validates that the value has to be equal to one of the elements in the specified array. Case sensitive matching.

var SomeModel = Backbone.Model.extend({
  validation: {
    country: {
      oneOf: ['Norway', 'Sweeden']
    }
  }
});

equalTo

Validates that the value has to be equal to the value of the attribute with the name specified.

var SomeModel = Backbone.Model.extend({
  validation: {
    password: {
      required: true
    },
    passwordRepeat: {
      equalTo: 'password'
    }
  }
});

pattern

Validates that the value has to match the pattern specified. Can be a regular expression or the name of one of the built in patterns.

var SomeModel = Backbone.Model.extend({
  validation: {
    email: {
      pattern: 'email'
    }
  }
});

The built-in patterns are:

Specify any regular expression you like:

var SomeModel = Backbone.Model.extend({
  validation: {
    email: {
      pattern: /^sample/
    }
  }
});

Extending Backbone.Validation

Adding custom validators

If you have custom validation logic that are used several places in your code, you can extend the validators with your own. And if you don't like the default implementation of one of the built-ins, you can override it.

_.extend(Backbone.Validation.validators, {
  myValidator: function(value, attr, customValue, model) {
    if(value !== customValue){
      return 'error';
    }
  },
  required: function(value, attr, customValue, model) {
    if(!value){
      return 'My version of the required validator';
    }
  },
});

var Model = Backbone.Model.extend({
  validation: {
    age: {
      myValidator: 1 // uses your custom validator
    }
  }
});

The validator should return an error message when the value is invalid, and nothing (undefined) if the value is valid. If the validator returns false, this will result in that all other validators specified for the attribute is bypassed, and the attribute is considered valid.

Adding custom patterns

If you have custom patterns that are used several places in your code, you can extend the patterns with your own. And if you don't like the default implementation of one of the built-ins, you can override it.

Remember to also provide a default error message for it.

_.extend(Backbone.Validation.patterns, {
  myPattern: /my-pattern/,
  email: /my-much-better-email-regex/
});

_.extend(Backbone.Validation.messages, {
  myPattern: 'This is an error message'
});

var Model = Backbone.Model.extend({
  validation: {
    name: {
      pattern: 'myPattern'
    }
  }
});

Overriding the default error messages

If you don't like the default error messages you can easilly customize them by override the default ones globally:

_.extend(Backbone.Validation.messages, {
  required: 'This field is required',
  min: '{0} should be at least {1} characters'
});

The message can contain placeholders for arguments that will be replaced:

Examples

If you have other cool examples, feel free to fork the fiddle, add a link here, and send me a pull request.

FAQ

What gets validated when?

If you are using Backbone v0.9.1 or later, all attributes in a model will be validated. However, if for instance name never has been set (either explicitly or with a default value) that attribute will not be validated before it gets set.

This is very useful when validating forms as they are populated, since you don't want to alert the user about errors in input not yet entered.

If you need to validate entire model (both attributes that has been set or not) you can call validate() or isValid(true) on the model.

Can I call one of the built in validators from a method validator?

Yes you can!

var Model = Backbone.Model.extend({
  validation: {
    name: function(val, attr, computed) {
      return Backbone.Validation.validators.length(val, attr, 4, this);
    }
  }
});

Can I call one of the built in validators from a custom validator?

Yes you can!

_.extend(Backbone.Validation.validators, {
  custom: function(value, attr, customValue, model) {
    return this.length(value, attr, 4, model) || this.custom2(value, attr, customValue, model);
  },
  custom2: function(value, attr, customValue, model) {
    if (value !== customValue) {
      return 'error';
    }
  }
});

How can I allow empty values but still validate if the user enters something?

By default, if you configure a validator for an attribute, it is considered required. However, if you want to allow empty values and still validate when something is entered, add required: false in addition to other validators.

validation: {
    value: {
        min: 1,
    required: false
  }
}

Do you support conditional validation?

Yes, well, sort of. You can have conditional validation by specifying the required validator as a function.

validation: {
  attribute: {
    required: function(val, attr, computed) {
      return computed.someOtherAttribute === 'foo';
    },
    length: 10
  }
}

In the example above, attribute is required and must have 10 characters only if someOtherAttribute has the value of foo. However, when attribute has any value it must be 10 characters, regardless of the value of someOtherAttribute.

Is there an elegant way to display the error message that is put into the data-error attribute?

The default implementation of the callbacks are a bit naïve, since it is very difficult to make a general implementation that suits everybody.

My recommendation is to override the callbacks and implement your own strategy for displaying the error messages.

Please refer to this section for more details.

How can I use it with Twitter Bootstrap?

driehle put together a gist in Coffee Script that helps rendering the error messages for Twitter Bootstrap:

https://gist.github.com/2909552

Basic behaviour:

Release notes

v0.11.5 commits

v0.11.4 commits

v0.11.3 commits

v0.11.2 commits

v0.11.1 commits

v0.11.0 commits

v0.10.1 commits

v0.10.0 commits

v0.9.2 commits

v0.9.1 commits

v0.9.0 commits

v0.8.2 commits

v0.8.1 commits

v0.8.0 commits

v0.7.1 commits

v0.7.0 commits

v0.6.4 commits

v0.6.3 commits

v0.6.2

v0.6.1

v0.6.0

v0.5.2

v0.5.1

v0.5.0

v0.4.0

v0.3.1

v0.3.0

v0.2.0

v0.1.3

v0.1.2

Contribute

In lieu of a formal styleguide, use two spaces for tabs and take care to maintain the existing coding style.

For a pull request to be accepted it must contain:

Make sure that all tests passes before submitting your pull request.

npm install -g grunt-cli
npm install
grunt

Inspiration

Backbone.Validation is inspired by Backbone.ModelBinding, and another implementation with a slightly different approach than mine at Backbone.Validations.

License

http://thedersen.mit-license.org/