Discourse include centinaia di Plugin Outlet che possono essere utilizzati per iniettare nuovo contenuto o sostituire contenuto esistente nell’interfaccia utente di Discourse. Gli ‘argomenti dell’outlet’ sono resi disponibili in modo che il contenuto possa essere personalizzato in base al contesto.
Scegliere un outlet
Per trovare il nome di un plugin outlet, cerca nel codice sorgente di Discourse “<PluginOutlet”, oppure utilizza il componente tema posizioni degli outlet del plugin. (es. topic-above-posts).
Outlet wrapper
Alcuni outlet nel codice sorgente sembrano <PluginOutlet @name="foo" />. Questi ti permettono di iniettare nuovo contenuto. Altri outlet ‘avvolgeranno’ un’implementazione esistente del codice sorgente in questo modo
<PluginOutlet @name="foo">
implementazione del codice sorgente
</PluginOutlet>
Definire un connettore per questo tipo di outlet ‘wrapper’ sostituirà l’implementazione del codice sorgente. Solo un tema/plugin attivo può contribuire con un connettore per un outlet wrapper del plugin.
Per gli outlet wrapper del plugin, puoi rendere l’implementazione originale del codice sorgente utilizzando la parola chiave {{yield}}. Questo può essere utile se vuoi sostituire l’implementazione del codice sorgente solo in determinate condizioni, o se desideri avvolgerla in qualcos’altro.
Definire il connettore
Una volta scelto un outlet, decidi un nome per il tuo connettore. Questo deve essere univoco tra tutti i temi/plugin installati in una determinata community. es. brand-official-topics
Nel tuo tema/plugin, definisci un nuovo connettore .gjs con un percorso formattato in questo modo:
{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs
{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.gjs
Il contenuto di questi file verrà reso come un componente Ember. Per informazioni generali su Ember e il formato .gjs, consulta le guide di Ember.
Per il nostro ipotetico connettore “argomenti ufficiali del brand”, il file potrebbe sembrare
<template>
<div class="alert alert-info">
Questo argomento è stato creato da un membro del
<a href="https://discourse.org/team">Team Discourse</a>
</div>
</template>
Utilizzare gli argomenti dell’outlet
Gli Outlet del Plugin forniscono informazioni sul contesto circostante tramite @outletArgs. Gli argomenti passati a ciascun outlet variano. Un modo semplice per visualizzare gli argomenti è aggiungere questo al tuo template:
{{log @outletArgs}}
Questo registrerà gli argomenti nella console di sviluppo del browser. Appariranno come un oggetto Proxy - per esplorare l’elenco degli argomenti, espandi il [[Target]] del proxy.
Nel nostro esempio topic-above-posts, l’argomento reso è disponibile sotto @outletArgs.model. Quindi possiamo aggiungere il nome utente del membro del team in questo modo:
<template>
<div class="alert alert-info">
Questo argomento è stato creato da
{{@outletArgs.model.details.created_by.username}}
(un membro del
<a href="https://discourse.org/team">Team Discourse</a>)
</div>
</template>
Aggiungere logica più complessa
A volte, un semplice template non è sufficiente. Per aggiungere logica Javascript al tuo connettore, aggiorna il tuo file .gjs per esportare un componente basato su classe. Questo funziona esattamente come qualsiasi altra definizione di componente e può includere iniezioni di servizi.
Nel nostro esempio topic-above-posts, potremmo voler rendere l’utente in modo diverso in base all’impostazione del sito ‘prioritize username in ux’. Il file .gjs potrebbe sembrare qualcosa del genere:
.../connectors/topic-above-posts/brand-official-topic.gjs:
import Component from "@glimmer/component";
import { service } from "@ember/service";
export default class BrandOfficialTopics extends Component {
@service siteSettings;
get displayName() {
const user = this.args.outletArgs.model.details.created_by;
if (this.siteSettings.prioritize_username_in_ux) {
return user.username;
} else {
return user.name;
}
}
<template>
<div class="alert alert-info">
Questo argomento è stato creato da
{{this.displayName}}
(un membro del
<a href="https://discourse.org/team">Team Discourse</a>)
</div>
</template>
}
Rendering condizionale
Se vuoi che il tuo contenuto venga reso solo in determinate condizioni, spesso è sufficiente avvolgere il tuo template con un blocco {{#if}} handlebars. Se non è sufficiente, potresti voler utilizzare il hook shouldRender per controllare se il template del tuo connettore viene reso affatto.
Innanzitutto, assicurati di avere un connettore .gjs basato su classe come descritto sopra. Quindi, aggiungi una funzione static shouldRender(). Estendendo il nostro esempio:
import Component from "@glimmer/component";
export default class BrandOfficialTopics extends Component {
static shouldRender(outletArgs, helper) {
const firstPost = outletArgs.model.postStream.posts[0];
return firstPost.primary_group_name === "team";
}
// ... (qualsiasi altra logica)
<template>
{{! ... }}
</template>
}
Ora il connettore verrà reso solo quando il primo post dell’argomento è stato creato da un membro del team.
shouldRender viene valutato in un contesto di autotracking Glimmer. Le modifiche future a qualsiasi proprietà referenziata (es. outletArgs) causeranno la ri-valutazione della funzione.
Introdurre nuovi outlet
Se hai bisogno di un outlet che non esiste ancora, sentiti libero di fare una pull request, o apri un argomento in Development.
Questo documento è sotto controllo di versione - suggerisci modifiche su github.