Autopsie d'un module

A la racine du dossier "dh_like", nous trouverons tous ou quelques-uns de ces fichiers :

1. dh_like.info.yml : déclaration du module (obligatoire) ;
2. dh_like.links.menu.yml : déclaration des liens de menu ;
3. dh_like.routing.yml : déclaration des routes ;
4. dh_libraries.yml : déclaration des bibliothèques JS ou CSS ;
5. dh_like.permissions.yml : déclaration des droits ;
6. dh_like.module : définition du hook_theme ;
7. dh_like.install: définition du hook-shema ;

Les fichiers numérotés 1 à 6 sont étudiés dans les paragraphes  ci-dessous. Le fichier 7 est présenté dans le billet "gérer la table likes"

Les 5 premiers fichiers portent l'extension ".yml"  et respectent la syntaxe YAML. Ils définissent l' ensemble des hiérarchies qui organisent le fonctionnement du module.      
Les fichiers d'extension ".module"  et ".install" sont écrits en PHP.

Dans ce dossier "dh_like", nous trouverons également les dossiers :

• "templates" qui contient les fichiers, écrits en YAML, pour les gabarits (modèles) des pages de ce module.
• "src" qui contient des fichiers, écrits en PHP, comme par exemple :
  • dans le dossier "form", le code pour les formulaires :
  • dans le dossier "controller", le code pour les contrôleurs du module ;
  • dans le dossier "plugins", le code pour les blocs ...

 Notez qu'il est possible de créer la structure complète d'un module grâce  à la commande "drush gen module" comme l'illustre l'image ci-contre.    
Dans cette illustration, la structure du module "learning" est créée automatiquement avec ses 7 fichiers.    
Sont créés également, les fichiers :

• LearningController.php, placé dans le répertoire "src/Controller" : un code exemple pour créer un contrôleur définissant les actions à mener par les routes ;
• ExempleBlock.php, placé dans le répertoire "src/Plugin/Block" : un code exemple pour la réalisation d'un bloc ;
• SettingForm, placé dans le répertoire "src/Form" : un code exemple pour créer un formulaire permettant de stocker un élément de configuration en base de données.

Cette image illustre les connexions existant entre ces divers fichiers.

Ce fichier est le seul à être présent dans tous les modules. Il a pour fonction la déclaration du module à travers la hiérarchie suivante :

• name: (obligatoire) le nom du module tel qu'il apparaitra dans la page d'administration des modules ("admin/modules") ;
• description: (recommandé)  de 255 caractère au plus. Ce texte apparait dans cette même page d'administration (il peut comporter un lien <a href="     "> </a>) ;
• type: (obligatoire) valeur possible : module,  theme ou  profile ;
• core_version_requirement: (obligatoire ) : ^10
• version: (optionnel)  ;
• configure: (optionnel) spécifies la route vers la page du formulaire de configuration du module ;
• dependencies: (optionnel) la liste des modules dont dépend le module.

Accès à la documentation officielle.

Exemple :  
Le fichier "dh_like.info.yml" dont le code est affiché ci-dessous produit l'affichage illustré dans l'image pour la page "/admin/modules" mis en évidence par le "1" sur l'image ci-dessous.

Ce fichier a pour fonction la déclaration des liens de menus fournis par le module. 
Il contient une hiérarchie pour chaque lien à décrire.  Pour respecter la règle de nommage, le nom d'une hiérarchie doit débuter par le nom du module (donc pour mon module par "dh_like."). Elle porte le nom (unique) de la route à décrire. . Elle doit avoir comme clés : 
 

• title: (obligatoire) définit le texte du lien dans le menu ;
• description: (optionnel) le texte de la balise <title> du lien ;
• route_name: (obligatoire) le nom de la route à appeler (cf : .routing.yml) ;
• menu_name: (optionnel) le nom du menu dans lequel sera placé le lien ( par défaut le menu "tools - outils" : /admin/structure/menu/manage/tools) ;
• parent: (optionnel) le nom du lien parent dans le menu ( par défaut la racine) ;
• weight: (optionnel) le rang dans l'ordre d'affichage (par défaut ordre alphabétique)

Accès à la documentation officielle.

 Exemple :  
Le fichier "dh_like.links.menu.yml" dont le code est affiché ci-dessous produit l'affichage illustré ci-dessous. 
"dh_like.home:" est le nom de la hiérarchie présentée.

Ce fichier a pour fonction la déclaration des "routes" du module. Une route relie un lien ("path") à un "gestionnaire" (contrôleur,  formulaire, etc)    qui effectue des traitements et affiche un contenu.

Accès à la documentation officielle.

Ce fichier contient une hiérarchie pour chacune des routes à déclarer.
Pour respecter la règle de nommage, le nom de chaque hiérarchie doit débuter par le nom du module. Elle doit avoir comme clés :

• path: URL de la page créée.  Ce chemin doit commencer par un slash et ne pas dépasser neuf niveaux ;
• defaults: hiérarchie qui définit les caractéristiques par défaut de la route. Elle indique principalement comment construire le contenu principal (ie : la page) correspondant à cette route. ;
  • _controller::method ou _form: ou ... : le nom complet du contrôleur ( au sens modèle - vue - contrôleur ) ou  du formulaire ... voir  https://www.drupal.org/docs/drupal-apis/routing-system/structure-of-routes
  • _title: le titre de la page créée ;
• requirements: hiérarchie qui définit les pré-requis à avoir pour accéder à la page. Cette hiérarchie peut utiliser les clés : 
  • _permission: le nom de la (des) autorisations d'accès à la page. Les autorisations de base de Drupal peuvent être complétée par un module à travers le fichier d'extension ".permissions.yml" (voir le §5). Ces autorisations se combinent par les opérateurs logiques "+" (ou) et "," (et).
  • _role: le nom du (des) rôle(s) autorisés. Ces rôles se combinent également par les opérateurs logiques "+"  et "," .
     

La clé _controller: (resp. _form) doit s'écrire sous la forme 'Drupal\module\Controller\ModuleController::methode' (resp. Drupal\module\Form\ModuleForm) dans laquelle :

• module doit être remplacé par le nom du module (en minuscule), donc par dh_like ;
• ModuleController doit être remplacé par le nom de la classe (au sens namespaced class),  donc LikeController  ;
• methode doit être remplacé par le nom de la méthode (function) créée dans la classe déclarée ci-dessus,  donc content().

Il est possible de passer des paramètres dans la route :

• ils figurent entre accolades dans la clé "path:" (exemple :   path: '/dh_like/ongletLike'/{param}') ;
• ils figurent comme paramètres de la fonction de traitement de la route (exemple : content($param)) ;
• ils sont validés dans la clé "requirements:" par exemple pour le paramètre "param" par :
  • param: 'article|page|billet'  ( "|" est l'opérateur logique "ou") : une liste de valeur
  • param: '[a-zA-Z]+ : une expression régulière.

La hiérarchie "dh_like.home:" du fichier "dh_like.routing.yml" produit, par la méthode "content()" du contrôleur "LikeController"  l'affichage illustré ci-dessous. Il s'agit d'une version simple de la page  d'administration du module "dh_like". Une version plus élaborée est décrite dans le billet "Administrer un module". 

Ce fichier contient les hiérarchies annonçant les fichiers de style associés au module.

Accès à la documentation officielle.

Dans le code suivant, qui est celui de mon module personnalisé "dh_like", la hiérarchie "custom" est  appelée par les "renderable array" des fichiers "like_controller.php" présenté dans le paragraphe 7 et "dh_like_form.php" présenté dans le billet "le bloc like" pour mettre en forme les items produits par le module : page, formulaires...

custom: 
 version: 1.x 
 css: 
   theme: 
     css/dh_like.css: {}

Le billet ".libraries.yml" présente l'étude du fichier des librairies utilisé par le thème de ce site.

Ce fichier a pour fonction la déclaration  des sections à ajouter dans la page "/admin/people/permissions" pour les droits d'accès à ce module.

Il contient une hiérarchie par section à ajouter, chaque hiérarchie porte le nom (unique) de la section à décrire.        
Une hiérarchie a pour clé :

• title: (obligatoire) le titre qui sera affiché en tête de section ;
• description: (obligatoire)  sera affiché en complément du titre dans la page des permissions ;
• restrict access: (optionnel) ie par défaut FALSE - si TRUE affichage de l'info d'avertissement danger de Drupal ;

Accès à la documentation officielle.

Pour que des sections soient ajoutées dynamiquement (par programmation), il faut déclarer une hiérarchie dont le nom est   "permission_callbacks"        
qui suit cette syntaxe       
 permission_callbacks:        
  - Drupal\module\ModuleClass::méthode

dans laquelle :

• module doit être remplacé par le nom du module
• ModuleClass doit être remplacé par le nom de la classe  définie dans ce module (au sens namedclass). Celle ou se trouve la fonction qui effectue le traitement.
• méthode doit être remplacé par le nom de la la méthode (function) qui effectue le traitement et qui est définie dans la classe ci-dessus.

en savoir encore plus ...

Il est également possible de contrôler les accès dans le code. 
Par exemple :

if (\Drupal::currentUser()->hasPermission('dh_like, skip')) {} else {}

permet de contrôler l'accès de l'utilisateur actuel.

 Ci-dessous figure le code du fichier "dh_like.permissions.yml"  et la vue qu'il produit dans la page des droits ("\admin\people\permissions").

Ce fichier écrit en PHP génère le contexte d'affichage du module.  
Dans le "jargon" de Drupal, il s'agit d'implémenter le hook_thème : une fonction  qui doit être nommée "module_theme()",  ie pour mon module,  le hook_ thème s'appellera donc"dh_like_theme()". 

Cette fonction génère le contexte d'affichage du module (grossiérement dit :  des variables utilisées et  le nom du (des) template(s) (gabarit) qui réalise(nt) l'affichage). 

Accès à la documentation officielle.

Ci-dessous, le code du fichier "dh_like.module" de mon module perso "dh_like".

<?php  
/**  
* Implements hook_theme().  
*/  
function dh_like_theme() {  
 return [  
   'dh_like_block' => [  
        'variables' => [  
            'data' => [],  
        ],  
   ],  
    'dh_like_controller' => [  
        'variables' => [  
            'data' => [],  
        ],  
        // j'impose le nom du template à utiliser
        'template' => 'dh-like',  
   ],  
 ];  
}

Avec le code ci-dessus, deux "templates" sont chargés de l'affichage du module .

• le template "dh-like-block.html.twig" 
• le template "dh-like.html.twig"

Dans ces 2 thèmes, pour afficher le contenu de la variable 'data', il faut utiliser la syntaxe twig :  {{ data }}.

Notons que :

1. les extensions sont implicites ;
2. lorsque le nom du template n'est pas précisé, il est déduit  de  l'attribut #theme du "renderable array" appelant le "hook_thème". Les "_" (underscores) sont automatiquement remplacés par des "-"(tirets) ;
3. Ces fichiers doivent se trouver dans le dossier "templates" à la racine du dossier du module (ici : /modules/dh_like/templates/) . 

La ligne de code 'variables' => ['data'=>[] ] permet de récupérer les variables de l'attribut #data du "renderable array" en y ajoutant si nécessaire une valeur par défaut. Pour récupérer également l'attribut #var  de ce  "renderable array", on utilisera  :   'variables' => ['data'=>[], 'var'=>[], ] .

Ce dossier contient les fichiers et les dossiers réalisant le module. On y trouve en particulier les dossiers :

• "controller" qui contient les fichiers définissant les contrôleurs (par exemple le fichier "LikeController.php", cf: dh_like.routing.yml vu en §3)   ;
•  "form" qui contient les fichiers définissant les formulaires (par exemple : le fichier like_form.php);
•  "plugin" qui contient par exemple :
  • le sous-dossier Block pour les fichiers définissant les blocs du module (par exemple : le fichier dh_like_block.php)

 Analyse de LikeController.php :

<?php  
/**  
* @file  
* Contains \Drupal\dh_like\Controller\LikeController.  
*/  
namespace Drupal\dh_like\Controller;  
use Drupal\Core\Controller\ControllerBase;  

class LikeController extends ControllerBase {  
   public function content() {  
     return array(  
       '#type' => 'markup',  
       '#markup' => t('La page de likes'),  
       '#prefix' => '<span class="dh_like_admin"> ',
       '#suffix' => '</span>',
       '#attached' => [
            'library' => [
                'dh_like/custom',
            ],
        ],
   );  
 }  
}

Ce fichier définit la classe "LikeController"  et sa méthode content() dont l'objectif est l'affichage de (la traduction de) "La page de likes". D'après le fichier "dh_like.routing.yml", cette page a pour titre "Likes", son adresse  est "/admin/config/services/dh_like", elle est illustrée par l'image du $3.

Dans l'univers "Drupal", le tableau renvoyé par la fonction content() s'appelle "renderable array". Lire ces pages https://happyculture.coop/blog/drupal-8-lapi-de-rendu-render-api et https://www.drupal.org/docs/drupal-apis/render-api/render-arrays pour en savoir plus.

Ce dossier contient le(s) modèle(s) d'affichage (templates) pour les pages créées par le module (cf : le fichier "dh_like.module"). 
Un "template" affiche, en particulier, le contenu (de certaines) des variables déclarées dans les "renderable array" des fonctions du module (voir le §7).

Le fichier "dh-like-block.html.twig", dont le code suit, produit  l'affichage illustré ci-dessous. Cet affichage est mis en forme par les styles définis dans la bibliothèque "dh_like.css" attachée à ces "renderable array". Le code de cette bibliothèque figure dans l'onglet ci-dessous. 
Une description plus détaillée du bloc des likes est présentée dans le billet " le bloc likes".