Advanced customization

AI-generated Key Takeaways

• Blockly allows customization by replacing default classes that implement specific interfaces.

• A replacement class should implement the corresponding interface functions, either by creating a new class or extending a Blockly class.

• You can inform Blockly about your replacement class by registering it as the default for its type or by injecting it using the plugins configuration option during initialization.

• Registering as the default uses Blockly.registry.register with Blockly.registry.DEFAULT and opt_allowOverrides set to true.

• Injecting uses the plugins property in the Blockly.inject configuration, mapping the registry type name to the replacement class or its registered name.

Blockly lets you customize certain functionality by replacing the corresponding Blockly classes.

Replaceable classes

The following Blockly classes can be replaced:

Blockly class	Interface	Registry type name
Blockly.dragging.Dragger	Blockly.IDragger	blockDragger
Blockly.ConnectionChecker	Blockly.IConnectionChecker	connectionChecker
Blockly.InsertionMarkerPreviewer	Blockly.IConnectionPreviewer	connectionPreviewer
Blockly.HorizontalFlyout	Blockly.IFlyout	flyoutsHorizontalToolbox
Blockly.VerticalFlyout	Blockly.IFlyout	flyoutsVerticalToolbox
Blockly.MetricsManager	Blockly.IMetricsManager	metricsManager
Blockly.Toolbox	Blockly.IToolbox	toolbox
Blockly.VariableMap	Blockly.IVariableMap	variableMap
Blockly.VariableModel	Blockly.IVariableModel	--

For information about how to replace a renderer, see Create custom renderers.

Create a replacement class

To create a replacement class, implement the functions in the corresponding interface. You can implement all of these functions in a new class, or extend the Blockly class and only override the functions you want to change. The only requirement is that you (or the base class) implement all of the functions in the interface and adhere to any requirements described in comments on the interface.

To indicate to the type checker that you implement a specific interface, annotate your class with the @implements {InterfaceName} JSDoc tag (in JavaScript) or the implements keyword (in TypeScript).

Tell Blockly about your replacement class

There are two ways to tell Blockly about your replacement class: register it as the default class of its type (preferred) or inject it using the plugins configuration option.

Register your replacement class as the default

The preferred way to tell Blockly about your replacement class is to register it as the default for its type. To do this, call Blockly.registry.register using the name Blockly.registry.DEFAULT and set the opt_allowOverrides parameter to true.

Blockly.registry.register(
  Blockly.registry.Type.VARIABLE_MODEL,
  Blockly.registry.DEFAULT,
  CustomVariableModel,
  true,
);

Inject your replacement class

You can also inject replacement classes using the plugins configuration option. This is an object that uses registry type names as property names and replacement classes or registered names as property values.

(In spite of the plugins property's name, your class does not need to be packaged and distributed through npm like the plugins used to extend Blockly.)

Either pass your replacement class to Blockly.inject:

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Or register your class using Blockly.registry.register and pass the registered name to Blockly.inject. This is useful if you store your configuration options as pure JSON.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', CustomMetricsManagerClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}