UI Editor/Templates

Templates are a feature of .ui files that allow for a piece of UI to be used as a definition for future pieces of UI, either those created by other UI files or those instantiated by script.

Local Templates

A local template is the most common type of template. It allows scripts to repeatedly create a hierarchy of components by calling CreateComponentFromTemplate() on any container. A common use for this is for displaying a set of similar items which are not known to the script creator beforehand: browsing a store, checking your inventory, etc.

Global Templates

A global template provides a common template that can be used among several packages to establish a shared look. The most obvious example of this is the CoreUI package which establishes templates for all types of components and windows. A common template functions like a local template, but exists within the shared namespace so other packages can reference it (and will replace other global templates with the same name).

CoreUI

By convention, the first script package delivered by the Service Provider to a client is the CoreUI package. The CoreUI package serves the important role of establishing Global Templates for future packages to use, thereby creating a common "theme" or appearance when connected to a given system.

Workflow

Creating a Template

To create a local template named "MyTemplate", follow these steps:

1. Create one or more components in your script package with one of them as the root of the others
2. Configure them with the Inspector to how you expect them to appear when in use
3. Rename the root component of the template in the Inspector to the name you want it for the template ("MyTemplate")
4. Right-click the root component and select "Template > Create Local"
5. (Optional) Delete the existing item from the hierarchy

The template can then be recreated at any time by right-clicking in the Hierarchy and choosing "Create > Templates > MyTemplate"

Updating a Template

To make changes to the above example "MyTemplate", follow these steps:

1. Right-click in the Hierarchy and choose "Create > Templates > MyTemplate"
2. Use the Inspector and Hierarchy to make any changes you want to that template or its children
3. Right-click the root node of the template in the Hierarchy ("MyTemplate") and select "Template > Update Local"
4. (Optional) Delete the existing item from the hierarchy

Deleting a Template

1. Expand the Template hierarchy in the Definition Panel to find the template you are looking for
2. Select the template you want to delete
3. Click the "Delete" button that appears

Template Ordering

When a new component is created, a set of templates is constructed and applied, resolving conflicts in favor of the "closest" template, followed by the style specific to this instance if it's being instantiated in a .ui file hierarchy. For a "button" component with Template "MyButton" and a Style "MyButtonInstance", the order is as follows:

1. Base properties of the button prefab
2. Global 'button' template (usually from CoreUI)
3. Local 'button' template (if any)
4. Global 'MyButton' template (if any)
5. Local 'MyButton' template
6. Style 'MyButtonInstance' from the matching .styles file

Likewise, when a template or style is updated, only the set of changes relative to its parents are saved, allowing both for smaller files and for updates made to higher up templates to cascade down to instantiated children.