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)
│  └─ 📄 sections.json                 Homepage section definitions
│
├─ 📁 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/                        Homepage section partials
│  ├─ 📄 features.blade.php
│  ├─ 📄 testimonials.blade.php
│  └─ 📄 ...
│
├─ 📁 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.

Homepage Sections

Templates define homepage sections through config/sections.json. Each section is a content block that site administrators can populate through the admin panel. The default template includes 11 section types.

See Sections for the complete list and configuration details.

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 data is preserved in the database (sections are template-declared but data-independent)
• 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.