Remove old API and events docs
This commit is contained in:
JC Brand
parent
38a232fd45
commit
a954ab914f
@ -18,10 +18,6 @@ an example of how this is done, please see the bottom of the *./index.html* page
|
||||
Please refer to the `Configuration settings`_ section below for info on
|
||||
all the available configuration settings.
|
||||
|
||||
After you have configured Converse, you'll have to regenerate the minified
|
||||
JavaScript file so that it will include the new settings. Please refer to the
|
||||
:ref:`minification` section for more info on how to do this.
|
||||
|
||||
.. _`configuration-settings`:
|
||||
|
||||
Configuration settings
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,590 +0,0 @@
|
||||
.. raw:: html
|
||||
|
||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
||||
|
||||
.. _`events-API`:
|
||||
|
||||
Events and promises
|
||||
===================
|
||||
|
||||
Converse and its plugins emit various events which you can listen to via the
|
||||
:ref:`listen-grouping`.
|
||||
|
||||
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`_
|
||||
* `connectionInitialized`_
|
||||
* `controlboxInitialized`_ (only via the `converse-controlbox` plugin)
|
||||
* `pluginsInitialized`_
|
||||
* `roomsPanelRendered`_ (only via the `converse-muc` plugin)
|
||||
* `rosterContactsFetched`_
|
||||
* `rosterGroupsFetched`_
|
||||
* `rosterInitialized`_
|
||||
* `roster`_
|
||||
* `statusInitialized`_
|
||||
|
||||
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.
|
||||
|
||||
Global events
|
||||
-------------
|
||||
|
||||
With global events, we mean events triggered in the global context, i.e. on the
|
||||
`window` object in browsers.
|
||||
|
||||
converse-loaded
|
||||
---------------
|
||||
|
||||
Once Converse.js has loaded, it'll dispatch a custom event with the name
|
||||
``converse-loaded``.
|
||||
|
||||
You can listen for this event in your scripts and thereby be informed as soon
|
||||
as converse.js has been loaded, which would mean it's safe to call
|
||||
``converse.initialize``.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
window.addEventListener('converse-loaded', () => {
|
||||
converse.initialize();
|
||||
});
|
||||
|
||||
|
||||
List protected of events (and promises)
|
||||
----------------------------------------
|
||||
|
||||
Hooking into events that Converse.js emits is a great way to extend or
|
||||
customize its functionality.
|
||||
|
||||
From version 3.0.0 and up, it's only possible to register event handlers inside
|
||||
a plugin, by using the closured ``_converse`` object. When writing a plugin,
|
||||
remember that it will also have to be whitelisted, before it will be loaded.
|
||||
Refer to the :ref:`whitelisted_plugins` setting.
|
||||
|
||||
Here follows the different events that are emitted:
|
||||
|
||||
afterMessagesFetched
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted whenever a chatbox has fetched its messages from ``sessionStorage`` and
|
||||
**NOT** from the server.
|
||||
|
||||
This event is listened to by the ``converse-mam`` plugin to know when it can
|
||||
fetch archived messages from the server.
|
||||
|
||||
The event handler is passed the ``Backbone.View`` instance of the relevant chat
|
||||
box.
|
||||
|
||||
``_converse.api.listen.on('afterMessagesFetched', function (chatboxview) { ... });``
|
||||
|
||||
.. _`cachedRoster`:
|
||||
|
||||
cachedRoster
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The contacts roster has been retrieved from the local cache (`sessionStorage`).
|
||||
|
||||
``_converse.api.listen.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
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
When a call button (i.e. with class .toggle-call) on a chatbox has been clicked.
|
||||
|
||||
``_converse.api.listen.on('callButtonClicked', function (connection, model) { ... });``
|
||||
|
||||
.. _`chatBoxesFetched`:
|
||||
|
||||
chatBoxesFetched
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Any open chatboxes (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 chatboxes.
|
||||
|
||||
``_converse.api.listen.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
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When a chatbox has been initialized. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatBoxInitialized', function (chatbox) { ... });``
|
||||
|
||||
chatBoxOpened
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When a chatbox has been opened. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatBoxOpened', function (chatbox) { ... });``
|
||||
|
||||
chatRoomOpened
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When a chatroom has been opened. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatRoomOpened', function (chatbox) { ... });``
|
||||
|
||||
chatBoxClosed
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When a chatbox has been closed. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatBoxClosed', function (chatbox) { ... });``
|
||||
|
||||
chatBoxFocused
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When the focus has been moved to a chatbox. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatBoxFocused', function (chatbox) { ... });``
|
||||
|
||||
chatBoxToggled
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When a chatbox has been minimized or maximized. Relevant to converse-chatview.js plugin.
|
||||
|
||||
``_converse.api.listen.on('chatBoxToggled', function (chatbox) { ... });``
|
||||
|
||||
clearSession
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Called when the user is logging out and provides the opportunity to remove session data.
|
||||
|
||||
connected
|
||||
~~~~~~~~~
|
||||
|
||||
After connection has been established and converse.js has got all its ducks in a row.
|
||||
|
||||
``_converse.api.listen.on('connected', function () { ... });``
|
||||
|
||||
connectionInitialized
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Called once the ``Strophe.Connection`` constructor has been initialized, which
|
||||
will be responsible for managing the connection to the XMPP server.
|
||||
|
||||
contactRequest
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Someone has requested to subscribe to your presence (i.e. to be your contact).
|
||||
|
||||
The `Backbone.Model <http://backbonejs.org/#Model>`_ instance representing the
|
||||
roster contact is passed to the event listener.
|
||||
|
||||
``_converse.api.listen.on('contactRequest', function (contact) { ... });``
|
||||
|
||||
contactRemoved
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The user has removed a contact.
|
||||
|
||||
``_converse.api.listen.on('contactRemoved', function (data) { ... });``
|
||||
|
||||
|
||||
contactPresenceChanged
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When a chat buddy's presence status has changed.
|
||||
The presence status is either `online`, `offline`, `dnd`, `away` or `xa`.
|
||||
|
||||
``_converse.api.listen.on('contactPresenceChanged', function (presence) { ... });``
|
||||
|
||||
contactStatusMessageChanged
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When a chat buddy's custom status message has changed.
|
||||
|
||||
``_converse.api.listen.on('contactStatusMessageChanged', function (data) { ... });``
|
||||
|
||||
controlboxInitialized
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Called when the controlbox has been initialized and therefore exists.
|
||||
|
||||
The controlbox contains the login and register forms when
|
||||
the user is logged out and a list of the user's contacts and group chats when
|
||||
logged in.
|
||||
|
||||
``_converse.api.listen.on('controlboxInitialized', function () { ... });``
|
||||
|
||||
Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.waitUntil('controlboxInitialized').then(function () {
|
||||
// Your code here...
|
||||
});
|
||||
|
||||
discoInitialized
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted once the ``converse-disco`` plugin has been initialized and the
|
||||
``_converse.disco_entities`` collection will be available and populated with at
|
||||
least the service discovery features of the user's own server.
|
||||
|
||||
``_converse.api.listen.on('discoInitialized', function () { ... });``
|
||||
|
||||
disconnected
|
||||
~~~~~~~~~~~~
|
||||
|
||||
After converse.js has disconnected from the XMPP server.
|
||||
|
||||
``_converse.api.listen.on('disconnected', function () { ... });``
|
||||
|
||||
initialized
|
||||
~~~~~~~~~~~
|
||||
|
||||
Once converse.js has been initialized.
|
||||
|
||||
``_converse.api.listen.on('initialized', function () { ... });``
|
||||
|
||||
See also `pluginsInitialized`_.
|
||||
|
||||
logout
|
||||
~~~~~~
|
||||
|
||||
The user has logged out.
|
||||
|
||||
``_converse.api.listen.on('logout', function () { ... });``
|
||||
|
||||
messageAdded
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Once a message has been added to a chatbox. The passed in data object contains
|
||||
a `chatbox` attribute, referring to the chatbox receiving the message, as well
|
||||
as a `message` attribute which refers to the Message model.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.listen.on('messageAdded', function (data) {
|
||||
// The message is at `data.message`
|
||||
// The original chatbox is at `data.chatbox`.
|
||||
});
|
||||
|
||||
|
||||
messageNotification
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted just before an HTML5 message notification will be sent out.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.listen.on('messageNotification', stanza => {
|
||||
|
||||
const body = sizzle(`encrypted[xmlns="${Strophe.NS.OMEMO}"]`, message).length ?
|
||||
__('OMEMO Message received') :
|
||||
_.get(message.querySelector('body'), 'textContent');
|
||||
alert(body);
|
||||
});
|
||||
|
||||
messageSend
|
||||
~~~~~~~~~~~
|
||||
|
||||
When a message will be sent out.
|
||||
|
||||
``_converse.api.listen.on('messageSend', function (messageText) { ... });``
|
||||
|
||||
noResumeableSession
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When keepalive=true but there aren't any stored prebind tokens.
|
||||
|
||||
``_converse.api.listen.on('noResumeableSession', function () { ... });``
|
||||
|
||||
.. _`pluginsInitialized`:
|
||||
|
||||
pluginsInitialized
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
is in `converse-notifications.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-notification.js>`.
|
||||
|
||||
``_converse.api.listen.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...
|
||||
});
|
||||
|
||||
privateChatsAutoJoined
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted once any private chats have been automatically joined as specified by
|
||||
the _`auto_join_private_chats` settings.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.listen.on('privateChatsAutoJoined', function () { ... });
|
||||
|
||||
Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.waitUntil('privateChatsAutoJoined').then(function () {
|
||||
// Your code here...
|
||||
});
|
||||
|
||||
|
||||
reconnecting
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Fired once converse.js has determined that it will attempt to reconnect (and
|
||||
each subsequent time, if it attempts repeatedly).
|
||||
|
||||
reconnected
|
||||
~~~~~~~~~~~
|
||||
|
||||
After the connection has dropped and converse.js has reconnected.
|
||||
Any Strophe stanza handlers (as registered via `converse.listen.stanza`) will
|
||||
have to be registered anew.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.listen.on('reconnected', function () { ... });
|
||||
|
||||
registeredGlobalEventHandlers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Called once Converse has registered its global event handlers (for events such
|
||||
as window resize or unload).
|
||||
|
||||
Plugins can listen to this event as cue to register their own global event
|
||||
handlers.
|
||||
|
||||
roomsAutoJoined
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted once any rooms that have been configured to be automatically joined,
|
||||
specified via the _`auto_join_rooms` setting, have been entered.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.listen.on('roomsAutoJoined', function () { ... });
|
||||
|
||||
Also available as an `ES2015 Promise <http://es6-features.org/#PromiseUsage>`_:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
_converse.api.waitUntil('roomsAutoJoined').then(function () {
|
||||
// Your code here...
|
||||
});
|
||||
|
||||
roomInviteSent
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
|
||||
|
||||
``_converse.api.listen.on('roomInvite', function (data) { ... });``
|
||||
|
||||
roomInviteReceived
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
|
||||
|
||||
``_converse.api.listen.on('roomInvite', function (data) { ... });``
|
||||
|
||||
.. _`roomsPanelRendered`:
|
||||
|
||||
roomsPanelRendered
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted once the "Rooms" panel in the control box has been rendered.
|
||||
Used by `converse-bookmarks` and `converse-roomslist` to know when they can
|
||||
render themselves in that panel.
|
||||
|
||||
``_converse.api.listen.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
|
||||
~~~~~~
|
||||
|
||||
When the roster has been received from the XMPP server.
|
||||
|
||||
``_converse.api.listen.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
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Backbone collections `RosterContacts` and `RosterGroups` have been created,
|
||||
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
|
||||
~~~~~~~~~~
|
||||
|
||||
When the roster receives a push event from server. (i.e. New entry in your buddy list)
|
||||
|
||||
``_converse.api.listen.on('rosterPush', function (items) { ... });``
|
||||
|
||||
rosterReadyAfterReconnection
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
serviceDiscovered
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
|
||||
|
||||
``_converse.api.listen.on('serviceDiscovered', function (service) { ... });``
|
||||
|
||||
|
||||
.. _`statusInitialized`:
|
||||
|
||||
statusInitialized
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
When the user's own chat status has been initialized.
|
||||
|
||||
``_converse.api.listen.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
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When own chat status has changed.
|
||||
|
||||
``_converse.api.listen.on('statusChanged', function (status) { ... });``
|
||||
|
||||
statusMessageChanged
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When own custom status message has changed.
|
||||
|
||||
``_converse.api.listen.on('statusMessageChanged', function (message) { ... });``
|
||||
|
||||
streamFeaturesAdded
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Emitted as soon as Converse has processed the stream features as advertised by
|
||||
the server. If you want to check whether a stream feature is supported before
|
||||
proceeding, then you'll first want to wait for this event.
|
||||
|
||||
windowStateChanged
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When window state has changed. Used to determine when a user left the page and when came back.
|
||||
|
||||
``_converse.api.listen.on('windowStateChanged', function (data) { ... });``
|
||||
|
||||
|
||||
List of events on the ChatRoom Backbone.Model
|
||||
---------------------------------------------
|
||||
|
||||
configurationNeeded
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Triggered when a new room has been created which first needs to be configured
|
||||
and when `auto_configure` is set to `false`.
|
||||
|
||||
Used by the core `ChatRoomView` view in order to know when to render the
|
||||
configuration form for a new room.
|
||||
@ -3,9 +3,6 @@
|
||||
Welcome to the new Converse API documentation, generated with
|
||||
[JSDoc](http://usejsdoc.org/).
|
||||
|
||||
This documentation replaces the (increasingly out of date and incomplete) [old API documentation](/docs/html/developer_api.html)
|
||||
and [old "Events and Promises" documentation](/docs/html/events.html).
|
||||
|
||||
## The public and private API
|
||||
|
||||
Converse has a public API and a private API only available to plugins.
|
||||
|
||||
@ -332,24 +332,26 @@ Converse comes with various :ref:`configuration-settings` that can be used to
|
||||
modify its functionality and behavior.
|
||||
|
||||
All configuration settings have default values which can be overridden when
|
||||
`converse.initialize` (see :ref:`initialize`) gets called.
|
||||
`converse.initialize` (see `converse.initialize </docs/html/api/converse.html#.initialize>`_)
|
||||
gets called.
|
||||
|
||||
Plugins often need their own additional configuration settings and you can add
|
||||
these settings with the `_converse.api.settings.update` method (see
|
||||
:ref:`settings-update`).
|
||||
these settings with the `_converse.api.settings.update </docs/html/api/-_converse.api.settings.html#.update>`_
|
||||
method.
|
||||
|
||||
Exposing promises
|
||||
-----------------
|
||||
|
||||
Converse has a ``waitUntil`` API method (see :ref:`waituntil-grouping`)
|
||||
Converse has a `waitUntil </docs/html/api/-_converse.api.html#.waitUntil>`_ API method
|
||||
which allows you to wait for various promises to resolve before executing a
|
||||
piece of code.
|
||||
|
||||
You can add new promises for your plugin by calling
|
||||
``_converse.api.promises.add`` (see :ref:`promises-grouping`).
|
||||
`_converse.api.promises.add </docs/html/api/-_converse.api.promises.html#.add>`_.
|
||||
|
||||
Generally, your plugin will then also be responsible for making sure these
|
||||
promises are resolved. You do this by calling ``_converse.api.emit``, which not
|
||||
promises are resolved. You do this by calling
|
||||
`_converse.api.trigger </docs/html/api/-_converse.api.html#.trigger>`_, which not
|
||||
only resolves the plugin but will also emit an event with the same name.
|
||||
|
||||
Dealing with asynchronicity
|
||||
@ -429,8 +431,8 @@ Finding the right promises and/or events to listen to, can be a bit
|
||||
challenging, and sometimes it might be necessary to create new events or
|
||||
promises.
|
||||
|
||||
Please refer to the :ref:`events-API` section of the documentation for an
|
||||
overview of what's available to you. If you need new events or promises, then
|
||||
Please refer to the `API documentation </docs/html/api/http://localhost:8008/docs/html/api/>`_
|
||||
for an overview of what's available to you. If you need new events or promises, then
|
||||
`please open an issue or make a pull request on Github <https://github.com/jcbrand/converse.js>`_
|
||||
|
||||
A full example plugin
|
||||
|
||||
Loading…
Reference in New Issue
Block a user