Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sunng87/handlebars-iron

Handlebars middleware for Iron web framework
https://github.com/sunng87/handlebars-iron

handlebars iron rust template-engine webdevelopment

Last synced: 4 days ago
JSON representation

Handlebars middleware for Iron web framework

Awesome Lists containing this project

README 

        
handlebars-iron

===============



[Handlebars](https://github.com/sunng87/handlebars-rust) middleware

for the [Iron web framework](http://ironframework.io).



[![Build

Status](https://travis-ci.org/sunng87/handlebars-iron.svg?branch=master)](https://travis-ci.org/sunng87/handlebars-iron)

[![](http://meritbadge.herokuapp.com/handlebars-iron)](https://crates.io/crates/handlebars-iron)



This library, together with handlebars, iron and hyper, works on

both stable and nightly rust.



Both iron and handlebars has backward-incompatible change during 0.x

releases. So you will need to choose handlebars-iron version based on

those two versions you were using:



handlebars-iron | handlebars | iron

--------------- | ---------- | ---

0.14.x | 0.16.x | 0.2.x

0.15.x | 0.18.x | 0.3.x

0.16.0 | 0.19.x | 0.3.x

0.17.x | 0.19.x | 0.4.x

0.18.x | 0.20.x (serde 0.8) | 0.4.x

0.19.x | 0.22.x | 0.4.x

0.20.x | 0.23.x | 0.4.x

0.21.x | 0.24.x | 0.4.x

0.22.x | 0.24.x | 0.5.x

0.23.x | 0.25.x (serde 0.9) | 0.5.x

0.24.x | 0.26.x (serde 1.0) | 0.5.x

0.25.x | 0.29.x | 0.5.x

0.26.x | 0.32.x | 0.6.x

0.27.x | 1.x | 0.6.x

0.28.x | 2.x | 0.6.x

0.29.x | 3.x | 0.6.x



## Usage



Add HandlebarsEngine to your Iron middleware chain as an "after"

middleware.



```rust

  /// HandlebarsEngine will look up all files with "./examples/templates/**/*.hbs"

  let mut hbse = HandlebarsEngine::new();

  hbse.add(Box::new(DirectorySource::new("./examples/templates/", ".hbs")));



  // load templates from all registered sources

  if let Err(r) = hbse.reload() {

    panic!("{}", r);

  }



  chain.link_after(hbse);

```



If you want register your own custom helpers, you can initialize the

`HandlebarsEngine` from a custom `Handlebars` registry.



```rust

  let mut hbse = HandlebarsEngine::new();

  hbse.add(Box::new(DirectorySource::new("./examples/templates/", ".hbs")));

  hbse.handlebars_mut().register_helper("helper", my_helper);



  // load templates from all registered sources

  if let Err(r) = hbse.reload() {

    panic!("{}", r);

  }



  chain.link_after(hbse);

```



You can find more information about custom helper in [handlebars-rust

document](https://github.com/sunng87/handlebars-rust#extensible-helper-system).



In your handler, set `Template` to response. As required by

Handlebars-rust, your data should impl `serde::Serialize`.



For `DirectorySource`, handlebars engine will walk the directory

specified by `prefix`, try to register all templates matches the

suffix, and extract its name as template name. For instance,

`./examples/templates/some/path/index.hbs` will be registered as

`some/path/index`.



```rust

/// render data with "index" template

/// that is "./examples/templates/index.hbs"

fn hello_world(_: &mut Request) -> IronResult {

    let mut resp = Response::new();



    let data = ...

    resp.set_mut(Template::new("index", data)).set_mut(status::Ok);

    Ok(resp)

}

```



By using `Template::with` You can also render some template without

actually register it. But this is not recommended because template

string needs to be parsed every time. Consider using a `MemorySource`

if possible.



```rust

/// render data with "index" template

/// that is "./examples/templates/index.hbs"

fn hello_world(_: &mut Request) -> IronResult {

    let mut resp = Response::new();



    let data = ...

    resp.set_mut(Template::with("
{{title}}
", data)).set_mut(status::Ok);

    Ok(resp)

}

```



Since this is simple library, you may run this

[example](https://github.com/sunng87/handlebars-iron/blob/master/examples/server.rs)

with `RUST_LOG=handlebars_iron=info cargo run --example server`

first, and

[documentation](https://docs.rs/crate/handlebars-iron)

then.



Rust and its ecosystem are still in early stage, this

project might been broken for various reasons. I will try my best to

keep this library compiles with latest Rust nightly before the 1.0

final release. If you find anything bad, pull requests and issue reporting

are always welcomed.



## Live reload



During development you may want to live-reload your templates without

having to restart your web server. Here comes the live-reload

feature.



Since live-reload may only be useful in development phase, we have

made it a optional feature. In order to enable it, you will need to

add feature `watch` in your cargo declaration:



```toml

[features]

## create a feature in your app

watch = ["handlebars-iron/watch"]



[dependencies]

handlebars-iron = ...

```



Check `examples/watch_server.rs` for further information. To test it:

`RUST_LOG=handlebars_iron=info cargo run --example watch_server

--features watch`.



## Using handlebars-iron?



Add your project to our

[adopters](https://github.com/sunng87/handlebars-rust/wiki/adopters).



## License



MIT, of course.