Merge pull request #1040 from ckeditor/t/1015

Feature: Introduce Virtual selection feature.
BREAKING CHANGE: ModelConverterBuilder#toStamp() functionality is renamed to ModelConverterBuilder#toElement. Introduced ModelConverterBuilder#toVirtualSelection which replaces current marker to element conversion.
BREAKING CHANGE: Parameter change for convertSelectionMarker() function from model-selection-to-view-converters.js.
BREAKING CHANGE: Removed wrapRange() and unwrapRange() functions from model-to-view-converters.js as they're no longer used.
BREAKING CHANGE: Renamed marker stamps to marker elements in code and docs.

Author: Piotr Jasiun

package.json

@@ -19,6 +19,7 @@
     "@ckeditor/ckeditor5-paragraph": "^0.8.0",
     "@ckeditor/ckeditor5-typing": "^0.9.1",
     "@ckeditor/ckeditor5-undo": "^0.8.1",
+    "@ckeditor/ckeditor5-widget": "^0.1.1",
     "eslint-config-ckeditor5": "^1.0.5",
     "gulp": "^3.9.1",
     "guppy-pre-commit": "^0.4.0"

src/controller/datacontroller.js

@@ -225,7 +225,7 @@ export default class DataController {
 	 * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the
 	 * {@link #viewToModel view to model converters}.
 	 *
-	 * When marker stamps were converted during conversion process then will be set as DocumentFragment's
+	 * When marker elements were converted during conversion process then will be set as DocumentFragment's
 	 * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
 	 *
 	 * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment

src/conversion/buildmodelconverter.js

@@ -15,8 +15,8 @@ import {
 	removeUIElement,
 	wrapItem,
 	unwrapItem,
-	wrapRange,
-	unwrapRange
+	convertTextsInsideMarker,
+	convertElementsInsideMarker
 } from './model-to-view-converters';
 
 import { convertSelectionAttribute, convertSelectionMarker } from './model-selection-to-view-converters';
@@ -37,7 +37,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  * {@link module:engine/conversion/model-to-view-converters}, {@link module:engine/conversion/modelconsumable~ModelConsumable},
  * {@link module:engine/conversion/mapper~Mapper}.
  *
- * Using this API it is possible to create four kinds of converters:
+ * Using this API it is possible to create five kinds of converters:
  *
  * 1. Model element to view element converter. This is a converter that takes the model element and represents it
  * in the view.
@@ -58,17 +58,25 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *
  *		buildModelConverter().for( dispatcher ).fromAttribute( 'bold' ).toElement( 'strong' );
  *
- * 4. Model marker to view element converter. This is a converter that converts markers from given group to view attribute element.
- * Markers, basically, are {@link module:engine/model/liverange~LiveRange} instances, that are named. In this conversion, model range is
- * converted to view range, then that view range is wrapped (or unwrapped, if range is removed) in a view attribute element.
- * To learn more about markers, see {@link module:engine/model/markercollection~MarkerCollection}.
+ * 4. Model marker to virtual selection converter. This is a converter that converts model markers to virtual
+ * selection described by {@link module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor} object passed to
+ * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toVirtualSelection} method.
  *
- *		const viewSpanSearchResult = new ViewAttributeElement( 'span', { class: 'search-result' } );
- *		buildModelConverter().for( dispatcher ).fromMarker( 'searchResult' ).toElement( viewSpanSearchResult );
+ *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toVirtualSelection( {
+ *			class: 'search',
+ *			priority: 20
+ *		} );
+ *
+ * 5. Model marker to element converter. This is a converter that takes model marker and creates separate elements at
+ * the beginning and at the end of the marker's range. For more information see
+ * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toElement} method.
+ *
+ *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toElement( 'span' );
  *
  * It is possible to provide various different parameters for
- * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toElement}
- * and {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toAttribute} methods.
+ * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toElement},
+ * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toAttribute} and
+ * {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toVirtualSelection} methods.
  * See their descriptions to learn more.
  *
  * It is also possible to {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#withPriority change default priority}
@@ -198,7 +206,13 @@ class ModelConverterBuilder {
 	 * `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 view element instance or creator function, it has to be/return a
 	 * proper type of view element: {@link module:engine/view/containerelement~ContainerElement ViewContainerElement} if you convert
-	 * from element or {@link module:engine/view/attributeelement~AttributeElement ViewAttributeElement} if you convert from attribute.
+	 * from element, {@link module:engine/view/attributeelement~AttributeElement ViewAttributeElement} if you convert
+	 * from attribute and {@link module:engine/view/uielement~UIElement ViewUIElement} if you convert from marker.
+	 *
+	 * NOTE: When converting from model's marker, separate elements will be created at the beginning and at the end of the
+	 * marker's range. If range is collapsed then only one element will be created. 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.
 	 *
 	 *		buildModelConverter().for( dispatcher ).fromElement( 'paragraph' ).toElement( 'p' );
 	 *
@@ -210,12 +224,17 @@ class ModelConverterBuilder {
 	 *
 	 *		buildModelConverter().for( dispatcher ).fromAttribute( 'bold' ).toElement( new ViewAttributeElement( 'strong' ) );
 	 *
+	 *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toElement( 'span' );
+	 *
+	 *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toElement( new ViewUIElement( 'span' ) );
+	 *
 	 * Creator function will be passed different values depending whether conversion is from element or from attribute:
 	 *
 	 * * from element: dispatcher's
 	 * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:insert insert event}
 	 * parameters will be passed,
-	 * * from attribute: there is one parameter and it is attribute value.
+	 * * from attribute: there is one parameter and it is attribute value,
+	 * * from marker: {@link module:engine/conversion/buildmodelconverter~MarkerViewElementCreatorData}.
 	 *
 	 * This method also registers model selection to view selection converter, if conversion is from attribute.
 	 *
@@ -243,77 +262,78 @@ class ModelConverterBuilder {
 				dispatcher.on( 'removeAttribute:' + this._from.key, unwrapItem( element ), { priority } );
 
 				dispatcher.on( 'selectionAttribute:' + this._from.key, convertSelectionAttribute( element ), { priority } );
-			} else {
-				element = typeof element == 'string' ? new ViewAttributeElement( element ) : element;
+			} else { // From marker to element.
+				const priority = this._from.priority === null ? 'normal' : this._from.priority;
 
-				dispatcher.on( 'addMarker:' + this._from.name, wrapRange( element ), { priority } );
-				dispatcher.on( 'removeMarker:' + this._from.name, unwrapRange( element ), { priority } );
+				element = typeof element == 'string' ? new ViewUIElement( element ) : element;
 
-				dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( element ), { priority } );
+				dispatcher.on( 'addMarker:' + this._from.name, insertUIElement( element ), { priority } );
+				dispatcher.on( 'removeMarker:' + this._from.name, removeUIElement( 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.
+	 * Registers that marker should be converted to virtual selection. Markers, basically,
+	 * are {@link module:engine/model/liverange~LiveRange} instances, that are named. Virtual selection is
+	 * a representation of the model marker in the view:
+	 * * each {@link module:engine/view/text~Text view text node} in the marker's range will be wrapped with `span`
+	 * {@link module:engine/view/attributeelement~AttributeElement},
+	 * * each {@link module:engine/view/containerelement~ContainerElement container view element} in the marker's
+	 * range can handle the virtual selection individually by providing `setVirtualSelection` and `removeVirtualSelection`
+	 * custom properties:
 	 *
-	 * 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}.
+	 *		viewElement.setCustomProperty( 'setVirtualSelection', ( element, descriptor ) => {} );
+	 *		viewElement.setCustomProperty( 'removeVirtualSelection', ( element, descriptor ) => {} );
 	 *
-	 *		buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toStamp( 'span' );
+	 * {@link module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor Descriptor} will be used to create
+	 * spans over text nodes and also will be provided to `setVirtualSelection` and `removeVirtualSelection` methods
+	 * each time virtual selection should be set or removed from view elements.
+	 * NOTE: When `setVirtualSelection` and `removeVirtualSelection` custom properties are present, converter assumes
+	 * that element itself is taking care of presenting virtual selection on its child nodes, so it won't convert virtual
+	 * selection on them.
 	 *
-	 *		buildModelConverter().for( dispatcher )
-	 *			.fromMarker( 'search' )
-	 *			.toStamp( new UIElement( 'span', { 'data-name': 'search' } ) );
+	 * Virtual selection descriptor can be provided as plain object:
 	 *
-	 *		buildModelConverter().for( dispatcher )
-	 *			.fromMarker( 'search' )
-	 *			.toStamp( ( data ) => new UIElement( 'span', { 'data-name': data.name ) );
-	 *
-	 * 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.name, 'data-start': true ) );
-	 *				}
+	 *		buildModelConverter.for( dispatcher ).fromMarker( 'search' ).toVirtualSelection( { class: 'search-mark' } );
+ 	 *
+	 * Also, descriptor creator function can be provided:
 	 *
-	 *				return new UIElement( 'span', { 'data-name': data.name, 'data-end': true ) );
-	 *			}
+	 *		buildModelConverter.for( dispatcher ).fromMarker( 'search:blue' ).toVirtualSelection( data => {
+	 *			const color = data.markerName.split( ':' )[ 1 ];
 	 *
-	 * Creator function provides
-	 * {@link module:engine/conversion/buildmodelconverter~StampCreatorData} parameters.
+	 *			return { class: 'search-' + color };
+	 *		} );
 	 *
-	 * 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.
+	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+	 * `build-model-converter-non-marker-to-virtual-selection` when trying to convert not from marker.
 	 *
-	 * @param {String|module:engine/view/uielement~UIElement|Function} element UIElement created by converter or
-	 * a function that returns view element.
+	 * @param {function|module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor} selectionDescriptor
 	 */
-	toStamp( element ) {
-		for ( const 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.'
-				);
-			}
+	toVirtualSelection( selectionDescriptor ) {
+		const priority = this._from.priority === null ? 'normal' : this._from.priority;
 
-			const priority = this._from.priority === null ? 'normal' : this._from.priority;
+		if ( this._from.type != 'marker' ) {
+			/**
+			 * To virtual selection conversion is supported only for model markers.
+			 *
+			 * @error build-model-converter-non-marker-to-virtual-selection
+			 */
+			throw new CKEditorError(
+				'build-model-converter-non-marker-to-virtual-selection: Conversion to virtual selection is supported ' +
+				'only from model markers.'
+			);
+		}
+
+		for ( const dispatcher of this._dispatchers ) {
+			// Separate converters for converting texts and elements inside marker's range.
+			dispatcher.on( 'addMarker:' + this._from.name, convertTextsInsideMarker( selectionDescriptor ), { priority } );
+			dispatcher.on( 'addMarker:' + this._from.name, convertElementsInsideMarker( selectionDescriptor ), { priority } );
 
-			element = typeof element == 'string' ? new ViewUIElement( element ) : element;
+			dispatcher.on( 'removeMarker:' + this._from.name, convertTextsInsideMarker( selectionDescriptor ), { priority } );
+			dispatcher.on( 'removeMarker:' + this._from.name, convertElementsInsideMarker( selectionDescriptor ), { priority } );
 
-			dispatcher.on( 'addMarker:' + this._from.name, insertUIElement( element ), { priority } );
-			dispatcher.on( 'removeMarker:' + this._from.name, removeUIElement( element ), { priority } );
+			dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( selectionDescriptor ), { priority } );
 		}
 	}
 
@@ -404,11 +424,26 @@ export default function buildModelConverter() {
 }
 
 /**
- * @typedef StampCreatorData
+ * @typedef MarkerViewElementCreatorData
  * @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 {String} data.markerName Marker name.
+ * @param {module:engine/model/range~Range} data.markerRange 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.
  */
+
+/**
+ * @typedef VirtualSelectionDescriptor
+ * Object describing how virtual selection should be created in the view. Each text node in virtual selection
+ * will be wrapped with `span` element with CSS class, attributes and priority described by this object. Each element
+ * can handle virtual selection separately by providing `setVirtualSelection` and `removeVirtualSelection` custom
+ * properties.
+ *
+ * @property {String} class CSS class that will be added to `span`
+ * {@link module:engine/view/attributeelement~AttributeElement} wrapping each text node in the virtual selection.
+ * @property {Number} [priority] {@link module:engine/view/attributeelement~AttributeElement#priority} of the `span`
+ * wrapping each text node in the virtual selection. If not provided, default 10 priority will be used.
+ * @property {Object} [attributes] Attributes that will be added to `span`
+ * {@link module:engine/view/attributeelement~AttributeElement} wrapping each text node it the virtual selection.
+ */

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

@@ -6,6 +6,7 @@
 import ViewElement from '../view/element';
 import ViewRange from '../view/range';
 import viewWriter from '../view/writer';
+import { virtualSelectionDescriptorToAttributeElement } from './model-to-view-converters';
 
 /**
  * Contains {@link module:engine/model/selection~Selection model selection} to
@@ -112,11 +113,6 @@ export function convertCollapsedSelection() {
  *			}
  *		}
  *		modelDispatcher.on( 'selectionAttribute:style', convertSelectionAttribute( styleCreator ) );
- *
- * **Note:** You can use the same `elementCreator` function for this converter factory
- * and {@link module:engine/conversion/model-to-view-converters~wrapRange}
- * model to view converter, as long as the `elementCreator` function uses only the first parameter (attribute value).
- *
  *		modelDispatcher.on( 'selection', convertCollapsedSelection() );
  *		modelDispatcher.on( 'selectionAttribute:italic', convertSelectionAttribute( new ViewAttributeElement( 'em' ) ) );
  *		modelDispatcher.on( 'selectionAttribute:bold', convertSelectionAttribute( new ViewAttributeElement( 'strong' ) ) );
@@ -163,27 +159,25 @@ export function convertSelectionAttribute( elementCreator ) {
  * Performs similar conversion as {@link ~convertSelectionAttribute}, but depends on a marker name of a marker in which
  * collapsed selection is placed.
  *
- *		modelDispatcher.on( 'selectionMarker:searchResult', wrapRange( new ViewAttributeElement( 'span', { class: 'searchResult' } ) ) );
- *
- * **Note:** You can use the same `elementCreator` function for this converter factory
- * and {@link module:engine/conversion/model-to-view-converters~wrapRange}.
+ *		modelDispatcher.on( 'selectionMarker:searchResult', convertSelectionMarker( { class: 'search' } ) );
  *
  * @see module:engine/conversion/model-selection-to-view-converters~convertSelectionAttribute
- * @param {module:engine/view/attributeelement~AttributeElement|Function} elementCreator View element,
- * or function returning a view element, which will be used for wrapping.
+ * @param {module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor|Function} selectionDescriptor Virtual
+ * selection descriptor object or function returning a descriptor object.
  * @returns {Function} Selection converter.
  */
-export function convertSelectionMarker( elementCreator ) {
+export function convertSelectionMarker( selectionDescriptor ) {
 	return ( evt, data, consumable, conversionApi ) => {
-		const viewElement = elementCreator instanceof ViewElement ?
-			elementCreator.clone( true ) :
-			elementCreator( data, consumable, conversionApi );
+		const descriptor = typeof selectionDescriptor == 'function' ?
+			selectionDescriptor( data, consumable, conversionApi ) :
+			selectionDescriptor;
 
-		if ( !viewElement ) {
+		if ( !descriptor ) {
 			return;
 		}
 
-		const consumableName = 'selectionMarker:' + data.name;
+		const viewElement = virtualSelectionDescriptorToAttributeElement( descriptor );
+		const consumableName = 'selectionMarker:' + data.markerName;
 
 		wrapCollapsedSelectionPosition( data.selection, conversionApi.viewSelection, viewElement, consumable, consumableName );
 	};