Crate rocket_dyn_templates::minijinja
source · Expand description
The minijinja templating engine library, reexported.
![](https://github.com/mitsuhiko/minijinja/raw/main/artwork/logo.png)
MiniJinja: a powerful template engine for Rust with minimal dependencies
MiniJinja is a powerful but minimal dependency template engine for Rust which
is based on the syntax and behavior of the
Jinja2 template engine for Python. It’s
implemented on top of serde
. The goal is to be able to render a large
chunk of the Jinja2 template ecosystem from Rust with a minimal engine and to
leverage an already existing ecosystem of editor integrations.
{% for user in users %}
<li>{{ user.name }}</li>
{% endfor %}
You can play with MiniJinja online in the browser playground powered by a WASM build of MiniJinja.
§Why MiniJinja
MiniJinja by its name wants to be a good default choice if you need a little bit of templating with minimal dependencies. It has the following goals:
- Well documented, compact API
- Minimal dependencies, reasonable compile times and decent runtime performance
- Stay close as possible to Jinja2
- Support for expression evaluation
- Support for all
serde
compatible types - Excellent test coverage
- Support for dynamic runtime objects with methods and dynamic attributes
§Template Usage
To use MiniJinja one needs to create an Environment
and populate it with
templates. Afterwards templates can be loaded and rendered. To pass data
one can pass any serde serializable value. The context!
macro can be
used to quickly construct a template context:
use minijinja::{Environment, context};
let mut env = Environment::new();
env.add_template("hello", "Hello {{ name }}!").unwrap();
let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "John")).unwrap());
Hello John!
For super trivial cases where you need to render a string once, you can
also use the render!
macro which acts a bit like a replacement
for the format!
macro.
§Expression Usage
MiniJinja — like Jinja2 — allows to be used as expression language. This can be
useful to express logic in configuration files or similar things. For this
purpose the Environment::compile_expression
method can be used. It returns
an expression object that can then be evaluated, returning the result:
use minijinja::{Environment, context};
let env = Environment::new();
let expr = env.compile_expression("number < 42").unwrap();
let result = expr.eval(context!(number => 23)).unwrap();
assert_eq!(result.is_true(), true);
This becomes particularly powerful when dynamic objects are exposed to templates.
§Custom Filters
MiniJinja lets you register functions as filter functions (see
Filter
) with the engine. These can then be
invoked directly from the template:
use minijinja::{Environment, context};
let mut env = Environment::new();
env.add_filter("repeat", str::repeat);
env.add_template("hello", "{{ 'Na '|repeat(3) }} {{ name }}!").unwrap();
let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "Batman")).unwrap());
Na Na Na Batman!
§Learn more
Environment
: the main API entry point. Teaches you how to configure the environment.Template
: the template object API. Shows you how templates can be rendered.syntax
: provides documentation of the template engine syntax.filters
: teaches you how to write custom filters and to see the list of built-in filters.tests
: teaches you how to write custom test functions and to see the list of built-in tests.functions
: teaches how to write custom functions and to see the list of built-in functions.- For auto reloading use the
minijinja-autoreload
crate. - For simpler embedding of templates use the
minijinja-embed
crate.
Additionally there is an list of examples with many different small example programs on GitHub to explore.
§Error Handling
MiniJinja tries to give you good errors out of the box. However if you use includes or
template inheritance your experience will improve greatly if you ensure to render chained
errors. For more information see Error
with an example.
§Size and Compile Times
MiniJinja attempts to compile fast so it can be used as a sensible template engine choice
when compile times matter. Because of this it’s internally modular so unnecessary bits and
pieces can be removed. The default set of features tries to strike a balance but in
situations where only a subset is needed (eg: build.rs
) all default features can be
be disabled.
§Optional Features
MiniJinja comes with a lot of optional features, some of which are turned on by default. If you plan on using MiniJinja in a library, please consider turning off all default features and to opt-in explicitly into the ones you actually need.
Configurable Features
To cut down on size of the engine some default functionality can be removed:
-
Engine Features:
builtins
: if this feature is removed the default filters, tests and functions are not implemented.macros
: when removed the{% macro %}
tag is not included.multi_template
: when removed the templates related to imports and extends are removed ({% from %}
,{% import %}
,{% include %}
, and{% extends %}
as well as{% block %}
).adjacent_loop_items
: when removed theprevitem
andnextitem
attributes of theloop
object no longer exist. Removing this feature can provide faster template execution when a lot of loops are involved.unicode
: when added unicode identifiers are supported and thesort
filter’s case insensitive comparison changes to using unicode and not ASCII rules. Without this features only ASCII identifiers can be used for variable names and attributes.serde
: enables or disables serde support. In current versions of MiniJinja it’s not possible to disable serde but it will become possible. To prevent breakage, MiniJinja warns if this feature is disabled.
-
Rust Functionality:
debug
: if this feature is removed some debug functionality of the engine is removed as well. This mainly affects the quality of error reporting.deserialization
: when removed this disables deserialization support for theValue
type, removes theViaDeserialize
type and the error type no longer implementsserde::de::Error
.std_collections
: if this feature is removed someObject
implementations for standard library collections are removed. Only the ones needed for the engine to function itself are retained.
There are some additional features that provide extra functionality:
fuel
: enables thefuel
feature which makes the engine track fuel consumption which can be used to better protect against expensive templates.loader
: enables owned and dynamic template loading of templates.custom_syntax
: when this feature is enabled, custom delimiters are supported by the parser.preserve_order
: When enable the internal value implementation uses an indexmap which preserves the original order of maps and structs.json
: When enabled thetojson
filter is added as builtin filter as well as the ability to auto escape viaAutoEscape::Json
.urlencode
: When enabled theurlencode
filter is added as builtin filter.loop_controls
: enables the{% break %}
and{% continue %}
loop control flow tags.
Performance and memory related features:
stacker
: enables automatic stack growth which permits much larger levels of recursion at runtime. This does not affect the maximum recursion at parsing time which is always limited.speedups
: enables all speedups, in particular it turns on thev_htmlescape
dependency for faster HTML escaping.key_interning
: if this feature is enabled the automatic string interning in the value type is enabled. This feature used to be turned on by default but has negative performance effects in newer versions of MiniJinja since a lot of the previous uses of key interning are no longer needed. Enabling it however cuts down on memory usage slightly in certain scenarios by interning all string keys used in dynamic map values.
Internals:
unstable_machinery
: exposes an unstable internal API (no semver guarantees) to parse templates and interact with the engine internals. If you need this functionality, please leave some feedback on GitHub.
Modules§
- Filter functions and abstractions.
- Global functions and abstractions.
- Documents the syntax for templates.
- Test functions and abstractions.
- Provides a dynamic value type abstraction.
Macros§
- An utility macro to create arguments for function calls.
- Creates a template context from keys and values or merging in another value.
- A macro similar to
format!
but that uses MiniJinja for rendering.
Structs§
- An abstraction that holds the engine configuration.
- Represents template errors.
- A handle to a compiled expression.
- Helper to HTML escape a string.
- An abstraction over
fmt::Write
for the rendering. - Provides access to the current execution state of the engine.
- Represents a handle to a template.
- Represents a dynamically typed value in the template engine.
Enums§
- Controls the autoescaping behavior.
- An enum describing the error kind.
- Defines the behavior of undefined values in the engine.
Functions§
- The default logic for auto escaping based on file extension.
- The default formatter.
- Helper to load templates from a given directory.