Skip to content

C
converse.js
Commit 6100aaf1 authored by JC Brand's avatar JC Brand
Browse files
Options

Refactor the API. updates #46 

API methods now consist of simple accessors and mutators that are logically
grouped.
parent 36db4c8b
Show whitespace changes
Inline Side-by-side
Showing with 1394 additions and 936 deletions
converse.js
View file @ 6100aaf1
......@@ -4713,53 +4713,86 @@
'initiateOTR': $.proxy(chatbox.initiateOTR, chatbox),
'maximize': $.proxy(chatbox.maximize, chatbox),
'minimize': $.proxy(chatbox.minimize, chatbox),
'set': $.proxy(chatbox.set, chatbox)
'set': $.proxy(chatbox.set, chatbox),
'open': chatbox.trigger.bind(chatbox, 'show')
};
};
return {
'getBuddy': function (jid) {
'initialize': function (settings, callback) {
converse.initialize(settings, callback);
},
'contacts': {
'get': function (jids) {
var _transform = function (jid) {
var contact = converse.roster.get(Strophe.getBareJidFromJid(jid));
if (contact) {
return contact.attributes;
}
return null;
};
if (typeof jids === "string") {
return _transform(jids);
}
return _.map(jids, _transform);
}
},
'getChatBox': function (jid) {
'chats': {
'get': function (jids) {
var _transform = function (jid) {
var chatbox = converse.chatboxes.get(jid);
if (chatbox) {
if (!chatbox) {
var roster_item = converse.roster.get(jid);
if (roster_item === undefined) {
converse.log('Could not get roster item for JID '+jid, 'error');
return null;
}
chatbox = converse.chatboxes.create({
'id': jid,
'jid': jid,
'fullname': _.isEmpty(roster_item.get('fullname'))? jid: roster_item.get('fullname'),
'image_type': roster_item.get('image_type'),
'image': roster_item.get('image'),
'url': roster_item.get('url')
});
}
return wrappedChatBox(chatbox);
};
if (typeof jids === "string") {
return _transform(jids);
}
},
'getRID': function () {
if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
return converse.connection.rid || converse.connection._proto.rid;
return _.map(jids, _transform);
}
return null;
},
'getSID': function () {
if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
'tokens': {
'get': function (id) {
if (!converse.expose_rid_and_sid || typeof converse.connection === "undefined") {
return null;
}
if (id.toLowerCase() === 'rid') {
return converse.connection.rid || converse.connection._proto.rid;
} else if (id.toLowerCase() === 'sid') {
return converse.connection.sid || converse.connection._proto.sid;
}
return null;
},
'initialize': function (settings, callback) {
converse.initialize(settings, callback);
},
'jQuery': $,
'openChatBox': function (jid) {
var contact = converse.roster.get(Strophe.getBareJidFromJid(jid));
if (contact) {
return wrappedChatBox(converse.chatboxviews.showChat(contact.attributes));
}
},
'listen': {
'once': function (evt, handler) {
converse.once(evt, handler);
},
'on': function (evt, handler) {
converse.on(evt, handler);
},
'off': function (evt, handler) {
'not': function (evt, handler) {
converse.off(evt, handler);
},
},
'plugins': {
'add': function (name, callback) {
converse.plugins[name] = callback;
},
'remove': function (name) {
delete converse.plugins[name];
},
'override': function (obj, attributes) {
/* Helper method for overriding or extending Converse's Backbone Views or Models
*
......@@ -4782,9 +4815,48 @@
obj.prototype[key] = value;
}
});
}
},
'registerPlugin': function (name, callback) {
converse.plugins[name] = callback;
'env': {
'jQuery': $,
'Strophe': Strophe,
'_': _
},
// Deprecated API methods
'getBuddy': function (jid) {
converse.log('WARNING: the "getBuddy" API method has been deprecated. Please use "contacts.get" instead');
return this.contacts.get(jid);
},
'getChatBox': function (jid) {
converse.log('WARNING: the "getChatBox" API method has been deprecated. Please use "chats.get" instead');
return this.chats.get(jid);
},
'openChatBox': function (jid) {
converse.log('WARNING: the "openChatBox" API method has been deprecated. Please use "chats.get(jid).open()" instead');
var chat = this.chats.get(jid);
if (chat) { chat.open(); }
return chat;
},
'getRID': function () {
converse.log('WARNING: the "getRID" API method has been deprecated. Please use "tokens.get(\'rid\')" instead');
return this.tokens.get('rid');
},
'getSID': function () {
converse.log('WARNING: the "getSID" API method has been deprecated. Please use "tokens.get(\'sid\')" instead');
return this.tokens.get('sid');
},
'once': function (evt, handler) {
converse.log('WARNING: the "one" API method has been deprecated. Please use "listen.once" instead');
return this.listen.once(evt, handler);
},
'on': function (evt, handler) {
converse.log('WARNING: the "on" API method has been deprecated. Please use "listen.on" instead');
return this.listen.on(evt, handler);
},
'off': function (evt, handler) {
converse.log('WARNING: the "off" API method has been deprecated. Please use "listen.not" instead');
return this.listen.not(evt, handler);
}
};
}));
docs/html/_sources/index.txt
View file @ 6100aaf1
......@@ -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
===========
......@@ -459,57 +459,321 @@ parsed.
Without AMD and require.js
==========================
Converse.js can also be used without require.js. If you for some reason prefer
to use it this way, please refer to
`non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
for an example of how and in what order all the Javascript files that converse.js
depends on need to be loaded.
Converse.js can also be used without require.js. If you for some reason prefer
to use it this way, please refer to
`non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
for an example of how and in what order all the Javascript files that converse.js
depends on need to be loaded.
Before submitting a pull request
================================
Add tests for your bugfix or feature
------------------------------------
Add a test for any bug fixed or feature added. We use Jasmine
for testing.
Take a look at ``tests.html`` and ``spec/MainSpec.js`` to see how
the tests are implemented.
If you are unsure how to write tests, please
`contact me <http://opkode.com/contact>`_ and I'll be happy to help.
Check that the tests pass
-------------------------
Check that the Jasmine tests complete sucessfully. Open
`tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
in your browser, and the tests will run automatically.
On the command line you can run:
::
grunt test
Check your code for errors or bad habits by running JSHint
----------------------------------------------------------
`JSHint <http://jshint.com>`_ will do a static analysis of your code and hightlight potential errors
and/or bad habits.
::
grunt jshint
You can run both the tests and jshint in one go by calling:
::
grunt check
Developer API
=============
.. note:: The API documented here is available in Converse.js 0.8.4 and higher.
Earlier versions of Converse.js might have different API methods or none at all.
In the Converse.js API, you traverse towards a logical grouping, from
which you can then call certain standardised accessors and mutators, like::
.get
.set
.add
.all
.remove
This is done to increase readability and to allow intuitive method chaining.
For example, to get a contact, you would do the following::
converse.contacts.get('jid@example.com');
To get multiple contacts, just pass in an array of jids::
converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
**Here follows now a breakdown of all API groupings and methods**:
initialize
----------
.. note:: This method is the one exception of a method which is not logically grouped
as explained above.
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
});
"contacts" grouping
-------------------
get
~~~
Returns a map of attributes for a given buddy (i.e. roster contact), specified
by JID (Jabber ID).
Example::
converse.contacts.get('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. |
+----------------+--------------------------------------------------------------------------------------------------------------------------------------+
"chats" grouping
----------------
get
~~~
Returns an object/map representing a chat box (without opening or affecting that chat box).
Example::
converse.chats.get('buddy@example.com')
*The returned chat box contains the following methods:*
+-------------+------------------------------------------+
| Method | Description |
+=============+==========================================+
| endOTR | End an OTR (Off-the-record) session. |
+-------------+------------------------------------------+
| get | Get an attribute (i.e. accessor). |
+-------------+------------------------------------------+
| initiateOTR | Start an OTR (off-the-record) session. |
+-------------+------------------------------------------+
| maximize | Minimize the chat box. |
+-------------+------------------------------------------+
| minimize | Maximize the chat box. |
+-------------+------------------------------------------+
| set | Set an attribute (i.e. mutator). |
+-------------+------------------------------------------+
*The get and set methods can be used to retrieve and change the following attributes:*
+-------------+-----------------------------------------------------+
| Attribute | Description |
+=============+=====================================================+
| height | The height of the chat box. |
+-------------+-----------------------------------------------------+
| url | The URL of the chat box heading. |
+-------------+-----------------------------------------------------+
"tokens" grouping
-----------------
get
~~~
Returns a token, either the RID or SID token depending on what's asked for.
Example::
converse.tokens.get('rid')
"listen" grouping
-----------------
Converse.js emits events to which you can subscribe from your own Javascript.
Concerning events, the following methods are available under the "listen"
grouping:
* **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::
Before submitting a pull request
================================
converse.listen.on('message', function (messageXML) { ... });
Add tests for your bugfix or feature
------------------------------------
* **once(eventName, callback)**:
Add a test for any bug fixed or feature added. We use Jasmine
for testing.
Calling the ``once`` method allows you to listen to an event
exactly once.
Take a look at ``tests.html`` and ``spec/MainSpec.js`` to see how
the tests are implemented.
Parameters:
If you are unsure how to write tests, please
`contact me <http://opkode.com/contact>`_ and I'll be happy to help.
* ``eventName`` is the event name as a string.
* ``callback`` is the callback method to be called when the event is emitted.
Check that the tests pass
-------------------------
For example::
Check that the Jasmine tests complete sucessfully. Open
`tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
in your browser, and the tests will run automatically.
converse.listen.once('message', function (messageXML) { ... });
On the command line you can run:
* **not(eventName, callback)**
::
To stop listening to an event, you can use the ``not`` method.
grunt test
Parameters:
Check your code for errors or bad habits by running JSHint
----------------------------------------------------------
* ``eventName`` is the event name as a string.
* ``callback`` refers to the function that is to be no longer executed.
`JSHint <http://jshint.com>`_ will do a static analysis of your code and hightlight potential errors
and/or bad habits.
For example::
::
converse.listen.not('message', function (messageXML) { ... });
grunt jshint
Events
======
.. note:: see also the `"listen" grouping`_ API section above.
You can run both the tests and jshint in one go by calling:
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) { ... });`` |
+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
grunt check
Minification
============
......@@ -568,8 +832,20 @@ After adding the string, you'll need to regenerate the POT file, like so:
make pot
To create a new PO file for a language in which converse.js is not yet
translated into, do the following
.. note:: In this example we use Polish (pl), you need to substitute 'pl' to your own language's code.
::
mkdir -p ./locale/pl/LC_MESSAGES
msginit -i ./locale/converse.pot -o ./locale/pl/LC_MESSAGES/converse.po -l pl
You can then create or update the PO file for a specific language by doing the following:
.. note:: In this example we use German (de), you need to substitute 'de' to your own language's code.
::
msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U
......@@ -643,6 +919,7 @@ Congratulations, you've now succesfully added your translations. Sorry for all
those hoops you had to jump through.
===============
Troubleshooting
===============
......@@ -713,190 +990,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) { ... });`` |
+----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
| **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
=============
......@@ -942,7 +1035,7 @@ Default: ``true``
Allow multi-user chat (muc) in chatrooms. Setting this to ``false`` will remove
the ``Chatrooms`` tab from the control box.
allow_muc
allow_otr
---------
Default: ``true``
......@@ -1031,8 +1124,10 @@ Default: ``true``
Determines whether Converse.js will maintain the chat session across page
loads.
*Please be aware*: This is a new still relatively experimental feature and there might be some
unhandled edge-cases.
See also:
* `Prebinding and Single Session Support`_
* `Using prebind in connection with keepalive`_
message_carbons
---------------
......@@ -1129,19 +1224,71 @@ prebind
Default: ``false``
See also: `Prebinding and Single Session Support`_
Use this option when you want to attach to an existing XMPP connection that was
already authenticated (usually on the backend before page load).
This is useful when you don't want to render the login form on the chat control
box with each page load.
For prebinding to work, your backend server must authenticate for you, and
then return a JID (jabber ID), SID (session ID) and RID (Request ID).
For prebinding to work, you must set up a pre-authenticated BOSH session,
for which you will receive a JID (jabber ID), SID (session ID) and RID
(Request ID).
These values (``rid``, ``sid`` and ``jid``) need to be passed into
``converse.initialize`` (with the exception of ``keepalive``, see below).
Additionally, you also have to specify a ``bosh_service_url``.
Using prebind in connection with keepalive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``prebind`` and `keepalive`_ options can be used together.
The ``keepalive`` option caches the ``rid``, ``sid`` and ``jid`` values
(henceforth referred to as *session tokens*) one receives from a prebinded
BOSH session, in order to re-use them when the page reloads.
However, if besides setting ``keepalive`` to ``true``, you also set ``prebind``
to ``true``, and you pass in valid session tokens to ``converse.initialize``,
then those passed in session tokens will be used instead of any tokens cached by
``keepalive``.
If you set ``prebind`` to ``true`` and don't pass in the session tokens to
``converse.initialize``, then converse.js will look for tokens cached by
``keepalive``.
If you've set ``keepalive`` and ``prebind`` to ``true``, don't pass in session
tokens and converse.js doesn't find any cached session tokens, then
converse.js will emit an event ``noResumeableSession`` and exit.
This allows you to start a prebinded session with valid tokens, and then fall
back to ``keepalive`` for maintaining that session across page reloads. When
for some reason ``keepalive`` doesn't have cached session tokens anymore, you
can listen for the ``noResumeableSession`` event and take that as a cue that
you should again prebind in order to get valid session tokens.
If you set ``prebind`` to ``true``, you have to make sure to also pass in these
values as ``jid``, ``sid``, ``rid``.
Here is a code example::
converse.on('noResumeableSession', function () {
$.getJSON('/prebind', function (data) {
converse.initialize({
prebind: true,
keepalive: true,
bosh_service_url: 'https://bind.example.com',
jid: data.jid,
sid: data.sid,
rid: data.rid
});
});
});
converse.initialize({
prebind: true,
keepalive: true,
bosh_service_url: 'https://bind.example.com'
}));
Additionally, you have to specify ``bosh_service_url``.
roster_groups
-------------
......
docs/html/index.html
View file @ 6100aaf1
This source diff could not be displayed because it is too large. You can view the blob instead.
docs/html/searchindex.js
View file @ 6100aaf1
Search.setIndex({envversion:42,terms:{"default":0,all:0,partial:0,edg:0,queri:0,lack:0,webchat:0,mp3:0,abil:0,follow:0,row:0,privat:0,typeerror:0,sensit:0,punjab:0,base64:0,readabl:0,descript:[],send:0,vcard:0,buddi:0,under:0,sens:0,spec:0,sent:0,global:0,everi:0,string:0,fals:0,voic:0,offlin:0,ident:0,mechan:0,jack:0,veri:0,join:0,tri:[],button:0,messagetext:0,list:0,correct:0,"try":0,item:0,sane:[],refer:0,awai:0,pleas:0,prevent:0,almond:0,prosodi:0,focu:0,jump:0,second:0,download:0,further:0,port:0,folk:0,even:0,index:0,hide:0,appear:0,section:0,abl:0,access:0,delet:0,version:0,awar:0,"new":0,net:0,"public":0,widget:0,full:0,themselv:[],messagexml:0,gener:0,here:0,bodi:0,middl:0,let:0,path:0,becom:0,modifi:[],sinc:0,valu:0,box:0,great:0,convers:0,mysit:0,current:0,ajax:0,fetch:0,implement:0,sorri:0,chanc:0,via:0,repositori:0,danger:0,primit:0,prefer:0,put:0,href:0,fake:0,sessionstorag:0,establish:0,from:0,zip:0,commun:0,deop:0,doubl:0,two:0,websit:0,few:[],stylesheet:0,busi:0,call:0,msg:0,until:0,tightli:0,more:0,emoticon:0,peopl:[],notic:0,site:0,particular:0,known:0,realli:0,cach:0,must:0,none:0,word:0,room:[],work:0,uniqu:0,dev:0,xhr:0,legwork:0,can:0,lc_messag:0,purpos:0,root:0,could:0,control:0,getsess:[],give:0,challeng:0,share:0,templat:0,topic:0,critic:0,proprietari:0,explor:0,onlin:0,callbuttonclick:0,occup:0,alwai:0,cours:0,multipl:0,goal:0,turn:0,anoth:0,deniabl:0,write:0,how:0,bosh_serv:[],sid:0,roster:0,instead:0,perspect:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,wrong:0,mai:0,underscor:0,data:0,demonstr:0,man:0,opkod:[],"short":0,attempt:0,practic:0,third:0,seriou:0,secur:0,credenti:0,correspond:0,assign:0,caus:0,inform:0,maintain:0,allow:0,media:0,order:0,talk:0,feedback:[],chatbox:0,chatroomopen:0,over:0,move:0,becaus:0,chatboxopen:0,report:0,own:0,through:0,reconnect:0,still:0,paramet:[],streamlin:0,jid:0,"8147a27e4a7f9b55ffc85c2683f9529a":[],render:0,fit:0,fix:0,better:0,window:0,pend:0,persist:0,mail:0,hidden:0,main:0,might:0,them:0,lastnam:0,"return":0,thei:0,python:0,encod:0,initi:[],rewriterul:0,mention:0,verifi:0,now:0,choic:0,name:0,edit:0,drop:0,crypto:0,separ:0,achiev:0,ejabberd:0,each:0,mean:0,subset:0,everyth:0,harm:0,chatboxfocus:0,map:0,michael:0,individu:0,idea:0,librelist:0,"static":0,expect:0,django:0,our:0,happen:0,extract:0,special:0,out:0,shown:0,"3rd":0,space:0,miss:0,proxy_pass:0,rel:0,internet:0,got:0,plural:0,factori:0,po2json:0,proxi:0,insid:0,written:0,differ:0,standard:0,standalon:0,reason:0,dictionari:0,ask:0,succesfulli:0,afterward:0,roominvites:0,fairli:0,blogpost:0,keep:0,thing:[],perhap:0,place:0,nicknam:0,imposs:0,first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,hoop:0,independ:0,cryptograph:0,number:0,yourself:0,instruct:0,alreadi:0,done:0,owner:0,happi:0,open:0,suffic:0,size:0,given:0,convent:0,top:0,attack:0,messag:0,cssmin:0,attach:0,stori:0,draft:0,jed:0,privaci:0,recent:0,store:0,listen:0,luckili:0,consol:0,option:0,especi:0,tool:0,copi:0,specifi:0,direct:0,maxim:0,part:0,pars:0,kept:0,ogg:0,exactli:0,than:0,serv:0,past:0,kind:0,bloat:0,provid:0,remov:0,jqueri:0,bridg:0,bind:0,someothersit:0,browser:0,pre:0,"function":0,sai:0,saa:0,session_kei:[],ani:0,packag:0,properli:0,increment:0,moffitt:0,element:0,issu:0,outbound:0,built:0,callback:0,latter:0,thorough:[],click:0,note:[],also:0,client:0,take:0,which:0,sure:0,normal:0,unsur:0,previou:0,reach:0,most:0,plai:0,eavesdropp:0,homepag:0,"class":0,don:0,url:0,clear:0,doe:0,runtim:0,statuschang:0,bower:0,usual:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,buddystatuschang:0,server_nam:0,protocol:0,longer:0,fine:0,find:0,help:0,xml:0,yoursit:0,onli:0,grunt:0,locat:0,just:0,mute:0,releas:0,stanza:0,chat_statu:0,haven:[],experiment:0,roominvitereceiv:0,folder:0,local:0,meant:0,wide:[],stop:0,account:[],soon:0,repo:0,nativ:0,cannot:0,cryptographi:0,increas:0,neither:0,enabl:0,emb:0,jasmin:0,mainspec:0,possibl:0,patch:0,remot:0,though:0,contain:0,ban:0,where:0,wiki:[],chatboxclos:0,stroph:0,see:0,bare:0,result:0,close:0,calendar:0,eventnam:0,best:0,concern:0,movim:[],statu:0,said:[],extend:0,inconveni:0,someth:0,particip:0,state:0,muc:0,between:0,"import":0,subscript:0,experi:0,approach:0,across:0,hash:0,attribut:0,altern:0,perfect:0,appreci:[],kei:0,screen:0,were:0,conjunct:0,extens:0,job:0,entir:0,"5e64a30272af065bd72258c565a03f2f":[],group:0,both:0,cor:0,instant:0,shortliv:0,howev:0,myself:[],etc:0,instanc:0,grain:0,mani:0,login:0,com:0,load:0,simpli:0,within:0,pot:0,sync:0,solv:0,carbon:0,assum:0,malleabl:0,backend:0,quit:[],user_id:0,sucessfulli:0,addition:0,rebuild:0,due:0,been:0,compon:0,json:0,much:0,toolbar:0,interest:0,subscrib:0,modern:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,togeth:0,els:0,last:0,otr:0,plausibl:0,present:0,invit:0,"case":0,multi:0,therefor:0,look:0,gnu:0,servic:0,plugin:0,messagesend:0,defin:0,"while":0,match:0,abov:[],observ:0,hightlight:0,engag:0,helper:0,readi:0,non:0,itself:0,incom:0,rid:0,pat:0,welcom:0,minim:0,receiv:0,parti:0,make:0,secreci:0,same:0,read:0,onconnectfacebook:[],html:0,unexpectedli:0,chatroom:0,document:[],medit:[],complet:0,status:0,signon:0,http:0,webserv:0,again:0,optim:0,roomview:0,upon:0,someon:[],hand:0,unhandl:0,"50kb":0,user:0,roominvit:0,uncaught:0,php:0,aka:0,forwarded_messag:0,weibel:0,stateless:0,moder:0,bewar:0,firstli:0,markup:0,min:0,well:0,object:0,thought:0,person:0,contact:0,command:[],wherebi:0,thi:0,choos:0,model:0,latest:0,plural_form:0,identifi:0,execut:0,tip:[],xep:0,human:0,languag:0,previous:0,web:0,xmlhttprequest:0,expos:0,field:0,extra:0,had:0,desktop:0,chat:[],non_amd:0,versa:0,appli:0,input:0,kick:0,build:0,applic:0,format:0,webpag:0,traffic:0,know:0,press:0,xss:0,like:0,specif:0,should:0,manual:0,benefit:0,api:[],avatar:0,have:0,popular:0,output:0,page:0,candi:0,facebookconnect:[],revers:0,chatboxtoggl:0,deal:0,visibl:0,some:0,substitu:0,openfir:0,bottom:0,avoid:0,deploy:0,rewriteengin:0,usernam:0,allow_otr:0,inject:0,speak:0,localhost:[],either:0,somehow:0,plu:0,who:[],msg_receiv:0,host:0,toggl:0,although:0,post:0,panel:0,src:0,about:0,actual:0,invitee_jid:0,firstnam:0,controlbox:0,unfortun:0,stand:0,act:0,telephon:0,curiou:0,deploi:0,toggle_particip:0,automat:0,right:0,empti:0,wrap:0,chang:0,merg:[],git:0,log:0,wai:0,pictur:0,aren:0,transfer:0,"long":0,custom:0,avail:0,trigger:0,localstorag:0,includ:0,lot:0,suit:0,forward:0,analysi:0,project:0,head:0,nplural:0,form:0,bundl:0,back:0,link:0,buddystatusmessagechang:0,synonym:0,line:0,inlin:0,"true":0,bug:0,congratul:0,requirej:0,info:0,made:0,dirti:[],locale_data:0,reload:0,whether:0,tab:0,asynchron:0,below:0,those:0,indefinit:0,otherwis:0,emit:0,significantli:0,gone:0,constant:0,creat:0,retriev:0,decrypt:0,doesn:0,mode:0,msgmerg:0,exist:0,file:0,face:0,probabl:0,denot:0,image_typ:0,want:0,when:0,detail:0,gettext:0,statusmessagechang:0,nick:0,valid:0,rememb:0,varieti:[],servernam:0,nice:0,node:0,intend:0,determin:0,duck:0,harsh:0,org:0,vcard_upd:0,elsewher:0,track:0,consid:0,conversej:0,stai:0,lang:0,fraught:0,vice:0,directori:0,virtualhost:0,getjson:0,rule:0,ignor:0,token:0,potenti:0,time:0},objtypes:{},objnames:{},filenames:["index"],titles:["Quickstart (to get a demo up and running)"],objects:{},titleterms:{roster_group:0,multilingu:0,code:0,xmpp:0,session:0,jshint:0,paramet:[],depend:0,configur:0,apach:0,descript:[],add:0,anim:0,get:0,end:0,amd:0,initi:0,nginx:0,facebook:[],front:0,requir:0,introduct:0,troubleshoot:0,authent:0,server:0,play_sound:0,xhr_custom_statu:0,integr:[],debug:0,manag:0,domain:0,set:[],habit:0,xhr_user_search_url:0,request:0,connect:0,pass:0,fullnam:0,event:0,librari:0,variabl:0,allow_muc:0,what:0,jabber:0,bad:0,content:0,use_otr_by_default:0,overcom:0,method:0,run:0,hide_muc_serv:0,javascript:0,visible_toolbar_button:0,bosh:0,css:0,xhr_custom_status_url:0,cache_otr_kei:0,side:0,solut:0,restrict:0,api:0,auto_list_room:0,instal:0,storag:0,your:0,script:0,support:0,submit:0,getsid:0,recommend:0,type:0,notif:0,minifi:0,translat:0,i18n:0,getrid:0,sound:0,pull:0,room:0,bugfix:0,record:0,error:0,auto_reconnect:0,problem:0,featur:0,quickstart:0,forward_messag:0,demo:0,auto_subscrib:0,argument:[],tag:0,chat:0,tabl:0,need:0,check:0,bosh_service_url:0,prebind:0,develop:0,message_carbon:0,getbuddi:0,cross:0,other:0,test:0,expose_rid_and_sid:0,you:0,singl:0,keepal:0,befor:0,allow_contact_request:0,encrypt:0,minif:0,xhr_user_search:0,off:0,use_vcard:0,show_controlbox_by_default:0,without:0,show_only_online_us:0,exampl:0,command:0,conflict:0}})
\ No newline at end of file
Search.setIndex({envversion:42,terms:{all:0,partial:0,edg:[],chain:0,queri:0,lack:0,standardis:0,webchat:0,mp3:0,abil:0,follow:0,row:0,privat:0,typeerror:0,sensit:0,punjab:0,base64:0,readabl:0,allow_otr:[],send:0,vcard:0,buddi:0,under:0,sens:0,spec:0,sent:0,file:0,global:0,everi:0,string:0,fals:0,voic:0,offlin:0,mechan:0,jack:0,fall:0,veri:[],affect:0,tri:[],button:0,messagetext:0,list:0,virtualhost:0,correct:0,"try":0,item:0,sane:[],pleas:0,prevent:0,almond:0,prosodi:0,focu:0,jump:0,second:0,jid2:0,jid1:0,download:0,further:0,port:0,folk:0,even:0,index:0,hide:0,appear:0,section:0,abl:0,current:0,delet:0,version:0,"new":0,net:0,"public":0,widget:0,full:0,themselv:[],messagexml:0,join:0,gener:0,here:0,bodi:0,middl:0,let:0,path:0,becom:0,modifi:[],sinc:0,valu:0,box:0,great:0,convers:0,mysit:0,anymor:0,reason:0,fetch:0,implement:0,sorri:0,chanc:0,via:0,although:0,danger:0,primit:0,prefer:0,ask:0,href:0,fake:0,sessionstorag:0,establish:0,from:0,zip:0,commun:0,deop:0,doubl:0,two:0,next:0,websit:0,few:[],stylesheet:0,call:0,msg:0,until:0,tightli:0,more:0,emoticon:0,peopl:[],line:0,notic:0,particular:[],known:0,cach:0,must:0,none:0,word:0,room:[],work:0,uniqu:0,dev:0,xhr:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,getsess:[],give:0,challeng:0,share:0,templat:0,topic:0,critic:0,movim:[],proprietari:0,explor:0,onlin:0,callbuttonclick:0,occup:0,alwai:0,cours:0,multipl:0,goal:0,turn:0,anoth:0,deniabl:0,write:0,how:0,bosh_serv:[],sid:0,verifi:0,perspect:0,updat:0,npm:0,map:0,product:0,resourc:0,earlier:0,usabl:0,shortliv:0,wrong:0,mai:0,pat:0,underscor:0,data:0,demonstr:0,man:0,repo:0,"short":0,attempt:0,practic:[],third:0,nativ:0,seriou:0,secur:0,credenti:0,correspond:0,element:0,caus:0,inform:0,maintain:0,allow:0,parti:0,order:0,talk:0,feedback:[],chatbox:0,chatroomopen:0,over:0,move:0,becaus:0,chatboxopen:0,increas:0,telephon:0,through:0,reconnect:0,still:0,paramet:[],streamlin:0,jid:0,"8147a27e4a7f9b55ffc85c2683f9529a":[],render:0,fit:0,fix:0,better:0,whether:0,window:0,pend:0,persist:0,mail:0,hidden:0,main:0,might:0,hoop:0,them:0,lastnam:0,"return":0,thei:0,python:0,toggle_particip:0,initi:[],rewriterul:0,mention:0,instead:0,aka:0,now:0,choic:0,name:0,edit:0,drop:0,crypto:0,separ:0,achiev:0,ejabberd:0,each:0,complet:0,mean:0,subset:0,status:0,harm:0,chatboxfocus:0,regener:0,experiment:[],michael:0,individu:0,idea:0,librelist:0,"static":0,expect:0,our:0,happen:0,extract:0,special:0,out:0,shown:0,"3rd":0,space:0,open:0,proxy_pass:0,rel:0,internet:0,got:0,plural:0,factori:0,po2json:0,model:0,after:0,proxi:0,insid:0,state:0,given:0,standard:0,standalon:0,ajax:0,dictionari:0,put:0,succesfulli:0,afterward:0,roominvites:0,unhandl:[],could:0,keep:0,thing:[],perhap:0,place:0,nicknam:0,imposs:0,token:[],first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,arrai:0,independ:0,number:0,yourself:0,instruct:0,alreadi:0,done:0,owner:0,custom:0,miss:0,suffic:0,size:0,differ:0,convent:0,top:0,mkdir:0,attack:0,messag:0,attach:0,stori:0,draft:0,jed:0,privaci:0,forwarded_messag:0,store:0,listen:[],luckili:0,assign:0,consol:0,option:0,especi:0,tool:0,copi:0,specifi:0,direct:0,maxim:0,part:0,pars:0,moder:0,ogg:0,exactli:0,than:0,serv:0,past:0,kind:0,bloat:0,provid:0,remov:0,jqueri:0,bridg:0,bind:0,toward:0,someothersit:0,browser:0,pre:0,analysi:0,sai:0,saa:0,session_kei:[],ani:0,packag:0,properli:0,increment:0,moffitt:0,django:0,normal:0,issu:0,outbound:0,built:0,callback:0,latter:0,yoursit:0,thorough:[],click:0,note:[],also:0,contact:[],take:0,which:0,therefor:0,sure:0,roster:0,unsur:0,previou:0,reach:0,most:0,plai:0,eavesdropp:0,homepag:0,"class":0,msginit:0,don:0,bug:0,url:0,clear:0,doe:0,noresumeablesess:0,runtim:0,statuschang:0,bower:0,latest:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,buddystatuschang:0,server_nam:0,identifi:0,fine:0,find:0,help:0,xml:0,henceforth:0,onli:0,grunt:0,locat:0,execut:0,explain:0,mute:0,releas:0,stanza:0,chat_statu:0,haven:[],busi:0,roominvitereceiv:0,folder:0,local:0,meant:0,wide:[],stop:0,account:[],soon:0,opkod:[],initiateotr:0,cannot:0,cryptographi:0,report:0,subscript:0,enabl:0,emb:0,approach:0,mainspec:0,multi:0,patch:0,remot:0,deploy:0,contain:0,ban:0,where:0,wiki:[],chatboxclos:0,stroph:0,see:0,bare:0,result:0,close:0,calendar:0,eventnam:0,best:0,concern:0,awar:[],statu:0,said:[],kei:0,inconveni:0,someth:0,particip:0,written:0,muc:0,between:0,"import":0,neither:0,experi:0,jasmin:0,across:0,attribut:0,altern:0,perfect:0,accord:0,appreci:[],extend:0,screen:0,were:0,conjunct:0,extens:0,job:0,entir:0,otherwis:0,"5e64a30272af065bd72258c565a03f2f":[],group:[],both:0,cor:0,instant:0,plugin:0,howev:0,avatar:0,etc:0,instanc:0,grain:0,logic:0,mani:0,login:0,com:0,load:0,simpli:0,pot:0,height:0,sync:0,solv:0,non:0,deploi:0,carbon:0,constant:0,assum:0,malleabl:0,backend:0,quit:[],user_id:0,sucessfulli:0,addition:0,rebuild:0,due:0,been:0,accessor:0,compon:0,json:0,much:0,besid:0,toolbar:0,interest:0,subscrib:0,modern:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,togeth:0,input:0,last:0,otr:0,plausibl:0,present:0,"case":0,myself:[],ident:0,look:0,gnu:0,servic:0,invit:0,messagesend:0,defin:0,"while":0,kick:0,abov:0,observ:0,hightlight:0,engag:0,helper:0,readi:0,site:0,itself:0,incom:0,rid:0,mutat:0,welcom:0,minim:0,receiv:0,media:0,make:0,format:0,same:0,webpag:0,onconnectfacebook:[],html:0,unexpectedli:0,chatroom:0,document:0,medit:[],higher:0,breakdown:0,signon:0,http:0,webserv:0,denot:0,optim:0,roomview:0,upon:0,someon:[],hand:0,fairli:0,"50kb":0,user:0,roominvit:0,uncaught:0,php:0,cssmin:0,recent:0,weibel:0,stateless:0,travers:0,kept:0,bewar:0,firstli:0,markup:0,min:0,well:0,thought:0,person:0,client:0,command:[],wherebi:0,thi:0,choos:0,everyth:0,usual:0,plural_form:0,protocol:0,just:0,when:0,xep:0,human:0,polish:0,yet:0,languag:0,previous:0,web:0,fraught:0,xmlhttprequest:0,expos:0,nick:0,extra:0,had:0,except:0,desktop:0,cue:0,non_amd:0,versa:0,appli:0,els:0,match:0,build:0,applic:0,secreci:0,read:0,intuit:0,traffic:0,know:0,press:0,xss:0,like:0,specif:0,should:0,reload:0,manual:0,benefit:0,api:[],either:0,have:0,popular:0,output:0,mode:0,page:0,candi:0,indefinit:0,facebookconnect:[],revers:0,chatboxtoggl:0,who:[],deal:0,visibl:0,some:0,substitu:0,certain:0,endotr:0,openfir:0,bottom:0,avoid:0,though:0,rewriteengin:0,usernam:0,substitut:0,exit:0,inject:0,speak:0,localhost:[],refer:0,somehow:0,plu:0,object:0,msg_receiv:0,host:0,repositori:0,post:0,panel:0,src:0,about:0,actual:0,would:0,invitee_jid:0,firstnam:0,controlbox:0,unfortun:0,stand:0,act:0,own:0,curiou:0,inlin:0,within:0,encod:0,automat:0,right:0,empti:0,wrap:0,chang:0,merg:[],git:0,log:0,wai:0,pictur:0,aren:0,transfer:0,"long":0,happi:0,avail:0,start:0,trigger:0,localstorag:0,includ:0,lot:0,suit:0,forward:0,"function":0,project:0,head:0,nplural:0,form:0,bundl:0,back:0,link:0,buddystatusmessagechang:0,synonym:0,cryptograph:0,realli:0,"true":0,awai:0,congratul:0,requirej:0,info:0,made:0,dirti:[],tab:0,possibl:0,"default":0,access:0,asynchron:0,below:0,those:0,toggl:0,legwork:0,emit:0,significantli:0,gone:0,hash:0,creat:0,retriev:0,decrypt:0,doesn:0,repres:0,msgmerg:0,exist:0,chat:[],face:0,probabl:0,again:0,image_typ:0,want:0,tip:[],detail:0,gettext:0,statusmessagechang:0,field:0,valid:0,rememb:0,varieti:[],servernam:0,nice:0,node:0,intend:0,determin:0,duck:0,harsh:0,org:0,vcard_upd:0,elsewher:0,track:0,consid:0,conversej:0,stai:0,lang:0,longer:0,vice:0,directori:0,descript:[],getjson:0,rule:0,ignor:0,locale_data:0,potenti:0,time:0},objtypes:{},objnames:{},filenames:["index"],titles:["Quickstart (to get a demo up and running)"],objects:{},titleterms:{demo:0,roster_group:0,multilingu:0,code:0,xmpp:0,session:0,jshint:0,paramet:[],group:0,singl:0,configur:0,apach:0,add:0,anim:0,get:0,end:0,amd:0,initi:0,nginx:0,facebook:[],front:0,requir:0,introduct:0,troubleshoot:0,authent:0,server:0,play_sound:0,bad:0,integr:[],debug:0,side:0,domain:0,set:[],habit:0,xhr_user_search_url:0,connect:0,pass:0,fullnam:0,event:0,librari:0,variabl:0,what:0,storag:0,xhr_custom_statu:0,content:0,show_only_online_us:0,allow_otr:0,use_otr_by_default:0,overcom:0,method:[],run:0,hide_muc_serv:0,javascript:0,visible_toolbar_button:0,bosh:0,depend:0,xhr_custom_status_url:0,cache_otr_kei:0,manag:0,solut:0,restrict:0,api:0,auto_list_room:0,instal:0,jabber:[],your:0,script:0,support:0,submit:0,getsid:[],recommend:0,type:0,listen:0,show_controlbox_by_default:0,notif:0,minifi:0,translat:0,i18n:0,getrid:[],sound:0,pull:0,room:0,bugfix:0,exampl:0,record:0,error:0,auto_reconnect:0,problem:0,featur:0,quickstart:0,forward_messag:0,descript:[],auto_subscrib:0,argument:[],tag:0,chat:0,tabl:0,need:0,check:0,bosh_service_url:0,prebind:0,develop:0,message_carbon:0,getbuddi:[],cross:0,other:0,test:0,expose_rid_and_sid:0,you:0,css:0,keepal:0,befor:0,allow_contact_request:0,encrypt:0,minif:0,xhr_user_search:0,off:0,use_vcard:0,request:0,without:0,allow_muc:0,contact:0,command:0,token:0,conflict:0}})
\ No newline at end of file
docs/source/index.rst
View file @ 6100aaf1
......@@ -515,11 +515,38 @@ You can run both the tests and jshint in one go by calling:
Developer API
=============
.. note:: see also the `event api methods`_, not listed here.
.. note:: The API documented here is available in Converse.js 0.8.4 and higher.
Earlier versions of Converse.js might have different API methods or none at all.
In the Converse.js API, you traverse towards a logical grouping, from
which you can then call certain standardised accessors and mutators, like::
.get
.set
.add
.all
.remove
This is done to increase readability and to allow intuitive method chaining.
For example, to get a contact, you would do the following::
converse.contacts.get('jid@example.com');
To get multiple contacts, just pass in an array of jids::
converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
**Here follows now a breakdown of all API groupings and methods**:
initialize
----------
.. note:: This method is the one exception of a method which is not logically grouped
as explained above.
Initializes converse.js. This method must always be called when using
converse.js.
......@@ -544,15 +571,18 @@ Example::
});
getBuddy
--------
"contacts" grouping
-------------------
get
~~~
Returns a map of attributes for a given buddy (i.e. roster contact), specified
by JID (Jabber ID).
Example::
converse.getBuddy('buddy@example.com')
converse.contacts.get('buddy@example.com')
The map of attributes:
......@@ -590,17 +620,19 @@ The map of attributes:
| vcard_updated | When last the buddy's VCard was updated. |
+----------------+--------------------------------------------------------------------------------------------------------------------------------------+
getChatBox
----------
"chats" grouping
----------------
get
~~~
Returns an object/map representing a chat box (without opening or affecting that chat box).
Example::
converse.getChatBox('buddy@example.com')
converse.chats.get('buddy@example.com')
The returned chat box contains the following methods:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*The returned chat box contains the following methods:*
+-------------+------------------------------------------+
| Method | Description |
......@@ -618,8 +650,7 @@ The returned chat box contains the following methods:
| set | Set an attribute (i.e. mutator). |
+-------------+------------------------------------------+
The get and set methods can be used to retrieve and change the following attributes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*The get and set methods can be used to retrieve and change the following attributes:*
+-------------+-----------------------------------------------------+
| Attribute | Description |
......@@ -629,39 +660,25 @@ The get and set methods can be used to retrieve and change the following attribu
| url | The URL of the chat box heading. |
+-------------+-----------------------------------------------------+
getRID
------
Returns the current RID (request ID) value.
getSID
------
"tokens" grouping
-----------------
Returns the current SID (Session ID) value.
get
~~~
openChatBox
-----------
Opens a chat box and returns an object/map representating that chat box.
If the chat box is already open, its text area will be focused.
Returns a token, either the RID or SID token depending on what's asked for.
Example::
converse.openChatBox('buddy@example.com')
Refer to `getChatBox`_ for more information on the object returned by this
method (which is the same for both).
converse.tokens.get('rid')
Events
======
"listen" grouping
-----------------
Converse.js emits events to which you can subscribe from your own Javascript.
Concerning events, the following methods are available:
Event API Methods
-----------------
Concerning events, the following methods are available under the "listen"
grouping:
* **on(eventName, callback)**:
......@@ -676,7 +693,7 @@ Event API Methods
For example::
converse.on('message', function (messageXML) { ... });
converse.listen.on('message', function (messageXML) { ... });
* **once(eventName, callback)**:
......@@ -690,17 +707,25 @@ Event API Methods
For example::
converse.once('message', function (messageXML) { ... });
converse.listen.once('message', function (messageXML) { ... });
* **off(eventName, callback)**
* **not(eventName, callback)**
To stop listening to an event, you can use the ``off`` method.
To stop listening to an event, you can use the ``not`` method.
Parameters:
* ``eventName`` is the event name as a string.
* ``callback`` refers to the function that is to be no longer executed.
For example::
converse.listen.not('message', function (messageXML) { ... });
Events
======
.. note:: see also the `"listen" grouping`_ API section above.
Event Types
-----------
......@@ -750,7 +775,6 @@ Here are the different events that are emitted:
+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
Minification
============
......
spec/converse.js
View file @ 6100aaf1
......@@ -10,6 +10,7 @@
} (this, function ($, mock, test_utils) {
return describe("Converse", $.proxy(function(mock, test_utils) {
describe("The \"tokens\" API", $.proxy(function () {
beforeEach($.proxy(function () {
test_utils.closeAllChatBoxes();
test_utils.clearBrowserStorage();
......@@ -17,7 +18,83 @@
test_utils.createContacts('current');
}, converse));
it("has an API method for retrieving the next RID", $.proxy(function () {
it("has a method for retrieving the next RID", $.proxy(function () {
var old_connection = converse.connection;
converse.connection._proto.rid = '1234';
converse.expose_rid_and_sid = false;
expect(converse_api.tokens.get('rid')).toBe(null);
converse.expose_rid_and_sid = true;
expect(converse_api.tokens.get('rid')).toBe('1234');
converse.connection = undefined;
expect(converse_api.tokens.get('rid')).toBe(null);
// Restore the connection
converse.connection = old_connection;
}, converse));
it("has a method for retrieving the SID", $.proxy(function () {
var old_connection = converse.connection;
converse.connection._proto.sid = '1234';
converse.expose_rid_and_sid = false;
expect(converse_api.tokens.get('sid')).toBe(null);
converse.expose_rid_and_sid = true;
expect(converse_api.tokens.get('sid')).toBe('1234');
converse.connection = undefined;
expect(converse_api.tokens.get('sid')).toBe(null);
// Restore the connection
converse.connection = old_connection;
}, converse));
}, converse));
describe("The \"contacts\" API", $.proxy(function () {
beforeEach($.proxy(function () {
test_utils.closeAllChatBoxes();
test_utils.clearBrowserStorage();
converse.rosterview.model.reset();
test_utils.createContacts('current');
}, converse));
it("has a method 'get' which returns a wrapped contact", $.proxy(function () {
// TODO: test multiple JIDs passed in
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
expect(converse_api.contacts.get('non-existing@jabber.org')).toBeFalsy();
var attrs = converse_api.contacts.get(jid);
expect(typeof attrs).toBe('object');
expect(attrs.fullname).toBe(mock.cur_names[0]);
expect(attrs.jid).toBe(jid);
}, converse));
}, converse));
describe("The \"chats\" API", $.proxy(function() {
beforeEach($.proxy(function () {
test_utils.closeAllChatBoxes();
test_utils.clearBrowserStorage();
converse.rosterview.model.reset();
test_utils.createContacts('current');
}, converse));
it("has a method 'get' which returns a wrapped chat box object", $.proxy(function () {
// TODO: test multiple JIDs passed in
// FIXME: when a non-existing chat box is "get(ted)", it's
// opened, which we don't want...
expect(converse_api.chats.get('non-existing@jabber.org')).toBeFalsy(); // test on user that doesn't exist.
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
var box = converse_api.chats.get(jid);
expect(box instanceof Object).toBeTruthy();
expect(box.get('box_id')).toBe(b64_sha1(jid));
var chatboxview = this.chatboxviews.get(jid);
expect(chatboxview.$el.is(':visible')).toBeTruthy();
}, converse));
}, converse));
describe("The DEPRECATED API", $.proxy(function() {
beforeEach($.proxy(function () {
test_utils.closeAllChatBoxes();
test_utils.clearBrowserStorage();
converse.rosterview.model.reset();
test_utils.createContacts('current');
}, converse));
it("has a method for retrieving the next RID", $.proxy(function () {
var old_connection = converse.connection;
converse.connection._proto.rid = '1234';
converse.expose_rid_and_sid = false;
......@@ -32,7 +109,7 @@
converse.connection = old_connection;
}, converse));
it("has an API method for retrieving the SID", $.proxy(function () {
it("has a method for retrieving the SID", $.proxy(function () {
var old_connection = converse.connection;
converse.connection._proto.sid = '1234';
converse.expose_rid_and_sid = false;
......@@ -47,7 +124,7 @@
converse.connection = old_connection;
}, converse));
it("has an API method for retrieving a buddy's attributes", $.proxy(function () {
it("has a method for retrieving a buddy's attributes", $.proxy(function () {
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
expect(converse_api.getBuddy('non-existing@jabber.org')).toBeFalsy();
var attrs = converse_api.getBuddy(jid);
......@@ -55,37 +132,8 @@
expect(attrs.fullname).toBe(mock.cur_names[0]);
expect(attrs.jid).toBe(jid);
}, converse));
it("has an API method, openChatBox, for opening a chat box for a buddy", $.proxy(function () {
expect(converse_api.openChatBox('non-existing@jabber.org')).toBeFalsy(); // test on user that doesn't exist.
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
var box = converse_api.openChatBox(jid);
expect(box instanceof Object).toBeTruthy();
expect(box.get('box_id')).toBe(b64_sha1(jid));
var chatboxview = this.chatboxviews.get(jid);
expect(chatboxview.$el.is(':visible')).toBeTruthy();
}, converse));
it("will focus an already open chat box, if the openChatBox API method is called for it.", $.proxy(function () {
// Calling openChatBox on an already open chat will focus it.
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
var chatboxview = this.chatboxviews.get(jid);
spyOn(chatboxview, 'focus');
test_utils.openChatBoxFor(jid);
box = converse_api.openChatBox(jid);
expect(chatboxview.focus).toHaveBeenCalled();
expect(box.get('box_id')).toBe(b64_sha1(jid));
}, converse));
it("has an API method, getChatBox, for retrieving chat box", $.proxy(function () {
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
expect(converse_api.getChatBox(jid)).toBeFalsy();
test_utils.openChatBoxFor(jid);
var box = converse_api.getChatBox(jid);
expect(box instanceof Object).toBeTruthy();
expect(box.get('box_id')).toBe(b64_sha1(jid));
}, converse));
}, converse, mock, test_utils));
}));
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7