Controlling the UI with the Feature API
Enable Feature#
The following API allows to enable a custom or built-in feature (see the list of built-in features below):
enable(featureId: FeatureId, predicate: FeaturePredicate)
The predicate
is either a boolean that forces the features to be enabled or not,
or a function that takes a context and returns a boolean value. (The type FeaturePredicate
is boolean | ((context: EnableFeatureContext) => boolean)
, where EnableFeatureContext
is {engine: CreativeEngine, isPreviousEnable: () => boolean}
.)
Providing a function has the added benefit of receiving the return value of any previous predicates. This is useful for overwriting the default behavior under specific circumstances, or for chaining more complex predicates.
Example: Chaining Predicates#
// Enable the feature by defaultcesdk.feature.enable('my.feature', true);// Disable the feature after 10 pmcesdk.feature.enable('my.feature',({isPreviousEnable}) =>(new Date().getHours() >= 22 ? false : isPreviousEnable()));
Tip: FeatureId
can be an arbitrary string, so you can use this mechanism to toggle your own custom features, as well.
Example: Overwriting Defaults#
Let's say you introduced a new kind of block that represents an Avatar. Regardless of scopes or the current mode of the editor, you want to hide the duplicate & delete button in the canvas menu for this kind of block. You can achieve this by adding new predicates to change the default feature behavior:
cesdk.feature.enable('ly.img.delete',({engine, isPreviousEnable}) => {const selectedBlock = engine.block.findAllSelected()[0];const kind = engine.block.getKind( selectedBlock );if (kind === 'avatar') {return false;} else {return isPreviousEnable();}});cesdk.feature.enable('ly.img.duplicate',({engine, isPreviousEnable}) => {const selectedBlock = engine.block.findAllSelected()[0];const kind = engine.block.getKind( selectedBlock );if (kind === 'avatar') {return false;} else {return isPreviousEnable();}});
Check Feature#
The following API allows to query if the feature is currently enabled:
isEnabled(featureId: FeatureId, context: FeatureContext)
The type FeatureContext
is {engine: CreativeEngine}
, meaning that you will need to supply the active engine instance when checking a feature, for Example:
if (!cesdk.feature.isEnabled('ly.img.navigate.close', { engine })) {return null;}
Built-In Features#
The following features are built-in to CE.SDK:
Feature ID | Description |
---|---|
Feature ID ly.img.navigate.back | Description Controls visibility of the "Back" button in the Navigation Bar.Defaults to the value of the configuration option ui.elements.navigation.action.back , or true if not set. |
Feature ID ly.img.navigate.close | Description Controls visibility of the "Close" button in the Navigation Bar.Defaults to the value of the configuration option ui.elements.navigation.action.close , or true if not set. |
Feature ID ly.img.delete | Description Controls the ability to delete a block. Changes visibility of the "Delete" button in the Canvas Menu, as well as the ability to delete by pressing the delete key. Will return false when the operation would delete all pages of the document. Will return false when target block is a page and configuration option ui.elements.blocks['//ly.img.ubq/page'].manage is false , or during 'Video' scene mode. |
Feature ID ly.img.duplicate | Description Controls visibility of the "Duplicate" button in the Canvas Menu. Does currently not influence the ability to copy/paste using keyboard shortcuts. Will return false when target block is a page and configuration option ui.elements.blocks['//ly.img.ubq/page'].manage is false , or during 'Video' scene mode. |
Feature ID ly.img.placeholder | Description Controls visibility of the "Placeholder" button in the Canvas Menu. Will return true for blocks of type '//ly.img.ubq/text' , '//ly.img.ubq/group' , '//ly.img.ubq/page' , '//ly.img.ubq/audio' , or '//ly.img.ubq/graphic' . |
Feature ID ly.img.preview | Description Controls existence of the "Preview" button in the Navigation Bar. Returns true when cesdk.engine.editor.getRole() returns Creator , e.g. when editing in the Creator role. |
Feature ID ly.img.page.move | Description Controls the ability to move pages, by showing the "Move Up/Down/Left/Right" buttons in the Canvas Menu. Returns false during 'Video' scene mode, or when scene layout is set to 'Free' or 'DepthStack' . Note that the "Move Up/Left" components will not show up when the target page is already the first page of the document, and "Move Down/Right" will not show up when the target page is already the last page of the document. |
Feature ID ly.img.group | Description Controls features for creating and dissolving groups, currently: The existence of "Group" and "Ungroup" buttons in the Inspector Bar. Returns false during 'Video' scene mode. |
Feature ID ly.img.replace | Description Controls presence of the "Replace" button in the Canvas Menu, and in the Fill Panel for image and video fills. Returns false by default for stickers. |
Feature ID ly.img.text.edit | Description Controls presence of the "Edit" button in the Canvas Menu. Only returns true for text blocks by default. |
Feature ID ly.img.text.typeface | Description Controls presence of the Typeface dropdown, and can disable the corresponding dropdown in the Advanced UI Inspector Panel. Only returns true for text blocks by default. |
Feature ID ly.img.text.fontSize | Description Controls presence of the Font Size input, and can disable the corresponding input in the Advanced UI Inspector Panel. Only returns true for text blocks by default. |
Feature ID ly.img.text.fontStyle | Description Controls presence of the Font Style controls (Bold toggle, Italic toggle), in the Canvas Menu, and can disable the corresponding inputs in the Advanced UI Inspector Panel. Only returns true for text blocks by default. |
Feature ID ly.img.text.alignment | Description Controls presence of the Text Horizontal Alignment dropdown, and can disable the corresponding controls in the Advanced UI Inspector Panel. Only returns true for text blocks by default. |
Feature ID ly.img.text.advanced | Description Controls the presence of the Advanced text controls in the Editor. Only returns true for text blocks by default. |
Feature ID ly.img.adjustment | Description Controls visibility of the "Adjustments" button, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.filter | Description Controls visibility of the "Filter" button, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.effect | Description Controls visibility of the "Effect" button, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.blur | Description Controls visibility of the "Blur" button, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.shadow | Description Controls visibility of the Shadow button, and can disable the corresponding control in the Advanced UI Inspector Panel. Returns false for pages by default. |
Feature ID ly.img.cutout | Description Controls visibility of the Cutout controls (Cutout Type, Cutout Offset, Cutout Smoothing), and can disable the corresponding controls in the Advanced UI Inspector Panel. Only returns true for cutouts by default. |
Feature ID ly.img.fill | Description Controls presence of the Fill button (opening the Fill Panel), and can disable the corresponding button in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.shape.options | Description Controls presence of the Shape Options dropdown in the Default UI Inspector Bar, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns true by default, but note that the component itself checks for the target block type and will only render for shape blocks. |
Feature ID ly.img.combine | Description Controls presence of the Combine dropdown, and can disable the corresponding button in the Advanced UI Inspector Panel. Returns true by default, but note that the component itself checks for the target block type and will only render if the selection contains only shape blocks and text, or only cutouts. |
Feature ID ly.img.trim | Description Controls presence of the Trim button, and can disable the corresponding button in the Fill Panel. Only returns true when scene mode is 'Video' . |
Feature ID ly.img.crop | Description Controls presence of the Trim button, and can disable the corresponding button in the Fill Panel. Returns false for stickers by default. |
Feature ID ly.img.volume | Description Controls presence of the Volume control, and can disable the corresponding button in the Fill Panel. Only returns true when scene mode is 'Video' . |
Feature ID ly.img.stroke | Description Controls presence of the Stroke controls (Color, Width, Stroke), and can disable the corresponding controls in the Advanced UI Inspector Panel. Returns false for stickers by default. |
Feature ID ly.img.position | Description Controls presence of the Position dropdown, and can disable the corresponding controls in the Advanced UI Inspector Panel. Returns false if target block is a page. |
Feature ID ly.img.options | Description Controls presence of the Options button (... button) in the Default UI Inspector Bar. Returns true by default. |
Feature ID ly.img.animations | Description Controls presence of the Animations button. Returns true by default for Graphic and Text blocks in video mode. |