chart.md

this documentation is partly outdated

Chart is the core class for each Datawrapper chart. The concept of charts and visualizations might be confusing, so please read on to get the idea: A chart is an abstract wrapper around the dataset and the ...

Initializing charts

var chart = dw.chart(attributes);

Operating on charts

# chart.get()

Retrieves one of the direct attributes of a chart (such as id or type) as well as any of the settings stored in the metadata JSON field.

const { id, title } = chart.get();

# chart.getMetadata(key, default)

Retrieves a value stored in the metadata JSON field.

const showHeader = chart.getMetadata('visualize.showHeader', true);

# chart.set(state)

Overrides one of the direct attributes of a chart (such as id or type) as well as any of the settings stored in the metadata JSON field. Note that the changes are not automatically synchronized with the data model on the server.

chart.set({ type: 'bar-chart' });

In order to synchronize the attributes you need to listen to change events and then update your data source accordingly. In Datawrapper we use [dw.backend.syncChart](Synchronizing charts with UI elements) for that.

# chart.setMetadata(key, value)

Stores a value in the metadata JSON field.

chart.setMetadata('visualize.showHeader', false);

# chart.onChange(callback)

Executes the callback function every time the chart attributes have been changed.

chart.onChange(function(chart, key, value) {
   console.log('The value of '+key+' has been changed to '+value);
});
chart.set('title', 'Foo');
// logs "The value of title has been changed to Foo"

# chart.observe(callback)

Executes the callback function every time the chart attributes have been changed. The difference to onChange is that the execution is throttled for 100ms so that several consecutive changes are grouped into one call.

chart.observe(function(chart, changes) {
   console.log(changes);
});
chart.set('title', 'Foo');
chart.set('type', 'line-chart');
// logs [{ key: "title", value: "Foo"}, { key: "type", value: "line-chart"}]

# chart.load([csvData])

Loads the chart data. Uses a datasource to fetch some data, for instance from a CSV file, and convert it into a dataset. Returns a deferred. If you provide the csvData argument it will be used as csv data instead of loading it from file. Note that you can also pass the dataset directly via chart.dataset().

chart.load().done(function() {
   // yay, the data has been loaded!
});

# chart.loaded(callback)

If the dataset has been loaded already, this will immediately call the callback function with the chart as first argument. Otherwise the callback will be kept and executed as soon the dataset has been loaded.

# chart.reload()

After a chart has been loaded once, it can be reloaded without having to download the data source again. Returns a deferred.

chart.load().done(function() {
   // chart has been loaded
   chart.reload();
});

# chart.dataset([dataset])

If called without any argument, this function returns the loaded dataset, including any changes stored in the chart metadata (such as data changes). If you provide the dataset argument the function sets it as new chart dataset and returns the chart instance.

chart.dataset();  // returns the chart dataset
chart.dataset(ds);  // sets ds as new dataset
chart.dataset(true);  // returns the chart dataset after re-applying changes, column sorting etc

# chart.theme(theme)

Gets or sets the theme.

chart.theme(dw.theme('default'));

# chart.vis(visualization)

Gets or sets the visualization.

var lineChart = new Datawrapper.Visualization.LineChart();
// initialize line chart...
chart.vis(lineChart);

# chart.columnFormatter(column)

Returns a function to convert values of a given column into nicely formatted strings. The behavior of the format function usually depends on the column type, the locale, the data input precision and user preferences (as set in descripe step in chart editor).

var dateColumn = chart.dataset().column('TIME'),
    formatter = chart.columnFormatter(dateColumn);

dateColumn.each(function(date) {
    console.log(formatter(date));
});

By default the formatter function uses the short format (the formatted number without prepending and appending any text). To get the long format you need to pass true a second parameter.

formatter(value); // short format, e.g. "12.3"
formatter(value, true); // long format, e.g. "USD 12.3"