Module bracket::helper[−][src]

Expand description

Helper trait and types for the default set of helpers.

The Helper Trait should be implemented for custom helpers which can then be added to a registry.

Helper call() functions accept three arguments:

rc The active renderer.
ctx Helper arguments and hash parameters.
template Inner template when called as a block.

The renderer can be used to render inner templates when a helper is called as a block and provides functions for writing to the output destination.

The context is used to access the arguments and hash parameters and may also be used for type assertions.

When a helper is called as a block the optional template node will be Some. Raw helpers can access the inner text using text().

To determine how a helper was invoked requires checking for an inner template or raw text; if neither is available it is a statement:

if let Some(node) = template {
    // Helper was invoked as a block `{{#helper}}...{{/helper}}`
} else if let Some(text) = ctx.text() {
    // Helper was invoked as a raw block `{{{{helper}}}}...{{{{/helper}}}}`
} else {
    // Helper was invoked as a statement `{{helper}}`
}

Type Assertions

Type assertions let us verify the type of helper arguments and hash parameters before we use them.

The arity() method is used to assert on argument length.

Use try_get() to get an argument and verify it is an expected type.

Use try_param() to get a hash parameter and verify it is an expected type.

Return Values

The signature for helper return values is HelperValue which requires that the call() function returns an optional Value.

A return value is useful when a helper is invoked as a statement; when invoked as a block return Ok(None).

If a statement helper is used for side-effects (such as the Log helper) then return Ok(None).

Local Helpers

Local helpers are defined on rc using register_local_helper() and live for the lifetime of the parent helper call.

They must implement the LocalHelper Trait which has an additional bounds on Clone.

Render

To render an inner template when a helper is called as a block use template() which will respect the current whitespace trim hints:

if let Some(node) = template {
   rc.template(node)?;
}

To buffer() the content of an inner template into a string:

if let Some(node) = template {
   let content = rc.buffer(node)?;
}

Raw Paths

Most of the time helpers operate on the Value type but sometimes it is useful to access the underlying raw string so that helpers can access paths directly.

To allow either a quoted string or a raw path and access it as Value::String regardless use get_fallback() and param_fallback().

For example an include helper might want to accept raw paths or string values:

ctx.arity(1..1)?;
if let Some(include_file) = ctx.get_fallback(0) {
    let include_file = ctx.try_value(include_file, &[Type::String])?
        .as_str()
        .unwrap();
    // Do something with the include file path
}

Alternatively to branch and treat paths differently to string values we can use the missing() and missing_param() functions to check whether a value was missing and use the raw path when it is missing.

For example a markdown helper may want to accept inline markdown when the argument is a string literal otherwise load content from a raw path when the value is missing:

if let Some(arg) = ctx.get(0) {
    if let Some(value) = ctx.missing(0) {
        // Missing values are always coerced to `Value::String`!
        if let Value::String(value) = value {
            // Do something with the raw path value
        }
    } else {
        let param = ctx.try_value(arg, &[Type::String])?.as_str().unwrap();
        // Do something with the string literal value
    }
}