Page tree
Skip to end of metadata
Go to start of metadata

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

Introduction

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.

Location

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 basics

Extending themes

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.

<theme extends=“Bootstrap3.2.0”>

Above example will extend the Bootstrap3.2.0 theme provided by the Extension Library.

Resources

Another nice thing about themes is to be a central place to declare all your ‘external’ resources, like css, javascript files.

But also meta tags you need across you entire application.

<resources>

        <metaData>

            <name>viewport</name>

            <content>width=device-width, initial-scale=1.0</content>

        </metaData>

    </resources>

<resource>

        <content-type>text/css</content-type>

        <href>libs/fontawesome/css/font-awesome.min.css</href>

</resource>

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.

Expression Language

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.

<control override=“false”>

        <name>ViewRoot</name>

        <property>

            <name>pageTitle</name>

            <value>#{javascript:database.getTitle();}</value>

        </property>

        <property>

            <name>pageIcon</name>

            <value>#{javascript:configBean.getFaviconURL()}</value>

        </property>

</control>

Components

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.

<control>

        <name>DataTable.ViewPanel</name>

        <property>

            <name>dataTableStyleClass</name>

            <value>table table-hover</value>

        </property>

</control>

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

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 –>

<control>

        <name>Button.Primary</name>

        <property>

            <name>styleClass</name>

            <value>btn btn-primary</value>

        </property>

</control>

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”>

</xp:button>

Advanced

There is more beyond the basics

Renderer

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.

<control>

        <name>Pager</name>

        <property>

          <name>rendererType</name>

          <value>nl.elstarit.renderers.type.BootstrapPagerRenderer</value>

        </property>

      </control>

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 –>

  <render-kit>

    <renderer>

      <component-family>com.ibm.xsp.Pager</component-family>

      <renderer-type>nl.elstarit.renderers.type.BootstrapPagerRenderer</renderer-type>

      <renderer-class>nl.elstarit.renderers.BootstrapPagerRenderer</renderer-class>

    </renderer>

  </render-kit>

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.




 

http://elstarit.nl/2015/06/01/power-of-themes-part-2-the-xml-syntax/