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