O Discourse possui a capacidade de os temas terem “configurações” que podem ser adicionadas pelos desenvolvedores de temas para permitir que os proprietários do site personalizem os temas por meio da interface do usuário, sem precisar alterar nenhuma linha de código e sem se preocupar em perder suas alterações com atualizações futuras do tema.
Os temas também podem alterar certas configurações do site personalizáveis; para mais informações sobre isso, consulte o tópico Configurações do site personalizáveis.
Adicionando configurações ao seu tema
Adicionar configurações ao seu tema é um pouco diferente de adicionar código CSS e JS, ou seja, não há como fazer isso por meio da interface do usuário.
A maneira de adicionar configurações é criar um repositório para seu tema e, na pasta raiz do seu repositório, criar um novo arquivo settings.yaml (ou settings.yml). Nesse arquivo, você usará a linguagem YAML para definir as configurações do seu tema.
Nota: Você pode achar útil fazer uso do Theme CLI, que simplifica enormemente o processo de desenvolvimento.
Se você estiver familiarizado com o desenvolvimento de plugins, isso não deve ser novidade para você — funciona basicamente da mesma maneira que adicionar configurações do site ao seu plugin. Basta inserir algum YAML válido no seu arquivo de configurações e você estará pronto para começar.
Uma configuração de tema válida deve ter um nome e um valor padrão; esse é o mínimo necessário e parece com isso:
simple_setting: true
Como você provavelmente pode perceber, isso criará uma configuração com o nome simple_setting e ela terá true como valor padrão.
Da mesma forma, você pode adicionar algo como isso:
site_name: My Forums
max_avatars: 7
E você terá mais duas configurações: site_name, que será uma configuração de string com “My Forums” como valor padrão, e max_avatars, como uma configuração de inteiro com valor padrão de 7.
Você pode acessar suas configurações no seu código JS assim: settings.sua_chave_de_configuracao.
Então, até este ponto, cobrimos a maneira mais simples de definir configurações. Na próxima seção, entraremos um pouco mais a fundo nos vários tipos de configurações e como você pode usá-las.
Tipos suportados
Existem 8 tipos de configurações:
integerfloatstringbool(para booleano)listenumobjects(substituto parajson_schema)upload(para imagens)
E você pode especificar o tipo adicionando um atributo type à sua configuração assim:
float_setting:
type: float
default: 3.14
Devo dizer que você nem sempre precisa definir explicitamente um atributo type, pois o Discourse é inteligente o suficiente para determinar o tipo de configuração a partir do valor padrão da configuração. Então, você pode reduzir o exemplo acima para isso:
float_setting:
default: 3.14
Dito isso, você precisa definir um atributo de tipo ao trabalhar com configurações list e enum, caso contrário, o Discourse não as reconhecerá corretamente.
Configuração de Lista:
whitelisted_fruits:
default: apples|oranges
type: list
Configuração de Enum:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Caso a diferença entre configurações de lista e enum não esteja clara para você: as configurações de enum permitem que os usuários do seu tema selecionem apenas um valor de um conjunto de valores definidos por você (veja o atributo choices).
Por outro lado, as configurações de lista permitem que seus usuários criem sua própria lista (ou seja, uma matriz) de valores. Eles podem adicionar ou remover valores da lista padrão de valores da configuração.
Você pode definir a lista padrão de valores para a configuração unindo os valores com o caractere barra vertical |. Veja a configuração de lista no exemplo acima.
Você pode ver um caso de uso real para configurações de lista aqui: Auto-Linkify Words.
Tipo objects
O tipo de configuração objects é um tipo especial que permite realizar configurações avançadas com estrutura e validações personalizadas. Temos uma documentação separada para este tipo.
Descrição e localizações de configuração
Você pode adicionar texto de descrição à sua configuração de tema e ele será exibido como um rótulo diretamente abaixo da configuração. Para fazer isso, basta adicionar um atributo description à sua configuração assim:
whitelisted_fruits:
default: apples|oranges
type: list
description: "Este texto será exibido abaixo desta configuração e explica o que a configuração faz!"
E você obterá isso:
Suporte a vários idiomas
Se você conhece mais de um idioma e deseja adicionar suporte para esses idiomas ao seu tema, você pode totalmente fazer isso, desde que o Discourse suporte os idiomas mencionados.
Primeiro, certifique-se de que o idioma que você deseja suportar esteja nesta lista:
Lista de idiomas
| Código | Nome | |||
|---|---|---|---|---|
| ar | اللغة العربية | |||
| bs_BA | bosanski jezik | |||
| ca | català | |||
| cs | čeština | |||
| da | dansk | |||
| de | Deutsch | |||
| el | ελληνικά | |||
| en | English | |||
| es | Español | |||
| et | eesti | |||
| fa_IR | فارسی | |||
| fi | suomi | |||
| fr | Français | |||
| gl | galego | |||
| he | עברית | |||
| id | Indonesian | |||
| it | Italiano | |||
| ja | 日本語 | |||
| ko | 한국어 | |||
| lv | latviešu valoda | |||
| nb_NO | Norsk bokmål | |||
| nl | Nederlands | |||
| pl_PL | język polski | |||
| pt | Português | |||
| pt_BR | Português (BR) | |||
| ro | limba română | |||
| ru | Русский | |||
| sk | slovenčina | |||
| sq | Shqip | |||
| sr | српски језик | |||
| sv | svenska | |||
| te | తెలुగు | |||
| th | ไทย | |||
| tr_TR | Türkçe | |||
| uk | українська мова | |||
| ur | اردو | |||
| vi | Việt Nam | |||
| zh_CN | 中文 | |||
| zh_TW | 中文 (TW) |
(Se você não conseguir ver seu idioma na lista, talvez queira dar uma olhada em How to add a new language)
Então, você precisará encontrar o código do seu idioma na lista acima e usar o código do idioma como uma chave sob o atributo description e a tradução como valor para a chave assim:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: Texto em inglês
ar: نص باللغة العربية
fr: Texte français
E agora você tem suporte para 3 idiomas: inglês, árabe e francês.
Atributos e opções adicionais de configuração
Atributos min e max
Às vezes, você pode precisar especificar limites que o valor de uma configuração não possa exceder para evitar que seus usuários quebrem acidentalmente o tema ou possivelmente todo o site.
Para especificar limites, basta adicionar um atributo min ou max ou ambos à sua configuração assim:
integer_setting:
default: 10
min: 5
max: 100
Você pode especificar limites para configurações dos tipos integer, float e string. Para configurações integer e float, o valor da própria configuração é verificado em relação aos limites. E para configurações string, o comprimento do valor é verificado em relação aos limites especificados.
Se seu usuário tentar inserir um valor que não esteja dentro da faixa permitida, ele verá um erro informando quais são os valores mínimo e máximo.
Acesso às configurações em seu JS/CSS/Handlebars
As configurações do tema estão disponíveis globalmente como uma variável settings nos arquivos JavaScript do tema. Por exemplo:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("as configurações são", settings);
});
Este objeto settings também pode ser usado normalmente dentro das tags <template> .gjs.
Definindo variáveis CSS
No CSS, uma variável será criada para cada configuração do seu tema e cada variável terá o mesmo nome da configuração que ela representa.
Então, se você tivesse uma configuração de float chamada global_font_size e uma configuração de string chamada site_background, você poderia fazer algo como isso no CSS do seu tema:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Resolvendo associação de grupo
Os componentes de tema às vezes precisam mostrar ou ocultar um recurso com base se o usuário atual está em um grupo configurado. Evite verificar currentUser.groups para isso, pois isso inclui apenas grupos que são visíveis para o usuário e pode perder grupos ocultos.
Para configurações de lista baseadas em grupo, adicione resolve_group_membership: true para resolver a verificação no lado do servidor:
copy_button_allowed_groups:
default: "1|3"
type: list
list_type: group
resolve_group_membership: true
Esta opção é válida apenas quando a configuração tem type: list e list_type: group. Quando habilitada, o objeto settings no frontend não inclui a lista original de grupos. Em vez disso, o Discourse adiciona um booleano com o mesmo nome da configuração prefixado por user_in_:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
if (!settings.user_in_copy_button_allowed_groups) {
return;
}
// O usuário está em pelo menos um grupo selecionado.
});
O booleano gerado também funciona com grupos automáticos, como logged_in_users e anonymous_users.
Tópicos Relacionados
Este documento é controlado por versão — sugira alterações no github.