Theming Part 2

Part 2 of 3 • Plain-English Theme Guide

Variables, Helper Functions, Partials & Assets

Once VoltCMS picks a template and layout, it hands your theme clean data and helper functions so you can build pages without wrestling with complex framework internals. Let's break down what variables you get, what helpers you can call, how partials work, and how stylesheets and scripts load.

1. Variables Handed to Layouts, Templates & Partials

Every layout, template, and partial receives shared context variables, and a partial can add or override variables when called via partial('name', [...]).

Shared Variable What It Gives You (in Plain Terms)
$site Site settings from Admin > Site settings: name, lang, url (public URL or ''), description, footer (footer text or ''), logo (URL or ''), logo_alt, and social_image (URL or '').
$title & $metaDescription The page title (without the site name) and meta description text ('' if none).
$noindex & $seo $noindex flags non-indexed pages (prefer $seo['robots']). $seo holds plain-text SEO data (escape when printing) printed by meta.php: title, description, canonical, robots, og, twitter, and feed.
$isHome true when rendering the home address (either the latest articles list or the page chosen as home page in Site settings, in which case $item and $body are populated like a content page).
$tags & $preview $tags lists tags (name, slug) for pages/articles (empty on private or list pages); $preview is true inside the admin preview.
$itemAssets & $nonce $itemAssets (css and js URL lists linked to the item in Admin > Code, printed by item-css.php and item-js.php). $nonce is the per-request Content Security Policy nonce for your own inline <style>/<script> blocks.
$customCss & $customJs Deprecated since 0.4.0 and always '' (kept only so older themes don't break; per-item code now uses $itemAssets).
$template, $theme & $content Active template name (such as article or page-about), active theme info array (name, title, version, author, is_child), and $content (in layout.php only: the rendered template HTML).

Extra Variables for Specific Templates

Depending on which template renders, VoltCMS adds extra variables tailored to that screen:

  • home: Adds $articles (id, slug, title, excerpt, published_at), $page, and $pages.
  • page, article, book, content: Adds $item (content fields like id, type, parent_id, slug, title, status, visibility, excerpt, meta_description, noindex, published_at, created_at, updated_at—skip internal fields) and $body (already sanitised HTML, printed raw).
  • book: Also provides $crumbs (public ancestors, root first), $children (ordered public child pages), and $neighbors (prev and next items or null).
  • tag & search: tag gives $tag, $items, $total, $page, and $pages; search gives $q, $searched, $results, $total, $page, and $pages.
  • private, error & 404: private gives $item and $error; error gives $code and $message; 404 adds no extra variables.

2. Helper Functions You Can Call in Themes

Small helper functions keep your theme markup clean, safe, and aware of subfolder installs, time zones, and nested page paths:

Escaping, URLs & Forms

  • e($text): HTML-escapes text—use it on everything except already-sanitised $body.
  • url('/path'): Builds a site URL that works even in a subfolder install.
  • content_url($row) & tag_url($tag): Builds content links from path (such as /parent/child/grandchild for book articles—never from slug alone) and tag links as /tag/{slug}.
  • csrf_field(): Outputs a hidden CSRF input for forms (such as the private-page form).

Dates, Menus, Partials & Assets

  • format_date($utc, $format = null) & iso_date($utc): Formats stored UTC dates using Site settings' time zone and format (default 21 Oct 2026) or outputs Y-m-d for <time datetime="...">.
  • menu('name', $vars = []) & get_menu('name'): Renders a menu via partials/menu-NAME.php or partials/menu.php (skipping empty/unknown menus unless render_empty is true) or returns menu data directly.
  • partial('name', $vars = []): Includes partials/name.php (child first, then Base).
  • get_theme_url('css/x.css'), theme_head_assets(), theme_footer_assets() & theme_info(): Resolve asset URLs (or the theme's asset directory when called empty), render CSS/JS tags, and return $theme metadata.

3. Base Partials & How Assets Load

Base ships ready-made partials—meta, vendor-css, vendor-js, item-css, item-js, preview-banner, header, footer, pagination (page, pages, base, optional query), breadcrumbs, book-nav, tags, and search-form—so you can override just one piece instead of rewriting everything. For example, overriding vendor-css.php lets you swap or self-host Bootstrap CSS, while keeping item-css.php and item-js.php ensures linked per-item code loads.

  • Global vs. Template Assets: Files listed in theme.json (Base first, then child) load on every page, while assets/css/templates/{template}.css and assets/js/templates/{template}.js load automatically only when that template is used.
  • Overrides & Caching: Putting a file at the same path in the child theme overrides Base; child assets link as /user/themes/{name}/assets/...?v={file time} and Base assets serve from /assets/base/...?v={CMS version} with a one-year cache tied to version/file changes.
  • Allowed Types & CSP Rules: Supported asset extensions include css, js, png, jpg, jpeg, gif, webp, svg, ico, woff, woff2, and txt (json, md, and html can exist in the theme but aren't served by the Base route). Scripts must be files (inline <script> and inline event handlers are blocked by CSP), and styles should use style="" attributes rather than inline <style> blocks except the nonce-carrying per-item block.