Blame view

bower_components/iron-list/README.md 3.38 KB
73bcce88   luigser   COMPONENTS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  iron-list
  ========================
  
  `iron-list` displays a virtual, *'infinite'* list. The template inside
  the iron-list element represents the DOM to create for each list item.
  The `items` property specifies an array of list item data.
  
  For performance reasons, not every item in the list is rendered at once;
  instead a small subset of actual template elements *(enough to fill the viewport)*
  are rendered and reused as the user scrolls. As such, it is important that all
  state of the list template be bound to the model driving it, since the view may
  be reused with a new model at any time. Particularly, any state that may change
  as the result of a user interaction with the list item must be bound to the model
  to avoid view state inconsistency.
  
e619a3b0   Luigi Serra   Controllet cross ...
16
  __Important:__ `iron-list` must ether be explicitly sized, or delegate scrolling to an
73bcce88   luigser   COMPONENTS
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
  explicitly sized parent. By "explicitly sized", we mean it either has an explicit
  CSS `height` property set via a class or inline style, or else is sized by other
  layout means (e.g. the `flex` or `fit` classes).
  
  ### Template model
  
  List item templates should bind to template models of the following structure:
  
  ```js
  {
    index: 0,     // data index for this item
    item: {       // user data corresponding to items[index]
      /* user item data  */
    }
  }
  ```
  
e619a3b0   Luigi Serra   Controllet cross ...
34
  Alternatively, you can change the property name used as data index by changing the
73bcce88   luigser   COMPONENTS
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
  `indexAs` property. The `as` property defines the name of the variable to add to the binding
  scope for the array.
  
  For example, given the following `data` array:
  
  ##### data.json
  
  ```js
  [
    {"name": "Bob"},
    {"name": "Tim"},
    {"name": "Mike"}
  ]
  ```
  
  The following code would render the list (note the name and checked properties are
  bound from the model object provided to the template scope):
  
  ```html
  <template is="dom-bind">
    <iron-ajax url="data.json" last-response="{{data}}" auto></iron-ajax>
    <iron-list items="[[data]]" as="item">
      <template>
        <div>
          Name: <span>[[item.name]]</span>
        </div>
      </template>
    </iron-list>
  </template>
  ```
e619a3b0   Luigi Serra   Controllet cross ...
65
66
67
  
  ### Resizing
  
eb240478   Luigi Serra   public room cards...
68
  `iron-list` lays out the items when it recives a notification via the `iron-resize` event.
e619a3b0   Luigi Serra   Controllet cross ...
69
70
71
72
73
74
75
76
  This event is fired by any element that implements `IronResizableBehavior`.
  
  By default, elements such as `iron-pages`, `paper-tabs` or `paper-dialog` will trigger
  this event automatically. If you hide the list manually (e.g. you use `display: none`)
  you might want to implement `IronResizableBehavior` or fire this event manually right 
  after the list became visible again. e.g.
  
  ```js
eb240478   Luigi Serra   public room cards...
77
78
79
80
81
82
83
84
85
86
87
88
89
  document.querySelector('iron-list').fire('iron-resize');
  ```
  
  ### Styling
  
  Use the `--iron-list-items-container` mixin to style the container of items, e.g.
  
  ```css
  iron-list {
   --iron-list-items-container: {
      margin: auto;
    };
  }
e619a3b0   Luigi Serra   Controllet cross ...
90
91
92
93
94
95
96
  ```
  
  ### When should `<iron-list>` be used?
  
  `iron-list` should be used when a page has significantly more DOM nodes than the ones visible on the screen. e.g. the page has 500 nodes, but only 20 are visible at the time. This is why we refer to it as a `virtual` list. In this case, a `dom-repeat` will still create 500 nodes which could slow down the web app, but `iron-list` will only create 20.
  
  However, having an `iron-list` does not mean that you can load all the data at once. Say, you have a million records in the database, you want to split the data into pages so you can bring a page at the time. The page could contain 500 items, and iron-list will only render 20.