Redirects, Rewrites, and Forwards
There are several ways to perform URL redirects and rewrites in dotCMS. Some methods, such as Vanity URLs and Tuckey Rewrite Rules always perform the rewrite or redirect when a user accesses the forwarding URL, while other methods such as [Velocity code] and [personalization Rules] allow you to only perform the redirect or rewrite under certain conditions.
Redirect Types: Redirect and Forward#
There are two basic ways to redirect a user to another URL: forwards and redirects (rewrites). A forward takes the visitor to the new URL without indicating to the browser or application that the URL has been redirected, and does not change the URL displayed in a visitor's browser. A redirect returns a code to the browser or application informing that the URL has been redirected, and replaces the URL in the visitor's browser with the new URL.
There are two different types of redirects, permanent (301) and temporary (302). Both behave similarly, except that search engines treat them differently, and using a 302 redirect may not pass the SEO benefits (e.g. page rank and link equity) to the new URL.
The following table summarizes the different redirect types:
| Status | Type | Visitor's URL | Description |
|---|---|---|---|
| 200 | Forward | Unchanged | The URL is forwarded to the new page without any notification to the browser, application or crawler that anything is out of the ordinary. |
| 301 | Permanent Redirect | Rewritten | - The application is redirected to the URL and notified that this is a permanent redirect. - Passes the SEO benefits of the original URL to the new URL. |
| 302 | Temporary Redirect | Rewritten | - The application is redirected to the URL and notified that this is a temporary redirect. - May not pass the SEO benefits of the original URL to the new URL. |
Redirect Methods#
dotCMS provides multiple different methods to perform forwards and redirects. The method you use determines:
- What redirect types you can use,
- Whether the redirect always happens or can be limited based on specific conditions (specified either via the user interface or code)
- Whether the forwarding URL must be a fixed value or can be matched using a pattern.
- Whether parameters can be used to extract some portion of the forwarding URL and include it in the redirected URL.
Note: The most common method for performing redirects is Vanity URLs. It is recommended that you use Vanity URLs for your redirects unless you have need of other features which are not available in the Vanity URLs feature.
The following table shows the different redirect methods available:
| Method | Supported Types | Trigger on/nConditions | URL Matching | Param Replacement |
|---|---|---|---|---|
| Vanity URLs | 200, 301, 302 | No | Regular expression | Yes |
| Rules (Personalization) | 301 | Yes | Exact match | No |
| Tuckey Rewrite Rules | 200, 301, 302 | No | Regular expression | Yes |
| Velocity: $response.sendRedirect | 301 | Yes | Exact match or URL Map pattern | Yes |
| Velocity: Set Response Headers | 301, 302 | Yes | Exact match or URL Map pattern | Yes |
Redirect Using Velocity Code#
You can perform redirects with Velocity code by calling the $response.sendRedirect method or setting the response headers.
Important:
Any time you use Velocity code to perform a redirect, you must follow the commands that perform the redirect with the Velocity #stop command. If you do not include the #stop, the redirect will fail with errors.
$response.sendRedirect Method#
In Velocity, you can perform redirects directly from a page or template using the $response.sendRedirect method. For example, the following code will send a 302 (temporary) redirect to the visitor's browser when added to the top of pages or in your templates:
$response.sendRedirect("$YOUR_NEW_URL") #stop
Setting Response Headers#
To control the redirect status (301/302), you can set the response headers as in the following example:
$response.setStatus(301) $response.setHeader("Location", "$YOUR_NEW_URL") #stop
Note: Since the above code sets HTTP Headers, it must be placed at the top of the page, before any HTML code which will be sent to the user's browser.