6.3. Creating and Using Themes

Custom themes are placed in ITMILL/themes folder of the web application (in the WebContent directory) as illustrated in Figure 6.1, “Theme Contents”. This location is fixed. You need to have a theme folder for each theme you use in your application, although applications rarely need more than a single theme. For example, if you want to define a theme with the name mytheme, you will place it in folder ITMILL/themes/mytheme.

A custom theme must also inherit the default theme, as shown in the example below:

@import "../default/styles.css";

body {
    background: yellow;
}

See the section called “Default Theme” and Section 6.3.3, “Theme Inheritance” below for details on inheriting the default theme and theme inheritance generally.

6.3.1. Styling Standard Components

Each user interface component in IT Mill Toolkit has a set of style classes that you can use to control the appearance of the component. Some components have additional elements that also allow styling.

The following table lists the style classes of all client-side components of IT Mill Toolkit. Notice that a single server-side component can have multiple client-side implementations. For example, a Button can be rendered on the client side either as a regular button or a check box, depending on the switchMode attribute of the button. For details regarding the mapping to client-side components, see Section 8.4, “Defining a Widget Set”. Each client-side component type has its own style class and a number of additional classes that depend on the client-side state of the component. For example, a text field will have i-textfield-focus class when mouse pointer hovers over the component. This state is purely on the client-side and is not passed to the server.

Some client-side components can be shared by different server-side components. There is also the IUnknownComponent, which is a component that indicates an internal error in a situation where the server asked to render a component which is not available on the client-side.

Table 6.1. Default CSS Style Names of IT Mill Toolkit Components

Server-Side ComponentClient-Side WidgetCSS Class NameState Indicators
ButtonIButtoni-button 
ICheckBox  
CustomComponentICustomComponenti-customcomponent 
CustomLayoutICustomLayout  
DateFieldIDateFieldi-datefield 
ICalendari-datefield-entrycalendar 
IDateFieldCalendari-datefield-calendar 
IPopupCalendari-datefield-calendar 
ITextualDate i-readonly, i-textfield-error
EmbeddedIEmbedded- 
FormIFormi-form 
FormLayoutIFormLayout- 
GridLayoutIGridLayout- 
LabelILabeli-label 
LinkILinki-linkreadonly, enabled
OptionGroupIOptionGroupi-select-optiongroup 
HorizontalLayoutIOrderedLayouti-orderedlayout 
VerticalLayoutIOrderedLayouti-orderedlayout 
PanelIPaneli-panel (i-panel-caption, i-panel-content, i-panel-deco) 
Select    
IListSelecti-listselect   
IFilterSelecti-filterselect    
SliderISlideri-slider   
SplitPanelISplitPanel-   
ISplitPanelHorizontal-   
ISplitPanelVertical-   
TableIScrollTablei-table   
ITablePagingi-table (i-table-tbody)   
TabSheetITabSheeti-tabsheet (i-tabsheet-content, i-tablsheet-tabs)   
TextFieldITextFieldi-textfieldi-textfield-focus  
ITextArea    
IPasswordField    
TreeITreei-tree (i-tree-node-selected)   
TwinColSelectITwinColSelecti-select-twincol (i-select-twincol-selections, i-select-twincol-buttons, i-select-twincol-deco)   
UploadIUpload-   
WindowIWindowi-window   
-CalendarEntry-   
-CalendarPaneli-datefield-calendarpanel   
-ContextMenui-contextmenu   
-IUnknownComponentitmtk-unknown (itmtk-unknown-caption)   
-IView-   
-Menubargwt-MenuBar   
-MenuItemgwt-MenuItem   
-Timei-datefield-time (i-select)   

Style names of sub-components are shown in parentheses.

Default Theme

The default theme is provided in the ITMILL/themes/default/styles.css stylesheet in the IT Mill Toolkit library JAR. This stylesheet is a compilation of the separate stylesheets for each component in the corresponding subdirectory.

Notice that the default theme included in the IT Mill Toolkit library JAR is served dynamically from the JAR by the servlet. Serving the theme statically by the web server is much more efficient. You only need to extract the ITMILL/ directory from the JAR under your WebContent directory. Just make sure to update it if you upgrade to a newer version of IT Mill Toolkit.

Creation of a default theme of custom GWT widgets is detailed in Section 8.2.3, “Styling GWT Widgets”.

6.3.2. Using Themes

Using a theme is simple, you only need to set the theme with setTheme().

Defining the appearance of a user interface component is fairly simple. First, you create a component and add a custom style name for it with addStyleName(). Then you write the CSS element that defines the formatting for the component.

6.3.3. Theme Inheritance

When you define your own theme, you will need to inherit the default theme (unless you just copy the default theme).

Inheritance in CSS is done with the @import statement. In the typical case where you define your own theme, you inherit the default theme as follows:

@import "../default/styles.css";

body {
    background: yellow;
}

You can even create a deep hierarchy of themes by inheritance. Such a solution is often useful if you have some overall theme for your application and a slightly modified theme for different user classes. You can even make it possible for each user to have his or her own theme.

For example, let us assume that we have the base theme of an application with the name myapp and a specific myapp-student theme for users with the student role. The stylesheet of the base theme would be located in themes/myapp/styles.css. We can then "inherit" it in themes/myapp-student/styles.css with a simple @import statement:

@import "../myapp/styles.css";

body {
    background: green;
}

This would make the page look just as with the base theme, except for the green background. You could use the theme inheritance as follows:

public class MyApplication extends com.itmill.toolkit.Application {
    
    public void init() {
        setTheme("myapp");
        ...
    }

    public void login(User user) {
        if (user.role == User.ROLE_STUDENT)
            setTheme("myapp-student");
        ...
    }

    public void logout() {
        setTheme("myapp");
        ...
    }
}