Template System Overview

Unfold CMS uses a powerful template system built on Laravel's Blade engine. Templates control the entire look and feel of your site — layouts, styles, homepage sections, ad zones, and menu locations. Templates are self-contained directories with configuration files that the CMS reads automatically.

How Templates Work

A template is a directory inside resources/views/templates/ that contains Blade views, configuration files, and static assets. The active template is set in Settings > Appearance or via the template.active_template configuration key.

Template Directory Structure

resources/views/templates/your-template/
│
├─ 📄 template.json                    Template metadata and declarations
│
├─ 📁 config/
│  ├─ 📄 options.json                  Customization options (colors, fonts, layout)
│  └─ 📄 pages.json                    Page definitions and section allow-lists
│
├─ 📁 layouts/
│  └─ 📄 app.blade.php                 Main layout
│
├─ 📄 home.blade.php                   Homepage
├─ 📄 post.blade.php                   Single blog post
├─ 📄 page.blade.php                   Static page
├─ 📄 blog.blade.php                   Blog listing
├─ 📄 category.blade.php               Category archive
├─ 📄 search.blade.php                 Search results
│
├─ 📁 sections/                        One folder per section type
│  ├─ 📁 hero/
│  │  ├─ 📄 section.json               Section schema (fields, settings, limits)
│  │  ├─ 📄 hero.blade.php             Section markup (receives $section)
│  │  └─ 📄 seed.json                  Demo content for installer
│  ├─ 📁 features/
│  │  └─ 📄 ...
│  └─ 📄 ...
│
├─ 📁 partials/                        Reusable components
│  ├─ 📄 header.blade.php
│  ├─ 📄 footer.blade.php
│  └─ 📄 sidebar.blade.php
│
├─ 📁 css/                             Template styles
├─ 📁 js/                              Template scripts
└─ 🖼️  screenshot.png                   Preview image for admin

template.json

Every template must include a template.json file. Only name and zones are required:

{
    "name": "Default Template",
    "version": "1.0.0",
    "author": "CMS Team",
    "description": "A clean, modern template with card-based layouts",
    "screenshot": "screenshot.png",
    "menu_locations": {
        "header": {
            "name": "Header Navigation",
            "description": "Main navigation links in the site header"
        },
        "footer": {
            "name": "Footer Navigation",
            "description": "Footer columns"
        }
    },
    "zones": {
        "header_leaderboard": {
            "name": "Header Leaderboard",
            "size": "728x90",
            "type": "banner"
        },
        "sidebar_top": {
            "name": "Sidebar Top",
            "size": "300x250",
            "type": "sidebar"
        }
    }
}

What's optional:

• menu_locations — If omitted, the CMS falls back to default header and footer locations. Your template still gets menus, just with the default location names.
• zones — Required by template validation. Use an empty object ("zones": {}) if your template doesn't display ads.

Template Options

Templates can expose customizable options through config/options.json. These options appear in the admin panel under template settings, allowing administrators to customize the template without editing code.

Common option types include:

• Colors — Brand colors, accent colors, background colors
• Typography — Font families, sizes, heading styles
• Layout — Sidebar position, content width, header style
• Features — Show/hide elements like search bar, social links

See the Template Development Guide for the complete options.json schema.

Page Sections

Templates declare section types as folders under sections/, and define which types each page allows in config/pages.json. Admins assemble sections on pages using the visual page builder at Admin > Pages. Placements are stored in the page_sections database table.

See Sections for the complete file structure, schema reference, and rendering guide.

Ad Zones

Templates declare advertising zones in template.json. These zones define where advertisements can be placed. When the template is activated, the CMS automatically creates or syncs the corresponding ad zone records in the database.

Zone Types

Common Zone Sizes

Switching Templates

To change the active template:

1. Go to Settings > Appearance in the admin panel
2. Select the desired template from the list
3. Save changes

When switching templates:

• Menu locations are re-mapped if the new template uses different location keys
• Ad zones are synced — new zones are created, orphaned zones are deactivated
• Section placements in page_sections are preserved per template — each template has its own set
• Template options reset to the new template's defaults

Child Templates

Unfold CMS supports a child template system for safe customization. A child template inherits from a parent template and can override specific files. This ensures your customizations survive template updates.

Create a child template by adding a parent key to template.json:

{
    "name": "My Custom Template",
    "parent": "default",
    "version": "1.0.0"
}

The child template only needs to contain the files you want to override. All other files fall through to the parent template.

For Developers

For a complete guide to building templates from scratch, including all configuration schemas, Blade directives, and helper functions, see the Template Development Guide.