#4469: Implemented the view RawElement

docs/_snippets/framework/tutorials/using-react-in-widget.js

@@ -114,17 +114,13 @@ class ProductPreviewEditing extends Plugin {
 
 				// The inner <div class="product__react-wrapper"></div> element.
 				// This element will host a React <ProductPreview /> component.
-				const reactWrapper = viewWriter.createUIElement( 'div', {
+				const reactWrapper = viewWriter.createRawElement( 'div', {
 					class: 'product__react-wrapper'
-				}, function( domDocument ) {
-					const domElement = this.toDomElement( domDocument );
-
+				}, function( domElement ) {
 					// This the place where React renders the actual product preview hosted
 					// by a UIElement in the view. you are using a function (renderer) passed as
 					// editor.config.products#productRenderer.
 					renderProduct( id, domElement );
-
-					return domElement;
 				} );
 
 				viewWriter.insert( viewWriter.createPositionAt( section, 0 ), reactWrapper );

docs/framework/guides/architecture/editing-engine.md

@@ -226,14 +226,15 @@ editor.data;                    // The data pipeline (DataController).
 
 ### Element types and custom data
 
-The structure of the view resembles the structure in the DOM very closely. The semantics of HTML is defined in its specification. The view structure comes "DTD-free", so in order to provide additional information and better express the semantics of the content, the view structure implements 5 element types ({@link module:engine/view/containerelement~ContainerElement}, {@link module:engine/view/attributeelement~AttributeElement}, {@link module:engine/view/emptyelement~EmptyElement}, {@link module:engine/view/uielement~UIElement}, and {@link module:engine/view/editableelement~EditableElement}) and so called {@link module:engine/view/element~Element#getCustomProperty "custom properties"} (i.e. custom element properties which are not rendered). This additional information provided by editor features is then used by the {@link module:engine/view/renderer~Renderer} and [converters](#conversion).
+The structure of the view resembles the structure in the DOM very closely. The semantics of HTML is defined in its specification. The view structure comes "DTD-free", so in order to provide additional information and better express the semantics of the content, the view structure implements 6 element types ({@link module:engine/view/containerelement~ContainerElement}, {@link module:engine/view/attributeelement~AttributeElement}, {@link module:engine/view/emptyelement~EmptyElement}, {@link module:engine/view/rawelement~RawElement}, {@link module:engine/view/uielement~UIElement}, and {@link module:engine/view/editableelement~EditableElement}) and so called {@link module:engine/view/element~Element#getCustomProperty "custom properties"} (i.e. custom element properties which are not rendered). This additional information provided by editor features is then used by the {@link module:engine/view/renderer~Renderer} and [converters](#conversion).
 
 The element types can be defined as follows:
 
 * **Container element** &ndash; The elements that build the structure of the content. Used for block elements such as `<p>`, `<h1>`, `<blockQuote>`, `<li>`, etc.
 * **Attribute element** &ndash; The elements that cannot contain container elements inside them. Most model text attributes are converted to view attribute elements. They are used mostly for inline styling elements such as `<strong>`, `<i>`, `<a>`, `<code>`. Similar attribute elements are flattened by the view writer, so e.g. `<a href="..."><a class="bar">x</a></a>` would automatically be optimized to `<a href="..." class="bar">x</a>`.
 * **Empty element** &ndash; The elements that must not have any child nodes, for example `<img>`.
 * **UI elements** &ndash; The elements that are not a part of the "data" but need to be "inlined" in the content. They are ignored by the selection (it jumps over them) and the view writer in general. The contents of these elements and events coming from them are filtered out, too.
+* **Raw element** &ndash; The elements that work as data containers ("wrappers", "sandboxes") but their children are transparent to the editor. Useful when non-standard data must be rendered but the editor should not be concerned what it is and how it works. Users cannot put the selection inside a raw element, split it into smaller chunks or directly modify its content.
 * **Editable element** &ndash; The elements used as "nested editables" of non-editable fragments of the content, for example a caption in the image widget, where the `<figure>` wrapping the image is not editable (it is a widget) and the `<figcaption>` inside it is an editable element.
 
 Additionally, you can define {@link module:engine/view/element~Element#getCustomProperty custom properties} which can be used to store information like:

docs/framework/guides/tutorials/using-react-in-a-widget.md

@@ -365,17 +365,13 @@ export default class ProductPreviewEditing extends Plugin {
 
 				// The inner <div class="product__react-wrapper"></div> element.
 				// This element will host a React <ProductPreview /> component.
-				const reactWrapper = viewWriter.createUIElement( 'div', {
+				const reactWrapper = viewWriter.createRawElement( 'div', {
 					class: 'product__react-wrapper'
-				}, function( domDocument ) {
-					const domElement = this.toDomElement( domDocument );
-
+				}, function( domElement ) {
 					// This the place where React renders the actual product preview hosted
 					// by a UIElement in the view. You are using a function (renderer) passed as
 					// editor.config.products#productRenderer.
 					renderProduct( id, domElement );
-
-					return domElement;
 				} );
 
 				viewWriter.insert( viewWriter.createPositionAt( section, 0 ), reactWrapper );
@@ -1184,17 +1180,13 @@ export default class ProductPreviewEditing extends Plugin {
 
 				// The inner <div class="product__react-wrapper"></div> element.
 				// This element will host a React <ProductPreview /> component.
-				const reactWrapper = viewWriter.createUIElement( 'div', {
+				const reactWrapper = viewWriter.createRawElement( 'div', {
 					class: 'product__react-wrapper'
-				}, function( domDocument ) {
-					const domElement = this.toDomElement( domDocument );
-
+				}, function( domElement ) {
 					// This the place where React renders the actual product preview hosted
 					// by a UIElement in the view. You are using a function (renderer) passed as
 					// editor.config.products#productRenderer.
 					renderProduct( id, domElement );
-
-					return domElement;
 				} );
 
 				viewWriter.insert( viewWriter.createPositionAt( section, 0 ), reactWrapper );

packages/ckeditor5-engine/src/dev-utils/view.js

@@ -25,6 +25,7 @@ import AttributeElement from '../view/attributeelement';
 import ContainerElement from '../view/containerelement';
 import EmptyElement from '../view/emptyelement';
 import UIElement from '../view/uielement';
+import RawElement from '../view/rawelement';
 import { StylesProcessor } from '../view/stylesmap';
 
 const ELEMENT_RANGE_START_TOKEN = '[';
@@ -35,7 +36,8 @@ const allowedTypes = {
 	'container': ContainerElement,
 	'attribute': AttributeElement,
 	'empty': EmptyElement,
-	'ui': UIElement
+	'ui': UIElement,
+	'raw': RawElement
 };
 
 /**
@@ -55,6 +57,8 @@ const allowedTypes = {
  * (`<span id="marker:foo">`).
  * @param {Boolean} [options.renderUIElements=false] When set to `true`, the inner content of each
  * {@link module:engine/view/uielement~UIElement} will be printed.
+ * @param {Boolean} [options.renderRawElements=false] When set to `true`, the inner content of each
+ * {@link module:engine/view/rawelement~RawElement} will be printed.
  * @returns {String} The stringified data.
  */
 export function getData( view, options = {} ) {
@@ -70,6 +74,7 @@ export function getData( view, options = {} ) {
 		showType: options.showType,
 		showPriority: options.showPriority,
 		renderUIElements: options.renderUIElements,
+		renderRawElements: options.renderRawElements,
 		ignoreRoot: true
 	};
 
@@ -234,6 +239,8 @@ setData._parse = parse;
  *  `{` and `}` and the selection outside the text as `[` and `]`. When set to `false`, both will be marked as `[` and `]` only.
  * @param {Boolean} [options.renderUIElements=false] When set to `true`, the inner content of each
  * {@link module:engine/view/uielement~UIElement} will be printed.
+ * @param {Boolean} [options.renderRawElements=false] When set to `true`, the inner content of each
+ * {@link module:engine/view/rawelement~RawElement} will be printed.
  * @returns {String} An HTML-like string representing the view.
  */
 export function stringify( node, selectionOrPositionOrRange = null, options = {} ) {
@@ -622,6 +629,8 @@ class ViewStringify {
 	 * `{` and `}` and the selection outside the text as `[` and `]`. When set to `false`, both are marked as `[` and `]`.
 	 * @param {Boolean} [options.renderUIElements=false] When set to `true`, the inner content of each
 	 * {@link module:engine/view/uielement~UIElement} will be printed.
+	 * @param {Boolean} [options.renderRawElements=false] When set to `true`, the inner content of each
+	 * {@link module:engine/view/rawelement~RawElement} will be printed.
 	 */
 	constructor( root, selection, options ) {
 		this.root = root;
@@ -638,6 +647,7 @@ class ViewStringify {
 		this.ignoreRoot = !!options.ignoreRoot;
 		this.sameSelectionCharacters = !!options.sameSelectionCharacters;
 		this.renderUIElements = !!options.renderUIElements;
+		this.renderRawElements = !!options.renderRawElements;
 	}
 
 	/**
@@ -670,8 +680,15 @@ class ViewStringify {
 				callback( this._stringifyElementOpen( root ) );
 			}
 
-			if ( this.renderUIElements && root.is( 'uiElement' ) ) {
+			if ( ( this.renderUIElements && root.is( 'uiElement' ) ) ) {
 				callback( root.render( document ).innerHTML );
+			} else if ( this.renderRawElements && root.is( 'rawElement' ) ) {
+				// There's no DOM element for "root" to pass to render(). Creating
+				// a surrogate container to render the children instead.
+				const rawContentContainer = document.createElement( 'div' );
+				root.render( rawContentContainer );
+
+				callback( rawContentContainer.innerHTML );
 			} else {
 				let offset = 0;
 				callback( this._stringifyElementRanges( root, offset ) );
@@ -824,8 +841,9 @@ class ViewStringify {
 	 * Returns:
 	 * * 'attribute' for {@link module:engine/view/attributeelement~AttributeElement attribute elements},
 	 * * 'container' for {@link module:engine/view/containerelement~ContainerElement container elements},
-	 * * 'empty' for {@link module:engine/view/emptyelement~EmptyElement empty elements}.
-	 * * 'ui' for {@link module:engine/view/uielement~UIElement UI elements}.
+	 * * 'empty' for {@link module:engine/view/emptyelement~EmptyElement empty elements},
+	 * * 'ui' for {@link module:engine/view/uielement~UIElement UI elements},
+	 * * 'raw' for {@link module:engine/view/rawelement~RawElement raw elements},
 	 * * an empty string when the current configuration is preventing showing elements' types.
 	 *
 	 * @private
@@ -943,10 +961,10 @@ function _convertViewElements( rootNode ) {
 		for ( const child of [ ...rootNode.getChildren() ] ) {
 			if ( convertedElement.is( 'emptyElement' ) ) {
 				throw new Error( 'Parse error - cannot parse inside EmptyElement.' );
-			}
-
-			if ( convertedElement.is( 'uiElement' ) ) {
+			} else if ( convertedElement.is( 'uiElement' ) ) {
 				throw new Error( 'Parse error - cannot parse inside UIElement.' );
+			} else if ( convertedElement.is( 'rawElement' ) ) {
+				throw new Error( 'Parse error - cannot parse inside RawElement.' );
 			}
 
 			convertedElement._appendChild( _convertViewElements( child ) );

packages/ckeditor5-engine/src/view/domconverter.js

@@ -29,16 +29,16 @@ import { isElement } from 'lodash-es';
 const BR_FILLER_REF = BR_FILLER( document );
 
 /**
- * DomConverter is a set of tools to do transformations between DOM nodes and view nodes. It also handles
- * {@link module:engine/view/domconverter~DomConverter#bindElements binding} these nodes.
+ * `DomConverter` is a set of tools to do transformations between DOM nodes and view nodes. It also handles
+ * {@link module:engine/view/domconverter~DomConverter#bindElements bindings} between these nodes.
  *
- * The instance of DOMConverter is available in {@link module:engine/view/view~View#domConverter `editor.editing.view.domConverter`}.
+ * The instance of `DOMConverter` is available under {@link module:engine/view/view~View#domConverter `editor.editing.view.domConverter`}.
  *
- * DomConverter does not check which nodes should be rendered (use {@link module:engine/view/renderer~Renderer}), does not keep a
+ * `DomConverter` does not check which nodes should be rendered (use {@link module:engine/view/renderer~Renderer}), does not keep a
  * state of a tree nor keeps synchronization between tree view and DOM tree (use {@link module:engine/view/document~Document}).
  *
- * DomConverter keeps DOM elements to View element bindings, so when the converter will be destroyed, the binding will
- * be lost. Two converters will keep separate binding maps, so one tree view can be bound with two DOM trees.
+ * `DomConverter` keeps DOM elements to View element bindings, so when the converter gets destroyed, the bindings are lost.
+ * Two converters will keep separate binding maps, so one tree view can be bound with two DOM trees.
  */
 export default class DomConverter {
 	/**
@@ -236,6 +236,12 @@ export default class DomConverter {
 					domElement = domDocument.createElement( viewNode.name );
 				}
 
+				// RawElement take care of their children in RawElement#render() method which can be customized
+				// (see https://github.com/ckeditor/ckeditor5/issues/4469).
+				if ( viewNode.is( 'rawElement' ) ) {
+					viewNode.render( domElement );
+				}
+
 				if ( options.bind ) {
 					this.bindElements( domElement, viewNode );
 				}
@@ -392,11 +398,11 @@ export default class DomConverter {
 			return null;
 		}
 
-		// When node is inside UIElement return that UIElement as it's view representation.
-		const uiElement = this.getParentUIElement( domNode, this._domToViewMapping );
+		// When node is inside a UIElement or a RawElement return that parent as it's view representation.
+		const hostElement = this.getHostViewElement( domNode, this._domToViewMapping );
 
-		if ( uiElement ) {
-			return uiElement;
+		if ( hostElement ) {
+			return hostElement;
 		}
 
 		if ( isText( domNode ) ) {
@@ -550,10 +556,10 @@ export default class DomConverter {
 			return this.domPositionToView( domParent.parentNode, indexOf( domParent ) );
 		}
 
-		// If position is somewhere inside UIElement - return position before that element.
+		// If position is somewhere inside UIElement or a RawElement - return position before that element.
 		const viewElement = this.mapDomToView( domParent );
 
-		if ( viewElement && viewElement.is( 'uiElement' ) ) {
+		if ( viewElement && ( viewElement.is( 'uiElement' ) || viewElement.is( 'rawElement' ) ) ) {
 			return ViewPosition._createBefore( viewElement );
 		}
 
@@ -605,14 +611,18 @@ export default class DomConverter {
 	 * {@link module:engine/view/documentfragment~DocumentFragment} for provided DOM element or
 	 * document fragment. If there is no view item {@link module:engine/view/domconverter~DomConverter#bindElements bound}
 	 * to the given DOM - `undefined` is returned.
-	 * For all DOM elements rendered by {@link module:engine/view/uielement~UIElement} that UIElement will be returned.
+	 *
+	 * For all DOM elements rendered by a {@link module:engine/view/uielement~UIElement} or
+	 * a {@link module:engine/view/rawelement~RawElement}, the parent `UIElement` or `RawElement` will be returned.
 	 *
 	 * @param {DocumentFragment|Element} domElementOrDocumentFragment DOM element or document fragment.
 	 * @returns {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment|undefined}
 	 * Corresponding view element, document fragment or `undefined` if no element was bound.
 	 */
 	mapDomToView( domElementOrDocumentFragment ) {
-		return this.getParentUIElement( domElementOrDocumentFragment ) || this._domToViewMapping.get( domElementOrDocumentFragment );
+		const hostElement = this.getHostViewElement( domElementOrDocumentFragment );
+
+		return hostElement || this._domToViewMapping.get( domElementOrDocumentFragment );
 	}
 
 	/**
@@ -625,7 +635,8 @@ export default class DomConverter {
 	 * If this is a first child in the parent and the parent is a {@link module:engine/view/domconverter~DomConverter#bindElements bound}
 	 * element, it is used to find the corresponding text node.
 	 *
-	 * For all text nodes rendered by {@link module:engine/view/uielement~UIElement} that UIElement will be returned.
+	 * For all text nodes rendered by a {@link module:engine/view/uielement~UIElement} or
+	 * a {@link module:engine/view/rawelement~RawElement}, the parent `UIElement` or `RawElement` will be returned.
 	 *
 	 * Otherwise `null` is returned.
 	 *
@@ -640,11 +651,11 @@ export default class DomConverter {
 			return null;
 		}
 
-		// If DOM text was rendered by UIElement - return that element.
-		const uiElement = this.getParentUIElement( domText );
+		// If DOM text was rendered by a UIElement or a RawElement - return this parent element.
+		const hostElement = this.getHostViewElement( domText );
 
-		if ( uiElement ) {
-			return uiElement;
+		if ( hostElement ) {
+			return hostElement;
 		}
 
 		const previousSibling = domText.previousSibling;
@@ -858,13 +869,13 @@ export default class DomConverter {
 	}
 
 	/**
-	 * Returns parent {@link module:engine/view/uielement~UIElement} for provided DOM node. Returns `null` if there is no
-	 * parent UIElement.
+	 * Returns a parent {@link module:engine/view/uielement~UIElement} or {@link module:engine/view/rawelement~RawElement}
+	 * that hosts the provided DOM node. Returns `null` if there is no such parent.
 	 *
 	 * @param {Node} domNode
-	 * @returns {module:engine/view/uielement~UIElement|null}
+	 * @returns {module:engine/view/uielement~UIElement|module:engine/view/rawelement~RawElement|null}
 	 */
-	getParentUIElement( domNode ) {
+	getHostViewElement( domNode ) {
 		const ancestors = getAncestors( domNode );
 
 		// Remove domNode from the list.
@@ -874,7 +885,7 @@ export default class DomConverter {
 			const domNode = ancestors.pop();
 			const viewNode = this._domToViewMapping.get( domNode );
 
-			if ( viewNode && viewNode.is( 'uiElement' ) ) {
+			if ( viewNode && ( viewNode.is( 'uiElement' ) || viewNode.is( 'rawElement' ) ) ) {
 				return viewNode;
 			}
 		}
@@ -886,8 +897,10 @@ export default class DomConverter {
 	 * Checks if given selection's boundaries are at correct places.
 	 *
 	 * The following places are considered as incorrect for selection boundaries:
+	 *
 	 * * before or in the middle of the inline filler sequence,
-	 * * inside the DOM element which represents {@link module:engine/view/uielement~UIElement a view ui element}.
+	 * * inside a DOM element which represents {@link module:engine/view/uielement~UIElement a view UI element},
+	 * * inside a DOM element which represents {@link module:engine/view/rawelement~RawElement a view raw element}.
 	 *
 	 * @param {Selection} domSelection DOM Selection object to be checked.
 	 * @returns {Boolean} `true` if the given selection is at a correct place, `false` otherwise.
@@ -919,9 +932,10 @@ export default class DomConverter {
 
 		const viewParent = this.mapDomToView( domParent );
 
-		// If selection is in `view.UIElement`, it is incorrect. Note that `mapDomToView()` returns `view.UIElement`
-		// also for any dom element that is inside the view ui element (so we don't need to perform any additional checks).
-		if ( viewParent && viewParent.is( 'uiElement' ) ) {
+		// The position is incorrect when anchored inside a UIElement or a RawElement.
+		// Note: In case of UIElement and RawElement, mapDomToView() returns a parent element for any DOM child
+		// so there's no need to perform any additional checks.
+		if ( viewParent && ( viewParent.is( 'uiElement' ) || viewParent.is( 'rawElement' ) ) ) {
 			return false;
 		}