Popularity
7.3
Growing
Activity
8.2
Growing
427
10
66

Monthly Downloads: 101,747
Programming language: Rust
License: MIT License
Tags: Web     Templating     Handlebars    
Latest version: v2.0.2
Add another 'Handlebars' Package

README

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.

Build Status [MIT licensed](./LICENSE) Docs Donate Donate

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 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 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
~2.0.0 1.32
~1.1.0 1.30
~1.0.0 1.23

Document

Rust doc.

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.

buymeacoffee

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 can be used in WebAssembly projects with the directory source feature disabled. Adding handlebars to your project like this:

handlebars = { version = "2", features = ["no_dir_source"], default-features = false }

Handlebars for Web Frameworks

Using handlebars-rust?

Add your project to our adopters.

License

This library (handlebars-rust) is open sourced under the MIT License.


*Note that all licence references and agreements mentioned in the handlebars-rust README section above are relevant to that project's source code only.