\nTutorial anterior: Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
Configurações do Site
Se você visitar /admin/site_settings em um Discourse no qual você tem capacidades de administrador, verá uma lista de configurações de configuração. Logo de início, fornecemos o que consideramos serem as melhores configurações para uma instalação do Discourse, mas também entendemos que as pessoas querem ajustar suas instalações para deixar seu fórum exatamente como desejam.
É provável que, a menos que seu plugin seja muito simples, você queira adicionar configurações que os usuários do seu plugin possam alterar e usar para configurar a funcionalidade. Felizmente, isso é bem fácil de fazer!
config/settings.yml
A primeira coisa que você precisará fazer é criar config/settings.yml dentro da pasta do seu plugin. Este arquivo descreverá todas as configurações que seu plugin precisará. Aqui está um arquivo de exemplo:
plugins:
awesomeness_enabled:
default: true
client: true
awesomeness_max_volume:
default: 10
client: true
O arquivo precisa estar no formato YAML. O YAML pode ser bem exigente, então, se o Discourse estiver com problemas para carregar suas configurações, sugiro que você tente validar seu YAML com uma ferramenta como o YAMLint.
Vou explicar o arquivo de exemplo em detalhes. O nível superior é plugins e isso diz ao Discourse que queremos que essas configurações apareçam em “Plugins” nas configurações do site.
Depois disso, duas configurações são declaradas, awesomeness_enabled e awesomeness_max_volume. O Discourse infere o tipo das configurações a partir do padrão, então awesomeness_enabled é um booleano e awesomeness_max_volume é um número.
O client: true é importante de entender. O Discourse é composto por duas aplicações principais, a API do lado do servidor escrita em Ruby on Rails, e a aplicação do lado do cliente escrita em Ember.js. Por padrão, não expomos configurações para o cliente Ember.js a menos que você adicione client: true. Fazemos isso porque algumas configurações são privadas, como chaves de API, e não devem ser enviadas aos usuários finais. Além disso, se enviássemos todas as configurações para o cliente, isso poderia ser muito para os usuários finais baixarem!
No nosso caso de exemplo, queremos que ambas as configurações sejam acessíveis no mundo JavaScript, bem como no mundo do lado do servidor.
Um segundo passo importante
Antes de poder usar suas configurações de site recém-adicionadas, você precisa adicionar traduções para elas. Como o Discourse suporta vários idiomas, qualquer texto que você adicionar terá que suportar a tradução para outros idiomas.
Vamos criar as traduções para nossas configurações em inglês:
config/locales/server.en.yml
en:
site_settings:
awesomeness_enabled: "Is this plugin awesome?"
awesomeness_max_volume: "What is the maximum volume possible?"
Os rótulos que adicionamos nesse arquivo serão exibidos na seção de administração. É uma boa ideia ser o mais claro possível sobre o que a configuração realiza.
Declarando a configuração como a ‘configuração habilitada’
Agora que temos nossa configuração de site, devemos dizer ao Discourse que ela é a que ativa e desativa nossos recursos.
Abra seu arquivo plugin.rb e adicione a seguinte linha abaixo dos comentários de metadados:
enabled_site_setting :awesomeness_enabled
Certifique-se de começar todas as suas outras configurações com “awesomeness_” para que o botão de configurações em /admin/plugins funcione corretamente.
Acessando suas novas configurações
Primeiro, você precisará reiniciar seu servidor de desenvolvimento para que as configurações entrem em vigor. Depois de fazer isso, as configurações devem estar disponíveis para seu código do lado do servidor e do lado do cliente.
Nós injetamos automaticamente as configurações do site na maioria dos objetos JavaScript, então, se você estiver declarando um Component, Controller, Route, View ou Model, você deve ser capaz de acessar a configuração do site simplesmente usando this.siteSettings.awesomeness_enabled. Na maioria dos templates handlebars, você também deve ser capaz de dizer {{siteSettings.awesomeness_enabled}} e o valor da configuração será exibido.
Ainda não cobrimos muita coisa sobre Ruby nesta série, mas se você quiser acessar as configurações do site na aplicação Ruby, você pode fazer isso através de: SiteSetting.awesomeness_enabled
Agora vá em frente e adicione configurações personalizadas aos seus plugins!
Mais na série
Parte 1: Noções Básicas de Plugin
Parte 2: Plugin Outlets
Parte 3: Este tópico
Parte 4: Configuração do git
Parte 5: Interfaces de Administrador
Parte 6: Testes de Aceitação
Parte 7: Publique seu plugin
Este documento é controlado por versão - sugira alterações no github.
