Include of a .vtl or .html file - Documentation topics on: dotparse,html,include,vtl,.

Include of a .vtl or .html file

The #dotParse() command can be used to include an HTML or VTL file in dotCMS. #dotParse will include the contents of the specified file.

Note: The contents of the included file will be parsed with both the Velocity and HTML parsers. For information on how to prevent parsing of the file contents, please see Preventing Parsing, below.

Calling Conventions

  • #dotParse accepts a path to a Velocity or HTML file in dotCMS or accessible via a URL.
  • The extension of the file parsed must be .vtl, .vm or .html.
  • #dotParse can be called in any Velocity context, including Templates, other #dotParse includes, Containers, Widgets, Custom Fields and Content.

Syntax

#dotParse may be called in the following contexts:

Using a Relative Path (to the dotCMS Site Browser tree)

#dotParse("/application/vtl/my-file.vtl")

Using an Absolute Path

#dotParse("http://demo.dotcms.com/application/vtl/my-file.vtl")

Across Hosts on the Same dotCMS Instance

#dotParse("//myhost.com/velocity/mycode.vtl")

By Identifier

#dotParse("/dotAsset/$identifier.vtl")

#dotParse 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 #dotParse:

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

Preventing Parsing

#dotParse automatically parses the included file using both the Velocity and HTML parsers. You must take additional steps if you wish to prevent parsing by the Velocity or HTML parsers.

Prevent Velocity Parsing

If you wish to include a file without applying the Velocity parser to the file, you can use the $import.read() method instead, and enclose it in the Velocity notation which prevents Velocity parsing:

#[[
    $import.read("http://demo.dotcms.com/test/import.html")
]]#

Note:

  • The file will still be parsed by the HTML parser (so any “<", ">“, or “&” chars will be interpreted).
  • The performance of #dotParse is better than the performance of $import.read().
    • So for any page which receives significant traffic, you should instead upload the file to be imported into the dotCMS system and use #dotParse instead.

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

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.