README.md

jQuery Form Validator

I got bored of using other people's validators that didn't work just as I wanted.

So I created one.

This is not a jQuery plugin, but does depend on jQuery.

Demo

There's a demo included in the demo/ folder. If you're not sure on the documentation, you should look at the demo first. It contains a pretty solid example on how to use the library. All the main methods are also covered in the tests, so between this document, the demo and the tests, you should be set. Any problems, raise an issue or tweet @Jack_Franklin.

Documentation

If anything's not clear, the best place to look is the tests. Every public method is tested in there.

Getting started

Create a new variable to store your form in:

var signUpForm =FormValidator();

Then call methods on signUpForm:

Dealing with Fields

addField(field)

Adds a field to the form validator, that you can then validate against. Argument can either be any valid CSS selector (any that you would pass into jQuery), or a jQuery object. If the jQuery object has multiple elements, only the first will be saved. Field is added to the internal fields object, which are index by the field's name attribute.

addFields(fields)

Same as addField, but handles multiple elements passed in. Either pass in an array of CSS selectors, or a jQuery object.

field(name) returns Object

Pass in a string which is the name of the field, and you get an object back representing it. Rarely useful. Response:

The first is preferred but the second may be useful if you need to programatically add validations at different times.

clearPendingValidations()

Clears all pending validations so none remain.

runValidations(clearAfter) returns Object

New in 0.6: returns a more complex object with each field's messages individually, along with the field's jQuery object.

Runs all pending validations, returning a response object.

If you pass in an argument of true, it clears the pending validations object completely.

The response is like so:

{
valid:true, //boolean true or false, if the entire validation set was valid
messages: [], //array of error messages of all fields combined
fields: {
username: {
field: { //the same object you would get from calling yourForm.field("username")
html: [ <input type="text" name="username"/> ],
attributes: {
type:"text",
name:"username"
}
},
messages: [], //error messages for just that field
valid:true, //boolean true/false for if THAT field was valid or not
html: [ <input type="text" name="username"/>] //jQuery object for that field. A shortcut to the html property of the field object
}
}
}

getPendingValidations returns Object

Returns the pending validations as a key-value object, with the key being the field name, and the value being the validation string. Sample response:

name is the name you'll refer to when adding validations to a field.
obj should contain two fields:
fn is the function that's run to test the validation. It's passed three arguments:

the value of the field you're validating against

the parameter(s) it's called with

a jQuery object containing the field
It's unlikely you'll ever use the third parameter, but it's there if you need it. A validation method just needs to return true or false.

message is the method's error message. These contain placeholders, which are documented below.

For example, the min_length validation function looks like so:

function(val, arg) {
returnval.length>= arg;
},

Because I know min_length will only take one argument, I can just reference the variable passed in. Validation methods are only passed in an array of arguments if they take more than one. If they only take one, that one value is passed in. Compare the above to the length_inbetween validator:

And that's it! A good place to start is demo/demo.js, which has a plain example to get you going in the right direction.

Contributing

This project uses Grunt JS for testing, linting and deploying.

Install Grunt JS: npm install -g grunt

Then clone and cd into this repository and run npm install.

Now you should be able to run grunt to lint, test, concatenate and minify.

Tests are written in Jasmine and can be tested with grunt jasmine.

You can run linting with grunt lint.

Run lints and tests with grunt test.

If you make a pull request, please write tests for it :)

Contributors

@jackfranklin

@joshstrange

Todo

Add NodeJS support

test and document cross-browser support

Changelog

Version 0.9.2

added fields() method, which returns the fields object of a JFV instance.

Version 0.9.1

add methods to JFV.prototype, not just to the JFV object.

Version 0.9

support AMD libraries like RequireJS.

switch to using proper semantic versioning (from this point on)

generated a Docco build file (see docs/).

rewrote library as a JS class (public API usage hasn't changed)

support validating checkboxes as well as text fields

Version 0.6

changed the response object to return each field and its error messages indidividually - thanks @joshstrange for the initial idea and some of the code.

Version 0.5

Fixed a typo in the README - thanks @joshstrange

use Regex to replace within messages - thanks @joshstrange

Integrated into Grunt JS (see section on Contributing)

Version 0.4

made it onto Hacker News!

thanks to a suggestion on there, ditched using strings for validations and switched to JS objects, which make much more sense. So, instead of:

addValidation("username", "min_length(5)|required");

It's now:

addValidation("username", { min_length:5, required:true });

A few things have changed as a by-product of this - please do read the docs carefully. Any questions please ask away!

Version 0.3

rewrote the validation methods so they are passed in three arguments: value, args, obj. Realised most methods will only care about the field value, so pass that in directly rather than just the object to streamline the validation methods. Object is passed in as 3rd argument if it is needed.

Version 0.2

ability to add fields through the FormValidator method.

runValidations takes optional argument which, if set to true, will clear pending validations once run.