handlebars-rust
Handlebars templating language implemented
in Rust and for Rust.
Handlebars-rust is the template engine that renders the official Rust website
rust-lang.org and its
book.
Getting Started
Quick Start
extern crate handlebars;
#[macro_use]
extern crate serde_json;
use handlebars::Handlebars;
fn main() -> Result<(), Box<dyn Error>> {
let mut reg = Handlebars::new();
// render without register
println!(
"{}",
reg.render_template("Hello {{name}}", &json!({"name": "foo"}))?
);
// register template using given name
reg.register_template_string("tpl_1", "Good afternoon, {{name}}")?;
println!("{}", reg.render("tpl_1", &json!({"name": "foo"}))?);
}
Code Example
If you are not familiar with handlebars language
syntax, it is recommended to walk through
their introduction first.
Check the render example in the source tree. The example shows you how
to:
- Create a
Handlebarsregistry and register the template from files; - Create a custom Helper with closure or struct implementing
HelperDef, and register it; - Define and prepare some data;
- Render it;
Run cargo run --example render to see results
(or RUST_LOG=handlebars=info cargo run --example render for logging
output).
Checkout examples/ for more concrete demos of the current API.
Minimum Rust Version Policy
Handlebars will track Rust nightly and stable channel. When dropping
support for previous stable versions, I will bump minor version
and clarify in CHANGELOG.
Rust compatibility table, Handlebars version range, Minimum Rust version, ---, ---, ~3.0.0, 1.32, ~2.0.0, 1.32, ~1.1.0, 1.30, ~1.0.0, 1.23, ## Document
Changelog
Changelog is available in the source tree named as CHANGELOG.md.
Contributor Guide
Any contribution to this library is welcomed. To get started into
development, I have several Help
Wanted
issues, with the difficulty level labeled. When running into any problem,
feel free to contact me on github.
I'm always looking for maintainers to work together on this library,
let me know (via email or anywhere in the issue tracker) if you
want to join.
Donations
I'm now accepting donations on liberapay
and buymeacoffee if you find my
work helpful and want to keep it going.
Why (this) Handlebars?
Handlebars is a real-world templating system that you can use to build
your application without pain.
Features
Isolation of Rust and HTML
This library doesn't attempt to use some macro magic to allow you to
write your template within your rust code. I admit that it's fun to do
that but it doesn't fit real-world use cases.
Limited but essential control structure built-in
Only essential control directives if and each are built-in. This
prevents you from putting too much application logic into your template.
Extensible helper system
You can write your own helper with Rust! It can be a block helper or
inline helper. Put your logic into the helper and don't repeat
yourself.
A helper can be as a simple as a Rust function like:
handlebars_helper!(hex:, v: i64, format!("0x{:x}", v));
/// register the helper
handlebars.register_helper("hex", Box::new(hex));
And using it in your template:
{{hex 16}}
Template inheritance
Every time I look into a templating system, I will investigate its
support for template
inheritance.
Template include is not sufficient for template reuse. In most cases
you will need a skeleton of page as parent (header, footer, etc.), and
embed your page into this parent.
You can find a real example of template inheritance in
examples/partials.rs and templates used by this file.
WebAssembly compatible
Handlebars 3.0 can be used in WebAssembly projects.
Handlebars for Web Frameworks
- Iron: handlebars-iron
- Rocket: rocket/contrib
- Warp: handlebars
example - Tower-web: Built-in
- Actix: handlebars
example
Using handlebars-rust?
Add your project to our
adopters.
License
This library (handlebars-rust) is open sourced under the MIT License.