events.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525
  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.js 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. messageSend
  164. ~~~~~~~~~~~
  165. When a message will be sent out.
  166. ``_converse.api.listen.on('messageSend', function (messageText) { ... });``
  167. noResumeableSession
  168. ~~~~~~~~~~~~~~~~~~~
  169. When keepalive=true but there aren't any stored prebind tokens.
  170. ``_converse.api.listen.on('noResumeableSession', function () { ... });``
  171. .. _`pluginsInitialized`:
  172. pluginsInitialized
  173. ~~~~~~~~~~~~~~~~~~
  174. Emitted once all plugins have been initialized. This is a useful event if you want to
  175. register event handlers but would like your own handlers to be overridable by
  176. plugins. In that case, you need to first wait until all plugins have been
  177. initialized, so that their overrides are active. One example where this is used
  178. is in `converse-notifications.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-notification.js>`.
  179. ``_converse.api.listen.on('pluginsInitialized', function () { ... });``
  180. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  181. .. code-block:: javascript
  182. _converse.api.waitUntil('pluginsInitialized').then(function () {
  183. // Your code here...
  184. });
  185. reconnecting
  186. ~~~~~~~~~~~~
  187. Fired once converse.js has determined that it will attempt to reconnect (and
  188. each subsequent time, if it attempts repeatedly).
  189. reconnected
  190. ~~~~~~~~~~~
  191. After the connection has dropped and converse.js has reconnected.
  192. Any Strophe stanza handlers (as registered via `converse.listen.stanza`) will
  193. have to be registered anew.
  194. .. code-block:: javascript
  195. _converse.api.listen.on('reconnected', function () { ... });
  196. privateChatsAutoJoined
  197. ~~~~~~~~~~~~~~~~~~~~~~
  198. Emitted once any private chats have been automatically joined as specified by
  199. the _`auto_join_private_chats` settings.
  200. .. code-block:: javascript
  201. _converse.api.listen.on('privateChatsAutoJoined', function () { ... });
  202. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_.
  203. .. code-block:: javascript
  204. _converse.api.waitUntil('privateChatsAutoJoined').then(function () {
  205. // Your code here...
  206. });
  207. roomsAutoJoined
  208. ---------------
  209. Emitted once any rooms that have been configured to be automatically joined,
  210. specified via the _`auto_join_rooms` setting, have been entered.
  211. .. code-block:: javascript
  212. _converse.api.listen.on('roomsAutoJoined', function () { ... });
  213. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  214. .. code-block:: javascript
  215. _converse.api.waitUntil('roomsAutoJoined').then(function () {
  216. // Your code here...
  217. });
  218. roomInviteSent
  219. ~~~~~~~~~~~~~~
  220. After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
  221. ``_converse.api.listen.on('roomInvite', function (data) { ... });``
  222. roomInviteReceived
  223. ~~~~~~~~~~~~~~~~~~
  224. After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
  225. ``_converse.api.listen.on('roomInvite', function (data) { ... });``
  226. .. _`roomsPanelRendered`:
  227. roomsPanelRendered
  228. ~~~~~~~~~~~~~~~~~~
  229. Emitted once the "Rooms" panel in the control box has been rendered.
  230. Used by `converse-bookmarks` and `converse-roomslist` to know when they can
  231. render themselves in that panel.
  232. ``_converse.api.listen.on('roomsPanelRendered', function (data) { ... });``
  233. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  234. .. code-block:: javascript
  235. _converse.api.waitUntil('roomsPanelRendered').then(function () {
  236. // Your code here...
  237. });
  238. .. _`roster`:
  239. roster
  240. ~~~~~~
  241. When the roster has been received from the XMPP server.
  242. ``_converse.api.listen.on('roster', function (items) { ... });``
  243. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  244. .. code-block:: javascript
  245. _converse.api.waitUntil('roster').then(function () {
  246. // Your code here...
  247. });
  248. See also the `cachedRoster` event further up, which gets called instead of
  249. `roster` if its already in `sessionStorage`.
  250. .. _`rosterContactsFetched`:
  251. rosterContactsFetched
  252. ~~~~~~~~~~~~~~~~~~~~~
  253. Triggered once roster contacts have been fetched. Used by the
  254. `converse-rosterview.js` plugin to know when it can start to show the roster.
  255. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  256. .. code-block:: javascript
  257. _converse.api.waitUntil('rosterContactsFetched').then(function () {
  258. // Your code here...
  259. });
  260. .. _`rosterGroupsFetched`:
  261. rosterGroupsFetched
  262. ~~~~~~~~~~~~~~~~~~~
  263. Triggered once roster groups have been fetched. Used by the
  264. `converse-rosterview.js` plugin to know when it can start alphabetically
  265. position roster groups.
  266. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  267. .. code-block:: javascript
  268. _converse.api.waitUntil('rosterGroupsFetched').then(function () {
  269. // Your code here...
  270. });
  271. .. _`rosterInitialized`:
  272. rosterInitialized
  273. ~~~~~~~~~~~~~~~~~
  274. The Backbone collections `RosterContacts` and `RosterGroups` have been created,
  275. but not yet populated with data.
  276. This event is useful when you want to create views for these collections.
  277. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  278. .. code-block:: javascript
  279. _converse.api.waitUntil('rosterInitialized').then(function () {
  280. // Your code here...
  281. });
  282. rosterPush
  283. ~~~~~~~~~~
  284. When the roster receives a push event from server. (i.e. New entry in your buddy list)
  285. ``_converse.api.listen.on('rosterPush', function (items) { ... });``
  286. rosterReadyAfterReconnection
  287. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  288. Similar to `rosterInitialized`, but instead pertaining to reconnection. This
  289. event indicates that the Backbone collections representing the roster and its
  290. groups are now again available after converse.js has reconnected.
  291. .. _`statusInitialized`:
  292. statusInitialized
  293. ~~~~~~~~~~~~~~~~~
  294. When the user's own chat status has been initialized.
  295. ``_converse.api.listen.on('statusInitialized', function (status) { ... });``
  296. Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
  297. .. code-block:: javascript
  298. _converse.api.waitUntil('statusInitialized').then(function () {
  299. // Your code here...
  300. });
  301. statusChanged
  302. ~~~~~~~~~~~~~
  303. When own chat status has changed.
  304. ``_converse.api.listen.on('statusChanged', function (status) { ... });``
  305. statusMessageChanged
  306. ~~~~~~~~~~~~~~~~~~~~
  307. When own custom status message has changed.
  308. ``_converse.api.listen.on('statusMessageChanged', function (message) { ... });``
  309. serviceDiscovered
  310. ~~~~~~~~~~~~~~~~~
  311. When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
  312. ``_converse.api.listen.on('serviceDiscovered', function (service) { ... });``
  313. windowStateChanged
  314. ~~~~~~~~~~~~~~~~~~
  315. When window state has changed. Used to determine when a user left the page and when came back.
  316. ``_converse.api.listen.on('windowStateChanged', function (data) { ... });``
  317. List of events on the ChatRoom Backbone.Model
  318. ---------------------------------------------
  319. configurationNeeded
  320. ~~~~~~~~~~~~~~~~~~~
  321. Triggered when a new room has been created which first needs to be configured
  322. and when `auto_configure` is set to `false`.
  323. Used by the core `ChatRoomView` view in order to know when to render the
  324. configuration form for a new room.