PowerBI Custom Visuals 1: Input Data & Settings
The first step of the custom visual is defining the types of data that can be loaded, and the various settings that will be available. This is handled by the capabilities.json file in the root of the directory. The content of this file controls the display of the input data pane and the visualisation settings pane in PowerBI.
There are three primary components of the capabilities.json file:
dataRolesobjectsdataViewMappings
The dataRoles section is used to specify the input data fields that will be displayed in PowerBI, and whether a given input will define the groupings when aggregrating the other inputs. There are three fields to provide for each input:
-
displayName: The text that will be shown in PowerBI -
name: What the object will be named internally for accessing by the visual -
kind: Whether the inputs are groups (Grouping) or responses which can be aggregated (Measure).
For the Funnel visual, this section is:
"dataRoles": [
{
"displayName": "Groups",
"name": "group",
"kind": "Grouping"
},
{
"displayName": "Numerator",
"name": "numerator",
"kind": "Measure"
},
{
"displayName": "Denominator",
"name": "denominator",
"kind": "Measure"
},
{
"displayName": "Optional: Chart Type",
"name": "chart_type",
"kind": "Measure"
},
{
"displayName": "Optional: Multiplier",
"name": "chart_multiplier",
"kind": "Measure"
}
]The objects section is used for defining the visualisation settings pane. Each settings group in the visualisations pane is constructed by defining a new entry in objects. This entry then contains further nested entries which define the individual settings options that are presented.
For example, the Funnel visual contains a settings group called "Data Settings", which includes a drop-down box for selecting the chart type:
The corresponding section of the capabilities.json file is:
"objects": {
"funnel" : {
"displayName": "Data Settings",
"properties": {
"data_type": {
"displayName": "Data Type",
"type" : {
"enumeration" : [
{
"displayName" : "Indirectly Standardised (HSMR)",
"value" : "SR"
},
{
"displayName" : "Proportion",
"value" : "PR"
},
{
"displayName" : "Rate",
"value" : "RC"
}
]
}
},
...The section above shows that new settings group has been defined ("funnel"), which will displayed in PowerBI as "Data Settings". The properties field then contains the definitions of the individual settings, which shows the first as the definition for data_type. Note that the "type" field of the definition controls the input method when the settings option is shown in PowerBI - where enumeration specifies a dropdown box.
The final section, dataViewMappings controls how the data is structured when it's loaded from PowerBI - this complements the earlier definitions of whether the input data are of type Grouping or Measure.
This visual uses the categorical view mapping, where a given input variable (in this case, hospitals) determines the categories/groupings for aggregating the inputs. This also determines which variables will be used for defining the relationships with other visuals to control interactivity (highlighting).
Within the categorical view mapping, the grouping variable(s) are declared under the categories section, and the others under the values section. For the Funnel visual, this section of the capabilities.json is:
"dataViewMappings": [
{
"categorical": {
"categories": {
"for": {
"in": "group"
}
},
"values": {
"select": [
{
"for": {
"in": "numerator"
}
},
{
"for": {
"in": "denominator"
}
},
{
"for": {
"in": "chart_type"
}
},
{
"for": {
"in": "chart_multiplier"
}
}
]
}
}
}
]