[−][src]Crate handlebars

Handlebars

Handlebars is a modern and extensible templating solution originally created in the JavaScript world. It's used by many popular frameworks like Ember.js and Chaplin. It's also ported to some other platforms such as Java.

And this is handlebars Rust implementation, designed for general purpose text generation.

Quick Start

use std::collections::BTreeMap;
use handlebars::Handlebars;

fn main() {
  // create the handlebars registry
  let mut handlebars = Handlebars::new();

  // register the template. The template string will be verified and compiled.
  let source = "hello {{world}}";
  assert!(handlebars.register_template_string("t1", source).is_ok());

  // Prepare some data.
  //
  // The data type should implements `serde::Serialize`
  let mut data = BTreeMap::new();
  data.insert("world".to_string(), "世界!".to_string());
  assert_eq!(handlebars.render("t1", &data).unwrap(), "hello 世界!");
}

In this example, we created a template registry and registered a template named t1. Then we rendered a BTreeMap with an entry of key world, the result is just what we expected.

I recommend you to walk through handlebars.js' intro page if you are not quite familiar with the template language itself.

Rational: 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 (and feel cool) to do that but it doesn't fit real-world use case in my opinion.

Limited but essential control structure built-in

Only essential control directive if and each were built-in. This prevents you to put 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 you logic into the helper and don't repeat yourself.

Template inheritance

Every time I look into a templating system, I will investigate its support for template inheritance.

Template include is not enough. In most case you will need a skeleton of page as parent (header, footer, etc.), and embed you page into this parent.

You can find a real example for template inheritance in examples/partials.rs, and templates used by this file.

Strict mode

Handlebars, the language designed to work with JavaScript, has no strict restriction on accessing non-existed fields or index. It generates empty string for such case. However, in Rust we want a little bit strict sometime.

By enabling strict_mode on handlebars:

handlebars.set_strict_mode(true);

You will get a RenderError when accessing fields that not exists.

Limitations

Compatibility with JavaScript version

This implementation is not fully compatible with the original javascript version.

First of all, mustache block is not supported. I suggest you to use #if and #each for same functionality.

There are some other minor features missing:

Feel free to fire an issue on github if you find missing features.

Static typed

As a static typed language, it's a little verbose to use handlebars. Handlebars templating language is designed against JSON data type. In rust, we will convert user's structs, vectors or maps to JSON type in order to use in template. You have to make sure your data implements the Serialize trait from the Serde project.

Usage

Template Creation and Registration

Templates are created from String and registered to Handlebars with a name.


use handlebars::Handlebars;

  let mut handlebars = Handlebars::new();
  let source = "hello {{world}}";

  assert!(handlebars.register_template_string("t1", source).is_ok())

On registration, the template is parsed, compiled and cached in the registry. So further usage will benefit from the one-time work. Also features like include, inheritance that involves template reference requires you to register those template first with a name so the registry can find it.

If you template is small or just to experiment, you can use render_template API without registration.

use handlebars::Handlebars;
use std::collections::BTreeMap;

  let mut handlebars = Handlebars::new();
  let source = "hello {{world}}";

  let mut data = BTreeMap::new();
  data.insert("world".to_string(), "世界!".to_string());
  assert_eq!(handlebars.render_template(source, &data)?, "hello 世界!".to_owned());

Rendering Something

Since handlebars is originally based on JavaScript type system. It supports dynamic features like duck-typing, truthy/falsey values. But for a static language like Rust, this is a little difficult. As a solution, we are using the serde_json::value::Value internally for data rendering.

That means, if you want to render something, you have to ensure the data type implements the serde::Serialize trait. Most rust internal types already have that trait. Use #derive[Serialize] for your types to generate default implementation.

You can use default render function to render a template into String. From 0.9, there's renderw to render text into anything of std::io::Write.


use handlebars::Handlebars;

#[derive(Serialize)]
struct Person {
  name: String,
  age: i16,
}

  let source = "Hello, {{name}}";

  let mut handlebars = Handlebars::new();
  assert!(handlebars.register_template_string("hello", source).is_ok());


  let data = Person {
      name: "Ning Sun".to_string(),
      age: 27
  };
  assert_eq!(handlebars.render("hello", &data)?, "Hello, Ning Sun".to_owned());

Or if you don't need the template to be cached or referenced by other ones, you can simply render it without registering.

use handlebars::Handlebars;

  let source = "Hello, {{name}}";

  let mut handlebars = Handlebars::new();

  let data = Person {
      name: "Ning Sun".to_string(),
      age: 27
  };
  assert_eq!(handlebars.render_template("Hello, {{name}}", &data)?,
      "Hello, Ning Sun".to_owned());

Escaping

As per the handlebars spec, output using {{expression}} is escaped by default (to be precise, the characters &"<> are replaced by their respective html / xml entities). However, since the use cases of a rust template engine are probably a bit more diverse than those of a JavaScript one, this implementation allows the user to supply a custom escape function to be used instead. For more information see the EscapeFn type and Handlebars::register_escape_fn() method.

Custom Helper

Handlebars is nothing without helpers. You can also create your own helpers with rust. Helpers in handlebars-rust are custom struct implements the HelperDef trait, concretely, the call function. For your convenience, most of stateless helpers can be implemented as bare functions.

use std::io::Write;
use handlebars::{Handlebars, HelperDef, RenderContext, Helper, Context, JsonRender, HelperResult, Output, RenderError};

// implement by a structure impls HelperDef
#[derive(Clone, Copy)]
struct SimpleHelper;

impl HelperDef for SimpleHelper {
  fn call<'reg: 'rc, 'rc>(&self, h: &Helper, _: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut Output) -> HelperResult {
    let param = h.param(0).unwrap();

    out.write("1st helper: ")?;
    out.write(param.value().render().as_ref())?;
    Ok(())
  }
}

// implement via bare function
fn another_simple_helper (h: &Helper, _: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut Output) -> HelperResult {
    let param = h.param(0).unwrap();

    out.write("2nd helper: ")?;
    out.write(param.value().render().as_ref())?;
    Ok(())
}


  let mut handlebars = Handlebars::new();
  handlebars.register_helper("simple-helper", Box::new(SimpleHelper));
  handlebars.register_helper("another-simple-helper", Box::new(another_simple_helper));
  // via closure
  handlebars.register_helper("closure-helper",
      Box::new(|h: &Helper, r: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut Output| -> HelperResult {
          let param = h.param(0).ok_or(RenderError::new("param not found"))?;

          out.write("3rd helper: ")?;
          out.write(param.value().render().as_ref())?;
          Ok(())
      }));

  let tpl = "{{simple-helper 1}}\n{{another-simple-helper 2}}\n{{closure-helper 3}}";
  assert_eq!(handlebars.render_template(tpl, &())?,
      "1st helper: 1\n2nd helper: 2\n3rd helper: 3".to_owned());

Data available to helper can be found in Helper. And there are more examples in HelperDef page.

You can learn more about helpers by looking into source code of built-in helpers.

Built-in Helpers

Template inheritance

Handlebars.js' partial system is fully supported in this implementation. Check example for details.

Re-exports

pub use self::template::Template;

Modules

template

Macros

handlebars_helper

Macro that allows you to quickly define a handlebars helper by passing a name and a closure.

Structs

Context

The context wrap data you render on your templates.

Decorator
Handlebars

The single entry point of your Handlebars templates

Helper
PathAndJson

Json wrapper that holds the Json value and reference path information

RenderContext

The context of a render call

RenderError

Error when rendering data on template.

StringWriter
TemplateError

Error on parsing template.

Enums

ScopedJson

A JSON wrapper designed for handlebars internal use case

TemplateFileError
TemplateRenderError

Traits

DecoratorDef

Decorator Definition

Evaluable

Evaluate directive or decorator

HelperDef

Helper Definition

JsonRender

Render Json data with default format

Output
Renderable

Render trait

Functions

html_escape

The default escape fn replaces the characters &"<> with the equivalent html / xml entities.

no_escape

EscapeFn that do not change any thing. Useful when using in a non-html environment.

to_json

Type Definitions

EscapeFn

This type represents an escape fn, that is a function who's purpose it is to escape potentially problematic characters in a string.

HelperResult