Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
25
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Update events documentation to also mention promises.

Browse Source
This commit is contained in:
JC Brand 2017-08-09 12:16:47 +02:00
parent 4e491ac5d3
commit faa614ba3b
3 changed files with 155 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/_templates/layout.html
View File

@ -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. #}

44
docs/source/developer_api.rst
View File

@ -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.

139
docs/source/events.rst
View File

@ -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
~~~~~~~~~~~~~