Chapter 6. Themes

This chapter provides details about using and creating themes that control the visual look of web applications using Cascading Style Sheets (CSS) and other theme resources. We provide an introduction to CSS, especially concerning the styling of HTML by element classes.

6.1. Overview

IT Mill Toolkit separates the appearance of the user interface from its logic using themes. Themes can include CSS style sheets, custom HTML layouts, and any necessary graphics used by them. Theme resources can also be accessed from an application with ThemeResource objects.

You place custom themes under the WebContents/ITMILL/themes/ folder of the web application. This location is fixed -- the folder "ITMILL" specifies that these are (static) resources specific to IT Mill Toolkit. The folder should normally contain also the built-in default theme, although you can let it be loaded dynamically from the Toolkit JAR (even though that is somewhat inefficient). Figure 6.1, “Theme Contents” illustrates the contents of a theme.

Figure 6.1. Theme Contents

Theme Contents

The name of a theme folder defines the name of the theme. The name is used in the setTheme() call. A theme must contain the styles.css stylesheet, but other contents have free naming. We suggest a convention for naming the folders as img for images, layouts for custom layouts, and css for additional stylesheets.

Custom themes must inherit the default theme (unless you just copy the default theme and use it as a template for efficiency reasons). See the section called “Default Theme” and Section 6.3.3, “Theme Inheritance” for details on inheriting the default theme.

You use a theme with a simple setTheme() method call for the Application object as follows:

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

An application can use different themes for different users and switch between themes during execution. For smaller changes, a theme can contain alternate styles for user interface components, which can be changed as needed.

In addition to style sheets, a theme can contain HTML templates for custom layouts used with CustomLayout. See Section 5.4, “Custom Layouts” for details.

Resources provided in a theme can also be accessed using the ThemeResource class, as described in Section 3.5.4, “Theme Resources”. This allows using theme resources, such as images, for example in Embedded objects and other objects that allow inclusion of images using resources.