Parts
Editors build pages in Variflow Builder from parts that you, the developer, write as files in the site's repo. There are three kinds:
| Kind | File | What it is |
|---|---|---|
| Section shell | <name>.section.json + <name>.section.html |
The top level of a page: a band with a look, spacing and a width, holding layouts. |
| Component | <name>.component.json + <name>.component.html |
Something a column holds: a heading, a button, a card. A container holds other components; a query component lists entries. |
| Pattern | patterns/<name>.pattern.json |
A saved piece of a page, built from sections and components. No partial of its own. Site builders can also save patterns from the page editor (Saved patterns). |
Each schema (.json) says what editors fill in and which design choices they get. Each partial
(.html) is the EE template markup that renders it. Parts style only with design tokens: a
schema can offer a scheme, a step from a token group or a component variant, never a colour, size
or font written out.
Check your parts with variflow:builder:verify, or on Builder › Parts in the
control panel, where you can also edit sections and components. To style them with plain CSS or a framework (Tailwind, Bootstrap and others), see
Bring your own CSS.
The folder
Parts live per site, in a fixed folder beside the site's templates:
system/user/templates/<site_short_name>/_sections/
├── hero.section.json + hero.section.html
├── band.section.json + band.section.html
├── heading.component.json + heading.component.html
├── card.component.json + card.component.html (a container)
├── latest_entries.component.json + latest_entries.component.html (a query component)
└── patterns/
└── newsletter_card.pattern.json
_sections/isn't a template group (it has no.groupsuffix), so EE never routes it.- On a multi-site install each site has its own folder, under its short name.
- File names are lowercase: letters, digits and underscores, then
.section.json,.component.jsonor.pattern.json. Anything else in the folder is reported as a warning and ignored. - A site with no
_sections/folder has no parts. That's a note, not an error. - Change them in your code editor and deploy them like templates, or edit sections and
components on Builder › Parts (Editing parts in the control panel).
variflow:builder:export-patternwrites a pattern file when you run it. Nothing else writes them.
Editing parts in the control panel
Builder › Parts lists every part. A section or component has Edit (or View, for a member who can't change it), and New part at the top starts one.
- The edit screen has two tabs, Template (the
.htmlpartial) and Settings (the.jsonschema), in EE's code editor with the Template Manager's highlighting. Beside them: the problems, what editors get from the part (its Library entry, sidebar fields and appearance), and the pages that use it. ⌘S or Ctrl+S saves. - Check runs the same checks as
variflow:builder:verifyon your changes without saving them. Each problem names its tab and line; click it to jump there. A problem the change causes elsewhere (a container that accepts the component, a pattern that uses a field) is listed too. - Save checks first. Errors stop it, so a mistake never reaches the page editor or the site; warnings don't. Problems the site already had in other parts don't stop it either.
- If the files changed on disk after you opened them (a deploy, a code editor, another member), Save doesn't overwrite them. It shows what changed between the disk version and yours, and you choose: discard yours, or Save mine over it.
- New part starts from a small working section or component, or a copy of an existing part under a new name. Nothing is written until you create it, and it's checked first.
- Revisions: every save keeps the version saved, and first the version on disk when it was changed outside the control panel, so that isn't lost either. The last 20 per part are kept. Compare one with the current files, or open it in the editor and save it to restore it.
- Delete removes both files. It's refused while any page uses the part (they're listed), or when removing it would break another part. A deleted part's last version stays in its revisions, and Deleted parts on Builder › Parts brings it back.
- Renaming isn't offered: pages store a part's name. Make a copy under the new name instead.
- Writes are atomic: each file is written beside the old one and renamed over it, so a reader
sees the old file or the new one, never part of either. Nothing extra is left in
_sections/.
Who can: parts are template code, so this follows EE's template partial permissions: Edit
template partials to change one, Create to add one and Delete to delete one, each with
Access Design (super admins always). Anyone who can open Builder's pages can read a part.
If the web server can't write to _sections/, the screen opens read-only and says why.
Version control: an edit here changes the files on that server only. On a site whose parts
are deployed from a repo, edit them in the repo, or copy changes made here back into it before
the next deploy overwrites them. To turn editing off on such a server, add this to config.php:
$config['variflow_builder_cp_editing'] = 'n';
Builder › Parts then shows the files read-only, with a note saying why. Patterns aren't edited here: saved patterns have Builder › Patterns, and pattern files are edited in your repo.
Common keys
Every schema is a JSON object. Unknown keys are errors, so a typo ("lable") is caught rather
than ignored; verify suggests the key you meant.
| Key | ||
|---|---|---|
name |
required | The part's name: lowercase letters, digits and underscores, starting with a letter. It must match the file name (hero for hero.section.json) and is unique per kind. |
label |
required | What editors see. |
description |
required | A sentence for the part picker. |
icon |
optional | An icon name (lowercase letters, digits, hyphens), such as image or table-columns: the part's icon in the editor's Library, Plan and the canvas's selection tab. See Icons. |
version |
required | A whole number, 1 or more. Raise it when you change a part in a way stored pages should know about. |
$comment |
optional | Your own notes. Ignored. |
preview |
optional | Sections and components: how the editor's canvas shows an edit. "swap" (the default) redraws just the section; "reload" reloads the whole page. See Previewing in the editor. |
Icons
The editor draws its own small set of icons (it uses no icon font). A part's icon is:
- its
icon, if it's one of the names below; - otherwise the icon for the part's
name, if that's one of them (a component calledheadinggets the heading icon,quotethe quote,imagethe image); - otherwise its kind's: a section, a component or a pattern (layouts and columns have their own).
So an icon the editor doesn't draw is no error: the part falls back to (2) or (3). Verify still
checks the name's form (lowercase letters, digits, hyphens).
| Names | |
|---|---|
heading |
A heading. |
paragraph, text |
Text. |
image, photo, picture, gallery, hero |
An image. |
button, buttons, actions, hand-pointer |
A button, or a row of them. |
link, arrow-right, more-link |
A link. |
list, list-ul, list-ol, features |
A list. |
star, feature |
A feature. |
quote, quote-left, quote-right, testimonial |
A quote. |
square, card |
A card. |
panel, window-maximize |
A panel. |
tag |
A product or a label. |
newspaper |
Stories, entries. |
calendar, calendar-days |
Dates, events, trips. |
book, book-open |
Reading, stories. |
envelope, newsletter |
A sign-up, email. |
megaphone, bullhorn, cta |
A call to action. |
house, home |
A home page part. |
bars, band |
A band. |
footer, window-minimize |
A footer. |
columns3, table-columns |
Columns. |
lines, grip-lines |
Rows. |
mountain, person-hiking |
The outdoors. |
video, film, circle-play |
Video. |
map, map-location-dot, location-dot |
A map, a place. |
form |
A form. |
divider, minus, hr |
A divider. |
accordion |
An accordion. |
table |
A table. |
section, component, cube, pattern, layout, column |
The kinds' own icons. |
Fields
fields is a list of what editors fill in. Sections and components have fields; patterns don't.
"fields": [
{ "name": "text", "label": "Heading", "type": "text", "required": true, "maxLength": 160, "inline": true },
{ "name": "level", "label": "Level", "type": "select", "default": "h2",
"options": [{ "value": "h2", "label": "Section (h2)" }, { "value": "h3", "label": "Sub-section (h3)" }] }
]
Every field has:
| Key | ||
|---|---|---|
name |
required | Unique in the part. Lowercase letters, digits and underscores; it can't start with vfb. |
label |
required | What editors see. |
type |
required | One of the types below. |
required |
optional | true or false (the default). |
default |
optional | The value a new part starts with. It must suit the type (below). |
inline |
optional | true: editable in place on the canvas (from Builder's live canvas). The partial must mark the element with data-vfb-field="<name>". Text, textarea, rich text, link and image fields can be inline. |
instructions |
optional | Help text under the field. |
showWhen |
optional | Show the field only when another field has certain values (below). |
The types, and their own options:
| Type | Options | Default |
|---|---|---|
text |
maxLength, placeholder |
a string ("") |
textarea |
maxLength, rows, placeholder |
a string |
richtext |
toolbar: minimal, basic or full |
a string |
url |
placeholder |
a string |
link |
none; a URL and its label | {"url": "…", "label": "…"} or null |
image |
directories: "all" or a list of upload directory IDs or names |
null (editors pick the file). Stored as a file ID, a path or URL, or asset:<name> (a Variflow asset); with alt text {"file": …, "alt": "…"}; decorative {"file": …, "decorative": true}, whose :alt is "" |
select |
options (required): a list of {"value": …, "label": …} |
one of the values (the first, if left out) |
toggle |
none | true or false |
number |
min, max, step |
a number within min and max, or null |
entries |
channels (required), status, min, max (required), fields, hideHeadingWhenEmpty: Picked entries |
[] (editors pick the entries) |
An option that belongs to another type is an unknown key. A select option's value can't be a
styling value ("#ff0000", "24px"): offer a token group as an appearance control instead.
Conditional fields
showWhen shows a field only when an earlier select or toggle field of the same part has
certain values, so editors don't see options that don't apply:
{ "name": "focus", "label": "Focus", "type": "select", "default": "center",
"options": [{ "value": "center", "label": "Centre" }, { "value": "top", "label": "Top" }],
"showWhen": { "field": "shape", "not": "original" } },
{ "name": "align", "label": "Align", "type": "select", "default": "start",
"options": [{ "value": "start", "label": "Start" }, { "value": "end", "label": "End" }],
"showWhen": { "field": "size", "in": ["natural"] } }
{"field": <name>, "in": [values…]}shows it for those values;{"field": <name>, "not": <a value, or a list>}shows it for any other. A select's values are its option values; a toggle's aretrueandfalse. The named field's default counts when a node hasn't set it.variflow:builder:verifychecks what it names: a field of the same part (show_when_field), listed earlier, so the inspector reads top down; aselectortoggle(show_when_type); values that field can have (show_when_value); and one level only: the named field can't have ashowWhenof its own (show_when_chain), so there's no chain and no cycle. A field can't name itself.- A hidden field keeps its value. The inspector doesn't show it, but the page keeps what it
was set to, so switching back brings it back. A
requiredfield that's hidden isn't required. - The renderer still passes it.
{vfb:field:focus}is there whether the field shows or not, so the partial decides what a hidden value means (Fernhaven's Image writesdata-focusonly when the shape crops), as it would withoutshowWhen.
Appearance
appearance is the design choices a part offers editors, by control name. Every control is backed
only by tokens and has a default. There are four kinds.
"appearance": {
"look": { "schemes": "all", "default": "light" },
"space_above": { "label": "Space above", "group": "space", "type": "dimension", "default": "space.none" },
"variant": { "label": "Style", "group": "component.button", "default": "button:primary" },
"container": { "allowed": ["default", "wide"], "default": "default" }
}
look: a scheme from the token file.
| Key | |
|---|---|
schemes |
"all" (the default) or a list of scheme names, without scheme: (["light", "dark"]). |
default |
A scheme name, or "inherit": no scheme of its own, so it takes the section's. |
label |
Optional (Look). |
variant: a component variant group from the token file
(Variflow Tokens' guide, Component variants).
| Key | |
|---|---|
group |
"component.button", or just "button". |
default |
A variant reference: "button:primary". |
label |
Optional (Style). |
container (sections only): the content width, from the grid's containers.
| Key | |
|---|---|
allowed |
Any of "default", "wide" and "full" (all three when left out). default and wide are the token file's grid.container.*; full is the whole width. |
default |
One of allowed. It's also the section's default content width; a section without a container control is default. |
label |
Optional (Width). |
Any other name (spacing, space_above, gap, tag_colour, …): a step from a token group.
| Key | |
|---|---|
group |
required: a token group path, such as space or color.feedback, or a list of them (["color.action", "color.feedback", "color.bark"]) that don't overlap. Editors pick one of their tokens, never one the token file hides ("hidden": true, Variflow Tokens 1.3.0). |
type |
optional: the token type the group must hold (dimension, color, …). A control named spacing is dimension unless it says otherwise. |
default |
required: a token in the group (in one of them, for a list), such as space.xl. |
label |
optional (from the name). |
Space above and Space below
Every component also gets two appearance options you don't declare: Space above and Space
below, from the site's spacing scale (the space token group). An editor picks a step for one
item; Standard, the default, outputs nothing, so your stylesheet's own spacing applies. A
picked step is an inline margin on the component's outer element (margin-block-start and
margin-block-end, such as var(--vf-space-8)), added to the first element of its rendered
partial, so it overrides the gap your CSS puts between items with nothing to add to the
stylesheet.
- The partial needs one outer element: markup that starts with text or a tag pair (such as
{exp:my_plugin}) can't take the margin. Wrap it in an element. - They're stored like any appearance value (
"appearance": {"space_above": "space.8"}), so the checks, locks,editablelists in structured patterns, the licence, and Variflow Tokens' usage, renames and remaps cover them. - A component that declares its own
space_aboveorspace_belowcontrol keeps it. Add"spacing": falseto a component's schema to leave both out (a divider, a full-bleed band). - Another group:
$config['variflow_builder_spacing'] = 'size.gap';inconfig.php.'n'turns them off everywhere. Verify warns (spacing_group_missing) when the group has no dimension tokens in the live build. - Sections already offer their own spacing controls, so they don't get these.
Tokens only
There are no free colours, sizes or fonts anywhere in a part. Verify fails a schema that tries
one, such as a "color" key, a control's default of "24px", "#1e2420", "var(--x)" or a
font stack, or a container width in pixels. Name a token group instead, and add the tokens to the
token file if they aren't there.
Sections
A section shell (*.section.json) is the top level of a page. It holds layouts: a layout preset
from the grid with a list of items per column. Besides the common keys, fields and appearance:
| Key | ||
|---|---|---|
presets |
optional | "all" (the default: every preset in the grid) or a list of preset names (["full", "8/4"]). |
content |
optional | "open" (the default): editors add, remove and arrange layouts and components. "fixed": the section always has the layouts in tree; editors fill them in. |
tree |
for fixed | The layouts it starts with (open) or always has (fixed), in the tree shape. |
The section's default content width is its container control's default (or default).
cta.section.json
{
"name": "cta",
"label": "Call to action",
"description": "A band that asks for one thing: copy and buttons, with an optional card beside them.",
"icon": "bullhorn",
"version": 1,
"appearance": {
"look": { "schemes": ["brand", "dark", "seasonal"], "default": "brand" },
"space_above": { "label": "Space above", "group": "space", "type": "dimension", "default": "space.3xl" },
"space_below": { "label": "Space below", "group": "space", "type": "dimension", "default": "space.3xl" },
"container": { "allowed": ["default", "wide"], "default": "default" }
},
"presets": ["full", "8/4", "6/6"],
"content": "open",
"tree": [
{
"preset": "8/4",
"columns": [
[
{ "type": "heading", "fields": { "level": "h2" } },
{ "type": "button", "variant": "button:primary" }
],
[
{ "type": "card", "look": "scheme:light", "children": [{ "type": "heading", "fields": { "level": "h3" } }] }
]
]
}
]
}
Components
A component (*.component.json) is something a column holds. Besides the common keys, fields and
appearance (any control but container):
| Key | ||
|---|---|---|
children |
optional | Makes it a container (a card, tabs, an accordion): {"accepts": [component names] or "all", "min": 0, "max": …}. Containers hold components, not layouts or sections. Every name in accepts must be a component. |
minSpan |
optional | The narrowest column it fits, in grid columns. Between the grid's minSpan and its columns; the grid's minSpan when left out. |
narrowLayout |
optional | An alternative for narrow slots: {"below": 8, "name": "list", "label": "List"}. In a slot narrower than below grid columns the partial gets {vfb:narrow} = list, so three across can become a list. The editor's Plan and inspector say so where it applies ("Shown as List here": label is the word they use). The slot is the column's width in the grid, from the presets it's nested in, so the same markup is used on every screen. |
query |
optional | Makes it a query component (below). A query component can't also be a container. |
card.component.json
{
"name": "card",
"label": "Card",
"description": "A card holding a few components: Raised or Flat, in its own scheme or the band's.",
"icon": "square",
"version": 1,
"appearance": {
"variant": { "label": "Card style", "group": "component.card", "default": "card:raised" },
"look": { "schemes": "all", "default": "inherit" }
},
"children": { "accepts": ["heading", "text", "button", "image"], "min": 1, "max": 6 },
"minSpan": 3
}
Recommended image part
An image should fill its column unless the editor says otherwise. Two things go wrong without
care: <figure> has a 40 px margin in every browser, and an <img> with no width is its own
size. Fernhaven's image component is a pattern to copy: positioning is a few select fields
(fixed lists, never free values), and the partial turns each choice into a class or data
attribute that your stylesheet styles. Abridged from image.component.json:
"fields": [
{ "name": "image", "label": "Image", "type": "image", "required": true, "inline": true },
{ "name": "alt", "label": "Alt text", "type": "text", "required": true, "maxLength": 200 },
{ "name": "size", "label": "Size", "type": "select", "default": "fill",
"options": [{ "value": "fill", "label": "Fill the column" }, { "value": "natural", "label": "Natural (never wider than the column)" }] },
{ "name": "shape", "label": "Shape", "type": "select", "default": "original",
"options": [{ "value": "original", "label": "Original" }, { "value": "wide", "label": "Wide (16:9)" }, { "value": "square", "label": "Square (1:1)" }] },
{ "name": "focus", "label": "Focus", "type": "select", "default": "center",
"options": [{ "value": "center", "label": "Centre" }, { "value": "top", "label": "Top" }],
"instructions": "The part of the photo kept when Shape crops it.",
"showWhen": { "field": "shape", "not": "original" } },
{ "name": "align", "label": "Align", "type": "select", "default": "start",
"options": [{ "value": "start", "label": "Start" }, { "value": "center", "label": "Centre" }, { "value": "end", "label": "End" }],
"instructions": "Where a Natural-size photo sits in the column.",
"showWhen": { "field": "size", "in": ["natural"] } }
],
"appearance": {
"corners": { "label": "Corners", "group": "radius", "type": "dimension", "default": "radius.lg" }
}
<figure class="fh-figure fh-figure--{vfb:field:size} fh-figure--{vfb:field:shape}"{if vfb:field:shape != "original"} data-focus="{vfb:field:focus}"{/if}{if vfb:field:size == "natural"} data-align="{vfb:field:align}"{/if} style="--fh-figure-radius: {vfb:appearance:corners};">
<img src="{vfb:field:image}" alt="{vfb:field:alt}" data-vfb-field="image">
</figure>
.fh-figure { margin: 0; }
.fh-figure img { display: block; width: 100%; height: auto; border-radius: var(--fh-figure-radius); }
.fh-figure--natural img { width: auto; max-width: 100%; }
.fh-figure--natural[data-align="center"] img { margin-inline: auto; }
.fh-figure--natural[data-align="end"] img { margin-inline-start: auto; }
.fh-figure--wide img, .fh-figure--square img { object-fit: cover; }
.fh-figure--wide img { aspect-ratio: 16 / 9; }
.fh-figure--square img { aspect-ratio: 1 / 1; }
.fh-figure[data-focus="top"] img { object-position: center top; }
- The defaults (
fill,original) are what a node stored before these fields existed gets, so adding them later leaves existing pages as they were. Raise the part'sversionwhen you do. - Focus and Align show only when they apply (conditional fields): Focus
when the shape crops, Align at natural size, matching what the partial uses (it writes
data-focusonly when the shape crops,data-alignonly at natural size). A value set before it was hidden stays on the page. - The editor's choices reach the page as class names and attribute values from your own option
lists, never as inline CSS; the only inline style is a token (
{vfb:appearance:corners}).
Query components
A query component lists entries. You fix the channels and the rules; editors get only the controls you expose.
Key in query |
||
|---|---|---|
channels |
required | Channel short names. |
status |
optional | Statuses to show (["open"], the default). |
orderBy |
optional | date (the default), title, edit_date, entry_id or random. |
sort |
optional | desc (the default) or asc. |
limit |
required | How many, by default. |
maxLimit |
required | The cap: editors can never ask for more. At most 100. |
controls |
optional | What editors may change, by name: {"type": "category", "label": …, "group": <category group ID or name>, "multiple": false} filters by a category, and {"type": "limit", "label": …} lets them choose how many, up to maxLimit. |
fields |
optional | Custom fields to have in {vfb:entries}, by variable name: {"excerpt": "fh_lede"} gives {excerpt}. Each must be a field of one of the channels. |
hideHeadingWhenEmpty |
optional | true: when nothing matches, the component isn't rendered at all, heading included. Otherwise its partial renders with no entries (Pages). |
latest_entries.component.json
{
"name": "latest_entries",
"label": "Latest from the journal",
"description": "The newest journal stories, by topic if you like.",
"icon": "newspaper",
"version": 1,
"fields": [
{ "name": "heading", "label": "Heading", "type": "text", "default": "From the journal", "inline": true }
],
"appearance": {
"variant": { "label": "Card style", "group": "card", "default": "card:flat" }
},
"minSpan": 4,
"narrowLayout": { "below": 8, "name": "list", "label": "List" },
"query": {
"channels": ["fh_journal"],
"status": ["open"],
"orderBy": "date",
"sort": "desc",
"limit": 3,
"maxLimit": 6,
"controls": {
"topic": { "type": "category", "label": "Topic", "group": "Fernhaven topics" },
"limit": { "type": "limit", "label": "How many" }
},
"hideHeadingWhenEmpty": true
}
}
Picked entries
An entries field lets editors hand-pick entries (featured products, related stories) and put
them in order. The partial loops over them with the same {vfb:entries}…{/vfb:entries} pair and
variables as a query component (Pages), in the editor's order. You fix
the channels and statuses; editors search those, pick, reorder and remove.
| Key on the field | ||
|---|---|---|
channels |
required | Channel short names editors pick from. |
status |
optional | Statuses an entry may have to be picked and shown (["open"], the default). |
max |
required | The most editors may pick. At most 50. |
min |
optional | The fewest (0, the default). |
fields |
optional | Custom fields to have in {vfb:entries}, as a query's fields: {"excerpt": "fh_lede"} gives {excerpt}. Each must be a field of one of the channels. |
hideHeadingWhenEmpty |
optional | true: when nothing is picked, or none of the picks can be shown, the component isn't rendered at all, heading included. |
The rules:
- One loop per component. A component has at most one
entriesfield, and one with anentriesfield can't also have aquery(orchildren), so{vfb:entries}always means one list. Anentriesfield on a section shell is refused too. - Not inline, and its
defaultis[]: entry IDs differ from site to site. - Verify checks the channels exist and each mapped field belongs to one of them, as for queries.
- Too few or too many picks (
min,max) and a pick that can't be shown any more (deleted, or moved to another channel or site) are content problems: they follow the field's "When the page has problems" setting, and the page renders without them (Pages). - A pick that's closed (in a status the field doesn't show), scheduled or expired is only switched off: the page renders without it, and it's no problem at all. It shows again when the entry is reopened, so closing an entry never stops a page from saving.
featured_entries.component.json
{
"name": "featured_entries",
"label": "Featured stories",
"description": "Journal stories you pick and order yourself.",
"icon": "star",
"version": 1,
"fields": [
{ "name": "heading", "label": "Heading", "type": "text", "default": "Featured stories", "inline": true },
{
"name": "stories",
"label": "Stories",
"type": "entries",
"instructions": "Pick up to six journal stories; they show in this order.",
"channels": ["fh_journal"],
"status": ["open"],
"max": 6,
"fields": { "excerpt": "fh_lede" },
"hideHeadingWhenEmpty": true
}
],
"appearance": {
"variant": { "label": "Card style", "group": "card", "default": "card:flat" }
},
"minSpan": 4,
"narrowLayout": { "below": 8, "name": "list", "label": "List" }
}
Its partial is latest_entries' markup: the same {vfb:entries} loop.
Patterns
A pattern (patterns/*.pattern.json) is a saved piece of a page that editors insert whole. It has
the common keys and:
| Key | ||
|---|---|---|
lock |
required | locked: inserted as is; editors change only its words, links and images (field values), never its parts, layouts or appearance. structured: the same, but editors may also change the appearance options in editable. open: a starting point, freely editable once inserted. A page's copy records the pattern, its version and its lock (Pages). |
root |
required | section: the tree is a list of sections. content: the tree is anything a column holds (components, containers, layouts), for any column wide enough. |
editable |
structured only | The appearance options editors may still change: look, variant, a control name (space_above) offered by a part in the tree, or order (a layout's phone order, for a pattern with a layout of two or more columns). |
tree |
required | The pattern itself, in the tree shape. |
A content pattern fits only where every preset and component in it fits. Verify works out the narrowest slot it fits (Builder › Parts shows it, as "fits 9+ columns").
Saved patterns
Patterns don't have to start as files. In the page editor, a member whose role has Save
patterns can select a section, or items side by side in a column, and choose Save as
pattern (Editing pages). The pattern is stored in the database
(Builder's variflow_builder_patterns table), not in _sections/, and from then on it's a pattern
like yours:
- It's checked exactly as a pattern file is (the same schema rules, the live token build, fit and depth, parts that exist), and it can't hold HTML: plain text fields hold words, rich text only what the editor's rich text makes.
- The Library offers it in every Builder field that allows it, next to the file patterns, marked
Saved; copies follow its lock; verify checks it (its "file" is
saved:<name>); Builder › Parts lists it with who saved it and when. - Builder › Patterns in the control panel lists the saved patterns with where they're used, and lets members with Save patterns change the label, description, icon and lock, edit the tree in the editor ("Edit tree"), or delete one. A new lock or a new tree is a new version. Super admins choose there which roles have Save patterns.
Name clashes
A pattern's name is unique on the site, file and saved patterns together:
- Saving a pattern in the editor with a file pattern's name is refused ("the file would win").
- If a pattern file appears later with a saved pattern's name (you exported it, or a colleague
added one), the file wins: the saved one isn't used, and verify warns
(
saved_shadowed), naming the file and the saved pattern. Delete the saved one (Builder › Patterns, orexport-pattern --delete-db), or rename it.
Copies on pages find their pattern by its name, so a saved pattern's name can't change once a page uses it.
Exporting a saved pattern
To keep a saved pattern in version control, write it to a file:
php system/ee/eecli.php variflow:builder:export-pattern newsletter
# writes system/user/templates/<site>/_sections/patterns/newsletter.pattern.json
The file is in this format, with the pattern's version, lock, editable options and tree; commit it
and deploy it like your other parts. Verifying parts has the
options (--site, --out, --force, --delete-db) and exit codes. Once the file is in place,
--delete-db (or deleting the saved one) lets the file take over: copies keep working, because the
name is the same.
newsletter_card.pattern.json
{
"name": "newsletter_card",
"label": "Newsletter card",
"description": "A card asking readers to sign up for the letter. Goes in any column.",
"icon": "envelope",
"version": 1,
"lock": "structured",
"root": "content",
"editable": ["look", "variant"],
"tree": [
{
"type": "card",
"variant": "card:raised",
"look": "scheme:brand",
"children": [
{ "type": "heading", "fields": { "eyebrow": "The letter", "text": "One email a month, from the shop", "level": "h3" } },
{ "type": "button", "variant": "button:primary", "fields": { "link": { "url": "/letter", "label": "Get the letter" } } }
]
}
]
}
home_hero.pattern.json
{
"name": "home_hero",
"label": "Home hero",
"description": "The Home page's hero, as signed off.",
"version": 1,
"lock": "locked",
"root": "section",
"tree": [
{
"section": "hero",
"look": "scheme:light",
"appearance": { "space_above": "space.none", "space_below": "space.2xl" },
"layouts": [
{ "preset": "full", "columns": [[{ "type": "heading", "fields": { "text": "Walk slower. Notice more.", "level": "h1" } }]] }
]
}
]
}
Trees
Patterns, and sections' starting layouts, are written in the same shape a Builder page stores (Pages › The tree has all of it):
{"v": 1, "sections": [
{"id": "s1", "section": "hero", "pattern": "home_hero", "lock": "locked", "look": "scheme:dark",
"appearance": {"space_below": "space.2xl"},
"layouts": [{"preset": "full", "columns": [[
{"type": "heading", "fields": {"text": "Gear for the long way round"}},
{"type": "button", "variant": "button:primary", "fields": {"link": {"url": "/shop", "label": "Shop now"}}}
]]}]}
]}
| Node | Keys |
|---|---|
| Section | section (the shell's name) and layouts; optional look, variant, appearance, fields. A page also stores id, and pattern, patternVersion, patternSource and lock on a pattern's copy (detachedFrom on a detached one: Pages). |
| Layout | preset (a grid preset's name) and columns: one list of items per column of the preset. Optional order ("reverse") and id. |
| Component | type (the component's name); optional look, variant, appearance, fields, children for a container, query for a query component's controls. Optional id. |
lookis a scheme reference ("scheme:dark") andvarianta variant reference ("button:outline"); the other appearance options go underappearance, by control name, with a token name as the value ("space.xl"), or a width forcontainer.fieldsholds field values by name, each the right kind for its field.- Sections are top level only. A section holds layouts. A layout has one list per column. A column holds components, containers and further layouts, never a section.
- Layouts nest at most 3 levels deep (a section's own layouts are level 1). Set
$config['variflow_builder_max_depth']inconfig.phpto change it. - Everything must fit: a nested preset needs a slot at least its
minSlotwide, and a component a column at least itsminSpan. A 3-across (minSlot 9 on a 12-column grid) fits in an 8/4's wide column only if the 8 is 9 or more, so it doesn't.
Partials
The partial beside each section and component schema is EE template markup: Builder renders it
with the node's values (Pages › Partials lists every variable). In short:
{vfb:attrs} for the look and variant attributes, {vfb:content} where a section's layouts or a
container's children go, {vfb:field:<name>} for each field ({vfb:field:link:url},
{vfb:field:image:alt}), {vfb:appearance:<control>} for a token control's CSS value
(var(--vf-space-xl)), {vfb:container}, {vfb:narrow}, and in a query component
{vfb:entries}…{/vfb:entries} and {vfb:count}.
<a class="btn" {vfb:attrs} href="{vfb:field:link:url}" data-vfb-field="link">{vfb:field:link:label}</a>
Verify checks that the partial exists, and that:
- every
inlinefield's element carriesdata-vfb-field="<name>"(an error if not), and no other element does (a warning). Builder takes these markers out of the HTML visitors get; - a section's or container's partial has
{vfb:content}, where its layouts or children go (a warning if not).
Previewing in the editor
The editor's canvas shows the entry's real page through EE's Live Preview, rendered with your
partials. In that preview (and only there: never for visitors, never in EE's own Live Preview
without the editor) Builder adds data-vfb-id to every node's element and keeps the
data-vfb-field markers, and the page carries a small script that talks to the editor. When an
editor changes a field or an appearance option, the editor asks the server for just that section's
HTML and swaps the section's element in place.
data-vfb-field="<name>" marks the element that shows an inline field, and makes it editable
on the canvas. Put it on the element that holds only the field's text: the <h2> around
{vfb:field:heading}, the <a> around a link's label, the <img> or its wrapper for an image. Text
fields are edited as plain text, rich text as HTML with a small toolbar, images by double-click.
"preview": "reload" is for parts whose markup a page-level script sets up once (a slider, a
lightbox, a masonry grid) and that would come back from a swap inert. A change anywhere in a section
holding such a part reloads the whole page instead (keeping the scroll position and the
selection). The default is "swap".
{ "name": "gallery", "label": "Gallery", "description": "A slider of photos.", "version": 1, "preview": "reload" }
Partials that preview well:
- One outer element. Builder puts the node's id on it (or on the element with
{vfb:attrs}), so the canvas can outline it, select it and swap it. A partial that starts with text, or has several top-level elements, can't be outlined as a whole. {vfb:attrs}on that outer element, so the look, the variant and the id are in one place.- Markers on simple elements. A
data-vfb-fieldelement that also holds other markup (an icon, another field) still works, but editing in place can only change its text. - An empty optional field isn't on the page when its markup is inside
{if vfb:field:…}. That's right for visitors; editors fill it in from the inspector. - Styles that don't depend on what came before. A swapped section is new markup in the same
place; CSS that targets it by structure keeps working. Scripts that bind to elements once, on
page load, don't see it: use event delegation, or
"preview": "reload". - No IDs that clash. Two copies of a part on one page mean two of every
idin its partial.