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}}
- 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.
Use
A key references a value within the scope of a template being rendered. In the following example, the key is
name
:If this template is rendered with:
The template writes out:
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:
Rendered with:
Writes out:
When
last
is looked up on the{first: "Justin"}
object and not found, it will then try to read the parent context'slast
property. This is why "Justin Meyer" is written out.Keys have different operators that control the values that are looked up or the value that is returned:
EXPRESSION.key
./key
../key
.
orthis
%special
*key
@key
~key
Default key return values by expression and data types
Keys can have slightly different default behavior depending if they are used in:
{{helper some.key}}
when compared to the other places they are used:
{{some.key}}
{{helper(some.key)}}
($click)="method(some.key)"
{some-attr}="some.key"
Furthermore keys return different values depending on the data type.
In general:
@
to prevent this).The following illustrates what
some.key
would return given different data structures as a helper expression and in all other expressions.context operators
./
,../
,.
andthis
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.The following template:
Rendered with:
Writes out:
Notice that
{{./last}}
returns nothing because there's nolast
property in the{first: "Justin"}
object.Adding
../
before a key will lookup the key starting in the parent context. By changing the previous template to:It will write out:
You can use
.././last
to lookuplast
only in the parent context.To write out the current context, write
{{.}}
or{{this}}
. For example, a template like:With data like:
Will write out:
at operator
@
The AT operator indicates to return whatever value is at a key, regardless if it's a function or a compute.
The following illustrates what
some@key
would return given different data structures:Where
some@key
returns a function, that function is "bound" via.bind(context)
to the parent object. This means that calling the function will havethis
set to what is expected.If the AT operator is used at the start of a key like:
This will return whatever is at the
key
property on the first context in the scope to have a non-undefinedkey
value.The AT operator can be used multiple times within a value lookup expression like:
compute operator
~
The compute operator can be used in non helper expressions to pass a compute instead of a value if an observable is found. This makes non-helper expression arguments behave similar to helper expression arguments.
The following illustrates what
~some.key
would return given different data structures:Notice that
~
should only be used once in a value lookup expression.template variable operator
*
Every template contains a context which is able to store values local to the template. Keys with
*
reference variables in that context.Template variables are often used to pass data between components.
<component-a>
exports itspropA
value to the template variable*variable
. This is, in turn, used to update the value ofpropB
in<component-b>
.Template variables are global to the template. Similar to JavaScript
var
variables, template variables do not have block leve scope. The following does not work:To work around this, an
localContext
helper could be created as follows:And used like:
special operator
%
Event bindings and some helpers like {{#each key}} provide special values that start with
%
to prevent potential collisions with other values.%index and %key
When looping over an array or can.List, you an use
%index
to write out the index of each property:Indexes start at 0. If you want to start at 1, you can create a helper like:
And use it like:
%element
In an event binding,
%element
references the DOM element the event happened on:%event
In an event binding,
%event
references the dispatched event object:%viewModel
In an event binding,
%viewModel
references the view model of the current element: