Description
With the Page FieldType, editors define a layout with multiple zones within a single front page.
Within each zone, editors create blocks that contain particular content categories. Specific content can be added to these blocks, they are called block items.
This is particularly useful for managing homepages/landing pages.
The Page FieldType is currently read-only with the Public API.
It's however still possible to edit content with it through the admin interface (which runs through the legacy stack).
| Name | Internal name | Expected input | Output |
|---|---|---|---|
Page | ezpage | N/A | eZ\Publish\Core\FieldType\Page\Parts\Page |
Configuration
Warning
You still need to define your available layouts and blocks in the legacy part to get them available in the admin interface. Please refer to eZ Publish legacy documentation to learn how to do so.
Defining a zone layout
A layout is a combination of zones that are placed on a page. The placement of the zones is defined in a template that is specified as part of the layout configuration. You can define as many layouts as you need.
You can define a new layout and enable it in your main YAML configuration:
ezpublish.yml
Then, when rendering a Page FieldType using myLayoutIdentifier, Resources/views/page/zonelayouts/my_template.html.twig from AcmeDemoBundle will be used (see how to use template identifiers in Symfony documentation).
Tip
You can specify a legacy template in your layout definition.
However, doing so will defer block display to the legacy templates as well.
Available blocks
The blocks need to be defined and enabled in the YAML configuration as well:
ezpublish.yml
Tip
To avoid issues and since the Page field are only in read only mode in eZ Publish 5.1, it is recommended to synchronize the block configuration between the legacy stack and the new stack.
Block template selection
Template selection rules are applied only when you render a block with the PageController (using ez_page:viewBlock from templates), see below.
Like you are able to define template selection rules when displaying Location and Content objects, you can also define rules for blocks, with dedicated matchers.
Configuration is a hash built in the following way:
ezpublish.yml
Tip
You can define your template selection rules in a different configuration file. Read the cookbook recipe to learn more about it .
Matchers for block_view follow the same behavior than matchers for regular location_view / content_view, except that their relative namespace will be eZ\Publish\Core\MVC\Symfony\View\BlockViewProvider\Configured\Matcher .
Hence you can combine matchers with AND and OR capabilities (see main matchers' documentation page).
Available matchers
| Identifier | Description |
|---|---|
Type | Matches the unique block identifier defined in the legacy For example with the following configuration in legacy block.ini, it will match against |
View | Matches the view’s unique identifier defined in the block definition in the legacy For example with the following configuration in legacy When no view is defined, the default value is default. |
Id\Block | Matches against the block ID, as stored in ezm_block table |
Id\Zone | Matches against the zone ID a block belongs to, as stored in ezm_block table |
Displaying the Page content
This section focuses on how to display blocks from zone/layout templates.
Render of these templates are triggered when using ez_render_field() helper, like for any other field type.
See field rendering documentation for more information.
Layout template
Goal of a layout template is to display zones for the given layout, depending on your layout configuration.
Variables passed to the layout template
| Variable name | Description | Type |
|---|---|---|
zones | Zone objects for this Page field | Array of eZ\Publish\Core\FieldType\Page\Parts\Zone objects |
zone_layout | The layout identifier (e.g. "2ZonesLayout1") | string |
pageService | The PageService object (read more below). | eZ\Bundle\EzPublishCoreBundle\FieldType\Page |
Rendering blocks
Each zone contain blocks that hold your content as block items. To render blocks from a layout template, you need to do a sub-request.
Tip
You can use a custom controller to display a block.
However, if you do so, you might need to get access to the PageService. You can get it via the service container with identifier ezpublish.fieldType.ezpage.pageService.
Using ez_page:viewBlock
This controller is responsible of choosing the right template for your block, depending on the rules you defined.
You can use this controller from templates with the following syntax:
Available arguments
| Name | Description | Type | Default value |
|---|---|---|---|
block | The block object you want to render | eZ\Publish\Core\FieldType\Page\Parts\Block | N/A |
params | Hash of variables you want to inject to sub-template, key being the exposed variable name. | hash | empty |
cacheSettings | Hash of cache settings to use by the sub-controller (useful if you use ESI or Hinclude strategies). | hash (accepted keys are max-age and smax-age) | empty |
Legacy BC
If no template selection rule is matched, the system will fallback to the legacy kernel and will use rules you might have defined in legacy. The result will be the same as when using legacy block_view_gui function.
However, additional variables (from the params argument) won't be passed to the resulted template.
Variables exposed to the block template
| Variable name | Type | Description |
|---|---|---|
block | eZ\Publish\Core\FieldType\Page\Parts\Block | The block to display |
pageService | eZ\Bundle\EzPublishCoreBundle\FieldType\Page\PageService | The PageService object |
And of course, all the additional variables you injected in the params argument .
Rendering Block items
As said above, a block holds your displayable content as block items which consists of eZ\Publish\Core\FieldType\Page\Parts\Item objects. Among the available properties, you will find contentId and locationId which reference the content/location you want to display. All you have to do then is to render it view ez_content:viewLocation or ez_content:viewContent (see full example below).
The PageService object
The PageService object (eZ\Bundle\EzPublishCoreBundle\FieldType\Page\PageService) is a helper giving the possibility to get current zone/block definitions and to retrieve block items.
Main methods
| Method name | Description | Return type |
|---|---|---|
getZoneDefinition() | Returns zone definition (all defined zones for the current siteaccess) as an array | array |
getZoneDefinitionByLayout() | Returns a zone definition for a given layout. It consists of a configuration array for the given layout. | array |
getBlockDefinition() | Returns block definition as an array | array |
getBlockDefinitionByIdentifier() | Returns a block definition for a given block identifier. | array |
getValidBlockItems() | Returns valid items (that are to be displayed), for a given block. | eZ\Publish\Core\FieldType\Page\Parts\Item[] |
getLastValidBlockItem() | Returns the last valid item, for a given block. | eZ\Publish\Core\FieldType\Page\Parts\Item|null |
getWaitingBlockItems() | Returns queued items (the next to be displayed), for a given block. | eZ\Publish\Core\FieldType\Page\Parts\Item[] |
getArchivedBlockItems() | Returns archived items (that were previously displayed), for a given block. | eZ\Publish\Core\FieldType\Page\Parts\Item[] |
getValidBlockItemsAsContentInfo() | Returns valid block items as content objects | eZ\Publish\API\Repository\Values\Content\ContentInfo[] |
Example
2zoneslayout1.html.twig
campaign_block.html.twig