MSDN Tutorials

Introduction to Custom Visuals

Welcome to the module on Power BI Custom Visuals! In this section, you'll learn how to extend the visualization capabilities of Power BI by creating your own interactive and data-rich visuals.

Custom visuals allow you to:

• Incorporate unique chart types not available in the standard Power BI library.
• Integrate with external libraries and frameworks (like D3.js, Plotly.js).
• Create highly interactive and engaging data experiences.
• Tailor visuals to specific business needs and branding requirements.

Development Environment Setup

Before you start coding, you need to set up your development environment. This involves installing Node.js, npm, and the Power BI Visuals Tools.

npm install -g powerbi-visuals-tools

pbiviz --version

Visual Basics: Structure and API

A Power BI custom visual is essentially a web application packaged in a specific format. It's built using TypeScript/JavaScript, HTML, and CSS.

The core components of a custom visual project are:

• src/visual.ts: Contains the main TypeScript class for your visual. This is where you'll implement the logic for rendering and updating the visual.
• src/settings.ts: Defines the formatting options available for your visual in the Power BI formatting pane.
• capabilities.json: A configuration file that describes the visual's capabilities, such as data roles, data view mappings, and formatting options.
• style/visual.less: Contains the SCSS/LESS or CSS for styling your visual.
• tsconfig.json: TypeScript compiler configuration.
• package.json: Project metadata and dependencies.

The main visual class in src/visual.ts typically implements an interface like IVisual, which has methods such as:

• constructor(options: VisualConstructorOptions): Called once when the visual is initialized.
• update(options: VisualUpdateOptions): Called whenever data or settings change. This is where you'll re-render your visual.

You can create a new visual project using the command:

pbiviz new MyCustomVisual

Then navigate into the project directory and start the development server:

cd MyCustomVisual
pbiviz start

This command will compile your visual and start a local server. You can then import the visual into Power BI Desktop for testing.

Data Binding and Formatting

The update method receives VisualUpdateOptions, which contains the data bound to your visual. The data is structured according to the dataRoles and dataViewMappings defined in your capabilities.json file.

You'll typically access the data through options.dataViews. For example, to get categorical data:

const dataView = options.dataViews[0];
if (dataView && dataView.categorical) {
    const categories = dataView.categorical.categories[0].values;
    const values = dataView.categorical.values[0].values;
    // Process categories and values to render your visual
}

Formatting options defined in settings.ts and exposed via capabilities.json allow users to customize the appearance of your visual through the Power BI formatting pane. These settings are passed to your visual via the options.dataViews[0].metadata.objects property.

Interactivity and Events

Custom visuals can respond to user interactions, such as clicks, hovers, and selections. They can also interact with other visuals on the report page.

To handle selections and propagate them to other visuals, you use the selectionManager service provided by the Power BI visuals SDK:

class Visual implements IVisual {
    private selectionManager: SelectionManager;

    constructor(options: VisualConstructorOptions) {
        this.selectionManager = options.host.createSelectionManager();
        // ... other initialization
    }

    public update(options: VisualUpdateOptions) {
        // ... rendering logic

        // Example: Attaching a click event to an SVG element
        d3.select(element).selectAll('.bar').on('click', (event, d) => {
            const selectionId = this.visualHost.createSelectionIdBuilder()
                                .withCategory(d.category.identity, d.category.index)
                                .createSelectionId();
            this.selectionManager.select(selectionId);
        });
    }
}

Capabilities.json Explained

The capabilities.json file is crucial for defining how your visual interacts with Power BI data and users.

Key sections include:

• dataRoles: Defines the different ways data can be bound to your visual (e.g., Category, Measure, Tooltip).
• dataViewMappings: Specifies how the bound data should be structured and presented to your visual. This can be categorical, table, or matrix format.
• objects: Describes the formatting options available in the Power BI formatting pane (e.g., colors, fonts, sizes).
• visualClassName: The name of the class in your TypeScript file that implements IVisual.

Example snippet:

{
    "dataRoles": [
        {
            "displayName": "Category",
            "name": "category",
            "kind": "Grouping"
        },
        {
            "displayName": "Value",
            "name": "value",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "categorical": {
                "categories": {
                    "for": { "dataRole": "category" }
                },
                "values": {
                    "group": {
                        "by": "category",
                        "select": [
                            { "dataRole": "value", "displayName": "Value" }
                        ]
                    }
                }
            }
        }
    ],
    "objects": {
        "categoryStyle": {
            "displayName": "Category Style",
            "properties": {
                "color": {
                    "type": { "enum": ["red", "green", "blue"] }
                }
            }
        }
    }
}

Packaging and Distribution

Once your visual is ready, you need to package it into a .pbiviz file for distribution and use in Power BI reports.

Run the following command in your visual's project directory:

pbiviz package

This command creates a dist/ folder containing your visual package. You can then import this .pbiviz file into Power BI Desktop or publish it to the Power BI service for wider use.

Best Practices

• Performance: Optimize your rendering logic, especially for large datasets. Use efficient DOM manipulation and consider libraries like D3.js.
• Accessibility: Ensure your visual is accessible to users with disabilities. Provide meaningful alt text, keyboard navigation, and sufficient color contrast.
• Interactivity: Make your visual responsive to user actions and support seamless integration with the Power BI report canvas.
• Error Handling: Implement robust error handling to gracefully manage unexpected data or situations.
• Code Maintainability: Write clean, well-documented code. Follow TypeScript best practices and leverage the SDK's features effectively.