How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 1 - Dev Env Setup, Reference and Testing

The purpose of this post is to show you how to take an existing open source d3 visual and create a Power BI Custom Visual from it.

I’ve been digging into the new Power BI Custom Visual SDK and just created my first visual called Liquid Fill Gauge. It is based off of Curtis Bratton’s Liquid Fill Gauge. Here’s how I did it…

Custom Visual Series

This is Part 1 of the series, here are the other posts:

2. How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 2 - Capabilities, dataRoles and dataViewMappings

3. How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 3 - Custom Format Properties

You can download the visual and use within your reports here: https://github.com/jongio/PowerBI-visuals-liquidFillGauge/releases/

I walk through each step below – feel free to skim through it, use it as a reference or follow along step-by-step.

Setup Power BI Custom Visual Dev Environment

1. Follow the instructions here to get your dev env setup: Power BI Documentation: Use developer tools to create custom visuals

Clone Repo

You can complete this exercise without cloning the repo, but if you want to get all the code and easily copy and paste, then you’ll want to clone.

Part 1 Code:

Here’s what your code will look like at the end of this blog post:
https://github.com/jongio/PowerBI-visuals-liquidFillGauge-Part1

git clone https://github.com/jongio/PowerBI-visuals-liquidFillGauge-Part1.git

Final Code:

Here’s the final liquidFillGauge code:
https://github.com/jongio/PowerBI-visuals-liquidFillGauge

git clone https://github.com/jongio/PowerBI-visuals-liquidFillGauge.git

Open Code

I use VS Code, but feel free to use any editor.

Create Custom Visual

This uses the new SDK to create a custom visual template.

This is what the dir structure looks like in VS Code.

Reference d3 Typings

You create Custom Visuals using TypeScript and d3, but d3 isn’t referenced by default in the new Custom Visual SDK. Here’s How to get it installed and referenced to make it visible to TypeScript.

Go to this post for instructions on how to add d3 to your visual and then come back here: How to Add [email protected] Reference to a Power BI Custom Visual (SDK v1.2)

Add liquidFillGauge.js File

1. Create a file in the “src” folder called “liquidFillGauge.js”.
2. Copy the code from the following file into it. If you cloned the repo, you will have this file locally as well.
https://raw.githubusercontent.com/jongio/PowerBI-visuals-liquidFillGauge-Part1/master/liquidFillGauge/src/liquidFillGauge.js

Notes

The following is informational only, you do not need to make these changes.

The original liquidFillGauge was pushed to GitHub as a stand alone d3 visual. I only had to change a the following two things for it to work with Power BI.

Clip-Path

PowerBI puts all Custom Visuals in IFRAMEs, so the clip-path needs to reference the absolute url of the page like so:

d3 Instance

Once I deployed my visual to PowerBI.com I ran into another IFRAME issue that required me to pass in the d3 selection instance, versus doing the d3.select inside the visual. Instead of passing in elementId, I pass in a reference to the svg element

Add liquidFillGauge.js to pbiviz.json

This will tell pbiviz to include the .js file in your project.

1. Open pbiviz.json and add a reference to liquidFillGauge.js to “externalJS”

Add TypeScript Definition File

The premise of this exercise is to take an existing d3 visual and easily turn it into a custom visual without having to rewrite the entire thing in TypeScript. What I would like to do is clone the existing visual and reference it from my visual.ts file. In order to do that, I need to make the visual file visible in TypeScript by creating a TypeScript definition file and including it in my project.

1. Create a new file in the “src” folder called “liquidFillGauge.d.ts” and add the following code to it.

Add liquidFillGauge.d.ts files to tsconfig.json

1. Open tsconfig.json and add references to the liquidFillGauge.d.ts.

This will tell pbiviz to include the TypeScript definition file in your project.

Add liquidFillGauge to visual.ts

The final step is to add code to the visual.ts file that will call the liquidFillGauge methods and create the visual.

1. Open visual.ts and copy the following code into it.

I added another local variable to hold a reference to the gauge and then either call loadLiquidFillGauge for the first load or call this.gauge.update for subsequent calls.

Test on PowerBI.com

1. Start your local server

2. Go to http://app.powerbi.com
3. Create a report that uses your visual
4. Map a data value to the “Measure Data” field. I’m using the Month column in the Dates table in the Customer Profitability Sample dataset.

Make sure you select “Count of Month” and it is assigned to “Measure Data”, not “Category Data”

5. You should then see your custom visual rendered.

If you do not see it, then compare your code to the code in this GitHub repo and fix anything that is different.

–
Hope this gets you on your way to creating your own visuals.
Jon