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
|
<?xml version="1.0"?>
<!--
Copyright 2000-2004 The Apache Software Foundation
Licensed 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>Differences: Velocity vs. WebMacro</title>
<author email="jon@latchkey.com">Velocity Documentation Team</author>
<author email="geirm@optonline.net">Velocity Documentation Team</author>
</properties>
<body>
<section name="Differences: Velocity vs. WebMacro">
<p>
On the mailing lists, we often get asked to explain the differences
between Velocity and WebMacro. Instead of answering the same question
over and over, we have started this document to describe some of the
differences in our approaches. In reality, both are excellent tools and
we feel that it is up to the user base to decide which one they would
like to use.
</p>
<p>
The language syntax is very close but not exactly the same. The syntaxes
were kept close for a few reasons:
</p>
<p>
1) The syntactical approach of $<foo> for references and
#<bar> for directives is a good one! It's easy for designers to
work with, people understand it, and there was no reason to reinvent the
wheel.
</p>
<p>
2) Since so many people were using the syntax, why invent another one?
Also, it makes the WebMacro to Velocity conversion much easier :) We
even have a <a href="migration.html">tool</a> to help with that.
</p>
<p>
Velocity was built new from the ground up. There isn't a snippet of
shared code. This was originally done because WebMacro was released
under a license (GPL) that is not compatible with the BSD/ASF license
and we (the original authors) needed a solution that was not under a GPL
license. Since then, WebMacro has been released under a dual GPL/ASF
license, however, that was too late, this project was already well
underway and we also felt that we have a better technical solution by
going with a generated parser instead of a hand coded one.
</p>
<p>
By starting new and fresh, we are less encumbered with some of the
baggage that WebMacro must deal with due to backwards compatibility
issues. We have fixed a few of the template language inconsistencies
that we saw creeping into WebMacro such as the fact that we do not
support using {} for code blocks (because we do not need to) and that we
use () around all #directives on the right hand side. Examples:
</p>
<source><![CDATA[#set ($bar = "foo")
#if ($bar.length() > 0)
stuff here
#end
]]></source>
<p>
Architecturally, the biggest difference until recently was the parser.
The Velocity parser is written using a tool called javacc, a very
popular Java-based parser generator. It was originally developed for
Sun by Metamata and is now maintained and managed by Metamata as well :
<a href="http://www.metamata.com/">www.metamata.com</a>.
</p>
<p>
The WebMacro parser was written by hand until recently and was the cause
of much pain when using WebMacro (due to many bugs in it) - their new
parser, for their 0.95 release is also written using javacc and promises
to be better (however, support for a lot of the baggage still exists).
</p>
<p>
Velocity is very simple in its architecture, as it is meant to be
nothing more than a template engine. The idea is to do one thing only
and do it well. Much in the spirit of the Unix philosophy - have a good
set of simple tools, and create bigger things using them. This has
enabled Velocity to be used as the basis for several different tools,
such as <a href="anakia.html">Anakia</a> and <a
href="texen.html">Texen</a>.
</p>
<p>
Velocity is recognized that it isn't going to try to be a 'development
framework' - there are plenty around, such as <a
href="http://jakarta.apache.org/turbine/">Turbine</a>.
</p>
<p>
Therefore, all facilities like 'context tool' and 'resource brokers' are
purposely left out of Velocity, acknowledging that not only will
frameworks do it, they will do it better anyway. Further, by leaving out
of the Velocity core much that should be done at the application / user
/ framework level, the Velocity core remains smaller and therefore, in
our opinion, more maintainable and extensible.
</p>
<p>
Internally, Velocity is pretty straightforward. There are no threads
created or managed for you. Templates are parsed and caches, kept in
their internal form of an 'Abstract Syntax Tree', a tree structure that
is then rapidly walked when your template is merged. Each node
corresponds to on of the syntactical elements in your template.
</p>
<p>
Internally within WebMacro, many of the methods and classes are marked
as private and/or final in order to achieve better speed. However, this
has prevented people from easily extending or overriding some of the
core funtionality and re-using some of the code. We would rather
sacrifice a few ms in favor of allowing more people to use our software
easily.
</p>
<p>
The biggest feature difference between the two are the '<a
href="user-guide.html">Velocimacros</a>'. Velocimacros can be thought of
as snippets of re-usable data that can contain anything. They are parsed
just like the data in a #parse() statement would be and you can pass in
variables that can optionally have scope only within the Velocimacro.
Velocimacro's help keep the core #directive set small and
clean : you can extend the designers toolkit with libraries of Velocimacros
rather than adding elements to the syntax or having two write tools that generate
HTML (or other specific) markup.
</p>
<p>
We hope this helps. The best way to understand Velocity is to use it,
and of course nothing beats looking at the source code.
</p>
</section>
</body>
</document>
|
