How to use the Messages Framework | Django Tutorial

Why should I use Messages?

Messages are used so you can give feedback to your visitors when something happens. Like if they submit a form, you might want to show a success message if everything is okay. Or you might want to show a message if there was an error.

Messages are built into all new Django projects, so you don't have to think about that.

A little example

Let's make a simple Django view where the user has submitted a contact form.

from django.contrib import messages
from django.shortcuts import render

def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)

        if form.is_valid():
            form.save()

            messages.success(request, 'The contact form was submitted!')
    else:
        form = ContactForm()

    return render(request, 'contact.html', {'form': form})

First we need to import Messages like we do on line 1. On line 11, we create a new Message.

Notice that we don't add the messages to the context for the frontend. This is because the messages is added to the session.

To show the messages, you can do the following:

{% if messages %}
    <ul class="messages">
        {% for message in messages %}
            <li class="{{ message.tags }}">{{ message }}</li>
        {% endfor %}
    </ul>
{% endif %}

This will generate something like this:

<ul class="messages">
  <li class="success">The contact form was submitted!</li>
</ul>

Different types of messages

DEBUG can only be used during development. In production, Django will automatically hide these messages.

Using together with Bulma / Custom classes

If you use a CSS framework like Bulma or Bootstrap, you often want to customize the message class. This can be done by adding an extra parameter like this.

from django.contrib import messages
from django.shortcuts import render

def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)

        if form.is_valid():
            form.save()

            messages.success(request, 'The contact form was submitted!', extra_tags='is-success')
    else:
        form = ContactForm()

    return render(request, 'contact.html', {'form': form})

To show the messages, you can do the following:

{% if messages %}
    {% for message in messages %}
        <div class="notification {{ message.tags }}">{{ message }}</div>
    {% endfor %}
{% endif %}

This will generate something like this:

<div class="notification success is-success">The contact form was submitted!</div>