Використання функції messages.add_message()

Ми вже встигли розібрати основні типи повідомлень, такі як success, error, warning та info, і обговорили, коли і як їх використовувати. Тепер настав час заглибитися в найпотужніший інструмент роботи з повідомленнями — messages.add_message(). Готові? Пристебніть ремені!

Що таке messages.add_message()

Спочатку розберемося, що таке messages.add_message() і навіщо він нам потрібен.
На практиці часто виникає потреба повідомити користувача про виконання якоїсь дії: успішну відправку форми, помилку при вході в систему або попередження про заповнення обов'язкових полів. Message Framework надає зручний спосіб додавання таких повідомлень у представлення — через метод messages.add_message().

У Django Message Framework є кілька скорочених функцій для додавання повідомлень: messages.success(), messages.error() і так далі. Однак add_message() надає найбільшу гнучкість:

1. Дозволяє задавати будь-який кастомний рівень повідомлення.
2. Універсальний — підходить для всіх типів повідомлень.
3. Підходить для динамічного додавання повідомлень.

Синтаксис функції messages.add_message()

Давай подивимось, як виглядає її базовий синтаксис:

from django.contrib import messages

messages.add_message(request, level, message, extra_tags='', fail_silently=False)

Розберемо аргументи:

• request: об'єкт запиту, в якому будуть зберігатися повідомлення.
• level: рівень повідомлення. Наприклад, messages.SUCCESS, messages.ERROR і так далі.
• message: текст самого повідомлення.
• extra_tags (необов'язково): додаткові теги для кастомізації відображення (наприклад, CSS-класи).
• fail_silently (необов'язково): якщо True, то ігнорує помилки при додаванні повідомлення.

Приклад використання

Почнемо з простого прикладу. Додамо повідомлення про успішну реєстрацію користувача.

from django.contrib import messages
from django.shortcuts import redirect

def register_user(request):
    # Логіка реєстрації користувача (умовно)
    if request.method == 'POST':
        # Виконуємо реєстрацію...
        messages.add_message(request, messages.SUCCESS, 'Ви успішно зареєструвалися!')
        return redirect('home')  # Перенаправляємо на головну сторінку

У цьому прикладі:

1. Ми додаємо повідомлення з рівнем SUCCESS.
2. Після додавання повідомлення користувач перенаправляється на home, де його чекає наше сповіщення.

Тепер, щоб побачити це повідомлення, потрібно рендерити їх у шаблоні (про це ми говорили у лекції 136). Якщо ви забули, нагадаю, як це робиться:

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

4. Динамічне додавання рівнів

За допомогою messages.add_message() ми можемо програмно вибирати рівень повідомлення. Наприклад, залежно від результату дії (успіх або помилка):

Приклад: динамічне визначення рівня повідомлення

from django.contrib import messages
from django.shortcuts import redirect

def process_form(request):
    if request.method == 'POST':
        form = MyForm(request.POST)
        if form.is_valid():
            # Успішно обробили форму
            messages.add_message(request, messages.SUCCESS, 'Форма успішно відправлена!')
        else:
            # Помилка при обробці форми
            messages.add_message(request, messages.ERROR, 'Виникли помилки при заповненні форми.')
        return redirect('form_page')

Це може бути корисно, якщо ви хочете логічно обробляти повідомлення за різними сценаріями, замість використання фіксованих функцій, таких як messages.success() або messages.error().

Кастомізація за допомогою extra_tags

Хочеш додати повідомленням унікальний стиль? Використовуй параметр extra_tags. Він додає додаткові CSS-класи до твого повідомлення.

Приклад: додавання кастомних тегів

from django.contrib import messages
from django.shortcuts import redirect

def login_user(request):
    if request.method == 'POST':
        # Найпростіша логіка авторизації
        username = request.POST.get('username')
        password = request.POST.get('password')
        if username == 'admin' and password == 'password123':
            messages.add_message(request, messages.SUCCESS, 'Ласкаво просимо, адміністратор!', extra_tags='admin-message')
            return redirect('dashboard')
        else:
            messages.add_message(request, messages.ERROR, 'Невірні облікові дані.', extra_tags='login-error')
            return redirect('login')

А в шаблоні:

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

Тепер повідомлення про успішний вхід отримає додаткові стилі через CSS-клас admin-message, а повідомлення про помилку — через CSS-клас login-error. Це можна використовувати для стилізації або навіть для JavaScript-анімацій.

Особливості fail_silently

Іноді повідомлення не додаються в результаті помилок (наприклад, якщо MessageMiddleware не підключений). Аргумент fail_silently=True ігнорує ці помилки. Однак його використання може призвести до "зникнення" повідомлень, якщо проєкт налаштований некоректно.

Рекомендація: намагайтесь використовувати fail_silently=False (за замовчуванням), щоб бути впевненими в тому, що все налаштовано правильно.

Практичне завдання

Частина 1. Реалізація сповіщень у формі зворотного зв'язку

Створіть сторінку зворотного зв'язку. Якщо форма відправлена коректно, показуйте користувачу сповіщення з рівнем SUCCESS. Якщо форма заповнена невірно, сповіщайте з рівнем ERROR. Переконайтеся, що сповіщення працюють з редиректом.

Підказка: форма повинна бути пов'язана з views.py так:

from django.contrib import messages
from django.shortcuts import redirect, render
from .forms import ContactForm

def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            # Збереження даних форми
            messages.add_message(request, messages.SUCCESS, 'Ваше повідомлення відправлено!')
            return redirect('contact')
        else:
            messages.add_message(request, messages.ERROR, 'Помилка! Перевірте правильність заповнення.')
    else:
        form = ContactForm()
    return render(request, 'contact.html', {'form': form})

Частина 2. Кастомні стилі для сповіщень

Додайте до сповіщень extra_tags для стилізації. Наприклад, успішне повідомлення нехай буде зеленим, а повідомлення про помилку — червоним.

Приклад CSS:

.success {
    color: green;
    font-weight: bold;
}

.error {
    color: red;
    font-weight: bold;
}

Шаблон:

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

Тепер ви знаєте, як керувати сповіщеннями у Django за допомогою messages.add_message(). Цей інструмент не лише зручний, але й надзвичайно важливий для створення дружнього інтерфейсу у будь-якому веб-додатку.