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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<document>
<properties>
<title>VelocityViewServlet</title>
<projectfile>xdocs/project.xml</projectfile>
<subprojectfile>xdocs/view.project.xml</subprojectfile>
</properties>
<body>
<section name="Overview">
<p class="note">
This page is still unfinished.
Much of this needs to be moved or at least
copied to a VelocityView page, as it
applies to anything using a
<a href="javadoc/org/apache/velocity/tools/view/VelocityView.html">VelocityView</a>
instance under the covers (including the
<a href="view.tag.html">VelocityViewTag</a>).
<a href="index.html#Contribution">Help is welcome!</a>
</p>
<p>
<a href="javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html">Javadoc is here</a>.
</p>
<p>
A typical application use-case for the VelocityViewServlet
is to provide the view rendering layer for
a servlet-based web application framework. The
<a href="struts.html">VelocityStruts</a> subproject
uses the approach to bring Velocity templates to the Struts 1
application framework.
</p>
</section>
<section name="Installation">
<p>The VelocityViewServlet needs to be installed into your servlet container
so it can handle all request for *.vm (velocity template) files. There are
only two additional configuration files, and they are shown in
detail below.</p>
<subsection name="Servlet Setup">
<p>
The servlet configuration (<strong>web.xml</strong>) must be
modified to include a reference to the VelocityViewServlet
(or subclass thereof) which will perform the rendering. All *.vm files are
mapped to this servlet which will populate the 'context' with
Request, Session, and Application scopes plus any additional tools
specified by your configuration (or provided as defaults). The servlet
will use this contextual information and the Velocity Engine to
render the template file.
</p>
<p>
<strong>Note:</strong> Additional functionality can be achieved
through subclassing the VelocityViewServlet, and will be discussed further in
the <a href="view.layoutservlet.html">VelocityLayoutServlet page</a>.
</p>
<p><b>web.xml</b></p>
<sourcecode>
<!-- Define Velocity template handler -->
<servlet>
<servlet-name>velocity</servlet-name>
<servlet-class>
org.apache.velocity.tools.view.VelocityViewServlet
</servlet-class>
<!--
Unless you plan to put your tools.xml and velocity.properties
under different folders or give them different names, then these
two init-params are unnecessary. The
VelocityViewServlet will automatically look for these files in
the following locations.
-->
<init-param>
<param-name>org.apache.velocity.toolbox</param-name>
<param-value>/WEB-INF/tools.xml</param-value>
</init-param>
<init-param>
<param-name>org.apache.velocity.properties</param-name>
<param-value>/WEB-INF/velocity.properties</param-value>
</init-param>
</servlet>
<!-- Map *.vm files to Velocity -->
<servlet-mapping>
<servlet-name>velocity</servlet-name>
<url-pattern>*.vm</url-pattern>
</servlet-mapping>
</sourcecode>
</subsection>
<subsection name="Velocity Configuration">
<p>
Velocity configuration is <strong>optional</strong>, and for
most applications the defaults will work fine. The
<strong>velocity.properties</strong> file contains settings that
affect logging, encoding, and macro settings.</p>
<p>The default configuration specifies the location of a 'global'
Velocimacro template. This file can contain macros which will be
made available to all templates.
</p>
<p>
The location of the configuration file may be specified in web.xml,
but it is recommended the file be placed inside the hidden WEB-INF
directory of the web application and named 'velocity.properties' which
is where the VelocityViewServlet will look for it in the absence of
any location specified in the web.xml.
An example configuration file is included with the distribution.
</p>
<p>
Please see the
<a href="http://velocity.apache.org/engine/devel/user-guide.html">Velocity User's Guide</a>
for more information on Velocity configuration.
</p>
<sourcecode>
velocimacro.library = /WEB-INF/VM_global_library.vm
velocimacro.permissions.allow.inline = true
velocimacro.permissions.allow.inline.to.replace.global = false
velocimacro.permissions.allow.inline.local.scope = false
velocimacro.context.localscope = false
</sourcecode>
</subsection>
<subsection name="Toolbox Configuration">
<p>
The toolbox file (located at <strong>/WEB-INF/tools.xml</strong> by
convention), maps out the "tools" and data we want available for
our templates to use. It's easier than that sounds.
</p>
<p>
Think about asking our friend Jon to grab us a 'wrench' from a
real toolbox. Jon just needs to know which wrench we want (metric,
pipe, crescent etc,). He doesn't need to know what the wrench does
nor what we are planning to do with it.
</p>
<p>
The Velocity Toolbox works the same way, we must only specify
which tool we want, and then the Velocity engine takes
care of the rest by making any public method available to the
template. For example, from the definitions below, the template
could call <code>$wrench.size</code>.
</p>
<p><b>PipeWrench.java</b></p>
<sourcecode>
public class PipeWrench {
public String getSize() {
return "Large Pipe Wrench!";
}
}
</sourcecode>
<p><b>tools.xml</b></p>
<sourcecode>
<?xml version="1.0"?>
<tools>
<toolbox scope="application">
<tool key="wrench" class="PipeWrench"/>
</toolbox>
</tools>
</sourcecode>
<p class="subsubSection">Toolbox Scopes</p>
<p>
You may have noticed that toolbox support built into VelocityView
also provides support for specifying the scope of your toolbox with
regards to the servlet environment.
Toolboxes may be placed within the <i>request</i>,
<i>session</i>, or <i>application</i> scopes of your web app.</p>
<p>The scope that you set for your toolbox will determine the
lifecycle of the tools within it:
</p>
<ul>
<li>
<i>application</i> scoped tools will be instantiated only once when
first used by a template and then reused by all templates for each
subsequent request. Due to this, it is <em>strongly</em> encouraged
that your application scoped tools be completely threadsafe. The
<a href="javadoc/org/apache/velocity/tools/generic/MathTool.html">MathTool</a>
(one of the <a href="generic.html">GenericTools</a>) is a good example
of tool meant to be application scoped.
</li>
<li>
<i>session</i> scoped tools are instantiated at most once
per unique session (if they are used by a template processed
for that session) and are then reused for every request
associated with that particular session.
</li>
<li>
<i>request</i> is the most common scope.
Tools with this scope are instantiated at most once per
servlet request fed to that VelocityView (if they are used by
a template processed during that request).
</li>
</ul>
<p class="subsubSection">Tool Path Restrictions</p>
<p>You can specify a restriction on the request URIs for which the tool
will be available in the context using the "restrictTo" attribute of
your tool configuration.
It can be an exact request path (matching one page) or end with the
<code>*</code> wildcard, meaning that incoming request paths need only
start with the provided value for the tool to be available.
For instance:</p>
<sourcecode>
<tool restrictTo="/catalog/*"
class="com.mycompany.tools.CatalogTool"/>
</sourcecode>
<p>
You may have noticed that this example tool configuration doesn't
have a "key" attribute. This is because VelocityTools 2 honors the
[Key]Tool naming convention. So a tool with the simple name of
"CatalogTool" will automatically be given the key "catalog" unless
another key is specified in the tool configuration or using the
<a href="javadoc/org/apache/velocity/tools/config/DefaultKey.html">DefaultKey</a>
annotation on the class.
</p>
<p class="subsubSection">Tool Properties</p>
<p>
The toolbox support built into VelocityTools also provides
support for passing configuration properties to tools.
If a tool has a
<code>public void configure(java.util.Map params)</code> method,
then VelocityTools will pass that method a map of all properties
set on the tool configuration, the toolbox to which it belongs and
properties set for the whole configuration.
</p>
<p>
VelocityTools will also use Commmons-BeanUtils to set any or all
of those same properties directly on the tool if their keys and types
have a matching public set[Key](Type) method on that tool.
</p>
<p>
These things happen immediately
after a tool instance is instantiated and before it is available to
your templates. This gives much flexibility in designing and configuring
your tools.</p>
<p>
You can specify properties for your tools, toolboxes or all tools
either as <property> tags or as attributes:
</p>
<sourcecode>
<tools foo="true">
<toolbox scope="application" someProperty="whatever">
<property key="bar">woogie</property>
<tool key="myTool" class="com.foo.tools.MyTool">
<property name="my.parameter.name" value="my.parameter.value"/>
</tool>
</toolbox>
</tools>
</sourcecode>
<p class="subsubSection">Static Data</p>
<p>
In addition to specifiying arbitrary Java classes as <b>tools</b>
to be automatically available to your templates, the toolbox support
also includes the ability to specify arbitrary strings, booleans,
numbers, lists of those, and even BeanUtils-convertable types to be
automatically available in your templates. The format
is as follows:
</p>
<sourcecode>
<?xml version="1.0"?>
<tools>
<data type="number" key="version" value="1.1"/>
<data key="startdate" value="Mon Sep 17 10:08:03 PDT 2007" class="java.util.Date"
converter="org.apache.commons.beanutils.locale.converters.DateLocaleConverter"/>
<data type="boolean" key="isSimple" value="true"/>
<data key="foo" value="this is foo."/>
<data key="bar">this is bar.</data>
<data type="list" key="dataKeys"
value="version,date,isSimple,foo,bar,dataKeys,switches"/>
<data type="list.boolean" key="switches" value="true,false,false,true"/>
</tools>
</sourcecode>
<p>
As with your tools, your data will be exposed to your templates
under the specified key (e.g. $version, $startdate, $isSimple,
$foo, $bar, $dataKeys and $switches). Unlike
tools, data does not go in a toolbox and is not scoped (as it is
necessarily static).
</p>
</subsection>
</section>
</body>
</document>
|
