can.stache

Use

Stache templates are a mustache and handlebars compatable syntax. They are used to:

• Convert data into HTML.
• Update the HTML when observable data changes.
• Provide custom elements and bindings.

The following creates a stache template, renders it with data, and inserts the result into the page:

// renderer is a "renderer function"
var renderer = can.stache("<h1>Hello {{subject}}</h1>");

// "renderer functions" render a template and return a
// document fragment.
var fragment = renderer({subject: "World"})

// A document fragment is a collection of elements that can be 
// used with jQuery or with normal DOM methods.
fragment //-> <h1>Hello World</h1>
document.body.appendChild(fragment)

Render a template with observable data like can.Maps or can.Lists and the HTML will update when the observable data changes.

var renderer = can.stache("<h1>Hello {{subject}}</h1>");
var map = new can.Map({subject: "World"});
var fragment = renderer(map)
document.body.appendChild(fragment)

map.attr("subject","Earth");

document.body.innerHTML //-> <h1>Hello Earth</h1>

There's a whole lot of behavior that can.stache provides. The following walks through the most important stuff:

• Magic Tag Types - The different tag types like {{key}} and {{#key}}...{{/key}}
• Scope and Context - How key values are looked up.
• Expressions - Supported expression types like {{helper arg}} and {{method(arg)}}
• Template Acquisition - How to load templates into your application.
• Helpers - The built in helpers and how to create your own.
• Live Binding - How live binding works.

Differences from can.mustache

can.stache is largely compatable with can.mustache. There are three main differences:

• Passes values in the scope to can.Component with {key}.
• section renderers return documentFragments.
• Element callbacks like {{(el) -> CODE}} are no longer supported.

Passing values in the scope to can.Components

A can.mustache template passes values from the scope to a can.Component by specifying the key of the value in the attribute directly. For example:

can.Component.extend({
  tag: "my-tag",
  template: "<h1>{{greeting}}</h1>"
});
var template = can.mustache("<my-tag greeting='message'></my-tag>");

var frag = template({
  message: "Hi"
});

frag //-> <my-tag greeting='message'><h1>Hi</h1></my-tag>

With stache, you wrap the key with {}. For example:

can.Component.extend({
  tag: "my-tag",
  template: "<h1>{{greeting}}</h1>"
});
var template = can.stache("<my-tag greeting='{message}'></my-tag>");

var frag = template({
  message: "Hi"
});

frag //-> <my-tag greeting='{message}'><h1>Hi</h1></my-tag>

If the key was not wrapped, the template would render:

frag //-> <my-tag greeting='message'><h1>message</h1></my-tag>

Because the attribute value would be passed as the value of greeting.

Section renderers return documentFragments

A Mustache section renderer called like options.fn() or options.inverse() would always return a String. For example, the following would wrap the .fn section in an <h1> tag:

can.mustache.registerHelper("wrapH1", function(options.fn()){
   return "<h1>"+options.fn()+"</h1>";
});

var template = can.mustache("{{#wrapH1}}Hi There!{{/#wrapH1}}");
template() //-> <h1>Hi There</h1>

can.stache's section renderers return documentFragments when sections are not contained within an html element. This means the result of the previous helper would be:

<h1>[object DocumentFragment]</h1>

Instead, helper functions should manipulate the document fragment into the desired response. With jQuery, this can be done like:

can.stache.registerHelper("wrapH1", function(options.fn()){
   return $("<h1>").append( options.fn() );
});

var template = can.stache("{{#wrapH1}}Hi There!{{/#wrapH1}}");
template() //-> <h1>Hi There</h1>

Element callbacks are no longer supported

can.mustache supported element callbacks like {{(el) -> CODE}}. These are not supported in can.stache. Instead, create a helper that returns a function or register a custom attribute.

can.stache.registerHelper("elementCallback", function(){
  return function(el){
    CODE
  }
});

can.view.tag("element-callback", function(el){
  CODE
})

Working with Promises

Promises passed into a template have the following attributes that are observable:

• isPending
• isResolved
• isRejected
• value - the resolved value of the promise, only available if isResolved is true
• reason - the rejected value, only available if isRejected is true
• state - "pending", "resolved", or "rejected"

Stache Template

<script id="template" type="text/stache">
    {{#if items.isPending}}
        <img src="loading.png"/>
    {{/if}}

    {{#if items.isResolved}}
        {{#each items.value}}
            <h2>{{name}}</h2>
        {{/each}}
    {{/if}}

    {{#if items.isRejected}}
        <img src="error.png"/>
    {{/if}}
</script>

JavaScript

var promise = $.get('/items');
var template = can.view('template', { items: promise });

Tags