Visual User Interface Design with Eclipse

7.4. Structure of a Visually Editable Component

A component created by the wizard and later managed by the visual editor has a very specific structure that allows you to insert your user interface logic in the component while keeping a minimal amount of code off-limits.You need to know what you can edit yourself and what exactly is managed by the editor. The managed member variables and methods are marked with the AutoGenerated annotation, as you can see later.

A visually editable component consists of:

•Member variables containing sub-component references

•Sub-component builder methods

•The constructor

The structure of a composite component is hierarchical, a nested hierarchy of layout components containing other layout components as well as regular components. The root layout of the component tree, or the composition root of the CustomComponent, is named mainLayout. See Section 5.22, “Component Composition with CustomComponent” for a detailed description of the structure of custom (composite) components.

7.4.1. Sub-Component References

The CustomComponent class will include a reference to each contained component as a member variable. The most important of these is the mainLayout reference to the composition root layout. Such automatically generated member variables are marked with the @AutoGenerated annotation. They are managed by the editor, so you should not edit them manually, unless you know what you are doing.

A composite component with an AbsoluteLayout as the composition root, containing a Button and a Table would have the references as follows:

public class MyComponent extends CustomComponent {

@AutoGenerated

private AbsoluteLayout mainLayout; @AutoGenerated

private Button myButton; @AutoGenerated

private Table myTable;

...

The names of the member variables are defined in the component properties panel of the visual editor, in the Component name field, as described in the section called “Basic Properties”. While you can change the name of any other components, the name of the root layout is always mainLayout. It is fixed because the editor does not make changes to the constructor, as noted in Section 7.4.3, “The Constructor”. You can, however, change the type of the root layout, which is an AbsoluteLayout by default.

Certain typically static components, such as the Label label component, will not have a reference as a member variable. See the description of the builder methods below for details.

220	Structure of a Visually Editable Component

Visual User Interface Design with Eclipse

7.4.2. Sub-Component Builders

Every managed layout component will have a builder method that creates the layout and all its contained components. The builder puts references to the created components in their corresponding member variables, and it also returns a reference to the created layout component.

Below is an example of an initial main layout:

@AutoGenerated

private AbsoluteLayout buildMainLayout() {

//common part: create layout mainLayout = new AbsoluteLayout();

//top-level component properties setHeight("100.0%"); setWidth("100.0%");

return mainLayout;

}

Notice that while the builder methods return a reference to the created component, they also write the reference directly to the member variable. The returned reference might not be used by the generated code at all (in the constructor or in the builder methods), but you can use it for your purposes.

The builder of the main layout is called in the constructor, as explained in Section 7.4.3, “The Constructor”. When you have a layout with nested layout components, the builders of each layout will call the appropriate builder methods of their contained layouts to create their contents.

7.4.3. The Constructor

When you create a new composite component using the wizard, it will create a constructor for the component and fill its basic content.

public MyComponent() { buildMainLayout(); setCompositionRoot(mainLayout);

// TODO add user code here

}

The most important thing to do in the constructor is to set the composition root of the CustomComponent with the setCompositionRoot() (see Section 5.22, “Component Composition with CustomComponent” for more details on the composition root). The generated constructor first builds the root layout of the composite component with buildMainLayout() and then uses the mainLayout reference.

The editor will not change the constructor afterwards, so you can safely change it as you want. The editor does not allow changing the member variable holding a reference to the root layout, so it is always named mainLayout.

Sub-Component Builders

221

222

Chapter 8

Themes

8.1. Overview ................................................................................................	223
8.2. Introduction to Cascading Style Sheets .................................................	225
8.3. Syntactically Awesome Stylesheets (Sass) ...........................................	230
8.4. Creating and Using Themes ..................................................................	232
8.5. Creating a Theme in Eclipse ..................................................................	236

This chapter provides details about using and creating themes that control the visual look of web applications. Themes are created using Sass, which is an extension of CSS (Cascading Style Sheets), or with plain CSS. We provide an introduction to CSS, especially concerning the styling of HTML by element classes.

8.1. Overview

Vaadin separates the appearance of the user interface from its logic using themes. Themes can include Sass or CSS style sheets, custom HTML layouts, and any necessary graphics. Theme resources can also be accessed from application code as ThemeResource objects.

Custom themes are placed under the VAADIN/themes/ folder of the web application (under WebContent in Eclipse). This location is fixed -- the VAADIN folder contains static resources that are served by the Vaadin servlet. The servlet augments the files stored in the folder by resources found from corresponding VAADIN folders contained in JARs in the class path. For example, the built-in themes are stored in the vaadin-themes.jar.

Figure 8.1, “Contents of a Theme” illustrates the contents of a theme.

Book of Vaadin

223

Themes

Figure 8.1. Contents of a Theme

The name of a theme folder defines the name of the theme. The name is used in the @Theme annotation that sets the theme. A theme must contain either a styles.scss for Sass themes, or styles.css stylesheet for plain CSS themes, but other contents have free naming. We recommend that you have the actual theme content in a SCSS file named after the theme, such as mytheme.scss, to make the names more unique.

We also suggest a convention for naming the folders as img for images, layouts for custom layouts, and css for additional stylesheets.

Custom themes that use an existing complete theme need to inherit the theme. See Section 8.4.4, “Built-in Themes” and Section 8.4.6, “Theme Inheritance” for details on inheriting a theme. Copying and modifying a complete theme is also possible, but it may need more work to maintain if the modifications are small.

You use a theme by specifying it with the @Theme annotation for the UI class of the application as follows:

@Theme("mytheme")

public class MyUI extends UI { @Override

protected void init(VaadinRequest request) {

...

}

}

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 6.14, “Custom Layouts” for details.

224

Overview