Custom Chart Tutorial Part Four

Welcome to part four of the custom chart tutorial. In this part, examine the types of controls that you can add to custom charts to make them more dynamic and reusable.

Axis Labels / Pickers

It is very common for end-users to want to explore a dataset by changing the group-by and metric fields used by a chart. For this scenario, Zoomdata provides an API for chart developers to quickly add axis labels that can act as controls to replace group-by and metric selections.

Let’s revisit the custom chart we have been working on throughout this tutorial. At the moment, it has a default group-by and metric selection defined at the source level. Let’s add some axis labels so that we can change the group-by and metric selection from within the chart itself. Using the CLI, enable Watch mode and the following code to the end of the Visualization.js file:

//...
controller.createAxisLabel({
  picks: 'Group By',
  position: 'bottom',
  orientation: 'horizontal',
});

controller.createAxisLabel({
  picks: 'Size',
  position: 'bottom',
  orientation: 'horizontal',
});

The controller.createAxisLabel method takes an object with the configuration options of the axis label. The following table describes possible option names and values you can use:

Option Description
picks Name of the query variable. Tip: Use the data accessor’s getName method to avoid hardcoding variable names
position Location of the axis label in the chart widget. Valid options: ‘bottom’, ‘left’, ‘right’, ‘top’
orientation Orientation of the axis label text. Valid options: ‘vertical’, ‘horizontal’

Preview the chart in a dashboard and notice the new axis labels/pickers below the chart. Play around with the controls and notice how the chart reacts to the changes in the query.

Axis Labels

Tooltips

In addition to axis labels, custom charts can define the use of Zoomdata tooltips to keep consistency with the look and feel of the out of the box charts. The pie chart we are building is currently using the Highcharts tooltips. Let’s re-define the tooltips using Zoomdata’s API.

The first step is to disabled the Highcharts tooltips:

var chart = Highcharts.chart(chartContainer, {
  tooltip: {
    enabled: false,
  },
//...

The second step is to add the original Zoomdata datum to the objects in the dataset. We simply need to modify the reshapeData function as follows:

function reshapeData(data) {
  return data.map(function(d) {
    return {
      name: groupAccessor.raw(d),
      y: metricAccessor.raw(d),
      datum: d,
    };
  });
}

Finally, we will add a mouseOver and mouseOut event handlers to each point in the series:

var chart = Highcharts.chart(chartContainer, {
//... other options
  series: [
    {
      name: metricAccessor.getLabel(),
      point: {
        events: {
          mouseOver: function(param) {
            controller.tooltip.show({
              x: param.target.tooltipPos[0],
              y: param.target.tooltipPos[1],
              data: function() {
                return param.target.datum;
              },
            });
          },
          mouseOut: function() {
            controller.tooltip.hide();
          },
        },
      },
    },
  ],
});

Notice the use of controller.tooltip.show and controller.tooltip.hide. The show method receives an option with the following properties:

Option Description
x The x coordinate in the screen where the tooltip should render
y The y coordinate in the screen where the tooltip should render
data Function that returns a Zoomdata datum object

Optional properties:

Option Description
event Takes a native browser event to specify the tooltip position. An alternative to x and y properties.
content Function that returns an HTML string to replace the content inside of the tooltip boxes

Whenever we mouse-over a pie slice, the mouseOver handler runs and the controller.tooltip.show API is called to display the tooltip. Likewise, the mouseOver event handler runs when the mouse leaves the pie slice and the controller.tooltip.hide API will be called to hide the tooltip.

The following image shows the custom pie chart with the Zoomdata tooltips displayed: Zoomdata Tooltips Shown

Radial Menu

The radial menu is a type of control found in many of the out-of-the-box Zoomdata charts. Chart developers will typically associate the click event of a chart’s data point to trigger the display the radial menu. Most of the time, the radial menu is used to do quick filtering operations on the chart itself or other charts in the dashboard.

Here’s an overview of the type of actions exposed as part of the radial menu:

Action Description
Zoom Open a panel to select a new attribute to drill into. The selection automatically changes the group-by field in the query and adds a filter condition matching the clicked data point
Filter Open a panel to select other charts in the dashboard to filter with a condition matching the clicked data point
Filter All Automatically filters all other charts in the dashboard from the same source with a condition matching the clicked data point
Details Opens a panel with a Raw Data table chart displaying the full set of records matching the clicked data point
Trend Switches the current chart to the out of the box Line Chart: Multiple Metrics chart and adds the clicked data point as a filter
Remove Removes the clicked data point by adding a filter to the query to exclude it

Similar to the tooltip API, Zoomdata provides an API that can be used to show the radial menu with the default actions outlined above. Let’s add the radial menu to the custom pie chart with the following code:

var chart = Highcharts.chart(chartContainer, {
  //... other options
  series: [
    {
      name: metricAccessor.getLabel(),
      point: {
        events: {
          click: function(param) {
            controller.menu.show({
              x: param.x,
              y: param.y,
              data: function() {
                return param.point.datum;
              },
            });
          },
          mouseOver: function(param) {
            controller.tooltip.show({
              x: param.target.tooltipPos[0],
              y: param.target.tooltipPos[1],
              data: function() {
                return param.target.datum;
              },
            });
          },
          mouseOut: function() {
            controller.tooltip.hide();
          },
        },
      },
    },
  ],
});

Notice the use of controller.menu.show. The show method receives an option with the following properties:

Option Description
x The x coordinate in the screen where the menu should render
y The y coordinate in the screen where the menu should render
data Function that returns a Zoomdata datum object

Optional properties:

Option Description
event Takes a native browser event to specify the menu position. An alternative to x and y properties.
menu Used to customize the list of actions that display in the menu. Custom actions along with their callbacks can be defined. Here’s an example menu: { items: ['Exclude', 'Zoom', 'Filter', 'Filter All', 'Info', 'Trend', 'Custom'], 'Custom': function() { // some custom action } }

Now, whenever we click a pie slice, the radial menu will be displayed and any of its actions can be triggered. Here is an image of what it looks like when it renders:

Zoomdata Radial Menu Show

Other Controls

In addition to the controls covered above, Zoomdata allows chart developers to show or hide the controls on the left rail of the chart. Zoomdata Other Controls

The display of these controls is configured using the CLI. Let’s practice by adding the Sort & Limit and the Color controls to the chart.

Type the following command into the terminal window and hit ENTER.

zd-chart edit "My First Custom Chart"

Follow the prompts and select the following options:

  1. Controls
  2. Using the arrows and the spacebar, select Sort & Limit and Color from the list

Press ENTER to make your selections and answer “N” to Would you like to make additional edits?

Refresh the custom chart in a dashboard and notice the two new controls on the left-hand rail. Note: You need to maximize the widget to see the left-hand rail if you have other charts in the dashboard.

Play around with the Sort & Limit control by changing the metric sort direction and by modifying the limit. The chart will automatically react to the new settings.

If you try to use the Color control, you will notice that the panel will not open. The color control will only work if we set one of our query variables as “driver” color. Since this is a pie chart with a different color per slice, let’s modify the group-by variable to use it as a driver of color in the chart.

Type the following command into the terminal window and hit ENTER.

zd-chart edit "My First Custom Chart"

Follow the prompts and select the following options:

  1. Variables
  2. Edit a variable
  3. Group By
  4. Configuration
  5. ATTRIBUTE & TIME

Answer “Y” to Will this variable drive color in your chart?. Answer “N” to Would you like to make additional edits?

Switch back to the dashboard and refresh to get the latest changes to the chart. The color control should now work, but the colors displayed do not match the ones in the pie chart.

Colors Don't Match

To fix the color mismatch, we need to tell Highcharts what color to use for each of the pie slices. Fortunately, Zoomdata provides an API via the data accessors for extracting the color based on a datum. In the data that we are providing to the chart, we can specify the color to associate with the data point.

Let’s make that minor modification:

function reshapeData(data) {
  return data.map(function(d) {
    return {
      name: groupAccessor.raw(d),
      y: metricAccessor.raw(d),
      datum: d,
      color: groupAccessor.color(d),
    };
  });
}

Notice how we are using the groupAccessor to extract the color since that’s tied to the “Group By” variable that is driving the color of the chart.

Here is the final look chart using Zoomdata colors:

Chart with Zoomdata Colors

Feel free to change the color palette used and see chart chart colors automatically reflect the change of palette.

That’s a Wrap

We have completed the final part of the custom chart tutorial. You are now armed with the necessary tools and knowledge to go and build new and feature rich charts in Zoomdata. Please check back periodically for updates to this tutorial. Hope you enjoyed it!