DocumentFragment (engine/view)
@ckeditor/ckeditor5-engine/src/view/documentfragment
Document fragment.
To create a new document fragment instance use the
UpcastWriter#createDocumentFragment()
method.
Filtering
Properties
-
Number of child nodes in this document fragment.
-
The document to which this document fragment belongs.
-
readonly
getFillerOffset : undefined
module:engine/view/documentfragment~DocumentFragment#getFillerOffset
Artificial element getFillerOffset. Returns
undefined
. Added for compatibility reasons. -
Is
true
if there are no nodes inside this document fragment,false
otherwise. -
Artificial element name. Returns
undefined
. Added for compatibility reasons. -
Artificial parent of
DocumentFragment
. Returnsnull
. Added for compatibility reasons. -
Artificial root of
DocumentFragment
. Returns itself. Added for compatibility reasons. -
private readonly
_children : Array<Node>
module:engine/view/documentfragment~DocumentFragment#_children
Array of child nodes.
-
private readonly
_customProperties : Map<string | symbol, unknown>
module:engine/view/documentfragment~DocumentFragment#_customProperties
Map of custom properties. Custom properties can be added to document fragment instance.
Methods
-
internal
constructor( document, [ children ] )
module:engine/view/documentfragment~DocumentFragment#constructor
Creates new DocumentFragment instance.
Parameters
-
Symbol.iterator() → Iterator<Node, any, undefined>
module:engine/view/documentfragment~DocumentFragment#Symbol.iterator
Iterable interface.
Iterates over nodes added to this document fragment.
Returns
Iterator<Node, any, undefined>
-
inherited
delegate( events ) → EmitterMixinDelegateChain
module:engine/view/documentfragment~DocumentFragment#delegate
Delegates selected events to another
Emitter
. For instance:emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then
eventX
is delegated (fired by)emitterB
andemitterC
along withdata
:emitterA.fire( 'eventX', data );
and
eventY
is delegated (fired by)emitterC
along withdata
:emitterA.fire( 'eventY', data );
Parameters
events : Array<string>
Event names that will be delegated to another emitter.
Returns
-
inherited
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
module:engine/view/documentfragment~DocumentFragment#fire
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfo
object, followed by the optionalargs
provided in thefire()
method call.Type parameters
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>
The name of the event or
EventInfo
object if event is delegated.args : TEvent[ 'args' ]
Additional arguments to be passed to the callbacks.
Returns
GetEventInfo<TEvent>[ 'return' ]
By default the method returns
undefined
. However, the return value can be changed by listeners through modification of theevt.return
's property (the event info is the first param of every callback).
-
-
getChildIndex( node ) → number
module:engine/view/documentfragment~DocumentFragment#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.
-
getChildren() → IterableIterator<Node>
module:engine/view/documentfragment~DocumentFragment#getChildren
-
getCustomProperties() → Iterable<tuple>
module:engine/view/documentfragment~DocumentFragment#getCustomProperties
Returns an iterator which iterates over this document fragment's custom properties. Iterator provides
[ key, value ]
pairs for each stored property.Returns
Iterable<tuple>
-
getCustomProperty( key ) → unknown
module:engine/view/documentfragment~DocumentFragment#getCustomProperty
Returns the custom property value for the given key.
Parameters
key : string | symbol
Returns
unknown
-
inherited
is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/documentfragment~DocumentFragment#is:ELEMENT
Checks whether this object is of type
Element
or its subclass.element.is( 'element' ); // -> true element.is( 'node' ); // -> true element.is( 'view:element' ); // -> true element.is( 'view:node' ); // -> true element.is( 'model:element' ); // -> false element.is( 'documentSelection' ); // -> false
Assuming that the object being checked is an element, you can also check its name:
element.is( 'element', 'img' ); // -> true if this is an <img> element text.is( 'element', 'img' ); -> false
Parameters
type : 'element' | 'view:element'
Returns
this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
inherited
is( type ) → this is AttributeElement
module:engine/view/documentfragment~DocumentFragment#is:ATTRIBUTE_ELEMENT
Checks whether this object is of type
AttributeElement
.attributeElement.is( 'attributeElement' ); // -> true attributeElement.is( 'element' ); // -> true attributeElement.is( 'node' ); // -> true attributeElement.is( 'view:attributeElement' ); // -> true attributeElement.is( 'view:element' ); // -> true attributeElement.is( 'view:node' ); // -> true attributeElement.is( 'model:element' ); // -> false attributeElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an attribute element, you can also check its name:
attributeElement.is( 'element', 'b' ); // -> true if this is a bold element attributeElement.is( 'attributeElement', 'b' ); // -> same as above text.is( 'element', 'b' ); -> false
Parameters
type : 'attributeElement' | 'view:attributeElement'
Returns
this is AttributeElement
-
inherited
is( type ) → this is EditableElement | RootEditableElement
module:engine/view/documentfragment~DocumentFragment#is:EDITABLE_ELEMENT
Checks whether this object is of type
EditableElement
or its subclass.editableElement.is( 'editableElement' ); // -> true editableElement.is( 'element' ); // -> true editableElement.is( 'node' ); // -> true editableElement.is( 'view:editableElement' ); // -> true editableElement.is( 'view:element' ); // -> true editableElement.is( 'view:node' ); // -> true editableElement.is( 'model:element' ); // -> false editableElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an editbale element, you can also check its name:
editableElement.is( 'element', 'div' ); // -> true if this is a div element editableElement.is( 'editableElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'editableElement' | 'view:editableElement'
Returns
this is EditableElement | RootEditableElement
-
inherited
is( type ) → this is ContainerElement | EditableElement | RootEditableElement
module:engine/view/documentfragment~DocumentFragment#is:CONTAINER_ELEMENT
Checks whether this object is of type
ContainerElement
or its subclass.containerElement.is( 'containerElement' ); // -> true containerElement.is( 'element' ); // -> true containerElement.is( 'node' ); // -> true containerElement.is( 'view:containerElement' ); // -> true containerElement.is( 'view:element' ); // -> true containerElement.is( 'view:node' ); // -> true containerElement.is( 'model:element' ); // -> false containerElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a container element, you can also check its name:
containerElement.is( 'element', 'div' ); // -> true if this is a div container element containerElement.is( 'contaienrElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'containerElement' | 'view:containerElement'
Returns
this is ContainerElement | EditableElement | RootEditableElement
-
inherited
is( type ) → this is EmptyElement
module:engine/view/documentfragment~DocumentFragment#is:EMPTY_ELEMENT
Checks whether this object is of type
EmptyElement
.emptyElement.is( 'emptyElement' ); // -> true emptyElement.is( 'element' ); // -> true emptyElement.is( 'node' ); // -> true emptyElement.is( 'view:emptyElement' ); // -> true emptyElement.is( 'view:element' ); // -> true emptyElement.is( 'view:node' ); // -> true emptyElement.is( 'model:element' ); // -> false emptyElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an empty element, you can also check its name:
emptyElement.is( 'element', 'img' ); // -> true if this is a img element emptyElement.is( 'emptyElement', 'img' ); // -> same as above text.is( 'element', 'img' ); -> false
Parameters
type : 'emptyElement' | 'view:emptyElement'
Returns
this is EmptyElement
-
Checks whether this object is of type
Text
.text.is( '$text' ); // -> true text.is( 'node' ); // -> true text.is( 'view:$text' ); // -> true text.is( 'view:node' ); // -> true text.is( 'model:$text' ); // -> false text.is( 'element' ); // -> false text.is( 'range' ); // -> false
Parameters
type : '$text' | 'view:$text'
Returns
this is Text
-
inherited
is( type ) → this is Selection | DocumentSelection
module:engine/view/documentfragment~DocumentFragment#is:SELECTION
Checks whether this object is of type
Selection
orDocumentSelection
.selection.is( 'selection' ); // -> true selection.is( 'view:selection' ); // -> true selection.is( 'model:selection' ); // -> false selection.is( 'element' ); // -> false selection.is( 'range' ); // -> false
Parameters
type : 'selection' | 'view:selection'
Returns
this is Selection | DocumentSelection
-
inherited
is( type ) → this is Position
module:engine/view/documentfragment~DocumentFragment#is:POSITION
Checks whether this object is of type
Position
.position.is( 'position' ); // -> true position.is( 'view:position' ); // -> true position.is( 'model:position' ); // -> false position.is( 'element' ); // -> false position.is( 'range' ); // -> false
Parameters
type : 'position' | 'view:position'
Returns
this is Position
-
inherited
is( type ) → this is TextProxy
module:engine/view/documentfragment~DocumentFragment#is:TEXT_PROXY
Checks whether this object is of type
TextProxy
.textProxy.is( '$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> false textProxy.is( 'element' ); // -> false textProxy.is( 'range' ); // -> false
Note: Until version 20.0.0 this method wasn't accepting
'$textProxy'
type. The legacy'textProxy'
type is still accepted for backward compatibility.Parameters
type : '$textProxy' | 'view:$textProxy'
Returns
this is TextProxy
-
inherited
is( type ) → this is DocumentFragment
module:engine/view/documentfragment~DocumentFragment#is:DOCUMENT_FRAGMENT
hecks whether this object is of type
DocumentFragment
.docFrag.is( 'documentFragment' ); // -> true docFrag.is( 'view:documentFragment' ); // -> true docFrag.is( 'model:documentFragment' ); // -> false docFrag.is( 'element' ); // -> false docFrag.is( 'node' ); // -> false
Parameters
type : 'documentFragment' | 'view:documentFragment'
Returns
this is DocumentFragment
-
inherited
is( type ) → this is UIElement
module:engine/view/documentfragment~DocumentFragment#is:UI_ELEMENT
Checks whether this object is of type
UIElement
.uiElement.is( 'uiElement' ); // -> true uiElement.is( 'element' ); // -> true uiElement.is( 'node' ); // -> true uiElement.is( 'view:uiElement' ); // -> true uiElement.is( 'view:element' ); // -> true uiElement.is( 'view:node' ); // -> true uiElement.is( 'model:element' ); // -> false uiElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an ui element, you can also check its name:
uiElement.is( 'element', 'span' ); // -> true if this is a span ui element uiElement.is( 'uiElement', 'span' ); // -> same as above text.is( 'element', 'span' ); -> false
Parameters
type : 'uiElement' | 'view:uiElement'
Returns
this is UIElement
-
inherited
is( type ) → this is RootEditableElement
module:engine/view/documentfragment~DocumentFragment#is:ROOT_ELEMENT
Checks whether this object is of type
RootEditableElement
.rootEditableElement.is( 'rootElement' ); // -> true rootEditableElement.is( 'editableElement' ); // -> true rootEditableElement.is( 'element' ); // -> true rootEditableElement.is( 'node' ); // -> true rootEditableElement.is( 'view:editableElement' ); // -> true rootEditableElement.is( 'view:element' ); // -> true rootEditableElement.is( 'view:node' ); // -> true rootEditableElement.is( 'model:element' ); // -> false rootEditableElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a root editable element, you can also check its name:
rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element rootEditableElement.is( 'rootElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'rootElement' | 'view:rootElement'
Returns
this is RootEditableElement
-
inherited
is( type ) → this is RawElement
module:engine/view/documentfragment~DocumentFragment#is:RAW_ELEMENT
Checks whether this object is of type
RawElement
.rawElement.is( 'rawElement' ); // -> true rawElement.is( 'element' ); // -> true rawElement.is( 'node' ); // -> true rawElement.is( 'view:rawElement' ); // -> true rawElement.is( 'view:element' ); // -> true rawElement.is( 'view:node' ); // -> true rawElement.is( 'model:element' ); // -> false rawElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a raw element, you can also check its name:
rawElement.is( 'img' ); // -> true if this is an img element rawElement.is( 'rawElement', 'img' ); // -> same as above text.is( 'img' ); -> false
Parameters
type : 'rawElement' | 'view:rawElement'
Returns
this is RawElement
-
inherited
is( type ) → this is DocumentSelection
module:engine/view/documentfragment~DocumentFragment#is:DOCUMENT_SELECTION
Checks whether this object is of type
DocumentSelection
.`docSelection.is( 'selection' ); // -> true docSelection.is( 'documentSelection' ); // -> true docSelection.is( 'view:selection' ); // -> true docSelection.is( 'view:documentSelection' ); // -> true docSelection.is( 'model:documentSelection' ); // -> false docSelection.is( 'element' ); // -> false docSelection.is( 'node' ); // -> false
Parameters
type : 'documentSelection' | 'view:documentSelection'
Returns
this is DocumentSelection
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:ATTRIBUTE_ELEMENT_NAME
Checks whether the object is of type
AttributeElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:EDITABLE_ELEMENT_NAME
Checks whether the object is of type
EditableElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:RAW_ELEMENT_NAME
Checks whether the object is of type
RawElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:UI_ELEMENT_NAME
Checks whether the object is of type
UIElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:ROOT_ELEMENT_NAME
Checks whether the object is of type
RootEditableElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:EMPTY_ELEMENT_NAME
Checks whether the object is of type
EmptyElement
has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:CONTAINER_ELEMENT_NAME
Checks whether the object is of type
ContainerElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/documentfragment~DocumentFragment#is:ELEMENT_NAME
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'
name : N
Returns
boolean
-
inherited
is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/documentfragment~DocumentFragment#is:NODE
Checks whether this object is of type
Node
or its subclass.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
Parameters
type : 'node' | 'view:node'
Returns
this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
inherited
listenTo( emitter, event, callback, [ options ] ) → void
module:engine/view/documentfragment~DocumentFragment#listenTo:BASE_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using
:
. When namespaced event is fired, it additionally fires all callbacks for that namespace.// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ). myEmitter.on( 'myGroup', genericCallback ); myEmitter.on( 'myGroup:myEvent', specificCallback ); // genericCallback is fired. myEmitter.fire( 'myGroup' ); // both genericCallback and specificCallback are fired. myEmitter.fire( 'myGroup:myEvent' ); // genericCallback is fired even though there are no callbacks for "foo". myEmitter.fire( 'myGroup:foo' );
An event callback can stop the event and set the return value of the
fire
method.Type parameters
Parameters
emitter : Emitter
The object that fires the event.
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
Stops executing the callback on the given event. Shorthand for
this.stopListening( this, event, callback )
.Parameters
event : string
The name of the event.
callback : Function
The function to stop being called.
Returns
void
-
inherited
on( event, callback, [ options ] ) → void
module:engine/view/documentfragment~DocumentFragment#on
Registers a callback function to be executed when an event is fired.
Shorthand for
this.listenTo( this, event, callback, options )
(it makes the emitter listen on itself).Type parameters
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
inherited
once( event, callback, [ options ] ) → void
module:engine/view/documentfragment~DocumentFragment#once
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling
on
followed byoff
in the callback.Type parameters
Parameters
event : TEvent[ 'name' ]
The name of the event.
callback : GetCallback<TEvent>
The function to be called on event.
[ options ] : GetCallbackOptions<TEvent>
Additional options.
Returns
void
-
inherited
stopDelegating( [ event ], [ emitter ] ) → void
module:engine/view/documentfragment~DocumentFragment#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
Parameters
[ event ] : string
The name of the event to stop delegating. If omitted, stops it all delegations.
[ emitter ] : Emitter
(requires
event
) The object to stop delegating a particular event to. If omitted, stops delegation ofevent
to all emitters.
Returns
void
-
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → void
module:engine/view/documentfragment~DocumentFragment#stopListening:BASE_STOP
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
Parameters
[ emitter ] : Emitter
The object to stop listening to. If omitted, stops it for all objects.
[ event ] : string
(Requires the
emitter
) The name of the event to stop listening to. If omitted, stops it for all events fromemitter
.[ callback ] : Function
(Requires the
event
) The function to be removed from the call list for the givenevent
.
Returns
void
-
internal
_appendChild( items ) → number
module:engine/view/documentfragment~DocumentFragment#_appendChild
Insert a child node or a list of child nodes at the end and sets the parent of these nodes to this fragment.
Parameters
Returns
number
Number of appended nodes.
-
internal
_fireChange( type, node ) → void
module:engine/view/documentfragment~DocumentFragment#_fireChange
Fires
change
event with given type of the change.Parameters
type : ChangeType
Type of the change.
node : Node | DocumentFragment
Changed node.
Returns
void
-
internal
_insertChild( index, items ) → number
module:engine/view/documentfragment~DocumentFragment#_insertChild
-
internal
_removeChildren( index, howMany ) → Array<Node>
module:engine/view/documentfragment~DocumentFragment#_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.
-
internal
_removeCustomProperty( key ) → boolean
module:engine/view/documentfragment~DocumentFragment#_removeCustomProperty
Removes the custom property stored under the given key.
Parameters
key : string | symbol
Returns
boolean
Returns true if property was removed.
Related:
-
internal
_setCustomProperty( key, value ) → void
module:engine/view/documentfragment~DocumentFragment#_setCustomProperty
Sets a custom property. They can be used to add special data to elements.
Parameters
key : string | symbol
value : unknown
Returns
void
Related:
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.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.