Il est fréquent que les applications Web ont besoin d’afficher des messages de notification (aussi appelés « messages flash ») pour les utilisateurs après le traitement d’un formulaire ou de tout autre type de saisie d’utilisateur.
\nPour cela, Django offre une prise en charge complète des messages stockés dans des cookies ou dans les sessions, aussi bien pour des utilisateurs anonymes que des utilisateurs connectés. L’infrastructure des messages permet de stocker temporairement des messages dans une requête et de les récupérer ensuite dans une prochaine requête (en générale la suivante) pour les afficher. Chaque message est étiqueté avec un niveau spécifique déterminant sa priorité (par ex. info, warning ou error).
Les messages sont implémentés par une classe d”intergiciel accompagnée d’un processeur de contexte.
\nLe fichier settings.py par défaut créé par django-admin startproject contient déjà tous les réglages nécessaires pour activer la fonctionnalité des messages :
'django.contrib.messages' figure dans INSTALLED_APPS.
MIDDLEWARE contient 'django.contrib.sessions.middleware.SessionMiddleware' et 'django.contrib.messages.middleware.MessageMiddleware'.
Le moteur de stockage par défaut dépend des sessions. C’est pourquoi SessionMiddleware doit être actif et apparaître avant MessageMiddleware dans MIDDLEWARE.
L’option 'context_processors' du moteur DjangoTemplates défini dans le réglage TEMPLATES contient 'django.contrib.messages.context_processors.messages'.
Si vous ne souhaitez pas utiliser les messages, vous pouvez enlever 'django.contrib.messages' du réglage INSTALLED_APPS, enlever la ligne MessageMiddleware du réglage MIDDLEWARE et enlever le processeur de contexte messages du réglage TEMPLATES.
L’infrastructure des messages peut utiliser différents moteurs pour stocker temporairement les messages.
\nDjango fournit trois classes de stockage intégrées dans django.contrib.messages:
Cette classe stocke tous les messages à l’intérieur de la session de la requête. Elle a donc besoin de l’application contrib.sessions de Django.
Cette classe stocke les données de messages dans un cookie (signé par l’empreinte secrète pour éviter d’être manipulé) pour que les notifications soient conservées d’une requête à l’autre. Les anciens messages sont effacés si la taille des données du cookie dépasse 2048 octets.
\nCette classe utilise d’abord CookieStorage, puis se rabat sur SessionStorage pour les messages qui ne rentrent pas dans un seul cookie. Elle exige également la présence de l’application contrib.sessions de Django.
Ce comportement évite d’écrire dans la session autant que possible. Cela donne en général les meilleures performances.
\nFallbackStorage est la classe de stockage par défaut. Si elle ne correspond pas à vos besoins, vous pouvez choisir une autre classe de stockage en définissant MESSAGE_STORAGE au chemin complet d’importation de la classe, par exemple :
MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'\nPour écrire votre propre classe de stockage, héritez de la classe BaseStorage dans django.contrib.messages.storage.base et implémentez les méthodes _get et _store.
L’infrastructure des messages est basée sur une architecture de niveaux configurable et semblable à celle du module de journalisation de Python. Les niveaux de messages permettent de grouper des messages par type afin qu’ils puissent être filtrés ou affichés différemment dans les vues et les gabarits.
\nLes niveaux intégrés, qui peuvent être importés directement depuis django.contrib.messages, sont :
Constante | \nBut | \n
|---|---|
| \nMessages liés au développement qui seront ignorés (ou supprimés) dans un déploiement en production. | \n
| \nMessages d’information pour l’utilisateur. | \n
| \nUne action a réussi, par ex. « votre profil a été mis à jour avec succès ». | \n
| \nIl n’y a pas eu d’erreur, mais il pourrait y en avoir une sous peu. | \n
| \nUne action n’a pas réussi ou une autre erreur quelconque s’est produite. | \n
Le réglage MESSAGE_LEVEL peut être utilisé pour modifier le niveau minimum enregistré (ou il peut être modifié selon la requête). Les tentatives d’ajouter des messages à un niveau inférieur à celui-ci seront ignorées.
Pour ajouter un message, appelez :
\nfrom django.contrib import messages\nmessages.add_message(request, messages.INFO, 'Hello world.')\nQuelques méthodes de raccourci fournissent une manière standard d’ajouter des messages avec les étiquettes couramment utilisées (qui sont généralement représentées sous formes de classes HTML des messages) :
\nmessages.debug(request, '%s SQL statements were executed.' % count)\nmessages.info(request, 'Three credits remain in your account.')\nmessages.success(request, 'Profile details updated.')\nmessages.warning(request, 'Your account expires in three days.')\nmessages.error(request, 'Document deleted.')\nDans votre gabarit, utilisez quelque chose comme :
\n{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>\n {% endfor %}\n</ul>\n{% endif %}\nSi vous utilisez le processeur de contexte, le gabarit devrait être produit avec un RequestContext. Sinon, assurez-vous que messages soit disponible dans le contexte du gabarit.
Même si vous savez qu’il n’y a qu’un message, il faut tout de même passer en boucle la liste des messages, sinon le message ne sera pas effacé de son stockage pour la requête suivante.
Le processeur de contexte fournit également une variable DEFAULT_MESSAGE_LEVELS qui fait correspondre les niveaux de messages à leur valeur numérique :
{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>\n {% if message.level == DEFAULT_MESSAGE_LEVELS.ERROR %}Important: {% endif %}\n {{ message }}\n </li>\n {% endfor %}\n</ul>\n{% endif %}\nEn dehors des gabarits, vous pouvez utiliser get_messages():
from django.contrib.messages import get_messages\n\nstorage = get_messages(request)\nfor message in storage:\n do_something_with_the_message(message)\nPar exemple, vous pouvez récupérer tous les messages pour les renvoyer dans une réponse JSONResponseMixin au lieu d’une réponse TemplateResponseMixin.
get_messages() renvoie une instance du moteur de stockage configuré.
MessageLien vers cette rubrique#Lorsque vous parcourez en boucle la liste des messages dans un gabarit, vous obtenez des instances de la classe Message. Il s’agit d’un objet très simple, ne possédant que quelques attributs :
message: le contenu textuel du message.
level: un nombre entier décrivant le type du message (voir la section sur les niveaux de messages ci-dessus).
tags: une chaîne combinant toutes les étiquettes de messages (extra_tags et level_tag) séparées par des espaces.
extra_tags: une chaîne contenant les étiquettes personnalisées du message, séparées par des espaces. Vide par défaut.
level_tag: la représentation textuelle du niveau. Par défaut, il s’agit de la version en minuscules du nom de la constante associée, mais cela peut être modifié en cas de besoin par l’emploi du réglage MESSAGE_TAGS.
Les niveaux de messages ne sont en fait que des nombres entiers, vous pouvez donc facilement définir vos propres niveaux et les utiliser pour créer des retours d’information plus personnalisés, par exemple :
\nCRITICAL = 50\n\ndef my_view(request):\n messages.add_message(request, CRITICAL, 'A serious error occurred.')\nSi vous créez des niveaux de messages personnalisés, vous devriez éviter de remplacer des niveaux existants. Les valeurs des niveaux intégrés sont :
\nConstante de niveau | \nValeur | \n
|---|---|
| \n10 | \n
| \n20 | \n
| \n25 | \n
| \n30 | \n
| \n40 | \n
Si vous avez besoin d’identifier les niveaux personnalisés dans du code HTML ou CSS, il est nécessaire de fournir une correspondance dans le réglage MESSAGE_TAGS.
Le niveau minimal enregistré peut être défini par requête au travers de la méthode set_level:
from django.contrib import messages\n\n# Change the messages level to ensure the debug message is added.\nmessages.set_level(request, messages.DEBUG)\nmessages.debug(request, 'Test message...')\n\n# In another request, record only messages with a level of WARNING and higher\nmessages.set_level(request, messages.WARNING)\nmessages.success(request, 'Your profile was updated.') # ignored\nmessages.warning(request, 'Your account is about to expire.') # recorded\n\n# Set the messages level back to default.\nmessages.set_level(request, None)\nDe même, le niveau actuel effectif peut être obtenu par get_level:
from django.contrib import messages\ncurrent_level = messages.get_level(request)\nPour plus d’informations sur le fonctionnement du niveau minimal enregistré, voir Niveaux de messages ci-dessus.
\nLors de l’écriture d’une application réutilisable (ou autre bout de code) et que l’on veut inclure la fonctionnalité des messages mais sans exiger des utilisateurs son activation s’ils ne le souhaitent pas, il est possible de transmettre un paramètre nommé supplémentaire fail_silently=True aux diverses méthodes de la famille add_message. Par exemple :
messages.add_message(\n request, messages.SUCCESS, 'Profile details updated.',\n fail_silently=True,\n)\nmessages.info(request, 'Hello world.', fail_silently=True)\nAjoute un attribut de message de succès aux classes basées sur FormView.
cleaned_data correspond aux données nettoyées du formulaire utilisé pour la mise en forme de la chaîne.
Exemple de fichier views.py:
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import Author\n\nclass AuthorCreate(SuccessMessageMixin, CreateView):\n model = Author\n success_url = '/success/'\n success_message = "%(name)s was created successfully"\nLes données nettoyées de form sont disponibles pour l’interpolation de chaîne avec la syntaxe %(nom_champ)s. Pour les ModelForm, si vous avez besoin d’accéder aux champs de l’objet enregistré, surchargez la méthode get_success_message().
Exemple de fichier views.py pour ModelForms :
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import ComplicatedModel\n\nclass ComplicatedCreate(SuccessMessageMixin, CreateView):\n model = ComplicatedModel\n success_url = '/success/'\n success_message = "%(calculated_field)s was created successfully"\n\n def get_success_message(self, cleaned_data):\n return self.success_message % dict(\n cleaned_data,\n calculated_field=self.object.calculated_field,\n )\nLes messages sont marqués pour leur suppression lorsqu’on boucle sur leur instance de stockage (puis effacés lorsque la réponse est traitée).
\nPour empêcher que les messages soient effacés, il est possible de définir le stockage des messages à False après l’itération :
storage = messages.get_messages(request)\nfor message in storage:\n do_something_with(message)\nstorage.used = False\nEn raison du fonctionnement des cookies (et donc des sessions), le comportement des moteurs qui se basent sur des cookies ou des sessions n’est pas défini lorsqu’un même client effectue plusieurs requêtes qui définissent ou lisent des messages en parallèle. Par exemple, si un client démarre une requête qui crée un message dans une fenêtre (ou un onglet) puis une autre qui récupère les messages non lus dans une autre fenêtre avant que la première fenêtre ait reçu sa redirection, il se peut que le message apparaisse dans la seconde fenêtre au lieu de la première où il aurait dû apparaître.
\nEn bref, lorsque plusieurs requêtes simultanées proviennent du même client, il n’y a aucune garantie que les messages soient affichés dans la même fenêtre qui les a produits, ou qu’ils soient effectivement affichés quelque part. Notez que cela ne pose habituellement pas de problème dans la plupart des applications et que ce problème va disparaître dans HTML5 où chaque fenêtre/onglet possède son propre contexte de navigation.
\nQuelques réglages permettent de contrôler le comportement des messages :
\n\nPour les moteurs qui utilisent les cookies, les réglages du cookie sont tirés des réglages du cookie de session :
\n\n