view.js 6.8 KB

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