Customizing themes in a dashboard space

A theme defines the overall structure, appearance, and behavior of a space. By default, all spaces use the standard theme that is provided with the product. You can create one or more custom themes to replace or augment this default theme.

About this task

The theme is a powerful set of programming artifacts that you can use to control every aspect of how a page is displayed in a space. However, for most customization purposes, for example, changing the color or images used within a space, consider customizing the styles used for the space rather than creating a new theme. Customizing the theme of a space is a much more complex undertaking, and has implications for space maintenance, migration, and upgrades to later product versions. For more information about customizing styles, see Creating and customizing styles for dashboard spaces.
Important: Before you customize the theme, be aware of the following:
  • Customizing a theme requires familiarity with HTML, CSS, JavaScript, the iWidget specification, and the Dojo widget library.
  • If you customize a theme, any IBM® updates to the default theme artifacts will not be applied during regular service or maintenance activities. Customized themes must be updated and maintained manually.

The following files and folders define and control the theme for a space.

Table 1. Theme files and folders
File or folder name Description
theme.html
The theme is primarily defined by the theme.html file. This file contains four types of elements:
Markup code
Static markup code that defines the overall structure of the page. You can modify this code to customize how the page is structured and organized.
JavaScript code
JavaScript code that defines page-level scripting logic. You can add additional JavaScript to extend the existing page behavior.
Dynamic content spots
Special markup that defines where generated content from server-side JavaServer Pages (JSP) files will be added. Administrators use the administrative console to map the content spot identifiers and JSP pages.
The following example illustrates a dynamic content spot:
<link rel="dynamic-content" href="dyn-cs:id:head@tl:oid:csa2.theme">
You can add, remove, replace, or hide dynamic content spots.
System widget markup
Special markup that reference widget descriptors (the iWidget 2.1 specification). Widgets are created with client-side JavaScript processing, and then added dynamically to the Document Object Model (DOM) in the defined regions. Widget artifacts can be deployed as Java EE WAR files or they can be deployed directly in WebDAV.
The following example illustrates system widget markup:
<div class="iw-iWidget iw-Standalone" id="modeSelector">
<a clas="iw-Definition" href="/BusinessSpace/iWidget/widgets/system/modeSelector/modeSelector.xml">
</div>
You can add, remove, replace, or hide system widgets.
embed.html A simplified version of theme.html, this file contains the main lotusFrame markup with the widgets and is used to display the content area when a page is embedded on another web page.
metadata.properties The properties file that contains identifying information for the theme.
theme.css and bspaceCustom.css The style sheets that control the appearance of the theme.

If you plan to make style changes to the theme, you need to either edit these files or create an additional CSS file as a peer of theme.css and bspaceCustom.css.

banner This folder contains the dynamic content needed for banner customization.
images This folder contains the images used in the theme.
menuDefinitions This folder contains JavaScript Object Notation (JSON) files used to customize the content in context menus.
metaData This folder contains the localized_en.properties file, which defines the name of theme shown in the Choose a theme for this space drop-down menu.
spaceStyles This folder contains JavaScript files and subfolders used to apply different styles to the interface.
Standard This folder contains the standard skin for widgets. This skin has a border around each widget and a toolbar on top with a context menu and icons for minimizing, maximizing, and restoring widget size.
Thin This folder contains a widget skin that hides the border and the toolbar.
  • Creating themes in a dashboard space
    For most of your space customization needs, you do not need to create a new theme. Instead, you can customize your spaces using custom color, images, banners, and so on without having to deal with the complexity of themes. If you do need to create a custom theme, you can customize the default theme to achieve the behavior and appearance that you want.
  • Elements in the theme for dashboard spaces
    Before you begin to customize the theme for a space, you need to understand what each element is responsible for and whether you can modify it.
  • Enabling banner customization in a custom theme for dashboard spaces
    The default theme allows for the customization of the banner that appears at the top of a space. You can allow the same banner customization in spaces that make use of your custom theme by providing your own dynamic content spot for your banner.

What to do next

To make your changes to the theme available, restart the server that hosts the dashboard space.
Parent topic: Customizing dashboard spaces