diff --git a/src/data-grid.js b/src/data-grid.js index 2dd31c94d..51df394cd 100644 --- a/src/data-grid.js +++ b/src/data-grid.js @@ -2,9 +2,10 @@ * Data grid is a simple widget designed to list the filtered records, providing * a simple way to define how the items are displayed. * - * Note: Unlike other charts, the data grid chart (and data table) use the {@link dc.dataGrid#group group} attribute as a keying function - * for {@link https://github.com/d3/d3-collection/blob/master/README.md#nest nesting} the data together in groups. - * Do not pass in a crossfilter group as this will not work. + * + * Note: Formerly the data grid chart (and data table) used the {@link dc.dataGrid#group group} attribute as a + * keying function for {@link https://github.com/d3/d3-collection/blob/master/README.md#nest nesting} the data + * together in sections. This was confusing so it has been renamed to `section`, although `group` still works. * * Examples: * - {@link http://europarl.me/dc.js/web/ep/index.html List of members of the european parliament} @@ -21,11 +22,12 @@ dc.dataGrid = function (parent, chartGroup) { var LABEL_CSS_CLASS = 'dc-grid-label'; var ITEM_CSS_CLASS = 'dc-grid-item'; - var GROUP_CSS_CLASS = 'dc-grid-group'; + var SECTION_CSS_CLASS = 'dc-grid-section dc-grid-group'; var GRID_CSS_CLASS = 'dc-grid-top'; var _chart = dc.baseMixin({}); + var _section = null; var _size = 999; // shouldn't be needed, but you might var _html = function (d) { return 'you need to provide an html() handling param: ' + JSON.stringify(d); }; var _sortBy = function (d) { @@ -34,54 +36,56 @@ dc.dataGrid = function (parent, chartGroup) { var _order = d3.ascending; var _beginSlice = 0, _endSlice; - var _htmlGroup = function (d) { - return '

' + + var _htmlSection = function (d) { + return '

' + _chart.keyAccessor()(d) + '

'; }; + _chart._mandatoryAttributes(['dimension', 'section']); + _chart._doRender = function () { _chart.selectAll('div.' + GRID_CSS_CLASS).remove(); - renderItems(renderGroups()); + renderItems(renderSections()); return _chart; }; - function renderGroups () { - var groups = _chart.root().selectAll('div.' + GRID_CSS_CLASS) + function renderSections () { + var sections = _chart.root().selectAll('div.' + GRID_CSS_CLASS) .data(nestEntries(), function (d) { return _chart.keyAccessor()(d); }); - var itemGroup = groups + var itemSection = sections .enter() .append('div') .attr('class', GRID_CSS_CLASS); - if (_htmlGroup) { - itemGroup + if (_htmlSection) { + itemSection .html(function (d) { - return _htmlGroup(d); + return _htmlSection(d); }); } - groups.exit().remove(); - return itemGroup; + sections.exit().remove(); + return itemSection; } function nestEntries () { var entries = _chart.dimension().top(_size); return d3.nest() - .key(_chart.group()) + .key(_chart.section()) .sortKeys(_order) .entries(entries.sort(function (a, b) { return _order(_sortBy(a), _sortBy(b)); }).slice(_beginSlice, _endSlice)); } - function renderItems (groups) { - var items = groups.order() + function renderItems (sections) { + var items = sections.order() .selectAll('div.' + ITEM_CSS_CLASS) .data(function (d) { return d.values; @@ -106,21 +110,40 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - * Get or set the group function for the data grid. The group function takes a data row and + * Get or set the section function for the data grid. The section function takes a data row and * returns the key to specify to {@link https://github.com/d3/d3-collection/blob/master/README.md#nest d3.nest} - * to split rows into groups. + * to split rows into sections. * - * Do not pass in a crossfilter group as this will not work. - * @method group + * Do not pass in a crossfilter section as this will not work. + * @method section * @memberof dc.dataGrid * @instance * @example - * // group rows by the value of their field + * // section rows by the value of their field * chart - * .group(function(d) { return d.field; }) + * .section(function(d) { return d.field; }) + * @param {Function} section Function taking a row of data and returning the nest key. + * @returns {Function|dc.dataGrid} + */ + _chart.section = function (section) { + if (!arguments.length) { + return _section; + } + _section = section; + return _chart; + }; + + /** + * Backward-compatible synonym for {@link dc.dataGrid#section section}. + * + * @method group + * @memberof dc.dataGrid + * @instance * @param {Function} groupFunction Function taking a row of data and returning the nest key. - * @returns {Function|dc.dataTable} + * @returns {Function|dc.dataGrid} */ + _chart.group = dc.logger.annotate(_chart.section, + 'consider using dataGrid.section instead of dataGrid.group for clarity'); /** * Get or set the index of the beginning slice which determines which entries get displayed by the widget. @@ -193,23 +216,34 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - * Get or set the function that formats a group label. - * @method htmlGroup + * Get or set the function that formats a section label. + * @method htmlSection * @memberof dc.dataGrid * @instance * @example - * chart.htmlGroup (function (d) { return '

'.d.key . 'with ' . d.values.length .' items

'}); - * @param {Function} [htmlGroup] + * chart.htmlSection (function (d) { return '

'.d.key . 'with ' . d.values.length .' items

'}); + * @param {Function} [htmlSection] * @returns {Function|dc.dataGrid} */ - _chart.htmlGroup = function (htmlGroup) { + _chart.htmlSection = function (htmlSection) { if (!arguments.length) { - return _htmlGroup; + return _htmlSection; } - _htmlGroup = htmlGroup; + _htmlSection = htmlSection; return _chart; }; + /** + * Backward-compatible synonym for {@link dc.dataGrid#htmlSection htmlSection}. + * @method htmlGroup + * @memberof dc.dataGrid + * @instance + * @param {Function} [htmlGroup] + * @returns {Function|dc.dataGrid} + */ + _chart.htmlGroup = dc.logger.annotate(_chart.htmlSection, + 'consider using dataGrid.htmlSection instead of dataGrid.htmlGroup for clarity'); + /** * Get or set sort-by function. This function works as a value accessor at the item * level and returns a particular field to be sorted. diff --git a/web/ep/index.html b/web/ep/index.html index b84087a4f..d6dd12838 100644 --- a/web/ep/index.html +++ b/web/ep/index.html @@ -148,7 +148,7 @@ dc.dataGrid(".dc-data-grid") .dimension(country) - .group(function (d) { + .section(function (d) { return d.country; }) .size(1000)