Pages
A Builder page is one Builder field on an entry. The field stores the page as a tree of your parts: sections, the layouts in them and the components in those. The field's template tag renders the tree with your partials, so the HTML is always your own markup, styled by your design tokens.
Getting a page on the site
- Parts. Write section shells and components in
_sections/(Parts), and runvariflow:builder:verify. - The field. In Channels › Fields, add a field of type Variflow Builder to the channel's field group (settings below).
- The template. Output it inside
{exp:channel:entries}, with Variflow Tokens' CSS and layout stylesheet in the page's<head>:
<head>
{exp:variflow:css}
{exp:variflow:layout_css}
</head>
<body>
{exp:channel:entries channel="pages" limit="1"}
{page_builder}
{/exp:channel:entries}
</body>
The Builder field
A Builder field is a whole page, so it's a top-level channel field only: it can't go in a Grid, Fluid or Bloqs field (EE doesn't offer it there).
| Setting | Default | |
|---|---|---|
| Section shells | The shells editors may add. All ticked means all, including shells added later. | All |
| Section patterns | The section patterns editors may insert. | All |
| Open sections | Whether editors may add sections that don't come from a pattern. | Off |
| Default section | The shell of the new section a drop outside any section makes (dragging a component onto page area). None: no such drops. Needs Open sections. | None |
| Layout depth | How many levels layouts may nest; a section's own layouts are level 1. | 3, or $config['variflow_builder_max_depth'] |
| Column dividers | Dragging a column divider: snap to the layout presets, or also (holding Alt/⌥) to any whole grid column, stored as custom spans (below). | Presets only |
| Allow detaching | Whether editors may detach a locked or structured pattern copy. | Off |
| When the page has problems | What EE's Save does with a page that has content problems: Refuse to save; Save drafts only (save unless the entry's status is open); or Save and warn (always save, with a warning). Integrity problems always refuse the save. | Save drafts only (fields saved before this setting existed: Refuse to save) |
The shell, pattern and open-section rules apply to what an editor adds or changes; a section already on a page stays when you change them.
Storage. The page is JSON in the field's own data column (EE 7's per-field tables). Only part
names, token references, field values and query settings are stored, never HTML. A page with no
sections stores nothing, so {if page_builder} is false.
Saving checks the whole page against the parts and the live token build (below) and, by the field's When the page has problems setting, refuses it with a message for each problem, naming the node:
Section 2 (Section) › layout 1 (full) › column 1 › item 2: Sections are top level only: a column can't hold a section.
Section 1 (Section) › appearance accent: "#ff0000" is a colour. Pick a token from color.
Content and integrity problems
Problems come in two kinds.
Content problems mean the page isn't finished. It still renders: what's there shows, an
empty required field renders an empty element (or nothing), a query limit out of range is held
to maxLimit. These follow the field's When the page has problems setting:
| Problem | Code |
|---|---|
| A required field is empty | required |
| A container holds fewer (or more) items than its schema asks for | children_count |
Text longer than its field's maxLength |
too_long |
A number outside its field's min and max |
out_of_range |
A query control's limit outside 1 to maxLimit |
limit_range |
| A query control's category isn't in its group | category_missing |
A component in a column narrower than its minSpan |
too_narrow |
An entries field picks fewer than its min or more than its max (the first max render) |
entries_count |
| A picked entry can't be shown: deleted, or in another channel or site (the page renders without it). A closed, scheduled or expired pick is only switched off: no problem | entry_unavailable |
| A column with nothing in it (it renders as an empty column) | empty_column |
| A section with nothing in it: no components in its layouts and none of its own text, link, image or picks fields filled in (it renders as its empty shell) | empty_section |
An empty section's columns aren't listed one by one. Empty columns and sections in a locked or structured pattern copy, or in a shell whose content is fixed, aren't problems: their structure is the pattern's or the shell's, and editors can't remove them.
Before the entry is published, the editor lists these with a one-click fix where there is one (Editing pages › Publish checks).
Integrity problems are everything else, and always refuse the save, whatever the setting:
they could break rendering or token safety, and the editor never makes them (only hand-edited
JSON, or parts and tokens that changed under the page). They include malformed JSON and a tree
of the wrong shape (unknown keys, so no HTML can be put in the tree; values of the wrong type;
sections in columns), unknown parts and presets, free styling values (#ff0000) and tokens or
schemes the live build doesn't have, layouts the grid can't hold (columns that don't match the
preset, the depth cap, a preset too wide for its slot), ids, the field's rules for what editors
add (allowed shells and patterns, open sections), and the lock rules on pattern copies and fixed
shells.
The setting's three choices:
- Refuse to save (what every field saved before this setting existed gets): any problem refuses the save.
- Save drafts only (the default for a new field): content problems are allowed unless the entry is published, that is, its status is open (or a status named published). Builder reads the status the publish form posts, else the entry's stored status, else the channel's default status; when it can't tell, it counts the entry as published.
- Save and warn: content problems never stop the save.
When a save goes through with problems, the publish form shows a warning after EE's own "Entry updated" message (Page: saved with 3 problems), naming each node. Nothing else changes: the editor still shows each problem on its node, Variflow Tokens' usage is recorded as for any save, and the page renders what it has.
For development, $config['variflow_builder_save_with_problems'] = 'y' in config.php
makes every Builder field on the site Save and warn, whatever its setting says (the field's
settings say so). Integrity problems are still refused. Use it while page structure and
templates are changing; leave it out in production.
Revisions and statuses work as for any field: a revision holds the page, and restoring it brings the page back.
The publish form shows one prominent button, Launch Variflow Page Builder (and any
problem with the field above it), which opens the page editor over the form (Editing pages). The editor writes the
tree into the field's hidden input as you work; EE's Save saves it. With
$config['variflow_builder_json_editor'] = 'y' in config.php, developers also get Edit JSON
in the editor's toolbar; what they apply is checked like any other change. With
$config['variflow_builder_save_with_problems'] = 'y', every Builder field saves pages with
content problems and warns (Content and integrity problems):
for development sites.
The editor needs its bundle in themes/user/variflow_builder/ (part of the add-on's download),
and editors' roles need access to the Variflow Builder add-on (Roles › CP Access › Add-ons),
because the editor's requests go through Builder's control panel pages. Without it, Launch Variflow
Page Builder says the editor couldn't open.
The tree
{"v": 1, "sections": [
{"id": "s1", "section": "hero", "pattern": "home_hero", "patternVersion": 1, "lock": "locked",
"look": "scheme:light", "appearance": {"space_below": "space.2xl"},
"fields": {"caption": "The Hoh valley in November rain"},
"layouts": [
{"id": "l2", "preset": "full", "columns": [[
{"id": "c3", "type": "heading", "fields": {"text": "Walk slower. Notice more.", "level": "h1"}},
{"id": "c4", "type": "button", "variant": "button:outline", "fields": {"link": {"url": "/shop", "label": "Shop"}}}
]]}
]}
]}
| Node | Keys |
|---|---|
| Page | v (the tree's version, 1) and sections. |
| Section | id, section (the shell), layouts; optional look, variant, appearance, fields. A copy of a pattern also has pattern, patternVersion, patternSource and lock; a detached copy detachedFrom instead (below). |
| Layout | id, preset (a grid preset's name), columns (one list of items per column of the preset); optional order (below). Or custom spans: "preset": "custom" with spans (below). |
| Component | id, type (the component); optional fields, look, variant, appearance, children (a container's components), query (a query component's controls), and pattern, patternVersion and patternSource for a copy of a content pattern (or detachedFrom). |
-
Ids are Builder's: every node has one, unique on the page, and it never changes while the node exists. Tokens' usage list, the live canvas and pattern syncing rely on them. A tree without ids (a pattern, a JSON file) gets them when it's saved.
-
lookis a scheme reference ("scheme:dark"),varianta component variant ("button:outline"), and the other appearance options are underappearanceby control name: a token ("space.xl"), or a width forcontainer. Nothing else: no colours, sizes or fonts. -
fieldsholds field values by name: a string, a link{"url", "label"}, an image (a file ID or path, or{"file": …, "alt": "…"}when the editor gave it alt text),true/false, a number. -
Pattern copies record where they came from:
pattern(its name),patternVersion(its version when inserted) andpatternSource:"file"for a pattern file,"db"for a pattern saved in the editor (a copy inserted before saved patterns existed has nopatternSource: it's a file pattern's). The name is what links a copy to its pattern, so a copy keeps working when a saved pattern is exported and the file takes over. A section copy also stores itslock. Each item of a content pattern's copy carries the same three keys. -
A detached copy (Detach in the editor, where the field allows it) is open: it keeps where it came from, for reports and for synced patterns to skip, and nothing else of the link:
{"id": "s4", "section": "cta", "detachedFrom": {"pattern": "newsletter", "version": 2, "source": "db"}, "layouts": []}A node has
patternordetachedFrom, never both. -
An
entriesfield's value is the picked entries' IDs, in the editor's order:"fields": {"stories": [1657, 1702, 1658]},[]when nothing's picked. Only IDs: no titles, no URLs, so a renamed or moved entry stays picked. IDs are whole numbers above 0, each once (anything else is an integrity problem); too few or too many, or an entry that can't be shown any more, are content problems (Picked entries). A pattern keeps the IDs as they are: copied to another site, they're that site's IDs (usually other entries, or none). -
queryholds a query component's control values:{"topic": "trips", "limit": 4}. A category is its ID or URL title (a list of them when the control ismultiple), ornullfor any. -
orderis a layout's phone order:"reverse"stacks its columns last column first when they stack (on phones), and left out they stack in order. It's what the editor's On phones sets (Editing pages): In order or Last column first. Those are the only two, whatever the number of columns: a 3-across set to Last column first stacks 3, 2,- It renders as
data-vf-order="reverse", which Variflow Tokens' layout stylesheet lays out. It's appearance: a locked pattern copy keeps its pattern's, and a structured copy may change it when the pattern listsorderineditable.
- It renders as
-
Custom spans are what a column divider dragged to a width no preset has stores (with the field's Column dividers set to Any column):
{"id": "l5", "preset": "custom", "spans": [7, 5], "columns": [[…], […]]}.spansare whole columns of the page grid, one per column, adding up to the grid's columns; none may make a column narrower than the grid'sminSpanwhere the layout sits, and only a section shell that allows every preset ("presets": "all") may hold them. They render as<div data-vf-layout="custom">with each column's span on it,<div style="--vf-span: 7">, which Variflow Tokens' layout stylesheet (1.3) lays out: stacked below the grid'smdbreakpoint, side by side from there, like a preset with no tablet spans. Choosing a preset for the layout drops its spans. (customis Builder's name for this; don't name a grid presetcustom.)
What's checked
Saving checks:
- Nesting: sections only at the top, layouts with one list per column, components and layouts in columns, containers holding the components they accept; layouts no deeper than the field's depth.
- Fit: each nested preset fits the slot it's in (its
minSlot), and each component its column (itsminSpan). Custom spans add up to the grid and keep every column at leastminSpanwide. - Fields: each value the right type for its field (lengths, select options, min and max), and required fields filled in.
- Appearance: each value one the part offers, and in the live token build (through the Integration API). A token renamed in Tokens is followed.
- Picked entries: IDs once each;
minandmax; each picked entry on this site, in the field's channels and statuses, published and not expired (content problems, so they follow the save setting). - Query controls: only the controls the schema gives,
limitup tomaxLimit, categories that exist in the control's group. - Pattern copies: a copy of a
lockedpattern can change only its field values: the same parts, layouts and appearance as the pattern. Astructuredcopy can also change the appearance options its pattern lists ineditable. Anopencopy is the editor's. A copy'slockcan't be changed, and it can be detached (itspatternreplaced bydetachedFrom) only when the field allows it ("Allow detaching"). A detached copy is open. A copy made from an older version of its pattern isn't checked against the new one (the editor marks it "Out of date"). A copy whose pattern has been deleted is open too: nothing holds it to a pattern any more. - Fixed shells: a section whose shell has
"content": "fixed"keeps the shell's layouts and components; editors fill them in and style them.
Versions
v is the tree's version. When a later release changes the shape, a stored tree is upgraded as
it's read, one version at a time; nothing has to be migrated. A tree newer than the installed
Builder isn't rendered or saved over.
Template tags
| Tag | Output |
|---|---|
{page_builder} |
Every section, rendered. |
{page_builder}…{/page_builder} |
A loop over the sections, for wrapping them yourself. |
{page_builder:outline} |
A list of the sections' headings (<ul class="vfb-outline">), each linked to its section when the section's outer element has an id. As a pair, a loop. |
{page_builder:total_sections} |
How many sections render. |
In the loop:
| Variable | |
|---|---|
{section:html} |
The section, rendered. |
{section:id} |
Its id (s1). |
{section:type} |
Its shell's name (hero). |
{section:look} |
Its scheme's name (dark), or nothing. |
{section:pattern} |
The pattern it came from, or nothing. |
{section:heading}, {section:anchor} |
Its first heading's text, and its outer element's id. |
{section:count}, {section:total} |
Its place, and how many there are. |
{page_builder}
<div class="page-section page-section--{section:type}">{section:html}</div>
{/page_builder}
The outline's loop has {outline:heading}, {outline:url} (#anchor, or nothing),
{outline:anchor}, {outline:id} and {outline:count}.
A hand-built fallback. {page_builder:total_sections} is 0 for a page with no sections, so a
template can fall back to other markup:
{if page_builder:total_sections > 0}{page_builder}{if:else}{body}{/if}
Partials
Each section and component renders its partial (<name>.section.html, <name>.component.html) as
an EE template fragment, with Builder's variables. What Builder doesn't set is left for EE to
parse with the rest of the template: globals ({path='…'}, {site_url}), and conditionals on
them.
Variables
| Variable | |
|---|---|
{vfb:attrs} |
The node's token attributes: data-vf-scheme="dark" for its look, data-vf-variant="button:outline" for its variant (its schema's defaults when the node has none; a look of inherit adds nothing). In a CP preview, also data-vfb-id for the live canvas (a partial without {vfb:attrs} gets it on its first element). Put it on the element the look and variant style. |
{vfb:content} |
A section's layouts, or a container's children. |
{vfb:field:<name>} |
A field's value, escaped for HTML (below). |
{vfb:appearance:<name>} |
A token control's value as CSS: var(--vf-space-xl), following schemes. Also :var (the var() reference), :value (the build's value, 48px), :name (space.xl) and :label. |
{vfb:appearance:container}, {vfb:container} |
A section's content width: default, wide or full. Put it on your wrapper as data-vf-container="{vfb:container}". |
{vfb:look}, {vfb:variant} |
The scheme's name (dark, or nothing) and the variant (button:outline). |
{vfb:narrow} |
The component's narrowLayout name when its column is narrower than below grid columns, otherwise nothing. The column's width is in grid columns, from the presets it sits in (the editor works it out the same way for its "Shown as List here"), so it doesn't change with the screen. |
{vfb:span} |
The width of the column the node sits in, in grid columns (12, 8, 4 …), from the presets it's nested in. |
{vfb:id}, {vfb:type}, {vfb:pattern} |
The node's id, its part's name, and the pattern it came from. |
{vfb:preview} |
y in a CP preview, otherwise nothing. |
{vfb:entries}…{/vfb:entries}, {vfb:count} |
A query component's entries, and how many (below). |
Each field, by type:
| Type | {vfb:field:<name>} |
Also |
|---|---|---|
| text, textarea, select, url | The value, escaped. | textarea: :br (line breaks as <br>) |
| richtext | The HTML, cleaned (no scripts or event attributes). | |
| link | The URL. | :url, :label |
| image | The file's URL. | :url, :alt (the alt text the page gives it, else the file's description, else its title), :title, :width, :height |
| toggle | 1 when on, nothing when off. |
|
| number | The number. |
A field that its showWhen hides in the editor (Parts) still
has its variable, with the value it was last set to (or its default): the partial decides what it
means.
Every field variable is also available without the prefix ({heading}, {link:url}), as 0.1's
first guide had them. Values are always escaped, and EE tag braces in them are encoded, so content
never becomes a tag. EE's variable modifiers (:limit, :length) aren't applied to Builder's
variables.
Use {if …} with any of them: {if vfb:field:eyebrow}, {if vfb:narrow == "list"},
{if vfb:count > 0}.
Builder takes your data-vfb-field markers (and any other data-vfb- attribute) out of the HTML
it sends to visitors; they're only for the live canvas.
Layouts
A layout renders as the preset's attributes from Variflow Tokens' layout stylesheet, with one
<div> per column:
<div data-vf-layout="8/4" data-vf-order="reverse">
<div>…the first column's items…</div>
<div>…the second column's…</div>
</div>
The layout stylesheet ({exp:variflow:layout_css}) sets the columns, the gutter and how they
stack. Each column's width is worked out from the presets around it (a 6/6 in the 8 of an 8/4 gives
two columns of 4), for {vfb:span} and {vfb:narrow}.
Query components
A query component runs its query itself, through EE's models, not a nested
{exp:channel:entries}: the schema's channels, statuses and order, on the current site,
published (not future or expired), filtered by the editor's categories, up to the editor's limit
(never more than maxLimit). Each distinct query runs once per request, however many times it's
on the page. To cache the page's output across requests, use EE's template caching.
In {vfb:entries}…{/vfb:entries}:
| Variable | |
|---|---|
{title}, {url_title}, {entry_id} |
The entry. |
{entry_date format="%M %j, %Y"} |
Its date, with EE's date formats. |
{permalink} |
Its URL: its Structure (or Pages) URI when it has one, otherwise the channel's comment URL (or channel URL) and its URL title. |
{channel}, {status}, {author_id} |
|
{count}, {total_results} |
|
the schema's fields |
Each custom field the schema maps ("fields": {"excerpt": "fh_lede"} gives {excerpt}). |
When nothing matches, {vfb:entries} is empty and {vfb:count} is 0. With
"hideHeadingWhenEmpty": true the component isn't rendered at all, heading included; without it,
the partial still renders, so it can say there's nothing yet.
Picked entries
A component with an entries field (Parts) gives its partial the
same {vfb:entries}…{/vfb:entries} loop and variables as a query component, with the editor's
picks in the editor's order. They're fetched in one query however many are picked (the same
query a query component runs, narrowed to the picked IDs): the field's channels and statuses, on
the current site, published (not future or expired).
A pick that's been deleted, closed, moved to a channel the field doesn't take, scheduled or
expired since is left out, quietly: no error on the page, and the rest keep their order. The
editor names a closed, scheduled or expired pick with a quiet note ("Not shown while it's
closed"); it isn't a page problem, and it shows again when the entry is reopened. A deleted pick,
or one in another channel or site, shows as unavailable, saying why, with Remove. {count} and
{total_results} count what's rendered, and {vfb:count} too. More picks than max (a page
saved with that problem) render the first max.
With nothing to show (nothing picked, or none of them can be shown) and
"hideHeadingWhenEmpty": true, the component isn't rendered at all, heading included; without
it, the partial renders with an empty loop and {vfb:count} 0.
To find the pages that pick an entry: php system/ee/eecli.php variflow:builder:usage --entry=<id>
(Verifying parts).
When something's wrong
A node whose part has gone, that no longer validates against the parts or the live build (a token removed, a preset renamed: an integrity problem), or whose partial is missing or can't be parsed (a broken conditional), renders nothing on the site, and Builder writes what and why to EE's Developer Log. The rest of the page renders. CP members looking at the entry in Live Preview (and the editor's canvas) see a notice in its place.
A node with only a content problem (an empty required field,
text over its maxLength, a component in too narrow a column) renders what it has, with no
notice: a page saved with problems shows what's there.
In Live Preview every node's element also carries data-vfb-id (on the element with
{vfb:attrs}, else on the partial's first element), for the editor's canvas
(Parts › Previewing in the editor). Visitors' pages never
have data-vfb-* attributes or the canvas's script.
A page of 30 sections renders in about 10 ms on a developer's machine, once its parts are read (about 45 ms for the first page of a request), not counting queries. Parts and partials are read once per request.
A worked example
A component (product_card.component.json) and its partial:
{
"name": "product_card",
"label": "Product card",
"description": "A product: photo, tag, name and price.",
"version": 1,
"fields": [
{ "name": "image", "label": "Photo", "type": "image", "inline": true },
{ "name": "name", "label": "Name", "type": "text", "required": true, "maxLength": 80, "inline": true },
{ "name": "price", "label": "Price", "type": "text", "maxLength": 20 },
{ "name": "tag", "label": "Tag", "type": "text", "maxLength": 24 },
{ "name": "url", "label": "Product link", "type": "url" }
],
"appearance": {
"variant": { "label": "Card style", "group": "card", "default": "card:raised" },
"tag_colour": { "label": "Tag colour", "group": "color", "type": "color", "default": "color.feedback.info" }
},
"minSpan": 3
}
<article class="card" {vfb:attrs}>{if vfb:field:image}
<img src="{vfb:field:image}" alt="{vfb:field:image:alt}" data-vfb-field="image">{/if}{if vfb:field:tag}
<span class="badge" style="--tone: {vfb:appearance:tag_colour};">{vfb:field:tag}</span>{/if}
<h3><a href="{vfb:field:url}" data-vfb-field="name">{vfb:field:name}</a></h3>
<p class="price">{vfb:field:price}</p>
</article>
A page with a band holding two of them side by side:
The tree
{"v": 1, "sections": [
{"section": "band", "look": "scheme:light", "appearance": {"space_above": "space.xl"},
"layouts": [
{"preset": "6/6", "columns": [
[{"type": "product_card", "fields": {"name": "Alder 28L Daypack", "price": "$148", "tag": "Repairable for life", "url": "/shop/alder"},
"appearance": {"tag_colour": "color.feedback.success"}}],
[{"type": "product_card", "variant": "card:flat", "fields": {"name": "Cedar Camp Mug", "price": "$24", "url": "/shop/mug"}}]
]}
]}
]}
And what {page_builder} outputs (the band's partial is <section class="band" {vfb:attrs} style="padding-top: {vfb:appearance:space_above};"><div class="wrap" data-vf-container="{vfb:container}">{vfb:content}</div></section>):
<section class="band" data-vf-scheme="light" style="padding-top: var(--vf-space-xl);"><div class="wrap" data-vf-container="default"><div data-vf-layout="6/6"><div><article class="card" data-vf-variant="card:raised">
<span class="badge" style="--tone: var(--vf-color-feedback-success);">Repairable for life</span>
<h3><a href="/shop/alder">Alder 28L Daypack</a></h3>
<p class="price">$148</p>
</article></div><div><article class="card" data-vf-variant="card:flat">
<h3><a href="/shop/mug">Cedar Camp Mug</a></h3>
<p class="price">$24</p>
</article></div></div></div></section>
Rename color.feedback.success in Variflow Tokens with Rewrite references and this page's tree
is rewritten with it; Undo puts it back. Token usage lists it as "Shop › Section › Product card ›
tag_colour", linked to the entry, and a token build that removes a token this page uses is refused.