ok.js
Simple validation library for Javascript models. It doesn't touch the DOM, it doesn't return messages. It just takes an object and validates it against a set of rules returning an object for working with errors.
I wasn't happy with the validation libraries available for Backbone models. Most are large and try and do too much. Ok was designed to take your models attributes and return a nice error object that your views can use to update your UI. It doesn't attempt to cover every validation use-case but it provides a simple interface for extending the validation rules available.
- Provide an easy interface for extending the validation rules
- Common and basic validation rules included by default
- Doesn't show errors or make DOM changes like jQuery.validate
- Doesn't handle messages of any kind
- Doesn't provide complex validation rules
Requirements
- Underscore.js
Getting Started
Download the production version or the development version.
Usage
var schema = first_name: required: true string: true last_name: required: true string: true birthday: date: true ; var errors = schema; // Any errors?if errorslength === 0 return "Hooray!"; // Loop through all of the errors easilyerrors;
With Backbone
var Person = BackboneModel;
Available Rules
The built-in rules will example usage.
required
Accepts a boolean value
name: required: true
Basic email check. It's not a complex email regex but it will cover the majority of cases. Accepts true
or false
.
email: email: true
url
Basic URL check. Accepts true
or false
.
blog: url: true
alphanumeric
Accepts a string with numbers or letters. A simple /^\w+$/
check. Accepts true
or false
.
username: alphanumeric: true
hex
Accepts a hex value with or without the leading hash. Accepts true
or false
.
color: hex: true
string
Check if a value is a string using underscores _.isString
method. Accepts true
or false
.
title: string: true
number
Check if a value is a number. Strings that return a number with parseFloat
will pass. Accepts true
or false
.
user_id: number: true
array
Check if a value is a string using underscores _.isArray
method. Accepts true
or false
.
entries: array: true
date
Simple date checking using Date.parse
or _.isDate
. Accepts true
or false
.
due_at: date: true
boolean
Check if a value is a string using underscores _.isBoolean
method. Accepts true
or false
.
terms: boolean: true
max
Limit a number to a max value.
size: max: 1000
min
Limit a number to a min value.
size: min: 1
length
Check the length property of an object.
account_id: length: 14
minlength
Check the length property of an object.
account_id: minlength: 14
maxlength
Check the length property of an object.
account_id: maxlength: 14
equal
Check the value equals the other object using _.isEqual
.
equal: secret: 'nyan'
range
Check that the number is within a range. Takes an object with a from
and to
value.
level: range: from: 0 to: 3
in
Checks to see if the value is any value in an array.
level: in: 0 1 3
pattern
Tests the value against the regex object.
name: pattern: /^foo/
Custom Rules
You can define a custom validator within your schema by passing a function as the value for a rule. For example:
var schema = { return value === datapassword_confirm; };
The function is passed the value being checked and the whole object of data being checked so you can do comparisons on other attributes.
Documentation
Schema
The schema is just a simple object with keys that map to attributes. The values are a hash of rules. The key is the validation type and the value will be passed to the validation method in OK.Validator. For example
var schema = name: string: true ;
This object can be passed to OK.validate(attributes, schema)
to be used once or you can contruct a new OK instance new OK(schema)
and reuse the same schema validation across your application.
OK.Error object
Whenever you validate you are returned an OK.Error object. This is a simple interface for working with the errors.
length
The total number of errors for all attributes. This is the easiest way to check if there are any errors.
var errors = OK;if errorslength > 0 // Update view
isValid(attr)
Check if an attribute that was passed in was valid.
get(attr)
Returns the errors object for an attribute or false if there is no errors for that attribute
each(attr, callback)
Loop through the errors for an attribute and call the callback. If the attr
param is omitted and a function is passed in as the
only parameter it will loop through the errors object itself so you can check each of the attributes.
toJSON
Similar the implementation in Backbone. Returns an object of errors that can be used as JSON.
Adding new validation rules
Adding new validation rules is just a matter of adding a new method to the prototype of OK.Validator
OKValidatorprototype{ return CreditCard;};
The function will be passed the value, the options for that rule (which is whatever you've defined in your schema) and the object of all the data that is being validated so you can check the value in relation to other values. Here's an example schema using the validation method we just defined:
var schema = card: creditcard: type: 'mastercard' ; var data = card: 'foo'; OK;
In the validtion method, value
will be 'foo'
, options will be { type: mastercard }
and data
will be the object that is passed in to validate.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.
Also, please don't edit files in the "dist" subdirectory as they are generated via grunt. You'll find source code in the "lib" subdirectory!
Release History
0.1.0 - First release
License
Copyright (c) 2012 Anthony Short
Licensed under the MIT license.