sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/views/container.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/view') ;
@@ -52,7 +52,12 @@ SC.ContainerView = SC.View.extend(
     var containerView = this.get('rootView') || this ;
     containerView.clear() ;
     var newView = newContent ;
-    if (newView) containerView.appendChild(newView) ;
+    
+    if (newView) {
+      newView.viewFrameWillChange() ;
+      containerView.appendChild(newView) ;
+      newView.viewFrameDidChange() ;
+    }
   },
   
   _contentObserver: function() {

data/frameworks/sproutcore/views/error_explanation.js

@@ -1,14 +1,23 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('views/label');
 
-// The ErrorExplanation view is a special type of label view that can display
-// one or more errors related to a form or field.  This view will set itself
-// to visible only if it has errors.
-SC.ErrorExplanationView = SC.LabelView.extend({
+/**
+  @class
+  
+  The ErrorExplanation view is a special type of label view that can display
+  one or more errors related to a form or field.  This view will set itself
+  to visible only if it has errors.
+  
+  @extends SC.View
+  @extends SC.Control
+  
+*/
+SC.ErrorExplanationView = SC.View.extend(SC.Control,
+/** @scope SC.ErrorExplanationView.prototype */ {
 
   emptyElement: '<ul class="errors"></ul>',
   explanationTemplate: '<li>%@</li>',
@@ -20,7 +29,8 @@ SC.ErrorExplanationView = SC.LabelView.extend({
     }).compact() ;
   },
   
-  contentBindingDefault: SC.Binding.Multiple,
+  valueBindingDefault: SC.Binding.Multiple,
+  
   formatter: function(errors, view) {
     errors = view._errorsFor(errors) ;
     if (!errors || errors.length == 0) return '' ;
@@ -30,16 +40,19 @@ SC.ErrorExplanationView = SC.LabelView.extend({
       return view.explanationTemplate.fmt(er); 
     }).join("") ;
   },
+  
   escapeHTML: false,
   
-  _contentVisibleObserver: function() {
-    var errors = this._errorsFor(this.get('content')) ;
+  _valueObserver: function() {
+    var errors = this._errorsFor(this.get('value')) ;
     var isVisible = errors && errors.length > 0 ;
     if (this.get('isVisible') != isVisible) this.set('isVisible',isVisible);
-  }.observes('content'),
+    this.set('innerHTML', this.formatter(errors, this)) ;
+  }.observes('value'),
   
   init: function() {
     arguments.callee.base.apply(this,arguments) ;
-    this._contentVisibleObserver() ;
+    this._valueObserver() ;
   }
+  
 });

data/frameworks/sproutcore/views/{checkbox_field.js → field/checkbox_field.js}

@@ -1,13 +1,23 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/field') ;
+require('views/field/field') ;
 
-// A text field is an input element with type "text".  This view adds support
-// for hinted values, etc.
-SC.CheckboxFieldView = SC.FieldView.extend({
+/**
+  @class
+  
+  Supports using platform native checkboxs with the input field.  If you 
+  would like to make use of the extended SproutCore checkbox features
+  including a mixed state and theming support, use SC.CheckboxView instead.
+  
+  @extends SC.FieldView
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.CheckboxFieldView = SC.FieldView.extend(
+/** @scope SC.CheckboxFieldView.prototype */ {
   
   emptyElement: '<input type="checkbox" value="1" />',
   
@@ -19,7 +29,7 @@ SC.CheckboxFieldView = SC.FieldView.extend({
     return this.rootElement.checked;
   },
   
-  valueBindingDefault: SC.Binding.Flag,
+  valueBindingDefault: SC.Binding.Bool,
   
   init: function() {
     arguments.callee.base.apply(this,arguments) ;

data/frameworks/sproutcore/views/field/field.js

@@ -0,0 +1,219 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
+require('views/view') ;
+require('mixins/control') ;
+require('mixins/validatable') ;
+
+/**
+  @class
+
+  Generic base class for working with views that depend on the "input" HTML 
+  tag such as text fields.
+  
+  You can work with subclasses of SC.FieldView or extend this class with your
+  own values as well.  Unlike most other HTML elements, web browsers have 
+  built-in support for editing the value of an input field.  This class
+  handles blending the browser input methods with the editing and events 
+  handling provided by the framework.  
+  
+  @extends SC.View
+  @extends SC.Control
+  @extends SC.Validatable
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.FieldView = SC.View.extend(SC.Control, SC.Validatable,
+/** @scope SC.FieldView.prototype */ {
+
+  // PUBLIC PROPERTIES
+  // You generally do not need to override these properties though you might
+  // change them....
+  
+  /**
+    The value of the field.  
+    
+    The form view will pick up whatever value is published here.  Generally 
+    you do not need to observe this property directly.  Instead you should 
+    override setFieldValue(), getFieldValue() and the error property.
+    
+    @field
+  */
+  value: null,
+
+  /**
+    name of key this field should display as part of a form.
+  
+    If you add a field as part of an SC.FormView, then the form view will 
+    automatically bind the field to the property key you name here on the 
+    content object.
+  */
+  fieldKey: null,
+  
+  /**
+    The human readable label you want shown for errors.  May be a loc string.
+  
+    If your field fails validation, then this is the name that will be shown
+    in the error explanation.
+  */  
+  fieldLabel: null,
+  
+  /**
+    The human readable label for this field for use in error strings.  
+    
+    This is either the fieldLabel or a humanized form of the fieldKey.
+    
+    @field
+  */  
+  errorLabel: function() {
+    var ret = this.get('fieldLabel') ;
+    if (ret) return ret ;
+    
+    // if field label is not provided, compute something...
+    var fk = this.get('fieldKey') ;
+    var def = (fk || '').humanize().capitalize() ;  
+    return "FieldKey.%@".fmt(fk).locWithDefault(def) ; // localize if poss.
+  }.property('fieldLabel','fieldKey'),
+  
+  /**
+    The raw value of the field, ignoring validation.  
+  
+    You generally should not override this.  Instead override setFieldValue() 
+    and getFieldValue().
+  
+    @field
+  */  
+  fieldValue: function(key,value) {
+    if (value !== undefined) this._setFieldValue(value) ;
+    return this._getFieldValue() ;
+  }.property('value'),
+
+  // ACTIONS
+  // You generally do not need to override these but they may be used.
+
+  /**
+    Called to perform validation on the field just before the form 
+    is submitted.  If you have a validator attached, this will get the
+    validators.
+  */  
+  validateSubmit: function() {
+    var ret = this.performValidateSubmit() ;
+    // save the value if needed
+    var value = ($ok(ret)) ? this._getFieldValue() : ret ;
+    if (value != this.get('value')) this.set('value', value) ;
+    return ret ;
+  },
+  
+  // OVERRIDE IN YOUR SUBCLASS
+  // Override these primitives in your subclass as required.
+  
+  /**
+    Override to set the actual value of the field.
+    
+    The default implementations set the value on the new value.  The value
+    will have already been converted to a field value using any validator.
+    
+    @param {Object} newValue the value to display.
+  */
+  setFieldValue: function(newValue) {
+    if (this.rootElement.value != newValue) this.rootElement.value = newValue;
+  },
+
+  /**
+    Override to retrieve the actual value of the field.
+    
+    The default implementation gets the value attribute of the rootElement.
+  */
+  getFieldValue: function() {
+    return this.rootElement.value;
+  },
+
+  /**
+    Call by your subclass anytime you want the view to pick up the current 
+    value from the form and post it out. 
+  
+    @param partialChange (optional) YES if this is a partial change.
+    @returns result of validation.
+  */
+  fieldValueDidChange: function(partialChange) {
+
+    // get the field value and set it.
+    // if ret is an error, use that instead of the field value.
+    var ret = this.performValidate(partialChange) ;
+    if (ret == SC.Validator.NO_CHANGE) return ret ;
+
+    // if the validator says everything is OK, then in addition to posting
+    // out the value, go ahead and pass the value back through itself.
+    // This way if you have a formatter applied, it will reformat.
+    //
+    // Do this BEFORE we set the value so that the valueObserver will not
+    // overreact.
+    //
+    if (!partialChange && $ok(ret)) this._setFieldValue(value) ;
+
+    var value = ($ok(ret)) ? this._getFieldValue() : ret ;
+    if (value != this.get('value')) this.set('value',value) ;
+    return ret ;
+  },
+
+  /**
+    Override to enable editing of this field.
+    
+    The default just sets the disabled property on the root element.
+  */
+  enableField: function() {
+    this.rootElement.disabled = NO ;
+  },
+
+  /**
+    Override to disable editing of the field
+    
+    The default just sets the disabled property on the root element.
+  */
+  disableField: function() {
+    this.rootElement.disabled = YES ;
+  },
+
+  /**
+    Overrides enabled observer to also call enableField()/disableField() 
+    methods.
+  */
+  isEnabledObserver: function() {
+    isEnabled = this.get('isEnabled') ;
+    arguments.callee.base.apply(this, arguments);
+    (isEnabled) ? this.enableField() : this.disableField(); 
+  }.observes('isEnabled'),
+
+  // PRIVATE SUPPORT METHODS
+  //
+  init: function() {
+    arguments.callee.base.call(this) ;
+    if (this.rootElement) this._setFieldValue(this.get('value')) ;
+  },
+  
+  
+  // called whenever the value is set on the object.  Will set the value
+  // on the field if the value is changed.
+  _valueObserver: function() {
+    var value = this.get('value') ;
+    var isError = $type(value) == T_ERROR ;
+    if (!isError && (value != this._getFieldValue())) {
+      this._setFieldValue(value) ;
+    } 
+  }.observes('value'),
+  
+  // these methods use the validator to conver the raw field value returned
+  // by your subclass into an object and visa versa.
+  _setFieldValue: function(newValue) {
+    return this.setFieldValue(this.fieldValueForObject(newValue)) ;
+  },
+  
+  _getFieldValue: function() {
+    return this.objectForFieldValue(this.getFieldValue()) ;
+  }
+  
+}) ;
+
+

data/frameworks/sproutcore/views/{radio_field.js → field/radio_field.js}

@@ -1,28 +1,43 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/field') ;
+require('views/field/field') ;
 
-// A RadioFieldView can be used to wrap a series of radio inputs.  The value
-// of this field will be the selected radio.  To use this, you really need to
-// provide some preformatted HTML that already contains the radio buttons with
-// matching name attributes.  If you use the form_view helpers, this will be
-// handled for you.
-SC.RadioFieldView = SC.FieldView.extend({
+/**
+  @class
+  
+  A RadioFieldView can be used to wrap a series of radio inputs.  The value
+  of this field will be the selected radio.  To use this, you really need to
+  provide some preformatted HTML that already contains the radio buttons with
+  matching name attributes.  If you use the form_view helpers, this will be
+  handled for you.
+  
+  @extends SC.FieldView
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.RadioFieldView = SC.FieldView.extend(
+/** @scope SC.RadioFieldView.prototype */ {
   
   emptyElement: '<div></div>',
   
-  // RO - returns the list of values allowed by these radio buttons.
+  /**
+    RO - The list of values allowed by these radio buttons.
+    
+    @field
+  */
   values: function() {
     if (!this._fields) return [] ;
     return Object.keys(this._fields) ;
   }.property(),
   
-  // If you would like your radio buttons to map to actual object values,
-  // then set this to a hash with keys matching values found in the radio
-  // buttons.
+  /**
+    If you would like your radio buttons to map to actual object values,
+    then set this to a hash with keys matching values found in the radio
+    buttons.
+  */  
   objects: null,
   
   // INTERNAL SUPPORT METHODS

data/frameworks/sproutcore/views/{select_field.js → field/select_field.js}

@@ -1,52 +1,83 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
-require('views/field') ;
+require('views/field/field') ;
 
-// SelectFieldView displays browser-native popup menu.  To use this view,
-// you should either bake into the HTML the preset list of options, or 
-// you can set the -objects property to an array of items to show.  The
-// value is current value of the select.
-SC.SelectFieldView = SC.FieldView.extend({
+/**
+  @class
+
+  SelectFieldView displays browser-native popup menu.  To use this view,
+  you should either bake into the HTML the preset list of options, or 
+  you can set the -objects property to an array of items to show.  The
+  value is current value of the select.
+  
+  @extends SC.FieldView
+  @author Charles Jolley
+  @version 1.0
+*/
+SC.SelectFieldView = SC.FieldView.extend(
+/** @scope SC.SelectFieldView.prototype */ {
 
  emptyElement: '<select></select>',
  
- // set this property to an array of items that will form the menu
- // you want to show.
+  /**
+    An array of items that will form the menu you want to show.
+  */ 
  objects: null,
 
- // if you set this to a non-null value, then the name shown for each 
- // menu item will be pulled from the object using the named property.
- // if this is null, the collection objects themselves will be used.
+  /**
+    If you set this to a non-null value, then the name shown for each 
+    menu item will be pulled from the object using the named property.
+    if this is null, the collection objects themselves will be used.
+  */
  nameKey: null,
 
- // if you set this to a non-null value, then the value of this key will
- // be used to sort the objects.  If this is not set, then nameKey will
- // be used.
- sortKey: null,
+  /**
+   If you set this to a non-null value, then the value of this key will
+   be used to sort the objects.  If this is not set, then nameKey will
+   be used.
+  */ 
+  sortKey: null,
 
- // set this to a non-null value to use a key from the passed set of objects
- // as the value for the options popup.  If you don't set this, then the
- // objects themselves will be used as the value.
- valueKey: null,
+  /**
+     Set this to a non-null value to use a key from the passed set of objects
+     as the value for the options popup.  If you don't set this, then the
+     objects themselves will be used as the value.
+  */ 
+  valueKey: null,
 
- // set this to non-null to place an empty option at the top of the menu.   
- emptyName: null,
+  /**
+    set this to non-null to place an empty option at the top of the menu.   
+  */
+  emptyName: null,
 
- // if true, the empty name will be localized.
- localize: false,
+  /**
+    if true, the empty name will be localized.
+  */
+  localize: false,
 
- // override this to change the enabled/disabled state of menu items as they
- // are built.  Return false if you want the menu item to be disabled.
- validateMenuItem: function(itemValue, itemName) {
+  /**
+    override this to change the enabled/disabled state of menu items as they
+    are built.  Return false if you want the menu item to be disabled.
+    
+    @param itemValue the value for the item to validate
+    @param itemName the name of the menu item to validate
+    @returns YES if the item should be enabled, NO otherwise
+  */  
+  validateMenuItem: function(itemValue, itemName) {
    return true ;
- },
+  },
 
- // override this method to implement your own sorting of the menu. By
- // default, menu items are sorted using the value shown.
- sortObjects: function(objects) {
+  /**
+    override this method to implement your own sorting of the menu. By
+    default, menu items are sorted using the value shown or the sortKey
+    
+    @param objects the unsorted array of objects to display.
+    @returns sorted array of objects
+  */
+  sortObjects: function(objects) {
    var nameKey = this.get('sortKey') || this.get('nameKey') ;
    objects = objects.sort(function(a,b) {
      if (nameKey) {
@@ -57,32 +88,30 @@ SC.SelectFieldView = SC.FieldView.extend({
    }) ;
 
    return objects ;
- },
+  },
 
- // call this method to rebuild the menu manually.  Normally you should not
- // need to do this since the menu will be rebuilt as its data changes.
- rebuildMenu: function() {
+  /**
+    call this method to rebuild the menu manually.  Normally you should not
+    need to do this since the menu will be rebuilt as its data changes.
+  */
+  rebuildMenu: function() {
    this._rebuildMenu() ;
- },
- 
- 
- mouseDown: function(e)
- {
-   e._stopWhenHandled = false;
-   return false;
- },
- 
- 
- // .......................................
- // PRIVATE
- //
+  },
+
+  // .......................................
+  // PRIVATE
+  //
+
+  /** @private */
+  mouseDown: function(e) { e._stopWhenHandled = false; return false; },
 
- // when fetching the raw value, convert back to an object if needed...
- getFieldValue: function() {
+  // when fetching the raw value, convert back to an object if needed...
+  /** @private */
+  getFieldValue: function() {
    var value = this.rootElement.value ; // get raw value...
    var valueKey = this.get('valueKey') ;
    var objects = this.get('objects') ;
-   
+ 
    // Handle empty selection.
    if (value == '***') {
      value = null ;
@@ -95,33 +124,34 @@ SC.SelectFieldView = SC.FieldView.extend({
      var found = null ; // matching object goes here.
      while(!found && (--loc >= 0)) {
        var object = objects[loc] ;
-       
+     
        // get value using valueKey if there is one or use object
        // map to _guid or toString.
        if (valueKey) object = (object.get) ? object.get(valueKey) : object[valueKey] ;
        ov = (object) ? ((object._guid) ? object._guid : object.toString()) : null ;
-       
+     
        // use this object value if it matches.
        if (value == ov) found = object ;
      }
    }
-   
+ 
    return value ;
- },
+  },
 
- // when setting the raw value, convert from object...
- setFieldValue: function(nv) {
+  // when setting the raw value, convert from object...
+  /** @private */
+  setFieldValue: function(nv) {
    if (nv) {
      nv = (nv._guid) ? nv._guid : nv.toString() ;
    } else {
      nv = "***" ;
    }
    if (this.rootElement.value != nv) this.rootElement.value = nv ;
- },
- 
- // this method is called anytime the objects property or any of its member
- // objects change.
- _rebuildMenu: function() {     
+  },
+
+  // this method is called anytime the objects property or any of its member
+  // objects change.
+  _rebuildMenu: function() {     
    // get list of objects.
    var nameKey = this.get('nameKey') ;
    var valueKey = this.get('valueKey') ;
@@ -136,18 +166,18 @@ SC.SelectFieldView = SC.FieldView.extend({
      objects = Array.from(objects) ; // make array.
      objects = this.sortObjects(objects) ; // sort'em.
      var html = [] ;       
- 
+
      var emptyName = this.get('emptyName') ;
      if (emptyName) {
        if (this.get('localize')) emptyName = emptyName.loc() ;
        html.push('<option value="***">%@</option>'.fmt(emptyName)) ;
        html.push('<option disabled="disabled"></option>') ;
      }
- 
+
      // generate option elements.
      objects.each(function(object) {
        if (object) {
-         
+       
          // either get the name from the object or convert object to string.
          var name = (nameKey) ? ((object.get) ? object.get(nameKey) : object[nameKey]) : object.toString() ;
 
@@ -155,28 +185,28 @@ SC.SelectFieldView = SC.FieldView.extend({
          // then convert to a string or use _guid if one of available.
          var value = (valueKey) ? ((object.get) ? object.get(valueKey) : object[valueKey]) : object ;
          if (value) value = (value._guid) ? value._guid : value.toString() ;
-         
+       
          // render HTML
          var disable = (this.validateMenuItem && this.validateMenuItem(value, name)) ? '' : 'disabled="disabled" ' ;
          html.push('<option %@value="%@">%@</option>'.fmt(disable,value,name)) ;
-     
+   
        // null value means separator.
        } else {
          html.push('<option disabled="disabled"></option>') ;
        }
      }.bind(this) );
- 
+
      // replace the contents of this HTML element.
      this.update(html.join(""));
      this.rootElement.value = fieldValue ;
- 
+
    } else {
      this.set('value',null);
    }
- },
+  },
 
- // object changes to the objects array of objects if possible.
- _objectsObserver: function() {
+  // object changes to the objects array of objects if possible.
+  _objectsObserver: function() {
    if (!this._boundObserver) {
      this._boundObserver = this._objectsItemObserver.bind(this) ;
    }
@@ -185,7 +215,7 @@ SC.SelectFieldView = SC.FieldView.extend({
      var loc ;
      var objects = Array.from(this.get('objects')) ;
      var func = this._boundObserver ;
-     
+   
      // stop observing old objects.
      if (this._objects) {
        loc = this._objects.length ;
@@ -206,7 +236,7 @@ SC.SelectFieldView = SC.FieldView.extend({
      this._objects = objects ;
      this._nameKey = this.get('nameKey') ;
      this._valueKey = this.get('valueKey') ;
-     
+   
      if (this._objects) {
        loc = this._objects.length ;
        while(--loc >= 0) {
@@ -221,41 +251,37 @@ SC.SelectFieldView = SC.FieldView.extend({
          } // if (object &&...)
        } // while(--loc)
      } // if (this._objects)
-  
+
     this._rebuildMenu() ;
    } // if (this.didChangeFor...)
- }.observes('objects','nameKey','valueKey'),
+  }.observes('objects','nameKey','valueKey'),
 
- // this is invoked anytime an item we are interested in in the menu changes
- // rebuild the menu when this happens, but only one time.
- _objectsItemObserver: function(item, key, value) {
+  // this is invoked anytime an item we are interested in in the menu changes
+  // rebuild the menu when this happens, but only one time.
+  _objectsItemObserver: function(item, key, value) {
     if (item.didChangeFor(this._guid, key)) {
       console.log('rebuildMenu') ;
       this._rebuildMenu() ;
     }
- },
-
-
+  },
 
-  _fieldDidFocus: function()
-  {
+  _fieldDidFocus: function() {
     var isFocused = this.get('isFocused');
     if (!isFocused) this.set('isFocused', true);
   },
-  _fieldDidBlur: function()
-  {
+
+  _fieldDidBlur: function() {
     var isFocused = this.get('isFocused');
     if (isFocused) this.set('isFocused', false);
   },
-  _isFocusedObserver: function()
-  {
+
+  _isFocusedObserver: function() {
     var isFocused = this.get('isFocused');
     this.setClassName('focus', isFocused);
   }.observes('isFocused'),
 
 
-  init: function()
-  {
+  init: function() {
     arguments.callee.base.call(this);
     this._rebuildMenu();