README.md
1handlebars-rust
2===============
3
4[Handlebars templating language](https://handlebarsjs.com) implemented
5in Rust and for Rust.
6
7Handlebars-rust is the template engine that renders the official Rust website
8[rust-lang.org](https://www.rust-lang.org), [its
9book](https://doc.rust-lang.org/book/).
10
11[](https://travis-ci.org/sunng87/handlebars-rust)
12[](https://crates.io/crates/handlebars)
13[](https://crates.io/crates/handlebars)
14[](./LICENSE)
15[](https://docs.rs/crate/handlebars/)
16
17[](https://liberapay.com/Sunng/donate)
18
19## Getting Started
20
21### Quick Start
22
23```rust
24use handlebars::Handlebars;
25use serde_json::json;
26
27fn main() -> Result<(), Box<dyn Error>> {
28 let mut reg = Handlebars::new();
29 // render without register
30 println!(
31 "{}",
32 reg.render_template("Hello {{name}}", &json!({"name": "foo"}))?
33 );
34
35 // register template using given name
36 reg.register_template_string("tpl_1", "Good afternoon, {{name}}")?;
37 println!("{}", reg.render("tpl_1", &json!({"name": "foo"}))?);
38
39 Ok(())
40}
41```
42
43### Code Example
44
45If you are not familiar with [handlebars language
46syntax](https://handlebarsjs.com), it is recommended to walk through
47their introduction first.
48
49Examples are provided in source tree to demo usage of various api.
50
51* [quick](https://github.com/sunng87/handlebars-rust/blob/master/examples/quick.rs)
52 the very basic example of registry and render apis
53* [render](https://github.com/sunng87/handlebars-rust/blob/master/examples/render.rs)
54 how to define custom helpers with function, trait impl or macro, and also how
55 to use custom helpers.
56* [render_file](https://github.com/sunng87/handlebars-rust/blob/master/examples/render_file.rs)
57 similar to render, but render to file instead of string
58* [partials](https://github.com/sunng87/handlebars-rust/blob/master/examples/partials.rs)
59 template inheritance with handlebars
60* [decorator](https://github.com/sunng87/handlebars-rust/blob/master/examples/decorator.rs)
61 how to use decorator to change data or define custom helper
62* [script](https://github.com/sunng87/handlebars-rust/blob/master/examples/script.rs)
63 how to define custom helper with rhai scripting language,
64 just like using javascript for handlebarsjs
65* [error](https://github.com/sunng87/handlebars-rust/blob/master/examples/error.rs)
66 simple case for error
67* [dev_mode](https://github.com/sunng87/handlebars-rust/blob/master/examples/dev_mode.rs)
68 a web server hosts handlebars in `dev_mode`, you can edit the template and see the change
69 without restarting your server.
70
71## Minimum Rust Version Policy
72
73Handlebars will track Rust nightly and stable channel. When dropping
74support for previous stable versions, I will bump **major** version
75and clarify in CHANGELOG.
76
77## Document
78
79[Rust doc](https://docs.rs/crate/handlebars/).
80
81## Changelog
82
83Changelog is available in the source tree named as `CHANGELOG.md`.
84
85## Contributor Guide
86
87Any contribution to this library is welcomed. To get started into
88development, I have several [Help
89Wanted](https://github.com/sunng87/handlebars-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
90issues, with the difficulty level labeled. When running into any problem,
91feel free to contact me on github.
92
93I'm always looking for maintainers to work together on this library,
94let me know (via email or anywhere in the issue tracker) if you
95want to join.
96
97## Why (this) Handlebars?
98
99Handlebars is a real-world templating system that you can use to build
100your application without pain.
101
102### Features
103
104#### Isolation of Rust and HTML
105
106This library doesn't attempt to use some macro magic to allow you to
107write your template within your rust code. I admit that it's fun to do
108that but it doesn't fit real-world use cases.
109
110#### Limited but essential control structures built-in
111
112Only essential control directives `if` and `each` are built-in. This
113prevents you from putting too much application logic into your template.
114
115#### Extensible helper system
116
117You can write your own helper with Rust! It can be a block helper or
118inline helper. Put your logic into the helper and don't repeat
119yourself.
120
121A helper can be as a simple as a Rust function like:
122
123```rust
124handlebars_helper!(hex: |v: i64| format!("0x{:x}", v));
125
126/// register the helper
127handlebars.register_helper("hex", Box::new(hex));
128```
129
130And using it in your template:
131
132```handlebars
133{{hex 16}}
134```
135
136By default, handlebars-rust ships [additional helpers](https://github.com/sunng87/handlebars-rust/blob/master/src/helpers/helper_boolean.rs#L5)
137(compared with original js version)
138that is useful when working with `if`.
139
140With `script_helper` feature flag enabled, you can also create helpers
141using [rhai](https://github.com/jonathandturner/rhai) script, just like JavaScript
142for handlebars-js. This feature was in early stage. Its API was limited at the
143moment, and can change in future.
144
145#### Template inheritance
146
147Every time I look into a templating system, I will investigate its
148support for [template
149inheritance](https://docs.djangoproject.com/en/1.9/ref/templates/language/#template-inheritance).
150
151Template include is not sufficient for template reuse. In most cases
152you will need a skeleton of page as parent (header, footer, etc.), and
153embed your page into this parent.
154
155You can find a real example of template inheritance in
156`examples/partials.rs` and templates used by this file.
157
158#### Auto-reload in dev mode
159
160By turning on `dev_mode`, handlebars auto reloads any template and scripts that
161loaded from files or directory. This can be handy for template development.
162
163#### WebAssembly compatible
164
165Handlebars 3.0 can be used in WebAssembly projects.
166
167## Related Projects
168
169### Web frameworks
170
171* Iron: [handlebars-iron](https://github.com/sunng87/handlebars-iron)
172* Rocket: [rocket/contrib](https://api.rocket.rs/v0.4/rocket_contrib/templates/index.html)
173* Warp: [handlebars
174 example](https://github.com/seanmonstar/warp/blob/master/examples/handlebars_template.rs)
175* Tower-web: [Built-in](https://github.com/carllerche/tower-web)
176* Actix: [handlebars
177 example](https://github.com/actix/examples/blob/master/template_engines/handlebars/src/main.rs)
178* Tide: [tide-handlebars](https://github.com/No9/tide-handlebars)
179
180### Adopters
181
182The
183[adopters](https://github.com/sunng87/handlebars-rust/wiki/Adopters)
184page lists projects that uses handlebars for part of their
185functionalities.
186
187### Extensions
188
189The
190[extensions](https://github.com/sunng87/handlebars-rust/wiki/Extensions)
191page has libraries that provide additional helpers, decorators and
192outputs to handlebars-rust, and you can use in your own projects.
193
194## License
195
196This library (handlebars-rust) is open sourced under the MIT License.
197
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}