Estaremos introduciendo un nuevo type: objects en los tipos admitidos para configuraciones de tema, que puede usarse para reemplazar el tipo json_schema existente, que tiene la intención de dejar de usarse pronto.
Definición de 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, que se utilizará como nombre de la configuración.
links: ...
A continuación, agrega 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. Tenga en cuenta que el valor predeterminado también se puede establecer 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, agregaremos la palabra clave properties al esquema, lo que nos permitirá definir y validar cómo debe 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 debe definir la palabra clave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
La definición de esquema anterior indica que el objeto link tiene una propiedad name de tipo string, lo que significa que solo se aceptarán valores de cadena para la propiedad. Actualmente, se admiten los siguientes tipos:
string: El valor de la propiedad se almacena como una cadena.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 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.icon: El valor de la propiedad es el nombre de un icono individual 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 registrarse por separado.
Con el esquema definido, el valor predeterminado de la configuración ahora se puede estableciendo 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 se puede marcar 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
Los valores en blanco de string, datetime e icon y las listas vacías de categories, groups y tags cuentan como faltantes: las propiedades requeridas las rechazan y las propiedades opcionales omiten sus validaciones. false cuenta como establecido.
Validaciones personalizadas
Para ciertos tipos de propiedades, hay 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 membresía de grupo
Las configuraciones de objetos pueden resolver propiedades 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.
Agrega 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 configuración almacenado siguen utilizando el array original de groups. En el objeto settings del tiempo de ejecución del frontend, Discourse elimina los ids de grupo de cada objeto y agrega un booleano con el mismo nombre de propiedad prefijado con 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 para propiedades de 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 un array de objetos. Para crear una estructura de objetos anidados, una propiedad también se puede anotar con type: objects y la definición 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 y localización de la configuración
Para agregar una descripción para la configuración en el idioma en, crea un archivo locales/en.yml con el siguiente formato dado el siguiente tipo de configuración de tema 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á controlado por versiones - sugiere cambios en github.
. Fue más un intento de ver si era posible, pero no un enfoque razonable.