Building an advanced Visualization extension using Qlik’s Nebula.js & D3.js
By: Dipankar Mazumdar
Tags: Visual Analytics, D3js, Qlik Sense

Based on the requirements, lets get started with building a QS extension using Nebula.js.

Prerequisites:

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.

Step1: Use nebula.js CLI to import the necessary packages. The command scaffolds a project into the /hello folder with the following structure:

/src

index.js - Main entry point of this visualization

- Main entry point of this visualization object-properties.js - Object properties stored in the app

- Object properties stored in the app data.js - Data configuration

- Data configuration /test - Integration tests

- Integration tests package.json

Command: npx @nebula.js/cli create hello --picasso none

Step 2: Start the development server by running:

cd hello

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 qHyperCubeDef objects).

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:

Custom Hooks from Nebula’s stardust package

The method that helps us in rendering our visualization object is the component() function. 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[0].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[0].qMatrix is updated with those values.

qHyperCube shows values of the dimensions and the structure to access them.

The required dimension values for our chart are then extracted from the hypercube using the qText property from qDataPages[0].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 useEffect hook.

D3.js specific code:

The 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

Dashboard:

PCP plot within Qlik Sense dashboard

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