PolyCMS Theme Management

Last updated on Jul 10, 2026 4:16 AM

Theme System Overview

Themes control the entire frontend appearance and layout of your PolyCMS blog. Navigate to Blog > Themes to manage installed themes.

Theme Listing

The Themes page displays all installed themes in a grid layout:

Theme name, version, and author
Theme description
Active/Inactive status indicator
Activate/Deactivate toggle
Theme Options link (for the active theme)

Installing a Theme

ZIP Upload

Navigate to Blog > Themes.
Click Upload Theme.
Select a .zip file containing the theme package.
The system validates the ZIP contents, scans for security threats, and extracts the theme to modules/polycms/themes/.
After installation, click Activate to enable the theme.

Manual Installation

Upload the theme folder directly to modules/polycms/themes/ via FTP or file manager.

Theme Security

When uploading themes via ZIP, PolyCMS performs security scanning:

Strips potentially dangerous PHP functions
Validates file extensions within the archive
Uses polycms_validate_file_path to prevent directory traversal attacks

Theme Options

Active themes can register a Theme Options settings panel accessible from the Themes page. Theme Options allow administrators to configure:

Site logo and favicon
Color schemes and layout preferences
Header and footer settings
Social media links
Custom CSS injection

Theme developers define available options using the Theme Options API. See Building a Custom Theme for implementation details.

Bundled Theme: Head Random

PolyCMS ships with the Head Random theme, providing:

Modern, responsive layout built with Bootstrap 5
Dark header with logo and search integration
Mobile-friendly hamburger navigation
Sidebar with widget support
SEO-optimized markup
Clean post and page templates

For detailed configuration, see Theme: Head Random.

Theme Preview Mode

Safely experiment with your site's design using Theme Preview Mode.

Staff members can click Preview on any installed theme to see how it looks on the frontend.
The preview is session-based and only visible to the staff member who initiated it.
Visitors to the site will continue to see the live, active theme.
A notification bar appears during preview mode with a button to exit the preview.

Child Themes

PolyCMS supports Child Themes, allowing developers to safely extend or override parent themes without losing modifications during theme updates.

To create a child theme:

Create a new theme directory (e.g., head-random-child).
Create a style.css file and include the Template header pointing to the parent theme slug:

   /*
   Theme Name: Head Random Child
   Template: head-random
   */

PolyCMS will automatically cascade template resolution: checking the child theme first, then falling back to the parent theme.

Template Hierarchy

Themes follow a standard template hierarchy. PolyCMS looks for template files in this order:

single.php      → Individual post view
category.php    → Category archive
tag.php         → Tag archive
page.php        → Static page
archive.php     → Date-based archives
search.php      → Search results
index.php       → Fallback for all views

Themes can also provide custom page templates (e.g., page-contact.php) that become selectable in the page editor.