Live binding handlebars templates
can-stache function
stache(template)
- types
simpleHelper function(*..., can-stache.sectionOptions, arg..., options)
[helper function(*..., can.stache.sectionOptions, arg..., options)](#helper-function-canstachesectionoptions-arg-optionshelperoptions-object)
helperOptions Object
key String
sectionRenderer function(context, helpers)
- static
- tags
- helper tags
{{#case expr}}BLOCK{{/case}}
{{data name[ key]}}
{{#default}}BLOCK{{/default}}
{{#each key}}BLOCK{{/each}}
{{#helper}}BLOCK{{else}}INVERSE{{/helper}}
{{helper [args...] [hashProperty=hashValue...]}}
{{#if key}}BLOCK{{/if}}
{{@index [offset]}}
{{#is expr...}}BLOCK{{/is}}
{{joinBase expr}}
{{@key}}
{{#log [message]}}
{{#routeCurrent hashes}}SUBEXPRESSION{{/routeCurrent}}
routeCurrent([hashes])
{{routeUrl hashes [,merge]}}
{{#helper [args...] [hashName=hashValue...]}}BLOCK{{/helper}}
{{#helper [args...] [hashName=hashValue...]}}BLOCK{{else}}INVERSE{{/helper}}
{{#switch expr}}BLOCK{{/switch}}
{{#unless key}}BLOCK{{/unless}}
{{#with key}}BLOCK{{/with}}
- types
Live binding Mustache and Handlebars-comptable templates.
Processes the template and returns a renderer function that renders the template with data and local helpers.
- template
{String}
: The text of a mustache template.
- returns
{renderer(Object, Object, data, helpers)}
: A renderer function that returns a live document fragment that can be inserted in the page.
A helper function passed to registerSimpleHelper.
-
undefined
{*}
: -
undefined
{can-stache.sectionOptions}
: -
arg
{*}
: Arguments passed from the tag. After the helper name, any space seperated [can.stache.key keys], numbers or strings are passed as arguments.
The following template:
<p>{{madLib "Lebron James" verb 4}}</p>
Rendered with
{verb: "swept"}
Will call a madLib
helper with the following arguements.
stache.registerSimpleHelper('madLib',
function(subject, verb, number){
// subject -> "Lebron James"
// verb -> "swept"
// number -> 4
});
Unlike [can.stache.helper] simple helpers will always pass the actual value (instead of a compute).
- options
{can.stache.helperOptions}
: An options object that gets populated with optional:
-
fn
andinverse
section rendering functions -
a
hash
object of the maps passed to the helper -
returns
{String|function(HTMLElement)}
: The content to be inserted into the template.
A helper function passed to registerHelper.
function(*..., can.stache.sectionOptions, arg..., options)
-
undefined
{*}
: -
undefined
{can.stache.sectionOptions}
: -
arg
{*|can.compute}
: Arguments passed from the tag. After the helper name, any space seperated keys, numbers or strings are passed as arguments. [can.stache.key Keys] that read an observable value are passed as [can-compute.computed]'s. -
options
{helperOptions}
: An options object that gets populated with optional:
-
fn
andinverse
section rendering functions -
a
hash
object of the maps passed to the helper -
returns
{documentFragment|String|can.contentArray|function(HTMLElement)}
: The content to be inserted into the template.
The options argument passed to a helper function.
-
fn
{sectionRenderer(context, helpers)}
: Renders the "truthy" subsection BLOCK.options.fn
is only available if the helper is called as a section or inverse section like:{{#helper}}
or `{{^helper}}. The subsection BLOCK'sAvailable if the helper is called as a section or inverse section. [can.stache.helpers.sectionHelper section helper] is called. Call
fn
to render the BLOCK with the specifiedcontext
. -
inverse
{sectionRenderer(context, helpers)}
: Provided if a section helper is called with {{else}}. Callinverse
to render the INVERSE with the specifiedcontext
. -
hash
{Object<String,*|String|Number>}
: An object containing all of the final arguments listed asname=value
pairs for the helper.{{helper arg1 arg2 name=value other=3 position="top"}}
options.hash = { name: <context_lookup>.value, other: 3, position: "top" }
-
context
{*}
: The current context the stache helper is called within.var temp = stache( "{{#person.name}}{{helper}}{{/person.name}}"); var data = {person: {name: {first: "Justin"}}}; can.stache.registerHelper("helper", function(options){ options.context === data.person //-> true }) temp(data);
-
scope
{can-view-scope}
: An object that represents the current context and all parent contexts. It can be used to look up key values in the current scope.var temp = stache( "{{#person.name}}{{helper}}{{/person.name}}"); var data = {person: {name: {first: "Justin"}}}; stache.registerHelper("helper", function(options){ options.scope.attr("first") //-> "Justin" options.scope.attr("person") //-> data.person }) temp(data);
-
options
{can.view-scope.Options}
: An object that represents the local stache helpers. It can be used to look up [can.stache.key key] valuesvar temp = stache("{{#person.name}}{{helper}}{{/person.name}}"); var data = {person: {name: "Justin"}}; stache.registerHelper("helper", function(options){ options.options.attr("helpers.specialHelper") //-> function }) temp(data, { specialHelper: function(){ ... } });
A named reference to a value in the [can-view-scope scope] or [can.view-scope.Options helper scope] in a template.
A key specifies a value in the [can.view.Scope scope] or [can-view-scope.Options options] of a template being rendered. The key is used to look up a value in the scope.
What the key looks like changes the behavior of how a value is looked up in the scope. Keys can look like:
{{name}}
- Single property name.{{name.first}}
- Multiple property names.{{foo\\.bar}}
- Single property name that includes a dot character.{{./name}}
- Single property in the current context.{{../name}}
- Single property in the parent context.{{.}}
or{{this}}
- The current context.{{../.}}
- The parent context.{{@key}}
- Pass the value at key, even if it's a function or a compute.{{~key}}
- Pass a compute as the key's value instead of the value.{{*variable}}
- Reference a value in template scope.{{%key}}
- A special value that is added to scope. Examples:{{%index}}
- The index of a value in an array or [can.List].{{%key}}
- The property name of a value within an object or [can.Map].{{%element}}
- The element an event was dispatched on.{{%event}}
- The event object.{{%viewModel}}
- The viewModel of the current element.
Renders a section. These functions are usually provided as .fn
and .inverse
on a stache helper's options.
-
context
{*|can-view-scope}
: Specifies the data the section is rendered with. If a [can-view-scope] is provided, that scope is used to render the section. If anything else is provided, it is used to create a new scope object with the current scope as it's parent. If nothing is provided, the current scope is used to render the section. -
helpers
{*|can-view-scope.Options}
: Specifies the helpers the section is rendered with. If a [can-view-scope.Options] is provided, that scope is used to render the section. If anything else is provided, it is used to create a new scope object with the current helper scope as it's parent. If nothing is provided, the current helper scope is used to render the section.
-
returns
{documentFragment|String}
: Returns the rendered result of the helper. If the section is within a tag, like:<h1 {{#helper}}class='power'{{/helper}}>
a String is returned.
If the section is outside a tag like:
<div> {{#helper}}<h2>Tasks</h2>{{/helper}} </div>
a documentFragment is returned.
The following template:
stache.registerHelper("upper", function(str){
return str.toUpperCase();
});
- name
{String}
: The name of the helper. - helper
{helper(*..., can.stache.sectionOptions, arg..., options)}
: The helper function.
- name
{String}
: The name of the helper. - helper
{can-stache.simplehelper}
: The helper function.
- str
{String}
: A string you don't want to become escaped.
- returns
{String}
: A string flagged bymustache
as safe, which will not become escaped, even if you use {{{key}}}(triple slash).
-
key
{key}
: A key that references one of the following:- A registered helper.
- A value within the current or parent [can-stache.context context]. If the value is a function or [can.compute], the function's return value is used.
-
returns
{String|function|*}
:After the key's value is found (and set to any function's return value), it is passed to [can.view.txt] as the result of a call to its
func
argument. There, if the value is a:null
orundefined
- an empty string is inserted into the rendered template result.String
orNumber
- the value is inserted into the rendered template result.Function
- A [can.view.hook hookup] attribute or element is inserted so this function will be called back with the DOM element after it is created.
Behaves just like {{key}} and {{helper}} but does not escape the result.
- key
{key}
: A key that references a value within the current or parent context. If the value is a function or [can-compute.computed], the function's return value is used.
- returns
{String|function|*}
:
Render blocks of text one or more times, depending on the value of the key in the current context.
- key
{key}
: A key that references a value within the current or parent [can-stache.context context]. If the value is a function or [can-compute.computed], the function's return value is used.
-
returns
{String}
:Depending on the value's type, the following actions happen:
Array
or [can-list] - the block is rendered for each item in the array. The [can-stache.context context] is set to the item within each block rendering.- A
truthy
value - the block is rendered with the [can.stache.context context] set to the value. - A
falsey
value - the block is not rendered.
The rendered result of the blocks, block or an empty string is returned.
The {{&key}}
tag is an alias for {{{key}}}, behaving just
like {{key}} and {{helper}} but does not
escape the result.
- key
{key}
: A key that references a value within the current or parent context. If the value is a function or [can-compute.computed], the function's return value is used.
- returns
{String|function|*}
:
Ends a {{#key}} or [can-stache.tags.sectionHelper {{#helper}}] block.
- key
{key}
: A key that matches the opening key or helper name. It's also possible to simply write{{/}}
to end a block.
Render blocks of text if the value of the key is falsey. An inverted section syntax is similar to regular sections except it begins with a caret rather than a pound. If the value referenced is falsey, the section will render.
- key
{key}
: A key that references a value within the current or parent [can-stache.context context]. If the value is a function or [can-compute.computed], the function's return value is used.
-
returns
{String}
:Depending on the value's type, the following actions happen:
- A
truthy
value - the block is not rendered. - A
falsey
value - the block is rendered.
The rendered result of the block or an empty string is returned.
- A
The comment tag operates similarly to a <!-- -->
tag in HTML. It exists in your template but never shows up.
- key
{key}
: Everything within this tag is completely ignored.
- returns
{String}
:
Renders the BLOCK
when expr
matches the expr
provided in the parent {{#switch expr}}.
-
expr
{can-stache.expression}
: An expression or key that references a value. -
BLOCK
{can-stache}
: a template that will render if the case clause resolves.
- returns
{DocumentFragment}
: A fragment, possibly containing the renderedBLOCK
.
Adds the current [can-stache.context context] to the element's [can-data].
- name
{String}
: The name of the data attribute to use for the context.
Renders the BLOCK
if no [can.stache.helpers.case] blocks within the switch resolved.
- BLOCK
{can.stache}
: a template to be rendered.
- returns
{DocumentFragment}
: A fragment, containing the rendered block.
Render the block of text for each item in key's value.
- key
{key}
: A key that references a value within the current or parent context. If the value is a function or can.compute, the function's return value is used.
If the value of the key is a [can.List], the resulting HTML is updated when the list changes. When a change in the list happens, only the minimum amount of DOM element changes occur.
If the value of the key is a [can.Map], the resulting HTML is updated whenever attributes are added or removed. When a change in the map happens, only the minimum amount of DOM element changes occur.
- BLOCK
{can.stache}
: A template that is rendered for each item in thekey
's value. TheBLOCK
is rendered with the context set to the item being rendered.
Creates an inverse
block for a helper function's
options argument's inverse
property.
- INVERSE
{can-stache}
: a stache template coverted to a function and set as the helper function's options argument'sinverse
property.
Calls a stache helper function or a function. For example:
The template:
<p>{{madLib "Lebron James" verb 4 foo="bar"}}</p>
Rendered with:
{verb: "swept"}
Will call a madLib
helper with the following arguements:
stache.registerHelper('madLib',
function(subject, verb, number, options){
// subject -> "Lebron James"
// verb -> "swept"
// number -> 4
// options.hash.foo -> "bar"
});
-
helper
{key}
: A key that finds a helper function that is either registered or found within the current or parent [can-stache.context context]. -
args
{key|String|Number}
: Space seperated arguments that get passed to the helper function as arguments. If the key's value is a:- [can-map] - A getter/setter [can.compute] is passed.
- [can-compute.computed] - The can.compute is passed.
function
- The function's return value is passed.
-
hashProperty
{String}
:
A property name that gets added to a helper options's hash object.
- hashValue
{key|String|Number}
: A value that gets set as a property value of the helper option argument's hash object.
Renders the BLOCK
template within the current template.
-
key
{key}
: A key that references a value within the current or parent context. If the value is a function or can.compute, the function's return value is used. -
BLOCK
{can-stache}
: A stache template.
- returns
{String}
: If the key's value is truthy, theBLOCK
is rendered with the current context and its value is returned; otherwise, an empty string.
Insert the index of an Array or [can-list] we are iterating on with #each
- offset
{Number}
: The number to optionally offset the index by.
Renders the BLOCK
template within the current template.
-
expr
{can-stache.expression}
: An expression or key that references a value within the current or parent -
BLOCK
{can-stache}
: A template that is rendered if the result of comparsionexpr1
andexpr2
value is truthy.
- returns
{DocumentFragment}
: If the key's value is truthy, theBLOCK
is rendered with the current context and its value is returned; otherwise, an empty string.
Return an application-relative url for a resource.
- expr
{can-stache.expression}
: An expression or key that references a value within the current or parent scope.
- returns
{String}
: An application-relative url.
Insert the property name of an Object or attribute name of a can.Map that we iterate over with #each
Logs the context of the current block with an optional message.
- message
{*}
: An optional message to log out in addition to the current context.
Renders SUBEXPRESSION
if the hashes
passed to [can-route.current route.current] returns true
.
Renders the {{else}} expression if [can-route.current route.current] returns false
.
- hashes
{}
: A hash expression likepage='edit' recipeId=id
.
- returns
{String}
: The result ofSUBEXPRESSION
or{{else}}
expression.
Calls [can-route.current can.route.current] with hashes
and returns the result.
- hashes
{}
: A hash expression likepage='edit' recipeId=id
.
- returns
{Boolean}
: Returns the result of calling [can-route.current route.current].
Passes the hashes to route.url
and returns the result.
-
hashes
{}
: A hash expression likepage='edit' recipeId=id
. -
merge
{Boolean}
: Passtrue
to create a url that mergeshashes
into the current [can-route] properties. Passing themerge
argument is only available in undefined likerouteUrl(id=itemId, true)
.
- returns
{String}
: Returns the result of callingroute.url
.
Calls a stache helper function or a function with a block to render.
The template:
<p>{{#countTo number}}{{num}}{{/countTo}}</p>
Rendered with:
{number: 5}
Will call the countTo
helper:
stache.registerHelper('countTo',
function(number, options){
var out = [];
for(var i =0; i < number; i++){
var docFrag = options.fn({num: i+1});
out.push( docFrag.textContent );
}
return out.join(" ");
});
Results in:
<p>1 2 3 4 5</p>
-
helper
{key}
: A key that finds a helper function that is either registered or found within the current or parent [can-stache.context context]. -
args
{key|String|Number}
: Space seperated arguments that get passed to the helper function as arguments. If the key's value is a:- [can-map] - A getter/setter [can-compute.computed] is passed.
- [can-compute.computed] - The compute is passed.
function
- The function's return value is passed.
-
hashProperty
{String}
:
A property name that gets added to a helper options's hash object.
-
hashValue
{key|String|Number}
: A value that gets set as a property value of the helper option argument's hash object. -
BLOCK
{stache}
: A stache template that gets compiled and passed to the helper function as the options argument'sfn
property.
Calls a stache helper function or a function with a fn
and inverse
block to
render.
The template:
<p>The bed is
{{#isJustRight firmness}}
pefect!
{{else}}
uncomfortable.
{{/justRight}}</p>
Rendered with:
{firmness: 45}
Will call the isJustRight
helper:
stache.registerHelper('isJustRight',
function(number, options){
if(number > 50){
return options.fn(this);
} else {
return options.inverse(this);
}
});
Results in:
<p>The bed is uncomfortable.</p>
-
helper
{key}
: A key that finds a helper function that is either registered or found within the current or parent [can-stache.context context]. -
args
{key|String|Number}
: Space seperated arguments that get passed to the helper function as arguments. If the key's value is a:- [can-map] - A getter/setter [can-compute.computed] is passed.
- [can-compute.computed] - The compute is passed.
function
- The function's return value is passed.
-
hashProperty
{String}
:
A property name that gets added to a helper options's hash object.
-
hashValue
{key|String|Number}
: A value that gets set as a property value of the helper option argument's hash object. -
BLOCK
{stache}
: A stache template that gets compiled and passed to the helper function as the options argument'sfn
property. -
INVERSE
{stache}
: A stache template that gets compiled and passed to the helper function as the options argument'sinverse
property.
Renders the BLOCK
with contextual {{#case expr}} and {{#default}} helpers.
-
expr
{can-stache.expression}
: An expression or key that references a value that will be switched on. -
BLOCK
{can-stache}
: a template that is rendered, uses {{#case expr}} and {{#default}} helpers to matchexpr
.
- returns
{DocumentFragment}
: A fragment containing the renderedBLOCK
.
Render the block of text if the key's value is falsey.
-
key
{key}
: A key that references a value within the current or parent context. If the value is a function or [can-compute.computed], the function's return value is used. -
BLOCK
{can.stache}
: A template that is rendered if thekey
's value is falsey.
Changes the context within a block.
-
key
{key}
: A key that references a value within the current or parent context. If the value is a function or [can-compute.computed], the function's return value is used. -
BLOCK
{can-stache}
: A template that is rendered with the context of thekey
's value.
To make a build of the distributables into dist/
in the cloned repository run
npm install
node build
Tests can run in the browser by opening a webserver and visiting the test.html
page.
Automated tests that run the tests from the command line in Firefox can be run with
npm test