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

Some API changes:

Browse Source 
* Let contacts.get() return all roster contacts.
* Also, add "open" method for the chats API.
* chats.get will now only return a chat box if it's already open.
This commit is contained in:
JC Brand 2015-02-25 18:31:09 +01:00
parent 71e9736b1d
commit c70561b898
4 changed files with 130 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
converse.js
View File

@ -5191,14 +5191,16 @@
};
var wrappedChatBox = function (chatbox) {
var view = converse.chatboxviews.get(chatbox.get('jid'));
return {
'close': $.proxy(view.close, view),
'endOTR': $.proxy(chatbox.endOTR, chatbox),
'focus': $.proxy(view.focus, view),
'get': $.proxy(chatbox.get, chatbox),
'initiateOTR': $.proxy(chatbox.initiateOTR, chatbox),
'maximize': $.proxy(chatbox.maximize, chatbox),
'minimize': $.proxy(chatbox.minimize, chatbox),
'set': $.proxy(chatbox.set, chatbox),
'open': chatbox.trigger.bind(chatbox, 'show')
'set': $.proxy(chatbox.set, chatbox)
};
};
return {
@ -5230,14 +5232,16 @@
}
return null;
};
if (typeof jids === "string") {
if (typeof jids === "undefined") {
jids = converse.roster.pluck('jid');
} else if (typeof jids === "string") {
return _transform(jids);
}
return _.map(jids, _transform);
}
},
'chats': {
'get': function (jids) {
'open': function (jids) {
var _transform = function (jid) {
var chatbox = converse.chatboxes.get(jid);
if (!chatbox) {
@ -5257,10 +5261,28 @@
}
return wrappedChatBox(chatbox);
};
if (typeof jids === "string") {
if (typeof jids === "undefined") {
converse.log("chats.open: You need to provide at least one JID", "error");
return null;
} else if (typeof jids === "string") {
return _transform(jids);
}
return _.map(jids, _transform);
},
'get': function (jids) {
var _transform = function (jid) {
var chatbox = converse.chatboxes.get(jid);
if (!chatbox) {
return null;
}
return wrappedChatBox(chatbox);
};
if (typeof jids === "undefined") {
jids = converse.roster.pluck('jid');
} else if (typeof jids === "string") {
return _transform(jids);
}
return _.filter(_.map(jids, _transform), function (i) {return i !== null;});
}
},
'tokens': {
@ -5319,7 +5341,7 @@
},
'env': {
'jQuery': $,
'Strophe': Strophe, // TODO: this must be wrapped
'Strophe': Strophe,
'$build': $build,
'$iq': $iq,
'$pres': $pres,

5
docs/CHANGES.rst
View File

@ -1,15 +1,18 @@
Changelog
=========
0.8.7 (Unreleased)
0.9.0 (Unreleased)
------------------
* Add new API method ``chats.open`` to open chat boxes. [jcbrand]
* Add new API method to set and get configuration settings. [jcbrand]
* Add responsiveness to CSS. We now use Sass preprocessor for generating CSS. [jcbrand]
* Calling the API method ``contacts.get()`` without parameters now returns all contacts. [jcbrand]
* Don't send out the message carbons IQ stanza on each page load. [jcbrand]
* New Makefile.win to build in Windows environments. [gbonvehi]
* Norwegian Bokmål translations. [Andreas Lorentsen]
* Strophe.log and Strophe.error now uses converse.log to output messages. [gbonvehi]
* The API method ``chats.get`` now only returns already opened chat boxes. [jcbrand]
* Updated Afrikaans translations. [jcbrand]
* #204 Support websocket connections. [jcbrand]
* #252, 253 Add fullname and jid to contact's tooltip in roster. [gbonvehi]

51
docs/source/development.rst
View File

@ -163,7 +163,6 @@ 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.
@ -176,6 +175,10 @@ To get multiple contacts, just pass in an array of jids::
converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
To get all contacts, simply call ``get`` without any jids::
converse.contacts.get();
**Here follows now a breakdown of all API groupings and methods**:
@ -218,14 +221,22 @@ Example:
get
~~~
Returns a map of attributes for a given buddy (i.e. roster contact), specified
by JID (Jabber ID).
This method is used to retrieve roster contacts.
Example::
To get a single roster contact, call the method with the contact's JID (Jabber ID):
converse.contacts.get('buddy@example.com')
The map of attributes:
To get multiple contacts, pass in an array of JIDs::
converse.contacts.get(['buddy1@example.com', 'buddy2@example.com'])
To return all contacts, simply call ``get`` without any parameters::
converse.contacts.get()
The returned roster contact objects have these attributes:
+----------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Attribute | |
@ -267,12 +278,36 @@ The map of attributes:
get
~~~
Returns an object/map representing a chat box (without opening or affecting that chat box).
Returns an object representing a chat box, if that chat box is already open.
If the chat box is not already open, this method will return ``null``.
Example::
To return a single chat box, provide the JID of the contact you're chatting
with in that chat box::
converse.chats.get('buddy@example.com')
To return an array of chat boxes, provide an array of JIDs::
converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
To return all open chat boxes, call the method without any JIDs::
converse.chats.get()
open
~~~~
Opens a chat box and returns an object representing a chat box.
To open a single chat box, provide the JID of the contact::
converse.chats.get('buddy@example.com')
To return an array of chat boxes, provide an array of JIDs::
converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
*The returned chat box contains the following methods:*
+-------------+------------------------------------------+
@ -290,6 +325,8 @@ Example::
+-------------+------------------------------------------+
| set | Set an attribute (i.e. mutator). |
+-------------+------------------------------------------+
| close | Close the chat box. |
+-------------+------------------------------------------+
*The get and set methods can be used to retrieve and change the following attributes:*

62
spec/converse.js
View File

@ -54,15 +54,29 @@
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';
it("has a method 'get' which returns wrapped contacts", $.proxy(function () {
// Check that it returns nothing if a non-existing JID is given
expect(converse_api.contacts.get('non-existing@jabber.org')).toBeFalsy();
// Check when a single jid is given
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
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);
// You can retrieve multiple contacts by passing in an array
var jid2 = mock.cur_names[1].replace(/ /g,'.').toLowerCase() + '@localhost';
var list = converse_api.contacts.get([jid, jid2]);
expect(Array.isArray(list)).toBeTruthy();
expect(list[0].fullname).toBe(mock.cur_names[0]);
expect(list[1].fullname).toBe(mock.cur_names[1]);
// Check that all JIDs are returned if you call without any parameters
list = converse_api.contacts.get();
expect(list.length).toBe(mock.cur_names.length);
}, converse));
}, converse));
describe("The \"chats\" API", $.proxy(function() {
@ -73,17 +87,49 @@
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.
it("has a method 'get' which returns a wrapped chat box if it's already open", $.proxy(function () {
// Test on chat that doesn't exist.
expect(converse_api.chats.get('non-existing@jabber.org')).toBeFalsy();
// Test on chat that's not open
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
var box = converse_api.chats.get(jid);
expect(box).toBe(null);
// Test for single JID
test_utils.openChatBoxFor(jid);
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();
// Test for multiple JIDs
var jid2 = mock.cur_names[1].replace(/ /g,'.').toLowerCase() + '@localhost';
test_utils.openChatBoxFor(jid2);
var list = converse_api.chats.get([jid, jid2]);
expect(Array.isArray(list)).toBeTruthy();
expect(list[0].get('box_id')).toBe(b64_sha1(jid));
expect(list[1].get('box_id')).toBe(b64_sha1(jid2));
}, converse));
it("has a method 'open' which opens and returns a wrapped chat box", $.proxy(function () {
// Test on chat that doesn't exist.
expect(converse_api.chats.get('non-existing@jabber.org')).toBeFalsy();
var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
var box = converse_api.chats.open(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();
// Test for multiple JIDs
var jid2 = mock.cur_names[1].replace(/ /g,'.').toLowerCase() + '@localhost';
var list = converse_api.chats.open([jid, jid2]);
expect(Array.isArray(list)).toBeTruthy();
expect(list[0].get('box_id')).toBe(b64_sha1(jid));
expect(list[1].get('box_id')).toBe(b64_sha1(jid2));
}, converse));
}, converse));