Callbacks

The Topol Plugin provides a powerful and flexible callback system that allows you to integrate seamlessly with your own application logic. This system enables event-driven communication from the editor (“callbacks up”) while your settings and configuration are passed into the editor (“props down”).

By defining a set of callback functions inside the TOPOL_OPTIONS object, you can respond to editor events such as save actions, file uploads, test email sends, undo/redo changes, and even error states.

All callbacks are optional, and you can include only the ones you need. Together, they give you full programmatic control over how your application responds to editor activity.

How to use Callbacks

Callbacks are defined inside the TOPOL_OPTIONS configuration like this:

const TOPOL_OPTIONS = {
  // other options...
  callbacks: {
    onSave(json, html) {
      // Handle save logic
    },
    onInit(json, html) {
      // Handle editor initialization
    },
    // more callbacks...
  },
};

Available Callbacks and their Usage

()

Triggered when the Save button is clicked or when TopolPlugin.save() is called manually.

Use this to save the template data (json) and its HTML output (html) to your backend or local storage.

const TOPOL_OPTIONS = {
  callbacks: {
    onSave(json, html) {
      // save json and html to your infrastructure
    },
  },
};

()

Called when the Save and Close button is clicked in the editor Top Bar.

Use this for saving and then exiting the editor or redirecting the user.

const TOPOL_OPTIONS = {
  callbacks: {
    onSaveAndClose(json, html) {
      // save json and html to your infrastructure and close the editor
    },
  },
};

()

Fires when a user sends a test email from the preview screen.

When testingEmails is set to true, the email parameter will always be an array of emails.

You can use this callback to send test emails using your own service (e.g., SendGrid, Mailgun, custom SMTP).

const TOPOL_OPTIONS = {
  callbacks: {
    onTestSend(email, json, html) {
      // send a test email using your preferred sender
    },
  },
};

()

Called when a user clicks “Choose a file” inside image or video properties.

Use this to trigger your custom file manager UI. You can read more about the feature here.

const TOPOL_OPTIONS = {
  callbacks: {
    onOpenFileManager() {
      // open your custom filemanager dialog window
    },
  },
};

()

Executed when the editor is fully initialized.

Commonly used to hide loading spinners or initialize user tracking once the editor is ready.

const TOPOL_OPTIONS = {
  callbacks: {
    onInit(json, html) {
      // hide the loader or track the usage
    },
  },
};

()

Fires after calling TopolPlugin.load(YOUR_TEMPLATE) and the template is fully rendered.

const TOPOL_OPTIONS = {
  callbacks: {
    onLoaded(json, html) {
      // hide the loader
    },
  },
};

()

Triggered when a user saves a content block to their personal library.

Use this to store the block definition on your own infrastructure. You can read more here.

const TOPOL_OPTIONS = {
  callbacks: {
    onBlockSave(block) {
      // save the block on your infrastructure
    },
  },
};

()

Fires when a user removes a saved block. You can read more here.

const TOPOL_OPTIONS = {
  callbacks: {
    onBlockRemove(blockId) {
      // remove the block on your infrastructure
    },
  },
};

()

Called when a user edits an existing saved block. You can read more here.

const TOPOL_OPTIONS = {
  callbacks: {
    onBlockEdit(blockId) {
      // edit the block on your infrastructure
    },
  },
};

()

Fired when the Undo button is used. count indicates how many steps have been undone.

const TOPOL_OPTIONS = {
  callbacks: {
    onUndoChange(count) {
      // ...
    },
  },
};

()

Fired when the Redo button is clicked. count shows the number of steps redone.

const TOPOL_OPTIONS = {
  callbacks: {
    onRedoChange(count) {
      // ...
    },
  },
};

()

Called when the user enters the Preview mode.

const TOPOL_OPTIONS = {
  callbacks: {
    onPreview(html) {
      // ...
    },
  },
};

()

If built-in notifications are disabled using disableAlerts: true, then this callback allows you to replace them with your own alert system.

You read more about the custom alerts here.

const TOPOL_OPTIONS = {
  callbacks: {
    onAlert(notification) {
      //use your own notification, or create proxy for built-in notifications
    },
  },
};

()

Fires when the editor encounters an unrecoverable error. Useful for diagnostics and fallbacks.

There are 3 types of errros:

• templateLoad - Indicates that the JSON of the template is not correct and editor cannot read it correctly.
• network - Indicates that network issue happened during internal or external (endpoints given in API property in TOPOL_OPTIONS) Fetch/XHR calls.
• authorize - Invalid API key or wrong/unverified domain

const TOPOL_OPTIONS = {
  callbacks: {
    onError(type, message) {
      if (type === "network") { // templateLoad | network | authorize
        console.log("Network issue: " + message);
      }
    },
  },
};