Sviluppo di plugin per Discourse - Parte 1 - Creare un plugin di base

[Discourse]

Creare un plugin per Discourse può essere davvero semplice, una volta che si imparano alcune particolarità. L’obiettivo di questo post è creare un plugin scheletro e introdurre i concetti di base.

Il tuo ambiente di sviluppo

Assicurati di avere un’istanza di Discourse in ambiente di sviluppo in esecuzione sul tuo computer. Ti consiglio di seguire la guida di configurazione appropriata e di tornare qui una volta completata.

plugin.rb

Usa GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub per creare un plugin scheletro completo di Discourse nella tua directory plugins

Lo scheletro è ora integrato nel core di Discourse; rake plugin:create[nome-plugin] creerà un plugin utilizzando lo scheletro.

Quando Discourse si avvia, cerca nella directory plugins le sottodirectory che contengono un file plugin.rb. Il file plugin.rb ha due scopi: funge da manifesto per il tuo plugin, contenendo le informazioni richieste come nome, informazioni di contatto e descrizione. Il secondo scopo è inizializzare qualsiasi codice Ruby necessario per l’esecuzione del tuo plugin.

Nel nostro caso, non aggiungeremo alcun codice Ruby, ma abbiamo comunque bisogno del file plugin.rb. Creiamo la directory basic-plugin con il file plugin.rb al suo interno, con il seguente contenuto:

basic-plugin/plugin.rb

# name: basic-plugin
# about: Un plugin super semplice per dimostrare come funzionano i plugin
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin

Una volta creato questo file, dovresti riavviare il server locale e il plugin dovrebbe essere caricato.

Un importante particolare da ricordare!

Se sei abituato allo sviluppo Rails standard, 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 l’esecuzione del server, quindi riavviarlo utilizzando bin/dev.

Le mie modifiche non sono state rilevate!

A volte la cache non viene svuotata completamente, specialmente quando crei nuovi file o elimini file vecchi. Per risolvere questo problema, elimina la tua cartella tmp e riavvia Rails. Su Mac puoi farlo con un unico comando: rm -rf tmp; bin/dev.

Verifica che il tuo plugin sia stato caricato

Dopo aver riavviato il server locale, visita l’URL /admin/plugins (assicurati di essere acceso come account amministratore prima, poiché solo gli amministratori possono vedere il registro dei plugin).

Se tutto ha funzionato, dovresti vedere il tuo plugin nell’elenco:

Congratulazioni, hai appena creato il tuo primo plugin!

Aggiungiamo del JavaScript

Al momento il tuo plugin non fa nulla. Aggiungiamo un file JavaScript che mostri una finestra di avviso quando Discourse si carica. Questo sarà estremamente fastidioso per qualsiasi utente e non è consigliato 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 server locale, dovresti vedere apparire a schermo “le finestre di avviso sono fastidiose!”. (Se non è così, consulta la sezione “Le mie modifiche non sono state rilevate” sopra).

Analizziamo come funziona questo processo:

1. I file JavaScript posizionati in assets/javascripts/discourse/initializers vengono eseguiti automaticamente quando l’applicazione Discourse si carica.

2. Questo file specifico exporta un oggetto, che ha una proprietà name e una funzione initialize.

3. Il name deve essere univoco, quindi l’ho chiamato semplicemente alert.

4. La funzione initialize() viene chiamata quando l’applicazione si carica. Nel nostro caso, si limita a eseguire il nostro codice alert().

Ora sei un ufficiale sviluppatore di plugin per Discourse!

---

Altri articoli nella serie

Parte 1: Questo argomento
Parte 2: Plugin Outlets
Parte 3: Impostazioni del sito
Parte 4: Configurazione di git
Parte 5: Interfacce di amministrazione
Parte 6: Test di accettazione
Parte 7: Pubblica il tuo plugin

---

Questo documento è controllato tramite versioning - suggerisci le modifiche su GitHub.