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/index.html.

14.2.2 Installing the Required JARs and Misc Files

The first step is to install the required files. For Tiles, the following files must be located in the WEB-INF/lib directory:

· tiles.jar

· commons-digester.jar

· commons-beanutils.jar

· commons-collections.jar

· commons-logging.jar

All of these binaries should already be present if you are using Struts. You will also need to install the Tiles TLD file, tiles.tld, in the WEB-INF directory for the application.

Don't add the tiles.jar file to the classpath of your servlet container in an attempt to avoid placing it in the WEB-INF/lib directory of each individual web application. Doing so will cause ClassNotFoundExceptions to be thrown.

You should put the tiles-config.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/tiles.tld</taglib-uri>
  <taglib-location>/WEB-INF/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/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 bind it to a Struts application.

With earlier versions of the Tiles framework, you had to configure a special ActionServlet called ActionComponentServlet in the web.xml file. It was also necessary to configure a special RequestProcessor in the Struts controller element. This is no longer true—a Tiles plug-in is now available that will take care of all the initialization.

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/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" />
</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.

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.

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.

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.

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.