Dans un précédent billet, je vous ai présenté le module Crumbs qui permet de maitriser son fil d'Ariane selon des critères très complets (views, token, taxonomy, entity reference, etc). Son système de plugins lui permet de supporter toute entité créée sur votre site Drupal. Ainsi, Crumbs supporte nativement les noeuds, les termes de taxonomie et les utilisateurs bien sûr, mais aussi les entités Organic Group et Commerce (au travers de Commerce Checkout).
Mais qu'en est-il des entités créées sur mesure, ou encore celles fournies par des modules contribués, tel que Entity Registration par exemple ?
Depuis la version beta-12, créer un plugin pour Crumbs est d'une facilité déconcertante. Créons ensemble un module qui va nous pemettre d'affiner notre fil d'Ariane pour les entités Registration.
Nous allons créer un module MYMODULE_crumbs dont la structure est présentée ci-dessous
Et déclarons notre module avec le fichier MYMODULE_crumbs.info
name = MYMODULE Crumbs
description = Module for Crumbs custom plugins.
core = 7.x
package = MYPACKAGE
; This allows to put our plugin classes into dedicated folders.
dependencies[] = xautoload
Ce module a pour dépendance le module X Autoload qui fournit pour Drupal 7 le chargement automatique de classes PHP (PHP class autoloading) disponible désormais sur Drupal 8. Ce module supporte la norme PSR-4 implémentée sur Drupal 8, mais également la norme PSR-0.
Nous créons ensuite notre fichier MYMODULE_crumbs.module qui va implémenter HOOK_crumbs_plugin($api)
/**
* Implements hook_crumbs_plugins()
*
* @param crumbs_InjectedAPI_hookCrumbsPlugins $api
*/
function MYMODULE_crumbs_crumbs_plugins($api) {
// The class will be MYMODULE_crumbs_CrumbsMonoPlugin_Registration.
$api->monoPlugin('Registration');
// Custom breadcrumb for registration/% pages.
// Let be the breadcrumb parent of registration/%.
// The second argument will make this behavior available as
// "MYMODULE.crumbs.registration.parent" on the weights configuration form,
// where it can be prioritized against other behaviors.
$api->routeParentPath('registration/%', 'registration.parent', 'CUSTOM_PATH');
// Let "Registration for 'xyz'" be the breadcrumb item title for registration/%.
// The second argument will make this behavior available as
// "MYMODULE.crumbs.registration.title" on the weights configuration form.
$api->routeTitleCallback('registration/%', 'registration.title', function($path, $item) {
return t("Registration for '@anon_mail'", array('@anon_mail' => $item['map'][1]->anon_mail));
});
}
Que fait ce module ? Il implémente les méthodes $api->routeParentPath et $api->routeTitleCallback qui vont retourner respectivement le chemin du parent et le titre à afficher dans le fil d'Ariane. C'est aussi simple que cela !
Dans notre exemple, la méthode $api->routeParentPath va retourner lors de la consultation d'une entité Registration (chemin registration/%) comme parent le chemin CUSTOM_PATH. Ce plugin sera disponible dans l'interface d'administration de Crumbs sous le nom de MYMODULE.crumbs.registration.parent, et vous pourrez lui affecter le poids désiré.
La méthode $api->routeTitleCallback va retourner lors de la consultation d'une entité Registration (chemin registration/%) le titre de la page affiché dans le fil d'Ariane. Ce titre sera Registration for @anon_mail où la variable @anon_mail est récupérée de l'entité Registration elle-même (correspondant au courriel saisi d'un internaute qui s'est inscrit à un événement) et sera bien sûr traductible. A noter que la variable $item['map'] contient les fragments du chemin de la page consultée. Ainsi, dans notre exemple, $item['map'][0] contient la première partie du chemin (fragment registration), $item['map'][1] contient l'objet Registration (fragment %) et donc toutes ses valeurs.
A noter que la méthode $api->routeParentPath ne permet de retourner qu'une chaine de caractère CUSTOM_PATH unique, saisie comme paramètre de la méthode. Si ces deux méthodes vous suffisent, vous pouvez retourner à vos occupations.
A l'inverse, si vous avez besoin de retourner un chemin parent dynamique en fonction de l'entité Registration consultée, il vous faut implémenter votre propre Plugin. Dans ce cas nous allons utiliser la méthode $api->monoPlugin('Registration') qui va implémenter notre propre classe MYMODULE_crumbs_CrumbsMonoPlugin_Registration. Dans cet exemple nous implémentons un MonoPlugin qui ne retourne qu'un seul candidat comme chemin parent. Si vous avez besoin de retourner plusieurs candidats, il vous faudra implémenter un MultiPlugin avec la méthode $api->multiPlugin('Registration'). A noter que si vous implémentez votre plugin avec cette méthode, il va sans dire qu'il n'est plus nécessaire d'utiliser les méthodes $api->routeParentPath et $api->routeTitleCallback.
Une fois notre classe déclarée, nous allons donc l'implémenter dans le fichier Registration.php (situé dans l'arboresence du module sous le chemin MYMODULE_crumbs/lib/CrumbsMonoPlugin).
class MYMODULE_crumbs_CrumbsMonoPlugin_Registration implements crumbs_MonoPlugin {
/**
* {@inheritdoc}
*/
function describe($api) {
$api->setTitle('Parent breadcrumbs for Registration entity');
}
/**
* Find Parent for Registration entity on path registration/%
*
* @param string $path
* @param array $item
*
* @return string
* A candidate for the breadcrumb item parent.
*/
function findParent__registration_x($path, $item) {
// Parent will be the session the registration belong to
return 'node/' . $item['map'][1]->entity_id;
}
}
Notre classe déclare son titre qui apparaîtra dans l'interface d'administration de Crumbs ($api->setTitle) et implémente la méthode findParent() qui va calculer le chemin parent candidat pour chaque entité Registration.
Dans cet exemple, nous retournons le chemin du noeud hôte (Host Entity) représentant l'événement pour lequel l'internaute s'est inscrit. Pour aller plus loin sur les différentes méthodes proposées par Crumbs vous pouvez consulter l'API de Crumbs ou encore le module Crumbs example fourni avec le module.
C'est juste impressionnant la facilité avec laquelle nous pouvons désormais créer nos propres plugins Crumbs. Chapeau bas au(x) mainteneur(s) du module. Essayer Crumbs, c'est l'adopter, non ?
Ajouter un commentaire