Zoomdata Version

Configuring Charts Via Visualization Variables


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 (v2.2 GA) .

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 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:

To identify chart settings using the client application:

  1. Log in to the Zoomdata client application using an administrator account.
  2. Select Settings ( ).
  3. Select Chart Studio .
  4. If your chart is a custom chart, select Edit from its row in the Manage Custom Charts list. Otherwise, select it from Create a New Chart From list of Zoomdata-provided templates, providing a unique name for the new chart, and select Accept .
    The Chart Studio opens.
  5. Select Manage .
  6. Select Variables . The Manage Variables dialog opens.

  7. Look at each entry in the Query and Constants tabs of the dialog.

    Each entry defines a chart setting, which is identified by the string in the first field.

    In the example above, the chart's constant settings are Chart Description and Chart Name . Variable settings are listed under the Query tab.

You can now continue to encode the settings .

To identify chart settings using a REST API call:

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 .

When using a REST API call to identify a chart's settings, it is easiest to find or create an instance of the chart in your data source. After you have created or found an instance of the chart in your data source, you can examine the data source's configuration to find the details of the chart's settings. You can copy and modify these for your embedding code.

Make a GET call to

https:// yourserver / path /service/sources/ 123456789

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
  • 123456789 is replaced with the sourceID for the source that holds the visualization settings you wish to identify.
    For steps to identify the sourceID of a chart's source, see Identifying the sourceID of a Chart's Source .

You can use curl, for example:

curl --user zoomdata:zoomdata -X GET https://developer.zoomdata.com/zoomdata/service/sources/56f16b6ae4b0de3f2348a234 -H "Content-Type: application/vnd.zoomdata.v1+json;"

The response body contains a JSON object that contains an object for each chart (visualization) in the source, like the following.

The following example of a visualization definition object is not guaranteed to be maintained in Zoomdata versions after version 2.2.x. Subsequent versions of Zoomdata will be accompanied with documentation new procedures and object structures and highlighting significant changes. For more information about using internal APIs, see Cautionary Note About Internal APIs .
id: "56f16b6be4b0de3f2348a24a",
visId: "56f16b6ae4b0de3f2348a234",
name: "Pie",
type: "PIE",
enabled: true,
source: {
variables: { Chart Name: "", Size: "count", Chart Description: "", Group By: "{"name":"usergender","limit":20,"sort":{"name":"count","dir":"desc"}}" },
sourceId: "56f16b6ae4b0de3f2348a245",
textSearchEnabled: false,
playbackMode: true,
live: true,
sparkIt: false },
owner: "SOURCE",
lastModified: 1465786050319

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:

element: vizLocation,
config: queryConfig,
source: {name: 'Real Time Sales'},
visualization: 'Packed Bubbles',
variables: {
'Bubble Size': 'price:avg',
'Chart Name': '',
'Bubble Color': 'count::{"autoShowColorLegend":true}',
'Chart Description': '',
'Group By': '{"name":"usergender", "limit":20, "sort":{"name":"count", "dir":"desc"}}'

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

To encode variables identified by referring to the UI:

  1. In a text editor, create a JSON object that includes a key for each chart query and each chart constant. The name of the key must match exactly the name of the chart setting.

    Thus, the chart variable names shown above are Buying Demographic and Selling Demographic . They must be encoded as the keys "Buying Demographic" and "Selling Demographic" with quotation marks, as shown below.
    "Buying Demographic":
    "Selling Demographic":
  2. For each key in the JSON object, provide a value, also enclosed in quotation marks. Each type of chart setting requires a different type of value. For example, Ungrouped query variables require the fieldID of the data source column that provides the values for that chart variable:
    "Buyer State": "transactionState"
    Various types of chart variables require varying information. Some chart variables require objects for their value. In these cases, the objects must be stringified and passed to their key as a single string value.
  3. Add a comma after each key:value pair except for the last pair.
  4. When you call client.visualize() use this string as the value of the variables key in the parameter object passed to visualize() .

To encode variables identified by using the REST API call:

  1. Copy the value of the variables: key from the object returned by your REST API call.
  2. Enclose each chart setting (chart variable) name in double quotes as shown in the example below.
    "Chart Name": "",
    "Size": "count",
    "Chart Description": "",
    "Group By": "{"name":"usergender","limit":20,"sort":{"name":"count","dir":"desc"}}"
  3. Replace the double quotation marks (") with single quotation marks (') as necessary to render valid strings from objects that are used as values. For example:
    "Chart Name": "",
    "Size": "count",
    "Chart Description": "",
    "Group By": '{"name":"usergender","limit":20,"sort":{"name":"count","dir":"desc"}}'
  4. For each key enclosed in the string, replace its value with the appropriate value for the chart settings that you want to use when embedding your visualization.
    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.
  5. When you call client.visualize() use this string as the value of the variables key in the parameter object passed to visualize() .