Krzysztof Krztoń 7 lat temu
rodzic
commit
dd6cac98d6

+ 9 - 5
packages/ckeditor5-paste-from-office/src/filters/common.js

@@ -13,7 +13,7 @@ const htmlDataProcessor = new HtmlDataProcessor();
  * @param {Object} data
  * @param {String} data.html HTML string from which `body` contents will be extracted.
  * @returns {Object} result
- * @returns {String|null} result.body Extracted `body` contents. If `body` tag was not present null is returned.
+ * @returns {String|null} result.body Extracted `body` contents. If `body` tag was not present or empty, `null` is returned.
  */
 export function extractBody( data ) {
 	const bodyRegexp = /<body[^>]*>([\s*|\S*]*?)<\/body>/i;
@@ -25,14 +25,15 @@ export function extractBody( data ) {
 }
 
 /**
- * Parses provided HTML string to {@link module:engine/view/view~View} element.
+ * Parses provided HTML string to {@link module:engine/view/node~Node}
+ * or {@link module:engine/view/documentfragment~DocumentFragment} instance.
  *
  * @param {Object} data
  * @param {String} data.body HTML string which should be parsed.
  * @returns {Object} result
  * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} result.view
- * The {@link module:engine/view/view~View} class instance created based on provided HTML string.
- * Returns `null` if `data.body` parameter was empty.
+ * The {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment} class
+ * instance created based on provided HTML string. Returns `null` if `data.body` parameter was empty.
  */
 export function bodyToView( data ) {
 	data.view = data.body ? htmlDataProcessor.toView( data.body ) : null;
@@ -68,6 +69,9 @@ export function extractStyles( data ) {
 /**
  * Parses given styles string returning native `CSSStyleSheet` object.
  *
+ * **Important**: during parsing, the browser will remove all invalid properties (e.g. all `mso-something-something: ...`)
+ * and all invalid selectors (like `@list l1:level1`).
+ *
  * @param {Object} data
  * @param {String} data.styles Styles to be parse.
  * @param {Document} domDocument Document used to create helper element in which stylesheet will be injected.
@@ -94,7 +98,7 @@ export function stylesToStylesheet( data, domDocument ) {
 
 // Parses provided CSS string creating native `CSSStyleSheet` object.
 //
-// If available this function use shadow DOM element to parse CSS. If not it fallback to ifrmae element.
+// If available this function uses shadow DOM element to parse CSS. If not, it fallbacks to the iframe element.
 //
 // @param {String} cssString String containing CSS rules/stylsheet to be parsed.
 // @param {Document} domDocument Document used to create helper element in which stylesheet will be injected.

+ 16 - 10
packages/ckeditor5-paste-from-office/src/filters/list.js

@@ -18,10 +18,11 @@ import RawWriter from '@ckeditor/ckeditor5-engine/src/view/rawwriter';
  *		<h1 style='mso-list:l0 level1 lfo1'>...</h1> // Heading 1 based list.
  *
  * @param {Object} data
- * @param {module:engine/view/view~View} data.view The {@link module:engine/view/view~View} instance.
+ * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} data.view The view
+ * structure which to transform.
  * @returns {Object} result
- * @returns {module:engine/view/view~View} result.view The {@link module:engine/view/view~View} instance
- * with list-like elements transformed into semantic lists.
+ * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} result.view The view
+ * structure instance with list-like elements transformed into semantic lists.
  */
 export function paragraphsToLists( data ) {
 	if ( data.view ) {
@@ -59,6 +60,7 @@ const listBulletMatcher = new Matcher( {
 //
 // @param {module:engine/src/view/position~Position} startPosition Position from which to start looking.
 // @returns {Array.<Object>} Array of found list items. Each item is an object containing:
+//
 //		* {module:engine/src/view/element~Element} element List-like element.
 //		* {Number} id List item id parsed from `mso-list` style (see `getListItemData()` function).
 //		* {Number} order List item creation order parsed from `mso-list` style (see `getListItemData()` function).
@@ -84,8 +86,8 @@ function findAllListNodes( startPosition ) {
 	return listNodes;
 }
 
-// Transforms given list-like nodes into semantic lists. As the function operates on provided
-// {module:engine/src/view/element~Element elements}, it will modify the view structure to which list elements belongs.
+// Transforms given list-like nodes into semantic lists. As the function operates on a provided
+// {module:engine/src/view/element~Element elements}, it will modify the view structure to which those list elements belongs.
 //
 // @param {Array.<Object>} listItems Array containing list items data. Usually it is the output of `findAllListNodes()` function.
 // @param {String} styles CSS styles which may contain additional data about lists format.
@@ -115,7 +117,7 @@ function createLists( listItems, styles ) {
 
 // Extracts list information from Word specific list style like:
 //
-//		`mso-list:l1 level1 lfo1`
+//		`style="mso-list:l1 level1 lfo1"`
 //
 // where:
 //
@@ -141,15 +143,19 @@ function getListItemData( element ) {
 	return data;
 }
 
-// Checks list item style based on provided CSS. List item style is extracted from CSS stylesheet. Each list with its specific
-// styling `mso-list:l1 level1 lfo1` has its dedicated properties in a stylesheet defined with selector like:
+// Checks list item style based on a provided CSS.
+//
+// List item style is extracted from CSS stylesheet. Each list with its specific style attribute value (`mso-list:l1 level1 lfo1`)
+// has its dedicated properties in a CSS stylesheet defined with a selector like:
 //
 // 		@list l1:level1 { ... }
 //
-// which contains `mso-level-number-format` property which defines list numbering/bullet style. If this property
+// It contains `mso-level-number-format` property which defines list numbering/bullet style. If this property
 // is not defined it means default `decimal` numbering.
 //
-// @param {Object} listItem List item for which list style will be find.
+// Here CSS string representation is used as `mso-level-number-format` is invalid CSS property which gets removed during parsing.
+//
+// @param {Object} listItem List item for which list style will be searched for.
 // @param {String} styles CSS stylesheet.
 // @returns {Object} result
 // @returns {String} result.type Type of the list, could be `ul` or `ol`.

+ 10 - 10
packages/ckeditor5-paste-from-office/src/pastefromword.js

@@ -14,7 +14,7 @@ import { extractBody, bodyToView, extractStyles } from './filters/common';
 import { paragraphsToLists } from './filters/list';
 
 /**
- * This plugin handles content pasted from Word and transforms it if necessary
+ * This plugin handles content pasted from Word and transforms it (if necessary)
  * to format suitable for editor {@link module:engine/model/model~Model}.
  *
  * @extends module:core/plugin~Plugin
@@ -69,7 +69,7 @@ export default class PasteFromWord extends Plugin {
 	}
 }
 
-// Checks if given HTML string was produced by pasting content from Word.
+// Checks if given HTML string is a result of pasting content from Word.
 //
 // @param {String} html HTML string to test.
 // @returns {Boolean} True if given HTML string is a Word HTML.
@@ -78,21 +78,21 @@ function isWordInput( html ) {
 	return !!( html && html.match( /<meta\s*name="?generator"?\s*content="?microsoft\s*word\s*\d+"?\/?>/gi ) );
 }
 
-// Transforms given HTML string by provided transformation functions.
+// Transforms given HTML string by provided filter functions.
 //
 // @param {String} html HTML string to transform.
 // @param {Document} domDocument Editor owner document.
-// @param {Array.<Function>} transforms Functions which are used in the order of passing to transform given HTML.
+// @param {Array.<Function>} filters Functions which are used filter/transform given HTML. Filters are executed
+// in an order they where provided to this function.
 // @returns {Object} data Object containing transformed parts of an input HTML string in a different formats. The number
-// and type of formats depends on a provided transforms as each transform can create separate format or change existing one.
+// and type of formats depends on a provided filters as each filter function can create separate format or change existing one.
 // @returns {String} data.html Input HTML string.
-// @returns {*} data.* Any type of data created by transform functions. It directly depends on transform functions
-// which were provided. to this function.
-function transformInput( html, domDocument, ...transforms ) {
+// @returns {*} data.* Any type of data created by filter functions. It directly depends on provided filter functions.
+function transformInput( html, domDocument, ...filters ) {
 	let transformedData = { html };
 
-	for ( const transform of transforms ) {
-		transformedData = transform( transformedData, domDocument );
+	for ( const filter of filters ) {
+		transformedData = filter( transformedData, domDocument );
 	}
 
 	return transformedData;

+ 13 - 13
packages/ckeditor5-paste-from-office/tests/_utils/utils.js

@@ -25,6 +25,19 @@ export function expectPaste( editor, input, expectedModel, expectedView = null )
 }
 
 /**
+ * Fires paste event on a given editor instance with a specific HTML data.
+ *
+ * @param {module:core/editor/editor~Editor} editor Editor instance on which paste event will be fired.
+ * @param {String} html The HTML data with which paste event will be fired.
+ */
+export function pasteHtml( editor, html ) {
+	editor.editing.view.document.fire( 'paste', {
+		dataTransfer: createDataTransfer( { 'text/html': html } ),
+		preventDefault() {}
+	} );
+}
+
+/**
  * Mocks dataTransfer object which can be used for simulating paste.
  *
  * @param {Object} data Object containing "mime type - data" pairs.
@@ -37,16 +50,3 @@ export function createDataTransfer( data ) {
 		}
 	};
 }
-
-/**
- * Fires paste event on a given editor instance with a specific HTML data.
- *
- * @param {module:core/editor/editor~Editor} editor Editor instance on which paste event will be fired.
- * @param {String} html The HTML data with which paste event will be fired.
- */
-export function pasteHtml( editor, html ) {
-	editor.editing.view.document.fire( 'paste', {
-		dataTransfer: createDataTransfer( { 'text/html': html } ),
-		preventDefault() {}
-	} );
-}