Skip to content
This repository has been archived by the owner on Jun 26, 2020. It is now read-only.

Commit

Permalink
Merge pull request #1091 from ckeditor/t/1085
Browse files Browse the repository at this point in the history 
Other: Renamed virtual selection to highlight. Closes #1085.
  • Loading branch information
Piotr Jasiun authored Aug 22, 2017
2 parents cb9d409 + 0168be4 commit 1955869
Show file tree
Hide file tree
Showing 11 changed files with 166 additions and 167 deletions.
75 changes: 37 additions & 38 deletions src/conversion/buildmodelconverter.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ import {
removeUIElement,
wrapItem,
unwrapItem,
convertTextsInsideMarker,
convertElementsInsideMarker
highlightText,
highlightElement
} from './model-to-view-converters';

import { convertSelectionAttribute, convertSelectionMarker } from './model-selection-to-view-converters';
Expand Down Expand Up @@ -58,11 +58,11 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
*
* buildModelConverter().for( dispatcher ).fromAttribute( 'bold' ).toElement( 'strong' );
*
* 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.
* 4. Model marker to view highlight converter. This is a converter that converts model markers to view highlight
* described by {@link module:engine/conversion/buildmodelconverter~HighlightDescriptor} object passed to
* {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toHighlight} method.
*
* buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toVirtualSelection( {
* buildModelConverter().for( dispatcher ).fromMarker( 'search' ).toHighlight( {
* class: 'search',
* priority: 20
* } );
Expand All @@ -76,7 +76,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
* It is possible to provide various different parameters for
* {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toElement},
* {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toAttribute} and
* {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toVirtualSelection} methods.
* {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#toHighlight} methods.
* See their descriptions to learn more.
*
* It is also possible to {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder#withPriority change default priority}
Expand Down Expand Up @@ -274,66 +274,65 @@ class ModelConverterBuilder {
}

/**
* 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
* Registers that marker should be converted to view highlight. Markers, basically,
* are {@link module:engine/model/liverange~LiveRange} instances, that are named. View highlight 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`
* range can handle highlighting individually by providing `addHighlight` and `removeHighlight`
* custom properties:
*
* viewElement.setCustomProperty( 'setVirtualSelection', ( element, descriptor ) => {} );
* viewElement.setCustomProperty( 'removeVirtualSelection', ( element, descriptor ) => {} );
* viewElement.setCustomProperty( 'addHighlight', ( element, descriptor ) => {} );
* viewElement.setCustomProperty( 'removeHighlight', ( element, descriptor ) => {} );
*
* {@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.
* {@link module:engine/conversion/buildmodelconverter~HighlightDescriptor} will be used to create
* spans over text nodes and also will be provided to `addHighlight` and `removeHighlight` methods
* each time highlight should be set or removed from view elements.
* NOTE: When `addHighlight` and `removeHighlight` custom properties are present, converter assumes
* that element itself is taking care of presenting highlight on its child nodes, so it won't convert them.
*
* Virtual selection descriptor can be provided as plain object:
* Highlight descriptor can be provided as plain object:
*
* buildModelConverter.for( dispatcher ).fromMarker( 'search' ).toVirtualSelection( { class: 'search-mark' } );
* buildModelConverter.for( dispatcher ).fromMarker( 'search' ).toHighlight( { class: 'search-highlight' } );
*
* Also, descriptor creator function can be provided:
*
* buildModelConverter.for( dispatcher ).fromMarker( 'search:blue' ).toVirtualSelection( data => {
* buildModelConverter.for( dispatcher ).fromMarker( 'search:blue' ).toHighlight( data => {
* const color = data.markerName.split( ':' )[ 1 ];
*
* return { class: 'search-' + color };
* } );
*
* Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
* `build-model-converter-non-marker-to-virtual-selection` when trying to convert not from marker.
* `build-model-converter-non-marker-to-highlight` when trying to convert not from marker.
*
* @param {function|module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor} selectionDescriptor
* @param {function|module:engine/conversion/buildmodelconverter~HighlightDescriptor} highlightDescriptor
*/
toVirtualSelection( selectionDescriptor ) {
toHighlight( highlightDescriptor ) {
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.
* To highlight conversion is supported only for model markers.
*
* @error build-model-converter-non-marker-to-virtual-selection
* @error build-model-converter-non-marker-to-highlight
*/
throw new CKEditorError(
'build-model-converter-non-marker-to-virtual-selection: Conversion to virtual selection is supported ' +
'build-model-converter-non-marker-to-highlight: Conversion to highlight 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 } );
dispatcher.on( 'addMarker:' + this._from.name, highlightText( highlightDescriptor ), { priority } );
dispatcher.on( 'addMarker:' + this._from.name, highlightElement( highlightDescriptor ), { priority } );

dispatcher.on( 'removeMarker:' + this._from.name, convertTextsInsideMarker( selectionDescriptor ), { priority } );
dispatcher.on( 'removeMarker:' + this._from.name, convertElementsInsideMarker( selectionDescriptor ), { priority } );
dispatcher.on( 'removeMarker:' + this._from.name, highlightText( highlightDescriptor ), { priority } );
dispatcher.on( 'removeMarker:' + this._from.name, highlightElement( highlightDescriptor ), { priority } );

dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( selectionDescriptor ), { priority } );
dispatcher.on( 'selectionMarker:' + this._from.name, convertSelectionMarker( highlightDescriptor ), { priority } );
}
}

Expand Down Expand Up @@ -434,16 +433,16 @@ export default function buildModelConverter() {
*/

/**
* @typedef VirtualSelectionDescriptor
* Object describing how virtual selection should be created in the view. Each text node in virtual selection
* @typedef HighlightDescriptor
* Object describing how content highlight should be created in the view. Each text node contained in highlight
* 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
* can handle displaying highlight separately by providing `addHighlight` and `removeHighlight` 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.
* {@link module:engine/view/attributeelement~AttributeElement} wrapping each text node in the highlighted content.
* @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.
* wrapping each text node in the highlighted content. 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.
* {@link module:engine/view/attributeelement~AttributeElement} wrapping each text node it the highlighted content.
*/
16 changes: 8 additions & 8 deletions src/conversion/model-selection-to-view-converters.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
import ViewElement from '../view/element';
import ViewRange from '../view/range';
import viewWriter from '../view/writer';
import { virtualSelectionDescriptorToAttributeElement } from './model-to-view-converters';
import { highlightDescriptorToAttributeElement } from './model-to-view-converters';

/**
* Contains {@link module:engine/model/selection~Selection model selection} to
Expand Down Expand Up @@ -162,21 +162,21 @@ export function convertSelectionAttribute( elementCreator ) {
* modelDispatcher.on( 'selectionMarker:searchResult', convertSelectionMarker( { class: 'search' } ) );
*
* @see module:engine/conversion/model-selection-to-view-converters~convertSelectionAttribute
* @param {module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor|Function} selectionDescriptor Virtual
* selection descriptor object or function returning a descriptor object.
* @param {module:engine/conversion/buildmodelconverter~HighlightDescriptor|Function} highlightDescriptor Highlight
* descriptor object or function returning a descriptor object.
* @returns {Function} Selection converter.
*/
export function convertSelectionMarker( selectionDescriptor ) {
export function convertSelectionMarker( highlightDescriptor ) {
return ( evt, data, consumable, conversionApi ) => {
const descriptor = typeof selectionDescriptor == 'function' ?
selectionDescriptor( data, consumable, conversionApi ) :
selectionDescriptor;
const descriptor = typeof highlightDescriptor == 'function' ?
highlightDescriptor( data, consumable, conversionApi ) :
highlightDescriptor;

if ( !descriptor ) {
return;
}

const viewElement = virtualSelectionDescriptorToAttributeElement( descriptor );
const viewElement = highlightDescriptorToAttributeElement( descriptor );
const consumableName = 'selectionMarker:' + data.markerName;

wrapCollapsedSelectionPosition( data.selection, conversionApi.viewSelection, viewElement, consumable, consumableName );
Expand Down
48 changes: 24 additions & 24 deletions src/conversion/model-to-view-converters.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -407,16 +407,16 @@ export function remove() {
/**
* Function factory, creates converter that converts all texts inside marker's range. Converter wraps each text with
* {@link module:engine/view/attributeelement~AttributeElement} created from provided descriptor.
* See {link module:engine/conversion/model-to-view-converters~virtualSelectionDescriptorToAttributeElement}.
* See {link module:engine/conversion/model-to-view-converters~highlightDescriptorToAttributeElement}.
*
* @param {module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor|Function} selectionDescriptor
* @param {module:engine/conversion/buildmodelconverter~HighlightDescriptor|Function} highlightDescriptor
* @return {Function}
*/
export function convertTextsInsideMarker( selectionDescriptor ) {
export function highlightText( highlightDescriptor ) {
return ( evt, data, consumable, conversionApi ) => {
const descriptor = typeof selectionDescriptor == 'function' ?
selectionDescriptor( data, consumable, conversionApi ) :
selectionDescriptor;
const descriptor = typeof highlightDescriptor == 'function' ?
highlightDescriptor( data, consumable, conversionApi ) :
highlightDescriptor;

const modelItem = data.item;

Expand All @@ -428,7 +428,7 @@ export function convertTextsInsideMarker( selectionDescriptor ) {
return;
}

const viewElement = virtualSelectionDescriptorToAttributeElement( descriptor );
const viewElement = highlightDescriptorToAttributeElement( descriptor );
const viewRange = conversionApi.mapper.toViewRange( data.range );

if ( evt.name.split( ':' )[ 0 ] == 'addMarker' ) {
Expand All @@ -441,23 +441,23 @@ export function convertTextsInsideMarker( selectionDescriptor ) {

/**
* Function factory, creates converter that converts all elements inside marker's range. Converter checks if element has
* functions stored under `setVirtualSelection` and `removeVirtualSelection` custom properties and calls them passing
* {@link module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor}. In such case converter will consume
* all element's children, assuming that they were handled by element itself. If selection descriptor will not provide
* functions stored under `addHighlight` and `removeHighlight` custom properties and calls them passing
* {@link module:engine/conversion/buildmodelconverter~HighlightDescriptor}. In such case converter will consume
* all element's children, assuming that they were handled by element itself. If highlight descriptor will not provide
* priority, priority 10 will be used as default, to be compliant with
* {@link module:engine/conversion/model-to-view-converters~convertTextsInsideMarker} method which uses default priority of
* {@link module:engine/conversion/model-to-view-converters~highlightText} method which uses default priority of
* {@link module:engine/view/attributeelement~AttributeElement}.
* When `setVirtualSelection` and `removeVirtualSelection` custom properties are not present, element is not converted
* When `addHighlight` and `removeHighlight` custom properties are not present, element is not converted
* in any special way. This means that converters will proceed to convert element's child nodes.
*
* @param {module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor|Function} selectionDescriptor
* @param {module:engine/conversion/buildmodelconverter~HighlightDescriptor|Function} highlightDescriptor
* @return {Function}
*/
export function convertElementsInsideMarker( selectionDescriptor ) {
export function highlightElement( highlightDescriptor ) {
return ( evt, data, consumable, conversionApi ) => {
const descriptor = typeof selectionDescriptor == 'function' ?
selectionDescriptor( data, consumable, conversionApi ) :
selectionDescriptor;
const descriptor = typeof highlightDescriptor == 'function' ?
highlightDescriptor( data, consumable, conversionApi ) :
highlightDescriptor;

const modelItem = data.item;

Expand All @@ -475,9 +475,9 @@ export function convertElementsInsideMarker( selectionDescriptor ) {

const viewElement = conversionApi.mapper.toViewElement( modelItem );
const addMarker = evt.name.split( ':' )[ 0 ] == 'addMarker';
const selectionHandlingMethod = addMarker ? 'setVirtualSelection' : 'removeVirtualSelection';
const highlightHandlingMethod = addMarker ? 'addHighlight' : 'removeHighlight';

if ( viewElement && viewElement.getCustomProperty( selectionHandlingMethod ) ) {
if ( viewElement && viewElement.getCustomProperty( highlightHandlingMethod ) ) {
// Consume element itself.
consumable.consume( data.item, evt.name );

Expand All @@ -486,7 +486,7 @@ export function convertElementsInsideMarker( selectionDescriptor ) {
consumable.consume( value.item, evt.name );
}

viewElement.getCustomProperty( selectionHandlingMethod )( viewElement, descriptor );
viewElement.getCustomProperty( highlightHandlingMethod )( viewElement, descriptor );
}
};
}
Expand Down Expand Up @@ -559,13 +559,13 @@ export function eventNameToConsumableType( evtName ) {

/**
* Creates `span` {@link module:engine/view/attributeelement~AttributeElement view attribute element} from information
* provided by {@link module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor} object. If priority
* is not provided in selection descriptor - default priority will be used.
* provided by {@link module:engine/conversion/buildmodelconverter~HighlightDescriptor} object. If priority
* is not provided in descriptor - default priority will be used.
*
* @param {module:engine/conversion/buildmodelconverter~VirtualSelectionDescriptor } descriptor
* @param {module:engine/conversion/buildmodelconverter~HighlightDescriptor } descriptor
* @return {module:engine/view/attributeelement~AttributeElement}
*/
export function virtualSelectionDescriptorToAttributeElement( descriptor ) {
export function highlightDescriptorToAttributeElement( descriptor ) {
const attributeElement = new ViewAttributeElement( 'span', descriptor.attributes );

if ( descriptor.class ) {
Expand Down
Loading

0 comments on commit 1955869

Please sign in to comment.