Programmatic Template Updates

updateTemplate replaces the entire template in a running editor, which suits pushing changes in from your application without the user acting.

Overview

Unlike load, which is used when the editor first opens, updateTemplate is built for runtime updates while the editor is active. It automatically:

• Normalizes the template against Topol's schema
• Creates an undo snapshot (configurable)
• Marks the template as edited

Basic usage

// Update template with a template object
window.TopolPlugin.updateTemplate(templateJson);

// Update template from a JSON string
window.TopolPlugin.updateTemplate(JSON.stringify(templateJson));

Options

The updateTemplate function accepts an optional second parameter for configuration:

interface IUpdateTemplateOptions {
  skipSnapshot?: boolean;
}

Option	Type	Default	Description
skipSnapshot	boolean	false	When true, skips creating an undo snapshot before updating

Examples

Standard update (with undo support)

By default, updateTemplate creates an undo snapshot before replacing the template. This allows users to undo the programmatic change:

// User can undo this change
window.TopolPlugin.updateTemplate(newTemplate);

The undo history holds the ten most recent snapshots, and taking a new one clears anything waiting to be redone.

Update without undo snapshot

If you don't want the update to be undoable (e.g., when syncing with external state), use the skipSnapshot option:

// User cannot undo this change
window.TopolPlugin.updateTemplate(newTemplate, { skipSnapshot: true });

Updating from external source

A common use case is updating the template based on external events:

// Listen for external template updates
socket.on("templateUpdate", (templateData) => {
  window.TopolPlugin.updateTemplate(templateData, { skipSnapshot: true });
});

Template format

Direct template object:

const template = {
  tagName: "mj-global-style",
  attributes: {
    /* ... */
  },
  children: [
    /* ... */
  ],
  // ...
};

window.TopolPlugin.updateTemplate(template);

Wrapped format, which also refreshes the block's feed data:

window.TopolPlugin.updateTemplate({
  template: templateJson,
  feeds: [],
  datafeeds: [],
});

Callbacks

onTemplateUpdated

Called with no arguments when the template is successfully updated:

const TOPOL_OPTIONS = {
  callbacks: {
    onTemplateUpdated() {
      console.log("Template was updated programmatically");
    },
  },
};

onError

Called with the type updateTemplate when a template passed as a string cannot be parsed as JSON. For full documentation on the onError callback, see Callbacks.

const TOPOL_OPTIONS = {
  callbacks: {
    onError(type, message, responseBody) {
      if (type === "updateTemplate") {
        console.error("Failed to update template:", message);
      }
    },
  },
};

responseBody stays undefined for this error type, since there is no server response involved.

Error handling

When a JSON string cannot be parsed:

1. The onError callback is triggered with type updateTemplate
2. A notification is shown to the user
3. The current template remains unchanged

A template that parses but does not match the schema is treated differently. Rather than being rejected, it is normalized: values that fail validation are replaced with valid ones and the update proceeds. Pass a well-formed template if you need the result to match your input exactly.