sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

data/lib/frameworks/sproutcore/frameworks/datastore/models/record_attribute.js

@@ -56,11 +56,12 @@ SC.RecordAttribute = SC.Object.extend(
   isRecordAttribute: YES,
 
   /**
-    The default value.  If attribute is null or undefined, this default value
-    will be substituted instead.  Note that defaultValues are not converted
-    so the value should be in the output type expected by the attribute.
+    The default value.  If attribute is `null` or `undefined`, this default
+    value will be substituted instead.  Note that `defaultValue`s are not
+    converted, so the value should be in the output type expected by the
+    attribute.
     
-    If you use a defaultValue function, the arguments given to it is the
+    If you use a `defaultValue` function, the arguments given to it are the
     record instance and the key.
     
     @type Object|function
@@ -73,7 +74,7 @@ SC.RecordAttribute = SC.Object.extend(
     naming a class.  The built in handler allows all native types to pass 
     through, converts records to ids and dates to UTF strings.
     
-    If you use the attr() helper method to create a RecordAttribute instance,
+    If you use the `attr()` helper method to create a RecordAttribute instance,
     it will set this property to the first parameter you pass.
     
     @type Object|String
@@ -93,7 +94,7 @@ SC.RecordAttribute = SC.Object.extend(
   key: null,
   
   /**
-    If YES, then the attribute is required and will fail validation unless
+    If `YES`, then the attribute is required and will fail validation unless
     the property is set to a non-null or undefined value.
     
     @type Boolean
@@ -102,7 +103,7 @@ SC.RecordAttribute = SC.Object.extend(
   isRequired: NO,
   
   /**
-    If NO then attempts to edit the attribute will be ignored.
+    If `NO` then attempts to edit the attribute will be ignored.
     
     @type Boolean
     @default YES
@@ -183,7 +184,7 @@ SC.RecordAttribute = SC.Object.extend(
   /** 
     Converts the passed value into the core attribute value.  This will apply 
     any format transforms.  You can install standard transforms by adding to
-    the SC.RecordAttribute.transforms hash.  See 
+    the `SC.RecordAttribute.transforms` hash.  See 
     SC.RecordAttribute.registerTransform() for more.
     
     @param {SC.Record} record The record instance
@@ -220,8 +221,8 @@ SC.RecordAttribute = SC.Object.extend(
     
     Shared observer used by any attribute whose transform creates a seperate
     object that needs to write back to the datahash when it changes. For
-    example, when enumerable content changes on a SC.Set attribute, it
-    writes back automatically instead of forcing you to call .set manually.
+    example, when enumerable content changes on a `SC.Set` attribute, it
+    writes back automatically instead of forcing you to call `.set` manually.
     
     This functionality can be used by setting an array named
     observesChildren on your transform containing the names of keys to
@@ -244,8 +245,8 @@ SC.RecordAttribute = SC.Object.extend(
   /** 
     Converts the passed value from the core attribute value.  This will apply 
     any format transforms.  You can install standard transforms by adding to
-    the SC.RecordAttribute.transforms hash.  See 
-    SC.RecordAttribute.registerTransform() for more.
+    the `SC.RecordAttribute.transforms` hash.  See 
+    `SC.RecordAttribute.registerTransform()` for more.
 
     @param {SC.Record} record The record instance
     @param {String} key The key used to access this attribute on the record
@@ -263,8 +264,8 @@ SC.RecordAttribute = SC.Object.extend(
   },
 
   /**
-    The core handler. Called when get() is called on the
-    parent record, since SC.RecordAttribute uses isProperty to masquerade
+    The core handler. Called when `get()` is called on the
+    parent record, since `SC.RecordAttribute` uses `isProperty` to masquerade
     as a computed property. Get expects a property be a function, thus we
     need to implement call.
     
@@ -301,13 +302,13 @@ SC.RecordAttribute = SC.Object.extend(
   // INTERNAL SUPPORT
   // 
   
-  /** @private - Make this look like a property so that get() will call it. */
+  /** @private - Make this look like a property so that `get()` will call it. */
   isProperty: YES,
   
   /** @private - Make this look cacheable */
   isCacheable: YES,
   
-  /** @private - needed for KVO property() support */
+  /** @private - needed for KVO `property()` support */
   dependentKeys: [],
   
   /** @private */
@@ -327,9 +328,9 @@ SC.RecordAttribute.mixin(
   /** @scope SC.RecordAttribute.prototype */{
   /**
     The default method used to create a record attribute instance.  Unlike 
-    create(), takes an attributeType as the first parameter which will be set 
-    on the attribute itself.  You can pass a string naming a class or a class
-    itself.
+    `create()`, takes an `attributeType` as the first parameter which will be
+    set on the attribute itself.  You can pass a string naming a class or a
+    class itself.
 
     @static
     @param {Object|String} attributeType the assumed attribute type
@@ -352,11 +353,15 @@ SC.RecordAttribute.mixin(
     object you pass can be of any type as long as it responds to the following
     methods
     
-    - *to(value, attr, klass, record, key)* converts the passed value (which will be of the class expected by the attribute) into the underlying attribute value
-    - *from(value, attr, klass, record, key)* converts the underyling attribute value into a value of the class
-    
+     - `to(value, attr, klass, record, key)` converts the passed value
+       (which will be of the class expected by the attribute) into the
+       underlying attribute value
+     - `from(value, attr, klass, record, key)` converts the underyling
+       attribute value into a value of the class
     
-    You can also provide an array of keys to observer on the return value. When any of these change, your from method will be called to write the changed object back to the record. For example:
+    You can also provide an array of keys to observer on the return value.
+    When any of these change, your from method will be called to write the
+    changed object back to the record. For example:
 
         {
           to: function(value, attr, type, record, key) {
@@ -548,14 +553,16 @@ SC.RecordAttribute.registerTransform(Date, {
 
 if (SC.DateTime && !SC.RecordAttribute.transforms[SC.guidFor(SC.DateTime)]) {
   /**
-    Registers a transform to allow SC.DateTime to be used as a record attribute,
-    ie SC.Record.attr(SC.DateTime);
+    Registers a transform to allow `SC.DateTime` to be used as a record
+    attribute, ie `SC.Record.attr(SC.DateTime);`
   
-    Because SC.RecordAttribute is in the datastore framework and SC.DateTime in
-    the foundation framework, and we don't know which framework is being loaded
-    first, this chunck of code is duplicated in both frameworks.
+    Because `SC.RecordAttribute` is in the datastore framework and
+    `SC.DateTime` in the foundation framework, and we don't know which
+    framework is being loaded first, this chunck of code is duplicated in
+    both frameworks.
   
-    IF YOU EDIT THIS CODE MAKE SURE YOU COPY YOUR CHANGES to record_attribute.js. 
+    IF YOU EDIT THIS CODE MAKE SURE YOU COPY YOUR CHANGES to
+    `record_attribute.js.`
   */
 
   SC.RecordAttribute.registerTransform(SC.DateTime, {

data/lib/frameworks/sproutcore/frameworks/datastore/models/single_attribute.js

@@ -10,10 +10,10 @@ sc_require('models/record_attribute');
 
 /** @class
   
-  SingleAttribute is a subclass of RecordAttribute and handles to-one
+  `SingleAttribute` is a subclass of `RecordAttribute` and handles to-one
   relationships.
 
-  There are many ways you can configure a SingleAttribute:
+  There are many ways you can configure a `SingleAttribute`:
   
       group: SC.Record.toOne('MyApp.Group', { 
         inverse: 'contacts', // set the key used to represent the inverse 

data/lib/frameworks/sproutcore/frameworks/datastore/system/child_array.js

@@ -8,8 +8,8 @@
 /**
   @class
 
-  A ChildArray is used to map an array of ChildRecord objects.
-  
+  A `ChildArray` is used to map an array of `ChildRecord` objects.
+
   @extends SC.Enumerable
   @extends SC.Array
   @since SproutCore 1.0
@@ -17,106 +17,106 @@
 
 SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
   /** @scope SC.ChildArray.prototype */ {
-    
+
   /**
-    If set, it is the default record recordType
-  
+    If set, it is the default record `recordType`
+
     @default null
     @type String
   */
   defaultRecordType: null,
-  
+
   /**
-    If set, the parent record will be notified whenever the array changes so that 
+    If set, the parent record will be notified whenever the array changes so that
     it can change its own state
-    
+
     @default null
     @type {SC.Record}
   */
   record: null,
-  
+
   /**
     If set will be used by the many array to get an editable version of the
-    storeIds from the owner.
-    
+    `storeId`s from the owner.
+
     @default null
     @type String
   */
   propertyName: null,
-  
+
   /**
     Actual references to the hashes
-  
+
     @default null
     @type {SC.Array}
   */
   children: null,
-  
+
   /**
-    The store that owns this record array.  All record arrays must have a 
+    The store that owns this record array.  All record arrays must have a
     store to function properly.
 
     @type SC.Store
-    @property 
+    @property
   */
   store: function() {
     return this.getPath('record.store');
   }.property('record').cacheable(),
-  
+
   /**
-    The storeKey for the parent record of this many array.  Editing this 
-    array will place the parent record into a READY_DIRTY state.
+    The storeKey for the parent record of this many array.  Editing this
+    array will place the parent record into a `READY_DIRTY state.
 
     @type Number
-    @property 
+    @property
   */
   storeKey: function() {
     return this.getPath('record.storeKey');
   }.property('record').cacheable(),
-  
+
   /**
-    Returns the storeIds in read only mode.  Avoids modifying the record 
+    Returns the storeIds in read only mode.  Avoids modifying the record
     unnecessarily.
-    
+
     @type SC.Array
-    @property 
+    @property
   */
   readOnlyChildren: function() {
     return this.get('record').readAttribute(this.get('propertyName'));
   }.property(),
-  
+
   /**
-    Returns an editable array of child hashes.  Marks the owner records as 
-    modified. 
-    
+    Returns an editable array of child hashes.  Marks the owner records as
+    modified.
+
     @type {SC.Array}
-    @property 
+    @property
   */
   editableChildren: function() {
     var store    = this.get('store'),
         storeKey = this.get('storeKey'),
         pname    = this.get('propertyName'),
         ret, hash;
-        
-    ret = store.readEditableProperty(storeKey, pname);    
+
+    ret = store.readEditableProperty(storeKey, pname);
     if (!ret) {
       hash = store.readEditableDataHash(storeKey);
-      ret = hash[pname] = [];      
+      ret = hash[pname] = [];
     }
-    
+
     if (ret !== this._prevChildren) this.recordPropertyDidChange();
     return ret ;
   }.property(),
-    
+
   // ..........................................................
   // ARRAY PRIMITIVES
-  // 
+  //
 
   /** @private
     Returned length is a pass-through to the storeIds array.
-    
+
     @type Number
-    @property 
+    @property
   */
   length: function() {
     var children = this.get('readOnlyChildren');
@@ -126,61 +126,61 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
   /**
     Looks up the store id in the store ids array and materializes a
     records.
-    
+
     @param {Number} idx index of the object to retrieve.
     @returns {SC.Record} The record if found or undefined.
   */
   objectAt: function(idx) {
-    var recs      = this._records, 
+    var recs      = this._records,
         children = this.get('readOnlyChildren'),
         hash, ret, pname = this.get('propertyName'),
         parent = this.get('record');
     var len = children ? children.length : 0;
-    
+
     if (!children) return undefined; // nothing to do
     if (recs && (ret=recs[idx])) return ret ; // cached
     if (!recs) this._records = recs = [] ; // create cache
-    
+
     // If not a good index return undefined
     if (idx >= len) return undefined;
     hash = children.objectAt(idx);
     if (!hash) return undefined;
-    
+
     // not in cache, materialize
     recs[idx] = ret = parent.registerNestedRecord(hash, pname, pname+'.'+idx);
-    
+
     return ret;
   },
 
-  /** 
+  /**
     Pass through to the underlying array.  The passed in objects must be
-    records, which can be converted to storeIds.
-    
+    records, which can be converted to `storeId`s.
+
     @param {Number} idx index of the object to replace.
     @param {Number} amt number of records to replace starting at idx.
     @param {Number} recs array with records to replace.
     @returns {SC.Record} The record if found or undefined.
-    
+
   */
   replace: function(idx, amt, recs) {
-    var children = this.get('editableChildren'), 
+    var children = this.get('editableChildren'),
         len      = recs ? (recs.get ? recs.get('length') : recs.length) : 0,
         record   = this.get('record'), newRecs,
-        
+
         pname    = this.get('propertyName'),
         cr, recordType;
     newRecs = this._processRecordsToHashes(recs);
     children.replace(idx, amt, newRecs);
     // notify that the record did change...
     record.recordDidChange(pname);
-  
+
     return this;
   },
-  
+
   /** @private
-  
+
     Converts a records array into an array of hashes.
-    
+
     @param {SC.Array} recs records to be converted to hashes.
     @returns {SC.Array} array of hashes.
   */
@@ -194,10 +194,10 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
         recs[idx] = store.readDataHash(sk);
       }
     });
-    
+
     return recs;
   },
-  
+
   /**
     Calls normalize on each object in the array
   */
@@ -206,31 +206,50 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
       if(child.normalize) child.normalize();
     });
   },
-  
+
   // ..........................................................
   // INTERNAL SUPPORT
-  //  
-  
-  /** 
+  //
+
+  /**
     Invoked whenever the children array changes.  Observes changes.
-    
-    @param {SC.Array} keys optional 
+
+    @param {SC.Array} keys optional
     @returns {SC.ChildArray} itself.
   */
   recordPropertyDidChange: function(keys) {
     if (keys && !keys.contains(this.get('propertyName'))) return this;
-    
-    var children = this.get('readOnlyChildren');
+
+    var children = this.get('readOnlyChildren'), oldLen = 0, newLen = 0;
     var prev = this._prevChildren, f = this._childrenContentDidChange;
-    
+
     if (children === prev) return this; // nothing to do
-        
-    if (prev) prev.removeObserver('[]', this, f);
+
+    if (prev) {
+      prev.removeArrayObservers({
+        target: this,
+        willChange: this.arrayContentWillChange,
+        didChange: f
+      });
+
+      oldLen = prev.get('length');
+    }
+
+    if (children) {
+      children.addArrayObservers({
+        target: this,
+        willChange: this.arrayContentWillChange,
+        didChange: f
+      });
+
+      newLen = children.get('length');
+    }
+
+
+    this.arrayContentWillChange(0, oldLen, newLen);
     this._prevChildren = children;
-    if (children) children.addObserver('[]', this, f);
-    
-    var rev = (children) ? children.propertyRevision : -1 ;
-    this._childrenContentDidChange(children, '[]', children, rev);
+    this._childrenContentDidChange(0, oldLen, newLen);
+
     return this;
   },
 
@@ -238,21 +257,21 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     Invoked whenever the content of the children array changes.  This will
     dump any cached record lookup and then notify that the enumerable content
     has changed.
-    
-    @param {Number} target 
-    @param {Number} key 
+
+    @param {Number} target
+    @param {Number} key
     @param {Number} value
     @param {Number} rev
   */
-  _childrenContentDidChange: function(target, key, value, rev) {
+  _childrenContentDidChange: function(start, removedCount, addedCount) {
     this._records = null ; // clear cache
-    this.enumerableContentDidChange();
+    this.arrayContentDidChange(start, removedCount, addedCount);
   },
-  
+
   /** @private */
   init: function() {
     sc_super();
     this.recordPropertyDidChange();
   }
-  
-}) ;
+
+}) ;