Presentamos un nuevo type: objects en los tipos compatibles para la configuración del tema, que se puede utilizar para reemplazar el tipo json_schema existente que pretendemos deprecar pronto.
Definir una configuración de tema de tipo objetos
Para crear una configuración de tema de tipo objetos, defina primero una clave de nivel superior, igual que con cualquier configuración de tema, que se utilizará como el nombre de la configuración.
links: ...
A continuación, agregue las palabras clave type, default y schema a la configuración.
links:
type: objects
default: []
schema: ...
type: objects indica que esta será una configuración de tipo objetos, mientras que la anotación default: [] establece el valor predeterminado de la configuración en una matriz vacía. Tenga en cuenta que el valor predeterminado también puede ser una matriz de objetos, lo cual demostraremos una vez que se haya definido el schema.
Para definir el esquema, defina primero el name del esquema de la siguiente manera:
links:
type: objects
default: []
schema:
name: link
A continuación, agregaremos la palabra clave properties al esquema, lo que nos permitirá definir y validar cómo debe ser cada objeto.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
En el ejemplo anterior, indicamos que el objeto link tiene una propiedad name. Para definir el tipo de datos esperado, cada propiedad debe definir la palabra clave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
La definición del esquema anterior establece que el objeto link tiene una propiedad name de tipo string, lo que significa que solo se aceptarán valores de tipo string para la propiedad. Actualmente se admiten los siguientes tipos:
-
string: El valor de la propiedad se almacena como una cadena. Establezcatextarea: truepara usar un área de texto expandible:description: type: string textarea: true validations: max_length: 500 -
integer: El valor de la propiedad se almacena como un entero. -
float: El valor de la propiedad se almacena como un número de punto flotante. -
boolean: El valor de la propiedad estrueofalse. -
upload: El valor de la propiedad es la URL del adjunto. -
enum: El valor de la propiedad debe ser uno de los valores definidos en la palabra clavechoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: El valor de la propiedad es una matriz de IDs de categorías válidos. -
groups: El valor de la propiedad es una matriz de IDs de grupos válidos. -
tags: El valor de la propiedad es una matriz de nombres de etiquetas válidos. -
icon: El valor de la propiedad es el nombre de un solo icono del conjunto de iconos de Discourse. Los iconos seleccionados se agregan automáticamente a la hoja de sprites, por lo que se pueden renderizar sin necesidad de registrarlos por separado.
Con el esquema definido, ahora se puede establecer el valor predeterminado de la configuración definiendo una matriz en yaml de la siguiente manera:
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
Propiedades obligatorias
Todas las propiedades definidas son opcionales por defecto. Para marcar una propiedad como obligatoria, simplemente anote la propiedad con required: true. Una propiedad también puede marcarse como opcional anotándola con required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Los valores string, datetime e icon vacíos, así como las listas vacías de categories, groups y tags, se consideran ausentes: las propiedades obligatorias los rechazan y las propiedades opcionales omiten sus validaciones. false se considera establecido.
Validaciones personalizadas
Para ciertos tipos de propiedades, existe soporte integrado para validaciones personalizadas, que se pueden declarar anotando la propiedad con la palabra clave validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Validaciones para tipos string
min_length: Longitud mínima de la propiedad. El valor de la palabra clave debe ser un entero.max_length: Longitud máxima de la propiedad. El valor de la palabra clave debe ser un entero.url: Valida que la propiedad sea una URL válida. El valor de la palabra clave puede sertrue/false.
Validaciones para tipos integer y float
min: Valor mínimo de la propiedad. El valor de la palabra clave debe ser un entero.max: Valor máximo de la propiedad. El valor de la palabra clave debe ser un entero.
Validaciones para tipos tags, groups y categories
min: Número mínimo de registros para la propiedad. El valor de la palabra clave debe ser un entero.max: Número máximo de registros para la propiedad. El valor de la palabra clave debe ser un entero.
Resolución de la membresía de grupos
Las configuraciones de objetos pueden resolver las propiedades de type: groups a un valor booleano para el usuario actual. Esto es útil cuando el código del tema solo necesita saber si el usuario actual pertenece a uno de los grupos configurados, porque currentUser.groups solo incluye grupos que son visibles para el usuario.
Agregue resolve_group_membership: true a la propiedad 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
La interfaz de administración y el valor de la configuración almacenada siguen utilizando la matriz groups original. En el objeto settings del runtime del frontend, Discourse elimina los IDs de grupo de cada objeto y agrega un booleano con el mismo nombre de propiedad prefijado por user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// El usuario pertenece al menos a un grupo seleccionado para esta sección.
}
}
Esta opción solo es válida en las propiedades del esquema de objeto con type: groups. También funciona con esquemas de objetos anidados y con grupos automáticos como logged_in_users y anonymous_users.
Estructura de objetos anidados
Un objeto también puede tener una propiedad que contenga una matriz de objetos. Para crear una estructura de objetos anidados, una propiedad también puede anotarse con type: objects y la definición de schema asociada.
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
Descripción de la configuración y localización
Para agregar una descripción para la configuración en la configuración regional en, cree un archivo locales/en.yml con el siguiente formato dada la siguiente configuración de tema de tipo objetos.
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 es una descripción para la configuración de tema de secciones
schema:
properties:
name:
label: Nombre
description: La descripción para la propiedad
links:
name:
label: Nombre
description: La descripción para la propiedad
url:
label: URL
description: La descripción para la propiedad
Este documento está controlado por versiones - sugiera cambios en github.
. Fue más un intento de ver si era posible, pero no un enfoque razonable.