key

  • typedef
can.stache.key

{String}

 

String

A key specifies a value in the scope or 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}} - a single property name.
  • {{name.first}} - multiple property names.
  • {{foo\\.bar}} - a single property name that includes a dot character.
  • {{./name}} - looks up a single property in the current context.
  • {{../name}} - looks up a single property in the parent context.
  • {{.}} or {{this}} - looks up the current context.
  • @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.

A named reference to a value in the scope or options of a template being rendered.

Use

A key references a value within the scope of a template being rendered. In the following example, the key is name:

<h1>{{name}}</h1>

If this template is rendered with:

{
  name: "Austin"
}

The template writes out:

<h1>Austin</h1>

A scope is a collection of multiple contexts. By default, a key walks up the scope to each context until it finds a value. For example, a template like:

{{first}} {{last}}
  {{#children}}
    {{first}} {{last}}
  {{/children}}

Rendered with:

{
  first: "Barry", last: "Meyer",
  children: [
    {first: "Kim", last: "Sully"},
    {first: "Justin"},
  ]
}

Writes out:

Barry Meyer
    Kim Sully
    Justin Meyer

When last is looked up on the {first: "Justin"} object and not found, it will then try to read the parent context's last property. This is why "Justin Meyer" is written out.

Controlling context lookup

Sometimes, especially with recursive templates, you want to control which context is used to lookup. Adding ./ before the key name will only look up in the current context. If we change the previous template to:

{{first}} {{last}}
  {{#children}}
    {{first}} {{./last}}
  {{/children}}

It will write out:

Barry Meyer
    Kim Sully
    Justin

Adding ../ before a key will lookup the key starting in the parent context. By changing the previous template to:

{{first}} {{last}}
  {{#children}}
    {{first}} {{../last}}
  {{/children}}

It will write out:

Barry Meyer
    Kim Meyer
    Justin Meyer

To write out the current context, write {{.}} or {{this}}. For example, a template like:

{{#each names}}{{.}} {{/each}}

With data like:

{names: ["Jan","Mark","Andrew"]}

Will write out:

Jan Mark Andrew

@index and @key

When looping over an array or can.List, you an use @index to write out the index of each property:

{{#each task}}
  <li>{{@index}} {{name}}</li>
{{/each}}

Indexes start at 0. If you want to start at 1, you can create a helper like:

can.stache.registerHelper('@indexNum', function(options){
  return options.scope.attr("@index")+1;
})

And use it like:

{{#each task}}
  <li>{{@indexNum}} {{name}}</li>
{{/each}}