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.

Configure Dock

iconSize: string is used to set the dock button icon size to large (24px) or normal (16px).
hideLabels: boolean shows or hides the labels inside the docks buttons.

import CreativeEditorSDK from 'https://cdn.img.ly/packages/imgly/cesdk-js/1.51.0/index.js';

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  ui: {
    elements: {
      view: 'default',
      /* ... */
      navigation: {
        /* ... */
      },
      panels: {
        /* ... */
      },
      dock: {
        iconSize: 'large', // 'large' or 'normal'
        hideLabels: false, // false or true
      },
      libraries: {
        /* ... */
      },
      blocks: {
        /* ... */
      },
    },
  },
  callbacks: { onUpload: 'local' }, // Enable local uploads in Asset Library.
};

CreativeEditorSDK.create('#cesdk_container', config).then(async instance => {
  // Do something with the instance of CreativeEditor SDK, for example:
  // Populate the asset library with default / demo asset sources.
  instance.addDefaultAssetSources();
  instance.addDemoAssetSources({ sceneMode: 'Design' });
  await instance.createDesignScene();
});

Rearrange Dock Components

There are 2 APIs for getting and setting the order of components in the Dock.

The content of the Dock changes based on the current edit mode ('Transform' (the default), 'Text', 'Crop', 'Trim', or a custom value), so both APIs accept an orderContext argument to specify the mode.

For example usage of these APIs, see also Moving Existing Buttons or Adding New Buttons in the Guides section.

Get the Current Order

getDockOrder(
  orderContext: OrderContext = { editMode: 'Transform' }
)

When omitting the orderContext parameter, the order for the 'Transform' edit mode is returned, e.g.

cesdk.ui.getDockOrder();
// [
//   {
//     id: 'ly.img.assetLibrary.dock',
//     key: 'ly.img.template',
//     icon: '@imgly/Template',
//     label: 'libraries.ly.img.template.label',
//     entries: [ 'ly.img.template' ]
//   },
//   ...
// ]

Set a new Order

setDockOrder(
  dockOrder: (DockOrderComponentId | DockOrderComponent)[],
  orderContext: OrderContext = { editMode: 'Transform' }
)

When omitting the orderContext parameter, the order is set for the default edit mode ('Transform'), e.g.:

// Sets the order for transform mode by default
cesdk.ui.setDockOrder(['my.component.for.transform.mode']);

Dock Components

The following lists the default Dock components available within CE.SDK.

Layout Helpers

Component ID Description

ly.img.separator Adds a small space (invisible <hr> element) in the Dock to help the visual separation of entries.
Separators follow some special layouting rules:
- If 2 or more separators end up next to each other (e.g. due to other components not rendering), only 1 separator will be rendered.
- Separators that end up being the first or last element in the Dock will not be rendered.
- Separators directly adjacent to the top side of a spacer (see below) will not be rendered.

ly.img.spacer Adds vertical spacing in the Dock.
Spacers will try to fill all available whitespace, by distributing the available space between all spacers found in the Dock.

Component ID	Description
`ly.img.separator`	Adds a small space (invisible `<hr>` element) in the Dock to help the visual separation of entries. Separators follow some special layouting rules: - If 2 or more separators end up next to each other (e.g. due to other components not rendering), only 1 separator will be rendered. - Separators that end up being the first or last element in the Dock will not be rendered. - Separators directly adjacent to the top side of a spacer (see below) will not be rendered.
`ly.img.spacer`	Adds vertical spacing in the Dock. Spacers will try to fill all available whitespace, by distributing the available space between all spacers found in the Dock.

Asset Library

Component ID	Description
`ly.img.assetLibrary.dock`	Asset Library: A button that opens the Asset Library Panel, showing the content of one or more associated asset entries. Requires additional keys to be set on the object passed to `setDockOrder`, as described below.

Payload

Key	Type	Description
`key`	`string`	Needs to be unique within the set of components in the Dock.
`label`	`string`	Used as a label for the button. If a matching I18N key is found, the label is localized.
`icon`	`CustomIcon`	One of 3 things: -A URL string pointing to an SVG image, or: - The string identifier of a custom or built-in icon (see Icons), or: - A callback returning a URL, which takes a single parameter of type `{theme: string, iconSize: 'normal' \| 'large' }`.
`entries`	`string[]`	List of Asset Entries that will be shown in the Asset Library Panel when pressing the button. A single entry will open that entry directly. Multiple entries will show a group overview.

Example Usage

// Set the Dock Order to show only the Image Asset Library.
cesdk.ui.setDockOrder([
  {
    id: 'ly.img.assetLibrary.dock', // Component id
    // All other keys are payload / parameters passed to the component
    key: 'ly.img.image',
    icon: '@imgly/Image',
    label: 'libraries.ly.img.image.label', // Using a I18N key
    entries: [
      'ly.img.image', // Only 1 entry is to be shown
    ],
  },
]);

Default Order

[
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.template',
    icon: '@imgly/Template',
    label: 'libraries.ly.img.template.label',
    entries: ['ly.img.template'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.video.template',
    icon: '@imgly/Template',
    label: 'libraries.ly.img.video.template.label',
    entries: ['ly.img.video.template'],
  },
  {
    id: 'ly.img.separator',
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.elements',
    icon: '@imgly/Library',
    label: 'component.library.elements',
    entries: [
      'ly.img.upload',
      'ly.img.video',
      'ly.img.audio',
      'ly.img.image',
      'ly.img.text',
      'ly.img.vectorpath',
      'ly.img.sticker',
      'cutout-entry',
    ],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.upload',
    icon: '@imgly/Upload',
    label: 'libraries.ly.img.upload.label',
    entries: ['ly.img.upload'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.video',
    icon: '@imgly/Video',
    label: 'libraries.ly.img.video.label',
    entries: ['ly.img.video'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.audio',
    icon: '@imgly/Audio',
    label: 'libraries.ly.img.audio.label',
    entries: ['ly.img.audio'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.image',
    icon: '@imgly/Image',
    label: 'libraries.ly.img.image.label',
    entries: ['ly.img.image'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.text',
    icon: '@imgly/Text',
    label: 'libraries.ly.img.text.label',
    entries: ['ly.img.text'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.vectorpath',
    icon: '@imgly/Shapes',
    label: 'libraries.ly.img.vectorpath.label',
    entries: ['ly.img.vectorpath'],
  },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.sticker',
    icon: '@imgly/Sticker',
    label: 'libraries.ly.img.sticker.label',
    entries: ['ly.img.sticker'],
  },
];