Add a theme

This procedure explains how to add a new theme to a customization project.

1. Open the gbc-project-dir/customization/customization-project-dir/config.json file.
   If this file does not exist, copy the config.json file from the sample customization project into your new customization project. Be sure to review the predefined themes to ensure they work for your customization!
2. To add a simple theme, add the details within curly braces.

   For example, to create a default theme for the desktop and a default theme for mobile devices, you would add the following, using two of the global theme parts that are provided by the GBC project package.

   {
     "themes": [{
         "name": "default",
         "title": "Default",
         "uses": ["platform/desktop"]
       },
       {
         "name": "default_mobile",
         "title": "Default",
         "uses": ["platform/mobile"]
       }
     ]
   }

   You can see that each theme consists of three entries:

   • name is an identifier for the theme. It must match the regular expression /^[a-z0-9_][a-z0-9_-]*$/i. This identifier must be unique.
   • title is the text the user will see as the theme identifier.
   • uses is an array of theme parts. In this simple example, each theme only has one theme part.

   Things to note:

   • The theme part is identified by the path to the theme from within the theme folder. For example, "platform/desktop" indicates that you go into the theme folder, search for the platform directory, then within the directory search for the desktop directory.
   • The local theme part directory (customization-project-dir/theme) is searched first. If the path is not found in the local theme part directory, the global theme part directory (gbc-project-dir/theme) is searched next.

   Note:

   If a local and a global theme part have the same path/name, the local theme part is used.

3. While the above themes are valid, they are simple in that they only have one theme part. Most themes will be comprised of multiple theme parts.

   For example, let's assume you have created two new theme parts:

   • customization-project-dir/theme/common
   • customization-project-dir/theme/colors/dark

   To add a new theme to your customization that utilizes these new theme parts when on a desktop device, add a new entry to your config.json file:

   {
     "themes": [{
         "name": "default",
         "title": "Default",
         "uses": ["platform/desktop"]
       },
       {
         "name": "dark",
         "title": "Dark",
         "uses": ["platform/desktop", "common", "colors/dark"]
       },
       {
         "name": "default_mobile",
         "title": "Default",
         "uses": ["platform/mobile"]
       }
     ]
   }

   In this example, a new "dark" theme is added. This new theme is the combination of these three theme parts.

   Things to note:

   • The theme parts may contain conflicting information. For example, they could each contain a setting for the same theme variable. In this situation, the last theme part listed where the variable was defined determines its value.
     In our example, assume

     • the theme variable theme-primary-color is set to yellow in the common theme part
     • the theme variable theme-primary-color is set to black in the colors/dark theme part
     The colors/dark theme part is listed after the common theme part; therefore, the theme variable theme-primary-color would be set to black.

     For more information about theme variables, see Theme variables reference.

   • A theme or a theme part can declare conditions. At build time, these conditions are combined; the produced theme must fit all conditions possible in the execution context. In other words, the combined theme conditions set by the theme parts must not conflict.

     For example, consider a theme definition that selects its theme parts with the following clause:

     "uses": ["platform/browser", "common", "platform/ur"]

     In this example, the condition set by the "platform/browser" theme part, "isBrowser", restricts the theme to a browser only, while the condition set by the "platform/ur" theme part, "isUR", restricts the theme to a Genero front-end using Universal Rendering only. These two theme conditions are mutually exclusive and therefore can never be met. The theme will never be used.

     For more information about theme conditions, see Theme conditions.

4. Save your changes and rebuild your customization using gbc build:

   $ gbc build --customization customization-project-dir

5. Test the new theme is available by closing and reopening your application.
   Tip:

   You may need to use CTRL + F5 to clear the browser cache before you see your changes.