|
|
@@ -0,0 +1,151 @@
|
|
|
+import isObject from 'lodash-es/isObject';
|
|
|
+import log from '@converse/headless/log.js';
|
|
|
+import {
|
|
|
+ clearUserSettings,
|
|
|
+ extendAppSettings,
|
|
|
+ getAppSetting,
|
|
|
+ getUserSettings,
|
|
|
+ updateAppSettings,
|
|
|
+ updateUserSettings,
|
|
|
+} from '@converse/headless/shared/settings/utils.js';
|
|
|
+
|
|
|
+/**
|
|
|
+ * This grouping allows access to the
|
|
|
+ * [configuration settings](/docs/html/configuration.html#configuration-settings)
|
|
|
+ * of Converse.
|
|
|
+ *
|
|
|
+ * @namespace _converse.api.settings
|
|
|
+ * @memberOf _converse.api
|
|
|
+ */
|
|
|
+export const settings_api = {
|
|
|
+ /**
|
|
|
+ * Allows new configuration settings to be specified, or new default values for
|
|
|
+ * existing configuration settings to be specified.
|
|
|
+ *
|
|
|
+ * 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.extend({
|
|
|
+ * 'enable_foo': true
|
|
|
+ * });
|
|
|
+ *
|
|
|
+ * // The user can then override the default value of the configuration setting when
|
|
|
+ * // calling `converse.initialize`.
|
|
|
+ * converse.initialize({
|
|
|
+ * 'enable_foo': false
|
|
|
+ * });
|
|
|
+ */
|
|
|
+ extend (settings) {
|
|
|
+ return extendAppSettings(settings);
|
|
|
+ },
|
|
|
+
|
|
|
+ update (settings) {
|
|
|
+ log.warn(
|
|
|
+ 'The api.settings.update 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.
|
|
|
+ * @example _converse.api.settings.get("play_sounds");
|
|
|
+ */
|
|
|
+ get (key) {
|
|
|
+ return getAppSetting(key);
|
|
|
+ },
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Set one or many configuration settings.
|
|
|
+ *
|
|
|
+ * Note, this is not an alternative to calling {@link converse.initialize}, which still needs
|
|
|
+ * to be called. Generally, you'd use this method after Converse is already
|
|
|
+ * running and you want to change the configuration on-the-fly.
|
|
|
+ *
|
|
|
+ * @method _converse.api.settings.set
|
|
|
+ * @param {Object} [settings] An object containing configuration settings.
|
|
|
+ * @param {string} [key] Alternatively to passing in an object, you can pass in a key and a value.
|
|
|
+ * @param {string} [value]
|
|
|
+ * @example _converse.api.settings.set("play_sounds", true);
|
|
|
+ * @example
|
|
|
+ * _converse.api.settings.set({
|
|
|
+ * "play_sounds": true,
|
|
|
+ * "hide_offline_users": true
|
|
|
+ * });
|
|
|
+ */
|
|
|
+ set (key, val) {
|
|
|
+ updateAppSettings(key, val);
|
|
|
+ },
|
|
|
+};
|
|
|
+
|
|
|
+
|
|
|
+/**
|
|
|
+ * API for accessing and setting user settings. User settings are
|
|
|
+ * different from the application settings from {@link _converse.api.settings}
|
|
|
+ * because they are per-user and set via user action.
|
|
|
+ * @namespace _converse.api.user.settings
|
|
|
+ * @memberOf _converse.api.user
|
|
|
+ */
|
|
|
+export const user_settings_api = {
|
|
|
+ /**
|
|
|
+ * Returns the user settings model. Useful when you want to listen for change events.
|
|
|
+ * @async
|
|
|
+ * @method _converse.api.user.settings.getModel
|
|
|
+ * @returns {Promise<Model>}
|
|
|
+ * @example const settings = await _converse.api.user.settings.getModel();
|
|
|
+ */
|
|
|
+ getModel () {
|
|
|
+ return getUserSettings();
|
|
|
+ },
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get the value of a particular user setting.
|
|
|
+ * @method _converse.api.user.settings.get
|
|
|
+ * @param {String} key - The setting name
|
|
|
+ * @param {*} [fallback] - An optional fallback value if the user setting is undefined
|
|
|
+ * @returns {Promise} Promise which resolves with the value of the particular configuration setting.
|
|
|
+ * @example _converse.api.user.settings.get("foo");
|
|
|
+ */
|
|
|
+ async get (key, fallback) {
|
|
|
+ const user_settings = await getUserSettings();
|
|
|
+ return user_settings.get(key) === undefined ? fallback : user_settings.get(key);
|
|
|
+ },
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Set one or many user settings.
|
|
|
+ * @async
|
|
|
+ * @method _converse.api.user.settings.set
|
|
|
+ * @param {Object} [settings] An object containing configuration settings.
|
|
|
+ * @param {string} [key] Alternatively to passing in an object, you can pass in a key and a value.
|
|
|
+ * @param {string} [value]
|
|
|
+ * @example _converse.api.user.settings.set("foo", "bar");
|
|
|
+ * @example
|
|
|
+ * _converse.api.user.settings.set({
|
|
|
+ * "foo": "bar",
|
|
|
+ * "baz": "buz"
|
|
|
+ * });
|
|
|
+ */
|
|
|
+ set (key, val) {
|
|
|
+ if (isObject(key)) {
|
|
|
+ return updateUserSettings(key, {'promise': true});
|
|
|
+ } else {
|
|
|
+ const o = {};
|
|
|
+ o[key] = val;
|
|
|
+ return updateUserSettings(o, {'promise': true});
|
|
|
+ }
|
|
|
+ },
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Clears all the user settings
|
|
|
+ * @async
|
|
|
+ * @method _converse.api.user.settings.clear
|
|
|
+ */
|
|
|
+ clear () {
|
|
|
+ return clearUserSettings();
|
|
|
+ }
|
|
|
+}
|
JC Brand