Flashing -> patterns documentation

15 years ago · a9d4ea81da
2 changed files with 86 additions and 68 deletions
--- a/docs/patterns.rst
+++ b/docs/patterns.rst
@ -164,3 +164,85 @@ this template "extends" another template.  When the template system evaluates
 this template, first it locates the parent.  The extends tag must be the
 first tag in the template.  To render the contents of a block defined in
 the parent template, use ``{{ super() }}``.
+
+.. _message-flashing-pattern:
+
+Message Flashing
+----------------
+
+Good applications and user interfaces are all about feedback.  If the user
+does not get enough feedback he 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.
+
+So here a full example::
+
+    from flask import flash, redirect, url_for, render_template
+
+    @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 sucessfully logged in')
+                return redirect(url_for('index'))
+        return render_template('login.html', error=error)
+
+And here the ``layout.html`` template which does the magic:
+
+.. sourcecode:: html+jinja
+
+   <!doctype html>
+   <title>My Application</title>
+   {% with messages = get_flashed_messages() %}
+     {% if messages %}
+       <ul class=flashes>
+       {% for message in messages %}
+         <li>{{ message }}</li>
+       {% endfor %}
+       </ul>
+     {% endif %}
+   {% endwith %}
+   {% block body %}{% endblock %}
+
+And here the index.html template:
+
+.. sourcecode:: html+jinja
+
+   {% extends "layout.html" %}
+   {% block body %}
+     <h1>Overview</h1>
+     <p>Do you want to <a href="{{ url_for('login') }}">log in?</a>
+   {% endblock %}
+
+And of course the login template:
+
+.. sourcecode:: html+jinja
+
+   {% extends "layout.html" %}
+   {% block body %}
+     <h1>Login</h1>
+     {% if error %}
+       <p class=error><strong>Error:</strong> {{ error }}
+     {% endif %}
+     <form action="" method=post>
+       <dl>
+         <dt>Username:
+         <dd><input type=text name=username value="{{
+             request.form.username }}">
+         <dt>Password:
+         <dd><input type=password name=password>
+       </dl>
+       <p><input type=submit value=Login>
+     </form>
+   {% endblock %}
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@ -489,71 +489,7 @@ 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.

-So here a full example::
-
-    from flask import flash, redirect, url_for, render_template
-
-    @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 sucessfully logged in')
-                return redirect(url_for('index'))
-        return render_template('login.html', error=error)
-
-And here the ``layout.html`` template which does the magic:
-
-.. sourcecode:: html+jinja
-
-   <!doctype html>
-   <title>My Application</title>
-   {% with messages = get_flashed_messages() %}
-     {% if messages %}
-       <ul class=flashes>
-       {% for message in messages %}
-         <li>{{ message }}</li>
-       {% endfor %}
-       </ul>
-     {% endif %}
-   {% endwith %}
-   {% block body %}{% endblock %}
-
-And here the index.html template:
-
-.. sourcecode:: html+jinja
-
-   {% extends "layout.html" %}
-   {% block body %}
-     <h1>Overview</h1>
-     <p>Do you want to <a href="{{ url_for('login') }}">log in?</a>
-   {% endblock %}
-
-And of course the login template:
-
-.. sourcecode:: html+jinja
-
-   {% extends "layout.html" %}
-   {% block body %}
-     <h1>Login</h1>
-     {% if error %}
-       <p class=error><strong>Error:</strong> {{ error }}
-     {% endif %}
-     <form action="" method=post>
-       <dl>
-         <dt>Username:
-         <dd><input type=text name=username value="{{
-             request.form.username }}">
-         <dt>Password:
-         <dd><input type=password name=password>
-       </dl>
-       <p><input type=submit value=Login>
-     </form>
-   {% endblock %}
+To flash a message use the :func:`~flask.flash` method, to get hold of the
+messages you can use :func:`~flask.get_flashed_messages` which is also
+available in the templates.  Check out the :ref:`message-flashing-pattern`
+for a full example.