Uso de la API DModal para renderizar ventanas modales (p. ej. popups/diálogos) en Discourse

Discourse 3.1.0.beta6 incluye una nueva API de componentes basada en <DModal>. DModal es parte del UI kit y se importa desde discourse/ui-kit/d-modal.

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

Renderizar un Modal

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

Un modal simple tendría este aspecto:

<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 en un modal
  </DModal>
{{/if}}

:information_source: El helper mut se usa 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:

Envolverlo en un componente

Antes de introducir más complejidad, generalmente es mejor envolver tu nuevo Modal en su propia definición de Componente. Vamos a mover el código 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 en un modal
  </DModal>
</template>

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

Para utilizar el nuevo componente, actualiza la llamada para referirse a él, asegurándote de pasar un argumento @closeModal.

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

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

Añadir un pie de página

Muchos modales tienen algún tipo de llamada a la acción. En Discourse, estos tienden a estar ubicados en la parte inferior del modal. Para hacer esto posible, DModal tiene varios ‘named blocks’ (bloques con nombre) dentro de los cuales se puede renderizar contenido. Aquí tienes 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 en un modal
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Enviar" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

Renderizar un modal desde un contexto no-hbs

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

Asegúrate de haber envuelto tu modal en su propio componente como se describió anteriormente. Luego, dispara 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)

// Añade esta llamada cuando quieras abrir el modal.
// Un argumento `@closeModal` se pasará automáticamente a tu componente.
this.modal.show(MyModal);

// Opcionalmente, pasa un parámetro '`model`'. Se pasa como `@model` a tu componente.
// Puede incluir datos, y también acciones/callbacks para que los use tu Modal.
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 named blocks y argumentos.

Argumentos

Arg Propósito
@closeModal Requerido para que aparezca la UI de cierre.
@title Renderiza <h1 id="discourse-modal-title">; conecta 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 extra en los wrappers de cabecera/cuerpo.
@dismissable Verdadero por defecto cuando se establece @closeModal. Deshabilita 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 foco esté en un formulario / textarea / select-kit.
@beforeClose async ({ initiatedBy }) => boolean. Devuelve false para cancelar el cierre (p. ej. confirmación de formulario sucio).
@hidden Pausa el manejo del teclado; se usa cuando hay un modal anidado encima.
@tagName "div" (por defecto) o "form". Usa "form" para formularios para que funcione el envío nativo.

Bloques

Bloque Posición Cuándo usarlo
default / :body Área de contenido principal Área por defecto
:aboveHeader Muy arriba, antes de la cabecera Raramente necesario; para contenido que debe estar sobre la barra de título (p. ej. un banner).
:headerAboveTitle Dentro de la cabecera, 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 adicional.
:headerBelowTitle Dentro de la cabecera, después del bloque de título Pestañas, sub-navegación o campo de búsqueda que forman parte de la cabecera.
:headerPrimaryAction Lado derecho de la cabecera solo en móvil Reemplaza el botón de cierre X con una acción principal (p. ej. “Guardar”). También renderiza automáticamente un botón “Cancelar” a la izquierda y añade .--has-primary-action a la cabecera.
:belowHeader Entre la cabecera y el cuerpo Contenido persistente de sub-cabecera (p. ej. searchbar) que está fuera del cuerpo desplazable, por lo que se muestra fijo.
:aboveFooter Entre el cuerpo y el pie de página Se suprime cuando se establece @hideFooter. Úsalo para contenido vinculado al pie de página pero fuera de él. También raro.
:footer Barra de acciones inferior Botones primarios y secundarios. El primer .btn-primary aquí es lo que dispara 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 los argumentos, y la implementación de la plantilla d-modal para los named blocks.

CSS

Utiliza 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): pensado para modales con sistema de búsqueda/filtrado para evitar cambios de altura basados en la longitud de los resultados (solo escritorio)
  • . --stacked establece los botones del pie de página en apilados (solo móvil)

Este documento está controlado por versiones - sugiere cambios en github.

17 Me gusta

Se dividió una publicación en un nuevo tema: ¿Puedo mostrar una ventana modal desde head_tag