Themes are a very powerful feature in XPages development. It is the central place to define external libraries, look and feel of components, which are available throughout the application
A Theme is pure XML as lots of other parts of XPages development. As XML should be valid, with themes it also the case. Be aware of compilation errors.
In a Theme you can specify resources, override existing controls. And of course extending existing themes.
Themes can be found in a Notes database under Resources –> Themes. And to benefit from themes, goto XSP properties ( how can be found Application Configuration ). On the first tab you can select via de dropdown box a theme.
When you have saved your own theme file, it should be selectable.
Save the XSP properties and, if necessary, build your project.
The first tag in the Theme file is the <theme> tag, and as you can see, you can extend other themes in this tag. This is a very usefull, because you can benefit from other themes and don’t need to write all the theme components.
Above example will extend the Bootstrap3.2.0 theme provided by the Extension Library.
But also meta tags you need across you entire application.
Above example shows the way to define the meta tag, like the view port
Below is an example who to include a css file which is available cross application.
Themes support the use of Expression Language, so you can benefit from other Java resources in the XPages application.
One nice example is the favicon, which is stored in a configuration file or application title. As you can in the example below, the pageTitle is set to the database title.
In the themes you can override existing components of the XPages runtime, with you own style or properties.
For a list of available components, navigate to the <Notes program>xsp\nsf\themes directory. Inside this folder you will fin all themes used by the XPages runtime.
Open it will you preferred text editor and start searching for you component.
There is comments above the components, so it is not that difficult to find the desired component.
In the above example I override the style of the ViewPanel Table class to meet the style of Bootstrap of tables.
As you can see, it is only a few lines of code, but all the view panels in the XPages application will behave like a Bootstrap table with hover colouring. Below the result.
Theme Id’s is another powerful functionality of Themes. In a Theme you specify a theme id component. Give it a unique name.
Best way to follow the way IBM is using, so you will later understand the use of the theme component.
<!– Primary Button –>
Inside the application to assign this theme name as ThemeId to a component and on runtime the button will behave as primary Bootstrap button.
<xp:button id=“buttonSave” themeId=“Button.Primary”>
There is more beyond the basics
In my application I am using bootstrap to make it responsive. One of the not so nice components that needs some love to meet the Bootstrap look and feel is the Pager.
I have created a custom Java renderer, which convert the standard Pager.
In the Theme I specify the component who will use the Renderer.
The RenderType is pointing to a Renderkit component I created in the Faces-config.xml, which is pointing to the actual Java Class who do the magic.
<!– Bootstrap render pager –>
The result of the renderer you see in the example below.
UPDATE: Paul Withers has asked to make a pull request to include my BootstrapRenderer in the Extension Library. I had a look at the source code of the Extension Library at Github and I noticed they changed the PagerRenderer heavily to meet the requirements of Bootstrap 3.x, the same what the goal of my own PagerRenderer. So take the above as an example. The nice layout is build in the latest version of the Extension Library.