Docs /Variflow Builder

Verifying parts

variflow:builder:verify loads a site's parts and checks each one, in two passes:

  1. Structure. Every key known and every value the right type; names unique and matching their files; each section's and component's partial present, with inline fields marked; containers naming real components; pattern and section trees well-formed (sections only at the top, layouts nested at most three deep); no free colours, sizes or fonts.
  2. The live token build, through Variflow Tokens' Integration API: every scheme, token group (and its type), variant group and container exists; defaults are real tokens, schemes and variants; the presets sections name exist; minSpan is within the grid; every preset and component in a tree fits where it sits. Query components' channels and category groups, entries fields' channels and mapped fields, and image fields' upload directories, are checked against the site.

It reads files (and the patterns saved in the editor, which it checks the same way: their "file" is saved:<name>) and writes nothing.

php system/ee/eecli.php variflow:builder:verify [--site=<id|name>] [--json] [--strict]
Option
--site, -s A site's ID or short name. The first site when left out.
--json, -j Print the result as JSON (below).
--strict Fail on warnings as well as errors.

Exit codes

Code
0 The parts are clean (warnings allowed, unless --strict). A site with no _sections/ folder is clean too: there's nothing to check.
1 Problems: at least one error, or with --strict a warning.
2 It can't run: Variflow Tokens isn't installed, its Integration API is older than 3 (Tokens 1.3), the site has no live token build, or there's no such site.

Output

As variflow:verify's: the site and a headline, then errors grouped by code, warnings and notes. Each problem ends with its file (in _sections/) and line.

[default_site] 1 error in 25 parts.
  Error · group_missing (1)
    The live build has no token group space.section. (band.section.json:14)
  Parts: 4 sections, 18 components, 3 patterns in /var/www/html/system/user/templates/default_site/_sections

Warnings are problems that don't stop a part working: a partial with no schema, a file that isn't a part, a data-vfb-field marker on a field that isn't inline, a deprecated token as a default, a narrow layout that can never apply, or a pattern file and a saved pattern with the same name (saved_shadowed: the file wins; Parts).

JSON

--json prints one object:

Key
site, siteId The site checked.
folder Its _sections/ folder (null when it couldn't run).
ok, exitCode, strict The result, as the exit code.
cantRun Why it couldn't run, or null.
summary sections, components, patterns, errors, warnings.
parts Each part that loaded: kind, name, label, description, icon, version, file, partial, fields, appearance, the kind's own keys, and issues (how many). A pattern has source (file or db), and a saved one saved (id, createdBy, createdAt, updatedBy, updatedAt).
issues Each problem: severity (error or warning), code, message, file, line, pointer (the JSON pointer in the file). A problem with the site as a whole (no grid in the build) has no file.
notes Notes, such as a missing folder.

In a deploy

Run it after variflow:build (or variflow:verify), so the parts are checked against the token build you're deploying:

php system/ee/eecli.php variflow:build && php system/ee/eecli.php variflow:builder:verify --strict

Exporting a saved pattern

variflow:builder:export-pattern writes a pattern saved in the editor to a pattern file, so you can commit it (Parts), then checks the file it wrote as verify checks a pattern file.

php system/ee/eecli.php variflow:builder:export-pattern <name> [--site=<id|name>] [--out=<dir>] [--force] [--delete-db]
Option
<name> The saved pattern's name.
--site, -s A site's ID or short name. The first site when left out.
--out, -o Write into this folder instead of the site's _sections/patterns/.
--force, -f Overwrite a file that's there. Without it, an existing file is never touched.
--delete-db After a clean export into the site's own _sections/patterns/, remove the saved pattern: the file takes over. Copies on pages keep working, since they find their pattern by name. Refused with --out somewhere else.

It writes <name>.pattern.json (two-space indents, a final newline) and prints any problems in it, each with its line. Exit codes are verify's:

Code
0 Written, and the file is clean.
1 Written, but the file has problems (the saved pattern names a part or token that's since gone, say): fix the saved pattern and export again. With --delete-db nothing is removed.
2 It can't run: no saved pattern by that name, the file exists (and no --force), the folder can't be written, --delete-db outside the site's patterns folder, or no such site.

Finding where an entry is picked

variflow:builder:usage --entry=<id> lists the Builder pages whose entries fields pick that entry (Parts): before you close or delete an entry, say. It reads the pages' stored trees and writes nothing.

php system/ee/eecli.php variflow:builder:usage --entry=<id> [--site=<id|name>] [--json]
Option
--entry, -e The entry's ID.
--site, -s A site's ID or short name. The first site when left out.
--json, -j Print the result as JSON: site, entry, and uses, each with entry_id and field_id (the page and its Builder field), title, node, field, position (1 for the first pick) and where.
[default_site] Entry 1658 is picked 1 time on 1 page.
  Home › Section 4 › layout 1 (full) › column 1 › Featured stories (entry 1652, stories #436, position 2)

It exits 0 whether or not the entry is picked, and 2 when it can't run (no entry ID, no such site, or Builder isn't installed).