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/jaggeryapps
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 thedevportal
folder or else run the command from thepublisher
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:
-
Navigate to the
<API-M_HOME>/repository/deployment/server/jaggeryapps/devportal
directory. -
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/source
- Publisher Portal -
publisher/source
- Developer Portal -
- 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/override/src
- Publisher Portal -
publisher/override/src
- Developer Portal -
- If you need to rewrite the UI completely, you can make changes in the following directory.
Overriding the API Documentation and Overview components¶
Any file inside <APP-ROOT>/override/src
folder can override the original file at <APP-ROOT>/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/override/src/app/components/Apis/Details/Documents/Overview.jsx
- [2] - devportal/source/src/app/components/Apis/Details/Documents/Overview.jsx
An example for the <APP-ROOT>/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/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/jaggeryapps/admin
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
-
Make the UI related changes in the respective folder based on the WSO2 API-M Console.
-
If you need to rewrite the admin UI completely, you can make changes in the following directory.
admin/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.admin/override/src
-
Overriding the API Documentation and Overview components¶
Any file inside <APP-ROOT>/override/src
folder can override the original file at <APP-ROOT>/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/override/src/app/components/Apis/Details/Documents/Overview.jsx
- [2] - devportal/source/src/app/components/Apis/Details/Documents/Overview.jsx
An example for the <APP-ROOT>/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/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
Top