Créer un bloc dans un module Drupal de manière programmatique

Les blocs dans Drupal 8 sont des instances de plugins de blocs.
Le gestionnaire de blocs de Drupal scanne vos modules à la recherche de classes contenant l’annotation @Block.

L’exemple de code ci-dessous utilise l’annotation @Block avec les propriétés « id » et « admin_label » pour définir un bloc personnalisé.

Créez le fichier src/Plugin/Block/HelloBlock.php dans la structure de votre module existant, puis ajoutez le code suivant.

Pour que Drupal reconnaisse cette nouvelle classe, il faudra vider le cache.

<?php

namespace Drupal\hello_world\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Fournit un bloc 'Hello'.
 *
 * @Block(
 *   id = "hello_block",
 *   admin_label = @Translation("Bloc Hello"),
 *   category = @Translation("Hello World"),
 * )
 */
class HelloBlock extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    return [
      '#markup' => $this->t('Hello, World!'),
    ];
  }

}

Pour ajouter le « Bloc Hello », allez dans Structure -> Disposition des blocs (admin/structure/block) et cliquez sur « Placer un bloc » dans la région souhaitée.

En cliquant sur « Placer un bloc », une fenêtre modale affichera la liste des blocs disponibles. Pour trouver rapidement votre bloc, utilisez l’option « Filtrer par nom » ou faites défiler jusqu’au « Bloc Hello ». Vous pouvez ainsi ajouter autant d’instances que vous voulez de ce bloc où vous voulez sur votre site.

Résolution des problèmes

• Le nom de la classe doit correspondre au nom du fichier (classe HelloBlock et fichier /src/Plugin/Block/HelloBlock.php). Si les noms diffèrent, le bloc apparaîtra dans la liste mais ne pourra pas être placé.
• Vérifiez soigneusement tous les chemins et noms de fichiers. Le fichier PHP doit être dans le bon répertoire (/src/Plugin/Block/) sinon Drupal ne le détectera pas.
• Si le bloc ne s’affiche pas sans erreur visible, consultez les logs d’erreurs PHP/Apache.
• Si le bloc n’apparaît pas dans la liste, videz le cache Drupal (par exemple via drush cr).
• Assurez-vous que le nom de votre module respecte la convention en minuscules. Certains ont remarqué que les blocs ne s’affichent pas pour des modules en camelCase (ex. myModule). Utilisez plutôt my_module. Ceci a été testé sous Drupal 8.8.1.

Note : Utilisation de templates Twig avec les blocs personnalisés

1. Ajoutez un hook_theme dans votre fichier .module.
Note : nommez la fonction de thème sans préfixe 'block__...' car cela n’enverra pas de variables aux templates de blocs. Utilisez plutôt le nom de votre module comme préfixe.

2. Utilisez la clé « #theme » dans le tableau de rendu de la méthode build() et transmettez les variables au même niveau que « #theme » avec des clés « #varname ».