Variables & Helpers

Themes receive their data as one flat set of values: the builder computes everything (URLs, dates, menus, design tokens, rendered fragments) before your template runs, then hands you the results as plain variables. This page lists what’s available and how the “helpers” work. (For the essential variables and syntax, the Template Reference covers the base cases; this page goes deeper.)

How helpers work in Chinaski

There are no custom template functions to learn: the standard Template Toolkit syntax is all there is ([% variable %], filters like | html and | uri, IF/FOREACH/INCLUDE, etc.). The “helpers” in practice are pre-computed variables: rather than asking you to format dates or assemble URLs in template code, the builder computes them and passes the answer. The known gotchas follow from this: there are no page.title-style objects (use title), and dates arrive ready-made (use the pre-computed date variable).

The core variables (per content type)

The Template Reference’s tables remain the primary contract for page.tt/post.tt/blog_index.tt/search.tt; title, body (pre-rendered, don’t escape), slug, lang, canonical_url, nav_items, featured image fields, analytics IDs, password_hash, hreflang links, breadcrumbs, and so on. This page documents everything else actually supplied.

Site-level variables every view gets

site_name, site_tagline, footer_copyright, year, url_base: identity and URL roots.
blog_prefix, blog_url_base: the blog path prefix in the current language, and the blog’s root address, pre-built.
dir: 'ltr' or 'rtl' per language; use it on <html> so right-to-left languages work.
Footer contacts: org_phone, org_email, org_linkedin, org_instagram from the site’s settings.
footer_feed_url: the feed address (empty when the site has no published posts).
Cookie-notice variables: the notice text, policy link, and button labels, each resolving to a per-language override when one exists.
noindex, airgap: plain booleans; a theme can change behavior (e.g. skip share scripts) when either is true.
PWA variables: pwa_enabled, pwa_theme_color, pwa_short_name.

nav_items: the flat per-slot list (label/url/slot/sort), including external links.
nav_by_slot and nav_tree_by_slot: the same items grouped by slot (‘header’/‘footer’), and additionally pre-built parent/child trees for nested menus; you don’t assemble nesting yourself.

Pre-rendered fragments

Some blocks of HTML are assembled before your template runs and reach you already rendered:

sidebar_html: the sidebar partial’s output (rendered when your theme provides _sidebar.tt; the theme config can turn the sidebar off).
stacks_html: every stack assigned to this page/post, rendered in order.
area_html: a map of area name → rendered blocks for themes that use layout areas; render each area’s HTML at the point in the template where that area belongs.

Configuration and tokens

theme_config: a theme can carry its own key/value settings (stored in the database with the theme) and read them in templates.
design_tokens: the site’s design-token list; most themes use tokens via the generated CSS, but the list is supplied for advanced cases.
custom_fields: this record’s custom key/value fields.
page_authors / post_authors: the assigned author list.
children (pages): the sub-pages under this page, ready for listing or menus.
default_site_image (+ an absolute variant): the site’s fallback share image; favicon_enabled, logo_file: the favicon pipeline flag and configured logo file.
Absolute image variants: the featured image and OG image variables come with abs-URL forms already resolved, so social tags don’t build URLs themselves.

What happens after your template output

Your template’s HTML is finished by the builder: snippets are injected into the head/body where configured, and the result is minified by default (a setting can turn that off) before being written to disk.

The theme-config idea

A theme can define its own settings (theme_config): the builder loads them from the database and passes them to every rendering. Combined with the default-fallback theme directory (your theme only needs the templates it changes; missing files fall back to the built-in ones), your theme stays simple.

The short version

Variables in = answers out: the builder does the computing so templates stay declarative; flat names, correct-and-localized values, no formatting code, no custom functions. If a value you need isn’t among them (per-visit state, per-record meta), it’s usually reachable via custom_fields, design tokens, or the site’s settings-derived variables listed above.