Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

URL translation

This section explains the different URL types that can be used with eZ publish and how the URL translator works. By default, eZ publish is capable of handling two types of URLs:

  • System URLs
  • Virtual URLs

System URLs

A system URL tells eZ publish about which module that should be run and which view that should be executed. It may contain additional parameters/values that are passed to the view itself. Every system URL follows the same structure and can be broken down into the following components:

  • Module name
  • View name
  • View parameters

The view parameters are optional and may consist of ordered and/or unordered values. A comprehensive description of the view parameters can be found in the "Modules and views" section. The following model shows the required sequence of the different URL components:


URL component



The name of the module that should be run.


The name of the view that should be executed.

Ordered view parameters

Some views make use of ordered parameters.

Unordered view parameters

Some views make use of unordered parameters.

The following example shows a typical system URL:


By looking at the URL, we can tell that it will instruct eZ publish to run the "content" module and execute the "edit" view. The values "13" and "3" are parameters that will be passed to the view itself. Please note that the exact style of the URLs depend on the access method that is used and the way the web server is configured. For example, the web server can be configured to hide away the "index.php" part of the address.

Virtual URLs

A virtual URL (also known as URL alias or nice URL) is nothing more than an alias for an existing system URL. Virtual URLs are nicer, easier to remember and sometimes shorter than system URLs. While system URLs reveal a great deal about what eZ publish is instructed to do, virtual URLs do not reveal any system specific information at all. A virtual URL can not be broken down to components in the same way as a system URL. The following example shows a typical virtual URL:


There are actually two types of virtual URLs, ones that are automatically generated and maintained by eZ publish and ones that are created and maintained by the site administrator. However, all virtual URLs are treated equally and thus they are handled in the same way. The system keeps track of the URLs in a table which basically consists of two columns: virtual/source address and system/destination address. An entry in the URL table might look something like this:

Virtual/source address

System/destination address



An actual URL using the virtual address in the table above could be the following:


According to the table above, the virtual URL will be translated internally to the following system URL:


Both URLs are perfectly valid and will produce the exact same output, in this case a full view of node number 46. When the virtual URL is used, the redirection/mapping will be done internally and thus the user will reach the target node without any glitches in form of redirections, page reloads, etc.

Automated virtual URL generation and maintenance

Every time an object is published, the system will automatically generate a virtual URL for each of the object's node assignments. The generated URL for a node is based on the node's location in the tree and the name of the object that the node encapsulates. The virtual URLs generated for the nodes are handled completely by the system and can not be changed using the administration interface. The following illustration shows an example of objects, nodes and a corresponding URL table.

Objects, nodes and the URL table.

Objects, nodes and the URL table.

The example above clearly demonstrates how the virtual URLs are generated. For each node, the system generates a path of strings separated by slashes. The strings in the path are the names of the objects that are referenced by the nodes up to and including the target node. Special symbols are converted to underscores and special characters are converted using the built in transliteration feature. For example, the Norwegian characters "æ", "ø" and "å" are converted to "ae", "oe" and "aa". If the system is about to generate a virtual URL that already exists, it will simply append an underscore at the end of the newly generated address and thus the risk of having duplicate URLs is eliminated.

When the name of an object is changed, the system will take care of changing the virtual URLs for the involved nodes. In addition, an internal redirection will be created, which will make sure that the old URL still works. The old virtual URL will keep working until the exact same URL needs to be generated for a node. In this case, the old virtual URL will be deleted.

Manual virtual URLs and translations

It is possible to manually add, edit and remove virtual URLs using the administration interface. The URL translator mechanism makes it possible to add three types of translations:

  • New virtual URL for an existing system URL
  • Secondary / alternative virtual URL for an existing virtual URL
  • Wildcard based URL forwarding

URL handling

When eZ publish receives a request, it looks at the URL that was sent by the web browser. The address is stripped for unnecessary parts such as for example the host/domain name, etc. If the address exists as a virtual URL in the table, eZ publish will attempt to process the corresponding system URL. If the address doesn't exist, eZ publish will attempt to interpret it as a system URL.

Balazs Halasy (03/02/2005 10:37 am)

Balazs Halasy (29/06/2005 12:02 pm)


  • URL translation with wildcard

    If you want the translation with wildcard, you have to set two links - one without and one with wildcard:

    myLink (new URL) ---> folder1/folder2 (existing url)
    myLink/* (new URL) ---> folder1/folder2/{1} (existing url)
  • NewWildcardURLAliasIsForwarding

    There is nice documentation in the "title" attribute of various input boxes. In case you can't see them, this is what it reads in "wildcard virtual url forwarding":

    Use this field to enter an address relative to the root of the system that should be translated into another URL. This address does not have to exist in your current system. You can place a star anywhere in the URL which will match an arbitrary number of characters.

    Use this field to enter a valid existing virtual URL in the system. A virtual URL is generated by the system and usually contains part of the content of an object. Any characters matched by a star in the source URL can be transfered to the destination URL by inserting {1} where appropriate.

    Use this checkbox to select if eZ publish should perform an internal redirect or a browser redirect. An internal redirect simply redirects the old URL to the new one without notifying the browser. A browser redirect makes the browser abort the current request and reload with the new URL. A browser redirect can be useful if you want the browser URL field to be updated.

    The last checkbox does not seem to make any difference. This might be a browser issue.