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

UPDATE: The Liquid Fill Gauge visual is now available to download from the Power BI Custom Visual Gallery!

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’s a circle gauge that represents a percentage value. All it does at the moment is display the value and nothing is configurable. I will continue to push new features as I finish them. It is based off of Curtis Bratton‘s Liquid Fill Gauge.

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/jonbgallant/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: http://blog.jongallant.com/2016/09/powerbi-custom-visual-dev.html

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.

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.

image_thumb3

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 so TypeScript can see it.

Go to this post for instructions on how to add d3 to your visual and then come back here: http://blog.jongallant.com/2016/11/pbiviz-12-d3-35-reference.html

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/jonbgallant/PowerBI-visuals-liquidFillGauge/master/liquidFillGauge/src/liquidFillGauge.js

=====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 about it for it to work with Power BI.

  • PowerBI puts all Custom Visuals in IFRAMEs so the clip-path needs to reference the absolute url of the page like so:
  • 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 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. You could define all of the methods and come up with a more sophisticated definition file, but I’ve found that the following works great.

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

Add liquidFillGauge files to tsconfig.json

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

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.

  • Notice the amd-dependency line at the top. This maps the TypeScript type definition to the visual.ts file so we can call loadLiquidFileGage that is in the liquidFillGauge file.
  • 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.
image_thumb11
5. You should then see your custom visual rendered.

image_thumb13

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