Canvas Bar - Vanilla JS

Rearrange Components#

There are 6 APIs for getting, setting, updating, removing, and inserting components in the Canvas Bar.

The Canvas Bar can appear in 2 positions: At the top of the canvas, and at the bottom of the canvas. The APIs can get and set the content for both of these positions independently.

The content of the Canvas Bar 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 similar APIs, see also Moving Existing Buttons or Adding New Buttons in the Guides section.

Get the Current Order#

getCanvasBarOrder(
  position: 'top' | 'bottom',
  orderContext: OrderContext = {
    editMode: 'Transform'
  }
)

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

cesdk.ui.getCanvasBarOrder('bottom');
// => [
// {id: 'ly.img.settings.canvasBar'},
// {id: 'ly.img.spacer'},
// ...
// ]

Set a new Order#

setCanvasBarOrder(
  canvasBarOrder: (CanvasBarComponentId | OrderComponent)[],
  position: 'top' | 'bottom',
  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.setCanvasBarOrder('bottom', ['my.component.for.transform.mode']);

Update Components#

updateCanvasBarOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<CanvasBarComponentId>>,
  update: CanvasBarComponentId | Partial<OrderComponent<CanvasBarComponentId>> | ((component: OrderComponent<CanvasBarComponentId>) => Partial<OrderComponent<CanvasBarComponentId>>),
  position: 'top' | 'bottom',
  orderContext?: OrderContext
)

Updates existing components in the canvas bar. 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.

// Replace the settings button with a custom settings component
cesdk.ui.updateCanvasBarOrderComponent(
  'ly.img.settings.canvasBar',
  'my-custom-settings-component',
  'bottom'
);

// Replace the add page button with a custom page management component
cesdk.ui.updateCanvasBarOrderComponent(
  (component) => component.id === 'ly.img.page.add.canvasBar',
  'my-custom-page-component',
  'top'
);

Remove Components#

removeCanvasBarOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<CanvasBarComponentId>>,
  position: 'top' | 'bottom',
  orderContext?: OrderContext
)

Removes components from the canvas bar. 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 add page button for single-page documents
cesdk.ui.removeCanvasBarOrderComponent(
  'ly.img.page.add.canvasBar',
  'bottom'
);

// Remove all settings controls for basic users
cesdk.ui.removeCanvasBarOrderComponent(
  (component) => component.id.includes('settings'),
  'top'
);

// Remove specific components by ID
cesdk.ui.removeCanvasBarOrderComponent(
  { id: 'ly.img.settings.canvasBar' },
  'bottom'
);

Insert Components#

insertCanvasBarOrderComponent(
  matcher: OrderComponentMatcher<OrderComponent<CanvasBarComponentId>>,
  component: CanvasBarComponentId | OrderComponent<CanvasBarComponentId>,
  position: 'top' | 'bottom',
  location?: InsertOrderComponentLocation,
  orderContext?: OrderContext
)

Inserts new components into the canvas bar. 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

Returns the updated canvas bar order array.

// Add a custom action after the settings button
cesdk.ui.insertCanvasBarOrderComponent(
  'ly.img.settings.canvasBar',
  'my-custom-action-component',
  'bottom'
);

// Add a separator before the add page button for better organization
cesdk.ui.insertCanvasBarOrderComponent(
  'ly.img.page.add.canvasBar',
  'ly.img.separator',
  'bottom',
  'before'
);

// Replace the default settings button with a custom one
cesdk.ui.insertCanvasBarOrderComponent(
  'ly.img.settings.canvasBar',
  'my-custom-settings-component',
  'top',
  'replace'
);

Canvas Bar Components#

The following lists the default Canvas Bar components available within CE.SDK.

Layout Helpers#

Component ID Description

ly.img.separator Adds a vertical separator (<hr> element) in the Canvas Bar.
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 Canvas Bar will not be rendered.
- Separators directly adjacent to the left side of a spacer (see below) will not be rendered.

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

Component ID	Description
`ly.img.separator`	Adds a vertical separator (`<hr>` element) in the Canvas Bar. 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 Canvas Bar will not be rendered. - Separators directly adjacent to the left side of a spacer (see below) will not be rendered.
`ly.img.spacer`	Adds horizontal spacing in the Canvas Bar. Spacers will try to fill all available whitespace, by distributing the available space between all spacers found in the Canvas Bar.

Common Controls#

Component ID	Description
`ly.img.settings.canvasBar`	Customize Editor button: Opens the Settings Panel when pressed.
`ly.img.page.add.canvasBar`	Add Page button: Adds a new page to the end of the document when pressed.

Default Order#

The default order of the Canvas Bar is the following:

[
  'ly.img.settings.canvasBar',
  'ly.img.spacer',
  'ly.img.page.add.canvasBar',
  'ly.img.spacer',
];