sproutcore 1.11.0.rc2 → 1.11.0.rc3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZDA3N2VhZDM4N2JjNjQyMzFiMzM5MWQ5OTc1MDkyZWJmNjU2OWRkMg==
+    MzljNWViZTUxOTllNmJmYjllOWU4MmMyMTk4Mzk5YjhiM2MyM2JjYw==
   data.tar.gz: !binary |-
-    Y2EzNWNiN2M0NzI2OTYyM2UzN2M4MDQ0ZTMyNzQ2Mzc2Y2U1OTY4Yg==
+    OWM0MmI4YmIwMGQ4ZTM2NmFhOTk1NTRmZWQ2ZjFmYzJmZWY3NTk0Yw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    YTRjNzY4ZjRkYjZiYjBiZjU0MjI2NGI4ZmE4ZTYzMzE3MDNiNjJhYzk0OWE0
-    NzhhN2MxNWQ5NzAwNzU3OTlhOGM1YjFlZTY0ODg2ZTE0ZTI0MTczMWQyZWVh
-    MThmNjc5MjMxYzBmYzVkZTE5OWZmZjNiMzhkNGZjM2UyZjQ4OWM=
+    ZDlkNzk0OWMyZTNjYzk2NjdlZmZmYjdkMmZjNjQ2ZGI4N2NhOWEzZmNhZTg5
+    YjA2OTQxMjVjNTc2OWYxOGI2ZWEyN2U1OTIwMmU5NDkwNWMzYWRlMTVkODcx
+    ZTgxNzI0MWIxMTU2NmRjYzIwMjJjOTEzMjI2OTMzNjNkNmQ2YzQ=
   data.tar.gz: !binary |-
-    MDc1MGQzMWM1YzljMDJhNTcyZGFlMjQwNDQxZDI5ZGMzZjg3M2FmN2UyNzZm
-    YjZmZGQ4YjA0NjU0OGYxMjZkOGI3ZDZjOGVhZmU5NDFmMjczMzdmOWZmNmNi
-    MDAwMzQ0NjJjNDEyMGNhYjc5NDhmNDIxYTBmMDhkYTBlZjMzZDE=
+    NDQyZGYxMTMxMTQ1YmJjZjZlMGZmZDNjNGQyZDE4MGYyMzhiZWViNWE5Mjdi
+    MjhjODE1N2M0ZDE1NTY1NGI4YTc4MTVkNTljMmNmOTIxZTVlMzIwODNkMjYy
+    N2Q2M2ZhZTM5ZGNkMTVlMzcyNTc1NGM4NGE2NGI4YzlhMDBiZmI=

data/CHANGELOG

@@ -1,3 +1,13 @@
+SproutCore 1.11.0.rc3
+-----------------
+
+* Updated the dependency requirements for compass, haml & sass to avoid exceptions running on Ruby 2.
+
+SproutCore 1.11.0.rc2
+-----------------
+
+* No changes.
+
 SproutCore 1.11.0.rc1
 -----------------
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 ---
 :major: 1
 :minor: 11
-:patch: 0.rc2
+:patch: 0.rc3

data/lib/frameworks/sproutcore/CHANGELOG.md

@@ -1,6 +1,120 @@
 CHANGE LOG
 ==========
 
+Edge
+-----------
+
+### NEW FEATURES
+### CHANGES & IMPROVEMENTS
+### DEPRECATIONS & REMOVALS
+### BUG FIXES
+
+1.11.0.rc3
+-----------
+
+### NEW FEATURES
+
+* *SC.NestedStore*  
+
+`SC.NestedStore` has a new property, `conflictedStoreKeys`, which is an array of all store keys that currently have conflicts with the nested store's parent. A conflict in a nested store can occur when the data in the parent store changes *after* the nested store has accessed and modified it.  
+
+For instance, in a multi-user system where records can be edited by multiple people at the same time, the client may use polling or websockets to update the records in the main store asynchronously in the background. With such a scenario it would be possible for the current user to be editing a record that someone else has changed in the meantime. If the client attempted to commit the changes from the nested store it would get an exception because of the conflict. Instead, the developer can now check the value of `conflictedStoreKeys` and if it is `null`, then commit the changes and if it is an array of store keys, then they know which records have conflicts and can deal with them directly.
+
+* *SC.Binding*  
+
+There are two new binding transforms, `string` and `integer`, that ensure the value is *always* a `String` or an integer `Number`. Examples include returning an empty `String` for `null` or `undefined` values when using the `string` transform and returning a 0 for these same values when using the `integer` transform. Furthermore, if the `integer` transform is given a String, it will be parsed to an integer `Number` according to the extra argument `radix` (which is 10 by default).
+
+There is also a new binding transform, `mix`, that allows for the aggregation of multiple bound properties into a single property through a given function. It is often the case that a single property depends on two or more bound properties in a complex manner that isn't handled by the current `and` and `or` transforms. To handle this situation previously, the developer would need to write the code to bind in the external property values and then make a local computed property dependent on each of these. The `mix` transform does exactly the same thing, but with less typing on the developer's part.  
+
+For example, to create a mix binding that concatenates two external properties in a non-trivial way, we can now do the following,  
+
+    currentGroupUserLabel: SC.LabelView.extend({
+
+      // Ex. Returns one of "", "Selected Group", or "Selected Group: Selected User"
+      valueBinding: SC.Binding.mix(
+        'MyApp.groupController.name', // The group name (may be null).
+        'MyApp.userController.fullName', // The user full name (may be null).
+
+        // Aggregate function. The arguments match the bound property values above.
+        function (groupName, userFullName) {
+          if (SC.none(userFullName)) {
+            if (SC.none(groupName)) {
+              return ''; // No group and no user. Ex. ""
+            } else {
+              return groupName; // Just a group. Ex. "Selected Group"
+            }
+          } else {
+            return '%@: %@'.fmt(groupName, userFullName); // Group and user. Ex. "Selected Group: Selected User"
+          }
+        })
+
+    })
+
+* *Updated Description* Scale is now a first-class layout property, correctly impacting `frame` and `clippingFrame`. If a view is scaled, the width & height of the frame will be correct as the view appears. For example, a view with layout equal to `{ width: 100, height: 100, scale: 2 }` will report a frame of `{ x: 0, y: 0, width: 200, height: 200, scale: 2 }`. The scale also takes a scaling origin into account as well and as part of this change, there are two new layout properties: `transformOriginX` and `transformOriginY`, which define the percentage (between 0.0 and 1.0) on the respective axis about which the scale transform is applied. These properties affect all transform styles and so can be used to also change the origin of a rotate style.  
+
+### CHANGES & IMPROVEMENTS
+
+* Documentation  
+
+** Added lots of documentation to `SC.Request` (examples), `SC.Query` (local vs. remote) and `SC.DateTime` (`adjust` and `advance`). 
+** Cleaned up documentation of all protocols, including a warning not to mix in protocols and fixed some problems that prevented some protocols from being properly generated on docs.sproutcore.com.
+** Added `SC.ObjectMixinProtocol` with documentation on using mixins with `SC.Object` as well as the methods `initMixin` and  `destroyMixin` that are supported.
+** Added documentation on touch event handling to `SC.ResponderProtocol` (i.e. the protocol that may be implemented by `SC.Responder` subclasses like `SC.View`).
+** Added/improved documentation on `SC.Gesturable` mixin.
+
+* SC.PickerPane  
+
+This view has been given special behavior when used with SC.View's `transitionIn` plugin support. If the plugin defines `layoutProperties` of either `scale` or `rotate`, then the picker will adjust its transform origin X & Y position to appear to scale or rotate out of the anchor. The result is a very nice effect that picker panes appear to pop out of their anchors.  
+To see it in effect, simply set the `transitionIn` property of the pane to one of `SC.View.SCALE_IN` or `SC.View.POP_IN`.
+
+* SC.SegmentedView  
+
+This view was refactored slightly to remove the special overflow view if `shouldHandleOverflow` is `false` (default). Previously the overflow view was always created and appended even if it was not to be used.  
+
+* The automatically adjusted size component of the layouts of `SC.ListView` and `SC.GridView` have changed to set `height` and `width` instead of `minHeight` and `minWidth` (as it applies). The reason for this change is so that the entire list of items can be GPU accelerated by setting `wantsAcceleratedLayer: true` on the view. GPU accelerated positioning using the `translateX` and `translateY` transforms requires that the view have a fixed position (top & left) and a fixed size (height & width). These views already have a fixed position by default and now by having them adjust their `height` or `width` (depending on the direction), it is possible to accelerate these views by also fixing the other size component (i.e. if the list scrolls vertically, the list will set its height, so the developer needs to set the lists width to a fixed value and then add `wantsAcceleratedLayer: true`).  
+
+Test Results:
+
+    With min-height (i.e. can't accelerate):       With height (and accelerated):
+
+      JS Function:       ~5.9ms                      JS Function:       ~5.9ms
+      Recalc. Style:     ~0.3ms                      Recalc. Style:     ~0.3ms
+      Layout:            ~0.3ms                      Update Layer Tree: ~0.2ms
+      Update Layer Tree: ~0.2ms                      Composite Layers:  ~0.3ms
+      Paint:             ~2.4ms
+      Composite Layers:  ~0.3ms
+      Update Layer Tree: ~0.1ms
+      Paint x 8:         ~6.0ms
+
+*How does this affect your code?*  
+Because lists and grids have an implied layout of `{ top: 0, bottom: 0, left: 0, right: 0 }`, they used to always stretch to fill their parent containing view. This is no longer the case and so a collection with too few items to fill the containing view will only be as tall or as wide as its items warrant. This will affect any background styles that were applied to the collection (such as the Ace theme did), which previously would have covered the whole containing view's background. Unfortunately, those background styles need to be moved to the style of the containing view in order to prevent any styling regressions after updating to this new version.  
+
+Therefore, to go along with this change the `background: white` style in the Ace theme that was applied to `$theme.collection` has been moved to `$theme.sc-scroll-view`. It has also been changed to `background-color: white`, which is less likely to conflict with other background styles.  
+
+*How do I check for style regressions?*  
+To ensure that any background styles applied to your collections still look correct, you should do a search through your stylesheets for `.collection` and move any custom background styles over to an `.sc-scroll-view` class.
+
+* The SC.Binding transforms `and` and `or` have been refactored to use the new `mix` code. This means that you can now pass more than two property paths to these transforms.  
+
+For example,  
+
+    isEnabledBinding: SC.Binding.and('.hasValue', '.valueIsValid', '.userIsAllowed')
+
+### DEPRECATIONS & REMOVALS
+
+* The `isPaneAttached` property of SC.Pane has been deprecated. This property is identical to the existing `isAttached` property of SC.View that SC.Pane extends and so `isPaneAttached` is not needed. Please use `isAttached` instead.  
+
+Note: This deprecation will show a console warning in debug (i.e. non-production) mode.
+
+### BUG FIXES
+
+* Added code to prevent a possible issue that could occur when animating to an implied layout position. For instance, if a view has a layout set to `{ top: 5 }`, the implied layout is actually `{ top: 5, right: 0, bottom: 0, left: 0 }`. The issue that could arise is if the code tried to animate to an implied value (ex. `view.animate('left', 0, { duration: 1 }, callbackFunc)`), the animation wouldn't actually need to run and the callback function would fail to fire.
+* Fixed possible issues that may occur when code altered child views in any of the view state callback functions: `didCreateLayer`, `didAppendToDocument`, `didHideInDocument`, `didShowInDocument`. The issue was that the callback functions were called on the parent before the child was updated to the proper new state. For example, if a developer set the visibility of a child view to false in `didCreateLayer`, at that point the child view would have still been in an unrendered state and optimizations preventing visibility changes to unrendered views would have meant the visibility change would have been lost.
+* Fixed an issue that could occur when using temporary IDs with newly created records. Because the `id` property is a computed property, once it has been read (i.e. `myNewRecord.get('id')`), it will remain cached for any further reads. This can become an issue in situations where the ID of the record changes after being saved to the server. For instance, a new record may be given a temporary ID when it is created and the temporary id may be accessed via `get`. After that record is saved to the server, a call to `store.dataSourceDidComplete(RecordType, newBody, newBody.id)` would properly update the `id` value in the store, but would fail to clear the record instance's cache of `id`. Therefore, a successive call to `get('id')` would return the old value.
+* Fixed an issue with observing the `selection` property of `SC.TextFieldView`. Since the `input` element doesn't update its `selectionStart` and `selectionEnd` values until after the event execution completes, the mouse and keypress event handlers that affect the selection must wait until after the run loop before notifying that the selection property has changed.
+* `SC.RootResponder` mistook two successive mousedown events at the same point as a double click even if the target of the second mousedown was different. The result was that if a view moved suddenly on a first click, a second immediate click at the same point would try to call `doubleClick` on the new target view instead of just `mouseUp`.
+* Fixed a regression in SC.CollectionView that prevented double clicks from triggering the action. Closes #1304 & #1305.
+
 1.11.0.rc2
 -----------
 
@@ -75,7 +189,6 @@ These new properties can be used by an `SC.Response` subclass to include allowin
 
 ### CHANGES & IMPROVEMENTS
 
-* Scale is now a first-class layout function, correctly impacting frame and clippingFrame. As a result, scaled content within a CollectionView will now correctly calculate which item views should be currently visible.
 * SC.ScrollView complete refactor:
   * If `horizontalOverlay` or `verticalOverlay` is true, it will use `SC.OverlayScrollerView` by default. It's no longer necessary to also set `horizontalScrollerView: SC.OverlayScrollerView` in order to get overlaid scrollers.
   * Use SC.ScrollView's horizontalAlign and verticalAlign properties to align fixed-width or -height content.

data/lib/frameworks/sproutcore/apps/showcase/views/views_item_view.js

@@ -54,13 +54,7 @@ Showcase.ViewsItemView = SC.View.extend({
   exampleBox: SC.ContainerView.design({
     classNames: ['example-box'],
     layoutBinding: SC.Binding.oneWay('.parentView.exampleLayout'),
-    nowShowingBinding: SC.Binding.oneWay('.parentView.content.exampleView'),
-    replaceContent: function(newContent) {
-      // SC.ContainerView needs its awake function to be called to be correctly initialized.
-      newContent.awake();
-
-      sc_super();
-    }
+    nowShowingBinding: SC.Binding.oneWay('.parentView.content.exampleView')
   }),
 
   supportButton: SC.ButtonView.design({

data/lib/frameworks/sproutcore/apps/showcase/views/views_list_view.js

@@ -14,24 +14,24 @@ Showcase.ViewsListView = SC.ListView.extend({
 
     classNames: ['views-list-view'],
 
-    customRowHeightIndexes: function() {
+    customRowSizeIndexes: function() {
       var content = this.get('content'),
-          customRowHeightIndexes = SC.IndexSet.create();
+          customRowSizeIndexes = SC.IndexSet.create();
 
       for (var i = content.get('length') - 1; i >= 0; i--) {
         if (content.objectAt(i).get('isShowingSnippet')) {
-          customRowHeightIndexes.add(i, 1);
+          customRowSizeIndexes.add(i, 1);
         }
       }
 
-      return customRowHeightIndexes;
-    }.property().idempotent(),
+      return customRowSizeIndexes;
+    }.property(),
 
     exampleHeight: 120,
 
     exampleView: Showcase.ViewsItemView,
 
-    itemHeight: function() {
+    rowSize: function() {
       var exampleHeight = this.get('exampleHeight');
 
       return exampleHeight + 120;
@@ -45,8 +45,8 @@ Showcase.ViewsListView = SC.ListView.extend({
       return null; // select all
     },
 
-    contentIndexRowHeight: function(view, content, contentIndex) {
-      return this.get('rowHeight') + 180;
+    contentIndexRowSize: function(view, content, contentIndex) {
+      return this.get('rowSize') + 180;
     },
 
     createItemView: function(exampleClass, idx, attrs) {
@@ -61,7 +61,7 @@ Showcase.ViewsListView = SC.ListView.extend({
 
       var content = this.content;
       for (var i = content.get('length') - 1; i >= 0; i--) {
-        content.objectAt(i).addObserver('isShowingSnippet', this, this._sclv_customRowHeightIndexesDidChange);
+        content.objectAt(i).addObserver('isShowingSnippet', this, this._sc_customRowSizeIndexesContentDidChange);
       }
     }
 

data/lib/frameworks/sproutcore/frameworks/ajax/system/request.js

@@ -10,13 +10,175 @@ sc_require('system/response');
 /**
   @class
 
-  Implements support for Ajax requests using XHR, XHR 2 and other protocols.
+  Implements support for AJAX requests using XHR, XHR2 and other protocols.
 
-  SC.Request is much like an inverted version of the request/response objects
-  you receive when implementing HTTP servers.
+  SC.Request is essentially a client version of the request/response objects you receive when
+  implementing HTTP servers.
 
-  To send a request, you just need to create your request object, configure
-  your options, and call send() to initiate the request.
+  To send a request, you just need to create your request object, configure your options, and call
+  `send()` to initiate the request. The request will be added to the pending request queue managed
+  by `SC.Request.manager`.
+
+  For example,
+
+      // Create a simple XHR request.
+      var request = SC.Request.create();
+      request.set('address', resourceAddress);
+      request.set('type', 'GET');
+      request.send();
+
+  The previous example will create an XHR GET request to `resourceAddress`. Because the `address`
+  and `type` of the request must be set on every request, there are helper methods on `SC.Request`
+  that you will likely use in every situation.
+
+  For example, the previous example can be written more concisely as,
+
+      // Create a simple XHR request.
+      var request = SC.Request.getUrl(resourceAddress);
+
+  There are four other helper methods to cover the other common HTTP method types: `POST`, `DELETE`,
+  `PUT` and `PATCH`, which are `postUrl`, `deleteUrl`, `putUrl` and `patchUrl` respectively. Since
+  you may also send a body with `POST`, `PUT` and `PATCH` requests, those helper methods also take a
+  second argument `body` (which is analogous to calling `request.set('body', body)`).
+
+  ## Responses
+
+  ### XHR Requests & Custom Communication Protocols
+
+  By default, the request will create an instance of `SC.XHRResponse` in order to complete the
+  request. As the name implies, the `SC.XHRResponse` class will make an XHR request to the server,
+  which is the typical method that the SproutCore client will communicate with remote endpoints.
+
+  In order to use a custom response type handler, you should extend `SC.Response` and set the
+  `responseClass` of the request to your custom response type.
+
+  For example,
+
+      var request = SC.Request.getUrl(resourceAddress).set('responseClass', MyApp.CustomProtocolResponse);
+
+
+  ### Handling Responses
+
+  `SC.Request` supports multiple response handlers based on the status code of the response. This
+  system is quite intelligent and allows for specific callbacks to handle specific status codes
+  (e.g. 404) or general status codes (e.g. 400) or combinations of both. Callbacks are registered
+  using the `notify` method, which accepts a `target` and a `method` which will be called when the
+  request completes. The most basic example of registering a general response handler would be like
+  so,
+
+      // The response handler target (typically a state or controller or some such SC.Object instance).
+      var targetObject;
+
+      targetObject = SC.Object.create({
+
+        handleResponse: function (response) {
+          // Handle the various possible status codes.
+          var status = response.get('status');
+          if (status === 200) { // 200 OK
+            // Do something.
+          } else if (status < 400) { // i.e. 3xx
+            // Do something.
+          } else ...
+        }
+
+      });
+
+
+      // Create a simple XHR request.
+      var request;
+
+      request = SC.Request.getUrl(resourceAddress)
+                          .notify(targetObject, 'handleResponse')
+                          .send();
+
+  However, this approach requires that every response handler be able to handle all of the possible
+  error codes that we may be able to handle in a more general manner. It's also more code for us
+  to write to write all of the multiple condition statements. For this reason, the `notify` method
+  accepts an optional status code argument *before* the target and method. You can use a generic
+  status code (i.e. 400) or a specific status code (i.e. 404). If you use a generic status code, all
+  statuses within that range will result in that callback being used.
+
+  For example, here is a more specific example,
+
+      // The response handler target (typically a data source or state or some such SC.Object instance).
+      var targetObject;
+
+      targetObject = SC.Object.create({
+
+        gotOK: function (response) { // 2xx Successful
+          // Do something.
+
+          return true; // Return true to ensure that any following generic handlers don't run!
+        },
+
+        gotForbidden: function (response) { // 403 Forbidden
+          // Do something.
+
+          return true; // Return true to ensure that any following generic handlers don't run!
+        },
+
+        gotUnknownError: function (response) { // 3xx, 4xx (except 403), 5xx
+          // Do something.
+        }
+
+      });
+
+
+      // Create a simple XHR request.
+      var request;
+
+      request = SC.Request.getUrl(resourceAddress)
+                          .notify(200, targetObject, 'gotOK')
+                          .notify(403, targetObject, 'gotForbidden')
+                          .notify(targetObject, 'gotUnknownError')
+                          .send();
+
+  Please note that the notifications will fall through in the order they are added if not handled.
+  This means that the generic handler `gotUnknownError` will be called for any responses not caught
+  by the other handlers. In this example, to ensure that `gotUnknownError` doesn't get called when a
+  2xx or 403 response comes in, those handlers *return `true`*.
+
+  Please also note that this design allows us to easily re-use handler methods. For example, we may
+  choose to have `gotUnknownError` be the standard last resort fallback handler for all requests.
+
+  For more examples, including handling of XHR2 progress events, please @see SC.Request.prototype.notify.
+
+  ### Response Bodies & JSON Decoding
+
+  The body of the response is the `body` property on the response object which is passed to the
+  notify target method. For example,
+
+      gotOK: function (response) { // 2xx Successful
+        var body = response.get('body');
+
+        // Do something.
+
+        return true; // Return true to ensure that any following generic handlers don't run!
+      },
+
+  The type of the body will depend on what the server returns, but since it will typically be JSON,
+  we have a built-in option to have the body be decoded into a JavaScript object automatically by
+  setting `isJSON` to true on the request.
+
+  For example,
+
+      // Create a simple XHR request.
+      var request;
+
+      request = SC.Request.getUrl(resourceAddress)
+                          .set('isJSON', true)
+                          .notify(200, targetObject, 'gotOK')
+                          .send();
+
+  There is a helper method to achieve this as well, `json()`,
+
+      // Create a simple XHR request.
+      var request;
+
+      request = SC.Request.getUrl(resourceAddress)
+                          .json() // Set `isJSON` to true.
+                          .notify(200, targetObject, 'gotOK')
+                          .send();
 
   @extends SC.Object
   @extends SC.Copyable

data/lib/frameworks/sproutcore/frameworks/ajax/system/response.js

@@ -6,15 +6,24 @@
 // ==========================================================================
 /*global ActiveXObject */
 
-/*
-  TODO Document SC.Response and SC.XHRResponse
-*/
-
 /**
   @class
 
-  A response represents a single response from a server request.  An instance
-  of this class is returned whenever you call SC.Request.send().
+  A response represents a single response from a server request and handles the communication to
+  the server.  An instance of this class is returned whenever you call `SC.Request.send()`.
+
+  SproutCore only defines one concrete subclass of `SC.Response`,`SC.XHRResponse`. In order to
+  use `SC.Request` with a non-XHR request type you should create a custom class that extends
+  `SC.Response` and set your custom class as the value of `responseClass` on all requests.
+
+  For example,
+
+      var request = SC.Request.getUrl(resourceAddress)
+                              .set('responseClass', MyApp.CustomProtocolResponse)
+                              .send();
+
+  To extend `SC.Response`, please look at the property and methods listed below. For more examples,
+  please look at the code in `SC.XHRResponse`.
 
   @extend SC.Object
   @since SproutCore 1.0
@@ -168,6 +177,7 @@ SC.Response = SC.Object.extend(
   */
   body: function() {
     // TODO: support XML
+    // TODO: why not use the content-type header?
     var ret = this.get('encodedBody');
     if (ret && this.get('isJSON')) {
       try {
@@ -429,8 +439,14 @@ SC.Response = SC.Object.extend(
 /**
   @class
 
-  Concrete implementation of SC.Response that implements support for using
-  XHR requests.
+  Concrete implementation of `SC.Response` that implements support for using XHR requests. This is
+  the default response class that `SC.Request` uses and it is able to create cross-browser
+  compatible XHR requests to the address defined on a request and to notify according to the status
+  code fallbacks registered on the request.
+
+  You will not typically deal with this class other than to receive an instance of it when handling
+  `SC.Request` responses. For more information on how to create a request and handle an XHR response,
+  please @see SC.Request.
 
   @extends SC.Response
   @since SproutCore 1.0