Usando la API DModal para renderizar ventanas modales (también llamadas popups/dialogos) en Discourse

[Discourse]

Discourse 3.1.0.beta6 incluye una nueva API basada en componentes para el elemento <DModal>.

Esto reemplaza a la antigua API basada en controladores, que ahora está obsoleta. Si tienes modales existentes que utilizan las APIs antiguas, consulta la guía de migración aquí.

Renderizado de un modal

Los modales se renderizan incluyendo el componente <DModal> en una plantilla de Handlebars. Si aún no tienes una plantilla adecuada, consulta Using Plugin Outlet Connectors from a Theme or Plugin.

Un modal simple se vería algo así:

<DButton
  @translatedLabel="Mostrar modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <DModal @title="Mi modal" @closeModal={{fn (mut this.modalIsVisible) false}}>
    Hola mundo, este es algún contenido dentro de un modal
  </DModal>
{{/if}}

El helper mut se utiliza aquí como una forma exclusiva de HBS para establecer un valor. También podrías establecer modalIsVisible utilizando cualquier otro método estándar de Ember.

Este ejemplo creará un modal simple como este:

Envolver en un componente

Antes de introducir más complejidad, por lo general es mejor encapsular tu nuevo modal en su propia definición de componente. Movamos el contenido de <DModal> dentro de un nuevo componente <MyModal />.

// components/my-modal.gjs
<template>
  <DModal @title="Mi modal" @closeModal={{@closeModal}}>
    Hola mundo, este es algún contenido dentro de un modal
  </DModal>
</template>

Actualizar este archivo .gjs a un componente basado en clases te permitirá introducir lógica y estado más complejos.

Para aprovechar el nuevo componente, actualiza el sitio de llamada para referenciarlo, asegurándote de pasar el argumento @closeModal.

<DButton
  @translatedLabel="Mostrar modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}

Agregar un pie de página

Muchos modales tienen algún tipo de llamada a la acción. En Discourse, estos suelen ubicarse en la parte inferior del modal. Para hacer esto posible, DModal tiene varios «bloques nombrados» en los que se puede renderizar contenido. Aquí está el ejemplo actualizado para incluir dos botones en el pie de página, uno de los cuales es nuestro botón estándar DModalCancel.

<DModal @title="Mi modal" @closeModal={{@closeModal}}>
  <:body>
    Hola mundo, este es algún contenido dentro de un modal
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Enviar" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

Renderizado de un modal desde un contexto no HBS

Idealmente, las instancias de <DModal> deben renderizarse desde dentro de una plantilla de Ember utilizando la técnica declarativa demostrada anteriormente. Si eso no es viable para tu caso de uso, se puede hacer inyectando el servicio modal y llamando a modal.show().

Asegúrate de haber encapsulado tu modal en su propio componente como se describió anteriormente. Luego, activa el modal pasando una referencia de tu clase de componente a showModal:

import MyModal from "discourse/components/my-modal";

// (inyecta el servicio modal en el lugar correspondiente)

// Agrega esta llamada cada vez que quieras abrir el modal.
// Se pasará automáticamente un argumento `@closeModal` a tu componente.
this.modal.show(MyModal);

// Opcionalmente, pasa un parámetro `model`. Se pasará como `@model` a tu componente.
// Esto puede incluir datos, así como acciones/callbacks para que tu modal los utilice.
this.modal.show(MyModal, {
  model: { topic: this.topic, someAction: this.someAction },
});

// `modal.show()` devuelve una promesa, por lo que puedes esperar a que se cierre.
// Se resolverá con los datos pasados a la acción `@closeModal`.
const result = await this.modal.show(MyModal);

¡Más personalización!

<DModal> tiene varios bloques nombrados y argumentos.

Argumentos

Arg	Propósito
@closeModal	Requerido para que aparezca la interfaz de cierre.
@title	Renderiza <h1 id="discourse-modal-title">; configura aria-labelledby.
@subtitle	Texto pequeño debajo del título.
@flash / @flashType	Alerta en línea en la parte superior del modal (DFlashMessage).
@hideHeader, @hideFooter	Oculta regiones completas.
@headerClass, @bodyClass	Clase adicional en los envoltorios del encabezado/cuerpo.
@dismissable	Verdadero por defecto cuando se establece @closeModal. Desactiva la tecla Esc / clic en el fondo / X.
@autofocus	Verdadero por defecto. Enfoca automáticamente el primer elemento enfocable mediante dTrapTab.
@submitOnEnter	Verdadero por defecto. Enter hace clic en .d-modal__footer .btn-primary a menos que el enfoque esté en un formulario / textarea / select-kit.
@beforeClose	async ({ initiatedBy }) => boolean. Devuelve false para cancelar el cierre (por ejemplo, confirmación de formulario no guardado).
@hidden	Pausa el manejo del teclado; se utiliza cuando un modal anidado está encima.
@tagName	"div" (predeterminado) o "form". Usa "form" para formularios para que funcione el envío nativo.

Bloques

Block	Posición	Cuándo usarlo
default / :body	Área de contenido principal	Área predeterminada
:aboveHeader	Muy arriba, antes del encabezado	Raramente necesario; para contenido que debe ubicarse por encima de la barra de título (por ejemplo, un banner).
:headerAboveTitle	Dentro del encabezado, antes del título	Presente pero sin usar. Raramente necesario.
:belowModalTitle	Dentro de .d-modal__title, después del <h1>	Excelente posición para información meta suplementaria.
:headerBelowTitle	Dentro del encabezado, después del bloque del título	Pestañas, subnavegación o campo de búsqueda que forman parte del encabezado.
:headerPrimaryAction	Lado derecho del encabezado solo en móviles	Reemplaza el botón de cierre X con una acción principal (por ejemplo, «Guardar»). También renderiza automáticamente un botón «Cancelar» a la izquierda y agrega .--has-primary-action al encabezado.
:belowHeader	Entre el encabezado y el cuerpo	Contenido de subencabezado persistente (por ejemplo, búsqueda) que está fuera del cuerpo desplazable, para que sea fijo.
:aboveFooter	Entre el cuerpo y el pie de página	Suprimido cuando se establece @hideFooter. Úsalo para contenido vinculado al pie de página pero fuera de él. También es raro.
:footer	Barra de acciones inferior	Botones primarios y secundarios. El primer .btn-primary aquí es lo que activa Enter.
:belowFooter	Después del pie de página	Raramente necesario; ignora @hideFooter. Útil para texto de estado fuera del área del pie de página con borde.

Fuentes: la guía de estilo interactiva para argumentos, y la implementación de la plantilla d-modal para bloques nombrados.

CSS

Usa las clases .d-modal como ancla para sobrescribir el núcleo y evita el selector heredado .modal.

4 modificadores disponibles:

• .--large establece el ancho máximo en 800px (solo escritorio)
• .--max establece el ancho máximo en 90vw (solo escritorio)
• .has-search establece la altura fija (80vh): diseñado para modales con sistema de búsqueda/filtro para evitar cambios de altura según la longitud de los resultados (solo escritorio)
• .--stacked establece los botones del pie de página en apilamiento (solo móviles)

---

Este documento está bajo control de versiones: sugiere cambios en GitHub.