How to customize the User Portal in WSO2 Identity Server 5.10.0
WSO2 Identity Server 5.10.0 is now available for everyone to use. And with that marked the introduction of the much-anticipated User Portal which is the successor to the dashboard. It was written from scratch and all the front-end portals are now intended to use a centralized theming mechanism paving the way for easy customization.
Click here to read more about the new features in 5.10.0.
Inspiration
I’m a night owl 🦉 hence the first thing I look for in a platform is the dark mode. Recently, Facebook rolled out its new redesigned portal with a dark mode and I immediately switched to it and has been loving the soothing color scheme and design. So, I thought of using that as a reference for this demo.
Checklist
In this post, I’ll try to cover the following steps in customizing the User Portal.
✅ Change the default theme to dark mode.
✅ Change the branding (Logo and Product title, Favicons, Copyright, etc.)
✅ Deploy the changes in the web app.
Pre-requisites
Okay, first things first, let’s check out the corresponding identity apps source code from the repo and set it up in the development environment. Follow this blog for instructions on setting up the dev environment and instead of checking out the master branch, you can check out the v1.0.72 tag since v1.0.72 of identity-apps was used in IS 5.10.0.
I’m working on my own fork of identity-apps and first I’m going to fetch all the tags and check out the v1.0.72 tag to a new branch.
$ git fetch --all --tags --prune$ git checkout tags/v1.0.72 -b feature-dark-theme-demo
Change the default theme to dark mode
A customized version of the default theme[1] in the Semantic UI LESS package has been used to achieve the look and feel of the User Portal which is packed with 5.10.0 distribution.
If you navigate to modules/theme/src/themes folder, you would see the default theme overrides. Check the Semantic UI documentation if you wish to learn more about Semantic UI theming [2].
All the theme global variable overrides can be found in modules/theme/src/themes/default/globals/site.variables file and for the full set of variables, refer the original theme variables file[3].
Let’s dive in and override the variables in site.variables.
- First I’m going to change the primary color of the portal from orange(#FF5000) to Facebook’s primary color which is a shade of blue(#2D88FF).
Add a new color under the site colors and let’s call it facebookBlue 😇.
/*-------------------
Site Colors
--------------------*/@facebookBlue : #2d88ff;
Now change the primary color variable.
/*-------------------
Brand Colors
--------------------*/@primaryColor : @facebookBlue;
2. Next, we can change the page background color from white to dark gray and change the default text color to a lighter shade.
Add a new variable under the brand colors and let’s call it globalBackgroundColor.
/*-------------------
Brand Colors
--------------------*/
@globalBackgroundColor: #18191a;Override the @pageBackground variable.
/*-------------------
Page
--------------------*/@pageBackground : @globalBackgroundColor;
@textColor : #e4e6eb;
You can now build the theme module by running the following command and check the results reflected on the dev server.
# from inside modules/theme$ npm run build
You will see something like the following. Quite frankly it looks like an uncooked pop tart but don’t worry, we can fix it 😁.
As you can see, we have to change the backgrounds of the header, footer, side navigation, and content cards.
3. Change the header & footer background.
Add a new variable under the brand colors and let’s call it globalForegroundColor.
In modules/theme/src/themes/default/collections/menu.variables
@background: @globalForegroundColor;4. The side panel background in Facebook UI is the same as the page background. The reusable variable that we created in step 2 will come in handy in this scenario.
In modules/theme/src/themes/default/collections/menu.overrides
.ui.vertical.menu {
&.side-panel {
background: @globalBackgroundColor;
// Other styles
}
}5. Modify the content card background color.
In modules/theme/src/themes/default/views/card.variables
@background: @globalForegroundColor;Now let’s do a status check to see the progress of our work by rebuilding the theme module. The changes should be reflected on the running dev server in no time.
You can clearly see that we are getting somewhere. But there are obvious issues such as the harsh borders around the cards and also the side navigation styles look a bit weird. Since we understand the procedure, now we can play around with the styles and get the desired effect with some trial and error.
Change the branding
Now that we are done with the styling, let’s change the product branding.
- Change the product logo.
Method 1 (Recommended)
If you wish to change the logo without touching the compiled javascript bundle, you can do the following to override the existing WSO2 logo with CSS.
I added an owl icon I downloaded from Flaticon.com(Credits should go to Freepik[4]) to the modules/theme/src/themes/default/assets/images folder.
In modules/theme/src/definitions/globals/product.less replace the existing styles in .product-logo class with the following.
.product-title {
.product-logo {
width: 25px;
height: 25px;
vertical-align: text-top;
margin-right: 5px;
background: url(assets/images/owl.svg) no-repeat;
background-size: auto;
svg {
display: none;
}
}
// Other styles
}Method 2
Add the downloaded icon to the modules/theme/src/themes/default/assets/images folder.
In modules/theme/src/index.js replace Logo with the path to the new icon.
export const Logo = require("../lib/assets/images/owl.svg");Build user-portal artifacts.
npx lerna run build — scope @wso2is/user-portalReplace main.js & main.js.map inside the user-portal web app with the same from apps/user-portal/build/user-portal.
2. Change the product title & Copyright.
In the IS pack, the User Portal web app is available on the following path.
<IS_HOME>/repository/deployment/server/webapps/user-portalIn index.jsp add the following two entries in the runConfig window object.
window["runConfig"] = {
...
applicationName: "NIGHT OWL EXPRESS",
copyrightText: "Night Owl Express © 2020"
};3. Change the Favicon and Title.
Replace favicon.ico at the root of the user-portal web app with the desired icon. You can use an online generator like favicon.io to generate a favicon for free.
To change the title, in index.jsp file of the web app, change the <title> tag.
<title>Night Owl Express</title>Deploy the changes in the web app
We are at the final step of the process which is the deployment. Follow the sequence of steps listed below to deploy the changes performed in the previous steps.
- Build the theme module.
# from inside modules/theme$ npm run build
2. Copy the artifacts to the web app.
The built artifacts will be available inside the lib folder. Copy everything to the clipboard and navigate to the user-portal web app in the IS pack.
As mentioned above, the user-portal web app is available in the following location.
<IS_HOME>/repository/deployment/server/webapps/user-portalReplace the contents inside /libs/styles/css with the copied artifacts.
NOTE: Make sure that you keep a backup of the original CSS folder.
This diff depicts the approach I took in order to achieve the following outcome.
The final compiled theme bundle can be found here.
Feel free to try this out and if you have any suggestions regarding the blog you can log an issue in this repo and also if you have any issues or suggestions regarding the user portal, please consider logging them here.
[1] https://github.com/Semantic-Org/Semantic-UI-LESS/tree/master/themes/default
[2] https://semantic-ui.com/usage/theming.html
[3] https://github.com/Semantic-Org/Semantic-UI-LESS/blob/master/themes/default/globals/site.variables
[4] Icons made by Freepik www.flaticon.com
Signing off… ✌️❤️
