CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
Home/CKEditor 5/API
Class

Suggestion (track-changes)

@ckeditor/ckeditor5-track-changes/src/suggestion

class

Represents a singular suggestion that is tracked by track changes plugin.

Suggestion instances are created and handled by track changes plugin.

Filtering

Properties

  • Custom suggestion attributes. See also setAttribute and removeAttribute.

  • Suggestion author.

  • Comment thread model for comments added to this suggestion.

  • Date when the suggestion was created.

  • Additional suggestion data.

  • Informs whether suggestion has at least one comment.

  • The first (most-previous) suggestion in this suggestion chain.

  • Suggestion ID.

  • isInContent : Boolean

    readonly

    Informs whether the suggestion is still in the editor content.

    Returns true if there is at least one marker suggestion in the editor content.

  • isMultiRange : Boolean

    readonly

    Informs whether the suggestion is a multi-range suggestion or a single-range suggestion.

    This is evaluated basing on the marker name belonging to this suggestion. Even if only one marker belongs to the suggestion at a given time it can still be a multi range suggestion.

  • next : Suggestion | null

    readonly observable

    Next suggestion in suggestions chain.

    Chained suggestions should be handled as one entity.

  • previous : Suggestion | null

    readonly observable

    Previous suggestion in suggestions chain.

    Chained suggestions should be handled as one entity.

  • subType : String | null

    readonly

    Suggestion sub-type.

    This is an additional identifier for suggestions. Two suggestions of the same type may have different sub-types to differentiate suggestions behavior and handle interactions between suggestions.

    Sub-type is used for:

    • suggestions joining (only suggestions with the same sub-type can be joined),
    • suggestions custom callbacks (fired when adding, deleting and joining suggestions).

  • Suggestion type.

Methods

  • constructor( model, options = { options.id, options.type, [options.subType], [options.attributes], options.author, options.onAccept, options.onDiscard, options.onAttributesChange } )

    Creates a new suggestion object.

    Parameters

    model : Model

    Model for which the suggestion is created.

    options : Object

    Suggestion options.

    Properties
    options.id : String

    Suggestion ID.

    options.type : String

    Suggestion type.

    [ options.subType ] : String

    Suggestion sub-type.

    [ options.attributes ] : String

    Custom suggestion attributes. See also setAttribute and removeAttribute.

    options.author : User

    User which created the suggestion.

    options.onAccept : function

    Callback to be executed when the suggestion is accepted.

    options.onDiscard : function

    Callback to be executed when the suggestion is discarded.

    options.onAttributesChange : function

    Callback to be executed when the suggestion attributes have changed.

  • Accepts the suggestion.

  • addMarkerName( markerName )

    Binds given marker name to this suggestion.

    Parameters

    markerName : String

  • addRange( range )

    Adds a new range to this suggestion. It is assumed that the suggestion is a multi-range suggestion.

    A marker name is generated from this suggestion's properties and a marker with that name is created and set to a given range.

    Parameters

    range : Range

  • Discards the suggestion.

  • getAllAdjacentSuggestions() → Array.<Suggestion>

    Returns all suggestions that are in this suggestion chain.

    Returns

    Array.<Suggestion>

  • getContainedElement() → Element | null

    Returns the model element contained in the suggestion.

    A model element is considered as contained if there is exactly one range in the suggestion, and that range contains exactly one element.

    Returns null if there is no contained element.

    Returns

    Element | null

  • getFirstMarker() → Marker | null

    Returns the first marker belonging to this suggestion, i.e the first marker that was added to this suggestion and not removed yet.

    This method is useful if you know that the suggestion has only one marker and want to process it.

    Returns

    Marker | null

  • getFirstRange() → Range

    Returns the first range belonging to this suggestion, i.e. the range of the first marker that was added to this suggestion and not removed yet.

    This method is useful if you know that the suggestion has only one marker and want to process its range.

    Returns

    Range

  • getItems() → Array.<Item>

    Returns all model items that are in this suggestion.

    Returns

    Array.<Item>

  • getMarkerNames() → Array.<String>

    Returns all names of markers belonging to this suggestion.

    Returns

    Array.<String>

  • getMarkers() → Array.<Marker>

    Returns all markers belonging to this suggestion.

    Returns

    Array.<Marker>

  • getRanges() → Array.<Range>

    Returns all ranges of all markers belonging to this suggestion.

    Returns

    Array.<Range>

  • isIntersectingWithRange( range ) → Boolean

    Checks if given range is intersecting with any of the ranges of markers belonging to this suggestion.

    Parameters

    range : Range

    Returns

    Boolean

  • removeAttribute( name )

    Removes suggestion attribute.

    See also setAttribute

    Parameters

    name : String

    Attribute name.

  • removeMarker( markerName )

    Removes marker with the given name from the suggestion and the editor content.

    Parameters

    markerName : String

    Name of the marker to remove.

  • Removes all markers from the suggestion and the editor content.

  • setAttribute( name, value )

    Adds suggestion attribute.

    Suggestion attributes are custom data that can be set and used by features built around suggestions. Use it to store your feature data with other suggestion data.

    suggestion.setAttribute( 'isImportant', true );

    You can group multiple values in an object, using dot notation:

    suggestion.setAttribute( 'customData.type', 'image' );
suggestion.setAttribute( 'customData.src', 'foo.jpg' );

    Attributes set on the suggestion can be accessed through attribute property:

    const isImportant = suggestion.attributes.isImportant;
const type = suggestion.attributes.customData.type;

    You can also observe attributes property or bind other properties to it:

    myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );

    Whenever setAttribute() or removeAttribute() is called, attributes property is re-set and observables are refreshed.

    Parameters

    name : String

    Attribute name.

    value : *

    Attribute value.

  • toJSON() → Object

    Returns

    Object

Static methods

  • getMultiRangeId() → String

    static

    Returns a random string that can be used as additional identifier for the marker name for suggestions that are multi range.

    Returns

    String

Events

  • change:attributes( eventInfo, name, value, oldValue )

    Fired when the attributes property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (attributes).

    value : Object

    New value of the attributes property with given key or null, if operation should remove property.

    oldValue : Object

    Old value of the attributes property with given key or null, if property was not set before.

  • change:createdAt( eventInfo, name, value, oldValue )

    Fired when the createdAt property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (createdAt).

    value : Date | null

    New value of the createdAt property with given key or null, if operation should remove property.

    oldValue : Date | null

    Old value of the createdAt property with given key or null, if property was not set before.

  • change:next( eventInfo, name, value, oldValue )

    Fired when the next property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (next).

    value : Suggestion | null

    New value of the next property with given key or null, if operation should remove property.

    oldValue : Suggestion | null

    Old value of the next property with given key or null, if property was not set before.

  • change:previous( eventInfo, name, value, oldValue )

    Fired when the previous property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (previous).

    value : Suggestion | null

    New value of the previous property with given key or null, if operation should remove property.

    oldValue : Suggestion | null

    Old value of the previous property with given key or null, if property was not set before.