Skip to main content

Templating

Struct Templating 

Source
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:

  1. Creates the templating engines with Rocket’s defaults.
  2. Calls the on_init callback.
  3. Loads the templates in template_dir.
  4. Calls the on_load callback.

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 testson_init
configure syntax, escaping, or other engine settingson_init
add a template used by templates in template_diron_init
add a template that uses templates in template_diron_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

Source

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())
        // ...
}
Source

pub fn init<F>(f: F) -> Self
where F: Fn(&mut Engines) + Send + Sync + 'static,

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 ...
        }))
        // ...
}
Source

pub fn try_init<F>(f: F) -> Self
where F: Fn(&mut Engines) -> Result<(), Box<dyn Error>> + Send + Sync + 'static,

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(())
        }))
        // ...
}
Source

pub fn on_init<F>(self, f: F) -> Self
where F: Fn(&mut Engines) + Send + Sync + 'static,

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.

Source

pub fn try_on_init<F>(self, f: F) -> Self
where F: Fn(&mut Engines) -> Result<(), Box<dyn Error>> + Send + Sync + 'static,

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.

Source

pub fn on_load<F>(self, f: F) -> Self
where F: Fn(&mut Engines) + Send + Sync + 'static,

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.

Source

pub fn try_on_load<F>(self, f: F) -> Self
where F: Fn(&mut Engines) -> Result<(), Box<dyn Error>> + Send + Sync + 'static,

Sets a fallible function f to be called after templates are loaded.

This variant of Templating::on_load() allows a fallible f. See errors for what happens when f fails.

Trait Implementations§

Source§

impl Default for Templating

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

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,

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 info(&self) -> Info

Returns an Info structure containing the name and Kind of this fairing. The name can be any arbitrary string. Kind must be an ord set of Kind variants. Read more
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,

The liftoff callback. Read more
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,

The request callback. Read more
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,

The response callback. Read more
Source§

fn on_shutdown<'life0, 'life1, 'async_trait>( &'life0 self, _rocket: &'life1 Rocket<Orbit>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

The shutdown callback. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> AsAny for T
where T: Any,

Source§

fn as_any_ref(&self) -> &(dyn Any + 'static)

Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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 more
Source§

impl<T> Paint for T
where T: ?Sized,

Source§

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 primary(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Primary].

§Example
println!("{}", value.primary());
Source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Fixed].

§Example
println!("{}", value.fixed(color));
Source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Rgb].

§Example
println!("{}", value.rgb(r, g, b));
Source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Black].

§Example
println!("{}", value.black());
Source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Red].

§Example
println!("{}", value.red());
Source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Green].

§Example
println!("{}", value.green());
Source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Yellow].

§Example
println!("{}", value.yellow());
Source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Blue].

§Example
println!("{}", value.blue());
Source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Magenta].

§Example
println!("{}", value.magenta());
Source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Cyan].

§Example
println!("{}", value.cyan());
Source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: White].

§Example
println!("{}", value.white());
Source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlack].

§Example
println!("{}", value.bright_black());
Source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightRed].

§Example
println!("{}", value.bright_red());
Source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightGreen].

§Example
println!("{}", value.bright_green());
Source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightYellow].

§Example
println!("{}", value.bright_yellow());
Source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlue].

§Example
println!("{}", value.bright_blue());
Source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.bright_magenta());
Source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightCyan].

§Example
println!("{}", value.bright_cyan());
Source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightWhite].

§Example
println!("{}", value.bright_white());
Source§

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>

Returns self with the bg() set to [Color :: Primary].

§Example
println!("{}", value.on_primary());
Source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Fixed].

§Example
println!("{}", value.on_fixed(color));
Source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Rgb].

§Example
println!("{}", value.on_rgb(r, g, b));
Source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Black].

§Example
println!("{}", value.on_black());
Source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Red].

§Example
println!("{}", value.on_red());
Source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Green].

§Example
println!("{}", value.on_green());
Source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Yellow].

§Example
println!("{}", value.on_yellow());
Source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Blue].

§Example
println!("{}", value.on_blue());
Source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Magenta].

§Example
println!("{}", value.on_magenta());
Source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Cyan].

§Example
println!("{}", value.on_cyan());
Source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: White].

§Example
println!("{}", value.on_white());
Source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlack].

§Example
println!("{}", value.on_bright_black());
Source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightRed].

§Example
println!("{}", value.on_bright_red());
Source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightGreen].

§Example
println!("{}", value.on_bright_green());
Source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightYellow].

§Example
println!("{}", value.on_bright_yellow());
Source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlue].

§Example
println!("{}", value.on_bright_blue());
Source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.on_bright_magenta());
Source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightCyan].

§Example
println!("{}", value.on_bright_cyan());
Source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightWhite].

§Example
println!("{}", value.on_bright_white());
Source§

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 bold(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Bold].

§Example
println!("{}", value.bold());
Source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Dim].

§Example
println!("{}", value.dim());
Source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Italic].

§Example
println!("{}", value.italic());
Source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Underline].

§Example
println!("{}", value.underline());

Returns self with the attr() set to [Attribute :: Blink].

§Example
println!("{}", value.blink());

Returns self with the attr() set to [Attribute :: RapidBlink].

§Example
println!("{}", value.rapid_blink());
Source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Invert].

§Example
println!("{}", value.invert());
Source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Conceal].

§Example
println!("{}", value.conceal());
Source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Strike].

§Example
println!("{}", value.strike());
Source§

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 mask(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Mask].

§Example
println!("{}", value.mask());
Source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Wrap].

§Example
println!("{}", value.wrap());
Source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Linger].

§Example
println!("{}", value.linger());
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.

Returns self with the quirk() set to [Quirk :: Clear].

§Example
println!("{}", value.clear());
Source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Resetting].

§Example
println!("{}", value.resetting());
Source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Bright].

§Example
println!("{}", value.bright());
Source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: OnBright].

§Example
println!("{}", value.on_bright());
Source§

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);
Source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
Source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more