Variables y Helpers de Template
Los themes reciben sus datos como un conjunto plano de valores: el builder calcula todo (URLs, fechas, menús, design tokens, fragmentos renderizados) antes de que corra tu template, y luego te entrega los resultados como variables planas. Esta página enumera lo que está disponible y cómo funcionan los "helpers". (Para las variables y la sintaxis esenciales, la Template Reference cubre los casos base; esta página va más a fondo.)
Cómo funcionan los helpers en Chinaski
No hay funciones de template personalizadas que aprender: la sintaxis estándar de Template Toolkit es todo lo que hay ([% variable %], filtros como | html y | uri, IF/FOREACH/INCLUDE, etc.). Los "helpers" en la práctica son variables precalculadas: en lugar de pedirte formatear fechas o armar URLs en código de template, el builder las calcula y pasa la respuesta. Los gotchas conocidos se derivan de esto: no hay objetos tipo page.title (usa title), y las fechas llegan listas para usar (usa la variable precalculada date).
Las variables centrales (por tipo de contenido)
Las tablas de la Template Reference siguen siendo el contrato principal para page.tt/post.tt/blog_index.tt/search.tt: title, body (pre-renderizado, no escapar), slug, lang, canonical_url, nav_items, campos de imagen destacada, analytics IDs, password_hash, enlaces hreflang, breadcrumbs, etc. Esta página documenta todo lo demás que realmente se suministra.
Variables de nivel de site que recibe toda vista
site_name,site_tagline,footer_copyright,year,url_base: identidad y raíces de URL.blog_prefix,blog_url_base: el prefijo de ruta del blog en el idioma actual, y la dirección raíz del blog, preconstruidas.dir:'ltr'o'rtl'por idioma; úsalo en<html>para que los idiomas de derecha a izquierda funcionen.- Contactos del footer:
org_phone,org_email,org_linkedin,org_instagramde las configuraciones del site. footer_feed_url: la dirección del feed (vacía cuando el site no tiene posts publicados).- Variables del cookie notice: el texto del notice, el enlace de la política y las etiquetas de los botones, cada uno resolviendo a un override por idioma cuando existe.
noindex,airgap: booleanos planos; un theme puede cambiar el comportamiento (por ejemplo omitir scripts de share) cuando cualquiera es verdadero.- Variables PWA:
pwa_enabled,pwa_theme_color,pwa_short_name.
Navegación como lista y como árbol
nav_items: la lista plana por slot (label/url/slot/sort), incluidos los enlaces externos.nav_by_slotynav_tree_by_slot: los mismos elementos agrupados por slot ('header'/'footer'), y adicionalmente árboles padre/hijo preconstruidos para menús anidados: no armas el anidamiento tú mismo.
Fragmentos pre-renderizados
Algunos bloques de HTML se ensamblan antes de que corra tu template y te llegan ya renderizados:
sidebar_html: la salida del parcial de la sidebar (renderizada cuando tu theme provee_sidebar.tt; la configuración del theme puede apagar la sidebar).stacks_html: cada stack asignado a esta página/post, renderizado en orden.area_html: un mapa de nombre de área → blocks renderizados para themes que usan áreas de layout; renderiza el HTML de cada área en el punto de la template donde esa área corresponde.
Configuración y tokens
theme_config: un theme puede llevar sus propias configuraciones clave/valor (almacenadas en la base de datos junto con el theme) y leerlas en las templates.design_tokens: la lista de design tokens del site; la mayoría de los themes usan tokens vía el CSS generado, pero la lista se suministra para casos avanzados.custom_fields: los campos clave/valor personalizados de este registro.page_authors/post_authors: la lista de autores asignados.children(pages): las subpáginas bajo esta página, listas para listados o menús.default_site_image(+ una variante absoluta): la imagen de share de fallback del site;favicon_enabled,logo_file: el flag del pipeline de favicon y el archivo de logo configurado.- Variantes absolutas de imágenes: las variables de imagen destacada e imagen OG vienen con formas de URL absolutas ya resueltas, para que las tags sociales no construyan URLs por sí mismas.
Qué ocurre después de la salida de tu template
El HTML de tu template es terminado por el builder: los snippets se inyectan en el head/body donde esté configurado, y el resultado se minifica por defecto (una configuración puede desactivarlo) antes de escribirse a disco.
La idea del theme-config
Un theme puede definir sus propias configuraciones (theme_config): el builder las carga de la base de datos y las pasa a cada renderizado. Combinado con el directorio de theme con fallback por defecto (tu theme solo necesita las templates que cambia; los archivos faltantes hacen fallback a los integrados), tu theme se mantiene simple.
La versión corta
Variables de entrada = respuestas de salida: el builder hace el cálculo para que las templates se mantengan declarativas: nombres planos, valores correctos y localizados, sin código de formateo, sin funciones personalizadas. Si un valor que necesitas no está entre ellos (estado por visita, meta por registro), normalmente se alcanza vía custom_fields, design tokens, o las variables derivadas de las configuraciones del site listadas arriba.