Blocs Gutenberg avec Sage 9 sur WordPress

<p>Comment organiser son thème WordPress Sage 9 pour créer et gérer des blocs Gutenberg avec Advanced Custom Fields (ACF).</p>







<p>L&#8217;objectif de cet article va être de créer un bloc Gutenberg avec des champs ACF sur le moteur de thème Sage 9.</p>



<p>À la sortie de <a href="https://roots.io/sage/" target="_blank" rel="noreferrer noopener">Sage 9</a>, WordPress n&#8217;avait pas encore en tête de gérer des blocs Gutenberg avec ACF; cela n&#8217;existait pas encore. Désormais c&#8217;est possible; et heureusement pour nous, la structure de Sage nous permettant aisément de développer cette fonctionnalité.</p>



<p>Sommaire : </p>



<ol><li>Collecter automatiquement tous nos blocs Gutenberg dans Sage</li><li>Création d&#8217;un bloc exemple &#8220;Témoignage&#8221;</li><li>Création d&#8217;un style dédié pour ce bloc</li><li>Gestion de la vue côté front</li><li><a href="#sources">Mise à disposition des sources</a></li></ol>



<h2>Architecture des blocs</h2>



<pre class="wp-block-code"><code>app/
  Blocks/ &lt;-- Où seront stocké tous nos blocs Gutenberg
    AbstractBlock.php &lt;-- classe abstraite commune à tous nos blocs
    QuoteBlock.php &lt;-- Configuration de notre bloc témoignage d'exemple
  blocks.php &lt;-- collecteur de blocs Gutenberg
resources/
  assets/
    images/
      blocks-previews/
        quote.jpg &lt;-- Image de prévisualisation de notre bloc témoignage
    styles/
      blocks/
        quote.scss &lt;-- style dédié à notre bloc Gutenberg
  views/
    blocks/
      block-quote.blade.php &lt;-- Vue de notre bloc témoignage d'exemple</code></pre>



<h2 id="h-cr-ation-d-un-collecteur-de-blocs-gutenberg-dans-sage">Création d&#8217;un collecteur de blocs Gutenberg dans Sage</h2>



<p>L&#8217;idée de cette section va être de créer un fichier qui va collecter automatiquement tous les blocs Gutenberg.</p>



<p>La logique de Sage 9 se trouve dans le répertoire app/ à la racine de notre thème. Nous allons suivre cette même logique pour nous permettre de créer notre collecteur de blocs.</p>



<p>Nous allons créer un répertoire Blocks au sein du répertoire app de notre thème. Celui-ci contiendra toute la logique de nos blocs.</p>



<pre class="wp-block-code"><code>$ mkdir app/Blocks</code></pre>



<p>A l&#8217;intérieur de ce dernier, nous allons créer une classe abstraite PHP AbstractBlocks.php. Elle contiendra toute la logique commune à nos blocs Gutenberg.</p>



<pre class="wp-block-code language-php"><code>&lt;?php
// app/Blocks/AbstractBlock.php

namespace App\Blocks;

use function App\asset_path;

abstract class AbstractBlock
{
    public string $name = '';
    public string $icon = '';

    public function __construct()
    {
        add_action('acf/init', &#91;$this, 'registerBlockType']);
    }

    public function registerBlockType(): void
    {
        acf_register_block_type(&#91;
            'name' =&gt; $this-&gt;name,
            'title' =&gt; $this-&gt;labels()&#91;'title'],
            'description' =&gt; $this-&gt;labels()&#91;'description'],
            'render_callback' =&gt; &#91;$this, 'acfBlockRenderCallback'],
            'category' =&gt; 'layout',
            'icon' =&gt; $this-&gt;icon,
            'enqueue_style' =&gt; asset_path('styles/' . $this-&gt;name . '.css'),
            'example' =&gt; &#91;
                'attributes' =&gt; &#91;
                    'mode' =&gt; 'preview',
                    'data' =&gt; &#91;
                        'image_path' =&gt; \App\asset_path('images/blocks-previews/' . $this-&gt;name . '.jpg'),
                    ]
                ]
            ],
        ]);
    }

    abstract protected function labels(): array;

    public function acfBlockRenderCallback($block, $content, $is_preview)
    {
        if ($is_preview &amp;&amp; isset($block&#91;'data']&#91;'image_path'])) {
            echo '&lt;img class="img-fluid" src="' . $block&#91;'data']&#91;'image_path'] . '"
            alt="' . $this-&gt;name . '" /&gt;';
            return;
        }

        echo \App\template(
            \App\locate_template('views/blocks/block-' . $this-&gt;name . '.blade.php'),
            &#91;'block' =&gt; $block]
        );
    }
}
</code></pre>



<p><strong>$name</strong> = correspondra au slug de notre bloc<br><strong>$icon</strong> = l&#8217;îcone qui sera utilisé dans notre éditeur Gutenberg, vous pouvez choisir une icone grace aux <a href="https://developer.wordpress.org/resource/dashicons/" target="_blank" rel="noreferrer noopener nofollow">Dashicons de WordPress</a>. </p>



<h2 id="h-pr-paration-de-l-initialisation">Préparation de l&#8217;initialisation</h2>



<p>Maintenant que toute la base est prête pour accepter nos blocs; on va devoir dire à Sage 9 de charger correctement tous les fichiers dans le dossier Blocks.</p>



<p>Nous allons créer un fichier dans le dossier app/ que l&#8217;on va nommer blocks.php :</p>



<pre class="wp-block-code language-php"><code>&lt;?php
// app/blocks.php

namespace App;

$blocks = collect(glob(__DIR__ . '/Blocks' . '/*.php'))
-&gt;map(function ($file_name) {
    return str_replace('.php', '', basename($file_name));
})-&gt;reject(function ($class_name) {
    return $class_name === 'AbstractBlock';
})-&gt;map(function ($class_name) {
    $full_class_name = "\\App\\Blocks\\{$class_name}";
    $class = new $full_class_name;
    return 'acf/'.$class-&gt;name;
})-&gt;values()-&gt;toArray();</code></pre>



<p>Ce fichier va collecter tous les blocs dans le répertoire Blocks/</p>



<p>Il ne nous reste plus qu&#8217;à appeler notre fichier blocks.php dans le fichier functions.php dans le dossier resources  (ligne 61) du thème comme ceci : </p>



<pre class="wp-block-code language-php"><code>/**
 * Sage required files
 *
 * The mapped array determines the code library included in your theme.
 * Add or remove files to the array as needed. Supports child theme overrides.
 */
array_map(function ($file) use ($sage_error) {
    $file = "../app/{$file}.php";
    if (!locate_template($file, true, true)) {
        $sage_error(sprintf(__('Error locating &lt;code&gt;%s&lt;/code&gt; for inclusion.', 'sage'), $file), 'File not found');
    }
}, &#91;'helpers', 'setup', 'filters', 'admin', 'blocks']);</code></pre>



<h2>Création de notre bloc Témoignage Gutenberg</h2>



<p>On rentre dans le vif du sujet avec la création de notre premier bloc Gutenberg avec Sage 9.</p>



<h3 id="h-configuration-du-bloc">Configuration du bloc</h3>



<p>Pour commencer, nous allons créer un nouveau bloc dans notre répertoire app/Blocks. Il va nous permettre de connecter notre bloc à l&#8217;administration d&#8217;une page avec Gutenberg :</p>



<pre class="wp-block-code language-php"><code>&lt;?php
// app/Blocks/QuoteBlock.php

namespace App\Blocks;

class QuoteBlock extends AbstractBlock
{
    public string $name = 'quote';
    public string $icon = 'format-quote';

    protected function labels(): array
    {
        return &#91;
            'title' =&gt; __('Témoignage', 'sage'),
            'description' =&gt; __('Affiche un bloc bleu pleine page avec un témoignage', 'sage')
        ];
    }
}
</code></pre>



<p>Comme on l&#8217;a vu plus haut, on va devoir définir deux paramètres : </p>



<p><strong>$name</strong> : Où on va définir le slug &#8220;quote&#8221;,<br><strong>$icon</strong> : et on va choisir une présentation de témoignage avec nos Dashicons</p>



<p>La méthode labels() va nous servir à définir toutes les traductions de notre bloc.</p>



<h3 id="h-style-du-bloc">Style du bloc</h3>



<p>Pour personnaliser l&#8217;affichage de notre bloc, on va créer un fichier de style SCSS dans le répertoire resources/assets/styles/blocks/ :</p>



<pre class="wp-block-code"><code>## resources/assets/styles/blocks/quote.scss

.block-quote {
  background: black;
  color: #fff;
}</code></pre>



<p>Ce fichier sera compilé avec Webpack lors de l&#8217;exécution de yarn build. Il va ensuite être lu par Gutenberg pour définir le style de notre bloc.</p>



<p>Pour ce faire, on va dire à Sage 9 qu&#8217;il doit aussi compiler indépendamment notre fichier CSS :</p>



<pre class="wp-block-code"><code>{
  "entry": {
    "quote": &#91;
      "./styles/blocks/quote.scss"
    ]
  },
}
</code></pre>



<h3 id="h-image-de-pr-visualisation">Image de prévisualisation</h3>



<p>Lors du passage de notre souris sur le bloc Gutenberg dans l&#8217;administration, on va afficher une image de présivualisation de notre bloc pour indiquer à nos administrateurs à quoi ressemble notre bloc.</p>



<p><em>Je préfère cette méthode plutôt que d&#8217;afficher le bloc avec des données d&#8217;exemple.</em></p>



<p>Vous êtes libre de la taille de votre image de prévisualisation, elle sera automatiquement redimensionnée par WordPress.</p>



<div class="wp-block-image"><figure class="aligncenter size-full"><img width="503" height="162" src="https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/previews-gutenberg-quote.jpg?resize=503%2C162&#038;ssl=1" alt="Présentation d'un bloc de prévisualisation Gutenberg" class="wp-image-4962" srcset="https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/previews-gutenberg-quote.jpg?w=503&amp;ssl=1 503w, https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/previews-gutenberg-quote.jpg?resize=300%2C97&amp;ssl=1 300w" sizes="(max-width: 503px) 100vw, 503px" data-recalc-dims="1" /></figure></div>



<p>Vous devez placer l&#8217;image dans le répertoire resources/assets/images/blocks/quote.jpg</p>



<h3 id="h-afficher-notre-bloc-c-t-front-et-gutenberg">Afficher notre bloc côté front et Gutenberg</h3>



<p>Nous allons désormais créer la vue de notre bloc Gutenberg qui sera partagée entre le front et le back depuis notre thème sage.</p>



<p>Nativement, Gutenberg ne sait pas lire le format .blade.php. Mais grace à notre AbstractBlock, on va pouvoir dire à Gutenberg comment le faire.</p>



<p>Créons un fichier dans notre répertoire views resources/views/blocks/block-quote.blade.php :</p>



<pre class="wp-block-code"><code>&lt;div class="block-quote"&gt;
  Hello World
&lt;/div&gt;
</code></pre>



<h2 id="h-dynamiser-notre-bloc-avec-acf">Dynamiser notre bloc avec ACF</h2>



<p>Désormais toute la structure de nos blocs est en place, on va pouvoir passer à l&#8217;ajout des champs personnalisés.</p>



<h3 id="h-wordplate-acf">Wordplate ACF</h3>



<p>Je ne suis pas un très grand fan de gérer mes champs ACF avec l&#8217;interface du backoffice. Même si l&#8217;interface est très pratique et user-friendly pour certain cas, je préfère construire mes ACF directement depuis mon thème. </p>



<p>Cela me permet de basculer ce thème sur une autre instance de WordPress sans devoir tout recréer côté Backoffice.</p>



<p>Pour ça, je m&#8217;appuie sur un compagnon de longue date qui se nomme <a href="https://github.com/wordplate/extended-acf/" target="_blank" rel="noreferrer noopener">Wordplate ACF</a>. </p>



<p>Il est installable grâce à Composer ! ça tombe bien, notre thème Sage 9 utilise aussi composer pour son fonctionnement interne !</p>



<pre class="wp-block-code language-bash"><code>composer require wordplate/acf</code></pre>



<p>Le <a href="https://github.com/wordplate/extended-acf/blob/master/README.md" target="_blank" rel="noreferrer noopener">README de Wordplate ACF</a> est très complet et introduit tout le comportement d&#8217;ACF au travers de son outil.</p>



<h3 id="h-prise-en-charge-d-acf-dans-nos-blocs-gutenberg-sur-notre-th-me-sage">Prise en charge d&#8217;ACF dans nos blocs Gutenberg sur notre thème Sage</h3>



<p>Au même titre que le chargement de nos blocs Gutenberg dans le thème Sage. Nous allons mettre en place dans notre AbstractBlock.php une petite méthode pour nous simplifier la vie.</p>



<p>Nos blocs en interne auront juste les champs à gérer, le reste se fera dans notre classe abstraite.</p>



<p>Commençons par rajouter une nouvelle méthode registerAcfBlockFields dans notre AbstractBlock.php :</p>



<pre class="wp-block-code language-php"><code>&lt;?php
// app/Blocks/AbstractBlock.php

namespace App\Blocks;

use WordPlate\Acf\Location;
use function App\asset_path;

abstract class AbstractBlock {
  // &#91;...]

  protected function registerAcfBlockFields(): void
  {
    $fields = wp_parse_args($this, &#91;
      'title' =&gt; $this-&gt;name,
      'fields' =&gt; $this-&gt;fields(),
      'location' =&gt; $this-&gt;location(),
      'hide_on_screen' =&gt; '',
    ]);

    register_extended_field_group($fields);
  }

  public function location(): array
  {
      return &#91;
          Location::if('block', 'acf/' . $this-&gt;name)
      ];
  }

  abstract protected function fields(): array;

  public function registerBlockType(): void
  {
    // &#91;...]
    $this-&gt;registerAcfBlockFields();
  }

}</code></pre>



<p>Comme vous pouvez le voir, on ajoute notre champ au travers du helper de Wordplate ACF register_extended_field_group(). Ensuite, on déclare une méthode abstraite pour rajouter les champs à notre classe de bloc.</p>



<h3 id="h-ajout-des-champs-acf-dans-notre-bloc-t-moignage">Ajout des champs ACF dans notre bloc témoignage</h3>



<p>On va pouvoir désormais rajouter des champs personnalisé à notre bloc Gutenberg Témoignage.</p>



<p>Pour cela, on va avoir besoin d&#8217;un champ texte, d&#8217;un auteur avec son titre/fonction et d&#8217;un avatar.</p>



<figure class="wp-block-image alignwide size-large"><img width="1024" height="272" src="https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/bloc-gutenberg-exemple-sage.jpg?resize=1024%2C272&#038;ssl=1" alt="Exemple de bloc Gutenberg côté front et back" class="wp-image-4960" srcset="https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/bloc-gutenberg-exemple-sage.jpg?resize=1024%2C272&amp;ssl=1 1024w, https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/bloc-gutenberg-exemple-sage.jpg?resize=300%2C80&amp;ssl=1 300w, https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/bloc-gutenberg-exemple-sage.jpg?resize=768%2C204&amp;ssl=1 768w, https://i0.wp.com/backend.inrage.fr/wp-content/uploads/2021/10/bloc-gutenberg-exemple-sage.jpg?w=1077&amp;ssl=1 1077w" sizes="(max-width: 1000px) 100vw, 1000px" data-recalc-dims="1" /></figure>



<p>C&#8217;est parti pour éditer notre fichier app/Blocks/QuoteBlock.php pour y faire nos changements et rajouter nos champs personnalisés : </p>



<pre class="wp-block-code language-php"><code>&lt;?php
// app/Blocks/QuoteBlock.php

namespace App\Blocks;

use WordPlate\Acf\Fields\Image;
use WordPlate\Acf\Fields\Text;
use WordPlate\Acf\Fields\Textarea;

class QuoteBlock extends AbstractBlock
{
    // &#91;...]

    protected function fields(): array
    {
        return &#91;
            Textarea::make('Contenu', 'blockquote')-&gt;rows(4)-&gt;newLines('br'),
            Image::make('Photo', 'avatar')-&gt;returnFormat('id'),
            Text::make('Nom', 'fullname'),
            Text::make('Fonction', 'function'),
        ];
    }
}</code></pre>



<h3 id="sources">Modification de la vue</h3>



<p>Il ne nous reste plus qu&#8217;à modifier la vue de notre block dans le fichier resources/views/blocks/quote.blade.php</p>



<pre class="wp-block-code language-html"><code>&lt;div class="block-quote {{ $block&#91;'className'] }}"&gt;
  &lt;div class="block-quote__text"&gt;{!! get_field('blockquote') !!}&lt;/div&gt;
  &lt;div class="author"&gt;
    &lt;div class="author__avatar"&gt;
      {!! wp_get_attachment_image(get_field('avatar')) !!}
    &lt;/div&gt;
    &lt;div&gt;
      &lt;div class="author__name"&gt;{!! get_field('fullname') !!}&lt;/div&gt;
      &lt;div class="author__function"&gt;{!! get_field('function') !!}&lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</code></pre>



<p>Vous êtes désormais fin prêt à gérer tous vos autres blocs Gutenberg avec votre thème Sage 9.</p>



<p>Si vous le désirez, j&#8217;ai mis à disposition les sources de cette article sur Github :</p>



<p><a href="https://github.com/inrage/wordpress-sage9-blocks" target="_blank" rel="noreferrer noopener">https://github.com/inrage/wordpress-sage9-blocks</a></p>

Blocs Gutenberg avec Sage 9 sur WordPress

Articles reliés

Contact Form 7 : Utiliser l’URL pour définir la valeur d’un select ou radio

Activer le mode maintenance de WordPress sans plugin