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

  • readonly

    isEmpty : boolean

    See source

    Informs whether there are any changes buffered in Differ.

  • private

    _cachedChanges : null | Array<DiffItem>

    See source

    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.

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

  • private

    _cachedChangesWithGraveyard : null | Array<DiffItem>

    See source

    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.

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

  • private

    _changeCount : number

    See source

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

  • private readonly

    _changedMarkers : Map<string, object>

    See source

    A map that stores all changed markers.

    The keys of the map are marker names.

    The values of the map are objects with the following properties:

    • oldMarkerData,
    • newMarkerData.

  • private readonly

    _changedRoots : Map<string, DiffItemRoot>

    See source

    A map that stores all roots that have been changed.

    The keys are the names of the roots while value represents the changes.

  • private readonly

    _changesInElement : Map<Element | DocumentFragment, Array<ChangeItem>>

    See source

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

    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.

  • private readonly

    _elementChildrenSnapshots : Map<Element | DocumentFragment, Array<DifferSnapshot>>

    See source

    For each element or document fragment inside which there was a change, it stores a snapshot of the child nodes list (an array of children snapshots that represent the state in the element / fragment before any change has happened).

    This complements _elementsSnapshots.

    See also DifferSnapshot.

  • private readonly

    _elementState : Map<Element, 'rename' | 'move' | 'refresh'>

    See source

    Keeps the state for a given element, describing how the element was changed so far. It is used to evaluate the action property of diff items returned by getChanges.

    Possible values, in the order from the lowest priority to the highest priority:

    • 'refresh' - element was refreshed,
    • 'rename' - element was renamed,
    • 'move' - element was moved (or, usually, removed, that is moved to the graveyard).

    Element that was refreshed, may change its state to 'rename' if it was later renamed, or to 'move' if it was removed. But the element cannot change its state from 'move' to 'rename', or from 'rename' to 'refresh'.

    Only already existing elements are registered in _elementState. If a new element was inserted as a result of a buffered operation, it is not be registered in _elementState.

  • private readonly

    _elementsSnapshots : Map<Node, DifferSnapshot>

    See source

    Stores a snapshot for these model nodes that might have changed.

    This complements _elementChildrenSnapshots.

    See also DifferSnapshot.

  • private readonly

    _markerCollection : MarkerCollection

    See source

    Reference to the model's marker collection.

  • private

    _refreshedItems : Set<Item>

    See source

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

Static properties

  • private readonly static

    _statesPriority : Array<undefined | string>

    See source

    Priority of the element states. States on higher indexes of the array can overwrite states on the lower indexes.

Methods

  • constructor( markerCollection )

    See source

    Creates a Differ instance.

    Parameters

    markerCollection : MarkerCollection

    Model's marker collection.

  • bufferMarkerChange( markerName, oldMarkerData, newMarkerData ) → void

    See source

    Buffers a marker change.

    Parameters

    markerName : string

    The name of the marker that changed.

    oldMarkerData : MarkerData

    Marker data before the change.

    newMarkerData : MarkerData

    Marker data after the change.

    Returns

    void

  • bufferOperation( operationToBuffer ) → void

    See source

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

    Parameters

    operationToBuffer : Operation

    An operation to buffer.

    Returns

    void

  • getChangedMarkers() → Array<object>

    See source

    Returns all markers which changed.

    Returns

    Array<object>

  • getChangedRoots() → Array<DiffItemRoot>

    See source

    Returns all roots that have changed (either were attached, or detached, or their attributes changed).

    Returns

    Array<DiffItemRoot>

    Diff between the old and the new roots state.

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

    See source

    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.

    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 {}

    Returns

    Array<DiffItem>

    Diff between the old and the new model tree state.

  • getMarkersToAdd() → Array<object>

    See source

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

    Returns

    Array<object>

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

  • getMarkersToRemove() → Array<object>

    See source

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

    Returns

    Array<object>

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

  • getRefreshedItems() → Set<Item>

    See source

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

    Returns

    Set<Item>

  • hasDataChanges() → boolean

    See source

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

    Types of changes which affect the editor data:

    • model structure changes,
    • attribute changes,
    • a root is added or detached,
    • changes of markers which were defined as affectsData,
    • changes of markers' affectsData property.

    Returns

    boolean

  • reset() → void

    See source

    Resets Differ. Removes all buffered changes.

    Returns

    void

  • internal

    _bufferRootLoad( root ) → void

    See source

    Buffers all the data related to given root like it was all just added to the editor.

    Following changes are buffered:

    • root is attached,
    • all root content is inserted,
    • all root attributes are added,
    • all markers inside the root are added.

    Parameters

    root : RootElement

    Returns

    void

  • internal

    _refreshItem( item ) → void

    See source

    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.

    Parameters

    item : Item

    Item to refresh.

    Returns

    void

  • private

    _bufferRootAttributeChange( rootName, key, oldValue, newValue ) → void

    See source

    Buffers a root attribute change.

    Parameters

    rootName : string
    key : string
    oldValue : unknown
    newValue : unknown

    Returns

    void

  • private

    _bufferRootStateChange( rootName, isAttached ) → void

    See source

    Buffers the root state change after the root was attached or detached

    Parameters

    rootName : string
    isAttached : boolean

    Returns

    void

  • private

    _getAttributesDiff( range, oldAttributes, newAttributes ) → Array<object>

    See source

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

    Parameters

    range : Range

    The range where the change happened.

    oldAttributes : Map<string, unknown>

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

    newAttributes : Map<string, unknown>

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

    Returns

    Array<object>

    An array containing one or more diff items.

  • private

    _getChangesForElement( element ) → Array<ChangeItem>

    See source

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

    Parameters

    element : Element | DocumentFragment

    Returns

    Array<ChangeItem>

  • private

    _getDiffActionForNode( node, diffItemType ) → DifferItemAction

    See source

    Returns a value for action property for diff items returned by getChanges. This method aims to return 'rename' or 'refresh' when it should, and diffItemType ("default action") in all other cases.

    It bases on a few factors:

    • for text nodes, the method always returns diffItemType,
    • for newly inserted element, the method returns diffItemType,
    • if element state was not recorded, the method returns diffItemType,
    • if state was recorded, and it was 'move' (default action), the method returns diffItemType,
    • finally, if state was 'refresh' or 'rename', the method returns the state value.

    Parameters

    node : Node
    diffItemType : 'insert' | 'remove'

    Returns

    DifferItemAction

  • private

    _getInsertDiff( parent, offset, action, elementSnapshot, [ elementSnapshotBefore ] ) → object

    See source

    Returns an object with a single insert change description.

    Parameters

    parent : Element | DocumentFragment

    The element in which the change happened.

    offset : number

    The offset at which change happened.

    action : DifferItemAction

    Further specifies what kind of action led to generating this change.

    elementSnapshot : DifferSnapshot

    Snapshot of the inserted node after changes.

    [ elementSnapshotBefore ] : DifferSnapshot

    Snapshot of the inserted node before changes.

    Returns

    object

    The diff item.

  • private

    _getRemoveDiff( parent, offset, action, elementSnapshot ) → object

    See source

    Returns an object with a single remove change description.

    Parameters

    parent : Element | DocumentFragment

    The element in which change happened.

    offset : number

    The offset at which change happened.

    action : DifferItemAction

    Further specifies what kind of action led to generating this change.

    elementSnapshot : DifferSnapshot

    The snapshot of the removed node before changes.

    Returns

    object

    The diff item.

  • private

    _handleChange( inc, changes ) → void

    See source

    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.

    Parameters

    inc : ChangeItem

    Incoming (new) change.

    changes : Array<ChangeItem>

    An array containing all the changes done on that element.

    Returns

    void

  • private

    _isInInsertedElement( element ) → boolean

    See source

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

    Parameters

    element : Element | DocumentFragment

    Returns

    boolean

  • private

    _makeSnapshots( element ) → void

    See source

    Creates and saves a snapshot for all children of the given element.

    Parameters

    element : Element | DocumentFragment

    Returns

    void

  • private

    _markAttribute( item ) → void

    See source

    Saves and handles an attribute change.

    Parameters

    item : Item

    Returns

    void

  • private

    _markChange( parent, changeItem ) → void

    See source

    Saves and handles a model change.

    Parameters

    parent : Element | DocumentFragment
    changeItem : ChangeItem

    Returns

    void

  • private

    _markInsert( parent, offset, howMany ) → void

    See source

    Saves and handles an insert change.

    Parameters

    parent : Element | DocumentFragment
    offset : number
    howMany : number

    Returns

    void

  • private

    _markRemove( parent, offset, howMany ) → void

    See source

    Saves and handles a remove change.

    Parameters

    parent : Element | DocumentFragment
    offset : number
    howMany : number

    Returns

    void

  • private

    _removeAllNestedChanges( parent, offset, howMany ) → void

    See source

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

    Parameters

    parent : Element | DocumentFragment
    offset : number
    howMany : number

    Returns

    void

  • private

    _setElementState( node, state ) → void

    See source

    Tries to set given state for given item.

    This method does simple validation (it sets the state only for model elements, not for text proxy nodes). It also follows state setting rules, that is, 'refresh' cannot overwrite 'rename', and 'rename' cannot overwrite 'move'.

    Parameters

    node : Item
    state : 'rename' | 'move' | 'refresh'

    Returns

    void