Configuring content blocks
🍫 Content blocks schema
Blocks defines a renderable element that can have a set of attributes (see next paragraph).
Their configuration is composed by the following properties:
- template (string, required)
The twig rendering template
- block_name (string, required)
Renders a label above the block in the DegDitor admin interface
- block_description (string, optional)
Renders a description in the block form in the DegDitor admin interface
- allowed_inner_blocks (array, optional)
The list of blocks that can be nested inside this block
- allowed_as_root (boolean, optional)
If the block could be added at root level, default is true
- attributes (array, optional)
The list of attributes for this block, see next paragraph
🧩 Attributes Schema
Attributes define configurable properties of each block.
Their configuration is composed by the following properties:
- type (array, required) that defines the attribute nature with following allowed values:
boolean Renders a checkboxtext Renders a text inputurl Renders a url inputlink Renders a combobox that allows to create a dynamic link to products, taxons, DegDitor pages and categoriesnumber Renders a number inputdate Renders a date pickerselect Renders a selectradio Renders a radio buttonslider Renders a slider inputtextarea Renders a textareamarkup Renders a Rich Text Editorproduct Renders a Sylius product selector with autocompletetaxon Renders a Sylius taxon selector with autocompletedegditor_category Renders a DegDitor category selector with autocompletedegditor_page Renders a DegDitor category selector with autocompletedegditor_image Renders a media browser dialogcolor_picker Renders a color pickerui_heading Renders a title and subtitle (used only in the DegDitor admin interface, designed for merchants)ui_alert Renders an alert (used only in the DegDitor admin interface, designed for merchants)
- name (string, required)
Renders a label above the field in the DegDitor admin interface
- description (string, optional)
Renders a description above the field in the DegDitor admin interface
- regex (string, optional)
The regex to be used to validate the attribute value
- required (boolean, optional, default false)
Sets the field as required, or not
- values ({label: string, value: string|int|bool|float|null}[], optional)
Available values for the attribute, if the attribute is of type select, or a pair of min-max values if the attribute is of type slider
- fallback
The key of the attribute to be used as fallback in case the current one has no value or nullish value
🏗 Configure via Symfony Tags
Blocks definitions must implement
FiftyDeg\SyliusDegditorBasePlugin\Configuration\BlockConfigurationInterface
Attributes definition must implement
FiftyDeg\SyliusDegditorBasePlugin\Configuration\AttributeConfigurationInterface
For convenince we provide the following abstract classes to be extended:
FiftyDeg\SyliusDegditorBasePlugin\Configuration\AbstractBlockConfiguration
FiftyDeg\SyliusDegditorBasePlugin\Configuration\AbstractAttributeConfiguration
Once you extended the abstract classes (or implemented the interfaces) then you can tag your services with the
fifty_deg_sylius_degditor_base.block_configuration
tag in your services configuration.
🧪 Example: Button Block (Service tags)
- Add your attributes definition, e.g.
<?php
declare(strict_types=1);
namespace YourBundle\BlockConfiguration\Attributes;
use FiftyDeg\SyliusDegditorBasePlugin\Configuration\AbstractAttributeConfiguration;
class LinkAttribute extends AbstractAttributeConfiguration
{
public function __construct(
private readonly string $id,
private readonly string $name = 'Link target',
private readonly string $description = 'Select the entity type and search the resource to create a link.',
private readonly bool $required = false,
private readonly ?string $fallback = null,
) {
parent::__construct(
id: $this->id,
type: self::TYPE_LINK,
name: $this->name,
description: $this->description,
required: $this->required,
fallback: $this->fallback,
);
}
}
<?php
declare(strict_types=1);
namespace YourBundle\BlockConfiguration\Attributes;
use FiftyDeg\SyliusDegditorBasePlugin\Configuration\AbstractAttributeConfiguration;
class InputTextAttribute extends AbstractAttributeConfiguration
{
public function __construct(
private readonly string $id,
private readonly string $name = 'Text input',
private readonly string $description = '',
private readonly bool $required = false,
private readonly string $regex = '',
private readonly ?string $fallback = null,
) {
parent::__construct(
id: $this->id,
type: self::TYPE_TEXT,
name: $this->name,
required: $this->required,
description: $this->description,
regex: $this->regex,
fallback: $this->fallback,
);
}
}
- Configure the button block with its attributes
<?php
declare(strict_types=1);
namespace YourBundle\BlockConfiguration\Blocks;
use FiftyDeg\SyliusDegditorBasePlugin\Configuration\AbstractBlockConfiguration;
use YourBundle\BlockConfiguration\Attributes\InputTextAttribute;
use YourBundle\BlockConfiguration\Attributes\LinkAttribute;
class ButtonBlock extends AbstractBlockConfiguration
{
public function __construct()
{
parent::__construct(
id: static::class,
template: '@YourBundle/blocks/atoms/button.html.twig',
name: 'Button',
description: 'A prompt that tells the user to take some specified action, like a button or a link.',
allowedAsRoot: false,
allowedInnerBlocks: [],
attributes: [
new InputTextAttribute(
id: 'button_label',
name: 'Button label',
description: 'The label shown inside the button.',
required: true,
),
new LinkAttribute(
id: 'button_link',
name: 'Button link',
description: 'The link of the button.',
required: true,
),
],
);
}
}
- Register the block configuration by using the
fifty_deg_sylius_degditor_base.block_configuration service tag
services:
your_bundle.block_configuration.blocks.button_block:
class: YourBundle\BlockConfiguration\Blocks\ButtonBlock
tags:
- { name: fifty_deg_sylius_degditor_base.block_configuration, priority: 100 }
🚀 Why This Approach Rocks
This approach is recommended over the YAML configuration mode, even if it's more verbose, because:
- it's easier to define generic attributes and reuse them across different blocks types
- IDs are auto-generated based on class name, improving:
- attributes referencing
- inner blocks referencing
- avoid typos and IDs duplications
- typehinting
- you can add conditional logics
- you can create attributes builders utilities, such as bootstrap responsive class names generation
- you can also benefit of dependency injection and pass services (and attributes as a service) in constructor
- quickly define their sorting thanks to the
priority tag attribute
🧠 Note: Changes to block services require cache clearing!
This code is evaluate at compile time so, each time you update your configuration, you need to clear cache
🧾 YAML-Based Configuration
Alongside with the Symfony tags block configuration mode, you can define your blocks and their attributes also with YAML.
Anyway,
we recommend using the Symfony tags way.
To configure blocks with YAML, create the
config/packages/fiftydeg_sylius_degditor_base.yaml
file in your project and follow the following examples.
✍️ Example: Button Block (YAML)
Below you will find the same button configured via YAML.
As you can see, it is much more concise, but it is more difficult to reuse attributes and you cannot use custom logic / generator functions when defining the content block.
fifty_deg_sylius_degditor_base:
blocks:
button:
template: "@YourBundle/Blocks/button.html.twig"
block_name: Button
block_description: A prompt that tells the user to take some specified action, like a button or a link.
allowed_inner_blocks: [ ]
allowed_as_root: false
attributes:
button_link:
{
type: "link",
name: "Button link",
description: "The link of the button.",
required: true,
}
button_label:
{
type: "text",
name: "Button label",
description: "The label shown inside the button.",
required: false,
fallback: button_link
}
♻️ YAML configuration with reusable Attributes
Thanks to the reusable_attributes configuration key, it's possible to define reusable blocks' attributes also using YAML configuration.
fifty_deg_sylius_degditor_base:
reusable_attributes:
button_attributes: &button_attributes
button_link:
{
type: "link",
name: "Button link",
description: "The link of the button.",
required: true,
}
button_label:
{
type: "text",
name: "Button label",
description: "The label shown inside the button.",
required: false,
fallback: button_link
}
blocks:
button:
template: "@YourBundle/Blocks/button.html.twig"
block_name: Button
block_description: A prompt that tells the user to take some specified action, like a button or a link.
allowed_inner_blocks: [ ]
allowed_as_root: false
attributes:
<<: *button_attributes