dockerfluxodecaixapro/rules/18_THEMES_CUSTOMIZER.md

Sistema de Temas e Customizer (Arquitetura)

Este documento detalha o funcionamento técnico do sistema de temas do SysCMS, incluindo a herança de templates e o motor de personalização dinâmica.

1. Arquitetura de Herança (Template Hierarchy)

O SysCMS utiliza um motor de busca de arquivos em camadas para permitir a máxima flexibilidade sem duplicidade de código:

1. Tema Ativo (themes/{active}/): Prioridade máxima.
2. Tema Pai (themes/{parent}/): Se o tema ativo tiver a tag Template no seu style.css.
3. Módulos (modules/{module}/views/): Fallback automático para as views padrão do sistema.
4. Templates Globais (templates/): Fallback para layouts e componentes comuns.

2. Overrides de Módulos

Para sobrescrever a visualização de um módulo (ex: index), o tema deve replicar a estrutura interna do módulo: themes/{tema}/modules/{nome_do_modulo}/views/{template}.twig

Isso permite que um tema mude apenas partes específicas de um módulo sem afetar sua lógica de controle.

3. O Personalizador (Customizer)

O Customizer é alimentado por um arquivo JSON e armazena os valores no banco de dados.

Fluxo de Dados:

1. Definição: O tema declara campos no arquivo customizer.json.
2. Gestão: O administrador altera os valores em Sistema > Temas > Personalizar.
3. Persistência: Os valores são salvos na tabela system_config com a chave theme_settings_{slug_do_tema}.
4. Injeção: O Kernel\View.php lê esses valores e os injeta na variável global theme_settings em todas as views Twig.

Tipos de Campos Suportados:

• color: Seletor de cores hexadecimal.
• text: Campo de texto simples.
• switch: Interruptor booleano (on/off).
• select: Menu suspenso com opções pré-definidas.

4. Assets e URLs Dinâmicas

• Use theme_url() para carregar arquivos CSS/JS/Imagens do tema. Ele resolverá automaticamente o caminho correto considerando a herança (Child > Parent).
• Use asset_url() para arquivos globais na pasta /public/assets.

5. Diretrizes para Desenvolvedores (IA)

• Sempre verifique o tema ativo: Antes de modificar qualquer arquivo em /modules/, verifique se o usuário deseja que a mudança seja global ou apenas para o tema atual.
• Não altere o Kernel para novos temas: O sistema de temas já é genérico. Novas funcionalidades de temas devem ser implementadas via customizer.json e lógica de template.
• Child Themes: Ao criar temas derivados, utilize a tag Template: no style.css para manter o código limpo e herdar funcionalidades do tema base.