Merge pull request #362 from pzia/master

Adding 'rooms' API

converse.js

@@ -5543,6 +5543,46 @@
                 return _.map(jids, getWrappedChatBox);
             }
         },
+        'rooms': {
+            'open': function (jids, nick) {
+                if (!nick) {
+                    nick = Strophe.getNodeFromJid(converse.bare_jid)
+                }
+                if (typeof nick !== "string") {
+                    throw new TypeError('rooms.open: invalid nick, must be string');
+                }
+                var _transform = function (jid) {
+                    var chatroom = converse.chatboxes.get(jid);
+                    converse.log('jid');
+                    if (!chatroom) {
+                        var chatroom = converse.chatboxviews.showChat({
+                            'id': jid,
+                            'jid': jid,
+                            'name': Strophe.unescapeNode(Strophe.getNodeFromJid(jid)),
+                            'nick': nick,
+                            'chatroom': true,
+                            'box_id' : b64_sha1(jid)
+                        });
+                    }
+                    return wrappedChatBox(chatroom);
+                };
+                if (typeof jids === "undefined") {
+                    throw new TypeError('rooms.open: You need to provide at least one JID');
+                } else if (typeof jids === "string") {
+                    return _transform(jids);
+                }
+                return _.map(jids, _transform);
+            },
+            'get': function (jids) {
+                if (typeof jids === "undefined") {
+                    throw new TypeError("rooms.get: You need to provide at least one JID");
+                    return null;
+                } else if (typeof jids === "string") {
+                    return getWrappedChatBox(jids);
+                }
+                return _.map(jids, getWrappedChatBox);
+            }
+        },
         'tokens': {
             'get': function (id) {
                 if (!converse.expose_rid_and_sid || typeof converse.connection === "undefined") {

docs/source/development.rst

@@ -351,6 +351,35 @@ To return an array of chat boxes, provide an array of JIDs::
 | url         | The URL of the chat box heading.                    |
 +-------------+-----------------------------------------------------+
 
+"rooms" grouping
+----------------
+
+get
+~~~
+
+Returns an object representing a multi user chat box (room).
+
+Similar to chats.get API
+
+open
+~~~~
+
+Opens a multi user chat box and returns an object representing it.
+Similar to chats.get API
+
+To open a single multi user chat box, provide the JID of the room::
+
+    converse.room.open('group@muc.example.com')
+
+To return an array of chat boxes, provide an array of JIDs::
+
+    converse.chats.open(['group1@muc.example.com', 'group2@muc.example.com'])
+
+To setup a custom nickname when joining the room, provide the optionnal nick argument::
+
+    converse.room.open('group@muc.example.com', 'mycustomnick')
+
+
 "settings" grouping
 -------------------