Struts in Action: Developing Applications with Tiles

11.5 Migrating an application to Tiles

At the beginning of this chapter we portrayed Tiles as a means of making your applications more consistent and easier to use. We also mentioned that consistency is a hallmark of good design. This is because consistency implies reuse. Reuse leads to applications that are hard to break and easy to maintain.

Often, you will have an existing application that you would like to adapt for Tiles. You may want it to improve the look so it is more consistent, or you may want to improve its functional design—or both. Improving the design of existing software is called refactoring [Fowler].

If you are familiar with conventional refactoring techniques, migrating an application to Tiles resembles the Extract Method. The tiles equate to methods that are called to render the page. When we are done, pages are reduced to a layout and a punch list of tiles to call. This works much like the central method in a class that just calls one member method after another.

Once we have extracted our tiles and reduced the page to a punch list, we can take the process a step further and replace the page with an XML element. Struts can use this element to render the tiles directly without bothering with a punch list page. But like all good refactorings, ours begins with the smallest step.

11.5.1 Setting up the Tiles framework

First, make an extra backup of everything, regardless of how many backups are made in the normal course. Migrating to Tiles can be tricky at first, and, realistically, you may need to make more than one pass before everything clicks into place. So be ready to roll back and try again. An extra backup on your desktop may be enough to lure you away from a three-hour debugging session spurred by some incidental typo.

Struts 1.0

If you haven’t done so, the first step is to install the Tiles 1.0 package and load the Tiles servlet through your application’s deployment descriptor. (See the package for details.) The 1.0 version of Artimus (see chapter 16) is based on Tiles and can be used for a working example. Then, test your application to be sure all is well by clicking through a few pages.

Also, be sure to set up a skeleton Tiles Definitions XML document so you can start filling it out as the refactoring proceeds.

Struts 1.1

Tiles is integrated with Struts 1.1. We cover the steps for enabling Tiles in Struts 1.1 in section 4.8 of this book.

11.5.2 Testing the default configuration

Set the debug and detail parameters in the deployment descriptor (web.xml) to level 2, and restart the application. Check the log entries carefully for any new error messages. Run any unit tests and click through the application to confirm that operation is still nominal.

11.5.3 Reviewing the pages

With Tiles up and running, the next thing is to take a good hard look at your pages and determine the overall layout types and the regions within each layout. It’s also time to start thinking about a naming scheme. Each component will need its own identifier.

Identifying the layouts

When you look through an application, you will find varieties of menu or dialog pages—list pages, view pages, and edit pages—among others. Here the focus should not be on what the pages contain but how the parts of the page fit together. Does it have a header or a footer? Does it have a menu? Is the menu along the side or at the top? At this point, the relative position of elements like the navigation bar is more important than the actual links on the bar.

From this group, try to identify some common layouts. Again, the focus is on the visual layouts used throughout your application, not on the page content.

Identifying the tiles

Next take a closer look at each of the common layouts and identify the individual tiles. Determine how the parts of the page fit together. Then take a look at the page itself and identify the individual tiles. The presentation code for each tile will be saved as a separate file. We can use it in multiple layouts or edit it without touching the other tiles.

As mentioned, this process is similar to applying the Extract Method to a large Java class. One clue is to look for any existing comments in the presentation code, like . A block of markup prefaced with a comment is often a tile waiting to happen, like the block shown in listing 11.12.

Listing 11.12 A good candidate for a tile

Style changes in a page are also a good indicator of a potential tile. If the designer put in a style to set off a portion of the page, that portion of the page may make for a good tile.

The best candidate is a block of self-contained code with a single, coherent purpose—again, not unlike a Java method.

If the presentation code does not have comments like these, it can be helpful to add them to some representative pages before making a pass to extract the tiles. If a page segment looks like a tile, except that each page prints something different on the tile, don’t despair. Tiles can also pass string constants to a tile so that the rest of the markup can be reused. For now, just put in a marker, like $ , where the replacement string would go.

Naming the candidates

It can help to start working on a naming scheme early in the process. What we call a component can crystallize its purpose. We will need names for the individual regions, the general layouts, and each page in the system.

Table 11.3 shows the Tiles nomenclature for these entities: tile, layout, and definition.

The tiles are coherent fragments of text and markup that you will extract from your existing pages. Tiles can host static content or markup, or a mix of both. Most tiles represent navigational controls and other common assets and will be reused between pages. Common assets might include a table that positions a logo somewhere on a page or a set of buttons, like Save and Cancel, that are used on several forms. If a style is already associated with the asset, consider naming the tile after the style.

Other tiles will contain content that is used on a single page. These tiles are often found at the center of the page surrounded by other tiles that provide the menu bars and other HTML chrome.

You can use the same conventions to name the tiles that you would use for any HTML or JSP. It can be useful to separate the shared tiles from those designed for a particular page. An easy way to do this is to open a tiles folder next to the folder you would usually use for your pages:

/pages ./article/Form.jsp ./channel/Channels.jsp/tiles ./header.jsp ./message.jsp

If a file resides in the tiles folder, it means that the file is meant to be used in more than one Definition. If a file resides in the pages folder, it means that the file contains unique content and is not expected to be shared.

The layouts are the containers for the tiles that describe where each component appears on the page. The layouts can be reused between Definitions. To keep everything together, you can create a layouts subdirectory beneath the tiles folder:

/tiles ./header.jsp ./message.jsp ./layouts ./Base.jsp ./Remote.jsp

The Definitions are stored as elements in an XML document. Each Definition element needs its own name. In practice, the Definitions share namespace with the ActionForwards. The scheme should ensure that the ActionForward and Definition names do not collide. It can be helpful to group Definitions together in a directory/subdirectory type structure, so a name separator is also needed. One convention is to use a dot (.) for a separator in Definition names where many people might use a slash (/) in an ActionForward. To be sure there is no conflict with file system names, a leading dot can also be used where a leading slash would usually go:

Of course, any convention will do. You could use @ signs instead of dots, or preface each Definition with TILES: and then use slashes. Since these are logical references, any valid URI will do.

Once you have a general idea of what tiles, layouts, and Definitions you will need, and what you will call them, the next step is to extract the tiles and refactor a page.

As with any refactoring, it’s best to start slow, making one small change after another, until the first iteration is complete. As the process continues, you can take larger and larger steps, building on the prior work (and learning from your mistakes).

In most cases, the goal will be to reduce the pages to a Definition that can be declared in the Tiles configuration file and called from within an ActionForward (see section 11.3 for details). This approach saves creating an extra punch list page to insert the tiles. But to get started, it’s simplest to build a page using the tags.

To get off on the right foot, remember to:

• Select a good starter page.
• Thoughtfully extract the tiles from that page.
• Develop a set of good (and bad) practices along the way.

Selecting a good starter page

It’s best to start with a simple page, extract the common components, and insert them one at a time back into the original page. Your application’s welcome or logon page can be a good candidate. These tend to be relatively simple pages with a nice mix of reusable and custom content. An interior page can also be a good choice, if it does not contain too much chrome. Listing 11.13 shows an interior page from the Artimus example application [ASF, Artimus] before it was migrated to Tiles.

Listing 11.13 Our starter page: /pages/View.jsp

">
Listing 11.15 shows how the View.jsp can include the Header tile again after it has been extracted.
Listing 11.15 Inserting an extracted tile: /pages/article/View.jsp
As soon as your first tile is extracted and inserted back, be sure to test opening the page before moving on to the next tile.
When this process is complete, the page will consist of a series of insert tiles, as shown in listing 11.16.
Listing 11.16 A refactored page: /pages/View.jsp (completed)
If the text in some of the tiles has to be customized, say with the page title, you can use the tag to send a custom value along to the tile. The tag can then write it out when the page renders. Listing 11.17 shows how to send the text to the tile; listing 11.18 shows how to write the dynamic text out again.
Listing 11.17 Inserting dynamic content: /pages/View.jsp (revised)
Listing 11.18 Writing dynamic content with getAsString
">
If you prefer, the Struts or tag can also be substituted for . The attributes are being saved to the standard contexts, so any standard tag will work as well.
Extracting tiles
The main work of the refactoring is to determine which part of the page is part of which tile, moving that fragment into its own file and then inserting it back again. Here’s a step-by-step checklist:

  
Select and cut the block.
  
Open a new file.
  
Paste in the block.
  
Save and name the file as a JSP (or HTML file if you can).
  
Insert any taglib import statements the tile requires.
  
Close the new tile.
  
Place a  tag where the segment used to be.
 
by 
DELETE
RESTORE
EDITCANCEL
 
DONE
< /HTML>
Once you’ve selected your starter page, go through it and extract each logical block into its own tile and insert it back again. After each extraction, test the page to be sure it still renders. Listing 11.14 shows a fragment extracted into its own tile.
Listing 11.14 An extracted tile: /tiles/header.jsp
">
View Article








 





 
NOTE 
 
The Tiles Definitions represent the set of pages that were in use before the refactoring began. The pages are being composed differently, but the content and appearance should remain the same. Most often, the Definition includes a body or content tile as part of the Definition. Some distinct pages may not have a unique tile but are represented by a unique list of shared tiles. You may have a form that uses different buttons under different circumstances. One page may include the set of buttons for creating a new record. Another page may include the set of buttons for updating a record. But other pages may share the sets of buttons and other tiles in the Definition. Distinct pages may also be created from the same Definition by passing a title string and the dynamic content retrieved from a data service. You might have several different ways of searching for records but display them all using the same Definition.
 
 
Extraction practices
Here are some caveats and practice notes regarding the extraction process. Since this will become a routine, it is important to have clear practices and to learn from past mistakes:

  
All custom tags used by the tile must be imported into the tile.
  
All custom tag elements must begin and end in the same tile.
  
Avoid carrying HTML elements over to another tile.
  
Mark up by contract.
  
Consider trade-offs.
  
Leverage technology.

All custom tags used by the tile must be imported into the tile. The tile will inherit HTML assets, like style sheets. It will not inherit references to JSP assets, like tag libraries. The web browser applies the style sheet when the page renders, but since each tile is in fact a stand-alone JSP servlet, it needs its own references to JSP resources.
All custom tag elements must begin and end in the same tile. If you use the tag in your file, place the elements for this tag at the top and bottom of your layout (which is a single tile). This restriction does not apply to HTML elements. You can, for example, open the element in a header tile and close the element in a footer tile, but custom tags are validated when the tile is compiled. JSP tag elements must begin and end within the same tile.

Avoid carrying HTML elements over to another tile. In practice, you may decide that one tile should open an element, like a table; a second should provide the content, like the rows in a table; and a third should close the element. When this pattern is useful, you should use it but still try to begin and end as many elements as possible in the same tile. This makes finding markup errors much easier. Even if the middle tile only provides the rows for a table, it can do so as complete … rows.
Mark up by contract. When you decide to use something like Tiles, you are also deciding to treat markup like code. Accordingly, all the usual paradigms apply, like assertions and program by contract. When you design your tiles, think about the preconditions and postconditions for each tile, just as you would for a method in a class. Don’t hesitate to document the conditions for each tile, just as you would for a method. A good approach is to just use standard JavaDoc conventions in a JSP comment, which avoids creating a new wheel:
For HTML tiles, just use HTML comment braces instead. Unlike JSP comments, HTML comments will be visible in the source of the page. You may wish to be brief and discreet when using HTML comments.
Consider trade-offs. Dissembling a page into tiles is much like normalizing a database. You can strip out absolutely all the redundant information, but if you do, some of the parts become so small that maintenance and performances issues can appear. In practice, you may have two or three varieties of header or footer files that may replicate markup. But if the markup changes, it is still easier to conform 3 files than 30 or 300. As with any programming task, the usual trade-offs apply.
Leverage technology. If you are also introducing style sheets and other markup changes at the same time, don’t hesitate to create skeleton files and use editing macros with search-and-replace to automate some of the work. It’s easy to forget how much time you can save with these old friends.
11.5.5 Extracting the tags into a Definition
After you have applied the process in section 11.5.3 to your starter page and have confirmed that it still works, you can finish the job by extracting the tags into an XML Definition. This is a four-step process:

  
Move the page to the layouts folder.
  
Rename the body tile.
  
Convert the insert tag to a layout and Definition.
  
Update the ActionForward.

Move the page to the layouts folder
Move the refactored page to the location you’ve chosen for layout tiles, under /tiles/layouts, for example. At this point, the refactored page should be a punch list of tags, and the original content of the page should have been reduced to a set of tiles.
Rename the body tile
One of the extracted tiles probably represents the body, or “guts,” of the original page. If so, consider renaming it as the original page you just moved. The implication is that the core content of the original page will still be where the original page stood. This helps to minimize change. If you need to edit the page’s content, the content will still be where it always was. If you do this, update the tag after moving or renaming the file. Working from listing 11.16, we would change
Convert the insert tag to a layout and Definition
Add a name property to each of the insert tags. This will often match the name of the JSP. The exception might be the tile representing the original body of your page. This will usually have a more generic name, like content.
Copy the statements from your refactored page into the starter tiles.xml configuration file that we set up at the beginning of this section and place them inside a element. If you used any elements, you can promote those to top-level elements now:
Then, rename the tags as elements and the page attribute as a value attribute. To the element, add name and path properties. The path property should be to your layout page (see step 1). The name property can correspond to the name of your original page, but substitute dots for the slashes. Listing 11.19 shows our complete tiles.xml file.
Listing 11.19 A Tiles configuration file: /WEB-INF/conf/tiles.xml
Now, in the layout page, change the tags to tags and delete the page attribute (since that is now part of the Definition) Any tags can be changed to tags. Keep the name attribute, but delete the value attribute (since the value is part of the Definition now).
Listing 11.20 shows a complete layout JSP.
Listing 11.20 A Tiles layout page: /tiles/layouts/Base.jsp
Update the ActionForward
Finally, replace the ActionForward that referred to the original JSP with a reference to the Tiles Definition:
As shown in figure 11.6, the Tiles ActionServlet will intercept the reference and apply the Definition to the layout page.
Figure 11.6 The Tiles ActionServlet uses the definition to help create the response.
If you were forwarding directly to the JSP before, you can use the standard Scaffold SuccessAction to route control through the controller so the Definition can be used to select and render the layout. You can use the Definition anywhere you were using a system path to the JSP. If there are enough references, you can even use the search-and-replace feature of your editor to change them all automatically.
At runtime, the Tiles ActionServlet will intercept the ActionForward and check its path against the Definitions in the Tiles configuration. If it finds a match, it includes each tile of the Definition in the response. The container then processes each included tile normally. The HTML tiles are rendered by the container’s HTML service, and the JSP tiles are rendered by the container’s JSP service.
If the ActionForward path is not the name of a Definition, the ActionServlet handles it as a normal URI, same as always.
To test your changes, be sure to reload the application so that the current Struts and Tiles configurations are loaded into memory. If you’ve been following along, you can try this now.
Once you have gone through the process of refactoring a page with and then converting it to a Definition, you may wish to convert other pages directly to a Definition. To do this, you:

  
Copy an existing Definition using the same layout and give it a new name.
  
Clip out and save the content segment of the page you are refactoring.
  
Change the new Definition to refer to the segment you just saved and converted.
  
Test and repeat.

 
NOTE 
 
When you first switch a block of pages over to Tiles, it may take a little extra time for the pages to render at first. This is because the JSPs for the new tiles are being created in addition to the usual one you need for the content. Once the JSP for each tile is created, it will not be re-created until it is changed, and everything goes back to normal. In the future, if you edit the content tile, only that one JSP will be recompiled.
 
 
11.5.6 Normalizing your base layout
Back in listing 11.20, we showed the layout file as a series of tags. If you like, you can also use regular HTML and JSP code on your layout page. This is a good place to put the topmost tags, like or , so that these do not need to be put inside other tiles, which might really be intended to do other things.
Listing 11.21 shows a revised base layout page that extracts the topmost elements from the header and navbar tiles and puts them on the base layout. We’ve also renamed it from Base.jsp to Article.jsp to indicate its role as the Article layout tile. Other pages in the application may need to use a different layout.
Listing 11.21 Revised layout tile (/tiles/layouts/Article.jsp)
">
11.5.7 Refining your Definitions into base and extended classes
As you commute your pages to layouts and Definitions, it’s easy to end up with sets like this:
If you look closely, you’ll see that the first and third items differ but the others are the same. A better way to write them, and any like them, is to create a base Definition. The Tiles Definition supports an extends property, which lets a Definition inherit attributes and overload only what needs to be changed. Here, we extend .article.Base and overload title and content:
With the base Definition in place, we now have to supply only two lines for each of our subDefinitions. The other settings fall through and do not need to be specified. If there are attributes that will be used throughout your site, you can put those in a base Definition and extend everything else from that. Then, if any of the base attributes change, you need to make the change in only one place.
As a convention, we put markers in for the values of the first and third items (title and content) to indicate that these are extension points that subDefinitions need to override. If the base Definition were used directly, then these markers would just print out as literals. The $<> markers have no special meaning to Tiles.
Another convention shown here is to use an initial capital letter for the layout JSP but an initial lowercase letter for the tile JSPs. This is to indicate that the layout page can be called directly, because it is a fully formed JSP class. The tile pages are like methods invoked by the layout JSP, and so use the same naming convention as a method. But this is only a convention; any other consistent naming scheme would work just as well.
11.5.8 Developing a routine
After the first few pages, you should be able to develop a routine that goes something like this:

  
Create a new Definition (in tag.xml), often by copying a similar one.
  
Update the Definition with the path to the existing page, page title, and any other custom information.
  
Open the existing page.
  
Delete the top and bottom, leaving the core content and tag import statements.
  
Review and revise the core content to ensure that the markup keeps its API contract with the tiles before and after it in the Definition. One tile may need to open an element, like a , and another tile may need to close it. Remove any unneeded tag import statements. Optionally, add a comment block.
  
Update the paths in the Struts configuration (struts-config.xml) to reference the new Definition, including any input properties.
  
Reload the tag configuration and the Struts configuration.
  
Review the page.
  
Rinse and repeat.

At first, you will probably start with pages as they appear in your application’s flow. Once you have the procedure down, it is not difficult to step through the page tree and refactor each page in turn. This will ensure that you don’t miss any. It may also uncover some obsolete pages left over from prior development efforts.
11.5.9 Managing the migration
Moving an application over to Tiles is not difficult but neither is it trivial. Be sure to schedule enough time for the project. The first few pages may take several hours, but once the pattern is established, additional pages may take only a few minutes each.
If you also need to apply a new look to the site, it may be best to first convert it to Tiles and then apply the new design so that you are not doing two new things at once. Once the layout is migrated to Tiles, bringing up the new design will go more quickly.
A good time to schedule a migration is when you know a visual redesign is coming but don’t have the new design in hand yet. If you can have the application migrated to Tiles while the redesign is being finalized, applying the changes will be a smoother process. Doing both at once is not recommended—especially for your first migration.
So what’s the bottom line of a migration? Your mileage will vary, but a small application with 25 presentation pages consuming about 140,000 kbytes of markup code was migrated to 55 tiles of about 120,000 kbytes—the 15% difference being redundant markup that was removed.
Moving forward, new pages for the application can now be created much more quickly and will be more consistent with existing pages. To change the overall layout, you can edit the layout or a few individual tiles instead of every page on the site.
11.6 Summary
Dynamic template systems, like the Tiles framework, can bring familiar programming patterns to the presentation layer of a web application. They let us slice and dice the HTML markup and JSP commands into manageable pieces. We can then assemble a page by calling the individual pieces, or tiles, the way we would call Java methods to perform a larger process. A tile encapsulates a block of markup, much like a method encapsulates a block of Java code.
The pages of a web application are built around a common look and feel, or layout, that helps users navigate the site. When we assemble pages using Tiles, we start with a base layout that defines where the tiles are placed and gives each position a logical name. The paths to the tiles a particular page uses can then be passed at runtime. A typical page may use five or six tiles, with only one or two of those changing from page to page.
In Tiles, a complete page, including the layout and the paths to its tiles, can be represented as an object called a Definition. To assemble a particular page, we can simply refer to its Tiles Definition. Like the Struts framework components, the Definitions can be configured using an XML document and loaded at startup.
The Struts framework uses ActionForwards to encapsulate paths to system resources, including presentation pages and Action classes. The framework’s controller, the ActionServlet, uses ActionForwards to route control. The other components refer to the ActionForward by name and rely on the controller to invoke the resource indicated by the forward’s path.
A standard extension to the controller allows Definitions to be used as the ActionForward path. When a Definition is the target of an ActionForward, the controller includes the fragments in a combined response. The standard service for each fragment then finishes the job.
When an application is migrated to Struts, one consequence is that system paths become encapsulated in the Struts configuration. The presentation pages can then refer to other resources using a logical name rather than an actual path or URI. This lets us focus on what the page wants to do rather than the particulars of how it is done.
In the same fashion, when an application is migrated to Tiles, the configuration encapsulates the system paths. Struts can then refer to the page Definition by name and leave the particulars of assembling the page to the Tiles framework.
Tiles can be of most use to larger systems with dozens or hundreds of pages. Like decomposing a process into constituent methods, refactoring an application to use Tiles creates more component parts, but each individual part is simpler to understand and maintain. More important, the individual tiles can be reused, avoiding the need to make the same change in multiple places. As applications grow, the need to eliminate redundancy becomes increasingly important.
The focus of this chapter has been to provide you with enough information to put Tiles to work in your application. But it by no means covers everything that is possible with the Tiles framework. The Artimus example application (see chapter 15) is based on Tiles and demonstrates several of the best practices described in this chapter.
In the next chapter, we explore another “optional” component, the Struts Validator.
About the Authors
Ted Husted is an acknowledged Struts authority, an active member of the Struts development team, and manager of the JGuru Struts Forum. As a consultant, Ted has worked with professional Struts development teams throughout the United States. Ted also helps manage the Apache Jakarta project, which hosts the Struts framework. Ted lives in Fairport, New York with his wife, two children, four computers, and an aging cat.
Cedric Dumoulin is an active member of the Struts development team and the author of the Tiles framework. Cedric is presently a researcher at the University of Lille. He has also worked in the R&D department of a leading international internet banking company. He lives in Lille, France.
George Franciscus is a principal at Nexcel, providing technical and management consulting services in several industries including Telecommunications, Banking, Life Insurance and Property and Casualty Insurance. George has expertise in Java, J2EE, Domino, relational databases, and mainframe technologies. He holds a BSc in Computer Science from the University of Toronto. George lives in Toronto, Ontario with his wife and three children.
David Winterfeldt is a Struts committer and author of the Commons Validator package. He works as a senior developer at a major company implementing J2EE technology. David currently lives in New York City.
Source of this material
To access the full Table of Contents for the book.