Discourse permite que temas tenham “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 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á maneira de fazê-lo 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). Neste arquivo, você usará a linguagem YAML para definir as configurações do seu tema.
Nota: Você pode achar útil usar o Theme CLI, que simplifica enormemente o processo de desenvolvimento.
Agora, se você está 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 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 notar, 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á duas configurações a mais: 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.your_setting_key.
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, porque 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 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 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 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)
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 um 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 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 configuração em si é 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 no 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 é 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 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 do 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, porque isso inclui apenas grupos que são visíveis para o usuário e pode perder grupos ocultos.
Para configurações de lista com base 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 de grupos original. 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. Configurações de tema do tipo objeto podem usar a mesma opção em propriedades type: groups. Consulte tipo objects para configurações de tema para mais detalhes.
Tópicos relacionados
Este documento é controlado por versão - sugira alterações no github.