Sviluppare un plugin in Discourse può essere davvero semplice, una volta che si imparano un paio di peculiarità. L’obiettivo di questo post è creare uno scheletro di plugin e introdurti alle basi.
Il tuo ambiente di sviluppo
Assicurati di avere un ambiente di sviluppo di Discourse in esecuzione sul tuo computer. Ti consiglio di usare la guida all’installazione appropriata e di tornare qui quando hai finito.
plugin.rb
Usa GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub per creare uno scheletro completo per un plugin di Discourse nella tua directory plugins
Lo scheletro è ora incluso nel core di Discourse,
rake plugin:create[nome-plugin]creerà un plugin usando lo scheletro
Quando Discourse si avvia, cerca nella directory plugins sottodirectory contenenti un file plugin.rb. Il file plugin.rb ha due scopi: è il manifesto del tuo plugin con le informazioni richieste riguardo al tuo plugin, inclusi: il nome, i contatti e una descrizione. Il secondo scopo è inizializzare qualsiasi codice Ruby necessario per eseguire il tuo plugin.
Nel nostro caso, non aggiungeremo codice Ruby, ma abbiamo comunque bisogno di plugin.rb. Creiamo la directory basic-plugin con il file plugin.rb all’interno, con il seguente contenuto:
basic-plugin/plugin.rb
# name: basic-plugin
# about: Un plugin molto semplice per dimostrare come funzionano i plugin
# version: 0.0.1
# authors: Sviluppatore Plugin Fantastico
# url: https://github.com/yourusername/basic-plugin
Una volta creato questo file, dovresti riavviare il server locale e il plugin dovrebbe essere caricato.
Un Gotcha importante!
Se sei abituato allo sviluppo regolare di Rails, potresti notare che i plugin non sono altrettanto comodi per quanto riguarda il ricaricamento. In generale, quando apporti modifiche al tuo plugin, dovresti premere Ctrl+c per fermare il server, quindi riavviarlo usando bin/dev.
Le mie modifiche non sono state recepite! 
A volte la cache non viene svuotata completamente, soprattutto quando si creano nuovi file o si eliminano quelli vecchi. Per aggirare questo problema, rimuovi la cartella tmp e riavvia Rails. Su un Mac puoi farlo con un singolo comando: rm -rf tmp; bin/dev.
Verificare che il tuo plugin sia stato caricato
Una volta riavviato il server locale, visita l’URL /admin/plugins (assicurati di essere loggato con un account admin prima, poiché solo gli amministratori possono vedere la registrazione dei plugin).
Se tutto ha funzionato, dovresti vedere il tuo plugin nell’elenco:
Congratulazioni, hai appena creato il tuo primo plugin!
Aggiungiamo un po’ di Javascript
Al momento il tuo plugin non fa nulla. Aggiungiamo un file javascript che mostrerà una finestra di avviso quando Discourse viene caricato. Questo sarà estremamente fastidioso per qualsiasi utente e non è raccomandato come plugin reale, ma mostrerà come inserire Javascript nella nostra applicazione in esecuzione.
Crea il seguente file:
plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js
export default {
name: "alert",
initialize() {
alert("le finestre di avviso sono fastidiose!");
},
};
Ora, se riavvii il tuo server locale, dovresti vedere “le finestre di avviso sono fastidiose!” apparire sullo schermo. (Se non è apparso, consulta la sezione “Le mie modifiche non sono state recepite” sopra).
Analizziamo come ha funzionato:
-
I file Javascript posizionati in
assets/javascripts/discourse/initializersvengono eseguiti automaticamente quando l’applicazione Discourse viene caricata. -
Questo particolare file
exports un oggetto, che ha unnamee una funzioneinitialize. -
Il
namedeve essere univoco, quindi l’ho chiamato semplicementealert. -
La funzione
initialize()viene chiamata quando l’applicazione viene caricata. Nel nostro caso, tutto ciò che fa è eseguire il nostro codicealert().
Pre-caricamento dei dati per il frontend
Usa register_preloaded_data in plugin.rb per includere dati nella risposta HTML iniziale senza una richiesta aggiuntiva:
after_initialize do
register_preloaded_data("visibility") do |guardian|
{ can_access: guardian.authenticated? }
end
end
Core aggiunge come prefisso alla chiave i metadati # name: del plugin. Per il basic-plugin sopra, leggi il valore analizzato in un initializer del frontend con:
import PreloadStore from "discourse/lib/preload-store";
const visibility = PreloadStore.get("basic-plugin:visibility");
Il blocco viene eseguito per ogni caricamento della pagina che rende il layout dell’applicazione, riceve il Guardian della richiesta e restituisce un valore serializzabile in JSON. Questi valori sono separati dal payload del sito anonimo memorizzato nella cache. Restituisci nil per omettere una voce; false è incluso. I blocchi dei plugin disabilitati vengono saltati. Limita i dati sensibili all’utente richiedente tramite il Guardian.
Sei ora uno sviluppatore ufficiale di plugin Discourse!
Altro nella serie
Parte 1: Questo argomento
Parte 2: Outlet dei Plugin
Parte 3: Impostazioni del Sito
Parte 4: Configurazione di git
Parte 5: Interfacce Admin
Parte 6: Test di accettazione
Parte 7: Pubblica il tuo plugin
Questo documento è sotto controllo versione - suggerisci modifiche su github.

