Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Skip to end of metadata
Go to start of metadata

The ViewController

eZ Publish comes with a native controller to display your content, known as the ViewController. It is called each time you try to reach a content item from its Url Alias (human readable, translatable URI generated for any content based on URL patterns defined per Content Type) and is able to render any content previously edited in the admin interface or via the eZ Publish Public API.

It can also be called directly by its direct URI : /content/location/<locationId>

A content item can also have different view types (full page, abstract in a list, block in a landing page...). By default the view type is full (for full page), but it can be anything (line, block...).

Important note regarding visibility

Location visibility flag, which you can change with hide/unhide in admin, is not permission based and thus acts as a simple potential filter. It is not meant to restrict access to content.

If you need to restrict access to a given content, use Sections or Object states, which are permission based.

 

View selection

To display a content item, the ViewController uses a view manager which selects the appropriate template depending on matching rules.

For more information about the view provider configuration, please refer to the dedicated page.

Location view template

A content view template is like any other template, with several specific aspects.

Available variables

Variable nameTypeDescription
locationeZ\Publish\Core\Repository\Values\Content\LocationThe location object. Contains meta information on the content (ContentInfo)
(only when accessing a location) 
contenteZ\Publish\Core\Repository\Values\Content\ContentThe content object, containing all fields and version information (VersionInfo)
noLayoutBooleanIf true, indicates if the content/location is to be displayed without any pagelayout (i.e. AJAX, sub-requests...).
It's generally false when displaying a content item in view type full
viewBaseLayoutStringThe base layout template to use when the view is requested to be generated outside of the pagelayout (when noLayout is true).

Template inheritance

Like any template, a content view template can use template inheritance. However keep in mind that your content can be also requested via sub-requests (see below how to render embedded content objects). In this case your template should probably not extend your main layout.

In this regard, it is recommended to use inheritance this way:

Rendering content's fields

As stated above, a view template receives the requested Content object, holding all fields.

In order to display the fields' value the way you want, you can either manipulate the Field Value object itself or use a template.

Getting raw Field value

Having access to the Content object in the template, you can use its public methods to access to all the information you need. You can also use ez_field_value helper to get the Field value in the current language if translation is available.

Using the FieldType's template block

All built-in FieldTypes come with a piece of Twig template code you can take advantage of by calling ez_render_field() helper.

Refer to ez_render_field() reference page for further information.

As this makes use of reusable templates, using ez_render_field() is the recommended way and is to be considered as a best practice.

Rendering Content name

The name of a content item is its generic "title", generated by the repository considering several rules in the FieldDefinition. It usually consists in the normalized value of the first field.

There are 2 different ways to access to this special property:

  • Through the name property of ContentInfo (not translated).
  • Through VersionInfo with the TranslationHelper (translated).

Name property in ContentInfo

This property is the actual content name, but in main language only (so it is not translated).

Translated name

The TranslationHelper service is available as of version 5.2 / 2013.09

The translated name is held in VersionInfo object, in the names property which consists of hash indexed by locale. You can easily retrieve it in the right language via the TranslationHelper service.

You can refer to ez_content_name() reference page for further information.

 

The helper will respect the prioritized languages. 

If there is no translation for your prioritized languages, the helper will always return the name in the main language.

You can also force a locale in a 2nd argument:

Exposing additional variables

It is possible to expose additional variables in a content view template. See parameters injection in content views or use your own custom controller to render a content item/location.

Making links to other locations

Linking to other locations is fairly easy and is done with native path() Twig helper (or url() if you want to generate absolute URLs). You just have to pass it the Location object and path() will generate the URLAlias for you.

If you don't have the Location object, but only its ID, you can generate the URLAlias the following way:

As of 5.4 / 2014.11, you can also use the Content ID. In that case generated link will point to the content main location.

Under the hood

In the backend, path() uses the Router to generate links.

This makes also easy to generate links from PHP, via the router service.

See also : Cross SiteAccess links

Render embedded content objects

Rendering an embedded content from a Twig template is pretty straight forward as you just need to do a subrequest with ez_content controller.

Using ez_content controller

This controller is exactly the same as the ViewController presented above and has 2 main actions:

  • viewLocation to render a location (same as when accessing a content item through an URLAlias)
  • viewContent to render a content item

You can use this controller from templates with the following syntax:

eZ Publish 5.1+ / Symfony 2.2+

 

The example above allows you to render a Location which ID is 123, with the view type line.

Reference of ez_content controller follow the syntax of controllers as a service, as explained in Symfony documentation.

Usage with drafts

Because drafts have no Location yet, you need to use viewContent instead of viewLocation when handling drafts.

Available arguments

As any controller, you can pass arguments to ez_content:viewLocation or ez_content:viewContent to fit your needs.

NameDescriptionTypeDefault value
locationIdId of the location you want to render.
Only for ez_content:viewLocation 
integerN/A
contentId

Id of the content you want to render.
Only for ez_content:viewContent 

integerN/A
viewType

The view type you want to render your content/location in.
Will be used by the ViewManager to select corresponding template, according to defined rules. 

Example: full, line, my_custom_view, ...

stringfull
layout

Indicates if the sub-view needs to use the main layout (see available variables in a view template)

 

booleanfalse
params

Hash of variables you want to inject to sub-template, key being the exposed variable name.

Available as of eZ Publish 5.1

hashempty hash

Render block

>= EZP 5.4>= 2014.11

You can specify which controller will be called for a specific block view match, much like defining custom controllers for location view or content view match.

Also, since there are two possible actions with which one can view a block: ez_page:viewBlock and ez_page:viewBlockById, it is possible to specify a controller action with a signature matching either one of original actions.

Example of configuration in ezpublish/config/ezpublish.yml:

ESI

Just as for regular Symfony controllers, you can take advantage of ESI and use different cache levels:

Using ESI (eZ Publish 5.1+ / Symfony 2.2+)

Only scalable variables can be sent via render_esi (not object)

 

 Asynchronous rendering

Symfony also supports asynchronous content rendering with the help of hinclude.js library.

Asynchronous rendering (eZ Publish 5.1+ / Symfony 2.2+)

Only scalable variables can be sent via render_hinclude (not object)

Display a default text

If you want to display a default text while a controller is loaded asynchronously, you have to pass a second parameters to your render_hinclude twig function.

Display a default text while asynchronous loading of a controller

See also :  How to use a custom controller to display a content item or location

 

 

hinclude.js needs to be properly included in your layout to work.

Please refer to Symfony documentation for all available options.

13 Comments

  1. When rendering embedded objects in a TWIG template, objectParameters will give you access to the parameters specified when embedding an object in the online editor, e.g. the image variation.

  2. What about the fallback for ez_field_value(content, 'image')? In the case of the text, it falls back to the main language if it doesn't find a translation, but what about if the field is not text but image type? 

  3. Stiff Roy It's not about text content, but value objects. ez_field_value() always return the appropriate value object for given field. If you ask for an image field, you will get an eZ\Publish\Core\FieldType\Image\Value object. And no, it won't fallback to main language. If no appropriate language could be found, it will return null.

    Here is the reference documentation for ez_field_value().

  4. Jérôme Vieilledent I have my object in 2 languages, eng-GB and ger-DE (main language eng-GB). I have a text field and an image field. in eng-GB siteaccess, both works fine, but in ger-DE siteaccess the text field gets the fallback value from the eng-GB but the image field is black and doesn't get the fallback from the eng-GB. Any suggestion about it? Thanks... (smile)

  5. Stiff Roy In order to have more accurate answers, I suggest that you ask on the Share Forums the same question.

  6. Hello,

    For the render_esi, the documentation miss some critical informations, if you use a the 'ez_content:viewLocation' instead of a custom controller  :

    • The default TTL is 60 second, which is really not relevant (so good to know) : HttpCache
    • You can set a TTL if needed for each ESI with 'cacheSettings': {'smax-age': 3600}
  7. gilles guirand : Usage of ez_content:viewLocation is highly recommended, even if you want to use a custom controller (set your custom controller in your view rules). 

    You can also set different cache values using a ResponseListener. You may use FOSHttpCacheBundle for this (which will be bundled with 5.4).

    • You can set a TTL if needed for each ESI with 'cacheSettings': {'smax-age': 3600}

    No, you cannot do that with ez_content:viewLocation, currently only with ez_page:viewBlock.

  8. Thanks for the quick answer :

    • is it not possible to make this cacheSettings parameter available ? (i mean, is there a blocker except the time to develop ?)
    • is there a motivation to set a defaut TTL to 60sec ? (maybe to avoid unexpected cache behaviour on first install / discovery of eZPublish)
  9. i'm fine with the default ttl setting. default settings should be conservative imho. Difficult to say what could be a good choice though...

  10. gilles guirand : It would be possible to add the cacheSettings parameters. PR accepted (smile). As for the default TTL to 60sec, yes. This is to ensure TTL is not too long in case of issue with purging (safeguard clause basically). But you know you can change it in your semantic configuration, right ?

  11. Sure, right, but it starts to be a new top 5 cache issue with eZ5 (smile) . So maybe should add a huge red box somewhere in the documentation (under render_esi) to advice to change this TTL with a more relevant value, depending on the project & the dynamic purge avaiable

  12. There is a typo in render_esi and render_hinclude examples; it says viewMode instead of viewType.