add doc for block builder

docs/utils/editors/builder.md

@@ -0,0 +1,128 @@
+# Builder Block
+
+Its gives you total control to build with blocks.
+
+![](/_static/img/editors/builder.png)
+
+## Add the builder in forms
+
+### Classic form
+
+```php-inline title="src/Form/ExampleType.php"
+namespace App\Form\ExampleType;
+
+use App\Core\Form\Type\BuilderType;
+use Symfony\Component\Form\AbstractType;
+use Symfony\Component\Form\FormBuilderInterface;
+
+class ExampleType extends AbstractType
+{
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->add(
+            'myField',
+            BuilderType::class
+        );
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+### Page form
+
+```php-inline title="src/Entity/Page/YourPage.php"
+namespace App\Entity\Page;
+
+use App\Core\Entity\Site\Page\Block;
+use App\Core\Entity\Site\Page\BuilderBlock;
+use App\Core\Form\Site\Page\BuilderBlockType;
+use Symfony\Component\Form\FormBuilderInterface;
+
+#[ORM\Entity]
+class YourPage extends Page
+{
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->add(
+            'myBlock',
+            BuilderBlockType::class,
+            [
+                'label' => 'My block',
+                'row_attr' => [
+                ],
+                'options' => [
+                    // options given to the sub form
+                ],
+            ]
+        );
+
+        // ...
+    }
+
+    public function setMyBlock(Block $block)
+    {
+        return $this->setBlock($block);
+    }
+
+    public function getMyBlock(): Block
+    {
+        return $this->getBlock('myBlock', BuilderBlock::class);
+    }
+
+    // ...
+}
+```
+
+## Creating custom block
+
+First, create a service which extends `App\Core\BuilderBlock\BuilderBlock` and tagged `builder_block.widget`.
+Then, implement the method `configure` as below.
+
+```php-inline title="src/BuilderBlock/CustomBlock.php"
+namespace App\BuilderBlock;
+
+use App\Core\BuilderBlock\BuilderBlock;
+use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;
+
+#[AutoconfigureTag('builder_block.widget')]
+class CustomBlock extends BuilderBlock
+{
+    public function configure()
+    {
+        $this
+            ->setName('custom')
+            ->setCategory('Category')
+            ->setLabel('My custom block')
+            ->setIsContainer(false) // set `true` if the block can contain blocks
+            ->setIcon('<i class="fas fa-pencil-alt"></i>')
+            ->setTemplate('builder_block/custom.html.twig')
+            ->addSetting(name: 'value', label: 'Value', type: 'textarea', attributes: [], default: 'Default value')
+        ;
+    }
+}
+```
+
+Create a template:
+
+```twig-inline title="templates/builder_block/custom.html.twig"
+<div id="{{ id }}">
+    {{ settings.value|default(null) }}
+
+    {# If it's a container: #}
+    {% for item in children %}
+        {{ item|block_to_html }}
+    {% endfor %}
+</div>
+```
+
+That's all folks!
+
+![](/_static/img/editors/builder2.png)
+![](/_static/img/editors/builder3.png)
+
+## Rendering
+
+To render blocks, simply use `{{ value|block_to_html }}`.

mkdocs.yml

@@ -92,6 +92,7 @@ nav:
       - Picker picker: utils/form/file_picker.md
       - Collection: utils/form/collection.md
       - Editors:
+        - Block builder: utils/editors/builder.md
         - TinyMCE: utils/editors/tinymce.md
         - GrapesJS: utils/editors/grapesjs.md
         - Editor.js: utils/editors/editorjs.md