ViewDomConverter

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.

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

The DOM Document used by ViewDomConverter to create DOM nodes.

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.

Elements which are considered pre-formatted elements.

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

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.

The DOM Document used by ViewDomConverter to create DOM nodes.

The DOM-to-view mapping.

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

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

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

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

The view-to-DOM mapping.

Creates a DOM converter.

Parameters

document : ViewDocument

The view document instance.

options : object

An object with configuration options.

Properties

[ options.blockFillerMode ] : 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'.

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

Defaults to {}

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 : ViewDocumentFragment

The view document fragment to bind.

Returns

void

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 : ViewElement

The view element to bind.

Returns

void

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 : ViewDocumentSelection

Returns

void

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

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

Defaults to []

Returns

IterableIterator<ViewNode>

View nodes.

Converts DOM parent and offset to view ViewPosition.

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

domOffset : number

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

Defaults to 0

Returns

null | ViewPosition

View position.

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

Parameters

domRange : Range | StaticRange

DOM range.

Returns

null | ViewRange

View range.

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

Parameters

domSelection : Selection

DOM selection.

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 fillers null will be returned. For all DOM elements rendered by ViewUIElement 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 | ViewNode | ViewDocumentFragment

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

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

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 : ViewText

View text node.

Returns

null | 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 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 ViewUIElement or a ViewRawElement, 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 | 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 ViewEditableElement.

Parameters

viewEditable : ViewEditableElement

Returns

void

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

Parameters

domNode : Node

Returns

null | 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 a view UI element,
• inside a DOM element which represents 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 Element or ViewDocumentFragment 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 ViewUIElement or a ViewRawElement, the parent UIElement or RawElement will be returned.

Parameters

domElementOrDocumentFragment : HTMLElement | DocumentFragment

DOM element or document fragment.

Returns

undefined | ViewElement | ViewDocumentFragment

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

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

Parameters

documentFragment : ViewDocumentFragment

View element or document fragment.

Returns

undefined | DocumentFragment

Corresponding DOM node or document fragment.

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

Parameters

documentFragmentOrElement : ViewElement | ViewDocumentFragment

View element or document fragment.

Returns

undefined | HTMLElement | DocumentFragment

Corresponding DOM node or document fragment.

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

Parameters

element : ViewElement

View element or document fragment.

Returns

undefined | HTMLElement

Corresponding DOM node or document fragment.

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

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

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.

[ relatedViewElement ] : 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 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

domElement : HTMLElement

The DOM element to unbind.

Returns

void

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 : ViewElement | ViewDocumentFragment

Parent view element.

options : object

See viewToDom options parameter.

Properties

[ options.bind ] : boolean

[ options.withChildren ] : boolean

Defaults to {}

Returns

IterableIterator<Node>

DOM nodes.

Converts view ViewPosition 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 : ViewPosition

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.

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

Parameters

viewRange : ViewRange

View range.

Returns

Range

DOM range.

Parameters

viewNode : ViewElement

[ options ] : object

Properties

[ options.bind ] : boolean

[ options.withChildren ] : boolean

Returns

HTMLElement

Parameters

viewNode : ViewDocumentFragment

[ options ] : object

Properties

[ options.bind ] : boolean

[ options.withChildren ] : boolean

Returns

DocumentFragment

Parameters

viewNode : ViewNode

[ options ] : object

Properties

[ options.bind ] : boolean

[ options.withChildren ] : boolean

Returns

Node

Parameters

viewNode : ViewText

[ options ] : object

Properties

[ options.bind ] : boolean

[ options.withChildren ] : boolean

Returns

Text

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

Returns

void

Clear temporary custom properties.

Returns

void

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

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

ViewElement

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

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

Returns

IterableIterator<null | ViewNode | ViewDocumentFragment>

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

Returns

Node

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 : ViewText

Reference node.

getNext : boolean

Returns

null | ViewElement | ViewTextProxy

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

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

Parameters

node : Node

Returns

boolean

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

Parameters

node : ViewNode

Returns

boolean

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.

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

Parameters

node : ViewNode | ViewDocumentFragment | ViewTextProxy

Returns

node is ViewElement

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 : ViewText | ViewTextProxy

Node to check

Returns

boolean

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

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

Parameters

viewElement : ViewElement | ViewDocumentFragment

View element to check.

options : object

Conversion options. See domToView options parameter.

Properties

[ options.withChildren ] : boolean

Returns

boolean

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

Parameters

node : ViewTextProxy

Node to check.

Returns

boolean

true if given node ends with space, false otherwise.

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   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   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   (e.g. 'x x' becomes 'x   x').

Content of preElements is not processed.

Parameters

node : ViewText | ViewTextProxy

View text node to process.

Returns

string

Processed text data.

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

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

options : object

Properties

[ options.withChildren ] : boolean

Returns

void

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

Parameters

elementName : string

The name of view element.

Returns

boolean