@ckeditor/ckeditor5-engine 30.0.0

package/src/dataprocessor/dataprocessor.jsdoc

@@ -0,0 +1,64 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/dataprocessor/dataprocessor
+ */
+
+/**
+ * The data processor interface. It should be implemented by actual data processors.
+ *
+ * Each data processor implements a certain format of the data. For example, {@glink features/markdown Markdown data processor}
+ * will convert the data (a Markdown string) to a {@link module:engine/view/documentfragment~DocumentFragment document fragment} and back.
+ *
+ * **Note:** While the CKEditor 5 architecture supports changing the data format, in most scenarios we do recommend sticking to
+ * the default format which is HTML (supported by the {@link module:engine/dataprocessor/htmldataprocessor~HtmlDataProcessor}).
+ * HTML remains [the best standard for rich-text data](https://medium.com/content-uneditable/a-standard-for-rich-text-data-4b3a507af552).
+ *
+ * And please do remember – using Markdown [does not automatically make your
+ * application/website secure](https://github.com/ckeditor/ckeditor5-markdown-gfm/issues/16#issuecomment-375752994).
+ *
+ * @interface DataProcessor
+ */
+
+/**
+ * Converts a {@link module:engine/view/documentfragment~DocumentFragment document fragment} to data.
+ *
+ * @method #toData
+ * @param {module:engine/view/documentfragment~DocumentFragment} fragment The document fragment to be processed.
+ * @returns {*}
+ */
+
+/**
+ * Converts the data to a {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
+ *
+ * @method #toView
+ * @param {*} data The data to be processed.
+ * @returns {module:engine/view/documentfragment~DocumentFragment}
+ */
+
+/**
+ * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+ * and its content should be converted to a
+ * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"` while
+ * converting {@link #toView to view}.
+ *
+ * @method #registerRawContentMatcher
+ * @param {module:engine/view/matcher~MatcherPattern} pattern Pattern matching all view elements whose content should
+ * be treated as plain text.
+ */
+
+/**
+ * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+ * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+ *
+ * This mode allows for more precise handling of block fillers (so they do not leak into the editor content) but bloats the
+ * editor data with additional markup.
+ *
+ * This mode may be required by some features and will be turned on by them automatically.
+ *
+ * @method #useFillerType
+ * @param {'default'|'marked'} type Whether to use the default or marked `&nbsp;` block fillers.
+ */

package/src/dataprocessor/htmldataprocessor.js

@@ -0,0 +1,159 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/dataprocessor/htmldataprocessor
+ */
+
+/* globals document, DOMParser, Node */
+
+import BasicHtmlWriter from './basichtmlwriter';
+import DomConverter from '../view/domconverter';
+
+/**
+ * The HTML data processor class.
+ * This data processor implementation uses HTML as input and output data.
+ *
+ * @implements module:engine/dataprocessor/dataprocessor~DataProcessor
+ */
+export default class HtmlDataProcessor {
+	/**
+	 * Creates a new instance of the HTML data processor class.
+	 *
+	 * @param {module:engine/view/document~Document} document The view document instance.
+	 */
+	constructor( document ) {
+		/**
+		 * A DOM parser instance used to parse an HTML string to an HTML document.
+		 *
+		 * @private
+		 * @member {DOMParser}
+		 */
+		this._domParser = new DOMParser();
+
+		/**
+		 * A DOM converter used to convert DOM elements to view elements.
+		 *
+		 * @private
+		 * @member {module:engine/view/domconverter~DomConverter}
+		 */
+		this._domConverter = new DomConverter( document, { blockFillerMode: 'nbsp' } );
+
+		/**
+		 * A basic HTML writer instance used to convert DOM elements to an HTML string.
+		 *
+		 * @private
+		 * @member {module:engine/dataprocessor/basichtmlwriter~BasicHtmlWriter}
+		 */
+		this._htmlWriter = new BasicHtmlWriter();
+	}
+
+	/**
+	 * Converts a provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+	 * to data format — in this case to an HTML string.
+	 *
+	 * @param {module:engine/view/documentfragment~DocumentFragment} viewFragment
+	 * @returns {String} HTML string.
+	 */
+	toData( viewFragment ) {
+		// Convert view DocumentFragment to DOM DocumentFragment.
+		const domFragment = this._domConverter.viewToDom( viewFragment, document );
+
+		// Convert DOM DocumentFragment to HTML output.
+		return this._htmlWriter.getHtml( domFragment );
+	}
+
+	/**
+	 * Converts the provided HTML string to a view tree.
+	 *
+	 * @param {String} data An HTML string.
+	 * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} A converted view element.
+	 */
+	toView( data ) {
+		// Convert input HTML data to DOM DocumentFragment.
+		const domFragment = this._toDom( data );
+
+		// Convert DOM DocumentFragment to view DocumentFragment.
+		return this._domConverter.domToView( domFragment );
+	}
+
+	/**
+	 * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+	 * and not processed during the conversion from the DOM to the view elements.
+	 *
+	 * The raw data can be later accessed by a
+	 * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+	 *
+	 * @param {module:engine/view/matcher~MatcherPattern} pattern Pattern matching all view elements whose content should
+	 * be treated as raw data.
+	 */
+	registerRawContentMatcher( pattern ) {
+		this._domConverter.registerRawContentMatcher( pattern );
+	}
+
+	/**
+	 * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+	 * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+	 *
+	 * This mode allows for a more precise handling of the block fillers (so they do not leak into the editor content) but
+	 * bloats the editor data with additional markup.
+	 *
+	 * This mode may be required by some features and will be turned on by them automatically.
+	 *
+	 * @param {'default'|'marked'} type Whether to use the default or the marked `&nbsp;` block fillers.
+	 */
+	useFillerType( type ) {
+		this._domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';
+	}
+
+	/**
+	 * Converts an HTML string to its DOM representation. Returns a document fragment containing nodes parsed from
+	 * the provided data.
+	 *
+	 * @private
+	 * @param {String} data
+	 * @returns {DocumentFragment}
+	 */
+	_toDom( data ) {
+		const document = this._domParser.parseFromString( data, 'text/html' );
+		const fragment = document.createDocumentFragment();
+
+		// The rules for parsing an HTML string can be read on https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhtml.
+		//
+		// In short, parsing tokens in an HTML string starts with the so-called "initial" insertion mode. When a DOM parser is in this
+		// state and encounters a comment node, it inserts this comment node as the last child of the newly-created `HTMLDocument` object.
+		// The parser then proceeds to successive insertion modes during parsing subsequent tokens and appends in the `HTMLDocument` object
+		// other nodes (like <html>, <head>, <body>). This causes that the first leading comments from HTML string become the first nodes
+		// in the `HTMLDocument` object, but not in the <body> collection, because they are ultimately located before the <html> element.
+		//
+		// Therefore, so that such leading comments do not disappear, they all are moved from the `HTMLDocument` object to the document
+		// fragment, until the <html> element is encountered.
+		//
+		// See: https://github.com/ckeditor/ckeditor5/issues/9861.
+		let documentChildNode = document.firstChild;
+
+		while ( !documentChildNode.isSameNode( document.documentElement ) ) {
+			const node = documentChildNode;
+
+			documentChildNode = documentChildNode.nextSibling;
+
+			// It seems that `DOMParser#parseFromString()` adds only comment nodes directly to the `HTMLDocument` object, before the <html>
+			// node. The condition below is just to be sure we are moving only comment nodes.
+
+			/* istanbul ignore else */
+			if ( node.nodeType == Node.COMMENT_NODE ) {
+				fragment.appendChild( node );
+			}
+		}
+
+		const bodyChildNodes = document.body.childNodes;
+
+		while ( bodyChildNodes.length > 0 ) {
+			fragment.appendChild( bodyChildNodes[ 0 ] );
+		}
+
+		return fragment;
+	}
+}

package/src/dataprocessor/htmlwriter.js

@@ -0,0 +1,22 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/dataprocessor/htmlwriter
+ */
+
+/**
+ * The HTML writer interface.
+ *
+ * @interface module:engine/dataprocessor/htmlwriter~HtmlWriter
+ */
+
+/**
+ * Returns an HTML string created from a document fragment.
+ *
+ * @method module:engine/dataprocessor/htmlwriter~HtmlWriter#getHtml
+ * @param {DocumentFragment} fragment
+ * @returns {String}
+ */

package/src/dataprocessor/xmldataprocessor.js

@@ -0,0 +1,161 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/dataprocessor/xmldataprocessor
+ */
+
+/* globals DOMParser, document */
+
+import BasicHtmlWriter from './basichtmlwriter';
+import DomConverter from '../view/domconverter';
+
+/**
+ * The XML data processor class.
+ * This data processor implementation uses XML as input and output data.
+ * This class is needed because unlike HTML, XML allows to use any tag with any value.
+ * For example, `<link>Text</link>` is a valid XML but invalid HTML.
+ *
+ * @implements module:engine/dataprocessor/dataprocessor~DataProcessor
+ */
+export default class XmlDataProcessor {
+	/**
+	 * Creates a new instance of the XML data processor class.
+	 *
+	 * @param {module:engine/view/document~Document} document The view document instance.
+	 * @param {Object} options Configuration options.
+	 * @param {Array<String>} [options.namespaces=[]] A list of namespaces allowed to use in the XML input.
+	 */
+	constructor( document, options = {} ) {
+		/**
+		 * A list of namespaces allowed to use in the XML input.
+		 *
+		 * For example, registering namespaces [ 'attribute', 'container' ] allows to use `<attirbute:tagName></attribute:tagName>`
+		 * and `<container:tagName></container:tagName>` input. It is mainly for debugging.
+		 *
+		 * @public
+		 * @member {DOMParser}
+		 */
+		this.namespaces = options.namespaces || [];
+
+		/**
+		 * DOM parser instance used to parse an XML string to an XML document.
+		 *
+		 * @private
+		 * @member {DOMParser}
+		 */
+		this._domParser = new DOMParser();
+
+		/**
+		 * DOM converter used to convert DOM elements to view elements.
+		 *
+		 * @private
+		 * @member {module:engine/view/domconverter~DomConverter}
+		 */
+		this._domConverter = new DomConverter( document, { blockFillerMode: 'nbsp' } );
+
+		/**
+		 * A basic HTML writer instance used to convert DOM elements to an XML string.
+		 * There is no need to use a dedicated XML writer because the basic HTML writer works well in this case.
+		 *
+		 * @private
+		 * @member {module:engine/dataprocessor/basichtmlwriter~BasicHtmlWriter}
+		 */
+		this._htmlWriter = new BasicHtmlWriter();
+	}
+
+	/**
+	 * Converts the provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+	 * to data format &mdash; in this case an XML string.
+	 *
+	 * @param {module:engine/view/documentfragment~DocumentFragment} viewFragment
+	 * @returns {String} An XML string.
+	 */
+	toData( viewFragment ) {
+		// Convert view DocumentFragment to DOM DocumentFragment.
+		const domFragment = this._domConverter.viewToDom( viewFragment, document );
+
+		// Convert DOM DocumentFragment to XML output.
+		// There is no need to use dedicated for XML serializing method because BasicHtmlWriter works well in this case.
+		return this._htmlWriter.getHtml( domFragment );
+	}
+
+	/**
+	 * Converts the provided XML string to a view tree.
+	 *
+	 * @param {String} data An XML string.
+	 * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} A converted view element.
+	 */
+	toView( data ) {
+		// Convert input XML data to DOM DocumentFragment.
+		const domFragment = this._toDom( data );
+
+		// Convert DOM DocumentFragment to view DocumentFragment.
+		return this._domConverter.domToView( domFragment, { keepOriginalCase: true } );
+	}
+
+	/**
+	 * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+	 * and not processed during the conversion from XML to view elements.
+	 *
+	 * The raw data can be later accessed by a
+	 * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"`.
+	 *
+	 * @param {module:engine/view/matcher~MatcherPattern} pattern Pattern matching all view elements whose content should
+	 * be treated as raw data.
+	 */
+	registerRawContentMatcher( pattern ) {
+		this._domConverter.registerRawContentMatcher( pattern );
+	}
+
+	/**
+	 * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+	 * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+	 *
+	 * This mode allows for a more precise handling of block fillers (so they do not leak into editor content) but
+	 * bloats the editor data with additional markup.
+	 *
+	 * This mode may be required by some features and will be turned on by them automatically.
+	 *
+	 * @param {'default'|'marked'} type Whether to use the default or the marked `&nbsp;` block fillers.
+	 */
+	useFillerType( type ) {
+		this._domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';
+	}
+
+	/**
+	 * Converts an XML string to its DOM representation. Returns a document fragment containing nodes parsed from
+	 * the provided data.
+	 *
+	 * @private
+	 * @param {String} data
+	 * @returns {DocumentFragment}
+	 */
+	_toDom( data ) {
+		// Stringify namespaces.
+		const namespaces = this.namespaces.map( nsp => `xmlns:${ nsp }="nsp"` ).join( ' ' );
+
+		// Wrap data into root element with optional namespace definitions.
+		data = `<xml ${ namespaces }>${ data }</xml>`;
+
+		const parsedDocument = this._domParser.parseFromString( data, 'text/xml' );
+
+		// Parse validation.
+		const parserError = parsedDocument.querySelector( 'parsererror' );
+
+		if ( parserError ) {
+			throw new Error( 'Parse error - ' + parserError.textContent );
+		}
+
+		const fragment = parsedDocument.createDocumentFragment();
+		const nodes = parsedDocument.documentElement.childNodes;
+
+		while ( nodes.length > 0 ) {
+			fragment.appendChild( nodes[ 0 ] );
+		}
+
+		return fragment;
+	}
+}