[excel] (PivotTable) Adding PivotTable summary samples (#340)

* Adding PivotTable summary samples

* Fix typos

* Apply suggestions from code review

Co-authored-by: Alison McKay <[email protected]>

---------

Co-authored-by: Alison McKay <[email protected]>

Author: AlexJerabek

docs/docs-ref-autogen/excel/excelscript/excelscript.datapivothierarchy.yml

@@ -189,7 +189,30 @@ methods:
           type: '<xref uid="ExcelScript!ExcelScript.ShowAsRule:interface" />'
       return:
         type: void
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * The script changes the display for "Crates Sold at Farm".
+           * It shows the percentage of the grand total, 
+           * instead of the default sum.
+           */
+          function main(workbook: ExcelScript.Workbook) {
+            // Get the PivotTable named "Farm Pivot".
+            const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+            // Get the data hierarchy "Sum of Crates Sold at Farm".
+            const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+            // Show the data as a percentage of the grand total.
+            farmSales.setShowAs({
+              calculation: ExcelScript.ShowAsCalculation.percentOfGrandTotal
+            });
+          }
+          ```
   - name: setSummarizeBy(summarizeBy)
     uid: 'ExcelScript!ExcelScript.DataPivotHierarchy#setSummarizeBy:member(1)'
     package: ExcelScript!

docs/docs-ref-autogen/excel/excelscript/excelscript.showascalculation.yml

@@ -4,7 +4,30 @@ uid: 'ExcelScript!ExcelScript.ShowAsCalculation:enum'
 package: ExcelScript!
 fullName: ExcelScript.ShowAsCalculation
 summary: The ShowAs calculation function for the DataPivotField.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * The script changes the display for "Crates Sold at Farm".
+   * It shows the percentage of the grand total, 
+   * instead of the default sum.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the PivotTable named "Farm Pivot".
+    const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+    // Get the data hierarchy "Sum of Crates Sold at Farm".
+    const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+    // Show the data as a percentage of the grand total.
+    farmSales.setShowAs({
+      calculation: ExcelScript.ShowAsCalculation.percentOfGrandTotal
+    });
+  }
+  ```
 isPreview: false
 isDeprecated: false
 fields:

docs/docs-ref-autogen/excel/excelscript/excelscript.showasrule.yml

@@ -4,7 +4,41 @@ uid: 'ExcelScript!ExcelScript.ShowAsRule:interface'
 package: ExcelScript!
 fullName: ExcelScript.ShowAsRule
 summary: ''
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * The script changes the display for "Crates Sold at Farm".
+   * The field shows each value's difference
+   * from the value of the "Lemon" in the same row.
+   * If the row has no value for "Lemon", the field shows "#N/A".
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the PivotTable named "Farm Pivot".
+    const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+    // Get the data hierarchy "Sum of Crates Sold at Farm".
+    const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+    // Get the row hierarchy "Type".
+    const typeField = farmPivot.getRowHierarchy("Type").getFields()[0];
+
+    // Change the data hierarchy to show each value as the difference
+    // from the value of the "Lemon" in that row.
+    const rule: ExcelScript.ShowAsRule = {
+      calculation: ExcelScript.ShowAsCalculation.differenceFrom,
+      baseField: typeField,
+      baseItem: typeField.getPivotItem("Lemon")
+    }
+    farmSales.setShowAs(rule);
+
+    // Set the name of the field to match the new behavior.
+    farmSales.setName("Difference from Lemons of Crates Sold at Farm");
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

docs/sample-scripts/excel-scripts.yaml

@@ -1691,6 +1691,25 @@
       const dataHierarchy = pivotTable.getDataHierarchies()[0];
       dataHierarchy.setSummarizeBy(ExcelScript.AggregationFunction.average);
     }
+'ExcelScript.DataPivotHierarchy#setShowAs:member(1)':
+  - |-
+    /**
+     * The script changes the display for "Crates Sold at Farm".
+     * It shows the percentage of the grand total, 
+     * instead of the default sum.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the PivotTable named "Farm Pivot".
+      const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+      // Get the data hierarchy "Sum of Crates Sold at Farm".
+      const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+      // Show the data as a percentage of the grand total.
+      farmSales.setShowAs({
+        calculation: ExcelScript.ShowAsCalculation.percentOfGrandTotal
+      });
+    }
 'ExcelScript.DataValidation#getType:member(1)':
   - |-
     /**
@@ -5293,6 +5312,55 @@
         worksheet.setVisibility(ExcelScript.SheetVisibility.visible);
       });
     }
+'ExcelScript.ShowAsCalculation:enum':
+  - |-
+    /**
+     * The script changes the display for "Crates Sold at Farm".
+     * It shows the percentage of the grand total, 
+     * instead of the default sum.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the PivotTable named "Farm Pivot".
+      const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+      // Get the data hierarchy "Sum of Crates Sold at Farm".
+      const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+      // Show the data as a percentage of the grand total.
+      farmSales.setShowAs({
+        calculation: ExcelScript.ShowAsCalculation.percentOfGrandTotal
+      });
+    }
+'ExcelScript.ShowAsRule:interface':
+  - |-
+    /**
+     * The script changes the display for "Crates Sold at Farm".
+     * The field shows each value's difference
+     * from the value of the "Lemon" in the same row.
+     * If the row has no value for "Lemon", the field shows "#N/A".
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the PivotTable named "Farm Pivot".
+      const farmPivot = workbook.getPivotTable("Farm Pivot");
+
+      // Get the data hierarchy "Sum of Crates Sold at Farm".
+      const farmSales = farmPivot.getDataHierarchy("Sum of Crates Sold at Farm");
+
+      // Get the row hierarchy "Type".
+      const typeField = farmPivot.getRowHierarchy("Type").getFields()[0];
+
+      // Change the data hierarchy to show each value as the difference
+      // from the value of the "Lemon" in that row.
+      const rule: ExcelScript.ShowAsRule = {
+        calculation: ExcelScript.ShowAsCalculation.differenceFrom,
+        baseField: typeField,
+        baseItem: typeField.getPivotItem("Lemon")
+      }
+      farmSales.setShowAs(rule);
+
+      // Set the name of the field to match the new behavior.
+      farmSales.setName("Difference from Lemons of Crates Sold at Farm");
+    }
 'ExcelScript.Slicer:interface':
   - |-
     /**

generate-docs/API Coverage Report.csv

@@ -1368,7 +1368,7 @@ ExcelScript.DataPivotHierarchy,"getSummarizeBy()",Method,Poor,false
 ExcelScript.DataPivotHierarchy,"setName(name)",Method,Poor,false
 ExcelScript.DataPivotHierarchy,"setNumberFormat(numberFormat)",Method,Poor,false
 ExcelScript.DataPivotHierarchy,"setPosition(position)",Method,Poor,false
-ExcelScript.DataPivotHierarchy,"setShowAs(showAs)",Method,Poor,false
+ExcelScript.DataPivotHierarchy,"setShowAs(showAs)",Method,Poor,true
 ExcelScript.DataPivotHierarchy,"setSummarizeBy(summarizeBy)",Method,Poor,true
 ExcelScript.DataPivotHierarchy,"setToDefault()",Method,Poor,false
 ExcelScript.DataValidation,N/A,Class,Fine,false
@@ -2848,7 +2848,7 @@ ExcelScript.SheetVisibility,N/A,Enum,Missing,true
 ExcelScript.SheetVisibility,"hidden",EnumField,Missing,false
 ExcelScript.SheetVisibility,"veryHidden",EnumField,Missing,false
 ExcelScript.SheetVisibility,"visible",EnumField,Missing,false
-ExcelScript.ShowAsCalculation,N/A,Enum,Fine,false
+ExcelScript.ShowAsCalculation,N/A,Enum,Fine,true
 ExcelScript.ShowAsCalculation,"differenceFrom",EnumField,Fine,false
 ExcelScript.ShowAsCalculation,"index",EnumField,Fine,false
 ExcelScript.ShowAsCalculation,"none",EnumField,Poor,false
@@ -2865,7 +2865,7 @@ ExcelScript.ShowAsCalculation,"rankAscending",EnumField,Fine,false
 ExcelScript.ShowAsCalculation,"rankDecending",EnumField,Fine,false
 ExcelScript.ShowAsCalculation,"runningTotal",EnumField,Fine,false
 ExcelScript.ShowAsCalculation,"unknown",EnumField,Poor,false
-ExcelScript.ShowAsRule,N/A,Class,Missing,false
+ExcelScript.ShowAsRule,N/A,Class,Missing,true
 ExcelScript.ShowAsRule,"baseField",Property,Fine,false
 ExcelScript.ShowAsRule,"baseItem",Property,Fine,false
 ExcelScript.ShowAsRule,"calculation",Property,Good,false