Migrate SampleBarChart to new Formatting Model Pane

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This page contains information about changes to the 'Sample bar chart' Power BI visual.
 
+## 3.3.0
+
+* Migrate to API version 5.1.0
+* Update powerbi-visuals-api to 5.1.x
+* Added powerbi-visuals-utils-formattingmodel 5.0.x
+* Replace enumerateObjectInstances by getFormattingModel API
+* Build new formatting pane settings
+
 ## 3.2.0
 
 * Added *modern tooltip* feature

Tutorial/ColorPalette.md

@@ -26,16 +26,28 @@ interface BarChartDataPoint {
 `colorPalette` is a service that manages the colors used on your visual. An instance of it is available on `IVisualHost`.
 
 ## Assigning Color to Data Points
-We defined `visualTransform` as a construct to convert `dataView` to a view model Bar Chart can use.
-Since we iterate through the data points in `visualTransform` it is also the ideal place to assign colors.
+We defined `createSelectorDataPoints` as a construct to convert  options `dataView` to Bar Chart data points that will be used in visual view.
+Since we iterate through the data points in `createSelectorDataPoints` it is also the ideal place to assign colors.
 
 ```typescript
 let colorPalette: IColorPalette = host.colorPalette; // host: IVisualHost
+const strokeColor: string = getColumnStrokeColor(colorPalette);
+const strokeWidth: number = getColumnStrokeWidth(colorPalette.isHighContrast);
+
 for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i < len; i++) {
+    const color: string = getColumnColorByIndex(category, i, colorPalette);
+
+    const selectionId: ISelectionId = host.createSelectionIdBuilder()
+        .withCategory(category, i)
+        .createSelectionId();
+
     barChartDataPoints.push({
-        category: category.values[i],
+        color,
+        strokeColor,
+        strokeWidth,
+        selectionId,
         value: dataValue.values[i],
-        color: colorPalette.getColor(category.values[i]).value,
+        category: `${category.values[i]}`,
     });
 }
 ```

Tutorial/ConditionalFormatting.md

@@ -1,7 +1,5 @@
 # Adding conditional formatting to your Visual 
-[Conditional formatting](https://docs.microsoft.com/en-us/power-bi/visuals/service-tips-and-tricks-for-color-formatting#conditional-formatting-for-visualizations) of custom properties is supported by updating `VisualObjectInstance` object's properties as enumerated under `enumerateObjectInstances` method.
-
-See [commit](https://github.com/microsoft/powerbi-visuals-api/commit/8fe88399c5ba82feeec4541ce5bf8e02a3ecd15a) for what was added at this step.
+[Conditional formatting](https://docs.microsoft.com/en-us/power-bi/visuals/service-tips-and-tricks-for-color-formatting#conditional-formatting-for-visualizations) of custom formatting properties is supported by updating formatting property object's in `getFormattingModel` method.
 
 Conditional formatting can only be applied to the following property types:
 * Color
@@ -10,25 +8,23 @@ Conditional formatting can only be applied to the following property types:
 * Web URL
 
 ## Add a conditional color formatting entry in the format pane
-To add the conditional color formatting button in the format pane for the desired object, under the `enumerateObjectInstances` method, make the following change:
+To add the conditional color formatting button in the format pane for the desired object, under the `getFormattingModel` method, make the following change:
 
-Via `propertyInstanceKind` property of enumerated `VisualObjectInstance`, list all the properties that you'd like to have the conditional formatting entry applied to in the format pane. 
+Define `instanceKind` property of required formatting property `descriptor` with the appropriate value.
 Use `VisualEnumerationInstanceKinds` enum to declare the type of the desired format (constant, rule or both). 
 
 ```typescript
 // List your conditional formatting properties
-propertyInstanceKind: {
-    fill: VisualEnumerationInstanceKinds.ConstantOrRule
-}
+instanceKind: powerbi.VisualEnumerationInstanceKinds.ConstantOrRule
 ```
 ![](images/ConditionalFormattingEntry.png)
 
 ## Define how conditional formatting behaves
 Using `createDataViewWildcardSelector` declared under `powerbi-visuals-utils-dataviewutils`, specify whether conditional formatting will be applied to instances, totals, or both. For more information, see [DataViewWildcard](https://docs.microsoft.com/en-us/power-bi/developer/visuals/utils-dataview#dataviewwildcard).
 
-In `enumerateObjectInstances`, make the following changes to the objects you want to apply conditional formatting to:
+In `BarChartFormattingSettingsModel`, make the following changes to the formatting properties you want to apply conditional formatting to:
 
-* Replace the `VisualObjectInstance`'s `selector` value with a `dataViewWildcard.createDataViewWildcardSelector()` call. Specify the desired option from `DataViewWildcardMatchingOption` enum to define whether conditional formatting is applied to instances, totals, or both.
+* Replace the formatting property `descriptor`'s `selector` value with a `dataViewWildcard.createDataViewWildcardSelector()` call. Specify the desired option from `DataViewWildcardMatchingOption` enum to define whether conditional formatting is applied to instances, totals, or both.
 
 * Add the `altConstantValueSelector` property having the value previously defined for the `selector` property.
 
@@ -39,6 +35,6 @@ selector: dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataV
 // Add this property with the value previously defined for the selector property
 altConstantValueSelector: barDataPoint.selectionId.getSelector()
 ```
-See [commit](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart/commit/956923b641bb1eacb613bf55a91f77725bc42431) for how conditional formatting was applied to sample bar chart.
+See [commit](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart) for how conditional formatting was applied to sample bar chart.
 
 ![](images/CondFormatSupport.png)

Tutorial/DataBinding.md

@@ -57,26 +57,25 @@ Use the internal `name` defined in your dataRoles to reference each field.
 
 For more information, see the section about [Data View Mapping](https://github.com/Microsoft/PowerBI-visuals/blob/master/Capabilities/DataViewMappings.md).
 
-## Defining and Using `visualTransform`
+## Defining and Using `createSelectorDataPoints`
 DataView is the structure that PowerBI provides to your visual and it contains the queried data to be visualized.
 However, DataView provides your data in different forms such as categorical and table forms. In this instance we're building a categorical visual and we will only need the use the categorical property on the DataView.
 
-Defining visualTransform will allow you to convert DataView into a view model your visual will use.
+Defining `createSelectorDataPoints` will allow you to convert options dataView into bar chart data points your visual will use.
 IVisualHost is required because when defining individual data points, you will want to assign colors and selection to them.
 
 ```typescript
 /**
- * Function that converts queried data into a view model that will be used by the visual
+ * Function that converts queried data into bar chart data points that will be used by the visual
  *
  * @function
  * @param {VisualUpdateOptions} options - Contains references to the size of the container
  *                                        and the dataView which contains all the data
  *                                        the visual had queried.
  * @param {IVisualHost} host            - Contains references to the host which contains services
  */
-function visualTransform(options: VisualUpdateOptions, host: IVisualHost): BarChartViewModel {
-    /*Convert dataView to your viewModel*/
+function createSelectorDataPoints(options: VisualUpdateOptions, host: IVisualHost): BarChartDataPoint[] {
+    /*Convert dataView to bar chart data points*/
 }
 
-```
-See [commit](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart/commit/3c6e8186436b63bf0cf97d2cdd5dde8aa8d08709) for what was added to visualTransform
+```

Tutorial/DataBoundObjects.md

@@ -9,16 +9,13 @@ See [commit](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart/commit/
 ## Define Object in Capabilities
 Similar to static objects, we will define another object in the capabilities
 `colorSelector` is the internal name that will be referenced in the `dataView`.
-`displayName` is the name that will be shown on the property pane.
 
 `fill` is a `StructuralObjectValue` and is not associated with a primitive type.
 
 ```typescript
 "colorSelector": {
-    "displayName": "Data Colors",
     "properties": {
         "fill": {
-            "displayName": "Color",
             "type": {
                 "fill": {
                     "solid": {
@@ -69,74 +66,67 @@ export function getCategoricalObjectValue<T>(category: DataViewCategoryColumn, i
 See [objectEnumerationUtility.ts](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart/blob/master/src/objectEnumerationUtility.ts) for source code.
 
 ## Defining Default Color and Retrieving Categorical Object from DataView
-Each color is now associated with each category inside `dataView`. We will set each data point to its cooresponding color.
+Each color is now associated with each category inside  options dataView. We will set each data point to its corresponding color.
 
 ```typescript
+ const strokeWidth: number = getColumnStrokeWidth(colorPalette.isHighContrast);
+
 for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i < len; i++) {
-    let defaultColor: Fill = {
-        solid: {
-            color: colorPalette.getColor(category.values[i]).value
-        }
-    }
+    const color: string = getColumnColorByIndex(category, i, colorPalette);
+
+    const selectionId: ISelectionId = host.createSelectionIdBuilder()
+        .withCategory(category, i)
+        .createSelectionId();
 
     barChartDataPoints.push({
-        category: category.values[i],
+        color,
+        strokeColor,
+        strokeWidth,
+        selectionId,
         value: dataValue.values[i],
-        color: getCategoricalObjectValue<Fill>(category, i, 'colorSelector', 'fill', defaultColor).solid.color,
-        selectionId: host.createSelectionIdBuilder()
-            .withCategory(category, i)
-            .createSelectionId()
+        category: `${category.values[i]}`,
     });
 }
 ```
 
-## Populate Property Pane with `enumerateObjectInstances`
-`enumerateObjectInstances` is used to populate the property pane with objects. 
+## Populate Property Pane with `getFormattingModel`
+`getFormattingModel` is used to populate the property pane with objects. 
+For more information [here](https://learn.microsoft.com/en-us/power-bi/developer/visuals/format-pane)
+
 For this instance, we would like a color picker per category we have. Each category be rendered on the property pane.
+We will do this by adding a populate method `populateColorSelector` to create corresponding bar chart data points color selector in format pane after building the data points in `update` method. This `populateColorSelector` method iterate through each data point with the associated color.
 
-We will do this by adding an additional case to the switch statement for `colorSelector` and iterate through each data point with the associated color.
+Selection is required to associate the color with a data point.
+In visual class:
+```typescript 
+    public update(options: VisualUpdateOptions) {
+        this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(BarChartSettingsModel, options.dataViews);
+        this.barDataPoints = createSelectorDataPoints(options, this.host);
+        this.formattingSettings.populateColorSelector(this.barDataPoints);
 
-Selection is required to associate the color with a datapoint.
+        // ...
+    }
+```
 
+In formatting settings model:
 ```typescript
-/**
- * Enumerates through the objects defined in the capabilities and adds the properties to the format pane
- *
- * @function
- * @param {EnumerateVisualObjectInstancesOptions} options - Map of defined objects
+ /**
+ * populate colorSelector object categories formatting properties
+ * @param dataPoints 
  */
-public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
-    let objectName = options.objectName;
-    let objectEnumeration: VisualObjectInstance[] = [];
-
-    switch(objectName) {
-        case 'enableAxis':
-            objectEnumeration.push({
-                objectName: objectName,
-                properties: {
-                    show: this.barChartSettings.enableAxis.show,
-                },
-                selector: null
-            });
-            break;
-        case 'colorSelector':
-            for(let barDataPoint of this.barDataPoints) {
-                objectEnumeration.push({
-                    objectName: objectName,
-                    displayName: barDataPoint.category,
-                    properties: {
-                        fill: {
-                            solid: {
-                                color: barDataPoint.color
-                            }
-                        }
-                    },
-                    selector: barDataPoint.selectionId.getSelector()
-                });
-            }
-            break;
-    };
-
-    return objectEnumeration;
+populateColorSelector(dataPoints: BarChartDataPoint[]) {
+    let slices = this.colorSelector.slices;
+    if (dataPoints) {
+        dataPoints.forEach(dataPoint => {
+            slices.push(new formattingSettings.ColorPicker({
+                name: "fill",
+                displayName: dataPoint.category,
+                value: { value: dataPoint.color },
+                selector: dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataViewWildcardMatchingOption.InstancesAndTotals),
+                altConstantSelector: dataPoint.selectionId.getSelector(),
+                instanceKind: powerbiVisualsApi.VisualEnumerationInstanceKinds.ConstantOrRule
+            }));
+        });
+    }
 }
 ```

Tutorial/ExtensibilityUtils.md

@@ -9,6 +9,7 @@ PowerBI provides several tools that help to cover the main needs to build your o
 5. [InteractivityUtils](https://www.npmjs.com/package/powerbi-visuals-utils-interactivityutils) is a set of functions and classes for implementation of cross-selection and cross-filtering for PowerBI custom visuals.
 6. [FormattingUtils](https://www.npmjs.com/package/powerbi-visuals-utils-formattingutils) are interfaces for creating PowerBI custom visuals.
 7. [SVGUtils](https://www.npmjs.com/package/powerbi-visuals-utils-svgutils) is a tool for SVG manipulations for PowerBI custom visuals.
+8. [FormattingModelUtils](https://github.com/microsoft/powerbi-visuals-utils-formattingmodel) is a set of classes, interfaces and method help building format pane easily.
 
 ### How to install
   To install the package you should run the following command in the directory with your current custom visual:

Tutorial/HighContrastSupport.md

@@ -65,7 +65,7 @@ In Sample Bar Chart, for example, all bars are drawn with 2 pixels thick foregro
 ![Sample Bar Chart using *Dark #2* color theme](images/HC_sampleBarChart_dark2.png)
 ![Sample Bar Chart using *White* color theme](images/HC_sampleBarChart_white.png)
 
-Here is one place in the `visualTransform` function that was changed to support high-contrast, it is called as part of rendering during `update`:
+Here is one place in the `createSelectorDataPoints` function that was changed to support high-contrast, it is called as part of rendering during `update`:
 
 **before**
 ```typescript
@@ -89,6 +89,11 @@ Here is one place in the `visualTransform` function that was changed to support
 
 **after**
 ```typescript
+
+    const colorPalette: ISandboxExtendedColorPalette = host.colorPalette;
+    const strokeColor: string = getColumnStrokeColor(colorPalette);
+    const strokeWidth: number = getColumnStrokeWidth(colorPalette.isHighContrast);
+
     for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i < len; i++) {
         const color: string = getColumnColorByIndex(category, i, colorPalette);
 

Tutorial/LaunchURL.md

@@ -1,12 +1,10 @@
 # Opening a URL in a new tab/window
 Launch URL allows opening a new browser tab (or window), by delegating the actual work to Power BI.
 
-See [commit](https://github.com/Microsoft/PowerBI-visuals-sampleBarChart/commit/2ecc5cf74b9bc6fbf5c03f84c3ab24841b489d4e) for what was added at this step.
-
 Note: custom visuals are hosted in Power BI inside sandboxed iframes, this prevents opening a new browser tab (or window) in "the usual way", e.g. using `window.open('http://some.link.net','_blank')`.
 
 ## Usage
-Use the `host.launchUrl()` API call, passing your destenation URL as a string argument:
+Use the `host.launchUrl()` API call, passing your destination URL as a string argument:
 
 ```typescript
 this.host.launchUrl('http://some.link.net');
@@ -18,7 +16,7 @@ this.host.launchUrl('http://some.link.net');
 
 ## Best practices
 1. For most cases, it is best to only open a link as a response to a user's explicit action. Make it easy for the user to understand that clicking the link or button will result in opening a new tab. Triggering a `launchUrl()` call without a user's action, or as a side effect of a different action can be confusing or frustrating for the user.
-2. If the link is not crucial for the proper functioning of the visual, it is recommanded to provide the report's author a way to disable and hide the link. This is especially relevant for special Power BI use-cases, such as embedding a report in a 3rd party application or publishing it to the web.
+2. If the link is not crucial for the proper functioning of the visual, it is recommended to provide the report's author a way to disable and hide the link. This is especially relevant for special Power BI use-cases, such as embedding a report in a 3rd party application or publishing it to the web.
 3. Avoid Triggering a `launchUrl()` call from inside a loop, the visual's `update` function, or any other frequently recurring code.
 
 ## Step by step example
@@ -51,11 +49,9 @@ A `showHelpLink` boolean static object was added to `capabilities.json` objects
 "objects": {
 //...
     "generalView": {
-            "displayName": "General View",
             "properties": 
                 //...
                 "showHelpLink": {
-                    "displayName": "Show Help Button",
                     "type": { 
                         "bool": true 
                     }

Tutorial/Locale.md

@@ -14,15 +14,15 @@ In the sample we display the current locale in the tooltip.
 
 Each of these bar charts was created under different locale (English, Basque and Hindi).
 
-The BarChart contructor now has a `locale` member which is instantiated in the constructor with the host `locale` instance.
+The BarChart constructor now has a `locale` member which is instantiated in the constructor with the host `locale` instance.
 
 ```typescript
     private locale: string;
     ...
     this.locale = options.host.locale;
 ```
 
-A `LocalizaionResources` interface was added, which helps in localizing strings. It defines the required string for each locale, and also the 'defaultValue', which will be displayed if the visual wansn't adapted to this locale.<br>
+A `LocalizationResources` interface was added, which helps in localizing strings. It defines the required string for each locale, and also the 'defaultValue', which will be displayed if the visual wasn't adapted to this locale.<br>
 `myResources` is an instance of this interface, which holds the localized strings:
 
 ```typescript
@@ -45,7 +45,7 @@ module powerbi.extensibility.visual {
 Getting a localized string is easy using `getLocalizedString`.
 ```typescript
     /**
-     * Returns the localized string in the locale transfared using the key that was given to serch the resources
+     * Returns the localized string in the locale transferred using the key that was given to search the resources
      * 
      * @param {string} locale - the locale in which PowerBI is currently running
      * @param {object} key - specify a key for the string you want localized in your visual
@@ -68,3 +68,6 @@ private getTooltipData(value: any): VisualTooltipDataItem[] {
     }];
 }
 ```
+
+## Format Pane Localization 
+For more info on localization [here](https://learn.microsoft.com/power-bi/developer/visuals/localization)