Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: master
223 lines (168 sloc) 10.62 kB
<html>
<head>
<title>Getting started with SiteMesh3</title>
<meta name='author' content='Joe Walnes'>
<style type='text/css'>
.decorator { color: #000099; }
.content { color: #990000; }
</style>
</head>
<body>
<h2>Introduction</h2>
<p>This tutorial is a quick introduction to using SiteMesh3 in a web-application. It covers:</p>
<ul>
<li>A high level overview of how SiteMesh3 works</li>
<li>Installation and configuration</li>
<li>Building and applying a simple decorator</li>
</ul>
<p>It is recommend you read the high level <a href="overview.html">SiteMesh Overview</a> before this tutorial.</p>
<h2>SiteMesh in web applications</h2>
<p>In a web application, SiteMesh acts as a Servler Filter. It allows requests to be handled by the Servlet engine as normal,
but the resulting HTML (referred to as the <b>content</b>) will be intercepted before being returned to the browser.</p>
<p>The intercepted content has certain properties extracted (typically the contents of the
<code>&lt;title&gt;</code>, <code>&lt;head&gt;</code> and <code>&lt;body&gt;</code> tags and is then passed on to a
second request that should return the common look and feel for the site (referred to as the <b>decorator</b>). The decorator
contains placeholders for where the properties extracted from the content should be inserted.</p>
<p>Under the hood, a key component of the SiteMesh architecture is the <b>content processor</b>. This is an efficient engine
for transforming and extracting content from HTML content. For most users, it's fine to use it as it comes, but it is also possible
to define your own transformation and extraction rules.</p>
<p>SiteMesh does not care what technologies are used to generate the content or the decorator. They may be
static files, Servlet, JSPs, other filters, MVC frameworks, etc. So long as it's served by the Servlet engine, SiteMesh can
work with it.</p>
<h2>Dependencies</h2>
<p>Running SiteMesh3 requires at least:</p>
<ul>
<li>JDK 1.5</li>
<li>A Servlet 2.5 compliant container</li>
<li>The SiteMesh runtime library</li>
</ul>
<p>The SiteMesh library should be <a href="http://github.com/sitemesh/sitemesh3/downloads" target="external">downloaded</a> and placed in <code><b>/WEB-INF/lib/</b></code>.</p>
<h2>Setup</h2>
<p>Insert the SiteMesh Filter in <code><b>/WEB-INF/web.xml</b></code>:</p>
<pre class='code'>&lt;web-app&gt;
...
&lt;filter&gt;
&lt;filter-name&gt;<b>sitemesh</b>&lt;/filter-name&gt;
&lt;filter-class&gt;<b>org.sitemesh.config.ConfigurableSiteMeshFilter</b>&lt;/filter-class&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
&lt;filter-name&gt;<b>sitemesh</b>&lt;/filter-name&gt;
&lt;url-pattern&gt;<b>/*</b>&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
&lt;/web-app&gt;</pre>
<p>Deploy the web-application to your Servlet container. From this point onwards, this tutorial assumes the web-app is running at <code><b>http://myserver/</b></code>.
<h2>Creating a decorator</h2>
<p>The <b>decorator</b> contains the common layout and style that should be applied to the pages in the web application.
It is a template that contains place holders for the content's <code>&lt;title&gt;</code>, <code>&lt;head&gt;</code> and
<code>&lt;body&gt;</code> elements.</p>
<p>At the bare minimum, it should contain:</p>
<pre class='code decorator'>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;<b>&lt;sitemesh:write property='title'/&gt;</b>&lt;/title&gt;
<b>&lt;sitemesh:write property='head'/&gt;</b>
&lt;/head&gt;
&lt;body&gt;
<b>&lt;sitemesh:write property='body'/&gt;</b>
&lt;/body&gt;
&lt;/html&gt;</pre>
<p>The <code><b>&lt;sitemesh:write property='...'/&gt;</b></code> tag will be rewritten by SiteMesh to include properties extracted from
the content. There are more properties that can be extracted from the content and it's possible to define your own rules - that will
be covered in another tutorial.</p>
<p>The bare minimum decorator isn't very useful. Let's add some style and a bit of common layout.</p>
<p>Create the file <code><b>/decorator.html</b></code> in your web-app, containing:</p>
<pre class='code decorator'>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;SiteMesh example: <b>&lt;sitemesh:write property='title'/&gt;</b>&lt;/title&gt;
&lt;style type='text/css'&gt;
/* Some CSS */
body { font-family: arial, sans-serif; background-color: #ffffcc; }
h1, h2, h3, h4 { text-align: center; background-color: #ccffcc; border-top: 1px solid #66ff66; }
.mainBody { padding: 10px; border: 1px solid #555555; }
.disclaimer { text-align: center; border-top: 1px solid #cccccc; margin-top: 40px; color: #666666; font-size: smaller; }
&lt;/style&gt;
<b>&lt;sitemesh:write property='head'/&gt;</b>
&lt;/head&gt;
&lt;body&gt;
&lt;h1 class='title'&gt;SiteMesh example site: <b>&lt;sitemesh:write property='title'/&gt;</b>&lt;/h1&gt;
&lt;div class='mainBody'&gt;
<b>&lt;sitemesh:write property='body'/&gt;</b>
&lt;/div&gt;
&lt;div class='disclaimer'&gt;Site disclaimer. This is an example.&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
<p>In this example, the decorator is a static <code>.html</code> file, but if you want the decorator to be more dynamic, technologies such as JSP, FreeMarker, etc can be used.
SiteMesh doesn't care - it just needs a path that can be served content by the Servlet engine.</p>
<h2>Configuration</h2>
<p>SiteMesh needs to be configured to know about this decorator and what it should do with it.</p>
<p>The configuration file should be created at <code><b>/WEB-INF/sitemesh3.xml</b></code>:</p>
<pre class='code'>&lt;sitemesh&gt;
&lt;mapping path="<b>/*</b>" decorator="<b>/decorator.html</b>"/&gt;
&lt;/sitemesh&gt;</pre>
<p>This tells SiteMesh that requests matching the path <code>/*</code> (i.e. all requests) should be decorated with <code>/decorator.html</code> that we just created.</p>
<p><i>If you don't like the idea of having to use XML to configure SiteMesh, don't worry - there are alternative mechanisms including
directly in <code>WEB-INF/web.xml</code>, programatically through a Java API, through Spring, by naming convention, or any custom way you may choose to plug in.
These are explained further in <a href="configuration.html">another article</a>.</i></p>
<h2>Creating some content</h2>
<p>Now to create some content. This is defined in plain HTML content. Create <code><b>/hello.html</b></code>:</p>
<pre class='code content'>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;<b>Hello World</b>&lt;/title&gt;
<b>&lt;meta name='description' content='A simple page'&gt;</b>
&lt;/head&gt;
&lt;body&gt;
<b>&lt;p&gt;Hello &lt;strong&gt;world&lt;/strong&gt;!&lt;/p&gt;</b>
&lt;/body&gt;
&lt;/html&gt;</pre>
<p>Like the decorator, the content may be static files or dynamically generated by the Servlet engine (e.g. JSP).</p>
<h2>The result</h2>
<p>Pointing your browser to <code><b>http://myserver/hello.html</b></code> will serve the content you just created, with the
decorator applied. The resulting merged HTML will look like this:</p>
<pre class='code decorator'>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;SiteMesh example: <b class='content'>Hello World</b>&lt;/title&gt;
&lt;style type='text/css'&gt;
/* Some CSS */
body { font-family: arial, sans-serif; background-color: #ffffcc; }
h1, h2, h3, h4 { text-align: center; background-color: #ccffcc; border-top: 1px solid #66ff66; }
.mainBody { padding: 10px; border: 1px solid #555555; }
.disclaimer { text-align: center; border-top: 1px solid #cccccc; margin-top: 40px; color: #666666; font-size: smaller; }
&lt;/style&gt;
<b class='content'>&lt;meta name='description' content='A simple page'&gt;</b>
&lt;/head&gt;
&lt;body&gt;
&lt;h1 class='title'&gt;SiteMesh example site: <b class='content'>Hello World</b>&lt;/h1&gt;
&lt;div class='mainBody'&gt;
<b class='content'>&lt;p&gt;Hello &lt;strong&gt;world&lt;/strong&gt;!&lt;/p&gt;</b>
&lt;/div&gt;
&lt;div class='disclaimer'&gt;Site disclaimer. This is an example.&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
<p>As you can see, the <code>&lt;title&gt;</code>, <code>&lt;head&gt;</code> and <code>&lt;body&gt;</code> have
been extracted from the content and inserted into the decorator template.</p>
<h2>Summary</h2>
<p>A quick recap:</p>
<ul>
<li>SiteMesh is installed by dropping the library jar in <code><b>/WEB-INF/lib</b></code> and creating a filter (with mapping) in <code><b>/WEB-INF/web.xml</b></code></li>
<li>It can be configured by creating a <code><b>/WEB-INF/sitemesh3.xml</b></code> file, or through <a href="configuration.html">other configuration methods</a></li>
<li>The filter intercepts requests to <b>Content</b>, runs it through the <b>Content Processor</b> and merges with a <b>Decorator</b>
<li>The <b>Content</b> is defined by an HTML page, that contains the vanilla HTML content of the site</li>
<li>The <b>Decorator</b> is also defined by an HTML page, that contains the look and feel of the site, and placeholder <code><b>&lt;sitemesh:write&gt;</b></code> tags to indicate where the <b>Content</b> should be merged in</li>
<li>The <b>Content Processor</b> contains the rules for extracting and transforming the content - it has some simple default rules and can be customized</li>
</ul>
<!--
<h2>Learn more</h2>
<p>This tutorial skipped over many of the features of SiteMesh. You have enough information to start using SiteMesh, but if you want to learn more...</p>
<ul>
<li><a href="overview.html">SiteMesh overview</a></li>
<li><a href="configuration.html">Configuring SiteMesh</a></li>
<li><a href="inline.html">Decorating inline page fragments</a></li>
<li><a href="chaining.html">Chaining decorators</a></li>
<li><a href="composition.html">Page composition</a></li>
<li><a href="content-processor.html">Content processor and tag reference</a></li>
<li><a href="offline.html">Building offline websites</a></li>
<li><a href="examples/index.html">Browse examples</a></li>
<li><a href="cookbook/index.html">SiteMesh cookbook</a></li>
</ul>
-->
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.