Expand the API to allow configuration settings to...

be set on the fly.

converse.js

@@ -231,7 +231,7 @@
 
         // Default configuration values
         // ----------------------------
-        var default_settings = {
+        this.default_settings = {
             allow_contact_requests: true,
             allow_dragresize: true,
             allow_logout: true,
@@ -278,9 +278,9 @@
             xhr_user_search: false,
             xhr_user_search_url: ''
         };
-        _.extend(this, default_settings);
+        _.extend(this, this.default_settings);
         // Allow only whitelisted configuration attributes to be overwritten
-        _.extend(this, _.pick(settings, Object.keys(default_settings)));
+        _.extend(this, _.pick(settings, Object.keys(this.default_settings)));
 
         if (settings.visible_toolbar_buttons) {
             _.extend(
@@ -5196,6 +5196,22 @@
         'initialize': function (settings, callback) {
             converse.initialize(settings, callback);
         },
+        'settings': {
+            'get': function (key) {
+                if (_.contains(Object.keys(converse.default_settings), key)) {
+                    return converse[key];
+                }
+            },
+            'set': function (key, val) {
+                var o = {};
+                if (typeof key === "object") {
+                    _.extend(converse, _.pick(key, Object.keys(converse.default_settings)));
+                } else if (typeof key === "string") {
+                    o[key] = val;
+                    _.extend(converse, _.pick(o, Object.keys(converse.default_settings)));
+                }
+            }
+        },
         'contacts': {
             'get': function (jids) {
                 var _transform = function (jid) {

docs/CHANGES.rst

 Changelog
 =========
 
-0.8.8 (Unreleased)
+0.8.7 (Unreleased)
 ------------------
 
-* Norwegian Bokmål translations. [Andreas Lorentsen]
-* Updated Afrikaans translations. [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]
 * 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]
+* Updated Afrikaans translations. [jcbrand]
 * #252, 253 Add fullname and jid to contact's tooltip in roster. [gbonvehi]
 * #292 Better support for XEP-0085 Chat State Notifications. [jcbrand]
 * #295 Document "allow_registration". [gbonvehi]
 * #304 Added Polish translations. [ser]
-* New Makefile.win to build in Windows environments. [gbonvehi]
-* Strophe.log and Strophe.error now uses converse.log to output messages. [gbonvehi]
 * #305 presence/show text in XMPP request isn't allowed by specification. [gbonvehi]
 
 0.8.6 (2014-12-07)

docs/source/configuration.rst

@@ -54,7 +54,7 @@ Default:  ``true``
 Allow Off-the-record encryption of single-user chat messages.
 
 allow_registration
----------
+------------------
 
 Default:  ``true``
 

docs/source/development.rst

@@ -301,6 +301,36 @@ Example::
 | url         | The URL of the chat box heading.                    |
 +-------------+-----------------------------------------------------+
 
+"settings" grouping
+-------------------
+
+This grouping allows you to get or set the configuration settings of converse.js.
+
+get(key)
+~~~~~~~~
+
+Returns the value of a configuration settings. For example::
+
+    converse.settings.get("play_sounds"); // default value returned would be false;
+
+set(key, value) or set(object)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set one or many configuration settings. For example::
+
+    converse.settings.set("play_sounds", true);
+
+or ::
+
+    converse.settings.set({
+        "play_sounds", true,
+        "hide_offline_users" true
+    });
+
+Note, this is not an alternative to calling ``converse.initialize``, which still needs
+to be called. Generally, you'd use this method after converse.js is already
+running and you want to change the configuration on-the-fly.
+
 "tokens" grouping
 -----------------
 

spec/converse.js

@@ -86,6 +86,28 @@
             }, converse));
         }, converse));
 
+        describe("The \"settings\" API", $.proxy(function() {
+            beforeEach($.proxy(function () {
+                test_utils.closeAllChatBoxes();
+                test_utils.clearBrowserStorage();
+                converse.rosterview.model.reset();
+                test_utils.createContacts('current');
+            }, converse));
+
+            it("has methods 'get' and 'set' to set configuration settings", $.proxy(function () {
+                expect(Object.keys(converse_api.settings)).toEqual(["get", "set"]);
+                expect(converse_api.settings.get("play_sounds")).toBe(false);
+                converse_api.settings.set("play_sounds", true);
+                expect(converse_api.settings.get("play_sounds")).toBe(true);
+                converse_api.settings.set({"play_sounds": false});
+                expect(converse_api.settings.get("play_sounds")).toBe(false);
+                // Only whitelisted settings allowed.
+                expect(typeof converse_api.settings.get("non_existing")).toBe("undefined");
+                converse_api.settings.set("non_existing", true);
+                expect(typeof converse_api.settings.get("non_existing")).toBe("undefined");
+            }, converse));
+        }, converse));
+
         describe("The DEPRECATED API", $.proxy(function() {
             beforeEach($.proxy(function () {
                 test_utils.closeAllChatBoxes();