820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithA Widget for displaying tabular data. The base implementation of DataTable
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithprovides the ability to dynamically generate an HTML table from a set of column
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithconfigurations and row data.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke SmithTwo classes are included in the `datatable-base` module: `Y.DataTable` and
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith`Y.DataTable.Base`.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith@module datatable
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith@submodule datatable-base
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith@main datatable
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith// DataTable API docs included before DataTable.Base to make yuidoc work
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke SmithA Widget for displaying tabular data. Before feature modules are `use()`d,
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smiththis class is functionally equivalent to DataTable.Base. However, feature
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithmodules can modify this class in non-destructive ways, expanding the API and
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithfunctionality.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke SmithThis is the primary DataTable class. Out of the box, it provides the ability
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithto dynamically generate an HTML table from a set of column configurations and
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithrow data. But feature module inclusion can add table sorting, pagintaion,
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithhighlighting, selection, and more.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// The functionality of this table would require additional modules be use()d,
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// but the feature APIs are aggregated onto Y.DataTable.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// (Snippet is for illustration. Not all features are available today.)
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar table = new Y.DataTable({
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { type: 'checkbox', defaultChecked: true },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'firstName', sortable: true, resizable: true },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'lastName', sortable: true },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'role', formatter: toRoleName }
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith type: 'json',
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith resultListLocator: 'results.users',
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith 'firstName',
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'role', type: 'number' }
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith recordType: UserModel,
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith pagedData: {
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith location: 'footer',
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith pageSizes: [20, 50, 'all'],
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith rowsPerPage: 20,
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith pageLinks: 5
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith editable: true
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith</code></pre>
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith### Column Configuration
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithThe column configurations are set in the form of an array of objects, where
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smitheach object corresponds to a column. For columns populated directly from the
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithrow data, a 'key' property is required to bind the column to that property or
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithattribute in the row data.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithNot all columns need to relate to row data, nor do all properties or attributes
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithof the row data need to have a corresponding column. However, only those
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithcolumns included in the `columns` configuration attribute will be rendered.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithOther column configuration properties are supported by the configured
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith`headerView`, `bodyView`, `footerView` classes as well as any features added by
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithplugins or class extensions. See the description of DataTable.HeaderView,
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithDataTable.BodyView, and other DataTable feature classes to see what column
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithproperties they support.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithSome examples of column configurations would be:
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar columns = [{ key: 'firstName' }, { key: 'lastName' }, { key: 'age' }];
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// For columns without any additional configuration, strings can be used
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar columns = ['firstName', 'lastName', 'age'];
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// Multi-row column headers (see DataTable.HeaderView for details)
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar columns = [
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith label: 'Name',
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'firstName' },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'lastName' }
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith 'age' // mixing and matching objects and strings is ok
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// Including columns that are not related 1:1 to row data fields/attributes
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// (See DataTable.BodyView for details)
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar columns = [
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith label: 'Name', // Needed for the column header
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith formatter: function (o) {
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith // Fill the column cells with data from firstName and lastName
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith if (o.data.age > 55) {
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith o.className += ' senior';
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith return o.data.lastName + ', ' + o.data.firstName;
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// Columns that include feature configurations (for illustration; not all
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// features are available today).
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithvar columns = [
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { type: 'checkbox', defaultChecked: true },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'firstName', sortable: true, resizable: true, min-width: '300px' },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'lastName', sortable: true, resizable: true, min-width: '300px' },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { key: 'age', emptyCellValue: '<em>unknown</em>' }
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith</code></pre>
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith### Row Data Configuration
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithThe `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:
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith1. An array of simple objects with key:value pairs
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith2. A ModelList of Base-based class instances (presumably Model subclass
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithIf an array of objects is passed, it will be translated into a ModelList filled
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithwith instances of the class provided to the `recordType` attribute. This
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithattribute can also create a custom Model subclass from an array of field names
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithor an object of attribute configurations. If no `recordType` is provided, one
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithwill be created for you from available information (see `_initRecordType`).
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithProviding either your own ModelList instance for `data`, or at least Model
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithclass for `recordType`, is the best way to control client-server
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithsynchronization when modifying data on the client side.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithThe ModelList instance that manages the table's data is available in the `data`
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithproperty on the DataTable instance.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith### Rendering
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithTable rendering is a collaborative process between the DataTable and its
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithconfigured `headerView`, `bodyView`, and `footerView`. The DataTable renders
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smiththe `<table>` and `<caption>`, but the contents of the table are delegated to
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithinstances of the classes provided to the `headerView`, `bodyView`, and
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith`footerView` attributes. If any of these attributes is unset, that portion of
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smiththe table won't be rendered.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithDataTable.Base assigns the default `headerView` to `Y.DataTable.HeaderView` and
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smiththe default `bodyView` to `Y.DataTable.BodyView`, though either can be
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithoverridden for custom rendering. No default `footerView` is assigned. See
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smiththose classes for more details about how they operate.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith@class DataTable
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith@extends DataTable.Base
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// DataTable API docs included before DataTable.Base to make yuidoc work
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke SmithThe baseline implementation of a DataTable. This class should be used
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithprimarily as a superclass for a custom DataTable with a specific set of
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithfeatures. Because features can be composed onto `Y.DataTable`, custom
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithsubclasses of DataTable.Base will remain unmodified when new feature modules
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke SmithExample usage might look like this:
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith// Custom subclass with only sorting and mutability added. If other datatable
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith// feature modules are loaded, this class will not be affected.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithvar MyTableClass = Y.Base.create('table', Y.DataTable.Base,
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith [ Y.DataTable.Sort, Y.DataTable.Mutable ]);
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithvar table = new MyTableClass({
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith columns: ['firstName', 'lastName', 'age'],
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { firstName: 'Frank', lastName: 'Zappa', age: 71 },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith { firstName: 'Albert', lastName: 'Einstein', age: 132 },
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithtable.render('#over-there');
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith// DataTable.Base can be instantiated if a featureless table is needed.
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithvar table = new Y.DataTable.Base({
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith columns: ['firstName', 'lastName', 'age'],
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith { firstName: 'Frank', lastName: 'Zappa', age: 71 },
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith { firstName: 'Albert', lastName: 'Einstein', age: 132 },
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smithtable.render('#in-here');
83abb4e792c64ccc94916233f9dedbd9fa638d50Luke Smith</code></pre>
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithDataTable.Base is built from DataTable.Core, and sets the default `headerView`
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smithto `Y.DataTable.HeaderView` and default `bodyView` to `Y.DataTable.BodyView`.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith@extends Widget
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith@uses DataTable.Core
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith@namespace DataTable
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke SmithY.DataTable.Base = Y.Base.create('datatable', Y.Widget, [Y.DataTable.Core],
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith // Default head and body views
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith// The DataTable API docs are above DataTable.Base docs.
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith Y.Base.create('datatable', Y.DataTable.Base, []), // Create the class
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith Y.DataTable); // Migrate static and namespaced classes
820d7f2eab2a78412c9803335bb10a2974e7fbf5Luke Smith}, '@VERSION@' ,{requires:['datatable-core', 'base-build', 'widget', 'datatable-head', 'datatable-body']});