Document that event listeners receive event as first arg. Fixes #336

docs/CHANGES.rst

@@ -6,6 +6,7 @@ Changelog
 
 * Set the JID input field in the login form to ``type=email``. [chatme]
 * New configuration setting ``allow_contact_removal``. [jcbrand]
+* Document that event handlers receive 'event' obj as first arg. [jcbrand]
 
 0.9.0 (2015-03-06)
 ------------------

docs/source/development.rst

@@ -401,7 +401,7 @@ grouping:
 
     For example::
 
-        converse.listen.on('message', function (messageXML) { ... });
+        converse.listen.on('message', function (event, messageXML) { ... });
 
 * **once(eventName, callback)**:
 
@@ -415,7 +415,7 @@ grouping:
 
     For example::
 
-        converse.listen.once('message', function (messageXML) { ... });
+        converse.listen.once('message', function (event, messageXML) { ... });
 
 * **not(eventName, callback)**
 
@@ -428,7 +428,7 @@ grouping:
 
     For example::
 
-        converse.listen.not('message', function (messageXML) { ... });
+        converse.listen.not('message', function (event, messageXML) { ... });
 
 Events
 ======
@@ -440,44 +440,44 @@ Event Types
 
 Here are the different events that are emitted:
 
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| Event Type                     | When is it triggered?                                                                             | Example                                                                                 |
-+================================+===================================================================================================+=========================================================================================+
-| **initialized**                | Once converse.js has been initialized.                                                            | ``converse.on('initialized', function () { ... });``                                    |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **ready**                      | After connection has been established and converse.js has got all its ducks in a row.             | ``converse.on('ready', function () { ... });``                                          |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **reconnect**                  | After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode. | ``converse.on('reconnect', function () { ... });``                                      |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **message**                    | When a message is received.                                                                       | ``converse.on('message', function (messageXML) { ... });``                              |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **messageSend**                | When a message will be sent out.                                                                  | ``converse.on('messageSend', function (messageText) { ... });``                         |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **noResumeableSession**        | When keepalive=true but there aren't any stored prebind tokens.                                   | ``converse.on('noResumeableSession', function () { ... });``                            |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roster**                     | When the roster is updated.                                                                       | ``converse.on('roster', function (items) { ... });``                                    |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **callButtonClicked**          | When a call button (i.e. with class .toggle-call) on a chat box has been clicked.                 | ``converse.on('callButtonClicked', function (connection, model) { ... });``             |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxOpened**              | When a chat box has been opened.                                                                  | ``converse.on('chatBoxOpened', function (chatbox) { ... });``                           |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatRoomOpened**             | When a chat room has been opened.                                                                 | ``converse.on('chatRoomOpened', function (chatbox) { ... });``                          |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxClosed**              | When a chat box has been closed.                                                                  | ``converse.on('chatBoxClosed', function (chatbox) { ... });``                           |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxFocused**             | When the focus has been moved to a chat box.                                                      | ``converse.on('chatBoxFocused', function (chatbox) { ... });``                          |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxToggled**             | When a chat box has been minimized or maximized.                                                  | ``converse.on('chatBoxToggled', function (chatbox) { ... });``                          |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roomInviteSent**             | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });``        |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roomInviteReceived**         | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });``        |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **statusChanged**              | When own chat status has changed.                                                                 | ``converse.on('statusChanged', function (status) { ... });``                            |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **statusMessageChanged**       | When own custom status message has changed.                                                       | ``converse.on('statusMessageChanged', function (message) { ... });``                    |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **contactStatusChanged**       | When a chat buddy's chat status has changed.                                                      | ``converse.on('contactStatusChanged', function (buddy, status) { ... });``              |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **contactStatusMessageChanged**| When a chat buddy's custom status message has changed.                                            | ``converse.on('contactStatusMessageChanged', function (buddy, messageText) { ... });``  |
-+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| Event Type                      | When is it triggered?                                                                             | Example                                                                                        |
++=================================+===================================================================================================+================================================================================================+
+| **initialized**                 | Once converse.js has been initialized.                                                            | ``converse.on('initialized', function (event) { ... });``                                      |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **ready**                       | After connection has been established and converse.js has got all its ducks in a row.             | ``converse.on('ready', function (event) { ... });``                                            |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **reconnect**                   | After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode. | ``converse.on('reconnect', function (event) { ... });``                                        |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **message**                     | When a message is received.                                                                       | ``converse.on('message', function (event, messageXML) { ... });``                              |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **messageSend**                 | When a message will be sent out.                                                                  | ``converse.on('messageSend', function (event, messageText) { ... });``                         |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **noResumeableSession**         | When keepalive=true but there aren't any stored prebind tokens.                                   | ``converse.on('noResumeableSession', function (event) { ... });``                              |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **roster**                      | When the roster is updated.                                                                       | ``converse.on('roster', function (event, items) { ... });``                                    |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **callButtonClicked**           | When a call button (i.e. with class .toggle-call) on a chat box has been clicked.                 | ``converse.on('callButtonClicked', function (event, connection, model) { ... });``             |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **chatBoxOpened**               | When a chat box has been opened.                                                                  | ``converse.on('chatBoxOpened', function (event, chatbox) { ... });``                           |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **chatRoomOpened**              | When a chat room has been opened.                                                                 | ``converse.on('chatRoomOpened', function (event, chatbox) { ... });``                          |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **chatBoxClosed**               | When a chat box has been closed.                                                                  | ``converse.on('chatBoxClosed', function (event, chatbox) { ... });``                           |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **chatBoxFocused**              | When the focus has been moved to a chat box.                                                      | ``converse.on('chatBoxFocused', function (event, chatbox) { ... });``                          |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **chatBoxToggled**              | When a chat box has been minimized or maximized.                                                  | ``converse.on('chatBoxToggled', function (event, chatbox) { ... });``                          |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **roomInviteSent**              | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (event, roomview, invitee_jid, reason) { ... });``        |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **roomInviteReceived**          | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (event, roomview, invitee_jid, reason) { ... });``        |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **statusChanged**               | When own chat status has changed.                                                                 | ``converse.on('statusChanged', function (event, status) { ... });``                            |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **statusMessageChanged**        | When own custom status message has changed.                                                       | ``converse.on('statusMessageChanged', function (event, message) { ... });``                    |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **contactStatusChanged**        | When a chat buddy's chat status has changed.                                                      | ``converse.on('contactStatusChanged', function (event, buddy, status) { ... });``              |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+
+| **contactStatusMessageChanged** | When a chat buddy's custom status message has changed.                                            | ``converse.on('contactStatusMessageChanged', function (event, buddy, messageText) { ... });``  |
++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+