Tutorial: Adding formatting options to the Circle Card visual

Članak
10/12/2021
5 min. za čitanje

When you create a visual, you can add options for customizing its properties. Some of the items that can be to customized formatted include:

Title
Background
Border
Shadow
Colors

In this tutorial, you learn how to:

Add formatting properties to your visual.
Package the visual
Import the custom visual to a Power BI Desktop or Service report

Prerequisite

This tutorial explains how to add common formatting properties to a visual. We'll use the Circle card visual as an example. We'll add the ability to change the color and thickness of the circle. If you don't have the Circle card project folder that you created in that tutorial, please redo the tutorial before continuing.

Adding formatting options

In PowerShell, Navigate to your circle card project folder and start the circle card visual. Your visual is now running while being hosted on your computer.
```
pbiviz start
```
In Power BI, select the Format page.

You should see a message that reads - Formatting options are unavailable for this visual.

If you see formatting options here but can't change them skip to Adding custom formatting options to customize them.
In Visual Studio Code, open the capabilities.json file.
Before the dataViewMappings array, add objects (after line 8).
```
"objects": {},
```
Save the capabilities.json file.
In Power BI, review the formatting options again.

Note

If you do not see the formatting options change then select Reload Custom Visual.
Set the Title option to Off. Notice that the visual no longer displays the measure name at the top-left corner.

Adding custom formatting options

Now let's add new group called color for configuring the color and width of the circle.

In PowerShell, enter Ctrl+C to stop the custom visual.

In Visual Studio Code, in the capabilities.json file, insert the following JSON fragment into the object labeled objects.

    {
        "circle": {
            "displayName": "Circle",
            "properties": {
                "circleColor": {
                    "displayName": "Color",
                    "description": "The fill color of the circle.",
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "circleThickness": {
                    "displayName": "Thickness",
                    "description": "The circle thickness.",
                    "type": {
                        "numeric": true
                    }
                }
            }
        }
    }

The JSON fragment describes a group called circle, which consists of two variables - circleColor and circleThickness.

Circle thickness code

Save the capabilities.json file.
In the Explorer pane, go to the src folder, and then select settings.ts. This file represents the settings for the starter visual.
In the settings.ts file, replace the two classes with the following code.
```
export class CircleSettings {
    public circleColor: string = "white";
    public circleThickness: number = 2;
}
export class VisualSettings extends DataViewObjectsParser {
    public circle: CircleSettings = new CircleSettings();
}
```
This module defines the two classes. The CircleSettings class defines two properties with names that match the objects defined in the capabilities.json file (circleColor and circleThickness) and also sets default values. The VisualSettings class inherits the DataViewObjectParser class and adds a property named circle, which matches the object defined in the capabilities.json file, and returns an instance of CircleSettings.
Save the settings.ts file.
Open the visual.ts file.

In the visual.ts file, import VisualSettings, VisualObjectInstanceEnumeration and EnumerateVisualObjectInstancesOptions:

import { VisualSettings } from "./settings";
import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;

and in the Visual class add the following property:

private visualSettings: VisualSettings;

This property stores a reference to the VisualSettings object, describing the visual settings.

Add visual class

In the Visual class, add the following method before the update method. This method is used to populate the formatting options.

public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
    const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
    return VisualSettings.enumerateObjectInstances(settings, options);
}

This method is used to populate the formatting options.

Visual settings object

In the update method, after the declaration of the radius variable, add the following code.

this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);

this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);

This code retrieves the format options. It adjusts any value passed into the circleThickness property, converting it to 0 if negative, or 10 if it's a value greater than 10.

Radius variable

In the circle element, modify the values passed to the fill style and stroke-width style as follows:
```
this.visualSettings.circle.circleColor
```
```
this.visualSettings.circle.circleThickness
```
Save the visual.ts file.
In PowerShell, start the visual.
```
pbiviz start
```
In Power BI, in the toolbar floating above the visual, select Toggle Auto Reload.
In the visual format options, expand Circle.

Modify the color and thickness option.

Modify the thickness option to a value less than zero, and a value higher than 10. Then notice the visual updates the value to a tolerable minimum or maximum.

Packaging the custom visual

Now that the visual is completed and ready to be used, it's time to package it. A packaged visual can be imported to Power BI reports or service to be used and enjoyed by others.

In this section you will learn how to

Enter property values for the custom visual project in the pbiviz.json file.
Update the icon (icon.png) file.
Finally, package the custom visual.

Edit the property values of the visual

In PowerShell, enter Ctrl+C to stop the custom visual.
Open the pbiviz.json file in Visual Studio Code.
In the visual object, modify the displayName property to Circle Card.

In the Visualizations pane, hovering over the icon reveals the display name.
For the description property, enter the following text.

Displays a formatted measure value inside a circle

Fill supportUrl and gitHubUrl for the visual.

Example:

{
    "supportUrl": "https://community.powerbi.com",
    "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
}

Enter your details in the author object.
Save the pbiviz.json file.

Update the icon

In the assets object of the pbiviz.json file, notice that the document defines a path to an icon. The icon is the image that appears in the Visualizations pane. It must be a PNG file, 20 pixels by 20 pixels.
In Windows Explorer, copy the icon.png file, and then paste it to replace the default file located in the assets folder.
In Visual Studio Code, in the Explorer pane, expand the assets folder, and then select the icon.png file.
Review the icon.

Package the visual

In Visual Studio Code, ensure that all files are saved.
To package the custom visual, in PowerShell, enter the following command.
```
pbiviz package
```

This command creates a pbiviz file in the dist/ directory of your visual project, and overwrites any previous pbiviz file that might exist.

Dist folder

The package contains everything required to import the custom visual into either the Power BI service or a Power BI Desktop report. You have now packaged the custom visual, and it's ready for use.

Importing the custom visual

Now you are ready to import the Circle Card custom visual so you can use it in your reports. Follow the directions in import a visual file from your local computer into Power-BI to import the circleCard.pbiviz file from the dist folder into your Power BI report.