Custom Routes (Static Routes)

Custom routes are used to define a URL-pattern for a specific action.

For example you have a newslist, which is generated out of a object list, and you want to give the news a detail page. Since objects are not reachable via the web and they have no template assigned you can use the custom routes to create this.

A configuration for a newslist could lool like this:

In the pattern you can define a regex, and the column "Variables" you can specify comma-separated the keys of the placeholders in the pattern regex.

This is how you can access the values of the variables (placeholders) you specified in the custom route:

$this->_getParam('YourKey');

The default variables can be accessed also the same way.

Create URL's out of Custom Routes (since build 516)

You can use the normal Zend_View helpers to generate a valid URL out of a custom route.

Simple Example: 

In the definition you have to define a name for the route and a reverse entry. The reverse entry is a string which can be handled by the PHP function vsprintf. The syntax for the formatting string can be found here.

In the template you can use the common URL view helper:

<?php echo $this->url(array("arg1","arg2"),"news") ?>

The resulting URL will be /news/arg1_arg2

Advanced usage with named placeholders and optional parts (since 1.3.3)

Since 1.3.3 it's also possible to use variables inside the reverse route as placeholders, which are filles automatically if they are available via the route.

You can define a placeholder in the reverse pattern with %THE_NAME, and it's also possible to define an optional part, to do so just enbrace the part with curly braces { } (see example below).

The above example matches for the following URL's:

/some-example/some~random~text_45
/some-example/This+is+some+random+text_998_category_776

As you can see the category part is optional.

Example 1: source url = /some-other-url

<?= $this->url(array(
        "text" => "This is some random text",
        "id" => 998,
        "categoryId" => 776,
        "getExample" => "some value"
    ),
    "example"
) ?>

Since there is no parameter available out of the route pattern you have to set every parameter + there is one parameter which is not in the reverse route, so that will be added as a normal GET parameter

Output will be: /some-example/This+is+some+random+text_998_category_776?getExample=some+value

Example 2: source url = /some-example/some~random~text_45

 <?= $this->url(array(
        "categoryId" => 776
    ),
    "example"
) ?>

The parameters text and id are available via the route pattern, so the will be added automatically if you don't specify them.

Output will be: /some-example/This+is+some+random+text_45_category_776

Example 3: source url = /some-example/some~random~text_45

<?= $this->url(array(
        "id" => 776
    ),
    "example"
) ?>

Output will be: /some-example/This+is+some+random+text_776

Dynamic controller / action / module out of the route pattern (since v1.4.2)

Since pimcore 1.4.2 pimcore supports dynamic values for the controller, action and the module. NOTE: This works only with named placeholders!
It works similar to the reverse route, you can place your placeholders directly into the controller.

The following screen should explain the way how it works: 

Advanced Usage - Direct the Request to a Plugin (since v1.4.2)

In the grid for the custom routes there is a hidden column "module", which can be shown by right clicking on a column head and enabling this column. When this column is filled, pimcore routes the request to a different module than the standard module (which ist website). Enter the name (= folder name) of the Plugin to which you want to route the request. Fill the other columns (route, controller, action ...) as always.

Responding 404 status code

Sometimes you want to trigger a correct 404 error within your controller/action (addressed by a custom route), for example when a requested object (in the route) doesn't exist anymore. 

This can be done anytime and anywhere in your code with: 

throw new Zend_Controller_Router_Exception("the requested object doesn't exist anymore");

This code triggers the error handler which shows the error page with the correct 404 status code. 

Example: 

public function testAction() {
    if(!$object = Object_Abstract::getById(intval($this->_getParam("id")))) {
        throw new Zend_Controller_Router_Exception("the requested object doesn't exist anymore");
    }
    
    //...
}

Related Forum Topic(s)

• Controllers without Documents and Static Routes