Allow the context to be passed in when registering event listeners

Similar to how backbone.js does it.

docs/CHANGES.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.0.1 (Unreleased)
+- Allow the context (i.e. `this` value) to be passed in when registering event
+  listeners with `converse.listen.on` and `converse.listen.once`. [jcbrand]
+
 ## 2.0.0 (2016-09-16)
 - #656 Online users count not shown initially [amanzur]
 - #674 Polish translation updated [ser]

docs/source/development.rst

@@ -768,7 +768,7 @@ Converse.js emits events to which you can subscribe from your own Javascript.
 Concerning events, the following methods are available under the "listen"
 grouping:
 
-* **on(eventName, callback)**:
+* **on(eventName, callback, [context])**:
 
     Calling the ``on`` method allows you to subscribe to an event.
     Every time the event fires, the callback method specified by ``callback`` will be
@@ -778,6 +778,7 @@ grouping:
 
     * ``eventName`` is the event name as a string.
     * ``callback`` is the callback method to be called when the event is emitted.
+    * ``context`` (optional), the value of the `this` parameter for the callback.
 
     For example:
 
@@ -785,7 +786,7 @@ grouping:
 
         converse.listen.on('message', function (event, messageXML) { ... });
 
-* **once(eventName, callback)**:
+* **once(eventName, callback, [context])**:
 
     Calling the ``once`` method allows you to listen to an event
     exactly once.
@@ -794,6 +795,7 @@ grouping:
 
     * ``eventName`` is the event name as a string.
     * ``callback`` is the callback method to be called when the event is emitted.
+    * ``context`` (optional), the value of the `this` parameter for the callback.
 
     For example:
 

src/converse-api.js

@@ -160,11 +160,11 @@
             }
         },
         'listen': {
-            'once': function (evt, handler) {
-                converse.once(evt, handler);
+            'once': function (evt, handler, context) {
+                converse.once(evt, handler, context);
             },
-            'on': function (evt, handler) {
-                converse.on(evt, handler);
+            'on': function (evt, handler, context) {
+                converse.on(evt, handler, context);
             },
             'not': function (evt, handler) {
                 converse.off(evt, handler);

src/converse-core.js

@@ -65,14 +65,20 @@
             $(event_context).trigger(evt, data);
         },
 
-        once: function (evt, handler) {
+        once: function (evt, handler, context) {
+            if (context) {
+                handler = handler.bind(context);
+            }
             $(event_context).one(evt, handler);
         },
 
-        on: function (evt, handler) {
+        on: function (evt, handler, context) {
             if (_.contains(['ready', 'initialized'], evt)) {
                 converse.log('Warning: The "'+evt+'" event has been deprecated and will be removed, please use "connected".');
             }
+            if (context) {
+                handler = handler.bind(context);
+            }
             $(event_context).bind(evt, handler);
         },