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
|
<?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>
<subprojectfile>xdocs/config.project.xml</subprojectfile>
</properties>
<body>
<section name="Configuration Overview">
<p>
The VelocityTools support infrastructure exists to
provide all your templates a common set of tools
and data. This is inspired by the
<a href="http://turbine.apache.org/turbine/turbine-2.2.0/pullmodel.html">
Pull MVC</a> model, which deviates from the strict MVC
purist approach out for the sake of convenience and
clarity. The goal here is to provide template authors
a common interface of data and functions across all
templates (we call this a "toolbox"), whether they
need all of those functions and data or not. This
saves the template author from having to remember what
keys were used where and makes it easy to drop a new
template (i.e. View) into an app without having to
modify the controller (which would typically involve
creating a new action class). The degree to which this
Pull MVC pattern violates MVC principles can (and
should) vary widely depending on your needs and goals.
</p>
<p>
The default VelocityTools 2 configuration does not
include any "gross MVC offenders", as such things
would be hard to generalize usefully. The default
configuration primarily includes tools for
manipulating values made available in the template's
context by a controller and a few for accessing static
resources.
</p>
<p>
However, it is likely that you will want to add your own data and
tools to your VelocityTools 2 configuration or at least want to
change the default settings of the standard tools. To that end,
configuration of your applications "toolbox(es)" can be done via
XML, Java or properties. Different configurations can also be
easily combined together.
</p>
<p>
There a few basic concepts to the configuration that
it is useful to know. First, what you are creating
a configuration for is a
<a href="javadoc/org/apache/velocity/tools/ToolboxFactory.html">ToolboxFactory</a>.
This factory produces your toolbox(es) as needed by
<a href="view.html">VelocityView</a> or your own
application. A factory can have any number of
toolboxes, all distinguished by their scope property.
There are three special scopes automatically recognized
by VelocityTools 2: "request", "application", and
"session". The "session" scope is only relevant within
a <a href="view.html">VelocityView</a> app, but the
other two may be useful anywhere. Placing a
tool within "request" scope means that a new instance
will be created for every context. Placing a tool
within "application" scope means that only one instance
of the tool will be created and shared throughout the
application, effectively acting as a singleton. This,
of course, means that thread-safety must be considered
when putting a tool in "application" scope.
</p>
<p>
Because of such concerns, Velocity Tools now provides
annotations to allow developers to restrict the scope(s)
in which a tool can be placed. For more on these and other available
annotations, see
<a href="creatingtools.html">Creating Your Own Tools</a>.
</p>
<p>
When the "application" toolbox is requested, the
ToolboxFactory will also include any "data" configured
for it. These are unchanging, static values that are
meant to be available to all templates in your
application. You can configure any number of data for
your application and the configuration supports both
automatic and explicit type conversion (via
Commons-BeanUtils
<a href="http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/org/apache/commons/beanutils/Converter.html">converters</a>
) for these values (since
XML and properties formats only allow string inputs).
</p>
<p>
Other things to know are that each toolbox can have
any number of tools within it, and that "properties"
may be added for any and all tools, toolboxes, and the
factory itself. A "property" added to one of these
also has all of the same type conversion support as
the "data" values do. Properties set on a toolbox are
made available to all tools within that toolbox and
properties set for the factory itself are made
available to all tools in your application.
</p>
<p>
Now on to the formats for specifying these things...
</p>
<ul>
<li><a href="config.xml.html">XML</a></li>
<li><a href="config.properties.html">Properties</a></li>
<li><a href="config.java.html">Java</a></li>
</ul>
</section>
</body>
</document>
|
