Précédent tutoriel : Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
Paramètres du site
Si vous visitez /admin/site_settings sur un Discourse sur lequel vous avez des capacités d’administrateur, vous verrez une liste de paramètres de configuration. Dès l’installation, nous fournissons ce que nous pensons être les meilleurs paramètres pour une installation de Discourse, mais nous comprenons également que les gens veulent ajuster leurs installations pour que leur forum soit exactement comme ils le souhaitent.
Il y a de fortes chances que, à moins que votre plugin ne soit très simple, vous souhaitiez ajouter des paramètres que les utilisateurs de votre plugin peuvent modifier et utiliser pour configurer les fonctionnalités. Heureusement, c’est assez facile à faire !
config/settings.yml
La première chose que vous devrez faire est de créer config/settings.yml dans votre dossier de plugin. Ce fichier décrira tous les paramètres dont votre plugin aura besoin. Voici un exemple de fichier :
plugins:
awesomeness_enabled:
default: true
client: true
awesomeness_max_volume:
default: 10
client: true
Le fichier doit être au format YAML. Le YAML peut être assez pointilleux, donc si Discourse a des difficultés à charger vos paramètres, je vous suggère d’essayer de valider votre YAML avec un outil comme YAMLint.
Je vais expliquer l’exemple de fichier en détail. Le niveau supérieur est plugins et cela indique à Discourse que nous voulons que ces paramètres apparaissent sous « Plugins » dans les paramètres du site.
Ensuite, deux paramètres sont déclarés, awesomeness_enabled et awesomeness_max_volume. Discourse déduit le type des paramètres à partir de la valeur par défaut, donc awesomeness_enabled est un booléen et awesomeness_max_volume est un nombre.
Le client: true est important à comprendre. Discourse est composé de deux applications principales, l’API côté serveur écrite en Ruby on Rails, et l’application côté client écrite en Ember.js. Par défaut, nous n’exposons pas les paramètres à l’application client Ember.js à moins que vous n’ajoutiez client: true. Nous faisons cela parce que certains paramètres sont privés, comme les clés API, et ne doivent pas être envoyés aux utilisateurs finaux. De plus, si nous envoyions tous les paramètres au client, cela pourrait représenter un téléchargement important pour les utilisateurs finaux !
Dans notre exemple, nous voulons que ces deux paramètres soient accessibles dans le monde JavaScript ainsi que dans le monde côté serveur.
Une deuxième étape importante
Avant de pouvoir utiliser vos paramètres de site nouvellement ajoutés, vous devez ajouter des traductions pour eux. Puisque Discourse prend en charge de nombreuses langues, tout texte que vous ajoutez devra prendre en charge la traduction dans d’autres langues.
Créons les traductions pour nos paramètres en anglais :
config/locales/server.en.yml
en:
site_settings:
awesomeness_enabled: "Ce plugin est-il génial ?"
awesomeness_max_volume: "Quel est le volume maximum possible ?"
Les étiquettes que nous avons ajoutées dans ce fichier seront affichées dans la section d’administration. C’est une bonne idée d’être aussi clair que possible sur ce que le paramètre accomplit.
Déclarer le paramètre comme le ‘paramètre activé’
Maintenant que nous avons notre paramètre de site, nous devons indiquer à Discourse que c’est celui qui active et désactive nos fonctionnalités.
Ouvrez votre fichier plugin.rb et ajoutez la ligne suivante sous les commentaires de métadonnées :
enabled_site_setting :awesomeness_enabled
Assurez-vous de commencer tous vos autres paramètres par « awesomeness_ » afin que le bouton de paramètres à /admin/plugins fonctionne correctement.
Accéder à vos nouveaux paramètres
Tout d’abord, vous devrez redémarrer votre serveur de développement pour que les paramètres prennent effet. Une fois que vous l’aurez fait, les paramètres devraient être disponibles pour votre code côté serveur et côté client.
Nous injectons automatiquement les paramètres du site dans la plupart des objets JavaScript, donc si vous déclarez un Component, Controller, Route, View ou Model, vous devriez pouvoir accéder au paramètre du site simplement en utilisant this.siteSettings.awesomeness_enabled. Dans la plupart des modèles handlebars, vous devriez également pouvoir dire {{siteSettings.awesomeness_enabled}} et la valeur du paramètre sera affichée.
Nous n’avons pas encore beaucoup couvert les choses en Ruby dans cette série, mais si vous souhaitez accéder aux paramètres du site dans l’application Ruby, vous pouvez le faire via : SiteSetting.awesomeness_enabled
Maintenant, allez de l’avant et ajoutez des paramètres personnalisés à vos plugins !
Plus dans la série
Partie 1 : Bases des plugins
Partie 2 : Points de sortie des plugins
Partie 3 : Ce sujet
Partie 4 : Configuration git
Partie 5 : Interfaces d’administration
Partie 6 : Tests d’acceptation
Partie 7 : Publiez votre plugin
Ce document est contrôlé par version - suggérez des modifications sur github.
