Remove old API and events docs
This commit is contained in:
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
|
Please refer to the `Configuration settings`_ section below for info on
|
||||||
all the available configuration settings.
|
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`:
|
||||||
|
|
||||||
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
|
Welcome to the new Converse API documentation, generated with
|
||||||
[JSDoc](http://usejsdoc.org/).
|
[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
|
## The public and private API
|
||||||
|
|
||||||
Converse has a public API and a private API only available to plugins.
|
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.
|
modify its functionality and behavior.
|
||||||
|
|
||||||
All configuration settings have default values which can be overridden when
|
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
|
Plugins often need their own additional configuration settings and you can add
|
||||||
these settings with the `_converse.api.settings.update` method (see
|
these settings with the `_converse.api.settings.update </docs/html/api/-_converse.api.settings.html#.update>`_
|
||||||
:ref:`settings-update`).
|
method.
|
||||||
|
|
||||||
Exposing promises
|
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
|
which allows you to wait for various promises to resolve before executing a
|
||||||
piece of code.
|
piece of code.
|
||||||
|
|
||||||
You can add new promises for your plugin by calling
|
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
|
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.
|
only resolves the plugin but will also emit an event with the same name.
|
||||||
|
|
||||||
Dealing with asynchronicity
|
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
|
challenging, and sometimes it might be necessary to create new events or
|
||||||
promises.
|
promises.
|
||||||
|
|
||||||
Please refer to the :ref:`events-API` section of the documentation for an
|
Please refer to the `API documentation </docs/html/api/http://localhost:8008/docs/html/api/>`_
|
||||||
overview of what's available to you. If you need new events or promises, then
|
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>`_
|
`please open an issue or make a pull request on Github <https://github.com/jcbrand/converse.js>`_
|
||||||
|
|
||||||
A full example plugin
|
A full example plugin
|
||||||
|
|
Loading…
Reference in New Issue