Velocity Best Practices

Before stepping into dotCMS examples and custom tooling with Velocity code, it is important to understand and keep in mind the following best practices for writing velocity code in dotCMS. You will see these practices implemented in many of the code samples provided throughout the dotCMS documentation.

Use Formal Variable Notation

Velocity supports both formal and informal references to variables. All variable references in Velocity must begin with a dollar sign ($), and all variable names must begin with a letter (a-z or A-Z, not a number or punctuation). Formal references surround the variable name in curly braces (e.g. ${variable}, while informal references use the variable name without curly braces (e.g. $variable). However informal references (without the curly braces) must be surrounded by spaces.

You can use both formal and informal variable references within dotCMS, but it is recommended that you use formal notation as a default, because there may be cases where you need to use a variable with no space before or after the variable. For example:

This text${variable}is broken by a variable.

Using formal notation ensures that variable references are always unambiguous, and will always work regardless of your use of white space.

Suppress Display of Code When a Variable is NULL

Velocity supports both simple and null suppressed output variable notation. Simple variable references begin with a dollar sign only ($). Null suppressed variable references begin with both a dollar sign and an exclamation point ($!).

Whether you use formal or informal variable notation, when you use simple variable references, if the value of the variable is NULL, the velocity variable name will display (as code) on the page, rather than displaying nothing. When you use Null suppressed notation, variables which have null values are not displayed, as shown in the table below:

Using null suppressed notation ensures that you do not accidentally display code on your pages when your Velocity variables unexpectedly contain null values. Please also see Check Variable Assignment Before Use, below.

Check Variable Assignment Before Use

When referencing a variable value which is not assigned within your own code, use the $UtilMethods.isSet() method to check whether the variable is set before using the variable in your code.

#if ($UtilMethods.isSet($variable)))
    ...(your code)...
#end

This (along with using null suppressed variable notation) helps ensure that you don't unintentionally display null or unexpected output on your pages when your Velocity references haven't been set.

Allow Editing of Content Items from Pages

As a content creator or editor views pages on the dotCMS backend, they may see content which needs to be edited. It is inconvenient for the content creator to leave the page view, open the Content Search screen, and search for the content item that needs editing in order to change the content; instead, you can give the content creator the ability to edit the content directly from the page view, using the #editContentlet directive.

#editContentlet(inode)

In addition, you can set a page up for inline editing of content, so that when a content creator who has not logged in is browing the front-end of the web site and wish to edit a page, they may easily log into the dotCMS back-end to edit the last viewed page.

For more information on how to allow editing of content items directly from within dotCMS pages, please see the Editing Pulled Content documentation.

Separate Velocity Code into .vtl Files

You can use Velocity code in many places within dotCMS, including Themes, Templates, Containers, Pages, Widgets, Content, Custom Fields, Workflow Actions and more. Although you can enter code directly anywhere in dotCMS, code it is often more flexible to create code in files, and then include that code in the appropriate places using the #dotParse method. Included code has a number of benefits:

• Code permissions can be separated from content permissions.
• The same code can be re-used in multiple places.
• The version history of the code and the content items it's used in is maintained separately.
• Code files can be updated and maintained via dotCLI.
  • This also allows you to maintain the code in a version control system outside of dotCMS, if desired — including through GitHub integration.

The VTL Include Widget

In addition to the #dotParse method, you can also include a Velocity code file on a page using the VTL Include widget. The VTL Include widget allows you to browse for and select a VTL file (including a file on another dotCMS host and include it in your page without writing any code on the page.

Store and Access Velocity Files on a Common Server

If you host multiple servers on the same dotCMS instance, you can access your Velocity files on one dotCMS host from another dotCMS host by referencing the server name when including the Velocity file, as in the following example:

#dotParse('//server.domain/path/to/file.vtl')

This allows you to develop and maintain your code on a single site and use it from multiple sites, helping to ensure that all your sites use the same versions of your Velocity code files.

Don't Check Return Values on Macros

Velocity supports the creation of macros, which allow you to encapsulate sections of Velocity code for easy re-use within later code or pages.

It is important to understand that Velocity macros do not return values; if you wish to set a result value in a Velocity macro, you must instead set the value of a Velocity variable within the macro.

Unique Macro Names

When creating macros, it is important to ensure all macro names are unique; if multiple macros possess the same name, the macro manager may pick randomly between them, resulting in errors or undefined results.