Struct rocket_contrib::Template
[−]
[src]
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
[src]
fn fairing() -> impl Fairing
[src]
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,
[src]
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,
[src]
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
[src]
impl Responder<'static> for Template
[src]
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>
[src]
Returns Ok
if a Response
could be generated successfully. Otherwise, returns an Err
with a failing Status
. Read more