XML Definitions Configuration

This section provides an overview of the Tiles XML configuration mechanism.

    <?xml version="1.0" encoding="UTF-8"?>

    <!DOCTYPE tiles-definitions PUBLIC
       "-//Apache Software Foundation//DTD Tiles Configuration 1.4//EN"
       "http://struts.apache.org/dtds/tiles-config_1_4.dtd">

    <tiles-definitions>

    <definition name="mainLayout" path="/common/layouts/classicLayout.jsp">
        <put name="title"  value="Sample Page Title" />
        <put name="header" value="/common/header.jsp" />
        <put name="menu"   value="mainMenu" />
        <put name="footer" value="/common/footer.jsp" />
        <put name="body"   value=".portal.body" />
    </definition>

    <definition name="mainMenu" path="/common/layouts/vboxLayout.jsp" >
        <putList name="list" >
            <add value="menu.links" />
            <add value="menu.taglib.references" />
            <add value="menu.printer.friendly" />
            <add value="menu.old.documents" />
      </putList>
    </definition>

    <definition name="aPage" extends="mainLayout">
        <put name="title"  value="Another Title" />
        <put name="body"   value="aPage.body" />
    </definition>

    </tiles-definitions>
    

The XML example above is representative of real-life usage. But it does not illustrate every aspect of the Tiles configuration file. We will now examine each portion of the configuration file in detail.

Definitions

A definition can define a template or a "tile." If it is defining a template its path will point to a JSP page that contains the layout of the template. The definition's attributes will point to various sections of the template that can be either used as is or overriden.

If a definition defines a tile it may refer to a named portion of a page such as the header, or it may refer to a reusable component, such as a customer form.

A template definition would be similar to the mainLayout definition above. It defines a template containing a layout and 5 named attributes. The "title" attribute is a String attribute that can be overridden. The "header" and "footer" attributes are pages that are included in the template. The "menu" and "body" attributes are definitions that would be defined elsewhere in the file.

A tile definition would be similar to the mainMenu definition above. This configures a menu tile that can be included anywhere on a page.

The following list shows the attributes of the Definition tag.

• controllerClass The fully qualified Java class name of the controller subclass to call immediately before the tiles is inserted. Only one of controllerClass or controllerUrl should be specified.
• controllerUrl The context-relative path to the resource used as controller called immediately before the tiles is inserted. Only one of controllerClass or controllerUrl should be specified.
• extends Name of a definition that is used as ancestor of this definition. All attributes from the ancestor are available to the new definition. Any attribute inherited from the ancestor can be overloaded by providing a new value.
• name (Required). The unique identifier for this definition.
• page Same as path.
• path The context-relative path to the resource used as tiles to insert. This tiles will be inserted and a tiles context containing appropriate attributes will be available.
• role Security role name that is allowed access to this definition object. The definition is inserted only if the role name is allowed.
• template Same as path. For compatibility with the template tag library.

Put

The "put" element describes an attribute of a definition. Definition attributes have a name and a value. The value can be specified as an xml attribute, or in the body of the <put>tag.

A definition attribute can be one of three basic types. It can be a String value that is inserted into a page. This value can be a simple String specified in the "value" attribute of the "put" tag or it can be complex HTML content specified as the body of the "put" tag. The attribute can also be the URL of a page to be included in another page. Thirdly, it can be the name of another Tiles definition to be inserted in a page.

The following list shows the attributes of the Put tag.

• content Same as value.
• direct Same as type="string".
• name (Required) The unique identifier for this put.
• type The type of the value. Can be: string, page, template or definition. By default, no type is associated to a value. If a type is associated, it will be used as a hint to process the value when the attribute will be used in the inserted tiles. A type of "string" indicates that the value should be inserted directly into the content of the page. A type of "page" or "template" indicates that the value is the URL of a page that should be included. A type of "definition" indicates that the value is the name of another Tiles definition that should be included in the page.
• value The value associated to this tiles attribute. The "value" attribute is required if the value is not specified in the content of the "put" tag.

PutList

The PutList tag is similar to the Put tag except that it allows you to specify a list of attributes for a Tiles Definition. It specifies an attribute that is a Java List containing any kind of values. In the config file, the list elements are specified by nested add, item or putList elements.

The following list shows the attributes of the PutList tag.

• name (Required). The unique identifier for this put list.

Add

The add element describes an element of a list. It is similar to the put element except that it is only used in lists. It supports the following attributes.

• content Same as value.
• direct Same as type="string".
• name (Required) The unique identifier for this put.
• type The type of the value. Can be: string, page, template or definition. By default, no type is associated to a value. If a type is associated, it will be used as a hint to process the value when the attribute will be used in the inserted tiles. A type of "string" indicates that the value should be inserted directly into the content of the page. A type of "page" or "template" indicates that the value is the URL of a page that should be included. A type of "definition" indicates that the value is the name of another Tiles definition that should be included in the page.
• value The value associated to this tiles attribute. The "value" attribute is required if the value is not specified in the content of the "add" tag.

Bean

The bean element describes an element of a list. It causes a bean of the specified java classtype to be created. This bean is initialized with appropriate nested set-property elements.

• classtype (Required). The fully qualified classname for this bean.

Set-Property

The set-property element specifies the method name and initial value of a bean property. When the object representing the surrounding element is instantiated, the accessor for the indicated property is called and passed the indicated value.

• property (Required). Name of the JavaBeans property whose setter method will be called.
• value (Required). String representation of the value to which this property will be set, after suitable type conversion

Item

The item element describes an element of a list. It causes a bean of the specified classtype to be created and added to the list. Each bean can contain different properties: value, link, icon, tooltip. These properties are to be interpreted by the jsp page using them.

Using the Item element is a good way to build menus. By default the bean is of type org.apache.struts.tiles.beans.SimpleMenuItem. The following attributes are supported.

• classtype The fully qualified classtype for this bean. If specified, the classtype must be a subclass of the interface org.apache.struts.tiles.beans.MenuItem.
• icon Link to the icon for the menu item.
• link (Required). URL of the location pointed to by the menu item.
• tooltip Alternative text describing the menu item.
• value (Required) The String to be displayed on the menu.

Description

The description element contains descriptive (paragraph length) text about the surrounding element, suitable for use in GUI tools.

Display-Name

The display-name element contains a short (one line) description of the surrounding element, suitable for use in GUI tools.

Icon

The icon element contains a small-icon and large-icon element which specify the location, relative to the Tiles configuration file, for small and large images used to represent the surrounding element in GUI tools.

Large-Icon

The large-icon element specifies the location, relative to the Struts configuration file, of a resource containing a large (32x32 pixel) icon image.

Small-Icon

The large-icon element specifies the location, relative to the Struts configuration file, of a resource containing a large (16x16 pixel) icon image.

Sample Book Chapters

• Developing applications with Tiles by Cedric Dumoulin and Ted Husted. Sample chapter from Struts in Action; available as a free download (PDF).
• Using Tiles Sample beta chapter from Programming Jakarta Struts; available as a free download (PDF).

Articles

• Open Source-Based Portal-Lite by Scott Nelson. Using Tiles to prototype a portal site.
• Improve performance by caching Struts and Tiles applications by Nirmala Kodali. Implementing caching under WebSphere.
• Introduction to Struts and Tiles with a working example by Sascha Wolski.
• Skin Web applications using Xkins by Guillermo Meyer. Use skinning with Struts and Tiles.
• Reuse Tiles and Simplify UI by James Holmes. Howto article in Oracle Magazine.
• Struts and Tiles aid component-based development by Wellie Chao.
• UI design with Tiles and Struts by Prakash Malani.
• Tiles Advanced Features by Cedric Dumoulin.

For a comprehensive listing of Struts resources, visit Struts Central.