CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

EditorWatchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/editorwatchdog

class
See source

A watchdog for CKEditor 5 editors.

See the Watchdog feature guide to learn the rationale behind it and how to use it.

Filtering

Properties

  • crashes : Array.<Object>

    readonly inherited

    An array of crashes saved as an object with the following properties:

    See source
    • message: String,
    • stack: String,
    • date: Number,
    • filename: String | undefined,
    • lineno: Number | undefined,
    • colno: Number | undefined,

  • editor : Editor

    readonly

    The current editor instance.

    See source

  • state : 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    inherited

    Specifies the state of the item watched by the watchdog. The state can be one of the following values:

    See source
    • initializing – Before the first initialization, and after crashes, before the item is ready.
    • ready – A state when the user can interact with the item.
    • crashed – A state when an error occurs. It quickly changes to initializing or crashedPermanently depending on how many and how frequent errors have been caught recently.
    • crashedPermanently – A state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
    • destroyed – A state when the item is manually destroyed by the user after calling watchdog.destroy().

  • _crashNumberLimit : Number

    protected inherited

    Related:

  • _creator : function

    protected inherited

    The creation method.

    See source

    Related:

  • _destructor : function

    protected inherited

    The destruction method.

    See source

    Related:

  • _item : Object | undefined

    protected inherited

    The watched item.

    See source

  • _minimumNonErrorTimePeriod : Number

    protected inherited

    Related:

  • _now

    protected inherited

    Returns the result of the Date.now() call. It can be overridden in tests to mock time as some popular approaches like sinon.useFakeTimers() do not work well with error handling.

    See source

  • _config : Object | undefined

    private

    The editor configuration.

    See source

  • _data : Object.<String, String>

    private

    The latest saved editor data represented as a root name -> root data object.

    See source

  • _editor : Editor

    private

    The current editor instance.

    See source

  • _elementOrData : HTMLElement | String | Object.<(String | String)>

    private

    The editor source element or data.

    See source

  • _lastDocumentVersion : Number

    private

    The last document version.

    See source

  • _listeners : Object.<String, Function>>

    private inherited

    A dictionary of event emitter listeners.

    See source

  • _throttledSave : function

    private

    Throttled save method. The save() method is called the specified saveInterval after throttledSave() is called, unless a new action happens in the meantime.

    See source

Methods

  • constructor( Editor, [ watchdogConfig ] )

    Parameters

    Editor : *

    The editor class.

    [ watchdogConfig ] : WatchdogConfig

    The watchdog plugin configuration.

  • create( [ elementOrData ], [ config ], [ context ] ) → Promise

    Creates the editor instance and keeps it running, using the defined creator and destructor.

    See source

    Parameters

    [ elementOrData ] : HTMLElement | String | Object.<(String | String)>

    The editor source element or the editor data.

    [ config ] : EditorConfig

    The editor configuration.

    [ context ] : Object

    A context for the editor.

    Returns

    Promise

  • destroy() → Promise

    Destroys the watchdog and the current editor instance. It fires the callback registered in setDestructor() and uses it to destroy the editor instance. It also sets the state to destroyed.

    See source

    Returns

    Promise

  • off( eventName, callback )

    inherited

    Stops listening to the specified event name by removing the callback from event listeners.

    See source

    Note that this method differs from the CKEditor 5's default EventEmitterMixin implementation.

    Parameters

    eventName : String

    The event name.

    callback : function

    A callback which will be removed from event listeners.

  • on( eventName, callback )

    inherited

    Starts listening to a specific event name by registering a callback that will be executed whenever an event with a given name fires.

    See source

    Note that this method differs from the CKEditor 5's default EventEmitterMixin implementation.

    Parameters

    eventName : String

    The event name.

    callback : function

    A callback which will be added to event listeners.

  • setCreator( creator )

    Sets the function that is responsible for the editor creation. It expects a function that should return a promise.

    See source
    watchdog.setCreator( ( element, config ) => ClassicEditor.create( element, config ) );

    Parameters

    creator : function

  • setDestructor( destructor )

    Sets the function that is responsible for the editor destruction. Overrides the default destruction function, which destroys only the editor instance. It expects a function that should return a promise or undefined.

    See source
    watchdog.setDestructor( editor => {
    // Do something before the editor is destroyed.

    return editor
        .destroy()
        .then( () => {
            // Do something after the editor is destroyed.
        } );
} );

    Parameters

    destructor : function

  • _fire( eventName, args )

    protected inherited

    Fires an event with a given event name and arguments.

    See source

    Note that this method differs from the CKEditor 5's default EventEmitterMixin implementation.

    Parameters

    eventName : String

    The event name.

    args : *

    Event arguments.

  • _isErrorComingFromThisItem( error )

    protected

    Traverses the error context and the current editor to find out whether these structures are connected to each other via properties.

    See source

    Parameters

    error : CKEditorError

  • _restart() → Promise

    protected

    Restarts the editor instance. This method is called whenever an editor error occurs. It fires the restart event and changes the state to initializing.

    See source

    Returns

    Promise

    Fires

  • _setExcludedProperties( props )

    protected

    Parameters

    props : Set

  • _startErrorHandling()

    protected inherited

    Starts error handling by attaching global error handlers.

    See source

  • _stopErrorHandling()

    protected inherited

    Stops error handling by detaching global error handlers.

    See source

  • _boundErrorHandler()

    private inherited

    Checks if the event error comes from the underlying item and restarts the item.

    See source

  • _cloneEditorConfiguration( config )

    private

    Clones the editor configuration.

    See source

    Parameters

    config : Object

  • _destroy() → Promise

    private

    Returns

    Promise

  • _getData() → Object.<String, String>

    private

    Returns the editor data.

    See source

    Returns

    Object.<String, String>

  • _handleError( error, evt )

    private inherited

    Checks if an error comes from the watched item and restarts it. It reacts to CKEditorError errors only.

    See source

    Parameters

    error : Error

    Error.

    evt : ErrorEvent | PromiseRejectionEvent

    An error event.

    Fires

  • _save()

    private

    Saves the editor data, so it can be restored after the crash even if the data cannot be fetched at the moment of the crash.

    See source

  • _shouldReactToError( error )

    private inherited

    Checks whether an error should be handled by the watchdog.

    See source

    Parameters

    error : Error

    An error that was caught by the error handling process.

  • _shouldRestart()

    private inherited

    Checks if the watchdog should restart the underlying item.

    See source

Events

  • error( eventInfo )

    inherited

    Fired when a new CKEditorError error connected to the watchdog instance occurs and the watchdog will react to it.

    See source
    watchdog.on( 'error', ( evt, { error, causesRestart } ) => {
    console.log( 'An error occurred.' );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • restart( eventInfo )

    Fired after the watchdog restarts the error in case of a crash.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.