Working with settings

Step by step guide how to build React-based Custom Visual

It’s time to make the visual customizable.

1. Go to capabilities.json and describe settings in objects property.

    //...
        "objects": {
            "circle": {
                "displayName": "Circle",
                "properties": {
                    "circleColor": {
                        "displayName": "Color",
                        "description": "The fill color of the circle.",
                        "type": {
                            "fill": {
                                "solid": {
                                    "color": true
                                }
                            }
                        }
                    },
                    "circleThickness": {
                        "displayName": "Thickness",
                        "description": "The circle thickness.",
                        "type": {
                            "numeric": true
                        }
                    }
                }
            }
        },
    //...
   

2. Replace existing code from src/settings.ts with the new one:

    "use strict";
   
    import { dataViewObjectsParser } from "powerbi-visuals-utils-dataviewutils";
    import DataViewObjectsParser = dataViewObjectsParser.DataViewObjectsParser;
   
    export class CircleSettings {
        public circleColor: string = "white";
        public circleThickness: number = 2;
    }
   
    export class VisualSettings extends DataViewObjectsParser {
        public circle: CircleSettings = new CircleSettings();
    }
   

3. Import required dependencies at the top of src/visual.ts

    import VisualObjectInstance = powerbi.VisualObjectInstance;
    import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
    import VisualObjectInstanceEnumerationObject = powerbi.VisualObjectInstanceEnumerationObject;
   
    import { VisualSettings } from "./settings";
   
   

4. enumerateObjectInstances method is used to apply visual settings. Extend src/visual.ts by inserting new lines:

    export class Visual implements IVisual {
        private settings: VisualSettings;
   
        //...
   
        public enumerateObjectInstances(
            options: EnumerateVisualObjectInstancesOptions
        ): VisualObjectInstance[] | VisualObjectInstanceEnumerationObject {
   
            return VisualSettings.enumerateObjectInstances(this.settings || VisualSettings.getDefault(), options);
        }
    }
   

5. Now the settings can be received from DataView object.

        public update(options: VisualUpdateOptions) {
   
            if(options.dataViews && options.dataViews[0]){
                //...
                this.settings = VisualSettings.parse(dataView) as VisualSettings;
                const object = this.settings.circle;
   
                ReactCircleCard.update({
                    borderWidth: object && object.circleThickness ? object.circleThickness : undefined,
                    background: object && object.circleColor ? object.circleColor : undefined,
                    //...
                });
            }
        }
    }
   

6. Apply the corresponding changes to src/component.tsx. Extend State interface first.

    export interface State {
        //...
        background?: string,
        borderWidth?: number
    }
   

   … and type the following code into render method.

        const { /*...*/ background, borderWidth } = this.state;
   
        const style: React.CSSProperties = { /*...*/ background, borderWidth };
   

   

Well done! Now you can develop your own Custom Visuals using React Framework.