Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
170 lines (136 sloc) 6.64 KB
<html>
<head>
<title>Configuring SiteMesh</title>
</head>
<body>
<p>SiteMesh supports two main approaches to configurations - <b>XML</b> or <b>Java</b>. It's up to you which you use. In fact, you can even use them both.</p>
<table class="definitionTable">
<tr>
<th>XML</th>
<th>Java</th>
</tr>
<tr>
<td>
<ul>
<li>Simplest to get started with</li>
<li>Automatically reloads when config file changes</li>
<li>Does not require Java programming</li>
</ul>
</td>
<td>
<ul>
<li>Allows for greater customization of SiteMesh</li>
<li>Avoids yet another configuration file</li>
<li>Can be used from higher level languages such as JRuby, Groovy, Scala...</li>
</ul>
</td>
</tr>
</table>
<h2>XML based configuration</h2>
<p>The configuration file should live in <code><b>/WEB-INF/sitemesh3.xml</b></code> in your web-application.</p>
<h4>Example</h4>
<pre class='code'>&lt;sitemesh&gt;
&lt;mapping path="<b>/*</b>" decorator="<b>/decorator.html</b>"/&gt;
&lt;mapping path="<b>/admin/*</b>" decorator="<b>/admin-decorator.html</b>"/&gt;
&lt;/sitemesh&gt;</pre>
<h2>Java based configuration</h2>
<p>To use the Java based configuration, subclass <code><b>org.sitemesh.config.ConfigurableSiteMeshFilter</b></code>
and overload the <code><b>applyCustomConfiguration(SiteMeshFilterBuilder builder)</b></code> method.
You shall be passed an object that you can use to configure SiteMesh. You then deploy this filter in to your web-application.</p>
<h4>Example</h4>
<pre class='code'>public class MySiteMeshFilter extends ConfigurableSiteMeshFilter {
@Override
protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
<b>builder.addDecoratorPath("/*", "/decorator.html")
.addDecoratorPath("/admin/*", "/admin/decorator.html");</b>
}
}</pre>
<p><b>Note:</b> The <code><b>SiteMeshFilterBuilder</b></code> class supports a chainable API where each method returns an instance of itself. This is a convenience, but you
don't have to use this style.</p>
<p><b>Note:</b> If you also have an XML config file, SiteMesh will load this before calling <code>applyCustomConfiguration()</code>.
This allows you to use XML for some configuration and Java for more advanced aspects.</p>
<h2>Configuring Decorator Mappings</h2>
<p>This is the most common configuration applied to SiteMesh - mapping which decorators are applied based on the paths.</p>
<p>Things you can do:</p>
<ul>
<li>Map a default decorator to all paths</li>
<li>Map a decorator to a specific path</li>
<li>Map multiple decorators to a path - each decorator is applied to the result of the previous</li>
<li>Exclude a path from being decorated</li>
</ul>
<h4>XML</h4>
<pre class="code">&lt;sitemesh&gt;
&lt;!-- Map default decorator. This shall be applied to all paths if no other paths match. --&gt;
<b>&lt;mapping decorator="/default-decorator.html"/&gt;</b>
&lt;!-- Map decorators to path patterns. --&gt;
<b>&lt;mapping path="/admin/*" decorator="/another-decorator.html"/&gt;</b>
<b>&lt;mapping path="/*.special.jsp" decorator="/special-decorator.html"/&gt;</b>
&lt;!-- Alternative convention. This is more verbose but allows multiple decorators
to be applied to a single path. --&gt;
<b>&lt;mapping&gt;
&lt;path&gt;/articles/*&lt;/path&gt;
&lt;decorator&gt;/decorators/article.html&lt;/decorator&gt;
&lt;decorator&gt;/decorators/two-page-layout.html&lt;/decorator&gt;
&lt;decorator&gt;/decorators/common.html&lt;/decorator&gt;
&lt;/mapping&gt;</b>
&lt;!-- Exclude path from decoration. --&gt;
<b>&lt;mapping path="/javadoc/*" exclue="true"/&gt;</b>
<b>&lt;mapping path="/brochures/*" exclue="true"/&gt;</b>
&lt;/sitemesh&gt;</pre>
<h4>Java</h4>
<pre class='code'>public class MySiteMeshFilter extends ConfigurableSiteMeshFilter {
@Override
protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
// Map default decorator. This shall be applied to all paths if no other paths match.
<b>builder.addDecoratorPath("/*", "/default-decorator.html")</b>
// Map decorators to path patterns.
<b>.addDecoratorPath("/admin/*", "/another-decorator.html")</b>
<b>.addDecoratorPath("/*.special.jsp", "/special-decorator.html")</b>
// Map multiple decorators to the a single path.
<b>.addDecoratorPaths("/articles/*", "/decorators/article.html",
"/decoratos/two-page-layout.html",
"/decorators/common.html")</b>
// Exclude path from decoration.
<b>.addExcludedPath("/javadoc/*")</b>
<b>.addExcludedPath("/brochures/*")</b>;
}
}</pre>
<h2>Advanced Configuration</h2>
<p>For most users, the decorator mappings above should be enough. But if you want more options...</p>
<h3>MIME Types</h3>
<p>By default, SiteMesh will only intercept responses that set the <b><code>Content-Type</code></b> HTTP header to <b><code>text/html</code></b>.</p>
<p>This can be altered to allow SiteMesh to intercept responses for other types. This is only applicable for the SiteMesh Filter - it is ignored by the offline site builder.</p>
<h4>XML</h4>
<pre class="code">&lt;sitemesh&gt;
<b>&lt;mime-type&gt;text/html&lt;/mime-type&gt;
&lt;mime-type&gt;application/vnd.wap.xhtml+xml&lt;/mime-type&gt;
&lt;mime-type&gt;application/xhtml+xml&lt;/mime-type&gt;</b>
...
&lt;/sitemesh&gt;</pre>
<h4>Java</h4>
<pre class='code'>public class MySiteMeshFilter extends ConfigurableSiteMeshFilter {
@Override
protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
<b>builder.setMimeTypes("text/html", "application/xhtml+xml", "application/vnd.wap.xhtml+xml")</b>;
}
}</pre>
<h3>Deploying Tag Rule Bundles</h3>
<p>An advanced feature of SiteMesh is the ability to define custom rules that manipulate tags on a page.
These are classes that implement <code>org.sitemesh.content.tagrules.TagRuleBundle</code>.</p>
<h4>XML</h4>
<pre class="code">&lt;sitemesh&gt;
<b>&lt;content-processor&gt;
&lt;tag-rule-bundle class="com.something.CssCompressingBundle"/&gt;
&lt;tag-rule-bundle class="com.something.LinkRewritingBundle"/&gt;
&lt;/content-processor&gt;</b>
...
&lt;/sitemesh&gt;</pre>
<h4>Java</h4>
<pre class='code'>public class MySiteMeshFilter extends ConfigurableSiteMeshFilter {
@Override
protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
<b>builder.addTagRuleBundles(new CssCompressingBundle(), new LinkRewritingBundle())</b>;
}
}</pre>
</body>
</html>
Something went wrong with that request. Please try again.