Zoomdata Version

Configuring Charts Via Visualization Variables

Overview

When a Zoomdata chart is embedded into a custom application, it uses the default settings provided in the data source configuration for that chart. For example, your source Real Time Sales has a default configuration for pie charts, established when the data source is created. For more information about configuring a source's default settings for a particular chart, see Example Chart Setup . To use the default configuration with an embedded chart, you only need to make sure that the correct metrics and fields or groups are present in the data query that supplies the chart with data and leave the variables key null ( {} ) in the visualize() call. For more information about configuring and creating a data query, see Query Configuration Object or Using a Data Query.

When embedding a chart, you also have the option of overriding default configurations by modifying the configuration of chart settings. You modify the default settings with the variables key in the parameter passed to the visualize() method.

Steps for Overriding Default Chart Settings

These high-level steps will guide your work in adjusting the settings used for visualizing a chart in an embedded application.

  1. Identify chart settings
  2. Encode settings

Identifying Chart Settings

Before you can encode settings into an embedded visualization, you must identify every required setting as well as any optional settings that you wish to use. Chart settings can be identified using an internal REST API method. The REST API method used in these steps is considered internal to the Zoomdata application. Internal APIs should not be used except as directed. For more information about using internal APIs, see Cautionary Note About Internal APIs.

  1. Find or create a dashboard that uses the chart.
  2. Make a GET call to
    https://yourserver/path/service/bookmarks

    in which

    • yourserver/path is the DNS and path for your Zoomdata server

    Internally, Zoomdata refers to dashboards as bookmarks.

    You can use curl, for example:

    curl --user name:password -X GET https://yourserver/path/service/bookmarks -H "Content-Type: application/vnd.zoomdata.v1+json;"
    

    in which:

    • name and password are the name and password with authorization to request information about the source
    • yourserver/path is the DNS and path for your Zoomdata server

    Previously, we had recommended using the /service/sources endpoint for this process. That endpoint still works, but the /bookmarks endpoint provides more information about more chart variables and may be more useful.

  3. Search the response object to find the bookmark whose name matches your dashboard's.
    The bookmarks each contain a visualizations array. The visualizations array contains a visualization object for each chart in the dashboard
  4. Find the visualization object that matches your chart within that bookmark's visualizations array.
    The visualization objects each include a variables object.

You can copy and modify the variables object for your embedding code.

The following example of a visualization definition object and the variables object that it contains are subject to change. Subsequent versions of Zoomdata will be accompanied by docs highlighting significant changes. For more information about using internal APIs, see Cautionary Note About Internal APIs.
"visualizations": [
	{
		"id": "591b499ee4b0190a47ad4aa7",
		"visId": "58b91e4ce4b0190a47ad4839",
		"ownerDashboardId": "591b499ee4b0190a47ad4aa5",
		"name": "Bars",
		"type": "UBER_BARS",
		"enabled": false,
		"widgetId": "bd2b4396fd79c6f79c435464ede28180",
		"layout": {},
		"source": {
		"variables": {
			"Multi Group By": [
				{
				"sort": {
					"dir": "desc",
					"name": "count" },
				"limit": 50,
				"name": "broadphaseofflight",
				"label": "Broad Phase Of Flight",
				"type": "ATTRIBUTE",
				"groupColorSet": "ZoomSequential",
				"autoShowColorLegend": false,
				"colorNumb": 3,
				"autoColor": true,
				"groupColors": {}
				},
			...
			],
		"Chart Name": "",
		"Metric": [
			{
			"name": "count"
			}
		],
		...
	}

The chart settings, together with their default values for the particular data source queried, are listed as the value of the variables key, as a single object.

Encoding Settings

Chart settings are encoded into the variables member of the object passed to the visualize() method. For example:

client.visualize({
	element: vizLocation,
	config: queryConfig,
	source: {name: 'Real Time Sales'},
	visualization: 'Bars',
	variables: {
		"Multi Group By": [
			{
			"sort": {
				"dir": "desc",
				"name": "count" },
			"limit": 50,
			"name": "broadphaseofflight",
			"label": "Broad Phase Of Flight",
			"type": "ATTRIBUTE",
			"groupColorSet": "ZoomSequential",
			"autoShowColorLegend": false,
			"colorNumb": 3,
			"autoColor": true,
			"groupColors": {}
			}
		],
		"Chart Name": "",
		"Metric": [
			{
			"name": "count"
			}
		],
	...
});

To encode the variables, follow the follow steps, depending on how you identified them.

To encode variables identified by using the REST API call:

Prior to v2.4, visualization variables needed to be stringified. Starting with Zoomdata 2.4, you can use the visualization's variables object as it is returned by the API. Use this object as the value of the variables key in the parameter object passed to visualize(). Note that group, field, and metric names are the fieldIDs for columns in the data source. To identify available fieldIDs, see the data source's configuration.

Was this topic helpful?