ContainerElement (engine/view)
@ckeditor/ckeditor5-engine/src/view/containerelement
Containers are elements which define document structure. They define boundaries for
attributes. They are mostly used for block elements like <p>
or <div>
.
Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various types (container element, attribute element, empty element, etc) when developing a feature.
The container element should be your default choice when writing a converter, unless:
- this element represents a model text attribute (then use
AttributeElement
), - this is an empty element like
<img>
(then useEmptyElement
), - this is a root element,
- this is a nested editable element (then use
EditableElement
).
To create a new container element instance use the
DowncastWriter#createContainerElement()
method.
Filtering
Properties
-
readonly inherited
childCount : Number
module:engine/view/containerelement~ContainerElement#childCount
Number of element's children.
-
The document instance to which this node belongs.
-
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.
-
Is
true
if there are no nodes inside this element,false
otherwise. -
Name of the element.
-
readonly inherited
nextSibling : Node | null
module:engine/view/containerelement~ContainerElement#nextSibling
Node's next sibling, or
null
if it is the last child. -
readonly inherited
parent : Element | DocumentFragment | null
module:engine/view/containerelement~ContainerElement#parent
Parent element. Null by default. Set by
_insertChild
. -
readonly inherited
previousSibling : Node | null
module:engine/view/containerelement~ContainerElement#previousSibling
Node's previous sibling, or
null
if it is the first child. -
readonly inherited
root : Node | DocumentFragment
module:engine/view/containerelement~ContainerElement#root
Top-most ancestor of the node. If the node has no parent it is the root itself.
-
Map of attributes, where attributes names are keys and attributes values are values.
-
protected inherited
_children : Array.<Node>
module:engine/view/containerelement~ContainerElement#_children
Array of child nodes.
-
Set of classes associated with element instance.
-
protected inherited
_customProperties : Map
module:engine/view/containerelement~ContainerElement#_customProperties
Map of custom properties. Custom properties can be added to element instance, will be cloned but not rendered into DOM.
-
Normalized styles.
-
private readonly inherited
_unsafeAttributesToRender : Array.<String>
module:engine/view/containerelement~ContainerElement#_unsafeAttributesToRender
A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms implemented in the
DomConverter
(for instance,shouldRenderAttribute
) would filter them out.These attributes can be specified as an option when the element is created by the
DowncastWriter
. To check whether an unsafe an attribute should be permitted, use theshouldRenderUnsafeAttribute
method.
Methods
-
protected
constructor( document, name, [ attrs ], [ children ] )
module:engine/view/containerelement~ContainerElement#constructor
-
inherited
findAncestor( patterns ) → Element | null
module:engine/view/containerelement~ContainerElement#findAncestor
Returns ancestor element that match specified pattern. Provided patterns should be compatible with Matcher as it is used internally.
Parameters
patterns : Object | String | RegExp | function
Patterns used to match correct ancestor. See
Matcher
.
Returns
Element | null
Found element or
null
if no matching ancestor was found.
Related:
-
inherited
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array
module:engine/view/containerelement~ContainerElement#getAncestors
Returns ancestors array of this node.
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.
-
inherited
getAttribute( key ) → String | undefined
module:engine/view/containerelement~ContainerElement#getAttribute
Gets attribute by key. If attribute is not present - returns undefined.
Parameters
key : String
Attribute key.
Returns
String | undefined
Attribute value.
-
inherited
getAttributeKeys() → Iterable.<String>
module:engine/view/containerelement~ContainerElement#getAttributeKeys
Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.
Returns
Iterable.<String>
Keys for attributes.
-
inherited
getAttributes() → Iterable.<*>
module:engine/view/containerelement~ContainerElement#getAttributes
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
Map
object and also can be passed inNode
constructor.Returns
Iterable.<*>
-
-
inherited
getChildIndex( node ) → Number
module:engine/view/containerelement~ContainerElement#getChildIndex
Gets index of the given child node. Returns
-1
if child node is not found.Parameters
node : Node
Child node.
Returns
Number
Index of the child node.
-
inherited
getChildren() → Iterable.<Node>
module:engine/view/containerelement~ContainerElement#getChildren
-
inherited
getClassNames() → Iterable.<String>
module:engine/view/containerelement~ContainerElement#getClassNames
-
inherited
getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null
module:engine/view/containerelement~ContainerElement#getCommonAncestor
Returns a
Element
orDocumentFragment
which is a common ancestor of both nodes.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
-
inherited
getCustomProperties() → Iterable.<*>
module:engine/view/containerelement~ContainerElement#getCustomProperties
Returns an iterator which iterates over this element's custom properties. Iterator provides
[ key, value ]
pairs for each stored property.Returns
Iterable.<*>
-
inherited
getCustomProperty( key ) → *
module:engine/view/containerelement~ContainerElement#getCustomProperty
Returns the custom property value for the given key.
Parameters
key : String | Symbol
Returns
*
-
inherited
getFillerOffset() → Number | null
module:engine/view/containerelement~ContainerElement#getFillerOffset
Returns block filler offset or
null
if block filler is not needed.Returns
Number | null
Block filler offset or
null
if block filler is not needed.
-
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
-
inherited
getNormalizedStyle( property ) → Object | String | undefined
module:engine/view/containerelement~ContainerElement#getNormalizedStyle
Returns a normalized style object or single style value.
For an element with style set to: margin:1px 2px 3em;
element.getNormalizedStyle( 'margin' ) );
will return:
{ top: '1px', right: '2px', bottom: '3em', left: '2px' // a normalized value from margin shorthand }
and reading for single style value:
styles.getNormalizedStyle( 'margin-left' );
Will return a
2px
string.Note: This method will return normalized values only if a particular style processor rule is enabled. See
StylesMap#getNormalized()
for details.Parameters
property : String
Name of CSS property
Returns
Object | String | undefined
-
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 = downcastWriter.createText( 'abc' ); const foo = downcastWriter.createText( 'foo' ); const h1 = downcastWriter.createElement( 'h1', null, downcastWriter.createText( 'header' ) ); const p = downcastWriter.createElement( 'p', null, [ abc, foo ] ); const div = downcastWriter.createElement( '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.
-
inherited
getStyle( property ) → String | undefined
module:engine/view/containerelement~ContainerElement#getStyle
Returns style value for the given property mae. If the style does not exist
undefined
is returned.Note: This method can work with normalized style names if a particular style processor rule is enabled. See
StylesMap#getAsString()
for details.For an element with style set to
'margin:1px'
:// Enable 'margin' shorthand processing: editor.data.addStyleProcessorRules( addMarginRules ); const element = view.change( writer => { const element = writer.createElement(); writer.setStyle( 'margin', '1px' ); writer.setStyle( 'margin-bottom', '3em' ); return element; } ); element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'
Parameters
property : String
Returns
String | undefined
-
inherited
getStyleNames( [ expand ] ) → Iterable.<String>
module:engine/view/containerelement~ContainerElement#getStyleNames
Returns iterator that contains all style names.
Parameters
[ expand ] : Boolean
Expand shorthand style properties and return all equivalent style representations.
Defaults to
false
Returns
Iterable.<String>
-
inherited
hasAttribute( key ) → Boolean
module:engine/view/containerelement~ContainerElement#hasAttribute
Returns a boolean indicating whether an attribute with the specified key exists in the element.
Parameters
key : String
Attribute key.
Returns
Boolean
true
if attribute with the specified key exists in the element, false otherwise.
-
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
-
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
-
Checks whether this object is of the given type.
This method is useful when processing view objects that are of unknown type. For example, a function may return a
DocumentFragment
or aNode
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
Since this method is also available on a range of model objects, you can prefix the type of the object with
model:
orview:
to check, for example, if this is the model's or view's element:viewElement.is( 'view:element' ); // -> true viewElement.is( 'model:element' ); // -> false
By using this method it is also possible to check a name of an element:
imgElement.is( 'element', 'img' ); // -> true imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise
The list of view objects which implement the
is()
method:AttributeElement#is()
ContainerElement#is()
DocumentFragment#is()
DocumentSelection#is()
EditableElement#is()
Element#is()
EmptyElement#is()
Node#is()
Position#is()
Range#is()
RootEditableElement#is()
Selection#is()
Text#is()
TextProxy#is()
UIElement#is()
Parameters
type : String
Type to check.
Returns
Boolean
-
Returns whether this node is after given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
Boolean
-
Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).
Returns
Boolean
-
Returns whether this node is before given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
Boolean
-
inherited
isSimilar( otherElement ) → Boolean
module:engine/view/containerelement~ContainerElement#isSimilar
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.
Parameters
otherElement : Element
Returns
Boolean
-
inherited
shouldRenderUnsafeAttribute( attributeName ) → Boolean
module:engine/view/containerelement~ContainerElement#shouldRenderUnsafeAttribute
Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms like
shouldRenderAttribute
say it should not.Unsafe attribute names can be specified when creating an element via
DowncastWriter
.Parameters
attributeName : String
The name of the attribute to be checked.
Returns
Boolean
-
Custom toJSON method to solve child-parent circular dependencies.
Returns
Object
Clone of this object with the parent property removed.
-
protected inherited
_addClass( className )
module:engine/view/containerelement~ContainerElement#_addClass
Adds specified class.
element._addClass( 'foo' ); // Adds 'foo' class. element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.
Parameters
className : Array.<String> | String
Fires
Related:
-
protected inherited
_appendChild( items ) → Number
module:engine/view/containerelement~ContainerElement#_appendChild
Insert a child node or a list of child nodes at the end of this node and sets the parent of these nodes to this element.
Parameters
Returns
Number
Number of appended nodes.
Fires
Related:
-
protected inherited
_clone( [ deep ] ) → Element
module:engine/view/containerelement~ContainerElement#_clone
Clones provided element.
Parameters
[ deep ] : Boolean
If set to
true
clones element and all its children recursively. When set tofalse
, element will be cloned without any children.Defaults to
false
Returns
Element
Clone of this element.
-
protected inherited
_fireChange( type, node )
module:engine/view/containerelement~ContainerElement#_fireChange
-
protected inherited
_insertChild( index, items ) → Number
module:engine/view/containerelement~ContainerElement#_insertChild
-
Removes node from parent.
-
protected inherited
_removeAttribute( key ) → Boolean
module:engine/view/containerelement~ContainerElement#_removeAttribute
Removes attribute from the element.
Parameters
key : String
Attribute key.
Returns
Boolean
Returns true if an attribute existed and has been removed.
Fires
Related:
-
protected inherited
_removeChildren( index, [ howMany ] ) → Array.<Node>
module:engine/view/containerelement~ContainerElement#_removeChildren
Removes number of child nodes starting at the given index and set the parent of these nodes to
null
.Parameters
index : Number
Number of the first node to remove.
[ howMany ] : Number
Number of nodes to remove.
Defaults to
1
Returns
Array.<Node>
The array of removed nodes.
Fires
Related:
-
protected inherited
_removeClass( className )
module:engine/view/containerelement~ContainerElement#_removeClass
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
Related:
-
protected inherited
_removeCustomProperty( key ) → Boolean
module:engine/view/containerelement~ContainerElement#_removeCustomProperty
Removes the custom property stored under the given key.
Parameters
key : String | Symbol
Returns
Boolean
Returns true if property was removed.
Related:
-
protected inherited
_removeStyle( property )
module:engine/view/containerelement~ContainerElement#_removeStyle
Removes specified style.
element._removeStyle( 'color' ); // Removes 'color' style. element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.
Note: This method can work with normalized style names if a particular style processor rule is enabled. See
StylesMap#remove()
for details.Parameters
property : Array.<String> | String
Fires
Related:
-
protected inherited
_setAttribute( key, value )
module:engine/view/containerelement~ContainerElement#_setAttribute
Adds or overwrite attribute with a specified key and value.
Parameters
key : String
Attribute key.
value : String
Attribute value.
Fires
Related:
-
protected inherited
_setCustomProperty( key, value )
module:engine/view/containerelement~ContainerElement#_setCustomProperty
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 | Symbol
value : *
Related:
-
protected inherited
_setStyle( property, [ value ] )
module:engine/view/containerelement~ContainerElement#_setStyle
Adds style to the element.
element._setStyle( 'color', 'red' ); element._setStyle( { color: 'red', position: 'fixed' } );
Note: This method can work with normalized style names if a particular style processor rule is enabled. See
StylesMap#set()
for details.Parameters
property : String | Object
Property name or object with key - value pairs.
[ value ] : String
Value to set. This parameter is ignored if object is provided as the first parameter.
Fires
Related:
Events
-
-
inherited
change:attributes( eventInfo, changedNode )
module:engine/view/containerelement~ContainerElement#event:change:attributes
Fired when list of elements attributes changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
-
inherited
change:children( eventInfo, changedNode )
module:engine/view/containerelement~ContainerElement#event:change:children
Fired when list of elements children changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
-
inherited
change:text( eventInfo, changedNode )
module:engine/view/containerelement~ContainerElement#event:change:text
Fired when text nodes data changes.
Change event is bubbled – it is fired on all ancestors.
Parameters
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.