5.5 Loading resources

In Velocity just as in other rendering techniques like JSP it is important to build output from multiple input files. For this, you need to be able to pull external resources into the rendering process.

Velocity supports the loading of external files by the #include and #parse directive, which both load external resources into the rendering process of a template.

Velocity does not allow you to include arbitrary files into your templates for security reasons. All included files will be loaded from ResourceLoaders configured in the Velocity configuration. Please consult the Developers Guide for information on how to do this.

File inclusion - #include

The #include directive allows the template designer to import a local file. Its contents replace the #include directive in the template. These contents are inserted as-is, they are not rendered through the template engine.

Multiple files can be loaded through a single #include directive, their names must be separated by commas.

Example 5.7. Including files into a Velocity Template

## Load the file one.txt into this template
#include( "one.txt" )

## Load multiple files into this template
#include( "one.txt","two.txt","three.txt" )

The file being included need not be referenced by name; in fact, it is often preferable to use a variable instead of a filename. This could be useful for targeting output according to criteria determined when the page request is submitted.

Example 5.8. Including a file named by a variable reference

#set ($seasonalgreetings = "christmas.txt")
#include( "greetings.txt", $seasonalgreetings )

Template inclusion - #parse

The #parse directive works similar to #include, but the contents of the file will be part of the template rendering process and all VTL elements in the file will be evaluted. The output will replace the #parse directive in the importing template.

Example 5.9. Including an external template

#parse( "one.vm" )

Like the #include directive, #parse can take a variable rather than a template. Unlike the #include directive, #parse will only take a single argument, you cannot load multiple templates with a single #parse directive.

Recursion is permitted; VTL templates can have #parse statements referring to templates that in turn have #parse statements.

Example 5.10. Parsing a recursive template

## ########################################
## Template "countdown.vm"
## ########################################
Count down.

#set( $count = 8 )
#parse( "counter.vm" )
All done with countdown.vm!
## ########################################


## ########################################
## Template "counter.vm
## ########################################
$count
#set( $count = $count - 1 )
#if( $count > 0 )
  #parse("counter.vm" )
#else
  All done with counter.vm!
#end
## ########################################


The resulting output:

Count down.
8
7
6
5
4
3
2
1
0

All done with counter.vm!
All done with countdown.vm!

To avoid infinitive recursion, the number of levels is limited through a configuration property. It is not possible to configure an infinite recursion depth. The default maximum number of recursions is 20.[11]

# Maximum number of #parse levels
directive.parse.max.depth = 10


[11] As we said, we wanted to make it hard to write templates that contain endless loops. Allowing recustion would have been too easy.