Discourse include centinaia di Plugin Outlet che possono essere utilizzati per iniettare nuovi contenuti o sostituire contenuti esistenti nell’interfaccia utente di Discourse. Gli ‘Outlet arguments’ (argomenti dell’outlet) sono resi disponibili in modo che il contenuto possa essere personalizzato in base al contesto.
Scelta di un outlet
Per trovare il nome di un plugin outlet, cerca nel core di Discourse “<PluginOutlet” oppure utilizza il componente tema plugin outlet locations. (es. topic-above-posts).
Wrapper outlets
Alcuni outlet nel core assomigliano a <PluginOutlet @name="foo" />. Questi ti permettono di iniettare nuovi contenuti. Altri outlet ‘avvolgeranno’ un’implementazione core esistente in questo modo
<PluginOutlet @name="foo">
core implementation
</PluginOutlet>
Definire un connettore per questo tipo di outlet ‘wrapper’ sostituirà l’implementazione core. Solo un tema/plugin attivo può contribuire con un connettore per un plugin outlet wrapper.
Per i plugin outlet wrapper, puoi renderizzare l’implementazione core originale usando la parola chiave {{yield}}. Questo può essere utile se vuoi sostituire l’implementazione core solo in determinate condizioni, o se desideri avvolgerla in qualcos’altro.
Definizione del template
Una volta scelto un outlet, decidi un nome per il tuo connettore. Questo deve essere univoco tra tutti i temi/plugin installati su una data community. es. brand-official-topics
Nel tuo tema/plugin, definisci un nuovo template handlebars con un percorso formattato in questo modo:
{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs
{plugin}/assets/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs
Il contenuto di questi file verrà renderizzato come un Ember Component. Per informazioni generali su Ember/Handlebars, consulta le guide di Ember.
Per il nostro ipotetico connettore “brand official topics”, il template potrebbe apparire così:
<div class="alert alert-info">
This topic was created by a member of the
<a href="https://discourse.org/team">Discourse Team</a>
</div>
Alcuni plugin outlet avvolgeranno automaticamente il tuo contenuto in un elemento HTML. Il tipo di elemento è definito da @connectorTagName sul <PluginOutlet>.
Utilizzo degli argomenti dell’outlet
I Plugin Outlet 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 stamperà gli argomenti nella console degli strumenti per sviluppatori del tuo browser. Appariranno come un oggetto Proxy - per esplorare l’elenco degli argomenti, espandi il [[Target]] del proxy.
Nel nostro esempio topic-above-posts, il topic renderizzato è disponibile sotto @outletArgs.model. Quindi possiamo aggiungere il nome utente del membro del team in questo modo:
<div class="alert alert-info">
This topic was created by
{{@outletArgs.model.details.created_by.username}}
(a member of the
<a href="https://discourse.org/team">Discourse Team</a>)
</div>
Aggiunta di logica più complessa
A volte, un semplice template handlebars non è sufficiente. Per aggiungere logica Javascript al tuo connettore, puoi definire un file Javascript adiacente al tuo template handlebars. Questo file dovrebbe esportare una definizione di componente. Questo funziona esattamente come qualsiasi altra definizione di componente e può includere iniezioni di servizi.
Definire un componente in questo modo rimuoverà l’elemento wrapper automatico connectorTagName, quindi potresti voler reintrodurre un elemento dello stesso tipo nel tuo file hbs.
Nel nostro esempio topic-above-posts, potremmo voler visualizzare l’utente in modo diverso in base all’impostazione del sito ‘prioritize username in ux’. Una definizione di componente per questo potrebbe apparire più o meno così:
.../connectors/topic-above-posts/brand-official-topic.js:
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;
}
}
}
Possiamo quindi aggiornare il template per fare riferimento al nuovo getter:
<div class="alert alert-info">
This topic was created by
{{this.displayName}}
(a member of the
<a href="https://discourse.org/team">Discourse Team</a>)
</div>
Rendering condizionale
Se vuoi che il tuo contenuto venga renderizzato solo in determinate condizioni, spesso è sufficiente avvolgere il tuo template con un blocco {{#if}} di handlebars. Se questo non è sufficiente, potresti voler usare la funzione shouldRender per controllare se il template del tuo connettore debba essere renderizzato affatto.
Innanzitutto, assicurati di avere una definizione di connettore .js come descritto sopra. Quindi, aggiungi una funzione statica static shouldRender(). Estendendo il nostro esempio:
import Component from "@glimmer/component";
import { getOwner } from "discourse-common/lib/get-owner";
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)
}
Ora il connettore verrà renderizzato solo quando il primo post del topic è stato creato da un membro del team.
shouldRender viene valutato in un contesto di autotracking Glimmer. Modifiche future a qualsiasi proprietà referenziata (es. outletArgs) causeranno la rivalutazione della funzione.
Introduzione di nuovi outlet
Se hai bisogno di un outlet che non esiste ancora, sentiti libero di creare una pull request o aprire un topic in Dev.
Questo documento è controllato tramite versione - suggerisci modifiche su github.