OpenCms documentation
OpenCms documentation

Edit aliases dialog

The Edit aliases dialog allows to define sophisticated rewrite rules for the URLs of the current site. The dialog is an extended version of the SEO options dialog.

To open the Edit aliases dialog, go to the sitemap editor, click on the context menu in the main toolbar and choose the "Edit aliases" menu entry under the "Advanced" submenu. The dialog is available for workplace users with role administrator only.

Opening the edit aliases dialog

The user interface is divided into three parts:

  1. Create new alias / Edit aliases. In this area simple aliases can be edited. Simple aliases map a single alias path to a single target resource. If simple aliases have already been created with the SEO options dialogue, these will also appear here.
  2. Create new rewrite / Edit rewrites. In this area, rewrite aliases can be edited. See below for more details.
  3. Import / export. There are two buttons at the bottom to import and export simple aliases as well as rewrite aliases.
The edit aliases dialog
In order to create a new simple alias, define an alias path, a target page and an action. Valid alias paths consist of one or more segments, where each segment consists of a slash / and one or more characters. This means that they may not end with a trailing slash /. Use the plus sign in order to complete a simple alias definition. Changes will only be applied after clicking the "Save" button.

There are three actions available, temporary redirect, permanent redirect, and show page. The show page action requires to define a page ending with index.html as the target, folders will not work. For a detailed explanation of these actions, see the SEO options dialog.

While a simple alias maps a single path to a single resource, rewrite aliases match whole classes of paths by means of regular expressions and replace the matched class with a new URL.

Rewrite rules behave as follows:

  • the first matching rewrite rule is applied
  • no order is defined for the matching, thus it is not possible to define overlapping patterns
  • the pattern for a rewrite alias follows standard Java regular expression syntax
  • the replacement string uses the dollar syntax ($1, $2,...) to access capture groups, internally processed by the Java method java.util.regex.Matcher.replaceFirst()
  • the pattern will always be matched against the whole path
  • rewrite aliases have precedence over simple aliases, i.e., if a rewrite alias matches the current request's path, a simple alias for that path will not match.

There are three possible actions for rewrite aliases:

Temporary redirect (302). A temporary redirect will be sent to the browser with the replacement string as the new URL.

Permanent redirect (301). A permanent redirect will be sent to the browser with the replacement string as the new URL.

Passthrough. The request will be passed through. For this action, the target resource must be a page ending with index.html, folders will not work.

As with simple aliases, use the plus sign to complete a rewrite definition. Again, changes will only be applied after clicking the "Save" button.

Alias definitions can be exported and imported with the buttons at the bottom of the edit aliases dialog.

Clicking on the "Export" button triggers a CSV file download containing all aliases currently defined for the website. The CSV file will not include any unsaved alias changes from the dialog.

Clicking the "Import" button will open the import aliases dialog where one can select a file and configure the field separator used in the CSV file to import.

The import aliases dialog

The CSV file must have the following format:

"/news-alias-1","/demo/about/index.html","redirect"
"/news-alias-2","/demo/about/index.html"
"/demo/([a-z]+).html","/demo/$1-old.html","permanentRedirect","rewrite"

Each line consists of two, three or four fields.

If the line contains three fields, it is interpreted as a simple alias with the following field definitions:

  • Field 1: The alias path
  • Field 2: The site path of the alias target
  • Field 3: The action for the rewrite.
    • page: Show the page
    • permanentRedirect: Send permanent redirect
    • redirect: Send temporary redirect

Lines with two fields will also be interpreted as simple aliases, with the alias mode implicitly set to "permanentRedirect".

If the line contains four fields, it is interpreted as a rewrite alias, with the following field definitions:

  • Field 1: The alias pattern
  • Field 2: The replacement string
  • Field 3: The action for the rewrite
    • passthrough: Pass the rewritten path to the next resource handler
    • permanentRedirect: Send permanent redirect
    • redirect: Send temporary redirect
  • Field 4: Must be the constant value "rewrite"

All incoming alias requests are handled by the class org.opencms.main.CmsAliasResourceHandler, which is by default configured in the opencms-system.xml configuration file under the <resourceinit>-element. If this handler is removed from the configuration, the alias dialog is still available, alias definitions have no effect though.

In addition, aliases behave in the following way:

  • for paths which actually exist in the VFS and for paths that start with /system/ the alias resource handler is not being used
  • aliases are defined for a specific site; thus it is possible to use the same alias path in different sites
  • request parameters are not preserved for POST alias requests in combination with a redirect action