Methods
When you invoke Chart2Music, it will return 2 items:
err- an error message (null if there were no errors)data- an individual C2M instance
An individual C2M instance has a handful of methods you can call:
appendData
This method allows a developer to add new data to a chart, without having to reset the entire chart's contents. The most common use case for this is for streaming data.
In order for this to work most effectively, please use the config live: true. When you set this item, users will be told that the chart is "live", so that they can expect that the chart will update. This will also enable your users to click "M" for "Monitor" mode, which will play the new data as it appends.
Parameters
| Parameter | Type | Required? | Description |
|---|---|---|---|
| dataPoint | any supported data type (eg, number) | required | The data you would like to append |
| categoryName | string | optional | If the chart has multiple categories, use this parameter to specify where you want the data to be appended to |
Examples
A chart without categories:
const {err, data: chart} = c2mChart({
type: "line",
element,
cc,
data: [1,2,3,4],
options: {
live: true
}
});
// Wait 1 second, and then append the number 5 to the chart's data
setTimeout(() => {
chart.appendData(5);
}, 1000)
A chart with categories:
const {err, data: chart} = c2mChart({
type: "line",
element,
cc,
data: {
a: [1,2,3,4],
b: [9,8,7,6]
},
options: {
live: true
}
});
setTimeout(() => {
chart.appendData(5, "a");
}, 1000)
cleanUp
This method will tear down changes made by calling c2mChart. Specifically, it removes:
- event listeners from the chart element
- attributes from the cahrt element
- dialogs from the DOM
After calling cleanUp, the chart will be not be navigable by keyboard or screen reader users.
getCurrent
This method allows a developer to determine which data point has focus.
Return properties
| Property | Type | Description |
|---|---|---|
| index | number | The index of the current data point |
| group | string | The name of the category currently in focus, if relevant |
| point | data point | The data point in focus |
| stat | string | Which statistic is in focus, if relevant |
Examples
Simple chart:
const {err, data: chart} = c2mChart({
type: "line",
element,
cc,
data: [
{x: 0, y: 100},
{x: 1, y: 200},
{x: 2, y: 300},
{x: 3, y: 400}
]
});
// When the user is focused x=2, y=300
chart.getCurrent();
/*
Returns:
{
index: 2,
group : "",
stat: "",
point: {
x: 2,
y: 300 // the provided value
}
}
*/
Chart with categories:
const {err, data: chart} = c2mChart({
type: "line",
element,
cc,
data: {
a: [100, 200, 300, 400],
b: [900, 800, 700, 600]
}
});
// When the user is focused on x=2, y=700, category=b
chart.getCurrent();
/*
Returns:
{
index: 2,
group : "b",
stat: "",
point: {
x: 2, // X value is determined based on the index when not explicitly provided
y: 700
}
}
*/
Chart with statistics:
const {err, data: chart} = c2mChart({
type: "line",
element,
cc,
data: [
{x: 0, high: 15, low: 7},
{x: 1, high: 20, low: 10},
{x: 2, high: 18, low: 13},
{x: 3, high: 18, low: 15}
]
});
// When the user is focused on "high" on the 3rd data point
chart.getCurrent();
/*
Returns:
{
index: 2,
group : "",
stat: "high",
point: {
x: 2,
high: 18,
low: 13
}
}
*/
setCategoryVisibility
This method lets you show or hide individual categories on a chart.
Parameters
| Parameter | Type | Required? | Description |
|---|---|---|---|
| categoryName | string | required | which category are we manipulating? |
| state | boolean | required | should the category be visible (true) or not (false)? |
Examples
const {data: chart} = c2mChart({
type: "line",
element,
cc,
data: {
a: [100, 200, 300, 400],
b: [900, 800, 700, 600]
}
});
// Hide "b"
chart.setCategoryVisibility("b", false);
// Show "b"
chart.setCategoryVisibility("b", true);
setData
This method lets you reset the data that drives your chart, as well as related metadata.
Parameters
| Parameter | Type | Required? | Description |
|---|---|---|---|
| data | any supported data type (eg number) | required | The new data |
| axes | AxisData | optional | Any new axis metadata (eg min/max) |
| pointIndex | number | optional | Which point should have focus after the data has reset (Defaults to first point) |
| categoryName | string | optional | Which group should have focus after the data has reset |
Examples
Resetting just data
const {data: chart} = c2mChart({
type: "line",
element,
cc,
data: [6, 7, 8, 9]
});
// Zoom out the chart:
chart.setData([4,5,6,7,8,9,10]);
In the above example, the user will be moved back to the front of the chart after it zooms out. This experience could be disorienting for the them. In order to keep the user where they were, use the pointIndex parameter:
const {data: chart} = c2mChart({
type: "line",
element,
cc,
data: [6, 7, 8, 9]
});
const {index} = chart.getCurrent();
// Zoom out the chart:
chart.setData(
[4,5,6,7,8,9,10] // new data
{}, // axis metadata (empty because there's no change)
index // stay at the current index
);
Now, the end-user won't move from 8, even as the chart zooms out.
Resetting data and axes:
const {data: chart} = c2mChart({
title: "Flour Sales",
type: "line",
element,
cc,
axes: {
y: {
label: "Sales in USD",
format: (value) => "$" + value // Put a $ in front of the number
}
},
data: [61, 73, 68],
})
// Change the unit on the Y axis
chart.setData(
[123, 145, 136],
{
y: {
label: "Sales in pounds",
format: (value) => value // Undo the USD formatter
}
}
)
And keeping the user from moving:
const {data: chart} = c2mChart({
title: "Flour Sales",
type: "line",
element,
cc,
axes: {
y: {
label: "Sales in USD",
format: (value) => "$" + value // Put a $ in front of the number
}
},
data: {
downtown: [61, 73, 68],
suburbs: [75, 79, 73]
},
});
// Get the user's current location
const {index, group} = chart.getCurrent();
// Change the unit on the Y axis
chart.setData(
{
downtown: [123, 145, 136],
suburbs: [145, 150, 148]
},
{
y: {
label: "Sales in pounds",
format: (value) => value // Undo the USD formatter
}
},
index, // eg, 2
group // eg, "suburbs"
)
// After the data updates, the user will be at x=2, y=148, category=suburbs