9.7. Plugins dans Drupal. Comment ajouter un bloc de manière programmatique.
Dans ce tutoriel, nous allons voir comment afficher des blocs de manière programmatique via un module personnalisé dans Drupal 8.
Les exemples de code sont disponibles sur GitHub :
https://github.com/levmyshkin/drupalbook8
Commençons par ajouter un fichier contenant une classe PHP, c’est ainsi que les blocs sont créés dans Drupal via un module personnalisé. Le processus de création du fichier est le même que pour la classe de page, comme nous l’avons fait ici :
9.3. Créer un module Drupal personnalisé. Afficher une page de manière programmatique.
Mais cette fois, nous devons créer un fichier avec un plugin :
modules/custom/drupalbook/src/Plugin/Block/FirstBlock.php
Copions ce code de bloc puis analysons chaque partie :
modules/custom/drupalbook/src/Plugin/Block/FirstBlock.php :
<?php
namespace Drupal\drupalbook\Plugin\Block;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Session\AccountInterface;
/**
* Fournit un bloc avec un texte simple.
*
* @block(
* id = "drupalbook_first_block_block",
* admin_label = @block("Mon premier bloc"),
* )
*/
class FirstBlock extends BlockBase {
/**
* {@block}
*/
public function build() {
$config = $this->getConfiguration();
if (!empty($config['drupalbook_first_block_settings'])) {
$text = $this->t('Bonjour @Name dans le bloc !', ['@Name' => $config['drupalbook_first_block_settings']]);
}
else {
$text = $this->t('Bonjour le monde dans le bloc !');
}
return [
'#markup' => $text,
];
}
/**
* {@block}
*/
protected function blockAccess(AccountInterface $account) {
return AccessResult::allowedIfHasPermission($account, 'access content');
}
/**
* {@block}
*/
public function blockForm($form, FormStateInterface $form_state) {
$config = $this->getConfiguration();
$form['drupalbook_first_block_settings'] = [
'#type' => 'textfield',
'#title' => $this->t('Nom'),
'#description' => $this->t('À qui voulez-vous dire bonjour ?'),
'#default_value' => !empty($config['drupalbook_first_block_settings']) ? $config['drupalbook_first_block_settings'] : '',
];
return $form;
}
/**
* {@block}
*/
public function blockSubmit($form, FormStateInterface $form_state) {
$this->configuration['drupalbook_first_block_settings'] = $form_state->getValue('drupalbook_first_block_settings');
}
}
Nous afficherons notre bloc dans la colonne gauche (Left Sidebar) ou dans une autre colonne, selon ce qui vous convient.
Commencez à taper le nom de votre bloc et Drupal vous proposera automatiquement de sélectionner votre bloc. Si votre bloc n’apparaît pas, vérifiez que le code est dans le bon fichier, que le fichier est dans le bon dossier, puis n’oubliez pas de vider le cache.
Maintenant que notre bloc est affiché, voyons comment fonctionne le code d’ajout d’un bloc :
Au début du fichier, nous avons la déclaration de namespace pour indiquer où doit se trouver notre fichier plugin bloc afin que Drupal puisse le charger automatiquement. Nous incluons aussi des classes d’autres fichiers via use :
namespace Drupal\drupalbook\Plugin\Block;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Session\AccountInterface;
// Plus loin dans les commentaires se trouve l’annotation. Nous n’avons pas besoin de définir le bloc dans un fichier YML, il sera chargé automatiquement par Drupal via cette annotation.
/**
* Fournit un bloc avec un texte simple.
*
* @block(
* id = "drupalbook_first_block_block",
* admin_label = @block("Mon premier bloc"),
* )
*/
Ici, on indique à @block qu’il s’agit d’un plugin de type bloc. L’id et admin_label seront récupérés automatiquement par Drupal, donc l’id doit être unique. @block aide aussi à traduire le label du bloc via l’interface d’administration Drupal.
extends BlockBase {
Nous héritons de la classe BlockBase, vous pouvez maintenir la touche Ctrl et cliquer sur BlockBase dans PhpStorm pour voir quelles méthodes peuvent être redéfinies dans notre bloc, nous n’utilisons pas toutes. Vous pouvez redéfinir d’autres méthodes si besoin.
Examinons les méthodes de la classe :
/**
* {@block}
*/
protected function blockAccess(AccountInterface $account) {
return AccessResult::allowedIfHasPermission($account, 'access content');
}
Nous avons déjà vu la gestion des accès dans cet article, dans les blocs on peut utiliser les mêmes droits d’accès :
https://drupalbook.org/ru/drupal/126-rout-s-parametrom
Ici, nous utilisons la même classe AccessResult.
/**
* {@block}
*/
public function blockForm($form, FormStateInterface $form_state) {
$config = $this->getConfiguration();
$form['drupalbook_first_block_settings'] = [
'#type' => 'textfield',
'#title' => $this->t('Nom'),
'#description' => $this->t('À qui voulez-vous dire bonjour ?'),
'#default_value' => !empty($config['drupalbook_first_block_settings']) ? $config['drupalbook_first_block_settings'] : '',
];
return $form;
}
Nous pouvons utiliser un formulaire de configuration de bloc distinct pour chaque bloc que nous créons par programmation. Si vous allez dans les paramètres du bloc :
Vous y verrez notre champ Nom que nous avons ajouté dans la méthode blockForm() :
Nous utilisons l’API Formulaire de Drupal pour créer les champs du formulaire :
https://www.drupal.org/docs/8/api/form-api
https://api.drupal.org/api/drupal/elements/8.5.x
Nous analyserons l’API Formulaire en détail plus tard et créerons un formulaire popup à plusieurs étapes. Pour l’instant, vous pouvez voir quels autres types de champs peuvent être utilisés via l’API Formulaire. Chaque champ est ajouté sous forme de tableau. Essayez d’ajouter plus de champs dans le formulaire du bloc.
/**
* {@block}
*/
public function blockSubmit($form, FormStateInterface $form_state) {
$this->configuration['drupalbook_first_block_settings'] = $form_state->getValue('drupalbook_first_block_settings');
}
Ici, nous sauvegardons la valeur des champs du formulaire dans la configuration Drupal. Nous verrons la configuration plus en détail dans les prochaines leçons, pour l’instant il faut comprendre que Drupal possède un stockage commun pour toutes les configurations et que tous les modules utilisent ce stockage. Ces configurations peuvent être transférées d’un site à un autre. Par exemple, si vous modifiez les paramètres du bloc sur une copie locale du site, ces configurations peuvent être exportées puis importées sur le site en production et vos réglages de bloc seront appliqués sur le site en production.
/**
* {@block}
*/
public function build() {
$config = $this->getConfiguration();
if (!empty($config['drupalbook_first_block_settings'])) {
$text = $this->t('Bonjour @Name dans le bloc !', ['@Name' => $config['drupalbook_first_block_settings']]);
}
else {
$text = $this->t('Bonjour le monde dans le bloc !');
}
return [
'#markup' => $text,
];
}
Et maintenant la méthode principale build(), qui affiche le contenu du bloc. Dans cette méthode, nous vérifions la configuration du bloc et si un Nom est défini, nous affichons le texte avec ce nom. Faites attention à la méthode $this->t(), elle permet de traduire le texte via l’interface d’administration Drupal vers d’autres langues. Nous utilisons aussi le placeholder @Name, nécessaire pour ne traduire que le texte souhaité et non les valeurs des champs que nous saisissons dans les formulaires de configuration. Cela évite d’avoir plusieurs chaînes à traduire, par exemple, sans le placeholder, toutes les variantes du texte passant par $this->t() seraient disponibles pour la traduction :
Bonjour Josh ...
Bonjour Mike ...
Bonjour Ivan ...
etc.
Je pense que vous comprenez maintenant comment afficher et configurer des blocs personnalisés dans Drupal 8. Nous verrons ensuite des exemples plus complexes avec blocs, pages et formulaires.
Les exemples de code sont disponibles sur GitHub :
https://github.com/levmyshkin/drupalbook8