Discourse permite que los temas tengan “configuraciones” que los desarrolladores de temas pueden añadir para permitir a los propietarios del sitio personalizar los temas a través de la interfaz de usuario, sin necesidad de cambiar ninguna línea de código ni preocuparse por perder sus cambios en futuras actualizaciones del tema.
Los temas también pueden modificar ciertas configuraciones del sitio personalizables; para más información al respecto, consulte el tema Configuraciones del sitio personalizables.
Añadir configuraciones a su tema
Añadir configuraciones a su tema es un poco diferente a añadir código CSS y JS, ya que no hay ninguna manera de hacerlo a través de la interfaz de usuario.
La forma de añadir configuraciones es crear un repositorio para su tema y, en la carpeta raíz de su repositorio, crear un nuevo archivo settings.yaml (o settings.yml). En este archivo, utilizará el lenguaje YAML para definir las configuraciones de su tema.
Nota: Puede resultar útil utilizar la CLI de temas, que simplifica enormemente el proceso de desarrollo.
Si está familiarizado con el desarrollo de plugins, esto no debería ser nuevo para usted: funciona básicamente de la misma manera que añadir configuraciones del sitio a su plugin. Simplemente agregue YAML válido en su archivo de configuraciones y estará listo para comenzar.
Una configuración de tema válida debe tener un nombre y un valor predeterminado; ese es el mínimo absoluto y se ve así:
simple_setting: true
Como probablemente pueda deducir, esto creará una configuración con el nombre simple_setting y tendrá true como valor predeterminado.
De manera similar, puede añadir algo como esto:
site_name: My Forums
max_avatars: 7
Y tendrá dos configuraciones más: site_name, que será una configuración de cadena con “My Forums” como valor predeterminado, y max_avatars, como una configuración entera con un valor predeterminado de 7.
Puede acceder a sus configuraciones en su código JS de la siguiente manera: settings.your_setting_key.
Hasta este punto, hemos cubierto la forma más simple de definir configuraciones. En la siguiente sección, profundizaremos un poco más en los diversos tipos de configuraciones y cómo puede utilizarlas.
Tipos compatibles
Hay 8 tipos de configuraciones:
integerfloatstringbool(para booleano)listenumobjects(reemplazo dejson_schema)upload(para imágenes)
Y puede especificar el tipo añadiendo un atributo type a su configuración de la siguiente manera:
float_setting:
type: float
default: 3.14
Debo decir que no siempre tiene que establecer explícitamente un atributo type, porque Discourse es lo suficientemente inteligente como para determinar el tipo de configuración a partir del valor predeterminado de la configuración. Así que puede reducir el ejemplo anterior a esto:
float_setting:
default: 3.14
Dicho esto, necesita establecer un atributo de tipo cuando trabaje con configuraciones list y enum, de lo contrario Discourse no las reconocerá correctamente.
Configuración de lista:
whitelisted_fruits:
default: apples|oranges
type: list
Configuración de enumeración:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
En caso de que la diferencia entre las configuraciones de lista y enumeración no le quede clara: las configuraciones de enumeración permiten a los usuarios de su tema seleccionar solo un valor de un conjunto de valores definidos por usted (ver el atributo choices).
Por otro lado, las configuraciones de lista permiten a sus usuarios crear su propia lista (es decir, una matriz) de valores. Pueden añadir o eliminar valores de la lista predeterminada de la configuración.
Puede establecer la lista predeterminada de valores para la configuración uniendo los valores con el carácter barra vertical |. Consulte la configuración de lista en el ejemplo anterior.
Puede ver un caso de uso real para las configuraciones de lista aquí: Auto-Linkify Words.
Tipo objects
El tipo de configuración objects es un tipo especial que le permite lograr configuraciones avanzadas con estructura y validaciones personalizadas. Tenemos una documentación separada para este tipo.
Descripción de la configuración y localizaciones
Puede añadir texto de descripción a su configuración de tema y se mostrará como una etiqueta directamente debajo de la configuración. Para hacerlo, simplemente añada un atributo description a su configuración de la siguiente manera:
whitelisted_fruits:
default: apples|oranges
type: list
description: "Este texto se mostrará debajo de esta configuración y explica qué hace la configuración!"
Y obtendrá esto:
Soporte para múltiples idiomas
Si conoce más de un idioma y desea añadir soporte para esos idiomas a su tema, puede hacerlo siempre que Discourse soporte dichos idiomas.
En primer lugar, asegúrese de que el idioma que desea apoyar esté en esta lista:
Lista de idiomas
| Código | Nombre | |||
|---|---|---|---|---|
| ar | اللغة العربية | |||
| bs_BA | bosanski jezik | |||
| ca | català | |||
| cs | čeština | |||
| da | dansk | |||
| de | Deutsch | |||
| el | ελληνικά | |||
| en | English | |||
| es | Español | |||
| et | eesti | |||
| fa_IR | فارسی | |||
| fi | suomi | |||
| fr | Français | |||
| gl | galego | |||
| he | עברית | |||
| id | Indonesian | |||
| it | Italiano | |||
| ja | 日本語 | |||
| ko | 한국어 | |||
| lv | latviešu valoda | |||
| nb_NO | Norsk bokmål | |||
| nl | Nederlands | |||
| pl_PL | język polski | |||
| pt | Português | |||
| pt_BR | Português (BR) | |||
| ro | limba română | |||
| ru | Русский | |||
| sk | slovenčina | |||
| sq | Shqip | |||
| sr | српски језик | |||
| sv | svenska | |||
| te | తెలुగు | |||
| th | ไทย | |||
| tr_TR | Türkçe | |||
| uk | українська мова | |||
| ur | اردو | |||
| vi | Việt Nam | |||
| zh_CN | 中文 | |||
| zh_TW | 中文 (TW) |
(Si no puede ver su idioma en la lista, quizás quiera echar un vistazo a How to add a new language)
Luego, necesitará encontrar el código de su idioma en la lista anterior y utilizar el código de idioma como clave bajo el atributo description y la traducción como valor para la clave de la siguiente manera:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: Texto en inglés
ar: نص باللغة العربية
fr: Texte français
Y ahora tiene soporte para 3 idiomas: inglés, árabe y francés.
Atributos y opciones adicionales de configuración
Atributos min y max
A veces puede necesitar especificar límites que un valor de configuración no pueda exceder para evitar que sus usuarios rompan accidentalmente el tema o posiblemente todo el sitio.
Para especificar límites, simplemente añada un atributo min o max o ambos a su configuración de la siguiente manera:
integer_setting:
default: 10
min: 5
max: 100
Puede especificar límites para configuraciones de tipo integer, float y string. Para configuraciones integer y float, el valor de la configuración en sí se verifica contra los límites. Y para configuraciones string, la longitud del valor se verifica contra los límites especificados.
Si su usuario intenta ingresar un valor que no esté dentro del rango permitido, verá un error que le indica cuáles son los valores mínimo y máximo.
Acceso a configuraciones en su JS/CSS/Handlebars
Las configuraciones del tema están disponibles globalmente como una variable settings en los archivos JavaScript del tema. Por ejemplo:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("las configuraciones son", settings);
});
Este objeto settings también es utilizable de manera normal dentro de las etiquetas <template> de .gjs.
Establecer variables CSS
En CSS, se creará una variable para cada configuración de su tema y cada variable tendrá el mismo nombre que la configuración que representa.
Así que si tuviera una configuración de punto flotante llamada global_font_size y una configuración de cadena llamada site_background, podría hacer algo como esto en el CSS de su tema:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Resolución de membresía de grupo
Los componentes de tema a veces necesitan mostrar u ocultar una función basándose en si el usuario actual está en un grupo configurado. Evite verificar currentUser.groups para esto, porque solo incluye grupos que son visibles para el usuario, y puede pasar por alto grupos ocultos.
Para configuraciones de lista respaldadas por grupos, añada resolve_group_membership: true para resolver la verificación en el servidor:
copy_button_allowed_groups:
default: "1|3"
type: list
list_type: group
resolve_group_membership: true
Esta opción solo es válida cuando la configuración tiene type: list y list_type: group. Cuando está habilitada, el objeto settings del frontend no incluye la lista de grupos original. En su lugar, Discourse añade un booleano con el mismo nombre de configuración precedido por user_in_:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
if (!settings.user_in_copy_button_allowed_groups) {
return;
}
// El usuario está en al menos uno de los grupos seleccionados.
});
El booleano generado también funciona con grupos automáticos como logged_in_users y anonymous_users. Las configuraciones de objetos de tema pueden utilizar la misma opción en propiedades type: groups. Consulte tipo de objetos para configuraciones de tema para más detalles.
Temas relacionados
Este documento está controlado por versiones - sugiera cambios en github.