viewcollection.js 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  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/viewcollection
  7. */
  8. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  9. import Collection from '@ckeditor/ckeditor5-utils/src/collection';
  10. /**
  11. * Collects {@link module:ui/view~View} instances.
  12. *
  13. * const parentView = new ParentView( locale );
  14. * const collection = new ViewCollection( locale );
  15. *
  16. * collection.setParent( parentView.element );
  17. *
  18. * const viewA = new ChildView( locale );
  19. * const viewB = new ChildView( locale );
  20. *
  21. * View collection renders and manages view {@link module:ui/view~View#element elements}:
  22. *
  23. * collection.add( viewA );
  24. * collection.add( viewB );
  25. *
  26. * console.log( parentView.element.firsChild ); // -> viewA.element
  27. * console.log( parentView.element.lastChild ); // -> viewB.element
  28. *
  29. * It {@link module:ui/viewcollection~ViewCollection#delegate propagates} DOM events too:
  30. *
  31. * // Delegate #click and #keydown events from viewA and viewB to the parentView.
  32. * collection.delegate( 'click' ).to( parentView );
  33. *
  34. * parentView.on( 'click', ( evt ) => {
  35. * console.log( `${ evt.source } has been clicked.` );
  36. * } );
  37. *
  38. * // This event will be delegated to the parentView.
  39. * viewB.fire( 'click' );
  40. *
  41. * **Note**: A view collection can be used directly in the {@link module:ui/template~TemplateDefinition definition}
  42. * of a {@link module:ui/template~Template template}.
  43. *
  44. * @extends module:utils/collection~Collection
  45. * @mixes module:utils/observablemixin~ObservableMixin
  46. */
  47. export default class ViewCollection extends Collection {
  48. /**
  49. * Creates a new instance of the {@link module:ui/viewcollection~ViewCollection}.
  50. *
  51. * @param {Iterable.<module:ui/view~View>} [initialItems] The initial items of the collection.
  52. */
  53. constructor( initialItems = [] ) {
  54. super( initialItems, {
  55. // An #id Number attribute should be legal and not break the `ViewCollection` instance.
  56. // https://github.com/ckeditor/ckeditor5-ui/issues/93
  57. idProperty: 'viewUid'
  58. } );
  59. // Handle {@link module:ui/view~View#element} in DOM when a new view is added to the collection.
  60. this.on( 'add', ( evt, view, index ) => {
  61. this._renderViewIntoCollectionParent( view, index );
  62. } );
  63. // Handle {@link module:ui/view~View#element} in DOM when a view is removed from the collection.
  64. this.on( 'remove', ( evt, view ) => {
  65. if ( view.element && this._parentElement ) {
  66. view.element.remove();
  67. }
  68. } );
  69. /**
  70. * A parent element within which child views are rendered and managed in DOM.
  71. *
  72. * @protected
  73. * @member {HTMLElement}
  74. */
  75. this._parentElement = null;
  76. }
  77. /**
  78. * Destroys the view collection along with child views.
  79. * See the view {@link module:ui/view~View#destroy} method.
  80. */
  81. destroy() {
  82. this.map( view => view.destroy() );
  83. }
  84. /**
  85. * Sets the parent HTML element of this collection. When parent is set, {@link #add adding} and
  86. * {@link #remove removing} views in the collection synchronizes their
  87. * {@link module:ui/view~View#element elements} in the parent element.
  88. *
  89. * @param {HTMLElement} element A new parent element.
  90. */
  91. setParent( elementOrDocFragment ) {
  92. this._parentElement = elementOrDocFragment;
  93. // Take care of the initial collection items passed to the constructor.
  94. for ( const view of this ) {
  95. this._renderViewIntoCollectionParent( view );
  96. }
  97. }
  98. /**
  99. * Delegates selected events coming from within views in the collection to any
  100. * {@link module:utils/emittermixin~Emitter}.
  101. *
  102. * For the following views and collection:
  103. *
  104. * const viewA = new View();
  105. * const viewB = new View();
  106. * const viewC = new View();
  107. *
  108. * const views = parentView.createCollection();
  109. *
  110. * views.delegate( 'eventX' ).to( viewB );
  111. * views.delegate( 'eventX', 'eventY' ).to( viewC );
  112. *
  113. * views.add( viewA );
  114. *
  115. * the `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:
  116. *
  117. * viewA.fire( 'eventX', customData );
  118. *
  119. * and `eventY` is delegated (fired by) `viewC` along with `customData`:
  120. *
  121. * viewA.fire( 'eventY', customData );
  122. *
  123. * See {@link module:utils/emittermixin~Emitter#delegate}.
  124. *
  125. * @param {...String} events {@link module:ui/view~View} event names to be delegated to another
  126. * {@link module:utils/emittermixin~Emitter}.
  127. * @returns {Object}
  128. * @returns {Function} return.to A function which accepts the destination of
  129. * {@link module:utils/emittermixin~Emitter#delegate delegated} events.
  130. */
  131. delegate( ...events ) {
  132. if ( !events.length || !isStringArray( events ) ) {
  133. /**
  134. * All event names must be strings.
  135. *
  136. * @error ui-viewcollection-delegate-wrong-events
  137. */
  138. throw new CKEditorError(
  139. 'ui-viewcollection-delegate-wrong-events: All event names must be strings.',
  140. this
  141. );
  142. }
  143. return {
  144. /**
  145. * Selects destination for {@link module:utils/emittermixin~Emitter#delegate} events.
  146. *
  147. * @memberOf module:ui/viewcollection~ViewCollection#delegate
  148. * @function module:ui/viewcollection~ViewCollection#delegate.to
  149. * @param {module:utils/emittermixin~Emitter} dest An `Emitter` instance which is
  150. * the destination for delegated events.
  151. */
  152. to: dest => {
  153. // Activate delegating on existing views in this collection.
  154. for ( const view of this ) {
  155. for ( const evtName of events ) {
  156. view.delegate( evtName ).to( dest );
  157. }
  158. }
  159. // Activate delegating on future views in this collection.
  160. this.on( 'add', ( evt, view ) => {
  161. for ( const evtName of events ) {
  162. view.delegate( evtName ).to( dest );
  163. }
  164. } );
  165. // Deactivate delegating when view is removed from this collection.
  166. this.on( 'remove', ( evt, view ) => {
  167. for ( const evtName of events ) {
  168. view.stopDelegating( evtName, dest );
  169. }
  170. } );
  171. }
  172. };
  173. }
  174. /**
  175. * This method {@link module:ui/view~View#render renders} a new view added to the collection.
  176. *
  177. * If the {@link #_parentElement parent element} of the collection is set, this method also adds
  178. * the view's {@link module:ui/view~View#element} as a child of the parent in DOM at a specified index.
  179. *
  180. * **Note**: If index is not specified, the view's element is pushed as the last child
  181. * of the parent element.
  182. *
  183. * @private
  184. * @param {module:ui/view~View} view A new view added to the collection.
  185. * @param {Number} [index] An index the view holds in the collection. When not specified,
  186. * the view is added at the end.
  187. */
  188. _renderViewIntoCollectionParent( view, index ) {
  189. if ( !view.isRendered ) {
  190. view.render();
  191. }
  192. if ( view.element && this._parentElement ) {
  193. this._parentElement.insertBefore( view.element, this._parentElement.children[ index ] );
  194. }
  195. }
  196. /**
  197. * Removes a child view from the collection. If the {@link #setParent parent element} of the
  198. * collection has been set, the {@link module:ui/view~View#element element} of the view is also removed
  199. * in DOM, reflecting the order of the collection.
  200. *
  201. * See the {@link #add} method.
  202. *
  203. * @method #remove
  204. * @param {module:ui/view~View|Number|String} subject The view to remove, its id or index in the collection.
  205. * @returns {Object} The removed view.
  206. */
  207. }
  208. // Check if all entries of the array are of `String` type.
  209. //
  210. // @private
  211. // @param {Array} arr An array to be checked.
  212. // @returns {Boolean}
  213. function isStringArray( arr ) {
  214. return arr.every( a => typeof a == 'string' );
  215. }