PowerBI - Custom Visualizations

Simon J.K. Pedersen (skp@delegate.dk)

How to get started building your own

Agenda

• What is a Custom Visualization
• How to make them
• How to distribute them
• Questions

What is a Custom Visualization

Get more from the Gallery

What is s Custom Visualization

• Just HTML, JavaScript and CSS
• Works on all paltforms (Web, Mobile, Desktop)
• Uses the PowerBI visulizations API
• The built-in visualizations use the same API*
• Packaged as a pbiviz file (just a zip)

Everything you can do in a browser you can do in a visualization

* except for the fact the custom visuals are sandboxed

What is s Custom Visualization

• Runs in Sandbox mode (an iframe)
• Written in TypeScript that transpiles to JavaScript
• Must implement the IVisual interface

export interface IVisual extends extensibility.IVisual {
        /** Notifies the IVisual of an update (data, viewmode, size change). */
        update<T>(options: VisualUpdateOptions, viewModel: T): void;

        /** Notifies the visual that it is being destroyed, 
            and to do any cleanup necessary (such as unsubscribing event handlers). */
        destroy?(): void;

        /** Gets the set of objects that the visual is currently displaying. */
        enumerateObjectInstances?(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration;
   }

What is a Custom Visualization

Life cycle

1. Init, called once when loaded do any heavy lifting
2. Get capabilities (enumerateObjectInstances), called to get the list of capabilities the visual have, to tell the host what the visual can do, e.g. to render the property pane
3. Update, called every time the visual should redraw, either because data changes or the layout changes
4. Destroy, called to release resources when the visual is removed

How to make a custom visualization

Prequisites

• Know TypeScript/JavaScript and HTML or team with someone who does
• Install node.js
• Pick an editor (Visual Studio Code, Visual Studio or something else, the editor is not important as long as it has syntax highlighting) 

How to make a custom visualization

• Tooling just changed as of 4th of August 2016 

The new way

• Read the docs (improved but still not perfect)
• Install the node CLI tool "npm install -g powerbi-visuals-tools"
• Make a new Visual "pbiviz new "Name of Visual"
• Run you visual "pbiviz start"
• Test it using the new PowerBI developer tools
• Run "pbiviz package"

How it used to be​

• Read the docs (poor)
• Clone a giant github repo 
• Use a Visual Studio extension or copy an existing visual and use that as a starting point
• Write your code
• Copy paste your code to PowerBI.com DevTools
• Test and Repeat 
• Use DevTools to package 

How to make a custom visualization

What do we get?

How to make a custom visualization

Capabilities.json

{
    "dataRoles": [],
    "dataViewMappings": [],
    "objects": {
        "settings": {
            "displayName": "Settings",
            "properties": {
                "baseUri": {
                    "displayName": "Server Url",
                    "type": {
                        "text": true
                    }
                },
                "toggle": {
                    "displayName": "Enable",
                    "type": {
                        "bool": true
                    }
                },
                "show": {
                    "displayName": "My Property Switch",
                    "type": {
                        "bool": true
                    }
                }
                
            }
        }
    },
    "supportsHighlight": true|false,
    "sorting": { ... }
}

How to make a custom visualization

Data Capabilities

{
    "dataRoles": [
        {
            "displayName": "Category Data",
            "name": "category",
            "kind": 0 
        },
        {
            "displayName": "Measure Data",
            "name": "measure",
            "kind": 1
        }
    ],
    "dataViewMappings": [
        {
            "categorical": {
                "categories": {
                    "for": {
                        "in": "category"
                    },
                    "dataReductionAlgorithm": {
                        "top": {}
                    }
                },
                "values": {
                    "select": [
                        {
                            "bind": {
                                "to": "measure"
                            }
                        }
                    ]
                }
            }
        }
    ]   
}

//Kind
0 = Category
1 = Measure
2 = MeasureOrCategory

How to make a custom visualization

Data View Mappings

Single

"dataViewMappings":[
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "single": { ... },
        "table": { ... },
        "matrix": { ... }
    }
]

"dataViewMappings": {
    "conditions": [
        { "Y": { "max": 1 } }
    ],
    "single": {
        "role": "Y"
    }
}  

Catagorical

"categorical": {
        "categories": {
            "for": { "in": "category" }
        },
        "values": {
            "select": [
                { "bind": { "to": "measure" } }
            ]
        }
    }

How to make a custom visualization

Data View Mappings

More info

How to make a custom visualization

• The typical flow in a Visual on every update cycle is:
  1. Check what is updated (exit early if it is just a resize event, and your visual can handle resize without rerender)
  2. Get data from ViewData from the data model that fits the visualization
  3. (Transform data from ViewData into a rendering model)
  4. Render the data 

How to make a custom visualization

• Use the built-in visuals when you can
  • Use the R visual if R has a graph that can do the job
  • Check the ideas.powerbi.com before you start 
• Use third party libraries in your visualization
  • OpenLayers for maps
• You are not limited to traditional visuals
  • You can do a video feed or audio if you want and it makes sense in your report
  • You can do WebGL  

Don't reinvent the wheel

How to distribute

• Your pbiviz files gets included in your pbix file
  • Beware it is hard to update your custom visuals in existing reports (equally true for standard visuals)
• Show stoppers in the past
  • Users have to accept the use of your third party visual
  • Impossible to delete custom visuals from pbix files
  • They broke in the mobile app
• Show stoppers now
  • None :) 

Thank you for your time!

Twitter: @simped

GitHub: https://github.com/sjkp/SJKP.PbiViz.HellowWorld

Mail: skp@delegate.dk / mail@sjkp.dk