[excel] (Query, Range, Worksheet, Shape) Add samples to highly viewed pages (#330)

* Add query sample

* Adding samples to highly viewed pages

* 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.query.yml

@@ -4,7 +4,25 @@ uid: 'ExcelScript!ExcelScript.Query:interface'
 package: ExcelScript!
 fullName: ExcelScript.Query
 summary: Represents a Power Query query.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script logs information about all the Power Query queries in the workbook.
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get all the Power Query queries in the workbook.
+    const queries = workbook.getQueries();
+
+    // For each query, log the date it was last refreshed.
+    queries.forEach((query: ExcelScript.Query) => {
+      console.log(`Query ${query.getName()} - last refreshed ${query.getRefreshDate()}`);
+    });
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -2342,7 +2342,27 @@ methods:
       content: 'select(): void;'
       return:
         type: void
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script selects the first row of a table.
+           */
+          function main(workbook: ExcelScript.Workbook) {
+            // Get the first table on the current worksheet.
+            const sheet = workbook.getActiveWorksheet()
+            const table = sheet.getTables()[0];
+
+            // Get the first data row in the table.
+            const row = table.getRangeBetweenHeaderAndTotal().getRow(0);
+
+            // Select the first data row.
+            row.select();
+          }
+          ```
   - name: setColumnHidden(columnHidden)
     uid: 'ExcelScript!ExcelScript.Range#setColumnHidden:member(1)'
     package: ExcelScript!

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

@@ -4,7 +4,28 @@ uid: 'ExcelScript!ExcelScript.ShapeFont:interface'
 package: ExcelScript!
 fullName: ExcelScript.ShapeFont
 summary: 'Represents the font attributes, such as font name, font size, and color, for a shape''s `TextRange` object.'
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This sample sets the font of a shape to be bold. 
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the first shape in the current worksheet.
+    const sheet = workbook.getActiveWorksheet();
+    const shape = sheet.getShapes()[0];
+
+    // Get the text font from the shape.
+    const text: ExcelScript.TextRange = shape.getTextFrame().getTextRange();
+    const shapeTextFont: ExcelScript.ShapeFont = text.getFont();
+
+    // Set the font to be bold.
+    shapeTextFont.setBold(true);
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

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

@@ -39,7 +39,28 @@ methods:
       content: 'getFont(): ShapeFont;'
       return:
         type: '<xref uid="ExcelScript!ExcelScript.ShapeFont:interface" />'
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This sample sets the font of a shape to be bold. 
+           */
+          function main(workbook: ExcelScript.Workbook) {
+            // Get the first shape in the current worksheet.
+            const sheet = workbook.getActiveWorksheet();
+            const shape = sheet.getShapes()[0];
+
+            // Get the text font from the shape.
+            const text: ExcelScript.TextRange = shape.getTextFrame().getTextRange();
+            const shapeTextFont: ExcelScript.ShapeFont = text.getFont();
+
+            // Set the font to be bold.
+            shapeTextFont.setBold(true);
+          }
+          ```
   - name: 'getSubstring(start, length)'
     uid: 'ExcelScript!ExcelScript.TextRange#getSubstring:member(1)'
     package: ExcelScript!

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

@@ -4,7 +4,33 @@ uid: 'ExcelScript!ExcelScript.WorksheetProtection:interface'
 package: ExcelScript!
 fullName: ExcelScript.WorksheetProtection
 summary: Represents the protection of a worksheet object.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script pauses the protection of a worksheet by using the provided password.
+   * This password could come from a Power Automate flow.
+   */
+  function main(workbook: ExcelScript.Workbook, password: string) {
+    // Get the worksheet named "Sales".
+    const sheet = workbook.getWorksheet("Sales");
+    const protection: ExcelScript.WorksheetProtection = sheet.getProtection();
+    
+    // Check if the provided password works.
+    if (protection.checkPassword(password)) {
+      protection.pauseProtection(password);
+
+      // Edit the worksheet...
+
+      protection.resumeProtection();
+    } else {
+      console.log("Incorrect password");
+    }
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

docs/sample-scripts/excel-scripts.yaml

@@ -3577,6 +3577,20 @@
       // Apply the given protection options.
       sheetProtection.protect(protectionOptions);
     }
+'ExcelScript.Query:interface':
+  - |-
+    /**
+     * This script logs information about all the Power Query queries in the workbook.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get all the Power Query queries in the workbook.
+      const queries = workbook.getQueries();
+
+      // For each query, log the date it was last refreshed.
+      queries.forEach((query: ExcelScript.Query) => {
+        console.log(`Query ${query.getName()} - last refreshed ${query.getRefreshDate()}`);
+      });
+    }
 'ExcelScript.Range:interface':
   - |-
     /**
@@ -4205,6 +4219,22 @@
       // Change the value of any cells with the value "monthly special".
       range.replaceAll("monthly special", "parsnip", {completeMatch: true});
     }
+'ExcelScript.Range#select:member(1)':
+  - |-
+    /**
+     * This script selects the first row of a table.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the first table on the current worksheet.
+      const sheet = workbook.getActiveWorksheet()
+      const table = sheet.getTables()[0];
+
+      // Get the first data row in the table.
+      const row = table.getRangeBetweenHeaderAndTotal().getRow(0);
+
+      // Select the first data row.
+      row.select();
+    }
 'ExcelScript.Range#setFormula:member(1)':
   - |-
     /*
@@ -5215,6 +5245,23 @@
       textFrame.getTextRange().setText(value.toString());
       textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);
     }
+'ExcelScript.ShapeFont:interface':
+  - |-
+    /**
+     * This sample sets the font of a shape to be bold. 
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the first shape in the current worksheet.
+      const sheet = workbook.getActiveWorksheet();
+      const shape = sheet.getShapes()[0];
+
+      // Get the text font from the shape.
+      const text: ExcelScript.TextRange = shape.getTextFrame().getTextRange();
+      const shapeTextFont: ExcelScript.ShapeFont = text.getFont();
+
+      // Set the font to be bold.
+      shapeTextFont.setBold(true);
+    }
 'ExcelScript.SheetVisibility:enum':
   - |-
     /**
@@ -5805,6 +5852,23 @@
       const hexText: ExcelScript.TextRange = hexagon.getTextFrame().getTextRange();
       hexText.setText("Forest");
     }
+'ExcelScript.TextRange#getFont:member(1)':
+  - |-
+    /**
+     * This sample sets the font of a shape to be bold. 
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the first shape in the current worksheet.
+      const sheet = workbook.getActiveWorksheet();
+      const shape = sheet.getShapes()[0];
+
+      // Get the text font from the shape.
+      const text: ExcelScript.TextRange = shape.getTextFrame().getTextRange();
+      const shapeTextFont: ExcelScript.ShapeFont = text.getFont();
+
+      // Set the font to be bold.
+      shapeTextFont.setBold(true);
+    }
 'ExcelScript.TextRange#getText:member(1)':
   - |-
     /**
@@ -6482,6 +6546,28 @@
       let date = new Date(Date.now());
       newSheet.setName(`${date.toDateString()}`);
     }
+'ExcelScript.WorksheetProtection:interface':
+  - |-
+    /**
+     * This script pauses the protection of a worksheet by using the provided password.
+     * This password could come from a Power Automate flow.
+     */
+    function main(workbook: ExcelScript.Workbook, password: string) {
+      // Get the worksheet named "Sales".
+      const sheet = workbook.getWorksheet("Sales");
+      const protection: ExcelScript.WorksheetProtection = sheet.getProtection();
+      
+      // Check if the provided password works.
+      if (protection.checkPassword(password)) {
+        protection.pauseProtection(password);
+
+        // Edit the worksheet...
+
+        protection.resumeProtection();
+      } else {
+        console.log("Incorrect password");
+      }
+    }
 'ExcelScript.WorksheetProtection#protect:member(1)':
   - |-
     /**

generate-docs/API Coverage Report.csv

@@ -2347,7 +2347,7 @@ ExcelScript.ProtectionSelectionMode,N/A,Enum,Missing,true
 ExcelScript.ProtectionSelectionMode,"none",EnumField,Fine,false
 ExcelScript.ProtectionSelectionMode,"normal",EnumField,Fine,false
 ExcelScript.ProtectionSelectionMode,"unlocked",EnumField,Fine,false
-ExcelScript.Query,N/A,Class,Poor,false
+ExcelScript.Query,N/A,Class,Poor,true
 ExcelScript.Query,"getError()",Method,Poor,false
 ExcelScript.Query,"getLoadedTo()",Method,Poor,false
 ExcelScript.Query,"getLoadedToDataModel()",Method,Poor,false
@@ -2455,7 +2455,7 @@ ExcelScript.Range,"merge(across)",Method,Fine,true
 ExcelScript.Range,"moveTo(destinationRange)",Method,Poor,false
 ExcelScript.Range,"removeDuplicates(columns, includesHeader)",Method,Poor,false
 ExcelScript.Range,"replaceAll(text, replacement, criteria)",Method,Poor,true
-ExcelScript.Range,"select()",Method,Poor,false
+ExcelScript.Range,"select()",Method,Poor,true
 ExcelScript.Range,"setColumnHidden(columnHidden)",Method,Poor,false
 ExcelScript.Range,"setDirty()",Method,Poor,false
 ExcelScript.Range,"setFormula(formula)",Method,Poor,true
@@ -2725,7 +2725,7 @@ ExcelScript.ShapeFillType,"noFill",EnumField,Poor,false
 ExcelScript.ShapeFillType,"pattern",EnumField,Poor,false
 ExcelScript.ShapeFillType,"pictureAndTexture",EnumField,Poor,false
 ExcelScript.ShapeFillType,"solid",EnumField,Poor,false
-ExcelScript.ShapeFont,N/A,Class,Fine,false
+ExcelScript.ShapeFont,N/A,Class,Fine,true
 ExcelScript.ShapeFont,"getBold()",Method,Poor,false
 ExcelScript.ShapeFont,"getColor()",Method,Poor,false
 ExcelScript.ShapeFont,"getItalic()",Method,Poor,false
@@ -3075,7 +3075,7 @@ ExcelScript.TextFrame,"setTopMargin(topMargin)",Method,Poor,false
 ExcelScript.TextFrame,"setVerticalAlignment(verticalAlignment)",Method,Poor,false
 ExcelScript.TextFrame,"setVerticalOverflow(verticalOverflow)",Method,Poor,false
 ExcelScript.TextRange,N/A,Class,Fine,true
-ExcelScript.TextRange,"getFont()",Method,Poor,false
+ExcelScript.TextRange,"getFont()",Method,Fine,true
 ExcelScript.TextRange,"getSubstring(start, length)",Method,Poor,false
 ExcelScript.TextRange,"getText()",Method,Poor,true
 ExcelScript.TextRange,"setText(text)",Method,Poor,false
@@ -3307,7 +3307,7 @@ ExcelScript.WorksheetPositionType,"before",EnumField,Missing,false
 ExcelScript.WorksheetPositionType,"beginning",EnumField,Missing,false
 ExcelScript.WorksheetPositionType,"end",EnumField,Missing,false
 ExcelScript.WorksheetPositionType,"none",EnumField,Missing,false
-ExcelScript.WorksheetProtection,N/A,Class,Fine,false
+ExcelScript.WorksheetProtection,N/A,Class,Fine,true
 ExcelScript.WorksheetProtection,"addAllowEditRange(title, rangeAddress, options)",Method,Poor,false
 ExcelScript.WorksheetProtection,"checkPassword(password)",Method,Poor,false
 ExcelScript.WorksheetProtection,"getAllowEditRange(key)",Method,Poor,false