[excel] (Formatting, Worksheet) Add search and custom format samples (#355)

* Add conditional formatting and worksheet search samples

* Run generate docs

Author: AlexJerabek

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

@@ -4,7 +4,32 @@ uid: 'ExcelScript!ExcelScript.ConditionalFormatRule:interface'
 package: ExcelScript!
 fullName: ExcelScript.ConditionalFormatRule
 summary: 'Represents a rule, for all traditional rule/format pairings.'
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script applies a custom conditional formatting to the selected range.
+   * A light-green fill is applied to a cell if the value is larger than the value in the row's previous column.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the selected cells.
+    let selectedRange = workbook.getSelectedRange();
+
+    // Apply a rule for positive change from the previous column.
+    let positiveChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+
+    // Set the conditional format to be a lightgreen fill.
+    let positiveCustom: ExcelScript.CustomConditionalFormat = positiveChange.getCustom();
+    positiveCustom.getFormat().getFill().setColor("lightgreen");
+
+    // Set the conditional rule to be if there is positive change across the row.
+    let positiveRule: ExcelScript.ConditionalFormatRule = positiveCustom.getRule();
+    positiveRule.setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -19,19 +19,22 @@ remarks: |-
     let selectedRange = workbook.getSelectedRange();
 
     // Apply a rule for positive change from the previous column.
-    let positiveChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-    positiveChange.getCustom().getFormat().getFill().setColor("lightgreen");
-    positiveChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+    let positiveChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+    let positiveCustom: ExcelScript.CustomConditionalFormat = positiveChange.getCustom();
+    positiveCustom.getFormat().getFill().setColor("lightgreen");
+    positiveCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
 
     // Apply a rule for negative change from the previous column.
-    let negativeChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-    negativeChange.getCustom().getFormat().getFill().setColor("pink");
-    negativeChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}<${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+    let negativeChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+    let negativeCustom: ExcelScript.CustomConditionalFormat = negativeChange.getCustom();
+    negativeCustom.getFormat().getFill().setColor("pink");
+    negativeCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}<${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
 
     // Apply a rule for no change from the previous column.
-    let noChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-    noChange.getCustom().getFormat().getFill().setColor("lightyellow");
-    noChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}=${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+    let sameChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+    let sameCustom: ExcelScript.CustomConditionalFormat = sameChange.getCustom();
+    sameCustom.getFormat().getFill().setColor("lightyellow");
+    sameCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}=${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
   }
   ```
 isPreview: false

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

@@ -792,7 +792,7 @@ methods:
           ```TypeScript
           /**
            * This script searches through a worksheet and finds cells containing "No". 
-           * Those cells are filled red.
+           * Those cells are filled with the color red.
            * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
            */
           function main(workbook: ExcelScript.Workbook) {

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

@@ -4,7 +4,32 @@ uid: 'ExcelScript!ExcelScript.WorksheetSearchCriteria:interface'
 package: ExcelScript!
 fullName: ExcelScript.WorksheetSearchCriteria
 summary: Represents the worksheet search criteria to be used.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script searches through a worksheet and finds cells containing "No". 
+   * Those cells are filled with the color red.
+   * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the current, active worksheet.
+    const worksheet = workbook.getActiveWorksheet();
+
+    // Get all the cells that exactly contain the string "No".
+    const searchCriteria: ExcelScript.WorksheetSearchCriteria = { 
+      completeMatch: true,
+      matchCase: true
+    };
+    const noCells = worksheet.findAll("No", searchCriteria);
+
+    // Set the fill color to red.
+    noCells.getFormat().getFill().setColor("red");
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

docs/sample-scripts/excel-scripts.yaml

@@ -1250,6 +1250,27 @@
       };
       presetFormat.setRule(duplicateRule);
     }
+'ExcelScript.ConditionalFormatRule:interface':
+  - |-
+    /**
+     * This script applies a custom conditional formatting to the selected range.
+     * A light-green fill is applied to a cell if the value is larger than the value in the row's previous column.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the selected cells.
+      let selectedRange = workbook.getSelectedRange();
+
+      // Apply a rule for positive change from the previous column.
+      let positiveChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+
+      // Set the conditional format to be a lightgreen fill.
+      let positiveCustom: ExcelScript.CustomConditionalFormat = positiveChange.getCustom();
+      positiveCustom.getFormat().getFill().setColor("lightgreen");
+
+      // Set the conditional rule to be if there is positive change across the row.
+      let positiveRule: ExcelScript.ConditionalFormatRule = positiveCustom.getRule();
+      positiveRule.setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+    }
 'ExcelScript.ConditionalFormatRuleType:enum':
   - |-
     /**
@@ -1640,19 +1661,22 @@
       let selectedRange = workbook.getSelectedRange();
 
       // Apply a rule for positive change from the previous column.
-      let positiveChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-      positiveChange.getCustom().getFormat().getFill().setColor("lightgreen");
-      positiveChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+      let positiveChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+      let positiveCustom: ExcelScript.CustomConditionalFormat = positiveChange.getCustom();
+      positiveCustom.getFormat().getFill().setColor("lightgreen");
+      positiveCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}>${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
 
       // Apply a rule for negative change from the previous column.
-      let negativeChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-      negativeChange.getCustom().getFormat().getFill().setColor("pink");
-      negativeChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}<${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+      let negativeChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+      let negativeCustom: ExcelScript.CustomConditionalFormat = negativeChange.getCustom();
+      negativeCustom.getFormat().getFill().setColor("pink");
+      negativeCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}<${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
 
       // Apply a rule for no change from the previous column.
-      let noChange = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
-      noChange.getCustom().getFormat().getFill().setColor("lightyellow");
-      noChange.getCustom().getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}=${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
+      let sameChange: ExcelScript.ConditionalFormat = selectedRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom);
+      let sameCustom: ExcelScript.CustomConditionalFormat = sameChange.getCustom();
+      sameCustom.getFormat().getFill().setColor("lightyellow");
+      sameCustom.getRule().setFormula(`=${selectedRange.getCell(0, 0).getAddress()}=${selectedRange.getOffsetRange(0, -1).getCell(0, 0).getAddress()}`);
     }
 'ExcelScript.CustomDataValidation:interface':
   - |-
@@ -6748,7 +6772,7 @@
  - |-
     /**
      * This script searches through a worksheet and finds cells containing "No". 
-     * Those cells are filled red.
+     * Those cells are filled with the color red.
      * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
      */
     function main(workbook: ExcelScript.Workbook) {
@@ -7006,4 +7030,25 @@
 
       // Apply the given protection options.
       sheetProtection.protect(protectionOptions);
+    }
+'ExcelScript.WorksheetSearchCriteria:interface':
+ - |-
+    /**
+     * This script searches through a worksheet and finds cells containing "No". 
+     * Those cells are filled with the color red.
+     * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the current, active worksheet.
+      const worksheet = workbook.getActiveWorksheet();
+
+      // Get all the cells that exactly contain the string "No".
+      const searchCriteria: ExcelScript.WorksheetSearchCriteria = { 
+        completeMatch: true,
+        matchCase: true
+      };
+      const noCells = worksheet.findAll("No", searchCriteria);
+
+      // Set the fill color to red.
+      noCells.getFormat().getFill().setColor("red");
     }

generate-docs/API Coverage Report.csv

@@ -1213,7 +1213,7 @@ ExcelScript.ConditionalFormatPresetCriterion,"twoStdDevAboveAverage",EnumField,M
 ExcelScript.ConditionalFormatPresetCriterion,"twoStdDevBelowAverage",EnumField,Missing,false
 ExcelScript.ConditionalFormatPresetCriterion,"uniqueValues",EnumField,Missing,false
 ExcelScript.ConditionalFormatPresetCriterion,"yesterday",EnumField,Missing,false
-ExcelScript.ConditionalFormatRule,N/A,Class,Fine,false
+ExcelScript.ConditionalFormatRule,N/A,Class,Fine,true
 ExcelScript.ConditionalFormatRule,"getFormula()",Method,Poor,false
 ExcelScript.ConditionalFormatRule,"getFormulaLocal()",Method,Poor,false
 ExcelScript.ConditionalFormatRule,"setFormula(formula)",Method,Poor,false
@@ -3340,6 +3340,6 @@ ExcelScript.WorksheetProtectionOptions,"allowInsertRows",Property,Fine,false
 ExcelScript.WorksheetProtectionOptions,"allowPivotTables",Property,Fine,false
 ExcelScript.WorksheetProtectionOptions,"allowSort",Property,Fine,false
 ExcelScript.WorksheetProtectionOptions,"selectionMode",Property,Fine,false
-ExcelScript.WorksheetSearchCriteria,N/A,Class,Fine,false
+ExcelScript.WorksheetSearchCriteria,N/A,Class,Fine,true
 ExcelScript.WorksheetSearchCriteria,"completeMatch",Property,Good,false
 ExcelScript.WorksheetSearchCriteria,"matchCase",Property,Good,false