Update events documentation to also mention promises.

docs/source/_templates/layout.html

@@ -2,7 +2,7 @@
 {% extends "!layout.html" %}
 
 {# Custom CSS overrides #}
-{% set bootswatch_css_custom = ['_static/style.css', "../../css/converse.min.css"] %}
+{% set css_files = css_files + ['_static/style.css', "../../css/converse.min.css"] %}
 {% set script_files = script_files + ["../../dist/converse.min.js", "../../analytics.js"] %}
 
 {# Add some extra stuff before and use existing with 'super()' call. #}

docs/source/developer_api.rst

@@ -188,16 +188,15 @@ two important ways:
 
 Converse.js has the following promises:
 
-* cachedRoster
-* chatBoxesFetched
-* connected
-* pluginsInitialized
-* roster
-* rosterContactsFetched
-* rosterGroupsFetched
-* rosterInitialized
-* statusInitialized
-* roomsPanelRendered (only via the `converse-muc` plugin)
+* :ref:`cachedRoster`
+* :ref:`chatBoxesFetched`
+* :ref:`pluginsInitialized`
+* :ref:`roster`
+* :ref:`rosterContactsFetched`
+* :ref:`rosterGroupsFetched`
+* :ref:`rosterInitialized`
+* :ref:`statusInitialized`
+* :ref:`roomsPanelRendered` (only via the `converse-muc` plugin)
 
 Below is an example from `converse-muc.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-muc.js>`_
 where the `rosterContactsFetched` promise is waited on. The method
@@ -903,21 +902,24 @@ The **promises** grouping
 -------------------------
 
 Converse.js and its plugins emit various events which you can listen to via the 
-:refs:`listen-grouping`.
+:ref:`listen-grouping`.
 
-These events can also be turned into promises, and by default some already
-are.
+Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
+although not all of them could logically act as promises, since some events
+might be fired multpile times whereas promises are to be resolved (or
+rejected) only once.
 
 The core events, which are also promises are:
 
-* cachedRoster
-* chatBoxesFetched
-* pluginsInitialized
-* roster
-* rosterContactsFetched
-* rosterGroupsFetched
-* rosterInitialized
-* statusInitialized
+* :ref:`cachedRoster`
+* :ref:`chatBoxesFetched`
+* :ref:`pluginsInitialized`
+* :ref:`roster`
+* :ref:`rosterContactsFetched`
+* :ref:`rosterGroupsFetched`
+* :ref:`rosterInitialized`
+* :ref:`statusInitialized`
+* :ref:`roomsPanelRendered` (only via the `converse-muc` plugin)
 
 The various plugins might also provide promises, and they do this by using the
 ``promises.add`` api method.

docs/source/events.rst

@@ -4,18 +4,41 @@
 
 .. _`events-API`:
 
-Events emitted by converse.js
-=============================
+Events and promises
+===================
 
 .. contents:: Table of Contents
    :depth: 2
    :local:
 
+Converse.js and its plugins emit various events which you can listen to via the
+:ref:`listen-grouping`.
 
-.. note:: see also :ref:`listen-grouping` above.
+Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
+although not all of them could logically act as promises, since some events
+might be fired multpile times whereas promises are to be resolved (or
+rejected) only once.
 
-Event Types
------------
+The core events, which are also promises are:
+
+* `cachedRoster`_
+* `chatBoxesFetched`_
+* `pluginsInitialized`_
+* `roster`_
+* `rosterContactsFetched`_
+* `rosterGroupsFetched`_
+* `rosterInitialized`_
+* `statusInitialized`_
+* `roomsPanelRendered`_ (only via the `converse-muc` plugin)
+
+For more info on how to use (or add promises), you can read the
+:ref:`promises-grouping` in the API documentation.
+
+Below we will now list all events and also specify whether they are available
+as promises.
+
+List of Events (and promises)
+-----------------------------
 
 Hooking into events that Converse.js emits is a great way to extend or
 customize its functionality.
@@ -41,6 +64,8 @@ box.
 
 ``_converse.on('afterMessagesFetched', function (chatboxview) { ... });``
 
+.. _`cachedRoster`:
+
 cachedRoster
 ~~~~~~~~~~~~
 
@@ -48,6 +73,14 @@ The contacts roster has been retrieved from the local cache (`sessionStorage`).
 
 ``_converse.on('cachedRoster', function (items) { ... });``
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('cachedRoster').then(function () {
+        // Your code here...
+    });
+
 See also the `roster`_ event further down.
 
 callButtonClicked
@@ -57,6 +90,26 @@ When a call button (i.e. with class .toggle-call) on a chat box has been clicked
 
 ``_converse.on('callButtonClicked', function (connection, model) { ... });``
 
+.. _`chatBoxesFetched`:
+
+chatBoxesFetched
+~~~~~~~~~~~~~~~~
+
+Any open chat boxes (from this current session) has been retrieved from the local cache (`sessionStorage`).
+
+You should wait for this event or promise before attempting to do things
+related to open chat boxes.
+
+``_converse.on('chatBoxesFetched', function (items) { ... });``
+
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('chatBoxesFetched').then(function () {
+        // Your code here...
+    });
+
 chatBoxInitialized
 ~~~~~~~~~~~~~~~~~~
 
@@ -174,7 +227,7 @@ Once a message has been added to a chat box. The passed in data object contains
 a `chatbox` attribute, referring to the chat box receiving the message, as well
 as a `message` attribute which refers to the Message model.
 
-.. code-block:: javascript 
+.. code-block:: javascript
 
     _converse.on('messageAdded', function (data) {
         // The message is at `data.message`
@@ -195,10 +248,12 @@ When keepalive=true but there aren't any stored prebind tokens.
 
 ``_converse.on('noResumeableSession', function () { ... });``
 
+.. _`pluginsInitialized`:
+
 pluginsInitialized
 ~~~~~~~~~~~~~~~~~~
 
-Once all plugins have been initialized. This is a useful event if you want to
+Emitted once all plugins have been initialized. This is a useful event if you want to
 register event handlers but would like your own handlers to be overridable by
 plugins. In that case, you need to first wait until all plugins have been
 initialized, so that their overrides are active. One example where this is used
@@ -206,6 +261,14 @@ is in `converse-notifications.js <https://github.com/jcbrand/converse.js/blob/ma
 
 ``_converse.on('pluginsInitialized', function () { ... });``
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('pluginsInitialized').then(function () {
+        // Your code here...
+    });
+
 reconnecting
 ~~~~~~~~~~~~
 
@@ -235,6 +298,8 @@ After the user has sent out a direct invitation, to a roster contact, asking the
 
 ``_converse.on('roomInvite', function (data) { ... });``
 
+.. _`roomsPanelRendered`:
+
 roomsPanelRendered
 ~~~~~~~~~~~~~~~~~~
 
@@ -244,6 +309,16 @@ render themselves in that panel.
 
 ``_converse.on('roomsPanelRendered', function (data) { ... });``
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('roomsPanelRendered').then(function () {
+        // Your code here...
+    });
+
+.. _`roster`:
+
 roster
 ~~~~~~
 
@@ -251,15 +326,35 @@ When the roster has been received from the XMPP server.
 
 ``_converse.on('roster', function (items) { ... });``
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('roster').then(function () {
+        // Your code here...
+    });
+
 See also the `cachedRoster` event further up, which gets called instead of
 `roster` if its already in `sessionStorage`.
 
+.. _`rosterContactsFetched`:
+
 rosterContactsFetched
 ~~~~~~~~~~~~~~~~~~~~~
 
 Triggered once roster contacts have been fetched. Used by the
 `converse-rosterview.js` plugin to know when it can start to show the roster.
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('rosterContactsFetched').then(function () {
+        // Your code here...
+    });
+
+.. _`rosterGroupsFetched`:
+
 rosterGroupsFetched
 ~~~~~~~~~~~~~~~~~~~
 
@@ -267,6 +362,16 @@ Triggered once roster groups have been fetched. Used by the
 `converse-rosterview.js` plugin to know when it can start alphabetically
 position roster groups.
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('rosterGroupsFetched').then(function () {
+        // Your code here...
+    });
+
+.. _`rosterInitialized`:
+
 rosterInitialized
 ~~~~~~~~~~~~~~~~~
 
@@ -275,6 +380,14 @@ but not yet populated with data.
 
 This event is useful when you want to create views for these collections.
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('rosterInitialized').then(function () {
+        // Your code here...
+    });
+
 rosterPush
 ~~~~~~~~~~
 
@@ -289,13 +402,23 @@ Similar to `rosterInitialized`, but instead pertaining to reconnection. This
 event indicates that the Backbone collections representing the roster and its
 groups are now again available after converse.js has reconnected.
 
+.. _`statusInitialized`:
+
 statusInitialized
 ~~~~~~~~~~~~~~~~~
 
-When own chat status has been initialized.
+When the user's own chat status has been initialized.
 
 ``_converse.on('statusInitialized', function (status) { ... });``
 
+Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
+
+.. code-block:: javascript
+
+    _converse.api.waitUntil('statusInitialized').then(function () {
+        // Your code here...
+    });
+
 statusChanged
 ~~~~~~~~~~~~~