KACF - Simplifier la création et la réutilisation de blocs Gutenberg (WordPress)
Liens clés
Introduction
WordPress est un outil très pratique lorsqu'il s'agit de développer des sites internet administrables (et donc évolutifs) pour un client. En effet, cet outil open source et simple d'utilisation permet aux clients non expérimentés de modifier des titres, des images ou encore des fichiers PDF très facilement.
Pour simplifier la création des sites, WordPress intègre depuis maintenant quelques années l'éditeur Gutenberg permettant de manipuler des blocs dans l'éditeur de page.
Nous allons voir ici comment simplifier la création et la réutilisation de blocs Gutenberg personalisés.
Une première approche classique
L'extension ACF permet, dans sa version PRO, d'enregistrer de nouveaux blocs Gutenberg.
Pour chaque nouveau bloc, il est alors nécessaire de créer un fichier PHP, un fichier CSS, un fichier JS et de lier ces fichiers au nouveau bloc grâce à la fonction acf_register_block_type(...).
Par exemple, pour intégrer un nouveau bloc shortcode, nous aurons besoin des fichiers suivants :
- un fichier de template :
// template.php
<?php
$shortcode = get_field('shortcode');
?>
<section class="shortcode">
<?php echo do_shortcode($shortcode) ?>
</section>
- un fichier de style :
/* style.css */
.shortcode {
max-width: 600px;
margin: auto;
}
- (éventuellement) un fichier de script :
// script.js
console.log('Shortcode')
Pour ensuite créer le bloc comme suit avec ACF (PRO) :
// functions.php
acf_register_block_type(array(
'name' => "shortcode",
'title' => "Shortcode",
'description' => "A simple shortcode",
'category' => "",
'render_template' => "./template.php",
'icon' => "shortcode",
'keywords' => ["shortcode", "short"],
'post_types' => ["page"],
'mode' => "edit",
'enqueue_style' => "./style.css"
'enqueue_script' => "./script.js",
));
En plus de cette intégration, il est nécessaire d'ajouter le bloc Shortcode dans l'onglet ACF de l'espace d'administration du site pour intégrer tous les champs utilisés dans le template (par exemple dans notre cas le champ shortcode).
On remarque ici une duplication de code à la création de chaque nouveau bloc. En plus d'être répétitive et chronophage, cette manipulation est source d'erreur et ne permet pas la réutilisation des blocs entre les thèmes WordPress.
Une seconde approche avec KACF
C'est pour automatiser ce processus qu'a été créé KACF.
Son fonctionnement ?
KACF va récupérer et créer tous les blocs Gutenberg stockés dans un dossier spécifique. De cette manière, il n'est plus nécessaire de préciser les champs ACF dans l'espace d'administration ou d'enregistrer manuellement les blocs.
KACF en détail
Pour fonctionner, KACF a besoin d'être initialisé. Par exemple avec les paramètres par défaut :
// functions.php
new kacf();
Ou encore avec des paramètres personnalisés :
// functions.php
new kacf(
$gutpath = '/gutenberg/', // path of your gutenberg folder
$add_hooks = true, // add action and filter to launch the KACF class
$relative_paths = array(
'php' => 'template.php', // php template path inside the block folder
'css' => 'style.css', // css path inside the block folder
'js' => 'script.js', // js path inside the block folder
'acf' => 'acf.php' // acf path inside the block folder
),
$unregister_default_blocks = true // unregister the WP core blocks
);
Nous précisons ici l'emplacement des dossiers des blocs Gutenberg (dans le dossier /gutenberg/) et l'architecture de chacun des dossiers, à savoir :
- un fichier de template template.php,
- un fichier de style style.css,
- un fichier de script script.js,
- un fichier pour générer le bloc ACF (PRO) acf.php.
Afin de récupérer les informations de chaque bloc (nom, catégorie, icône...), KACF utilise la fonction native get_file_data(...) de WordPress. Cette fonction permet de récupérer des informations en commentaire placées au début d'un fichier PHP (utilisé notamment pour le nommage des templates de page).
Une nouvelle structure
Voici à quoi ressemble la nouvelle structure du thème WordPress :
...
functions.php
gutenberg/
|--- shortcode/
| |--- acf.php
| |--- style.css
| |--- script.js
| |--- template.php
|
|--- bloc2/
| |--- acf.php
| |--- style.css
| |--- script.js
| |--- template.php
...
...Avec un fichier de template modifié :
<?php
/*
* title: Shortcode
** icon: shortcode
** keywords:
** post_types:
** description:
** category:
*/
?>
<?php
$shortcode = get_field('shortcode');
?>
<section class="shortcode">
<?php echo do_shortcode($shortcode) ?>
</section>
(la clé name est générée à partir du nom du dossier pour éviter les doublons).
Et un fichier acf.php qu'il est possible d'extraire depuis l'onglet ACF de l'administration du site (pour plus d'informations, voir le forum ACF) :
<?php
if (function_exists('acf_add_local_field_group')) :
acf_add_local_field_group(array(
'key' => 'group_62ab4bdba7918',
'title' => 'Shortcode',
'fields' => array(
array(
'key' => 'field_62ab4bef6145b',
'label' => 'Code Court',
'name' => '',
'type' => 'message',
'instructions' => '',
'required' => 0,
'conditional_logic' => 0,
'wrapper' => array(
'width' => '',
'class' => '',
'id' => '',
),
'message' => 'Le Code Court (aussi appelé "shortcode") vous permet d\'intégrer un contenu important grâce à un simple texte.',
'new_lines' => 'wpautop',
'esc_html' => 0,
),
array(
'key' => 'field_62ab4be26145a',
'label' => 'Shortcode',
'name' => 'shortcode',
'type' => 'text',
'instructions' => '',
'required' => 1,
'conditional_logic' => 0,
'wrapper' => array(
'width' => '',
'class' => '',
'id' => '',
),
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
'maxlength' => '',
),
),
'location' => array(
array(
array(
'param' => 'block',
'operator' => '==',
'value' => 'acf/shortcode',
),
),
),
'menu_order' => 0,
'position' => 'normal',
'style' => 'default',
'label_placement' => 'left',
'instruction_placement' => 'label',
'hide_on_screen' => '',
'active' => true,
'description' => '',
'acfe_display_title' => '',
'acfe_autosync' => '',
'acfe_form' => 0,
'acfe_meta' => '',
'acfe_note' => '',
));
endif;
Les champs ACF générés depuis les fichiers acf.php sont des champs locaux. Ils ne sont donc ni visibles ni modifiables par défaut depuis l'onglet ACF du site internet. Pour permettre la modification de ces champs, il est possible d'utiliser l'extension ACF Extended.
Pour utiliser ce bloc sur un autre thème WordPress, il suffira alors de copier le dossier shortcode et de le coller dans le dossier gutenberg du nouveau thème.
Conclusion
La combinaison du nouvel éditeur de bloc Gutenberg et de la librairie KACF (couplée avec l'extension ACF (PRO)) permet de réutiliser très facilement les blocs Gutenberg entre des thèmes WordPress en évitant la duplication du code et les erreurs d'intégration.