Building SiteMesh Decorators

Once SiteMesh has been installed and configured, you can begin writing decorators for your web application.

Introduction

Decorators are the pages that "decorate" the original, requested page (the page that is handed to the SiteMesh filter from the web container). Most (HTML) decorators are a combination of:

meta tags (keywords, description, author)
stylesheet (CSS)
header
navigation
footer
copyright notice

First, define what different navigation/layout schemes you need. For example: Do I need a default decorator (a standard one for all pages)? Do I have a special layout for the index page? Is the header needed for my documentation files? Do I need printable version of my website?

Web Application Structure

Here is an example structure of a web application. This is not needed for SiteMesh to work.

`/decorators`	Directory containing all decorator files (e.g. `main.jsp`, `printable.jsp`).
`/includes`	Directory containing all files to be included into other files (e.g. `header.jsp`, `footer.jsp`, `copyright.jsp`).
`/images`	Directory containing all images (e.g. `background.gif`, `logo.gif`).
`/styles`	Directory containing all .CSS styles (e.g. `ie4.css`, `ns4.css`).
`/scripts`	Directory containing all scripts (JavaScript, VBScript files).

Good practices:

Define a stylesheet to use in the entire application and include it using this script.
Use includes in your decorators (e.g. includes/navigation.jsp, includes/style.jsp).
Try not to refer to the absolute root ("/") path. Use <%=request.getContextPath()%>/ instead. This will make life easier when moving your web application under another context path.
Making your decorators compatible with multiple browsers (IE, Mozilla, Opera, ...) will (probably) make your entire application (all decorated pages) compatible.
Be careful when using frames, because decorators may NOT be applied to frames (FrameSetDecoratorMapper).

My First Decorator

Basically, all you need to know is what decorator tags you can use. The title, head and body tags are most used.
Here is an example of a decorator (save it as /decorators/main.jsp):

1: <%-- 2: % This is the main decorator for all SOMECOMPANY INTRANET pages. 3: % It includes standard caching, style sheet, header, footer and copyright notice. 4: --%> 5: <%@ taglib uri="http://www.opensymphony.com/sitemesh/decorator" prefix="decorator" %> 6: <%@ include file="/includes/cache.jsp" %> 7: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 8: <html> 9: <head> 10: <title><decorator:title default="INTRANET" /></title> 11: <decorator:head /> 12: <%@ include file="/includes/style.jsp" %> 13: </head> 14: <body bgcolor="#FFFFFF" background="<%=request.getContextPath()%>/images/bg.gif"> 15: <script type="text/javascript">window.status = "Loading: <decorator:title default="INTRANET" />...";</script> 16: <%@ include file="/includes/header.jsp"%> 17: <table width="100%" border="0" cellspacing="0" cellpadding="0"> 18: <tr> 19: <td height="20" nowrap> </td> 20: </tr> 21: <tr> 22: <td width="1%" nowrap> </td> 23: <td width="16%" valign="top" nowrap> 23: <script type="text/javascript">window.status = "Loading: Navigation...";</script> 24: <%@ include file="/includes/navigation.jsp" %> 25: </td> 26: <td width="2%" nowrap> </td> 27: <td valign="top"> 28: <br> 29: <script type="text/javascript">window.status = "Loading: Document body...";</script> 30: <div class="docBody"><decorator:body /></div> 31: </td> 32: <td width="1%" nowrap> </td> 33: </tr> 34: </table> 35: <br> 36: <%@ include file="/includes/footer.jsp" %> 37: <%@ include file="/includes/copyright.jsp" %> 38: <script type="text/javascript">window.status = "Done";</script> 39: </body> 40: </html>

Line 1-4:
An explanation of the decorator. This way different people working on the decorator are quickly up to speed.
Line 5:
This is needed for the decorator: tags to work (also needed on all pages that work with inline decorators (page:applyDecorator).
Line 6:
Sets the necessary response headers to let the browser cache the page. Omit this line if your application is real dynamic (changing data).
Line 10:
If the requested page doesn't have a title, the default title is used ("INTRANET").
Line 15:
The status bar gets a message when the page is loading.
Line 30:
The entire body of the requested page has the docBody class. This way the navigation and body do not have to have the same font.

Now open WEB-INF/decorators.xml with your favorite editor and let SiteMesh know there is a decorator (with a mapping):

<decorators defaultdir="/decorators">
    <decorator name="main" page="main.jsp">
          <pattern>/*</pattern>
    </decorator>
</decorators>

Now deploy the web application, go to the welcome page, and the main decorator will be applied.

More examples

More examples are included with the SiteMesh distribution, under the src/example-webapp directory. If the examples don't give you enough to go on, take a look at SiteMesh in action, download the petsoar-app at http://www.wiley.com/legacy/compbooks/walnes/.