Report an issue
Module

engine/model/operation/transform

@ckeditor/ckeditor5-engine/src/model/operation/transform

module

Filtering

Functions

  • transform( a, b, [ context ] ) → Array.<Operation>

    Transforms given operation by another operation and returns the result of that transformation as an array containing one or more operations.

    Operations work on specified positions, passed to them when they are created. Whenever document changes, we have to reflect those modifications by updating or "transforming" operations which are not yet applied. When an operation is transformed, its parameters may change based on the operation by which it is transformed. If the transform-by operation applied any modifications to the Tree Data Model which affect positions or nodes connected with transformed operation, those changes will be reflected in the parameters of the returned operation(s).

    Whenever the document has different version than the operation you want to apply, you need to transform that operation by all operations which were already applied to the document and have greater version than the operation being applied. Transform them in the same order as those operations which were applied. This way all modifications done to the Tree Data Model will be reflected in the operation parameters and the operation will "operate" on "up-to-date" version of the Tree Data Model. This is mostly the case with Operational Transformations but it might be needed in particular features as well.

    In some cases, when given operation apply changes to the same nodes as this operation, two or more operations need to be created as one would not be able to reflect the combination of these operations. This is why an array is returned instead of a single object. All returned operations have to be applied (or further transformed) to get an effect which was intended in pre-transformed operation.

    Sometimes two operations are in conflict. This happens when they modify the same node in a different way, i.e. set different value for the same attribute or move the node into different positions. When this happens, we need to decide which operation is more important. We can't assume that operation a or operation b is always more important. In Operational Transformations algorithms we often need to get a result of transforming a by b and also b by a. In both transformations the same operation has to be the important one. If we assume that first or the second passed operation is always more important we won't be able to solve this case.

    Parameters

    a : Operation

    Operation that will be transformed.

    b : Operation

    Operation to transform by.

    [ context ] : transformationContext

    Transformation context.

    Returns

    Array.<Operation>

    Result of the transformation.