Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.
L1–L2
Unit 02 · Records in templates
Documenting a template's inputs
Records in templatesPage 17 of 35Updated
A template that expects variables is an interface, and its markup does not say what the interface is. The header comment convention in both engines, what to record (each variable, its type, whether it is required, the layout areas a component reads), and the comment syntax that breaks a page.
Who this is for. The theme developer writing an include, a component or a page template that another developer will call or change. Afterwards every template you write states its contract in its first lines, and the next person can use it without reading every line below.
A template is an interface
An include reads variables its caller must set, a component reads layout areas the layout in the admin must define, and a page template reads a record of one particular type. None of that is visible from outside: a caller who forgets a variable gets an empty block or, in Smarty, an error several includes deep. The header comment is the only place the contract can live.
The header comment
Start every include and component with a comment that lists what it reads, one line each: the name, the type, whether it is required, and the default when it is not. For a component, list the layout areas it reads and their input types, because someone has to create them on the layout in the admin.
Template codecomponents/post-card.html
{*
Card for one blog post. Used by blogs/posts/index.html and the related-posts component.
Parameters
post Post required the post to show
size string optional 'small' or 'large'; default 'small'
showDate bool optional default true
Sets for the caller
_templateContext 'deferredScripts' adds /dist/cards.js
*}
{$size = $size|default:'small'}
{$showDate = $showDate|default:true}
{#
Card for one blog post. Used by blogs/posts/index.html and the related-posts component.
Parameters
post Post required the post to show
size string optional 'small' or 'large'; default 'small'
showDate bool optional default true
Sets for the caller
_templateContext 'deferredScripts' adds /dist/cards.js
#}
{% set size = size|default('small') %}
{% set showDate = showDate ?? true %}
A component's header lists layout areas instead of parameters, with the input type each must have:
Template codecomponents/callout.html
{*
Callout: a tip, warning or note inside a page.
Areas (create them on the component's layout)
tone Select: tip | warning | info default info
heading Text optional
body Richtext required
*}
{#
Callout: a tip, warning or note inside a page.
Areas (create them on the component's layout)
tone Select: tip | warning | info default info
heading Text optional
body Richtext required
#}
Apply the defaults right below the comment, as in the first example, so the documented default and the real one cannot drift apart. Keep the comment next to the code, and change both in the same commit.
This documentation site follows the convention in every component and layout template: each lists its layout areas and input types in its header, and those headers are what an administrator works from when creating the layouts.
Comment syntax that breaks a page
Smarty comments do not nest. The first closing delimiter, a star followed by a closing brace, ends the comment wherever it appears. Writing it inside a comment, for example in an example of a comment, ends the comment early and prints the rest onto every page.
Twig's closing delimiter, a hash followed by a closing brace, does the same inside a Twig comment.
An HTML comment is not a template comment.<!-- --> is sent to every visitor, and the template code inside it still runs. Document templates with the engine's comment, which is removed when the template is compiled.