Design Doc: Offline Usage

Overview

SiteMesh has typically been used to decorate content on the fly in a web-application using a Servlet Filter. However there is also a strong need to be able to apply decorators to static files as an offline batch activity.

The SiteMesh offline generator will keep things simple – it will apply static decorators to static content. If any additional processing needs to be done (e.g. generating a navigation bar), this can be done by other tools (e.g. Texen).

Usage

Java API

Example Java API usage:

SiteMeshConfig config = new SiteMeshConfig();

config.addDecoratorPath(“/*”, “/decorators/main.html”);

config.addDecoratorPath(“/docs/*”, “/decorators/docs.html”);
SiteMeshOfflineGenerator generator = new SiteMeshOfflineGenerator(

    config, sourceDirectory, destinationDirectory);

generator.process(“somefile.html”);

generator.process(“docs/anotherfile.html”);

All the other usages of the generator will simply be layers on top of this.

Command line

The standard sitemesh jar will be executable. Options are passed as command line arguments.

java -jar sitemesh.jar --sourcedir=/some/dir --destdir=/another/dir --config=sitemesh.xml /some/dir/*.html

The tool must be passed a list of file names that it should process (trailing arguments).

It should also be possible to treat the tool as a pipe filter (i.e. input via stdin, output via stdout). Example:

cat somefile.html | java -jar sitemesh.jar --sourcedir=/some/dir --config=sitemesh.xml > newfile.html

It would also be nice to wrap this up in a script or binary for convenience. This could be a useful tool that would reach beyond Java developers. Example:

# Platform specific installation
apt-get install sitemesh

# Now use it
cat somefile.html | sitemesh --decorator=somedecorator.html > newfile.html
<pre>

h4. Ant task

The SiteMesh Ant task will act as a [[FilterReader|http://ant.apache.org/manual/CoreTypes/filterchain.html]] that can be embedded in an Ant FilterChain (inside a &lt;copy&gt; task).

The advantage the FilterReader has over a standalone Ant task is that:
* It can be chained with other filters in a single copy operation.
* It inherits all the features of the &lt;copy&gt; task.

Example ant task:

<pre>
&lt;!-- Define filter --&gt;
&lt;typedef type="sitemesh" 
         classname="org.sitemesh.offline.ant.SiteMeshFilter" 
         classpath="path/to/sitemesh.jar"/&gt;

&lt;!-- Copy HTML files from srcdir to destdir, applying decorators
     as it goes.  --&gt;
&lt;copy todir="destdir"&gt;
  &lt;fileset dir="srcdir" includes="**/*.html"/&gt;
  &lt;filterchain&gt;
    &lt;sitemesh config="sitemesh-config.xml"/&gt;
  &lt;/filterchain&gt;
&lt;/copy&gt;

Like the other interfaces to the offline generator, it should be possible to configure it by pointing at a sitemesh config file (as in example above) or through inline parameters:

<!-- Alternative, use inline parameters -->
<copy file="srcdir" todir="destdir">
  <filterchain>
    <sitemesh>
      <!-- note: Ant style file patterns. -->
      <decorator path="**/*.html" decorator="/decorators/main.html"/>
      <decorator path="docs/*.html" decorator="/decorators/docs.html"/>
    </sitemesh>
  </filterchain>
</copy>
</pre>

h4. Maven plugin

__TODO__

h3. Configuration

Any configuration mechanism that is available to the online version of SiteMesh should be applicable offline. In fact, the offline generator and online Servlet should be able share the same config and behave in the same way (assuming the content is static of course).

The configuration options should include:
* Referencing a config file
* Config passed as arguments to tool
* A config object (built programatically, injected through container, etc)

As usual, it should be easy for users to wire up their own config mechanisms.

h3. Noteable features

* The Java API will be accessed through a virtual file system interface. Typically this will be backed by an implementation that reads/writes directly to disk, but it will also make it easy to customize to use different sources/destinations (e.g. database, web sites, in memory).

* Only write if output modified. If SiteMesh is run and the result is no different to the last run, the file should not be modified. This makes it play nice with incremental build tools.

* It should be possible to mix and match offline and online. For example, say a site mostly consists of static page, but a few are generated by Servlets, you should be able to share the same decorators and config, and get optimal runtime performance.