CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
Home/CKEditor 5/API
Class

Position (engine/model)

@ckeditor/ckeditor5-engine/src/model/position

class
See source

Represents a position in the model tree.

A position is represented by its root and a path in that root.

You can create position instances via its constructor or the createPosition*() factory methods of Model and Writer.

Note: Position is based on offsets, not indexes. This means that a position between two text nodes foo and bar has offset 3, not 1. See path for more information.

Since a position in the model is represented by a position root and position path it is possible to create positions placed in non-existing places. This requirement is important for operational transformation algorithms.

Also, operations kept in the document history are storing positions (and ranges) which were correct when those operations were applied, but may not be correct after the document has changed.

When changes are applied to the model, it may also happen that position parent will change even if position path has not changed. Keep in mind, that if a position leads to non-existing element, parent and some other properties and methods will throw errors.

In most cases, position with wrong path is caused by an error in code, but it is sometimes needed, as described above.

Filtering

Properties

  • index : Number

    readonly

    Position offset converted to an index in position's parent node. It is equal to the index of a node after this position. If position is placed in text node, position index is equal to the index of that text node.

    See source

  • isAtEnd : Boolean

    readonly

    Is true if position is at the end of its parent, false otherwise.

    See source

  • isAtStart : Boolean

    readonly

    Is true if position is at the beginning of its parent, false otherwise.

    See source

  • nodeAfter : Node | null

    readonly

    Node directly after this position or null if this position is in text node.

    See source

  • nodeBefore : Node | null

    readonly

    Node directly before this position or null if this position is in text node.

    See source

  • offset : Number

    Offset at which this position is located in its parent. It is equal to the last item in position path.

    See source

  • parent : Element | DocumentFragment

    readonly

    Parent element of this position.

    See source

    Keep in mind that parent value is calculated when the property is accessed. If position path leads to a non-existing element, parent property will throw error.

    Also it is a good idea to cache parent property if it is used frequently in an algorithm (i.e. in a long loop).

  • path : Array.<Number>

    readonly

    Position of the node in the tree. Path contains offsets, not indexes.

    See source

    Position can be placed before, after or in a node if that node has offsetSize greater than 1. Items in position path are starting offsets of position ancestors, starting from direct root children, down to the position offset in it's parent.

    ROOT
 |- P            before: [ 0 ]         after: [ 1 ]
 |- UL           before: [ 1 ]         after: [ 2 ]
    |- LI        before: [ 1, 0 ]      after: [ 1, 1 ]
    |  |- foo    before: [ 1, 0, 0 ]   after: [ 1, 0, 3 ]
    |- LI        before: [ 1, 1 ]      after: [ 1, 2 ]
       |- bar    before: [ 1, 1, 0 ]   after: [ 1, 1, 3 ]

    foo and bar are representing text nodes. Since text nodes has offset size greater than 1 you can place position offset between their start and end:

    ROOT
 |- P
 |- UL
    |- LI
    |  |- f^o|o  ^ has path: [ 1, 0, 1 ]   | has path: [ 1, 0, 2 ]
    |- LI
       |- b^a|r  ^ has path: [ 1, 1, 1 ]   | has path: [ 1, 1, 2 ]

  • root : Element | DocumentFragment

    readonly

    Root of the position path.

    See source

  • stickiness : PositionStickiness

    Position stickiness. See PositionStickiness.

    See source

  • textNode : Text | null

    readonly

    Returns text node instance in which this position is placed or null if this position is not in a text node.

    See source

Methods

  • constructor( root, path, [ stickiness ] )

    Creates a position.

    See source

    Parameters

    root : Element | DocumentFragment

    Root of the position.

    path : Array.<Number>

    Position path. See path.

    [ stickiness ] : PositionStickiness

    Position stickiness. See PositionStickiness.

    Defaults to 'toNone'

  • clone() → Position

    Returns a new position that is equal to current position.

    See source

    Returns

    Position

  • compareWith( otherPosition ) → PositionRelation

    Checks whether this position is before or after given position.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    PositionRelation

  • findAncestor( parentName ) → Element | null

    Returns the parent element of the given name. Returns null if the position is not inside the desired parent.

    See source

    Parameters

    parentName : String

    The name of the parent element to find.

    Returns

    Element | null

  • getAncestors() → Array.<Item>

    Returns ancestors array of this position, that is this position's parent and its ancestors.

    See source

    Returns

    Array.<Item>

    Array with ancestors.

  • getCommonAncestor( position ) → Element | DocumentFragment | null

    Returns an Element or DocumentFragment which is a common ancestor of both positions. The roots of these two positions must be identical.

    See source

    Parameters

    position : Position

    The second position.

    Returns

    Element | DocumentFragment | null

  • getCommonPath( position ) → Array.<Number>

    Returns the slice of two position paths which is identical. The roots of these two paths must be identical.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    position : Position

    The second position.

    Returns

    Array.<Number>

    The common path.

  • getLastMatchingPosition( skip, options ) → Position

    Gets the farthest position which matches the callback using TreeWalker.

    See source

    For example:

    getLastMatchingPosition( value => value.type == 'text' );
// <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>

getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } );
// <paragraph>foo[]</paragraph> -> <paragraph>[]foo</paragraph>

getLastMatchingPosition( value => false );
// Do not move the position.

    Parameters

    skip : function

    Callback function. Gets TreeWalkerValue and should return true if the value should be skipped or false if not.

    options : Object

    Object with configuration options. See TreeWalker.

    Returns

    Position

    The position after the last item which matches the skip callback test.

  • getParentPath() → Array.<Number>

    Returns a path to this position's parent. Parent path is equal to position path but without the last item.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Returns

    Array.<Number>

    Path to the parent.

  • getShiftedBy( shift ) → Position

    Returns a new instance of Position, that has same parent but it's offset is shifted by shift value (can be a negative value).

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    shift : Number

    Offset shift. Can be a negative value.

    Returns

    Position

    Shifted position.

  • getTransformedByOperation( operation ) → Position

    Returns a copy of this position that is transformed by given operation.

    See source

    The new position's parameters are updated accordingly to the effect of the operation.

    For example, if n nodes are inserted before the position, the returned position offset will be increased by n. If the position was in a merged element, it will be accordingly moved to the new element, etc.

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    operation : Operation

    Operation to transform by.

    Returns

    Position

    Transformed position.

  • hasSameParentAs( position ) → Boolean

    Checks if two positions are in the same parent.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    position : Position

    Position to compare with.

    Returns

    Boolean

    true if positions have the same parent, false otherwise.

  • is( type ) → Boolean

    Checks whether this object is of the given.

    See source
    position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true

position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false

    Check the entire list of model objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

  • isAfter( otherPosition ) → Boolean

    Checks whether this position is after given position.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if this position is after given position.

    Related:

  • isBefore( otherPosition ) → Boolean

    Checks whether this position is before given position.

    See source

    Note: watch out when using negation of the value returned by this method, because the negation will also be true if positions are in different roots and you might not expect this. You should probably use a.isAfter( b ) || a.isEqual( b ) or !a.isBefore( p ) && a.root == b.root in most scenarios. If your condition uses multiple isAfter and isBefore checks, build them so they do not use negated values, i.e.:

    if ( a.isBefore( b ) && c.isAfter( d ) ) {
	// do A.
} else {
	// do B.
}

    or, if you have only one if-branch:

    if ( !( a.isBefore( b ) && c.isAfter( d ) ) {
	// do B.
}

    rather than:

    if ( !a.isBefore( b ) || && !c.isAfter( d ) ) {
	// do B.
} else {
	// do A.
}

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if this position is before given position.

  • isEqual( otherPosition ) → Boolean

    Checks whether this position is equal to given position.

    See source

    This method is safe to use it on non-existing positions (for example during operational transformation).

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if positions are same.

  • isTouching( otherPosition ) → Boolean

    Checks whether this position is touching given position. Positions touch when there are no text nodes or empty nodes in a range between them. Technically, those positions are not equal but in many cases they are very similar or even indistinguishable.

    See source

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if positions touch.

  • _getCombined( source, target ) → Position

    protected

    Returns a new position that is a combination of this position and given positions.

    See source

    The combined position is a copy of this position transformed by moving a range starting at source position to the target position. It is expected that this position is inside the moved range.

    Example:

    let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
let source = model.createPositionFromPath( root, [ 2, 2 ] );
let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`

    Explanation:

    We have a position [ 2, 3, 1 ] and move some nodes from [ 2, 2 ] to [ 1, 1, 3 ]. The original position was inside moved nodes and now should point to the new place. The moved nodes will be after positions [ 1, 1, 3 ], [ 1, 1, 4 ], [ 1, 1, 5 ]. Since our position was in the second moved node, the transformed position will be in a sub-tree of a node at [ 1, 1, 4 ]. Looking at original path, we took care of [ 2, 3 ] part of it. Now we have to add the rest of the original path to the transformed path. Finally, the transformed position will point to [ 1, 1, 4, 1 ].

    Parameters

    source : Position

    Beginning of the moved range.

    target : Position

    Position where the range is moved.

    Returns

    Position

    Combined position.

  • _getTransformedByDeletion( deletePosition, howMany ) → Position | null

    protected

    Returns a copy of this position that is updated by removing howMany nodes starting from deletePosition. It may happen that this position is in a removed node. If that is the case, null is returned instead.

    See source

    Parameters

    deletePosition : Position

    Position before the first removed node.

    howMany : Number

    How many nodes are removed.

    Returns

    Position | null

    Transformed position or null.

  • _getTransformedByInsertOperation( operation ) → Position

    protected

    Returns a copy of this position transformed by an insert operation.

    See source

    Parameters

    operation : InsertOperation

    Returns

    Position

  • _getTransformedByInsertion( insertPosition, howMany ) → Position

    protected

    Returns a copy of this position that is updated by inserting howMany nodes at insertPosition.

    See source

    Parameters

    insertPosition : Position

    Position where nodes are inserted.

    howMany : Number

    How many nodes are inserted.

    Returns

    Position

    Transformed position.

  • _getTransformedByMergeOperation( operation ) → Position

    protected

    Returns a copy of this position transformed by merge operation.

    See source

    Parameters

    operation : MergeOperation

    Returns

    Position

  • _getTransformedByMove( sourcePosition, targetPosition, howMany ) → Position

    protected

    Returns a copy of this position that is updated by moving howMany nodes from sourcePosition to targetPosition.

    See source

    Parameters

    sourcePosition : Position

    Position before the first element to move.

    targetPosition : Position

    Position where moved elements will be inserted.

    howMany : Number

    How many consecutive nodes to move, starting from sourcePosition.

    Returns

    Position

    Transformed position.

  • _getTransformedByMoveOperation( operation ) → Position

    protected

    Returns a copy of this position transformed by a move operation.

    See source

    Parameters

    operation : MoveOperation

    Returns

    Position

  • _getTransformedBySplitOperation( operation ) → Position

    protected

    Returns a copy of this position transformed by a split operation.

    See source

    Parameters

    operation : SplitOperation

    Returns

    Position

Static methods

  • fromJSON( json, doc ) → Position

    static

    Creates a Position instance from given plain object (i.e. parsed JSON string).

    See source

    Parameters

    json : Object

    Plain object to be converted to Position.

    doc : Document

    Document object that will be position owner.

    Returns

    Position

    Position instance created using given plain object.

  • _createAfter( item, [ stickiness ] ) → Position

    protected static

    Creates a new position, after given model item.

    See source

    Parameters

    item : Item

    Item after which the position should be placed.

    [ stickiness ] : PositionStickiness

    Position stickiness.

    Defaults to 'toNone'

    Returns

    Position

  • _createAt( itemOrPosition, [ offset ], [ stickiness ] )

    protected static

    Creates position at the given location. The location can be specified as:

    See source
    • a position,
    • parent element and offset (offset defaults to 0),
    • parent element and 'end' (sets position at the end of that element),
    • model item and 'before' or 'after' (sets position before or after given model item).

    This method is a shortcut to other factory methods such as:

    Parameters

    itemOrPosition : Item | Position
    [ offset ] : Number | 'end' | 'before' | 'after'

    Offset or one of the flags. Used only when the first parameter is a model item.

    [ stickiness ] : PositionStickiness

    Position stickiness. Used only when the first parameter is a model item.

    Defaults to 'toNone'

  • _createBefore( item, [ stickiness ] ) → Position

    protected static

    Creates a new position, before the given model item.

    See source

    Parameters

    item : Item

    Item before which the position should be placed.

    [ stickiness ] : PositionStickiness

    Position stickiness.

    Defaults to 'toNone'

    Returns

    Position