Variables

Variables are reusable values referenced in content as {{key}} and substituted on read (in getBlockTree and getPublishedContent, unless raw: true). Methods live under cms.api.variables and are mirrored on the client as client.variables.<method> with identical types.

A key is alphanumeric plus underscores. Updating a variable's value revalidates the published roots that use it. Deleting one that is in use throws VARIABLE_IN_USE.

Reference a variable in any string property, for example { title: 'Hello {{siteName}}' }. An unknown key is left literal.

Client-side substitution

The {{key}} helpers the server uses on read are exported as pure functions, so an editor can preview substitution from a variables map it already loaded (for example from variables.list) without another request. Import them from @createcms/core on the server and from @createcms/core/react in the browser.

import { extractVariableKeys, resolveTemplateString } from '@createcms/core/react';

const { variables } = await client.variables.list();
const vars = new Map(variables.map((v) => [v.key, v.value]));
resolveTemplateString('Hello {{siteName}}', vars); // 'Hello Acme'
extractVariableKeys('{{a}} and {{b}}'); // ['a', 'b']

VAR_PATTERN (the {{key}} regex, global) is exported as well; reset its lastIndex before a manual exec or test, or use extractVariableKeys.

Methods

List Variables

List every variable, ordered by key, so you can browse or search what's defined. All query fields are optional — call it with no arguments to page through everything from the top.

const data = await cms.api.variables.list({
  query: { search: 'site', limit: 20 },
});

const { data, error } = await client.variables.list({
  query: { search: 'site', limit: 20 },
});

Get a Variable

Fetch a single variable by its key, and find out in the same call whether it's currently referenced anywhere. Throws VARIABLE_NOT_FOUND if no variable has that key.

const data = await cms.api.variables.getVariable({
  query: { key: 'siteName' }, // required
});

const { data, error } = await client.variables.getVariable({
  query: { key: 'siteName' }, // required
});

Create a Variable

Create a new variable with a unique key. You get back the created variable, including its generated id and timestamps. A duplicate key throws VARIABLE_KEY_EXISTS.

const data = await cms.api.variables.createVariable({
  body: {
    key: 'siteName', // required
    value: 'Acme', // required
    description: 'Public site name',
  },
});

const { data, error } = await client.variables.createVariable({
  body: {
    key: 'siteName', // required
    value: 'Acme', // required
    description: 'Public site name',
  },
});

Update a Variable

Update a variable's value and/or description. Changing the value revalidates every published root that references it, so the new value goes live automatically.

const data = await cms.api.variables.updateVariable({
  body: {
    key: 'siteName', // required
    value: 'Acme Corp',
  },
});

const { data, error } = await client.variables.updateVariable({
  body: {
    key: 'siteName', // required
    value: 'Acme Corp',
  },
});

Delete a Variable

Delete a variable by key. It fails with VARIABLE_IN_USE if the variable is still referenced in any live content or template, so you can't leave a dangling {{key}} behind.

const data = await cms.api.variables.deleteVariable({
  body: { key: 'siteName' }, // required
});

const { data, error } = await client.variables.deleteVariable({
  body: { key: 'siteName' }, // required
});

List Variable Usages

Find every place a variable is referenced before you change or delete it: the distinct live block usages in branch heads and the template usages, each with a total count.

const data = await cms.api.variables.getVariableUsages({
  query: { key: 'siteName' }, // required
});

const { data, error } = await client.variables.getVariableUsages({
  query: { key: 'siteName' }, // required
});