judge 0.3.1 → 0.4.0

data/judge.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{judge}
-  s.version = "0.3.1"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joe Corcoran"]
-  s.date = %q{2011-07-26}
+  s.date = %q{2011-08-03}
   s.description = %q{Validate forms in-place using your model validations}
   s.email = %q{joe@tribesports.com}
   s.extra_rdoc_files = [
@@ -25,6 +25,8 @@ Gem::Specification.new do |s|
     "README.md",
     "Rakefile",
     "VERSION",
+    "docs/docco.css",
+    "docs/judge.html",
     "judge.gemspec",
     "lib/generators/judge/judge_generator.rb",
     "lib/generators/judge/templates/json2.js",
@@ -78,8 +80,6 @@ Gem::Specification.new do |s|
     "test/dummy/db/migrate/20110725082530_create_continent_country_and_city_tables.rb",
     "test/dummy/db/schema.rb",
     "test/dummy/db/test.sqlite3",
-    "test/dummy/log/development.log",
-    "test/dummy/log/production.log",
     "test/dummy/log/server.log",
     "test/dummy/public/404.html",
     "test/dummy/public/422.html",

data/lib/generators/judge/templates/judge.js

@@ -1,13 +1,17 @@
+// This is the JavaScript part of Judge, a client-side validation gem for Rails 3.
+// You can find a guide and some more traditional API documentation at <http://joecorcoran.github.com/judge/>.
+// Hopefully this page will help you understand what's happening under the hood.
+
 /*jshint curly: true, evil: true, newcap: true, noarg: true */
-/*global _: false, JSON: false */
+/*global _: false, JSON: false */  
 
-// global namespace
+// The judge namespace.
 var judge = judge || {};
 
-// Watcher is a DOM element wrapper that judge uses to store validation info and instance methods
+// A judge.Watcher is a DOM element wrapper that judge uses to store validation info and instance methods.
 judge.Watcher = function (element) {
   
-  // dependency errors
+  // Throw dependency errors.
   if (!window.hasOwnProperty('_')) {
     throw new ReferenceError('[judge] Underscore.js not found');
   }
@@ -15,7 +19,7 @@ judge.Watcher = function (element) {
     throw new ReferenceError('[judge] JSON global object not found');
   }
 
-  // constructor usage errors
+  // Throw some constructor usage errors.
   if (_(element).isUndefined()) {
     throw new ReferenceError('[judge] No DOM element passed to constructor');
   }
@@ -23,22 +27,24 @@ judge.Watcher = function (element) {
     throw new TypeError('[judge] Cannot construct new Watcher for object of this type');
   }
   if (element.getAttribute('data-validate') === null) {
-    throw new ReferenceError('[judge] Cannot construct new Watcher for this element, please use judge form builder methods in your view');
+    throw new ReferenceError('[judge] Cannot construct Watcher for this element, use judge form builders');
   }
   if (element.form.getAttribute('data-error-messages') === null) {
-    throw new ReferenceError('[judge] Element parent form was not created using judge form helper, please amend');
+    throw new ReferenceError('[judge] Parent form was not created using judge form helper, please amend');
   }
 
 
-  // convenience accessor
+  // Convenient access to this Watcher.
   var instance = this;
 
-  // common instance properties
+  // Watcher instance properties.
   this.element         = element;
   this.validators      = JSON.parse(this.element.getAttribute('data-validate'));
   this.defaultMessages = JSON.parse(this.element.form.getAttribute('data-error-messages'));
   
-  // instance methods
+  // This instance method returns the validity of the watched element, 
+  // represented as an array of objects containing validity information
+  // for each validator found on the element.
   this.validate = function() {
     instance.errorMessages = [];
     var validators = instance.validators,
@@ -63,11 +69,14 @@ judge.Watcher = function (element) {
 
 };
 
-// instance methods
+// Watcher prototype methods.
 judge.Watcher.prototype.validates = function() {
   var instance        = this,
       extendedMethods = judge.customValidators,
       methods         = {
+
+        // Presence validator ported as closely as possible
+        // from [ActiveModel::Validations::PresenceValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/PresenceValidator.html).
         presence: function(options) {
           if (instance.element.value.length) {
             return { valid:true };
@@ -76,6 +85,8 @@ judge.Watcher.prototype.validates = function() {
           }
         },
         
+        // Length validator ported as closely as possible
+        // from [ActiveModel::Validations::LengthValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/LengthValidator.html).
         length: function(options) {
           var msgs = [],
               length = instance.element.value.length,
@@ -85,32 +96,45 @@ judge.Watcher.prototype.validates = function() {
                 is:      { operator: '!=', message: 'wrong_length' }
               };
           _(types).each(function(properties, type) {
-            if (options.hasOwnProperty(type) && judge.utils.operate(length, properties.operator, options[type])) {
+            var invalid = judge.utils.operate(length, properties.operator, options[type]);
+            if (options.hasOwnProperty(type) && invalid) {
               var m = options[properties.message] || instance.defaultMessages[properties.message];
               msgs.push(judge.utils.countMsg(m, options[type]));
             }
           });
           return msgs.length ? { valid:false, messages:msgs } : { valid:true };
         },
-
+        
+        // Exclusion validator ported as closely as possible
+        // from [ActiveModel::Validations::ExclusionValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/ExclusionValidator.html).
         exclusion: function(options) {
           var stringIn = _(options['in']).map(function(o) { return o.toString(); });
           if (_(stringIn).include(instance.element.value)) {
-            return { valid:false, messages:[options.message || instance.defaultMessages.exclusion] };
+            return {
+              valid:false,
+              messages:[options.message || instance.defaultMessages.exclusion]
+            };
           } else {
             return { valid:true };
           }
         },
-
+        
+        // Inclusion validator ported as closely as possible
+        // from [ActiveModel::Validations::InclusionValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/InclusionValidator.html).
         inclusion: function(options) {
           var stringIn = _(options['in']).map(function(o) { return o.toString(); });
           if (!_(stringIn).include(instance.element.value)) {
-            return { valid:false, messages:[options.message || instance.defaultMessages.inclusion] };
+            return {
+              valid:false,
+              messages:[options.message || instance.defaultMessages.inclusion]
+            };
           } else {
             return { valid:true };
           }
         },
-
+        
+        // Numericality validator ported as closely as possible
+        // from [ActiveModel::Validations::NumericalityValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/NumericalityValidator.html).
         numericality: function(options) {
           var operators = {
                 greater_than: '>',
@@ -121,16 +145,23 @@ judge.Watcher.prototype.validates = function() {
               },
               msgs = [],
               value = instance.element.value,
-              parsedValue = parseFloat(value); 
+              parsedValue = parseFloat(value, 10); 
 
           if (isNaN(Number(value))) {
             msgs.push(options.message || instance.defaultMessages.not_a_number);
           } else {
-            if (options.odd && judge.utils.isEven(parsedValue)) { msgs.push(instance.defaultMessages.odd); }
-            if (options.even && judge.utils.isOdd(parsedValue)) { msgs.push(instance.defaultMessages.even); }
-            if (options.only_integer && !judge.utils.isInt(parsedValue)) { msgs.push(instance.defaultMessages.not_an_integer); }
+            if (options.odd && judge.utils.isEven(parsedValue)) {
+              msgs.push(instance.defaultMessages.odd);
+            }
+            if (options.even && judge.utils.isOdd(parsedValue)) {
+              msgs.push(instance.defaultMessages.even);
+            }
+            if (options.only_integer && !judge.utils.isInt(parsedValue)) {
+              msgs.push(instance.defaultMessages.not_an_integer);
+            }
             _(operators).each(function(operator, key) {
-              if (options.hasOwnProperty(key) && !judge.utils.operate(parsedValue, operators[key], parseFloat(options[key]))) {
+              var valid = judge.utils.operate(parsedValue, operators[key], parseFloat(options[key], 10));
+              if (options.hasOwnProperty(key) && !valid) {
                 var m = options.message || instance.defaultMessages[key];
                 msgs.push(judge.utils.countMsg(m, options[key]));
               }
@@ -138,29 +169,42 @@ judge.Watcher.prototype.validates = function() {
           }
           return msgs.length? { valid:false, messages:msgs } : { valid:true };
         },
-
+        
+        // Format validator ported as closely as possible
+        // from [ActiveModel::Validations::FormatValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/FormatValidator.html).
         format: function(options) {
           var msgs  = [],
               value = instance.element.value;
           if (options.hasOwnProperty('with')) {
             var withReg = judge.utils.convertRegExp(options['with']);
-            if (!withReg.test(value)) { msgs.push(options.message || instance.defaultMessages.invalid); }
+            if (!withReg.test(value)) {
+              msgs.push(options.message || instance.defaultMessages.invalid);
+            }
           }
           if (options.hasOwnProperty('without')) {
             var withoutReg = judge.utils.convertRegExp(options.without);
-            if (withoutReg.test(value)) { msgs.push(options.message || instance.defaultMessages.invalid); }
+            if (withoutReg.test(value)) {
+              msgs.push(options.message || instance.defaultMessages.invalid);
+            }
           }
           return msgs.length ? { valid:false, messages:msgs } : { valid:true };
         },
-
+        
+        // Acceptance validator ported as closely as possible
+        // from [ActiveModel::Validations::AcceptanceValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/AcceptanceValidator.html).
         acceptance: function(options) {
           if (instance.element.checked === true) {
             return { valid:true };
           } else {
-            return { valid:false, messages:[options.message || instance.defaultMessages.accepted] };
+            return {
+              valid:false,
+              messages:[options.message || instance.defaultMessages.accepted]
+            };
           }
         },
-
+        
+        // Confirmation validator ported as closely as possible
+        // from [ActiveModel::Validations::ConfirmationValidator](http://api.rubyonrails.org/classes/ActiveModel/Validations/ConfirmationValidator.html).
         confirmation: function(options) {
           var id       = instance.element.getAttribute('id'),
               confId   = id + '_confirmation',
@@ -168,25 +212,31 @@ judge.Watcher.prototype.validates = function() {
           if (instance.element.value === confElem.value) {
             return { valid:true };
           } else {
-            return { valid:false, messages:[options.message || instance.defaultMessages.confirmation] };
+            return {
+              valid:false,
+              messages:[options.message || instance.defaultMessages.confirmation]
+            };
           }
         }
       };
+  // Return all validation methods, including those found in judge.customValidators.
+  // If you name a custom validation method the same as a default one, for example
+  //   `judge.customValidators.presence = function() {};`
+  // then the custom method _will overwrite_ the default one, so be careful!
   return _.extend(methods, extendedMethods);
 };
 
-// static properties
+// This object should contain any judge validation methods
+// that correspond to custom validators used in the model.
 judge.customValidators = {};
 
-// storage
+// The judge store is now open :)
 judge.store = (function() {
-  // private
   var store   = {};
 
-  // public methods
   return {
 
-    // store Watcher for element against user defined key
+    // Stores a Watcher for an element against a user defined key.
     save: function(key, element) {
       var elements = judge.utils.isCollection(element) ? element : [element];
       _(elements).each(function(element) {
@@ -200,7 +250,7 @@ judge.store = (function() {
       return store;
     },
 
-    // remove individual stored Watcher
+    // Removes an individual stored Watcher.
     remove: function(key, element) {
       if (!store.hasOwnProperty(key)) {
         return null;
@@ -210,13 +260,15 @@ judge.store = (function() {
       return store;
     },
 
-    // get entire store object, or get array of Watchers stored against key
+    // Returns the entire store object, or an array of Watchers stored against
+    // the given key.
     get: function(key) {
       if (_(key).isUndefined()) { return store; }
       return store.hasOwnProperty(key) ? store[key] : null;
     },
 
-    // get store object with watchers converted to elements, or DOM elements stored within all watchers stored against key
+    // Returns the entire store object with Watchers converted to elements, 
+    // or all DOM elements stored within all Watchers stored against the given key.
     getDOM: function(key) {
       if (_(key).isUndefined()) {
         var convertedStore = {};
@@ -228,7 +280,8 @@ judge.store = (function() {
       return store.hasOwnProperty(key) ? _(store[key]).pluck('element') : null;
     },
 
-    // wipe entire store object, or wipe all Watchers stored against key
+    // Wipes the entire store object, or wipes all Watchers stored against 
+    // the given key.
     clear: function(key) {
       if (_(key).isUndefined()) {
         store = {};
@@ -242,7 +295,8 @@ judge.store = (function() {
   };
 }());
 
-// validate element(s) without storing
+// Validate all given element(s) without storing. Watcher creation is handled for you,
+// but the created Watchers will not be returned, so it's less flexible.
 judge.validate = function(elements) {
   var results = [];
   elements = judge.utils.isCollection(elements) ? elements : [elements];
@@ -253,9 +307,10 @@ judge.validate = function(elements) {
   return results;
 };
 
-// utils
+// The obligatory utilities.
 judge.utils = {
-  // determine whether object is a DOM element of the types that judge can work with
+  
+  // Determines whether an object is a DOM element of the types that judge can work with.
   isValidatable: function(object) {
     var type = judge.utils.getObjectString(object);
     return (
@@ -265,7 +320,7 @@ judge.utils = {
     );
   },
 
-  // a way of checking isArray but including NodeList
+  // A way of checking isArray but including NodeList.
   isCollection: function(object) {
     var type = judge.utils.getObjectString(object);
     return (
@@ -273,27 +328,32 @@ judge.utils = {
     );
   },
 
-  // return object type as represented in Object.prototype.toString
+  // Returns the object type as represented in `Object.prototype.toString`.
   getObjectString: function(object) {
     var string = Object.prototype.toString.call(object);
     return string.replace(/\[|\]/g, '').split(' ')[1];
   },
 
-  // (3, '<', 4) => '3 < 4' => true
+  // OMG! How can you use eval, you monster! It's totally evil!
+  // It's used for stuff like `(3, '<', 4) => '3 < 4' => true`.
   operate: function(input, operator, validInput) {
     return eval(input+' '+operator+' '+validInput);
   },
 
-  // sub expected value into error message
+  // Sub the expected value into an error message.
   countMsg: function(message, count) { return message.replace(/\%\{count\}/, count); },
 
-  // numerical helpers
+  // Some nifty numerical helpers.
   isInt: function(value) { return value === +value && value === (value|0); },
   isFloat: function(value) { return value === +value && value !== (value|0); },
   isEven: function(value) { return (value % 2 === 0) ? true : false; },
   isOdd: function(value) { return !judge.utils.isEven(value); },
 
-  // convert ruby flag-first, string formatted RegExp into JS
+  // Converts a ruby flag-first formatted regular expression, given as a string, into JavaScript.
+  // This is rudimentary at best, as there are many, many difference between Ruby
+  // and JavaScript when it comes to regexp-fu. Basically, if you validate your records
+  // records using complex regular expressions AND you hope that this will "just work"
+  // on the client-side too&hellip; you are going to be pretty disappointed.
   convertRegExp: function(string) {
     var p = string.slice(1, -1).split(':'),
         o = p.shift(),

data/lib/judge/form.rb

@@ -4,7 +4,7 @@ module Judge
 
     include ActionView::Helpers::TagHelper
     
-    %w{text_field text_area}.each do |type|
+    %w{text_field text_area password_field}.each do |type|
       helper = <<-END
         def validated_#{type}(method, options = {})
           options = { "data-validate" => Judge::Utils.jsonify_validators(self.object, method) }.merge(options)
@@ -19,7 +19,6 @@ module Judge
       @template.radio_button(@object_name, method, tag_value, objectify_options(options))
     end
     
-
     def validated_check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
       options = { "data-validate" => Judge::Utils.jsonify_validators(self.object, method) }.merge(options)
       @template.check_box(self.object_name, method, objectify_options(options), checked_value, unchecked_value)
@@ -39,6 +38,22 @@ module Judge
       html_options = { "data-validate" => Judge::Utils.jsonify_validators(self.object, method) }.merge(html_options)
       @template.grouped_collection_select(self.object_name, method, collection, group_method, group_label_method, option_key_method, option_value_method, objectify_options(options), @default_options.merge(html_options))
     end
+
+    %w{date_select datetime_select time_select}.each do |type|
+      helper = <<-END
+        def validated_#{type}(method, options = {}, html_options = {})
+          html_options = { "data-validate" => Judge::Utils.jsonify_validators(self.object, method) }.merge(html_options)
+          @template.#{type}(self.object_name, method, objectify_options(options), html_options)
+        end
+      END
+      class_eval helper, __FILE__, __LINE__
+    end
+
+    def validated_time_zone_select(method, priority_zones = nil, options = {}, html_options = {})
+      html_options = { "data-validate" => Judge::Utils.jsonify_validators(self.object, method) }.merge(html_options)
+      @template.time_zone_select(@object_name, method, priority_zones, objectify_options(options), @default_options.merge(html_options))
+    end
+    
     
   end
 

data/test/dummy/app/models/foo.rb

@@ -8,6 +8,12 @@ class Foo < ActiveRecord::Base
   validates :five, :format => { :without => /[A-Za-z]+/ }
   validates :six, :acceptance => true
   validates :seven, :confirmation => true
+  validates :eight, :confirmation => true
+
+  validates :nine, :presence => true
+  validates :ten, :presence => true
+  validates :eleven, :presence => true
+  validates :twelve, :presence => true
 
 end
 

data/test/dummy/app/views/foos/new.html.erb

@@ -41,6 +41,27 @@
     <%= f.label :seven %><br />
     <%= f.validated_text_field :seven %>
   </div>
+  <div class="field">
+    <%= f.label :eight %><br />
+    <%= f.validated_password_field :eight %>
+  </div>
+  <div class="field">
+    <%= f.label :nine %><br />
+    <%= f.validated_time_zone_select :nine, ActiveSupport::TimeZone.us_zones, :include_blank => true %>
+  </div>
+  <div class="field">
+    <%= f.label :ten %><br />
+    <%= f.validated_time_select :ten, :include_blank => true, :ignore_date => true %>
+  </div>
+  <div class="field">
+    <%= f.label :eleven %><br />
+    <%= f.validated_datetime_select :eleven, :include_blank => true %>
+  </div>
+  <div class="field">
+    <%= f.label :twelve %><br />
+    <%= f.validated_date_select :twelve, :include_blank => true %>
+  </div>
+
   <div class="actions">
     <%= f.submit %>
   </div>