Discourse tiene la capacidad de que los temas tengan “configuraciones” que los desarrolladores de temas pueden agregar para permitir a los propietarios de sitios web personalizar los temas a través de la interfaz de usuario sin tener que cambiar ninguna línea de código y sin preocuparse por perder sus cambios con futuras actualizaciones del tema.
Los temas también pueden alterar ciertas configuraciones de sitio personalizables; para obtener más información sobre eso, consulte el tema Configuraciones de sitio personalizables.
Agregar configuraciones a su tema
Agregar configuraciones a su tema es un poco diferente de agregar código CSS y JS, ya que no hay forma de hacerlo a través de la interfaz de usuario.
La forma de agregar 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, usará el lenguaje YAML para definir las configuraciones de su tema.
Nota: Puede resultar útil hacer uso de la CLI de temas, que simplifica enormemente el proceso de desarrollo.
Ahora, si está familiarizado con el desarrollo de plugins, esto no debería ser algo nuevo para usted: funciona de manera muy similar a agregar configuraciones de sitio a su plugin. Simplemente coloque YAML válido en su archivo de configuración y estará listo para ir.
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 notar, eso creará una configuración con el nombre simple_setting y tendrá true como su valor predeterminado.
De manera similar, puede agregar 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 de entero con un valor predeterminado de 7.
Puede acceder a sus configuraciones en su código JS de esta 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 usarlas.
Tipos admitidos
Hay 9 tipos de configuraciones:
integerfloatstringbool(para booleano)listenumobjects(reemplazo dejson_schema)upload(para imágenes)icon(para un icono individual del conjunto de iconos de Discourse)
Y puede especificar el tipo agregando un atributo type a su configuración de esta manera:
float_setting:
type: float
default: 3.14
Debo decir que no siempre tiene que establecer explícitamente un atributo type, ya que 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, enum e icon, de lo contrario Discourse no las reconocerá correctamente.
Configuración de lista:
whitelisted_fruits:
default: apples|oranges
type: list
Configuración Enum:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Por si la diferencia entre las configuraciones de lista y enum no le queda clara: las configuraciones enum permiten a los usuarios de su tema seleccionar solo un valor de un conjunto de valores definidos por usted (vea el atributo choices).
Por otro lado, las configuraciones de lista permiten a sus usuarios crear su propia lista (es decir, un arreglo) de valores. Pueden agregar 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 un carácter de barra vertical |. Vea 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.
Configuración de icono:
banner_icon:
default: bullhorn
type: icon
Las configuraciones de icono le dan a los propietarios del sitio un selector de iconos buscable, y el valor es el nombre del icono. Discourse agrega el icono seleccionado a la hoja de sprites, por lo que puede renderizarlo en su tema sin registrarlo por separado.
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 agregar 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 agregue un atributo description a su configuración de esta manera:
whitelisted_fruits:
default: apples|oranges
type: list
description: "This text will be displayed under this setting and it explains what the setting does!"
Y obtendrá esto:
Soporte para múltiples idiomas
Si conoce más de un idioma y desea agregar soporte para esos idiomas a su tema, puede hacerlo por completo, siempre que Discourse admita dichos idiomas.
En primer lugar, asegúrese de que el idioma que desea admitir esté en esta lista:
Lista de idiomas
| Code | Name | |||
|---|---|---|---|---|
| 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, es posible que desee echar un vistazo a How to add a new language)
Luego, deberá encontrar el código de su idioma de la lista anterior y usar el código de idioma como clave bajo el atributo description y la traducción como valor para la clave de esta manera:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: English text
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 el valor de una configuración no pueda exceder para evitar que sus usuarios rompan accidentalmente el tema o posiblemente todo el sitio.
Para especificar límites, simplemente agregue un atributo min o max o ambos a su configuración de esta manera:
integer_setting:
default: 10
min: 5
max: 100
Puede especificar límites para configuraciones de tipo integer, float y string. Para las configuraciones integer y float, el valor de la configuración en sí se comprueba contra los límites. Y para las configuraciones string, la longitud del valor se comprueba 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ínimos y máximos.
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("settings are", settings);
});
Este objeto settings también es utilizable de forma 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 tenía una configuración 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
A veces, los componentes del tema 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, ya que solo incluye grupos que son visibles para el usuario y puede omitir grupos ocultos.
Para las configuraciones de lista basadas en grupos, agregue 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á habilitado, el objeto settings del frontend no incluye la lista original de grupos. En cambio, Discourse agrega un booleano con el mismo nombre de configuración prefijado con 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 tema de objetos pueden usar la misma opción en propiedades de type: groups. Consulte tipo objects para configuraciones de tema para obtener detalles.
Temas relacionados
Este documento está controlado por versiones: sugiera cambios en github.