Module rocket_contrib::templates

Dynamic template engine support for handlebars and tera.

Overview

The general outline for using templates in Rocket is:

0. Enable the rocket_contrib feature corresponding to your templating engine(s) of choice:

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

1. Write your template files in Handlebars (extension: .hbs) or tera (extensions: .tera) in the templates directory (default: {rocket_root}/templates).

2. Attach the template fairing, Template::fairing():

   use rocket_contrib::templates::Template;
   
   fn main() {
       rocket::ignite()
           .attach(Template::fairing())
           // ...
   }

3. Return a Template using Template::render(), supplying the name of the template file minus the last two extensions, from a handler.

   use rocket_contrib::templates::Template;
   
   #[get("/")]
   fn index() -> Template {
       let context = context();
       Template::render("template-name", &context)
   }

Discovery

Template names passed in to Template::render() must correspond to a previously discovered template in the configured template directory. The template directory is configured via the template_dir configuration parameter and defaults to templates/. The path set in template_dir is relative to the Rocket configuration file. See the configuration chapter of the guide for more information on configuration.

The corresponding templating engine used for a given template is based on a template's extension. At present, this library supports the following engines 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 table illustrates this mapping:

path	name
{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 Fairing

Template discovery is actualized by the template fairing, which itself is created via Template::fairing() or Template::custom(), the latter of which allows for customizations to the templating engine. In order for any templates to be rendered, the template fairing must be attached to the running Rocket instance. Failure to do so will result in a run-time error.

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.

In debug mode (without the --release flag passed to cargo), templates will be automatically reloaded from disk if any changes have been made to the templates directory since the previous request. In release builds, template reloading is disabled to improve performance and cannot be enabled.

Re-exports

pub extern crate tera;

pub extern crate handlebars;

Structs

Engines	A structure exposing access to templating engines.
Metadata	Request guard for dynamiclly querying template metadata.
Template	Responder that renders a dynamic template.