Our Blog > Blog Detail

Web Content Viewer- Asponte Custom Skin


Creating Custom Theme Modules for IBM WebSphere Portal v8.5

  • Created By: wpsadmin
  • Updated: May 27, 2015

WPS v7.0.0.2 first introduced the concept of a modular theme. As the product has matured through its version, the modular themes concept has been extended and enhanced greatly to accommodate a variety of use cases. Today, we'll cover two simple use cases where we create our own custom modules to include some JavaScript and CSS files, as well as a java servlet to retrieve some data and return it to the resource aggregator. For the purposes of this blog entry, we are going to be using a theme who's static content is not stored in WebDAV, however there is no difference between the two other than the file locations. There are two ways to introduce a custom theme module to the portal theme. The first avenue is via the contributions folder inside the static project.
First, create a new JavaScript file inside the js directory in the static project. The js folder can be found in the /themes/html/mycustom-85-theme directory of the static project, or in WebDAV it will be in fs-type1/themes/mycustom-85-theme/js. Let's call the JavaScript file "mycustomjs.js" for our purposes. 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 another 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. Lets call the CSS file "mycustomcss.css" for our purposes. Inside the file, paste the following css code:

         background-color: red !important;

Create another 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, its time to add them to a custom module. Create a text file with a .json extension inside the contributions folder 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:


It is a best practice to include non-framework JavaScript files, like the ones we've created here, in a config module instead of a 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". These correspond to the "co:head" and "co:config" tags found in the theme.html file (or theme_XX.html if you are supporting multiple languages). Ideally, the files we're adding should be separated into multiple modules. However, we are not doing that for the purposes of this exercise. Consider that an "on your own" exercise after you have become a certified custom module developer of which we'll award you after completing this exercise.
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.
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).
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. If you become tired of restarting the server, there are two things you can do to help alleviate the server restart downtime.
1.    Turn on Developer Mode
TODO: describe turning on dev mode in REE
2.    Add max-age header to resources in Default.jsp
Open Default.jsp in your dynamic theme project and add the following code in side the tag:
This will automatically append a "max-age" header with a value of 2 seconds to all resources, helping with the caching on the server.
After verifying everything works as expected, now let's turn on remote debugging. Turning on remote debugging makes the resource aggregator no longer bundle all files into as few requests as possible. It decouples all the files and loads them in the theme one at a time and the files who's sub-contributions are type "debug" (like our uncompressed files).
To turn on remote debugging, login to the portal server and go to the logging and tracing page inside the administration area. Enter the following trace string into the text box and hit the plus icon to add it.
After adding the trace string, revist the page that has the custom theme module on it and you should get a javascript alert message in addition to the console message. The background color should also now be black.
So far, we've shown you how to create a custom theme module using the contributions json file. Now, let's add a custom theme module that calls a custom servlet to return some custom CSS. While we're going to keep this example super simple, the objective here is to realize that once you can get portal to call a custom servlet, what can be done in that servlet is endless as long as it returns javascript or CSS. We at Asponte tend to use this for retrieving CSS that we store in WCM for ease of development during a project.
In the dynamic project, create a new java package in the dynamic project (com.mycustomtheme.servlets for example). In that package, create a new java servlet called "GetMyCustomCSS" and implement the GET method (POST is never called). Paste the following code into the doGet method of the servlet.

PrintWriter writer = response.getWriter();
writer.write("body{background-color:blue !important;}");

In the WEB-INF directory of the static project, create a new file called "plugin.xml" or open yours up if you already have one. If you already have one, omit the first and last lines. Otherwise, copy the entire xml below and update your dynamic project context root accordingly.

<xml version="1.0" encoding="UTF-8">

<plugin id="com.mycustom85theme.plugins" name="8.5 Custom Theme Modules" provider-name="MyCustomTheme" version="1.0.0">

    <extension id="my_custom_dynamic_css" point="com.ibm.portal.resourceaggregator.module">

        <module id="my_custom_dynamic_css"><title lang="en" value="My Custom Dynamic CSS"></title></module>


Now modify the theme profile and remove our previously added custom modules and replace them with "my_custom_dynamic_css". Deploy the theme and restart the portal server. A restart is required regardless of the options previously mentioned because the plugin.xml file is loaded on server startup and isn't reread when the theme is deployed.
After the restart, navigate to the page where the custom profile was applied and verify that the background is now blue.
In this blog, we've showed you how to add a custom theme module using both the contributions json file as well as the plugin.xml. 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. Also, if you enjoyed it and want more, please like this blog entry.

Contact Form- Asponte Custom Skin


Contact Us


Call Us 888-926-9434
Complementary Content