14.5 Using Definitions

So far, we've seen that using Tiles can add value to an application because you're able to organize the layout of a page into a single resource, the layout JSP page. This can save development time and, more importantly, the time it takes to change the layout for an application. However, there is a problem with the approach used in the Storefront application shown earlier. In each of the non-layout tiles, there is redundant code that specifies what content to use for the header, menubar, and copyright content the same attributes are being passed in every page. This may not always be the case, but in general, these values will be constant throughout an application. For instance, the same copyright is typically shown on every page.

It's redundant to have to specify these in every tile. Ideally, we could declare these attributes in one place, and the tiles could include just the page-specific attributes where needed. Tiles definitions provide just such functionality. A definition allows you to statically specify the attributes that are used by a template, which in turn allows you to specify only the page-specific attributes in your tiles. Definitions enable you to:

• Centralize declaration of page description

• Avoid repetitive declaration of nearly identical pages (by using definition inheritance)

• Avoid creation of intermediate components used to pass parameters

• Specify the name of a definition as a forward in the Struts configuration file

• Specify the name of a definition as component parameters

• Overload definition attributes

• Use a different copy of a component, depending on the locale (I18N)

• Use a different copy of a component, depending on a key (this might be used to show different layouts depending on the client type)

Definitions can be declared in a JSP page or an XML file. Either way, you should strive to keep the definitions in a central place. If you are planning on using a JSP page to specify your definitions, put all the definitions for your application in a single page. Don't spread your definitions throughout your site, as that will only make maintenance more difficult.

14.5.1 Declaring Definitions in a JSP Page

As previously mentioned, there are two locations in which you can specify definitions: a JSP page or an XML file. We'll discuss the JSP page approach first.

To use the JSP approach, create a JSP page and declare all of your definitions in that file. For the Storefront application, we've created a file called storefront-defs.jsp and put the default definition in it, as Example 14-6 shows.

Example 14-6. Declaring tiles definitions in a JSP page

<%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %> <tiles:definition        page="/layouts/storefrontDefaultLayout.jsp"    scope="request">     <tiles:put name="header" value="/common/header.jsp" />     <tiles:put name="menubar" value="/common/menubar.jsp" />     <tiles:put name="copyright" value="/common/copyright.jsp" />   </tiles:definition>

The definition in Example 14-6 uses the same layout tile used earlier. The common files that were spread through the various tiles are now located in the definition file. This makes changing their values much easier. For instance, if we wanted to specify a different copyright page, the only place to change it would be in the definition file; we would not have to modify every JSP page.

The definition tag syntax looks very similar to the syntax for the insert tags shown earlier. We just need to provide an id attribute and switch the path attribute to the page attribute. Also, the default scope for the definition tag is page. It was set to request scope here to give it a little broader scope.

To take advantage of the definition, the tile components need to be able to access it. Because we have given the definition request scope and it will exist only for the lifetime of a request, we need a way to include the definition in the various JSP pages. Fortunately, we already know how to include a JSP page in another page using the JSP include directive. Example 14-7 shows what the signin.jsp page looks like using the JSP definition file.

Example 14-7. The signin.jsp page using a tile definition

<%@ taglib uri="/WEB-INF/struts-tiles.tld" prefix="tiles" %> <%@include file="../common/storefront-defs.jsp" %> <tiles:insert definition="storefront.default">   <tiles:put name="body-content" value="/index.jsp"/> </tiles:insert>

With this approach, the tile components have to insert only the page-specific content. Compare Example 14-7 to Example 14-5. Notice that the signin.jsp file using the definition needs to provide only the page-specific content, the sign-body.jsp file.

14.5.2 Declaring Definitions in a Configuration File

You also have the option of declaring definitions in a centralized XML file. Whether you use the JSP or the XML alternative really depends on your requirements. With the XML approach, you won't need to use the include directive shown earlier.

14.5.2.1 Creating a definition configuration file

To use the XML approach, create an XML file that follows the syntax of the tiles-config.dtd file. The definition XML file should be placed in the WEB-INF directory, as with the other application meta-information. The DTD should also be placed in the WEB-INF directory. Example 14-8 shows an example of a definition XML file.

Example 14-8. The Storefront definition XML file

<!DOCTYPE tiles-definitions PUBLIC   "-//Apache Software Foundation//DTD Tiles Configuration//EN"   "http://jakarta.apache.org/struts/dtds/tiles-config.dtd"> <tiles-definitions>  <definition name="storefront.default" path="/layouts/storefrontDefaultLayout.jsp">       <put name="header" value="/common/header.jsp" />   <put name="menubar" value="/common/menubar.jsp" />   <put name="copyright" value="/common/copyright.jsp" />    </definition> </tiles-definitions>

There's not much difference between the definition format specified in the JSP file in Example 14-6 and the XML file in Example 14-8. The XML file uses a slightly different syntax, but it's still very similar.

The two formats are just similar enough to cause problems. Notice that in the JSP definition, you use the put tag:

<tiles:put    name="body-content"    value="../security/signin-body.jsp"/>

but in the XML definition, you use the put element:

<put    name="header"    value="/common/header.jsp" />

Make sure that you don't get these two confused, as this can be a difficult bug to track down.

Each definition should have a unique name. JSP tags and pages use the name to retrieve the definition. It can't be used as a URL, however; it's only a logical name for the definition.

14.5.3 Extending Tile Definitions

One of the most powerful features of tile definitions is the ability to create new definitions by extending existing ones. All attributes and properties of the parent definition are inherited, and you can override any attribute or property. To extend a definition, add the extends attribute. Example 14-9 shows an example of a definition named storefront.custom extending the storefront.default definition.

Example 14-9. Definitions can extend other definitions

<tiles-definitions>  <definition name="storefront.default" path="/layouts/storefrontDefaultLayout.jsp">       <put name="header" value="/common/header.jsp" />   <put name="menubar" value="/common/menubar.jsp" />   <put name="copyright" value="/common/copyright.jsp" />    </definition> </tiles-definitions> <tiles-definitions>  <definition name="storefront.custom" extends="storefront.default">       <put name="copyright" value="/common/new-copyright.jsp" />    </definition> </tiles-definitions>

In Example 14-9, all of the attributes in the storefront.default definition are inherited. However, the storefront.customer definition overrides the value for the copyright attribute with an alternate copyright page. This is a very powerful feature. If you have multiple child definitions all extending a root definition, changing a value in the root definition changes it for all the children. Thus, you can change the layout in the root definition and have it changed for all child definitions.

14.5.4 Using Definitions as Forwards in Struts

Tiles definitions can also be used as Struts forwards, instead of actual URLs. To use definitions in this manner, you first create the definitions:

<tiles-definitions>     <definition name="storefront.default"                path="/layouts/storefrontDefaultLayout.jsp">         <put name="header" value="/common/header.jsp" />     <put name="menubar" value="/common/menubar.jsp" />     <put name="copyright" value="/common/copyright.jsp" />     </definition>      <definition name="storefront.superuser.main" extends="storefront.default">         <put name="header" value="/common/super_header.jsp" />     <put name="menubar" value="/common/super_menubar.jsp" />     <put name="copyright" value="/common/copyright.jsp" />     </definition>   </tiles-definitions>

This fragment shows two definitions, the standard default definition and a second one that defines the layout for a "superuser." A superuser might be someone that frequents the site and places many orders, and such a user might be given more options on the menu bar to facilitate faster ordering.

In the Struts configuration file, we need to define the forwards that use these definitions:

<global-forwards>  <forward name="Super_Success" path="storefront.superuser.main" />    </global-forwards>

You can then use the Super_Success forward to send the user to the storefront.superuser.main definition just as you would for any other forward.