lib/yuilib/3.13.0/datatable-base/datatable-base-debug.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('datatable-base', function (Y, NAME) {
   9
  10 /**
  11 A Widget for displaying tabular data.  The base implementation of DataTable
  12 provides the ability to dynamically generate an HTML table from a set of column
  13 configurations and row data.
  14
  15 Two classes are included in the `datatable-base` module: `Y.DataTable` and
  16 `Y.DataTable.Base`.
  17
  18 @module datatable
  19 @submodule datatable-base
  20 @main datatable
  21 @since 3.5.0
  22 **/
  23
  24 // DataTable API docs included before DataTable.Base to make yuidoc work
  25 /**
  26 A Widget for displaying tabular data.  Before feature modules are `use()`d,
  27 this class is functionally equivalent to DataTable.Base.  However, feature
  28 modules can modify this class in non-destructive ways, expanding the API and
  29 functionality.
  30
  31 This is the primary DataTable class.  Out of the box, it provides the ability
  32 to dynamically generate an HTML table from a set of column configurations and
  33 row data.  But feature module inclusion can add table sorting, pagintaion,
  34 highlighting, selection, and more.
  35
  36 <pre><code>
  37 // The functionality of this table would require additional modules be use()d,
  38 // but the feature APIs are aggregated onto Y.DataTable.
  39 // (Snippet is for illustration. Not all features are available today.)
  40 var table = new Y.DataTable({
  41     columns: [
  42         { type: 'checkbox', defaultChecked: true },
  43         { key: 'firstName', sortable: true, resizable: true },
  44         { key: 'lastName', sortable: true },
  45         { key: 'role', formatter: toRoleName }
  46     ],
  47     data: {
  48         source: 'http://myserver.com/service/json',
  49         type: 'json',
  50         schema: {
  51             resultListLocator: 'results.users',
  52             fields: [
  53                 'username',
  54                 'firstName',
  55                 'lastName',
  56                 { key: 'role', type: 'number' }
  57             ]
  58         }
  59     },
  60     recordType: UserModel,
  61     pagedData: {
  62         location: 'footer',
  63         pageSizes: [20, 50, 'all'],
  64         rowsPerPage: 20,
  65         pageLinks: 5
  66     },
  67     editable: true
  68 });
  69 </code></pre>
  70
  71 ### Column Configuration
  72
  73 The column configurations are set in the form of an array of objects, where
  74 each object corresponds to a column.  For columns populated directly from the
  75 row data, a 'key' property is required to bind the column to that property or
  76 attribute in the row data.
  77
  78 Not all columns need to relate to row data, nor do all properties or attributes
  79 of the row data need to have a corresponding column.  However, only those
  80 columns included in the `columns` configuration attribute will be rendered.
  81
  82 Other column configuration properties are supported by the configured
  83 `view`, class as well as any features added by plugins or class extensions.
  84 See the description of DataTable.TableView and its subviews
  85 DataTable.HeaderView, DataTable.BodyView, and DataTable.FooterView (and other
  86 DataTable feature classes) to see what column properties they support.
  87
  88 Some examples of column configurations would be:
  89
  90 <pre><code>
  91 // Basic
  92 var columns = [{ key: 'firstName' }, { key: 'lastName' }, { key: 'age' }];
  93
  94 // For columns without any additional configuration, strings can be used
  95 var columns = ['firstName', 'lastName', 'age'];
  96
  97 // Multi-row column headers (see DataTable.HeaderView for details)
  98 var columns = [
  99     {
 100         label: 'Name',
 101         children: [
 102             { key: 'firstName' },
 103             { key: 'lastName' }
 104         ]
 105     },
 106     'age' // mixing and matching objects and strings is ok
 107 ];
 108
 109 // Including columns that are not related 1:1 to row data fields/attributes
 110 // (See DataTable.BodyView for details)
 111 var columns = [
 112     {
 113         label: 'Name', // Needed for the column header
 114         formatter: function (o) {
 115             // Fill the column cells with data from firstName and lastName
 116             if (o.data.age > 55) {
 117                 o.className += ' senior';
 118             }
 119             return o.data.lastName + ', ' + o.data.firstName;
 120         }
 121     },
 122     'age'
 123 ];
 124
 125 // Columns that include feature configurations (for illustration; not all
 126 // features are available today).
 127 var columns = [
 128     { type: 'checkbox', defaultChecked: true },
 129     { key: 'firstName', sortable: true, resizable: true, min-width: '300px' },
 130     { key: 'lastName', sortable: true, resizable: true, min-width: '300px' },
 131     { key: 'age', emptyCellValue: '<em>unknown</em>' }
 132 ];
 133 </code></pre>
 134
 135 ### Row Data Configuration
 136
 137 The `data` configuration attribute is responsible for housing the data objects
 138 that will be rendered as rows.  You can provide this information in two ways by default:
 139
 140 1. An array of simple objects with key:value pairs
 141 2. A ModelList of Base-based class instances (presumably Model subclass
 142    instances)
 143
 144 If an array of objects is passed, it will be translated into a ModelList filled
 145 with instances of the class provided to the `recordType` attribute.  This
 146 attribute can also create a custom Model subclass from an array of field names
 147 or an object of attribute configurations.  If no `recordType` is provided, one
 148 will be created for you from available information (see `_initRecordType`).
 149 Providing either your own ModelList instance for `data`, or at least Model
 150 class for `recordType`, is the best way to control client-server
 151 synchronization when modifying data on the client side.
 152
 153 The ModelList instance that manages the table's data is available in the `data`
 154 property on the DataTable instance.
 155
 156
 157 ### Rendering
 158
 159 Table rendering is a collaborative process between the DataTable and its
 160 configured `view`. The DataTable creates an instance of the configured `view`
 161 (DataTable.TableView by default), and calls its `render()` method.
 162 DataTable.TableView, for instance, then creates the `<table>` and `<caption>`,
 163 then delegates the rendering of the specific sections of the table to subviews,
 164 which can be configured as `headerView`, `bodyView`, and `footerView`.
 165 DataTable.TableView defaults the `headerView` to DataTable.HeaderView and the
 166 `bodyView` to DataTable.BodyView, but leaves the `footerView` unassigned.
 167 Setting any subview to `null` will result in that table section not being
 168 rendered.
 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.Sortable, 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 `view`
 218 to `Y.DataTable.TableView`.
 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
 228     /**
 229     Pass through to `delegate()` called from the `contentBox`.
 230
 231     @method delegate
 232     @param type {String} the event type to delegate
 233     @param fn {Function} the callback function to execute.  This function
 234                  will be provided the event object for the delegated event.
 235     @param spec {String|Function} a selector that must match the target of the
 236                  event or a function to test target and its parents for a match
 237     @param context {Object} optional argument that specifies what 'this' refers to
 238     @param args* {any} 0..n additional arguments to pass on to the callback
 239                  function.  These arguments will be added after the event object.
 240     @return {EventHandle} the detach handle
 241     @since 3.5.0
 242     **/
 243     delegate: function () {
 244         var contentBox = this.get('contentBox');
 245
 246         return contentBox.delegate.apply(contentBox, arguments);
 247     },
 248
 249     /**
 250     Destroys the table `View` if it's been created.
 251
 252     @method destructor
 253     @protected
 254     @since 3.6.0
 255     **/
 256     destructor: function () {
 257         if (this.view) {
 258             this.view.destroy();
 259         }
 260     },
 261
 262     /**
 263     Returns the `<td>` Node from the given row and column index.  Alternately,
 264     the `seed` can be a Node.  If so, the nearest ancestor cell is returned.
 265     If the `seed` is a cell, it is returned.  If there is no cell at the given
 266     coordinates, `null` is returned.
 267
 268     Optionally, include an offset array or string to return a cell near the
 269     cell identified by the `seed`.  The offset can be an array containing the
 270     number of rows to shift followed by the number of columns to shift, or one
 271     of "above", "below", "next", or "previous".
 272
 273     <pre><code>// Previous cell in the previous row
 274     var cell = table.getCell(e.target, [-1, -1]);
 275
 276     // Next cell
 277     var cell = table.getCell(e.target, 'next');
 278     var cell = table.getCell(e.taregt, [0, 1];</pre></code>
 279
 280     This is actually just a pass through to the `view` instance's method
 281     by the same name.
 282
 283     @method getCell
 284     @param {Number[]|Node} seed Array of row and column indexes, or a Node that
 285         is either the cell itself or a descendant of one.
 286     @param {Number[]|String} [shift] Offset by which to identify the returned
 287         cell Node
 288     @return {Node}
 289     @since 3.5.0
 290     **/
 291     getCell: function (/* seed, shift */) {
 292         return this.view && this.view.getCell &&
 293             this.view.getCell.apply(this.view, arguments);
 294     },
 295
 296     /**
 297     Returns the `<tr>` Node from the given row index, Model, or Model's
 298     `clientId`.  If the rows haven't been rendered yet, or if the row can't be
 299     found by the input, `null` is returned.
 300
 301     This is actually just a pass through to the `view` instance's method
 302     by the same name.
 303
 304     @method getRow
 305     @param {Number|String|Model} id Row index, Model instance, or clientId
 306     @return {Node}
 307     @since 3.5.0
 308     **/
 309     getRow: function (/* id */) {
 310         return this.view && this.view.getRow &&
 311             this.view.getRow.apply(this.view, arguments);
 312     },
 313
 314     /**
 315     Updates the `_displayColumns` property.
 316
 317     @method _afterDisplayColumnsChange
 318     @param {EventFacade} e The `columnsChange` event
 319     @protected
 320     @since 3.6.0
 321     **/
 322     // FIXME: This is a kludge for back compat with features that reference
 323     // _displayColumns.  They should be updated to TableView plugins.
 324     _afterDisplayColumnsChange: function (e) {
 325         this._extractDisplayColumns(e.newVal || []);
 326     },
 327
 328     /**
 329     Attaches subscriptions to relay core change events to the view.
 330
 331     @method bindUI
 332     @protected
 333     @since 3.6.0
 334     **/
 335     bindUI: function () {
 336         this._eventHandles.relayCoreChanges = this.after(
 337             ['columnsChange',
 338              'dataChange',
 339              'summaryChange',
 340              'captionChange',
 341              'widthChange'],
 342             Y.bind('_relayCoreAttrChange', this));
 343     },
 344
 345     /**
 346     The default behavior of the `renderView` event.  Calls `render()` on the
 347     `View` instance on the event.
 348
 349     @method _defRenderViewFn
 350     @param {EventFacade} e The `renderView` event
 351     @protected
 352     **/
 353     _defRenderViewFn: function (e) {
 354         e.view.render();
 355     },
 356
 357     /**
 358     Processes the full column array, distilling the columns down to those that
 359     correspond to cell data columns.
 360
 361     @method _extractDisplayColumns
 362     @param {Object[]} columns The full set of table columns
 363     @protected
 364     **/
 365     // FIXME: this is a kludge for back compat, duplicating logic in the
 366     // tableView
 367     _extractDisplayColumns: function (columns) {
 368         var displayColumns = [];
 369
 370         function process(cols) {
 371             var i, len, col;
 372
 373             for (i = 0, len = cols.length; i < len; ++i) {
 374                 col = cols[i];
 375
 376                 if (Y.Lang.isArray(col.children)) {
 377                     process(col.children);
 378                 } else {
 379                     displayColumns.push(col);
 380                 }
 381             }
 382         }
 383
 384         process(columns);
 385
 386         /**
 387         Array of the columns that correspond to those with value cells in the
 388         data rows. Excludes colspan header columns (configured with `children`).
 389
 390         @property _displayColumns
 391         @type {Object[]}
 392         @since 3.5.0
 393         **/
 394         this._displayColumns = displayColumns;
 395     },
 396
 397     /**
 398     Sets up the instance's events.
 399
 400     @method initializer
 401     @param {Object} [config] Configuration object passed at construction
 402     @protected
 403     @since 3.6.0
 404     **/
 405     initializer: function () {
 406         this.publish('renderView', {
 407             defaultFn: Y.bind('_defRenderViewFn', this)
 408         });
 409
 410         // Have to use get('columns'), not config.columns because the setter
 411         // needs to transform string columns to objects.
 412         this._extractDisplayColumns(this.get('columns') || []);
 413
 414         // FIXME: kludge for back compat of features that reference
 415         // _displayColumns on the instance.  They need to be updated to
 416         // TableView plugins, most likely.
 417         this.after('columnsChange', Y.bind('_afterDisplayColumnsChange', this));
 418     },
 419
 420     /**
 421     Relays attribute changes to the instance's `view`.
 422
 423     @method _relayCoreAttrChange
 424     @param {EventFacade} e The change event
 425     @protected
 426     @since 3.6.0
 427     **/
 428     _relayCoreAttrChange: function (e) {
 429         var attr = (e.attrName === 'data') ? 'modelList' : e.attrName;
 430
 431         this.view.set(attr, e.newVal);
 432     },
 433
 434     /**
 435     Instantiates the configured `view` class that will be responsible for
 436     setting up the View class.
 437
 438     @method @renderUI
 439     @protected
 440     @since 3.6.0
 441     **/
 442     renderUI: function () {
 443         var self = this,
 444             View = this.get('view');
 445
 446         if (View) {
 447             this.view = new View(
 448                 Y.merge(
 449                     this.getAttrs(),
 450                     {
 451                         host     : this,
 452                         container: this.get('contentBox'),
 453                         modelList: this.data
 454                     },
 455                     this.get('viewConfig')));
 456
 457             // For back compat, share the view instances and primary nodes
 458             // on this instance.
 459             // TODO: Remove this?
 460             if (!this._eventHandles.legacyFeatureProps) {
 461                 this._eventHandles.legacyFeatureProps = this.view.after({
 462                     renderHeader: function (e) {
 463                         self.head = e.view;
 464                         self._theadNode = e.view.theadNode;
 465                         // TODO: clean up the repetition.
 466                         // This is here so that subscribers to renderHeader etc
 467                         // have access to this._tableNode from the DT instance
 468                         self._tableNode = e.view.get('container');
 469                     },
 470                     renderFooter: function (e) {
 471                         self.foot = e.view;
 472                         self._tfootNode = e.view.tfootNode;
 473                         self._tableNode = e.view.get('container');
 474                     },
 475                     renderBody: function (e) {
 476                         self.body = e.view;
 477                         self._tbodyNode = e.view.tbodyNode;
 478                         self._tableNode = e.view.get('container');
 479                     },
 480                     // FIXME: guarantee that the properties are available, even
 481                     // if the configured (or omitted) views don't create them
 482                     renderTable: function () {
 483                         var contentBox = this.get('container');
 484
 485                         self._tableNode = this.tableNode ||
 486                             contentBox.one('.' + this.getClassName('table') +
 487                                            ', table');
 488
 489                         // FIXME: _captionNode isn't available until after
 490                         // renderTable unless in the renderX subs I look for
 491                         // it under the container's parentNode (to account for
 492                         // scroll breaking out the caption table).
 493                         self._captionNode = this.captionNode ||
 494                             contentBox.one('caption');
 495
 496                         if (!self._theadNode) {
 497                             self._theadNode = contentBox.one(
 498                                 '.' + this.getClassName('columns') + ', thead');
 499                         }
 500
 501                         if (!self._tbodyNode) {
 502                             self._tbodyNode = contentBox.one(
 503                                 '.' + this.getClassName('data') + ', tbody');
 504                         }
 505
 506                         if (!self._tfootNode) {
 507                             self._tfootNode = contentBox.one(
 508                                 '.' + this.getClassName('footer') + ', tfoot');
 509                         }
 510                     }
 511                 });
 512             }
 513
 514             // To *somewhat* preserve table.on('renderHeader', fn) in the
 515             // form of table.on('table:renderHeader', fn), because I couldn't
 516             // figure out another option.
 517             this.view.addTarget(this);
 518         }
 519     },
 520
 521     /**
 522     Fires the `renderView` event, delegating UI updates to the configured View.
 523
 524     @method syncUI
 525     @since 3.5.0
 526     **/
 527     syncUI: function () {
 528         if (this.view) {
 529             this.fire('renderView', { view: this.view });
 530         }
 531     },
 532
 533     /**
 534     Verifies the input value is a function with a `render` method on its
 535     prototype.  `null` is also accepted to remove the default View.
 536
 537     @method _validateView
 538     @protected
 539     @since 3.5.0
 540     **/
 541     _validateView: function (val) {
 542         // TODO support View instances?
 543         return val === null || (Y.Lang.isFunction(val) && val.prototype.render);
 544     }
 545 }, {
 546     ATTRS: {
 547         /**
 548         The View class used to render the `<table>` into the Widget's
 549         `contentBox`.  This View can handle the entire table rendering itself
 550         or delegate to other Views.
 551
 552         It is not strictly necessary that the class function assigned here be
 553         a View subclass.  It must however have a `render()` method.
 554
 555         When the DataTable is rendered, an instance of this View will be
 556         created and its `render()` method called.  The View instance will be
 557         assigned to the DataTable instance's `view` property.
 558
 559         @attribute view
 560         @type {Function}
 561         @default Y.DataTable.TableView
 562         @since 3.6.0
 563         **/
 564         view: {
 565             value: Y.DataTable.TableView,
 566             validator: '_validateView'
 567         },
 568
 569         /**
 570         Configuration object passed to the class constructor in `view`
 571         during render.
 572
 573         @attribute viewConfig
 574         @type {Object}
 575         @default undefined (initially unset)
 576         @protected
 577         @since 3.6.0
 578         **/
 579         viewConfig: {}
 580
 581         /**
 582         If the View class assigned to the DataTable's `view` attribute supports
 583         it, this class will be used for rendering the contents of the
 584         `<thead>`&mdash;the column headers for the table.
 585
 586         Similar to `view`, the instance of this View will be assigned to the
 587         DataTable instance's `head` property.
 588
 589         It is not strictly necessary that the class function assigned here be
 590         a View subclass.  It must however have a `render()` method.
 591
 592         @attribute headerView
 593         @type {Function|Object}
 594         @default Y.DataTable.HeaderView
 595         @since 3.5.0
 596         **/
 597         /*
 598         headerView: {
 599             value: Y.DataTable.HeaderView,
 600             validator: '_validateView'
 601         },
 602         */
 603
 604         /**
 605         Configuration object passed to the class constructor in `headerView`
 606         during render.
 607
 608         @attribute headerConfig
 609         @type {Object}
 610         @default undefined (initially unset)
 611         @protected
 612         @since 3.6.0
 613         **/
 614         //headConfig: {},
 615
 616         /**
 617         If the View class assigned to the DataTable's `view` attribute supports
 618         it, this class will be used for rendering the contents of the `<tfoot>`.
 619
 620         Similar to `view`, the instance of this View will be assigned to the
 621         DataTable instance's `foot` property.
 622
 623         It is not strictly necessary that the class function assigned here be
 624         a View subclass.  It must however have a `render()` method.
 625
 626         @attribute footerView
 627         @type {Function|Object}
 628         @since 3.5.0
 629         **/
 630         /*
 631         footerView: {
 632             validator: '_validateView'
 633         },
 634         */
 635
 636         /**
 637         Configuration object passed to the class constructor in `footerView`
 638         during render.
 639
 640         @attribute footerConfig
 641         @type {Object}
 642         @default undefined (initially unset)
 643         @protected
 644         @since 3.6.0
 645         **/
 646         //footerConfig: {},
 647
 648         /**
 649         If the View class assigned to the DataTable's `view` attribute supports
 650         it, this class will be used for rendering the contents of the `<tbody>`
 651         including all data rows.
 652
 653         Similar to `view`, the instance of this View will be assigned to the
 654         DataTable instance's `body` property.
 655
 656         It is not strictly necessary that the class function assigned here be
 657         a View subclass.  It must however have a `render()` method.
 658
 659         @attribute bodyView
 660         @type {Function}
 661         @default Y.DataTable.BodyView
 662         @since 3.5.0
 663         **/
 664         /*
 665         bodyView: {
 666             value: Y.DataTable.BodyView,
 667             validator: '_validateView'
 668         },
 669         */
 670
 671         /**
 672         Configuration object passed to the class constructor in `bodyView`
 673         during render.
 674
 675         @attribute bodyConfig
 676         @type {Object}
 677         @default undefined (initially unset)
 678         @protected
 679         @since 3.6.0
 680         **/
 681         //bodyConfig: {}
 682     }
 683 });
 684
 685 // The DataTable API docs are above DataTable.Base docs.
 686 Y.DataTable = Y.mix(
 687     Y.Base.create('datatable', Y.DataTable.Base, []), // Create the class
 688     Y.DataTable); // Migrate static and namespaced classes
 689
 690
 691 }, '3.13.0', {
 692     "requires": [
 693         "datatable-core",
 694         "datatable-table",
 695         "datatable-head",
 696         "datatable-body",
 697         "base-build",
 698         "widget"
 699     ],
 700     "skinnable": true
 701 });