• Documentation >
• Content management >
• Pages >
• Page blocks

Page blocks

Page blocks are configured in YAML files, under the ibexa_fieldtype_page key. Keep in mind that Page block configuration isn't SiteAccess-aware.

Ibexa DXP ships with a number of page blocks. For a list of all page blocks that are available out-of-the-box, see Page block reference.

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

Clear the persistence cache

Persistence cache must be cleared after any modifications have been made to the block config in Page Builder, such as adding, removing or altering the Page blocks, block attributes, validators or views configuration.

To clear the persistence cache run ./bin/console cache:pool:clear [cache-pool] command. The default cache-pool is named cache.tagaware.filesystem. The default cache-pool when running redis is named cache.redis. If you have customized the persistence cache configuration, the name of your cache pool might be different.

In prod mode, you also need to clear the symfony cache by running ./bin/console c:c. In dev mode, the Symfony cache will be rebuilt automatically.

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:

ibexa_fieldtype_page:
    blocks:
        event:
            name: Event Block
            category: Custom
            thumbnail: /bundles/ibexaicons/img/all-icons.svg#date
            configuration_template: '@ibexadesign/blocks/event/config.html.twig'
            views:
                default:
                    template: '@ibexadesign/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.

ibexa_fieldtype_page:
    blocks:
        event:
            views:
                default:
                    template: '@ibexadesign/blocks/event/template.html.twig'
                    name: Default view
                    priority: -255
                featured:
                    template: '@ibexadesign/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/ibexa/page-builder/src/bundle/Resources/views/page_builder/block/config.html.twig.

You can override it by using the configuration_template configuration key:

ibexa_fieldtype_page:
    blocks:
        event:
            name: Event Block
            category: Custom
            thumbnail: /bundles/ibexaicons/img/all-icons.svg#date
            configuration_template: '@ibexadesign/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:

{% extends '@IbexaPageBuilder/page_builder/block/config.html.twig' %}

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

{% block basic_tab_content %}
    <div class="ibexa-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="ibexa-pb-block-embed-field">
        {% include '@IbexaPageBuilder/page_builder/block/config/embed_button.html.twig' with {
            udw_config_name: 'block_event_embed',
            data_open_udw: 'data-open-udw-embed'
        } %}
        {% include '@IbexaPageBuilder/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:

<?php declare(strict_types=1);

namespace App\Block\Listener;

use Ibexa\FieldTypePage\FieldType\Page\Block\Renderer\BlockRenderEvents;
use Ibexa\FieldTypePage\FieldType\Page\Block\Renderer\Event\PreRenderEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

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

    public function onBlockPreRender(PreRenderEvent $event): void
    {
        $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:

<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 Ibexa\FieldTypePage\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.