diff --git a/converse.js b/converse.js index fe85d949c..0ed157a44 100644 --- a/converse.js +++ b/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, diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 7397c7eb1..90b0fb260 100644 --- a/docs/CHANGES.rst +++ b/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] diff --git a/docs/source/development.rst b/docs/source/development.rst index 3c485d30a..99833d7b6 100644 --- a/docs/source/development.rst +++ b/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:* diff --git a/spec/converse.js b/spec/converse.js index 93b833e8d..58e9d5685 100644 --- a/spec/converse.js +++ b/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));