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.
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:
|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.
|Get the request URL for a URL mapped page.|
|Get the content object of a URL mapped piece of content.|
|Retrieves the parameter of the GET/POST variable |
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.
|Retrieves the visitor's public IP address.|
|Retrieves the base URL used to access a page.|
Can be used to construct parameter URLs for the current page.
|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 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:
|User Agent||Set to this Value When|
|DOTCMS-CMIS||The content is accessed from a CMIS client.|
|DOTCMS-HTMLPAGEDIFF||The content is queried and read in Preview Mode.|
|DOTCMS_PUSH_PUBLISH||The content is being Push Published to a Static Endpoint.|
|DOTCMS-SITESEARCH||Site Search is querying and reading your page.|
|DOTCMS-TIMEMACHINE||Time Machine is querying and reading your page.|
#if ($request.getAttribute("User-Agent") == "DOTCMS-SITESEARCH") ##Custom code... #end
The server's response (HttpServletResponse) is also available in all contexts. The methods available from the
$response object include the following:
|Generates a 404 error (“Page Not Found”).|
|Adds a |
|Sets the content mime type to |
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.
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:
|Assigns the value the value |
|Returns the value of the |
|Removes the |
|Destroys the user's session.|
Note: A new one will automatically be created on the next request.
|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.