Customize the Pentaho User Console
You can change 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 change interactive elements of Report Designer, Analyzer, and Dashboard Designer. For example, you can change the User Console’s default theme from Ruby to Sapphire or Crystal, then examine the style definitions to customize the login page.
Before editing any elements in the Pentaho WAR file, you must stop the web application server on which you are running the Pentaho software.
Location of customizable configuration files
Mantle style CSS
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.pentaho/server/pentaho-server/tomcat/webapps/pentaho/mantle/MantleStyle.css
Theme-specific local and global style sheets for PUC
These directories contain style sheets and other theme materials for each Pentaho Server client tool.
|globalRuby.css||/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/ruby/||This is the main structural, theme-specific style sheet for the default theme for the User Console (Ruby).|
|mantleRuby.css||/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes/ruby/||This is the customizable presentation portion of the theme style sheet for the default theme for the User Console (Ruby).|
|globalCrystal.css||/server/pentaho-server/pentaho-solutions/system/common-ui/resources/themes/crystal/||This is the main structural, theme-specific style sheet for an alternate theme for the User Console (Crystal).|
|mantleCrystal.css||/server/pentaho-server/tomcat/webapps/pentaho/mantle/themes/crystal/||This is the customizable presentation portion of the theme style sheet for an alternate theme for the User Console (Crystal).|
Product-specific theme settings for Analyzer, Dashboard Designer, and Interactive Reports
These directories contain style sheets and other theme materials for each.
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 Reports||pentaho-solutions/system/pentaho-interactive-reporting/resources/web/themes/||Style sheets and theming materials for Interactive Reports.|
|Dashboard Designer||pentaho-solutions/system/dashboards/resources/themes/||Style sheets and theming materials for Dashboard Designer.|
Change the application login page logo and background
#login" for easy identification. The method for changing the logo and background for other available themes, like Crystal and Sapphire, is the same. Each theme uses different style definitions, image types, names, and file paths.
Follow the steps below to change the default logo and background images for the User Console login page theme.
Back up and remove the default image file for the logo from the /pentaho-server/pentaho-solutions/system/common-ui/resources/themes/<theme-name>/images directory of the theme you want to change.
Ruby (default) header_logo.svg Crystal puc-login-logo.png Sapphire pentaho-logo-white.png
Rename the new image file to match the name of the logo file that you are replacing, and then copy the new image file into the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory.
Update the style definitions for your image. Navigate to the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme name> directory for the theme you are changing and then open the .css file with a text editor.
Ruby (default) globalRuby.css Crystal globalCrystal.css Sapphire globalSapphire.css
Locate the #login-header-logo property, then adjust the dimensions and margin for the new image.
(Optional) You can back up and remove the background image file. If not replacing the background image, proceed to the next step.The background image file is located in the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory of the theme you want to change. Use the following table to locate your theme and image.
Ruby (default) bg.svg Crystal login-crystal-bg.jpeg Sapphire #0F2B5B
Rename the new background image file to match the name of the background file that you are replacing, and then copy the new image file into the \pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name>\images directory.
Update the image dimensions for your background. Navigate to the \server\pentaho-server\pentaho-solutions\system\common-ui\resources\themes\<theme-name> directory and open the .css file with a text editor.
Locate the #login-background property, then adjust the dimensions, position, and other properties for the background image.
Save and close the file.
Clear the web browser cache and restart the server 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
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 Reports 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.
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.
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
?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>
<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 or localized message bundle, you can switch to it through the View menu in the Pentaho User Console.
hidden="true"property to the theme node.
You can manually specify a theme for a specified 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 currently active theme are loaded instead, which is useful when testing 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 have 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:
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.
The English-language version of the standard message bundle. This is an identical copy of mantleMessages.properties.
The French-language version of the standard message bundle.
The German-language version of the standard message bundle.
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.
The following code is an example of the content found in the mantleMessages_supported_languages.properties file:
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.