Theming Part 3

Part 3 of 3 • Plain-English Theme Guide

Browser Editor, Menus, Site Features, Safety & Current Boundaries

The final part of the theme guide covers how you edit and manage theme files from the admin panel, how menus and site-wide settings connect to your theme, what safety rules protect your site when things go wrong, and what features are intentionally out of scope right now.

1. Editing, Creating, Overriding & Deleting Files Safely

You can edit child theme files right in the browser under Admin > Themes > Edit files, backed by strict server-side checks so mistakes don't silently overwrite work or break your site.

  • Strict Child-Theme Confinement: Only files inside user/themes/{child}/ can be edited—never Base, core CMS files, configs, logs, or backups. Paths allow only letters, digits, _, and - per segment, rejecting .., absolute paths, hidden files, and symlinks anywhere along the path (including the theme folder).
  • Allowed Types, Size & PHP Safety Lint: Editable text files include php, css, js, json, txt, md, and html up to 512 KB in UTF-8 without NUL bytes (images and fonts use FTP). PHP is allowed only in layout.php, templates/*.php, and partials/*.php, checked for syntax errors with line numbers, and scanned by a lint that blocks program execution, eval, include/require (use partial() instead), file/network/mail functions, superglobals, and disallowed CMS classes (allowing only ContentRepository, MediaRepository, Url, Format, Slug, Seo, and Theme).
  • Revisions, Conflict Checks & Live Warnings: Every save keeps a revision under user/backups/themes/{theme}/{file}.revisions/ (up to the newest 20) that you can inspect or restore. If a file changed on the server after you opened it (such as via FTP), saving is blocked while keeping your editor text intact, and editing live active-theme files prompts for confirmation.
  • Reference Panel & Snippets: Beside the editor, a Reference panel shows variables for that file type, helper functions, existing partials, and safe code snippets you can insert at the cursor (replacing any selection), while CSS, JS, and theme.json show concise guidance.
  • New Files, Overrides & Deletions: You can create approved new files (layout.php, templates/NAME.php, partials/NAME.php, and assets/css/...css or assets/js/...js up to two subfolders deep), copy a Base file into your child theme to override it (or delete your copy to revert), and delete non-theme.json files into user/backups/deleted/{theme}/ (newest 30 kept) with restoration available under Recently deleted—all within a 300-file theme limit.

2. Menus, Site Settings, SEO, Discovery & Per-Page Code

VoltCMS handles data rules, visibility filtering, and URLs behind the scenes so your theme focuses on presentation:

Menus & Custom Markup

Configure menus (such as main or footer) with page links or custom links and one level of sub-items in Admin > Menus. menu('name') renders partials/menu-NAME.php or partials/menu.php, while get_menu('name') returns structured items (label, url, type, active, in_trail, new_tab, external, rel, depth, and children).

Draft, private, trashed, or disabled items (and children of hidden items) are filtered out automatically, page links follow page IDs (including linking the chosen home page to /), and the default theme uses Bootstrap nav markup you can override.

Home Page & Global Display Settings

In Site settings, Home page can show latest articles or a chosen published, public page/article/book at / (301-redirecting its own path to /, setting canonical to /, listing once in the sitemap, setting $isHome, and falling back to latest articles if unpublished or private).

Site settings also control Items per page (5–50), Time zone and date format (used by format_date() and iso_date() from UTC storage), Footer text (supporting {year}, escaped), and Maintenance mode (returning 503 with templates/error.php and the site message for visitors while signed-in admins still see the normal site).

  • SEO, Sitemap, Feed & Robots: partials/meta.php outputs description, robots, canonical URL, Open Graph, Twitter tags, and feed links from $seo. Without a site URL, canonical, og:url, image tags, and feed links are omitted; noindex pages omit canonical and social tags; private pages omit SEO/social tags completely so link previews leak nothing; descriptions fall back from meta description to excerpt to site description; social images fall back to the site default; and an editor SEO title overrides <title> and og:title (while legacy $metaDescription and $noindex still work, and /sitemap.xml, /feed.xml, and /robots.txt are generated automatically).
  • Tags, Search & Content URLs: Tags render via partials/tags.php and list on /tag/{slug} via templates/tag.php (10 items per page, newest first, returning 404 if a tag has no public items), while /search?q= uses templates/search.php (never indexed) and partials/search-form.php. Content URLs use path (without a leading slash, such as /parent/child/grandchild for book articles) via content_url(), and old URLs after renames or moves redirect automatically.
  • Per-Page CSS & JavaScript: Instead of typing per-page code directly into content, create assets in Admin > Code and check them on needed pages/articles (served as cache-busted files in user/assets/, with pre-0.4.0 per-page code migrated automatically on update).

3. Activation Checks, Crash Recovery, Security & Current Limits

VoltCMS is designed to fail gracefully and keep theme behavior transparent—including being honest about what templates are a safety net rather than a sandbox, and what features are not part of the theme system.

  • Before Activation: A child theme activates only if theme.json is valid, the folder name is valid, parent is omitted or "base", requires.cms is met, listed assets exist in the theme or Base, every PHP file parses, there are no symlinks/hidden files/disallowed types, and the theme has at most 500 files with none over 2 MB (unused PHP files show as non-blocking warnings).
  • When Something Goes Wrong: Syntax or runtime errors in a child template/layout fall back to Base and log to user/logs/app.log; broken Base files fall back to a plain built-in page; missing/invalid active theme folders fall back to Base with a warning; damaged theme.json still lets templates render while pausing manifest assets; and you can click Switch back to Base anytime in Admin > Themes.
  • Security & API Stability: Theme PHP is trusted code (not a sandbox), so only install/edit trusted themes, protect admin accounts with 2FA, restrict write access to user/themes/, escape output with e(), avoid printing sensitive/internal fields like $item['view_password_hash'], custom_css, or custom_js, and rely on blocking of direct theme PHP access. Documented templates, partials, variables, and helpers form a stable public API with deprecation notices before removal.
  • What Themes Cannot Do Yet: There is no functions.php or hooks, no regions or blocks (dropped from the plan), no theme settings screen, and no child-of-child themes.