sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/validators/credit_card.js

@@ -1,24 +1,45 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('validators/validator') ;
 
-// Force to be a valid credit card number.
-SC.Validator.CreditCard = SC.Validator.extend({
+/**
+  Validate a field value as a credit card number. 
   
-  // expects a string of 16 digits. split into groups of 4
+  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)
+
+  @class
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 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 ;
   },
-  
-  // remove all whitespace to make a single number.
+
+  /**
+    Removes all whitespace or dashes to make a single string.
+  */
   objectForFieldValue: function(value, form, field) {
-    return value.replace(/^\s+|\s+$/g,'') ;
+    return value.replace(/[\s-\.\:]/g,'') ;
   },
   
   validate: function(form, field) { 
@@ -30,11 +51,10 @@ SC.Validator.CreditCard = SC.Validator.extend({
     return $error("Invalid.CreditCard(%@)".loc(label), label);
   },
   
-  // Borrowed from: David Leppek :: https://www.azcode.com/Mod10
   checkNumber: function(ccNumb) {
-    var valid = "0123456789"  // Valid digits in a credit card number
+    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);  // integer of ccNumb
+    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
@@ -59,12 +79,12 @@ SC.Validator.CreditCard = SC.Validator.extend({
     } 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) % 10;  // right most digit
-          calc = parseInt(calc);  // assure it is an integer
+          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) % 10 ;    // NEXT right most digit
+          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.

data/frameworks/sproutcore/validators/date.js

@@ -1,17 +1,35 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('validators/validator') ;
 
-// Handle the parsing and display of dates.
-SC.Validator.Date = SC.Validator.extend({
+/**
+  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 true, dates will be converted to a natural language format if
+    possible such as "Tomorrow" or "Today".
+  */
   naturalLanguage: true,
   
-  // if we have a number, then convert to a date object.
+  /**
+    if we have a number, then convert to a date object.
+  */
   fieldValueForObject: function(object, form, field) {
     var date ;
     if (typeof(object) == "number") {
@@ -23,8 +41,10 @@ SC.Validator.Date = SC.Validator.extend({
     return object ;
   },
 
-  // try to pase value as a date. convert into a number, or return null if
-  // it could not be parsed.
+  /**
+    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) ;

data/frameworks/sproutcore/validators/email.js

@@ -7,7 +7,17 @@
 // ==========================================================================
 
 require('validators/validator') ;
-SC.Validator.Email = SC.Validator.extend({
+
+/**
+  Requires a valid email format.
+  
+  @class
+  @extends SC.Validator
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator.Email = SC.Validator.extend(
+/** @scope SC.Validator.Email.prototype */ {
   
   validate: function(form, field) { 
     return (field.get('fieldValue') || '').match(/.+@.+\...+/) ; 
@@ -20,8 +30,16 @@ SC.Validator.Email = SC.Validator.extend({
     
 }) ;
 
-// this variant allows an email to be empty.
-SC.Validator.EmailOrEmpty = SC.Validator.Email.extend({
+/**
+  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/validators/not_empty.js

@@ -7,7 +7,17 @@
 // ==========================================================================
 
 require('validators/validator') ;
-SC.Validator.NotEmpty = SC.Validator.extend({
+
+/**
+  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'); 

data/frameworks/sproutcore/validators/number.js

@@ -1,14 +1,28 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('validators/validator') ;
 
-// Handle the parsing and display of numbers.
-SC.Validator.Number = SC.Validator.extend({
+/**
+  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 */ {
 
-  places: 0, // 0 to force int. otherwise fixed.
+  /**
+    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($type(object)) {

data/frameworks/sproutcore/validators/password.js

@@ -9,7 +9,18 @@
 // ==========================================================================
 
 require('validators/validator') ;
-SC.Validator.Password = SC.Validator.extend({
+
+/**
+  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) {
     argments.callee.base.call(this,form,field) ;

data/frameworks/sproutcore/validators/validator.js

@@ -3,30 +3,41 @@
 // Author: Charles Jolley
 // ==========================================================================
 
-//
-// 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) ;
-//
-SC.Validator = SC.Object.extend({
+require('foundation/object');
+
+/**
+  @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
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.Validator = SC.Object.extend(
+/** @scope SC.Validator.prototype */ {
 
   // ..........................................
   // OBJECT VALUE CONVERSION
@@ -37,44 +48,66 @@ SC.Validator = SC.Object.extend({
   // For example, you might add or remove a dollar sign or convert the 
   // value to a number.
   
-  // This method should return the value to set in the field for the passed
-  // object value.  The form and field to be set MAY (but will not always)
-  // be passed also.
-  fieldValueForObject: function(object, form, field) { return object; },
+/**
+  Returns the value to set in the field for the passed object value.  
   
-  // This method should return the object value for the string passed. The
-  // form and field the value came from MAY (but will not always) be passed
-  // also.
-  objectForFieldValue: function(value, form, field) { return 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
   //
-  // You can implement standard behavior for your validator by using the
-  // vaidate and validateError methods.  validate() should return false
-  // if the field is not valid.
-  //
-  // Expects:
-  // form: the form
-  // field: the field to validate
-  //
-  // Returns:
-  // true if the field is valid, otherwise not.
-  //
+
+  /**
+    Validate the field value.  
+    
+    You can implement standard behavior for your validator by using the
+    vaidate and validateError methods.  validate() should return false
+    if the field is not valid.
+
+    @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; },
 
-  // This is the other standard validator method that can be used to impement
-  // basic validation.  This should return an error object explaining why
-  // the field is not valid.  It will only be called if validate() returned
-  // false.
-  //
-  // Expects:
-  // form: the form
-  // field: the field that is no valid.
-  //
-  // Returns:
-  // Error string.
-  //
+  /**
+    Returns an error object if the field is invalid.
+  
+    This is the other standard validator method that can be used to impement
+    basic validation.  This should return an error object explaining why
+    the field is not valid.  It will only be called if validate() returned
+    false.
+  
+    @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 $error(
       "Invalid.General(%@)".loc(field.get('fieldValue')),
@@ -85,169 +118,137 @@ SC.Validator = SC.Object.extend({
   // VALIDATION API
   //
 
-  // this method gets invoked just before the user ends editing of the field.
-  //
-  // Expects;
-  // field: the field that was changed.
-  // oldValue: the value of the field before the user changed it.
-  //
-  // Return:
-  // SC.Validator.OK if the item was valid, an error object if the item is 
-  // not valid.
-  //
+  /**
+    Invoked just before the user ends editing of the field.
+  
+    The default implementation calls your validate() method and then
+    validateError() if valiate() returns NO.  This method should return 
+    SC.Validator.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.Validator.OK or an error object.
+  
+  */
   validateChange: function(form, field, oldValue) { 
     return (this.validate(form,field)) ? SC.Validator.OK : this.validateError(form, field);
   },
 
-  // this method is called for the field just before the form is submitted.
-  //
-  // Expects:
-  // form: the form the field belongs to
-  // field: the field to validate.
-  //
-  // Returns:
-  // An error string of SC.Validator.OK if the field is valid.  If you return
-  // an error string, form submission will be cancelled.
-  //
+  /**
+    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.Validator.OK or an error object.
+  
+  */  
   validateSubmit: function(form, field) { 
     return (this.validate(form,field)) ? SC.Validator.OK : this.validateError(form, field);
   },
 
-  // 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.
-  //
-  // Expects:
-  // form: the form the field belongs to
-  // field: the field to validate.
-  //
-  // Returns:
-  // An error string if there was a problem, SC.Validator.OK if you checked
-  // the field and it was valid or SC.Validator.NO_CHANGE if you did not
-  // check the field.  (Passing back OK will hide any showing errors.)
-  //
+  /**
+    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.Validator.NO_CHANGE if you
+    did not actually validate the partial string.  If you return 
+    SC.Validator.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.Validator.OK, SC.Validator.NO_CHANGE or an error object.
+  */  
   validatePartial: function(form, field) { 
     if (!field.get('isValid')) {
       return (this.validate(form,field)) ? SC.Validator.OK : this.validateError(form, field);
     } else return SC.Validator.NO_CHANGE ;
   },
   
-  // this method gets called when the user types a key.  It's useful to 
-  // restrict the letters and numbers the user is allowed to enter.  Return
-  // true/false to allow the keypress or not.
-  //
-  // Expects:
-  // form: the form the field belongs to
-  // field: the field in focus.
-  // char: a string with the characters being added.
-  //
-  // Returns:
-  // true to allow the keypress, false otherwise.
-  //
+  /**
+    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
+  */
   validateKeypress: function(form, field,charStr) { return true; },
 
   // .....................................
   // OTHER METHODS
 
-  // this method will be called on all validators when they are attached to
-  // a field.  You can use this to do any setup that you need.
-  attachTo: function(form,field) {
-    // this._form = form ;
-    // this._field = field ;
-    // var that = this ;
-    // ['focus','change','blur','keypress'].each(function(key) {
-    //   var f = that['_'+key].bindAsEventListener(that) ;
-    //   Event.observe(field,key,f) ;
-    // }) ;
-    // 
-    // if (!this._boundPartial) this._boundPartial = this._partial.bind(this) ;
-    // if (field.addObserver) field.addObserver('fieldValue',this._boundPartial);
-    // return this ;
-  },
+  /**
+    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) { },
 
-  // this method is called on a validator just before it is removed from a 
-  // field.  You can tear down any setup you did for the attachTo() method.
-  detachFrom: 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, 
   
-  // detach: function() {
-  //     var that = this ;
-  //     ['focus','change','blur', 'keypress'].each(function(key) {
-  //       var f = that['_'+key].bindAsEventListener(that) ;
-  //       Event.stopObserving(that._field,key,f) ;
-  //     }) ;
-  //     if (this._field.removeObserver) {
-  //       this._field.removeObserver('fieldValue',this._boundPartial) ;
-  //     }
-  //     return this ;
-  //   },
-  //   
-  //   // save the old value before the user makes changes
-  //   _focus: function(ev) { 
-  //     this._oldValue = this._field.get('fieldValue'); 
-  //   },
-  //   
-  //   _blur: function(ev) {
-  //     if (this._oldValue != this._field.get('fieldValue')) this._change(ev) ;
-  //     this._oldValue = null ;  
-  //   },
-  //   
-  //   // invoked whenever the field value changes.
-  //   _change: function(ev)  {
-  //     var err = this.validateChange(this._form,this._field,this._oldValue) ;
-  //     this._oldValue = null ;
-  //     if (err == SC.Validator.NO_CHANGE) return ; // nothing to do.
-  //     if (err == SC.Validator.OK) err = null ;
-  //     this._form.setErrorFor(this._field,err) ; // also clears error.
-  //   },
-  //   
-  //   _keypress: function(ev) {
-  //     var str = Event.getCharString(ev) ;
-  //     var allow = this.validateKeypress(this._form,this._field,str) ;
-  //     return allow ;
-  //   },
-  //   
-  //   _partial: function() {
-  //     var err = this.validatePartial(this._form,this._field) ;
-  //     if (err == SC.Validator.NO_CHANGE) return ; // nothing to do
-  //     if (err == SC.Validator.OK) err = null ;
-  //     if (this._field.set) this._field.set('isValid', err == null)
-  //     this._form.setErrorFor(this._field,err) ;
-  //   },
-  //   
-  //   // invoked by form.
-  //   _validate: function() {
-  //     var err = this.validateSubmit(this._form,this._field) ;
-  //     if (err == SC.Validator.NO_CHANGE) return true ; // nothing to do.
-  //     if (err == SC.Validator.OK) err = null ;
-  //     this._form.setErrorFor(this._field,err) ;
-  //     return (err == null) ; // true = ok to submit.
-  //   }
+  /**
+    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:
 
-SC.Validator.mixin({
+    * 'key' or 'multiple_words' will find validators Key and MultipleWords
 
-  // CONSTANTS
-  OK: true, NO_CHANGE: false,  
+    * 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]'.
 
-  // this is 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.Validaotr} validator instance or null
+  */  
   findFor: function(form,field, validatorKey) {
     
     // Convert the validator into a validator instance.
@@ -293,12 +294,21 @@ SC.Validator.mixin({
     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) ;
   }
   
-})
+}) ;
+