API day: Les messages Flash

L’API TYPO3 met à disposition beaucoup de fonctionnalités dont certaines assez peu connues.
Voici, par exemple, la gestion des messages d’information dans TYPO3.

Cette fonctionnalité permet d’uniformiser le système d’affichage des messages d’information, d’avertissement ou d’erreur dans les développements TYPO3.

A) Présentation

Il n’est pas rare d’avoir à mettre en place des messages d’information à destination des contributeurs.
Par exemple :
– affichage d’un texte de confirmation en cas de traitement terminé avec succès
– affichage d’une procédure de secours en cas de traitement terminé en erreur
– etc …

L’API met à disposition des développeurs un système de gestion de messages permettant d’uniformiser cette communication à destination des contributeurs.

TYPO3 utilise déjà ce système, par exemple dans le module page ou le planificateur de tache ou pour confirmer certaines actions.

Dans le module page à la racine :

Dans le module page dans un dossier système

Dans le planificateur de tache

Cela peut être utile aussi dans le cas de processus qui n’aurait pas de retour graphique comme par exemple le résultat d’un hook dans le TCEMAIN.

Il faut savoir que le code est compatible pour un fonctionnement en Backoffice comme pour un fonctionnement en Frontoffice, il est donc possible d’utiliser aussi les flashmessages directement dans ses plugins Front, afin de confirmer une action utilisateur ou d’informer d’une erreur.

B) Création d’un « message flash » en backoffice

Pour créer un nouveau message « flash » il faut déclarer un objet de type « t3lib_FlashMessage ».
Cet objet prend en paramètre :
– le message proprement dit (le contenu de la bulle d’information)
– le titre (affiché en haut de la bulle).
– le type de message (voir paragraphe sur les types de messages )
– la mise en session

Ce dernier paramètre est spécial parce qu’il active la mise en session du message. Au lieu d’un affichage instantané (et une perte du message si le module ne permet pas l’affichage des messages), ce dernier sera conservé pour l’utilisateur connecté tant qu’il n’est pas possible de l’afficher.
Par exemple si l’ajout se fait dans un module ne permettant pas l’affichage des messages flash, ces derniers seront stockés dans la session jusqu’à ce qu’un module compatible (ex le module page ou le module liste) les affiche.
Cela veut dire que les messages pourraient être affichés « hors contexte » et que le contributeur pourrait ne pas comprendre ce message.
Dans cet article on partira sur le fonctionnement par défaut, c’est à dire sans mise en session.

Préparation du message

<?php
  //version TYPO3 v4.X
  $flashMessage = t3lib_div::makeInstance(
     't3lib_FlashMessage',
     '<br/>Le message Flash est bien visible (texte).<br/>',
     'Confirmation (titre)',
     t3lib_FlashMessage::OK,
     FALSE
  );

  //ATTENTION :  à partir de la version 6.0, la déclaration change :
  //version TYPO3 v6.X
  $FlashMessage =  \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
     'TYPO3\\CMS\Core\\Messaging\\FlashMessage',
     '<br/>Le message Flash est bien visible (texte).<br/>',
     'Confirmation (titre)',
     \TYPO3\CMS\Core\Messaging\FlashMessage::OK,
     FALSE
  );
?>

A partir de ce code, l’objet $flashMessage contient tout ce qu’il faut pour générer le message flash, il ne reste donc plus qu’à l’afficher.

C) Affichage d’un message flash en backoffice

1) Affichage manuel du message

Il est possible de générer soi même l’affichage du message Flash.
Pour cela il suffit d’appeler la fonction « render() » de l’objet déclaré précédemment.
Le code HTML renvoyé par cette fonction tout le bloc du message.

<?php
  //génération manuelle du bloc du message
  //version v4.X et v6.X
  $content = $flashMessage->render();
?>

L’avantage est qu’il est possible de choisir simplement où sera positionné le message flash.
La seule contrainte est qu’il faut le faire autant de fois qu’il y a de message à afficher.
Capture d’écran du résultat :

2) Affichage automatique

Dans le cas du développement d’un module, le framework met en place la mécanique pour afficher automatiquement tous les messages qui auraient été générés par ce module

Ajout du message dans la file d’attente des messages pour un affichage « dès que possible »

<?php
  //mise en file d'attente du message
  //version v4.X
  t3lib_FlashMessageQueue::addMessage($flashMessage);

  //ATTENTION :  à partir de la version 6.0, la déclaration change :
  //version v6.X
  $flashMessageService =  \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Messaging\\FlashMessageService');
  /** @var $defaultFlashMessageQueue \TYPO3\CMS\Core\Messaging\FlashMessageQueue */
  $defaultFlashMessageQueue = $flashMessageService->getMessageQueueByIdentifier();
  $defaultFlashMessageQueue->enqueue($flashMessage);
?>

L’affichage se fera alors automatiquement lors de l’appel de la fonction « moduleBody() » présent dans les classes de templating du backoffice.
Les messages viendront se placer juste au dessus du contenu généré, ou alors à l’emplacement du tag ###FLASHMESSAGES### si celui ci est présent dans le template HTML utilisé par la classe de templating.
Pour gérer l’ordre d’affichage il est nécessaire de gérer l’ordre d’ajout dans la file d’attente.

3) Cas des processus sans affichage

Dans le cas d’un processus sans affichage (ex : hook du TCEMAIN), c’est ce fonctionnement qui est à utiliser.
En effet, si on met en place un processus effectuant une tache lors de la mise à jour d’enregistrement et que l’on désire un message de confirmation, il faut remplir la file d’attente des messages et attendre que l’utilisateur affiche un module compatible avec l’affichage des messages flash.
Attention : bien que rare, il n’est pas impossible que l’administrateur soit dans un module qui ne prenne pas en charge l’affichage des messages (par la mise en place d’une redirection du navigateur ou par la non utilisation des fonctions de templating backend).
Dans ces cas là, le message peut ne pas être visible de l’utilisateur.

C) Affichage d’un message flash en frontoffice

L’api TYPO3 autorise la génération de message flash depuis un plugin front.
La seule différence est que les CSS pour la mise en forme ne sont pas intégrés automatiquement.
Voici par exemple le code permettant de mettre en place la base des CSS :

<?php
  $code  = ".typo3-message .message-header{padding: 10px 10px 0 30px;font-size:0.9em;}";
  $code .= ".typo3-message .message-body{padding: 0 10px 10px 10px;font-size:0.9em;}";

  $GLOBALS['TSFE']->getPageRenderer()->addCssFile(t3lib_extMgm::siteRelPath('t3skin') . 'stylesheets/visual/element_message.css');
  $GLOBALS['TSFE']->getPageRenderer()->addCssInlineBlock('flashmessage',$code);
?>

Source:
http://www.thefox.ch/php/code-schnipsel/typo3/t3lib-flashmessage-im-frontend-nutzen/

D) Équivalent coté client en javascript

Le framework TYPO3 met aussi à disposition, dans l’environnement backend, un ensemble de fonctionnalités javascript. Parmi ces fonctionnalités, on retrouve l’équivalent des messages Flash.

Ces messages sont utilisés par exemple dans le cas de problèmes avec ExtBase, ou dans le gestionnaire d’extensions pour afficher un détail des opérations effectuées pendant l’installation de l’extension.

Capture d’écran du gestionnaire d’extension lors d’une installation :

Cela passe par l’appel de la fonction javascript « TYPO3.Flashmessage.display ».
Cette fonction prend en paramètre :
– le type de message (voir paragraphe sur les types de messages )
– le titre (affiché en haut de la bulle).
– le message proprement dit (le contenu de la bulle d’information)
– la durée (en seconde) pendant laquelle sera affichée le message.

Voici par exemple le code javascript permettant de lancer l’affichage d’un message d’erreur :

 //affichage d'un message flash d'erreur pendant 15 secondes
 TYPO3.Flashmessage.display(
    TYPO3.Severity.error,
    'Annonce BIOS',
    'Clavier non trouvé. Appuyez sur F1 pour continuer',
    15
 );

Le message sera alors affiché en haut de l’interface d’administration. Une fois la durée écoulée, le message disparait automatiquement avec un petit effet d’animation.

E) Types de messages

Le type de message (3eme paramètre de la fonction en PHP, ou le 1er en javascript) permet de définir la présentation des messages par l’utilisation d’un code couleur et d’une icône contextualisée.
Cela permet de faire passer visuellement un complément d’information au contributeur.

Il existe par défaut plusieurs styles de messages :

1) information

Code à utiliser :
TYPO3 V4 : t3lib_FlashMessage::INFO
TYPO3 V6 : \TYPO3\CMS\Core\Messaging\FlashMessage::INFO
Javascript : TYPO3.Severity.information

2) avertissement

Code à utiliser :
TYPO3 V4 : t3lib_FlashMessage::WARNING
TYPO3 V6 : \TYPO3\CMS\Core\Messaging\FlashMessage::WARNING
Javascript : TYPO3.Severity.warning

3) erreur

Code à utiliser :
TYPO3 V4 : t3lib_FlashMessage::ERROR
TYPO3 V6 : \TYPO3\CMS\Core\Messaging\FlashMessage::ERROR
Javascript : TYPO3.Severity.error

4) confirmation

Code à utiliser :
TYPO3 V4 : t3lib_FlashMessage::OK
TYPO3 V6 : \TYPO3\CMS\Core\Messaging\FlashMessage::OK
Javascript : TYPO3.Severity.ok

5) notice

Code à utiliser :
TYPO3 V4 : t3lib_FlashMessage::NOTICE
TYPO3 V6 : \TYPO3\CMS\Core\Messaging\FlashMessage::NOTICE
Javascript : TYPO3.Severity.notice

F) Informations:

Apparu sur TYPO3 v4.3, testé sur une v4.5 et toujours valide en v6.1.
La classe « t3lib_FlashMessage » (ancienne classe) fait partie des classes « migrées » qui ont vocation à être retirées du CMS après la version 6.2

Sources :
– Buzz.typo3.org : 4.3 Treasure Trove: Flash messages
– Flash messages dans la documentation CoreAPI