🎨

Mastering XooPress Themes

From Basic Templates to Advanced Child Themes

XooPress adopts the WordPress-style theming system, making it instantly familiar to millions of developers and designers. Whether you're building your first theme or creating advanced child themes, this guide covers everything you need to know.

📁 Understanding Theme Structure

Every XooPress theme lives in the /themes/ directory. Here's what a complete theme looks like:

themes/my-theme/
├── style.css          # Theme metadata (required)
├── index.php          # Main template (required fallback)
├── header.php         # Header template part
├── footer.php         # Footer template part
├── sidebar.php        # Sidebar template part
├── functions.php      # Theme functions (loaded on every request)
├── screenshot.png     # Admin preview image (880x660 recommended)
├── theme.json         # Advanced configuration
├── assets/            # Static assets (CSS, JS, images)
│   ├── css/
│   │   └── main.css
│   ├── js/
│   │   └── main.js
│   └── images/
│       └── logo.svg
└── templates/         # Alternative template directory
    └── page-home.php

🎨 The Heart of Your Theme: style.css

The style.css file serves two purposes: it contains your theme's metadata AND your CSS styles. The header block follows the WordPress convention:

/*
Theme Name: My Awesome Theme
Theme URI: https://example.com/
Author: Your Name
Author URI: https://example.com/
Description: A modern, responsive theme for XooPress
Version: 1.0.0
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.html
Template: parent-theme-dir   /* For child themes only */
Tags: one-column, two-columns, right-sidebar, custom-header
Text Domain: my-theme
*/

/* Your CSS starts here */
:root {
    --primary-color: #4f46e5;
    --text-color: #1f2937;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    color: var(--text-color);
    line-height: 1.6;
}

💡 Pro Tip: Only Theme Name is required! All other fields are optional, but including them helps users understand your theme.

🖼️ Essential Template Files

header.php

<!DOCTYPE html>
<html <?= $htmlAttrs ?? 'lang="en"' ?>>
<head>
    <meta charset="<?= $charset ?? 'UTF-8' ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?= !empty($title) ? htmlspecialchars($title) . ' - ' : '' ?><?= htmlspecialchars($siteName ?? 'XooPress') ?></title>
    <link rel="stylesheet" href="<?= $theme->getStylesheetUrl() ?>">
    <?php if (!empty($head)) echo $head; ?>
</head>
<body>
    <header class="site-header">
        <div class="container">
            <h1><a href="<?= $homeUrl ?? '/' ?>"><?= htmlspecialchars($siteName ?? 'XooPress') ?></a></h1>
        </div>
    </header>
    <main class="site-content">
        <div class="container">

index.php

<?= $theme->getHeader() ?>

<div class="content-area">
    <?php if (!empty($posts)): ?>
        <?php foreach ($posts as $post): ?>
            <article class="post">
                <h2><a href="/posts/<?= $post['id'] ?>"><?= htmlspecialchars($post['title']) ?></a></h2>
                <div class="content">
                    <?= $post['rendered_content'] ?? $post['content'] ?>
                </div>
            </article>
        <?php endforeach; ?>
    <?php endif; ?>
</div>

<?= $theme->getFooter() ?>

footer.php

        </div><!-- .container -->
    </main>
    <footer>
        <p>&copy; <?= date('Y') ?> <?= htmlspecialchars($siteName ?? 'XooPress') ?></p>
    </footer>
</body>
</html>

🔧 Available Template Variables

When building themes, you have access to these variables in your templates:

Variable	Description
`$theme`	ThemeManager instance with helper methods
`$activeTheme`	Active (parent) theme data array
`$childTheme`	Child theme data array (or null)
`$posts`	Array of post records from the controller
`$post`	Single post record (on single post pages)
`$siteName`	Site name from database settings
`$siteDescription`	Site description from database settings

🧩 Template Parts System

XooPress provides a WordPress-like template part system for organizing reusable components:

<?php
// In any template file:
$theme->getHeader();                    // Includes header.php
$theme->getFooter();                    // Includes footer.php  
$theme->getSidebar();                   // Includes sidebar.php
$theme->getTemplatePart('nav', 'main'); // Includes nav-main.php
$theme->getTemplatePart('loop');        // Includes loop.php
?>

Template parts follow the child-parent hierarchy, searching in this order:

Child theme templates/ directory
Parent theme templates/ directory
Child theme root directory
Parent theme root directory

👶 Child Themes - The Smart Way to Customize

Child themes are the professional way to customize an existing theme without losing your changes when the parent theme updates.

✨ Why Use Child Themes?

Safe Updates — Update the parent theme without losing customizations
Minimal Files — Only include the files you want to override
Clean Separation — Keep custom code separate from the parent theme

Creating a Child Theme in 3 Steps

Step 1: Create a directory in /themes/

themes/my-child-theme/

Step 2: Add a style.css file with the Template: header pointing to the parent theme:

/*
Theme Name: My Child Theme
Theme URI: https://example.com/
Author: Your Name
Description: A child theme of XooPress Lite
Version: 1.0.0
Template: xoopress-lite
Text Domain: my-child
*/

⚠️ Important: The Template: header must exactly match the directory name of the parent theme (case-sensitive)!

Step 3: Activate your child theme at /admin/themes

What Gets Overridden?

Any file in the child theme with the same name as a parent theme file will override it:

themes/xoopress-lite/          # Parent theme
├── header.php                 # Default header
├── footer.php                 # Default footer
├── index.php                  # Default index
└── sidebar.php                # Default sidebar

themes/my-child/               # Child theme
├── style.css                  # Required
├── header.php                 # Overrides parent's header.php
└── custom-page.php            # New template (parent doesn't have)

In this example, only header.php is overridden. The footer, index, and sidebar come from the parent theme.

functions.php in Child Themes

Both parent and child functions.php files are loaded. The parent loads first, then the child:

// themes/my-child/functions.php
<?php
// This runs AFTER the parent theme's functions.php

// Add custom styles
$theme->addAsset('css', 'custom.css');

// Override parent settings
$theme->setSetting('layout', 'full-width');

💾 Theme Settings

Store per-theme settings in the database using simple key-value pairs:

<?php
// In your theme's functions.php or any template:
$theme->setSetting('layout', 'full-width');
$theme->setSetting('primary_color', '#4f46e5');
$theme->setSetting('sidebar_position', 'right');

// Retrieve settings with defaults
$layout = $theme->getSetting('layout', 'default');
$color = $theme->getSetting('primary_color', '#333');
?>

Settings are stored in the xp_theme_settings database table and persist across theme switches.

📦 Theme Management via Admin

The admin panel at /admin/themes provides complete theme management:

✓

Activate

Click "Activate" under any installed theme to apply it immediately to your public site.

📤

Upload

Upload a .zip file containing your theme. The system extracts it to /themes/ automatically.

🗑️

Delete

Delete inactive themes directly from the admin panel. (Active themes cannot be deleted.)

Theme ZIP Requirements

When uploading a theme, your ZIP file must follow this structure:

my-theme.zip
└── my-theme/                    # Must contain a directory
    ├── style.css                # Required - must have Theme Name
    ├── index.php                # Required - fallback template
    ├── header.php               # Optional
    ├── footer.php               # Optional
    ├── sidebar.php              # Optional
    ├── functions.php            # Optional
    ├── screenshot.png           # Optional - admin preview (880x660)
    ├── theme.json               # Optional - advanced config
    └── assets/                  # Optional - static assets
        ├── css/
        ├── js/
        └── images/

📊 Theme States

State	Description
● Active	Currently in use on the public site
● Inactive	Installed but not active

🎯 Real-World Examples

Example 1: Simple Blog Theme

themes/my-blog/
├── style.css
├── index.php
├── header.php
├── footer.php
└── single.php      # Custom single post view

Example 2: Child Theme Overriding Header Only

themes/custom-header/
├── style.css       (Template: xoopress-lite)
└── header.php      (Only this file is overridden)

Example 3: Complete Custom Theme

themes/premium-theme/
├── style.css
├── index.php
├── header.php
├── footer.php
├── sidebar.php
├── functions.php
├── theme.json
├── screenshot.png
├── assets/
│   ├── css/main.css
│   ├── js/main.js
│   └── images/logo.svg
└── templates/
    ├── page-home.php
    ├── page-about.php
    └── single-portfolio.php

🚀 Next Steps

📖 Read the Building Your First Module guide for backend development
🎨 Explore the Theme Manager to see available themes
🔧 Check out Site Settings to configure your site
📝 Create your first post using one of the 4 editor types

💡 Theme Development Tips:

Always include a fallback index.php — it's the ultimate safety net
Use $post['rendered_content'] ?? $post['content'] for backward compatibility
Test your theme with both XooPress Lite and XooPress Dark
Make your theme responsive — test on mobile devices
Include a screenshot.png (880x660) for better admin presentation

Happy theming with XooPress! 🎨 Whether you're building from scratch or creating child themes, the WordPress-style system makes it familiar and powerful.