Scopes

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine block API to modify a block's scopes. For a more high-level introduction, check the corresponding guide.

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.

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.

Functions#

JavaScript


findAllScopes(): string[]

Get all available global scopes that can be set.

Returns The names of all available global scopes.

JavaScript


setGlobalScope(key: string, value: 'Allow' | 'Deny' | 'Defer'): void

Set a scope to be globally allowed, denied, or deferred to the block-level.

key: The scope to set.
value: Allow will always allow the scope, Deny will always deny the scope, and Defer will defer to the block-level.

JavaScript


getGlobalScope(key: string): 'Allow' | 'Deny' | 'Defer'

Query the state of a global scope.

key: The scope to query.
Returns Allow if the scope is allowed, Deny if it is disallowed, and Defer if it is deferred to the block-level.

JavaScript


isScopeEnabled(id: DesignBlockId, key: string): boolean

Query whether a scope is enabled for a given block.

id: The block whose scope state should be queried.
key: The scope to query.
Returns the enabled state of the scope for the given block.

JavaScript


setScopeEnabled(id: DesignBlockId, key: string, enabled: boolean): void

Enable or disable a scope for a given block.

id: The block whose scope should be enabled or disabled.
key: The scope to enable or disable.
enabled: Whether the scope should be enabled or disabled.

JavaScript


isAllowedByScope(id: DesignBlockId, key: string): boolean

Check if a scope is allowed for a given block.

id: The block to check.
key: The scope to check.
Returns whether the scope is allowed for the given block.


/* Store a list of all available global scopes. */
let scopes = engine.editor.findAllScopes();

/* Let the global scope defer to the block-level. */
engine.editor.setGlobalScope('layer/move', 'Defer');

/* Manipulation of layout properties of any block will fail at this point. */
try {
  engine.block.setPositionX(image, 100); // Not allowed
} catch (err) {
  console.log(err.message);
}

/* This will return 'Defer'. */
engine.editor.getGlobalScope('layer/move');

/* Allow the user to control the layout properties of the image block. */
engine.block.setScopeEnabled(image, 'layer/move', true);

/* Manipulation of layout properties of any block is now allowed. */
try {
  engine.block.setPositionX(image, 100); // Allowed
} catch (err) {
  console.log(err.message);
}

/* Verify that the 'layer/move' scope is now enabled for the image block. */
engine.block.isScopeEnabled(image, 'layer/move');

/* This will return true as well since the global scope is set to 'Defer'. */
engine.block.isAllowedByScope(image, 'layer/move');