Package org.apache.struts.tiles

The Tiles taglib and framework allows building web pages by assembling reusable pieces of pages, called Tiles.

Interface Summary

AttributeDefinition Attribute definition used in a component definition.
ComponentDefinitionsFactory Component repository interface.
Controller A controller is a piece of code called before rendering a jsp page.
DefinitionsFactory Tiles Definition factory.

Class Summary

ActionController Struts wrapper implementation of Controller.
ComponentContext Component context.
ComponentDefinition Definition of a template / component attributes.
ControllerSupport Basic implementation of Controller.
DefinitionAttribute Attribute representing a Component Definition.
DefinitionNameAttribute Component attribute.
DefinitionsFactoryConfig A TilesFactoryConfig object hold configuration attributes for a tile definition factory.
DefinitionsFactoryException Exception thrown when an error occurs while the factory tries to create a new instance mapper.
DefinitionsUtil Utilities class for definitions factory.
DefinitionsUtil.ServletPropertiesMap Inner class.
DirectStringAttribute Component attribute.
FactoryNotFoundException Exception thrown when definitions factory is not found.
NoSuchDefinitionException Exception thrown when a definition is not found.
PathAttribute Component attribute.
TilesException Root class for all Tiles-exceptions.
TilesPlugin Tiles Plugin used to initialize Tiles.
TilesRequestProcessor RequestProcessor contains the processing logic that the Struts controller servlet performs as it receives each servlet request from the container.
TilesUtil Class containing utility methods for Tiles.
TilesUtilImpl Default implementation of TilesUtil.
TilesUtilStrutsImpl TilesUtil implementation for Struts 1.1 with one single factory.
TilesUtilStrutsModulesImpl Implementation of TilesUtil for Struts multi modules.
UntypedAttribute Common implementation of attribute definition.
UrlController Tiles controller including a local URL.
The Tiles taglib and framework allows building web pages by assembling reusable pieces of pages, called Tiles. A Tiles is usually a simple JSP page. TagLib Tiles UML

Introduction

The Tiles framework allows building pages by assembling reusable Tiles. As an example, the page in the next figure can be build by assembling a header, a footer, a menu and a body.

doc-files/image001

definition name

Simple Examples

Insert a JSP page

<tiles:insert page="/layouts/commonLayout.jsp" flush="true" />

This example inserts the specified page in place of the tag. The page attribute is any valid URL pointing to a resource inside the current site.

Insert a Tiles passing some attributes

<tiles:insert page="/layouts/classicLayout.jsp" flush=&quot;true">
<tiles:put name="title"  value="Page Title" />
<tiles:put name="header" value="/common/header.jsp" />
<tiles:put name="footer" value="/common/footer.jsp" />
<tiles:put name="menu"   value="/common/menu.jsp" />
<tiles:put name="body"   value="/tiles/mainBody.jsp" />
</tiles:insert>

This example inserts the specified page, passing it the attributes. Attributes are stored in a Tiles context which is passed to the inserted pag and can then be accesssed by their names.

Retrieve an attribute value as String

<tiles:getAsString name="title" />

This example retrieves the value of the attribute "title" and prints it as a String in the current output stream. The method toString() is applied on the attribute value, allowing to pass any kind of object as value.

Insert Tiles referenced by an attribute

<tiles:insert attribute='menu' />

This inserts the Tiles referenced by the attribute "menu" value. The specified attribute value is first retrieved from current Tiles's context, and then the value is used as a page target to insert.

Classic Layout

This example is a layout assembling a page in the classic header-footer-menu-body fashion.

<%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %>
<HTML>
<HEAD>
<link rel="stylesheet" href="<%=request.getContextPath()%>/layouts/stylesheet.css" 
type="text/css"/>
<title><tiles:getAsString name="title"/></title>
</HEAD>
<body>
<table border="0" width="100%" cellspacing="5">
<tr>
<td colspan="2"><tiles:insert attribute="header" /></td>
</tr>
<tr>
<td width="140" valign="top">
<tiles:insert attribute='menu' />
</td>
<td valign="top"  align="left">
<tiles:insert attribute='body' />
</td>
</tr>
<tr>
<td colspan="2">
<tiles:insert attribute="footer" />
</td>
</tr>
</table>
</body>
</html>

The layout is declared in a JSP page (ex: /layouts/classicLayout.jsp). It can be used in conjunction with the tag described in "Insert a page passing some attributes".

Definitions

A definition associates a logical name with the URL of a Tiles to be inserted and some attribute values. A definition doesn't insert the Tiles. This is done later using the definition name. A definition name can be inserted as often as you want in your site, making it easy to reuse a Tiles.

A definition can extend another definition and overload some attributes or add new ones. This makes easy factorization of definitions differing by some attributes. For example, you can define a master definition declaring the main header, menu, footer, and a default title. Then let each of your page definitions extend this master definition and overload the title and the body.

Definitions can be declared in a JSP page, or in one or more centralized files. To enable the definitions from centralized files, you need to initialize the "definitions factory&&quot; which will parse the definitions from the files and provide them to the Tiles framework.

Enabling Definition Factory

To enable Tiles definitions described in one or more files, you need to write these files and to initialize the definition factory.

Initialization is different depending on the Struts version you use, or if you do not use Struts at all.

Struts1.1

Use the Tiles plug-in to enable Tiles definitions. This plug-in creates the definition factory and passese it a configuration object populated with parameters. Parameters can be specified in the web.xml file or as plug-in parameters. The plug-in first reads parameters from web.xml, and then overloads them with the ones found in the plug-in. All parameters are optional and can be omitted. The plug-in should be declared in each struts-config file:

<plug-in className=&&quot;org.apache.struts.tiles.TilesPlugin&&quot; >
<set-property property=&&quot;definitions-config&&quot; 
value=&&quot;/WEB-INF/tiles-defs.xml,
/WEB-INF/tiles-tests-defs.xml,/WEB-INF/tiles-tutorial-defs.xml,
/WEB-INF/tiles-examples-defs.xml&&quot; />
<set-property property=&&quot;moduleAware&&quot; value=&&quot;true&&quot; />
<set-property property=&&quot;definitions-parser-validate&&quot; value=&&quot;true&&quot; />
</plug-in>
  • definitions-parser-validate: (optional)
    • Specify if XML parser should validate the Tiles configuration file
      • true : validate. DTD should be specified in file header (default)
      • false : no validation
    • moduleAware: (optional)
      • Specify if the Tiles definition factory is module aware. If true (default), there will be one factory for each Struts module. If false, there will be one common factory for all module. In this later case, it is still needed to declare one plugin per module. The factory will be initialized with parameters found in the first initialized plugin (generally the one associated with the default module).
        • true : Tiles framework is module aware
        • false :Tiles framework has one single factoy shared among modules (default)
      • tilesUtilImplClassname: (optional - for advanced user)
        • Specify The classname of the TilesUtil implementation to use. The specified class should be a subclass of TilesUtilStrutsImpl. This option disable the moduleAware option.
          Specifying &&quot;TilesUtilStrutsImpl&&quot; is equivalent to moduleAware = false.
          Specifying &&quot;TilesUtilStrutsModuleImpl&&quot; is equivalent to moduleAware = true. This option is taken into account only once, when it is first encountered. To avoid problems, it is advice to specify the same values in all TilesPlugin declaration.
      • The TilesPlugin class creates one definition factory for each struts module.

        If the flag moduleAware is false, only one shared factory is created for all modules. In this later case, the factory is initialized with parameters found in the first plugin. The plugins should be declared in all modules, and the moduleAware flag should be the same for the entire application.

        Paths found in Tiles definitions are relative to the main context.

        You don't need to specify a TilesRequestProcessor, this is automatically done by the plug-in. If, however, you want to specify your own RequestProcessor, it should extend the TilesRequestProcessor. The plug-in checks this constraint.

        Struts1.0.x

        You need to use a special servlet extending the Struts servlet. This is specified in the web.xml file of your application:

        <servlet>
        <servlet-name>action</servlet-name>
        <servlet-class>org.apache.struts.tiles.ActionComponentServlet</servlet-class>   
        <!-- Tiles Servlet parameter 
        Specify configuration file names. There can be several comma 
        separated file names
        --> 	
        <init-param>
        <param-name>definitions-config</param-name>
        <param-value>/WEB-INF/tiles-defs.xml</param-value>
        </init-param>
        <!-- Tiles Servlet parameter 
        Specify if XML parser should validate the Tiles configuration file(s).
        true : validate. DTD should be specified in file header.
        false : no validation
        --> 	
        <init-param>
        <param-name>definitions-parser-validate</param-name>
        <param-value>true</param-value>
        </init-param>
        ...
        </servlet>
        

        Without Struts

        Tiles can be used without Struts. To initialize the definition factory, you can use the provided servlet. Declare it in the web.xml file of your application:

        <servlet>
        <servlet-name>action</servlet-name>
        <servlet-class>org.apache.struts.tiles.TilesServlet</servlet-class>
        <init-param>
        <param-name>definitions-config</param-name>
        <param-value>/WEB-INF/tiles-defs.xml</param-value>
        </init-param>
        <init-param>
        <param-name>definitions-parser-validate</param-name>
        <param-value>true</param-value>
        </init-param>
        ...
        

        The parameters are the same as for Struts1.1 or 1.0.

        Definition File Syntax

        The definition file syntax can be found in the tiles-config_1_1.dtd file.

        Following is a simple example:

        <!DOCTYPE tiles-definitions PUBLIC
        &&quot;-//Apache Software Foundation//DTD Tiles Configuration//EN&&quot;
        &&quot;http://jakarta.apache.org/struts/dtds/tiles-config_1_1.dtd&&quot;>
        <!-- Definitions for Tiles documentation   -->
        <tiles-definitions>
        <!-- ========================================================== -->
        <!-- Master definition                                          -->
        <!-- ========================================================== -->
        <!-- Main page layout used as a root for other page definitions -->
        <definition name=&&quot;site.mainLayout&&quot; path=&&quot;/layouts/classicLayout.jsp&&quot;>
        <put name=&&quot;title&&quot;  value=&&quot;Tiles Blank Site&&quot; />
        <put name=&&quot;header&&quot; value=&&quot;/tiles/common/header.jsp&&quot; />
        <put name=&&quot;menu&&quot;   value=&&quot;site.menu.bar&&quot; />
        <put name=&&quot;footer&&quot; value=&&quot;/tiles/common/footer.jsp&&quot; />
        <put name=&&quot;body&&quot;   value=&&quot;/tiles/body.jsp&&quot; />
        </definition>
        <!-- ========================================================== -->
        <!-- Index page definition                                      -->
        <!-- ========================================================== -->
        <!-- This definition inherits from the main definition.
        It overloads the page title and the body used.
        Use the same mechanism to define new pages sharing common 
        properties (here header, menu, footer, layout)
        -->
        <definition name=&&quot;site.index.page&&quot; extends=&&quot;site.mainLayout&&quot; >
        <put name=&&quot;title&&quot;  value=&&quot;Tiles Blank Site Index&&quot; />
        <put name=&&quot;body&&quot;   value=&&quot;/tiles/body.jsp&&quot; />
        </definition>
        </tiles-definition>
        

        Debugging

        To debug a page made of Tiles, you can use following advices:


        Copyright B) 2000-2007 - The Apache Software Foundation