1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<html>
<head>
<title>SiteMesh DecoratorMappers</title>
</head>
<body>
<p>When a page has been parsed, it then has to be mapped to a decorator.
This mapping is performed by a chain of <a
href="api/com/opensymphony/module/sitemesh/DecoratorMapper.html">DecoratorMappers</a>
(referred to as mappers from here on).</p>
<p>For each request, the first mapper in the chain is asked which
decorator should be used. It is passed across a reference to the Page
object and HttpServletRequest. It returns either a Decorator object, if
it knows which decorator to be used, or null. If null is returned, the
next mapper in the chain is queried. This whole process is repeated
until there are no more mappers in the chain, or one of the mappers
returns a valid decorator. If no mappers return a decorator, the page is
not decorated at all and served in its original state.</p>
<p>This way the mappers are chained together and queried is known as the
Chain of Responsibility design pattern.</p>
<p>Examples of mappers:</p>
<ul>
<li>Determine decorator based on path of requested page.</li>
<li>Use different decorators based on time, locale or browser.</li>
<li>Use simplified decorators for search-engine robots.</li>
<li>Switch decorators based on a URL parameter, request attribute or meta-tag.</li>
<li>Use custom decorators based on user's saved settings...</li>
</ul>
<p>The main implementation of DecoratorMapper is <a href="api/com/opensymphony/module/sitemesh/mapper/ConfigDecoratorMapper.html">ConfigDecoratorMapper</a> which
reads the decorators and mappings from <code>/WEB-INF/decorators.xml</code>. The appropriate decorator is then applied
depending on the URL pattern.</p>
<p>DecoratorMappers are simple to write and the distribution includes some
samples that demonstrate how to write them and how flexible they can be.
These are:
<table border="0" cellspacing="10">
<tr>
<td valign="top"><strong>AgentDecoratorMapper</strong></td>
<td>Can determine the user-agent (i.e. web-browser) requesting a page,
and map to a suitable Decorator.</td>
</tr>
<tr>
<td valign="top"><strong>ConfigDecoratorMapper</strong></td>
<td>Default implementation of DecoratorMapper. Reads decorators and
mappings from the <code>config</code> property (default '/WEB-
INF/decorators.xml').</td>
</tr>
<tr>
<td valign="top"><strong>CookieDecoratorMapper</strong></td>
<td>Will map a suitable decorator based on a cookie value.</td>
</tr>
<tr>
<td valign="top"><strong>EnvEntryDecoratorMapper</strong></td>
<td>Allows the reference to a web-app environment entry for the decorator name,
and falls back to ConfigDecoratorMapper's behavior if no matching environment
entry is found.</td>
</tr>
<tr>
<td valign="top"><strong>FileDecoratorMapper</strong></td>
<td>Will treat the name of the decorator as a file-name to use (in the
context of the web-app).</td>
</tr>
<tr>
<td valign="top"><strong>FrameSetDecoratorMapper</strong></td>
<td>Will use the specified decorator when the Page is an instance of HTMLPage and
isFrameSet() returns true. The
name of this decorator should be supplied in the <code>decorator</code>
property - if no decorator property is supplied, no decorator is applied
to frame based pages.</td>
</tr>
<tr>
<td valign="top"><strong>InlineDecoratorMapper</strong></td>
<td>Used to determine the correct Decorator when using inline decorators.</td>
</tr>
<tr>
<td><strong>LanguageDecoratorMapper</strong></td>
<td>Can determine the preferred language set in the browser requesting a page,
and map to a suitable Decorator (using the "Accept-Language" HTTP header).</td>
</tr>
<tr>
<td valign="top"><strong>PageDecoratorMapper</strong></td>
<td>The actual Page determines the Decorator to be used.
<p>The 'meta.decorator' and 'decorator' properties
of the page are accessed and if any of them contain the name of a valid
Decorator, that Decorator shall be applied.</p></td>
</tr>
<tr>
<td valign="top"><strong>ParameterDecoratorMapper</strong></td>
<td>Will choose the decorator based on request parameters.
<p>The ParameterDecoratorMapper is configured via three properties.</p>
<p><code>decorator.parameter</code> - the parameter which contains the name
of the decorator which will be mapped. The default is "decorator".</p>
<p>For example if <code>decorator.parameter</code> is "foobar" then
myurl.jsp?foobar=mydecorator will map to the decorator named "mydecorator".</p>
<p>You can also supply an optional 'confirmation parameter'.
The decorator will only be mapped if the parameter named <code>parameter.name</code> is
in the request URI and the value of that parameter is equal to the
<code>parameter.value</code> property.</p>
<p>For example assuming parameter.name=confirm and parameter.value=true
the URI myurl.jsp?decorator=mydecorator&confirm=true will map the decorator mydecorator.
where as the URIs myurl.jsp?decorator=mydecorator and myurl.jsp?decorator=mydecorator&confirm=false will
not return any decorator.</p>
</td>
</tr>
<tr>
<td valign="top"><strong>SessionDecoratorMapper</strong></td>
<td><p>Will look at a session attribute to find the name of an appropriate decorator to use. If the
session attribute is present, the mapper will not do anything and allow the next mapper in the chain
to select a decorator.</p>
<p>By default, it will look at the 'decorator' session attribute, however this can be overriden by
configuring the mapper with a 'decorator.parameter' property.</p></td>
</tr>
<tr>
<td valign="top"><strong>PrintableDecoratorMapper</strong></td>
<td>Will check to see whether 'printable=true' is supplied as a request parameter
and if so, use the specified decorator instead. The name of this
decorator should be supplied in the <code>decorator</code> property.</td>
</tr>
<tr>
<td valign="top"><strong>RobotDecoratorMapper</strong></td>
<td>Will use the specified decorator when the
requester is identified as a robot (also known as spider, crawler,
ferret) of a search engine. The name of this decorator should be
supplied in the <code>decorator</code> property.</td>
</tr>
</table>
<p>An example of a custom DecoratorMapper could be one that displays different
Decorators based on time (e.g. morning, afternoon, Christmas, etc).</p>
<h3>Custom mapper configuration</h3>
<p>To be able to specify which mappers will be applied to a request, create the
file <code>[web-app]/WEB-INF/sitemesh.xml</code> that contains the following:</p>
<pre style="border: 1px solid #999999; padding: 5px">
<sitemesh>
<property name="decorators-file" value="/WEB-INF/decorators.xml" />
<excludes file="${decorators-file}" />
<page-parsers>
<parser content-type="text/html"
class="com.opensymphony.module.sitemesh.parser.HTMLPageParser" />
<parser content-type="text/html;charset=ISO-8859-1"
class="com.opensymphony.module.sitemesh.parser.HTMLPageParser" />
</page-parsers>
<decorator-mappers>
<mapper class="com.opensymphony.module.sitemesh.mapper.ConfigDecoratorMapper">
<param name="config" value="${decorators-file}" />
</mapper>
</decorator-mappers>
</sitemesh>
</pre>
<p>In this example, the only mapper that will be applied is the <code>ConfigDecoratorMapper</code>,
and that will only be applied to responses of type <code>text/html</code> or
<code>text/html;charset=ISO-8859-1</code>. Responses of any other content type (eg
<code>image/gif</code>) will be ignored by Sitemesh. Additionally, any files that match a
pattern specified in the <code>excludes</code> file (in this case <code>'/WEB-INF/decorators.xml'</code>)
will not be touched by Sitemesh.</p>
<p>The excludes file points to an XML file that contains an <code><excludes /></code> block
similar to the following:</p>
<pre style="border: 1px solid #999999; padding: 5px">
<decorators>
<excludes>
<pattern>/plainPage.jsp</pattern>
<pattern>/plain/*.jsp</pattern>
</excludes>
</decorators>
</pre>
<p>The above example would prevent <code>/plainPage.jsp</code> and any JSP pages in the
<code>/plain</code> directory from being decorated. (Note that the pattern matching follows
exactly the same rules as the decorator mappings used by the <code>ConfigDecoratorMapper</code>.)</p>
<p>Typically the <code><excludes /></code> block is just added at the start of the
<code>decorators.xml</code> file, however this is not a requirement and any other XML
file can be specified instead by changing the excludes file specified in <code>sitemesh.xml</code>.
This might be useful if for example the <code>ConfigDecoratorMapper</code> is not being used
in your deployment.</p>
<p>Note that preventing pages from being decorated by adding them to the excludes list
superceeds, and is a better approach than, the old method of mapping the pages to a
non-existent decorator. This is because when pages were mapped to a non-existent decorator
they were still buffered internally by Sitemesh. By using the exclude list Sitemesh will not
let the request pass straight through to the servlet container without any buffering.</p>
<h3>Default mapper configuration</h3>
<p>If <code>sitemesh.xml</code> is not found in the <code>WEB-INF</code> dir,
the default mapper configuration will be used. The default mapper configuration is
defined in sitemesh-default.xml (packaged inside the jar) and consists of the
following mappers:</p>
<ul>
<li>PageDecoratorMapper</li>
<li>FrameSetDecoratorMapper</li>
<li>PrintableDecoratorMapper</li>
<li>FileDecoratorMapper</li>
<li>ConfigDecoratorMapper</li>
</ul>
By default only content of type <code>text/html</code> will be decorated by Sitemesh.
</body>
</html>
|
