The Basics of Customizing the Web Editor

Let's start with the basics.

Locations#

To understand the extension points of the web editor, it is helpful to know about the different areas or locations of the editor where you can customize the behavior or appearance. Let's take a look at these locations.

Canvas#

The canvas is the main area of the editor where the user interacts with design content. This part is completely controlled by the Creative Engine. It is basically the core of CE.SDK and the web editor is build around it. This is also the part you need to interact with if you want to create a complete custom UI and not use the web editor.

Here is more information about how to control this area via API.

Dock#

The dock is the main entry point for user interactions not directly related to the currently selected block. It occupies a prominent place in the editor and is primarily, though not exclusively, used to open panels with asset libraries. Therefore, the default and recommended position of the asset library panel is on the side of the dock. However, depending on the use case, it might be beneficial to add other buttons and functionalities (even block-specific ones) to highlight them due to the prominence of the dock.

Here is more information about APIs specific to this location.

Canvas Menu#

For every selected block on the canvas, the canvas menu appears either above or below the frame of the selected block. This menu provides the most important block-specific actions and settings, ensuring they are immediately visible to the user. It is recommended to add as few elements as possible to the canvas menu to keep it clean and focused.

Here is more information about APIs specific to this location.

Inspector Bar#

The main location for block-specific functionality is the inspector bar. Any action or setting available to the user for the currently selected block that does not appear in the canvas menu should be added here.

Here is more information about APIs specific to this location.

Navigation Bar#

Actions that affect browser navigation (e.g. going back or closing the editor), have global effects on the scene (e.g. undo/redo and zoom), or process the scene in some way (e.g. saving and exporting) should be placed in the navigation bar.

Here is more information about APIs specific to this location.

Canvas Bar#

The canvas bar is intended for actions that affect the canvas or scene as a whole. Undo/redo or zoom controls can be placed here as an alternative to the navigation bar.

Here is more information about APIs specific to this location.

Controlling the Order of a Location#

The key APIs to customize the different locations of the web editor are the specific Order APIs. These APIs allow you to control what is displayed in the different locations and in what order or layout. Each location has its own Order API that you can use to add, remove, or reorder components, e.g., setDockOrder, setCanvasMenuOrder, setInspectorBarOrder, setNavigationBarOrder, and setCanvasBarOrder.

At its core, these methods take an array of IDs that represent components. The CE.SDK web editor provides a set of predefined components for various purposes.

For instance, ly.img.delete.canvasMenu represents a button in the canvas menu that is used to delete the currently selected block. In the default order of the canvas menu, this ID is already included at the very end. If, for some use-case-related reason, you decide that this button should be placed at the beginning of the canvas menu, you need to push this ID to the beginning of the order and set it with setCanvasMenuOrder. If you decide to remove it completely from the canvas menu and allow the user to delete blocks only via the inspector bar, you can simply omit this ID from the order you set with setCanvasMenuOrder. Please refer to the corresponding API reference for a list of available components for each location.

Layout Components#

In addition to functional components, the CE.SDK web editor provides a few special components that can be used to control the layout of different locations. For instance, ly.img.separator is a special component that can be used to separate different groups of components. If you want to separate the default components of the canvas menu from your custom components, you can add this separator to the order you set with setCanvasMenuOrder.

Another layout component is ly.img.spacer. The spacer is a simple component that can be used to add space between components. All spacers will take up the remaining space of the location and push the following components to the right side of the location. If a single spacer is placed at the beginning of an order, all other components will be aligned to the right side. If a spacer is placed at both the beginning and the end of an order, all components will be centered.

Registration of new Components#

Besides the predefined components, you can also register your own components. We provide a set of builder components such as buttons, dropdowns, and inputs that you can use to create custom components with entirely unique behavior and logic.

Once registered with registerComponent, they can be used in various locations of the web editor via the Order APIs. This allows you to deeply integrate your logic into the web editor and make it a part of the user experience.

Additionally, if you are not satisfied with the behavior or appearance of our default components, you can override them with your own implementations.

cesdk.ui.registerComponent( 'myCustomComponent', ({ builder: { Button }, engine }) => {
    const selectedBlockIds = engine.block.findAllSelected();
    if (selectedBlockIds.length !== 0) {
      return;
    }

    const [selectedBlockId] = selectedBlockIds;

    const kind = engine.block.getKind(selectedBlockId);

    if (kind === 'jumper') {
      Button('jumper-button', {
        label: 'Jump!',
        onClick: () => {
          engine.block.setPositionX(
            selectedBlockId,
            engine.block.getPositionX(selectedBlockId) + 100
          );
        }
      });
    }
  }
);

Enable or Disable Features#

Sometimes it is sufficient to completely remove a component from a location by removing it from the order. However, in some cases, you might want to keep the component only for certain blocks but keep it for other. You could do this by overriding the component with a custom implementation that checks the current block and decides whether to show the component or not but that is rather cumbersome.

To make this easier, we provide the Feature API that allows you to control components on a feature level for the current context. You can write your own or hook into existing features from the web editor or plugins.

Let's say you introduced a new kind of block that represents an Avatar. Regardless of scopes or the current mode of the editor, you want to not show the duplicate & delete button in the canvas menu for this kind of block. You can achieve this calling enable('ly.img.delete.canvasMenu', (context) = {[...]}) and return false for the Avatar block.

Putting It All Together#

The web editor provides a set of APIs that can be grouped into three categories: Order APIs, Component APIs, and Feature APIs. This separation allows for multiple use cases of customization. When used together, these APIs can be employed to make small adjustments to the default behavior of the editor or installed plugins, extend and deeply integrate custom logic, or completely redefine the default behavior.