Advanced UI Customization¶

The user interface of the WSO2 API-M Developer Portal and Publisher Portal can be customized simply without editing the React codebase or the CSS in most cases. You will be required to modify the React codebase only if you need to do advanced customizations.

Adding advanced UI customizations to WSO2 API-M UIs¶

Follow the instructions below to add advanced UI customizations to the Developer Portal and/or Publisher. Instructions for the admin portal are slightly different from the steps mentioning below. Please refer to Admin Portal advanced UI customizations for more details.

Publisher and Developer Portal advanced UI customizations¶

Prerequisites

NodeJS - This is a platform required for ReactJS development. The compatible version is 16.x.
NPM

Navigate to the <API-M_HOME>/repository/deployment/server/webapps directory in a terminal and run the following command.
```
npm install
```
This will install the dependencies for the lerna package manager.
Run the following command from the same directory in a terminal.
```
npm run bootstrap
```
This will install the local package dependencies in the Publisher and Developer Portal applications.
Run the command given below in the relevant application.

If it is a Developer Portal, run npm run build:dev from the devportal folder or else run the command from the publisher folder), to start the npm build. Note that it will continuously watch for any changes and rebuild the project.

For example to customize the Developer Portal:
1. Navigate to the <API-M_HOME>/repository/deployment/server/webapps/devportal/src/main/webapp directory.
2. Run the following command.
  Production deployment
  
  The development build is not optimized and contains a large bundle size. Make sure to use the production build when the customizations are ready for production. Use the following command to get the production-ready build.
```
npm run build:prod
```
Make the UI related changes in the respective folder based on the WSO2 API-M Console.
- If you need to rewrite the UI completely, you can make changes in the following directory.
  - Developer Portal - devportal/src/main/webapp/source
  - Publisher Portal - publisher/src/main/webapp/source
- If you want to override a specific React component or a file from the source/src/ directory, you need to make the changes in the following directory by only copying the desired file/files.
  - Developer Portal - devportal/src/main/webapp/override/src
  - Publisher Portal - publisher/src/main/webapp/override/src

Overriding the API Documentation and Overview components¶

Any file inside <APP-ROOT>/src/main/webapp/override/src folder can override the original file at <APP-ROOT>/src/main/webapp/source/src folder. The name of the file and location relative to the source folder has to be identical. This concept applies to publisher and admin web-apps as well. For example, [1] is taking precedence over [2] when the npm build is running.

[1] - devportal/src/main/webapp/override/src/app/components/Apis/Details/Documents/Overview.jsx
[2] - devportal/src/main/webapp/source/src/app/components/Apis/Details/Documents/Overview.jsx

An example for the <APP-ROOT>/src/main/webapp/override/src folder is shown below.

override
└── src
    ├── Readme.txt
    └── app
        └── components
            └── Apis
                └── Details
                    ├── Documents
                    │   └── Documentation.jsx
                    └── Overview.jsx

Adding new files to the override folder¶

You can add your own files to customize the UI in the admin/src/main/webapp/override/src folder.

For example, you can import the NewFile.jsx by adding the AppOverride prefix to the import and provide the full path relative to the override folder.

import NewFile from 'AppOverride/src/app/components/Apis/Details/NewFile.jsx';

After importing the NewFile.jsx the folder structure will be as follows:

override
└── src
    ├── Readme.txt
    └── app
        └── components
            └── Apis
                └── Details
                    ├── Documents
                    │   └── Documentation.jsx
                    └── Overview.jsx
                    └── NewFile.jsx

A bundler error will show up if you try to import the NewFile.jsx from Overview.jsx as follows.

import NewFile from './NewFile.jsx';

Admin Portal advanced UI customizations¶

Prerequisites

NodeJS - This is a JavaScript runtime environment required for ReactJS development.
NPM

Navigate to the <API-M_HOME>/repository/deployment/server/webapps/admin/src/main/webapp/ directory in a terminal and run the following command.
```
npm ci
```
This will install the local package dependencies in the Admin applications.
Build with customizations

Run the following command to start the npm build. Note that it will continuously watch for any changes and rebuild the project.
```
npm run build:dev
```
Production deployment

The development build is not optimized and contains a large bundle size. Make sure to use the production build when the customizations are ready for production. Use the following command to get the production-ready build.
```
npm run build:prod
```
1. Make the UI related changes in the respective folder based on the WSO2 API-M Console.
2. If you need to rewrite the admin UI completely, you can make changes in the following directory.
  - admin/src/main/webapp/source
3. If you want to override a specific React component or a file from the source/src/ directory, you need to make the changes in the following directory by only copying the desired file/files.
  - admin/src/main/webapp/override/src

Overriding the API Documentation and Overview components¶

Any file inside <APP-ROOT>/src/main/webapp/override/src folder can override the original file at <APP-ROOT>/src/main/webapp/source/src folder. The name of the file and location relative to the source folder has to be identical. This concept applies to publisher and admin web-apps as well. For example, [1] is taking precedence over [2] when the npm build is running.

[1] - devportal/src/main/webapp/override/src/app/components/Apis/Details/Documents/Overview.jsx
[2] - devportal/src/main/webapp/source/src/app/components/Apis/Details/Documents/Overview.jsx

An example for the <APP-ROOT>/src/main/webapp/override/src folder is shown below.

override
└── src
    ├── Readme.txt
    └── app
        └── components
            └── Apis
                └── Details
                    ├── Documents
                    │   └── Documentation.jsx
                    └── Overview.jsx

Adding new files to the override folder¶

You can add your own files to customize the UI in the admin/src/main/webapp/override/src folder.

For example, you can import the NewFile.jsx by adding the AppOverride prefix to the import and provide the full path relative to the override folder.

import NewFile from 'AppOverride/src/app/components/Apis/Details/NewFile.jsx';

After importing the NewFile.jsx the folder structure will be as follows:

override
└── src
    ├── Readme.txt
    └── app
        └── components
            └── Apis
                └── Details
                    ├── Documents
                    │   └── Documentation.jsx
                    └── Overview.jsx
                    └── NewFile.jsx

A bundler error occurs if you try to import the NewFile.jsx from Overview.jsx as follows.

import NewFile from './NewFile.jsx';

Development¶

During an active development, the watch mode works with the overridden files. Adding new files and directories will not trigger a new webpack build.

Production Build¶

Make sure you do a production build after you finish development with the command given below. The output of the production build contains minified javascript files optimized for web browsers.

npm run build:prod