view.js 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. 'use strict';
  6. import Model from './model.js';
  7. import Collection from '../utils/collection.js';
  8. import Region from './region.js';
  9. import Template from './template.js';
  10. import CKEditorError from '../utils/ckeditorerror.js';
  11. import DOMEmitterMixin from './domemittermixin.js';
  12. import mix from '../utils/mix.js';
  13. /**
  14. * Basic View class.
  15. *
  16. * @memberOf ui
  17. * @mixes DOMEmitterMixin
  18. */
  19. export default class View {
  20. /**
  21. * Creates an instance of the {@link ui.View} class.
  22. *
  23. * @param {utils.Locale} [locale] The {@link ckeditor5.Editor#locale editor's locale} instance.
  24. */
  25. constructor( locale ) {
  26. /**
  27. * Model of this view.
  28. *
  29. * @member {ui.Model} ui.View#model
  30. */
  31. this.model = new Model();
  32. /**
  33. * @readonly
  34. * @member {utils.Locale} ui.View#locale
  35. */
  36. this.locale = locale;
  37. /**
  38. * Shorthand for {@link utils.Locale#t}.
  39. *
  40. * Note: If locale instance hasn't been passed to the view this method may not be available.
  41. *
  42. * @see utils.Locale#t
  43. * @method ui.View#t
  44. */
  45. this.t = locale && locale.t;
  46. /**
  47. * Regions of this view. See {@link ui.View#register}.
  48. *
  49. * @member {utils.Collection} ui.View#regions
  50. */
  51. this.regions = new Collection( {
  52. idProperty: 'name'
  53. } );
  54. /**
  55. * Template of this view.
  56. *
  57. * @member {ui.Template} ui.View#template
  58. */
  59. /**
  60. * Region selectors of this view. See {@link ui.View#register}.
  61. *
  62. * @private
  63. * @member {Object} ui.View#_regionSelectors
  64. */
  65. this._regionSelectors = {};
  66. /**
  67. * Element of this view.
  68. *
  69. * @private
  70. * @member {HTMLElement} ui.View.#_element
  71. */
  72. /**
  73. * Cached {@link ui.Template} binder object specific for this instance.
  74. * See {@link ui.View#bind}.
  75. *
  76. * @private
  77. * @member {Object} ui.View.#_bind
  78. */
  79. }
  80. /**
  81. * Element of this view. The element is rendered on first reference
  82. * using {@link ui.View#template} definition.
  83. *
  84. * @type {HTMLElement}
  85. */
  86. get element() {
  87. if ( this._element ) {
  88. return this._element;
  89. }
  90. // No template means no element (a virtual view).
  91. if ( !this.template ) {
  92. return null;
  93. }
  94. return ( this._element = this.template.render() );
  95. }
  96. set element( el ) {
  97. this._element = el;
  98. }
  99. /**
  100. * Shorthand for {@link ui.Template#bind}, bound to {@link ui.View#model}
  101. * and {@link ui.View} on the first access.
  102. *
  103. * Cached {@link ui.Template#bind} object is stored in {@link ui.View.#_bind}.
  104. *
  105. * @method ui.View#bind
  106. */
  107. get bind() {
  108. if ( this._bind ) {
  109. return this._bind;
  110. }
  111. return ( this._bind = Template.bind( this.model, this ) );
  112. }
  113. /**
  114. * Initializes the view.
  115. *
  116. * Note: {@link ui.Controller} supports if a promise is returned by this method,
  117. * what means that view initialization may be asynchronous.
  118. */
  119. init() {
  120. this._initRegions();
  121. }
  122. /**
  123. * Registers a region in {@link ui.View#regions}.
  124. *
  125. * let view = new View();
  126. *
  127. * // region.name == "foo", region.element == view.element.firstChild
  128. * view.register( 'foo', el => el.firstChild );
  129. *
  130. * // region.name == "bar", region.element == view.element.querySelector( 'span' )
  131. * view.register( new Region( 'bar' ), 'span' );
  132. *
  133. * // region.name == "bar", region.element == view.element.querySelector( '#div#id' )
  134. * view.register( 'bar', 'div#id', true );
  135. *
  136. * // region.name == "baz", region.element == null
  137. * view.register( 'baz', true );
  138. *
  139. * @param {String|Region} stringOrRegion The name or an instance of the Region
  140. * to be registered. If `String`, the region will be created on the fly.
  141. * @param {String|Function|true} regionSelector The selector to retrieve region's element
  142. * in DOM when the region instance is initialized (see {@link Region#init}, {@link ui.View#init}).
  143. * @param {Boolean} [override] When set `true` it will allow overriding of registered regions.
  144. */
  145. register( ...args ) {
  146. let region, regionName;
  147. if ( typeof args[ 0 ] === 'string' ) {
  148. regionName = args[ 0 ];
  149. region = this.regions.get( regionName ) || new Region( regionName );
  150. } else if ( args[ 0 ] instanceof Region ) {
  151. regionName = args[ 0 ].name;
  152. region = args[ 0 ];
  153. } else {
  154. /**
  155. * A name of the region or an instance of Region is required.
  156. *
  157. * @error ui-view-register-wrongtype
  158. */
  159. throw new CKEditorError( 'ui-view-register-wrongtype' );
  160. }
  161. const regionSelector = args[ 1 ];
  162. if ( !regionSelector || !isValidRegionSelector( regionSelector ) ) {
  163. /**
  164. * The selector must be String, Function or `true`.
  165. *
  166. * @error ui-view-register-badselector
  167. */
  168. throw new CKEditorError( 'ui-view-register-badselector' );
  169. }
  170. const registered = this.regions.get( regionName );
  171. if ( !registered ) {
  172. this.regions.add( region );
  173. } else {
  174. if ( registered !== region ) {
  175. if ( !args[ 2 ] ) {
  176. /**
  177. * Overriding is possible only when `override` flag is set.
  178. *
  179. * @error ui-view-register-override
  180. */
  181. throw new CKEditorError( 'ui-view-register-override' );
  182. }
  183. this.regions.remove( registered );
  184. this.regions.add( region );
  185. }
  186. }
  187. this._regionSelectors[ regionName ] = regionSelector;
  188. }
  189. /**
  190. * Destroys the view instance. The process includes:
  191. *
  192. * 1. Removal of child views from {@link ui.View#regions}.
  193. * 2. Destruction of the {@link ui.View#regions}.
  194. * 3. Removal of {@link #_el} from DOM.
  195. */
  196. destroy() {
  197. let childView;
  198. this.stopListening();
  199. for ( let region of this.regions ) {
  200. while ( ( childView = region.views.get( 0 ) ) ) {
  201. region.views.remove( childView );
  202. }
  203. this.regions.remove( region ).destroy();
  204. }
  205. if ( this.template ) {
  206. this.element.remove();
  207. }
  208. this.model = this.regions = this.template = this.locale = this.t = null;
  209. this._regionSelectors = this._element = null;
  210. }
  211. /**
  212. * Initializes {@link ui.View#regions} of this view by passing a DOM element
  213. * generated from {@link ui.View#_regionSelectors} into {@link Region#init}.
  214. *
  215. * @protected
  216. */
  217. _initRegions() {
  218. let region, regionEl, regionSelector;
  219. for ( region of this.regions ) {
  220. regionSelector = this._regionSelectors[ region.name ];
  221. if ( typeof regionSelector == 'string' ) {
  222. regionEl = this.element.querySelector( regionSelector );
  223. } else if ( typeof regionSelector == 'function' ) {
  224. regionEl = regionSelector( this.element );
  225. } else {
  226. regionEl = null;
  227. }
  228. region.init( regionEl );
  229. }
  230. }
  231. }
  232. mix( View, DOMEmitterMixin );
  233. const validSelectorTypes = new Set( [ 'string', 'boolean', 'function' ] );
  234. /**
  235. * Check whether region selector is valid.
  236. *
  237. * @ignore
  238. * @private
  239. * @param {*} selector Selector to be checked.
  240. * @returns {Boolean}
  241. */
  242. function isValidRegionSelector( selector ) {
  243. return validSelectorTypes.has( typeof selector ) && selector !== false;
  244. }