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.
Delegates selected events to another module:utils/emittermixin~Emitter. For instance:
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then eventX is delegated (fired by) emitterB and emitterC along with data:
emitterA.fire( 'eventX', data );
and eventY is delegated (fired by) emitterC along with data:
emitterA.fire( 'eventY', data );
Event names that will be delegated to another emitter.
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.
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an module:utils/eventinfo~EventInfo object,
followed by the optional args provided in the fire() method call.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The name of the event or EventInfo object if event is delegated.
Additional arguments to be passed to the callbacks.
By default the method returns undefined. However, the return value can be changed by listeners
through modification of the module:utils/eventinfo~EventInfo#return evt.return's property (the event info
is the first param of every callback).
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.
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using :.
When namespaced event is fired, it additionally fires all callbacks for that namespace.
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );
// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
An event callback can module:utils/eventinfo~EventInfo#stop stop the event and set the module:utils/eventinfo~EventInfo#return return value of the #fire method.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The object that fires the event.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
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.
Stops executing the callback on the given event.
Shorthand for #stopListening this.stopListening( this, event, callback ).
The name of the event.
The function to stop being called.
Registers a callback function to be executed when an event is fired.
Shorthand for #listenTo this.listenTo( this, event, callback, options ) (it makes the emitter
listen on itself).
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling #on followed by #off in the callback.
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
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.
Stops delegating events. It can be used at different levels:
Optionalevent: stringThe name of the event to stop delegating. If omitted, stops it all delegations.
Optionalemitter: Emitter(requires event) The object to stop delegating a particular event to.
If omitted, stops delegation of event to all emitters.
Stops listening for events. It can be used at different levels:
Optionalemitter: EmitterThe object to stop listening to. If omitted, stops it for all objects.
Optionalevent: string(Requires the emitter) The name of the event to stop listening to. If omitted, stops it
for all events from emitter.
Optionalcallback: Function(Requires the event) The function to be removed from the call list for the given
event.
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.