Advanced SiteMesh

SiteMesh Architecture

The SiteMesh architecture is based on Filters, namely the PageFilter class. When a container receives a request for a page, it will pass it to PageFilter, which will create a custom response object for collecting the application's response, and pass it to the web application along with the request. The web application will write the requested resource in the custom response object and will return it back to PageFilter.

1. The Parsing Phase

   Once control comes back to the PageFilter class, it will examine the content type of the response generated by the web application. Depending on the content type, it will determine which parser class to use for parsing the response. It will create an object of that parser class and will pass the response to it. For example, if an application returns content of the type text/html, SiteMesh will create an object of the FastPageParser class and pass the page generated by the web application to it. FastPageParser will parse that page to read the header, footer, title, etc. from it.

2. The Decoration Phase

   Once the parsing phase is complete, SiteMesh will start the decoration phrase. This can be divided into two phases.

   a. Determining how to decorate this page

   SiteMesh has a concept of decorator mapper, which is a Java class implementing the DecoratorMapper interface (meaning it has init() and getDecorator() methods). A mapper is declared by adding an entry for it in sitemesh.xml. In sitemesh.xml, every mapper is parent of the mapper declared just above it. When SiteMesh has to find the decorator for a particular page, it will create an instance of the first mapper in sitemesh.xml and call its getDecorator() method. In the getDecorator() method, the mapper class will try to determine a decorator for that page. If mapper is able to get a decorator, it will return it; otherwise, it will call the getDecorator() method of its parent, following this process until it finds the correct decorator for that page.

   b. Applying decorators

   Once the decorator (a JSP page) is found, SiteMesh will dispatch the request to it. The decorator JSP page has access to the parsed page from the previous phase. It will use various SiteMesh custom tags to read various parts (such as header, footer, and title) and insert them at appropriate places in the final output page.

You can define which page parser classes to use for particular content types and what decorator mappers to use by editing WEB-INF/sitemesh.xml like this:

<?xml version="1.0" encoding="UTF-8"?>

<sitemesh>

  <property name="decorators-file" value="/WEB-INF/decorators.xml"/>

  <excludes file="${decorators-file}"/>

  <page-parsers>

    <parser content-type="text/html" 

        class="com.opensymphony.module.sitemesh.parser.FastPageParser" />

  </page-parsers>

  <decorator-mappers>

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.PageDecoratorMapper">

      <param name="property.1" value="meta.decorator" />

      <param name="property.2" value="decorator" />

    </mapper>

    <!-- Mapper for localization -->

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.LanguageDecoratorMapper">

      <param name="match.en" value="en" />

      <param name="match.zh" value="zh" />

    </mapper>

    <!-- Mapper for browser compatibility -->

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.AgentDecoratorMapper">

      <param name="match.MSIE" value="ie" />

      <param name="match.Mozilla/" value="ns" />

    </mapper>

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.PrintableDecoratorMapper">

      <param name="decorator" value="printable" />

      <param name="parameter.name" value="printable" />

      <param name="parameter.value" value="true" />

    </mapper>

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.ParameterDecoratorMapper">

      <param name="decorator.parameter" value="decorator" />

      <param name="parameter.name" value="confirm" />

      <param name="parameter.value" value="true" />

    </mapper>

    <mapper 

        class="com.opensymphony.module.sitemesh.mapper.ConfigDecoratorMapper">

      <param name="config" value="${decorators-file}" />

    </mapper>

  </decorator-mappers>

</sitemesh>

In this listing, <property name="decorators-file"> defines which file contains decorator definitions. <page-parsers> defines what content types SiteMesh can handle. Each <parser> child element maps which class should be used for parsing the response of a particular content type. In our sample sitemesh.xml, we are telling SiteMesh that FastPageParser should be used for handling the text/html type of content. By default, SiteMesh can only handle HTML, but you can create your own parsers for handling other content types.

The <decorator-mappers> element defines what mappers SiteMesh is going to apply while finding decorators for a particular page. You can pass configuration information to the mapper with the <param> sub-element. SiteMesh will wrap these configuration parameters in a java.util.Properties object and pass it to the init() method of mapper class.

Locale-Specific Decorators

In our example sitemesh.xml, we have the following tag:

<mapper class="com.opensymphony.module.sitemesh.mapper.LanguageDecoratorMapper">

  <param name="match.en" value="en" />

  <param name="match.zh" value="zh" />

</mapper>

While finding a decorator for a page, SiteMesh will read the Accept-Language header of the request. If it matches the en locale, it will take the name of the decorator JSP and append -en to it. In our sample, if you request help.jsp, for which headerfooter.jsp is the decorator, then for the English locale, SiteMesh will search for headerfooter-en.jsp. If headerfooter-en.jsp is found, it will use that; otherwise it will use headerfooter.jsp.

Browser-Specific Decorator

We are using AgentDecoratorMapper for browser compatibility:

<mapper 

class="com.opensymphony.module.sitemesh.mapper.AgentDecoratorMapper">

  <param name="match.MSIE" value="ie" />

  <param name="match.Mozilla/" value="ns" />

</mapper>

This means that while finding the decorator for a page, SiteMesh will try to figure out what the user's browser is from the value of the User-Agent header. If it is Microsoft Internet Explorer, then it will append -ie to the name of the decorator file, and if found, use it as the decorator. Otherwise, it will use headerfooter.jsp

Advanced SiteMesh

SiteMesh provides mappers, which let every page participate in process of finding a decorator for that page.

PrintableDecoratorMapper

Most web sites provide a facility for getting a printable version of a page. The printable version normally removes headers, footers, and side menus, and may provide a different stylesheet. In SiteMesh, we can achieve this by using PrintableDecoratorMapper. To use this mapper you have to add an entry for it in sitemesh.xml, like this:

<mapper 

class= "com.opensymphony.module.sitemesh.mapper.PrintableDecoratorMapper">

  <param name="decorator" value="printable" />

  <param name="parameter.name" value="printable" />

  <param name="parameter.value" value="true" />

</mapper>

This passes three parameters to PrintableDecoratorMapper. These parameters are passed to the PrintableDecoratorMapper's init method as a java.util.Properties object:

• decorator
  The name of the decorator, which should be used for creating the printable version of a page.

• parameter.name
  The name of the request parameter to be used for informing SiteMesh that we want a printable page. In our example, all we have to do is pass printable=true in the query string.

• parameter.value
  The value of the printable parameter that indicates we want a printable version of the page.