Sviluppare Plugin per Discourse - Parte 1 - Creare un plugin di base

[Discourse]

Creare un plugin in Discourse può essere davvero semplice, una volta apprese alcune particolarità. 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 utilizzare la guida di configurazione appropriata e di tornare qui una volta terminato.

plugin.rb

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

Lo scheletro è ora incluso nel core di Discourse, rake plugin:create[nome-plugin] creerà un plugin utilizzando 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 per il tuo plugin con le informazioni richieste sul plugin, tra cui: nome, informazioni di contatto 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 del 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 insidia!

Se hai familiarità con lo sviluppo rails tradizionale, potresti notare che i plugin non sono così facili quando si tratta di ricaricamento. In generale, quando apporti modifiche al tuo plugin, dovresti premere Ctrl+c per fermare l’esecuzione del server, quindi eseguirlo di nuovo usando bin/ember-cli -u.

Le mie modifiche non sono state recepite!

A volte la cache non viene cancellata completamente, specialmente quando crei nuovi file o ne elimini di vecchi. Per aggirare questo problema, rimuovi la tua cartella tmp e avvia rails di nuovo. Su un mac puoi farlo con un unico comando: rm -rf tmp; bin/ember-cli -u.

Verifica 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 admin possono vedere il registro dei plugin).

Se tutto è andato bene, 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 si carica. Questo sarà super 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("alert boxes are annoying!");
  },
};

Ora, se riavvii il server locale, dovresti vedere “alert boxes are annoying!” apparire sullo schermo. (Se non l’hai visto, consulta l’intestazione “Le mie modifiche non sono state recepite” sopra).

Analizziamo come ha funzionato:

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

2. Questo particolare file exporta un oggetto, che ha un name e una funzione initialize.

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

4. La funzione initialize() viene chiamata quando l’applicazione si carica. Nel nostro caso, tutto ciò che fa è eseguire il nostro codice alert().

Ora sei un plugin developer ufficiale di Discourse!

---

Altro nella serie

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

---

Questo documento è controllato tramite versione - suggerisci modifiche su github.