Request, Response and Session - Documentation topics on: headers,httpservletrequest,httpservletresponse,httpsession,redirects,request,request parameter,session,url parameter,velocity,.

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:

Method ExampleDescription
$request.getParameter("id")Retrieves the parameter of the GET/POST variable id.
Note: Make sure to escape this method call if you use it on a page, to avoid XSS security issues:
id: “$UtilMethods.xmlEscape($!request.getParameter(“id”))“.
For more information on using URL parameters in your pages and Velocity code, please see the URL Parameters documentation.
$request.getHeader("user-agent")Retrieves the visitor's browser user agent.
Note: Can also be used to determine when pages are shown with internal dotCMS tools; for more information, please see below.
$request.getRemoteAddr()Retrieves the visitor's public IP address.
$request.getAttribute("javax.servlet.forward.request_uri")Get the request URL for a URL mapped page.
$request.getAttribute("")Get the content object of a URL mapped piece of content.
$request.getRequestURI()Retrieves the base URL used to access a page.
Can be used to construct parameter URLs for the current page.
$request.getSession().setAttribute('com.dotmarketing.htmlpage.language', '2')Sets a new language (Ex: language_id=2), in the current session.

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 its own User Agents when rendering its own pages, to allow 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.

The following custom User Agents are set by dotCMS depending on the internal dotCMS tool accessing your content:

User AgentSet to this Value When
DOTCMS-SITESEARCHSite Search is querying and reading your page.
DOTCMS-CMISThe content is accessed from a CMIS client.
DOTCMS-HTMLPAGEDIFFThe content is queried and read in Preview Mode.
DOTCMS-TIMEMACHINETime Machine is querying and reading your page.


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

Response ($response)

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

Method ExampleDescription
$response.sendError(404)Generates a 404 error (“Page Not Found”).
$response.addHeader("Powered-by", "dotCMS")Adds a Powered-by header to the response.
$response.setContentType("text/xml")Sets the content mime type to text/xml.

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. Several of the most commonly used methods in the session are displayed below:

Method ExampleDescription
$session.setAttribute("name", "Joe User")Assigns the value the value Joe User to the session attribute name.
Note: The name attribute is created if it doesn't already exist.
$session.getAttribute("name")Returns the value of the name attribute
(e.g., Joe User if used with the above example).
$session.removeAttribute("name")Removes the name attribute from the session.
$session.invalidate()Destroys the user's session.
Note: A new one will automatically be created on the next request.
$session.getAttribute("com.dotmarketing.htmlpage.language")Get the language currently selected by the visitor.

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.