Crate rocket_dyn_templates

Dynamic templating engine support for Rocket.

This crate adds support for dynamic template rendering to Rocket. It automatically discovers templates, provides a Responder to render templates, and automatically reloads templates when compiled in debug mode. At present, it supports Handlebars and Tera.

Usage

1. Enable the rocket_dyn_templates feature corresponding to your templating engine(s) of choice:

   [dependencies.rocket_dyn_templates]
   version = "0.1.0-rc.1"
   features = ["handlebars", "tera"]
   

2. Write your template files in Handlebars (.hbs) and/or Tera (.tera) in the configurable template_dir directory (default: {rocket_root}/templates).

3. Attach Template::fairing() return a Template using Template::render(), supplying the name of the template file minus the last two extensions:

   use rocket_dyn_templates::Template;
   
   #[launch]
   fn rocket() -> _ {
       rocket::build().attach(Template::fairing())
   }
   
   #[get("/")]
   fn index() -> Template {
       Template::render("template-name", &context)
   }

Naming

Templates discovered by Rocket are renamed from their file name to their file name without the last two extensions. As such, refer to a template with file name foo.html.hbs or foo.html.tera as foo. See Discovery for more.

Templates that are not discovered by Rocket, such as those registered directly via Template::custom(), are not renamed. Use the name with which the template was originally registered.

Content Type

The Content-Type of the response is automatically determined by the non-engine extension of the template name or text/plain if there is no extension or the extension is unknown. For example, for a discovered template with file name foo.html.hbs or a manually registered template with name ending in foo.html, the Content-Type is automatically set to ContentType::HTML.

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:

Engine	Version	Extension
Tera	1	.tera
Handlebars	3	.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 contains examples of this mapping:

example template path	template 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 and Customization

Template discovery is actualized by the template fairing, which itself is created via Template::fairing(), Template::custom(), or Template::try_custom(), the latter two allowing customizations to templating engines such as registering template helpers and register templates from strings.

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 an ignite-time error.

Rendering

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.

Automatic Reloading

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.

Modules

handlebars	The handlebars templating engine library, reexported.
tera	The tera templating engine library, reexported.

Structs

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