User Guide
One Tiles is installed and the XML Definitions are being loaded,
the better part of using Tiles is managing the XML Definitions.
XML Definitions Configuration
This section provides an overview of the Tiles XML configuration mechanism.
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE tiles-definitions PUBLIC
"-//Apache Software Foundation//DTD Tiles Configuration 1.3//EN"
"http://struts.apache.org/dtds/tiles-config_1_3.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.
