xdocs/index.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>
     </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>
	<?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>