How to Manage Scopes
CE.SDK allows you to control which parts of a block can be manipulated. Scopes describe different aspects of a block, e.g. layout or style and can be enabled or disabled for every single block. There's also the option to control a scope globally. When configuring a scope globally you can set an override to always allow or deny a certain type of manipulation for every block. Or you can configure the global scope to defer to the individual block scopes.
Initially, the block-level scopes are all disabled while at the global level all scopes are set to "Allow". This overrides the block-level and allows for any kind of manipulation.
If you want to implement a limited editing mode in your software you can set the desired scopes on the blocks you want the user to manipulate and then restrict the available actions by globally setting the scopes to "Defer". In the same way you can prevent any manipulation of properties covered by a scope by setting the respective global scope to "Deny".
Explore a full code sample on Stackblitz or view the code on Github.
Setup#
This example uses the headless CreativeEngine. See the Setup article for a detailed guide.
To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block.
Check out the APIs Overview to see that illustrated in more detail.
Available Scopes#
You can retrieve all available scopes by calling editor.findAllScopes().
We currently support the following scopes:
| Scope | Explanation |
|---|---|
Scope "layer/move" | Explanation Whether the block's position can be changed |
Scope "layer/resize" | Explanation Whether the block can be resized |
Scope "layer/rotate" | Explanation Whether the block's rotation can be changed |
Scope "layer/flip" | Explanation Whether the block can be flipped |
Scope "layer/crop" | Explanation Whether the block's content can be cropped |
Scope "layer/clipping" | Explanation Whether the block's clipping can be changed |
Scope "layer/opacity" | Explanation Whether the block's opacity can be changed |
Scope "layer/blendMode" | Explanation Whether the block's blend mode can be changed |
Scope "layer/visibility" | Explanation Whether the block's visibility can be changed |
Scope "appearance/adjustments" | Explanation Whether the block's adjustments can be changed |
Scope "appearance/filter" | Explanation Whether the block's filter can be changed |
Scope "appearance/effect" | Explanation Whether the block's effect can be changed |
Scope "appearance/blur" | Explanation Whether the block's blur can be changed |
Scope "appearance/shadow" | Explanation Whether the block's shadow can be changed |
Scope "lifecycle/destroy" | Explanation Whether the block can be deleted |
Scope "lifecycle/duplicate" | Explanation Whether the block can be duplicated |
Scope "editor/add" | Explanation Whether new blocks can be added |
Scope "editor/select" | Explanation Whether a block can be selected or not |
Scope "fill/change" | Explanation Whether the block's fill can be changed |
Scope "fill/changeType" | Explanation Whether the block's fill type can be changed |
Scope "stroke/change" | Explanation Whether the block's stroke can be changed |
Scope "shape/change" | Explanation Whether the block's shape can be changed |
Scope "text/edit" | Explanation Whether the block's text can be changed |
Scope "text/character" | Explanation Whether the block's text properties can be changed |
Managing Scopes#
First, we globally defer the 'layer/move' scope to the block-level using editor.setGlobalScope('layer/move', 'Defer'). Since all blocks default to having their scopes set to false initially, modifying the layout properties of any block will fail at this point.
| Value | Explanation |
|---|---|
Value "Allow" | Explanation Manipulation of properties covered by the scope is always allowed |
Value "Deny" | Explanation Manipulation of properties covered by the scope is always denied |
Value "Defer" | Explanation Permission is deferred to the scope of the individual blocks |
We can verify the current state of the global 'layer/move' scope using editor.getGlobalScope('layer/move').
Now we can allow the 'layer/move' scope for a single block by setting it to true using block.setScopeEnabled(block: number, key: string, enabled: boolean).
Again we can verify this change by calling block.isScopeEnabled(block: number, key: string): boolean.
Finally, block.isAllowedByScope(block: number, key: string): boolean will allow us to verify a block's final scope state by taking both the global state as well as block-level state into account.