Embed the Template Editor

Use the embedded template editor when your users need to configure PDF templates without leaving your application.

Setup

Include the template editor JavaScript library:

Include template_editor.js

<script
type="text/javascript"
src="https://cdn.docspring.com/embed/template_editor.v0.1.1.js"
></script>

Note

Enterprise deployments can load this script from the local DocSpring domain instead of the CDN: https://docspring.yourcompany.com/assets/embed/template_editor.js.

Render the editor inline:

Inline embedded editor

<div id="template-editor" style="height: 720px"></div>

<script>
DocSpring.createTemplateEditor('#template-editor', {
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN',
  inline: true,
  externalUser: {
    name: 'Jane Editor',
    email: '[email protected]',
    external_id: 'user_123'
  },
  darkMode: false,
  doneButtonLabel: 'Done',
  onDone: function(data) {
    // Close your modal or advance to the next step.
  }
})
</script>

Or open it as a modal:

Modal embedded editor

DocSpring.createTemplateEditor({
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN'
})

Note

Embedded editors always edit the draft template. When the embed_edit_allow_versioning capability is enabled on the template, the versioning UI lets users publish, restore, or delete template versions. The embed token cannot copy a template or delete the draft. See Security.

Embedded Template Editor Example Test the embedded editor with your own template UID, embed edit token, and options

Embed Domains

Add your domain to the template’s Embed Domains setting so the editor can be loaded on your pages. Note: when Embed Domains is set but the embedding page sends no Referer or Origin header, the editor refuses to load. Leave the field blank only when you do not want any domain restriction. See Security for what the embed token can and cannot do.

Options

The first argument can be a selector string (with options as the second argument) or a single options object. When a selector is provided the editor renders inline unless you pass inline: false; with no selector it opens as a modal.

Option	Type	Required	Description
templateId	string	Yes	Template ID, such as tpl_123.
token	string	Yes	Template embed edit token.
externalUser	object	No	Details for the user editing the template in your app. Used for “last changed by” and version publisher labels.
selector	string	No	Target element for an inline editor. May be passed here instead of as the first argument.
inline	boolean	No	Defaults to true when a selector is provided. Pass false to force modal mode even with a selector.
darkMode	boolean	No	Pass true to render the embedded editor with DocSpring’s dark theme, or false to force the light theme.
showDoneButton	boolean	No	Show a customizable done button in the editor header. Defaults to true.
doneButtonLabel	string	No	Label for the done button. Defaults to Done.
disableDoneButtonIfPredefinedFieldsMissing	boolean	No	Disable the done button until every required_in_template predefined field has been added. Defaults to true.
features	object	No	Per-embed feature overrides.
closeModalOnClickOverlay	boolean	No	In modal mode, close the editor when the overlay behind it is clicked. Defaults to true.
fullScreenModal	boolean	No	In modal mode, remove the default side margins and use the full viewport width. Defaults to false.
modalMaxWidth	string	No	In modal mode, cap the iframe width with a CSS length such as 1200px or 80vw. Defaults to no max width.
iframeClass	string	No	Additional class names for the iframe.
iframeStyle	string	No	Additional inline CSS for the iframe.
editorURL	string	No	Override the iframe URL. This is mainly useful for local development or custom routing.
region	string	No	Use a DocSpring region: US, EU, or AU. Defaults to US.
host	string	No	Use one host for both app and API URLs, usually for single-domain enterprise deployments.
appHost	string	No	Override the app host used for the editor iframe, usually for split-domain enterprise deployments.
apiHost	string	No	Override the API host for consistency with other embedded libraries.

Region and custom host

Use region when your account is in the EU or AU region:

Regional embedded editor

DocSpring.createTemplateEditor('#template-editor', {
templateId: 'tpl_123',
token: 'EMBED_EDIT_TOKEN',
region: 'AU'
})

For single-domain enterprise deployments, use host:

Enterprise host

DocSpring.createTemplateEditor('#template-editor', {
templateId: 'tpl_123',
token: 'EMBED_EDIT_TOKEN',
host: 'https://docspring.example.com'
})

For split-domain deployments, use appHost and apiHost. Existing globals such as DocSpring.appHost, DocSpring.host, DocSpring.scheme, and DocSpring.port are still supported. If you pass editorURL, that full URL takes precedence and is also used to verify messages from the iframe.

externalUser supports these fields:

Field	Type	Description
name	string	Display name for editor attribution. Defaults to Embedded Template User.
email	string	Email address for editor attribution metadata.
external_id	string	Your application’s stable user ID.

If externalUser is omitted, embedded saves and published versions are attributed to Embedded Template User.

Return value

DocSpring.createTemplateEditor returns an object you can use to control the editor:

Property	Type	Description
iframe	element	The created <iframe> element.
close	function	Closes the editor, removes its iframe and message listener, and fires onClose.
url	string	The full editor URL loaded in the iframe.

Note

Only one embedded template editor should be active on a page. Creating a new editor closes the previous editor instance first. Modal editors close automatically after onDone and onEvent run. Use the returned close() function (or DocSpring.closeTemplateEditor()) when you need to close an editor from another part of your application.

Events

Event callbacks

DocSpring.createTemplateEditor('#template-editor', {
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN',
  inline: true,
  onLoad: function(data) {},
  onSave: function(data) {},
  onVersionPublish: function(data) {},
  onVersionRestore: function(data) {},
  onVersionDelete: function(data) {},
  onDocumentUpdate: function(data) {},
  onDone: function(data) {},
  onError: function(error) {},
  onClose: function() {},
  onEvent: function(eventName, data) {}
})

Each event has a named callback (onLoad, onSave, and so on). onEvent is a catch-all that fires for every event with the event name and its data. onClose fires when a modal editor is closed. Version events only fire when versioning is enabled for the embed.

The Done button only fires onDone when the editor has no pending changes, no active save request, and no save error. Host applications can use onSave to observe successful saves and onDone to advance or close the editor after the user clicks Done. If a save fails, the editor keeps Done disabled until the save error is resolved.

Version Attribution

Template API responses include versions metadata for published template versions. Publisher IDs are split by actor type:

Field	Description
published_by_type	user for a DocSpring account user, or external_user for an embedded editor user.
published_by_user_id	DocSpring user ID (usr_...) when published_by_type is user; omitted otherwise.
published_by_external_id	Your externalUser.external_id when published_by_type is external_user; omitted when not provided.
published_by_name	Display name for the publisher.
published_by_email	External publisher email address when provided.

Security

The embed edit token is a per-template edit credential, not a read-only key. Anyone holding it can edit the template through the embed API, and it is not a hidden secret: it appears in the editor URL and is returned in authenticated API responses. Treat it like an API key scoped to a single template and never expose a token for a template the end user should not be able to edit.

By default the token can only edit template content — fields, field layout, name, defaults, predefined fields, and HTML/SCSS. Three per-template capability flags (all default false) widen what an embed may do. They are enforced on the server, so they are the real boundary; the features options only control which controls are shown.

Capability	Default	Allows the embed to…
embed_edit_allow_settings	false	Edit template settings such as the webhook URL, redirect URL, encryption password, public access, and expiration.
embed_edit_allow_versioning	false	Publish, restore, and delete versions, and view version history.
embed_edit_allow_document_replacement	false	Upload a replacement PDF document.

Set these with the authenticated API or in the dashboard. The matching features switches (showSettings, showVersions, allowPdfReplacement) are forced off when their capability is disabled, so a host cannot re-enable a disabled capability from the browser.

When embed_edit_allow_settings is false, the embedded editor also receives sanitized settings values in its boot payload and template JSON responses. Sensitive settings such as webhook URLs, Slack webhook URLs, redirect URLs, and PDF encryption passwords are returned as null or safe defaults. Enable embed_edit_allow_settings only when the embedded user should both view and edit those settings.

Regardless of any capability, the embed token cannot change the template’s Embed Domains, change the capability flags, lock the template, rotate its own token, copy the template, or delete the draft / entire template family. Those actions require account authentication (the dashboard or the authenticated API).

Embed Domains only restricts which origins may frame the editor (the iframe HTML load); it does not gate the JSON API, which is authenticated by the token. We recommend always setting Embed Domains in production.

Customize the Embedded Template Editor Control which editor features are available in an embed