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.
This is Part 1 of the series, here are the other posts:
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.
1. Follow the instructions here to get your dev env setup: Power BI Documentation: Use developer tools to create custom visuals
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.
Here’s what your code will look like at the end of this blog post:
git clone https://github.com/jongio/PowerBI-visuals-liquidFillGauge-Part1.git
Here’s the final liquidFillGauge code:
git clone https://github.com/jongio/PowerBI-visuals-liquidFillGauge.git
I use VS Code, but feel free to use any editor.
This uses the new SDK to create a custom visual template.
This is what the dir structure looks like in VS Code.
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)
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.
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.
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
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”
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.
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.
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.