DataTable.Core Class
Class extension providing the core API and structure for the DataTable Widget.
Item Index
Methods
- _afterColumnsChange
- _createRecordClass
- _createTable
- _createTBody
- _createTFoot
- _createTHead
- _defRenderBodyFn
- _defRenderFooterFn
- _defRenderHeaderFn
- _defRenderTableFn
- _getColumns
- _getColumnset
- _getData
- _initColumns
- _initData
- _initEvents
- _initRecordType
- _initViewConfig
- _parseColumns
- _setColumnMap
- _setColumnset
- _setData
- _setDisplayColumns
- _setRecordset
- _setRecordType
- _uiSetCaption
- _uiSetSummary
- _uiSetWidth
- _validateView
- bindUI
- delegate
- getCell
- getColumn
- getRow
- initializer
- renderUI
- syncUI
Properties
Methods
_afterColumnsChange
-
e
Updates the _columnMap
property in response to changes in the columns
attribute.
Parameters:
-
e
EventFacadeThe
columnsChange
event object
_createRecordClass
-
attrs
Creates a Model subclass from an array of attribute names or an object of
attribute definitions. This is used to generate a class suitable to
represent the data passed to the data
attribute if no recordType
is
set.
Parameters:
-
attrs
String | ObjectNames assigned to the Model subclass's
ATTRS
or its entireATTRS
definition object
Returns:
_createTable
()
Node
protected
Creates the <table>
.
Returns:
<table>
node
_createTBody
()
protected
Creates a <tbody>
node from the TBODY_TEMPLATE
.
_createTFoot
()
protected
Creates a <tfoot>
node from the TFOOT_TEMPLATE
.
_createTHead
()
protected
Creates a <thead>
node from the THEAD_TEMPLATE
.
_defRenderBodyFn
-
e
Calls render()
on the bodyView
class instance and inserts the view's
container into the <table>
.
Assigns the instance's body
property from e.view
and the _tbodyNode
from the view's container
attribute.
Parameters:
-
e
EventFacadeThe renderBody event
_defRenderHeaderFn
-
e
Calls render()
on the headerView
class instance and inserts the view's
container into the <table>
.
Assigns the instance's head
property from e.view
and the _theadNode
from the view's container
attribute.
Parameters:
-
e
EventFacadeThe renderHeader event
_defRenderTableFn
-
e
Renders the <table>
, <caption>
, and <colgroup>
.
Assigns the generated table to the _tableNode
property.
Parameters:
-
e
EventFacadeThe renderTable event
_getColumns
-
columns
-
name
The getter for the columns
attribute. Returns the array of column
configuration objects if instance.get('columns')
is called, or the
specific column object if instance.get('columns.columnKey')
is called.
Parameters:
-
columns
ObjectThe full array of column objects
-
name
StringThe attribute name requested (e.g. 'columns' or 'columns.foo');
_getColumnset
-
ignored
-
name
Relays the get()
request for the deprecated columnset
attribute to the
columns
attribute.
THIS BREAKS BACKWARD COMPATIBILITY. 3.4.1 and prior implementations will
expect a Columnset instance returned from get('columnset')
.
Parameters:
-
ignored
ObjectThe current value stored in the
columnset
state -
name
StringThe attribute name requested (e.g. 'columnset' or 'columnset.foo');
_getData
-
val
The getter for the data
attribute. Returns the ModelList stored in the
data
property. If the ModelList is not yet set, it returns the current
raw data (presumably an empty array or undefined
).
Parameters:
-
val
Object | ModelListThe current data stored in the attribute
_initColumns
()
protected
Initializes the _columnMap
property from the configured columns
attribute. If columns
is not set, but recordType
is, it uses the
ATTRS
of that class. If neither are set, it temporarily falls back to an
empty array. _initRecordType
will call back into this method if it finds
the columnMap
empty.
_initData
()
protected
Initializes the instance's data
property from the value of the data
attribute. If the attribute value is a ModelList, it is assigned directly
to this.data
. If it is an array, a ModelList is created, its model
property is set to the configured recordType
class, and it is seeded with
the array data. This ModelList is then assigned to this.data
.
_initEvents
()
protected
Publishes core events.
_initRecordType
()
protected
If the recordType
attribute is not set, this method attempts to set a
default value.
It tries the following methods to determine a default:
- If the
data
attribute is set with a ModelList with amodel
property, that class is used. - If the
data
attribute is set with a non-empty ModelList, theconstructor
of the first item is used. - If the
data
attribute is set with a non-empty array and the first item is a Base subclass, its constructor is used. - If the
data
attribute is set with a non-empty array a custom Model subclass is generated using the keys of the first item as itsATTRS
. - If the
_columnMap
property has keys, a custom Model subclass is generated using those keys as itsATTRS
.
Of none of those are successful, it subscribes to the change events for
columns
, recordType
, and data
to try again.
If defaulting the recordType
and the current _columnMap
property is
empty, it will call _initColumns
.
_initViewConfig
()
protected
Initializes the _viewConfig
, _headerConfig
, _bodyConfig
, and
_footerConfig
properties with the configuration objects that will be
passed to the constructors of the headerView
, bodyView
, and
footerView
.
Extensions can add to the config objects to deliver custom parameters at
view instantiation. _viewConfig
is used as the prototype of the other
three config objects, so properties added here will be inherited by all
configs.
_parseColumns
-
columns
Iterates the array of column configurations to capture all columns with a
key
property. Columns that are represented as strings will be replaced
with objects with the string assigned as the key
property. If a column
has a children
property, it will be iterated, adding any nested column
keys to the returned map. There is no limit to the levels of nesting.
All columns are assigned a _yuid
stamp and _id
property corresponding
to the column's configured name
or key
property with any spaces
replaced with dashes. If the same name
or key
appears in multiple
columns, subsequent appearances will have their _id
appended with an
incrementing number (e.g. if column "foo" is included in the columns
attribute twice, the first will get _id
of "foo", and the second an _id
of "foo1").
The result is an object map with column keys as the property name and the corresponding column object as the associated value.
Parameters:
-
columns
Object | StringThe array of column names or configuration objects to scan
_setColumnMap
-
columns
Assigns the _columnMap
property with the parsed results of the array of
column definitions passed.
Parameters:
-
columns
Object | Stringthe raw column configuration objects or key names
_setColumnset
-
val
Relays attribute assignments of the deprecated columnset
attribute to the
columns
attribute. If a Columnset is object is passed, its basic object
structure is mined.
Parameters:
-
val
Array | ColumnsetThe columnset value to relay
_setData
()
protected
Accepts an object with each
and getAttrs
(preferably a ModelList or
subclass) or an array of data objects. If an array is passes, it will
create a ModelList to wrap the data. In doing so, it will set the created
ModelList's model
property to the class in the recordType
attribute,
which will be defaulted if not yet set.
If the data
property is already set with a ModelList, passing an array as
the value will call the ModelList's reset()
method with that array rather
than replacing the stored ModelList wholesale.
Any non-ModelList-ish and non-array value is invalid.
_setDisplayColumns
-
columns
Stores an array of columns intended for display in the _displayColumns
property. This method assumes that if a column configuration object does
not have children, it is a display column.
Parameters:
-
columns
ObjectColumn config array to extract display columns from
_setRecordset
-
val
Relays the value assigned to the deprecated recordset
attribute to the
data
attribute. If a Recordset instance is passed, the raw object data
will be culled from it.
Parameters:
-
val
Object | RecordsetThe recordset value to relay
_setRecordType
-
val
Accepts a Base subclass (preferably a Model subclass). Alternately, it will
generate a custom Model subclass from an array of attribute names or an
object defining attributes and their respective configurations (it is
assigned as the ATTRS
of the new class).
Any other value is invalid.
Parameters:
-
val
Function | String | ObjectThe Model subclass, array of attribute names, or the
ATTRS
definition for a custom model subclass
Returns:
_uiSetCaption
-
htmlContent
Creates, removes, or updates the table's <caption>
element per the input
value. Empty values result in the caption being removed.
Parameters:
-
htmlContent
HTMLThe content to populate the table caption
_uiSetSummary
()
protected
Updates the table's summary
attribute with the input value.
_uiSetWidth
-
width
Sets the boundingBox
and table width per the input value.
Parameters:
-
width
Number | StringThe width to make the table
_validateView
()
protected
Verifies the input value is a function with a render
method on its
prototype. null
is also accepted to remove the default View.
bindUI
()
protected
Subscribes to attribute change events to update the UI.
delegate
-
type
-
fn
-
spec
-
context
-
args
Pass through to delegate()
called from the contentBox
.
Parameters:
-
type
Stringthe event type to delegate
-
fn
Functionthe callback function to execute. This function will be provided the event object for the delegated event.
-
spec
String | Functiona selector that must match the target of the event or a function to test target and its parents for a match
-
context
Objectoptional argument that specifies what 'this' refers to
-
args
Any multiple0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.
Returns:
getCell
-
row
-
col
Returns the Node for a cell at the given coordinates.
Technically, this only relays to the bodyView
instance's getCell
method.
If the bodyView
doesn't have a getCell
method, undefined
is returned.
Parameters:
-
row
NumberIndex of the cell's containing row
-
col
NumberIndex of the cell's containing column
Returns:
getColumn
-
name
Gets the column configuration object for the given key, name, or index. For
nested columns, name
can be an array of indexes, each identifying the index
of that column in the respective parent's "children" array.
If you pass a column object, it will be returned.
For columns with keys, you can also fetch the column with
instance.get('columns.foo')
.
Parameters:
-
name
String | Number | NumberKey, "name", index, or index array to identify the column
Returns:
getRow
-
index
Returns the Node for a row at the given index.
Technically, this only relays to the bodyView
instance's getRow
method.
If the bodyView
doesn't have a getRow
method, undefined
is returned.
Parameters:
-
index
NumberIndex of the row in the data
<tbody>
Returns:
initializer
()
protected
Initializes the columns, recordType
and data ModelList.
renderUI
()
protected
Builds the table and attaches it to the DOM. This requires the host class
to provide a contentBox
attribute. This is typically provided by Widget.
syncUI
()
Updates the UI with the current attribute state.
Properties
_bodyConfig
Object
protected
Configuration object passed to the class constructor in bodyView
during
render.
This property is set by the _initViewConfig
method at instantiation.
Default: undefined (initially unset)
_columnMap
Object
protected
A map of column key to column configuration objects parsed from the
columns
attribute.
Default: undefined (initially unset)
_displayColumns
Object
protected
Contains column configuration objects for those columns believed to be intended for display in the <tbody>
. Populated by _setDisplayColumns
.
_headerConfig
Object
protected
Configuration object passed to the class constructor in headerView
during
render.
This property is set by the _initViewConfig
method at instantiation.
Default: undefined (initially unset)
_tableNode
Node
protected
The Node instance of the table containing the data rows. This is set when the table is rendered. It may also be set by progressive enhancement, though this extension does not provide the logic to parse from source.
Default: undefined (initially unset)
_viewConfig
Object
protected
Configuration object used as the prototype of _headerConfig
,
_bodyConfig
, and _footerConfig
. Add properties to this object if you
want them in all three of the other config objects.
This property is set by the _initViewConfig
method at instantiation.
Default: undefined (initially unset)
body
Object
The object or instance of the class assigned to bodyView
that is
responsible for rendering and managing the table's <tbody>
(s) and its
content.
Default: undefined (initially unset)
CAPTION_TEMPLATE
HTML
The HTML template used to create the caption Node if the caption
attribute is set.
Default: '<caption class="{className}"/>'
data
ModelList
The ModelList that manages the table's data.
Default: undefined (initially unset)
foot
Object
The object or instance of the class assigned to footerView
that is
responsible for rendering and managing the table's <tfoot>
and its
content.
Default: undefined (initially unset)
head
Object
The object or instance of the class assigned to headerView
that is
responsible for rendering and managing the table's <thead>
and its
content.
Default: undefined (initially unset)
TABLE_TEMPLATE
HTML
The HTML template used to create the table Node.
Default: '<table class="{className}"/>'
TBODY_TEMPLATE
HTML
HTML template used to create table's <tbody>
if configured with a
bodyView
.
Default: '<tbody class="{className}"/>'
TFOOT_TEMPLATE
HTML
Template used to create the table's <tfoot>
if configured with a
footerView
.
Default: '<tfoot class="{className}"/>'
THEAD_TEMPLATE
HTML
Template used to create the table's <thead>
if configured with a
headerView
.
Default: '<thead class="{className}"/>'
Attributes
bodyView
Function | Object
The class or object to use for rendering the <tbody>
or <tbody>
s and
all data row content for the table. This attribute is responsible for
populating the the instance's body
property.
If a class constructor (function) is passed, an instance of that clas will
be created at render()
time and assigned to this.body
. If an object is
passed, body
will be set immediately.
Valid objects or classes will have a render()
method, though it is
recommended that they be subclasses of Y.Base
or Y.View
. If the object
or class supports events, its addTarget()
method will be called to bubble
its events to this instance.
The core implementaion does not define a default bodyView
. Classes
built from this extension should define a default.
columns
Object | String
Columns to include in the rendered table.
If omitted, the attributes on the configured recordType
or the first item
in the data
collection will be used as a source.
This attribute takes an array of strings or objects (mixing the two is
fine). Each string or object is considered a column to be rendered.
Strings are converted to objects, so columns: ['first', 'last']
becomes
columns: [{ key: 'first' }, { key: 'last' }]
.
DataTable.Core only concerns itself with the key
property of columns.
All other properties are for use by the headerView
, bodyView
,
footerView
, and any class extensions or plugins on the final class or
instance. See the descriptions of the view classes and feature class
extensions and plugins for details on the specific properties they read or
add to column definitions.
Default: (from recordType
ATTRS or first item in the data
)
columnset
Object | Columnset
deprecated
Deprecated as of 3.5.0. Passes through to the columns
attribute.
If a Columnset object is passed, its raw object and array column data will be extracted for use.
WARNING: get('columnset')
will NOT return a Columnset instance as of
3.5.0. This is a break in backward compatibility.
data
ModelList | Object
The collection of data records to display. This attribute is a pass
through to a data
property, which is a ModelList instance.
If this attribute is passed a ModelList or subclass, it will be assigned to
the property directly. If an array of objects is passed, a new ModelList
will be created using the configured recordType
as its model
property
and seeded with the array.
Retrieving this attribute will return the ModelList stored in the data
property.
Default: new ModelList()
headerView
Function | Object
The class or object to use for rendering the <thead>
and column headers
for the table. This attribute is responsible for populating the the
instance's head
property.
If a class constructor (function) is passed, an instance of that clas will
be created at render()
time and assigned to this.head
. If an object is
passed, head
will be set immediately.
Valid objects or classes will have a render()
method, though it is
recommended that they be subclasses of Y.Base
or Y.View
. If the object
or class supports events, its addTarget()
method will be called to bubble
its events to this instance.
The core implementaion does not define a default headerView
. Classes
built from this extension should define a default.
recordset
Object | Recordset
deprecated
Deprecated as of 3.5.0. Passes through to the data
attribute.
WARNING: get('recordset')
will NOT return a Recordset instance as of
3.5.0. This is a break in backward compatibility.
recordType
Function
Model subclass to use as the model
for the ModelList stored in the data
attribute.
If not provided, it will try really hard to figure out what to use. The following attempts will be made to set a default value:
- If the
data
attribute is set with a ModelList instance and itsmodel
property is set, that will be used. - If the
data
attribute is set with a ModelList instance, and itsmodel
property is unset, but it is populated, theATTRS
of the `constructor of the first item will be used. - If the
data
attribute is set with a non-empty array, a Model subclass will be generated using the keys of the first item as itsATTRS
(see the_createRecordClass
method). - If the
columns
attribute is set, a Model subclass will be generated using the columns defined with akey
. This is least desirable because columns can be duplicated or nested in a way that's not parsable. - If neither
data
norcolumns
is set or populated, a change event subscriber will listen for the first to be changed and try all over again.
Default: (see description)