Struct trillium_tera::Tera
source · pub struct Tera { /* private fields */ }
Expand description
Main point of interaction in this library.
The Tera
struct is the primary interface for working with the Tera template engine. It contains parsed templates, registered filters (which can filter
data), functions, and testers. It also contains some configuration options, such as a list of
suffixes for files that have autoescaping turned on.
It is responsible for:
- Loading and managing templates from files or strings
- Parsing templates and checking for syntax errors
- Maintaining a cache of compiled templates for efficient rendering
- Providing an interface for rendering templates with given contexts
- Managing template inheritance and includes
- Handling custom filters and functions
- Overriding settings, such as autoescape rules
§Example
Basic usage:
use tera::Tera;
// Create a new Tera instance and add a template from a string
let mut tera = Tera::new("templates/**/*").unwrap();
tera.add_raw_template("hello", "Hello, {{ name }}!").unwrap();
// Prepare the context with some data
let mut context = tera::Context::new();
context.insert("name", "World");
// Render the template with the given context
let rendered = tera.render("hello", &context).unwrap();
assert_eq!(rendered, "Hello, World!");
Implementations§
source§impl Tera
impl Tera
sourcepub fn new(dir: &str) -> Result<Tera, Error>
pub fn new(dir: &str) -> Result<Tera, Error>
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:
let tera = Tera::new("examples/basic/templates/**/*").unwrap();
sourcepub fn parse(dir: &str) -> Result<Tera, Error>
pub fn parse(dir: &str) -> Result<Tera, Error>
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:
let mut tera = Tera::parse("examples/basic/templates/**/*").unwrap();
// do not forget to build the inheritance chains
tera.build_inheritance_chains().unwrap();
sourcepub fn build_inheritance_chains(&mut self) -> Result<(), Error>
pub fn build_inheritance_chains(&mut self) -> Result<(), Error>
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()
.
sourcepub fn check_macro_files(&self) -> Result<(), Error>
pub fn check_macro_files(&self) -> Result<(), Error>
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.
sourcepub fn render(
&self,
template_name: &str,
context: &Context,
) -> Result<String, Error>
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 an empty context, simply pass an empty Context
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>");
sourcepub fn render_to(
&self,
template_name: &str,
context: &Context,
write: impl Write,
) -> Result<(), Error>
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>");
sourcepub fn render_str(
&mut self,
input: &str,
context: &Context,
) -> Result<String, Error>
pub fn render_str( &mut self, input: &str, context: &Context, ) -> Result<String, Error>
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!");
sourcepub fn one_off(
input: &str,
context: &Context,
autoescape: bool,
) -> Result<String, Error>
pub fn one_off( 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
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);
sourcepub fn get_template_names(&self) -> impl Iterator<Item = &str>
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"));
sourcepub fn add_raw_template(
&mut self,
name: &str,
content: &str,
) -> Result<(), Error>
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 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:
let mut tera = Tera::default();
tera.add_raw_template("new.html", "Blabla").unwrap();
sourcepub fn add_raw_templates<I, N, C>(&mut self, templates: I) -> Result<(), Error>
pub fn add_raw_templates<I, N, C>(&mut self, templates: I) -> Result<(), Error>
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"),
]);
sourcepub fn add_template_file<P>(
&mut self,
path: P,
name: Option<&str>,
) -> Result<(), Error>
pub fn add_template_file<P>( &mut self, path: P, name: Option<&str>, ) -> Result<(), Error>
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("examples/basic/templates/macros.html", Some("macros.html")).unwrap();
// Use path as name
tera.add_template_file("examples/basic/templates/base.html", None).unwrap();
sourcepub fn add_template_files<I, P, N>(&mut self, files: I) -> Result<(), Error>
pub fn add_template_files<I, P, N>(&mut self, files: I) -> Result<(), Error>
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
]);
sourcepub fn register_filter<F>(&mut self, name: &str, filter: F)where
F: Filter + 'static,
pub fn register_filter<F>(&mut self, name: &str, filter: F)where
F: Filter + 'static,
Register a filter with Tera.
If a filter with that name already exists, it will be overwritten
tera.register_filter("upper", string::upper);
sourcepub fn register_tester<T>(&mut self, name: &str, tester: T)where
T: Test + 'static,
pub fn register_tester<T>(&mut self, name: &str, tester: T)where
T: Test + 'static,
Register a tester with Tera.
If a tester with that name already exists, it will be overwritten
tera.register_tester("odd", testers::odd);
sourcepub fn register_function<F>(&mut self, name: &str, function: F)where
F: Function + 'static,
pub fn register_function<F>(&mut self, name: &str, function: F)where
F: Function + 'static,
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);
sourcepub fn autoescape_on(&mut self, suffixes: Vec<&'static str>)
pub fn autoescape_on(&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:
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![]);
sourcepub fn set_escape_fn(&mut self, function: fn(_: &str) -> String)
pub fn set_escape_fn(&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:
// 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\"!";"#);
sourcepub fn reset_escape_fn(&mut self)
pub fn reset_escape_fn(&mut self)
Reset escape function to default escape_html()
.
sourcepub fn full_reload(&mut self) -> Result<(), Error>
pub fn full_reload(&mut self) -> Result<(), Error>
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.
sourcepub fn extend(&mut self, other: &Tera) -> Result<(), Error>
pub fn extend(&mut self, other: &Tera) -> Result<(), Error>
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);
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Tera
impl !RefUnwindSafe for Tera
impl Send for Tera
impl Sync for Tera
impl Unpin for Tera
impl !UnwindSafe for Tera
Blanket Implementations§
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
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)