Create New Theme in WebSphere Portal

This article shows you how to create a new theme in WebSphere Portal from v8.5 CF8  onward. There are other considerations that you might want to consider when you are creating a new theme for your clients. For example:

  • Should you enable friendly url in the portal (How to enable friendly url in WebSphere Portal Theme)?
  • Do you need to support localization? If not, do remember to remove locales support with this exercise to avoid nasty surprises.
  • How do you make IBM theme truly responsive? By default, IBM theme 8.5 will render desktop/tablet/mobile views according to browser’s User Agent. Which means despite iPad is able to support 1024 pixels, IBM theme will still renders your theme in tablet view.

 

This article was updated on 30 Oct 2015 to incorporate WebSphere Portal v8.5 CF8 updates such as DXSync and Theme Manager into the process.

Step 1: Install IBM Digital Experience File Sync for Static Resources Development

  1. DxSync only works fully with Node.js v0.12.* (as of WebSphere Portal v8.5 CF8). Pathwatcher module will not work if u are using the latest Node.js.
  2. Download the latest stable release of IBM Digital Experience File Sync from Github.
  3. Extract the file and run the “install.cmd” using cmd.
    20151028066

Alternatively, you can continue to use WebDAV client for static resources development. Our past favourite client is Cyberduck:

  • Connect to http://<server ip>:<port>/wps/mycontenthandler/dav/themelist via WebDAV client.
    Note: in our screenshot, you might notice that we are pointing to “/web/” instead of the default “/wps/“, please ignore that as we are trying out other configuration at the same time. By default, it will be pointing to “/wps/”.
    20131227003

 

Step 2: Setup DXSync and Copy The Static Resources for Your Theme

  1. Create new theme using Theme Manager. Click on “Theme Development” in the Applications menu.
    20160405140
  2. Click on the “Create Theme” button.
    20160405138
  3. Key in your theme’s title, description and select “Portal 8.5” as template.

    Note: In this step, I would prefer to remove the spaces for the theme’s title so that the theme folder created is more in-line with IBM themes naming convention (without spaces – see below screenshots).2016040513720151030072

  4. Click on the “Edit” (Gear) icon and edit the theme’s properties accordingly. Below are some of the common configuration that I would usually do:
    • General Tab
      • Add back the spaces for the theme’s Title *.
        20160405143
    • Skins Tab
      • Theme Manager by default will clone and install Portal 8.5 skins (Hidden, Hidden Plus, No Skin and Standard) and installed them as 4 separate new skins. This will cause skin duplication in your client’s environment (see the screenshot below).
        20160405147
        First identify the skin(s) that you are going to use and edit the skin’s Title, Localization, Unique Name and Static Content Root accordingly. For the unused skins, just make a “mark” in the skin’s title  as we are going to delete them in the later stage.
        20160405144
    • Localization Tab
      • Add back the spaces for the theme’s Title.
        20160405146
    • Advanced Tab
      • Edit the theme’s unique name accordingly and click on the “Done” button.
        20160405145
  5. Create a new local directory in your desktop for DXSync syndication with the new theme.
    20151030073
  6. In your command prompt, go to the local directory that you have just created and type “dxsync init“. Key in the necessary information.
    20151030074
    20151030075
  7. Start DXSync syndication by running the following command: “dxsync run“.
    20151030076
What we have done so far?
We have successfully setup DXSync and replicate the theme's static resources (as in the "frontend"), but the new theme is still referencing the default theme's dynamic resources (css/js/navigation, page menu, footer etc). 

To understand the static resources portion, go to your local DXSync theme folder <local_dxsync_theme_dir>/nls folder and play around with theme_en.html file.

 

Step 3: Remove Unwanted Skins

We have been experimenting around to find the easiest and “cleanest” (no skin entry in xmlaccess and WebDAV) way to delete skin. Below are our findings:

  1. Go to WebSphere Portal Administration page (http://<base portal ip>:10039/wps/myportal/Administration).
  2. Go to Portal User Interface > Themes and Skins.
    20160406148
  3. Delete the unwanted skins that you have “marked” earlier.
    20160406149
  4. Go to your local DXSync theme’s skin folder (<local_dxsync_theme_dir>/skins) and delete the unwanted skin folders. You will need to stop your DXSync in order to delete the folders.
    20160406150
  5. Run DXSync to sync up your changes. Don’t worry about the temporary error warning message (see screenshot below).
    20160406151

 

Step 4: Copy The Dynamic Resources for Your Theme

  1. Open your Eclipse or IBM® Rational® Application Developer and make sure Java EE developer tools add-on is installed.
    (note that the screenshots will varies between different RAD versions, I am currently using RAD 9.1)
  2. Click on File > New > Web Project.
    20160406153
  3. Key in your custom theme’s name and do the following:
    • Select “Simple” as Project Templates
    • Select “Java EE” as Programming Model
    • Click on the “Next” button
      20160406154
  4. Under Deployment tab, do the following:
    • Unchecked “Add support for WebSphere bindings and extensions”
    • Select “2.4” as Web module version
    • Checked “Add project to an EAR
    • Click on the “Finish” button
      20160406156
  5. Go to <portal_server_root>\theme\wp.theme.themes\default85\installedApps\DefaultTheme85.ear\DefaultTheme85.war and copy the following folders to your web project’s WebContent folder:
    • skins folder
    • themes folder
  6. Go to <portal_server_root>\theme\wp.theme.themes\default85\installedApps\DefaultTheme85.ear\DefaultTheme85.war\WEB-INF and copy the following files/folders to your web project’s WEB-INF folder:
    • decorations.xml
    • tld folder
    • plugin.xml
  7. Your web project’s file structure should looks similar like this:
    20160406158
  8. Edit the plugin.xml as follows:
    1. Change the following configuration to match your custom theme (see example below):
      • Plugin id and name (*important step*)
      • Extension id
      • Module id
        20160406157
    2. Edit all <title> and <description> tags to match your custom theme’s title and description
    3. Change all “85theme_” to your custom theme references (“ghostTheme_“)
      20160407158
    4. Remember to update the plugin.xml whenever you have add in a new dynamic resource.
  9. Follow the steps in WebSphere Portal: Specify White and Black List for Web Application to specify white and blacklist for your theme.
  10. Right-click your custom EAR project and export it as EAR file.
    20160407159
  11. Log on to the WebSphere® Integrated Solutions Console (https://<server ip>:10041/ibm/console) and go to Applications > Application Types > WebSphere enterprise applications.
  12. Click on the Install button and select your exported custom EAR file. Click on the Next button.
  13. Select Fast Path, expand Choose to generate default bindings and mappings, select Generate Default Bindings, and click Next button.
  14. Click on the Next button again (unless you wish to edit the default installation options).
  15. Checked the custom module and click on the Apply button. Click on the Next button.
  16. Click on the Finish button.
  17. When the EAR file is done installing, click Save directly to the master configuration link.
  18. Checked the custom application and click on the Start button.
  19. If the entire process is successfully, you should be able to find your new dynamic resources at <wp_profile_root>\installedApps\<cell>\<CustomThemeEAR.ear>\<CustomTheme.war> folder.
What we have done so far?
We have successfully replicate a new set of dynamic resources for our custom theme (as in the "backend codes"). But unlike Step 1, we are unable to test the changes immediately as our custom theme is still referencing the default theme's dynamic resources. Hence, this brings us to the 3rd step!

 

Step 5: Modify The Dynamic Resource References For Your Theme

  1. Ensure that your DXSync syndication for your custom theme’s static resources is still running.
  2. Go to your local static resources “<custom theme>/profiles” folder and replace all “wp_dynamicContentSpots_85occurrences in profile_*.json files to the new custom theme reference that you have defined in the plugin.xml (“geek_dynamicContentSpots_ghostTheme“).
  3. At the <custom theme>/nls folder, edit theme_en.html and replace all “85theme” occurrences to the new custom theme reference you have defined in the plugin.xml (“ghostTheme“). For example dyn-cs:id:85theme_head becomes dyn-cs:id:ghostTheme_head.
  4. Restart WebSphere Portal (even though I suspect that this step is not necessary).
What we have done so far?
We have successfully modify our custom theme to reference the new set of dynamic resources which we have created in Step 2. To verify, make changes to your dynamic resources jsp and restart WebSphere Portal, the changes should reflect.

 

Step 6: Enable JSP Auto-Reload In WebSphere Application Server

Do the steps listed in Enable Auto JSP Reload in WebSphere Portal to prevent the need to restart WebSphere Portal whenever you have make changes to the dynamic resources.

References:

  1. Theme Customization 8.0 Quick Reference
  2. Developing Themes for WebSphere Portal 8.5

One thought on “Create New Theme in WebSphere Portal”

Leave a Reply

Your email address will not be published. Required fields are marked *