From 77137a538cd9e79b288491ba492819b1e37733de Mon Sep 17 00:00:00 2001 From: JC Brand Date: Mon, 16 Mar 2015 10:40:00 +0100 Subject: [PATCH] Document that event listeners receive event as first arg. Fixes #336 --- docs/CHANGES.rst | 1 + docs/source/development.rst | 88 ++++++++++++++++++------------------- 2 files changed, 45 insertions(+), 44 deletions(-) diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index cf3982dce..17ccd6be6 100644 --- a/docs/CHANGES.rst +++ b/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) ------------------ diff --git a/docs/source/development.rst b/docs/source/development.rst index e75e50c5d..bceddb612 100644 --- a/docs/source/development.rst +++ b/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) { ... });`` | ++---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+