@nebula.js/sn-bar-chart
Version:
Bar chart supernova
309 lines (265 loc) • 7.79 kB
Markdown
The bar chart is suitable for comparing multiple values. The dimension
axis shows the category items that are compared, and the measure axis
shows the value for each category item.
Requires `@nebula.js/stardust` version `1.7.0` or later.
If you use npm: `npm install @nebula.js/sn-bar-chart`. You can also load through the script tag directly from [https://unpkg.com](https://unpkg.com/@nebula.js/sn-bar-chart).
<!--Property specification: <Link
to="/apis/javascript/nebula-bar-chart">@nebula.js/sn-bar-chart:properties</Link>-->
```js
import { embed } from '@nebula.js/stardust';
import bar from '@nebula.js/sn-bar-chart';
// 'app' is an enigma app model
const nuked = embed(app, {
types: [
{
// register bar chart
name: 'barchart',
load: () => Promise.resolve(bar),
},
],
});
// Rendering a bar chart on the fly
nuked.render({
type: 'barchart',
element: document.querySelector('.bars'),
fields: ['Dim1', '=Sum(Expression1)'],
options: {
direction: 'ltr',
freeResize: true,
viewState: {
scrollPosition: 25,
},
},
properties: {
color: { mode: 'byDimension' }, // overrides default properties
},
});
```
- direction - ltr/rtl
- freeResize - in conjunction with snapshotData on layout,
lets the chart ignore size set on snapshotData
- viewState - settings for the initial rendering of the table
- viewState.scrollPosition - pixel position of the scroll
You can make more complex comparisons of data by using grouped or stacked bars.
This requires using two dimensions and one measure.
The [Grouped bar chart](
[](
use the same two dimensions and the same measure.
You can change the orientation of a bar chart by following
this [Horizontal bar chart](
Grouped bars: with grouped bars, you can easily compare
two or more items in the same categorical group.
```js
// Rendering a bar chart on the fly
nuked.render({
type: 'barchart',
element: document.querySelector('.bars'),
fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
// overrides default properties
properties: {
barGrouping: {
grouping: 'grouped',
},
dataPoint: {
showLabels: true,
showSegmentLabels: false,
showTotalLabels: true,
},
},
});
```
Stacked bars: with stacked bars it is easier to compare
the total quantity between different months.
Stacked bars combine bars of different groups on top of each other
and the total height of the resulting bar represents the combined result.
```js
// Rendering a bar chart on the fly
nuked.render({
type: 'barchart',
element: document.querySelector('.bars'),
fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
// overrides default properties
properties: {
barGrouping: {
grouping: 'stacked',
},
dataPoint: {
showLabels: true,
showSegmentLabels: true,
showTotalLabels: true,
},
},
});
```
The bar chart can be displayed horizontally or vertically
by setting `orientation` property to `horizontal` or `vertical`,
as a horizontal bar chart example below:
```js
// Rendering a bar chart on the fly
nuked.render({
type: 'barchart',
element: document.querySelector('.bars'),
fields: ['Product Group', '=Sum(Sales)', '=Sum(Margin)'],
// overrides default properties
properties: {
barGrouping: {
grouping: 'grouped',
},
dataPoint: {
showLabels: true,
showSegmentLabels: false,
showTotalLabels: true,
},
orientation: 'horizontal',
},
});
```
A plugin can be passed into a bar chart to add or modify its capability
or visual appearance.
A plugin needs to be defined before it can be rendered together with the chart.
```js
// Step 1: define the plugin
// Adding a line plugin that goes through the ends of the bars
const linePlugin = {
info: {
name: 'line-plugin',
type: 'component-definition',
},
fn: ({ keys, layout }) => {
const componentDefinition = {
key: 'sum-line',
type: 'line',
layout: { displayOrder: 10 },
data: { collection: keys.COLLECTION.MAIN },
settings: {
coordinates: {
minor: { scale: keys.SCALE.MAIN.MINOR, fn: (d) => d.scale(d.datum.end.value) },
major: { scale: keys.SCALE.MAIN.MAJOR },
},
layers: { line: { stroke: 'red', strokeWidth: 2, opacity: 0.5, strokeDasharray: '5 10' } },
},
};
return componentDefinition;
},
};
// Step 2: passing the plugin definition into the render function
// Render a bar chart with plugins
nuked.render({
element: document.querySelector('#object'),
type: 'sn-bar-chart',
plugins: [linePlugin],
fields: ['Letter', '=Sum(Frequency)*100'],
// eslint-disable-next-line no-undef
properties: {
title: 'Frequencies of Letters in English (%)',
},
});
```
The plugin definition is an object, with two properties `info` and `fn`.
The `fn` returns a `picasso.js` component. To build this component,
some important chart internals are passed into the argument object of `fn`.
```js
// Structure of the argument object of fn
const pluginArgs = {
layout,
keys: {
SCALE: {
MAIN: {
MINOR,
MAJOR,
},
},
COMPONENT: {
BAR,
BAR_AXIS,
Y_AXIS,
MEASURE_TITLE,
DIMENSION_TITLE,
},
COLLECTION: {
MAIN,
},
},
};
```
With plugins, you can either add new components or modify existing components
of the bar chart.
The new component can be a standard Picasso component
or a custom Picasso component. Here we demo a standard
reference line component at the median of the frequency values.
```js
// Adding reference line at the median of the frequency
const medianReferenceLinePlugin = {
info: {
name: 'median-reference-line-plugin',
type: 'component-definition',
},
fn: ({ keys, layout }) => {
const frequencies = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => item[1].qNum);
const value = getMedian(frequencies);
const componentDefinition = {
key: 'median-reference-line',
type: 'ref-line',
layout: { displayOrder: 4 },
lines: {
y: [
{
line: {
stroke: 'black',
strokeWidth: 2,
strokeDasharray: '5 10',
},
scale: keys.SCALE.MAIN.MINOR,
value,
label: {
text: `Median frequency:`,
fontSize: '15px',
// opacity: 1,
},
},
],
},
};
return componentDefinition;
},
};
```
As an example, the bar component can be modified with plugin.
To overide an existing component, `fn` should returns a `picasso.js` component
that has the same `key` as the existing component (`keys.COMPONENT.BAR` in
this example)
```js
// Modifying the look of the existing bar component
const barPlugin = {
info: {
name: 'bar-plugin',
type: 'component-definition',
},
fn: ({ layout, keys }) => {
const componentDefinition = {
type: 'box',
// Provide the same name as the exisiting line component to override it
key: keys.COMPONENT.BAR,
settings: {
box: { width: 0.8, stroke: 'dimgray', strokeWidth: 2 },
},
};
return componentDefinition;
},
};
```
- The plugins API is still experimental.
- We can not guarantee our charts to be compatible with all different settings, especially when modifying existing components.