Aliases
Aliases are a Coherent Prysm Exporter only feature that helps in the creation of components. They are templates used in UI menus that are resolved when the document is published.
Export time aliases
Creating aliases
Aliases are created through the Global aliases menu in the Document tab.
Symbol aliases are created through the Aliases menu in the Properties tab.
Aliases resolution
When a document is published, the aliases are resolved from the scene of the document down to its elements. The UI menu options are then evaluated with the resolved aliases. Aliases in children deeper down the scene override global aliases and aliases further up the document. Symbol aliases are visible to all of its children.
For a document that contains the following chain of symbols. Scene -> Symbol 1 -> Symbol 2 where Symbol 2 is a child of Symbol 1 and Symbol 1 is a child of the Scene.
And the following aliases.
| Global alias name | Global alias value | Symbol 1 alias name | Symbol 1 alias value | Symbol 2 alias name | Symbol 2 alias value |
|---|---|---|---|---|---|
| clrProp | globalClrProp | clrProp | symbol1ClrProp | sizeProp | symbol2ClrProp |
| sizeProp | globalSizeProp | - | - | nameProp | symbol2NameProp |
| nameProp | globalNameProp | - | - | - | - |
The resolved aliases in the symbols are the following.
| Scene alias name | Scene alias value | Symbol 1 alias name | Symbol 1 alias value | Symbol 2 alias name | Symbol 2 alias value |
|---|---|---|---|---|---|
| clrProp | globalClrProp | clrProp | symbol1ClrProp | clrProp | symbol1ClrProp |
| sizeProp | globalSizeProp | sizeProp | globalSizeProp | sizeProp | symbol2ClrProp |
| nameProp | globalNameProp | nameProp | globalNameProp | nameProp | symbol2NameProp |
Using aliases
Resolved aliases are used in expressions through the #(aliasName) syntax. When an #(aliasName) is found in an expression it is replaced with the value of the alias for the symbol that contains the expression.
Aliases can be used in the following places.
| Menu that accepts aliases |
|---|
| "Localization id" in the "Symbol/Instance Properties" tab |
| "Export user images/Image source" in the "Symbol/Instance Properties" tab |
| "Extra CSS classes" in the "Symbol/Instance Properties" tab |
| "Extra CSS classes" in the "Symbol/Instance Children properties" tab |
| "Custom attributes" in the "Symbol/Instance Properties" tab |
| "Custom attributes" in the "Symbol/Instance Children properties" tab |
| "Data binding attributes" in the "Symbol/Instance Bindings" tab |
| "Children custom attributes" in the "Symbol/Instance Properties" tab |
| "Event type: custom/Event name" in the "Symbol/Instance Events" tab |
| "Engine trigger/Event name" in the "Symbol/Instance Events" tab |
| "Engine call/Function" in the "Symbol/Instance Events" tab |
| "Event type: custom-bound/Event name" in the "Symbol/Instance Bindings/Data binding events" tab |
| "Handler type/Value" in the "Symbol/Instance Bindings/Data binding events" tab |
| "Engine trigger/Event name" in the "Symbol/Instance Bindings/Data binding events" tab |
| "Engine call/Function" in the "Symbol/Instance Bindings/Data binding events" tab |
Aliases are resolved in the custom event name, Engine trigger and Engine call menus of the Events tab.
Aliases are resolved in the value of custom data-binding event handlers and in the custom event name, Engine trigger and Engine call menus.
The following tables describe how expressions are evaluated for specific aliases.
| Alias name | Alias value |
|---|---|
| model | hudModel |
| clrProp | hudColor |
| Expression | Result |
|---|---|
| #(model).#(clrProp) | hudModel.hudColor |
| #(model).#(sizeProp) | hudModel.#(sizeProp) |
Runtime aliases and components
Components are loaded at runtime and we want them to be customizable. Hence, component aliases are also resolved at runtime and you can use aliases that don't exist while creating components e.g. you can set the value of a data-bind-value attribute to {{#(ALIAS)}} while ALIAS is not defined in the document that generates the component. This makes it possible to create components with placeholders and define their values in the screens that use the components.
When a component is loaded it adds all aliases defined in symbols that are part of the component to a runtime collection. All aliases defined in symbols on the screen are also added to the collection. As data-prysm-id's assigned to elements are unique, all elements can get their aliases at runtime.
The algorithm for the resolution of aliases starts from an element, gets all of its aliases, and then gets all aliases that are not present in the collection from its entire parent chain. This means that aliases defined in nested movie clips overwrite those of parents exactly like in the export time resolution.
The Prysm Exporter generates code that resolves runtime aliases automatically when used in all of the menus mentioned in the Export time section. Aside from that, we defined a function prysm.getRuntimeAliasValue that you can use to resolve an alias value through JavaScript. You can use that in events, timeline scripts, and standalone JavaScript files.
The function accepts an element and resolves aliases starting from it and going up the parent chain e.g.
// The structure of the DOM is the following
//
// Movie Clip root
// Movie Clip parent
// Movie Clip element with instance name = someInstanceName
//
// The root element defines the ALIAS with the value ALIAS_VALUE
const element = document.querySelector(".someInstanceName");
// The following line will print "ALIAS_VALUE" to the console
console.log(prysm.getRuntimeAliasValue("ALIAS", element));
Note: Aliases are resolved at export time when used in an expression in a component AND are defined in the file that generates the component.