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

Type parameters

Properties

  • readonly inherited

    crashes : Array<object>

    See source

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

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

  • readonly

    editor : null | TEditor

    See source

    The current editor instance.

  • inherited

    state : WatchdogState

    See source

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

    • 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().

  • internal readonly

    _item : null | TEditor

    See source

  • protected

    _creator : EditorCreatorFunction<TEditor>

    See source

    The creation method.

    Related:

  • protected

    _destructor : ( Editor ) => Promise<unknown>

    See source

    The destruction method.

  • private

    _config : EditorConfig | undefined

    See source

    The editor configuration.

  • private

    _data : EditorData | undefined

    See source

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

  • private

    _editables : Record<string, HTMLElement>

    See source

    The latest record of the editor editable elements. Used to restart the editor.

  • private

    _editor : null | TEditor

    See source

    The current editor instance.

  • private

    _elementOrData : string | HTMLElement | Record<string, string> | Record<string, HTMLElement> | undefined

    See source

    The editor source element or data.

  • private

    _excludedProps : Set<unknown> | undefined

    See source

  • private

    _initUsingData : boolean

    See source

    Specifies whether the editor was initialized using document data (true) or HTML elements (false).

  • private

    _lastDocumentVersion : number | undefined

    See source

    The last document version.

  • private

    _lifecyclePromise : null | Promise<unknown>

    See source

    A promise associated with the life cycle of the editor (creation or destruction processes).

    It is used to prevent the initialization of the editor if the previous instance has not been destroyed yet, and conversely, to prevent the destruction of the editor if it has not been initialized.

  • private

    _throttledSave : DebouncedFunc<() => void>

    See source

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

Methods

  • constructor( Editor = { Editor.create }, watchdogConfig )

    See source

    Type parameters

    TEditor : extends [object Object] = default

    Parameters

    Editor : null | object

    The editor class.

    Properties
    Editor.create : Promise<TEditor>
    watchdogConfig : WatchdogConfig

    The watchdog plugin configuration.

    Defaults to {}

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

    See source

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

    Parameters

    elementOrData : string | HTMLElement | Record<string, string> | Record<string, HTMLElement>

    The editor source element or the editor data.

    Defaults to ...

    config : EditorConfig

    The editor configuration.

    Defaults to ...

    [ context ] : Context

    A context for the editor.

    Returns

    Promise<unknown>

  • destroy() → Promise<unknown>

    See source

    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.

    Returns

    Promise<unknown>

  • inherited

    off( eventName, callback ) → void

    See source

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

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

    Parameters

    eventName : keyof EventMap

    The event name.

    callback : unknown

    A callback which will be removed from event listeners.

    Returns

    void

  • inherited

    on( eventName, callback ) → void

    See source

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

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

    Type parameters

    K : extends keyof EventMap

    Parameters

    eventName : K

    The event name.

    callback : EventCallback<K>

    A callback which will be added to event listeners.

    Returns

    void

  • setCreator( creator ) → void

    See source

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

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

    Parameters

    creator : EditorCreatorFunction<TEditor>

    Returns

    void

  • setDestructor( destructor ) → void

    See source

    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.

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

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

    Parameters

    destructor : ( Editor ) => Promise<unknown>

    Returns

    void

  • internal

    _isErrorComingFromThisItem( error ) → boolean

    See source

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

    Parameters

    error : CKEditorError

    Returns

    boolean

  • internal

    _setExcludedProperties( props ) → void

    See source

    Parameters

    props : Set<unknown>

    Returns

    void

  • protected inherited

    _fire( eventName, args ) → void

    See source

    Fires an event with a given event name and arguments.

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

    Type parameters

    K : extends keyof EventMap

    Parameters

    eventName : K
    args : EventArgs<K>

    Returns

    void

  • protected

    _restart() → Promise<unknown>

    See source

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

    Returns

    Promise<unknown>

    Fires

  • protected inherited

    _startErrorHandling() → void

    See source

    Starts error handling by attaching global error handlers.

    Returns

    void

  • protected inherited

    _stopErrorHandling() → void

    See source

    Stops error handling by detaching global error handlers.

    Returns

    void

  • private

    _cloneEditorConfiguration( config ) → EditorConfig

    See source

    Clones the editor configuration.

    Parameters

    config : EditorConfig

    Returns

    EditorConfig

  • private

    _destroy() → Promise<unknown>

    See source

    Returns

    Promise<unknown>

  • private

    _getData() → EditorData

    See source

    Gets all data that is required to reinitialize editor instance.

    Returns

    EditorData

  • private

    _getEditables() → Record<string, HTMLElement>

    See source

    For each attached model root, returns its HTML editable element (if available).

    Returns

    Record<string, HTMLElement>

  • private

    _save() → void

    See source

    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.

    Returns

    void

Events

  • inherited

    error( eventInfo, <anonymous> )

    See source

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

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    <anonymous> : WatchdogErrorEventData

  • restart( eventInfo )

    See source

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • inherited

    stateChange( eventInfo )

    See source

    Fired when the watchdog state changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.