Show:
Module: datatable-core
Parent Module: datatable

This is a documentation entry only

Columns are described by object literals with a set of properties. There is not an actual DataTable.Column class. However, for the purpose of documenting it, this pseudo-class is declared here.

DataTables accept an array of column definitions in their columns attribute. Each entry in this array is a column definition which may contain any combination of the properties listed below.

There are no mandatory properties though a column will usually have a key property to reference the data it is supposed to show. The columns attribute can accept a plain string in lieu of an object literal, which is the equivalent of an object with the key property set to that string.

Properties

_colspan

Integer protected

(read-only) Used by Y.DataTable.HeaderView when building stacked column headers.

_headers

Array protected

(read-only) Array of the ids of the column and all parent columns. Used by Y.DataTable.BodyView to populate <td headers="THIS"> when a cell references more than one header.

_id

String protected

(read-only) A unique-to-this-instance name used extensively in the rendering process. It is also used to create the column's classname, as the input name table.getColumn(HERE), and in the column header's <th data-yui3-col-id="HERE">.

The value is populated by the first of name, field, key, id, or _yuid to have a value. If that value has already been used (such as when multiple columns have the same key), an incrementer is added to the end. For example, two columns with key: "id" will have _ids of "id" and "id2". table.getColumn("id") will return the first column, and table.getColumn("id2") will return the second.

_parent

DataTable.Column protected

(read-only) Assigned to all columns in a column's children collection. References the parent column object.

_rowspan

Integer protected

(read-only) Used by Y.DataTable.HeaderView when building stacked column headers.

_yuid

String protected

(read-only) The unique identifier assigned to each column. This is used for the id if not set, and the _id if none of name, field, key, or id are set.

abbr

String

Assigns the value <th abbr="HERE">.

{
                                                  key  : 'forecast',
                                                  label: '1yr Target Forecast',
                                                  abbr : 'Forecast'
                                                }

allowHTML

Boolean

Skips the security step of HTML escaping the value for cells in this column.

This is also necessary if emptyCellValue is set with an HTML string. nodeFormatters ignore this configuration. If using a nodeFormatter, it is recommended to use Y.Escape.html() on any user supplied content that is to be displayed.

{
                                                    key: 'preview',
                                                    allowHTML: true
                                                }

booleanLabels

Object

Determines the texts to be shown to represent Boolean values when the boolean formatter is used.

The attribute is an object with text values for properties true and false.

{key:"active", formatter: "boolean", booleanLabels: {
                                                    "true": "yes",
                                                    "false": "no"
                                                }}

buttonLabel

String

Label to be shown in the face of a button produced by the button formatter

caseSensitive

Boolean

Provided by the datatable-sort module.

Defined in yui3/src/datatable/js/sort.js:913

When the instance's caseSensitive attribute is set to true the sort order is case sensitive (relevant to string columns only).

Case sensitive sort is marginally more efficient and should be considered for large data sets when case insensitive sort is not required.

{ key: 'lastLogin', sortable: true, caseSensitive: true }

cellTemplate

String

Overrides the default CELL_TEMPLATE used by Y.DataTable.BodyView to render the data cells for this column. This is necessary when more control is needed over the markup for the <td> itself, rather than its content.

{
                                                    key: 'id',
                                                    cellTemplate:
                                                        '<td class="{className}">' +
                                                          '<input type="checkbox" ' +
                                                                 'id="{content}">' +
                                                        '</td>'
                                                }

children

Array

Used to create stacked headers.

Child columns may also contain children. There is no limit to the depth of nesting.

Columns configured with children are for display only and <strong>should not</strong> be configured with a key. Configurations relating to the display of data, such as formatter, nodeFormatter, emptyCellValue, etc. are ignored.

{ label: 'Name', children: [
                                                    { key: 'firstName', label: 'First`},
                                                    { key: 'lastName', label: 'Last`}
                                                ]}

className

String

A string of CSS classes that will be added to the <td>'s class attribute.

Note, all cells will automatically have a class in the form of "yui3-datatable-col-XXX" added to the <td>, where XXX is the column's configured name, key, or id (in that order of preference) sanitized from invalid characters.

{
                                                    key: 'symbol',
                                                    className: 'no-hide'
                                                }

currencyFormat

Object

Format specification for columns using the currency formatter. It contains an object as described in Number.format.

dateFormat

String

Format specification for columns using the date formatter. It contains a string as described in Date.format.

emptyCellValue

String depending on the setting of allowHTML

Provides the default value to populate the cell if the data for that cell is undefined, null, or an empty string.

{
                                                    key: 'price',
                                                    emptyCellValue: '???'
                                                }

field

String

An alias for name for backward compatibility.

{ field: 'fullname', formatter: ... }

formatter

String | | Function

String or function used to translate the raw record data for each cell in a given column into a format better suited to display.

If it is a string, it will initially be assumed to be the name of one of the formatting functions in Y.DataTable.BodyView.Formatters. If one such formatting function exists, it will be used.

If no such named formatter is found, it will be assumed to be a template string and will be expanded. The placeholders can contain the key to any field in the record or the placeholder {value} which represents the value of the current field.

If the value is a function, it will be assumed to be a formatting function. A formatting function receives a single argument, an object with the following properties:

  • value The raw value from the record Model to populate this cell. Equivalent to o.record.get(o.column.key) or o.data[o.column.key].
  • data The Model data for this row in simple object format.
  • record The Model for this row.
  • column The column configuration object.
  • className A string of class names to add <td class="HERE"> in addition to the column class and any classes in the column's className configuration.
  • rowIndex The index of the current Model in the ModelList. Typically correlates to the row index as well.
  • rowClass A string of css classes to add <tr class="HERE"><td.... This is useful to avoid the need for nodeFormatters to add classes to the containing row.

The formatter function may return a string value that will be used for the cell contents or it may change the value of the value, className or rowClass properties which well then be used to format the cell. If the value for the cell is returned in the value property of the input argument, no value should be returned.

{
                                                    key: 'name',
                                                    formatter: 'link',  // named formatter
                                                    linkFrom: 'website' // extra column property for link formatter
                                                },
                                                {
                                                    key: 'cost',
                                                    formatter: '${value}' // formatter template string
                                                  //formatter: '${cost}'  // same result but less portable
                                                },
                                                {
                                                    name: 'Name',          // column does not have associated field value
                                                                           // thus, it uses name instead of key
                                                    formatter: '{firstName} {lastName}' // template references other fields
                                                },
                                                {
                                                    key: 'price',
                                                    formatter: function (o) { // function both returns a string to show
                                                        if (o.value > 3) {    // and a className to apply to the cell
                                                            o.className += 'expensive';
                                                        }
                                                
                                                        return '$' + o.value.toFixed(2);
                                                    }
                                                },

headerTemplate

HTML

Overrides the default CELL_TEMPLATE used by Y.DataTable.HeaderView to render the header cell for this column. This is necessary when more control is needed over the markup for the header itself, rather than its content.

Use the label configuration if you don't need to customize the <th> iteself.

Implementers are strongly encouraged to preserve at least the {id} and {_id} placeholders in the custom value.

{
                                                    headerTemplate:
                                                        '<th id="{id}" ' +
                                                            'title="Unread" ' +
                                                            'class="{className}" ' +
                                                            '{_id}>&#9679;</th>'
                                                }

id

String

Overrides the default unique id assigned <th id="HERE">.

Use this with caution, since it can result in duplicate ids in the DOM.

{
                                                    name: 'checkAll',
                                                    id: 'check-all',
                                                    label: ...
                                                    formatter: ...
                                                }

key

String

Binds the column values to the named property in the data.

Optional if formatter, nodeFormatter, or cellTemplate is used to populate the content.

It should not be set if children is set.

The value is used for the _id property unless the name property is also set.

{ key: 'username' }
                                                

The above column definition can be reduced to this:

'username'

label

String

HTML to populate the header <th> for the column. It defaults to the value of the key property or the text Column n where n is an ordinal number.

{ key: 'MfgvaPrtNum', label: 'Part Number' }

linkFrom

String

Name of the field that is to provide the link for a column using the email or link formatters.

lookupTable

Object | | Array

Map of values to text used to translate internal values to human readable text in columns using the lookup formatter.

The map can be given in either of two formats:

{key: "status", formatter: "lookup", lookupTable: {
                                                    0: "unknown",
                                                    1: "requested",
                                                    2: "approved",
                                                    3: "delivered"
                                                }},
                                                {key: "otherStatus", formatter: "lookup", lookupTable: [
                                                    {value:0, text: "unknown"},
                                                    {value:1, text: "requested"},
                                                    {value:2, text: "approved"},
                                                    {value:3, text: "delivered"}
                                                ]}
                                                

The last format is compatible with the dropdown and autocomplete-based editors, where the order of the items in the dropdown matters.

name

String

An identifier that can be used to locate a column via getColumn or style columns with class yui3-datatable-col-NAME after dropping characters that are not valid for CSS class names.

It defaults to the key.

The value is used for the _id property.

{ name: 'fullname', formatter: ... }

nodeFormatter

Function

Used to customize the content of the data cells for this column.

nodeFormatter is significantly slower than formatter and should be avoided if possible. Unlike formatter, nodeFormatter has access to the <td> element and its ancestors.

The function provided is expected to fill in the <td> element itself. Node formatters should return false except in certain conditions as described in the users guide.

The function receives a single object argument with the following properties:

  • td The <td> Node for this cell.
  • cell If the cell <td> contains an element with classyui3-datatable-liner, this will refer to that Node. Otherwise, it is equivalent to td (default behavior).
  • value The raw value from the record Model to populate this cell. Equivalent to o.record.get(o.column.key) or o.data[o.column.key].
  • data The Model data for this row in simple object format.
  • record The Model for this row.
  • column The column configuration object.
  • rowIndex The index of the current Model in the ModelList. Typically correlates to the row index as well.

Example:

nodeFormatter: function (o) {
                                                    if (o.value < o.data.quota) {
                                                        o.td.setAttribute('rowspan', 2);
                                                        o.td.setAttribute('data-term-id', this.record.get('id'));
                                                
                                                        o.td.ancestor().insert(
                                                            '<tr><td colspan"3">' +
                                                                '<button class="term">terminate</button>' +
                                                            '</td></tr>',
                                                            'after');
                                                    }
                                                
                                                    o.cell.setHTML(o.value);
                                                    return false;
                                                }

numberFormat

Object

Format specification for columns using the number formatter. It contains an object as described in Number.format.

sortable

Boolean

Provided by the datatable-sort module.

Defined in yui3/src/datatable/js/sort.js:899

Used when the instance's sortable attribute is set to "auto" (the default) to determine which columns will support user sorting by clicking on the header.

If the instance's key attribute is not set, this configuration is ignored.

{ key: 'lastLogin', sortable: true }

sortDir

Number

Provided by the datatable-sort module.

Defined in yui3/src/datatable/js/sort.js:959

(read-only) If a column is sorted, this will be set to 1 for ascending order or -1 for descending. This configuration is public for inspection, but can't be used during DataTable instantiation to set the sort direction of the column. Use the table's sortBy attribute for that.

sortFn

Function

Provided by the datatable-sort module.

Defined in yui3/src/datatable/js/sort.js:926

Allows a column to be sorted using a custom algorithm. The function receives three parameters, the first two being the two record Models to compare, and the third being a boolean true if the sort order should be descending.

The function should return 1 to sort a above b, -1 to sort a below b, and 0 if they are equal. Keep in mind that the order should be reversed when desc is true.

The desc parameter is provided to allow sortFns to always sort certain values above or below others, such as always sorting nulls on top.

{
                                                  label: 'Name',
                                                  sortFn: function (a, b, desc) {
                                                    var an = a.get('lname') + b.get('fname'),
                                                        bn = a.get('lname') + b.get('fname'),
                                                        order = (an > bn) ? 1 : -(an < bn);
                                                
                                                    return desc ? -order : order;
                                                  },
                                                  formatter: function (o) {
                                                    return o.data.lname + ', ' + o.data.fname;
                                                  }
                                                }

title

String

Assigns the value <th title="HERE">.

{
                                                  key  : 'forecast',
                                                  label: '1yr Target Forecast',
                                                  title: 'Target Forecast for the Next 12 Months'
                                                }

width

String

Adds a style width setting to an associated <col> element for the column.

Note, the assigned width will not truncate cell content, and it will not preserve the configured width if doing so would compromise either the instance's width configuration or the natural width of the table's containing DOM elements.

If absolute widths are required, it can be accomplished with some custom CSS and the use of a cellTemplate, or formatter.

See the description of datatable-column-widths for an example of how to do this.

{ key: 'a', width: '400px' },
                                                { key: 'b', width: '10em' }