Jelajahi Sumber

Docs: Reviewed and improved documentation of the ViewCollection class.

Aleksander Nowodzinski 8 tahun lalu
induk
melakukan
db94e9026c
1 mengubah file dengan 88 tambahan dan 15 penghapusan
  1. 88 15
      packages/ckeditor5-ui/src/viewcollection.js

+ 88 - 15
packages/ckeditor5-ui/src/viewcollection.js

@@ -15,12 +15,46 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 /**
 /**
  * Collects {@link module:ui/view~View} instances.
  * Collects {@link module:ui/view~View} instances.
  *
  *
+ *		const parentView = new ParentView( locale );
+ *		const collection = new ViewCollection( locale );
+ *
+ *		collection.setParent( parentView.element );
+ *
+ *		const viewA = new ChildView( locale );
+ *		const viewB = new ChildView( locale );
+ *
+ * View collection manages view {@link module:ui/view~View#element elements}:
+ *
+ *		// parentView.element.children == [ viewA.element, vievB.element ]
+ *		collection.add( viewA );
+ *		collection.add( viewB );
+ *
+ * It handles initialization of the children:
+ *
+ *		// viewA.ready == viewB.ready == true;
+ *		collection.init();
+ *
+ * It {@link module:ui/viewcollection~ViewCollection#delegate propagates} DOM events too:
+ *
+ *		// Delegate #click and #keydown events from viewA and viewB to the parentView.
+ *		collection.delegate( 'click' ).to( parentView );
+ *
+ *		parentView.on( 'click', ( evt ) => {
+ *			console.log( `${ evt.source } has been clicked.` );
+ *		} );
+ *
+ *		// This event will be delegated to the parentView.
+ *		viewB.fire( 'click' );
+ *
+ * **Note**: A view collection can be used directly in the {@link module:ui/template~TemplateDefinition definition}
+ * of a {@link module:ui/template~Template template}.
+ *
  * @extends module:utils/collection~Collection
  * @extends module:utils/collection~Collection
  * @mixes module:utils/observablemixin~ObservableMixin
  * @mixes module:utils/observablemixin~ObservableMixin
  */
  */
 export default class ViewCollection extends Collection {
 export default class ViewCollection extends Collection {
 	/**
 	/**
-	 * Creates a new {@link module:ui/viewcollection~ViewCollection} instance.
+	 * Creates a new instance of the {@link module:ui/viewcollection~ViewCollection}.
 	 *
 	 *
 	 * @param {module:utils/locale~Locale} [locale] The {@link module:core/editor~Editor editor's locale} instance.
 	 * @param {module:utils/locale~Locale} [locale] The {@link module:core/editor~Editor editor's locale} instance.
 	 */
 	 */
@@ -46,15 +80,16 @@ export default class ViewCollection extends Collection {
 		} );
 		} );
 
 
 		/**
 		/**
-		 * The {@link module:core/editor/editor~Editor editor's locale} instance.
+		 * The {@link module:core/editor/editor~Editor#locale editor's locale} instance.
+		 * See the view {@link module:ui/view~View#locale locale} property.
 		 *
 		 *
 		 * @member {module:utils/locale~Locale}
 		 * @member {module:utils/locale~Locale}
 		 */
 		 */
 		this.locale = locale;
 		this.locale = locale;
 
 
 		/**
 		/**
-		 * Set to `true` once the parent's {@link module:ui/view~View#ready} is true, which means
-		 * that all the views in the collection are also ready (which can be asynchronous).
+		 * Set `true` when all views in the collection are {@link module:ui/view~View#ready}.
+		 * See the view {@link module:ui/view~View#init init} method.
 		 *
 		 *
 		 * @readonly
 		 * @readonly
 		 * @observable
 		 * @observable
@@ -72,8 +107,10 @@ export default class ViewCollection extends Collection {
 	}
 	}
 
 
 	/**
 	/**
-	 * Initializes child views by injecting {@link module:ui/view~View#element} into DOM
-	 * and calling {@link module:ui/view~View#init}.
+	 * Initializes all child views in the collection by calling view {@link module:ui/view~View#init}
+	 * method.
+	 *
+	 * Once finished, sets {@link #ready} `true`.
 	 */
 	 */
 	init() {
 	init() {
 		if ( this.ready ) {
 		if ( this.ready ) {
@@ -92,14 +129,33 @@ export default class ViewCollection extends Collection {
 
 
 	/**
 	/**
 	 * Destroys the view collection along with child views.
 	 * Destroys the view collection along with child views.
+	 * See the view {@link module:ui/view~View#destroy} method.
 	 */
 	 */
 	destroy() {
 	destroy() {
 		this.map( v => v.destroy() );
 		this.map( v => v.destroy() );
 	}
 	}
 
 
 	/**
 	/**
-	 * Adds a child view to the collection. If {@link module:ui/viewcollection~ViewCollection#ready}, the child view
-	 * is also initialized when added.
+	 * Adds a new child view to the collection. If the collection is
+	 * {@link module:ui/viewcollection~ViewCollection#ready}, the child view is also
+	 * {@link module:ui/view~View#init initialized} when added.
+	 *
+	 * Additionally, if the {@link #setParent parent element} of the collection has been set, the
+	 * {@link module:ui/view~View#element element} of the view is also added in DOM,
+	 * reflecting the order of the collection.
+	 *
+	 *		const collection = new ViewCollection();
+	 *		const parentElement = document.querySelector( '#container' );
+	 *		collection.setParent( parentElement );
+	 *
+	 *		const viewA = new View();
+	 *		const viewB = new View();
+	 *
+	 *		// parentElement.children == [ viewA.element, vievB.element ]
+	 *		collection.add( viewA );
+	 *		collection.add( viewB );
+	 *
+	 * See the {@link #remove} method.
 	 *
 	 *
 	 * @param {module:ui/view~View} view A child view.
 	 * @param {module:ui/view~View} view A child view.
 	 * @param {Number} [index] Index at which the child will be added to the collection.
 	 * @param {Number} [index] Index at which the child will be added to the collection.
@@ -113,18 +169,21 @@ export default class ViewCollection extends Collection {
 	}
 	}
 
 
 	/**
 	/**
-	 * Sets {@link #_parentElement} of this collection.
+	 * Sets the parent HTML element of this collection. When parent is set, {@link #add adding} and
+	 * {@link #remove removing} views in the collection synchronizes their
+	 * {@link module:ui/view~View#element elements} in the parent element.
 	 *
 	 *
-	 * @param {HTMLElement} element A new parent.
+	 * @param {HTMLElement} element A new parent element.
 	 */
 	 */
 	setParent( elementOrDocFragment ) {
 	setParent( elementOrDocFragment ) {
 		this._parentElement = elementOrDocFragment;
 		this._parentElement = elementOrDocFragment;
 	}
 	}
 
 
 	/**
 	/**
-	 * Delegates selected events coming from within the collection to desired {@link module:utils/emittermixin~EmitterMixin}.
+	 * Delegates selected events coming from within views in the collection to any
+	 * {@link module:utils/emittermixin~Emitter}.
 	 *
 	 *
-	 * For instance:
+	 * For the following views and collection:
 	 *
 	 *
 	 *		const viewA = new View();
 	 *		const viewA = new View();
 	 *		const viewB = new View();
 	 *		const viewB = new View();
@@ -137,7 +196,7 @@ export default class ViewCollection extends Collection {
 	 *
 	 *
 	 *		views.add( viewA );
 	 *		views.add( viewA );
 	 *
 	 *
-	 * then `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:
+	 * the `eventX` is delegated (fired by) `viewB` and `viewC` along with `customData`:
 	 *
 	 *
 	 *		viewA.fire( 'eventX', customData );
 	 *		viewA.fire( 'eventX', customData );
 	 *
 	 *
@@ -148,8 +207,10 @@ export default class ViewCollection extends Collection {
 	 * See {@link module:utils/emittermixin~EmitterMixin#delegate}.
 	 * See {@link module:utils/emittermixin~EmitterMixin#delegate}.
 	 *
 	 *
 	 * @param {...String} events {@link module:ui/view~View} event names to be delegated to another
 	 * @param {...String} events {@link module:ui/view~View} event names to be delegated to another
-	 * {@link module:utils/emittermixin~EmitterMixin}.
-	 * @returns {module:ui/viewcollection~ViewCollection#delegate.to}
+	 * {@link module:utils/emittermixin~Emitter}.
+	 * @returns {Object}
+	 * @returns {Function} return.to A function which accepts the destination of
+	 * {@link module:utils/emittermixin~EmitterMixin#delegate delegated} events.
 	 */
 	 */
 	delegate( ...events ) {
 	delegate( ...events ) {
 		if ( !events.length || !isStringArray( events ) ) {
 		if ( !events.length || !isStringArray( events ) ) {
@@ -194,6 +255,18 @@ export default class ViewCollection extends Collection {
 			}
 			}
 		};
 		};
 	}
 	}
+
+	/**
+	 * Removes a child view from the collection. If the {@link #setParent parent element} of the
+	 * collection has been set, the {@link module:ui/view~View#element element} of the view is also removed
+	 * in DOM, reflecting the order of the collection.
+	 *
+	 * See the {@link #add} method.
+	 *
+	 * @method #remove
+	 * @param {module:ui/view~View|Number|String} subject The view to remove, its id or index in the collection.
+	 * @returns {Object} The removed view.
+	 */
 }
 }
 
 
 mix( Collection, ObservableMixin );
 mix( Collection, ObservableMixin );