Microsoft contributed the Power BI visualization framework and its complete library of visuals to the open source community. Available on GitHub
(https://github.com/Microsoft/PowerBI-Visuals), this project has two main goals. First, it teaches developers how to build and test custom visuals. Anyone can clone the GitHub project and explore the code in Visual Studio. You can learn from the existing code how to create your own visuals. You can use a “playground” application to test Power BI and custom visuals. Second, it allows the community to extend the Microsoft-provided visualizations. Microsoft hopes that the community can add useful features to existing visualizations by submitting GitHub pull requests (a pull request is a way of submitting contributions to an open source project).
Getting started with the visualization framework
The visualization framework includes the following components:
The source code of all the visuals used in Power BI. Microsoft also published the source code of all custom visuals that Microsoft contributed to the Power BI visuals gallery.
A playground application to help you test the existing visuals, and experiment with the
ones you have created.
A VisualTemplate extension for getting started with custom visuals.
Microsoft provided the steps for cloning and setting up the project on GitHub. I recommend you use Visual Studio 2015 for two reasons. First, the setup steps and walkthroughs on GitHub refer to the Visual Studio 2015 IDE and the VisualTemplate extension is available only with Visual Studio 2015. Second, Visual Studio 2015 integrates with GitHub. If you don’t have Visual Studio 2015, you can install the free community edition from https://www.visualstudio.com/vs-2015-product-editions.
TIP If you plan to contribute to the existing code by submitting GitHub pull requests, I recommend you also install the GitHub Extension for Visual Studio, which is an optional feature in the Visual Studio 2015 setup. This extension lets you clone GitHub repositories, create new repositories, and use GitHub features, such as Pull Requests, Issues, and Reports inside the Visual Studio IDE.
Exploring visual code
Once you install the project, the first thing you’d probably want to do is browse the code of the Microsoft Power BI visuals:
1.In the Visual Studio Solution Explorer, expand the Power BI-visuals project node.
2.Expand the src ð Clients ð visuals folder, as shown in Figure 13.5.
Figure 13.5 Most of the Power BI visuals are located in the visuals folder.
The samples folder includes most of the Power BI visuals. As you can see, the files have a
*.ts file extension because visuals are written in TypeScript. Most of the Power BI charts are located in the \Visuals\cartesian folder. The \Visuals\capabilities folder includes files that are used by the visuals to advertise their capabilities to the host.
Using the VisualTemplate extension
If you decide to code your visual in Visual Studio, you might find the Microsoft-provided VisualTemplate extension useful. It creates a template that you can use to jumpstart the visual implementation. Follow these steps to install the extension:
1.Install Visual Studio 2015. (Remember that the extension targets Visual Studio 2015 only.)
2.On the GitHub Power BI Visuals home page, click the “VSIX Package” link to download and install the extension. To check if the extension is installed, open Visual Studio, go to Tools menu ð Extensions, and then check that the VisualTemplate extension is listed.
3.To add a visual template to the project, right-click the folder where you want to add it to, such as the \Visuals\visuals folder, and then click File ð “Add New Item”.
4.In the Visual C# tab, find the IVisual template (see Figure 13.6), and then click Add.
This adds a new IVisual.ts file to your project.
Figure 13.6 The IVisual template is installed by the VisualTemplate extension.
The code in IVisual.ts file includes a definition of the IVisual interface (see Figure 13.7) with comments to help you code your visual. It also includes the definition of the
IVisualPlugin interface. Implementing the IVisualPlugin interface allows the playground application to discover the visual, and add the visual to the “Select a visual” drop-down on the home page (index.html), so that you can test the visual in the playground app.
Figure 13.7 The IVisual template includes code to get you started coding custom visuals.
Testing visuals
You can use the playground app to test a visual by following these steps:
1.In the Solution Explorer, navigate to src ð Clients ð PowerBIVisualsPlayground folder.
2.Right-click the index.html file, and then click “Set as Start Page”.
3.In the project properties (Build tab), set the “Before running startup page” drop-down to
“No Build” so that Visual Studio doesn’t compile the project every time you run it (this saves you time).
4.Press Ctrl-F5 to run the playground application and open the index.html page (see Figure 13.8).
Figure 13.8 The playground application allows you to test visuals.
5.Expand the “Select a visual” dropdown to find the visual you want to test. The page updates to show you the presentation of the visual. It also gives you options to enable animation and interaction options if the visual supports these features.
Debugging visuals
You have to use the browser debugging capabilities to debug a visual in the playground application. Here are the steps if you target Google Chrome:
1.With the index.html page open, press F12 to open Chrome Developer Tools.
2.In the Sources tab, expand the src/Clients folder and locate the TypeScript file of the visualization you want to debug. For example, to debug the areaRangeChart visual, select the areaRangeChart.ts file found in the samples folder (see Figure 13.9).
Figure 13.9 Use the browser debugging capabilities to debug a visual.
3.In the source pane, click a line number to set a breakpoint where you want the debugger to stop. For example, to debug the update method, put a breakpoint by clicking the line number below the update() method.
4.Expand the “Select a visual” dropdown and select the visual you want to debug. At this point, the breakpoint should be hit and you should be able to step through the code.
NOTE The playground application and Power BI Developer Tools allow you to debug the IVisual interface methods, but because they don’t actually host the visual, they don’t let you step through the configuration code that reads the data roles and formatting properties. If you need to debug this code, consider debugging the visual when it’s added to a Power BI Service report. I’ll show this debugging technique in the next section.