judge 1.5.0 → 2.0.0

data/README.md

@@ -1,26 +1,285 @@
-judge
-=====
+# Judge
 
 [![Build status](https://secure.travis-ci.org/joecorcoran/judge.png?branch=master)](http://travis-ci.org/joecorcoran/judge)
 
-Client-side form validation in Rails 3.
+Judge allows easy client side form validation for Rails 3 by porting many `ActiveModel::Validation` features to JavaScript. The most common validations work through JSON strings stored within HTML5 data attributes and are executed purely on the client side. Wherever you need to, Judge provides a simple interface for AJAX validations too.
 
-Usage
------
+## Rationale
 
-See http://judge.joecorcoran.co.uk for documentation.
+Whenever we need to give the user instant feedback on their form data, it's common to write some JavaScript to test form element values. Since whatever code we write to manage our data integrity in Ruby has to be copied as closely as possible in JavaScript, we end up with some very unsatisfying duplication of application logic.
 
-Extensions
-----------
+In many cases it would be simpler to safely expose the validation information from our models to the client – this is where Judge steps in.
 
-Use Judge with your favourite form building tool.
+## Installation
 
-* http://github.com/joecorcoran/judge-formtastic
-* http://github.com/joecorcoran/judge-simple_form
+Judge only supports Rails 3.1 or higher.
 
-License
--------
+Judge relies on [Underscore.js](underscore) in general and [JSON2.js](json2) for browsers that lack proper JSON support. If your application already makes use of these files, you can safely ignore the versions provided with Judge.
+
+### With asset pipeline enabled
+
+Add `judge` to your Gemfile and run `bundle install`.
+
+Mount the engine in your routes file, as follows:
+
+```ruby
+# config/routes.rb
+mount Judge::Engine => '/judge'
+```
+
+Judge makes three JavaScript files available. You'll always need *judge.js* and *underscore.js*, whereas *json2.js* is only needed in older browsers. Add the following lines to *application.js*:
+
+```
+//= require underscore
+//= require json2
+//= require judge
+```
+
+### Without asset pipeline
+
+Add `judge` to your Gemfile and run `bundle install`. Then run
+
+    $ rails generate judge:install path/to/your/js/dir
+
+to copy *judge.js* to your application. There are **--json2** and **--underscore** options to copy the dependencies too.
+
+Mount the engine in your routes file, as follows:
+
+```ruby
+# config/routes.rb
+mount Judge::Engine => '/judge'
+```
+    
+## Getting started
+
+Add a simple validation to your model.
+
+```ruby
+class Post < ActiveRecord::Base
+  validates :title, :presence => true
+end
+```
+
+Make sure your form uses the Judge::FormBuilder and add the :validate option to the field.
+
+```ruby
+form_for(@post, :builder => Judge::FormBuilder) do |f|
+  f.text_field :title, :validate => true
+end
+```
+
+On the client side, you can now validate the title input.
+
+```javascript
+judge.validate(document.getElementById('post_title'), {
+  valid: function(element) {
+    element.style.border = '1px solid green';
+  },
+  invalid: function(element, messages) {
+    element.style.border = '1px solid red';
+    alert(messages.join(','));
+  }
+});
+```
+
+## Judge::FormBuilder
+
+You can use any of the methods from the standard ActionView::Helpers::FormBuilder – just add `:validate => true` to the options hash.
+
+```ruby
+f.date_select :birthday, :validate => true
+```
+
+If you need to use Judge in conjunction with your own custom `FormBuilder` methods, make sure your `FormBuilder` inherits from `Judge::FormBuilder` and use the `#add_validate_attr!` helper.
+
+```ruby
+class MyFormBuilder < Judge::FormBuilder
+  def fancy_text_field(method, options = {})
+    add_validate_attr!(self.object, method, options)
+    # do your stuff here
+  end
+end
+```
+
+## Available 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);
+* uniqueness;
+* any `EachValidator` that you have written, provided you add a JavaScript version too and add it to `judge.eachValidators`.
+
+Options like *if*, *unless* and *on* are not available as they relate to record persistence.
+
+The *allow_blank* option is available everywhere it should be. Error messages are looked up according to the [Rails i18n API](http://guides.rubyonrails.org/i18n.html#translations-for-active-record-models).
+
+## Validating uniqueness
+
+In order to validate uniqueness Judge sends requests to the mounted `Judge::Engine` path, which responds with a JSON representation of an error message array. The array is empty if the value is valid.
+
+Since this effectively means adding an open, queryable endpoint to your application, Judge is cautious and requires you to be explicit about which attributes from which models you would like to expose for validation via XHR. Allowed attributes are configurable as in the following example. Note that you are only required to do this for `uniqueness` and any other validators you write that make requests to the server.
+
+```ruby
+# config/initializers/judge.rb
+Judge.configure do
+  expose Post, :title, :body
+end
+```
+
+## Mounting the engine at a different location
+
+You can choose a path other than `'/judge'` if you need to; just make sure to set this on the client side too:
+
+```ruby
+# config/routes.rb
+mount Judge::Engine => '/whatever'
+```
+
+```javascript
+judge.enginePath = '/whatever';
+```
+
+## Writing your own `EachValidator`
+
+If you write your own `ActiveModel::EachValidator`, Judge provides a way to ensure that your I18n error messages are available on the client side. Simply pass to `uses_messages` any number of message keys and Judge will look up the translated messages. Let's run through an example.
+
+```ruby
+class FooValidator < ActiveModel::EachValidator
+  uses_messages :not_foo
+
+  def validate_each(record, attribute, value)
+    unless value == 'foo'
+      record.errors.add(:title, :not_foo)
+    end
+  end
+end
+```
+
+We'll use the validator in the example above to validate the title attribute of a Post object:
+
+```ruby
+class Post < ActiveRecord::Base
+  validates :title, :foo => true
+end
+```
+
+```ruby
+form_for(@post, :builder => Judge::FormBuilder) do |f|
+  text_field :title, :validate => true
+end
+```
+
+Judge will look for the `not_foo` message at
+*activerecord.errors.models.post.attributes.title.not_foo*
+first and then onwards down the [Rails I18n lookup chain](http://guides.rubyonrails.org/i18n.html#translations-for-active-record-models).
+
+We then need to add our own validator method to the `judge.eachValidators` object on the client side:
+
+```javascript
+judge.eachValidators.foo = function(options, messages) {
+  var errorMessages = [];
+  // 'this' refers to the form element
+  if (this.value !== 'foo') {
+    errorMessages.push(messages.not_foo);
+  }
+  return new judge.Validation(errorMessages);
+};
+```
+
+## `judge.Validation`
+
+All client side validators must return a `Validation` – an object that can exist in three different states: *valid*, *invalid* or *pending*. If your validator function is synchronous, you can return a closed `Validation` simply by passing an array of error messages to the constructor.
+
+```javascript
+new judge.Validation([]);
+  // => empty array, this Validation is 'valid'
+new judge.Validation(['must not be blank']);
+  // => array has messages, this Validation is 'invalid'
+```
+
+The *pending* state is provided for asynchronous validation; a `Validation` object we will close some time in the future. Let's look at an example, using jQuery's popular `ajax` function:
+
+```javascript
+judge.eachValidators.bar = function() {
+  // create a 'pending' validation
+  var validation = new judge.Validation();
+  $.ajax('/bar-checking-service').done(function(messages) {
+    // You can close a Validation with either an array
+    // or a string that represents a JSON array
+    validation.close(messages);
+  });
+  return validation;
+};
+```
+
+There are helper functions, `judge.pending()` and `judge.closed()` for creating a new `Validation` too.
+
+```javascript
+judge.eachValidators.bar = function() {
+  return judge.closed(['not valid']);
+};
+
+judge.eachValidators.bar = function() {
+  var validation = new judge.pending();
+  doAsyncStuff(function(messages) {
+    validation.close(messages);
+  });
+  return validation;
+};
+```
+
+In the unlikely event that you don't already use a library with AJAX capability, a basic function is provided for making GET requests as follows:
+
+```javascript
+judge.get('/something', {
+  success: function(status, headers, text) {
+    // status code 20x
+  },
+  error: function(status, headers, text) {
+    // any other status code
+  }
+});
+```
+
+## Judge extensions
+
+If you use [Formtastic](https://github.com/justinfrench/formtastic) or [SimpleForm](https://github.com/plataformatec/simple_form), there are extension gems to help you use Judge within your forms without any extra setup. They are essentially basic patches that add the `:validate => true` option to the `input` method.
+
+### Formtastic
+
+https://github.com/joecorcoran/judge-formtastic
+
+```ruby
+gem 'judge-formtastic'
+```
+
+```ruby
+semantic_form_for(@user) do |f|
+  f.input :name, :validate => true
+end
+```
+
+### SimpleForm
+
+https://github.com/joecorcoran/judge-simple_form
+
+```ruby
+gem 'judge-simple_form'
+```
+
+```ruby
+simple_form_for(@user) do |f|
+  f.input :name, :validate => true
+end
+```
+
+## License
 
 Released under an MIT license (see LICENSE.txt).
 
-http://blog.joecorcoran.co.uk
+[blog.joecorcoran.co.uk](http://blog.joecorcoran.co.uk) | [@josephcorcoran](http://twitter.com/josephcorcoran)

data/app/assets/javascripts/judge.js

@@ -0,0 +1,391 @@
+// Judge 2.0.0
+// (c) 2011-2012 Joe Corcoran
+// http://raw.github.com/joecorcoran/judge/master/LICENSE.txt
+
+// This is judge.js: the JavaScript part of Judge. Judge is a client-side
+// validation gem for Rails 3. You can find the Judge gem API documentation at
+// <http://judge.joecorcoran.co.uk>.
+
+(function() {
+
+  var root = this;
+
+  // The judge namespace.
+  var judge = root.judge = {},
+      _     = root._;
+
+  judge.VERSION = '2.0.0';
+
+  // Trying to be a bit more descriptive than the basic error types allow.
+  var DependencyError = function(message) {
+    this.name = 'DependencyError';
+    this.message = message;
+  };
+  DependencyError.prototype = new Error();
+  DependencyError.prototype.constructor = DependencyError;
+
+  // Throw dependency errors if necessary.
+  if (typeof _ === 'undefined') {
+    throw new DependencyError('Ensure underscore.js is loaded');
+  }
+  if (_.isUndefined(root.JSON)) {
+    throw new DependencyError(
+      'Judge depends on the global JSON object (load json2.js in old browsers)'
+    );
+  }
+
+  // Returns the object type as represented in `Object.prototype.toString`.
+  var objectString = function(object) {
+    var string = Object.prototype.toString.call(object);
+    return string.replace(/\[|\]/g, '').split(' ')[1];
+  };
+
+  // A way of checking isArray, but including weird object types that are
+  // returned from collection queries.
+  var isCollection = function(object) {
+    var type  = objectString(object),
+        types = [
+          'Array',
+          'NodeList',
+          'StaticNodeList',
+          'HTMLCollection',
+          'HTMLFormElement',
+          'HTMLAllCollection'
+        ];
+    return _(types).include(type);
+  };
+
+  // eval is used here for stuff like `(3, '<', 4) => '3 < 4' => true`.
+  var operate = function(input, operator, validInput) {
+    return eval(input+' '+operator+' '+validInput);
+  };
+
+  // Some nifty numerical helpers.
+  var
+    isInt  = function(value) { return value === +value && value === (value|0); },
+    isEven = function(value) { return (value % 2 === 0) ? true : false; },
+    isOdd  = function(value) { return !isEven(value); };
+
+  // Converts a Ruby regular expression, given as a string, into JavaScript.
+  // This is rudimentary at best, as there are many, many differences between
+  // Ruby and JavaScript when it comes to regexp-fu. The plan is to replace this
+  // with an XRegExp plugin which will port some Ruby regexp features to
+  // JavaScript.
+  var convertFlags = function(string) {
+    var on = string.split('-')[0];
+    return (/m/.test(on)) ? 'm' : '';
+  };
+  var convertRegExp = function(string) {
+    var parts  = string.slice(1, -1).split(':'),
+        flags  = parts.shift().replace('?', ''),
+        source = parts.join(':').replace(/\\\\/g, '\\');
+    return new RegExp(source, convertFlags(flags));
+  };
+
+  // Returns a browser-specific XHR object, or null if one cannot be constructed.
+  var reqObj = function() {
+    return (
+      (root.ActiveXObject && new root.ActiveXObject('Microsoft.XMLHTTP')) ||
+      (root.XMLHttpRequest && new root.XMLHttpRequest()) ||
+      null
+    );
+  };
+
+  // Performs a GET request using the browser's XHR object. This provides very
+  // basic ajax capability and was written specifically for use in the provided
+  // uniqueness validator without requiring jQuery.
+  var get = judge.get = function(url, callbacks) {
+    var req = reqObj();
+    if (!!req) {
+      req.onreadystatechange = function() {
+        if (req.readyState === 4) {
+          req.onreadystatechange = void 0;
+          var callback = /^20\d$/.test(req.status) ? callbacks.success : callbacks['error'];
+          callback(req.status, req.responseHeaders, req.responseText);
+        }
+      };
+      req.open('GET', url, true);
+      req.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
+      req.setRequestHeader('Accept', 'application/json');
+      req.send();
+    }
+    return req;
+  };
+
+  // Some helper methods for working with Rails-style input attributes.
+  var
+    attrFromName = function(name) {
+      var matches, attr = '';
+      if (matches = name.match(/\[(\w+)\]$/)) {
+        attr = matches[1];
+      }
+      return attr;
+    };
+    classFromName = function(name) {
+      var bracketed, klass = '';
+      if (bracketed = name.match(/\[(\w+)\]/g)) {
+        klass = (bracketed.length > 1) ? camelize(debracket(bracketed[0])) : name.match(/^\w+/)[0];
+      }
+      return klass;
+    };
+    debracket = function(str) {
+      return str.replace(/\[|\]/g, '');
+    };
+    camelize = function(str) {
+      return str.replace(/(^[a-z]|\_[a-z])/g, function($1) {
+        return $1.toUpperCase().replace('_','');
+      });
+    };
+
+  // Build the URL necessary to send a GET request to the mounted validations
+  // controller to check the validity of the given form element.
+  var urlFor = judge.urlFor = function(el, kind) {
+    var path   = judge.enginePath,
+        params = {
+          'klass'    : classFromName(el.name),
+          'attribute': attrFromName(el.name),
+          'value'    : encodeURIComponent(el.value),
+          'kind'     : kind
+        };
+    return encodeURI(path + queryString(params));
+  };
+
+  // Convert an object literal into an encoded query string.
+  var queryString = function(obj) {
+    var e  = encodeURIComponent,
+        qs = _.reduce(obj, function(memo, value, key) {
+      return memo + e(key) + '=' + e(value) + '&';
+    }, '?');
+    return qs.replace(/&$/, '').replace(/%20/g, '+');
+  };
+
+  // Default path to mounted engine. Override this if you decide to mount
+  // Judge::Engine at a different location.
+  judge.enginePath = '/judge';
+
+  // Provides event dispatch behaviour when mixed into an object. Concept
+  // taken from Backbone.js, stripped down and altered.
+  // Backbone.js (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc.
+  // http://backbonejs.org
+  var Dispatcher = judge.Dispatcher = {
+    on: function(event, callback, scope) {
+      if (!_.isFunction(callback)) return this;
+      this._events || (this._events = {});
+      var events = this._events[event] || (this._events[event] = []);
+      events.push({ callback: callback, scope: scope || this });
+      this.trigger('bind');
+      return this;
+    },
+    trigger: function(event) {
+      if (!this._events) return this;
+      var args      = _.rest(arguments),
+          events = this._events[event] || (this._events[event] = []);
+      _.each(events, function(event) {
+        event.callback.apply(event.scope, args);
+      });
+      return this;
+    }
+  };
+
+  // A queue of closed or pending Validation objects.
+  var ValidationQueue = judge.ValidationQueue = function(element) {
+    this.element        = element;
+    this.validations    = [];
+    this.attrValidators = root.JSON.parse(this.element.getAttribute('data-validate'));
+
+    _.each(this.attrValidators, function(av) {
+      if (this.element.value.length || av.options.allow_blank !== true) {
+        var method     = _.bind(judge.eachValidators[av.kind], this.element),
+            validation = method(av.options, av.messages);
+        validation.on('close', this.tryClose, this);
+        this.on('bind', this.tryClose, this);
+        this.validations.push(validation);
+      }
+    }, this);
+    this.tryClose.call(this);
+  };
+  _.extend(ValidationQueue.prototype, Dispatcher, {
+    tryClose: function() {
+      var report = _.reduce(this.validations, function(obj, validation) {
+        obj.statuses = _.union(obj.statuses, [validation.status()]);
+        obj.messages = _.union(obj.messages, _.compact(validation.messages));
+        return obj;
+      }, { statuses: [], messages: [] }, this);
+      if (!_.contains(report.statuses, 'pending')) {
+        var status = _.contains(report.statuses, 'invalid') ? 'invalid' : 'valid';
+        this.trigger('close', this.element, status, report.messages);
+        this.trigger(status, this.element, report.messages);
+      }
+    }
+  });
+
+  // Event-capable object returned by validator methods.
+  var Validation = judge.Validation = function(messages) {
+    this.messages = null;
+    if (_.isArray(messages)) this.close(messages);
+    return this;
+  };
+  _.extend(Validation.prototype, Dispatcher, {
+    close: function(messages) {
+      if (this.closed()) return null;
+      this.messages = _.isString(messages) ? root.JSON.parse(messages) : messages;
+      this.trigger('close', this.status(), this.messages);
+      return this;
+    },
+    closed: function() {
+      return _.isArray(this.messages);
+    },
+    status: function() {
+      if (!this.closed()) return 'pending';
+      return this.messages.length > 0 ? 'invalid' : 'valid';
+    }
+  });
+
+  // Convenience methods for creating Validation objects in different states.
+  var pending = judge.pending = function() {
+    return new Validation();
+  };
+  var closed = judge.closed = function(messages) {
+    return new Validation(messages);
+  };
+
+  // Ported ActiveModel validators.
+  // See <http://api.rubyonrails.org/classes/ActiveModel/Validations.html> for
+  // the originals.
+  judge.eachValidators = {
+    // ActiveModel::Validations::PresenceValidator
+    presence: function(options, messages) {
+      return closed(this.value.length ? [] : [messages.blank]);
+    },
+    
+    // ActiveModel::Validations::LengthValidator
+    length: function(options, messages) {
+      var msgs = [],
+          types = {
+            minimum: { operator: '<',  message: 'too_short' },
+            maximum: { operator: '>',  message: 'too_long' },
+            is:      { operator: '!=', message: 'wrong_length' }
+          };
+      _(types).each(function(properties, type) {
+        var invalid = operate(this.value.length, properties.operator, options[type]);
+        if (_(options).has(type) && invalid) {
+          msgs.push(messages[properties.message]);
+        }
+      }, this);
+      return closed(msgs);
+    },
+    
+    // ActiveModel::Validations::ExclusionValidator
+    exclusion: function(options, messages) {
+      var stringIn = _(options['in']).map(function(o) {
+        return o.toString();
+      });
+      return closed(
+        _.include(stringIn, this.value) ? [messages.exclusion] : []
+      );
+    },
+    
+    // ActiveModel::Validations::InclusionValidator
+    inclusion: function(options, messages) {
+      var stringIn = _(options['in']).map(function(o) {
+        return o.toString();
+      });
+      return closed(
+        !_.include(stringIn, this.value) ? [messages.inclusion] : []
+      );
+    },
+    
+    // ActiveModel::Validations::NumericalityValidator
+    numericality: function(options, messages) {
+      var operators = {
+            greater_than: '>',
+            greater_than_or_equal_to: '>=',
+            equal_to: '==',
+            less_than: '<',
+            less_than_or_equal_to: '<='
+          },
+          msgs = [],
+          parsedValue = parseFloat(this.value, 10); 
+
+      if (isNaN(Number(this.value))) {
+        msgs.push(messages.not_a_number);
+      } else {
+        if (options.odd && isEven(parsedValue)) msgs.push(messages.odd);
+        if (options.even && isOdd(parsedValue)) msgs.push(messages.even);
+        if (options.only_integer && !isInt(parsedValue)) msgs.push(messages.not_an_integer);
+        _(operators).each(function(operator, key) {
+          var valid = operate(parsedValue, operators[key], parseFloat(options[key], 10));
+          if (_(options).has(key) && !valid) {
+            msgs.push(messages[key]);
+          }
+        });
+      }
+      return closed(msgs);
+    },
+    
+    // ActiveModel::Validations::FormatValidator
+    format: function(options, messages) {
+      var msgs  = [];
+      if (_(options).has('with')) {
+        var withReg = convertRegExp(options['with']);
+        if (!withReg.test(this.value)) {
+          msgs.push(messages.invalid);
+        }
+      }
+      if (_(options).has('without')) {
+        var withoutReg = convertRegExp(options.without);
+        if (withoutReg.test(this.value)) {
+          msgs.push(messages.invalid);
+        }
+      }
+      return closed(msgs);
+    },
+    
+    // ActiveModel::Validations::AcceptanceValidator
+    acceptance: function(options, messages) {
+      return closed(this.checked === true ? [] : [messages.accepted]);
+    },
+    
+    // ActiveModel::Validations::ConfirmationValidator
+    confirmation: function(options, messages) {
+      var id       = this.getAttribute('id'),
+          confId   = id + '_confirmation',
+          confElem = root.document.getElementById(confId);
+      return closed(
+        this.value === confElem.value ? [] : [messages.confirmation]
+      );
+    },
+
+    // ActiveModel::Validations::UniquenessValidator
+    uniqueness: function(options, messages) {
+      var validation = pending();          
+      get(urlFor(this, 'uniqueness'), {
+        success: function(status, headers, text) {
+          validation.close(text);
+        },
+        error: function(status, headers, text) {
+          validation.close(['Request error: ' + status]);
+        }
+      });
+      return validation;
+    }
+  };
+
+  var isCallbacksObj = function(obj) {
+    return _.isObject(obj) && _.has(obj, 'valid') && _.has(obj, 'invalid');
+  };
+
+  // Method for validating a form element. Pass either a single
+  // callback or one for valid and one for invalid.
+  judge.validate = function(element, callbacks) {
+    var queue = new ValidationQueue(element);
+    if (_.isFunction(callbacks)) {
+      queue.on('close', callbacks);
+    } else if (isCallbacksObj(callbacks)) {
+      queue.on('valid', callbacks.valid);
+      queue.on('invalid', callbacks.invalid);
+    }
+    return queue;
+  };
+
+}).call(this);