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 defaultcesdk.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 componentcesdk.ui.updateCanvasBarOrderComponent( 'ly.img.settings.canvasBar', 'my-custom-settings-component', 'bottom');
// Replace the add page button with a custom page management componentcesdk.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 documentscesdk.ui.removeCanvasBarOrderComponent( 'ly.img.page.add.canvasBar', 'bottom');
// Remove all settings controls for basic userscesdk.ui.removeCanvasBarOrderComponent( (component) => component.id.includes('settings'), 'top');
// Remove specific components by IDcesdk.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 buttoncesdk.ui.insertCanvasBarOrderComponent( 'ly.img.settings.canvasBar', 'my-custom-action-component', 'bottom');
// Add a separator before the add page button for better organizationcesdk.ui.insertCanvasBarOrderComponent( 'ly.img.page.add.canvasBar', 'ly.img.separator', 'bottom', 'before');
// Replace the default settings button with a custom onecesdk.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. |
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',];