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

Description

With the Page FieldType, in legacy part of "ezflow" extension, editors can define a layout with multiple zones within a single front- or landing-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 Field Type has limited write support with the Public API as of EZP-25413 - Page FieldType Public API should save custom attributes and rotation Closed , part of v5.4.7 releases, before this it where read-only. In all versions it is still possible to edit content with it through the admin interface (which runs through the legacy stack)

NameInternal nameExpected inputOutput
PageezpageN/AeZ\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 myLayoutIdentifierResources/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

IdentifierDescription
Type

Matches the unique block identifier defined in the legacy block.ini file (see legacy documentation).

For example with the following configuration in legacy block.ini, it will match against Manual3Items:


View

Matches the view’s unique identifier defined in the block definition in the legacy block.ini (see legacy documentation).

For example with the following configuration in legacy block.ini, it will match against 3_items1:

When no view is defined, the default value is default.


Id\BlockMatches against the block ID, as stored in ezm_block table
Id\ZoneMatches 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 nameDescriptionType
zonesZone objects for this Page fieldArray of eZ\Publish\Core\FieldType\Page\Parts\Zone objects
zone_layoutThe 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
NameDescriptionTypeDefault value
blockThe block object you want to rendereZ\Publish\Core\FieldType\Page\Parts\BlockN/A
params

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

hashempty
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 nameTypeDescription
blockeZ\Publish\Core\FieldType\Page\Parts\BlockThe block to display
valid_itemsArray of eZ\Publish\Core\FieldType\Page\PartsDisplayable block items
valid_contentinfo_itemsArray of eZ\Publish\API\Repository\Values\Content\ContentInfoDisplayable block items, as ContentInfo objects.
pageService (deprecated as of v5.2)eZ\Bundle\EzPublishCoreBundle\FieldType\Page\PageServiceThe PageService object (deprecated)

And of course, all the additional variables you injected in the params argument .

valid_items and valid_contentinfo_items variables are available as of v5.2 / 2013.11.

Usage of pageService is deprecated as of v5.2 / 2013.11 and will be removed in v6.0.

 

Using pageView:viewBlockById

>= EZP 5.3.2

You can render Blocks with ESI strategy in all contexts, ie including using Varnish with the controller viewBlockById.

 

This feature is available from eZ Platform 5.3.2.

Available arguments
NameDescriptionTypeDefault value
idThe block ID of the block you want to render
A \eZ\Publish\API\Repository\Exceptions\NotFoundException will be thrown, if block could not be found
stringN/A
params

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

hashempty
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

 

 

 

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 nameDescriptionReturn type
getZoneDefinition()Returns zone definition (all defined zones for the current siteaccess) as an arrayarray
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 arrayarray
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 objectseZ\Publish\API\Repository\Values\Content\ContentInfo[]

Example

2zoneslayout1.html.twig
campaign_block.html.twig

10 Comments

  1. I have a question about configuration part. when you define layout template in yaml file like

    template: "AcmeDemoBundle:page/zonelayouts/my_template.html.twig"

    Do i suppose that i need to create that file under Resource/views in my bundle? Or do i need something more?

    Thanks!. 

     

  2. Carlos: Yes (updated the doc). Your comment also pointed out that the template identifier was wrong. You must use:

  3. Thanks Jerome. Now i know what it wasn't working for me last night (smile)

  4. Two things about the provided samples:

    In the zone definition sample, i think there's "wrong order". It says

    ezpublish:
        system:
            my_siteaccess:
                layouts:
                    ezpage:
    where it should say (i think )
    ezpublish:
        system:
            my_siteaccess:
                ezpage:
                    layouts:
    And about defining the zone with a legacy template,
    ezpublish:
        system:
            my_siteaccess:
                ezpage:
                    myLegacyLayout:
    don't wee need to add "layouts" between ezpage: and myLegacyLayout?
    Thanks
  5. You're right Carlos, fixing.

  6. The warning at the top of the page says that bock and zone definition is still needed for the backoffice to work. But it seems that if there is no list of enabled layouts in the eZ5 configuration, an exception is thrown (or if a content with a Page field which uses a layout which is not defined as enabled in ez5 configuration).

    Should this be filed as bug? (the best thing to do would be imho to avoid as much as possible to have to do double-configuration, as long as the ez-4 part is still mandatory)

  7. Guys, are you sure that block object is passable with render_esi ? via GET on fragment url?

    Check this out: http://blogs.arondor.com/en/Content-management/Error-during-loading-of-an-eZ-Flow-landing-page-with-eZ-Publish-5-on-PROD

    Looks to me there should be a possibility to pass only block id...

  8. You're right Ivo. Fixing

  9. I think it would be useful to give an example of custom controller for a block because it's a little tricky and not so simple as a custom controller used to display a simple location.

    The built in controller with the page service only fetches contents ordering them by priority. That's limited. I wanted to reproduce the fetchClass property in legacy ezflow.

    So here's how I did it :

    First of all you need to build your controller as a service.

    It needs to extends eZ\Publish\Core\MVC\Symfony\Controller\Controller class and it's constructor must have to parameters the ViewManager that will help display the block and the PageService.

    first in the services.yml file you need to declare the service

    service.yml

    Then for the block you specify the custom controller like this

    ezpage.yml

     

    And there we go to the controller itself that you have to place in the controller folder of your bundle.

    Controller

     

    Hope this helps. Didn't find a best way to do it.

  10. Although the document here says

    "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). "

    It is in fact possible to add a field of the type ezpage to a contentType. It's just not possible to fill it.

    See Re: 5. Other recipes