Using the new eZ Platform view API

19 Oct 2015  | 
Edi Modrić
Using the new eZ Platform view API

eZ Platform is coming along nicely and soon we will have a final 1.0 release on our hands. Last week a new feature called the View API landed in master, and it will change the way you write your custom controllers.

The old way

Before, if you wanted to create an override rule for viewing your custom content type, you needed to specify it in a way similar to this:

ezpublish:
    system:
        frontend_group:
            location_view:
                full:
                    my_frontpage:
                        template: NetgenSiteBundle:override/full:my_frontpage.html.twig
                        match:
                            Identifier\ContentType: my_frontpage

You could have also specified your custom controller by adding this to the rule directly below my_frontpage config key:

controller: NetgenSiteBundle:FullView:viewMyFrontpage

and your controller basically overrode the built-in ez_content:viewLocation controller, but you still had to call it at the end of your controller, since it handled setting the HTTP caching headers. You were able to inject the custom parameters into $params argument and send it off to the built-in view controller, which then made sure your custom parameters were available to the Twig template as variables. Your controller action looked something like this:

public function viewMyFrontpageAction( $locationId, $viewType, $layout = false, array $params = array() )
{
    // some processing
 
    return $this->get( 'ez_location' )->viewLocation(
        $locationId,
        $viewType,
        $layout,
        $params + array( 'my_value' => $myValue )
    );
}

The new way

That all changes now. First of all, there are no more location_view rules. Well, there are, but they're deprecated and should not be used as they're being replaced with content_view rules. If you don't have a custom controller specified in your location_view rules, they will be silently converted to content_view rules and the new view API, and everything will work the way it did before. Nonetheless, you are encouraged to change them to content_view rules to keep everything clean.

If you, however, do use the custom controller (either in location_view rules or content_view rules), your override rules will be left as they are and will continue to use the old system detailed above. To migrate that overrides, you should first switch them to content_view rules and then rewrite your custom controllers to the new view API. Your new controller will look like this:

public function viewMyFrontpageAction( ContentView $view )
{
    // some processing
 
    $view->addParameters(
        array(
            'my_value' => $myValue
        )
    );
 
    return $view;
}

The $view object you receive (eZ\Publish\Core\MVC\Symfony\View\ContentView) will have everything you need so that you can work. Some of the convenient methods available enable you to get the content being viewed ($view->getContent()), location being viewed ($view->getLocation()), manipulate response (for setting the custom headers, for example) ($view->setResponse(new Response())), disable HTTP cache ($view->setCacheEnabled(false)), change the template ($view->setTemplateIdentifier( 'NetgenSiteBundle:override/full:my_frontpage_other_template.html.twig')), and so on.

One of the most used methods on $view object will probably be the one to add parameters to the view, shown in the example above. The parameters you add to the view will be available to the Twig templates as variables, just like before.

After you do your thing with the $view object and change it in any way you like, you will simply return it from your controller and eZ Platform will take care of rendering the template, setting the X-Location-Id header if you hadn't already done so, and setting and returning the response back to your browser.

Now, if that ain't cool, I don't know what is :)

Comments

blog comments powered by Disqus

Short backstory of our blog: Sharing our experience from various web projects based on eZ Publish / eZ Platform, Symfony, PHP, HTML5, MySQL, jQuery, CSS, etc. and focusing on solving the problems we encountered.

Subscribe to RSS feed

Tags