Crie e personalize temas da instalação: organização de diretórios, enqueue de assets, template parts, herança de views e particularidades do RedeMapas.

No Mapas Culturais, um tema controla todos os aspectos visuais de uma instalação: templates HTML, folhas de estilo, scripts, imagens e conteúdo de página. Cada tema é uma classe PHP que estende MapasCulturais\Theme.

O tema ativo é definido em configuração:

// dev/config.d/0.main.php
return [
    'themes.active' => 'redemapas',
];

Temas disponíveis

A cadeia de herança do tema ativo do RedeMapas é:

RedeMapas → BaseV2 → BaseV1

Arquivos em um tema filho sobrescrevem o arquivo correspondente de qualquer tema pai. A busca sobe pela cadeia até encontrar uma correspondência.

Historical ecosystem themes

Older documentation also indexed theme repositories from specific installations and forks. That catalog is useful only as a discovery aid when tracing UI ancestry:

Treat these names as historical references, not as a supported catalog for the current installation.

RedeMapas theme in the repository

In the RedeMapas installation, the active theme is not just an example folder. It is a first-class part of the deployment and should be treated carefully during maintenance.

O guia antigo de desenvolvedores destacava um detalhe operacional que ainda passa despercebido com facilidade: alterações no tema ativo frequentemente precisam ser validadas junto com a configuração de deploy, a UI de autenticação e o comportamento de PWA / Web Push, porque é no tema que essas preocupações específicas da instalação se encontram.

Ao auditar um problema de interface ou login, sempre confirme se o comportamento vem de:

• framework core
• module/plugin code
• src/themes/RedeMapas/
• environment-specific configuration

Directory structure

Each theme lives under src/themes/<ThemeName>/:

src/themes/MyTheme/
  Theme.php          → Main theme class; _init() registers hooks and assets
  conf-base.php      → Theme-specific configuration defaults
  assets/            → Compiled and static files (publicly served)
    css/
    fonts/
    img/
  assets-src/        → Source JS/CSS (compiled by pnpm into assets/)
  views/             → PHP view templates, organized by controller
    agent/
    space/
    event/
    ...
  layouts/           → Page layout wrappers
    default.php
    search.php
    panel.php
    parts/           → Reusable layout fragments
  pages/             → Static Markdown pages

Theme class

A classe do tema fica em Theme.php e deve estender a classe do tema pai:

<?php
namespace MapasCulturais\Themes\MyTheme;

class Theme extends \MapasCulturais\Themes\BaseV2\Theme
{
    static function getThemeFolder(): string
    {
        return __DIR__;
    }

    protected function _init(): void
    {
        parent::_init();

        $app = \MapasCulturais\App::i();

        // Register assets, hooks, and configuration here
        $app->hook('mapasculturais.init', function() {
            $this->publishAssets();
        });
    }

    protected function _publishAssets(): void
    {
        $app = \MapasCulturais\App::i();

        $app->enqueueStyle('app', 'my-theme', 'css/my-theme.css');
        $app->enqueueScript('app', 'my-theme', 'js/my-theme.js', ['jquery']);
    }
}

Enqueueing assets

Use the application's enqueue methods to load stylesheets and scripts. Assets are deduplicated and output in dependency order.

// Enqueue a stylesheet
// Parameters: $group, $name, $path_relative_to_assets/, $dependencies
$app->enqueueStyle('app', 'my-style', 'css/my-style.css');

// Enqueue a stylesheet that depends on another
$app->enqueueStyle('app', 'my-style', 'css/my-style.css', ['base-style']);

// Enqueue a script
$app->enqueueScript('app', 'my-script', 'js/my-script.js');

// Enqueue a script with dependencies
$app->enqueueScript('app', 'my-script', 'js/my-script.js', ['jquery']);

Asset groups and their output order:

Para obter a URL pública de um asset sem imprimi-la:

$url = $this->asset('img/logo.png', false);

// Make a URL available to JavaScript
$this->jsObject['assets']['logo'] = $this->asset('img/logo.png', false);

Template parts

Parts are reusable PHP fragments stored in layouts/parts/. Include them from any view, layout, or other part:

// Include a part
$this->part('header');

// Pass variables into a part
$this->part('entity-card', ['entity' => $agent, 'show_avatar' => true]);

Inside layouts/parts/entity-card.php, passed variables are available directly:

<div class="card">
    <?php if ($show_avatar): ?>
        <img src="<?php $this->asset('img/' . $entity->type . '-avatar.png'); ?>" alt="">
    <?php endif; ?>
    <h3><?php echo $entity->name; ?></h3>
</div>

Overriding parent theme views

Qualquer arquivo em views/, layouts/, layouts/parts/ ou assets/ pode ser sobrescrito colocando um arquivo com o mesmo caminho relativo no tema filho. O framework percorre a hierarquia de temas do filho para o pai e usa a primeira correspondência encontrada.

To override the default header:

1. Create src/themes/MyTheme/layouts/parts/header.php
2. The child theme's version is used automatically — no registration required.

Static Markdown pages

Páginas em layouts/pages/ são arquivos Markdown renderizados pelo framework. A URL é derivada do nome do arquivo:

O primeiro cabeçalho h1 do arquivo se torna o título da aba do navegador.

Variables available in views

Inside any view, layout, or part:

Check authentication state:

<?php if (!$app->user->is('guest')): ?>
    <p>Logged in as <?php echo $app->user->profile->name; ?></p>
<?php else: ?>
    <p>Not logged in.</p>
<?php endif; ?>

Layouts

Layouts wrap view content with the page shell (HTML, head, header, footer). Views use the default layout by default. Override per view:

<?php $this->layout = 'panel'; ?>

The minimum layout structure:

<html>
<head>
    <title><?php echo $this->getTitle(); ?></title>
    <?php mapasculturais_head(); ?>
</head>
<body>
    <?php body_header(); ?>
    <?php echo $TEMPLATE_CONTENT; ?>
    <?php body_footer(); ?>
</body>
</html>

RedeMapas-specific features

PWA support

Progressive Web App support is implemented in src/themes/RedeMapas/Pwa/. It enables installation as a home screen app on mobile devices. HTTPS is required (use the Caddy override in development).

WebPush notifications

Push notifications use the Web Push protocol with VAPID keys. Configure the keys via environment variables:

REDEMAPAS_VAPID_PUBLIC_KEY=<your-public-key>
REDEMAPAS_VAPID_PRIVATE_KEY=<your-private-key>

The push flow is implemented in:

• src/themes/RedeMapas/Push/ — subscription management and payload building
• src/themes/RedeMapas/Jobs/SendWebPushNotification.php — async job that dispatches pushes

Asset source vs. compiled output

For theme work, distinguish clearly between:

• assets-src/ — editable source files
• assets/ — compiled output served publicly

In practice, most UI changes should start in assets-src/ and be verified through the workspace build process instead of editing compiled files directly.

Subsite support

The RedeMapas theme supports multi-tenant deployments through subsites, where multiple independent installations share a single server. Subsite support is disabled in the default development configuration (DISABLE_SUBSITES=true).

Create a subsite via the interactive PHP shell:

$app = MapasCulturais\App::i();
$agent = $app->repo('Agent')->find(1);

$subsite = new \MapasCulturais\Entities\Subsite();
$subsite->name = 'My Subsite';
$subsite->url  = 'subsite.example.org';

$app->disableAccessControl();
$app->em->persist($subsite);
$app->em->flush();
$app->enableAccessControl();