diff options
Diffstat (limited to 'vendor/handlebars/README.md')
| -rw-r--r-- | vendor/handlebars/README.md | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/vendor/handlebars/README.md b/vendor/handlebars/README.md new file mode 100644 index 000000000..4a9c41827 --- /dev/null +++ b/vendor/handlebars/README.md @@ -0,0 +1,196 @@ +handlebars-rust +=============== + +[Handlebars templating language](https://handlebarsjs.com) implemented +in Rust and for Rust. + +Handlebars-rust is the template engine that renders the official Rust website +[rust-lang.org](https://www.rust-lang.org), [its +book](https://doc.rust-lang.org/book/). + +[](https://travis-ci.org/sunng87/handlebars-rust) +[](https://crates.io/crates/handlebars) +[](https://crates.io/crates/handlebars) +[](./LICENSE) +[](https://docs.rs/crate/handlebars/) + +[](https://liberapay.com/Sunng/donate) + +## Getting Started + +### Quick Start + +```rust +use handlebars::Handlebars; +use serde_json::json; + +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"}))?); + + Ok(()) +} +``` + +### Code Example + +If you are not familiar with [handlebars language +syntax](https://handlebarsjs.com), it is recommended to walk through +their introduction first. + +Examples are provided in source tree to demo usage of various api. + +* [quick](https://github.com/sunng87/handlebars-rust/blob/master/examples/quick.rs) + the very basic example of registry and render apis +* [render](https://github.com/sunng87/handlebars-rust/blob/master/examples/render.rs) + how to define custom helpers with function, trait impl or macro, and also how + to use custom helpers. +* [render_file](https://github.com/sunng87/handlebars-rust/blob/master/examples/render_file.rs) + similar to render, but render to file instead of string +* [partials](https://github.com/sunng87/handlebars-rust/blob/master/examples/partials.rs) + template inheritance with handlebars +* [decorator](https://github.com/sunng87/handlebars-rust/blob/master/examples/decorator.rs) + how to use decorator to change data or define custom helper +* [script](https://github.com/sunng87/handlebars-rust/blob/master/examples/script.rs) + how to define custom helper with rhai scripting language, + just like using javascript for handlebarsjs +* [error](https://github.com/sunng87/handlebars-rust/blob/master/examples/error.rs) + simple case for error +* [dev_mode](https://github.com/sunng87/handlebars-rust/blob/master/examples/dev_mode.rs) + a web server hosts handlebars in `dev_mode`, you can edit the template and see the change + without restarting your server. + +## Minimum Rust Version Policy + +Handlebars will track Rust nightly and stable channel. When dropping +support for previous stable versions, I will bump **major** version +and clarify in CHANGELOG. + +## Document + +[Rust doc](https://docs.rs/crate/handlebars/). + +## 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](https://github.com/sunng87/handlebars-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +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: + +```rust +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: + +```handlebars +{{hex 16}} +``` + +By default, handlebars-rust ships [additional helpers](https://github.com/sunng87/handlebars-rust/blob/master/src/helpers/helper_boolean.rs#L5) +(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](https://github.com/jonathandturner/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](https://docs.djangoproject.com/en/1.9/ref/templates/language/#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. + +## Related Projects + +### Web frameworks + +* Iron: [handlebars-iron](https://github.com/sunng87/handlebars-iron) +* Rocket: [rocket/contrib](https://api.rocket.rs/v0.4/rocket_contrib/templates/index.html) +* Warp: [handlebars + example](https://github.com/seanmonstar/warp/blob/master/examples/handlebars_template.rs) +* Tower-web: [Built-in](https://github.com/carllerche/tower-web) +* Actix: [handlebars + example](https://github.com/actix/examples/blob/master/template_engines/handlebars/src/main.rs) +* Tide: [tide-handlebars](https://github.com/No9/tide-handlebars) + +### Adopters + +The +[adopters](https://github.com/sunng87/handlebars-rust/wiki/Adopters) +page lists projects that uses handlebars for part of their +functionalities. + +### Extensions + +The +[extensions](https://github.com/sunng87/handlebars-rust/wiki/Extensions) +page has libraries that provide additional helpers, decorators and +outputs to handlebars-rust, and you can use in your own projects. + +## License + +This library (handlebars-rust) is open sourced under the MIT License. |