core.js revision 201232b90752c6d505c32c25b94ba1c66e41f256
in the `headerView`, `bodyView`, and `footerView` attributes. In this extension they have no default values, requiring implementers to supply their own classes to render the table content. // TODO: add this to Y.Object // Not doing a hasOwnProperty check on purpose Class extension providing the core API and structure for the DataTable Widget. 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. @type {Object[]|String[]} @default (from `recordType` ATTRS or first item in the `data`) // TODO: change to setter to coerce Columnset? Model subclass to use as the `model` for the ModelList stored in the `data` 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 @default (see description) 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` @type {ModelList|Object[]} @default `new ModelList()` 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. 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. 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. Content for the `<table summary="ATTRIBUTE VALUE HERE">`. Values assigned to this attribute will be HTML escaped for security. @default '' (empty string) // For paranoid reasons, the value is escaped on its way in because // rendering can be based on string concatenation. 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) 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. @type {Object[]|Recordset} @deprecated Use the `data` 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 WARNING: `get('columnset')` will NOT return a Columnset instance as of 3.5.0. This is a break in backward compatibility. @type {Object[]|Columnset} @deprecated Use the `columns` attribute // -- Instance properties ------------------------------------------------- The HTML template used to create the caption Node if the `caption` @property CAPTION_TEMPLATE The HTML template used to create the table Node. HTML template used to create table's `<tbody>` if configured with a @default '<tbody class="{classes}"/>' Template used to create the table's `<tfoot>` if configured with a @default '<tfoot class="{classes}"/>' '<tfoot class="{classes}"/',
Template used to create the table's `<thead>` if configured with a @default '<thead class="{classes}"/>' '<thead class="{classes}"/>',
The object or instance of the class assigned to `bodyView` that is responsible for rendering and managing the table's `<tbody>`(s) and its @default undefined (initially unset) The object or instance of the class assigned to `footerView` that is responsible for rendering and managing the table's `<tfoot>` and its @default undefined (initially unset) The object or instance of the class assigned to `headerView` that is responsible for rendering and managing the table's `<thead>` and its @default undefined (initially unset) The ModelList that manages the table's data. @default undefined (initially unset) // -- Public methods ------------------------------------------------------ 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. @param {Number} row Index of the cell's containing row @param {Number} col Index of the cell's containing column 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')`. @param {String|Number|Number[]} name Key, "name", index, or index array to @return {Object} the column configuration object // TODO: support getting a column from a DOM node - this will cross // the line into the View logic, so it should be relayed // Assume an object passed in is already a column def // Only need to check against name because the initial // col = get('columns.' + name) would get it from the key map 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. @param {Number} index Index of the row in the data `<tbody>` Updates the UI with the current attribute state. // -- Protected and private properties and methods ------------------------ Configuration object passed to the class constructor in `bodyView` during This property is set by the `_initViewConfig` method at instantiation. @default undefined (initially unset) A map of column key to column configuration objects parsed from the @default undefined (initially unset) Configuration object passed to the class constructor in `footerView` during This property is set by the `_initViewConfig` method at instantiation. @default undefined (initially unset) Configuration object passed to the class constructor in `headerView` during This property is set by the `_initViewConfig` method at instantiation. @default undefined (initially unset) 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) 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) Relays `captionChange` events to `_uiSetCaption`. @method _afterCaptionChange @param {EventFacade} e The `captionChange` event object Updates the `_columnMap` property in response to changes in the `columns` @method _afterColumnsChange @param {EventFacade} e The `columnsChange` event object Relays `summaryChange` events to `_uiSetSummary`. @method _afterSummaryChange @param {EventFacade} e The `summaryChange` event object Subscribes to attribute change events to update the UI. // TODO: handle widget attribute changes 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 @method _createRecordClass @param {String[]|Object} attrs Names assigned to the Model subclass's `ATTRS` or its entire `ATTRS` definition object @return {Node} The `<table>` node Creates a `<tbody>` node from the `TBODY_TEMPLATE`. Creates a `<tfoot>` node from the `TFOOT_TEMPLATE`. Creates a `<thead>` node from the `THEAD_TEMPLATE`. 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. @param {EventFacade} e The renderBody event 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. @method _defRenderFooterFn @param {EventFacade} e The renderFooter event 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. @method _defRenderHeaderFn @param {EventFacade} e The renderHeader event Renders the `<table>`, `<caption>`, and `<colgroup>`. Assigns the generated table to the `_tableNode` property. @method _defRenderTableFn @param {EventFacade} e The renderTable event Contains column configuration objects for those columns believed to be intended for display in the `<tbody>`. Populated by `_setDisplayColumns`. @property _displayColumns @value undefined (initially not set) 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. @param {Object[]} columns The full array of column objects @param {String} name The attribute name requested (e.g. 'columns' or 'columns.foo'); // Workaround for an attribute oddity (ticket #2529254) // getter is expected to return an object if get('columns.foo') is called. // Note 'columns.' is 8 characters Relays the `get()` request for the deprecated `columnset` attribute to the THIS BREAKS BACKWARD COMPATIBILITY. 3.4.1 and prior implementations will expect a Columnset instance returned from `get('columnset')`. @param {Object} ignored The current value stored in the `columnset` state @param {String} name The attribute name requested (e.g. 'columnset' or 'columnset.foo'); @deprecated This will be removed with the `columnset` attribute in a future 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`). @param {Object[]|ModelList} val The current data stored in the attribute 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 // Default column definition from the configured recordType // TODO: merge superclass attributes up to Model? 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`. // _initRecordType is run before this, so recordType will be set // if the data array had any records. Otherwise, values is an // empty array, so no need to call reset(); // Make sure the attribute state object contains the ModelList. // TODO: maybe better would be to purge the attribute state value? // Y.bind used to allow late binding for method override support Initializes the columns, `recordType` and data ModelList. If the `recordType` attribute is not set, this method attempts to set a It tries the following methods to determine a default: 1. If the `data` attribute is set with a ModelList with a `model` property, 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`. if (!
this.
get(
'recordType')) {
// Use the ModelList's specified Model class // Or if not configured, use the construct of the first Model // Or if the data is an array, build a class from the first item // Or if the columns were defined, build a class from the keys // FIXME: Edge case race condition with // new DT({ on/after: { <any of these changes> } }) OR // new DT().on( <any of these changes> ) // where there's not enough info to assign this.data.model // executed before this subscription. [
'columnsChange',
'recordTypeChange',
'dataChange'],
// manually batch detach rather than manage separate // subs in case the change was inadequate to populate // recordType. But subs must be detached because the // subscriber recurses to _initRecordType, which would // result in duplicate subs. // FIXME: resubscribing if there's still not enough // info to populate recordType will place the new // subs later in the callback queue, opening the // race condition even more. // If recordType isn't set yet, _initRecordType // will have recreated this subscription. Initializes the `_viewConfig`, `_headerConfig`, `_bodyConfig`, and `_footerConfig` properties with the configuration objects that will be passed to the constructors of the `headerView`, `bodyView`, and 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 // Use prototypal inheritance to share common configs from _viewConfig 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. The result is an object map with column keys as the property name and the corresponding column object as the associated value. @param {Object[]|String[]} columns The array of column names or configuration objects to scan @param {Object} [map] The map to add keyed columns to // Update the array entry as well, so the attribute state array // contains the same objects. 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. // _viewConfig is the prototype for _headerConfig et al. this.
fire(
'renderTable', {
// off DOM or in an existing node attached to a different parentNode }
else { Y.
log(
'Problem rendering DataTable: table not created',
'warn',
'datatable');
// On the same line to allow builder to strip the else clause }
else { Y.
log(
'Problem rendering DataTable: contentBox not found',
'warn',
'datatable');
// On the same line to allow builder to strip the else clause Assigns the `_columnMap` property with the parsed results of the array of column definitions passed. @param {Object[]|String[]} columns the raw column configuration objects or Relays attribute assignments of the deprecated `columnset` attribute to the `columns` attribute. If a Columnset is object is passed, its basic object @param {Array|Columnset} val The columnset value to relay @deprecated This will be removed with the deprecated `columnset` attribute 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. // FIXME: this should happen only once, but this is a side // effect in the setter. Bad form, but I need the model set // before calling reset() // TODO: return true to avoid storing the data object both in // the state object underlying the attribute an in the data // property (decrease memory footprint)? // else pass through the array data, but don't assign this.data // Let the _initData process clean up. // TODO: return true to decrease memory footprint? 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. @method _setDisplayColumns @param {Object[]} columns Column config array to extract display columns from Relays the value assigned to the deprecated `recordset` attribute to the `data` attribute. If a Recordset instance is passed, the raw object data @param {Object[]|Recordset} val The recordset value to relay @deprecated This will be removed with the deprecated `recordset` attribute 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. @param {Function|String[]|Object} val The Model subclass, array of attribute names, or the `ATTRS` definition for a custom model Creates, removes, or updates the table's `<caption>` element per the input value. Empty values result in the caption being removed. @param {HTML} htmlContent The content to populate the table caption Updates the table's `summary` attribute with the input value. Sets the `boundingBox` and table width per the input value. @param {Number|String} width The width to make the table Verifies the input value is a function with a `render` method on its prototype. `null` is also accepted to remove the default View. // TODO support View instances?