Merge pull request #12771 from MicrosoftDocs/main

12/19/2024 PM Publish

.openpublishing.redirection.json

@@ -6360,6 +6360,11 @@
             "source_path": "powerbi-docs/guidance/whitepaper-azure-b2b-power-bi.md",
             "redirect_url": "/power-bi/enterprise/service-admin-azure-ad-b2b",
             "redirect_document_id": false
+        },
+        {
+            "source_path": "powerbi-docs/developer/visuals/format-pane.md",
+            "redirect_url": "/power-bi/developer/visuals/format-pane-general",
+            "redirect_document_id": false
         }   
   ]
 }

powerbi-docs/developer/visuals/TOC.yml

@@ -73,7 +73,48 @@
     - name: "Analytics pane" 
       href: analytics-pane.md
     - name: "Add format pane"
-      href: format-pane.md
+      expanded: false
+      items:
+        - name: "Format pane"
+          href: format-pane-general.md
+        - name: "Format pane example"
+          href: format-pane-example.md
+        - name: "Formatting components"
+          expanded: false
+          items:
+            - name: "Formatting card"
+              href: formatting-model-card.md
+            - name: "Formatting group"
+              href: formatting-model-group.md
+            - name: "Formatting container"
+              href: formatting-model-container.md
+        - name: "Formatting slices"
+          expanded: false
+          items:
+            - name: "Toggle switch"
+              href: "formatting-model-toggleswitch.md"
+            - name: "Num up down"
+              href: "formatting-model-numupdown.md"
+            - name: "Slider"
+              href: "formatting-model-slider.md"
+            - name: "Color picker"
+              href: "formatting-model-colorpicker.md"
+            - name: "Dropdowns"
+              href: "formatting-model-dropdown.md"
+            - name: "Flag selections"
+              href: "formatting-model-flagselection.md"
+            - name: "Text input"
+              href: "formatting-model-textinput.md"
+            - name: "Text area"
+              href: "formatting-model-textarea.md"
+            - name: "Font picker"
+              href: "formatting-model-fontpicker.md"
+            - name: "Alignment group"
+              href: "formatting-model-alignmentgroup.md"
+            - name: "Font control"
+              href: "formatting-model-fontcontrol.md"
+            - name: "Margin padding"
+              href: "formatting-model-marginpadding.md"
     - name: "Fetch more data" 
       href: fetch-more-data.md
     - name: "Add bookmarks support"

powerbi-docs/developer/visuals/analytics-pane.md

@@ -29,7 +29,7 @@ For the **Analytics** pane, the object is defined as follows:
 
 ### [API 5.1+](#tab/API-5-1)
 
-Under the object's definition, add only the object name, property name and type as explained [here](./format-pane.md).
+Under the object's definition, add only the object name, property name and type as explained [here](./format-pane-general.md).
 Example:
 
 ```json

powerbi-docs/developer/visuals/changelog.md

@@ -34,7 +34,7 @@ https://github.com/microsoft/powerbi-visuals-api/blob/main/CHANGELOG.md
 
 ## API v5.9.0
 
-* [**Hierarchial identity filter API**](./hierarchy-filter-api.md): Allows you to create a visual that uses Matrix DataView Mapping to filter data based on data points that use a hierarchal structure. This is useful for custom visuals that leverage group-on keys semantic models and want to filter hierarchies based on data points.
+* [**Hierarchical identity filter API**](./hierarchy-filter-api.md): Allows you to create a visual that uses Matrix DataView Mapping to filter data based on data points that use a hierarchical structure. This is useful for custom visuals that leverage group-on keys semantic models and want to filter hierarchies based on data points.
 * [`acquireAADTokenService`](./authentication-api.md): Extended with additional properties
 * Supports Desktop March 2024
 
@@ -76,7 +76,7 @@ https://github.com/microsoft/powerbi-visuals-api/blob/main/CHANGELOG.md
 * **[Custom sorting](./sort-options.md#custom-sorting)** - improved custom sorting for tables
 * **[Subtotals](./total-subtotal-api.md)** - new *Subtotals Type* indicates if totals should be retrieved before or after the rest of the data
 * **[Identity filter](./identity-filter-api.md)** - filter categorical data
-* **[New format pane](./format-pane.md)** - design a custom visual that supports the new format pane design
+* **[New format pane](./format-pane-general.md)** - design a custom visual that supports the new format pane design
 * Supports Desktop October 2022
 
 ## API v4.7.0
@@ -237,10 +237,10 @@ https://github.com/microsoft/powerbi-visuals-api/blob/main/CHANGELOG.md
 ## API v1.1.0
 
 * Supports debug visual in iFrame
-* Adds light weight sandbox with faster initialization of the iFrame
+* Adds lightweight sandbox with faster initialization of the iFrame
 * Fixes [Capabilities.objects does not support "text" type](https://github.com/Microsoft/PowerBI-visuals-tools/issues/12) issue
 * Supports `pbiviz update` to update visual API type definitions and schema
-* Supports `--api-version` flag in `pbiviz new` to create visuals with a specific api version
+* Supports `--api-version` flag in `pbiviz new` to create visuals with a specific API version
 * Supports alpha release of API v1.2.0
 
 ### Visual Host

powerbi-docs/developer/visuals/create-bar-chart.md

@@ -531,9 +531,9 @@ In addition to scaling, the update method also handles selections and colors. Th
 
 ### Populate the properties pane using the formatting model Utils
 
-The final method in the `IVisual` function is [`getFormattingModel`](visual-api.md#getformattingmodel-optional). This method builds and returns a modern *format pane formatting model* object containing all the [format pane](./format-pane.md) components and properties. It then places the object inside the **Format** pane. In our case, we create format cards for `enableAxis` and `colorSelector`, including formatting properties for `show` and `fill`, according to the *"objects"* in the *capabilities.json* file. To add a color picker for each category on the **Property** pane, add a for loop on `barDataPoints` and for each one add a new color picker format property to the formatting model.
+The final method in the `IVisual` function is [`getFormattingModel`](visual-api.md#getformattingmodel-optional). This method builds and returns a modern *format pane formatting model* object containing all the [format pane](./format-pane-general.md) components and properties. It then places the object inside the **Format** pane. In our case, we create format cards for `enableAxis` and `colorSelector`, including formatting properties for `show` and `fill`, according to the *"objects"* in the *capabilities.json* file. To add a color picker for each category on the **Property** pane, add a for loop on `barDataPoints` and for each one add a new color picker format property to the formatting model.
 
-To build a formatting model, the developer should be familiar with all its components. Check out the components of the format pane in [`Format Pane`](./format-pane.md). Check out `getFormattingModel` API of the [`FormattingModel utils`](./utils-formatting-model.md) in the [formatting model utils repository](https://github.com/microsoft/powerbi-visuals-utils-formattingmodel).
+To build a formatting model, the developer should be familiar with all its components. Check out the components of the format pane in [`Format Pane`](./format-pane-general.md). Check out `getFormattingModel` API of the [`FormattingModel utils`](./utils-formatting-model.md) in the [formatting model utils repository](https://github.com/microsoft/powerbi-visuals-utils-formattingmodel).
 
 [Download the file](https://github.com/microsoft/PowerBI-visuals-sampleBarChart/blob/main/src/barChartSettingsModel.ts) and save it to the */src* folder.
 Declare formatting properties and their values in a formatting settings class:

powerbi-docs/developer/visuals/custom-visual-develop-tutorial-format-options.md

@@ -234,10 +234,11 @@ For tips about debugging your custom visual, see the [debugging guide](visuals-h
 
 Now that the visual is completed and ready to be used, it's time to package it. A packaged visual can be imported to Power BI reports or service to be used and enjoyed by others.
 
-When your visual is ready, follow the directions in [Package a Power BI visual](./package-visual.md) and then, if you want, share it with others so they can [import](./import-visual.md) and enjoy it. 
+When your visual is ready, follow the directions in [Package a Power BI visual](./package-visual.md) and then, if you want, share it with others so they can [import](./import-visual.md) and enjoy it.
 
 ## Related content
 
+* [Learn more about the new Format Pane](format-pane-general.md)
 * [Create a Power BI bar chart visual](create-bar-chart.md)
 * [Learn how to debug a Power BI visual you created](visuals-how-to-debug.md)
 * [Power BI visuals project structure](visual-project-structure.md)

powerbi-docs/developer/visuals/format-pane.md → powerbi-docs/developer/visuals/format-pane-example.md

@@ -11,210 +11,15 @@ ms.date: 12/12/2023
 #customer intent: As a custom Power BI visual developer, I want to learn how to customize the new Format pane in Power BI custom visuals using the new formatting model so that I can create visuals that are easier for report creators to use.
 ---
 
-# Customize the format pane in Power BI custom visuals
+# Add the new format pane to a custom visual using API
 
-Starting from API version 5.1, developers can create visuals that use the [new Power format pane](../../fundamentals/desktop-format-pane.md). Developers can define the cards and their categories for any property in their custom visual, making it easier for report creators to use these visuals.
+> [!IMPORTANT]
+> To add the new Format pane to a custom visual, we recommend using [**formattingmodel utils**](./utils-formatting-model.md).
 
-The new API uses the **FormattingModel** method to customize parts of the format and analytics panes.
+Although we recommend using [formattingmodel utils](./utils-formatting-model.md) with the new format pane, this example demonstrates how to build a custom visual formatting model with one card using only the API.
 
-> [!TIP]
-> The `getFormattingModel` method replaces the `enumerateObjectInstances` method in earlier API versions.
-
-The `getFormattingModel` returns a `FormattingModel` that defines how the visual's formatting and analytics pane look.
-
-In addition to all the old formatting pane capabilities, the [new formatting model](#formatting-model) supports new format pane capabilities, new properties and new hierarchies.
-
-:::image type="content" source="media/format-pane/formatting-model.png" alt-text="Screenshot of the new formatting pane.":::
-
-To upgrade to API version 5.1+, set the `apiVersion` in your *pbiviz.json* file to `5.1` or later and do **one** of the following:
-
-* Use [formattingmodel util](./utils-formatting-model.md). (**Recommended**)
-* Without this util, use only APIs according to the following method.
-
-## Create a visual that supports the new format pane
-
-To create a custom visual that uses the new format pane:
-
-1. Define all the customizable [`objects`](./objects-properties.md) in your *capabilities.json* file.  
-   The following properties are required for each object:
-
-   * object name
-   * property name
-   * property type
-
-   All other properties, including `DisplayName` and `description`, are now optional.
-
-2. Build the custom visual [**FormattingModel**](#formatting-model).
-  Define the properties of your custom visual formatting model and build it using code (not JSON).
-
-3. Implement the `getFormattingModel` API in the custom visual class that returns custom visual formatting model. (This API replaces the `enumerateObjectInstances` that was used in previous versions).
-
-## Map formatting properties
-
-If you have a custom visual created with an older API and you want to migrate to the new format pane, or if you're creating a new custom visual:
-
-1. Set the `apiVersion` in your *pbiviz.json* file to `5.1` or later.
-
-2. For each object name and property name in *capabilities.json*, create a matching formatting property. The formatting property should have a descriptor that contains an `objectName` and `propertyName` that matches the object name and property name in *capabilities.json*.
-
-The `objects` properties in the capabilities file still have the same format and don't need to be changed.
-
-For example, if the `circle` object in your *capabilities.json* file is defined like this:
-
-```json
-"objects": {
-    "circle": {
-        "properties": {
-            "circleColor": {
-                "type": {
-                    "fill": {
-                        "solid": {
-                            "color": true
-                        }
-                    }
-                  }
-          },
-        }
-      }
-    }
-```
-
-The formatting property in your model should be of type `ColorPicker` and look like this:
-
-```javascript
-control: {
-    type: "ColorPicker",
-    properties: {
-        descriptor: {
-            objectName: "circle",
-            propertyName: "circleColor"
-        },
-        value: {
-            value: this.visualSettings.circle.circleColor
-        }
-    }
-}
-```
-
-You'll get an error if one of the following conditions is true:
-
-* The object or property name in the capabilities file doesn’t match the one in the formatting model
-* The property type in the capabilities file doesn’t match the type in formatting model
-
-## Formatting model
-
-The formatting model is where you describe and customize all the properties of your format pane.
-
-### Formatting model components
-
-In the new formatting model, property components are grouped together in logical categories and subcategories. These groups make the model easier to scan. There are the five basic components, from largest to smallest:
-
-* **Formatting model**  
-  The largest pane container, used for formatting the pane's frontal interface. It contains a list of formatting cards.
-
-* **Formatting card**  
-  The top level properties grouping container for formatting properties. Each card consists of one or more formatting groups, as shown here.
-
-  :::image type="content" source="./media/format-pane/formatting-cards.png" alt-text="Screenshot of formatting model with individual formatting cards.":::
-
-* **Formatting group**  
-  The secondary-level properties grouping container. The formatting group is displayed as a grouping container for formatting slices.
-
-  :::image type="content" source="./media/format-pane/formatting-groups.png" alt-text="Screenshot of formatting cards divided into formatting groups.":::
-
-* **Formatting slice**  
-  Property container. There are two types of slices:
-
-  * Simple slice: Individual property container
-  * [Composite slice](#composite-slice-properties): Multiple related property containers grouped into one formatting slice
-
-  The following image shows the different types of slices. "Font" is a composite slice consisting of font family, size, and bold, italics and underline switches. "Color", "display units" and the other slices are simple slices with one component each.
-
-  :::image type="content" source="./media/format-pane/format-pane-slices.png" alt-text="Screenshot of format pane composite and simple slices.":::
-
-### Visualization pane formatting properties
-
-Every property in the formatting model should match and object type in the *capabilities.json* file.
-
-The following table shows the formatting property types in *capabilities.json* file and their matching type class in modern formatting model properties:
-
-| Type             | Capabilities Value Type | Formatting Property  |
-|------------------|-------------------------|----------------------|
-| Boolean          | Bool                    | ToggleSwitch         |
-| Number           | <li>numeric</li> <li> integer </li>       | <li> NumUpDown </li> <li>Slider</li>     |
-| Enumeration list | enumeration:[]          | <li> ItemDropdown</li> <li> ItemFlagsSelection</li><li> AutoDropdown</li><li> AutoFlagsSelection</li> <sup>*</sup> See note below       |
-| Color            | Fill                    | ColorPicker          |
-| Gradient         | FillRule                | GradientBar: property value should be string consisting of: </n>`minValue[,midValue],maxValue`          |
-| Text             | Text                    | <li>TextInput</li> <li>TextArea</li>  |
-
-Capabilities Formatting Objects
-
-| Type             | Capabilities Value Type | Formatting Property  |
-|------------------|-------------------------|----------------------|
-| Font size           | FontSize             | NumUpDown            |
-| Font family         | FontFamily           | FontPicker           |
-| Line Alignment      | Alignment            | AlignmentGroup       |
-| Label Display Units | LabelDisplayUnits    | AutoDropDown         |
-
-<sup>*</sup> The enumeration list formatting property is different in the formatting model and in the capabilities file.
-
-* Declare the following properties in the formatting settings class, including the list of enumeration items:
-
-  * ItemDropdown
-  * ItemFlagsSelection  
-
-* Declare the following properties in the formatting settings class, without the list of enumeration items. Declare their enumeration items list in *capabilities.json* under the appropriate object. (These types are the same as in the previous API versions):
-
-  * AutoDropdown
-  * AutoFlagSelection  
-
-### Composite slice properties
-
-A formatting composite slice is a formatting slice that contains multiple related properties all together.
-
-For now we have two composite slice types:
-
-* FontControl  
-  This keeps all font related properties together. It consists of the following properties:
-
-  * Font Family
-  * Font Size
-  * Bold [optional]
-  * Italic [optional]
-  * Underline [optional]
-
-  :::image type="content" source="media/format-pane/font-slices.png" alt-text="Screenshot of font composite slice with font family, font size, bold, italic, and underline options.":::
-
-  Each of these properties should have a corresponding object in capabilities file:
-
-  | Property    | Capabilities Type         | Formatting Type  |
-  |-------------|---------------------------|------------------|
-  | Font Family | Formatting: { fontFamily} | FontPicker       |
-  | Font Size   | Formatting: {fontSize}    | NumUpDown        |
-  | Bold        | Bool                      | ToggleSwitch     |
-  | Italic      | Bool                      | ToggleSwitch     |
-  | Underline   | Bool                      | ToggleSwitch     |
-
-* MarginPadding
-  Margin padding determines the alignment of the text in the visual. It consists of the following properties:
-
-  * Left
-  * Right
-  * Top
-  * Bottom
-
-  Each of these properties should have a corresponding object in capabilities file:
-
-  | Property    | Capabilities Type         | Formatting Type  |
-  |-------------|---------------------------|------------------|
-  | Left        | Numeric                   | NumUpDown        |
-  | Right       | Numeric                   | NumUpDown        |
-  | Top         | Numeric                   | NumUpDown        |
-  | Bottom      | Numeric                   | NumUpDown        |
-
 ## Example: Formatting a data card
 
-In this example, we show how to build a custom visual formatting model with one card.  
 The card has two groups:
 
 * **Font control group** with one composite property