How to Write Custom Panels

Similar to registering custom components, the CE.SDK web editor allows you to render custom panels. Built-in UI elements ensure that your custom panel blends seamlessly with the editor's look and feel, while still enabling you to adapt the editor to your unique workflows.

registerPanel(panelId: string, renderFunction: ({ builder, engine, state }) => void)

Registers a panel whose content can be rendered with a panel builder, similar to how custom components are registered.

The builder's render function is called with three arguments: the builder, the engine, and the state. The builder object is used to define which base components (such as buttons) should be rendered. The engine is used to retrieve any state from the engine. The render function will be called again if any engine-related state changes occur due to engine calls or the local state was updated.

• panelId: The unique ID of the new registered panel.
• renderFunction: The render function of the panel.

When is a Panel Rendered?#

It is important concept to understand when a panel re-renders after its initial rendering. The component assumes that all its state is stored in the engine or the local state. Whenever we detect a change that is relevant for this panel it will re-render.

Using the Engine#

Inside the render function, any calls that retrieve values from the engine will be tracked. If a change is detected, the render function will be automatically re-called.

For example, in a panel, we could query for all selected blocks and decide whether to render a button based on the result. The engine detects the call to findAllSelected and knows that if the selection changes, it needs to re-render the panel. This behavior applies to all methods provided by the engine.

Using Local State#

Besides the engine, the render function also receives a state argument to manage local state. This can be used to control input components or store state in general. When the state changes, the panel will be re-rendered as well.

The state argument is a function that is called with a unique ID for the state. Any subsequent call to the state within this panel will return the same state. The second optional argument is the default value for this state. If the state has not been set yet, it will return this value. Without this argument, you'll need to handle undefined values manually.

The return value of the state call is an object with value and setValue properties, which can be used to get and set the state. Since these property names match those used by input components, the object can be directly spread into the component options.

cesdk.ui.registerPanel('counter', ({ builder, state }) => {
  const urlState = state('url', '');
  const { value, setValue } = state('counter', 0);

  builder.Section('counter', {
    children: () => {
      builder.TextInput('text-input-1', {
        inputLabel: 'TextInput 1',
        ...urlState
      });

      builder.Button('submit-button', {
        label: 'Submit',
        onClick: () => {
          const pressed = value + 1;
          setValue(pressed);
          console.log(
            `Pressed ${pressed} times with the current URL ${urlState.value}`
          );
        }
      });
    }
  });
});

Integrate the Panel into the Editor#

After registering a component, it is not automatically opened or integrated in any other way. The CE.SDK editor is just aware that there is a panel with this id.

Opening a Panel#

Once a panel is registered, it can be controlled using the Panel API, just like any other panel. For instance, you can open a custom panel with cesdk.ui.openPanel(registeredPanelId). Other settings, such as position and floating, can also be adjusted accordingly.

In most cases, you will want to open it using a custom button, .e.g in a button inside the Dock or Inspector Bar.

Setting the Title of a Custom Panel#

The title of a panel is determined by a translation based on the panel's ID. For example, if the panel ID is myCustomPanel, the corresponding translation key would be panel.myCustomPanel.

cesdk.setTranslations({
  en: {
    'panel.myCustomPanel': 'My Custom Panel',
  },
  de: {
    'panel.myCustomPanel': 'Mein eigenes Panel',
  }
});

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.

Builder Components#

The following builder components can be used inside a registered panel.

Button#

A simple button to react on a user click.

ButtonGroup#

Grouping of multiple buttons in a single segmented control.

Checkbox#

A labeled checkbox.

ColorInput#

A big color swatch that opens a color picker when clicked.

Dropdown#

A button that opens a dropdown with additional content when the user clicks on it.

Heading#

Renders its content as heading to the panel.

Library#

A complete asset library with a search option.

MediaPreview#

A large preview area showing an image or color. Optionally contains a button in the bottom right corner, offering contextual action.

NumberInput#

A number input field.

Select#

A dropdown to select one of multiple choices.

Separator#

Adds a separator (<hr> element) in the panel to help the visual separation of entries. This builder component has no properties.

Slider#

A slider for intuitively adjusting a number.

Text#

A piece of non-interactive text.

TextArea#

A large text field accepting user input.

TextInput#

A small text field accepting user input.