Refactor the API. updates #46
API methods now consist of simple accessors and mutators that are logically grouped.
This commit is contained in:
parent
36db4c8b27
commit
6100aaf114
128
converse.js
128
converse.js
@ -4713,53 +4713,86 @@
|
|||||||
'initiateOTR': $.proxy(chatbox.initiateOTR, chatbox),
|
'initiateOTR': $.proxy(chatbox.initiateOTR, chatbox),
|
||||||
'maximize': $.proxy(chatbox.maximize, chatbox),
|
'maximize': $.proxy(chatbox.maximize, chatbox),
|
||||||
'minimize': $.proxy(chatbox.minimize, chatbox),
|
'minimize': $.proxy(chatbox.minimize, chatbox),
|
||||||
'set': $.proxy(chatbox.set, chatbox)
|
'set': $.proxy(chatbox.set, chatbox),
|
||||||
|
'open': chatbox.trigger.bind(chatbox, 'show')
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
return {
|
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));
|
var contact = converse.roster.get(Strophe.getBareJidFromJid(jid));
|
||||||
if (contact) {
|
if (contact) {
|
||||||
return contact.attributes;
|
return contact.attributes;
|
||||||
}
|
}
|
||||||
},
|
|
||||||
'getChatBox': function (jid) {
|
|
||||||
var chatbox = converse.chatboxes.get(jid);
|
|
||||||
if (chatbox) {
|
|
||||||
return wrappedChatBox(chatbox);
|
|
||||||
}
|
|
||||||
},
|
|
||||||
'getRID': function () {
|
|
||||||
if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
|
|
||||||
return converse.connection.rid || converse.connection._proto.rid;
|
|
||||||
}
|
|
||||||
return null;
|
return null;
|
||||||
|
};
|
||||||
|
if (typeof jids === "string") {
|
||||||
|
return _transform(jids);
|
||||||
|
}
|
||||||
|
return _.map(jids, _transform);
|
||||||
|
}
|
||||||
},
|
},
|
||||||
'getSID': function () {
|
'chats': {
|
||||||
if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
|
'get': function (jids) {
|
||||||
|
var _transform = function (jid) {
|
||||||
|
var chatbox = converse.chatboxes.get(jid);
|
||||||
|
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);
|
||||||
|
}
|
||||||
|
return _.map(jids, _transform);
|
||||||
|
}
|
||||||
|
},
|
||||||
|
'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 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) {
|
'once': function (evt, handler) {
|
||||||
converse.once(evt, handler);
|
converse.once(evt, handler);
|
||||||
},
|
},
|
||||||
'on': function (evt, handler) {
|
'on': function (evt, handler) {
|
||||||
converse.on(evt, handler);
|
converse.on(evt, handler);
|
||||||
},
|
},
|
||||||
'off': function (evt, handler) {
|
'not': function (evt, handler) {
|
||||||
converse.off(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) {
|
'override': function (obj, attributes) {
|
||||||
/* Helper method for overriding or extending Converse's Backbone Views or Models
|
/* Helper method for overriding or extending Converse's Backbone Views or Models
|
||||||
*
|
*
|
||||||
@ -4782,9 +4815,48 @@
|
|||||||
obj.prototype[key] = value;
|
obj.prototype[key] = value;
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
}
|
||||||
},
|
},
|
||||||
'registerPlugin': function (name, callback) {
|
'env': {
|
||||||
converse.plugins[name] = callback;
|
'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);
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
}));
|
}));
|
||||||
|
Binary file not shown.
@ -28,7 +28,7 @@ tags:
|
|||||||
<link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
|
<link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
|
||||||
<script src="builds/converse.min.js"></script>
|
<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.
|
your requirements.
|
||||||
|
|
||||||
Please refer to the `Configuration variables`_ section further below for info on
|
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.
|
Converse.js repository may serve as a nice usable example.
|
||||||
|
|
||||||
These minified files provide the same demo-like functionality as is available
|
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
|
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing.
|
||||||
practical.
|
|
||||||
|
|
||||||
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
|
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`_.
|
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
|
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
|
`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.
|
code.
|
||||||
|
|
||||||
The `What you will need`_ section has more information on all these
|
The `What you will need`_ section has more information on all these
|
||||||
requirements.
|
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
|
What you will need
|
||||||
==================
|
==================
|
||||||
|
|
||||||
An XMPP/Jabber server
|
An XMPP server
|
||||||
=====================
|
==============
|
||||||
|
|
||||||
*Converse.js* implements `XMPP`_ as its messaging protocol, and therefore needs
|
*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).
|
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.
|
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
|
Development
|
||||||
===========
|
===========
|
||||||
@ -511,6 +511,270 @@ You can run both the tests and jshint in one go by calling:
|
|||||||
|
|
||||||
grunt check
|
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::
|
||||||
|
|
||||||
|
converse.listen.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.listen.once('message', function (messageXML) { ... });
|
||||||
|
|
||||||
|
* **not(eventName, callback)**
|
||||||
|
|
||||||
|
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
|
||||||
|
-----------
|
||||||
|
|
||||||
|
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
|
Minification
|
||||||
============
|
============
|
||||||
|
|
||||||
@ -568,8 +832,20 @@ After adding the string, you'll need to regenerate the POT file, like so:
|
|||||||
|
|
||||||
make pot
|
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:
|
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
|
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.
|
those hoops you had to jump through.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
===============
|
===============
|
||||||
Troubleshooting
|
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).
|
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
|
Configuration
|
||||||
=============
|
=============
|
||||||
@ -942,7 +1035,7 @@ Default: ``true``
|
|||||||
Allow multi-user chat (muc) in chatrooms. Setting this to ``false`` will remove
|
Allow multi-user chat (muc) in chatrooms. Setting this to ``false`` will remove
|
||||||
the ``Chatrooms`` tab from the control box.
|
the ``Chatrooms`` tab from the control box.
|
||||||
|
|
||||||
allow_muc
|
allow_otr
|
||||||
---------
|
---------
|
||||||
|
|
||||||
Default: ``true``
|
Default: ``true``
|
||||||
@ -1031,8 +1124,10 @@ Default: ``true``
|
|||||||
Determines whether Converse.js will maintain the chat session across page
|
Determines whether Converse.js will maintain the chat session across page
|
||||||
loads.
|
loads.
|
||||||
|
|
||||||
*Please be aware*: This is a new still relatively experimental feature and there might be some
|
See also:
|
||||||
unhandled edge-cases.
|
|
||||||
|
* `Prebinding and Single Session Support`_
|
||||||
|
* `Using prebind in connection with keepalive`_
|
||||||
|
|
||||||
message_carbons
|
message_carbons
|
||||||
---------------
|
---------------
|
||||||
@ -1129,19 +1224,71 @@ prebind
|
|||||||
|
|
||||||
Default: ``false``
|
Default: ``false``
|
||||||
|
|
||||||
|
See also: `Prebinding and Single Session Support`_
|
||||||
|
|
||||||
Use this option when you want to attach to an existing XMPP connection that was
|
Use this option when you want to attach to an existing XMPP connection that was
|
||||||
already authenticated (usually on the backend before page load).
|
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
|
This is useful when you don't want to render the login form on the chat control
|
||||||
box with each page load.
|
box with each page load.
|
||||||
|
|
||||||
For prebinding to work, your backend server must authenticate for you, and
|
For prebinding to work, you must set up a pre-authenticated BOSH session,
|
||||||
then return a JID (jabber ID), SID (session ID) and RID (Request ID).
|
for which you will receive a JID (jabber ID), SID (session ID) and RID
|
||||||
|
(Request ID).
|
||||||
|
|
||||||
If you set ``prebind`` to ``true``, you have to make sure to also pass in these
|
These values (``rid``, ``sid`` and ``jid``) need to be passed into
|
||||||
values as ``jid``, ``sid``, ``rid``.
|
``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.
|
||||||
|
|
||||||
|
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
|
roster_groups
|
||||||
-------------
|
-------------
|
||||||
|
1393
docs/html/index.html
1393
docs/html/index.html
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
@ -515,11 +515,38 @@ You can run both the tests and jshint in one go by calling:
|
|||||||
Developer API
|
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
|
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
|
Initializes converse.js. This method must always be called when using
|
||||||
converse.js.
|
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
|
Returns a map of attributes for a given buddy (i.e. roster contact), specified
|
||||||
by JID (Jabber ID).
|
by JID (Jabber ID).
|
||||||
|
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
converse.getBuddy('buddy@example.com')
|
converse.contacts.get('buddy@example.com')
|
||||||
|
|
||||||
The map of attributes:
|
The map of attributes:
|
||||||
|
|
||||||
@ -590,17 +620,19 @@ The map of attributes:
|
|||||||
| vcard_updated | When last the buddy's VCard was updated. |
|
| 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).
|
Returns an object/map representing a chat box (without opening or affecting that chat box).
|
||||||
|
|
||||||
Example::
|
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 |
|
| Method | Description |
|
||||||
@ -618,8 +650,7 @@ The returned chat box contains the following methods:
|
|||||||
| set | Set an attribute (i.e. mutator). |
|
| 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 |
|
| 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. |
|
| url | The URL of the chat box heading. |
|
||||||
+-------------+-----------------------------------------------------+
|
+-------------+-----------------------------------------------------+
|
||||||
|
|
||||||
getRID
|
"tokens" grouping
|
||||||
------
|
-----------------
|
||||||
|
|
||||||
Returns the current RID (request ID) value.
|
get
|
||||||
|
~~~
|
||||||
|
|
||||||
getSID
|
Returns a token, either the RID or SID token depending on what's asked for.
|
||||||
------
|
|
||||||
|
|
||||||
Returns the current SID (Session ID) value.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
converse.openChatBox('buddy@example.com')
|
converse.tokens.get('rid')
|
||||||
|
|
||||||
Refer to `getChatBox`_ for more information on the object returned by this
|
"listen" grouping
|
||||||
method (which is the same for both).
|
-----------------
|
||||||
|
|
||||||
|
|
||||||
Events
|
|
||||||
======
|
|
||||||
|
|
||||||
Converse.js emits events to which you can subscribe from your own Javascript.
|
Converse.js emits events to which you can subscribe from your own Javascript.
|
||||||
|
|
||||||
Concerning events, the following methods are available:
|
Concerning events, the following methods are available under the "listen"
|
||||||
|
grouping:
|
||||||
Event API Methods
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
* **on(eventName, callback)**:
|
* **on(eventName, callback)**:
|
||||||
|
|
||||||
@ -676,7 +693,7 @@ Event API Methods
|
|||||||
|
|
||||||
For example::
|
For example::
|
||||||
|
|
||||||
converse.on('message', function (messageXML) { ... });
|
converse.listen.on('message', function (messageXML) { ... });
|
||||||
|
|
||||||
* **once(eventName, callback)**:
|
* **once(eventName, callback)**:
|
||||||
|
|
||||||
@ -690,17 +707,25 @@ Event API Methods
|
|||||||
|
|
||||||
For example::
|
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:
|
Parameters:
|
||||||
|
|
||||||
* ``eventName`` is the event name as a string.
|
* ``eventName`` is the event name as a string.
|
||||||
* ``callback`` refers to the function that is to be no longer executed.
|
* ``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
|
Event Types
|
||||||
-----------
|
-----------
|
||||||
@ -750,7 +775,6 @@ Here are the different events that are emitted:
|
|||||||
+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
|
+--------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Minification
|
Minification
|
||||||
============
|
============
|
||||||
|
|
||||||
|
112
spec/converse.js
112
spec/converse.js
@ -10,6 +10,7 @@
|
|||||||
} (this, function ($, mock, test_utils) {
|
} (this, function ($, mock, test_utils) {
|
||||||
return describe("Converse", $.proxy(function(mock, test_utils) {
|
return describe("Converse", $.proxy(function(mock, test_utils) {
|
||||||
|
|
||||||
|
describe("The \"tokens\" API", $.proxy(function () {
|
||||||
beforeEach($.proxy(function () {
|
beforeEach($.proxy(function () {
|
||||||
test_utils.closeAllChatBoxes();
|
test_utils.closeAllChatBoxes();
|
||||||
test_utils.clearBrowserStorage();
|
test_utils.clearBrowserStorage();
|
||||||
@ -17,7 +18,83 @@
|
|||||||
test_utils.createContacts('current');
|
test_utils.createContacts('current');
|
||||||
}, converse));
|
}, 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;
|
var old_connection = converse.connection;
|
||||||
converse.connection._proto.rid = '1234';
|
converse.connection._proto.rid = '1234';
|
||||||
converse.expose_rid_and_sid = false;
|
converse.expose_rid_and_sid = false;
|
||||||
@ -32,7 +109,7 @@
|
|||||||
converse.connection = old_connection;
|
converse.connection = old_connection;
|
||||||
}, converse));
|
}, 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;
|
var old_connection = converse.connection;
|
||||||
converse.connection._proto.sid = '1234';
|
converse.connection._proto.sid = '1234';
|
||||||
converse.expose_rid_and_sid = false;
|
converse.expose_rid_and_sid = false;
|
||||||
@ -47,7 +124,7 @@
|
|||||||
converse.connection = old_connection;
|
converse.connection = old_connection;
|
||||||
}, converse));
|
}, 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';
|
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
|
||||||
expect(converse_api.getBuddy('non-existing@jabber.org')).toBeFalsy();
|
expect(converse_api.getBuddy('non-existing@jabber.org')).toBeFalsy();
|
||||||
var attrs = converse_api.getBuddy(jid);
|
var attrs = converse_api.getBuddy(jid);
|
||||||
@ -55,37 +132,8 @@
|
|||||||
expect(attrs.fullname).toBe(mock.cur_names[0]);
|
expect(attrs.fullname).toBe(mock.cur_names[0]);
|
||||||
expect(attrs.jid).toBe(jid);
|
expect(attrs.jid).toBe(jid);
|
||||||
}, converse));
|
}, 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));
|
}, 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));
|
}, converse, mock, test_utils));
|
||||||
}));
|
}));
|
||||||
|
Loading…
Reference in New Issue
Block a user