Rendering templates
===================
MicroPie can render HTML templates using the Jinja2 template engine.
Templates allow you to separate presentation from code by placing
HTML in separate files. Template rendering is optional; you can use
MicroPie without Jinja2 installed, but the
:meth:`~micropie.App._render_template` helper will return a
``500 Internal Server Error: Jinja2 not installed.`` message unless
Jinja2 is installed.
Installing Jinja2
-----------------
If you installed MicroPie with the ``[standard]`` extra, Jinja2 is
already available. Otherwise install it with pip:
.. code-block:: console
$ pip install jinja2
Creating templates
------------------
MicroPie looks for templates in a directory called ``templates`` in
your current working directory. Use normal Jinja2 syntax in your
templates. Here is a simple ``templates/index.html`` file:
.. code-block:: html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{{ title }}</title>
</head>
<body>
<h1>{{ message }}</h1>
</body>
</html>
Rendering a template
--------------------
To render a template, call :meth:`~micropie.App._render_template` from
within an asynchronous handler. The method returns a string containing
the rendered HTML. Because template loading and rendering may block,
MicroPie runs it in a background thread using ``asyncio.to_thread``.
.. code-block:: python
from micropie import App
class MyApp(App):
async def index(self):
return await self._render_template(
"index.html",
title="Welcome",
message="Hello from MicroPie!",
)
app = MyApp()
When you visit ``/`` in your browser, MicroPie returns the rendered
HTML with a ``Content‑Type`` of ``text/html; charset=utf‑8``.
Template variables
------------------
You can pass arbitrary keyword arguments to `_render_template`. These
become variables in the Jinja2 template. For more information on
creating complex templates, including inheritance and control flow,
refer to the `Jinja2 documentation <https://jinja.palletsprojects.com>`_.
