Skip to content
  • Documentation >
  • Guide >
  • Content management >
  • Page >
  • Page block attributes

Page block attributes

A block has attributes that the editor fills in when adding th block to a Page. Each block can have the following properties:

Attribute Description
type Attribute type.
name (Optional) The displayed name for the attribute. You can omit it, block identifier is then used as the name.
value (Optional) The default value for the attribute.
category (Optional) The tab where the attribute is displayed in the block edit modal.
validators (Optional) Validators checking the attribute value.
options (Optional) Additional options, dependent on the attribute type.

Block attribute types

The following attribute types are available:

Type Description Options
integer Integer value -
string String -
url URL -
text Text block -
richtext Rich text block (see creating RichText block) -
embed Embedded Content item -
select Drop-down with options to select choices lists the available options
multiple, when set to true, allows selecting more than one option.
multiple Checkbox(es) choices lists the available options.
radio Radio buttons choices lists the available options.
locationlist Location selection -
contenttypelist List of Content Types -
schedule_events,
schedule_snapshots,
schedule_initial_items,
schedule_slots,
schedule_loaded_snapshot		 Used in the Content Scheduler block -
nested_attribute Defines a group of attributes in a block. attributes - a list of attributes in the group. The attributes in the group are configured as regular attributes.
multiple, when set to true. New groups are added dynamically with the Add field group button.

When you define attributes, you can omit most keys as long as you use simple types that do not require additional options:

1
2
3
4
attributes:
    first_field: text
    second_field: string
    third_field: integer

embed and locationlist use the Universal Discovery Widget (UDW). When creating a block with these two types you can configure the UDW behavior. For more information, see Create custom page block / Add edit template

Custom attribute types

You can create custom attribute type to add to Page blocks.

A custom attribute requires attribute type class, a mapper and a template.

Block attribute type

First, create the attribute type class.

It can extend one of the types available in ezplatform-page-fieldtype/src/lib/Form/Type/BlockAttribute/. You can also use one of the built-in Symfony types, for example AbstractType for any custom type or IntegerType for numeric types.

To define the type, create a src/Block/Attribute/MyStringAttributeType.php file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php declare(strict_types=1);

namespace App\Block\Attribute;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class MyStringAttributeType extends AbstractType
{
    public function getParent()
    {
        return TextType::class;
    }

    public function getBlockPrefix()
    {
        return 'my_string_attribute';
    }
}

Note that the attribute uses AbstractType (line 5) and TextType (line 6). Adding getBlockPrefix (line 15) returns a unique prefix key for a custom template of the attribute.

Mapper

At this point, the attribute type configuration is complete, but it requires a mapper. Depending on the complexity of the type, you can use a GenericFormTypeMapper or create your own.

Generic mapper

For a generic mapper, add a new service definition to config/services.yaml:

1
2
3
4
5
6
my_application.block.attribute.my_string:
    class: EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Attribute\FormTypeMapper\GenericFormTypeMapper
    arguments:
        $formTypeClass: App\Block\Attribute\MyStringAttributeType
    tags:
        - { name: ezplatform.page_builder.attribute_form_type_mapper, alias: my_string }

Custom mapper

To use a custom mapper, create a class that inherits from EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Attribute\FormTypeMapper\AttributeFormTypeMapperInterface, for example in src/Block/Attribute/MyStringAttributeMapper.php:

 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
36
<?php declare(strict_types=1);

namespace App\Block\Attribute;

use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Attribute\FormTypeMapper\AttributeFormTypeMapperInterface;
use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Definition\BlockAttributeDefinition;
use EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Definition\BlockDefinition;
use Symfony\Component\Form\FormBuilderInterface;

class MyStringAttributeMapper implements AttributeFormTypeMapperInterface
{
    /**
     * @param \Symfony\Component\Form\FormBuilderInterface $formBuilder
     * @param \EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Definition\BlockDefinition $blockDefinition
     * @param \EzSystems\EzPlatformPageFieldType\FieldType\Page\Block\Definition\BlockAttributeDefinition $blockAttributeDefinition
     * @param array $constraints
     *
     * @return \Symfony\Component\Form\FormBuilderInterface
     *
     * @throws \Exception
     */
    public function map(
        FormBuilderInterface $formBuilder,
        BlockDefinition $blockDefinition,
        BlockAttributeDefinition $blockAttributeDefinition,
        array $constraints = []
    ): FormBuilderInterface {
        return $formBuilder->create(
            'value',
            MyStringAttributeType::class,
            [
                'constraints' => $constraints,
            ]
        );
    }
}

Then, add a new service definition for your mapper to config/services.yaml:

1
2
3
App\Block\Attribute\MyStringAttributeMapper:
        tags:
            - { name: ezplatform.page_builder.attribute_form_type_mapper, alias: my_string }

Edit templates

Next, configure a template for the attribute edit form by creating a templates/custom_form_templates.html.twig file:

1
2
3
4
{% block my_string_attribute_widget %}
    <h2>My String</h2>
    {{ form_widget(form) }}
{% endblock %}

Add the template to your configuration:

1
2
3
4
5
system:
    default:
        page_builder_forms:
            block_edit_form_templates:
                - { template: custom_form_templates.html.twig, priority: 0 }

Custom attribute configuration

Now, you can create a block containing your custom attribute:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
ezplatform_page_fieldtype:
    blocks:
        my_block:
            name: MyBlock
            category: default
            thumbnail: /bundles/ibexaplatformicons/img/all-icons.svg#edit
            views:
                default: 
                    name: Default block layout
                    template: my_block.html.twig
                    priority: -255
            attributes:
                my_string_attribute:
                    type: my_string
                    name: MyString

Nested attribute configuration

The nested_attribute attribute is used when you want to create a group of attributes.

First, make sure you have configured the attributes you want to use in the group.

Next, provide the configuration. See the example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
ezplatform_page_fieldtype:
    blocks:
        block_name:
            category: default
            thumbnail: 'path/icons.svg'
            views:
                default: { name: 'Default block layout', template: 'template.html.twig', priority: -255 }
            attributes:
                group:
                    name: Group name
                    type: nested_attribute
                    options:
                        attributes:
                            attribute_1:
                                name: Name 1
                                type: type
                            attribute_2:
                                name: Name 2
                                type: type
                        multiple: true

To set validation for each nested attribute:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
                    name: Group name
                    type: nested_attribute
                    options:
                        attributes:
                            attribute_1:
                                name: Name 1
                                type: type
                                validators:
                                    not_blank:
                                        message: 'Provide a value'

Validators can be also set on a parent attribute (group defining level), it means all validators apply to each nested attribute:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
                    name: Group name
                    type: nested_attribute
                    options:
                        attributes:
                            attribute_1:
                                name: Name 1
                                type: type
                             attribute_2:
                                name: Name 2
                                type: type
                        multiple: true
                    validators:
                        not_blank:
                            message: 'Provide a value'

Moving attributes between groups

If you move an attribute between groups or add an ungrouped attribute to a group, the block values are removed.

Help messages for form fields

With the help, help_attr, and help_html field options, you can set help messages for fields in the Page block.

You can set options with the following configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
ezplatform_page_fieldtype:
    blocks:
        block_name:
            attributes:
                attribute_name:
                    options:
                        help:
                            text: 'Some example text'
                            html: true|false
                            attr:
                                class: 'class1 class2'
  • help - defines a help message which is rendered below the field.
  • help_attr - sets the HTML attributes for the element which displays the help message.
  • help_html - set this option to true to disable escaping the contents of the help option when rendering in the template.

Help message in nested attributes

You can set the options for root or nested attribute, see the example configuration:

 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
36
ezplatform_page_fieldtype:
    blocks:
            slider:
                category: default
                thumbnail: '/bundles/ibexaadminui/img/ibexa-icons.svg'
                views:
                    default: { name: 'Default block layout', template: 'themes/blocks/slider.html.twig', priority: -255 }
                attributes:
                    group:
                        name: Group name
                        type: nested_attribute
                        options:
                            help:
                                text: 'Root class text'
                                html: true # true|false
                                attr:
                                    class: 'root-class-1 root-class-2'
                            attributes:
                                integer:
                                    name: Age
                                    type: integer
                                    validators:
                                        not_blank:
                                            message: 'Provide a value'
                                    options:
                                        help:
                                            text: 'Nested attribute text'
                                            html: true
                                            attr:
                                                class: 'nested-1 nested-2'
                                string:
                                    name: Name
                                    type: string
                                    validators:
                                        not_blank:
                                            message: 'Provide a value'

Help message