Improve the documentation of dialogs, reformat content

diff --git a/docs/javascript/components_confirmation.md b/docs/javascript/components_confirmation.md
index d9a19540def71decc7b9953df656183d7aa3d7a3..a41b78ff21c6f9135bf78cd06445f63635acd64b 100644 (file)
--- a/docs/javascript/components_confirmation.md
+++ b/docs/javascript/components_confirmation.md
@@ -12,7 +12,7 @@ const result = await confirmationFactory()
   .custom("Do you want a cookie?")
   .withoutMessage();
 if (result) {
-    // User has confirmed the dialog.
+  // User has confirmed the dialog.
 }
 ```
 
@@ -31,10 +31,14 @@ Destructive actions are those that cannot be undone and either cause a permanent
 All questions should be phrased in one or two ways depending on the action.
 
 Destructive action:
-> Are you sure you want to […]?
+
+> Are you sure you want to delete “Example Object”?
+> (German) Wollen Sie „Beispiel-Objekt” wirklich löschen?
 
 All other actions:
-> Do you want to […]
+
+> Do you want to move “Example Object” to the trash bin?
+> (German) Möchten Sie „Beispiel-Objekt“ in den Papierkorb verschieben?
 
 ## Available Presets
 
@@ -47,10 +51,29 @@ Soft deleting objects with an optional input field for a reason:
 
 ```ts
 const askForReason = true;
-const { result, reason } = await confirmationFactory()
-  .softDelete(theObjectName, askForReason);
+const { result, reason } = await confirmationFactory().softDelete(
+  theObjectName,
+  askForReason
+);
+if (result) {
+  console.log(
+    "The user has requested a soft delete, the following reason was provided:",
+    reason
+  );
+}
+```
+
+The `reason` will always be a string, but with a length of zero if the `result` is `false` or if no reason was requested.
+You can simply omit the value if you do not use the reason.
+
+```ts
+const askForReason = false;
+const { result } = await confirmationFactory().softDelete(
+  theObjectName,
+  askForReason
+);
 if (result) {
-    console.log("The user has requested a soft delete, the following reason was provided:", reason);
+  console.log("The user has requested a soft delete.");
 }
 ```
 
@@ -59,10 +82,9 @@ if (result) {
 Restore a previously soft deleted object:
 
 ```ts
-const result = await confirmationFactory()
-  .restore(theObjectName);
+const result = await confirmationFactory().restore(theObjectName);
 if (result) {
-    console.log("The user has requested to restore the object.");
+  console.log("The user has requested to restore the object.");
 }
 ```
 
@@ -71,9 +93,8 @@ if (result) {
 Permanently delete an object, will inform the user that the action cannot be undone:
 
 ```ts
-const result = await confirmationFactory()
-  .delete(theObjectName);
+const result = await confirmationFactory().delete(theObjectName);
 if (result) {
-    console.log("The user has requested to delete the object.");
+  console.log("The user has requested to delete the object.");
 }
 ```

diff --git a/docs/javascript/components_dialog.md b/docs/javascript/components_dialog.md
index 89854a29025bfc7bbf016abb4661cc0d9b6be991..a706dd3c757eff57547180e0e0c8828e87198404 100644 (file)
--- a/docs/javascript/components_dialog.md
+++ b/docs/javascript/components_dialog.md
@@ -1,6 +1,6 @@
 # Dialogs - JavaScript API
 
-Modal dialogs are a powerful tool to draw the viewerâ\80\98s attention to an important message, question or form.
+Modal dialogs are a powerful tool to draw the viewerâ\80\99s attention to an important message, question or form.
 Dialogs naturally interrupt the workflow and prevent the navigation to other sections by making other elements on the page inert.
 
 WoltLab Suite 6.0 ships with four different types of dialogs.
@@ -8,17 +8,16 @@ WoltLab Suite 6.0 ships with four different types of dialogs.
 ## Dialogs Without Controls
 
 Dialogs may contain just an explanation or extra information that should be presented to the viewer without requiring any further interaction.
+The dialog can be closed via the “X” button or by clicking the modal backdrop.
 
 ```ts
-const dialog = dialogFactory()
-  .fromHtml("<p>Hello World</p>")
-  .withoutControls();
+const dialog = dialogFactory().fromHtml("<p>Hello World</p>").withoutControls();
 dialog.show("Greetings from my dialog");
 ```
 
 ### When to Use
 
-The short answer is: Donâ\80\98t.
+The short answer is: Donâ\80\99t.
 
 Dialogs without controls are an anti-pattern because they only contain content that does not require the modal appearance of a dialog.
 More often than not dialogs are used for this kind of content because they are easy to use without thinking about better ways to present the content.
@@ -36,7 +35,7 @@ An alert will only provide a single button to acknowledge the dialog and must no
 const dialog = dialogFactory()
   .fromHtml("<p>ERROR: Something went wrong!</p>")
   .asAlert();
-dialog.show("Server Error")
+dialog.show("Server Error");
 ```
 
 ### When to Use
@@ -55,7 +54,9 @@ Confirmation dialogs are supported through a separate factory function that prov
 
 The most common type of dialogs are prompts that are similar to confirmation dialogs, but without the restrictions and with a regular title.
 These dialogs can be used universally and provide a submit and cancel button by default.
+
 In addition they offer an “extra” button that is placed to the left of the default buttons are can be used to offer a single additional action.
+A possible use case for an “extra” button would be a dialog that includes an instance of the WYSIWYG editor, the extra button could be used to trigger a message preview.
 
 ### Code Example
 
@@ -68,7 +69,7 @@ In addition they offer an “extra” button that is placed to the left of the d
       <label for="myInput">Title</label>
     </dt>
     <dd>
-      <input type="text" name="myInput" id="myInput" value="" required>
+      <input type="text" name="myInput" id="myInput" value="" required />
     </dd>
   </dl>
 </template>
@@ -76,10 +77,8 @@ In addition they offer an “extra” button that is placed to the left of the d
 
 ```ts
 document.getElementById("showMyDialog")!.addEventListener("click", () => {
-  const dialog = dialogFactory()
-    .fromId("myDialog")
-    .asPrompt();
-  
+  const dialog = dialogFactory().fromId("myDialog").asPrompt();
+
   dialog.addEventListener("primary", () => {
     const myInput = document.getElementById("myInput");
 
@@ -233,7 +232,3 @@ dialog.addEventListener("validate", (event) => {
   }
 });
 ```
-
-## Code Examples
-
-TODO