From b9012dc0444c6e1df323e5c7450abb4208f7f5ee Mon Sep 17 00:00:00 2001 From: Matthew Traynham Date: Mon, 10 Aug 2015 22:34:56 -0400 Subject: [PATCH 1/8] Initial commit for jsdoc migration... --- Gruntfile.js | 53 +++---------- package.json | 1 + src/bar-chart.js | 158 ++++++++++++++++++++------------------- src/base-mixin.js | 166 +++++++++++++++++++++++------------------ src/core.js | 185 +++++++++++++++++++++++++--------------------- 5 files changed, 289 insertions(+), 274 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 36ea97942..02a6d2ad3 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -67,6 +67,10 @@ module.exports = function (grunt) { } }, watch: { + jsdoc2md: { + files: ['<%= conf.src %>/**/*.js'], + tasks: ['jsdoc2md'] + }, scripts: { files: ['<%= conf.src %>/**/*.js', '<%= conf.web %>/stock.js'], tasks: ['docs'] @@ -179,25 +183,12 @@ module.exports = function (grunt) { } } }, - emu: { - api: { - src: '<%= conf.pkg.name %>.js', - dest: '<%= conf.web %>/docs/api-latest.md' + jsdoc2md: { + dist: { + src: ['src/{core,base-mixin,bar-chart}.js'], + dest: 'web/docs/api-latest.md' } }, - toc: { - api: { - src: '<%= emu.api.dest %>', - dest: '<%= emu.api.dest %>' - } - }, - markdown: { - html: { - src: '<%= emu.api.dest %>', - dest: '<%= conf.web %>/docs/index.html' - }, - options: {markdownOptions: {highlight: 'manual'}} - }, docco: { options: { dst: '<%= conf.web %>/docs', @@ -324,35 +315,10 @@ module.exports = function (grunt) { } }); - // custom tasks - grunt.registerMultiTask('emu', 'Documentation extraction by emu.', function () { - var emu = require('emu'), - srcFile = this.files[0].src[0], - destFile = this.files[0].dest, - source = grunt.file.read(srcFile); - grunt.file.write(destFile, emu.getComments(source)); - grunt.log.writeln('File \'' + destFile + '\' created.'); - }); grunt.registerTask('merge', 'Merge a github pull request.', function (pr) { grunt.log.writeln('Merge Github Pull Request #' + pr); grunt.task.run(['shell:merge:' + pr, 'test' , 'shell:amend']); }); - grunt.registerMultiTask('toc', 'Generate a markdown table of contents.', function () { - var marked = require('marked'), - slugify = function (s) { return s.trim().replace(/[-_\s]+/g, '-').toLowerCase(); }, - srcFile = this.files[0].src[0], - destFile = this.files[0].dest, - source = grunt.file.read(srcFile), - tokens = marked.lexer(source), - toc = tokens.filter(function (item) { - return item.type === 'heading' && item.depth === 2; - }).reduce(function (toc, item) { - return toc + ' * [' + item.text + '](#' + slugify(item.text) + ')\n'; - }, ''); - - grunt.file.write(destFile, '# DC API\n' + toc + '\n' + source); - grunt.log.writeln('Added TOC to \'' + destFile + '\'.'); - }); grunt.registerTask('test-stock-example', 'Test a new rendering of the stock example web page against a ' + 'baseline rendering', function (option) { require('./regression/stock-regression-test.js').testStockExample(this.async(), option === 'diff'); @@ -373,7 +339,7 @@ module.exports = function (grunt) { // task aliases grunt.registerTask('build', ['concat', 'uglify']); - grunt.registerTask('docs', ['build', 'copy', 'emu', 'toc', 'markdown', 'docco', 'fileindex']); + grunt.registerTask('docs', ['build', 'copy', 'jsdoc2md', 'docco', 'fileindex']); grunt.registerTask('web', ['docs', 'gh-pages']); grunt.registerTask('server', ['docs', 'fileindex', 'jasmine:specs:build', 'connect:server', 'watch:jasmine-docs']); grunt.registerTask('test', ['build', 'jasmine:specs', 'shell:hooks']); @@ -383,6 +349,7 @@ module.exports = function (grunt) { grunt.registerTask('ci-pull', ['test', 'jasmine:specs:build', 'connect:server']); grunt.registerTask('lint', ['changed:jshint', 'changed:jscs']); grunt.registerTask('default', ['build']); + grunt.registerTask('jsdoc', ['jsdoc2md', 'watch:jsdoc2md']); }; module.exports.jsFiles = [ diff --git a/package.json b/package.json index 4a6f8449b..729a5ca67 100644 --- a/package.json +++ b/package.json @@ -45,6 +45,7 @@ "grunt-docco2": "~0.2.0", "grunt-fileindex": "^0.1.0", "grunt-gh-pages": "~0.9.1", + "grunt-jsdoc-to-markdown": "~1.1.1", "grunt-jscs": "~1.2.0", "grunt-lib-phantomjs": "~0.6.0", "grunt-markdown": "~0.7.0", diff --git a/src/bar-chart.js b/src/bar-chart.js index ca0226d4a..3e1009c83 100644 --- a/src/bar-chart.js +++ b/src/bar-chart.js @@ -1,38 +1,30 @@ /** -## Bar Chart -Includes: [Stack Mixin](#stack Mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Concrete bar chart/histogram implementation. - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.barChart(parent[, chartGroup]) -Create a bar chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection | compositeChart - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite - chart instance. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bar chart instance - -```js -// create a bar chart under #chart-container1 element using the default global chart group -var chart1 = dc.barChart('#chart-container1'); -// create a bar chart under #chart-container2 element using chart group A -var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.barChart(compositeChart); -``` - -**/ + * Concrete bar chart/histogram implementation. + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + * @name barChart + * @memberOf dc + * @mixes baseMixin + * @example + * // create a bar chart under #chart-container1 element using the default global chart group + * var chart1 = dc.barChart('#chart-container1'); + * // create a bar chart under #chart-container2 element using chart group A + * var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); + * // create a sub-chart under a composite parent chart + * var chart3 = dc.barChart(compositeChart); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + <<<<<<< HEAD + * @returns {barChart} + ======= + * @returns {BarChart} + >>>>>>> cec52eb469e363b35b6f8c2f36488f9bb1d481fc + */ dc.barChart = function (parent, chartGroup) { var MIN_BAR_WIDTH = 1; var DEFAULT_GAP_BETWEEN_BARS = 2; @@ -185,15 +177,18 @@ dc.barChart = function (parent, chartGroup) { }; /** - #### .centerBar(boolean) - Whether the bar chart will render each bar centered around the data position on x axis. Default: false - - **/ - _chart.centerBar = function (_) { + * Whether the bar chart will render each bar centered around the data position on x axis + * @name centerBar + * @memberOf dc.barChart + * @instance + * @param {Boolean} [centerBar=false] + * @returns {Boolean} + */ + _chart.centerBar = function (centerBar) { if (!arguments.length) { return _centerBar; } - _centerBar = _; + _centerBar = centerBar; return _chart; }; @@ -202,17 +197,21 @@ dc.barChart = function (parent, chartGroup) { }); /** - #### .barPadding([padding]) - Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. - Setting this value will also remove any previously set `gap`. See the - [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) - for a visual description of how the padding is applied. - **/ - _chart.barPadding = function (_) { + * Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. + * Setting this value will also remove any previously set `gap`. See the + * [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) + * for a visual description of how the padding is applied. + * @name barPadding + * @memberOf dc.barChart + * @instance + * @param {Number} [barPadding] + * @returns {Number} + */ + _chart.barPadding = function (barPadding) { if (!arguments.length) { return _chart._rangeBandPadding(); } - _chart._rangeBandPadding(_); + _chart._rangeBandPadding(barPadding); _gap = undefined; return _chart; }; @@ -222,26 +221,31 @@ dc.barChart = function (parent, chartGroup) { }; /** - #### .outerPadding([padding]) - Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. - Will pad the width by `padding * barWidth` on each side of the chart. - - Default: 0.5 - **/ + * Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. + * Will pad the width by `padding * barWidth` on each side of the chart. + * @name outerPadding + * @memberOf dc.barChart + * @instance + * @param {Number} [padding=0.5] + * @returns {Number} + */ _chart.outerPadding = _chart._outerRangeBandPadding; /** - #### .gap(gapBetweenBars) - Manually set fixed gap (in px) between bars instead of relying on the default auto-generated - gap. By default the bar chart implementation will calculate and set the gap automatically - based on the number of data points and the length of the x axis. - - **/ - _chart.gap = function (_) { + * Manually set fixed gap (in px) between bars instead of relying on the default auto-generated + * gap. By default the bar chart implementation will calculate and set the gap automatically + * based on the number of data points and the length of the x axis. + * @name gap + * @memberOf dc.barChart + * @instance + * @param {Number} [gap=2] + * @returns {Number} + */ + _chart.gap = function (gap) { if (!arguments.length) { return _gap; } - _gap = _; + _gap = gap; return _chart; }; @@ -259,23 +263,25 @@ dc.barChart = function (parent, chartGroup) { }; /** - #### .alwaysUseRounding([boolean]) - Set or get whether rounding is enabled when bars are centered. Default: false. If false, using - rounding with centered bars will result in a warning and rounding will be ignored. This flag - has no effect if bars are not centered. - - When using standard d3.js rounding methods, the brush often doesn't align correctly with - centered bars since the bars are offset. The rounding function must add an offset to - compensate, such as in the following example. - ```js - chart.round(function(n) {return Math.floor(n)+0.5}); - ``` - **/ - _chart.alwaysUseRounding = function (_) { + * Set or get whether rounding is enabled when bars are centered. Default: false. If false, using + * rounding with centered bars will result in a warning and rounding will be ignored. This flag + * has no effect if bars are not centered. + * When using standard d3.js rounding methods, the brush often doesn't align correctly with + * centered bars since the bars are offset. The rounding function must add an offset to + * compensate, such as in the following example. + * @name alwaysUseRounding + * @memberOf dc.barChart + * @instance + * @example + * chart.round(function(n) {return Math.floor(n)+0.5}); + * @param {Boolean} [alwaysUseRounding=false] + * @returns {Boolean} + */ + _chart.alwaysUseRounding = function (alwaysUseRounding) { if (!arguments.length) { return _alwaysUseRounding; } - _alwaysUseRounding = _; + _alwaysUseRounding = alwaysUseRounding; return _chart; }; diff --git a/src/base-mixin.js b/src/base-mixin.js index ad18f42a6..8d790052d 100644 --- a/src/base-mixin.js +++ b/src/base-mixin.js @@ -1,9 +1,13 @@ /** -## Base Mixin -Base Mixin is an abstract functional object representing a basic dc chart object -for all chart and widget implementations. Methods from the Base Mixin are inherited -and available on all chart implementation in the DC library. -**/ + * Base Mixin is an abstract functional object representing a basic dc chart object + * for all chart and widget implementations. Methods from the Base Mixin are inherited + * and available on all chart implementation in the DC library. + * @name baseMixin + * @memberOf dc + * @mixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.baseMixin = function (_chart) { _chart.__dcFlag__ = dc.utils.uniqueId(); @@ -90,11 +94,14 @@ dc.baseMixin = function (_chart) { }; /** - #### .width([value]) - Set or get the width attribute of a chart. See `.height` below for further description of the - behavior. - - **/ + * Set or get the width attribute of a chart. See `.height` below for further description of the + * behavior. + * @name width + * @memberOf dc.baseMixin + * @instance + * @param {Number|Function} w + * @returns {Number} + */ _chart.width = function (w) { if (!arguments.length) { return _width(_root.node()); @@ -104,26 +111,25 @@ dc.baseMixin = function (_chart) { }; /** - #### .height([value]) - Set or get the height attribute of a chart. The height is applied to the SVG element generated by - the chart when rendered (or rerendered). If a value is given, then it will be used to calculate - the new height and the chart returned for method chaining. The value can either be a numeric, a - function, or falsy. If no value is specified then the value of the current height attribute will - be returned. - - By default, without an explicit height being given, the chart will select the width of its - anchor element. If that isn't possible it defaults to 200. Setting the value falsy will return - the chart to the default behavior - - Examples: - - ```js - chart.height(250); // Set the chart's height to 250px; - chart.height(function(anchor) { return doSomethingWith(anchor); }); // set the chart's height with a function - chart.height(null); // reset the height to the default auto calculation - ``` - - **/ + * Set or get the height attribute of a chart. The height is applied to the SVG element generated by + * the chart when rendered (or rerendered). If a value is given, then it will be used to calculate + * the new height and the chart returned for method chaining. The value can either be a numeric, a + * function, or falsy. If no value is specified then the value of the current height attribute will + * be returned. + * + * By default, without an explicit height being given, the chart will select the width of its + * anchor element. If that isn't possible it defaults to 200. Setting the value falsy will return + * the chart to the default behavior + * @name height + * @memberOf dc.baseMixin + * @instance + * @example + * chart.height(250); // Set the chart's height to 250px; + * chart.height(function(anchor) { return doSomethingWith(anchor); }); // set the chart's height with a function + * chart.height(null); // reset the height to the default auto calculation + * @param {Number|Function} h + * @returns {Number} + */ _chart.height = function (h) { if (!arguments.length) { return _height(_root.node()); @@ -133,11 +139,14 @@ dc.baseMixin = function (_chart) { }; /** - #### .minWidth([value]) - Set or get the minimum width attribute of a chart. This only applicable if the width is - calculated by dc. - - **/ + * Set or get the minimum width attribute of a chart. This only applicable if the width is + * calculated by dc. + * @name minWidth + * @memberOf dc.baseMixin + * @instance + * @param {Number} w + * @returns {Number} + */ _chart.minWidth = function (w) { if (!arguments.length) { return _minWidth; @@ -147,28 +156,36 @@ dc.baseMixin = function (_chart) { }; /** - #### .minHeight([value]) - Set or get the minimum height attribute of a chart. This only applicable if the height is - calculated by dc. - - **/ - _chart.minHeight = function (w) { + * Set or get the minimum height attribute of a chart. This only applicable if the height is + * calculated by dc. + * @name minHeight + * @memberOf dc.baseMixin + * @instance + * @param {Number} h + * @returns {Number} + */ + _chart.minHeight = function (h) { if (!arguments.length) { return _minHeight; } - _minHeight = w; + _minHeight = h; return _chart; }; /** - #### .dimension([value]) - **mandatory** - Set or get the dimension attribute of a chart. In dc a dimension can be any valid [crossfilter - dimension](https://github.com/square/crossfilter/wiki/API-Reference#wiki-dimension). - - If a value is given, then it will be used as the new dimension. If no value is specified then - the current dimension will be returned. - - **/ + * **mandatory** + * + * Set or get the dimension attribute of a chart. In dc a dimension can be any valid [crossfilter + * dimension](https://github.com/square/crossfilter/wiki/API-Reference#wiki-dimension). + * + * If a value is given, then it will be used as the new dimension. If no value is specified then + * the current dimension will be returned. + * @name dimension + * @memberOf dc.baseMixin + * @instance + * @param {Dimension} d + * @returns {Dimension} + */ _chart.dimension = function (d) { if (!arguments.length) { return _dimension; @@ -179,16 +196,19 @@ dc.baseMixin = function (_chart) { }; /** - #### .data([callback]) - Set the data callback or retrieve the chart's data set. The data callback is passed the chart's - group and by default will return `group.all()`. This behavior may be modified to, for instance, - return only the top 5 groups: - ``` - chart.data(function(group) { - return group.top(5); - }); - ``` - **/ + * Set the data callback or retrieve the chart's data set. The data callback is passed the chart's + * group and by default will return `group.all()`. This behavior may be modified to, for instance, + * return only the top 5 groups. + * @name data + * @memberOf dc.baseMixin + * @instance + * @example + * chart.data(function(group) { + * return group.top(5); + * }); + * @param {Function} [callback] + * @returns {*} + */ _chart.data = function (d) { if (!arguments.length) { return _data.call(_chart, _group); @@ -199,16 +219,22 @@ dc.baseMixin = function (_chart) { }; /** - #### .group([value, [name]]) - **mandatory** - Set or get the group attribute of a chart. In dc a group is a [crossfilter - group](https://github.com/square/crossfilter/wiki/API-Reference#wiki-group). Usually the group - should be created from the particular dimension associated with the same chart. If a value is - given, then it will be used as the new group. - - If no value specified then the current group will be returned. - If `name` is specified then it will be used to generate legend label. - - **/ + * **mandatory** + * + * Set or get the group attribute of a chart. In dc a group is a [crossfilter + * group](https://github.com/square/crossfilter/wiki/API-Reference#wiki-group). Usually the group + * should be created from the particular dimension associated with the same chart. If a value is + * given, then it will be used as the new group. + * + * If no value specified then the current group will be returned. + * If `name` is specified then it will be used to generate legend label. + * @name group + * @memberOf dc.baseMixin + * @instance + * @param {Group} [group] + * @param {String} [name] + * @returns {Group} + */ _chart.group = function (g, name) { if (!arguments.length) { return _group; diff --git a/src/core.js b/src/core.js index 563b793a2..42a1fc525 100644 --- a/src/core.js +++ b/src/core.js @@ -1,22 +1,19 @@ /** -#### Version <%= conf.pkg.version %> -The entire dc.js library is scoped under the **dc** name space. It does not introduce anything else -into the global name space. -#### Function Chaining -Most dc functions are designed to allow function chaining, meaning they return the current chart -instance whenever it is appropriate. This way chart configuration can be written in the following -style: -```js -chart.width(300) - .height(300) - .filter('sunday') -``` -The getter forms of functions do not participate in function chaining because they necessarily -return values that are not the chart. (Although some, such as `.svg` and `.xAxis`, return values -that are chainable d3 objects.) - -**/ - + * The entire dc.js library is scoped under the **dc** name space. It does not introduce + * anything else into the global name space. + * + * Most `dc` functions are designed to allow function chaining, meaning they return the current chart + * instance whenever it is appropriate. The getter forms of functions do not participate in function + * chaining because they necessarily return values that are not the chart. Although some, + * such as `.svg` and `.xAxis`, return values that are chainable d3 objects. + * @namespace dc + * @version <%= conf.pkg.version %> + * @example + * // Example chaining + * chart.width(300) + * .height(300) + * .filter('sunday'); + */ /*jshint -W062*/ /*jshint -W079*/ var dc = { @@ -111,14 +108,12 @@ dc.deregisterAllCharts = function (group) { }; /** -## Utilities -**/ - -/** -#### dc.filterAll([chartGroup]) -Clear all filters on all charts within the given chart group. If the chart group is not given then -only charts that belong to the default chart group will be reset. -**/ + * Clear all filters on all charts within the given chart group. If the chart group is not given then + * only charts that belong to the default chart group will be reset. + * @memberOf dc + * @name filterAll + * @param {String} [group] + */ dc.filterAll = function (group) { var charts = dc.chartRegistry.list(group); for (var i = 0; i < charts.length; ++i) { @@ -127,10 +122,12 @@ dc.filterAll = function (group) { }; /** -#### dc.refocusAll([chartGroup]) -Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is -not given then only charts that belong to the default chart group will be reset. -**/ + * Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is + * not given then only charts that belong to the default chart group will be reset. + * @memberOf dc + * @name refocusAll + * @param {String} [group] + */ dc.refocusAll = function (group) { var charts = dc.chartRegistry.list(group); for (var i = 0; i < charts.length; ++i) { @@ -141,10 +138,12 @@ dc.refocusAll = function (group) { }; /** -#### dc.renderAll([chartGroup]) -Re-render all charts belong to the given chart group. If the chart group is not given then only -charts that belong to the default chart group will be re-rendered. -**/ + * Re-render all charts belong to the given chart group. If the chart group is not given then only + * charts that belong to the default chart group will be re-rendered. + * @memberOf dc + * @name renderAll + * @param {String} [group] + */ dc.renderAll = function (group) { var charts = dc.chartRegistry.list(group); for (var i = 0; i < charts.length; ++i) { @@ -157,12 +156,14 @@ dc.renderAll = function (group) { }; /** -#### dc.redrawAll([chartGroup]) -Redraw all charts belong to the given chart group. If the chart group is not given then only charts -that belong to the default chart group will be re-drawn. Redraw is different from re-render since -when redrawing dc tries to update the graphic incrementally, using transitions, instead of starting -from scratch. -**/ + * Redraw all charts belong to the given chart group. If the chart group is not given then only charts + * that belong to the default chart group will be re-drawn. Redraw is different from re-render since + * when redrawing dc tries to update the graphic incrementally, using transitions, instead of starting + * from scratch. + * @memberOf dc + * @name redrawAll + * @param {String} [group] + */ dc.redrawAll = function (group) { var charts = dc.chartRegistry.list(group); for (var i = 0; i < charts.length; ++i) { @@ -175,10 +176,13 @@ dc.redrawAll = function (group) { }; /** -#### dc.disableTransitions -If this boolean is set truthy, all transitions will be disabled, and changes to the charts will happen -immediately. Default: false -**/ + * If this boolean is set truthy, all transitions will be disabled, and changes to the charts will happen + * immediately + * @memberOf dc + * @name disableTransitions + * @type {Boolean} + * @default false + */ dc.disableTransitions = false; dc.transition = function (selections, duration, callback, name) { @@ -211,59 +215,70 @@ dc.optionalTransition = function (enable, duration, callback, name) { } }; +/** + * @name units + * @memberOf dc + * @type {{}} + */ dc.units = {}; /** -#### dc.units.integers -`dc.units.integers` is the default value for `xUnits` for the [Coordinate Grid -Chart](#coordinate-grid-chart) and should be used when the x values are a sequence of integers. - -It is a function that counts the number of integers in the range supplied in its start and end parameters. - -```js -chart.xUnits(dc.units.integers) // already the default -``` - -**/ -dc.units.integers = function (s, e) { - return Math.abs(e - s); + * The default value for `xUnits` for the [Coordinate Grid Chart](#coordinate-grid-chart) and should + * be used when the x values are a sequence of integers. + * It is a function that counts the number of integers in the range supplied in its start and end parameters. + * @name integers + * @memberOf dc.units + * @example + * chart.xUnits(dc.units.integers) // already the default + * @param {Number} start + * @param {Number} end + * @returns {Number} + */ +dc.units.integers = function (start, end) { + return Math.abs(end - start); }; /** -#### dc.units.ordinal -This argument can be passed to the `xUnits` function of the to specify ordinal units for the x -axis. Usually this parameter is used in combination with passing `d3.scale.ordinal()` to `.x`. - -It just returns the domain passed to it, which for ordinal charts is an array of all values. - -```js -chart.xUnits(dc.units.ordinal) - .x(d3.scale.ordinal()) -``` - -**/ + * This argument can be passed to the `xUnits` function of the to specify ordinal units for the x + * axis. Usually this parameter is used in combination with passing `d3.scale.ordinal()` to `.x`. + * It just returns the domain passed to it, which for ordinal charts is an array of all values. + * @name ordinal + * @memberOf dc.units + * @example + * chart.xUnits(dc.units.ordinal) + * .x(d3.scale.ordinal()) + * @param {*} start + * @param {*} end + * @param {Array} domain + * @returns {Array} + */ dc.units.ordinal = function (s, e, domain) { return domain; }; /** -#### dc.units.fp.precision(precision) -This function generates an argument for the [Coordinate Grid Chart's](#coordinate-grid-chart) -`xUnits` function specifying that the x values are floating-point numbers with the given -precision. - -The returned function determines how many values at the given precision will fit into the range -supplied in its start and end parameters. - -```js -// specify values (and ticks) every 0.1 units -chart.xUnits(dc.units.fp.precision(0.1) -// there are 500 units between 0.5 and 1 if the precision is 0.001 -var thousandths = dc.units.fp.precision(0.001); -thousandths(0.5, 1.0) // returns 500 -``` -**/ + * @name fp + * @memberOf dc.units + * @type {{}} + */ dc.units.fp = {}; +/** + * This function generates an argument for the [Coordinate Grid Chart's](#coordinate-grid-chart) + * `xUnits` function specifying that the x values are floating-point numbers with the given + * precision. + * The returned function determines how many values at the given precision will fit into the range + * supplied in its start and end parameters. + * @name precision + * @memberOf dc.units.fp + * @example + * // specify values (and ticks) every 0.1 units + * chart.xUnits(dc.units.fp.precision(0.1) + * // there are 500 units between 0.5 and 1 if the precision is 0.001 + * var thousandths = dc.units.fp.precision(0.001); + * thousandths(0.5, 1.0) // returns 500 + * @param {Number} precision + * @returns {Function} start-end unit function + */ dc.units.fp.precision = function (precision) { var _f = function (s, e) { var d = Math.abs((e - s) / _f.resolution); From 3393701459ea2440f36fd4b98d6e11abcc9c0aa2 Mon Sep 17 00:00:00 2001 From: Matthew Traynham Date: Mon, 10 Aug 2015 22:41:08 -0400 Subject: [PATCH 2/8] Adding preview for api docs --- web/docs/api-latest.md | 2258 ++++++---------------------------------- 1 file changed, 297 insertions(+), 1961 deletions(-) diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index c17264dfd..2cbf0213a 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -1,167 +1,84 @@ -# DC API - * [Utilities](#utilities) - * [Filters](#filters) - * [Base Mixin](#base-mixin) - * [Listeners](#listeners) - * [Margin Mixin](#margin-mixin) - * [Color Mixin](#color-mixin) - * [Coordinate Grid Mixin](#coordinate-grid-mixin) - * [Stack Mixin](#stack-mixin) - * [Cap Mixin](#cap-mixin) - * [Bubble Mixin](#bubble-mixin) - * [Pie Chart](#pie-chart) - * [Bar Chart](#bar-chart) - * [Line Chart](#line-chart) - * [Data Count Widget](#data-count-widget) - * [Data Table Widget](#data-table-widget) - * [Data Grid Widget](#data-grid-widget) - * [Bubble Chart](#bubble-chart) - * [Composite Chart](#composite-chart) - * [Series Chart](#series-chart) - * [Geo Choropleth Chart](#geo-choropleth-chart) - * [Bubble Overlay Chart](#bubble-overlay-chart) - * [Row Chart](#row-chart) - * [Legend](#legend) - * [Scatter Plot](#scatter-plot) - * [Number Display Widget](#number-display-widget) - * [Heat Map](#heat-map) - * [Box Plot](#box-plot) - -#### Version 2.0.0-beta.17 -The entire dc.js library is scoped under the **dc** name space. It does not introduce anything else -into the global name space. -#### Function Chaining -Most dc functions are designed to allow function chaining, meaning they return the current chart -instance whenever it is appropriate. This way chart configuration can be written in the following -style: -```js -chart.width(300) -.height(300) -.filter('sunday') -``` -The getter forms of functions do not participate in function chaining because they necessarily -return values that are not the chart. (Although some, such as `.svg` and `.xAxis`, return values -that are chainable d3 objects.) - -## Utilities - -#### dc.filterAll([chartGroup]) -Clear all filters on all charts within the given chart group. If the chart group is not given then -only charts that belong to the default chart group will be reset. - -#### dc.refocusAll([chartGroup]) -Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is -not given then only charts that belong to the default chart group will be reset. - -#### dc.renderAll([chartGroup]) -Re-render all charts belong to the given chart group. If the chart group is not given then only -charts that belong to the default chart group will be re-rendered. - -#### dc.redrawAll([chartGroup]) -Redraw all charts belong to the given chart group. If the chart group is not given then only charts -that belong to the default chart group will be re-drawn. Redraw is different from re-render since -when redrawing dc tries to update the graphic incrementally, using transitions, instead of starting -from scratch. - -#### dc.disableTransitions -If this boolean is set truthy, all transitions will be disabled, and changes to the charts will happen -immediately. Default: false - -#### dc.units.integers -`dc.units.integers` is the default value for `xUnits` for the [Coordinate Grid -Chart](#coordinate-grid-chart) and should be used when the x values are a sequence of integers. - -It is a function that counts the number of integers in the range supplied in its start and end parameters. - -```js -chart.xUnits(dc.units.integers) // already the default -``` - -#### dc.units.ordinal -This argument can be passed to the `xUnits` function of the to specify ordinal units for the x -axis. Usually this parameter is used in combination with passing `d3.scale.ordinal()` to `.x`. - -It just returns the domain passed to it, which for ordinal charts is an array of all values. + +## dc : object +The entire dc.js library is scoped under the **dc** name space. It does not introduce +anything else into the global name space. -```js -chart.xUnits(dc.units.ordinal) -.x(d3.scale.ordinal()) -``` - -#### dc.units.fp.precision(precision) -This function generates an argument for the [Coordinate Grid Chart's](#coordinate-grid-chart) -`xUnits` function specifying that the x values are floating-point numbers with the given -precision. - -The returned function determines how many values at the given precision will fit into the range -supplied in its start and end parameters. - -```js -// specify values (and ticks) every 0.1 units -chart.xUnits(dc.units.fp.precision(0.1) -// there are 500 units between 0.5 and 1 if the precision is 0.001 -var thousandths = dc.units.fp.precision(0.001); -thousandths(0.5, 1.0) // returns 500 -``` - -#### dc.events.trigger(function[, delay]) -This function triggers a throttled event function with a specified delay (in milli-seconds). Events -that are triggered repetitively due to user interaction such brush dragging might flood the library -and invoke more renders than can be executed in time. Using this function to wrap your event -function allows the library to smooth out the rendering by throttling events and only responding to -the most recent event. +Most `dc` functions are designed to allow function chaining, meaning they return the current chart +instance whenever it is appropriate. The getter forms of functions do not participate in function +chaining because they necessarily return values that are not the chart. Although some, +such as `.svg` and `.xAxis`, return values that are chainable d3 objects. +**Kind**: global namespace +**Version**: <%= conf.pkg.version %> +**Example** ```js -chart.on('renderlet', function(chart) { - // smooth the rendering through event throttling - dc.events.trigger(function(){ - // focus some other chart to the range selected by user on this chart - someOtherChart.focus(chart.filter()); - }); -}) -``` - -## Filters -The dc.js filters are functions which are passed into crossfilter to chose which records will be -accumulated to produce values for the charts. In the crossfilter model, any filters applied on one -dimension will affect all the other dimensions but not that one. dc always applies a filter -function to the dimension; the function combines multiple filters and if any of them accept a -record, it is filtered in. - -These filter constructors are used as appropriate by the various charts to implement brushing. We -mention below which chart uses which filter. In some cases, many instances of a filter will be added. - -#### dc.filters.RangedFilter(low, high) -RangedFilter is a filter which accepts keys between `low` and `high`. It is used to implement X -axis brushing for the [coordinate grid charts](#coordinate-grid-mixin). - -#### dc.filters.TwoDimensionalFilter(array) -TwoDimensionalFilter is a filter which accepts a single two-dimensional value. It is used by the -[heat map chart](#heat-map) to include particular cells as they are clicked. (Rows and columns are -filtered by filtering all the cells in the row or column.) +// Example chaining +chart.width(300) + .height(300) + .filter('sunday'); +``` + +* [dc](#dc) : object + * [.baseMixin](#dc.baseMixin) ⇒ Chart + * [.width](#dc.baseMixin+width) ⇒ Number + * [.height](#dc.baseMixin+height) ⇒ Number + * [.minWidth](#dc.baseMixin+minWidth) ⇒ Number + * [.minHeight](#dc.baseMixin+minHeight) ⇒ Number + * [.dimension](#dc.baseMixin+dimension) ⇒ Dimension + * [.data](#dc.baseMixin+data) ⇒ \* + * [.group](#dc.baseMixin+group) ⇒ Group + * [.barChart](#dc.barChart) ⇒ barChart | BarChart + * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean + * [.barPadding](#dc.barChart+barPadding) ⇒ Number + * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number + * [.gap](#dc.barChart+gap) ⇒ Number + * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean + * [.filterAll](#dc.filterAll) + * [.refocusAll](#dc.refocusAll) + * [.renderAll](#dc.renderAll) + * [.redrawAll](#dc.redrawAll) + * [.disableTransitions](#dc.disableTransitions) : Boolean + * [.units](#dc.units) : Object + * [.integers](#dc.units.integers) ⇒ Number + * [.ordinal](#dc.units.ordinal) ⇒ Array.<String> + * [.fp](#dc.units.fp) : Object + * [.precision](#dc.units.fp.precision) ⇒ function + + +### dc.baseMixin ⇒ Chart +Base Mixin is an abstract functional object representing a basic dc chart object +for all chart and widget implementations. Methods from the Base Mixin are inherited +and available on all chart implementation in the DC library. -#### dc.filters.RangedTwoDimensionalFilter(array) -The RangedTwoDimensionalFilter allows filtering all values which fit within a rectangular -region. It is used by the [scatter plot](#scatter-plot) to implement rectangular brushing. +**Kind**: static mixin of [dc](#dc) -It takes two two-dimensional points in the form `[[x1,y1],[x2,y2]]`, and normalizes them so that -`x1 <= x2` and `y1 <- y2`. It then returns a filter which accepts any points which are in the -rectangular range including the lower values but excluding the higher values. +| Param | Type | +| --- | --- | +| _chart | Chart | -If an array of two values are given to the RangedTwoDimensionalFilter, it interprets the values as -two x coordinates `x1` and `x2` and returns a filter which accepts any points for which `x1 <= x < -x2`. -## Base Mixin -Base Mixin is an abstract functional object representing a basic dc chart object -for all chart and widget implementations. Methods from the Base Mixin are inherited -and available on all chart implementation in the DC library. +* [.baseMixin](#dc.baseMixin) ⇒ Chart + * [.width](#dc.baseMixin+width) ⇒ Number + * [.height](#dc.baseMixin+height) ⇒ Number + * [.minWidth](#dc.baseMixin+minWidth) ⇒ Number + * [.minHeight](#dc.baseMixin+minHeight) ⇒ Number + * [.dimension](#dc.baseMixin+dimension) ⇒ Dimension + * [.data](#dc.baseMixin+data) ⇒ \* + * [.group](#dc.baseMixin+group) ⇒ Group -#### .width([value]) + +#### baseMixin.width ⇒ Number Set or get the width attribute of a chart. See `.height` below for further description of the behavior. -#### .height([value]) +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| w | Number | function | + + +#### baseMixin.height ⇒ Number Set or get the height attribute of a chart. The height is applied to the SVG element generated by the chart when rendered (or rerendered). If a value is given, then it will be used to calculate the new height and the chart returned for method chaining. The value can either be a numeric, a @@ -172,40 +89,78 @@ By default, without an explicit height being given, the chart will select the wi anchor element. If that isn't possible it defaults to 200. Setting the value falsy will return the chart to the default behavior -Examples: +**Kind**: instance property of [baseMixin](#dc.baseMixin) +| Param | Type | +| --- | --- | +| h | Number | function | + +**Example** ```js chart.height(250); // Set the chart's height to 250px; chart.height(function(anchor) { return doSomethingWith(anchor); }); // set the chart's height with a function chart.height(null); // reset the height to the default auto calculation ``` - -#### .minWidth([value]) + +#### baseMixin.minWidth ⇒ Number Set or get the minimum width attribute of a chart. This only applicable if the width is calculated by dc. -#### .minHeight([value]) +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| w | Number | + + +#### baseMixin.minHeight ⇒ Number Set or get the minimum height attribute of a chart. This only applicable if the height is calculated by dc. -#### .dimension([value]) - **mandatory** +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| h | Number | + + +#### baseMixin.dimension ⇒ Dimension +**mandatory** + Set or get the dimension attribute of a chart. In dc a dimension can be any valid [crossfilter dimension](https://github.com/square/crossfilter/wiki/API-Reference#wiki-dimension). If a value is given, then it will be used as the new dimension. If no value is specified then the current dimension will be returned. -#### .data([callback]) +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| d | Dimension | + + +#### baseMixin.data ⇒ \* Set the data callback or retrieve the chart's data set. The data callback is passed the chart's group and by default will return `group.all()`. This behavior may be modified to, for instance, -return only the top 5 groups: -``` - chart.data(function(group) { - return group.top(5); - }); +return only the top 5 groups. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [callback] | function | + +**Example** +```js +chart.data(function(group) { + return group.top(5); +}); ``` + +#### baseMixin.group ⇒ Group +**mandatory** -#### .group([value, [name]]) - **mandatory** Set or get the group attribute of a chart. In dc a group is a [crossfilter group](https://github.com/square/crossfilter/wiki/API-Reference#wiki-group). Usually the group should be created from the particular dimension associated with the same chart. If a value is @@ -214,1852 +169,233 @@ given, then it will be used as the new group. If no value specified then the current group will be returned. If `name` is specified then it will be used to generate legend label. -#### .ordering([orderFunction]) -Get or set an accessor to order ordinal charts - -#### .filterAll() -Clear all filters associated with this chart. - -#### .select(selector) -Execute d3 single selection in the chart's scope using the given selector and return the d3 -selection. Roughly the same as: -```js -d3.select('#chart-id').select(selector); -``` -This function is **not chainable** since it does not return a chart instance; however the d3 -selection result can be chained to d3 function calls. - -#### .selectAll(selector) -Execute in scope d3 selectAll using the given selector and return d3 selection result. Roughly -the same as: -```js -d3.select('#chart-id').selectAll(selector); -``` -This function is **not chainable** since it does not return a chart instance; however the d3 -selection result can be chained to d3 function calls. - -#### .anchor([anchorChart|anchorSelector|anchorNode], [chartGroup]) -Set the svg root to either be an existing chart's root; or any valid [d3 single -selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom -block element such as a div; or a dom element or d3 selection. Optionally registers the chart -within the chartGroup. This class is called internally on chart initialization, but be called -again to relocate the chart. However, it will orphan any previously created SVG elements. - -#### .anchorName() -Returns the dom id for the chart's anchored location. - -#### .root([rootElement]) -Returns the root element where a chart resides. Usually it will be the parent div element where -the svg was created. You can also pass in a new root element however this is usually handled by -dc internally. Resetting the root element on a chart outside of dc internals may have -unexpected consequences. - -#### .svg([svgElement]) -Returns the top svg element for this specific chart. You can also pass in a new svg element, -however this is usually handled by dc internally. Resetting the svg element on a chart outside -of dc internals may have unexpected consequences. - -#### .resetSvg() -Remove the chart's SVG elements from the dom and recreate the container SVG element. - -#### .filterPrinter([filterPrinterFunction]) -Set or get the filter printer function. The filter printer function is used to generate human -friendly text for filter value(s) associated with the chart instance. By default dc charts use a -default filter printer `dc.printers.filter` that provides simple printing support for both -single value and ranged filters. - -#### .turnOnControls() & .turnOffControls() -Turn on/off optional control elements within the root element. dc currently supports the -following html control elements. - -* root.selectAll('.reset') - elements are turned on if the chart has an active filter. This type - of control element is usually used to store a reset link to allow user to reset filter on a - certain chart. This element will be turned off automatically if the filter is cleared. -* root.selectAll('.filter') elements are turned on if the chart has an active filter. The text - content of this element is then replaced with the current filter value using the filter printer - function. This type of element will be turned off automatically if the filter is cleared. - -#### .transitionDuration([duration]) -Set or get the animation transition duration(in milliseconds) for this chart instance. Default -duration is 750ms. - -#### .render() -Invoking this method will force the chart to re-render everything from scratch. Generally it -should only be used to render the chart for the first time on the page or if you want to make -sure everything is redrawn from scratch instead of relying on the default incremental redrawing -behaviour. - -#### .redraw() -Calling redraw will cause the chart to re-render data changes incrementally. If there is no -change in the underlying data dimension then calling this method will have no effect on the -chart. Most chart interaction in dc will automatically trigger this method through internal -events (in particular [dc.redrawAll](#dcredrawallchartgroup)); therefore, you only need to -manually invoke this function if data is manipulated outside of dc's control (for example if -data is loaded in the background using `crossfilter.add()`). - -#### .hasFilterHandler([function]) -Set or get the has filter handler. The has filter handler is a function that checks to see if -the chart's current filters include a specific filter. Using a custom has filter handler allows -you to change the way filters are checked for and replaced. - -```js -// default has filter handler -function (filters, filter) { - if (filter === null || typeof(filter) === 'undefined') { - return filters.length > 0; - } - return filters.some(function (f) { - return filter <= f && filter >= f; - }); -} - -// custom filter handler (no-op) -chart.hasFilterHandler(function(filters, filter) { - return false; -}); -``` - -#### .hasFilter([filter]) -Check whether any active filter or a specific filter is associated with particular chart instance. -This function is **not chainable**. - -#### .removeFilterHandler([function]) -Set or get the remove filter handler. The remove filter handler is a function that removes a -filter from the chart's current filters. Using a custom remove filter handler allows you to -change how filters are removed or perform additional work when removing a filter, e.g. when -using a filter server other than crossfilter. - -Any changes should modify the `filters` array argument and return that array. - -```js -// default remove filter handler -function (filters, filter) { - for (var i = 0; i < filters.length; i++) { - if (filters[i] <= filter && filters[i] >= filter) { - filters.splice(i, 1); - break; - } - } - return filters; -} - -// custom filter handler (no-op) -chart.removeFilterHandler(function(filters, filter) { - return filters; -}); -``` - -#### .addFilterHandler([function]) -Set or get the add filter handler. The add filter handler is a function that adds a filter to -the chart's filter list. Using a custom add filter handler allows you to change the way filters -are added or perform additional work when adding a filter, e.g. when using a filter server other -than crossfilter. - -Any changes should modify the `filters` array argument and return that array. - -```js -// default add filter handler -function (filters, filter) { - filters.push(filter); - return filters; -} - -// custom filter handler (no-op) -chart.addFilterHandler(function(filters, filter) { - return filters; -}); -``` - -#### .resetFilterHandler([function]) -Set or get the reset filter handler. The reset filter handler is a function that resets the -chart's filter list by returning a new list. Using a custom reset filter handler allows you to -change the way filters are reset, or perform additional work when resetting the filters, -e.g. when using a filter server other than crossfilter. - -This function should return an array. - -```js -// default remove filter handler -function (filters) { - return []; -} - -// custom filter handler (no-op) -chart.resetFilterHandler(function(filters) { - return filters; -}); -``` - -#### .filter([filterValue]) -Filter the chart by the given value or return the current filter if the input parameter is missing. -```js -// filter by a single string -chart.filter('Sunday'); -// filter by a single age -chart.filter(18); -``` - -#### .filters() -Returns all current filters. This method does not perform defensive cloning of the internal -filter array before returning, therefore any modification of the returned array will effect the -chart's internal filter storage. - -#### .onClick(datum) -This function is passed to d3 as the onClick handler for each chart. The default behavior is to -filter on the clicked datum (passed to the callback) and redraw the chart group. - -#### .filterHandler([function]) -Set or get the filter handler. The filter handler is a function that performs the filter action -on a specific dimension. Using a custom filter handler allows you to perform additional logic -before or after filtering. - -```js -// default filter handler -function(dimension, filter){ - dimension.filter(filter); // perform filtering - return filter; // return the actual filter value -} - -// custom filter handler -chart.filterHandler(function(dimension, filter){ - var newFilter = filter + 10; - dimension.filter(newFilter); - return newFilter; // set the actual filter value to the new value -}); -``` - -#### .keyAccessor([keyAccessorFunction]) -Set or get the key accessor function. The key accessor function is used to retrieve the key -value from the crossfilter group. Key values are used differently in different charts, for -example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart. -```js -// default key accessor -chart.keyAccessor(function(d) { return d.key; }); -// custom key accessor for a multi-value crossfilter reduction -chart.keyAccessor(function(p) { return p.value.absGain; }); -``` - -#### .valueAccessor([valueAccessorFunction]) -Set or get the value accessor function. The value accessor function is used to retrieve the -value from the crossfilter group. Group values are used differently in different charts, for -example values correspond to slice sizes in a pie chart and y axis positions in a grid -coordinate chart. -```js -// default value accessor -chart.valueAccessor(function(d) { return d.value; }); -// custom value accessor for a multi-value crossfilter reduction -chart.valueAccessor(function(p) { return p.value.percentageGain; }); -``` - -#### .label([labelFunction]) -Set or get the label function. The chart class will use this function to render labels for each -child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every -chart supports the label function for example bar chart and line chart do not use this function -at all. -```js -// default label function just return the key -chart.label(function(d) { return d.key; }); -// label function has access to the standard d3 data binding and can get quite complicated -chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; }); -``` - -#### .renderLabel(boolean) -Turn on/off label rendering - -#### .title([titleFunction]) -Set or get the title function. The chart class will use this function to render the svg title -(usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice -in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; -however in grid coordinate charts you need to turn off the brush in order to see titles, because -otherwise the brush layer will block tooltip triggering. -```js -// default title function just return the key -chart.title(function(d) { return d.key + ': ' + d.value; }); -// title function has access to the standard d3 data binding and can get quite complicated -chart.title(function(p) { - return p.key.getFullYear() - + '\n' - + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n' - + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n' - + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%'; -}); -``` - -#### .renderTitle(boolean) -Turn on/off title rendering, or return the state of the render title flag if no arguments are -given. - -#### .renderlet(renderletFunction) -A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added -to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked -right after the chart finishes its transitions, giving you a way to modify the svg -elements. Renderlet functions take the chart instance as the only input parameter and you can -use the dc API or use raw d3 to achieve pretty much any effect. - -@Deprecated - Use [Listeners](#Listeners) with a 'renderlet' prefix -Generates a random key for the renderlet, which makes it hard to remove. -```js -// do this instead of .renderlet(function(chart) { ... }) -chart.on("renderlet", function(chart){ - // mix of dc API and d3 manipulation - chart.select('g.y').style('display', 'none'); - // its a closure so you can also access other chart variable available in the closure scope - moveChart.filter(chart.filter()); -}); -``` - -#### .chartGroup([group]) -Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn -together since it is expected they share the same underlying crossfilter data set. - -#### .expireCache() -Expire the internal chart cache. dc charts cache some data internally on a per chart basis to -speed up rendering and avoid unnecessary calculation; however it might be useful to clear the -cache if you have changed state which will affect rendering. For example if you invoke the -`crossfilter.add` function or reset group or dimension after rendering it is a good idea to -clear the cache to make sure charts are rendered properly. - -#### .legend([dc.legend]) -Attach a dc.legend widget to this chart. The legend widget will automatically draw legend labels -based on the color setting and names associated with each group. - -```js -chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) -``` - -#### .chartID() -Returns the internal numeric ID of the chart. - -#### .options(optionsObject) -Set chart options using a configuration object. Each key in the object will cause the method of -the same name to be called with the value to set that attribute for the chart. - -Example: -``` -chart.options({dimension: myDimension, group: myGroup}); -``` - -## Listeners -All dc chart instance supports the following listeners. - -#### .on('renderlet', function(chart, filter){...}) -This listener function will be invoked after transitions after redraw and render. Replaces the -deprecated `.renderlet()` method. - -#### .on('pretransition', function(chart, filter){...}) -Like `.on('renderlet', ...)` but the event is fired before transitions start. - -#### .on('preRender', function(chart){...}) -This listener function will be invoked before chart rendering. - -#### .on('postRender', function(chart){...}) -This listener function will be invoked after chart finish rendering including all renderlets' logic. - -#### .on('preRedraw', function(chart){...}) -This listener function will be invoked before chart redrawing. - -#### .on('postRedraw', function(chart){...}) -This listener function will be invoked after chart finish redrawing including all renderlets' logic. - -#### .on('filtered', function(chart, filter){...}) -This listener function will be invoked after a filter is applied, added or removed. +**Kind**: instance property of [baseMixin](#dc.baseMixin) -#### .on('zoomed', function(chart, filter){...}) -This listener function will be invoked after a zoom is triggered. +| Param | Type | +| --- | --- | +| [group] | Group | +| [name] | String | -## Margin Mixin -Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid -Charts. - -#### .margins([margins]) -Get or set the margins for a particular coordinate grid chart instance. The margins is stored as -an associative Javascript array. Default margins: {top: 10, right: 50, bottom: 30, left: 30}. - -The margins can be accessed directly from the getter. -```js -var leftMargin = chart.margins().left; // 30 by default -chart.margins().left = 50; -leftMargin = chart.margins().left; // now 50 -``` - -## Color Mixin -The Color Mixin is an abstract chart functional class providing universal coloring support -as a mix-in for any concrete chart implementation. - -#### .colors([colorScale]) -Retrieve current color scale or set a new color scale. This methods accepts any function that -operates like a d3 scale. If not set the default is -`d3.scale.category20c()`. -```js -// alternate categorical scale -chart.colors(d3.scale.category20b()); - -// ordinal scale -chart.colors(d3.scale.ordinal().range(['red','green','blue'])); -// convenience method, the same as above -chart.ordinalColors(['red','green','blue']); - -// set a linear scale -chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); -``` + +### dc.barChart ⇒ barChart | BarChart +Concrete bar chart/histogram implementation. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### .ordinalColors(r) -Convenience method to set the color scale to d3.scale.ordinal with range `r`. +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin +**Returns**: barChart - =======BarChart - >>>>>>> cec52eb469e363b35b6f8c2f36488f9bb1d481fc -#### .linearColors(r) -Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. <<<<<<< HEAD | -#### .colorAccessor([colorAccessorFunction]) -Set or the get color accessor function. This function will be used to map a data point in a -crossfilter group to a color value on the color scale. The default function uses the key -accessor. +**Example** ```js -// default index based color accessor -.colorAccessor(function (d, i){return i;}) -// color accessor for a multi-value crossfilter reduction -.colorAccessor(function (d){return d.value.absGain;}) +// create a bar chart under #chart-container1 element using the default global chart group +var chart1 = dc.barChart('#chart-container1'); +// create a bar chart under #chart-container2 element using chart group A +var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); +// create a sub-chart under a composite parent chart +var chart3 = dc.barChart(compositeChart); ``` -#### .colorDomain([domain]) -Set or get the current domain for the color mapping function. The domain must be supplied as an -array. +* [.barChart](#dc.barChart) ⇒ barChart | BarChart + * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean + * [.barPadding](#dc.barChart+barPadding) ⇒ Number + * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number + * [.gap](#dc.barChart+gap) ⇒ Number + * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean -Note: previously this method accepted a callback function. Instead you may use a custom scale -set by `.colors`. + +#### barChart.centerBar ⇒ Boolean +Whether the bar chart will render each bar centered around the data position on x axis -#### .calculateColorDomain() -Set the domain by determining the min and max values as retrieved by `.colorAccessor` over the -chart's dataset. +**Kind**: instance property of [barChart](#dc.barChart) -#### .getColor(d [, i]) -Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. +| Param | Type | Default | +| --- | --- | --- | +| [centerBar] | Boolean | false | -#### .colorCalculator([value]) -Gets or sets chart.getColor. - -## Coordinate Grid Mixin -Includes: [Color Mixin](#color-mixin), [Margin Mixin](#margin-mixin), [Base Mixin](#base-mixin) + +#### barChart.barPadding ⇒ Number +Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. +Setting this value will also remove any previously set `gap`. See the +[d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) +for a visual description of how the padding is applied. -Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based -concrete chart types, e.g. bar chart, line chart, and bubble chart. +**Kind**: instance property of [barChart](#dc.barChart) -#### .rescale() -When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate -and redraw the axes. (`.rescale()` is called automatically when the x or y scale is replaced -with `.x()` or `.y()`, and has no effect on elastic scales.) +| Param | Type | +| --- | --- | +| [barPadding] | Number | -#### .rangeChart([chart]) -Get or set the range selection chart associated with this instance. Setting the range selection -chart using this function will automatically update its selection brush when the current chart -zooms in. In return the given range chart will also automatically attach this chart as its focus -chart hence zoom in when range brush updates. See the [Nasdaq 100 -Index](http://dc-js.github.com/dc.js/) example for this effect in action. + +#### barChart.outerPadding ⇒ Number +Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. +Will pad the width by `padding * barWidth` on each side of the chart. -#### .zoomScale([extent]) -Get or set the scale extent for mouse zooms. +**Kind**: instance property of [barChart](#dc.barChart) -#### .zoomOutRestrict([true/false]) -Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart. +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Number | 0.5 | -#### .g([gElement]) -Get or set the root g element. This method is usually used to retrieve the g element in order to -overlay custom svg drawing programatically. **Caution**: The root g element is usually generated -by dc.js internals, and resetting it might produce unpredictable result. + +#### barChart.gap ⇒ Number +Manually set fixed gap (in px) between bars instead of relying on the default auto-generated +gap. By default the bar chart implementation will calculate and set the gap automatically +based on the number of data points and the length of the x axis. -#### .mouseZoomable([boolean]) -Set or get mouse zoom capability flag (default: false). When turned on the chart will be -zoomable using the mouse wheel. If the range selector chart is attached zooming will also update -the range selection brush on the associated range selector chart. +**Kind**: instance property of [barChart](#dc.barChart) -#### .chartBodyG() -Retrieve the svg group for the chart body. +| Param | Type | Default | +| --- | --- | --- | +| [gap] | Number | 2 | -#### .x([xScale]) - **mandatory** -Get or set the x scale. The x scale can be any d3 -[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) or -[ordinal scale](https://github.com/mbostock/d3/wiki/Ordinal-Scales). -```js -// set x to a linear scale -chart.x(d3.scale.linear().domain([-2500, 2500])) -// set x to a time scale to generate histogram -chart.x(d3.time.scale().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)])) -``` + +#### barChart.alwaysUseRounding ⇒ Boolean +Set or get whether rounding is enabled when bars are centered. Default: false. If false, using +rounding with centered bars will result in a warning and rounding will be ignored. This flag +has no effect if bars are not centered. +When using standard d3.js rounding methods, the brush often doesn't align correctly with +centered bars since the bars are offset. The rounding function must add an offset to +compensate, such as in the following example. -#### .xUnits([xUnits function]) -Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate -the number of data projections on x axis such as the number of bars for a bar chart or the -number of dots for a line chart. This function is expected to return a Javascript array of all -data points on x axis, or the number of points on the axis. [d3 time range functions -d3.time.days, d3.time.months, and -d3.time.years](https://github.com/mbostock/d3/wiki/Time-Intervals#aliases) are all valid xUnits -function. dc.js also provides a few units function, see the [Utilities](#utilities) section for -a list of built-in units functions. The default xUnits function is dc.units.integers. -```js -// set x units to count days -chart.xUnits(d3.time.days); -// set x units to count months -chart.xUnits(d3.time.months); -``` -A custom xUnits function can be used as long as it follows the following interface: -```js -// units in integer -function(start, end, xDomain) { - // simply calculates how many integers in the domain - return Math.abs(end - start); -}; - -// fixed units -function(start, end, xDomain) { - // be aware using fixed units will disable the focus/zoom ability on the chart - return 1000; -}; -``` +**Kind**: instance property of [barChart](#dc.barChart) -#### .xAxis([xAxis]) -Set or get the x axis used by a particular coordinate grid chart instance. This function is most -useful when x axis customization is required. The x axis in dc.js is an instance of a [d3 -axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis); therefore it supports any -valid d3 axis manipulation. **Caution**: The x axis is usually generated internally by dc; -resetting it may cause unexpected results. -```js -// customize x axis tick format -chart.xAxis().tickFormat(function(v) {return v + '%';}); -// customize x axis tick values -chart.xAxis().tickValues([0, 100, 200, 300]); -``` +| Param | Type | Default | +| --- | --- | --- | +| [alwaysUseRounding] | Boolean | false | -#### .elasticX([boolean]) -Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will -attempt to recalculate the x axis range whenever a redraw event is triggered. - -#### .xAxisPadding([padding]) -Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x -axis if elasticX is turned on; otherwise it is ignored. - -* padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to -number or date x axes. When padding a date axis, an integer represents number of days being padded -and a percentage string will be treated the same as an integer. - -#### .xUnitCount() -Returns the number of units displayed on the x axis using the unit measure configured by -.xUnits. - -#### .useRightYAxis() -Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When -used with a chart in a composite chart, allows both left and right Y axes to be shown on a -chart. - -#### isOrdinal() -Returns true if the chart is using ordinal xUnits ([dc.units.ordinal](#dcunitsordinal)), or false -otherwise. Most charts behave differently with ordinal data and use the result of this method to -trigger the appropriate logic. - -#### .xAxisLabel([labelText, [, padding]]) -Set or get the x axis label. If setting the label, you may optionally include additional padding to -the margin to make room for the label. By default the padded is set to 12 to accomodate the text height. - -#### .yAxisLabel([labelText, [, padding]]) -Set or get the y axis label. If setting the label, you may optionally include additional padding -to the margin to make room for the label. By default the padded is set to 12 to accomodate the -text height. - -#### .y([yScale]) -Get or set the y scale. The y scale is typically automatically determined by the chart implementation. - -#### .yAxis([yAxis]) -Set or get the y axis used by the coordinate grid chart instance. This function is most useful -when y axis customization is required. The y axis in dc.js is simply an instance of a [d3 axis -object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis); therefore it supports any -valid d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; -resetting it may cause unexpected results. +**Example** ```js -// customize y axis tick format -chart.yAxis().tickFormat(function(v) {return v + '%';}); -// customize y axis tick values -chart.yAxis().tickValues([0, 100, 200, 300]); +chart.round(function(n) {return Math.floor(n)+0.5}); ``` + +### dc.filterAll +Clear all filters on all charts within the given chart group. If the chart group is not given then +only charts that belong to the default chart group will be reset. -#### .elasticY([boolean]) -Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will -attempt to recalculate the y axis range whenever a redraw event is triggered. - -#### .renderHorizontalGridLines([boolean]) -Turn on/off horizontal grid lines. +**Kind**: static property of [dc](#dc) -#### .renderVerticalGridLines([boolean]) -Turn on/off vertical grid lines. +| Param | Type | +| --- | --- | +| [group] | String | -#### .xAxisMin() -Calculates the minimum x value to display in the chart. Includes xAxisPadding if set. + +### dc.refocusAll +Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is +not given then only charts that belong to the default chart group will be reset. -#### .xAxisMax() -Calculates the maximum x value to display in the chart. Includes xAxisPadding if set. +**Kind**: static property of [dc](#dc) -#### .yAxisMin() -Calculates the minimum y value to display in the chart. Includes yAxisPadding if set. +| Param | Type | +| --- | --- | +| [group] | String | -#### .yAxisMax() -Calculates the maximum y value to display in the chart. Includes yAxisPadding if set. + +### dc.renderAll +Re-render all charts belong to the given chart group. If the chart group is not given then only +charts that belong to the default chart group will be re-rendered. -#### .yAxisPadding([padding]) -Set or get y axis padding for the elastic y axis. The padding will be added to the top of the y -axis if elasticY is turned on; otherwise it is ignored. +**Kind**: static property of [dc](#dc) -* padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to -number or date axes. When padding a date axis, an integer represents number of days being padded -and a percentage string will be treated the same as an integer. +| Param | Type | +| --- | --- | +| [group] | String | -#### .round([rounding function]) -Set or get the rounding function used to quantize the selection when brushing is enabled. -```js -// set x unit round to by month, this will make sure range selection brush will -// select whole months -chart.round(d3.time.month.round); -``` + +### dc.redrawAll +Redraw all charts belong to the given chart group. If the chart group is not given then only charts +that belong to the default chart group will be re-drawn. Redraw is different from re-render since +when redrawing dc tries to update the graphic incrementally, using transitions, instead of starting +from scratch. -#### .clipPadding([padding]) -Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to -the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area -will be exactly the chart body area minus the margins. Default: 5 +**Kind**: static property of [dc](#dc) -#### .focus([range]) -Zoom this chart to focus on the given range. The given range should be an array containing only -2 elements (`[start, end]`) defining a range in the x domain. If the range is not given or set -to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; -otherwise focus will be ignored._ -```js -chart.on('renderlet', function(chart) { - // smooth the rendering through event throttling - dc.events.trigger(function(){ - // focus some other chart to the range selected by user on this chart - someOtherChart.focus(chart.filter()); - }); -}) -``` +| Param | Type | +| --- | --- | +| [group] | String | -#### .brushOn([boolean]) -Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse -across a chart with a quantitative scale to perform range filtering based on the extent of the -brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and -unfilter them. However turning on the brush filter will disable other interactive elements on -the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible -if enabled, but only via scrolling (panning will be disabled.) Default: true + +### dc.disableTransitions : Boolean +If this boolean is set truthy, all transitions will be disabled, and changes to the charts will happen +immediately + +**Kind**: static property of [dc](#dc) +**Default**: false + +### dc.units : Object +**Kind**: static property of [dc](#dc) + +* [.units](#dc.units) : Object + * [.integers](#dc.units.integers) ⇒ Number + * [.ordinal](#dc.units.ordinal) ⇒ Array.<String> + * [.fp](#dc.units.fp) : Object + * [.precision](#dc.units.fp.precision) ⇒ function + + +#### units.integers ⇒ Number +The default value for `xUnits` for the [Coordinate Grid Chart](#coordinate-grid-chart) and should +be used when the x values are a sequence of integers. +It is a function that counts the number of integers in the range supplied in its start and end parameters. -## Stack Mixin -Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. +**Kind**: static property of [units](#dc.units) -#### .stack(group[, name, accessor]) -Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks -in the same chart will share the same key accessor and therefore the same set of keys. +| Param | Type | +| --- | --- | +| start | Number | +| end | Number | -For example, in a stacked bar chart, the bars of each stack will be positioned using the same set -of keys on the x axis, while stacked vertically. If name is specified then it will be used to -generate the legend label. +**Example** ```js -// stack group using default accessor -chart.stack(valueSumGroup) -// stack group using custom accessor -.stack(avgByDayGroup, function(d){return d.value.avgByDay;}); +chart.xUnits(dc.units.integers) // already the default ``` + +#### units.ordinal ⇒ Array.<String> +This argument can be passed to the `xUnits` function of the to specify ordinal units for the x +axis. Usually this parameter is used in combination with passing `d3.scale.ordinal()` to `.x`. +It just returns the domain passed to it, which for ordinal charts is an array of all values. -#### .hidableStacks([boolean]) -Allow named stacks to be hidden or shown by clicking on legend items. -This does not affect the behavior of hideStack or showStack. - -#### .hideStack(name) -Hide all stacks on the chart with the given name. -The chart must be re-rendered for this change to appear. - -#### .showStack(name) -Show all stacks on the chart with the given name. -The chart must be re-rendered for this change to appear. +**Kind**: static property of [units](#dc.units) -#### .title([stackName], [titleFunction]) -Set or get the title function. Chart class will use this function to render svg title (usually interpreted by -browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. -Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to -use title otherwise the brush layer will block tooltip trigger. +| Param | Type | +| --- | --- | +| start | \* | +| end | \* | +| domain | Array.<String> | -If the first argument is a stack name, the title function will get or set the title for that stack. If stackName -is not provided, the first stack is implied. +**Example** ```js -// set a title function on 'first stack' -chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); -// get a title function from 'second stack' -var secondTitleFunction = chart.title('second stack'); -); +chart.xUnits(dc.units.ordinal) + .x(d3.scale.ordinal()) ``` + +#### units.fp : Object +**Kind**: static property of [units](#dc.units) + +##### fp.precision ⇒ function +This function generates an argument for the [Coordinate Grid Chart's](#coordinate-grid-chart) +`xUnits` function specifying that the x values are floating-point numbers with the given +precision. +The returned function determines how many values at the given precision will fit into the range +supplied in its start and end parameters. -#### .stackLayout([layout]) -Gets or sets the stack layout algorithm, which computes a baseline for each stack and -propagates it to the next. The default is -[d3.layout.stack](https://github.com/mbostock/d3/wiki/Stack-Layout#stack). - -## Cap Mixin -Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the -Row and Pie Charts. - -The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest -will be replaced with an *others* element, with value equal to the sum of the replaced values. The -keys of the elements below the cap limit are recorded in order to filter by those keys when the -*others* element is clicked. - -#### .cap([count]) -Get or set the count of elements to that will be included in the cap. +**Kind**: static property of [fp](#dc.units.fp) +**Returns**: function - start-end unit function -#### .othersLabel([label]) -Get or set the label for *Others* slice when slices cap is specified. Default label is **Others**. +| Param | Type | +| --- | --- | +| precision | Number | -#### .othersGrouper([grouperFunction]) -Get or set the grouper function that will perform the insertion of data for the *Others* slice -if the slices cap is specified. If set to a falsy value, no others will be added. By default the -grouper function computes the sum of all values below the cap. +**Example** ```js -chart.othersGrouper(function (data) { - // compute the value for others, presumably the sum of all values below the cap - var othersSum = yourComputeOthersValueLogic(data) - - // the keys are needed to properly filter when the others element is clicked - var othersKeys = yourComputeOthersKeysArrayLogic(data); - - // add the others row to the dataset - data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); - - return data; -}); +// specify values (and ticks) every 0.1 units +chart.xUnits(dc.units.fp.precision(0.1) +// there are 500 units between 0.5 and 1 if the precision is 0.001 +var thousandths = dc.units.fp.precision(0.001); +thousandths(0.5, 1.0) // returns 500 ``` - -## Bubble Mixin -Includes: [Color Mixin](#color-mixin) - -This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. - -#### .r([bubbleRadiusScale]) -Get or set the bubble radius scale. By default the bubble chart uses -`d3.scale.linear().domain([0, 100])` as its r scale . - -#### .radiusValueAccessor([radiusValueAccessor]) -Get or set the radius value accessor function. If set, the radius value accessor function will -be used to retrieve a data value for each bubble. The data retrieved then will be mapped using -the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble -size. - -#### .minRadiusWithLabel([radius]) -Get or set the minimum radius for label rendering. If a bubble's radius is less than this value -then no label will be rendered. Default: 10 - -#### .maxBubbleRelativeSize([relativeSize]) -Get or set the maximum relative size of a bubble to the length of x axis. This value is useful -when the difference in radius between bubbles is too great. Default: 0.3 - -## Pie Chart -Includes: [Cap Mixin](#cap-mixin), [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -The pie chart implementation is usually used to visualize a small categorical distribution. The pie -chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each -slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting -by key. - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.pieChart(parent[, chartGroup]) -Create a pie chart instance and attaches it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created pie chart instance - -```js -// create a pie chart under #chart-container1 element using the default global chart group -var chart1 = dc.pieChart('#chart-container1'); -// create a pie chart under #chart-container2 element using chart group A -var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); -``` - -#### .slicesCap([cap]) -Get or set the maximum number of slices the pie chart will generate. The top slices are determined by -value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. -The resulting data will still be sorted by .ordering (default by key). - -#### .externalRadiusPadding([externalRadiusPadding]) -Get or set the external radius padding of the pie chart. This will force the radius of the -pie chart to become smaller or larger depending on the value. Default external radius padding is 0px. - -#### .innerRadius([innerRadius]) -Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the -pie chart will be rendered as a doughnut chart. Default inner radius is 0px. - -#### .radius([radius]) -Get or set the outer radius. If the radius is not set, it will be half of the minimum of the -chart width and height. - -#### .cx([cx]) -Get or set center x coordinate position. Default is center of svg. - -#### .cy([cy]) -Get or set center y coordinate position. Default is center of svg. - -#### .minAngleForLabel([minAngle]) -Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not -display a slice label. Default min angle is 0.5. - -## Bar Chart -Includes: [Stack Mixin](#stack Mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Concrete bar chart/histogram implementation. - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.barChart(parent[, chartGroup]) -Create a bar chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection | compositeChart - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite -chart instance. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bar chart instance - -```js -// create a bar chart under #chart-container1 element using the default global chart group -var chart1 = dc.barChart('#chart-container1'); -// create a bar chart under #chart-container2 element using chart group A -var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.barChart(compositeChart); -``` - -#### .centerBar(boolean) -Whether the bar chart will render each bar centered around the data position on x axis. Default: false - -#### .barPadding([padding]) -Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. -Setting this value will also remove any previously set `gap`. See the -[d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) -for a visual description of how the padding is applied. - -#### .outerPadding([padding]) -Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. -Will pad the width by `padding * barWidth` on each side of the chart. - -Default: 0.5 - -#### .gap(gapBetweenBars) -Manually set fixed gap (in px) between bars instead of relying on the default auto-generated -gap. By default the bar chart implementation will calculate and set the gap automatically -based on the number of data points and the length of the x axis. - -#### .alwaysUseRounding([boolean]) -Set or get whether rounding is enabled when bars are centered. Default: false. If false, using -rounding with centered bars will result in a warning and rounding will be ignored. This flag -has no effect if bars are not centered. - -When using standard d3.js rounding methods, the brush often doesn't align correctly with -centered bars since the bars are offset. The rounding function must add an offset to -compensate, such as in the following example. -```js -chart.round(function(n) {return Math.floor(n)+0.5}); -``` - -## Line Chart -Includes [Stack Mixin](#stack-mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Concrete line/area chart implementation. - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.lineChart(parent[, chartGroup]) -Create a line chart instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection | compositeChart - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -If the line chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite -chart instance. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created line chart instance - -```js -// create a line chart under #chart-container1 element using the default global chart group -var chart1 = dc.lineChart('#chart-container1'); -// create a line chart under #chart-container2 element using chart group A -var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.lineChart(compositeChart); -``` - -#### .interpolate([value]) -Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step -functions, splines, and cubic interpolation. This is passed to -[d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and -[d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), -where you can find a complete list of valid arguments - -#### .tension([value]) -Gets or sets the tension to use for lines drawn, in the range 0 to 1. -This parameter further customizes the interpolation behavior. It is passed to -[d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and -[d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). Default: -0.7 - -#### .defined([value]) -Gets or sets a function that will determine discontinuities in the line which should be -skipped: the path will be broken into separate subpaths if some points are undefined. -This function is passed to -[d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) - -Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write -custom reduce functions to get this to work, depending on your data. See -https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 - -#### .dashStyle([array]) -Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty -array (solid line). - ```js - // create a Dash Dot Dot Dot - chart.dashStyle([3,1,1,1]); - ``` - -#### .renderArea([boolean]) -Get or set render area flag. If the flag is set to true then the chart will render the area -beneath each line and the line chart effectively becomes an area chart. - -#### .dotRadius([dotRadius]) -Get or set the radius (in px) for dots displayed on the data points. Default dot radius is 5. - -#### .renderDataPoints([options]) -Always show individual dots for each datapoint. - -Options, if given, is an object that can contain the following: - -* fillOpacity (default 0.8) -* strokeOpacity (default 0.8) -* radius (default 2) - -If `options` is falsy, it disables data point rendering. - -If no `options` are provided, the current `options` values are instead returned. - -Example: -``` -chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) -``` - -## Data Count Widget -Includes: [Base Mixin](#base-mixin) - -The data count widget is a simple widget designed to display the number of records selected by the -current filters out of the total number of records in the data set. Once created the data count widget -will automatically update the text content of the following elements under the parent element. - -* '.total-count' - total number of records -* '.filter-count' - number of records matched by the current filters - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.dataCount(parent[, chartGroup]) -Create a data count widget and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this widget should be placed in. -The data count widget will only react to filter changes in the chart group. - -Returns: -A newly created data count widget instance -#### .dimension(allData) - **mandatory** -For the data count widget the only valid dimension is the entire data set. -#### .group(groupAll) - **mandatory** -For the data count widget the only valid group is the group returned by `dimension.groupAll()`. - -```js -var ndx = crossfilter(data); -var all = ndx.groupAll(); - -dc.dataCount('.dc-data-count') - .dimension(ndx) - .group(all); -``` - -#### html([object]) -Gets or sets an optional object specifying HTML templates to use depending how many items are -selected. The text `%total-count` will replaced with the total number of records, and the text -`%filter-count` will be replaced with the number of selected records. -- all: HTML template to use if all items are selected -- some: HTML template to use if not all items are selected - -```js -counter.html({ - some: '%filter-count out of %total-count records selected', - all: 'All records selected. Click on charts to apply filters' -}) -``` - -#### formatNumber([formatter]) -Gets or sets an optional function to format the filter count and total count. - -```js -counter.formatNumber(d3.format('.2g')) -``` - -## Data Table Widget -Includes: [Base Mixin](#base-mixin) - -The data table is a simple widget designed to list crossfilter focused data set (rows being -filtered) in a good old tabular fashion. - -Note: Unlike other charts, the data table (and data grid chart) use the group attribute as a keying function -for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. -Do not pass in a crossfilter group as this will not work. - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.dataTable(parent[, chartGroup]) -Create a data table widget instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created data table widget instance - -#### .size([size]) -Get or set the table size which determines the number of rows displayed by the widget. - -#### .columns([columnFunctionArray]) -Get or set column functions. The data table widget now supports several methods of specifying -the columns to display. The original method, first shown below, uses an array of functions to -generate dynamic columns. Column functions are simple javascript functions with only one input -argument `d` which represents a row in the data set. The return value of these functions will be -used directly to generate table content for each cell. However, this method requires the .html -table entry to have a fixed set of column headers. - -```js - chart.columns([ - function(d) { - return d.date; - }, - function(d) { - return d.open; - }, - function(d) { - return d.close; - }, - function(d) { - return numberFormat(d.close - d.open); - }, - function(d) { - return d.volume; - } - ]); -``` - -The next example shows you can simply list the data (d) content directly without -specifying it as a function, except where necessary (ie, computed columns). Note -the data element accessor name is capitalized when displayed in the table. You can -also mix in functions as desired or necessary, but you must use the - Object = [Label, Fn] method as shown below. -You may wish to override the following two functions, which are internally used to -translate the column information or function into a displayed header. The first one -is used on the simple "string" column specifier, the second is used to transform the -String(fn) into something displayable. For the Stock example, the function for Change -becomes a header of 'd.close - d.open'. - _chart._doColumnHeaderCapitalize _chart._doColumnHeaderFnToString -You may use your own Object definition, however you must then override - _chart._doColumnHeaderFormat , _chart._doColumnValueFormat -Be aware that fields without numberFormat specification will be displayed just as -they are stored in the data, unformatted. -```js - chart.columns([ - "date", // d["date"], ie, a field accessor; capitalized automatically - "open", // ... - "close", // ... - ["Change", // Specify an Object = [Label, Fn] - function (d) { - return numberFormat(d.close - d.open); - }], - "volume" // d["volume"], ie, a field accessor; capitalized automatically - ]); -``` - -A third example, where all fields are specified using the Object = [Label, Fn] method. - -```js - chart.columns([ - ["Date", // Specify an Object = [Label, Fn] - function (d) { - return d.date; - }], - ["Open", - function (d) { - return numberFormat(d.open); - }], - ["Close", - function (d) { - return numberFormat(d.close); - }], - ["Change", - function (d) { - return numberFormat(d.close - d.open); - }], - ["Volume", - function (d) { - return d.volume; - }] - ]); -``` - -#### .sortBy([sortByFunction]) -Get or set sort-by function. This function works as a value accessor at row level and returns a -particular field to be sorted by. Default value: identity function - -```js - chart.sortBy(function(d) { - return d.date; - }); -``` - -#### .order([order]) -Get or set sort order. Default value: ``` d3.ascending ``` - -```js - chart.order(d3.descending); -``` - -### .showGroups(true|false) -Get or set if group rows will be shown. Default value ``` true ``` -The .group() getter-setter must be provided in either case. - -```js - chart - .group([value], [name]) - .showGroups(true|false); -``` - -## Data Grid Widget - -Includes: [Base Mixin](#base-mixin) - -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 group attribute as a keying function -for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. -Do not pass in a crossfilter group as this will not work. - -Examples: -* [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) - -#### dc.dataGrid(parent[, chartGroup]) -Create a data grid widget instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created data grid widget instance - -#### .beginSlice([index]) -Get or set the index of the beginning slice which determines which entries get displayed by the widget -Useful when implementing pagination. - -#### .endSlice([index]) -Get or set the index of the end slice which determines which entries get displayed by the widget -Useful when implementing pagination. - -#### .size([size]) -Get or set the grid size which determines the number of items displayed by the widget. - -#### .html( function (data) { return ''; }) -Get or set the function that formats an item. The data grid widget uses a -function to generate dynamic html. Use your favourite templating engine or -generate the string directly. -```js -chart.html(function (d) { return '
'+data.exampleString+'
';}); -``` - -#### .htmlGroup( function (data) { return ''; }) -Get or set the function that formats a group label. -```js -chart.htmlGroup (function (d) { return '

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

'}); -``` - -#### .sortBy([sortByFunction]) -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. -by. Default: identity function - -```js -chart.sortBy(function(d) { - return d.date; -}); -``` - -#### .order([order]) -Get or set sort order function. Default value: ``` d3.ascending ``` - -```js -chart.order(d3.descending); -``` - -## Bubble Chart -Includes: [Bubble Mixin](#bubble-mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -A concrete implementation of a general purpose bubble chart that allows data visualization using the -following dimensions: - -* x axis position -* y axis position -* bubble radius -* color - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) -#### dc.bubbleChart(parent[, chartGroup]) -Create a bubble chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection | compositeChart - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bubble chart instance - -```js -// create a bubble chart under #chart-container1 element using the default global chart group -var bubbleChart1 = dc.bubbleChart('#chart-container1'); -// create a bubble chart under #chart-container2 element using chart group A -var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); -``` - -#### .elasticRadius([boolean]) -Turn on or off the elastic bubble radius feature, or return the value of the flag. If this -feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. - -## Composite Chart -Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Composite charts are a special kind of chart that render multiple charts on the same Coordinate -Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to -achieve some quite flexible charting effects. -#### dc.compositeChart(parent[, chartGroup]) -Create a composite chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created composite chart instance - -```js -// create a composite chart under #chart-container1 element using the default global chart group -var compositeChart1 = dc.compositeChart('#chart-container1'); -// create a composite chart under #chart-container2 element using chart group A -var compositeChart2 = dc.compositeChart('#chart-container2', 'chartGroupA'); -``` - -#### .useRightAxisGridLines(bool) -Get or set whether to draw gridlines from the right y axis. Drawing from the left y axis is the -default behavior. This option is only respected when subcharts with both left and right y-axes -are present. - -#### .childOptions({object}) -Get or set chart-specific options for all child charts. This is equivalent to calling `.options` -on each child chart. - -#### .rightYAxisLabel([labelText]) -Set or get the right y axis label. - -#### .compose(subChartArray) -Combine the given charts into one single composite coordinate grid chart. - -```js -// compose the given charts in the array into one single composite chart -moveChart.compose([ - // when creating sub-chart you need to pass in the parent chart - dc.lineChart(moveChart) - .group(indexAvgByMonthGroup) // if group is missing then parent's group will be used - .valueAccessor(function (d){return d.value.avg;}) - // most of the normal functions will continue to work in a composed chart - .renderArea(true) - .stack(monthlyMoveGroup, function (d){return d.value;}) - .title(function (d){ - var value = d.value.avg?d.value.avg:d.value; - if(isNaN(value)) value = 0; - return dateFormat(d.key) + '\n' + numberFormat(value); - }), - dc.barChart(moveChart) - .group(volumeByMonthGroup) - .centerBar(true) -]); -``` - -#### .children() -Returns the child charts which are composed into the composite chart. - -#### .shareColors([boolean]) -Get or set color sharing for the chart. If set, the `.colors()` value from this chart -will be shared with composed children. Additionally if the child chart implements -Stackable and has not set a custom .colorAccessor, then it will generate a color -specific to its order in the composition. - -#### .shareTitle([[boolean]) -Get or set title sharing for the chart. If set, the `.title()` value from this chart will be -shared with composed children. Default value is true. - -#### .rightY([yScale]) -Get or set the y scale for the right axis. The right y scale is typically automatically -generated by the chart implementation. - -#### .rightYAxis([yAxis]) -Set or get the right y axis used by the composite chart. This function is most useful when y -axis customization is required. The y axis in dc.js is an instance of a [d3 axis -object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis) therefore it supports any valid -d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; -resetting it may cause unexpected results. -```jså -// customize y axis tick format -chart.rightYAxis().tickFormat(function (v) {return v + '%';}); -// customize y axis tick values -chart.rightYAxis().tickValues([0, 100, 200, 300]); -``` - -## Series Chart - -Includes: [Composite Chart](#composite chart) - -A series chart is a chart that shows multiple series of data overlaid on one chart, where the -series is specified in the data. It is a specialization of Composite Chart and inherits all -composite features other than recomposing the chart. - -#### dc.seriesChart(parent[, chartGroup]) -Create a series chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created series chart instance - -```js -// create a series chart under #chart-container1 element using the default global chart group -var seriesChart1 = dc.seriesChart("#chart-container1"); -// create a series chart under #chart-container2 element using chart group A -var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); -``` - -#### .chart([function]) -Get or set the chart function, which generates the child charts. Default: dc.lineChart - -``` -// put interpolation on the line charts used for the series -chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) -// do a scatter series chart -chart.chart(dc.scatterPlot) -``` - -#### .seriesAccessor([accessor]) -Get or set accessor function for the displayed series. Given a datum, this function -should return the series that datum belongs to. - -#### .seriesSort([sortFunction]) -Get or set a function to sort the list of series by, given series values. - -Example: -``` -chart.seriesSort(d3.descending); -``` - -#### .valueSort([sortFunction]) -Get or set a function to sort each series values by. By default this is the key accessor which, -for example, will ensure a lineChart series connects its points in increasing key/x order, -rather than haphazardly. - -## Geo Choropleth Chart -Includes: [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map -from GeoJson data. This chart implementation was inspired by [the great d3 choropleth -example](http://bl.ocks.org/4060606). - -Examples: -* [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) -#### dc.geoChoroplethChart(parent[, chartGroup]) -Create a choropleth chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created choropleth chart instance - -```js -// create a choropleth chart under '#us-chart' element using the default global chart group -var chart1 = dc.geoChoroplethChart('#us-chart'); -// create a choropleth chart under '#us-chart2' element using chart group A -var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); -``` - -#### .overlayGeoJson(json, name, keyAccessor) - **mandatory** -Use this function to insert a new GeoJson map layer. This function can be invoked multiple times -if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple -layers with the same name the new overlay will override the existing one. - -Parameters: -* json - GeoJson feed -* name - name of the layer -* keyAccessor - accessor function used to extract 'key' from the GeoJson data. The key extracted by -this function should match the keys returned by the crossfilter groups. - -```js -// insert a layer for rendering US states -chart.overlayGeoJson(statesJson.features, 'state', function(d) { - return d.properties.name; -}); -``` - -#### .projection(projection) -Set custom geo projection function. See the available [d3 geo projection -functions](https://github.com/mbostock/d3/wiki/Geo-Projections). Default value: albersUsa. - -#### .geoJsons() -Returns all GeoJson layers currently registered with this chart. The returned array is a -reference to this chart's internal data structure, so any modification to this array will also -modify this chart's internal registration. - -Returns an array of objects containing fields {name, data, accessor} - -#### .geoPath() -Returns the [d3.geo.path](https://github.com/mbostock/d3/wiki/Geo-Paths#path) object used to -render the projection and features. Can be useful for figuring out the bounding box of the -feature set and thus a way to calculate scale and translation for the projection. - -#### .removeGeoJson(name) -Remove a GeoJson layer from this chart by name - -## Bubble Overlay Chart -Includes: [Bubble Mixin](#bubble-mixin), [Base Mixin](#base-mixin) - -The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay -chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the -typical x and y positioning while retaining the capability to visualize data using bubble radius -and coloring. - -Examples: -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.bubbleOverlay(parent[, chartGroup]) -Create a bubble overlay chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -off-screen. Typically this element should also be the parent of the underlying image. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bubble overlay chart instance - -```js -// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group -var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); -// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A -var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); -``` -#### .svg(imageElement) - **mandatory** -Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg -element; therefore the bubble overlay chart will not work if this function is not invoked. If the -underlying image is a bitmap, then an empty svg will need to be created on top of the image. - -```js -// set up underlying svg element -chart.svg(d3.select('#chart svg')); -``` - -#### .point(name, x, y) - **mandatory** -Set up a data point on the overlay. The name of a data point should match a specific 'key' among -data groups generated using keyAccessor. If a match is found (point name <-> data group key) -then a bubble will be generated at the position specified by the function. x and y -value specified here are relative to the underlying svg. - -## Row Chart -Includes: [Cap Mixin](#cap-mixin), [Margin Mixin](#margin-mixin), [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -Concrete row chart implementation. -#### dc.rowChart(parent[, chartGroup]) -Create a row chart instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created row chart instance - -```js -// create a row chart under #chart-container1 element using the default global chart group -var chart1 = dc.rowChart('#chart-container1'); -// create a row chart under #chart-container2 element using chart group A -var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); -``` - -#### .x([scale]) -Gets or sets the x scale. The x scale can be any d3 -[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) - -#### .renderTitleLabel(boolean) -Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' - -#### .xAxis() -Get the x axis for the row chart instance. Note: not settable for row charts. -See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. -```js -// customize x axis tick format -chart.xAxis().tickFormat(function (v) {return v + '%';}); -// customize x axis tick values -chart.xAxis().tickValues([0, 100, 200, 300]); -``` - -#### .fixedBarHeight([height]) -Get or set the fixed bar height. Default is [false] which will auto-scale bars. -For example, if you want to fix the height for a specific number of bars (useful in TopN charts) -you could fix height as follows (where count = total number of bars in your TopN and gap is -your vertical gap space). -```js - chart.fixedBarHeight( chartheight - (count + 1) * gap / count); -``` - -#### .gap([gap]) -Get or set the vertical gap space between rows on a particular row chart instance. Default gap is 5px; - -#### .elasticX([boolean]) -Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the -data range when filtered. - -#### .labelOffsetX([x]) -Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. -Default x offset is 10px; - -#### .labelOffsetY([y]) -Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. -Default y offset is 15px; - -#### .titleLabelOffsetx([x]) -Get of set the x offset (horizontal space between right edge of row and right edge or text. -Default x offset is 2px; - -## Legend -Legend is a attachable widget that can be added to other dc charts to render horizontal legend -labels. - -```js -chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) -``` - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) - -#### .x([value]) -Set or get x coordinate for legend widget. Default: 0. - -#### .y([value]) -Set or get y coordinate for legend widget. Default: 0. - -#### .gap([value]) -Set or get gap between legend items. Default: 5. - -#### .itemHeight([value]) -Set or get legend item height. Default: 12. - -#### .horizontal([boolean]) -Position legend horizontally instead of vertically - -#### .legendWidth([value]) -Maximum width for horizontal legend. Default: 560. - -#### .itemWidth([value]) -legendItem width for horizontal legend. Default: 70. - -#### .autoItemWidth([value]) -Turn automatic width for legend items on or off. If true, itemWidth() is ignored. -This setting takes into account gap(). Default: false. - -## Scatter Plot -Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - -A scatter plot chart -#### dc.scatterPlot(parent[, chartGroup]) -Create a scatter plot instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection | compositeChart - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -If the scatter plot is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite -chart instance. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created scatter plot instance - -```js -// create a scatter plot under #chart-container1 element using the default global chart group -var chart1 = dc.scatterPlot('#chart-container1'); -// create a scatter plot under #chart-container2 element using chart group A -var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.scatterPlot(compositeChart); -``` - -#### .existenceAccessor([accessor]) -Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and -opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, -the existence accessor checks if the reduced value is truthy. - -#### .symbol([type]) -Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 -[docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. -Type can be a constant or an accessor. - -#### .symbolSize([radius]) -Set or get radius for symbols. Default: 3. - -#### .highlightedSize([radius]) -Set or get radius for highlighted symbols. Default: 4. - -#### .hiddenSize([radius]) -Set or get radius for symbols when the group is empty. Default: 0. - -## Number Display Widget -Includes: [Base Mixin](#base-mixin) - -A display of a single numeric value. - -Examples: - -* [Test Example](http://dc-js.github.io/dc.js/examples/number.html) -#### dc.numberDisplay(parent[, chartGroup]) -Create a Number Display instance and attach it to the given parent element. - -Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and -a valueAccessor that returns a single value. - -Parameters: - -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -The number display widget will only react to filter changes in the chart group. - -Returns: -A newly created number display instance - -```js -// create a number display under #chart-container1 element using the default global chart group -var display1 = dc.numberDisplay('#chart-container1'); -``` - -#### .html([object]) - Gets or sets an optional object specifying HTML templates to use depending on the number - displayed. The text `%number` will be replaced with the current value. - - one: HTML template to use if the number is 1 - - zero: HTML template to use if the number is 0 - - some: HTML template to use otherwise - - ```js - numberWidget.html({ - one:'%number record', - some:'%number records', - none:'no records'}) - ``` - -#### .value() -Calculate and return the underlying value of the display - -#### .formatNumber([formatter]) -Get or set a function to format the value for the display. By default `d3.format('.2s');` is used. - -## Heat Map - -Includes: [Color Mixin](#color-mixin), [Margin Mixin](#margin-mixin), [Base Mixin](#base-mixin) - -A heat map is matrix that represents the values of two dimensions of data using colors. - -#### dc.heatMap(parent[, chartGroup]) -Create a heat map instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying -a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created heat map instance - -```js -// create a heat map under #chart-container1 element using the default global chart group -var heatMap1 = dc.heatMap('#chart-container1'); -// create a heat map under #chart-container2 element using chart group A -var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); -``` - -#### .colsLabel([labelFunction]) -Set or get the column label function. The chart class uses this function to render -column labels on the X axis. It is passed the column name. -```js -// the default label function just returns the name -chart.colsLabel(function(d) { return d; }); -``` - -#### .rowsLabel([labelFunction]) -Set or get the row label function. The chart class uses this function to render -row labels on the Y axis. It is passed the row name. -```js -// the default label function just returns the name -chart.rowsLabel(function(d) { return d; }); -``` - -#### .rows([values]) -Gets or sets the values used to create the rows of the heatmap, as an array. By default, all -the values will be fetched from the data using the value accessor, and they will be sorted in -ascending order. - -#### .cols([keys]) -Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all -the values will be fetched from the data using the key accessor, and they will be sorted in -ascending order. - -#### .boxOnClick([handler]) -Gets or sets the handler that fires when an individual cell is clicked in the heatmap. -By default, filtering of the cell will be toggled. - -#### .xAxisOnClick([handler]) -Gets or sets the handler that fires when a column tick is clicked in the x axis. -By default, if any cells in the column are unselected, the whole column will be selected, -otherwise the whole column will be unselected. - -#### .yAxisOnClick([handler]) -Gets or sets the handler that fires when a row tick is clicked in the y axis. -By default, if any cells in the row are unselected, the whole row will be selected, -otherwise the whole row will be unselected. - -## Box Plot - -Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - -A box plot is a chart that depicts numerical data via their quartile ranges. - -#### dc.boxPlot(parent[, chartGroup]) -Create a box plot instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid -[d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) representing -a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. -Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created box plot instance - -```js -// create a box plot under #chart-container1 element using the default global chart group -var boxPlot1 = dc.boxPlot('#chart-container1'); -// create a box plot under #chart-container2 element using chart group A -var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); -``` - -#### .boxPadding([padding]) -Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. -See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) -for a visual description of how the padding is applied. - -Default: 0.8 - -#### .outerPadding([padding]) -Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts -or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. - -Default: 0.5 - -#### .boxWidth(width || function(innerChartWidth, xUnits) { ... }) -Get or set the numerical width of the boxplot box. The width may also be a function taking as -parameters the chart width excluding the right and left margins, as well as the number of x -units. - -#### .tickFormat() -Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to -integer formatting. -```js -// format ticks to 2 decimal places -chart.tickFormat(d3.format('.2f')); -``` \ No newline at end of file From bdea27389ba66643c2df243152962eea31d973bf Mon Sep 17 00:00:00 2001 From: Matthew Traynham Date: Mon, 10 Aug 2015 22:43:12 -0400 Subject: [PATCH 3/8] Fix small issue with bar chart docs --- src/bar-chart.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/bar-chart.js b/src/bar-chart.js index 3e1009c83..8c416e213 100644 --- a/src/bar-chart.js +++ b/src/bar-chart.js @@ -19,11 +19,7 @@ * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. * Interaction with a chart will only trigger events and redraws within the chart's group. - <<<<<<< HEAD - * @returns {barChart} - ======= * @returns {BarChart} - >>>>>>> cec52eb469e363b35b6f8c2f36488f9bb1d481fc */ dc.barChart = function (parent, chartGroup) { var MIN_BAR_WIDTH = 1; From 009af9db98ef91381a1e0d69b3d24c8b9e105409 Mon Sep 17 00:00:00 2001 From: Matthew Traynham Date: Tue, 11 Aug 2015 00:44:28 -0400 Subject: [PATCH 4/8] Added box-plot, bubble variations, cap & color mixins to docs --- Gruntfile.js | 3 +- src/box-plot.js | 123 ++++++----- src/bubble-chart.js | 73 +++---- src/bubble-mixin.js | 86 +++++--- src/bubble-overlay.js | 99 +++++---- src/cap-mixin.js | 96 ++++---- src/color-mixin.js | 154 +++++++------ web/docs/api-latest.md | 486 ++++++++++++++++++++++++++++++++++++++++- 8 files changed, 831 insertions(+), 289 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 02a6d2ad3..285a16abf 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -185,7 +185,8 @@ module.exports = function (grunt) { }, jsdoc2md: { dist: { - src: ['src/{core,base-mixin,bar-chart}.js'], + src: ['src/{bar-chart,base-mixin,box-plot,bubble-chart,bubble-mixin,' + + 'bubble-overlay,cap-mixin,color-mixin,core}.js'], dest: 'web/docs/api-latest.md' } }, diff --git a/src/box-plot.js b/src/box-plot.js index d4ef5ccea..d7735796a 100644 --- a/src/box-plot.js +++ b/src/box-plot.js @@ -1,31 +1,24 @@ /** - ## Box Plot - - Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - - A box plot is a chart that depicts numerical data via their quartile ranges. - - #### dc.boxPlot(parent[, chartGroup]) - Create a box plot instance and attach it to the given parent element. - - Parameters: - * parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) representing - a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - - Returns: - A newly created box plot instance - - ```js - // create a box plot under #chart-container1 element using the default global chart group - var boxPlot1 = dc.boxPlot('#chart-container1'); - // create a box plot under #chart-container2 element using chart group A - var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); - ``` - - **/ + * A box plot is a chart that depicts numerical data via their quartile ranges. + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + * @name boxPlot + * @memberOf dc + * @mixes coordinateGridMixin + * @example + * // create a box plot under #chart-container1 element using the default global chart group + * var boxPlot1 = dc.boxPlot('#chart-container1'); + * // create a box plot under #chart-container2 element using chart group A + * var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {BoxPlot} + */ dc.boxPlot = function (parent, chartGroup) { var _chart = dc.coordinateGridMixin({}); @@ -83,37 +76,50 @@ dc.boxPlot = function (parent, chartGroup) { }); /** - #### .boxPadding([padding]) - Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. - See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) - for a visual description of how the padding is applied. - - Default: 0.8 - **/ + * Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. + * See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) + * for a visual description of how the padding is applied. + * @name boxPadding + * @memberOf dc.boxPlot + * @instance + * @param {Number} [padding=0.8] + * @returns {Number} + */ _chart.boxPadding = _chart._rangeBandPadding; _chart.boxPadding(0.8); /** - #### .outerPadding([padding]) - Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts - or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. - - Default: 0.5 - **/ + * Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts + * or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. + * @name outerPadding + * @memberOf dc.boxPlot + * @instance + * @param {Number} [padding=0.5] + * @returns {Number} + */ _chart.outerPadding = _chart._outerRangeBandPadding; _chart.outerPadding(0.5); /** - #### .boxWidth(width || function(innerChartWidth, xUnits) { ... }) - Get or set the numerical width of the boxplot box. The width may also be a function taking as - parameters the chart width excluding the right and left margins, as well as the number of x - units. - **/ - _chart.boxWidth = function (_) { + * Get or set the numerical width of the boxplot box. The width may also be a function taking as + * parameters the chart width excluding the right and left margins, as well as the number of x + * units. + * @example + * // Using numerical parameter + * chart.boxWidth(10); + * // Using function + * chart.boxWidth((innerChartWidth, xUnits) { ... }); + * @name boxWidth + * @memberOf dc.boxPlot + * @instance + * @param {Number|Function} [boxWidth=0.5] + * @returns {Number|Function} + */ + _chart.boxWidth = function (boxWidth) { if (!arguments.length) { return _boxWidth; } - _boxWidth = d3.functor(_); + _boxWidth = d3.functor(boxWidth); return _chart; }; @@ -209,19 +215,22 @@ dc.boxPlot = function (parent, chartGroup) { }; /** - #### .tickFormat() - Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to - integer formatting. - ```js - // format ticks to 2 decimal places - chart.tickFormat(d3.format('.2f')); - ``` - **/ - _chart.tickFormat = function (x) { + * Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to + * integer formatting. + * @example + * // format ticks to 2 decimal places + * chart.tickFormat(d3.format('.2f')); + * @name tickFormat + * @memberOf dc.boxPlot + * @instance + * @param {Function} [tickFormat] + * @returns {Number|Function} + */ + _chart.tickFormat = function (tickFormat) { if (!arguments.length) { return _tickFormat; } - _tickFormat = x; + _tickFormat = tickFormat; return _chart; }; diff --git a/src/bubble-chart.js b/src/bubble-chart.js index 1d64adf5f..1091aaf74 100644 --- a/src/bubble-chart.js +++ b/src/bubble-chart.js @@ -1,39 +1,29 @@ /** -## Bubble Chart -Includes: [Bubble Mixin](#bubble-mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -A concrete implementation of a general purpose bubble chart that allows data visualization using the -following dimensions: - -* x axis position -* y axis position -* bubble radius -* color - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) -#### dc.bubbleChart(parent[, chartGroup]) -Create a bubble chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection | compositeChart - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bubble chart instance - -```js -// create a bubble chart under #chart-container1 element using the default global chart group -var bubbleChart1 = dc.bubbleChart('#chart-container1'); -// create a bubble chart under #chart-container2 element using chart group A -var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); -``` - -**/ + * A concrete implementation of a general purpose bubble chart that allows data visualization using the + * following dimensions: + * - x axis position + * - y axis position + * - bubble radius + * - color + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + * @name bubbleChart + * @memberOf dc + * @mixes bubbleMixin,coordinateGridMixin + * @example + * // create a bubble chart under #chart-container1 element using the default global chart group + * var bubbleChart1 = dc.bubbleChart('#chart-container1'); + * // create a bubble chart under #chart-container2 element using chart group A + * var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {BubbleChart} + */ dc.bubbleChart = function (parent, chartGroup) { var _chart = dc.bubbleMixin(dc.coordinateGridMixin({})); @@ -46,11 +36,14 @@ dc.bubbleChart = function (parent, chartGroup) { }; /** - #### .elasticRadius([boolean]) - Turn on or off the elastic bubble radius feature, or return the value of the flag. If this - feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. - - **/ + * Turn on or off the elastic bubble radius feature, or return the value of the flag. If this + * feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. + * @name elasticRadius + * @memberOf dc.bubbleChart + * @instance + * @param {Boolean} [padding=false] + * @returns {Boolean} + */ _chart.elasticRadius = function (_) { if (!arguments.length) { return _elasticRadius; diff --git a/src/bubble-mixin.js b/src/bubble-mixin.js index c087e502f..c5cd7b570 100644 --- a/src/bubble-mixin.js +++ b/src/bubble-mixin.js @@ -1,10 +1,12 @@ /** -## Bubble Mixin -Includes: [Color Mixin](#color-mixin) - -This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. - -**/ + * This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. + * @name bubbleMixin + * @memberOf dc + * @mixin + * @mixes colorMixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.bubbleMixin = function (_chart) { var _maxBubbleRelativeSize = 0.3; var _minRadiusWithLabel = 10; @@ -28,32 +30,38 @@ dc.bubbleMixin = function (_chart) { }; /** - #### .r([bubbleRadiusScale]) - Get or set the bubble radius scale. By default the bubble chart uses - `d3.scale.linear().domain([0, 100])` as its r scale . - - **/ - _chart.r = function (_) { + * Get or set the bubble radius scale. By default the bubble chart uses + * `d3.scale.linear().domain([0, 100])` as its r scale . + * @name r + * @memberOf dc.bubbleMixin + * @instance + * @param {Number[]} [bubbleRadiusScale] + * @returns {Number[]} + */ + _chart.r = function (bubbleRadiusScale) { if (!arguments.length) { return _r; } - _r = _; + _r = bubbleRadiusScale; return _chart; }; /** - #### .radiusValueAccessor([radiusValueAccessor]) - Get or set the radius value accessor function. If set, the radius value accessor function will - be used to retrieve a data value for each bubble. The data retrieved then will be mapped using - the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble - size. - - **/ - _chart.radiusValueAccessor = function (_) { + * Get or set the radius value accessor function. If set, the radius value accessor function will + * be used to retrieve a data value for each bubble. The data retrieved then will be mapped using + * the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble + * size. + * @name radiusValueAccessor + * @memberOf dc.bubbleMixin + * @instance + * @param {Function} [radiusValueAccessor] + * @returns {Function} + */ + _chart.radiusValueAccessor = function (radiusValueAccessor) { if (!arguments.length) { return _rValueAccessor; } - _rValueAccessor = _; + _rValueAccessor = radiusValueAccessor; return _chart; }; @@ -137,30 +145,36 @@ dc.bubbleMixin = function (_chart) { }; /** - #### .minRadiusWithLabel([radius]) - Get or set the minimum radius for label rendering. If a bubble's radius is less than this value - then no label will be rendered. Default: 10 - - **/ - _chart.minRadiusWithLabel = function (_) { + * Get or set the minimum radius for label rendering. If a bubble's radius is less than this value + * then no label will be rendered. + * @name minRadiusWithLabel + * @memberOf dc.bubbleMixin + * @instance + * @param {Number} [radius=10] + * @returns {Number} + */ + _chart.minRadiusWithLabel = function (radius) { if (!arguments.length) { return _minRadiusWithLabel; } - _minRadiusWithLabel = _; + _minRadiusWithLabel = radius; return _chart; }; /** - #### .maxBubbleRelativeSize([relativeSize]) - Get or set the maximum relative size of a bubble to the length of x axis. This value is useful - when the difference in radius between bubbles is too great. Default: 0.3 - - **/ - _chart.maxBubbleRelativeSize = function (_) { + * Get or set the maximum relative size of a bubble to the length of x axis. This value is useful + * when the difference in radius between bubbles is too great. + * @name maxBubbleRelativeSize + * @memberOf dc.bubbleMixin + * @instance + * @param {Number} [relativeSize=0.3] + * @returns {Number} + */ + _chart.maxBubbleRelativeSize = function (relativeSize) { if (!arguments.length) { return _maxBubbleRelativeSize; } - _maxBubbleRelativeSize = _; + _maxBubbleRelativeSize = relativeSize; return _chart; }; diff --git a/src/bubble-overlay.js b/src/bubble-overlay.js index 3bc801775..176455135 100644 --- a/src/bubble-overlay.js +++ b/src/bubble-overlay.js @@ -1,50 +1,46 @@ /** -## Bubble Overlay Chart -Includes: [Bubble Mixin](#bubble-mixin), [Base Mixin](#base-mixin) - -The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay -chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the -typical x and y positioning while retaining the capability to visualize data using bubble radius -and coloring. - -Examples: -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.bubbleOverlay(parent[, chartGroup]) -Create a bubble overlay chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - off-screen. Typically this element should also be the parent of the underlying image. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created bubble overlay chart instance - -```js -// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group -var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); -// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A -var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); -``` -#### .svg(imageElement) - **mandatory** -Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg -element; therefore the bubble overlay chart will not work if this function is not invoked. If the -underlying image is a bitmap, then an empty svg will need to be created on top of the image. - -```js -// set up underlying svg element -chart.svg(d3.select('#chart svg')); -``` - -**/ + * The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay + * chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the + * typical x and y positioning while retaining the capability to visualize data using bubble radius + * and coloring. + * Examples: + * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + * @name bubbleOverlay + * @memberOf dc + * @mixes bubbleMixin,baseMixin + * @example + * // create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group + * var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); + * // create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A + * var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {BubbleOverlay} + */ dc.bubbleOverlay = function (root, chartGroup) { var BUBBLE_OVERLAY_CLASS = 'bubble-overlay'; var BUBBLE_NODE_CLASS = 'node'; var BUBBLE_CLASS = 'bubble'; + /** + * **mandatory** + * + * Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg + * element; therefore the bubble overlay chart will not work if this function is not invoked. If the + * underlying image is a bitmap, then an empty svg will need to be created on top of the image. + * @name svg + * @memberOf dc.bubbleOverlay + * @instance + * @example + * // set up underlying svg element + * chart.svg(d3.select('#chart svg')); + * @param {Selection} [imageElement] + * @returns {Chart} + */ var _chart = dc.bubbleMixin(dc.baseMixin({})); var _g; var _points = []; @@ -56,13 +52,20 @@ dc.bubbleOverlay = function (root, chartGroup) { }); /** - #### .point(name, x, y) - **mandatory** - Set up a data point on the overlay. The name of a data point should match a specific 'key' among - data groups generated using keyAccessor. If a match is found (point name <-> data group key) - then a bubble will be generated at the position specified by the function. x and y - value specified here are relative to the underlying svg. - - **/ + * **mandatory** + * + * Set up a data point on the overlay. The name of a data point should match a specific 'key' among + * data groups generated using keyAccessor. If a match is found (point name <-> data group key) + * then a bubble will be generated at the position specified by the function. x and y + * value specified here are relative to the underlying svg. + * @name point + * @memberOf dc.bubbleOverlay + * @instance + * @param {String} name + * @param {Number} x + * @param {Number} y + * @returns {Chart} + */ _chart.point = function (name, x, y) { _points.push({name: name, x: x, y: y}); return _chart; diff --git a/src/cap-mixin.js b/src/cap-mixin.js index d0b8ca39c..8a98efd2c 100644 --- a/src/cap-mixin.js +++ b/src/cap-mixin.js @@ -1,14 +1,17 @@ /** -## Cap Mixin -Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the -Row and Pie Charts. - -The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest -will be replaced with an *others* element, with value equal to the sum of the replaced values. The -keys of the elements below the cap limit are recorded in order to filter by those keys when the -*others* element is clicked. - -**/ + * Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the + * Row and Pie Charts. + * + * The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest + * will be replaced with an *others* element, with value equal to the sum of the replaced values. The + * keys of the elements below the cap limit are recorded in order to filter by those keys when the + * others* element is clicked. + * @name capMixin + * @memberOf dc + * @mixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.capMixin = function (_chart) { var _cap = Infinity; @@ -57,54 +60,65 @@ dc.capMixin = function (_chart) { }); /** - #### .cap([count]) - Get or set the count of elements to that will be included in the cap. - **/ - _chart.cap = function (_) { + * Get or set the count of elements to that will be included in the cap. + * @name cap + * @memberOf dc.capMixin + * @instance + * @param {Number} [count=Infinity] + * @returns {Number} + */ + _chart.cap = function (count) { if (!arguments.length) { return _cap; } - _cap = _; + _cap = count; return _chart; }; /** - #### .othersLabel([label]) - Get or set the label for *Others* slice when slices cap is specified. Default label is **Others**. - **/ - _chart.othersLabel = function (_) { + * Get or set the label for *Others* slice when slices cap is specified + * @name othersLabel + * @memberOf dc.capMixin + * @instance + * @param {String} [label=Others] + * @returns {String} + */ + _chart.othersLabel = function (label) { if (!arguments.length) { return _othersLabel; } - _othersLabel = _; + _othersLabel = label; return _chart; }; /** - #### .othersGrouper([grouperFunction]) - Get or set the grouper function that will perform the insertion of data for the *Others* slice - if the slices cap is specified. If set to a falsy value, no others will be added. By default the - grouper function computes the sum of all values below the cap. - ```js - chart.othersGrouper(function (data) { - // compute the value for others, presumably the sum of all values below the cap - var othersSum = yourComputeOthersValueLogic(data) - - // the keys are needed to properly filter when the others element is clicked - var othersKeys = yourComputeOthersKeysArrayLogic(data); - - // add the others row to the dataset - data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); - - return data; - }); - ``` - **/ - _chart.othersGrouper = function (_) { + * Get or set the grouper function that will perform the insertion of data for the *Others* slice + * if the slices cap is specified. If set to a falsy value, no others will be added. By default the + * grouper function computes the sum of all values below the cap. + * @name othersGrouper + * @memberOf dc.capMixin + * @instance + * @example + * chart.othersGrouper(function (data) { + * // compute the value for others, presumably the sum of all values below the cap + * var othersSum = yourComputeOthersValueLogic(data) + * + * // the keys are needed to properly filter when the others element is clicked + * var othersKeys = yourComputeOthersKeysArrayLogic(data); + * + * // add the others row to the dataset + * data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); + * + * return data; + * }); + * @param {Function} [grouperFunction] + * @returns {Function} + */ + _chart.othersGrouper = function (grouperFunction) { if (!arguments.length) { return _othersGrouper; } - _othersGrouper = _; + _othersGrouper = grouperFunction; return _chart; }; diff --git a/src/color-mixin.js b/src/color-mixin.js index 331d2c778..d9f7dde7a 100644 --- a/src/color-mixin.js +++ b/src/color-mixin.js @@ -4,7 +4,15 @@ The Color Mixin is an abstract chart functional class providing universal colori as a mix-in for any concrete chart implementation. **/ - +/** + * The Color Mixin is an abstract chart functional class providing universal coloring support + * as a mix-in for any concrete chart implementation. + * @name colorMixin + * @memberOf dc + * @mixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.colorMixin = function (_chart) { var _colors = d3.scale.category20c(); var _defaultAccessor = true; @@ -12,23 +20,25 @@ dc.colorMixin = function (_chart) { var _colorAccessor = function (d) { return _chart.keyAccessor()(d); }; /** - #### .colors([colorScale]) - Retrieve current color scale or set a new color scale. This methods accepts any function that - operates like a d3 scale. If not set the default is - `d3.scale.category20c()`. - ```js - // alternate categorical scale - chart.colors(d3.scale.category20b()); - - // ordinal scale - chart.colors(d3.scale.ordinal().range(['red','green','blue'])); - // convenience method, the same as above - chart.ordinalColors(['red','green','blue']); - - // set a linear scale - chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); - ``` - **/ + * Retrieve current color scale or set a new color scale. This methods accepts any function that + * operates like a d3 scale. + * @name colors + * @memberOf dc.colorMixin + * @instance + * @example + * // alternate categorical scale + * chart.colors(d3.scale.category20b()); + * + * // ordinal scale + * chart.colors(d3.scale.ordinal().range(['red','green','blue'])); + * // convenience method, the same as above + * chart.ordinalColors(['red','green','blue']); + * + * // set a linear scale + * chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); + * @param {D3Scale} [colorScale=d3.scale.category20c()] + * @returns {Chart} + */ _chart.colors = function (_) { if (!arguments.length) { return _colors; @@ -42,19 +52,25 @@ dc.colorMixin = function (_chart) { }; /** - #### .ordinalColors(r) - Convenience method to set the color scale to d3.scale.ordinal with range `r`. - - **/ + * Convenience method to set the color scale to d3.scale.ordinal with range `r`. + * @name ordinalColors + * @memberOf dc.colorMixin + * @instance + * @param {Array} r + * @returns {Chart} + */ _chart.ordinalColors = function (r) { return _chart.colors(d3.scale.ordinal().range(r)); }; /** - #### .linearColors(r) - Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. - - **/ + * Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. + * @name linearColors + * @memberOf dc.colorMixin + * @instance + * @param {Array} r + * @returns {Chart} + */ _chart.linearColors = function (r) { return _chart.colors(d3.scale.linear() .range(r) @@ -62,22 +78,25 @@ dc.colorMixin = function (_chart) { }; /** - #### .colorAccessor([colorAccessorFunction]) - Set or the get color accessor function. This function will be used to map a data point in a - crossfilter group to a color value on the color scale. The default function uses the key - accessor. - ```js - // default index based color accessor - .colorAccessor(function (d, i){return i;}) - // color accessor for a multi-value crossfilter reduction - .colorAccessor(function (d){return d.value.absGain;}) - ``` - **/ - _chart.colorAccessor = function (_) { + * Set or the get color accessor function. This function will be used to map a data point in a + * crossfilter group to a color value on the color scale. The default function uses the key + * accessor. + * @name linearColors + * @memberOf dc.colorMixin + * @instance + * @example + * // default index based color accessor + * .colorAccessor(function (d, i){return i;}) + * // color accessor for a multi-value crossfilter reduction + * .colorAccessor(function (d){return d.value.absGain;}) + * @param {Function} [colorAccessorFunction] + * @returns {Function} + */ + _chart.colorAccessor = function (colorAccessorFunction) { if (!arguments.length) { return _colorAccessor; } - _colorAccessor = _; + _colorAccessor = colorAccessorFunction; _defaultAccessor = false; return _chart; }; @@ -88,28 +107,33 @@ dc.colorMixin = function (_chart) { }; /** - #### .colorDomain([domain]) - Set or get the current domain for the color mapping function. The domain must be supplied as an - array. - - Note: previously this method accepted a callback function. Instead you may use a custom scale - set by `.colors`. - - **/ - _chart.colorDomain = function (_) { + * Set or get the current domain for the color mapping function. The domain must be supplied as an + * array. + * + * Note: previously this method accepted a callback function. Instead you may use a custom scale + * set by `.colors`. + * @name colorDomain + * @memberOf dc.colorMixin + * @instance + * @param {Array} [domain] + * @returns {Function} + */ + _chart.colorDomain = function (domain) { if (!arguments.length) { return _colors.domain(); } - _colors.domain(_); + _colors.domain(domain); return _chart; }; /** - #### .calculateColorDomain() - Set the domain by determining the min and max values as retrieved by `.colorAccessor` over the - chart's dataset. - - **/ + * Set the domain by determining the min and max values as retrieved by `.colorAccessor` over the + * chart's dataset. + * @name calculateColorDomain + * @memberOf dc.colorMixin + * @instance + * @returns {Chart} + */ _chart.calculateColorDomain = function () { var newDomain = [d3.min(_chart.data(), _chart.colorAccessor()), d3.max(_chart.data(), _chart.colorAccessor())]; @@ -118,18 +142,26 @@ dc.colorMixin = function (_chart) { }; /** - #### .getColor(d [, i]) - Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. - - **/ + * Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. + * @name getColor + * @memberOf dc.colorMixin + * @instance + * @param {*} d + * @param {Number} [i] + * @returns {String} + */ _chart.getColor = function (d, i) { return _colors(_colorAccessor.call(this, d, i)); }; /** - #### .colorCalculator([value]) - Gets or sets chart.getColor. - **/ + * Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. + * @name colorCalculator + * @memberOf dc.colorMixin + * @instance + * @param {*} [value] + * @returns {*} + */ _chart.colorCalculator = function (_) { if (!arguments.length) { return _chart.getColor; diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index 2cbf0213a..196cc9a05 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -27,12 +27,40 @@ chart.width(300) * [.dimension](#dc.baseMixin+dimension) ⇒ Dimension * [.data](#dc.baseMixin+data) ⇒ \* * [.group](#dc.baseMixin+group) ⇒ Group - * [.barChart](#dc.barChart) ⇒ barChart | BarChart + * [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart + * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> + * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function + * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number + * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number + * [.capMixin](#dc.capMixin) ⇒ Chart + * [.cap](#dc.capMixin+cap) ⇒ Number + * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String + * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function + * [.colorMixin](#dc.colorMixin) ⇒ Chart + * [.colors](#dc.colorMixin+colors) ⇒ Chart + * [.ordinalColors](#dc.colorMixin+ordinalColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ function + * [.colorDomain](#dc.colorMixin+colorDomain) ⇒ function + * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart + * [.getColor](#dc.colorMixin+getColor) ⇒ String + * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* + * [.barChart](#dc.barChart) ⇒ BarChart * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean * [.barPadding](#dc.barChart+barPadding) ⇒ Number * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number * [.gap](#dc.barChart+gap) ⇒ Number * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean + * [.boxPlot](#dc.boxPlot) ⇒ BoxPlot + * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number + * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number + * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function + * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function + * [.bubbleChart](#dc.bubbleChart) ⇒ BubbleChart + * [.elasticRadius](#dc.bubbleChart+elasticRadius) ⇒ Boolean + * [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay + * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart + * [.point](#dc.bubbleOverlay+point) ⇒ Chart * [.filterAll](#dc.filterAll) * [.refocusAll](#dc.refocusAll) * [.renderAll](#dc.renderAll) @@ -176,8 +204,267 @@ If `name` is specified then it will be used to generate legend label. | [group] | Group | | [name] | String | + +### dc.bubbleMixin ⇒ Chart +This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. + +**Kind**: static mixin of [dc](#dc) +**Mixes**: colorMixin + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart + * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> + * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function + * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number + * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number + + +#### bubbleMixin.r ⇒ Array.<Number> +Get or set the bubble radius scale. By default the bubble chart uses +`d3.scale.linear().domain([0, 100])` as its r scale . + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | +| --- | --- | +| [bubbleRadiusScale] | Array.<Number> | + + +#### bubbleMixin.radiusValueAccessor ⇒ function +Get or set the radius value accessor function. If set, the radius value accessor function will +be used to retrieve a data value for each bubble. The data retrieved then will be mapped using +the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble +size. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | +| --- | --- | +| [radiusValueAccessor] | function | + + +#### bubbleMixin.minRadiusWithLabel ⇒ Number +Get or set the minimum radius for label rendering. If a bubble's radius is less than this value +then no label will be rendered. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [radius] | Number | 10 | + + +#### bubbleMixin.maxBubbleRelativeSize ⇒ Number +Get or set the maximum relative size of a bubble to the length of x axis. This value is useful +when the difference in radius between bubbles is too great. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [relativeSize] | Number | 0.3 | + + +### dc.capMixin ⇒ Chart +Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the +Row and Pie Charts. + +The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest +will be replaced with an *others* element, with value equal to the sum of the replaced values. The +keys of the elements below the cap limit are recorded in order to filter by those keys when the +others* element is clicked. + +**Kind**: static mixin of [dc](#dc) + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.capMixin](#dc.capMixin) ⇒ Chart + * [.cap](#dc.capMixin+cap) ⇒ Number + * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String + * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function + + +#### capMixin.cap ⇒ Number +Get or set the count of elements to that will be included in the cap. + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [count] | Number | Infinity | + + +#### capMixin.othersLabel ⇒ String +Get or set the label for *Others* slice when slices cap is specified + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [label] | String | Others | + + +#### capMixin.othersGrouper ⇒ function +Get or set the grouper function that will perform the insertion of data for the *Others* slice +if the slices cap is specified. If set to a falsy value, no others will be added. By default the +grouper function computes the sum of all values below the cap. + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | +| --- | --- | +| [grouperFunction] | function | + +**Example** +```js +chart.othersGrouper(function (data) { + // compute the value for others, presumably the sum of all values below the cap + var othersSum = yourComputeOthersValueLogic(data) + + // the keys are needed to properly filter when the others element is clicked + var othersKeys = yourComputeOthersKeysArrayLogic(data); + + // add the others row to the dataset + data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); + + return data; +}); +``` + +### dc.colorMixin ⇒ Chart +The Color Mixin is an abstract chart functional class providing universal coloring support +as a mix-in for any concrete chart implementation. + +**Kind**: static mixin of [dc](#dc) + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.colorMixin](#dc.colorMixin) ⇒ Chart + * [.colors](#dc.colorMixin+colors) ⇒ Chart + * [.ordinalColors](#dc.colorMixin+ordinalColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ function + * [.colorDomain](#dc.colorMixin+colorDomain) ⇒ function + * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart + * [.getColor](#dc.colorMixin+getColor) ⇒ String + * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* + + +#### colorMixin.colors ⇒ Chart +Retrieve current color scale or set a new color scale. This methods accepts any function that +operates like a d3 scale. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [colorScale] | D3Scale | d3.scale.category20c() | + +**Example** +```js +// alternate categorical scale +chart.colors(d3.scale.category20b()); + +// ordinal scale +chart.colors(d3.scale.ordinal().range(['red','green','blue'])); +// convenience method, the same as above +chart.ordinalColors(['red','green','blue']); + +// set a linear scale +chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); +``` + +#### colorMixin.ordinalColors ⇒ Chart +Convenience method to set the color scale to d3.scale.ordinal with range `r`. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| r | Array.<String> | + + +#### colorMixin.linearColors ⇒ Chart +Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| r | Array.<Number> | + + +#### colorMixin.linearColors ⇒ function +Set or the get color accessor function. This function will be used to map a data point in a +crossfilter group to a color value on the color scale. The default function uses the key +accessor. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| [colorAccessorFunction] | function | + +**Example** +```js +// default index based color accessor +.colorAccessor(function (d, i){return i;}) +// color accessor for a multi-value crossfilter reduction +.colorAccessor(function (d){return d.value.absGain;}) +``` + +#### colorMixin.colorDomain ⇒ function +Set or get the current domain for the color mapping function. The domain must be supplied as an +array. + +Note: previously this method accepted a callback function. Instead you may use a custom scale +set by `.colors`. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| [domain] | Array.<String> | + + +#### colorMixin.calculateColorDomain ⇒ Chart +Set the domain by determining the min and max values as retrieved by `.colorAccessor` over the +chart's dataset. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +#### colorMixin.getColor ⇒ String +Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| d | \* | +| [i] | Number | + + +#### colorMixin.colorCalculator ⇒ \* +Get the color for the datum d and counter i. This is used internally by charts to retrieve a color. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) + +| Param | Type | +| --- | --- | +| [value] | \* | + -### dc.barChart ⇒ barChart | BarChart +### dc.barChart ⇒ BarChart Concrete bar chart/histogram implementation. Examples: - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) @@ -185,12 +472,11 @@ Examples: **Kind**: static property of [dc](#dc) **Mixes**: baseMixin -**Returns**: barChart - =======BarChart - >>>>>>> cec52eb469e363b35b6f8c2f36488f9bb1d481fc | Param | Type | Description | | --- | --- | --- | | parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. <<<<<<< HEAD | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** ```js @@ -202,7 +488,7 @@ var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); var chart3 = dc.barChart(compositeChart); ``` -* [.barChart](#dc.barChart) ⇒ barChart | BarChart +* [.barChart](#dc.barChart) ⇒ BarChart * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean * [.barPadding](#dc.barChart+barPadding) ⇒ Number * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number @@ -274,6 +560,196 @@ compensate, such as in the following example. ```js chart.round(function(n) {return Math.floor(n)+0.5}); ``` + +### dc.boxPlot ⇒ BoxPlot +A box plot is a chart that depicts numerical data via their quartile ranges. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a box plot under #chart-container1 element using the default global chart group +var boxPlot1 = dc.boxPlot('#chart-container1'); +// create a box plot under #chart-container2 element using chart group A +var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); +``` + +* [.boxPlot](#dc.boxPlot) ⇒ BoxPlot + * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number + * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number + * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function + * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function + + +#### boxPlot.boxPadding ⇒ Number +Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. +See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) +for a visual description of how the padding is applied. + +**Kind**: instance property of [boxPlot](#dc.boxPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Number | 0.8 | + + +#### boxPlot.outerPadding ⇒ Number +Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts +or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. + +**Kind**: instance property of [boxPlot](#dc.boxPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Number | 0.5 | + + +#### boxPlot.boxWidth ⇒ Number | function +Get or set the numerical width of the boxplot box. The width may also be a function taking as +parameters the chart width excluding the right and left margins, as well as the number of x +units. + +**Kind**: instance property of [boxPlot](#dc.boxPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [boxWidth] | Number | function | 0.5 | + +**Example** +```js +// Using numerical parameter +chart.boxWidth(10); +// Using function +chart.boxWidth((innerChartWidth, xUnits) { ... }); +``` + +#### boxPlot.tickFormat ⇒ Number | function +Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to +integer formatting. + +**Kind**: instance property of [boxPlot](#dc.boxPlot) + +| Param | Type | +| --- | --- | +| [tickFormat] | function | + +**Example** +```js +// format ticks to 2 decimal places +chart.tickFormat(d3.format('.2f')); +``` + +### dc.bubbleChart ⇒ BubbleChart +A concrete implementation of a general purpose bubble chart that allows data visualization using the +following dimensions: +- x axis position +- y axis position +- bubble radius +- color +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: bubbleMixin,coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a bubble chart under #chart-container1 element using the default global chart group +var bubbleChart1 = dc.bubbleChart('#chart-container1'); +// create a bubble chart under #chart-container2 element using chart group A +var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); +``` + +#### bubbleChart.elasticRadius ⇒ Boolean +Turn on or off the elastic bubble radius feature, or return the value of the flag. If this +feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. + +**Kind**: instance property of [bubbleChart](#dc.bubbleChart) + +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Boolean | false | + + +### dc.bubbleOverlay ⇒ BubbleOverlay +The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay +chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the +typical x and y positioning while retaining the capability to visualize data using bubble radius +and coloring. +Examples: +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: bubbleMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group +var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); +// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A +var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); +``` + +* [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay + * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart + * [.point](#dc.bubbleOverlay+point) ⇒ Chart + + +#### bubbleOverlay.svg ⇒ Chart +**mandatory** + +Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg +element; therefore the bubble overlay chart will not work if this function is not invoked. If the +underlying image is a bitmap, then an empty svg will need to be created on top of the image. + +**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) + +| Param | Type | +| --- | --- | +| [imageElement] | Selection | + +**Example** +```js +// set up underlying svg element +chart.svg(d3.select('#chart svg')); +``` + +#### bubbleOverlay.point ⇒ Chart +**mandatory** + +Set up a data point on the overlay. The name of a data point should match a specific 'key' among +data groups generated using keyAccessor. If a match is found (point name <-> data group key) +then a bubble will be generated at the position specified by the function. x and y +value specified here are relative to the underlying svg. + +**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) + +| Param | Type | +| --- | --- | +| name | String | +| x | Number | +| y | Number | + ### dc.filterAll Clear all filters on all charts within the given chart group. If the chart group is not given then From 7d32f23b51e63f056f1d92bae7e81ba1d1768f6e Mon Sep 17 00:00:00 2001 From: Matthew Traynham Date: Tue, 11 Aug 2015 01:27:44 -0400 Subject: [PATCH 5/8] Finished base mixin docs --- src/base-mixin.js | 885 +++++++++++++++++++++++------------------ web/docs/api-latest.md | 636 +++++++++++++++++++++++++++++ 2 files changed, 1130 insertions(+), 391 deletions(-) diff --git a/src/base-mixin.js b/src/base-mixin.js index 8d790052d..dc55dab7a 100644 --- a/src/base-mixin.js +++ b/src/base-mixin.js @@ -246,14 +246,18 @@ dc.baseMixin = function (_chart) { }; /** - #### .ordering([orderFunction]) - Get or set an accessor to order ordinal charts - **/ - _chart.ordering = function (o) { + * Get or set an accessor to order ordinal charts + * @name ordering + * @memberOf dc.baseMixin + * @instance + * @param {Function} [orderFunction] + * @returns {Function} + */ + _chart.ordering = function (orderFunction) { if (!arguments.length) { return _ordering; } - _ordering = o; + _ordering = orderFunction; _orderSort = crossfilter.quicksort.by(_ordering); _chart.expireCache(); return _chart; @@ -274,52 +278,64 @@ dc.baseMixin = function (_chart) { }; /** - #### .filterAll() - Clear all filters associated with this chart. - - **/ + * Clear all filters associated with this chart. + * @name filterAll + * @memberOf dc.baseMixin + * @instance + * @returns {Chart} + */ _chart.filterAll = function () { return _chart.filter(null); }; /** - #### .select(selector) - Execute d3 single selection in the chart's scope using the given selector and return the d3 - selection. Roughly the same as: - ```js - d3.select('#chart-id').select(selector); - ``` - This function is **not chainable** since it does not return a chart instance; however the d3 - selection result can be chained to d3 function calls. - - **/ + * Execute d3 single selection in the chart's scope using the given selector and return the d3 + * selection. + * + * This function is **not chainable** since it does not return a chart instance; however the d3 + * selection result can be chained to d3 function calls. + * @name select + * @memberOf dc.baseMixin + * @instance + * @example + * // Similar to: + * d3.select('#chart-id').select(selector); + * @returns {Selection} + */ _chart.select = function (s) { return _root.select(s); }; /** - #### .selectAll(selector) - Execute in scope d3 selectAll using the given selector and return d3 selection result. Roughly - the same as: - ```js - d3.select('#chart-id').selectAll(selector); - ``` - This function is **not chainable** since it does not return a chart instance; however the d3 - selection result can be chained to d3 function calls. - - **/ + * Execute in scope d3 selectAll using the given selector and return d3 selection result. + * + * This function is **not chainable** since it does not return a chart instance; however the d3 + * selection result can be chained to d3 function calls. + * @name selectAll + * @memberOf dc.baseMixin + * @instance + * @example + * // Similar to: + * d3.select('#chart-id').selectAll(selector); + * @returns {Selection} + */ _chart.selectAll = function (s) { return _root ? _root.selectAll(s) : null; }; /** - #### .anchor([anchorChart|anchorSelector|anchorNode], [chartGroup]) - Set the svg root to either be an existing chart's root; or any valid [d3 single - selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom - block element such as a div; or a dom element or d3 selection. Optionally registers the chart - within the chartGroup. This class is called internally on chart initialization, but be called - again to relocate the chart. However, it will orphan any previously created SVG elements. - **/ + * Set the svg root to either be an existing chart's root; or any valid [d3 single + * selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom + * block element such as a div; or a dom element or d3 selection. Optionally registers the chart + * within the chartGroup. This class is called internally on chart initialization, but be called + * again to relocate the chart. However, it will orphan any previously created SVG elements. + * @name anchor + * @memberOf dc.baseMixin + * @instance + * @param {anchorChart|anchorSelector|anchorNode} [a] + * @param {chartGroup} [chartGroup] + * @returns {Chart} + */ _chart.anchor = function (a, chartGroup) { if (!arguments.length) { return _anchor; @@ -340,10 +356,12 @@ dc.baseMixin = function (_chart) { }; /** - #### .anchorName() - Returns the dom id for the chart's anchored location. - - **/ + * Returns the dom id for the chart's anchored location. + * @name anchorName + * @memberOf dc.baseMixin + * @instance + * @return {String} + */ _chart.anchorName = function () { var a = _chart.anchor(); if (a && a.id) { @@ -356,13 +374,16 @@ dc.baseMixin = function (_chart) { }; /** - #### .root([rootElement]) - Returns the root element where a chart resides. Usually it will be the parent div element where - the svg was created. You can also pass in a new root element however this is usually handled by - dc internally. Resetting the root element on a chart outside of dc internals may have - unexpected consequences. - - **/ + * Returns the root element where a chart resides. Usually it will be the parent div element where + * the svg was created. You can also pass in a new root element however this is usually handled by + * dc internally. Resetting the root element on a chart outside of dc internals may have + * unexpected consequences. + * @name root + * @memberOf dc.baseMixin + * @instance + * @param {Element} [rootElement] + * @return {Element} + */ _chart.root = function (r) { if (!arguments.length) { return _root; @@ -372,12 +393,15 @@ dc.baseMixin = function (_chart) { }; /** - #### .svg([svgElement]) - Returns the top svg element for this specific chart. You can also pass in a new svg element, - however this is usually handled by dc internally. Resetting the svg element on a chart outside - of dc internals may have unexpected consequences. - - **/ + * Returns the top svg element for this specific chart. You can also pass in a new svg element, + * however this is usually handled by dc internally. Resetting the svg element on a chart outside + * of dc internals may have unexpected consequences. + * @name svg + * @memberOf dc.baseMixin + * @instance + * @param {SVGElement} [svgElement] + * @return {SVGElement} + */ _chart.svg = function (_) { if (!arguments.length) { return _svg; @@ -387,9 +411,12 @@ dc.baseMixin = function (_chart) { }; /** - #### .resetSvg() - Remove the chart's SVG elements from the dom and recreate the container SVG element. - **/ + * Remove the chart's SVG elements from the dom and recreate the container SVG element. + * @name resetSvg + * @memberOf dc.baseMixin + * @instance + * @return {SVGElement} + */ _chart.resetSvg = function () { _chart.select('svg').remove(); return generateSvg(); @@ -410,18 +437,21 @@ dc.baseMixin = function (_chart) { } /** - #### .filterPrinter([filterPrinterFunction]) - Set or get the filter printer function. The filter printer function is used to generate human - friendly text for filter value(s) associated with the chart instance. By default dc charts use a - default filter printer `dc.printers.filter` that provides simple printing support for both - single value and ranged filters. - - **/ - _chart.filterPrinter = function (_) { + * Set or get the filter printer function. The filter printer function is used to generate human + * friendly text for filter value(s) associated with the chart instance. By default dc charts use a + * default filter printer `dc.printers.filter` that provides simple printing support for both + * single value and ranged filters. + * @name filterPrinter + * @memberOf dc.baseMixin + * @instance + * @param {Function} [filterPrinterFunction] + * @return {Function} + */ + _chart.filterPrinter = function (filterPrinterFunction) { if (!arguments.length) { return _filterPrinter; } - _filterPrinter = _; + _filterPrinter = filterPrinterFunction; return _chart; }; @@ -438,6 +468,20 @@ dc.baseMixin = function (_chart) { function. This type of element will be turned off automatically if the filter is cleared. **/ + /** + * Turn on optional control elements within the root element. dc currently supports the + * following html control elements. + * * root.selectAll('.reset') - elements are turned on if the chart has an active filter. This type + * of control element is usually used to store a reset link to allow user to reset filter on a + * certain chart. This element will be turned off automatically if the filter is cleared. + * * root.selectAll('.filter') elements are turned on if the chart has an active filter. The text + * content of this element is then replaced with the current filter value using the filter printer + * function. This type of element will be turned off automatically if the filter is cleared. + * @name turnOnControls + * @memberOf dc.baseMixin + * @instance + * @return {Chart} + */ _chart.turnOnControls = function () { if (_root) { _chart.selectAll('.reset').style('display', null); @@ -446,6 +490,13 @@ dc.baseMixin = function (_chart) { return _chart; }; + /** + * Turn off optional control elements within the root element. + * @name turnOffControls + * @memberOf dc.baseMixin + * @instance + * @return {Chart} + */ _chart.turnOffControls = function () { if (_root) { _chart.selectAll('.reset').style('display', 'none'); @@ -455,16 +506,18 @@ dc.baseMixin = function (_chart) { }; /** - #### .transitionDuration([duration]) - Set or get the animation transition duration(in milliseconds) for this chart instance. Default - duration is 750ms. - - **/ - _chart.transitionDuration = function (d) { + * Set or get the animation transition duration (in milliseconds) for this chart instance. + * @name transitionDuration + * @memberOf dc.baseMixin + * @instance + * @param {Number} [duration] + * @return {Number} + */ + _chart.transitionDuration = function (duration) { if (!arguments.length) { return _transitionDuration; } - _transitionDuration = d; + _transitionDuration = duration; return _chart; }; @@ -484,13 +537,15 @@ dc.baseMixin = function (_chart) { } /** - #### .render() - Invoking this method will force the chart to re-render everything from scratch. Generally it - should only be used to render the chart for the first time on the page or if you want to make - sure everything is redrawn from scratch instead of relying on the default incremental redrawing - behaviour. - - **/ + * Invoking this method will force the chart to re-render everything from scratch. Generally it + * should only be used to render the chart for the first time on the page or if you want to make + * sure everything is redrawn from scratch instead of relying on the default incremental redrawing + * behaviour. + * @name render + * @memberOf dc.baseMixin + * @instance + * @return {Chart} + */ _chart.render = function () { _listeners.preRender(_chart); @@ -528,15 +583,17 @@ dc.baseMixin = function (_chart) { }; /** - #### .redraw() - Calling redraw will cause the chart to re-render data changes incrementally. If there is no - change in the underlying data dimension then calling this method will have no effect on the - chart. Most chart interaction in dc will automatically trigger this method through internal - events (in particular [dc.redrawAll](#dcredrawallchartgroup)); therefore, you only need to - manually invoke this function if data is manipulated outside of dc's control (for example if - data is loaded in the background using `crossfilter.add()`). - - **/ + * Calling redraw will cause the chart to re-render data changes incrementally. If there is no + * change in the underlying data dimension then calling this method will have no effect on the + * chart. Most chart interaction in dc will automatically trigger this method through internal + * events (in particular [dc.redrawAll](#dcredrawallchartgroup)); therefore, you only need to + * manually invoke this function if data is manipulated outside of dc's control (for example if + * data is loaded in the background using `crossfilter.add()`). + * @name redraw + * @memberOf dc.baseMixin + * @instance + * @return {Chart} + */ _chart.redraw = function () { sizeSvg(); _listeners.preRedraw(_chart); @@ -580,42 +637,47 @@ dc.baseMixin = function (_chart) { }; /** - #### .hasFilterHandler([function]) - Set or get the has filter handler. The has filter handler is a function that checks to see if - the chart's current filters include a specific filter. Using a custom has filter handler allows - you to change the way filters are checked for and replaced. - - ```js - // default has filter handler - function (filters, filter) { - if (filter === null || typeof(filter) === 'undefined') { - return filters.length > 0; - } - return filters.some(function (f) { - return filter <= f && filter >= f; - }); - } - - // custom filter handler (no-op) - chart.hasFilterHandler(function(filters, filter) { - return false; - }); - ``` - **/ - _chart.hasFilterHandler = function (_) { + * Set or get the has filter handler. The has filter handler is a function that checks to see if + * the chart's current filters include a specific filter. Using a custom has filter handler allows + * you to change the way filters are checked for and replaced. + * @name hasFilterHandler + * @memberOf dc.baseMixin + * @instance + * @example + * // default has filter handler + * function (filters, filter) { + * if (filter === null || typeof(filter) === 'undefined') { + * return filters.length > 0; + * } + * return filters.some(function (f) { + * return filter <= f && filter >= f; + * }); + * } + * + * // custom filter handler (no-op) + * chart.hasFilterHandler(function(filters, filter) { + * return false; + * }); + * @param {Function} [hasFilterHandler] + * @return {Chart} + */ + _chart.hasFilterHandler = function (hasFilterHandler) { if (!arguments.length) { return _hasFilterHandler; } - _hasFilterHandler = _; + _hasFilterHandler = hasFilterHandler; return _chart; }; /** - #### .hasFilter([filter]) - Check whether any active filter or a specific filter is associated with particular chart instance. - This function is **not chainable**. - - **/ + * Check whether any active filter or a specific filter is associated with particular chart instance. + * This function is **not chainable**. + * @name hasFilter + * @memberOf dc.baseMixin + * @instance + * @param {*} [hasFilter] + * @return {Boolean} + */ _chart.hasFilter = function (filter) { return _hasFilterHandler(_filters, filter); }; @@ -631,37 +693,39 @@ dc.baseMixin = function (_chart) { }; /** - #### .removeFilterHandler([function]) - Set or get the remove filter handler. The remove filter handler is a function that removes a - filter from the chart's current filters. Using a custom remove filter handler allows you to - change how filters are removed or perform additional work when removing a filter, e.g. when - using a filter server other than crossfilter. - - Any changes should modify the `filters` array argument and return that array. - - ```js - // default remove filter handler - function (filters, filter) { - for (var i = 0; i < filters.length; i++) { - if (filters[i] <= filter && filters[i] >= filter) { - filters.splice(i, 1); - break; - } - } - return filters; - } - - // custom filter handler (no-op) - chart.removeFilterHandler(function(filters, filter) { - return filters; - }); - ``` - **/ - _chart.removeFilterHandler = function (_) { + * Set or get the remove filter handler. The remove filter handler is a function that removes a + * filter from the chart's current filters. Using a custom remove filter handler allows you to + * change how filters are removed or perform additional work when removing a filter, e.g. when + * using a filter server other than crossfilter. + * + * Any changes should modify the `filters` array argument and return that array. + * @name removeFilterHandler + * @memberOf dc.baseMixin + * @instance + * @example + * // default remove filter handler + * function (filters, filter) { + * for (var i = 0; i < filters.length; i++) { + * if (filters[i] <= filter && filters[i] >= filter) { + * filters.splice(i, 1); + * break; + * } + * } + * return filters; + * } + * + * // custom filter handler (no-op) + * chart.removeFilterHandler(function(filters, filter) { + * return filters; + * }); + * @param {Function} [removeFilterHandler] + * @return {Chart} + */ + _chart.removeFilterHandler = function (removeFilterHandler) { if (!arguments.length) { return _removeFilterHandler; } - _removeFilterHandler = _; + _removeFilterHandler = removeFilterHandler; return _chart; }; @@ -671,32 +735,34 @@ dc.baseMixin = function (_chart) { }; /** - #### .addFilterHandler([function]) - Set or get the add filter handler. The add filter handler is a function that adds a filter to - the chart's filter list. Using a custom add filter handler allows you to change the way filters - are added or perform additional work when adding a filter, e.g. when using a filter server other - than crossfilter. - - Any changes should modify the `filters` array argument and return that array. - - ```js - // default add filter handler - function (filters, filter) { - filters.push(filter); - return filters; - } - - // custom filter handler (no-op) - chart.addFilterHandler(function(filters, filter) { - return filters; - }); - ``` - **/ - _chart.addFilterHandler = function (_) { + * Set or get the add filter handler. The add filter handler is a function that adds a filter to + * the chart's filter list. Using a custom add filter handler allows you to change the way filters + * are added or perform additional work when adding a filter, e.g. when using a filter server other + * than crossfilter. + * + * Any changes should modify the `filters` array argument and return that array. + * @name addFilterHandler + * @memberOf dc.baseMixin + * @instance + * @example + * // default add filter handler + * function (filters, filter) { + * filters.push(filter); + * return filters; + * } + * + * // custom filter handler (no-op) + * chart.addFilterHandler(function(filters, filter) { + * return filters; + * }); + * @param {Function} [addFilterHandler] + * @return {Chart} + */ + _chart.addFilterHandler = function (addFilterHandler) { if (!arguments.length) { return _addFilterHandler; } - _addFilterHandler = _; + _addFilterHandler = addFilterHandler; return _chart; }; @@ -705,31 +771,33 @@ dc.baseMixin = function (_chart) { }; /** - #### .resetFilterHandler([function]) - Set or get the reset filter handler. The reset filter handler is a function that resets the - chart's filter list by returning a new list. Using a custom reset filter handler allows you to - change the way filters are reset, or perform additional work when resetting the filters, - e.g. when using a filter server other than crossfilter. - - This function should return an array. - - ```js - // default remove filter handler - function (filters) { - return []; - } - - // custom filter handler (no-op) - chart.resetFilterHandler(function(filters) { - return filters; - }); - ``` - **/ - _chart.resetFilterHandler = function (_) { + * Set or get the reset filter handler. The reset filter handler is a function that resets the + * chart's filter list by returning a new list. Using a custom reset filter handler allows you to + * change the way filters are reset, or perform additional work when resetting the filters, + * e.g. when using a filter server other than crossfilter. + * + * This function should return an array. + * @name resetFilterHandler + * @memberOf dc.baseMixin + * @instance + * @example + * // default remove filter handler + * function (filters) { + * return []; + * } + * + * // custom filter handler (no-op) + * chart.resetFilterHandler(function(filters) { + * return filters; + * }); + * @param {Function} [resetFilterHandler] + * @return {Chart} + */ + _chart.resetFilterHandler = function (resetFilterHandler) { if (!arguments.length) { return _resetFilterHandler; } - _resetFilterHandler = _; + _resetFilterHandler = resetFilterHandler; return _chart; }; @@ -746,15 +814,18 @@ dc.baseMixin = function (_chart) { }; /** - #### .filter([filterValue]) - Filter the chart by the given value or return the current filter if the input parameter is missing. - ```js - // filter by a single string - chart.filter('Sunday'); - // filter by a single age - chart.filter(18); - ``` - **/ + * Filter the chart by the given value or return the current filter if the input parameter is missing. + * @name filter + * @memberOf dc.baseMixin + * @instance + * @example + * // filter by a single string + * chart.filter('Sunday'); + * // filter by a single age + * chart.filter(18); + * @param {*} [filterValue] + * @return {Chart} + */ _chart.filter = function (_) { if (!arguments.length) { return _filters.length > 0 ? _filters[0] : null; @@ -789,12 +860,14 @@ dc.baseMixin = function (_chart) { }; /** - #### .filters() - Returns all current filters. This method does not perform defensive cloning of the internal - filter array before returning, therefore any modification of the returned array will effect the - chart's internal filter storage. - - **/ + * Returns all current filters. This method does not perform defensive cloning of the internal + * filter array before returning, therefore any modification of the returned array will effect the + * chart's internal filter storage. + * @name filters + * @memberOf dc.baseMixin + * @instance + * @return {Array<*>} + */ _chart.filters = function () { return _filters; }; @@ -815,10 +888,13 @@ dc.baseMixin = function (_chart) { }; /** - #### .onClick(datum) - This function is passed to d3 as the onClick handler for each chart. The default behavior is to - filter on the clicked datum (passed to the callback) and redraw the chart group. - **/ + * This function is passed to d3 as the onClick handler for each chart. The default behavior is to + * filter on the clicked datum (passed to the callback) and redraw the chart group. + * @name onClick + * @memberOf dc.baseMixin + * @instance + * @param {*} datum + */ _chart.onClick = function (d) { var filter = _chart.keyAccessor()(d); dc.events.trigger(function () { @@ -828,27 +904,28 @@ dc.baseMixin = function (_chart) { }; /** - #### .filterHandler([function]) - Set or get the filter handler. The filter handler is a function that performs the filter action - on a specific dimension. Using a custom filter handler allows you to perform additional logic - before or after filtering. - - ```js - // default filter handler - function(dimension, filter){ - dimension.filter(filter); // perform filtering - return filter; // return the actual filter value - } - - // custom filter handler - chart.filterHandler(function(dimension, filter){ - var newFilter = filter + 10; - dimension.filter(newFilter); - return newFilter; // set the actual filter value to the new value - }); - ``` - - **/ + * Set or get the filter handler. The filter handler is a function that performs the filter action + * on a specific dimension. Using a custom filter handler allows you to perform additional logic + * before or after filtering. + * @name filterHandler + * @memberOf dc.baseMixin + * @instance + * @example + * // default filter handler + * function(dimension, filter){ + * dimension.filter(filter); // perform filtering + * return filter; // return the actual filter value + * } + * + * // custom filter handler + * chart.filterHandler(function(dimension, filter){ + * var newFilter = filter + 10; + * dimension.filter(newFilter); + * return newFilter; // set the actual filter value to the new value + * }); + * @param {Function} filterHandler + * @return {Chart} + */ _chart.filterHandler = function (_) { if (!arguments.length) { return _filterHandler; @@ -891,62 +968,68 @@ dc.baseMixin = function (_chart) { }; /** - #### .keyAccessor([keyAccessorFunction]) - Set or get the key accessor function. The key accessor function is used to retrieve the key - value from the crossfilter group. Key values are used differently in different charts, for - example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart. - ```js - // default key accessor - chart.keyAccessor(function(d) { return d.key; }); - // custom key accessor for a multi-value crossfilter reduction - chart.keyAccessor(function(p) { return p.value.absGain; }); - ``` - - **/ - _chart.keyAccessor = function (_) { + * Set or get the key accessor function. The key accessor function is used to retrieve the key + * value from the crossfilter group. Key values are used differently in different charts, for + * example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart. + * @name keyAccessor + * @memberOf dc.baseMixin + * @instance + * @example + * // default key accessor + * chart.keyAccessor(function(d) { return d.key; }); + * // custom key accessor for a multi-value crossfilter reduction + * chart.keyAccessor(function(p) { return p.value.absGain; }); + * @param {Function} keyAccessor + * @return {Chart} + */ + _chart.keyAccessor = function (keyAccessor) { if (!arguments.length) { return _keyAccessor; } - _keyAccessor = _; + _keyAccessor = keyAccessor; return _chart; }; /** - #### .valueAccessor([valueAccessorFunction]) - Set or get the value accessor function. The value accessor function is used to retrieve the - value from the crossfilter group. Group values are used differently in different charts, for - example values correspond to slice sizes in a pie chart and y axis positions in a grid - coordinate chart. - ```js - // default value accessor - chart.valueAccessor(function(d) { return d.value; }); - // custom value accessor for a multi-value crossfilter reduction - chart.valueAccessor(function(p) { return p.value.percentageGain; }); - ``` - - **/ - _chart.valueAccessor = function (_) { + * Set or get the value accessor function. The value accessor function is used to retrieve the + * value from the crossfilter group. Group values are used differently in different charts, for + * example values correspond to slice sizes in a pie chart and y axis positions in a grid + * coordinate chart. + * @name valueAccessor + * @memberOf dc.baseMixin + * @instance + * @example + * // default value accessor + * chart.valueAccessor(function(d) { return d.value; }); + * // custom value accessor for a multi-value crossfilter reduction + * chart.valueAccessor(function(p) { return p.value.percentageGain; }); + * @param {Function} valueAccessor + * @return {Chart} + */ + _chart.valueAccessor = function (valueAccessor) { if (!arguments.length) { return _valueAccessor; } - _valueAccessor = _; + _valueAccessor = valueAccessor; return _chart; }; /** - #### .label([labelFunction]) - Set or get the label function. The chart class will use this function to render labels for each - child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every - chart supports the label function for example bar chart and line chart do not use this function - at all. - ```js - // default label function just return the key - chart.label(function(d) { return d.key; }); - // label function has access to the standard d3 data binding and can get quite complicated - chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; }); - ``` - - **/ + * Set or get the label function. The chart class will use this function to render labels for each + * child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every + * chart supports the label function for example bar chart and line chart do not use this function + * at all. + * @name label + * @memberOf dc.baseMixin + * @instance + * @example + * // default label function just return the key + * chart.label(function(d) { return d.key; }); + * // label function has access to the standard d3 data binding and can get quite complicated + * chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; }); + * @param {Function} labelFunction + * @return {Chart} + */ _chart.label = function (_) { if (!arguments.length) { return _label; @@ -957,100 +1040,113 @@ dc.baseMixin = function (_chart) { }; /** - #### .renderLabel(boolean) - Turn on/off label rendering - - **/ - _chart.renderLabel = function (_) { + * Turn on/off label rendering + * @name renderLabel + * @memberOf dc.baseMixin + * @instance + * @param {Boolean} renderLabel + * @return {Boolean} + */ + _chart.renderLabel = function (renderLabel) { if (!arguments.length) { return _renderLabel; } - _renderLabel = _; + _renderLabel = renderLabel; return _chart; }; /** - #### .title([titleFunction]) - Set or get the title function. The chart class will use this function to render the svg title - (usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice - in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; - however in grid coordinate charts you need to turn off the brush in order to see titles, because - otherwise the brush layer will block tooltip triggering. - ```js - // default title function just return the key - chart.title(function(d) { return d.key + ': ' + d.value; }); - // title function has access to the standard d3 data binding and can get quite complicated - chart.title(function(p) { - return p.key.getFullYear() - + '\n' - + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n' - + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n' - + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%'; - }); - ``` - - **/ - _chart.title = function (_) { + * Set or get the title function. The chart class will use this function to render the svg title + * (usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice + * in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; + * however in grid coordinate charts you need to turn off the brush in order to see titles, because + * otherwise the brush layer will block tooltip triggering. + * @name title + * @memberOf dc.baseMixin + * @instance + * @example + * // default title function just return the key + * chart.title(function(d) { return d.key + ': ' + d.value; }); + * // title function has access to the standard d3 data binding and can get quite complicated + * chart.title(function(p) { + * return p.key.getFullYear() + * + '\n' + * + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n' + * + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n' + * + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%'; + * }); + * @param {Function} titleFunction + * @return {Function} + */ + _chart.title = function (titleFunction) { if (!arguments.length) { return _title; } - _title = _; + _title = titleFunction; return _chart; }; /** - #### .renderTitle(boolean) - Turn on/off title rendering, or return the state of the render title flag if no arguments are - given. - - **/ - _chart.renderTitle = function (_) { + * Turn on/off title rendering, or return the state of the render title flag if no arguments are + * given. + * @name renderTitle + * @memberOf dc.baseMixin + * @instance + * @param {Boolean} renderTitle + * @return {Boolean} + */ + _chart.renderTitle = function (renderTitle) { if (!arguments.length) { return _renderTitle; } - _renderTitle = _; + _renderTitle = renderTitle; return _chart; }; /** - #### .renderlet(renderletFunction) - A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added - to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked - right after the chart finishes its transitions, giving you a way to modify the svg - elements. Renderlet functions take the chart instance as the only input parameter and you can - use the dc API or use raw d3 to achieve pretty much any effect. - - @Deprecated - Use [Listeners](#Listeners) with a 'renderlet' prefix - Generates a random key for the renderlet, which makes it hard to remove. - ```js - // do this instead of .renderlet(function(chart) { ... }) - chart.on("renderlet", function(chart){ - // mix of dc API and d3 manipulation - chart.select('g.y').style('display', 'none'); - // its a closure so you can also access other chart variable available in the closure scope - moveChart.filter(chart.filter()); - }); - ``` - - **/ + * A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added + * to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked + * right after the chart finishes its transitions, giving you a way to modify the svg + * elements. Renderlet functions take the chart instance as the only input parameter and you can + * use the dc API or use raw d3 to achieve pretty much any effect. + * @name renderlet + * @memberOf dc.baseMixin + * @instance + * @deprecated Use [Listeners](#Listeners) with a 'renderlet' prefix. + * Generates a random key for the renderlet, which makes it hard to remove. + * @example + * // do this instead of .renderlet(function(chart) { ... }) + * chart.on("renderlet", function(chart){ + * // mix of dc API and d3 manipulation + * chart.select('g.y').style('display', 'none'); + * // its a closure so you can also access other chart variable available in the closure scope + * moveChart.filter(chart.filter()); + * }); + * @param {Function} renderletFunction + * @return {Function} + */ _chart.renderlet = dc.logger.deprecate(function (_) { _chart.on('renderlet.' + dc.utils.uniqueId(), _); return _chart; }, 'chart.renderlet has been deprecated. Please use chart.on("renderlet.", renderletFunction)'); /** - #### .chartGroup([group]) - Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn - together since it is expected they share the same underlying crossfilter data set. - **/ - _chart.chartGroup = function (_) { + * Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn + * together since it is expected they share the same underlying crossfilter data set. + * @name chartGroup + * @memberOf dc.baseMixin + * @instance + * @param {String} chartGroup + * @return {String} + */ + _chart.chartGroup = function (chartGroup) { if (!arguments.length) { return _chartGroup; } if (!_isChild) { dc.deregisterChart(_chart, _chartGroup); } - _chartGroup = _; + _chartGroup = chartGroup; if (!_isChild) { dc.registerChart(_chart, _chartGroup); } @@ -1058,29 +1154,32 @@ dc.baseMixin = function (_chart) { }; /** - #### .expireCache() - Expire the internal chart cache. dc charts cache some data internally on a per chart basis to - speed up rendering and avoid unnecessary calculation; however it might be useful to clear the - cache if you have changed state which will affect rendering. For example if you invoke the - `crossfilter.add` function or reset group or dimension after rendering it is a good idea to - clear the cache to make sure charts are rendered properly. - - **/ + * Expire the internal chart cache. dc charts cache some data internally on a per chart basis to + * speed up rendering and avoid unnecessary calculation; however it might be useful to clear the + * cache if you have changed state which will affect rendering. For example if you invoke the + * `crossfilter.add` function or reset group or dimension after rendering it is a good idea to + * clear the cache to make sure charts are rendered properly. + * @name expireCache + * @memberOf dc.baseMixin + * @instance + * @return {Chart} + */ _chart.expireCache = function () { // do nothing in base, should be overridden by sub-function return _chart; }; /** - #### .legend([dc.legend]) - Attach a dc.legend widget to this chart. The legend widget will automatically draw legend labels - based on the color setting and names associated with each group. - - ```js - chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) - ``` - - **/ + * Attach a dc.legend widget to this chart. The legend widget will automatically draw legend labels + * based on the color setting and names associated with each group. + * @name legend + * @memberOf dc.baseMixin + * @instance + * @example + * chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) + * @param {dc.legend} [legend] + * @return {dc.legend} + */ _chart.legend = function (l) { if (!arguments.length) { return _legend; @@ -1091,23 +1190,27 @@ dc.baseMixin = function (_chart) { }; /** - #### .chartID() - Returns the internal numeric ID of the chart. - **/ + * Returns the internal numeric ID of the chart. + * @name chartID + * @memberOf dc.baseMixin + * @instance + * @return {String} + */ _chart.chartID = function () { return _chart.__dcFlag__; }; /** - #### .options(optionsObject) - Set chart options using a configuration object. Each key in the object will cause the method of - the same name to be called with the value to set that attribute for the chart. - - Example: - ``` - chart.options({dimension: myDimension, group: myGroup}); - ``` - **/ + * Set chart options using a configuration object. Each key in the object will cause the method of + * the same name to be called with the value to set that attribute for the chart. + * @name options + * @memberOf dc.baseMixin + * @instance + * @example + * chart.options({dimension: myDimension, group: myGroup}); + * @param {{}} opts + * @return {Chart} + */ _chart.options = function (opts) { var applyOptions = [ 'anchor', @@ -1136,35 +1239,35 @@ dc.baseMixin = function (_chart) { }; /** - ## Listeners - All dc chart instance supports the following listeners. - - #### .on('renderlet', function(chart, filter){...}) - This listener function will be invoked after transitions after redraw and render. Replaces the - deprecated `.renderlet()` method. - - #### .on('pretransition', function(chart, filter){...}) - Like `.on('renderlet', ...)` but the event is fired before transitions start. - - #### .on('preRender', function(chart){...}) - This listener function will be invoked before chart rendering. - - #### .on('postRender', function(chart){...}) - This listener function will be invoked after chart finish rendering including all renderlets' logic. - - #### .on('preRedraw', function(chart){...}) - This listener function will be invoked before chart redrawing. - - #### .on('postRedraw', function(chart){...}) - This listener function will be invoked after chart finish redrawing including all renderlets' logic. - - #### .on('filtered', function(chart, filter){...}) - This listener function will be invoked after a filter is applied, added or removed. - - #### .on('zoomed', function(chart, filter){...}) - This listener function will be invoked after a zoom is triggered. - - **/ + * All dc chart instance supports the following listeners. + * Supports the following events: + * * 'renderlet' - This listener function will be invoked after transitions after redraw and render. Replaces the + * deprecated `.renderlet()` method. + * * 'pretransition' - Like `.on('renderlet', ...)` but the event is fired before transitions start. + * * 'preRender' - This listener function will be invoked before chart rendering. + * * 'postRender' - This listener function will be invoked after chart finish rendering including + * all renderlets' logic. + * * 'preRedraw' - This listener function will be invoked before chart redrawing. + * * 'postRedraw' - This listener function will be invoked after chart finish redrawing + * including all renderlets' logic. + * * 'filtered' - This listener function will be invoked after a filter is applied, added or removed. + * * 'zoomed' - This listener function will be invoked after a zoom is triggered. + * @name on + * @memberOf dc.baseMixin + * @instance + * @example + * .on('renderlet', function(chart, filter){...}) + * .on('pretransition', function(chart, filter){...}) + * .on('preRender', function(chart){...}) + * .on('postRender', function(chart){...}) + * .on('preRedraw', function(chart){...}) + * .on('postRedraw', function(chart){...}) + * .on('filtered', function(chart, filter){...}) + * .on('zoomed', function(chart, filter){...}) + * @param {String} event + * @param {Function} listener + * @return {Chart} + */ _chart.on = function (event, listener) { _listeners.on(event, listener); return _chart; diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index 196cc9a05..02c91a170 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -27,6 +27,43 @@ chart.width(300) * [.dimension](#dc.baseMixin+dimension) ⇒ Dimension * [.data](#dc.baseMixin+data) ⇒ \* * [.group](#dc.baseMixin+group) ⇒ Group + * [.ordering](#dc.baseMixin+ordering) ⇒ function + * [.filterAll](#dc.baseMixin+filterAll) ⇒ Chart + * [.select](#dc.baseMixin+select) ⇒ Selection + * [.selectAll](#dc.baseMixin+selectAll) ⇒ Selection + * [.anchor](#dc.baseMixin+anchor) ⇒ Chart + * [.anchorName](#dc.baseMixin+anchorName) ⇒ String + * [.root](#dc.baseMixin+root) ⇒ Element + * [.svg](#dc.baseMixin+svg) ⇒ SVGElement + * [.resetSvg](#dc.baseMixin+resetSvg) ⇒ SVGElement + * [.filterPrinter](#dc.baseMixin+filterPrinter) ⇒ function + * [.turnOnControls](#dc.baseMixin+turnOnControls) ⇒ Chart + * [.turnOffControls](#dc.baseMixin+turnOffControls) ⇒ Chart + * [.transitionDuration](#dc.baseMixin+transitionDuration) ⇒ Number + * [.render](#dc.baseMixin+render) ⇒ Chart + * [.redraw](#dc.baseMixin+redraw) ⇒ Chart + * [.hasFilterHandler](#dc.baseMixin+hasFilterHandler) ⇒ Chart + * [.hasFilter](#dc.baseMixin+hasFilter) ⇒ Boolean + * [.removeFilterHandler](#dc.baseMixin+removeFilterHandler) ⇒ Chart + * [.addFilterHandler](#dc.baseMixin+addFilterHandler) ⇒ Chart + * [.resetFilterHandler](#dc.baseMixin+resetFilterHandler) ⇒ Chart + * [.filter](#dc.baseMixin+filter) ⇒ Chart + * [.filters](#dc.baseMixin+filters) ⇒ Array.<\*> + * [.onClick](#dc.baseMixin+onClick) + * [.filterHandler](#dc.baseMixin+filterHandler) ⇒ Chart + * [.keyAccessor](#dc.baseMixin+keyAccessor) ⇒ Chart + * [.valueAccessor](#dc.baseMixin+valueAccessor) ⇒ Chart + * [.label](#dc.baseMixin+label) ⇒ Chart + * [.renderLabel](#dc.baseMixin+renderLabel) ⇒ Boolean + * [.title](#dc.baseMixin+title) ⇒ function + * [.renderTitle](#dc.baseMixin+renderTitle) ⇒ Boolean + * ~~[.renderlet](#dc.baseMixin+renderlet) ⇒ function~~ + * [.chartGroup](#dc.baseMixin+chartGroup) ⇒ String + * [.expireCache](#dc.baseMixin+expireCache) ⇒ Chart + * [.legend](#dc.baseMixin+legend) ⇒ dc.legend + * [.chartID](#dc.baseMixin+chartID) ⇒ String + * [.options](#dc.baseMixin+options) ⇒ Chart + * [.on](#dc.baseMixin+on) ⇒ Chart * [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function @@ -93,6 +130,43 @@ and available on all chart implementation in the DC library. * [.dimension](#dc.baseMixin+dimension) ⇒ Dimension * [.data](#dc.baseMixin+data) ⇒ \* * [.group](#dc.baseMixin+group) ⇒ Group + * [.ordering](#dc.baseMixin+ordering) ⇒ function + * [.filterAll](#dc.baseMixin+filterAll) ⇒ Chart + * [.select](#dc.baseMixin+select) ⇒ Selection + * [.selectAll](#dc.baseMixin+selectAll) ⇒ Selection + * [.anchor](#dc.baseMixin+anchor) ⇒ Chart + * [.anchorName](#dc.baseMixin+anchorName) ⇒ String + * [.root](#dc.baseMixin+root) ⇒ Element + * [.svg](#dc.baseMixin+svg) ⇒ SVGElement + * [.resetSvg](#dc.baseMixin+resetSvg) ⇒ SVGElement + * [.filterPrinter](#dc.baseMixin+filterPrinter) ⇒ function + * [.turnOnControls](#dc.baseMixin+turnOnControls) ⇒ Chart + * [.turnOffControls](#dc.baseMixin+turnOffControls) ⇒ Chart + * [.transitionDuration](#dc.baseMixin+transitionDuration) ⇒ Number + * [.render](#dc.baseMixin+render) ⇒ Chart + * [.redraw](#dc.baseMixin+redraw) ⇒ Chart + * [.hasFilterHandler](#dc.baseMixin+hasFilterHandler) ⇒ Chart + * [.hasFilter](#dc.baseMixin+hasFilter) ⇒ Boolean + * [.removeFilterHandler](#dc.baseMixin+removeFilterHandler) ⇒ Chart + * [.addFilterHandler](#dc.baseMixin+addFilterHandler) ⇒ Chart + * [.resetFilterHandler](#dc.baseMixin+resetFilterHandler) ⇒ Chart + * [.filter](#dc.baseMixin+filter) ⇒ Chart + * [.filters](#dc.baseMixin+filters) ⇒ Array.<\*> + * [.onClick](#dc.baseMixin+onClick) + * [.filterHandler](#dc.baseMixin+filterHandler) ⇒ Chart + * [.keyAccessor](#dc.baseMixin+keyAccessor) ⇒ Chart + * [.valueAccessor](#dc.baseMixin+valueAccessor) ⇒ Chart + * [.label](#dc.baseMixin+label) ⇒ Chart + * [.renderLabel](#dc.baseMixin+renderLabel) ⇒ Boolean + * [.title](#dc.baseMixin+title) ⇒ function + * [.renderTitle](#dc.baseMixin+renderTitle) ⇒ Boolean + * ~~[.renderlet](#dc.baseMixin+renderlet) ⇒ function~~ + * [.chartGroup](#dc.baseMixin+chartGroup) ⇒ String + * [.expireCache](#dc.baseMixin+expireCache) ⇒ Chart + * [.legend](#dc.baseMixin+legend) ⇒ dc.legend + * [.chartID](#dc.baseMixin+chartID) ⇒ String + * [.options](#dc.baseMixin+options) ⇒ Chart + * [.on](#dc.baseMixin+on) ⇒ Chart #### baseMixin.width ⇒ Number @@ -204,6 +278,568 @@ If `name` is specified then it will be used to generate legend label. | [group] | Group | | [name] | String | + +#### baseMixin.ordering ⇒ function +Get or set an accessor to order ordinal charts + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [orderFunction] | function | + + +#### baseMixin.filterAll ⇒ Chart +Clear all filters associated with this chart. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.select ⇒ Selection +Execute d3 single selection in the chart's scope using the given selector and return the d3 +selection. + +This function is **not chainable** since it does not return a chart instance; however the d3 +selection result can be chained to d3 function calls. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) +**Example** +```js +// Similar to: +d3.select('#chart-id').select(selector); +``` + +#### baseMixin.selectAll ⇒ Selection +Execute in scope d3 selectAll using the given selector and return d3 selection result. + +This function is **not chainable** since it does not return a chart instance; however the d3 +selection result can be chained to d3 function calls. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) +**Example** +```js +// Similar to: +d3.select('#chart-id').selectAll(selector); +``` + +#### baseMixin.anchor ⇒ Chart +Set the svg root to either be an existing chart's root; or any valid [d3 single +selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom +block element such as a div; or a dom element or d3 selection. Optionally registers the chart +within the chartGroup. This class is called internally on chart initialization, but be called +again to relocate the chart. However, it will orphan any previously created SVG elements. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [a] | anchorChart | anchorSelector | anchorNode | +| [chartGroup] | chartGroup | + + +#### baseMixin.anchorName ⇒ String +Returns the dom id for the chart's anchored location. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.root ⇒ Element +Returns the root element where a chart resides. Usually it will be the parent div element where +the svg was created. You can also pass in a new root element however this is usually handled by +dc internally. Resetting the root element on a chart outside of dc internals may have +unexpected consequences. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [rootElement] | Element | + + +#### baseMixin.svg ⇒ SVGElement +Returns the top svg element for this specific chart. You can also pass in a new svg element, +however this is usually handled by dc internally. Resetting the svg element on a chart outside +of dc internals may have unexpected consequences. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [svgElement] | SVGElement | + + +#### baseMixin.resetSvg ⇒ SVGElement +Remove the chart's SVG elements from the dom and recreate the container SVG element. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.filterPrinter ⇒ function +Set or get the filter printer function. The filter printer function is used to generate human +friendly text for filter value(s) associated with the chart instance. By default dc charts use a +default filter printer `dc.printers.filter` that provides simple printing support for both +single value and ranged filters. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [filterPrinterFunction] | function | + + +#### baseMixin.turnOnControls ⇒ Chart +Turn on optional control elements within the root element. dc currently supports the +following html control elements. +* root.selectAll('.reset') - elements are turned on if the chart has an active filter. This type +of control element is usually used to store a reset link to allow user to reset filter on a +certain chart. This element will be turned off automatically if the filter is cleared. +* root.selectAll('.filter') elements are turned on if the chart has an active filter. The text +content of this element is then replaced with the current filter value using the filter printer +function. This type of element will be turned off automatically if the filter is cleared. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.turnOffControls ⇒ Chart +Turn off optional control elements within the root element. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.transitionDuration ⇒ Number +Set or get the animation transition duration (in milliseconds) for this chart instance. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [duration] | Number | + + +#### baseMixin.render ⇒ Chart +Invoking this method will force the chart to re-render everything from scratch. Generally it +should only be used to render the chart for the first time on the page or if you want to make +sure everything is redrawn from scratch instead of relying on the default incremental redrawing +behaviour. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.redraw ⇒ Chart +Calling redraw will cause the chart to re-render data changes incrementally. If there is no +change in the underlying data dimension then calling this method will have no effect on the +chart. Most chart interaction in dc will automatically trigger this method through internal +events (in particular [dc.redrawAll](#dcredrawallchartgroup)); therefore, you only need to +manually invoke this function if data is manipulated outside of dc's control (for example if +data is loaded in the background using `crossfilter.add()`). + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.hasFilterHandler ⇒ Chart +Set or get the has filter handler. The has filter handler is a function that checks to see if +the chart's current filters include a specific filter. Using a custom has filter handler allows +you to change the way filters are checked for and replaced. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [hasFilterHandler] | function | + +**Example** +```js +// default has filter handler +function (filters, filter) { + if (filter === null || typeof(filter) === 'undefined') { + return filters.length > 0; + } + return filters.some(function (f) { + return filter <= f && filter >= f; + }); +} + +// custom filter handler (no-op) +chart.hasFilterHandler(function(filters, filter) { + return false; +}); +``` + +#### baseMixin.hasFilter ⇒ Boolean +Check whether any active filter or a specific filter is associated with particular chart instance. +This function is **not chainable**. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [hasFilter] | \* | + + +#### baseMixin.removeFilterHandler ⇒ Chart +Set or get the remove filter handler. The remove filter handler is a function that removes a +filter from the chart's current filters. Using a custom remove filter handler allows you to +change how filters are removed or perform additional work when removing a filter, e.g. when +using a filter server other than crossfilter. + +Any changes should modify the `filters` array argument and return that array. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [removeFilterHandler] | function | + +**Example** +```js +// default remove filter handler +function (filters, filter) { + for (var i = 0; i < filters.length; i++) { + if (filters[i] <= filter && filters[i] >= filter) { + filters.splice(i, 1); + break; + } + } + return filters; +} + +// custom filter handler (no-op) +chart.removeFilterHandler(function(filters, filter) { + return filters; +}); +``` + +#### baseMixin.addFilterHandler ⇒ Chart +Set or get the add filter handler. The add filter handler is a function that adds a filter to +the chart's filter list. Using a custom add filter handler allows you to change the way filters +are added or perform additional work when adding a filter, e.g. when using a filter server other +than crossfilter. + +Any changes should modify the `filters` array argument and return that array. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [addFilterHandler] | function | + +**Example** +```js +// default add filter handler +function (filters, filter) { + filters.push(filter); + return filters; +} + +// custom filter handler (no-op) +chart.addFilterHandler(function(filters, filter) { + return filters; +}); +``` + +#### baseMixin.resetFilterHandler ⇒ Chart +Set or get the reset filter handler. The reset filter handler is a function that resets the +chart's filter list by returning a new list. Using a custom reset filter handler allows you to +change the way filters are reset, or perform additional work when resetting the filters, +e.g. when using a filter server other than crossfilter. + +This function should return an array. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [resetFilterHandler] | function | + +**Example** +```js +// default remove filter handler +function (filters) { + return []; +} + +// custom filter handler (no-op) +chart.resetFilterHandler(function(filters) { + return filters; +}); +``` + +#### baseMixin.filter ⇒ Chart +Filter the chart by the given value or return the current filter if the input parameter is missing. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [filterValue] | \* | + +**Example** +```js +// filter by a single string +chart.filter('Sunday'); +// filter by a single age +chart.filter(18); +``` + +#### baseMixin.filters ⇒ Array.<\*> +Returns all current filters. This method does not perform defensive cloning of the internal +filter array before returning, therefore any modification of the returned array will effect the +chart's internal filter storage. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.onClick +This function is passed to d3 as the onClick handler for each chart. The default behavior is to +filter on the clicked datum (passed to the callback) and redraw the chart group. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| datum | \* | + + +#### baseMixin.filterHandler ⇒ Chart +Set or get the filter handler. The filter handler is a function that performs the filter action +on a specific dimension. Using a custom filter handler allows you to perform additional logic +before or after filtering. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| filterHandler | function | + +**Example** +```js +// default filter handler +function(dimension, filter){ + dimension.filter(filter); // perform filtering + return filter; // return the actual filter value +} + +// custom filter handler +chart.filterHandler(function(dimension, filter){ + var newFilter = filter + 10; + dimension.filter(newFilter); + return newFilter; // set the actual filter value to the new value +}); +``` + +#### baseMixin.keyAccessor ⇒ Chart +Set or get the key accessor function. The key accessor function is used to retrieve the key +value from the crossfilter group. Key values are used differently in different charts, for +example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| keyAccessor | function | + +**Example** +```js +// default key accessor +chart.keyAccessor(function(d) { return d.key; }); +// custom key accessor for a multi-value crossfilter reduction +chart.keyAccessor(function(p) { return p.value.absGain; }); +``` + +#### baseMixin.valueAccessor ⇒ Chart +Set or get the value accessor function. The value accessor function is used to retrieve the +value from the crossfilter group. Group values are used differently in different charts, for +example values correspond to slice sizes in a pie chart and y axis positions in a grid +coordinate chart. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| valueAccessor | function | + +**Example** +```js +// default value accessor +chart.valueAccessor(function(d) { return d.value; }); +// custom value accessor for a multi-value crossfilter reduction +chart.valueAccessor(function(p) { return p.value.percentageGain; }); +``` + +#### baseMixin.label ⇒ Chart +Set or get the label function. The chart class will use this function to render labels for each +child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every +chart supports the label function for example bar chart and line chart do not use this function +at all. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| labelFunction | function | + +**Example** +```js +// default label function just return the key +chart.label(function(d) { return d.key; }); +// label function has access to the standard d3 data binding and can get quite complicated +chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; }); +``` + +#### baseMixin.renderLabel ⇒ Boolean +Turn on/off label rendering + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| renderLabel | Boolean | + + +#### baseMixin.title ⇒ function +Set or get the title function. The chart class will use this function to render the svg title +(usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice +in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; +however in grid coordinate charts you need to turn off the brush in order to see titles, because +otherwise the brush layer will block tooltip triggering. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| titleFunction | function | + +**Example** +```js +// default title function just return the key +chart.title(function(d) { return d.key + ': ' + d.value; }); +// title function has access to the standard d3 data binding and can get quite complicated +chart.title(function(p) { + return p.key.getFullYear() + + '\n' + + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n' + + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n' + + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%'; +}); +``` + +#### baseMixin.renderTitle ⇒ Boolean +Turn on/off title rendering, or return the state of the render title flag if no arguments are +given. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| renderTitle | Boolean | + + +#### ~~baseMixin.renderlet ⇒ function~~ +***Deprecated*** + +A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added +to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked +right after the chart finishes its transitions, giving you a way to modify the svg +elements. Renderlet functions take the chart instance as the only input parameter and you can +use the dc API or use raw d3 to achieve pretty much any effect. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| renderletFunction | function | + +**Example** +```js +// do this instead of .renderlet(function(chart) { ... }) +chart.on("renderlet", function(chart){ + // mix of dc API and d3 manipulation + chart.select('g.y').style('display', 'none'); + // its a closure so you can also access other chart variable available in the closure scope + moveChart.filter(chart.filter()); +}); +``` + +#### baseMixin.chartGroup ⇒ String +Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn +together since it is expected they share the same underlying crossfilter data set. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| chartGroup | String | + + +#### baseMixin.expireCache ⇒ Chart +Expire the internal chart cache. dc charts cache some data internally on a per chart basis to +speed up rendering and avoid unnecessary calculation; however it might be useful to clear the +cache if you have changed state which will affect rendering. For example if you invoke the +`crossfilter.add` function or reset group or dimension after rendering it is a good idea to +clear the cache to make sure charts are rendered properly. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.legend ⇒ dc.legend +Attach a dc.legend widget to this chart. The legend widget will automatically draw legend labels +based on the color setting and names associated with each group. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| [legend] | dc.legend | + +**Example** +```js +chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) +``` + +#### baseMixin.chartID ⇒ String +Returns the internal numeric ID of the chart. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +#### baseMixin.options ⇒ Chart +Set chart options using a configuration object. Each key in the object will cause the method of +the same name to be called with the value to set that attribute for the chart. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| opts | Object | + +**Example** +```js +chart.options({dimension: myDimension, group: myGroup}); +``` + +#### baseMixin.on ⇒ Chart +All dc chart instance supports the following listeners. +Supports the following events: +* 'renderlet' - This listener function will be invoked after transitions after redraw and render. Replaces the +deprecated `.renderlet()` method. +* 'pretransition' - Like `.on('renderlet', ...)` but the event is fired before transitions start. +* 'preRender' - This listener function will be invoked before chart rendering. +* 'postRender' - This listener function will be invoked after chart finish rendering including +all renderlets' logic. +* 'preRedraw' - This listener function will be invoked before chart redrawing. +* 'postRedraw' - This listener function will be invoked after chart finish redrawing +including all renderlets' logic. +* 'filtered' - This listener function will be invoked after a filter is applied, added or removed. +* 'zoomed' - This listener function will be invoked after a zoom is triggered. + +**Kind**: instance property of [baseMixin](#dc.baseMixin) + +| Param | Type | +| --- | --- | +| event | String | +| listener | function | + +**Example** +```js +.on('renderlet', function(chart, filter){...}) +.on('pretransition', function(chart, filter){...}) +.on('preRender', function(chart){...}) +.on('postRender', function(chart){...}) +.on('preRedraw', function(chart){...}) +.on('postRedraw', function(chart){...}) +.on('filtered', function(chart, filter){...}) +.on('zoomed', function(chart, filter){...}) +``` ### dc.bubbleMixin ⇒ Chart This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. From 6f1cd638bfb327fab341291addf04c72279901b8 Mon Sep 17 00:00:00 2001 From: Matt Traynham Date: Mon, 17 Aug 2015 00:54:49 -0400 Subject: [PATCH 6/8] Migrated some more sources to jsdoc --- Gruntfile.js | 4 +- src/color-mixin.js | 6 - src/geo-choropleth-chart.js | 143 ++--- src/heatmap.js | 173 ++--- src/legend.js | 110 ++-- src/line-chart.js | 199 +++--- src/margin-mixin.js | 37 +- src/number-display.js | 100 ++- src/pie-chart.js | 161 ++--- src/row-chart.js | 171 ++--- src/scatter-plot.js | 113 ++-- src/series-chart.js | 115 ++-- src/stack-mixin.js | 136 ++-- web/docs/api-latest.md | 1194 ++++++++++++++++++++++++++++++++++- 14 files changed, 1973 insertions(+), 689 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 285a16abf..7b2ebb556 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -186,7 +186,9 @@ module.exports = function (grunt) { jsdoc2md: { dist: { src: ['src/{bar-chart,base-mixin,box-plot,bubble-chart,bubble-mixin,' + - 'bubble-overlay,cap-mixin,color-mixin,core}.js'], + 'bubble-overlay,cap-mixin,color-mixin,core,geo-choropleth-chart,' + + 'heatmap,legend,line-chart,margin-mixin,number-display,pie-chart,row-chart,' + + 'scatter-plot,series-chart,stack-mixin}.js'], dest: 'web/docs/api-latest.md' } }, diff --git a/src/color-mixin.js b/src/color-mixin.js index d9f7dde7a..29ddeb428 100644 --- a/src/color-mixin.js +++ b/src/color-mixin.js @@ -1,9 +1,3 @@ -/** -## Color Mixin -The Color Mixin is an abstract chart functional class providing universal coloring support -as a mix-in for any concrete chart implementation. - -**/ /** * The Color Mixin is an abstract chart functional class providing universal coloring support * as a mix-in for any concrete chart implementation. diff --git a/src/geo-choropleth-chart.js b/src/geo-choropleth-chart.js index 2843d1033..a1d867c0c 100644 --- a/src/geo-choropleth-chart.js +++ b/src/geo-choropleth-chart.js @@ -1,35 +1,24 @@ /** -## Geo Choropleth Chart -Includes: [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map -from GeoJson data. This chart implementation was inspired by [the great d3 choropleth -example](http://bl.ocks.org/4060606). - -Examples: -* [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) -#### dc.geoChoroplethChart(parent[, chartGroup]) -Create a choropleth chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created choropleth chart instance - -```js -// create a choropleth chart under '#us-chart' element using the default global chart group -var chart1 = dc.geoChoroplethChart('#us-chart'); -// create a choropleth chart under '#us-chart2' element using chart group A -var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); -``` - -**/ + * The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map + * from GeoJson data. This chart implementation was inspired by [the great d3 choropleth example](http://bl.ocks.org/4060606). + * Examples: + * - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + * @name geoChoroplethChart + * @memberOf dc + * @mixes colorMixin,baseMixin + * @example + * // create a choropleth chart under '#us-chart' element using the default global chart group + * var chart1 = dc.geoChoroplethChart('#us-chart'); + * // create a choropleth chart under '#us-chart2' element using chart group A + * var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {GeoChoroplethChart} + */ dc.geoChoroplethChart = function (parent, chartGroup) { var _chart = dc.colorMixin(dc.baseMixin({})); @@ -183,25 +172,25 @@ dc.geoChoroplethChart = function (parent, chartGroup) { }; /** - #### .overlayGeoJson(json, name, keyAccessor) - **mandatory** - Use this function to insert a new GeoJson map layer. This function can be invoked multiple times - if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple - layers with the same name the new overlay will override the existing one. - - Parameters: - * json - GeoJson feed - * name - name of the layer - * keyAccessor - accessor function used to extract 'key' from the GeoJson data. The key extracted by - this function should match the keys returned by the crossfilter groups. - - ```js - // insert a layer for rendering US states - chart.overlayGeoJson(statesJson.features, 'state', function(d) { - return d.properties.name; - }); - ``` - - **/ + * **mandatory** + * + * Use this function to insert a new GeoJson map layer. This function can be invoked multiple times + * if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple + * layers with the same name the new overlay will override the existing one. + * @name overlayGeoJson + * @memberOf dc.geoChoroplethChart + * @instance + * @example + * // insert a layer for rendering US states + * chart.overlayGeoJson(statesJson.features, 'state', function(d) { + * return d.properties.name; + * }); + * @param {Object} json - a geojson feed + * @param {String} name - name of the layer + * @param {Function} keyAccessor - accessor function used to extract 'key' from the GeoJson data. The key extracted by + * this function should match the keys returned by the crossfilter groups. + * @returns {Chart} + */ _chart.overlayGeoJson = function (json, name, keyAccessor) { for (var i = 0; i < _geoJsons.length; ++i) { if (_geoJsons[i].name === name) { @@ -215,11 +204,14 @@ dc.geoChoroplethChart = function (parent, chartGroup) { }; /** - #### .projection(projection) - Set custom geo projection function. See the available [d3 geo projection - functions](https://github.com/mbostock/d3/wiki/Geo-Projections). Default value: albersUsa. - - **/ + * Set custom geo projection function. See the available [d3 geo projection + * functions](https://github.com/mbostock/d3/wiki/Geo-Projections). + * @name projection + * @memberOf dc.geoChoroplethChart + * @instance + * @param {d3.projection} [projection=d3.projection.albersUsa()] + * @returns {Chart} + */ _chart.projection = function (projection) { _geoPath.projection(projection); _projectionFlag = true; @@ -227,34 +219,39 @@ dc.geoChoroplethChart = function (parent, chartGroup) { }; /** - #### .geoJsons() - Returns all GeoJson layers currently registered with this chart. The returned array is a - reference to this chart's internal data structure, so any modification to this array will also - modify this chart's internal registration. - - Returns an array of objects containing fields {name, data, accessor} - - **/ + * Returns all GeoJson layers currently registered with this chart. The returned array is a + * reference to this chart's internal data structure, so any modification to this array will also + * modify this chart's internal registration. + * @name geoJsons + * @memberOf dc.geoChoroplethChart + * @instance + * @returns {Array<{name:String, data: Object, accessor: Function}>} + */ _chart.geoJsons = function () { return _geoJsons; }; /** - #### .geoPath() - Returns the [d3.geo.path](https://github.com/mbostock/d3/wiki/Geo-Paths#path) object used to - render the projection and features. Can be useful for figuring out the bounding box of the - feature set and thus a way to calculate scale and translation for the projection. - - **/ + * Returns the [d3.geo.path](https://github.com/mbostock/d3/wiki/Geo-Paths#path) object used to + * render the projection and features. Can be useful for figuring out the bounding box of the + * feature set and thus a way to calculate scale and translation for the projection. + * @name geoPath + * @memberOf dc.geoChoroplethChart + * @instance + * @returns {d3.geo.path} + */ _chart.geoPath = function () { return _geoPath; }; /** - #### .removeGeoJson(name) - Remove a GeoJson layer from this chart by name - - **/ + * Remove a GeoJson layer from this chart by name + * @name removeGeoJson + * @memberOf dc.geoChoroplethChart + * @instance + * @param {String} name + * @returns {Chart} + */ _chart.removeGeoJson = function (name) { var geoJsons = []; diff --git a/src/heatmap.js b/src/heatmap.js index ae33c3b5d..0289e2404 100644 --- a/src/heatmap.js +++ b/src/heatmap.js @@ -1,32 +1,21 @@ /** - ## Heat Map - - Includes: [Color Mixin](#color-mixin), [Margin Mixin](#margin-mixin), [Base Mixin](#base-mixin) - - A heat map is matrix that represents the values of two dimensions of data using colors. - - #### dc.heatMap(parent[, chartGroup]) - Create a heat map instance and attach it to the given parent element. - - Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - - Returns: - A newly created heat map instance - - ```js - // create a heat map under #chart-container1 element using the default global chart group - var heatMap1 = dc.heatMap('#chart-container1'); - // create a heat map under #chart-container2 element using chart group A - var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); - ``` - - **/ + * A heat map is matrix that represents the values of two dimensions of data using colors. + * @name heatMap + * @memberOf dc + * @mixes colorMixin,marginMixin,baseMixin + * @example + * // create a heat map under #chart-container1 element using the default global chart group + * var heatMap1 = dc.heatMap('#chart-container1'); + * // create a heat map under #chart-container2 element using chart group A + * var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {HeatMap} + */ dc.heatMap = function (parent, chartGroup) { var DEFAULT_BORDER_RADIUS = 6.75; @@ -49,15 +38,18 @@ dc.heatMap = function (parent, chartGroup) { return d; }; - /** - #### .colsLabel([labelFunction]) - Set or get the column label function. The chart class uses this function to render - column labels on the X axis. It is passed the column name. - ```js - // the default label function just returns the name - chart.colsLabel(function(d) { return d; }); - ``` - **/ + /** + * Set or get the column label function. The chart class uses this function to render + * column labels on the X axis. It is passed the column name. + * @name colsLabel + * @memberOf dc.heatMap + * @instance + * @example + * // the default label function just returns the name + * chart.colsLabel(function(d) { return d; }); + * @param {Function} [labelFunction=function(d) { return d; }] + * @returns {Chart} + */ _chart.colsLabel = function (_) { if (!arguments.length) { return _colsLabel; @@ -66,15 +58,18 @@ dc.heatMap = function (parent, chartGroup) { return _chart; }; - /** - #### .rowsLabel([labelFunction]) - Set or get the row label function. The chart class uses this function to render - row labels on the Y axis. It is passed the row name. - ```js - // the default label function just returns the name - chart.rowsLabel(function(d) { return d; }); - ``` - **/ + /** + * Set or get the row label function. The chart class uses this function to render + * row labels on the Y axis. It is passed the row name. + * @name rowsLabel + * @memberOf dc.heatMap + * @instance + * @example + * // the default label function just returns the name + * chart.rowsLabel(function(d) { return d; }); + * @param {Function} [labelFunction=function(d) { return d; }] + * @returns {Chart} + */ _chart.rowsLabel = function (_) { if (!arguments.length) { return _rowsLabel; @@ -127,12 +122,15 @@ dc.heatMap = function (parent, chartGroup) { } /** - #### .rows([values]) - Gets or sets the values used to create the rows of the heatmap, as an array. By default, all - the values will be fetched from the data using the value accessor, and they will be sorted in - ascending order. - **/ - + * Gets or sets the values used to create the rows of the heatmap, as an array. By default, all + * the values will be fetched from the data using the value accessor, and they will be sorted in + * ascending order. + * @name rows + * @memberOf dc.heatMap + * @instance + * @param {Array} [rows] + * @returns {Chart} + */ _chart.rows = function (_) { if (arguments.length) { _rows = _; @@ -147,11 +145,15 @@ dc.heatMap = function (parent, chartGroup) { }; /** - #### .cols([keys]) - Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all - the values will be fetched from the data using the key accessor, and they will be sorted in - ascending order. - **/ + * Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all + * the values will be fetched from the data using the key accessor, and they will be sorted in + * ascending order. + * @name cols + * @memberOf dc.heatMap + * @instance + * @param {Array} [cols] + * @returns {Chart} + */ _chart.cols = function (_) { if (arguments.length) { _cols = _; @@ -262,11 +264,16 @@ dc.heatMap = function (parent, chartGroup) { } return _chart; }; + /** - #### .boxOnClick([handler]) - Gets or sets the handler that fires when an individual cell is clicked in the heatmap. - By default, filtering of the cell will be toggled. - **/ + * Gets or sets the handler that fires when an individual cell is clicked in the heatmap. + * By default, filtering of the cell will be toggled. + * @name boxOnClick + * @memberOf dc.heatMap + * @instance + * @param {Function} [handler] + * @returns {Chart} + */ _chart.boxOnClick = function (f) { if (!arguments.length) { return _boxOnClick; @@ -276,11 +283,15 @@ dc.heatMap = function (parent, chartGroup) { }; /** - #### .xAxisOnClick([handler]) - Gets or sets the handler that fires when a column tick is clicked in the x axis. - By default, if any cells in the column are unselected, the whole column will be selected, - otherwise the whole column will be unselected. - **/ + * Gets or sets the handler that fires when a column tick is clicked in the x axis. + * By default, if any cells in the column are unselected, the whole column will be selected, + * otherwise the whole column will be unselected. + * @name xAxisOnClick + * @memberOf dc.heatMap + * @instance + * @param {Function} [handler] + * @returns {Chart} + */ _chart.xAxisOnClick = function (f) { if (!arguments.length) { return _xAxisOnClick; @@ -290,11 +301,15 @@ dc.heatMap = function (parent, chartGroup) { }; /** - #### .yAxisOnClick([handler]) - Gets or sets the handler that fires when a row tick is clicked in the y axis. - By default, if any cells in the row are unselected, the whole row will be selected, - otherwise the whole row will be unselected. - **/ + * Gets or sets the handler that fires when a row tick is clicked in the y axis. + * By default, if any cells in the row are unselected, the whole row will be selected, + * otherwise the whole row will be unselected. + * @name yAxisOnClick + * @memberOf dc.heatMap + * @instance + * @param {Function} [handler] + * @returns {Chart} + */ _chart.yAxisOnClick = function (f) { if (!arguments.length) { return _yAxisOnClick; @@ -304,8 +319,12 @@ dc.heatMap = function (parent, chartGroup) { }; /** - #### .xBorderRadius([value]) - Gets or sets the X border radius. Set to 0 to get full rectangles. Default: 6.75 + * Gets or sets the X border radius. Set to 0 to get full rectangles. + * @name xBorderRadius + * @memberOf dc.heatMap + * @instance + * @param {Number} [xBorderRadius=6.75] + * @returns {Chart} */ _chart.xBorderRadius = function (d) { if (!arguments.length) { @@ -316,8 +335,12 @@ dc.heatMap = function (parent, chartGroup) { }; /** - #### .xBorderRadius([value]) - Gets or sets the Y border radius. Set to 0 to get full rectangles. Default: 6.75 + * Gets or sets the Y border radius. Set to 0 to get full rectangles. + * @name yBorderRadius + * @memberOf dc.heatMap + * @instance + * @param {Number} [yBorderRadius=6.75] + * @returns {Chart} */ _chart.yBorderRadius = function (d) { if (!arguments.length) { diff --git a/src/legend.js b/src/legend.js index ab60dd992..26d691302 100644 --- a/src/legend.js +++ b/src/legend.js @@ -1,17 +1,15 @@ /** -## Legend -Legend is a attachable widget that can be added to other dc charts to render horizontal legend -labels. - -```js -chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) -``` - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) - -**/ + * Legend is a attachable widget that can be added to other dc charts to render horizontal legend + * labels. + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + * @name legend + * @memberOf dc + * @example + * chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) + * @returns {Legend} + */ dc.legend = function () { var LABEL_GAP = 2; @@ -112,11 +110,15 @@ dc.legend = function () { function legendItemHeight() { return _gap + _itemHeight; } - + /** - #### .x([value]) - Set or get x coordinate for legend widget. Default: 0. - **/ + * Set or get x coordinate for legend widget. + * @name x + * @memberOf dc.legend + * @instance + * @param {Number} [x=0] + * @returns {Legend} + */ _legend.x = function (x) { if (!arguments.length) { return _x; @@ -124,11 +126,15 @@ dc.legend = function () { _x = x; return _legend; }; - + /** - #### .y([value]) - Set or get y coordinate for legend widget. Default: 0. - **/ + * Set or get y coordinate for legend widget. + * @name y + * @memberOf dc.legend + * @instance + * @param {Number} [y=0] + * @returns {Legend} + */ _legend.y = function (y) { if (!arguments.length) { return _y; @@ -138,9 +144,13 @@ dc.legend = function () { }; /** - #### .gap([value]) - Set or get gap between legend items. Default: 5. - **/ + * Set or get gap between legend items. + * @name gap + * @memberOf dc.legend + * @instance + * @param {Number} [gap=5] + * @returns {Legend} + */ _legend.gap = function (gap) { if (!arguments.length) { return _gap; @@ -150,9 +160,13 @@ dc.legend = function () { }; /** - #### .itemHeight([value]) - Set or get legend item height. Default: 12. - **/ + * Set or get legend item height. + * @name itemHeight + * @memberOf dc.legend + * @instance + * @param {Number} [itemHeight=12] + * @returns {Legend} + */ _legend.itemHeight = function (h) { if (!arguments.length) { return _itemHeight; @@ -162,9 +176,13 @@ dc.legend = function () { }; /** - #### .horizontal([boolean]) - Position legend horizontally instead of vertically - **/ + * Position legend horizontally instead of vertically. + * @name horizontal + * @memberOf dc.legend + * @instance + * @param {Boolean} [horizontal] + * @returns {Legend} + */ _legend.horizontal = function (_) { if (!arguments.length) { return _horizontal; @@ -174,9 +192,13 @@ dc.legend = function () { }; /** - #### .legendWidth([value]) - Maximum width for horizontal legend. Default: 560. - **/ + * Maximum width for horizontal legend. + * @name legendWidth + * @memberOf dc.legend + * @instance + * @param {Number} [legendWidth=500] + * @returns {Legend} + */ _legend.legendWidth = function (_) { if (!arguments.length) { return _legendWidth; @@ -186,9 +208,13 @@ dc.legend = function () { }; /** - #### .itemWidth([value]) - legendItem width for horizontal legend. Default: 70. - **/ + * legendItem width for horizontal legend. + * @name itemWidth + * @memberOf dc.legend + * @instance + * @param {Number} [itemWidth=70] + * @returns {Legend} + */ _legend.itemWidth = function (_) { if (!arguments.length) { return _itemWidth; @@ -198,10 +224,14 @@ dc.legend = function () { }; /** - #### .autoItemWidth([value]) - Turn automatic width for legend items on or off. If true, itemWidth() is ignored. - This setting takes into account gap(). Default: false. - **/ + * Turn automatic width for legend items on or off. If true, itemWidth() is ignored. + * This setting takes into account gap(). + * @name autoItemWidth + * @memberOf dc.legend + * @instance + * @param {Boolean} [autoItemWidth=false] + * @returns {Legend} + */ _legend.autoItemWidth = function (_) { if (!arguments.length) { return _autoItemWidth; diff --git a/src/line-chart.js b/src/line-chart.js index 1c1965171..4e8cc103e 100644 --- a/src/line-chart.js +++ b/src/line-chart.js @@ -1,39 +1,26 @@ /** -## Line Chart -Includes [Stack Mixin](#stack-mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Concrete line/area chart implementation. - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) -#### dc.lineChart(parent[, chartGroup]) -Create a line chart instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection | compositeChart - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - If the line chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite - chart instance. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created line chart instance - -```js -// create a line chart under #chart-container1 element using the default global chart group -var chart1 = dc.lineChart('#chart-container1'); -// create a line chart under #chart-container2 element using chart group A -var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.lineChart(compositeChart); -``` - -**/ + * Concrete line/area chart implementation. + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + * @name lineChart + * @memberOf dc + * @mixes stackMixin,coordinateGridMixin + * @example + * // create a line chart under #chart-container1 element using the default global chart group + * var chart1 = dc.lineChart('#chart-container1'); + * // create a line chart under #chart-container2 element using chart group A + * var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); + * // create a sub-chart under a composite parent chart + * var chart3 = dc.lineChart(compositeChart); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {LineChart} + */ dc.lineChart = function (parent, chartGroup) { var DEFAULT_DOT_RADIUS = 5; var TOOLTIP_G_CLASS = 'dc-tooltip'; @@ -82,13 +69,17 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .interpolate([value]) - Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step - functions, splines, and cubic interpolation. This is passed to - [d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and - [d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), - where you can find a complete list of valid arguments - **/ + * Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step + * functions, splines, and cubic interpolation. This is passed to + * [d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and + * [d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), + * where you can find a complete list of valid arguments + * @name interpolate + * @memberOf dc.lineChart + * @instance + * @param {String} [interpolate] + * @returns {Chart} + */ _chart.interpolate = function (_) { if (!arguments.length) { return _interpolate; @@ -98,13 +89,16 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .tension([value]) - Gets or sets the tension to use for lines drawn, in the range 0 to 1. - This parameter further customizes the interpolation behavior. It is passed to - [d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and - [d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). Default: - 0.7 - **/ + * Gets or sets the tension to use for lines drawn, in the range 0 to 1. + * This parameter further customizes the interpolation behavior. It is passed to + * [d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and + * [d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). + * @name tension + * @memberOf dc.lineChart + * @instance + * @param {Number} [tension=0.7] + * @returns {Chart} + */ _chart.tension = function (_) { if (!arguments.length) { return _tension; @@ -114,16 +108,20 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .defined([value]) - Gets or sets a function that will determine discontinuities in the line which should be - skipped: the path will be broken into separate subpaths if some points are undefined. - This function is passed to - [d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) - - Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write - custom reduce functions to get this to work, depending on your data. See - https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 - **/ + * Gets or sets a function that will determine discontinuities in the line which should be + * skipped: the path will be broken into separate subpaths if some points are undefined. + * This function is passed to + * [d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) + * + * Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write + * custom reduce functions to get this to work, depending on your data. See + * https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 + * @name defined + * @memberOf dc.lineChart + * @instance + * @param {Function} [defined] + * @returns {Chart} + */ _chart.defined = function (_) { if (!arguments.length) { return _defined; @@ -133,14 +131,17 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .dashStyle([array]) - Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty - array (solid line). - ```js - // create a Dash Dot Dot Dot - chart.dashStyle([3,1,1,1]); - ``` - **/ + * Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty + * array (solid line). + * @name dashStyle + * @memberOf dc.lineChart + * @instance + * @example + * // create a Dash Dot Dot Dot + * chart.dashStyle([3,1,1,1]); + * @param {Array} [dashStyle=[]] + * @returns {Chart} + */ _chart.dashStyle = function (_) { if (!arguments.length) { return _dashStyle; @@ -150,11 +151,14 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .renderArea([boolean]) - Get or set render area flag. If the flag is set to true then the chart will render the area - beneath each line and the line chart effectively becomes an area chart. - - **/ + * Get or set render area flag. If the flag is set to true then the chart will render the area + * beneath each line and the line chart effectively becomes an area chart. + * @name renderArea + * @memberOf dc.lineChart + * @instance + * @param {Boolean} [renderArea=false] + * @returns {Chart} + */ _chart.renderArea = function (_) { if (!arguments.length) { return _renderArea; @@ -341,10 +345,13 @@ dc.lineChart = function (parent, chartGroup) { } /** - #### .xyTipsOn([boolean]) - Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis - dashed lines back to each respective axis. This is ignored if the chart brush is on (`brushOn`) - Default: true + * Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis + * dashed lines back to each respective axis. This is ignored if the chart brush is on (`brushOn`) + * @name xyTipsOn + * @memberOf dc.lineChart + * @instance + * @param {Boolean} [xyTipsOn=false] + * @returns {Chart} */ _chart.xyTipsOn = function (_) { if (!arguments.length) { @@ -355,9 +362,13 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .dotRadius([dotRadius]) - Get or set the radius (in px) for dots displayed on the data points. Default dot radius is 5. - **/ + * Get or set the radius (in px) for dots displayed on the data points. + * @name dotRadius + * @memberOf dc.lineChart + * @instance + * @param {Number} [dotRadius=5] + * @returns {Chart} + */ _chart.dotRadius = function (_) { if (!arguments.length) { return _dotRadius; @@ -367,24 +378,18 @@ dc.lineChart = function (parent, chartGroup) { }; /** - #### .renderDataPoints([options]) - Always show individual dots for each datapoint. - - Options, if given, is an object that can contain the following: - - * fillOpacity (default 0.8) - * strokeOpacity (default 0.8) - * radius (default 2) - - If `options` is falsy, it disables data point rendering. - - If no `options` are provided, the current `options` values are instead returned. - - Example: - ``` - chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) - ``` - **/ + * Always show individual dots for each datapoint. + * If `options` is falsy, it disables data point rendering. + * + * If no `options` are provided, the current `options` values are instead returned. + * @name renderDataPoints + * @memberOf dc.lineChart + * @instance + * @example + * chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) + * @param {{fillOpacity: Number, strokeOpacity: Number, radius: Number}} [options={fillOpacity: 0.8, strokeOpacity: 0.8, radius: 2}] + * @returns {Chart} + */ _chart.renderDataPoints = function (options) { if (!arguments.length) { return { diff --git a/src/margin-mixin.js b/src/margin-mixin.js index cf77dd682..71a17cae1 100644 --- a/src/margin-mixin.js +++ b/src/margin-mixin.js @@ -1,25 +1,28 @@ /** -## Margin Mixin -Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid -Charts. - -**/ + * Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid + * Charts. + * @name marginMixin + * @memberOf dc + * @mixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.marginMixin = function (_chart) { var _margin = {top: 10, right: 50, bottom: 30, left: 30}; /** - #### .margins([margins]) - Get or set the margins for a particular coordinate grid chart instance. The margins is stored as - an associative Javascript array. Default margins: {top: 10, right: 50, bottom: 30, left: 30}. - - The margins can be accessed directly from the getter. - ```js - var leftMargin = chart.margins().left; // 30 by default - chart.margins().left = 50; - leftMargin = chart.margins().left; // now 50 - ``` - - **/ + * Get or set the margins for a particular coordinate grid chart instance. The margins is stored as + * an associative Javascript array. + * @name margins + * @memberOf dc.marginMixin + * @instance + * @example + * var leftMargin = chart.margins().left; // 30 by default + * chart.margins().left = 50; + * leftMargin = chart.margins().left; // now 50 + * @param {{top:Number, right: Number, left: Number, bottom: Number}} [margins={top: 10, right: 50, bottom: 30, left: 30}] + * @returns {Chart} + */ _chart.margins = function (m) { if (!arguments.length) { return _margin; diff --git a/src/number-display.js b/src/number-display.js index cb2046e57..7072af6ac 100644 --- a/src/number-display.js +++ b/src/number-display.js @@ -1,35 +1,21 @@ /** -## Number Display Widget -Includes: [Base Mixin](#base-mixin) - -A display of a single numeric value. - -Examples: - -* [Test Example](http://dc-js.github.io/dc.js/examples/number.html) -#### dc.numberDisplay(parent[, chartGroup]) -Create a Number Display instance and attach it to the given parent element. - -Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and -a valueAccessor that returns a single value. - -Parameters: - -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - The number display widget will only react to filter changes in the chart group. - -Returns: -A newly created number display instance - -```js -// create a number display under #chart-container1 element using the default global chart group -var display1 = dc.numberDisplay('#chart-container1'); -``` - -**/ + * A display of a single numeric value. + * Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and + * a valueAccessor that returns a single value. + * @name numberDisplay + * @memberOf dc + * @mixes baseMixin + * @example + * // create a number display under #chart-container1 element using the default global chart group + * var display1 = dc.numberDisplay('#chart-container1'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {NumberDisplay} + */ dc.numberDisplay = function (parent, chartGroup) { var SPAN_CLASS = 'number-display'; var _formatNumber = d3.format('.2s'); @@ -40,21 +26,22 @@ dc.numberDisplay = function (parent, chartGroup) { _chart._mandatoryAttributes(['group']); /** - #### .html([object]) - Gets or sets an optional object specifying HTML templates to use depending on the number - displayed. The text `%number` will be replaced with the current value. - - one: HTML template to use if the number is 1 - - zero: HTML template to use if the number is 0 - - some: HTML template to use otherwise - - ```js - numberWidget.html({ - one:'%number record', - some:'%number records', - none:'no records'}) - ``` - **/ - + * Gets or sets an optional object specifying HTML templates to use depending on the number + * displayed. The text `%number` will be replaced with the current value. + * - one: HTML template to use if the number is 1 + * - zero: HTML template to use if the number is 0 + * - some: HTML template to use otherwise + * @name html + * @memberOf dc.numberDisplay + * @instance + * @example + * numberWidget.html({ + * one:'%number record', + * some:'%number records', + * none:'no records'}) + * @param {Object} [externalRadiusPadding=0] + * @returns {Chart} + */ _chart.html = function (s) { if (!arguments.length) { return _html; @@ -80,10 +67,12 @@ dc.numberDisplay = function (parent, chartGroup) { }; /** - #### .value() - Calculate and return the underlying value of the display - **/ - + * Calculate and return the underlying value of the display + * @name value + * @memberOf dc.numberDisplay + * @instance + * @returns {Number} + */ _chart.value = function () { return _chart.data(); }; @@ -131,10 +120,13 @@ dc.numberDisplay = function (parent, chartGroup) { }; /** - #### .formatNumber([formatter]) - Get or set a function to format the value for the display. By default `d3.format('.2s');` is used. - - **/ + * Get or set a function to format the value for the display. + * @name formatNumber + * @memberOf dc.numberDisplay + * @instance + * @param {Function} [formatter=d3.format('.2s')] + * @returns {Chart} + */ _chart.formatNumber = function (_) { if (!arguments.length) { return _formatNumber; diff --git a/src/pie-chart.js b/src/pie-chart.js index 7fad66c1b..d7e427285 100644 --- a/src/pie-chart.js +++ b/src/pie-chart.js @@ -1,38 +1,24 @@ /** -## Pie Chart -Includes: [Cap Mixin](#cap-mixin), [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -The pie chart implementation is usually used to visualize a small categorical distribution. The pie -chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each -slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting -by key. - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.pieChart(parent[, chartGroup]) -Create a pie chart instance and attaches it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created pie chart instance - -```js -// create a pie chart under #chart-container1 element using the default global chart group -var chart1 = dc.pieChart('#chart-container1'); -// create a pie chart under #chart-container2 element using chart group A -var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); -``` - -**/ + * The pie chart implementation is usually used to visualize a small categorical distribution. The pie + * chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each + * slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting + * by key. + * @name pieChart + * @memberOf dc + * @mixes capMixin,colorMixin,baseMixin + * @example + * // create a pie chart under #chart-container1 element using the default global chart group + * var chart1 = dc.pieChart('#chart-container1'); + * // create a pie chart under #chart-container2 element using chart group A + * var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {PieChart} + */ dc.pieChart = function (parent, chartGroup) { var DEFAULT_MIN_ANGLE_FOR_LABEL = 0.5; @@ -59,12 +45,14 @@ dc.pieChart = function (parent, chartGroup) { }); /** - #### .slicesCap([cap]) - Get or set the maximum number of slices the pie chart will generate. The top slices are determined by - value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. - The resulting data will still be sorted by .ordering (default by key). - - **/ + * Get or set the maximum number of slices the pie chart will generate. The top slices are determined by + * value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. + * @name slicesCap + * @memberOf dc.pieChart + * @instance + * @param {Number} [cap] + * @returns {Chart} + */ _chart.slicesCap = _chart.cap; _chart.label(_chart.cappedKeyAccessor); @@ -257,11 +245,14 @@ dc.pieChart = function (parent, chartGroup) { } /** - #### .externalRadiusPadding([externalRadiusPadding]) - Get or set the external radius padding of the pie chart. This will force the radius of the - pie chart to become smaller or larger depending on the value. Default external radius padding is 0px. - - **/ + * Get or set the external radius padding of the pie chart. This will force the radius of the + * pie chart to become smaller or larger depending on the value. + * @name externalRadiusPadding + * @memberOf dc.pieChart + * @instance + * @param {Number} [externalRadiusPadding=0] + * @returns {Chart} + */ _chart.externalRadiusPadding = function (_) { if (!arguments.length) { return _externalRadiusPadding; @@ -271,11 +262,14 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .innerRadius([innerRadius]) - Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the - pie chart will be rendered as a doughnut chart. Default inner radius is 0px. - - **/ + * Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the + * pie chart will be rendered as a doughnut chart. + * @name innerRadius + * @memberOf dc.pieChart + * @instance + * @param {Number} [innerRadius=0] + * @returns {Chart} + */ _chart.innerRadius = function (r) { if (!arguments.length) { return _innerRadius; @@ -285,11 +279,14 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .radius([radius]) - Get or set the outer radius. If the radius is not set, it will be half of the minimum of the - chart width and height. - - **/ + * Get or set the outer radius. If the radius is not set, it will be half of the minimum of the + * chart width and height. + * @name radius + * @memberOf dc.pieChart + * @instance + * @param {Number} [radius] + * @returns {Chart} + */ _chart.radius = function (r) { if (!arguments.length) { return _givenRadius; @@ -299,10 +296,13 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .cx([cx]) - Get or set center x coordinate position. Default is center of svg. - - **/ + * Get or set center x coordinate position. Default is center of svg. + * @name cx + * @memberOf dc.pieChart + * @instance + * @param {Number} [cx] + * @returns {Chart} + */ _chart.cx = function (cx) { if (!arguments.length) { return (_cx || _chart.width() / 2); @@ -312,10 +312,13 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .cy([cy]) - Get or set center y coordinate position. Default is center of svg. - - **/ + * Get or set center y coordinate position. Default is center of svg. + * @name cy + * @memberOf dc.pieChart + * @instance + * @param {Number} [cy] + * @returns {Chart} + */ _chart.cy = function (cy) { if (!arguments.length) { return (_cy || _chart.height() / 2); @@ -338,10 +341,14 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .minAngleForLabel([minAngle]) - Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not - display a slice label. Default min angle is 0.5. - **/ + * Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not + * display a slice label. + * @name minAngleForLabel + * @memberOf dc.pieChart + * @instance + * @param {Number} [minAngleForLabel=0.5] + * @returns {Chart} + */ _chart.minAngleForLabel = function (_) { if (!arguments.length) { return _minAngleForLabel; @@ -399,8 +406,12 @@ dc.pieChart = function (parent, chartGroup) { } /** - #### .emptyTitle([title]) - Title to use for the only slice when there is no data + * Title to use for the only slice when there is no data. + * @name emptyTitle + * @memberOf dc.pieChart + * @instance + * @param {String} [title] + * @returns {Chart} */ _chart.emptyTitle = function (title) { if (arguments.length === 0) { @@ -411,10 +422,14 @@ dc.pieChart = function (parent, chartGroup) { }; /** - #### .externalLabels([radius]) - Position slice labels offset from the outer edge of the chart - - The given argument sets the radial offset. + * Position slice labels offset from the outer edge of the chart + * + * The given argument sets the radial offset. + * @name externalLabels + * @memberOf dc.pieChart + * @instance + * @param {Number} [radius] + * @returns {Chart} */ _chart.externalLabels = function (radius) { if (arguments.length === 0) { diff --git a/src/row-chart.js b/src/row-chart.js index d7a16decc..38ad316af 100644 --- a/src/row-chart.js +++ b/src/row-chart.js @@ -1,31 +1,21 @@ /** -## Row Chart -Includes: [Cap Mixin](#cap-mixin), [Margin Mixin](#margin-mixin), [Color Mixin](#color-mixin), [Base Mixin](#base-mixin) - -Concrete row chart implementation. -#### dc.rowChart(parent[, chartGroup]) -Create a row chart instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created row chart instance - -```js -// create a row chart under #chart-container1 element using the default global chart group -var chart1 = dc.rowChart('#chart-container1'); -// create a row chart under #chart-container2 element using chart group A -var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); -``` - -**/ + * Concrete row chart implementation. + * @name rowChart + * @memberOf dc + * @mixes capMixin,marginMixin,colorMixin,baseMixin + * @example + * // create a row chart under #chart-container1 element using the default global chart group + * var chart1 = dc.rowChart('#chart-container1'); + * // create a row chart under #chart-container2 element using chart group A + * var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {RowChart} + */ dc.rowChart = function (parent, chartGroup) { var _g; @@ -100,10 +90,14 @@ dc.rowChart = function (parent, chartGroup) { _chart.label(_chart.cappedKeyAccessor); /** - #### .x([scale]) - Gets or sets the x scale. The x scale can be any d3 - [quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) - **/ + * Gets or sets the x scale. The x scale can be any d3 + * [quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) + * @name x + * @memberOf dc.rowChart + * @instance + * @param {d3.scale} [scale] + * @returns {Chart} + */ _chart.x = function (x) { if (!arguments.length) { return _x; @@ -255,10 +249,13 @@ dc.rowChart = function (parent, chartGroup) { } /** - #### .renderTitleLabel(boolean) - Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' - - **/ + * Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' + * @name renderTitleLabel + * @memberOf dc.rowChart + * @instance + * @param {Boolean} [renderTitleLabel] + * @returns {Chart} + */ _chart.renderTitleLabel = function (_) { if (!arguments.length) { return _renderTitleLabel; @@ -284,31 +281,35 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .xAxis() - Get the x axis for the row chart instance. Note: not settable for row charts. - See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. - ```js - // customize x axis tick format - chart.xAxis().tickFormat(function (v) {return v + '%';}); - // customize x axis tick values - chart.xAxis().tickValues([0, 100, 200, 300]); - ``` - - **/ + * Get the x axis for the row chart instance. Note: not settable for row charts. + * See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. + * @name xAxis + * @memberOf dc.rowChart + * @instance + * @example + * // customize x axis tick format + * chart.xAxis().tickFormat(function (v) {return v + '%';}); + * // customize x axis tick values + * chart.xAxis().tickValues([0, 100, 200, 300]); + * @returns {d3.svg.Axis} + */ _chart.xAxis = function () { return _xAxis; }; /** - #### .fixedBarHeight([height]) - Get or set the fixed bar height. Default is [false] which will auto-scale bars. - For example, if you want to fix the height for a specific number of bars (useful in TopN charts) - you could fix height as follows (where count = total number of bars in your TopN and gap is - your vertical gap space). - ```js - chart.fixedBarHeight( chartheight - (count + 1) * gap / count); - ``` - **/ + * Get or set the fixed bar height. Default is [false] which will auto-scale bars. + * For example, if you want to fix the height for a specific number of bars (useful in TopN charts) + * you could fix height as follows (where count = total number of bars in your TopN and gap is + * your vertical gap space). + * @name fixedBarHeight + * @memberOf dc.rowChart + * @instance + * @example + * chart.fixedBarHeight( chartheight - (count + 1) * gap / count); + * @param {Number} [height] + * @returns {Chart} + */ _chart.fixedBarHeight = function (g) { if (!arguments.length) { return _fixedBarHeight; @@ -318,10 +319,13 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .gap([gap]) - Get or set the vertical gap space between rows on a particular row chart instance. Default gap is 5px; - - **/ + * Get or set the vertical gap space between rows on a particular row chart instance + * @name gap + * @memberOf dc.rowChart + * @instance + * @param {Number} [gap=5] + * @returns {Chart} + */ _chart.gap = function (g) { if (!arguments.length) { return _gap; @@ -331,11 +335,14 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .elasticX([boolean]) - Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the - data range when filtered. - - **/ + * Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the + * data range when filtered. + * @name elasticX + * @memberOf dc.rowChart + * @instance + * @param {Boolean} [elasticX] + * @returns {Chart} + */ _chart.elasticX = function (_) { if (!arguments.length) { return _elasticX; @@ -345,11 +352,13 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .labelOffsetX([x]) - Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. - Default x offset is 10px; - - **/ + * Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. + * @name labelOffsetX + * @memberOf dc.rowChart + * @instance + * @param {Number} [labelOffsetX=10] + * @returns {Chart} + */ _chart.labelOffsetX = function (o) { if (!arguments.length) { return _labelOffsetX; @@ -359,11 +368,13 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .labelOffsetY([y]) - Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. - Default y offset is 15px; - - **/ + * Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. + * @name labelOffsetY + * @memberOf dc.rowChart + * @instance + * @param {Number} [labelOffsety=15] + * @returns {Chart} + */ _chart.labelOffsetY = function (o) { if (!arguments.length) { return _labelOffsetY; @@ -374,11 +385,13 @@ dc.rowChart = function (parent, chartGroup) { }; /** - #### .titleLabelOffsetx([x]) - Get of set the x offset (horizontal space between right edge of row and right edge or text. - Default x offset is 2px; - - **/ + * Get of set the x offset (horizontal space between right edge of row and right edge or text. + * @name titleLabelOffsetX + * @memberOf dc.rowChart + * @instance + * @param {Number} [x=2] + * @returns {Chart} + */ _chart.titleLabelOffsetX = function (o) { if (!arguments.length) { return _titleLabelOffsetX; diff --git a/src/scatter-plot.js b/src/scatter-plot.js index 55aaf04aa..6eda5852b 100644 --- a/src/scatter-plot.js +++ b/src/scatter-plot.js @@ -1,35 +1,23 @@ /** -## Scatter Plot -Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - -A scatter plot chart -#### dc.scatterPlot(parent[, chartGroup]) -Create a scatter plot instance and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection | compositeChart - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - If the scatter plot is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite - chart instance. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created scatter plot instance - -```js -// create a scatter plot under #chart-container1 element using the default global chart group -var chart1 = dc.scatterPlot('#chart-container1'); -// create a scatter plot under #chart-container2 element using chart group A -var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.scatterPlot(compositeChart); -``` - - **/ + * A scatter plot chart + * @name scatterPlot + * @memberOf dc + * @mixes coordinateGridMixin + * @example + * // create a scatter plot under #chart-container1 element using the default global chart group + * var chart1 = dc.scatterPlot('#chart-container1'); + * // create a scatter plot under #chart-container2 element using chart group A + * var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); + * // create a sub-chart under a composite parent chart + * var chart3 = dc.scatterPlot(compositeChart); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {SeriesChart} + */ dc.scatterPlot = function (parent, chartGroup) { var _chart = dc.coordinateGridMixin({}); var _symbol = d3.svg.symbol(); @@ -91,12 +79,15 @@ dc.scatterPlot = function (parent, chartGroup) { }; /** - #### .existenceAccessor([accessor]) - Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and - opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, - the existence accessor checks if the reduced value is truthy. - **/ - + * Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and + * opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, + * the existence accessor checks if the reduced value is truthy. + * @name existenceAccessor + * @memberOf dc.scatterPlot + * @instance + * @param {Function} [accessor] + * @returns {Chart} + */ _chart.existenceAccessor = function (acc) { if (!arguments.length) { return _existenceAccessor; @@ -106,12 +97,15 @@ dc.scatterPlot = function (parent, chartGroup) { }; /** - #### .symbol([type]) - Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 - [docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. - Type can be a constant or an accessor. - - **/ + * Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 + * [docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. + * Type can be a constant or an accessor. + * @name symbol + * @memberOf dc.scatterPlot + * @instance + * @param {Function} [type] + * @returns {Chart} + */ _chart.symbol = function (type) { if (!arguments.length) { return _symbol.type(); @@ -121,10 +115,13 @@ dc.scatterPlot = function (parent, chartGroup) { }; /** - #### .symbolSize([radius]) - Set or get radius for symbols. Default: 3. - - **/ + * Set or get radius for symbols. + * @name symbolSize + * @memberOf dc.scatterPlot + * @instance + * @param {Number} [radius=3] + * @returns {Chart} + */ _chart.symbolSize = function (s) { if (!arguments.length) { return _symbolSize; @@ -134,10 +131,13 @@ dc.scatterPlot = function (parent, chartGroup) { }; /** - #### .highlightedSize([radius]) - Set or get radius for highlighted symbols. Default: 4. - - **/ + * Set or get radius for highlighted symbols. + * @name highlightedSize + * @memberOf dc.scatterPlot + * @instance + * @param {Number} [radius=4] + * @returns {Chart} + */ _chart.highlightedSize = function (s) { if (!arguments.length) { return _highlightedSize; @@ -147,10 +147,13 @@ dc.scatterPlot = function (parent, chartGroup) { }; /** - #### .hiddenSize([radius]) - Set or get radius for symbols when the group is empty. Default: 0. - - **/ + * Set or get radius for symbols when the group is empty. + * @name hiddenSize + * @memberOf dc.scatterPlot + * @instance + * @param {Number} [radius=0] + * @returns {Chart} + */ _chart.hiddenSize = function (s) { if (!arguments.length) { return _hiddenSize; diff --git a/src/series-chart.js b/src/series-chart.js index 244eaf349..4a05beeb4 100644 --- a/src/series-chart.js +++ b/src/series-chart.js @@ -1,34 +1,23 @@ /** - ## Series Chart - - Includes: [Composite Chart](#composite chart) - - A series chart is a chart that shows multiple series of data overlaid on one chart, where the - series is specified in the data. It is a specialization of Composite Chart and inherits all - composite features other than recomposing the chart. - - #### dc.seriesChart(parent[, chartGroup]) - Create a series chart instance and attach it to the given parent element. - - Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - - Returns: - A newly created series chart instance - - ```js - // create a series chart under #chart-container1 element using the default global chart group - var seriesChart1 = dc.seriesChart("#chart-container1"); - // create a series chart under #chart-container2 element using chart group A - var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); - ``` - - **/ + * A series chart is a chart that shows multiple series of data overlaid on one chart, where the + * series is specified in the data. It is a specialization of Composite Chart and inherits all + * composite features other than recomposing the chart. + * @name seriesChart + * @memberOf dc + * @mixes compositeChart + * @example + * // create a series chart under #chart-container1 element using the default global chart group + * var seriesChart1 = dc.seriesChart("#chart-container1"); + * // create a series chart under #chart-container2 element using chart group A + * var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {SeriesChart} + */ dc.seriesChart = function (parent, chartGroup) { var _chart = dc.compositeChart(parent, chartGroup); @@ -98,17 +87,18 @@ dc.seriesChart = function (parent, chartGroup) { } /** - #### .chart([function]) - Get or set the chart function, which generates the child charts. Default: dc.lineChart - - ``` - // put interpolation on the line charts used for the series - chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) - // do a scatter series chart - chart.chart(dc.scatterPlot) - ``` - - **/ + * Get or set the chart function, which generates the child charts. + * @name chart + * @memberOf dc.seriesChart + * @instance + * @example + * // put interpolation on the line charts used for the series + * chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) + * // do a scatter series chart + * chart.chart(dc.scatterPlot) + * @param {Function} chartFunction=dc.lineChart + * @returns {Chart} + */ _chart.chart = function (_) { if (!arguments.length) { return _chartFunction; @@ -119,10 +109,14 @@ dc.seriesChart = function (parent, chartGroup) { }; /** - #### .seriesAccessor([accessor]) - Get or set accessor function for the displayed series. Given a datum, this function - should return the series that datum belongs to. - **/ + * Get or set accessor function for the displayed series. Given a datum, this function + * should return the series that datum belongs to. + * @name seriesAccessor + * @memberOf dc.seriesChart + * @instance + * @param {Function} [accessor] + * @returns {Chart} + */ _chart.seriesAccessor = function (_) { if (!arguments.length) { return _seriesAccessor; @@ -133,14 +127,15 @@ dc.seriesChart = function (parent, chartGroup) { }; /** - #### .seriesSort([sortFunction]) - Get or set a function to sort the list of series by, given series values. - - Example: - ``` - chart.seriesSort(d3.descending); - ``` - **/ + * Get or set a function to sort the list of series by, given series values. + * @name seriesSort + * @memberOf dc.seriesChart + * @instance + * @example + * chart.seriesSort(d3.descending); + * @param {Function} [sortFunction] + * @returns {Chart} + */ _chart.seriesSort = function (_) { if (!arguments.length) { return _seriesSort; @@ -151,11 +146,15 @@ dc.seriesChart = function (parent, chartGroup) { }; /** - #### .valueSort([sortFunction]) - Get or set a function to sort each series values by. By default this is the key accessor which, - for example, will ensure a lineChart series connects its points in increasing key/x order, - rather than haphazardly. - **/ + * Get or set a function to sort each series values by. By default this is the key accessor which, + * for example, will ensure a lineChart series connects its points in increasing key/x order, + * rather than haphazardly. + * @name valueSort + * @memberOf dc.seriesChart + * @instance + * @param {Function} [sortFunction] + * @returns {Chart} + */ _chart.valueSort = function (_) { if (!arguments.length) { return _valueSort; diff --git a/src/stack-mixin.js b/src/stack-mixin.js index 7252ac3bc..790d15bca 100644 --- a/src/stack-mixin.js +++ b/src/stack-mixin.js @@ -1,8 +1,11 @@ /** -## Stack Mixin -Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. - -**/ + * Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. + * @name stackMixin + * @memberOf dc + * @mixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.stackMixin = function (_chart) { function prepareValues (layer, layerIdx) { @@ -52,21 +55,25 @@ dc.stackMixin = function (_chart) { } /** - #### .stack(group[, name, accessor]) - Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks - in the same chart will share the same key accessor and therefore the same set of keys. - - For example, in a stacked bar chart, the bars of each stack will be positioned using the same set - of keys on the x axis, while stacked vertically. If name is specified then it will be used to - generate the legend label. - ```js - // stack group using default accessor - chart.stack(valueSumGroup) - // stack group using custom accessor - .stack(avgByDayGroup, function(d){return d.value.avgByDay;}); - ``` - - **/ + * Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks + * in the same chart will share the same key accessor and therefore the same set of keys. + * + * For example, in a stacked bar chart, the bars of each stack will be positioned using the same set + * of keys on the x axis, while stacked vertically. If name is specified then it will be used to + * generate the legend label. + * @name stack + * @memberOf dc.stackMixin + * @instance + * @example + * // stack group using default accessor + * chart.stack(valueSumGroup) + * // stack group using custom accessor + * .stack(avgByDayGroup, function(d){return d.value.avgByDay;}); + * @param {CrossfilterGroup} group + * @param {String} [name] + * @param {Function} [accessor] + * @returns {Chart} + */ _chart.stack = function (group, name, accessor) { if (!arguments.length) { return _stack; @@ -102,16 +109,19 @@ dc.stackMixin = function (_chart) { }); /** - #### .hidableStacks([boolean]) - Allow named stacks to be hidden or shown by clicking on legend items. - This does not affect the behavior of hideStack or showStack. - - **/ - _chart.hidableStacks = function (_) { + * Allow named stacks to be hidden or shown by clicking on legend items. + * This does not affect the behavior of hideStack or showStack. + * @name hidableStacks + * @memberOf dc.stackMixin + * @instance + * @param {Boolean} hidableStacks + * @returns {Chart} + */ + _chart.hidableStacks = function (hidableStacks) { if (!arguments.length) { return _hidableStacks; } - _hidableStacks = _; + _hidableStacks = hidableStacks; return _chart; }; @@ -121,11 +131,14 @@ dc.stackMixin = function (_chart) { } /** - #### .hideStack(name) - Hide all stacks on the chart with the given name. - The chart must be re-rendered for this change to appear. - - **/ + * Hide all stacks on the chart with the given name. + * The chart must be re-rendered for this change to appear. + * @name hideStack + * @memberOf dc.stackMixin + * @instance + * @param {String} stackName + * @returns {Chart} + */ _chart.hideStack = function (stackName) { var layer = findLayerByName(stackName); if (layer) { @@ -135,11 +148,14 @@ dc.stackMixin = function (_chart) { }; /** - #### .showStack(name) - Show all stacks on the chart with the given name. - The chart must be re-rendered for this change to appear. - - **/ + * Show all stacks on the chart with the given name. + * The chart must be re-rendered for this change to appear. + * @name showStack + * @memberOf dc.stackMixin + * @instance + * @param {String} stackName + * @returns {Chart} + */ _chart.showStack = function (stackName) { var layer = findLayerByName(stackName); if (layer) { @@ -185,22 +201,25 @@ dc.stackMixin = function (_chart) { }; /** - #### .title([stackName], [titleFunction]) - Set or get the title function. Chart class will use this function to render svg title (usually interpreted by - browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. - Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to - use title otherwise the brush layer will block tooltip trigger. - - If the first argument is a stack name, the title function will get or set the title for that stack. If stackName - is not provided, the first stack is implied. - ```js - // set a title function on 'first stack' - chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); - // get a title function from 'second stack' - var secondTitleFunction = chart.title('second stack'); - ); - ``` - **/ + * Set or get the title function. Chart class will use this function to render svg title (usually interpreted by + * browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. + * Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to + * use title otherwise the brush layer will block tooltip trigger. + * + * If the first argument is a stack name, the title function will get or set the title for that stack. If stackName + * is not provided, the first stack is implied. + * @name title + * @memberOf dc.stackMixin + * @instance + * @example + * // set a title function on 'first stack' + * chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); + * // get a title function from 'second stack' + * var secondTitleFunction = chart.title('second stack'); + * @param {String} [stackName] + * @param {Function} [titleAccessor] + * @returns {Chart} + */ dc.override(_chart, 'title', function (stackName, titleAccessor) { if (!stackName) { return _chart._title(); @@ -223,11 +242,14 @@ dc.stackMixin = function (_chart) { }); /** - #### .stackLayout([layout]) - Gets or sets the stack layout algorithm, which computes a baseline for each stack and - propagates it to the next. The default is - [d3.layout.stack](https://github.com/mbostock/d3/wiki/Stack-Layout#stack). - **/ + * Gets or sets the stack layout algorithm, which computes a baseline for each stack and + * propagates it to the next + * @name stackLayout + * @memberOf dc.stackMixin + * @instance + * @param {Function} [stack=d3.layout.stack] + * @returns {Chart} + */ _chart.stackLayout = function (stack) { if (!arguments.length) { return _stackLayout; diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index 02c91a170..d93c9d06e 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -60,7 +60,7 @@ chart.width(300) * ~~[.renderlet](#dc.baseMixin+renderlet) ⇒ function~~ * [.chartGroup](#dc.baseMixin+chartGroup) ⇒ String * [.expireCache](#dc.baseMixin+expireCache) ⇒ Chart - * [.legend](#dc.baseMixin+legend) ⇒ dc.legend + * [.legend](#dc.baseMixin+legend) ⇒ [legend](#dc.legend) * [.chartID](#dc.baseMixin+chartID) ⇒ String * [.options](#dc.baseMixin+options) ⇒ Chart * [.on](#dc.baseMixin+on) ⇒ Chart @@ -82,6 +82,15 @@ chart.width(300) * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart * [.getColor](#dc.colorMixin+getColor) ⇒ String * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* + * [.marginMixin](#dc.marginMixin) ⇒ Chart + * [.margins](#dc.marginMixin+margins) ⇒ Chart + * [.stackMixin](#dc.stackMixin) ⇒ Chart + * [.stack](#dc.stackMixin+stack) ⇒ Chart + * [.hidableStacks](#dc.stackMixin+hidableStacks) ⇒ Chart + * [.hideStack](#dc.stackMixin+hideStack) ⇒ Chart + * [.showStack](#dc.stackMixin+showStack) ⇒ Chart + * [.title](#dc.stackMixin+title) ⇒ Chart + * [.stackLayout](#dc.stackMixin+stackLayout) ⇒ Chart * [.barChart](#dc.barChart) ⇒ BarChart * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean * [.barPadding](#dc.barChart+barPadding) ⇒ Number @@ -108,6 +117,75 @@ chart.width(300) * [.ordinal](#dc.units.ordinal) ⇒ Array.<String> * [.fp](#dc.units.fp) : Object * [.precision](#dc.units.fp.precision) ⇒ function + * [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart + * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart + * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart + * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> + * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path + * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart + * [.heatMap](#dc.heatMap) ⇒ HeatMap + * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart + * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart + * [.rows](#dc.heatMap+rows) ⇒ Chart + * [.cols](#dc.heatMap+cols) ⇒ Chart + * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart + * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart + * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart + * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart + * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart + * [.legend](#dc.legend) ⇒ Legend + * [.x](#dc.legend+x) ⇒ Legend + * [.y](#dc.legend+y) ⇒ Legend + * [.gap](#dc.legend+gap) ⇒ Legend + * [.itemHeight](#dc.legend+itemHeight) ⇒ Legend + * [.horizontal](#dc.legend+horizontal) ⇒ Legend + * [.legendWidth](#dc.legend+legendWidth) ⇒ Legend + * [.itemWidth](#dc.legend+itemWidth) ⇒ Legend + * [.autoItemWidth](#dc.legend+autoItemWidth) ⇒ Legend + * [.lineChart](#dc.lineChart) ⇒ LineChart + * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart + * [.tension](#dc.lineChart+tension) ⇒ Chart + * [.defined](#dc.lineChart+defined) ⇒ Chart + * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart + * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart + * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart + * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart + * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart + * [.numberDisplay](#dc.numberDisplay) ⇒ NumberDisplay + * [.html](#dc.numberDisplay+html) ⇒ Chart + * [.value](#dc.numberDisplay+value) ⇒ Number + * [.formatNumber](#dc.numberDisplay+formatNumber) ⇒ Chart + * [.pieChart](#dc.pieChart) ⇒ PieChart + * [.slicesCap](#dc.pieChart+slicesCap) ⇒ Chart + * [.externalRadiusPadding](#dc.pieChart+externalRadiusPadding) ⇒ Chart + * [.innerRadius](#dc.pieChart+innerRadius) ⇒ Chart + * [.radius](#dc.pieChart+radius) ⇒ Chart + * [.cx](#dc.pieChart+cx) ⇒ Chart + * [.cy](#dc.pieChart+cy) ⇒ Chart + * [.minAngleForLabel](#dc.pieChart+minAngleForLabel) ⇒ Chart + * [.emptyTitle](#dc.pieChart+emptyTitle) ⇒ Chart + * [.externalLabels](#dc.pieChart+externalLabels) ⇒ Chart + * [.rowChart](#dc.rowChart) ⇒ RowChart + * [.x](#dc.rowChart+x) ⇒ Chart + * [.renderTitleLabel](#dc.rowChart+renderTitleLabel) ⇒ Chart + * [.xAxis](#dc.rowChart+xAxis) ⇒ d3.svg.Axis + * [.fixedBarHeight](#dc.rowChart+fixedBarHeight) ⇒ Chart + * [.gap](#dc.rowChart+gap) ⇒ Chart + * [.elasticX](#dc.rowChart+elasticX) ⇒ Chart + * [.labelOffsetX](#dc.rowChart+labelOffsetX) ⇒ Chart + * [.labelOffsetY](#dc.rowChart+labelOffsetY) ⇒ Chart + * [.titleLabelOffsetX](#dc.rowChart+titleLabelOffsetX) ⇒ Chart + * [.scatterPlot](#dc.scatterPlot) ⇒ SeriesChart + * [.existenceAccessor](#dc.scatterPlot+existenceAccessor) ⇒ Chart + * [.symbol](#dc.scatterPlot+symbol) ⇒ Chart + * [.symbolSize](#dc.scatterPlot+symbolSize) ⇒ Chart + * [.highlightedSize](#dc.scatterPlot+highlightedSize) ⇒ Chart + * [.hiddenSize](#dc.scatterPlot+hiddenSize) ⇒ Chart + * [.seriesChart](#dc.seriesChart) ⇒ SeriesChart + * [.chart](#dc.seriesChart+chart) ⇒ Chart + * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart + * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart + * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart ### dc.baseMixin ⇒ Chart @@ -163,7 +241,7 @@ and available on all chart implementation in the DC library. * ~~[.renderlet](#dc.baseMixin+renderlet) ⇒ function~~ * [.chartGroup](#dc.baseMixin+chartGroup) ⇒ String * [.expireCache](#dc.baseMixin+expireCache) ⇒ Chart - * [.legend](#dc.baseMixin+legend) ⇒ dc.legend + * [.legend](#dc.baseMixin+legend) ⇒ [legend](#dc.legend) * [.chartID](#dc.baseMixin+chartID) ⇒ String * [.options](#dc.baseMixin+options) ⇒ Chart * [.on](#dc.baseMixin+on) ⇒ Chart @@ -772,7 +850,7 @@ clear the cache to make sure charts are rendered properly. **Kind**: instance property of [baseMixin](#dc.baseMixin) -#### baseMixin.legend ⇒ dc.legend +#### baseMixin.legend ⇒ [legend](#dc.legend) Attach a dc.legend widget to this chart. The legend widget will automatically draw legend labels based on the color setting and names associated with each group. @@ -780,7 +858,7 @@ based on the color setting and names associated with each group. | Param | Type | | --- | --- | -| [legend] | dc.legend | +| [legend] | [legend](#dc.legend) | **Example** ```js @@ -1099,6 +1177,145 @@ Get the color for the datum d and counter i. This is used internally by charts t | --- | --- | | [value] | \* | + +### dc.marginMixin ⇒ Chart +Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid +Charts. + +**Kind**: static mixin of [dc](#dc) + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +#### marginMixin.margins ⇒ Chart +Get or set the margins for a particular coordinate grid chart instance. The margins is stored as +an associative Javascript array. + +**Kind**: instance property of [marginMixin](#dc.marginMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [margins] | Object | {top: 10, right: 50, bottom: 30, left: 30} | + +**Example** +```js +var leftMargin = chart.margins().left; // 30 by default +chart.margins().left = 50; +leftMargin = chart.margins().left; // now 50 +``` + +### dc.stackMixin ⇒ Chart +Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. + +**Kind**: static mixin of [dc](#dc) + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.stackMixin](#dc.stackMixin) ⇒ Chart + * [.stack](#dc.stackMixin+stack) ⇒ Chart + * [.hidableStacks](#dc.stackMixin+hidableStacks) ⇒ Chart + * [.hideStack](#dc.stackMixin+hideStack) ⇒ Chart + * [.showStack](#dc.stackMixin+showStack) ⇒ Chart + * [.title](#dc.stackMixin+title) ⇒ Chart + * [.stackLayout](#dc.stackMixin+stackLayout) ⇒ Chart + + +#### stackMixin.stack ⇒ Chart +Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks +in the same chart will share the same key accessor and therefore the same set of keys. + +For example, in a stacked bar chart, the bars of each stack will be positioned using the same set +of keys on the x axis, while stacked vertically. If name is specified then it will be used to +generate the legend label. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| group | CrossfilterGroup | +| [name] | String | +| [accessor] | function | + +**Example** +```js +// stack group using default accessor +chart.stack(valueSumGroup) +// stack group using custom accessor +.stack(avgByDayGroup, function(d){return d.value.avgByDay;}); +``` + +#### stackMixin.hidableStacks ⇒ Chart +Allow named stacks to be hidden or shown by clicking on legend items. +This does not affect the behavior of hideStack or showStack. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| hidableStacks | Boolean | + + +#### stackMixin.hideStack ⇒ Chart +Hide all stacks on the chart with the given name. +The chart must be re-rendered for this change to appear. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| stackName | String | + + +#### stackMixin.showStack ⇒ Chart +Show all stacks on the chart with the given name. +The chart must be re-rendered for this change to appear. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| stackName | String | + + +#### stackMixin.title ⇒ Chart +Set or get the title function. Chart class will use this function to render svg title (usually interpreted by +browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. +Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to +use title otherwise the brush layer will block tooltip trigger. + +If the first argument is a stack name, the title function will get or set the title for that stack. If stackName +is not provided, the first stack is implied. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| [stackName] | String | +| [titleAccessor] | function | + +**Example** +```js +// set a title function on 'first stack' +chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); +// get a title function from 'second stack' +var secondTitleFunction = chart.title('second stack'); +``` + +#### stackMixin.stackLayout ⇒ Chart +Gets or sets the stack layout algorithm, which computes a baseline for each stack and +propagates it to the next + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [stack] | function | d3.layout.stack | + ### dc.barChart ⇒ BarChart Concrete bar chart/histogram implementation. @@ -1511,3 +1728,972 @@ chart.xUnits(dc.units.fp.precision(0.1) var thousandths = dc.units.fp.precision(0.001); thousandths(0.5, 1.0) // returns 500 ``` + +### dc.geoChoroplethChart ⇒ GeoChoroplethChart +The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map +from GeoJson data. This chart implementation was inspired by [the great d3 choropleth example](http://bl.ocks.org/4060606). +Examples: +- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: colorMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a choropleth chart under '#us-chart' element using the default global chart group +var chart1 = dc.geoChoroplethChart('#us-chart'); +// create a choropleth chart under '#us-chart2' element using chart group A +var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); +``` + +* [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart + * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart + * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart + * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> + * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path + * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart + + +#### geoChoroplethChart.overlayGeoJson ⇒ Chart +**mandatory** + +Use this function to insert a new GeoJson map layer. This function can be invoked multiple times +if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple +layers with the same name the new overlay will override the existing one. + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +| Param | Type | Description | +| --- | --- | --- | +| json | Object | a geojson feed | +| name | String | name of the layer | +| keyAccessor | function | accessor function used to extract 'key' from the GeoJson data. The key extracted by this function should match the keys returned by the crossfilter groups. | + +**Example** +```js +// insert a layer for rendering US states +chart.overlayGeoJson(statesJson.features, 'state', function(d) { + return d.properties.name; +}); +``` + +#### geoChoroplethChart.projection ⇒ Chart +Set custom geo projection function. See the available [d3 geo projection +functions](https://github.com/mbostock/d3/wiki/Geo-Projections). + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +| Param | Type | Default | +| --- | --- | --- | +| [projection] | d3.projection | d3.projection.albersUsa() | + + +#### geoChoroplethChart.geoJsons ⇒ Array.<{name:String, data: Object, accessor: function()}> +Returns all GeoJson layers currently registered with this chart. The returned array is a +reference to this chart's internal data structure, so any modification to this array will also +modify this chart's internal registration. + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +#### geoChoroplethChart.geoPath ⇒ d3.geo.path +Returns the [d3.geo.path](https://github.com/mbostock/d3/wiki/Geo-Paths#path) object used to +render the projection and features. Can be useful for figuring out the bounding box of the +feature set and thus a way to calculate scale and translation for the projection. + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +#### geoChoroplethChart.removeGeoJson ⇒ Chart +Remove a GeoJson layer from this chart by name + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +| Param | Type | +| --- | --- | +| name | String | + + +### dc.heatMap ⇒ HeatMap +A heat map is matrix that represents the values of two dimensions of data using colors. + +**Kind**: static property of [dc](#dc) +**Mixes**: colorMixin,marginMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a heat map under #chart-container1 element using the default global chart group +var heatMap1 = dc.heatMap('#chart-container1'); +// create a heat map under #chart-container2 element using chart group A +var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); +``` + +* [.heatMap](#dc.heatMap) ⇒ HeatMap + * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart + * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart + * [.rows](#dc.heatMap+rows) ⇒ Chart + * [.cols](#dc.heatMap+cols) ⇒ Chart + * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart + * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart + * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart + * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart + * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart + + +#### heatMap.colsLabel ⇒ Chart +Set or get the column label function. The chart class uses this function to render +column labels on the X axis. It is passed the column name. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | Default | +| --- | --- | --- | +| [labelFunction] | function | function(d) { return d; } | + +**Example** +```js +// the default label function just returns the name +chart.colsLabel(function(d) { return d; }); +``` + +#### heatMap.rowsLabel ⇒ Chart +Set or get the row label function. The chart class uses this function to render +row labels on the Y axis. It is passed the row name. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | Default | +| --- | --- | --- | +| [labelFunction] | function | function(d) { return d; } | + +**Example** +```js +// the default label function just returns the name +chart.rowsLabel(function(d) { return d; }); +``` + +#### heatMap.rows ⇒ Chart +Gets or sets the values used to create the rows of the heatmap, as an array. By default, all +the values will be fetched from the data using the value accessor, and they will be sorted in +ascending order. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [rows] | Array.<(String\|Number)> | + + +#### heatMap.cols ⇒ Chart +Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all +the values will be fetched from the data using the key accessor, and they will be sorted in +ascending order. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [cols] | Array.<(String\|Number)> | + + +#### heatMap.boxOnClick ⇒ Chart +Gets or sets the handler that fires when an individual cell is clicked in the heatmap. +By default, filtering of the cell will be toggled. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [handler] | function | + + +#### heatMap.xAxisOnClick ⇒ Chart +Gets or sets the handler that fires when a column tick is clicked in the x axis. +By default, if any cells in the column are unselected, the whole column will be selected, +otherwise the whole column will be unselected. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [handler] | function | + + +#### heatMap.yAxisOnClick ⇒ Chart +Gets or sets the handler that fires when a row tick is clicked in the y axis. +By default, if any cells in the row are unselected, the whole row will be selected, +otherwise the whole row will be unselected. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [handler] | function | + + +#### heatMap.xBorderRadius ⇒ Chart +Gets or sets the X border radius. Set to 0 to get full rectangles. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | Default | +| --- | --- | --- | +| [xBorderRadius] | Number | 6.75 | + + +#### heatMap.yBorderRadius ⇒ Chart +Gets or sets the Y border radius. Set to 0 to get full rectangles. + +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | Default | +| --- | --- | --- | +| [yBorderRadius] | Number | 6.75 | + + +### dc.legend ⇒ Legend +Legend is a attachable widget that can be added to other dc charts to render horizontal legend +labels. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Example** +```js +chart.legend(dc.legend().x(400).y(10).itemHeight(13).gap(5)) +``` + +* [.legend](#dc.legend) ⇒ Legend + * [.x](#dc.legend+x) ⇒ Legend + * [.y](#dc.legend+y) ⇒ Legend + * [.gap](#dc.legend+gap) ⇒ Legend + * [.itemHeight](#dc.legend+itemHeight) ⇒ Legend + * [.horizontal](#dc.legend+horizontal) ⇒ Legend + * [.legendWidth](#dc.legend+legendWidth) ⇒ Legend + * [.itemWidth](#dc.legend+itemWidth) ⇒ Legend + * [.autoItemWidth](#dc.legend+autoItemWidth) ⇒ Legend + + +#### legend.x ⇒ Legend +Set or get x coordinate for legend widget. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [x] | Number | 0 | + + +#### legend.y ⇒ Legend +Set or get y coordinate for legend widget. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [y] | Number | 0 | + + +#### legend.gap ⇒ Legend +Set or get gap between legend items. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [gap] | Number | 5 | + + +#### legend.itemHeight ⇒ Legend +Set or get legend item height. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [itemHeight] | Number | 12 | + + +#### legend.horizontal ⇒ Legend +Position legend horizontally instead of vertically. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | +| --- | --- | +| [horizontal] | Boolean | + + +#### legend.legendWidth ⇒ Legend +Maximum width for horizontal legend. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [legendWidth] | Number | 500 | + + +#### legend.itemWidth ⇒ Legend +legendItem width for horizontal legend. + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [itemWidth] | Number | 70 | + + +#### legend.autoItemWidth ⇒ Legend +Turn automatic width for legend items on or off. If true, itemWidth() is ignored. +This setting takes into account gap(). + +**Kind**: instance property of [legend](#dc.legend) + +| Param | Type | Default | +| --- | --- | --- | +| [autoItemWidth] | Boolean | false | + + +### dc.lineChart ⇒ LineChart +Concrete line/area chart implementation. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: stackMixin,coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a line chart under #chart-container1 element using the default global chart group +var chart1 = dc.lineChart('#chart-container1'); +// create a line chart under #chart-container2 element using chart group A +var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); +// create a sub-chart under a composite parent chart +var chart3 = dc.lineChart(compositeChart); +``` + +* [.lineChart](#dc.lineChart) ⇒ LineChart + * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart + * [.tension](#dc.lineChart+tension) ⇒ Chart + * [.defined](#dc.lineChart+defined) ⇒ Chart + * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart + * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart + * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart + * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart + * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart + + +#### lineChart.interpolate ⇒ Chart +Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step +functions, splines, and cubic interpolation. This is passed to +[d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and +[d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), +where you can find a complete list of valid arguments + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | +| --- | --- | +| [interpolate] | String | + + +#### lineChart.tension ⇒ Chart +Gets or sets the tension to use for lines drawn, in the range 0 to 1. +This parameter further customizes the interpolation behavior. It is passed to +[d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and +[d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [tension] | Number | 0.7 | + + +#### lineChart.defined ⇒ Chart +Gets or sets a function that will determine discontinuities in the line which should be +skipped: the path will be broken into separate subpaths if some points are undefined. +This function is passed to +[d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) + +Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write +custom reduce functions to get this to work, depending on your data. See +https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | +| --- | --- | +| [defined] | function | + + +#### lineChart.dashStyle ⇒ Chart +Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty +array (solid line). + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [dashStyle] | Array.<Number> | [] | + +**Example** +```js +// create a Dash Dot Dot Dot +chart.dashStyle([3,1,1,1]); +``` + +#### lineChart.renderArea ⇒ Chart +Get or set render area flag. If the flag is set to true then the chart will render the area +beneath each line and the line chart effectively becomes an area chart. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [renderArea] | Boolean | false | + + +#### lineChart.xyTipsOn ⇒ Chart +Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis +dashed lines back to each respective axis. This is ignored if the chart brush is on (`brushOn`) + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [xyTipsOn] | Boolean | false | + + +#### lineChart.dotRadius ⇒ Chart +Get or set the radius (in px) for dots displayed on the data points. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [dotRadius] | Number | 5 | + + +#### lineChart.renderDataPoints ⇒ Chart +Always show individual dots for each datapoint. +If `options` is falsy, it disables data point rendering. + +If no `options` are provided, the current `options` values are instead returned. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [options] | Object | {fillOpacity: 0.8, strokeOpacity: 0.8, radius: 2} | + +**Example** +```js +chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) +``` + +### dc.numberDisplay ⇒ NumberDisplay +A display of a single numeric value. +Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and +a valueAccessor that returns a single value. + +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a number display under #chart-container1 element using the default global chart group +var display1 = dc.numberDisplay('#chart-container1'); +``` + +* [.numberDisplay](#dc.numberDisplay) ⇒ NumberDisplay + * [.html](#dc.numberDisplay+html) ⇒ Chart + * [.value](#dc.numberDisplay+value) ⇒ Number + * [.formatNumber](#dc.numberDisplay+formatNumber) ⇒ Chart + + +#### numberDisplay.html ⇒ Chart +Gets or sets an optional object specifying HTML templates to use depending on the number +displayed. The text `%number` will be replaced with the current value. +- one: HTML template to use if the number is 1 +- zero: HTML template to use if the number is 0 +- some: HTML template to use otherwise + +**Kind**: instance property of [numberDisplay](#dc.numberDisplay) + +| Param | Type | Default | +| --- | --- | --- | +| [externalRadiusPadding] | Object | 0 | + +**Example** +```js +numberWidget.html({ + one:'%number record', + some:'%number records', + none:'no records'}) +``` + +#### numberDisplay.value ⇒ Number +Calculate and return the underlying value of the display + +**Kind**: instance property of [numberDisplay](#dc.numberDisplay) + +#### numberDisplay.formatNumber ⇒ Chart +Get or set a function to format the value for the display. + +**Kind**: instance property of [numberDisplay](#dc.numberDisplay) + +| Param | Type | Default | +| --- | --- | --- | +| [formatter] | function | d3.format('.2s') | + + +### dc.pieChart ⇒ PieChart +The pie chart implementation is usually used to visualize a small categorical distribution. The pie +chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each +slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting +by key. + +**Kind**: static property of [dc](#dc) +**Mixes**: capMixin,colorMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a pie chart under #chart-container1 element using the default global chart group +var chart1 = dc.pieChart('#chart-container1'); +// create a pie chart under #chart-container2 element using chart group A +var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); +``` + +* [.pieChart](#dc.pieChart) ⇒ PieChart + * [.slicesCap](#dc.pieChart+slicesCap) ⇒ Chart + * [.externalRadiusPadding](#dc.pieChart+externalRadiusPadding) ⇒ Chart + * [.innerRadius](#dc.pieChart+innerRadius) ⇒ Chart + * [.radius](#dc.pieChart+radius) ⇒ Chart + * [.cx](#dc.pieChart+cx) ⇒ Chart + * [.cy](#dc.pieChart+cy) ⇒ Chart + * [.minAngleForLabel](#dc.pieChart+minAngleForLabel) ⇒ Chart + * [.emptyTitle](#dc.pieChart+emptyTitle) ⇒ Chart + * [.externalLabels](#dc.pieChart+externalLabels) ⇒ Chart + + +#### pieChart.slicesCap ⇒ Chart +Get or set the maximum number of slices the pie chart will generate. The top slices are determined by +value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cap] | Number | + + +#### pieChart.externalRadiusPadding ⇒ Chart +Get or set the external radius padding of the pie chart. This will force the radius of the +pie chart to become smaller or larger depending on the value. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [externalRadiusPadding] | Number | 0 | + + +#### pieChart.innerRadius ⇒ Chart +Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the +pie chart will be rendered as a doughnut chart. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [innerRadius] | Number | 0 | + + +#### pieChart.radius ⇒ Chart +Get or set the outer radius. If the radius is not set, it will be half of the minimum of the +chart width and height. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [radius] | Number | + + +#### pieChart.cx ⇒ Chart +Get or set center x coordinate position. Default is center of svg. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cx] | Number | + + +#### pieChart.cy ⇒ Chart +Get or set center y coordinate position. Default is center of svg. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cy] | Number | + + +#### pieChart.minAngleForLabel ⇒ Chart +Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not +display a slice label. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [minAngleForLabel] | Number | 0.5 | + + +#### pieChart.emptyTitle ⇒ Chart +Title to use for the only slice when there is no data. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [title] | String | + + +#### pieChart.externalLabels ⇒ Chart +Position slice labels offset from the outer edge of the chart + +The given argument sets the radial offset. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [radius] | Number | + + +### dc.rowChart ⇒ RowChart +Concrete row chart implementation. + +**Kind**: static property of [dc](#dc) +**Mixes**: capMixin,marginMixin,colorMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a row chart under #chart-container1 element using the default global chart group +var chart1 = dc.rowChart('#chart-container1'); +// create a row chart under #chart-container2 element using chart group A +var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); +``` + +* [.rowChart](#dc.rowChart) ⇒ RowChart + * [.x](#dc.rowChart+x) ⇒ Chart + * [.renderTitleLabel](#dc.rowChart+renderTitleLabel) ⇒ Chart + * [.xAxis](#dc.rowChart+xAxis) ⇒ d3.svg.Axis + * [.fixedBarHeight](#dc.rowChart+fixedBarHeight) ⇒ Chart + * [.gap](#dc.rowChart+gap) ⇒ Chart + * [.elasticX](#dc.rowChart+elasticX) ⇒ Chart + * [.labelOffsetX](#dc.rowChart+labelOffsetX) ⇒ Chart + * [.labelOffsetY](#dc.rowChart+labelOffsetY) ⇒ Chart + * [.titleLabelOffsetX](#dc.rowChart+titleLabelOffsetX) ⇒ Chart + + +#### rowChart.x ⇒ Chart +Gets or sets the x scale. The x scale can be any d3 +[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | +| --- | --- | +| [scale] | d3.scale | + + +#### rowChart.renderTitleLabel ⇒ Chart +Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | +| --- | --- | +| [renderTitleLabel] | Boolean | + + +#### rowChart.xAxis ⇒ d3.svg.Axis +Get the x axis for the row chart instance. Note: not settable for row charts. +See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. + +**Kind**: instance property of [rowChart](#dc.rowChart) +**Example** +```js +// customize x axis tick format +chart.xAxis().tickFormat(function (v) {return v + '%';}); +// customize x axis tick values +chart.xAxis().tickValues([0, 100, 200, 300]); +``` + +#### rowChart.fixedBarHeight ⇒ Chart +Get or set the fixed bar height. Default is [false] which will auto-scale bars. +For example, if you want to fix the height for a specific number of bars (useful in TopN charts) +you could fix height as follows (where count = total number of bars in your TopN and gap is +your vertical gap space). + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | +| --- | --- | +| [height] | Number | + +**Example** +```js +chart.fixedBarHeight( chartheight - (count + 1) * gap / count); +``` + +#### rowChart.gap ⇒ Chart +Get or set the vertical gap space between rows on a particular row chart instance + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | Default | +| --- | --- | --- | +| [gap] | Number | 5 | + + +#### rowChart.elasticX ⇒ Chart +Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the +data range when filtered. + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | +| --- | --- | +| [elasticX] | Boolean | + + +#### rowChart.labelOffsetX ⇒ Chart +Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | Default | +| --- | --- | --- | +| [labelOffsetX] | Number | 10 | + + +#### rowChart.labelOffsetY ⇒ Chart +Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | Default | +| --- | --- | --- | +| [labelOffsety] | Number | 15 | + + +#### rowChart.titleLabelOffsetX ⇒ Chart +Get of set the x offset (horizontal space between right edge of row and right edge or text. + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | Default | +| --- | --- | --- | +| [x] | Number | 2 | + + +### dc.scatterPlot ⇒ SeriesChart +A scatter plot chart + +**Kind**: static property of [dc](#dc) +**Mixes**: coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a scatter plot under #chart-container1 element using the default global chart group +var chart1 = dc.scatterPlot('#chart-container1'); +// create a scatter plot under #chart-container2 element using chart group A +var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); +// create a sub-chart under a composite parent chart +var chart3 = dc.scatterPlot(compositeChart); +``` + +* [.scatterPlot](#dc.scatterPlot) ⇒ SeriesChart + * [.existenceAccessor](#dc.scatterPlot+existenceAccessor) ⇒ Chart + * [.symbol](#dc.scatterPlot+symbol) ⇒ Chart + * [.symbolSize](#dc.scatterPlot+symbolSize) ⇒ Chart + * [.highlightedSize](#dc.scatterPlot+highlightedSize) ⇒ Chart + * [.hiddenSize](#dc.scatterPlot+hiddenSize) ⇒ Chart + + +#### scatterPlot.existenceAccessor ⇒ Chart +Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and +opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, +the existence accessor checks if the reduced value is truthy. + +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +| Param | Type | +| --- | --- | +| [accessor] | function | + + +#### scatterPlot.symbol ⇒ Chart +Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 +[docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. +Type can be a constant or an accessor. + +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +| Param | Type | +| --- | --- | +| [type] | function | + + +#### scatterPlot.symbolSize ⇒ Chart +Set or get radius for symbols. + +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [radius] | Number | 3 | + + +#### scatterPlot.highlightedSize ⇒ Chart +Set or get radius for highlighted symbols. + +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [radius] | Number | 4 | + + +#### scatterPlot.hiddenSize ⇒ Chart +Set or get radius for symbols when the group is empty. + +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +| Param | Type | Default | +| --- | --- | --- | +| [radius] | Number | 0 | + + +### dc.seriesChart ⇒ SeriesChart +A series chart is a chart that shows multiple series of data overlaid on one chart, where the +series is specified in the data. It is a specialization of Composite Chart and inherits all +composite features other than recomposing the chart. + +**Kind**: static property of [dc](#dc) +**Mixes**: compositeChart + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a series chart under #chart-container1 element using the default global chart group +var seriesChart1 = dc.seriesChart("#chart-container1"); +// create a series chart under #chart-container2 element using chart group A +var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); +``` + +* [.seriesChart](#dc.seriesChart) ⇒ SeriesChart + * [.chart](#dc.seriesChart+chart) ⇒ Chart + * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart + * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart + * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart + + +#### seriesChart.chart ⇒ Chart +Get or set the chart function, which generates the child charts. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | Default | +| --- | --- | --- | +| chartFunction | function | dc.lineChart | + +**Example** +```js +// put interpolation on the line charts used for the series +chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) +// do a scatter series chart +chart.chart(dc.scatterPlot) +``` + +#### seriesChart.seriesAccessor ⇒ Chart +Get or set accessor function for the displayed series. Given a datum, this function +should return the series that datum belongs to. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [accessor] | function | + + +#### seriesChart.seriesSort ⇒ Chart +Get or set a function to sort the list of series by, given series values. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [sortFunction] | function | + +**Example** +```js +chart.seriesSort(d3.descending); +``` + +#### seriesChart.valueSort ⇒ Chart +Get or set a function to sort each series values by. By default this is the key accessor which, +for example, will ensure a lineChart series connects its points in increasing key/x order, +rather than haphazardly. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [sortFunction] | function | + From 905fffa2a3d67b3042238c9c5bebe4ae7af5f312 Mon Sep 17 00:00:00 2001 From: Matt Traynham Date: Mon, 17 Aug 2015 01:55:10 -0400 Subject: [PATCH 7/8] Migrated the rest of the source files to jsdoc --- Gruntfile.js | 5 +- src/composite-chart.js | 213 ++- src/coordinate-grid-mixin.js | 553 +++--- src/data-count.js | 114 +- src/data-grid.js | 163 +- src/data-table.js | 266 ++- src/events.js | 35 +- src/filters.js | 81 +- web/docs/api-latest.md | 3367 ++++++++++++++++++++++------------ 9 files changed, 2986 insertions(+), 1811 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 7b2ebb556..d4424f22f 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -185,10 +185,7 @@ module.exports = function (grunt) { }, jsdoc2md: { dist: { - src: ['src/{bar-chart,base-mixin,box-plot,bubble-chart,bubble-mixin,' + - 'bubble-overlay,cap-mixin,color-mixin,core,geo-choropleth-chart,' + - 'heatmap,legend,line-chart,margin-mixin,number-display,pie-chart,row-chart,' + - 'scatter-plot,series-chart,stack-mixin}.js'], + src: 'dc.js', dest: 'web/docs/api-latest.md' } }, diff --git a/src/composite-chart.js b/src/composite-chart.js index 8375c347b..1d339729f 100644 --- a/src/composite-chart.js +++ b/src/composite-chart.js @@ -1,31 +1,23 @@ /** -## Composite Chart -Includes: [Coordinate Grid Mixin](#coordinate-grid-mixin) - -Composite charts are a special kind of chart that render multiple charts on the same Coordinate -Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to -achieve some quite flexible charting effects. -#### dc.compositeChart(parent[, chartGroup]) -Create a composite chart instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created composite chart instance - -```js -// create a composite chart under #chart-container1 element using the default global chart group -var compositeChart1 = dc.compositeChart('#chart-container1'); -// create a composite chart under #chart-container2 element using chart group A -var compositeChart2 = dc.compositeChart('#chart-container2', 'chartGroupA'); -``` - -**/ + * Composite charts are a special kind of chart that render multiple charts on the same Coordinate + * Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to + * achieve some quite flexible charting effects. + * @name compositeChart + * @memberOf dc + * @mixes coordinateGridMixin + * @example + * // create a composite chart under #chart-container1 element using the default global chart group + * var compositeChart1 = dc.compositeChart('#chart-container1'); + * // create a composite chart under #chart-container2 element using chart group A + * var compositeChart2 = dc.compositeChart('#chart-container2', 'chartGroupA'); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {CompositeChart} + */ dc.compositeChart = function (parent, chartGroup) { var SUB_CHART_CLASS = 'sub'; @@ -176,11 +168,15 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .useRightAxisGridLines(bool) - Get or set whether to draw gridlines from the right y axis. Drawing from the left y axis is the - default behavior. This option is only respected when subcharts with both left and right y-axes - are present. - **/ + * Get or set whether to draw gridlines from the right y axis. Drawing from the left y axis is the + * default behavior. This option is only respected when subcharts with both left and right y-axes + * are present. + * @name useRightAxisGridLines + * @memberOf dc.compositeChart + * @instance + * @param {Boolean} [useRightAxisGridLines] + * @return {Chart} + */ _chart.useRightAxisGridLines = function (_) { if (!arguments) { return _rightAxisGridLines; @@ -191,10 +187,14 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .childOptions({object}) - Get or set chart-specific options for all child charts. This is equivalent to calling `.options` - on each child chart. - **/ + * Get or set chart-specific options for all child charts. This is equivalent to calling `.options` + * on each child chart. + * @name childOptions + * @memberOf dc.compositeChart + * @instance + * @param {Object} [options] + * @return {Chart} + */ _chart.childOptions = function (_) { if (!arguments.length) { return _childOptions; @@ -215,9 +215,13 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .rightYAxisLabel([labelText]) - Set or get the right y axis label. - **/ + * Set or get the right y axis label. + * @name rightYAxisLabel + * @memberOf dc.compositeChart + * @instance + * @param {String} [rightYAxisLabel] + * @return {Chart} + */ _chart.rightYAxisLabel = function (_, padding) { if (!arguments.length) { return _rightYAxisLabel; @@ -230,31 +234,31 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .compose(subChartArray) - Combine the given charts into one single composite coordinate grid chart. - - ```js - // compose the given charts in the array into one single composite chart - moveChart.compose([ - // when creating sub-chart you need to pass in the parent chart - dc.lineChart(moveChart) - .group(indexAvgByMonthGroup) // if group is missing then parent's group will be used - .valueAccessor(function (d){return d.value.avg;}) - // most of the normal functions will continue to work in a composed chart - .renderArea(true) - .stack(monthlyMoveGroup, function (d){return d.value;}) - .title(function (d){ - var value = d.value.avg?d.value.avg:d.value; - if(isNaN(value)) value = 0; - return dateFormat(d.key) + '\n' + numberFormat(value); - }), - dc.barChart(moveChart) - .group(volumeByMonthGroup) - .centerBar(true) - ]); - ``` - - **/ + * Combine the given charts into one single composite coordinate grid chart. + * @name compose + * @memberOf dc.compositeChart + * @instance + * @example + * moveChart.compose([ + * // when creating sub-chart you need to pass in the parent chart + * dc.lineChart(moveChart) + * .group(indexAvgByMonthGroup) // if group is missing then parent's group will be used + * .valueAccessor(function (d){return d.value.avg;}) + * // most of the normal functions will continue to work in a composed chart + * .renderArea(true) + * .stack(monthlyMoveGroup, function (d){return d.value;}) + * .title(function (d){ + * var value = d.value.avg?d.value.avg:d.value; + * if(isNaN(value)) value = 0; + * return dateFormat(d.key) + '\n' + numberFormat(value); + * }), + * dc.barChart(moveChart) + * .group(volumeByMonthGroup) + * .centerBar(true) + * ]); + * @param {Array} [subChartArray] + * @return {Chart} + */ _chart.compose = function (charts) { _children = charts; _children.forEach(function (child) { @@ -272,21 +276,27 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .children() - Returns the child charts which are composed into the composite chart. - **/ - + * Returns the child charts which are composed into the composite chart. + * @name children + * @memberOf dc.compositeChart + * @instance + * @return {Array} + */ _chart.children = function () { return _children; }; /** - #### .shareColors([boolean]) - Get or set color sharing for the chart. If set, the `.colors()` value from this chart - will be shared with composed children. Additionally if the child chart implements - Stackable and has not set a custom .colorAccessor, then it will generate a color - specific to its order in the composition. - **/ + * Get or set color sharing for the chart. If set, the `.colors()` value from this chart + * will be shared with composed children. Additionally if the child chart implements + * Stackable and has not set a custom .colorAccessor, then it will generate a color + * specific to its order in the composition. + * @name shareColors + * @memberOf dc.compositeChart + * @instance + * @param {Boolean} [shareColors] + * @return {Chart} + */ _chart.shareColors = function (_) { if (!arguments.length) { return _shareColors; @@ -296,10 +306,14 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .shareTitle([[boolean]) - Get or set title sharing for the chart. If set, the `.title()` value from this chart will be - shared with composed children. Default value is true. - **/ + * Get or set title sharing for the chart. If set, the `.title()` value from this chart will be + * shared with composed children. + * @name shareTitle + * @memberOf dc.compositeChart + * @instance + * @param {Boolean} [shareTitle=true] + * @return {Chart} + */ _chart.shareTitle = function (_) { if (!arguments.length) { return _shareTitle; @@ -309,11 +323,14 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .rightY([yScale]) - Get or set the y scale for the right axis. The right y scale is typically automatically - generated by the chart implementation. - - **/ + * Get or set the y scale for the right axis. The right y scale is typically automatically + * generated by the chart implementation. + * @name rightY + * @memberOf dc.compositeChart + * @instance + * @param {d3.scale} [yScale] + * @return {Chart} + */ _chart.rightY = function (_) { if (!arguments.length) { return _rightY; @@ -414,20 +431,22 @@ dc.compositeChart = function (parent, chartGroup) { }; /** - #### .rightYAxis([yAxis]) - Set or get the right y axis used by the composite chart. This function is most useful when y - axis customization is required. The y axis in dc.js is an instance of a [d3 axis - object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis) therefore it supports any valid - d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; - resetting it may cause unexpected results. - ```jså - // customize y axis tick format - chart.rightYAxis().tickFormat(function (v) {return v + '%';}); - // customize y axis tick values - chart.rightYAxis().tickValues([0, 100, 200, 300]); - ``` - - **/ + * Set or get the right y axis used by the composite chart. This function is most useful when y + * axis customization is required. The y axis in dc.js is an instance of a [d3 axis + * object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis) therefore it supports any valid + * d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; + * resetting it may cause unexpected results. + * @name rightYAxis + * @memberOf dc.compositeChart + * @instance + * @example + * // customize y axis tick format + * chart.rightYAxis().tickFormat(function (v) {return v + '%';}); + * // customize y axis tick values + * chart.rightYAxis().tickValues([0, 100, 200, 300]); + * @param {d3.svg.axis} [rightYAxis] + * @return {Chart} + */ _chart.rightYAxis = function (rightYAxis) { if (!arguments.length) { return _rightYAxis; diff --git a/src/coordinate-grid-mixin.js b/src/coordinate-grid-mixin.js index 1b05f4658..e83b9b115 100644 --- a/src/coordinate-grid-mixin.js +++ b/src/coordinate-grid-mixin.js @@ -1,11 +1,13 @@ /** -## Coordinate Grid Mixin -Includes: [Color Mixin](#color-mixin), [Margin Mixin](#margin-mixin), [Base Mixin](#base-mixin) - -Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based -concrete chart types, e.g. bar chart, line chart, and bubble chart. - -**/ + * Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based + * concrete chart types, e.g. bar chart, line chart, and bubble chart. + * @name coordinateGridMixin + * @memberOf dc + * @mixin + * @mixes colorMixin,marginMixin,baseMixin + * @param {Chart} _chart + * @returns {Chart} + */ dc.coordinateGridMixin = function (_chart) { var GRID_LINE_CLASS = 'grid-line'; var HORIZONTAL_CLASS = 'horizontal'; @@ -101,11 +103,14 @@ dc.coordinateGridMixin = function (_chart) { var _useRightYAxis = false; /** - #### .rescale() - When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate - and redraw the axes. (`.rescale()` is called automatically when the x or y scale is replaced - with `.x()` or `.y()`, and has no effect on elastic scales.) - **/ + * When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate + * and redraw the axes. (`.rescale()` is called automatically when the x or y scale is replaced + * with `.x()` or `.y()`, and has no effect on elastic scales.) + * @name rescale + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {Chart} + */ _chart.rescale = function () { _unitCount = undefined; _resizing = true; @@ -113,14 +118,17 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .rangeChart([chart]) - Get or set the range selection chart associated with this instance. Setting the range selection - chart using this function will automatically update its selection brush when the current chart - zooms in. In return the given range chart will also automatically attach this chart as its focus - chart hence zoom in when range brush updates. See the [Nasdaq 100 - Index](http://dc-js.github.com/dc.js/) example for this effect in action. - - **/ + * Get or set the range selection chart associated with this instance. Setting the range selection + * chart using this function will automatically update its selection brush when the current chart + * zooms in. In return the given range chart will also automatically attach this chart as its focus + * chart hence zoom in when range brush updates. See the [Nasdaq 100 + * Index](http://dc-js.github.com/dc.js/) example for this effect in action. + * @name rangeChart + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Chart} [rangeChart] + * @returns {Chart} + */ _chart.rangeChart = function (_) { if (!arguments.length) { return _rangeChart; @@ -131,10 +139,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .zoomScale([extent]) - Get or set the scale extent for mouse zooms. - - **/ + * Get or set the scale extent for mouse zooms. + * @name zoomScale + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Array<*>} [extent] + * @returns {Chart} + */ _chart.zoomScale = function (_) { if (!arguments.length) { return _zoomScale; @@ -144,9 +155,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .zoomOutRestrict([true/false]) - Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart. - **/ + * Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart. + * @name zoomOutRestrict + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [zoomOutRestrict] + * @returns {Chart} + */ _chart.zoomOutRestrict = function (r) { if (!arguments.length) { return _zoomOutRestrict; @@ -173,12 +188,15 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .g([gElement]) - Get or set the root g element. This method is usually used to retrieve the g element in order to - overlay custom svg drawing programatically. **Caution**: The root g element is usually generated - by dc.js internals, and resetting it might produce unpredictable result. - - **/ + * Get or set the root g element. This method is usually used to retrieve the g element in order to + * overlay custom svg drawing programatically. **Caution**: The root g element is usually generated + * by dc.js internals, and resetting it might produce unpredictable result. + * @name g + * @memberOf dc.coordinateGridMixin + * @instance + * @param {svg} [gElement] + * @returns {Chart} + */ _chart.g = function (_) { if (!arguments.length) { return _g; @@ -188,12 +206,15 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .mouseZoomable([boolean]) - Set or get mouse zoom capability flag (default: false). When turned on the chart will be - zoomable using the mouse wheel. If the range selector chart is attached zooming will also update - the range selection brush on the associated range selector chart. - - **/ + * Set or get mouse zoom capability flag (default: false). When turned on the chart will be + * zoomable using the mouse wheel. If the range selector chart is attached zooming will also update + * the range selection brush on the associated range selector chart. + * @name mouseZoomable + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [mouseZoomable] + * @returns {Chart} + */ _chart.mouseZoomable = function (z) { if (!arguments.length) { return _mouseZoomable; @@ -203,9 +224,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .chartBodyG() - Retrieve the svg group for the chart body. - **/ + * Retrieve the svg group for the chart body. + * @name chartBodyG + * @memberOf dc.coordinateGridMixin + * @instance + * @param {svg} [chartBodyG] + * @returns {Chart} + */ _chart.chartBodyG = function (_) { if (!arguments.length) { return _chartBodyG; @@ -215,18 +240,22 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .x([xScale]) - **mandatory** - Get or set the x scale. The x scale can be any d3 - [quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) or - [ordinal scale](https://github.com/mbostock/d3/wiki/Ordinal-Scales). - ```js - // set x to a linear scale - chart.x(d3.scale.linear().domain([-2500, 2500])) - // set x to a time scale to generate histogram - chart.x(d3.time.scale().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)])) - ``` - - **/ + * **mandatory** + * + * Get or set the x scale. The x scale can be any d3 + * [quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) or + * [ordinal scale](https://github.com/mbostock/d3/wiki/Ordinal-Scales). + * @name x + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * // set x to a linear scale + * chart.x(d3.scale.linear().domain([-2500, 2500])) + * // set x to a time scale to generate histogram + * chart.x(d3.time.scale().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)])) + * @param {d3.scale} [xScale] + * @returns {Chart} + */ _chart.x = function (_) { if (!arguments.length) { return _x; @@ -242,37 +271,37 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xUnits([xUnits function]) - Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate - the number of data projections on x axis such as the number of bars for a bar chart or the - number of dots for a line chart. This function is expected to return a Javascript array of all - data points on x axis, or the number of points on the axis. [d3 time range functions - d3.time.days, d3.time.months, and - d3.time.years](https://github.com/mbostock/d3/wiki/Time-Intervals#aliases) are all valid xUnits - function. dc.js also provides a few units function, see the [Utilities](#utilities) section for - a list of built-in units functions. The default xUnits function is dc.units.integers. - ```js - // set x units to count days - chart.xUnits(d3.time.days); - // set x units to count months - chart.xUnits(d3.time.months); - ``` - A custom xUnits function can be used as long as it follows the following interface: - ```js - // units in integer - function(start, end, xDomain) { - // simply calculates how many integers in the domain - return Math.abs(end - start); - }; - - // fixed units - function(start, end, xDomain) { - // be aware using fixed units will disable the focus/zoom ability on the chart - return 1000; - }; - ``` - - **/ + * Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate + * the number of data projections on x axis such as the number of bars for a bar chart or the + * number of dots for a line chart. This function is expected to return a Javascript array of all + * data points on x axis, or the number of points on the axis. [d3 time range functions + * d3.time.days, d3.time.months, and + * d3.time.years](https://github.com/mbostock/d3/wiki/Time-Intervals#aliases) are all valid xUnits + * function. dc.js also provides a few units function, see the [Utilities](#utilities) section for + * a list of built-in units functions. The default xUnits function is dc.units.integers. + * @name xUnits + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * // set x units to count days + * chart.xUnits(d3.time.days); + * // set x units to count months + * chart.xUnits(d3.time.months); + * + * // A custom xUnits function can be used as long as it follows the following interface: + * // units in integer + * function(start, end, xDomain) { + * // simply calculates how many integers in the domain + * return Math.abs(end - start); + * }; + * + * // fixed units + * function(start, end, xDomain) { + * // be aware using fixed units will disable the focus/zoom ability on the chart + * return 1000; + * @param {Function} [xUnits] + * @returns {Chart} + */ _chart.xUnits = function (_) { if (!arguments.length) { return _xUnits; @@ -282,20 +311,22 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xAxis([xAxis]) - Set or get the x axis used by a particular coordinate grid chart instance. This function is most - useful when x axis customization is required. The x axis in dc.js is an instance of a [d3 - axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis); therefore it supports any - valid d3 axis manipulation. **Caution**: The x axis is usually generated internally by dc; - resetting it may cause unexpected results. - ```js - // customize x axis tick format - chart.xAxis().tickFormat(function(v) {return v + '%';}); - // customize x axis tick values - chart.xAxis().tickValues([0, 100, 200, 300]); - ``` - - **/ + * Set or get the x axis used by a particular coordinate grid chart instance. This function is most + * useful when x axis customization is required. The x axis in dc.js is an instance of a [d3 + * axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis); therefore it supports any + * valid d3 axis manipulation. **Caution**: The x axis is usually generated internally by dc; + * resetting it may cause unexpected results. + * @name xAxis + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * // customize x axis tick format + * chart.xAxis().tickFormat(function(v) {return v + '%';}); + * // customize x axis tick values + * chart.xAxis().tickValues([0, 100, 200, 300]); + * @param {d3.svg.axis} [xAxis] + * @returns {Chart} + */ _chart.xAxis = function (_) { if (!arguments.length) { return _xAxis; @@ -305,11 +336,14 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .elasticX([boolean]) - Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will - attempt to recalculate the x axis range whenever a redraw event is triggered. - - **/ + * Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will + * attempt to recalculate the x axis range whenever a redraw event is triggered. + * @name elasticX + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [elasticX] + * @returns {Chart} + */ _chart.elasticX = function (_) { if (!arguments.length) { return _xElasticity; @@ -319,15 +353,18 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xAxisPadding([padding]) - Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x - axis if elasticX is turned on; otherwise it is ignored. - - * padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to - number or date x axes. When padding a date axis, an integer represents number of days being padded - and a percentage string will be treated the same as an integer. - - **/ + * Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x + * axis if elasticX is turned on; otherwise it is ignored. + * + * padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to + * number or date x axes. When padding a date axis, an integer represents number of days being padded + * and a percentage string will be treated the same as an integer. + * @name xAxisPadding + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Number|String} [padding] + * @returns {Chart} + */ _chart.xAxisPadding = function (_) { if (!arguments.length) { return _xAxisPadding; @@ -337,10 +374,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xUnitCount() - Returns the number of units displayed on the x axis using the unit measure configured by - .xUnits. - **/ + * Returns the number of units displayed on the x axis using the unit measure configured by + * .xUnits. + * @name xUnitCount + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {Number} + */ _chart.xUnitCount = function () { if (_unitCount === undefined) { var units = _chart.xUnits()(_chart.x().domain()[0], _chart.x().domain()[1], _chart.x().domain()); @@ -354,13 +394,17 @@ dc.coordinateGridMixin = function (_chart) { return _unitCount; }; - /** - #### .useRightYAxis() - Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When - used with a chart in a composite chart, allows both left and right Y axes to be shown on a - chart. - **/ + /** + * Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When + * used with a chart in a composite chart, allows both left and right Y axes to be shown on a + * chart. + * @name useRightYAxis + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [useRightYAxis] + * @returns {Chart} + */ _chart.useRightYAxis = function (_) { if (!arguments.length) { return _useRightYAxis; @@ -370,11 +414,14 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### isOrdinal() - Returns true if the chart is using ordinal xUnits ([dc.units.ordinal](#dcunitsordinal)), or false - otherwise. Most charts behave differently with ordinal data and use the result of this method to - trigger the appropriate logic. - **/ + * Returns true if the chart is using ordinal xUnits ([dc.units.ordinal](#dcunitsordinal)), or false + * otherwise. Most charts behave differently with ordinal data and use the result of this method to + * trigger the appropriate logic. + * @name isOrdinal + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {Boolean} + */ _chart.isOrdinal = function () { return _chart.xUnits() === dc.units.ordinal; }; @@ -513,10 +560,15 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xAxisLabel([labelText, [, padding]]) - Set or get the x axis label. If setting the label, you may optionally include additional padding to - the margin to make room for the label. By default the padded is set to 12 to accomodate the text height. - **/ + * Set or get the x axis label. If setting the label, you may optionally include additional padding to + * the margin to make room for the label. By default the padded is set to 12 to accomodate the text height. + * @name xAxisLabel + * @memberOf dc.coordinateGridMixin + * @instance + * @param {String} [labelText] + * @param {Number} [padding=12] + * @returns {Chart} + */ _chart.xAxisLabel = function (_, padding) { if (!arguments.length) { return _xAxisLabel; @@ -642,11 +694,16 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .yAxisLabel([labelText, [, padding]]) - Set or get the y axis label. If setting the label, you may optionally include additional padding - to the margin to make room for the label. By default the padded is set to 12 to accomodate the - text height. - **/ + * Set or get the y axis label. If setting the label, you may optionally include additional padding + * to the margin to make room for the label. By default the padded is set to 12 to accomodate the + * text height. + * @name yAxisLabel + * @memberOf dc.coordinateGridMixin + * @instance + * @param {String} [labelText] + * @param {Number} [padding=12] + * @returns {Chart} + */ _chart.yAxisLabel = function (_, padding) { if (!arguments.length) { return _yAxisLabel; @@ -659,10 +716,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .y([yScale]) - Get or set the y scale. The y scale is typically automatically determined by the chart implementation. - - **/ + * Get or set the y scale. The y scale is typically automatically determined by the chart implementation. + * @name y + * @memberOf dc.coordinateGridMixin + * @instance + * @param {d3.scale} [y] + * @returns {Chart} + */ _chart.y = function (_) { if (!arguments.length) { return _y; @@ -673,20 +733,22 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .yAxis([yAxis]) - Set or get the y axis used by the coordinate grid chart instance. This function is most useful - when y axis customization is required. The y axis in dc.js is simply an instance of a [d3 axis - object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis); therefore it supports any - valid d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; - resetting it may cause unexpected results. - ```js - // customize y axis tick format - chart.yAxis().tickFormat(function(v) {return v + '%';}); - // customize y axis tick values - chart.yAxis().tickValues([0, 100, 200, 300]); - ``` - - **/ + * Set or get the y axis used by the coordinate grid chart instance. This function is most useful + * when y axis customization is required. The y axis in dc.js is simply an instance of a [d3 axis + * object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis); therefore it supports any + * valid d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; + * resetting it may cause unexpected results. + * @name yAxis + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * // customize y axis tick format + * chart.yAxis().tickFormat(function(v) {return v + '%';}); + * // customize y axis tick values + * chart.yAxis().tickValues([0, 100, 200, 300]); + * @param {d3.svg.axis} [yAxis] + * @returns {Chart} + */ _chart.yAxis = function (y) { if (!arguments.length) { return _yAxis; @@ -696,11 +758,14 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .elasticY([boolean]) - Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will - attempt to recalculate the y axis range whenever a redraw event is triggered. - - **/ + * Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will + * attempt to recalculate the y axis range whenever a redraw event is triggered. + * @name elasticY + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [elasticY] + * @returns {Chart} + */ _chart.elasticY = function (_) { if (!arguments.length) { return _yElasticity; @@ -710,10 +775,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .renderHorizontalGridLines([boolean]) - Turn on/off horizontal grid lines. - - **/ + * Turn on/off horizontal grid lines. + * @name renderHorizontalGridLines + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [renderHorizontalGridLines] + * @returns {Chart} + */ _chart.renderHorizontalGridLines = function (_) { if (!arguments.length) { return _renderHorizontalGridLine; @@ -723,10 +791,13 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .renderVerticalGridLines([boolean]) - Turn on/off vertical grid lines. - - **/ + * Turn on/off vertical grid lines. + * @name renderVerticalGridLines + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [renderVerticalGridLines] + * @returns {Chart} + */ _chart.renderVerticalGridLines = function (_) { if (!arguments.length) { return _renderVerticalGridLine; @@ -736,9 +807,12 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xAxisMin() - Calculates the minimum x value to display in the chart. Includes xAxisPadding if set. - **/ + * Calculates the minimum x value to display in the chart. Includes xAxisPadding if set. + * @name xAxisMin + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {*} + */ _chart.xAxisMin = function () { var min = d3.min(_chart.data(), function (e) { return _chart.keyAccessor()(e); @@ -747,9 +821,12 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .xAxisMax() - Calculates the maximum x value to display in the chart. Includes xAxisPadding if set. - **/ + * Calculates the maximum x value to display in the chart. Includes xAxisPadding if set. + * @name xAxisMax + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {*} + */ _chart.xAxisMax = function () { var max = d3.max(_chart.data(), function (e) { return _chart.keyAccessor()(e); @@ -758,9 +835,12 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .yAxisMin() - Calculates the minimum y value to display in the chart. Includes yAxisPadding if set. - **/ + * Calculates the minimum y value to display in the chart. Includes yAxisPadding if set. + * @name yAxisMin + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {*} + */ _chart.yAxisMin = function () { var min = d3.min(_chart.data(), function (e) { return _chart.valueAccessor()(e); @@ -769,9 +849,12 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .yAxisMax() - Calculates the maximum y value to display in the chart. Includes yAxisPadding if set. - **/ + * Calculates the maximum y value to display in the chart. Includes yAxisPadding if set. + * @name yAxisMax + * @memberOf dc.coordinateGridMixin + * @instance + * @returns {*} + */ _chart.yAxisMax = function () { var max = d3.max(_chart.data(), function (e) { return _chart.valueAccessor()(e); @@ -780,15 +863,18 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .yAxisPadding([padding]) - Set or get y axis padding for the elastic y axis. The padding will be added to the top of the y - axis if elasticY is turned on; otherwise it is ignored. - - * padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to - number or date axes. When padding a date axis, an integer represents number of days being padded - and a percentage string will be treated the same as an integer. - - **/ + * Set or get y axis padding for the elastic y axis. The padding will be added to the top of the y + * axis if elasticY is turned on; otherwise it is ignored. + * + * padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to + * number or date axes. When padding a date axis, an integer represents number of days being padded + * and a percentage string will be treated the same as an integer. + * @name yAxisPadding + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Number|String} [padding] + * @returns {Chart} + */ _chart.yAxisPadding = function (_) { if (!arguments.length) { return _yAxisPadding; @@ -802,15 +888,17 @@ dc.coordinateGridMixin = function (_chart) { }; /** - #### .round([rounding function]) - Set or get the rounding function used to quantize the selection when brushing is enabled. - ```js - // set x unit round to by month, this will make sure range selection brush will - // select whole months - chart.round(d3.time.month.round); - ``` - - **/ + * Set or get the rounding function used to quantize the selection when brushing is enabled. + * @name round + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * // set x unit round to by month, this will make sure range selection brush will + * // select whole months + * chart.round(d3.time.month.round); + * @param {Function} [round] + * @returns {Chart} + */ _chart.round = function (_) { if (!arguments.length) { return _round; @@ -968,12 +1056,15 @@ dc.coordinateGridMixin = function (_chart) { } /** - #### .clipPadding([padding]) - Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to - the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area - will be exactly the chart body area minus the margins. Default: 5 - - **/ + * Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to + * the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area + * will be exactly the chart body area minus the margins. + * @name clipPadding + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Number} [padding=5] + * @returns {Chart} + */ _chart.clipPadding = function (p) { if (!arguments.length) { return _clipPadding; @@ -1080,22 +1171,23 @@ dc.coordinateGridMixin = function (_chart) { } /** - #### .focus([range]) - Zoom this chart to focus on the given range. The given range should be an array containing only - 2 elements (`[start, end]`) defining a range in the x domain. If the range is not given or set - to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; - otherwise focus will be ignored._ - ```js - chart.on('renderlet', function(chart) { - // smooth the rendering through event throttling - dc.events.trigger(function(){ - // focus some other chart to the range selected by user on this chart - someOtherChart.focus(chart.filter()); - }); - }) - ``` - - **/ + * Zoom this chart to focus on the given range. The given range should be an array containing only + * 2 elements (`[start, end]`) defining a range in the x domain. If the range is not given or set + * to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; + * otherwise focus will be ignored. + * @name focus + * @memberOf dc.coordinateGridMixin + * @instance + * @example + * chart.on('renderlet', function(chart) { + * // smooth the rendering through event throttling + * dc.events.trigger(function(){ + * // focus some other chart to the range selected by user on this chart + * someOtherChart.focus(chart.filter()); + * }); + * }) + * @param {Array} [range] + */ _chart.focus = function (range) { if (hasRangeSelected(range)) { _chart.x().domain(range); @@ -1148,15 +1240,18 @@ dc.coordinateGridMixin = function (_chart) { } /** - #### .brushOn([boolean]) - Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse - across a chart with a quantitative scale to perform range filtering based on the extent of the - brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and - unfilter them. However turning on the brush filter will disable other interactive elements on - the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible - if enabled, but only via scrolling (panning will be disabled.) Default: true - - **/ + * Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse + * across a chart with a quantitative scale to perform range filtering based on the extent of the + * brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and + * unfilter them. However turning on the brush filter will disable other interactive elements on + * the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible + * if enabled, but only via scrolling (panning will be disabled.) + * @name brushOn + * @memberOf dc.coordinateGridMixin + * @instance + * @param {Boolean} [brushOn=true] + * @return {Chart} + */ _chart.brushOn = function (_) { if (!arguments.length) { return _brushOn; diff --git a/src/data-count.js b/src/data-count.js index be8e5ff37..c3e37f4f5 100644 --- a/src/data-count.js +++ b/src/data-count.js @@ -1,65 +1,53 @@ /** -## Data Count Widget -Includes: [Base Mixin](#base-mixin) - -The data count widget is a simple widget designed to display the number of records selected by the -current filters out of the total number of records in the data set. Once created the data count widget -will automatically update the text content of the following elements under the parent element. - -* '.total-count' - total number of records -* '.filter-count' - number of records matched by the current filters - -Examples: - -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.dataCount(parent[, chartGroup]) -Create a data count widget and attach it to the given parent element. - -Parameters: - -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. -* chartGroup : string (optional) - name of the chart group this widget should be placed in. - The data count widget will only react to filter changes in the chart group. - -Returns: -A newly created data count widget instance -#### .dimension(allData) - **mandatory** -For the data count widget the only valid dimension is the entire data set. -#### .group(groupAll) - **mandatory** -For the data count widget the only valid group is the group returned by `dimension.groupAll()`. - -```js -var ndx = crossfilter(data); -var all = ndx.groupAll(); - -dc.dataCount('.dc-data-count') - .dimension(ndx) - .group(all); -``` - -**/ + * The data count widget is a simple widget designed to display the number of records selected by the + * current filters out of the total number of records in the data set. Once created the data count widget + * will automatically update the text content of the following elements under the parent element. + * + * '.total-count' - total number of records + * '.filter-count' - number of records matched by the current filters + * + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * @name dataCount + * @memberOf dc + * @mixes baseMixin + * @example + * var ndx = crossfilter(data); + * var all = ndx.groupAll(); + * + * dc.dataCount('.dc-data-count') + * .dimension(ndx) + * .group(all); + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {DataCount} + */ dc.dataCount = function (parent, chartGroup) { var _formatNumber = d3.format(',d'); var _chart = dc.baseMixin({}); var _html = {some:'', all:''}; /** - #### html([object]) - Gets or sets an optional object specifying HTML templates to use depending how many items are - selected. The text `%total-count` will replaced with the total number of records, and the text - `%filter-count` will be replaced with the number of selected records. - - all: HTML template to use if all items are selected - - some: HTML template to use if not all items are selected - - ```js - counter.html({ - some: '%filter-count out of %total-count records selected', - all: 'All records selected. Click on charts to apply filters' - }) - ``` - **/ + * Gets or sets an optional object specifying HTML templates to use depending how many items are + * selected. The text `%total-count` will replaced with the total number of records, and the text + * `%filter-count` will be replaced with the number of selected records. + * - all: HTML template to use if all items are selected + * - some: HTML template to use if not all items are selected + * @name html + * @memberOf dc.dataCount + * @instance + * @example + * counter.html({ + * some: '%filter-count out of %total-count records selected', + * all: 'All records selected. Click on charts to apply filters' + * }) + * @param {{some:String, all: String}} [options] + * @returns {Chart} + */ _chart.html = function (s) { if (!arguments.length) { return _html; @@ -74,13 +62,15 @@ dc.dataCount = function (parent, chartGroup) { }; /** - #### formatNumber([formatter]) - Gets or sets an optional function to format the filter count and total count. - - ```js - counter.formatNumber(d3.format('.2g')) - ``` - **/ + * Gets or sets an optional function to format the filter count and total count. + * @name formatNumber + * @memberOf dc.dataCount + * @instance + * @example + * counter.formatNumber(d3.format('.2g')) + * @param {Function} [formatter=d3.format('.2g')] + * @returns {Chart} + */ _chart.formatNumber = function (s) { if (!arguments.length) { return _formatNumber; diff --git a/src/data-grid.js b/src/data-grid.js index b75f2bf12..9874f6e5f 100644 --- a/src/data-grid.js +++ b/src/data-grid.js @@ -1,33 +1,24 @@ /** - ## Data Grid Widget - - Includes: [Base Mixin](#base-mixin) - - 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 group attribute as a keying function - for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. - Do not pass in a crossfilter group as this will not work. - - Examples: - * [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) - - #### dc.dataGrid(parent[, chartGroup]) - Create a data grid widget instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created data grid widget instance - - **/ + * 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 group attribute as a keying function + * for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. + * Do not pass in a crossfilter group as this will not work. + * + * Examples: + * - [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) + * @name dataGrid + * @memberOf dc + * @mixes baseMixin + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {DataGrid} + */ dc.dataGrid = function (parent, chartGroup) { var LABEL_CSS_CLASS = 'dc-grid-label'; var ITEM_CSS_CLASS = 'dc-grid-item'; @@ -114,11 +105,14 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .beginSlice([index]) - Get or set the index of the beginning slice which determines which entries get displayed by the widget - Useful when implementing pagination. - - **/ + * Get or set the index of the beginning slice which determines which entries get displayed by the widget + * Useful when implementing pagination. + * @name beginSlice + * @memberOf dc.dataGrid + * @instance + * @param {Number} [beginSlice=0] + * @returns {Chart} + */ _chart.beginSlice = function (_) { if (!arguments.length) { return _beginSlice; @@ -128,11 +122,14 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .endSlice([index]) - Get or set the index of the end slice which determines which entries get displayed by the widget - Useful when implementing pagination. - - **/ + * Get or set the index of the end slice which determines which entries get displayed by the widget + * Useful when implementing pagination. + * @name endSlice + * @memberOf dc.dataGrid + * @instance + * @param {Number} [endSlice] + * @returns {Chart} + */ _chart.endSlice = function (_) { if (!arguments.length) { return _endSlice; @@ -142,10 +139,13 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .size([size]) - Get or set the grid size which determines the number of items displayed by the widget. - - **/ + * Get or set the grid size which determines the number of items displayed by the widget. + * @name size + * @memberOf dc.dataGrid + * @instance + * @param {Number} [size=999] + * @returns {Chart} + */ _chart.size = function (s) { if (!arguments.length) { return _size; @@ -155,15 +155,17 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .html( function (data) { return ''; }) - Get or set the function that formats an item. The data grid widget uses a - function to generate dynamic html. Use your favourite templating engine or - generate the string directly. - ```js - chart.html(function (d) { return '
'+data.exampleString+'
';}); - ``` - - **/ + * Get or set the function that formats an item. The data grid widget uses a + * function to generate dynamic html. Use your favourite templating engine or + * generate the string directly. + * @name html + * @memberOf dc.dataGrid + * @instance + * @example + * chart.html(function (d) { return '
'+data.exampleString+'
';}); + * @param {Function} [html] + * @returns {Chart} + */ _chart.html = function (_) { if (!arguments.length) { return _html; @@ -173,13 +175,15 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .htmlGroup( function (data) { return ''; }) - Get or set the function that formats a group label. - ```js - chart.htmlGroup (function (d) { return '

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

'}); - ``` - - **/ + * Get or set the function that formats a group label. + * @name htmlGroup + * @memberOf dc.dataGrid + * @instance + * @example + * chart.htmlGroup (function (d) { return '

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

'}); + * @param {Function} [htmlGroup] + * @returns {Chart} + */ _chart.htmlGroup = function (_) { if (!arguments.length) { return _htmlGroup; @@ -189,18 +193,18 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .sortBy([sortByFunction]) - 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. - by. Default: identity function - - ```js - chart.sortBy(function(d) { - return d.date; - }); - ``` - - **/ + * 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. + * @name sortBy + * @memberOf dc.dataGrid + * @instance + * @example + * chart.sortBy(function(d) { + * return d.date; + * }); + * @param {Function} [sortByFunction] + * @returns {Chart} + */ _chart.sortBy = function (_) { if (!arguments.length) { return _sortBy; @@ -210,14 +214,15 @@ dc.dataGrid = function (parent, chartGroup) { }; /** - #### .order([order]) - Get or set sort order function. Default value: ``` d3.ascending ``` - - ```js - chart.order(d3.descending); - ``` - - **/ + * Get or set sort order function. + * @name order + * @memberOf dc.dataGrid + * @instance + * @example + * chart.order(d3.descending); + * @param {Function} [order=d3.ascending] + * @returns {Chart} + */ _chart.order = function (_) { if (!arguments.length) { return _order; diff --git a/src/data-table.js b/src/data-table.js index 8a10d400b..21c565816 100644 --- a/src/data-table.js +++ b/src/data-table.js @@ -1,31 +1,24 @@ /** -## Data Table Widget -Includes: [Base Mixin](#base-mixin) - -The data table is a simple widget designed to list crossfilter focused data set (rows being -filtered) in a good old tabular fashion. - -Note: Unlike other charts, the data table (and data grid chart) use the group attribute as a keying function -for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. -Do not pass in a crossfilter group as this will not work. - -Examples: -* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -#### dc.dataTable(parent[, chartGroup]) -Create a data table widget instance and attach it to the given parent element. - -Parameters: -* parent : string | node | selection - any valid - [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying - a dom block element such as a div; or a dom element or d3 selection. - -* chartGroup : string (optional) - name of the chart group this chart instance should be placed in. - Interaction with a chart will only trigger events and redraws within the chart's group. - -Returns: -A newly created data table widget instance - -**/ + * The data table is a simple widget designed to list crossfilter focused data set (rows being + * filtered) in a good old tabular fashion. + * + * Note: Unlike other charts, the data table (and data grid chart) use the group attribute as a keying function + * for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. + * Do not pass in a crossfilter group as this will not work. + * + * Examples: + * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + * @name dataTable + * @memberOf dc + * @mixes baseMixin + * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid + * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying + * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart + * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. + * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in. + * Interaction with a chart will only trigger events and redraws within the chart's group. + * @returns {DataTable} + */ dc.dataTable = function (parent, chartGroup) { var LABEL_CSS_CLASS = 'dc-table-label'; var ROW_CSS_CLASS = 'dc-table-row'; @@ -194,10 +187,13 @@ dc.dataTable = function (parent, chartGroup) { }; /** - #### .size([size]) - Get or set the table size which determines the number of rows displayed by the widget. - - **/ + * Get or set the table size which determines the number of rows displayed by the widget. + * @name size + * @memberOf dc.dataTable + * @instance + * @param {Number} [size] + * @returns {Chart} + */ _chart.size = function (s) { if (!arguments.length) { return _size; @@ -207,90 +203,66 @@ dc.dataTable = function (parent, chartGroup) { }; /** - #### .columns([columnFunctionArray]) - Get or set column functions. The data table widget now supports several methods of specifying - the columns to display. The original method, first shown below, uses an array of functions to - generate dynamic columns. Column functions are simple javascript functions with only one input - argument `d` which represents a row in the data set. The return value of these functions will be - used directly to generate table content for each cell. However, this method requires the .html - table entry to have a fixed set of column headers. - - ```js - chart.columns([ - function(d) { - return d.date; - }, - function(d) { - return d.open; - }, - function(d) { - return d.close; - }, - function(d) { - return numberFormat(d.close - d.open); - }, - function(d) { - return d.volume; - } - ]); - ``` - - The next example shows you can simply list the data (d) content directly without - specifying it as a function, except where necessary (ie, computed columns). Note - the data element accessor name is capitalized when displayed in the table. You can - also mix in functions as desired or necessary, but you must use the - Object = [Label, Fn] method as shown below. - You may wish to override the following two functions, which are internally used to - translate the column information or function into a displayed header. The first one - is used on the simple "string" column specifier, the second is used to transform the - String(fn) into something displayable. For the Stock example, the function for Change - becomes a header of 'd.close - d.open'. - _chart._doColumnHeaderCapitalize _chart._doColumnHeaderFnToString - You may use your own Object definition, however you must then override - _chart._doColumnHeaderFormat , _chart._doColumnValueFormat - Be aware that fields without numberFormat specification will be displayed just as - they are stored in the data, unformatted. - ```js - chart.columns([ - "date", // d["date"], ie, a field accessor; capitalized automatically - "open", // ... - "close", // ... - ["Change", // Specify an Object = [Label, Fn] - function (d) { - return numberFormat(d.close - d.open); - }], - "volume" // d["volume"], ie, a field accessor; capitalized automatically - ]); - ``` - - A third example, where all fields are specified using the Object = [Label, Fn] method. - - ```js - chart.columns([ - ["Date", // Specify an Object = [Label, Fn] - function (d) { - return d.date; - }], - ["Open", - function (d) { - return numberFormat(d.open); - }], - ["Close", - function (d) { - return numberFormat(d.close); - }], - ["Change", - function (d) { - return numberFormat(d.close - d.open); - }], - ["Volume", - function (d) { - return d.volume; - }] - ]); - ``` - - **/ + * Get or set column functions. The data table widget now supports several methods of specifying + * the columns to display. The original method, first shown below, uses an array of functions to + * generate dynamic columns. Column functions are simple javascript functions with only one input + * argument `d` which represents a row in the data set. The return value of these functions will be + * used directly to generate table content for each cell. However, this method requires the .html + * table entry to have a fixed set of column headers. + * + * The second example shows you can simply list the data (d) content directly without + * specifying it as a function, except where necessary (ie, computed columns). Note + * the data element accessor name is capitalized when displayed in the table. You can + * also mix in functions as desired or necessary, but you must use the + * Object = [Label, Fn] method as shown below. + * You may wish to override the following two functions, which are internally used to + * translate the column information or function into a displayed header. The first one + * is used on the simple "string" column specifier, the second is used to transform the + * String(fn) into something displayable. For the Stock example, the function for Change + * becomes a header of 'd.close - d.open'. + * _chart._doColumnHeaderCapitalize _chart._doColumnHeaderFnToString + * You may use your own Object definition, however you must then override + * _chart._doColumnHeaderFormat , _chart._doColumnValueFormat + * Be aware that fields without numberFormat specification will be displayed just as + * they are stored in the data, unformatted. + * + * The third example, where all fields are specified using the Object = [Label, Fn] method. + * @name columns + * @memberOf dc.dataTable + * @instance + * @example + * chart.columns([ + * function(d) { return d.date; }, + * function(d) { return d.open; }, + * function(d) { return d.close; }, + * function(d) { return numberFormat(d.close - d.open); }, + * function(d) { return d.volume; } + * ]); + * @example + * chart.columns([ + * "date", // d["date"], ie, a field accessor; capitalized automatically + * "open", // ... + * "close", // ... + * ["Change", // Specify an Object = [Label, Fn] + * function (d) { return numberFormat(d.close - d.open); }], + * "volume" // d["volume"], ie, a field accessor; capitalized automatically + * ]); + * @example + * chart.columns([ + * ["Date", // Specify an Object = [Label, Fn] + * function (d) { return d.date; }], + * ["Open", + * function (d) { return numberFormat(d.open); }], + * ["Close", + * function (d) { return numberFormat(d.close); }], + * ["Change", + * function (d) { return numberFormat(d.close - d.open); }], + * ["Volume", + * function (d) { return d.volume; }] + * ]); + * @param {Array} [columns] + * @returns {Chart} + */ _chart.columns = function (_) { if (!arguments.length) { return _columns; @@ -300,17 +272,18 @@ dc.dataTable = function (parent, chartGroup) { }; /** - #### .sortBy([sortByFunction]) - Get or set sort-by function. This function works as a value accessor at row level and returns a - particular field to be sorted by. Default value: identity function - - ```js - chart.sortBy(function(d) { - return d.date; - }); - ``` - - **/ + * Get or set sort-by function. This function works as a value accessor at row level and returns a + * particular field to be sorted by. Default value: identity function + * @name sortBy + * @memberOf dc.dataTable + * @instance + * @example + * chart.sortBy(function(d) { + * return d.date; + * }); + * @param {Function} [sortBy] + * @returns {Chart} + */ _chart.sortBy = function (_) { if (!arguments.length) { return _sortBy; @@ -320,14 +293,15 @@ dc.dataTable = function (parent, chartGroup) { }; /** - #### .order([order]) - Get or set sort order. Default value: ``` d3.ascending ``` - - ```js - chart.order(d3.descending); - ``` - - **/ + * Get or set sort order. + * @name order + * @memberOf dc.dataTable + * @instance + * @example + * chart.order(d3.descending); + * @param {Function} [order=d3.ascending] + * @returns {Chart} + */ _chart.order = function (_) { if (!arguments.length) { return _order; @@ -337,17 +311,19 @@ dc.dataTable = function (parent, chartGroup) { }; /** - ### .showGroups(true|false) - Get or set if group rows will be shown. Default value ``` true ``` - The .group() getter-setter must be provided in either case. - - ```js - chart - .group([value], [name]) - .showGroups(true|false); - ``` - - **/ + * Get or set if group rows will be shown. + * + * The .group() getter-setter must be provided in either case. + * @name order + * @memberOf dc.dataTable + * @instance + * @example + * chart + * .group([value], [name]) + * .showGroups(true|false); + * @param {Boolean} [showGroups=true] + * @returns {Chart} + */ _chart.showGroups = function (_) { if (!arguments.length) { return true; diff --git a/src/events.js b/src/events.js index e893946c7..ebddcd596 100644 --- a/src/events.js +++ b/src/events.js @@ -3,23 +3,24 @@ dc.events = { }; /** -#### dc.events.trigger(function[, delay]) -This function triggers a throttled event function with a specified delay (in milli-seconds). Events -that are triggered repetitively due to user interaction such brush dragging might flood the library -and invoke more renders than can be executed in time. Using this function to wrap your event -function allows the library to smooth out the rendering by throttling events and only responding to -the most recent event. - -```js - chart.on('renderlet', function(chart) { - // smooth the rendering through event throttling - dc.events.trigger(function(){ - // focus some other chart to the range selected by user on this chart - someOtherChart.focus(chart.filter()); - }); - }) -``` -**/ + * This function triggers a throttled event function with a specified delay (in milli-seconds). Events + * that are triggered repetitively due to user interaction such brush dragging might flood the library + * and invoke more renders than can be executed in time. Using this function to wrap your event + * function allows the library to smooth out the rendering by throttling events and only responding to + * the most recent event. + * @name events.trigger + * @memberOf dc + * @example + * chart.on('renderlet', function(chart) { + * // smooth the rendering through event throttling + * dc.events.trigger(function(){ + * // focus some other chart to the range selected by user on this chart + * someOtherChart.focus(chart.filter()); + * }); + * }) + * @param {Function} closure + * @param {Number} [delay] + */ dc.events.trigger = function (closure, delay) { if (!delay) { closure(); diff --git a/src/filters.js b/src/filters.js index f8059370d..f40fb69df 100644 --- a/src/filters.js +++ b/src/filters.js @@ -1,23 +1,28 @@ -dc.filters = {}; - /** -## Filters -The dc.js filters are functions which are passed into crossfilter to chose which records will be -accumulated to produce values for the charts. In the crossfilter model, any filters applied on one -dimension will affect all the other dimensions but not that one. dc always applies a filter -function to the dimension; the function combines multiple filters and if any of them accept a -record, it is filtered in. - -These filter constructors are used as appropriate by the various charts to implement brushing. We -mention below which chart uses which filter. In some cases, many instances of a filter will be added. - -**/ + * The dc.js filters are functions which are passed into crossfilter to chose which records will be + * accumulated to produce values for the charts. In the crossfilter model, any filters applied on one + * dimension will affect all the other dimensions but not that one. dc always applies a filter + * function to the dimension; the function combines multiple filters and if any of them accept a + * record, it is filtered in. + * + * These filter constructors are used as appropriate by the various charts to implement brushing. We + * mention below which chart uses which filter. In some cases, many instances of a filter will be added. + * @name filters + * @memberOf dc + * @type {{}} + */ +dc.filters = {}; /** -#### dc.filters.RangedFilter(low, high) - RangedFilter is a filter which accepts keys between `low` and `high`. It is used to implement X - axis brushing for the [coordinate grid charts](#coordinate-grid-mixin). -**/ + * RangedFilter is a filter which accepts keys between `low` and `high`. It is used to implement X + * axis brushing for the [coordinate grid charts](#coordinate-grid-mixin). + * @name RangedFilter + * @memberOf dc.filters + * @param {Number} low + * @param {Number} high + * @returns {Array} + * @constructor + */ dc.filters.RangedFilter = function (low, high) { var range = new Array(low, high); range.isFiltered = function (value) { @@ -28,11 +33,15 @@ dc.filters.RangedFilter = function (low, high) { }; /** -#### dc.filters.TwoDimensionalFilter(array) - TwoDimensionalFilter is a filter which accepts a single two-dimensional value. It is used by the - [heat map chart](#heat-map) to include particular cells as they are clicked. (Rows and columns are - filtered by filtering all the cells in the row or column.) -**/ + * TwoDimensionalFilter is a filter which accepts a single two-dimensional value. It is used by the + * [heat map chart](#heat-map) to include particular cells as they are clicked. (Rows and columns are + * filtered by filtering all the cells in the row or column.) + * @name TwoDimensionalFilter + * @memberOf dc.filters + * @param {Array} filter + * @returns {Array} + * @constructor + */ dc.filters.TwoDimensionalFilter = function (array) { if (array === null) { return null; } @@ -46,18 +55,22 @@ dc.filters.TwoDimensionalFilter = function (array) { }; /** -#### dc.filters.RangedTwoDimensionalFilter(array) - The RangedTwoDimensionalFilter allows filtering all values which fit within a rectangular - region. It is used by the [scatter plot](#scatter-plot) to implement rectangular brushing. - - It takes two two-dimensional points in the form `[[x1,y1],[x2,y2]]`, and normalizes them so that - `x1 <= x2` and `y1 <- y2`. It then returns a filter which accepts any points which are in the - rectangular range including the lower values but excluding the higher values. - - If an array of two values are given to the RangedTwoDimensionalFilter, it interprets the values as - two x coordinates `x1` and `x2` and returns a filter which accepts any points for which `x1 <= x < - x2`. - **/ + * The RangedTwoDimensionalFilter allows filtering all values which fit within a rectangular + * region. It is used by the [scatter plot](#scatter-plot) to implement rectangular brushing. + * + * It takes two two-dimensional points in the form `[[x1,y1],[x2,y2]]`, and normalizes them so that + * `x1 <= x2` and `y1 <- y2`. It then returns a filter which accepts any points which are in the + * rectangular range including the lower values but excluding the higher values. + * + * If an array of two values are given to the RangedTwoDimensionalFilter, it interprets the values as + * two x coordinates `x1` and `x2` and returns a filter which accepts any points for which `x1 <= x < + * x2`. + * @name RangedTwoDimensionalFilter + * @memberOf dc.filters + * @param {Array>} filter + * @returns {Array>} + * @constructor + */ dc.filters.RangedTwoDimensionalFilter = function (array) { if (array === null) { return null; } diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index d93c9d06e..1a5fc4d79 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -9,7 +9,7 @@ chaining because they necessarily return values that are not the chart. Althoug such as `.svg` and `.xAxis`, return values that are chainable d3 objects. **Kind**: global namespace -**Version**: <%= conf.pkg.version %> +**Version**: 2.0.0-beta.17 **Example** ```js // Example chaining @@ -64,15 +64,8 @@ chart.width(300) * [.chartID](#dc.baseMixin+chartID) ⇒ String * [.options](#dc.baseMixin+options) ⇒ Chart * [.on](#dc.baseMixin+on) ⇒ Chart - * [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart - * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> - * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function - * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number - * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number - * [.capMixin](#dc.capMixin) ⇒ Chart - * [.cap](#dc.capMixin+cap) ⇒ Number - * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String - * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function + * [.marginMixin](#dc.marginMixin) ⇒ Chart + * [.margins](#dc.marginMixin+margins) ⇒ Chart * [.colorMixin](#dc.colorMixin) ⇒ Chart * [.colors](#dc.colorMixin+colors) ⇒ Chart * [.ordinalColors](#dc.colorMixin+ordinalColors) ⇒ Chart @@ -82,8 +75,38 @@ chart.width(300) * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart * [.getColor](#dc.colorMixin+getColor) ⇒ String * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* - * [.marginMixin](#dc.marginMixin) ⇒ Chart - * [.margins](#dc.marginMixin+margins) ⇒ Chart + * [.coordinateGridMixin](#dc.coordinateGridMixin) ⇒ Chart + * [.rescale](#dc.coordinateGridMixin+rescale) ⇒ Chart + * [.rangeChart](#dc.coordinateGridMixin+rangeChart) ⇒ Chart + * [.zoomScale](#dc.coordinateGridMixin+zoomScale) ⇒ Chart + * [.zoomOutRestrict](#dc.coordinateGridMixin+zoomOutRestrict) ⇒ Chart + * [.g](#dc.coordinateGridMixin+g) ⇒ Chart + * [.mouseZoomable](#dc.coordinateGridMixin+mouseZoomable) ⇒ Chart + * [.chartBodyG](#dc.coordinateGridMixin+chartBodyG) ⇒ Chart + * [.x](#dc.coordinateGridMixin+x) ⇒ Chart + * [.xUnits](#dc.coordinateGridMixin+xUnits) ⇒ Chart + * [.xAxis](#dc.coordinateGridMixin+xAxis) ⇒ Chart + * [.elasticX](#dc.coordinateGridMixin+elasticX) ⇒ Chart + * [.xAxisPadding](#dc.coordinateGridMixin+xAxisPadding) ⇒ Chart + * [.xUnitCount](#dc.coordinateGridMixin+xUnitCount) ⇒ Number + * [.useRightYAxis](#dc.coordinateGridMixin+useRightYAxis) ⇒ Chart + * [.isOrdinal](#dc.coordinateGridMixin+isOrdinal) ⇒ Boolean + * [.xAxisLabel](#dc.coordinateGridMixin+xAxisLabel) ⇒ Chart + * [.yAxisLabel](#dc.coordinateGridMixin+yAxisLabel) ⇒ Chart + * [.y](#dc.coordinateGridMixin+y) ⇒ Chart + * [.yAxis](#dc.coordinateGridMixin+yAxis) ⇒ Chart + * [.elasticY](#dc.coordinateGridMixin+elasticY) ⇒ Chart + * [.renderHorizontalGridLines](#dc.coordinateGridMixin+renderHorizontalGridLines) ⇒ Chart + * [.renderVerticalGridLines](#dc.coordinateGridMixin+renderVerticalGridLines) ⇒ Chart + * [.xAxisMin](#dc.coordinateGridMixin+xAxisMin) ⇒ \* + * [.xAxisMax](#dc.coordinateGridMixin+xAxisMax) ⇒ \* + * [.yAxisMin](#dc.coordinateGridMixin+yAxisMin) ⇒ \* + * [.yAxisMax](#dc.coordinateGridMixin+yAxisMax) ⇒ \* + * [.yAxisPadding](#dc.coordinateGridMixin+yAxisPadding) ⇒ Chart + * [.round](#dc.coordinateGridMixin+round) ⇒ Chart + * [.clipPadding](#dc.coordinateGridMixin+clipPadding) ⇒ Chart + * [.focus](#dc.coordinateGridMixin+focus) + * [.brushOn](#dc.coordinateGridMixin+brushOn) ⇒ Chart * [.stackMixin](#dc.stackMixin) ⇒ Chart * [.stack](#dc.stackMixin+stack) ⇒ Chart * [.hidableStacks](#dc.stackMixin+hidableStacks) ⇒ Chart @@ -91,22 +114,15 @@ chart.width(300) * [.showStack](#dc.stackMixin+showStack) ⇒ Chart * [.title](#dc.stackMixin+title) ⇒ Chart * [.stackLayout](#dc.stackMixin+stackLayout) ⇒ Chart - * [.barChart](#dc.barChart) ⇒ BarChart - * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean - * [.barPadding](#dc.barChart+barPadding) ⇒ Number - * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number - * [.gap](#dc.barChart+gap) ⇒ Number - * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean - * [.boxPlot](#dc.boxPlot) ⇒ BoxPlot - * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number - * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number - * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function - * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function - * [.bubbleChart](#dc.bubbleChart) ⇒ BubbleChart - * [.elasticRadius](#dc.bubbleChart+elasticRadius) ⇒ Boolean - * [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay - * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart - * [.point](#dc.bubbleOverlay+point) ⇒ Chart + * [.capMixin](#dc.capMixin) ⇒ Chart + * [.cap](#dc.capMixin+cap) ⇒ Number + * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String + * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function + * [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart + * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> + * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function + * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number + * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number * [.filterAll](#dc.filterAll) * [.refocusAll](#dc.refocusAll) * [.renderAll](#dc.renderAll) @@ -117,44 +133,13 @@ chart.width(300) * [.ordinal](#dc.units.ordinal) ⇒ Array.<String> * [.fp](#dc.units.fp) : Object * [.precision](#dc.units.fp.precision) ⇒ function - * [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart - * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart - * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart - * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> - * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path - * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart - * [.heatMap](#dc.heatMap) ⇒ HeatMap - * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart - * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart - * [.rows](#dc.heatMap+rows) ⇒ Chart - * [.cols](#dc.heatMap+cols) ⇒ Chart - * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart - * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart - * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart - * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart - * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart - * [.legend](#dc.legend) ⇒ Legend - * [.x](#dc.legend+x) ⇒ Legend - * [.y](#dc.legend+y) ⇒ Legend - * [.gap](#dc.legend+gap) ⇒ Legend - * [.itemHeight](#dc.legend+itemHeight) ⇒ Legend - * [.horizontal](#dc.legend+horizontal) ⇒ Legend - * [.legendWidth](#dc.legend+legendWidth) ⇒ Legend - * [.itemWidth](#dc.legend+itemWidth) ⇒ Legend - * [.autoItemWidth](#dc.legend+autoItemWidth) ⇒ Legend - * [.lineChart](#dc.lineChart) ⇒ LineChart - * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart - * [.tension](#dc.lineChart+tension) ⇒ Chart - * [.defined](#dc.lineChart+defined) ⇒ Chart - * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart - * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart - * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart - * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart - * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart - * [.numberDisplay](#dc.numberDisplay) ⇒ NumberDisplay - * [.html](#dc.numberDisplay+html) ⇒ Chart - * [.value](#dc.numberDisplay+value) ⇒ Number - * [.formatNumber](#dc.numberDisplay+formatNumber) ⇒ Chart + * [.filters](#dc.filters) : Object + * [.RangedFilter](#dc.filters.RangedFilter) + * [new RangedFilter(low, high)](#new_dc.filters.RangedFilter_new) + * [.TwoDimensionalFilter](#dc.filters.TwoDimensionalFilter) + * [new TwoDimensionalFilter(filter)](#new_dc.filters.TwoDimensionalFilter_new) + * [.RangedTwoDimensionalFilter](#dc.filters.RangedTwoDimensionalFilter) + * [new RangedTwoDimensionalFilter(filter)](#new_dc.filters.RangedTwoDimensionalFilter_new) * [.pieChart](#dc.pieChart) ⇒ PieChart * [.slicesCap](#dc.pieChart+slicesCap) ⇒ Chart * [.externalRadiusPadding](#dc.pieChart+externalRadiusPadding) ⇒ Chart @@ -165,6 +150,64 @@ chart.width(300) * [.minAngleForLabel](#dc.pieChart+minAngleForLabel) ⇒ Chart * [.emptyTitle](#dc.pieChart+emptyTitle) ⇒ Chart * [.externalLabels](#dc.pieChart+externalLabels) ⇒ Chart + * [.barChart](#dc.barChart) ⇒ BarChart + * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean + * [.barPadding](#dc.barChart+barPadding) ⇒ Number + * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number + * [.gap](#dc.barChart+gap) ⇒ Number + * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean + * [.lineChart](#dc.lineChart) ⇒ LineChart + * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart + * [.tension](#dc.lineChart+tension) ⇒ Chart + * [.defined](#dc.lineChart+defined) ⇒ Chart + * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart + * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart + * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart + * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart + * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart + * [.dataCount](#dc.dataCount) ⇒ DataCount + * [.html](#dc.dataCount+html) ⇒ Chart + * [.formatNumber](#dc.dataCount+formatNumber) ⇒ Chart + * [.dataTable](#dc.dataTable) ⇒ DataTable + * [.size](#dc.dataTable+size) ⇒ Chart + * [.columns](#dc.dataTable+columns) ⇒ Chart + * [.sortBy](#dc.dataTable+sortBy) ⇒ Chart + * [.order](#dc.dataTable+order) ⇒ Chart + * [.order](#dc.dataTable+order) ⇒ Chart + * [.dataGrid](#dc.dataGrid) ⇒ DataGrid + * [.beginSlice](#dc.dataGrid+beginSlice) ⇒ Chart + * [.endSlice](#dc.dataGrid+endSlice) ⇒ Chart + * [.size](#dc.dataGrid+size) ⇒ Chart + * [.html](#dc.dataGrid+html) ⇒ Chart + * [.htmlGroup](#dc.dataGrid+htmlGroup) ⇒ Chart + * [.sortBy](#dc.dataGrid+sortBy) ⇒ Chart + * [.order](#dc.dataGrid+order) ⇒ Chart + * [.bubbleChart](#dc.bubbleChart) ⇒ BubbleChart + * [.elasticRadius](#dc.bubbleChart+elasticRadius) ⇒ Boolean + * [.compositeChart](#dc.compositeChart) ⇒ CompositeChart + * [.useRightAxisGridLines](#dc.compositeChart+useRightAxisGridLines) ⇒ Chart + * [.childOptions](#dc.compositeChart+childOptions) ⇒ Chart + * [.rightYAxisLabel](#dc.compositeChart+rightYAxisLabel) ⇒ Chart + * [.compose](#dc.compositeChart+compose) ⇒ Chart + * [.children](#dc.compositeChart+children) ⇒ Array.<Chart> + * [.shareColors](#dc.compositeChart+shareColors) ⇒ Chart + * [.shareTitle](#dc.compositeChart+shareTitle) ⇒ Chart + * [.rightY](#dc.compositeChart+rightY) ⇒ Chart + * [.rightYAxis](#dc.compositeChart+rightYAxis) ⇒ Chart + * [.seriesChart](#dc.seriesChart) ⇒ SeriesChart + * [.chart](#dc.seriesChart+chart) ⇒ Chart + * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart + * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart + * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart + * [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart + * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart + * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart + * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> + * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path + * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart + * [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay + * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart + * [.point](#dc.bubbleOverlay+point) ⇒ Chart * [.rowChart](#dc.rowChart) ⇒ RowChart * [.x](#dc.rowChart+x) ⇒ Chart * [.renderTitleLabel](#dc.rowChart+renderTitleLabel) ⇒ Chart @@ -175,17 +218,40 @@ chart.width(300) * [.labelOffsetX](#dc.rowChart+labelOffsetX) ⇒ Chart * [.labelOffsetY](#dc.rowChart+labelOffsetY) ⇒ Chart * [.titleLabelOffsetX](#dc.rowChart+titleLabelOffsetX) ⇒ Chart + * [.legend](#dc.legend) ⇒ Legend + * [.x](#dc.legend+x) ⇒ Legend + * [.y](#dc.legend+y) ⇒ Legend + * [.gap](#dc.legend+gap) ⇒ Legend + * [.itemHeight](#dc.legend+itemHeight) ⇒ Legend + * [.horizontal](#dc.legend+horizontal) ⇒ Legend + * [.legendWidth](#dc.legend+legendWidth) ⇒ Legend + * [.itemWidth](#dc.legend+itemWidth) ⇒ Legend + * [.autoItemWidth](#dc.legend+autoItemWidth) ⇒ Legend * [.scatterPlot](#dc.scatterPlot) ⇒ SeriesChart * [.existenceAccessor](#dc.scatterPlot+existenceAccessor) ⇒ Chart * [.symbol](#dc.scatterPlot+symbol) ⇒ Chart * [.symbolSize](#dc.scatterPlot+symbolSize) ⇒ Chart * [.highlightedSize](#dc.scatterPlot+highlightedSize) ⇒ Chart * [.hiddenSize](#dc.scatterPlot+hiddenSize) ⇒ Chart - * [.seriesChart](#dc.seriesChart) ⇒ SeriesChart - * [.chart](#dc.seriesChart+chart) ⇒ Chart - * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart - * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart - * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart + * [.numberDisplay](#dc.numberDisplay) ⇒ NumberDisplay + * [.html](#dc.numberDisplay+html) ⇒ Chart + * [.value](#dc.numberDisplay+value) ⇒ Number + * [.formatNumber](#dc.numberDisplay+formatNumber) ⇒ Chart + * [.heatMap](#dc.heatMap) ⇒ HeatMap + * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart + * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart + * [.rows](#dc.heatMap+rows) ⇒ Chart + * [.cols](#dc.heatMap+cols) ⇒ Chart + * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart + * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart + * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart + * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart + * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart + * [.boxPlot](#dc.boxPlot) ⇒ BoxPlot + * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number + * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number + * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function + * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function ### dc.baseMixin ⇒ Chart @@ -918,200 +984,95 @@ including all renderlets' logic. .on('filtered', function(chart, filter){...}) .on('zoomed', function(chart, filter){...}) ``` - -### dc.bubbleMixin ⇒ Chart -This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. + +### dc.marginMixin ⇒ Chart +Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid +Charts. **Kind**: static mixin of [dc](#dc) -**Mixes**: colorMixin | Param | Type | | --- | --- | | _chart | Chart | + +#### marginMixin.margins ⇒ Chart +Get or set the margins for a particular coordinate grid chart instance. The margins is stored as +an associative Javascript array. -* [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart - * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> - * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function - * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number - * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number - - -#### bubbleMixin.r ⇒ Array.<Number> -Get or set the bubble radius scale. By default the bubble chart uses -`d3.scale.linear().domain([0, 100])` as its r scale . - -**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) +**Kind**: instance property of [marginMixin](#dc.marginMixin) -| Param | Type | -| --- | --- | -| [bubbleRadiusScale] | Array.<Number> | +| Param | Type | Default | +| --- | --- | --- | +| [margins] | Object | {top: 10, right: 50, bottom: 30, left: 30} | - -#### bubbleMixin.radiusValueAccessor ⇒ function -Get or set the radius value accessor function. If set, the radius value accessor function will -be used to retrieve a data value for each bubble. The data retrieved then will be mapped using -the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble -size. +**Example** +```js +var leftMargin = chart.margins().left; // 30 by default +chart.margins().left = 50; +leftMargin = chart.margins().left; // now 50 +``` + +### dc.colorMixin ⇒ Chart +The Color Mixin is an abstract chart functional class providing universal coloring support +as a mix-in for any concrete chart implementation. -**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) +**Kind**: static mixin of [dc](#dc) | Param | Type | | --- | --- | -| [radiusValueAccessor] | function | - - -#### bubbleMixin.minRadiusWithLabel ⇒ Number -Get or set the minimum radius for label rendering. If a bubble's radius is less than this value -then no label will be rendered. +| _chart | Chart | -**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) -| Param | Type | Default | -| --- | --- | --- | -| [radius] | Number | 10 | +* [.colorMixin](#dc.colorMixin) ⇒ Chart + * [.colors](#dc.colorMixin+colors) ⇒ Chart + * [.ordinalColors](#dc.colorMixin+ordinalColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ Chart + * [.linearColors](#dc.colorMixin+linearColors) ⇒ function + * [.colorDomain](#dc.colorMixin+colorDomain) ⇒ function + * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart + * [.getColor](#dc.colorMixin+getColor) ⇒ String + * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* - -#### bubbleMixin.maxBubbleRelativeSize ⇒ Number -Get or set the maximum relative size of a bubble to the length of x axis. This value is useful -when the difference in radius between bubbles is too great. + +#### colorMixin.colors ⇒ Chart +Retrieve current color scale or set a new color scale. This methods accepts any function that +operates like a d3 scale. -**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) +**Kind**: instance property of [colorMixin](#dc.colorMixin) | Param | Type | Default | | --- | --- | --- | -| [relativeSize] | Number | 0.3 | +| [colorScale] | D3Scale | d3.scale.category20c() | - -### dc.capMixin ⇒ Chart -Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the -Row and Pie Charts. +**Example** +```js +// alternate categorical scale +chart.colors(d3.scale.category20b()); -The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest -will be replaced with an *others* element, with value equal to the sum of the replaced values. The -keys of the elements below the cap limit are recorded in order to filter by those keys when the -others* element is clicked. +// ordinal scale +chart.colors(d3.scale.ordinal().range(['red','green','blue'])); +// convenience method, the same as above +chart.ordinalColors(['red','green','blue']); -**Kind**: static mixin of [dc](#dc) +// set a linear scale +chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); +``` + +#### colorMixin.ordinalColors ⇒ Chart +Convenience method to set the color scale to d3.scale.ordinal with range `r`. + +**Kind**: instance property of [colorMixin](#dc.colorMixin) | Param | Type | | --- | --- | -| _chart | Chart | +| r | Array.<String> | + +#### colorMixin.linearColors ⇒ Chart +Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. -* [.capMixin](#dc.capMixin) ⇒ Chart - * [.cap](#dc.capMixin+cap) ⇒ Number - * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String - * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function - - -#### capMixin.cap ⇒ Number -Get or set the count of elements to that will be included in the cap. - -**Kind**: instance property of [capMixin](#dc.capMixin) - -| Param | Type | Default | -| --- | --- | --- | -| [count] | Number | Infinity | - - -#### capMixin.othersLabel ⇒ String -Get or set the label for *Others* slice when slices cap is specified - -**Kind**: instance property of [capMixin](#dc.capMixin) - -| Param | Type | Default | -| --- | --- | --- | -| [label] | String | Others | - - -#### capMixin.othersGrouper ⇒ function -Get or set the grouper function that will perform the insertion of data for the *Others* slice -if the slices cap is specified. If set to a falsy value, no others will be added. By default the -grouper function computes the sum of all values below the cap. - -**Kind**: instance property of [capMixin](#dc.capMixin) - -| Param | Type | -| --- | --- | -| [grouperFunction] | function | - -**Example** -```js -chart.othersGrouper(function (data) { - // compute the value for others, presumably the sum of all values below the cap - var othersSum = yourComputeOthersValueLogic(data) - - // the keys are needed to properly filter when the others element is clicked - var othersKeys = yourComputeOthersKeysArrayLogic(data); - - // add the others row to the dataset - data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); - - return data; -}); -``` - -### dc.colorMixin ⇒ Chart -The Color Mixin is an abstract chart functional class providing universal coloring support -as a mix-in for any concrete chart implementation. - -**Kind**: static mixin of [dc](#dc) - -| Param | Type | -| --- | --- | -| _chart | Chart | - - -* [.colorMixin](#dc.colorMixin) ⇒ Chart - * [.colors](#dc.colorMixin+colors) ⇒ Chart - * [.ordinalColors](#dc.colorMixin+ordinalColors) ⇒ Chart - * [.linearColors](#dc.colorMixin+linearColors) ⇒ Chart - * [.linearColors](#dc.colorMixin+linearColors) ⇒ function - * [.colorDomain](#dc.colorMixin+colorDomain) ⇒ function - * [.calculateColorDomain](#dc.colorMixin+calculateColorDomain) ⇒ Chart - * [.getColor](#dc.colorMixin+getColor) ⇒ String - * [.colorCalculator](#dc.colorMixin+colorCalculator) ⇒ \* - - -#### colorMixin.colors ⇒ Chart -Retrieve current color scale or set a new color scale. This methods accepts any function that -operates like a d3 scale. - -**Kind**: instance property of [colorMixin](#dc.colorMixin) - -| Param | Type | Default | -| --- | --- | --- | -| [colorScale] | D3Scale | d3.scale.category20c() | - -**Example** -```js -// alternate categorical scale -chart.colors(d3.scale.category20b()); - -// ordinal scale -chart.colors(d3.scale.ordinal().range(['red','green','blue'])); -// convenience method, the same as above -chart.ordinalColors(['red','green','blue']); - -// set a linear scale -chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]); -``` - -#### colorMixin.ordinalColors ⇒ Chart -Convenience method to set the color scale to d3.scale.ordinal with range `r`. - -**Kind**: instance property of [colorMixin](#dc.colorMixin) - -| Param | Type | -| --- | --- | -| r | Array.<String> | - - -#### colorMixin.linearColors ⇒ Chart -Convenience method to set the color scale to an Hcl interpolated linear scale with range `r`. - -**Kind**: instance property of [colorMixin](#dc.colorMixin) +**Kind**: instance property of [colorMixin](#dc.colorMixin) | Param | Type | | --- | --- | @@ -1177,464 +1138,720 @@ Get the color for the datum d and counter i. This is used internally by charts t | --- | --- | | [value] | \* | - -### dc.marginMixin ⇒ Chart -Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid -Charts. + +### dc.coordinateGridMixin ⇒ Chart +Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based +concrete chart types, e.g. bar chart, line chart, and bubble chart. **Kind**: static mixin of [dc](#dc) +**Mixes**: colorMixin,marginMixin,baseMixin | Param | Type | | --- | --- | | _chart | Chart | - -#### marginMixin.margins ⇒ Chart -Get or set the margins for a particular coordinate grid chart instance. The margins is stored as -an associative Javascript array. -**Kind**: instance property of [marginMixin](#dc.marginMixin) +* [.coordinateGridMixin](#dc.coordinateGridMixin) ⇒ Chart + * [.rescale](#dc.coordinateGridMixin+rescale) ⇒ Chart + * [.rangeChart](#dc.coordinateGridMixin+rangeChart) ⇒ Chart + * [.zoomScale](#dc.coordinateGridMixin+zoomScale) ⇒ Chart + * [.zoomOutRestrict](#dc.coordinateGridMixin+zoomOutRestrict) ⇒ Chart + * [.g](#dc.coordinateGridMixin+g) ⇒ Chart + * [.mouseZoomable](#dc.coordinateGridMixin+mouseZoomable) ⇒ Chart + * [.chartBodyG](#dc.coordinateGridMixin+chartBodyG) ⇒ Chart + * [.x](#dc.coordinateGridMixin+x) ⇒ Chart + * [.xUnits](#dc.coordinateGridMixin+xUnits) ⇒ Chart + * [.xAxis](#dc.coordinateGridMixin+xAxis) ⇒ Chart + * [.elasticX](#dc.coordinateGridMixin+elasticX) ⇒ Chart + * [.xAxisPadding](#dc.coordinateGridMixin+xAxisPadding) ⇒ Chart + * [.xUnitCount](#dc.coordinateGridMixin+xUnitCount) ⇒ Number + * [.useRightYAxis](#dc.coordinateGridMixin+useRightYAxis) ⇒ Chart + * [.isOrdinal](#dc.coordinateGridMixin+isOrdinal) ⇒ Boolean + * [.xAxisLabel](#dc.coordinateGridMixin+xAxisLabel) ⇒ Chart + * [.yAxisLabel](#dc.coordinateGridMixin+yAxisLabel) ⇒ Chart + * [.y](#dc.coordinateGridMixin+y) ⇒ Chart + * [.yAxis](#dc.coordinateGridMixin+yAxis) ⇒ Chart + * [.elasticY](#dc.coordinateGridMixin+elasticY) ⇒ Chart + * [.renderHorizontalGridLines](#dc.coordinateGridMixin+renderHorizontalGridLines) ⇒ Chart + * [.renderVerticalGridLines](#dc.coordinateGridMixin+renderVerticalGridLines) ⇒ Chart + * [.xAxisMin](#dc.coordinateGridMixin+xAxisMin) ⇒ \* + * [.xAxisMax](#dc.coordinateGridMixin+xAxisMax) ⇒ \* + * [.yAxisMin](#dc.coordinateGridMixin+yAxisMin) ⇒ \* + * [.yAxisMax](#dc.coordinateGridMixin+yAxisMax) ⇒ \* + * [.yAxisPadding](#dc.coordinateGridMixin+yAxisPadding) ⇒ Chart + * [.round](#dc.coordinateGridMixin+round) ⇒ Chart + * [.clipPadding](#dc.coordinateGridMixin+clipPadding) ⇒ Chart + * [.focus](#dc.coordinateGridMixin+focus) + * [.brushOn](#dc.coordinateGridMixin+brushOn) ⇒ Chart -| Param | Type | Default | -| --- | --- | --- | -| [margins] | Object | {top: 10, right: 50, bottom: 30, left: 30} | + +#### coordinateGridMixin.rescale ⇒ Chart +When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate +and redraw the axes. (`.rescale()` is called automatically when the x or y scale is replaced +with `.x()` or `.y()`, and has no effect on elastic scales.) -**Example** -```js -var leftMargin = chart.margins().left; // 30 by default -chart.margins().left = 50; -leftMargin = chart.margins().left; // now 50 -``` - -### dc.stackMixin ⇒ Chart -Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.rangeChart ⇒ Chart +Get or set the range selection chart associated with this instance. Setting the range selection +chart using this function will automatically update its selection brush when the current chart +zooms in. In return the given range chart will also automatically attach this chart as its focus +chart hence zoom in when range brush updates. See the [Nasdaq 100 +Index](http://dc-js.github.com/dc.js/) example for this effect in action. -**Kind**: static mixin of [dc](#dc) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| _chart | Chart | +| [rangeChart] | Chart | + +#### coordinateGridMixin.zoomScale ⇒ Chart +Get or set the scale extent for mouse zooms. -* [.stackMixin](#dc.stackMixin) ⇒ Chart - * [.stack](#dc.stackMixin+stack) ⇒ Chart - * [.hidableStacks](#dc.stackMixin+hidableStacks) ⇒ Chart - * [.hideStack](#dc.stackMixin+hideStack) ⇒ Chart - * [.showStack](#dc.stackMixin+showStack) ⇒ Chart - * [.title](#dc.stackMixin+title) ⇒ Chart - * [.stackLayout](#dc.stackMixin+stackLayout) ⇒ Chart +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### stackMixin.stack ⇒ Chart -Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks -in the same chart will share the same key accessor and therefore the same set of keys. +| Param | Type | +| --- | --- | +| [extent] | Array.<\*> | -For example, in a stacked bar chart, the bars of each stack will be positioned using the same set -of keys on the x axis, while stacked vertically. If name is specified then it will be used to -generate the legend label. + +#### coordinateGridMixin.zoomOutRestrict ⇒ Chart +Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart. -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| group | CrossfilterGroup | -| [name] | String | -| [accessor] | function | +| [zoomOutRestrict] | Boolean | -**Example** -```js -// stack group using default accessor -chart.stack(valueSumGroup) -// stack group using custom accessor -.stack(avgByDayGroup, function(d){return d.value.avgByDay;}); -``` - -#### stackMixin.hidableStacks ⇒ Chart -Allow named stacks to be hidden or shown by clicking on legend items. -This does not affect the behavior of hideStack or showStack. + +#### coordinateGridMixin.g ⇒ Chart +Get or set the root g element. This method is usually used to retrieve the g element in order to +overlay custom svg drawing programatically. **Caution**: The root g element is usually generated +by dc.js internals, and resetting it might produce unpredictable result. -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| hidableStacks | Boolean | +| [gElement] | svg | - -#### stackMixin.hideStack ⇒ Chart -Hide all stacks on the chart with the given name. -The chart must be re-rendered for this change to appear. + +#### coordinateGridMixin.mouseZoomable ⇒ Chart +Set or get mouse zoom capability flag (default: false). When turned on the chart will be +zoomable using the mouse wheel. If the range selector chart is attached zooming will also update +the range selection brush on the associated range selector chart. -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| stackName | String | +| [mouseZoomable] | Boolean | - -#### stackMixin.showStack ⇒ Chart -Show all stacks on the chart with the given name. -The chart must be re-rendered for this change to appear. + +#### coordinateGridMixin.chartBodyG ⇒ Chart +Retrieve the svg group for the chart body. -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| stackName | String | +| [chartBodyG] | svg | - -#### stackMixin.title ⇒ Chart -Set or get the title function. Chart class will use this function to render svg title (usually interpreted by -browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. -Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to -use title otherwise the brush layer will block tooltip trigger. + +#### coordinateGridMixin.x ⇒ Chart +**mandatory** -If the first argument is a stack name, the title function will get or set the title for that stack. If stackName -is not provided, the first stack is implied. +Get or set the x scale. The x scale can be any d3 +[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) or +[ordinal scale](https://github.com/mbostock/d3/wiki/Ordinal-Scales). -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| [stackName] | String | -| [titleAccessor] | function | +| [xScale] | d3.scale | **Example** ```js -// set a title function on 'first stack' -chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); -// get a title function from 'second stack' -var secondTitleFunction = chart.title('second stack'); +// set x to a linear scale +chart.x(d3.scale.linear().domain([-2500, 2500])) +// set x to a time scale to generate histogram +chart.x(d3.time.scale().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)])) ``` - -#### stackMixin.stackLayout ⇒ Chart -Gets or sets the stack layout algorithm, which computes a baseline for each stack and -propagates it to the next + +#### coordinateGridMixin.xUnits ⇒ Chart +Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate +the number of data projections on x axis such as the number of bars for a bar chart or the +number of dots for a line chart. This function is expected to return a Javascript array of all +data points on x axis, or the number of points on the axis. [d3 time range functions +d3.time.days, d3.time.months, and +d3.time.years](https://github.com/mbostock/d3/wiki/Time-Intervals#aliases) are all valid xUnits +function. dc.js also provides a few units function, see the [Utilities](#utilities) section for +a list of built-in units functions. The default xUnits function is dc.units.integers. -**Kind**: instance property of [stackMixin](#dc.stackMixin) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -| Param | Type | Default | -| --- | --- | --- | -| [stack] | function | d3.layout.stack | +| Param | Type | +| --- | --- | +| [xUnits] | function | - -### dc.barChart ⇒ BarChart -Concrete bar chart/histogram implementation. -Examples: -- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) +**Example** +```js +// set x units to count days +chart.xUnits(d3.time.days); +// set x units to count months +chart.xUnits(d3.time.months); + +// A custom xUnits function can be used as long as it follows the following interface: +// units in integer +function(start, end, xDomain) { + // simply calculates how many integers in the domain + return Math.abs(end - start); +}; + +// fixed units +function(start, end, xDomain) { + // be aware using fixed units will disable the focus/zoom ability on the chart + return 1000; +``` + +#### coordinateGridMixin.xAxis ⇒ Chart +Set or get the x axis used by a particular coordinate grid chart instance. This function is most +useful when x axis customization is required. The x axis in dc.js is an instance of a [d3 +axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis); therefore it supports any +valid d3 axis manipulation. **Caution**: The x axis is usually generated internally by dc; +resetting it may cause unexpected results. -**Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +| Param | Type | +| --- | --- | +| [xAxis] | d3.svg.axis | **Example** ```js -// create a bar chart under #chart-container1 element using the default global chart group -var chart1 = dc.barChart('#chart-container1'); -// create a bar chart under #chart-container2 element using chart group A -var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.barChart(compositeChart); +// customize x axis tick format +chart.xAxis().tickFormat(function(v) {return v + '%';}); +// customize x axis tick values +chart.xAxis().tickValues([0, 100, 200, 300]); ``` + +#### coordinateGridMixin.elasticX ⇒ Chart +Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will +attempt to recalculate the x axis range whenever a redraw event is triggered. -* [.barChart](#dc.barChart) ⇒ BarChart - * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean - * [.barPadding](#dc.barChart+barPadding) ⇒ Number - * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number - * [.gap](#dc.barChart+gap) ⇒ Number - * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean - - -#### barChart.centerBar ⇒ Boolean -Whether the bar chart will render each bar centered around the data position on x axis +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -**Kind**: instance property of [barChart](#dc.barChart) +| Param | Type | +| --- | --- | +| [elasticX] | Boolean | -| Param | Type | Default | -| --- | --- | --- | -| [centerBar] | Boolean | false | + +#### coordinateGridMixin.xAxisPadding ⇒ Chart +Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x +axis if elasticX is turned on; otherwise it is ignored. - -#### barChart.barPadding ⇒ Number -Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. -Setting this value will also remove any previously set `gap`. See the -[d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) -for a visual description of how the padding is applied. +padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to +number or date x axes. When padding a date axis, an integer represents number of days being padded +and a percentage string will be treated the same as an integer. -**Kind**: instance property of [barChart](#dc.barChart) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| [barPadding] | Number | +| [padding] | Number | String | - -#### barChart.outerPadding ⇒ Number -Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. -Will pad the width by `padding * barWidth` on each side of the chart. + +#### coordinateGridMixin.xUnitCount ⇒ Number +Returns the number of units displayed on the x axis using the unit measure configured by +.xUnits. -**Kind**: instance property of [barChart](#dc.barChart) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.useRightYAxis ⇒ Chart +Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When +used with a chart in a composite chart, allows both left and right Y axes to be shown on a +chart. -| Param | Type | Default | -| --- | --- | --- | -| [padding] | Number | 0.5 | +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### barChart.gap ⇒ Number -Manually set fixed gap (in px) between bars instead of relying on the default auto-generated -gap. By default the bar chart implementation will calculate and set the gap automatically -based on the number of data points and the length of the x axis. +| Param | Type | +| --- | --- | +| [useRightYAxis] | Boolean | -**Kind**: instance property of [barChart](#dc.barChart) + +#### coordinateGridMixin.isOrdinal ⇒ Boolean +Returns true if the chart is using ordinal xUnits ([dc.units.ordinal](#dcunitsordinal)), or false +otherwise. Most charts behave differently with ordinal data and use the result of this method to +trigger the appropriate logic. + +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.xAxisLabel ⇒ Chart +Set or get the x axis label. If setting the label, you may optionally include additional padding to +the margin to make room for the label. By default the padded is set to 12 to accomodate the text height. + +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Default | | --- | --- | --- | -| [gap] | Number | 2 | +| [labelText] | String | | +| [padding] | Number | 12 | - -#### barChart.alwaysUseRounding ⇒ Boolean -Set or get whether rounding is enabled when bars are centered. Default: false. If false, using -rounding with centered bars will result in a warning and rounding will be ignored. This flag -has no effect if bars are not centered. -When using standard d3.js rounding methods, the brush often doesn't align correctly with -centered bars since the bars are offset. The rounding function must add an offset to -compensate, such as in the following example. + +#### coordinateGridMixin.yAxisLabel ⇒ Chart +Set or get the y axis label. If setting the label, you may optionally include additional padding +to the margin to make room for the label. By default the padded is set to 12 to accomodate the +text height. -**Kind**: instance property of [barChart](#dc.barChart) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Default | | --- | --- | --- | -| [alwaysUseRounding] | Boolean | false | +| [labelText] | String | | +| [padding] | Number | 12 | -**Example** -```js -chart.round(function(n) {return Math.floor(n)+0.5}); -``` - -### dc.boxPlot ⇒ BoxPlot -A box plot is a chart that depicts numerical data via their quartile ranges. -Examples: -- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +#### coordinateGridMixin.y ⇒ Chart +Get or set the y scale. The y scale is typically automatically determined by the chart implementation. -**Kind**: static property of [dc](#dc) -**Mixes**: coordinateGridMixin +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +| Param | Type | +| --- | --- | +| [y] | d3.scale | + + +#### coordinateGridMixin.yAxis ⇒ Chart +Set or get the y axis used by the coordinate grid chart instance. This function is most useful +when y axis customization is required. The y axis in dc.js is simply an instance of a [d3 axis +object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis); therefore it supports any +valid d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; +resetting it may cause unexpected results. + +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +| Param | Type | +| --- | --- | +| [yAxis] | d3.svg.axis | **Example** ```js -// create a box plot under #chart-container1 element using the default global chart group -var boxPlot1 = dc.boxPlot('#chart-container1'); -// create a box plot under #chart-container2 element using chart group A -var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); +// customize y axis tick format +chart.yAxis().tickFormat(function(v) {return v + '%';}); +// customize y axis tick values +chart.yAxis().tickValues([0, 100, 200, 300]); ``` + +#### coordinateGridMixin.elasticY ⇒ Chart +Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will +attempt to recalculate the y axis range whenever a redraw event is triggered. -* [.boxPlot](#dc.boxPlot) ⇒ BoxPlot - * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number - * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number - * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function - * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### boxPlot.boxPadding ⇒ Number -Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. -See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) -for a visual description of how the padding is applied. +| Param | Type | +| --- | --- | +| [elasticY] | Boolean | -**Kind**: instance property of [boxPlot](#dc.boxPlot) + +#### coordinateGridMixin.renderHorizontalGridLines ⇒ Chart +Turn on/off horizontal grid lines. -| Param | Type | Default | -| --- | --- | --- | -| [padding] | Number | 0.8 | +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### boxPlot.outerPadding ⇒ Number -Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts -or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. +| Param | Type | +| --- | --- | +| [renderHorizontalGridLines] | Boolean | -**Kind**: instance property of [boxPlot](#dc.boxPlot) + +#### coordinateGridMixin.renderVerticalGridLines ⇒ Chart +Turn on/off vertical grid lines. -| Param | Type | Default | -| --- | --- | --- | -| [padding] | Number | 0.5 | +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### boxPlot.boxWidth ⇒ Number | function -Get or set the numerical width of the boxplot box. The width may also be a function taking as -parameters the chart width excluding the right and left margins, as well as the number of x -units. +| Param | Type | +| --- | --- | +| [renderVerticalGridLines] | Boolean | -**Kind**: instance property of [boxPlot](#dc.boxPlot) + +#### coordinateGridMixin.xAxisMin ⇒ \* +Calculates the minimum x value to display in the chart. Includes xAxisPadding if set. -| Param | Type | Default | -| --- | --- | --- | -| [boxWidth] | Number | function | 0.5 | +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.xAxisMax ⇒ \* +Calculates the maximum x value to display in the chart. Includes xAxisPadding if set. -**Example** -```js -// Using numerical parameter -chart.boxWidth(10); -// Using function -chart.boxWidth((innerChartWidth, xUnits) { ... }); -``` - -#### boxPlot.tickFormat ⇒ Number | function -Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to -integer formatting. +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.yAxisMin ⇒ \* +Calculates the minimum y value to display in the chart. Includes yAxisPadding if set. -**Kind**: instance property of [boxPlot](#dc.boxPlot) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.yAxisMax ⇒ \* +Calculates the maximum y value to display in the chart. Includes yAxisPadding if set. + +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) + +#### coordinateGridMixin.yAxisPadding ⇒ Chart +Set or get y axis padding for the elastic y axis. The padding will be added to the top of the y +axis if elasticY is turned on; otherwise it is ignored. + +padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to +number or date axes. When padding a date axis, an integer represents number of days being padded +and a percentage string will be treated the same as an integer. + +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | | --- | --- | -| [tickFormat] | function | +| [padding] | Number | String | -**Example** -```js -// format ticks to 2 decimal places -chart.tickFormat(d3.format('.2f')); -``` - -### dc.bubbleChart ⇒ BubbleChart -A concrete implementation of a general purpose bubble chart that allows data visualization using the -following dimensions: -- x axis position -- y axis position -- bubble radius -- color -Examples: -- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +#### coordinateGridMixin.round ⇒ Chart +Set or get the rounding function used to quantize the selection when brushing is enabled. -**Kind**: static property of [dc](#dc) -**Mixes**: bubbleMixin,coordinateGridMixin +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +| Param | Type | +| --- | --- | +| [round] | function | **Example** ```js -// create a bubble chart under #chart-container1 element using the default global chart group -var bubbleChart1 = dc.bubbleChart('#chart-container1'); -// create a bubble chart under #chart-container2 element using chart group A -var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); +// set x unit round to by month, this will make sure range selection brush will +// select whole months +chart.round(d3.time.month.round); ``` - -#### bubbleChart.elasticRadius ⇒ Boolean -Turn on or off the elastic bubble radius feature, or return the value of the flag. If this -feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. + +#### coordinateGridMixin.clipPadding ⇒ Chart +Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to +the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area +will be exactly the chart body area minus the margins. -**Kind**: instance property of [bubbleChart](#dc.bubbleChart) +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Default | | --- | --- | --- | -| [padding] | Boolean | false | +| [padding] | Number | 5 | - -### dc.bubbleOverlay ⇒ BubbleOverlay -The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay -chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the -typical x and y positioning while retaining the capability to visualize data using bubble radius -and coloring. -Examples: -- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +#### coordinateGridMixin.focus +Zoom this chart to focus on the given range. The given range should be an array containing only +2 elements (`[start, end]`) defining a range in the x domain. If the range is not given or set +to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; +otherwise focus will be ignored. -**Kind**: static property of [dc](#dc) -**Mixes**: bubbleMixin,baseMixin +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +| Param | Type | +| --- | --- | +| [range] | Array.<Number> | **Example** ```js -// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group -var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); -// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A -var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); +chart.on('renderlet', function(chart) { + // smooth the rendering through event throttling + dc.events.trigger(function(){ + // focus some other chart to the range selected by user on this chart + someOtherChart.focus(chart.filter()); + }); +}) ``` + +#### coordinateGridMixin.brushOn ⇒ Chart +Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse +across a chart with a quantitative scale to perform range filtering based on the extent of the +brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and +unfilter them. However turning on the brush filter will disable other interactive elements on +the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible +if enabled, but only via scrolling (panning will be disabled.) -* [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay - * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart - * [.point](#dc.bubbleOverlay+point) ⇒ Chart +**Kind**: instance property of [coordinateGridMixin](#dc.coordinateGridMixin) - -#### bubbleOverlay.svg ⇒ Chart -**mandatory** +| Param | Type | Default | +| --- | --- | --- | +| [brushOn] | Boolean | true | -Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg -element; therefore the bubble overlay chart will not work if this function is not invoked. If the -underlying image is a bitmap, then an empty svg will need to be created on top of the image. + +### dc.stackMixin ⇒ Chart +Stack Mixin is an mixin that provides cross-chart support of stackability using d3.layout.stack. -**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) +**Kind**: static mixin of [dc](#dc) | Param | Type | | --- | --- | -| [imageElement] | Selection | +| _chart | Chart | -**Example** -```js -// set up underlying svg element -chart.svg(d3.select('#chart svg')); -``` - -#### bubbleOverlay.point ⇒ Chart -**mandatory** -Set up a data point on the overlay. The name of a data point should match a specific 'key' among -data groups generated using keyAccessor. If a match is found (point name <-> data group key) -then a bubble will be generated at the position specified by the function. x and y -value specified here are relative to the underlying svg. +* [.stackMixin](#dc.stackMixin) ⇒ Chart + * [.stack](#dc.stackMixin+stack) ⇒ Chart + * [.hidableStacks](#dc.stackMixin+hidableStacks) ⇒ Chart + * [.hideStack](#dc.stackMixin+hideStack) ⇒ Chart + * [.showStack](#dc.stackMixin+showStack) ⇒ Chart + * [.title](#dc.stackMixin+title) ⇒ Chart + * [.stackLayout](#dc.stackMixin+stackLayout) ⇒ Chart -**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) + +#### stackMixin.stack ⇒ Chart +Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks +in the same chart will share the same key accessor and therefore the same set of keys. + +For example, in a stacked bar chart, the bars of each stack will be positioned using the same set +of keys on the x axis, while stacked vertically. If name is specified then it will be used to +generate the legend label. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) | Param | Type | | --- | --- | -| name | String | -| x | Number | -| y | Number | +| group | CrossfilterGroup | +| [name] | String | +| [accessor] | function | - -### dc.filterAll -Clear all filters on all charts within the given chart group. If the chart group is not given then -only charts that belong to the default chart group will be reset. +**Example** +```js +// stack group using default accessor +chart.stack(valueSumGroup) +// stack group using custom accessor +.stack(avgByDayGroup, function(d){return d.value.avgByDay;}); +``` + +#### stackMixin.hidableStacks ⇒ Chart +Allow named stacks to be hidden or shown by clicking on legend items. +This does not affect the behavior of hideStack or showStack. -**Kind**: static property of [dc](#dc) +**Kind**: instance property of [stackMixin](#dc.stackMixin) | Param | Type | | --- | --- | -| [group] | String | +| hidableStacks | Boolean | - -### dc.refocusAll -Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is -not given then only charts that belong to the default chart group will be reset. + +#### stackMixin.hideStack ⇒ Chart +Hide all stacks on the chart with the given name. +The chart must be re-rendered for this change to appear. -**Kind**: static property of [dc](#dc) +**Kind**: instance property of [stackMixin](#dc.stackMixin) | Param | Type | | --- | --- | -| [group] | String | +| stackName | String | - -### dc.renderAll -Re-render all charts belong to the given chart group. If the chart group is not given then only -charts that belong to the default chart group will be re-rendered. + +#### stackMixin.showStack ⇒ Chart +Show all stacks on the chart with the given name. +The chart must be re-rendered for this change to appear. -**Kind**: static property of [dc](#dc) +**Kind**: instance property of [stackMixin](#dc.stackMixin) | Param | Type | | --- | --- | -| [group] | String | +| stackName | String | + + +#### stackMixin.title ⇒ Chart +Set or get the title function. Chart class will use this function to render svg title (usually interpreted by +browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. +Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to +use title otherwise the brush layer will block tooltip trigger. + +If the first argument is a stack name, the title function will get or set the title for that stack. If stackName +is not provided, the first stack is implied. + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | +| --- | --- | +| [stackName] | String | +| [titleAccessor] | function | + +**Example** +```js +// set a title function on 'first stack' +chart.title('first stack', function(d) { return d.key + ': ' + d.value; }); +// get a title function from 'second stack' +var secondTitleFunction = chart.title('second stack'); +``` + +#### stackMixin.stackLayout ⇒ Chart +Gets or sets the stack layout algorithm, which computes a baseline for each stack and +propagates it to the next + +**Kind**: instance property of [stackMixin](#dc.stackMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [stack] | function | d3.layout.stack | + + +### dc.capMixin ⇒ Chart +Cap is a mixin that groups small data elements below a _cap_ into an *others* grouping for both the +Row and Pie Charts. + +The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest +will be replaced with an *others* element, with value equal to the sum of the replaced values. The +keys of the elements below the cap limit are recorded in order to filter by those keys when the +others* element is clicked. + +**Kind**: static mixin of [dc](#dc) + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.capMixin](#dc.capMixin) ⇒ Chart + * [.cap](#dc.capMixin+cap) ⇒ Number + * [.othersLabel](#dc.capMixin+othersLabel) ⇒ String + * [.othersGrouper](#dc.capMixin+othersGrouper) ⇒ function + + +#### capMixin.cap ⇒ Number +Get or set the count of elements to that will be included in the cap. + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [count] | Number | Infinity | + + +#### capMixin.othersLabel ⇒ String +Get or set the label for *Others* slice when slices cap is specified + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [label] | String | Others | + + +#### capMixin.othersGrouper ⇒ function +Get or set the grouper function that will perform the insertion of data for the *Others* slice +if the slices cap is specified. If set to a falsy value, no others will be added. By default the +grouper function computes the sum of all values below the cap. + +**Kind**: instance property of [capMixin](#dc.capMixin) + +| Param | Type | +| --- | --- | +| [grouperFunction] | function | + +**Example** +```js +chart.othersGrouper(function (data) { + // compute the value for others, presumably the sum of all values below the cap + var othersSum = yourComputeOthersValueLogic(data) + + // the keys are needed to properly filter when the others element is clicked + var othersKeys = yourComputeOthersKeysArrayLogic(data); + + // add the others row to the dataset + data.push({'key': 'Others', 'value': othersSum, 'others': othersKeys }); + + return data; +}); +``` + +### dc.bubbleMixin ⇒ Chart +This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. + +**Kind**: static mixin of [dc](#dc) +**Mixes**: colorMixin + +| Param | Type | +| --- | --- | +| _chart | Chart | + + +* [.bubbleMixin](#dc.bubbleMixin) ⇒ Chart + * [.r](#dc.bubbleMixin+r) ⇒ Array.<Number> + * [.radiusValueAccessor](#dc.bubbleMixin+radiusValueAccessor) ⇒ function + * [.minRadiusWithLabel](#dc.bubbleMixin+minRadiusWithLabel) ⇒ Number + * [.maxBubbleRelativeSize](#dc.bubbleMixin+maxBubbleRelativeSize) ⇒ Number + + +#### bubbleMixin.r ⇒ Array.<Number> +Get or set the bubble radius scale. By default the bubble chart uses +`d3.scale.linear().domain([0, 100])` as its r scale . + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | +| --- | --- | +| [bubbleRadiusScale] | Array.<Number> | + + +#### bubbleMixin.radiusValueAccessor ⇒ function +Get or set the radius value accessor function. If set, the radius value accessor function will +be used to retrieve a data value for each bubble. The data retrieved then will be mapped using +the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble +size. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | +| --- | --- | +| [radiusValueAccessor] | function | + + +#### bubbleMixin.minRadiusWithLabel ⇒ Number +Get or set the minimum radius for label rendering. If a bubble's radius is less than this value +then no label will be rendered. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [radius] | Number | 10 | + + +#### bubbleMixin.maxBubbleRelativeSize ⇒ Number +Get or set the maximum relative size of a bubble to the length of x axis. This value is useful +when the difference in radius between bubbles is too great. + +**Kind**: instance property of [bubbleMixin](#dc.bubbleMixin) + +| Param | Type | Default | +| --- | --- | --- | +| [relativeSize] | Number | 0.3 | + + +### dc.filterAll +Clear all filters on all charts within the given chart group. If the chart group is not given then +only charts that belong to the default chart group will be reset. + +**Kind**: static property of [dc](#dc) + +| Param | Type | +| --- | --- | +| [group] | String | + + +### dc.refocusAll +Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is +not given then only charts that belong to the default chart group will be reset. + +**Kind**: static property of [dc](#dc) + +| Param | Type | +| --- | --- | +| [group] | String | + + +### dc.renderAll +Re-render all charts belong to the given chart group. If the chart group is not given then only +charts that belong to the default chart group will be re-rendered. + +**Kind**: static property of [dc](#dc) + +| Param | Type | +| --- | --- | +| [group] | String | ### dc.redrawAll @@ -1728,69 +1945,1136 @@ chart.xUnits(dc.units.fp.precision(0.1) var thousandths = dc.units.fp.precision(0.001); thousandths(0.5, 1.0) // returns 500 ``` - -### dc.geoChoroplethChart ⇒ GeoChoroplethChart -The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map -from GeoJson data. This chart implementation was inspired by [the great d3 choropleth example](http://bl.ocks.org/4060606). -Examples: -- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +### dc.filters : Object +The dc.js filters are functions which are passed into crossfilter to chose which records will be +accumulated to produce values for the charts. In the crossfilter model, any filters applied on one +dimension will affect all the other dimensions but not that one. dc always applies a filter +function to the dimension; the function combines multiple filters and if any of them accept a +record, it is filtered in. + +These filter constructors are used as appropriate by the various charts to implement brushing. We +mention below which chart uses which filter. In some cases, many instances of a filter will be added. **Kind**: static property of [dc](#dc) -**Mixes**: colorMixin,baseMixin -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +* [.filters](#dc.filters) : Object + * [.RangedFilter](#dc.filters.RangedFilter) + * [new RangedFilter(low, high)](#new_dc.filters.RangedFilter_new) + * [.TwoDimensionalFilter](#dc.filters.TwoDimensionalFilter) + * [new TwoDimensionalFilter(filter)](#new_dc.filters.TwoDimensionalFilter_new) + * [.RangedTwoDimensionalFilter](#dc.filters.RangedTwoDimensionalFilter) + * [new RangedTwoDimensionalFilter(filter)](#new_dc.filters.RangedTwoDimensionalFilter_new) -**Example** -```js -// create a choropleth chart under '#us-chart' element using the default global chart group -var chart1 = dc.geoChoroplethChart('#us-chart'); -// create a choropleth chart under '#us-chart2' element using chart group A -var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); -``` + +#### filters.RangedFilter +**Kind**: static class of [filters](#dc.filters) + +##### new RangedFilter(low, high) +RangedFilter is a filter which accepts keys between `low` and `high`. It is used to implement X +axis brushing for the [coordinate grid charts](#coordinate-grid-mixin). -* [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart - * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart - * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart - * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> - * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path - * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart - -#### geoChoroplethChart.overlayGeoJson ⇒ Chart -**mandatory** +| Param | Type | +| --- | --- | +| low | Number | +| high | Number | -Use this function to insert a new GeoJson map layer. This function can be invoked multiple times -if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple -layers with the same name the new overlay will override the existing one. + +#### filters.TwoDimensionalFilter +**Kind**: static class of [filters](#dc.filters) + +##### new TwoDimensionalFilter(filter) +TwoDimensionalFilter is a filter which accepts a single two-dimensional value. It is used by the +[heat map chart](#heat-map) to include particular cells as they are clicked. (Rows and columns are +filtered by filtering all the cells in the row or column.) -**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) -| Param | Type | Description | -| --- | --- | --- | -| json | Object | a geojson feed | -| name | String | name of the layer | -| keyAccessor | function | accessor function used to extract 'key' from the GeoJson data. The key extracted by this function should match the keys returned by the crossfilter groups. | +| Param | Type | +| --- | --- | +| filter | Array.<Number> | -**Example** -```js -// insert a layer for rendering US states -chart.overlayGeoJson(statesJson.features, 'state', function(d) { - return d.properties.name; -}); -``` - -#### geoChoroplethChart.projection ⇒ Chart -Set custom geo projection function. See the available [d3 geo projection -functions](https://github.com/mbostock/d3/wiki/Geo-Projections). + +#### filters.RangedTwoDimensionalFilter +**Kind**: static class of [filters](#dc.filters) + +##### new RangedTwoDimensionalFilter(filter) +The RangedTwoDimensionalFilter allows filtering all values which fit within a rectangular +region. It is used by the [scatter plot](#scatter-plot) to implement rectangular brushing. -**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) +It takes two two-dimensional points in the form `[[x1,y1],[x2,y2]]`, and normalizes them so that +`x1 <= x2` and `y1 <- y2`. It then returns a filter which accepts any points which are in the +rectangular range including the lower values but excluding the higher values. -| Param | Type | Default | -| --- | --- | --- | -| [projection] | d3.projection | d3.projection.albersUsa() | +If an array of two values are given to the RangedTwoDimensionalFilter, it interprets the values as +two x coordinates `x1` and `x2` and returns a filter which accepts any points for which `x1 <= x < +x2`. + + +| Param | Type | +| --- | --- | +| filter | Array.<Array.<Number>> | + + +### dc.pieChart ⇒ PieChart +The pie chart implementation is usually used to visualize a small categorical distribution. The pie +chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each +slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting +by key. + +**Kind**: static property of [dc](#dc) +**Mixes**: capMixin,colorMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a pie chart under #chart-container1 element using the default global chart group +var chart1 = dc.pieChart('#chart-container1'); +// create a pie chart under #chart-container2 element using chart group A +var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); +``` + +* [.pieChart](#dc.pieChart) ⇒ PieChart + * [.slicesCap](#dc.pieChart+slicesCap) ⇒ Chart + * [.externalRadiusPadding](#dc.pieChart+externalRadiusPadding) ⇒ Chart + * [.innerRadius](#dc.pieChart+innerRadius) ⇒ Chart + * [.radius](#dc.pieChart+radius) ⇒ Chart + * [.cx](#dc.pieChart+cx) ⇒ Chart + * [.cy](#dc.pieChart+cy) ⇒ Chart + * [.minAngleForLabel](#dc.pieChart+minAngleForLabel) ⇒ Chart + * [.emptyTitle](#dc.pieChart+emptyTitle) ⇒ Chart + * [.externalLabels](#dc.pieChart+externalLabels) ⇒ Chart + + +#### pieChart.slicesCap ⇒ Chart +Get or set the maximum number of slices the pie chart will generate. The top slices are determined by +value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cap] | Number | + + +#### pieChart.externalRadiusPadding ⇒ Chart +Get or set the external radius padding of the pie chart. This will force the radius of the +pie chart to become smaller or larger depending on the value. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [externalRadiusPadding] | Number | 0 | + + +#### pieChart.innerRadius ⇒ Chart +Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the +pie chart will be rendered as a doughnut chart. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [innerRadius] | Number | 0 | + + +#### pieChart.radius ⇒ Chart +Get or set the outer radius. If the radius is not set, it will be half of the minimum of the +chart width and height. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [radius] | Number | + + +#### pieChart.cx ⇒ Chart +Get or set center x coordinate position. Default is center of svg. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cx] | Number | + + +#### pieChart.cy ⇒ Chart +Get or set center y coordinate position. Default is center of svg. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [cy] | Number | + + +#### pieChart.minAngleForLabel ⇒ Chart +Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not +display a slice label. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | Default | +| --- | --- | --- | +| [minAngleForLabel] | Number | 0.5 | + + +#### pieChart.emptyTitle ⇒ Chart +Title to use for the only slice when there is no data. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [title] | String | + + +#### pieChart.externalLabels ⇒ Chart +Position slice labels offset from the outer edge of the chart + +The given argument sets the radial offset. + +**Kind**: instance property of [pieChart](#dc.pieChart) + +| Param | Type | +| --- | --- | +| [radius] | Number | + + +### dc.barChart ⇒ BarChart +Concrete bar chart/histogram implementation. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a bar chart under #chart-container1 element using the default global chart group +var chart1 = dc.barChart('#chart-container1'); +// create a bar chart under #chart-container2 element using chart group A +var chart2 = dc.barChart('#chart-container2', 'chartGroupA'); +// create a sub-chart under a composite parent chart +var chart3 = dc.barChart(compositeChart); +``` + +* [.barChart](#dc.barChart) ⇒ BarChart + * [.centerBar](#dc.barChart+centerBar) ⇒ Boolean + * [.barPadding](#dc.barChart+barPadding) ⇒ Number + * [.outerPadding](#dc.barChart+outerPadding) ⇒ Number + * [.gap](#dc.barChart+gap) ⇒ Number + * [.alwaysUseRounding](#dc.barChart+alwaysUseRounding) ⇒ Boolean + + +#### barChart.centerBar ⇒ Boolean +Whether the bar chart will render each bar centered around the data position on x axis + +**Kind**: instance property of [barChart](#dc.barChart) + +| Param | Type | Default | +| --- | --- | --- | +| [centerBar] | Boolean | false | + + +#### barChart.barPadding ⇒ Number +Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. +Setting this value will also remove any previously set `gap`. See the +[d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) +for a visual description of how the padding is applied. + +**Kind**: instance property of [barChart](#dc.barChart) + +| Param | Type | +| --- | --- | +| [barPadding] | Number | + + +#### barChart.outerPadding ⇒ Number +Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. +Will pad the width by `padding * barWidth` on each side of the chart. + +**Kind**: instance property of [barChart](#dc.barChart) + +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Number | 0.5 | + + +#### barChart.gap ⇒ Number +Manually set fixed gap (in px) between bars instead of relying on the default auto-generated +gap. By default the bar chart implementation will calculate and set the gap automatically +based on the number of data points and the length of the x axis. + +**Kind**: instance property of [barChart](#dc.barChart) + +| Param | Type | Default | +| --- | --- | --- | +| [gap] | Number | 2 | + + +#### barChart.alwaysUseRounding ⇒ Boolean +Set or get whether rounding is enabled when bars are centered. Default: false. If false, using +rounding with centered bars will result in a warning and rounding will be ignored. This flag +has no effect if bars are not centered. +When using standard d3.js rounding methods, the brush often doesn't align correctly with +centered bars since the bars are offset. The rounding function must add an offset to +compensate, such as in the following example. + +**Kind**: instance property of [barChart](#dc.barChart) + +| Param | Type | Default | +| --- | --- | --- | +| [alwaysUseRounding] | Boolean | false | + +**Example** +```js +chart.round(function(n) {return Math.floor(n)+0.5}); +``` + +### dc.lineChart ⇒ LineChart +Concrete line/area chart implementation. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: stackMixin,coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a line chart under #chart-container1 element using the default global chart group +var chart1 = dc.lineChart('#chart-container1'); +// create a line chart under #chart-container2 element using chart group A +var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); +// create a sub-chart under a composite parent chart +var chart3 = dc.lineChart(compositeChart); +``` + +* [.lineChart](#dc.lineChart) ⇒ LineChart + * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart + * [.tension](#dc.lineChart+tension) ⇒ Chart + * [.defined](#dc.lineChart+defined) ⇒ Chart + * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart + * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart + * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart + * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart + * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart + + +#### lineChart.interpolate ⇒ Chart +Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step +functions, splines, and cubic interpolation. This is passed to +[d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and +[d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), +where you can find a complete list of valid arguments + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | +| --- | --- | +| [interpolate] | String | + + +#### lineChart.tension ⇒ Chart +Gets or sets the tension to use for lines drawn, in the range 0 to 1. +This parameter further customizes the interpolation behavior. It is passed to +[d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and +[d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [tension] | Number | 0.7 | + + +#### lineChart.defined ⇒ Chart +Gets or sets a function that will determine discontinuities in the line which should be +skipped: the path will be broken into separate subpaths if some points are undefined. +This function is passed to +[d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) + +Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write +custom reduce functions to get this to work, depending on your data. See +https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | +| --- | --- | +| [defined] | function | + + +#### lineChart.dashStyle ⇒ Chart +Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty +array (solid line). + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [dashStyle] | Array.<Number> | [] | + +**Example** +```js +// create a Dash Dot Dot Dot +chart.dashStyle([3,1,1,1]); +``` + +#### lineChart.renderArea ⇒ Chart +Get or set render area flag. If the flag is set to true then the chart will render the area +beneath each line and the line chart effectively becomes an area chart. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [renderArea] | Boolean | false | + + +#### lineChart.xyTipsOn ⇒ Chart +Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis +dashed lines back to each respective axis. This is ignored if the chart brush is on (`brushOn`) + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [xyTipsOn] | Boolean | false | + + +#### lineChart.dotRadius ⇒ Chart +Get or set the radius (in px) for dots displayed on the data points. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [dotRadius] | Number | 5 | + + +#### lineChart.renderDataPoints ⇒ Chart +Always show individual dots for each datapoint. +If `options` is falsy, it disables data point rendering. + +If no `options` are provided, the current `options` values are instead returned. + +**Kind**: instance property of [lineChart](#dc.lineChart) + +| Param | Type | Default | +| --- | --- | --- | +| [options] | Object | {fillOpacity: 0.8, strokeOpacity: 0.8, radius: 2} | + +**Example** +```js +chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) +``` + +### dc.dataCount ⇒ DataCount +The data count widget is a simple widget designed to display the number of records selected by the +current filters out of the total number of records in the data set. Once created the data count widget +will automatically update the text content of the following elements under the parent element. + +'.total-count' - total number of records +'.filter-count' - number of records matched by the current filters + +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +var ndx = crossfilter(data); +var all = ndx.groupAll(); + +dc.dataCount('.dc-data-count') + .dimension(ndx) + .group(all); +``` + +* [.dataCount](#dc.dataCount) ⇒ DataCount + * [.html](#dc.dataCount+html) ⇒ Chart + * [.formatNumber](#dc.dataCount+formatNumber) ⇒ Chart + + +#### dataCount.html ⇒ Chart +Gets or sets an optional object specifying HTML templates to use depending how many items are +selected. The text `%total-count` will replaced with the total number of records, and the text +`%filter-count` will be replaced with the number of selected records. +- all: HTML template to use if all items are selected +- some: HTML template to use if not all items are selected + +**Kind**: instance property of [dataCount](#dc.dataCount) + +| Param | Type | +| --- | --- | +| [options] | Object | + +**Example** +```js +counter.html({ + some: '%filter-count out of %total-count records selected', + all: 'All records selected. Click on charts to apply filters' +}) +``` + +#### dataCount.formatNumber ⇒ Chart +Gets or sets an optional function to format the filter count and total count. + +**Kind**: instance property of [dataCount](#dc.dataCount) + +| Param | Type | Default | +| --- | --- | --- | +| [formatter] | function | d3.format('.2g') | + +**Example** +```js +counter.formatNumber(d3.format('.2g')) +``` + +### dc.dataTable ⇒ DataTable +The data table is a simple widget designed to list crossfilter focused data set (rows being +filtered) in a good old tabular fashion. + +Note: Unlike other charts, the data table (and data grid chart) use the group attribute as a keying function +for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. +Do not pass in a crossfilter group as this will not work. + +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) + +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + + +* [.dataTable](#dc.dataTable) ⇒ DataTable + * [.size](#dc.dataTable+size) ⇒ Chart + * [.columns](#dc.dataTable+columns) ⇒ Chart + * [.sortBy](#dc.dataTable+sortBy) ⇒ Chart + * [.order](#dc.dataTable+order) ⇒ Chart + * [.order](#dc.dataTable+order) ⇒ Chart + + +#### dataTable.size ⇒ Chart +Get or set the table size which determines the number of rows displayed by the widget. + +**Kind**: instance property of [dataTable](#dc.dataTable) + +| Param | Type | +| --- | --- | +| [size] | Number | + + +#### dataTable.columns ⇒ Chart +Get or set column functions. The data table widget now supports several methods of specifying +the columns to display. The original method, first shown below, uses an array of functions to +generate dynamic columns. Column functions are simple javascript functions with only one input +argument `d` which represents a row in the data set. The return value of these functions will be +used directly to generate table content for each cell. However, this method requires the .html +table entry to have a fixed set of column headers. + +The second example shows you can simply list the data (d) content directly without +specifying it as a function, except where necessary (ie, computed columns). Note +the data element accessor name is capitalized when displayed in the table. You can +also mix in functions as desired or necessary, but you must use the +Object = [Label, Fn] method as shown below. +You may wish to override the following two functions, which are internally used to +translate the column information or function into a displayed header. The first one +is used on the simple "string" column specifier, the second is used to transform the +String(fn) into something displayable. For the Stock example, the function for Change +becomes a header of 'd.close - d.open'. +_chart._doColumnHeaderCapitalize _chart._doColumnHeaderFnToString +You may use your own Object definition, however you must then override +_chart._doColumnHeaderFormat , _chart._doColumnValueFormat +Be aware that fields without numberFormat specification will be displayed just as +they are stored in the data, unformatted. + +The third example, where all fields are specified using the Object = [Label, Fn] method. + +**Kind**: instance property of [dataTable](#dc.dataTable) + +| Param | Type | +| --- | --- | +| [columns] | Array.<function()> | + +**Example** +```js +chart.columns([ + function(d) { return d.date; }, + function(d) { return d.open; }, + function(d) { return d.close; }, + function(d) { return numberFormat(d.close - d.open); }, + function(d) { return d.volume; } +]); +``` +**Example** +```js +chart.columns([ + "date", // d["date"], ie, a field accessor; capitalized automatically + "open", // ... + "close", // ... + ["Change", // Specify an Object = [Label, Fn] + function (d) { return numberFormat(d.close - d.open); }], + "volume" // d["volume"], ie, a field accessor; capitalized automatically +]); +``` +**Example** +```js +chart.columns([ + ["Date", // Specify an Object = [Label, Fn] + function (d) { return d.date; }], + ["Open", + function (d) { return numberFormat(d.open); }], + ["Close", + function (d) { return numberFormat(d.close); }], + ["Change", + function (d) { return numberFormat(d.close - d.open); }], + ["Volume", + function (d) { return d.volume; }] +]); +``` + +#### dataTable.sortBy ⇒ Chart +Get or set sort-by function. This function works as a value accessor at row level and returns a +particular field to be sorted by. Default value: identity function + +**Kind**: instance property of [dataTable](#dc.dataTable) + +| Param | Type | +| --- | --- | +| [sortBy] | function | + +**Example** +```js +chart.sortBy(function(d) { + return d.date; +}); +``` + +#### dataTable.order ⇒ Chart +Get or set sort order. + +**Kind**: instance property of [dataTable](#dc.dataTable) + +| Param | Type | Default | +| --- | --- | --- | +| [order] | function | d3.ascending | + +**Example** +```js +chart.order(d3.descending); +``` + +#### dataTable.order ⇒ Chart +Get or set if group rows will be shown. + +The .group() getter-setter must be provided in either case. + +**Kind**: instance property of [dataTable](#dc.dataTable) + +| Param | Type | Default | +| --- | --- | --- | +| [showGroups] | Boolean | true | + +**Example** +```js +chart + .group([value], [name]) + .showGroups(true|false); +``` + +### dc.dataGrid ⇒ DataGrid +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 group attribute as a keying function +for [nesting](https://github.com/mbostock/d3/wiki/Arrays#-nest) the data together in groups. +Do not pass in a crossfilter group as this will not work. + +Examples: +- [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + + +* [.dataGrid](#dc.dataGrid) ⇒ DataGrid + * [.beginSlice](#dc.dataGrid+beginSlice) ⇒ Chart + * [.endSlice](#dc.dataGrid+endSlice) ⇒ Chart + * [.size](#dc.dataGrid+size) ⇒ Chart + * [.html](#dc.dataGrid+html) ⇒ Chart + * [.htmlGroup](#dc.dataGrid+htmlGroup) ⇒ Chart + * [.sortBy](#dc.dataGrid+sortBy) ⇒ Chart + * [.order](#dc.dataGrid+order) ⇒ Chart + + +#### dataGrid.beginSlice ⇒ Chart +Get or set the index of the beginning slice which determines which entries get displayed by the widget +Useful when implementing pagination. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | Default | +| --- | --- | --- | +| [beginSlice] | Number | 0 | + + +#### dataGrid.endSlice ⇒ Chart +Get or set the index of the end slice which determines which entries get displayed by the widget +Useful when implementing pagination. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | +| --- | --- | +| [endSlice] | Number | + + +#### dataGrid.size ⇒ Chart +Get or set the grid size which determines the number of items displayed by the widget. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | Default | +| --- | --- | --- | +| [size] | Number | 999 | + + +#### dataGrid.html ⇒ Chart +Get or set the function that formats an item. The data grid widget uses a +function to generate dynamic html. Use your favourite templating engine or +generate the string directly. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | +| --- | --- | +| [html] | function | + +**Example** +```js +chart.html(function (d) { return '
'+data.exampleString+'
';}); +``` + +#### dataGrid.htmlGroup ⇒ Chart +Get or set the function that formats a group label. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | +| --- | --- | +| [htmlGroup] | function | + +**Example** +```js +chart.htmlGroup (function (d) { return '

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

'}); +``` + +#### dataGrid.sortBy ⇒ Chart +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. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | +| --- | --- | +| [sortByFunction] | function | + +**Example** +```js +chart.sortBy(function(d) { + return d.date; +}); +``` + +#### dataGrid.order ⇒ Chart +Get or set sort order function. + +**Kind**: instance property of [dataGrid](#dc.dataGrid) + +| Param | Type | Default | +| --- | --- | --- | +| [order] | function | d3.ascending | + +**Example** +```js +chart.order(d3.descending); +``` + +### dc.bubbleChart ⇒ BubbleChart +A concrete implementation of a general purpose bubble chart that allows data visualization using the +following dimensions: +- x axis position +- y axis position +- bubble radius +- color +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: bubbleMixin,coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a bubble chart under #chart-container1 element using the default global chart group +var bubbleChart1 = dc.bubbleChart('#chart-container1'); +// create a bubble chart under #chart-container2 element using chart group A +var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA'); +``` + +#### bubbleChart.elasticRadius ⇒ Boolean +Turn on or off the elastic bubble radius feature, or return the value of the flag. If this +feature is turned on, then bubble radii will be automatically rescaled to fit the chart better. + +**Kind**: instance property of [bubbleChart](#dc.bubbleChart) + +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Boolean | false | + + +### dc.compositeChart ⇒ CompositeChart +Composite charts are a special kind of chart that render multiple charts on the same Coordinate +Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to +achieve some quite flexible charting effects. + +**Kind**: static property of [dc](#dc) +**Mixes**: coordinateGridMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a composite chart under #chart-container1 element using the default global chart group +var compositeChart1 = dc.compositeChart('#chart-container1'); +// create a composite chart under #chart-container2 element using chart group A +var compositeChart2 = dc.compositeChart('#chart-container2', 'chartGroupA'); +``` + +* [.compositeChart](#dc.compositeChart) ⇒ CompositeChart + * [.useRightAxisGridLines](#dc.compositeChart+useRightAxisGridLines) ⇒ Chart + * [.childOptions](#dc.compositeChart+childOptions) ⇒ Chart + * [.rightYAxisLabel](#dc.compositeChart+rightYAxisLabel) ⇒ Chart + * [.compose](#dc.compositeChart+compose) ⇒ Chart + * [.children](#dc.compositeChart+children) ⇒ Array.<Chart> + * [.shareColors](#dc.compositeChart+shareColors) ⇒ Chart + * [.shareTitle](#dc.compositeChart+shareTitle) ⇒ Chart + * [.rightY](#dc.compositeChart+rightY) ⇒ Chart + * [.rightYAxis](#dc.compositeChart+rightYAxis) ⇒ Chart + + +#### compositeChart.useRightAxisGridLines ⇒ Chart +Get or set whether to draw gridlines from the right y axis. Drawing from the left y axis is the +default behavior. This option is only respected when subcharts with both left and right y-axes +are present. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [useRightAxisGridLines] | Boolean | + + +#### compositeChart.childOptions ⇒ Chart +Get or set chart-specific options for all child charts. This is equivalent to calling `.options` +on each child chart. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [options] | Object | + + +#### compositeChart.rightYAxisLabel ⇒ Chart +Set or get the right y axis label. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [rightYAxisLabel] | String | + + +#### compositeChart.compose ⇒ Chart +Combine the given charts into one single composite coordinate grid chart. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [subChartArray] | Array.<Chart> | + +**Example** +```js +moveChart.compose([ + // when creating sub-chart you need to pass in the parent chart + dc.lineChart(moveChart) + .group(indexAvgByMonthGroup) // if group is missing then parent's group will be used + .valueAccessor(function (d){return d.value.avg;}) + // most of the normal functions will continue to work in a composed chart + .renderArea(true) + .stack(monthlyMoveGroup, function (d){return d.value;}) + .title(function (d){ + var value = d.value.avg?d.value.avg:d.value; + if(isNaN(value)) value = 0; + return dateFormat(d.key) + '\n' + numberFormat(value); + }), + dc.barChart(moveChart) + .group(volumeByMonthGroup) + .centerBar(true) +]); +``` + +#### compositeChart.children ⇒ Array.<Chart> +Returns the child charts which are composed into the composite chart. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +#### compositeChart.shareColors ⇒ Chart +Get or set color sharing for the chart. If set, the `.colors()` value from this chart +will be shared with composed children. Additionally if the child chart implements +Stackable and has not set a custom .colorAccessor, then it will generate a color +specific to its order in the composition. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [shareColors] | Boolean | + + +#### compositeChart.shareTitle ⇒ Chart +Get or set title sharing for the chart. If set, the `.title()` value from this chart will be +shared with composed children. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | Default | +| --- | --- | --- | +| [shareTitle] | Boolean | true | + + +#### compositeChart.rightY ⇒ Chart +Get or set the y scale for the right axis. The right y scale is typically automatically +generated by the chart implementation. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [yScale] | d3.scale | + + +#### compositeChart.rightYAxis ⇒ Chart +Set or get the right y axis used by the composite chart. This function is most useful when y +axis customization is required. The y axis in dc.js is an instance of a [d3 axis +object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-_axis) therefore it supports any valid +d3 axis manipulation. **Caution**: The y axis is usually generated internally by dc; +resetting it may cause unexpected results. + +**Kind**: instance property of [compositeChart](#dc.compositeChart) + +| Param | Type | +| --- | --- | +| [rightYAxis] | d3.svg.axis | + +**Example** +```js +// customize y axis tick format +chart.rightYAxis().tickFormat(function (v) {return v + '%';}); +// customize y axis tick values +chart.rightYAxis().tickValues([0, 100, 200, 300]); +``` + +### dc.seriesChart ⇒ SeriesChart +A series chart is a chart that shows multiple series of data overlaid on one chart, where the +series is specified in the data. It is a specialization of Composite Chart and inherits all +composite features other than recomposing the chart. + +**Kind**: static property of [dc](#dc) +**Mixes**: compositeChart + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a series chart under #chart-container1 element using the default global chart group +var seriesChart1 = dc.seriesChart("#chart-container1"); +// create a series chart under #chart-container2 element using chart group A +var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); +``` + +* [.seriesChart](#dc.seriesChart) ⇒ SeriesChart + * [.chart](#dc.seriesChart+chart) ⇒ Chart + * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart + * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart + * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart + + +#### seriesChart.chart ⇒ Chart +Get or set the chart function, which generates the child charts. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | Default | +| --- | --- | --- | +| chartFunction | function | dc.lineChart | + +**Example** +```js +// put interpolation on the line charts used for the series +chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) +// do a scatter series chart +chart.chart(dc.scatterPlot) +``` + +#### seriesChart.seriesAccessor ⇒ Chart +Get or set accessor function for the displayed series. Given a datum, this function +should return the series that datum belongs to. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [accessor] | function | + + +#### seriesChart.seriesSort ⇒ Chart +Get or set a function to sort the list of series by, given series values. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [sortFunction] | function | + +**Example** +```js +chart.seriesSort(d3.descending); +``` + +#### seriesChart.valueSort ⇒ Chart +Get or set a function to sort each series values by. By default this is the key accessor which, +for example, will ensure a lineChart series connects its points in increasing key/x order, +rather than haphazardly. + +**Kind**: instance property of [seriesChart](#dc.seriesChart) + +| Param | Type | +| --- | --- | +| [sortFunction] | function | + + +### dc.geoChoroplethChart ⇒ GeoChoroplethChart +The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map +from GeoJson data. This chart implementation was inspired by [the great d3 choropleth example](http://bl.ocks.org/4060606). +Examples: +- [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) + +**Kind**: static property of [dc](#dc) +**Mixes**: colorMixin,baseMixin + +| Param | Type | Description | +| --- | --- | --- | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | + +**Example** +```js +// create a choropleth chart under '#us-chart' element using the default global chart group +var chart1 = dc.geoChoroplethChart('#us-chart'); +// create a choropleth chart under '#us-chart2' element using chart group A +var chart2 = dc.compositeChart('#us-chart2', 'chartGroupA'); +``` + +* [.geoChoroplethChart](#dc.geoChoroplethChart) ⇒ GeoChoroplethChart + * [.overlayGeoJson](#dc.geoChoroplethChart+overlayGeoJson) ⇒ Chart + * [.projection](#dc.geoChoroplethChart+projection) ⇒ Chart + * [.geoJsons](#dc.geoChoroplethChart+geoJsons) ⇒ Array.<{name:String, data: Object, accessor: function()}> + * [.geoPath](#dc.geoChoroplethChart+geoPath) ⇒ d3.geo.path + * [.removeGeoJson](#dc.geoChoroplethChart+removeGeoJson) ⇒ Chart + + +#### geoChoroplethChart.overlayGeoJson ⇒ Chart +**mandatory** + +Use this function to insert a new GeoJson map layer. This function can be invoked multiple times +if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple +layers with the same name the new overlay will override the existing one. + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +| Param | Type | Description | +| --- | --- | --- | +| json | Object | a geojson feed | +| name | String | name of the layer | +| keyAccessor | function | accessor function used to extract 'key' from the GeoJson data. The key extracted by this function should match the keys returned by the crossfilter groups. | + +**Example** +```js +// insert a layer for rendering US states +chart.overlayGeoJson(statesJson.features, 'state', function(d) { + return d.properties.name; +}); +``` + +#### geoChoroplethChart.projection ⇒ Chart +Set custom geo projection function. See the available [d3 geo projection +functions](https://github.com/mbostock/d3/wiki/Geo-Projections). + +**Kind**: instance property of [geoChoroplethChart](#dc.geoChoroplethChart) + +| Param | Type | Default | +| --- | --- | --- | +| [projection] | d3.projection | d3.projection.albersUsa() | #### geoChoroplethChart.geoJsons ⇒ Array.<{name:String, data: Object, accessor: function()}> @@ -1816,147 +3100,203 @@ Remove a GeoJson layer from this chart by name | --- | --- | | name | String | - -### dc.heatMap ⇒ HeatMap -A heat map is matrix that represents the values of two dimensions of data using colors. + +### dc.bubbleOverlay ⇒ BubbleOverlay +The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay +chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the +typical x and y positioning while retaining the capability to visualize data using bubble radius +and coloring. +Examples: +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: colorMixin,marginMixin,baseMixin +**Mixes**: bubbleMixin,baseMixin | Param | Type | Description | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | | [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** ```js -// create a heat map under #chart-container1 element using the default global chart group -var heatMap1 = dc.heatMap('#chart-container1'); -// create a heat map under #chart-container2 element using chart group A -var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); +// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group +var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); +// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A +var bubbleChart2 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg')); ``` -* [.heatMap](#dc.heatMap) ⇒ HeatMap - * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart - * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart - * [.rows](#dc.heatMap+rows) ⇒ Chart - * [.cols](#dc.heatMap+cols) ⇒ Chart - * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart - * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart - * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart - * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart - * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart +* [.bubbleOverlay](#dc.bubbleOverlay) ⇒ BubbleOverlay + * [.svg](#dc.bubbleOverlay+svg) ⇒ Chart + * [.point](#dc.bubbleOverlay+point) ⇒ Chart - -#### heatMap.colsLabel ⇒ Chart -Set or get the column label function. The chart class uses this function to render -column labels on the X axis. It is passed the column name. + +#### bubbleOverlay.svg ⇒ Chart +**mandatory** -**Kind**: instance property of [heatMap](#dc.heatMap) +Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg +element; therefore the bubble overlay chart will not work if this function is not invoked. If the +underlying image is a bitmap, then an empty svg will need to be created on top of the image. -| Param | Type | Default | -| --- | --- | --- | -| [labelFunction] | function | function(d) { return d; } | +**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) + +| Param | Type | +| --- | --- | +| [imageElement] | Selection | **Example** ```js -// the default label function just returns the name -chart.colsLabel(function(d) { return d; }); +// set up underlying svg element +chart.svg(d3.select('#chart svg')); ``` - -#### heatMap.rowsLabel ⇒ Chart -Set or get the row label function. The chart class uses this function to render -row labels on the Y axis. It is passed the row name. + +#### bubbleOverlay.point ⇒ Chart +**mandatory** -**Kind**: instance property of [heatMap](#dc.heatMap) +Set up a data point on the overlay. The name of a data point should match a specific 'key' among +data groups generated using keyAccessor. If a match is found (point name <-> data group key) +then a bubble will be generated at the position specified by the function. x and y +value specified here are relative to the underlying svg. -| Param | Type | Default | +**Kind**: instance property of [bubbleOverlay](#dc.bubbleOverlay) + +| Param | Type | +| --- | --- | +| name | String | +| x | Number | +| y | Number | + + +### dc.rowChart ⇒ RowChart +Concrete row chart implementation. + +**Kind**: static property of [dc](#dc) +**Mixes**: capMixin,marginMixin,colorMixin,baseMixin + +| Param | Type | Description | | --- | --- | --- | -| [labelFunction] | function | function(d) { return d; } | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** ```js -// the default label function just returns the name -chart.rowsLabel(function(d) { return d; }); +// create a row chart under #chart-container1 element using the default global chart group +var chart1 = dc.rowChart('#chart-container1'); +// create a row chart under #chart-container2 element using chart group A +var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); ``` - -#### heatMap.rows ⇒ Chart -Gets or sets the values used to create the rows of the heatmap, as an array. By default, all -the values will be fetched from the data using the value accessor, and they will be sorted in -ascending order. -**Kind**: instance property of [heatMap](#dc.heatMap) +* [.rowChart](#dc.rowChart) ⇒ RowChart + * [.x](#dc.rowChart+x) ⇒ Chart + * [.renderTitleLabel](#dc.rowChart+renderTitleLabel) ⇒ Chart + * [.xAxis](#dc.rowChart+xAxis) ⇒ d3.svg.Axis + * [.fixedBarHeight](#dc.rowChart+fixedBarHeight) ⇒ Chart + * [.gap](#dc.rowChart+gap) ⇒ Chart + * [.elasticX](#dc.rowChart+elasticX) ⇒ Chart + * [.labelOffsetX](#dc.rowChart+labelOffsetX) ⇒ Chart + * [.labelOffsetY](#dc.rowChart+labelOffsetY) ⇒ Chart + * [.titleLabelOffsetX](#dc.rowChart+titleLabelOffsetX) ⇒ Chart + + +#### rowChart.x ⇒ Chart +Gets or sets the x scale. The x scale can be any d3 +[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) + +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | | --- | --- | -| [rows] | Array.<(String\|Number)> | +| [scale] | d3.scale | - -#### heatMap.cols ⇒ Chart -Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all -the values will be fetched from the data using the key accessor, and they will be sorted in -ascending order. + +#### rowChart.renderTitleLabel ⇒ Chart +Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | | --- | --- | -| [cols] | Array.<(String\|Number)> | +| [renderTitleLabel] | Boolean | - -#### heatMap.boxOnClick ⇒ Chart -Gets or sets the handler that fires when an individual cell is clicked in the heatmap. -By default, filtering of the cell will be toggled. + +#### rowChart.xAxis ⇒ d3.svg.Axis +Get the x axis for the row chart instance. Note: not settable for row charts. +See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) +**Example** +```js +// customize x axis tick format +chart.xAxis().tickFormat(function (v) {return v + '%';}); +// customize x axis tick values +chart.xAxis().tickValues([0, 100, 200, 300]); +``` + +#### rowChart.fixedBarHeight ⇒ Chart +Get or set the fixed bar height. Default is [false] which will auto-scale bars. +For example, if you want to fix the height for a specific number of bars (useful in TopN charts) +you could fix height as follows (where count = total number of bars in your TopN and gap is +your vertical gap space). + +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | | --- | --- | -| [handler] | function | +| [height] | Number | - -#### heatMap.xAxisOnClick ⇒ Chart -Gets or sets the handler that fires when a column tick is clicked in the x axis. -By default, if any cells in the column are unselected, the whole column will be selected, -otherwise the whole column will be unselected. +**Example** +```js +chart.fixedBarHeight( chartheight - (count + 1) * gap / count); +``` + +#### rowChart.gap ⇒ Chart +Get or set the vertical gap space between rows on a particular row chart instance -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) -| Param | Type | -| --- | --- | -| [handler] | function | +| Param | Type | Default | +| --- | --- | --- | +| [gap] | Number | 5 | - -#### heatMap.yAxisOnClick ⇒ Chart -Gets or sets the handler that fires when a row tick is clicked in the y axis. -By default, if any cells in the row are unselected, the whole row will be selected, -otherwise the whole row will be unselected. + +#### rowChart.elasticX ⇒ Chart +Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the +data range when filtered. -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | | --- | --- | -| [handler] | function | +| [elasticX] | Boolean | - -#### heatMap.xBorderRadius ⇒ Chart -Gets or sets the X border radius. Set to 0 to get full rectangles. + +#### rowChart.labelOffsetX ⇒ Chart +Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | Default | | --- | --- | --- | -| [xBorderRadius] | Number | 6.75 | +| [labelOffsetX] | Number | 10 | - -#### heatMap.yBorderRadius ⇒ Chart -Gets or sets the Y border radius. Set to 0 to get full rectangles. + +#### rowChart.labelOffsetY ⇒ Chart +Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. -**Kind**: instance property of [heatMap](#dc.heatMap) +**Kind**: instance property of [rowChart](#dc.rowChart) | Param | Type | Default | | --- | --- | --- | -| [yBorderRadius] | Number | 6.75 | +| [labelOffsety] | Number | 15 | + + +#### rowChart.titleLabelOffsetX ⇒ Chart +Get of set the x offset (horizontal space between right edge of row and right edge or text. + +**Kind**: instance property of [rowChart](#dc.rowChart) + +| Param | Type | Default | +| --- | --- | --- | +| [x] | Number | 2 | ### dc.legend ⇒ Legend @@ -2063,150 +3403,89 @@ This setting takes into account gap(). | --- | --- | --- | | [autoItemWidth] | Boolean | false | - -### dc.lineChart ⇒ LineChart -Concrete line/area chart implementation. -Examples: -- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) -- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) + +### dc.scatterPlot ⇒ SeriesChart +A scatter plot chart **Kind**: static property of [dc](#dc) -**Mixes**: stackMixin,coordinateGridMixin +**Mixes**: coordinateGridMixin | Param | Type | Description | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | | [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** ```js -// create a line chart under #chart-container1 element using the default global chart group -var chart1 = dc.lineChart('#chart-container1'); -// create a line chart under #chart-container2 element using chart group A -var chart2 = dc.lineChart('#chart-container2', 'chartGroupA'); +// create a scatter plot under #chart-container1 element using the default global chart group +var chart1 = dc.scatterPlot('#chart-container1'); +// create a scatter plot under #chart-container2 element using chart group A +var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); // create a sub-chart under a composite parent chart -var chart3 = dc.lineChart(compositeChart); +var chart3 = dc.scatterPlot(compositeChart); ``` -* [.lineChart](#dc.lineChart) ⇒ LineChart - * [.interpolate](#dc.lineChart+interpolate) ⇒ Chart - * [.tension](#dc.lineChart+tension) ⇒ Chart - * [.defined](#dc.lineChart+defined) ⇒ Chart - * [.dashStyle](#dc.lineChart+dashStyle) ⇒ Chart - * [.renderArea](#dc.lineChart+renderArea) ⇒ Chart - * [.xyTipsOn](#dc.lineChart+xyTipsOn) ⇒ Chart - * [.dotRadius](#dc.lineChart+dotRadius) ⇒ Chart - * [.renderDataPoints](#dc.lineChart+renderDataPoints) ⇒ Chart +* [.scatterPlot](#dc.scatterPlot) ⇒ SeriesChart + * [.existenceAccessor](#dc.scatterPlot+existenceAccessor) ⇒ Chart + * [.symbol](#dc.scatterPlot+symbol) ⇒ Chart + * [.symbolSize](#dc.scatterPlot+symbolSize) ⇒ Chart + * [.highlightedSize](#dc.scatterPlot+highlightedSize) ⇒ Chart + * [.hiddenSize](#dc.scatterPlot+hiddenSize) ⇒ Chart - -#### lineChart.interpolate ⇒ Chart -Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step -functions, splines, and cubic interpolation. This is passed to -[d3.svg.line.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_interpolate) and -[d3.svg.area.interpolate](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_interpolate), -where you can find a complete list of valid arguments + +#### scatterPlot.existenceAccessor ⇒ Chart +Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and +opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, +the existence accessor checks if the reduced value is truthy. -**Kind**: instance property of [lineChart](#dc.lineChart) +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) | Param | Type | | --- | --- | -| [interpolate] | String | - - -#### lineChart.tension ⇒ Chart -Gets or sets the tension to use for lines drawn, in the range 0 to 1. -This parameter further customizes the interpolation behavior. It is passed to -[d3.svg.line.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_tension) and -[d3.svg.area.tension](https://github.com/mbostock/d3/wiki/SVG-Shapes#area_tension). - -**Kind**: instance property of [lineChart](#dc.lineChart) - -| Param | Type | Default | -| --- | --- | --- | -| [tension] | Number | 0.7 | - - -#### lineChart.defined ⇒ Chart -Gets or sets a function that will determine discontinuities in the line which should be -skipped: the path will be broken into separate subpaths if some points are undefined. -This function is passed to -[d3.svg.line.defined](https://github.com/mbostock/d3/wiki/SVG-Shapes#line_defined) +| [accessor] | function | -Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write -custom reduce functions to get this to work, depending on your data. See -https://github.com/dc-js/dc.js/issues/615#issuecomment-49089248 + +#### scatterPlot.symbol ⇒ Chart +Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 +[docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. +Type can be a constant or an accessor. -**Kind**: instance property of [lineChart](#dc.lineChart) +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) | Param | Type | | --- | --- | -| [defined] | function | - - -#### lineChart.dashStyle ⇒ Chart -Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty -array (solid line). - -**Kind**: instance property of [lineChart](#dc.lineChart) - -| Param | Type | Default | -| --- | --- | --- | -| [dashStyle] | Array.<Number> | [] | - -**Example** -```js -// create a Dash Dot Dot Dot -chart.dashStyle([3,1,1,1]); -``` - -#### lineChart.renderArea ⇒ Chart -Get or set render area flag. If the flag is set to true then the chart will render the area -beneath each line and the line chart effectively becomes an area chart. - -**Kind**: instance property of [lineChart](#dc.lineChart) - -| Param | Type | Default | -| --- | --- | --- | -| [renderArea] | Boolean | false | +| [type] | function | - -#### lineChart.xyTipsOn ⇒ Chart -Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis -dashed lines back to each respective axis. This is ignored if the chart brush is on (`brushOn`) + +#### scatterPlot.symbolSize ⇒ Chart +Set or get radius for symbols. -**Kind**: instance property of [lineChart](#dc.lineChart) +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) | Param | Type | Default | | --- | --- | --- | -| [xyTipsOn] | Boolean | false | +| [radius] | Number | 3 | - -#### lineChart.dotRadius ⇒ Chart -Get or set the radius (in px) for dots displayed on the data points. + +#### scatterPlot.highlightedSize ⇒ Chart +Set or get radius for highlighted symbols. -**Kind**: instance property of [lineChart](#dc.lineChart) +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) | Param | Type | Default | | --- | --- | --- | -| [dotRadius] | Number | 5 | - - -#### lineChart.renderDataPoints ⇒ Chart -Always show individual dots for each datapoint. -If `options` is falsy, it disables data point rendering. +| [radius] | Number | 4 | -If no `options` are provided, the current `options` values are instead returned. + +#### scatterPlot.hiddenSize ⇒ Chart +Set or get radius for symbols when the group is empty. -**Kind**: instance property of [lineChart](#dc.lineChart) +**Kind**: instance property of [scatterPlot](#dc.scatterPlot) | Param | Type | Default | | --- | --- | --- | -| [options] | Object | {fillOpacity: 0.8, strokeOpacity: 0.8, radius: 2} | +| [radius] | Number | 0 | -**Example** -```js -chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.8}) -``` ### dc.numberDisplay ⇒ NumberDisplay A display of a single numeric value. @@ -2218,7 +3497,7 @@ a valueAccessor that returns a single value. | Param | Type | Description | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | | [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** @@ -2268,432 +3547,232 @@ Get or set a function to format the value for the display. | --- | --- | --- | | [formatter] | function | d3.format('.2s') | - -### dc.pieChart ⇒ PieChart -The pie chart implementation is usually used to visualize a small categorical distribution. The pie -chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each -slice relative to the sum of all values. Slices are ordered by `.ordering` which defaults to sorting -by key. - -**Kind**: static property of [dc](#dc) -**Mixes**: capMixin,colorMixin,baseMixin - -| Param | Type | Description | -| --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | - -**Example** -```js -// create a pie chart under #chart-container1 element using the default global chart group -var chart1 = dc.pieChart('#chart-container1'); -// create a pie chart under #chart-container2 element using chart group A -var chart2 = dc.pieChart('#chart-container2', 'chartGroupA'); -``` - -* [.pieChart](#dc.pieChart) ⇒ PieChart - * [.slicesCap](#dc.pieChart+slicesCap) ⇒ Chart - * [.externalRadiusPadding](#dc.pieChart+externalRadiusPadding) ⇒ Chart - * [.innerRadius](#dc.pieChart+innerRadius) ⇒ Chart - * [.radius](#dc.pieChart+radius) ⇒ Chart - * [.cx](#dc.pieChart+cx) ⇒ Chart - * [.cy](#dc.pieChart+cy) ⇒ Chart - * [.minAngleForLabel](#dc.pieChart+minAngleForLabel) ⇒ Chart - * [.emptyTitle](#dc.pieChart+emptyTitle) ⇒ Chart - * [.externalLabels](#dc.pieChart+externalLabels) ⇒ Chart - - -#### pieChart.slicesCap ⇒ Chart -Get or set the maximum number of slices the pie chart will generate. The top slices are determined by -value from high to low. Other slices exeeding the cap will be rolled up into one single *Others* slice. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [cap] | Number | - - -#### pieChart.externalRadiusPadding ⇒ Chart -Get or set the external radius padding of the pie chart. This will force the radius of the -pie chart to become smaller or larger depending on the value. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | Default | -| --- | --- | --- | -| [externalRadiusPadding] | Number | 0 | - - -#### pieChart.innerRadius ⇒ Chart -Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the -pie chart will be rendered as a doughnut chart. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | Default | -| --- | --- | --- | -| [innerRadius] | Number | 0 | - - -#### pieChart.radius ⇒ Chart -Get or set the outer radius. If the radius is not set, it will be half of the minimum of the -chart width and height. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [radius] | Number | - - -#### pieChart.cx ⇒ Chart -Get or set center x coordinate position. Default is center of svg. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [cx] | Number | - - -#### pieChart.cy ⇒ Chart -Get or set center y coordinate position. Default is center of svg. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [cy] | Number | - - -#### pieChart.minAngleForLabel ⇒ Chart -Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not -display a slice label. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | Default | -| --- | --- | --- | -| [minAngleForLabel] | Number | 0.5 | - - -#### pieChart.emptyTitle ⇒ Chart -Title to use for the only slice when there is no data. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [title] | String | - - -#### pieChart.externalLabels ⇒ Chart -Position slice labels offset from the outer edge of the chart - -The given argument sets the radial offset. - -**Kind**: instance property of [pieChart](#dc.pieChart) - -| Param | Type | -| --- | --- | -| [radius] | Number | - - -### dc.rowChart ⇒ RowChart -Concrete row chart implementation. + +### dc.heatMap ⇒ HeatMap +A heat map is matrix that represents the values of two dimensions of data using colors. **Kind**: static property of [dc](#dc) -**Mixes**: capMixin,marginMixin,colorMixin,baseMixin +**Mixes**: colorMixin,marginMixin,baseMixin | Param | Type | Description | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | - -**Example** -```js -// create a row chart under #chart-container1 element using the default global chart group -var chart1 = dc.rowChart('#chart-container1'); -// create a row chart under #chart-container2 element using chart group A -var chart2 = dc.rowChart('#chart-container2', 'chartGroupA'); -``` - -* [.rowChart](#dc.rowChart) ⇒ RowChart - * [.x](#dc.rowChart+x) ⇒ Chart - * [.renderTitleLabel](#dc.rowChart+renderTitleLabel) ⇒ Chart - * [.xAxis](#dc.rowChart+xAxis) ⇒ d3.svg.Axis - * [.fixedBarHeight](#dc.rowChart+fixedBarHeight) ⇒ Chart - * [.gap](#dc.rowChart+gap) ⇒ Chart - * [.elasticX](#dc.rowChart+elasticX) ⇒ Chart - * [.labelOffsetX](#dc.rowChart+labelOffsetX) ⇒ Chart - * [.labelOffsetY](#dc.rowChart+labelOffsetY) ⇒ Chart - * [.titleLabelOffsetX](#dc.rowChart+titleLabelOffsetX) ⇒ Chart - - -#### rowChart.x ⇒ Chart -Gets or sets the x scale. The x scale can be any d3 -[quantitive scale](https://github.com/mbostock/d3/wiki/Quantitative-Scales) - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | -| --- | --- | -| [scale] | d3.scale | - - -#### rowChart.renderTitleLabel ⇒ Chart -Turn on/off Title label rendering (values) using SVG style of text-anchor 'end' - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | -| --- | --- | -| [renderTitleLabel] | Boolean | - - -#### rowChart.xAxis ⇒ d3.svg.Axis -Get the x axis for the row chart instance. Note: not settable for row charts. -See the [d3 axis object](https://github.com/mbostock/d3/wiki/SVG-Axes#wiki-axis) documention for more information. - -**Kind**: instance property of [rowChart](#dc.rowChart) -**Example** -```js -// customize x axis tick format -chart.xAxis().tickFormat(function (v) {return v + '%';}); -// customize x axis tick values -chart.xAxis().tickValues([0, 100, 200, 300]); -``` - -#### rowChart.fixedBarHeight ⇒ Chart -Get or set the fixed bar height. Default is [false] which will auto-scale bars. -For example, if you want to fix the height for a specific number of bars (useful in TopN charts) -you could fix height as follows (where count = total number of bars in your TopN and gap is -your vertical gap space). - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | -| --- | --- | -| [height] | Number | - -**Example** -```js -chart.fixedBarHeight( chartheight - (count + 1) * gap / count); -``` - -#### rowChart.gap ⇒ Chart -Get or set the vertical gap space between rows on a particular row chart instance - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | Default | -| --- | --- | --- | -| [gap] | Number | 5 | - - -#### rowChart.elasticX ⇒ Chart -Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the -data range when filtered. - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | -| --- | --- | -| [elasticX] | Boolean | - - -#### rowChart.labelOffsetX ⇒ Chart -Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart. - -**Kind**: instance property of [rowChart](#dc.rowChart) - -| Param | Type | Default | -| --- | --- | --- | -| [labelOffsetX] | Number | 10 | - - -#### rowChart.labelOffsetY ⇒ Chart -Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart. +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | -**Kind**: instance property of [rowChart](#dc.rowChart) +**Example** +```js +// create a heat map under #chart-container1 element using the default global chart group +var heatMap1 = dc.heatMap('#chart-container1'); +// create a heat map under #chart-container2 element using chart group A +var heatMap2 = dc.heatMap('#chart-container2', 'chartGroupA'); +``` -| Param | Type | Default | -| --- | --- | --- | -| [labelOffsety] | Number | 15 | +* [.heatMap](#dc.heatMap) ⇒ HeatMap + * [.colsLabel](#dc.heatMap+colsLabel) ⇒ Chart + * [.rowsLabel](#dc.heatMap+rowsLabel) ⇒ Chart + * [.rows](#dc.heatMap+rows) ⇒ Chart + * [.cols](#dc.heatMap+cols) ⇒ Chart + * [.boxOnClick](#dc.heatMap+boxOnClick) ⇒ Chart + * [.xAxisOnClick](#dc.heatMap+xAxisOnClick) ⇒ Chart + * [.yAxisOnClick](#dc.heatMap+yAxisOnClick) ⇒ Chart + * [.xBorderRadius](#dc.heatMap+xBorderRadius) ⇒ Chart + * [.yBorderRadius](#dc.heatMap+yBorderRadius) ⇒ Chart - -#### rowChart.titleLabelOffsetX ⇒ Chart -Get of set the x offset (horizontal space between right edge of row and right edge or text. + +#### heatMap.colsLabel ⇒ Chart +Set or get the column label function. The chart class uses this function to render +column labels on the X axis. It is passed the column name. -**Kind**: instance property of [rowChart](#dc.rowChart) +**Kind**: instance property of [heatMap](#dc.heatMap) | Param | Type | Default | | --- | --- | --- | -| [x] | Number | 2 | +| [labelFunction] | function | function(d) { return d; } | - -### dc.scatterPlot ⇒ SeriesChart -A scatter plot chart +**Example** +```js +// the default label function just returns the name +chart.colsLabel(function(d) { return d; }); +``` + +#### heatMap.rowsLabel ⇒ Chart +Set or get the row label function. The chart class uses this function to render +row labels on the Y axis. It is passed the row name. -**Kind**: static property of [dc](#dc) -**Mixes**: coordinateGridMixin +**Kind**: instance property of [heatMap](#dc.heatMap) -| Param | Type | Description | +| Param | Type | Default | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | -| [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | +| [labelFunction] | function | function(d) { return d; } | **Example** ```js -// create a scatter plot under #chart-container1 element using the default global chart group -var chart1 = dc.scatterPlot('#chart-container1'); -// create a scatter plot under #chart-container2 element using chart group A -var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA'); -// create a sub-chart under a composite parent chart -var chart3 = dc.scatterPlot(compositeChart); +// the default label function just returns the name +chart.rowsLabel(function(d) { return d; }); ``` + +#### heatMap.rows ⇒ Chart +Gets or sets the values used to create the rows of the heatmap, as an array. By default, all +the values will be fetched from the data using the value accessor, and they will be sorted in +ascending order. -* [.scatterPlot](#dc.scatterPlot) ⇒ SeriesChart - * [.existenceAccessor](#dc.scatterPlot+existenceAccessor) ⇒ Chart - * [.symbol](#dc.scatterPlot+symbol) ⇒ Chart - * [.symbolSize](#dc.scatterPlot+symbolSize) ⇒ Chart - * [.highlightedSize](#dc.scatterPlot+highlightedSize) ⇒ Chart - * [.hiddenSize](#dc.scatterPlot+hiddenSize) ⇒ Chart +**Kind**: instance property of [heatMap](#dc.heatMap) - -#### scatterPlot.existenceAccessor ⇒ Chart -Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and -opacity 1; if it does not exist, it is drawn with hiddenSize radius and opacity 0. By default, -the existence accessor checks if the reduced value is truthy. +| Param | Type | +| --- | --- | +| [rows] | Array.<(String\|Number)> | -**Kind**: instance property of [scatterPlot](#dc.scatterPlot) + +#### heatMap.cols ⇒ Chart +Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all +the values will be fetched from the data using the key accessor, and they will be sorted in +ascending order. + +**Kind**: instance property of [heatMap](#dc.heatMap) | Param | Type | | --- | --- | -| [accessor] | function | +| [cols] | Array.<(String\|Number)> | - -#### scatterPlot.symbol ⇒ Chart -Get or set the symbol type used for each point. By default the symbol is a circle. See the D3 -[docs](https://github.com/mbostock/d3/wiki/SVG-Shapes#wiki-symbol_type) for acceptable types. -Type can be a constant or an accessor. + +#### heatMap.boxOnClick ⇒ Chart +Gets or sets the handler that fires when an individual cell is clicked in the heatmap. +By default, filtering of the cell will be toggled. -**Kind**: instance property of [scatterPlot](#dc.scatterPlot) +**Kind**: instance property of [heatMap](#dc.heatMap) | Param | Type | | --- | --- | -| [type] | function | +| [handler] | function | - -#### scatterPlot.symbolSize ⇒ Chart -Set or get radius for symbols. + +#### heatMap.xAxisOnClick ⇒ Chart +Gets or sets the handler that fires when a column tick is clicked in the x axis. +By default, if any cells in the column are unselected, the whole column will be selected, +otherwise the whole column will be unselected. -**Kind**: instance property of [scatterPlot](#dc.scatterPlot) +**Kind**: instance property of [heatMap](#dc.heatMap) -| Param | Type | Default | -| --- | --- | --- | -| [radius] | Number | 3 | +| Param | Type | +| --- | --- | +| [handler] | function | - -#### scatterPlot.highlightedSize ⇒ Chart -Set or get radius for highlighted symbols. + +#### heatMap.yAxisOnClick ⇒ Chart +Gets or sets the handler that fires when a row tick is clicked in the y axis. +By default, if any cells in the row are unselected, the whole row will be selected, +otherwise the whole row will be unselected. -**Kind**: instance property of [scatterPlot](#dc.scatterPlot) +**Kind**: instance property of [heatMap](#dc.heatMap) + +| Param | Type | +| --- | --- | +| [handler] | function | + + +#### heatMap.xBorderRadius ⇒ Chart +Gets or sets the X border radius. Set to 0 to get full rectangles. + +**Kind**: instance property of [heatMap](#dc.heatMap) | Param | Type | Default | | --- | --- | --- | -| [radius] | Number | 4 | +| [xBorderRadius] | Number | 6.75 | - -#### scatterPlot.hiddenSize ⇒ Chart -Set or get radius for symbols when the group is empty. + +#### heatMap.yBorderRadius ⇒ Chart +Gets or sets the Y border radius. Set to 0 to get full rectangles. -**Kind**: instance property of [scatterPlot](#dc.scatterPlot) +**Kind**: instance property of [heatMap](#dc.heatMap) | Param | Type | Default | | --- | --- | --- | -| [radius] | Number | 0 | +| [yBorderRadius] | Number | 6.75 | - -### dc.seriesChart ⇒ SeriesChart -A series chart is a chart that shows multiple series of data overlaid on one chart, where the -series is specified in the data. It is a specialization of Composite Chart and inherits all -composite features other than recomposing the chart. + +### dc.boxPlot ⇒ BoxPlot +A box plot is a chart that depicts numerical data via their quartile ranges. +Examples: +- [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) +- [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: compositeChart +**Mixes**: coordinateGridMixin | Param | Type | Description | | --- | --- | --- | -| parent | String | node | d3.selection | dc.compositeChart | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | +| parent | String | node | d3.selection | [compositeChart](#dc.compositeChart) | Any valid [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance. | | [chartGroup] | String | The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group. | **Example** ```js -// create a series chart under #chart-container1 element using the default global chart group -var seriesChart1 = dc.seriesChart("#chart-container1"); -// create a series chart under #chart-container2 element using chart group A -var seriesChart2 = dc.seriesChart("#chart-container2", "chartGroupA"); +// create a box plot under #chart-container1 element using the default global chart group +var boxPlot1 = dc.boxPlot('#chart-container1'); +// create a box plot under #chart-container2 element using chart group A +var boxPlot2 = dc.boxPlot('#chart-container2', 'chartGroupA'); ``` -* [.seriesChart](#dc.seriesChart) ⇒ SeriesChart - * [.chart](#dc.seriesChart+chart) ⇒ Chart - * [.seriesAccessor](#dc.seriesChart+seriesAccessor) ⇒ Chart - * [.seriesSort](#dc.seriesChart+seriesSort) ⇒ Chart - * [.valueSort](#dc.seriesChart+valueSort) ⇒ Chart +* [.boxPlot](#dc.boxPlot) ⇒ BoxPlot + * [.boxPadding](#dc.boxPlot+boxPadding) ⇒ Number + * [.outerPadding](#dc.boxPlot+outerPadding) ⇒ Number + * [.boxWidth](#dc.boxPlot+boxWidth) ⇒ Number | function + * [.tickFormat](#dc.boxPlot+tickFormat) ⇒ Number | function - -#### seriesChart.chart ⇒ Chart -Get or set the chart function, which generates the child charts. + +#### boxPlot.boxPadding ⇒ Number +Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. +See the [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands) +for a visual description of how the padding is applied. -**Kind**: instance property of [seriesChart](#dc.seriesChart) +**Kind**: instance property of [boxPlot](#dc.boxPlot) | Param | Type | Default | | --- | --- | --- | -| chartFunction | function | dc.lineChart | +| [padding] | Number | 0.8 | -**Example** -```js -// put interpolation on the line charts used for the series -chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); }) -// do a scatter series chart -chart.chart(dc.scatterPlot) -``` - -#### seriesChart.seriesAccessor ⇒ Chart -Get or set accessor function for the displayed series. Given a datum, this function -should return the series that datum belongs to. + +#### boxPlot.outerPadding ⇒ Number +Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts +or on charts with a custom `.boxWidth`. Will pad the width by `padding * barWidth` on each side of the chart. -**Kind**: instance property of [seriesChart](#dc.seriesChart) +**Kind**: instance property of [boxPlot](#dc.boxPlot) -| Param | Type | -| --- | --- | -| [accessor] | function | +| Param | Type | Default | +| --- | --- | --- | +| [padding] | Number | 0.5 | - -#### seriesChart.seriesSort ⇒ Chart -Get or set a function to sort the list of series by, given series values. + +#### boxPlot.boxWidth ⇒ Number | function +Get or set the numerical width of the boxplot box. The width may also be a function taking as +parameters the chart width excluding the right and left margins, as well as the number of x +units. -**Kind**: instance property of [seriesChart](#dc.seriesChart) +**Kind**: instance property of [boxPlot](#dc.boxPlot) -| Param | Type | -| --- | --- | -| [sortFunction] | function | +| Param | Type | Default | +| --- | --- | --- | +| [boxWidth] | Number | function | 0.5 | **Example** ```js -chart.seriesSort(d3.descending); +// Using numerical parameter +chart.boxWidth(10); +// Using function +chart.boxWidth((innerChartWidth, xUnits) { ... }); ``` - -#### seriesChart.valueSort ⇒ Chart -Get or set a function to sort each series values by. By default this is the key accessor which, -for example, will ensure a lineChart series connects its points in increasing key/x order, -rather than haphazardly. + +#### boxPlot.tickFormat ⇒ Number | function +Set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to +integer formatting. -**Kind**: instance property of [seriesChart](#dc.seriesChart) +**Kind**: instance property of [boxPlot](#dc.boxPlot) | Param | Type | | --- | --- | -| [sortFunction] | function | +| [tickFormat] | function | +**Example** +```js +// format ticks to 2 decimal places +chart.tickFormat(d3.format('.2f')); +``` From 7dd8d36c924f05408003de1f42e563fdcdfab6c5 Mon Sep 17 00:00:00 2001 From: Matt Traynham Date: Mon, 17 Aug 2015 02:07:03 -0400 Subject: [PATCH 8/8] Fixes mixes jsdoc --- src/bar-chart.js | 3 ++- src/box-plot.js | 2 +- src/bubble-chart.js | 3 ++- src/bubble-mixin.js | 2 +- src/bubble-overlay.js | 3 ++- src/composite-chart.js | 2 +- src/coordinate-grid-mixin.js | 4 +++- src/data-count.js | 2 +- src/data-grid.js | 2 +- src/data-table.js | 2 +- src/geo-choropleth-chart.js | 3 ++- src/heatmap.js | 4 +++- src/line-chart.js | 3 ++- src/number-display.js | 2 +- src/pie-chart.js | 4 +++- src/row-chart.js | 5 ++++- src/scatter-plot.js | 2 +- src/series-chart.js | 2 +- web/docs/api-latest.md | 36 ++++++++++++++++++------------------ 19 files changed, 50 insertions(+), 36 deletions(-) diff --git a/src/bar-chart.js b/src/bar-chart.js index 8c416e213..6c8c73dd1 100644 --- a/src/bar-chart.js +++ b/src/bar-chart.js @@ -5,7 +5,8 @@ * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) * @name barChart * @memberOf dc - * @mixes baseMixin + * @mixes dc.stackMixin + * @mixes dc.coordinateGridMixin * @example * // create a bar chart under #chart-container1 element using the default global chart group * var chart1 = dc.barChart('#chart-container1'); diff --git a/src/box-plot.js b/src/box-plot.js index d7735796a..f655a4b98 100644 --- a/src/box-plot.js +++ b/src/box-plot.js @@ -5,7 +5,7 @@ * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) * @name boxPlot * @memberOf dc - * @mixes coordinateGridMixin + * @mixes dc.coordinateGridMixin * @example * // create a box plot under #chart-container1 element using the default global chart group * var boxPlot1 = dc.boxPlot('#chart-container1'); diff --git a/src/bubble-chart.js b/src/bubble-chart.js index 1091aaf74..d3b0d205a 100644 --- a/src/bubble-chart.js +++ b/src/bubble-chart.js @@ -10,7 +10,8 @@ * - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) * @name bubbleChart * @memberOf dc - * @mixes bubbleMixin,coordinateGridMixin + * @mixes dc.bubbleMixin + * @mixes dc.coordinateGridMixin * @example * // create a bubble chart under #chart-container1 element using the default global chart group * var bubbleChart1 = dc.bubbleChart('#chart-container1'); diff --git a/src/bubble-mixin.js b/src/bubble-mixin.js index c5cd7b570..59b2a4307 100644 --- a/src/bubble-mixin.js +++ b/src/bubble-mixin.js @@ -3,7 +3,7 @@ * @name bubbleMixin * @memberOf dc * @mixin - * @mixes colorMixin + * @mixes dc.colorMixin * @param {Chart} _chart * @returns {Chart} */ diff --git a/src/bubble-overlay.js b/src/bubble-overlay.js index 176455135..026460fb7 100644 --- a/src/bubble-overlay.js +++ b/src/bubble-overlay.js @@ -7,7 +7,8 @@ * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) * @name bubbleOverlay * @memberOf dc - * @mixes bubbleMixin,baseMixin + * @mixes dc.bubbleMixin + * @mixes dc.baseMixin * @example * // create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group * var bubbleChart1 = dc.bubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg')); diff --git a/src/composite-chart.js b/src/composite-chart.js index 1d339729f..af55f29d7 100644 --- a/src/composite-chart.js +++ b/src/composite-chart.js @@ -4,7 +4,7 @@ * achieve some quite flexible charting effects. * @name compositeChart * @memberOf dc - * @mixes coordinateGridMixin + * @mixes dc.coordinateGridMixin * @example * // create a composite chart under #chart-container1 element using the default global chart group * var compositeChart1 = dc.compositeChart('#chart-container1'); diff --git a/src/coordinate-grid-mixin.js b/src/coordinate-grid-mixin.js index e83b9b115..f18e86d0a 100644 --- a/src/coordinate-grid-mixin.js +++ b/src/coordinate-grid-mixin.js @@ -4,7 +4,9 @@ * @name coordinateGridMixin * @memberOf dc * @mixin - * @mixes colorMixin,marginMixin,baseMixin + * @mixes dc.colorMixin + * @mixes dc.marginMixin + * @mixes dc.baseMixin * @param {Chart} _chart * @returns {Chart} */ diff --git a/src/data-count.js b/src/data-count.js index c3e37f4f5..01e7be70a 100644 --- a/src/data-count.js +++ b/src/data-count.js @@ -10,7 +10,7 @@ * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) * @name dataCount * @memberOf dc - * @mixes baseMixin + * @mixes dc.baseMixin * @example * var ndx = crossfilter(data); * var all = ndx.groupAll(); diff --git a/src/data-grid.js b/src/data-grid.js index 9874f6e5f..e01624da5 100644 --- a/src/data-grid.js +++ b/src/data-grid.js @@ -10,7 +10,7 @@ * - [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) * @name dataGrid * @memberOf dc - * @mixes baseMixin + * @mixes dc.baseMixin * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart diff --git a/src/data-table.js b/src/data-table.js index 21c565816..832759c9b 100644 --- a/src/data-table.js +++ b/src/data-table.js @@ -10,7 +10,7 @@ * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) * @name dataTable * @memberOf dc - * @mixes baseMixin + * @mixes dc.baseMixin * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying * a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart diff --git a/src/geo-choropleth-chart.js b/src/geo-choropleth-chart.js index a1d867c0c..c9d297662 100644 --- a/src/geo-choropleth-chart.js +++ b/src/geo-choropleth-chart.js @@ -5,7 +5,8 @@ * - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) * @name geoChoroplethChart * @memberOf dc - * @mixes colorMixin,baseMixin + * @mixes dc.colorMixin + * @mixes dc.baseMixin * @example * // create a choropleth chart under '#us-chart' element using the default global chart group * var chart1 = dc.geoChoroplethChart('#us-chart'); diff --git a/src/heatmap.js b/src/heatmap.js index 0289e2404..72d71030a 100644 --- a/src/heatmap.js +++ b/src/heatmap.js @@ -2,7 +2,9 @@ * A heat map is matrix that represents the values of two dimensions of data using colors. * @name heatMap * @memberOf dc - * @mixes colorMixin,marginMixin,baseMixin + * @mixes dc.colorMixin + * @mixes dc.marginMixin + * @mixes dc.baseMixin * @example * // create a heat map under #chart-container1 element using the default global chart group * var heatMap1 = dc.heatMap('#chart-container1'); diff --git a/src/line-chart.js b/src/line-chart.js index 4e8cc103e..39eba1806 100644 --- a/src/line-chart.js +++ b/src/line-chart.js @@ -5,7 +5,8 @@ * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) * @name lineChart * @memberOf dc - * @mixes stackMixin,coordinateGridMixin + * @mixes dc.stackMixin + * @mixes dc.coordinateGridMixin * @example * // create a line chart under #chart-container1 element using the default global chart group * var chart1 = dc.lineChart('#chart-container1'); diff --git a/src/number-display.js b/src/number-display.js index 7072af6ac..10b131ba8 100644 --- a/src/number-display.js +++ b/src/number-display.js @@ -4,7 +4,7 @@ * a valueAccessor that returns a single value. * @name numberDisplay * @memberOf dc - * @mixes baseMixin + * @mixes dc.baseMixin * @example * // create a number display under #chart-container1 element using the default global chart group * var display1 = dc.numberDisplay('#chart-container1'); diff --git a/src/pie-chart.js b/src/pie-chart.js index d7e427285..cff40f956 100644 --- a/src/pie-chart.js +++ b/src/pie-chart.js @@ -5,7 +5,9 @@ * by key. * @name pieChart * @memberOf dc - * @mixes capMixin,colorMixin,baseMixin + * @mixes dc.capMixin + * @mixes dc.colorMixin + * @mixes dc.baseMixin * @example * // create a pie chart under #chart-container1 element using the default global chart group * var chart1 = dc.pieChart('#chart-container1'); diff --git a/src/row-chart.js b/src/row-chart.js index 38ad316af..cae5e3423 100644 --- a/src/row-chart.js +++ b/src/row-chart.js @@ -2,7 +2,10 @@ * Concrete row chart implementation. * @name rowChart * @memberOf dc - * @mixes capMixin,marginMixin,colorMixin,baseMixin + * @mixes dc.capMixin + * @mixes dc.marginMixin + * @mixes dc.colorMixin + * @mixes dc.baseMixin * @example * // create a row chart under #chart-container1 element using the default global chart group * var chart1 = dc.rowChart('#chart-container1'); diff --git a/src/scatter-plot.js b/src/scatter-plot.js index 6eda5852b..75cf295ed 100644 --- a/src/scatter-plot.js +++ b/src/scatter-plot.js @@ -2,7 +2,7 @@ * A scatter plot chart * @name scatterPlot * @memberOf dc - * @mixes coordinateGridMixin + * @mixes dc.coordinateGridMixin * @example * // create a scatter plot under #chart-container1 element using the default global chart group * var chart1 = dc.scatterPlot('#chart-container1'); diff --git a/src/series-chart.js b/src/series-chart.js index 4a05beeb4..8c424874d 100644 --- a/src/series-chart.js +++ b/src/series-chart.js @@ -4,7 +4,7 @@ * composite features other than recomposing the chart. * @name seriesChart * @memberOf dc - * @mixes compositeChart + * @mixes dc.compositeChart * @example * // create a series chart under #chart-container1 element using the default global chart group * var seriesChart1 = dc.seriesChart("#chart-container1"); diff --git a/web/docs/api-latest.md b/web/docs/api-latest.md index 1a5fc4d79..ffb3cf991 100644 --- a/web/docs/api-latest.md +++ b/web/docs/api-latest.md @@ -1144,7 +1144,7 @@ Coordinate Grid is an abstract base chart designed to support a number of coordi concrete chart types, e.g. bar chart, line chart, and bubble chart. **Kind**: static mixin of [dc](#dc) -**Mixes**: colorMixin,marginMixin,baseMixin +**Mixes**: [colorMixin](#dc.colorMixin), [marginMixin](#dc.marginMixin), [baseMixin](#dc.baseMixin) | Param | Type | | --- | --- | @@ -1761,7 +1761,7 @@ chart.othersGrouper(function (data) { This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles. **Kind**: static mixin of [dc](#dc) -**Mixes**: colorMixin +**Mixes**: [colorMixin](#dc.colorMixin) | Param | Type | | --- | --- | @@ -2023,7 +2023,7 @@ slice relative to the sum of all values. Slices are ordered by `.ordering` which by key. **Kind**: static property of [dc](#dc) -**Mixes**: capMixin,colorMixin,baseMixin +**Mixes**: [capMixin](#dc.capMixin), [colorMixin](#dc.colorMixin), [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -2154,7 +2154,7 @@ Examples: - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Mixes**: [stackMixin](#dc.stackMixin), [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- | @@ -2251,7 +2251,7 @@ Examples: - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: stackMixin,coordinateGridMixin +**Mixes**: [stackMixin](#dc.stackMixin), [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- | @@ -2400,7 +2400,7 @@ Examples: - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) **Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Mixes**: [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -2469,7 +2469,7 @@ Examples: - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/) **Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Mixes**: [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -2625,7 +2625,7 @@ Examples: - [List of members of the european parliament](http://europarl.me/dc.js/web/ep/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Mixes**: [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -2748,7 +2748,7 @@ Examples: - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: bubbleMixin,coordinateGridMixin +**Mixes**: [bubbleMixin](#dc.bubbleMixin), [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- | @@ -2780,7 +2780,7 @@ Grid. You can overlay (compose) different bar/line/area charts in a single compo achieve some quite flexible charting effects. **Kind**: static property of [dc](#dc) -**Mixes**: coordinateGridMixin +**Mixes**: [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- | @@ -2937,7 +2937,7 @@ series is specified in the data. It is a specialization of Composite Chart and i composite features other than recomposing the chart. **Kind**: static property of [dc](#dc) -**Mixes**: compositeChart +**Mixes**: [compositeChart](#dc.compositeChart) | Param | Type | Description | | --- | --- | --- | @@ -3020,7 +3020,7 @@ Examples: - [US Venture Capital Landscape 2011](http://dc-js.github.com/dc.js/vc/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: colorMixin,baseMixin +**Mixes**: [colorMixin](#dc.colorMixin), [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -3110,7 +3110,7 @@ Examples: - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: bubbleMixin,baseMixin +**Mixes**: [bubbleMixin](#dc.bubbleMixin), [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -3170,7 +3170,7 @@ value specified here are relative to the underlying svg. Concrete row chart implementation. **Kind**: static property of [dc](#dc) -**Mixes**: capMixin,marginMixin,colorMixin,baseMixin +**Mixes**: [capMixin](#dc.capMixin), [marginMixin](#dc.marginMixin), [colorMixin](#dc.colorMixin), [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -3408,7 +3408,7 @@ This setting takes into account gap(). A scatter plot chart **Kind**: static property of [dc](#dc) -**Mixes**: coordinateGridMixin +**Mixes**: [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- | @@ -3493,7 +3493,7 @@ Unlike other charts, you do not need to set a dimension. Instead a group object a valueAccessor that returns a single value. **Kind**: static property of [dc](#dc) -**Mixes**: baseMixin +**Mixes**: [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -3552,7 +3552,7 @@ Get or set a function to format the value for the display. A heat map is matrix that represents the values of two dimensions of data using colors. **Kind**: static property of [dc](#dc) -**Mixes**: colorMixin,marginMixin,baseMixin +**Mixes**: [colorMixin](#dc.colorMixin), [marginMixin](#dc.marginMixin), [baseMixin](#dc.baseMixin) | Param | Type | Description | | --- | --- | --- | @@ -3697,7 +3697,7 @@ Examples: - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html) **Kind**: static property of [dc](#dc) -**Mixes**: coordinateGridMixin +**Mixes**: [coordinateGridMixin](#dc.coordinateGridMixin) | Param | Type | Description | | --- | --- | --- |