can-stache

@function can-stache.helpers.each {{#each(expression)}} @parent can-stache/deprecated @deprecated {4.15.0} Use [can-stache.helpers.for-of] instead. @signature `{{#each(EXPRESSION)}}FN{{else}}INVERSE{{/each}}` Render `FN` for each item in `EXPRESSION`’s return value. If `EXPRESSION` is falsey or an empty list, render `INVERSE`. ```html {{#each(todos)}} <li>{{name}}</li> {{else}} <li>No todos, rest easy!</li> {{/each}} ``` @param {can-stache/expressions/key-lookup|can-stache/expressions/call} EXPRESSION An expression that typically returns a list like data structure. If the value of the EXPRESSION is a [can-define/list/list] or [can-list], the resulting HTML is updated when the list changes. When a change in the list happens, only the minimum amount of DOM element changes occur. The list itself can also change, and a [can-diff/list/list diff] will be performed, which also will perform a minimal set of updates. The [can-stache/keys/special special %key key] is available within `FN`. If the value of the key is an object, `FN` will be called for each property on the object. The [can-stache/keys/special special %key key] is available within `FN`. @param {can-stache.sectionRenderer} FN A subsection that will be rendered with each item in `EXPRESSION` or property value in `EXPRESSION`. @param {can-stache.sectionRenderer} [INVERSE] An optional subsection that will be rendered if `EXPRESSION` is falsey or an empty list or object. @signature `{{#each(EXPRESSION, HASH_EXPRESSION)}}FN{{else}}INVERSE{{/each}}` Like a normal `{{#each(EXPRESSION)}}`, but uses [can-stache/expressions/hash] to add the current `value`, `key`, or `index` to the current scope. ```html {{#each(todos, todo=value num=index)}} <li data-index="{{num}}">{{todo.name}}</li> {{/each}} ``` @param {can-stache/expressions/key-lookup|can-stache/expressions/call} EXPRESSION An expression that returns a list or object like data structure. @param {can-stache/expressions/hash} HASH_EXPRESSION A hash expression that aliases special properties for each iteration: - `value`: The current value - `key`: The key of the current object item - `index`: The index of the current array item @param {can-stache.sectionRenderer} FN A subsection that will be rendered with each item in `EXPRESSION` or property value in `EXPRESSION`. @param {can-stache.sectionRenderer} [INVERSE] An optional subsection that will be rendered if `EXPRESSION` is falsey or an empty list or object. @signature `{{#each(EXPRESSION)}}FN{{else}}INVERSE{{/each}}` Like a normal `{{#each(EXPRESSION)}}`, but adds each item in `EXPRESSION` as `KEY` in `FN`’s [can-view-scope]. ```html {{#each(todos, todo=value)}} <li>{{todo.name}}</li> {{/each}} ``` @param {can-stache/expressions/key-lookup|can-stache/expressions/call} EXPRESSION An expression that returns a list or object like data structure. @param {can-stache.key} key The name that: - each item in `EXPRESSION`’s list, or - each property value in `EXPRESSION`’s object should take on in `FN`. @param {can-stache.sectionRenderer} FN A subsection that will be rendered with each item in `EXPRESSION` or property value in `EXPRESSION`. @param {can-stache.sectionRenderer} [INVERSE] An optional subsection that will be rendered if `EXPRESSION` is falsey or an empty list or object. @body ## Use Use the `each` helper to iterate over a array of items and render the block between the helper and the slash. For example, this template: ```html <ul> {{#each(friends)}} <li>{{name}}</li> {{/each}} </ul> ``` Rendered with: ```js { friends: [ { name: "Austin" }, { name: "Justin" } ] } ``` Renders: ```html <ul> <li>Austin</li> <li>Justin</li> </ul> ``` ## Object iteration When iterating over [can-map] it will only iterate over the map’s [can-map.keys] and none of the hidden properties of a Map. For example, this template: ```html <ul> {{#each(person)}} <li>{{.}}</li> {{/each}} </ul> ``` Rendered with: ```js { person: { name: "Josh", age: 27 } } ``` Renders: ```html <ul> <li>Josh</li> <li>27</li> </ul> ``` ## Understanding when to use #each with lists `{{#each(key)}}` iteration will do basic diffing and aim to only update the DOM where the change occurred. Whereas [can-stache.tags.section] default iteration will re-render the entire section for any change in the list. [can-stache.tags.section] iteration is the preferred method to use when a list is replaced or changing significantly. When doing single list item changes frequently, `{{#each(expression)}}` iteration is the faster choice. For example, assuming "list" is a [can-define/list/list] instance: `{{#each(list)}}` and `{{#list}}` both iterate through an instance of [can-define/list/list], however we setup the bindings differently. `{{#each(list)}}` will setup bindings on every individual item being iterated through, while `{{#list}}` will not. This makes a difference in two scenarios: 1) You have a large list, with minimal updates planned after initial render. In this case, `{{#list}}` might be more advantageous as there will be a faster initial render. However, if any part of the list changes, the entire `{{#list}}` area will be re-processed. 2) You have a large list, with many updates planned after initial render. A grid with many columns of editable fields, for instance. In this case, you many want to use `{{#each(list)}}`, even though it will be slower on initial render (we’re setting up more bindings), you’ll have faster updates as there are now many sections.