Creating a sub-theme

Create a custom theme for your Developer Portal site by generating and configuring a sub-theme. A sub-theme is a theme that inherits all the resources of a specified parent theme. You can then override specific resources to configure your required customizations.

About this task

Directly editing the API Connect theme isn’t permitted or supported, as edited versions of these files are overwritten when a fix pack or iFix is installed. So, the way to create a custom theme is to create a custom sub-theme of the standard API Connect theme that the Developer Portal uses by default. You can also create a sub-theme that is based on one of the following color templates:

Business Mono
Sapphire Blue
Emerald Green
Golden Brown
Ruby Red

Selecting a color template provides you with a base theme that you can build on more easily to produce your required site branding and styling.

Create a sub-theme by using the theme generator in the Developer Portal UI, customize the appearance as required, and then upload the compressed file back onto the site.

Important:

• You’re not permitted to include any IBM® API Connect code within any custom themes that you create. Also, directly editing any API Connect themes on the file system is not permitted or supported, as edited versions of these files are overwritten when a fix pack or iFix is installed.
• All custom development is your responsibility. Although the use of custom themes is supported, IBM API Connect do not provide support in their development or modification.

For a guided example on creating a sub-theme, see Tutorial: Creating a custom theme for the Developer Portal. In this example, you create a sub-theme, and then customize the styling by editing the overrides.css file.

1. On the administrator dashboard, click Appearance > Generate sub-theme.
   The Generate sub-theme page is displayed.
2. Enter a Sub-theme name, and select the Sub-theme type that you would like to use. The name can contain only lowercase characters a - z, and numerals 1 - 9.
   • CSS - Cascading Style Sheets; the language that is used to describe how to display the HTML elements in the theme.
   • SCSS - Sass CSS; a superset of CSS. SCSS contains all the features of CSS, but is extended to include the features of Sass as well. However, SCSS must be compiled into CSS before it can be installed and used in the Developer Portal.
3. Select the template to base your sub-theme on:
   • Default - the standard connect_theme that the Developer Portal is based on.
   • Business Mono - a black and white color theme.
   • Sapphire Blue - a blue color theme.
   • Emerald Green - a green color theme.
   • Golden Brown - a brown color theme.
   • Ruby Red - a red color theme.
4. Click Generate.
   Your sub-theme is available to download from the Generate sub-theme page.
5. Click your new sub-theme and save it to your preferred location.
6. Extract the resources from the sub-theme file, and then edit the specific resources to configure the customizations that you require.
   Define your theme by creating metadata in the your_theme_name.info.yml file. You can then customize the appearance of your theme by configuring the overrides.css file. For detailed information about how to customize themes, see Theming Drupal.
7. After you have completed your customizations, compress the sub-theme resources back into the .zip file.
   Note that the following file extensions are also supported: tar, tgz, gz, and bz2.
8. Install your new sub-theme onto the Developer Portal by clicking Appearance > Install new theme.
9. Click Choose file, select your sub-theme, and then click Install.
10. Click Install newly added theme, find your new theme in the list of Uninstalled themes, and click Install and set as default to set your new custom sub-theme as the default theme for your site.
    Your new theme is now set as the default theme, and is listed in the Installed themes section.