O Discourse possui a capacidade de temas terem “configurações” que podem ser adicionadas por desenvolvedores de temas, permitindo 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 com a perda de alterações em futuras atualizações do tema.
Os temas também podem alterar certas configurações de site tematizáveis. Para mais informações sobre isso, veja o tópico Configurações de site tematizá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á uma maneira de fazê-lo pela interface do usuário.
A maneira de adicionar configurações é criar um repositório para o seu tema e, na pasta raiz do seu repositório, criar um novo arquivo settings.yaml (ou settings.yml). Neste arquivo, você usará a linguagem YAML para definir as configurações do seu tema.
Nota: Você pode achar útil fazer uso da Theme CLI, que simplifica enormemente o processo de desenvolvimento.
Agora, se você está familiarizado com o desenvolvimento de plugins, isso não deve ser algo novo para você - funciona basicamente da mesma maneira que adicionar configurações de site ao seu plugin. Basta despejar algum YAML válido no seu arquivo de configurações e você estará pronto para ir.
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 da seguinte forma: settings.your_setting_key.
Então, até este ponto, cobrimos a maneira mais simples de definir configurações. Na próxima seção, vamos aprofundar um pouco mais nos vários tipos de configurações e como você pode usá-las.
Tipos suportados
Há 9 tipos de configurações:
integerfloatstringbool(para booleano)listenumobjects(substituto parajson_schema)upload(para imagens)icon(para um único ícone do conjunto de ícones do Discourse)
E você pode especificar o tipo adicionando um atributo type à sua configuração, como este:
float_setting:
type: float
default: 3.14
Devo dizer que nem sempre você precisa definir explicitamente um atributo type, pois o Discourse é inteligente o suficiente para determinar o tipo da configuração a partir do valor padrão da configuração. Então, você pode reduzir o exemplo acima a este:
float_setting:
default: 3.14
Dito isso, você precisa definir um atributo de tipo ao trabalhar com configurações list, enum e icon, 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ê: 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, configurações de lista permitem que seus usuários criem sua própria lista (ou seja, um array) 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 juntando os valores com um caractere de 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.
Configuração de Ícone:
banner_icon:
default: bullhorn
type: icon
Configurações de ícone dão aos proprietários do site um seletor de ícones pesquisável, e o valor é o nome do ícone. O Discourse adiciona o ícone selecionado à folha de sprites, então você pode renderizá-lo no seu tema sem registrá-lo separadamente.
Tipo objects
O tipo de configuração objects é um tipo especial que permite que você realize configurações avançadas com estrutura e validações personalizadas. Temos uma documentação separada para este tipo.
Descrição da configuração e localizações
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, como este:
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 múltiplos idiomas
Se você conhece mais de um idioma e deseja adicionar suporte a esses idiomas ao seu tema, você pode totalmente fazer isso, desde que o Discourse suporte os ditos idiomas.
Primeiro de tudo, verifique se o idioma que você deseja suportar está 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 consegue 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, como este:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: Texto em inglês
ar: نص باللغة العربية
fr: Texte français
E agora você tem suporte a 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 pode exceder para impedir que seus usuários quebrem acidentalmente o tema ou, possivelmente, o site inteiro.
Para especificar limites, basta adicionar um atributo min ou max ou ambos à sua configuração, como este:
integer_setting:
default: 10
min: 5
max: 100
Você pode especificar limites para configurações de tipo integer, float e string. Para configurações de integer e float, o valor da própria configuração é verificado contra os limites. E para configurações de string, o comprimento do valor é verificado contra os 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 no seu JS/CSS/Handlebars
As configurações do tema ficam 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("settings are", settings);
});
Este objeto settings também pode ser usado normalmente dentro de tags <template> de .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 a pertença a grupos
Componentes de tema às vezes precisam exibir ou ocultar um recurso com base em se o usuário atual está em um grupo configurado. Evite verificar currentUser.groups para isso, pois ele inclui apenas grupos que são visíveis para o usuário e pode perder grupos ocultos.
Para configurações de lista baseadas em grupos, 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 só é válida quando a configuração tem type: list e list_type: group. Quando habilitada, o objeto settings do front-end 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;
}
// 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. Configurações de tema de objeto podem usar a mesma opção em propriedades de type: groups. Veja objects type for theme settings para detalhes.
Tópicos Relacionados
Este documento é controlado por versão - sugira alterações no github.