LivePosition (engine/model)

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

class

LivePosition is a type of Position that updates itself as document is changed through operations. It may be used as a bookmark.

Note: Contrary to Position, LivePosition works only in roots that are RootElement. If DocumentFragment is passed, error will be thrown.

Note: Be very careful when dealing with LivePosition. Each LivePosition instance bind events that might have to be unbound. Use detach whenever you don't need LivePosition anymore.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

index : Number

readonly inherited

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 inherited

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

See source
isAtStart : Boolean

readonly inherited

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

See source
nodeAfter : Node | null

readonly inherited

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

See source
nodeBefore : Node | null

readonly inherited

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

See source
offset : Number

inherited

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 inherited

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 inherited
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 inherited

Root of the position path.

See source
stickiness : PositionStickiness

inherited

Position stickiness. See PositionStickiness.

See source
textNode : Text | null

readonly inherited

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 live position.

See source
Parameters

root : RootElement

path : Array.<Number>

[ stickiness ] : PositionStickiness

Defaults to toNone

Related:
- Position
clone() → Position

inherited

Returns a new position that is equal to current position.

See source

Returns

Position
compareWith( otherPosition ) → PositionRelation

inherited

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
detach()

Unbinds all events previously bound by LivePosition. Use it whenever you don't need LivePosition instance anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was referring to it).

See source
findAncestor( parentName ) → Element | null

inherited

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>

inherited

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

inherited

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>

inherited

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

inherited
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>

inherited

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

inherited

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

inherited

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

inherited

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

inherited
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

inherited
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:
- Position#isBefore
isBefore( otherPosition ) → Boolean

inherited
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

inherited

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

inherited

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.
toPosition() → Position

Creates a position instance, which is equal to this live position.

See source

Returns

Position
_getCombined( source, target ) → Position

protected inherited
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 inherited

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 inherited

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

See source

Parameters

operation : InsertOperation

Returns

Position
_getTransformedByInsertion( insertPosition, howMany ) → Position

protected inherited

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 inherited

Returns a copy of this position transformed by merge operation.

See source

Parameters

operation : MergeOperation

Returns

Position
_getTransformedByMove( sourcePosition, targetPosition, howMany ) → Position

protected inherited

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 inherited

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

See source

Parameters

operation : MoveOperation

Returns

Position
_getTransformedBySplitOperation( operation ) → Position

protected inherited

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

See source

Parameters

operation : SplitOperation

Returns

Position

Static methods

fromJSON( json, doc ) → Position

inherited 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.
fromPosition( position, [ stickiness ] ) → LivePosition

static

Creates a LivePosition instance that is equal to position.

See source

Parameters

position : Position

[ stickiness ] : PositionStickiness

Returns

LivePosition
_createAfter( node, [ stickiness ] ) → LivePosition

protected static
Parameters

node : Node

[ stickiness ] : PositionStickiness

Defaults to 'toNone'

Returns

LivePosition

Related:
- _createAfter
_createAt( itemOrPosition, [ offset ], [ stickiness ] ) → LivePosition

protected static
Parameters

itemOrPosition : Item | Position

[ offset ] : Number | 'end' | 'before' | 'after'

[ stickiness ] : PositionStickiness

Defaults to 'toNone'

Returns

LivePosition

Related:
- _createAt
_createBefore( node, [ stickiness ] ) → LivePosition

protected static
Parameters

node : Node

[ stickiness ] : PositionStickiness

Defaults to 'toNone'

Returns

LivePosition

Related:
- _createBefore

Events

change( eventInfo, oldPosition )

Fired when LivePosition instance is changed due to changes on Document.

See source

Parameters

eventInfo : EventInfo

An object containing information about the fired event.

oldPosition : Position

Position equal to this live position before it got changed.

Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.

LivePosition (engine/model)

Filtering

Properties

index : Numbermodule:engine/model/liveposition~LivePosition#index

isAtEnd : Booleanmodule:engine/model/liveposition~LivePosition#isAtEnd

isAtStart : Booleanmodule:engine/model/liveposition~LivePosition#isAtStart

nodeAfter : Node | nullmodule:engine/model/liveposition~LivePosition#nodeAfter

nodeBefore : Node | nullmodule:engine/model/liveposition~LivePosition#nodeBefore

offset : Numbermodule:engine/model/liveposition~LivePosition#offset

parent : Element | DocumentFragmentmodule:engine/model/liveposition~LivePosition#parent

path : Array.<Number>module:engine/model/liveposition~LivePosition#path

root : Element | DocumentFragmentmodule:engine/model/liveposition~LivePosition#root

stickiness : PositionStickinessmodule:engine/model/liveposition~LivePosition#stickiness

textNode : Text | nullmodule:engine/model/liveposition~LivePosition#textNode

Methods

constructor( root, path, [ stickiness ] )module:engine/model/liveposition~LivePosition#constructor

Parameters

Related:

clone() → Positionmodule:engine/model/liveposition~LivePosition#clone

Returns

compareWith( otherPosition ) → PositionRelationmodule:engine/model/liveposition~LivePosition#compareWith

Parameters

Returns

detach()module:engine/model/liveposition~LivePosition#detach

findAncestor( parentName ) → Element | nullmodule:engine/model/liveposition~LivePosition#findAncestor

Parameters

Returns

getAncestors() → Array.<Item>module:engine/model/liveposition~LivePosition#getAncestors

Returns

getCommonAncestor( position ) → Element | DocumentFragment | nullmodule:engine/model/liveposition~LivePosition#getCommonAncestor

Parameters

Returns

getCommonPath( position ) → Array.<Number>module:engine/model/liveposition~LivePosition#getCommonPath

Parameters

Returns

getLastMatchingPosition( skip, options ) → Positionmodule:engine/model/liveposition~LivePosition#getLastMatchingPosition

Parameters

Returns

getParentPath() → Array.<Number>module:engine/model/liveposition~LivePosition#getParentPath

Returns

getShiftedBy( shift ) → Positionmodule:engine/model/liveposition~LivePosition#getShiftedBy

Parameters

Returns

getTransformedByOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#getTransformedByOperation

Parameters

Returns

hasSameParentAs( position ) → Booleanmodule:engine/model/liveposition~LivePosition#hasSameParentAs

Parameters

Returns

is( type ) → Booleanmodule:engine/model/liveposition~LivePosition#is

Parameters

Returns

isAfter( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isAfter

Parameters

Returns

Related:

isBefore( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isBefore

Parameters

Returns

isEqual( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isEqual

Parameters

Returns

isTouching( otherPosition ) → Booleanmodule:engine/model/liveposition~LivePosition#isTouching

Parameters

Returns

toPosition() → Positionmodule:engine/model/liveposition~LivePosition#toPosition

Returns

_getCombined( source, target ) → Positionmodule:engine/model/liveposition~LivePosition#_getCombined

Parameters

Returns

_getTransformedByDeletion( deletePosition, howMany ) → Position | nullmodule:engine/model/liveposition~LivePosition#_getTransformedByDeletion

Parameters

Returns

_getTransformedByInsertOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByInsertOperation

Parameters

Returns

_getTransformedByInsertion( insertPosition, howMany ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByInsertion

Parameters

Returns

_getTransformedByMergeOperation( operation ) → Positionmodule:engine/model/liveposition~LivePosition#_getTransformedByMergeOperation

`index : Number`

`isAtEnd : Boolean`

`isAtStart : Boolean`

`nodeAfter : Node | null`

`nodeBefore : Node | null`

`offset : Number`

`parent : Element | DocumentFragment`

`path : Array.<Number>`

`root : Element | DocumentFragment`

`stickiness : PositionStickiness`

`textNode : Text | null`

`constructor( root, path, [ stickiness ] )`

`clone() → Position`

`compareWith( otherPosition ) → PositionRelation`

`detach()`

`findAncestor( parentName ) → Element | null`

`getAncestors() → Array.<Item>`

`getCommonAncestor( position ) → Element | DocumentFragment | null`

`getCommonPath( position ) → Array.<Number>`

`getLastMatchingPosition( skip, options ) → Position`

`getParentPath() → Array.<Number>`

`getShiftedBy( shift ) → Position`

`getTransformedByOperation( operation ) → Position`

`hasSameParentAs( position ) → Boolean`

`is( type ) → Boolean`

`isAfter( otherPosition ) → Boolean`

`isBefore( otherPosition ) → Boolean`

`isEqual( otherPosition ) → Boolean`

`isTouching( otherPosition ) → Boolean`

`toPosition() → Position`

`_getCombined( source, target ) → Position`

`_getTransformedByDeletion( deletePosition, howMany ) → Position | null`

`_getTransformedByInsertOperation( operation ) → Position`

`_getTransformedByInsertion( insertPosition, howMany ) → Position`

`_getTransformedByMergeOperation( operation ) → Position`

`_getTransformedByMove( sourcePosition, targetPosition, howMany ) → Position`

`_getTransformedByMoveOperation( operation ) → Position`

`_getTransformedBySplitOperation( operation ) → Position`

`fromJSON( json, doc ) → Position`

`fromPosition( position, [ stickiness ] ) → LivePosition`

`_createAfter( node, [ stickiness ] ) → LivePosition`

`_createAt( itemOrPosition, [ offset ], [ stickiness ] ) → LivePosition`

`_createBefore( node, [ stickiness ] ) → LivePosition`

`change( eventInfo, oldPosition )`