8
0
Просмотр исходного кода

Docs: Added docs to the View class.

Aleksander Nowodziński 9 лет назад
Родитель
Сommit
2f7b882428
2 измененных файлов с 141 добавлено и 5 удалено
  1. 82 2
      packages/ckeditor5-ui/src/view.js
  2. 59 3
      packages/ckeditor5-ui/src/viewcollection.js

+ 82 - 2
packages/ckeditor5-ui/src/view.js

@@ -22,7 +22,34 @@ export default class View {
 	/**
 	 * Creates an instance of the {@link ui.View} class.
 	 *
-	 * TODO: A simple example how to create one.
+	 *		class SampleView extends View {
+	 *			constructor( locale ) {
+	 *				super( locale );
+	 *
+	 *				this.template = new Template( {
+	 *					tag: 'p',
+	 *					children: [
+	 *						'Hello',
+	 *						{
+	 *							tag: 'b',
+	 *							children: [
+	 *								'world!'
+	 *							]
+	 *						}
+	 *					],
+	 *					attributes: {
+	 *						class: 'foo'
+	 *					}
+	 *				} );
+	 *			}
+	 *		}
+	 *
+	 *		const view = new SampleView( locale )
+	 *
+	 *		view.init().then( () => {
+	 *			// Will append <p class="foo">Hello<b>world</b></p>
+	 *			document.body.appendChild( view.element );
+	 *		} );
 	 *
 	 * @param {utils.Locale} [locale] The {@link core.editor.Editor#locale editor's locale} instance.
 	 */
@@ -144,7 +171,32 @@ export default class View {
 	 * Creates a new collection of views, which can be used in this view instance
 	 * i.e. as a member of {@link ui.TemplateDefinition#children}.
 	 *
-	 * TODO: An example how to use created collection in a template definition.
+	 *		class SampleView extends View {
+	 *			constructor( locale ) {
+	 *				super( locale );
+	 *
+	 *				this.items = this.createCollection();
+ 	 *
+	 *				this.template = new Template( {
+	 *					tag: 'p',
+	 *
+	 *					// `items` collection will render here.
+	 *					children: this.items
+	 *				} );
+	 *			}
+	 *		}
+	 *
+	 *		const view = new SampleView( locale )
+	 *		const anotherView = new AnotherSampleView( locale )
+	 *
+	 *		view.init().then( () => {
+	 *			// Will append <p></p>
+	 *			document.body.appendChild( view.element );
+	 *
+	 *			// `anotherView` becomes a child of the view, which is reflected in DOM
+	 *			// <p><anotherView#element></p>
+	 *			view.items.add( anotherView );
+	 *		} );
 	 *
 	 * @returns {ui.ViewCollection} A new collection of view instances.
 	 */
@@ -161,6 +213,34 @@ export default class View {
 	 * view is managed by its parent, including initialization ({@link ui.view#init})
 	 * and destruction ({@link ui.view#destroy}).
 	 *
+	 *		class SampleView extends View {
+	 *			constructor( locale ) {
+	 *				super( locale );
+	 *
+	 *				this.childView = new SomeChildView( locale );
+	 *
+	 *				// Register a new child view.
+	 *				this.addChild( this.childView );
+	 *
+	 *				this.template = new Template( {
+	 *					tag: 'p',
+	 *
+	 *					children: [
+	 *						{ tag: 'b' },
+	 *						// This is where the `childView` will render.
+	 *						this.childView
+	 *					]
+	 *				} );
+	 *			}
+	 *		}
+	 *
+	 *		const view = new SampleView( locale )
+	 *
+	 *		view.init().then( () => {
+	 *			// Will append <p><b></b><childView#element></p>
+	 *			document.body.appendChild( view.element );
+	 *		} );
+	 *
 	 * @param {...ui.View} children Children views to be registered.
 	 */
 	addChild( ...children ) {

+ 59 - 3
packages/ckeditor5-ui/src/viewcollection.js

@@ -153,10 +153,66 @@ export default class ViewCollection extends Collection {
 	}
 
 	/**
-	 * Binds a view collection to {@link utils.Collection} of items to create
-	 * a factory of view instances.
+	 * Binds a view collection to {@link utils.Collection} of items to create a factory of
+	 * view instances.
 	 *
-	 * TODO: Example and longer explanation. Probably imported from ControllerCollection#bind.
+	 * The process can be automatic:
+	 *
+	 *		// This collection stores items.
+	 *		const items = new Collection( { idProperty: 'label' } );
+	 *
+	 *		// This view collection will become a factory out of the collection of items.
+	 *		const views = new ViewCollection( locale );
+	 *
+	 *		// Activate the binding – since now, this view collection works like a **factory**.
+	 *		// Each new item is passed to the FooView constructor like new FooView( locale, item ).
+	 *		views.bindTo( items ).as( FooView );
+	 *
+	 *		// As new items arrive to the collection, each becomes an instance of FooView
+	 *		// in the view collection.
+	 *		items.add( new Model( { label: 'foo' } ) );
+	 *		items.add( new Model( { label: 'bar' } ) );
+	 *
+	 *		console.log( views.length == 2 );
+	 *
+	 *		// View collection is updated as the model is removed.
+	 *		items.remove( 0 );
+	 *		console.log( views.length == 1 );
+	 *
+	 * or the factory can be driven by a custom callback:
+	 *
+	 *		// This collection stores any kind of data.
+	 *		const data = new Collection();
+	 *
+	 *		// This view collection will become a custom factory for the data.
+	 *		const views = new ViewCollection( locale );
+	 *
+	 *		// Activate the binding – the **factory** is driven by a custom callback.
+	 *		views.bind( data ).as( item => {
+	 *			if ( !item.foo ) {
+	 *				return null;
+	 *			} else if ( item.foo == 'bar' ) {
+	 *				return new BarView();
+	 *			} else {
+	 *				return new DifferentView();
+	 *			}
+	 *		} );
+	 *
+	 *		// As new data arrive to the collection, each is handled individually by the callback.
+	 *		// This will produce BarView.
+	 *		data.add( { foo: 'bar' } );
+	 *
+	 *		// And this one will become DifferentView.
+	 *		data.add( { foo: 'baz' } );
+	 *
+	 *		// Also there will be no view for data lacking the `foo` property.
+	 *		data.add( {} );
+	 *
+	 *		console.log( controllers.length == 2 );
+	 *
+	 *		// View collection is also updated as the data is removed.
+	 *		data.remove( 0 );
+	 *		console.log( controllers.length == 1 );
 	 *
 	 * @param {utils.Collection} collection A collection to be bound.
 	 * @returns {ui.ViewCollection.bindTo#as}