Improve the documentation of dialogs, provide more examples

diff --git a/docs/javascript/components_dialog.md b/docs/javascript/components_dialog.md
index 71c893b8b9c80054c07313f89a1fd5b55f4a9193..fc56edbabf9f935b03b0c3c5cfa28f0e59828d7e 100644 (file)
--- a/docs/javascript/components_dialog.md
+++ b/docs/javascript/components_dialog.md
@@ -5,6 +5,16 @@ Dialogs naturally interrupt the workflow and prevent the navigation to other sec
 
 WoltLab Suite 6.0 ships with four different types of dialogs.
 
+## Quickstart
+
+There are four different types of dialogs that each fulfill their own specialized role and that provide built-in features to make the development much easier.
+Please see the following list to make a quick decision of what kind of dialog you need.
+
+* Is this some kind of error message? Use an alert dialog.
+* Are you asking the user to confirm an action? Use a [confirmation dialog](components_confirmation.md).
+* Does the dialog contain form inputs that the user must fill in? Use a prompt dialog.
+* Do you want to present information to the user without requiring any action? Use a dialog without controls.
+
 ## Dialogs Without Controls
 
 Dialogs may contain just an explanation or extra information that should be presented to the viewer without requiring any further interaction.

diff --git a/docs/javascript/new-api_dialogs.md b/docs/javascript/new-api_dialogs.md
index f90c95ae8de8f8d73af97bac5f3689a118659387..66dff7eb8cb0edfb0946b83c179ff586aae22ffc 100644 (file)
--- a/docs/javascript/new-api_dialogs.md
+++ b/docs/javascript/new-api_dialogs.md
@@ -1,5 +1,7 @@
 # Dialogs - JavaScript API
 
+!!! info This API has been deprecated in WoltLab Suite 6.0, please refer to the new [dialog implementation](components_dialog.md).
+
 ## Introduction
 
 Dialogs are full screen overlays that cover the currently visible window area

diff --git a/docs/migration/wsc55/dialogs.md b/docs/migration/wsc55/dialogs.md
index f7a486f98b79ee73926dcebba7876f2c15f4449f..27d87be7e338009e4c5f5ea46ecdb272a2671693 100644 (file)
--- a/docs/migration/wsc55/dialogs.md
+++ b/docs/migration/wsc55/dialogs.md
@@ -11,6 +11,24 @@ A lot of research has gone into the accessibility of dialogs and the general rec
 One big issue of dialogs have been their inconsistent appearance in terms of form buttons and their (lack of) keyboard support for input fields.
 WoltLab Suite 6.0 provides a completely redesigned API that strives to make the process of creating dialogs much easier and features a consistent keyboard support out of the box.
 
+## Conceptual Changes
+
+Dialogs are a powerful tool, but as will all things, it is easy to go overboard and eventually one starts using dialogs out of convenience rather than necessity.
+In general dialogs should only be used when you need to provide information out of flow, for example, for urgent error messages.
+
+A common misuse that we are guilty of aswell is the use of dialogs to present content.
+Dialogs completely interrupt whatever the user is doing and can sometimes even hide contextual relevant content on the page.
+It is best to embed information into regular pages and either use deep links to refer to them or make use of flyovers to present the content in place.
+
+Another important change is the handling of form inputs.
+Previously it was required to manually craft the form submit buttons, handle button clicks and implement a proper validation.
+The new API provides the “prompt” type which implements all this for you and exposing JavaScript events to validate, submit and cancel the dialog.
+
+Last but not least there have been updates to the visual appearance of dialogs.
+The new dialogs mimic the appearance on modern desktop operating systems as well as smartphones by aligning the buttons to the bottom right.
+In addition the order of buttons has been changed to always show the primary button on the rightmost position.
+These changes were made in an effort to make it easier for users to adopt an already well known control concept and to improve the overall accessibility.
+
 ## Migrating to the Dialogs of WoltLab Suite 6.0
 
 The old dialogs are still fully supported and have remained unchanged apart from a visual update to bring them in line with the new dialogs.
@@ -32,9 +50,7 @@ The major change is the removal of the AJAX support as the content source, you s
 You can now access the content element directly, because everything happens in-place.
 
 ```ts
-const dialog = dialogFactory()
-  .fromHtml('<p>Hello World!</p>')
-  .asAlert();
+const dialog = dialogFactory().fromHtml("<p>Hello World!</p>").asAlert();
 
 // Do something with `dialog.content` or bind event listeners.
 
@@ -55,22 +71,21 @@ As a developer you only need to listen for the `validate` and the `primary` even
 
 ```ts
 const dialog = dialogFactory()
-  .fromId('myComplexDialogWithFormInputs')
+  .fromId("myComplexDialogWithFormInputs")
   .asPrompt();
 
 dialog.addEventListener("validate", (event) => {
-    // Validate the form inputs in `dialog.content`.
+  // Validate the form inputs in `dialog.content`.
 
-    if (validationHasFailed) {
-        event.preventDefault();
-    }
+  if (validationHasFailed) {
+    event.preventDefault();
+  }
 });
 
 dialog.addEventListener("primary", () => {
-    // The dialog has been successfully validated
-    // and was submitted by the user.
-
-    // You can access form inputs through `dialog.content`.
+  // The dialog has been successfully validated
+  // and was submitted by the user.
+  // You can access form inputs through `dialog.content`.
 });
 ```
 
@@ -87,7 +102,7 @@ It is recommended to use `<template>` in this case which will never be rendered
 
 <!-- Use instead -->
 <template id="myDialog">
-    <!-- … -->
+  <!-- … -->
 </template>
 ```
 
@@ -113,4 +128,92 @@ The changes can be summed up as follows:
 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.
+5. Interact with the dialog’s `.content` property and make use of an event listener to handle the user interaction.
+
+### Creating a Dialog Using an ID
+
+```ts
+_dialogSetup() {
+  return {
+    // …
+    id: "myDialog",
+  };
+}
+```
+
+New API
+
+```ts
+dialogFactory().fromId("myDialog").withoutControls();
+```
+
+### Using `source` to Provide the Dialog HTML
+
+```ts
+_dialogSetup() {
+  return {
+    // …
+    source: "<p>Hello World</p>",
+  };
+}
+```
+
+New API
+
+```ts
+dialogFactory().fromHtml("<p>Hello World</p>").withoutControls();
+```
+
+### Updating the HTML When the Dialog Is Shown
+
+```ts
+_dialogSetup() {
+  return {
+    // …
+    options: {
+      // …
+      onShow: (content) => {
+        content.querySelector("p")!.textContent = "Hello World";
+      },
+    },
+  };
+}
+```
+
+New API
+
+```ts
+const dialog = dialogFactory().fromHtml("<p></p>").withoutControls();
+
+// Somewhere later in the code
+
+dialog.content.querySelector("p")!.textContent = "Hello World";
+
+dialog.show("Some Title");
+```
+
+### Specifying the Title of a Dialog
+
+The title was previously fixed in the `_dialogSetup()` method and could only be changed on runtime using the `setTitle()` method.
+
+```ts
+_dialogSetup() {
+  return {
+    // …
+    options: {
+      // …
+      title: "Some Title",
+    },
+  };
+}
+```
+
+The title is now provided whenever the dialog should be opened, permitting changes in place.
+
+```ts
+const dialog = dialogFactory().fromHtml("<p></p>").withoutControls();
+
+// Somewhere later in the code
+
+dialog.show("Some Title");
+```