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 nodeFormatter
s 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
ornodeFormatter
only) if the implementer wants a predictable name to refer to in their CSS.cellTemplate
- Overrides the instance'sCELL_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 byformatter
s. 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 aformatter
, is the empty string,null
, orundefined
.allowHTML
- Set totrue
if a column value,formatter
, oremptyCellValue
can contain HTML. This defaults tofalse
to protect against XSS.className
- Space delimited CSS classes to add to all<td>
s in a column.
Column formatter
s 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 allowformatter
s to add CSS classes to the cell's<td>
.rowIndex
- The zero-based row number.rowClass
- Initially empty string to allowformatter
s 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 nodeFormatter
s 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 nodeFormatter
s.
Item Index
Methods
Methods
_afterColumnChange
-
e
Handles changes in the source's columns attribute. Redraws the table data.
Parameters:
-
e
EventFacadeThe
columnsChange
event object
_afterDataChange
-
e
Handles modelList changes, including additions, deletions, and updates.
Modifies the existing table DOM accordingly.
Parameters:
-
e
EventFacadeThe
change
event from the ModelList
_applyNodeFormatters
-
tbody
-
columns
Iterates the modelList
, and calls any nodeFormatter
s found in the
columns
param on the appropriate cell Nodes in the tbody
.
Parameters:
-
tbody
NodeThe
<tbody>
Node whose columns to update -
columns
ObjectThe column configurations
_createDataHTML
-
columns
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
ObjectThe column configurations to customize the generated cell content or class names
Returns:
modelList
, each applied
to the _rowTemplate
_createRowHTML
-
model
-
index
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'sfoo
attribute, or the result of the column'sformatter
if assigned. If the value is '',null
, orundefined
, and the column'semptyCellValue
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 (viao.rowClass
).
Because this object is available to formatters, any additional properties
can be added to fill in custom {placeholders} in the _rowTemplate
.
Parameters:
-
model
ModelThe Model instance to apply to the row template
-
index
NumberThe index the row will be appearing
Returns:
nodeFormatter
s
_createRowTemplate
-
columns
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 formatter
s.
Assigns the _rowTemplate
property.
Parameters:
-
columns
ObjectArray of column configuration objects
_parseColumns
-
data
-
columns
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
ObjectArray of unfiltered column configuration objects
-
columns
ObjectWorking array of data columns. Used for recursion.
Returns:
bindUI
()
protected
Binds event subscriptions from the UI and the source (if assigned).
destructor
()
protected
Destroys the instance.
getCell
-
row
-
col
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
NumberZero based index of the row with the target cell
-
col
NumberZero based index of the column with the target cell
Returns:
getClassName
-
token
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 multipleAny number of tokens to include in the class name
Returns:
getRow
-
row
Returns the <tr>
Node from the given row index. If there is
no row at the given index, null
is returned.
Parameters:
-
row
NumberZero based index of the row
Returns:
initializer
-
config
Initializes the instance. Reads the following configuration properties in addition to the instance attributes:
columns
- (REQUIRED) The initial column informationcssPrefix
- The base string for classes generated bygetClassName
source
- The object to serve as source of truth for column info
Parameters:
-
config
ObjectConfiguration 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:
A row template is assembled from the
columns
property (see_createRowTemplate
)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 withformatter
s, the function is called to generate cell content. Cells withnodeFormatter
s 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.If any column is configured with a
nodeFormatter
, themodelList
is iterated again to apply thenodeFormatter
s.
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
ornodeFormatter
only) if the implementer wants a predictable name to refer to in their CSS.cellTemplate
- Overrides the instance'sCELL_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 byformatter
s. 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 aformatter
, is the empty string,null
, orundefined
.allowHTML
- Set totrue
if a column value,formatter
, oremptyCellValue
can contain HTML. This defaults tofalse
to protect against XSS.className
- Space delimited CSS classes to add to all<td>
s in a column.
Column formatter
s 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 allowformatter
s to add CSS classes to the cell's<td>
.rowIndex
- The zero-based row number.rowClass
- Initially empty string to allowformatter
s 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 nodeFormatter
s 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 nodeFormatter
s.
Returns:
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)