sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

data/frameworks/sproutcore/frameworks/foundation/validators/credit_card.js

@@ -0,0 +1,125 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/** @class
+  Validate a field value as a credit card number. 
+  
+  This validator will perform a basic check to ensure the credit card number
+  is mathematically valid.  It will also accept numbers with spaces, dashes
+  or other punctuation.  
+  
+  Converted credit card numbers are broken into units of 4.
+  
+  Basic credit card validation courtesy David Leppek 
+  (https://www.azcode.com/Mod10)
+
+  @extends SC.Validator
+  @since SproutCore 1.0
+*/
+SC.Validator.CreditCard = SC.Validator.extend(
+/** @scope SC.Validator.CreditCard.prototype */ {
+
+  /**
+    Expects a string of 16 digits.  Will split into groups of 4 for display.
+  */
+  fieldValueForObject: function(object, form, field) {
+    if (typeof(object) == "string" && object.length == 16) {
+      object = [object.slice(0,4),object.slice(4,8),object.slice(8,12),object.slice(12,16)].join(' ') ;
+    }
+    return object ;
+  },
+
+  /**
+    Removes all whitespace or dashes to make a single string.
+  */
+  objectForFieldValue: function(value, form, field) {
+    return value.replace(/[\s-\.\:]/g,'') ;
+  },
+  
+  validate: function(form, field) { 
+    return this.checkNumber(field.get('fieldValue')) ; 
+  },
+  
+  validateError: function(form, field) {
+    var label = field.get('errorLabel') || 'Field' ;
+    return SC.$error("Invalid.CreditCard(%@)".loc(label), label);
+  },
+  
+  /** 
+    Allow only numbers, dashes, and spaces 
+  */
+  validateKeyDown: function(form, field, charStr) {
+    return !!charStr.match(/[0-9\- ]/);
+  },
+  
+  checkNumber: function(ccNumb) {
+    
+    if (!ccNumb || ccNumb.length===0) return YES; // do not validate empty
+    
+    // remove any spaces or dashes
+    ccNumb = ccNumb.replace(/[^0-9]/g,'');
+    
+    var valid = "0123456789";  // Valid digits in a credit card number
+    var len = ccNumb.length;  // The length of the submitted cc number
+    var iCCN = parseInt(ccNumb,0);  // integer of ccNumb
+    var sCCN = ccNumb.toString();  // string of ccNumb
+    sCCN = sCCN.replace (/^\s+|\s+$/g,'');  // strip spaces
+    var iTotal = 0;  // integer total set at zero
+    var bNum = true;  // by default assume it is a number
+    var bResult = false;  // by default assume it is NOT a valid cc
+    var temp;  // temp variable for parsing string
+    var calc;  // used for calculation of each digit
+
+    // Determine if the ccNumb is in fact all numbers
+    for (var j=0; j<len; j++) {
+      temp = "" + sCCN.substring(j, j+1);
+      if (valid.indexOf(temp) == "-1"){bNum = false;}
+    }
+
+    // if it is NOT a number, you can either alert to the fact, 
+    // or just pass a failure
+    if(!bNum) bResult = false;
+
+    // Determine if it is the proper length 
+    if((len === 0)&&(bResult)){  // nothing, field is blank AND passed above # check
+      bResult = false;
+    } else{  // ccNumb is a number and the proper length - let's see if it is a valid card number
+      if(len >= 15){  // 15 or 16 for Amex or V/MC
+        for(var i=len;i>0;i--){  // LOOP throught the digits of the card
+          calc = parseInt(iCCN,0) % 10;  // right most digit
+          calc = parseInt(calc,0);  // assure it is an integer
+          iTotal += calc;  // running total of the card number as we loop - Do Nothing to first digit
+          i--;  // decrement the count - move to the next digit in the card
+          iCCN = iCCN / 10;                               // subtracts right most digit from ccNumb
+          calc = parseInt(iCCN,0) % 10 ;    // NEXT right most digit
+          calc = calc *2;                                 // multiply the digit by two
+          // Instead of some screwy method of converting 16 to a string and then parsing 1 and 6 and then adding them to make 7,
+          // I use a simple switch statement to change the value of calc2 to 7 if 16 is the multiple.
+          switch(calc){
+            case 10: calc = 1; break;       //5*2=10 & 1+0 = 1
+            case 12: calc = 3; break;       //6*2=12 & 1+2 = 3
+            case 14: calc = 5; break;       //7*2=14 & 1+4 = 5
+            case 16: calc = 7; break;       //8*2=16 & 1+6 = 7
+            case 18: calc = 9; break;       //9*2=18 & 1+8 = 9
+            default: calc = calc;           //4*2= 8 &   8 = 8  -same for all lower numbers
+          }                                               
+        iCCN = iCCN / 10;  // subtracts right most digit from ccNum
+        iTotal += calc;  // running total of the card number as we loop
+      }  // END OF LOOP
+      if ((iTotal%10)===0){  // check to see if the sum Mod 10 is zero
+        bResult = true;  // This IS (or could be) a valid credit card number.
+      } else {
+        bResult = false;  // This could NOT be a valid credit card number
+        }
+      }
+    }
+    return bResult; // Return the results
+  }
+    
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/date.js

@@ -0,0 +1,52 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/**
+  Handle parsing and display of dates.
+  
+  @class
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator.Date = SC.Validator.extend(
+/** @scope SC.Validator.Date.prototype */ {
+
+  /**
+    The standard format you want the validator to convert dates to.
+  */
+  format: 'NNN d, yyyy h:mm:ss a',
+  
+  /**
+    if we have a number, then convert to a date object.
+  */
+  fieldValueForObject: function(object, form, field) {
+    var date ;
+    if (typeof(object) == "number") {
+      date = new Date(object) ;
+    } else if (object instanceof Date) { date = object; }
+      
+    if (date) object = date.format(this.get('format')) ;
+    
+    return object ;
+  },
+
+  /**
+    Try to pase value as a date. convert into a number, or return null if
+    it could not be parsed.
+  */
+  objectForFieldValue: function(value, form, field) {
+    if (value) {
+      var date = Date.parseDate(value) ;
+      value = (date) ? date.getTime() : null ;
+    }
+    return value ;
+  }
+    
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/email.js

@@ -0,0 +1,45 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/**
+  Requires a valid email format.
+  
+  @class
+  @extends SC.Validator
+  @version 1.0
+*/
+SC.Validator.Email = SC.Validator.extend(
+/** @scope SC.Validator.Email.prototype */ {
+  
+  validate: function(form, field) { 
+    return (field.get('fieldValue') || '').match(/.+@.+\...+/) ; 
+  },
+  
+  validateError: function(form, field) {
+    var label = field.get('errorLabel') || 'Field' ;
+    return SC.$error("Invalid.Email(%@)".loc(label), label) ;
+  }  
+    
+}) ;
+
+/**
+  This variant allows an empty field as well as an email address.
+  
+  @class
+  @extends SC.Validator.Email
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator.EmailOrEmpty = SC.Validator.Email.extend(
+/** @scope SC.Validator.EmailOrEmpty.prototype */ {
+  validate: function(form, field) {
+    var value = field.get('fieldValue') ; 
+    return (value && value.length > 0) ? value.match(/.+@.+\...+/) : true ;
+  }
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/not_empty.js

@@ -0,0 +1,33 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/**
+  Requires some content in field, but does not check the specific content.
+  
+  @class
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator.NotEmpty = SC.Validator.extend(
+/** @scope SC.Validator.NotEmpty.prototype */ {
+  
+  validate: function(form, field) {
+    var value = field.get('fieldValue'); 
+    var ret = !!value ;
+    if (ret && value.length) ret = value.length > 0 ;
+    return ret ;
+  },
+  
+  validateError: function(form, field) {
+    var label = field.get('errorLabel') || 'Field' ;
+    return SC.$error("Invalid.NotEmpty(%@)".loc(label.capitalize()), field.get('errorLabel'));
+  }
+    
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/number.js

@@ -0,0 +1,82 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/**
+  Handles parsing and validating of numbers.
+  
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 1.0
+  @class
+*/
+SC.Validator.Number = SC.Validator.extend(
+/** @scope SC.Validator.Number.prototype */ {
+
+  /**
+    Number of decimal places to show.  
+    
+    If 0, then numbers will be treated as integers.  Otherwise, numbers will
+    show with a fixed number of decimals.
+  */
+  places: 0,
+  
+  fieldValueForObject: function(object, form, field) {
+    switch(SC.typeOf(object)) {
+      case SC.T_NUMBER:
+        object = object.toFixed(this.get('places')) ;
+        break ;
+      case SC.T_NULL:
+      case SC.T_UNDEFINED:
+        object = '';
+        break ;
+    }
+    return object ;
+  },
+
+  objectForFieldValue: function(value, form, field) {
+    
+    // strip out commas
+    value = value.replace(/,/g,'');
+    
+    switch(SC.typeOf(value)) {
+      case SC.T_STRING:
+        if (value.length == '') {
+          value = null ;
+        } else if (this.get('places') > 0) {
+          value = parseFloat(value) ;
+        } else {
+          value = parseInt(value,0) ;
+        }
+        break ;
+      case SC.T_NULL:
+      case SC.T_UNDEFINED:
+        value = null ;
+        break ;
+    }
+    return value ;
+  },
+  
+  validate: function(form, field) { 
+    var value = field.get('fieldValue') ;
+    return (value == '') || !(isNaN(value) || isNaN(parseFloat(value))) ; 
+  },
+  
+  validateError: function(form, field) {
+    var label = field.get('errorLabel') || 'Field' ;
+    return SC.$error("Invalid.Number(%@)".loc(label), label) ;
+  },
+  
+  /** 
+    Allow only numbers, dashes, period, and commas
+  */
+  validateKeyDown: function(form, field, charStr) {
+    return !!charStr.match(/[0-9\.,\-]/);
+  }
+    
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/password.js

@@ -0,0 +1,86 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('validators/validator') ;
+
+/**
+  Ensures all fields with the Password validator attached in the same form
+  contain the same value.
+  
+  @class
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator.Password = SC.Validator.extend(
+/** @scope SC.Validator.Password.prototype */ {
+
+  attachTo: function(form,field) {
+    sc_super();
+    if (!this.fields) this.fields = [] ;
+    this.fields.push(field) ;
+  },
+
+  validate: function(force) {
+    if (!this.fields || this.fields.length == 0) return true ;
+    
+    var empty = false ;
+    var notEmpty = false ;
+    var ret = true ;
+    var value = this.fields[0].get('fieldValue') ;
+    this.fields.forEach(function(field) {
+      var curValue = field.get('fieldValue') ;
+      if (curValue != value) ret= false ;
+      if (!curValue || curValue.length == 0) empty = true ;
+      if (curValue && curValue.length > 0) notEmpty = true ;
+    }) ;
+
+    // if forces, valid OK if there was an empty.  If not forced, valid OK 
+    // only if all fields match AND they are not all empty.
+    if (force) {
+      return (notEmpty == false) ? false : ret ;
+    } else {
+      return (empty == true) ? true : ret ;
+    }
+  },
+  
+  // update field states
+  updateFields: function(form,valid) {
+    if (!this.fields || this.fields.length == 0) return true ;
+    var err = "Invalid.Password".loc();
+    var topField = this._field ;
+    this.fields.forEach(function(f) {
+      var msg = (valid) ? null : ((f == topField) ? err : '') ;
+      form.setErrorFor(f,msg) ;
+    }) ;
+    return (valid) ? SC.VALIDATE_OK : err ;
+  },
+  
+  validateChange: function(form, field, oldValue) { 
+    return this.updateFields(form, this.validate(false)) ;
+  },
+
+  // this method is called just before the form is submitted.
+  // field: the field toe validate.
+  validateSubmit: function(form, field) { 
+    return this.updateFields(form, this.validate(true)) ;
+  },
+
+  // this method gets called 1ms after the user types a key (if a change is
+  // allowed).  You can use this validate the new partial string and return 
+  // an error if needed.
+  //
+  // The default will validate a partial only if there was already an error.
+  // this allows the user to try to get it right before you bug them.
+  validatePartial: function(form, field) {
+    var isInvalid = !this._field.get('isValid') ;
+    if (isInvalid) {
+      return this.updateFields(form, this.validate(false)) ;
+    } else return SC.VALIDATE_NO_CHANGE ;
+  }
+    
+}) ;

data/frameworks/sproutcore/frameworks/foundation/validators/validator.js

@@ -0,0 +1,311 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+SC.VALIDATE_OK = YES;
+SC.VALIDATE_NO_CHANGE = NO;
+
+/**
+  @class
+  
+  Validators provide a way for you to implement simple form field validation
+  and transformation.  To use a validator, simply name the validator in the
+  "validate" attribute in your text field.  For example, if you want to
+  validate a field using the PhoneNumberValidator use this:
+
+  <input value="1234567890" validate="phone-number" />
+
+  Validators get notified at three points.  You can implement one or all
+  of these methods to support validation.  All of the validate methods except
+  for validateKeypress behave the same way.  You are passed a form, field,
+  and possibly the oldValue.  You are expected to return Validator.OK or
+  an error string.  Inside this method you typically do one of all of the
+  following:
+
+  1. You can simply validate the field value and return OK or an error str
+  
+  2. You can modify the field value (for example, you could format the
+     string to match some predefined format).
+     
+  3. If you need to roundtrip the server first to perform validation, you can
+     return Validator.OK, then save the form and field info until after the
+     roundtrip.  On return, if there is a problem, first verify the field
+     value has not changed and then call form.errorFor(field,str) ;
+
+  @extends SC.Object
+  @since SproutCore 1.0
+*/
+SC.Validator = SC.Object.extend(
+/** @scope SC.Validator.prototype */ {
+
+  // ..........................................
+  // OBJECT VALUE CONVERSION
+  //
+  // The following methods are used to convert the string value of a field
+  // to and from an object value.  The default implementations return
+  // the string, but you can override this to provide specific behaviors. 
+  // For example, you might add or remove a dollar sign or convert the 
+  // value to a number.
+  
+/**
+  Returns the value to set in the field for the passed object value.  
+  
+  The form and view to be set MAY (but will not always) be passed also.  You
+  should override this method to help convert an input object into a value
+  that can be displayed by the field.  For example, you might convert a 
+  date to a property formatted string or a number to a properly formatted
+  value.
+  
+  @param {Object} object The object to transform
+  @param {SC.FormView} form The form this field belongs to. (optional)
+  @param {SC.View} view The view the value is required for.
+  @returns {Object} a value (usually a string) suitable for display
+*/
+  fieldValueForObject: function(object, form, view) { return object; },
+  
+  /**
+    Returns the object value for the passed string.
+    
+    The form and view MAY (but wil not always) be passed also.  You should
+    override this method to convert a field value, such as string, into an
+    object value suitable for consumption by the rest of the app.  For example
+    you may convert a string into a date or a number.
+    
+    @param {String} value the field value.  (Usually a String).
+    @param {SC.FormView} form The form this field belongs to. (optional)
+    @param {SC.View} view The view this value was pulled from.
+    @returns {Object} an object suitable for consumption by the app.
+  */
+  objectForFieldValue: function(value, form, view) { return value; },
+  
+  // ..........................................
+  // VALIDATION PRIMITIVES
+  //
+
+  /**
+    Validate the field value.  
+    
+    You can implement standard behavior for your validator by using the validate() and validateError() methods.  validate() should return NO if the field is not valid, YES otherwise.  If you return NO from this method, then the validateError() method will be called so you can generate an error object describing the specific problem.
+
+    @param {SC.FormView} form the form this view belongs to
+    @param {SC.View} field the field to validate.  Responds to fieldValue.
+    @returns {Boolean} YES if field is valid.
+  */
+  validate: function(form, field) { return true; },
+
+  /**
+    Returns an error object if the field is invalid.
+  
+    This is the other standard validator method that can be used to impement basic validation.  Return an error object explaining why the field is not valid.  It will only be called if validate() returned NO.
+    
+    The default implementation of htis method returns a generic error message with the loc string "Invalid.Generate({fieldValue})".  You can simply define this loc string in strings.js if you prefer or you can override this method to provide a more specific error message.
+  
+    @param {SC.FormView} form the form this view belongs to
+    @param {SC.View} field the field to validate.  Responds to fieldValue.
+    @returns {SC.Error} an error object
+  */
+  validateError: function(form, field) { 
+    return SC.$error(
+      "Invalid.General(%@)".loc(field.get('fieldValue')),
+      field.get('fieldKey')) ; 
+  },
+
+  // ..........................................
+  // VALIDATION API
+  //
+
+  /**
+    Invoked just before the user ends editing of the field.
+
+    This is a primitive validation method.  You can implement the two higher-level methods (validate() and validateError()) if you prefer.
+    
+    The default implementation calls your validate() method and then validateError() if valiate() returns NO.  This method should return SC.VALIDATE_OK if validation succeeded or an error object if it fails.
+  
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+    @param {Object} oldValue: the value of the field before the change
+
+    @returns SC.VALIDATE_OK or an error object.
+  
+  */
+  validateChange: function(form, field, oldValue) { 
+    return this.validate(form,field) ? SC.VALIDATE_OK : this.validateError(form, field);
+  },
+
+  /**
+    Invoked just before the form is submitted.
+  
+    This method gives your validators one last chance to perform validation
+    on the form as a whole.  The default version does the same thing as the 
+    validateChange() method.
+  
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+
+    @returns SC.VALIDATE_OK or an error object.
+  
+  */  
+  validateSubmit: function(form, field) { 
+    return this.validate(form,field) ? SC.VALIDATE_OK : this.validateError(form, field);
+  },
+
+  /**
+    Invoked 1ms after the user types a key (if a change is allowed).  
+  
+    You can use this validate the new partial string and return an error if 
+    needed. The default will validate a partial only if there was already an 
+    error. This allows the user to try to get it right before you bug them.
+  
+    Unlike the other methods, you should return SC.VALIDATE_NO_CHANGE if you
+    did not actually validate the partial string.  If you return 
+    SC.VALIDATE_OK then any showing errors will be hidden.
+  
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+
+    @returns SC.VALIDATE_OK, SC.VALIDATE_NO_CHANGE or an error object.
+  */  
+  validatePartial: function(form, field) { 
+    if (!field.get('isValid')) {
+      return this.validate(form,field) ? SC.VALIDATE_OK : this.validateError(form, field);
+    } else return SC.VALIDATE_NO_CHANGE ;
+  },
+  
+  /**
+    Invoked when the user presses a key.  
+  
+    This method is used to restrict the letters and numbers the user is 
+    allowed to enter.  You should not use this method to perform full 
+    validation on the field.  Instead use validatePartial().
+  
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+    @param {String} char the characters being added
+    
+    @returns {Boolean} YES if allowed, NO otherwise
+  */
+  validateKeyDown: function(form, field,charStr) { return true; },
+
+  // .....................................
+  // OTHER METHODS
+
+  /**
+    Called on all validators when they are attached to a field.  
+  
+    You can use this to do any setup that you need.  The default does nothing.
+    
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+  */
+  attachTo: function(form,field) { },
+
+  /**
+    Called on a validator just before it is removed from a field.  You can 
+    tear down any setup you did for the attachTo() method.
+    
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+  */
+  detachFrom: function(form, field) {}
+
+}) ;
+
+SC.Validator.mixin(/** @scope SC.Validator */ {
+
+  /**
+    Return value when validation was performed and value is OK.
+  */
+  OK: true, 
+  
+  /**
+    Return value when validation was not performed.
+  */
+  NO_CHANGE: false,  
+
+  /**
+    Invoked by a field whenever a validator is attached to the field.
+    
+    The passed validatorKey can be a validator instance, a validator class
+    or a string naming a validator. To make your validator
+    visible, you should name your validator under the SC.Validator base.
+    for example SC.Validator.Number would get used for the 'number' 
+    validator key.
+  
+    This understands validatorKey strings in the following format:
+
+    * 'key' or 'multiple_words' will find validators Key and MultipleWords
+
+    * if you want to share a single validator among multiple fields (for
+      example to validate that two passwords are the same) set a name inside
+      brackets. i.e. 'password[pwd]'.
+
+    @param {SC.FormView} form the form for the field
+    @param {SC.View} field the field to validate
+    @param {Object} validatorKey the key to validate
+    
+    @returns {SC.Validator} validator instance or null
+  */  
+  findFor: function(form,field, validatorKey) {
+    
+    // Convert the validator into a validator instance.
+    var validator ;
+    if (!validatorKey) return ; // nothing to do...
+    
+    if (validatorKey instanceof SC.Validator) {
+      validator = validatorKey ;
+    } else if (validatorKey.isClass) {
+      validator = validatorKey.create() ;
+      
+    } else if (SC.typeOf(validatorKey) === SC.T_STRING) {
+
+      // extract optional key name
+      var name = null ;
+      var m = validatorKey.match(/^(.+)\[(.*)\]/) ;
+      if (m) {
+        validatorKey = m[1] ; name = m[2]; 
+      }
+      
+      // convert the validatorKey name into a class.
+      validatorKey = validatorKey.classify() ;
+      var validatorClass = SC.Validator[validatorKey] ;
+      if (SC.none(validatorClass)) {
+        throw "validator %@ not found for %@".fmt(validatorKey, field) ;
+      } else if (name) {
+
+        // if a key was also passed, then find the validator in the list of
+        // validators for the form.  Otherwise, just create a new instance.
+        if (!form) {
+          throw "named validator (%@) could not be found for field %@ because the field does not belong to a form".fmt(name,field) ;
+        }
+        
+        if (!form._validatorHash) form._validatorHash = {} ;
+        validator = (name) ? form._validatorHash[name] : null ;
+        if (!validator) validator = validatorClass.create() ;
+        if (name) form._validatorHash[name] = validator ;
+      } else validator = validatorClass.create() ;
+    } 
+    
+    return validator ;
+  },
+  
+  /**
+    Convenience class method to call the fieldValueForObject() instance
+    method you define in your subclass.
+  */
+  fieldValueForObject: function(object, form, field) {
+    return this.prototype.fieldValueForObject(object,form,field) ;
+  },
+
+  /**
+    Convenience class method to call the objectForFieldValue() instance
+    method you define in your subclass.
+  */
+  objectForFieldValue: function(value, form, field) {
+    return this.prototype.objectForFieldValue(value,form,field) ;
+  }
+  
+}) ;
+