Zoomdata Version

Migrating Custom Charts

OVERVIEW

Starting with Zoomdata v2.2, the Zoomdata application is powered by a new client library. This client library provides the APIs needed to integrate custom chart templates. To make your custom chart templates work with the new client library and Zoomdata v2.2, you will need to make a few changes to your custom chart template. While the overall logic has not been changed for integrating your custom chart template with Zoomdata, the new data accessors simplify the API and make integration easier.

This document covers the steps needed to migrate your custom charts to use the new interface. For information about upgrading your embedded applications of Zoomdata, see Migrating from the Legacy SDK .

Controller object Improvements

The controller's API has been extensively, but not completely, redesigned in the new client library. While there has been no change to the basic logic integrating a chart with Zoomdata, controller's methods have been reorganized. The table below indicates new methods used to replace methods from the legacy version of the client library.

Data Accessors

Each variable needed by your visualization has a data accessor that you can access through controller.dataAccessors . These accessors expose all the variables that your chart needs, such as its metrics and groups. These accessors also expose user selections for color and data value formatting.

Accessing User Color Choices

You can use data accessors to accomplish tasks like determine which UI variable manages the chart's current color selection, and then use those colors in your chart.

var colorAccessor;

// identify the data accessor that exposes UI-selected color preference
controller.dataAccessors.forEach( function(theAccessor) {
if (theAccessor.isColor) { colorAccessor = theAccessor; }
}

var colorsActive = colorAccessor.getColorRange('active');

Summary of Changes

The following chart indicates APIs for working with the controller object from the original Zoomdata client library. For each of the groups of original methods and properties, there are notes indicating whether and how the methods or properties have changed in the new client library's controller object.

Legacy Client Library object Use New Client Library object Notes
controller.element HTML element containing the visualization. Charts are typically attached to an HTML element in the browser window; use this member variable where the visualization's HTML element is required. controller.element API is unchanged
controller.update( data, progress ) called by Zoomdata when new data needs to be sent to a chart. You should override this function with your own definition. controller.update( data, progress ) API is unchanged
controller.resize( height, width, size ) called by Zoomdata when a chart's HTML container is resized. You should override this function with your own definition. controller.resize( height, width, size ) API is unchanged
controller.onNoDataFound() called by Zoomdata whenever there is no data found for the current query configuration. You should override this function with your own definition. controller.onNoDataFound() API is unchanged
controller.clear() called by Zoomdata when a chart needs to be cleared. You should override this function with your own definition. controller.clear() API is unchanged
controller.metrics[chart_variable] metrics were accessed by a distinct path controller.dataAccessors[chart_variable]
controller.dataAccessors.getMetricAccessors();

For a full list of member methods and objects, see hosted JSdocs (coming soon).
metrics are now accessed through the dataAccessors property of controller. chart_variable is a string literal or a variable string that matches the name of a chart variable, such as "Bar Height" or "Bar Width" or "Arc Size". The variable used must be set up correctly in the Chart Studio Manage > Variables control. the controller.dataAccessors path contains an object for each chart variable (metrics and groups).
controller.state.groupBy.setAttribute('usercity');
controller.state.groupBy.setAttributes(['usercity', 'product']);
controller.state.groupBy.at(0).setLimit(20);
controller.state.groupBy.at(0).setSortDirection('Ascending Value');
controller.state.groupBy.at(0).setSortMetric('plannedsales');
groups were accessed by a distinct path controller.dataAccessors[chart_variable]

For a full list of member methods and objects, see hosted JSdocs (coming soon).
groups are now accessed through the dataAccessors property of controller.
chart_variable is a string literal or a variable string that matches the name of a chart variable, such as "Bar Height" or "Bar Width" or "Arc Size". The variable used must be set up correctly in the Chart Studio Manage > Variables control. the controller.dataAccessors path contains an object for each chart variable (metrics and groups).
controller.state.filters.reset();
controller.state.addFilter(filter);
controller.state.addFilters(filters);
controller.state.removeFilter(filter);
controller.state.setFilter(filter);
filters were accessed through the state object controller.query.filters.addFilters(filtersSet)
controller.query.filters.addToAll(filtersSet)
controller.query.filters.removeFilters(filtersSet)
controller.query.filters.removeFromAll(filtersSet)
filters are now a member of controller