Theme-able images

To make sure we can display different icons per theme (Onyx, Crystal, Slate, …) we should not be using static paths to images in HTML via the <img> tag. Rather, we should favor using CSS to set background images of a DOM element. This allows us to override images/icons with just CSS to customize a theme.

In general:

change this:

<img src='path/to/my-image.png'/>

preferably to something like this:

.my-image-style { background: url('path/to/my-image.png'); height: 16px; width: 16px;}

<div class='my-image-style'></div>

or, if you must continue using the <img> tag due to some technical limitation/restriction:

<img src='path/to/blank/image.png' class='my-image-style' />

GWT retro-fitting

• If you see an Image in use, change it's source to a blank image. If you don't set it's source or give it an invalid image path, the DOM element will not render properly. It will typically have a border around it that can't be hidden with CSS. Second, add a css style to the object that defines a background image and most likely height & width as well.
• Retrofit usage of GWT image bundles. While these are great for size and performance, they aren't themeable.
• There is a new utility class that can be used to generate an Image in such a fashion. Use the org.pentaho.gwt.widgets.client.utils.ImageUtil class's getThemeableImage method (there is an override to this class in the user-console project that provides the same functionality). This method will generate an Image that sets the source to a blank image and adds any number of class names to the resulting DOM element.
• Example usages of the ImageUtil:

  ImageUtil.getThemeableImage("pentaho-editbutton")      // standard edit icon (pencil) used in the platform
  ImageUtil.getThemeableImage("icon-small", "icon-run"); // usage that sets 2 distinct classnames on the element.
  

Tips on image styling/theming

• Check to see if a css class already exists for an image/icon in one of the themed css files (globalOnyx.css, globalCrystal.css). if so, use it.
• If the image you need isn't available already as a common image/icon but could be re-used by others:
  • Add the image file to a themeable area (like pentaho-commons-gwt-modules/pentaho-gwt-widgets/src/org/pentaho/gwt/widgets/themes/public/themes/images)
  • Add a css definition to all themed files: globalOnyx.css, globalCrystal.css, globalSlate.css. Be sure to define background image url, height, and width
    globalOnyx.css, globalSlate.css

    .my-image-style {
      background: url('../images/myNewCommonIcon.png');  // up to the common theme images folder
      height: 16px;
      width: 16px;
    }
    

  • If a particular theme needs a custom version of the image/icon, add it to the theme-specific images folder and reference it in the css (like pentaho-commons-gwt-modules/pentaho-gwt-widgets/src/org/pentaho/gwt/widgets/themes/public/themes/crystal/images)
    globalCrystal.css

    .my-image-style {
      background: url('images/myNewCommonIcon.png');   // reference to the theme-specific images folder
      height: 16px;
      width: 16px;
    }
    

• If the image/icon is not a common/re-usable one, it should be themed within the context of the plugin that needs it. The process is the saem, but rather than adding the images/css to the global theming system, add them to the plugin (mantle/analyzer/dashboards/...). For example, if the image is only needed for analyzer
  • Add the image to an appropriate subfolder in pentaho-analyzer/resource/images
  • Add a css definition to common.css in analyzer to make sure all themes have a starting point they can override
  • Add theme override images/css to the appropriate theme folders within analyzer as needed.