The Template Macro

In previous instructions the rust code made use of the template derive macro. Invoking this macro is how our template code gets compiled into our rust code. This macro performs a few different things depending on what options are provided, however the core function is converting template code into a Template trait implementation.

In the instructions the path argument was used to load a template from a file. This is the most common way of defining templates. Arguments are provided using the same macro syntax and the stilts prefix followed by the args to provide.

#[derive(Template)]            // Use the derive macro
#[stilts(path = "index.html")] // Provides arguments to the derive macro
struct Example;                // The item which the trait is implemented on

Macro Arguments

The template derive macro has multiple arguments which can be used to tweak how the macro generates the template code. Some arguments are used to override behavior described in the configuration section.

Either path or content must be specified

  • path: The path relative to the template root of the template to render
  • content: The direct contents of the template provided by a string literal
  • escape: Override the escaper detected by file extension with a specified one
  • trim: Override the trim behavior defined in your config
  • block: Only render the contents of a specific block within the template specified by path or content

Examples:

Standard use case

#[derive(Template)]
#[stilts(path = "index.html")]
struct MyTemplate {
    my_data: String,
}

Using content instead of path

use stilts::Template;
#[derive(Template)]
#[stilts(content = "My {% data %} Template")]
struct MyInlineTemplate {
    data: String,
}

An example of setting the trim and escape to something else. This forces Stilts to not trim whitespace around expressions, and to use the Empty escaper which does no escaping at all.

use stilts::Template;
#[derive(Template)]
#[stilts(
    content = "Templates are fun",
    trim = false,
    escape = ::stilts::escaping::Empty
)]
struct MyOverridenTemplate {
    my_data: String,
}

Only rendering a single block

#[derive(Template)]
#[stilts(path = "index.html", block = "popup")]
struct MyTemplate {
    my_data: String,
}