Drupal Commerce 2 fournit par défaut un journal d'activité sur la vie de chaque commande : la mise au panier de produits, l'entrée dans le tunnel d'achat, la passation de la commande, son expédition éventuelle et sa conclusion.
A chaque statut de la commande correspond une entrée dans un journal qui est générée. Cela fournit un historique complet pour chaque commande.
Ayant eu besoin de personnaliser ce journal d'activité, pour permettre aux gestionnaires de la boutique en ligne d'inscrire dans ce journal différents commentaires liés à la gestion de la commande, j'ai découvert à cette occasion le petit module, utilisé pour générer ce journal, développé par les mainteneurs de Drupal commerce 2. Un petit module simple mais extrêmement puissant, intitulé commerce log. Mes modules préférés.
Nous allons découvrir comment utiliser ce module pour insérer des entrées de journal complémentaires. Ces entrées peuvent aussi bien être générées automatiquement, que correspondre à une saisie utilisateur.
Le module Commerce Log
Ce module déclare 2 types de Plugin : LogCategory et LogTemplate. Le premier nous permet de déclarer des catégories de log, tandis que le second nous permet de créer des templates de Log, que nous affecterons aux catégories préalablement créées. Son fonctionnement est extrêmement similaire à State Machine : pas d'interface graphique (d'où aussi moins de code, et donc de maintenance), et donc création / déclaration des plugins au moyen de fichiers de configuration YAML.
Mais parce qu'un bon exemple vaut parfois mieux q'un long discours, rentrons dans le vif du sujet tout de suite. Nous allons permettre aux gestionnaires des commandes de laisser des commentaires dans ce journal d'activité.
Un journal d'activité sur mesure
Créons un petit module MYMODULE et déclarons tout de suite notre template de Log.
La structure de notre module va ressembler à ceci
├── MYMODULE.commerce_log_categories.yml
├── MYMODULE.commerce_log_templates.yml
├── MYMODULE.info.yml
├── MYMODULE.install
├── MYMODULE.module
La catégorie d'un Log nous permet de spécifier pour quelle type d'entité le Log sera généré. Ici nous déclarons la catégorie MYMODULE_order qui concernera les entités Commandes de Drupal Commerce :
MYMODULE_order: label: Order comment entity_type: commerce_order
Puis nous déclarons notre template, ici order_comment que nous affectons à notre catégorie. Nous aurions pu ici utiliser la catégorie déjà créée par le module commerce log.
order_comment:
category: commerce_order
label: 'Comment'
template: "<p><b>{{ 'Comment'|t }} :</b> {{ comment }}</p>"
L'information clé du Plugin LogTemplate est son template qui est déclaré. Il s'agit en fait d'un simple inline_template de Twig. Ici nous déclarons notre inline template qui utilisera une variable comment.
Et c'est fini !
Enfin presque. Il ne reste plus qu'à générer nos entrées de journal au bon moment. Vu que nous souhaitons ici enregistrer des commentaires des gestionnaires de la boutique en ligne, nous allons intervenir avant l'enregistrement d'une commande.
Nous prenons soin de créer au préalable un simple champ texte, par exemple field_order_note, sur l'entité commande et mettons un peu en forme le formulaire d'édition d'une commande pour obtenir ce résultat.
Puis nous implémentons hook_entity_presave(), pour intervenir avant l'enregistrement d'une commande. Tout simplement nous allons vérifier si ce champ est renseigné, et le cas échéant nous générerons l'entrée de journal.
/**
* Implements hook_entity_presave().
*/
function MYMODULE_entity_presave(EntityInterface $entity) {
if ($entity instanceof OrderInterface) {
if ($entity->hasField('field_order_note')) {
if (!$entity->get('field_order_note')->isEmpty()) {
// Get the comment, clear it from the order, and log it.
$comment = $entity->get('field_order_note')->value;
$entity->set('field_order_note', '');
/** @var \Drupal\commerce_log\LogStorageInterface $logStorage */
$logStorage = \Drupal::entityTypeManager()->getStorage('commerce_log');
$logStorage->generate($entity, 'order_comment', ['comment' => $comment])->save();
}
}
}
}
La méthode clé ici pour générer l'entrée de journal est la methode generate() de la classe LogStorage.
Cette méthode attend comme arguments, l'entité elle-même, l'identifiant du template à utiliser, et enfin un tableau de paramètres à passer au template inline de Twig. Nous pouvons donc passer autant de paramètres que nécessaires au template Twig pour générer l'entrée du journal.
Et nous pouvons alors depuis le formulaire d'édition, saisir un commentaire.
Et nous retrouvons désormais cette note dans le journal d'activité de la commande.
Pour aller plus loin avec Commerce Log
Commerce log est utilisé pour générer le journal d'activité des commandes de Drupal commerce. Mais son design nous permet de générer des journaux pour n'importe quelle type d'entité de Drupal 8. Par exemple générer des journaux d'activité pour certains utilisateurs, en fonction de certaines actions réalisées sur les contenus d'un projet, selon des conditions basées par exemple sur les roles des utilisateurs et des termes de taxonomy communs. Aussi bien la suite de modules Message couvre ce besoin, mais si vous disposez déjà de Drupal Commerce 2 sur le projet, il n'est peut-être pas utile d'installer ces autres modules pour cela. Mais ceci fera l'objet d'un autre billet.
Ajouter un commentaire