La gestion du fil d’Ariane dans Drupal : modules communautaires ou code ?

Drupal est capable d'automatiser la génération de fils d'Ariane via des modules de la communauté tels que Easy Breadcrumb ou encore Menu Breadcrumb. Selon le besoin, il est possible d’altérer le breadcrumb par des hooks.

Drupal possède également une API pour générer finement et de manière personnalisé un fil d'Ariane. Cela se fait grâce à l’implémentation de la classe BreadcrumbBuilderInterface. Ce qui sera le sujet de notre article.

Comment organiser son projet Drupal ?

Pour commencer, il faut savoir qu’il n’y a pas de limite d’implémentation d’une classe BreadcrumbBuilderInterface.

En effet, il est tout à fait possible d’avoir plusieurs “gestionnaires” de breadcrumb. Le choix du breabcrumb utilisé dans une page se fera en fonction des priorités et des conditions qui seront définies.

Prenons par exemple la situation suivante : je travaille sur un site qui dispose du module Menu Breadcrumb. Ce module va créer pour moi le fil d’Ariane de mes pages, à condition que celles-ci soient rattachées à un menu du site.

Oui mais voilà, je souhaiterais un fil d’Ariane différent pour les pages de type “Article”, avec des critères particuliers. Il faudra alors que j'implémente mon propre breadcrumb et faire en sorte qu’il ne soit utilisé que sur les pages Article.

Comme pour toute fonctionnalité dans Drupal, tout commence par un module. Chez Adimeo, l’organisation d’un projet Drupal veut que nous classions les modules du site par thématique ou type de page. C’est pourquoi je crée dans notre projet, un module qui concentrera tout ce qui impacte précisément les pages de type Article. Par convention il portera comme nom : nomduprojet_article.

Comment coder son fil d'Ariane ?

Maintenant que mon module existe, je peux commencer à développer mon gestionnaire de breadcrumb en créant une classe : ArticleBreadcrumbBuilder.php.

Cette classe devra implémenter l’interface BreadcrumbBuilderInterface, dont les méthodes ont un objet implémentant RouteMatchInterface en paramètre, et utilisera les classes Breadcrumb et Link pour générer le fil d’Ariane proprement dit.

J’aurai donc les bases suivantes dans mon fichier : nomduprojet_article/src/Breadcrumb/ArticleBreadcrumbBuilder.php

<?php
namespace Drupal\nomduprojet_article\Breadcrumb;

use Drupal\Core\Breadcrumb\BreadcrumbBuilderInterface;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Breadcrumb\Breadcrumb;
use Drupal\Core\Link;

Class ArticleBreadcrumbBuilder implements BreadcrumbBuilderInterface {

}

L’interface BreadcrumbBuilderInterface nous oblige à écrire deux méthodes :

• applies() : Permet de définir dans quels cas appeler notre constructeur de fil d’Ariane. Elle retournera TRUE ou FALSE selon le cas,
• build() : Retourne un objet Breadcrumb, c’est notre fil d’Ariane.

La méthode applies()

Cette méthode devra renvoyer la valeur TRUE si la page affichée correspond à un nœud et qu’il est de type "Article".

public function applies (RouteMatchInterface $route_match) {
    $parameters = $route_match->getParameters()->all();
    if(isset($parameters['node'])) {
        return $parameters['node']->getType() === 'article';
    }
}

La méthode build()

Avec cette méthode, il sera possible de définir le contenu du fil d’Ariane. Par exemple : un lien vers l’accueil, un texte "Articles" (sans lien pour l’exemple), le titre de l’article. En mettant le tout en cache pour chaque URL via la méthode addCacheContext().

  public function build(RouteMatchInterface $route_match) {
    $breadcrumb = new Breadcrumb();

    $breadcrumb->addCacheContexts(["url"]);

    $breadcrumb->addLink(Link::createFromRoute(t('Home'), ''));
    $breadcrumb->addLink(Link::createFromRoute(t('Articles'), ''));

    $request = \Drupal::request();
    $page_title = \Drupal::service('title_resolver')->getTitle($request, $route_match->getRouteObject());
    if (!empty($page_title)) {
      $breadcrumb->addLink(Link::createFromRoute($page_title, ''));
    }

    return $breadcrumb;
  }

Le code de notre classe est complet. Il me restera à la déclarer comme service dans le fichier nomduprojet_article.services.yml à la racine de mon module. J’utiliserai le tag breadcrumb_builder pour connecter la classe au gestionnaire de breadcrumb de Drupal.

Je préciserai également la priorité. Plus la priorité sera haute et plus elle sera appelée par rapport aux autres services utilisant le même tag (celui des modules contribués par exemple) : nomduprojet_article/nomduprojet_article.services.yml.

services:
  nomduprojet_article.breadcrumb:
    class: Drupal\nomduprojet_article\Breadcrumb\ArticleBreadcrumbBuilder
    tags:
      - { name: breadcrumb_builder, priority: 100 }

La dernière étape sera de vider les caches. Le fil d’Ariane apparaitra sur les pages de type "Article".

Une remarque pour terminer

Il existe une corrélation entre le Namespace de ma classe et l’emplacement du fichier PHP du projet.

Drupal utilise le standard PHP PSR4 pour l’autoloading et le Namespacing. Il faut garder en tête que le Namespace Drupal\nom_du_module\ correspond au répertoire src qui se trouve à la racine de votre module.

Ensuite, j’ajoute au Namespace le répertoire dans lequel se trouve mon fichier PHP. Chaque classe est rangée dans un répertoire par famille.

Même si techniquement rien ne m’empêche de nommer les répertoires comme je le veux, je vais tout de même respecter les standards définis dans un souci de bonnes pratiques. Voici quelques exemples : Controller, Service, Routing, Entity, Form, Plugin, etc.

Crédit photo : Yurich84