How to Create a Plugin

Creating your own plugin can be useful for your integration if you want to bundle features together or even publish them for others to use.

Create a Plugin#

Plugins are added to the editor using the addPlugin method. This method takes a plugin object that needs to provide specific properties and methods.

The most important method is initialize, which is called when the plugin is added to the editor. It will receive the current execution context as an argument. If the plugin is added only to the engine, the cesdk argument will be undefined. This allows you to write plugins that can be used for both the engine and the editor.

You can pass this MyPlugin object directly to the addPlugin method. If you plan to publish your plugin in private or public repositories, this object is what should be exported.

However, most plugins will need some kind of configuration. If you expose a plugin, it is a good convention to export a function that returns the plugin object and accepts a config object as an argument. Even if you don't need any configuration yet, it is recommended to use this pattern to avoid breaking user code in the future once you introduce an optional configuration.

const MyPlugin = () => ({
  name: 'MyPlugin',
  version: '1.0.0',
  initialize: ({
    // This argument is only defined if the plugin is added to the editor.
    // If you call the `addPlugin` method on the engine, this argument will be undefined.
    cesdk,
    // The engine is always defined
    engine
  }) => {
    // Your plugin code here
  }
});

cesdk.ui.addPlugin(MyPlugin());

Initialization of a Plugin#

What is supposed to be done in the initialize method of a plugin? There are no enforced rules, but some conventions are recommended, especially if you plan to publish your plugin in any way.

Adding a plugin will call the initialize method of the plugin object directly. The purpose of this method is to register components, and features, or subscribe to events and changes of blocks. It is not supposed to immediately execute any action or make changes to the editor.

This includes changing the order of any location, such as adding a new component to it. The integrator of the plugin needs to decide when to add which component and where. If the plugin wants to add a shortcut for that, the default locations can be optionally set via the plugin configuration.

const MyPlugin = ({ ui: { locations } }) => ({
  name: 'MyPlugin',
  version: '1.0.0',
  initialize: ({ cesdk, engine }) => {
    // Register a new components
    cesdk.ui.registernComponent('myComponent.canvasMenu', [...]);
    cesdk.ui.registernComponent('myComponent.inspectorBar', [...]);

    // Register a new feature
    cesdk.feature.enable('myFeature', true);

    // Subscribe to events or similar
    // [...]

    if (locations.includes('canvasMenu') {
      cesdk.ui.setCanvasMenuOrder(['myComponent.canvasMenu', ...cesdk.ui.getCanvasMenuOrder()]);
    }
    if (locations.includes('inspectorBar') {
      cesdk.ui.setInspectorBarOrder(['myComponent.inspectorBar', ...cesdk.ui.getInspectorBarOrder()]);
    }
  }
});