xdocs/config.xml - velocity-tools - Git at Google

 <?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>
	<?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>