Discourse permite que los temas tengan “ajustes” que pueden ser agregados por los desarrolladores de temas 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 preocuparse por perder sus cambios con futuras actualizaciones del tema.
Los temas también pueden alterar ciertos ajustes configurables del sitio; para más información al respecto, consulte el tema Ajustes configurables del sitio.
Agregar ajustes a su tema
Agregar ajustes a su tema es un poco diferente a agregar código CSS y JS, es decir, no hay forma de hacerlo a través de la interfaz de usuario.
La forma de agregar ajustes 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 los ajustes 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 nuevo para usted: funciona mayormente de la misma manera que agregar ajustes del sitio a su plugin. Simplemente escriba algún YAML válido en su archivo de ajustes y estará listo para comenzar.
Un ajuste de tema válido debe tener un nombre y un valor predeterminado; ese es el mínimo absoluto y se ve así:
ajuste_sencillo: true
Como probablemente pueda deducir, eso creará un ajuste con el nombre ajuste_sencillo y tendrá true como su valor predeterminado.
De manera similar, puede agregar algo como esto:
nombre_del_sitio: Mis Foros
max_avatares: 7
Y tendrá dos ajustes más, nombre_del_sitio que será un ajuste de tipo cadena con “Mis Foros” como valor predeterminado, y max_avatares como un ajuste de tipo entero con valor predeterminado de 7.
Puede acceder a sus ajustes en su código JS de esta manera: settings.clave_de_su_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 puede utilizarlos.
Tipos compatibles
Existen 9 tipos de ajustes:
integer(entero)float(flotante)string(cadena)bool(para booleano)list(lista)enum(enumeración)objects(objeto, reemplazo dejson_schema)upload(para imágenes)icon(para un único icono del conjunto de iconos de Discourse)
Y puede especificar el tipo agregando un atributo type a su ajuste de la siguiente manera:
ajuste_flotante:
type: float
default: 3.14
Debo decir que no siempre es necesario establecer explícitamente un atributo type porque Discourse es lo suficientemente inteligente como para determinar el tipo de ajuste a partir del valor predeterminado del ajuste. Así que puede reducir el ejemplo anterior a esto:
ajuste_flotante:
default: 3.14
Dicho esto, necesita establecer un atributo de tipo cuando trabaje con ajustes de tipo list, enum y icon, de lo contrario Discourse no los reconocerá correctamente.
Ajuste de Lista:
frutas_autorizadas:
default: manzanas|naranjas
type: list
Ajuste de Enumeración:
fruta_favorita:
default: naranja
type: enum
choices:
- manzana
- banana
En caso de que la diferencia entre los ajustes de lista y enumeración no esté clara para usted: los ajustes de enumeración 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, los ajustes de lista permiten a sus usuarios crear su propia lista (es decir, una matriz) de valores. Pueden agregar o eliminar valores de la lista predeterminada del ajuste.
Puede establecer la lista predeterminada de valores para el ajuste uniendo los valores con un carácter barra vertical |. Vea el ajuste de lista en el ejemplo anterior.
Puede ver un caso de uso real para los ajustes de lista aquí: Auto-Linkify Words.
Ajuste de Icono:
icono_del_banner:
default: bullhorn
type: icon
Los ajustes de icono brindan a los propietarios del sitio un selector de iconos con función de búsqueda, 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 necesidad de registrarlo por separado.
Tipo objects
El tipo de ajuste objects es un tipo especial que le permite lograr ajustes avanzados con estructura y validaciones personalizadas. Tenemos una documentación separada para este tipo.
Descripción y localización de ajustes
Puede agregar texto descriptivo a su ajuste de tema y se mostrará como una etiqueta directamente debajo del ajuste. Para hacerlo, simplemente agregue un atributo description a su ajuste de la siguiente manera:
frutas_autorizadas:
default: manzanas|naranjas
type: list
description: "Este texto se mostrará debajo de este ajuste y explica qué hace el ajuste!"
Y obtendrá esto:
Compatibilidad con múltiples idiomas
Si conoce más de un idioma y desea agregar compatibilidad 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 desee echar un vistazo a How to add a new language)
Luego, necesitará encontrar el código de su 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 tiene compatibilidad para 3 idiomas: inglés, árabe y francés.
Atributos y opciones adicionales de ajustes
Atributos min y max
A veces puede necesitar especificar límites que el valor de un ajuste 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 ajuste de la siguiente manera:
ajuste_entero:
default: 10
min: 5
max: 100
Puede 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 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 ajustes en su 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 etiquetas <template> .gjs.
Establecer variables CSS
En CSS, se creará una variable para cada ajuste de su tema y cada variable tendrá el mismo nombre que el ajuste que representa.
Así que si tuviera un ajuste flotante llamado tamano_fuente_global y un ajuste de cadena llamado fondo_del_sitio, 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 según si el usuario actual pertenece a un grupo configurado. Evite 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, agregue resolve_group_membership: true para resolver la verificación en el lado del servidor:
grupos_autorizados_para_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 original de grupos. En su lugar, Discourse agrega 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_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. Los ajustes de tema de tipo objeto pueden usar la misma opción en propiedades de type: groups. Consulte tipo objects para ajustes de tema para más detalles.
Temas Relacionados
Este documento está controlado por versiones - sugiera cambios en github.