Docs /Variflow Builder

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 .group suffix), 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.json or .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-pattern writes 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 .html partial) and Settings (the .json schema), 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:verify on 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:

  1. its icon, if it's one of the names below;
  2. otherwise the icon for the part's name, if that's one of them (a component called heading gets the heading icon, quote the quote, image the image);
  3. 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 are true and false. The named field's default counts when a node hasn't set it.
  • variflow:builder:verify checks what it names: a field of the same part (show_when_field), listed earlier, so the inspector reads top down; a select or toggle (show_when_type); values that field can have (show_when_value); and one level only: the named field can't have a showWhen of 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 required field 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 writes data-focus only when the shape crops), as it would without showWhen.

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, editable lists in structured patterns, the licence, and Variflow Tokens' usage, renames and remaps cover them.
  • A component that declares its own space_above or space_below control keeps it. Add "spacing": false to a component's schema to leave both out (a divider, a full-bleed band).
  • Another group: $config['variflow_builder_spacing'] = 'size.gap'; in config.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's version when 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-focus only when the shape crops, data-align only 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 entries field, and one with an entries field can't also have a query (or children), so {vfb:entries} always means one list. An entries field on a section shell is refused too.
  • Not inline, and its default is []: 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, or export-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.
  • look is a scheme reference ("scheme:dark") and variant a variant reference ("button:outline"); the other appearance options go under appearance, by control name, with a token name as the value ("space.xl"), or a width for container.
  • fields holds 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'] in config.php to change it.
  • Everything must fit: a nested preset needs a slot at least its minSlot wide, and a component a column at least its minSpan. 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 inline field's element carries data-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-field element 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 id in its partial.