Overriding Developer Portal Theme

WSO2 provides the developers with an easier approach to customize the UI. You do not need to have React, CSS, or HTML knowledge to customize the UI. We have a single JSON file which holds the parameterized constraints of the look and feel. For example, you can change the font family via the JSON file so that the changes appear throughout the Developer Portal. When updating the Developer Portal theme, you can update not only the look and feel but also behaviors such as making the listing view default instead of grid view, hiding social features, etc.

Devportal

You can find default theme from the following location <API-M_HOME>/repository/deployment/server/jaggeryapps/devportal/source/src/defaultTheme.js.

The defaultTheme.js file has all the parameters defining the look and feel of the Developer Portal.

You can override the parameters defined in the above file from <API-M_HOME>/repository/deployment/server/jaggeryapps/devportal/site/public/theme/defaultTheme.js. Changes done in this file are reflected directly in the Developer Portal ( It's not required to restart the server or rebuild the source code).

Note

API Manager Devportal is themed using React Material Design. The theme configuration is an external JSON file resides outside the React codebase. While an administrator who has access to the file system can override the default theme configuration, a tenant admin can override both of them via the defaultTheme.json file. You can refer to <APIM_HOME>/repository/deployment/server/jaggeryapps/devportal/source/src/defaultTheme.js for available parameters. Note that you need to only put the parameters that you override to your file. The parameters you can override via the theme are listed at the bottom. Additionally, the default theme params available with React Material Design library can be overridden via this file.

Ex: Enable landing page. defaultTheme.js.

const Configurations = {
    custom: {
        landingPage: {
            active: true,
        },
    },
};
Ex: Enable landing page. defaultTheme.json ( Teant theming ).

{
  "custom": {
    "landingPage": {
      "active": true
    }
  }
}

Tenant Theming

Uploading Devportal theme via the Admin Portal (Tenants Only)

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

  1. Download the sample theme here sample-theme.zip.
  2. The sample-theme.zip file contains the following folder structure.

    You can make the changes required to defaultTheme.json file and archive it back. The name of the archive does not matter, but the name of the JSON file (defaultTheme.json) does. Uses of resources in login folder will be discussed in Applying thems for tenant login pages section.

    └──apim
    │    └──css
    │    │    └── custom.css
    │    ├── defaultTheme.json
    │    └── images
    │          └── custom-logo.png
    └──analytics
    │     └── images
    │          └── custom-logo.png
    │          └── favicon.ico
    └──login
         └──css
         │    └── custom.css
         ├── loginTheme.json
         └── images
               └── custom-logo.png
               └── favicon.ico
  3. Sign in to the WSO2 Admin Portal (https://<server-host>:<server-port>/admin) with your tenant username (format: <username>@<domain>.com) and password.

  4. Click Tenant Theme under Settings category and click Browse File to Upload to upload your ZIP file. Alternatively, you can drag and drop your ZIP file to upload.

    Upload tenant theme

  5. Access the API Developer Portal (https://<server-host>:<server-port>/devportal) using your tenant username and password.

    Note the new theme is applied.

Note

From API-M 3.1.0 onwards, defaultTheme.json can contain only the custom modifications done to the default theme. Therefore the following are valid defaultTheme.json files.

    Ex1:
    {
      direction: 'rtl'
    }

    Ex2: 
    {
        custom: {
                defaultApiView: 'list',
        }
    }

The default theme configuration can be found at <APIM_HOME>/repository/deployment/server/jaggeryapps/devportal/source/src/defaultTheme.js. In the shared defaultTheme.json we have overriden the custom.appBar configurations only.

{
    "custom": {
        "appBar": {
            "logo": "/site/public/tenant_themes/<tenant-domain>/apim/images/custom-logo.svg",
            "logoHeight": 31,
            "logoWidth": 144,
            "background": "#1d344f",
                "activeBackground": "#254061"
        }
    }
}

Adding custom logo for the tenant

In your tenant theme, you can refer to an image from the defaultTheme.json file as follows. The examples below uses the custom-logo.png image from the sample-theme.zip. The image can be referred using one of the following URL patterns.

The path format to the custom-logo.png image within the tenant domain theme is as follows:

"logo": "/site/public/tenant_themes/<tenant-domain>/apim/images/custom-logo.png",
The path to the custom-logo.png image within the kim@testorg.com tenant domain theme is as follows:

"logo": "/site/public/tenant_themes/kim@testorg.com/apim/images/custom-logo.png",

The following defines the logo image from an external URL.

"logo": "https://dummyimage.com/208x19/66aad1/ffffff&text=testlogo",

Applying CSS rules to change the look and feel

If you prefer to change the styling using CSS rules, you can use the custom.css file. The above sample theme also has a custom CSS file. In the CSS file, let's change the top header background color to black.

Note that we have injected IDs into the dom elements. You can use them to apply CSS rules. However, be aware about the dynamically generated CSS class names. These class names have a number suffix which changes from version to version. Therefore, it is recommended not to use them for styling purposes.

The CSS file is referenced in the defaultTheme.json in the following manner. It is not a must to replace the <tenant-domain> in the following line, as at runtime the Developer Portal will automatically replace it with the current tenant domain.

   "tenantCustomCss": "/site/public/tenant_themes/<tenant-domain>/apim/css/custom.css",

Content of defaultTheme.json

The following is the Devportal app theme object merging with the React Material Design default theme object described here.

Applying themes for tenant login pages

  1. Configure a custom URL for tenant.

  2. Login to tenant's carbon console and add following property to /_system/config/apimgt/applicationdata/tenant-conf.json file.

"EnablePerTenantServiceProviderCreation" : "true" 
3. login folder in the tenant theme contains the config files and resources to define login theme customizations.
└──login
└──css
│    └── custom.css
├── loginTheme.json
└── images
     └── custom-logo.png
     └── favicon.ico
4. Apply changes to login/loginTheme.json file. A sample file would look like below.
{
  "title" : "WSO2 API Manager",
  "header" : {
    "title" : "API Manager"     
  },
  "footer" : {
    "name" : "WSO2 API Manager"
  },  
  "favicon" : {
    "src" : "favicon.ico"
  },
  //"logo" : {
    //"src" : "custom-logo.png",
    //"alt" : "logo",
    //"height" : "60",
    //"width" : "60"
  //},
  "cookie-policy" : {
    "visible" : true,
    "text" : "<custom cookie policy text>"
  },
  "privacy-policy" : {
    "visible" : true,
    "text" : "<custom privacy policy text>"
  }
}

Note

Please note that it is not allowed to define both a header.title and a logo for the login customizations. You can only define either a header.title or a logo.

  1. Copy the image files into login/images folder and mention the file names against favicon and logo src fileds. In case you need to change the look and feel of login pages you can add a custom css file to login/css folder. Make sure to name the file as custom.css.
  2. Zip this file along with other resources in the tenant theme and upload via admin portal. Or you can make changes manually if you have access to the server's file system.

Publisher

The default theme is located in the <API-M_HOME>/repository/deployment/server/jaggeryapps/publisher/site/public/theme/ directory.

The defaultTheme.js file has all the parameters defining the look and feel of the Publisher app.

Make sure to take a backup of the defaultTheme.js before making any changes.

Changes done in the defaultTheme.js file are reflected directly in the Publisher app ( It's not required to restart the server or rebuild the source code).

Note

It's required to keep the complete configuration in the site/public/theme/defaultTheme.js for publisher app.

Content of defaultTheme.js

The following is the Publisher app theme object merging with the React Material Design default theme object described here.

Top