Some API changes:

* 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.

converse.js

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

docs/CHANGES.rst

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

docs/source/development.rst

@@ -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:*
 

spec/converse.js

@@ -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));