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 : undefinedmodule:engine/view/documentfragment~DocumentFragment#getFillerOffsetArtificial element getFillerOffset. Returns
undefined. Added for compatibility reasons. -
Is
trueif there are no nodes inside this document fragment,falseotherwise. -
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#_childrenArray of child nodes.
-
private readonly
_customProperties : Map<string | symbol, unknown>module:engine/view/documentfragment~DocumentFragment#_customPropertiesMap of custom properties. Custom properties can be added to document fragment instance.
Methods
-
internal
constructor( document, [ children ] )module:engine/view/documentfragment~DocumentFragment#constructorCreates new DocumentFragment instance.
Parameters
-
Symbol.iterator() → Iterator<Node>module:engine/view/documentfragment~DocumentFragment#Symbol.iterator -
inherited
delegate( events ) → EmitterMixinDelegateChainmodule:engine/view/documentfragment~DocumentFragment#delegateDelegates selected events to another
Emitter. For instance:emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );then
eventXis delegated (fired by)emitterBandemitterCalong withdata:emitterA.fire( 'eventX', data );and
eventYis delegated (fired by)emitterCalong 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#fireFires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an
EventInfoobject, followed by the optionalargsprovided in thefire()method call.Type parameters
Parameters
eventOrInfo : GetNameOrEventInfo<TEvent>The name of the event or
EventInfoobject 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 ) → numbermodule:engine/view/documentfragment~DocumentFragment#getChildIndexGets index of the given child node. Returns
-1if child node is not found.Parameters
node : NodeChild node.
Returns
numberIndex of the child node.
-
getChildren() → IterableIterator<Node>module:engine/view/documentfragment~DocumentFragment#getChildren -
getCustomProperties() → Iterable<tuple>module:engine/view/documentfragment~DocumentFragment#getCustomPropertiesReturns 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 ) → unknownmodule:engine/view/documentfragment~DocumentFragment#getCustomPropertyReturns 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 | UIElementmodule:engine/view/documentfragment~DocumentFragment#is:ELEMENTChecks whether this object is of type
Elementor 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'element' | 'view:element'
Returns
this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
inherited
is( type ) → this is AttributeElementmodule:engine/view/documentfragment~DocumentFragment#is:ATTRIBUTE_ELEMENTChecks 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'attributeElement' | 'view:attributeElement'
Returns
this is AttributeElement
-
inherited
is( type ) → this is EditableElement | RootEditableElementmodule:engine/view/documentfragment~DocumentFragment#is:EDITABLE_ELEMENTChecks whether this object is of type
EditableElementor 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'editableElement' | 'view:editableElement'
Returns
this is EditableElement | RootEditableElement
-
inherited
is( type ) → this is ContainerElement | EditableElement | RootEditableElementmodule:engine/view/documentfragment~DocumentFragment#is:CONTAINER_ELEMENTChecks whether this object is of type
ContainerElementor 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'containerElement' | 'view:containerElement'
Returns
this is ContainerElement | EditableElement | RootEditableElement
-
inherited
is( type ) → this is RawElementmodule:engine/view/documentfragment~DocumentFragment#is:RAW_ELEMENTChecks 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'rawElement' | 'view:rawElement'
Returns
this is RawElement
-
inherited
is( type ) → this is DocumentFragmentmodule:engine/view/documentfragment~DocumentFragment#is:DOCUMENT_FRAGMENThecks 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' ); // -> falseParameters
type : 'documentFragment' | 'view:documentFragment'
Returns
this is DocumentFragment
-
inherited
is( type ) → this is Positionmodule:engine/view/documentfragment~DocumentFragment#is:POSITIONChecks 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' ); // -> falseParameters
type : 'position' | 'view:position'
Returns
this is Position
-
inherited
is( type ) → this is TextProxymodule:engine/view/documentfragment~DocumentFragment#is:TEXT_PROXYChecks 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' ); // -> falseNote: 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
-
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' ); // -> falseParameters
type : '$text' | 'view:$text'
Returns
this is Text
-
inherited
is( type ) → this is UIElementmodule:engine/view/documentfragment~DocumentFragment#is:UI_ELEMENTChecks 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'uiElement' | 'view:uiElement'
Returns
this is UIElement
-
inherited
is( type ) → this is RootEditableElementmodule:engine/view/documentfragment~DocumentFragment#is:ROOT_ELEMENTChecks 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'rootElement' | 'view:rootElement'
Returns
this is RootEditableElement
-
inherited
is( type ) → this is EmptyElementmodule:engine/view/documentfragment~DocumentFragment#is:EMPTY_ELEMENTChecks 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'emptyElement' | 'view:emptyElement'
Returns
this is EmptyElement
-
inherited
is( type ) → this is Selection | DocumentSelectionmodule:engine/view/documentfragment~DocumentFragment#is:SELECTIONChecks whether this object is of type
SelectionorDocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'view:selection' ); // -> true selection.is( 'model:selection' ); // -> false selection.is( 'element' ); // -> false selection.is( 'range' ); // -> falseParameters
type : 'selection' | 'view:selection'
Returns
this is Selection | DocumentSelection
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:ELEMENT_NAMEChecks whether the object is of type
Elementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:CONTAINER_ELEMENT_NAMEChecks whether the object is of type
ContainerElementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:EMPTY_ELEMENT_NAMEChecks whether the object is of type
EmptyElementhas the specifiedname.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:ROOT_ELEMENT_NAMEChecks whether the object is of type
RootEditableElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:UI_ELEMENT_NAMEChecks whether the object is of type
UIElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:RAW_ELEMENT_NAMEChecks whether the object is of type
RawElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:EDITABLE_ELEMENT_NAMEChecks whether the object is of type
EditableElementor its subclass and has the specifiedname.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'name : N
Returns
boolean
-
inherited
is( type, name ) → booleanmodule:engine/view/documentfragment~DocumentFragment#is:ATTRIBUTE_ELEMENT_NAMEChecks whether the object is of type
AttributeElementand has the specifiedname.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'name : N
Returns
boolean
-
inherited
is( type ) → this is DocumentSelectionmodule:engine/view/documentfragment~DocumentFragment#is:DOCUMENT_SELECTIONChecks 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' ); // -> falseParameters
type : 'documentSelection' | 'view:documentSelection'
Returns
this is DocumentSelection
-
inherited
is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElementmodule:engine/view/documentfragment~DocumentFragment#is:NODEChecks whether this object is of type
Nodeor its subclass.This method is useful when processing view objects that are of unknown type. For example, a function may return a
DocumentFragmentor aNodethat 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 fragmentSince 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' ); // -> falseBy 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 preciseParameters
type : 'node' | 'view:node'
Returns
this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
inherited
listenTo( emitter, event, callback, [ options ] ) → voidmodule:engine/view/documentfragment~DocumentFragment#listenTo:BASE_EMITTERRegisters 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
firemethod.Type parameters
Parameters
emitter : EmitterThe 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 : stringThe name of the event.
callback : FunctionThe function to stop being called.
Returns
void
-
inherited
on( event, callback, [ options ] ) → voidmodule:engine/view/documentfragment~DocumentFragment#onRegisters 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 ] ) → voidmodule:engine/view/documentfragment~DocumentFragment#onceRegisters a callback function to be executed on the next time the event is fired only. This is similar to calling
onfollowed byoffin 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 ] ) → voidmodule:engine/view/documentfragment~DocumentFragment#stopDelegatingStops 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 ] : stringThe 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 ofeventto all emitters.
Returns
void
-
inherited
stopListening( [ emitter ], [ event ], [ callback ] ) → voidmodule:engine/view/documentfragment~DocumentFragment#stopListening:BASE_STOPStops 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 ] : EmitterThe 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 ) → numbermodule:engine/view/documentfragment~DocumentFragment#_appendChild -
internal
_fireChange( type, node, [ data ] = { data.index } ) → voidmodule:engine/view/documentfragment~DocumentFragment#_fireChangeParameters
type : ChangeTypeType of the change.
node : Node | DocumentFragmentChanged node.
[ data ] : objectAdditional data.
Propertiesdata.index : number
Returns
void
Fires
-
internal
_insertChild( index, items ) → numbermodule:engine/view/documentfragment~DocumentFragment#_insertChildInserts a child node or a list of child nodes on the given index and sets the parent of these nodes to this fragment.
Parameters
index : numberPosition where nodes should be inserted.
items : string | Item | Iterable<( string | Item )>Items to be inserted.
Returns
numberNumber of inserted nodes.
-
internal
_removeChildren( index, howMany ) → Array<Node>module:engine/view/documentfragment~DocumentFragment#_removeChildrenRemoves number of child nodes starting at the given index and set the parent of these nodes to
null.Parameters
index : numberNumber of the first node to remove.
howMany : numberNumber of nodes to remove.
Defaults to
1
Returns
Array<Node>The array of removed nodes.
-
internal
_removeCustomProperty( key ) → booleanmodule:engine/view/documentfragment~DocumentFragment#_removeCustomPropertyRemoves the custom property stored under the given key.
Parameters
key : string | symbol
Returns
booleanReturns true if property was removed.
Related:
-
internal
_setCustomProperty( key, value ) → voidmodule:engine/view/documentfragment~DocumentFragment#_setCustomPropertySets a custom property. They can be used to add special data to elements.
Parameters
key : string | symbolvalue : 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.