Skip to content

Commit

Permalink
Merge pull request #2 from litestar-org/flash-1
Browse files Browse the repository at this point in the history
docs: add more documentation
  • Loading branch information
euri10 authored Mar 4, 2024
2 parents 708baee + 0e6e5ff commit 9ff2737
Show file tree
Hide file tree
Showing 9 changed files with 117 additions and 26 deletions.
Empty file.
9 changes: 9 additions & 0 deletions docs/examples/plugins/flash_messages/jinja.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
from litestar import Litestar
from litestar.contrib.jinja import JinjaTemplateEngine
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(plugins=[flash_plugin])
9 changes: 9 additions & 0 deletions docs/examples/plugins/flash_messages/mako.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
from litestar import Litestar
from litestar.contrib.mako import MakoTemplateEngine
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=MakoTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(plugins=[flash_plugin])
9 changes: 9 additions & 0 deletions docs/examples/plugins/flash_messages/minijinja.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
from litestar import Litestar
from litestar.contrib.minijinja import MiniJinjaTemplateEngine
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=MiniJinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(plugins=[flash_plugin])
26 changes: 26 additions & 0 deletions docs/examples/plugins/flash_messages/usage.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
from litestar import Litestar, Request, get
from litestar.contrib.jinja import JinjaTemplateEngine
from litestar.plugins.flash import FlashConfig, FlashPlugin, flash
from litestar.response import Template
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))


@get()
async def index(request: Request) -> Template:
"""Example of adding and displaying a flash message."""
flash(request, "Oh no! I've been flashed!", category="error")

return Template(
template_str="""
<h1>Flash Message Example</h1>
{% for message in get_flashes() %}
<p>{{ message.message }} (Category:{{ message.category }})</p>
{% endfor %}
"""
)


app = Litestar(plugins=[flash_plugin], route_handlers=[index], template_config=template_config)
2 changes: 1 addition & 1 deletion docs/reference/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ API reference
openapi/index
pagination
params
plugins
plugins/index
repository/index
response/index
router
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/plugins/flash_messages.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
=====
flash
=====


.. automodule:: litestar.plugins.flash
:members:
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
=======
plugins
=======


.. automodule:: litestar.plugins
:members:

.. toctree::
:maxdepth: 1

flash_messages
74 changes: 50 additions & 24 deletions docs/usage/plugins/flash_messages.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,46 +2,72 @@
Flash Messages
==============

.. todo:: Document flash messages from https://github.com/litestar-org/litestar/pull/3145/
.. versionadded:: 2.7.0

Flash messages are a powerful tool for conveying information to the user,
such as success notifications, warnings, or errors through one-time messages alongside a response due
to some kind of user action.

They are typically used to display a message on the next page load and are a great way
to enhance user experience by providing immediate feedback on their actions from things like form submissions.

Registering the plugin
----------------------

.. todo:: Document registering the plugin from

Adding Messages
---------------
The FlashPlugin can be easily integrated with different templating engines.
Below are examples of how to register the ``FlashPlugin`` with ``Jinja2``, ``Mako``, and ``MiniJinja`` templating engines.

.. todo:: Document adding messages to request scope
.. tab-set::

Retrieving Messages
-------------------
.. tab-item:: Jinja2
:sync: jinja

.. todo:: Document retrieving messages from request scope
.. literalinclude:: /examples/plugins/flash_messages/jinja.py
:language: python
:caption: Registering the flash message plugin using the Jinja2 templating engine

Using Messages in Templates
---------------------------
.. tab-item:: Mako
:sync: mako

.. tab-set::
.. literalinclude:: /examples/plugins/flash_messages/mako.py
:language: python
:caption: Registering the flash message plugin using the Mako templating engine

.. tab-item:: Jinja2
.. tab-item:: MiniJinja
:sync: minijinja

.. code-block:: html
:caption: Displaying flash messages in a Jinja2 template
.. literalinclude:: /examples/plugins/flash_messages/minijinja.py
:language: python
:caption: Registering the flash message plugin using the MiniJinja templating engine

.. todo:: Add Jinja2 example
Using the plugin
----------------

.. tab-item:: Mako
After registering the FlashPlugin with your application, you can start using it to add and display
flash messages within your application routes.

.. code-block:: html
:caption: Displaying flash messages in a Mako template
Here is an example showing how to use the FlashPlugin with the Jinja2 templating engine to display flash messages.
The same approach applies to Mako and MiniJinja engines as well.

.. literalinclude:: /examples/plugins/flash_messages/usage.py
:language: python
:caption: Using the flash message plugin with Jinja2 templating engine to display flash messages

.. todo:: Add Mako example
Breakdown
+++++++++

.. tab-item:: Mini-Jinja
#. Here we import the requires classes and functions from the Litestar package and related plugins.
#. We then create our ``TemplateConfig`` and ``FlashConfig`` instances, each setting up the configuration for
the template engine and flash messages, respectively.
#. A single route handler named ``index`` is defined using the ``@get()`` decorator.

.. code-block:: html
:caption: Displaying flash messages in a Mini-Jinja template
* Within this handler, the ``flash`` function is called to add a new flash message.
This message is stored in the request's context, making it accessible to the template engine for rendering in the response.
* The function returns a ``Template`` instance, where ``template_str``
(read more about :ref:`template strings <usage/templating:template files vs. strings>`)
contains inline HTML and Jinja2 template code.
This template dynamically displays any flash messages by iterating over them with a Jinja2 for loop.
Each message is wrapped in a paragraph (``<p>``) tag, showing the message content and its category.

.. todo:: Add Mini-Jinja example
#. Finally, a ``Litestar`` application instance is created, specifying the ``flash_plugin`` and ``index`` route handler in its configuration.
The application is also configured with the ``template_config``, which includes the ``Jinja2`` templating engine and the path to the templates directory.

0 comments on commit 9ff2737

Please sign in to comment.