head.js revision 53c97f474022b2633bdeccab063f518c4015f27a
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithView class responsible for rendering the `<thead>` section of a table. Used as
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smiththe default `headerView` for `Y.DataTable.Base` and `Y.DataTable` classes.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith@module datatable
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith@submodule datatable-head
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithView class responsible for rendering the `<thead>` section of a table. Used as
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smiththe default `headerView` for `Y.DataTable.Base` and `Y.DataTable` classes.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithTranslates the provided array of column configuration objects into a rendered
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith`<thead>` based on the data in those objects.
e0a1afd287c016be5722249b10ba81684f33886bLuke SmithThe structure of the column data is expected to be a single array of objects,
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smithwhere each object corresponds to a `<th>`. Those objects may contain a
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith`children` property containing a similarly structured array to indicate the
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smithnested cells should be grouped under the parent column's colspan in a separate
e0a1afd287c016be5722249b10ba81684f33886bLuke Smithrow of header cells. E.g.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smithnew Y.DataTable.HeaderView({
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith container: tableNode,
e0a1afd287c016be5722249b10ba81684f33886bLuke Smith { key: 'id' }, // no nesting
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'name', children: [
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'firstName', label: 'First' },
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'lastName', label: 'Last' } ] }
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith</code></pre>
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithThis would translate to the following visualization:
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith---------------------
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith| |---------------
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith| id | First | Last |
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith---------------------
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithSupported properties of the column objects include:
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `label` - The HTML content of the header cell.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `key` - If `label` is not specified, the `key` is used for content.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `children` - Array of columns to appear below this column in the next
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `headerTemplate` - Overrides the instance's `CELL_TEMPLATE` for cells in this
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith column only.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `abbr` - The content of the 'abbr' attribute of the `<th>`
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `className` - Adds this string of CSS classes to the column header
1a40b51b558814291aa784dfd7335004602428ceLuke SmithThrough the life of instantiation and rendering, the column objects will have
1a40b51b558814291aa784dfd7335004602428ceLuke Smiththe following properties added to them:
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith * `id` - (Defaulted by DataTable) The id to assign the rendered column
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith * `_colspan` - To supply the `<th>` attribute
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith * `_rowspan` - To supply the `<th>` attribute
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith * `_parent` - (Added by DataTable) If the column is a child of another
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith column, this points to its parent column
0e7d399f99fcb097a927af7e6588f393740585a2Luke SmithThe column object is also used to provide values for {placeholder} tokens in the
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smithinstance's `CELL_TEMPLATE`, so you can modify the template and include other
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smithcolumn object properties to populate them.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith@class HeaderView
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith@namespace DataTable
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith@extends View
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke SmithY.namespace('DataTable').HeaderView = Y.Base.create('tableHeader', Y.View, [], {
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith // -- Instance properties -------------------------------------------------
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith Template used to create the table's header cell markup. Override this to
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith customize how header cell markup is created.
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith @property CELL_TEMPLATE
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith @type {HTML}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default '<th id="{id}" colspan="{_colspan}" rowspan="{_rowspan}" class="{className}" scope="col" {_id}{abbr}>{content}</th>'
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith '<th id="{id}" colspan="{_colspan}" rowspan="{_rowspan}" class="{className}" scope="col" {_id}{abbr}>{content}</th>',
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith The data representation of the header rows to render. This is assigned by
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith parsing the `columns` configuration array, and is used by the render()
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @property columns
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @type {Array[]}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default (initially unset)
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith //TODO: should this be protected?
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith //columns: null,
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Template used to create the table's header row markup. Override this to
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith customize the row markup.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @property ROW_TEMPLATE
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @type {HTML}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default '<tr>{content}</tr>'
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith '<tr>{content}</tr>',
0e7d399f99fcb097a927af7e6588f393740585a2Luke Smith The object that serves as the source of truth for column and row data.
0e7d399f99fcb097a927af7e6588f393740585a2Luke Smith This property is assigned at instantiation from the `source` property of
0e7d399f99fcb097a927af7e6588f393740585a2Luke Smith the configuration object passed to the constructor.
0e7d399f99fcb097a927af7e6588f393740585a2Luke Smith @property source
0e7d399f99fcb097a927af7e6588f393740585a2Luke Smith @type {Object}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default (initially unset)
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
e0a1afd287c016be5722249b10ba81684f33886bLuke Smith //TODO: should this be protected?
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith //source: null,
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith // -- Public methods ------------------------------------------------------
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Builds a CSS class name from the provided tokens. If the instance is
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith created with `cssPrefix` or `source` in the configuration, it will use this
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith prefix (the `_cssPrefix` of the `source` object) as the base token. This
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith allows class instances to generate markup with class names that correspond
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith to the parent class that is consuming them.
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith @method getClassName
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith @param {String} token* Any number of tokens to include in the class name
b30dbdf0ef8772c980fc59f2d2015a295c0b4dc3Luke Smith @return {String} The generated class name
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
1a40b51b558814291aa784dfd7335004602428ceLuke Smith getClassName: function () {
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith return _getClassName.apply(ClassNameManager, args);
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith Creates the `<thead>` Node content by assembling markup generated by
a3e011a6940a2707d43148e12f3d3cd6fd388794Luke Smith populating the `ROW_TEMPLATE` and `CELL_TEMPLATE` templates with content
1a40b51b558814291aa784dfd7335004602428ceLuke Smith from the `columns` property.
1a40b51b558814291aa784dfd7335004602428ceLuke Smith @method render
1a40b51b558814291aa784dfd7335004602428ceLuke Smith @return {HeaderView} The instance
1a40b51b558814291aa784dfd7335004602428ceLuke Smith @since 3.5.0
1a40b51b558814291aa784dfd7335004602428ceLuke Smith render: function () {
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith for (i = 0, len = columns.length; i < len; ++i) {
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith for (j = 0, jlen = columns[i].length; j < jlen; ++j) {
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith values.className += ' ' + this.getClassName('first', 'header');
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith col.headerTemplate || this.CELL_TEMPLATE, values);
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith return this;
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith // -- Protected and private properties and methods ------------------------
1080d9c735088a474affe30611ae889315840a17Luke Smith The base token for classes created with the `getClassName` method.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @property _cssPrefix
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @type {String}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default 'yui3-table'
1080d9c735088a474affe30611ae889315840a17Luke Smith @since 3.5.0
1080d9c735088a474affe30611ae889315840a17Luke Smith _cssPrefix: ClassNameManager.getClassName('table'),
1080d9c735088a474affe30611ae889315840a17Luke Smith Handles changes in the source's columns attribute. Redraws the headers.
1080d9c735088a474affe30611ae889315840a17Luke Smith @method _afterColumnsChange
1080d9c735088a474affe30611ae889315840a17Luke Smith @param {EventFacade} e The `columnsChange` event object
1080d9c735088a474affe30611ae889315840a17Luke Smith @since 3.5.0
1080d9c735088a474affe30611ae889315840a17Luke Smith Binds event subscriptions from the UI and the source (if assigned).
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @method bindUI
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith bindUI: function () {
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith if (this.source && !this._eventHandles.columnsChange) {
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith // TODO: How best to decouple this?
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Destroys the instance.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @method destructor
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith destructor: function () {
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith (new Y.EventHandle(Y.Object.values(this._eventHandles))).detach();
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Holds the event subscriptions needing to be detached when the instance is
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith `destroy()`ed.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @property _eventHandles
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @type {Object}
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @default undefined (initially unset)
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith //_eventHandles: null,
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Initializes the instance. Reads the following configuration properties:
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `columns` - (REQUIRED) The initial column information
e0a1afd287c016be5722249b10ba81684f33886bLuke Smith * `cssPrefix` - The base string for classes generated by `getClassName`
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith * `source` - The object to serve as source of truth for column info
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @method initializer
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @param {Object} config Configuration data
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith @since 3.5.0
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith var cssPrefix = config.cssPrefix || (config.source || {}).cssPrefix;
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith this.columns = this._parseColumns(config.columns);
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith Translate the input column format into a structure useful for rendering a
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith `<thead>`, rows, and cells. The structure of the input is expected to be a
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith single array of objects, where each object corresponds to a `<th>`. Those
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith objects may contain a `children` property containing a similarly structured
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith array to indicate the nested cells should be grouped under the parent
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith column's colspan in a separate row of header cells. E.g.
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'id' }, // no nesting
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'name', children: [
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'firstName', label: 'First' },
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith { key: 'lastName', label: 'Last' } ] }
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith </code></pre>
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith would indicate two header rows with the first column 'id' being assigned a
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith `rowspan` of `2`, the 'name' column appearing in the first row with a
e0a1afd287c016be5722249b10ba81684f33886bLuke Smith `colspan` of `2`, and the 'firstName' and 'lastName' columns appearing in
cfb2dc43f7aba18c4c6b0db07ca060089bd2e670Luke Smith the second row, below the 'name' column.
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith ---------------------
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith | |---------------
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith | id | First | Last |
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith ---------------------
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith Supported properties of the column objects include:
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `label` - The HTML content of the header cell.
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `key` - If `label` is not specified, the `key` is used for content.
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `children` - Array of columns to appear below this column in the next
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith * `abbr` - The content of the 'abbr' attribute of the `<th>`
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith * `headerTemplate` - Overrides the instance's `CELL_TEMPLATE` for cells
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith in this column only.
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith The output structure is basically a simulation of the `<thead>` structure
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith with arrays for rows and objects for cells. Column objects have the
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith following properties added to them:
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `id` - (Defaulted by DataTable) The id to assign the rendered
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `_colspan` - Per the `<th>` attribute
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith * `_rowspan` - Per the `<th>` attribute
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith * `_parent` - (Added by DataTable) If the column is a child of another
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith column, this points to its parent column
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith The column object is also used to provide values for {placeholder}
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith replacement in the `CELL_TEMPLATE`, so you can modify the template and
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith include other column object properties to populate them.
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith @method _parseColumns
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith @param {Object[]} data Array of column object data
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith @return {Array[]} An array of arrays corresponding to the header row
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith structure to render
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith @since 3.5.0
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith // First pass, assign colspans and calculate row count for
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith // non-nested headers' rowspan
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith // break to let the while loop process the children
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith // All columns in this row are processed
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith // Can't use .length because in 3+ rows, colspan
deb753fedac28c24a82440a4f7ca53df8a72a124Luke Smith // needs to aggregate the colspans of children
d15134141197c4fc93eb6094020e03eb72aa8d73Luke Smith // Second pass, build row arrays and assign rowspan
if (i >= len) {
return columns;