Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

URL Redirection

[Note]Note

This feature is only available in the Professional release

Sometimes you need to create short, memorable URLs to some of your site's pages which Joomla!'s co-founder Brian Teeman calls PEF (Pub Ear Friendly). Arguably, telling someone to visit http://www.example.com/downloads is much easier than telling them to visit http://www.example.com/index.php?option=com_downloads&view=repository&task=list or even http://www.example.com/site-resources/download.html. Some other times you would like to use a short URL to an external site but do not wish to use one of the free services, like bit.ly, ow.ly, t.co or tinyurl.com for privacy reasons. Admin Tools to the rescue! The custom URL redirection feature allows you to do all of the above with a ridiculously simple interface.

The URL Redirection management page

The main administration page shows you a list of the custom URL redirections defined on your sites. Each entry consists of the following information:

  • The ordering handle. When you order the display by Ordering (ascending or descending) you can drag items using this handle to reorder them. URL Redirections are evaluated respecting this order.

  • The left hand checkbox. The toolbar operations will apply only to the checked items.

  • Visiting this. The relative path on your site which triggers the redirection. This URL must not be valid when the URL Redirection feature is disabled. For example, if your site is accessible at http://www.example.com/joomla and this field reads search/google, then all requests to http://www.example.com/joomla/search/google will be redirected to the Existing URL with a 301 (Permanently Moved) HTTP status code, to keep search engines happy. Clicking on the displayed value will open the Edit/Add page so that you can edit the entry.

  • Takes you there. The URL where your visitors will be taken to. This URL must be valid even when the URL Redirection feature is not enabled. It is existing content and you're about to create a new URL which will take your visitors to it. It can be a relative URL in your own site or an absolute URL to a different site. Clicking on it will open it in a new window so that you can preview the results.

  • Keep URL Parameters. If it's set to None any URL parameters sent by your visitors when they access the Visiting this URL will be discarded. If it's set to Override All then their URL parameters will override any and all URL parameters in the Takes you there URL. If it's set to Add new then their URL parameters will only be applied if and only if they do not already exist in the Takes you there URL.

  • Published. When unpublished, the redirection will not take place. Useful to temporarily take down a redirection without deleting it.

When adding a new entry or editing an existing entry, the following page appears:

The URL Redirection editor page

There are three fields to edit:

Visiting this

A relative path which triggers the redirection.

For example, if your site is accessible as http://www.example.com/joomla, entering google in this field will cause the URL http://www.example.com/joomla/google to redirect to the the URL you entered in the Existing URL field above. You can use subdirectories in your path, e.g. search/external/google.

Since Admin Tools 3.3.0 you can redirect internal URLs, which contain index.php. For example you can use index.php?option=com_foobar&view=abc to redirect this URL to somewhere else. Pitfalls: you must NOT put your site's URL in front of index.php. Moreover, if someone uses the URL index.php?option=com_foobar&view=abc&something=else (additional parameters) or index.php?view=abc&option=com_foobar (different parameter order) to access your site the URL redirection will NOT take place.

If you want to allow additional parameters in an internal URL you can use the form index.php?option=com_foobar&view=abc% (note the percent sign at the end) to allow any URL beginning with this text to be redirected. The pitfall is that if you use the format above the URL index.php?option=com_foobar&view=abcdef will also be redirected which may not be what you want. In this case you may want to try index.php?option=com_foobar&view=abc&% to redirect only URLs which have view=abc followed by other parameters. You can even place one or more % anywhere in the URL to redirect, for example index.php?option=com_foobar&view=abc&task=%&% to redirect URLs of the com_foobar component, abc view and any task followed by zero or more parameters.

Note that in an effort to make what you need to enter here more obvious your site's URL is already present in front of the field. This is a reminder that you must NOT type your site's URL. If your site is accessible from multiple URLs, e.g. http://www.example.com, https://www.example.com and https://example.com, the redirection applies on all site URLs even though they are not all printed out on this form. This is not a bug, it's the expected behavior. Joomla only reports the current URL your site uses, not all possible ones. The redirection applies to your Joomla installation, not a specific domain, subdomain or site URL.

Takes you here

An existing URL on your site, or a link to an external page.

When using a URL in your own site you should provide a relative URL, i.e. you should not include the URL to your site's root. Use the relative path instead. For example, putting index.php?option=com_frontpage is sufficient to display the front-end component. You can use either an index.php URL or a SEF URL (as long as you have SEF URLs turned on in your Global Configuration!).

The biggest strength of this feature is the ability to enter external links. For instance you can enter http://www.google.com to redirect your visitors to Google's search page. Using this powerful feature allows you to run your private URL shortening service on your own domain.

Keep URL Parameters

When set to None any query string parameters in the URL typed in by your visitor (i.e. anything after the question mark) will be ignored.

When set to Override All any query string parameters in the URL typed in by your visitor will override any parameters in the Existing URL, or added to it if they didn't exist in the first place.

When set to Add New any query string parameters in the URL typed in by your visitor which do not exist in the Existing URL will be added to it. Existing query parameters will not be overridden.

If you are trying to redirect a non-SEF URL (a URL with index.php inside it), e.g. index.php?option=com_foobar&something=123, you will very likely need to set this option to either None or Add New. If you fail to do that you might end up with a redirection loop. This is not a bug, it's perfectly reasonable. When you allow Overide All and try to redirect from one component (option=com_something) to another (option=com_another) the redirection URL will have its option parameter (com_another) overridden with the old option parameter (com_something). Since you are trying to redirect com_something you end up in a redirection loop which will cause the browser to complain.

Published

When unpublished, the redirection will not take place. Useful to temporarily take down a redirection without deleting it.

[Tip]Tip

If you want to make a simple redirection set Existing URL to the URL you are redirecting to, New URL to the URL you are redirecting from and Keep URL Parameters to None.

Use the Save button to save the changes and go back to the administration page, Save & New to save the changes and start entering the information for a new redirection, Apply to save the changes and return to this editor page and Cancel to discard all changes and return th the administration page.