SchemaCheckChildEvent (engine/model)

Event fired when the checkChild method is called. It allows plugging in additional behavior, for example implementing rules which cannot be defined using the declarative SchemaItemDefinition interface.

Note: The addChildCheck method is a more handy way to register callbacks. Internally, it registers a listener to this event but comes with a simpler API and it is the recommended choice in most of the cases.

The checkChild method fires an event because it is decorated with it. Thanks to that you can use this event in various ways, but the most important use case is overriding standard behavior of the checkChild() method. Let's see a typical listener template:

schema.on( 'checkChild', ( evt, args ) => {
	const context = args[ 0 ];
	const childDefinition = args[ 1 ];
}, { priority: 'high' } );

The listener is added with a high priority to be executed before the default method is really called. The args callback parameter contains arguments passed to checkChild( context, child ). However, the context parameter is already normalized to a SchemaContext instance and child to a SchemaCompiledItemDefinition instance, so you do not have to worry about the various ways how context and child may be passed to checkChild().

Note: childDefinition may be undefined if checkChild() was called with a non-registered element.

So, in order to implement a rule "disallow heading1 in blockQuote", you can add such a listener:

schema.on( 'checkChild', ( evt, args ) => {
	const context = args[ 0 ];
	const childDefinition = args[ 1 ];

	if ( context.endsWith( 'blockQuote' ) && childDefinition && childDefinition.name == 'heading1' ) {
		// Prevent next listeners from being called.
		evt.stop();
		// Set the checkChild()'s return value.
		evt.return = false;
	}
}, { priority: 'high' } );

Allowing elements in specific contexts will be a far less common use case, because it is normally handled by the allowIn rule from SchemaItemDefinition. But if you have a complex scenario where listItem should be allowed only in element foo which must be in element bar, then this would be the way:

schema.on( 'checkChild', ( evt, args ) => {
	const context = args[ 0 ];
	const childDefinition = args[ 1 ];

	if ( context.endsWith( 'bar foo' ) && childDefinition.name == 'listItem' ) {
		// Prevent next listeners from being called.
		evt.stop();
		// Set the checkChild()'s return value.
		evt.return = true;
	}
}, { priority: 'high' } );