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