Debian Codegraph @

docs/usage/plugins/flash_messages.rst

raw
1 ==============
2 Flash Messages
3 ==============
4
5 .. versionadded:: 2.7.0
6
7 Flash messages are a powerful tool for conveying information to the user,
8 such as success notifications, warnings, or errors through one-time messages alongside a response due
9 to some kind of user action.
10
11 They are typically used to display a message on the next page load and are a great way
12 to enhance user experience by providing immediate feedback on their actions from things like form submissions.
13
14 Registering the plugin
15 ----------------------
16
17 The FlashPlugin can be easily integrated with different templating engines.
18 Below are examples of how to register the ``FlashPlugin`` with ``Jinja2``, ``Mako``, and ``MiniJinja`` templating engines.
19
20 .. tab-set::
21
22 .. tab-item:: Jinja2
23 :sync: jinja
24
25 .. literalinclude:: /examples/plugins/flash_messages/jinja.py
26 :language: python
27 :caption: Registering the flash message plugin using the Jinja2 templating engine
28
29 .. tab-item:: Mako
30 :sync: mako
31
32 .. literalinclude:: /examples/plugins/flash_messages/mako.py
33 :language: python
34 :caption: Registering the flash message plugin using the Mako templating engine
35
36 .. tab-item:: MiniJinja
37 :sync: minijinja
38
39 .. literalinclude:: /examples/plugins/flash_messages/minijinja.py
40 :language: python
41 :caption: Registering the flash message plugin using the MiniJinja templating engine
42
43 Using the plugin
44 ----------------
45
46 After registering the FlashPlugin with your application, you can start using it to add and display
47 flash messages within your application routes.
48
49 Here is an example showing how to use the FlashPlugin with the Jinja2 templating engine to display flash messages.
50 The same approach applies to Mako and MiniJinja engines as well.
51
52 .. literalinclude:: /examples/plugins/flash_messages/usage.py
53 :language: python
54 :caption: Using the flash message plugin with Jinja2 templating engine to display flash messages
55
56 Breakdown
57 +++++++++
58
59 #. Here we import the requires classes and functions from the Litestar package and related plugins.
60 #. Flash messages requires a valid session configuration, so we create and enable the ``ServerSideSession`` middleware.
61 #. We then create our ``TemplateConfig`` and ``FlashConfig`` instances, each setting up the configuration for
62 the template engine and flash messages, respectively.
63 #. A single route handler named ``index`` is defined using the ``@get()`` decorator.
64
65 * Within this handler, the ``flash`` function is called to add a new flash message.
66 This message is stored in the request's context, making it accessible to the template engine for rendering in the response.
67 * The function returns a ``Template`` instance, where ``template_str``
68 (read more about :ref:`template strings <usage/templating:template files vs. strings>`)
69 contains inline HTML and Jinja2 template code.
70 This template dynamically displays any flash messages by iterating over them with a Jinja2 for loop.
71 Each message is wrapped in a paragraph (``<p>``) tag, showing the message content and its category.
72
73 #. Finally, a ``Litestar`` application instance is created, specifying the ``flash_plugin`` and ``index`` route handler in its configuration.
74 The application is also configured with the ``template_config``, which includes the ``Jinja2`` templating engine and the path to the templates directory.