Merge branch 'main' into live

Author: github-actions

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

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!

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

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" });
+          ```

docs/docs-ref-autogen/office/office/office.ui.yml

@@ -4,13 +4,11 @@ uid: 'office!Office.UI:interface'
 package: office!
 fullName: Office.UI
 summary: >-
-  Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your
-  Office Add-ins.
+  Provides objects and methods to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.
 
 
-  Visit "[Use the Dialog API in your Office
-  Add-ins](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-api-in-office-add-ins)<!-- -->" for more
-  information.
+  For guidance on how to configure dialog boxes, see [Use the Dialog API in your Office
+  Add-ins](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-api-in-office-add-ins)<!-- -->.
 remarks: |-
 
 
@@ -210,62 +208,31 @@ methods:
       365](https://learn.microsoft.com/office/dev/add-ins/develop/unified-manifest-overview)<!-- -->.
 
 
-      The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial
-      page loads, you can go to other domains.
-
-
-      Any page calling `Office.context.ui.messageParent` must also be on the same domain as the parent page.
-
-
-      **Design considerations**:
-
-
-      The following design considerations apply to dialog boxes.
-
-
-      - An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the
-      same time from Add-in Commands (custom ribbon buttons or menu items).
-
-
-      - Every dialog box can be moved and resized by the user.
+      **Important**:
 
 
-      - Every dialog box is centered on the screen when opened.
-
-
-      - Dialog boxes appear on top of the application and in the order in which they were created.
-
-
-      Use a dialog box to:
-
-
-      - Display authentication pages to collect user credentials.
-
-
-      - Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.
+      - The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial
+      page loads, you can go to other domains.
 
 
-      - Temporarily increase the surface area that a user has available to complete a task.
+      - Any page calling `Office.context.ui.messageParent` must also be on the same domain as the parent page.
 
 
-      Do not use a dialog box to interact with a document. Use a task pane instead.
+      - To learn about rules, limitations, and best practices for the Office Dialog API, see [Best practices and rules
+      for the Office dialog API](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-best-practices)<!-- -->.
 
 
-      **displayDialogAsync Errors**
+      - For information on errors and how to handle them, see [Handle errors and events in the Office dialog
+      box](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-handle-errors-events)<!-- -->.
 
 
-      <table> <tr> <th>Code number</th> <th>Meaning</th> </tr> <tr> <td>12004</td> <td>The domain of the URL passed to
-      displayDialogAsync isn't trusted. The domain must be either the same domain as the host page (including protocol
-      and port number), or it must be registered in the <code>AppDomains</code> section of the add-in manifest.</td>
-      </tr> <tr> <td>12005</td> <td>The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In
-      some versions of Office, the error message returned with 12005 is the same one returned for 12004.)</td> </tr>
-      <tr> <td>12007</td> <td>A dialog box is already opened from the task pane. A task pane add-in can only have one
-      dialog box open at a time.</td> </tr> <tr> <td>12009</td> <td>The user chose to ignore the dialog box. This error
-      can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.</td>
-      </tr> </table>
+      - In Outlook on the web and new Outlook on Windows, don't set the
+      [window.name](https://developer.mozilla.org/docs/Web/API/Window/name) property when configuring a dialog in your
+      add-in. The `window.name` property is used by these Outlook clients to maintain functionality across page
+      redirects.
 
 
-      In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult
+      - In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult
       object to return the following information.
 
 
@@ -365,62 +332,31 @@ methods:
       365](https://learn.microsoft.com/office/dev/add-ins/develop/unified-manifest-overview)<!-- -->.
 
 
-      The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial
-      page loads, you can go to other domains.
+      **Important**:
 
 
-      Any page calling `Office.context.ui.messageParent` must also be on the same domain as the parent page.
-
-
-      **Design considerations**:
-
-
-      The following design considerations apply to dialog boxes.
-
-
-      - An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the
-      same time from Add-in Commands (custom ribbon buttons or menu items).
-
-
-      - Every dialog box can be moved and resized by the user.
-
-
-      - Every dialog box is centered on the screen when opened.
-
-
-      - Dialog boxes appear on top of the application and in the order in which they were created.
-
-
-      Use a dialog box to:
-
-
-      - Display authentication pages to collect user credentials.
-
-
-      - Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.
+      - The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial
+      page loads, you can go to other domains.
 
 
-      - Temporarily increase the surface area that a user has available to complete a task.
+      - Any page calling `Office.context.ui.messageParent` must also be on the same domain as the parent page.
 
 
-      Do not use a dialog box to interact with a document. Use a task pane instead.
+      - To learn about rules, limitations, and best practices for the Office Dialog API, see [Best practices and rules
+      for the Office dialog API](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-best-practices)<!-- -->.
 
 
-      **displayDialogAsync Errors**
+      - For information on errors and how to handle them, see [Handle errors and events in the Office dialog
+      box](https://learn.microsoft.com/office/dev/add-ins/develop/dialog-handle-errors-events)<!-- -->.
 
 
-      <table> <tr> <th>Code number</th> <th>Meaning</th> </tr> <tr> <td>12004</td> <td>The domain of the URL passed to
-      displayDialogAsync isn't trusted. The domain must be either the same domain as the host page (including protocol
-      and port number), or it must be registered in the <code>AppDomains</code> section of the add-in manifest.</td>
-      </tr> <tr> <td>12005</td> <td>The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In
-      some versions of Office, the error message returned with 12005 is the same one returned for 12004.)</td> </tr>
-      <tr> <td>12007</td> <td>A dialog box is already opened from the task pane. A task pane add-in can only have one
-      dialog box open at a time.</td> </tr> <tr> <td>12009</td> <td>The user chose to ignore the dialog box. This error
-      can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.</td>
-      </tr> </table>
+      - In Outlook on the web and new Outlook on Windows, don't set the
+      [window.name](https://developer.mozilla.org/docs/Web/API/Window/name) property when configuring a dialog in your
+      add-in. The `window.name` property is used by these Outlook clients to maintain functionality across page
+      redirects.
 
 
-      In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult
+      - In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult
       object to return the following information.
 
 
@@ -533,7 +469,9 @@ methods:
       content: 'openBrowserWindow(url: string): void;'
       parameters:
         - id: url
-          description: 'The full URL to be opened including protocol (e.g., https), and port number, if any.'
+          description: >-
+            The full URL to be opened including protocol (http or https), and port number, if any. Other protocols like
+            mailto aren't supported.
           type: string
       return:
         type: void

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