handlebars-rust
Rust templating with Handlebars templating language.
Getting Started
Quick Start
extern crate handlebars;
extern crate serde_json;
use Handlebars;
Note that I use unwrap
here which is not recommended in your real code.
Code Example
If you are not familiar with handlebars language syntax, it is recommended to walk through their introduction first.
Check render
example in the source tree. The example shows you how
to:
- Create a
Handlebars
registry 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 current API.
From 0.26, Serde JSON is the default type system
for this library. The data you pass to handlebars template must
implements the Serialize
trait. Note that we don't actually
serialize data to JSON string, we just use the JSON type: number,
boolean and etc.
Rustc_serialize is now officially deprecated. If your application is
still using it, you need to use handlebars-rust 0.25.*
.
Documents
Changelog
Change log is available in the source tree named as CHANGELOG.md
.
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 case.
Limited but essential control structure built-in
Only essential control directive if
and each
were built-in. This
prevents you to put 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 you logic into the helper and don't repeat yourself.
A helper can be as a simple as a Rust function like:
/// register the helper
handlebars.register_helper;
And using it in your template:
{{hex my_value}}
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 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.
WebAssembly compatible
You can use this handlebars implementation in your rust project that compiles to WebAssembly. Checkout my fork of todomvc demo.
Limitations
- This implementation is not fully compatible with the original
javascript version. Specifically, mustache list iteration and null
check doesn't work. But you can use
#each
and#if
for same behavior. - You will need to make your data
Serializable
on serde. We don't actually serialize data into JSON string or similar. However, we use JSON data type system in template render process.
Handlebars-js features supported in Handlebars-rust
- Expression / Block Helpers
- Built-in helpers
- each
- if
- with
- lookup
- log
- Custom helper
- Parameter and hashes for helper, block params
- Partials, include, template inheritance
- Omitting whitespace with
~
- Subexpression
{{(foo bar)}}
- Json expression
a.b.[0]
anda.b.[c]
- RawHelper syntax
{{{{raw-helper}}}}...{{{{/raw-helper}}}}
- Decorator, implemented in Rust way
JavaScript implementation features we don't have
- Mustache block (use
if
/each
instead) - Chained else
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.
Handlebars for Web Frameworks
- Iron: handlebars-iron
- Rocket: rocket/contrib
Using handlebars-rust?
Add your project to our adopters.
License
This library (handlebars-rust) is open sourced under MIT License.