Template languages: Velocity and FreeMarker

IntelliJ IDEA lets you develop templates in Velocity (VTL) and FreeMarker (FTL).

Coding assistance and syntax highlighting rely on the Apache Velocity and FreeMarker plugins which are bundled and enabled in IntelliJ IDEA by default. If the relevant features aren't available, make sure that you didn't disable the plugin. For more information, refer to Open plugin settings.

The following file types are supported by default:

VTL	.ft, .vm, .vsl
FTL	.ftl, .ftlh, .ftlx

To enable coding assistance for languages in which the static part of the template is written (those are referred to as template data languages), do one of the following:

Associate the template data language with files and folders in your project

In the Settings dialog (Control+Alt+S), click Languages and Frameworks and then click Template Data Languages.
Click the template data language cell to the right of the project or the corresponding directory or file, and select the language.
Click OK to apply changes.

Individual template files can be assigned a template data language directly in the editor using the Change template data language to context menu command.

Add an extension pattern for the corresponding file types

In the Settings dialog (Control+Alt+S), click Editor and then click File Types.
Under Recognized File Types, select FreeMarker Template or Velocity Template.
Under File name patterns, click .
In the Add Wildcard dialog, specify the file name extension pattern, select a language, and click OK.
Click OK to apply changes.

Fixing unresolved references

IntelliJ IDEA provides inspections for detecting unresolved references in template languages:

Example template language inspection for unresolved references

Unresolved references can be fixed using intention actions. You can select to add a comment in the same file, or to create a separate file with comments. For more information, refer to Special comments.

Example template language intentions for fixing unresolved references

In the latter case, a file with the default name velocity_implicit.vm or freemarker_implicit.ftl is created. This file starts with the following comment:

#* @implicitly included *#

Code completion for defining reference types is available in the comments files.

If you rename the file or move it to a different location within the source root, reference definitions will not be lost.

Special comments

IntelliJ IDEA provides the following special comments for working with template languages:

FreeMarker comments are delimited using either <#-- and --> or [#-- and --#].

Comment	Description
`@implicitly included`	Any FreeMarker file that starts with this comment is included in all files that are in the same module or its dependencies. Use such a dedicated comments file to define IDE-specific comments, so that they do not pollute your template files.
`@ftlvariable`	Defines a variable. For example, the following comment declares a variable named `foo` of type `String`, visible only in the specified file: <#-- @ftlvariable name="foo" type="java.lang.String" file="path/to/file" --> To properly resolve `String` in this case, the module should have JDK attached. Primitive and generic types are supported. The `file` parameter is optional.
`@ftlroot`	Defines the path relative to which `import` and `include` directives are resolved. The path is specified relative to any of the directories in the current FTL file's package. Paths inside JARs are also supported, for example: <#-- @ftlroot "path/to.jar!/path/inside/jar" -->

Comment

Description

@implicitly included

Any FreeMarker file that starts with this comment is included in all files that are in the same module or its dependencies. Use such a dedicated comments file to define IDE-specific comments, so that they do not pollute your template files.

@ftlvariable

Defines a variable. For example, the following comment declares a variable named foo of type String, visible only in the specified file:

<#-- @ftlvariable name="foo" type="java.lang.String" file="path/to/file" -->

To properly resolve String in this case, the module should have JDK attached. Primitive and generic types are supported. The file parameter is optional.

@ftlroot

Defines the path relative to which import and include directives are resolved. The path is specified relative to any of the directories in the current FTL file's package. Paths inside JARs are also supported, for example:

<#-- @ftlroot "path/to.jar!/path/inside/jar" -->

Velocity comments are delimited using #* and *#.

Comment	Description
`@implicitly included`	Any Velocity file that starts with this comment is included in all files that are in the same module. Use such a dedicated comments file to define IDE-specific comments, so that they do not pollute your template files.
`@vtlvariable`	Defines a variable. For example, the following comment declares a variable named `foo` of type `String`, visible only in the specified file: #* @vtlvariable name="foo" type="java.lang.String" file="path/to/file" *# To properly resolve `String` in this case, the module should have JDK attached. Primitive and generic types are supported. The `file` parameter is optional.
`@vtlmacrolibrary`	Defines the file with template macros relative to the file with this comment. For example, the following comment makes macros from `lib.vm` accessible to code insight in `file.vm`: #* @vtlmacrolibrary path="lib.vm" file="file.vm" *#
`@velocityproperties`	Defines the velocity.properties file and the runtime root directory relative to the file with this comment. For example: #* @velocityproperties path=”path/to/velocity.properties” runtime_root=”path/to/runtime/root/dir” *#

Last modified: 05 September 2023