Request, Response and Session

dotCMS automatically maps the users request, session and the server's response to object for use in all Velocity contexts, including templates, pages, vtls, content, widgets, etc.

Request ($request)

The visitor's request object (HttpServletRequest) is available in all Velocity contexts. You can access the request by referencing the $request object in your Velocity code.

The following are several commonly used Request object methods:

For a complete list of methods available, please see the Java documentation for HttpServletRequest.

Accessing dotCMS User Agents

In addition to common User Agents, dotCMS also sets a request attribute when dotCMS tools are rendering pages. This allows you to specify custom behaviour when those tools are accessing and reading your pages. For example, when the Site Search is reading all your HTML Pages you may want to “hide” the footer of your HTML Pages from the index process to ensure only relevant information is indexed.

Note: These values are set in a request attribute named User-Agent, not in the User-Agent header.

The User-Agent request attribute is set to the following values by dotCMS depending on the internal dotCMS tool accessing your content:

Example:

#if ($request.getAttribute("User-Agent") == "DOTCMS-SITESEARCH") 
    ##Custom code... 
#end

Response ($response)

The server's response (HttpServletResponse) is also available in all contexts. The methods available from the $response object include the following:

Note: Once output from the server has started, you will not be able to redirect or modify many attributes of the response mid-stream (such as content-type, error code, and redirect); any attempt to do so will fail, and will generate an error in your logs.

You may also use the $response object to perform redirects; please see the Redirects documentation for details.

For a complete list of methods available to you, please see the Java documentation for HttpServletResponse.

Session ($session)

You can access the user's session (HTTPSession) via the $session object. The user's session can be used to store state and values that can be retrieved across pages.

Note: This viewtool cannot be used to set session variables directly from a static page — e.g., one served via CDN — but can still be utilized via the Scripting API in such a case.

Several of the most commonly used methods in the session are displayed below:

Note: In high volume systems, it is generally bad practice to store large amounts of data in a user's session, as it can fill up the server's memory.

For a complete list of methods available to you, please see the Java documentation for HTTPSession.

Session Lifespan

By default, the system invalidates a session after 30 minutes of inactivity. This limit can be adjusted through $session.setMaxInactiveInterval(maxIntervalInSeconds). Once a session is invalidated, no method of the $session object suffices to reinstate it; a browser refresh or similar becomes necessary to generate a new session. However, using virtually any method of the $session object will suffice to reset the inactive interval.

A client-side script can interact with the $session object via the Scripting API to keep a session alive. For example:

setInterval(myTimer, 600000);

function myTimer() {
   fetch('/api/vtl/keep-alive');
}

This activates the HTTP GET method of a custom keep-alive Scripting API once every 10 minutes. To create this example case, simply define a get.vtl file in /application/apivtl/keep-alive — or name it anything else you prefer. The contents of the VTL file can likewise be as simple as fetching a session's id, creationTime, lastAccessedTime, any attribute, etc. The data might be returned as follows:

$dotJSON.put("session-created", ${session.creationTime})

However, the Javascript example above isn't configured to receive a respons, and indeed the keep-alive doesn't need to return anything at all; it can consist entirely of the $session call.

$session.creationTime