Flash Notices

## What the messages framework is for `django.contrib.messages` delivers **one-time notices** ("Profile saved.", "Password too short.") from the request that creates them to the next page that displays them. The typical case is **Post/Redirect/Get**: a view handles a POST, saves something, and redirects. The redirect response renders no template, so the notice has to be stored somewhere between the two requests and shown once on the page the browser lands on. ## The three moving parts A new project from `startproject` already has all three enabled: | Part | Where | What it does | |---|---|---| | The app | `"django.contrib.messages"` in `INSTALLED_APPS` | Registers the framework | | The middleware | `django.contrib.messages.middleware.MessageMiddleware` in `MIDDLEWARE` | Attaches a storage object to each request and saves unread messages on the response | | The context processor | `django.contrib.messages.context_processors.messages` in the template `OPTIONS` | Puts `messages` (and `DEFAULT_MESSAGE_LEVELS`) into every template context | Without the middleware, calling `messages.success()` raises `MessageFailure` ("You cannot add messages without installing django.contrib.messages.middleware.MessageMiddleware") unless you pass `fail_silently=True`. ## Adding the notice in the view ```python from django.contrib import messages from django.shortcuts import redirect, render from .forms import ProfileForm def edit_profile(request): form = ProfileForm(request.POST or None, instance=request.user.profile) if request.method == "POST" and form.is_valid(): form.save() messages.success(request, "Profile saved.") return redirect("profile") return render(request, "accounts/profile_form.html", {"form": form}) ``` The shortcut functions `debug()`, `info()`, `success()`, `warning()` and `error()` all call `messages.add_message(request, level, message, extra_tags="", fail_silently=False)` with the matching level constant. Nothing is written at that moment: the message is **queued** on the request's storage, and `MessageMiddleware` stores it when the redirect response passes back through. ## Showing it in the template Put the loop in the base template so every page can display notices: ```django {% if messages %} <ul class="messages"> {% for message in messages %} <li class="{{ message.tags }}">{{ message }}</li> {% endfor %} </ul> {% endif %} ``` - `{{ message }}` renders the text. - `message.tags` is a space-separated string of any `extra_tags` plus the level tag (`"success"` here), ready for CSS classes. - `message.level` is the numeric level, useful with `DEFAULT_MESSAGE_LEVELS` for comparisons in templates. ## Why the notice shows exactly once Iterating the storage (the `{% for %}` loop) marks it as **used**. When the response for that page goes back through `MessageMiddleware`, the used messages are not stored again, so a reload does not show them. Only iteration counts: `{% if messages %}` checks the length without consuming anything. ## With a class-based view For an `UpdateView`, `django.contrib.messages.views.SuccessMessageMixin` adds the success message after `form_valid()` succeeds: ```python from django.contrib.messages.views import SuccessMessageMixin from django.views.generic import UpdateView class ProfileUpdateView(SuccessMessageMixin, UpdateView): fields = ["display_name", "bio"] success_url = "/profile/" success_message = "Profile saved for %(display_name)s." def get_object(self): return self.request.user.profile ``` `success_message` is interpolated with the form's `cleaned_data`. ## Common mistakes - **Rendering instead of redirecting after a successful POST.** The notice shows, but a browser refresh resubmits the form; redirect and let the message carry over. - **Putting the loop in only some templates.** A landing page that does not extend the base template never iterates `messages`, so the notice waits and appears on a later page. - **Passing the text in the query string.** It can be forged, bookmarked and logged; the messages framework signs cookie data and keeps session data server-side. - **Building a custom session key for notices.** You then have to remember to delete it; the framework already consumes on display. - **Adding the message in a script-driven endpoint.** A JSON response is never rendered with the template loop, so the notice appears on the next full page load instead. - **Forgetting `fail_silently=True` in a reusable app.** Projects that removed `MessageMiddleware` would otherwise get `MessageFailure`. ## Checklist 1. App, middleware and context processor enabled (they are by default). 2. `messages.success(request, ...)` **before** returning the redirect. 3. A `{% for message in messages %}` loop in a template every landing page extends. 4. Style with `message.tags`; do not build a custom session key for notices.