{{ message.message }} (Category:{{ message.category }})
+ {% endfor %} + """ + ) + + +app = Litestar(plugins=[flash_plugin], route_handlers=[index], template_config=template_config) diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 6fcd7bc88e..1929bf6b5d 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -28,7 +28,7 @@ API reference openapi/index pagination params - plugins + plugins/index repository/index response/index router diff --git a/docs/reference/plugins/flash_messages.rst b/docs/reference/plugins/flash_messages.rst new file mode 100644 index 0000000000..34d1b411d5 --- /dev/null +++ b/docs/reference/plugins/flash_messages.rst @@ -0,0 +1,7 @@ +===== +flash +===== + + +.. automodule:: litestar.plugins.flash + :members: diff --git a/docs/reference/plugins.rst b/docs/reference/plugins/index.rst similarity index 52% rename from docs/reference/plugins.rst rename to docs/reference/plugins/index.rst index 626910d988..4a2462b506 100644 --- a/docs/reference/plugins.rst +++ b/docs/reference/plugins/index.rst @@ -1,6 +1,11 @@ +======= plugins ======= - .. automodule:: litestar.plugins :members: + +.. toctree:: + :maxdepth: 1 + + flash_messages diff --git a/docs/usage/plugins/flash_messages.rst b/docs/usage/plugins/flash_messages.rst index 720a838e5b..8ff46b8db6 100644 --- a/docs/usage/plugins/flash_messages.rst +++ b/docs/usage/plugins/flash_messages.rst @@ -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``) 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.