[All hosts] (dialog) Move modal dialog article (OfficeDev#4313)

* Resolve merge conflicts

* link typo

* Resolve merge conflicts

* Transfer modal dialog article to excludes folder

---------

Co-authored-by: Rick Kirkham <[email protected]>

Author: samantharamon

docs/develop/dialog-api-in-office-add-ins.md

@@ -27,7 +27,7 @@ The dialog box always opens in the center of the screen. The user can move and r
 
 The Office JavaScript APIs include a [Dialog](/javascript/api/office/office.dialog) object and two functions in the [Office.context.ui namespace](/javascript/api/office/office.ui).
 
-To open a dialog box, your code, typically a page in a task pane, calls the [displayDialogAsync](/javascript/api/office/office.ui) method and passes to it the URL of the resource that you want to open. The page on which this method is called is known as the "host page". For example, if you call this method in script on index.html in a task pane, then index.html is the host page of the dialog box that the method opens.
+To open a dialog box, your code, typically a page in a task pane, calls the [displayDialogAsync](/javascript/api/office/office.ui#office-office-ui-displaydialogasync-member(1)) method and passes to it the URL of the resource that you want to open. The page on which this method is called is known as the "host page". For example, if you call this method in script on index.html in a task pane, then index.html is the host page of the dialog box that the method opens.
 
 The resource that is opened in the dialog box is usually a page, but it can be a controller method in an MVC application, a route, a web service method, or any other resource. In this article, 'page' or 'website' refers to the resource in the dialog box. The following code is a simple example.
 
@@ -231,7 +231,7 @@ Office.context.ui.messageParent("Some message", { targetOrigin: "*" });
 > [!TIP]
 > The `DialogMessageOptions` parameter was added to the `messageParent` method as a required parameter in mid-2021. Older add-ins that send a cross-domain message with the method no longer work until they are updated to use the new parameter. Until the add-in is updated, *in Office on Windows only*, users and system administrators can enable those add-ins to continue working by specifying the trusted domains with a registry setting: **HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains**. To do this, create a file with a `.reg` extension, save it to the Windows computer, and then double-click it to run it. The following is an example of the contents of such a file.
 >
-> ```
+> ```properties
 > Windows Registry Editor Version 5.00
 > 
 > [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
@@ -363,7 +363,7 @@ For example, your code could use the [Office.onReady or Office.initialize functi
 > [!TIP]
 > The `DialogMessageOptions` parameter was added to the `messageChild` method as a required parameter in mid-2021. Older add-ins that send a cross-domain message with the method no longer work until they are updated to use the new parameter. Until the add-in is updated, *in Office on Windows only*, users and system administrators can enable those add-ins to continue working by specifying the trusted domains with a registry setting: **HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains**. To do this, create a file with a `.reg` extension, save it to the Windows computer, and then double-click it to run it. The following is an example of the contents of such a file.
 >
-> ```
+> ```properties
 > Windows Registry Editor Version 5.00
 > 
 > [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]

docs/excludes/modal-dialog-tip.md

@@ -0,0 +1,4 @@
+<!-- Add to https://learn.microsoft.com/office/dev/add-ins/develop/dialog-api-in-office-add-ins when modal dialog feature is deployed.  -->
+
+> [!TIP]
+> If the child dialog is the [preview modal dialog](modal-dialog.md), then a call of `messageChild` can't be triggered by user interaction with the add-in's task pane or add-in commands, because user interaction is blocked while the modal dialog is open. So, if your dialog use case requires messaging from the parent to the dialog, you will nearly always need to use the non-modal dialog API. However, calling `Office.context.ui.messageParent` in the dialog triggers the `DialogMessageReceived` event in the parent, and code in the handler for that event can call `messageChild`.

docs/excludes/modal-dialog.md

@@ -0,0 +1,23 @@
+---
+title: Use the Office modal dialog API in your Office Add-ins
+description: Learn the basics of creating a modal dialog box in an Office Add-in.
+ms.date: 04/30/2022
+ms.topic: how-to
+ms.localizationpriority: medium
+---
+
+# Use the Office modal dialog API in Office Add-ins (preview)
+
+There's a *modal* dialog API available in preview. It shouldn't be used in production add-ins, but we encourage you to experiment with it.
+
+[!INCLUDE [Information about using preview APIs](../includes/using-preview-apis-host.md)]
+
+When the modal dialog is open, the user experiences the following behavior.
+
+- The user can't interact with the Office document.
+- The user can't interact with Office application (for example, Excel or Word).
+- The user also can't interact with any other instances of the same Office application.
+- The user can't interact with the add-in's task pane, if any, or custom add-in commands, if any.
+- Event handlers registered by the add-in do run, but the only events that can occur are those that don't require user interaction with the document, the Office application, or the add-in, other than the dialog itself. For example, calling `Office.context.ui.messageParent` in the dialog triggers the `DialogMessageReceived` event in the parent.
+
+Everything in the article [Use the Office dialog API in your Office Add-ins](dialog-api-in-office-add-ins.md), including the **Advanced topics and special scenarios** and **Next steps** sections (and the articles that are linked to in those sections), applies to the modal dialog as well as the non-modal dialog except that the method that opens the modal dialog is [Office.context.ui.displayModalDialogAsync](/javascript/api/office/office.ui#office-office-ui-displaymodaldialogasync-member(1)) instead of [Office.context.ui.displayDialogAsync](/javascript/api/office/office.ui#office-office-ui-displaydialogasync-member(1)). In all the code examples, and the add-in samples linked to in the **Samples** section, you can simply replace calls of `displayDialogAsync` with calls of `displayModalDialogAsync`.