[excel] (Range, Workbook) Add samples for WorkbookRangeAreas and WorkbookProtection (#338)

* Adding protection samples

* Add precedent samples

Author: AlexJerabek

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

@@ -799,7 +799,30 @@ methods:
       content: 'getDirectPrecedents(): WorkbookRangeAreas;'
       return:
         type: '<xref uid="ExcelScript!ExcelScript.WorkbookRangeAreas:interface" />'
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script finds the direct precedents of the active cell.
+           * It changes the font and color of those precedent cells. 
+           */
+          function main(workbook: ExcelScript.Workbook) {
+            // Get the active cell.
+            const selected = workbook.getActiveCell();
+            
+            // Get the cells that are direct precedents of the current cell.
+            const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();
+
+            // Set the font to bold and the fill color to orange for all the precedent cells.
+            precedents.getRanges().forEach(range => {
+              range.getFormat().getFill().setColor("orange");
+              range.getFormat().getFont().setBold(true);
+            });
+          }
+          ```
   - name: getEntireColumn()
     uid: 'ExcelScript!ExcelScript.Range#getEntireColumn:member(1)'
     package: ExcelScript!

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

@@ -1259,7 +1259,29 @@ methods:
       content: 'getProtection(): WorkbookProtection;'
       return:
         type: '<xref uid="ExcelScript!ExcelScript.WorkbookProtection:interface" />'
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script protects the workbook with a password, if it isn't already protected.
+           * The password is provided by the user through a prompt.
+           */
+          function main(workbook: ExcelScript.Workbook, password?: string) {
+            // Get the workbook-level protection object.
+            const protection = workbook.getProtection();
+
+            // Check if the workbook is already protected.
+            if (!protection.getProtected()) {
+                // Protect the workbook with the given password.
+                // If the optional password was omitted, 
+                // no password will be needed to unprotect the workbook.
+              protection.protect(password);
+            }
+          }
+          ```
   - name: getQueries()
     uid: 'ExcelScript!ExcelScript.Workbook#getQueries:member(1)'
     package: ExcelScript!

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

@@ -21,7 +21,26 @@ methods:
       content: 'getProtected(): boolean;'
       return:
         type: boolean
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script protects the workbook with a default password, if there is not already protection.
+           */
+          function main(workbook: ExcelScript.Workbook) {
+            // Get the workbook-level protection object.
+            const protection = workbook.getProtection();
+
+            // Check if the workbook is already protected.
+            if (!protection.getProtected()) {
+              // Apply a default password.
+              protection.protect("1234");
+            }
+          }
+          ```
   - name: protect(password)
     uid: 'ExcelScript!ExcelScript.WorkbookProtection#protect:member(1)'
     package: ExcelScript!
@@ -38,7 +57,25 @@ methods:
           type: string
       return:
         type: void
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script protects the workbook using a password given in a user prompt.
+           */
+          function main(workbook: ExcelScript.Workbook, password?: string) {
+            // Get the workbook-level protection object.
+            const protection = workbook.getProtection();
+
+            // Protect the workbook with the given password.
+            // If the optional password was omitted, 
+            // no password will be needed to unprotect the workbook.
+            protection.protect(password);
+          }
+          ```
   - name: unprotect(password)
     uid: 'ExcelScript!ExcelScript.WorkbookProtection#unprotect:member(1)'
     package: ExcelScript!
@@ -55,4 +92,20 @@ methods:
           type: string
       return:
         type: void
-        description: ''
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          /**
+           * This script removes protection from the workbook using a password given in a user prompt.
+           */
+          function main(workbook: ExcelScript.Workbook, password?: string) {
+            // Get the workbook-level protection object.
+            const protection = workbook.getProtection();
+
+            // Unprotect the workbook with the given password.
+            protection.unprotect(password);
+          }
+          ```

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

@@ -4,7 +4,30 @@ uid: 'ExcelScript!ExcelScript.WorkbookRangeAreas:interface'
 package: ExcelScript!
 fullName: ExcelScript.WorkbookRangeAreas
 summary: Represents a collection of one or more rectangular ranges in multiple worksheets.
-remarks: ''
+remarks: |-
+
+
+  #### Examples
+
+  ```TypeScript
+  /**
+   * This script finds the direct precedents of the active cell.
+   * It changes the font and color of those precedent cells. 
+   */
+  function main(workbook: ExcelScript.Workbook) {
+    // Get the active cell.
+    const selected = workbook.getActiveCell();
+    
+    // Get the cells that are direct precedents of the current cell.
+    const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();
+
+    // Set the font to bold and the fill color to orange for all the precedent cells.
+    precedents.getRanges().forEach(range => {
+      range.getFormat().getFill().setColor("orange");
+      range.getFormat().getFont().setBold(true);
+    });
+  }
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

docs/sample-scripts/excel-scripts.yaml

@@ -3864,6 +3864,25 @@
           }
         });
     }
+'ExcelScript.Range#getDirectPrecedents:member(1)':
+  - |-
+    /**
+     * This script finds the direct precedents of the active cell.
+     * It changes the font and color of those precedent cells. 
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the active cell.
+      const selected = workbook.getActiveCell();
+      
+      // Get the cells that are direct precedents of the current cell.
+      const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();
+
+      // Set the font to bold and the fill color to orange for all the precedent cells.
+      precedents.getRanges().forEach(range => {
+        range.getFormat().getFill().setColor("orange");
+        range.getFormat().getFont().setBold(true);
+      });
+    }
 'ExcelScript.Range#getExtendedRange:member(1)':
   - |-
     /**
@@ -6123,6 +6142,24 @@
         }
       });
     }
+'ExcelScript.Workbook#getProtection:member(1)':
+  - |-
+    /**
+     * This script protects the workbook with a password, if it isn't already protected.
+     * The password is provided by the user through a prompt.
+     */
+    function main(workbook: ExcelScript.Workbook, password?: string) {
+      // Get the workbook-level protection object.
+      const protection = workbook.getProtection();
+
+      // Check if the workbook is already protected.
+      if (!protection.getProtected()) {
+          // Protect the workbook with the given password.
+          // If the optional password was omitted, 
+          // no password will be needed to unprotect the workbook.
+        protection.protect(password);
+      }
+    }
 'ExcelScript.Workbook#getWorksheet:member(1)':
   - |-
     /**
@@ -6154,6 +6191,66 @@
       console.log(names);
       console.log(`Total worksheets inside of this workbook: ${sheets.length}`);
     }
+'ExcelScript.WorkbookProtection#getProtected:member(1)':
+  - |-
+    /**
+     * This script protects the workbook with a default password, if there is not already protection.
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the workbook-level protection object.
+      const protection = workbook.getProtection();
+
+      // Check if the workbook is already protected.
+      if (!protection.getProtected()) {
+        // Apply a default password.
+        protection.protect("1234");
+      }
+    }
+'ExcelScript.WorkbookProtection#protect:member(1)':
+  - |-
+    /**
+     * This script protects the workbook using a password given in a user prompt.
+     */
+    function main(workbook: ExcelScript.Workbook, password?: string) {
+      // Get the workbook-level protection object.
+      const protection = workbook.getProtection();
+
+      // Protect the workbook with the given password.
+      // If the optional password was omitted, 
+      // no password will be needed to unprotect the workbook.
+      protection.protect(password);
+    }
+'ExcelScript.WorkbookProtection#unprotect:member(1)':
+  - |-
+    /**
+     * This script removes protection from the workbook using a password given in a user prompt.
+     */
+    function main(workbook: ExcelScript.Workbook, password?: string) {
+      // Get the workbook-level protection object.
+      const protection = workbook.getProtection();
+
+      // Unprotect the workbook with the given password.
+      protection.unprotect(password);
+    }
+'ExcelScript.WorkbookRangeAreas:interface':
+  - |-
+    /**
+     * This script finds the direct precedents of the active cell.
+     * It changes the font and color of those precedent cells. 
+     */
+    function main(workbook: ExcelScript.Workbook) {
+      // Get the active cell.
+      const selected = workbook.getActiveCell();
+      
+      // Get the cells that are direct precedents of the current cell.
+      const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();
+
+      // Set the font to bold and the fill color to orange for all the precedent cells.
+      precedents.getRanges().forEach(range => {
+        range.getFormat().getFill().setColor("orange");
+        range.getFormat().getFont().setBold(true);
+      });
+    }
 'ExcelScript.WorkbookLinksRefreshMode:enum':
   - |-
     /**

generate-docs/API Coverage Report.csv

@@ -2387,7 +2387,7 @@ ExcelScript.Range,"getColumnsBefore(count)",Method,Poor,false
 ExcelScript.Range,"getConditionalFormat(id)",Method,Poor,false
 ExcelScript.Range,"getConditionalFormats()",Method,Poor,false
 ExcelScript.Range,"getDataValidation()",Method,Poor,true
-ExcelScript.Range,"getDirectPrecedents()",Method,Poor,false
+ExcelScript.Range,"getDirectPrecedents()",Method,Fine,true
 ExcelScript.Range,"getEntireColumn()",Method,Poor,false
 ExcelScript.Range,"getEntireRow()",Method,Poor,false
 ExcelScript.Range,"getExtendedRange(direction, activeCell)",Method,Fine,true
@@ -3166,7 +3166,7 @@ ExcelScript.Workbook,"getPredefinedCellStyle(name)",Method,Poor,false
 ExcelScript.Workbook,"getPredefinedCellStyles()",Method,Poor,false
 ExcelScript.Workbook,"getPreviouslySaved()",Method,Poor,false
 ExcelScript.Workbook,"getProperties()",Method,Poor,false
-ExcelScript.Workbook,"getProtection()",Method,Poor,false
+ExcelScript.Workbook,"getProtection()",Method,Poor,true
 ExcelScript.Workbook,"getQueries()",Method,Poor,false
 ExcelScript.Workbook,"getQuery(key)",Method,Poor,false
 ExcelScript.Workbook,"getReadOnly()",Method,Poor,false
@@ -3200,10 +3200,10 @@ ExcelScript.WorkbookLinksRefreshMode,N/A,Enum,Fine,true
 ExcelScript.WorkbookLinksRefreshMode,"automatic",EnumField,Fine,false
 ExcelScript.WorkbookLinksRefreshMode,"manual",EnumField,Fine,false
 ExcelScript.WorkbookProtection,N/A,Class,Fine,false
-ExcelScript.WorkbookProtection,"getProtected()",Method,Poor,false
-ExcelScript.WorkbookProtection,"protect(password)",Method,Poor,false
-ExcelScript.WorkbookProtection,"unprotect(password)",Method,Poor,false
-ExcelScript.WorkbookRangeAreas,N/A,Class,Fine,false
+ExcelScript.WorkbookProtection,"getProtected()",Method,Poor,true
+ExcelScript.WorkbookProtection,"protect(password)",Method,Poor,true
+ExcelScript.WorkbookProtection,"unprotect(password)",Method,Poor,true
+ExcelScript.WorkbookRangeAreas,N/A,Class,Fine,true
 ExcelScript.WorkbookRangeAreas,"getAddresses()",Method,Poor,false
 ExcelScript.WorkbookRangeAreas,"getAreas()",Method,Poor,false
 ExcelScript.WorkbookRangeAreas,"getRangeAreasBySheet(key)",Method,Poor,false