Rename `api.settings.update` to `api.settings.extend`

This is to try and make it clearer that this method won't override
initialization settings, and is instead simply to add to the default
settings.

CHANGES.md

@@ -25,6 +25,7 @@ Soon we'll deprecate the latter, so prepare now.
 - #2002: fix rendering of `muc_roomid_policy_hint`
 - #2006: fix rendering of emojis in case `use_system_emojis == false`
 - #2028: Implement XEP-0333 `displayed` chat marker
+- The API method `api.settings.update` has been deprecated in favor of `api.settings.extend`.
 - Filter roster contacts via all available information (JID, nickname and VCard full name).
 - Allow ignoring of bootstrap modules at build using environment variable. For xample: `export BOOTSTRAP_IGNORE_MODULES="Modal,Dropdown" && make dist`
 - Bugfix. Handle stanza that clears the MUC subject

spec/converse.js

@@ -4,19 +4,6 @@ describe("Converse", function() {
 
     describe("Settings", function () {
 
-        it("extended via settings.update don't override settings passed in via converse.initialize",
-                mock.initConverse([], {'emoji_categories': {"travel": ":rocket:"}}, (done, _converse) => {
-
-            expect(_converse.api.settings.get('emoji_categories')?.travel).toBe(':rocket:');
-
-            // Test that the update command doesn't override user-provided site
-            // settings (i.e. settings passed in via converse.initialize).
-            _converse.api.settings.update({'emoji_categories': {"travel": ":motorcycle:", "food": ":burger:"}});
-
-            expect(_converse.api.settings.get('emoji_categories')?.travel).toBe(':rocket:');
-            expect(_converse.api.settings.get('emoji_categories')?.food).toBe(undefined);
-            done();
-        }));
     });
 
     describe("Authentication", function () {
@@ -340,7 +327,7 @@ describe("Converse", function() {
         it("has methods 'get' and 'set' to set configuration settings",
                 mock.initConverse(null, {'play_sounds': true}, (done, _converse) => {
 
-            expect(Object.keys(_converse.api.settings)).toEqual(["update", "get", "set"]);
+            expect(Object.keys(_converse.api.settings)).toEqual(["extend", "update", "get", "set"]);
             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);
@@ -352,6 +339,21 @@ describe("Converse", function() {
             expect(typeof _converse.api.settings.get("non_existing")).toBe("undefined");
             done();
         }));
+
+        it("extended via settings.extend don't override settings passed in via converse.initialize",
+                mock.initConverse([], {'emoji_categories': {"travel": ":rocket:"}}, (done, _converse) => {
+
+            expect(_converse.api.settings.get('emoji_categories')?.travel).toBe(':rocket:');
+
+            // Test that the extend command doesn't override user-provided site
+            // settings (i.e. settings passed in via converse.initialize).
+            _converse.api.settings.extend({'emoji_categories': {"travel": ":motorcycle:", "food": ":burger:"}});
+
+            expect(_converse.api.settings.get('emoji_categories')?.travel).toBe(':rocket:');
+            expect(_converse.api.settings.get('emoji_categories')?.food).toBe(undefined);
+            done();
+        }));
+
     });
 
     describe("The \"plugins\" API", function() {

spec/messages.js

@@ -15,6 +15,9 @@ describe("A Chat Message", function () {
         await mock.openChatBoxFor(_converse, contact_jid);
         const view = _converse.api.chatviews.get(contact_jid);
         await _converse.handleMessageStanza(mock.createChatMessage(_converse, contact_jid, 'This message will be read'));
+        const msg_el = await u.waitUntil(() => view.el.querySelector('converse-chat-message'));
+        expect(msg_el.querySelector('.chat-msg__text').textContent).toBe('This message will be read');
+        expect(view.model.get('num_unread')).toBe(0);
 
         _converse.windowState = 'hidden';
         await _converse.handleMessageStanza(mock.createChatMessage(_converse, contact_jid, 'This message will be new'));

src/converse-bookmark-views.js

@@ -40,7 +40,7 @@ converse.plugins.add('converse-bookmark-views', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             hide_open_bookmarks: true,
         });
 

src/converse-chatboxviews.js

@@ -54,7 +54,7 @@ converse.plugins.add('converse-chatboxviews', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             'animate': true,
             'theme': 'default'
         });

src/converse-chatview.js

@@ -51,7 +51,7 @@ converse.plugins.add('converse-chatview', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             'auto_focus': true,
             'message_limit': 0,
             'muc_hats_from_vcard': false,

src/converse-controlbox.js

@@ -99,7 +99,7 @@ converse.plugins.add('converse-controlbox', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             allow_logout: true,
             default_domain: undefined,
             locked_domain: undefined,

src/converse-dragresize.js

@@ -133,7 +133,7 @@ converse.plugins.add('converse-dragresize', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             'allow_dragresize': true,
         });
 

src/converse-emoji-views.js

@@ -69,7 +69,7 @@ converse.plugins.add('converse-emoji-views', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             'use_system_emojis': true,
             'visible_toolbar_buttons': {
                 'emoji': true

src/converse-fullscreen.js

@@ -7,7 +7,7 @@ import "@converse/headless/converse-muc";
 import "converse-chatview";
 import "converse-controlbox";
 import "converse-singleton";
-import { converse } from "@converse/headless/converse-core";
+import { _converse, api, converse } from "@converse/headless/converse-core";
 import tpl_brand_heading from "templates/inverse_brand_heading.html";
 
 
@@ -26,14 +26,12 @@ converse.plugins.add('converse-fullscreen', {
 
         ControlBoxView: {
             createBrandHeadingHTML() {
-                const { _converse } = this.__super__;
                 return tpl_brand_heading({
                     'version_name': _converse.VERSION_NAME
                 });
             },
 
             insertBrandHeading () {
-                const { _converse } = this.__super__;
                 const el = _converse.root.getElementById('converse-login-panel');
                 el.parentNode.insertAdjacentHTML(
                     'afterbegin',
@@ -44,7 +42,7 @@ converse.plugins.add('converse-fullscreen', {
     },
 
     initialize () {
-        this._converse.api.settings.update({
+        api.settings.extend({
             chatview_avatar_height: 50,
             chatview_avatar_width: 50,
             hide_open_bookmarks: true,

src/converse-minimize.js

@@ -114,7 +114,7 @@ converse.plugins.add('converse-minimize', {
          * loaded by Converse.js's plugin machinery.
          */
 
-        api.settings.update({'no_trimming': false});
+        api.settings.extend({'no_trimming': false});
 
         const minimizableChatBox = {
             maximize () {

src/converse-muc-views.js

@@ -92,7 +92,7 @@ converse.plugins.add('converse-muc-views', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             'auto_list_rooms': false,
             'cache_muc_messages': true,
             'locked_muc_nickname': false,

src/converse-notification.js

@@ -22,7 +22,7 @@ converse.plugins.add('converse-notification', {
          */
         _converse.supports_html5_notification = "Notification" in window;
 
-        api.settings.update({
+        api.settings.extend({
             notify_all_room_messages: false,
             show_desktop_notifications: true,
             show_chat_state_notifications: false,

src/converse-oauth.js

@@ -73,7 +73,7 @@ converse.plugins.add("converse-oauth", {
         const { api } = _converse;
         const { __ } = _converse;
 
-        api.settings.update({
+        api.settings.extend({
             'oauth_providers': [],
         });
 

src/converse-omemo.js

@@ -215,7 +215,7 @@ converse.plugins.add('converse-omemo', {
          * loaded by Converse.js's plugin machinery.
          */
 
-        api.settings.update({'omemo_default': false});
+        api.settings.extend({'omemo_default': false});
 
         api.promises.add(['OMEMOInitialized']);
 

src/converse-profile.js

@@ -29,7 +29,7 @@ converse.plugins.add('converse-profile', {
          * loaded by converse.js's plugin machinery.
          */
 
-        api.settings.update({
+        api.settings.extend({
             'allow_adhoc_commands': true,
             'show_client_info': true
         });

src/converse-push.js

@@ -21,7 +21,7 @@ converse.plugins.add('converse-push', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             'push_app_servers': [],
             'enable_muc_push': false
         });

src/converse-register.js

@@ -69,7 +69,7 @@ converse.plugins.add('converse-register', {
         _converse.CONNECTION_STATUS[Strophe.Status.CONFLICT] = 'CONFLICT';
         _converse.CONNECTION_STATUS[Strophe.Status.NOTACCEPTABLE] = 'NOTACCEPTABLE';
 
-        api.settings.update({
+        api.settings.extend({
             'allow_registration': true,
             'domain_placeholder': __(" e.g. conversejs.org"),  // Placeholder text shown in the domain input on the registration form
             'providers_link': 'https://compliance.conversations.im/', // Link to XMPP providers shown on registration page

src/converse-rosterview.js

@@ -35,7 +35,7 @@ converse.plugins.add('converse-rosterview', {
          * loaded by converse.js's plugin machinery.
          */
 
-        api.settings.update({
+        api.settings.extend({
             'autocomplete_add_contact': true,
             'allow_chat_pending_contacts': true,
             'allow_contact_removal': true,

src/converse-singleton.js

@@ -17,7 +17,7 @@ converse.plugins.add('converse-singleton', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by converse.js's plugin machinery.
          */
-        this._converse.api.settings.update({
+        this._converse.api.settings.extend({
             'allow_logout': false,          // No point in logging out when we have auto_login as true.
             'allow_muc_invitations': false, // Doesn't make sense to allow because only
                                             // roster contacts can be invited

src/headless/converse-bookmarks.js

@@ -66,7 +66,7 @@ converse.plugins.add('converse-bookmarks', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             allow_bookmarks: true,
             allow_public_bookmarks: false,
             muc_respect_autojoin: true

src/headless/converse-bosh.js

@@ -21,7 +21,7 @@ converse.plugins.add('converse-bosh', {
     },
 
     initialize () {
-        api.settings.update({
+        api.settings.extend({
             bosh_service_url: undefined,
             prebind_url: null
         });

src/headless/converse-chat.js

@@ -40,7 +40,7 @@ converse.plugins.add('converse-chat', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             'allow_message_corrections': 'all',
             'allow_message_retraction': 'all',
             'auto_join_private_chats': [],

src/headless/converse-core.js

@@ -637,10 +637,14 @@ export const api = _converse.api = {
          * Allows new configuration settings to be specified, or new default values for
          * existing configuration settings to be specified.
          *
-         * @method _converse.api.settings.update
+         * Note, calling this method *after* converse.initialize has been
+         * called will *not* change the initialization settings provided via
+         * `converse.initialize`.
+         *
+         * @method _converse.api.settings.extend
          * @param {object} settings The configuration settings
          * @example
-         * _converse.api.settings.update({
+         * _converse.api.settings.extend({
          *    'enable_foo': true
          * });
          *
@@ -650,7 +654,7 @@ export const api = _converse.api = {
          *     'enable_foo': false
          * });
          */
-        update (settings) {
+        extend (settings) {
             u.merge(DEFAULT_SETTINGS, settings);
             // When updating the settings, we need to avoid overwriting the
             // initialization_settings (i.e. the settings passed in via converse.initialize).
@@ -661,6 +665,12 @@ export const api = _converse.api = {
             u.merge(_converse, updated_settings); // FIXME: remove
         },
 
+        update (settings) {
+            log.warn("The api.settings.extend method has been deprecated and will be removed. "+
+                     "Please use api.settings.extend instead.");
+            return this.extend(settings);
+        },
+
         /**
          * @method _converse.api.settings.get
          * @returns {*} Value of the particular configuration setting.

src/headless/converse-emoji.js

@@ -62,7 +62,7 @@ converse.plugins.add('converse-emoji', {
          */
         const { ___ } = _converse;
 
-        api.settings.update({
+        api.settings.extend({
             'emoji_image_path': twemoji.default.base,
             'emoji_categories': {
                 "smileys": ":grinning:",

src/headless/converse-mam.js

@@ -131,7 +131,7 @@ converse.plugins.add('converse-mam', {
         /* The initialize function gets called as soon as the plugin is
          * loaded by Converse.js's plugin machinery.
          */
-        api.settings.update({
+        api.settings.extend({
             archived_messages_page_size: '50',
             message_archiving: undefined, // Supported values are 'always', 'never', 'roster' (https://xmpp.org/extensions/xep-0313.html#prefs)
             message_archiving_timeout: 20000, // Time (in milliseconds) to wait before aborting MAM request

src/headless/converse-muc.js

@@ -114,7 +114,7 @@ converse.plugins.add('converse-muc', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             'allow_muc': true,
             'allow_muc_invitations': true,
             'auto_join_on_invite': false,

src/headless/converse-ping.js

@@ -23,7 +23,7 @@ converse.plugins.add('converse-ping', {
          */
         let lastStanzaDate;
 
-        api.settings.update({
+        api.settings.extend({
             ping_interval: 60 //in seconds
         });
 

src/headless/converse-roster.js

@@ -24,7 +24,7 @@ converse.plugins.add('converse-roster', {
          */
         const { __ } = _converse;
 
-        api.settings.update({
+        api.settings.extend({
             'allow_contact_requests': true,
             'auto_subscribe': false,
             'synchronize_availability': true,

src/headless/converse-smacks.js

@@ -22,7 +22,7 @@ converse.plugins.add('converse-smacks', {
         // ====================================
         // Refer to docs/source/configuration.rst for explanations of these
         // configuration settings.
-        api.settings.update({
+        api.settings.extend({
             'enable_smacks': true,
             'smacks_max_unacked_stanzas': 5,
         });

src/headless/converse-status.js

@@ -14,7 +14,7 @@ converse.plugins.add('converse-status', {
 
     initialize () {
 
-        api.settings.update({
+        api.settings.extend({
             auto_away: 0, // Seconds after which user status is set to 'away'
             auto_xa: 0, // Seconds after which user status is set to 'xa'
             csi_waiting_time: 0, // Support for XEP-0352. Seconds before client is considered idle and CSI is sent out.