Introducimos un nuevo type: objects a los tipos admitidos para configuraciones de tema, el cual puede usarse para reemplazar el tipo existente json_schema, que tenemos la intención de obsoletizar pronto.
Definiendo una configuración de tema de tipo objects
Para crear una configuración de tema de tipo objects, primero define una clave de nivel superior igual que cualquier otra configuración de tema, la cual será usada como el nombre de la configuración.
links: ...
A continuación, añade 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 objects, mientras que la anotación default: [] establece el valor predeterminado de la configuración como un array vacío. Ten en cuenta que el valor predeterminado también puede establecerse como un array de objetos, lo cual demostraremos una vez que se haya definido el schema.
Para definir el esquema, primero define el name del esquema de la siguiente manera:
links:
type: objects
default: []
schema:
name: link
A continuación, añadiremos la palabra clave properties al esquema, lo cual nos permitirá definir y validar cómo debería verse cada objeto.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
En el ejemplo anterior, estamos indicando que el objeto link tiene una propiedad name. Para definir el tipo de datos esperado, cada propiedad necesita definir la palabra clave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
La definición de 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 un string.integer: El valor de la propiedad se almacena como un entero.float: El valor de la propiedad se almacena como un float.boolean: El valor de la propiedad estrueofalse.upload: El valor de la propiedad es la URL del archivo 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 3categories: El valor de la propiedad es un array de ids de categoría válidos.groups: El valor de la propiedad es un array de ids de grupo válidos.tags: El valor de la propiedad es un array de nombres de etiqueta válidos.
Con el esquema definido, el valor predeterminado de la configuración ahora puede establecerse definiendo un array 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 requeridas
Todas las propiedades definidas son opcionales por defecto. Para marcar una propiedad como requerida, simplemente anota la propiedad con required: true. Una propiedad también puede marcarse como opcional anotando la propiedad con required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Validaciones personalizadas
Para ciertos tipos de propiedad, hay soporte integrado para validaciones personalizadas, las cuales pueden declararse anotando la propiedad con la palabra clave validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min: 1
max: 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 pertenencia a grupo
Las configuraciones de objetos pueden resolver propiedades de type: groups a un booleano para el usuario actual. Esto es útil cuando el código del tema solo necesita saber si el usuario actual está en uno de los grupos configurados, porque currentUser.groups solo incluye grupos que son visibles para el usuario.
Añade 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 usuario de administrador y el valor de configuración almacenado aún usan el array original groups. En el objeto settings de tiempo de ejecución del frontend, Discourse elimina los ids de grupo de cada objeto y añade 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 está en al menos uno de los grupos seleccionados para esta sección.
}
}
Esta opción solo es válida en propiedades de esquema de objeto con type: groups. También funciona en 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 un array 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 configuración y localización
Para añadir una descripción para la configuración en el locale en, crea un archivo locales/en.yml con el siguiente formato dada la siguiente configuración de tema de 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 es una descripción para la configuración de tema sections
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á bajo control de versiones - sugiere cambios en github.
. Fue más un intento de ver si era posible, pero no un enfoque razonable.