About this task
This procedure explains how to add a new theme part to a customization project. A theme part can set:
- theme variables
- resources
- conditions
Theme parts can be defined as global (for all customizations in a project) or local (within a specific customization).
TIP: To ease migration, it is recommended that you use local theme parts. Using local theme parts avoids the need to manage changes to the global theme parts directory during a migration.
Once defined, a theme part can be added to the themes defined for the customization.
Prerequisites
- You must understand how customization works. See Customization fundamentals.
- You have a project directory, which includes a theme folder at
gbc-project-dir/theme. This directory contains the collection of global theme parts. Each theme part is saved in its own directory. - You have a customization project, which includes a theme folder at
gbc-project-dir/customization/<customization_project_dir>/theme. This directory contains the collection of local theme parts. Each theme part is saved in its own directory.
Create a new theme part
Determine whether you are creating a local or global theme part. The decision will identify which directory you are working in:
gbc-project-dir/themesfor global theme parts.gbc-project-dir/customization/customization-project-dir/themesfor local theme parts.
TIP: To ease migration, it is recommended that you use local theme parts. Using local theme parts avoids the need to manage changes to the global theme parts directory during a migration.
A theme part is identified by the name of the folder.
Set up the folder structure
To start, create the root folder for the theme part. The content that you put in the root folder will depend on what you need to customize.
For example, Let us set up for a theme part that we will call "foo". We plan to store this theme part in a parent folder named "mythemeparts". We would navigate to gbc-project-dir/customization/customization-project-dir/theme/mythemeparts/ and create the directory foo.
Within this folder, we could add the following depending on our goals for the theme part:
| Directory or file | Description |
|---|---|
foo |
A theme part folder named "foo". |
foo/resources (folder) |
Theme resources, such as images and fonts. Any and all theme part resources can be stored here, to include html and JavaScript files (if necessary). Images should be included in the img subdirectory. |
foo/resources/img (folder) |
The img subdirectory containing images. |
foo/sass (folder) |
Cascading Style Sheet files for instructing the browser how to display specific widgets. You can change colors, font, how text is layed out, and so on. |
foo/sass/theme.scss (file) |
Entries here modify the stylesheet. While you can add css details directly into this file, a preferred method is to use the @import statement to import other stylesheets contained in the sass folder. For example, if you had a file named myHeader.scss in the theme's sass folder, you would include @import "myHeader" at the top of the theme.scss file. |
foo/theme.config.json (file) |
Details any conditions and identifies any custom widgets for the theme part. |
foo/theme.scss.json (file) |
Defines any theme variables for the theme part. |
To reiterate, we would not necessarily add all the folders and files for every theme part we create. If you examine the theme parts that come with the default installation, you will see that they only contain those files and folders that they need.
Add the theme parts to the themes
Once you define the theme part, you are ready to add it to one or more themes. See the topics Add a theme or Modify a theme.