Judge 1.0.0

Simple client side form validation for Rails 3

Judge allows easy live form validation for Rails 3 apps, by porting many ActiveModel::Validation features to JavaScript and exposing your model validations as JSON within HTML5 data attributes. It's fast and it's purely on the client side – no more code duplication for standard validators, no need for gratuitous AJAX.

Dependencies

Judge relies on Underscore.js, along with json2.js, which defers to the native JSON global object in modern browsers.

Installation

Add the following to your Gemfile:

gem "judge", "~> 1.0.0"

and then run:

$ bundle install

To copy the Judge JavaScript files to your app, use the generator:

$ rails generate judge [path] [options]

The path parameter is optional and defaults to public/javascripts. So running the generator without specifying a path and with no options will give you:

• public/javascripts/underscore.js
• public/javascripts/json2.js
• public/javascripts/judge.js

The only option is --no-dep, which prevents the generator from copying Underscore.js and json2.js into your chosen directory if you already have them.

Rails 3.0

$ rails generate judge

Then do whatever it is you usually do to ensure that JavaScript files are included properly (e.g. add them to assets.yml if you are using Jammit).

Rails 3.1

Run the generator as follows to copy judge.js and its dependencies to your app:

$ rails generate judge app/assets/javascripts

These files should now be included, thanks to the following line in your manifest file (app/assets/javascripts/application.js):

//= require_tree .

If you ever come across problems with your require order, you can ensure that Judge's dependencies are required first by doing something like this:

//= require underscore
//= require json2
//= require_tree .

Quick start

As of version 1.0.0, Judge form builder methods are no longer prefixed with “validated_”. The syntax is now in line with standard Rails form builders, as follows:

<%= form_for(@post, :builder => Judge::FormBuilder) do |f|%>
  <%= f.text_field :title, :validate => true %>
  <%= f.text_area :body, :validate => true %>
<% end %>

Most Judge functionality on the client side is based on the use of watchers. A watcher is a sort of pointer object for a DOM element. Create a watcher for an input element:

var watcher = new judge.Watcher(document.getElementById('foo'));

Check whether the value of the watched input element is valid – this checks validity at the time you call validate(), not the time at which the watcher was instantiated:

watcher.validate().valid; // => true 

If you want to do a quick validation and see no benefit in creating a watcher, you can do that too. This example will validate all input elements on the page, provided they have been created with Judge::FormBuilder:

judge.validate(document.getElementsByTagName('input'));
  // => [ { valid:true, messages:[], element:HTMLInputElement },
  //      { valid:false, messages:['must be even'], element:HTMLInputElement } ]

Ruby

What’s available

You can use any of the standard form builders from ActionView::Helpers::FormBuilder – just add :validate => true to the options hash.

Validators:

• presence;
• length (options: minimum, maximum, is);
• exclusion (options: in);
• inclusion (options: in);
• format (options: with, without); and
• numericality (options: greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, equal_to, odd, even, only_integer);
• acceptance;
• confirmation (input and confirmation input must have matching ids);
• any custom validator you have used, provided you define it on the client side and add it to judge.customValidators.

The allow_blank option is available everywhere it should be. Error messages are looked up according to the Rails i18n API.

If you have any custom form builders defined that override ActionView::Helpers::FormBuilder in your app, you could make them validatable on the client side by inheriting Judge::FormBuilder instead:

class MyCustomFormBuilder < Judge::FormBuilder
  # methods like text_field, text_area etc. go here
end

What’s not

The tokenizer option for the length validator is currently missing. Options like if, unless and on, which require more involved interactions with your Rails application, aren't really viable in a universal way on the client side and are simply ignored. Validating uniqueness with Judge might happen in the future, provided the method arrived at:

1. Makes no assumptions about your app;
2. Can add the necessary routes/actions to your app in a way that doesn't make anyone barf; and
3. Doesn't rely on jQuery to make requests.

For now, you can define a custom validator that makes an XMLHttpRequest if you need to.

JavaScript

This is the judge.js API documentation. For some literate programming-type goodness, check out the annotated JavaScript source, generated by Docco.

judge

The global namespace.

judge.validate(document.getElementsByTagName('input'));
  // => [ { valid:true, messages:[], element:HTMLInputElement },
  //      { valid:false, messages:['must be even'], element:HTMLInputElement } ]

# autoload this file 
class FooValidator < ActiveModel::EachValidator
  def validate_each(record, attribute, value)
    record.errors[attribute] << "Should be foo" unless value == "foo"
  end
end

# your model
class Thing < ActiveRecord::Base
  validates :title, :foo => true
end

# your view
<%= form_for(@thing, :builder => Judge::FormBuilder) do |f| %>
  <%= text_field :title, :validate => true %>
<% end %>

// on the client side
judge.customValidators.foo = function(options, messages) {
  // do your foo checking here
};

judge.Watcher

Constructor for watchers. Watchers are wrapper objects that contain a DOM element and various validation methods. The constructor takes one argument, a DOM element. For example:

var watcher = new judge.Watcher(document.getElementById('foo'));

watcher.validate();
  // => { valid:false, messages:['must be even'], element:HTMLInputElement }

watcher.validators;
  // => [ { kind:'presence', options:{ … } }, { kind:'format', options:{ … } } ]

judge.store

Contains some methods for storing and retrieving watchers in groups, for more customised validation scenarios. Have you ever wanted to validate a number of form elements when the user triggers an event? Storing your reference to the elements can make things easier.

judge.store.save('mykey', document.getElementById('foo'));
  // => [ { element:HTMLInputElement, … } ]

judge.store.save('mykey', document.getElementByTagName('input'));
  // => [ { element:HTMLInputElement, … }, { element:HTMLInputElement, … }, … ]

judge.store.get('mykey'); 
  // => [ { element:HTMLInputElement, … } ]

judge.store.get();
  // => { mykey:[ { element:HTMLInputElement, … } ], … }

judge.store.getDOM('mykey');
  // => [ HTMLInputElement, HTMLInputElement … ]
  
judge.store.getDOM();
  // => { mykey: [ HTMLInputElement ], mykey2: [ HTMLInputElement … ] }

judge.store.validate('mykey');
// => [ { valid:true, messages:[], element:HTMLInputElement },
//      { valid:false, messages:['must be even'], element:HTMLInputElement } ]

judge.store.validate();
  // => null

judge.store.remove('mykey', document.getElementById('foo'));
  // => { mykey:[ … ], mykey2:[ … ] }

judge.store.clear('mykey');
  // => { mykey:[], … }
judge.store.clear();
  // => {} 

Tests

Judge uses Travis for continuous integration. Current status of master branch:

Since Travis is still quite young, you might want to run the tests yourself:

# All tests, JavaScript tests headlessly (requires phantom.js)
$ bundle exec rake test

# Only Ruby tests
$ bundle exec rake test:ruby

# Only JavaScript tests, headless (requires phantom.js)
$ bundle exec rake jasmine:phantom

# Only JavaScript tests, with Selenium
$ bundle exec rake jasmine:ci