Merge pull request #845 from ckeditor/t/787

Feature: Introduced markers serialization. Closes #787. Closes #846.

BREAKING CHANGES: `BuildModelConverter#fromMarkerCollapsed` is removed. Use `BuildModelConverter#fromMarker` instead.

NOTE: `insertUIElement` model to view converter now supports collapsed and non-collapsed ranges.

Author: oskarwrobel

src/controller/datacontroller.js

@@ -224,10 +224,13 @@ export default class DataController {
 	}
 
 	/**
-	 * Returns the content of the given {@link module:engine/view/element~Element view element} or
+	 * Returns wrapped by {module:engine/model/documentfragment~DocumentFragment} result of the given
+	 * {@link module:engine/view/element~Element view element} or
 	 * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the
-	 * {@link #viewToModel view to model converters} to a
-	 * {@link module:engine/model/documentfragment~DocumentFragment model document fragment}.
+	 * {@link #viewToModel view to model converters}.
+	 *
+	 * When marker stamps were converted during conversion process then will be set as DocumentFragment
+	 * {@link module:engine/view/documentfragment~DocumentFragment#markers static markers map}.
 	 *
 	 * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment
 	 * Element or document fragment which content will be converted.
@@ -281,7 +284,7 @@ export default class DataController {
 	 * See {@link module:engine/controller/modifyselection~modifySelection}.
 	 *
 	 * @fires modifySelection
-	 * @param {module:engine/model/selection~Selection} The selection to modify.
+	 * @param {module:engine/model/selection~Selection} selection The selection to modify.
 	 * @param {Object} options See {@link module:engine/controller/modifyselection~modifySelection}'s options.
 	 */
 	modifySelection( selection, options ) {

src/conversion/buildmodelconverter.js

@@ -152,8 +152,7 @@ class ModelConverterBuilder {
 	}
 
 	/**
-	 * Registers what type of non-collapsed marker should be converted. For collapsed markers conversion, see
-	 * {@link #fromCollapsedMarker}.
+	 * Registers what type of marker should be converted.
 	 *
 	 * @chainable
 	 * @param {String} markerName Name of marker to convert.
@@ -163,27 +162,7 @@ class ModelConverterBuilder {
 		this._from = {
 			type: 'marker',
 			name: markerName,
-			priority: null,
-			collapsed: false
-		};
-
-		return this;
-	}
-
-	/**
-	 * Registers what type of collapsed marker should be converted. For non-collapsed markers conversion,
-	 * see {@link #fromMarker}.
-	 *
-	 * @chainable
-	 * @param {String} markerName Name of marker to convert.
-	 * @returns {module:engine/conversion/buildmodelconverter~ModelConverterBuilder}
-	 */
-	fromCollapsedMarker( markerName ) {
-		this._from = {
-			type: 'marker',
-			name: markerName,
-			priority: null,
-			collapsed: true
+			priority: null
 		};
 
 		return this;
@@ -265,22 +244,76 @@ class ModelConverterBuilder {
 
 				dispatcher.on( 'selectionAttribute:' + this._from.key, convertSelectionAttribute( element ), { priority } );
 			} else {
-				if ( this._from.collapsed ) {
-					// From collapsed marker to view element -> insertUIElement, removeUIElement.
-					element = typeof element == 'string' ? new ViewUIElement( element ) : element;
+				element = typeof element == 'string' ? new ViewAttributeElement( element ) : element;
 
-					dispatcher.on( 'addMarker:' + this._from.name, insertUIElement( element ), { priority } );
-					dispatcher.on( 'removeMarker:' + this._from.name, removeUIElement( element ), { priority } );
-				} else {
-					// From non-collapsed marker to view element -> wrapRange and unwrapRange.
-					element = typeof element == 'string' ? new ViewAttributeElement( element ) : element;
+				dispatcher.on( 'addMarker:' + this._from.name, wrapRange( element ), { priority } );
+				dispatcher.on( 'removeMarker:' + this._from.name, unwrapRange( element ), { priority } );
 
-					dispatcher.on( 'addMarker:' + this._from.name, wrapRange( element ), { priority } );
-					dispatcher.on( 'removeMarker:' + this._from.name, unwrapRange( element ), { priority } );
+				dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( element ), { priority } );
+			}
+		}
+	}
 
-					dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( element ), { priority } );
-				}
+	/**
+	 * Registers what view stamp will be created by converter to mark marker range bounds. Separate elements will be
+	 * created at the beginning and at the end of the range. If range is collapsed then only one element will be created.
+	 *
+	 * Method accepts various ways of providing how the view element will be created. You can pass view element name as
+	 * `string`, view element instance which will be cloned and used, or creator function which returns view element that
+	 * will be used. Keep in mind that when you provide view element instance or creator function, it has to be/return a
+	 * proper type of view element: {@link module:engine/view/uielement~UIElement UIElement}.
+	 *
+	 *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toStamp( 'span' );
+	 *
+	 *		buildModelConverter().for( dispatcher )
+	 *			.fromMarker( 'search' )
+	 *			.toStamp( new UIElement( 'span', { 'data-name': 'search' } ) );
+	 *
+	 *		buildModelConverter().for( dispatcher )
+	 *			.fromMarker( 'search' )
+	 *			.toStamp( ( data ) => new UIElement( 'span', { 'data-name': data.marker.getName() ) );
+	 *
+	 * Creator function provides additional `data.isOpening` parameter which defined if currently converted element is
+	 * a beginning or end of the marker range. This makes possible to create different opening and closing stamp.
+	 *
+	 *		buildModelConverter().for( dispatcher )
+	 *			.fromMarker( 'search' )
+	 *			.toStamp( ( data ) => {
+	 *				if ( data.isOpening ) {
+	 *					return new UIElement( 'span', { 'data-name': data.marker.getName(), 'data-start': true ) );
+	 *				}
+	 *
+	 *				return new UIElement( 'span', { 'data-name': data.marker.getName(), 'data-end': true ) );
+	 *			}
+	 *
+	 * Creator function provides
+	 * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#StampCreatorData} parameters.
+	 *
+	 * See how markers {module:engine/model/buildviewconverter~ViewConverterBuilder#toMarker view -> model serialization}
+	 * works to find out what view element format is the best for you.
+	 *
+	 * @param {String|module:engine/view/element~UIElement|Function} element UIElement created by converter or
+	 * a function that returns view element.
+	 */
+	toStamp( element ) {
+		for ( let dispatcher of this._dispatchers ) {
+			if ( this._from.type != 'marker' ) {
+				/**
+				 * To-stamp conversion is supported only for model markers.
+				 *
+				 * @error build-model-converter-element-to-stamp
+				 */
+				throw new CKEditorError(
+					'build-model-converter-non-marker-to-stamp: To-stamp conversion is supported only from model markers.'
+				);
 			}
+
+			const priority = this._from.priority === null ? 'normal' : this._from.priority;
+
+			element = typeof element == 'string' ? new ViewUIElement( element ) : element;
+
+			dispatcher.on( 'addMarker:' + this._from.name, insertUIElement( element ), { priority } );
+			dispatcher.on( 'removeMarker:' + this._from.name, removeUIElement( element ), { priority } );
 		}
 	}
 
@@ -321,7 +354,6 @@ class ModelConverterBuilder {
 			 * To-attribute conversion is supported only for model attributes.
 			 *
 			 * @error build-model-converter-element-to-attribute
-			 * @param {module:engine/model/range~Range} range
 			 */
 			throw new CKEditorError( 'build-model-converter-non-attribute-to-attribute: ' +
 				'To-attribute conversion is supported only from model attributes.' );
@@ -370,3 +402,13 @@ class ModelConverterBuilder {
 export default function buildModelConverter() {
 	return new ModelConverterBuilder();
 }
+
+/**
+ * @typedef {StampCreatorData} {module:engine/conversion/buildmodelconverter~ModelConverterBuilder#StampCreatorData}
+ * @param {Object} data Additional information about the change.
+ * @param {String} data.name Marker name.
+ * @param {module:engine/model/range~Range} data.range Marker range.
+ * @param {Boolean} data.isOpening Defines if currently converted element is a beginning or end of the marker range.
+ * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
+ * @param {Object} conversionApi Conversion interface to be used by callback, passed in `ModelConversionDispatcher` constructor.
+ */

src/conversion/buildviewconverter.js

@@ -11,6 +11,7 @@ import Matcher from '../view/matcher';
 import ModelElement from '../model/element';
 import ModelPosition from '../model/position';
 import modelWriter from '../model/writer';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
 
 /**
@@ -254,7 +255,7 @@ class ViewConverterBuilder {
 	 * @param {String|Function} element Model element name or model element creator function.
 	 */
 	toElement( element ) {
-		const eventCallbackGen = function( from ) {
+		function eventCallbackGen( from ) {
 			return ( evt, data, consumable, conversionApi ) => {
 				// There is one callback for all patterns in the matcher.
 				// This will be usually just one pattern but we support matchers with many patterns too.
@@ -301,7 +302,7 @@ class ViewConverterBuilder {
 					break;
 				}
 			};
-		};
+		}
 
 		this._setCallback( eventCallbackGen, 'normal' );
 	}
@@ -322,7 +323,7 @@ class ViewConverterBuilder {
 	 * @param {String} [value] Attribute value. Required if `keyOrCreator` is a `string`. Ignored otherwise.
 	 */
 	toAttribute( keyOrCreator, value ) {
-		const eventCallbackGen = function( from ) {
+		function eventCallbackGen( from ) {
 			return ( evt, data, consumable, conversionApi ) => {
 				// There is one callback for all patterns in the matcher.
 				// This will be usually just one pattern but we support matchers with many patterns too.
@@ -356,11 +357,91 @@ class ViewConverterBuilder {
 					break;
 				}
 			};
-		};
+		}
 
 		this._setCallback( eventCallbackGen, 'low' );
 	}
 
+	/**
+	 * Registers how model element marking marker range will be created by converter.
+	 *
+	 * Created element has to match the following pattern:
+	 *
+	 * 		{ name: '$marker', attribute: { data-name: /^\w/ } }
+	 *
+	 * There are two ways of creating this element:
+	 *
+	 * 1. Makes sure that converted view element will have property `data-name` then converter will
+	 * automatically take this property value. In this case there is no need to provide creator function.
+	 * For the following view:
+	 *
+	 *		<marker data-name="search"></marker>foo<marker data-name="search"></marker>
+	 *
+	 * converter should look like this:
+	 *
+	 *		buildViewConverter().for( dispatcher ).fromElement( 'marker' ).toMarker();
+	 *
+	 * 2. Creates element by creator:
+	 *
+	 * For the following view:
+	 *
+	 * 		<span foo="search"></span>foo<span foo="search"></span>
+	 *
+	 * converter should look like this:
+	 *
+	 * 		buildViewConverter().for( dispatcher ).from( { name: 'span', { attribute: foo: /^\w/ } } ).toMarker( ( data ) => {
+	 * 			return new Element( '$marker', { 'data-name': data.getAttribute( 'foo' ) } );
+	 * 		} );
+	 *
+	 * @param {Function} [creator] Creator function.
+	 */
+	toMarker( creator ) {
+		function eventCallbackGen( from ) {
+			return ( evt, data, consumable ) => {
+				// There is one callback for all patterns in the matcher.
+				// This will be usually just one pattern but we support matchers with many patterns too.
+				const matchAll = from.matcher.matchAll( data.input );
+
+				// If there is no match, this callback should not do anything.
+				if ( !matchAll ) {
+					return;
+				}
+
+				let modelElement;
+
+				// When creator is provided then create model element basing on creator function.
+				if ( creator instanceof Function ) {
+					modelElement = creator( data.input );
+				// When there is no creator then create model element basing on data from view element.
+				} else {
+					modelElement = new ModelElement( '$marker', { 'data-name': data.input.getAttribute( 'data-name' ) } );
+				}
+
+				// Check if model element is correct (has proper name and property).
+				if ( modelElement.name != '$marker' || typeof modelElement.getAttribute( 'data-name' ) != 'string' ) {
+					throw new CKEditorError(
+						'build-view-converter-invalid-marker: Invalid model element to mark marker range.'
+					);
+				}
+
+				// Now, for every match between matcher and actual element, we will try to consume the match.
+				for ( const match of matchAll ) {
+					// Try to consume appropriate values from consumable values list.
+					if ( !consumable.consume( data.input, from.consume || match.match ) ) {
+						continue;
+					}
+
+					data.output = modelElement;
+
+					// Prevent multiple conversion if there are other correct matches.
+					break;
+				}
+			};
+		}
+
+		this._setCallback( eventCallbackGen, 'normal' );
+	}
+
 	/**
 	 * Helper function that uses given callback generator to created callback function and sets it on registered dispatchers.
 	 *

src/conversion/model-to-view-converters.js

@@ -91,6 +91,8 @@ export function insertText() {
 /**
  * Function factory, creates a converter that converts marker adding change to the view ui element.
  * The view ui element that will be added to the view depends on passed parameter. See {@link ~insertElement}.
+ * In a case of collapsed range element will not wrap range but separate elements will be placed at the beginning
+ * and at the end of the range.
  *
  * **Note:** unlike {@link ~insertElement}, the converter does not bind view element to model, because this converter
  * uses marker as "model source of data". This means that view ui element does not have corresponding model element.
@@ -101,21 +103,34 @@ export function insertText() {
  */
 export function insertUIElement( elementCreator ) {
 	return ( evt, data, consumable, conversionApi ) => {
-		const viewElement = ( elementCreator instanceof ViewElement ) ?
-			elementCreator.clone( true ) :
-			elementCreator( data, consumable, conversionApi );
+		let viewStartElement, viewEndElement;
 
-		if ( !viewElement ) {
+		if ( elementCreator instanceof ViewElement ) {
+			viewStartElement = elementCreator.clone( true );
+			viewEndElement = elementCreator.clone( true );
+		} else {
+			data.isOpening = true;
+			viewStartElement = elementCreator( data, consumable, conversionApi );
+
+			data.isOpening = false;
+			viewEndElement = elementCreator( data, consumable, conversionApi );
+		}
+
+		if ( !viewStartElement || !viewEndElement ) {
 			return;
 		}
 
 		if ( !consumable.consume( data.range, 'addMarker' ) ) {
 			return;
 		}
 
-		const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
+		const mapper = conversionApi.mapper;
 
-		viewWriter.insert( viewPosition, viewElement );
+		viewWriter.insert( mapper.toViewPosition( data.range.start ), viewStartElement );
+
+		if ( !data.range.isCollapsed ) {
+			viewWriter.insert( mapper.toViewPosition( data.range.end ), viewEndElement );
+		}
 	};
 }
 
@@ -439,11 +454,20 @@ export function remove() {
  */
 export function removeUIElement( elementCreator ) {
 	return ( evt, data, consumable, conversionApi ) => {
-		const viewElement = ( elementCreator instanceof ViewElement ) ?
-			elementCreator.clone( true ) :
-			elementCreator( data, consumable, conversionApi );
+		let viewStartElement, viewEndElement;
 
-		if ( !viewElement ) {
+		if ( elementCreator instanceof ViewElement ) {
+			viewStartElement = elementCreator.clone( true );
+			viewEndElement = elementCreator.clone( true );
+		} else {
+			data.isOpening = true;
+			viewStartElement = elementCreator( data, consumable, conversionApi );
+
+			data.isOpening = false;
+			viewEndElement = elementCreator( data, consumable, conversionApi );
+		}
+
+		if ( !viewStartElement || !viewEndElement ) {
 			return;
 		}
 
@@ -453,7 +477,13 @@ export function removeUIElement( elementCreator ) {
 
 		const viewRange = conversionApi.mapper.toViewRange( data.range );
 
-		viewWriter.clear( viewRange.getEnlarged(), viewElement );
+		// First remove closing element.
+		viewWriter.clear( viewRange.getEnlarged(), viewEndElement );
+
+		// If closing and opening elements are not the same then remove opening element.
+		if ( !viewStartElement.isSimilar( viewEndElement ) ) {
+			viewWriter.clear( viewRange.getEnlarged(), viewStartElement );
+		}
 	};
 }