can-stache-bindings

can-stache-bindings

Default binding syntaxes for can-stache.

• syntaxes
  • {(child-prop)}="key"
  • {($child-prop)}="key"
  • {child-prop}="key"
  • {$child-prop}="key"
  • {^child-prop}="key"
  • {^$child-prop}="key"
  • ($DOM_EVENT)='CALL_EXPRESSION'
  • (VIEW_MODEL_EVENT)='CALL_EXPRESSION'
  • *ref-prop
• converters
  • boolean-to-inList(item, list)
  • string-to-any(~item)
  • not(~value)
  • index-to-selected(~item, list)

API

{(child-prop)}="key"

Two-way binds childProp in the [can-component::ViewModel ViewModel] to [can-stache.key] in the parent [can-view-scope scope]. If childProp is updated key will be updated and vice-versa.

<my-component {(some-prop)}="value"/>

When setting up the binding:

• If childProp is undefined, key will be set to childProp.
• If key is undefined, childProp will be set to key.
• If both childProp and key are defined, key will be set to childProp.

1. child-prop {String}: The name of the property of the viewModel to two-way bind.

2. key {can-stache/expressions/literal|can-stache/expressions/key-lookup|can-stache/expressions/call|can-stache/expressions/helper}: A call expression whose value will be used to two-way bind in the parent scope.

{($child-prop)}="key"

Two-way binds the element's childProp property or attribute to [can-stache.key] in the parent [can-view-scope scope]. If childProp is updated key will be updated and vice-versa.

<input {($value)}="name"/>

1. child-prop {String}: The name of the element's property or attribute to two-way bind.

2. key {can-stache/expressions/literal|can-stache/expressions/key-lookup|can-stache/expressions/call|can-stache/expressions/helper}: A call expression whose value will be used to two-way bind in the parent scope.

{child-prop}="key"

Imports [can-stache.key] in the [can-view-scope scope] to childProp in [can-component::ViewModel ViewModel]. It also updates childProp with the value of key when key changes.

<my-component {some-prop}="value"/>

1. child-prop {String}: The name of the property to set in the component's viewmodel.

2. key {can-stache/expressions/literal|can-stache/expressions/key-lookup|can-stache/expressions/call|can-stache/expressions/helper}: An expression whose resulting value is used to set as childProp.

{$child-prop}="key"

Imports [can-stache.key] in the [can-view-scope scope] to childProp property or attribute on the element.

<input {$value}="name"/>

This signature works, but the following should be used instead:

<input value="{{name}}"/>

{^child-prop}="key"

Exports childProp in the [can-component::ViewModel ViewModel] to [can-stache.key] in the parent [can-view-scope scope]. It also updates key with the value of childProp when childProp changes.

<my-component {^some-prop}="value"/>

1. child-prop {String}: The name of the property to export from the child components viewmodel. Use {^this} or {^.} to export the entire viewModel.

2. key {can-stache/expressions/literal|can-stache/expressions/key-lookup|can-stache/expressions/call|can-stache/expressions/helper}: An expression that will be used to set in the parent scope.

{^$child-prop}="key"

Exports the element's childProp property or attribute to [can-stache.key] in the parent [can-view-scope scope]. It also updates key with the value of childProp when childProp changes.

<input {^$value}="name"/>

1. child-prop {String}: The name of the element's property or attribute to export.

2. key {can-stache/expressions/literal|can-stache/expressions/key-lookup|can-stache/expressions/call|can-stache/expressions/helper}: An expression whose resulting value with be used to set in the parent scope.

($DOM_EVENT)='CALL_EXPRESSION'

Listens to an event on the element and calls the [can-stache/expressions/call] when that event occurs.

<div ($click)="doSomething()"/>

1. DOM_EVENT {String}: A DOM event name like "click".

2. CALL_EXPRESSION {can-stache/expressions/call}: A call expression like method(key) that is called when the DOM_EVENT is fired. The following key values are also supported:

   • %element - The element the event happened upon.
   • $element - The element the event happened upon.
   • %event - The event object.
   • %viewModel - If the element is a [can-component], the component's [can-component::ViewModel ViewModel].
   • %context - The current context.
   • %scope - The current [can-view-scope scope].

(VIEW_MODEL_EVENT)='CALL_EXPRESSION'

Listens to an event on the element's [can-component::ViewModel ViewModel] and calls the [can-stache/expressions/call] when that event occurs.

<my-component (show)="doSomething()"/>

1. DOM_EVENT {String}: A DOM event name like "click". jQuery custom events can also be given.

2. CALL_EXPRESSION {can-stache.expressions}: A call expression like method(key) that is called when the DOM_EVENT is fired. The following key values are also supported:

   • %element - The element the event happened upon.

   • $element - The [can.$] wrapped element the event happened upon.

   • %event - The event object.

   • %viewModel - If the element is a [can-component], the component's [can-component::ViewModel ViewModel].

   • %context - The current context.

   • %scope - The current [can-view-scope].

*ref-prop

A shorthand for exporting an element's viewModel to the reference scope.

1. ref-prop {String}: The name of the property to set in the template's 'references' scope.

boolean-to-inList(item, list)

When the getter is called, returns true if item is within the list, determined using .indexOf.

When the setter is called, if the new value is truthy then the item will be added to the list using .push; if it is falsey the item will removed from the list using .splice.

<input type="checkbox" {($value)}="boolean-to-inList(item, list)" />

1. item {*}: The item to which to check
2. list {can-define/list/list|can-list|Array}: The list

• returns {can-compute}: A compute that will be used by undefined as a getter/setter when the element's value changes.

string-to-any(~item)

When the getter is called, gets the value of the compute and calls .toString() on that value.

When the setter is called, takes the new value and converts it to the primitive value using [can-util/js/string-to-any/string-to-any] and sets the compute using that converted value.

<select {($value)}="string-to-any(~favePlayer)">
  <option value="23">Michael Jordan</option>
	<option value="32">Magic Johnson</option>
</select>

1. item {can-compute}: A compute holding a primitive value.

• returns {can-compute}: A compute that will be used by undefined as a getter/setter when the element's value changes.

not(~value)

When the getter is called, gets the value of the compute and returns the negation.

When the setter is called, sets the compute's value to the negation of the new value derived from the element.

Note that not needs a compute so that it can update the scope's value when the setter is called.

<input type="checkbox" {($checked)}="not(~val)" />

1. value {can-compute}: A value stored in a [can-compute].

• returns {can-compute}: A compute that will be two-way bound by undefined as a getter/setter on the element.

index-to-selected(~item, list)

When the getter is called, returns the index of the passed in item (which should be a [can-compute] from the provided list.

When the setter is called, takes the selected index value and finds the item from the list with that index and passes that to set the compute's value.

<select {($value)}="index-to-selected(~person, people)">

	{{#each people}}

		<option value="{{%index}}">{{name}}</option>

	{{/each}}

</select>

1. item {can-compute}: A compute whose item is in the list.
2. list {can-define/list/list|can-list|Array}: A list used to find the item.

• returns {can-compute}: A compute that will be two-way bound to the select's value.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

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