ImportTool

The Import Tool is a general-purpose text-importing viewtool, which allows you to import the contents of a text file into your page.

The following example shows how the import viewtool is mapped in the toolbox.xml file:

    <tool>
        <key>import</key>
        <scope>request</scope>
        <class>org.apache.velocity.tools.view.tools.ImportTool</class>
    </tool>

Note:

• Text imported using the Import Tool will be passed through both the Velocity and HTML parsers.
  • For information on how to prevent imported text from being intepreted, please see the Preventing Parsing documentation.
• The Import Tool is intended for accessing remote resources (on a server other than your dotCMS server).
  • For both security and performance reasons, it is strongly recommended that you instead use other tools such as content pulls, includes, or the REST API to access content on your dotCMS server.

Usage

$import.read( URL, Timeout )

Limitations

Keep mind that any use of the $import.read("https://remoteUrl.com/") is a synchronous server side call and is only going to be as reliable and as responsive as the endpoint https://remoteUrl.com/ that the $import.read is calling. If that remote endpoint has a latency of a few seconds, it means that every dotCMS page that calls that endpoint is going to hang for a few seconds before the page can begin to render. On a loaded site, or a site that does a $import.read call on every page (say in a header or footer) this can block all the receiving threads in tomcat and take a server down. Use of this tools should be either page or block cached in order to maintain performance.

Parameters

Notes:

• The timeout is specified in milliseconds (not seconds).
• The timeout value is optional.
  • If no timeout value is specified, the default timeout (normally 15000) is used.
  • The default value may be changed by modifying the URL_CONNECTION_TIMEOUT property found in the dotmarketing-config.properties file.
• The timeout specifies the total time to wait to both make the connection perform the read.
  • The Import Tool will automatically kill the connection after the specified time, regardless of what state the import is in.
  • Therefore the timeout should be greater than the time it takes for both the connection and read.
• The $import.read() call will not follow redirects, since following redirects could potentially introduce security vulnerabilities.
  • Therefore you must specify the full direct path to the resource (including appropriate use of http:// vs. https://, depending on the server configuration) in the call.

Examples

Default Timeout

The following method inserts the contents of the http://www.foo.com/bleh.jsp?sneh=bar URL into the page, using the default timeout:

$import.read("http://www.foo.com/bleh.jsp?sneh=bar")

Specify Timeout and Prevent Parsing

The following imports the same URL, with a timeout ensuring that the connection will be terminated after 3 seconds, and enclosed with formatting commands to ensure the imported text is not interpreted by the Velocity parser:

#[[
    $import.read("http://www.foo.com/bleh.jsp?sneh=bar", 3000)
]]#

For more information on how to escape imported text to avoid parsing, please see the Preventing Parsing section of the Include of a .vtl or .html file documentation.

Toolbox.xml Configuration

The Import Tool is enabled by default in dotCMS. To ensure the Import Tool is enabled, verify that the following lines exist in your toolbox.xml file:

<tool>
    <key>import</key>
    <scope>request</scope>
    <class>org.apache.velocity.tools.view.tools.ImportTool</class>
</tool>