How to Write Custom Components

The CE.SDK web editor provides a set of built-in components that you can reference and render in a specific order. You can see a list of all available components in the respective documentation, including Dock, Canvas Menu, Inspector Bar, Navigation Bar and Canvas Bar.

Additionally, you can write your own custom components, register them, and use them just like the built-in components. This allows you to extend the functionality of the CE.SDK web editor with custom logic and create a more personalized experience for your users.

Registering a Custom Component#

The entry point for writing a custom component is the method registerComponent. For a given identifier, you add a function that will be called repeatedly to render this component. Several arguments are passed to this function that can be used to access the current state of the engine and render an UI with the help of the builder.

cesdk.ui.registerComponent('myCustomComponent', ({ builder: { Button }, engine }) => {
  const selectedIds = engine.block.findAllSelected();

  if (selectedIds.length !== 1) return;

  Button('button-id', {
    label: 'My Button',
    onClick: () => {
      console.log('Button clicked');
    }
  });
});

When is a Component Rendered?#

It is important concept to understand when this component re-renders after its initial rendering (e.g. the canvas menu was opened). The component assumes that all its state is stored in the engine. Whenever we detect a change that is relevant for this component it will re-render.

In the above example, we query for all selected blocks and based on the result we render a button or not. The engine detects the call to findAllSelected and now knows that if the selection changes, it needs to re-render this component. This works with all methods provided by the engine.

Passing Data to a Custom Component#

If you add a component to an order, you can either pass a string representing the component or an object with the id and additional data. This data can be accessed in the component function with inside the payload property.

cesdk.ui.registerComponent(
  'myDockEnry.dock',
  ({ builder: { Button }, engine, payload }) => {
    const { label } = payload;
    console.log("Label", label);
  }
);

cesdk.ui.setDockOrder([
  {
    id: 'myDockEnry.dock',
    label: "Custom Label"
  }
]);

Using the Builder#

The builder object passed to the render function provides a set of methods to create UI elements. Calling this method will add a builder component to the user interface. This includes buttons, dropdowns, text, etc.

Available Builder components#

Not every location supports every builder component yet. It will be extended over time. If you are unsure, you can always check the documentation of the respective component.