Enable new rooms to be configured automatically

Via `rooms.open` API method.

docs/CHANGES.md

@@ -2,6 +2,8 @@
 
 ## 2.0.2 (Unreleased)
 - #721 keepalive not working with anonymous authentication [jcbrand]
+- Enable new rooms to be configured automatically, with a default config, via `rooms.open`.
+  For details, refer to the [relevant documentation](https://conversejs.org/docs/html/developer_api.html#the-rooms-grouping) [jcbrand]
 
 ## 2.0.1 (2016-11-07)
 - #203 New configuration setting [muc_domain](https://conversejs.org/docs/html/configuration.html#muc_domain) [jcbrand]

docs/source/developer_api.rst

@@ -540,12 +540,12 @@ open
 ~~~~
 
 Opens a multi user chat box and returns an object representing it.
-Similar to chats.get API
+Similar to the ``chats.get`` API.
 
 It takes 2 parameters:
 
-* the room JID (if not specified, all rooms will be returned).
-* a map (object) containing any extra room attributes. For example, if you want
+* The room JID or JIDs (if not specified, all currently open rooms will be returned).
+* A map (object) containing any extra room attributes. For example, if you want
   to specify the nickname, use ``{'nick': 'bloodninja'}``.
 
 To open a single multi user chat box, provide the JID of the room:
@@ -566,6 +566,41 @@ To setup a custom nickname when joining the room, provide the optional nick argu
 
     converse.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
 
+Room attributes that may be passed in:
+
+* *nick*: The nickname to be used
+* *auto_configure*: A boolean, indicating whether the room should be configured
+  automatically or not. If set to ``true``, then it makes sense to pass in
+  configuration settings.
+* *roomconfig*: A map of configuration settings to be used when the room gets
+  configured automatically. Currently it doesn't make sense to specify
+  ``roomconfig`` values if ``auto_configure`` is set to ``false``.
+  For a list of configuration values that can be passed in, refer to these values
+  in the `XEP-0045 MUC specification <http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner>`_.
+  The values should be named without the ``muc#roomconfig_`` prefix.
+
+For example, opening a room with a specific default configuration:
+
+.. code-block:: javascript
+
+    converse.rooms.open(
+        'myroom@conference.example.org',
+        { 'nick': 'coolguy69',
+          'auto_configure': true,
+          'roomconfig': {
+            'changesubject': false,
+            'membersonly': true,
+            'persistentroom': true,
+            'publicroom': true,
+            'roomdesc': 'Comfy room for hanging out',
+            'whois': 'anyone'
+          }
+        },
+        true
+    );
+
+.. note:: `multi-list` configuration values are not yet supported.
+
 close
 ~~~~~
 

src/converse-muc.js

@@ -754,6 +754,44 @@
                         });
                 },
 
+                autoConfigureChatRoom: function (stanza) {
+                    /* Automatically configure room based on the
+                     * 'roomconfigure' data on this view's model.
+                     */
+                    var that = this, configArray = [],
+                        $fields = $(stanza).find('field'),
+                        count = $fields.length,
+                        config = this.model.get('roomconfig');
+
+                    $fields.each(function () {
+                        var fieldname = this.getAttribute('var').replace('muc#roomconfig_', ''),
+                            type = this.getAttribute('type'),
+                            value;
+                        if (fieldname in config) {
+                            switch (type) {
+                                case 'boolean':
+                                    value = config[fieldname] ? 1 : 0;
+                                    break;
+                                case 'list-multi':
+                                    // TODO: we don't yet handle "list-multi" types
+                                    value = this.innerHTML;
+                                    break;
+                                default:
+                                    value = config[fieldname];
+                            }
+                            this.innerHTML = $build('value').t(value);
+                        }
+                        configArray.push(this);
+                        if (!--count) {
+                            that.sendConfiguration(
+                                configArray,
+                                that.onConfigSaved.bind(that),
+                                that.onErrorConfigSaved.bind(that)
+                            );
+                        }
+                    });
+                },
+
                 onConfigSaved: function (stanza) {
                     // TODO: provide feedback
                 },
@@ -774,20 +812,27 @@
                 },
 
                 configureChatRoom: function (ev) {
+                    var handleIQ;
                     if (typeof ev !== 'undefined' && ev.preventDefault) {
                         ev.preventDefault();
                     }
-                    if (this.$el.find('div.chatroom-form-container').length) {
-                        return;
+                    if (this.model.get('auto_configure')) {
+                        handleIQ = this.autoConfigureChatRoom.bind(this);
+                    } else {
+                        if (this.$el.find('div.chatroom-form-container').length) {
+                            return;
+                        }
+                        var $body = this.$('.chatroom-body');
+                        $body.children().addClass('hidden');
+                        $body.append(converse.templates.chatroom_form());
+                        handleIQ = this.renderConfigurationForm.bind(this);
                     }
-                    this.$('.chatroom-body').children().addClass('hidden');
-                    this.$('.chatroom-body').append(converse.templates.chatroom_form());
                     converse.connection.sendIQ(
-                            $iq({
-                                to: this.model.get('jid'),
-                                type: "get"
-                            }).c("query", {xmlns: Strophe.NS.MUC_OWNER}).tree(),
-                            this.renderConfigurationForm.bind(this)
+                        $iq({
+                            'to': this.model.get('jid'),
+                            'type': "get"
+                        }).c("query", {xmlns: Strophe.NS.MUC_OWNER}).tree(),
+                        handleIQ
                     );
                 },