diff --git a/converse.js b/converse.js
index 48aa61745..2c0477436 100644
--- a/converse.js
+++ b/converse.js
@@ -4641,7 +4641,6 @@
var chatbox = converse.chatboxes.get(jid);
if (chatbox) {
return {
- 'attributes': chatbox.attributes,
'endOTR': chatbox.endOTR,
'get': chatbox.get,
'initiateOTR': chatbox.initiateOTR,
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 364b6c0d4..88e6511df 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -28,7 +28,7 @@ tags:
-You need to initialize Converse.js with configuration settings particular to
+You need to initialize Converse.js with configuration settings according to
your requirements.
Please refer to the `Configuration variables`_ section further below for info on
@@ -56,12 +56,11 @@ The `index.html `
Converse.js repository may serve as a nice usable example.
These minified files provide the same demo-like functionality as is available
-on the `conversejs.org `_ website. Useful for testing or demoing, but not very
-practical.
+on the `conversejs.org `_ website. Useful for testing or demoing.
-You'll most likely want to implement some kind of single-signon solution for
+You'll most likely want to implement some kind of single persistent session solution for
your website, where users authenticate once in your website and then stay
-logged into their XMPP session upon page reload.
+logged in to their XMPP session upon the next page reload.
For more info on this, read: `Prebinding and Single Session Support`_.
@@ -90,19 +89,106 @@ requirement for many sites dealing with sensitive information.
You'll need to set up your own XMPP server and in order to have
`Session Support`_ (i.e. single-signon functionality whereby users are authenticated once and stay
-logged in to XMPP upon page reload) you will also have to add some server-side
+logged in to XMPP upon page reload) you will likely also have to add some server-side
code.
The `What you will need`_ section has more information on all these
requirements.
+========
+Features
+========
+
+Off-the-record encryption
+=========================
+
+Converse.js supports `Off-the-record (OTR) `_
+encrypted messaging.
+
+The OTR protocol not only **encrypts your messages**, it provides ways to
+**verify the identity** of the person you are talking to,
+**plausible deniability** and **perfect forward secrecy** by generating
+new encryption keys for each conversation.
+
+In its current state, Javascript cryptography is fraught with dangers and
+challenges that make it impossible to reach the same standard of security that
+is available with native "desktop" software.
+
+This is due to its runtime malleability, the way it is "installed" (e.g.
+served) and the browser's lack of cryptographic primitives needed to implement
+secure crypto.
+
+For harsh but fairly valid criticism of Javascript cryptography, read:
+`Javascript Cryptography Considered Harmful `_.
+
+To get an idea on how this applies to OTR support in Converse.js, please read
+`my thoughts on it `_.
+
+For now, suffice to say that although its useful to have OTR support in
+Converse.js in order to avoid most eavesdroppers, if you need serious
+communications privacy, then you're much better off using native software.
+
+Sound Notifications
+===================
+
+From version 0.8.1 Converse.js can play a sound notification when you receive a
+message.
+
+For more info, please see the `play_sounds`_ configuration setting.
+
+Multilingual Support
+====================
+
+Converse.js is translated into multiple languages. The default build,
+``converse.min.js``, includes all languages.
+
+Languages increase the size of the Converse.js significantly.
+
+If you only need one, or a subset of the available languages, it's better to
+make a custom build which includes only those languages that you need.
+
+Chat Rooms
+==========
+
+Commands
+--------
+
+Here are the different commands that may be used in a chat room:
+
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| Event Type | When is it triggered? | Example (substitue $nickname with an actual user's nickname) |
++============+==============================================================================================+===============================================================+
+| **ban** | Ban a user from the chat room. They will not be able to join again. | /ban $nickname |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **clear** | Clear the messages shown in the chat room. | /clear |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **deop** | Make a moderator a normal participant. | /deop $nickname [$reason] |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **help** | Show the list of available commands. | /help |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **kick** | Kick a user out of a room. They will be able to join again. | /kick $nickname [$reason] |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **me** | Speak in the 3rd person. | /me $message |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **mute** | Remove a user's ability to post messages to the room. They will still be able to observe. | /mute $nickname [$reason] |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **nick** | Change your nickname. | /nick $nickname |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **op** | Make a normal participant a moderator. | /op $nickname [$reason] |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **topic** | Set the topic of the chat room. | /topic ${topic text} |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **voice** | Allow a muted user to post messages to the room. | /voice $nickname [$reason] |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+
+
==================
What you will need
==================
-An XMPP/Jabber server
-=====================
+An XMPP server
+==============
*Converse.js* implements `XMPP`_ as its messaging protocol, and therefore needs
to connect to an XMPP/Jabber server (Jabber is really just a synonym for XMPP).
@@ -288,92 +374,6 @@ Example code for server-side prebinding
See this `example Django application`_ by Jack Moffitt.
-========
-Features
-========
-
-Off-the-record encryption
-=========================
-
-Converse.js supports `Off-the-record (OTR) `_
-encrypted messaging.
-
-The OTR protocol not only **encrypts your messages**, it provides ways to
-**verify the identity** of the person you are talking to,
-**plausible deniability** and **perfect forward secrecy** by generating
-new encryption keys for each conversation.
-
-In its current state, Javascript cryptography is fraught with dangers and
-challenges that make it impossible to reach the same standard of security that
-is available with native "desktop" software.
-
-This is due to its runtime malleability, the way it is "installed" (e.g.
-served) and the browser's lack of cryptographic primitives needed to implement
-secure crypto.
-
-For harsh but fairly valid criticism of Javascript cryptography, read:
-`Javascript Cryptography Considered Harmful `_.
-
-To get an idea on how this applies to OTR support in Converse.js, please read
-`my thoughts on it `_.
-
-For now, suffice to say that although its useful to have OTR support in
-Converse.js in order to avoid most eavesdroppers, if you need serious
-communications privacy, then you're much better off using native software.
-
-Sound Notifications
-===================
-
-From version 0.8.1 Converse.js can play a sound notification when you receive a
-message.
-
-For more info, please see the `play_sounds`_ configuration setting.
-
-Multilingual Support
-====================
-
-Converse.js is translated into multiple languages. The default build,
-``converse.min.js``, includes all languages.
-
-Languages increase the size of the Converse.js significantly.
-
-If you only need one, or a subset of the available languages, it's better to
-make a custom build which includes only those languages that you need.
-
-Chat Rooms
-==========
-
-Commands
---------
-
-Here are the different commands that may be used in a chat room:
-
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| Event Type | When is it triggered? | Example (substitue $nickname with an actual user's nickname) |
-+============+==============================================================================================+===============================================================+
-| **ban** | Ban a user from the chat room. They will not be able to join again. | /ban $nickname |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **clear** | Clear the messages shown in the chat room. | /clear |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **deop** | Make a moderator a normal participant. | /deop $nickname [$reason] |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **help** | Show the list of available commands. | /help |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **kick** | Kick a user out of a room. They will be able to join again. | /kick $nickname [$reason] |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **me** | Speak in the 3rd person. | /me $message |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **mute** | Remove a user's ability to post messages to the room. They will still be able to observe. | /mute $nickname [$reason] |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **nick** | Change your nickname. | /nick $nickname |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **op** | Make a normal participant a moderator. | /op $nickname [$reason] |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **topic** | Set the topic of the chat room. | /topic ${topic text} |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-| **voice** | Allow a muted user to post messages to the room. | /voice $nickname [$reason] |
-+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
-
===========
Development
===========
@@ -511,6 +511,194 @@ You can run both the tests and jshint in one go by calling:
grunt check
+
+Developer API
+=============
+
+.. note:: see also the `event api methods`_, not listed here.
+
+initialize
+----------
+
+Initializes converse.js. This method must always be called when using
+converse.js.
+
+The `initialize` method takes a map (also called a hash or dictionary) of
+`configuration variables`_.
+
+Example::
+
+ 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
+ });
+
+
+getBuddy
+--------
+
+Returns a map of attributes for a given buddy (i.e. roster contact), specified
+by JID (Jabber ID).
+
+Example::
+
+ converse.getBuddy('buddy@example.com')
+
+The map of 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. |
++----------------+--------------------------------------------------------------------------------------------------------------------------------------+
+
+getRID
+------
+
+Returns the current RID (request ID) value.
+
+getSID
+------
+
+Returns the current SID (Session ID) value.
+
+
+Events
+======
+
+Converse.js emits events to which you can subscribe from your own Javascript.
+
+Concerning events, the following methods are available:
+
+Event API Methods
+-----------------
+
+* **on(eventName, callback)**:
+
+ 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.
+
+ For example::
+
+ converse.on('message', function (messageXML) { ... });
+
+* **once(eventName, callback)**:
+
+ 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.
+
+ For example::
+
+ converse.once('message', function (messageXML) { ... });
+
+* **off(eventName, callback)**
+
+ To stop listening to an event, you can use the ``off`` method.
+
+ Parameters:
+
+ * ``eventName`` is the event name as a string.
+ * ``callback`` refers to the function that is to be no longer executed.
+
+
+Event Types
+-----------
+
+Here are the different events that are emitted:
+
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| Event Type | When is it triggered? | Example |
++================================+===================================================================================================+=========================================================================================+
+| **initialized** | Once converse.js has been initialized. | ``converse.on('initialized', function () { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **ready** | After connection has been established and converse.js has got all its ducks in a row. | ``converse.on('ready', function () { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **reconnect** | After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode. | ``converse.on('reconnect', function () { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **message** | When a message is received. | ``converse.on('message', function (messageXML) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **messageSend** | When a message will be sent out. | ``converse.on('messageSend', function (messageText) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **noResumeableSession** | When keepalive=true but there aren't any stored prebind tokens. | ``converse.on('noResumeableSession', function () { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **roster** | When the roster is updated. | ``converse.on('roster', function (items) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **callButtonClicked** | When a call button (i.e. with class .toggle-call) on a chat box has been clicked. | ``converse.on('callButtonClicked', function (connection, model) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **chatBoxOpened** | When a chat box has been opened. | ``converse.on('chatBoxOpened', function (chatbox) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **chatRoomOpened** | When a chat room has been opened. | ``converse.on('chatRoomOpened', function (chatbox) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **chatBoxClosed** | When a chat box has been closed. | ``converse.on('chatBoxClosed', function (chatbox) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **chatBoxFocused** | When the focus has been moved to a chat box. | ``converse.on('chatBoxFocused', function (chatbox) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **chatBoxToggled** | When a chat box has been minimized or maximized. | ``converse.on('chatBoxToggled', function (chatbox) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **roomInviteSent** | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **roomInviteReceived** | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **statusChanged** | When own chat status has changed. | ``converse.on('statusChanged', function (status) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **statusMessageChanged** | When own custom status message has changed. | ``converse.on('statusMessageChanged', function (message) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **buddyStatusChanged** | When a chat buddy's chat status has changed. | ``converse.on('buddyStatusChanged', function (buddy, status) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| **buddyStatusMessageChanged** | When a chat buddy's custom status message has changed. | ``converse.on('buddyStatusMessageChanged', function (buddy, messageText) { ... });`` |
++--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+
+
+
Minification
============
@@ -643,6 +831,7 @@ Congratulations, you've now succesfully added your translations. Sorry for all
those hoops you had to jump through.
+
===============
Troubleshooting
===============
@@ -713,192 +902,6 @@ your own libraries, making sure that they are loaded in the correct order (e.g.
jQuery plugins must load after jQuery).
-======
-Events
-======
-
-Converse.js emits events to which you can subscribe from your own Javascript.
-
-Concerning events, the following methods are available:
-
-Event API Methods
-=================
-
-* **on(eventName, callback)**:
-
- 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.
-
- For example::
-
- converse.on('message', function (messageXML) { ... });
-
-* **once(eventName, callback)**:
-
- 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.
-
- For example::
-
- converse.once('message', function (messageXML) { ... });
-
-* **off(eventName, callback)**
-
- To stop listening to an event, you can use the ``off`` method.
-
- Parameters:
-
- * ``eventName`` is the event name as a string.
- * ``callback`` refers to the function that is to be no longer executed.
-
-
-Event Types
-===========
-
-Here are the different events that are emitted:
-
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| Event Type | When is it triggered? | Example |
-+==================================+===================================================================================================+=========================================================================================+
-| **initialized** | Once converse.js has been initialized. | ``converse.on('initialized', function () { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **ready** | After connection has been established and converse.js has got all its ducks in a row. | ``converse.on('ready', function () { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **reconnect** | After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode. | ``converse.on('reconnect', function () { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **message** | When a message is received. | ``converse.on('message', function (messageXML) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **messageSend** | When a message will be sent out. | ``converse.on('messageSend', function (messageText) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **noResumeableSession** | When keepalive=true but there aren't any stored prebind tokens. | ``converse.on('noResumeableSession', function () { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roster** | When the roster is updated. | ``converse.on('roster', function (items) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **callButtonClicked** | When a call button (i.e. with class .toggle-call) on a chat box has been clicked. | ``converse.on('callButtonClicked', function (connection, model) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxOpened** | When a chat box has been opened. | ``converse.on('chatBoxOpened', function (chatbox) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatRoomOpened** | When a chat room has been opened. | ``converse.on('chatRoomOpened', function (chatbox) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxClosed** | When a chat box has been closed. | ``converse.on('chatBoxClosed', function (chatbox) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxFocused** | When the focus has been moved to a chat box. | ``converse.on('chatBoxFocused', function (chatbox) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **chatBoxToggled** | When a chat box has been minimized or maximized. | ``converse.on('chatBoxToggled', function (chatbox) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roomInviteSent** | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **roomInviteReceived** | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.on('roomInvite', function (roomview, invitee_jid, reason) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **statusChanged** | When own chat status has changed. | ``converse.on('statusChanged', function (status) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **statusMessageChanged** | When own custom status message has changed. | ``converse.on('statusMessageChanged', function (message) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **buddyStatusChanged** | When a chat buddy's chat status has changed. | ``converse.on('buddyStatusChanged', function (buddy, status) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| **buddyStatusMessageChanged** | When a chat buddy's custom status message has changed. | ``converse.on('buddyStatusMessageChanged', function (buddy, messageText) { ... });`` |
-+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-
-=============
-Developer API
-=============
-
-.. note:: see also the `event api methods`_, not listed here.
-
-initialize
-==========
-
-Initializes converse.js. This method must always be called when using
-converse.js.
-
-The `initialize` method takes a map (also called a hash or dictionary) of
-`configuration variables`_.
-
-Example::
-
- 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
- });
-
-
-getBuddy
-========
-
-Returns a map of attributes for a given buddy (i.e. roster contact), specified
-by JID (Jabber ID).
-
-Example::
-
- converse.getBuddy('buddy@example.com')
-
-The map of 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. |
-+----------------+--------------------------------------------------------------------------------------------------------------------------------------+
-
-getRID
-======
-
-Returns the current RID (request ID) value.
-
-getSID
-======
-
-Returns the current SID (Session ID) value.
-
=============
Configuration
=============