events.rst 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558
  1. .. raw:: html
  2. <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
  3. .. _`events-API`:
  4. Events and promises
  5. ===================
  6. Converse and its plugins emit various events which you can listen to via the
  7. :ref:`listen-grouping`.
  8. Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
  9. although not all of them could logically act as promises, since some events
  10. might be fired multpile times whereas promises are to be resolved (or
  11. rejected) only once.
  12. The core events, which are also promises are:
  13. * `cachedRoster`_
  14. * `chatBoxesFetched`_
  15. * `controlboxInitialized`_ (only via the `converse-controlbox` plugin)
  16. * `pluginsInitialized`_
  17. * `roomsPanelRendered`_ (only via the `converse-muc` plugin)
  18. * `rosterContactsFetched`_
  19. * `rosterGroupsFetched`_
  20. * `rosterInitialized`_
  21. * `roster`_
  22. * `statusInitialized`_
  23. For more info on how to use (or add promises), you can read the
  24. :ref:`promises-grouping` in the API documentation.
  25. Below we will now list all events and also specify whether they are available
  26. as promises.
  27. List of global events (and promises)
  28. ------------------------------------
  29. Hooking into events that Converse.js emits is a great way to extend or
  30. customize its functionality.
  31. From version 3.0.0 and up, it's only possible to register event handlers inside
  32. a plugin, by using the closured ``_converse`` object. When writing a plugin,
  33. remember that it will also have to be whitelisted, before it will be loaded.
  34. Refer to the :ref:`whitelisted_plugins` setting.
  35. Here follows the different events that are emitted:
  36. afterMessagesFetched
  37. ~~~~~~~~~~~~~~~~~~~~
  38. Emitted whenever a chatbox has fetched its messages from ``sessionStorage`` and
  39. **NOT** from the server.
  40. This event is listened to by the ``converse-mam`` plugin to know when it can
  41. fetch archived messages from the server.
  42. The event handler is passed the ``Backbone.View`` instance of the relevant chat
  43. box.
  44. ``_converse.api.listen.on('afterMessagesFetched', function (chatboxview) { ... });``
  45. .. _`cachedRoster`:
  46. cachedRoster
  47. ~~~~~~~~~~~~
  48. The contacts roster has been retrieved from the local cache (`sessionStorage`).
  49. ``_converse.api.listen.on('cachedRoster', function (items) { ... });``
  50. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  51. .. code-block:: javascript
  52. _converse.api.waitUntil('cachedRoster').then(function () {
  53. // Your code here...
  54. });
  55. See also the `roster`_ event further down.
  56. callButtonClicked
  57. ~~~~~~~~~~~~~~~~~
  58. When a call button (i.e. with class .toggle-call) on a chatbox has been clicked.
  59. ``_converse.api.listen.on('callButtonClicked', function (connection, model) { ... });``
  60. .. _`chatBoxesFetched`:
  61. chatBoxesFetched
  62. ~~~~~~~~~~~~~~~~
  63. Any open chatboxes (from this current session) has been retrieved from the local cache (`sessionStorage`).
  64. You should wait for this event or promise before attempting to do things
  65. related to open chatboxes.
  66. ``_converse.api.listen.on('chatBoxesFetched', function (items) { ... });``
  67. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  68. .. code-block:: javascript
  69. _converse.api.waitUntil('chatBoxesFetched').then(function () {
  70. // Your code here...
  71. });
  72. chatBoxInitialized
  73. ~~~~~~~~~~~~~~~~~~
  74. When a chatbox has been initialized. Relevant to converse-chatview.js plugin.
  75. ``_converse.api.listen.on('chatBoxInitialized', function (chatbox) { ... });``
  76. chatBoxOpened
  77. ~~~~~~~~~~~~~
  78. When a chatbox has been opened. Relevant to converse-chatview.js plugin.
  79. ``_converse.api.listen.on('chatBoxOpened', function (chatbox) { ... });``
  80. chatRoomOpened
  81. ~~~~~~~~~~~~~~
  82. When a chatroom has been opened. Relevant to converse-chatview.js plugin.
  83. ``_converse.api.listen.on('chatRoomOpened', function (chatbox) { ... });``
  84. chatBoxClosed
  85. ~~~~~~~~~~~~~
  86. When a chatbox has been closed. Relevant to converse-chatview.js plugin.
  87. ``_converse.api.listen.on('chatBoxClosed', function (chatbox) { ... });``
  88. chatBoxFocused
  89. ~~~~~~~~~~~~~~
  90. When the focus has been moved to a chatbox. Relevant to converse-chatview.js plugin.
  91. ``_converse.api.listen.on('chatBoxFocused', function (chatbox) { ... });``
  92. chatBoxToggled
  93. ~~~~~~~~~~~~~~
  94. When a chatbox has been minimized or maximized. Relevant to converse-chatview.js plugin.
  95. ``_converse.api.listen.on('chatBoxToggled', function (chatbox) { ... });``
  96. clearSession
  97. ~~~~~~~~~~~~
  98. Called when the user is logging out and provides the opportunity to remove session data.
  99. connected
  100. ~~~~~~~~~
  101. After connection has been established and converse.js has got all its ducks in a row.
  102. ``_converse.api.listen.on('connected', function () { ... });``
  103. contactRequest
  104. ~~~~~~~~~~~~~~
  105. Someone has requested to subscribe to your presence (i.e. to be your contact).
  106. The `Backbone.Model <http://backbonejs.org/#Model>`_ instance representing the
  107. roster contact is passed to the event listener.
  108. ``_converse.api.listen.on('contactRequest', function (contact) { ... });``
  109. contactRemoved
  110. ~~~~~~~~~~~~~~
  111. The user has removed a contact.
  112. ``_converse.api.listen.on('contactRemoved', function (data) { ... });``
  113. contactPresenceChanged
  114. ~~~~~~~~~~~~~~~~~~~~~~
  115. When a chat buddy's presence status has changed.
  116. The presence status is either `online`, `offline`, `dnd`, `away` or `xa`.
  117. ``_converse.api.listen.on('contactPresenceChanged', function (presence) { ... });``
  118. contactStatusMessageChanged
  119. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  120. When a chat buddy's custom status message has changed.
  121. ``_converse.api.listen.on('contactStatusMessageChanged', function (data) { ... });``
  122. controlboxInitialized
  123. ~~~~~~~~~~~~~~~~~~~~~
  124. Called when the controlbox has been initialized and therefore exists.
  125. The controlbox contains the login and register forms when
  126. the user is logged out and a list of the user's contacts and group chats when
  127. logged in.
  128. ``_converse.api.listen.on('controlboxInitialized', function () { ... });``
  129. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  130. .. code-block:: javascript
  131. _converse.api.waitUntil('controlboxInitialized').then(function () {
  132. // Your code here...
  133. });
  134. discoInitialized
  135. ~~~~~~~~~~~~~~~~
  136. Emitted once the ``converse-disco`` plugin has been initialized and the
  137. ``_converse.disco_entities`` collection will be available and populated with at
  138. least the service discovery features of the user's own server.
  139. ``_converse.api.listen.on('discoInitialized', function () { ... });``
  140. disconnected
  141. ~~~~~~~~~~~~
  142. After converse.js has disconnected from the XMPP server.
  143. ``_converse.api.listen.on('disconnected', function () { ... });``
  144. initialized
  145. ~~~~~~~~~~~
  146. Once converse.js has been initialized.
  147. ``_converse.api.listen.on('initialized', function () { ... });``
  148. See also `pluginsInitialized`_.
  149. logout
  150. ~~~~~~
  151. The user has logged out.
  152. ``_converse.api.listen.on('logout', function () { ... });``
  153. messageAdded
  154. ~~~~~~~~~~~~
  155. Once a message has been added to a chatbox. The passed in data object contains
  156. a `chatbox` attribute, referring to the chatbox receiving the message, as well
  157. as a `message` attribute which refers to the Message model.
  158. .. code-block:: javascript
  159. _converse.api.listen.on('messageAdded', function (data) {
  160. // The message is at `data.message`
  161. // The original chatbox is at `data.chatbox`.
  162. });
  163. messageNotification
  164. ~~~~~~~~~~~~~~~~~~~
  165. Emitted just before an HTML5 message notification will be sent out.
  166. .. code-block:: javascript
  167. _converse.api.listen.on('messageNotification', stanza => {
  168. const body = sizzle(`encrypted[xmlns="${Strophe.NS.OMEMO}"]`, message).length ?
  169. __('OMEMO Message received') :
  170. _.get(message.querySelector('body'), 'textContent');
  171. alert(body);
  172. });
  173. messageSend
  174. ~~~~~~~~~~~
  175. When a message will be sent out.
  176. ``_converse.api.listen.on('messageSend', function (messageText) { ... });``
  177. noResumeableSession
  178. ~~~~~~~~~~~~~~~~~~~
  179. When keepalive=true but there aren't any stored prebind tokens.
  180. ``_converse.api.listen.on('noResumeableSession', function () { ... });``
  181. .. _`pluginsInitialized`:
  182. pluginsInitialized
  183. ~~~~~~~~~~~~~~~~~~
  184. Emitted once all plugins have been initialized. This is a useful event if you want to
  185. register event handlers but would like your own handlers to be overridable by
  186. plugins. In that case, you need to first wait until all plugins have been
  187. initialized, so that their overrides are active. One example where this is used
  188. is in `converse-notifications.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-notification.js>`.
  189. ``_converse.api.listen.on('pluginsInitialized', function () { ... });``
  190. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  191. .. code-block:: javascript
  192. _converse.api.waitUntil('pluginsInitialized').then(function () {
  193. // Your code here...
  194. });
  195. privateChatsAutoJoined
  196. ~~~~~~~~~~~~~~~~~~~~~~
  197. Emitted once any private chats have been automatically joined as specified by
  198. the _`auto_join_private_chats` settings.
  199. .. code-block:: javascript
  200. _converse.api.listen.on('privateChatsAutoJoined', function () { ... });
  201. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_.
  202. .. code-block:: javascript
  203. _converse.api.waitUntil('privateChatsAutoJoined').then(function () {
  204. // Your code here...
  205. });
  206. reconnecting
  207. ~~~~~~~~~~~~
  208. Fired once converse.js has determined that it will attempt to reconnect (and
  209. each subsequent time, if it attempts repeatedly).
  210. reconnected
  211. ~~~~~~~~~~~
  212. After the connection has dropped and converse.js has reconnected.
  213. Any Strophe stanza handlers (as registered via `converse.listen.stanza`) will
  214. have to be registered anew.
  215. .. code-block:: javascript
  216. _converse.api.listen.on('reconnected', function () { ... });
  217. registeredGlobalEventHandlers
  218. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  219. Called once Converse has registered its global event handlers (for events such
  220. as window resize or unload).
  221. Plugins can listen to this event as cue to register their own global event
  222. handlers.
  223. roomsAutoJoined
  224. ~~~~~~~~~~~~~~~
  225. Emitted once any rooms that have been configured to be automatically joined,
  226. specified via the _`auto_join_rooms` setting, have been entered.
  227. .. code-block:: javascript
  228. _converse.api.listen.on('roomsAutoJoined', function () { ... });
  229. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  230. .. code-block:: javascript
  231. _converse.api.waitUntil('roomsAutoJoined').then(function () {
  232. // Your code here...
  233. });
  234. roomInviteSent
  235. ~~~~~~~~~~~~~~
  236. After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
  237. ``_converse.api.listen.on('roomInvite', function (data) { ... });``
  238. roomInviteReceived
  239. ~~~~~~~~~~~~~~~~~~
  240. After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
  241. ``_converse.api.listen.on('roomInvite', function (data) { ... });``
  242. .. _`roomsPanelRendered`:
  243. roomsPanelRendered
  244. ~~~~~~~~~~~~~~~~~~
  245. Emitted once the "Rooms" panel in the control box has been rendered.
  246. Used by `converse-bookmarks` and `converse-roomslist` to know when they can
  247. render themselves in that panel.
  248. ``_converse.api.listen.on('roomsPanelRendered', function (data) { ... });``
  249. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  250. .. code-block:: javascript
  251. _converse.api.waitUntil('roomsPanelRendered').then(function () {
  252. // Your code here...
  253. });
  254. .. _`roster`:
  255. roster
  256. ~~~~~~
  257. When the roster has been received from the XMPP server.
  258. ``_converse.api.listen.on('roster', function (items) { ... });``
  259. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  260. .. code-block:: javascript
  261. _converse.api.waitUntil('roster').then(function () {
  262. // Your code here...
  263. });
  264. See also the `cachedRoster` event further up, which gets called instead of
  265. `roster` if its already in `sessionStorage`.
  266. .. _`rosterContactsFetched`:
  267. rosterContactsFetched
  268. ~~~~~~~~~~~~~~~~~~~~~
  269. Triggered once roster contacts have been fetched. Used by the
  270. `converse-rosterview.js` plugin to know when it can start to show the roster.
  271. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  272. .. code-block:: javascript
  273. _converse.api.waitUntil('rosterContactsFetched').then(function () {
  274. // Your code here...
  275. });
  276. .. _`rosterGroupsFetched`:
  277. rosterGroupsFetched
  278. ~~~~~~~~~~~~~~~~~~~
  279. Triggered once roster groups have been fetched. Used by the
  280. `converse-rosterview.js` plugin to know when it can start alphabetically
  281. position roster groups.
  282. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  283. .. code-block:: javascript
  284. _converse.api.waitUntil('rosterGroupsFetched').then(function () {
  285. // Your code here...
  286. });
  287. .. _`rosterInitialized`:
  288. rosterInitialized
  289. ~~~~~~~~~~~~~~~~~
  290. The Backbone collections `RosterContacts` and `RosterGroups` have been created,
  291. but not yet populated with data.
  292. This event is useful when you want to create views for these collections.
  293. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  294. .. code-block:: javascript
  295. _converse.api.waitUntil('rosterInitialized').then(function () {
  296. // Your code here...
  297. });
  298. rosterPush
  299. ~~~~~~~~~~
  300. When the roster receives a push event from server. (i.e. New entry in your buddy list)
  301. ``_converse.api.listen.on('rosterPush', function (items) { ... });``
  302. rosterReadyAfterReconnection
  303. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  304. Similar to `rosterInitialized`, but instead pertaining to reconnection. This
  305. event indicates that the Backbone collections representing the roster and its
  306. groups are now again available after converse.js has reconnected.
  307. serviceDiscovered
  308. ~~~~~~~~~~~~~~~~~
  309. When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
  310. ``_converse.api.listen.on('serviceDiscovered', function (service) { ... });``
  311. .. _`statusInitialized`:
  312. statusInitialized
  313. ~~~~~~~~~~~~~~~~~
  314. When the user's own chat status has been initialized.
  315. ``_converse.api.listen.on('statusInitialized', function (status) { ... });``
  316. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  317. .. code-block:: javascript
  318. _converse.api.waitUntil('statusInitialized').then(function () {
  319. // Your code here...
  320. });
  321. statusChanged
  322. ~~~~~~~~~~~~~
  323. When own chat status has changed.
  324. ``_converse.api.listen.on('statusChanged', function (status) { ... });``
  325. statusMessageChanged
  326. ~~~~~~~~~~~~~~~~~~~~
  327. When own custom status message has changed.
  328. ``_converse.api.listen.on('statusMessageChanged', function (message) { ... });``
  329. streamFeaturesAdded
  330. ~~~~~~~~~~~~~~~~~~~
  331. Emitted as soon as Converse has processed the stream features as advertised by
  332. the server. If you want to check whether a stream feature is supported before
  333. proceeding, then you'll first want to wait for this event.
  334. windowStateChanged
  335. ~~~~~~~~~~~~~~~~~~
  336. When window state has changed. Used to determine when a user left the page and when came back.
  337. ``_converse.api.listen.on('windowStateChanged', function (data) { ... });``
  338. List of events on the ChatRoom Backbone.Model
  339. ---------------------------------------------
  340. configurationNeeded
  341. ~~~~~~~~~~~~~~~~~~~
  342. Triggered when a new room has been created which first needs to be configured
  343. and when `auto_configure` is set to `false`.
  344. Used by the core `ChatRoomView` view in order to know when to render the
  345. configuration form for a new room.