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:

http://www.example.com/index.php/<module>/<view>/[<ordered_view_parameters>]/[<unordered_view_parameters>]

The following example shows a typical system URL:

http://www.example.com/index.php/content/edit/13/3

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:

http://www.example.com/company/about

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:

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

http://www.example.com/company/about

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

http://www.example.com/content/view/full/46

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.

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.