1 // ==========================================================================
  2 // Project:   SproutCore - JavaScript Application Framework
  3 // Copyright: ©2006-2011 Strobe Inc. and contributors.
  4 //            Portions ©2008-2011 Apple Inc. All rights reserved.
  5 // License:   Licensed under MIT license (see license.js)
  6 // ==========================================================================
  7 
  8 sc_require('models/record');
  9 sc_require('models/record_attribute');
 10 
 11 /** @class
 12 
 13   Describes a single attribute that is fetched dynamically from the server
 14   when you request it.  Normally getting a property value with this attribute
 15   applied will cause call the `find()` method on the record store passing
 16   the attribute record type as the query key along with the property value,
 17   owner record, and property key name as parameters.
 18 
 19   The DataSource you hook up to your store must know how to load this kind
 20   of relationship for this fetched property to work properly.
 21 
 22   The return value is usually an `SC.RecordArray` that will populate with the
 23   record data so that you can display it.
 24 
 25   @extends SC.RecordAttribute
 26   @since SproutCore 1.0
 27 */
 28 SC.FetchedAttribute = SC.RecordAttribute.extend(
 29   /** @scope SC.FetchedAttribute.prototype */ {
 30 
 31   /**
 32     Define the param key that will be passed to the `find` method on the
 33     store.  If `null`, the param will not be sent.  Defaults to `'link'`
 34 
 35     @type String
 36   */
 37   paramValueKey: 'link',
 38 
 39   /**
 40     Define the param key used to send the parent record.  If `null`, the param
 41     will not be sent.  Defaults to '`owner'`.
 42 
 43     @type String
 44   */
 45   paramOwnerKey: 'owner',
 46 
 47   /**
 48     Define the param key used to send the key name used to reference this
 49     attribute.  If `null`, the param will not be sent.  Defaults to `"rel"`
 50 
 51     @type String
 52   */
 53   paramRelKey: 'rel',
 54 
 55   /**
 56     Optional query key to pass to find.  Otherwise type class will be
 57     passed.
 58 
 59     @type String
 60   */
 61   queryKey: null,
 62 
 63   /**
 64     Fetched attributes are not editable
 65 
 66     @type Boolean
 67   */
 68   isEditable: NO,
 69 
 70   // ..........................................................
 71   // LOW-LEVEL METHODS
 72   //
 73 
 74   /**  @private - adapted for fetching. do find */
 75   toType: function(record, key, value) {
 76     var store = record.get('store');
 77     if (!store) return null ; // nothing to do
 78 
 79     var paramValueKey = this.get('paramValueKey'),
 80         paramOwnerKey = this.get('paramOwnerKey'),
 81         paramRelKey   = this.get('paramRelKey'),
 82         queryKey      = this.get('queryKey') || this.get('typeClass'),
 83         params        = {};
 84 
 85     // setup params for query
 86     if (paramValueKey) params[paramValueKey] = value ;
 87     if (paramOwnerKey) params[paramOwnerKey] = record ;
 88     if (paramRelKey)   params[paramRelKey]   = this.get('key') || key ;
 89 
 90     // make request - should return SC.RecordArray instance
 91     return store.find(queryKey, params);
 92   },
 93 
 94   /** @private - fetched attributes are read only. */
 95   fromType: function(record, key, value) {
 96     return value;
 97   }
 98 
 99 }) ;
100 
101