Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / ListView.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.2.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 <div id="cls-Ext.list.ListView"></div>/**
16  * @class Ext.list.ListView
17  * @extends Ext.DataView
18  * <p>Ext.list.ListView is a fast and light-weight implentation of a
19  * {@link Ext.grid.GridPanel Grid} like view with the following characteristics:</p>
20  * <div class="mdetail-params"><ul>
21  * <li>resizable columns</li>
22  * <li>selectable</li>
23  * <li>column widths are initially proportioned by percentage based on the container
24  * width and number of columns</li>
25  * <li>uses templates to render the data in any required format</li>
26  * <li>no horizontal scrolling</li>
27  * <li>no editing</li>
28  * </ul></div>
29  * <p>Example usage:</p>
30  * <pre><code>
31 // consume JSON of this form:
32 {
33    "images":[
34       {
35          "name":"dance_fever.jpg",
36          "size":2067,
37          "lastmod":1236974993000,
38          "url":"images\/thumbs\/dance_fever.jpg"
39       },
40       {
41          "name":"zack_sink.jpg",
42          "size":2303,
43          "lastmod":1236974993000,
44          "url":"images\/thumbs\/zack_sink.jpg"
45       }
46    ]
47 }
48 var store = new Ext.data.JsonStore({
49     url: 'get-images.php',
50     root: 'images',
51     fields: [
52         'name', 'url',
53         {name:'size', type: 'float'},
54         {name:'lastmod', type:'date', dateFormat:'timestamp'}
55     ]
56 });
57 store.load();
58
59 var listView = new Ext.list.ListView({
60     store: store,
61     multiSelect: true,
62     emptyText: 'No images to display',
63     reserveScrollOffset: true,
64     columns: [{
65         header: 'File',
66         width: .5,
67         dataIndex: 'name'
68     },{
69         header: 'Last Modified',
70         width: .35,
71         dataIndex: 'lastmod',
72         tpl: '{lastmod:date("m-d h:i a")}'
73     },{
74         header: 'Size',
75         dataIndex: 'size',
76         tpl: '{size:fileSize}', // format using Ext.util.Format.fileSize()
77         align: 'right'
78     }]
79 });
80
81 // put it in a Panel so it looks pretty
82 var panel = new Ext.Panel({
83     id:'images-view',
84     width:425,
85     height:250,
86     collapsible:true,
87     layout:'fit',
88     title:'Simple ListView <i>(0 items selected)</i>',
89     items: listView
90 });
91 panel.render(document.body);
92
93 // little bit of feedback
94 listView.on('selectionchange', function(view, nodes){
95     var l = nodes.length;
96     var s = l != 1 ? 's' : '';
97     panel.setTitle('Simple ListView <i>('+l+' item'+s+' selected)</i>');
98 });
99  * </code></pre>
100  * @constructor
101  * @param {Object} config
102  * @xtype listview
103  */
104 Ext.list.ListView = Ext.extend(Ext.DataView, {
105     <div id="prop-Ext.list.ListView-disableHeaders"></div>/**
106      * Set this property to <tt>true</tt> to disable the header click handler disabling sort
107      * (defaults to <tt>false</tt>).
108      * @type Boolean
109      * @property disableHeaders
110      */
111     <div id="cfg-Ext.list.ListView-hideHeaders"></div>/**
112      * @cfg {Boolean} hideHeaders
113      * <tt>true</tt> to hide the {@link #internalTpl header row} (defaults to <tt>false</tt> so
114      * the {@link #internalTpl header row} will be shown).
115      */
116     <div id="cfg-Ext.list.ListView-itemSelector"></div>/**
117      * @cfg {String} itemSelector
118      * Defaults to <tt>'dl'</tt> to work with the preconfigured <b><tt>{@link Ext.DataView#tpl tpl}</tt></b>.
119      * This setting specifies the CSS selector (e.g. <tt>div.some-class</tt> or <tt>span:first-child</tt>)
120      * that will be used to determine what nodes the ListView will be working with.
121      */
122     itemSelector: 'dl',
123     <div id="cfg-Ext.list.ListView-selectedClass"></div>/**
124      * @cfg {String} selectedClass The CSS class applied to a selected row (defaults to
125      * <tt>'x-list-selected'</tt>). An example overriding the default styling:
126     <pre><code>
127     .x-list-selected {background-color: yellow;}
128     </code></pre>
129      * @type String
130      */
131     selectedClass:'x-list-selected',
132     <div id="cfg-Ext.list.ListView-overClass"></div>/**
133      * @cfg {String} overClass The CSS class applied when over a row (defaults to
134      * <tt>'x-list-over'</tt>). An example overriding the default styling:
135     <pre><code>
136     .x-list-over {background-color: orange;}
137     </code></pre>
138      * @type String
139      */
140     overClass:'x-list-over',
141     <div id="cfg-Ext.list.ListView-reserveScrollOffset"></div>/**
142      * @cfg {Boolean} reserveScrollOffset
143      * By default will defer accounting for the configured <b><tt>{@link #scrollOffset}</tt></b>
144      * for 10 milliseconds.  Specify <tt>true</tt> to account for the configured
145      * <b><tt>{@link #scrollOffset}</tt></b> immediately.
146      */
147     <div id="cfg-Ext.list.ListView-scrollOffset"></div>/**
148      * @cfg {Number} scrollOffset The amount of space to reserve for the scrollbar (defaults to
149      * <tt>undefined</tt>). If an explicit value isn't specified, this will be automatically
150      * calculated.
151      */
152     scrollOffset : undefined,
153     <div id="cfg-Ext.list.ListView-columnResize"></div>/**
154      * @cfg {Boolean/Object} columnResize
155      * Specify <tt>true</tt> or specify a configuration object for {@link Ext.list.ListView.ColumnResizer}
156      * to enable the columns to be resizable (defaults to <tt>true</tt>).
157      */
158     columnResize: true,
159     <div id="cfg-Ext.list.ListView-columns"></div>/**
160      * @cfg {Array} columns An array of column configuration objects, for example:
161      * <pre><code>
162 {
163     align: 'right',
164     dataIndex: 'size',
165     header: 'Size',
166     tpl: '{size:fileSize}',
167     width: .35
168 }
169      * </code></pre>
170      * Acceptable properties for each column configuration object are:
171      * <div class="mdetail-params"><ul>
172      * <li><b><tt>align</tt></b> : String<div class="sub-desc">Set the CSS text-align property
173      * of the column. Defaults to <tt>'left'</tt>.</div></li>
174      * <li><b><tt>dataIndex</tt></b> : String<div class="sub-desc">See {@link Ext.grid.Column}.
175      * {@link Ext.grid.Column#dataIndex dataIndex} for details.</div></li>
176      * <li><b><tt>header</tt></b> : String<div class="sub-desc">See {@link Ext.grid.Column}.
177      * {@link Ext.grid.Column#header header} for details.</div></li>
178      * <li><b><tt>tpl</tt></b> : String<div class="sub-desc">Specify a string to pass as the
179      * configuration string for {@link Ext.XTemplate}.  By default an {@link Ext.XTemplate}
180      * will be implicitly created using the <tt>dataIndex</tt>.</div></li>
181      * <li><b><tt>width</tt></b> : Number<div class="sub-desc">Percentage of the container width
182      * this column should be allocated.  Columns that have no width specified will be
183      * allocated with an equal percentage to fill 100% of the container width.  To easily take
184      * advantage of the full container width, leave the width of at least one column undefined.
185      * Note that if you do not want to take up the full width of the container, the width of
186      * every column needs to be explicitly defined.</div></li>
187      * </ul></div>
188      */
189     <div id="cfg-Ext.list.ListView-columnSort"></div>/**
190      * @cfg {Boolean/Object} columnSort
191      * Specify <tt>true</tt> or specify a configuration object for {@link Ext.list.ListView.Sorter}
192      * to enable the columns to be sortable (defaults to <tt>true</tt>).
193      */
194     columnSort: true,
195     <div id="cfg-Ext.list.ListView-internalTpl"></div>/**
196      * @cfg {String/Array} internalTpl
197      * The template to be used for the header row.  See {@link #tpl} for more details.
198      */
199
200     /*
201      * IE has issues when setting percentage based widths to 100%. Default to 99.
202      */
203     maxWidth: Ext.isIE ? 99 : 100,
204
205     initComponent : function(){
206         if(this.columnResize){
207             this.colResizer = new Ext.list.ColumnResizer(this.colResizer);
208             this.colResizer.init(this);
209         }
210         if(this.columnSort){
211             this.colSorter = new Ext.list.Sorter(this.columnSort);
212             this.colSorter.init(this);
213         }
214         if(!this.internalTpl){
215             this.internalTpl = new Ext.XTemplate(
216                 '<div class="x-list-header"><div class="x-list-header-inner">',
217                     '<tpl for="columns">',
218                     '<div style="width:{[values.width*100]}%;text-align:{align};"><em unselectable="on" id="',this.id, '-xlhd-{#}">',
219                         '{header}',
220                     '</em></div>',
221                     '</tpl>',
222                     '<div class="x-clear"></div>',
223                 '</div></div>',
224                 '<div class="x-list-body"><div class="x-list-body-inner">',
225                 '</div></div>'
226             );
227         }
228         if(!this.tpl){
229             this.tpl = new Ext.XTemplate(
230                 '<tpl for="rows">',
231                     '<dl>',
232                         '<tpl for="parent.columns">',
233                         '<dt style="width:{[values.width*100]}%;text-align:{align};">',
234                         '<em unselectable="on"<tpl if="cls"> class="{cls}</tpl>">',
235                             '{[values.tpl.apply(parent)]}',
236                         '</em></dt>',
237                         '</tpl>',
238                         '<div class="x-clear"></div>',
239                     '</dl>',
240                 '</tpl>'
241             );
242         };
243
244         var cs = this.columns,
245             allocatedWidth = 0,
246             colsWithWidth = 0,
247             len = cs.length,
248             columns = [];
249
250         for(var i = 0; i < len; i++){
251             var c = cs[i];
252             if(!c.isColumn) {
253                 c.xtype = c.xtype ? (/^lv/.test(c.xtype) ? c.xtype : 'lv' + c.xtype) : 'lvcolumn';
254                 c = Ext.create(c);
255             }
256             if(c.width) {
257                 allocatedWidth += c.width*100;
258                 colsWithWidth++;
259             }
260             columns.push(c);
261         }
262
263         cs = this.columns = columns;
264
265         // auto calculate missing column widths
266         if(colsWithWidth < len){
267             var remaining = len - colsWithWidth;
268             if(allocatedWidth < this.maxWidth){
269                 var perCol = ((this.maxWidth-allocatedWidth) / remaining)/100;
270                 for(var j = 0; j < len; j++){
271                     var c = cs[j];
272                     if(!c.width){
273                         c.width = perCol;
274                     }
275                 }
276             }
277         }
278         Ext.list.ListView.superclass.initComponent.call(this);
279     },
280
281     onRender : function(){
282         this.autoEl = {
283             cls: 'x-list-wrap'
284         };
285         Ext.list.ListView.superclass.onRender.apply(this, arguments);
286
287         this.internalTpl.overwrite(this.el, {columns: this.columns});
288
289         this.innerBody = Ext.get(this.el.dom.childNodes[1].firstChild);
290         this.innerHd = Ext.get(this.el.dom.firstChild.firstChild);
291
292         if(this.hideHeaders){
293             this.el.dom.firstChild.style.display = 'none';
294         }
295     },
296
297     getTemplateTarget : function(){
298         return this.innerBody;
299     },
300
301     <div id="method-Ext.list.ListView-collectData"></div>/**
302      * <p>Function which can be overridden which returns the data object passed to this
303      * view's {@link #tpl template} to render the whole ListView. The returned object
304      * shall contain the following properties:</p>
305      * <div class="mdetail-params"><ul>
306      * <li><b>columns</b> : String<div class="sub-desc">See <tt>{@link #columns}</tt></div></li>
307      * <li><b>rows</b> : String<div class="sub-desc">See
308      * <tt>{@link Ext.DataView}.{@link Ext.DataView#collectData collectData}</div></li>
309      * </ul></div>
310      * @param {Array} records An Array of {@link Ext.data.Record}s to be rendered into the DataView.
311      * @param {Number} startIndex the index number of the Record being prepared for rendering.
312      * @return {Object} A data object containing properties to be processed by a repeating
313      * XTemplate as described above.
314      */
315     collectData : function(){
316         var rs = Ext.list.ListView.superclass.collectData.apply(this, arguments);
317         return {
318             columns: this.columns,
319             rows: rs
320         }
321     },
322
323     verifyInternalSize : function(){
324         if(this.lastSize){
325             this.onResize(this.lastSize.width, this.lastSize.height);
326         }
327     },
328
329     // private
330     onResize : function(w, h){
331         var bd = this.innerBody.dom;
332         var hd = this.innerHd.dom;
333         if(!bd){
334             return;
335         }
336         var bdp = bd.parentNode;
337         if(Ext.isNumber(w)){
338             var sw = w - Ext.num(this.scrollOffset, Ext.getScrollBarWidth());
339             if(this.reserveScrollOffset || ((bdp.offsetWidth - bdp.clientWidth) > 10)){
340                 bd.style.width = sw + 'px';
341                 hd.style.width = sw + 'px';
342             }else{
343                 bd.style.width = w + 'px';
344                 hd.style.width = w + 'px';
345                 setTimeout(function(){
346                     if((bdp.offsetWidth - bdp.clientWidth) > 10){
347                         bd.style.width = sw + 'px';
348                         hd.style.width = sw + 'px';
349                     }
350                 }, 10);
351             }
352         }
353         if(Ext.isNumber(h)){
354             bdp.style.height = (h - hd.parentNode.offsetHeight) + 'px';
355         }
356     },
357
358     updateIndexes : function(){
359         Ext.list.ListView.superclass.updateIndexes.apply(this, arguments);
360         this.verifyInternalSize();
361     },
362
363     findHeaderIndex : function(hd){
364         hd = hd.dom || hd;
365         var pn = hd.parentNode, cs = pn.parentNode.childNodes;
366         for(var i = 0, c; c = cs[i]; i++){
367             if(c == pn){
368                 return i;
369             }
370         }
371         return -1;
372     },
373
374     setHdWidths : function(){
375         var els = this.innerHd.dom.getElementsByTagName('div');
376         for(var i = 0, cs = this.columns, len = cs.length; i < len; i++){
377             els[i].style.width = (cs[i].width*100) + '%';
378         }
379     }
380 });
381
382 Ext.reg('listview', Ext.list.ListView);
383
384 // Backwards compatibility alias
385 Ext.ListView = Ext.list.ListView;</pre>    
386 </body>
387 </html>