Templates

A template is a default value for a block property in a given collection and block type. Template strings can contain {{key}} variables, resolved when applied. Templates are keyed by (collection, blockType, propertyKey). Methods live under cms.api.templates and mirror on the client as client.templates.<method> with identical types.

Templates are not versioned content, so these methods do not return a commit envelope. A template can only target a text property (string or richText); pointing one at any other property type throws TEMPLATE_PROPERTY_INVALID.

Methods

List Templates

List every template, ordered by collection then block type, so you can see which block properties already have defaults. Narrow the results by collection, block type, or a case-insensitive substring of the template string, and page through with limit/offset. Every filter is optional.

const data = await cms.api.templates.list({
  query: { collection: 'pages', blockType: 'hero', limit: 20 },
});

const { data, error } = await client.templates.list({
  query: { collection: 'pages', blockType: 'hero', limit: 20 },
});

Get a Template

Fetch a single template by id, so you can inspect its string, description, and which property it targets. Throws TEMPLATE_NOT_FOUND if no template with that id exists.

const data = await cms.api.templates.getTemplate({
  query: { templateId: 'tpl_abc123' }, // required
});

const { data, error } = await client.templates.getTemplate({
  query: { templateId: 'tpl_abc123' }, // required
});

Get Resolved Defaults

Resolve the default values for every template on a collection and block type, with {{key}} variables already substituted, so you can seed a new block's properties. You get back a defaults map from propertyKey to its resolved string; it is empty when the pair has no templates.

const data = await cms.api.templates.getTemplateDefaults({
  query: { collection: 'pages', blockType: 'hero' }, // both required
});

const { data, error } = await client.templates.getTemplateDefaults({
  query: { collection: 'pages', blockType: 'hero' }, // both required
});

Resolve a Template String

Resolve an arbitrary template string against your current variables, substituting {{key}} placeholders with their stored values. Unknown placeholders are left literal, so you can preview exactly what a template will render to.

const data = await cms.api.templates.resolveTemplate({
  query: { template: 'Welcome to {{siteName}}' }, // required
});

const { data, error } = await client.templates.resolveTemplate({
  query: { template: 'Welcome to {{siteName}}' }, // required
});

Create a Template

Create a template for a (collection, blockType, propertyKey) triple; you get back the new record, and its {{key}} variable usages are tracked for you. The target property must be a string or richText property — pointing at any other type throws TEMPLATE_PROPERTY_INVALID — and a duplicate triple throws TEMPLATE_KEY_EXISTS.

const data = await cms.api.templates.createTemplate({
  body: {
    collection: 'pages', // required
    blockType: 'hero', // required
    propertyKey: 'title', // required
    template: 'Welcome to {{siteName}}', // required
  },
});

const { data, error } = await client.templates.createTemplate({
  body: {
    collection: 'pages', // required
    blockType: 'hero', // required
    propertyKey: 'title', // required
    template: 'Welcome to {{siteName}}', // required
  },
});

Update a Template

Update a template's string and/or description; omitted fields keep their current value, and changing the string re-syncs its tracked variable usages. Throws TEMPLATE_NOT_FOUND if the template does not exist.

const data = await cms.api.templates.updateTemplate({
  body: {
    templateId: 'tpl_abc123', // required
    template: 'Updated {{siteName}} content',
  },
});

const { data, error } = await client.templates.updateTemplate({
  body: {
    templateId: 'tpl_abc123', // required
    template: 'Updated {{siteName}} content',
  },
});

Delete a Template

Delete a template by id. You get back the id you deleted; throws TEMPLATE_NOT_FOUND if it does not exist.

const data = await cms.api.templates.deleteTemplate({
  body: { templateId: 'tpl_abc123' }, // required
});

const { data, error } = await client.templates.deleteTemplate({
  body: { templateId: 'tpl_abc123' }, // required
});