Forráskód Böngészése

Docs: Update configuration defined converters docs and method names.

Maciej Gołaszewski 8 éve
szülő
commit
eee580d0e0

+ 171 - 14
packages/ckeditor5-engine/src/conversion/configurationdefinedconverters.js

@@ -11,14 +11,40 @@ import AttributeElement from '../view/attributeelement';
 import ViewContainerElement from '../view/containerelement';
 
 import buildModelConverter from './buildmodelconverter';
+import buildViewConverter from './buildviewconverter';
 
 /**
- * Helper for creating model to view converter from model's element.
+ * Helper for creating model to view converter from model's element
+ * to {@link module:engine/view/containerelement~ContainerElement ViewContainerElement}. The `acceptAlso` property is ignored.
+ *
+ * You can define conversion as simple model element to view element conversion using simplified definition:
+ *
+ *		modelElementToViewContainerElement( {
+ *			model: 'heading1',
+ *			view: 'h1',
+ *		}, [ dispatcher ] );
+ *
+ * Or defining full-flavored view object:
+ *
+ *		modelElementToViewContainerElement( {
+ *			model: 'heading1',
+ *			view: {
+ *				name: 'h1',
+ *				class: [ 'header', 'article-header' ],
+ *				attributes: {
+ *					data-header: 'level-1',
+ *				}
+ *			},
+ *		}, [ dispatcher ] );
+ *
+ * Above will generate an HTML tag:
+ *
+ *		<h1 class="header article-header" data-header="level-1">...</h1>
  *
  * @param {module:engine/conversion/configurationdefinedconverters~ConverterDefinition} definition A conversion configuration.
  * @param {Array.<module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher>} dispatchers
  */
-export function containerElementToView( definition, dispatchers ) {
+export function modelElementToViewContainerElement( definition, dispatchers ) {
 	const { model: modelElement, viewDefinition } = parseConverterDefinition( definition );
 
 	buildModelConverter()
@@ -28,11 +54,59 @@ export function containerElementToView( definition, dispatchers ) {
 }
 
 /**
+ * Helper for creating view to model converter from view to model element. It will convert also all matched view elements defined in
+ * `acceptAlso` property. The `model` property is used as model element name.
+ *
+ * Conversion from model to view might be defined as simple one to one conversion:
+ *
+ *		viewToModelElement( { model: 'heading1', view: 'h1' }, [ dispatcher ] );
+ *
+ * As a full-flavored definition:
+ *
+ *		viewToModelElement( {
+ *			model: 'heading1',
+ *			view: {
+ *				name: 'p',
+ *				attributes: {
+ *					'data-heading': 'true'
+ *				},
+ *				// it might require to define higher priority for elements matched by other features
+ *				priority: 'high'
+ *			}
+  *		}, [ dispatcher ] );
+ *
+ * or with `acceptAlso` property to match many elements:
+ *
+ *		viewToModelElement( {
+ *			model: 'heading1',
+ *			view: {
+ *				name: 'h1'
+ *			},
+ *			acceptAlso: [
+ *				{ name: 'p', attributes: { 'data-heading': 'level1' }, priority: 'high' },
+ *				{ name: 'h2', class: 'heading-main' },
+ *				{ name: 'div', style: { 'font-weight': 'bold', font-size: '24px' } }
+ *			]
+ *		}, [ dispatcher ] );
+ *
+ *    Above example will convert such existing HTML content:
+ *
+ *		<h1>A heading</h1>
+ *		<h2 class="heading-main">Another heading</h2>
+ *		<p data-heading="level1">Paragraph-like heading</p>
+ *		<div style="font-size:24px; font-weigh:bold;">Another non-semantic header</div>
+ *
+ * into `heading1` model element so after rendering it the output HTML will be cleaned up:
+ *
+ *		<h1>A heading</h1>
+ *		<h1>Another heading</h1>
+ *		<h1>Paragraph-like heading</h1>
+ *		<h1>Another non-semantic header</h1>
  *
  * @param {module:engine/conversion/configurationdefinedconverters~ConverterDefinition} definition A conversion configuration.
  * @param {Array.<module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher>} dispatchers
  */
-export function viewToContainerElement( definition, dispatchers ) {
+export function viewToModelElement( definition, dispatchers ) {
 	const { model: modelElement, viewDefinitions } = parseConverterDefinition( definition );
 
 	const converter = prepareViewConverter( dispatchers, viewDefinitions );
@@ -41,13 +115,37 @@ export function viewToContainerElement( definition, dispatchers ) {
 }
 
 /**
- * Helper for creating model to view converter from model's attribute.
+ * Helper for creating model to view converter from model's attribute
+ * to {@link module:engine/view/attributeelement~AttributeElement AttributeElement}. The `acceptAlso` property is ignored.
+ *
+ * You can define conversion as simple model element to view element conversion using simplified definition:
  *
- * @param {String} attributeName
+ *		modelAttributeToViewAttributeElement( 'bold', {
+ *			model: 'true',
+ *			view: 'strong',
+ *		}, [ dispatcher ] );
+ *
+ * Or defining full-flavored view object:
+ *
+ *		modelAttributeToViewAttributeElement( 'fontSize' {
+ *			model: 'big',
+ *			view: {
+ *				name: 'span',
+ *				styles: {
+ *					'font-size': '1.2em'
+ *				}
+ *			},
+ *		}, [ dispatcher ] );
+ *
+ * Above will generate an HTML tag for model's attribute `fontSize` with a `big` value set:
+ *
+ *		<span style="font-size:1.2em;">...</span>
+ *
+ * @param {String} attributeName Attribute name from which convert.
  * @param {module:engine/conversion/configurationdefinedconverters~ConverterDefinition} definition A conversion configuration.
  * @param {Array.<module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher>} dispatchers
  */
-export function attributeElementToViewConverter( attributeName, definition, dispatchers ) {
+export function modelAttributeToViewAttributeElement( attributeName, definition, dispatchers ) {
 	const { model: attributeValue, viewDefinition } = parseConverterDefinition( definition );
 
 	buildModelConverter()
@@ -63,12 +161,63 @@ export function attributeElementToViewConverter( attributeName, definition, disp
 }
 
 /**
+ * Helper for creating view to model converter from view to model attribute. It will convert also all matched view elements defined in
+ * `acceptAlso` property. The `model` property is used as model's attribute value to match.
+ *
+ * Conversion from model to view might be defined as simple one to one conversion:
+ *
+ *		viewToModelAttribute( 'bold', { model: true, view: 'strong' }, [ dispatcher ] );
+ *
+ * As a full-flavored definition:
+ *
+ *		viewToModelAttribute( 'fontSize', {
+ *			model: 'big',
+ *			view: {
+ *				name: 'span',
+ *				style: {
+ *					'font-size': '1.2em'
+ *				}
+ *			}
+  *		}, [ dispatcher ] );
  *
- * @param attributeName
+ * or with `acceptAlso` property to match many elements:
+ *
+ *		viewToModelAttribute( 'fontSize', {
+ *			model: 'big',
+ *			view: {
+ *				name: 'span',
+ *				class: 'text-big'
+ *			},
+ *			acceptAlso: [
+ *				{ name: 'span', attributes: { 'data-size': 'big' } },
+ *				{ name: 'span', class: [ 'font', 'font-huge' ] },
+ *				{ name: 'span', style: { font-size: '18px' } }
+ *			]
+ *		}, [ dispatcher ] );
+ *
+ *    Above example will convert such existing HTML content:
+ *
+ *		<p>An example text with some big elements:
+ *			<span class="text-big>one</span>,
+ *			<span data-size="big>two</span>,
+ *			<span class="font font-huge>three</span>,
+ *			<span style="font-size:18px>four</span>
+ *		<p>
+ *
+ * into `fontSize` model attribute with 'big' value set so after rendering it the output HTML will be cleaned up:
+ *
+ *		<p>An example text with some big elements:
+ *			<span class="text-big>one</span>,
+ *			<span class="text-big>two</span>,
+ *			<span class="text-big>three</span>,
+ *			<span class="text-big>four</span>
+ *		<p>
+ *
+ * @param {String} attributeName Attribute name to which convert.
  * @param {module:engine/conversion/configurationdefinedconverters~ConverterDefinition} definition A conversion configuration.
  * @param {Array.<module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher>} dispatchers
  */
-export function viewToAttributeElementConverter( attributeName, definition, dispatchers ) {
+export function viewToModelAttribute( attributeName, definition, dispatchers ) {
 	const { model: attributeValue, viewDefinitions } = parseConverterDefinition( definition );
 
 	const converter = prepareViewConverter( dispatchers, viewDefinitions );
@@ -79,8 +228,6 @@ export function viewToAttributeElementConverter( attributeName, definition, disp
 	} ) );
 }
 
-import buildViewConverter from './buildviewconverter';
-
 // Prepares a {@link module:engine/conversion/configurationdefinedconverters~ConverterDefinition definition object} for building converters.
 //
 // @param {module:engine/conversion/configurationdefinedconverters~ConverterDefinition} definition An object that defines view to model
@@ -146,8 +293,18 @@ function definitionToPattern( viewDefinition ) {
 }
 
 /**
- * @typedef {Object} ConvertedDefinition
- * @property {String} model
- * @property {String|module:engine/view/viewelementdefinition~ViewElementDefinition} view
- * @property {Array.<module:engine/view/viewelementdefinition~ViewElementDefinition>} acceptAlso
+ * Defines conversion details.
+ *
+ * @typedef {Object} ConverterDefinition
+ * @property {String} model Defines to model conversion. When using to element conversion
+ * ({@link module:engine/conversion/configurationdefinedconverters~viewToModelElement}
+ * and {@link module:engine/conversion/configurationdefinedconverters~modelElementToViewContainerElement})
+ * it defines element name. When using to attribute conversion
+ * ({@link module:engine/conversion/configurationdefinedconverters~viewToModelAttribute}
+ * and {@link module:engine/conversion/configurationdefinedconverters~modelAttributeToViewAttributeElement})
+ * it defines attribute value to which it is converted.
+ * @property {String|module:engine/view/viewelementdefinition~ViewElementDefinition} view Defines model to view conversion and is also used
+ * in view to model conversion pipeline.
+ * @property {Array.<module:engine/view/viewelementdefinition~ViewElementDefinition>} acceptAlso An array with all matched elements that
+ * view to model conversion should also accepts.
  */

+ 1 - 1
packages/ckeditor5-engine/src/view/viewelementdefinition.jsdoc

@@ -12,7 +12,7 @@
  *
  * @typedef {Object} module:engine/view/viewelementdefinition~ViewElementDefinition
  *
- * @property {String} name View element attribute name.
+ * @property {String} name View element name.
  * @property {String|Array.<String>} [classes] Class name or array of class names to match. Each name can be
  * provided in a form of string.
  * @property {Object} [styles] Object with key-value pairs representing styles to match. Each object key

+ 28 - 27
packages/ckeditor5-engine/tests/conversion/configurationdefinedconverters.js

@@ -20,10 +20,10 @@ import { insertText, remove } from '../../src/conversion/model-to-view-converter
 import { convertText } from '../../src/conversion/view-to-model-converters';
 
 import {
-	attributeElementToViewConverter,
-	viewToAttributeElementConverter,
-	containerElementToView,
-	viewToContainerElement
+	modelAttributeToViewAttributeElement,
+	viewToModelAttribute,
+	modelElementToViewContainerElement,
+	viewToModelElement
 } from '../../src/conversion/configurationdefinedconverters';
 
 import ViewConversionDispatcher from '../../src/conversion/viewconversiondispatcher';
@@ -124,9 +124,9 @@ describe( 'Configuration defined converters', () => {
 		viewDoc.destroy();
 	} );
 
-	describe( 'Attribute converter', () => {
+	describe( 'Attribute converters', () => {
 		function testConversion( definition, expectedConversion ) {
-			attributeElementToViewConverter( 'foo', definition, [ dispatcher ] );
+			modelAttributeToViewAttributeElement( 'foo', definition, [ dispatcher ] );
 
 			const modelElement = new ModelText( 'foo', { foo: 'bar' } );
 			modelRoot.appendChildren( modelElement );
@@ -177,7 +177,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should do nothing for undefined value', () => {
-				attributeElementToViewConverter( 'foo', { model: 'bar', view: 'strong' }, [ dispatcher ] );
+				modelAttributeToViewAttributeElement( 'foo', { model: 'bar', view: 'strong' }, [ dispatcher ] );
 
 				const modelElement = new ModelText( 'foo', { foo: 'baz' } );
 				modelRoot.appendChildren( modelElement );
@@ -211,7 +211,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', { model: 'bar', view: 'strong' }, [ dispatcher ] );
+				viewToModelAttribute( 'foo', { model: 'bar', view: 'strong' }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewAttributeElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData
@@ -221,7 +221,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', { model: 'bar', view: { name: 'strong' } }, [ dispatcher ] );
+				viewToModelAttribute( 'foo', { model: 'bar', view: { name: 'strong' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewAttributeElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData
@@ -231,7 +231,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', { model: 'bar', view: { name: 'span', classes: 'foo' } }, [ dispatcher ] );
+				viewToModelAttribute( 'foo', { model: 'bar', view: { name: 'span', classes: 'foo' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewAttributeElement( 'span', { class: 'foo' }, new ViewText( 'foo' ) ), batch, additionalData
@@ -241,7 +241,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', {
+				viewToModelAttribute( 'foo', {
 					model: 'bar',
 					view: { name: 'span', classes: [ 'foo', 'bar' ] }
 				}, [ dispatcher ] );
@@ -254,7 +254,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', {
+				viewToModelAttribute( 'foo', {
 					model: 'bar',
 					view: { name: 'span', styles: { 'font-weight': 'bold' } }
 				}, [ dispatcher ] );
@@ -267,7 +267,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', {
+				viewToModelAttribute( 'foo', {
 					model: 'bar',
 					view: { name: 'span', attributes: { 'data-foo': 'bar' } }
 				}, [ dispatcher ] );
@@ -280,7 +280,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', {
+				viewToModelAttribute( 'foo', {
 					model: 'bar',
 					view: 'strong',
 					acceptsAlso: [
@@ -297,8 +297,8 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToAttributeElementConverter( 'foo', { model: 'baz', view: 'strong' }, [ dispatcher ] );
-				viewToAttributeElementConverter( 'foo', { model: 'bar', view: { name: 'strong', priority: 'high' } }, [ dispatcher ] );
+				viewToModelAttribute( 'foo', { model: 'baz', view: 'strong' }, [ dispatcher ] );
+				viewToModelAttribute( 'foo', { model: 'bar', view: { name: 'strong', priority: 'high' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewAttributeElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData
@@ -309,9 +309,9 @@ describe( 'Configuration defined converters', () => {
 		} );
 	} );
 
-	describe( 'Element converter', () => {
+	describe( 'Element converters', () => {
 		function testModelConversion( definition, expectedResult ) {
-			containerElementToView( definition, [ dispatcher ] );
+			modelElementToViewContainerElement( definition, [ dispatcher ] );
 
 			const modelElement = new ModelElement( 'foo', null, new ModelText( 'bar' ) );
 			modelRoot.appendChildren( modelElement );
@@ -380,8 +380,9 @@ describe( 'Configuration defined converters', () => {
 				dispatcher.on( 'text', convertText() );
 			} );
 
+			// TODO:
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: 'strong' }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: 'strong' }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData
@@ -391,7 +392,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: { name: 'strong' } }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'strong' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData
@@ -401,7 +402,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: { name: 'span', classes: 'foo' } }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'span', classes: 'foo' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'span', { class: 'foo' }, new ViewText( 'foo' ) ), batch, additionalData
@@ -411,7 +412,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: { name: 'span', classes: [ 'foo', 'bar' ] } }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'span', classes: [ 'foo', 'bar' ] } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'span', { class: 'foo bar' }, new ViewText( 'foo' ) ), batch, additionalData
@@ -421,7 +422,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: { name: 'span', styles: { 'font-weight': 'bold' } } }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'span', styles: { 'font-weight': 'bold' } } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'span', { style: 'font-weight:bold' }, new ViewText( 'foo' ) ), batch, additionalData
@@ -431,7 +432,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'bar', view: { name: 'span', attributes: { 'data-foo': 'bar' } } }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'span', attributes: { 'data-foo': 'bar' } } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'span', { 'data-foo': 'bar' }, new ViewText( 'foo' ) ), batch, additionalData
@@ -441,7 +442,7 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( {
+				viewToModelElement( {
 					model: 'bar',
 					view: 'strong',
 					acceptsAlso: [
@@ -458,8 +459,8 @@ describe( 'Configuration defined converters', () => {
 			} );
 
 			it( 'should convert from view element to model attribute', () => {
-				viewToContainerElement( { model: 'baz', view: 'strong' }, [ dispatcher ] );
-				viewToContainerElement( { model: 'bar', view: { name: 'strong', priority: 'high' } }, [ dispatcher ] );
+				viewToModelElement( { model: 'baz', view: 'strong' }, [ dispatcher ] );
+				viewToModelElement( { model: 'bar', view: { name: 'strong', priority: 'high' } }, [ dispatcher ] );
 
 				const conversionResult = dispatcher.convert(
 					new ViewElement( 'strong', null, new ViewText( 'foo' ) ), batch, additionalData