RootElement (engine/model)

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

Properties

• childCount : Numbermodule:engine/model/rootelement~RootElement#childCount

  readonly inherited

  Number of this element's children.

  See source

• document : Document | nullmodule:engine/model/rootelement~RootElement#document

  readonly

  Document that owns this root element.

  See source

• endOffset : Number | nullmodule:engine/model/rootelement~RootElement#endOffset

  readonly inherited

  Offset at which this node ends in it's parent. It is equal to the sum of this node's start offset and offset size. Equals to null if the node has no parent.

  See source

• index : Number | nullmodule:engine/model/rootelement~RootElement#index

  readonly inherited

  Index of this node in it's parent or null if the node has no parent.

  See source

  Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.

• isEmpty : Booleanmodule:engine/model/rootelement~RootElement#isEmpty

  readonly inherited

  Is true if there are no nodes inside this element, false otherwise.

  See source

• maxOffset : Numbermodule:engine/model/rootelement~RootElement#maxOffset

  readonly inherited

  Sum of offset sizes of all of this element's children.

  See source

• name : Stringmodule:engine/model/rootelement~RootElement#name

  readonly inherited

  Element name.

  See source

• nextSibling : Node | nullmodule:engine/model/rootelement~RootElement#nextSibling

  readonly inherited

  Node's next sibling or null if the node is a last child of it's parent or if the node has no parent.

  See source

• offsetSize : Numbermodule:engine/model/rootelement~RootElement#offsetSize

  readonly inherited

  Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent. It is important for position. When node has offsetSize greater than 1, position can be placed between that node start and end. offsetSize greater than 1 is for nodes that represents more than one entity, i.e. text node.

  See source

• parent : Element | DocumentFragment | nullmodule:engine/model/rootelement~RootElement#parent

  readonly inherited

  Parent of this node. It could be Element or DocumentFragment. Equals to null if the node has no parent.

  See source

• previousSibling : Node | nullmodule:engine/model/rootelement~RootElement#previousSibling

  readonly inherited

  Node's previous sibling or null if the node is a first child of it's parent or if the node has no parent.

  See source

• root : Node | DocumentFragmentmodule:engine/model/rootelement~RootElement#root

  readonly inherited

  The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part of DocumentFragment, it's root is equal to that DocumentFragment.

  See source

• rootName : Stringmodule:engine/model/rootelement~RootElement#rootName

  readonly

  Unique root name used to identify this root element by Document.

  See source

• startOffset : Number | nullmodule:engine/model/rootelement~RootElement#startOffset

  readonly inherited

  Offset at which this node starts in it's parent. It is equal to the sum of offsetSize of all it's previous siblings. Equals to null if node has no parent.

  See source

  Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.

• _attrs : Mapmodule:engine/model/rootelement~RootElement#_attrs

  private inherited

  Attributes set on this node.

  See source

• _children : NodeListmodule:engine/model/rootelement~RootElement#_children

  private inherited

  List of children nodes.

  See source

• _document : Documentmodule:engine/model/rootelement~RootElement#_document

  private

  Document that is an owner of this root.

  See source

Methods

• constructor( document, name, [ rootName ] )module:engine/model/rootelement~RootElement#constructor

  Creates root element.

  See source

  Parameters

  document : Document

  Document that is an owner of this root.

  name : String

  Node name.

  [ rootName ] : String

  Unique root name used to identify this root element by Document.

  Defaults to 'main'

• findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | nullmodule:engine/model/rootelement~RootElement#findAncestor

  inherited

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

  See source

  Parameters

  parentName : String

  The name of the parent element to find.

  [ options ] : Object

  Options object.

  Properties

  [ options.includeSelf ] : Boolean

  When set to true this node will be also included while searching.

  Defaults to false

  Returns

  Element | null

• getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Arraymodule:engine/model/rootelement~RootElement#getAncestors

  inherited

  Returns ancestors array of this node.

  See source

  Parameters

  options : Object

  Options object.

  Properties

  [ options.includeSelf ] : Boolean

  When set to true this node will be also included in parent's array.

  Defaults to false

  [ options.parentFirst ] : Boolean

  When set to true, array will be sorted from node's parent to root element, otherwise root element will be the first item in the array.

  Defaults to false

  Returns

  Array

  Array with ancestors.

• getAttribute( key ) → *module:engine/model/rootelement~RootElement#getAttribute

  inherited

  Gets an attribute value for given key or undefined if that attribute is not set on node.

  See source

  Parameters

  key : String

  Key of attribute to look for.

  Returns

  *

  Attribute value or undefined.

• getAttributeKeys() → Iterable.<String>module:engine/model/rootelement~RootElement#getAttributeKeys

  inherited

  Returns iterator that iterates over this node's attribute keys.

  See source

  Returns

  Iterable.<String>

• getAttributes() → Iterable.<*>module:engine/model/rootelement~RootElement#getAttributes

  inherited

  Returns iterator that iterates over this node's attributes.

  See source

  Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native Map object and also can be passed in Node constructor.

  Returns

  Iterable.<*>

• getChild( index ) → Nodemodule:engine/model/rootelement~RootElement#getChild

  inherited

  Gets the child at the given index.

  See source

  Parameters

  index : Number

  Index of child.

  Returns

  Node

  Child node.

• getChildIndex( node ) → Numbermodule:engine/model/rootelement~RootElement#getChildIndex

  inherited

  Returns an index of the given child node. Returns null if given node is not a child of this element.

  See source

  Parameters

  node : Node

  Child node to look for.

  Returns

  Number

  Child node's index in this element.

• getChildStartOffset( node ) → Numbermodule:engine/model/rootelement~RootElement#getChildStartOffset

  inherited

  Returns the starting offset of given child. Starting offset is equal to the sum of offset sizes of all node's siblings that are before it. Returns null if given node is not a child of this element.

  See source

  Parameters

  node : Node

  Child node to look for.

  Returns

  Number

  Child node's starting offset.

• getChildren() → Iterable.<Node>module:engine/model/rootelement~RootElement#getChildren

  inherited

  Returns an iterator that iterates over all of this element's children.

  See source

  Returns

  Iterable.<Node>

• getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | nullmodule:engine/model/rootelement~RootElement#getCommonAncestor

  inherited

  Returns a Element or DocumentFragment which is a common ancestor of both nodes.

  See source

  Parameters

  node : Node

  The second node.

  options : Object

  Options object.

  Properties

  [ options.includeSelf ] : Boolean

  When set to true both nodes will be considered "ancestors" too. Which means that if e.g. node A is inside B, then their common ancestor will be B.

  Defaults to false

  Returns

  Element | DocumentFragment | null

• getNodeByPath( relativePath ) → Nodemodule:engine/model/rootelement~RootElement#getNodeByPath

  inherited

  Returns a descendant node by its path relative to this element.

  See source

  // <this>a<b>c</b></this>
  this.getNodeByPath( [ 0 ] );     // -> "a"
  this.getNodeByPath( [ 1 ] );     // -> <b>
  this.getNodeByPath( [ 1, 0 ] );  // -> "c"

  Copy

  Parameters

  relativePath : Array.<Number>

  Path of the node to find, relative to this element.

  Returns

  Node

• getPath() → Array.<Number>module:engine/model/rootelement~RootElement#getPath

  inherited

  Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node, beginning from root, down to this node's starting offset. The path can be used to create Position instance.

  See source

  const abc = new Text( 'abc' );
  const foo = new Text( 'foo' );
  const h1 = new Element( 'h1', null, new Text( 'header' ) );
  const p = new Element( 'p', null, [ abc, foo ] );
  const div = new Element( 'div', null, [ h1, p ] );
  foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
  h1.getPath(); // Returns [ 0 ].
  div.getPath(); // Returns [].

  Copy

  Returns

  Array.<Number>

  The path.

• hasAttribute( key ) → Booleanmodule:engine/model/rootelement~RootElement#hasAttribute

  inherited

  Checks if the node has an attribute with given key.

  See source

  Parameters

  key : String

  Key of attribute to check.

  Returns

  Boolean

  true if attribute with given key is set on node, false otherwise.

• is( type ) → Booleanmodule:engine/model/rootelement~RootElement#is

  inherited

  Checks whether this object is of the given type.

  See source

  This method is useful when processing model objects that are of unknown type. For example, a function may return a DocumentFragment or a Node that can be either a text node or an element. This method can be used to check what kind of object is returned.

  someObject.is( 'element' ); // -> true if this is an element
  someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
  someObject.is( 'documentFragment' ); // -> true if this is a document fragment
  

  Copy

  Since this method is also available on a range of view objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:

  modelElement.is( 'model:element' ); // -> true
  modelElement.is( 'view:element' ); // -> false
  

  Copy

  By using this method it is also possible to check a name of an element:

  imageElement.is( 'element', 'imageBlock' ); // -> true
  imageElement.is( 'element', 'imageBlock' ); // -> same as above
  imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
  

  Copy

  The list of model objects which implement the is() method:

  • Node#is()
  • Text#is()
  • Element#is()
  • RootElement#is()
  • Position#is()
  • LivePosition#is()
  • Range#is()
  • LiveRange#is()
  • DocumentFragment#is()
  • Selection#is()
  • DocumentSelection#is()
  • Marker#is()
  • TextProxy#is()

  Parameters

  type : String

  Type to check.

  Returns

  Boolean

• isAfter( node ) → Booleanmodule:engine/model/rootelement~RootElement#isAfter

  inherited

  Returns whether this node is after given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

  See source

  Parameters

  node : Node

  Node to compare with.

  Returns

  Boolean

• isAttached() → Booleanmodule:engine/model/rootelement~RootElement#isAttached

  inherited

  Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).

  See source

  Returns

  Boolean

• isBefore( node ) → Booleanmodule:engine/model/rootelement~RootElement#isBefore

  inherited

  Returns whether this node is before given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

  See source

  Parameters

  node : Node

  Node to compare with.

  Returns

  Boolean

• offsetToIndex( offset ) → Numbermodule:engine/model/rootelement~RootElement#offsetToIndex

  inherited

  Returns index of a node that occupies given offset. If given offset is too low, returns 0. If given offset is too high, returns index after last child.

  See source

  const textNode = new Text( 'foo' );
  const pElement = new Element( 'p' );
  const divElement = new Element( [ textNode, pElement ] );
  divElement.offsetToIndex( -1 ); // Returns 0, because offset is too low.
  divElement.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
  divElement.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
  divElement.offsetToIndex( 2 ); // Returns 0.
  divElement.offsetToIndex( 3 ); // Returns 1.
  divElement.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.

  Copy

  Parameters

  offset : Number

  Offset to look for.

  Returns

  Number

• toJSON() → Objectmodule:engine/model/rootelement~RootElement#toJSON

  inherited

  Converts Node to plain object and returns it.

  See source

  Returns

  Object

  Node converted to plain object.

• _appendChild( nodes )module:engine/model/rootelement~RootElement#_appendChild

  protected inherited

  Inserts one or more nodes at the end of this element.

  See source

  Parameters

  nodes : Item | Iterable.<Item>

  Nodes to be inserted.

  Related:

  • Writer#append

• _clearAttributes()module:engine/model/rootelement~RootElement#_clearAttributes

  protected inherited

  Removes all attributes from the node.

  See source

  Related:

  • Writer#clearAttributes

• _clone( [ deep ] )module:engine/model/rootelement~RootElement#_clone

  protected inherited

  Creates a copy of this element and returns it. Created element has the same name and attributes as the original element. If clone is deep, the original element's children are also cloned. If not, then empty element is returned.

  See source

  Parameters

  [ deep ] : Boolean

  If set to true clones element and all its children recursively. When set to false, element will be cloned without any child.

  Defaults to false

• _insertChild( index, items )module:engine/model/rootelement~RootElement#_insertChild

  protected inherited

  Inserts one or more nodes at the given index and sets parent of these nodes to this element.

  See source

  Parameters

  index : Number

  Index at which nodes should be inserted.

  items : Item | Iterable.<Item>

  Items to be inserted.

  Related:

  • Writer#insert

• _remove()module:engine/model/rootelement~RootElement#_remove

  protected inherited

  Removes this node from it's parent.

  See source

  Related:

  • Writer#remove

• _removeAttribute( key ) → Booleanmodule:engine/model/rootelement~RootElement#_removeAttribute

  protected inherited

  Removes an attribute with given key from the node.

  See source

  Parameters

  key : String

  Key of attribute to remove.

  Returns

  Boolean

  true if the attribute was set on the element, false otherwise.

  Related:

  • Writer#removeAttribute

• _removeChildren( index, [ howMany ] ) → Array.<Node>module:engine/model/rootelement~RootElement#_removeChildren

  protected inherited

  Removes one or more nodes starting at the given index and sets parent of these nodes to null.

  See source

  Parameters

  index : Number

  Index of the first node to remove.

  [ howMany ] : Number

  Number of nodes to remove.

  Defaults to 1

  Returns

  Array.<Node>

  Array containing removed nodes.

  Related:

  • Writer#remove

• _setAttribute( key, value )module:engine/model/rootelement~RootElement#_setAttribute

  protected inherited

  Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.

  See source

  Parameters

  key : String

  Key of attribute to set.

  value : *

  Attribute value.

  Related:

  • Writer#setAttribute

• _setAttributesTo( [ attrs ] )module:engine/model/rootelement~RootElement#_setAttributesTo

  protected inherited

  Removes all attributes from the node and sets given attributes.

  See source

  Parameters

  [ attrs ] : Object

  Attributes to set. See toMap for a list of accepted values.

  Related:

  • Writer#setAttributes

Static methods

• fromJSON( json ) → Elementmodule:engine/model/rootelement~RootElement.fromJSON

  inherited static

  Creates an Element instance from given plain object (i.e. parsed JSON string). Converts Element children to proper nodes.

  See source

  Parameters

  json : Object

  Plain object to be converted to Element.

  Returns

  Element

  Element instance created using given plain object.