Route filters

Route filters allow you to change the the URLs generated by XenForo to more closely fit your needs.

Warning

Route filters are an advanced feature. They can create ambiguous URL structures that may prevent access to other pages. You should test your changes carefully after setting up a route filter.

What is a route?

A route is XenForo's term for the part of the URL that XenForo uses to determine which page to load. The Use Full Friendly URLs option will affect the URL but not the actual route. However, other options may affect the actual route generated.

For example, if you have installed XenForo into http://example.com/community/, the following examples highlight the route portion of the URL in bold:

  • http://example.com/community/index.php?threads/example.1/
  • http://example.com/community/threads/example.1/
  • http://example.com/community/index.php?threads/example.1/page-2
  • http://example.com/community/threads/example.1/page-2
  • http://example.com/community/index.php?threads/example.1/&example=query
  • http://example.com/community/threads/example.1/?example=query

The examples that show index.php? will be the URL without friendly URLs enabled. You can use this guide to determine the route for any URL.

Defining a Route Filter

A standard route filter is bi-directional. It changes the generated URLs to your specified version and then, when a user loads that URL, it converts it back to the standard XenForo version so that it can be processed. As such, the Find Route value should be the standard XenForo route and the Replace With value should be what you want the route to look like.

Both the find and replace fields can have wild cards. Wild cards take one of the following forms:

  • {name} - this will match anything other than a /
  • {name:digit} - this will only match digits
  • {name:string} - this will match anything but a / or .

The same wild cards must be in both the find and replace fields

Route filters always match from the very beginning of a route. A route filter does not have to match the whole root. It will match as much as it can and leave the rest as is. This means that you can focus on changing exactly what you want to change, without affecting more specific parts of the URL.

To prevent errors, a route filter must always begin with a route prefix that does not contain a wild card. Essentially, this means that you can't specify a wild card before the first / in the find or replace fields.

If you wish to create a route filter that is uni-directional, you can select the Incoming URL conversion only option. This effectively allows you to redirect an old route to a new route without changing the value of the new route. If this is selected, any user visiting a route that matches the replace value will be redirected to the find value automatically.

Note

The route filter manager and editor is found under the Setup section of the admin control panel.

Example 1: Changing a Route Prefix

The default URLs in XenForo are in English. You may wish to change these to be in your preferred language. For example, in Spanish, "forums" is "foros". To setup a route filter to do this you would enter:

  • Find route: forums/
  • Replace with: foros/

This will automatically match all URLs within the forums route prefix, such as forums/example.1/ which would become foros/example.1/

As another example, you may have our Resource Manager add-on installed and you prefer to call it Downloads. You could simply change resources/ to downloads/

Example 2: Changing a Page Node Route

Page nodes in XenForo always have a URL structure of pages/page-name/, but maybe you have a hierarchy of pages like:

  • Parent (pages/parent/)
    • Child (pages/child/)
      • Grandchild (pages/grandchild)

With route filters, you can make your URLs have a hierarchy as well:

  • Find: pages/parent/, replace: parent/
  • Find: pages/child/, replace: parent/child/
  • Find: pages/grandchild/, replace: parent/child/grandchild/

This example also shows how you can remove the pages/ prefix from specific pages.

Warning

It's important to be very careful that your page name does not interfere with any standard URLs. If this interferes with standard URLs, this will break other places in XenForo.