can
Version:
MIT-licensed, client-side, JavaScript framework that makes building rich web applications easy.
1,665 lines (1,037 loc) • 37.9 kB
HTML
<!--####################################################################
THIS IS A GENERATED FILE -- ANY CHANGES MADE WILL BE OVERWRITTEN
INSTEAD CHANGE:
source: [object Object]
@page can-stache.Helpers
######################################################################## -->
<html lang="en">
<head>
<meta charset="utf-8">
<title>CanJS - Helpers</title>
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
<link rel="stylesheet" type="text/css" href="./static/bundles/bit-docs-site/static.css">
<link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico">
<link rel="apple-touch-icon" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png">
<link rel="apple-touch-icon-precomposed" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png">
<link rel="apple-touch-icon" sizes="72x72" href="../docs/images/canjs_favicon_72x72.png">
<link rel="apple-touch-icon" sizes="114x114" href="../docs/images/canjs_favicon_114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="../docs/images/canjs_favicon_128x128.png">
<link rel="apple-touch-icon" sizes="144x144" href="../docs/images/canjs_favicon_144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="../docs/images/canjs_favicon_152x152.png">
<meta content="yes" name="apple-mobile-web-app-capable">
<meta name="apple-mobile-web-app-status-bar-style" content="white-translucent">
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-2302003-11', 'auto');
ga('send', 'pageview');
</script>
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger"/>
<label for="nav-trigger">Menu</label>
<div id="everything">
<div id="left" class="column">
<div class="top-left">
<div class="brand">
<div class="logo">
<a href="../index.html" alt="CanJS"></a>
<div class="dropdown project-dropdown">
<a href="https://donejs.com/">DoneJS</a>
<a href="http://stealjs.com/">StealJS</a>
<a href="http://jquerypp.com/">jQuery ++</a>
<a href="https://funcunit.com/">FuncUnit</a>
<a href="http://documentjs.com/">DocumentJS</a>
</div>
</div>
<div class="version">
<div class="version-number">
3.0.0
</div>
<div class="dropdown version-dropdown">
<a href="https://v2.canjs.com">2.3.27</a>
</div>
</div>
</div>
<div class="search-bar">
<p>
</p>
</div>
</div>
<div class="bottom-left">
<div class="social-side-container">
<ul class="social-side">
<li>
<a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/github.png">Github</a>
</li>
<li>
<a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/twitter.png">Twitter</a>
</li>
</ul>
<ul class="social-side">
<li>
<a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a>
</li>
<li>
<a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a>
</li>
</ul>
</div>
<ul>
<li class="
">
<a class="page"
href="guides.html"
title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the
framework you marry. This page helps you know how advance through the different stages of this
relationship:">
Guides
</a>
</li>
<li class="
parent
expanded">
<a class="page"
href="can-core.html"
title="The best, most hardened and generally useful libraries in CanJS.">
Core
</a>
<ul>
<li class="
">
<a class="module"
href="can-component.html"
title="Create a custom element that can be used to manage widgets or application logic.">
can-component
</a>
</li>
<li class="
">
<a class="module"
href="can-compute.html"
title="Create an observable value.">
can-compute
</a>
</li>
<li class="
">
<a class="module"
href="can-connect.html"
title="can-connect provides persisted data middleware. Use it to assemble powerful model layers for any JavaScript project.">
can-connect
</a>
</li>
<li class="
">
<a class="module"
href="can-define.html"
title="Exports the define method that defines observable properties and their behavior on a prototype object.">
can-define
</a>
</li>
<li class="
">
<a class="module"
href="can-define/list/list.html"
title="Create observable lists.">
can-define/list/list
</a>
</li>
<li class="
">
<a class="module"
href="can-define/map/map.html"
title="Create observable objects.">
can-define/map/map
</a>
</li>
<li class="
">
<a class="function"
href="can-route.html"
title="Manage browser history and client state by synchronizing the window.location.hash with a map.">
can-route
</a>
</li>
<li class="
">
<a class="module"
href="can-route-pushstate.html"
title="Changes can-route to use pushstate
to change the window's pathname instead
of the hash.
var route = require("can-route-pushstate");
route("{page}", { page: "home" });
route.ready();
route.attr("page", "user");
location.pathname; // -> "/user"">
can-route-pushstate
</a>
</li>
<li class="
">
<a class="module"
href="can-set.html"
title="can-set is a utility for comparing sets that are represented by the parameters commonly passed to service requests.">
can-set
</a>
</li>
<li class="
parent
expanded">
<a class="module"
href="can-stache.html"
title="Live binding Mustache and Handlebars-compatible templates.">
can-stache
</a>
<ul>
<li>
<span>Pages</span>
<ul>
<li class="
">
<a class="page"
href="can-stache.magicTagTypes.html"
title="">
Magic Tag Types
</a>
</li>
<li class="
">
<a class="page"
href="can-stache.scopeAndContext.html"
title="">
Scope and Context
</a>
</li>
<li class="
">
<a class="page"
href="can-stache.expressions.html"
title="In addition to different magic tag types, stache supports different expression
types. These can be used in various combinations to call helper methods
or viewModel methods. The following is an example of all the expressions
combined:">
Expressions
</a>
</li>
<li class="
">
<a class="page"
href="can-stache.Acquisition.html"
title="There are number of ways to acquire templates such as: raw text,
a module loader, or script tags in the markup.">
Template Acquisition
</a>
</li>
<li class="current
parent
expanded">
<a class="page"
href="can-stache.Helpers.html"
title="Helpers are functions that can be registered and called from within templates. These functions
are typically used to provide functionality that is more appropriate for
the view than the viewModel.">
Helpers
</a>
</li>
<li class="
">
<a class="page"
href="can-stache.Binding.html"
title="Live binding refers to templates which update themselves when their state or data changes.
can-stache templates are able to listen to observables
(like map, list, and can-compute) changing and update the page
to reflect those changes.">
Live Binding
</a>
</li>
</ul>
</li>
<li>
<span>Methods</span>
<ul>
<li class="
">
<a class="function"
href="can-stache.from.html"
title="Return a template loaded from an element.">
from
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.registerConverter.html"
title="Register a helper for bidirectional value conversion.">
registerConverter
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.registerHelper.html"
title="Register a helper.">
registerHelper
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.registerPartial.html"
title="Register a partial.
Register a partial template that can be rendered with can-stache.tags.partial.">
registerPartial
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.registerSimpleHelper.html"
title="Register a helper that gets passed values.">
registerSimpleHelper
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.safeString.html"
title="Indicate that a string does not need to be escaped to be safely inserted into the page.">
safeString
</a>
</li>
</ul>
</li>
<li>
<span>Tags</span>
<ul>
<li class="
">
<a class="function"
href="can-stache.tags.escaped.html"
title="Insert the value of the expression into the output of the template.">
{{expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.unescaped.html"
title="Insert the unescaped value of the expression into the output of the template.">
{{{expression}}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.section.html"
title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">
{{#expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.close.html"
title="">
{{/expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.inverse.html"
title="Like can-stache.tags.section, but renders the opposite subsection depending on the type of expression
or the expression's return value.">
{{^expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.partial.html"
title="Render another template within the current template.">
{{>key}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.tags.comment.html"
title="A comment that doesn't get inserted into the rendered result.">
{{!expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.else.html"
title="">
{{else}}
</a>
</li>
</ul>
</li>
<li>
<span>Expressions</span>
<ul>
<li class="
">
<a class="typedef"
href="can-stache/expressions/bracket.html"
title="">
Bracket Expression
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/expressions/call.html"
title="">
Call Expression
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/expressions/hash.html"
title="">
Hash Expression
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/expressions/helper.html"
title="">
Helper Expression
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/expressions/key-lookup.html"
title="">
KeyLookup Expression
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/expressions/literal.html"
title="Specify a JavaScript primitive type.">
Literal Expression
</a>
</li>
</ul>
</li>
<li>
<span>Key Operators</span>
<ul>
<li class="
">
<a class="typedef"
href="can-stache/keys/at.html"
title="Return whatever value is at a key, regardless
if it's a function or a compute.">
@at
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/compute.html"
title="Pass a compute instead of a value if an observable is found within
calls.">
~compute
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/current.html"
title="Lookup a value in only the current context.">
./current
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/parent.html"
title="Start looking for values in the parent context.">
../parent
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/special.html"
title="Event bindings and some helpers like can-stache.helpers.each
provide special values that start with % to prevent potential collisions with
other values.">
%special
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/this.html"
title="Write out or return the current context.">
this
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache/keys/variable.html"
title="Store a variable local to the template.">
*variable
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.key.html"
title="A named reference to a value in the scope or helper scope in a template.">
key
</a>
</li>
</ul>
</li>
<li>
<span>Helpers</span>
<ul>
<li class="
">
<a class="function"
href="can-stache.helpers.if.html"
title="can-stache.helpers.if">
{{#if expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.unless.html"
title="">
{{#unless expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.each.html"
title="">
{{#each expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.with.html"
title="Changes the context within a block.">
{{#with expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.log.html"
title="">
{{log}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.is.html"
title="Render something if two values are equal.">
{{#is expressions}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.switch.html"
title="">
{{#switch expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.case.html"
title="">
{{#case expression}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.default.html"
title="">
{{#default}}
</a>
</li>
<li class="
">
<a class="function"
href="can-stache.helpers.joinBase.html"
title="">
{{joinBase expressions}}
</a>
</li>
</ul>
</li>
<li>
<span>Types</span>
<ul>
<li class="
">
<a class="typedef"
href="can-stache.getterSetter.html"
title="The getterSetter argument passed to registerConverter.">
getterSetter
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.helper.html"
title="A helper function passed to can-stache.registerHelper.
Given the arguments, returns the content that should be shown in the DOM
or a function that will be called on the DOM element the helper was
called on.">
helper
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.helperOptions.html"
title="The options argument passed to a helper function when called by a helper.">
helperOptions
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.renderer.html"
title="A function returned by can-stache that renders a template into an html documentFragment.">
renderer
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.sectionRenderer.html"
title="Renders a section. These functions are usually provided as .fn and .inverse on a stache helper's options.">
sectionRenderer
</a>
</li>
<li class="
">
<a class="typedef"
href="can-stache.simpleHelper.html"
title="A helper function passed to can-stache.registerSimpleHelper.">
simpleHelper
</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="
">
<a class="module"
href="can-stache/helpers/route.html"
title="Adds stache helpers that use can-route.">
can-stache/helpers/route
</a>
</li>
<li class="
">
<a class="module"
href="can-stache-bindings.html"
title="Provides template event, one-way, and two-way bindings.">
can-stache-bindings
</a>
</li>
</ul>
</li>
<li class="
">
<a class="page"
href="can-ecosystem.html"
title="Useful libraries that extend or add important features to the core collection.">
Ecosystem
</a>
</li>
<li class="
">
<a class="page"
href="can-infrastructure.html"
title="Utility libraries that power the core and ecosystem collection.">
Infrastructure
</a>
</li>
<li class="
">
<a class="page"
href="can-legacy.html"
title="Former libraries that we still accept patches for, but are not under active development.">
Legacy
</a>
</li>
</ul>
</div>
</div>
<div id="right" class="column">
<div class="top-right">
<div class="top-right-top">
<ul class="top-right-bitovi">
<li class="dropdown">
<a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a>
<ul class="dropdown-menu">
<li><a href="http://bitovi.com">Bitovi.com</a></li>
<li><a href="http://bitovi.com/blog/">Blog</a></li>
<li><a href="http://bitovi.com/consulting/">Consulting</a></li>
<li><a href="http://bitovi.com/training/">Training</a></li>
<li><a href="http://bitovi.com/open-source/">Open Source</a></li>
</ul>
</li>
</ul>
<div class="brand">
<div class="logo">
<a href="../index.html" alt="CanJS"></a>
</div>
</div>
<ul class="top-right-links">
<li>
<a href="https://gitter.im/canjs/canjs">Chat</a>
</li>
<li>
<a href="http://forums.donejs.com/c/canjs">Forum</a>
</li>
<li>
<a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a>
</li>
<li>
<a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</li>
</ul>
</div>
<div class="breadcrumb">
<li><a href="../index.html">CanJS</a></li> /
<li><a href="can-core.html">Core</a></li> /
<li><a href="can-stache.html">can-stache</a></li> /
<li><a href="can-stache.Helpers.html">Helpers</a></li>
<li class="breadcrumb-dropdown">/ <a> On this page</a>
<ul class="on-this-page"></ul>
</li>
<div class="nav-toggle" title="Back to top"></div>
</div>
</div>
<div class="bottom-right">
<article>
<section class="title">
<div class="page-type">
<h1>Helpers</h1>
<div>page</div>
</div>
<section class="description">
<p>Helpers are functions that can be registered and called from within templates. These functions
are typically used to provide functionality that is more appropriate for
the <code>view</code> than the <code>viewModel</code>.</p>
</section>
</section>
<section class="on-this-page-table">
</section>
<section class="title-footer">
<ul class="title-links">
<!-- <li><a href="#">docco</a></li> -->
<li><a href="//github.com/canjs/can-stache/tree/v3.0.8/docs/helpers.md">source</a></li>
<!-- <li><a href="#">download</a></li> -->
<!-- <li><a href="#">tests</a></li> -->
</ul>
</section>
<section class="body">
<p>Example custom helpers might include:</p>
<ul>
<li>Converting a raw <code>Date</code> to a more user friendly timestamp. <code>{{timestamp birthday}}</code></li>
<li>Internationalization. <code>{{i18n 'Hello'}}</code></li>
<li>Convert markdown into HTML. <code>{{markdown(comment)}}</code></li>
</ul>
<p>Stache includes a number of built-in helpers, but custom helpers can be registered as well.</p>
<h2>Built-in Helpers</h2>
<p>The <code><a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#if key}}</a></code> helper is used for <strong>if</strong> statements. The <strong>if</strong> helper is similar
to using a <code><a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#key}}</a></code> section. If they key passed to the helper is <strong>truthy</strong>, the
section will be rendered.</p>
<pre><code>Template:
{{#if friends}}
I have friends!
{{/if}}
Data:
{
friends: true
}
Result:
I have friends!
</code></pre>
<p>When using the <code><a href="can-stache.helpers.if.html" title="can-stache.helpers.if">{{#if key}}</a></code> helper, or any other helper for that matter,
the special <code><a href="can-stache.helpers.else.html" title="">{{else}}</a></code> helper is available. <code>{{else}}</code> is equivalent to
an <a href="can-stache.tags.inverse.html" title="Like can-stache.tags.section, but renders the opposite subsection depending on the type of expression
or the expression's return value.">{{^key}}</a> inverse section (renders if given <strong>falsey</strong> data), except that it
only uses a single tag and exists inside a helper section.</p>
<pre><code>Template:
<ul>
{{#if friends}}
</li>{{name}}</li>
{{else}}
<li>No friends.</li>
{{/if}}
</ul>
Data:
{
friends: false
}
Result:
<ul>
<li>No friends.</li>
</ul>
</code></pre>
<p>The <code><a href="can-stache.helpers.unless.html" title="">{{#unless key}}</a></code> helper is equivalent to using a
<code><a href="can-stache.tags.inverse.html" title="Like can-stache.tags.section, but renders the opposite subsection depending on the type of expression
or the expression's return value.">{{^key}}</a></code> inverse section. If they key passed to the helper is <strong>falsey</strong>, the
section will be rendered.</p>
<pre><code>Template:
{{#unless friends}}
You don't have any friends!
{{/unless}}
Data:
{
friends: []
}
Result:
You don't have any friends!
</code></pre>
<p>The <code><a href="can-stache.helpers.each.html" title="">{{#each key}}</a></code> helper is similar to using a
<code><a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#key}}</a></code> section for iterating an array. In this case, the entire array
will be rendered using the inner text item by item.</p>
<pre><code>Template:
<ul>
{{#each friends}}
<li>{{name}}</li>
{{/each}}
</ul>
Data:
{
friends: [
{ name: "Austin" },
{ name: "Justin" }
]
}
Result:
<ul>
<li>Austin</li>
<li>Justin</li>
</ul>
</code></pre>
<p>The <code><a href="can-stache.helpers.with.html" title="Changes the context within a block.">{{#with key}}</a></code> helper is equivalent to using a
<code><a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#key}}</a></code> section for regular objects. The helper will change
the current context so that all tags inside will look for keys on the local context first.</p>
<pre><code>Template:
<h1>Hi {{name}}</h1>
{{#with friend}}
<p>You have a new friend: {{name}}</p>
{{/with}}
Data:
{
name: "Andy",
friend: { name: "Justin" }
}
Result:
<h1>Hi Austin</h1>
<p>You have a new friend: Justin</p>
</code></pre>
<p>When using the <code><a href="can-stache.helpers.is.html" title="Render something if two values are equal.">{{#is key1 key2}}</a></code> helper you can simply compare
key1 and key2. If the result of comparsion is <strong>truthy</strong>, the section will be rendered.</p>
<pre><code>Template:
<ul>
{{#is name 'Alex'}}
</li>Your name is {{name}}</li>
{{else}}
<li>Your name is not Alex!</li>
{{/is}}
</ul>
Data:
{
name: 'John'
}
Result:
<ul>
<li>Your name is not Alex!</li>
</ul>
</code></pre>
<h2>Registering Helpers</h2>
<p>You can register your own global helper with the <code><a href="can-stache.registerSimpleHelper.html" title="Register a helper that gets passed values.">registerSimpleHelper</a></code>
<code><a href="can-stache.registerHelper.html" title="Register a helper.">registerHelper</a></code> or
methods.</p>
<p><code><a href="can-stache.registerSimpleHelper.html" title="Register a helper that gets passed values.">registerSimpleHelper</a></code> calls the registered helper function with
values, while <code><a href="can-stache.registerHelper.html" title="Register a helper.">registerHelper</a></code> calls the registered helper function with
<a href="can-compute.computed.html" title="A derived value from other computes and observable maps.">computes</a> if observable data is passed. <code>registerSimpleHelper</code> is
easiser to use for basic helper functionality.</p>
<p>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
<a href="https://github.com/jquery/globalize">jQuery Globalize</a>.</p>
<pre><code>stache.registerSimpleHelper('l10n', function(str, options){
return Globalize != undefined
? Globalize.localize(str)
: str;
});
</code></pre>
<p>In the template, invoke the helper by calling the helper
name followed by any additional arguments.</p>
<pre><code>Template:
<span>{{l10n 'mystring'}}</span>
Result:
<span>my string localized</span>
</code></pre>
<h3>Helper Arguments</h3>
<p>The type of arguments passed to a <code>registerHelper</code> function depends on how the helper was called and the values
passed to the helper. In short, observables will be passed as <a href="can-compute.computed.html" title="A derived value from other computes and observable maps.">compute</a> arguments
in helper expressions. In any other circumstance, values will be passed.</p>
<p>Helpers can be called as either a <a href="can-stache.expressions.html" title="In addition to different magic tag types, stache supports different expression
types. These can be used in various combinations to call helper methods
or viewModel methods. The following is an example of all the expressions
combined:">Call or Helper Expression</a>:</p>
<ul>
<li>Call expression - <code>{{myHelper(firstValue, secondValue)}}</code></li>
<li>Helper expression - <code>{{myHelper firstValue secondValue}}</code></li>
</ul>
<p>Helpers can also be called with observable values or non-observable values.</p>
<p>Considering a helper like:</p>
<pre><code class="language-js">stache.registerHelper("myHelper", function(value){ ... })
</code></pre>
<p>The following details what <code>value</code> is depending on how the helper is called
and the data passed.</p>
<h4>Call expression with non-observable data</h4>
<pre><code>Data:
{ name: 'John' }
Template:
{{ myHelper(name) }}
value:
'John'
</code></pre>
<h4>Call expression with observable data</h4>
<pre><code>Data:
new DefineMap({ name: 'John' })
Template:
{{ myHelper(name) }}
value:
'John'
</code></pre>
<h4>Helper expression with non-observable data</h4>
<pre><code>Data:
{ name: 'John' }
Template:
{{ myHelper name }}
value:
'John'
</code></pre>
<h4>Helper expression with observable data</h4>
<pre><code>Data:
new DefineMap({ name: 'John' })
Template:
{{ myHelper name }}
value:
compute('John')
</code></pre>
<h3>Evaluating Helpers</h3>
<p>If you want to use a helper with a <a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#expression}}</a> tag, you need to call
<code>options.fn(context)</code> in your return statement. This will return a
document fragment or string with the resulting evaluated subsection.</p>
<p>Similarly, you can call <code>options.inverse(context)</code> to evaluate the
template between an <code>{{else}}</code> tag and the closing tag.</p>
<p>For example, when a route matches the string passed to our
routing helper it will show/hide the text.</p>
<pre><code>stache.registerHelper('routing', function(str, options){
if (route.attr('filter') === str)
return options.fn(this);
}
});
{{#routing 'advanced'}}
You have applied the advanced filter.
{{/routing}}
</code></pre>
<p><strong>Advanced Helpers</strong></p>
<p>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 <code>key=value</code> syntax. The hash object will be provided
to the helper as <code>options.hash</code>. Additionally, when using <a href="can-stache.tags.section.html" title="Renders a subsection one or more times depending on the type of expression
or the expression's return value.">{{#expression}}</a> tags with a helper,
you can set a custom context by passing the object instead of <code>this</code>.</p>
<pre><code>stache.registerHelper('exercise', function(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'
}
</code></pre>
<p>This would output:</p>
<pre><code>Along with the cat, dog, parrot, we walked around the block
3 times this morning.
</code></pre>
<p>Whereas an empty data object would output:</p>
<pre><code>We were lazy today.
</code></pre>
</section>
<script type="text/javascript">
var docObject = {"src":{"path":"node_modules/can-stache/docs/helpers.md"},"description":"\nHelpers are functions that can be registered and called from within templates. These functions\nare typically used to provide functionality that is more appropriate for\nthe `view` than the `viewModel`.\n","name":"can-stache.Helpers","title":"Helpers","type":"page","parent":"can-stache.pages","order":4,"pathToRoot":".."};
</script>
</article>
<footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer>
</div>
</div>
</div>
<script>
steal = {
instantiated: {
"bundles/bit-docs-site/static.css!$css" : null
}
};
</script>
<script type='text/javascript' data-main="bit-docs-site/static" src="./static/node_modules/steal/steal.production.js"></script>
<script async defer src="https://buttons.github.io/buttons.js"></script>
</body>
</html>