com.smartgwt.client.docs
Interface Skinning


public interface Skinning

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

Basics

Modifying Skins

To modify a skin, first create a copy of one of the skins that comes with the SmartGWT SDK, then modify the copy. Full instructions are provided in Chapter 9 of the ${isc.DocUtils.linkForDocNode('QuickStartGuide', 'QuickStart Guide')}.

Locating Skinning Properties

Starting from the name of the component

Given a SmartGWT component that you want to skin, use the search feature of the SmartGWT Reference to locate it, and open the "Instance APIs" tab.

TIP: the Instance APIs tab allows you to search within just the current class, limit the display to just properties or methods, and sort by type.

Starting from a running example

Open the Developer Console and use the Watch Tab to locate the component or subcomponent you want to skin, then locate it in the documentation, as above.

If you don't find the component in the documentation, it may be a custom component specific to your organization. To find the base SmartGWT component for a component named "MyComponent", use the following code to find out the name of the superclass:

     isc.MyComponent.getSuperClass().getClassName()
 
Repeat this until you arrive at a SmartGWT built-in class. You can execute this code in the "Eval JS" area of the Results pane of the Developer Console.

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

Image URLs in SmartGWT

Properties that refer to images by URL, such as src and icon, are specially interpreted in SmartGWT 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 SmartGWT component is not assumed to be relative to the current page. See com.smartgwt.client..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 SmartGWT components are specified in load_skin.js via JavaScript, using calls to com.smartgwt.client..Class#addProperties and com.smartgwt.client..Class#changeDefaults. For example, the load_skin.js file from the "SmartGWT" sample skin includes the following code to establish the media used by minimizeButton:

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

Specifying Image Sizes

Many SmartGWT 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, SmartGWT 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 SmartGWT

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

CSS borders, margins and padding applied to SmartGWT components can be treated as purely visual properties with no effect on sizing or layout. Unlike HTML elements, a SmartGWT 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, SmartGWT skinning requires only novice-level familiarity with CSS, as CSS is used principally for colors and fonts. See com.smartgwt.client..CSSStyleName 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.

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

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 SmartGWT 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. EdgedCanvas is also used to construct dropshadows, which can be enabled on any component via showShadow.

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 com.smartgwt.client.util.isc#defineClass. For example:

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