Introduction to Django Messaging System And How to Use them In Templates

Django's messaging framework provides a way to temporarily store messages in one request and retrieve them for display in a subsequent request.

March 17, 2025 by

Hamed Mohammadi

| No comments yet

Django's messaging framework is a powerful yet simple tool that allows developers to display one-time notification messages (often called "flash messages") to users after processing forms or responding to user actions. These messages provide immediate feedback about the result of an operation, enhancing the user experience by communicating important information effectively. The framework is built into Django by default and provides a flexible system for creating, storing, and displaying these temporary messages.

What is Django's Messaging System?

Django's messaging framework provides a way to temporarily store messages in one request and retrieve them for display in a subsequent request (usually the next one). The system is designed to be lightweight and flexible, making it easy to implement common notification patterns in web applications. Messages are tagged with specific levels that determine their priority and visual presentation, similar to logging levels in Python.

The framework handles all the complexities of storing these messages between requests, whether the user is authenticated or anonymous, using either cookies or session-based storage. This means you can focus on what messages to show rather than how to implement the underlying storage and retrieval mechanism.

Setting Up the Messaging Framework

One of the best things about Django's messaging system is that it comes configured and ready to use in new Django projects. When you create a new project using django-admin startproject, the default settings.py file already includes all necessary configurations5.

The default setup includes:

'django.contrib.messages' in the INSTALLED_APPS setting
'django.contrib.sessions.middleware.SessionMiddleware' and 'django.contrib.messages.middleware.MessageMiddleware' in MIDDLEWARE
'django.contrib.messages.context_processors.messages' in the context processors list for your template engine

If you're working with an existing project that doesn't have these settings, you'll need to add them manually. The message middleware depends on session middleware, so ensure that SessionMiddleware appears before MessageMiddleware in your middleware settings.

Understanding Message Levels

Django's messaging framework organizes messages into different levels, similar to logging levels. Each level corresponds to a specific type of notification and has an associated integer value and tag:

Level Constant	Tag	Value	Purpose
DEBUG	debug	10	Development-related messages
INFO	info	20	Informational messages
SUCCESS	success	25	Successful action notifications
WARNING	warning	30	Warning messages
ERROR	error	40	Error notifications

These levels help categorize messages and allow for conditional formatting in templates. You can also configure the minimum level that will be recorded using the MESSAGE_LEVEL setting5. Any message with a level below this threshold will be ignored.

Adding Messages in Views

Adding messages in your Django views is straightforward. First, import the messages module from django.contrib:

from django.contrib import messages

Then, you can add messages in your view functions using either the add_message method or one of the convenience methods for specific levels:

# Using add_message method
messages.add_message(request, messages.INFO, 'Hello world.')

# Using convenience methods
messages.debug(request, "%s SQL statements were executed." % count)
messages.info(request, "Three credits remain in your account.")
messages.success(request, "Profile details updated.")
messages.warning(request, "Your account expires in three days.")
messages.error(request, "Document deleted.")

These messages are stored temporarily and will be available in the next request, making them perfect for form submission feedback.

Real-World Example: User Registration

Here's a practical example of using messages in a user registration view:

def register(request):
    if request.method == "POST":
        form = UserCreationForm(request.POST)
        if form.is_valid():
            user = form.save()
            username = form.cleaned_data.get('username')
            messages.success(request, f"New account created: {username}")
            login(request, user)
            return redirect("main:homepage")
        else:
            for msg in form.error_messages:
                messages.error(request, f"{msg}: {form.error_messages[msg]}")
            
    # ... rest of view code

This code adds a success message when a user successfully creates an account, and error messages if there are problems with the form submission.

Displaying Messages in Templates

To display messages to users, you need to iterate over the messages variable in your templates. The messages variable is automatically added to the template context by the messages context processor.

Here's a basic template example for displaying messages:

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

This code checks if there are any messages and then iterates over them, displaying each one in a list item. The message's tags (which correspond to the message level) are added as a CSS class, allowing you to style different types of messages differently.

It's important to note that even if you know there's only one message, you should still iterate over the messages sequence because this process is what clears the message storage for the next request.

Advanced Template Usage

You can also check the message level in your template to provide different formatting or additional content based on the message type:

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

This example adds the word "Important:" before error messages, making them stand out even more.

Styling Messages

The message tags (debug, info, success, warning, error) are added as CSS classes to the message elements, making it easy to style them differently. You can use these classes in your CSS to give different visual treatments to different types of messages:

.messages {
    list-style: none;
    margin: 0;
    padding: 0;
}

.messages li {
    padding: 10px 15px;
    margin-bottom: 10px;
    border-radius: 4px;
}

.debug {
    background-color: #e3f2fd;
    color: #0d47a1;
}

.info {
    background-color: #e8f5e9;
    color: #1b5e20;
}

.success {
    background-color: #e8f5e9;
    color: #1b5e20;
}

.warning {
    background-color: #fff3e0;
    color: #e65100;
}

.error {
    background-color: #ffebee;
    color: #b71c1c;
}

Message Storage Backends

Django provides three built-in storage classes for storing messages:

SessionStorage - Stores messages in the user's session, requiring Django's sessions framework to be enabled.
CookieStorage - Stores messages in a cookie, signed with a secret hash to prevent manipulation.
FallbackStorage - First tries to use CookieStorage, and falls back to SessionStorage for messages that won't fit in a cookie. This is the default storage class.

The default FallbackStorage provides the best performance in most cases by avoiding session writes when possible. However, if you need to customize the storage mechanism, you can set the MESSAGE_STORAGE setting to the full import path of your preferred storage class:

MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

Implementation Examples

Basic Messaging in a Simple Form Handler

def contact_form(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            # Process the form data
            form.save()
            messages.success(request, "Thank you for your message! We'll get back to you soon.")
            return redirect('contact_success')
        else:
            messages.error(request, "There was an error with your submission. Please check the form.")
    else:
        form = ContactForm()
    
    return render(request, 'contact/form.html', {'form': form})

Using Messages with Authentication

def login_view(request):
    if request.method == 'POST':
        form = AuthenticationForm(request, data=request.POST)
        if form.is_valid():
            username = form.cleaned_data.get('username')
            password = form.cleaned_data.get('password')
            user = authenticate(username=username, password=password)
            if user is not None:
                login(request, user)
                messages.info(request, f"You are now logged in as {username}")
                return redirect('home')
            else:
                messages.error(request, "Invalid username or password.")
        else:
            messages.error(request, "Invalid username or password.")
    else:
        form = AuthenticationForm()
    
    return render(request, 'login.html', {'form': form})

Integration with Front-end Frameworks

If you're using a front-end framework like Materialize CSS, you can integrate Django's messages with the framework's notification components. For example, with Materialize CSS, you can use "toasts" to display messages:

{% if messages %}
    {% for message in messages %}
        <script>
            document.addEventListener('DOMContentLoaded', function() {
                M.toast({html: "{{ message }}", classes: "{{ message.tags }}"});
            });
        </script>
    {% endfor %}
{% endif %}

Best Practices and Tips

Always iterate over messages: Even if you expect only one message, iterate over the messages collection to ensure they are properly cleared.
Use the appropriate level: Choose the message level that best matches the nature of your notification - don't use ERROR for informational messages or SUCCESS for warnings.
Keep messages concise: Messages should be short and to the point, providing just enough information for the user to understand what happened.
Include actionable information: When appropriate, include information about what the user should do next, especially for warning and error messages.
Consider message expiration: By default, messages are cleared after they're displayed once, but you can create a custom storage backend if you need different behavior.

Conclusion

Django's messaging framework provides a simple yet powerful way to communicate with users through one-time notifications. With minimal setup and a few lines of code, you can create a robust messaging system that enhances the user experience of your web application.

The framework's flexibility allows for easy integration with various front-end technologies and design patterns, while its built-in features handle the complexities of message storage and retrieval. By using appropriate message levels and thoughtful template design, you can create an informative and visually appealing feedback system for your users.

Whether you're building a simple contact form or a complex web application, Django's messaging system is an essential tool for effective user communication.

Citations:

in Django

Hamed Mohammadi March 17, 2025

Share this post

Our blogs

Archive

Please visit our blog at:

https://zehabsd.com/blog

A platform for Flash Stories:

https://readflashy.com

A platform for Persian Literature Lovers:

https://sarayesokhan.com

Sign in to leave a comment

Always First.

Be the first to find out all the latest news, products, and trends.