5.4. Custom Layouts

While it is possible to create almost any typical layout with the standard layout components, it is sometimes best to separate the layout completely from code. With the CustomLayout component, you can write your layout as a template in XHTML that provides locations of any contained components. The layout template is included in a theme. This separation allows the layout to be designed separately from code, for example using WYSIWYG web designer tools such as Adobe Dreamweaver.

A template is a HTML file located under layouts folder under a theme folder under the WebContent/ITMILL/themes/ folder, for example, WebContent/ITMILL/themes/themename/layouts/mylayout.html. (Notice that the root path WebContent/ITMILL/themes/ for themes is fixed.) A template can also be provided dynamically from an InputStream, as explained below. A template includes <div> elements with a location attribute that defines the location identifier. All custom layout HTML-files must be saved using UTF-8 character encoding.

<table width="100%" height="100%">
  <tr height="100%">
    <td>
      <table align="center">
        <tr>
          <td align="right">User&nbsp;name:</td>
          <td><div location="username"></div></td>
        </tr>
        <tr>
          <td align="right">Password:</td>
          <td><div location="password"></div></td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <td align="right" colspan="2"><div location="okbutton"></div></td>
  </tr>
</table>

The client-side engine of IT Mill Toolkit will replace contents of the location elements with the components. The components are bound to the location elements by the location identifier given to addComponent(), as shown in the example below.

// Have a Panel where to put the custom layout.
final Panel panel = new Panel("Login");
panel.setSizeUndefined();
main.addComponent(panel);

// Create the custom layout from the "layoutname.html" template.
final CustomLayout custom = new CustomLayout("layoutname");
custom.addStyleName("customlayoutexample");

// Use it as the layout of the Panel.
panel.setLayout(custom);

// Create a few components and bind them to the location tags
// in the custom layout.
TextField username = new TextField();
custom.addComponent(username, "username");

TextField password = new TextField();
custom.addComponent(password, "password");

final Button ok = new Button("Login");
custom.addComponent(ok, "okbutton");

The resulting layout is shown below in Figure 5.12, “Example of a Custom Layout Component”.

Figure 5.12. Example of a Custom Layout Component

Example of a Custom Layout Component

You can use addComponent() also to replace an existing component in the location given in the second parameter.

In addition to a static template file, you can provide a template dynamically with the CustomLayout constructor that accepts an InputStream as the template source. For example:

new CustomLayout(new ByteArrayInputStream("<b>Template</b>".getBytes()));

or

new CustomLayout(new FileInputStream(file));