SchemaCheckAttributeEvent (engine/model)

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

Note: The addAttributeCheck 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 checkAttribute 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 the standard behavior of the checkAttribute() method. Let's see a typical listener template:

schema.on( 'checkAttribute', ( evt, args ) => {
	const context = args[ 0 ];
	const attributeName = 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 checkAttribute( context, attributeName ). However, the context parameter is already normalized to a SchemaContext instance, so you do not have to worry about the various ways how context may be passed to checkAttribute().

So, in order to implement a rule "disallow bold in a text which is in a heading1, you can add such a listener:

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

	if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
		// Prevent next listeners from being called.
		evt.stop();
		// Set the checkAttribute()'s return value.
		evt.return = false;
	}
}, { priority: 'high' } );

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

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

	if ( context.endsWith( 'bar foo $text' ) && attributeName == 'bold' ) {
		// Prevent next listeners from being called.
		evt.stop();
		// Set the checkAttribute()'s return value.
		evt.return = true;
	}
}, { priority: 'high' } );