Rust templating with Handlebars templating language.
This library works on stable Rust 1.4.0 and above. In most time, it also works on beta and nightly channel.
Check render
example in the source tree. The example shows you how
to:
Handlebars
registry and register the template from files;HelperDef
, and register 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 current API.
From 0.13, you can use either rustc_serialize
or serde
for your
data type. By default we use ToJson
from rustc_serialize
to
convert your data into handlebars internal types. If you use serde
framework in your project, you can enable serde_type
feature of this
crate and we will use Serialize
from serde
to convert.
Change log is available in the source tree named as CHANGELOG.md
.
Handlebars is a real-world templating system that you can use to build your application without pain.
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 case.
Only essential control directive if
and each
were built-in. This
prevents you to put too much application logic into your template.
You can write your own helper with Rust! It can be a block helper or inline helper. Put you logic into the helper and don't repeat yourself.
A helper can be as a simple as a Rust function like:
```rust fn hexhelper (: &Context, h: &Helper, : &Handlebars, rc: &mut RenderContext) -> Result<(), RenderError> { // just for example, add error check for unwrap let param = h.param(0).unwrap().value(); let rendered = format!("0x{:x}", param.asu64().unwrap()); try!(rc.writer.write(rendered.intobytes().asref())); Ok(()) }
/// register the helper handlebars.registerhelper("hex", Box::new(hexhelper)); ```
And using it in your template:
handlebars
{{hex my_value}}
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 case you will need a skeleton of page as parent (header, footer, etc.), and embed you page into this parent.
You can find a real example for template inheritance in
examples/partials.rs
, and templates used by this file.
From 0.21 we support Handlebars 4.0 partial syntax with crate feature
partial4
. Original partial syntax via block
, partial
helpers are
still support at the moment. But no doubt partial4
will become
default in future releases. There is no rust code difference between
the syntax, just template change. Examples can be find in
examples/partials.rs
.
#each
and #if
for same
behavior.ToJson
-able, so we can render
it. If you were on nightly channel, we have a syntax
extension to generate
default ToJson
implementation for you. If you use
serde, you can enable
serde_type
feature of handlebars-rust and add #derive[Serialize]
for your types.>
partial4
)~
{{(foo bar)}}
a.b.[0]
and a.b.[c]
{{{{raw-helper}}}}...{{{{/raw-helper}}}}
if
/each
instead)Feel free to report an issue if you find something broken. We aren't going to implement all features of handlebars-js, but we should have a workaround for cases we don't support.
I have started another project handlebars-iron for the Iron web framework.
Add your project to our adopters.
This library (handlebars-rust) is open sourced under MIT License.
Ning Sun (sunng@about.me)