Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
24
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Trying to organize doc chapters a bit more logically.

Browse Source
This commit is contained in:
JC Brand 2014-10-12 10:42:07 +02:00
parent 5b46e27c41
commit 48dd0cc674
2 changed files with 283 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
converse.js
View File

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

563
docs/source/index.rst
View File

@ -28,7 +28,7 @@ tags:
<link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
<script src="builds/converse.min.js"></script>
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 <https://github.com/jcbrand/converse.js/blob/master/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 <http://conversejs.org>`_ website. Useful for testing or demoing, but not very
practical.
on the `conversejs.org <http://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) <https://otr.cypherpunks.ca/>`_
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 <http://www.matasano.com/articles/javascript-cryptography/>`_.
To get an idea on how this applies to OTR support in Converse.js, please read
`my thoughts on it <https://opkode.com/media/blog/2013/11/11/conversejs-otr-support>`_.
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) <https://otr.cypherpunks.ca/>`_
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 <http://www.matasano.com/articles/javascript-cryptography/>`_.
To get an idea on how this applies to OTR support in Converse.js, please read
`my thoughts on it <https://opkode.com/media/blog/2013/11/11/conversejs-otr-support>`_.
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
=============