datatable-head.js revision db7877b089ad41f8aebc49c0810c81adc5c44cac
YUI.add('datatable-head', function(Y) {
/**
View class responsible for rendering the `<thead>` section of a table. Used as
the default `headerView` for `Y.DataTable.Base` and `Y.DataTable` classes.
Translates the provided array of column configuration objects into a rendered
`<thead>` based on the data in those objects.
The structure of the column data is expected to be a single array of objects,
where each object corresponds to a `<th>`. Those objects may contain a
`children` property containing a similarly structured array to indicate the
nested cells should be grouped under the parent column's colspan in a separate
row of header cells. E.g.
<pre><code>
new Y.DataTable.HeaderView({
container: tableNode,
columns: [
{ key: 'id' }, // no nesting
{ key: 'name', children: [
{ key: 'firstName', label: 'First' },
{ key: 'lastName', label: 'Last' } ] }
]
}).render();
</code></pre>
This would translate to the following visualization:
<pre>
---------------------
| | name |
| |---------------
| id | First | Last |
---------------------
</pre>
Supported properties of the column objects include:
* `label` - The HTML content of the header cell.
* `key` - If `label` is not specified, the `key` is used for content.
* `children` - Array of columns to appear below this column in the next
row.
* `abbr` - The content of the 'abbr' attribute of the `<th>`
Through the life of instantiation and rendering, the column objects will have
the following properties added to them:
* `colspan` - To supply the `<th>` attribute
* `rowspan` - To supply the `<th>` attribute
* `parent` - If the column is a child of another column, this points to
its parent column
* `_yuid` - A unique YUI generated id used as the `<th>`'s 'id' for
reference in the data `<td>`'s 'headers' attribute.
The column object is also used to provide values for {placeholder} tokens in the
instance's `CELL_TEMPLATE`, so you can modify the template and include other
column object properties to populate them.
@module datatable-head
@class HeaderView
@namespace DataTable
@extends View
**/
var Lang = Y.Lang,
fromTemplate = Lang.sub,
isArray = Lang.isArray,
toArray = Y.Array,
ClassNameManager = Y.ClassNameManager,
_getClassName = ClassNameManager.getClassName;
Y.namespace('DataTable').HeaderView = Y.Base.create('tableHeader', Y.View, [], {
// -- Instance properties -------------------------------------------------
/**
Template used to create the table's header cell markup. Override this to
customize how these cells' markup is created.
@property CELL_TEMPLATE
@type {HTML}
@default '<th id="{_yuid}" abbr="{abbr} colspan="{colspan}" rowspan="{rowspan}" class="{className}" {headers}>{content}</th>'
**/
CELL_TEMPLATE :
'<th id="{_yuid}" abbr="{abbr}" colspan="{colspan}" rowspan="{rowspan}" class="{className}" scope="col" role="columnheader" {headers}>{content}</th>',
/**
The data representation of the header rows to render. This is assigned by
parsing the `columns` configuration array, and is used by the render()
method.
@property columns
@type {Array[]}
@default (initially unset)
**/
//TODO: should this be protected?
//columns: null,
/**
The object that serves as the source of truth for column and row data.
This property is assigned at instantiation from the `source` property of
the configuration object passed to the constructor.
@property source
@type {Object}
@default (initially unset)
**/
//TODO: should this be protected?
//source: null,
/**
Template used to create the table's header row markup. Override this to
customize the row markup.
@property ROW_TEMPLATE
@type {HTML}
@default '<tr>{content}</tr>'
**/
ROW_TEMPLATE:
'<tr role="row">{content}</tr>',
// -- Public methods ------------------------------------------------------
/**
Builds a CSS class name from the provided tokens. If the instance is
created with `cssPrefix` or `source` in the configuration, it will use this
prefix (the `_cssPrefix` of the `source` object) as the base token. This
allows class instances to generate markup with class names that correspond
to the parent class that is consuming them.
@method getClassName
@param {String} token* Any number of tokens to include in the class name
@return {String} The generated class name
**/
getClassName: function () {
var args = toArray(arguments);
args.unshift(this._cssPrefix);
args.push(true);
return _getClassName.apply(ClassNameManager, args);
},
/**
Creates the `<thead>` Node content by assembling markup generated by
populating the `ROW_TEMPLATE` and `CELL_TEMPLATE` templates with content
from the `columns` property.
@method render
@return {HeaderView} The instance
@chainable
**/
render: function () {
var thead = this.get('container'),
columns = this.columns,
defaults = {
abbr: '',
colspan: 1,
rowspan: 1
},
i, len, j, jlen, col, className, html, content, values;
if (thead && columns) {
html = '';
if (columns.length) {
for (i = 0, len = columns.length; i < len; ++i) {
content = '';
for (j = 0, jlen = columns[i].length; j < jlen; ++j) {
col = columns[i][j];
className = this.getClassName('header');
values = Y.merge(
defaults,
col, {
className: className,
content : col.label || col.key ||
("Column " + (j + 1)),
headers : ''
}
);
if (col._id) {
values.className +=
' ' + this.getClassName('col', col._id);
}
if (col.parent) {
values.headers =
'headers="' + col.parent.headers.join(' ') + '"';
}
content += fromTemplate(this.CELL_TEMPLATE, values);
}
html += fromTemplate(this.ROW_TEMPLATE, {
content: content
});
}
}
thead.setContent(html);
}
this.bindUI();
return this;
},
// -- Protected and private properties and methods ------------------------
/**
The base token for classes created with the `getClassName` method.
@property _cssPrefix
@type {String}
@default 'yui3-table'
@protected
**/
_cssPrefix: ClassNameManager.getClassName('table'),
/**
Handles changes in the source's columns attribute. Redraws the headers.
@method _afterColumnsChange
@param {EventFacade} e The `columnsChange` event object
@protected
**/
_afterColumnsChange: function (e) {
this.columns = this._parseColumns(e.newVal);
this.render();
},
/**
Binds event subscriptions from the UI and the source (if assigned).
@method bindUI
@protected
**/
bindUI: function () {
if (this.source && !this._eventHandles.columnsChange) {
// TODO: How best to decouple this?
this._eventHandles.columnsChange =
this.source.after('columnsChange',
Y.bind('_afterColumnsChange', this));
}
},
/**
Destroys the instance.
@method destructor
@protected
**/
destructor: function () {
(new Y.EventHandle(Y.Object.values(this._eventHandles))).detach();
},
/**
Holds the event subscriptions needing to be detached when the instance is
`destroy()`ed.
@property _eventHandles
@type {Object}
@default undefined (initially unset)
@protected
**/
//_eventHandles: null,
/**
Initializes the instance. Reads the following configuration properties:
* `columns` - (REQUIRED) The initial column information
* `cssPrefix` - The base string for classes generated by `getClassName`
* `source` - The object to serve as source of truth for column info
@method initializer
@param {Object} config Configuration data
@protected
**/
initializer: function (config) {
config || (config = {});
var cssPrefix = config.cssPrefix || (config.source || {}).cssPrefix;
this.source = config.source;
this.columns = this._parseColumns(config.columns);
this._eventHandles = [];
if (cssPrefix) {
this._cssPrefix = cssPrefix;
}
},
/**
Translate the input column format into a structure useful for rendering a
`<thead>`, rows, and cells. The structure of the input is expected to be a
single array of objects, where each object corresponds to a `<th>`. Those
objects may contain a `children` property containing a similarly structured
array to indicate the nested cells should be grouped under the parent
column's colspan in a separate row of header cells. E.g.
<pre><code>
[
{ key: 'id' }, // no nesting
{ key: 'name', children: [
{ key: 'firstName', label: 'First' },
{ key: 'lastName', label: 'Last' } ] }
]
</code></pre>
would indicate two header rows with the first column 'id' being assigned a
`rowspan` of `2`, the 'name' column appearing in the first row with a
`colspan` of `2`, and the 'firstName' and 'lastName' columns appearing in
the second row, below the 'name' column.
<pre>
---------------------
| | name |
| |---------------
| id | First | Last |
---------------------
</pre>
Supported properties of the column objects include:
* `label` - The HTML content of the header cell.
* `key` - If `label` is not specified, the `key` is used for content.
* `children` - Array of columns to appear below this column in the next
row.
* `abbr` - The content of the 'abbr' attribute of the `<th>`
The output structure is basically a simulation of the `<thead>` structure
with arrays for rows and objects for cells. Column objects have the
following properties added to them:
* `colspan` - Per the `<th>` attribute
* `rowspan` - Per the `<th>` attribute
* `parent` - If the column is a child of another column, this points to
its parent column
* `_yuid` - A unique YUI generated id used as the `<th>`'s 'id' for
reference in the data `<td>`'s 'headers' attribute.
The column object is also used to provide values for {placeholder}
replacement in the `CELL_TEMPLATE`, so you can modify the template and
include other column object properties to populate them.
@method _parseColumns
@param {Object[]} data Array of column object data
@return {Array[]} An array of arrays corresponding to the header row
structure to render
@protected
**/
_parseColumns: function (data) {
var columns = [],
stack = [],
rowSpan = 1,
entry, row, col, children, parent, i, len, j;
if (isArray(data) && data.length) {
// First pass, assign colspans and calculate row count for
// non-nested headers' rowspan
stack.push([data, -1]);
while (stack.length) {
entry = stack[stack.length - 1];
row = entry[0];
i = entry[1] + 1;
for (len = row.length; i < len; ++i) {
col = row[i];
children = col.children;
Y.stamp(col);
if (isArray(children) && children.length) {
stack.push([children, -1]);
entry[1] = i;
rowSpan = Math.max(rowSpan, stack.length);
// break to let the while loop process the children
break;
} else {
col.colspan = 1;
}
}
if (i >= len) {
// All columns in this row are processed
if (stack.length > 1) {
entry = stack[stack.length - 2];
parent = entry[0][entry[1]];
parent.colspan = 0;
for (i = 0, len = row.length; i < len; ++i) {
// Can't use .length because in 3+ rows, colspan
// needs to aggregate the colspans of children
parent.colspan += row[i].colspan;
// Assign the parent column for ease of navigation
row[i].parent = parent;
}
}
stack.pop();
}
}
// Second pass, build row arrays and assign rowspan
for (i = 0; i < rowSpan; ++i) {
columns.push([]);
}
stack.push([data, -1]);
while (stack.length) {
entry = stack[stack.length - 1];
row = entry[0];
i = entry[1] + 1;
for (len = row.length; i < len; ++i) {
col = row[i];
children = col.children;
columns[stack.length - 1].push(col);
entry[1] = i;
// collect the IDs of parent cols
col.headers = [col._yuid];
for (j = stack.length - 2; j >= 0; --j) {
parent = stack[j][0][stack[j][1]];
col.headers.unshift(parent._yuid);
}
if (children && children.length) {
// parent cells must assume rowspan 1 (long story)
// break to let the while loop process the children
stack.push([children, -1]);
break;
} else {
col.rowspan = rowSpan - stack.length + 1;
}
}
if (i >= len) {
// All columns in this row are processed
stack.pop();
}
}
}
return columns;
}
});
}, '@VERSION@' ,{requires:['datatable-core', 'view', 'classnamemanager']});