Converse converse.js

Source: headless/shared/settings/api.js

  1. import isObject from 'lodash-es/isObject';
  2. import log from '@converse/headless/log.js';
  3. import {
  4. clearUserSettings,
  5. extendAppSettings,
  6. getAppSetting,
  7. getUserSettings,
  8. registerListener,
  9. unregisterListener,
  10. updateAppSettings,
  11. updateUserSettings,
  12. } from '@converse/headless/shared/settings/utils.js';
  13. /**
  14. * This grouping allows access to the
  15. * [configuration settings](/docs/html/configuration.html#configuration-settings)
  16. * of Converse.
  17. *
  18. * @namespace _converse.api.settings
  19. * @memberOf _converse.api
  20. */
  21. export const settings_api = {
  22. /**
  23. * Allows new configuration settings to be specified, or new default values for
  24. * existing configuration settings to be specified.
  25. *
  26. * Note, calling this method *after* converse.initialize has been
  27. * called will *not* change the initialization settings provided via
  28. * `converse.initialize`.
  29. *
  30. * @method _converse.api.settings.extend
  31. * @param { object } settings The configuration settings
  32. * @example
  33. * _converse.api.settings.extend({
  34. * 'enable_foo': true
  35. * });
  36. *
  37. * // The user can then override the default value of the configuration setting when
  38. * // calling `converse.initialize`.
  39. * converse.initialize({
  40. * 'enable_foo': false
  41. * });
  42. */
  43. extend (settings) {
  44. return extendAppSettings(settings);
  45. },
  46. update (settings) {
  47. log.warn(
  48. 'The api.settings.update method has been deprecated and will be removed. ' +
  49. 'Please use api.settings.extend instead.'
  50. );
  51. return this.extend(settings);
  52. },
  53. /**
  54. * @method _converse.api.settings.get
  55. * @returns {*} Value of the particular configuration setting.
  56. * @example _converse.api.settings.get("play_sounds");
  57. */
  58. get (key) {
  59. return getAppSetting(key);
  60. },
  61. /**
  62. * Set one or many configuration settings.
  63. *
  64. * Note, this is not an alternative to calling {@link converse.initialize}, which still needs
  65. * to be called. Generally, you'd use this method after Converse is already
  66. * running and you want to change the configuration on-the-fly.
  67. *
  68. * @method _converse.api.settings.set
  69. * @param { Object | string } [settings_or_key]
  70. * An object containing configuration settings.
  71. * Alternatively to passing in an object, you can pass in a key and a value.
  72. * @param { string } [value]
  73. * @example _converse.api.settings.set("play_sounds", true);
  74. * @example
  75. * _converse.api.settings.set({
  76. * "play_sounds": true,
  77. * "hide_offline_users": true
  78. * });
  79. */
  80. set (settings_or_key, value) {
  81. updateAppSettings(settings_or_key, value);
  82. },
  83. /**
  84. * The `listen` namespace exposes methods for creating event listeners
  85. * (aka handlers) for events related to settings.
  86. *
  87. * @namespace _converse.api.settings.listen
  88. * @memberOf _converse.api.settings
  89. */
  90. listen: {
  91. /**
  92. * Register an event listener for the passed in event.
  93. * @method _converse.api.settings.listen.on
  94. * @param { ('change') } name - The name of the event to listen for.
  95. * Currently there is only the 'change' event.
  96. * @param { Function } handler - The event handler function
  97. * @param { Object } [context] - The context of the `this` attribute of the
  98. * handler function.
  99. * @example _converse.api.settings.listen.on('change', callback);
  100. */
  101. on (name, handler, context) {
  102. registerListener(name, handler, context);
  103. },
  104. /**
  105. * To stop listening to an event, you can use the `not` method.
  106. * @method _converse.api.settings.listen.not
  107. * @param { String } name The event's name
  108. * @param { Function } handler The callback method that is to no longer be called when the event fires
  109. * @example _converse.api.settings.listen.not('change', callback);
  110. */
  111. not (name, handler) {
  112. unregisterListener(name, handler);
  113. }
  114. }
  115. };
  116. /**
  117. * API for accessing and setting user settings. User settings are
  118. * different from the application settings from {@link _converse.api.settings}
  119. * because they are per-user and set via user action.
  120. * @namespace _converse.api.user.settings
  121. * @memberOf _converse.api.user
  122. */
  123. export const user_settings_api = {
  124. /**
  125. * Returns the user settings model. Useful when you want to listen for change events.
  126. * @async
  127. * @method _converse.api.user.settings.getModel
  128. * @returns {Promise<Model>}
  129. * @example const settings = await _converse.api.user.settings.getModel();
  130. */
  131. getModel () {
  132. return getUserSettings();
  133. },
  134. /**
  135. * Get the value of a particular user setting.
  136. * @method _converse.api.user.settings.get
  137. * @param { String } key - The setting name
  138. * @param {*} [fallback] - An optional fallback value if the user setting is undefined
  139. * @returns {Promise} Promise which resolves with the value of the particular configuration setting.
  140. * @example _converse.api.user.settings.get("foo");
  141. */
  142. async get (key, fallback) {
  143. const user_settings = await getUserSettings();
  144. return user_settings.get(key) === undefined ? fallback : user_settings.get(key);
  145. },
  146. /**
  147. * Set one or many user settings.
  148. * @async
  149. * @method _converse.api.user.settings.set
  150. * @param { Object } [settings] An object containing configuration settings.
  151. * @param { string } [key] Alternatively to passing in an object, you can pass in a key and a value.
  152. * @param { string } [value]
  153. * @example _converse.api.user.settings.set("foo", "bar");
  154. * @example
  155. * _converse.api.user.settings.set({
  156. * "foo": "bar",
  157. * "baz": "buz"
  158. * });
  159. */
  160. set (key, val) {
  161. if (isObject(key)) {
  162. return updateUserSettings(key, {'promise': true});
  163. } else {
  164. const o = {};
  165. o[key] = val;
  166. return updateUserSettings(o, {'promise': true});
  167. }
  168. },
  169. /**
  170. * Clears all the user settings
  171. * @async
  172. * @method _converse.api.user.settings.clear
  173. */
  174. clear () {
  175. return clearUserSettings();
  176. }
  177. }