You can include any text file on your dotCMS instance (even a file on a different Site) within any content displayed by dotCMS.
- Calling Conventions
- Including Multilingual Content
- Preventing Parsing
- Including Text from an External Link
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() command can be used to include the entire contents of a Velocity or HTML file.
- 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.
#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.
- 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.
- For the
#dotParse()command only, the extension of the file parsed must be .vtl, .vm or .html.
#dotInclude may be called in the following contexts.
Note: Although all the examples below use the
#dotParse command, all contexts apply equally to the
|Relative Path (on the same dotCMS Site)|
|On a specific Site (on the same dotCMS instance)|
|Absolute Path (on any site)|
|By Identifier (please see Note below)|
Note: Including Files by Identifier
Including a file by identifier is not generally recommended, since it makes it difficult to identify which file is being included without performing a query to find the included file by its identifier. However including the file in this way 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:
Including Multilingual Content
The #dotParse() and #dotInclude() directives automatically account for multilingual files and content according to the appropriate Default Language Fall-through settings. When code that includes #dotParse() or #dotInclude() is placed on a page and evaluated, dotCMS will check to see if a version of the specified file exists in the user's selected language, and if so the appropriate language version of the file will be included. If a version of the specified file does not exist in the user's selected language, dotCMS will choose to either include the default language version of the file, or to include nothing, based on the
#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
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
#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:
For more information on the
$import.read() method, please see the ImportTool documentation.