In this tutorial, you develop a Power BI visual named circle card that displays a formatted measure value inside a circle. The circle card visual supports customization of fill color and outline thickness.
In this tutorial, you learn how to:
Before you start developing your Power BI visual, verify that you have everything listed in this section.
A Power BI Pro or Premium Per User (PPU) account. If you don't have one, sign up for a free trial.
Visual Studio Code (VS Code). VS Code is an ideal Integrated Development Environment (IDE) for developing Javascript and Typescript applications.
Windows PowerShell version 4 or later (for Windows). Or Terminal (for Mac).
An environment ready for developing a Power BI visual. Set up your environment for developing a Power BI visual.
This tutorial uses the US Sales Analysis report. You can download this report and upload it to Power BI service, or use your own report. If you need more information about Power BI service, and uploading files, refer to the Get started creating in the Power BI service tutorial.
In this section, you create a project for the circle card visual.
Open a new terminal in VS Code and navigate to the folder you want to create your project in.
Enter the following command in the PowerShell terminal:
Open the CircleCard folder in the VS Code explorer. (File > Open Folder).
For a detailed explanation of the function of each of these files, see Power BI visual project structure.
Check the terminal window and confirm that you're in the circleCard directory. Install the Power BI visual tools dependencies.
Start the circle card visual.
Your visual is now running while being hosted on your computer.
To test the visual in Power BI service, we'll use the US Sales Analysis report. You can download this report and upload it to Power BI service.
You can also use your own report to test the visual.
Sign in to PowerBI.com and open the US Sales Analysis report.
Select Edit.
Create a new page for testing, by clicking on the New page button at the bottom of the Power BI service interface.
From the Visualizations pane, select the Developer Visual.
This visual represents the custom visual that you're running on your computer. It's only available when the custom visual debugging setting is enabled.
Verify that a visual was added to the report canvas.
This is a simple visual that displays the number of times its update method has been called. At this stage, the visual does not retrieve any data.
While the new visual is selected, go to the Data pane, expand Sales, and select Quantity.
To test how the visual is responding, resize it and notice that the Update count value increments every time you resize the visual.
In this section you learn how to turn your visual into a circle, and make it display text.
Set up the visual.ts file.
In VS Code, in the Explorer pane, expand the src folder, and select the file visual.ts.
Remove all the code under the MIT License comment.
import the libraries and modules needed, and define the type selection for the d3 library:
Notice that among the items you imported are:
- IVisualHost - A collection of properties and services used to interact with the visual host (Power BI).
- D3 library - Javascript library for creating data driven documents.
Below the imports, create an empty visual class. The visual class implements the IVisual interface where all visuals begin:
For information about what goes into the visual class, see Visual API. In the next three steps, we define this class.
Add class-level private methods at the beginning of the visual class:
Notice that some of these private methods use the Selection type.
Define the circle and text elements in the constructor method. This method is called when the visual is instantiated. The D3 Scalable Vector Graphics (SVG) enable creating three shapes: a circle, and two text elements:
Define the width and height in the update method. This method is called every time there's a change in the data or host environment, such as a new value or resizing.
Save the visual.ts file.
Verify that the final code in the visual.ts file looks like this:
The circle card visual is a simple visual that doesn't create any objects in the Format pane. Therefore, you can safely remove the objects section of the file.
Open your project in VS Code (File > Open Folder).
Select the capabilities.json file.
Remove the entire objects array.
Don't leave any blank lines between dataRoles and dataViewMappings.Save the capabilities.json file.
Stop the visual from running and restart it.
In the PowerShell window where you started the visual, enter Ctrl+C. If prompted to terminate the batch job, enter Y and then Enter.
In PowerShell, start the visual again.
Verify that the visual displays the newly added elements.
In Power BI service, open the Power BI US Sales Analysis report. If you're using a different report to develop the circle card visual, navigate to that report.
Drag a value into the Measure box and make sure that the visual is shaped as a circle.
If the visual isn't displaying anything, from the Fields pane, drag the Quantity field into the developer visual.
Resize the visual.
Notice that the circle and text scale to fit the dimensions of the visual. The update method is called when you resize the visual, and as a result the visual elements get rescaled.
Use this setting to ensure that the visual is automatically reloaded each time you save project changes.
Navigate to the Power BI US Sales Analysis report (or to the project that has your circle card visual).
Select the circle card visual.
In the floating toolbar, select Toggle Auto Reload.
In this section, you define data roles and data view mappings. You also modify the visual to display the name of the value it's displaying.
Modify the capabilities.json file to define the data role, objects, and data view mappings.
Define the data role
Define the dataRoles array with a single data role of the type measure. This data role is called measure, and is displayed as Measure. It allows passing either a measure field, or a summed up field.
Open the capabilities.json file in VS Code.
Remove all the content inside the dataRoles array.
Insert the following code to the dataRoles array.
Save the capabilities.json file.
Define the data view mapping
Define a field called measure in the dataViewMappings array. This field can be passed to the data role.
Open the capabilities.json file in VS Code.
Remove all the content inside the dataViewMappings array.
Insert the following code to the dataViewMappings array.
Save the capabilities.json file.
Confirm that your capabilities.json file looks like this:
Verify that the circle card visual displays the measure field, and review the changes you made using the Show Dataview option.
In Power BI service, open the Power BI US Sales Analysis report. If you're using a different report to develop the circle card visual, navigate to that report.
Notice that the circle card visual can now be configured with a field titled Measure. You can drag and drop elements from the Data pane into the Measure field.
In the floating toolbar, select Show Dataview.
Select the three dots to expand the display, and select single to view the value.
Expand metadata, then the columns array, and review the format and displayName values.
To toggle back to the visual, in the toolbar floating above the visual, select Show Dataview.
So far, the visual renders, but doesn't display any data. In this section, you make changes to the visual.ts file, so that the circle card visual can consume data.
Open the visual.ts file in VS Code.
In the update method:
Add the following statement as the first statement. The statement assigns dataView to a variable for easy access, and declares the variable to reference the dataView object.
Replace .text("Value") with this line of code:
Replace .text("Label") with this line of code:
Save the visual.ts file.
Review the visual in the Power BI service.
The visual now displays the name and value of the selected data field.