Position (engine/model)
@ckeditor/ckeditor5-engine/src/model/position
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
-
Is
true
if position is at the end of its parent,false
otherwise. -
Is
true
if position is at the beginning of its parent,false
otherwise. -
Node directly after this position or
null
if this position is in text node. -
Node directly before this position or
null
if this position is in text node. -
offset : Number
module:engine/model/position~Position#offset
-
Parent element of this position.
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). -
Position of the node in the tree. Path contains offsets, not indexes.
Position can be placed before, after or in a node if that node has
offsetSize
greater than1
. 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
andbar
are representing text nodes. Since text nodes has offset size greater than1
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 of the position path.
-
stickiness : PositionStickiness
module:engine/model/position~Position#stickiness
Position stickiness. See
PositionStickiness
. -
Returns text node instance in which this position is placed or
null
if this position is not in a text node.
Methods
-
constructor( root, path, [ stickiness ] )
module:engine/model/position~Position#constructor
Creates a position.
Parameters
root : Element | DocumentFragment
Root of the position.
path : Array.<Number>
Position path. See
path
.[ stickiness ] : PositionStickiness
Position stickiness. See
PositionStickiness
.Defaults to
'toNone'
-
-
compareWith( otherPosition ) → PositionRelation
module:engine/model/position~Position#compareWith
Checks whether this position is before or after given position.
This method is safe to use it on non-existing positions (for example during operational transformation).
Parameters
otherPosition : Position
Position to compare with.
Returns
-
findAncestor( parentName ) → Element | null
module:engine/model/position~Position#findAncestor
Returns the parent element of the given name. Returns null if the position is not inside the desired parent.
Parameters
parentName : String
The name of the parent element to find.
Returns
Element | null
-
getAncestors() → Array.<Item>
module:engine/model/position~Position#getAncestors
Returns ancestors array of this position, that is this position's parent and its ancestors.
Returns
Array.<Item>
Array with ancestors.
-
getCommonAncestor( position ) → Element | DocumentFragment | null
module:engine/model/position~Position#getCommonAncestor
Returns an
Element
orDocumentFragment
which is a common ancestor of both positions. The roots of these two positions must be identical.Parameters
position : Position
The second position.
Returns
Element | DocumentFragment | null
-
getCommonPath( position ) → Array.<Number>
module:engine/model/position~Position#getCommonPath
Returns the slice of two position paths which is identical. The roots of these two paths must be identical.
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
module:engine/model/position~Position#getLastMatchingPosition
Gets the farthest position which matches the callback using TreeWalker.
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 returntrue
if the value should be skipped orfalse
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>
module:engine/model/position~Position#getParentPath
Returns a path to this position's parent. Parent path is equal to position path but without the last item.
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
module:engine/model/position~Position#getShiftedBy
Returns a new instance of
Position
, that has same parent but it's offset is shifted byshift
value (can be a negative value).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
module:engine/model/position~Position#getTransformedByOperation
Returns a copy of this position that is transformed by given
operation
.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 positionoffset
will be increased byn
. 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
module:engine/model/position~Position#hasSameParentAs
Checks if two positions are in the same parent.
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
module:engine/model/position~Position#is
Checks whether this object is of the given.
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
module:engine/model/position~Position#isAfter
Checks whether this position is after given position.
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
module:engine/model/position~Position#isBefore
Checks whether this position is before given position.
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 usea.isAfter( b ) || a.isEqual( b )
or!a.isBefore( p ) && a.root == b.root
in most scenarios. If your condition uses multipleisAfter
andisBefore
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
module:engine/model/position~Position#isEqual
Checks whether this position is equal to given position.
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
module:engine/model/position~Position#isTouching
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.
Parameters
otherPosition : Position
Position to compare with.
Returns
Boolean
True if positions touch.
-
protected
_getCombined( source, target ) → Position
module:engine/model/position~Position#_getCombined
Returns a new position that is a combination of this position and given positions.
The combined position is a copy of this position transformed by moving a range starting at
source
position to thetarget
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.
-
protected
_getTransformedByDeletion( deletePosition, howMany ) → Position | null
module:engine/model/position~Position#_getTransformedByDeletion
Returns a copy of this position that is updated by removing
howMany
nodes starting fromdeletePosition
. It may happen that this position is in a removed node. If that is the case,null
is returned instead.Parameters
deletePosition : Position
Position before the first removed node.
howMany : Number
How many nodes are removed.
Returns
Position | null
Transformed position or
null
.
-
protected
_getTransformedByInsertOperation( operation ) → Position
module:engine/model/position~Position#_getTransformedByInsertOperation
Returns a copy of this position transformed by an insert operation.
Parameters
operation : InsertOperation
Returns
-
protected
_getTransformedByInsertion( insertPosition, howMany ) → Position
module:engine/model/position~Position#_getTransformedByInsertion
-
protected
_getTransformedByMergeOperation( operation ) → Position
module:engine/model/position~Position#_getTransformedByMergeOperation
Returns a copy of this position transformed by merge operation.
Parameters
operation : MergeOperation
Returns
-
protected
_getTransformedByMove( sourcePosition, targetPosition, howMany ) → Position
module:engine/model/position~Position#_getTransformedByMove
Returns a copy of this position that is updated by moving
howMany
nodes fromsourcePosition
totargetPosition
.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.
-
protected
_getTransformedByMoveOperation( operation ) → Position
module:engine/model/position~Position#_getTransformedByMoveOperation
Returns a copy of this position transformed by a move operation.
Parameters
operation : MoveOperation
Returns
-
protected
_getTransformedBySplitOperation( operation ) → Position
module:engine/model/position~Position#_getTransformedBySplitOperation
Returns a copy of this position transformed by a split operation.
Parameters
operation : SplitOperation
Returns
Static methods
-
protected static
_createAfter( item, [ stickiness ] ) → Position
module:engine/model/position~Position._createAfter
Creates a new position, after given model item.
Parameters
item : Item
Item after which the position should be placed.
[ stickiness ] : PositionStickiness
Position stickiness.
Defaults to
'toNone'
Returns
-
protected static
_createAt( itemOrPosition, [ offset ], [ stickiness ] )
module:engine/model/position~Position._createAt
Creates position at the given location. The location can be specified as:
- 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'
-
protected static
_createBefore( item, [ stickiness ] ) → Position
module:engine/model/position~Position._createBefore
Creates a new position, before the given model item.
Parameters
item : Item
Item before which the position should be placed.
[ stickiness ] : PositionStickiness
Position stickiness.
Defaults to
'toNone'
Returns
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.