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 binding these nodes.

The instance of DOMConverter is available in editor.editing.view.domConverter.

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

DomConverter keeps DOM elements to View element bindings, so when the converter will be destroyed, the binding will be 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'

    readonly

    The mode of a block filler used by DOM converter.

    See source

  • document : Document

    readonly

  • preElements : Array.<String>

    readonly

    Elements which are considered pre-formatted elements.

    See source

  • _blockFiller : function

    private readonly

    Block filler creator, which is used to create all block fillers during the view to DOM conversion and to recognize block fillers during the DOM to view conversion.

    See source

  • _domToViewMapping : WeakMap

    private

    DOM to View mapping.

    See source

  • _fakeSelectionMapping : WeakMap

    private

    Holds mapping between fake selection containers and corresponding view selections.

    See source

  • _viewToDomMapping : WeakMap

    private

    View to DOM mapping.

    See source

Methods

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

    Creates DOM converter.

    See source

    Parameters

    document : Document

    The view document instance.

    options : Object

    Object with configuration options.

    Properties
    [ options.blockFillerMode ] : BlockFillerMode

    The type of the block filler to use.

    Defaults to 'br'

  • _checkShouldLeftTrimDomText( prevNode )

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

    See source

    Parameters

    prevNode : Node

  • _checkShouldRightTrimDomText( node, nextNode )

    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

  • _getTouchingViewTextNode( node, getNext ) → Text | null

    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 | null

    Touching text node or null if there is no next or previous touching text node.

  • 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

    DOM document fragment to bind.

    viewFragment : DocumentFragment

    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

    DOM element to bind.

    viewElement : Element

    View element to bind.

  • bindFakeSelection( domElement, viewDocumentSelection )

    Binds given DOM element that represents fake selection to a position of a document selection. Document selection copy is stored and can be retrieved by 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.

    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] } ) → 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 converter to lower case.

    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 view selection instance corresponding to given DOM element that represents fake selection. Returns undefined if binding to given DOM element does not exists.

    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 UIElement that UIElement 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

  • getParentUIElement( domNode ) → UIElement | null

    Returns parent UIElement for provided DOM node. Returns null if there is no parent UIElement.

    See source

    Parameters

    domNode : Node

    Returns

    UIElement | 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.

  • isComment( node ) → Boolean

    Returns true when node.nodeType equals Node.COMMENT_NODE.

    See source

    Parameters

    node : Node

    Node to check.

    Returns

    Boolean

  • 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 given selection's boundaries are at correct places.

    See source

    The following places are considered as incorrect for selection boundaries:

    • before or in the middle of the inline filler sequence,
    • inside the DOM element which represents a view ui element.

    Parameters

    domSelection : Selection

    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. For all DOM elements rendered by UIElement that UIElement will be returned.

    See source

    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.

  • unbindDomElement( domElement )

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

    See source

    Parameters

    domElement : HTMLElement

    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 view to DOM. 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.

    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.

  • _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 node or a <br>. The search is terminated at block element boundaries and if a matching node wasn't found so far, null is returned.

    See source

    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

  • _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.

  • _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.