The configured ViewProvider allows you to configure template selection when using the ViewController, either directly from a URL or via a sub-request.
eZ Publish 4.x terminology
In eZ Publish 4.x, it was known as template override system by configuration (override.ini).
However this only reflects old overrides for node/view/*.tpl and content/view/*.tpl.
Principle
The configured ViewProvider takes its configuration from your siteaccess in the content_view section. This configuration is a hash built in the following way:
Important note about template matching
Template matching will NOT work if your content contains a Field Type that is not supported by the repository. It can be the case when you are in the process of a migration from eZ Publish 4.x, where custom datatypes have been developed.
In this case the repository will throw an exception which is caught in the ViewController, causing a fallback to the legacy kernel.
The list of Field Types supported out of the box is available here.
Tip
You can define your template selection rules in a different configuration file. Read the cookbook recipe to learn more about it.
You can also use your own custom controller to render a content/location.
About location_view & content_view
Until eZ Publish Platform 5.4, the main view action was location_view. This is deprecated since eZ Platform 15.12 (1.0). Only content_view should be used to view content, with a location as an option.
Existing location_view rules will be, when possible, converted transparently to content_view, with a deprecation notice. However, it is not possible to do so when the rule uses a custom controller.
In any case, location_view rules should be converted to content_view ones, as location_view will be removed in the next kernel major version.
Matchers
To be able to select the right templates against conditions, the view provider uses matcher objects, all implementing eZ\Publish\Core\MVC\Symfony\View\ContentViewProvider\Configured\Matcher interface.
Matcher identifier
The matcher identifier can comply to 3 different formats:
- Relative qualified class name (e.g.
Identifier\ContentType). This is the most common case and used for native matchers. It will then be relative toeZ\Publish\Core\MVC\Symfony\View\ContentViewProvider\Configured\Matcher. - Full qualified class name (e.g.
\Foo\Bar\MyMatcher). This is a way to specify a custom matcher that doesn't need specific dependency injection. Please note that it must start with a\. - Service identifier, as defined in Symfony service container. This is the way to specify a more complex custom matcher that has dependencies.
Injecting the Repository
If your matcher needs the repository, simply make it implement eZ\Publish\Core\MVC\RepositoryAwareInterface or extend the eZ\Publish\Core\MVC\RepositoryAware abstract class. The repository will then be correctly injected before matching.
Matcher value
The value associated to the matcher is being passed to its setMatchingConfig() method and can be anything supported by the matcher.
Passing an array amounts to applying a logical OR.
Combining matchers
It is possible to combine matchers to add additional constraints for matching a template:
The example above can be translated as "Match any content which ContentType identifier is small_folder OR folder, AND having frontpage as ParentContentType identifier".
Available matchers
The following table presents all native matchers.
| Identifier | Description |
|---|---|
Id\Content | Matches the ID number of the Content item |
Id\ContentType | Matches the ID number of the Content Type that the Content item is an instance of |
Id\ContentTypeGroup | Matches the ID number of the group containing the Content Type that the Content item is an instance of |
Id\Location | Matches the ID number of a Location. In the case of a Content item, matched against the main location. |
Id\ParentContentType | Matches the ID number of the parent Content Type. In the case of a Content item, matched against the main location. |
Id\ParentLocation | Matches the ID number of the parent Location. |
Id\Remote | Matches the remoteId of either content or Location, depending on the object matched. |
Id\Section | Matches the ID number of the Section that the Content item belongs to. |
Id\State | Not supported yet. |
Identifier\ContentType | Matches the identifier of the Content Type that the Content item is an instance of. |
Identifier\ParentContentType | Matches the identifier of the parent Content Type. |
Identifier\Section | Matches the identifier of the Section that the Content item belongs to. |
Identifier\State | Not supported yet. |
Depth | Matches the depth of the Location. The depth of a top level Location is 1. |
UrlAlias | Matches the virtual URL of the Location (i.e. Important: Matches when the UrlAlias of the location starts with the value passed. |
4 Comments
Nicolas Pastorino
Hi guys, great piece of doc!
Pierre seems to have stumbled upon a non-working 'content_view' View Provider. All details here:
http://share.ez.no/forums/setup-design/override-a-content-template#comment79595
Cheers,
Gareth Arnott
content_viewseems to work now! I couldn't see a concrete example in the DemoBundle. Here is a rough outline of what I have:block/my_author.html.twigLooks like this:And the code to render in the main template is like this:
The my_author attribute is of type
ezobjectrelationHope that's clear. Apologies if I've missed anything.
Gaetano Giunta
For all hackerz out there: if you want to implement a custom matcher, nothing is easier:
a) register it as a service (no tags needed)
b) make sure it implements the good interface (you probably are better of subclassing some of the existing ones)
Eirik Alfstad Johansen
From what I understand, `location_view` is deprecated and should be replaced with `content_view` in the code excerpts.