Browse Source

Docs: DOMConverter documentation.

Piotr Jasiun 9 years ago
parent
commit
8872412b39

+ 2 - 2
packages/ckeditor5-engine/src/treeview/attributeelement.js

@@ -46,7 +46,7 @@ export default class AttributeElement extends Element {
 	 *
 	 *
 	 * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
 	 * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
 	 * element will be cloned without any children.
 	 * element will be cloned without any children.
-	 * @returns {Element} Clone of this element.
+	 * @returns {engine.treeView.AttributeElement} Clone of this element.
 	 */
 	 */
 	clone( deep ) {
 	clone( deep ) {
 		const cloned = super.clone( deep );
 		const cloned = super.clone( deep );
@@ -62,7 +62,7 @@ export default class AttributeElement extends Element {
 	 * Both elements should have the same name, attributes and priority to be considered as similar.
 	 * Both elements should have the same name, attributes and priority to be considered as similar.
 	 * Two similar elements can contain different set of children nodes.
 	 * Two similar elements can contain different set of children nodes.
 	 *
 	 *
-	 * @param {Element} otherElement
+	 * @param {engine.treeView.Element} otherElement
 	 * @returns {Boolean}
 	 * @returns {Boolean}
 	 */
 	 */
 	isSimilar( otherElement ) {
 	isSimilar( otherElement ) {

+ 81 - 10
packages/ckeditor5-engine/src/treeview/domconverter.js

@@ -60,8 +60,8 @@ export default class DomConverter {
 		this._viewToDomMapping = new WeakMap();
 		this._viewToDomMapping = new WeakMap();
 
 
 		/**
 		/**
-		 * Block filler creator, which is used to create all block fillers during the view to DOM conversion and
-		 * to recognize block fillers during the DOM to view conversion.
+		 * Block {@link engile.treeView.filler filler} creator, which is used to create all block fillers during the
+		 * view to DOM conversion and to recognize block fillers during the DOM to view conversion.
 		 *
 		 *
 		 * @member {Function} engine.treeView.DomConverter#blockFiller
 		 * @member {Function} engine.treeView.DomConverter#blockFiller
 		 */
 		 */
@@ -146,6 +146,15 @@ export default class DomConverter {
 		}
 		}
 	}
 	}
 
 
+	/**
+	 * Converts children of the view element to DOM using {@link engine.treeView.DomConverter#viewToDom} method.
+	 * Additionally this method adds block {@link engile.treeView.filler filler} to the list of children, if needed.
+	 *
+	 * @param {engine.treeView.Element|engine.treeView.DocumentFragment} viewElement Parent view element.
+	 * @param {document} domDocument Document which will be used to create DOM nodes.
+	 * @param {Object} options See {@link engine.treeView.DomConverter#viewToDom} options parameter.
+	 * @returns {Iterable.<Node>} DOM nodes.
+	 */
 	*viewChildrenToDom( viewElement, domDocument, options = {} ) {
 	*viewChildrenToDom( viewElement, domDocument, options = {} ) {
 		let fillerPositionOffset = viewElement.getFillerOffset && viewElement.getFillerOffset();
 		let fillerPositionOffset = viewElement.getFillerOffset && viewElement.getFillerOffset();
 		let offset = 0;
 		let offset = 0;
@@ -165,6 +174,13 @@ export default class DomConverter {
 		}
 		}
 	}
 	}
 
 
+	/**
+	 * Converts view {@link engine.treeView.Range} to DOM range.
+	 * Inline and block {@link engile.treeView.filler fillers} are handled during the conversion.
+	 *
+	 * @param {engine.treeView.Range} viewRange View range.
+	 * @returns {Range} DOM range.
+	 */
 	viewRangeToDom( viewRange ) {
 	viewRangeToDom( viewRange ) {
 		const domStart = this.viewPositionToDom( viewRange.start );
 		const domStart = this.viewPositionToDom( viewRange.start );
 		const domEnd = this.viewPositionToDom( viewRange.end );
 		const domEnd = this.viewPositionToDom( viewRange.end );
@@ -176,6 +192,17 @@ export default class DomConverter {
 		return domRange;
 		return domRange;
 	}
 	}
 
 
+	/**
+	 * Converts view {@link engine.treeView.Position} to DOM parent and offset.
+	 *
+	 * Inline and block {@link engile.treeView.filler fillers} are handled during the conversion.
+	 * If the converted position is directly before inline filler it is moved inside the filler.
+	 *
+	 * @param {engine.treeView.position} viewPosition View position.
+	 * @returns {Object} position
+	 * @returns {Node} position.parent DOM position parent.
+	 * @returns {Number} position.offset DOM position offset.
+	 */
 	viewPositionToDom( viewPosition ) {
 	viewPositionToDom( viewPosition ) {
 		const viewParent = viewPosition.parent;
 		const viewParent = viewPosition.parent;
 
 
@@ -188,7 +215,8 @@ export default class DomConverter {
 			}
 			}
 
 
 			return { parent: domParent, offset: offset };
 			return { parent: domParent, offset: offset };
-		} else {
+		} // instanceof HTMLElement
+		else {
 			let domParent, domBefore, domAfter;
 			let domParent, domBefore, domAfter;
 
 
 			if ( viewPosition.offset === 0 ) {
 			if ( viewPosition.offset === 0 ) {
@@ -214,13 +242,15 @@ export default class DomConverter {
 
 
 	/**
 	/**
 	 * Converts DOM to view. For all text nodes, not bound elements and document fragments new items will
 	 * Converts DOM to view. For all text nodes, not bound elements and document fragments new items will
-	 * be created. For bound elements and document fragments function will return corresponding items.
+	 * be created. For bound elements and document fragments function will return corresponding items. For
+	 * {@link engile.treeView.filler fillers} null will be returned.
 	 *
 	 *
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment to transform.
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment to transform.
 	 * @param {Object} [options] Conversion options.
 	 * @param {Object} [options] Conversion options.
 	 * @param {Boolean} [options.bind=false] Determines whether new elements will be bound.
 	 * @param {Boolean} [options.bind=false] Determines whether new elements will be bound.
 	 * @param {Boolean} [options.withChildren=true] It true node's and document fragment's children will be converted too.
 	 * @param {Boolean} [options.withChildren=true] It true node's and document fragment's children will be converted too.
-	 * @returns {engine.treeView.Node|engine.treeView.DocumentFragment} Converted node or document fragment.
+	 * @returns {engine.treeView.Node|engine.treeView.DocumentFragment|null} Converted node or document fragment. Null
+	 * if DOM node is a {@link engile.treeView.filler filler}.
 	 */
 	 */
 	domToView( domNode, options = {} ) {
 	domToView( domNode, options = {} ) {
 		if ( isBlockFiller( domNode, this.blockFiller )  ) {
 		if ( isBlockFiller( domNode, this.blockFiller )  ) {
@@ -240,7 +270,7 @@ export default class DomConverter {
 
 
 			let viewElement;
 			let viewElement;
 
 
-			if ( domNode instanceof  DocumentFragment ) {
+			if ( domNode instanceof DocumentFragment ) {
 				// Create view document fragment.
 				// Create view document fragment.
 				viewElement = new ViewDocumentFragment();
 				viewElement = new ViewDocumentFragment();
 
 
@@ -273,9 +303,17 @@ export default class DomConverter {
 		}
 		}
 	}
 	}
 
 
-	*domChildrenToView( domNode, options = {} ) {
-		for ( let i = 0; i < domNode.childNodes.length; i++ ) {
-			const domChild = domNode.childNodes[ i ];
+	/**
+	 * Converts children of the DOM element to view nodes using {@link engine.treeView.DomConverter#domToView} method.
+	 * Additionally this method omit block {@link engile.treeView.filler filler}, if it exists in the DOM parent.
+	 *
+	 * @param {HTMLElement} domElement Parent DOM element.
+	 * @param {Object} options See {@link engine.treeView.DomConverter#domToView} options parameter.
+	 * @returns {Iterable.<engine.treeView.Node>} View nodes.
+	 */
+	*domChildrenToView( domElement, options = {} ) {
+		for ( let i = 0; i < domElement.childNodes.length; i++ ) {
+			const domChild = domElement.childNodes[ i ];
 			const viewChild = this.domToView( domChild, options );
 			const viewChild = this.domToView( domChild, options );
 
 
 			if ( viewChild !== null ) {
 			if ( viewChild !== null ) {
@@ -284,6 +322,13 @@ export default class DomConverter {
 		}
 		}
 	}
 	}
 
 
+	/**
+	 * Converts DOM selection to view {@link engine.treeView.Selection}.
+	 * Ranges which can not be converted will be omitted.
+	 *
+	 * @param {Selection} domSelection DOM selection.
+	 * @returns {engine.treeView.Selection} View selection.
+	 */
 	domSelectionToView( domSelection ) {
 	domSelectionToView( domSelection ) {
 		const viewSelection = new ViewSelection();
 		const viewSelection = new ViewSelection();
 
 
@@ -299,6 +344,13 @@ export default class DomConverter {
 		return viewSelection;
 		return viewSelection;
 	}
 	}
 
 
+	/**
+	 * Converts DOM Range to view {@link engine.treeView.range}.
+	 * If the start or end position can not be converted null is returned.
+	 *
+	 * @param {Range} domRange DOM range.
+	 * @returns {engine.treeView.Range|null} View range.
+	 */
 	domRangeToView( domRange ) {
 	domRangeToView( domRange ) {
 		const viewStart = this.domPositionToView( domRange.startContainer, domRange.startOffset );
 		const viewStart = this.domPositionToView( domRange.startContainer, domRange.startOffset );
 		const viewEnd = this.domPositionToView( domRange.endContainer, domRange.endOffset );
 		const viewEnd = this.domPositionToView( domRange.endContainer, domRange.endOffset );
@@ -310,6 +362,18 @@ export default class DomConverter {
 		return null;
 		return null;
 	}
 	}
 
 
+	/**
+	 * Converts DOM parent and offset to view {@link engine.treeView.Position}.
+	 *
+	 * If the position is inside a {@link engile.treeView.filler filler} which has no corresponding view node,
+	 * position of the filler will be converted and returned.
+	 *
+	 * If structures are too different and it is not possible to find corresponding position then null will be returned.
+	 *
+	 * @param {Node} domParent DOM position parent.
+	 * @param {Number} domOffset DOM position offset.
+	 * @returns {engine.treeView.Position} viewPosition View position.
+	 */
 	domPositionToView( domParent, domOffset ) {
 	domPositionToView( domParent, domOffset ) {
 		if ( isBlockFiller( domParent, this.blockFiller ) ) {
 		if ( isBlockFiller( domParent, this.blockFiller ) ) {
 			return this.domPositionToView( domParent.parentNode, indexOf( domParent ) );
 			return this.domPositionToView( domParent.parentNode, indexOf( domParent ) );
@@ -333,7 +397,8 @@ export default class DomConverter {
 			}
 			}
 
 
 			return new ViewPosition( viewParent, offset );
 			return new ViewPosition( viewParent, offset );
-		} else {
+		} // domParent instanceof HTMLElement
+		else {
 			if ( domOffset === 0 ) {
 			if ( domOffset === 0 ) {
 				const viewParent = this.getCorrespondingView( domParent );
 				const viewParent = this.getCorrespondingView( domParent );
 
 
@@ -359,6 +424,8 @@ export default class DomConverter {
 	 * nodes and {@link engine.treeView.DomConverter#getCorrespondingViewDocumentFragment getCorrespondingViewDocumentFragment}
 	 * nodes and {@link engine.treeView.DomConverter#getCorrespondingViewDocumentFragment getCorrespondingViewDocumentFragment}
 	 * for document fragments.
 	 * for document fragments.
 	 *
 	 *
+	 * Note that for the block or inline {@link engile.treeView.filler filler} this method returns null.
+	 *
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment.
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment.
 	 * @returns {engine.treeView.Node|engine.treeView.DocumentFragment|null} Corresponding view item.
 	 * @returns {engine.treeView.Node|engine.treeView.DocumentFragment|null} Corresponding view item.
 	 */
 	 */
@@ -408,6 +475,8 @@ export default class DomConverter {
 	 *
 	 *
 	 * Otherwise `null` is returned.
 	 * Otherwise `null` is returned.
 	 *
 	 *
+	 * Note that for the block or inline {@link engile.treeView.filler filler} this method returns null.
+	 *
 	 * @param {Text} domText DOM text node.
 	 * @param {Text} domText DOM text node.
 	 * @returns {engine.treeView.Text|null} Corresponding view text node or null, if it was not possible to find a
 	 * @returns {engine.treeView.Text|null} Corresponding view text node or null, if it was not possible to find a
 	 * corresponding node.
 	 * corresponding node.
@@ -431,6 +500,7 @@ export default class DomConverter {
 			if ( viewElement ) {
 			if ( viewElement ) {
 				const nextSibling = viewElement.getNextSibling();
 				const nextSibling = viewElement.getNextSibling();
 
 
+				// It might be filler which has no corresponding view node.
 				if ( nextSibling instanceof ViewText ) {
 				if ( nextSibling instanceof ViewText ) {
 					return viewElement.getNextSibling();
 					return viewElement.getNextSibling();
 				} else {
 				} else {
@@ -445,6 +515,7 @@ export default class DomConverter {
 			if ( viewElement ) {
 			if ( viewElement ) {
 				const firstChild = viewElement.getChild( 0 );
 				const firstChild = viewElement.getChild( 0 );
 
 
+				// It might be filler which has no corresponding view node.
 				if ( firstChild instanceof ViewText ) {
 				if ( firstChild instanceof ViewText ) {
 					return firstChild;
 					return firstChild;
 				} else {
 				} else {

+ 2 - 2
packages/ckeditor5-engine/src/treeview/element.js

@@ -108,7 +108,7 @@ export default class Element extends Node {
 	 *
 	 *
 	 * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
 	 * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
 	 * element will be cloned without any children.
 	 * element will be cloned without any children.
-	 * @returns {Element} Clone of this element.
+	 * @returns {engine.treeView.Element} Clone of this element.
 	 */
 	 */
 	clone( deep ) {
 	clone( deep ) {
 		const childrenClone = [];
 		const childrenClone = [];
@@ -355,7 +355,7 @@ export default class Element extends Node {
 	 * Both elements should have the same name and attributes to be considered as similar. Two similar elements
 	 * Both elements should have the same name and attributes to be considered as similar. Two similar elements
 	 * can contain different set of children nodes.
 	 * can contain different set of children nodes.
 	 *
 	 *
-	 * @param {Element} otherElement
+	 * @param {engine.treeView.Element} otherElement
 	 * @returns {Boolean}
 	 * @returns {Boolean}
 	 */
 	 */
 	isSimilar( otherElement ) {
 	isSimilar( otherElement ) {

+ 1 - 1
packages/ckeditor5-engine/tests/_utils/view.js

@@ -868,4 +868,4 @@ export function setData( treeView, data ) {
 
 
 export function getData( treeView ) {
 export function getData( treeView ) {
 	return stringify( treeView.getRoot(), treeView.selection );
 	return stringify( treeView.getRoot(), treeView.selection );
-}
+}