view.js 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518
  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 ui/view
  7. */
  8. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  9. import ViewCollection from './viewcollection';
  10. import Template from './template';
  11. import DomEmitterMixin from '@ckeditor/ckeditor5-utils/src/dom/emittermixin';
  12. import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
  13. import Collection from '@ckeditor/ckeditor5-utils/src/collection';
  14. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  15. import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
  16. import '../theme/globals/globals.css';
  17. /**
  18. * The basic view class, which represents an HTML element created out of a
  19. * {@link module:ui/view~View#template}. Views are building blocks of the user interface and handle
  20. * interaction
  21. *
  22. * Views {@link module:ui/view~View#registerChild aggregate} children in
  23. * {@link module:ui/view~View#createCollection collections} and manage the life cycle of DOM
  24. * listeners e.g. by handling rendering and destruction.
  25. *
  26. * See the {@link module:ui/template~TemplateDefinition} syntax to learn more about shaping view
  27. * elements, attributes and listeners.
  28. *
  29. * class SampleView extends View {
  30. * constructor( locale ) {
  31. * super( locale );
  32. *
  33. * const bind = this.bindTemplate;
  34. *
  35. * // Views define their interface (state) using observable attributes.
  36. * this.set( 'elementClass', 'bar' );
  37. *
  38. * this.setTemplate( {
  39. * tag: 'p',
  40. *
  41. * // The element of the view can be defined with its children.
  42. * children: [
  43. * 'Hello',
  44. * {
  45. * tag: 'b',
  46. * children: [ 'world!' ]
  47. * }
  48. * ],
  49. * attributes: {
  50. * class: [
  51. * 'foo',
  52. *
  53. * // Observable attributes control the state of the view in DOM.
  54. * bind.to( 'elementClass' )
  55. * ]
  56. * },
  57. * on: {
  58. * // Views listen to DOM events and propagate them.
  59. * click: bind.to( 'clicked' )
  60. * }
  61. * } );
  62. * }
  63. * }
  64. *
  65. * const view = new SampleView( locale );
  66. *
  67. * view.render();
  68. *
  69. * // Append <p class="foo bar">Hello<b>world</b></p> to the <body>
  70. * document.body.appendChild( view.element );
  71. *
  72. * // Change the class attribute to <p class="foo baz">Hello<b>world</b></p>
  73. * view.elementClass = 'baz';
  74. *
  75. * // Respond to the "click" event in DOM by executing a custom action.
  76. * view.on( 'clicked', () => {
  77. * console.log( 'The view has been clicked!' );
  78. * } );
  79. *
  80. * @mixes module:utils/observablemixin~ObservableMixin
  81. */
  82. export default class View {
  83. /**
  84. * Creates an instance of the {@link module:ui/view~View} class.
  85. *
  86. * Also see {@link #render}.
  87. *
  88. * @param {module:utils/locale~Locale} [locale] The localization services instance.
  89. */
  90. constructor( locale ) {
  91. /**
  92. * An HTML element of the view. `null` until {@link #render rendered}
  93. * from the {@link #template}.
  94. *
  95. * class SampleView extends View {
  96. * constructor() {
  97. * super();
  98. *
  99. * // A template instance the #element will be created from.
  100. * this.setTemplate( {
  101. * tag: 'p'
  102. *
  103. * // ...
  104. * } );
  105. * }
  106. * }
  107. *
  108. * const view = new SampleView();
  109. *
  110. * // Renders the #template.
  111. * view.render();
  112. *
  113. * // Append the HTML element of the view to <body>.
  114. * document.body.appendChild( view.element );
  115. *
  116. * **Note**: The element of the view can also be assigned directly:
  117. *
  118. * view.element = document.querySelector( '#my-container' );
  119. *
  120. * @member {HTMLElement}
  121. */
  122. this.element = null;
  123. /**
  124. * Set `true` when the view has already been {@link module:ui/view~View#render rendered}.
  125. *
  126. * @readonly
  127. * @member {Boolean} #isRendered
  128. */
  129. this.isRendered = false;
  130. /**
  131. * A set of tools to localize the user interface.
  132. *
  133. * Also see {@link module:core/editor/editor~Editor#locale}.
  134. *
  135. * @readonly
  136. * @member {module:utils/locale~Locale}
  137. */
  138. this.locale = locale;
  139. /**
  140. * Shorthand for {@link module:utils/locale~Locale#t}.
  141. *
  142. * Note: If {@link #locale} instance hasn't been passed to the view this method may not
  143. * be available.
  144. *
  145. * @see module:utils/locale~Locale#t
  146. * @method
  147. */
  148. this.t = locale && locale.t;
  149. /**
  150. * Collections registered with {@link #createCollection}.
  151. *
  152. * @protected
  153. * @member {Set.<module:ui/viewcollection~ViewCollection>}
  154. */
  155. this._viewCollections = new Collection();
  156. /**
  157. * A collection of view instances, which have been added directly
  158. * into the {@link module:ui/template~Template#children}.
  159. *
  160. * @protected
  161. * @member {module:ui/viewcollection~ViewCollection}
  162. */
  163. this._unboundChildren = this.createCollection();
  164. // Pass parent locale to its children.
  165. this._viewCollections.on( 'add', ( evt, collection ) => {
  166. collection.locale = locale;
  167. } );
  168. /**
  169. * Template of this view. It provides the {@link #element} representing
  170. * the view in DOM, which is {@link #render rendered}.
  171. *
  172. * @member {module:ui/template~Template} #template
  173. */
  174. /**
  175. * Cached {@link module:ui/template~BindChain bind chain} object created by the
  176. * {@link #template}. See {@link #bindTemplate}.
  177. *
  178. * @private
  179. * @member {Object} #_bindTemplate
  180. */
  181. this.decorate( 'render' );
  182. }
  183. /**
  184. * Shorthand for {@link module:ui/template~Template.bind}, a binding
  185. * {@link module:ui/template~BindChain interface} pre–configured for the view instance.
  186. *
  187. * It provides {@link module:ui/template~BindChain#to `to()`} and
  188. * {@link module:ui/template~BindChain#if `if()`} methods that initialize bindings with
  189. * observable attributes and attach DOM listeners.
  190. *
  191. * class SampleView extends View {
  192. * constructor( locale ) {
  193. * super( locale );
  194. *
  195. * const bind = this.bindTemplate;
  196. *
  197. * // These {@link module:utils/observablemixin~Observable observable} attributes will control
  198. * // the state of the view in DOM.
  199. * this.set( {
  200. * elementClass: 'foo',
  201. * isEnabled: true
  202. * } );
  203. *
  204. * this.setTemplate( {
  205. * tag: 'p',
  206. *
  207. * attributes: {
  208. * // The class HTML attribute will follow elementClass
  209. * // and isEnabled view attributes.
  210. * class: [
  211. * bind.to( 'elementClass' )
  212. * bind.if( 'isEnabled', 'present-when-enabled' )
  213. * ]
  214. * },
  215. *
  216. * on: {
  217. * // The view will fire the "clicked" event upon clicking <p> in DOM.
  218. * click: bind.to( 'clicked' )
  219. * }
  220. * } );
  221. * }
  222. * }
  223. *
  224. * @method #bindTemplate
  225. */
  226. get bindTemplate() {
  227. if ( this._bindTemplate ) {
  228. return this._bindTemplate;
  229. }
  230. return ( this._bindTemplate = Template.bind( this, this ) );
  231. }
  232. /**
  233. * Creates a new collection of views, which can be used as
  234. * {@link module:ui/template~Template#children} of this view.
  235. *
  236. * class SampleView extends View {
  237. * constructor( locale ) {
  238. * super( locale );
  239. *
  240. * this.items = this.createCollection();
  241. *
  242. * this.setTemplate( {
  243. * tag: 'p',
  244. *
  245. * // `items` collection will render here.
  246. * children: this.items
  247. * } );
  248. * }
  249. * }
  250. *
  251. * const view = new SampleView( locale );
  252. * const child = new ChildView( locale );
  253. *
  254. * view.render();
  255. *
  256. * // It will append <p></p> to the <body>.
  257. * document.body.appendChild( view.element );
  258. *
  259. * // From now on the child is nested under its parent, which is also reflected in DOM.
  260. * // <p><child#element></p>
  261. * view.items.add( child );
  262. *
  263. * @param {Array.<module:ui/view~View>} [views] Initial views of the collection.
  264. * @returns {module:ui/viewcollection~ViewCollection} A new collection of view instances.
  265. */
  266. createCollection( views ) {
  267. const collection = new ViewCollection( views );
  268. this._viewCollections.add( collection );
  269. return collection;
  270. }
  271. /**
  272. * Registers a new child view under the view instance. Once registered, a child
  273. * view is managed by its parent, including {@link #render rendering}
  274. * and {@link #destroy destruction}.
  275. *
  276. * To revert this, use {@link #deregisterChild}.
  277. *
  278. * class SampleView extends View {
  279. * constructor( locale ) {
  280. * super( locale );
  281. *
  282. * this.childA = new SomeChildView( locale );
  283. * this.childB = new SomeChildView( locale );
  284. *
  285. * this.setTemplate( { tag: 'p' } );
  286. *
  287. * // Register the children.
  288. * this.registerChild( [ this.childA, this.childB ] );
  289. * }
  290. *
  291. * render() {
  292. * super.render();
  293. *
  294. * this.element.appendChild( this.childA.element );
  295. * this.element.appendChild( this.childB.element );
  296. * }
  297. * }
  298. *
  299. * const view = new SampleView( locale );
  300. *
  301. * view.render();
  302. *
  303. * // Will append <p><childA#element><b></b><childB#element></p>.
  304. * document.body.appendChild( view.element );
  305. *
  306. * **Note**: There's no need to add child views if they're already referenced in the
  307. * {@link #template}:
  308. *
  309. * class SampleView extends View {
  310. * constructor( locale ) {
  311. * super( locale );
  312. *
  313. * this.childA = new SomeChildView( locale );
  314. * this.childB = new SomeChildView( locale );
  315. *
  316. * this.setTemplate( {
  317. * tag: 'p',
  318. *
  319. * // These children will be added automatically. There's no
  320. * // need to call {@link #registerChild} for any of them.
  321. * children: [ this.childA, this.childB ]
  322. * } );
  323. * }
  324. *
  325. * // ...
  326. * }
  327. *
  328. * @param {module:ui/view~View|Iterable.<module:ui/view~View>} children Children views to be registered.
  329. */
  330. registerChild( children ) {
  331. if ( !isIterable( children ) ) {
  332. children = [ children ];
  333. }
  334. for ( const child of children ) {
  335. this._unboundChildren.add( child );
  336. }
  337. }
  338. /**
  339. * The opposite of {@link #registerChild}. Removes a child view from this view instance.
  340. * Once removed, the child is no longer managed by its parent, e.g. it can safely
  341. * become a child of another parent view.
  342. *
  343. * @see #registerChild
  344. * @param {module:ui/view~View|Iterable.<module:ui/view~View>} children Child views to be removed.
  345. */
  346. deregisterChild( children ) {
  347. if ( !isIterable( children ) ) {
  348. children = [ children ];
  349. }
  350. for ( const child of children ) {
  351. this._unboundChildren.remove( child );
  352. }
  353. }
  354. /**
  355. * Sets the {@link #template} of the view with with given definition.
  356. *
  357. * A shorthand for:
  358. *
  359. * view.setTemplate( definition );
  360. *
  361. * @param {module:ui/template~TemplateDefinition} definition Definition of view's template.
  362. */
  363. setTemplate( definition ) {
  364. this.template = new Template( definition );
  365. }
  366. /**
  367. * {@link module:ui/template~Template.extend Extends} the {@link #template} of the view with
  368. * with given definition.
  369. *
  370. * A shorthand for:
  371. *
  372. * Template.extend( view.template, definition );
  373. *
  374. * **Note**: Is requires the {@link #template} to be already set. See {@link #setTemplate}.
  375. *
  376. * @param {module:ui/template~TemplateDefinition} definition Definition which
  377. * extends the {@link #template}.
  378. */
  379. extendTemplate( definition ) {
  380. Template.extend( this.template, definition );
  381. }
  382. /**
  383. * Recursively renders the view.
  384. *
  385. * Once the view is rendered:
  386. * * the {@link #element} becomes an HTML element out of {@link #template},
  387. * * the {@link #isRendered} flag is set `true`.
  388. *
  389. * **Note**: The children of the view:
  390. * * defined directly in the {@link #template}
  391. * * residing in collections created by the {@link #createCollection} method,
  392. * * and added by {@link #registerChild}
  393. * are also rendered in the process.
  394. *
  395. * In general, `render()` method is the right place to keep the code which refers to the
  396. * {@link #element} and should be executed at the very beginning of the view's life cycle.
  397. *
  398. * It is possible to {@link module:ui/template~Template.extend} the {@link #template} before
  399. * the view is rendered. To allow an early customization of the view (e.g. by its parent),
  400. * such references should be done in `render()`.
  401. *
  402. * class SampleView extends View {
  403. * constructor() {
  404. * this.setTemplate( {
  405. * // ...
  406. * } );
  407. * },
  408. *
  409. * render() {
  410. * // View#element becomes available.
  411. * super.render();
  412. *
  413. * // The "scroll" listener depends on #element.
  414. * this.listenTo( window, 'scroll', () => {
  415. * // A reference to #element would render the #template and make it non-extendable.
  416. * if ( window.scrollY > 0 ) {
  417. * this.element.scrollLeft = 100;
  418. * } else {
  419. * this.element.scrollLeft = 0;
  420. * }
  421. * } );
  422. * }
  423. * }
  424. *
  425. * const view = new SampleView();
  426. *
  427. * // Let's customize the view before it gets rendered.
  428. * view.extendTemplate( {
  429. * attributes: {
  430. * class: [
  431. * 'additional-class'
  432. * ]
  433. * }
  434. * } );
  435. *
  436. * // Late rendering allows customization of the view.
  437. * view.render();
  438. */
  439. render() {
  440. if ( this.isRendered ) {
  441. /**
  442. * This View has already been rendered.
  443. *
  444. * @error ui-view-render-rendered
  445. */
  446. throw new CKEditorError(
  447. 'ui-view-render-already-rendered: This View has already been rendered.',
  448. this
  449. );
  450. }
  451. // Render #element of the view.
  452. if ( this.template ) {
  453. this.element = this.template.render();
  454. // Auto–register view children from #template.
  455. this.registerChild( this.template.getViews() );
  456. }
  457. this.isRendered = true;
  458. }
  459. /**
  460. * Recursively destroys the view instance and child views added by {@link #registerChild} and
  461. * residing in collections created by the {@link #createCollection}.
  462. *
  463. * Destruction disables all event listeners:
  464. * * created on the view, e.g. `view.on( 'event', () => {} )`,
  465. * * defined in the {@link #template} for DOM events.
  466. */
  467. destroy() {
  468. this.stopListening();
  469. this._viewCollections.map( c => c.destroy() );
  470. // Template isn't obligatory for views.
  471. if ( this.template && this.template._revertData ) {
  472. this.template.revert( this.element );
  473. }
  474. }
  475. /**
  476. * Event fired by the {@link #render} method. Actual rendering is executed as a listener to
  477. * this event with the default priority.
  478. *
  479. * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
  480. *
  481. * @event render
  482. */
  483. }
  484. mix( View, DomEmitterMixin );
  485. mix( View, ObservableMixin );