path: root/book/src/template_expansion.md

# Template Expansion

This chapter will explain how the different parts of the templates are
translated into Rust code.

⚠️ Please note that the generated code might change in the future so the
following examples might not be up-to-date.

## Basic explanations

Whwn you add `#[derive(Template)]` and `#[template(...)]` on your type, the
`Template` derive proc-macro will then generate an implementation of the
`askama::Template` trait which will be a Rust version of the template.

It will also implement the `std::fmt::Display` trait on your type which will
internally call the `askama::Template` trait.

Let's take a small example:

```rust
#[derive(Template)]
#[template(source = "{% set x = 12 %}", ext = "html")]
struct Mine;
```

will generate:

```rust
impl ::askama::Template for YourType {
    fn render_into(
        &self,
        writer: &mut (impl ::std::fmt::Write + ?Sized),
    ) -> ::askama::Result<()> {
        let x = 12;
        ::askama::Result::Ok(())
    }
    const EXTENSION: ::std::option::Option<&'static ::std::primitive::str> = Some(
        "html",
    );
    const SIZE_HINT: ::std::primitive::usize = 0;
    const MIME_TYPE: &'static ::std::primitive::str = "text/html; charset=utf-8";
}

impl ::std::fmt::Display for YourType {
    #[inline]
    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
        ::askama::Template::render_into(self, f).map_err(|_| ::std::fmt::Error {})
    }
}
```

For simplicity, we will only keep the content of the `askama::Template::render_into`
function from now on.

## Text content

If you have "text content" (for example HTML) in your template:

```html
<h1>{{ title }}</h1>
```

It will generate it like this:

```rust
writer
    .write_fmt(
        format_args!(
            "<h1>{0}</h1>",
            &::askama::MarkupDisplay::new_unsafe(&(self.title), ::askama::Html),
        ),
    )?;
::askama::Result::Ok(())
```

About `MarkupDisplay`: we need to use this type in order to prevent generating
invalid HTML. Let's take an example: if `title` is `"<a>"` and we display it as
is, in the generated HTML, you won't see `<a>` but instead a new HTML element
will be created. To prevent this, we need to escape some characters.

In this example, `<a>` will become `&lt;a&gt;`. And this is why there is the
`safe` builtin filter, in case you want it to be displayed as is.

## Variables

### Variables creation

If you create a variable in your template, it will be created in the generated
Rust code as well. For example:

```jinja
{% set x = 12 %}
{% let y = x + 1 %}
```

will generate:

```rust
let x = 12;
let y = x + 1;
::askama::Result::Ok(())
```

### Variables usage

By default, variables will reference a field from the type on which the `askama::Template`
trait is implemented:

```jinja
{{ y }}
```

This template will expand as follows:

```rust
writer
    .write_fmt(
        format_args!(
            "{0}",
            &::askama::MarkupDisplay::new_unsafe(&(self.y), ::askama::Html),
        ),
    )?;
::askama::Result::Ok(())
```

This is why if the variable is undefined, it won't work with Askama and why
we can't check if a variable is defined or not.

You can still access constants and statics by using paths. Let's say you have in
your Rust code:

```rust
const FOO: u32 = 0;
```

Then you can use them in your template by referring to them with a path:

```jinja
{{ crate::FOO }}{{ super::FOO }}{{ self::FOO }}
```

It will generate:

```rust
writer
    .write_fmt(
        format_args!(
            "{0}{1}{2}",
            &::askama::MarkupDisplay::new_unsafe(&(crate::FOO), ::askama::Html),
            &::askama::MarkupDisplay::new_unsafe(&(super::FOO), ::askama::Html),
            &::askama::MarkupDisplay::new_unsafe(&(self::FOO), ::askama::Html),
        ),
    )?;
::askama::Result::Ok(())
```

(Note: `crate::` is to get an item at the root level of the crate, `super::` is
to get an item in the parent module and `self::` is to get an item in the
current module.)

You can also access items from the type that implements `Template` as well using
as `Self::`, it'll use the same logic.

## Control blocks

### if/else

The generated code can be more complex than expected, as seen with `if`/`else`
conditions:

```jinja
{% if x == "a" %}
gateau
{% else %}
tarte
{% endif %}
```

It will generate:

```rust
if *(&(self.x == "a") as &bool) {
    writer.write_str("gateau")?;
} else {
    writer.write_str("tarte")?;
}
::askama::Result::Ok(())
```

Very much as expected except for the `&(self.x == "a") as &bool`. Now about why
the `as &bool` is needed:

The following syntax `*(&(...) as &bool)` is used to  trigger Rust's automatic
dereferencing, to coerce e.g. `&&&&&bool` to `bool`. First `&(...) as &bool`
coerces e.g. `&&&bool` to `&bool`. Then `*(&bool)` finally dereferences it to
`bool`.

In short, it allows to fallback to a boolean as much as possible, but it also
explains why you can't do:

```jinja
{% set x = "a" %}
{% if x %}
    {{ x }}
{% endif %}
```

Because it fail to compile because:

```console
error[E0605]: non-primitive cast: `&&str` as `&bool`
```

### if let

```jinja
{% if let Some(x) = x %}
    {{ x }}
{% endif %}
```

will generate:

```rust
if let Some(x) = &(self.x) {
    writer
        .write_fmt(
            format_args!(
                "{0}",
                &::askama::MarkupDisplay::new_unsafe(&(x), ::askama::Html),
            ),
        )?;
}
```

### Loops

```html
{% for user in users %}
    {{ user }}
{% endfor %}
```

will generate:

```rust
{
    let _iter = (&self.users).into_iter();
    for (user, _loop_item) in ::askama::helpers::TemplateLoop::new(_iter) {
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(&(user), ::askama::Html),
                ),
            )?;
    }
}
::askama::Result::Ok(())
```

Now let's see what happens if you add an `else` condition:

```jinja
{% for user in x if x.len() > 2 %}
    {{ user }}
{% else %}
    {{ x }}
{% endfor %}
```

Which generates:

```rust
{
    let mut _did_loop = false;
    let _iter = (&self.users).into_iter();
    for (user, _loop_item) in ::askama::helpers::TemplateLoop::new(_iter) {
        _did_loop = true;
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(&(user), ::askama::Html),
                ),
            )?;
    }
    if !_did_loop {
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(
                        &(self.x),
                        ::askama::Html,
                    ),
                ),
            )?;
    }
}
::askama::Result::Ok(())
```

It creates a `_did_loop` variable which will check if we entered the loop. If
we didn't (because the iterator didn't return any value), it will enter the
`else` condition by checking `if !_did_loop {`.

We can extend it even further if we add an `if` condition on our loop:

```jinja
{% for user in users if users.len() > 2 %}
    {{ user }}
{% else %}
    {{ x }}
{% endfor %}
```

which generates:

```rust
{
    let mut _did_loop = false;
    let _iter = (&self.users).into_iter();
    let _iter = _iter.filter(|user| -> bool { self.users.len() > 2 });
    for (user, _loop_item) in ::askama::helpers::TemplateLoop::new(_iter) {
        _did_loop = true;
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(&(user), ::askama::Html),
                ),
            )?;
    }
    if !_did_loop {
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(
                        &(self.x),
                        ::askama::Html,
                    ),
                ),
            )?;
    }
}
::askama::Result::Ok(())
```

It generates an iterator but filters it based on the `if` condition (`users.len() > 2`).
So once again, if the iterator doesn't return any value, we enter the `else`
condition.

Of course, if you only have a `if` and no `else`, the generated code is much
shorter:

```jinja
{% for user in users if users.len() > 2 %}
    {{ user }}
{% endfor %}
```

Which generates:

```rust
{
    let _iter = (&self.users).into_iter();
    let _iter = _iter.filter(|user| -> bool { self.users.len() > 2 });
    for (user, _loop_item) in ::askama::helpers::TemplateLoop::new(_iter) {
        writer
            .write_fmt(
                format_args!(
                    "\n    {0}\n",
                    &::askama::MarkupDisplay::new_unsafe(&(user), ::askama::Html),
                ),
            )?;
    }
}
::askama::Result::Ok(())
```

## Filters

Example of using the `abs` built-in filter:

```jinja
{{ -2|abs }}
```

Which generates:

```rust
writer
    .write_fmt(
        format_args!(
            "{0}",
            &::askama::MarkupDisplay::new_unsafe(
                &(::askama::filters::abs(-2)?),
                ::askama::Html,
            ),
        ),
    )?;
::askama::Result::Ok(())
```

The filter is called with `-2` as first argument. You can add further arguments
to the call like this:

```jinja
{{ "a"|indent(4) }}
```

Which generates:

```rust
writer
    .write_fmt(
        format_args!(
            "{0}",
            &::askama::MarkupDisplay::new_unsafe(
                &(::askama::filters::indent("a", 4)?),
                ::askama::Html,
            ),
        ),
    )?;
::askama::Result::Ok(())
```

No surprise there, `4` is added after `"a"`. Now let's check when we chain the filters:

```jinja
{{ "a"|indent(4)|capitalize }}
```

Which generates:

```rust
writer
    .write_fmt(
        format_args!(
            "{0}",
            &::askama::MarkupDisplay::new_unsafe(
                &(::askama::filters::capitalize(
                    &(::askama::filters::indent("a", 4)?),
                )?),
                ::askama::Html,
            ),
        ),
    )?;
::askama::Result::Ok(())
```

As expected, `capitalize`'s first argument is the value returned by the `indent` call.

## Macros

This code:

```html
{% macro heading(arg) %}
<h1>{{arg}}</h1>
{% endmacro %}

{% call heading("title") %}
```

generates:

```rust
{
    let (arg) = (("title"));
    writer
        .write_fmt(
            format_args!(
                "\n<h1>{0}</h1>\n",
                &::askama::MarkupDisplay::new_unsafe(&(arg), ::askama::Html),
            ),
        )?;
}
::askama::Result::Ok(())
```

As you can see, the macro itself isn't present in the generated code, only its
internal code is generated as well as its arguments.