Theming Part 3
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, andhtmlup to 512 KB in UTF-8 without NUL bytes (images and fonts use FTP). PHP is allowed only inlayout.php,templates/*.php, andpartials/*.php, checked for syntax errors with line numbers, and scanned by a lint that blocks program execution,eval,include/require(usepartial()instead), file/network/mail functions, superglobals, and disallowed CMS classes (allowing onlyContentRepository,MediaRepository,Url,Format,Slug,Seo, andTheme). -
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.jsonshow concise guidance. -
New Files, Overrides & Deletions: You can create approved new files (
layout.php,templates/NAME.php,partials/NAME.php, andassets/css/...cssorassets/js/...jsup 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.jsonfiles intouser/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.phpoutputs 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;noindexpages 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>andog:title(while legacy$metaDescriptionand$noindexstill work, and/sitemap.xml,/feed.xml, and/robots.txtare generated automatically). -
Tags, Search & Content URLs: Tags render via
partials/tags.phpand list on/tag/{slug}viatemplates/tag.php(10 items per page, newest first, returning 404 if a tag has no public items), while/search?q=usestemplates/search.php(never indexed) andpartials/search-form.php. Content URLs usepath(without a leading slash, such as/parent/child/grandchildfor book articles) viacontent_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.jsonis valid, the folder name is valid,parentis omitted or"base",requires.cmsis 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; damagedtheme.jsonstill 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 withe(), avoid printing sensitive/internal fields like$item['view_password_hash'],custom_css, orcustom_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.phpor hooks, no regions or blocks (dropped from the plan), no theme settings screen, and no child-of-child themes.