Include a VTL or HTML file

You can include any text file on your dotCMS instance (even a file on a different Site) within any content displayed by dotCMS.

Commands

There are two different ways to include files in content, depending on whether or not you want the text in the included file to be interpreted by the Velocity parser.

dotParse

The built-in #dotParse() command can be used to include the entire contents of a Velocity or HTML file. Its full syntax is as follows:

#dotParse(String filename[, Integer ttl])

That is, its first, required argument is a path to the VTL file to be parsed; its second, optional argument defines a TTL for the result — effectively encasing the directive in a #dotcache block.

Parsing conventions:

• The entire contents of the file will be passed through the Velocity parser so that all Velocity code in the file will be executed.
• The output of the Velocity code in the file will then be parsed with the HTML parser.

For information on how to prevent HTML parsing of the file contents, or to prevent portions of the file from being parsed by the Velocity parser, please see Preventing Parsing, below.

TTL Interactions

• When a dotParse directive is used without the TTL, and not already within a dotcache block, the contents are updated based on the value of the Page TTL.
• Or, if a dotParse directive is used without the TTL, and is within a dotcache block, the contents are updated based on the value TTL supplied in the dotcache block.
• Or, if a dotParse directive is used with the TTL, the contents are updated based on the value TTL supplied in the dotParse directive. *This is true whether or not the dotParse block is within a dotcache block or not.
• Lastly, if 2 or more dotParse directives in a row use different TTLs, or if some use the TTL and some don't, the code in each dotParse directive is updated based on their own TTLs.
  • In other words, the TTL from a dotParse directive should never affect any code other than the code inserted by that dotParse directive.

dotInclude

The built-in #dotInclude() command can be used to include any file in dotCMS.

• The contents of the file will not be passed through the Velocity parser.
  • Thus any characters in the file which would normally be interpreted by Velocity can remain unescaped in the file.
• The contents of the file will still be parsed by the HTML parser.
  • For information on how to prevent HTML parsing of the file contents, please see Preventing Parsing, below.
• By default, only files with certain extensions will be accepted.
  • The following extensions are accepted by default:
    • .css
    • .htm
    • .html
    • .js
    • .json
    • .txt
  • You may change the extensions accepted by adding the VELOCITY_INCLUDE_ALLOWED_EXTENSIONS property to the dotmarketing-config.properties file.

    VELOCITY_INCLUDE_ALLOWED_EXTENSIONS=css,htm,html,js,json,txt
    

Calling Conventions

• Both commands accept a path to a file in dotCMS.
  • The included file must be located within the same dotCMS instance; both commands will fail if the included file is located outside of dotCMS.
  • To include a file outside the same dotCMS instance, please see Including Text from an External Link, below.
• Both commands can be called in any Velocity context.
  • This includes Templates, other files included with #dotParse or #dotInclude (e.g. recursive includes), Containers, Widgets, Custom Fields and Content.
• For the #dotParse() command only, the extension of the file parsed must be .vtl, .vm or .html.

Syntax

Both #dotParse and #dotInclude may be called in the following contexts.

Note: Although all the examples below use the #dotParse command, all contexts apply equally to the #dotInclude command.

Note: Including Files by Identifier

Including a file in this way allows you to include files from other types of contents such as dotAssets. It also ensures that the file will still be found and included properly even if the file is moved or renamed at a later date, so this method may make sense if you know the file name and location may be changed in the future.

Automatic Edit Link

Both of these commands will automatically include an edit link to the parsed file when you are in Edit mode. The edit link can be disabled by adding #set($dontShowIcon=true) before you call either command:

#set($dontShowIcon=true)
#dotParse("/application/vtl/my-file.vtl")

Preventing Parsing

#dotParse automatically parses the entire included file using both the Velocity and HTML parsers, and #dotInclude automatically parses the included file using the HTML parser. You must take additional steps if you wish to prevent parsing of any file by the HTML parser, or to prevent #dotParse from parsing a portion of the file with the Velocity parser.

Prevent HTML Parsing

If you display the contents of a file on a Page, the file will automatically be interpreted by your browser's HTML parser. Therefore, if you wish to display the contents of the file without HTML parsing, you must escape the special HTML characters in the contents of the file.

Individual HTML characters may be escaped using either HTML & notation or the dotCMS EscapeTool Velocity viewtool.

You may escape all of the HTML characters in imported text at one time using the $esc.html method of the EscapeTool, but be aware that HTML escaped in this way may not contain line breaks and other formatting necessary to display the escaped HTML in an easily readable format on the page.

Prevent Velocity Parsing

If you wish to prevent a portion of the included text from being parsed by Velocity, you can do one of the following:

1. Break out the portion of the file you don't want parsed into a separate file.

You can then include the parseable and unparseable files separately (using #dotParse and #dotInclude, respectively).

2. Add Velocity “do not parse” notation within the included file.

Within the included file, enclose the unparseable portion of the file in the Velocity notation which instructs the Velocity parser to ignore that block of text.

#[[
    ...do not parse this text...
]]#

Note that when you use either of these methods, all included text will still be parsed by the HTML parser (so any <, >, or & chars will be interpreted). Please see Prevent HTML Parsing above for more information.

Including Text from an External Link

Both #dotParse and #dotInclude are designed to only allow you to include the contents of files on the same dotCMS instance. However if you wish to include the contents of a file or page from another site, you may use the ImportTool Velocity Viewtool provided with dotCMS. For example, the following command imports the entire contents of the Apache Velocity 1.7 user's guide:

$import.read("http://velocity.apache.org/engine/1.7/user-guide.html")

For more information on the $import.read() method, please see the ImportTool documentation.