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

ContextWatchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/contextwatchdog

class
See source

A watchdog for the Context class.

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

Filtering

Properties

  • context : Context | null

    The context instance. Keep in mind that this property might be changed when the context watchdog restarts, so do not keep this instance internally. Always operate on the ContextWatchdog#context property.

    See source

  • 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,

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

  • 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

  • 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

  • _watchdogs : Map.<string, EditorWatchdog>

    protected

    A map of internal watchdogs for added items.

    See source

  • _actionQueues : ActionQueues

    private

    An action queue, which is used to handle async functions queuing.

    See source

  • _config : Object | undefined

    private

    The context configuration.

    See source

  • _context : Context | null

    private

    The current context instance.

    See source

  • _contextConfig : Object

    private

    The configuration for the Context.

    See source

  • _contextProps : Set.<*>

    private

    Context properties (nodes/references) that are gathered during the initial context creation and are used to distinguish the origin of an error.

    See source

  • _listeners : Object.<String, Function>>

    private inherited

    A dictionary of event emitter listeners.

    See source

  • _watchdogConfig : WatchdogConfig

    private

    The watchdog configuration.

    See source

Methods

  • constructor( Context, [ watchdogConfig ] )

    The context watchdog class constructor.

    See source
    const watchdog = new ContextWatchdog( Context );

await watchdog.create( contextConfiguration );

await watchdog.add( item );

    See the Watchdog feature guide to learn more how to use this feature.

    Parameters

    Context : function

    The Context class.

    [ watchdogConfig ] : WatchdogConfig

    The watchdog configuration.

  • add( itemConfigurationOrItemConfigurations ) → Promise

    Adds items to the watchdog. Once created, instances of these items will be available using the getItem method.

    See source

    Items can be passed together as an array of objects:

    await watchdog.add( [ {
	id: 'editor1',
	type: 'editor',
	sourceElementOrData: document.querySelector( '#editor' ),
	config: {
		plugins: [ Essentials, Paragraph, Bold, Italic ],
		toolbar: [ 'bold', 'italic', 'alignment' ]
	},
	creator: ( element, config ) => ClassicEditor.create( element, config )
} ] );

    Or one by one as objects:

    await watchdog.add( {
	id: 'editor1',
	type: 'editor',
	sourceElementOrData: document.querySelector( '#editor' ),
	config: {
		plugins: [ Essentials, Paragraph, Bold, Italic ],
		toolbar: [ 'bold', 'italic', 'alignment' ]
	},
	creator: ( element, config ) => ClassicEditor.create( element, config )
] );

    Then an instance can be retrieved using the getItem method:

    const editor1 = watchdog.getItem( 'editor1' );

    Note that this method can be called multiple times, but for performance reasons it is better to pass all items together.

    Parameters

    itemConfigurationOrItemConfigurations : WatchdogItemConfiguration | Array.<WatchdogItemConfiguration>

    An item configuration object or an array of item configurations.

    Returns

    Promise

  • create( [ contextConfig ] ) → Promise

    Initializes the context watchdog. Once it is created, the watchdog takes care about recreating the context and the provided items, and starts the error handling mechanism.

    See source
    await watchdog.create( {
	plugins: []
} );

    Parameters

    [ contextConfig ] : Object

    The context configuration. See Context.

    Returns

    Promise

  • destroy()

    inherited

    Destroys the watchdog and releases the resources.

    See source

  • getItem( itemId ) → *

    Returns an item instance with the given itemId.

    See source
    const editor1 = watchdog.getItem( 'editor1' );

    Parameters

    itemId : String

    The item ID.

    Returns

    *

    The item instance or undefined if an item with a given ID has not been found.

  • getItemState( itemId ) → 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    Gets the state of the given item. See state for a list of available states.

    See source
    const editor1State = watchdog.getItemState( 'editor1' );

    Parameters

    itemId : String

    Item ID.

    Returns

    'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    The state of the item.

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

  • remove( itemIdOrItemIds ) → Promise

    Removes and destroys item(s) with given ID(s).

    See source
    await watchdog.remove( 'editor1' );

    Or

    await watchdog.remove( [ 'editor1', 'editor2' ] );

    Parameters

    itemIdOrItemIds : Array.<String> | String

    Item ID or an array of item IDs.

    Returns

    Promise

  • setCreator( creator )

    inherited

    Sets the function that is responsible for the context creation. It expects a function that should return a promise (or undefined).

    See source
    watchdog.setCreator( config => Context.create( config ) );

    Parameters

    creator : function

  • setDestructor( destructor )

    inherited

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

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

	return context
		.destroy()
		.then( () => {
			// Do something after the context 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.

  • _getWatchdog( itemId ) → Watchdog

    protected

    Returns the watchdog for a given item ID.

    See source

    Parameters

    itemId : String

    Item ID.

    Returns

    Watchdog

    Watchdog

  • _isErrorComingFromThisItem( error ) → Boolean

    protected

    Checks whether an error comes from the context instance and not from the item instances.

    See source

    Parameters

    error : Error

    Returns

    Boolean

  • _restart() → Promise

    protected

    Restarts the context watchdog.

    See source

    Returns

    Promise

  • _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

  • _create() → Promise

    private

    Returns

    Promise

  • _destroy() → Promise

    private

    Destroys the context instance and all added items.

    See source

    Returns

    Promise

  • _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

  • _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.

  • itemError( eventInfo )

    Fired when a new error occurred in one of the added items.

    See source
    watchdog.on( 'itemError', ( evt, { error, itemId, causesRestart } ) => {
	console.log( `An error occurred in an item with the '${ itemId }' ID.` );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • itemRestart( eventInfo )

    Fired after an item has been restarted.

    See source
    watchdog.on( 'itemRestart', ( evt, { itemId } ) => {
	console.log( 'An item with with the '${ itemId }' ID has been restarted.' );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • restart( eventInfo )

    Fired after the watchdog restarts the context and the added items because of a crash.

    See source
    watchdog.on( 'restart', () => {
	console.log( 'The context has been restarted.' );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.