浏览代码

Updated docs in view controller and document.

Szymon Kupś 7 年之前
父节点
当前提交
a9aa752798
共有 2 个文件被更改,包括 26 次插入35 次删除
  1. 6 28
      packages/ckeditor5-engine/src/view/document.js
  2. 20 7
      packages/ckeditor5-engine/src/view/view.js

+ 6 - 28
packages/ckeditor5-engine/src/view/document.js

@@ -88,38 +88,16 @@ export default class Document {
 	}
 
 	/**
-	 * TODO: update docs
-	 * Used to register a post-fixer callback. A post-fixer mechanism guarantees that the features that listen to
-	 * the {@link module:engine/model/model~Model#event:_change model's change event} will operate on a correct model state.
+	 * Used to register a post-fixer callback. A post-fixer mechanism that allows to update view tree just before rendering
+	 * to the DOM is started.
 	 *
-	 * An execution of a feature may lead to an incorrect document tree state. The callbacks are used to fix the document tree after
-	 * it has changed. Post-fixers are fired just after all changes from the outermost change block were applied but
-	 * before the {@link module:engine/model/document~Document#event:change change event} is fired. If a post-fixer callback made
+	 * 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/model/writer~Writer writer} instance connected with the
-	 * executed changes block. Thanks to that, all changes done by the callback will be added to the same
-	 * {@link module:engine/model/batch~Batch batch} (and undo step) as the original changes. This makes post-fixer changes transparent
-	 * for the user.
-	 *
-	 * An example of a post-fixer is a callback that checks if all the data were removed from the editor. If so, the
-	 * callback should add an empty paragraph so that the editor is never empty:
-	 *
-	 *		document.registerPostFixer( writer => {
-	 *			const changes = document.differ.getChanges();
-	 *
-	 *			// Check if the changes lead to an empty root in the editor.
-	 *			for ( const entry of changes ) {
-	 *				if ( entry.type == 'remove' && entry.position.root.isEmpty ) {
-	 *					writer.insertElement( 'paragraph', entry.position.root, 0 );
-	 *
-	 *					// It is fine to return early, even if multiple roots would need to be fixed.
-	 *					// All post-fixers will be fired again, so if there are more empty roots, those will be fixed, too.
-	 *					return true;
-	 *				}
-	 *			}
-	 *		} );
+	 * 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
 	 */

+ 20 - 7
packages/ckeditor5-engine/src/view/view.js

@@ -319,7 +319,19 @@ export default class View {
 	change( callback ) {
 		if ( this._renderingInProgress || this._postFixersInProgress ) {
 			// TODO: better description
-			throw new CKEditorError( 'incorrect-view-change' );
+			/**
+			 * 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.'
+			);
 		}
 
 		// Recursive call to view.change() method - execute listener immediately.
@@ -380,13 +392,14 @@ export default class View {
 	}
 
 	/**
-	 * TODO: fix description
-	 * Fired after a topmost {@link module:engine/view/view~View#change change block} is finished and the DOM rendering has
-	 * been executed.
+	 * 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.
 	 *
-	 * 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.
+	 * Actual rendering is performed as a first listener on 'normal' priority.
+	 *
+	 *		view.on( 'render', () => {
+	 *			// Rendering to the DOM is complete.
+	 *		} );
 	 *
 	 * @event module:engine/view/view~View#event:render
 	 */