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 |