Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(9)

Side by Side Diff: third_party/polymer/v1_0/components-chromium/iron-list/README.md

Issue 1834313003: Remove unneeded files from third_party/polymer. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Restore bower.json files. Created 4 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
(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 [![Build status](https://travis-ci.org/PolymerElements/iron-list.svg?branch=mast er)](https://travis-ci.org/PolymerElements/iron-list)
16
17 _[Demo and API docs](https://elements.polymer-project.org/elements/iron-list)_
18
19
20 ##&lt;iron-list&gt;
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
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698