8
0
Эх сурвалжийг харах

Changed Operation method name from `reverseOperation()` to `getReversed()`.

Szymon Cofalik 10 жил өмнө
parent
commit
1c7e3265b7

+ 3 - 7
packages/ckeditor5-engine/src/document/changeoperation.js

@@ -59,9 +59,7 @@ CKEDITOR.define( [ 'document/operation', 'ckeditorerror' ], function( Operation,
 		}
 
 		/**
-		 * Execute operation.
-		 *
-		 * @protected
+		 * See {@link document.Operation#_execute}.
 		 */
 		_execute() {
 			var oldAttr = this.oldAttr;
@@ -130,11 +128,9 @@ CKEDITOR.define( [ 'document/operation', 'ckeditorerror' ], function( Operation,
 		}
 
 		/**
-		 * Creates an reverse change operation.
-		 *
-		 * @returns {document.ChangeOperation} Reverse operation.
+		 * See {@link document.Operation#getReversed}.
 		 */
-		reverseOperation() {
+		getReversed() {
 			return new ChangeOperation( this.range, this.newAttr, this.oldAttr, this.baseVersion + 1 );
 		}
 	}

+ 3 - 7
packages/ckeditor5-engine/src/document/insertoperation.js

@@ -42,20 +42,16 @@ CKEDITOR.define( [ 'document/operation', 'document/nodelist', 'document/removeop
 		}
 
 		/**
-		 * Execute operation.
-		 *
-		 * @protected
+		 * See {@link document.Operation#_execute}.
 		 */
 		_execute() {
 			this.position.parent.insertChildren( this.position.offset, this.nodeList );
 		}
 
 		/**
-		 * Creates a reverse operation.
-		 *
-		 * @returns {document.RemoveOperation} Reverse operation.
+		 * See {@link document.Operation#getReversed}.
 		 */
-		reverseOperation() {
+		getReversed() {
 			// Because of circular dependencies we need to re-require remove operation here.
 			var RemoveOperation = CKEDITOR.require( 'document/removeoperation' );
 

+ 3 - 7
packages/ckeditor5-engine/src/document/moveoperation.js

@@ -52,9 +52,7 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Execute operation.
-		 *
-		 * @protected
+		 * See {@link document.Operation#_execute}.
 		 */
 		_execute() {
 			var sourceElement = this.sourcePosition.parent;
@@ -133,11 +131,9 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Creates a reverse operation.
-		 *
-		 * @returns {document.MoveOperation} Reverse operation.
+		 * See {@link document.Operation#getReversed}.
 		 */
-		reverseOperation() {
+		getReversed() {
 			return new MoveOperation( this.targetPosition, this.sourcePosition, this.howMany, this.baseVersion + 1 );
 		}
 	}

+ 46 - 0
packages/ckeditor5-engine/src/document/operation.js

@@ -28,6 +28,52 @@ CKEDITOR.define( [], function() {
 			 * @property {Number} baseVersion
 			 */
 			this.baseVersion = baseVersion;
+
+			/**
+			 * Executes the operation - modifications described by the operation attributes
+			 * will be applied to the tree model.
+			 *
+			 * This method has to be defined in deriving operation class.
+			 *
+			 * @method _execute
+			 * @protected
+			 */
+
+			/**
+			 * Creates and returns a reverse operation. Reverse operation when executed right after
+			 * the original operation will bring back tree model state to the point before the original
+			 * operation execution. In other words, it reverses changes done by the original operation.
+			 *
+			 * Keep in mind that tree model state may change since executing the original operation,
+			 * so reverse operation will be "outdated". In that case you will need to
+			 * {@link #getTransformedBy transform} it by all operations that were executed after the original operation
+			 *
+			 * This method has to be defined in deriving operation class.
+			 *
+			 * @method getReversed
+			 * @returns {document.Operation} Reversed operation.
+			 */
+
+			/**
+			 * Creates and returns a clone of this operation that is transformed by given operation.
+			 * When operation is transformed it's parameters may change accordingly to the operation which it is
+			 * transformed by. If given operation applied any modifications to the tree model that are
+			 * affecting ranges / positions / nodes connected with this operation, those changes will be reflected
+			 * in parameters of returned operation.
+			 *
+			 * Whenever a {@link document.Document document} has different {@link document.Document#baseVersion}
+			 * than an operation you want to {@link #_execute execute}, you need to transform that operation by
+			 * all the operations that were executed on the {@link document.Document document} since it has
+			 * {@link document.Document#baseVersion} same as the operation (transform in the same order as those
+			 * operations were executed). This way all modifications done to the tree model will be reflected
+			 * in the operation parameters and the operation will "work" on "up-to-date" version of the tree model.
+			 *
+			 * This method has to be defined in deriving operation class.
+			 *
+			 * @method getTransformedBy
+			 * @param {document.Operation} operation Operation by which this operation will be transformed.
+			 * @returns {document.Operation} A result of transformation of this operation by the given operation.
+			 */
 		}
 	}
 

+ 2 - 4
packages/ckeditor5-engine/src/document/reinsertoperation.js

@@ -20,11 +20,9 @@ CKEDITOR.define( [
 	 */
 	class ReinsertOperation extends MoveOperation {
 		/**
-		 * Creates a reverse operation.
-		 *
-		 * @returns {document.RemoveOperation} Reverse operation.
+		 * See {@link document.Operation#getReversed}.
 		 */
-		reverseOperation() {
+		getReversed() {
 			// Because of circular dependencies we need to re-require reinsert operation here.
 			var RemoveOperation = CKEDITOR.require( 'document/removeoperation' );
 

+ 2 - 4
packages/ckeditor5-engine/src/document/removeoperation.js

@@ -36,11 +36,9 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Creates a reverse operation.
-		 *
-		 * @returns {document.ReinsertOperation} Reverse operation.
+		 * See {@link document.Operation#getReversed}.
 		 */
-		reverseOperation() {
+		getReversed() {
 			// Because of circular dependencies we need to re-require reinsert operation here.
 			var ReinsertOperation = CKEDITOR.require( 'document/reinsertoperation' );
 

+ 4 - 4
packages/ckeditor5-engine/tests/document/changeoperation.js

@@ -164,7 +164,7 @@ describe( 'ChangeOperation', function() {
 		var newAttr = new Attribute( 'x', 'new' );
 		var range = new Range( new Position( [ 0 ], root ), new Position( [ 3 ], root ) );
 		var operation = new ChangeOperation( range, oldAttr, newAttr, doc.version );
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		expect( reverse ).to.be.an.instanceof( ChangeOperation );
 		expect( reverse.baseVersion ).to.equal( 1 );
@@ -185,7 +185,7 @@ describe( 'ChangeOperation', function() {
 			doc.version
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		doc.applyOperation( operation );
 		doc.applyOperation( reverse );
@@ -210,7 +210,7 @@ describe( 'ChangeOperation', function() {
 			doc.version
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		doc.applyOperation( operation );
 
@@ -238,7 +238,7 @@ describe( 'ChangeOperation', function() {
 			doc.version
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		doc.applyOperation( operation );
 

+ 3 - 3
packages/ckeditor5-engine/tests/document/insertoperation.js

@@ -112,7 +112,7 @@ describe( 'InsertOperation', function() {
 			0
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		expect( reverse ).to.be.an.instanceof( RemoveOperation );
 		expect( reverse.baseVersion ).to.equal( 1 );
@@ -127,7 +127,7 @@ describe( 'InsertOperation', function() {
 			doc.version
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		doc.applyOperation( operation );
 
@@ -146,7 +146,7 @@ describe( 'InsertOperation', function() {
 			doc.version
 		);
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		doc.applyOperation( operation );
 

+ 2 - 2
packages/ckeditor5-engine/tests/document/moveoperation.js

@@ -109,7 +109,7 @@ describe( 'MoveOperation', function() {
 
 		var operation = new MoveOperation( sourcePosition, targetPosition, nodeList.length, doc.version );
 
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		expect( reverse ).to.be.an.instanceof( MoveOperation );
 		expect( reverse.baseVersion ).to.equal( 1 );
@@ -139,7 +139,7 @@ describe( 'MoveOperation', function() {
 		expect( p2.getChildCount() ).to.equal( 1 );
 		expect( p2.getChild( 0 ).name ).to.equal( 'x' );
 
-		doc.applyOperation( operation.reverseOperation() );
+		doc.applyOperation( operation.getReversed() );
 
 		expect( doc.version ).to.equal( 2 );
 		expect( root.getChildCount() ).to.equal( 2 );

+ 2 - 2
packages/ckeditor5-engine/tests/document/reinsertoperation.js

@@ -49,7 +49,7 @@ describe( 'ReinsertOperation', function() {
 	} );
 
 	it( 'should create a remove operation as a reverse', function() {
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		expect( reverse ).to.be.an.instanceof( RemoveOperation );
 		expect( reverse.baseVersion ).to.equal( 1 );
@@ -59,7 +59,7 @@ describe( 'ReinsertOperation', function() {
 	} );
 
 	it( 'should undo reinsert set of nodes by applying reverse operation', function() {
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		graveyard.insertChildren( 0, 'bar' );
 

+ 2 - 2
packages/ckeditor5-engine/tests/document/removeoperation.js

@@ -71,7 +71,7 @@ describe( 'RemoveOperation', function() {
 	it( 'should create a reinsert operation as a reverse', function() {
 		var position = new Position( [ 0 ], root );
 		var operation = new RemoveOperation( position, 2, 0 );
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		expect( reverse ).to.be.an.instanceof( ReinsertOperation );
 		expect( reverse.baseVersion ).to.equal( 1 );
@@ -83,7 +83,7 @@ describe( 'RemoveOperation', function() {
 	it( 'should undo remove set of nodes by applying reverse operation', function() {
 		var position = new Position( [ 0 ], root );
 		var operation = new RemoveOperation( position, 3, 0 );
-		var reverse = operation.reverseOperation();
+		var reverse = operation.getReversed();
 
 		root.insertChildren( 0, 'bar' );