Theme Builder

The Theme Builder is an extension of the Showcase Application that allows developers to build custom themes using existing CH5 theme files. The Theme Editor generates a CSS file that can be used by CH5 and Crestron Construct™ software and a JSON file that defines the properties of the theme (for future use).

NOTE: The Theme Builder should only be open in one browser and tab at a time.

The Theme Builder is accessed by selecting the art canvas button Art Canvas Button on the top right of the app.

Showcase App Home

The Theme Builder opens with sections for creating and uploading themes shown by default.

Theme Builder Home Page

Once the Theme Builder is open, select the pin button Pin Button to shrink the window to half size so it displays alongside the Showcase Application. Select the pin button again to return the window to full size. Additionally, select the x button X Button to close the Theme Builder and return to the Showcase Application.

A help button Help Button is also provided that, when selected, walks the user through various elements of the Theme Builder.

The following sections describe how to use the Theme Builder to create custom themes.

Create a New Theme

When Theme Builder is opened, a Create New Theme section is displayed by default. Additionally, select CREATE NEW THEME from the right toolbar of the Theme Builder project window to access this section.

Create New Theme Section

To create a new theme:

  1. Enter the theme name in the Theme Name dialog box.

    2. NOTE: The theme name must follow these validation rules. An error will be thrown if the theme name is not valid, and the theme cannot be created until the issues are resolved.

    • Must be between 3 and 20 characters
    • Must start with a letter
    • Can contain letters, numbers, and hyphens (but cannot end with a hyphen)
    • Cannot contain any other special characters
    • Cannot share the same name as a previously-created theme (though theme names are case-sensitive, allowing for lowercase and uppercase variations of the same name)
  2. Use the right drop-down menu to select the base theme for your custom theme (Light, Dark, High Contrast, Zoom Light, or Zoom Dark). The custom theme will be created using the default values from the selected base theme.
  3. Select Create Theme. A success message is displayed once the theme is created, and the project window is displayed for the theme.

    4. Theme Project Window (New Theme Created)

Once the theme is created, it will be selectable via the Theme drop-down menu on the top right of the window (along with all other preexisting CH5 themes).

Theme Drop-Down Menu

Up to three custom themes can be added per web browser and are selectable from the Theme drop-down menu. Themes are saved within the browser's local storage, so if the browser cache is deleted, all saved themes will also be deleted. Refer to Download a Theme for information on how to download a theme from the browser to your local computer.

NOTE: Themes are saved at the browser level and are unique to that browser. For example, a theme created in the Chrome® browser will not be accessible within the Firefox® browser.

Upload an Existing Theme

When Theme Builder is opened, an Upload Theme section is displayed by default. Additionally, select UPLOAD THEME from the right toolbar of the Theme Builder project window to access this section.

Upload Theme Section

To upload an existing theme to the Theme Builder:

  1. Select Choose File to browse your local computer for a theme to upload.

    2. NOTE: The selected theme CSS and JSON files must be compressed within a ZIP file and must not share the same name as a theme already saved within Theme Builder.

  2. After choosing the desired theme ZIP file, select Upload Theme. A success message is displayed once the theme is uploaded, and the project window is displayed for the theme.

    3. NOTE: If there are already three saved themes in the browser's local storage, the theme cannot be uploaded until an existing theme is deleted.

    Theme Project Window (Theme Uploaded)

After a new theme is created or uploaded, use the project window to modify the theme. The following navigational sections are provided:

  • A toolbar on the right of the window with app controls
  • A top filter bar that shows or hides grouped variable types and advanced functions
  • Expandable accordions for each variable type with a Filter function that allows only certain properties to be displayed based on the entered criterion

Theme Project Navigation

The right toolbar provides the following controls:

  • Select CREATE NEW THEME to create a new theme in the browser. Refer to Create a New Theme.
  • Select UPLOAD THEME to upload an existing theme to the browser. Refer to Upload an Existing Theme.
  • Select DELETE THEME to delete a theme from the browser. Refer to Delete a Theme.
  • Select DOWNLOAD THEME to download the theme files to your local computer. Refer to Download a Theme.
  • Select SAVE AS to save the current theme with a different name. Refer to Save a Theme
  • Select EXPAND ALL to expand all variable accordions.
  • Select COLLAPSE ALL to collapse all variable accordions.

NOTE: If there are any project errors, the number of errors will be displayed under the COLLAPSE ALL button.

The top filter bar provides the following controls:

  • Use the left toggle to show only basic theme variables (Basic) or all theme variables (Advanced) for the selected type(s).
  • Select the Colors, Numbers, Lists, or Units buttons to show only variables of the selected type. The respective button will be filled blue when selected and white when deselected.

    • NOTE: Press and hold the buttons to multiselect variable types.

  • Select All to show or hide all variables.

NOTE: Variables will be filtered based on all the filtering options selected. For example, Basic mode is selected, an Advanced mode color will not be shown even if the Color filter is selected.

The theme variable accordions are described in the following section.

Update Theme Variables

Use the theme variables accordions to enter custom values for the theme variables. Accordions can be expanded or collapsed individually using the plus (+) and minus (-) buttons respectively or as a group using the EXPAND ALL and COLLAPSE ALL controls in the right toolbar. The variables shown can be further controlled using the Filter text box at the top of the accordions and the filter controls at the top of the window.

NOTE: Selecting a variable in the Showcase Application will scroll automatically to its respective accordion when returning to the Theme Editor.

Theme Builder Variables

Each theme variable is categorized into primary and secondary types.

The following primary types are supported:

  • Color: Represents all variables of the type color, in which the variable input is a color (Hex, RGB, RGBA, color name) and can be selected from a color picker.
    • Example Variables: --theme-colors--danger-background, --theme-colors--danger-font-color
    • Example Values: #fff, #d8d8d8, RGB(120,133,145), red
  • Number: Represents all variables of the type number, in which the variable input is a number and can be entered manually.
    • Example Variables: --theme-ch5-button--line-height, --theme-ch5-button--pressed-line-height
    • Example Values: 1.2, 0
  • List: Represents all variables of the type list, in which the variable input can be selected from a drop-down menu.
    • Example Variables: --theme-ch5-button--secondary-border-style, --theme-ch5-button--x-large-font-weight
  • Unit: Represents all variables of the type unit, in which the variable input is a combination of a text input and drop-down field.
    • Example Variables: --theme-fonts--font-size, --theme-ch5-animation--size-large
    • Example Values: 4 px, 2 em, 10%

The following secondary types are supported:

  • String: Any string can be added to a variable. Doing so will convert the input field to a text box for free entry. The only validation rules will be applied:
    • For Color variables, the color value is validated. Any invalid values will default to black in the color picker.
    • For Number variables, the number value is validated to verify it is a valid number.
  • Variable: Represents all applicable CSS variable types of the four primary types. The input on these variables will be a var( variable_name), meaning that the variable can have the same value as another variable of the same type.
    • Example: --theme-colors--danger-background-color, --theme-colors--danger-font-color whose values can be var(--theme-colors--warning-background-color, var(--theme-colors--danger-border-color)

To set a secondary variable type, select the primary type link shown below the input field and then select the required type.

Color Variables

Select within the color text box to open a window with a color picker. Use the color picker to select the color, and use the sliders to change the color family and shade.

Color Variable Picker

If the secondary String type has been specified for the input, a valid color must be entered in the text box. An error is displayed if an invalid value is entered.

Color Variable (String)

If the secondary Variable type has been specified for the input, then an appropriate CSS variable name must be used to set the color. The variable name can be searched by entering a search term in the input box or copied into the text box.

Color Variable (Variable)

Number Variables

Use the up and down arrows on the right of the input box to increment or decrement the numeric value by 1 (support is browser dependent).

Number Variable

If the secondary String type has been specified for the input, a valid number must be entered in the text box. An error is displayed if an invalid value is entered.

Number Variable (String)

If the secondary Variable type has been specified for the input, then an appropriate CSS variable name must be used to set the number. The variable name can be searched by entering a search term in the input box or copied into the text box.

Number Variable (Variable)

List Variables

Use the drop-down menu to select a value from the available selections.

List Variable

If the secondary String type has been specified for the input, a custom value can be entered into the text box. No validation is performed on the input.

List Variable (String)

If the secondary Variable type has been specified for the input, then an appropriate CSS variable name must be used to set the list value. The variable name can be searched by entering a search term in the input box or copied into the text box.

List Variable (Variable)

Unit Variables

Use the text box and drop-down menu to enter a numeric value and a unit of measurement, respectively. An error is displayed if invalid text is entered.

Unit Variable

If the secondary String type has been specified for the input, a custom value can be entered into the text box. No validation is performed on the input.

Unit Variable (String)

If the secondary Variable type has been specified for the input, then an appropriate CSS variable name must be used to set the unit value. The variable name can be searched by entering a search term in the input box or copied into the text box.

Unit Variable (Variable)

Save a Theme

Themes created in the Theme Builder are saved automatically into the browser's local storage. Saved data will persist in the web browser even after the browser is closed or the computer is restarted.

However, a theme will not be saved automatically if there are errors with any theme variables, and the SAVE AS function will not be available. Errors are shown at the bottom of the right toolbar.

Theme Builder Error

To ensure the theme is saved, fix any variable errors. If the errors are not fixed and the web browser is closed, then only the last valid version of the theme will be saved.

CAUTION: If the browser's local storage is cleared, then the theme will be lost permanently.

The current theme can also be saved with a new name using the SAVE AS function.

NOTE: Once a theme is renamed using the SAVE AS function, its previous version with the older name is no longer available. If necessary, download the existing theme prior to renaming as described in Download a Theme.

To save a theme with a new name:

  1. Select SAVE AS from the right toolbar. A Save As tile is displayed.

    2. Save As Tile

  2. Enter the theme name in the New Theme Name dialog box.

    3. NOTE: The theme name must follow these validation rules. An error will be thrown if the theme name is not valid, and the theme cannot be created until the issues are resolved.

    • Must be between 3 and 20 characters
    • Must start with a letter
    • Can contain letters, numbers, and hyphens (but cannot end with a hyphen)
    • Cannot contain any other special characters
    • Cannot share the same name as a previously-created theme (though theme names are case-sensitive, allowing for lowercase and uppercase variations of the same name)
  3. Select Save. A success message is displayed once the theme is saved, and the project window is displayed for the theme.

    4. Theme Project Window (New Theme Created)

Once the theme is saved, it will be selectable via the Theme drop-down menu on the top right of the window (along with all other preexisting CH5 themes).

Theme Drop-Down Menu

Up to three custom themes can be added per web browser and are selectable from the Theme drop-down menu. Themes are saved within the browser's local storage, so if the browser cache is deleted, all saved themes will also be deleted. Refer to Download a Theme for information on how to download a theme from the browser to your local computer.

NOTE: Themes are saved at the browser level and are unique to that browser. For example, a theme created in the Chrome® browser will not be accessible within the Firefox® browser.

Download a Theme

To download a theme to your local computer:

  1. Select the theme to download from the Theme drop-down menu.
  2. Select DOWNLOAD THEME from the right toolbar.

The theme is downloaded to your local computer as a ZIP file containing the theme CSS and JSON files.

NOTES:

  • If the theme has any errors, only the most recently saved changes of valid variables will be downloaded.
  • Do not make any manual changes to the generated ZIP file (such as changing the folder content). Doing so may cause the theme to not function properly.

Delete a Theme

To delete a theme from the web browser:

  1. Select the theme to delete from the Theme drop-down menu.
  2. Select DELETE THEME from the right toolbar. A confirmation dialog is displayed.
  3. Select OK. The theme is deleted from the web browser.