URL Parameters

You may pass parameters to any dotCMS URI via the standard request header convention, consisting of a question mark, followed by the parameter name, an equal sign, and the parameter value. You may retrieve and check the value of the parameter in the page using Velocity code to dynamically change the behavior or content displayed in the page.

Passing Parameters in the URL

To pass a single URL parameter, enter the normal URI of the page or other resource followed by the standard question mark (?) notation to identify the parameter. For example:

http://my.domain.com/normal/path?parameter=value

To pass multiple parameters to the same URL, pass all parameters after the first parameter using an ampersand (&) and then the normal notation for the additional parameters. For example:

http://my.domain.com/normal/path?parameter1=value1&parameter2=value2&parameter3=value3

Retrieving Parameters in Your Pages and Widgets

To retrieve the value of any parameter, use the Velocity $request.getParameter("parameter_id") method to access the value of the parameter from within your code.

Important Security Considerations

Since URL parameters can be entered by users directly, it is possible for security exploits to be attempted by entering compromising code or characters in the value of URL parameters, which could then be executed if the parameter values are displayed directly in you page or widgets.

Therefore it is strongly recommended that, whenever you display or use URL the values of URL parameters in your page or code, you escape the parameter values using the $UtilMethods.xmlEscape() method. This method automatically escapes any special characters and code which might be used to attempt to execute unwanted code in your pages.

The following example demonstrates how to use the xmlEscape() method to sanitize a URL parameter value:

$UtilMethods.xmlEscape($!request.getParameter("parameter_id"))

Example

The following code retrieves and checks the value of a “department” URL parameter, modifying a query used to pull content for the page based on the value (if any) passed to the parameter:

#if($UtilMethods.isSet($request.getParameter("department")))
    #set($department        = $!request.getParameter("department"))
    #set($search_department = " +employee.department:$department")
#else
    #set($search_department = "")
#end

<ul>
    #foreach( $staff in $dotcontent.pull("+contentType:employee"$!{search_department}, 10, "employee.lastName, employee.firstName" )
        <li>$staff.lastName, $staff.firstName: $staff.department</li>
    #end
</ul>

Thus, for example, if the page was a top-level page named “employees”, then the page could either be accessed via a URL of the form http://my.domain.com/employees?department=engineering to display a list of all employees in the Engineering department, or via a URL of the simple form http://my.domain.employees to display a list of all employees in all departments.

Notes

For more information on the $request object and the $request.getParameter() property, please see the Request, Response and Session documentation.

For more information on performing content pulls and queries using Velocity, please see the Pulling and Displaying Content documentation.