allow $.ev.run to be overridden for those who want more control; loop method signature changed significantly

John Beppu · John Beppu · commit 853a8507a7fc · 2009-09-07T03:50:15.000-07:00
diff --git a/README.textile b/README.textile
@@ -7,22 +7,52 @@ h1. API
 
 h2. Starting and Stopping the Event Loop
 
-h3. $.ev.loop(url, channels)
+h3. $.ev.loop(url, handlers)
+
+*url* - the URL you want to long-poll on.
+
+*handlers* - an object that maps event types to event handlers.
+
+Example:
+
+  $.ev.loop('/comet/channel/foo/2894293942', {
+
+    // ev.type == "backgroundColor"
+    backgroundColor: function(ev) {
+      $('body').css({ backgroundColor: ev.color });
+    },
+
+    // ev.type == "foregroundColor"
+    foregroundColor: function(ev) {
+      $('body').css({ color: ev.color });
+    },
+
+    // ev.type == "debugMessage"
+    debugMessage: function(ev) {
+      console.log(ev.message);
+    }
+
+  });
 
 h3. $.ev.stop()
 
-h2. Adding Event Handlers
+This will stop the long-polling loop.
 
-I took a very low-tech approach to event handlers.  Basically,
-$.ev.handlers is treated as a hash that's keyed by event.type and
-contains functions that will run when events of that type come in.
+Example:
 
-  $.ev.handlers['hello'] = function(ev){ console.log(ev.toSource()) };
+  $.ev.stop();
 
+h2. Event Handlers
 
-h1. Example
+This library makes the assumption that every event from the COMET server
+will be an object with a *type* attribute.  Based on the value of the
+*type* attribute, jQuery.ev will dispatch events to the event handlers.
+
+h1. Code Examples
 
 "http://github.com/beppu/mad-scientists-lab/tree/master/chat/":http://github.com/beppu/mad-scientists-lab/tree/master/chat/
 
+"http://github.com/beppu/stardust/tree/master":http://github.com/beppu/stardust/tree/master
+
 "http://bavl.org:4234/":http://bavl.org:4234/
 
diff --git a/jquery.ev.js b/jquery.ev.js
@@ -1,55 +1,93 @@
+/* Title: jQuery.ev
+ *
+ * A COMET event loop for jQuery
+ *
+ * $.ev.loop long-polls on a URL and expects to get an array of JSON-encoded
+ * objects back.  Each of these objects should represent a message from the COMET
+ * server that's telling your client-side Javascript to do something.
+ *
+ */
 (function($){
 
-  $.ev = $.ev || {
+  $.ev = {
 
     handlers : {},
     running  : false,
     xhr      : null,
     verbose  : true,
+    timeout  : null,
 
-    run: function(events) {
-      var i;
-      for (i = 0; i < events.length; i++) {
-        var e = events[i];
-        if (!e) continue;
-        var h = this.handlers[e.type];
-        if (h) h(e);
+    /* Method: run
+     *
+     * Respond to an array of messages using the object in this.handlers
+     *
+     */
+    run: function(messages) {
+      var i, m, h; // index, event, handler
+      for (i = 0; i < messages.length; i++) {
+        m = messages[i];
+        if (!m) continue;
+        h = this.handlers[m.type];
+        if (!h) h = this.handlers['*'];
+        if ( h) h(m);
       }
     },
 
+    /* Method: stop
+     *
+     * Stop the loop
+     *
+     */
     stop: function() {
-      this.running = false;
       if (this.xhr) {
         this.xhr.abort();
         this.xhr = null;
       }
-      // Maybe it should let the server side know that it stopped listening.
+      this.running = false;
     },
 
-    loop: function(url, channels) {
+    /*
+     * Method: loop
+     *
+     * Long poll on a URL
+     *
+     * Arguments:
+     *
+     *   url
+     *   handler
+     *
+     */
+    loop: function(url, handlers) {
       var self = this;
+      if (handlers) {
+        if (typeof handlers == "object") {
+          this.handlers = handlers;
+        } else if (typeof handlers == "function") {
+          this.run = handlers;
+        } else {
+          throw("handlers must be an object or function");
+        }
+      }
       this.running = true;
-      if (!channels) channels = [];
       this.xhr = $.ajax({
         type     : 'GET',
         dataType : 'json',
         url      : url,
-        data     : { channels: channels },
-        success  : function(events, status) {
-          // self.log('success', events);
-          self.run(events)
+        timeout  : self.timeout,
+        success  : function(messages, status) {
+          // console.log('success', messages);
+          self.run(messages)
         },
         complete : function(xhr, status) {
           var delay;
           if (status == 'success') {
             delay = 100;
           } else {
-            // self.log('status: ' + status, '; waiting before long-polling again...');
+            // console.log('status: ' + status, '; waiting before long-polling again...');
             delay = 5000;
           }
-          window.setTimeout(function(){
-            if (self.running) self.loop(url, channels);
-          }, delay);
+          // "recursively" loop
+          window.setTimeout(function(){ if (self.running) self.loop(url); }, delay);
         }
       });
     }
