- Location of Customizable Configuration Files
- Change Logo on Application Login Page
- Add a Logo to the Web Application
- Change the Background Image
- Make Custom User Console Themes
- Test Your CSS Changes
- Localize the Pentaho Server
You can alter the look and feel of the Pentaho User Console (the standard web application for the Pentaho Server) by manually editing its configuration files, graphics, and CSS style sheets. Through these files and style sheets, you can also alter interactive elements of Reporting, Analysis, and Dashboards. If you need to configure or manage Pentaho Server users and their roles, as opposed to changing its style, please use the Administration page of the console.
Before editing anything in the Pentaho WAR file, you must stop the web application server on which you are running the Pentaho Suite.
Location of Customizable Configuration Files
This is the structural cascading style sheet for the Pentaho User Console. It inherits some elements from the Widgets.css file in the same directory, so you may need to look at that as well. Modifying these styles could have dramatic impact on Pentaho User Console rendering.
Theme-Specific Local and Global Style Sheets for PUC
These directories contain style sheets and other theme materials for each Pentaho Server client tool.
|globalCrystal.css||/pentaho-solutions/system/common-ui/resources/themes/crystal/||This is the main structural, theme-specific style sheet for the default theme for the User Console (Crystal).|
|mantleCrystal.css||tomcat/webapps/pentaho/mantle/themes/crystal/||This is the customizable presentation portion of the theme style sheet for the default theme for the User Console (Crystal).|
|globalOnyx.css||/pentaho-solutions/system/common-ui/resources/themes/onyx/||This is the main structural, theme-specific style sheet for an alternate theme for the User Console (Onyx).|
|mantleOnyx.css||tomcat/webapps/pentaho/mantle/themes/onyx/||This is the customizable presentation portion of the theme style sheet for an alternate theme for the User Console (Onyx).|
Product-Specific Theme Settings for Analyzer, Dashboard Designer, and Interactive Reporting
These directories contain style sheets and other theme materials for each.
Set the <cache>false</cache> in ...pentaho-solutions/system/common-ui/settings.xml while customizing these plugins. Otherwise, the changes are not visible without a server restart.
|Analyzer||/pentaho-solutions/system/analyzer/styles/themes/||Style sheets and theming materials for Analyzer.|
|Interactive Reporting||/pentaho-solutions/system/pentaho-interactive-reporting/resources/web/themes/||Style sheets and theming materials for Interactive Reporting.|
|Dashboard Designer||/pentaho-solutions/system/dashboards/resources/themes/||Style sheets and theming materials for Dashboard Designer.|
Change Logo on Application Login Page
You can change the User Console login page to display a different logo than the default one, such as your corporate logo or other image.
- Backup and remove the file puc-login-logo.png from the /pentaho/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/images directory.
- Rename your own logo image to puc-login-logo.png.
- Copy the image into the /pentaho/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/images directory. Your users must clear the cache on their web browsers and reboot to be able to see the new logo.
Add a Logo to the Web Application
You can customize the Pentaho web application to display a logo. The best way to do this is to edit the Mantle.jsp file in the /pentaho/server/pentaho-server/tomcat/webapps/pentaho/mantle/ folder.
In this example, the logo is added to the header on the right, but you can add it to the left or as a banner on the top or bottom of the page.
<div id="pucWrapper" cellspacing="0" cellpadding="0" style="width: 100%; height: 100%;"> <div id="pucHeader" cellspacing="0" cellpadding="0"> ... <div id="logo" style="float: right; padding-right:10px"><IMG src="mantle/logo.png"></IMG></div> ...
The logo.png is used as the graphic within the pucHeader div.
Change the Background Image
You can change the background image that appears in the content pane in the Pentaho User Console by modifying or replacing the login-crystal-bg.jpeg file in the pentaho/system/common-ui/resources/themes/<theme-name>/images folder. The folder and file name must be identical.
Make Custom User Console Themes
The User Console's graphical interface is built on a CSS-based theme system. The sections below contain information for theme designers and developers.
Understanding Theme System Basics
The CSS-based theme system enables you to change the look of the Pentaho Server. With this type of theme system, you can create or add your own themes 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, Ruby. This theme is located in the Common UI plug-in directory: /pentaho/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes.
Themes can be systemwide or local.
- Systemwide: Common styles and scripts applied across the client tools of the entire Pentaho Server.
- For example, the style of the buttons used in the client tools are defined in the default systemwide Ruby theme. A modification to the buttons in the Ruby theme changes the way buttons look in all the client tools.
- Local: Styles and scripts applied to a particular area, also known as context.
- Contexts include Pentaho Server plug-ins as well as the names of the top-level directories in the Pentaho WAR file. These theme resources only take effect in their particular area of the Pentaho Server client tools.
<themes root-folder="style"> <crystal display-name="Crystal" system="true"> <file>crystalStyles.css</file> <file>crystalScripts.js</file> </crystal> </themes>
When this theme is active, the following resources are added to the HTML page:
Although resources are automatically inserted, your CSS changes will not appear in the User Console until you start and restart the Pentaho Server. Every time you modify a theme along with any XML or CSS files, the Pentaho Server must be restarted before your changes can appear in the User Console.
You can add local styles in a similar fashion. The only requirement is for you to tell the system what context you need to load. You can tell the system what needs to be loaded by adding ?context=myPlugin to the webcontext.js script where myPlugin is the name of your plug-in or root WAR folder:
Creating a New Theme
The best way to create a new theme is to copy an existing theme folder structure and modify it to make it your own. Make sure to duplicate the theme folder structure in both the /pentaho/server/pentaho-server/pentaho-solutions/system/common-ui and /pentaho/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes directories when copying an existing theme.
On startup, the Pentaho Server searches for themes.xml files in every plug-in and root-level folder in the Pentaho WAR file. Multiple themes can be defined in the themes.xml files of each directory. Themes can be systemwide, local, or a combination of both. The following example defines both a systemwide 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>
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, it is simply a directory name inside the WAR file. For example, if your theme is located under an accounting folder inside the structure of your Pentaho WAR file, the resources are loaded from the accounting/resources/themes folder of this structure.
Besides inserting the new <themes> node into the themes.xml files, you need to change the name of the mantleTheme_name.css file in the copied mantle theme folder structure to match your new theme name (Theme_name). After changing this file name, re-edit the themes.xml file in /pentaho/server/biserveree/tomcat/webapps/pentaho/mantle to include a reference to this new CSS file.
Plug-in resource loading is different than WAR-based loading. With this type of loading, 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 are accessed from the following URL: /pentaho/context/accounting/resources/themes/. This kind of resource mapping is most commonly implemented in Pentaho Server plug-ins through static-path entries:
<static-paths> <static-path url="/accounting/resources" localFolder="resources"/> </static-paths>
When you want your changes to appear, restart the Pentaho Server before opening the User Console.
Setting the Default Theme
The default system theme is defined in the /pentaho-solutions/system/pentaho.xml configuration file through the <default-theme> node. The Pentaho Server ships with Ruby as the default theme; changing the value to another theme name will set the default active theme for all User Console users.
Switching 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.
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. Only the requested page is affected. For example, the following URL loads the Sapphire theme systemwide and local themes if available:
If either the systemwide or local debug theme is not found, the resources for the current active theme loads, which 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, which 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.
Localize the Pentaho Server
You can localize the Pentaho User Console, Pentaho Analyzer, and Dashboard Designer by creating locale- and language-specific message bundles within the Pentaho Web application. Message bundles are dynamically adjusted according to browser locale, so you can create localized message bundles for every language you want to support, and let each individual user's system language settings determine which one is loaded.
Stop the Pentaho Server before editing anything inside of the Pentaho WAR file.
For brevity's sake, only the default Pentaho User Console files will be explained in detail. The file naming convention is identical among all message bundles in Pentaho Business Analytics. The following files are located in the /mantle/messages/ directory:
- mantleMessages.properties: The default message bundle for the Pentaho User Console. In its initial condition, it is a copy of mantleMessages_en.properties. If you want to change the default language and dialect, copy your preferred message bundle file over this one.
- mantleMessages_en.properties: The English-language version of the standard message bundle. This is an identical copy of mantleMessages.properties.
- mantleMessages_fr.properties: The French-language version of the standard message bundle.
- mantleMessages_de.properties: The German-language version of the standard message bundle.
- mantleMessages_supported_languages.properties: Contains a list of localized message bundles and the native language names they correspond to; this relieves the Pentaho Server of the burden of having to discover them on its own. A supported_languages.properties file should be created for every message bundle that you intend to localize.
en=English de=Deutsch fr=Français
New files are created in the following format: mantleMessages_xx_YY.properties where xx represents a lowercase two-letter language code, and YY represents a two-letter locale code, where applicable. So, for instance, U.S. and British English could have two separate message bundles if you wanted to draw a distinction between the two dialects:
The language and country codes must be in standard ISO format. You can look up both sets of codes on these pages:
You can edit the default message bundle directly if you need to make surgical changes to the content inside of it. If you plan to translate it into another language, it makes more sense to copy the file and change the name appropriately, then translate it line by line. Be sure to update supported_languages.properties with the new country and dialect code and the native language name that it corresponds to.
All message bundles must be UTF-8 encoded.