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.
Page Based Decorator With PageDecoratorMapper
With this modification, individual pages can specify the decorator to use with a meta tag.
First, add to the sitemesh.xml the PageDecoratorMapper,
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.