Articles on: Developer

Integrating the Embedded Editor: Capturing Template Events with PostMessage

We're excited to introduce a powerful new capability for the Embedded Document Template Editor! You can now achieve tighter integration and greater control over the template editing lifecycle by listening to editor events directly within your host application using the JavaScript postMessage API.

This feature is essential for developers looking to create a seamless, integrated experience when embedding our template editor in an Iframe. By capturing events like template saves and loads, you can trigger custom actions, update your UI, or manage application state.

How It Works: The `postMessage` Integration

When you embed the PDF Generator API template editor within an Iframe, the editor can now communicate status updates back to its parent window (your application) via postMessage.

Key Template Editor Events

We currently support the following essential events, which are crucial for maintaining synchronicity between the embedded editor and your application:

Event Name	Description	Triggered After	Primary Use Case
pdfgeneratorapi.save	Indicates a successful template save operation.	The user clicks 'Save' in the editor, and the template is stored.	Update a "Last Saved" timestamp, close a modal, or refresh a template list in the parent application.
pdfgeneratorapi.load	Indicates the template editor has finished loading the specified template.	The editor Iframe has initialised and the template is ready for editing.	Hide a loading spinner, or enable related UI elements in the host application.
pdfgeneratorapi.delete	Indicates the user has deleted the template from within the editor.	The user confirms the template deletion.	Remove the deleted template from a list in the parent application, or navigate the user away from the editor view.

Developer Implementation Guide

Integrating these events requires setting up an event listener in your host application's JavaScript. This listener will monitor all incoming postMessage events from the Iframe and filter for those originating from the PDF Generator API editor.

Use the standard window.addEventListener('message', ...) function in the parent window where the Iframe is embedded.

// Function to handle specific PDF Generator API events
function handlePdfGeneratorEvent(data) {
    console.log(`PDF Generator API Event Captured: ${data.event}`);
    // The event data payload can be accessed via data.payload
    // The payload content might vary based on the event (e.g., template ID, status)
    switch (data.event) {
        case 'pdfgeneratorapi.save':
            console.log('Template was successfully saved.');
            // Implement logic here: e.g., show a success notification
            break;
        case 'pdfgeneratorapi.load':
            console.log('Template editor loaded successfully.');
            // Implement logic here: e.g., hide a loading spinner
            break;
        case 'pdfgeneratorapi.delete':
            console.log('Template was deleted.');
            // Implement logic here: e.g., redirect user
            break;
        default:
            console.warn('Unknown PDF Generator API event:', data.event);
    }
}

// Listen for all postMessage events
window.addEventListener('message', function(event) {
    // SECURITY CHECK: Always verify the origin of the message
    // You should restrict the origin to your expected domain for security.
    // if (event.origin !== 'https://us1.pdfgeneratorapi.com') { return; }

    // Log all messages for debugging
    console.log('Received postMessage:', event);

    // Check if the message is a PDF Generator API event
    // The event data will be structured as { event: 'pdfgeneratorapi.eventname', payload: {...} }
    if (event.data && event.data.event && event.data.event.startsWith('pdfgeneratorapi.')) {
        handlePdfGeneratorEvent(event.data);
    }
});

Updated on: 18/11/2025

Was this article helpful?

Thank you!

Integrating the Embedded Editor: Capturing Template Events with PostMessage