Skip to content

Latest commit

 

History

History
373 lines (268 loc) · 13.2 KB

README.md

File metadata and controls

373 lines (268 loc) · 13.2 KB
Raw

Chart templates

This is the documentation for our chart templates, which can be found in templates/charts/.

Table of Contents

Getting started

All the charts in these templates use d3.js (version 5), which will be automatically installed when you set up a new chart or run npm install.

Importing templates

Each template can be imported into your javascript as an ES6 module and instantiated as a chart object. For example, here's how you would create a new bar chart in the div #g-chart-example:

import HorizontalBarChart from '../templates/charts/bar-chart-horizontal.js';

const BARS_DATA = [
  {
    name: 'Bar 1',
    value: '20',
  },
  {
    name: 'Bar 2',
    value: '10',
  },
];

const exampleChart = new HorizontalBarChart({
  containerId: 'g-chart-example',
  data: BARS_DATA,
  bandKey: 'name',
  valueKey: 'value',
});

Importing styles

Stylesheets can be found in templates/charts/stylesheets/ and imported in your graphic.scss file.

@import 'charts/stylesheets/chart-with-axes.scss';
@import 'charts/stylesheets/chart-labels.scss';

Individual template config options

Each chart type accepts an object of config options to customize the chart. All charts must include a containerId, which is used to select the DOM element where the chart will be drawn.

ChartBase

Options for the base template, which just draws an SVG. All of these options will be available to other templates.

# config.containerId - String. Required.

The id of the DOM element where the chart will be drawn. Should not include the # identifier.

# config.responsive - Boolean. Default value: true

Whether the chart should redraw on tmp_resize.

# config.aspectRatio - Number or Function. Default value: 4/3

The aspect ratio of the chart canvas, expressed as a ratio of width to height. Any positive finite value is accepted, though for readability we prefer a math expression (e.g. 16/9) to a decimal value (e.g. 1.77). A higher value will be a shallower chart; a lower value will be a taller chart. The default value, 4/3, represents a chart with a height that is three-quarters of its width.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

Example: Setting aspect ratio responsively

The example below sets an aspect ratio of 4:3 for charts with a width smaller than 600px, and a ratio of 16:9 for wider charts.

const mobileBreak = 600;

const responsiveChart = new ChartBase({
  containerId: 'g-chart-example',
  aspectRatio: (width) => { return width < mobileBreak ? 4/3 : 16/9 }
});

# config.marginTop - Number or Function. Default value: 10

The space between the top edge of the SVG and the area where the chart itself is drawn.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

# config.marginRight - Number or Function. Default value: 10

The space between the right edge of the SVG and the area where the chart itself is drawn.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

# config.marginBottom - Number or Function. Default value: 10

The space between the bottom edge of the SVG and the area where the chart itself is drawn.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

# config.marginLeft - Number or Function. Default value: 10

The space between the left edge of the SVG and the area where the chart itself is drawn.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

ChartWithAxes

Options for the chart with axes template, which extends ChartBase and draws X and Y axes onto the SVG.

Inherits all config options made available by ChartBase.

# config.data - Array. Required.

An array of data. If no rounded min/max values are defined, the range of any data scales will calculate the maximum and minimum values from this data to serve as the range.

# config.xKey - String. Required.

The name of the property through which the x value can be accessed in each datum.

# config.yKey - String. Required.

The name of the property through which the y value can be accessed in each datum.

# config.xDataFormat - Function. Default value: (d) => { return +d; }

A function that accesses and/or formats the x data value.

# config.yDataFormat - Function. Default value: (d) => { return +d; }

A function that accesses and/or formats the y data value.

# config.roundedXMin - Number, Date. Default value: null

If the x data uses a numeric scale, this value will be used to set the minimum value of the xScale range (and thus the minimum value displayed on the x axis). Useful for setting your axes to tidy, rounded values.

# config.roundedYMin - Number, Date. Default value: null

If the y data uses a numeric scale, this value will be used to set the minimum value of the yScale range (and thus the minimum value displayed on the y axis). Useful for setting your axes to tidy, rounded values.

# config.roundedXMax - Number, Date. Default value: null

If the x data uses a numeric scale, this value will be used to set the maximum value of the xScale range (and thus the maximum value displayed on the x axis). Useful for setting your axes to tidy, rounded values.

# config.roundedYMax - Number, Date. Default value: null

If the y data uses a numeric scale, this value will be used to set the maximum value of the yScale range (and thus the maximum value displayed on the y axis). Useful for setting your axes to tidy, rounded values.

# config.xAxisTickFormat - Function. Default value: (d, width) => { return utilities.addCommas(d) }

A function that formats the tick labels along the x axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.

Example: Setting tick format responsively

The example below formats ticks as 1k, 2k, etc. for charts narrower than 600px and 1,000, 2,000, etc. for wider charts.

const mobileBreak = 600;

const responsiveChart = new ChartWithAxes({
  containerId: 'g-chart-example',
  data: EXAMPLE_DATA,
  xKey: 'x',
  yKey: 'y',
  xAxisTickFormat: (d, width) => { return width < mobileBreak ? `${ d / 1000 }k` : utilities.addCommas(d) }
});

# config.yAxisTickFormat - Function. Default value: (d, width) => { return utilities.addCommas(d) }

A function that formats the tick labels along the y axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.

# config.xAxisTicks
# config.yAxisTicks
# config.xAxisTickArguments
# config.yAxisTickArguments
# config.xAxisTickValues
# config.yAxisTickValues

Implementing d3.js's axis tick options for the x and y axes, respectively. See the d3 documentation.

Can be expressed as a function with one argument, the width of the chart SVG in pixels, to set values responsively.

VerticalBarChart

Options for the vertical bar chart template, which extends ChartWithAxes and draws a bar chart with bars running vertically.

Inherits all config options made available by ChartBase and ChartWithAxes, with some new default values noted below.

To make it as easy as possible to convert from a vertical bar chart to a horizontal bar chart, the config options reference data by band and value rather than x and y. band refers to the category or name of each bar (i.e. the independent variable), while value refers to the size of each bar (the dependent variable).

# config.bandKey - String. Required.

The name of the property through which the bar's band can be accessed in each datum.

# config.valueKey - String. Required.

The name of the property through which the bar's value can be accessed in each datum.

# config.bandDataFormat - Function. Default value: (d) => { return d; }

A function that accesses and/or formats the band data value.

# config.valueDataFormat - Function. Default value: (d) => { return +d; }

A function that accesses and/or formats the value data value.

# config.barPadding - Number. Default value: 0.1

A value between 0 and 1 that sets the inner and outer padding of each band. Refer to the d3.js documentation for band.padding().

# config.roundBarSize - Boolean. Default value: false

If true, the start and stop position of each band will be integers. Refer to the d3.js documentation for band.round().

# config.labelFormat - Function. Default value: (d) => { return utilities.addCommas(d) }

A function that formats the label displayed with each bar.

# config.xAxisTickFormat - Function. Default value: (d, width) => { return d }

A function that formats the tick labels along the x axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.

# config.yAxisTickFormat - Function. Default value: (d, width) => { return utilities.addCommas(d) }

A function that formats the tick labels along the y axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.

HorizontalBarChart

# config.xAxisTickFormat - Function. Default value: (d, width) => { return utilities.addCommas(d) }

A function that formats the tick labels along the x axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.

# config.yAxisTickFormat - Function. Default value: (d, width) => { return d }

A function that formats the tick labels along the y axis. The function is passed two arguments: d, representing the value of the tick, and width, the width of the chart SVG, which can be used to format the ticks responsively.