Control the CreativeEditor UI via API

Once the CreativeEditor is initialized, the user interface can be controlled with the following API. This will allow us to integrate the editor in a broader context and leverage more use cases and workflows.

Panel API#

Panels are a basic concept of our UI, e.g. extensively used for asset libraries and inspectors. Given a CreativeEditorSDK instance, we can query if a given panel is open as well as access methods to open/close them.

cesdk.ui.isPanelOpen(panelId: string, options?: { position?: PanelPosition, floating?: boolean }): boolean returns true if a panel with the given panel id is open. If options are provided they will be matched against the panel's options. E.g. isPanelOpen('//ly.img.panel/assetLibrary', { floating: false }) will only return true if the asset library is open as a floating panel.

cesdk.ui.openPanel(panelId: string, options?: { position?: PanelPosition, floating?: boolean }) opens a panel with the given id if and only if it exists, is not open and is currently registered (known to the UI). Otherwise the method does nothing and is a noop. Options can be provided additionally that will override the default position and floating of the given panel. Please note, that the default position and floating behavior are not changed for this panel.

cesdk.ui.closePanel(panelId: string) closes a panel with the given id if and only if it exists and is open. Otherwise the method does nothing and is a noop.

Panel Position#

Every panel in the UI is typically displayed either on the left or right side of the canvas. An exception exists for rendering in smaller viewports, where all panels are situated at the bottom.

The setPanelPosition API is used to determine a panel's default placement.

cesdk.ui.setPanelPosition(panelId: string, panelPosition: PanelPosition) assigns a specific position to a panel identified by panelId. This function will also alter the panel's position while it is open, provided the panel wasn't initially opened with a pre-defined position option (see above).

Floating Panel#

Panels can either float over the canvas, potentially obscuring content, or be positioned adjacent to the canvas. The setPanelFloating API allows you to modify this behavior to suit different use cases.

cesdk.ui.setPanelFloating(panelId: string, floating: boolean) when set to true, the specified panel will float above the canvas. Conversely, setting it to false places the panel beside the canvas.

Available Panels#

Currently we support the following panel ids.

Panel Id	Description
Panel Id `//ly.img.panel/inspector`	Description The inspector panel for the currently selected block. Please note, that if no block is selected at all, this will open an empty panel with no content. In the advanced view, inspector panels are always open and cannot be opened/closed.
Panel Id `//ly.img.panel/assetLibrary`	Description The panel for the asset library, Please note, that currently it is ot possible to open a new asset library with library entries defined. Thus, opening an asset library would show an empty library. More useful is `closePanel` to close an already open asset library.
Panel Id `//ly.img.panel/assetLibrary.replace`	Description The panel containing the replace library for the currently selected block. Please note, that if no block is selected or the selected block does not have asset replacement configured, the opened library will be empty. See Custom Asset Library for more information.
Panel Id `//ly.img.panel/settings`	Description The settings panel to customize the editor during runtime.

Notifications#

The CE.SDK editor brings a notification API designed to deliver non-intrusive messages to the user, appearing in the lower right corner of the user interface. Use them to convey information without disrupting the user's current workflow. It provides a range of customization options to fit your specific needs.

cesdk.ui.showNotification(notification: string | Notification): string displays a new notification to the user, accepting either a simple string message or a more complex notification object that allows for additional configuration options (detailed below). It returns an id of the notification.
cesdk.ui.updateNotification(notificationId: string, notification: Notification): updates a notification given by the id. All configuration options can be changed. If the notificationId` doesn't exist or the notification has already been dismissed, this action will have no effect.
cesdk.ui.dismissNotification(notificationId: string) removes a notification identified by the provided notification notificationId. If the notificationId doesn't exist or the notification has already been dismissed, this action will have no effect.

Notification Options#

All options apart from message are optional

Option	Description
Option `message`	Description The message displayed on the notification. This can either be a string or an internationalization (i18n) key from the CE.SDK translations, allowing for localized messages.
Option `type`	Description Notifications can be displayed in various styles, each differing in appearance to convey the appropriate context to the user. The available types include `info` (which is the default setting), `warning`, `error`, `success`, and `loading` (which displays a loading spinner).
Option `duration`	Description Notifications typically disappear after a set period, but the duration can vary based on the message's importance. Less critical updates may vanish swiftly, whereas warnings or significant alerts stay open for a longer time. You can specify this duration using either a numerical value representing milliseconds or predefined strings from CE.SDK, such as `short`, `medium` (which is the default setting), or `long`, each corresponding to different default durations. For notifications that should remain visible indefinitely, the `infinite` value can be used to prevent automatic dismissal.
Option `onDismiss`	Description A callback function that is triggered upon the dismissal of the notification, whether it's done automatically, programmatically, or manually by the user.
Option `action: { label: "Retry", onClick: () => void }`	Description Adds a single action button within the notification for user interaction.

Dialogs#

The CE.SDK editor provides a dialog API to display modal dialogs to the user. Dialogs are used to convey important information, warnings, or to request user input. They can be customized to fit your specific needs. The dialog API provides methods to show, update, and close dialogs. Dialogs can be updated on the fly to reflect changes in the underlying data or to provide feedback to the user.

cesdk.ui.showDialog(dialog: string | Dialog): string displays a new dialog to the user, accepting either a simple string message or a more complex dialog object that allows for additional configuration options (detailed below). It returns an id of the dialog.
cesdk.ui.updateDialog(dialogId: string, dialog: Dialog) updates a dialog given by the id. All configuration options can be changed. If the dialogId doesn't exist or the dialog has already been dismissed, this action will have no effect.
cesdk.ui.closeDialog(dialogId: string) removes a dialog identified by the provided dialog dialogId. If the dialogId doesn't exist or the dialog has already been dismissed, this action will have no effect.

Dialog Options#

All options apart from content are optional. All strings can be internationalization (i18n) keys from the CE.SDK translations, allowing for localized messages.

Option	Description
Option `type`	Description The type of dialog to display. The available types include `regular`, `success`, `error`, `info`, `warning`, and `loading`. The default type is `regular`.
Option `size`	Description The size of the dialog. The available sizes include `regular` and `large`. The default size is `regular`.
Option `content`	Description The content of the dialog. This can either be a `string` or an object with a `title` and `message` property. The `title` is optional. The `message` can be a string or an array of strings.
Option `progress`	Description The progress of the dialog. This can be a `number`, `indeterminate`, or an object with a `value` and `max` property.
Option `actions`	Description An array of action objects. Each action object must have a `label` and an `onClick` function. The `variant` and `color` properties are optional. The `variant` can be `regular` or `plain`. The `color` can be `accent` or `danger`.
Option `cancel`	Description An action object that represents the cancel action. The structure is the same as for the `actions` property.
Option `onClose`	Description A callback function that is triggered when the dialog is closed. This can be used to perform cleanup operations or to trigger additional actions.
Option `clickOutsideToClose`	Description A boolean value that determines whether the dialog can be closed by clicking outside of it. The default value is `true`.


CreativeEditorSDK.create('#cesdk', config).then(async (cesdk) => {

  await cesdk.addDefaultAssetSources();
  await cesdk.addDemoAssetSources();

  // The inspector should be rendered on the left as a non-floating panel
  cesdk.ui.setPanelPosition('//ly.img.panel/inspector', 'left');
  cesdk.ui.setPanelFloating('//ly.img.panel/inspector', false);

  await cesdk.createDesignScene();

  // Adding some image after creating the scene
  const image = await cesdk.engine.asset.defaultApplyAsset({
    id: 'ly.img.cesdk.images.samples/sample.1',
    meta: {
      uri: 'https://cdn.img.ly/assets/demo/v1/ly.img.image/images/sample_1.jpg',
      width: 2500,
      height: 1667
    }
  });

  if (image == null) return;

  // Select the first image after loading the scene ...
  cesdk.engine.block.setSelected(image, true);

  // ... and opening the replace asset library for the user to choose a differnt image
  if (!cesdk.ui.isPanelOpen('//ly.img.panel/assetLibrary.replace')) {
    cesdk.ui.openPanel('//ly.img.panel/assetLibrary.replace');
  }

  // Open the inspector panel, but override the default position and floating we set above.
  cesdk.ui.openPanel('//ly.img.panel/inspector', { position: 'right', floating: true });


  cesdk.ui.showNotification("Welcome to our editor!");

  const notificationId = cesdk.ui.showNotification({
    type: 'loading', message: 'Loading data...', duration: 'infinite'
  });
  setTimeout(() => {
    cesdk.ui.updateNotification(notificationId, {
      type: 'success', message: "Data loaded", duration: 'short'
    });
  }, 5000);

  // Use the dialog API to show a simple dialog
  const simpleDialogId = cesdk.ui.showDialog(
    'This is a simple information Dialog'
  );

  // Use the API to close the dialog
  cesdk.ui.closeDialog(simpleDialogId);

  // Show a warning dialog
  cesdk.ui.showDialog({
    type: 'warning',
    content: {
      title: 'warning',
      message: 'This is a warning dialog'
    },
    actions: [
      { label: 'OK', onClick: (context) => cesdk.ui.closeDialog(context.id) }
    ],
    cancel: {
      label: 'Cancel',
      onClick: (context) => cesdk.ui.closeDialog(context.id)
    },
    onClose: () => console.log('Warning dialog closed')
  });

  // Show a simple loading dialog
  cesdk.ui.showDialog({
    type: 'loading',
    content: 'loading...',
    progress: 'indeterminate',
    cancel: {
      label: 'Cancel',
      onClick: (context) => cesdk.ui.closeDialog(context.id)
    }
  });

  // Show a large loading dialog with a progress value
  const largeProgressDialogId = cesdk.ui.showDialog({
    type: 'loading',
    content: {
      title: 'Loading',
      message: 'Loading data...'
    },
    progress: 0,
    cancel: {
      label: 'Cancel',
      onClick: (context) => cesdk.ui.closeDialog(context.id)
    }
  });

  // Update the progress value of the large loading dialog
  cesdk.ui.updateDialog(largeProgressDialogId, {
    progress: 50
  });
});