sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/core_foundation/views/view/touch.js

@@ -0,0 +1,67 @@
+sc_require("views/view");
+
+SC.View.reopen(
+  /** @scope SC.View.prototype */ {
+
+  // ..........................................................
+  // MULTITOUCH SUPPORT
+  //
+  /**
+    Set to YES if you want to receive touch events for each distinct touch (rather than only
+    the first touch start and last touch end).
+  */
+  acceptsMultitouch: NO,
+
+  /**
+    Is YES if the view is currently being touched. NO otherwise.
+  */
+  hasTouch: NO,
+
+  /**
+    A boundary set of distances outside which the touch will not be considered "inside" the view anymore.
+
+    By default, up to 50px on each side.
+  */
+  touchBoundary: { left: 50, right: 50, top: 50, bottom: 50 },
+
+  /**
+    @private
+    A computed property based on frame.
+  */
+  _touchBoundaryFrame: function (){
+    return this.get("parentView").convertFrameToView(this.get('frame'), null);
+  }.property("frame", "parentView").cacheable(),
+
+  /**
+    Returns YES if the provided touch is within the boundary.
+  */
+  touchIsInBoundary: function(touch) {
+    var f = this.get("_touchBoundaryFrame"), maxX = 0, maxY = 0, boundary = this.get("touchBoundary");
+    var x = touch.pageX, y = touch.pageY;
+
+    if (x < f.x) {
+      x = f.x - x;
+      maxX = boundary.left;
+    } else if (x > f.x + f.width) {
+      x = x - (f.x + f.width);
+      maxX = boundary.right;
+    } else {
+      x = 0;
+      maxX = 1;
+    }
+
+    if (y < f.y) {
+      y = f.y - y;
+      maxY = boundary.top;
+    } else if (y > f.y + f.height) {
+      y = y - (f.y + f.height);
+      maxY = boundary.bottom;
+    } else {
+      y = 0;
+      maxY = 1;
+    }
+
+    if (x > 100 || y > 100) return NO;
+    return YES;
+  }
+});

data/lib/frameworks/sproutcore/frameworks/core_foundation/views/view/visibility.js

@@ -0,0 +1,118 @@
+sc_require("views/view");
+
+SC.View.reopen(
+  /** @scope SC.View.prototype */ {
+
+  /**
+    Set to YES to indicate the view has visibility support added.
+  */
+  hasVisibility: YES,
+
+  /**
+    YES only if the view and all of its parent views are currently visible
+    in the window.  This property is used to optimize certain behaviors in
+    the view.  For example, updates to the view layer are not performed
+    if the view until the view becomes visible in the window.
+  */
+  isVisibleInWindow: NO,
+
+  /**
+   By default we don't disable the context menu. Overriding this property
+   can enable/disable the context menu per view.
+  */
+  isContextMenuEnabled: function() {
+    return SC.CONTEXT_MENU_ENABLED;
+  }.property(),
+
+  /**
+    Recomputes the isVisibleInWindow property based on the visibility of the
+    view and its parent.  If the recomputed value differs from the current
+    isVisibleInWindow state, this method will also call
+    recomputIsVisibleInWindow() on its child views as well.  As an optional
+    optimization, you can pass the isVisibleInWindow state of the parentView
+    if you already know it.
+
+    You will not generally need to call or override this method yourself. It
+    is used by the SC.View hierarchy to relay window visibility changes up
+    and down the chain.
+
+    @property {Boolean} parentViewIsVisible
+    @returns {SC.View} receiver
+  */
+  recomputeIsVisibleInWindow: function(parentViewIsVisible) {
+    var previous = this.get('isVisibleInWindow'),
+        current  = this.get('isVisible'),
+        parentView;
+
+    // isVisibleInWindow = isVisible && parentView.isVisibleInWindow
+    // this approach only goes up to the parentView if necessary.
+    if (current) {
+      // If we weren't passed in 'parentViewIsVisible' (we generally aren't;
+      // it's an optimization), then calculate it.
+      if (parentViewIsVisible === undefined) {
+        parentView = this.get('parentView');
+        parentViewIsVisible = parentView ? parentView.get('isVisibleInWindow') : NO;
+      }
+      current = current && parentViewIsVisible;
+    }
+
+    // If our visibility has changed, then set the new value and notify our
+    // child views to update their value.
+    if (previous !== current) {
+      this.set('isVisibleInWindow', current);
+
+      var childViews = this.get('childViews'), len = childViews.length, idx, view;
+      for(idx=0;idx<len;idx++) {
+        view = childViews[idx];
+        if(view.recomputeIsVisibleInWindow) { view.recomputeIsVisibleInWindow(current); }
+      }
+
+      // For historical reasons, we'll also layout the child views if
+      // necessary.
+      if (current) {
+        if (this.get('childViewsNeedLayout')) { this.invokeOnce(this.layoutChildViewsIfNeeded); }
+      }
+      else {
+        // Also, if we were previously visible and were the first responder,
+        // resign it.  This more appropriately belongs in a
+        // 'isVisibleInWindow' observer or some such helper method because
+        // this work is not strictly related to computing the visibility, but
+        // view performance is critical, so avoiding the extra observer is
+        // worthwhile.
+        if (this.get('isFirstResponder')) { this.resignFirstResponder(); }
+      }
+    }
+
+    // If we're in this function, then that means one of our ancestor views
+    // changed, or changed its 'isVisibleInWindow' value.  That means that if
+    // we are out of sync with the layer, then we need to update our state
+    // now.
+    //
+    // For example, say we're isVisible=NO, but we have not yet added the
+    // 'sc-hidden' class to the layer because of the "don't update the layer if
+    // we're not visible in the window" check.  If any of our parent views
+    // became visible, our layer would incorrectly be shown!
+    this.updateLayerIfNeeded(YES);
+
+    return this;
+  },
+
+
+  /** @private
+    Whenever the view's visibility changes, we need to recompute whether it is
+    actually visible inside the window (a view is only visible in the window
+    if it is marked as visibile and its parent view is as well), in addition
+    to updating the layer accordingly.
+  */
+  _sc_isVisibleDidChange: function() {
+    // 'isVisible' is effectively a displayProperty, but we'll call
+    // displayDidChange() manually here instead of declaring it as a
+    // displayProperty because that avoids having two observers on
+    // 'isVisible'.  A single observer is:
+    //   a.  More efficient
+    //   b.  More correct, because we can guarantee the order of operations
+    this.displayDidChange();
+
+    this.recomputeIsVisibleInWindow();
+  }.observes('isVisible')
+})

data/lib/frameworks/sproutcore/frameworks/core_tools/core.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/core_tools/data_source.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)
 // ==========================================================================
 /*globals CoreTools */

data/lib/frameworks/sproutcore/frameworks/core_tools/english.lproj/strings.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools Strings
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/core_tools/fixtures/target.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools.Target Fixtures
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/core_tools/fixtures/test.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools.Test Fixtures
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/core_tools/models/target.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools.Target
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/core_tools/models/test.js

@@ -1,6 +1,6 @@
 // ==========================================================================
 // Project:   CoreTools.Test
-// Copyright: ©2010 Apple Inc.
+// Copyright: ©2011 Apple Inc.
 // ==========================================================================
 /*globals CoreTools */
 

data/lib/frameworks/sproutcore/frameworks/datastore/core.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/data_sources/cascade.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)
 // ==========================================================================
 
@@ -16,23 +16,21 @@ sc_require('data_sources/data_source');
   You can use a cascading data source to tie together multiple data sources,
   treating them as a single namespace.
   
-  h2. Configuring a Cascade Data Source
+  ## Configuring a Cascade Data Source
   
   You will usually define your cascading data source in your main method after
   all the classes you have are loaded.
   
-  {{{
-    MyApp.dataSource = SC.CascadeDataSource.create({
-      dataSources: "prefs youtube photos".w(),
+      MyApp.dataSource = SC.CascadeDataSource.create({
+        dataSources: "prefs youtube photos".w(),
+        
+        prefs:   MyApp.PrefsDataSource.create({ root: "/prefs" }),
+        youtube: YouTube.YouTubeDataSource.create({ apiKey: "123456" }),
+        photos:  MyApp.PhotosDataSource.create({ root: "photos" })
+        
+      });
       
-      prefs:   MyApp.PrefsDataSource.create({ root: "/prefs" }),
-      youtube: YouTube.YouTubeDataSource.create({ apiKey: "123456" }),
-      photos:  MyApp.PhotosDataSource.create({ root: "photos" })
-      
-    });
-    
-    MyApp.store.set('dataSource', MyApp.dataSource);
-  }}}
+      MyApp.store.set('dataSource', MyApp.dataSource);
   
   Note that the order you define your dataSources property will determine the
   order in which requests will cascade from the store.
@@ -40,14 +38,12 @@ sc_require('data_sources/data_source');
   Alternatively, you can use a more jQuery-like API for defining your data
   sources:
   
-  {{{
-    MyApp.dataSource = SC.CascadeDataSource.create()
-      .from(MyApp.PrefsDataSource.create({ root: "/prefs" }))
-      .from(YouTube.YouTubeDataSource.create({ apiKey: "123456" }))
-      .from(MyApp.PhotosDataSource.create({ root: "photos" }));
+      MyApp.dataSource = SC.CascadeDataSource.create()
+        .from(MyApp.PrefsDataSource.create({ root: "/prefs" }))
+        .from(YouTube.YouTubeDataSource.create({ apiKey: "123456" }))
+        .from(MyApp.PhotosDataSource.create({ root: "photos" }));
 
-    MyApp.store.set('dataSource', MyApp.dataSource);
-  }}}
+      MyApp.store.set('dataSource', MyApp.dataSource);
 
   In this case, the order you call from() will determine the order the request
   will cascade.
@@ -119,7 +115,7 @@ SC.CascadeDataSource = SC.DataSource.extend(
   },
 
   /** @private - just cascades */
-  commitRecords: function(store, createStoreKeys, updateStoreKeys, destroyStoreKeys) {
+  commitRecords: function(store, createStoreKeys, updateStoreKeys, destroyStoreKeys, params) {
     var sources = this.get('dataSources'), 
         len     = sources ? sources.length : 0,
         ret     = NO,

data/lib/frameworks/sproutcore/frameworks/datastore/data_sources/data_source.js

@@ -1,15 +1,205 @@
 // ==========================================================================
 // 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)
 // ==========================================================================
 
 
 /** @class
 
-  TODO: Describe
-  
+  A DataSource connects an in-memory store to one or more server backends.
+  To connect to a data backend on a server, subclass `SC.DataSource`
+  and implement the necessary data source methods to communicate with the
+  particular backend.
+
+  ## Create a Data Source
+
+  To implement the data source, subclass `SC.DataSource` in a file located
+  either in the root level of your app or framework, or in a directory
+  called "data_sources":
+
+      MyApp.DataSource = SC.DataSource.extend({
+        // implement the data source API...
+      });
+
+  ## Connect to a Data Source
+
+  New SproutCore applications are wired up to fixtures as their data source.
+  When you are ready to connect to a server, swap the use of fixtures with a
+  call to the desired data source.
+
+  In core.js:
+
+      // change...
+      store: SC.Store.create().from(SC.Record.fixtures)
+
+      // to...
+      store: SC.Store.create().from('MyApp.DataSource')
+
+  Note that the data source class name is referenced by string since the file
+  in which it is defined may not have been loaded yet. The first time a
+  data store tries to access its data source it will look up the class name
+  and instantiate that data source.
+
+  ## Implement the Data Source API
+
+  There are three methods that a data store invokes on its data source:
+
+   * `fetch()` — called the first time you try to `find()` a query
+     on a store or any time you refresh the record array after that.
+   * `retrieveRecords()` — called when you access an individual
+     record that has not been loaded yet
+   * `commitRecords()` — called if the the store has changes
+     pending and its `commitRecords()` method is invoked.
+
+  The data store will call the `commitRecords()` method when records
+  need to be created, updated, or deleted. If the server that the data source
+  connects to handles these three actions in a uniform manner, it may be
+  convenient to implement the `commitRecords()` to handle record
+  creation, updating, and deletion.
+
+  However, if the calls the data source will need to make to the server to
+  create, update, and delete records differ from each other to a significant
+  enough degree, it will be more convenient to rely on the default behavior
+  of `commitRecords()` and instead implement the three methods that
+  it will call by default:
+
+   * `createRecords()` — called with a list of records that are new
+     and need to be created on the server.
+   * `updateRecords()` — called with a list of records that already
+      exist on the server but that need to be updated.
+   * `destroyRecords()` — called with a list of records that should
+     be deleted on the server.
+
+  ### Multiple records
+
+  The `retrieveRecords()`, `createRecords()`, `updateRecords()` and
+  `destroyRecords()` methods all work on multiple records. If your server
+  API accommodates calls where you can  pass a list of records, this might
+  be the best level at which to implement the Data Source API. On the other
+  hand, if the server requires that you send commands for it for individual
+  records, you can rely on the default implementation of these four methods,
+  which will call the following for each individual record, one at a time:
+
+   - `retrieveRecord()` — called to retrieve a single record.
+   - `createRecord()` — called to create a single record.
+   - `updateRecord()` — called to update a single record.
+   - `destroyRecord()` — called to destroy a single record.
+
+
+  ### Return Values
+
+  All of the methods you implement must return one of three values:
+   - `YES` — all the records were handled.
+   - `NO` — none of the records were handled.
+   - `SC.MIXED_STATE` — some, but not all of the records were handled.
+
+
+  ### Store Keys
+
+  Whenever a data store invokes one of the data source methods it does so
+  with a storeKeys or storeKey argument. Store keys are transient integers
+  assigned to each data hash when it is first loaded into the store. It is
+  used to track data hashes as they move up and down nested stores (even if
+  no associated record is ever created from it).
+
+  When passed a storeKey you can use it to retrieve the status, data hash,
+  record type, or record ID, using the following data store methods:
+
+   * `readDataHash(storeKey)` — returns the data hash associated with
+     a store key, if any.
+   * `readStatus(storeKey)` — returns the current record status
+     associated with the store key. May be `SC.Record.EMPTY`.
+   * `SC.Store.recordTypeFor(storeKey)` — returns the record type for
+     the associated store key.
+   * `recordType.idFor(storeKey)` — returns the record ID for
+     the associated store key. You must call this method on `SC.Record`
+     subclass itself, not on an instance of `SC.Record`.
+
+  These methods are safe for reading data from the store. To modify data
+  in the data store you must use the store callbacks described below. The
+  store callbacks will ensure that the record states remain consistent.
+
+  ### Store Callbacks
+
+  When a data store calls a data source method, it puts affected records into
+  a `BUSY` state. To guarantee data integrity and consistency, these records
+  cannot be modified by the rest of the application while they are in the `BUSY`
+  state.
+
+  Because records are "locked" while in the `BUSY` state, it is the data source's
+  responsibility to invoke a callback on the store for each record or query that
+  was passed to it and that the data source handled. To reduce the amount of work
+  that a data source must do, the data store will automatically unlock the relevant
+  records if the the data source method returned `NO`, indicating that the records
+  were unhandled.
+
+  Although a data source can invoke callback methods at any time, they should
+  usually be invoked after receiving a response from the server. For example, when
+  the data source commits a change to a record by issuing a command to the server,
+  it waits for the server to acknowledge the command before invoking the
+  `dataSourceDidComplete()` callback.
+
+  In some cases a data source may be able to assume a server's response and invoke
+  the callback on the store immediately. This can improve performance because the
+  record can be unlocked right away.
+
+
+  ### Record-Related Callbacks
+
+  When `retrieveRecords()`, `commitRecords()`, or any of the related methods are
+  called on a data source, the store puts any records to be handled by the data
+  store in a `BUSY` state. To release the records the data source must invoke one
+  of the record-related callbacks on the store:
+
+   * `dataSourceDidComplete(storeKey, dataHash, id)` — the most common
+     callback. You might use this callback when you have retrieved a record to
+     load its contents into the store. The callback tells the store that the data
+     source is finished with the storeKey in question. The `dataHash` and `id`
+     arguments are optional and will replace the current dataHash and/or id. Also
+     see "Loading Records" below.
+   * `dataSourceDidError(storeKey, error)` — a data source should call this
+     when a request could not be completed because an error occurred. The error
+     argument is optional and can contain more information about the error.
+   * `dataSourceDidCancel(storeKey)` — a data source should call this when
+     an operation is cancelled for some reason. This could be used when the user
+     is able to cancel an operation that is in progress.
+
+  ### Loading Records into the Store
+
+  Instead of orchestrating multiple `dataSourceDidComplete()` callbacks when loading
+  multiple records, a data source can call the `loadRecords()` method on the store,
+  passing in a `recordType`, and array of data hashes, and optionally an array of ids.
+  The `loadRecords()` method takes care of looking up storeKeys and calling the
+  `dataSourceDidComplete()` callback as needed.
+
+  `loadRecords()` is often the most convenient way to get large blocks of data into
+  the store, especially in response to a `fetch()` or `retrieveRecords()` call.
+
+
+  ### Query-Related Callbacks
+
+  Like records, queries that are passed through the `fetch()` method also have an
+  associated status property; accessed through the `status`  property on the record
+  array returned from `find()`. To properly reset this status, a data source must
+  invoke an appropriate query-related callback on the store. The callbacks for
+  queries are similar to those for records:
+
+   * `dataSourceDidFetchQuery(query)` — the data source must call this when
+     it has completed fetching any related data for the query. This returns the
+     query results (record array) status into a `READY` state.
+   * `dataSourceDidErrorQuery(query, error)` — the data source should call
+     this if it encounters an error in executing the query. This puts the query
+     results into an `ERROR` state.
+   * `dataSourceDidCancelQuery(query)` — the data source should call this
+     if loading the results is cancelled.
+
+  In addition to these callbacks, the method `loadQueryResults(query, storeKey)`
+  is used by data sources when handling remote queries. This method is similar to
+  `dataSourceDidFetchQuery()`, except that you also provide an array of storeKeys
+  (or a promise to provide store keys) that comprises the result set.
+
   @extend SC.Object
   @since SproutCore 1.0
 */
@@ -17,71 +207,71 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
 
   // ..........................................................
   // SC.STORE ENTRY POINTS
-  // 
-  
+  //
+
 
   /**
-  
-    Invoked by the store whenever it needs to retrieve data matching a 
+
+    Invoked by the store whenever it needs to retrieve data matching a
     specific query, triggered by find().  This method is called anytime
-    you invoke SC.Store#find() with a query or SC.RecordArray#refresh().  You 
-    should override this method to actually retrieve data from the server 
-    needed to fulfill the query.  If the query is a remote query, then you 
+    you invoke SC.Store#find() with a query or SC.RecordArray#refresh().  You
+    should override this method to actually retrieve data from the server
+    needed to fulfill the query.  If the query is a remote query, then you
     will also need to provide the contents of the query as well.
-    
-    h3. Handling Local Queries
-    
+
+    ### Handling Local Queries
+
     Most queries you create in your application will be local queries.  Local
     queries are populated automatically from whatever data you have in memory.
     When your fetch() method is called on a local queries, all you need to do
-    is load any records that might be matched by the query into memory. 
-    
+    is load any records that might be matched by the query into memory.
+
     The way you choose which queries to fetch is up to you, though usually it
     can be something fairly straightforward such as loading all records of a
     specified type.
-    
-    When you finish loading any data that might be required for your query, 
-    you should always call SC.Store#dataSourceDidFetchQuery() to put the query 
+
+    When you finish loading any data that might be required for your query,
+    you should always call SC.Store#dataSourceDidFetchQuery() to put the query
     back into the READY state.  You should call this method even if you choose
     not to load any new data into the store in order to notify that the store
     that you think it is ready to return results for the query.
-    
-    h3. Handling Remote Queries
-    
+
+    ### Handling Remote Queries
+
     Remote queries are special queries whose results will be populated by the
-    server instead of from memory.  Usually you will only need to use this 
+    server instead of from memory.  Usually you will only need to use this
     type of query when loading large amounts of data from the server.
-    
+
     Like Local queries, to fetch a remote query you will need to load any data
     you need to fetch from the server and add the records to the store.  Once
     you are finished loading this data, however, you must also call
     SC.Store#loadQueryResults() to actually set an array of storeKeys that
     represent the latest results from the server.  This will implicitly also
-    call datasSourceDidFetchQuery() so you don't need to call this method 
+    call datasSourceDidFetchQuery() so you don't need to call this method
     yourself.
-    
-    If you want to support incremental loading from the server for remote 
-    queries, you can do so by passing a SC.SparseArray instance instead of 
+
+    If you want to support incremental loading from the server for remote
+    queries, you can do so by passing a SC.SparseArray instance instead of
     a regular array of storeKeys and then populate the sparse array on demand.
-    
-    h3. Handling Errors and Cancelations
-    
-    If you encounter an error while trying to fetch the results for a query 
+
+    ### Handling Errors and Cancelations
+
+    If you encounter an error while trying to fetch the results for a query
     you can call SC.Store#dataSourceDidErrorQuery() instead.  This will put
-    the query results into an error state.  
-    
-    If you had to cancel fetching a query before the results were returned, 
-    you can instead call SC.Store#dataSourceDidCancelQuery().  This will set 
-    the query back into the state it was in previously before it started 
+    the query results into an error state.
+
+    If you had to cancel fetching a query before the results were returned,
+    you can instead call SC.Store#dataSourceDidCancelQuery().  This will set
+    the query back into the state it was in previously before it started
     loading the query.
-    
-    h3. Return Values
-    
+
+    ### Return Values
+
     When you return from this method, be sure to return a Boolean.  YES means
     you handled the query, NO means you can't handle the query.  When using
     a cascading data source, returning NO will mean the next data source will
     be asked to fetch the same results as well.
-    
+
     @param {SC.Store} store the requesting store
     @param {SC.Query} query query describing the request
     @returns {Boolean} YES if you can handle fetching the query, NO otherwise
@@ -89,44 +279,44 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   fetch: function(store, query) {
     return NO ; // do not handle anything!
   },
-  
+
   /**
-    Called by the store whenever it needs to load a specific set of store 
+    Called by the store whenever it needs to load a specific set of store
     keys.  The default implementation will call retrieveRecord() for each
-    storeKey.  
-    
-    You should implement either retrieveRecord() or retrieveRecords() to 
+    storeKey.
+
+    You should implement either retrieveRecord() or retrieveRecords() to
     actually fetch the records referenced by the storeKeys .
-    
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKeys
     @param {Array} ids - optional
     @returns {Boolean} YES if handled, NO otherwise
   */
   retrieveRecords: function(store, storeKeys, ids) {
-    return this._handleEach(store, storeKeys, this.retrieveRecord, ids);  
+    return this._handleEach(store, storeKeys, this.retrieveRecord, ids);
   },
-  
+
   /**
-    Invoked by the store whenever it has one or more records with pending 
+    Invoked by the store whenever it has one or more records with pending
     changes that need to be sent back to the server.  The store keys will be
     separated into three categories:
-    
-     - createStoreKeys: records that need to be created on server
-     - updateStoreKeys: existing records that have been modified
-     - destroyStoreKeys: records need to be destroyed on the server
-     
+
+     - `createStoreKeys`: records that need to be created on server
+     - `updateStoreKeys`: existing records that have been modified
+     - `destroyStoreKeys`: records need to be destroyed on the server
+
     If you do not override this method yourself, this method will actually
-    invoke createRecords(), updateRecords(), and destroyRecords() on the 
+    invoke `createRecords()`, `updateRecords()`, and `destroyRecords()` on the
     dataSource, passing each array of storeKeys.  You can usually implement
     those methods instead of overriding this method.
-    
+
     However, if your server API can sync multiple changes at once, you may
     prefer to override this method instead.
-    
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle any of the keys, YES if you can handle all of the keys, or
-    SC.MIXED_STATE if you can handle some of them.
+
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle any of the keys, `YES` if you can handle all of the keys, or
+    `SC.MIXED_STATE` if you can handle some of them.
 
     @param {SC.Store} store the requesting store
     @param {Array} createStoreKeys keys to create
@@ -141,31 +331,31 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
     if (createStoreKeys.length>0) {
       cret = this.createRecords.call(this, store, createStoreKeys, params);
     }
-        
+
     if (updateStoreKeys.length>0) {
-      uret = this.updateRecords.call(this, store, updateStoreKeys, params); 
+      uret = this.updateRecords.call(this, store, updateStoreKeys, params);
     }
-       
+
     if (destroyStoreKeys.length>0) {
       dret = this.destroyRecords.call(this, store, destroyStoreKeys, params);
     }
-     
+
     return ((cret === uret) && (cret === dret)) ? cret : SC.MIXED_STATE;
   },
-  
+
   /**
     Invoked by the store whenever it needs to cancel one or more records that
     are currently in-flight.  If any of the storeKeys match records you are
-    currently acting upon, you should cancel the in-progress operation and 
-    return YES.
-    
+    currently acting upon, you should cancel the in-progress operation and
+    return `YES`.
+
     If you implement an in-memory data source that immediately services the
     other requests, then this method will never be called on your data source.
-    
-    To support cascading data stores, be sure to return NO if you cannot 
-    retrieve any of the keys, YES if you can retrieve all of the, or
-    SC.MIXED_STATE if you can retrieve some of the.
-    
+
+    To support cascading data stores, be sure to return `NO` if you cannot
+    retrieve any of the keys, `YES` if you can retrieve all of the, or
+    `SC.MIXED_STATE` if you can retrieve some of the.
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKeys array of storeKeys to retrieve
     @returns {Boolean} YES if data source can handle keys
@@ -173,74 +363,74 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   cancel: function(store, storeKeys) {
     return NO;
   },
-  
+
   // ..........................................................
   // BULK RECORD ACTIONS
-  // 
-  
+  //
+
   /**
-    Called from commitRecords() to commit modified existing records to the 
-    store.  You can override this method to actually send the updated 
-    records to your store.  The default version will simply call 
-    updateRecord() for each storeKey.
+    Called from `commitRecords()` to commit modified existing records to the
+    store.  You can override this method to actually send the updated
+    records to your store.  The default version will simply call
+    `updateRecord()` for each storeKey.
 
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle any of the keys, YES if you can handle all of the keys, or
-    SC.MIXED_STATE if you can handle some of them.
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle any of the keys, `YES` if you can handle all of the keys, or
+    `SC.MIXED_STATE` if you can handle some of them.
 
     @param {SC.Store} store the requesting store
     @param {Array} storeKeys keys to update
-    @param {Hash} params 
-      to be passed down to data source. originated from the commitRecords() 
+    @param {Hash} params
+      to be passed down to data source. originated from the commitRecords()
       call on the store
 
-    @returns {Boolean} YES, NO, or SC.MIXED_STATE  
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
 
   */
   updateRecords: function(store, storeKeys, params) {
     return this._handleEach(store, storeKeys, this.updateRecord, null, params);
   },
-  
+
   /**
-    Called from commitRecords() to commit newly created records to the 
-    store.  You can override this method to actually send the created 
-    records to your store.  The default version will simply call 
-    createRecord() for each storeKey.
+    Called from `commitRecords()` to commit newly created records to the
+    store.  You can override this method to actually send the created
+    records to your store.  The default version will simply call
+    `createRecord()` for each storeKey.
 
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle any of the keys, YES if you can handle all of the keys, or
-    SC.MIXED_STATE if you can handle some of them.
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle any of the keys, `YES` if you can handle all of the keys, or
+    `SC.MIXED_STATE` if you can handle some of them.
 
     @param {SC.Store} store the requesting store
     @param {Array} storeKeys keys to update
-    
-    @param {Hash} params 
-      to be passed down to data source. originated from the commitRecords() 
+
+    @param {Hash} params
+      to be passed down to data source. originated from the commitRecords()
       call on the store
-    
-    @returns {Boolean} YES, NO, or SC.MIXED_STATE  
-  
+
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
+
   */
   createRecords: function(store, storeKeys, params) {
     return this._handleEach(store, storeKeys, this.createRecord, null, params);
   },
 
   /**
-    Called from commitRecords() to commit destroted records to the 
-    store.  You can override this method to actually send the destroyed 
-    records to your store.  The default version will simply call 
-    destroyRecord() for each storeKey.
+    Called from `commitRecords()` to commit destroted records to the
+    store.  You can override this method to actually send the destroyed
+    records to your store.  The default version will simply call
+    `destroyRecord()` for each storeKey.
 
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle any of the keys, YES if you can handle all of the keys, or
-    SC.MIXED_STATE if you can handle some of them.
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle any of the keys, `YES` if you can handle all of the keys, or
+    `SC.MIXED_STATE` if you can handle some of them.
 
     @param {SC.Store} store the requesting store
     @param {Array} storeKeys keys to update
     @param {Hash} params to be passed down to data source. originated
       from the commitRecords() call on the store
 
-    @returns {Boolean} YES, NO, or SC.MIXED_STATE  
+    @returns {Boolean} YES, NO, or SC.MIXED_STATE
 
   */
   destroyRecords: function(store, storeKeys, params) {
@@ -253,10 +443,10 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   _handleEach: function(store, storeKeys, action, ids, params) {
     var len = storeKeys.length, idx, ret, cur, lastArg;
     if(!ids) ids = [];
-    
+
     for(idx=0;idx<len;idx++) {
       lastArg = ids[idx] ? ids[idx] : params;
-      
+
       cur = action.call(this, store, storeKeys[idx], lastArg, params);
       if (ret === undefined) {
         ret = cur ;
@@ -268,19 +458,19 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
     }
     return ret ? ret : null ;
   },
-  
+
 
   // ..........................................................
   // SINGLE RECORD ACTIONS
-  // 
-  
+  //
+
   /**
-    Called from updatesRecords() to update a single record.  This is the 
+    Called from `updatesRecords()` to update a single record.  This is the
     most basic primitive to can implement to support updating a record.
-    
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle the passed storeKey or YES if you can.
-    
+
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle the passed storeKey or `YES` if you can.
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKey key to update
     @param {Hash} params to be passed down to data source. originated
@@ -292,8 +482,8 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   },
 
   /**
-    Called from retrieveRecords() to retrieve a single record.
-    
+    Called from `retrieveRecords()` to retrieve a single record.
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKey key to retrieve
     @param {String} id the id to retrieve
@@ -304,12 +494,12 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   },
 
   /**
-    Called from createdRecords() to created a single record.  This is the 
+    Called from `createdRecords()` to created a single record.  This is the
     most basic primitive to can implement to support creating a record.
-    
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle the passed storeKey or YES if you can.
-    
+
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle the passed storeKey or `YES` if you can.
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKey key to update
     @param {Hash} params to be passed down to data source. originated
@@ -321,12 +511,12 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   },
 
   /**
-    Called from destroyRecords() to destroy a single record.  This is the 
+    Called from `destroyRecords()` to destroy a single record.  This is the
     most basic primitive to can implement to support destroying a record.
-    
-    To support cascading data stores, be sure to return NO if you cannot 
-    handle the passed storeKey or YES if you can.
-    
+
+    To support cascading data stores, be sure to return `NO` if you cannot
+    handle the passed storeKey or `YES` if you can.
+
     @param {SC.Store} store the requesting store
     @param {Array} storeKey key to update
     @param {Hash} params to be passed down to data source. originated
@@ -335,6 +525,6 @@ SC.DataSource = SC.Object.extend( /** @scope SC.DataSource.prototype */ {
   */
   destroyRecord: function(store, storeKey, params) {
     return NO ;
-  }  
-    
+  }
+
 });