API Docs for:
Show:

DataTable.BodyView Class

View class responsible for rendering the <tbody> section of a table. Used as the default bodyView for Y.DataTable.Base and Y.DataTable classes.

Translates the provided modelList into a rendered <tbody> based on the data in the constituent Models, altered or ammended by any special column configurations.

The columns configuration, passed to the constructor, determines which columns will be rendered.

The rendering process involves constructing an HTML template for a complete row of data, built by concatenating a customized copy of the instance's CELL_TEMPLATE into the ROW_TEMPLATE once for each column. This template is then populated with values from each Model in the modelList, aggregating a complete HTML string of all row and column data. A <tbody> Node is then created from the markup and any column nodeFormatters are applied.

Supported properties of the column objects include:

  • key - Used to link a column to an attribute in a Model.
  • name - Used for columns that don't relate to an attribute in the Model (formatter or nodeFormatter only) if the implementer wants a predictable name to refer to in their CSS.
  • cellTemplate - Overrides the instance's CELL_TEMPLATE for cells in this column only.
  • formatter - Used to customize or override the content value from the Model. These do not have access to the cell or row Nodes and should return string (HTML) content.
  • nodeFormatter - Used to provide content for a cell as well as perform any custom modifications on the cell or row Node that could not be performed by formatters. Should be used sparingly for better performance.
  • emptyCellValue - String (HTML) value to use if the Model data for a column, or the content generated by a formatter, is the empty string, null, or undefined.
  • allowHTML - Set to true if a column value, formatter, or emptyCellValue can contain HTML. This defaults to false to protect against XSS.
  • className - Space delimited CSS classes to add to all <td>s in a column.

Column formatters are passed an object (o) with the following properties:

  • value - The current value of the column's associated attribute, if any.
  • data - An object map of Model keys to their current values.
  • record - The Model instance.
  • column - The column configuration object for the current column.
  • className - Initially empty string to allow formatters to add CSS classes to the cell's <td>.
  • rowIndex - The zero-based row number.
  • rowClass - Initially empty string to allow formatters to add CSS classes to the cell's containing row <tr>.

They may return a value or update o.value to assign specific HTML content. A returned value has higher precedence.

Column nodeFormatters are passed an object (o) with the following properties:

  • value - The current value of the column's associated attribute, if any.
  • td - The <td> Node instance.
  • cell - The <div> liner Node instance if present, otherwise, the <td>. When adding content to the cell, prefer appending into this property.
  • data - An object map of Model keys to their current values.
  • record - The Model instance.
  • column - The column configuration object for the current column.
  • rowIndex - The zero-based row number.

They are expected to inject content into the cell's Node directly, including any "empty" cell content. Each nodeFormatter will have access through the Node API to all cells and rows in the <tbody>, but not to the <table>, as it will not be attached yet.

If a nodeFormatter returns false, the o.td and o.cell Nodes will be destroy()ed to remove them from the Node cache and free up memory. The DOM elements will remain as will any content added to them. It is highly advisable to always return false from your nodeFormatters.

Methods

_afterColumnChange

(
  • e
)
protected

Handles changes in the source's columns attribute. Redraws the table data.

Parameters:

  • e EventFacade

    The columnsChange event object

_afterDataChange

(
  • e
)
protected

Handles modelList changes, including additions, deletions, and updates.

Modifies the existing table DOM accordingly.

Parameters:

  • e EventFacade

    The change event from the ModelList

_applyNodeFormatters

(
  • tbody
  • columns
)
protected

Iterates the modelList, and calls any nodeFormatters found in the columns param on the appropriate cell Nodes in the tbody.

Parameters:

  • tbody Node

    The <tbody> Node whose columns to update

  • columns Object

    The column configurations

_createDataHTML

(
  • columns
)
HTML protected

Iterates the modelList and applies each Model to the _rowTemplate, allowing any column formatter or emptyCellValue to override cell content for the appropriate column. The aggregated HTML string is returned.

Parameters:

  • columns Object

    The column configurations to customize the generated cell content or class names

Returns:

HTML: The markup for all Models in the modelList, each applied to the _rowTemplate

_createRowHTML

(
  • model
  • index
)
HTML protected

Applies the data of a given Model, modified by any column formatters and supplemented by other template values to the instance's _rowTemplate (see _createRowTemplate). The generated string is then returned.

The data from Model's attributes is fetched by toJSON and this data object is appended with other properties to supply values to {placeholders} in the template. For a template generated from a Model with 'foo' and 'bar' attributes, the data object would end up with the following properties before being used to populate the _rowTemplate:

  • clientID - From Model, used the assign the <tr>'s 'id' attribute.
  • foo - The value to populate the 'foo' column cell content. This value will be the value stored in the Model's foo attribute, or the result of the column's formatter if assigned. If the value is '', null, or undefined, and the column's emptyCellValue is assigned, that value will be used.
  • bar - Same for the 'bar' column cell content.
  • foo-className - String of CSS classes to apply to the <td>.
  • bar-className - Same.
  • rowClass - String of CSS classes to apply to the <tr>. This will be the odd/even class per the specified index plus any additional classes assigned by column formatters (via o.rowClass).

Because this object is available to formatters, any additional properties can be added to fill in custom {placeholders} in the _rowTemplate.

Parameters:

  • model Model

    The Model instance to apply to the row template

  • index Number

    The index the row will be appearing

Returns:

HTML: The markup for the provided Model, less any nodeFormatters

_createRowTemplate

(
  • columns
)
protected

Creates a custom HTML template string for use in generating the markup for individual table rows with {placeholder}s to capture data from the Models in the modelList attribute or from column formatters.

Assigns the _rowTemplate property.

Parameters:

  • columns Object

    Array of column configuration objects

_parseColumns

(
  • data
  • columns
)
Object protected

Flattens an array of potentially nested column configurations into a single depth array of data columns. Columns that have children are disregarded in favor of searching their child columns. The resulting array corresponds 1:1 with columns that will contain data in the <tbody>.

Parameters:

  • data Object

    Array of unfiltered column configuration objects

  • columns Object

    Working array of data columns. Used for recursion.

Returns:

Object: Only those columns that will be rendered.

bindUI

() protected

Binds event subscriptions from the UI and the source (if assigned).

destructor

() protected

Destroys the instance.

getCell

(
  • row
  • col
)
Node

Returns the <td> Node from the given row and column index. If there is no cell at the given coordinates, null is returned.

Parameters:

  • row Number

    Zero based index of the row with the target cell

  • col Number

    Zero based index of the column with the target cell

Returns:

Node:

getClassName

(
  • token
)
String

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.

Parameters:

  • token String multiple

    Any number of tokens to include in the class name

Returns:

String: The generated class name

getRow

(
  • row
)
Node

Returns the <tr> Node from the given row index. If there is no row at the given index, null is returned.

Parameters:

  • row Number

    Zero based index of the row

Returns:

Node:

initializer

(
  • config
)
protected

Initializes the instance. Reads the following configuration properties in addition to the instance attributes:

  • 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

Parameters:

  • config Object

    Configuration data

render

() BodyView chainable

Creates the table's <tbody> content by assembling markup generated by populating the ROW\_TEMPLATE, and CELL\_TEMPLATE templates with content from the columns property and modelList attribute.

The rendering process happens in three stages:

  1. A row template is assembled from the columns property (see _createRowTemplate)

  2. An HTML string is built up by concatening the application of the data in each Model in the modelList to the row template. For cells with formatters, the function is called to generate cell content. Cells with nodeFormatters are ignored. For all other cells, the data value from the Model attribute for the given column key is used. The accumulated row markup is then inserted into the container.

  3. If any column is configured with a nodeFormatter, the modelList is iterated again to apply the nodeFormatters.

Supported properties of the column objects include:

  • key - Used to link a column to an attribute in a Model.
  • name - Used for columns that don't relate to an attribute in the Model (formatter or nodeFormatter only) if the implementer wants a predictable name to refer to in their CSS.
  • cellTemplate - Overrides the instance's CELL_TEMPLATE for cells in this column only.
  • formatter - Used to customize or override the content value from the Model. These do not have access to the cell or row Nodes and should return string (HTML) content.
  • nodeFormatter - Used to provide content for a cell as well as perform any custom modifications on the cell or row Node that could not be performed by formatters. Should be used sparingly for better performance.
  • emptyCellValue - String (HTML) value to use if the Model data for a column, or the content generated by a formatter, is the empty string, null, or undefined.
  • allowHTML - Set to true if a column value, formatter, or emptyCellValue can contain HTML. This defaults to false to protect against XSS.
  • className - Space delimited CSS classes to add to all <td>s in a column.

Column formatters are passed an object (o) with the following properties:

  • value - The current value of the column's associated attribute, if any.
  • data - An object map of Model keys to their current values.
  • record - The Model instance.
  • column - The column configuration object for the current column.
  • className - Initially empty string to allow formatters to add CSS classes to the cell's <td>.
  • rowIndex - The zero-based row number.
  • rowClass - Initially empty string to allow formatters to add CSS classes to the cell's containing row <tr>.

They may return a value or update o.value to assign specific HTML content. A returned value has higher precedence.

Column nodeFormatters are passed an object (o) with the following properties:

  • value - The current value of the column's associated attribute, if any.
  • td - The <td> Node instance.
  • cell - The <div> liner Node instance if present, otherwise, the <td>. When adding content to the cell, prefer appending into this property.
  • data - An object map of Model keys to their current values.
  • record - The Model instance.
  • column - The column configuration object for the current column.
  • rowIndex - The zero-based row number.

They are expected to inject content into the cell's Node directly, including any "empty" cell content. Each nodeFormatter will have access through the Node API to all cells and rows in the <tbody>, but not to the <table>, as it will not be attached yet.

If a nodeFormatter returns false, the o.td and o.cell Nodes will be destroy()ed to remove them from the Node cache and free up memory. The DOM elements will remain as will any content added to them. It is highly advisable to always return false from your nodeFormatters.

Returns:

BodyView: The instance

Properties

_cssPrefix

String protected

The base token for classes created with the getClassName method.

Default: 'yui3-table'

_eventHandles

Object protected

Holds the event subscriptions needing to be detached when the instance is destroy()ed.

Default: undefined (initially unset)

_rowTemplate

HTML protected

The HTML template used to create a full row of markup for a single Model in the modelList plus any customizations defined in the column configurations.

Default: (initially unset)

CELL_TEMPLATE

HTML

HTML template used to create table cells.

Default: '<td {headers} class="{className}">{content}</td>'

CLASS_EVEN

String

CSS class applied to even rows. This is assigned at instantiation after setting up the _cssPrefix for the instance.

For DataTable, this will be yui3-datatable-even.

Default: 'yui3-table-even'

CLASS_ODD

String

CSS class applied to odd rows. This is assigned at instantiation after setting up the _cssPrefix for the instance.

When used by DataTable instances, this will be yui3-datatable-odd.

Default: 'yui3-table-odd'

ROW_TEMPLATE

HTML

HTML template used to create table rows.

Default: '<tr id="{rowId}" class="{rowClass}">{content}</tr>'

source

Object

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.

Default: (initially unset)