Building an advanced Visualization extension using Qlik’s Nebula.js & D3.js
The Extension API consists of methods and properties used to create custom visualization extensions.
Enter… Qlik Sense’s Open Source Solution — Nebula.js!
User scenario: An organization using Qlik Sense has a new requirement to develop a visual representation to understand high-dimensional mutlivariate dataset for their organization. Their dataset consists of numerical values, and they want to compare multiple features together to analyze the relationships between them. Based on these requirements, their Data Visualization Engineer presents to them the ‘Parallel Coordinate plot’.
So, what is a Parallel coordinate plot?
Parallel coordinate plots (PCP) have proved to be efficient in effectively visualizing high-dimensional multivariate datasets. In a parallel coordinate, each feature is represented as vertical bars and the values are plotted as a series of lines connected across each axis. Their advantage is that the vertical bars(features) can have their own scale, as each feature works off a different unit of measurement. PCP provides insights into specific hidden patterns in data like similarities, clusters, etc., and allows for more straightforward comparative analysis.
Based on the requirements, lets get started with building a QS extension using Nebula.js.
- Node.js(version 10 or newer)
- A terminal(for example, Git Bash on Windows or Terminal on Mac)
- An IDE of your choice, for example, VS Code.
- An existing web integration, or possibility to get one created in your tenant(this specifically applies to QS SaaS edition).
- A Qlik Sense app with data.
nebula.js CLI to import the necessary packages. The command scaffolds a project into the
/hello folder with the following structure:
index.js- Main entry point of this visualization
object-properties.js- Object properties stored in the app
data.js- Data configuration
/test- Integration tests
npx @nebula.js/cli create hello --picasso none
Step 2: Start the development server by running:
npm run start
The command starts a local development server and opens up http://localhost:8080 in your browser. The benefit of having the dev server with Nebula.js is that it provides an interactive way to test and edit your extension without the need to iteratively deploy in QS every time a new change is made.
Step 3: Configure the data structure.
Visualizations in QS are based on a hypercube definition(qHyperCubeDef ). Therefore, any new visual object we want to bring into the QS ecosystem needs to have the data structure defined. With Nebula.js, we have the object-properties.js file that allows defining the structure of our object.
We also need to set a data target in the
data.js file so we refer to the right hypercube definition(important to note in case you have multiple
Step 4: Developing the visualization extension using Nebula.js and D3.js.
QS Nebula.js specific code:
Now that we have everything ready, we start developing our extension with the custom visualization object using the index.js file from our project.
Note that Nebula.js and its primary package @nebula.js/stardust is built on the concept of custom hooks. This might sound familiar to people working with React.js. Hooks is a concept that emphasizes reusable, composable functions rather than classical object-oriented classes and inheritance. The primary hooks that we are dependent on for developing our extension object are described below:
The method that helps us in rendering our visualization object is the
component() function is executed every time something related to the object rendering changes, for example, theme, data model, data selections, component state, etc. This function can be compared to the paint() function in the Extension API.
To render our data, we first need to access the layout through the useLayout hook and then use it in combination with the useEffect hook. The hypercube’s qDataPages.qMatrix contains all the data(dimension and measures) used in the QS environment, and we will need to pass this data to our D3.js-based visualization.
To see the data values and understand the structure of the qHyperCube, it is always a good idea to do a console.log(layout). A snippet shows values specific to our use case. Every time a new dimension or measure is added to our extension object, qDataPages.qMatrix is updated with those values.
The required dimension values for our chart are then extracted from the hypercube using the qText property from qDataPages.qMatrix like below.
Our next step is to define the width and height of the visualization object, and capture its id. We will use this id to bind it to our element object from the
useLayout hook as shown below:
Finally, we make a call to the D3.js function from within the
D3.js specific code:
viz() function contains all of our D3.js code that allows us to draw a Parallel coordinate plot. First, we would need to append the SVG to the <div> that contains the id of our QS object, like below.
We then get all of the dimensions except Species to build our x and y axes.
To draw the lines for our Parallel coordinate plot, we will need to build the path function that would take a row from our qHyperCube and return the x and y coordinates of the line.
And finally, we bind everything with our SVG like below:
Step 5: Deploying the extension.
To build our project, we use the below command below to generates all QS readable files and puts them in a folder
/hello-ext . This folder can then be compressed(.zip) and uploaded to the Extension section of SaaS console to be used within the QS environment.
npm run sense
If you are just getting started with Nebula.js, https://qlik.dev is a great place to review the basics and drill-down on related functions.
This project’s source code is made available at: https://github.com/dipankarqlik/Nebula