Docs /Variflow Tokens

Changing tokens

Entries store token names. Change a name in the token file and every entry that stores it would break, so Variflow changes names in two steps: first the token file, then (if you want) the stored data. At no point does content point at a name the live build can't resolve.

The control panel never writes your token file. Rename and Deprecate record what you asked for and give you the exact patch to commit. The change happens when a build from the updated file goes live.

Renaming a token

Open the token (Add-Ons › Variflow Tokens, click its label) and choose Rename…. The window shows:

  • Impact: stored references, entries, fields and channels, and the tokens that alias this one. Below it, the pickers whose settings name the token ("Picker settings that name it: 1 field setting, 4 Bloqs atoms"): see Pickers follow the change.
  • The new name: checked as you type (valid, not taken, no clash with another token's CSS name).
  • Stored entry data: what happens to content (below).
  • The patch: "Commit this to <file>", the diff, and Copy patch.

The patch moves the token to its new name, keeps the old name under $extensions.variflow.renames, and updates every reference to it in the file. Commit it, then build.

Stored data What happens
Alias only (the default) Entries keep the old name, which resolves to the new token. Nothing in your content changes.
Also rewrite stored entry data, after the next build Queued. Once a build with the new name is live, entries are rewritten to the new name.

Deprecating a token

Deprecate… adds $deprecated (with the replacement, if you pick one) to the token.

  • Editors stop being offered the token. Entries that already use it keep rendering it, and editors see it marked as being retired, with Switch to … when there's a replacement.
  • Also swap stored values to the replacement: changes those entries straight away, because the replacement already exists.

Rename and Deprecate need a super admin on a licensed site (or during the 14-day trial: see Licensing).

Pending and queued changes

Every change shows on the token's page and under Builds › Queued changes until it settles:

Status Means
Pending Waiting for the token file to contain the change
Queued A rename whose stored data is rewritten once the new name is live
Done Settled
Cancelled Stopped before it ran
Failed The rewrite hit an error; the note says why, and Retry runs it again

A token can have one open change at a time. Cancel a pending or queued one from its page or from Builds.

Pickers follow the change

A Tokens field, Grid column or Bloqs atom can list its tokens by name (Only these tokens) and name a Default. When a change rewrites stored data, those settings change with it, so the picker keeps offering the token the content now holds:

  • Which changes: a rename with rewrite, a deprecate with swap, and a remap. A rename that's alias only, or a deprecation that keeps values, leaves settings alone, just as it leaves content alone.
  • What changes: the old name in the explicit list becomes the new one, in the same place (it isn't listed twice if the new name was there already), and a default equal to the old name becomes the new one. Scheme pickers, and the tier, type and group filters, are never changed.
  • When: in the same run as the content, so a queued rename's settings change when its rewrite runs. The result note says how many ("Picker settings updated: 1 field setting, 8 Bloqs atoms.").

Filters that leave the token out. A picker with no explicit list that filters by tier, type or group can stop offering the token: the old name passed the filter and the new one doesn't. Its filter isn't changed. The window (in the patch box) and the run's result warn instead, e.g. "Field "Accent" filters by group color.brand; color.action.accent is outside it.", so you can widen the filter in the field's settings.

When rewrites run

After every publish (a build or a rollback), Variflow checks the site's open changes against the new live build, and runs a queued rewrite once the new name is live:

  • Where it looks: stored values exactly equal to the old name, in fields, Grid columns, Fluid fields and Bloqs atoms (draft blocks too). Nothing else in an entry is touched.
  • Batches: entries are written 50 at a time, each batch in its own transaction.
  • Safe to repeat: every write checks the value is still the old name, so an interrupted rewrite can simply run again.
  • Revisions: each changed entry gets a revision where the channel keeps revisions. The window names channels that don't, before you queue anything.
  • Failures: a rewrite that fails never fails the build, because the build is already published.

On the command line, variflow:rewrite:run does the same and says what's still waiting.

Bloqs, picker settings and Undo

ExpressionEngine's entry revisions don't include Bloqs blocks or field settings, so they can't undo those. Instead, Variflow records every Bloqs atom and every picker setting a rename, deprecate-and-swap or remap rewrites, with its old and new value.

To put them back, open Builds, find the change under Queued changes, and click Undo. Each Bloqs atom that still holds the new name goes back to the old one, and each picker whose list and default are still what the change wrote gets its old ones back. Anything an editor has changed since is left as it is, and the message says how many.

Undo doesn't touch channel fields: restore those from the entry's revisions as usual. An entry whose only change was in Bloqs doesn't get a revision, since it wouldn't hold that change.

Remapping removed tokens

If a new token file removes tokens that content still uses, the build fails and says so. Click Remap usage… on the failure banner:

  1. Pick a replacement for each removed token: one that's in both the live build and the new file.
  2. Apply. Stored values move to the replacements now, while the old build is still live.
  3. Rebuild. The removal now passes.

Each row also says which picker settings name the removed token: the remap updates them too (see Pickers follow the change), and warns under the replacement when a filter would leave it out.

A name neither build has. Content can store a name the live build doesn't have as a token either: a reference that was already broken, or an old name the live build only resolves through a rename. Its type is unknown, so the replacement can be any token that's in both builds, and isn't deprecated in the new file. The list starts with the tokens nearest the old name (color.brand.*, then color.*), then the rest grouped by type. The screen notes "Neither build has this token, so its type is unknown: check the replacement suits where it's used", and there's no colour difference to show.

Remap needs a super admin, and never a licence: it's how a stuck deploy gets unstuck.

Related