8
0
فهرست منبع

Simplified RawElement#render(). Added docs to the class.

Aleksander Nowodzinski 5 سال پیش
والد
کامیت
1fa577f35a
1فایلهای تغییر یافته به همراه20 افزوده شده و 38 حذف شده
  1. 20 38
      packages/ckeditor5-engine/src/view/rawelement.js

+ 20 - 38
packages/ckeditor5-engine/src/view/rawelement.js

@@ -14,7 +14,15 @@ import Node from './node';
 /**
  * The raw element class.
  *
- * It is used to represent elements that TODO.
+ * Raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or
+ * even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures
+ * in the editor content without, for instance, worrying about compatibility with other editor features.
+ * Raw elements make a perfect tool for integration with external frameworks and data sources.
+ *
+ * Unlike {@link module:engine/view/uielement~UIElement ui elements}, raw elements act like a real editor
+ * content (similar to {@link module:engine/view/containerelement~ContainerElement} or
+ * {@link module:engine/view/emptyelement~EmptyElement}), they are considered by the editor selection and
+ * {@link module:widget/utils.toWidget they can work as widgets}.
  *
  * To create a new raw element use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
@@ -100,59 +108,33 @@ export default class RawElement extends Element {
 	_insertChild( index, nodes ) {
 		if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
 			/**
-			 * Cannot add children to a {@link module:engine/view/rawelement~RawElement}.
+			 * Cannot add children to a {@link module:engine/view/rawelement~RawElement} instance.
 			 *
 			 * @error view-rawelement-cannot-add
 			 */
 			throw new CKEditorError(
-				'view-rawelement-cannot-add: Cannot add child nodes to RawElement instance.',
+				'view-rawelement-cannot-add: Cannot add child nodes to a RawElement instance.',
 				[ this, nodes ]
 			);
 		}
 	}
 
 	/**
-	 * Renders this {@link module:engine/view/rawelement~RawElement} to DOM. This method is called by
-	 * {@link module:engine/view/domconverter~DomConverter}.
-	 * Do not use inheritance to create custom rendering method, replace `render()` method instead:
+	 * Allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
+	 * This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
+	 * passed as an argument leaving the number and shape of the children up to the integrator.
 	 *
-	 *		const myRawElement = downcastWriter.createRawElement( 'span' );
+	 * This method **must be defined** for the `RawElement` to work:
 	 *
-	 *		myRawElement.render = function( domDocument ) {
-	 *			const domElement = this.toDomElement( domDocument );
-	 *			domElement.innerHTML = '<b>this is ui element</b>';
+	 *		const myRawElement = downcastWriter.createRawElement( 'div' );
 	 *
-	 *			return domElement;
+	 *		myRawElement.render = function( domElement ) {
+	 *			domElement.innerHTML = '<b>This is the raw content of myRawElement.</b>';
 	 *		};
 	 *
-	 * If changes in your raw element should trigger some editor UI update you should call
-	 * the {@link module:core/editor/editorui~EditorUI#update `editor.ui.update()`} method
-	 * after rendering your UI element.
-	 *
-	 * @param {Document} domDocument
-	 * @returns {HTMLElement}
-	 */
-	render( domDocument ) {
-		return this.toDomElement( domDocument );
-	}
-
-	/**
-	 * Creates DOM element based on this view `RawElement`.
-	 *
-	 * **Note**: Each time this method is called new DOM element is created.
-	 *
-	 * @param {Document} domDocument
-	 * @returns {HTMLElement}
+	 * @method #render
+	 * @param {HTMLElement} domElement The native DOM element representing the raw view element.
 	 */
-	toDomElement( domDocument ) {
-		const domElement = domDocument.createElement( this.name );
-
-		for ( const key of this.getAttributeKeys() ) {
-			domElement.setAttribute( key, this.getAttribute( key ) );
-		}
-
-		return domElement;
-	}
 }
 
 // Returns `null` because block filler is not needed for RawElements.