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

  • blockElements : Array.<String>

    readonly

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

    See source

    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 : 'br' | 'nbsp' | 'markedNbsp'

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

    See source

  • document : Document

    readonly

  • inlineObjectElements : Array.<String>

    readonly

    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.

    See source

    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.

  • preElements : Array.<String>

    readonly

    Elements which are considered pre-formatted elements.

    See source

  • renderingMode : 'data' | 'editing'

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

    See source

  • unsafeElements : Array.<String>

    readonly

    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.

    See source

  • _domToViewMapping : WeakMap

    private

    The DOM-to-view mapping.

    See source

  • _encounteredRawContentDomNodes : WeakSet.<Node>

    private

    A set of encountered raw content DOM nodes. It is used for preventing left trimming of the following text node.

    See source

  • _fakeSelectionMapping : WeakMap

    private

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

    See source

  • _rawContentElementMatcher : Matcher

    private

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

    See source

  • _viewToDomMapping : WeakMap

    private

    The view-to-DOM mapping.

    See source

Methods

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

    Creates a DOM converter.

    See source

    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 'editing'

  • bindDocumentFragments( domFragment, viewFragment )

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

    See source

    Parameters

    domFragment : DocumentFragment

    The DOM document fragment to bind.

    viewFragment : DocumentFragment

    The view document fragment to bind.

  • bindElements( domElement, viewElement )

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

    See source

    Parameters

    domElement : HTMLElement

    The DOM element to bind.

    viewElement : Element

    The view element to bind.

  • bindFakeSelection( domElement, viewDocumentSelection )

    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.

    See source

    Parameters

    domElement : HTMLElement
    viewDocumentSelection : DocumentSelection

  • domChildrenToView( domElement, options ) → Iterable.<Node>

    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.

    See source

    Parameters

    domElement : HTMLElement

    Parent DOM element.

    options : Object

    See domToView options parameter.

    Returns

    Iterable.<Node>

    View nodes.

  • domPositionToView( domParent, [ domOffset ] ) → Position

    Converts DOM parent and offset to view Position.

    See source

    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

    Position

    viewPosition View position.

  • domRangeToView( domRange ) → Range | null

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

    See source

    Parameters

    domRange : Range

    DOM range.

    Returns

    Range | null

    View range.

  • domSelectionToView( domSelection ) → Selection

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

    See source

    Parameters

    domSelection : Selection

    DOM selection.

    Returns

    Selection

    View selection.

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

    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.

    See source

    Parameters

    domNode : Node | DocumentFragment

    DOM node or document fragment to transform.

    [ options ] : Object

    Conversion options.

    Properties
    [ options.bind ] : Boolean

    Determines whether new elements will be bound.

    Defaults to false

    [ options.withChildren ] : Boolean

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

    Defaults to true

    [ options.keepOriginalCase ] : Boolean

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

    Defaults to false

    [ options.skipComments ] : Boolean

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

    Defaults to false

    Returns

    Node | DocumentFragment | null

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

  • fakeSelectionToView( domElement ) → Selection | undefined

    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.

    See source

    Parameters

    domElement : HTMLElement

    Returns

    Selection | undefined

  • findCorrespondingDomText( viewText ) → Text | null

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

    See source

    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

    Text | null

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

  • findCorrespondingViewText( domText ) → Text | null

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

    See source

    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

    Text | null

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

  • focus( viewEditable )

    Focuses DOM editable that is corresponding to provided EditableElement.

    See source

    Parameters

    viewEditable : EditableElement

  • getHostViewElement( domNode ) → UIElement | RawElement | null

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

    See source

    Parameters

    domNode : Node

    Returns

    UIElement | RawElement | null

  • isBlockFiller( domNode ) → Boolean

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

    See source
    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 ) → Boolean

    Returns true when node.nodeType equals Node.DOCUMENT_FRAGMENT_NODE.

    See source

    Parameters

    node : Node

    Node to check.

    Returns

    Boolean

  • isDomSelectionBackward( DOM ) → Boolean

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

    See source

    Parameters

    DOM : Selection

    Selection instance to check.

    Returns

    Boolean

  • isDomSelectionCorrect( domSelection ) → Boolean

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

    See source

    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 ) → Boolean

    Returns true when node.nodeType equals Node.ELEMENT_NODE.

    See source

    Parameters

    node : Node

    Node to check.

    Returns

    Boolean

  • mapDomToView( domElementOrDocumentFragment ) → Element | DocumentFragment | undefined

    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.

    See source

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

    Parameters

    domElementOrDocumentFragment : DocumentFragment | Element

    DOM element or document fragment.

    Returns

    Element | DocumentFragment | undefined

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

  • mapViewToDom( viewNode ) → Node | DocumentFragment | undefined

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

    See source

    Parameters

    viewNode : Element | DocumentFragment

    View element or document fragment.

    Returns

    Node | DocumentFragment | undefined

    Corresponding DOM node or document fragment.

  • registerRawContentMatcher( pattern )

    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.

    See source

    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.

  • removeDomElementAttribute( domElement, key )

    Removes an attribute from a DOM element.

    See source

    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.

  • setContentOf( domElement, html )

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

    See source

    Parameters

    domElement : Element

    DOM element that should have html set as its content.

    html : String

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

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

    Sets the attribute on a DOM element.

    See source

    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.

  • shouldRenderAttribute( attributeKey, attributeValue, elementName ) → Boolean

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

    See source

    Parameters

    attributeKey : String
    attributeValue : String
    elementName : String

    Element name in lower case.

    Returns

    Boolean

  • unbindDomElement( domElement )

    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.

    See source

    Parameters

    domElement : HTMLElement

    The DOM element to unbind.

  • viewChildrenToDom( viewElement, domDocument, options ) → Iterable.<Node>

    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.

    See source

    Parameters

    viewElement : Element | DocumentFragment

    Parent view element.

    domDocument : Document

    Document which will be used to create DOM nodes.

    options : Object

    See viewToDom options parameter.

    Returns

    Iterable.<Node>

    DOM nodes.

  • viewPositionToDom( viewPosition ) → Object | null

    Converts view Position to DOM parent and offset.

    See source

    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

    Object | null

    position DOM position or null if view position could not be converted to DOM.

    Node

    position.parent DOM position parent.

    Number

    position.offset DOM position offset.

  • viewRangeToDom( viewRange ) → Range

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

    See source

    Parameters

    viewRange : Range

    View range.

    Returns

    Range

    DOM range.

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

    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.

    See source

    Parameters

    viewNode : Node | DocumentFragment

    View node or document fragment to transform.

    domDocument : Document

    Document which will be used to create DOM nodes.

    [ options ] : Object

    Conversion options.

    Properties
    [ options.bind ] : Boolean

    Determines whether new elements will be bound.

    Defaults to false

    [ options.withChildren ] : Boolean

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

    Defaults to true

    Returns

    Node | DocumentFragment

    Converted node or DocumentFragment.

  • _checkShouldLeftTrimDomText( node, prevNode )

    private

    Helper function which checks if a DOM text node, preceded by the given prevNode should be trimmed from the left side.

    See source

    Parameters

    node : Node
    prevNode : Node

    Either DOM text or <br> or one of #inlineObjectElements.

  • _checkShouldRightTrimDomText( node, nextNode )

    private

    Helper function which checks if a DOM text node, succeeded by the given nextNode should be trimmed from the right side.

    See source

    Parameters

    node : Node
    nextNode : Node

    Either DOM text or <br> or one of #inlineObjectElements.

  • _createReplacementDomElement( elementName, [ originalDomElement ] ) → Element

    private

    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.

    See source

    Parameters

    elementName : String

    The name of view element.

    [ originalDomElement ] : Element

    The original DOM element to copy attributes and content from.

    Returns

    Element

  • _createViewElement( node, options ) → Element

    private

    Creates view element basing on the node type.

    See source

    Parameters

    node : Node

    DOM node to check.

    options : Object

    Conversion options. See domToView options parameter.

    Returns

    Element

  • _getBlockFiller() → Node

    private

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

    See source

    Returns

    Node

    filler

  • _getTouchingInlineDomNode( node, getNext ) → Text | Element | null

    private

    Helper function. For the given text node, it finds the closest touching node which is either a text, <br> or an inline object.

    See source

    If no such node is found, null is returned.

    For instance, in the following DOM structure:

    <p>foo<b>bar</b><br>bom</p>
    • foo doesn't have its previous touching inline node (null is returned),
    • foo's next touching inline node is bar
    • bar's next touching inline node is <br>

    This method returns text nodes and <br> elements because these types of nodes affect how spaces in the given text node need to be converted.

    Parameters

    node : Text
    getNext : Boolean

    Returns

    Text | Element | null

  • _getTouchingInlineViewNode( node, getNext ) → Text | Element | null

    private

    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.

    See source

    Parameters

    node : Text

    Reference node.

    getNext : Boolean

    Returns

    Text | Element | null

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

  • _isBlockElement( node ) → Boolean

    private

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

    See source

    Parameters

    node : Node

    Returns

    Boolean

  • _isDomSelectionPositionCorrect( domParent, offset ) → Boolean

    private

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

    See source

    Parameters

    domParent : Element

    Position parent.

    offset : Number

    Position offset.

    Returns

    Boolean

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

  • _isInlineObjectElement( node ) → Boolean

    private

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

    See source

    Parameters

    node : Node

    Returns

    Boolean

  • _isViewElementWithRawContent( viewElement, options ) → Boolean

    private

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

    See source

    Parameters

    viewElement : Element

    View element to check.

    options : Object

    Conversion options. See domToView options parameter.

    Returns

    Boolean

  • _nodeEndsWithSpace( node ) → Boolean

    private

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

    See source

    Parameters

    node : Text

    Node to check.

    Returns

    Boolean

    true if given node ends with space, false otherwise.

  • _processDataFromDomText( node ) → String

    private

    Takes text data from native Text node and processes it to a correct view text node data.

    See source

    Following changes are done:

    • multiple whitespaces are replaced to a single space,
    • space at the beginning of a text node is removed if it is the first text node in its container element or if the previous text node ends with a space character,
    • space at the end of the text node is removed 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
    • nbsps are converted to spaces.

    Parameters

    node : Node

    DOM text node to process.

    Returns

    String

    Processed data.

  • _processDataFromViewText( node ) → String

    private

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

    See source

    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

    View text node to process.

    Returns

    String

    Processed text data.

  • _shouldRenameElement( elementName ) → Boolean

    private

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

    See source

    Parameters

    elementName : String

    The name of view element.

    Returns

    Boolean