Leveraging the power of Qlik Sense(SaaS) Extension API to design a new visualization chart
Qlik Sense API’s have been a powerful set of tools for the developer community to build out-of-the-box capabilities and to integrate them seamlessly within the Qlik’s ecosystem. These APIs enable a developer to communicate with the Qlik platform using technology frameworks such as JavaScript, .NET to build custom Visualizations, widgets, or Mashups(integrating Qlik objects with web portal).
Consider a scenario where a customer already uses the benefits of Qlik Sense native charts and objects and their new requirement is to present some data in a chart that perfectly syncs with their use case but is not available within Qlik Sense by default. This is where Qlik Extension API comes to the rescue!
The Extension API provides various methods and properties that can be used by developers to create custom visualization extensions. In short, it gives you a way to develop and reuse visualizations in some widely used JavaScript libraries such as D3.js (Ref: https://d3js.org) and allows them to be brought into the Qlik Sense environment. Qlik’s developer portal provides precise documentation on the usability of this API (Ref: https://qlik.dev/apis/javascript/extensions)
The image above highlights the general workflow for Extension API from both Qlik Sense Customer & Developer perspective. Qlik Sense API’s in general have been an exciting opportunity for Web developers to showcase their already existing skills primarily with HTML, JavaScript & CSS. And with the Extension API, they have the power to build their interactive visualization charts and style them as per the needs.
In this blog, we are going to make use of the Qlik Sense Extension API and D3.js to develop a new chart ‘Scatter-Pie plot’ that is not natively available within Qlik Sense. D3.js is an SVG based visualization library that tightly integrates with data sources to produce dynamic, scalable visual metaphors in a web browser. The focus of this work would primarily be around creating an Extension object and not D3.js programming. Also, note that this blog is focused towards the SaaS edition of Qlik Sense.
Now that we have a basic idea of Qlik Sense Extension API and the D3.js based visualization, lets deep dive into the steps.
Step 1: Resources gathering
Like any other projects, our first step is to get a dataset for performing analytical tasks with Qlik Sense. For this work, I have used a sample ‘Superstore’ dataset that contains information of sales, profit, sales per category(furniture, office materials, technology) per state for ~10 states in the US.
We will also need a D3.js code and its associated library reference (Ref: https://github.com/d3/d3/releases/)for creating our Extension object. I have written a D3.js code that aims to build a Scatter-Pie chart and our main motive would be to use this chart within the Qlik Sense environment.
Step 2 : Load the data in Qlik Sense
We then load our dataset to the Qlik SaaS environment and create a few charts for our analysis.
Now, before we move ahead, let’s recall our Problem statement again!
Problem statement: Our use-case is that we need a new chart to be able to plot Sales & Profit correlations but users would also want to see the category wise sales made inside the same chart.
Step 3: Creating our Qlik Sense Extension object
Keeping in mind the problem statement, we understand that a Scatter-Pie chart i.e. pie charts representing individual categories instead of a traditional bubble might help us in our task. Now that we have the data loaded in Qlik Sense, we will start creating our Extension object.
The main components of a Qlik Extension file are described below:
We start by creating our piescat.qext file like below:
Next, we will start building our Extension’s main JavaScript code, piescat.js.
For the simplicity of understanding and in order to have a distinction , we will segregate the code into 2 parts: Qlik Sense API code and D3.js code.
Qlik Sense API specific code:
First, we need to define our dependency files (.css & d3 library- d3.min.js) inside the define( ) statement. This way, we get to load the files that our extension will rely upon to create the new visualization. A snippet of the code is given below:
define(["jquery", "text!./piescat.css", "./d3.min"], function ($, cssContent) {Our next step is to define the Extension object along with its properties to be used in the Qlik Sense environment. This is where we can programmatically create the object properties and control the behavior of our extension using Qlik’s API. In our code piescat.js, the return statement defines these properties like below:
return {
initialProperties: {
version: 1.0,
qHyperCubeDef: {
qDimensions: [],
qMeasures: [],
qInitialDataFetch: [
{
qWidth: 4,
qHeight: 1000,
},
],
},
},
definition: {
type: "items",
component: "accordion",
items: {
dimensions: {
uses: "dimensions",
min: 1,
max: 2,
},
measures: {
uses: "measures",
min: 2,
max: 2,
},
}We define the initial properties (qWidth:4, qHeight:1000) for retrieving our data and also specify the minimum and the maximum number of dimensions & measures to be used.
The next step is building our paint( ) function that basically controls the rendering of the visualization. This function is very crucial and is called every time the visualization is rendered for common operations in Qlik Sense like filtering, apply selections, resizing, etc.
paint($element, layout) function takes 2 parameters as arguments. The $element is a jQuery wrapper that contains the HTML element to render our visualization. And the layout parameter provides information about the data and properties of an object.
Inside the paint( ) function, we retrieve the necessary data and perform data processing to create variables to be passed on to our D3.js code for binding the Qlik Sense data to the D3.js SVG. Here’s a snippet:
var qMatrix = layout.qHyperCube.qDataPages[0].qMatrix; //an array to hold the measure labels:
var measureLabels = layout.qHyperCube.qMeasureInfo.map(function (d) {
return d.qFallbackTitle;
});
//an array that invokes each row of qMatrix from layout:
var data = qMatrix.map(function (d) {
return {
Dim1: d[0].qText, //pie
Dim2: d[1].qText, //state
Dim3: d[2].qText, //Sales
Dim4: d[3].qText, //Profit
};
});
The final step in the Qlik Sense API specific code is to make a call to the visualization function holding our D3.js code like below:
viz(data, measureLabels, width, height, id); // call our D3.js codeD3.js code
The viz( ) function holds the D3.js code that we use to build our new visualization: Scatter-Pie plot. Like mentioned before, in this work our focus would not be on developing the D3 code but applying it. So, copy and paste the D3.js code inside the viz( ) function.
Please note that we will need to pass on the data(dimensions and measures) retrieved in the paint( ) function using Qlik Sense API so they can be bound with the D3 code. A snippet of the code that uses the data(highlighted in bold) is below:
svg
.append("g")
.selectAll("dot")
.data(data)
.enter()
.append("g")
.attr("transform", function (d) {
return "translate(" + x(d.Dim3) + "," + y(d.Dim4) + ")";
})
.selectAll("whatever")
.data(function (d) {
return pie(d3.entries(d.Dim1.split(",")));
})Step 4: Deploying the Extension
The final step is to make the developed Extension object accessible to Qlik Sense SaaS users. To do that, we first compress all our files (CSS, JS, D3 library, QEXT) as zipping and go to the Qlik Management Console. To add our custom object, we click on the Extension button on the right-hand side as shown below:
The Add button allows us to upload our compressed extension file.
Once the extension is uploaded successfully, we can go to our Qlik Sense app (previously created) and try using the extension.
Step 5: Using the extension
We open the Qlik Sense sheet and traverse to Custom Objects section from the right hand navigation. This allows us to see our deployed extension object as highlighted below:
We should now be able to use the extension as a new chart for the Business requirement by dragging & dropping on the existing sheet.
The new Visualization is shown below:
The benefit of this visualization is that we can see the individual sales made per category while we project the Sales & Profit correlations in the X & Y-axis. The bubble size helps us understand the Sales made in each state and state information is attached to each Pie for clarity.
DASHBOARD IN ACTION:
Now that we have an idea of how to use Qlik Sense Extension API to create custom objects, we can try out a variety of open-sourced solutions available in the Qlik Garden — https://developer.qlik.com/garden.
The Project’s source code is available here : https://github.com/dipankarqlik/QlikAPI
