Partial Content

Working with eZ Publish 5 - Content Templates

Now that you have the surround running in Twig templates, it's time to take over those content templates from the legacy template system and create Twig templates for those too. 

First, let's catch up your tutorial code for this step by updating your branch to tutorial-2. As with last time, note that this will erase your local changes for the sake of consistency, so if you have things you want to keep, commit them as a new branch. 

Clean up your working directory:

git checkout -- *
git clean -f -d 

and pull down the next step of the tutorial:

git checkout -b tutorial-3 origin/tutorial-3 

This includes our template and asset additions from the last step.

In the legacy eZ Publish template system, there was a rules-based system that the CMS used to decide which template would be used for a given content object based on its type, location, the type of appearance requested (view) and other rules. An analogous system is in place for eZ Publish 5, but it's a bit cleaner and more extensible. 

First, let's create a template for our 'Blog' content type, which is the kind of page we've been looking at when we load the root of the site. In our bundle, create the directory Resources/views/full, and add a 'blog.html.twig' file in it. Add this content to the file: 

{# This template extends pagelayout.html.twig and just replaces the 'content' block #}
{% extends noLayout ? viewbaseLayout : "BlendPartialContentBundle::pagelayout.html.twig" %}
{% block content %}
    {# The 'location' variable contains info about the current position in the site and some metadata #}
    <h1 class="page-title">{{ location.contentInfo.name }}</h1>
    <article class="extra description">
        {# The 'content' variable contains the content object we're viewing #}
        {# ez_render_field is a twig helper function that uses either twig or legacy templates to render the
           data from the field
        #}
        {{ ez_render_field( content, "description" ) }}
    </article>
    Blog posts will go here
{% endblock %}

The 'extends' keyword declares that this template inherits from the pagelayout.html.twig, which means that our page will look just like that template, except our new template markup will be plugged in to the 'content' block. This seems similar on the surface to eZ's former templating system, but keep in mind that the template will be rendered in a single step - both the inner and outer template will have access to the same variables.

Go ahead and create a 'blog_post.html.twig' in that same 'full' folder: 

{% extends noLayout ? viewbaseLayout : "BlendPartialContentBundle::pagelayout.html.twig" %}
{% block content %}
    <article class="body">
        <h1 class="page-title">{{ location.contentInfo.name }}</h1>
        <div>
            {{ ez_render_field( content, "body" ) }}
        </div>
    </article>
{% endblock %}

Nothing new there, just more of the same.

The next step is to tell eZ Publish about our new templates. This means configuring the template system in the yml files. To keep things familiar, we'll create an override.yml and include it, sort of like the override.ini files you might be familiar with from the legacy system.

Up in the htdocs/ezpublish/config folder, create a new file, override.yml, and add these rules to it:

#This ezpublish.system preamble states the context these rules apply in
ezpublish:
    system:
        # The siteaccess
        ezdemo_site_user:
            location_view:
                # Type of the view. 'full' is when an object represents the whole page
                full:
                    # name for our rule
                    blog:
                        # template to use
                        template: BlendPartialContentBundle:full:blog.html.twig
                        # when to use this template (when the ContentType is 'blog') 
                        match:
                            Identifier\ContentType: blog
                    blog_post:
                        template: BlendPartialContentBundle:full:blog_post.html.twig
                        match:
                            Identifier\ContentType: blog_post

As you can see, you create a rule for each template to tell eZ Publish when you want to use it. Next, we need to tell eZ Publish to include our new ini file in its configuration. Add this to the top of htdocs/ezpublish/config/ezpublish.yml

imports:
    - { resource: override.yml }

This will include your new override.yml file in to the ezpublish.yml as though it were part of the file.

That's it. Refresh your page and you should see your new templates in use.

Screenshot of full view template in use

The rules for selecting templates in eZ Publish 5 are similar to those in eZ Publish 4, just with a new template language and configuration syntax. You can read more about it in the eZ Publish 5 documentation

Next we'll get some blog posts showing up by retrieving content from the repository.