Theming Part 2
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 likeid,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(prevandnextitems ornull). -
tag&search:taggives$tag,$items,$total,$page, and$pages;searchgives$q,$searched,$results,$total,$page, and$pages. -
private,error&404:privategives$itemand$error;errorgives$codeand$message;404adds 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 frompath(such as/parent/child/grandchildfor book articles—never fromslugalone) 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 (default21 Oct 2026) or outputsY-m-dfor<time datetime="...">.menu('name', $vars = [])&get_menu('name'): Renders a menu viapartials/menu-NAME.phporpartials/menu.php(skipping empty/unknown menus unlessrender_emptyistrue) or returns menu data directly.partial('name', $vars = []): Includespartials/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$thememetadata.
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, whileassets/css/templates/{template}.cssandassets/js/templates/{template}.jsload 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, andtxt(json,md, andhtmlcan 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 usestyle=""attributes rather than inline<style>blocks except the nonce-carrying per-item block.