Estamos introduzindo um novo type: objects para os tipos suportados para configurações de tema, que pode ser usado para substituir o tipo json_schema existente, que pretendemos depreciar em breve.
Definindo uma configuração de tema do tipo objects
Para criar uma configuração de tema do tipo objects, primeiro defina uma chave de nível superior assim como qualquer outra configuração de tema, que será usada como o nome da configuração.
links: ...
Em seguida, adicione as palavras-chave type, default e schema à configuração.
links:
type: objects
default: []
schema: ...
type: objects indica que esta será uma configuração do tipo objects, enquanto a anotação default: [] define o valor padrão da configuração como um array vazio. Note que o valor padrão também pode ser definido como um array de objects, o que demonstraremos assim que o schema for definido.
Para definir o esquema, primeiro defina o name do esquema desta forma:
links:
type: objects
default: []
schema:
name: link
Em seguida, adicionaremos a palavra-chave properties ao esquema, o que nos permitirá definir e validar como cada object deve ser estruturado.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
No exemplo acima, estamos declarando que o object link tem uma propriedade name. Para definir o tipo de dados esperado, cada propriedade precisa definir a palavra-chave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
A definição de esquema acima indica que o object link tem uma propriedade name do tipo string, o que significa que apenas valores de string serão aceitos para a propriedade. Atualmente, os seguintes tipos são suportados:
-
string: O valor da propriedade é armazenado como uma string. Definatextarea: truepara usar uma área de texto expansível:description: type: string textarea: true validations: max_length: 500 -
integer: O valor da propriedade é armazenado como um inteiro. -
float: O valor da propriedade é armazenado como um float. -
boolean: O valor da propriedade étrueoufalse. -
upload: O valor da propriedade é a URL do anexo. -
enum: O valor da propriedade deve ser um dos valores definidos na palavra-chavechoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: O valor da propriedade é um array de IDs de categoria válidos. -
groups: O valor da propriedade é um array de IDs de grupo válidos. -
tags: O valor da propriedade é um array de nomes de tags válidos. -
icon: O valor da propriedade é o nome de um único ícone do conjunto de ícones do Discourse. Os ícones selecionados são adicionados automaticamente à folha de sprites, portanto, podem ser renderizados sem serem registrados separadamente.
Com o esquema definido, o valor padrão da configuração pode agora ser definido por meio da definição de um array no yaml, desta forma:
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
Propriedades obrigatórias
Todas as propriedades definidas são opcionais por padrão. Para marcar uma propriedade como obrigatória, simplesmente anote a propriedade com required: true. Uma propriedade também pode ser marcada como opcional anotando-a com required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Valores vazios para string, datetime e icon, bem como listas vazias para categories, groups e tags, são contados como ausentes: propriedades obrigatórias os rejeitam e propriedades opcionais ignoram suas validações. false conta como definido.
Validações Personalizadas
Para certos tipos de propriedade, há suporte integrado para validações personalizadas, que podem ser declaradas anotando a propriedade com a palavra-chave validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Validações para tipos string
min_length: Comprimento mínimo da propriedade. O valor da palavra-chave deve ser um inteiro.max_length: Comprimento máximo da propriedade. O valor da palavra-chave deve ser um inteiro.url: Valida se a propriedade é uma URL válida. O valor da palavra-chave pode sertrue/false.
Validações para tipos integer e float
min: Valor mínimo da propriedade. O valor da palavra-chave deve ser um inteiro.max: Valor máximo da propriedade. O valor da palavra-chave deve ser um inteiro.
Validações para tipos tags, groups e categories
min: Número mínimo de registros para a propriedade. O valor da palavra-chave deve ser um inteiro.max: Número máximo de registros para a propriedade. O valor da palavra-chave deve ser um inteiro.
Resolvendo a pertença a grupos
As configurações de objects podem resolver propriedades type: groups em um booleano para o usuário atual. Isso é útil quando o código do tema precisa apenas saber se o usuário atual está em um dos grupos configurados, porque currentUser.groups inclui apenas os grupos visíveis para o usuário.
Adicione resolve_group_membership: true à propriedade groups:
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
A interface administrativa e o valor da configuração armazenada ainda usam o array groups original. No objeto settings do tempo de execução do frontend, o Discourse remove os IDs dos grupos de cada object e adiciona um booleano com o mesmo nome de propriedade, prefixado por user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// O usuário está em pelo menos um dos grupos selecionados para esta seção.
}
}
Esta opção é válida apenas para propriedades de esquema de object com type: groups. Ela também funciona com esquemas de objects aninhados e com grupos automáticos, como logged_in_users e anonymous_users.
Estrutura de objects aninhados
Um object também pode ter uma propriedade que contém um array de objects. Para criar uma estrutura de objects aninhados, uma propriedade também pode ser anotada com type: objects e a definição de schema associada.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
Descrição da configuração e localização
Para adicionar uma descrição para a configuração na localidade en, crie um arquivo locales/en.yml com o seguinte formato, dada a seguinte configuração de tema do tipo objects.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: Esta é uma descrição para a configuração de tema sections
schema:
properties:
name:
label: Nome
description: A descrição para a propriedade
links:
name:
label: Nome
description: A descrição para a propriedade
url:
label: URL
description: A descrição para a propriedade
Este documento é controlado por versão - sugira alterações no github.
. Foi mais uma tentativa de ver se era possível, mas não uma abordagem razoável.