Struct rocket_contrib::Template

pub struct Template { /* fields omitted */ }

The Template type implements generic support for template rendering in Rocket.

Templating in Rocket works by first discovering all of the templates inside the template directory. The template directory is configurable via the template_dir configuration parameter and defaults to templates/. The path set in template_dir should be relative to the Rocket configuration file. See the configuration chapter of the guide for more information on configuration.

Templates are discovered according to their extension. At present, this library supports the following templates and extensions:

• Tera: .tera
• Handlebars: .hbs

Any file that ends with one of these extension will be discovered and rendered with the corresponding templating engine. The name of the template will be the path to the template file relative to template_dir minus at most two extensions. The following are examples of template names (on the right) given that the template is at the path on the left.

• {template_dir}/index.html.hbs => index
• {template_dir}/index.tera => index
• {template_dir}/index.hbs => index
• {template_dir}/dir/index.hbs => dir/index
• {template_dir}/dir/index.html.tera => dir/index
• {template_dir}/index.template.html.hbs => index.template
• {template_dir}/subdir/index.template.html.hbs => subdir/index.template

The recommended naming scheme is to use two extensions: one for the file type, and one for the template extension. This means that template extensions should look like: .html.hbs, .html.tera, .xml.hbs, etc.

Template discovery is actualized by the template fairing, which itself is created via the Template::fairing() method. In order for any templates to be rendered, the template fairing must be attached to the running Rocket instance.

Templates are rendered with the render method. The method takes in the name of a template and a context to render the template with. The context can be any type that implements Serialize from Serde and would serialize to an Object value.

Usage

To use, add the handlebars_templates feature, the tera_templates feature, or both, to the rocket_contrib dependencies section of your Cargo.toml:

[dependencies.rocket_contrib]
version = "*"
default-features = false
features = ["handlebars_templates", "tera_templates"]

Then, ensure that the template fairing is attached to your Rocket application:

extern crate rocket;
extern crate rocket_contrib;

use rocket_contrib::Template;

fn main() {
    rocket::ignite()
        // ...
        .attach(Template::fairing())
        // ...
}

The Template type implements Rocket's Responder trait, so it can be returned from a request handler directly:

#[get("/")]
fn index() -> Template {
    let context = ...;
    Template::render("index", &context)
}

Methods

impl Template

fn fairing() -> impl Fairing

Returns a fairing that intializes and maintains templating state.

This fairing must be attached to any Rocket instance that wishes to render templates. Failure to attach this fairing will result in a "Uninitialized template context: missing fairing." error message when a template is attempted to be rendered.

Example

To attach this fairing, simple call attach on the application's Rocket instance with Template::fairing():

extern crate rocket;
extern crate rocket_contrib;

use rocket_contrib::Template;

fn main() {
    rocket::ignite()
        // ...
        .attach(Template::fairing())
        // ...
}

fn render<S, C>(name: S, context: C) -> Template where
    S: Into<Cow<'static, str>>,
    C: Serialize, 

Render the template named name with the context context. The context can be of any type that implements Serialize. This is typically a HashMap or a custom struct.

Example

use std::collections::HashMap;
use rocket_contrib::Template;

// Create a `context`. Here, just an empty `HashMap`.
let mut context = HashMap::new();

let template = Template::render("index", context);

fn show<P, S, C>(root: P, name: S, context: C) -> Option<String> where
    P: AsRef<Path>,
    S: Into<Cow<'static, str>>,
    C: Serialize, 

Render the template named name located at the path root with the context context into a String. This method is very slow and should not be used in any running Rocket application. This method should only be used during testing to validate Template responses. For other uses, use render instead.

The context can be of any type that implements Serialize. This is typically a HashMap or a custom struct. The path root can be relative, in which case it is relative to the current working directory, or absolute.

Returns Some if the template could be rendered. Otherwise, returns None. If rendering fails, error output is printed to the console.

Example

use std::collections::HashMap;
use rocket_contrib::Template;

// Create a `context`. Here, just an empty `HashMap`.
let mut context = HashMap::new();

let template = Template::show("templates/", "index", context);

Trait Implementations

impl Debug for Template

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Responder<'static> for Template

Returns a response with the Content-Type derived from the template's extension and a fixed-size body containing the rendered template. If rendering fails, an Err of Status::InternalServerError is returned.

fn respond_to(self, req: &Request) -> Result<'static>

Returns Ok if a Response could be generated successfully. Otherwise, returns an Err with a failing Status.