Struct ReloadableTera 

pub struct ReloadableTera { /* private fields */ }

Reloadable Tera.

Implementations

impl ReloadableTera

pub fn new() -> ReloadableTera

Create an instance of ReloadableTera.

pub fn register_template_file<P: Into<PathBuf>>( &mut self, name: &'static str, file_path: P, ) -> Result<(), TeraError>

Register a template from a path and it can be reloaded automatically.

pub fn unregister_template_file<S: AsRef<str>>( &mut self, name: S, ) -> Option<PathBuf>

Unregister a template from a file by a name.

Tera provides no API for removing a single template, so the template itself stays inside Tera and only stops being reloaded.

pub fn reload_if_needed(&mut self) -> Result<(), TeraError>

Reload templates if needed.

Methods from Deref<Target = Tera>

pub fn autoescape_on( &mut self, suffixes: impl IntoIterator<Item = impl Into<Cow<'static, str>>>, )

Select which suffix(es) to automatically do HTML escaping on.

By default, autoescaping is performed on .html, .htm and .xml template files. Only call this function if you wish to change the defaults.

Examples

Basic usage:

let mut tera = Tera::default();
// escape only files ending with `.php.html`
tera.autoescape_on([".php.html"]);
// disable autoescaping completely
tera.autoescape_on(Vec::<&str>::new());

pub fn set_delimiters(&mut self, delimiters: Delimiters) -> Result<(), Error>

Set custom delimiters for template syntax.

This must be called before adding any templates. Returns an error if any delimiter is empty, if start delimiters conflict or if there are already templates added to the Tera instance.

Example

use tera::{Tera, Delimiters};

let mut tera = Tera::new();
tera.set_delimiters(Delimiters {
    block_start: "<%".into(),
    block_end: "%>".into(),
    variable_start: "<<".into(),
    variable_end: ">>".into(),
    comment_start: "<#".into(),
    comment_end: "#>".into(),
}).unwrap();
tera.add_raw_template("example", "<< name >>").unwrap();

pub fn set_escape_fn( &mut self, function: fn(&str, &mut dyn Write) -> Result<(), Error>, )

Set user-defined function that is used to escape content.

Often times, arbitrary data needs to be injected into a template without allowing injection attacks. For this reason, typically escaping is performed on all input. By default, the escaping function will produce HTML escapes, but it can be overridden to produce escapes more appropriate to the language being used.

Inside templates, escaping can be turned off for specific content using the safe filter. For example, the string {{ data }} inside a template will escape data, while {{ data | safe }} will not.

Examples

Basic usage:

// Create new Tera instance
let mut tera = Tera::default();

// Override escape function to escape the letter A, why not
tera.set_escape_fn(|input: &str, output: &mut dyn Write| {
    for byte in input.bytes() {
        match byte {
            b'a' => output.write_all(b"?")?,
            _ => output.write_all(&[byte])?,
        }
    }
    Ok(())
});

// Create template and enable autoescape
tera.add_raw_template("hello.js", "const data = \"{{ content }}\";").unwrap();
tera.autoescape_on(vec!["js"]);

// Create context with some data
let mut context = Context::new();
context.insert("content", &r#"Hello tera"#);

// Render template
let result = tera.render("hello.js", &context).unwrap();
assert_eq!(result, r#"const data = "Hello ter?";"#);

pub fn reset_escape_fn(&mut self)

Reset escape function to default escape_html().

pub fn register_filter<Func, Arg, Res>( &mut self, name: impl Into<Cow<'static, str>>, filter: Func, )

where Func: Filter<Arg, Res> + for<'a> Filter<<Arg as ArgFromValue<'a>>::Output, Res>, Arg: for<'a> ArgFromValue<'a>, Res: FunctionResult,

Register a filter with Tera.

If a filter with that name already exists, it will be overwritten

let mut tera = Tera::default();
tera.register_filter("double", |x: i64, _: Kwargs, _: &State| x * 2);

pub fn register_test<Func, Arg, Res>( &mut self, name: impl Into<Cow<'static, str>>, test: Func, )

where Func: Test<Arg, Res> + for<'a> Test<<Arg as ArgFromValue<'a>>::Output, Res>, Arg: for<'a> ArgFromValue<'a>, Res: TestResult,

Register a test with Tera.

If a test with that name already exists, it will be overwritten

let mut tera = Tera::default();
tera.register_test("odd", |x: i64, _: Kwargs, _: &State| x % 2 != 0);

pub fn register_function<Func, Res>( &mut self, name: impl Into<Cow<'static, str>>, func: Func, )

where Func: Function<Res>, Res: FunctionResult,

Register a function with Tera.

If a function with that name already exists, it will be overwritten

pub fn register_from(&mut self, other: &Tera)

Register filters, tests, and functions from another Tera instance.

If a filter/test/function with the same name already exists in this instance, it will not be overwritten.

pub fn get_template_variables( &self, template_name: &str, ) -> Result<HashSet<&str>, Error>

Does a best-effort to find the top level variables that might be needed to be provided to render the template.

This doesn’t do a full analysis and just reports all top level variables that were found. It doesn’t care about if statements etc.

pub fn get_component_definition(&self, name: &str) -> Option<ComponentInfo>

Returns information about a registered component definition.

Returns None if no component with the given name is found.

Examples

let mut tera = Tera::default();
tera.add_raw_template(
    "components.html",
    r#"{% component Button(label: String, variant="primary") %}<button>{{ label }}</button>{% endcomponent Button %}"#,
).unwrap();

let info = tera.get_component_definition("Button").unwrap();
assert_eq!(info.name(), "Button");
assert_eq!(info.args().len(), 2);

pub fn contains_component(&self, component_name: &str) -> bool

Lookups a component by name, returning whether it’s found or not Returns fakse if no component with the given name is found.

Examples

let mut tera = Tera::default();
tera.add_raw_template(
    "components.html",
    r#"{% component Button(label: String, variant="primary") %}<button>{{ label }}</button>{% endcomponent Button %}"#,
).unwrap();

assert!(tera.contains_component("Button"));

pub fn get_component_names(&self) -> impl Iterator<Item = &str>

Returns an iterator over the names of all registered components in an unspecified order.

Example

use tera::Tera;

let mut tera = Tera::default();
tera.add_raw_template("foo", "{% component hello(name) %}{{ name }}{% endcomponent %}");

let names: Vec<_> = tera.get_component_names().collect();
assert_eq!(names.len(), 1);
assert!(names.contains(&"hello"));

pub fn add_raw_template( &mut self, name: &str, content: &str, ) -> Result<(), Error>

Add a single template to the Tera instance.

This will error if there are errors in the inheritance, such as adding a child template without the parent one.

Bulk loading

If you want to add several templates, use add_raw_templates().

Examples

Basic usage:

let mut tera = Tera::default();
tera.add_raw_template("new.html", "Blabla").unwrap();

pub fn add_raw_templates<I, N, C>(&mut self, templates: I) -> Result<(), Error>

where I: IntoIterator<Item = (N, C)>, N: AsRef<str>, C: AsRef<str>,

Add all the templates given to the Tera instance

This will error if there are errors in the inheritance, such as adding a child template without the parent one.

let mut tera = Tera::default();
tera.add_raw_templates(vec![
    ("new.html", "blabla"),
    ("new2.html", "hello"),
]).unwrap();

pub fn add_template_file<P>( &mut self, path: P, name: Option<&str>, ) -> Result<(), Error>

where P: AsRef<Path>,

Add a single template from a path to the Tera instance. The default name for the template is the path given, but this can be renamed with the name parameter

This will error if the inheritance chain can’t be built, such as adding a child template without the parent one. If you want to add several file, use Tera::add_template_files

let mut tera = Tera::default();
// Rename template with custom name
tera.add_template_file("path/to/template.html", Some("template.html")).unwrap();
// Use path as name
tera.add_template_file("path/to/other.html", None).unwrap();

pub fn add_template_files<I, P, N>(&mut self, files: I) -> Result<(), Error>

where I: IntoIterator<Item = (P, Option<N>)>, P: AsRef<Path>, N: AsRef<str>,

Add several templates from paths to the Tera instance.

The default name for the template is the path given, but this can be renamed with the second parameter of the tuple

This will error if the inheritance chain can’t be built, such as adding a child template without the parent one.

let mut tera = Tera::default();
tera.add_template_files(vec![
    ("./path/to/template.tera", None), // this template will have the value of path1 as name
    ("./path/to/other.tera", Some("hey")), // this template will have `hey` as name
]);

pub fn set_fallback_prefixes( &mut self, prefixes: impl IntoIterator<Item = impl Into<Cow<'static, str>>>, ) -> Result<(), Error>

Set fallback prefixes to try when a template is not found by exact name. This needs to be called before adding templates, it will error otherwise.

When a template is requested (via render, extends, or include) and the exact name is not found, these prefixes are tried in order. The first prefix that produces a match is used.

Prefixes should include any path separator (e.g., "themes/cool/" not "themes/cool").

Example

let mut tera = Tera::default();
// Templates in "themes/cool/" can be referenced without the prefix
tera.set_fallback_prefixes(["themes/cool/"]).unwrap();

pub fn contains_template(&self, template_name: &str) -> bool

Lookups a template by name, resolving fallback prefixes if needed, returning whether it’s found or not

pub fn get_template_names(&self) -> impl Iterator<Item = &str>

Returns an iterator over the names of all registered templates in an unspecified order.

Example

use tera::Tera;

let mut tera = Tera::default();
tera.add_raw_template("foo", "{{ hello }}");
tera.add_raw_template("another-one.html", "contents go here");

let names: Vec<_> = tera.get_template_names().collect();
assert_eq!(names.len(), 2);
assert!(names.contains(&"foo"));
assert!(names.contains(&"another-one.html"));

pub fn render( &self, template_name: &str, context: &Context, ) -> Result<String, Error>

Renders a Tera template given a Context.

Examples

Basic usage:

// Create new tera instance with sample template
let mut tera = Tera::default();
tera.add_raw_template("info", "My age is {{ age }}.");

// Create new context
let mut context = Context::new();
context.insert("age", &18);

// Render template using the context
let output = tera.render("info", &context).unwrap();
assert_eq!(output, "My age is 18.");

To render a template with no context, simply pass a Context::new() object.

// Create new tera instance with demo template
let mut tera = Tera::default();
tera.add_raw_template("hello.html", "<h1>Hello</h1>");

// Render a template with an empty context
let output = tera.render("hello.html", &Context::new()).unwrap();
assert_eq!(output, "<h1>Hello</h1>");

pub fn render_to( &self, template_name: &str, context: &Context, write: impl Write, ) -> Result<(), Error>

Renders a Tera template given a Context to something that implements Write.

The only difference from render() is that this version doesn’t convert buffer to a String, allowing to render directly to anything that implements Write. For example, this could be used to write directly to a File.

Any I/O error will be reported in the result.

Examples

Rendering into a Vec<u8>:

let mut tera = Tera::default();
tera.add_raw_template("index.html", "<p>{{ name }}</p>");

// Rendering a template to an internal buffer
let mut buffer = Vec::new();
let mut context = Context::new();
context.insert("name", "John Wick");
tera.render_to("index.html", &context, &mut buffer).unwrap();
assert_eq!(buffer, b"<p>John Wick</p>");

pub fn global_context(&mut self) -> &mut Context

Returns the global context, allowing modifications to it

The global context is automatically included into every template, which is useful for sharing common data.

The global context is not passed if you call render_component.

let mut tera = Tera::new();
tera.global_context().insert("name", "John Doe");

let content = tera
    .render_str("Hello, {{ name }}!", &Context::new(), false)
    .unwrap();
assert_eq!(content, "Hello, John Doe!".to_string());

let content2 = tera
    .render_str(
        "UserID: {{ id }}, Username: {{ name }}",
        &context! { id => &7489 },
        false,
    )
    .unwrap();
assert_eq!(content2, "UserID: 7489, Username: John Doe");

pub fn render_str( &self, input: &str, context: &Context, autoescape: bool, ) -> Result<String, Error>

Renders a one-off template (for example a template coming from a user input) given a Context and using this Tera instance’s filters, tests, functions and components.

The only limitation is that it cannot use {% extends %} and therefore blocks.

Any errors will mention the __tera_one_off template: this is the name given to the template by Tera.

let tera = Tera::new();
let result = tera.render_str(
    "Hello {{ name }}!",
    &context! { name => "world" },
    false,
).unwrap();
assert_eq!(result, "Hello world!");

pub fn render_str_to( &self, input: &str, context: &Context, autoescape: bool, write: impl Write, ) -> Result<(), Error>

Renders a one-off template to a writer.

Same as render_str but writes to a Write implementor.

pub fn render_component( &self, component_name: &str, context: &Context, body: Option<&str>, autoescape: bool, ) -> Result<String, Error>

Renders a component by name with the given context and optional body content.

The context should contain the component’s arguments as key-value pairs.

Examples

let mut tera = Tera::default();
tera.add_raw_template(
    "components.html",
    r#"{% component Button(label) %}<button>{{ label }}</button>{% endcomponent Button %}
{% component Card(title) %}<div><h1>{{ title }}</h1>{{ body }}</div>{% endcomponent Card %}"#,
).unwrap();

// Render a component with arguments
let html = tera.render_component(
    "Button",
    &context! { label => "Click me" },
    None,
    true,
).unwrap();
assert_eq!(html, "<button>Click me</button>");

// Render a component with body content
let html = tera.render_component(
    "Card",
    &context! { title => "My Card" },
    Some("<p>Card content here</p>"),
    true,
).unwrap();
assert_eq!(html, "<div><h1>My Card</h1><p>Card content here</p></div>");

pub fn render_component_to( &self, component_name: &str, context: &Context, body: Option<&str>, autoescape: bool, write: impl Write, ) -> Result<(), Error>

Renders a component by name to something that implements Write.

Same as render_component but writes to a Write implementor instead of returning a String.

Examples

let mut tera = Tera::default();
tera.add_raw_template(
    "components.html",
    r#"{% component Button(label) %}<button>{{ label }}</button>{% endcomponent Button %}"#,
).unwrap();

let mut buffer = Vec::new();
tera.render_component_to(
    "Button",
    &context! { label => "Click me" },
    None,
    true,
    &mut buffer,
).unwrap();
assert_eq!(buffer, b"<button>Click me</button>");

pub fn render_block( &self, template_name: &str, block_name: &str, context: &Context, ) -> Result<String, Error>

Renders a block by name with the given context.

Examples

// Create new tera instance with demo template
let mut tera = Tera::default();
tera.add_raw_template("hello.html", "<h1>Hello</h1>{% block content %}in block{% endblock %}");

// Render a template with an empty context
let output = tera.render_block("hello.html", "content", &Context::new()).unwrap();
assert_eq!(output, "in block");

pub fn render_block_to( &self, template_name: &str, block_name: &str, context: &Context, write: impl Write, ) -> Result<(), Error>

Renders a block by name with the given context to something that implements Write.

Examples

let mut tera = Tera::default();
tera.add_raw_template("hello.html", "<h1>Hello</h1>{% block content %}in block{% endblock %}");

let mut buffer = Vec::new();
tera.render_block_to("hello.html", "content", &Context::new(), &mut buffer).unwrap();
assert_eq!(buffer, b"in block");

Trait Implementations

impl Debug for ReloadableTera

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReloadableTera

fn default() -> Self

Returns the “default value” for a type.

impl Deref for ReloadableTera

type Target = Tera

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for ReloadableTera

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.