diff --git a/Makefile b/Makefile
index cdff95931..021b62c38 100644
--- a/Makefile
+++ b/Makefile
@@ -227,6 +227,7 @@ check: eslint
html:
rm -rf $(BUILDDIR)/html
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ make apidoc
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b96619ec9..8c7ca6003 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
-# Converse.js documentation build configuration file, created by
+# Converse documentation build configuration file, created by
# sphinx-quickstart on Fri Apr 26 20:48:03 2013.
#
# This file is execfile()d with the current directory set to its containing dir.
@@ -40,8 +40,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
-project = u'Converse.js'
-copyright = u'2017, JC Brand'
+project = u'Converse'
+copyright = u'2018, JC Brand'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -108,7 +108,7 @@ html_logo = "_static/conversejs_small.png"
# theme further.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
- 'navbar_title': "Converse.js",
+ 'navbar_title': "Converse",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Table of Contents",
# A list of tuples containing pages or urls to link to.
@@ -229,7 +229,7 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'Conversejs.tex', u'Converse.js Documentation',
+ ('index', 'Conversejs.tex', u'Converse Documentation',
u'JC Brand', 'manual'),
]
@@ -259,7 +259,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'conversejs', u'Converse.js Documentation',
+ ('index', 'conversejs', u'Converse Documentation',
[u'JC Brand'], 1)
]
@@ -273,8 +273,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'Conversejs', u'Converse.js Documentation',
- u'JC Brand', 'Conversejs', 'Open Source XMPP webchat',
+ ('index', 'Conversejs', u'Converse Documentation',
+ u'JC Brand', 'Converse', 'Open Source XMPP webchat',
'Miscellaneous'),
]
diff --git a/docs/source/developer_api.rst b/docs/source/developer_api.rst
index d209429ad..75c3be1a3 100644
--- a/docs/source/developer_api.rst
+++ b/docs/source/developer_api.rst
@@ -2,12 +2,12 @@
-=============================
-The converse.js developer API
-=============================
+=========================
+The old API documentation
+=========================
-.. 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.
+.. 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
@@ -15,7 +15,7 @@ The converse.js developer API
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
+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
@@ -58,8 +58,8 @@ 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.js.
-This method must always be called when using converse.js.
+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`.
@@ -105,7 +105,7 @@ Registers a new plugin.
// Inside this method, you have access to the closured
// _converse object, which contains the core logic and data
- // structures of converse.js
+ // structures of Converse
}
}
converse.plugins.add('myplugin', plugin);
@@ -182,7 +182,7 @@ two important ways:
* 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:
+Converse has the following promises:
* :ref:`cachedRoster`
* :ref:`chatBoxesFetched`
@@ -210,7 +210,7 @@ already by that time.
The **archive** grouping
------------------------
-Converse.js supports the *Message Archive Management*
+Converse supports the *Message Archive Management*
(`XEP-0313 `_) protocol,
through which it is able to query an XMPP server for archived messages.
@@ -263,12 +263,12 @@ the returned messages.
**Waiting until server support has been determined**
-The query method will only work if converse.js has been able to determine that
+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.js loads in a browser tab, if you call the query
+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.
@@ -453,7 +453,7 @@ Paramters:
get
***
-Returns all of the identities registered for this client (i.e. instance of Converse.js).
+Returns all of the identities registered for this client (i.e. instance of Converse).
.. code-block:: javascript
@@ -473,17 +473,17 @@ Paramters:
* (String) name
* (String) lang
-Lets you add new identities for this client (i.e. instance of Converse.js).
+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.js');
+ _converse.api.disco.own.identities.add('client', 'web', 'Converse');
get
***
-Returns all of the identities registered for this client (i.e. instance of Converse.js).
+Returns all of the identities registered for this client (i.e. instance of Converse).
.. code-block:: javascript
@@ -602,7 +602,7 @@ Logs the user in. This method can accept a map with the credentials, like this:
}
});
-or it can be called without any parameters, in which case converse.js will try
+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.
@@ -877,40 +877,6 @@ To return an array of chats, provide an array of JIDs:
});
-*The returned chat object contains the following methods:*
-
-+-------------------+------------------------------------------+
-| Method | Description |
-+===================+==========================================+
-| close | Close the chat. |
-+-------------------+------------------------------------------+
-| focus | Focuses the chat 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. |
-+-------------------+------------------------------------------+
-| model.minimize | Maximize the chat. |
-+-------------------+------------------------------------------+
-| model.set | Set an attribute (i.e. mutator). |
-+-------------------+------------------------------------------+
-| show | Opens/shows the chat. |
-+-------------------+------------------------------------------+
-
-*The get and set methods can be used to retrieve and change the following attributes:*
-
-+-------------+-----------------------------------------------------+
-| Attribute | Description |
-+=============+=====================================================+
-| height | The height of the chat. |
-+-------------+-----------------------------------------------------+
-| url | The URL of the chat heading. |
-+-------------+-----------------------------------------------------+
-
The **chatviews** grouping
--------------------------
@@ -941,7 +907,7 @@ To return an array of views, provide an array of JIDs:
The **listen** grouping
-----------------------
-Converse.js emits events to which you can subscribe from your own JavaScript.
+Converse emits events to which you can subscribe from your own JavaScript.
Concerning events, the following methods are available under the "listen"
grouping:
@@ -1139,7 +1105,7 @@ JIDs.
The **promises** grouping
-------------------------
-Converse.js and its plugins emit various events which you can listen to via the
+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 `_,
@@ -1198,7 +1164,7 @@ For example:
The **settings** grouping
-------------------------
-This grouping allows access to the configuration settings of converse.js.
+This grouping allows access to the configuration settings of Converse.
.. _`settings-update`:
@@ -1279,7 +1245,7 @@ or :
});
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
+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
diff --git a/docs/source/development.rst b/docs/source/development.rst
index 1f116a860..3c7a7487d 100644
--- a/docs/source/development.rst
+++ b/docs/source/development.rst
@@ -8,13 +8,13 @@
Development
===========
-Welcome to the developer documentation of converse.js. Read the documentation
+Welcome to the developer documentation of Converse. Read the documentation
linked to below, if you want to add new features or create your own customized
-version of converse.js.
+version of Converse.
-Converse.js itself composed of plugins, and exposes an API with which you can
+Converse itself composed of plugins, and exposes an API with which you can
create and register your own plugins. This is the recommended way to customize
-or add new functionality to converse.js.
+or add new functionality to Converse.
.. toctree::
:maxdepth: 2
@@ -22,6 +22,7 @@ or add new functionality to converse.js.
developer_guidelines
style_guide
plugin_development
+ api/index
developer_api
events
other_frameworks
diff --git a/src/converse-chatboxes.js b/src/converse-chatboxes.js
index 361f3db51..8aab5742a 100644
--- a/src/converse-chatboxes.js
+++ b/src/converse-chatboxes.js
@@ -873,6 +873,11 @@
/************************ BEGIN API ************************/
_.extend(_converse.api, {
+ /**
+ * The "chats" grouping (used for one-on-one chats)
+ *
+ * @namespace
+ */
'chats': {
'create' (jids, attrs) {
if (_.isUndefined(jids)) {
@@ -882,7 +887,6 @@
);
return null;
}
-
if (_.isString(jids)) {
if (attrs && !_.get(attrs, 'fullname')) {
attrs.fullname = _.get(_converse.api.contacts.get(jids), 'attributes.fullname');
@@ -899,6 +903,40 @@
return _converse.chatboxes.getChatBox(jid, attrs, true).trigger('show');
});
},
+
+ /**
+ * Opens a new one-on-one chat.
+ *
+ * @function
+ *
+ * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
+ * @returns {Promise} Promise which resolves with the Backbone.Model representing the chat.
+ *
+ * @example
+ * // To open a single chat, provide the JID of the contact you're chatting with in that chat:
+ * 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
+ * });
+ * }
+ * });
+ *
+ * @example
+ * // To open an array of chats, provide an array of JIDs:
+ * 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
+ * });
+ * }
+ * });
+ *
+ */
'open' (jids, attrs) {
return new Promise((resolve, reject) => {
Promise.all([
@@ -917,6 +955,28 @@
}).catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
});
},
+
+ /**
+ * Returns a chat model. The chat should already be open.
+ *
+ * @function
+ *
+ * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
+ * @returns {Backbone.Model}
+ *
+ * @example
+ * // To return a single chat, provide the JID of the contact you're chatting with in that chat:
+ * const model = _converse.api.chats.get('buddy@example.com');
+ *
+ * @example
+ * // To return an array of chats, provide an array of JIDs:
+ * const models = _converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com']);
+ *
+ * @example
+ * // To return all open chats, call the method without any parameters::
+ * const models = _converse.api.chats.get();
+ *
+ */
'get' (jids) {
if (_.isUndefined(jids)) {
const result = [];