Trilium Frontend API
    Preparing search index...

    Class ViewDomConverter

    ViewDomConverter is a set of tools to do transformations between DOM nodes and view nodes. It also handles module:engine/view/domconverter~ViewDomConverter#bindElements bindings between these nodes.

    An instance of the DOM converter is available under module:engine/view/view~EditingView#domConverter editor.editing.view.domConverter.

    The DOM converter does not check which nodes should be rendered (use module:engine/view/renderer~ViewRenderer), does not keep the state of a tree nor keeps the synchronization between the tree view and the DOM tree (use module:engine/view/document~ViewDocument).

    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.

    Index

    Constructors

    • Creates a DOM converter.

      Parameters

      • document: ViewDocument

        The view document instance.

      • Optionaloptions: { blockFillerMode?: ViewBlockFillerMode; renderingMode?: "data" | "editing" }

        An object with configuration options.

        • OptionalblockFillerMode?: ViewBlockFillerMode

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

        • OptionalrenderingMode?: "data" | "editing"

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

      Returns ViewDomConverter

    Properties

    blockElements: string[]

    Elements which are considered block elements (and hence should be filled with a #isBlockFiller 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: ViewBlockFillerMode

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

    document: ViewDocument
    inlineObjectElements: string[]

    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.

    preElements: string[]

    Elements which are considered pre-formatted elements.

    renderingMode: "data" | "editing"

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

    unsafeElements: string[]

    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.

    Accessors

    • get domDocument(): Document

      The DOM Document used by ViewDomConverter to create DOM nodes.

      Returns Document

    Methods

    • Internal

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

      Returns void

    • Internal

      Clear temporary custom properties.

      Returns void

    • Binds DOM and view document fragments, so it will be possible to get corresponding document fragments using module:engine/view/domconverter~ViewDomConverter#mapDomToView and module:engine/view/domconverter~ViewDomConverter#mapViewToDom.

      Parameters

      Returns void

    • Binds DOM and view elements, so it will be possible to get corresponding elements using module:engine/view/domconverter~ViewDomConverter#mapDomToView and module:engine/view/domconverter~ViewDomConverter#mapViewToDom.

      Parameters

      Returns void

    • Binds a given DOM element that represents fake selection to a position of a module:engine/view/documentselection~ViewDocumentSelection document selection. Document selection copy is stored and can be retrieved by the module:engine/view/domconverter~ViewDomConverter#fakeSelectionToView method.

      Parameters

      Returns void

    • Converts children of the DOM element to view nodes using the module:engine/view/domconverter~ViewDomConverter#domToView method. Additionally this method omits block module:engine/view/filler filler, if it exists in the DOM parent.

      Parameters

      • domElement: HTMLElement

        Parent DOM element.

      • Optionaloptions: {
            bind?: boolean;
            keepOriginalCase?: boolean;
            skipComments?: boolean;
            withChildren?: boolean;
        }

        See module:engine/view/domconverter~ViewDomConverter#domToView options parameter.

      • OptionalinlineNodes: ViewNode[]

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

      Returns IterableIterator<ViewNode>

      View nodes.

    • Converts DOM parent and offset to view module:engine/view/position~ViewPosition.

      If the position is inside a module:engine/view/filler 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 module:engine/view/uielement~ViewUIElement 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.

      • OptionaldomOffset: number

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

      Returns ViewPosition

      View position.

    • Converts DOM Range to view module:engine/view/range~ViewRange. If the start or end position cannot be converted null is returned.

      Parameters

      Returns ViewRange

      View range.

    • Converts DOM selection to view module:engine/view/selection~ViewSelection. Ranges which cannot be converted will be omitted.

      Parameters

      Returns ViewSelection

      View selection.

    • 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 module:engine/view/filler fillers null will be returned. For all DOM elements rendered by module:engine/view/uielement~ViewUIElement that UIElement will be returned.

      Parameters

      • domNode: Node

        DOM node or document fragment to transform.

      • Optionaloptions: {
            bind?: boolean;
            keepOriginalCase?: boolean;
            skipComments?: boolean;
            withChildren?: boolean;
        }

        Conversion options.

        • Optionalbind?: boolean

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

        • OptionalkeepOriginalCase?: boolean

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

        • OptionalskipComments?: boolean

          If false, comment nodes will be converted to $comment module:engine/view/uielement~ViewUIElement view UI elements. False by default.

        • OptionalwithChildren?: boolean

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

      Returns ViewDocumentFragment | ViewNode

      Converted node or document fragment or null if DOM node is a module:engine/view/filler filler or the given node is an empty text node.

    • Returns a module:engine/view/selection~ViewSelection 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

      Returns ViewSelection

    • Finds corresponding text node. Text nodes are not module:engine/view/domconverter~ViewDomConverter#bindElements bound, corresponding text node is returned based on the sibling or parent.

      If the directly previous sibling is a module:engine/view/domconverter~ViewDomConverter#bindElements 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 module:engine/view/domconverter~ViewDomConverter#bindElements bound element, it is used to find the corresponding text node.

      Otherwise null is returned.

      Parameters

      Returns Text

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

    • Finds corresponding text node. Text nodes are not module:engine/view/domconverter~ViewDomConverter#bindElements bound, corresponding text node is returned based on the sibling or parent.

      If the directly previous sibling is a module:engine/view/domconverter~ViewDomConverter#bindElements 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 module:engine/view/domconverter~ViewDomConverter#bindElements bound element, it is used to find the corresponding text node.

      For all text nodes rendered by a module:engine/view/uielement~ViewUIElement or a module:engine/view/rawelement~ViewRawElement, the parent UIElement or RawElement will be returned.

      Otherwise null is returned.

      Note that for the block or inline module:engine/view/filler filler this method returns null.

      Parameters

      • domText: Text

        DOM text node.

      Returns ViewText | ViewRawElement | ViewUIElement

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

    • Focuses DOM editable that is corresponding to provided module:engine/view/editableelement~ViewEditableElement.

      Parameters

      Returns void

    • Returns a parent module:engine/view/uielement~ViewUIElement or module:engine/view/rawelement~ViewRawElement that hosts the provided DOM node. Returns null if there is no such parent.

      Parameters

      Returns ViewRawElement | ViewUIElement

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

      const converter = new ViewDomConverter( 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.

    • Returns true when node.nodeType equals Node.DOCUMENT_FRAGMENT_NODE.

      Parameters

      • node: Node

        Node to check.

      Returns node is DocumentFragment

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

      Parameters

      • selection: Selection

        Selection instance to check.

      Returns boolean

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

      The following places are considered as incorrect for selection boundaries:

      • before or in the middle of an inline filler sequence,
      • inside a DOM element which represents module:engine/view/uielement~ViewUIElement a view UI element,
      • inside a DOM element which represents module:engine/view/rawelement~ViewRawElement a view raw element.

      Parameters

      • domSelection: Selection

        The DOM selection object to be checked.

      Returns boolean

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

    • Returns true when node.nodeType equals Node.ELEMENT_NODE.

      Parameters

      • node: Node

        Node to check.

      Returns node is HTMLElement

    • Returns corresponding view module:engine/view/element~ViewElement Element or module:engine/view/documentfragment~ViewDocumentFragment for provided DOM element or document fragment. If there is no view item module:engine/view/domconverter~ViewDomConverter#bindElements bound to the given DOM - undefined is returned.

      For all DOM elements rendered by a module:engine/view/uielement~ViewUIElement or a module:engine/view/rawelement~ViewRawElement, the parent UIElement or RawElement will be returned.

      Parameters

      Returns ViewDocumentFragment | ViewElement

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

    • Returns corresponding DOM item for provided module:engine/view/element~ViewElement Element or module:engine/view/documentfragment~ViewDocumentFragment DocumentFragment. To find a corresponding text for module:engine/view/text~ViewText view Text instance use #findCorrespondingDomText.

      Parameters

      • element: ViewElement

        View element or document fragment.

      Returns HTMLElement

      Corresponding DOM node or document fragment.

      ELEMENT

    • Returns corresponding DOM item for provided module:engine/view/element~ViewElement Element or module:engine/view/documentfragment~ViewDocumentFragment DocumentFragment. To find a corresponding text for module:engine/view/text~ViewText view Text instance use #findCorrespondingDomText.

      Parameters

      Returns DocumentFragment

      Corresponding DOM node or document fragment.

      DOCUMENT_FRAGMENT

    • Returns corresponding DOM item for provided module:engine/view/element~ViewElement Element or module:engine/view/documentfragment~ViewDocumentFragment DocumentFragment. To find a corresponding text for module:engine/view/text~ViewText view Text instance use #findCorrespondingDomText.

      Parameters

      Returns HTMLElement | DocumentFragment

      Corresponding DOM node or document fragment.

      DOCUMENT_FRAGMENT_OR_ELEMENT

    • Registers a module:engine/view/matcher~MatcherPattern for inline object view elements.

      This is affecting how module:engine/view/domconverter~ViewDomConverter#domToView and module:engine/view/domconverter~ViewDomConverter#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

    • Registers a module:engine/view/matcher~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 module:engine/view/domconverter~ViewDomConverter#domToView and module:engine/view/domconverter~ViewDomConverter#domChildrenToView process DOM nodes.

      The raw data can be later accessed by a module:engine/view/element~ViewElement#getCustomProperty 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

    • 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

    • 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

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

      • OptionalrelatedViewElement: ViewElement

        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 module:engine/view/downcastwriter~ViewDowncastWriter methods can allow certain attributes that would normally be filtered out.

      Returns void

    • 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

    • 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

      Returns void

    • Converts children of the view element to DOM using the module:engine/view/domconverter~ViewDomConverter#viewToDom method. Additionally, this method adds block module:engine/view/filler filler to the list of children, if needed.

      Parameters

      • viewElement: ViewDocumentFragment | ViewElement

        Parent view element.

      • Optionaloptions: { bind?: boolean; withChildren?: boolean }

        See module:engine/view/domconverter~ViewDomConverter#viewToDom options parameter.

      Returns IterableIterator<Node>

      DOM nodes.

    • Converts view module:engine/view/position~ViewPosition to DOM parent and offset.

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

      Parameters

      Returns { offset: number; parent: Node }

      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.
    • Converts view module:engine/view/range~ViewRange to DOM range. Inline and block module:engine/view/filler fillers are handled during the conversion.

      Parameters

      Returns Range

      DOM range.

    • Parameters

      • viewNode: ViewText
      • Optionaloptions: { bind?: boolean; withChildren?: boolean }

      Returns Text

    • Parameters

      • viewNode: ViewElement
      • Optionaloptions: { bind?: boolean; withChildren?: boolean }

      Returns HTMLElement

    • Parameters

      • viewNode: ViewNode
      • Optionaloptions: { bind?: boolean; withChildren?: boolean }

      Returns Node

    • Parameters

      Returns DocumentFragment