/** * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved. * For licensing, see LICENSE.md. */ /** * @module engine/model/document */ // Load all basic deltas and transformations, they register themselves, but they need to be imported somewhere. /* eslint-disable no-unused-vars */ import deltas from './delta/basic-deltas'; import transformations from './delta/basic-transformations'; /* eslint-enable no-unused-vars */ import Range from './range'; import Position from './position'; import RootElement from './rootelement'; import Batch from './batch'; import History from './history'; import LiveSelection from './liveselection'; import Schema from './schema'; import TreeWalker from './treewalker'; import MarkerCollection from './markercollection'; import clone from '@ckeditor/ckeditor5-utils/src/lib/lodash/clone'; import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin'; import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror'; import mix from '@ckeditor/ckeditor5-utils/src/mix'; import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckeditor5-utils/src/unicode'; const graveyardName = '$graveyard'; /** * Document tree model describes all editable data in the editor. It may contain multiple * {@link module:engine/model/document~Document#roots root elements}, for example if the editor have multiple editable areas, * each area will be represented by the separate root. * * All changes in the document are done by {@link module:engine/model/operation/operation~Operation operations}. To create operations in * a simple way, use the {@link module:engine/model/batch~Batch} API, for example: * * doc.batch().insert( position, nodes ).split( otherPosition ); * * @see module:engine/model/document~Document#batch * @mixes module:utils/emittermixin~EmitterMixin */ export default class Document { /** * Creates an empty document instance with no {@link #roots} (other than * the {@link #graveyard graveyard root}). */ constructor() { /** * Document version. It starts from `0` and every operation increases the version number. It is used to ensure that * operations are applied on the proper document version. * If the {@link module:engine/model/operation/operation~Operation#baseVersion} will not match document version the * {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown. * * @readonly * @member {Number} */ this.version = 0; /** * Schema for this document. * * @member {module:engine/model/schema~Schema} */ this.schema = new Schema(); /** * Document's history. * * **Note:** Be aware that deltas applied to the document might get removed or changed. * * @readonly * @member {module:engine/model/history~History} */ this.history = new History( this ); /** * Document's markers' collection. * * @readonly * @member {module:engine/model/markercollection~MarkerCollection} */ this.markers = new MarkerCollection(); /** * Selection done on this document. * * @readonly * @member {module:engine/model/liveselection~LiveSelection} */ this.selection = new LiveSelection( this ); /** * Array of pending changes. See: {@link #enqueueChanges}. * * @private * @member {Array.} */ this._pendingChanges = []; /** * List of roots that are owned and managed by this document. Use {@link #createRoot} and * {@link #getRoot} to manipulate it. * * @readonly * @member {Map} */ this.roots = new Map(); // Add events that will ensure selection correctness. this.selection.on( 'change:range', () => { for ( const range of this.selection.getRanges() ) { if ( !this._validateSelectionRange( range ) ) { /** * Range from document selection starts or ends at incorrect position. * * @error document-selection-wrong-position * @param {module:engine/model/range~Range} range */ throw new CKEditorError( 'document-selection-wrong-position: ' + 'Range from document selection starts or ends at incorrect position.', { range } ); } } } ); // Graveyard tree root. Document always have a graveyard root, which stores removed nodes. this.createRoot( '$root', graveyardName ); } /** * Graveyard tree root. Document always have a graveyard root, which stores removed nodes. * * @readonly * @member {module:engine/model/rootelement~RootElement} */ get graveyard() { return this.getRoot( graveyardName ); } /** * This is the entry point for all document changes. All changes on the document are done using * {@link module:engine/model/operation/operation~Operation operations}. To create operations in the simple way use the * {@link module:engine/model/batch~Batch} API available via {@link #batch} method. * * @fires event:change * @param {module:engine/model/operation/operation~Operation} operation Operation to be applied. */ applyOperation( operation ) { if ( operation.baseVersion !== this.version ) { /** * Only operations with matching versions can be applied. * * @error document-applyOperation-wrong-version * @param {module:engine/model/operation/operation~Operation} operation */ throw new CKEditorError( 'model-document-applyOperation-wrong-version: Only operations with matching versions can be applied.', { operation } ); } const changes = operation._execute(); this.version++; this.history.addDelta( operation.delta ); if ( changes ) { // `NoOperation` returns no changes, do not fire event for it. this.fire( 'change', operation.type, changes, operation.delta.batch, operation.delta.type ); } } /** * Creates a {@link module:engine/model/batch~Batch} instance which allows to change the document. * * @param {String} [type] Batch type. See {@link module:engine/model/batch~Batch#type}. * @returns {module:engine/model/batch~Batch} Batch instance. */ batch( type ) { return new Batch( this, type ); } /** * Creates a new top-level root. * * @param {String} [elementName='$root'] Element name. Defaults to `'$root'` which also have * some basic schema defined (`$block`s are allowed inside the `$root`). Make sure to define a proper * schema if you use a different name. * @param {String} [rootName='main'] Unique root name. * @returns {module:engine/model/rootelement~RootElement} Created root. */ createRoot( elementName = '$root', rootName = 'main' ) { if ( this.roots.has( rootName ) ) { /** * Root with specified name already exists. * * @error document-createRoot-name-exists * @param {module:engine/model/document~Document} doc * @param {String} name */ throw new CKEditorError( 'model-document-createRoot-name-exists: Root with specified name already exists.', { name: rootName } ); } const root = new RootElement( this, elementName, rootName ); this.roots.set( rootName, root ); return root; } /** * Removes all events listeners set by document instance. */ destroy() { this.selection.destroy(); this.stopListening(); } /** * Enqueues document changes. Any changes to be done on document (mostly using {@link #batch} * should be placed in the queued callback. If no other plugin is changing document at the moment, the callback will be * called immediately. Otherwise it will wait for all previously queued changes to finish happening. This way * queued callback will not interrupt other callbacks. * * When all queued changes are done {@link #event:changesDone} event is fired. * * @fires changesDone * @param {Function} callback Callback to enqueue. */ enqueueChanges( callback ) { this._pendingChanges.push( callback ); if ( this._pendingChanges.length == 1 ) { while ( this._pendingChanges.length ) { this._pendingChanges[ 0 ](); this._pendingChanges.shift(); } this.fire( 'changesDone' ); } } /** * Returns top-level root by its name. * * @param {String} [name='main'] Unique root name. * @returns {module:engine/model/rootelement~RootElement} Root registered under given name. */ getRoot( name = 'main' ) { if ( !this.roots.has( name ) ) { /** * Root with specified name does not exist. * * @error document-getRoot-root-not-exist * @param {String} name */ throw new CKEditorError( 'model-document-getRoot-root-not-exist: Root with specified name does not exist.', { name } ); } return this.roots.get( name ); } /** * Checks if root with given name is defined. * * @param {String} name Name of root to check. * @returns {Boolean} */ hasRoot( name ) { return this.roots.has( name ); } /** * Returns array with names of all roots (without the {@link #graveyard}) added to the document. * * @returns {Array.} Roots names. */ getRootNames() { return Array.from( this.roots.keys() ).filter( name => name != graveyardName ); } /** * Basing on given `position`, finds and returns a {@link module:engine/model/range~Range Range} instance that is * nearest to that `position` and is a correct range for selection. * * Correct selection range might be collapsed - when it's located in position where text node can be placed. * Non-collapsed range is returned when selection can be placed around element marked as "object" in * {@link module:engine/model/schema~Schema schema}. * * Direction of searching for nearest correct selection range can be specified as: * * `both` - searching will be performed in both ways, * * `forward` - searching will be performed only forward, * * `backward` - searching will be performed only backward. * * When valid selection range cannot be found, `null` is returned. * * @param {module:engine/model/position~Position} position Reference position where new selection range should be looked for. * @param {'both'|'forward'|'backward'} [direction='both'] Search direction. * @returns {module:engine/model/range~Range|null} Nearest selection range or `null` if one cannot be found. */ getNearestSelectionRange( position, direction = 'both' ) { // Return collapsed range if provided position is valid. if ( this.schema.check( { name: '$text', inside: position } ) ) { return new Range( position ); } let backwardWalker, forwardWalker; if ( direction == 'both' || direction == 'backward' ) { backwardWalker = new TreeWalker( { startPosition: position, direction: 'backward' } ); } if ( direction == 'both' || direction == 'forward' ) { forwardWalker = new TreeWalker( { startPosition: position } ); } for ( const data of combineWalkers( backwardWalker, forwardWalker ) ) { const type = ( data.walker == backwardWalker ? 'elementEnd' : 'elementStart' ); const value = data.value; if ( value.type == type && this.schema.objects.has( value.item.name ) ) { return Range.createOn( value.item ); } if ( this.schema.check( { name: '$text', inside: value.nextPosition } ) ) { return new Range( value.nextPosition ); } } return null; } /** * Custom toJSON method to solve child-parent circular dependencies. * * @returns {Object} Clone of this object with the document property changed to string. */ toJSON() { const json = clone( this ); // Due to circular references we need to remove parent reference. json.selection = '[engine.model.LiveSelection]'; return json; } /** * Returns default root for this document which is either the first root that was added to the the document using * {@link #createRoot} or the {@link #graveyard graveyard root} if no other roots were created. * * @protected * @returns {module:engine/model/rootelement~RootElement} The default root for this document. */ _getDefaultRoot() { for ( const root of this.roots.values() ) { if ( root !== this.graveyard ) { return root; } } return this.graveyard; } /** * Returns a default range for this selection. The default range is a collapsed range that starts and ends * at the beginning of this selection's document's {@link #_getDefaultRoot default root}. * * @protected * @returns {module:engine/model/range~Range} */ _getDefaultRange() { const defaultRoot = this._getDefaultRoot(); // Find the first position where the selection can be put. const position = new Position( defaultRoot, [ 0 ] ); const nearestRange = this.getNearestSelectionRange( position ); // If valid selection range is not found - return range collapsed at the beginning of the root. return nearestRange || new Range( position ); } /** * Checks whether given {@link module:engine/model/range~Range range} is a valid range for * {@link #selection document's selection}. * * @private * @param {module:engine/model/range~Range} range Range to check. * @returns {Boolean} `true` if `range` is valid, `false` otherwise. */ _validateSelectionRange( range ) { return validateTextNodePosition( range.start ) && validateTextNodePosition( range.end ); } /** * Fired when document changes by applying an operation. * * There are 5 types of change: * * * 'insert' when nodes are inserted, * * 'remove' when nodes are removed, * * 'reinsert' when remove is undone, * * 'move' when nodes are moved, * * 'addAttribute' when attributes are added, * * 'removeAttribute' when attributes are removed, * * 'changeAttribute' when attributes change, * * 'addRootAttribute' when attribute for root is added, * * 'removeRootAttribute' when attribute for root is removed, * * 'changeRootAttribute' when attribute for root changes. * * @event change * @param {String} type Change type, possible option: 'insert', 'remove', 'reinsert', 'move', 'attribute'. * @param {Object} data Additional information about the change. * @param {module:engine/model/range~Range} data.range Range in model containing changed nodes. Note that the range state is * after changes has been done, i.e. for 'remove' the range will be in the {@link #graveyard graveyard root}. * This is `undefined` for "...root..." types. * @param {module:engine/model/position~Position} [data.sourcePosition] Change source position. * Exists for 'remove', 'reinsert' and 'move'. * Note that this position state is before changes has been done, i.e. for 'reinsert' the source position will be in the * {@link #graveyard graveyard root}. * @param {String} [data.key] Only for attribute types. Key of changed / inserted / removed attribute. * @param {*} [data.oldValue] Only for 'removeAttribute', 'removeRootAttribute', 'changeAttribute' or * 'changeRootAttribute' type. * @param {*} [data.newValue] Only for 'addAttribute', 'addRootAttribute', 'changeAttribute' or * 'changeRootAttribute' type. * @param {module:engine/model/rootelement~RootElement} [changeInfo.root] Root element which attributes got changed. This is defined * only for root types. * @param {module:engine/model/batch~Batch} batch A {@link module:engine/model/batch~Batch batch} * of changes which this change is a part of. */ /** * Fired when all queued document changes are done. See {@link #enqueueChanges}. * * @event changesDone */ } mix( Document, EmitterMixin ); // Checks whether given range boundary position is valid for document selection, meaning that is not between // unicode surrogate pairs or base character and combining marks. function validateTextNodePosition( rangeBoundary ) { const textNode = rangeBoundary.textNode; if ( textNode ) { const data = textNode.data; const offset = rangeBoundary.offset - textNode.startOffset; return !isInsideSurrogatePair( data, offset ) && !isInsideCombinedSymbol( data, offset ); } return true; } // Generator function returning values from provided walkers, switching between them at each iteration. If only one walker // is provided it will return data only from that walker. // // @param {module:engine/module/treewalker~TreeWalker} [backward] Walker iterating in backward direction. // @param {module:engine/module/treewalker~TreeWalker} [forward] Walker iterating in forward direction. // @returns {Iterable.} Object returned at each iteration contains `value` and `walker` (informing which walker returned // given value) fields. function* combineWalkers( backward, forward ) { let done = false; while ( !done ) { done = true; if ( backward ) { const step = backward.next(); if ( !step.done ) { done = false; yield{ walker: backward, value: step.value }; } } if ( forward ) { const step = forward.next(); if ( !step.done ) { done = false; yield{ walker: forward, value: step.value }; } } } }