Add 2 new API methods. updates #46

Added openChatBox and getChatBox.

converse.js

@@ -3019,19 +3019,18 @@
                  * If it doesn't exist, create it.
                  */
                 var chatbox  = this.model.get(attrs.jid);
-                if (chatbox) {
-                    if (chatbox.get('minimized')) {
-                        chatbox.maximize();
-                    } else {
-                        chatbox.trigger('show');
-                    }
-                } else {
+                if (!chatbox) {
                     chatbox = this.model.create(attrs, {
                         'error': function (model, response) {
                             converse.log(response.responseText);
                         }
                     });
                 }
+                if (chatbox.get('minimized')) {
+                    chatbox.maximize();
+                } else {
+                    chatbox.trigger('show');
+                }
                 return chatbox;
             }
         });
@@ -3258,6 +3257,8 @@
 
             openChat: function (ev) {
                 if (ev && ev.preventDefault) { ev.preventDefault(); }
+                // XXX: Can this.model.attributes be used here, instead of
+                // manually specifying all attributes?
                 return converse.chatboxviews.showChat({
                     'id': this.model.get('jid'),
                     'jid': this.model.get('jid'),
@@ -4636,6 +4637,20 @@
                 return contact.attributes;
             }
         },
+        'getChatBox': function (jid) {
+            var chatbox = converse.chatboxes.get(jid);
+            if (chatbox) {
+                return {
+                    'attributes': chatbox.attributes,
+                    'endOTR': chatbox.endOTR,
+                    'get': chatbox.get,
+                    'initiateOTR': chatbox.initiateOTR,
+                    'maximize': chatbox.maximize,
+                    'minimize': chatbox.minimize,
+                    'set': chatbox.set
+                };
+            }
+        },
         'getRID': function () {
             if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") {
                 return converse.connection.rid || converse.connection._proto.rid;
@@ -4648,6 +4663,22 @@
             }
             return null;
         },
+        'openChatBox': function (jid) {
+            var chatbox;
+            var contact = converse.roster.get(Strophe.getBareJidFromJid(jid));
+            if (contact) {
+                chatbox = converse.chatboxviews.showChat(contact.attributes);
+                return {
+                    'attributes': chatbox.attributes,
+                    'endOTR': chatbox.endOTR,
+                    'get': chatbox.get,
+                    'initiateOTR': chatbox.initiateOTR,
+                    'maximize': chatbox.maximize,
+                    'minimize': chatbox.minimize,
+                    'set': chatbox.set
+                };
+            }
+        },
         'once': function (evt, handler) {
             converse.once(evt, handler);
         },

docs/CHANGES.rst

@@ -8,6 +8,7 @@ Changelog
 * Bugfix. Cannot read property "top" of undefined. [jcbrand]
 * Add new event, noResumeableSession, for when keepalive=true and there aren't
   any prebind session tokens. [jcbrand]
+* Add 2 new API methods, getChatBox and openChatBox. [jcbrand]
 
 0.8.3 (2014-09-22)
 ------------------

spec/converse.js

@@ -10,8 +10,10 @@
     return describe("Converse", $.proxy(function(mock, test_utils) {
 
         beforeEach($.proxy(function () {
-            window.localStorage.clear();
-            window.sessionStorage.clear();
+            test_utils.closeAllChatBoxes();
+            test_utils.clearBrowserStorage();
+            converse.rosterview.model.reset();
+            test_utils.createContacts('current');
         }, converse));
 
         it("has an API method for retrieving the next RID", $.proxy(function () {
@@ -46,12 +48,43 @@
 
         it("has an API method for retrieving a buddy's attributes", $.proxy(function () {
             var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
-            expect(converse_api.getBuddy(jid)).toBeFalsy();
-            test_utils.createContacts('current');
+            expect(converse_api.getBuddy('non-existing@jabber.org')).toBeFalsy();
             var attrs = converse_api.getBuddy(jid);
             expect(typeof attrs).toBe('object');
             expect(attrs.fullname).toBe(mock.cur_names[0]);
             expect(attrs.jid).toBe(jid);
         }, converse));
+
+        it("has an API method, openChatBox, for opening a chat box for a buddy", $.proxy(function () {
+            expect(converse_api.openChatBox('non-existing@jabber.org')).toBeFalsy(); // test on user that doesn't exist.
+            var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
+            var box = converse_api.openChatBox(jid);
+            expect(box instanceof Object).toBeTruthy();
+            expect(box.get('box_id')).toBe(b64_sha1(jid));
+            var chatboxview = this.chatboxviews.get(jid);
+            expect(chatboxview.$el.is(':visible')).toBeTruthy();
+        }, converse));
+
+        it("will focus an already open chat box, if the openChatBox API method is called for it.", $.proxy(function () {
+            // Calling openChatBox on an already open chat will focus it.
+            var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
+            var chatboxview = this.chatboxviews.get(jid);
+            spyOn(chatboxview, 'focus');
+            test_utils.openChatBoxFor(jid);
+            box = converse_api.openChatBox(jid);
+            expect(chatboxview.focus).toHaveBeenCalled();
+            expect(box.get('box_id')).toBe(b64_sha1(jid));
+
+        }, converse));
+
+        it("has an API method, getChatBox, for retrieving chat box", $.proxy(function () {
+            var jid = mock.cur_names[0].replace(/ /g,'.').toLowerCase() + '@localhost';
+            expect(converse_api.getChatBox(jid)).toBeFalsy();
+            test_utils.openChatBoxFor(jid);
+            var box = converse_api.getChatBox(jid);
+            expect(box instanceof Object).toBeTruthy();
+            expect(box.get('box_id')).toBe(b64_sha1(jid));
+        }, converse));
+
     }, converse, mock, test_utils));
 }));