config.js 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module utils/config
  7. */
  8. import { isPlainObject, isElement, cloneDeepWith } from 'lodash-es';
  9. /**
  10. * Handles a configuration dictionary.
  11. */
  12. export default class Config {
  13. /**
  14. * Creates an instance of the {@link ~Config} class.
  15. *
  16. * @param {Object} [configurations] The initial configurations to be set. Usually, provided by the user.
  17. * @param {Object} [defaultConfigurations] The default configurations. Usually, provided by the system.
  18. */
  19. constructor( configurations, defaultConfigurations ) {
  20. /**
  21. * Store for the whole configuration.
  22. *
  23. * @private
  24. * @member {Object}
  25. */
  26. this._config = {};
  27. // Set default configuration.
  28. if ( defaultConfigurations ) {
  29. // Clone the configuration to make sure that the properties will not be shared
  30. // between editors and make the watchdog feature work correctly.
  31. this.define( cloneConfig( defaultConfigurations ) );
  32. }
  33. // Set initial configuration.
  34. if ( configurations ) {
  35. this._setObjectToTarget( this._config, configurations );
  36. }
  37. }
  38. /**
  39. * Set configuration values.
  40. *
  41. * It accepts both a name/value pair or an object, which properties and values will be used to set
  42. * configurations.
  43. *
  44. * It also accepts setting a "deep configuration" by using dots in the name. For example, `'resize.width'` sets
  45. * the value for the `width` configuration in the `resize` subset.
  46. *
  47. * config.set( 'width', 500 );
  48. * config.set( 'toolbar.collapsed', true );
  49. *
  50. * // Equivalent to:
  51. * config.set( {
  52. * width: 500
  53. * toolbar: {
  54. * collapsed: true
  55. * }
  56. * } );
  57. *
  58. * Passing an object as the value will amend the configuration, not replace it.
  59. *
  60. * config.set( 'toolbar', {
  61. * collapsed: true,
  62. * } );
  63. *
  64. * config.set( 'toolbar', {
  65. * color: 'red',
  66. * } );
  67. *
  68. * config.get( 'toolbar.collapsed' ); // true
  69. * config.get( 'toolbar.color' ); // 'red'
  70. *
  71. * @param {String|Object} name The configuration name or an object from which take properties as
  72. * configuration entries. Configuration names are case-sensitive.
  73. * @param {*} value The configuration value. Used if a name is passed.
  74. */
  75. set( name, value ) {
  76. this._setToTarget( this._config, name, value );
  77. }
  78. /**
  79. * Does exactly the same as {@link #set} with one exception – passed configuration extends
  80. * existing one, but does not overwrite already defined values.
  81. *
  82. * This method is supposed to be called by plugin developers to setup plugin's configurations. It would be
  83. * rarely used for other needs.
  84. *
  85. * @param {String|Object} name The configuration name or an object from which take properties as
  86. * configuration entries. Configuration names are case-sensitive.
  87. * @param {*} value The configuration value. Used if a name is passed.
  88. */
  89. define( name, value ) {
  90. const isDefine = true;
  91. this._setToTarget( this._config, name, value, isDefine );
  92. }
  93. /**
  94. * Gets the value for a configuration entry.
  95. *
  96. * config.get( 'name' );
  97. *
  98. * Deep configurations can be retrieved by separating each part with a dot.
  99. *
  100. * config.get( 'toolbar.collapsed' );
  101. *
  102. * @param {String} name The configuration name. Configuration names are case-sensitive.
  103. * @returns {*} The configuration value or `undefined` if the configuration entry was not found.
  104. */
  105. get( name ) {
  106. return this._getFromSource( this._config, name );
  107. }
  108. /**
  109. * Iterates over all top level configuration names.
  110. *
  111. * @returns {Iterable.<String>}
  112. */
  113. * names() {
  114. for ( const name of Object.keys( this._config ) ) {
  115. yield name;
  116. }
  117. }
  118. /**
  119. * Saves passed configuration to the specified target (nested object).
  120. *
  121. * @private
  122. * @param {Object} target Nested config object.
  123. * @param {String|Object} name The configuration name or an object from which take properties as
  124. * configuration entries. Configuration names are case-sensitive.
  125. * @param {*} value The configuration value. Used if a name is passed.
  126. * @param {Boolean} [isDefine=false] Define if passed configuration should overwrite existing one.
  127. */
  128. _setToTarget( target, name, value, isDefine = false ) {
  129. // In case of an object, iterate through it and call `_setToTarget` again for each property.
  130. if ( isPlainObject( name ) ) {
  131. this._setObjectToTarget( target, name, isDefine );
  132. return;
  133. }
  134. // The configuration name should be split into parts if it has dots. E.g. `resize.width` -> [`resize`, `width`].
  135. const parts = name.split( '.' );
  136. // Take the name of the configuration out of the parts. E.g. `resize.width` -> `width`.
  137. name = parts.pop();
  138. // Iterate over parts to check if currently stored configuration has proper structure.
  139. for ( const part of parts ) {
  140. // If there is no object for specified part then create one.
  141. if ( !isPlainObject( target[ part ] ) ) {
  142. target[ part ] = {};
  143. }
  144. // Nested object becomes a target.
  145. target = target[ part ];
  146. }
  147. // In case of value is an object.
  148. if ( isPlainObject( value ) ) {
  149. // We take care of proper config structure.
  150. if ( !isPlainObject( target[ name ] ) ) {
  151. target[ name ] = {};
  152. }
  153. target = target[ name ];
  154. // And iterate through this object calling `_setToTarget` again for each property.
  155. this._setObjectToTarget( target, value, isDefine );
  156. return;
  157. }
  158. // Do nothing if we are defining configuration for non empty name.
  159. if ( isDefine && typeof target[ name ] != 'undefined' ) {
  160. return;
  161. }
  162. target[ name ] = value;
  163. }
  164. /**
  165. * Get specified configuration from specified source (nested object).
  166. *
  167. * @private
  168. * @param {Object} source level of nested object.
  169. * @param {String} name The configuration name. Configuration names are case-sensitive.
  170. * @returns {*} The configuration value or `undefined` if the configuration entry was not found.
  171. */
  172. _getFromSource( source, name ) {
  173. // The configuration name should be split into parts if it has dots. E.g. `resize.width` -> [`resize`, `width`].
  174. const parts = name.split( '.' );
  175. // Take the name of the configuration out of the parts. E.g. `resize.width` -> `width`.
  176. name = parts.pop();
  177. // Iterate over parts to check if currently stored configuration has proper structure.
  178. for ( const part of parts ) {
  179. if ( !isPlainObject( source[ part ] ) ) {
  180. source = null;
  181. break;
  182. }
  183. // Nested object becomes a source.
  184. source = source[ part ];
  185. }
  186. // Always returns undefined for non existing configuration.
  187. return source ? cloneConfig( source[ name ] ) : undefined;
  188. }
  189. /**
  190. * Iterates through passed object and calls {@link #_setToTarget} method with object key and value for each property.
  191. *
  192. * @private
  193. * @param {Object} target Nested config object.
  194. * @param {Object} configuration Configuration data set
  195. * @param {Boolean} [isDefine] Defines if passed configuration is default configuration or not.
  196. */
  197. _setObjectToTarget( target, configuration, isDefine ) {
  198. Object.keys( configuration ).forEach( key => {
  199. this._setToTarget( target, key, configuration[ key ], isDefine );
  200. } );
  201. }
  202. }
  203. // Clones configuration object or value.
  204. // @param {*} source Source configuration
  205. // @returns {*} Cloned configuration value.
  206. function cloneConfig( source ) {
  207. return cloneDeepWith( source, leaveDOMReferences );
  208. }
  209. // A customized function for cloneDeepWith.
  210. // It will leave references to DOM Elements instead of cloning them.
  211. //
  212. // @param {*} value
  213. // @returns {Element|undefined}
  214. function leaveDOMReferences( value ) {
  215. return isElement( value ) ? value : undefined;
  216. }