Creates a DOM converter.
The view document instance.
Optionaloptions: { blockFillerMode?: ViewBlockFillerMode; renderingMode?: "data" | "editing" }An object with configuration options.
OptionalblockFillerMode?: ViewBlockFillerModeThe 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.
ReadonlyblockElements 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.
The mode of a block filler used by the DOM converter.
ReadonlydocumentReadonlyinlineA 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.
ReadonlypreElements which are considered pre-formatted elements.
ReadonlyrenderingWhether to leave the View-to-DOM conversion result unchanged or improve editing experience by filtering out interactive data.
ReadonlyunsafeA 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.
The DOM Document used by ViewDomConverter to create DOM nodes.
InternalRemove DOM selection from blurred editable, so it won't interfere with clicking on dropdowns (especially on iOS).
InternalClear temporary custom properties.
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.
The DOM document fragment to bind.
The view document fragment to bind.
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.
The DOM element to bind.
The view element to bind.
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.
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.
Parent DOM element.
Optionaloptions: {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.
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.
DOM position parent.
OptionaldomOffset: numberDOM position offset. You can skip it when converting the inline filler node.
View position.
Converts DOM Range to view module:engine/view/range~ViewRange.
If the start or end position cannot be converted null is returned.
DOM range.
View range.
Converts DOM selection to view module:engine/view/selection~ViewSelection. Ranges which cannot be converted will be omitted.
DOM selection.
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.
DOM node or document fragment to transform.
Optionaloptions: {Conversion options.
Optionalbind?: booleanDetermines whether new elements will be bound. False by default.
OptionalkeepOriginalCase?: booleanIf false, node's tag name will be converted to lower case. False by default.
OptionalskipComments?: booleanIf false, comment nodes will be converted to $comment
module:engine/view/uielement~ViewUIElement view UI elements. False by default.
OptionalwithChildren?: booleanIf true, node's and document fragment's children will be converted too. True by default.
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.
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.
View text node.
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.
DOM text node.
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.
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.
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.
DOM node to check.
True if a node is considered a block filler for given mode.
Returns true when node.nodeType equals Node.DOCUMENT_FRAGMENT_NODE.
Node to check.
Returns true if given selection is a backward selection, that is, if it's focus is before anchor.
Selection instance to check.
Checks if the given selection's boundaries are at correct places.
The following places are considered as incorrect for selection boundaries:
The DOM selection object to be checked.
true if the given selection is at a correct place, false otherwise.
Returns true when node.nodeType equals Node.ELEMENT_NODE.
Node to check.
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.
DOM element or document fragment.
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.
View element or document fragment.
Corresponding DOM node or 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.
View element or document fragment.
Corresponding DOM node or 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.
View element or document fragment.
Corresponding DOM node or document fragment.
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.
Pattern matching a view element which should be treated as an inline object.
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".
Pattern matching a view element whose content should be treated as raw data.
Removes an attribute from a DOM element.
Note: To set the attribute, use #setDomElementAttribute.
The DOM element the attribute should be removed from.
The name of the attribute.
Set domElement's content using provided html argument. Apply necessary filtering for the editing pipeline.
DOM element that should have html set as its content.
Textual representation of the HTML that will be set on domElement.
Sets the attribute on a DOM element.
Note: To remove the attribute, use #removeDomElementAttribute.
The DOM element the attribute should be set on.
The name of the attribute.
The value of the attribute.
OptionalrelatedViewElement: ViewElementThe 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.
Decides whether a given pair of attribute key and value should be passed further down the pipeline.
Element name in lower case.
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.
The DOM element to unbind.
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.
Parent view element.
Optionaloptions: { bind?: boolean; withChildren?: boolean }See module:engine/view/domconverter~ViewDomConverter#viewToDom options parameter.
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.
View position.
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.Optionaloptions: { bind?: boolean; withChildren?: boolean }Optionaloptions: { bind?: boolean; withChildren?: boolean }
ViewDomConverteris 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.