Marks model and view elements as corresponding. Corresponding elements can be retrieved by using the module:engine/conversion/mapper~Mapper#toModelElement toModelElement and module:engine/conversion/mapper~Mapper#toViewElement toViewElement methods. The information that elements are bound is also used to translate positions.
Model element.
View element.
Binds the given marker name with the given module:engine/view/element~ViewElement view element. The element will be added to the current set of elements bound with the given marker name.
Element to bind.
Marker name.
Removes all model to view and view to model bindings.
For the given viewPosition, finds and returns the closest ancestor of this position that has a mapping to
the model.
Position for which a mapped ancestor should be found.
Finds the position in a view element or view document fragment node (or in its children) with the expected model offset.
If the passed viewContainer is bound to model, Mapper will use caching mechanism to improve performance.
Tree view element in which we are looking for the position.
Expected offset.
Found position.
Unbinds all deferred binding removals of view elements that in the meantime were not re-attached to some root or document fragment.
See: #unbindViewElement unbindViewElement().
Returns all marker names of markers which have changed due to unbinding a view element (so it is assumed that the view element has been removed, moved or renamed) since the last flush. After returning, the marker names list is cleared.
Gets the length of the view element in the model.
The length is calculated as follows:
viewNode, it is used to
evaluate the model length (viewNode is used as first and only parameter passed to the callback),Examples:
foo -> 3 // Text length is equal to its data length.
<p>foo</p> -> 1 // Length of an element which is mapped is by default equal to 1.
<b>foo</b> -> 3 // Length of an element which is not mapped is a length of its children.
<div><p>x</p><p>y</p></div> -> 2 // Assuming that <div> is not mapped and <p> are mapped.
View node.
Length of the node in the tree model.
Gets all view elements bound to the given marker name.
Marker name.
View elements bound with the given marker name or null
if no elements are bound to the given marker name.
This method is deprecated and will be removed in one of the future CKEditor 5 releases.
Using this method will turn off Mapper caching system and may degrade performance when operating on bigger documents.
Registers a callback that evaluates the length in the model of a view element with the given name.
The callback is fired with one argument, which is a view element instance. The callback is expected to return a number representing the length of the view element in the model.
// List item in view may contain nested list, which have other list items. In model though,
// the lists are represented by flat structure. Because of those differences, length of list view element
// may be greater than one. In the callback it's checked how many nested list items are in evaluated list item.
function getViewListItemLength( element ) {
let length = 1;
for ( let child of element.getChildren() ) {
if ( child.name == 'ul' || child.name == 'ol' ) {
for ( let item of child.getChildren() ) {
length += getViewListItemLength( item );
}
}
}
return length;
}
mapper.registerViewToModelLength( 'li', getViewListItemLength );
Name of view element for which callback is registered.
Function return a length of view element instance in model.
Gets the corresponding model element.
Note: module:engine/view/uielement~ViewUIElement does not have corresponding element in model.
View element.
Corresponding model element or undefined if not found.
Gets the corresponding model document fragment.
View document fragment.
Corresponding model document fragment or undefined if not found.
Gets the corresponding model position.
View position.
Corresponding model position.
Gets the corresponding model range.
View range.
Corresponding model range.
Gets the corresponding view element.
Model element.
Corresponding view element or undefined if not found.
Gets the corresponding view document fragment.
Model document fragment.
Corresponding view document fragment or undefined if not found.
Gets the corresponding view position.
Model position.
Optionaloptions: { isPhantom?: boolean }
Additional options for position mapping process.
OptionalisPhantom?: booleanShould be set to true if the model position to map is pointing to a place
in model tree which no longer exists. For example, it could be an end of a removed model range.
Corresponding view position.
Gets the corresponding view range.
Model range.
Corresponding view range.
Unbinds an element from given marker name.
Element to unbind.
Marker name.
Unbinds the given module:engine/model/element~ModelElement model element from the map.
Note: the model-to-view binding will be removed, if it existed. However, the corresponding view-to-model binding
will be removed only if the view element is still bound to the passed modelElement.
This behavior lets for re-binding view element to another model element without fear of losing the new binding when the previously bound model element is unbound.
Model element to unbind.
Unbinds the given module:engine/view/element~ViewElement view element from the map.
Note: view-to-model binding will be removed, if it existed. However, corresponding model-to-view binding
will be removed only if model element is still bound to the passed viewElement.
This behavior allows for re-binding model element to another view element without fear of losing the new binding when the previously bound view element is unbound.
View element to unbind.
Optionaloptions: { defer?: boolean }
The options object.
Optionaldefer?: booleanControls whether the binding should be removed immediately or deferred until a
#flushDeferredBindings flushDeferredBindings() call.
Maps elements, positions and markers between the module:engine/view/document~ViewDocument view and the module:engine/model/model model.
The instance of the Mapper used for the editing pipeline is available in module:engine/controller/editingcontroller~EditingController#mapper
editor.editing.mapper.Mapper uses bound elements to find corresponding elements and positions, so, to get proper results, all model elements should be module:engine/conversion/mapper~Mapper#bindElements bound.
To map the complex model to/from view relations, you may provide custom callbacks for the module:engine/conversion/mapper~Mapper#event:modelToViewPosition modelToViewPosition event and module:engine/conversion/mapper~Mapper#event:viewToModelPosition viewToModelPosition event that are fired whenever a position mapping request occurs. Those events are fired by the module:engine/conversion/mapper~Mapper#toViewPosition toViewPosition and module:engine/conversion/mapper~Mapper#toModelPosition toModelPosition methods.
Mapperadds its own default callbacks with'lowest'priority. To override defaultMappermapping, add custom callback with higher priority and stop the event.