Variables

A variable is a named value you set once and reference from many places in your content. You write {{key}} in any string property, and the CMS substitutes the variable's current value when content is read.

How substitution works

Variables are resolved on read, not on write. getBlockTree and getPublishedContent replace every {{key}} in string properties with the variable's value; pass raw: true to skip substitution and see the literal template. An unknown key is left as-is.

// stored:    { title: 'Welcome to {{siteName}}' }
// variable:  siteName = 'Acme'
// read:      { title: 'Welcome to Acme' }

Editing safely

Because a value is shared, changing it updates every entry that uses it. Updating a variable's value automatically revalidates the published entries that reference it. A variable that is still in use cannot be deleted (VARIABLE_IN_USE); getVariableUsages shows where it is used.

Scoping (i18n / multi-tenant)

With the scoping plugins, variables follow the same model as content:

• multi-tenant — variables are partitioned per tenant. Each tenant has its own companyName/siteUrl/…; the same key is independent across tenants, and content resolves the active tenant's value.
• i18n — variables are per language with fallback, exactly like a translated entry. A value is resolved in the active language; if it has no value there, it falls back through the configured chain to the default language. So you define shared values once (in the default language) and only override the few that need translating.

// companyName: only defined in the default language 'en' = 'Acme'
// cta:         'en' = 'Buy now', 'de' = 'Jetzt kaufen'
// reading a German page:
//   {{companyName}} → 'Acme'          (fell back to en)
//   {{cta}}         → 'Jetzt kaufen'  (de override)

Managing variables (create/list/update/delete) always targets the exact active cell (tenant + language) — there is no fallback when editing, so in German you manage German values. Uniqueness is per (tenant, language, key).

Relationship to templates

Templates are default property values that can themselves contain {{variables}}, so a new block can start with a value like © {{companyName}} already filled in. A template's variables resolve through the same scope (tenant + language fallback) when the block is read.