06-templating.md
Templating
Output a Mason field with its tag. Everything is pre-rendered to safe HTML.
Full render
{mason_field}
Renders the whole document — rich text and every enabled brick — as HTML. Disabled bricks are skipped, and the field's editor mode is respected.
Looping bricks
Iterate the bricks yourself for full control over the markup:
{mason_field}
{bricks}
{if brick_type == "callout"}
<div class="callout {brick:tone}">{brick:heading}</div>
{if:elseif brick_type == "quote"}
<blockquote>{brick:quote} — {brick:cite}</blockquote>
{/if}
{/bricks}
{/mason_field}
Inside {bricks}:
{brick_type}— the brick's short name.{brick:short_name}— a field's value.{if brick_type == "..."}— conditionals on the brick type.
Sub-values
Some kinds expose extra tokens:
- Link —
{brick:short_name:url},{brick:short_name:text},{brick:short_name:target} - File —
{brick:short_name:url},{brick:short_name:title} - Entry —
{brick:short_name:id},{brick:short_name:title},{brick:short_name:url_title}, plus every custom field on the related entry by its short name:{brick:short_name:field}(files resolve to a URL). For a multi-pick relationship, loop it —{brick:short_name}…{/brick:short_name}— and the same per-entry tokens resolve per row.
Grid rows
Loop a grid by its short name; each column's short name resolves per row:
{brick:items}
<li>{brick:list_item}{if done} ✓{/if}</li>
{/brick:items}
{brick:items:count} gives the number of rows.
Listing (channel query)
A Listing field loops live channel entries — same syntax as a grid. Each row exposes id, title, url_title, url (built from the field's Link prefix), a formatted date, and every custom field on the entry by its short name (files resolve to a URL):
<div class="grid">
{brick:projects}
<a href="{brick:url}" class="card">
{if project_cover}<img src="{brick:project_cover}" alt="{brick:title}">{/if}
<h3>{brick:title}</h3>
<time>{brick:date}</time>
{if project_excerpt}<p>{brick:project_excerpt}</p>{/if}
</a>
{/brick:projects}
</div>
{brick:projects:count} gives the number of entries returned. (Here projects is the Listing field's short name; project_cover / project_excerpt are custom fields on the listed channel.)
Braces in authored content
EE's template parser reads the output a fieldtype returns, so a literal { typed into a Mason field would otherwise be treated as the start of a tag — and content quoting EE syntax would break the page rendering it.
Mason therefore outputs literal braces from authored content as { / }. Browsers display these as ordinary braces, so an author can write documentation, a tutorial, or a JSON snippet containing { and it renders exactly as typed.
The consequence is that EE tags typed into a Mason field are displayed, not executed — writing {exp:channel:entries} in the editor shows that text on the page. Template logic belongs in your templates and brick partials, where the {brick:short_name} tokens below are resolved normally; this only affects braces in content an author typed.
Custom brick markup
By default a brick renders Mason's generic markup. Give it a template — a partial — to control that markup completely, using the same {brick:short_name} tokens, {if …} conditionals and Grid loops described above.
There are two places to write it, and they are the same template:
In the control panel. Open the brick and switch on Template. This is the whole of it — edit, save, done.
On the server. system/user/templates/mason-bricks/<brick_short_name>.html, beside your EE templates but not one of them: no site folder, no .group, and it will not appear in the Templates manager. Mason reads the file directly.
The two stay in step, the way ExpressionEngine's own templates do when saved as files:
- A file wins whenever one exists. It is the thing your editor, your deploy and your version control can act on, so nothing should quietly override it.
- Saving in the control panel writes that file, when the directory allows it.
- A partial that arrived over FTP is adopted the first time you open the brick — no copy-and-paste to get it into the editor.
- With no writable template directory, the markup is kept in the database instead. The brick renders identically; you simply have one home rather than two.
- A file that exists but cannot be written is reported when you save, rather than the edit being stored while the old file carries on rendering.
Renaming a brick moves its partial with it — the two are tied together by filename.
If a brick has no partial in either place, Mason falls back to system/user/addons/mason/templates/bricks/<handle>.html and then to its generic markup, so the add-on's bundled defaults still apply.
Two things worth knowing, because both fail silently by design: a token naming a field that does not exist renders as empty, and an unclosed loop swallows the rest of the partial. The usual symptom is "part of my brick just isn't there". mason_validate_template (see AI assistant) names the offending token.