Utilizzare l'API DModal per rendere finestre modali (aka popup/dialoghi) in Discourse

[Discourse]

Discourse 3.1.0.beta6 introduce una nuova API basata su componenti per <DModal>.

Questa sostituisce la vecchia API basata sui controller, ora deprecata. Se hai modali esistenti che utilizzano le vecchie API, consulta la guida alla migrazione qui.

Rendering di un Modale

I modali vengono resi includendo il componente <DModal> in un template Handlebars. Se non hai già un template adatto, consulta Using Plugin Outlet Connectors from a Theme or Plugin.

Un modale semplice potrebbe apparire così:

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

{{#if this.modalIsVisible}}
  <DModal @title="Il Mio Modale" @closeModal={{fn (mut this.modalIsVisible) false}}>
    Ciao mondo, questo è un contenuto all'interno di un modale
  </DModal>
{{/if}}

L’helper mut viene utilizzato qui come modo specifico per HBS per impostare un valore. Potresti anche impostare modalIsVisible utilizzando qualsiasi altro metodo standard di Ember.

Questo esempio creerà un modale semplice come questo:

Incapsulamento in un componente

Prima di introdurre ulteriori complessità, è generalmente meglio incapsulare il tuo nuovo modale in una definizione di componente dedicata. Spostiamo il contenuto di <DModal> all’interno di un nuovo componente <MyModal />.

// components/my-modal.gjs
<template>
  <DModal @title="Il Mio Modale" @closeModal={{@closeModal}}>
    Ciao mondo, questo è un contenuto all'interno di un modale
  </DModal>
</template>

Aggiornare questo file .gjs a un componente basato su classi ti consentirà di introdurre logica e stato più complessi.

Per utilizzare il nuovo componente, aggiorna il punto di chiamata per fare riferimento ad esso, assicurandoti di passare un argomento @closeModal.

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

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

Aggiunta di un piè di pagina

Molti modali includono una qualche forma di invito all’azione. In Discourse, questi tendono a essere posizionati nella parte inferiore del modale. Per abilitare questa funzionalità, DModal dispone di diversi “blocchi denominati” in cui è possibile renderizzare contenuto. Ecco l’esempio aggiornato per includere due pulsanti nel piè di pagina, uno dei quali è il nostro pulsante standard DModalCancel.

<DModal @title="Il Mio Modale" @closeModal={{@closeModal}}>
  <:body>
    Ciao mondo, questo è un contenuto all'interno di un modale
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Invia" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

Rendering di un modale da un contesto non HBS

Idealmente, le istanze di <DModal> dovrebbero essere renderizzate all’interno di un template Ember utilizzando la tecnica dichiarativa dimostrata sopra. Se ciò non è fattibile per il tuo caso d’uso, è possibile farlo iniettando il servizio modal e chiamando modal.show().

Assicurati di aver incapsulato il tuo modale in un componente dedicato come descritto sopra. Quindi, attiva il modale passando un riferimento alla classe del tuo componente a showModal:

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

// (inietta il servizio modal nel luogo appropriato)

// Aggiungi questa chiamata ogni volta che desideri aprire il modale.
// Un argomento `@closeModal` verrà passato automaticamente al tuo componente.
this.modal.show(MyModal);

// Opzionalmente, passa un parametro '`model`'. Passato come `@model` al tuo componente.
// Questo può includere dati e anche azioni/callback da utilizzare nel tuo Modale.
this.modal.show(MyModal, {
  model: { topic: this.topic, someAction: this.someAction },
});

// `modal.show()` restituisce una promessa, quindi puoi attendere che venga chiuso
// Si risolverà con i dati passati all'azione `@closeModal`
const result = await this.modal.show(MyModal);

Ancora più personalizzabile!

<DModal> dispone di diversi blocchi denominati e argomenti. Consulta la guida agli stili interattiva per gli argomenti e l’implementazione del template d-modal per i blocchi denominati.

---

Questo documento è sottoposto a controllo versione: suggerisci modifiche su GitHub.