Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
196 lines (162 sloc) 10.4 KB
<html>
<head>
<title>Building offline websites with SiteMesh</title>
<style>
.attribute{
color: blue;
font-weight: bold;
}
.node {
color: #330099;
font-weight: bold;
}
</style>
</head>
<body>
<p>A new feature in SiteMesh 3 is being able to apply decorators to content as an offline task, typically as part of a build step.</p>
<p>If both your content and your decorators are static, this offers a few benefits:</p>
<ul>
<li>Allows final content to be distributed as pre-generated folder. Useful for including documentation with products without having to include a full Servlet compliant web-server.</li>
<li>Cuts down server loads - most web-server architectures are optimized for serving static files.</li>
<li>Provides more flexibility on where you can host content.</li>
</ul>
<p>It's also possible to reuse decorators and configuration between a web application that generates decorated content on the fly,
and offline generated files.</p>
<h2>Usage</h2>
<p>There are a few different approaches to invoking the SiteMesh offline generator:</p>
<ol>
<li><b>Command line interface</b></li>
<li><b><a href="http://ant.apache.org/" target="external">Apache Ant</a> task</b></li>
<li><b>Java API</b> (this can be embedded in applications, or used from higher level languages such as JRuby, Groovy or Scala)</li>
</ol>
<p>Each of these can have the mappings of the decorators passed directly to them, or load from the SiteMesh <a href="configuration.html">configuration file</a>.</p>
<p>Use the approach that suits your project.</p>
<h2>Command line interface</h2>
<p>You can invoke the command line interface by running the executable sitemesh.jar. It requires Java 5 but no other dependencies.</p>
<p>Invoking on it's own will output a detailed help message:</p>
<pre class="code"><b>java -jar sitemesh-3.x.jar</b></pre>
<h4>Arguments</h4>
<p>The following arguments need to be passed to the command line:</p>
<table class="definitionTable">
<tr>
<td><b><code>-src</code></b></td>
<td>Required</td>
<td>Path to source directory, containing content and decorators</td>
</tr>
<tr>
<td><b><code>-dest</code></b></td>
<td>Required</td>
<td>Path to destination directory, where decorated content will be written</td>
</tr>
<tr>
<td><b><code>-dest</code></b></td>
<td>Required</td>
<td>Path to destination directory, where decorated content will be written</td>
</tr>
<tr>
<td><b><code>-config</code></b></td>
<td rowspan="2">One of these</td>
<td>Path to <a href="configuration.html">configuration file</a></td>
</tr>
<tr>
<td><b><code>-decoratorMapping</code></b></td>
<td>TODO</a></td>
</tr>
<tr>
<td><b><code>FILE1 FILE2 FILE3...</code></b></td>
<td>Required</td>
<td>List of content files to apply decorators to. These must be relative to the <code>src</code> directory</td>
</tr>
</table>
<h4>Example</h4>
<pre class="code">java -jar sitemesh-3.x.jar -src project/src -config project/sitemesh.xml -dest project/build index.html page1.html page2.html</pre>
<h2>Ant Task</h2>
<h3>Overview</h3>
<p>The sitemesh.jar comes prepackaged with a custom Ant task that can be used for offline processing. In the following examples, we're going to look
at how to install and use the SiteMeshTask to generate static content in the offline mode.</p>
<h3>SiteMeshTask</h3>
<p>The SiteMeshTask defines the following attributes:</p>
<ol>
<li>destDir - The output folder in which all of the decorated files will be placed.</li>
<li>config - The location of the SiteMesh configuration file.</li>
<li>srcdir - The source directory which contains all of the files to be decorated.</li>
<li>includes - An Ant style filter of what files to include.</li>
<li>excludes - An Ant style filter of what files to exclude.</li>
</ol>
<p>The SiteMeshTask can also accept the following child nodes:</p>
<ol>
<li>fileset - The standard Ant <a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a> that will use the srcdir of the sitemesh node.</li>
<li>sitemeshfileset - A custom SiteMesh FileSet that supports an additional attribute called "decorator" which can be used to associate a decorator with the
given FileSet.</li>
</ol>
<h3>Getting started!</h3>
<p>The below provides a high level outline of what steps we're going to cover in this section.</p>
<ol>
<li>Create a SiteMesh configuration file.</li>
<li>Register the SiteMeshTask with Ant</li>
<li>Define the &lt;<span class="node">sitemesh</span>/&gt; node.</li>
<li>Execute Ant</li>
</ol>
<h4>1. Creating the SiteMesh configuration file</h4>
<p>The SiteMeshTask can be given a configuration file to tell SiteMesh how to decorate files. The power of this feature is that the configuration is then
externalized from the buid.xml file. In our first two examples, we're going to show how to use this form of the SiteMeshTask. Below is a very simple
SiteMesh configuration file that applies the main.html decorator to all pages.</p>
<pre>&lt;<span class="node">sitemesh</span>&gt;
&lt;<span class="node">mapping</span> <span class="attribute">path</span>="/*" <span class="attribute">decorator</span>="/decorators/main.html"/&gt;
&lt;<span class="node">/sitemesh</span>&gt;
</pre>
<h4>2. Registering SiteMeshTask with Ant</h4>
<p>In order to use SiteMesh from within Ant, the first thing you will need to do is register the SiteMeshTask with Ant using the following
&lt;<span class="node">taskdef</span>/&gt; declaration.</p>
<pre class="code">&lt;<span class="node">project</span> <span class="attribute">name</span>="my-ant-project"&gt;
<b>&lt;<span class="node">taskdef</span> <span class="attribute">name</span>="sitemesh"
<span class="attribute">classname</span>="org.sitemesh.ant.SiteMeshTask"
<span class="attribute">classpath</span>="path/to/sitemesh-3.x.jar"/&gt;</b>
...
&lt;<span class="node">/project</span>&gt;</pre>
<p>For more information on registering custom tasks within Ant, please see <a href="http://ant.apache.org/manual/tutorial-writing-tasks.html" target="_new">Writing Ant Tasks</a>.</p>
<h4>3. Define the &lt;<span class="node">sitemesh</span>/&gt; node.</h4>
<p>Now that we've created the SiteMesh configuration file and registered the SiteMeshTask with Ant, it's time to start using SiteMesh within our tasks.</p>
<h5>Using the sitemesh task without a fileset.</h5>
<p>Let's look at how to provide &lt;<span class="node">sitemesh</span>/&gt; with a configuration file and tell it what directories to include or exclude.</p>
<p>In this example, we're going to process all of the files stored in "project/src" and place the decorated files into "project/build".</p>
<pre class="code">&lt;<span class="node">project</span> <span class="attribute">name</span>="my-ant-project"&gt;
&lt;<span class="node">target</span> <span class="attribute">name</span>="my-target"&gt;
<b>&lt;<span class="node">sitemesh</span> <span class="attribute">srcdir</span>="project/src"
<span class="attribute">config</span>="project/sitemesh.xml"
<span class="attribute">destdir</span>="project/build"
<span class="attribute">includes></span>="**/*.html"
<span class="attribute">excludes</span>="decorators/*"/&gt;</b>
&lt;<span class="node">/target</span>&gt;
&lt;<span class="node">/project</span>&gt;</pre>
<p>The benefit to the above is that all configuration is externalized from the the build.xml file.</p>
<h5>Using the sitemesh task with the sitemeshfileset</h5>
<p>In the below example, multiple source folders are used by provided a sitemeshfileset. This provides greater control over what folders
should be included or excluded, but still leverage a common destination folder and configuration file.</p>
<pre class="code">&lt;<span class="node">project</span> <span class="attribute">name</span>="my-ant-project"&gt;
&lt;<span class="node">sitemesh</span> <span class="attribute">destdir</span>="site/documentation"
<span class="attribute">config</span>="config/sitemesh.xml"&gt;
&lt;<span class="node">sitemeshfileset</span> <span class="attribute">dir</span>="documentation"&gt;
&lt;<span class="node">include</span> <span class="attribute">name</span>="**/*.html"/&gt;
&lt;<span class="node">exclude</span> <span class="attribute">name</span>="private/*"/&gt;
&lt;<span class="node">/sitemeshfileset</span>&gt;
&lt;<span class="node">sitemeshfileset</span> <span class="attribute">dir</span>="presentation"&gt;
&lt;<span class="node">include</span> <span class="attribute">name</span>="**/*.html"/&gt;
&lt;<span class="node">/sitemeshfileset</span>&gt;
&lt;<span class="node">/sitemesh</span>&gt;
&lt;<span class="node">/project</span>&gt;</pre>
<h5>Using the sitemesh task with the sitemeshfileset with an associated decorator</h5>
<p>In our finaly example, a decorator will be used on each sitemeshfileset.</p>
<pre class="code">&lt;<span class="node">project</span> <span class="attribute">name</span>="my-ant-project"&gt;
&lt;<span class="node">target</span> <span class="attribute">name</span>="generate-with-custom-decorator"
<span class="attribute">description</span>="Generate static content that's internal to the company."&gt;
&lt;<span class="node">sitemesh</span> <span class="attribute">destdir</span>="site/documentation"&gt;
&lt;<span class="node">sitemeshfileset</span> <span class="attribute">dir</span>="documentation"
<span class="attribute">decorator</span>="decorators/private.html"&gt;
&lt;<span class="node">include</span> <span class="attribute">name</span>="private/*.html"/&gt;
&lt;<span class="node">/sitemeshfileset</span>&gt;
&lt;<span class="node">/sitemesh</span>&gt;
&lt;<span class="node">/target</span>&gt;
&lt;<span class="node">/project</span>&gt;</pre>
</body>
</html>