[][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.

Features

Handlebars is a real-world templating system that you can use to build your application without pain.

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 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.

The built-in helpers like if and each were written with these helper APIs and the APIs are fully available to developers.

Template inheritance

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

Template inclusion 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 original 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:

  • Chained else #12

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

Types

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 into SerDe-Json's Value 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 dyn 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 dyn 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 dyn 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.

Script Helper

Like our Javascript counterparts, handlebars allows user to define simple helpers with a script language, rhai. This can be enabled by turning on script_helper feature flag.

A sample script:

{{percent 0.34 label="%"}}
// percent.rhai
// get first parameter from `params` array
let value = params[0];
// get key  value pair `label` from `hash` map
let label = hash["label"];

// compute the final string presentation
(value * 100).to_string() + label

A runnable example can be find in the repo.

Built-in Helpers

  • {{{{raw}}}} ... {{{{/raw}}}} escape handlebars expression within the block
  • {{#if ...}} ... {{else}} ... {{/if}} if-else block
  • {{#unless ...}} ... {{else}} .. {{/unless}} if-not-else block
  • {{#each ...}} ... {{/each}} iterates over an array or object. Handlebar-rust doesn't support mustache iteration syntax so use this instead.
  • {{#with ...}} ... {{/with}} change current context. Similar to {{#each}}, used for replace corresponding mustache syntax.
  • {{lookup ... ...}} get value from array by @index or @key
  • {{> ...}} include template with name
  • {{log ...}} log value with rust logger, default level: INFO. Currently you cannot change the level.
  • Boolean helpers that can be used in if as subexpression, for example {{#if (gt 2 1)}} ...:
    • eq
    • ne
    • gt
    • gte
    • lt
    • lte
    • and
    • or
    • not

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

debug

This macro is defined if the logging feature is set.

error

This macro is defined if the logging feature is not set.

handlebars_helper

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

info

This macro is defined if the logging feature is not set.

log

This macro is defined if the logging feature is not set.

trace

This macro is defined if the logging feature is not set.

warn

This macro is defined if the logging feature is not set.

Structs

BlockContext

A data structure holds contextual data for current block scope.

BlockParams

A map holds block parameters. The parameter can be either a value or a reference

Context

The context wrap data you render on your templates.

Decorator

Render-time Decorator data when using in a decorator definition

Handlebars

The single entry point of your Handlebars templates

Helper

Render-time Helper data when using in a helper definition

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.

TemplateError

Error on parsing template.

Enums

Path

Represents the Json path in templates.

ScopedJson

A JSON wrapper designed for handlebars internal use case

TemplateFileError

A combined error type for TemplateError and IOError

TemplateRenderError

A combined error type for TemplateError, IOError and RenderError

Traits

DecoratorDef

Decorator Definition

Evaluable

Evaluate decorator or decorator

HelperDef

Helper Definition

JsonRender

Render Json data with default format

Output

The Output API.

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

Convert any serializable data into Serde Json type

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

A type alias for Result<(), RenderError>