Creating Custom Theme Modules via the Contribution folder in IBM WebSphere Portal v8.5
WPS v7.0.0.2 first introduced the concept of a modular theme. As the product has matured, the modular themes concept has been extended and enhanced greatly to accommodate a variety of use cases.
In this post we’ll show you the simple use case and create our own custom module to include some JavaScript and CSS files in three steps:
- Write and add the new custom module to the theme’s profile
- Build and deploy the theme to your server
- Review and validate the changes made to the theme on the server
For the purposes of this blog entry, we are going to be using a theme with static content not stored in WebDAV. While there are two ways to introduce a custom theme module to the portal theme, there is no difference between the two other than the file locations. The route we’ll take today is through the contributions folder inside the static project.
First, create a new JavaScript file inside the js directory in the static project. The js folder is found in the /themes/html/mycustom-85-theme directory of the static project, or in WebDAV it is in fs-type1/themes/mycustom-85-theme/js.
Let’s call this JavaScript file “mycustomjs.js” for this exercise. Inside the file, paste the following code:
if (console){
console.log(“Hello there good lookin!”);
}
alert(“Hello there good lookin! Doing some debugging, eh?”);
Next, create a second new JavaScript file and call it “mycustomjs.min.js” and paste the following code:
if (console){console.log(“Hello there good lookin!”);}
Next, create a new CSS file inside the css directory in the static project. Let’s call the CSS file “mycustomcss.css” for our project. Inside that file, paste the following css code:
body{
background-color: red !important;
}
Create a second CSS file and call it “mycustomcss.min.css” and paste the following code:
body{background-color:black !important;}
Now that we have our minified and unminified JavaScript and CSS files created, it’s time to add them to a custom module!
Go to your contributions folder and create a text file with a .json extension inside of your static project. The contributions folder can be found in the /themes/html/mycustom-85-theme directory of the static project, or in the fs-type1/themes/mycustom-85-theme/contributions folder in WebDAV. Paste the following JSON into the file:
{
“modules”:[{
“id”:”my_custom_theme_module”,
“contributions”:[{
“type”:”head”,
“sub-contributions”:[{
“type”:”css”,
“uris”:[{
“value”:”css/mycustomcss.min.css”
},{
“value”:”css/mycustomcss.css”,
“type”:”debug”
}]
},{
“type”:”js”,
“uris”:[{
“value”:”js/mycustomjs.min.js”
},{
“value”:”js/mycustomjs.js”,
“type”:”debug”
}]
}]
}]
}]
}
The JS file we created would be considered a non-framework JavaScript file. In accordance with best practices, this file will be included in a config module instead of the head module. This is defined in the “type” attribute of the contributions section of the module definition– the two valid values for the “type” attribute are “head” and “config”. As you add more files, they would be organized into various modules. HCL goes into greater detail on how to format JSON files.
Now it’s time to add our newly created custom module to the theme’s profile. If you are already using a custom profile, then simply add “my_custom_theme_module” to the list of non-deferred modules. Deferred modules are in the “Deferred” section of the profile (see profile_deferred.json for an example of this). If you are using the default theme’s profile (likely profile_deferred.json if you haven’t been creating custom profiles and your theme is based on the OOTB WPS v8.5 theme), open its profile definition file and add “my_custom_theme_module” to the list of non-deferred modules.
Build & Deploy
Now it’s time to deploy our custom module and updated profile. If your server was not placed in developer mode or your resource aggregator cache settings are still set to the default settings, you will need to restart the server after you deploy your theme (or after you upload to WebDAV). Deploy your custom theme EAR file via the WAS admin console in the deployment manager if clustered, or the WAS admin console of your standalone server. After you have deployed your theme, restart the portal server (or cluster).
Review & Validate
Once the server is back up, navigate to the portal page which uses your custom theme. You should see the JavaScript message in your browser’s console as well as the page having a red background color. If this isn’t the case, be sure you have modified the appropriate profile and check any messages in the WPS logs. Correct, deploy, and restart the server to test again.
In this blog, we’ve discussed how to add a custom theme module using both the contributions json file. This wasn’t intended to be a comprehensive example but just a quick example to show you the possibilities with custom theme modules. If you would like to know more information, or have questions around the contents of this blog, please leave a comment and let us know!
