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
|
<?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>Overview</title>
<projectfile>xdocs/project.xml</projectfile>
</properties>
<body>
<section name="Overview">
<p>
A Velocity "tool" is just a POJO (plain old java object) that is
"useful" in a template and is not meant to be rendered in the
output. In other words, a "tool" (in Velocity-speak) is meant
to be used but not seen themselves (e.g. for formatting dates
or numbers, url building, etc).
</p>
<p>
The VelocityTools project is, first of all, a collection of such
useful Java classes, as well as infrastructure to easily,
automatically and transparently make these tools available to your
Velocity templates. Other aims of the project include providing
easy integration of Velocity into the view-layer of your web
applications (via the
<a href="view.tag.html">VelocityViewTag</a> and
<a href="view.servlet.html">VelocityViewServlet</a>)
and integration with Struts 1.x applications.
</p>
<p>
In recognition of these varying aims, the VelocityTools project is
divided into three parts: <a href="generic.html">GenericTools</a>,
<a href="view.html">VelocityView</a> and <a href="struts.html">
VelocityStruts</a>. Each of these parts builds on the previous one
and has its own JAR distribution.
</p>
<subsection name="GenericTools">
<p>
<a href="generic.html">GenericTools</a> is the set of classes
that provide basic infrastructure for using tools in standard
Java SE Velocity projects, as well as a set of tools for use
in generic Velocity templates. Perenial favorites here are
the DateTool, NumberTool and RenderTool, though there are many
others available as well.
</p>
</subsection>
<subsection name="VelocityView">
<p>
<a href="view.html">VelocityView</a> includes all of the
<a href="generic.html">GenericTools</a> structure and
specialized tools for using Velocity in the view layer of web
applications (Java EE projects). This includes the
<a href="view.servlet.html">VelocityViewServlet</a> or
<a href="view.layoutservlet.html">VelocityLayoutServlet</a>
for processing Velocity template requests and the
<a href="view.tag.html">VelocityViewTag</a> for
embedding Velocity in JSP. Popular tools here are the LinkTool
and the ParameterTool.
</p>
</subsection>
<subsection name="VelocityStruts">
<p>
<a href="struts.html">VelocityStruts</a> includes both
<a href="view.html">VelocityView</a> and <a href="generic.html">
GenericTools</a> and adds tools for use in Struts 1.x
applications. These tools match the functions of the key
Struts taglibs and provide access to Struts resources, messages,
tiles, validation functions and more.
</p>
</subsection>
<p>
It is worth noting that these tools, being POJOs (though some
require a little configuration) are generally useful and may be
used within your java classes or even other template languages,
though you may need to instantiate and configure them manually (not
difficult) to do so. VelocityTools 2 has been designed with this
in mind. Ask on the user mailing list if you have questions about
using VelocityTools without Velocity.
</p>
</section>
<section name="Why 2.0?">
<p>
Those already familiar with VelocityTools 1.x may be curious about
the goals and motivations behind developing VelocityTools 2.
In planning and developing the 2.0 release, there were three main
goals:
</p>
<ul>
<li>
Transparent, on-demand tool instantiation (aka lazy loading
for tools) - This allows you to have many tools available
(even ones that are expensive to instantiate), but not waste
time instantiating or initializing/configuring those you don't
use for every request.
</li>
<li>
More accessible, reusable infrastructure - This allows easier
access to tools outside of your templates and provides better
means to integrate VelocityTools support into other web
frameworks or even other view technologies
(e.g. VelocityViewTag).
</li>
<li>
Simpler, more flexible toolbox
<a href="config.html">configuration</a> - Now you can
configure via a
<a href="config.properties.html">properties file</a>,
<a href="config.java.html">plain java</a>, or really
whatever you want (though perhaps with a bit more work). No
<a href="config.xml.html">XML</a> required anymore; though,
if you do use it, it's now a lot better than it was.
</li>
</ul>
<p>
These things could not have been accomplished without rewriting
most of the core infrastructure and configuration code. At the
same time, we wanted to make it easy for people to upgrade from
the 1.x series. This led to the decision to aim for complete
backwards compatibility. Granted much has been deprecated and
those who directly used or extended the 1.x infrastructure will
have to update their code in just a few releases, but for the time
being they should be able to use 2.0 in their applications with
few problems. Those who merely used the old toolbox.xml format or
the old tools directly will be immediately able to take advantage
of the new infrastructure without even updating their
configuration, though eventually even the old toolbox.xml format
may be retired. Don't cry. You'll like the
<a href="config.xml.html">new one</a> better once
you get to know it! It can do much more with much less typing.
</p>
</section>
<section name="Subversion Repository">
<p>
All VelocityTools project code is maintained in the Subversion
repository which can be reached in a number of ways. The most
direct method of accessing the repository is through a
web browser, but to effectively work on the code, a
<a href="http://svn.tigris.org/links.html#clients">Subversion
client</a> is required.
</p>
<p>
Repository:
<a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/">
http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/
</a>
</p>
</section>
<section name="Helping Out">
<subsection name="Communication">
<p>
Feedback about the project, whether positive or gently critical,
is always helpful to those working on the project. Such feedback
may be sent to either the user@velocity.apache.org or
dev@velocity.apache.org
<a href="http://velocity.apache.org/contact.html">mailing lists</a>.
</p>
<p>
Another great way to help is to simply participate in conversations
on the mailing list. On the user list, you can help answer questions
that other users have. This frees the developers to focus on
development more than user support. On the dev list, you can
participate in design discussions and release votes to help
maintain the high quality of the releases and direct the future
directions of the project.
</p>
</subsection>
<subsection name="Contribution">
<p>
Those interested in furthering the development of this
project have an open invitation to jump in and help out.
We welcome your contributions!
Patches can be sent to the mailing list or attached to a
<a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a>
issue. The <a href="http://wiki.apache.org/velocity/VelocityTools">Wiki</a>
can also be a good place to discuss and develop ideas.
</p>
<p>A few good places to get started include:</p>
<ul>
<li>Documentation (patches for the site or additions to
the Wiki)</li>
<li>Improving the example apps</li>
<li>Working on unresolved tasks in
<a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a></li>
<li>Contributing to the
<a href="http://wiki.apache.org/velocity/VelocimacroLibrary">VelocimacroLibrary</a></li>
</ul>
<p>
Other project goals and proposals can be found in the project
<a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/STATUS?view=markup">STATUS</a> file.
</p>
</subsection>
<subsection name="Code">
<p>
When contributing code, it helps <strong>immensely</strong> if you follow
through with the things on this checklist, especially the coding conventions.
Keeping our code style consistent, our codebase stays easy to read and easy
to patch. Adding javadoc (and examples therein) simplifies the documentation
process and reduces confusion about the purpose of various methods and classes.
Tests make sure that things work as expected, especially as development continues
down the road. Of course, contributions that don't follow the checklist will
be considered and often accepted, but you can expect the project committers
to be slower and less enthusiastic in doing so. :)
</p>
<p><b>Checklist for Code Contributions</b>:</p>
<ul>
<li><a href="http://wiki.apache.org/velocity/CodeStandards">Velocity coding conventions</a></li>
<li>Javadoc included (the more detailed the better)</li>
<li>Examples included (in JavaDoc or as stand-alone template example)</li>
<li>Tests included (not required but <b>GREATLY</b> appreciated)</li>
</ul>
</subsection>
</section>
</body>
</document>
|
