8
0

document.js 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. 'use strict';
  6. import RootElement from './rootelement.js';
  7. import Batch from './batch.js';
  8. import Selection from './selection.js';
  9. import EmitterMixin from '../emittermixin.js';
  10. import CKEditorError from '../ckeditorerror.js';
  11. import utils from '../utils.js';
  12. const graveyardSymbol = Symbol( 'graveyard' );
  13. /**
  14. * Document tree model describes all editable data in the editor. It may contain multiple {@link #roots root elements},
  15. * for example if the editor have multiple editable areas, each area will be represented by the separate root.
  16. *
  17. * All changes in the document are done by {@link treeModel.operation.Operation operations}. To create operations in
  18. * the simple way use use the {@link treeModel.Batch} API, for example:
  19. *
  20. * doc.batch().insert( position, nodes ).split( otherPosition );
  21. *
  22. * @see #batch
  23. *
  24. * @class treeModel.Document
  25. */
  26. export default class Document {
  27. /**
  28. * Creates an empty document instance with no {@link #roots} (other than graveyard).
  29. *
  30. * @constructor
  31. */
  32. constructor() {
  33. /**
  34. * List of roots that are owned and managed by this document.
  35. *
  36. * @readonly
  37. * @property {Map} roots
  38. */
  39. this.roots = new Map();
  40. /**
  41. * Document version. It starts from `0` and every operation increases the version number. It is used to ensure that
  42. * operations are applied on the proper document version. If the {@link treeModel.operation.Operation#baseVersion} will
  43. * not match document version the {@link document-applyOperation-wrong-version} error is thrown.
  44. *
  45. * @readonly
  46. * @property {Number} version
  47. */
  48. this.version = 0;
  49. // Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
  50. this.createRoot( graveyardSymbol );
  51. /**
  52. * Array of pending changes. See: {@link #enqueueChanges}.
  53. *
  54. * @private
  55. * @property {Array.<Function>}
  56. */
  57. this._pendingChanges = [];
  58. /**
  59. * Selection done on this document.
  60. *
  61. * @readonly
  62. * @property {treeModel.Selection}
  63. */
  64. this.selection = new Selection();
  65. }
  66. /**
  67. * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
  68. *
  69. * @readonly
  70. * @property {treeModel.RootElement} graveyard
  71. */
  72. get graveyard() {
  73. return this.getRoot( graveyardSymbol );
  74. }
  75. /**
  76. * This is the entry point for all document changes. All changes on the document are done using
  77. * {@link treeModel.operation.Operation operations}. To create operations in the simple way use the
  78. * {@link treeModel.Batch} API available via {@link #batch} method.
  79. *
  80. * This method calls {@link #change} event.
  81. *
  82. * @param {treeModel.operation.Operation} operation Operation to be applied.
  83. */
  84. applyOperation( operation ) {
  85. if ( operation.baseVersion !== this.version ) {
  86. /**
  87. * Only operations with matching versions can be applied.
  88. *
  89. * @error document-applyOperation-wrong-version
  90. * @param {treeModel.operation.Operation} operation
  91. */
  92. throw new CKEditorError(
  93. 'document-applyOperation-wrong-version: Only operations with matching versions can be applied.',
  94. { operation: operation } );
  95. }
  96. let changes = operation._execute();
  97. this.version++;
  98. const batch = operation.delta && operation.delta.batch;
  99. this.fire( 'change', operation.type, changes, batch );
  100. }
  101. /**
  102. * Creates a {@link treeModel.Batch} instance which allows to change the document.
  103. *
  104. * @returns {treeModel.Batch} Batch instance.
  105. */
  106. batch() {
  107. return new Batch( this );
  108. }
  109. /**
  110. * Creates a new top-level root.
  111. *
  112. * @param {String|Symbol} name Unique root name.
  113. * @returns {treeModel.RootElement} Created root.
  114. */
  115. createRoot( name ) {
  116. if ( this.roots.has( name ) ) {
  117. /**
  118. * Root with specified name already exists.
  119. *
  120. * @error document-createRoot-name-exists
  121. * @param {treeModel.Document} doc
  122. * @param {String} name
  123. */
  124. throw new CKEditorError(
  125. 'document-createRoot-name-exists: Root with specified name already exists.',
  126. { name: name }
  127. );
  128. }
  129. const root = new RootElement( this );
  130. this.roots.set( name, root );
  131. return root;
  132. }
  133. /**
  134. * Enqueue a callback with document changes. Any changes to be done on document (mostly using {@link #batch} should
  135. * be placed in the queued callback. If no other plugin is changing document at the moment, the callback will be
  136. * called immediately. Otherwise it will wait for all previously queued changes to finish happening. This way
  137. * queued callback will not interrupt other callbacks.
  138. *
  139. * When all queued changes are done {@link #changesDone} event is fired.
  140. *
  141. * @param {Function} callback Callback to enqueue.
  142. */
  143. enqueueChanges( callback ) {
  144. this._pendingChanges.push( callback );
  145. if ( this._pendingChanges.length == 1 ) {
  146. while ( this._pendingChanges.length ) {
  147. this._pendingChanges[ 0 ]();
  148. this._pendingChanges.shift();
  149. }
  150. this.fire( 'changesDone' );
  151. }
  152. }
  153. /**
  154. * Returns top-level root by it's name.
  155. *
  156. * @param {String|Symbol} name Name of the root to get.
  157. * @returns {treeModel.RootElement} Root registered under given name.
  158. */
  159. getRoot( name ) {
  160. if ( !this.roots.has( name ) ) {
  161. /**
  162. * Root with specified name does not exist.
  163. *
  164. * @error document-createRoot-root-not-exist
  165. * @param {String} name
  166. */
  167. throw new CKEditorError(
  168. 'document-createRoot-root-not-exist: Root with specified name does not exist.',
  169. { name: name }
  170. );
  171. }
  172. return this.roots.get( name );
  173. }
  174. /**
  175. * Fired when document changes by applying an operation.
  176. *
  177. * There are 5 types of change:
  178. *
  179. * * 'insert' when nodes are inserted,
  180. * * 'remove' when nodes are removed,
  181. * * 'reinsert' when remove is undone,
  182. * * 'move' when nodes are moved,
  183. * * 'attr' when attributes change.
  184. *
  185. * Change event is fired after the change is done. This means that any ranges or positions passed in
  186. * `changeInfo` are referencing nodes and paths in updated tree model.
  187. *
  188. * @event change
  189. * @param {String} type Change type, possible option: 'insert', 'remove', 'reinsert', 'move', 'attr'.
  190. * @param {Object} changeInfo Additional information about the change.
  191. * @param {treeModel.Range} changeInfo.range Range containing changed nodes. Note that for 'remove' the range will be in the
  192. * {@link #graveyard graveyard root}.
  193. * @param {treeModel.Position} [changeInfo.sourcePosition] Change source position. Exists for 'remove', 'reinsert' and 'move'.
  194. * Note that for 'reinsert' the source position will be in the {@link #graveyard graveyard root}.
  195. * @param {String} [changeInfo.key] Only for 'attr' type. Key of changed / inserted / removed attribute.
  196. * @param {*} [changeInfo.oldValue] Only for 'attr' type. If the type is 'attr' and `oldValue`
  197. * is `undefined` it means that new attribute was inserted. Otherwise it contains changed or removed attribute value.
  198. * @param {*} [changeInfo.newValue] Only for 'attr' type. If the type is 'attr' and `newValue`
  199. * is `undefined` it means that attribute was removed. Otherwise it contains changed or inserted attribute value.
  200. * @param {treeModel.Batch} {@link treeModel.Batch} of changes which this change is a part of.
  201. */
  202. /**
  203. * Fired when all queued document changes are done. See {@link #enqueueChanges}.
  204. *
  205. * @event changesDone
  206. */
  207. }
  208. utils.mix( Document, EmitterMixin );