8
0
Quellcode durchsuchen

Merge pull request #1731 from ckeditor/t/1726

Docs: Update `view.Document#registerPostFixer()` docs. Closes #1726.
Piotrek Koszuliński vor 6 Jahren
Ursprung
Commit
6137aa6855
1 geänderte Dateien mit 35 neuen und 9 gelöschten Zeilen
  1. 35 9
      packages/ckeditor5-engine/src/view/document.js

+ 35 - 9
packages/ckeditor5-engine/src/view/document.js

@@ -100,23 +100,49 @@ export default class Document {
 	}
 
 	/**
-	 * Used to register a post-fixer callback. A post-fixers mechanism allows to update view tree just before rendering
+	 * Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
 	 * to the DOM.
 	 *
-	 * Post-fixers are fired just after all changes from the outermost change block were applied but
+	 * Post-fixers are executed right 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.
 	 *
-	 * View post-fixers are useful when you wants to update view structure whenever it changes, for instance add some classes
-	 * to elements based on the view structure or selection. However, is you need DOM elements to be already updated, use
-	 * {@link module:engine/view/view~View#event:render render event}.
+	 * View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
+	 * changes executed in a view post-fixer should not break model-view mapping.
 	 *
-	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}
-	 * instance connected with the executed changes block.
+	 * The types of changes which should be safe:
 	 *
-	 * Note that registering a post-fixer won't re-render the editor's view. If the view should change after registering the post-fixer then
-	 * it should be done manually calling `view.forceRender();`.
+	 * * adding or removing attribute from elements,
+	 * * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
+	 * * {@link module:engine/model/differ~Differ#refreshItem marking some of the model elements to be re-converted}.
+	 *
+	 * Try to avoid changes which touch view structure:
+	 *
+	 * * you should not add or remove nor wrap or unwrap any view elements,
+	 * * you should not change the editor data model in a view post-fixer.
+	 *
+	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
+	 *
+	 * Typically, a post-fixer will look like this:
+	 *
+	 *		editor.editing.view.document.registerPostFixer( writer => {
+	 *			if ( checkSomeCondition() ) {
+	 *				writer.doSomething();
+	 *
+	 *				// Let other post-fixers know that something changed.
+	 *				return true;
+	 *			}
+	 *		} );
+	 *
+	 * Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
+	 * That is because adding a post-fixer does not execute it.
+	 * The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
+	 * If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
+	 * {@link module:engine/view/view~View#forceRender `view.forceRender()`}.
+	 *
+	 * If you need to register a callback which is executed when DOM elements are already updated,
+	 * use {@link module:engine/view/view~View#event:render render event}.
 	 *
 	 * @param {Function} postFixer
 	 */