|
|
@@ -7,10 +7,33 @@
|
|
|
|
|
|
CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
|
|
|
/**
|
|
|
+ * The transaction class groups document changes (deltas). All deltas grouped in a single transactions can be
|
|
|
+ * reverted together, so you can think about the transaction as a single undo step. If you want to extend one
|
|
|
+ * undo step you can call another method on the same transaction object. If you want to create a separate undo step
|
|
|
+ * you can create a new transaction.
|
|
|
+ *
|
|
|
+ * For example to create two separate undo steps you can call:
|
|
|
+ *
|
|
|
+ * doc.makeTransaction().insert( firstPosition, 'foo' );
|
|
|
+ * doc.makeTransaction().insert( secondPosition, 'bar' );
|
|
|
+ *
|
|
|
+ * To create a single undo step:
|
|
|
+ *
|
|
|
+ * const transaction = doc.makeTransaction()
|
|
|
+ * transaction.insert( firstPosition, 'foo' );
|
|
|
+ * transaction.insert( secontPosition, 'bar' );
|
|
|
+ *
|
|
|
+ * Note that all document modification methods (insert, remove, split, etc.) are chainable so you can shorten code to:
|
|
|
+ *
|
|
|
+ * doc.makeTransaction().insert( firstPosition, 'foo' ).insert( secontPosition, 'bar' );
|
|
|
+ *
|
|
|
* @class document.Transaction
|
|
|
*/
|
|
|
class Transaction {
|
|
|
/**
|
|
|
+ * Creates transaction instance. Not recommended to use directly, use {@link document.Document#makeTransaction}
|
|
|
+ * instead.
|
|
|
+ *
|
|
|
* @constructor
|
|
|
*/
|
|
|
constructor( doc ) {
|
|
|
@@ -18,6 +41,14 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
|
|
|
this.deltas = [];
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Adds delta to the transaction instance. All modification methods (insert, remove, split, etc.) use this method
|
|
|
+ * to add created deltas.
|
|
|
+ *
|
|
|
+ * @param {document.delta.Delta} delta Delta to add.
|
|
|
+ *
|
|
|
+ * @return {document.delta.Delta} Added delta.
|
|
|
+ */
|
|
|
addDelta( delta ) {
|
|
|
delta.transaction = this;
|
|
|
this.deltas.push( delta );
|
|
|
@@ -25,10 +56,50 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
|
|
|
return delta;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Transaction provides iterator interface which will iterate over deltas in the transaction.
|
|
|
+ */
|
|
|
[ Symbol.iterator ]() {
|
|
|
return this.deltas[ Symbol.iterator ]();
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Static method to register transaction methods. To make code scalable transaction do not have modification
|
|
|
+ * methods build in. They can be registered using this method.
|
|
|
+ *
|
|
|
+ * This method check if there is no naming collision and throw `transaction-register-taken` if the method name
|
|
|
+ * is already taken.
|
|
|
+ *
|
|
|
+ * It also pass {@link document.Document} and {@link document.Transaction} do the creator class.
|
|
|
+ *
|
|
|
+ * Registered function returns `this` so they because chainable by default.
|
|
|
+ *
|
|
|
+ * Beside that no magic happens here, the methods is added to the Transaction prototype.
|
|
|
+ *
|
|
|
+ * For example:
|
|
|
+ *
|
|
|
+ * Transaction.register( 'insert', ( doc, transaction, position, nodes ) => {
|
|
|
+ * // You can use a class inherit from Delta if that class should handle OT in the special way.
|
|
|
+ * const delta = new Delta();
|
|
|
+ *
|
|
|
+ * // Create operations which should be components of this delta.
|
|
|
+ * const operation = new InsertOperation( position, nodes, doc.version );
|
|
|
+ *
|
|
|
+ * // Remember to apply every operation, no magic, you need to do it manually.
|
|
|
+ * doc.applyOperation( operation );
|
|
|
+ *
|
|
|
+ * // Add operation to the delta.
|
|
|
+ * delta.addOperation( operation );
|
|
|
+ *
|
|
|
+ * // Add delta to the transaction instance.
|
|
|
+ * transaction.addDelta( delta );
|
|
|
+ *
|
|
|
+ * // You do not need to return transaction, register method will take care to make the method chainable.
|
|
|
+ * } );
|
|
|
+ *
|
|
|
+ * @param {String} name Method name.
|
|
|
+ * @param {Fuction} creator Method body.
|
|
|
+ */
|
|
|
static register( name, creator ) {
|
|
|
if ( Transaction.prototype[ name ] ) {
|
|
|
/**
|