Add more guidelines for the migration of dialogs

diff --git a/docs/migration/wsc55/dialogs.md b/docs/migration/wsc55/dialogs.md
index 608dd3c67d950b5c7a1ad80cbfd5a06b59868e27..f7a486f98b79ee73926dcebba7876f2c15f4449f 100644 (file)
--- a/docs/migration/wsc55/dialogs.md
+++ b/docs/migration/wsc55/dialogs.md
@@ -23,7 +23,7 @@ The `_dialogSetup()` method was complex, offered subpar auto completition suppor
 
 ### `source`
 
-The source of a dialog is provided directly through the fluent API of `dialogFactory()` which provides methods to spawn dialogs using elements, HTML strings or completely empty.
+The source of a dialog is provided directly through the fluent API of [`dialogFactory()`](components_dialog.md) which provides methods to spawn dialogs using elements, HTML strings or completely empty.
 
 The major change is the removal of the AJAX support as the content source, you should use [`dboAction()`](new-api_ajax.md) instead and then create the dialog.
 
@@ -74,8 +74,43 @@ dialog.addEventListener("primary", () => {
 });
 ```
 
+## Changes to the Template
+
+Both the old and the new API support the use of existing elements to create dialogs.
+It is recommended to use `<template>` in this case which will never be rendered and has a well-defined role.
+
+```html
+<!-- Previous -->
+<div id="myDialog" style="display: none">
+  <!-- … -->
+</div>
+
+<!-- Use instead -->
+<template id="myDialog">
+    <!-- … -->
+</template>
+```
+
+Dialogs have historically been using the same HTML markup that regular pages do, including but not limited to the use of sections.
+For dialogs that use only a single container it is recommend to drop the section entirely.
+
+If your dialog contain multiple sections it is recommended to skip the title of the first section.
+
+### `.formSubmit`
+
+Form controls are no longer defined through the template, instead those are implicitly generated by the new dialog API.
+Please see the explanation on the four different [dialog types](components_dialog.md) to learn more about form controls.
+
 ## Migration by Example
 
 There is no universal pattern that fits every case, because dialogs vary greatly between each other and the required functionality causes the actual implementation to be different.
 
 As an example we have migrated the dialog to create a new box to use the new API. It uses a prompt dialog that automagically adds form controls and fires an event once the user submits the dialog. You can find the commit [3a9210f229f6a2cf5e800c2c4536c9774d02fc86](https://github.com/WoltLab/WCF/commit/3a9210f229f6a2cf5e800c2c4536c9774d02fc86?diff=split) on GitHub.
+
+The changes can be summed up as follows:
+
+1. Use a `<template>` element for the dialog content.
+2. Remove the `.formSubmit` section from the HTML.
+3. Unwrap the contents by stripping the `.section`.
+4. Create and store the reference to the dialog in a property for later re-use.
+4. Interact with the dialog’s `.content` property and make use of an event listener to handle the user interaction.