Estamos introduzindo um novo type: objects para os tipos suportados em configurações de tema, que pode ser usado para substituir o tipo existente json_schema, que pretendemos descontinuar 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 em qualquer 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 após a definição do schema.
Para definir o schema, primeiro defina o name do schema da seguinte forma:
links:
type: objects
default: []
schema:
name: link
Em seguida, adicionaremos a palavra-chave properties ao schema, o que nos permitirá definir e validar como cada objecto deve ser estruturado.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
No exemplo acima, estamos declarando que o objecto link possui uma propriedade name. Para definir o tipo de dado esperado, cada propriedade precisa definir a palavra-chave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
A definição de schema acima estabelece que o objecto link possui uma propriedade name do tipo string, o que significa que apenas valores de string serão aceitos para essa propriedade. Atualmente, os seguintes tipos são suportados:
string: O valor da propriedade é armazenado como uma string.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: - nome 1 - nome 2 - nome 3categories: O valor da propriedade é um array de IDs de categorias válidos.groups: O valor da propriedade é um array de IDs de grupos válidos.tags: O valor da propriedade é um array de nomes de tags válidos.
Com o schema definido, o valor padrão da configuração agora pode ser definido criando um array em yaml da seguinte forma:
links:
type: objects
default:
- name: link 1
title: título do link 1
- name: link 2
title: título do link 2
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, basta anotar 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
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: 1
max: 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.
Resolução de pertencimento a grupos
Configurações de objectos podem resolver propriedades do type: groups para um booleano para o usuário atual. Isso é útil quando o código do tema só precisa saber se o usuário atual está em um dos grupos configurados, pois 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: seção 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
A interface de administração e o valor da configuração armazenada ainda usam o array original de groups. No objecto settings de tempo de execução do frontend, o Discourse remove os IDs dos grupos de cada objecto 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 em propriedades de schema de objecto com type: groups. Ela também funciona em schemas de objectos aninhados e com grupos automáticos como logged_in_users e anonymous_users.
Estrutura de objectos aninhados
Um objecto também pode ter uma propriedade que contém um array de objectos. Para criar uma estrutura de objectos aninhados, uma propriedade também pode ser anotada com type: objects e a definição de schema associada.
sections:
type: objects
default:
- name: seção 1
links:
- name: link 1
url: /alguma/url
- name: link 2
url: /outra/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 no locale 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: seção 1
links:
- name: link 1
url: /alguma/url
- name: link 2
url: /outra/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 possui controle de versão - sugira alterações no github.
. Foi mais uma tentativa de ver se era possível, mas não uma abordagem razoável.