[All hosts] Add code samples (#2207)

OfficeDev · Feb 24, 2025 · feb5325 · feb5325
1 parent 9ecd4d7
commit feb5325
Show file tree

Hide file tree

Showing 9 changed files with 256 additions and 4 deletions.
diff --git a/docs/code-snippets/office-snippets.yaml b/docs/code-snippets/office-snippets.yaml
@@ -979,6 +979,26 @@ Office.CoercionType:enum:
             }
         });
     }
+Office.Context:interface:
+  - |-
+    // Get the Office host, version, and platform in which the add-in is running.
+    const contextInfo = Office.context.diagnostics;
+    console.log("Office application: " + contextInfo.host);
+    console.log("Office version: " + contextInfo.version);
+    console.log("Platform: " + contextInfo.platform);
+Office.Context#auth:member:
+  - |-
+    // Get an access token.
+    const authContext = Office.context.auth;
+    authContext.getAccessTokenAsync((result) => {
+        if (result.status === Office.AsyncResultStatus.Failed) {
+            console.log("Error obtaining token", result.error);
+            return;
+        }
+
+        const token = result.value;
+        console.log(token);
+    });
 Office.Context#contentLanguage:member:
   - |-
     function sayHelloWithContentLanguage() {
@@ -1763,6 +1783,33 @@ Office.DevicePermissionType:enum:
     } else {
         console.log("The add-in isn't running in Excel, Outlook, PowerPoint, or Word.");
     }
+Office.Dialog:interface:
+  - |-
+    // The following example shows how to open a dialog with a specified size. It also shows
+    // how to register a function to handle the message when Office.UI.messageParent() is called
+    // in the dialog and how to use that handler to close the dialog.
+
+    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();
+                // Do something to process the message.
+            });
+        }
+    );
+
+    // The following example does the same thing in TypeScript.
+
+    Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
+        (asyncResult: Office.AsyncResult) => {
+            const dialog: Office.Dialog = asyncResult.value;
+            dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
+                dialog.close();
+                // Do something to process the message.
+            });
+        }
+    );
 Office.Dialog#addEventHandler:member(1):
   - |-
     // The following example shows how to open a dialog with a specified size. It also shows
@@ -1833,6 +1880,10 @@ Office.Dialog#messageChild:member(1):
         const messageToDialog = JSON.stringify(currentWorksheet);
         dialog.messageChild(messageToDialog);
     }
+Office.DialogMessageOptions#targetOrigin:member:
+  - |-
+    // The following example shows how to send a message to the domain of the parent runtime.
+    Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });
 Office.DialogOptions#height:member:
   - |-
     // The following example shows how to open a dialog with a specified size. It also shows

diff --git a/docs/docs-ref-autogen/office/office/office.context.yml b/docs/docs-ref-autogen/office/office/office.context.yml
@@ -23,6 +23,24 @@ remarks: >-
   </strong></td><td> Not supported </td><td> Supported </td><td> Supported </td><td> Not supported </td><td> Not
   applicable </td></tr> <tr><td><strong> Word </strong></td><td> Supported </td><td> Supported </td><td> Supported
   </td><td> Supported </td><td> Not applicable </td></tr> </table>
+
+
+  #### Examples
+
+
+  ```TypeScript
+
+  // Get the Office host, version, and platform in which the add-in is running.
+
+  const contextInfo = Office.context.diagnostics;
+
+  console.log("Office application: " + contextInfo.host);
+
+  console.log("Office version: " + contextInfo.version);
+
+  console.log("Platform: " + contextInfo.platform);
+
+  ```
 isPreview: false
 isDeprecated: false
 type: interface
@@ -39,6 +57,24 @@ properties:
       content: 'auth: Auth;'
       return:
         type: '<xref uid="office!Office.Auth:interface" />'
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          // Get an access token.
+          const authContext = Office.context.auth;
+          authContext.getAccessTokenAsync((result) => {
+              if (result.status === Office.AsyncResultStatus.Failed) {
+                  console.log("Error obtaining token", result.error);
+                  return;
+              }
+
+              const token = result.value;
+              console.log(token);
+          });
+          ```
   - name: commerceAllowed
     uid: 'office!Office.Context#commerceAllowed:member'
     package: office!

diff --git a/docs/docs-ref-autogen/office/office/office.dialog.yml b/docs/docs-ref-autogen/office/office/office.dialog.yml
@@ -9,6 +9,45 @@ summary: >-
 remarks: >-
   **Requirement set**:
   [DialogAPI](https://learn.microsoft.com/javascript/api/requirement-sets/common/dialog-api-requirement-sets)
+
+
+  #### Examples
+
+
+  ```TypeScript
+
+  // The following example shows how to open a dialog with a specified size. It also shows
+
+  // how to register a function to handle the message when Office.UI.messageParent() is called
+
+  // in the dialog and how to use that handler to close the dialog.
+
+
+  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();
+              // Do something to process the message.
+          });
+      }
+  );
+
+
+  // The following example does the same thing in TypeScript.
+
+
+  Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
+      (asyncResult: Office.AsyncResult) => {
+          const dialog: Office.Dialog = asyncResult.value;
+          dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
+              dialog.close();
+              // Do something to process the message.
+          });
+      }
+  );
+
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

diff --git a/docs/docs-ref-autogen/office/office/office.dialogmessageoptions.yml b/docs/docs-ref-autogen/office/office/office.dialogmessageoptions.yml
@@ -25,3 +25,12 @@ properties:
       content: 'targetOrigin: string;'
       return:
         type: string
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          // The following example shows how to send a message to the domain of the parent runtime.
+          Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });
+          ```
diff --git a/docs/docs-ref-autogen/office_release/office/office.context.yml b/docs/docs-ref-autogen/office_release/office/office.context.yml
@@ -23,6 +23,24 @@ remarks: >-
   </strong></td><td> Not supported </td><td> Supported </td><td> Supported </td><td> Not supported </td><td> Not
   applicable </td></tr> <tr><td><strong> Word </strong></td><td> Supported </td><td> Supported </td><td> Supported
   </td><td> Supported </td><td> Not applicable </td></tr> </table>
+
+
+  #### Examples
+
+
+  ```TypeScript
+
+  // Get the Office host, version, and platform in which the add-in is running.
+
+  const contextInfo = Office.context.diagnostics;
+
+  console.log("Office application: " + contextInfo.host);
+
+  console.log("Office version: " + contextInfo.version);
+
+  console.log("Platform: " + contextInfo.platform);
+
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

diff --git a/docs/docs-ref-autogen/office_release/office/office.dialog.yml b/docs/docs-ref-autogen/office_release/office/office.dialog.yml
@@ -9,6 +9,45 @@ summary: >-
 remarks: >-
   **Requirement set**:
   [DialogAPI](https://learn.microsoft.com/javascript/api/requirement-sets/common/dialog-api-requirement-sets)
+
+
+  #### Examples
+
+
+  ```TypeScript
+
+  // The following example shows how to open a dialog with a specified size. It also shows
+
+  // how to register a function to handle the message when Office.UI.messageParent() is called
+
+  // in the dialog and how to use that handler to close the dialog.
+
+
+  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();
+              // Do something to process the message.
+          });
+      }
+  );
+
+
+  // The following example does the same thing in TypeScript.
+
+
+  Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
+      (asyncResult: Office.AsyncResult) => {
+          const dialog: Office.Dialog = asyncResult.value;
+          dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
+              dialog.close();
+              // Do something to process the message.
+          });
+      }
+  );
+
+  ```
 isPreview: false
 isDeprecated: false
 type: interface

diff --git a/docs/docs-ref-autogen/office_release/office/office.dialogmessageoptions.yml b/docs/docs-ref-autogen/office_release/office/office.dialogmessageoptions.yml
@@ -25,3 +25,12 @@ properties:
       content: 'targetOrigin: string;'
       return:
         type: string
+        description: |-
+
+
+          #### Examples
+
+          ```TypeScript
+          // The following example shows how to send a message to the domain of the parent runtime.
+          Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });
+          ```
diff --git a/generate-docs/API Coverage Report.csv b/generate-docs/API Coverage Report.csv
@@ -6907,8 +6907,8 @@ Office.CoercionType,"SlideRange",EnumField,Good,false
 Office.CoercionType,"Table",EnumField,Good,false
 Office.CoercionType,"Text",EnumField,Good,false
 Office.CoercionType,"XmlSvg",EnumField,Good,false
-Office.Context,N/A,Class,Good,false
-Office.Context,"auth",Property,Fine,false
+Office.Context,N/A,Class,Good,true
+Office.Context,"auth",Property,Fine,true
 Office.Context,"commerceAllowed",Property,Good,true
 Office.Context,"contentLanguage",Property,Good,true
 Office.Context,"diagnostics",Property,Good,true
@@ -6995,13 +6995,13 @@ Office.DevicePermissionType,N/A,Enum,Good,true
 Office.DevicePermissionType,"camera",EnumField,Fine,false
 Office.DevicePermissionType,"geolocation",EnumField,Fine,false
 Office.DevicePermissionType,"microphone",EnumField,Fine,false
-Office.Dialog,N/A,Class,Good,false
+Office.Dialog,N/A,Class,Good,true
 Office.Dialog,"addEventHandler(eventType, handler)",Method,Fine,true
 Office.Dialog,"close()",Method,Good,true
 Office.Dialog,"messageChild(message, messageOptions)",Method,Fine,true
 Office.Dialog,"sendMessage(name)",Method,Poor,false
 Office.DialogMessageOptions,N/A,Class,Good,false
-Office.DialogMessageOptions,"targetOrigin",Property,Good,false
+Office.DialogMessageOptions,"targetOrigin",Property,Good,true
 Office.DialogOptions,N/A,Class,Fine,false
 Office.DialogOptions,"asyncContext",Property,Fine,false
 Office.DialogOptions,"displayInIframe",Property,Good,false

diff --git a/generate-docs/script-inputs/local-repo-snippets.yaml b/generate-docs/script-inputs/local-repo-snippets.yaml
@@ -2520,6 +2520,26 @@ Office.CoercionType:enum:
             }
         });
     }
+Office.Context:interface:
+  - |-
+    // Get the Office host, version, and platform in which the add-in is running.
+    const contextInfo = Office.context.diagnostics;
+    console.log("Office application: " + contextInfo.host);
+    console.log("Office version: " + contextInfo.version);
+    console.log("Platform: " + contextInfo.platform);
+Office.Context#auth:member:
+  - |-
+    // Get an access token.
+    const authContext = Office.context.auth;
+    authContext.getAccessTokenAsync((result) => {
+        if (result.status === Office.AsyncResultStatus.Failed) {
+            console.log("Error obtaining token", result.error);
+            return;
+        }
+
+        const token = result.value;
+        console.log(token);
+    });
 Office.Context#contentLanguage:member:
   - |-
     function sayHelloWithContentLanguage() {
@@ -3304,6 +3324,33 @@ Office.DevicePermissionType:enum:
     } else {
         console.log("The add-in isn't running in Excel, Outlook, PowerPoint, or Word.");
     }
+Office.Dialog:interface:
+  - |-
+    // The following example shows how to open a dialog with a specified size. It also shows
+    // how to register a function to handle the message when Office.UI.messageParent() is called
+    // in the dialog and how to use that handler to close the dialog.
+
+    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();
+                // Do something to process the message.
+            });
+        }
+    );
+
+    // The following example does the same thing in TypeScript.
+
+    Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
+        (asyncResult: Office.AsyncResult) => {
+            const dialog: Office.Dialog = asyncResult.value;
+            dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
+                dialog.close();
+                // Do something to process the message.
+            });
+        }
+    );
 Office.Dialog#addEventHandler:member(1):
   - |-
     // The following example shows how to open a dialog with a specified size. It also shows
@@ -3374,6 +3421,10 @@ Office.Dialog#messageChild:member(1):
         const messageToDialog = JSON.stringify(currentWorksheet);
         dialog.messageChild(messageToDialog);
     }
+Office.DialogMessageOptions#targetOrigin:member:
+  - |-
+    // The following example shows how to send a message to the domain of the parent runtime.
+    Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });
 Office.DialogOptions#height:member:
   - |-
     // The following example shows how to open a dialog with a specified size. It also shows