CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Marker (engine/model)

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

class
See source

Marker is a continuous parts of model (like a range), is named and represent some kind of information about marked part of model document. In contrary to nodes, which are building blocks of model document tree, markers are not stored directly in document tree but in model markers' collection. Still, they are document data, by giving additional meaning to the part of a model document between marker start and marker end.

In this sense, markers are similar to adding and converting attributes on nodes. The difference is that attribute is connected with a given node (e.g. a character is bold no matter if it gets moved or content around it changes). Markers on the other hand are continuous ranges and are characterized by their start and end position. This means that any character in the marker is marked by the marker. For example, if a character is moved outside of marker it stops being "special" and the marker is shrunk. Similarly, when a character is moved into the marker from other place in document model, it starts being "special" and the marker is enlarged.

Another upside of markers is that finding marked part of document is fast and easy. Using attributes to mark some nodes and then trying to find that part of document would require traversing whole document tree. Marker gives instant access to the range which it is marking at the moment.

Markers are built from a name and a range.

Range of the marker is updated automatically when document changes, using live range mechanism.

Name is used to group and identify markers. Names have to be unique, but markers can be grouped by using common prefixes, separated with :, for example: user:john or search:3. That's useful in term of creating namespaces for custom elements (e.g. comments, highlights). You can use this prefixes in event-update listeners to listen on changes in a group of markers. For instance: model.markers.on( 'update:user', callback ); will be called whenever any user:* markers changes.

There are two types of markers.

  1. Markers managed directly, without using operations. They are added directly by Writer to the MarkerCollection without any additional mechanism. They can be used as bookmarks or visual markers. They are great for showing results of the find, or select link when the focus is in the input.

  2. Markers managed using operations. These markers are also stored in MarkerCollection but changes in these markers is managed the same way all other changes in the model structure - using operations. Therefore, they are handled in the undo stack and synchronized between clients if the collaboration plugin is enabled. This type of markers is useful for solutions like spell checking or comments.

Both type of them should be added / updated by addMarker and removed by removeMarker methods.

model.change( ( writer ) => {
    const marker = writer.addMarker( name, { range, usingOperation: true } );

    // ...

    writer.removeMarker( marker );
} );

See Writer to find more examples.

Since markers need to track change in the document, for efficiency reasons, it is best to create and keep as little markers as possible and remove them as soon as they are not needed anymore.

Markers can be downcasted and upcasted.

Markers downcast happens on event-addMarker and event-removeMarker events. Use downcast converters or attach a custom converter to mentioned events. For data pipeline, marker should be downcasted to an element. Then, it can be upcasted back to a marker. Again, use upcast converters or attach a custom converter to event-element.

Marker instances are created and destroyed only by MarkerCollection.

Filtering

Properties

  • affectsData

    A value indicating if the marker changes the data.

    See source

  • managedUsingOperations

    A value indicating if the marker is managed using operations. See marker class description to learn more about marker types. See addMarker.

    See source

  • name : String

    readonly

    Marker's name.

    See source

  • _liveRange : LiveRange

    protected

    Range marked by the marker.

    See source

  • _affectsData : Boolean

    private

    Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).

    See source

  • _managedUsingOperations : Boolean

    private

    Flag indicates if the marker is managed using operations or not.

    See source

Methods

  • constructor( name, liveRange, managedUsingOperations, affectsData )

    Creates a marker instance.

    See source

    Parameters

    name : String

    Marker name.

    liveRange : LiveRange

    Range marked by the marker.

    managedUsingOperations : Boolean

    Specifies whether the marker is managed using operations.

    affectsData : Boolean

    Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).

  • getEnd() → Position

    Returns current marker end position.

    See source

    Returns

    Position

  • getRange() → Range

    Returns a range that represents the current state of the marker.

    See source

    Keep in mind that returned value is a Range, not a LiveRange. This means that it is up-to-date and relevant only until next model document change. Do not store values returned by this method. Instead, store name and get Marker instance from MarkerCollection every time there is a need to read marker properties. This will guarantee that the marker has not been removed and that it's data is up-to-date.

    Returns

    Range

  • getStart() → Position

    Returns current marker start position.

    See source

    Returns

    Position

  • is( type ) → Boolean

    Checks whether this object is of the given.

    See source
    marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true

marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false

    Check the entire list of model objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

  • _attachLiveRange( liveRange ) → LiveRange

    protected

    Binds new live range to the marker and detach the old one if is attached.

    See source

    Parameters

    liveRange : LiveRange

    Live range to attach

    Returns

    LiveRange

    Attached live range.

  • _detachLiveRange()

    protected

    Unbinds and destroys currently attached live range.

    See source

Events