1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
//! Tera templating support for Rocket.
//!
//! This crate adds support for using [Tera](https://keats.github.io/tera/) with Rocket. It
//! automatically discovers templates, provides a `Responder` to render templates,
//! and automatically reloads templates when compiled in debug mode.
//!
//! # Usage
//!
//! 1. Depend on the crate: `cargo add rocket_tera`
//!
//! 2. Write your templates inside of the [configurable]
//! `${ROCKET_ROOT}/templates`. Every file in that directory is a template;
//! no particular extension is required, but the extension determines the
//! response's `Content-Type`, as in
//! `${ROCKET_ROOT}/templates/index.html`.
//!
//! [configurable]: #configuration
//!
//! 3. Attach `Template::fairing()` and return a [`Template`] from your routes
//! via [`Template::render()`], supplying the path of the template file
//! **relative to the template directory**:
//!
//! ```rust
//! # #[macro_use] extern crate rocket;
//! use rocket_tera::{Template, context};
//!
//! #[get("/")]
//! fn index() -> Template {
//! Template::render("index.html", context! { field: "value" })
//! }
//!
//! #[launch]
//! fn rocket() -> _ {
//! rocket::build().attach(Template::fairing())
//! }
//! ```
//!
//! ## Configuration
//!
//! This crate reads one configuration parameter from the configured figment:
//!
//! * `template_dir` (**default: `templates/`**)
//!
//! A path to a directory to search for template files in. Relative paths
//! are considered relative to the configuration file, or if there is no file,
//! the current working directory.
//!
//! For example, to change the default and set `template_dir` to different
//! values based on whether the application was compiled for debug or release
//! from a `Rocket.toml` file (read by the default figment), you might write:
//!
//! ```toml
//! [debug]
//! template_dir = "static/templates"
//!
//! [release]
//! template_dir = "/var/opt/www/templates"
//! ```
//!
//! **Note:** `template_dir` defaults to `templates/`. It _does not_ need to be
//! specified if the default suffices.
//!
//! See the [configuration chapter] of the guide for more information on
//! configuration.
//!
//! [configuration chapter]: https://rocket.rs/guide/v0.5/configuration/
//!
//! ## Template Naming and Content-Types
//!
//! Templates are rendered by _name_ via [`Template::render()`], which returns a
//! [`Template`] responder. The _name_ of the template is the path to the
//! template file, relative to `template_dir`, extension included.
//!
//! The `Content-Type` of the response is automatically determined by the
//! extension using [`ContentType::from_extension()`]. If there is no extension
//! or it is unknown, `text/plain` is used.
//!
//! The following table contains examples:
//!
//! | template path | [`Template::render()`] call | content-type |
//! |-------------------------------------------|----------------------------------------|--------------|
//! | {template_dir}/index.html | `render("index.html")` | HTML |
//! | {template_dir}/index | `render("index")` | `text/plain` |
//! | {template_dir}/dir/index | `render("dir/index")` | `text/plain` |
//! | {template_dir}/dir/data.json | `render("dir/data.json")` | JSON |
//! | {template_dir}/data.template.xml | `render("data.template.xml")` | XML |
//! | {template_dir}/subdir/index.template.html | `render("subdir/index.template.html")` | HTML |
//!
//! Give every template the extension of the file type it renders to, so that
//! the `Content-Type` is correct: `.html`, `.xml`, and so on.
//!
//! [`ContentType::from_extension()`]: ../rocket/http/struct.ContentType.html#method.from_extension
//!
//! ### Rendering Context
//!
//! In addition to a name, [`Template::render()`] requires a context to use
//! during rendering. The context can be any [`Serialize`] type that serializes
//! to an `Object` (a dictionary) value. The [`context!`] macro can be used to
//! create inline `Serialize`-able context objects.
//!
//! [`Serialize`]: rocket::serde::Serialize
//!
//! ```rust
//! # #[macro_use] extern crate rocket;
//! use rocket::serde::Serialize;
//! use rocket_tera::{Template, context};
//!
//! #[get("/")]
//! fn index() -> Template {
//! // Using the `context! { }` macro.
//! Template::render("index.html", context! {
//! site_name: "Rocket - Home Page",
//! version: 127,
//! })
//! }
//!
//! #[get("/")]
//! fn index2() -> Template {
//! #[derive(Serialize)]
//! #[serde(crate = "rocket::serde")]
//! struct IndexContext {
//! site_name: &'static str,
//! version: u8
//! }
//!
//! // Using an existing `IndexContext`, which implements `Serialize`.
//! Template::render("index.html", IndexContext {
//! site_name: "Rocket - Home Page",
//! version: 127,
//! })
//! }
//! ```
//!
//! ### Discovery, Automatic Reloads, and Engine Customization
//!
//! As long as one of [`Template::fairing()`], [`Template::custom()`], or
//! [`Template::try_custom()`] is [attached], every file in the configured
//! `template_dir` is registered with Tera and can be rendered. Files that are
//! not valid Tera templates will abort the launch, so keep non-template assets
//! out of `template_dir`.
//!
//! _**Note:** Templates that are registered directly via [`Template::custom()`]
//! use whatever name was provided during that registration._
//!
//! In debug mode (without the `--release` flag passed to `cargo`), templates
//! are **automatically reloaded** from disk when changes are made. In release
//! builds, template reloading is disabled to improve performance and cannot be
//! enabled.
//!
//! [attached]: rocket::Rocket::attach()
//!
//! ### `tera-contrib` Features
//!
//! Tera 2 moved builtin features that required other dependencies to the [`tera-contrib`] crate.
//! Enabling a `contrib-*` feature here enables and registers the matching `tera-contrib` feature:
//!
//! | Feature | Registers |
//! |---------|-----------|
//! | `contrib-base64` | `b64_encode`, `b64_decode` filters |
//! | `contrib-date` | `date` filter, `now` function, `before` / `after` tests |
//! | `contrib-filesize_format` | `filesize_format` filter |
//! | `contrib-format` | `format` filter |
//! | `contrib-json` | `json_encode` filter |
//! | `contrib-rand` | `get_random` function, `shuffle` filter |
//! | `contrib-regex` | `striptags`, `spaceless`, `regex_replace` filters, `matching` test |
//! | `contrib-slug` | `slug` filter |
//! | `contrib-urlencode` | `urlencode`, `urlencode_strict` filters |
//!
//! [`tera-contrib`]: https://docs.rs/tera-contrib/0.3
//!
//! ### Metadata and Rendering to `String`
//!
//! The [`Metadata`] request guard allows dynamically querying templating
//! metadata, such as whether a template is known to exist
//! ([`Metadata::contains_template()`]), and to render templates to `String`
//! ([`Metadata::render()`]).
extern crate rocket;
/// The tera templating engine library, reexported.
pub use tera;
pub use serde;
pub use Metadata;
pub use Template;