Discourse permite que los temas tengan “ajustes” que los desarrolladores de temas pueden añadir para permitir que los propietarios del sitio personalicen 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 en futuras actualizaciones del tema.
Los temas también pueden modificar ciertos ajustes configurables del sitio; para más información al respecto, consulta el tema Ajustes configurables del sitio.
Añadir ajustes a tu tema
Añadir ajustes a tu tema es un poco diferente a añadir código CSS y JS, ya que no hay forma de hacerlo a través de la interfaz de usuario.
La forma de añadir ajustes es crear un repositorio para tu tema, y en la carpeta raíz de tu repositorio crear un nuevo archivo settings.yaml (o settings.yml). En este archivo usarás el lenguaje YAML para definir los ajustes de tu tema.
Nota: Podrías encontrar útil utilizar la CLI de Temas, que simplifica enormemente el proceso de desarrollo.
Si estás familiarizado con el desarrollo de plugins, esto no debería ser nuevo para ti: funciona principalmente de la misma manera que añadir ajustes de sitio a tu plugin. Simplemente agrega algún YAML válido en tu archivo de ajustes y estarás listo para empezar.
Un ajuste de tema válido debe tener un nombre y un valor predeterminado, ese es el mínimo indispensable y se ve así:
ajuste_sencillo: true
Como probablemente puedas deducir, eso creará un ajuste con el nombre ajuste_sencillo y tendrá true como su valor predeterminado.
De manera similar, puedes añadir algo como esto:
nombre_sitio: Mis Foros
max_avatares: 7
Y tendrás dos ajustes más, nombre_sitio que será un ajuste de tipo cadena con “Mis Foros” como valor predeterminado, y max_avatares como un ajuste de tipo entero con un valor predeterminado de 7.
Puedes acceder a tus ajustes en tu código JS de esta manera: settings.tu_clave_ajuste.
Hasta este punto hemos cubierto la forma más sencilla de definir ajustes. En la siguiente sección profundizaremos un poco más en los diversos tipos de ajustes y cómo puedes utilizarlos.
Tipos admitidos
Hay 8 tipos de ajustes:
integerfloatstringbool(para booleanos)listenumobjects(reemplazo dejson_schema)upload(para imágenes)
Y puedes especificar el tipo añadiendo un atributo type a tu ajuste de esta manera:
ajuste_flotante:
type: float
default: 3.14
Debo decir que no siempre tienes que establecer explícitamente un atributo type porque Discourse es lo suficientemente inteligente como para deducir el tipo de ajuste a partir del valor predeterminado del ajuste. Así que puedes reducir el ejemplo anterior a esto:
ajuste_flotante:
default: 3.14
Dicho esto, necesitas establecer un atributo de tipo cuando trabajes con ajustes de tipo list y enum, de lo contrario Discourse no los reconocerá correctamente.
Ajuste de Lista:
frutas_autorizadas:
default: manzanas|naranjas
type: list
Ajuste de Enum:
fruta_favorita:
default: naranja
type: enum
choices:
- manzana
- banana
En caso de que la diferencia entre ajustes de lista y enum no te quede clara: los ajustes de enum permiten que los usuarios de tu tema seleccionen solo un valor de un conjunto de valores definidos por ti (ver el atributo choices).
Por otro lado, los ajustes de lista permiten que tus usuarios creen su propia lista (es decir, una matriz) de valores. Pueden añadir o eliminar valores de la lista predeterminada del ajuste.
Puedes establecer la lista predeterminada de valores para el ajuste uniendo los valores con el carácter barra vertical |. Consulta el ajuste de lista en el ejemplo anterior.
Puedes ver un caso de uso real para ajustes de lista aquí: Auto-Linkify Words.
Tipo objects
El tipo de ajuste objects es un tipo especial que te permite lograr ajustes avanzados con estructura y validaciones personalizadas. Tenemos una documentación separada para este tipo.
Descripción de ajustes y localizaciones
Puedes añadir texto de descripción a tu ajuste de tema y se mostrará como una etiqueta directamente debajo del ajuste. Para hacerlo, simplemente añade un atributo description a tu ajuste de la siguiente manera:
frutas_autorizadas:
default: manzanas|naranjas
type: list
description: "¡Este texto se mostrará debajo de este ajuste y explica lo que hace el ajuste!"
Y obtendrás esto:
Soporte para múltiples idiomas
Si conoces más de un idioma y deseas añadir soporte para esos idiomas a tu tema, puedes hacerlo siempre y cuando Discourse admita dichos idiomas.
En primer lugar, asegúrate de que el idioma que deseas admitir 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 puedes ver tu idioma en la lista, quizás quieras echar un vistazo a How to add a new language)
Luego, necesitarás encontrar el código de tu idioma en 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 la siguiente manera:
frutas_autorizadas:
default: manzanas|naranjas
type: list
description:
en: Texto en inglés
ar: نص باللغة العربية
fr: Texte français
Y ahora tienes soporte para 3 idiomas: inglés, árabe y francés.
Atributos y opciones adicionales de ajustes
Atributos min y max
A veces puede que necesites especificar límites que un valor de ajuste no pueda exceder para evitar que tus usuarios rompan accidentalmente el tema o posiblemente todo el sitio.
Para especificar límites, simplemente añade un atributo min o max o ambos a tu ajuste de la siguiente manera:
ajuste_entero:
default: 10
min: 5
max: 100
Puedes especificar límites para ajustes de tipo integer, float y string. Para ajustes de tipo integer y float, se verifica el valor del ajuste en sí contra los límites. Y para ajustes de tipo string, se verifica la longitud del valor contra los límites especificados.
Si tu 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 ajustes en tu JS/CSS/Handlebars
Los ajustes de 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("los ajustes son", settings);
});
Este objeto settings también es utilizable normalmente dentro de las etiquetas <template> de .gjs.
Establecer variables CSS
En CSS, se creará una variable para cada ajuste de tu tema y cada variable tendrá el mismo nombre que el ajuste que representa.
Así que si tuvieras un ajuste flotante llamado tamano_fuente_global y un ajuste de cadena llamado fondo_sitio, podrías hacer algo como esto en el CSS de tu tema:
html {
font-size: #{$tamano-fuente-global}px;
background: $fondo-sitio;
}
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 pertenece a un grupo configurado. Evita verificar currentUser.groups para esto, porque solo incluye grupos que son visibles para el usuario, y puede omitir grupos ocultos.
Para ajustes de lista respaldados por grupos, añade resolve_group_membership: true para resolver la verificación en el servidor:
grupos_autorizados_boton_copiar:
default: "1|3"
type: list
list_type: group
resolve_group_membership: true
Esta opción solo es válida cuando el ajuste 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 ajuste 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_grupos_autorizados_boton_copiar) {
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.
Temas Relacionados
Este documento está controlado por versiones - sugiere cambios en github.