Visual API

All visuals start with a class that implements the IVisual interface. You can name the class anything as long as there's exactly one class that implements the IVisual interface.

Note

The visual class name must be the same as the visualClassName in the pbiviz.json file.

The visual class should implement the following methods as shown in the sample below:

  • constructor, a standard constructor that initializes the visual's state
  • update, updates the visual's data
  • getFormattingModel, returns a formatting model that populates the property pane (formatting options) where you can modify properties as needed
  • destroy, a standard destructor for cleanup
class MyVisual implements IVisual {
    
    constructor(options: VisualConstructorOptions) {
        //one time setup code goes here (called once)
    }
    
    public update(options: VisualUpdateOptions): void {
        //code to update your visual goes here (called on all view or data changes)
    }

    public getFormattingModel(): FormattingModel {
        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }
    
    public destroy(): void {
        //one time cleanup code goes here (called once)
    }
}

constructor

The constructor of the visual class is called when the visual is instantiated. It can be used for any set-up operations the visual needs.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

  • element: HTMLElement, a reference to the DOM element that will contain your visual

  • host: IVisualHost, a collection of properties and services that can be used to interact with the visual host (Power BI)

    IVisualHost contains the following services:

    • createSelectionIdBuilder, generates and stores metadata for selectable items in your visual

    • createSelectionManager, creates the communication bridge used to notify the visual's host about changes in the selection state, see Selection API.

    • createLocalizationManager, generates a manager to help with localization

    • allowInteractions: boolean, a boolean flag that determines whether or not the visual is interactive

    • applyJsonFilter, applies specific filter types, see Filter API

    • persistProperties, allows users to create persistent settings and save them along with the visual definition, so they're available on the next reload

    • eventService, returns an event service to support Render events

    • storageService, returns a service to help use local storage in the visual

    • authenticationService, generates a service to help with user authentication

    • tooltipService, returns a tooltip service to help use tooltips in the visual

    • launchUrl, helps to launch URL in next tab

    • locale, returns a locale string, see Localization

    • instanceId, returns a string to identify the current visual instance

    • colorPalette, returns the colorPalette required to apply colors to your data

    • fetchMoreData, supports using more data than the standard limit (1K rows)

    • switchFocusModeState, helps to change the focus mode state

      export interface IVisualHost extends extensibility.IVisualHost {
           createSelectionIdBuilder: () => visuals.ISelectionIdBuilder;
           : () => ISelectionManager;
           colorPalette: ISandboxExtendedColorPalette;
           persistProperties: (changes: VisualObjectInstancesToPersist) => void;
           applyJsonFilter: (filter: IFilter[] | IFilter, objectName: string, propertyName: string, action: FilterAction) => void;
           tooltipService: ITooltipService;
           telemetry: ITelemetryService;
           authenticationService: IAuthenticationService;
           locale: string;
           allowInteractions: boolean;
           launchUrl: (url: string) => void;
           fetchMoreData: () => boolean;
           instanceId: string;
           refreshHostData: () => void;
           createLocalizationManager: () => ILocalizationManager;
           storageService: ILocalVisualStorageService;
           eventService: IVisualEventService;
           switchFocusModeState: (on: boolean) => void;
      }
      

update

All visuals must implement a public update method that's called whenever there's a change in the data or host environment.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport, dimensions of the viewport that the visual should be rendered within
  • dataViews: DataView[], the dataview object that contains all data needed to render your visual (your visual will typically use the categorical property under DataView)
  • type: VisualUpdateType, flags indicating the type(s) of data being updated (Data | Resize | ViewMode | Style | ResizeEnd)
  • viewMode: ViewMode, flags indicating the view mode of the visual (View | Edit | InFocusEdit)
  • editMode: EditMode, flag indicating the edit mode of the visual (Default | Advanced) (if the visual supports AdvancedEditMode, it should render its advanced UI controls only when editMode is set to Advanced, see AdvancedEditMode)
  • operationKind?: VisualDataChangeOperationKind, flag indicating type of data change (Create | Append)
  • jsonFilters?: IFilter[], collection of applied json filters
  • isInFocus?: boolean, flag to indicate if the visual is in focus mode or not

getFormattingModel (optional)

This method is called once each time we open the properties pane or the user edits any of the properties in the pane. It returns FormattingModel with all information on the properties pane design, hierarchy, properties and latest formatting values.

getFormattingModel(): visuals.FormattingModel;

destroy (optional)

The destroy function is called when your visual is unloaded and can be used for clean-up tasks such as removing event listeners.

public destroy(): void

Tip

Power BI generally doesn't call destroy since it's faster to remove the entire IFrame that contains the visual.

Next steps