pub struct Templating { /* private fields */ }Expand description
A fairing that initializes and maintains templating state.
§Usage
To use Templating, first construct an instance with Templating::new()
or Templating::init(). The former uses the default configuration, while
the latter allows you to customize the templating engines. Then, attach the
instance to your application’s instance of Rocket:
use rocket_dyn_templates::Templating;
rocket::build()
// ...
.attach(Templating::new())This fairing must be attached to any Rocket instance that wishes to
render templates. Failure to attach this fairing will result in an
“Uninitialized template context: missing fairing.” error message when a
template is attempted to be rendered.
§Customization
Templating engines can be customized via two callbacks: one set via
Templating::init() or on_init(), and another set
via on_load(). Each is passed an Engines, which
exposes the enabled engines. Regardless of the order in which the callbacks
are set, the fairing initializes templating as follows:
- Creates the templating engines with Rocket’s defaults.
- Calls the
on_initcallback. - Loads the templates in
template_dir. - Calls the
on_loadcallback.
Which callback to use depends on the templates in template_dir. Some
engines check a template as soon as it’s added, requiring everything it
uses, such as filters and other templates, to already exist. As such,
anything that templates in template_dir use must be registered in
on_init, before those templates are loaded. Conversely, a template that
uses templates in template_dir must be added in on_load, after those
templates are loaded. In summary:
| To… | Use |
|---|---|
| register helpers, filters, functions, or tests | on_init |
| configure syntax, escaping, or other engine settings | on_init |
add a template used by templates in template_dir | on_init |
add a template that uses templates in template_dir | on_load |
As a general rule of thumb, use on_init. Only use on_load to add
templates that extend, include, or otherwise use templates in
template_dir. See Engines for details on when each engine checks
templates.
For example, the following adds two Tera templates: footer.html, which
templates in template_dir can include, and child.html, which extends
base.html, a template in template_dir:
use rocket_dyn_templates::Templating;
let templating = Templating::try_init(|engines| {
engines.tera.add_raw_template("footer.html", "<footer>Rocket</footer>")?;
Ok(())
}).try_on_load(|engines| {
engines.tera.add_raw_template("child.html", concat!(
"{% extends \"base.html\" %}",
"{% block content %}Hello, world!{% endblock %}",
))?;
Ok(())
});
rocket::build().attach(templating);§Reloading
In debug mode, the fairing checks for modifications to templates before every request and reloads them if necessary. Reloading repeats all of the steps above with new engines, so both callbacks are called again.
§Errors
If loading templates or a callback fails, the remaining steps are skipped. During ignition, this aborts launch. During reloading, the new engines are discarded, and the previous templates continue to be used.
Implementations§
Source§impl Templating
impl Templating
Sourcepub fn new() -> Self
pub fn new() -> Self
Returns a fairing that initializes and maintains templating state.
If you wish to customize the internal templating engines, use
Templating::init() instead.
§Example
To attach this fairing, simply call attach on the application’s
Rocket instance with Templating::new():
extern crate rocket;
extern crate rocket_dyn_templates;
use rocket_dyn_templates::Templating;
fn main() {
rocket::build()
// ...
.attach(Templating::new())
// ...
}Sourcepub fn init<F>(f: F) -> Self
pub fn init<F>(f: F) -> Self
Returns a fairing that initializes and maintains templating state.
Unlike Templating::new(), this method allows you to customize the
templating engines via the function f, which is called before
templates are loaded. This is equivalent to
Templating::new().on_init(f). See
customization for details.
This method does not allow the function f to fail. If f is fallible,
use Templating::try_init() instead.
§Example
extern crate rocket;
extern crate rocket_dyn_templates;
use rocket_dyn_templates::Templating;
fn main() {
rocket::build()
// ...
.attach(Templating::init(|engines| {
// engines.handlebars.register_helper ...
}))
// ...
}Sourcepub fn try_init<F>(f: F) -> Self
pub fn try_init<F>(f: F) -> Self
Returns a fairing that initializes and maintains templating state.
This variant of Templating::init() allows a fallible f and is
equivalent to Templating::new().try_on_init(f). See
errors for what happens when f fails.
§Example
extern crate rocket;
extern crate rocket_dyn_templates;
use rocket_dyn_templates::Templating;
fn main() {
rocket::build()
// ...
.attach(Templating::try_init(|engines| {
// engines.handlebars.register_helper ...
Ok(())
}))
// ...
}Sourcepub fn on_init<F>(self, f: F) -> Self
pub fn on_init<F>(self, f: F) -> Self
Sets the function f to be called before templates are loaded.
Use this method to register helpers, configure engines, and add
templates that templates in template_dir use. See
customization for details. If an on_init
callback was previously set, it is replaced with f.
This method does not allow the function f to fail. If f is fallible,
use Templating::try_on_init() instead.
Sourcepub fn try_on_init<F>(self, f: F) -> Self
pub fn try_on_init<F>(self, f: F) -> Self
Sets a fallible function f to be called before templates are loaded.
This variant of Templating::on_init() allows a fallible f. See
errors for what happens when f fails.
Sourcepub fn on_load<F>(self, f: F) -> Self
pub fn on_load<F>(self, f: F) -> Self
Sets the function f to be called after templates are loaded.
Use this method to add templates that extend, include, or otherwise use
templates in template_dir. See
customization for details. If an on_load
callback was previously set, it is replaced with f.
This method does not allow the function f to fail. If f is fallible,
use Templating::try_on_load() instead.
Trait Implementations§
Source§impl Default for Templating
impl Default for Templating
Source§impl Fairing for Templating
impl Fairing for Templating
Source§fn on_ignite<'life0, 'async_trait>(
&'life0 self,
rocket: Rocket<Build>,
) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn on_ignite<'life0, 'async_trait>(
&'life0 self,
rocket: Rocket<Build>,
) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
Initializes the template context. Templates will be searched for in the
template_dir config variable or the default (templates/).
The user’s callbacks, if any were supplied, are called to customize the
template engines. In debug mode, the ContextManager::new method
initializes a directory watcher for auto-reloading of templates.
Source§fn on_liftoff<'life0, 'life1, 'async_trait>(
&'life0 self,
rocket: &'life1 Rocket<Orbit>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
fn on_liftoff<'life0, 'life1, 'async_trait>(
&'life0 self,
rocket: &'life1 Rocket<Orbit>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Source§fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
req: &'life1 mut Request<'life2>,
_data: &'life3 mut Data<'life4>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
req: &'life1 mut Request<'life2>,
_data: &'life3 mut Data<'life4>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
Source§fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
_req: &'r Request<'life1>,
_res: &'life2 mut Response<'r>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'r: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
_req: &'r Request<'life1>,
_res: &'life2 mut Response<'r>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'r: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
Auto Trait Implementations§
impl !RefUnwindSafe for Templating
impl !UnwindSafe for Templating
impl Forget for Templating
impl Freeze for Templating
impl Move for Templating
impl Send for Templating
impl Sync for Templating
impl Unpin for Templating
impl UnsafeUnpin for Templating
Blanket Implementations§
Source§impl<T> AsAny for Twhere
T: Any,
impl<T> AsAny for Twhere
T: Any,
fn as_any_ref(&self) -> &(dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Source§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
Source§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
Source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the foreground set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red() and
green(), which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg():
use yansi::{Paint, Color};
painted.fg(Color::White);Set foreground color to white using white().
use yansi::Paint;
painted.white();Source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
Source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
Source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
Source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
Source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
Source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
Source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the background set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red() and
on_green(), which have the same functionality but
are pithier.
§Example
Set background color to red using fg():
use yansi::{Paint, Color};
painted.bg(Color::Red);Set background color to red using on_red().
use yansi::Paint;
painted.on_red();Source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
Source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
Source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
Source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute value.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold() and
underline(), which have the same functionality
but are pithier.
§Example
Make text bold using attr():
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);Make text bold using using bold().
use yansi::Paint;
painted.bold();Source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi Quirk value.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask() and
wrap(), which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk():
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);Enable wrapping using wrap().
use yansi::Paint;
painted.wrap();Source§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
fn clear(&self) -> Painted<&T>
renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
Source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted only when both stdout and stderr are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);