ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button O'Reilly Book Excerpts: Programming Jakarta Struts

Programming Jakarta Struts: Using Tiles, Part 2

Related Reading

Programming Jakarta Struts
By Chuck Cavaness

by Chuck Cavaness

In part two in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to install and configure tiles, as well as get an overview on tiles.

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.

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.

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:

In This Series

Programming Jakarta Struts: Using Tiles, Part 4
We conclude this book excerpt series on using tiles from Programming Jakarta Struts by showing you how to use definitions. You'll also find coverage on support for internationalization of tiles.

Programming Jakarta Struts: Using Tiles, Part 3
In part 3 in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to use the tile tag library.

Programming Jakarta Struts: Using Tiles, Part 1
In part one in this series of book excerpts on using tiles from Programming Jakarta Struts, learn how to use tiles, and gain an understanding of templates.

  • 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.

WARNING: 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.

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:


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" %>

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.

TIP: 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" />

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.

Overview of Tiles

The Tiles framework provides a templating mechanism that allows you to separate the responsibilities of layout from those of content. As with the templates described earlier in this chapter, you have the ability to establish a layout and dynamically insert the contents of your pages into that layout at runtime. This is a powerful mechanism if you need to customize your site based on such things as internationalization, user preferences, or just the look-and-feel changes that occur in every web application sooner or later. The Tiles framework provides the following features:

  • Template capabilities
  • Dynamic page construction and loading
  • Screen definitions
  • Support for tile and layout reuse
  • Support for internationalization
  • Support for multiple channels

There has been a Template tag library within the Struts framework for quite some time. These tags allow you to use a very basic templating approach to assemble your JSP pages in a web application. Although these tags are helpful in separating the content for a web application from its prescribed layout, the Tiles framework goes much further and actually provides a superset of the Template tag library's behavior, as well as many other features.

TIP: The Tiles framework was previously called Components, but the name was changed because that term is so overused. The Tiles documentation and source code still make reference to the old name in some places.

Cedric Dumoulin created the Tiles framework to extend the concept of templates and provide developers with more flexibility and freedom when creating web applications built with JSP technology. The content for the web applications is still driven by JSP pages and JavaBeans. However, the layout is specified within a separate JSP page or, as we'll see later, in an XML file.

What Is a Tile?

A tile is an area or region within a web page. A page can consist of just one region or be broken up into several regions. Figure 14-1 illustrates an example from the Storefront application.

Figure 14-1. The regions of the Storefront application

A JSP page is typically made of several regions, or tiles. There's nothing too special about the page, other than the fact that it's designed to be used with the Tiles framework and makes use of the Tiles tag library.

The most important aspect of a tile is that it is reusable. This is true for layouts as well as body content. Unlike most JSP pages, tile components are reused within an application and possibly across different applications. Other than that, there's nothing that complicated about a tile. In fact, most of the examples we've seen so far can be classified as tiles, including Example 14-2 through Example 14-4 (found on the second page of the first article).

Using a Layout Tile

In the Tiles world, a layout is what we have been referring to as a template. A layout serves the exact same purpose as a template--that is, to assemble a group of tiles to specify the format of a page. Example 14-2 is, in fact, a Tiles layout. The syntax between Tiles and a template library like the one included with Struts is almost identical.

TIP: The Tiles framework provides a superset of the functionality included with the standard Struts template tags defined by David Geary, but it takes the concept of templates even further by providing additional functionality.

Layouts also are considered tiles. JSP pages and even entire applications can reuse layouts, and it's common to build a library of layouts that are used in many different projects. The Tiles framework comes with several prebuilt layout tiles that you can reuse or modify as needed. The included layouts are:

  • Classic layout: Renders a header, left menu, body, and footer
  • Columns layout: Renders a list of tiles in multiple columns, each of which renders its tiles vertically stacked
  • Center layout: Renders a header, left tile, right tile, body, and footer
  • Menu layout: Renders a menu with links
  • Tabs layout: Renders several tiles in a tabs-like fashion
  • Vertical box layout: Renders a list of tiles in a vertical column

Because one of the main goals of Tiles is reusability, you can reuse these layouts within your application with little or no modifications. You also have the freedom to customize the layouts in any way you need.

Planning Your Layout

It's very important that you plan your layout requirements ahead of time. Trying to decide how your site is going to look after it's already built is definitely not the right approach. This decision is typically made by a human factors team, product management, or possibly the web developers themselves. In any case, you need to develop the layout (or layouts) well ahead of any actual development.

The default layout for the Storefront application was presented in Example 14-2. This layout will be used as an example throughout this chapter.

Passing Parameters to the Layout

The layout tile shown in Example 14-2 is generic. It doesn't know anything about the itemdetail.jsp content or any of the other pages, for that matter. This is intentional, as it allows us to reuse this layout for many pages. Instead of being hardcoded within the layout page, the content is supplied or "passed" as parameters to the layout page at runtime. Let's look at the signin.jsp tile for the Storefront application, shown in Example 14-5.

Example 14-5: The signin.jsp tile for the Storefront application
<%@ taglib uri="/WEB-INF/tiles.tld" prefix="tiles" %>

<tiles:insert page="../layouts/storefrontDefaultLayout.jsp" flush="true">
  <tiles:put name="header" value="../common/header.jsp"/>
  <tiles:put name="menubar" value="../common/menubar.jsp"/>
  <tiles:put name="body-content" value="../security/signin-body.jsp"/>  
  <tiles:put name="copyright" value="../common/copyright.jsp"/>

The purpose of the put tags in Example 14-5 is to supply the layout tile, which is specified in the enclosing insert tag, with content. The values of the name attributes in Example 14-5 (as in the other tiles shown in Example 14-3 and Example 14-4 in the previous article) must match the ones that the layout tile is expecting.

TIP: The insert tag optionally can include an ignore attribute that will cause the tag to not write out anything when it can't find a value for an expected attribute. By default, a runtime exception is thrown when an attribute has not been supplied.

In the next installment, learn about the Tiles Tag Library.

Chuck Cavaness is a graduate from Georgia Tech with degrees in computer engineering and computer science. He has built Java-based enterprise systems in the healthcare, banking, and B2B sectors. He is also the author of two O'Reilly books, Programming Jakarta Struts and Jakarta Struts Pocket Reference.

Return to ONJava.com.