API Docs for:
Show:

DataTable.Core Class

Class extension providing the core API and structure for the DataTable Widget.

Methods

_afterColumnsChange

(
  • e
)
protected

Updates the _columnMap property in response to changes in the columns attribute.

Parameters:

  • e EventFacade

    The columnsChange event object

_createRecordClass

(
  • attrs
)
Model protected

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 | Object

    Names assigned to the Model subclass's ATTRS or its entire ATTRS definition object

Returns:

Model:

_createTable

() Node protected

Creates the <table>.

Returns:

Node: The <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
)
protected

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 EventFacade

    The renderBody event

_defRenderFooterFn

(
  • e
)
protected

Calls render() on the footerView class instance and inserts the view's container into the <table>.

Assigns the instance's foot property from e.view and the _tfootNode from the view's container attribute.

Parameters:

  • e EventFacade

    The renderFooter event

_defRenderHeaderFn

(
  • e
)
protected

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 EventFacade

    The renderHeader event

_defRenderTableFn

(
  • e
)
protected

Renders the <table>, <caption>, and <colgroup>.

Assigns the generated table to the _tableNode property.

Parameters:

  • e EventFacade

    The renderTable event

_getColumns

(
  • columns
  • name
)
protected

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 Object

    The full array of column objects

  • name String

    The attribute name requested (e.g. 'columns' or 'columns.foo');

_getColumnset

(
  • ignored
  • name
)
deprecated protected

Provided by the datatable-core module.

Defined in /Users/lsmith/dev/yui3-gallery/src/gallery-datatable-350-preview/js/datatable.js:789

Deprecated: This will be removed with the columnset attribute in a future version.

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 Object

    The current value stored in the columnset state

  • name String

    The attribute name requested (e.g. 'columnset' or 'columnset.foo');

_getData

(
  • val
)
protected

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 | ModelList

    The 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:

  1. If the data attribute is set with a ModelList with a model property, that class is used.
  2. If the data attribute is set with a non-empty ModelList, the constructor of the first item is used.
  3. If the data attribute is set with a non-empty array and the first item is a Base subclass, its constructor is used.
  4. 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 its ATTRS.
  5. If the _columnMap property has keys, a custom Model subclass is generated using those keys as its ATTRS.

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
)
protected

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 | String

    The array of column names or configuration objects to scan

_setColumnMap

(
  • columns
)
protected

Assigns the _columnMap property with the parsed results of the array of column definitions passed.

Parameters:

  • columns Object | String

    the raw column configuration objects or key names

_setColumnset

(
  • val
)
deprecated protected

Provided by the datatable-core module.

Defined in /Users/lsmith/dev/yui3-gallery/src/gallery-datatable-350-preview/js/datatable.js:1193

Deprecated: This will be removed with the deprecated columnset attribute in a later version.

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 | Columnset

    The 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
)
protected

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 Object

    Column config array to extract display columns from

_setRecordset

(
  • val
)
deprecated protected

Provided by the datatable-core module.

Defined in /Users/lsmith/dev/yui3-gallery/src/gallery-datatable-350-preview/js/datatable.js:1291

Deprecated: This will be removed with the deprecated recordset attribute in a later version.

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 | Recordset

    The recordset value to relay

_setRecordType

(
  • val
)
Function protected

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 | Object

    The Model subclass, array of attribute names, or the ATTRS definition for a custom model subclass

Returns:

Function: A Base/Model subclass

_uiSetCaption

(
  • htmlContent
)
protected

Creates, removes, or updates the table's <caption> element per the input value. Empty values result in the caption being removed.

Parameters:

  • htmlContent HTML

    The content to populate the table caption

_uiSetSummary

() protected

Updates the table's summary attribute with the input value.

_uiSetWidth

(
  • width
)
protected

Sets the boundingBox and table width per the input value.

Parameters:

  • width Number | String

    The 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
)
EventHandle

Pass through to delegate() called from the contentBox.

Parameters:

  • type String

    the event type to delegate

  • fn Function

    the callback function to execute. This function will be provided the event object for the delegated event.

  • spec String | Function

    a selector that must match the target of the event or a function to test target and its parents for a match

  • context Object

    optional argument that specifies what 'this' refers to

  • args Any multiple

    0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Returns:

EventHandle: the detach handle

getCell

(
  • row
  • col
)
Node

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 Number

    Index of the cell's containing row

  • col Number

    Index of the cell's containing column

Returns:

Node:

getColumn

(
  • name
)
Object

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 | Number

    Key, "name", index, or index array to identify the column

Returns:

Object: the column configuration object

getRow

(
  • index
)
Node

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 Number

    Index of the row in the data <tbody>

Returns:

Node:

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.

_footerConfig

Object protected

Configuration object passed to the class constructor in footerView during render.

This property is set by the _initViewConfig method at instantiation.

Default: undefined (initially unset)

_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.

caption

HTML

HTML content of an optional <caption> element to appear above the table. Leave this config unset or set to a falsy value to remove the caption.

Default: '' (empty string)

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

Provided by the datatable-core module.

Defined in /Users/lsmith/dev/yui3-gallery/src/gallery-datatable-350-preview/js/datatable.js:252

Deprecated: Use the columns attribute

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()

footerView

Function | Object

The class or object to use for rendering the <tfoot> and any relevant content for it. This attribute is responsible for populating the the instance's foot property.

If a class constructor (function) is passed, an instance of that clas will be created at render() time and assigned to this.foot. If an object is passed, foot 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 footerView. Classes built from this extension should define a default if appropriate.

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

Provided by the datatable-core module.

Defined in /Users/lsmith/dev/yui3-gallery/src/gallery-datatable-350-preview/js/datatable.js:237

Deprecated: Use the data attribute

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:

  1. If the data attribute is set with a ModelList instance and its model property is set, that will be used.
  2. If the data attribute is set with a ModelList instance, and its model property is unset, but it is populated, the ATTRS of the `constructor of the first item will be used.
  3. 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 its ATTRS (see the _createRecordClass method).
  4. If the columns attribute is set, a Model subclass will be generated using the columns defined with a key. This is least desirable because columns can be duplicated or nested in a way that's not parsable.
  5. If neither data nor columns is set or populated, a change event subscriber will listen for the first to be changed and try all over again.

Default: (see description)

summary

String

Content for the <table summary="ATTRIBUTE VALUE HERE">. Values assigned to this attribute will be HTML escaped for security.

Default: '' (empty string)