Generic confirmation dialog containing a reason-field

[mutec]

It would be good to have a pre-defined dialog containing a reason-field like softDelete() for other purposes. The question/title should be provided per function-argument.
While preparing several packages for WSC 6, I had to implement a function like softDelete() multiple times yet; just because I need a dedicated title and the additional reason-field.

async customReason(question?: string, askForReason = false, reasonFieldLabel = ""): Promise<ResultCustomReason> {
    // dummy
}

[dtdesign]

Can you please be more specific on your use case? Do you simply happen to need a “free text” input and it just happens that the “reason” of softDelete() is just that?

The purpose of these presets is to provide ready-made solutions for typical use-cases and not to provide a general toolchain for generation dialog forms. If you find yourself requiring one or more form element, you should rather make use of the form builder dialogs, which combine both the form builder and the new dialog API.

[mutec]

I'm doing several things like closing, moving to trash, disabling, banning that allow to store why that action is done (like the moving to trash dialog). All those actions create a dialog for confirmation and providing the (optional) reason.
One way is to implement the same code about 5 times (or whenever I'm questioning for a reason). The other way would be that you implement a function that allows a custom dialog-title and provides the reason-field by default.

To be precise:

  type ResultReasonedConfirmation = {
    result: boolean;
    reason: string;
  };

  async customReason(question?: string, askForReason = false, reasonFieldLabel = ""): Promise<ResultReasonedConfirmation> {
    const dialog = dialogFactory().withoutContent().asConfirmation();

    let reason: HTMLTextAreaElement | undefined = undefined;
    if (askForReason) {
      const id = DomUtil.getUniqueId();
      const label = reasonFieldLabel ? reasonFieldLabel : getPhrase("wcf.dialog.confirmation.reason");

      const dl = document.createElement("dl");
      dl.innerHTML = `
        <dt><label for="${id}">${label}</label></dt>
        <dd><textarea id="${id}" cols="40" rows="3"></textarea></dd>
      `;
      reason = dl.querySelector("textarea")!;

      dialog.content.append(dl);
    }

    dialog.show(question);

    return new Promise<ResultReasonedConfirmation>((resolve) => {
      dialog.addEventListener("primary", () => {
        resolve({
          result: true,
          reason: reason ? reason.value.trim() : "",
        });
      });

      dialog.addEventListener("cancel", () => {
        resolve({
          result: false,
          reason: "",
        });
      });
    });
  }

As you can see the purpose isn't to create (custom) forms, but providing a function what shows a confirmation for a custom "question" and asks for a reason.
Having a short look at the language files of the Core, I found those use-cases:

• banning a user
• disabling a user's signature
• disabling a user's avatar
• disabling a user's cover photo
• deleting moderated content

To be honest, I'd replace the softDelete() function completely by a dialog with textarea. Replacing a placeholder in a phrase is no magic, but saving those 30 lines (multiple times) improves writing code and the page's performance.

[dtdesign]

Thank you for clarifying your use-case, it helps a lot to first understand what is needed to figure out what the best approach is.

Having a short look at the language files of the Core, I found those use-cases: […]

These are not applicable, because they offer a much more complex UI. Besides offering a reason they also include the ability to limit the duration of those actions, before the restrictions are automatically lifted. These should use the Psr15DialogForm implementation instead which offers a simple API to create and validate the form fields.

This also outline the core issue here: Such a ready-made component is only useful if you have only this element and nothing else. Once you add extra logic or elements you MUST migrate to the form builder, because otherwise you start reinventing the form builder in JS, while still having to deal with the full validation on the server side.

My intention was to create an API that is easy to use and maintain while also being slim enough without overlapping too much with existing APIs. That said, the primary difference between a confirmation to disable content and the removal is the extra description that warns about the consequences. Maybe I can create a more generalized prefab that offers an optional description, so that the removal dialog is just a more specialized variant of it.

[dtdesign]

@mutec I have implemented this in 75c9220 by adding the method withReason(question: string, askForReason: boolean) which works like the already known softDelete() prefab.

This is intended to provide a shortcut for confirmation prompts that only require an (optional) reason field. If you do require additional input fields, then you should use a PSR-15 form builder instead.