Skip to content
  • Documentation >
  • Guide >
  • Content management >
  • Page >
  • Page blocks

Page blocks

Page blocks are configured in YAML files, under the ezplatform_page_fieldtype key.

Caution

Page block configuration is not SiteAccess-aware.

Tip

For information on how to create and configure new layouts for the Page, see Page layouts.

Block configuration

Each configured block has an identifier and the following settings:

Setting Description
name Name of the block used in the Page Builder interface.
category Category in the Page Builder elements menu that the block is shown in.
thumbnail Thumbnail used in the Page Builder elements menu.
views Available templates for the block.
visible (Optional) Toggles the block's visibility in the Page Builder elements menu. Remove the block from the layout before you publish another version of the page.
configuration_template (Optional) Template for the block settings modal.
attributes (Optional) List of block attributes.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
ezplatform_page_fieldtype:
    blocks:
        event:
            name: Event Block
            category: Custom
            thumbnail: /bundles/ibexaplatformicons/img/all-icons.svg#date
            configuration_template: '@ezdesign/blocks/event/config.html.twig'
            views:
                default:
                    template: '@ezdesign/blocks/event/template.html.twig'
                    name: Default view
                    priority: -255
            attributes:
# ...

Tip

For a full example of block configuration, see Create custom Page block.

Overwriting existing blocks

You can overwrite the following properties in the existing blocks:

  • name
  • category
  • thumbnail
  • views

Block templates

Page blocks can have multiple templates. This allows you to create different styles for each block and let the editor choose them when adding the block from the UI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
ezplatform_page_fieldtype:
    blocks:
        event:
            views:
                default:
                    template: '@ezdesign/blocks/event/template.html.twig'
                    name: Default view
                    priority: -255
                featured:
                    template: '@ezdesign/blocks/event/featured_template.html.twig'
                    name: Featured view
                    priority: 50

priority defines the order of block views on the block configuration screen. The highest number shows first on the list.

Tip

Default views have a priority of -255. It is good practice to keep the value between -255 and 255.

Block modal template

The template for the configuration modal of built-in Page blocks is contained in vendor/ezsystems/ezplatform-page-builder/src/bundle/Resources/views/page_builder/block/config.html.twig.

You can override it by using the configuration_template setting:

1
2
3
4
5
6
7
ezplatform_page_fieldtype:
    blocks:
        event:
            name: Event Block
            category: Custom
            thumbnail: /bundles/ibexaplatformicons/img/all-icons.svg#date
            configuration_template: '@ezdesign/blocks/event/config.html.twig'

The template can extend the default config.html.twig and modify its blocks. Blocks basic_tab_content and design_tab_content correspond to the Basic and Design tabs in the modal.

The following example wraps all form fields for block attributes in an ordered list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{% extends '@EzPlatformPageBuilder/page_builder/block/config.html.twig' %}

{% block content %}
    {% set form_templates = [_self] %}
    {{ parent() }}
{% endblock %}

{% block basic_tab_content %}
    <div class="ez-block-config__fields">
        {{ form_row(form.name) }}
        {% if attributes_per_category['default'] is defined %}
            <ol>
                {% for identifier in attributes_per_category['default'] %}
                    {% block config_entry %}
                        <li>
                            {{ form_row(form.attributes[identifier]) }}
                        </li>
                    {% endblock %}
                {% endfor %}
            </ol>
        {% endif %}
    </div>
{% endblock %}

{% block block_configuration_attribute_embed_widget %}
    {% set attr = attr|merge({'hidden': true}) %}
    {{ form_widget(form, {'attr': attr})}}
    <div class="ez-block-embed-field">
        {% include '@EzPlatformPageBuilder/page_builder/block/config/embed_button.html.twig' with {
            udw_config_name: 'block_event_embed',
            data_open_udw: 'data-open-udw-embed'
        } %}
        {% include '@EzPlatformPageBuilder/page_builder/block/config/embed_preview.html.twig' %}
    </div>
{% endblock %}

Block events

To add functionalities to your block that go beyond the available attributes, you can use an event listener.

You can listen to events related to block definition and block rendering.

The following events are available:

  • BlockDefinitionEvents::getBlockDefinitionEventName - dispatched when block definition is created
  • BlockDefinitionEvents::getBlockAttributeDefinitionEventName - dispatched when block attribute definition is created
  • BlockRenderEvents::getBlockPreRenderEventName - dispatched before a block is rendered
  • BlockRenderEvents::getBlockPostRenderEventName - dispatched after a block is rendered

For example, to modify a block by adding a new parameter to it, you can create the following listener:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?php declare(strict_types=1);

namespace App\Block\Listener;

use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Renderer\BlockRenderEvents;
use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Renderer\Event\PreRenderEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MyBlockListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            BlockRenderEvents::getBlockPreRenderEventName('my_block') => 'onBlockPreRender',
        ];
    }

    public function onBlockPreRender(PreRenderEvent $event)
    {
        $renderRequest = $event->getRenderRequest();

        $parameters = $event->getRenderRequest()->getParameters();

        $parameters['my_parameter'] = 'parameter_value';

        $renderRequest->setParameters($parameters);
    }
}

Before the block is rendered, the listener adds my_parameter to it with value parameter_value. You can use this parameter, for example, in block template:

1
2
3
<div>
    {{ my_parameter }}
</div>

Exposing content relations from blocks

Page blocks, for example Embed block or Collection block, can embed other Content items. Publishing a Page with such blocks creates Relations to those Content items.

When creating a custom block with embeds, you can ensure such Relations are created using the block Relation collection event.

The event is dispatched on content publication. You can hook your event listener to the BlockRelationEvents::getCollectBlockRelationsEventName event.

To expose relations, pass an array containing Content IDs to the \EzSystems\EzPlatformPageFieldType\Event\CollectBlockRelationsEvent::setRelations() method. If embedded Content changes, old Relations are removed automatically.

Providing Relations also invalidates HTTP cache for your block response in one of the related Content items changes.