RouteReference

Version compatibility

Route references are compatible with eZ Publish 5.3 / 2014.= 05

=20

Description
Solution
Usage=20
- Twig
- PHP
Extending the RouteReference generation process

=20

Description

Sometimes, when generating links to a resource, you need to modify the d= efault router's behavior.

Use cases can be:

Language switch links

Download links

Pass a Content item instead of a Location (and use its

mainL=
ocationId

)

Solution

The concept of RouteReference has been introd= uced, which works in the same way of Symfony's ControllerReference for sub-requests. A RouteReference rep= resents a route (to a location object, a declared route...) with its parame= ters and can be passed to the Router for link genera= tion.


The advantage of a RouteReference is that its par=
ams can be modified later, and then passed to the router (e.g. to generate =
a link to the same location in several different languages).
Furthermore, the RouteReference generation proces=
s can be extended to fit specific needs.
Usage
Twig
Prototype:

=20
ez_route( [routing_resource[, parameters_hash]] )=20



routing_resource can be any valid resource (route nam=
e, Location object...). If omitted (null), the current route w=
ill be taken into account.
parameters_hash is a hash with arbitrary key/values. =
It will be passed to the router in the end.



Minimal usage is pretty straightforward:

=20
{# With a declared route. #}
{% set routeRef =3D ez_route( "my_route" ) %}

{# With a location, given "location" variable is a valid Location object. #=
}
{% set routeRef =3D ez_route( location ) %}

{# Then pass the routeRef variable to path() to generate the link #}
<a href=3D"{{ path( routeRef ) }}">My link</a>=20


 
Passing parameters and play with the RouteReference:

=20
{% set routeRef =3D ez_route( "my_route", {"some": "thing"} ) %}

{# You can then add parameters further on #}
{% do routeRef.set( "foo", ["bar", "baz"] ) %}

{# Or even modify the route resource #}
{% do routeRef.setRoute( "another_route" ) %}

<a href=3D"{{ path( routeRef ) }}">My link</a>=20


PHP
You can easily generate links based on a RouteRe=
ference from PHP too, with the RouteRef=
erenceGenerator service:

=20
// Assuming we're in a controller
/** @var \eZ\Publish\Core\MVC\Symfony\Routing\Generator\RouteReferenceGener=
atorInterface $routeRefGenerator */
$routeRefGenerator =3D $this->get( 'ezpublish.route_reference.generator'=
 );
$routeRef =3D $routeRefGenerator->generate( 'my_route', array( 'some' =
=3D> 'thing' );
$routeRef->set( 'foo', array( 'bar', 'baz' ) );
$routeRef->setRoute( 'another_route' );

$link =3D $this->generateUrl( $routeRef );=20


Extending the RouteReference generation process
When generating the route reference, the RouteReferenceGenera=
tor service fires an MVCEvents::ROUTE_REFERENCE_GENE=
RATION (ezpublish.routing.reference_generation) event.=
 This event can be listened to in order to modify the final route reference=
 (adding/changing parameters, changing the route name...).
All listeners receive a eZ\Publish\Core\MVC\Symfony\Event\Rou=
teReferenceGenerationEvent object, which contains the current r=
equest object and the route reference.

=20
namespace Acme\AcmeTestBundle\EventListener;

use eZ\Publish\Core\MVC\Symfony\Event\RouteReferenceGenerationEvent;
use eZ\Publish\Core\MVC\Symfony\MVCEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MyRouteReferenceListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return array(
            MVCEvents::ROUTE_REFERENCE_GENERATION =3D> 'onRouteReference=
Generation'
        );
    }

    public function onRouteReferenceGeneration( RouteReferenceGenerationEve=
nt $event )
    {
        $routeReference =3D $event->getRouteReference();
        $request =3D $event->getRequest();

        // Let's say we want to change the route name if "some_parameter" p=
aram is present
        if ( $routeReference->has( 'some_parameter' )
        {
            $routeReference->setRoute( 'a_specific_route' );
            // We remove "some_parameter", as we don't need it any more
            $routeReference->remove( 'some_parameter' );
            // We add another parameter, just because it's fun :-)
            $routeReference->set( 'another_parameter', array( 'parameter=
s', 'are', 'fun' );
        }
    }
}=20




Service declaration:

=20
# AcmeTestBundle/Resources/config/services.yml
parameters:
    acme.my_route_reference_listener.class: Acme\AcmeTestBundle\EventListen=
er\MyRouteReferenceListener

services:
    acme.my_route_reference_listener:
        class: %acme.my_route_reference_listener.class%
        tags:
            - { name: kernel.event_subscriber }=20





A real life implementation example can be the LanguageSwitcher (eZ\Publish\Core\MVC\Symfony\EventListener\LanguageSw=
itchListener).