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