The User Console is the standard web application for the BA Server, and includes interactive elements of Reporting, Analysis and Dashboards. The Administration page of the console is the central framework through which your BA Server is configured and managed. You can alter the look and feel of the User Console by editing its configuration files, graphics, and CSS style sheets manually.
The Pentaho web application server must be stopped before editing anything inside of the Pentaho WAR file.
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 BA 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 Pentaho 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 Pentaho 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 Pentaho 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.|
|Mobile||/pentaho-solutions/system/pentaho-mobile-plugin/resources/css||Style sheets and theming materials for the Mobile application.|
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/biserver-ee/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/biserver-ee/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/biserver-ee/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.
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.
<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:
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:
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.
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:
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.