• Documentation >
• Guide >
• Content management >
• Page >
• Create custom Page block

Create custom Page block

In addition to existing blocks which you can use in a Page, you can also create custom blocks.

To do this, add block configuration in a YAML file, under the ezplatform_page_fieldtype key, for example in config/packages/ezplatform_page_builder.yaml.

The following example shows how to create a block that showcases an event.

Configure block

First, add the following YAML configuration:

ezplatform_page_fieldtype:
    blocks:
        event:
            name: Event Block
            category: Custom
            thumbnail: /bundles/ibexaplatformicons/img/all-icons.svg#date
            attributes:
                name:
                    type: text
                    name: Event name
                    validators:
                        not_blank:
                            message: Please provide a name
                category:
                    type: select
                    name: Select a category
                    value: visual
                    options:
                        multiple: true
                        choices:
                            'Music': music
                            'Visual arts': visual
                            'Sports': sports
                event:
                    type: embed
                    name: Event
                    validators:
                        not_blank:
                            message: Please select an event
                        content_type:
                            message: Please select an event
                            options:
                                types: ['event']
                        regexp:
                            message: Choose a content item
                            options:
                                pattern: '/[0-9]+/'

event is the internal name for the block, and name indicates the name under which the block is available in the interface. You also set up the category in the Elements panel that the block appears in. In this case, it doesn't show with the rest of the built-in blocks, but in a separate "Custom" category. The thumbnail for the block can be one of the pre-existing icons, like in the example above, or you can use a custom SVG file.

A block can have multiple attributes that you edit when adding it to a Page. In this example, you configure three attributes: name of the event, category it belongs to, and an event Content item that you select and embed.

For a list of all available attribute types, see Page block attributes.

Each attribute can have validators. The not_blank validators in the example ensure that the user fills in the two block fields. The content_type validator in the example ensure that the user choose a content item of the content type event. The regexp validator ensure that the final value looks like a content ID.

Add block templates

A block can have different templates that you select when adding it to a Page.

To configure block templates, add them to block configuration:

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

Provide the templates in the indicated folder, in this case in templates/themes/<your_theme>/blocks/event.

For example the featured_template.html.twig file can look like this:

<h1>{{ name }}</h1>
<p>{{ category }}</p>
{{ render(controller('ez_content::viewAction', {
    'contentId': event,
    'viewType': 'embed'
})) }}

The templates have access to all block attributes, as you can see above in the name, category and event variables.

Priority of templates indicates the order in which they are presented in Page Builder. The template with the greatest priority is used as the default one.

Add pre-render event listener

If you need to compute variables to pass to the template, you can listen or subscribe to the block pre-render event.

For example, the following event subscriber loads the event content item and passes it to the template as event_content:

<?php declare(strict_types=1);

namespace App\Event\Subscriber;

use eZ\Publish\API\Repository\ContentService;
use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Renderer\BlockRenderEvents;
use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Renderer\Event\PreRenderEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BlockEmbedEventEventSubscriber implements EventSubscriberInterface
{
    private ContentService $contentService;

    public function __construct(ContentService $contentService)
    {
        $this->contentService = $contentService;
    }

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

    public function onBlockPreRender(PreRenderEvent $event)
    {
        $renderRequest = $event->getRenderRequest();
        $parameters = $event->getRenderRequest()->getParameters();
        $parameters['event_content'] = $this->contentService->loadContent($parameters['event']);
        $renderRequest->setParameters($parameters);
    }
}

The block view template could now use ibexa_render(event_content, {'viewType': 'embed'}) instead of render(controller('ibexa_content::viewAction', {'contentId': event, 'viewType': 'embed'})), other content Twig functions, or field Twig functions.

For more information, see Block events.

Add edit template

You can also customize the template for the block settings modal. Do this under the configuration_template key:

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'

Place the edit template in templates/themes/<your_theme>/blocks/event/config.html.twig:

{% 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 %}

This example template overrides the embed attribute widget to customize the Universal Discovery Widget (UDW). It adds itself to the form_templates and defines a block_configuration_attribute_embed_widget block. The following UDW configuration is used so only an event typed content item can be selected:

ezplatform:
    system:
        default:
            universal_discovery_widget_module:
                configuration:
                    block_event_embed:
                        multiple: false
                        allowed_content_types: ['event']

For more information, see UDW configuration.

Your custom page block is now ready. Before you can use it in Page Builder, you must enable it in Page field settings.