[excel] (Formatting) Conditional formatting and user input sample (#642)

* Adding conditional formatting and parameter sample

* Add link to new sample from user input article

* Account for worksheet names with ! in them

* Add entry to sample list on the overview

* Apply suggestions from code review

Co-authored-by: Elizabeth Samuel <[email protected]>

---------

Co-authored-by: Elizabeth Samuel <[email protected]>

Author: AlexJerabek

docs/develop/user-input.md

@@ -113,3 +113,4 @@ When adding input parameters and return values, consider the following allowance
 
 - [Pass data to and from scripts in Power Automate](power-automate-parameters-returns.md)
 - [Run Office Scripts in Excel with buttons](script-buttons.md)
+- [Set conditional formatting for cross-column comparisons](../resources/samples/conditional-formatting-parameters.md)

docs/resources/samples/conditional-formatting-parameters.md

@@ -0,0 +1,92 @@
+---
+title: Set conditional formatting for cross-column comparisons
+description: Learn how to apply conditional formatting and get input from the user.
+ms.date: 09/07/2023
+ms.localizationpriority: medium
+---
+
+# Set conditional formatting for cross-column comparisons
+
+This sample shows how to apply conditional formatting to a range. The conditions used are comparing values to those in an adjacent column.  Additionally, this sample uses [parameters to get user input](../../develop/user-input.md). This lets the person running the script select the range, the type of comparison, and the colors.
+
+## Sample code: Set conditional formatting
+
+```TypeScript
+/**
+ * Formats a range on the current sheet based on values in an adjacent column.
+ * @param rangeAddress The A1-notation range to format.
+ * @param compareTo The adjacent column to compare against.
+ * @param colorIfGreater The color of the cell if the value is greater than the adjacent column.
+ * @param colorIfEqual The color of the cell if the value is equal to the adjacent column.
+ * @param colorIfLess The color of the cell if the value is less than the adjacent column.
+ */
+function main(
+  workbook: ExcelScript.Workbook,
+  rangeAddress: string, compareTo: "Left" | "Right",
+  colorIfGreater: "Red" | "Green" | "Yellow" | "None",
+  colorIfLess: "Red" | "Green" | "Yellow" | "None",
+  colorIfEqual: "Red" | "Green" | "Yellow" | "None"
+) {
+  // Get the specified range.
+  const selectedSheet = workbook.getActiveWorksheet();
+  const range = selectedSheet.getRange(rangeAddress);
+
+  // Remove old conditional formatting.
+  range.clearAllConditionalFormats();
+
+  // Get the address of the first adjacent cell of the adjacent column.
+  let adjacentColumn: string;
+  if (compareTo == "Left") {
+    adjacentColumn = range.getColumnsBefore().getCell(0, 0).getAddress();
+  } else {
+    adjacentColumn = range.getColumnsAfter().getCell(0, 0).getAddress();
+  }
+
+  // Remove the worksheet name from the address to create a relative formula.
+  let formula = "=$" + adjacentColumn.substring(adjacentColumn.lastIndexOf("!") + 1);
+
+  // Set the conditional formatting based on the user's color choices.
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfGreater, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.greaterThan);
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfEqual, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.equalTo);
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfLess, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.lessThan);
+}
+
+function setConditionalFormatting(
+  conditionalFormat: ExcelScript.CellValueConditionalFormat,
+   color: "Red" | "Green" | "Yellow" | "None", 
+   formula: string, 
+   operator: ExcelScript.ConditionalCellValueOperator
+) {
+  // Pick the fill and font colors based on the preset color choices.
+  if (color == "Red") {
+    conditionalFormat.getFormat().getFont().setColor("#9C0006");
+    conditionalFormat.getFormat().getFill().setColor("#FFC7CE");
+  } else if (color == "Green") {
+    conditionalFormat.getFormat().getFont().setColor("#001600");
+    conditionalFormat.getFormat().getFill().setColor("#C6EFCE");
+  } else if (color == "Yellow") {
+    conditionalFormat.getFormat().getFont().setColor("#9C5700");
+    conditionalFormat.getFormat().getFill().setColor("#FFEB9C");
+  } else { /* None */
+    return;
+  }
+
+  // Apply the conditional formatting.
+  conditionalFormat.setRule({ 
+    formula1: formula,
+    operator: operator
+  });
+}
+```

docs/resources/samples/samples-overview.md

@@ -30,6 +30,7 @@ This section contains [Office Scripts](../../overview/excel.md) based solutions
 | [JavaScript `Date` samples](javascript-dates.md) | A collection of samples that show how to translate between JavaScript and Excel date formats. |
 | [Record day-to-day changes in Excel and report them with a Power Automate flow](report-day-to-day-changes.md) | This sample uses a scheduled Power Automate flow to record daily readings and report the changes. |
 | [Row and column visibility samples](row-and-column-visibility.md) | A collection of samples that demonstrate how to show, hide, and freeze rows and columns. |
+| [Set conditional formatting for cross-column comparisons](conditional-formatting-parameters.md) | This sample applies formatting based on values in adjacent columns. It also gets user input through script parameters. |
 
 ## Beyond the basics
 
@@ -42,12 +43,12 @@ Check out the following end-to-end project that automates sample scenarios along
 | [Cross-reference workbooks](excel-cross-reference.md) | This sample uses Office Scripts and Power Automate to cross-reference and validate information in different workbooks. |
 | [Count blank rows in a specific sheet or in all sheets](count-blank-rows.md) | This sample detects if there are any blank rows in sheets where you anticipate data to be present and then report the blank row count for usage in a Power Automate flow. |
 | [Email chart and table images](email-images-chart-table.md) | This sample uses Office Scripts and Power Automate actions to create a chart and send that chart as an image by email. |
-| [External fetch calls](external-fetch-calls.md) | This sample uses `fetch` to get information from GitHub for the script. |
 | [Manage calculation mode in Excel](excel-calculation.md) | This sample shows how to use the calculation mode and calculate methods in Excel using Office Scripts. |
 | [Move rows across tables](move-rows-across-tables.md) | This sample shows how to move rows across tables by saving filters, then processing and reapplying the filters. |
 | [Output Excel data as JSON](get-table-data.md) | This solution shows how to output Excel table data as JSON to use in Power Automate. |
 | [Remove hyperlinks from each cell in an Excel worksheet](remove-hyperlinks-from-cells.md) | This sample clears all of the hyperlinks from the current worksheet. |
 | [Run a script on all Excel files in a folder](automate-tasks-on-all-excel-files-in-folder.md) | This project performs a set of automation tasks on all files situated in a folder on OneDrive for Business (can also be used for a SharePoint folder). It performs calculations on the Excel files, adds formatting, and inserts a comment that @mentions a colleague. |
+| [Use external fetch calls](external-fetch-calls.md) | This sample uses `fetch` to get information from GitHub for the script. |
 | [Write a large dataset](write-large-dataset.md) | This sample shows how to send a large range as smaller subranges. |
 
 ## Scenarios

docs/toc.yml

@@ -90,6 +90,8 @@ items:
         href: resources/samples/report-day-to-day-changes.md
       - name: Row and column visibility
         href: resources/samples/row-and-column-visibility.md
+      - name: Set conditional formatting for cross-column comparisons
+        href: resources/samples/conditional-formatting-parameters.md
     - name: Beyond the basics
       items:
       - name: Combine worksheets into a single workbook