src/grid/Panel.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @author Aaron Conran
  17  * @docauthor Ed Spencer
  18  *
  19  * Grids are an excellent way of showing large amounts of tabular data on the client side. Essentially a supercharged
  20  * `<table>`, GridPanel makes it easy to fetch, sort and filter large amounts of data.
  21  *
  22  * Grids are composed of two main pieces - a {@link Ext.data.Store Store} full of data and a set of columns to render.
  23  *
  24  * ## Basic GridPanel
  25  *
  26  *     @example
  27  *     Ext.create('Ext.data.Store', {
  28  *         storeId:'simpsonsStore',
  29  *         fields:['name', 'email', 'phone'],
  30  *         data:{'items':[
  31  *             { 'name': 'Lisa',  "email":"lisa@simpsons.com",  "phone":"555-111-1224"  },
  32  *             { 'name': 'Bart',  "email":"bart@simpsons.com",  "phone":"555-222-1234" },
  33  *             { 'name': 'Homer', "email":"home@simpsons.com",  "phone":"555-222-1244"  },
  34  *             { 'name': 'Marge', "email":"marge@simpsons.com", "phone":"555-222-1254"  }
  35  *         ]},
  36  *         proxy: {
  37  *             type: 'memory',
  38  *             reader: {
  39  *                 type: 'json',
  40  *                 root: 'items'
  41  *             }
  42  *         }
  43  *     });
  44  *
  45  *     Ext.create('Ext.grid.Panel', {
  46  *         title: 'Simpsons',
  47  *         store: Ext.data.StoreManager.lookup('simpsonsStore'),
  48  *         columns: [
  49  *             { header: 'Name',  dataIndex: 'name' },
  50  *             { header: 'Email', dataIndex: 'email', flex: 1 },
  51  *             { header: 'Phone', dataIndex: 'phone' }
  52  *         ],
  53  *         height: 200,
  54  *         width: 400,
  55  *         renderTo: Ext.getBody()
  56  *     });
  57  *
  58  * The code above produces a simple grid with three columns. We specified a Store which will load JSON data inline.
  59  * In most apps we would be placing the grid inside another container and wouldn't need to use the
  60  * {@link #height}, {@link #width} and {@link #renderTo} configurations but they are included here to make it easy to get
  61  * up and running.
  62  *
  63  * The grid we created above will contain a header bar with a title ('Simpsons'), a row of column headers directly underneath
  64  * and finally the grid rows under the headers.
  65  *
  66  * ## Configuring columns
  67  *
  68  * By default, each column is sortable and will toggle between ASC and DESC sorting when you click on its header. Each
  69  * column header is also reorderable by default, and each gains a drop-down menu with options to hide and show columns.
  70  * It's easy to configure each column - here we use the same example as above and just modify the columns config:
  71  *
  72  *     columns: [
  73  *         {
  74  *             header: 'Name',
  75  *             dataIndex: 'name',
  76  *             sortable: false,
  77  *             hideable: false,
  78  *             flex: 1
  79  *         },
  80  *         {
  81  *             header: 'Email',
  82  *             dataIndex: 'email',
  83  *             hidden: true
  84  *         },
  85  *         {
  86  *             header: 'Phone',
  87  *             dataIndex: 'phone',
  88  *             width: 100
  89  *         }
  90  *     ]
  91  *
  92  * We turned off sorting and hiding on the 'Name' column so clicking its header now has no effect. We also made the Email
  93  * column hidden by default (it can be shown again by using the menu on any other column). We also set the Phone column to
  94  * a fixed with of 100px and flexed the Name column, which means it takes up all remaining width after the other columns
  95  * have been accounted for. See the {@link Ext.grid.column.Column column docs} for more details.
  96  *
  97  * ## Renderers
  98  *
  99  * As well as customizing columns, it's easy to alter the rendering of individual cells using renderers. A renderer is
 100  * tied to a particular column and is passed the value that would be rendered into each cell in that column. For example,
 101  * we could define a renderer function for the email column to turn each email address into a mailto link:
 102  *
 103  *     columns: [
 104  *         {
 105  *             header: 'Email',
 106  *             dataIndex: 'email',
 107  *             renderer: function(value) {
 108  *                 return Ext.String.format('<a href="mailto:{0}">{1}</a>', value, value);
 109  *             }
 110  *         }
 111  *     ]
 112  *
 113  * See the {@link Ext.grid.column.Column column docs} for more information on renderers.
 114  *
 115  * ## Selection Models
 116  *
 117  * Sometimes all you want is to render data onto the screen for viewing, but usually it's necessary to interact with or
 118  * update that data. Grids use a concept called a Selection Model, which is simply a mechanism for selecting some part of
 119  * the data in the grid. The two main types of Selection Model are RowSelectionModel, where entire rows are selected, and
 120  * CellSelectionModel, where individual cells are selected.
 121  *
 122  * Grids use a Row Selection Model by default, but this is easy to customise like so:
 123  *
 124  *     Ext.create('Ext.grid.Panel', {
 125  *         selType: 'cellmodel',
 126  *         store: ...
 127  *     });
 128  *
 129  * Specifying the `cellmodel` changes a couple of things. Firstly, clicking on a cell now
 130  * selects just that cell (using a {@link Ext.selection.RowModel rowmodel} will select the entire row), and secondly the
 131  * keyboard navigation will walk from cell to cell instead of row to row. Cell-based selection models are usually used in
 132  * conjunction with editing.
 133  *
 134  * ## Editing
 135  *
 136  * Grid has built-in support for in-line editing. There are two chief editing modes - cell editing and row editing. Cell
 137  * editing is easy to add to your existing column setup - here we'll just modify the example above to include an editor
 138  * on both the name and the email columns:
 139  *
 140  *     Ext.create('Ext.grid.Panel', {
 141  *         title: 'Simpsons',
 142  *         store: Ext.data.StoreManager.lookup('simpsonsStore'),
 143  *         columns: [
 144  *             { header: 'Name',  dataIndex: 'name', field: 'textfield' },
 145  *             { header: 'Email', dataIndex: 'email', flex: 1,
 146  *                 field: {
 147  *                     xtype: 'textfield',
 148  *                     allowBlank: false
 149  *                 }
 150  *             },
 151  *             { header: 'Phone', dataIndex: 'phone' }
 152  *         ],
 153  *         selType: 'cellmodel',
 154  *         plugins: [
 155  *             Ext.create('Ext.grid.plugin.CellEditing', {
 156  *                 clicksToEdit: 1
 157  *             })
 158  *         ],
 159  *         height: 200,
 160  *         width: 400,
 161  *         renderTo: Ext.getBody()
 162  *     });
 163  *
 164  * This requires a little explanation. We're passing in {@link #store store} and {@link #columns columns} as normal, but
 165  * this time we've also specified a {@link Ext.grid.column.Column#field field} on two of our columns. For the Name column
 166  * we just want a default textfield to edit the value, so we specify 'textfield'. For the Email column we customized the
 167  * editor slightly by passing allowBlank: false, which will provide inline validation.
 168  *
 169  * To support cell editing, we also specified that the grid should use the 'cellmodel' {@link #selType}, and created an
 170  * instance of the {@link Ext.grid.plugin.CellEditing CellEditing plugin}, which we configured to activate each editor after a
 171  * single click.
 172  *
 173  * ## Row Editing
 174  *
 175  * The other type of editing is row-based editing, using the RowEditor component. This enables you to edit an entire row
 176  * at a time, rather than editing cell by cell. Row Editing works in exactly the same way as cell editing, all we need to
 177  * do is change the plugin type to {@link Ext.grid.plugin.RowEditing}, and set the selType to 'rowmodel':
 178  *
 179  *     Ext.create('Ext.grid.Panel', {
 180  *         title: 'Simpsons',
 181  *         store: Ext.data.StoreManager.lookup('simpsonsStore'),
 182  *         columns: [
 183  *             { header: 'Name',  dataIndex: 'name', field: 'textfield' },
 184  *             { header: 'Email', dataIndex: 'email', flex:1,
 185  *                 field: {
 186  *                     xtype: 'textfield',
 187  *                     allowBlank: false
 188  *                 }
 189  *             },
 190  *             { header: 'Phone', dataIndex: 'phone' }
 191  *         ],
 192  *         selType: 'rowmodel',
 193  *         plugins: [
 194  *             Ext.create('Ext.grid.plugin.RowEditing', {
 195  *                 clicksToEdit: 1
 196  *             })
 197  *         ],
 198  *         height: 200,
 199  *         width: 400,
 200  *         renderTo: Ext.getBody()
 201  *     });
 202  *
 203  * Again we passed some configuration to our {@link Ext.grid.plugin.RowEditing} plugin, and now when we click each row a row
 204  * editor will appear and enable us to edit each of the columns we have specified an editor for.
 205  *
 206  * ## Sorting & Filtering
 207  *
 208  * Every grid is attached to a {@link Ext.data.Store Store}, which provides multi-sort and filtering capabilities. It's
 209  * easy to set up a grid to be sorted from the start:
 210  *
 211  *     var myGrid = Ext.create('Ext.grid.Panel', {
 212  *         store: {
 213  *             fields: ['name', 'email', 'phone'],
 214  *             sorters: ['name', 'phone']
 215  *         },
 216  *         columns: [
 217  *             { text: 'Name',  dataIndex: 'name' },
 218  *             { text: 'Email', dataIndex: 'email' }
 219  *         ]
 220  *     });
 221  *
 222  * Sorting at run time is easily accomplished by simply clicking each column header. If you need to perform sorting on
 223  * more than one field at run time it's easy to do so by adding new sorters to the store:
 224  *
 225  *     myGrid.store.sort([
 226  *         { property: 'name',  direction: 'ASC' },
 227  *         { property: 'email', direction: 'DESC' }
 228  *     ]);
 229  *
 230  * See {@link Ext.data.Store} for examples of filtering.
 231  *
 232  * ## Grouping
 233  *
 234  * Grid supports the grouping of rows by any field. For example if we had a set of employee records, we might want to
 235  * group by the department that each employee works in. Here's how we might set that up:
 236  *
 237  *     @example
 238  *     var store = Ext.create('Ext.data.Store', {
 239  *         storeId:'employeeStore',
 240  *         fields:['name', 'senority', 'department'],
 241  *         groupField: 'department',
 242  *         data: {'employees':[
 243  *             { "name": "Michael Scott",  "senority": 7, "department": "Manangement" },
 244  *             { "name": "Dwight Schrute", "senority": 2, "department": "Sales" },
 245  *             { "name": "Jim Halpert",    "senority": 3, "department": "Sales" },
 246  *             { "name": "Kevin Malone",   "senority": 4, "department": "Accounting" },
 247  *             { "name": "Angela Martin",  "senority": 5, "department": "Accounting" }
 248  *         ]},
 249  *         proxy: {
 250  *             type: 'memory',
 251  *             reader: {
 252  *                 type: 'json',
 253  *                 root: 'employees'
 254  *             }
 255  *         }
 256  *     });
 257  *
 258  *     Ext.create('Ext.grid.Panel', {
 259  *         title: 'Employees',
 260  *         store: Ext.data.StoreManager.lookup('employeeStore'),
 261  *         columns: [
 262  *             { header: 'Name',     dataIndex: 'name' },
 263  *             { header: 'Senority', dataIndex: 'senority' }
 264  *         ],
 265  *         features: [{ftype:'grouping'}],
 266  *         width: 200,
 267  *         height: 275,
 268  *         renderTo: Ext.getBody()
 269  *     });
 270  *
 271  * ## Infinite Scrolling
 272  *
 273  * Grid supports infinite scrolling as an alternative to using a paging toolbar. Your users can scroll through thousands
 274  * of records without the performance penalties of renderering all the records on screen at once. The grid should be bound
 275  * to a store with a pageSize specified.
 276  *
 277  *     var grid = Ext.create('Ext.grid.Panel', {
 278  *         // Use a PagingGridScroller (this is interchangeable with a PagingToolbar)
 279  *         verticalScrollerType: 'paginggridscroller',
 280  *         // do not reset the scrollbar when the view refreshs
 281  *         invalidateScrollerOnRefresh: false,
 282  *         // infinite scrolling does not support selection
 283  *         disableSelection: true,
 284  *         // ...
 285  *     });
 286  *
 287  * ## Paging
 288  *
 289  * Grid supports paging through large sets of data via a PagingToolbar or PagingGridScroller (see the Infinite Scrolling section above).
 290  * To leverage paging via a toolbar or scroller, you need to set a pageSize configuration on the Store.
 291  *
 292  *     @example
 293  *     var itemsPerPage = 2;   // set the number of items you want per page
 294  *
 295  *     var store = Ext.create('Ext.data.Store', {
 296  *         id:'simpsonsStore',
 297  *         autoLoad: false,
 298  *         fields:['name', 'email', 'phone'],
 299  *         pageSize: itemsPerPage, // items per page
 300  *         proxy: {
 301  *             type: 'ajax',
 302  *             url: 'pagingstore.js',  // url that will load data with respect to start and limit params
 303  *             reader: {
 304  *                 type: 'json',
 305  *                 root: 'items',
 306  *                 totalProperty: 'total'
 307  *             }
 308  *         }
 309  *     });
 310  *
 311  *     // specify segment of data you want to load using params
 312  *     store.load({
 313  *         params:{
 314  *             start:0,
 315  *             limit: itemsPerPage
 316  *         }
 317  *     });
 318  *
 319  *     Ext.create('Ext.grid.Panel', {
 320  *         title: 'Simpsons',
 321  *         store: store,
 322  *         columns: [
 323  *             {header: 'Name',  dataIndex: 'name'},
 324  *             {header: 'Email', dataIndex: 'email', flex:1},
 325  *             {header: 'Phone', dataIndex: 'phone'}
 326  *         ],
 327  *         width: 400,
 328  *         height: 125,
 329  *         dockedItems: [{
 330  *             xtype: 'pagingtoolbar',
 331  *             store: store,   // same store GridPanel is using
 332  *             dock: 'bottom',
 333  *             displayInfo: true
 334  *         }],
 335  *         renderTo: Ext.getBody()
 336  *     });
 337  */
 338 Ext.define('Ext.grid.Panel', {
 339     extend: 'Ext.panel.Table',
 340     requires: ['Ext.grid.View'],
 341     alias: ['widget.gridpanel', 'widget.grid'],
 342     alternateClassName: ['Ext.list.ListView', 'Ext.ListView', 'Ext.grid.GridPanel'],
 343     viewType: 'gridview',
 344
 345     lockable: false,
 346
 347     // Required for the Lockable Mixin. These are the configurations which will be copied to the
 348     // normal and locked sub tablepanels
 349     normalCfgCopy: ['invalidateScrollerOnRefresh', 'verticalScroller', 'verticalScrollDock', 'verticalScrollerType', 'scroll'],
 350     lockedCfgCopy: ['invalidateScrollerOnRefresh'],
 351
 352     /**
 353      * @cfg {Boolean} [columnLines=false] Adds column line styling
 354      */
 355
 356     initComponent: function() {
 357         var me = this;
 358
 359         if (me.columnLines) {
 360             me.setColumnLines(me.columnLines);
 361         }
 362
 363         me.callParent();
 364     },
 365
 366     setColumnLines: function(show) {
 367         var me = this,
 368             method = (show) ? 'addClsWithUI' : 'removeClsWithUI';
 369
 370         me[method]('with-col-lines');
 371     }
 372 });
 373