TemplateConfig¶
TemplateConfig is a simple set of configurations that when passed enables the template engine.
Info
Currently Esmerald supports Jinja2
or mako
(deprecated). Mako will be removed in the release 3.6.0 of Esmerald.
It is important to understand that you don't need to use the provided JinjaTemplateEngine
or MakoTemplateEngine
from Esmerald within the TemplateConfig
.
You are free to build your own and pass it to the TemplateConfig
. This way you can design however you see fit.
Tip
Esmerald being built on top of Lilya, uses the JinjaTemplateEngine
from it which means you can read
the Jinja2Template from Lilya to understand
the parameters and how to use them.
You can also create your own jinja2 engine and pass it in the engine
parameter of the TemplateConfig
.
You will notice the name of the parameters in the TemplateConfig
match maority of the jinja2 implementation.
Warning
The mako
engine integration, due to its own limitations, will be not supported by Esmerald from version 3.6.0.
TemplateConfig and application¶
To use the TemplateConfig in an application instance.
from pathlib import Path
from esmerald import Esmerald
from esmerald.config.template import TemplateConfig
from esmerald.template.jinja import JinjaTemplateEngine
template_config = TemplateConfig(
directory=Path("templates"),
engine=JinjaTemplateEngine,
)
app = Esmerald(template_config=template_config)
Another example
from pathlib import Path
from esmerald import Esmerald
from esmerald.config.template import TemplateConfig
from esmerald.template.mako import MakoTemplateEngine
template_config = TemplateConfig(
directory=Path("templates"),
engine=MakoTemplateEngine,
)
app = Esmerald(template_config=template_config)
Parameters¶
All the parameters and defaults are available in the TemplateConfig Reference.
TemplateConfig and application settings¶
The TemplateConfig can be done directly via application instantiation but also via settings.
from pathlib import Path
from esmerald import EsmeraldAPISettings
from esmerald.config.template import TemplateConfig
from esmerald.template.jinja import JinjaTemplateEngine
class CustomSettings(EsmeraldAPISettings):
@property
def template_config(self) -> TemplateConfig:
"""
Initial Default configuration for the StaticFilesConfig.
This can be overwritten in another setting or simply override
`template_config` or then override the `def template_config()`
property to change the behavior of the whole template_config.
Esmerald can also support other engines like mako, Diazo,
Cheetah. Currently natively only supports jinja2 and mako as they
are standards in the market.
"""
return TemplateConfig(
directory=Path("templates"),
engine=JinjaTemplateEngine,
)
This will make sure you keep the settings clean, separated and without a bloated Esmerald instance.
url_for
¶
Esmerald automatically provides the url_for
when using the jinja template system, that means
you can do something like this:
<link href="{{ url_for('static', path='/css/app.min.css') }}" rel="stylesheet" />
How to use¶
Simply return Template
(of esmerald) not TemplateResponse
with a name
parameter pointing to the relative path of the template.
You can pass extra data via setting the context
parameter to a dictionary containing the extra data.
To select the return type (txt, html) you need to name the files: foo.html.jinja
.
Using async templates¶
A very good feature of jinja2 is that you can you can have async templates. This means awaitables are automatically resolved and async iteration is supported out of the box. This is especially useful for the async ORMs, for example Edgy.
from pathlib import Path
from esmerald import EsmeraldAPISettings
from esmerald.config.template import TemplateConfig
from esmerald.template.jinja import JinjaTemplateEngine
class CustomSettings(EsmeraldAPISettings):
@property
def template_config(self) -> TemplateConfig:
return TemplateConfig(
directory=Path("templates"),
env_options={"enable_async": True},
)
And now you can iterate over QuerySets out of the box. Nothing else is required.
Note that internally the template response switches the render method and uses the async content feature of lilya
so you can only access the body attribute after calling __call__
or resolve_async_content()
.