@terrestris/d3-util
v0.9.5
Published
A set of helper classes for working with d3 charts.
Downloads
22
Maintainers
Keywords
Readme
d3-util
A set of helper classes for working with d3 charts.
Installation
npm i @terrestris/d3-util
In order to use the library in your project, make sure you load the moment.js library as well.
Usage
General notes
The ChartRenderer
is the main entry point to render a chart. It features a
render
method that can be used to render its components to a given DOM node.
The chart renderer can be constructed with a few parameters:
components
: a list of chart components constituting the chartsize
: the desired chart size in pixelszoomType
: the desired zoom type.'none'
for no zoom,'transform'
for a zoom using the svgtransform
attribute without rebuilding the DOM or'rerender'
for a zoom rebuilding the DOM. Using the transform method has the effect of also zooming the shapes, i.e. a line of 1px will get bigger when zooming in.onMouseMoveFunc
: the function that will be called on every mouse move over the entiresvg
.
Components
LegendComponent
The legend component simply renders a list of legend elements. It accepts the following configuration parameters:
extraClasses
: a string with extra CSS classes to add to the legend grouplegendEntryMaxLength
: a number with the max number of characters per line for legend labelsposition
: an array[x, y]
with the desired position within the svgitems
: an array of legend element configurations
The legend items can have the following configuration parameters:
contextmenuHandler
: can be a function that is called in case the user right clicks or long touches the item. Argument is thed3.event
eventcustomRenderer
: can be a function that is called during rendering and will be called with the item's group element. Can be used to e.g. render custom buttons for the legend elementonClick
: can be a function getting the currentd3.event
once an item is clickedonHover
: can be a function getting the currentd3.event
once the mouse is over the itemonMouseOut
: can be a function getting the currentd3.event
once the mouse is leaving the itemstyle
: can be an object with svg style parameters such asstroke
,stroke-width
etc. in order to style the legend icontitle
: the legend textvalue
: if set, avalue
attribute will be added to the legend nodetype
: can be'line'
,'bar'
,'area'
or'background'
in order to render a line, a small bar chart icon, a line with the area below it filled or just a filled block
BarComponent
The bar component can render (grouped) bar charts. It accepts the following configuration parameters:
axes
: an axis configuration object (see below)backgroundColor
: can be a hex color stringextraClasses
: a string with extra CSS classes to set on the bar chart nodeposition
: the[x, y]
coordinatesrotateBarLabel
: if true, the labels will be rotated by 90°size
: the[width, height]
sizetitle
: if set, a heading will be rendered with this texttitleColor
: the color hex stringtitlePadding
: title padding from the toptitleSize
: title sizegroupedInitiallyHidden
: a list of grouping indexes for bars that should initially be hiddengroupsInitiallyHidden
: a list of group indexes for bars that should initially be hiddendata
: the data object. Example:
{
data: [{
value: 'Value 1',
values: [{
index: 'Group 1',
value: 23,
uncertainty: undefined,
color: '#ff0000',
belowThreshold: false,
label: '23',
tooltipFunc: target => 'Tooltip'
}, {
index: 'Group 3',
value: 42,
uncertainty: 5.6,
color: '#00ff00',
belowThreshold: true,
label: '<'
}]
}],
grouped: ['Group 1', 'Group 2', 'Group 3']
}
The grouped
field contains a list of the grouped indexes, the data list
contains the actual groups. A group object contains a value
with the group
name/label and a list of values
corresponding to the actual bars.
The bar objects can have a number of configuration values:
index
: corresponds to one of the value in thegrouped
list (not all grouped values must be contained in every group)value
: the actual y valueuncertainty
: if set to a value, an uncertainty indicator will be rendered on top of the barcolor
: the hex color valuebelowThreshold
: if true, no bar will be drawn, just the labellabel
: if set, a label will be rendered onto the bartooltipFunc
: if set, the function will be called with the bar element upon mouseover
TimeseriesComponent
The timeseries component can render multiple line charts. It supports the following configuration parameters:
axes
: an axis configuration object (see below)backgroundColor
: as color hex stringextraClasses
: extra classes to set on the timeseries chart nodeposition
: the[x, y]
coordinatessize
: the[width, height]
sizetitle
: if set, a heading will be rendered with this texttitleColor
: the color hex stringtitlePadding
: title padding from the toptitleSize
: title sizeinitialZoom
: if set, an initial zoom transform object (withx
,y
,kx
andky
set)moveToRight
: if set totrue
, theinitialZoom
will be modified so the timeseries is scrolled completely to the rightseries
: a list of line chart configurations as follows
A line chart configuration has the following options:
axes
: a list of axis ids referencing x and y axis configurations like['x', 'y0']
color
: the color hex stringcurveType
: a d3 curve type string likecurveStepBefore
shapeType
: usually'line'
, can also be'area'
useTooltipFunc
: a boolean indicating whether the third data value is a tooltip mouseover function and fifth value is a mouseout functiondata
: an array with the data:[xvalue, yvalue, mouseOverFunc, styleObject, mouseOutFunc]
initiallyVisible
: a boolean indicating whether the line is initially visible defaulting to true
The tooltip function is optional as well as the style. If the style is set, it is used to configure the corresponding point symbol. Examples for style objects would be:
{
"type": "circle",
"radius": "5"
}
{
"type": "circle",
"radius": "10"
}
{
"type": "star",
"sides": 5,
"radius": 10
}
{
"type": "rect",
"width": 15,
"height": 20
}
Axis configuration objects
The axis configuration objects configure the scales and axes of a chart. You'll
need to configure at least an x
and a y
axis, but at least for line charts
multiple y axes are allowed (you still must use the same x axis for all lines).
The object maps axis ids (with x
and y
mandatory) to axis configurations,
which may have the following options:
display
: boolean that determines whether the axis is drawn or notformat
: a d3 format string like",.2f"
,"dynamic"
, a format array or a format functionlabel
: an optional axis labellabelColor
: the label color hex stringlabelPadding
: label paddinglabelRotation
: label rotationlabelSize
: label sizemax
: the axis and scale max value (optional)min
: the axis and scale min value (optional)orientation
: the axis orientation (x or y)sanitizeLabels
: if set to true, overlapping tick labels will be removed (only supported for y axes)scale
: the scale to use (linear, log, time)tickPadding
: the tick paddingtickSize
: the tick sizefactor
: if set, the axis' max value will be divided by this value so you can get a bigger interval when using auto calculated min/max values
If the format is set to "dynamic"
, it will be dynamically adjusted to the
following d3-format equivalents, based on the rendered value:
value < 1
:.3f
1 < value < 10
:.2f
10 < value < 100
:.1f
100 < value
:.0f
If the format is set to an array, it must be an array of objects like this:
[{
"min": 0,
"max": 1,
"format": ".3f"
}, {
"min": 1,
"max": 100,
"format": ".0f"
}]
A format matches a value, if the value is >= min
and < max
. You can use
"-Infinity"
and "Infinity"
for min and max to get unbounded classes.
A note on line charts: you can have multiple y axes here. Using the line chart axis references you can have some lines correspond to one y axis and some lines correspond to another y axis. As noted above, you still need to use the same x axis for all lines (else the chart would supposedly be confusing anyway).
Development
If you want to contribute, you can build the project like this:
git checkout https://github.com/terrestris/d3-util
cd d3-util
npm i
and then either
npm run build:dev
in order to get a development build or
npm run build:dist
in order to get a production build.