handlebars-rust

A Decorator is used to modify the rendering environment at a specific point in a template. Decorators are invoked using the {{*name}} syntax.

Currently, decorators share the same definition as helpers, but they are intended for side effects that affect subsequent rendering, such as:

1. Updating context data: Changing the data available to the template for the remainder of the render process.
2. Defining local helpers: Overriding or registering new helper behaviors that are only active from the decorator's position until the end of the template (or until unregistered).

To implement a decorator, you can either implement the DecoratorDef trait or simply pass a closure/function that matches the expected signature.

use handlebars::*;

// Example: A decorator that updates context data
fn update_data<'reg: 'rc, 'rc>(_: &Decorator, _: &Handlebars, ctx: &Context, rc: &mut RenderContext) 
        -> Result<(), RenderError> {
    let mut new_ctx = ctx.clone();
    {
        let mut data = new_ctx.data_mut();
        if let Some(ref mut m) = data.as_object_mut() {
            m.insert("hello".to_string(), to_json("world"));
        }
    }
    rc.set_context(new_ctx);
    Ok(())
}

The Registry allows you to control how missing data or missing helpers are handled using set_strict_mode and by registering a custom helperMissing helper.

• Strict Mode: When set_strict_mode(true) is called, attempting to render a template with a missing key (that is neither in the context nor registered as a helper) will return an Err.
• Custom helperMissing: You can register a custom helper named helperMissing to define a fallback behavior (e.g., printing a specific message) when a helper or key cannot be resolved. This is only effective when strict mode is disabled.

Note: By default, if a key is not found in the context and no helper exists, the engine outputs nothing.

// Enable strict mode to catch missing keys as errors
r.set_strict_mode(true);

// Register a custom fallback for missing helpers/keys
r.register_helper(
    "helperMissing",
    Box::new(|h, _, _, _, out| {
        let name = h.name();
        write!(out, "{name} not resolved")?;
        Ok(())
    }),
);

To create custom helpers in handlebars-rust, you can implement the HelperDef trait. There are two primary ways to define a helper depending on whether you need to return a value (composable) or write directly to the output (non-composable).

1. Inline Helpers (Composable)

Use call_inner to implement a helper that returns a ScopedJson. These are ideal for subexpressions (e.g., {{foo value=(bar 1)}}) because the returned value maintains its type information. If you only implement call_inner, the default call implementation handles escaping and outputting the result.

2. Complex/Output Helpers (Non-composable)

Implement the call method directly if you need access to the Output trait to write custom strings or render child templates (like #if or #each). Note that helpers defined this way are not easily composable in subexpressions because they write raw strings to the output, and the engine must attempt to parse them back as JSON.

3. Bare Functions

You can use a simple function as a helper without implementing a struct, thanks to the unboxed_closure support for functions matching the helper signature.

/// Define an inline helper
use handlebars::*;

fn upper(h: &Helper< '_>, _: &Handlebars<'_>, _: &Context, rc:
    &mut RenderContext<'_, '_>, out: &mut dyn Output) 
    -> HelperResult {
   // get parameter from helper or throw an error
   let param = h.param(0).and_then(|v| v.value().as_str()).unwrap_or("");
   out.write(param.to_uppercase().as_ref())?;
   Ok(())
}

/// Define block helper
fn dummy_block<'reg, 'rc>(
    h: &Helper<'rc>,
    r: &'reg Handlebars<'reg>,
    ctx: &'rc Context,
    rc: &mut RenderContext<'reg, 'rc>,
    out: &mut dyn Output,
) -> HelperResult {
    h.template()
        .map(|t| t.render(r, ctx, rc, out))
        .unwrap_or(Ok(()))
}

/// Define helper function using macro
handlebars_helper!(plus: |x: i64, y: i64| x + y);

let mut hbs = Handlebars::new();
hbs.register_helper("plus", Box::new(plus));