The Theme Engine

templates/website/{Theme}/
├── theme.php     # the manifest: engine, meta, status, settings schema. Written by the author
├── config.php    # the saved setting VALUES. Written at runtime, never by hand
├── hooks.php     # the theme's listeners: variables, output filters, routing additions
├── cover.png     # the catalogue thumbnail meta['image'] points at
├── layouts/      # page shells a view extends: default, auth, checkout, invoice
├── partials/     # the pieces a layout assembles: header, footer, topbar, drawer, popup
├── components/   # markup two or more views share: plan grid, payment methods, panels
├── views/        # the surfaces, grouped by area: account/ auth/ checkout/ content/ page/ products/
├── tables/       # column presets for the client area list tables
├── assets/       # css, js, images, favicon the theme ships
├── locale/       # the theme's own wording, per language and per view scope
└── content/      # operator edits of that wording, written from the panel

public static function active(): self;                 // the installation's theme, falling back to Basic
public static function installed(): array;
public static function manifest(string $themeName): array;

public function getName(): string;
public function engine(): string;
public function exists(): bool;
public function dir(): string;                          // filesystem path, trailing separator
public function assetUrl(string $path = ''): string;    // address of a file under assets/
public function viewExists(string $view): bool;         // 'account/dashboard', no extension
public function render(string $view, array $data = []): string;
public function lang(string $key, array $vars = []): string;

public function settingsSchema(): array;                // theme.php → settings
public function savedConfig(): array;                   // config.php → the saved values
public function setting(string $key): mixed;            // saved value, else the schema default
public function allSettings(): array;                   // what the views receive as $setting
public function boot(): void;                            // includes hooks.php, once, before the first render

return [
    'engine' => 'smarty',
    'meta'   => [
        'name'    => 'Acme',
        'version' => '1.0.0',
        'author'  => 'Acme Ltd',
        'image'   => 'cover.png',
    ],
    'settings' => [
        'groups' => [
            'topbar' => ['label' => 'grp_topbar', 'icon' => 'bi-megaphone'],
        ],
        'fields' => [
            'topbar_enabled' => [
                'type'    => 'switch',
                'group'   => 'topbar',
                'label'   => 'set_topbar_enabled',   // a key in locale/{lang}.php
                'default' => false,
            ],
            'topbar_text' => [
                'type'      => 'textarea',
                'group'     => 'topbar',
                'label'     => 'set_topbar_text',
                'default'   => '',
                'rows'      => 3,
                'multilang' => true,
                // The row stays collapsed until the switch above is on.
                'depends'   => ['topbar_enabled' => true],
            ],
        ],
    ],
];

{if $setting.topbar_enabled}
    <div class="topbar">{$setting.topbar_text nofilter}</div>
{/if}

// ONE handler per theme: only the last registration's return value survives.
Hook::add("filter:template.variables", 1, function ($template, $data) {

    // Runs on every website page, so anything with a query goes through the cache.
    $data["footer_groups"] = Cache::remember('website', 'acme_footer_' . Language::selected(), 3600,
        fn (): array => Products::groups());

    return $data;   // returning nothing drops every key the platform collected
});

// Markup, not data: the layout's hook points take a string and print it as-is.
Hook::add("ui:client.head.css", 1, fn () => '<link rel="stylesheet" href="' . Theme::active()->assetUrl('css/extra.css') . '">');