pandadoc-editor Library

The pandadoc-editor library provides an easy way to embed the PandaDoc Editor in your web application using E-Token authentication.

Features

• Embedded Sending
• Embedded Editing
• E-Token authentication (simplified setup)
• Debug mode for troubleshooting
• Field and Block visibility control

Installation

To install pandadoc-editor, you can use either npm or yarn:

npm install pandadoc-editor

or

yarn add pandadoc-editor

Quick Start

First, import the library in your project:

import { Editor } from 'pandadoc-editor';

Then, initialize and open the editor:

const editor = new Editor(
  'editor-container',
  {
    token: 'your-e-token-here', // E-Token for authentication
  },
  {
    region: 'com', // Optional: specify region ('com' or 'eu')
  },
);

// Open the editor
await editor.open();

API Reference

Constructor

const editor = new Editor(elementId, config, pdConfig);

Parameters:

• elementId (string): The ID of the DOM element to replace with the editor
• config (EditorConfig): Editor configuration options
• pdConfig (PDConfigModel): PandaDoc server configuration

PDConfig Options:

const editor = new Editor(
  'editor-container',
  {
    token: 'your-e-token-here',
  },
  {
    region: 'eu', // Preferred: Use region for better maintainability
    host: 'https://custom.pandadoc.com/', // Deprecated: Use region instead
  },
);

Methods

open(options)

Opens the editor with the specified configuration.

await editor.open({
  token: 'your-e-token-here',
  fieldPlacementOnly: true,
  debugMode: false,
});

close()

Closes the editor.

await editor.close();

destroy()

Destroys the editor instance and cleans up resources to prevent memory leaks. This method:

• Destroys the event bus and command bus
• Removes the iframe from the DOM
• Should be called when you no longer need the editor instance

editor.destroy();

Important: After calling destroy(), the editor instance cannot be reused. Create a new instance if needed.

Events

The editor emits various events that you can listen to using the on(), off(), and once() methods:

on(eventName, handler)

Registers an event listener that persists until manually removed.

editor.on('content.rendered', (payload) => {
  console.log('Content has been rendered', payload);
});

off(eventName, handler)

Removes a previously registered event listener.

const handler = (payload) => console.log('Rendered', payload);
editor.on('content.rendered', handler);
editor.off('content.rendered', handler); // Remove the listener

once(eventName, handler)

Registers an event listener that fires only once and then automatically removes itself.

editor.once('content.rendered', (payload) => {
  console.log('Content rendered for the first time', payload);
  // This handler will not be called again
});

Available Events

content.rendered

Emitted when the document or template content has been rendered and is visible in the editor.

editor.on('content.rendered', (payload) => {
  console.log('Document/Template rendered:', payload);
});

document.loading

Emitted when the editor starts loading a document.

editor.on('document.loading', (payload) => {
  console.log('Document loading...', payload);
});

document.loading.error

Emitted when an error occurs while loading a document.

editor.on('document.loading.error', (payload) => {
  console.error('Failed to load document:', payload);
});

template.loading

Emitted when the editor starts loading a template.

editor.on('template.loading', (payload) => {
  console.log('Template loading...', payload);
});

template.loading.error

Emitted when an error occurs while loading a template.

editor.on('template.loading.error', (payload) => {
  console.error('Failed to load template:', payload);
});

Event Handler Chaining

Event handler methods support method chaining for more concise code:

editor
  .on('content.rendered', () => console.log('Rendered'))
  .on('document.loading', () => console.log('Loading'))
  .once('document.loading.error', () => console.log('Error'));

Field Visibility Control

You can control the visibility of different field types using the fields parameter:

Default Field Configuration

const defaultFieldConfiguration = {
  text: { visible: true },
  checkbox: { visible: true },
  dropdown: { visible: true },
  date: { visible: true },
  signature: { visible: true },
  stamp: { visible: true },
  initials: { visible: true },
  payment_details: { visible: true },
  collect_file: { visible: true },
  radio_buttons: { visible: true },
};

Example: Hiding Specific Fields

const editor = new Editor('editor-container', {
  token: 'your-e-token-here',
  fields: {
    stamp: {
      visible: false,
    },
    dropdown: {
      visible: false,
    },
  },
});

await editor.open();

Debug Mode

Enable debug mode to get detailed logging of editor operations:

const editor = new Editor('editor-container', {
  token: 'your-e-token',
  debugMode: true,
});

When debug mode is enabled, you'll see console logs for:

• Constructor initialization
• Open/close operations with parameters
• Command dispatching
• Error conditions and their reasons
• Resource cleanup during destroy

Debug logs are prefixed with [Editor Debug] and include relevant data for troubleshooting.

Region Configuration

You can specify which PandaDoc region to use by setting the region parameter:

// For global region (default)
const editor = new Editor(
  'editor-container',
  {
    token: 'your-e-token-here',
  },
  {
    region: 'com', // Global region - app.pandadoc.com
  },
);

// For EU region
const editor = new Editor(
  'editor-container',
  {
    token: 'your-e-token-here',
  },
  {
    region: 'eu', // EU region - app.pandadoc.eu
  },
);

Available Regions

• 'com': Global region (app.pandadoc.com) - Default
• 'eu': EU region (app.pandadoc.eu)

Priority Order

The host resolution follows this priority order:

1. pdConfig.host (deprecated but highest priority for backward compatibility)
2. pdConfig.region (recommended approach)
3. Default: 'com' (global region)

Complete Usage Example

import { Editor } from 'pandadoc-editor';

// Initialize the editor
const editor = new Editor(
  'editor-container',
  {
    token: 'your-e-token-here',
    debugMode: true, // Enable for development
    width: 800,
    height: 600,
    fieldPlacementOnly: false,
    fields: {
      signature: { visible: true },
      date: { visible: true },
      text: { visible: true },
      stamp: { visible: false }, // Hide stamp fields
    },
  },
  {
    region: 'com', // Use global region (default)
  },
);

// Set up event listeners
editor
  .on('content.rendered', () => {
    console.log('Content is now visible to the user');
  })
  .on('document.loading', () => {
    console.log('Document is loading...');
  })
  .on('document.loading.error', (error) => {
    console.error('Failed to load document:', error);
  })
  .once('template.loading', () => {
    console.log('Template started loading (fires once)');
  });

try {
  // Open the editor
  await editor.open();

  // ... user interacts with editor ...

  // Close when done
  await editor.close();
} finally {
  // Always clean up resources
  editor.destroy();
}

Legacy Methods (Deprecated)

The following methods are deprecated and will be removed in future versions. Use the open() method instead:

• openDocument(options) - Use open(options) instead
• openTemplate(options) - Use open(options) instead

These legacy methods used the old authentication approach with documentId, workspaceId, and organizationId parameters. The new E-Token authentication simplifies the setup process.

Error Handling

import { Editor } from 'pandadoc-editor';

const editor = new Editor('editor-container', {
  token: 'your-e-token-here',
  debugMode: true, // Helps with troubleshooting
});

try {
  await editor.open();
} catch (error) {
  console.error('Failed to open editor:', error);
  // Handle error appropriately
} finally {
  // Always clean up
  editor.destroy();
}

Building

To build the library, run:

vite build

This will generate the library bundle in the dist directory.