KeyLookup Expression

typedef

`key`

A KeyLookup expression specifies a value in the scope or HelperOptions scope that will be looked up. KeyLookup expressions can be the entire stache expression like:

{{key}}

Or they can makeup the method, helper, arguments and hash value parts of Call Expression, Helper Expression, and Hash Expressions:

{{method(arg1,arg2}}          Call
{{helper arg1 arg2}}          Helper
{{method( prop=hashValue )}}  Hash

`CALL_EXPRESSION.key`

Looks up key on the return value of CALL_EXPRESSION.

{{#each Todo.getList(complete=completed).value}}

Parameters

CALL_EXPRESSION {Call Expression}:
A call expression that may or may not return a value.
key {String}:
A property value to look up on the result of CALL_EXPRESSION.

Use

The value returned up by a KeyLookup depends on what the key looks like, and what expression type the KeyLookup is within.

For example, {{method(~./key)}} will call method with a compute that looks up the value of key only in the top of the scope.

The rules are as follows:

Call Expression arguments {{method(key)}} - values are passed.
Helper Expression arguments {{helper key}} - computes are passed.
hash value in Call Expression {{method(hash=key)}} - values are set as property values.
hash value in Helper Expression {{method hash=key}} - computes are set as property values.
special operator {{%index}} - lookup values in a special context provided by some helpers.
compute operator {{method(~key)}} - pass a compute instead of a value.
at operator {{method(@key}} - pass a function instead of trying to read the value of the function.
current operator {{./key}} - only lookup key at the top of the scope.
parent operator {{../key}} - lookup the value in the parent context.
context key {{this}} - return the current context/top of the scope.

Default key return values by expression and data types

Keys can have slightly different default behavior depending if they are used in:

helper arguments like: {{helper some.key}}

when compared to the other places they are used:

insertion tags like: {{some.key}}
call-expression arguments like: {{helper(some.key)}}
event bindings like: ($click)="method(some.key)"
data bindings like: {some-attr}="some.key"

Furthermore keys return different values depending on the data type.

In general:

Functions are called to get their return value. (Use the @ operator to prevent this).
Keys in helper expression arguments that find observable data return a compute that represents the value.
Keys in other expressions return the value.
If no observable data is found, the key's value is returned in all expressions.

The following illustrates what some.key would return given different data structures as a Helper Expression and in all other expressions.

// A non-observable JS object:
{some: {key: "value"}};
   // Helper -> "value"
   // Other  -> "value"

// A non-observable JS object w/ a function at the end
{some: {key: function(){ return "value"; }}}
   // Helper -> "value"
   // Other  -> "value"

// A non-observable JS object with intermeidate functions:
{some: function(){ return {key: "value"}}}
   // Helper -> "value"
   // Other  -> "value"

// A observable can-map
{some: new Map({key: "value"})}
   // Helper -> canCompute("value")
   // Other  -> "value"

// A method on an observable can-map that reads observables
var Some = Map.extend({key: function(){ return this.attr("value")}})
{some: new Some({value: "value"})}
   // Helper -> canCompute("value")
   // Other  -> "value"