Merge pull request #1313 from ckeditor/t/1312

Other: Fix `render()` and `change()` flow. Introduce postfixers in view. Closes #1312.

Author: Piotr Jasiun

src/conversion/downcastdispatcher.js

@@ -476,7 +476,6 @@ export default class DowncastDispatcher {
 	 * @param {Object} data Additional information about the change.
 	 * @param {module:engine/model/item~Item} data.item Inserted item.
 	 * @param {module:engine/model/range~Range} data.range Range spanning over inserted item.
-	 * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
 	 * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor.
 	 */
 

src/view/document.js

@@ -65,6 +65,14 @@ export default class Document {
 		 * @member {Boolean} module:engine/view/document~Document#isFocused
 		 */
 		this.set( 'isFocused', false );
+
+		/**
+		 * Post-fixer callbacks registered to the view document.
+		 *
+		 * @private
+		 * @member {Set}
+		 */
+		this._postFixers = new Set();
 	}
 
 	/**
@@ -78,6 +86,44 @@ export default class Document {
 	getRoot( name = 'main' ) {
 		return this.roots.get( name );
 	}
+
+	/**
+	 * Used to register a post-fixer callback. A post-fixers mechanism allows to update view tree just before rendering
+	 * to the DOM.
+	 *
+	 * Post-fixers are fired just after all changes from the outermost change block were applied but
+	 * before the {@link module:engine/view/view~View#event:render render event} is fired. If a post-fixer callback made
+	 * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+	 * not be fixed in the new document tree state.
+	 *
+	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/writer~Writer writer} instance connected with the
+	 * executed changes block.
+	 *
+	 * @param {Function} postFixer
+	 */
+	registerPostFixer( postFixer ) {
+		this._postFixers.add( postFixer );
+	}
+
+	/**
+	 * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+	 *
+	 * @protected
+	 * @param {module:engine/view/writer~Writer} writer
+	 */
+	_callPostFixers( writer ) {
+		let wasFixed = false;
+
+		do {
+			for ( const callback of this._postFixers ) {
+				wasFixed = callback( writer );
+
+				if ( wasFixed ) {
+					break;
+				}
+			}
+		} while ( wasFixed );
+	}
 }
 
 mix( Document, ObservableMixin );

src/view/placeholder.js

@@ -7,20 +7,16 @@
  * @module engine/view/placeholder
  */
 
-import extend from '@ckeditor/ckeditor5-utils/src/lib/lodash/extend';
-import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 import '../../theme/placeholder.css';
 
-const listener = {};
-extend( listener, EmitterMixin );
-
 // Each document stores information about its placeholder elements and check functions.
 const documentPlaceholders = new WeakMap();
 
 /**
  * Attaches placeholder to provided element and updates it's visibility. To change placeholder simply call this method
  * once again with new parameters.
  *
+ * @param {module:engine/view/view~View} view View controller.
  * @param {module:engine/view/element~Element} element Element to attach placeholder to.
  * @param {String} placeholderText Placeholder text to use.
  * @param {Function} [checkFunction] If provided it will be called before checking if placeholder should be displayed.
@@ -29,28 +25,19 @@ const documentPlaceholders = new WeakMap();
 export function attachPlaceholder( view, element, placeholderText, checkFunction ) {
 	const document = view.document;
 
-	// Detach placeholder if was used before.
-	detachPlaceholder( view, element );
-
 	// Single listener per document.
 	if ( !documentPlaceholders.has( document ) ) {
 		documentPlaceholders.set( document, new Map() );
 
-		// Attach listener just before rendering and update placeholders.
-		listener.listenTo( view, 'render', () => updateAllPlaceholders( view ) );
+		// Create view post fixer that will add placeholder where needed.
+		document.registerPostFixer( writer => updateAllPlaceholders( document, writer ) );
 	}
 
-	// Store text in element's data attribute.
-	// This data attribute is used in CSS class to show the placeholder.
-	view.change( writer => {
-		writer.setAttribute( 'data-placeholder', placeholderText, element );
-	} );
-
-	// Store information about placeholder.
-	documentPlaceholders.get( document ).set( element, checkFunction );
+	// Store information about element with placeholder.
+	documentPlaceholders.get( document ).set( element, { placeholderText, checkFunction } );
 
-	// Update right away too.
-	updateSinglePlaceholder( view, element, checkFunction );
+	// Update view right away.
+	view.render();
 }
 
 /**
@@ -75,39 +62,55 @@ export function detachPlaceholder( view, element ) {
 // Updates all placeholders of given document.
 //
 // @private
-// @param {module:engine/view/view~View} view
-function updateAllPlaceholders( view ) {
-	const placeholders = documentPlaceholders.get( view.document );
-
-	for ( const [ element, checkFunction ] of placeholders ) {
-		updateSinglePlaceholder( view, element, checkFunction );
+// @param {module:engine/view/document~Document} view
+// @param {module:engine/view/writer~Writer} writer
+function updateAllPlaceholders( document, writer ) {
+	const placeholders = documentPlaceholders.get( document );
+	let changed = false;
+
+	for ( const [ element, info ] of placeholders ) {
+		if ( updateSinglePlaceholder( writer, element, info ) ) {
+			changed = true;
+		}
 	}
+
+	return changed;
 }
 
 // Updates placeholder class of given element.
 //
 // @private
-// @param {module:engine/view/view~View} view
+// @param {module:engine/view/writer~Writer} writer
 // @param {module:engine/view/element~Element} element
-// @param {Function} checkFunction
-function updateSinglePlaceholder( view, element, checkFunction ) {
+// @param {Object} info
+function updateSinglePlaceholder( writer, element, info ) {
 	const document = element.document;
+	const text = info.placeholderText;
+	let changed = false;
 
 	// Element was removed from document.
 	if ( !document ) {
-		return;
+		return false;
+	}
+
+	// Update data attribute if needed.
+	if ( element.getAttribute( 'data-placeholder' ) !== text ) {
+		writer.setAttribute( 'data-placeholder', text, element );
+		changed = true;
 	}
 
 	const viewSelection = document.selection;
 	const anchor = viewSelection.anchor;
+	const checkFunction = info.checkFunction;
 
 	// If checkFunction is provided and returns false - remove placeholder.
 	if ( checkFunction && !checkFunction() ) {
-		view.change( writer => {
+		if ( element.hasClass( 'ck-placeholder' ) ) {
 			writer.removeClass( 'ck-placeholder', element );
-		} );
+			changed = true;
+		}
 
-		return;
+		return changed;
 	}
 
 	// Element is empty for placeholder purposes when it has no children or only ui elements.
@@ -116,21 +119,26 @@ function updateSinglePlaceholder( view, element, checkFunction ) {
 
 	// If element is empty and editor is blurred.
 	if ( !document.isFocused && isEmptyish ) {
-		view.change( writer => {
+		if ( !element.hasClass( 'ck-placeholder' ) ) {
 			writer.addClass( 'ck-placeholder', element );
-		} );
+			changed = true;
+		}
 
-		return;
+		return changed;
 	}
 
 	// It there are no child elements and selection is not placed inside element.
 	if ( isEmptyish && anchor && anchor.parent !== element ) {
-		view.change( writer => {
+		if ( !element.hasClass( 'ck-placeholder' ) ) {
 			writer.addClass( 'ck-placeholder', element );
-		} );
+			changed = true;
+		}
 	} else {
-		view.change( writer => {
+		if ( element.hasClass( 'ck-placeholder' ) ) {
 			writer.removeClass( 'ck-placeholder', element );
-		} );
+			changed = true;
+		}
 	}
+
+	return changed;
 }

src/view/view.js

@@ -109,15 +109,20 @@ export default class View {
 		this._ongoingChange = false;
 
 		/**
-		 * Is set to `true` when rendering view to DOM was started.
-		 * This is used to check whether view document can accept changes in current state.
-		 * From the moment when rendering to DOM is stared view tree is locked to prevent changes that will not be
-		 * reflected in the DOM.
+		 * Used to prevent calling {@link #render} and {@link #change) during rendering view to the DOM.
 		 *
 		 * @private
-		 * @member {Boolean} module:engine/view/view~View#_renderingStarted
+		 * @member {Boolean} module:engine/view/view~View#_renderingInProgress
 		 */
-		this._renderingStarted = false;
+		this._renderingInProgress = false;
+
+		/**
+		 * Used to prevent calling {@link #render} and {@link #change) during rendering view to the DOM.
+		 *
+		 * @private
+		 * @member {Boolean} module:engine/view/view~View#_renderingInProgress
+		 */
+		this._postFixersInProgress = false;
 
 		/**
 		 * Writer instance used in {@link #change change method) callbacks.
@@ -138,10 +143,10 @@ export default class View {
 		injectQuirksHandling( this );
 		injectUiElementHandling( this );
 
-		// Use 'low` priority so that all listeners on 'normal` priority will be executed before.
+		// Use 'normal' priority so that rendering is performed as first when using that priority.
 		this.on( 'render', () => {
 			this._render();
-		}, { priority: 'low' } );
+		} );
 	}
 
 	/**
@@ -312,21 +317,41 @@ export default class View {
 	 * @param {Function} callback Callback function which may modify the view.
 	 */
 	change( callback ) {
-		// Check if change is performed in correct moment.
-		this._assertRenderingInProgress();
+		if ( this._renderingInProgress || this._postFixersInProgress ) {
+			/**
+			 * Thrown when there is an attempt to make changes to the view tree when it is in incorrect state. This may
+			 * cause some unexpected behaviour and inconsistency between the DOM and the view.
+			 * This may be caused by:
+			 *   * calling {@link #change} or {@link #render} during rendering process,
+			 *   * calling {@link #change} or {@link #render} inside of
+			 *   {@link module:engine/view/document~Document#registerPostFixer post fixer function}.
+			 */
+			throw new CKEditorError(
+				'cannot-change-view-tree: ' +
+				'Attempting to make changes to the view when it is in incorrect state: rendering or post fixers are in progress. ' +
+				'This may cause some unexpected behaviour and inconsistency between the DOM and the view.'
+			);
+		}
 
-		// If other changes are in progress wait with rendering until every ongoing change is over.
+		// Recursive call to view.change() method - execute listener immediately.
 		if ( this._ongoingChange ) {
 			callback( this._writer );
-		} else {
-			this._ongoingChange = true;
-
-			callback( this._writer );
-			this.fire( 'render' );
 
-			this._ongoingChange = false;
-			this._renderingStarted = false;
+			return;
 		}
+
+		// This lock will assure that all recursive calls to view.change() will end up in same block - one "render"
+		// event for all nested calls.
+		this._ongoingChange = true;
+		callback( this._writer );
+		this._ongoingChange = false;
+
+		// Execute all document post fixers after the change.
+		this._postFixersInProgress = true;
+		this.document._callPostFixers( this._writer );
+		this._postFixersInProgress = false;
+
+		this.fire( 'render' );
 	}
 
 	/**
@@ -337,15 +362,7 @@ export default class View {
 	 * trying to re-render when rendering to DOM has already started.
 	 */
 	render() {
-		// Check if rendering is performed in correct moment.
-		this._assertRenderingInProgress();
-
-		// Render only if no ongoing changes are in progress. If there are some, view document will be rendered after all
-		// changes are done. This way view document will not be rendered in the middle of some changes.
-		if ( !this._ongoingChange ) {
-			this.fire( 'render' );
-			this._renderingStarted = false;
-		}
+		this.change( () => {} );
 	}
 
 	/**
@@ -366,47 +383,22 @@ export default class View {
 	 * @private
 	 */
 	_render() {
-		this._renderingStarted = true;
-
+		this._renderingInProgress = true;
 		this.disableObservers();
 		this._renderer.render();
 		this.enableObservers();
+		this._renderingInProgress = false;
 	}
 
 	/**
-	 * Throws `applying-view-changes-on-rendering` error when trying to modify or re-render view tree when rendering is
-	 * already started
+	 * Fired after a topmost {@link module:engine/view/view~View#change change block} and all
+	 * {@link module:engine/view/document~Document#registerPostFixer post fixers} are executed.
 	 *
-	 * @private
-	 */
-	_assertRenderingInProgress() {
-		if ( this._renderingStarted ) {
-			/**
-			 * There is an attempt to make changes in the view tree after the rendering process
-			 * has started. This may cause unexpected behaviour and inconsistency between the DOM and the view.
-			 * This may be caused by:
-			 *   * calling `view.change()` or `view.render()` methods during rendering process,
-			 *   * calling `view.change()` or `view.render()` methods in callbacks to
-			 *   {module:engine/view/document~Document#event:change view document change event) on `low` priority, after
-			 *   rendering is over for current `change` block.
-			 *
-			 * @error applying-view-changes-on-rendering
-			 */
-			throw new CKEditorError(
-				'applying-view-changes-on-rendering: ' +
-				'Attempting to make changes in the view during rendering process. ' +
-				'This may cause some unexpected behaviour and inconsistency between the DOM and the view.'
-			);
-		}
-	}
-
-	/**
-	 * Fired after a topmost {@link module:engine/view/view~View#change change block} is finished and the DOM rendering has
-	 * been executed.
+	 * Actual rendering is performed as a first listener on 'normal' priority.
 	 *
-	 * Actual rendering is performed on 'low' priority. This means that all listeners on 'normal' and above priorities
-	 * will be executed after changes made to view tree but before rendering to the DOM. Use `low` priority for callbacks that
-	 * should be executed after rendering to the DOM.
+	 *		view.on( 'render', () => {
+	 *			// Rendering to the DOM is complete.
+	 *		} );
 	 *
 	 * @event module:engine/view/view~View#event:render
 	 */