.. _message-flashing-pattern:

Message Flashing¶

Good applications and user interfaces are all about feedback. If the user does not get enough feedback they will probably end up hating the application. Flask provides a really simple way to give feedback to a user with the flashing system. The flashing system basically makes it possible to record a message at the end of a request and access it next request and only next request. This is usually combined with a layout template that does this. Note that browsers and sometimes web servers enforce a limit on cookie sizes. This means that flashing messages that are too large for session cookies causes message flashing to fail silently.

Simple Flashing¶

So here is a full example::

from flask import Flask, flash, redirect, render_template, \
     request, url_for

app = Flask(__name__)
app.secret_key = b'_5#y2L"F4Q8z\n\xec]/'

@app.route('/')
def index():
    return render_template('index.html')

@app.route('/login', methods=['GET', 'POST'])
def login():
    error = None
    if request.method == 'POST':
        if request.form['username'] != 'admin' or \
                request.form['password'] != 'secret':
            error = 'Invalid credentials'
        else:
            flash('You were successfully logged in')
            return redirect(url_for('index'))
    return render_template('login.html', error=error)

And here is the :file:layout.html template which does the magic:

.. sourcecode:: html+jinja

<!doctype html> My Application {% with messages = get_flashed_messages() %} {% if messages %}

{{ message }}

{% endif %} {% endwith %} {% block body %}{% endblock %}

Here is the :file:index.html template which inherits from :file:layout.html:

.. sourcecode:: html+jinja

{% extends "layout.html" %} {% block body %}

Overview

Do you want to log in? {% endblock %}

And here is the :file:login.html template which also inherits from :file:layout.html:

.. sourcecode:: html+jinja

{% extends "layout.html" %} {% block body %}

Login

{% if error %}

Error: {{ error }} {% endif %}

{% endblock %}

Flashing With Categories¶

.. versionadded:: 0.3

It is also possible to provide categories when flashing a message. The default category if nothing is provided is 'message'. Alternative categories can be used to give the user better feedback. For example error messages could be displayed with a red background.

To flash a message with a different category, just use the second argument to the :func:~flask.flash function::

flash(u'Invalid password provided', 'error')

Inside the template you then have to tell the :func:~flask.get_flashed_messages function to also return the categories. The loop looks slightly different in that situation then:

.. sourcecode:: html+jinja

{% with messages = get_flashed_messages(with_categories=true) %} {% if messages %}

{{ message }}

{% endif %} {% endwith %}

This is just one example of how to render these flashed messages. One might also use the category to add a prefix such as <strong>Error:</strong> to the message.

Filtering Flash Messages¶

.. versionadded:: 0.9

Optionally you can pass a list of categories which filters the results of :func:~flask.get_flashed_messages. This is useful if you wish to render each category in a separate block.

.. sourcecode:: html+jinja

{% with errors = get_flashed_messages(category_filter=["error"]) %}
{% if errors %}
&lt;div class="alert-message block-message error"&gt;
  &lt;a class="close" href="#"&gt;×&lt;/a&gt;
  &lt;ul&gt;
    {%- for msg in errors %}
    &lt;li&gt;{{ msg }}&lt;/li&gt;
    {% endfor -%}
  &lt;/ul&gt;
&lt;/div&gt;
{% endif %}
{% endwith %}