From 48dd0cc674a1a1c08b737879a4a4971ed06fbf17 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Sun, 12 Oct 2014 10:42:07 +0200 Subject: [PATCH] Trying to organize doc chapters a bit more logically. --- converse.js | 1 - docs/source/index.rst | 563 +++++++++++++++++++++--------------------- 2 files changed, 283 insertions(+), 281 deletions(-) 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 =============