impl Tera

fn new(dir: &str) -> Result<Tera>

Create a new instance of Tera, containing all the parsed templates found in the dir glob.

A glob is a pattern for matching multiple file paths, employing special characters such as the single asterisk (*) to match any sequence of characters within a single directory level, and the double asterisk (**) to match any sequence of characters across multiple directory levels, thereby providing a flexible and concise way to select files based on their names, extensions, or hierarchical relationships. For example, the glob pattern templates/*.html will match all files with the .html extension located directly inside the templates folder, while the glob pattern templates/**/*.html will match all files with the .html extension directly inside or in a subdirectory of templates.

In order to create an empty Tera instance, you can use the Default implementation.

Examples

Basic usage:

# use tera::Tera;
let tera = Tera::new("examples/basic/templates/**/*").unwrap();

fn parse(dir: &str) -> Result<Tera>

Create a new instance of Tera, containing all the parsed templates found in the dir glob.

The difference to Tera::new is that it won't build the inheritance chains automatically, so you are free to modify the templates if you need to.

Inheritance Chains

You will not get a working Tera instance using this method. You will need to call build_inheritance_chains() to make it usable.

Examples

Basic usage:

# use tera::Tera;
let mut tera = Tera::parse("examples/basic/templates/**/*").unwrap();

// do not forget to build the inheritance chains
tera.build_inheritance_chains().unwrap();

fn build_inheritance_chains(self: &mut Self) -> Result<()>

Build inheritance chains for loaded templates.

We need to know the hierarchy of templates to be able to render multiple extends level. This happens at compile-time to avoid checking it every time we want to render a template. This also checks for soundness issues in the inheritance chains, such as missing template or circular extends. It also builds the block inheritance chain and detects when super() is called in a place where it can't possibly work

You generally don't need to call that yourself, unless you used [Tera::parse()].

fn check_macro_files(self: &Self) -> Result<()>

We keep track of macro files loaded in each Template so we can know whether one or them is missing and error accordingly before the user tries to render a template.

As with build_inheritance_chains(), you don't usually need to call that yourself.

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

Renders a Tera template given a Context.

Examples

Basic usage:

# use tera::{Tera, Context};
// 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 an empty context, simply pass an empty Context object.

# use tera::{Tera, Context};
// 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>");

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

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

# use tera::{Context, Tera};
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>");

fn render_str(self: &mut Self, input: &str, context: &Context) -> Result<String>

Renders a one off template (for example a template coming from a user input) given a Context and an instance of Tera. This allows you to render templates using custom filters or functions.

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

let mut context = Context::new();
context.insert("greeting", &"Hello");
let string = tera.render_str("{{ greeting }} World!", &context)?;
assert_eq!(string, "Hello World!");

fn one_off(input: &str, context: &Context, autoescape: bool) -> Result<String>

Renders a one off template (for example a template coming from a user input) given a Context

This creates a separate instance of Tera with no possibilities of adding custom filters or testers, parses the template and render it immediately. Any errors will mention the __tera_one_off template: this is the name given to the template by Tera

let mut context = Context::new();
context.insert("greeting", &"hello");
Tera::one_off("{{ greeting }} world", &context, true);

fn get_template_names(self: &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"));

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

Add a single template to the Tera instance.

This will error if the inheritance chain can't be built, 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:

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

fn add_raw_templates<I, N, C>(self: &mut Self, templates: I) -> Result<()>
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 the inheritance chain can't be built, such as adding a child template without the parent one.

tera.add_raw_templates(vec![
    ("new.html", "blabla"),
    ("new2.html", "hello"),
]);

fn add_template_file<P: AsRef<Path>>(self: &mut Self, path: P, name: Option<&str>) -> Result<()>

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

# use tera::Tera;
let mut tera = Tera::default();
// Rename template with custom name
tera.add_template_file("examples/basic/templates/macros.html", Some("macros.html")).unwrap();
// Use path as name
tera.add_template_file("examples/basic/templates/base.html", None).unwrap();

fn add_template_files<I, P, N>(self: &mut Self, files: I) -> Result<()>
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.

# use tera::Tera;
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
]);

fn register_filter<F: Filter + 'static>(self: &mut Self, name: &str, filter: F)

Register a filter with Tera.

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

tera.register_filter("upper", string::upper);

fn register_tester<T: Test + 'static>(self: &mut Self, name: &str, tester: T)

Register a tester with Tera.

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

tera.register_tester("odd", testers::odd);

fn register_function<F: Function + 'static>(self: &mut Self, name: &str, function: F)

Register a function with Tera.

This registers an arbitrary function to make it callable from within a template. If a function with that name already exists, it will be overwritten.

tera.register_function("range", range);

fn autoescape_on(self: &mut Self, suffixes: Vec<&'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:

# use tera::Tera;
let mut tera = Tera::default();
// escape only files ending with `.php.html`
tera.autoescape_on(vec![".php.html"]);
// disable autoescaping completely
tera.autoescape_on(vec![]);

fn set_escape_fn(self: &mut Self, function: fn(_: &str) -> String)

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:

# use tera::{Tera, Context};
// Create new Tera instance
let mut tera = Tera::default();

// Override escape function
tera.set_escape_fn(|input| {
    input.escape_default().collect()
});

// 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", &"Hello\n\'world\"!");

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

fn reset_escape_fn(self: &mut Self)

Reset escape function to default [escape_html()].

fn full_reload(self: &mut Self) -> Result<()>

Re-parse all templates found in the glob given to Tera.

Use this when you are watching a directory and want to reload everything, for example when a file is added.

If you are adding templates without using a glob, we can't know when a template is deleted, which would result in an error if we are trying to reload that file.

fn extend(self: &mut Self, other: &Tera) -> Result<()>

Extend this Tera instance with the templates, filters, testers and functions defined in another instance.

Use that method when you want to add a given Tera instance templates/filters/testers/functions to your own. If a template/filter/tester/function with the same name already exists in your instance, it will not be overwritten.

 // add all the templates from FRAMEWORK_TERA
 // except the ones that have an identical name to the ones in `my_tera`
 my_tera.extend(&FRAMEWORK_TERA);

impl Clone for Tera

fn clone(self: &Self) -> Tera

impl Debug for Tera

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

impl Default for Tera

fn default() -> Tera

impl Freeze for Tera

impl RefUnwindSafe for Tera

impl Send for Tera

impl Sync for Tera

impl Unpin for Tera

impl UnsafeUnpin for Tera

impl UnwindSafe for Tera

impl<T> Any for Tera

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Tera

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Tera

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

impl<T> CloneToUninit for Tera

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Tera

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for Tera

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

unsafe fn drop(ptr: usize)

impl<T> ToOwned for Tera

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for Tera

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for Tera

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Tera

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

impl<V, T> VZip for Tera

fn vzip(self: Self) -> V