Back to Main Site

Building a Custom Theme for PolyCMS on RISE CRM

Last updated on Nov 22, 2026 11:35 AM 11:35 AM 2,053.82 ms

PolyCMS themes live in plugins/polycms/themes/{slug}/ and control every aspect of your public RISE CRM website and blog presentation using a WordPress-inspired template hierarchy with child theme support, dynamic Theme Options, and full MTBuilder visual page builder compatibility. This guide provides a complete, working theme scaffold that activates cleanly at Appearance > Themes and configures without code at Appearance > Theme Options.

Theme Directory Structure

Place every custom theme inside plugins/polycms/themes/. Only style.css and index.php are strictly required for validation, while specialized templates let you customize individual views:

plugins/polycms/themes/
\-- my-theme/
    |-- style.css            # Theme manifest header (required)
    |-- index.php            # Final fallback template (required)
    |-- header.php           # Shared site header
    |-- footer.php           # Shared site footer
    |-- single.php           # Single post view
    |-- page.php             # Standard static page view
    |-- page-landing.php     # Full-width landing template for MTBuilder
    |-- category.php         # Category archive view
    |-- tag.php              # Tag archive view
    |-- author.php           # Author archive view
    |-- archive.php          # Generic archive fallback
    |-- search.php           # Search results view
    |-- 404.php              # Not found view
    |-- functions.php        # Theme hooks and helper functions (optional)
    |-- theme-options.php    # Declarative Theme Options schema (optional)
    |-- screenshot.png       # Admin preview card image (optional)
    |-- partials/            # Reusable template parts
    |-- assets/
    |   |-- css/theme.css
    |   |-- js/theme.js
    |   \-- images/
    \-- languages/
        \-- english/
            \-- mytheme_lang.php

Template Hierarchy and Child Theme Fallback

When rendering a public route, Libraries/Blog_theme_loader.php resolves templates in strict specificity order: active (child) theme -> parent theme (if Template: is set in style.css) -> core plugin fallback (plugins/polycms/Views/frontend/).

Single Post:    single-{post_slug}.php -> single.php -> archive.php -> index.php
Static Page:    {page_template}.php -> page.php -> index.php
Category:       category-{category_slug}.php -> category.php -> archive.php -> index.php
Tag:            tag-{tag_slug}.php -> tag.php -> archive.php -> index.php
Author:         author.php -> archive.php -> index.php
Search:         search.php -> archive.php -> index.php
Homepage:       home.php -> index.php
404 Page:       404.php -> Views/frontend/404.php

Creating a Child Theme

To customize the bundled head-random theme safely without editing its files, add Template: head-random to your child theme's style.css. PolyCMS loads the parent theme's functions.php first, then your child theme's functions.php, and resolves any missing template files or partials from the parent automatically.

MTBuilder Compatibility in Your Theme Scaffold

To ensure MTBuilder preset layouts, Template Parts, and custom blocks render edge-to-edge without styling conflicts, follow four design rules:

  1. Provide a full-width landing template (page-landing.php) without forced sidebars or narrow fixed containers.
  2. Apply content filters via polycms_apply_filters('polycms_post_content', $content, $page) so MTBuilder shortcodes and responsive grid wrappers render properly.
  3. Fire frontend head and footer hooks (polycms_do_action('polycms_head'), polycms_do_action('polycms_footer'), and polycms_do_action('polycms_footer_scripts')) so MTBuilder and active sub-plugins load mtbuilder-frontend.css and scripts.
  4. Scope global CSS carefully: Avoid aggressive global resets on a, button, h1-h6, .row, or .col-* that could override block-level spacing or button contrast.

Example Full-Width MTBuilder Template (page-landing.php)

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main landing-main">
    <?php
    if (isset($page) && is_object($page)) {
        echo polycms_apply_filters('polycms_post_content', $page->content, $page);
    }
    ?>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Step 1: Create style.css (Theme Manifest)

PolyCMS reads the CSS comment block at the top of style.css to display your theme in Appearance > Themes.

/*
Theme Name: My Custom Theme
Theme URI: https://your-website.com/my-theme
Description: A fast, responsive Bootstrap 5 theme for PolyCMS on RISE CRM.
Version: 1.0.0
Author: Your Name
Author URI: https://your-website.com
Text Domain: my-theme
Requires PolyCMS: 1.3.0
Requires PHP: 8.1
License: Commercial
*/

/* Base rules can live here or inside assets/css/theme.css */

Step 2: Create header.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<!DOCTYPE html>
<html lang="<?php echo esc_attr((string) polycms_get_option('active_language', 'en')); ?>">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <?php
    if (!empty($seo_meta_tags)) {
        echo $seo_meta_tags;
    } elseif (!empty($title)) {
        echo '<title>' . html_escape($title) . '</title>' . "\n";
    }
    if (!empty($og_tags)) {
        echo $og_tags;
    }
    if (!empty($twitter_tags)) {
        echo $twitter_tags;
    }
    ?>

    <link rel="stylesheet" href="<?php echo esc_attr(polycms_theme_url('my-theme', 'assets/css/theme.css')); ?>">

    <?php polycms_do_action('polycms_head'); ?>
</head>
<body class="<?php echo esc_attr(polycms_body_class()); ?>">
<?php
polycms_do_action('polycms_body_start');

if (function_exists('polycms_render_admin_bar')) {
    polycms_render_admin_bar();
}
?>

<header class="site-header">
    <div class="container d-flex align-items-center justify-content-between py-3">
        <a href="<?php echo esc_attr(polycms_get_blog_url()); ?>" class="site-logo fw-bold text-decoration-none">
            <?php echo html_escape((string) polycms_get_theme_option('blog_title', polycms_get_option('companyname', 'RISE CRM'))); ?>
        </a>
        <?php polycms_render_menu('main'); ?>
    </div>
</header>

Step 3: Create footer.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>

<footer class="site-footer py-4 mt-5 border-top">
    <div class="container">
        <div class="footer-widgets mb-3">
            <?php polycms_render_widget_area('footer'); ?>
        </div>
        <p class="mb-0 text-muted">
            &copy; <?php echo date('Y'); ?> <?php echo html_escape((string) polycms_get_option('companyname', 'RISE CRM')); ?>. All rights reserved.
        </p>
    </div>
</footer>

<script src="<?php echo esc_attr(polycms_theme_url('my-theme', 'assets/js/theme.js')); ?>"></script>
<?php
polycms_do_action('polycms_footer');
polycms_do_action('polycms_footer_scripts');
?>
</body>
</html>

Step 4: Create index.php (Fallback Post Loop)

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <h1 class="mb-4"><?php echo html_escape($title ?? 'Blog'); ?></h1>

        <?php if (!empty($posts)): ?>
            <div class="row g-4">
                <?php foreach ($posts as $post): ?>
                    <div class="col-md-6">
                        <article class="card h-100">
                            <?php if (!empty($post->feature_image)): ?>
                                <img src="<?php echo esc_attr(base_url('files/' . ltrim($post->feature_image, '/'))); ?>"
                                     alt="<?php echo esc_attr($post->title); ?>"
                                     class="card-img-top" loading="lazy">
                            <?php endif; ?>
                            <div class="card-body">
                                <h2 class="h5 card-title">
                                    <a href="<?php echo esc_attr(polycms_get_post_permalink($post)); ?>">
                                        <?php echo html_escape($post->title); ?>
                                    </a>
                                </h2>
                                <div class="text-muted small mb-2">
                                    <time datetime="<?php echo esc_attr($post->published_at ?? ''); ?>">
                                        <?php echo html_escape(polycms_format_date($post->published_at ?? '')); ?>
                                    </time>
                                </div>
                                <p class="card-text"><?php echo html_escape(polycms_get_post_excerpt($post, 150)); ?></p>
                            </div>
                        </article>
                    </div>
                <?php endforeach; ?>
            </div>

            <?php if (!empty($pagination)): ?>
                <div class="mt-4"><?php echo $pagination; ?></div>
            <?php endif; ?>
        <?php else: ?>
            <p>No posts found.</p>
        <?php endif; ?>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Step 5: Create single.php and category.php

single.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <div class="row g-4">
            <div class="col-lg-8">
                <article class="single-post">
                    <header class="mb-4">
                        <h1><?php echo html_escape($post->title); ?></h1>
                        <div class="text-muted small">
                            <span><?php echo html_escape(trim(($post->firstname ?? '') . ' ' . ($post->lastname ?? ''))); ?></span>
                            | <time datetime="<?php echo esc_attr($post->published_at ?? ''); ?>">
                                <?php echo html_escape(polycms_format_date($post->published_at ?? '')); ?>
                            </time>
                        </div>
                    </header>

                    <?php if (!empty($post->feature_image)): ?>
                        <div class="mb-4">
                            <img src="<?php echo esc_attr(base_url('files/' . ltrim($post->feature_image, '/'))); ?>"
                                 alt="<?php echo esc_attr($post->title); ?>" class="img-fluid rounded">
                        </div>
                    <?php endif; ?>

                    <div class="post-content">
                        <?php echo polycms_apply_filters('polycms_post_content', $post->content, $post); ?>
                    </div>

                    <?php if (!empty($post->tags)): ?>
                        <div class="post-tags mt-4">
                            <?php foreach ($post->tags as $tag): ?>
                                <a href="<?php echo esc_attr(polycms_get_tag_url($tag)); ?>" class="badge bg-light text-dark text-decoration-none me-1">
                                    #<?php echo html_escape($tag->name); ?>
                                </a>
                            <?php endforeach; ?>
                        </div>
                    <?php endif; ?>
                </article>

                <?php
                if (isset($blog_theme_loader)) {
                    $blog_theme_loader->get_template_part('comments', null, ['post' => $post]);
                }
                ?>
            </div>

            <aside class="col-lg-4">
                <?php polycms_render_widget_area('sidebar'); ?>
            </aside>
        </div>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

category.php

<?php defined('BASEPATH') or exit('No direct script access allowed'); ?>
<?php include __DIR__ . '/header.php'; ?>

<main class="site-main py-5">
    <div class="container">
        <header class="mb-4">
            <h1>Category: <?php echo html_escape($category->name); ?></h1>
            <?php if (!empty($category->description)): ?>
                <p class="text-muted"><?php echo html_escape($category->description); ?></p>
            <?php endif; ?>
        </header>

        <?php if (!empty($posts)): ?>
            <div class="row g-4">
                <?php foreach ($posts as $post): ?>
                    <div class="col-md-6">
                        <article class="card h-100 p-3">
                            <h2 class="h5">
                                <a href="<?php echo esc_attr(polycms_get_post_permalink($post)); ?>">
                                    <?php echo html_escape($post->title); ?>
                                </a>
                            </h2>
                            <p class="mb-0"><?php echo html_escape(polycms_get_post_excerpt($post, 150)); ?></p>
                        </article>
                    </div>
                <?php endforeach; ?>
            </div>
            <?php if (!empty($pagination)) { echo '<div class="mt-4">' . $pagination . '</div>'; } ?>
        <?php else: ?>
            <p>No posts found in this category.</p>
        <?php endif; ?>
    </div>
</main>

<?php include __DIR__ . '/footer.php'; ?>

Step 6: Declare Theme Options (theme-options.php)

To expose visual customization controls at Appearance > Theme Options, return an associative schema array from theme-options.php at your theme root. Supported field types include text, textarea, number, select, checkbox, color, image, and repeater.

<?php
defined('BASEPATH') or exit('No direct script access allowed');

return [
    'blog_title' => [
        'type'        => 'text',
        'group'       => 'Branding',
        'label'       => 'Blog Title',
        'description' => 'Displayed in the site header.',
        'default'     => 'Company Blog',
    ],
    'primary_color' => [
        'type'    => 'color',
        'group'   => 'Appearance',
        'label'   => 'Primary Brand Color',
        'default' => '#3b82f6',
    ],
    'posts_per_row' => [
        'type'    => 'select',
        'group'   => 'Layout',
        'label'   => 'Posts Per Row',
        'default' => '2',
        'options' => [
            '1' => '1 Column',
            '2' => '2 Columns',
            '3' => '3 Columns',
        ],
    ],
    'show_sidebar' => [
        'type'    => 'checkbox',
        'group'   => 'Layout',
        'label'   => 'Show Sidebar on Single Posts',
        'default' => '1',
    ],
];

Read saved option values anywhere in your templates with polycms_get_theme_option('primary_color', '#3b82f6').

Mixing Theme Template Parts with MTBuilder Template Parts

Keep layout responsibilities cleanly separated:

  1. Theme template parts (partials/ loaded via polycms_get_template_part()) should render stable global chrome such as headers, legal footers, and breadcrumbs.
  2. MTBuilder Template Parts should power marketing sections such as hero variants, pricing grids, testimonials, and campaign calls-to-action that editors swap frequently without deploying code.

Activation and Preview in RISE CRM

  1. Place your theme folder inside plugins/polycms/themes/my-theme/ (or upload a ZIP via Appearance > Themes).
  2. Navigate to Appearance > Themes in RISE CRM.
  3. Click Preview to inspect the theme in a staff-only session without impacting public visitors, then click Activate when ready.
  4. Customize colors, logos, and layout settings at Appearance > Theme Options.

Best Practices

  1. Always call polycms_do_action('polycms_head') and polycms_do_action('polycms_footer'): Bundled plugins like Google Analytics, Banner Slider, MTOptimize, and MTBuilder rely on these hooks.
  2. Escape all dynamic output: Use html_escape() for text nodes and esc_attr() for HTML attributes.
  3. Pass post and page HTML through polycms_apply_filters('polycms_post_content', ...): Ensures internal link resolution, shortcodes, and MTBuilder layouts execute properly.
  4. Call polycms_render_admin_bar(): Gives logged-in RISE staff instant frontend shortcuts to edit content and clear page cache.
  5. Test responsive breakpoints: Verify Bootstrap 5 layout grids and menus across mobile, tablet, and desktop viewports.

Need Help Building Your Theme?

If you need assistance structuring a custom theme, configuring Theme Options, or building a child theme for head-random, leave a comment on our CodeCanyon portfolio page. Free developer support is included for all PolyCMS customers.

Related Documentation