Instructions

The sections that follow describe the various procedures needed to extend the existing Crestron themes.

Creating Themes

To create a new theme, issue the npm run create-theme [THEME_NAME] shell command, where [THEME_NAME] is the theme name. The theme is created as an .scss file within the themes directory.

New themes are extended from the three existing themes provided by Crestron. The following options control the default theme that will be extended:

  • light: Extends the light theme.
  • dark: Extends the dark theme.
  • high-contrast: Extends the high-contrast theme.

For example, a new theme extended from the light theme would use the following command syntax:

Copy 
npm run create-theme my-theme light

Linking Themes

When creating a new theme, the following options can be appended to the command to control how the theme is linked to the default.

  • --soft-link: The import statement is being added in the generated file. This ensures that the latest version of the default theme is copied.
    • NOTE: If no option is appended to the command, soft linking is used by default.
  • --hard-link: The content of the default theme is copied to the generated file. The latest version of the default theme will not be copied automatically.

For example, a new theme extended from the light theme with hard linking would use the following command syntax:

Copy 
npm run create-theme my-theme light --hard-link

Customizing Themes

When a new theme is created, it contains only a link to the default base theme. The existing theme and variable SCSS files contain sample code that can be copied to the new theme and modified.

NOTE: Changes made to the existing theme and variable SCSS files affect all themes that use these CSS classes. Changes made to the custom theme SCSS file affect only that outpit.

Theme SCSS Files

To access the existing theme SCSS files, navigate to ch5-core > themes. The following image shows an example of the light.scss file.

Each of the three theme SCSS files (light, dark, and high-contrast) contain numerous CSS classes that are organized and divided by commented section. Each CSS class also contains a brief commented line that explain the class function.

To add a class to a new theme, simply copy and paste it from the theme SCSS file to the new theme SCSS file. Then, modify the value of the class as needed.

NOTE: Ensure that the copied classes are placed above the @import code section within the new theme SCSS file.

For example, if the $ch5-button-text-border-color class is copied, modify the default hex value to change the color of the button text border within a project.

Component Variable SCSS File

Each CH5 component has a varables.scss file that controls the styling of these components within the UI. The CSS classes from these variable SCSS files can also be copied into a new theme and modified.

Bundle the Theme

Various NPM shell scripts are provided that allow the custom theme to be bundled and viewed.

  • npm run bundle-theme-all: Bundles the default theme
  • npm run bundle-and-watch: Bundles the default theme with the watch option
  • npm run start: Runs the SCSS app to view theme changes
  • webpack --config webpack.run.js --outputpath=[RELATIVE_PATH_FOR_DESTINATION_DIRECTORY]: Bundles and copies themes to another directory with the webpack shell command.
    • The webpack shell command must be installed globally using npm install webpack - g prior to running this shell script.
    • Example syntax: webpack --config webpack.run.js --outputpath='../showcase-app/dist/crestron-components-assets'
  • npm run bundle-theme-all-app-run: Bundles and copy themes to another directory via .env file configuration as described below.
    • Create an .env file under the 'BlackbirdComponentLibrary/library/crestron-components-sass/' directory.
    • Add the properties and values below to the .env file:

      DESTINATION_THEMES_FILE_PATH = [RELATIVE_PATH_FOR_DESTINATION_DIRECTORY]

      • Example syntax: DESTINATION_THEMES_FILE_PATH = ['../showcase-app/dist/crestron-components-assets'
      • Update the --outputpath of the webpack shell command in package.json.

      Copy fonts and web fonts. Fonts, web fonts, and theme directories should be at the same level.

      • DESTINATION_WEBFONTS_FILE_PATH = [RELATIVE_PATH_FOR_WEBFONTS]
      • DESTINATION_FONTS_FILE_PATH = [RELATIVE_PATH_FOR_FONTS]