Themes were added with XPage to provide the developers with the ability to define the look and feel of an application. The themes provide the following abilities:
- Add CSS resources to an XPage.
- Link to specific controls using its theme ID.
- Apply property values to controls.
- Easy to select a different theme to give a different look and feel.
- Can be set globally (all applications) or per application.
- Different themes can be applied depending on the context.
The theme is handled on the server side where it drives the page creation and controls the HTML generation. It is fully used by XPages, partially by the "classic" web engine. The hardest part will be recognizing how many things you can control from a theme if the results are to be used across multiple applications then put it in the theme.
For the best practice, using themes make your application easier to change, and, make it easier to develop and maintain consistent elements that themes are applied to.
Themes are extensible
Themes can inherit from other themes and override elements of the inherited themes. You normally create a theme by extending one of the standard themes. Domino comes with three themes:
- Webstandard: The basic clean theme
- OneUIv2 ( oneuiv2, oneuiv2_red, oneuiv2_green, oneuiv2_metal, oneuiv2_gold)
- Notes: Notes client theme
The default is the Webstandard.
Creating multiple theme document allows you to build different sets of style sheets that can be selected when the application is deployed. The application can easily have the look and feel changed by selecting which theme to use. For example, you can have different color-based themes. You can choose between red, blue, gold, or metal color themes with OneUI CSS framework.
There are two options for applying CSS style sheets to an XPage applications:
- Add the CSS style sheet as a resource and select the styles in the XPage or custom control.
- Create a theme document and reference the CSS style sheet from it.
Adding the style sheet directly to the XPage or custom control does have a few advantages:
- The list of classes will show in the Styles section for all the controls on the page.
- The design perspective for the XPage will try and apply the styles so visually you will see how the page will look without having to preview it.
You can add the style sheet to a custom control so it is applied to the rest of an XPage. However, make sure that you do not have it as a resource on multiple controls because it is loaded each time it is listed.
Some of the advantages to using themes include:
- Building applications that are easily customized by a third-party.
- Tailoring the site to the user: You can compute the styling by requested device, language, or browser.
- Inherit from other themes such as the built in WebStandard or OneUI.
- Settings that are higher up the tree (themes you have extended from, styling set within the control) that can be overridden.
- Stylesheet and styling information can be computed
- Component styling can be globally controlled; no need to set style information or class. All buttons across all applications have the same style with one place to control all the edits.
The disadvantage is that the list of classes in the style sheets is not display in the Styles section for each control and the design perspective will not render the controls with the style sheets. This can fixed by using a dummy css files that only contains the style class names. For example:
This allows the styles to show in the list and to be rendered in the Design pane. Do not forget to remove it before deploying so you save resources.
To build a theme, the first thing is to select the theme you will be building upon by setting the inheritance in the Theme root element:
If a theme extends a theme with the same name, then the new theme is searched at the upper level. For example, a database theme "oursite" can inherit from a global theme "oursite". All circular references
are checked and prevented.
Check for Safari If you want to include HTML5 and support the webkit based browsers:
Style classes can be set depending on the scoped variables, as in the example below:
The example above applies a style to expand or collapse an area based on the value of the sessionScoped variable ec
You can have elements be hidden in one theme and available in another. Here is an example where additional information is display if a certain theme is selected.
Create a new theme called oneuiv2-debug that extends the oneuiv2_red theme.
The default theme contents use theme inheritance.
Application themes can extend an existing global theme using the
extends attribute. Existing themes include the following options:
1. webstandard 2. oneui 3. notes
The tags contain the themeID and the contains the properties to be set. So the property styleClass is set to debugInfoVisible which is a CSS class. The CSS class:
border: 1px solid;
On one of the custom controls is a div tag that contains the debugging information:
Debug info is displayed when a debug-mode theme has
been selected in the Application Properties
<xp:label id="label3" value="isAuthor: "></xp:label>
<xp:text escape="true" id="debugIsAuthor"
<xp:text escape="true" id="computedField3">
var from = doc.getItemValueString("From");@Name("[ABBREVIATE]",from);}]]>
<xp:text escape="true" id="computedField4"
The div only shows if the debugTheme is selected.
You can set the control or property to over ride the base theme setting or to just extend them.
The control override value can be true (your property only is used) or false (your property is added to any in the theme):
The property can have the mode value be "override" (your property only is used) or "concat" (your property is added to any in the theme):
<property mode ="override">
Themes and classic Domino
The theme property only works on classic web elements if the Enable enhanced HTML generationoption is selected on the database properties dialog box.
To include the same style sheet on all the forms in your database, you can use a theme. First check the Enable enhanced HTML option. Then create a theme design element with the following content in it:
That automatically adds the stylesheet to the form. You can set the style applied to the Domino controls by putting the following in the theme:
This automatically puts a style tag with the specified value on every body tag generated.
Parent topic: 5.0 User interface considerations