Add an example to keep track of a dialog instance

diff --git a/docs/javascript/components_dialog.md b/docs/javascript/components_dialog.md
index fc56edbabf9f935b03b0c3c5cfa28f0e59828d7e..774f4b8d3dcd4575ba4472f8375fc59bca2c4794 100644 (file)
--- a/docs/javascript/components_dialog.md
+++ b/docs/javascript/components_dialog.md
@@ -176,6 +176,47 @@ dialog.content.append(p);
 const input = dialog.content.querySelector('input[type="text"]');
 ```
 
+### Managing an Instance of a Dialog
+
+The old API for dialogs implicitly kept track of the instance by binding it to the `this` parameter as seen in calls like `UiDialog.open(this);`.
+The new implementation requires to you to keep track of the dialog on your own.
+
+```ts
+class MyComponent {
+  #dialog?: WoltlabCoreDialogElement;
+
+  constructor() {
+    const button = document.querySelector(".myButton") as HTMLButtonElement;
+    button.addEventListener("click", () => {
+      this.#showGreeting(button.dataset.name);
+    });
+  }
+
+  #showGreeting(name: string | undefined): void {
+    const dialog = this.#getDialog();
+
+    const p = dialog.content.querySelector("p")!;
+    if (name === undefined) {
+      p.textContent = "Hello World";
+    } else {
+      p.textContent = `Hello ${name}`;
+    }
+
+    dialog.show("Greetings!");
+  }
+
+  #getDialog(): WoltlabCoreDialogElement {
+    if (this.#dialog === undefined) {
+      this.#dialog = dialogFactory()
+        .fromHtml("<p>Hello from MyComponent</p>")
+        .withoutControls();
+    }
+
+    return this.#dialog;
+  }
+}
+```
+
 ### Event Access
 
 You can bind event listeners to specialized events to get notified of events and to modify its behavior.

diff --git a/docs/javascript/new-api_dialogs.md b/docs/javascript/new-api_dialogs.md
index 66dff7eb8cb0edfb0946b83c179ff586aae22ffc..6de443edeb55a50714fa0be1b947c95dbb02ce0c 100644 (file)
--- a/docs/javascript/new-api_dialogs.md
+++ b/docs/javascript/new-api_dialogs.md
@@ -1,6 +1,6 @@
 # Dialogs - JavaScript API
 
-!!! info This API has been deprecated in WoltLab Suite 6.0, please refer to the new [dialog implementation](components_dialog.md).
+!!! info "This API has been deprecated in WoltLab Suite 6.0, please refer to the new [dialog implementation](components_dialog.md)."
 
 ## Introduction
 

diff --git a/mkdocs.yml b/mkdocs.yml
index a26d971bf66c936951ac6266077565daddbebf1d..d09c48bef8b6d11b7457095ce0083240fcd6ad17 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -118,6 +118,7 @@ nav:
       - 'TypeScript and JavaScript': 'migration/wsc55/javascript.md'
       - 'Templates': 'migration/wsc55/templates.md'
       - 'Icons': 'migration/wsc55/icons.md'
+      - 'Dialogs': 'migration/wsc55/dialogs.md'
       - 'Third Party Libraries': 'migration/wsc55/libraries.md'
       - 'Deprecations and Removals': 'migration/wsc55/deprecations_removals.md'
     - 'From WoltLab Suite 5.4':