Introduction to SiteMesh
byWill Iverson
03/11/2004


Contents
How Does It Work?
Installing SiteMesh
web.xml
decorators.xml
decorators/*.jsp
sitemesh-2.0.1.jar
*.tld
Advanced SiteMesh
Summary

In the past, I used to build my web applications the old-fashioned way: handcrafting assembly, carefully building my raw byte handlers to work with Unicode, counting instructions, and using make files to target different CPUs.
OK, maybe not.
Although I‘ve never actually felt the need to build my web application with assembly (CISC or RISC), I sometimes think my fellow developers are on a quest to make their development processes as painful as possible. In particular, I‘ve seen many developers agonize over the best way to handle basic web application building blocks: things like headers, footers, navigation bars, support for printable pages, light-weight pages for handheld devices, and more. In the end, things like includes and brute-force copy-and-paste win out surprisingly often.
In my experience, I‘ve been able to easily solve these problems cleanly, easily, and elegantly using the open source servlet filterSiteMesh, which ishosted on java.net. Instead of requiring a new templating language, XSLT, or "porting" your pages to a new system, using SiteMesh often allows you to dramatically simplify your pages while still using ordinary HTML, JSP, servlets (including Struts), and other familiar technologies.
How Does It Work?
SiteMesh implements a page filter, taking advantage of one of the lesser-known features of the servlet specification. Let‘s imagine you have a simple JSP that returns the current date and time. Ordinarily, the request for the page comes in to the application server, the page is rendered, and then the results are returned to the web browser. SiteMesh, as a page filter, takes the page after it is rendered and performs additional processing before returning the document to the web browser. This change is most simply described as the additional step shown between Figure 1 and Figure 2.

Figure 1. Normal Page Rendering

Figure 2. SiteMesh Page Rendering
Let‘s look at a simple example of this. Consider the following simple JSP:
Hello World!
<%= 1+1 %>
You‘ll notice that the page has a title and a body (like any ordinary HTML page). You‘ll notice a tiny bit of JSP code -- this will be rendered just as you would expect. Indeed, you can use any and all features that you would expect, and you link between the various JSP and other resources just as you might expect.
Now, let‘s look at a simple SiteMesh "decorator" page. Listing 2 shows a JSP page, called by SiteMesh.
<%@ taglib uri="sitemesh-decorator"prefix="decorator" %>

(printable version)

Looking at the decorator, we can see a few interesting things. First, a SiteMesh taglib is introduced in the first line. This taglib includes everything required to work with the original page. You can see that we use two of the SiteMesh declared tags, and . Not surprisingly, the returns the contents of the Hello World!
<%= 1+1 %>
We can make a decorator "smart" enough to know to look for this meta tag, and if present, generate the appropriate HTML:
<%@ taglib uri="sitemesh-decorator" prefix="decorator" %>

">

---

(printable version)

You‘ll notice that we use a default attribute in the getProperty tag -- if no author is specified, we‘ll just assume that it was written by the staff. If you decide to use this model for storing page metadata, you‘ll want to work with your content developers and other team members to determine what tags you want to use and how you‘ll be using them. At the simple end, you may want to use meta tags to describe things like the author and page timestamp. At the complex end, you may do things like standardize on an XML file to manage your site navigation and use a meta tag to pass the page‘s node to the decorator.
The page that results from applying this decorator to the JSP page above is shown in Figure 6.

Figure 6. meta Tag Displayed
These page attributes are powerful, and you can retrieve many different properties, not just the meta tags (here‘sa list of generated page properties). After using SiteMesh for a while, you‘ll start thinking about HTML and JSP as a mechanism for generating simple markup -- closer to the original intent of HTML -- without having to make a full switch to an XML/XSL or other template engine.
Summary
As we‘ve seen, SiteMesh provides for a powerful, easy-to-use, non-intrusive mechanism for applying page templates. It‘s easy to envision a wide range of possible uses. For example, you might define a decorator that emits extra debugging information about the page, as determined by the browser (this is especially powerful when combined with a web browser that lets you set an arbitrary user-agent). You might define a decorator with a stripped-down XML output, allowing for easier automated testing. You can even use the decorator to grab content from other pages, for example, to simple portal-like capability.
Once you‘ve gotten comfortable with sitemesh-blank.war, I‘d suggest looking at sitemesh-example.war for more features and ideas.
Regardless of how you use SiteMesh, I‘ve found that it lets me centralize a tremendous amount of code, moving it out of my presentation layer and into my decorators, without having to learn a new programming language or templating system.
Oh, and as a final note for those of you still interested in building web pages in assembly, check outhome.worldonline.dk/viksoe/asmil.htm.
Good luck and happy coding!
Will Iverson served as Developer Relations Manager for the VisualCafé group at Symantec, as the Java & Runtimes Product Manager at Apple Computer and has led Cascade Technology Group, a private consulting firm, since 1999.