Merge pull request #332 from ckeditor/t/262

Other: Implemented `View#render` method which replaces the `#element` rendering upon the first reference and incorporates the `#init` method functionality. Closes #262. Closes #302.

From now on `View#setTemplate` and `View#extendTemplate` methods are recommended as a shorthand for `view.template = new Template( { ... } )` and `Template.extend( view.template )`.

BREAKING CHANGE: The `init()` method in various UI components has been renamed to `render()`. Please refer to the documentation to learn more.

BREAKING CHANGE: The `View#element` is no longer a getter which renders an element when first referenced. Use the `View#render()` method instead.

BREAKING CHANGE: `Template#children` property became an `Array` (previously `ViewCollection`).

BREAKING CHANGE: `View#addChildren` and `View#removeChildren` methods became `#registerChildren` and `#deregisterChildren`.

BREAKING CHANGE:  The DOM structure of the `StickyPanelView` has changed along with the class names. Please refer to the component documentation to learn more.

Author: oskarwrobel

docs/_snippets/examples/bootstrap-ui-inner.js

@@ -59,8 +59,8 @@ export default class BootstrapEditor extends StandardEditor {
 
 			resolve(
 				editor.initPlugins()
-					// Initialize the editable view in DOM first.
-					.then( () => editable.init() )
+					// Render the editable view in DOM first.
+					.then( () => editable.render() )
 					// Replace the editor#element with editor.editable#element.
 					.then( () => editor._elementReplacer.replace( element, editable.element ) )
 					// Handle the UI of the editor.

docs/framework/guides/external-ui.md

@@ -83,8 +83,8 @@ export default class BootstrapEditor extends StandardEditor {
 
 			resolve(
 				editor.initPlugins()
-					// Initialize the editable view in DOM first.
-					.then( () => editable.init() )
+					// Render the editable view in DOM first.
+					.then( () => editable.render() )
 					// Replace the editor#element with editor.editable#element.
 					.then( () => editor._elementReplacer.replace( element, editable.element ) )
 					// Handle the UI of the editor.

src/bindings/preventdefault.js

@@ -17,7 +17,7 @@
  *
  *		// ...
  *
- *		this.template = new Template( {
+ *		this.setTemplate( {
  *			tag: 'div',
  *
  *			on: {

src/button/buttonview.js

@@ -8,7 +8,6 @@
  */
 
 import View from '../view';
-import Template from '../template';
 import IconView from '../icon/iconview';
 import TooltipView from '../tooltip/tooltipview';
 
@@ -26,7 +25,7 @@ import { getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils/src/keyboard';
  *			withText: true
  *		} );
  *
- *		view.init();
+ *		view.render();
  *
  *		document.body.append( view.element );
  *
@@ -39,6 +38,8 @@ export default class ButtonView extends View {
 	constructor( locale ) {
 		super( locale );
 
+		const bind = this.bindTemplate;
+
 		/**
 		 * The label of the button view visible to the user when {@link #withText} is `true`.
 		 * It can also be used to create a {@link #tooltip}.
@@ -151,6 +152,30 @@ export default class ButtonView extends View {
 		 */
 		this.set( 'tabindex', -1 );
 
+		/**
+		 * Collection of the child views inside of the button {@link #element}.
+		 *
+		 * @readonly
+		 * @member {module:ui/viewcollection~ViewCollection}
+		 */
+		this.children = this.createCollection();
+
+		/**
+		 * Tooltip of the button view. It is configurable using the {@link #tooltip tooltip attribute}.
+		 *
+		 * @readonly
+		 * @member {module:ui/tooltip/tooltipview~TooltipView} #tooltipView
+		 */
+		this.tooltipView = this._createTooltipView();
+
+		/**
+		 * Label of the button view. It is configurable using the {@link #label label attribute}.
+		 *
+		 * @readonly
+		 * @member {module:ui/view~View} #labelView
+		 */
+		this.labelView = this._createLabelView();
+
 		/**
 		 * Tooltip of the button bound to the template.
 		 *
@@ -167,24 +192,14 @@ export default class ButtonView extends View {
 			this._getTooltipString.bind( this )
 		);
 
-		/**
-		 * Tooltip of the button view. It is configurable using the {@link #tooltip tooltip attribute}.
-		 *
-		 * @readonly
-		 * @member {module:ui/tooltip/tooltipview~TooltipView} #tooltipView
-		 */
-		this.tooltipView = this._createTooltipView();
-
 		/**
 		 * (Optional) The icon view of the button. Only present when the {@link #icon icon attribute} is defined.
 		 *
 		 * @readonly
 		 * @member {module:ui/icon/iconview~IconView} #iconView
 		 */
 
-		const bind = this.bindTemplate;
-
-		this.template = new Template( {
+		this.setTemplate( {
 			tag: 'button',
 
 			attributes: {
@@ -199,22 +214,7 @@ export default class ButtonView extends View {
 				tabindex: bind.to( 'tabindex' )
 			},
 
-			children: [
-				{
-					tag: 'span',
-
-					attributes: {
-						class: [ 'ck-button__label' ]
-					},
-
-					children: [
-						{
-							text: bind.to( 'label' )
-						}
-					]
-				},
-				this.tooltipView
-			],
+			children: this.children,
 
 			on: {
 				mousedown: bind.to( evt => {
@@ -246,18 +246,19 @@ export default class ButtonView extends View {
 	/**
 	 * @inheritDoc
 	 */
-	init() {
+	render() {
+		super.render();
+
 		if ( this.icon ) {
 			const iconView = this.iconView = new IconView();
 
 			iconView.bind( 'content' ).to( this, 'icon' );
-			this.element.insertBefore( iconView.element, this.element.firstChild );
 
-			// Make sure the icon will be destroyed along with the button.
-			this.addChildren( iconView );
+			this.children.add( iconView );
 		}
 
-		super.init();
+		this.children.add( this.tooltipView );
+		this.children.add( this.labelView );
 	}
 
 	/**
@@ -283,6 +284,32 @@ export default class ButtonView extends View {
 		return tooltipView;
 	}
 
+	/**
+	 * Creates a label view instance and binds it with button attributes.
+	 *
+	 * @private
+	 * @returns {module:ui/view~View}
+	 */
+	_createLabelView() {
+		const labelView = new View();
+
+		labelView.setTemplate( {
+			tag: 'span',
+
+			attributes: {
+				class: [ 'ck-button__label' ]
+			},
+
+			children: [
+				{
+					text: this.bindTemplate.to( 'label' )
+				}
+			]
+		} );
+
+		return labelView;
+	}
+
 	/**
 	 * Gets the text for the {@link #tooltipView} from the combination of
 	 * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.

src/dropdown/createdropdown.js

@@ -24,7 +24,7 @@ import DropdownPanelView from './dropdownpanelview';
  *
  *		const dropdown = createDropdown( model );
  *
- *		dropdown.init();
+ *		dropdown.render();
  *
  *		// Will render a dropdown labeled "A dropdown" with an empty panel.
  *		document.body.appendChild( dropdown.element );

src/dropdown/dropdownpanelview.js

@@ -8,7 +8,6 @@
  */
 
 import View from '../view';
-import Template from '../template';
 
 /**
  * The dropdown panel view class.
@@ -46,7 +45,7 @@ export default class DropdownPanelView extends View {
 		 */
 		this.children = this.createCollection();
 
-		this.template = new Template( {
+		this.setTemplate( {
 			tag: 'div',
 
 			attributes: {

src/dropdown/dropdownview.js

@@ -8,7 +8,6 @@
  */
 
 import View from '../view';
-import Template from '../template';
 import FocusTracker from '@ckeditor/ckeditor5-utils/src/focustracker';
 import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 
@@ -25,7 +24,7 @@ import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
  *			withText: true
  *		} );
  *
- *		dropdown.init();
+ *		dropdown.render();
  *
  *		// Will render a dropdown with a panel containing a "Content of the panel" text.
  *		document.body.appendChild( dropdown.element );
@@ -46,7 +45,7 @@ export default class DropdownView extends View {
 		// Extend button's template before it's registered as a child of the dropdown because
 		// by doing so, its #element is rendered and any post–render template extension will
 		// not be reflected in DOM.
-		Template.extend( buttonView.template, {
+		buttonView.extendTemplate( {
 			attributes: {
 				class: [
 					'ck-dropdown__button'
@@ -106,7 +105,7 @@ export default class DropdownView extends View {
 		 */
 		this.keystrokes = new KeystrokeHandler();
 
-		this.template = new Template( {
+		this.setTemplate( {
 			tag: 'div',
 
 			attributes: {
@@ -120,20 +119,22 @@ export default class DropdownView extends View {
 				panelView
 			]
 		} );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	render() {
+		super.render();
 
 		// Toggle the the dropdown when it's button has been clicked.
-		this.listenTo( buttonView, 'execute', () => {
+		this.listenTo( this.buttonView, 'execute', () => {
 			this.isOpen = !this.isOpen;
 		} );
 
 		// Toggle the visibility of the panel when the dropdown becomes open.
-		panelView.bind( 'isVisible' ).to( this, 'isOpen' );
-	}
+		this.panelView.bind( 'isVisible' ).to( this, 'isOpen' );
 
-	/**
-	 * @inheritDoc
-	 */
-	init() {
 		// Listen for keystrokes coming from within #element.
 		this.keystrokes.listenTo( this.element );
 
@@ -167,8 +168,6 @@ export default class DropdownView extends View {
 		// Close the dropdown using the arrow left/escape key.
 		this.keystrokes.set( 'arrowleft', closeDropdown );
 		this.keystrokes.set( 'esc', closeDropdown );
-
-		super.init();
 	}
 
 	/**

src/dropdown/list/createlistdropdown.js

@@ -31,10 +31,9 @@ import createDropdown from '../createdropdown';
  *
  *		const dropdown = createListDropdown( model, locale );
  *
- *		dropdown.init();
- *
  *		// Will render a dropdown labeled "A dropdown" with a list in the panel
  *		// containing two items.
+ *		dropdown.render()
  *		document.body.appendChild( dropdown.element );
  *
  * The model instance remains in control of the dropdown after it has been created. E.g. changes to the
@@ -54,7 +53,6 @@ import createDropdown from '../createdropdown';
  */
 export default function createListDropdown( model, locale ) {
 	const dropdownView = createDropdown( model, locale );
-
 	const listView = dropdownView.listView = new ListView( locale );
 
 	listView.items.bindTo( model.items ).using( itemModel => {

src/editableui/editableuiview.js

@@ -8,7 +8,6 @@
  */
 
 import View from '../view';
-import Template from '../template';
 
 /**
  * The editable UI view class.
@@ -32,7 +31,7 @@ export default class EditableUIView extends View {
 			this.element = this.editableElement = editableElement;
 		}
 
-		this.template = new Template( {
+		this.setTemplate( {
 			tag: 'div',
 			attributes: {
 				class: [
@@ -77,17 +76,17 @@ export default class EditableUIView extends View {
 	}
 
 	/**
-	 * Initializes the view by either applying the {@link #template} to the existing
+	 * Renders the view by either applying the {@link #template} to the existing
 	 * {@link #editableElement} or assigning {@link #element} as {@link #editableElement}.
 	 */
-	init() {
+	render() {
+		super.render();
+
 		if ( this.externalElement ) {
-			this.template.apply( this.externalElement );
+			this.template.apply( this.element = this.externalElement );
 		} else {
 			this.editableElement = this.element;
 		}
-
-		super.init();
 	}
 
 	/**

src/editableui/inline/inlineeditableuiview.js

@@ -8,7 +8,6 @@
  */
 
 import EditableUIView from '../../editableui/editableuiview';
-import Template from '../../template';
 
 /**
  * The inline editable UI class implementing an inline {@link module:ui/editableui/editableuiview~EditableUIView}.
@@ -42,7 +41,7 @@ export default class InlineEditableUIView extends EditableUIView {
 			return t( 'Rich Text Editor, %0', [ value ] );
 		};
 
-		Template.extend( this.template, {
+		this.extendTemplate( {
 			attributes: {
 				role: 'textbox',
 				'aria-label': bind.to( 'name', getLabel ),

src/editorui/boxed/boxededitoruiview.js

@@ -9,7 +9,6 @@
 
 import EditorUIView from '../../editorui/editoruiview';
 import uid from '@ckeditor/ckeditor5-utils/src/uid';
-import Template from '../../template';
 
 /**
  * The boxed editor UI view class. This class represents an editor interface
@@ -47,7 +46,7 @@ export default class BoxedEditorUIView extends EditorUIView {
 		 */
 		this.main = this.createCollection();
 
-		this.template = new Template( {
+		this.setTemplate( {
 			tag: 'div',
 
 			attributes: {