Remove old API and events docs

docs/source/configuration.rst

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

docs/source/developer_api.rst

@@ -1,1360 +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>
-
-=========================
-The old API documentation
-=========================
-
-.. note:: The API documented here is available in Converse 0.8.4 and higher.
-        Earlier versions of Converse might have different API methods or none at all.
-
-.. 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 API is broken up into different logical "groupings" (for
-example ``converse.plugins`` or ``converse.contacts``).
-
-There are some exceptions to this, like ``converse.initialize``, which aren't
-groupings but single methods.
-
-The groupings logically group methods, such as standardised accessors and
-mutators::
-
-    .get
-    .set
-    .add
-    .remove
-
-So for example, to get a contact, you would do the following::
-
-    _converse.api.contacts.get('jid@example.com');
-
-To get multiple contacts, just pass in an array of jids::
-
-    _converse.api.contacts.get(['jid1@example.com', 'jid2@example.com']);
-
-To get all contacts, simply call ``get`` without any jids::
-
-    _converse.api.contacts.get();
-
-
-Public API methods
-==================
-
-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.
-
-.. _`initialize`:
-
-initialize
-----------
-
-.. note:: This method is the one exception of a method which is not logically grouped as explained above.
-
-Publich API method which initializes Converse.
-This method must always be called when using Converse.
-
-The `initialize` method takes a map of :ref:`configuration-settings`.
-
-Example:
-
-.. code-block:: javascript
-
-    converse.initialize({
-            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
-        });
-
-
-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
-        }
-    }
-    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.
-
-emit
-----
-
-This method allows you to emit events, which can be listened to via
-``_converse.api.listen.on`` or ``_converse.api.listen.once``.
-
-For example:
-
-.. code-block:: javascript
-
-    _converse.api.trigger('foo-completed');
-
-Additionally, if a promise has been registered under the same name
-(via ``_converse.api.promises.add``), then that promise will also be resolved
-when calling ``emit``.
-
-send
-----
-
-Allows you to send XML stanzas.
-
-For example, to send a message stanza:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var msg = converse.env.$msg({
-                from: 'juliet@example.com/balcony',
-                to:'romeo@example.net',
-                type:'chat'
-            });
-            this._converse.api.send(msg);
-
-        }
-    });
-
-.. _`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 has the following promises:
-
-* :ref:`cachedRoster`
-* :ref:`chatBoxesFetched`
-* :ref:`pluginsInitialized`
-* :ref:`roster`
-* :ref:`rosterContactsFetched`
-* :ref:`rosterGroupsFetched`
-* :ref:`rosterInitialized`
-* :ref:`statusInitialized`
-* :ref:`roomsPanelRendered` (only via the `converse-muc` plugin)
-
-Below is an example from `converse-muc.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-muc.js>`_
-where the `rosterContactsFetched` promise is waited on. The method
-`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.
-
-
-The **archive** grouping
-------------------------
-
-Converse 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-settings` 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
-
-    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.
-            }
-            this._converse.api.archive.query(callback, errback))
-
-        }
-    });
-
-
-**Waiting until server support has been determined**
-
-The query method will only work if Converse 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 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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var _converse = this._converse;
-            _converse.api.listen.on('serviceDiscovered', function (feature) {
-                if (feature.get('var') === converse.env.Strophe.NS.MAM) {
-                    _converse.api.archive.query()
-                }
-            });
-
-    converse.listen.on('serviceDiscovered', function (feature) {
-        if (feature.get('var') === converse.env.Strophe.NS.MAM) {
-            converse.archive.query()
-        }
-    });
-
-**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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            // For a particular user
-            this._converse.api.archive.query({'with': 'john@doe.net'}, callback, errback);)
-
-            // For a particular room
-            this._converse.api.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
-
-        }
-    });
-
-
-**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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var options = {
-                'with': 'john@doe.net',
-                'start': '2010-06-07T00:00:00Z',
-                'end': '2010-07-07T13:23:54Z'
-            };
-            this._converse.api.archive.query(options, callback, errback);
-
-        }
-    });
-
-
-**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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            // Return maximum 10 archived messages
-            this._converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
-
-        }
-    });
-
-**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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            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:
-                _converse.api.archive.query(rsm.next(10), callback, errback))
-
-            }
-            _converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
-
-        }
-    });
-
-**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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var _converse = this._converse;
-            _converse.api.archive.query({'before': '', 'max':5}, function (message, rsm) {
-                // 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.
-                _converse.api.archive.query(rsm, callback, errback);
-            }
-
-        }
-    });
-
-The **connection** grouping
----------------------------
-
-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.
-
-
-The **disco** grouping
-----------------------
-
-This grouping collects API functions related to `service discovery
-<https://xmpp.org/extensions/xep-0030.html>`_.
-
-The **disco.own** grouping
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The **disco.own.features** grouping
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-add
-***
-
-Paramters:
-
-* (String) name
-
-get
-***
-
-Returns all of the identities registered for this client (i.e. instance of Converse).
-
-.. code-block:: javascript
-
-    const identities = _converse.api.disco.own.identities.get();
-
-
-The **disco.own.identities** grouping
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-add
-***
-
-Paramters:
-
-* (String) category
-* (String) type
-* (String) name
-* (String) lang
-
-Lets you add new identities for this client (i.e. instance of Converse).
-
-.. code-block:: javascript
-
-    _converse.api.disco.own.identities.add('client', 'web', 'Converse');
-
-
-get
-***
-
-Returns all of the identities registered for this client (i.e. instance of Converse).
-
-.. code-block:: javascript
-
-    const identities = _converse.api.disco.own.identities.get();
-
-clear
-*****
-
-Clears all previously set identities.
-
-
-getIdentity
-~~~~~~~~~~~
-
-Paramters:
-
-* (String) category
-* (String) type
-* (String) entity JID
-
-Get the identity (with the given category and type) for a given disco entity.
-
-For example, when determining support for PEP (personal eventing protocol), you
-want to know whether the user's own JID has an identity with
-``category='pubsub'`` and ``type='pep'`` as explained in this section of
-XEP-0163: https://xmpp.org/extensions/xep-0163.html#support
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            _converse.api.disco.getIdentity('pubsub', 'pep', _converse.bare_jid).then(
-                function (identity) {
-                    if (_.isNil(identity)) {
-                        // The entity DOES NOT have this identity
-                    } else {
-                        // The entity DOES have this identity
-                    }
-                }
-            ).catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
-        }
-    });
-
-supports
-~~~~~~~~
-
-Used to determine whether an entity supports a given feature.
-
-Returns a `Promise` which, when resolved, returns a map/object with keys
-`supported` (a boolean) and `feature` which is a `Backbone.Model <http://backbonejs.org/#Model>`_.
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            _converse.api.disco.supports(Strophe.NS.MAM, _converse.bare_jid)
-            .then(value => {
-                // `value` is a map with two keys, `supported` and `feature`.
-                if (value.supported) {
-                    // The feature is supported
-                } else {
-                    // The feature is not supported
-                }
-            }).catch(() => {
-                _converse.log(
-                    "Error or timeout while checking for feature support",
-                    Strophe.LogLevel.ERROR
-                );
-            });
-        }
-    });
-
-
-The **user** grouping
----------------------
-
-This grouping collects API functions related to the current logged in user.
-
-jid
-~~~
-
-Returns the current user's full JID (Jabber ID).
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            alert(this._converse.api.user.jid());
-
-        }
-    });
-
-login
-~~~~~
-
-Logs the user in. This method can accept a map with the credentials, like this:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.user.login({
-                'jid': 'dummy@example.com',
-                'password': 'secret'
-            });
-
-        }
-    });
-
-or it can be called without any parameters, in which case Converse 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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.user.logout();
-
-        }
-    });
-
-
-The **status** sub-grouping
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Set and get the user's chat status, also called their *availability*.
-
-get
-^^^
-
-Return the current user's availability status:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            alert(this._converse.api.user.status.get()); // For example "dnd"
-
-        }
-    });
-
-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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.user.status.set('dnd');
-
-        }
-    });
-
-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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.user.status.set('dnd', 'In a meeting');
-
-        }
-    });
-
-The **message** sub-grouping
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``user.status.message`` sub-grouping exposes methods for setting and
-retrieving the user's custom status message.
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-            this._converse.api.user.status.message.set('In a meeting');
-            // Returns "In a meeting"
-            return this._converse.api.user.status.message.get();
-        }
-    });
-
-
-The **contacts** grouping
--------------------------
-
-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
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var _converse = this._converse;
-            _converse.api.listen.on('rosterContactsFetched', function () {
-                var contact = _converse.api.contacts.get('buddy@example.com')
-            });
-
-        }
-    });
-
-To get multiple contacts, pass in an array of JIDs:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var _converse = this._converse;
-            _converse.api.listen.on('rosterContactsFetched', function () {
-                var contacts = _converse.api.contacts.get(
-                    ['buddy1@example.com', 'buddy2@example.com']
-                )
-            });
-
-        }
-    });
-
-To return all contacts, simply call ``get`` without any parameters:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            var _converse = this._converse;
-            _converse.api.listen.on('rosterContactsFetched', function () {
-                var contacts = _converse.api.contacts.get();
-            });
-
-        }
-    });
-
-
-The returned roster contact is a `Backbone.Model <http://backbonejs.org/#Model>`_ of type _converse.RosterContacts.
-
-It has the following attributes (which should be accessed via `get <http://backbonejs.org/#Model-get>`_).
-
-+----------------+-----------------------------------------------------------------------------------------------------------------+
-| 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
-
-    _converse.api.contacts.add('buddy@example.com')
-
-You may also provide the fullname. If not present, we use the jid as fullname:
-
-.. code-block:: javascript
-
-    _converse.api.contacts.add('buddy@example.com', 'Buddy')
-
-The **chats** grouping
-----------------------
-
-Note, for MUC chatrooms, you need to use the "rooms" grouping instead.
-
-get
-~~~
-
-Returns an object representing a chat. The chat should already be open.
-
-To return a single chat, provide the JID of the contact you're chatting
-with in that chat:
-
-.. code-block:: javascript
-
-    _converse.api.chats.get('buddy@example.com')
-
-To return an array of chats, provide an array of JIDs:
-
-.. code-block:: javascript
-
-    _converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com'])
-
-To return all open chats, call the method without any JIDs::
-
-    _converse.api.chats.get()
-
-open
-~~~~
-
-Opens a new chat.
-
-It returns an promise which will resolve with a `Backbone.Model <https://backbonejs.org/#Model>`_ representing the chat.
-
-Note that converse doesn't allow opening chats with users who aren't in your roster
-(unless you have set :ref:`allow_non_roster_messaging` to ``true``).
-
-These two events fire only once per session, so they're also available as promises.
-
-So, to open a single chat:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function() {
-            var _converse = this._converse;
-
-            // Note, buddy@example.org must be in your contacts roster!
-            _converse.api.chats.open('buddy@example.com').then((chat) => {
-                // Now you can do something with the chat model
-            });
-        }
-    });
-
-To return an array of chats, provide an array of JIDs:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-            var _converse = this._converse;
-            // Note, these users must first be in your contacts roster!
-            _converse.api.chats.open(['buddy1@example.com', 'buddy2@example.com']).then((chats) => {
-                // Now you can do something with the chat models
-            });
-        }
-    });
-
-
-The **chatviews** grouping
---------------------------
-
-.. note:: This is only for private chats.
-
-get
-~~~
-
-Returns a `Backbone.View <http://backbonejs.org/#View>`_ of type _converse.ChatBoxView.
-
-The chat should already be open, otherwise `undefined` will be returned.
-
-To return a single view, provide the JID of the contact:
-
-.. code-block:: javascript
-
-    _converse.api.chatviews.get('buddy@example.com')
-
-To return an array of views, provide an array of JIDs:
-
-.. code-block:: javascript
-
-    _converse.api.chatviews.get(['buddy1@example.com', 'buddy2@example.com'])
-
-
-.. _`listen-grouping`:
-
-The **listen** grouping
------------------------
-
-Converse emits events to which you can subscribe to.
-
-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
-
-        _converse.api.listen.on('message', function (messageXML) { ... });
-
-* **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
-
-        _converse.api.listen.once('message', function (messageXML) { ... });
-
-* **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
-
-        _converse.api.listen.not('message', function (messageXML) { ... });
-
-
-The **rooms** grouping
-----------------------
-
-get
-~~~
-
-Returns an object representing a multi user chat (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
-
-    converse.plugins.add('myplugin', {
-
-        initialize: function () {
-            var _converse = this._converse;
-            _converse.api.waitUntil('roomsAutoJoined').then(function () {
-                var create_if_not_found = true;
-                this._converse.api.rooms.get(
-                    'group@muc.example.com',
-                    {'nick': 'dread-pirate-roberts'},
-                    create_if_not_found
-                )
-            });
-        }
-    });
-
-open
-~~~~
-
-Opens a multi user chat and returns an object representing it.
-Similar to the ``chats.get`` API.
-
-It takes 2 parameters:
-
-* 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
-  to specify the nickname, use ``{'nick': 'bloodninja'}``.
-
-To open a single multi user chat, provide the JID of the room:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.rooms.open('group@muc.example.com')
-
-        }
-    });
-
-To return an array of rooms, provide an array of room JIDs:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
-
-        }
-    });
-
-To setup a custom nickname when joining the room, provide the optional nick argument:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
-
-        }
-    });
-
-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 <https://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner>`_.
-  The values should be named without the ``muc#roomconfig_`` prefix.
-* *maximize*: A boolean, indicating whether minimized rooms should also be
-  maximized, when opened. Set to ``false`` by default.
-* *bring_to_foreground*: A boolean indicating whether the room should be
-  brought to the foreground and therefore replace the currently shown chat.
-  If there is no chat currently open, then this option is ineffective.
-
-For example, opening a room with a specific default configuration:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.rooms.open(
-                '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
-            );
-
-        }
-    });
-
-
-.. note:: `multi-list` configuration values are not yet supported.
-
-close
-~~~~~
-
-Lets you close open chatrooms. You can call this method without any arguments
-to close all open chatrooms, or you can specify a single JID or an array of
-JIDs.
-
-.. _`promises-grouping`:
-
-The **promises** grouping
--------------------------
-
-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:
-
-* :ref:`cachedRoster`
-* :ref:`chatBoxesFetched`
-* :ref:`pluginsInitialized`
-* :ref:`roster`
-* :ref:`rosterContactsFetched`
-* :ref:`rosterGroupsFetched`
-* :ref:`rosterInitialized`
-* :ref:`statusInitialized`
-* :ref:`roomsPanelRendered` (only via the `converse-muc` plugin)
-
-The various plugins might also provide promises, and they do this by using the
-``promises.add`` api method.
-
-add(promises)
-~~~~~~~~~~~~~
-
-By calling ``promises.add``, a new promise is made available for other code or
-plugins to depend on via the ``_converse.api.waitUntil`` method.
-
-This method accepts either a string or list of strings which specify the
-promise(s) to be added.
-
-For example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-            this._converse.api.promises.add('foo-completed');
-        }
-    });
-
-Generally, it's the responsibility of the plugin which adds the promise to
-also resolve it.
-
-This is done by calling ``_converse.api.emit``, which not only resolve the
-promise, but also emit an event with the same name (which can be listened to
-via ``_converse.api.listen``).
-
-For example:
-
-.. code-block:: javascript
-
-    _converse.api.trigger('foo-completed');
-
-
-The **settings** grouping
--------------------------
-
-This grouping allows access to the configuration settings of Converse.
-
-.. _`settings-update`:
-
-update(settings)
-~~~~~~~~~~~~~~~~
-
-Allows new configuration settings to be specified, or new default values for
-existing configuration settings to be specified.
-
-For example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-            this._converse.api.settings.update({
-                'enable_foo': true
-            });
-        }
-    });
-
-The user can then override the default value of the configuration setting when
-calling `converse.initialize`.
-
-For example:
-
-.. code-block:: javascript
-
-    converse.initialize({
-        'enable_foo': false
-    });
-
-
-get(key)
-~~~~~~~~
-
-Returns the value of the particular configuration setting. For example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            // default value would be false;
-            alert(this._converse.api.settings.get("play_sounds"));
-
-        }
-    });
-
-set(key, value) or set(object)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Set one or many configuration settings. For example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.settings.set("play_sounds", true);
-
-        }
-    });
-
-or :
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            this._converse.api.settings.set({
-                "play_sounds", true,
-                "hide_offline_users" true
-            });
-
-        }
-    });
-
-Note, this is not an alternative to calling ``converse.initialize``, which still needs
-to be called. Generally, you'd use this method after Converse is already
-running and you want to change the configuration on-the-fly.
-
-The **tokens** grouping
------------------------
-
-get
-~~~
-
-Returns a token, either the RID or SID token depending on what's asked for.
-
-Example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            alert(this._converse.api.tokens.get('rid'));
-
-        }
-    });
-
-
-The **vcard** grouping
------------------------
-
-get
-~~~
-
-Parameters:
-
-* ``model`` either a `Backbone.Model` instance, or a string JID.
-* ``force`` (optional), a boolean indicating whether the vcard should be
-  fetched even if it's been fetched before.
-
-Returns a Promise which results with the VCard data for a particular JID or for
-a `Backbone.Model` instance which represents an entity with a JID (such as a roster contact,
-chat or chatroom occupant).
-
-If a `Backbone.Model` instance is passed in, then it must have either a `jid`
-attribute or a `muc_jid` attribute.
-
-Example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            _converse.api.waitUntil('rosterContactsFetched').then(() => {
-                this._converse.api.vcard.get('someone@example.org').then(
-                    (vcard) => {
-                        // Do something with the vcard...
-                    }
-                );
-            });
-
-        }
-    });
-
-set
-~~~
-
-Parameters:
-
-* ``data`` a map of VCard keys and values
-
-Enables setting new values for a VCard.
-
-Example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            _converse.api.waitUntil('rosterContactsFetched').then(() => {
-                this._converse.api.vcard.set({
-                    'jid': 'someone@example.org',
-                    'fn': 'Someone Somewhere',
-                    'nickname': 'someone'
-                }).then(() => {
-                    // Succes
-                }).catch(() => {
-                    // Failure
-                }).
-            });
-
-        }
-    });
-
-update
-~~~~~~
-
-Parameters:
-
-* ``model`` a `Backbone.Model` instance
-* ``force`` (optional), a boolean indicating whether the vcard should be
-  fetched again even if it's been fetched before.
-
-Fetches the VCard associated with a particular `Backbone.Model` instance
-(by using its `jid` or `muc_jid` attribute) and then updates the model with the
-returned VCard data.
-
-Returns a promise;
-
-Example:
-
-.. code-block:: javascript
-
-    converse.plugins.add('myplugin', {
-        initialize: function () {
-
-            _converse.api.waitUntil('rosterContactsFetched').then(() => {
-                const chatbox = _converse.chatboxes.getChatBox('someone@example.org');
-                _converse.api.vcard.update(chatbox);
-            });
-        }
-    });

docs/source/events.rst

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

docs/source/jsdoc_intro.md

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

docs/source/plugin_development.rst

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