Autopsie d'un module

Dans l'univers Drupal, un module s'appuie sur une arborescence de fichiers très précise dont la racine porte le nom du module et qui se trouve dans le dossier "modules" de votre site. Pour la clarté du billet, je considérerai que l'on analyse le module "autopsie_module". L'arborescence débute donc par un dossier nommé "autopsie_module" situé dans le dossier "module" du site.

Le nom du module s'écrit en minuscule, le seul caractère spécial est _. Il doit être unique dans l'univers Drupal.

A la racine du dossier "autopsie_module", nous trouverons ces fichiers :

1. autopsie_module.info.yml
2. autopsie_module.routing.yml
3. autopsie_module.links.menu.yml
4. autopsie_module.permissions.yml
5. autopsie_module.module

Les fichiers portant l'extension yml respectent la syntaxe YAML.et définissent l' ensemble des hiérarchies qui organisent le fonctionnement du module.
Le fichier d'extension module est écrit en PHP et concerne principalement le rendu vers l'utilisateur.

Nous y trouvons également les dossiers :

• templates qui contiendra les fichiers, écrits en YAML, pour les gabarits (modèles) des pages de ce module.
• "src" qui contiendra les fichiers source, écrits en PHP,  du module comme par exemple le gestionnaire des permissions dynamiques ou le contrôleur du module ( dans le dossier "controller")

Ce fichier a pour fonction la déclaration du module
Cette hiérarchie doit avoir comme attribut :

• name: (obligatoire) tel qu'il apparaitra dans la page d'administration des modules ;
• description: (recommandé)  de 255 caractère au plus. Cette texte apparait dans la page d'administration des modules (il peut comporter un lien <a href="     "> </a>) ;
• type: (obligatoire) valeur possible : module ; theme ou  profile ;
• core: (obligatoire) 8.x pour un module destiné à D8 ;
• core_version_requirement: (optionnel) ^8 || ^9
• version: (optionnel) ;
• configure: specifies la route vers la page du formulaire de configuration du module ;
• dependencies: (optionnel) la liste des modules dont dépend le module

Exemple : le fichier captcha.info.yml du module CAPTCHA

name: CAPTCHA
type: module
description: Provides the CAPTCHA API for adding challenges to arbitrary forms.
package: Spam control
core: 8.x
configure: captcha_settings
dependencies:
  - drupal:node

Ce fichier a pour fonction la déclaration des routes (accès aux pages) du module.

Il contient une hiérarchie par route à décrire, la hiérarchie porte le nom de la route à décrire.
Une hiérarchie doit avoir comme attribut :

• path: URL de la page créative  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 ;
  • _controller: ou _form: le nom complet du contrôleur ( au sens modèle - vue - contôleur) ie : la fonction qui crée la page  dans le contrôleur ;
  • _title: le titre de la page créée par le contrôleur ;
• requirements: hiérarchie qui définit les pré-requis que le visiteur du site doit avoir pour accéder à la page ;
  • _permission:

L'attribut _controller: doit s'écrire sous la forme 'Drupal\module\Controller\ModuleController::methode dans laquelle :

• module doit être remplacé par le nom du module (en minuscule)
• ModuleController doit être remplacé par le nom de la classe (au sens namespaced class)
• methode doit être remplacé par le nom de la méthode (function) créée dans la classe déclarée ci-dessus (voir le $ sur le contrôleur)

 Ci-dessous figure un extrait du fichier captcha.routing.yml du module CAPTCHA

captcha_settings:
  path: '/admin/config/people/captcha'
  defaults:
    _form: '\Drupal\captcha\Form\CaptchaSettingsForm'
    _title: 'CAPTCHA settings'
  requirements:
    _permission: 'administer CAPTCHA settings'

captcha_examples:
  path: '/admin/config/people/captcha/examples/{module}/{challenge}'
  defaults:
    _form: '\Drupal\captcha\Form\CaptchaExamplesForm'
    _title: 'CAPTCHA examples'
    module: '   '
    challenge: '   '
  requirements:
    _permission: 'administer CAPTCHA settings'

Ce fichier a pour fonction la déclaration des liens que le module crée dans les menus du site.
Il contient une hiérarchie par lien à décrire. Elle porte le nom (unique) du lien à décrire.
Une hiérarchie doit avoir comme attribut :

• 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 "ctools - outils") ;
• 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)

 Ci-dessous figure un extrait du fichier captcha.links.menu.yml du module CAPTCHA

captcha.settings:
  title: 'CAPTCHA module settings'
  description: 'Administer how and where CAPTCHA is used.'
  route_name: captcha_settings
  parent: user.admin_index
  weight: -1

captcha.examples:
  title: 'CAPTCHA examples'
  description: An overview of the available challenge types with examples.'
  route_name: captcha_examples
  parent: captcha.settings
  weight: 0

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, la hiérarchie porte le nom (unique) de la section à décrire.
Une hiérarchie doit avoir comme attribut :

• 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 ;

 Ci-dessous figure le fichier captcha.links.menu.yml du module CAPTCHA et la vue qu'il produit dans la page des droits.

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
  - 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 ...

Ce fichier écrit en PHP génère le contexte d'affichage du module ( grossiérement dit : déclare le nom du template (gabarit) qui réalise l'affichage).
Dans le "jargon" de Drupal, il s'agit d'implémenter le hook_thème. C'est une fonction nommée "module_theme()" - module doit être le nom du module ; donc dans cette présentation  le hook_ thème s'appellera "autopsie_module_theme()" car le module se nomme "autopsie_module".

Ci-dessous,vous lirez le code typique de cette fonction.

function autopsie_module_theme($existing, $type, $theme, $path)
{
    return array(
        'autopsie_theme => array(
            'variables' => array(),
            'template' => 'autopsie_theme',
        )
    );
}

Donc selon le code ci-dessus, le fichier implémentant le template se nommera autopsie_theme.html.twig ( les extensions sont implicites ). Il doit se trouver dans le dossier "templates" à la racine du dossier du module (ici : /modules/autopsie_module/templates/autopsie_theme.html.twig).

La ligne de code 'variables' => array() est à utiliser pour installer vos propres variables .

'variables' => array('variable1' => NULL, 'variable2' => NULL, )

Ce dossier contient le(s) modèle(s) d'affichage (templates) pour les pages crées par le module (cf : le fichier xxxx.module) du module.
Il affiche, en particulier, le contenu de certaines variables déclarées et manipulées par le contrôleur du module (voir le §7).

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

•  "controller" et le fichier définissant la classe et la méthode (cf : xxxx.routing.yml)  du contrôleur ;
•  "form" et le fichier définissant la classe  (cf : xxxx.routing.yml)  du formulaire ;
•  "plugin"