PowerBI Custom Visuals 2: The Visual Class

Structure of a Custom Visual: 2

The Visual Class

The visual itself is defined in a visual.ts file at the root of the package directory. PowerBI custom visuals use an object-oriented approach in Typescript for their definition, see this Wiki page for an introduction to the object-oriented approach in Typescript.

The Custom Visuals API defines a base object type (class) for a custom visual (IVisual). Defining custom visuals then requires specifying an implementation of this base class, with three required methods (functions):

• constructor
• update
• enumerateObjectInstances

A minimal 'skeleton' of a custom visual in Typescript looks like the following (note that import statements are used to introduce type and function definitions from other packages/files):

import powerbi from "powerbi-visuals-api";
import IVisual = powerbi.extensibility.IVisual;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;

export class Visual implements IVisual {

  constructor(options: VisualConstructorOptions) {
  };

  update(options: VisualUpdateOptions) {
  };

  enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions) {
  };
}

Note that these functions are each defined as taking an input argument called options. This is implicitly passed to the visual from PowerBI, and contains all of the user-provided data and settings. These options objects slightly differ between the functions, because each function has a distinct purpose.

constructor()

As discussed in the object-oriented primer wiki page, the constructor is a special function for a class which defines how its members/values will be initialised when the object is created. The constructor() for a custom visual is used to initialise the plotting area and objects which will later be updated with the plotted content itself. This constructor() call is only run once (when the visual is first added to a report page), with all of actual calculation and plotting handled by the update() function.

update()

The update() method is run on every update or change to the visual (e.g., adding/removing data, resizing the plot, highlighting data on other visuals). The options object passed to the update() function contains all of the user-provided data, and is used to extract the input data and display a plot/visual. Whenever a change to the visual is made, the update() function is called again to operate on the newly changed input data and draw the plot within the newly sized plotting area.

enumerateObjectInstances()

The final required method is enumerateObjectInstances(), this method is used to expose the settings specified in the capabilities.json file to PowerBI for rendering.