lib/yui/3.5.0/build/datatable-base/datatable-base.js

   1 /*
   2 YUI 3.5.0 (build 5089)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('datatable-base', function(Y) {
   8
   9 /**
  10 A Widget for displaying tabular data.  The base implementation of DataTable
  11 provides the ability to dynamically generate an HTML table from a set of column
  12 configurations and row data.
  13
  14 Two classes are included in the `datatable-base` module: `Y.DataTable` and
  15 `Y.DataTable.Base`.
  16
  17 @module datatable
  18 @submodule datatable-base
  19 @main datatable
  20 @since 3.5.0
  21 **/
  22
  23 // DataTable API docs included before DataTable.Base to make yuidoc work
  24 /**
  25 A Widget for displaying tabular data.  Before feature modules are `use()`d,
  26 this class is functionally equivalent to DataTable.Base.  However, feature
  27 modules can modify this class in non-destructive ways, expanding the API and
  28 functionality.
  29
  30 This is the primary DataTable class.  Out of the box, it provides the ability
  31 to dynamically generate an HTML table from a set of column configurations and
  32 row data.  But feature module inclusion can add table sorting, pagintaion,
  33 highlighting, selection, and more.
  34
  35 <pre><code>
  36 // The functionality of this table would require additional modules be use()d,
  37 // but the feature APIs are aggregated onto Y.DataTable.
  38 // (Snippet is for illustration. Not all features are available today.)
  39 var table = new Y.DataTable({
  40     columns: [
  41         { type: 'checkbox', defaultChecked: true },
  42         { key: 'firstName', sortable: true, resizable: true },
  43         { key: 'lastName', sortable: true },
  44         { key: 'role', formatter: toRoleName }
  45     ],
  46     data: {
  47         source: 'http://myserver.com/service/json',
  48         type: 'json',
  49         schema: {
  50             resultListLocator: 'results.users',
  51             fields: [
  52                 'username',
  53                 'firstName',
  54                 'lastName',
  55                 { key: 'role', type: 'number' }
  56             ]
  57         }
  58     },
  59     recordType: UserModel,
  60     pagedData: {
  61         location: 'footer',
  62         pageSizes: [20, 50, 'all'],
  63         rowsPerPage: 20,
  64         pageLinks: 5
  65     },
  66     editable: true
  67 });
  68 </code></pre>
  69
  70 ### Column Configuration
  71
  72 The column configurations are set in the form of an array of objects, where
  73 each object corresponds to a column.  For columns populated directly from the
  74 row data, a 'key' property is required to bind the column to that property or
  75 attribute in the row data.
  76
  77 Not all columns need to relate to row data, nor do all properties or attributes
  78 of the row data need to have a corresponding column.  However, only those
  79 columns included in the `columns` configuration attribute will be rendered.
  80
  81 Other column configuration properties are supported by the configured
  82 `headerView`, `bodyView`, `footerView` classes as well as any features added by
  83 plugins or class extensions.  See the description of DataTable.HeaderView,
  84 DataTable.BodyView, and other DataTable feature classes to see what column
  85 properties they support.
  86
  87 Some examples of column configurations would be:
  88
  89 <pre><code>
  90 // Basic
  91 var columns = [{ key: 'firstName' }, { key: 'lastName' }, { key: 'age' }];
  92
  93 // For columns without any additional configuration, strings can be used
  94 var columns = ['firstName', 'lastName', 'age'];
  95
  96 // Multi-row column headers (see DataTable.HeaderView for details)
  97 var columns = [
  98     {
  99         label: 'Name',
 100         children: [
 101             { key: 'firstName' },
 102             { key: 'lastName' }
 103         ]
 104     },
 105     'age' // mixing and matching objects and strings is ok
 106 ];
 107
 108 // Including columns that are not related 1:1 to row data fields/attributes
 109 // (See DataTable.BodyView for details)
 110 var columns = [
 111     {
 112         label: 'Name', // Needed for the column header
 113         formatter: function (o) {
 114             // Fill the column cells with data from firstName and lastName
 115             if (o.data.age > 55) {
 116                 o.className += ' senior';
 117             }
 118             return o.data.lastName + ', ' + o.data.firstName;
 119         }
 120     },
 121     'age'
 122 ];
 123
 124 // Columns that include feature configurations (for illustration; not all
 125 // features are available today).
 126 var columns = [
 127     { type: 'checkbox', defaultChecked: true },
 128     { key: 'firstName', sortable: true, resizable: true, min-width: '300px' },
 129     { key: 'lastName', sortable: true, resizable: true, min-width: '300px' },
 130     { key: 'age', emptyCellValue: '<em>unknown</em>' }
 131 ];
 132 </code></pre>
 133
 134 ### Row Data Configuration
 135
 136 The `data` configuration attribute is responsible for housing the data objects that will be rendered as rows.  You can provide this information in two ways by default:
 137
 138 1. An array of simple objects with key:value pairs
 139 2. A ModelList of Base-based class instances (presumably Model subclass
 140    instances)
 141
 142 If an array of objects is passed, it will be translated into a ModelList filled
 143 with instances of the class provided to the `recordType` attribute.  This
 144 attribute can also create a custom Model subclass from an array of field names
 145 or an object of attribute configurations.  If no `recordType` is provided, one
 146 will be created for you from available information (see `_initRecordType`).
 147 Providing either your own ModelList instance for `data`, or at least Model
 148 class for `recordType`, is the best way to control client-server
 149 synchronization when modifying data on the client side.
 150
 151 The ModelList instance that manages the table's data is available in the `data`
 152 property on the DataTable instance.
 153
 154
 155 ### Rendering
 156
 157 Table rendering is a collaborative process between the DataTable and its
 158 configured `headerView`, `bodyView`, and `footerView`.  The DataTable renders
 159 the `<table>` and `<caption>`, but the contents of the table are delegated to
 160 instances of the classes provided to the `headerView`, `bodyView`, and
 161 `footerView` attributes. If any of these attributes is unset, that portion of
 162 the table won't be rendered.
 163
 164 DataTable.Base assigns the default `headerView` to `Y.DataTable.HeaderView` and
 165 the default `bodyView` to `Y.DataTable.BodyView`, though either can be
 166 overridden for custom rendering.  No default `footerView` is assigned. See
 167 those classes for more details about how they operate.
 168
 169
 170 @class DataTable
 171 @extends DataTable.Base
 172 @since 3.5.0
 173 **/
 174
 175 // DataTable API docs included before DataTable.Base to make yuidoc work
 176 /**
 177 The baseline implementation of a DataTable.  This class should be used
 178 primarily as a superclass for a custom DataTable with a specific set of
 179 features.  Because features can be composed onto `Y.DataTable`, custom
 180 subclasses of DataTable.Base will remain unmodified when new feature modules
 181 are loaded.
 182
 183 Example usage might look like this:
 184
 185 <pre><code>
 186 // Custom subclass with only sorting and mutability added.  If other datatable
 187 // feature modules are loaded, this class will not be affected.
 188 var MyTableClass = Y.Base.create('table', Y.DataTable.Base,
 189                        [ Y.DataTable.Sort, Y.DataTable.Mutable ]);
 190
 191 var table = new MyTableClass({
 192     columns: ['firstName', 'lastName', 'age'],
 193     data: [
 194         { firstName: 'Frank', lastName: 'Zappa', age: 71 },
 195         { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
 196         { firstName: 'Albert', lastName: 'Einstein', age: 132 },
 197         ...
 198     ]
 199 });
 200
 201 table.render('#over-there');
 202
 203 // DataTable.Base can be instantiated if a featureless table is needed.
 204 var table = new Y.DataTable.Base({
 205     columns: ['firstName', 'lastName', 'age'],
 206     data: [
 207         { firstName: 'Frank', lastName: 'Zappa', age: 71 },
 208         { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
 209         { firstName: 'Albert', lastName: 'Einstein', age: 132 },
 210         ...
 211     ]
 212 });
 213
 214 table.render('#in-here');
 215 </code></pre>
 216
 217 DataTable.Base is built from DataTable.Core, and sets the default `headerView`
 218 to `Y.DataTable.HeaderView` and default `bodyView` to `Y.DataTable.BodyView`.
 219
 220 @class Base
 221 @extends Widget
 222 @uses DataTable.Core
 223 @namespace DataTable
 224 @since 3.5.0
 225 **/
 226 Y.DataTable.Base = Y.Base.create('datatable', Y.Widget, [Y.DataTable.Core],
 227     null, {
 228         ATTRS: {
 229             // Default head and body views
 230             headerView: { value: Y.DataTable.HeaderView },
 231             bodyView  : { value: Y.DataTable.BodyView }
 232         }
 233     });
 234
 235 // The DataTable API docs are above DataTable.Base docs.
 236 Y.DataTable = Y.mix(
 237     Y.Base.create('datatable', Y.DataTable.Base, []), // Create the class
 238     Y.DataTable); // Migrate static and namespaced classes
 239
 240
 241 }, '3.5.0' ,{requires:['datatable-core', 'base-build', 'widget', 'datatable-head', 'datatable-body']});