As discussed in Decorating Beyond URL Patterns, SiteMesh out of the box uses sitemesh-default.xml which contains mappers to how decorators are applied.
In some cases you want to go beyond the defaults and use more advanced mappers or even define you own custom mappers.
This example will take you through configuring your own sitemesh.xml mapper file to decorate using query string parameters. After completing this tutorial you will be able to apply similar steps to make use of other advanced mappers.
Creating Your Own sitemesh.xml
To start extract the sitemesh-default.xml file from your SiteMesh jar file into your web applications WEB-INF directory and rename it sitemesh.xml.
Here are the contents of sitemesh-default.xml from sitemesh-2.4.1.jar.
Decorate using Query Parameters
With this modification, individual pages will be able to specify the decorator to use with a query string parameter. For example, the following url would override the default coffeebreak pattern based decorator and load a Paris themed decorator.
First, add to the sitemesh.xml the PageDecoratorMapper,
Ordering Mapper Elements
The order of the mapper elements determine precedence. A well behaved application should use the following order,
- Parameter query = ParameterDecoratorMapper
- Page specific using meta tag = PageDecoratorMapper
- Pattern = ConfigDecoratorMapper
Keep in mind that the nature of the mapper elements can override the order set by the developer.
For example, a common mistake is to put ConfigDecoratorMapper before PageDecoratorMapper. Because ConfigDecoratorMapper is so general, technically all pages request would cause a decorator to be loaded and as such the PageDecoratorMapper never gets loaded. Even in the case of an exclude in decorators.xml, the match is to not apply a decorator and again PageDecoratorMapper is never loaded.