D3 visualisation using Custom View

This article shows how to integrate a D3 visualisation into Omniscope report using Custom View API. 

D3 is a powerful visualisation library that could be used to complement native Omniscope visualisations. We will use a D3 Bar chart to showcase the integration process and demonstrate how to use the Custom View API. 

We have taken a JsFiddle example:

https://jsfiddle.net/matehu/w7h81xz2/

Step 1: Create a new project

Click on the plus button on the top right-hand corner of the Project list page.

Step 2: Getting data

We converted the sample data into CSV format and uploaded it to the Omniscope server - the same folder as our Project. You could do the same with your data.

In the Workflow app, add File block and choose the CSV format. This choice will automatically populate the default options for you.

Step 3: Connect File block to Report block.

The next step in our integration process is to connect the file source block to the Report block. Simply drag the arrow from File block to plug it into the Report block input.

Note: Report block in Omniscope can be connected to one or multiple data sources, to feed the visualisation/dashboard. 

Step 4: Open Report block

We are now ready to create the custom view. Open the Report block (you will see the default combination: Bar chart, table with data and filters). 

Click on the Add view button and pick the View Designer option to create /import/export your custom views.

When the View designer page opens create a new view and give it a name - in this case "My chart".

Step 5: Editing the Custom view.

Omniscope will create a basic custom view, which you can edit further to meet your needs. 

The original example has the following HTML, as per jsfiddle link:

Take line 8 and 9 and add to our own HTML in the appropriate place, as marked by the comment:

Take the contents of the body (line 12 to 17) and copy into index.html, just under the <main> tag. We are not using <main> tag in our example, so we will remove it.

Next, we need to add the CSS, as per image, so we will simply copy it into the head of the HTML.  You can upload your own resources for the view by simply dragging them onto the left-hand panel, where you see all your files.

Next the JavaScript code - copy it into the callback of Omniscope load event, as per screenshot.

Our next step is to replace the sample hard-coded in the file with the one from Omniscope. By default, Omniscope default template provides you with Measures / Splits which we will be using below to configure the bar chart. The default template is also enabled to automatically do queries on the server for you. This is very handy for a Custom view developer, as it means you don't have to write custom queries to get the data into your charts - the API will automatically use the callback function when anything in the application changes i.e. filtering/selection or other visualisation settings options.

Back to the example: open a new tab in your browser and open your project to add "My chart" in the Report from the Add view menu. The reason to open the project on another tab is that you can have a View designer open at the same time as the chart, so you can immediately monitor the effects of your changes. 

Right now, the view is still showing the sample data which is hard-coded, so we will replace it with the following lines (see the API documentation for more details regarding the different methods available to the developer).

// Retrieve the auto-query results, a 2d array ([row][column]):
var data = omniscope.view.context().result.data.records;

      
// Convert 2d array to array for chart - for simplicity.
data = data.map(function (arr) {
            
    return {
       language: arr[0],
       value: arr[1]
    }
});

Simply re-assign const sample to const sample = data 

const sample = data;

We also added the following below const SVG line to ensure that every time the view is rebuilt, it deletes the previous SVG created. 

// So on rebuild previous svg children are deleted.
d3.select("svg").selectAll("*").remove();

Next, open your Report and click on the "Present" button to allow you to select the newly-created custom view. In this example we'll click on the "My chart" view, and set the "Measures" and "Split" respectively to "Value" and "Language" 

Change Filters devices from the default search mode to choices by clicking on the small cog icon. 

Click on the "Present" mode again to view the results - we now have a Custom view written in D3 that responds to filtering done in Omniscope.

The possibilities are endless with Omniscope Custom View API... 

Useful links:

• You can find the above example here. 
• See here for more documentation on our Custom View API.
• An IOZ of the project is attached below - simply upload to your Omniscope installation to examine the file structure.