Tuesday, March 11, 2014

How to Load a Different Theme for a Specific XPage

You would think that what I am about to describe would be something that it easy and straightforward but it is certainly not. In the post I am going to go over the two best ways to use a different theme for a specific XPage(s) in your applications.

This post is based on my own experiences, and experiences gained from this Stack Overflow question that I asked.   Thanks to Toby Samples and Tim Tripcony for your answers which are paraphrased below.

The Problem

For whatever reason, whether you are having CSS conflicts or a different reason and you want to use a different theme for a certain page and leave the rest of the application alone.  The assumption here is that you have a theme that you like for the majority of your application.  You have already set that theme in the XSP Properties of the application.

Fix #1

Set the session variable in each XPage to set the theme.  When you set the theme name in the XSP Properties, you are actually setting a session variable called "xsp.theme" that tells the XPages machine what theme to load.  If you want to load a different theme it is a simple fix, just set the variable to another theme.  To make this work, the catch is that you have to set this on every XPage in the application.   The code will look something like this:  context.setSessionProperty("xsp.theme", "alt-theme"); You would place this code in an event in each XPage.  I don't know which event would be the best, but start with BeforeRenderResponse.  The code that you place in the other XPages would set the xsp.theme property back to the name of the primary theme.

Fix #2

Use a complementary NSF to hold the XPage that use the alternative theme.  The fact that the application is split into two NSF's will be seamless to the users.  Tim Tripcony make a compelling argument to the benefits of this approach.  The chief benefit in my opinion is that you leave the rest of your application alone.   This approach seems like the easiest to implement if you are pressed for time.

What Approach did I go with?

I was going to go with Fix#1 but before I got a chance to do that, my friend Brad Balassaitis emailed me that he had figured out why I was have CSS conflicts and how to fix them and thus eliminated my need to use an alternative theme. Thanks again, Brad.


  1. You are welcome! I'm glad I was able to help.

  2. Steve, I have added the phase listener code to my SO answer that would allow you to do Fix # 1 without touching every page, in fact you don't have to touch any pages.


    1. Thanks Toby for chiming in. I did see that, but didn't understand the ramifications, as in that you didn't have to touch every page. I must admit that phase listeners are something that I haven't wrapped my mind around yet. Congrats on the new job!

  3. Thanks! IBM has mentioned of a 3rd option of simply adding a new property in the XPage to point to the different theme. Basically, in the XPage's All properties - data - properties - add one where the parameter is "xsp.theme" and the val is your theme name. You can find details in Niklas' answer here: http://stackoverflow.com/questions/9367722/how-to-use-multiple-themes-at-the-same-time

    Any ideas?