sunng87/handlebars-rust — 1.5k Stars

Topics

#handlebars #handlebars-js #rust #template-engine

Language breakdown

Rust 99.0%

JavaScript 0.6%

HTML 0.4%

Shell 0.0%

Handlebars 0.0%

▸ Files click to expand

README

handlebars-rust ===============

Handlebars templating language implemented in Rust and for Rust.

Getting Started

Quick Start

use handlebars::Handlebars;
use serde_json::json;
use std::error::Error;
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.registertemplatestring("tpl_1", "Good afternoon, {{name}}")?;     println!("{}", reg.render("tpl_1", &json!({"name": "foo"}))?);
Ok(()) }

Code Example

If you are not familiar with handlebars language syntax, it is recommended to walk through their introduction first.

Examples are provided in source tree to demo usage of various api.

quick

the very basic example of registry and render apis

render

how to define custom helpers with function, trait impl or macro, and also how to use custom helpers.

render_file

similar to render, but render to file instead of string

helper_macro

demos usage of handlebars_helper! to simplify helper development

partials

template inheritance with handlebars

decorator

how to use decorator to change data or define custom helper

script

how to define custom helper with rhai scripting language, just like using javascript for handlebarsjs

error

simple case for error

dev_mode

a web server hosts handlebars in dev_mode, you can edit the template and see the change without restarting your server.

Web Playground

We have github action to compile latest master branch into WebAssembly and serve it on github pages. You can test and verify your template with both handlebars-rust and handlebarjs.

Minimum Rust Version Policy

Handlebars will track Rust nightly and stable channel. When dropping support for previous stable versions, I will bump patch version and clarify in CHANGELOG.

Docs

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.

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 structures 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}}

By default, handlebars-rust ships additional helpers (compared with original js version) that is useful when working with if.

With script_helper feature flag enabled, you can also create helpers using rhai script, just like JavaScript for handlebars-js. This feature was in early stage. Its API was limited at the moment, and can change in future.

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.

Auto-reload in dev mode

By turning on dev_mode, handlebars auto reloads any template and scripts that loaded from files or directory. This can be handy for template development.

WebAssembly compatible

Handlebars 3.0 can be used in WebAssembly projects.

Fully scriptable

With rhai script support, you can implement your own helper with the scripting language. Together with the template lanaguage itself, template development can be fully scriptable without changing rust code.