dotCMS - Open Source Content Management System, Ondemand CMS, and Professional Support

Velocity and dotCMS

Velocity is programming code that permits web page designers to reference methods defined in Java code.   Velocity allows dotCMS java methods to be exposed and utilized on contentlets, containers, and templates.

dotCMS leverages the power of Velocity code to create dynamic pulls of content on webpages that automatically update themselves as new content is published.  Furthermore, the dotCMS downloads with dozens of pre-written Velocity macros that can be called with only a few lines of Velocity code.

Velocity has its own documentation which can be reviewed at velocity.apache.org:

http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html

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 from Velocity-tools 1.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 its toolbox.
The Current Tools are listed below and the key for calling them using velocity in the dotCMS is displayed 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 available 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 available 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 Examples, Tips, and Tricks documentation.