浏览代码

Add documentation to restricted editing mode conversion helpers.

Maciej Gołaszewski 6 年之前
父节点
当前提交
492617844a

+ 35 - 7
packages/ckeditor5-restricted-editing/src/restrictededitingmode/converters.js

@@ -8,7 +8,7 @@
  */
 
 import Matcher from '@ckeditor/ckeditor5-engine/src/view/matcher';
-import { getMarker } from './utils';
+import { getMarkerAtPosition } from './utils';
 
 const HIGHLIGHT_CLASS = 'ck-restricted-editing-exception_selected';
 
@@ -23,6 +23,8 @@ const HIGHLIGHT_CLASS = 'ck-restricted-editing-exception_selected';
  * * The class is added in the view post fixer, after other changes in the model tree were converted to the view.
  *
  * This way, adding and removing the highlight does not interfere with conversion.
+ *
+ * @param {module:core/editor/editor~Editor} editor
  */
 export function setupExceptionHighlighting( editor ) {
 	const view = editor.editing.view;
@@ -33,7 +35,7 @@ export function setupExceptionHighlighting( editor ) {
 	view.document.registerPostFixer( writer => {
 		const modelSelection = model.document.selection;
 
-		const marker = getMarker( editor, modelSelection.anchor );
+		const marker = getMarkerAtPosition( editor, modelSelection.anchor );
 
 		if ( !marker ) {
 			return;
@@ -64,7 +66,14 @@ export function setupExceptionHighlighting( editor ) {
 	} );
 }
 
-export function resurrectCollapsedMarker( editor ) {
+/**
+ * A post-fixer that prevents removing collapsed marker from the document.
+ *
+ * @param {module:core/editor/editor~Editor} editor
+ * @returns {Function}
+ */
+export function resurrectCollapsedMarkerPostFixer( editor ) {
+	// This post-fixer shouldn't be necessary after https://github.com/ckeditor/ckeditor5/issues/5778.
 	return writer => {
 		let changeApplied = false;
 
@@ -82,14 +91,21 @@ export function resurrectCollapsedMarker( editor ) {
 	};
 }
 
-export function extendMarkerWhenTypingOnMarkerBoundary( editor ) {
+/**
+ * A post-fixer that extends a marker when user types on it boundaries.
+ *
+ * @param {module:core/editor/editor~Editor} editor
+ * @returns {Function}
+ */
+export function extendMarkerOnTypingPostFixer( editor ) {
+	// This post-fixer shouldn't be necessary after https://github.com/ckeditor/ckeditor5/issues/5778.
 	return writer => {
 		let changeApplied = false;
 
 		for ( const change of editor.model.document.differ.getChanges() ) {
 			if ( change.type == 'insert' && change.name == '$text' && change.length === 1 ) {
-				changeApplied = _tryExtendMarkedEnd( editor, change.position, writer ) || changeApplied;
 				changeApplied = _tryExtendMarkerStart( editor, change.position, writer ) || changeApplied;
+				changeApplied = _tryExtendMarkedEnd( editor, change.position, writer ) || changeApplied;
 			}
 		}
 
@@ -97,6 +113,16 @@ export function extendMarkerWhenTypingOnMarkerBoundary( editor ) {
 	};
 }
 
+/**
+ * A view highlight to marker conversion helper.
+ *
+ * @param {Object} config Conversion configuration.
+ * @param {module:engine/view/matcher~MatcherPattern} [config.view] Pattern matching all view elements which should be converted. If not
+ * set, the converter will fire for every view element.
+ * @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.converterPriority='normal'] Converter priority.
+ */
 export function upcastHighlightToMarker( config ) {
 	return dispatcher => dispatcher.on( 'element:span', ( evt, data, conversionApi ) => {
 		const { writer } = conversionApi;
@@ -133,8 +159,9 @@ export function upcastHighlightToMarker( config ) {
 	} );
 }
 
+// Extend marker if typing detected on marker's start position.
 function _tryExtendMarkerStart( editor, position, writer ) {
-	const markerAtStart = getMarker( editor, position.getShiftedBy( 1 ) );
+	const markerAtStart = getMarkerAtPosition( editor, position.getShiftedBy( 1 ) );
 
 	if ( markerAtStart && markerAtStart.getStart().isEqual( position.getShiftedBy( 1 ) ) ) {
 		writer.updateMarker( markerAtStart, {
@@ -147,8 +174,9 @@ function _tryExtendMarkerStart( editor, position, writer ) {
 	return false;
 }
 
+// Extend marker if typing detected on marker's end position.
 function _tryExtendMarkedEnd( editor, position, writer ) {
-	const markerAtEnd = getMarker( editor, position );
+	const markerAtEnd = getMarkerAtPosition( editor, position );
 
 	if ( markerAtEnd && markerAtEnd.getEnd().isEqual( position ) ) {
 		writer.updateMarker( markerAtEnd, {

+ 33 - 5
packages/ckeditor5-restricted-editing/src/restrictededitingmode/utils.js

@@ -7,11 +7,20 @@
  * @module restricted-editing/restrictededitingmode/utils
  */
 
-export function getMarker( editor, position ) {
+/**
+ * Returns a single "restricted-editing-exception" marker at a given position. Contrary to
+ * {@link module:engine/model/markercollection~MarkerCollection#getMarkersAtPosition} it return a marker also when the postion is equal
+ * to one of markers start or end positions.
+ *
+ * @param {module:core/editor/editor~Editor} editor
+ * @param {module:engine/model/position~Position} position
+ * @returns {module:engine/model/markercollection~Marker|undefined} marker
+ */
+export function getMarkerAtPosition( editor, position ) {
 	for ( const marker of editor.model.markers ) {
 		const markerRange = marker.getRange();
 
-		if ( isPositionInRangeOrOnRangeBoundary( markerRange, position ) ) {
+		if ( isPositionInRangeBoundaries( markerRange, position ) ) {
 			if ( marker.name.startsWith( 'restricted-editing-exception:' ) ) {
 				return marker;
 			}
@@ -19,7 +28,14 @@ export function getMarker( editor, position ) {
 	}
 }
 
-export function isPositionInRangeOrOnRangeBoundary( range, position ) {
+/**
+ * Checks if the position is fully contained in range. Positions equal to range start or end are considered "in".
+ *
+ * @param {module:engine/model/range~Range} range
+ * @param {module:engine/model/position~Position} position
+ * @returns {Boolean}
+ */
+export function isPositionInRangeBoundaries( range, position ) {
 	return (
 		range.containsPosition( position ) ||
 		range.end.isEqual( position ) ||
@@ -27,7 +43,19 @@ export function isPositionInRangeOrOnRangeBoundary( range, position ) {
 	);
 }
 
-export function isSelectionInExceptionMarker( marker, selection ) {
+/**
+ * Checks if the selection is fully contained in marker. Positions on marker boundaries are considered "in".
+ *
+ *		<marker>[]foo</marker> -> true
+ *		<marker>f[oo]</marker> -> true
+ *		<marker>f[oo</marker> ba]r -> false
+ *		<marker>foo</marker> []bar -> false
+ *
+ * @param {module:engine/model/selection~Selection} selection
+ * @param {module:engine/model/markercollection~Marker} marker
+ * @returns {Boolean}
+ */
+export function isSelectionInMarker( selection, marker ) {
 	if ( !marker ) {
 		return false;
 	}
@@ -35,7 +63,7 @@ export function isSelectionInExceptionMarker( marker, selection ) {
 	const markerRange = marker.getRange();
 
 	if ( selection.isCollapsed ) {
-		return isPositionInRangeOrOnRangeBoundary( markerRange, selection.focus );
+		return isPositionInRangeBoundaries( markerRange, selection.focus );
 	}
 
 	return markerRange.containsRange( selection.getFirstRange(), true );

+ 11 - 11
packages/ckeditor5-restricted-editing/src/restrictededitingmodeediting.js

@@ -10,12 +10,12 @@
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import RestrictedEditingNavigationCommand from './restrictededitingmodenavigationcommand';
 import {
-	extendMarkerWhenTypingOnMarkerBoundary,
-	resurrectCollapsedMarker,
+	extendMarkerOnTypingPostFixer,
+	resurrectCollapsedMarkerPostFixer,
 	setupExceptionHighlighting,
 	upcastHighlightToMarker
 } from './restrictededitingmode/converters';
-import { getMarker, isSelectionInExceptionMarker } from './restrictededitingmode/utils';
+import { getMarkerAtPosition, isSelectionInMarker } from './restrictededitingmode/utils';
 
 /**
  * The Restricted Editing Mode editing feature.
@@ -49,6 +49,8 @@ export default class RestrictedEditingModeEditing extends Plugin {
 	 */
 	init() {
 		const editor = this.editor;
+		const model = editor.model;
+		const doc = model.document;
 
 		// Commands that allow navigation in the content.
 		editor.commands.add( 'goToPreviousRestrictedEditingRegion', new RestrictedEditingNavigationCommand( editor, 'backward' ) );
@@ -99,8 +101,8 @@ export default class RestrictedEditingModeEditing extends Plugin {
 			} )
 		} );
 
-		editor.model.document.registerPostFixer( extendMarkerWhenTypingOnMarkerBoundary( editor ) );
-		editor.model.document.registerPostFixer( resurrectCollapsedMarker( editor ) );
+		doc.registerPostFixer( extendMarkerOnTypingPostFixer( editor ) );
+		doc.registerPostFixer( resurrectCollapsedMarkerPostFixer( editor ) );
 
 		const getCommandExecuter = commandName => {
 			return ( data, cancel ) => {
@@ -120,10 +122,8 @@ export default class RestrictedEditingModeEditing extends Plugin {
 		setupExceptionHighlighting( editor );
 		this._disableCommands( editor );
 
-		const selection = editor.model.document.selection;
-
-		this.listenTo( selection, 'change', this._checkCommands.bind( this ) );
-		this.listenTo( editor.model.document, 'change:data', this._checkCommands.bind( this ) );
+		this.listenTo( doc.selection, 'change', this._checkCommands.bind( this ) );
+		this.listenTo( doc, 'change:data', this._checkCommands.bind( this ) );
 
 		// Block clipboard completely in restricted mode.
 		this.listenTo( editor.editing.view.document, 'clipboardInput', evt => {
@@ -141,9 +141,9 @@ export default class RestrictedEditingModeEditing extends Plugin {
 			return;
 		}
 
-		const marker = getMarker( editor, selection.focus );
+		const marker = getMarkerAtPosition( editor, selection.focus );
 
-		if ( isSelectionInExceptionMarker( marker, selection ) ) {
+		if ( isSelectionInMarker( selection, marker ) ) {
 			this._enableCommands( marker );
 		} else {
 			this._disableCommands();