Use

Global helper functions should be used to enhance stache with useful functionality common to most of your application. Examples of custom helpers might include:

• Converting a raw Date to a more user friendly timestamp. {{ timestamp(birthday) }}
• Internationalization. {{ i18n('Hello') }}
• Convert markdown into HTML. {{ markdown(comment) }}

Stache includes a number of built-in helpers, but custom helpers can be added as well.

You can register your own global helper with the addHelper or addLiveHelper methods.

addHelper calls the registered helper function with values, while addLiveHelper calls the registered helper function with computes if observable data is passed. addHelper is easier to use for basic helper functionality.

Localization is a good example of a custom helper you might implement in your application. The below example takes a given key and returns the localized value using jQuery Globalize.

stache.addHelper( "l10n", function( str, options ) {
    return typeof Globalize !== "undefined" ?
        Globalize.localize( str ) :
        str;
} );

In the template, invoke the helper by calling the helper name followed by any additional arguments.

<!-- Template -->
<span>{{ l10n('mystring') }}</span>

<!-- Result -->
<span>my string localized</span>

Helper Arguments

The type of arguments passed to a addHelper function depends on how the helper was called and the values passed to the helper. If the helper is called:

• directly within the magic tags like {{ helper() }}, it will be called with an additional helperOptions argument.
• within another expression like {{ outer( helper() ) }}, it will be called with the arguments visible from stache.

The following demonstrates this:

import {stache} from "can";

stache.addHelper( "argumentsLength", function() {
    return arguments.length;
} );

stache.addHelper( "echo", function(value) {
    return value;
} );

var frag = stache(`
    <p>{{ argumentsLength(0,1) }} should be 3</p>
    <p>{{ echo( argumentsLength(0,1) ) }} should be 2</p>
`)();

document.body.append(frag);

Evaluating Helpers

If you want to use a helper with a {{#expression}} tag, you should call options.fn(context) in your return statement. This will return a document fragment or string with the resulting evaluated subsection.

Similarly, you can call options.inverse(context) to evaluate the template between an {{else}} tag and the closing tag.

For example, when a route matches the string passed to our routing helper it will show/hide the text.

import {stache, ObservableObject} from "can";

stache.addHelper( "isReady", ( status, options ) => {

    if ( ["new","backlog"].indexOf(status) !== -1 ) {
        return options.fn();
    } else {
        return options.inverse();
    }
} );

var data = new ObservableObject({status: "new"});
var frag = stache(`
    {{# isReady(status) }}
        I am ready.
    {{else}}
        Wait!
    {{/ isReady }}

    <select value:bind="status">
        <option>new</option>
        <option>backlog</option>
        <option>assigned</option>
        <option>complete</option>
    </select>
`)(data);

document.body.append(frag);

Advanced Helpers

Helpers can be passed normal objects, native objects like numbers and strings, as well as a hash object. The hash object will be an object literal containing all ending arguments using the key=value syntax. The hash object will be provided to the helper as options.hash. Additionally, when using {{#expression}} tags with a helper, you can set a custom context by passing the object instead of this.

stache.addHelper( "exercise", ( group, action, num, options ) => {
    if ( group && group.length > 0 && action && num > 0 ) {
        return options.fn( {
            group: group,
            action: action,
            where: options.hash.where,
            when: options.hash.when,
            num: num
        } );
    } else {
        return options.inverse( this );
    }
} );

{{#exercise(pets, 'walked', 3, where='around the block' when=time)}}
    Along with the {{#group}}{{.}}, {{/group}}
    we {{action}} {{where}} {{num}} times {{when}}.
{{else}}
    We were lazy today.
{{/exercise}}

{
    pets: [ "cat", "dog", "parrot" ],
    time: "this morning"
}

This would output:

Along with the cat, dog, parrot, we walked around the block
3 times this morning.

Whereas an empty data object would output:

We were lazy today.