O Discourse possui a capacidade de temas terem “configurações” que podem ser adicionadas por 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 de site personalizáveis; para mais informações sobre isso, consulte o tópico Configurações de 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, pois não há maneira de 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 utilizar o Theme CLI, que simplifica enormemente o processo de desenvolvimento.
Agora, 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 de 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 se parece com isso:
simple_setting: true
Como você provavelmente pode perceber, isso criará uma configuração com o nome simple_setting e terá true como seu 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, vamos mergulhar um pouco mais 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(substituição 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 deduzir 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 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 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 juntando 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 da 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 múltiplos idiomas
Se você conhece mais de um idioma e deseja adicionar suporte para esses idiomas ao seu tema, você pode 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 consegue ver seu idioma na lista, talvez queira dar uma olhada em How to add a new language)
Em seguida, 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: Texto em francês
E agora você tem suporte para 3 idiomas: inglês, árabe e francês.
Atributos min e max
Às vezes, você pode precisar especificar limites que um valor de 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 configuração em si é verificado contra os limites. E para configurações 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 de 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 é utilizável normalmente dentro de 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 representa.
Então, se você tivesse uma configuração float chamada global_font_size e uma configuração 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 grupos
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 ele inclui apenas grupos 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 é 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 dos grupos selecionados.
});
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.