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.57.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 6 APIs for getting, setting, updating, removing, and inserting 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 all 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']);

Update Components#

updateDockOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<DockOrderComponentId>>,
  update: DockOrderComponentId | Partial<OrderComponent<DockOrderComponentId>> | ((component: OrderComponent<DockOrderComponentId>) => Partial<OrderComponent<DockOrderComponentId>>),
  orderContext?: OrderContext
)

Updates existing components in the dock. The matcher can be:

A component ID string
A partial object describing the component to match
A function that receives the component and index, returning true if it matches

The update can be:

A new component ID string
A partial object with updated properties
A function that receives the current component and returns the updated one

Returns an object with the number of updated components and the updated order array.

// Change the icon and label for the image library
cesdk.ui.updateDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.image' },
  (component) => ({
    ...component,
    icon: '@imgly/Photo',
    label: 'My Photos',
    entries: ['ly.img.image', 'ly.img.custom.photos']
  })
);

// Update the upload library label for different user contexts
cesdk.ui.updateDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.upload' },
  { label: 'Upload Files' }
);

// Update the entries for the elements library to show only specific categories
cesdk.ui.updateDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.elements' },
  { entries: ['ly.img.image', 'ly.img.text', 'ly.img.vectorpath'] }
);

Remove Components#

removeDockOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<DockOrderComponentId>>,
  orderContext?: OrderContext
)

Removes components from the dock. The matcher can be:

A component ID string
A partial object describing the component to match
A function that receives the component and index, returning true if it matches

Returns an object with the number of removed components and the updated order array.

// Remove the video library for mobile users
cesdk.ui.removeDockOrderComponent(
  (component) => component.id === 'ly.img.assetLibrary.dock' && component.key === 'ly.img.video'
);

// Remove all template libraries for users without template access
cesdk.ui.removeDockOrderComponent(
  (component) => component.id === 'ly.img.assetLibrary.dock' && component.key && component.key.includes('template')
);

// Remove the audio library by key
cesdk.ui.removeDockOrderComponent({ id: 'ly.img.assetLibrary.dock', key: 'ly.img.audio' });

Insert Components#

insertDockOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<DockOrderComponentId>>,
  component: DockOrderComponentId | OrderComponent<DockOrderComponentId>,
  location?: InsertOrderComponentLocation,
  orderContext?: OrderContext
)

Inserts new components into the dock. The matcher can be:

A component ID string
A partial object describing the component to match
A function that receives the component and index, returning true if it matches

The location can be:

'before' - Insert before the matched component
'after' - Insert after the matched component (default)
'replace' - Replace the matched component
'asChild' - Insert as a child of the matched component

Note: The 'asChild' option is only supported for custom components that you register via registerComponent. Built-in dock components like ly.img.assetLibrary.dock do not support yet take advantage of this pattern.

Returns the updated dock order array.

// Add a custom asset library after the image library
cesdk.ui.insertDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.image' },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.custom',
    icon: 'custom-icon',
    label: 'Custom Assets',
    entries: ['ly.img.custom', 'ly.img.brand']
  }
);

// Add a separator before the upload library for better organization
cesdk.ui.insertDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.upload' },
  'ly.img.separator',
  'before'
);

// Replace the elements library with a simplified version
cesdk.ui.insertDockOrderComponent(
  { id: 'ly.img.assetLibrary.dock', key: 'ly.img.elements' },
  {
    id: 'ly.img.assetLibrary.dock',
    key: 'ly.img.elements.simple',
    icon: '@imgly/Library',
    label: 'Basic Elements',
    entries: ['ly.img.image', 'ly.img.text']
  },
  'replace'
);

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'],
  },
];