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.

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: {