Velocity and the dotCMS - The purpose of this document is to help one understand and get started with
using velocity(the template language used in templates, containers, and contentlets) in the dotCMS.
Velocity has its own documentation which can be downloaded fro velocity.apache.org.  This document is not
meant to replace the velocity document but is more to help one understand some of the not so obvious things
between Velocity and the dotCMS.  Before diving into this document it is recommended that one reads 
http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html.  Velocity 1.5 is the currently
the version of Velocity that the dotCMS uses. 

Velocity within the dotCMS is primarily used in templates, containers, and contentlets. The dotCMS
exposes most of the tools from velocity-tools 1.2.  You can download the package fro Velocity-tools1.2 and
look in its doc directory for more detailed information on how to use each tool.  You don't have to worry 
about the places where velocity tools tells you to place xml in the toolbox.xml as the dotCMS already has
all the above mentioned tools in it's toolbox. The Current Tools are as follows. 
The key for calling them using velocity in the dotCMS is listed after the hyphen of each tool

DateTool - date
    A tool for manipulating and formatting dates.
MathTool - math
    A tool for performing floating point math.
NumberTool - number
    A tool for formatting numbers.
RenderTool - render
    A tool to evaluate and render arbitrary strings of VTL (Velocity Template Language).
EscapeTool - esc
    A tool to help with common escaping needs in Velocity templates.
Alternator and AlternatorTool - alternator
    Utility class for easily alternating over values in a list and tool for easy creation of Alternators in templates.
ValueParser - parser
    A tool to retrieve and parse String values pulled from a map. This provides the basis for the ParameterParser in VelocityView.
ListTool - listTool
    A tool to help when working with arrays or Lists. This tool transparently handles both the same way.
SortTool - sorter
    A tool that allows a user to sort a collection (or array, iterator, etc) on any arbitary set of properties exposed by the 
	objects contained within the collection.
IteratorTool - mill
    A convenience tool to use with #foreach loops. It wraps a list to let the designer specify a condition to terminate 
	the loop, and reuse the same list in different loops. 
ImportTool - import
	General-purpose text-importing view tool for templates.
	
At times the dotCMS also uses Struts actions before a page gets sent to Velocity to be displayed.  Most people probably don't care
about these tags but for the sake of knowing they are available they are mentioned here. 
ErrorsTool - errors
	This tool deals with Struts error messages. Errors may stem from the validation of a submitted form or from the processing of a request. 
	If there are errors, they are made available to the view to render. 
MessageTool - text
	The MessageTool is used to render internationalized message strings. 
	Source of the strings are the message resource bundles of the Struts framework.
ActionMessagesTool - messages
  	This tool deals with Struts action messages.
FormTool - form
		Struts has support to parse incoming HTTP requests and populate a Java bean with the submitted request parameters. 
		The same Java bean is used to populate forms with initial values. Additionally, a hook allows the application developer to 
		include automatic form validation code.

The dotCMS also has a number of tools it provides.  The tools are listed below and the javadoc for them can be found in the
dotCMS api.  The dotCMS's api can be found under liferay/api.   If you do not already have the api built you can build it using ant.
Make sure you download Apache Ant and follow it's install instructions.  From the root of the dotCMS type ant javadoc.

	webapi - com.dotmarketing.viewtools.WebAPI
	commentsapi - com.dotmarketing.viewtools.CommentsWebAPI
	categories - com.dotmarketing.viewtools.CategoriesWebAPI
	cmsuser - com.dotmarketing.viewtools.CMSUsersWebAPI
	website - com.dotmarketing.viewtools.WebsiteWebAPI
	contents - com.dotmarketing.viewtools.ContentsWebAPI
	searchapi - com.dotmarketing.viewtools.SearchAPI
	sitemapapi - com.dotmarketing.viewtools.SiteMapWebAPI
	macro - com.dotmarketing.viewtools.DotCMSMacroWebAPI
	eventsapi - com.dotmarketing.viewtools.EventsWebAPI
	globalvars - com.dotmarketing.viewtools.GlobalVariableWebAPI
	nav - com.dotmarketing.viewtools.NavigationWebAPI
	virtualtourapi - com.dotmarketing.viewtools.VirtualTourWebAPI
	bannersapi - com.dotmarketing.viewtools.BannersWebAPI
	glossary - com.dotmarketing.viewtools.GlossaryWebAPI
	productwebapi - com.dotmarketing.viewtools.ProductWebAPI
	utilHtml - com.dotmarketing.util.UtilHTML
	config - com.dotmarketing.util.Config
	webevents - com.dotmarketing.viewtools.WebEventsWebAPI
	contentRating - com.dotmarketing.viewtools.ContentRatingWebAPI
	alertMessagesWebAPI - com.dotmarketing.util.AlertMessagesWebAPI
	favorites - com.dotmarketing.viewtools.FavoritesWebAPI
	tags - com.dotmarketing.viewtools.TagsWebAPI
	crypt - com.dotmarketing.viewtools.CryptWebAPI
	stringsapi - com.dotmarketing.viewtools.StringsWebApi

There are a number of variables which are availible to you from containers, templates, or contentlets.
From anywhere in the dotCMS you can use the following Velocity variables
	$quote
	$HTMLPAGE_INODE
	$HTMLPAGE_TITLE
	$HTMLPAGE_FRIENDLY_NAME
	$TEMPLATE_INODE
	$HTMLPAGE_META
	$HTMLPAGE_META
	$HTMLPAGE_SECURE
	$VTLSERVLET_URI
	$HTMLPAGE_REDIRECT
	$pageTitle
	$pageChannel
	$friendlyName
	$HTML_PAGE_LAST_MOD_DATE
	$EDIT_MODE

From a Container
	$SERVER_NAME
	$CONTAINER_IDENTIFIER_INODE
	$CONTAINER_INODE
	$CONTAINER_MAX_CONTENTLETS
	$CONTAINER_STRUCTURE_NAME
	$STATIC_CONTAINER
	$SORT_PAGE
	$containerInode
	$EDIT_CONTAINER_PERMISSION
	$ADD_CONTENT_PERMISSION
	$CONTENTLETS
	$CONTAINER_NUM_CONTENTLETS
	$CONTAINER_NAME
	$CONTAINER_STRUCTURE_NAME
	If the container has notes
		$CONTAINER_NOTES
	If the container is dynamic
		$CONTENTS_PER_PAGE
		$CONTENTS_PER_PAGE
		$CURRENT_PAGE
		$CURRENT_PAGE
		$LUCENE_QUERY
		
The following properties are avialible on content
		$content.permission
		$content.inode
		$content.identifier
		$content.contentTitle
		$content.contentLastModDate
		
For examples on how to use Velocity in the dotCMS and for some helpful tips see the Velocity Cheat Sheet.