ContainerElement (engine/view)
@ckeditor/ckeditor5-engine/src/view/containerelement
Containers are elements which define document structure. They define boundaries for
attributes. They are mostly use for block elements like <p> or <div>.
Editing engine does not define fixed HTML DTD. This is why the type of the Element need to
be defined by the feature developer.
Creating an element you should use ContainerElement class or AttributeElement. This is
important to define the type of the element because of two reasons:
Firstly, DomConverter needs the information what is an editable block to convert elements to
DOM properly. DomConverter will ensure that ContainerElement is editable and it is possible
to put caret inside it, even if the container is empty.
Secondly, view downcast writer uses this information. Nodes breaking and merging is performed only in a bounds of a container nodes.
For instance if <p> is an container and <b> is attribute:
<p><b>fo^o</b></p>breakAttributes will create:
<p><b>fo</b><b>o</b></p>There might be a need to mark <span> element as a container node, for example in situation when it will be a
container of an inline widget:
<span color="red">foobar</span> // attribute
<span data-widget>foobar</span> // containerFiltering
Properties
-
childCount : Numberreadonly inherited
Number of element's children.
-
View document that owns this node, or
nullif the node is inside document fragment. -
index : Number | nullreadonly inherited
Index of the node in the parent element or null if the node has no parent.
Accessing this property throws an error if this node's parent element does not contain it. This means that view tree got broken.
-
isEmpty : Booleanreadonly inherited
Is
trueif there are no nodes inside this element,falseotherwise. -
name : Stringreadonly inherited
Name of the element.
-
nextSibling : Node | nullreadonly inherited
Node's next sibling, or
nullif it is the last child. -
parent : Element | DocumentFragment | nullreadonly inherited
Parent element. Null by default. Set by
_insertChild. -
previousSibling : Node | nullreadonly inherited
Node's previous sibling, or
nullif it is the first child. -
root : Node | DocumentFragmentreadonly inherited
Top-most ancestor of the node. If the node has no parent it is the root itself.
-
_attrs : Mapprotected inherited
Map of attributes, where attributes names are keys and attributes values are values.
-
Array of child nodes.
-
_classes : Setprotected inherited
Set of classes associated with element instance.
-
_customPropertiesprotected inherited
Map of custom properties. Custom properties can be added to element instance, will be cloned but not rendered into DOM.
-
_styles : Setprotected inherited
Map of styles.
Methods
-
constructor()protected
Creates a container element.
Overrides: Element#constructor -
_fireChange( type, node )inherited
-
_removeChildren( index, [ howMany ] ) → Array.<Node>inherited
-
_removeClass( className )inherited
Removes specified class.
element._removeClass( 'foo' ); // Removes 'foo' class. element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.Parameters
className : Array.<String> | String
Fires
-
findAncestor( patterns ) → Element | nullinherited
Returns ancestor element that match specified pattern. Provided patterns should be compatible with Matcher as it is used internally.
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Arrayinherited
Returns ancestors array of this node.
Parameters
options : ObjectOptions object.
Properties[ options.includeSelf ] : BooleanWhen set to
truethis node will be also included in parent's array.Defaults to
false[ options.parentFirst ] : BooleanWhen 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
ArrayArray with ancestors.
-
getAttribute( key ) → String | undefinedinherited
Gets attribute by key. If attribute is not present - returns undefined.
Parameters
key : StringAttribute key.
Returns
String | undefinedAttribute value.
-
getAttributeKeys() → Iterable.<String>inherited
Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.
Returns
Iterable.<String>Keys for attributes.
-
getAttributes() → Iterable.<*>inherited
Returns iterator that iterates over this element's attributes.
Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native
Mapobject and also can be passed inNodeconstructor.Returns
Iterable.<*>
-
Gets child at the given index.
-
getChildIndex( node ) → Numberinherited
Gets index of the given child node. Returns
-1if child node is not found. -
getChildren() → Iterable.<Node>inherited
Gets child nodes iterator.
Returns
Iterable.<Node>Child nodes iterator.
-
getClassNames() → Iterable.<String>inherited
Returns iterator that contains all class names.
Returns
Iterable.<String>
-
getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | nullinherited
Returns a
ElementorDocumentFragmentwhich is a common ancestor of both nodes.Parameters
node : NodeThe second node.
options : ObjectOptions object.
Properties[ options.includeSelf ] : BooleanWhen set to
trueboth 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
-
getCustomProperties() → Iterable.<*>inherited
Returns an iterator which iterates over this element's custom properties. Iterator provides
[ key, value ]pairs for each stored property.Returns
Iterable.<*>
-
getCustomProperty( key ) → *inherited
Returns the custom property value for the given key.
Parameters
key : String | Symbol
Returns
*
-
getFillerOffset() → Number | nullReturns block filler offset or
nullif block filler is not needed.Returns
Number | nullBlock filler offset or
nullif block filler is not needed.
Overrides: Element#getFillerOffset -
getIdentity() → Stringinherited
Returns identity string based on element's name, styles, classes and other attributes. Two elements that are similar will have same identity string. It has the following format:
'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'For example:
const element = writer.createContainerElement( 'foo', { banana: '10', apple: '20', style: 'color: red; border-color: white;', class: 'baz' } ); // returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"' element.getIdentity();NOTE: Classes, styles and other attributes are sorted alphabetically.
Returns
String
-
getPath() → Array.<Number>inherited
Gets a path to the node. The path is an array containing indices of consecutive ancestors of this node, beginning from root, down to this node's index.
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 [].Returns
Array.<Number>The path.
-
getStyle( property ) → String | undefinedinherited
Returns style value for given property. Undefined is returned if style does not exist.
Parameters
property : String
Returns
String | undefined
-
getStyleNames() → Iterable.<String>inherited
Returns iterator that contains all style names.
Returns
Iterable.<String>
-
hasAttribute( key ) → Booleaninherited
Returns a boolean indicating whether an attribute with the specified key exists in the element.
Parameters
key : StringAttribute key.
Returns
Booleantrueif attribute with the specified key exists in the element, false otherwise.
-
hasClass( className )inherited
Returns true if class is present. If more then one class is provided - returns true only when all classes are present.
element.hasClass( 'foo' ); // Returns true if 'foo' class is present. element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.Parameters
className : String
-
hasStyle( property )inherited
Returns true if style keys are present. If more then one style property is provided - returns true only when all properties are present.
element.hasStyle( 'color' ); // Returns true if 'border-top' style is present. element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.Parameters
property : String
-
is( type, [ name ] ) → Booleaninherited
Checks whether given view tree object is of given type.
Read more in
is.Parameters
type : String[ name ] : StringElement name.
Returns
Boolean
Overrides: Element#is -
isAfter( node ) → Booleaninherited
Returns whether this node is after given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments). -
isBefore( node ) → Booleaninherited
Returns whether this node is before given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments). -
isSimilar( otherElement ) → Booleaninherited
Checks if this element is similar to other element. Both elements should have the same name and attributes to be considered as similar. Two similar elements can contain different set of children nodes.
-
toJSON() → Objectinherited
Custom toJSON method to solve child-parent circular dependencies.
Returns
ObjectClone of this object with the parent property removed.
-
_addClass( className )protected inherited
Adds specified class.
element._addClass( 'foo' ); // Adds 'foo' class. element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.Parameters
className : Array.<String> | String
Fires
-
_appendChild( items ) → Numberprotected inherited
-
Clones provided element.
Parameters
[ deep ] : BooleanIf set to
trueclones element and all its children recursively. When set tofalse, element will be cloned without any children.Defaults to
false
Returns
ElementClone of this element.
-
_insertChild( index, items ) → Numberprotected inherited
-
_remove()protected inherited
Removes node from parent.
-
_removeAttribute( key ) → Booleanprotected inherited
Removes attribute from the element.
Parameters
key : StringAttribute key.
Returns
BooleanReturns true if an attribute existed and has been removed.
Fires
-
_removeCustomProperty( key ) → Booleanprotected inherited
Removes the custom property stored under the given key.
Parameters
key : String | Symbol
Returns
BooleanReturns true if property was removed.
-
_removeStyle( property )protected inherited
Removes specified style.
element._removeStyle( 'color' ); // Removes 'color' style. element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.Parameters
property : Array.<String> | String
Fires
-
_setAttribute( key, value )protected inherited
Adds or overwrite attribute with a specified key and value.
-
_setCustomProperty( key, value )protected inherited
Sets a custom property. Unlike attributes, custom properties are not rendered to the DOM, so they can be used to add special data to elements.
Parameters
key : String | Symbolvalue : *
-
_setStyle( property, [ value ] )protected inherited
Adds style to the element.
element._setStyle( 'color', 'red' ); element._setStyle( { color: 'red', position: 'fixed' } );Parameters
property : String | ObjectProperty name or object with key - value pairs.
[ value ] : StringValue to set. This parameter is ignored if object is provided as the first parameter.
Fires
Events
-
change( eventInfo )inherited
Parameters
eventInfo : EventInfoAn object containing information about the fired event.
-
change:attributes( eventInfo, changedNode )inherited
-
change:children( eventInfo, changedNode )inherited
-
change:text( eventInfo, changedNode )inherited
Fired when text nodes data changes.