[All hosts] (Office.Context) Add code samples to properties (#2077)

* Add snippets to Office.Context properties * Apply suggestions from code review Co-authored-by: Alex Jerabek <[email protected]> * Run script --------- Co-authored-by: Alex Jerabek <[email protected]>
OfficeDev · Sep 30, 2024 · 0453502 · 0453502
1 parent 98f2add
commit 0453502
Show file tree

Hide file tree

Showing 5 changed files with 416 additions and 20 deletions.
diff --git a/docs/code-snippets/office-snippets.yaml b/docs/code-snippets/office-snippets.yaml
@@ -996,6 +996,15 @@ Office.Context#contentLanguage:member:
     function write(message){
         document.getElementById('message').innerText += message; 
     }
+Office.Context#commerceAllowed:member:
+  - |-
+    // Check if the add-in is running on an iPad.
+    const allowCommerce = Office.context.commerceAllowed;
+    const isTouchEnabled = Office.context.touchEnabled;
+    if (!allowCommerce && isTouchEnabled) {
+        // Add-in is running on an iPad.
+        // Do something.
+    }
 Office.Context#diagnostics:member:
   - |-
     const contextInfo = Office.context.diagnostics;
@@ -1033,6 +1042,18 @@ Office.Context#document:member:
         _document = Office.context.document;
         });
     }
+Office.Context#host:member:
+  - |-
+    const host = Office.context.host;
+    if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
+        // Do something.
+    } else if (host === Office.HostType.Outlook) {
+        // Do something.
+    }
+Office.Context#license:member:
+  - |-
+    const license = Office.context.license;
+    console.log(`Office license: ${license}`);
 Office.Context#mailbox:member:
   - |-
     // The following line of code access the item object of the JavaScript API for Office.
@@ -1095,6 +1116,53 @@ Office.Context#partitionKey:member:
             return localStorage.getItem(key);
         }
     }
+Office.Context#platform:member:
+- |-
+    // Request permission from a user to access their devices from Office on the web.
+    if (Office.context.platform === Office.PlatformType.OfficeOnline) {
+        const deviceCapabilities = [
+            Office.DevicePermissionType.camera,
+            Office.DevicePermissionType.microphone
+        ];
+        Office.devicePermission
+            .requestPermissions(deviceCapabilities)
+            .then((isGranted) => {
+                if (isGranted) {
+                    // Do something with device capabilities.
+                }
+            })
+            .catch((error) => {
+                console.log("Permission denied.");
+                console.error(error);
+            });
+    }
+Office.Context#requirements:member:
+  - |-
+    // To use the setCellProperties API, check if ExcelApi 1.9 is supported.
+    if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
+        const cellProperties: Excel.SettableCellProperties[][] =
+        colors2D.map(row =>
+            row.map(color =>
+                ({
+                    format: {
+                        fill: {
+                            color: color
+                        }
+                    }
+                })
+            )
+        );
+        sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
+    }
+    ...
+Office.Context#roamingSettings:member:
+  - |-
+    // Get the current value of the 'myKey' setting.
+    const value = Office.context.roamingSettings.get('myKey');
+    // Update the value of the 'myKey' setting.
+    Office.context.roamingSettings.set('myKey', 'Hello World!');
+    // Persist the change.
+    Office.context.roamingSettings.saveAsync();
 Office.Context#sensitivityLabelsCatalog:member:
   - |-
     // Check if the catalog of sensitivity labels is enabled on the current mailbox.
@@ -1114,14 +1182,29 @@ Office.Context#sensitivityLabelsCatalog:member:
             console.log("Action failed with error: " + asyncResult.error.message);
         }
     });
-Office.Context#roamingSettings:member:
+Office.Context#touchEnabled:member:
   - |-
-    // Get the current value of the 'myKey' setting.
-    const value = Office.context.roamingSettings.get('myKey');
-    // Update the value of the 'myKey' setting.
-    Office.context.roamingSettings.set('myKey', 'Hello World!');
-    // Persist the change.
-    Office.context.roamingSettings.saveAsync();
+    // Check if the add-in is running on an iPad.
+    const allowCommerce = Office.context.commerceAllowed;
+    const isTouchEnabled = Office.context.touchEnabled;
+    if (!allowCommerce && isTouchEnabled) {
+        // Add-in is running on an iPad.
+        // Do something.
+    }
+Office.context#ui:member:
+  - |-
+    // Open a dialog and register an event handler.
+    Office.context.ui.displayDialogAsync(
+        "https://www.contoso.com/myDialog.html",
+        { height: 30, width: 20 },
+        (asyncResult) => {
+            const dialog = asyncResult.value;
+            dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
+                dialog.close();
+                processMessage(arg);
+            });
+        }
+    );
 Office.Context#urls:member:
   - |-
     // Get the value of the first parameter of the JavaScript runtime URL.

diff --git a/docs/docs-ref-autogen/office/office/office.context.yml b/docs/docs-ref-autogen/office/office/office.context.yml
@@ -55,6 +55,25 @@ properties:
       Office Add-ins running in Office on the Windows desktop or in the browser do allow such links. If you want the UI
       of your add-in to provide a link to an external payment system on platforms other than iOS, you can use the
       commerceAllowed property to control when that link is displayed.
+
+
+      #### Examples
+
+
+      ```TypeScript
+
+      // Check if the add-in is running on an iPad.
+
+      const allowCommerce = Office.context.commerceAllowed;
+
+      const isTouchEnabled = Office.context.touchEnabled;
+
+      if (!allowCommerce && isTouchEnabled) {
+          // Add-in is running on an iPad.
+          // Do something.
+      }
+
+      ```
     isPreview: false
     isDeprecated: false
     syntax:
@@ -257,6 +276,22 @@ properties:
       requirement sets, you can use the
       [Office.context.mailbox.diagnostics](https://learn.microsoft.com/javascript/api/outlook/office.mailbox?view=outlook-js-preview&preserve-view=true#outlook-office-mailbox-diagnostics-member)
       property to get similar information.
+
+
+      #### Examples
+
+
+      ```TypeScript
+
+      const host = Office.context.host;
+
+      if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
+          // Do something.
+      } else if (host === Office.HostType.Outlook) {
+          // Do something.
+      }
+
+      ```
     isPreview: false
     isDeprecated: false
     syntax:
@@ -275,6 +310,15 @@ properties:
       content: 'license: object;'
       return:
         type: object
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          const license = Office.context.license;
+          console.log(`Office license: ${license}`);
+          ```
   - name: mailbox
     uid: 'office!Office.Context#mailbox:member'
     package: office!
@@ -445,6 +489,34 @@ properties:
 
       - In Outlook, `OfficeOnline` is returned if an add-is is running in Outlook on the web or in [new Outlook on
       Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627)<!-- -->.
+
+
+      #### Examples
+
+
+      ```TypeScript
+
+      // Request permission from a user to access their devices from Office on the web.
+
+      if (Office.context.platform === Office.PlatformType.OfficeOnline) {
+          const deviceCapabilities = [
+              Office.DevicePermissionType.camera,
+              Office.DevicePermissionType.microphone
+          ];
+          Office.devicePermission
+              .requestPermissions(deviceCapabilities)
+              .then((isGranted) => {
+                  if (isGranted) {
+                      // Do something with device capabilities.
+                  }
+              })
+              .catch((error) => {
+                  console.log("Permission denied.");
+                  console.error(error);
+              });
+      }
+
+      ```
     isPreview: false
     isDeprecated: false
     syntax:
@@ -465,6 +537,30 @@ properties:
       content: 'requirements: RequirementSetSupport;'
       return:
         type: '<xref uid="office!Office.RequirementSetSupport:interface" />'
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          // To use the setCellProperties API, check if ExcelApi 1.9 is supported.
+          if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
+              const cellProperties: Excel.SettableCellProperties[][] =
+              colors2D.map(row =>
+                  row.map(color =>
+                      ({
+                          format: {
+                              fill: {
+                                  color: color
+                              }
+                          }
+                      })
+                  )
+              );
+              sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
+          }
+          ...
+          ```
   - name: roamingSettings
     uid: 'office!Office.Context#roamingSettings:member'
     package: office!
@@ -578,6 +674,25 @@ properties:
 
       Use the touchEnabled property to determine when your add-in is running on a touch device and if necessary, adjust
       the kind of controls, and size and spacing of elements in your add-in's UI to accommodate touch interactions.
+
+
+      #### Examples
+
+
+      ```TypeScript
+
+      // Check if the add-in is running on an iPad.
+
+      const allowCommerce = Office.context.commerceAllowed;
+
+      const isTouchEnabled = Office.context.touchEnabled;
+
+      if (!allowCommerce && isTouchEnabled) {
+          // Add-in is running on an iPad.
+          // Do something.
+      }
+
+      ```
     isPreview: false
     isDeprecated: false
     syntax: