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

data/lib/frameworks/sproutcore/frameworks/datastore/models/children_attribute.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)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/fetched_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)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/many_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)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/record.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)
 // ==========================================================================
 
@@ -14,9 +14,7 @@
   
   To create a new model class, in your SproutCore workspace, do:
   
-  {{{
-    $ sc-gen model MyApp.MyModel
-  }}}
+      $ sc-gen model MyApp.MyModel
   
   This will create MyApp.MyModel in clients/my_app/models/my_model.js.
   
@@ -34,6 +32,7 @@
   updateAttributes() method.
 
   @extends SC.Object
+  @see SC.RecordAttribute
   @since SproutCore 1.0
 */
 SC.Record = SC.Object.extend(
@@ -42,12 +41,16 @@ SC.Record = SC.Object.extend(
   /**  
     Walk like a duck
   
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isRecord: YES,
   
   /**
     If you have nested records
+    
+    @type Boolean
+    @default NO
   */
   isParentRecord: NO,
   
@@ -59,7 +62,8 @@ SC.Record = SC.Object.extend(
     This is the primary key used to distinguish records.  If the keys
     match, the records are assumed to be identical.
     
-    @property {String}
+    @type String
+    @default 'guid'
   */
   primaryKey: 'guid',
   
@@ -69,7 +73,9 @@ SC.Record = SC.Object.extend(
     have a primaryKey set on this class, then the id will be the value of the
     primaryKey property on the underlying JSON hash.
     
-    @property {String}
+    @type String
+    @property
+    @dependsOn storeKey
   */
   id: function(key, value) {
     if (value !== undefined) {
@@ -94,7 +100,9 @@ SC.Record = SC.Object.extend(
     These are all described in more detail in the class mixin (below) where 
     they are defined.
     
-    @property {Number}
+    @type Number
+    @property
+    @dependsOn storeKey
   */
   status: function() {
     return this.store.readStatus(this.storeKey);
@@ -107,7 +115,8 @@ SC.Record = SC.Object.extend(
     This property is set when the record instance is created and should not be
     changed or else it will break the record behavior.
     
-    @property {SC.Store}
+    @type SC.Store
+    @default null
   */
   store: null,
 
@@ -118,14 +127,17 @@ SC.Record = SC.Object.extend(
     You should not edit this store key but you may sometimes need to refer to
     this store key when implementing a Server object.
     
-    @property {Number}
+    @type Number
+    @default null
   */
   storeKey: null,
 
   /** 
     YES when the record has been destroyed
     
-    @property {Boolean}
+    @type Boolean
+    @property
+    @dependsOn status
   */
   isDestroyed: function() {
     return !!(this.get('status') & SC.Record.DESTROYED);  
@@ -140,7 +152,9 @@ SC.Record = SC.Object.extend(
     set this property to YES but the status of the record is anything but
     SC.Record.READY, the return value of this property may remain NO.
     
-    @property {Boolean}
+    @type Boolean
+    @property
+    @dependsOn status
   */
   isEditable: function(key, value) {
     if (value !== undefined) this._screc_isEditable = value;
@@ -148,13 +162,20 @@ SC.Record = SC.Object.extend(
     else return NO ;
   }.property('status').cacheable(),
 
+  /**
+    @private
+    
+    Backing value for isEditable
+  */
   _screc_isEditable: YES, // default
 
   /**
     YES when the record's contents have been loaded for the first time.  You 
     can use this to quickly determine if the record is ready to display.
     
-    @property {Boolean}
+    @type Boolean
+    @property
+    @dependsOn status
   */
   isLoaded: function() {
     var K = SC.Record, 
@@ -171,7 +192,8 @@ SC.Record = SC.Object.extend(
     
     Note this must be a regular Array - NOT any object implementing SC.Array.
     
-    @property {Array}
+    @type Array
+    @default null
   */
   relationships: null,
 
@@ -180,7 +202,8 @@ SC.Record = SC.Object.extend(
     make changes to this hash, be sure to call beginEditing() before you get
     the attributes and endEditing() afterwards.
   
-    @property {Hash}
+    @type Hash
+    @property
   **/
   attributes: function() {
     var store    = this.get('store'), 
@@ -194,7 +217,8 @@ SC.Record = SC.Object.extend(
     you would like to edit the attributes, see the @attributes@ property
     instead.
   
-    @property {Hash}
+    @type Hash
+    @property
   **/
   readOnlyAttributes: function() {
     var store    = this.get('store'), 
@@ -207,12 +231,18 @@ SC.Record = SC.Object.extend(
   }.property(),
   
   /**
-   * The namespace which to retrieve the childRecord Types from
-   */
+    The namespace which to retrieve the childRecord Types from
+    
+    @type String
+    @default null
+  */
   nestedRecordNamespace: null,
   
   /**
-    Function that returns whether this is a nested Record
+    Whether or not this is a nested Record.
+    
+    @type Boolean
+    @property
   */
   isNestedRecord: function(){
     var store = this.get('store'), ret,
@@ -223,6 +253,12 @@ SC.Record = SC.Object.extend(
     return ret;
   }.property().cacheable(),
   
+  /**
+    The parent record if this is a nested record.
+    
+    @type Boolean
+    @property
+  */
   parentRecord: function(){
     var sk = this.storeKey, store = this.get('store');
     return store.materializeParentRecord(sk);
@@ -238,12 +274,13 @@ SC.Record = SC.Object.extend(
     record data from the server.  If the record is new and exists only in 
     memory then this call will have no effect.
     
-    @param {boolean} recordOnly, optional param if you want to only THIS record
+    @param {boolean} recordOnly optional param if you want to only THIS record
       even if it is a child record.
+    @param {Function} callback optional callback that will fire when request finishes
     
     @returns {SC.Record} receiver
   */
-  refresh: function(recordOnly) { 
+  refresh: function(recordOnly, callback) { 
     var store = this.get('store'), rec, ro,
         sk = this.get('storeKey'),
         prKey = store.parentStoreKeyExists();
@@ -252,10 +289,10 @@ SC.Record = SC.Object.extend(
     // we will commit this record
     ro = recordOnly || (SC.none(recordOnly) && SC.none(prKey));
     if (ro){
-      store.refreshRecord(null, null, sk);
+      store.refreshRecord(null, null, sk, callback);
     } else if (prKey){
       rec = store.materializeRecord(prKey);
-      rec.refresh(recordOnly);
+      rec.refresh(recordOnly, callback);
     }
 
     return this ;
@@ -266,8 +303,8 @@ SC.Record = SC.Object.extend(
     records destroyed in the store as well as changing the isDestroyed 
     property on the record to YES.  If this is a new record, this will avoid 
     creating the record in the first place.
-    
-    @param {boolean} recordOnly, optional param if you want to only THIS record
+
+    @param {boolean} recordOnly optional param if you want to only THIS record
       even if it is a child record. 
     
     @returns {SC.Record} receiver
@@ -306,7 +343,7 @@ SC.Record = SC.Object.extend(
     If you pass the key that changed it will ensure that observers are fired
     only once for the changed property instead of allPropertiesDidChange()
     
-    @param {String} key that changed (optional)
+    @param {String} key key that changed (optional)
     @returns {SC.Record} receiver
   */
   recordDidChange: function(key) {
@@ -355,7 +392,7 @@ SC.Record = SC.Object.extend(
     
     Calls to beginEditing() and endEditing() can be nested.
     
-    @param {String} key that changed (optional)
+    @param {String} key key that changed (optional)
     @returns {SC.Record} receiver
   */
   endEditing: function(key) {
@@ -450,11 +487,17 @@ SC.Record = SC.Object.extend(
         destroyed  = K.DESTROYED,
         readyClean = K.READY_CLEAN,
         iter;
-        
-    // If the child is dirty, then make sure the parent gets a dirty
-    // status.  (If the child is created or destroyed, there's no need,
-    // because the parent will dirty itself when it modifies that
-    // relationship.)
+    
+    /**
+      @private
+      
+      If the child is dirty, then make sure the parent gets a dirty
+      status.  (If the child is created or destroyed, there's no need,
+      because the parent will dirty itself when it modifies that
+      relationship.)
+      
+      @param {SC.Record} record to propagate to
+    */
     iter =  function(rec) {
       var childStatus, parentStatus;
       
@@ -644,11 +687,13 @@ SC.Record = SC.Object.extend(
     
     @param {Hash} params optional additonal params that will passed down
       to the data source
-    @param {boolean} recordOnly, optional param if you want to only commit a single
+    @param {boolean} recordOnly optional param if you want to only commit a single
       record if it has a parent.
+    @param {Function} callback optional callback that the store will fire once the 
+    datasource finished committing
     @returns {SC.Record} receiver
   */
-  commitRecord: function(params, recordOnly) {    
+  commitRecord: function(params, recordOnly, callback) {    
     var store = this.get('store'), rec, ro,
         sk = this.get('storeKey'),
         prKey = store.parentStoreKeyExists();
@@ -657,12 +702,11 @@ SC.Record = SC.Object.extend(
     // we will commit this record
     ro = recordOnly || (SC.none(recordOnly) && SC.none(prKey));
     if (ro){
-      store.commitRecord(undefined, undefined, this.get('storeKey'), params);
+      store.commitRecord(undefined, undefined, this.get('storeKey'), params, callback);
     } else if (prKey){
       rec = store.materializeRecord(prKey);
-      rec.commitRecord(params, recordOnly);
+      rec.commitRecord(params, recordOnly, callback);
     }
-    
     return this ;
   },
   
@@ -674,7 +718,9 @@ SC.Record = SC.Object.extend(
     Returns YES whenever the status is SC.Record.ERROR.  This will allow you 
     to put the UI into an error state.
     
-    @property {Boolean}
+    @type Boolean
+    @property
+    @dependsOn status
   */
   isError: function() {
     return this.get('status') & SC.Record.ERROR;
@@ -684,7 +730,9 @@ SC.Record = SC.Object.extend(
     Returns the receiver if the record is in an error state.  Returns null
     otherwise.
     
-    @property {SC.Record}
+    @type SC.Record
+    @property
+    @dependsOn isError
   */
   errorValue: function() {
     return this.get('isError') ? SC.val(this.get('errorObject')) : null ;
@@ -694,7 +742,9 @@ SC.Record = SC.Object.extend(
     Returns the current error object only if the record is in an error state.
     If no explicit error object has been set, returns SC.Record.GENERIC_ERROR.
     
-    @property {SC.Error}
+    @type SC.Error
+    @property
+    @dependsOn isError
   */
   errorObject: function() {
     if (this.get('isError')) {
@@ -767,6 +817,8 @@ SC.Record = SC.Object.extend(
 
     @param {Hash} value The hash of attributes to apply to the child record.
     @param {Integer} key The store key that we are asking for
+    @param {String} path The property path of the child record
+    @returns {SC.Record} the child record that was registered
    */
   registerNestedRecord: function(value, key, path) {
     var store, psk, csk, childRecord, recordType;
@@ -795,6 +847,8 @@ SC.Record = SC.Object.extend(
   },
   
   /**
+    @private
+    
      private method that retrieves the recordType from the hash that is provided.
 
      Important for use in polymorphism but you must have the following items in the
@@ -804,6 +858,7 @@ SC.Record = SC.Object.extend(
 
      @param {Hash} value The hash of attributes to apply to the child record.
      @param {String} key the name of the key on the attribute
+     @param {SC.Record} the record that was materialized
     */
   _materializeNestedRecordType: function(value, key){
     var childNS, recordType, ret;
@@ -836,6 +891,7 @@ SC.Record = SC.Object.extend(
     @param {SC.Record} recordType The type of the nested record to create.
     @param {Hash} hash The hash of attributes to apply to the child record.
     (may be null)
+    @returns {SC.Record} the nested record created
    */
   createNestedRecord: function(recordType, hash) {
     var store, id, sk, pk, cr = null, existingId = null;
@@ -879,22 +935,27 @@ SC.Record = SC.Object.extend(
   _nestedRecordKey: 0,
     
   /**
-   * Override this function if you want to have a special way of creating 
-   * ids for your child records
+    Override this function if you want to have a special way of creating 
+    ids for your child records
+    
+    @param {SC.Record} childRecord
+    @returns {String} the id generated
    */
   generateIdForChild: function(childRecord){}
      
 }) ;
 
 // Class Methods
-SC.Record.mixin( /** @scope SC.Record */ {
+SC.Record.mixin( /** @scope SC.Record.prototype */ {
 
   /**
     Whether to ignore unknown properties when they are being set on the record
     object. This is useful if you want to strictly enforce the model schema
     and not allow dynamically expanding it by setting new unknown properties
     
-    @property {Boolean}
+    @static
+    @type Boolean
+    @default NO
   */
   ignoreUnknownProperties: NO,
 
@@ -907,7 +968,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0001
   */
   CLEAN:            0x0001, // 1
 
@@ -916,7 +980,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0002
   */
   DIRTY:            0x0002, // 2
   
@@ -927,7 +994,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     it when working with the low-level data hash API on SC.Store. Use a 
     logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0100
   */
   EMPTY:            0x0100, // 256
 
@@ -936,7 +1006,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x1000
   */
   ERROR:            0x1000, // 4096
   
@@ -945,7 +1018,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0200
   */
   READY:            0x0200, // 512
 
@@ -954,7 +1030,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0201
   */
   READY_CLEAN:      0x0201, // 513
 
@@ -964,7 +1043,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0202
   */
   READY_DIRTY:      0x0202, // 514
 
@@ -974,7 +1056,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0203
   */
   READY_NEW:        0x0203, // 515
   
@@ -984,7 +1069,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0400
   */
   DESTROYED:        0x0400, // 1024
 
@@ -994,7 +1082,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0401
   */
   DESTROYED_CLEAN:  0x0401, // 1025
 
@@ -1004,7 +1095,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0402
   */
   DESTROYED_DIRTY:  0x0402, // 1026
   
@@ -1014,7 +1108,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0800
   */
   BUSY:             0x0800, // 2048
 
@@ -1024,7 +1121,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0804
   */
   BUSY_LOADING:     0x0804, // 2052
 
@@ -1035,7 +1135,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0808
   */
   BUSY_CREATING:    0x0808, // 2056
 
@@ -1045,7 +1148,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0810
   */
   BUSY_COMMITTING:  0x0810, // 2064
 
@@ -1055,7 +1161,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status.
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0820
   */
   BUSY_REFRESH:     0x0820, // 2080
 
@@ -1065,7 +1174,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0821
   */
   BUSY_REFRESH_CLEAN:  0x0821, // 2081
 
@@ -1074,7 +1186,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0822
   */
   BUSY_REFRESH_DIRTY:  0x0822, // 2082
 
@@ -1083,7 +1198,10 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use a logical AND (single &) to test record status
   
-    @property {Number}
+    @static
+    @constant
+    @type Number
+    @default 0x0840
   */
   BUSY_DESTROYING:  0x0840, // 2112
 
@@ -1096,41 +1214,52 @@ SC.Record.mixin( /** @scope SC.Record */ {
     Error for when you try to modify a record while it is in a bad 
     state.
     
-    @property {SC.Error}
+    @static
+    @constant
+    @type SC.Error
   */
-  BAD_STATE_ERROR:     SC.$error("Internal barf Inconsistency"),
+  BAD_STATE_ERROR:     SC.$error("Internal Inconsistency"),
 
   /**
     Error for when you try to create a new record that already exists.
     
-    @property {SC.Error}
+    @static
+    @constant
+    @type SC.Error
   */
   RECORD_EXISTS_ERROR: SC.$error("Record Exists"),
 
   /**
     Error for when you attempt to locate a record that is not found
     
-    @property {SC.Error}
+    @static
+    @constant
+    @type SC.Error
   */
   NOT_FOUND_ERROR:     SC.$error("Not found "),
 
   /**
     Error for when you try to modify a record that is currently busy
     
-    @property {SC.Error}
+    @static
+    @constant
+    @type SC.Error
   */
   BUSY_ERROR:          SC.$error("Busy"),
 
   /**
     Generic unknown record error
     
-    @property {SC.Error}
+    @static
+    @constant
+    @type SC.Error
   */
   GENERIC_ERROR:       SC.$error("Generic Error"),
   
   /**
-   * The next child key to allocate.  A nextChildKey must always be greater than 0.
-   */
+    @private
+    The next child key to allocate.  A nextChildKey must always be greater than 0.
+  */
   _nextChildKey: 0,
   
   // ..........................................................
@@ -1145,13 +1274,9 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use this helper when you define SC.Record subclasses. 
     
-    h4. Example
-    
-    {{{
-      MyApp.Contact = SC.Record.extend({
-        firstName: SC.Record.attr(String, { isRequired: YES })
-      });
-    }}}
+        MyApp.Contact = SC.Record.extend({
+          firstName: SC.Record.attr(String, { isRequired: YES })
+        });
     
     @param {Class} type the attribute type
     @param {Hash} opts the options for the attribute
@@ -1168,13 +1293,9 @@ SC.Record.mixin( /** @scope SC.Record */ {
     
     Use this helper when you define SC.Record subclasses. 
     
-    h4. Example
-    
-    {{{
-      MyApp.Group = SC.Record.extend({
-        contacts: SC.Record.fetch('MyApp.Contact')
-      });
-    }}}
+        MyApp.Group = SC.Record.extend({
+          contacts: SC.Record.fetch('MyApp.Contact')
+        });
     
     @param {SC.Record|String} recordType The type of records to load
     @param {Hash} opts the options for the attribute
@@ -1185,11 +1306,11 @@ SC.Record.mixin( /** @scope SC.Record */ {
   },
   
   /**
-    Returns:
+    Will return one of the following:
     
-    1: SC.ManyAttribute that describes a record array backed by an 
+    1. SC.ManyAttribute that describes a record array backed by an 
     array of guids stored in the underlying JSON.  
-    2: SC.ChildrenAttribute that describes a record array backed by a
+    2. SC.ChildrenAttribute that describes a record array backed by a
     array of hashes.
     
     You can edit the contents of this relationship.
@@ -1217,11 +1338,11 @@ SC.Record.mixin( /** @scope SC.Record */ {
   },
   
   /**
-    Returns:
+    Will return one of the following:
+    
     1. SC.SingleAttribute that converts the underlying ID to a single
     record.  If you modify this property, it will rewrite the underyling ID. 
     It will also modify the inverse of the relationship, if you set it.
-    
     2. SC.ChildAttribute that you can edit the contents
     of this relationship.