Theme System

The User Console's graphical interface is built on a CSS-based theme system. The sections below contain information for theme designers and developers.

Theme System Overview

The CSS-based theme system allows you to change the look of the BA Server and its client tools by creating and adding your own themes. This is accomplished by working with just a few key configuration files.

The style sheets that make up the look and feel of the User Console, Dashboard Designer, Analyzer and Interactive Reporting are mostly in one location. These styles and scripts combine to make the default system theme, Crystal. This theme is located in the Common UI plug-in directory: /pentaho/server/biserver-ee/pentaho-solutions/system/common-ui/resources/themes.

There are two different kinds of themes: system and local. System themes provide common styles and scripts that apply across the entire BA Server. For instance, buttons are defined in the default system theme, Crystal. A change to the Crystal system theme will change the way buttons look in all applications. Local themes are defined for a particular area or "context" of the BA Server. Contexts include BA Server plug-ins as well as the names of the top-level directories in the Pentaho WAR. Resources for local themes take effect only in their particular area of the BA Server.

Any page shown by the BA Server that includes the webcontext.js script will automatically have all of the active theme's JavaScript and CSS files included. For instance, below is a sample theme containing one CSS and JavaScript file:

<themes root-folder="style">
   <crystal display-name="Crystal" system="true">
    <file>crystalStyles.css</file>
    <file>crystalScripts.js</file>
   </crystal>
</themes>

When the Crystal theme is active, the following are added to the HTML page:

<script type="text/javascript" src="/pentaho/common-ui/themes/crystal/crystalStyles.js"></script>
<link rel="stylesheet" type="text/css" href="/pentaho/common-ui/themes/crystal/crystalStyles.css"/>

This automatic insertion of theme resources makes it possible to change themes without having to edit the main content HTML documents to include the theme resource's tag individually. The theme system will include any number of JavaScript and CSS files defined for your theme.

You can add local styles in a similar fashion. The only requirement is that you tell the system what context you need to load. This is done by adding ?context=myPlugin to the webcontext.js script where myPlugin is the name of your plug-in or root WAR folder:

<script type="text/javascript" src="webContext.js?context=myPlugin"></script>

Create a New Theme

The best way to create a new theme is to copy an existing theme folder, and use that to create your new theme.

On startup, the BA Server searches for themes.xml files in every plug-in and root-level folder in the Pentaho WAR. Multiple themes can be defined in one themes.xml file, and they can be system, local, or a combination of both. The following example defines a system and local theme named Crystal.

<themes root-folder="resources/themes">
    <crystal display-name="Crystal" system="true">
     <file>crystalStyles.css</file>
     <file>crystalScripts.js</file>
    </crystal>
    <crystal display-name="Crystal" system="true">
     <file>localCrystalStyles.css</file>
    </crystal>
</themes>

Notice that the <themes> node has a root-folder attribute. The value of this attribute is the name of the directory (relative to the Web application context) where your themes are stored. For WAR-based contexts, this is simply a directory name inside the WAR. For instance, if your theme is located in the /pentaho.war/accounting/ folder, the resources would be loaded from /pentaho.war/accounting/resources/themes/.

Plug-in resource loading is different than WAR-based loading in that the plug-in controls how resources are mapped to the URL. If the theme file from above was located in a plug-in called accounting, then the resources would be accessed from the following URL: /pentaho/context/accounting/resources/themes/. This kind of resource mapping is most commonly implemented in BA Server plug-ins through static-path entries:

<static-paths>
    <static-path url="/accounting/resources" localFolder="resources"/>
</static-paths>

Set the Default Theme

The default system theme is defined in the /pentaho-solutions/system/pentaho.xml configuration file through the default-theme node. The BA Server ships with Crystal as the default theme; changing the value to another theme name will set the default active theme for all User Console users.

Switch Console Themes

If you have created an alternate theme and/or localized message bundle, you can switch to it through the View menu in the Pentaho User Console.

Note: You can prevent themes from appearing in this menu by adding a hidden="true" property to the theme node.
You can manually specify a theme for a particular page by including a theme= URL parameter. This will affect only the requested page. The following will load the debug system and local themes if available:

http://localhost:8080/pentaho/content/myPlugin/index.html?theme=debug

If either the system or local debug theme is not found, the resources for the current active theme loads instead. This is particularly useful when testing out new themes and for loading debug versions of scripts and styles.

It is also possible to set the session variable pentaho-user-theme to the desired theme name. This is usually done in a start-up action to have per-user themes in multi-tenancy scenarios.

Test Your CSS Changes

The style sheet files explained earlier in this section contain many style definitions, which makes it difficult to map the CSS classes to what you see in the application at runtime. To make this task easier, we recommend that you use the DevTools for Chrome, Web Inspector for Safari, or Firebug for Firefox to inspect the UI elements you want to style.

Once you've selected an element, you can view all of the CSS properties that apply to it, then change the CSS and watch your changes take immediate effect. This allows you to quickly and easily find the appropriate CSS to edit and gives you the ability to preview your changes in real time.