| OLD | NEW |
| (Empty) |
| 1 | |
| 2 <!--- | |
| 3 | |
| 4 This README is automatically generated from the comments in these files: | |
| 5 iron-list.html | |
| 6 | |
| 7 Edit those files, and our readme bot will duplicate them over here! | |
| 8 Edit this file, and the bot will squash your changes :) | |
| 9 | |
| 10 The bot does some handling of markdown. Please file a bug if it does the wrong | |
| 11 thing! https://github.com/PolymerLabs/tedium/issues | |
| 12 | |
| 13 --> | |
| 14 | |
| 15 [](https://travis-ci.org/PolymerElements/iron-list) | |
| 16 | |
| 17 _[Demo and API docs](https://elements.polymer-project.org/elements/iron-list)_ | |
| 18 | |
| 19 | |
| 20 ##<iron-list> | |
| 21 | |
| 22 `iron-list` displays a virtual, 'infinite' list. The template inside | |
| 23 the iron-list element represents the DOM to create for each list item. | |
| 24 The `items` property specifies an array of list item data. | |
| 25 | |
| 26 For performance reasons, not every item in the list is rendered at once; | |
| 27 instead a small subset of actual template elements *(enough to fill the viewport
)* | |
| 28 are rendered and reused as the user scrolls. As such, it is important that all | |
| 29 state of the list template be bound to the model driving it, since the view may | |
| 30 be reused with a new model at any time. Particularly, any state that may change | |
| 31 as the result of a user interaction with the list item must be bound to the mode
l | |
| 32 to avoid view state inconsistency. | |
| 33 | |
| 34 __Important:__ `iron-list` must either be explicitly sized, or delegate scrollin
g to an | |
| 35 explicitly sized parent. By "explicitly sized", we mean it either has an explici
t | |
| 36 CSS `height` property set via a class or inline style, or else is sized by other | |
| 37 layout means (e.g. the `flex` or `fit` classes). | |
| 38 | |
| 39 ### Template model | |
| 40 | |
| 41 List item templates should bind to template models of the following structure: | |
| 42 | |
| 43 ```js | |
| 44 { | |
| 45 index: 0, // index in the item array | |
| 46 selected: false, // true if the current item is selected | |
| 47 tabIndex: -1, // a dynamically generated tabIndex for focus management | |
| 48 item: {} // user data corresponding to items[index] | |
| 49 } | |
| 50 ``` | |
| 51 | |
| 52 Alternatively, you can change the property name used as data index by changing t
he | |
| 53 `indexAs` property. The `as` property defines the name of the variable to add to
the binding | |
| 54 scope for the array. | |
| 55 | |
| 56 For example, given the following `data` array: | |
| 57 | |
| 58 ##### data.json | |
| 59 | |
| 60 ```js | |
| 61 [ | |
| 62 {"name": "Bob"}, | |
| 63 {"name": "Tim"}, | |
| 64 {"name": "Mike"} | |
| 65 ] | |
| 66 ``` | |
| 67 | |
| 68 The following code would render the list (note the name and checked properties a
re | |
| 69 bound from the model object provided to the template scope): | |
| 70 | |
| 71 ```html | |
| 72 <template is="dom-bind"> | |
| 73 <iron-ajax url="data.json" last-response="{{data}}" auto></iron-ajax> | |
| 74 <iron-list items="[[data]]" as="item"> | |
| 75 <template> | |
| 76 <div> | |
| 77 Name: [[item.name]] | |
| 78 </div> | |
| 79 </template> | |
| 80 </iron-list> | |
| 81 </template> | |
| 82 ``` | |
| 83 | |
| 84 ### Accessibility | |
| 85 | |
| 86 `iron-list` automatically manages the focus state for the items. It also provide
s | |
| 87 a `tabIndex` property within the template scope that can be used for keyboard na
vigation. | |
| 88 For example, users can press the up and down keys to move to previous and next | |
| 89 items in the list: | |
| 90 | |
| 91 ```html | |
| 92 <iron-list items="[[data]]" as="item"> | |
| 93 <template> | |
| 94 <div tabindex$="[[tabIndex]]"> | |
| 95 Name: [[item.name]] | |
| 96 </div> | |
| 97 </template> | |
| 98 </iron-list> | |
| 99 ``` | |
| 100 | |
| 101 ### Styling | |
| 102 | |
| 103 You can use the `--iron-list-items-container` mixin to style the container of it
ems: | |
| 104 | |
| 105 ```css | |
| 106 iron-list { | |
| 107 --iron-list-items-container: { | |
| 108 margin: auto; | |
| 109 }; | |
| 110 } | |
| 111 ``` | |
| 112 | |
| 113 ### Resizing | |
| 114 | |
| 115 `iron-list` lays out the items when it receives a notification via the `iron-res
ize` event. | |
| 116 This event is fired by any element that implements `IronResizableBehavior`. | |
| 117 | |
| 118 By default, elements such as `iron-pages`, `paper-tabs` or `paper-dialog` will t
rigger | |
| 119 this event automatically. If you hide the list manually (e.g. you use `display:
none`) | |
| 120 you might want to implement `IronResizableBehavior` or fire this event manually
right | |
| 121 after the list became visible again. For example: | |
| 122 | |
| 123 ```js | |
| 124 document.querySelector('iron-list').fire('iron-resize'); | |
| 125 ``` | |
| 126 | |
| 127 ### When should `<iron-list>` be used? | |
| 128 | |
| 129 `iron-list` should be used when a page has significantly more DOM nodes than the
ones | |
| 130 visible on the screen. e.g. the page has 500 nodes, but only 20 are visible at t
he time. | |
| 131 This is why we refer to it as a `virtual` list. In this case, a `dom-repeat` wil
l still | |
| 132 create 500 nodes which could slow down the web app, but `iron-list` will only cr
eate 20. | |
| 133 | |
| 134 However, having an `iron-list` does not mean that you can load all the data at o
nce. | |
| 135 Say, you have a million records in the database, you want to split the data into
pages | |
| 136 so you can bring a page at the time. The page could contain 500 items, and iron-
list | |
| 137 will only render 20. | |
| 138 | |
| 139 | |
| OLD | NEW |