CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

DomConverter (engine/view)

@ckeditor/ckeditor5-engine/src/view/domconverter

class
See source

DomConverter is a set of tools to do transformations between DOM nodes and view nodes. It also handles bindings between these nodes.

An instance of the DOM converter is available under editor.editing.view.domConverter.

The DOM converter does not check which nodes should be rendered (use Renderer), does not keep the state of a tree nor keeps the synchronization between the tree view and the DOM tree (use Document).

The DOM converter keeps DOM elements to view element bindings, so when the converter gets destroyed, the bindings are lost. Two converters will keep separate binding maps, so one tree view can be bound with two DOM trees.

Filtering

Properties

  • readonly

    blockElements : Array<string>

    See source

    Elements which are considered block elements (and hence should be filled with a block filler).

    Whether an element is considered a block element also affects handling of trailing whitespaces.

    You can extend this array if you introduce support for block elements which are not yet recognized here.

  • blockFillerMode : BlockFillerMode

    See source

    The mode of a block filler used by the DOM converter.

  • readonly

    document : Document

    See source

  • readonly

    inlineObjectElements : Array<string>

    See source

    A list of elements that exist inline (in text) but their inner structure cannot be edited because of the way they are rendered by the browser. They are mostly HTML form elements but there are other elements such as <img> or <iframe> that also have non-editable children or no children whatsoever.

    Whether an element is considered an inline object has an impact on white space rendering (trimming) around (and inside of it). In short, white spaces in text nodes next to inline objects are not trimmed.

    You can extend this array if you introduce support for inline object elements which are not yet recognized here.

  • readonly

    preElements : Array<string>

    See source

    Elements which are considered pre-formatted elements.

  • readonly

    renderingMode : 'data' | 'editing'

    See source

    Whether to leave the View-to-DOM conversion result unchanged or improve editing experience by filtering out interactive data.

  • readonly

    unsafeElements : Array<string>

    See source

    A list of elements which may affect the editing experience. To avoid this, those elements are replaced with <span data-ck-unsafe-element="[element name]"></span> while rendering in the editing mode.

  • private readonly

    _domDocument : Document

    See source

    The DOM Document used to create DOM nodes.

  • private readonly

    _domToViewMapping : WeakMap<HTMLElement | DocumentFragment, Element | DocumentFragment>

    See source

    The DOM-to-view mapping.

  • private readonly

    _elementsWithTemporaryCustomProperties : Set<Element | DocumentFragment>

    See source

    Set of elements with temporary custom properties that require clearing after render.

  • private readonly

    _fakeSelectionMapping : WeakMap<HTMLElement, Selection>

    See source

    Holds the mapping between fake selection containers and corresponding view selections.

  • private readonly

    _inlineObjectElementMatcher : Matcher

    See source

    Matcher for inline object view elements. This is an extension of a simple inlineObjectElements array of element names.

  • private readonly

    _rawContentElementMatcher : Matcher

    See source

    Matcher for view elements whose content should be treated as raw data and not processed during the conversion from DOM nodes to view elements.

  • private readonly

    _viewToDomMapping : WeakMap<Element | DocumentFragment, HTMLElement | DocumentFragment>

    See source

    The view-to-DOM mapping.

Methods

  • constructor( document, options = { [options.blockFillerMode], [options.renderingMode] } )

    See source

    Creates a DOM converter.

    Parameters

    document : Document

    The view document instance.

    options : object

    An object with configuration options.

    Properties
    [ options.blockFillerMode ] : BlockFillerMode

    The type of the block filler to use. Default value depends on the options.renderingMode: 'nbsp' when options.renderingMode == 'data', 'br' when options.renderingMode == 'editing'.

    [ options.renderingMode ] : 'data' | 'editing'

    Whether to leave the View-to-DOM conversion result unchanged or improve editing experience by filtering out interactive data.

    Defaults to {}

  • bindDocumentFragments( domFragment, viewFragment ) → void

    See source

    Binds DOM and view document fragments, so it will be possible to get corresponding document fragments using mapDomToView and mapViewToDom.

    Parameters

    domFragment : DocumentFragment

    The DOM document fragment to bind.

    viewFragment : DocumentFragment

    The view document fragment to bind.

    Returns

    void

  • bindElements( domElement, viewElement ) → void

    See source

    Binds DOM and view elements, so it will be possible to get corresponding elements using mapDomToView and mapViewToDom.

    Parameters

    domElement : HTMLElement

    The DOM element to bind.

    viewElement : Element

    The view element to bind.

    Returns

    void

  • bindFakeSelection( domElement, viewDocumentSelection ) → void

    See source

    Binds a given DOM element that represents fake selection to a position of a document selection. Document selection copy is stored and can be retrieved by the fakeSelectionToView method.

    Parameters

    domElement : HTMLElement
    viewDocumentSelection : DocumentSelection

    Returns

    void

  • domChildrenToView( domElement, options = { [options.bind], [options.keepOriginalCase], [options.skipComments], [options.withChildren] }, inlineNodes ) → IterableIterator<Node>

    See source

    Converts children of the DOM element to view nodes using the domToView method. Additionally this method omits block filler, if it exists in the DOM parent.

    Parameters

    domElement : HTMLElement

    Parent DOM element.

    options : undefined | object

    See domToView options parameter.

    Properties
    [ options.bind ] : boolean
    [ options.keepOriginalCase ] : boolean
    [ options.skipComments ] : boolean
    [ options.withChildren ] : boolean

    Defaults to {}

    inlineNodes : Array<Node>

    An array that will be populated with inline nodes. It's used internally for whitespace processing.

    Defaults to []

    Returns

    IterableIterator<Node>

    View nodes.

  • domPositionToView( domParent, domOffset ) → null | Position

    See source

    Converts DOM parent and offset to view Position.

    If the position is inside a filler which has no corresponding view node, position of the filler will be converted and returned.

    If the position is inside DOM element rendered by UIElement that position will be converted to view position before that UIElement.

    If structures are too different and it is not possible to find corresponding position then null will be returned.

    Parameters

    domParent : Node

    DOM position parent.

    domOffset : number

    DOM position offset. You can skip it when converting the inline filler node.

    Defaults to 0

    Returns

    null | Position

    View position.

  • domRangeToView( domRange ) → null | Range

    See source

    Converts DOM Range to view Range. If the start or end position can not be converted null is returned.

    Parameters

    domRange : Range | StaticRange

    DOM range.

    Returns

    null | Range

    View range.

  • domSelectionToView( domSelection ) → Selection

    See source

    Converts DOM selection to view Selection. Ranges which cannot be converted will be omitted.

    Parameters

    domSelection : Selection

    DOM selection.

    Returns

    Selection

    View selection.

  • domToView( domNode, options = { [options.bind], [options.keepOriginalCase], [options.skipComments], [options.withChildren] } ) → null | Node | DocumentFragment

    See source

    Converts DOM to view. For all text nodes, not bound elements and document fragments new items will be created. For bound elements and document fragments function will return corresponding items. For fillers null will be returned. For all DOM elements rendered by UIElement that UIElement will be returned.

    Parameters

    domNode : Node

    DOM node or document fragment to transform.

    options : object

    Conversion options.

    Properties
    [ options.bind ] : boolean

    Determines whether new elements will be bound. False by default.

    [ options.keepOriginalCase ] : boolean

    If false, node's tag name will be converted to lower case. False by default.

    [ options.skipComments ] : boolean

    If false, comment nodes will be converted to $comment view UI elements. False by default.

    [ options.withChildren ] : boolean

    If true, node's and document fragment's children will be converted too. True by default.

    Defaults to {}

    Returns

    null | Node | DocumentFragment

    Converted node or document fragment or null if DOM node is a filler or the given node is an empty text node.

  • fakeSelectionToView( domElement ) → undefined | Selection

    See source

    Returns a view selection instance corresponding to a given DOM element that represents fake selection. Returns undefined if binding to the given DOM element does not exist.

    Parameters

    domElement : HTMLElement

    Returns

    undefined | Selection

  • findCorrespondingDomText( viewText ) → null | Text

    See source

    Finds corresponding text node. Text nodes are not bound, corresponding text node is returned based on the sibling or parent.

    If the directly previous sibling is a bound element, it is used to find the corresponding text node.

    If this is a first child in the parent and the parent is a bound element, it is used to find the corresponding text node.

    Otherwise null is returned.

    Parameters

    viewText : Text

    View text node.

    Returns

    null | Text

    Corresponding DOM text node or null, if it was not possible to find a corresponding node.

  • findCorrespondingViewText( domText ) → null | Text | RawElement | UIElement

    See source

    Finds corresponding text node. Text nodes are not bound, corresponding text node is returned based on the sibling or parent.

    If the directly previous sibling is a bound element, it is used to find the corresponding text node.

    If this is a first child in the parent and the parent is a bound element, it is used to find the corresponding text node.

    For all text nodes rendered by a UIElement or a RawElement, the parent UIElement or RawElement will be returned.

    Otherwise null is returned.

    Note that for the block or inline filler this method returns null.

    Parameters

    domText : Text

    DOM text node.

    Returns

    null | Text | RawElement | UIElement

    Corresponding view text node or null, if it was not possible to find a corresponding node.

  • focus( viewEditable ) → void

    See source

    Focuses DOM editable that is corresponding to provided EditableElement.

    Parameters

    viewEditable : EditableElement

    Returns

    void

  • getHostViewElement( domNode ) → null | RawElement | UIElement

    See source

    Returns a parent UIElement or RawElement that hosts the provided DOM node. Returns null if there is no such parent.

    Parameters

    domNode : Node

    Returns

    null | RawElement | UIElement

  • isBlockFiller( domNode ) → boolean

    See source

    Checks if the node is an instance of the block filler for this DOM converter.

    const converter = new DomConverter( viewDocument, { blockFillerMode: 'br' } );

converter.isBlockFiller( BR_FILLER( document ) ); // true
converter.isBlockFiller( NBSP_FILLER( document ) ); // false

    Note:: For the 'nbsp' mode the method also checks context of a node so it cannot be a detached node.

    Note: A special case in the 'nbsp' mode exists where the <br> in <p><br></p> is treated as a block filler.

    Parameters

    domNode : Node

    DOM node to check.

    Returns

    boolean

    True if a node is considered a block filler for given mode.

  • isDocumentFragment( node ) → node is DocumentFragment

    See source

    Returns true when node.nodeType equals Node.DOCUMENT_FRAGMENT_NODE.

    Parameters

    node : Node

    Node to check.

    Returns

    node is DocumentFragment

  • isDomSelectionBackward( selection ) → boolean

    See source

    Returns true if given selection is a backward selection, that is, if it's focus is before anchor.

    Parameters

    selection : Selection

    Returns

    boolean

  • isDomSelectionCorrect( domSelection ) → boolean

    See source

    Checks if the given selection's boundaries are at correct places.

    The following places are considered as incorrect for selection boundaries:

    Parameters

    domSelection : Selection

    The DOM selection object to be checked.

    Returns

    boolean

    true if the given selection is at a correct place, false otherwise.

  • isElement( node ) → node is HTMLElement

    See source

    Returns true when node.nodeType equals Node.ELEMENT_NODE.

    Parameters

    node : Node

    Node to check.

    Returns

    node is HTMLElement

  • mapDomToView( domElementOrDocumentFragment ) → undefined | Element | DocumentFragment

    See source

    Returns corresponding view Element or DocumentFragment for provided DOM element or document fragment. If there is no view item bound to the given DOM - undefined is returned.

    For all DOM elements rendered by a UIElement or a RawElement, the parent UIElement or RawElement will be returned.

    Parameters

    domElementOrDocumentFragment : HTMLElement | DocumentFragment

    DOM element or document fragment.

    Returns

    undefined | Element | DocumentFragment

    Corresponding view element, document fragment or undefined if no element was bound.

  • mapViewToDom( documentFragment ) → undefined | DocumentFragment

    See source

    Returns corresponding DOM item for provided Element or DocumentFragment. To find a corresponding text for view Text instance use findCorrespondingDomText.

    Parameters

    documentFragment : DocumentFragment

    View element or document fragment.

    Returns

    undefined | DocumentFragment

    Corresponding DOM node or document fragment.

  • mapViewToDom( documentFragmentOrElement ) → undefined | HTMLElement | DocumentFragment

    See source

    Returns corresponding DOM item for provided Element or DocumentFragment. To find a corresponding text for view Text instance use findCorrespondingDomText.

    Parameters

    documentFragmentOrElement : Element | DocumentFragment

    View element or document fragment.

    Returns

    undefined | HTMLElement | DocumentFragment

    Corresponding DOM node or document fragment.

  • mapViewToDom( element ) → undefined | HTMLElement

    See source

    Returns corresponding DOM item for provided Element or DocumentFragment. To find a corresponding text for view Text instance use findCorrespondingDomText.

    Parameters

    element : Element

    View element or document fragment.

    Returns

    undefined | HTMLElement

    Corresponding DOM node or document fragment.

  • registerInlineObjectMatcher( pattern ) → void

    See source

    Registers a MatcherPattern for inline object view elements.

    This is affecting how domToView and domChildrenToView process DOM nodes.

    This is an extension of a simple inlineObjectElements array of element names.

    Parameters

    pattern : MatcherPattern

    Pattern matching a view element which should be treated as an inline object.

    Returns

    void

  • registerRawContentMatcher( pattern ) → void

    See source

    Registers a MatcherPattern for view elements whose content should be treated as raw data and not processed during the conversion from DOM nodes to view elements.

    This is affecting how domToView and domChildrenToView process DOM nodes.

    The raw data can be later accessed by a custom property of a view element called "$rawContent".

    Parameters

    pattern : MatcherPattern

    Pattern matching a view element whose content should be treated as raw data.

    Returns

    void

  • removeDomElementAttribute( domElement, key ) → void

    See source

    Removes an attribute from a DOM element.

    Note: To set the attribute, use setDomElementAttribute.

    Parameters

    domElement : HTMLElement

    The DOM element the attribute should be removed from.

    key : string

    The name of the attribute.

    Returns

    void

  • setContentOf( domElement, html ) → void

    See source

    Set domElement's content using provided html argument. Apply necessary filtering for the editing pipeline.

    Parameters

    domElement : HTMLElement

    DOM element that should have html set as its content.

    html : string

    Textual representation of the HTML that will be set on domElement.

    Returns

    void

  • setDomElementAttribute( domElement, key, value, [ relatedViewElement ] ) → void

    See source

    Sets the attribute on a DOM element.

    Note: To remove the attribute, use removeDomElementAttribute.

    Parameters

    domElement : HTMLElement

    The DOM element the attribute should be set on.

    key : string

    The name of the attribute.

    value : string

    The value of the attribute.

    [ relatedViewElement ] : Element

    The view element related to the domElement (if there is any). It helps decide whether the attribute set is unsafe. For instance, view elements created via the DowncastWriter methods can allow certain attributes that would normally be filtered out.

    Returns

    void

  • shouldRenderAttribute( attributeKey, attributeValue, elementName ) → boolean

    See source

    Decides whether a given pair of attribute key and value should be passed further down the pipeline.

    Parameters

    attributeKey : string
    attributeValue : string
    elementName : string

    Element name in lower case.

    Returns

    boolean

  • unbindDomElement( domElement ) → void

    See source

    Unbinds a given DOM element from the view element it was bound to. Unbinding is deep, meaning that all children of the DOM element will be unbound too.

    Parameters

    domElement : HTMLElement

    The DOM element to unbind.

    Returns

    void

  • viewChildrenToDom( viewElement, options = { [options.bind], [options.withChildren] } ) → IterableIterator<Node>

    See source

    Converts children of the view element to DOM using the viewToDom method. Additionally, this method adds block filler to the list of children, if needed.

    Parameters

    viewElement : Element | DocumentFragment

    Parent view element.

    options : object

    See viewToDom options parameter.

    Properties
    [ options.bind ] : boolean
    [ options.withChildren ] : boolean

    Defaults to {}

    Returns

    IterableIterator<Node>

    DOM nodes.

  • viewPositionToDom( viewPosition ) → null | object

    See source

    Converts view Position to DOM parent and offset.

    Inline and block fillers are handled during the conversion. If the converted position is directly before inline filler it is moved inside the filler.

    Parameters

    viewPosition : Position

    View position.

    Returns

    null | object

    DOM position or null if view position could not be converted to DOM. DOM position has two properties:

    • parent - DOM position parent.
    • offset - DOM position offset.

  • viewRangeToDom( viewRange ) → Range

    See source

    Converts view Range to DOM range. Inline and block fillers are handled during the conversion.

    Parameters

    viewRange : Range

    View range.

    Returns

    Range

    DOM range.

  • viewToDom( viewNode, [ options ] = { [options.bind], [options.withChildren] } ) → HTMLElement

    See source

    Converts the view to the DOM. For all text nodes, not bound elements and document fragments new items will be created. For bound elements and document fragments the method will return corresponding items.

    Parameters

    viewNode : Element

    View node or document fragment to transform.

    [ options ] : object

    Conversion options.

    Properties
    [ options.bind ] : boolean

    Determines whether new elements will be bound.

    [ options.withChildren ] : boolean

    If false, node's and document fragment's children will not be converted.

    Returns

    HTMLElement

    Converted node or DocumentFragment.

  • viewToDom( viewNode, [ options ] = { [options.bind], [options.withChildren] } ) → DocumentFragment

    See source

    Converts the view to the DOM. For all text nodes, not bound elements and document fragments new items will be created. For bound elements and document fragments the method will return corresponding items.

    Parameters

    viewNode : DocumentFragment

    View node or document fragment to transform.

    [ options ] : object

    Conversion options.

    Properties
    [ options.bind ] : boolean

    Determines whether new elements will be bound.

    [ options.withChildren ] : boolean

    If false, node's and document fragment's children will not be converted.

    Returns

    DocumentFragment

    Converted node or DocumentFragment.

  • viewToDom( viewNode, [ options ] = { [options.bind], [options.withChildren] } ) → Node

    See source

    Converts the view to the DOM. For all text nodes, not bound elements and document fragments new items will be created. For bound elements and document fragments the method will return corresponding items.

    Parameters

    viewNode : Node

    View node or document fragment to transform.

    [ options ] : object

    Conversion options.

    Properties
    [ options.bind ] : boolean

    Determines whether new elements will be bound.

    [ options.withChildren ] : boolean

    If false, node's and document fragment's children will not be converted.

    Returns

    Node

    Converted node or DocumentFragment.

  • viewToDom( viewNode, [ options ] = { [options.bind], [options.withChildren] } ) → Text

    See source

    Converts the view to the DOM. For all text nodes, not bound elements and document fragments new items will be created. For bound elements and document fragments the method will return corresponding items.

    Parameters

    viewNode : Text

    View node or document fragment to transform.

    [ options ] : object

    Conversion options.

    Properties
    [ options.bind ] : boolean

    Determines whether new elements will be bound.

    [ options.withChildren ] : boolean

    If false, node's and document fragment's children will not be converted.

    Returns

    Text

    Converted node or DocumentFragment.

  • internal

    _clearDomSelection() → void

    See source

    Remove DOM selection from blurred editable, so it won't interfere with clicking on dropdowns (especially on iOS).

    Returns

    void

  • internal

    _clearTemporaryCustomProperties() → void

    See source

    Clear temporary custom properties.

    Returns

    void

  • private

    _createReplacementDomElement( elementName, [ originalDomElement ] ) → HTMLElement

    See source

    Return a element with a special attribute holding the name of the original element. Optionally, copy all the attributes of the original element if that element is provided.

    Parameters

    elementName : string

    The name of view element.

    [ originalDomElement ] : HTMLElement

    The original DOM element to copy attributes and content from.

    Returns

    HTMLElement

  • private

    _createViewElement( node, options = { [options.keepOriginalCase] } ) → Element

    See source

    Creates view element basing on the node type.

    Parameters

    node : Node

    DOM node to check.

    options : object

    Conversion options. See domToView options parameter.

    Properties
    [ options.keepOriginalCase ] : boolean

    Returns

    Element

  • private

    _domToView( domNode, options = { [options.bind], [options.keepOriginalCase], [options.skipComments], [options.withChildren] }, inlineNodes ) → IterableIterator<null | Node | DocumentFragment>

    See source

    Internal generator for domToView. Also used by domChildrenToView. Separates DOM nodes conversion from whitespaces processing.

    Parameters

    domNode : Node

    DOM node or document fragment to transform.

    options : object
    Properties
    [ options.bind ] : boolean
    [ options.keepOriginalCase ] : boolean
    [ options.skipComments ] : boolean
    [ options.withChildren ] : boolean
    inlineNodes : Array<Node>

    An array of recently encountered inline nodes truncated to the block element boundaries. Used later to process whitespaces.

    Returns

    IterableIterator<null | Node | DocumentFragment>

  • private

    _getBlockFiller() → Node

    See source

    Returns the block filler node based on the current blockFillerMode setting.

    Returns

    Node

  • private

    _getTouchingInlineViewNode( node, getNext ) → null | Element | TextProxy

    See source

    Helper function. For given view text node, it finds previous or next sibling that is contained in the same container element. If there is no such sibling, null is returned.

    Parameters

    node : Text

    Reference node.

    getNext : boolean

    Returns

    null | Element | TextProxy

    Touching text node, an inline object or null if there is no next or previous touching text node.

  • private

    _isBlockDomElement( node ) → boolean

    See source

    Returns true if a DOM node belongs to blockElements. false otherwise.

    Parameters

    node : Node

    Returns

    boolean

  • private

    _isBlockViewElement( node ) → boolean

    See source

    Returns true if a view node belongs to blockElements. false otherwise.

    Parameters

    node : Node

    Returns

    boolean

  • private

    _isDomSelectionPositionCorrect( domParent, offset ) → boolean

    See source

    Checks if the given DOM position is a correct place for selection boundary. See isDomSelectionCorrect.

    Parameters

    domParent : Node

    Position parent.

    offset : number

    Position offset.

    Returns

    boolean

    true if given position is at a correct place for selection boundary, false otherwise.

  • private

    _isInlineObjectElement( node ) → node is Element

    See source

    Returns true if a DOM node belongs to inlineObjectElements. false otherwise.

    Parameters

    node : Node | DocumentFragment | TextProxy

    Returns

    node is Element

  • private

    _isPreFormatted( node ) → boolean

    See source

    Checks whether given text contains preformatted white space. This is the case if

    • any of node ancestors has a name which is in preElements array, or
    • the closest ancestor that has the white-space CSS property sets it to a value that preserves spaces

    Parameters

    node : Text | TextProxy

    Node to check

    Returns

    boolean

    true if given node contains preformatted white space, false otherwise.

  • private

    _isViewElementWithRawContent( viewElement, options = { [options.withChildren] } ) → boolean

    See source

    Checks if view element's content should be treated as a raw data.

    Parameters

    viewElement : Element | DocumentFragment

    View element to check.

    options : object

    Conversion options. See domToView options parameter.

    Properties
    [ options.withChildren ] : boolean

    Returns

    boolean

  • private

    _nodeEndsWithSpace( node ) → boolean

    See source

    Checks whether given node ends with a space character after changing appropriate space characters to &nbsp;s.

    Parameters

    node : TextProxy

    Node to check.

    Returns

    boolean

    true if given node ends with space, false otherwise.

  • private

    _processDataFromViewText( node ) → string

    See source

    Takes text data from a given data and processes it so it is correctly displayed in the DOM.

    Following changes are done:

    • a space at the beginning is changed to &nbsp; if this is the first text node in its container element or if a previous text node ends with a space character,
    • space at the end of the text node is changed to &nbsp; if there are two spaces at the end of a node or if next node starts with a space or if it is the last text node in its container,
    • remaining spaces are replaced to a chain of spaces and &nbsp; (e.g. 'x x' becomes 'x &nbsp; x').

    Content of preElements is not processed.

    Parameters

    node : Text | TextProxy

    View text node to process.

    Returns

    string

    Processed text data.

  • private

    _processDomInlineNodes( domParent, inlineNodes, options = { [options.withChildren] } ) → void

    See source

    Internal helper that walks the list of inline view nodes already generated from DOM nodes and handles whitespaces and NBSPs.

    Parameters

    domParent : null | HTMLElement

    The DOM parent of the given inline nodes. This should be a document fragment or a block element to whitespace processing start cleaning.

    inlineNodes : Array<Node>

    An array of recently encountered inline nodes truncated to the block element boundaries.

    options : object
    Properties
    [ options.withChildren ] : boolean

    Returns

    void

  • private

    _shouldRenameElement( elementName ) → boolean

    See source

    Checks whether a given element name should be renamed in a current rendering mode.

    Parameters

    elementName : string

    The name of view element.

    Returns

    boolean