In addition to the powerful tools dotCMS provides for displaying content dynamically, dotCMS also includes many tools to ingest and display content from external sources.
Ingesting External Content
You may import and parse content in all of the following formats in dotCMS. Please click the link for each format for information and links to the documentation pages for each format listed below.
Text and HTML
There are two main ways to import text into a dotCMS object or page:
- The #dotParse command can be used to insert the contents of a named resource within your dotCMS system (such as an uploaded file).
- The Import Tool can be used to insert the contents of a named external resource (such as an external HTML page) into your page, providing a simple and effective alternative to an iframe.
When using either of these tools, please note the following:
- Characters in imported text will still be interpreted by the Velocity parser and the user's browser.
- For information on how to escape plain text to avoid parsing, please see the Preventing Parsing section of the Include of a .vtl or .html file documentation.
- The #dotParse command has better performance than the ImportTool.
- If a page or objects is are expected to have high traffic, you should import the text into dotCMS as a File or other content, and then use the #dotParse command to include the text.
Cookies
The CookieTool Velocity viewtool can be used to set and retrieve cookie values from within your Velocity code, including cookies which have been set previously by other pages or sites. For more information, please see the CookieTool documentation.
Files
There are two ways of accessing files in dotCMS, either as individual files uploaded into dotCMS, or as binary files uploaded into other dotCMS content. Since files uploaded as binary files must be uploaded one at a time and are always tied to a specific content item, in many cases you may want to upload files as individual files within dotCMS, allowing you to upload files in bulk and access the same file from multiple pieces of content.
You can upload files of any type into dotCMS as individual files in two different ways:
- Manually on the dotCMS backend (through the Site Browser tab, either individually or through the Multiple Files option)
- In bulk using dotCLI.
Once files have been uploaded into your dotCMS system, you can access them easily from within dotCMS. For example, you can easily display and process image files, access file metadata, import HMTL, text or code, or use many of the other methods described in this document to process files in different formats for use in your code or display on your site.
JSON
The JSONTool Velocity viewtool allows you to ingest a JSON object and use Velocity to iterate over each child object with simple velocity that is easy to manage and read. For more information, please see the JSONTool documentation.
Markdown
The MarkdownTool Velocity viewtool allows you to display markdown formatted text on your pages. The MarkdownTool supports the popular Github version of Markdown. For code examples and more information, please see the MarkdownTool documentation.
RSS
The RSSTool Velocity viewtool allows you to pull an external RSS or ATOM feed to retrieve full or summarized text, publishing dates, authorship, etc. For more information, please see the RSSTool documentation.
SQL
The SQLTool Velocity viewtool allows you to perform simple or parameterized SQL queries against an external database, and iterate over the results of the pull using simple Velocity. For more information, please see the Executing a SQL Query documentation.
Velocity
By default, any text included on your page will be interpreted by the Velocity parser, so any time you import VTL code into your dotCMS system and display it, the Velocity code will be executed.
If you wish to explicitly evaluate text using the Velocity parser, you may also use the RenderTool Velocity viewtool. This can be useful, for example, when combining elements of objects into a single Velocity statement, or when you wish to recursively evaluate Velocity code.
In addition, you can perform checks to determine whether an imported resource contains Velocity code using the VelocityTool viewtool.
Web APIs
You can import the output from most web APIs into a dotCMS object, which you can then access and manipulate using Velocity code. Which methods you use to access the web API will depend on the output format of the API; for example, many web APIs produce output in JSON format, so web APIs are often accessed in dotCMS using the JSONTool Velocity viewtool.
For an example of using the JSONTool to access an external web API, please see the Visitor Geolocation documentation, which includes code to access the Maxmind GeoLite2 Geolocation database using the GeoLite2 web API, and then accesses the object to retrieve geolocation information about the current visitor in dotCMS.
Wiki Formats
The WikiTool Velocity viewtool can parse wiki formatted content, including Mediawiki, textile, confluence, tracwiki and twiki markup. For code examples and more information, please see the WikiTool documentation.
XML
The XML Tool Velocity viewtool allows you to use Velocity to iterate over XML objects retrieved from an XML page. For code examples and more information, please see the XML Tool documentation.
XSLT
The XSLTTool Velocity viewtool can transform XML documents into other formats given a link to the XML document and a link to the XSL for the transformation. For code examples and more information, please see the XSLTTool documentation.
