2016-11-02 15:31:58 +01:00
|
|
|
.. 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>
|
2017-02-14 10:56:30 +01:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
=============================
|
2016-10-21 16:33:47 +02:00
|
|
|
The converse.js developer API
|
|
|
|
=============================
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
.. contents:: Table of Contents
|
|
|
|
:depth: 2
|
|
|
|
:local:
|
|
|
|
|
2016-10-21 16:33:47 +02:00
|
|
|
.. note:: The API documented here is available in Converse.js 0.8.4 and higher.
|
|
|
|
Earlier versions of Converse.js might have different API methods or none at all.
|
|
|
|
|
2016-12-19 10:32:48 +01:00
|
|
|
.. note:: From version 3.0.0 and onwards many API methods have been made
|
|
|
|
private and available to plugins only. This means that if you want to
|
|
|
|
use the API, you'll first need to create a plugin from which you can
|
|
|
|
access it. This change is done to avoid leakage of sensitive data to
|
|
|
|
malicious or non-whitelisted scripts.
|
|
|
|
|
|
|
|
The Converse.js API is broken up into different logical "groupings" (for
|
|
|
|
example ``converse.plugins`` or ``converse.contacts``).
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
There are some exceptions to this, like ``converse.initialize``, which aren't
|
|
|
|
groupings but single methods.
|
2016-12-19 10:32:48 +01:00
|
|
|
|
|
|
|
The groupings logically group methods, such as standardised accessors and
|
|
|
|
mutators::
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
.get
|
|
|
|
.set
|
|
|
|
.add
|
|
|
|
.remove
|
|
|
|
|
2016-12-19 10:32:48 +01:00
|
|
|
So for example, to get a contact, you would do the following::
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.contacts.get('jid@example.com');
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To get multiple contacts, just pass in an array of jids::
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.contacts.get(['jid1@example.com', 'jid2@example.com']);
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To get all contacts, simply call ``get`` without any jids::
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.contacts.get();
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
Public API methods
|
|
|
|
==================
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
Publich API methods are those methods that are accessible on the global
|
|
|
|
``window.converse`` object. They are public, because any Javascript in the page
|
|
|
|
can call them. Public methods therefore don't expose any sensitive or closured
|
|
|
|
data. To do that, you'll need to create a plugin, which has access to the
|
|
|
|
private API method.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
initialize
|
|
|
|
----------
|
|
|
|
|
2016-12-19 10:32:48 +01:00
|
|
|
.. note:: This method is the one exception of a method which is not logically grouped as explained above.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
Publich API method which initializes converse.js.
|
|
|
|
This method must always be called when using converse.js.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
The `initialize` method takes a map of :ref:`configuration-variables`.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
|
|
|
converse.initialize({
|
|
|
|
allow_otr: true,
|
|
|
|
auto_list_rooms: false,
|
|
|
|
auto_subscribe: false,
|
|
|
|
bosh_service_url: 'https://bind.example.com',
|
|
|
|
hide_muc_server: false,
|
|
|
|
i18n: locales['en'],
|
|
|
|
keepalive: true,
|
|
|
|
play_sounds: true,
|
|
|
|
prebind: false,
|
|
|
|
show_controlbox_by_default: true,
|
|
|
|
debug: false,
|
|
|
|
roster_groups: true
|
|
|
|
});
|
|
|
|
|
2017-02-14 10:56:30 +01:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
The **plugin** grouping
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
Exposes methods for adding and removing plugins. You'll need to write a plugin
|
|
|
|
if you want to have access to the private API methods defined further down below.
|
|
|
|
|
|
|
|
For more information on plugins, read the section :ref:`writing-a-plugin`.
|
|
|
|
|
|
|
|
add
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Registers a new plugin.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
|
|
|
var plugin = {
|
|
|
|
initialize: function () {
|
|
|
|
// method on any plugin (if it exists) as soon as the plugin has
|
|
|
|
// been loaded.
|
|
|
|
|
|
|
|
// Inside this method, you have access to the closured
|
|
|
|
// _converse object, which contains the core logic and data
|
|
|
|
// structures of converse.js
|
|
|
|
}
|
|
|
|
}
|
|
|
|
converse.plugins.add('myplugin', plugin);
|
|
|
|
|
|
|
|
|
|
|
|
Private API methods
|
|
|
|
===================
|
|
|
|
|
|
|
|
The private API methods are only accessible via the closured ``_converse``
|
|
|
|
object, which is only available to plugins.
|
|
|
|
|
|
|
|
These methods are kept private (i.e. not global) because they may return
|
|
|
|
sensitive data which should be kept off-limits to other 3rd-party scripts
|
|
|
|
that might be running in the page.
|
|
|
|
|
|
|
|
.. note:: The example code snippets shown below are a bit contrived. I've added
|
|
|
|
the minimum plugin boilerplace around the actual example, to show that
|
|
|
|
these API methods can only be called inside a plugin where the
|
|
|
|
``_converse`` object is available. However, sometimes other considerations
|
|
|
|
need to be made as well. For example, for certain API methods it is
|
|
|
|
necessary to first wait until the data has been received from the XMPP
|
|
|
|
server (or from the browser's sessionStorage cache). Due to
|
|
|
|
time-constriaints these limitations are ignored in the examples below. For
|
|
|
|
a fuller picture, refer to the section :ref:`events-API` as well.
|
|
|
|
|
2016-10-21 16:33:47 +02:00
|
|
|
send
|
|
|
|
----
|
|
|
|
|
|
|
|
Allows you to send XML stanzas.
|
|
|
|
|
|
|
|
For example, to send a message stanza:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var msg = converse.env.$msg({
|
|
|
|
from: 'juliet@example.com/balcony',
|
|
|
|
to:'romeo@example.net',
|
|
|
|
type:'chat'
|
|
|
|
});
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.send(msg);
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
2016-10-21 16:33:47 +02:00
|
|
|
});
|
|
|
|
|
|
|
|
|
2017-02-14 10:56:30 +01:00
|
|
|
.. _`waituntil-grouping`:
|
|
|
|
|
|
|
|
waitUntil
|
|
|
|
---------
|
|
|
|
|
|
|
|
This method can be used to wait for promises. Promises are similar to events
|
|
|
|
(for event handling, refer to the :ref:`listen-grouping`), but they differ in
|
|
|
|
two important ways:
|
|
|
|
|
|
|
|
* A promise gets resolved only once, whereas events can fire multiple times.
|
|
|
|
* A handler registered for a promise, will still fire *after* the promise has
|
|
|
|
been resolved, which is not the case with an event handler.
|
|
|
|
|
|
|
|
Converse.js has the following promises:
|
|
|
|
|
|
|
|
* cachedRoster
|
|
|
|
* chatBoxesFetched
|
|
|
|
* connected
|
|
|
|
* pluginsInitialized
|
|
|
|
* roster
|
|
|
|
* rosterContactsFetched
|
|
|
|
* rosterGroupsFetched
|
|
|
|
* rosterInitialized
|
|
|
|
* statusInitialized
|
2017-05-07 20:16:13 +02:00
|
|
|
* roomsPanelRendered (only via the `converse-muc` plugin)
|
2017-02-14 10:56:30 +01:00
|
|
|
|
|
|
|
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
|
|
|
|
`this.initInviteWidget` will initialize the chatroom invitation widget.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
|
|
|
_converse.api.waitUntil('rosterContactsFetched').then(this.initInviteWidget.bind(this));
|
|
|
|
|
|
|
|
The line above executes only once a chatroom has been opened and entered, so
|
|
|
|
using an event handler here would not work, since the event might have fired
|
|
|
|
already by that time.
|
|
|
|
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **archive** grouping
|
|
|
|
------------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Converse.js supports the *Message Archive Management*
|
|
|
|
(`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
|
|
|
|
through which it is able to query an XMPP server for archived messages.
|
|
|
|
|
|
|
|
See also the **message_archiving** option in the :ref:`configuration-variables` section, which you'll usually
|
|
|
|
want to in conjunction with this API.
|
|
|
|
|
|
|
|
query
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
The ``query`` method is used to query for archived messages.
|
|
|
|
|
|
|
|
It accepts the following optional parameters:
|
|
|
|
|
|
|
|
* **options** an object containing the query parameters. Valid query parameters
|
|
|
|
are ``with``, ``start``, ``end``, ``first``, ``last``, ``after``, ``before``, ``index`` and ``count``.
|
|
|
|
* **callback** is the callback method that will be called when all the messages
|
|
|
|
have been received.
|
|
|
|
* **errback** is the callback method to be called when an error is returned by
|
|
|
|
the XMPP server, for example when it doesn't support message archiving.
|
|
|
|
|
|
|
|
Examples
|
|
|
|
^^^^^^^^
|
|
|
|
|
|
|
|
**Requesting all archived messages**
|
|
|
|
|
|
|
|
The simplest query that can be made is to simply not pass in any parameters.
|
|
|
|
Such a query will return all archived messages for the current user.
|
|
|
|
|
|
|
|
Generally, you'll however always want to pass in a callback method, to receive
|
|
|
|
the returned messages.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var errback = function (iq) {
|
|
|
|
// The query was not successful, perhaps inform the user?
|
|
|
|
// The IQ stanza returned by the XMPP server is passed in, so that you
|
|
|
|
// may inspect it and determine what the problem was.
|
|
|
|
}
|
|
|
|
var callback = function (messages) {
|
|
|
|
// Do something with the messages, like showing them in your webpage.
|
|
|
|
}
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.archive.query(callback, errback))
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
**Waiting until server support has been determined**
|
|
|
|
|
|
|
|
The query method will only work if converse.js has been able to determine that
|
|
|
|
the server supports MAM queries, otherwise the following error will be raised:
|
|
|
|
|
|
|
|
- *This server does not support XEP-0313, Message Archive Management*
|
|
|
|
|
|
|
|
The very first time converse.js loads in a browser tab, if you call the query
|
|
|
|
API too quickly, the above error might appear because service discovery has not
|
|
|
|
yet been completed.
|
|
|
|
|
|
|
|
To work solve this problem, you can first listen for the ``serviceDiscovered`` event,
|
|
|
|
through which you can be informed once support for MAM has been determined.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var _converse = this._converse;
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.on('serviceDiscovered', function (feature) {
|
2016-12-20 10:31:11 +01:00
|
|
|
if (feature.get('var') === converse.env.Strophe.NS.MAM) {
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.archive.query()
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
});
|
|
|
|
|
2016-12-19 08:33:46 +01:00
|
|
|
converse.listen.on('serviceDiscovered', function (feature) {
|
|
|
|
if (feature.get('var') === converse.env.Strophe.NS.MAM) {
|
|
|
|
converse.archive.query()
|
2016-10-21 16:33:47 +02:00
|
|
|
}
|
|
|
|
});
|
|
|
|
|
|
|
|
**Requesting all archived messages for a particular contact or room**
|
|
|
|
|
|
|
|
To query for messages sent between the current user and another user or room,
|
|
|
|
the query options need to contain the the JID (Jabber ID) of the user or
|
|
|
|
room under the ``with`` key.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
// For a particular user
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.archive.query({'with': 'john@doe.net'}, callback, errback);)
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
// For a particular room
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
**Requesting all archived messages before or after a certain date**
|
|
|
|
|
|
|
|
The ``start`` and ``end`` parameters are used to query for messages
|
|
|
|
within a certain timeframe. The passed in date values may either be ISO8601
|
|
|
|
formatted date strings, or Javascript Date objects.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var options = {
|
|
|
|
'with': 'john@doe.net',
|
|
|
|
'start': '2010-06-07T00:00:00Z',
|
|
|
|
'end': '2010-07-07T13:23:54Z'
|
|
|
|
};
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.archive.query(options, callback, errback);
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
**Limiting the amount of messages returned**
|
|
|
|
|
|
|
|
The amount of returned messages may be limited with the ``max`` parameter.
|
|
|
|
By default, the messages are returned from oldest to newest.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
// Return maximum 10 archived messages
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
**Paging forwards through a set of archived messages**
|
|
|
|
|
|
|
|
When limiting the amount of messages returned per query, you might want to
|
|
|
|
repeatedly make a further query to fetch the next batch of messages.
|
|
|
|
|
|
|
|
To simplify this usecase for you, the callback method receives not only an array
|
|
|
|
with the returned archived messages, but also a special RSM (*Result Set
|
|
|
|
Management*) object which contains the query parameters you passed in, as well
|
|
|
|
as two utility methods ``next``, and ``previous``.
|
|
|
|
|
|
|
|
When you call one of these utility methods on the returned RSM object, and then
|
|
|
|
pass the result into a new query, you'll receive the next or previous batch of
|
|
|
|
archived messages. Please note, when calling these methods, pass in an integer
|
|
|
|
to limit your results.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
var _converse = this._converse;
|
|
|
|
var callback = function (messages, rsm) {
|
|
|
|
// Do something with the messages, like showing them in your webpage.
|
|
|
|
// ...
|
|
|
|
// You can now use the returned "rsm" object, to fetch the next batch of messages:
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.archive.query(rsm.next(10), callback, errback))
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
**Paging backwards through a set of archived messages**
|
|
|
|
|
|
|
|
To page backwards through the archive, you need to know the UID of the message
|
|
|
|
which you'd like to page backwards from and then pass that as value for the
|
|
|
|
``before`` parameter. If you simply want to page backwards from the most recent
|
|
|
|
message, pass in the ``before`` parameter with an empty string value ``''``.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var _converse = this._converse;
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.archive.query({'before': '', 'max':5}, function (message, rsm) {
|
2016-12-20 10:31:11 +01:00
|
|
|
// Do something with the messages, like showing them in your webpage.
|
|
|
|
// ...
|
|
|
|
// You can now use the returned "rsm" object, to fetch the previous batch of messages:
|
|
|
|
rsm.previous(5); // Call previous method, to update the object's parameters,
|
|
|
|
// passing in a limit value of 5.
|
|
|
|
// Now we query again, to get the previous batch.
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.archive.query(rsm, callback, errback);
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **connection** grouping
|
|
|
|
---------------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
This grouping collects API functions related to the XMPP connection.
|
|
|
|
|
|
|
|
connected
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
A boolean attribute (i.e. not a callable) which is set to `true` or `false` depending
|
|
|
|
on whether there is an established connection.
|
|
|
|
|
|
|
|
disconnect
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
Terminates the connection.
|
|
|
|
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **user** grouping
|
|
|
|
---------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
This grouping collects API functions related to the current logged in user.
|
|
|
|
|
|
|
|
jid
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Return's the current user's full JID (Jabber ID).
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
alert(this._converse.api.user.jid());
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
login
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
Logs the user in. This method can accept a map with the credentials, like this:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.user.login({
|
2016-12-20 10:31:11 +01:00
|
|
|
'jid': 'dummy@example.com',
|
|
|
|
'password': 'secret'
|
|
|
|
});
|
|
|
|
|
|
|
|
}
|
2016-10-21 16:33:47 +02:00
|
|
|
});
|
|
|
|
|
|
|
|
or it can be called without any parameters, in which case converse.js will try
|
|
|
|
to log the user in by calling the `prebind_url` or `credentials_url` depending
|
|
|
|
on whether prebinding is used or not.
|
|
|
|
|
|
|
|
logout
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
Log the user out of the current XMPP session.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.user.logout();
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **status** sub-grouping
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Set and get the user's chat status, also called their *availability*.
|
|
|
|
|
|
|
|
get
|
|
|
|
^^^
|
|
|
|
|
|
|
|
Return the current user's availability status:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
alert(this._converse.api.user.status.get()); // For example "dnd"
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
set
|
|
|
|
^^^
|
|
|
|
|
|
|
|
The user's status can be set to one of the following values:
|
|
|
|
|
|
|
|
* **away**
|
|
|
|
* **dnd**
|
|
|
|
* **offline**
|
|
|
|
* **online**
|
|
|
|
* **unavailable**
|
|
|
|
* **xa**
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.user.status.set('dnd');
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Because the user's availability is often set together with a custom status
|
|
|
|
message, this method also allows you to pass in a status message as a
|
|
|
|
second parameter:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.user.status.set('dnd', 'In a meeting');
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **message** sub-grouping
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
The ``user.status.message`` sub-grouping exposes methods for setting and
|
|
|
|
retrieving the user's custom status message.
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.user.status.message.set('In a meeting');
|
2016-12-20 10:31:11 +01:00
|
|
|
// Returns "In a meeting"
|
2017-04-19 15:00:59 +02:00
|
|
|
return this._converse.api.user.status.message.get();
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **contacts** grouping
|
|
|
|
-------------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
get
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This method is used to retrieve roster contacts.
|
|
|
|
|
|
|
|
To get a single roster contact, call the method with the contact's JID (Jabber ID):
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var _converse = this._converse;
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.on('rosterContactsFetched', function () {
|
|
|
|
var contact = _converse.api.contacts.get('buddy@example.com')
|
2016-12-20 10:31:11 +01:00
|
|
|
});
|
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To get multiple contacts, pass in an array of JIDs:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var _converse = this._converse;
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.on('rosterContactsFetched', function () {
|
|
|
|
var contacts = _converse.api.contacts.get(
|
2016-12-20 10:31:11 +01:00
|
|
|
['buddy1@example.com', 'buddy2@example.com']
|
|
|
|
)
|
|
|
|
});
|
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To return all contacts, simply call ``get`` without any parameters:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
var _converse = this._converse;
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.on('rosterContactsFetched', function () {
|
|
|
|
var contacts = _converse.api.contacts.get();
|
2016-12-20 10:31:11 +01:00
|
|
|
});
|
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
The returned roster contact objects have these attributes:
|
|
|
|
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| Attribute | |
|
|
|
|
+================+=================================================================================================================+
|
|
|
|
| ask | If ask === 'subscribe', then we have asked this person to be our chat buddy. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| fullname | The person's full name. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| jid | The person's Jabber/XMPP username. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| requesting | If true, then this person is asking to be our chat buddy. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| subscription | The subscription state between the current user and this chat buddy. Can be `none`, `to`, `from` or `both`. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| id | A unique id, same as the jid. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| chat_status | The person's chat status. Can be `online`, `offline`, `busy`, `xa` (extended away) or `away`. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| user_id | The user id part of the JID (the part before the `@`). |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| resources | The known resources for this chat buddy. Each resource denotes a separate and connected chat client. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| groups | The roster groups in which this chat buddy was placed. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| status | Their human readable custom status message. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| image_type | The image's file type. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| image | The Base64 encoded image data. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| url | The buddy's website URL, as specified in their VCard data. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
| vcard_updated | When last the buddy's VCard was updated. |
|
|
|
|
+----------------+-----------------------------------------------------------------------------------------------------------------+
|
|
|
|
|
|
|
|
add
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Add a contact.
|
|
|
|
|
|
|
|
Provide the JID of the contact you want to add:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.contacts.add('buddy@example.com')
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
You may also provide the fullname. If not present, we use the jid as fullname:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.contacts.add('buddy@example.com', 'Buddy')
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **chats** grouping
|
|
|
|
----------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Note, for MUC chat rooms, you need to use the "rooms" grouping instead.
|
|
|
|
|
|
|
|
get
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Returns an object representing a chat box.
|
|
|
|
|
|
|
|
To return a single chat box, provide the JID of the contact you're chatting
|
|
|
|
with in that chat box:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.chats.get('buddy@example.com')
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To return an array of chat boxes, provide an array of JIDs:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com'])
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To return all open chat boxes, call the method without any JIDs::
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.chats.get()
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
open
|
|
|
|
~~~~
|
|
|
|
|
2017-02-14 15:58:29 +01:00
|
|
|
Opens a chat box and returns a Backbone.View object representing a chat box.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To open a single chat box, provide the JID of the contact:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.chats.open('buddy@example.com')
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To return an array of chat boxes, provide an array of JIDs:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.chats.open(['buddy1@example.com', 'buddy2@example.com'])
|
2016-12-20 10:31:11 +01:00
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
*The returned chat box object contains the following methods:*
|
|
|
|
|
2017-02-14 15:58:29 +01:00
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| Method | Description |
|
|
|
|
+===================+==========================================+
|
|
|
|
| close | Close the chat box. |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| focus | Focuses the chat box textarea |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.endOTR | End an OTR (Off-the-record) session. |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.get | Get an attribute (i.e. accessor). |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.initiateOTR | Start an OTR (off-the-record) session. |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.maximize | Minimize the chat box. |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.minimize | Maximize the chat box. |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| model.set | Set an attribute (i.e. mutator). |
|
|
|
|
+-------------------+------------------------------------------+
|
|
|
|
| show | Opens/shows the chat box. |
|
|
|
|
+-------------------+------------------------------------------+
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
*The get and set methods can be used to retrieve and change the following attributes:*
|
|
|
|
|
|
|
|
+-------------+-----------------------------------------------------+
|
|
|
|
| Attribute | Description |
|
|
|
|
+=============+=====================================================+
|
|
|
|
| height | The height of the chat box. |
|
|
|
|
+-------------+-----------------------------------------------------+
|
|
|
|
| url | The URL of the chat box heading. |
|
|
|
|
+-------------+-----------------------------------------------------+
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **rooms** grouping
|
|
|
|
----------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
get
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Returns an object representing a multi user chat box (room).
|
|
|
|
It takes 3 parameters:
|
|
|
|
|
|
|
|
* the room JID (if not specified, all rooms will be returned).
|
|
|
|
* a map (object) containing any extra room attributes For example, if you want
|
|
|
|
to specify the nickname, use ``{'nick': 'bloodninja'}``. Previously (before
|
|
|
|
version 1.0.7, the second parameter only accepted the nickname (as a string
|
|
|
|
value). This is currently still accepted, but then you can't pass in any
|
|
|
|
other room attributes. If the nickname is not specified then the node part of
|
|
|
|
the user's JID will be used.
|
|
|
|
* a boolean, indicating whether the room should be created if not found (default: `false`)
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
var nick = 'dread-pirate-roberts';
|
|
|
|
var create_if_not_found = true;
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.rooms.open(
|
2016-12-20 10:31:11 +01:00
|
|
|
'group@muc.example.com',
|
|
|
|
{'nick': nick},
|
|
|
|
create_if_not_found
|
|
|
|
)
|
|
|
|
}
|
|
|
|
});
|
|
|
|
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
open
|
|
|
|
~~~~
|
|
|
|
|
|
|
|
Opens a multi user chat box and returns an object representing it.
|
2016-11-20 17:42:11 +01:00
|
|
|
Similar to the ``chats.get`` API.
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
It takes 2 parameters:
|
|
|
|
|
2016-11-20 17:42:11 +01:00
|
|
|
* The room JID or JIDs (if not specified, all currently open rooms will be returned).
|
|
|
|
* A map (object) containing any extra room attributes. For example, if you want
|
2016-10-21 16:33:47 +02:00
|
|
|
to specify the nickname, use ``{'nick': 'bloodninja'}``.
|
|
|
|
|
|
|
|
To open a single multi user chat box, provide the JID of the room:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.rooms.open('group@muc.example.com')
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To return an array of rooms, provide an array of room JIDs:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
To setup a custom nickname when joining the room, provide the optional nick argument:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
2016-11-20 17:42:11 +01:00
|
|
|
Room attributes that may be passed in:
|
|
|
|
|
|
|
|
* *nick*: The nickname to be used
|
|
|
|
* *auto_configure*: A boolean, indicating whether the room should be configured
|
|
|
|
automatically or not. If set to ``true``, then it makes sense to pass in
|
|
|
|
configuration settings.
|
|
|
|
* *roomconfig*: A map of configuration settings to be used when the room gets
|
|
|
|
configured automatically. Currently it doesn't make sense to specify
|
|
|
|
``roomconfig`` values if ``auto_configure`` is set to ``false``.
|
|
|
|
For a list of configuration values that can be passed in, refer to these values
|
|
|
|
in the `XEP-0045 MUC specification <http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner>`_.
|
|
|
|
The values should be named without the ``muc#roomconfig_`` prefix.
|
2016-11-30 11:00:12 +01:00
|
|
|
* *maximize*: A boolean, indicating whether minimized rooms should also be
|
|
|
|
maximized, when opened. Set to ``false`` by default.
|
2016-11-20 17:42:11 +01:00
|
|
|
|
|
|
|
For example, opening a room with a specific default configuration:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.rooms.open(
|
2016-12-20 10:31:11 +01:00
|
|
|
'myroom@conference.example.org',
|
|
|
|
{ 'nick': 'coolguy69',
|
|
|
|
'auto_configure': true,
|
|
|
|
'roomconfig': {
|
|
|
|
'changesubject': false,
|
|
|
|
'membersonly': true,
|
|
|
|
'persistentroom': true,
|
|
|
|
'publicroom': true,
|
|
|
|
'roomdesc': 'Comfy room for hanging out',
|
|
|
|
'whois': 'anyone'
|
|
|
|
}
|
|
|
|
},
|
|
|
|
true
|
|
|
|
);
|
|
|
|
|
|
|
|
}
|
|
|
|
});
|
|
|
|
|
2016-11-20 17:42:11 +01:00
|
|
|
|
|
|
|
.. note:: `multi-list` configuration values are not yet supported.
|
|
|
|
|
2016-10-21 16:33:47 +02:00
|
|
|
close
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
Lets you close open chat rooms. You can call this method without any arguments
|
|
|
|
to close all open chat rooms, or you can specify a single JID or an array of
|
|
|
|
JIDs.
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **settings** grouping
|
|
|
|
-------------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
This grouping allows you to get or set the configuration settings of converse.js.
|
|
|
|
|
|
|
|
get(key)
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
Returns the value of a configuration settings. For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
|
|
|
// default value would be false;
|
2017-04-19 15:00:59 +02:00
|
|
|
alert(this._converse.api.settings.get("play_sounds"));
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
set(key, value) or set(object)
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
Set one or many configuration settings. For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.settings.set("play_sounds", true);
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
or :
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
this._converse.api.settings.set({
|
2016-12-20 10:31:11 +01:00
|
|
|
"play_sounds", true,
|
|
|
|
"hide_offline_users" true
|
|
|
|
});
|
|
|
|
|
|
|
|
}
|
2016-10-21 16:33:47 +02:00
|
|
|
});
|
|
|
|
|
|
|
|
Note, this is not an alternative to calling ``converse.initialize``, which still needs
|
|
|
|
to be called. Generally, you'd use this method after converse.js is already
|
|
|
|
running and you want to change the configuration on-the-fly.
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **tokens** grouping
|
|
|
|
-----------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
get
|
|
|
|
~~~
|
|
|
|
|
|
|
|
Returns a token, either the RID or SID token depending on what's asked for.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2016-12-20 10:31:11 +01:00
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
alert(this._converse.api.tokens.get('rid'));
|
2016-12-20 10:31:11 +01:00
|
|
|
|
|
|
|
}
|
|
|
|
});
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
|
|
|
|
.. _`listen-grouping`:
|
|
|
|
|
2016-11-02 15:31:58 +01:00
|
|
|
The **listen** grouping
|
|
|
|
-----------------------
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
Converse.js emits events to which you can subscribe from your own Javascript.
|
|
|
|
|
|
|
|
Concerning events, the following methods are available under the "listen"
|
|
|
|
grouping:
|
|
|
|
|
|
|
|
* **on(eventName, callback, [context])**:
|
|
|
|
|
|
|
|
Calling the ``on`` method allows you to subscribe to an event.
|
|
|
|
Every time the event fires, the callback method specified by ``callback`` will be
|
|
|
|
called.
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
|
|
|
|
* ``eventName`` is the event name as a string.
|
|
|
|
* ``callback`` is the callback method to be called when the event is emitted.
|
|
|
|
* ``context`` (optional), the value of the `this` parameter for the callback.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.on('message', function (messageXML) { ... });
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
* **once(eventName, callback, [context])**:
|
|
|
|
|
|
|
|
Calling the ``once`` method allows you to listen to an event
|
|
|
|
exactly once.
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
|
|
|
|
* ``eventName`` is the event name as a string.
|
|
|
|
* ``callback`` is the callback method to be called when the event is emitted.
|
|
|
|
* ``context`` (optional), the value of the `this` parameter for the callback.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.once('message', function (messageXML) { ... });
|
2016-10-21 16:33:47 +02:00
|
|
|
|
|
|
|
* **not(eventName, callback)**
|
|
|
|
|
|
|
|
To stop listening to an event, you can use the ``not`` method.
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
|
|
|
|
* ``eventName`` is the event name as a string.
|
|
|
|
* ``callback`` refers to the function that is to be no longer executed.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
|
2017-04-19 15:00:59 +02:00
|
|
|
_converse.api.listen.not('message', function (messageXML) { ... });
|
2017-02-14 10:56:30 +01:00
|
|
|
|