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.

From 3.10, multilingual virtual URLs are supported. The system keeps track of the URLs in a table which basically consists of three columns:

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 re-directions, page reloads, etc. The language mask field is used internally by the system to identify which languages the alias is associated with (based on the same bit-field algorithm as for content objects).

If the site administrator creates a virtual URL for accessing the "content/search" interface, the system will add a new entry to the table:

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

http://www.example.com/findme

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

http://www.example.com/content/search

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. If an object exists in several languages, the system will generate virtual URLs for all translations. 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 corresponding URLs.

Objects, nodes and nice URLs.

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.

In eZ Publish 3.9 and earlier versions, URL transformation rules were more restrictive and only supported some ASCII characters (lowercase Latin letters from "a" to "z", digits and underscores). Special symbols were converted to underscores and special characters were converted using the built in transliteration feature. For example, the Norwegian characters "æ", "ø" and "å" were converted to "ae", "oe" and "aa". If the system was about to generate a virtual URL that already existed, it would simply append an underscore at the end of the newly generated address and thus the risk of having duplicate URLs was eliminated.

From 3.10, it is possible to enable Unicode support for the URLs and thus no transliteration needs to be performed since most characters are allowed. If there are two nodes with identical or almost identical names within the same location, the system will generate unique URL aliases for newly introduced conflicting nodes by attaching numbers to their URL aliases (for example, "Company", "Company2", "Company3" and so on).

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

It is possible to manually add, edit and remove virtual URLs using the administration interface (both global aliases and node URL aliases). Refer to "Managing URL aliases" for more information. In addition, wildcard based URL forwarding is supported. (This feature was removed when implementing the multilingual URLs functionality for eZ Publish 3.10.0 and then re-added in later versions.)