sproutcore 1.11.0.rc1 → 1.11.0.rc2

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

@@ -10,15 +10,15 @@ sc_require('mixins/websocket_delegate');
   @class
 
   Implements support for WebSocket.
-  
+
   Example Usage:
 
     var ws = SC.WebSocket.create({
       server: 'ws://server',
     }).connect();
-    
+
     ws.notify(this, 'wsReceivedMessage');
-    
+
     ws.send('message');
 
   @since SproutCore 1.11
@@ -27,7 +27,7 @@ sc_require('mixins/websocket_delegate');
   @author Nicolas BADIA
 */
 SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
-  
+
   /**
     URL of the WebSocket server.
 
@@ -54,9 +54,9 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
   isConnected: false,
 
   /**
-    In order to handle authentification, set `isAuth` to NO in the 
-    `webSocketDidOpen` delegate method just after sending a request to 
-    authentificate the connection. This way, any futher message will be put in 
+    In order to handle authentification, set `isAuth` to NO in the
+    `webSocketDidOpen` delegate method just after sending a request to
+    authentificate the connection. This way, any futher message will be put in
     queue until the server tels you the connection is authentified. Once it
     did, you should set `isAuth` to YES to resume the queue.
 
@@ -64,7 +64,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
 
     @type Boolean
     @default null
-  */  
+  */
   isAuth: null,
 
   /**
@@ -77,7 +77,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
 
   /**
     A WebSocket delegate.
-    
+
     @see SC.WebSocketDelegate
     @type {SC.WebSocketDelegate}
     @default null
@@ -109,7 +109,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
   /**
     Call this method to open a connection.
 
-    @returns {SC.WebSocket} 
+    @returns {SC.WebSocket}
   */
   connect: function() {
     var that = this;
@@ -119,30 +119,30 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     if (!this.isSupported || this.socket) return this;
 
     try {
-      var socket = this.socket = new WebSocket(this.get('server')); 
+      var socket = this.socket = new WebSocket(this.get('server'));
 
       socket.onopen = function() {
-        SC.RunLoop.begin(); 
-        that.onOpen.apply(that, arguments); 
-        SC.RunLoop.end(); 
+        SC.RunLoop.begin();
+        that.onOpen.apply(that, arguments);
+        SC.RunLoop.end();
       };
 
       socket.onmessage = function() {
-        SC.RunLoop.begin(); 
-        that.onMessage.apply(that, arguments); 
-        SC.RunLoop.end(); 
+        SC.RunLoop.begin();
+        that.onMessage.apply(that, arguments);
+        SC.RunLoop.end();
       };
 
       socket.onclose = function() {
-        SC.RunLoop.begin(); 
-        that.onClose.apply(that, arguments); 
-        SC.RunLoop.end(); 
+        SC.RunLoop.begin();
+        that.onClose.apply(that, arguments);
+        SC.RunLoop.end();
       };
 
       socket.onerror = function() {
-        SC.RunLoop.begin(); 
-        that.onError.apply(that, arguments); 
-        SC.RunLoop.end(); 
+        SC.RunLoop.begin();
+        that.onError.apply(that, arguments);
+        SC.RunLoop.end();
       };
     } catch(e) {
       SC.error('An error has occurred while connnecting to the websocket server: '+e);
@@ -153,10 +153,10 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
 
   /**
     Call this method to close a connection.
-    
+
     @param code {Number} A numeric value indicating the status code explaining why the connection is being closed. If this parameter is not specified, a default value of 1000 (indicating a normal "transaction complete" closure) is assumed.
     @param reason {String} A human-readable string explaining why the connection is closing. This string must be no longer than 123 bytes of UTF-8 text (not characters).
-    @returns {SC.WebSocket} 
+    @returns {SC.WebSocket}
   */
   close: function(code, reason) {
     var socket = this.socket;
@@ -169,14 +169,14 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
   },
 
   /**
-    Configures a callback to execute when an event happen. You must pass 
+    Configures a callback to execute when an event happen. You must pass
     at least a target and action/method to this and optionally an event name.
 
     You may also pass additional arguments which will then be passed along to
     your callback.
 
     Example:
-        
+
         var websocket = SC.WebSocket.create({ server: 'ws://server' }).connect();
 
         webSocket.notify('onopen', this, 'wsWasOpen');
@@ -189,24 +189,35 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     Your notification callback should expect to receive the WebSocket object as
     the first parameter and the event or message; plus any additional parameters that you pass. If your callback handles the notification and to prevent further handling, it
     should return YES.
-    
+
     @param target {String} String Event name.
     @param target {Object} The target object for the callback action.
     @param action {String|Function} The method name or function to call on the target.
     @returns {SC.WebSocket} The SC.WebSocket object.
   */
   notify: function(event, target, action) {
-    var args;
+    var args,
+      i, len;
 
     if (SC.typeOf(event) !== SC.T_STRING) {
-      args = SC.A(arguments).slice(2);
+      // Fast arguments access.
+      // Accessing `arguments.length` is just a Number and doesn't materialize the `arguments` object, which is costly.
+      args = new Array(arguments.length - 2); //  SC.A(arguments).slice(2)
+      for (i = 0, len = args.length; i < len; i++) { args[i] = arguments[i + 2]; }
 
       // Shift the arguments
       action = target;
       target = event;
       event = 'onmessage';
     } else {
-      args = SC.A(arguments).slice(3);
+      if (arguments.length > 3) {
+        // Fast arguments access.
+        // Accessing `arguments.length` is just a Number and doesn't materialize the `arguments` object, which is costly.
+        args = new Array(arguments.length - 3); //  SC.A(arguments).slice(3)
+        for (i = 0, len = args.length; i < len; i++) { args[i] = arguments[i + 3]; }
+      } else {
+        args = [];
+      }
     }
 
     var listeners = this.get('listeners');
@@ -214,12 +225,12 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     if(!listeners[event]) { listeners[event] = []; }
 
     //@if(debug)
-    for (var i = listeners[event].length - 1; i >= 0; i--) {
+    for (i = listeners[event].length - 1; i >= 0; i--) {
       var listener = listeners[event][i];
       if (listener.event === event && listener.target === target && listener.action === action) {
         SC.warn("Developer Warning: This listener is already defined.");
       }
-    };
+    }
     //@endif
 
     // Add another listener for the given event name.
@@ -231,14 +242,14 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
   /**
     Send the passed message. If the connection is not yet open or anthentified,
     the message will be put in the queue.
-    
+
     @param message {String|Object} The message to send.
-    @returns {SC.WebSocket} 
+    @returns {SC.WebSocket}
   */
   send: function(message) {
     if (this.isConnected === true && this.isAuth !== false) {
       if (this.isJSON) {
-        var message = JSON.stringify(message);
+        message = JSON.stringify(message);
       }
 
       this.socket.send(message);
@@ -272,9 +283,13 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
   */
   onMessage: function(messageEvent) {
     if (messageEvent) {
-      var message = data = messageEvent.data,
-        del = this.get('objectDelegate'),
-        ret = del.webSocketDidReceiveMessage(this, data);
+      var del = this.get('objectDelegate'),
+        message,
+        data,
+        ret;
+
+      message = data = messageEvent.data;
+      ret = del.webSocketDidReceiveMessage(this, data);
 
       if (ret !== true) {
         if (this.isJSON) {
@@ -299,7 +314,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     this.socket = null;
 
     var ret = del.webSocketDidClose(this, closeEvent);
-    
+
     if (ret !== true) {
       this._notifyListeners('onclose', closeEvent);
       this.tryReconnect();
@@ -310,7 +325,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
      @private
   */
   onError: function(event) {
-    var del = this.get('objectDelegate'), 
+    var del = this.get('objectDelegate'),
       ret = del.webSocketDidError(this, event);
 
     if (ret !== true) this._notifyListeners('onerror', event);
@@ -404,7 +419,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     @default null
   */
   socket: null,
-  
+
   /**
     @private
 
@@ -412,7 +427,7 @@ SC.WebSocket = SC.Object.extend(SC.DelegateSupport, SC.WebSocketDelegate, {
     @default null
   */
   listeners: null,
-  
+
   /**
     @private
 

data/lib/frameworks/sproutcore/frameworks/core_foundation/mixins/action_support.js

@@ -8,73 +8,230 @@
 /**
   @class
 
-  Implements basic target and action support for views.
+  Implements basic target + action support for views. To use, simply set the `action` property on
+  the view to the name of a method handled by an object in the current responder chain and call
+  `fireAction`. If the `target` property is also set, the `action` will only be attempted on that
+  target object. If not set, then the responder chain will be searched for an object that implements
+  the named action.
+
+  *Note* Because searching the responder chain is slower, it is recommended to specify an actual
+  target whenever possible.
+
+  ### Implementing Actions in a Target
+
+  The method signature for target + action implementors is,
+
+      methodName: function (sender, context) {
+        return; // Optional: return a value to the sender.
+      }
+
+  For views implementing `SC.ActionSupport`, the `sender` will always be `this`, which can be useful
+  when an action may be called by multiple views and the target needs to know from which view it was
+  triggered. For example, here is an action that will hide the sender's (any sender's) pane,
+
+      // Hides the pane of the current sender.
+      hidePane: function (sender) {
+        var pane = sender.get('pane');
+        pane.set('isVisible', false);
+      }
+
+  In order to pass additional information to the target, the target's action method may accept a
+  second argument, `context`. This argument will be the value of the same-named `context` argument
+  passed to `fireAction()` of the view. Here is a simple example to help illustrate this,
+
+      // Target
+      var theTargetObject = SC.Object.create({
+
+        theActionMethod: function (sender, context) {
+          console.log("theActionMethod was called at: %@".fmt(context.calledAt))
+        }
+
+      });
+
+      // View with SC.ActionSupport
+      var view = SC.View.create(SC.ActionSupport, {
+        action: 'theActionMethod',
+        target: theTargetObject,
+
+        someEvent: function () {
+          var addedContext = {
+            calledAt: new Date() // Calling specific information to pass to the target.
+          };
+
+          this.fireAction(addedContext);
+        }
+
+      });
 
-  @author Erich Ocean
-  @author Colin Campbell (colin@sproutcore.com)
   @since SproutCore 1.7
 */
 SC.ActionSupport =
 /** @scope SC.ActionSupport.prototype */ {
 
+  //@if(debug)
+  // Provide some debug-only developer warning support.
+  initMixin: function () {
+    if (this.actionContext !== null) {
+      SC.warn("Developer Warning: The `actionContext` property of `SC.ActionSupport` has been deprecated. Please pass the `context` argument to `fireAction()` directly.");
+    }
+  },
+  //@endif
+
   /**
-    The target object to invoke the action on when fireAction() is called.
+    The name of the method to call when `fireAction` is called.
 
-    If you set this target, the action will be called on the target object
-    directly when fireAction() is called. If you leave this property set to
-    null, then the responder chain will be searched for a view that implements
-    the action.
+    This property is used in conjunction with the `target` property to execute a method when
+    `fireAction` is called. If you do not specify a target, then the responder chain will be
+    searched for a view that implements the named action. If you do set a target, then the button
+    will only try to call the method on that target.
 
-    @type Object
-    @default null
-  */
-  target: null,
+    The action method of the target should implement the following signature:
 
-  /**
-    The name of the action you want triggered when fireAction() is called.
+        methodName: function (sender, context) {
+          return; // Optional: return a value to the sender.
+        }
+
+    ### Supporting multiple actions
+
+    The most correct way to handle variable properties in SproutCore is to use a computed property.
+    For example, imagine if the action depended on a property, `isReady`. While we could set
+    `action` accordingly each time prior to calling `fireAction()` like so,
+
+        mouseUp: function () {
+          var isReady = this.get('isReady');
+
+          if (isReady) {
+            this.set('action', 'doReadyAction');
+          } else {
+            this.set('action', 'doNotReadyAction');
+          }
+
+          this.fireAction();
+        }
 
-    This property is used in conjunction with the target property to execute
-    a method when fireAction() is called.
+    This is a bit wasteful (imagine `isReady` doesn't change very often) and leaves `action` in
+    an improper state (i.e. what if `isReady` changes without a call to mouseUp, then `action` is
+    incorrect for any code that may reference it).
 
-    If you do not set a target, then calling fireAction() will cause the
-    responder chain to search for a view that implements the action you name
-    here.  If you set a target, then fireAction() will try to call the
-    method on the target itself.
+    The better approach is to make `action` a computed property dependent on `isReady`.
+
+    For example, the previous example would be better as,
+
+        action: function () {
+          return this.get('isReady') ? 'doReadyAction' : 'doNotReadyAction';
+        }.property('isReady'), // .cacheable() - optional to cache the result (consider memory used to cache result vs. computation time to compute result)
+
+        mouseUp: function () {
+          this.fireAction(); // Fires with current value of `action`.
+        }
 
     @type String
     @default null
   */
   action: null,
 
+  /** @deprecated Version 1.11.0. Please specify `context` argument when calling fireAction method.
+    @type Object
+    @default null
+  */
+  actionContext: null,
+
   /**
-    Will be sent along with the action to provide the context of the action.
-    This is an easy way to include information along with the action.
+    The target to invoke the action on when `fireAction` is called.
+
+    If you set this target, the action will be called on the target object directly when the button
+    is clicked.  If you leave this property set to `null`, then the responder chain will be
+    searched for a view that implements the action when the button is pressed.
+
+    The action method of the target should implement the following signature:
+
+        methodName: function (sender, context) {
+          return; // Optional: return a value to the sender.
+        }
+
+    ### Supporting multiple targets
+
+    The most correct way to handle variable properties in SproutCore is to use a computed property.
+    For example, imagine if the target depended on a property, `isReady`. While we could set
+    `target` accordingly each time prior to calling `fireAction()` like so,
+
+        mouseUp: function () {
+          var isReady = this.get('isReady');
+
+          if (isReady) {
+            this.set('target', MyApp.readyTarget);
+          } else {
+            this.set('target', MyApp.notReadyTarget);
+          }
+
+          this.fireAction();
+        }
+
+    This is a bit wasteful (imagine `isReady` doesn't change very often) and leaves `target` in
+    an improper state (i.e. what if `isReady` changes without a call to mouseUp, then `target` is
+    incorrect for any code that may reference it).
+
+    The better approach is to make `target` a computed property dependent on `isReady`.
+
+    For example, the previous example would be better as,
+
+        target: function () {
+          return this.get('isReady') ? MyApp.readyTarget : MyApp.notReadyTarget;
+        }.property('isReady'), // .cacheable() - optional to cache the result (consider memory used to cache result vs. computation time to compute result)
+
+        mouseUp: function () {
+          this.fireAction(); // Fires with current value of `target`.
+        }
 
     @type Object
     @default null
   */
-  actionContext: null,
+  target: null,
 
    /**
-     Perform the action. If an action parameter is not provided, then
-     the action defaults to the `action` property.
+     Perform the current action on the current target with the given context. If no target is set,
+     then the responder chain will be searched for an object that implements the action.
 
-     @param {String} [action] The action to fire.
+     You can pass the `context` parameter, which is useful in order to provide additional
+     information to the target, such as the current state of the sender when the action was
+     triggered.
 
-     @returns {Boolean} true if successful
-     @returns {Boolean} false otherwise
+     @param {Object} [context] additional context information to pass to the target
+     @returns {Boolean} true if successful; false otherwise
   */
-  fireAction: function(action) {
-    var target = this.get('target') || null,
-        rootResponder = this.getPath('pane.rootResponder');
-
-    if (action === undefined) { action = this.get('action'); }
+  // TODO: remove backwards compatibility for `action` argument
+  fireAction: function (actionOrContext) {
+    var pane = this.get('pane'),
+      rootResponder = pane.get('rootResponder'),
+      action = this.get('action'),
+      context;
+
+    // Normalize arguments.
+    // TODO: Fully deprecate action argument and actionContext property.
+
+    // No argument, use action (above) and actionContext properties.
+    if (actionOrContext === undefined) {
+      context = this.get('actionContext');
+
+    // String argument and no action (above) property, assume action method name. Use argument with actionContext property.
+    } else if (typeof actionOrContext === SC.T_STRING && action == null) {
+      //@if(debug)
+      // Provide some debug-only developer warning support.
+      SC.warn("Developer Warning: The signature of `SC.ActionSupport.prototype.fireAction` has changed. Please set the `action` property on your view and only pass an optional context argument to `fireAction`.");
+      //@endif
+      action = actionOrContext;
+      context = this.get('actionContext');
+
+    // Something else, use action property (above) and context argument.
+    } else {
+      context = actionOrContext;
+    }
 
     if (action && rootResponder) {
-      return rootResponder.sendAction(action, target, this, this.get('pane'), this.get('actionContext'), this);
+      return rootResponder.sendAction(action, this.get('target'), this, pane, context, this);
     }
 
     return false;
   }
 
-};
+};