Programming Jakarta Struts, 2nd Edition [Electronic resources]

14.2 Installing and Configuring Tiles

Before you can use the Tiles framework, you must ensure that it's installed and properly configured within your web container. The Tiles framework is not dependent on any specific container. You will need to obtain the required files and ensure that they are placed into their proper directories within the web application.

14.2.1 Downloading Tiles

The Tiles framework is included with the Struts distribution. It previously was included in the contrib folder, but it is now part of the core distribution. You also can find the latest source and binary distribution, as well as other useful information, at http://www.lifl.fr/~dumoulin/tiles/indexl.

14.2.2 Installing the Required JARs and Misc Files

With earlier versions of Struts and Tiles, each was contained within its own JAR file. With Struts 1.1, Tiles components have now been integrated into struts.jar. As with all other things Struts, you will also need the standard commons JAR files installed in the WEB-INF/lib directory.

You will also need to install the Tiles TLD file, struts-tiles.tld, in the WEB-INF directory for the application.

You should put the tiles-config_1_1.dtd file in the WEB-INF directory, too. This DTD is used to validate Tiles definition files, which we'll discuss later in this chapter.

14.2.3 Adding the Tiles Tag Library

As with any other JSP tag library, you must add the Tiles library to the web application deployment descriptor before you can use it. Add the following taglib element to the web.xml file:

<taglib>
<taglib-uri>/WEB-INF/struts-tiles.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-tiles.tld</taglib-location>
</taglib>

There should already be taglib elements present if you are using any of the standard Struts tag libraries. Each page that needs to use the Tiles tag library must include the following line at the top:

<%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %>

14.2.4 Configuring Tiles to Work with Struts

The Tiles framework can be used with or without Struts. Depending on how you use it, there are several options for configuring it for a web application. Because this book is about Struts, we'll focus on how to use it within a Struts application.

The Tiles plug-in is really necessary only if you are planning on using Tiles definitions. It is possible to use the Tiles libraries with Struts without configuring the plug-in. However, it doesn't hurt to configure it, and it may save you time later if you decide to use definitions.

To add the Tiles plug-in to a Struts application, add the following plug-in element to the Struts configuration file:

<plug-in className="org.apache.struts.tiles.TilesPlugin" >
<set-property property="definitions-config" value="/WEB-INF/struts-tiles-defs.xml" />
<set-property property="definitions-debug" value="2" />
<set-property property="definitions-parser-details" value="2" />
<set-property property="definitions-parser-validate" value="true" />
<set-property property="moduleAware" value="true" />
</plug-in>

Within the plug-in element, you can specify one or more set-property elements to pass additional parameters to the Plugin class. The definitions-config initialization parameter specifies the XML file or files containing Tile definitions. If multiple filenames are used, they must be comma-separated.

14.2.4.1 The definitions-debug property

The definitions-debug parameter specifies the debug level. The allowed values are:

0

No debug information is written out.

1

Partial debug information is provided.

2

Full debug information is provided.

The default value is 0.

14.2.4.2 The definitions-parser-details property

The definitions-parser-details parameter indicates the required level of debugging information while the definition files are being parsed. This value is passed to the Commons Digester. The allowed values are the same as those for the definitions-debug parameter. The default value is 0.

14.2.4.3 The definitions-parser-validate property

The definitions-parser-validate parameter specifies whether the parser should validate the Tiles configuration file. The allowed values are true and false. The default is true.

14.2.4.4 The moduleAware property

The moduleAware parameter specifies that a factory is created for each Struts module in the application.

14.2.4.5 The definitions-factory-class property

There is an additional parameter, not shown, called definitions-factory-class. You can create a custom definitions factory and supply the class name here. The default is org.apache.struts.tiles.xmlDefinition.I18NfactorySet.