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

URL handling

Whenever a link, a non-content specific image, a stylesheet, etc. is to be included, a suitable template operator must be used in order to ensure that the path to the included file is correct. At any time, one of the following operators should be used:

ezurl

The "ezurl" operator makes sure that a URL works regardless of the location of the eZ Publish folder, the access method and the environment that eZ Publish is running in (non virtual host, virtual host, etc.). It is only the eZ Publish specific part of the URL that needs to be provided. The rest (http://, host, domain, directory, siteaccess, port, etc.) will be generated by the operator. The final output will be a valid address. This approach makes it possible to use generic URLs in template without the risk of having to modify every address when the site is moved and/or when the access method is changed. By default, the "ezurl" operator outputs an address that is already encapsulated by two double quotes. In other words, the output can be fed directly to an hyperlink reference in the HTML code. The following examples demonstrate the usage of this operator.

Link to a module/view (using a system URL)

<a href={'/user/login'|ezurl()}>Login</a>

The example above demonstrates how to create a link to the login view of the user module. The "/user/login" is just an example, another example would be a link to a node: "/content/view/full/34". If eZ Publish is running in a directory called "ezpublish" on www.example.com using the URL access method and the name of the siteaccess is "my_company", the operator will produce the following output:

"http://www.example.com/ezpublish/index.php/my_company/user/login"

If eZ Publish is running in a virtual host mode and uses the host access method, the following URL will be produced:

"http://www.example.com/user/login"

Link to a node (using the node's virtual URL)

When a link to a node (using the node's virtual URL, also known as URL alias) is created, the address must be piped through the "ezurl" operator. The reason for this is that the internal URL table only contains the eZ Publish specific part of the URLs. The following example demonstrates how to use the "ezurl" operator to create a valid virtual URL for a node.

<a href={$node.url_alias|ezurl()}>Link to a node</a>

If the URL alias of the node is "company/about_us" and eZ Publish is running in a virtual host environment using the host access method, the following URL will be produced:

"http://www.example.com/company/about_us"

For information about how eZ Publish treats URLs, please refer to the "URL translation" section of the "Concepts and basics" chapter.

ezimage

The "ezimage" operator works in the same way as the "ezurl" operator (described above), except that it does not include the "index.php" part. This operator must be used every time a non content specific image is included in a template. The image must be placed in the "images" directory of one of the designs that are used by the siteaccess. The operator produces a valid link to the image regardless of the directory, access method and/or the environment that eZ Publish is running in. The following example demonstrates how the "ezimage" operator should be used.

<img src={'women.jpg'|ezimage()} alt="This is my image." ... />

If eZ Publish is using the host access method and the siteaccess is using a design called "my_design", the operator will produce the following output:

"http://www.example.com/design/my_design/images/women.jpg"

If the image is placed inside a subdirectory within the "images" directory, the name of the subdirectory must be specified in the template. If the requested file is not found within the main design of the siteaccess, the system will search for it in the additional designs and the standard design. Please refer to the documentation of the automatic fallback system for more information about this feature.

ezdesign

The "ezdesign" operator works in the same way as the "ezurl" operator (described above), except that it does not include the "index.php" part. This operator must be used every time a design element (style sheets, JavaScript, etc.) is included in a template. The operator takes care of producing a valid link for the given design component by providing the root to the design directory which contains the target file. The following example demonstrates the proper way of including a CSS file using this operator.

...
<style type="text/css">
    @import url({'stylesheets/my_stuff.css'|ezdesign()});
</style>
...

If eZ Publish is using the host access method and the siteaccess is using a design called "my_design", the operator will produce the following output:

"http://www.example.com/design/my_design/stylesheets/my_stuff.css"

If the requested file is not found within the main design of the siteaccess, the system will search for it in the additional designs and the standard design. Please refer to the documentation of the automatic fallback system for more information about this feature.

Balazs Halasy (03/03/2005 9:28 am)

Julia Shymova (19/06/2008 1:26 pm)

Balazs Halasy, Julia Shymova


Comments

There are no comments.