com.smartgwt.client.docs
Interface Skinning

public interface Skinning

Skinning / Theming

Skinning (aka "theming" or "branding") is the process of modifying Smart GWT's default look and feel to match the desired look and feel for your application. Smart GWT supports an extremely powerful and simple skinning system that allows designers with a basic grasp of CSS and JSON to skin any Smart GWT component.

Basics

• Smart GWT components create their visual appearance by dynamically generating HTML, within the browser, using JavaScript.
• the HTML generated by Smart GWT components contains CSS style names and URLs to images
• Smart GWT components can be skinned by replacing the CSS styles and images that the components use by default, or by using JavaScript properties to configure components to use new CSS styles and new image URLs.
• You can change the appearance of an individual Smart GWT component by calling setter methods such as setStyleName() or setBackgroundColor(), or you can skin all components of the same class at once, by using Canvas.setDefaultProperties(). to change the defaults for the class.
• A "skin" consists of:
  • a single CSS stylesheet containing all CSS styles used by Smart GWT components (skin_styles.css)
  • a single JavaScript file that sets component defaults (load_skin.js)
  • a directory tree of images organized by component
• The example skins that come with Smart GWT are inside smartgwt.jar and smartgwt-skins.jar as GWT modules. The standard directory layout for a skin is:

           skin_styles.css
           load_skin.js
           images/
               ListGrid/
                   sort_ascending.gif
                   ...
               Tab/
               ... other directories containing
                   component or shared media ...
    

• A skin is implicitly loaded when you add an <inherits> tag in your .gwt.xml file to include SmartGWT components (name="com.smartgwt(ee).SmartGWT(Pro|Power|EE)"). To switch skins, add the "NoTheme" suffix to the "name" attribute of this <inherits> tag, then add <inherits name="com.smartclient.theme.enterpriseblue.SkinName"/>. These tags cause a <SCRIPT SRC=> tag to be injected into your bootstrap .html page, which loads load_skin.js for the appropriate skin. load_skin.js loads the stylesheet and sets the CSS styleNames and media URLs that Smart GWT components will use.

CSS3 mode

3 of Smart GWT's most commonly used skins - Enterprise, EnterpriseBlue and Graphite - now have a "CSS3 mode" in which almost all images required by the skin are replaced with CSS3 settings that appear nearly identical to the image-based appearance. This results in a performance boost through both a simplified DOM and far few images being loaded.

By default CSS3 mode is automatically used in modern browsers such as Firefox, Chrome and Safari. Internet Explorer 9 does not have sufficient CSS support to create a close match to the existing image-based skin, so CSS3 mode is not enabled by default. If CSS3 mode is manually enabled for IE, this will result in a degraded appearance that is similar across IE6, 7, 8 and 9: rounded elements such as tabs will become square, and gradient backgrounds will have subtly lower quality (due to lack of CSS color stop support).

To override the default decision on whether to use CSS3 support, set the JavaScript global variable isc_css3Mode before any of the Smart GWT libraries are loaded. For example:

    <script>isc_css3Mode = "on";</script>
  

Possible settings are:

• "supported"
: (default setting) CSS3 mode will be used for browsers that fully support it (including rounded edges and full gradient support)
• "off"
: CSS3 mode will never be used
• "on"
: CSS3 mode will be used for all browser

For more control than the above settings provide, you can create a custom skin based on one of the above 3 skins and modify load_skin.js - whether CSS3 mode is used is controlled by a JavaScript variable useCSS3 defined in this file.

NOTE: we are working on improving IE9 support using the limited CSS3 features provided by this browser, but at the moment, the well-published workarounds for IE9's CSS3 bugs create other bugs of their own that are, as yet, unresolved.

Modifying Skins

To modify a skin, first create a copy of one of the skins that comes with the Smart GWT SDK, then modify the copy. Full instructions are provided in Chapter 9 of the QuickStart Guide.

Locating Skinning Properties

Starting from the name of the component

Given a Smart GWT component that you want to skin, open it's JavaDoc:

• for properties that set CSS styles, look for properties whose name includes "style", eg baseStyle
• for properties that control URLs to media, look for properties whose name includes "src", "image" or "icon", such as src
• for subcomponents that also support skinning, look for methods like setSubcomponentProperties(), such as Window.setPaneContainerProperties().

Starting from a running example

Specific browsers offer alternate approaches to quickly discover the images or style names being used for a part of a Smart GWT component's appearance:

• the Firefox browser offers a dialog via Tools->"Page Info" that gives a manifest of media used in the page.
• the Firebug extension for Firefox has an "Inspect" feature that allows you to see the HTML, CSS and media in use for a given area of the screen
• right clicking (option-click on a Mac) on an image and choosing "Properties" shows a dialog that provides the image URL in most browsers. Tips:
  • if a Smart GWT component is showing text over an image, right-click at the very edge of the underlying image to get image properties rather than information about the text label
  • on some browsers, in order to see the full image URL, you may need to drag select the partial URL of the image shown in the properties dialog

Image URLs in Smart GWT

Properties that refer to images by URL, such as src and icon, are specially interpreted in Smart GWT to allow for simpler and more uniform image URLs, and to allow applications to be restructured more easily.

Unlike the URL used with an HTML <IMG> element, the image URL passed to a Smart GWT component is not assumed to be relative to the current page. See SCImgURL for a full explanation of the default application image directory, and the meaning of the "[SKIN]" prefix.

Specifying Image URLs

Default image URLs for Smart GWT components are specified in load_skin.js via JavaScript, using calls to Class.addProperties and Class.changeDefaults. For example, the load_skin.js file from the "Enterprise" skin includes the following code to establish the media used by minimizeButton:

     isc.Window.changeDefaults("minimizeButtonDefaults", { 
          src:"[SKIN]/Window/minimize.png"
     });
  

NOTE: These are JavaScript APIs and hence do not appear in SmartGWT JavaDoc - you may want to refer to the SmartClient Reference available at Isomorphic.com for these specific APIs.

Specifying Image Sizes

Many Smart GWT components must know some image sizes in advance, in order to allow those components to autosize to data or content.

For example, the ImgTabs used in TabSets are capable of automatically sizing to a variable length title. To make this possible, Smart GWT must know the sizes of the images used as "endcaps" on each tab in advance.

Like image URLs, image sizes are specified in load_skin.js. The following code sample establishes the default size of the "endcaps" for tabs, by setting a default value for capSize:

      isc.ImgTab.addProperties({
          capSize:4
      })
  

CSS usage in Smart GWT

In Smart GWT, screen layout and sizing are controlled via JavaScript, and appearance via CSS and images.

CSS borders, margins and padding applied to Smart GWT components can be treated as purely visual properties with no effect on sizing or layout. Unlike HTML elements, a Smart GWT component will always have the exact size you specify via JavaScript, regardless of browser platform, browser compatibility mode, or borders, margins, or padding, all of which normally affect the final size of an HTML element.

For this reason, Smart GWT skinning requires only novice-level familiarity with CSS, as CSS is used principally for colors and fonts. See this discussion for further details on what properties should be set via CSS vs via JavaScript.

Statefulness and Suffixes

Some components or areas within components, including buttons and the cells within a grid, are "stateful", meaning that they can be in one of a set of states each of which has a distinct visual appearance.

Stateful components switch the CSS styles or image URLs they are using as they transition from state to state, appending state information as suffixes on the style names or URL. See src and baseStyle for details and examples.

Smart GWT has built-in logic to manage a series of state transitions, such as:

• "rollover": showing a different appearance when the mouse is over a component
• "button down": showing a different appearance when the mouse is pressed over a component
• "disabled": showing a different appearance when a component cannot be interacted with
• "selected": showing one of a set of components in a different state to indicate selection

Flags on some components, such as showRollOver, allow you to control whether the component will switch CSS style or image URL when the component transitions into a given state.

StretchImg: 3-segment stretchable images

A StretchImg is Smart GWT component that renders out a compound image composed of 3 image files: two fixed-size endcaps images and a stretchable center segment. Like stateful components, the names of each image segment is appended to the image URL as a suffix. See src for details.

EdgedCanvas

Similar to a StretchImg, an EdgedCanvas provides an image-based decorative edge around and/or behind another component, with up to 9 segments (a 3x3 grid). Decorative edges can be added to any component by setting showEdges:true. EdgedCanvas is also used to construct dropshadows, which can be enabled on any component via showShadow:true.

Multiple looks for the same component type

In some cases you need to create two variations in appearance for a component with the same behavior. For example, you may want to create a specialized Window, called "PaletteWindow", that behaves like a normal Window but has a very compact look & feel. To create a separately skinnable component for PaletteWindow, use isc.defineClass. For example:

     isc.defineClass("PaletteWindow", "Window");
     isc.PaletteWindow.addProperties({
         showFooter:false,
         ...
     })
  

This creates a SmartClient class, which does not exist as a Java class. To make your SmartGWT widget use the settings on this Smart GWT class, call setScClassName() passing the String name of the Smart GWT class.

Where to put skin-related JavaScript

If you're creating a custom skin, you can place JavaScript snippets such as those shown above in your custom skin's load_skin.js file. If you prefer not to create a custom skin for small customizations, you can execute JavaScript via a JSNI method in your Java code. With this latter approach, be sure to change "isc." to "$wnd.isc." wherever it appears, and to call the JSNI method before creating any SmartGWT components.