Docs /Variflow Builder

Overview

Variflow Builder is a page builder for ExpressionEngine 7 from Bison Digital. Editors compose pages from parts you write as files in the site's repo (section shells, components and patterns), and every design choice they make is one of the site's design tokens: a scheme, a step from a token group, a component variant. There are no free colours, sizes or fonts.

Builder needs Variflow Tokens 1.3 or later, which supplies the tokens, the page grid and layout presets, and component variants. Builder reads them only through Tokens' Integration API.

1.0.0 defines the parts, checks them, renders pages from them, and gives editors the full visual editor: the live canvas, Plan, drag and drop, saved patterns and publish checks.

What's in 1.0

  • The parts format: JSON schemas with an EE partial each, in system/user/templates/<site>/_sections/.
  • variflow:builder:verify: checks every part against its schema rules and the live token build, reporting each problem with its file and line. Use it in deploy scripts.
  • Builder › Parts in the control panel: every section, component and pattern with its fields, appearance options and problems, and a Verify button. Sections and components can be edited there too: template and settings in EE's code editor, checked before they're saved, with revisions.
  • The Variflow Builder field and its template tag (Pages): an entry's page, stored as a tree of your parts (never HTML), checked when it's saved and rendered with your partials. Variflow Tokens' usage, build guard, renames, remaps and Undo cover the token references in it.
  • The page editor (Editing pages): full screen over the publish form, with a Library of what fits and of your design tokens, the live page in the centre (your templates through EE's Live Preview, on desktop, tablet and phone, with selection, editing in place and a grid overlay) or Plan (the page as an outline you drag items and tokens around in), and an inspector with Variflow Tokens' pickers. Locked pattern copies offer only what their lock allows. Everything works from the keyboard; EE's own Save saves the page.
  • Saved patterns (Parts, Editing pages): members with Save patterns save a section, or items in a column, as a pattern from the editor; Builder › Patterns manages them; variflow:builder:export-pattern writes one to a file for version control (Verifying parts). Where a field allows it, editors can detach a locked copy.

Requirements

  • ExpressionEngine 7.3 or later, PHP 8.2 or later.
  • Variflow Tokens 1.3 or later, installed (with its own update run), with a live build that has a grid (for layouts). Builder refuses to install without it and says why.

Installing

  1. Copy system/user/addons/variflow_builder into your site.
  2. In the control panel, Add-Ons › Variflow Builder › Install (or php system/ee/eecli.php addons:install -a variflow_builder).

Then follow Getting started.

Updating: copy the new system/user/addons/variflow_builder and themes/user/variflow_builder over the old ones, then Add-Ons › Variflow Builder › Update (or addons:update -a variflow_builder). Pages and parts need no changes.

Four config.php settings are for developers: $config['variflow_builder_json_editor'] = 'y' adds Edit JSON to the page editor; $config['variflow_builder_save_with_problems'] = 'y' makes every Builder field save pages with content problems (and warn) instead of refusing them, for development sites (Pages); and $config['variflow_builder_cp_editing'] = 'n' turns off editing parts in the control panel, for a server whose parts are deployed from version control (Parts); and $config['variflow_builder_spacing'] names the token group behind every component's Space above and Space below (space by default, 'n' for none: Parts).

Getting started

  1. Parts. Write your first parts in system/user/templates/<site>/_sections/ (Parts): a section shell, a component or two, and a section pattern to start pages from. Run php system/ee/eecli.php variflow:builder:verify until it's clean.
  2. The field. Add a Variflow Builder field to a channel (Pages), and give an entry a page: Launch Variflow Page Builder in the publish form (Editing pages).
  3. The template tag. Output {my_field} in the entry's template, with {exp:variflow:css} and {exp:variflow:layout_css} in the <head> (Pages).
  4. Your CSS. Style the parts with your own CSS or a framework: Tailwind, Bootstrap and others (Bring your own CSS).

Uninstalling removes only Builder's own records; Builder fields keep their data, and your part files stay where they are. EE asks first, naming the fields that use the fieldtype (the command line doesn't ask). While Builder's files are on the server, EE still renders those fields' pages. Before you delete the files, delete the Builder fields or take their tags out of your templates: EE shows an error page for any template that outputs a field whose fieldtype file is missing. Builder's one table, the patterns saved in the editor, is dropped too, unless pages still hold copies of saved patterns: then it stays, so those copies keep their pattern if Builder is installed again. Export any you want to keep first.

Licensing

One licence covers one production site, plus any number of development and staging copies of it. Variflow Tokens needs its own licence. Buy Builder in the ExpressionEngine store, then add its key in Add-Ons › Licences (EE checks it automatically; the status refreshes the next time someone loads a control panel page).

A 14-day trial. On a production site without a valid licence, everything works for 14 days, counted from the first time Builder sees the problem (a new site, or a renewal that lapsed; adding a key resets it). Builder's trial is its own, separate from Tokens'. Members who can act on it (super admins, and roles with access to Builder) see a banner on Builder's pages and in the page editor counting down the days; they can dismiss it for the browser session. Each Builder field's settings show the licence's state too.

After the trial, page layout locks until a licence is added: every section behaves like a locked pattern copy of itself. Editors see one notice in the page editor ("Builder's licence has lapsed, so page layout is locked. Text and images can still be edited.").

Always works Stops after the trial, without a licence
Front-end pages, template tags, Live Preview Adding, moving, duplicating or removing sections, layouts, columns and components (the Library, the start prompt, drag and drop)
Editing and saving text, links, images, picked entries and query options Changing presets, column widths and phone order
Every control panel page, variflow:builder:verify, variflow:builder:usage Changing looks, variants, appearance and tokens
Detaching a copy, Save as pattern, Builder › Patterns edits, variflow:builder:export-pattern
Editing, creating and deleting parts on Builder › Parts (they can still be read there)

The server decides, not the editor: a save that changes anything but field values is refused (license_lapsed), whatever the field's When the page has problems setting. A page that already has a saved layout always saves when only its words and images change.

Only EE's statuses that name Builder as unlicensed (invalid, expired) count. EE's own licence messages about your ExpressionEngine installation (such as update_available or license_expired) never count against Builder, and neither does "no status" (na).

Development hosts are always treated as licensed: localhost, 127.0.0.1, *.test, *.local, *.localhost, *.ddev.site, *.lndo.site, and any you add in config.php:

$config['variflow_builder_dev_domains'] = ['staging.example.com'];  // and its subdomains
$config['variflow_dev_domains'] = ['staging.example.com'];          // Variflow Tokens' list counts too
$config['bison_dev_domains'] = ['*.preview.example.com'];           // shared by Bison Digital add-ons

To see what an unlicensed site gets on a development host, set $config['variflow_builder_simulate_license'] = 'grace'; (the trial's banner) or 'lapsed' (after the trial). It can only take a licence away, never grant one.

The full terms are in LICENSE.md. The page editor uses Lit (LICENSE-lit.txt).

Support