Add and document `bring_to_foreground` option to rooms API

docs/source/developer_api.rst

@@ -987,6 +987,9 @@ Room attributes that may be passed in:
   The values should be named without the ``muc#roomconfig_`` prefix.
 * *maximize*: A boolean, indicating whether minimized rooms should also be
   maximized, when opened. Set to ``false`` by default.
+* *bring_to_foreground*: A boolean indicating whether the room should be
+  brought to the foreground and therefore replace the currently shown chat.
+  If there is no chat currently open, then this option is ineffective.
 
 For example, opening a room with a specific default configuration:
 

src/converse-bookmarks.js

@@ -231,7 +231,7 @@
                      */
                     ev.preventDefault();
                     const jid = ev.target.getAttribute('data-room-jid');
-                    const chatroom = _converse.openChatRoom({'jid': jid}, true);
+                    const chatroom = _converse.api.rooms.open(jid, {'bring_to_foreground': true});
                     _converse.chatboxviews.get(jid).renderBookmarkForm();
                 },
             });

src/converse-muc.js

@@ -2895,13 +2895,16 @@
 
             _converse.getChatRoom = function (jid, attrs, fetcher) {
                 jid = jid.toLowerCase();
-                return _converse.getViewForChatBox(fetcher(_.extend({
-                    'id': jid,
-                    'jid': jid,
-                    'name': Strophe.unescapeNode(Strophe.getNodeFromJid(jid)),
-                    'type': CHATROOMS_TYPE,
-                    'box_id': b64_sha1(jid)
-                }, attrs)));
+                return _converse.getViewForChatBox(
+                    fetcher(_.extend({
+                            'id': jid,
+                            'jid': jid,
+                            'name': Strophe.unescapeNode(Strophe.getNodeFromJid(jid)),
+                            'type': CHATROOMS_TYPE,
+                            'box_id': b64_sha1(jid)
+                        }, attrs),
+                        attrs.bring_to_foreground
+                    ));
             };
 
             /* We extend the default converse.js API to add methods specific to MUC