Theme System

Pragma CMS uses an isolated and granular theme system. Unlike other CMS platforms where a theme is just a stylesheet, a theme in Pragma is a complete, self-contained environment.

Theme Structure

A standard theme is organized with a strict hierarchy to keep logic and presentation separated:

TEXT

themes/
└── default-theme/
    ├── assets/             # /css, /js, /images, /fonts, /icons, /vendors
    ├── lang/               # /en.php, /fr.php (Theme-specific UI translations)
    ├── screenshots/        # Images used for the Admin preview
    ├── templates/          # Content views (e.g., home.php, article.php) and /components
    ├── functions.php       # Theme-specific PHP logic (Hooks, Custom helpers)
    └── theme.json          # The manifest file (Required)

Key Files Explained:

theme.json: The configuration manifest. It tells the CMS the theme's name, version, author, and description so it can be displayed and activated in the Administration panel.
functions.php: This file is automatically loaded when the theme is active. It is the perfect place to register custom Hooks, modify the Field Registry, or inject specific tracking scripts without touching the core.
templates/: This folder contains the specific views for your pages (e.g., home.php, blog/list.php). The CMS controllers automatically inject the output of these templates into the core system shell (cms-core/system/templates/base.php).

Assets Management

Pragma CMS optimizes resource loading through two parallel mechanisms:

Automatic Injection: The system automatically scans the theme's assets/css/ and assets/js/ folders. Every file found is globally injected into the public front-end.
Programmatic Enqueue (Hooks): For precise control (e.g., loading a library only on specific pages or injecting scripts into the Admin UI), use the Hook API in functions.php:

PHP

// Example: Injecting a vendor library into the public front-end
Hooks::addAction(Hook::ENQUEUE_CSS, function(object $page) {
    $page->cssFiles[] = getAssetsPath("vendors/font-awesome/all.min.css", isTheme: true);
});

Intelligent "Fallback" Logic

Pragma CMS uses a cascading fallback system to resolve templates. It searches for rendering files in this strict order of priority:

themes/[active-theme]/templates/ (The current global design).
sites/[site-handle]/templates/ (Site-specific overrides for multi-site setups).
extensions/[extension-name]/resources/templates/ (Extension-provided defaults).
cms-versions/[version]/system/templates/ (The ultimate system fallbacks).

This ensures you can always override a core template without modifying the original files.

Default Theme vs. Starter Kits

Default Theme: A minimalist "Blank Canvas" for developers starting from scratch.
Default Theme Custom: A duplicated, renamed version of the "Default Theme" where you can work safely without your code being overwritten during core updates.
Starter Kits: Pre-configured themes packaged with specific Content Types and Extensions (e.g., Blog Kit, Agency Kit) designed for specific use cases.