Precedente tutorial: Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
Impostazioni Sito
Se visiti /admin/site_settings su un Discourse su cui hai capacità di amministratore, vedrai un elenco di impostazioni di configurazione. Appena installato, forniamo quelle che riteniamo siano le impostazioni migliori per un’installazione di Discourse, ma comprendiamo anche che le persone vogliono modificare le loro installazioni per rendere il loro forum esattamente come desiderano.
È probabile che, a meno che il tuo plugin non sia molto semplice, tu voglia aggiungere impostazioni che gli utenti del tuo plugin possano modificare e utilizzare per configurare le funzionalità. Fortunatamente, questo è piuttosto facile da fare!
config/settings.yml
La prima cosa che dovrai fare è creare config/settings.yml all’interno della cartella del tuo plugin. Questo file delineerà tutte le impostazioni di cui il tuo plugin avrà bisogno. Ecco un file di esempio:
plugins:
awesomeness_enabled:
default: true
client: true
awesomeness_max_volume:
default: 10
client: true
Il file deve essere in formato YAML. YAML può essere piuttosto esigente, quindi se Discourse ha problemi a caricare le tue impostazioni, ti suggerisco di provare a convalidare il tuo YAML con uno strumento come YAMLint.
Spiegherò il file di esempio in dettaglio. Il livello superiore è plugins e questo dice a Discourse che vogliamo che queste impostazioni appaiano sotto “Plugins” nelle impostazioni del sito.
Successivamente, vengono dichiarate due impostazioni, awesomeness_enabled e awesomeness_max_volume. Discourse deduce il tipo delle impostazioni dal valore predefinito, quindi awesomeness_enabled è un booleano e awesomeness_max_volume è un numero.
Il client: true è importante da capire. Discourse è composto da due applicazioni principali, l’API lato server scritta in Ruby on Rails e l’applicazione lato client scritta in Ember.js. Per impostazione predefinita, non esponiamo le impostazioni all’app client Ember.js a meno che tu non aggiunga client: true. Lo facciamo perché alcune impostazioni sono private come le chiavi API e non dovrebbero essere inviate agli utenti finali. Inoltre, se inviassimo ogni impostazione al client, potrebbe essere un carico notevole per gli utenti finali scaricarle!
Nel nostro esempio, vogliamo che entrambe queste impostazioni siano accessibili nel mondo JavaScript così come nel mondo lato server.
Un secondo passo importante
Prima di poter utilizzare le impostazioni del sito appena aggiunte, devi aggiungere le traduzioni per esse. Poiché Discourse supporta molte lingue, qualsiasi testo che aggiungi dovrà supportare la traduzione in altre lingue.
Creiamo le traduzioni per le nostre impostazioni in inglese:
config/locales/server.en.yml
en:
site_settings:
awesomeness_enabled: "Is this plugin awesome?"
awesomeness_max_volume: "What is the maximum volume possible?"
Le etichette che abbiamo aggiunto in quel file verranno visualizzate nella sezione admin. È buona norma essere il più chiari possibile su ciò che l’impostazione realizza.
Dichiarare l’impostazione come ‘impostazione di abilitazione’
Ora che abbiamo la nostra impostazione del sito, dovremmo dire a Discourse che è quella che attiva e disattiva le nostre funzionalità.
Apri il tuo file plugin.rb e aggiungi la seguente riga sotto i commenti dei metadati:
enabled_site_setting :awesomeness_enabled
Assicurati di iniziare tutte le altre impostazioni con “awesomeness_” affinché il pulsante delle impostazioni in /admin/plugins funzioni correttamente.
Accesso alle tue nuove impostazioni
Innanzitutto, dovrai riavviare il tuo server di sviluppo affinché le impostazioni abbiano effetto. Una volta fatto ciò, le impostazioni dovrebbero essere disponibili per il tuo codice lato server e client.
Iniettiamo automaticamente le impostazioni del sito nella maggior parte degli oggetti JavaScript, quindi se stai dichiarando un Component, Controller, Route, View o Model dovresti essere in grado di accedere all’impostazione del sito semplicemente usando this.siteSettings.awesomeness_enabled. Nella maggior parte dei template handlebars dovresti anche essere in grado di dire {{siteSettings.awesomeness_enabled}} e il valore dell’impostazione verrà visualizzato.
Non abbiamo ancora trattato molto materiale Ruby in questa serie, ma se vuoi accedere alle impostazioni del sito nell’applicazione Ruby puoi farlo tramite: SiteSetting.awesomeness_enabled
Ora vai avanti e aggiungi impostazioni personalizzate ai tuoi plugin!
Altro nella serie
Parte 1: Plugin Basics
Parte 2: Plugin Outlets
Parte 3: Questo argomento
Parte 4: git setup
Parte 5: Admin interfaces
Parte 6: Acceptance tests
Parte 7: Publish your plugin
Questo documento è controllato tramite versione - suggerisci modifiche su github.
