datatable-base-debug.js revision 820d7f2eab2a78412c9803335bb10a2974e7fbf5
7db19a177889ecbab7588eb69413515649018bd3Matt SweeneyYUI.add('datatable-base', function(Y) {
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney/**
7db19a177889ecbab7588eb69413515649018bd3Matt SweeneyA Widget for displaying tabular data. The base implementation of DataTable
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeneyprovides the ability to dynamically generate an HTML table from a set of column
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeneyconfigurations and row data.
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney
7db19a177889ecbab7588eb69413515649018bd3Matt SweeneyTwo classes are included in the `datatable-base` module:
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney1. `Y.DataTable` - Main instantiable class, has all loaded features available
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney2. `Y.DataTable.Base` - Featureless version for use primarily as a superclass.
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney
7db19a177889ecbab7588eb69413515649018bd3Matt SweeneyExample usage might look like this:
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney<pre><code>
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney// Featureless table, usually used as a subclass, but can be instantiated
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeneyvar table = new Y.DataTable.Base({
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney columns: ['firstName', 'lastName', 'age'],
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney data: [
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney { firstName: 'Frank', lastName: 'Zappa', age: 71 },
7db19a177889ecbab7588eb69413515649018bd3Matt Sweeney { firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
50a44094a1bbdeaaccbb3cfac2ba7b92aabb374bMatt Sweeney { firstName: 'Albert', lastName: 'Einstein', age: 132 },
...
]
});
table.render('#in-here');
// Table with all loaded features available (not .Base)
// The functionality of this table would require additional modules be use()d,
// but the feature APIs are aggregated onto Y.DataTable.
// (Snippet is for illustration. Not all features are available today.)
var table = new Y.DataTable({
columns: [
{ type: 'checkbox', defaultChecked: true },
{ key: 'firstName', sortable: true, resizable: true },
{ key: 'lastName', sortable: true },
{ key: 'role', formatter: toRoleName }
],
data: {
source: 'http://myserver.com/service/json',
type: 'json',
schema: {
resultListLocator: 'results.users',
fields: [
'username',
'firstName',
'lastName',
{ key: 'role', type: 'number' }
]
}
},
recordType: UserModel,
pagedData: {
location: 'footer',
pageSizes: [20, 50, 'all'],
rowsPerPage: 20,
pageLinks: 5
},
editable: true,
filterable: true
});
</code></pre>
### Column Configuration
The column configurations are set in the form of an array of objects, where
each object corresponds to a column. For columns populated directly from the
row data, a 'key' property is required to bind the column to that property or
attribute in the row data.
Not all columns need to relate to row data, nor do all properties or attributes
of the row data need to have a corresponding column. However, only those
columns included in the `columns` configuration attribute will be rendered.
Other column configuration properties are supported by the configured
`headerView`, `bodyView`, `footerView` classes as well as any features added by
plugins or class extensions. See the description of DataTable.HeaderView,
DataTable.BodyView, and other DataTable feature classes to see what column
properties they support.
Some examples of column configurations would be:
<pre><code>
// Basic
var columns = [{ key: 'firstName' }, { key: 'lastName' }, { key: 'age' }];
// For columns without any additional configuration, strings can be used
var columns = ['firstName', 'lastName', 'age'];
// Multi-row column headers (see DataTable.HeaderView for details)
var columns = [
{
label: 'Name',
children: [
{ key: 'firstName' },
{ key: 'lastName' }
]
},
'age' // mixing and matching objects and strings is ok
];
// Including columns that are not related 1:1 to row data fields/attributes
// (See DataTable.BodyView for details)
var columns = [
{
label: 'Name', // Needed for the column header
formatter: function (o) {
// Fill the column cells with data from firstName and lastName
if (o.data.age > 55) {
o.classnames += ' senior';
}
return o.data.lastName + ', ' + o.data.firstName;
}
},
'age'
];
// Columns that include feature configurations (for illustration; not all
// features are available today).
var columns = [
{ type: 'checkbox', defaultChecked: true },
{ key: 'firstName', sortable: true, resizable: true, min-width: '300px' },
{ key: 'lastName', sortable: true, resizable: true, min-width: '300px' },
{ key: 'age', emptyCellValue: '<em>unknown</em>' }
];
</code></pre>
### Row Data Configuration
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:
1. An array of simple objects with key:value pairs
2. A ModelList of Base-based class instances (presumably Model subclass
instances)
If an array of objects is passed, it will be translated into a ModelList filled
with instances of the class provided to the `recordType` attribute. This
attribute can also create a custom Model subclass from an array of field names
or an object of attribute configurations. If no `recordType` is provided, one
will be created for you from available information (see `_initRecordType`).
Providing either your own ModelList instance for `data`, or at least Model
class for `recordType`, is the best way to control client-server
synchronization when modifying data on the client side.
The ModelList instance that manages the table's data is available in the `data`
property on the DataTable instance.
### Rendering
Table rendering is a collaborative process between the DataTable and its
configured `headerView`, `bodyView`, and `footerView`. The DataTable renders
the `<table>` and `<caption>`, but the contents of the table are delegated to
instances of the classes provided to the `headerView`, `bodyView`, and
`footerView` attributes. If any of these attributes is unset, that portion of
the table won't be rendered.
DataTable.Base assigns the default `headerView` to `Y.DataTable.HeaderView` and
the default `bodyView` to `Y.DataTable.BodyView`, though either can be
overridden for custom rendering. No default `footerView` is assigned. See
those classes for more details about how they operate.
@module datatable-base
@main
**/
// DataTable API docs included before DataTable.Base to make yuidoc work
/**
A Widget for displaying tabular data. Before feature modules are `use()`d,
this class is functionally equivalent to DataTable.Base. However, feature
modules can modify this class in non-destructive ways, expanding the API and
functionality.
This is the primary DataTable class. Out of the box, it provides the ability
to dynamically generate an HTML table from a set of column configurations and
row data. But feature module inclusion can add table sorting, pagintaion,
highlighting, selection, and more.
<pre><code>
// Basic use
var table = new Y.DataTable({
columns: ['firstName', 'lastName', 'age'],
data: [
{ firstName: 'Frank', lastName: 'Zappa', age: 71 },
{ firstName: 'Frank', lastName: 'Lloyd Wright', age: 144 },
{ firstName: 'Albert', lastName: 'Einstein', age: 132 },
...
]
});
table.render('#in-here');
// Table with loaded features.
// The functionality of this table would require additional modules be use()d,
// but the feature APIs are aggregated onto Y.DataTable.
// (Snippet is for illustration. Not all features are available today.)
var table = new Y.DataTable({
columns: [
{ type: 'checkbox', defaultChecked: true },
{ key: 'firstName', sortable: true, resizable: true },
{ key: 'lastName', sortable: true },
{ key: 'role', formatter: toRoleName }
],
data: {
source: 'http://myserver.com/service/json',
type: 'json',
schema: {
resultListLocator: 'results.users',
fields: [
'username',
'firstName',
'lastName',
{ key: 'role', type: 'number' }
]
}
},
recordType: UserModel,
pagedData: {
location: 'footer',
pageSizes: [20, 50, 'all'],
rowsPerPage: 20,
pageLinks: 5
},
editable: true,
filterable: true
});
</code></pre>
@class DataTable
@extends DataTable.Base
**/
// DataTable API docs included before DataTable.Base to make yuidoc work
/**
The baseline implementation of a DataTable. This class should be used
primarily as a superclass for a custom DataTable with a specific set of
features. Because features can be composed onto `Y.DataTable`, custom
subclasses of DataTable.Base will remain unmodified when new feature modules
are loaded.
DataTable.Base is built from DataTable.Core, and sets the default `headerView`
to `Y.DataTable.HeaderView` and default `bodyView` to `Y.DataTable.BodyView`.
@class Base
@extends Widget
@uses DataTable.Core
@namespace DataTable
**/
Y.DataTable.Base = Y.Base.create('datatable', Y.Widget, [Y.DataTable.Core],
null, {
ATTRS: {
// Default head and body views
headerView: { value: Y.DataTable.HeaderView },
bodyView : { value: Y.DataTable.BodyView }
}
});
// The DataTable API docs are above DataTable.Base docs.
Y.DataTable = Y.mix(
Y.Base.create('datatable', Y.DataTable.Base, []), // Create the class
Y.DataTable); // Migrate static and namespaced classes
}, '@VERSION@' ,{requires:['datatable-core', 'base-build', 'widget', 'datatable-head', 'datatable-body']});