third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html

   1 <!--
   2 @license
   3 Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
   4 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   5 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   6 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   7 Code distributed by Google as part of the polymer project is also
   8 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   9 --><html><head><link rel="import" href="../polymer/polymer.html">
  10 <link rel="import" href="../iron-resizable-behavior/iron-resizable-behavior.html">
  11
  12 <!--
  13
  14 `iron-list` displays a virtual, 'infinite' list. The template inside
  15 the iron-list element represents the DOM to create for each list item.
  16 The `items` property specifies an array of list item data.
  17
  18 For performance reasons, not every item in the list is rendered at once;
  19 instead a small subset of actual template elements *(enough to fill the viewport)*
  20 are rendered and reused as the user scrolls. As such, it is important that all
  21 state of the list template be bound to the model driving it, since the view may
  22 be reused with a new model at any time. Particularly, any state that may change
  23 as the result of a user interaction with the list item must be bound to the model
  24 to avoid view state inconsistency.
  25
  26 __Important:__ `iron-list` must ether be explicitly sized, or delegate scrolling to an
  27 explicitly sized parent. By "explicitly sized", we mean it either has an explicit
  28 CSS `height` property set via a class or inline style, or else is sized by other
  29 layout means (e.g. the `flex` or `fit` classes).
  30
  31 ### Template model
  32
  33 List item templates should bind to template models of the following structure:
  34
  35     {
  36       index: 0,     // data index for this item
  37       item: {       // user data corresponding to items[index]
  38         /* user item data  */
  39       }
  40     }
  41
  42 Alternatively, you can change the property name used as data index by changing the
  43 `indexAs` property. The `as` property defines the name of the variable to add to the binding
  44 scope for the array.
  45
  46 For example, given the following `data` array:
  47
  48 ##### data.json
  49
  50     [
  51       {"name": "Bob"},
  52       {"name": "Tim"},
  53       {"name": "Mike"}
  54     ]
  55
  56 The following code would render the list (note the name and checked properties are
  57 bound from the model object provided to the template scope):
  58
  59     <template is="dom-bind">
  60       <iron-ajax url="data.json" last-response="{{data}}" auto></iron-ajax>
  61       <iron-list items="[[data]]" as="item">
  62         <template>
  63           <div>
  64             Name: <span>[[item.name]]</span>
  65           </div>
  66         </template>
  67       </iron-list>
  68     </template>
  69
  70 ### Resizing
  71
  72 `iron-list` lays out the items when it recives a notification via the `resize` event.
  73 This event is fired by any element that implements `IronResizableBehavior`.
  74
  75 By default, elements such as `iron-pages`, `paper-tabs` or `paper-dialog` will trigger
  76 this event automatically. If you hide the list manually (e.g. you use `display: none`)
  77 you might want to implement `IronResizableBehavior` or fire this event manually right
  78 after the list became visible again. e.g.
  79
  80     document.querySelector('iron-list').fire('resize');
  81
  82
  83 @group Iron Element
  84 @element iron-list
  85 @demo demo/index.html
  86 -->
  87
  88 </head><body><dom-module id="iron-list">
  89   <style>
  90
  91     :host {
  92       display: block;
  93     }
  94
  95     :host(.has-scroller) {
  96       overflow: auto;
  97     }
  98
  99     :host(:not(.has-scroller)) {
 100       position: relative;
 101     }
 102
 103     #items {
 104       position: relative;
 105     }
 106
 107     #items > ::content > * {
 108       width: 100%;
 109       box-sizing: border-box;
 110       position: absolute;
 111       top: 0;
 112       will-change: transform;
 113     }
 114
 115   </style>
 116   <template>
 117
 118     <array-selector id="selector" items="{{items}}" selected="{{selectedItems}}" selected-item="{{selectedItem}}">
 119     </array-selector>
 120
 121     <div id="items">
 122       <content></content>
 123     </div>
 124
 125   </template>
 126 </dom-module>
 127
 128 <script src="iron-list-extracted.js"></script></body></html>