Merge pull request #1413 from ckeditor/t/1408

Feature: Introduce `ElementDefinition#priority` property which allows specifying the priority of created element during the downcast conversion. Closes #1408.

src/conversion/conversion.js

@@ -164,7 +164,7 @@ export default class Conversion {
  * conversion.elementToElement( { model: 'paragraph', view: 'p' } );
  *
  * // Override other converters by specifying converter definition with higher priority.
- * conversion.elementToElement( { model: 'paragraph', view: 'div', priority: 'high' } );
+ * conversion.elementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
  *
  * // View specified as an object instead of a string.
  * conversion.elementToElement( {
@@ -237,7 +237,7 @@ export default class Conversion {
  upcastElementToElement( {
  model,
  view,
- priority: definition.priority
+ converterPriority: definition.converterPriority
  } )
  );
  }
@@ -251,7 +251,7 @@ export default class Conversion {
  * conversion.attributeToElement( { model: 'bold', view: 'strong' } );
  *
  * // Override other converters by specifying converter definition with higher priority.
- * conversion.attributeToElement( { model: 'bold', view: 'b', priority: 'high' } );
+ * conversion.attributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
  *
  * // View specified as an object instead of a string.
  * conversion.attributeToElement( {
@@ -579,7 +579,7 @@ export default class Conversion {
  * Any view element matching `upcastAlso` will also be converted to model. If `model` describes multiple values, `upcastAlso`
  * is an object that assigns those values (`upcastAlso` object keys) to {@link module:engine/view/matcher~MatcherPattern}s
  * (`upcastAlso` object values).
- * @property {module:utils/priorities~PriorityString} [priority] Conversion priority.
+ * @property {module:utils/priorities~PriorityString} [converterPriority] Converter priority.
  */
 
 // Helper function for `Conversion` `.add()` method.

src/conversion/downcast-converters.js

@@ -26,7 +26,7 @@ import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
  *
  * downcastElementToElement( { model: 'paragraph', view: 'p' } );
  *
- * downcastElementToElement( { model: 'paragraph', view: 'div', priority: 'high' } );
+ * downcastElementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
  *
  * downcastElementToElement( {
  * model: 'fancyParagraph',
@@ -55,7 +55,7 @@ export function downcastElementToElement( config ) {
  config.view = _normalizeToElementConfig( config.view, 'container' );
 
  return dispatcher => {
- dispatcher.on( 'insert:' + config.model, insertElement( config.view ), { priority: config.priority || 'normal' } );
+ dispatcher.on( 'insert:' + config.model, insertElement( config.view ), { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -67,7 +67,7 @@ export function downcastElementToElement( config ) {
  *
  * downcastAttributeToElement( { model: 'bold', view: 'strong' } );
  *
- * downcastAttributeToElement( { model: 'bold', view: 'b', priority: 'high' } );
+ * downcastAttributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
  *
  * downcastAttributeToElement( {
  * model: 'invert',
@@ -123,7 +123,7 @@ export function downcastElementToElement( config ) {
  * @param {module:engine/view/elementdefinition~ElementDefinition|Function|Object} config.view View element definition or a function
  * that takes model attribute value and view writer as parameters and returns a view attribute element. If `config.model.values` is
  * given, `config.view` should be an object assigning values from `config.model.values` to view element definitions or functions.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function downcastAttributeToElement( config ) {
@@ -147,7 +147,7 @@ export function downcastAttributeToElement( config ) {
  const elementCreator = _getFromAttributeCreator( config );
 
  return dispatcher => {
- dispatcher.on( eventName, wrap( elementCreator ), { priority: config.priority || 'normal' } );
+ dispatcher.on( eventName, wrap( elementCreator ), { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -159,7 +159,7 @@ export function downcastAttributeToElement( config ) {
  *
  * downcastAttributeToAttribute( { model: 'source', view: 'src' } );
  *
- * downcastAttributeToAttribute( { model: 'source', view: 'href', priority: 'high' } );
+ * downcastAttributeToAttribute( { model: 'source', view: 'href', converterPriority: 'high' } );
  *
  * downcastAttributeToAttribute( {
  * model: {
@@ -201,7 +201,7 @@ export function downcastAttributeToElement( config ) {
  * array of `String`s. If `key` is `'style'`, `value` is an object with key-value pairs. In other cases, `value` is a `String`.
  * If `config.model.values` is set, `config.view` should be an object assigning values from `config.model.values` to
  * `{ key, value }` objects or a functions.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function downcastAttributeToAttribute( config ) {
@@ -225,7 +225,7 @@ export function downcastAttributeToAttribute( config ) {
  const elementCreator = _getFromAttributeCreator( config );
 
  return dispatcher => {
- dispatcher.on( eventName, changeAttribute( elementCreator ), { priority: config.priority || 'normal' } );
+ dispatcher.on( eventName, changeAttribute( elementCreator ), { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -238,7 +238,7 @@ export function downcastAttributeToAttribute( config ) {
  *
  * downcastMarkerToElement( { model: 'search', view: 'marker-search' } );
  *
- * downcastMarkerToElement( { model: 'search', view: 'search-result', priority: 'high' } );
+ * downcastMarkerToElement( { model: 'search', view: 'search-result', converterPriority: 'high' } );
  *
  * downcastMarkerToElement( {
  * model: 'search',
@@ -272,7 +272,7 @@ export function downcastAttributeToAttribute( config ) {
  * @param {String} config.model Name of the model marker (or model marker group) to convert.
  * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view View element definition or a function
  * that takes model marker data as a parameter and returns view ui element.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function downcastMarkerToElement( config ) {
@@ -281,8 +281,8 @@ export function downcastMarkerToElement( config ) {
  config.view = _normalizeToElementConfig( config.view, 'ui' );
 
  return dispatcher => {
- dispatcher.on( 'addMarker:' + config.model, insertUIElement( config.view ), { priority: config.priority || 'normal' } );
- dispatcher.on( 'removeMarker:' + config.model, removeUIElement( config.view ), { priority: config.priority || 'normal' } );
+ dispatcher.on( 'addMarker:' + config.model, insertUIElement( config.view ), { priority: config.converterPriority || 'normal' } );
+ dispatcher.on( 'removeMarker:' + config.model, removeUIElement( config.view ), { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -307,7 +307,7 @@ export function downcastMarkerToElement( config ) {
  *
  * downcastMarkerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
  *
- * downcastMarkerToHighlight( { model: 'comment', view: { classes: 'new-comment' }, priority: 'high' } );
+ * downcastMarkerToHighlight( { model: 'comment', view: { classes: 'new-comment' }, converterPriority: 'high' } );
  *
  * downcastMarkerToHighlight( {
  * model: 'comment',
@@ -331,14 +331,14 @@ export function downcastMarkerToElement( config ) {
  * @param {String} config.model Name of the model marker (or model marker group) to convert.
  * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} config.view Highlight descriptor
  * which will be used for highlighting or a function that takes model marker data as a parameter and returns a highlight descriptor.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function downcastMarkerToHighlight( config ) {
  return dispatcher => {
- dispatcher.on( 'addMarker:' + config.model, highlightText( config.view ), { priority: config.priority || 'normal' } );
- dispatcher.on( 'addMarker:' + config.model, highlightElement( config.view ), { priority: config.priority || 'normal' } );
- dispatcher.on( 'removeMarker:' + config.model, removeHighlight( config.view ), { priority: config.priority || 'normal' } );
+ dispatcher.on( 'addMarker:' + config.model, highlightText( config.view ), { priority: config.converterPriority || 'normal' } );
+ dispatcher.on( 'addMarker:' + config.model, highlightElement( config.view ), { priority: config.converterPriority || 'normal' } );
+ dispatcher.on( 'removeMarker:' + config.model, removeHighlight( config.view ), { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -370,14 +370,19 @@ function _createViewElementFromDefinition( viewElementDefinition, viewWriter, vi
  }
 
  let element;
+ const attributes = Object.assign( {}, viewElementDefinition.attributes );
 
  if ( viewElementType == 'container' ) {
- element = viewWriter.createContainerElement( viewElementDefinition.name, Object.assign( {}, viewElementDefinition.attributes ) );
+ element = viewWriter.createContainerElement( viewElementDefinition.name, attributes );
  } else if ( viewElementType == 'attribute' ) {
- element = viewWriter.createAttributeElement( viewElementDefinition.name, Object.assign( {}, viewElementDefinition.attributes ) );
+ const options = {
+ priority: viewElementDefinition.priority || ViewAttributeElement.DEFAULT_PRIORITY
+ };
+
+ element = viewWriter.createAttributeElement( viewElementDefinition.name, attributes, options );
  } else {
  // 'ui'.
- element = viewWriter.createUIElement( viewElementDefinition.name, Object.assign( {}, viewElementDefinition.attributes ) );
+ element = viewWriter.createUIElement( viewElementDefinition.name, attributes );
  }
 
  if ( viewElementDefinition.styles ) {

src/conversion/upcast-converters.js

@@ -26,7 +26,7 @@ import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
  *
  * upcastElementToElement( { view: 'p', model: 'paragraph' } );
  *
- * upcastElementToElement( { view: 'p', model: 'paragraph', priority: 'high' } );
+ * upcastElementToElement( { view: 'p', model: 'paragraph', converterPriority: 'high' } );
  *
  * upcastElementToElement( {
  * view: {
@@ -52,7 +52,7 @@ import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
  * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
  * @param {String|module:engine/model/element~Element|Function} config.model Name of the model element, a model element
  * instance or a function that takes a view element and returns a model element. The model element will be inserted in the model.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function upcastElementToElement( config ) {
@@ -64,7 +64,7 @@ export function upcastElementToElement( config ) {
  const eventName = elementName ? 'element:' + elementName : 'element';
 
  return dispatcher => {
- dispatcher.on( eventName, converter, { priority: config.priority || 'normal' } );
+ dispatcher.on( eventName, converter, { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -78,7 +78,7 @@ export function upcastElementToElement( config ) {
  *
  * upcastElementToAttribute( { view: 'strong', model: 'bold' } );
  *
- * upcastElementToAttribute( { view: 'strong', model: 'bold', priority: 'high' } );
+ * upcastElementToAttribute( { view: 'strong', model: 'bold', converterPriority: 'high' } );
  *
  * upcastElementToAttribute( {
  * view: {
@@ -130,7 +130,7 @@ export function upcastElementToElement( config ) {
  * @param {String|Object} config.model Model attribute key or an object with `key` and `value` properties, describing
  * the model attribute. `value` property may be set as a function that takes a view element and returns the value.
  * If `String` is given, the model attribute value will be set to `true`.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function upcastElementToAttribute( config ) {
@@ -144,7 +144,7 @@ export function upcastElementToAttribute( config ) {
  const eventName = elementName ? 'element:' + elementName : 'element';
 
  return dispatcher => {
- dispatcher.on( eventName, converter, { priority: config.priority || 'normal' } );
+ dispatcher.on( eventName, converter, { priority: config.converterPriority || 'normal' } );
  };
 }
 
@@ -160,7 +160,7 @@ export function upcastElementToAttribute( config ) {
  *
  * upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source' } );
  *
- * upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source', priority: 'normal' } );
+ * upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source', converterPriority: 'normal' } );
  *
  * upcastAttributeToAttribute( {
  * view: {
@@ -209,7 +209,7 @@ export function upcastElementToAttribute( config ) {
  * @param {String|Object} config.model Model attribute key or an object with `key` and `value` properties, describing
  * the model attribute. `value` property may be set as a function that takes a view element and returns the value.
  * If `String` is given, the model attribute value will be same as view attribute value.
- * @param {module:utils/priorities~PriorityString} [config.priority='low'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='low'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function upcastAttributeToAttribute( config ) {
@@ -226,7 +226,7 @@ export function upcastAttributeToAttribute( config ) {
  const converter = _prepareToAttributeConverter( config );
 
  return dispatcher => {
- dispatcher.on( 'element', converter, { priority: config.priority || 'low' } );
+ dispatcher.on( 'element', converter, { priority: config.converterPriority || 'low' } );
  };
 }
 
@@ -240,7 +240,7 @@ export function upcastAttributeToAttribute( config ) {
  *
  * upcastElementToMarker( { view: 'marker-search', model: 'search' } );
  *
- * upcastElementToMarker( { view: 'marker-search', model: 'search', priority: 'high' } );
+ * upcastElementToMarker( { view: 'marker-search', model: 'search', converterPriority: 'high' } );
  *
  * upcastElementToMarker( {
  * view: 'marker-search',
@@ -263,7 +263,7 @@ export function upcastAttributeToAttribute( config ) {
  * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
  * @param {String|Function} config.model Name of the model marker, or a function that takes a view element and returns
  * a model marker name.
- * @param {module:utils/priorities~PriorityString} [config.priority='normal'] Converter priority.
+ * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
 export function upcastElementToMarker( config ) {

src/view/elementdefinition.jsdoc

@@ -55,4 +55,5 @@
  * Value under that key must be a string.
  * @property {Object} [attributes] Object with key-value pairs representing attributes. Each object key represents
  * attribute name. Value under that key must be a string.
+ * @property {Number} [priority] Element's {@link module:engine/view/attributeelement~AttributeElement#priority priority}.
  */

tests/conversion/conversion.js

@@ -125,9 +125,9 @@ describe( 'Conversion', () => {
  test( '<p>Foo</p>', '<paragraph>Foo</paragraph>' );
  } );
 
- it( 'config.priority is defined', () => {
+ it( 'config.converterPriority is defined', () => {
  conversion.elementToElement( { model: 'paragraph', view: 'p' } );
- conversion.elementToElement( { model: 'paragraph', view: 'div', priority: 'high' } );
+ conversion.elementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
 
  test( '<div>Foo</div>', '<paragraph>Foo</paragraph>' );
  test( '<p>Foo</p>', '<paragraph>Foo</paragraph>', '<div>Foo</div>' );
@@ -224,9 +224,9 @@ describe( 'Conversion', () => {
  test( '<p><strong>Foo</strong> bar</p>', '<paragraph><$text bold="true">Foo</$text> bar</paragraph>' );
  } );
 
- it( 'config.priority is defined', () => {
+ it( 'config.converterPriority is defined', () => {
  conversion.attributeToElement( { model: 'bold', view: 'strong' } );
- conversion.attributeToElement( { model: 'bold', view: 'b', priority: 'high' } );
+ conversion.attributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
 
  test( '<p><b>Foo</b></p>', '<paragraph><$text bold="true">Foo</$text></paragraph>' );
  test( '<p><strong>Foo</strong></p>', '<paragraph><$text bold="true">Foo</$text></paragraph>', '<p><b>Foo</b></p>' );