Subscribe to specific Entity/Action pairs to capture print job identifiers and trigger immediate reactions when users interact with the Editor.

Events are the primary way your website "hears" what the user is doing inside the Editor in real-time.

Introduction

The TronDesigner integration script emits structured events whenever significant actions occur within the Editor — such as creating a print job or modifying design elements.

To listen for these actions, you use the subscribeDesignerEvent method. These client-side subscriptions allow your application to react instantly to user behavior without waiting for a page reload.

Use these Event Subscriptions to:

• Capture Identifiers: Get the printJobGuid immediately upon design completion.

• Sync Systems: Send design IDs to your backend to link them with your system.

• UI Feedback: Trigger local reactions, such as showing "Success" notifications, updating price displays, or closing the Editor modal.

⚠️ Choose the right tool for the job:

• For guaranteed delivery: Use Webhooks for server-to-server callbacks (even if the user closes their browser).

• For deep data access: Use the REST API to fetch full binary files (PDFs/PNGs) or complex data models using the ID captured via events.

Core Event Structure

When the Editor is integrated via the Web Integration Script, it exposes events through the window.tronDesigner instance. Each event uses a decoupled Entity/Action model, ensuring that the notifications are structured and predictable.

Event Object Fields

Each event handler receives a strongly typed payload (the event object) that contains the necessary identifiers and the complete data model.

Managing Subscriptions

It is crucial to manage and clean up your listeners to prevent memory leaks or unwanted side effects, especially in Single Page Applications (SPAs).

Subscribing

Unlike standard browser events that clutter the global window object, TronDesigner events are managed directly through the integration instance. This encapsulated approach provides precise control over the specific data entities and actions your application monitors.

Method: subscribeDesignerEvent(entityType, eventType, callback)

• Registers a new subscription (event handler) to listen for a specific action on a specific entity (e.g. 'printJob' 'created').

Example
HTML
Copy
// Example: Subscribing to Print Job creation
integration.subscribeDesignerEvent(
    'printJob',   // entityType
    'created',    // eventType
    (event) => {
        // 'event' matches the DesignerEntityEvent interface
        console.log("Print Job Created:", event.data); // accessing the DTO
    }
);

Unsubscribing

Properly removing listeners ensures your application remains performant and avoids duplicate logic execution.

1. Unsubscribing a Single Callback: Use unsubscribeDesignerEvent(callback) to remove a specific event handler function from its subscription. This requires referencing the exact function that was initially passed to the subscription method.

2. Unsubscribing by Entity/Event Type: Use unsubscribeDesignerEvents to clear multiple handlers simultaneously. You can choose to clear all handlers for a specific combination, or omit the parameters to clear everything:

   • unsubscribeDesignerEvents(entityType, eventType): Unsubscribes all handlers for the specified entity and event type (e.g., all callbacks listening for 'logo' 'updated').

   • unsubscribeDesignerEvents(): Unsubscribes all event handlers of any type and entity.

For a complete, working code example and demonstration of the available combinations, please refer to our Integration Sandbox Environment: Using Designer Events.

Event Catalog

The Editor uses a decoupled approach to event handling. To register a subscription, you must specify both the Entity Type and the Event Type.

The following table lists the most common subscription targets and the conditions that trigger them:

Event payload

Every event delivers a structured object containing the data relevant to that specific action. This payload provides the essential identifiers needed to sync the design with your internal database.

The event object is strongly typed (e.g., DesignerEntityEvent<IPrintJobDTO>) and provides essential data points to identify the resulting entity and user context.

Typical Data Received: When subscribing to a 'printJob' event, the following key fields are typically available on the received event object:

• entityGuid: The primary unique identifier (representing the printJobGuid) that you will use to interact with the REST API.

• customProperties: Any metadata (key/value pairs) that your application passed into the Editor Arguments during initialization.

• customer: The customer identity context (if the user was configured during initialization).

• result: Optional information about how the user finished the editor (e.g., confirmed, canceled, or specific outcomes defined by your configuration).

Typical payload for a 'printJob' subscription (Type: DesignerEntityEvent<IPrintJobDTO>):

Example
HTML
Copy
integration.subscribeDesignerEvent(
  'printJob',  // entityType
  'created',   // eventType
  (event) => {
    // Properties are destructured directly from the 'event' object, 
    const {
      printJobGuid,
      customProperties,
      customer,
      result
    } = event; 

    // Example: send GUID and cart reference to backend
    fetch("/api/cart/attach-print-job", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        printJobGuid,
        // Safely access the custom property
        cartLineId: customProperties?.cartLineId 
      })
    });
  }
);

Implementation Example

Handling printJobCreated

The most common use for events is capturing the printJobGuid the moment a user finishes their design. Below are the two ways to implement this logic.

JavaScript API (Recommended). Use this approach if you are using the JS Builder or an SPA. It allows you to keep your logic encapsulated within your application's design flow.

HTML Data Attributes (Callback). Use this approach if you prefer a "low-code" integration. You define a global function in your <head> and link it to the script via a data attribute.

Example
JS
HTML Attribute
Copy
window.tronDesigner.subscribeDesignerEvent("printJob", "created", (event) => {
  const data = event.detail;

  // Always present
  const printJobGuid = data.printJobGuid;

  // Optional, if you passed them in editor arguments
  const customProps = data.customProperties || {};
  const orderCode = data.customer?.orderCode;

  // 1) Store the GUID in your system (order line, quote item, etc.)
  savePrintJobLinkToCart(printJobGuid, customProps, orderCode);

  // 2) Optionally redirect or update UI
  // (You can also drive your own redirect instead of using editor.result.redirectUrl)
});

Common use cases

Webshop / Front-End Integration

This is the standard flow for customer-facing customization. The front-end needs to link the finalized design to the shopping cart or order immediately.

• Trigger: The user completes a design and confirms the creation of a new print job.

• Signal: The printJob 'created' event fires, delivering the printJobGuid.

• Subscription: integration.subscribeDesignerEvent('printJob', 'created', ...)

• Action: Your front-end captures the printJobGuid and sends it to your backend API to update the corresponding cart line or order item.

Admin / Back-Office UI

Use event subscriptions to keep internal tools synchronized with actions happening inside the Editor (e.g., when an admin or designer saves a job).

• Refresh Panel: Subscribe to the printJob 'updated' event to automatically refresh a Print Job detail panel when changes are saved in the Editor.

  • Subscription: integration.subscribeDesignerEvent('printJob', 'updated', ...)

• Workflow Control: Use the proofreading entity events to track when a design has been reviewed or flagged for changes, allowing your UI to update workflow statuses (e.g., "Pending Approval" to "Approved") instantly.

  • Subscription: integration.subscribeDesignerEvent('proofreading', 'updated', ...)

Integration with REST API

The primary purpose of receiving a printJobGuid in the event payload is to enable subsequent calls to your secure backend or the TronDesigner REST API for heavy lifting tasks.

Receiving a GUID allows your system to perform heavy-lifting tasks via the TronDesigner REST API, such as:

• Asset Retrieval: Automatically fetching high-resolution assets (e.g., calling get preview image, get proof PDF).

• Detail Inspection: Validating the final configuration data (e.g., checking print positions, technologies, selected colors, and dimensions).

Warning: Keep in mind

⚠️ Client-Side Reliability. Since JavaScript events are triggered by user actions within the browser, they are subject to the lifecycle of the user's browser tab.

• Speed Matters: Ensure your event handling logic (specifically saving the ID to your database) is fast and efficient. If your processing takes too long and the user closes the tab or navigates away immediately after clicking "Save," the browser execution may be interrupted before your script finishes.

• User Intent: Generally, if a user closes the tab before your script finishes, they are likely abandoning the session entirely.

• Guaranteed Delivery: For critical data persistence, we recommend using Webhooks as a secondary server-to-server backup. This ensures no printJobGuid is lost even if the user's browser window is closed unexpectedly.

Next Steps

To further refine your integration, explore the following resources:

• Integration Recipes – Explore end-to-end examples.

• Webhooks – Configure server-to-server notifications.

• REST API – Learn how to use the printJobGuid to query design details.