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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
//! 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. Depend on `rocket_dyn_templates`. Enable the feature(s) corresponding
//!      to your templating engine(s) of choice:
//!
//!      ```toml
//!      [dependencies.rocket_dyn_templates]
//!      version = "0.1.0"
//!      features = ["handlebars", "tera", "minijinja"]
//!      ```
//!
//!   2. Write your templates inside of the [configurable]
//!      `${ROCKET_ROOT}/templates`. The filename _must_ end with an extension
//!      corresponding to an enabled engine. The second-to-last extension should
//!      correspond to the file's type:
//!
//!      | Engine       | Extension | Example                                    |
//!      |--------------|-----------|--------------------------------------------|
//!      | [Tera]       | `.tera`   | `${ROCKET_ROOT}/templates/index.html.tera` |
//!      | [Handlebars] | `.hbs`    | `${ROCKET_ROOT}/templates/index.html.hbs`  |
//!      | [MiniJinja]  | `.j2`     | `${ROCKET_ROOT}/templates/index.html.j2`   |
//!
//!      [configurable]: #configuration
//!      [Tera]: https://docs.rs/crate/tera/1
//!      [Handlebars]: https://docs.rs/crate/handlebars/5
//!      [MiniJinja]: https://docs.rs/minijinja/2
//!
//!   3. Attach `Template::fairing()` and return a [`Template`] from your routes
//!      via [`Template::render()`], supplying the name of the template file
//!      **minus the last two extensions**:
//!
//!      ```rust
//!      # #[macro_use] extern crate rocket;
//!      use rocket_dyn_templates::{Template, context};
//!
//!      #[get("/")]
//!      fn index() -> Template {
//!          Template::render("index", 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 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/master/guide/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`, minus at most two extensions.
//!
//! The `Content-Type` of the response is automatically determined by the
//! non-engine extension using [`ContentType::from_extension()`]. If there is no
//! such 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.hbs                 | `render("index")`                 | HTML         |
//! | {template_dir}/index.tera                     | `render("index")`                 | `text/plain` |
//! | {template_dir}/index.hbs                      | `render("index")`                 | `text/plain` |
//! | {template_dir}/dir/index.hbs                  | `render("dir/index")`             | `text/plain` |
//! | {template_dir}/dir/data.json.tera             | `render("dir/data")`              | JSON         |
//! | {template_dir}/data.template.xml.hbs          | `render("data.template")`         | XML          |
//! | {template_dir}/subdir/index.template.html.hbs | `render("subdir/index.template")` | HTML         |
//!
//! 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`, 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_dyn_templates::{Template, context};
//!
//! #[get("/")]
//! fn index() -> Template {
//!     // Using the `context! { }` macro.
//!     Template::render("index", 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", 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], any file in the configured
//! `template_dir` ending with a known engine extension (as described in the
//! [usage section](#usage)) can be rendered. The latter two fairings allow
//! customizations such as registering helpers and templates from strings.
//!
//! _**Note:** Templates that are registered directly via [`Template::custom()`],
//! use whatever name provided during that registration; no extensions are
//! automatically removed._
//!
//! 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()
//!
//! ### 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()`]).

#![doc(html_root_url = "https://api.rocket.rs/master/rocket_dyn_templates")]
#![doc(html_favicon_url = "https://rocket.rs/images/favicon.ico")]
#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")]

#[macro_use] extern crate rocket;

#[doc(inline)]
#[cfg(feature = "tera")]
/// The tera templating engine library, reexported.
pub use tera;

#[doc(inline)]
#[cfg(feature = "handlebars")]
/// The handlebars templating engine library, reexported.
pub use handlebars;

#[doc(inline)]
#[cfg(feature = "minijinja")]
/// The minijinja templating engine library, reexported.
pub use minijinja;

#[doc(hidden)]
pub use rocket::serde;

mod engine;
mod fairing;
mod context;
mod metadata;
mod template;

pub use engine::Engines;
pub use metadata::Metadata;
pub use template::Template;