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:

1. from flask import Flask, flash, redirect, render_template, \
2. request, url_for

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

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

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

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

1. <!doctype html>
2. <title>My Application</title>
3. {% with messages = get_flashed_messages() %}
4. {% if messages %}
5. <ul class=flashes>
6. {% for message in messages %}
7. <li>{{ message }}</li>
8. {% endfor %}
9. </ul>
10. {% endif %}
11. {% endwith %}
12. {% block body %}{% endblock %}

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

1. {% extends "layout.html" %}
2. {% block body %}
3. <h1>Overview</h1>
4. <p>Do you want to <a href="{{ url_for('login') }}">log in?</a>
5. {% endblock %}

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

1. {% extends "layout.html" %}
2. {% block body %}
3. <h1>Login</h1>
4. {% if error %}
5. <p class=error><strong>Error:</strong> {{ error }}
6. {% endif %}
7. <form method=post>
8. <dl>
9. <dt>Username:
10. <dd><input type=text name=username value="{{
11. request.form.username }}">
12. <dt>Password:
13. <dd><input type=password name=password>
14. </dl>
15. <p><input type=submit value=Login>
16. </form>
17. {% endblock %}

Flashing With Categories

Changelog

New in version 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 flash() function:

1. flash('Invalid password provided', 'error')

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

1. {% with messages = get_flashed_messages(with_categories=true) %}
2. {% if messages %}
3. <ul class=flashes>
4. {% for category, message in messages %}
5. <li class="{{ category }}">{{ message }}</li>
6. {% endfor %}
7. </ul>
8. {% endif %}
9. {% 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

Changelog

New in version 0.9.

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

1. {% with errors = get_flashed_messages(category_filter=["error"]) %}
2. {% if errors %}
3. <div class="alert-message block-message error">
4. <a class="close" href="#">×</a>
5. <ul>
6. {%- for msg in errors %}
7. <li>{{ msg }}</li>
8. {% endfor -%}
9. </ul>
10. </div>
11. {% endif %}
12. {% endwith %}