Titulo

descripocion

Slider 2

Descripcion Slider 2

Este manual explica paso a paso cómo configurar correctamente el sistema de personalización de temas para que los cambios visuales se apliquen correctamente.

1. Proceso general de personalización

La personalización de temas en MuseDock CMS funciona a través de tres componentes interconectados:

1. theme.json - Define qué opciones de personalización están disponibles
2. template.css - Define cómo se aplican las variables CSS a los elementos HTML
3. ThemeAppearanceController.php - Mapea las opciones del theme.json a las variables CSS

Para que todo funcione correctamente, debe haber coherencia entre estos tres componentes.

2. Paso a paso para añadir una nueva opción personalizable

2.1. Definir la opción en theme.json

Primero, debes definir la opción en el archivo theme.json:

"customizable_options": {
  "header": {
    "type": "section",
    "label": "Cabecera",
    "options": {
      "header_bg_color": {
        "type": "color",
        "label": "Color de fondo de la cabecera principal",
        "default": "#ffffff"
      },
      "nueva_opcion": {
        "type": "color",
        "label": "Etiqueta visible en el panel",
        "default": "#valor-por-defecto"
      }
    }
  }
}

Estructura clave:

• La opción debe estar dentro de una sección (como "header")
• Debe tener un tipo (color, toggle, select, etc.)
• Debe tener una etiqueta visible para el usuario
• El valor por defecto debe ser del tipo correcto para esa opción

2.2. Definir la variable CSS en template.css

Luego, debes definir la variable CSS y su aplicación en template.css:

:root {
  /* Variables existentes */
  --header-bg-color: #ffffff;
  
  /* Nueva variable */
  --nombre-variable-css: #valor-por-defecto;
}

/* Aplicación de variables existentes */
.header-bottom {
  background-color: var(--header-bg-color);
}

/* Aplicación de la nueva variable */
.selector-css {
  propiedad-css: var(--nombre-variable-css);
}

Recuerda:

• El bloque :root debe definir TODAS las variables CSS utilizadas
• Cada variable debe tener un valor por defecto coherente con su tipo
• Debe haber reglas CSS que apliquen estas variables a elementos HTML específicos

2.3. Añadir el mapeo en ThemeAppearanceController.php

Finalmente, modifica el método getOptionCssMappings() para incluir el mapeo entre la opción del theme.json y la variable CSS:

protected function getOptionCssMappings(): array
{
    return [
        // Mapeos existentes
        'header.header_bg_color' => '--header-bg-color',
        
        // Nuevo mapeo
        'seccion.nueva_opcion' => '--nombre-variable-css'
    ];
}

El formato es: 'seccion.opcion' => '--variable-css'

3. Reglas importantes

1. Coherencia de nombres: El nombre de la opción en theme.json (seccion.opcion) debe coincidir exactamente con la clave en el mapeo.
2. Coherencia de valores: El tipo de valor en theme.json (color, texto, número) debe ser compatible con la propiedad CSS que lo utilizará.
3. Completitud del bloque
    
   : Todas las variables CSS usadas en el tema deben estar definidas en el bloque :root del template.css.
4. Mapeo completo: Cada opción definida en theme.json que quieras utilizar debe tener su correspondiente mapeo en getOptionCssMappings().
5. Aplicación efectiva: Cada variable CSS debe aplicarse a al menos un selector HTML en el template.css.

4. Tipos de opciones y sus valores

5. Flujo de ejecución

1. Usuario selecciona opciones en el panel de administración
2. Al guardar, se almacenan en la tabla theme_options
3. El controlador lee estas opciones y genera un CSS personalizado
4. Este CSS aplica las variables personalizadas a los elementos HTML
5. El navegador renderiza el tema con los nuevos valores

6. Depuración de problemas

Si un cambio no se aplica correctamente, verifica:

1. Que la opción esté correctamente definida en theme.json
2. Que la variable CSS esté definida en el bloque :root de template.css
3. Que exista un mapeo en getOptionCssMappings() para esa opción
4. Que la variable CSS se esté aplicando a algún selector en template.css
5. Que el valor guardado en la tabla theme_options sea el esperado

Siguiendo estas pautas, podrás añadir correctamente opciones personalizables a tu tema y asegurarte de que los cambios se apliquen correctamente.