CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Differ (engine/model)

@ckeditor/ckeditor5-engine/src/model/differ

class
See source

Calculates the difference between two model states.

Receives operations that are to be applied on the model document. Marks parts of the model document tree which are changed and saves the state of these elements before the change. Then, it compares saved elements with the changed elements, after all changes are applied on the model document. Calculates the diff between saved elements and new ones and returns a change set.

Filtering

Properties

  • isEmpty : Boolean

    readonly

    Informs whether there are any changes buffered in Differ.

    See source

  • _cachedChanges : Array.<Object> | null

    private

    For efficiency purposes, Differ stores the change set returned by the differ after getChanges call. Cache is reset each time a new operation is buffered. If the cache has not been reset, getChanges will return the cached value instead of calculating it again.

    See source

    This property stores those changes that did not take place in graveyard root.

  • _cachedChangesWithGraveyard : Array.<Object> | null

    private

    For efficiency purposes, Differ stores the change set returned by the differ after the getChanges call. The cache is reset each time a new operation is buffered. If the cache has not been reset, getChanges will return the cached value instead of calculating it again.

    See source

    This property stores all changes evaluated by Differ, including those that took place in the graveyard.

  • _changeCount : Number

    private

    Stores the number of changes that were processed. Used to order the changes chronologically. It is important when changes are sorted.

    See source

  • _changedMarkers : Map.<String, Object>

    private

    A map that stores all changed markers.

    See source

    The keys of the map are marker names. The values of the map are objects with the following properties:

    • oldMarkerData,
    • newMarkerData.

  • _changesInElement : Map

    private

    A map that stores changes that happened in a given element.

    See source

    The keys of the map are references to the model elements. The values of the map are arrays with changes that were done on this element.

  • _elementSnapshots : Map

    private

    A map that stores "element's children snapshots". A snapshot is representing children of a given element before the first change was applied on that element. Snapshot items are objects with two properties: name, containing the element name (or '$text' for a text node) and attributes which is a map of the node's attributes.

    See source

  • _markerCollection : MarkerCollection

    private

    Reference to the model's marker collection.

    See source

  • _refreshedItems : Set.<Item>

    private

    Set of model items that were marked to get refreshed in _refreshItem.

    See source

Methods

  • constructor( markerCollection )

    Creates a Differ instance.

    See source

    Parameters

    markerCollection : MarkerCollection

    Model's marker collection.

  • bufferMarkerChange( markerName, oldMarkerData, newMarkerData )

    Buffers a marker change.

    See source

    Parameters

    markerName : String

    The name of the marker that changed.

    oldMarkerData : MarkerData

    Marker data before the change.

    newMarkerData : MarkerData

    Marker data after the change.

  • bufferOperation( operation )

    Buffers the given operation. An operation has to be buffered before it is executed.

    See source

    Operation type is checked and it is checked which nodes it will affect. These nodes are then stored in Differ in the state before the operation is executed.

    Parameters

    operation : Operation

    An operation to buffer.

  • getChangedMarkers() → Array.<Object>

    Returns all markers which changed.

    See source

    Returns

    Array.<Object>

  • getChanges( options = { [options.includeChangesInGraveyard] } ) → Array.<DiffItem>

    Calculates the diff between the old model tree state (the state before the first buffered operations since the last reset call) and the new model tree state (actual one). It should be called after all buffered operations are executed.

    See source

    The diff set is returned as an array of diff items, each describing a change done on the model. The items are sorted by the position on which the change happened. If a position is before another one, it will be on an earlier index in the diff set.

    Note: Elements inside inserted element will not have a separate diff item, only the top most element change will be reported.

    Because calculating the diff is a costly operation, the result is cached. If no new operation was buffered since the previous getChanges call, the next call will return the cached value.

    Parameters

    options : Object

    Additional options.

    Properties
    [ options.includeChangesInGraveyard ] : Boolean

    If set to true, also changes that happened in the graveyard root will be returned. By default, changes in the graveyard root are not returned.

    Defaults to false

    Returns

    Array.<DiffItem>

    Diff between the old and the new model tree state.

  • getMarkersToAdd() → Array.<Object>

    Returns all markers which should be added as a result of buffered changes.

    See source

    Returns

    Array.<Object>

    Markers to add. Each array item is an object containing the name and range properties.

  • getMarkersToRemove() → Array.<Object>

    Returns all markers that should be removed as a result of buffered changes.

    See source

    Returns

    Array.<Object>

    Markers to remove. Each array item is an object containing the name and range properties.

  • getRefreshedItems() → Set.<Item>

    Returns a set of model items that were marked to get refreshed.

    See source

    Returns

    Set.<Item>

  • hasDataChanges() → Boolean

    Checks whether some of the buffered changes affect the editor data.

    See source

    Types of changes which affect the editor data:

    • model structure changes,
    • attribute changes,
    • changes of markers which were defined as affectsData,
    • changes of markers' affectsData property.

    Returns

    Boolean

  • reset()

    Resets Differ. Removes all buffered changes.

    See source

  • _refreshItem( item )

    protected

    Marks the given item in differ to be "refreshed". It means that the item will be marked as removed and inserted in the differ changes set, so it will be effectively re-converted when the differ changes are handled by a dispatcher.

    See source

    Parameters

    item : Item

    Item to refresh.

  • _getAttributesDiff( range, oldAttributes, newAttributes ) → Array.<Object>

    private

    Returns an array of objects where each one is a single attribute change description.

    See source

    Parameters

    range : Range

    The range where the change happened.

    oldAttributes : Map

    A map, map iterator or compatible object that contains attributes before the change.

    newAttributes : Map

    A map, map iterator or compatible object that contains attributes after the change.

    Returns

    Array.<Object>

    An array containing one or more diff items.

  • _getChangesForElement( element ) → Array.<Object>

    private

    Gets an array of changes that have already been saved for a given element.

    See source

    Parameters

    element : Element

    Returns

    Array.<Object>

  • _getInsertDiff( parent, offset, elementSnapshot ) → Object

    private

    Returns an object with a single insert change description.

    See source

    Parameters

    parent : Element

    The element in which the change happened.

    offset : Number

    The offset at which change happened.

    elementSnapshot : Object

    The snapshot of the removed element a character.

    Returns

    Object

    The diff item.

  • _getRemoveDiff( parent, offset, elementSnapshot ) → Object

    private

    Returns an object with a single remove change description.

    See source

    Parameters

    parent : Element

    The element in which change happened.

    offset : Number

    The offset at which change happened.

    elementSnapshot : Object

    The snapshot of the removed element a character.

    Returns

    Object

    The diff item.

  • _handleChange( inc, changes )

    private

    For a given newly saved change, compares it with a change already done on the element and modifies the incoming change and/or the old change.

    See source

    Parameters

    inc : Object

    Incoming (new) change.

    changes : Array.<Object>

    An array containing all the changes done on that element.

  • _isInInsertedElement( element ) → Boolean

    private

    Checks whether given element or any of its parents is an element that is buffered as an inserted element.

    See source

    Parameters

    element : Element

    Element to check.

    Returns

    Boolean

  • _makeSnapshot( element )

    private

    Saves a children snapshot for a given element.

    See source

    Parameters

    element : Element

  • _markAttribute( item )

    private

    Saves and handles an attribute change.

    See source

    Parameters

    item : Item

  • _markChange( parent, changeItem )

    private

    Saves and handles a model change.

    See source

    Parameters

    parent : Element
    changeItem : Object

  • _markInsert( parent, offset, howMany )

    private

    Saves and handles an insert change.

    See source

    Parameters

    parent : Element
    offset : Number
    howMany : Number

  • _markRemove( parent, offset, howMany )

    private

    Saves and handles a remove change.

    See source

    Parameters

    parent : Element
    offset : Number
    howMany : Number

  • _removeAllNestedChanges( parent, offset, howMany )

    private

    Removes deeply all buffered changes that are registered in elements from range specified by parent, offset and howMany.

    See source

    Parameters

    parent : Element
    offset : Number
    howMany : Number