Sonata Extra Bundle: integrate the Gutenberg editor

Introduction

Integrating the Gutenberg editor into Sonata involves using the 'Automatic Isolated block editor' library. This guide details the steps necessary to install and configure the Gutenberg editor in your Sonata application.

Screens

Library Installation

The Gutenberg editor relies on a library of 'Automatic Isolated Block Editor'. You can download the library using the following link: Automatic isolated block editor library

Installation steps

Download and install the library :

Use the command line to download and install the resources from the Gutenberg library:

bin/console sonata:extra:install-gutenberg
bin/console assets:install

Add a Gutenberg widget field in Twig form themes:

Update your twig.yaml configuration to include the Gutenberg widget field:

#config/packages/twig.yaml
twig:
    form_themes:
        - '@PartitechSonataExtra/Form/gutenberg_field.html.twig'

Using Gutenberg in Sonata Admin

Form type configuration

Implement the Gutenberg form type in your Sonata administration class:

<?php

namespace App\Admin;

use App\Form\Type\GutenbergType;
use Sonata\AdminBundle\Form\FormMapper;
// ... other uses

class YourEntityAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $formMapper)
    {
        $formMapper
            ->add('yourField', GutenbergType::class, [
                'label' => 'Your Field',
                // ... other options
            ]);
    }
}

Gutenberg Blocks

The Gutenberg editor comes with a variety of default blocks:

Text

core/paragraph
core/citation
"core/preformatted"
nucleus/verse
core/list
core/list-item

Media

core/image
noyau/audio
core/video
core/gallery
« core/media-text »
core/file
core/coverage

Formatting

core/code
core/html
core/citation
core/table
main text columns

Layout

core/button
core/buttons
core/column
core/columns
core/group
core/separator
core/spacing
core/list-of-pages
core/list-item-page
core/navigation
core/navigation-link
core/navigation-menu

Widgets

core/archives
core/calendar
core/categories
core/latest-comments
core/latest-articles
core/rss
core/research
core/shortcode
"core/social link"
core/social-links
core/tag-cloud

Integrate

core/embed
core/block
core/pattern

Site

«core/site-logo»
core/site-title
core/site-slogan
home/link
core/login-logout

Model

core/query
core/query-pagination
core/next-page-request
core/query-pagination-numbers
core/previous-pagination-request
core/query-without-results
core/query-title
core/model-part

Post

core/article-title
core/publication-excerpt
core/featured-image
core/article-content
core/article-author
core/author-name
core/publication-date
core/post-terms
core/next-navigation-link
core/publication-model
core/comment-form
core/author's-biography

Comments

core/comments
core/author-name-of-the-comment
core/content-comment
core/comment-date
core/edit-comment-link
core/response-link-to-comment
core/comment-model
core/comments-title
"core/comments-pagination"
"core/comments-pagination-next"
core/comments-pagination-numbers
core/comments-pagination-previous

Plus

core/plus
"core/next page"
core/read-more
core/details
core/footnotes
core/avatar
core/missing

Media upload

The media download function is enabled by default. You can override the media context as follows:

$formMapper
    ->add('content', GutenbergType::class, [
        'label' => 'Content',
        'context' => 'default'
    ]);

Customization of allowed blocks

You can specify which blocks are allowed:

$formMapper
    ->add('content', GutenbergType::class, [
        'label' => 'Content',
        'allowed_blocks' => [
            "core/pattern",
            "core/categories",
            // ... other allowed blocks
        ],
    ]);

Add custom patterns

Step 1: Create a templates directory

To add custom templates, create a directory in your project configuration:

Access your configuration directory: config/
Create a new directory named patterns/

Step 2: Add your pattern library

Inside the pattern directory, create your own pattern library:

Create a subdirectory for your library: config/patterns/my-library/
Inside this library directory, add your pattern files (for example, pattern1.php). The files can be named as desired.

Step 3: Define the model files

Each pattern file must contain a PHP header and the Gutenberg block code. Here is an example of a header and block layout:

<?php
/**
 * Title: My Test Pattern 1
 * Description: Example of a custom pattern
 * Categories: test
 */
?>
<!-- wp:group {"layout":{"type":"constrained","contentSize":"400px"}} -->
<div class="wp-block-group">
    <!-- wp:cover {"url":"[Image URL]","dimRatio":0,"isDark":false,"style":{"border":{"radius":"10px"}},"layout":{"type":"constrained"}} -->
    <div class="wp-block-cover is-light" style="border-radius:10px">
        <!-- Your block content -->
    </div>
    <!-- /wp:cover -->
</div>
<!-- /wp:group -->

Finally, the structure should look like this:

--config<br>
-----patterns<br>
--------my-library<br>
-----------------patern1.php<br>
-----------------patern2.php<br>

Step 4: Configure FormType

Importer GutenbergPatternsService :

Import GutenbergPatternsService in your administration class.

use App\Service\GutenbergPatternsService;

Inject the Service:

Use the attribute #[Required] to inject GutenbergPatternsService :

#[Required]
public function required(GutenbergPatternsService $gutenbergPatterns): void {
    $this->gutenbergPatterns = $gutenbergPatterns;
}

*Set up the FormMapper :

Retrieve the patterns and pass them on to FormMapper :

$patterns = $this->gutenbergPatterns->getPatterns(['my-library']);

$formMapper
    ->add('content', GutenbergType::class, [
        'label' => 'Content',
        'patterns' => $patterns,
        'context' => 'default',
        'allowed_blocks' => [
            "core/pattern",
            "core/categories",
            // ... other allowed blocks
        ],
    ])
;

Adapt the example to the installed version

The Symfony and Sonata examples remain tied to the versions indicated in the article. Symfony 4.x and Symfony 6.2 are no longer maintained: for a current project, use a maintained branch and the documentation that exactly matches your dependencies.

php bin/console about
composer show symfony/framework-bundle sonata-project/admin-bundle

Before resuming the code, check the signatures, services, routes, and templates concerned. Then add a functional test covering permissions, HTTP code, and the visible result.

Reference: maintained Symfony versions.