About this task

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

Prerequisites

• You must understand how customization works. See Customization fundamentals.
• You have the theme parts that you plan to use to build the theme. These theme parts may be local to the customization, or global to the project.

Access the config.json file for the customization

Adding a theme simply requires making additions to the config.json file located in the customization-project-dir directory. If the file exists, open gbc-project-dir/customization/customization-project-dir/config.json with a text editor. If the file does not exist, copy the config.json file from the sample customization project into your new customization project.

NOTE: If you copy the config.json file from the sample project, be sure to review the predefined themes to ensure they work for your customization!

Add a simple theme

Once created, you add each new theme 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 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 will be used.

Add a theme with multiple theme parts

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/mythemeparts/common`
• *customization-project-dir*/theme/mythemeparts/colors/dark`

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

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

In this example, three theme parts were specified for a new "dark" theme. The 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 mythemeparts/commontheme part, yet set to black in the mythemeparts/colors/darktheme part. The mythemeparts/colors/darktheme part is listed after the mythemeparts/commontheme part, therefore the theme variable theme-primary-color would be set to black.

Rebuild using gbc build.

When you have finished your modifications, save your changes and rebuild your customization:

$ gbc build --customization <customization_project_dir>

Test

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.