Zoomdata Version

Embedding a Visualization (Chart) in a Web App

Overview

The Zoomdata Application Framework provides a client library for embedding visualization into a web application without using an iframe. To assist you in this task, Zoomdata provides:

  • This topic, which includes annotated steps for embedding a visualization in your own web app
  • A simple example of an embedded visualization with annotated code, discussed in this topic, and available for download at Zoomdata's Github repo.
  • Before beginning, please look at What Can You Embed? to see which parts of charts get embedded when you embed one in a custom application.

Steps for embedding a Chart in Your Own Web App

These stages for embedding a chart in a web application will guide your work.

  1. Prepare your HTML file for the chart.
  2. Organize application and security parameters.
  3. Add Code to Your Web App to Display the Visualization.

Preparing Your HTML File for the Chart

To prepare your own HTML file for the chart:

  1. Link and include various dependencies. The main dependency is the Zoomdata JavaScript client library. The library is located in your Zoomdata installation at the URL /zoomdata/sdk/2.0/zoomdata-client.js . The minified version is available at /zoomdata/sdk/2.0/zoomdata-client.min.js . The application framework also depends on jQuery. Zoomdata recommends that you link jQuery v1.8 or later.
  2. In your HTML file, create a JavaScript <script> element with an anonymous function. Your embedding code will be placed inside the element.
    <script type="text/javascript"></script>
    
  3. Add a <div> or other element to your HTML, assigning it a unique id attribute. The visualization will be attached to this element.
    <div id="visualization" class="widgetContent medium" style="width:40%; height:40%; float:left; top:20%"></div>
    
    Note that in Zoomdata v2.2 and 2.3, certain visualizations require the attribute class="widgetContent medium" to be explicitly added to the element to which the visualization is attached. The best practice is to use the attribute for all visualizations when using v2.2 or v2.3.

Organizing Application and Security Parameters

Connecting the web page to your Zoomdata server requires supplying the Zoomdata server with application and security parameters in the form of JavaScript objects. These two objects are themselves bundled together as a single object to be passed to the createClient() method. For example:

ZoomdataSDK.createClient({
   credentials: credentialConfig,
   application: applicationConfig
})

For more information about the application configuration object, see Application Configuration Object.

For more information about the security configuration object, see Security Configuration Object.

Adding Code to Your Web App to Display the Visualization

The Zoomdata JavaScript client library includes an application-level object called ZoomdataSDK. The ZoomdataSDK object is used to create a client object. The client object is used to render visualizations. In its simplest form, the code for creating a client and embedding a visualization typically looks as follows.

ZoomdataSDK.createClient({ 
	credentials: credentialConfig, 
	application: applicationConfig 
	}) 
	.then(function(client) { 
		window.client = client; 
		return(client); 
	}) 
	.then(function(client) { 
		client.visualize({ 
			element: vizLocation, 
			config: queryConfig, 
			source: {name: 'Real Time Sales'}, 
			visualization: 'Packed Bubbles', 
			variables: { 
				'Bubble Size': 'count', 
				'Bubble Color': 'usersentiment:avg' } 
		}) 
		.then(function(result) {
			window.viz = result;
		});
	});

The basic code can be expanded to add event and error handling as well as other functionality.

To embed a visualization:

  1. Create a Zoomdata client instance using createClient().
    ZoomdataSDK.createClient({ 
    	credentials: credentialConfig, 
    	application: applicationConfig 
    	}) 
    	.then(function(client) { 
    		window.client = client; 
    		return(client); 
    	});
    
    You will commonly need to refer to a client later in your code, so assigning it to a variable is important. In the example above, after the client is created it is returned by createClient() and supplied to the chained then() function. It is then added to window as a member object. Adding client to window is not necessary, but doing so can make handling easier.
  2. Assign the visualization’s container HTML element to a JavaScript variable.
    var vizLocation = document.getElementById('visualization');
    
  3. Prepare a data query to pass to the client’s visualize() member function. Alternately, you can pass a query configuration object. An example of a simple query configuration object follows.
    var queryConfig = {
    	tz: 'UTC'
    };
    
    For information about possible parameters for a query configuration object, see Query Configuration Object.
  4. Render the visualization using the client object’s visualize() member function.
    window.client.visualize({ 
    	element: vizLocation,
    	interactive: true, 
    	config: queryConfig, 
    	source: {name: 'Real Time Sales'}, 
    	visualization: 'Packed Bubbles', 
    	variables: { 
    		'Bubble Size': 'count', 
    		'Bubble Color': 'usersentiment:avg'
    	} 
    });
    
    In the example above:
    • The object passed to visualize() includes the config and source keys it needs to create a query configuration object. Instead of passing those keys, you can use a query key to pass a query. You must supply visualize() with either a query object or with the configuration parameters it needs to create a query. Either way, the client needs a query object to render a visualization.
    • interactive is an optional boolean value that is used to control the interactivity of charts. Some charts offered by Zoomdata or developed by your own engineers may not take this value into account. Each chart is different.
    • The visualization and variables keys specify the visualization to be rendered and assign its variables, such as bar color or bubble size. The particular visualization in the example does not use any variables. For information about translating Zoomdata variables into a JSON object, see Translating Visualization Variables into a JSON Object.
  5. The visualize() call is typically chained to the createClient() call using a then() function to prevent the browser from attempting to render the visualization until after the client has finished initiating.
  6. Typically done(), or catch() functions are chained to the call to add more robust handling. At a minimum, the visualization should be assigned to a variable so that it can be accessed later.