sproutcore 1.5.0.pre.5 → 1.5.0.rc.1

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

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -15,12 +15,10 @@ sc_require('models/record');
   
   When defining an attribute on an SC.Record, you can configure it this way: 
   
-  {{{
-    title: SC.Record.attr(String, { 
-      defaultValue: 'Untitled',
-      isRequired: YES|NO
-    })
-  }}}
+      title: SC.Record.attr(String, { 
+        defaultValue: 'Untitled',
+        isRequired: YES|NO
+      })
   
   In addition to having predefined transform types, there is also a way to 
   set a computed relationship on an attribute. A typical example of this would
@@ -29,11 +27,9 @@ sc_require('models/record');
   other attributes). To set up such a computed property, you can attach a 
   function in the attribute definition of the SC.Record subclass:
   
-  {{{
-    relatedToComputed: SC.Record.toOne(function() {
-      return (this.readAttribute('relatedToComputed').indexOf("foo")==0) ? MyApp.Foo : MyApp.Bar;
-    })
-  }}}
+      relatedToComputed: SC.Record.toOne(function() {
+        return (this.readAttribute('relatedToComputed').indexOf("foo")==0) ? MyApp.Foo : MyApp.Bar;
+      })
   
   Notice that we are not using .get() to avoid another transform which would 
   trigger an infinite loop.
@@ -44,6 +40,9 @@ sc_require('models/record');
   A number of default RecordAttribute types are defined on the SC.Record.
   
   @extends SC.Object
+  @see SC.Record
+  @see SC.ManyAttribute
+  @see SC.SingleAttribute
   @since SproutCore 1.0
 */
 SC.RecordAttribute = SC.Object.extend(
@@ -51,7 +50,8 @@ SC.RecordAttribute = SC.Object.extend(
   /**
     Walk like a duck.
 
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isRecordAttribute: YES,
 
@@ -63,7 +63,8 @@ SC.RecordAttribute = SC.Object.extend(
     If you use a defaultValue function, the arguments given to it is the
     record instance and the key.
     
-    @property {Object|function}
+    @type Object|function
+    @default null
   */
   defaultValue: null,
   
@@ -75,7 +76,8 @@ SC.RecordAttribute = SC.Object.extend(
     If you use the attr() helper method to create a RecordAttribute instance,
     it will set this property to the first parameter you pass.
     
-    @property {Object|String}
+    @type Object|String
+    @default String
   */
   type: String,
   
@@ -85,7 +87,8 @@ SC.RecordAttribute = SC.Object.extend(
     attribute assigned to on the record.  If you need to provide some kind
     of alternate mapping, this provides you a way to override it.
     
-    @property {String}
+    @type String
+    @default null
   */
   key: null,
   
@@ -93,14 +96,16 @@ SC.RecordAttribute = SC.Object.extend(
     If YES, then the attribute is required and will fail validation unless
     the property is set to a non-null or undefined value.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isRequired: NO,
   
   /**
     If NO then attempts to edit the attribute will be ignored.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isEditable: YES,  
   
@@ -108,7 +113,8 @@ SC.RecordAttribute = SC.Object.extend(
     If set when using the Date format, expect the ISO8601 date format.  
     This is the default.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   useIsoDate: YES,
   
@@ -122,7 +128,8 @@ SC.RecordAttribute = SC.Object.extend(
     object (image) you might also want to automatically mark the parent 
     (album) dirty as well.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   aggregate: NO,
   
@@ -135,7 +142,9 @@ SC.RecordAttribute = SC.Object.extend(
     class, returns the type unchanged.  Otherwise attempts to lookup the 
     type as a property path.
     
-    @property {Object}
+    @property
+    @type Object
+    @default String
   */
   typeClass: function() {
     var ret = this.get('type');
@@ -144,9 +153,12 @@ SC.RecordAttribute = SC.Object.extend(
   }.property('type').cacheable(),
   
   /**
-    Finds the transform handler. 
+    Finds the transform handler. Attempts to find a transform that you
+    registered using registerTransform for this attribute's type, otherwise
+    defaults to using the default transform for String.
     
-    @property {Function}
+    @property
+    @type Transform
   */
   transform: function() {
     var klass      = this.get('typeClass') || String,
@@ -174,10 +186,10 @@ SC.RecordAttribute = SC.Object.extend(
     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
-    @param {Object} value the property value
-    @returns {Object} attribute value
+    @param {SC.Record} record The record instance
+    @param {String} key The key used to access this attribute on the record
+    @param {Object} value The property value before being transformed
+    @returns {Object} The transformed value
   */
   toType: function(record, key, value) {
     var transform = this.get('transform'),
@@ -206,11 +218,22 @@ SC.RecordAttribute = SC.Object.extend(
   /**
     @private
     
-    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.
-    This functionality can be used by setting an array named observesChildren on your transform containing the names of keys to observe.
-    When one of them triggers it will call childDidChange on your transform with the same arguments as to and from.
+    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.
+    
+    This functionality can be used by setting an array named
+    observesChildren on your transform containing the names of keys to
+    observe. When one of them triggers it will call childDidChange on your
+    transform with the same arguments as to and from.
+    
+    @param {Object} obj The transformed value that is being observed
+    @param {String} key The key used to access this attribute on the record
+    @param {Object} prev Previous value (not used)
+    @param {Object} context Hash of extra context information
   */
-  _SCRA_childObserver: function(obj, key, deprecated, context, rev) {
+  _SCRA_childObserver: function(obj, key, prev, context) {
     // write the new value back to the record
     this.call(context.record, context.key, obj);
     
@@ -224,10 +247,10 @@ SC.RecordAttribute = SC.Object.extend(
     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
-    @param {Object} value the property value
-    @returns {Object} attribute value
+    @param {SC.Record} record The record instance
+    @param {String} key The key used to access this attribute on the record
+    @param {Object} value The transformed value
+    @returns {Object} The value converted back to attribute format
   */
   fromType: function(record, key, value) {
     var transform = this.get('transform'),
@@ -240,11 +263,14 @@ SC.RecordAttribute = SC.Object.extend(
   },
 
   /**
-    The core handler.  Called from the property.
+    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.
     
-    @param {SC.Record} record the record instance
-    @param {String} key the key used to access this attribute on the record
-    @param {Object} value the property value if called as a setter
+    @param {SC.Record} record The record instance
+    @param {String} key The key used to access this attribute on the record
+    @param {Object} value The property value if called as a setter
     @returns {Object} property value
   */
   call: function(record, key, value) {
@@ -291,66 +317,69 @@ SC.RecordAttribute = SC.Object.extend(
     this.cacheKey = "__cache__" + SC.guidFor(this) ;
     this.lastSetValueKey = "__lastValue__" + SC.guidFor(this) ;
   }
-  
 }) ;
 
 // ..........................................................
 // CLASS METHODS
 // 
 
-/**
-  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.
-  
-  @param {Object|String} attributeType the assumed attribute type
-  @param {Hash} opts optional additional config options
-  @returns {SC.RecordAttribute} new instance
-*/
-SC.RecordAttribute.attr = function(attributeType, opts) {
-  if (!opts) opts = {} ;
-  if (!opts.type) opts.type = attributeType || String ;
-  return this.create(opts);
-};
-
-/** @private
-  Hash of registered transforms by class guid. 
-*/
-SC.RecordAttribute.transforms = {};
+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.
+
+    @static
+    @param {Object|String} attributeType the assumed attribute type
+    @param {Hash} opts optional additional config options
+    @returns {SC.RecordAttribute} new instance
+  */
+  attr: function(attributeType, opts) {
+    if (!opts) opts = {} ;
+    if (!opts.type) opts.type = attributeType || String ;
+    return this.create(opts);
+  },
 
-/**
-  Call to register a transform handler for a specific type of object.  The
-  object you pass can be of any type as long as it responds to the following
-  methods:
+  /** @private
+    Hash of registered transforms by class guid. 
+  */
+  transforms: {},
 
-  | *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:
-  
-  {{{
-  {
-    to: function(value, attr, type, record, key) {
-      if(value) return value.toSet();
-      else return SC.Set.create();
-    },
-  
-    from: function(value, attr, type, record, key) {
-      return value.toArray();
-    },
-  
-    observesChildren: ['[]']
+  /**
+    Call to register a transform handler for a specific type of object.  The
+    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
+    
+    
+    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) {
+            if(value) return value.toSet();
+            else return SC.Set.create();
+          },
+
+          from: function(value, attr, type, record, key) {
+            return value.toArray();
+          },
+
+          observesChildren: ['[]']
+        }
+
+    @static
+    @param {Object} klass the type of object you convert
+    @param {Object} transform the transform object
+    @returns {SC.RecordAttribute} receiver
+  */
+  registerTransform: function(klass, transform) {
+    SC.RecordAttribute.transforms[SC.guidFor(klass)] = transform;
   }
-  }}}
-  
-  @param {Object} klass the type of object you convert
-  @param {Object} transform the transform object
-  @returns {SC.RecordAttribute} receiver
-*/
-SC.RecordAttribute.registerTransform = function(klass, transform) {
-  SC.RecordAttribute.transforms[SC.guidFor(klass)] = transform;
-};
+});
 
 // ..........................................................
 // STANDARD ATTRIBUTE TRANSFORMS
@@ -484,7 +513,8 @@ SC.RecordAttribute.registerTransform(Date, {
   },
   
   _dates: {},
-
+  
+  /** @private - pad with leading zeroes */
   _zeropad: function(num) { 
     return ((num<0) ? '-' : '') + ((num<10) ? '0' : '') + Math.abs(num); 
   },

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

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -15,14 +15,12 @@ sc_require('models/record_attribute');
 
   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 
-      isMaster: YES|NO, // indicate whether changing this should dirty
-      transform: function(), // transforms value <=> storeKey,
-      isEditable: YES|NO, make editable or not
-    });
-  }}}
+      group: SC.Record.toOne('MyApp.Group', { 
+        inverse: 'contacts', // set the key used to represent the inverse 
+        isMaster: YES|NO, // indicate whether changing this should dirty
+        transform: function(), // transforms value <=> storeKey,
+        isEditable: YES|NO, make editable or not
+      });
   
   @extends SC.RecordAttribute
   @since SproutCore 1.0
@@ -35,7 +33,8 @@ SC.SingleAttribute = SC.RecordAttribute.extend(
     of the current relationship.  If set, then modifying this relationship
     will also alter the opposite side of the relationship.
     
-    @property {String}
+    @type String
+    @default null
   */
   inverse: null,
   
@@ -43,7 +42,8 @@ SC.SingleAttribute = SC.RecordAttribute.extend(
     If set, determines that when an inverse relationship changes whether this
     record should become dirty also or not.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isMaster: YES,
   
@@ -101,11 +101,10 @@ SC.SingleAttribute = SC.RecordAttribute.extend(
     of the relationship.  If this matches the inverse setting of the attribute
     then it will update itself accordingly.
     
-    @param {SC.Record} the record owning this attribute
+    @param {SC.Record} record the record owning this attribute
     @param {String} key the key for this attribute
     @param {SC.Record} inverseRecord record that was removed from inverse
-    @param {String} key key on inverse that was modified
-    @returns {void}
+    @param {String} inverseKey key on inverse that was modified
   */
   inverseDidRemoveRecord: function(record, key, inverseRecord, inverseKey) {
 
@@ -130,11 +129,10 @@ SC.SingleAttribute = SC.RecordAttribute.extend(
     inverse relationship.  This will set the value of this inverse record to 
     the new record.
     
-    @param {SC.Record} the record owning this attribute
+    @param {SC.Record} record the record owning this attribute
     @param {String} key the key for this attribute
     @param {SC.Record} inverseRecord record that was added to inverse
-    @param {String} key key on inverse that was modified
-    @returns {void}
+    @param {String} inverseKey key on inverse that was modified
   */
   inverseDidAddRecord: function(record, key, inverseRecord, inverseKey) {
     

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

@@ -1,6 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2010 Evin Grano
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -15,12 +16,13 @@
 */
 
 SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
-  /** @scope SC.ManyArray.prototype */ {
+  /** @scope SC.ChildArray.prototype */ {
     
   /**
     If set, it is the default record recordType
   
-    @property {SC.Record}
+    @default null
+    @type String
   */
   defaultRecordType: null,
   
@@ -28,7 +30,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     If set, the parent record will be notified whenever the array changes so that 
     it can change its own state
     
-    @property {SC.Record}
+    @default null
+    @type {SC.Record}
   */
   record: null,
   
@@ -36,12 +39,16 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     If set will be used by the many array to get an editable version of the
     storeIds from the owner.
     
-    @property {String}
+    @default null
+    @type String
   */
   propertyName: null,
   
   /**
     Actual references to the hashes
+  
+    @default null
+    @type {SC.Array}
   */
   children: null,
   
@@ -49,7 +56,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     The store that owns this record array.  All record arrays must have a 
     store to function properly.
 
-    @property {SC.Store}
+    @type SC.Store
+    @property 
   */
   store: function() {
     return this.getPath('record.store');
@@ -59,7 +67,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     The storeKey for the parent record of this many array.  Editing this 
     array will place the parent record into a READY_DIRTY state.
 
-    @property {Number}
+    @type Number
+    @property 
   */
   storeKey: function() {
     return this.getPath('record.storeKey');
@@ -69,7 +78,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     Returns the storeIds in read only mode.  Avoids modifying the record 
     unnecessarily.
     
-    @property {SC.Array}
+    @type SC.Array
+    @property 
   */
   readOnlyChildren: function() {
     return this.get('record').readAttribute(this.get('propertyName'));
@@ -79,7 +89,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     Returns an editable array of child hashes.  Marks the owner records as 
     modified. 
     
-    @property {SC.Array}
+    @type {SC.Array}
+    @property 
   */
   editableChildren: function() {
     var store    = this.get('store'),
@@ -104,16 +115,20 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
   /** @private
     Returned length is a pass-through to the storeIds array.
     
-    @property {Number}
+    @type Number
+    @property 
   */
   length: function() {
     var children = this.get('readOnlyChildren');
     return children ? children.length : 0;
   }.property('readOnlyChildren'),
 
-  /** @private
+  /**
     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, 
@@ -137,9 +152,15 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     return ret;
   },
 
-  /** @private
+  /** 
     Pass through to the underlying array.  The passed in objects must be
     records, which can be converted to storeIds.
+    
+    @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'), 
@@ -156,6 +177,13 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     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.
+  */
   _processRecordsToHashes: function(recs){
     var store, sk;
     recs = recs || [];
@@ -170,8 +198,8 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
     return recs;
   },
   
-  /*
-  calls normalize on each object in the array
+  /**
+    Calls normalize on each object in the array
   */
   normalize: function(){
     this.forEach(function(child,id){
@@ -183,8 +211,11 @@ SC.ChildArray = SC.Object.extend(SC.Enumerable, SC.Array,
   // INTERNAL SUPPORT
   //  
   
-  /** @private 
+  /** 
     Invoked whenever the children array changes.  Observes changes.
+    
+    @param {SC.Array} keys optional 
+    @returns {SC.ChildArray} itself.
   */
   recordPropertyDidChange: function(keys) {
     if (keys && !keys.contains(this.get('propertyName'))) return this;
@@ -207,6 +238,11 @@ 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} value
+    @param {Number} rev
   */
   _childrenContentDidChange: function(target, key, value, rev) {
     this._records = null ; // clear cache