Templates#

Starlite has built-in support for both the Jinja2 and Mako template engines, as well as abstractions to make use of any template engine you wish.

Template engines#

To stay lightweight, a Starlite installation does not include the Jinja or Mako libraries themselves. Before you can start using them, you have to install it via the respective extra:

  • pip install starlite[jinja] for Jinja2

  • pip install starlite[mako] for Mako

Tip

Jinja is included in the standard extra. If you installed Starlite using starlite[standard], you do not need to explicitly add the jinja extra.

Registering a template engine#

To register one of the built-in template engines you simply need to pass it to the Starlite constructor:

from pathlib import Path

from starlite import Starlite, TemplateConfig
from starlite.contrib.jinja import JinjaTemplateEngine

app = Starlite(
    route_handlers=[],
    template_config=TemplateConfig(
        directory=Path("templates"),
        engine=JinjaTemplateEngine,
    ),
)

from pathlib import Path

from starlite import Starlite, TemplateConfig
from starlite.contrib.mako import MakoTemplateEngine

app = Starlite(
    route_handlers=[],
    template_config=TemplateConfig(
        directory=Path("templates"),
        engine=MakoTemplateEngine,
    ),
)

Note

The directory parameter passed to TemplateConfig can be either a directory or list of directories to use for loading templates.

Defining a custom template engine#

If you wish to use another templating engine, you can easily do so by implementing TemplateEngineProtocol. This class accepts a generic argument which should be the template class, and it specifies two methods:

from typing import Protocol, Union, List
from pydantic import DirectoryPath

# the template class of the respective library
from some_lib import SomeTemplate


class TemplateEngineProtocol(Protocol[SomeTemplate]):
    def __init__(self, directory: Union[DirectoryPath, List[DirectoryPath]]) -> None:
        """Builds a template engine."""
        ...

    def get_template(self, template_name: str) -> SomeTemplate:
        """Loads the template with template_name and returns it."""
        ...

from typing import Protocol, Union
from pydantic import DirectoryPath

# the template class of the respective library
from some_lib import SomeTemplate


class TemplateEngineProtocol(Protocol[SomeTemplate]):
    def __init__(self, directory: Union[DirectoryPath, list[DirectoryPath]]) -> None:
        """Builds a template engine."""
        ...

    def get_template(self, template_name: str) -> SomeTemplate:
        """Loads the template with template_name and returns it."""
        ...

from typing import Protocol
from pydantic import DirectoryPath

# the template class of the respective library
from some_lib import SomeTemplate


class TemplateEngineProtocol(Protocol[SomeTemplate]):
    def __init__(self, directory: DirectoryPath | list[DirectoryPath]) -> None:
        """Builds a template engine."""
        ...

    def get_template(self, template_name: str) -> SomeTemplate:
        """Loads the template with template_name and returns it."""
        ...

Once you have your custom engine you can register it as you would the built-in engines.

Accessing the template engine instance#

If you need to access the template engine instance, you can do so via the TemplateConfig.engine attribute:

from starlite import TemplateConfig
from starlite.contrib.jinja import JinjaTemplateEngine

template_config = TemplateConfig(engine=JinjaTemplateEngine)
template_config.engine_instance.engine.globals["foo"] = "bar"

from starlite import TemplateConfig
from starlite.contrib.mako import MakoTemplateEngine

template_config = TemplateConfig(engine=MakoTemplateEngine)
template_config.engine_instance.engine.has_template("foo")

Template responses#

Once you have a template engine registered you can return Templates from your route handlers:

from pathlib import Path

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.jinja import JinjaTemplateEngine


@get(path="/")
def index(name: str) -> Template:
    return Template(name="hello.html.jinja2", context={"name": name})


app = Starlite(
    route_handlers=[index],
    template_config=TemplateConfig(
        directory=Path("templates"),
        engine=JinjaTemplateEngine,
    ),
)

from pathlib import Path

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.mako import MakoTemplateEngine


@get(path="/")
def index(name: str) -> Template:
    return Template(name="hello.html.mako", context={"name": name})


app = Starlite(
    route_handlers=[index],
    template_config=TemplateConfig(
        directory=Path("templates"),
        engine=MakoTemplateEngine,
    ),
)

  • name is the name of the template file within on of the specified directories. If no file with that name is found, a TemplateNotFoundException exception will be raised.

  • context is a dictionary containing arbitrary data that will be passed to the template engine’s render method. For Jinja and Mako, this data will be available in the template context

Template context#

Both Jinja2 and Mako support passing a context object to the template as well as defining callables that will be available inside the template.

Accessing the request instance#

The current Request is available within the template context under request, which also provides access to the app instance.

Accessing app.state.key for example would look like this: <strong>check_context_key: </strong>{{ check_context_key() }}

<html>
    <body>
        <div>
            <span>My state value: {{request.app.state.some_key}}</span>
        </div>
    </body>
</html>

html
<html>
    <body>
        <div>
            <span>My state value: ${request.app.state.some_key}</span>
        </div>
    </body>
</html>

Adding CSRF inputs#

If you want to add a hidden <input> tag containing a CSRF token, you first need to configure CSRF protection. With that in place, you can now insert the CSRF input field inside an HTML form:

<html>
    <body>
        <div>
            <form action="https://myserverurl.com/some-endpoint" method="post">
                {{ csrf_input }}
                <label for="fname">First name:</label><br>
                <input type="text" id="fname" name="fname">
                <label for="lname">Last name:</label><br>
                <input type="text" id="lname" name="lname">
            </form>
        </div>
    </body>
</html>

<html>
    <body>
        <div>
            <form action="https://myserverurl.com/some-endpoint" method="post">
                ${csrf_input}
                <label for="fname">First name:</label><br>
                <input type="text" id="fname" name="fname">
                <label for="lname">Last name:</label><br>
                <input type="text" id="lname" name="lname">
            </form>
        </div>
    </body>
</html>

The input holds a CSRF token as its value and is hidden so users cannot see or interact with it. The token is sent back to the server when the form is submitted, and is checked by the CSRF middleware.

Passing template context#

Passing context to the template is very simple - its one of the kwargs expected by the Template container, so simply pass a string keyed dictionary of values:

from starlite import Template, get


@get(path="/info")
def info() -> Template:
    return Template(name="info.html", context={"numbers": "1234567890"})

Template callables#

Both Jinja2 and Mako allow users to define custom callables that are ran inside the template. Starlite builds on this and offers some functions out of the box.

Built-in callables#

url_for

To access urls for route handlers you can use the url_for function. Its signature and behaviour matches route_reverse behaviour. More details about route handler indexing can be found here.

csrf_token

This function returns the request’s unique CSRF token You can use this if you wish to insert the csrf_token into non-HTML based templates, or insert it into HTML templates not using a hidden input field but by some other means, for example inside a special <meta> tag.

url_for_static_asset

URLs for static files can be created using the url_for_static_asset function. It’s signature and behaviour are identical to app.url_for_static_asset.

Registering template callables#

The TemplateEngineProtocol specifies the method register_template_callable that allows defining a custom callable on a template engine. This method is implemented for the two built in engines, and it can be used to register callables that will be injected into the template. The callable should expect one argument - the context dictionary. It can be any callable - a function, method or class that defines the call method. For example:

template_functions.py#
from pathlib import Path
from typing import Dict

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.jinja import JinjaTemplateEngine


def my_template_function(ctx: Dict) -> str:
    return ctx.get("my_context_key", "nope")


def register_template_callables(engine: JinjaTemplateEngine) -> None:
    engine.register_template_callable(
        key="check_context_key",
        template_callable=my_template_function,
    )


template_config = TemplateConfig(
    directory=Path("templates"),
    engine=JinjaTemplateEngine,
    engine_callback=register_template_callables,
)


@get("/")
def index() -> Template:
    return Template(name="index.html.jinja2")


app = Starlite(
    route_handlers=[index],
    template_config=template_config,
)
template_functions.py#
from pathlib import Path

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.jinja import JinjaTemplateEngine


def my_template_function(ctx: dict) -> str:
    return ctx.get("my_context_key", "nope")


def register_template_callables(engine: JinjaTemplateEngine) -> None:
    engine.register_template_callable(
        key="check_context_key",
        template_callable=my_template_function,
    )


template_config = TemplateConfig(
    directory=Path("templates"),
    engine=JinjaTemplateEngine,
    engine_callback=register_template_callables,
)


@get("/")
def index() -> Template:
    return Template(name="index.html.jinja2")


app = Starlite(
    route_handlers=[index],
    template_config=template_config,
)
templates/index.html.jinja2#
<strong>check_context_key: </strong>{{ check_context_key() }}
template_functions.py#
from pathlib import Path
from typing import Dict

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.mako import MakoTemplateEngine


def my_template_function(ctx: Dict) -> str:
    return ctx.get("my_context_key", "nope")


def register_template_callables(engine: MakoTemplateEngine) -> None:
    engine.register_template_callable(
        key="check_context_key",
        template_callable=my_template_function,
    )


template_config = TemplateConfig(
    directory=Path("templates"),
    engine=MakoTemplateEngine,
    engine_callback=register_template_callables,
)


@get("/")
def index() -> Template:
    return Template(name="index.html.mako")


app = Starlite(
    route_handlers=[index],
    template_config=template_config,
)
template_functions.py#
from pathlib import Path

from starlite import Starlite, Template, TemplateConfig, get
from starlite.contrib.mako import MakoTemplateEngine


def my_template_function(ctx: dict) -> str:
    return ctx.get("my_context_key", "nope")


def register_template_callables(engine: MakoTemplateEngine) -> None:
    engine.register_template_callable(
        key="check_context_key",
        template_callable=my_template_function,
    )


template_config = TemplateConfig(
    directory=Path("templates"),
    engine=MakoTemplateEngine,
    engine_callback=register_template_callables,
)


@get("/")
def index() -> Template:
    return Template(name="index.html.mako")


app = Starlite(
    route_handlers=[index],
    template_config=template_config,
)
templates/index.html.mako#
<strong>check_context_key: </strong>${ check_context_key() }

Run the example with uvicorn template_functions:app , visit http://127.0.0.1:8000, and you’ll see

Template engine callable example