Adding a New API Store Theme

A theme consists of UI elements such as logos, images, copyrights messages, landing page text, background colors etc. WSO2 API Store comes with a default theme. You can extend the existing theme by writing a new one or customising the existing one.

Folder structure of the API Store themes

The default theme of the API Store is named wso2. You find it inside the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/wso2 folder. If you do not have access to the file system, download the default theme from here. 

The easiest way to create a new theme is to copy the files of an existing theme to a folder that is named after your new theme, and do the modifications you want to the files inside it. All themes have the same folder structure as shown below:

You can add a new theme as a main theme or a sub-theme.

• A main theme is saved inside the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/themes directory
• A sub theme is saved inside the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/<main-theme-directory>/subtheme directory. 
  

As a sub-theme is saved inside a main theme, it needs to contain only the files that are different from the main theme. Any file that you add inside the sub-theme overrides the corresponding files in the main theme. The rest of the files are inherited from the main theme. 

Let's see how to create a new theme and set it to the API Store: 

Writing a sub theme of the main theme

As a main theme already has most of the UIs, the syntax, and logic of Jaggery code defined, in a typical scenario, you do not have to implement a theme from scratch. Rather, you just add in your edits as a sub-theme of the existing main theme as given below: 

1. Download the default main theme from here, unzip it, and rename the folder according to the name of your new theme (e.g., ancient). Let's refer to this folder as <THEME_HOME>.
   The downloaded file contains the same files and folders that are available in the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/wso2 directory. 

2. Add your changes to your sub-theme.

   For example, make the following changes in the CSS styles in the <THEME_HOME>/css/custom.css file using a text editor and save.

   1. Add the following code to change the color of the header to red.

      header.header-default{
      	background:red !important;
      }

   2. Update the color given for the search box to #0be2e2.

      .search-wrap>.form-control, .search-wrap .btn.wrap-input-right  {
          background-color: #0be2e2;
          border: 0px;
          color: #FFF;
          height: 40px;
          margin-top:-3px;
      }

   The custom.css file related to the sub-theme should always have the entire set of CSS styles. Therefore, do not delete the code related to the CSS styles that you have not changed in the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/<main-theme-directory>/subtheme/<sub-theme>/css/custom.css file.

3. As you plan to upload the theme as a sub-theme of the default main theme, delete all the files and folders in your <THEME_HOME> folder with the exception of the ones that you edited, because the rest of the files are automatically applied from the main theme.

Setting the new theme as the default theme

The following are the two methods in which you can set your new theme as the default theme:

• Saving directly in the file system

• Uploading through the Admin Portal (Tenants Only)

Saving directly in the file system

If you have access to the file system, do the following:

1. Save the <THEME_HOME> folder that contains the sub-theme of the main theme inside the <APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/wso2/subthemes folder. This makes your new theme a sub-theme of the main wso2 theme.

2. Open the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json file, and add the following code to it. It specifies the base theme as wso2, which is overridden by the sub-theme ancient.

   "theme" : {
           "base" : "wso2",
           "subtheme" : "ancient"
   }

3. Open the API Store.
   Note the new theme that is applied to it.
    

Uploading through the Admin Portal (Tenants Only)

If you do not have access to the file system, you can upload the theme through the Admin Portal as shown below: 

1. Navigate inside the <THEME_HOME> folder that contains the sub-theme of the main theme, select all the folders inside it, and right-click to compress all the selected files and folders. Then rename the ZIP file based on the name of your sub-theme. For this example use the ancient.zip file.

2. Sign in to the WSO2 Admin Portal (https://<server-host>:9443/admin) with your tenant username (format <username>@<domain>.com kim@testorg.com) and password.
3. Expand the Settings menu, click Upload Tenant Theme and upload your ZIP file.
   
4. Access the API Store ( https://<server-host>:9443/store) using your tenant username and password.
   Note the new theme that is applied.