[excel] (Range, PivotTable) Add FilterPivotHierarchy and ConditionalFormat samples (#325)

* Add FitlerPivotHierarchy samples

* PR feedback

Author: AlexJerabek

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

@@ -4,7 +4,39 @@ uid: 'ExcelScript!ExcelScript.ConditionalRangeFill:interface'
 package: ExcelScript!
 fullName: ExcelScript.ConditionalRangeFill
 summary: Represents the background of a conditional range object.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script applies cell value conditional formatting to a range.
+   * Any value less than 60 will have the cell's fill color changed and the font made italic.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the range to format.
+    const selectedRange = workbook.getSelectedRange();
+
+    // Add cell value conditional formatting.
+    const cellValueConditionalFormatting =
+      selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+    // Create the condition, in this case when the cell value is less than 60.
+    const rule: ExcelScript.ConditionalCellValueRule = {
+      formula1: "60",
+      operator: ExcelScript.ConditionalCellValueOperator.lessThan
+    };
+    cellValueConditionalFormatting.setRule(rule);
+
+    // Set the format to apply when the condition is met.
+    const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+    const fill: ExcelScript.ConditionalRangeFill = format.getFill();
+    const font: ExcelScript.ConditionalRangeFont = format.getFont();
+    fill.setColor("yellow");
+    font.setItalic(true);
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -4,7 +4,39 @@ uid: 'ExcelScript!ExcelScript.ConditionalRangeFont:interface'
 package: ExcelScript!
 fullName: ExcelScript.ConditionalRangeFont
 summary: 'This object represents the font attributes (font style, color, etc.) for an object.'
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script applies cell value conditional formatting to a range.
+   * Any value less than 60 will have the cell's fill color changed and the font made italic.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the range to format.
+    const selectedRange = workbook.getSelectedRange();
+
+    // Add cell value conditional formatting.
+    const cellValueConditionalFormatting =
+      selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+    // Create the condition, in this case when the cell value is less than 60.
+    const rule: ExcelScript.ConditionalCellValueRule = {
+      formula1: "60",
+      operator: ExcelScript.ConditionalCellValueOperator.lessThan
+    };
+    cellValueConditionalFormatting.setRule(rule);
+
+    // Set the format to apply when the condition is met.
+    const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+    const fill: ExcelScript.ConditionalRangeFill = format.getFill();
+    const font: ExcelScript.ConditionalRangeFont = format.getFont();
+    fill.setColor("yellow");
+    font.setItalic(true);
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -4,7 +4,37 @@ uid: 'ExcelScript!ExcelScript.ConditionalRangeFormat:interface'
 package: ExcelScript!
 fullName: ExcelScript.ConditionalRangeFormat
 summary: 'A format object encapsulating the conditional formats range''s font, fill, borders, and other properties.'
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script applies cell value conditional formatting to a range.
+   * Any value less than 60 will have the cell's fill color changed and the font made italic.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the range to format.
+    const selectedRange = workbook.getSelectedRange();
+
+    // Add cell value conditional formatting.
+    const cellValueConditionalFormatting =
+      selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+    // Create the condition, in this case when the cell value is less than 60.
+    const rule: ExcelScript.ConditionalCellValueRule = {
+      formula1: "60",
+      operator: ExcelScript.ConditionalCellValueOperator.lessThan
+    };
+    cellValueConditionalFormatting.setRule(rule);
+
+    // Set the format to apply when the condition is met.
+    const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+    format.getFill().setColor("yellow");
+    format.getFont().setItalic(true);
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -4,7 +4,33 @@ uid: 'ExcelScript!ExcelScript.FilterPivotHierarchy:interface'
 package: ExcelScript!
 fullName: ExcelScript.FilterPivotHierarchy
 summary: Represents the Excel FilterPivotHierarchy.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script creates a PivotTable with a filter.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the two worksheets to use in PivotTable creation.
+    const dataSheet = workbook.getWorksheet("Data");
+    const pivotSheet = workbook.getWorksheet("Pivot");
+
+    // Create a new PivotTable.
+    const newPivot = pivotSheet.addPivotTable(
+      "My PivotTable", 
+      dataSheet.getUsedRange(), 
+      pivotSheet.getRange("A1"));
+
+    // Add a filter with the Quarter field.
+    const filter: ExcelScript.FilterPivotHierarchy = 
+      newPivot.addFilterHierarchy(newPivot.getHierarchy("Quarter"));
+
+    // Add other hierarchies...
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface
@@ -60,7 +86,25 @@ methods:
       content: 'getName(): string;'
       return:
         type: string
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script logs the names of all the filter hierarchies in a PivotTable.
+           */
+          function main(workbook: ExcelScript.Workbook) {
+              // Get the first PivotTable in the workbook.
+              const pivotTable = workbook.getPivotTables()[0];
+
+              // For each pivot filter, log its name.
+              pivotTable.getFilterHierarchies().forEach((filter: ExcelScript.FilterPivotHierarchy) => {
+                console.log(filter.getName());
+              });
+          }
+          ```
   - name: getPivotField(name)
     uid: 'ExcelScript!ExcelScript.FilterPivotHierarchy#getPivotField:member(1)'
     package: ExcelScript!

docs/sample-scripts/excel-scripts.yaml

@@ -1374,6 +1374,88 @@
       };
       presetFormat.setRule(duplicateRule);
     }
+'ExcelScript.ConditionalRangeFill:interface':
+  - |-
+    /**
+     * This script applies cell value conditional formatting to a range.
+     * Any value less than 60 will have the cell's fill color changed and the font made italic.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the range to format.
+      const selectedRange = workbook.getSelectedRange();
+
+      // Add cell value conditional formatting.
+      const cellValueConditionalFormatting =
+        selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+      // Create the condition, in this case when the cell value is less than 60.
+      const rule: ExcelScript.ConditionalCellValueRule = {
+        formula1: "60",
+        operator: ExcelScript.ConditionalCellValueOperator.lessThan
+      };
+      cellValueConditionalFormatting.setRule(rule);
+
+      // Set the format to apply when the condition is met.
+      const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+      const fill: ExcelScript.ConditionalRangeFill = format.getFill();
+      const font: ExcelScript.ConditionalRangeFont = format.getFont();
+      fill.setColor("yellow");
+      font.setItalic(true);
+    }
+'ExcelScript.ConditionalRangeFont:interface':
+  - |-
+    /**
+     * This script applies cell value conditional formatting to a range.
+     * Any value less than 60 will have the cell's fill color changed and the font made italic.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the range to format.
+      const selectedRange = workbook.getSelectedRange();
+
+      // Add cell value conditional formatting.
+      const cellValueConditionalFormatting =
+        selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+      // Create the condition, in this case when the cell value is less than 60.
+      const rule: ExcelScript.ConditionalCellValueRule = {
+        formula1: "60",
+        operator: ExcelScript.ConditionalCellValueOperator.lessThan
+      };
+      cellValueConditionalFormatting.setRule(rule);
+
+      // Set the format to apply when the condition is met.
+      const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+      const fill: ExcelScript.ConditionalRangeFill = format.getFill();
+      const font: ExcelScript.ConditionalRangeFont = format.getFont();
+      fill.setColor("yellow");
+      font.setItalic(true);
+    }
+'ExcelScript.ConditionalRangeFormat:interface':
+  - |-
+    /**
+     * This script applies cell value conditional formatting to a range.
+     * Any value less than 60 will have the cell's fill color changed and the font made italic.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the range to format.
+      const selectedRange = workbook.getSelectedRange();
+
+      // Add cell value conditional formatting.
+      const cellValueConditionalFormatting =
+        selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue();
+
+      // Create the condition, in this case when the cell value is less than 60.
+      const rule: ExcelScript.ConditionalCellValueRule = {
+        formula1: "60",
+        operator: ExcelScript.ConditionalCellValueOperator.lessThan
+      };
+      cellValueConditionalFormatting.setRule(rule);
+
+      // Set the format to apply when the condition is met.
+      const format: ExcelScript.ConditionalRangeFormat = cellValueConditionalFormatting.getFormat();
+      format.getFill().setColor("yellow");
+      format.getFont().setItalic(true);
+    }
 'ExcelScript.ConditionalTextComparisonRule:interface':
   - |-
     /**
@@ -2345,6 +2427,44 @@
       // greater than 0 and less than or equal to 60.
       table.getColumnByName("Exam Score").getFilter().applyCustomFilter(">0", "<=60", ExcelScript.FilterOperator.and);
     }
+'ExcelScript.FilterPivotHierarchy:interface':
+  - |-
+    /**
+     * This script creates a PivotTable with a filter.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the two worksheets to use in PivotTable creation.
+      const dataSheet = workbook.getWorksheet("Data");
+      const pivotSheet = workbook.getWorksheet("Pivot");
+
+      // Create a new PivotTable.
+      const newPivot = pivotSheet.addPivotTable(
+        "My PivotTable", 
+        dataSheet.getUsedRange(), 
+        pivotSheet.getRange("A1"));
+
+      // Add a filter with the Quarter field.
+      const filter: ExcelScript.FilterPivotHierarchy = 
+        newPivot.addFilterHierarchy(newPivot.getHierarchy("Quarter"));
+
+      // Add other hierarchies...
+    }
+'ExcelScript.FilterPivotHierarchy#getName:member(1)':
+  - |-
+    /**
+     * This script logs the names of all the filter hierarchies in a PivotTable.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+        // Get the first PivotTable in the workbook.
+        const pivotTable = workbook.getPivotTables()[0];
+
+        // For each pivot filter, log its name.
+        pivotTable.getFilterHierarchies().forEach((filter: ExcelScript.FilterPivotHierarchy) => {
+          console.log(filter.getName());
+        });
+    }
+
+
 'ExcelScript.GeometricShapeType:enum':
   - |-
     /**

generate-docs/API Coverage Report.csv

@@ -1265,11 +1265,11 @@ ExcelScript.ConditionalRangeBorderLineStyle,"dashDot",EnumField,Missing,false
 ExcelScript.ConditionalRangeBorderLineStyle,"dashDotDot",EnumField,Missing,false
 ExcelScript.ConditionalRangeBorderLineStyle,"dot",EnumField,Missing,false
 ExcelScript.ConditionalRangeBorderLineStyle,"none",EnumField,Missing,false
-ExcelScript.ConditionalRangeFill,N/A,Class,Fine,false
+ExcelScript.ConditionalRangeFill,N/A,Class,Fine,true
 ExcelScript.ConditionalRangeFill,"clear()",Method,Poor,false
 ExcelScript.ConditionalRangeFill,"getColor()",Method,Poor,false
 ExcelScript.ConditionalRangeFill,"setColor(color)",Method,Poor,false
-ExcelScript.ConditionalRangeFont,N/A,Class,Fine,false
+ExcelScript.ConditionalRangeFont,N/A,Class,Fine,true
 ExcelScript.ConditionalRangeFont,"clear()",Method,Poor,false
 ExcelScript.ConditionalRangeFont,"getBold()",Method,Poor,false
 ExcelScript.ConditionalRangeFont,"getColor()",Method,Poor,false
@@ -1285,7 +1285,7 @@ ExcelScript.ConditionalRangeFontUnderlineStyle,N/A,Enum,Missing,false
 ExcelScript.ConditionalRangeFontUnderlineStyle,"double",EnumField,Missing,false
 ExcelScript.ConditionalRangeFontUnderlineStyle,"none",EnumField,Missing,false
 ExcelScript.ConditionalRangeFontUnderlineStyle,"single",EnumField,Missing,false
-ExcelScript.ConditionalRangeFormat,N/A,Class,Fine,false
+ExcelScript.ConditionalRangeFormat,N/A,Class,Fine,true
 ExcelScript.ConditionalRangeFormat,"getBorders()",Method,Poor,false
 ExcelScript.ConditionalRangeFormat,"getConditionalRangeBorder(index)",Method,Poor,false
 ExcelScript.ConditionalRangeFormat,"getConditionalRangeBorderBottom()",Method,Poor,false
@@ -1615,11 +1615,11 @@ ExcelScript.FilterOn,"values",EnumField,Missing,false
 ExcelScript.FilterOperator,N/A,Enum,Missing,true
 ExcelScript.FilterOperator,"and",EnumField,Missing,false
 ExcelScript.FilterOperator,"or",EnumField,Missing,false
-ExcelScript.FilterPivotHierarchy,N/A,Class,Poor,false
+ExcelScript.FilterPivotHierarchy,N/A,Class,Poor,true
 ExcelScript.FilterPivotHierarchy,"getEnableMultipleFilterItems()",Method,Poor,false
 ExcelScript.FilterPivotHierarchy,"getFields()",Method,Poor,false
 ExcelScript.FilterPivotHierarchy,"getId()",Method,Poor,false
-ExcelScript.FilterPivotHierarchy,"getName()",Method,Poor,false
+ExcelScript.FilterPivotHierarchy,"getName()",Method,Poor,true
 ExcelScript.FilterPivotHierarchy,"getPivotField(name)",Method,Poor,false
 ExcelScript.FilterPivotHierarchy,"getPosition()",Method,Poor,false
 ExcelScript.FilterPivotHierarchy,"setEnableMultipleFilterItems(enableMultipleFilterItems)",Method,Poor,false