Konfiguration

Das Templatical SDK bietet verschiedene Konfigurationsoptionen, um sein Verhalten und Erscheinungsbild anzupassen.

Grundkonfiguration

import { init } from '@templatical/embedded';

const editor = await init({
  container: '#email-editor',
  auth: {
    url: 'https://your-app.com/api/token',
  },
});

Erforderliche Optionen

Option	Typ	Beschreibung
container	string | HTMLElement	CSS-Selektor oder DOM-Element für den Editor
auth.url	string	URL Ihres Token-Endpunkts (siehe Authentifizierung)

Optionen

Alle folgenden Optionen werden innerhalb des init()-Aufrufs zusammen mit den erforderlichen Optionen übergeben:

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  // ...Optionen
});

locale

Legt die UI-Sprache fest. Standard ist 'en'.

locale: 'de',

Unterstützte Sprachen: en (Englisch), de (Deutsch). Sie können auch vollständige Locale-Codes wie en-GB oder de-AT verwenden — das SDK erkennt die Basissprache automatisch.

mergeTags

Konfiguriert die Erkennung und Anzeige von Merge-Tags. Wenn der Editor einen übereinstimmenden value im Vorlageninhalt erkennt, zeigt er stattdessen das lesbare label an. Dadurch werden Merge-Tags wie {{first_name}} als benutzerfreundliche Bezeichnungen (z. B. „Vorname") in der Editor-Oberfläche dargestellt.

mergeTags: {
  tags: [
    { label: 'Vorname', value: '{{first_name}}' },
    { label: 'Nachname', value: '{{last_name}}' },
    { label: 'E-Mail', value: '{{email}}' },
    { label: 'Abmelde-URL', value: '{{unsubscribe_url}}' },
  ],
},

Eigenschaft	Typ	Beschreibung
tags	MergeTag[]	Liste bekannter Merge-Tags
tags[].label	string	Anzeigename im Editor, wenn der Merge-Tag erkannt wird
tags[].value	string	Der Merge-Tag, der im Vorlageninhalt abgeglichen wird
syntax	string | SyntaxPreset	Syntax-Preset-Name oder benutzerdefinierte Regex (Standard: 'liquid')

Die Option syntax steuert, wie der Editor Merge-Tags erkennt, die in Inhalte eingegeben oder eingefügt werden. Integrierte Presets: 'liquid' (Standard), 'handlebars', 'mailchimp', 'ampscript', 'django'.

// Handlebars-Syntax verwenden
mergeTags: {
  syntax: 'handlebars',
  tags: [
    { label: 'Vorname', value: '{{first_name}}' },
  ],
},

// Benutzerdefinierte Regex-Muster verwenden
mergeTags: {
  syntax: {
    value: /\$\{.+?\}/g,       // Erkennt ${variable}
    logic: /\$\{#(\w+).*?\}/g, // Erkennt ${#if ...}
  },
  tags: [
    { label: 'Vorname', value: '${first_name}' },
  ],
},

Siehe Merge-Tags für die vollständige Anleitung einschließlich aller Syntax-Presets, benutzerdefinierter Syntax und Best Practices.

Wenn Sie Benutzern ermöglichen möchten, Merge-Tags dynamisch über eine eigene Oberfläche auszuwählen, siehe den onRequestMergeTag-Callback.

displayConditions

Konfiguriert Anzeigebedingungen auf Blockebene. Anzeigebedingungen ermöglichen es Benutzern, Blöcke basierend auf Empfängerdaten bedingt anzuzeigen oder auszublenden. Der Consumer definiert verfügbare Bedingungen mit before/after-Umschließungsstrings, und Benutzer wählen aus einem Dropdown in der Toolbar.

displayConditions: {
  conditions: [
    {
      label: 'Nur VIP-Kunden',
      before: '{% if customer.vip %}',
      after: '{% endif %}',
      group: 'Kunde',
      description: 'Wird nur VIP-Kunden angezeigt.',
    },
    {
      label: 'Free-Plan-Benutzer',
      before: '{% if customer.plan == "free" %}',
      after: '{% endif %}',
      group: 'Kunde',
      description: 'Richtet sich an Benutzer im kostenlosen Plan.',
    },
    {
      label: 'Englischsprachige Empfänger',
      before: '{% if contact.language == "en" %}',
      after: '{% endif %}',
      group: 'Sprache',
    },
  ],
  allowCustom: true,
},

Eigenschaften der obersten Ebene:

Eigenschaft	Typ	Beschreibung
conditions	DisplayCondition[]	Array vordefinierter Anzeigebedingungen
allowCustom	boolean?	Bei true können Benutzer eigene before/after-Logik schreiben (Standard: false)

Bedingungseigenschaften:

Eigenschaft	Typ	Beschreibung
label	string	Lesbarer Name im Toolbar-Dropdown
before	string	Markup, das vor dem Block im exportierten HTML eingefügt wird
after	string	Markup, das nach dem Block im exportierten HTML eingefügt wird
group	string?	Optionale Gruppierung zur Organisation der Bedingungen im Dropdown
description	string?	Beschreibung, die unter dem Bedingungslabel angezeigt wird

Wenn ein Benutzer eine Bedingung für einen Block auswählt, zeigt der Block ein Filter-Icon-Badge im Editor-Canvas an. Beim Export wird das gerenderte HTML des Blocks mit den before- und after-Strings umschlossen. Bei aktiviertem allowCustom erscheint eine Option „Eigene Bedingung" am Ende des Dropdowns, mit der Benutzer eigene before/after-Umschließungslogik schreiben können.

Siehe Anzeigebedingungen für die vollständige Anleitung einschließlich plattformspezifischer Beispiele und Anwendungsfälle.

autoSave

Plan Feature

Diese Funktion ist nur in den Plänen Launch, Growth und Scale verfügbar.

Aktiviert automatisches Speichern. Bei true speichert der Editor die Vorlage automatisch nach Änderungen. Verwenden Sie autoSaveDebounce, um die Verzögerung in Millisekunden zu steuern (Minimum 3000, Standard 5000).

autoSave: true,
autoSaveDebounce: 10000, // 10 Sekunden

ai

Steuert, welche KI-Funktionen im Editor verfügbar sind. Standardmäßig sind alle KI-Funktionen aktiviert, wenn Ihr Plan KI-Generierung beinhaltet. Sie können einzelne Funktionen gezielt deaktivieren oder alle KI-Funktionen auf einmal deaktivieren.

Setzen Sie false, um alle KI-Funktionen zu deaktivieren:

ai: false,

Oder übergeben Sie ein Objekt, um einzelne Funktionen zu steuern:

ai: {
  chat: true,              // KI-Chat-Assistent
  scoring: true,           // Vorlagen-Qualitätsbewertung
  designToTemplate: true,  // Design-zu-Vorlage-Konvertierung
  rewrite: true,           // KI-Text-Umschreibung in der Toolbar
},

Eigenschaft	Typ	Standard	Beschreibung
chat	boolean	true	KI-Chat-Assistent aktivieren/deaktivieren
scoring	boolean	true	Vorlagen-Qualitätsbewertung aktivieren/deaktivieren
designToTemplate	boolean	true	Design-zu-Vorlage-Konvertierung aktivieren/deaktivieren
rewrite	boolean	true	KI-Text-Umschreibung in der Block-Toolbar aktivieren/deaktivieren

Verhaltenshinweise:

• Das Weglassen der ai-Option aktiviert alle KI-Funktionen (Standardverhalten).
• ai: false deaktiviert alle KI-Funktionen.
• Jede Funktion ist standardmäßig true, wenn das ai-Objekt übergeben wird, aber die Eigenschaft weggelassen wird.
• Die KI-Menüschaltfläche in der Kopfzeile wird ausgeblendet, wenn chat, scoring und designToTemplate alle deaktiviert sind. Die rewrite-Funktion befindet sich unabhängig davon in der Block-Toolbar.
• KI-Funktionen erfordern auch, dass Ihr Abonnementplan KI-Generierung beinhaltet. Wenn der Plan dies nicht beinhaltet, werden KI-Funktionen unabhängig von dieser Konfiguration ausgeblendet.

Beispiele:

// Nur Chat deaktivieren, andere KI-Funktionen beibehalten
ai: { chat: false },

// Nur Umschreibung aktivieren (blendet KI-Menüschaltfläche aus, Umschreibung bleibt in der Toolbar)
ai: { chat: false, scoring: false, designToTemplate: false },

// Alle KI-Funktionen deaktivieren
ai: false,

commenting

Plan Feature

Diese Funktion ist nur in den Plänen Growth und Scale verfügbar.

Steuert, ob die Kommentarfunktion im Editor verfügbar ist. Standard ist true. Setzen Sie false, um Kommentare unabhängig von Planverfügbarkeit oder Benutzeridentitätskonfiguration zu deaktivieren.

commenting: false,

Siehe Kommentare für die vollständige Anleitung einschließlich Einrichtung, Benutzeridentität und den onComment-Callback.

customBlocks

Plan Feature

Diese Funktion ist nur im Scale-Plan verfügbar.

Registriert benutzerdefinierte Inhaltsblöcke, die neben den integrierten Blöcken in der Editor-Seitenleiste erscheinen. Benutzerdefinierte Blöcke werden deklarativ mit Feldern und einer Liquid-Vorlage definiert — kein JavaScript erforderlich.

customBlocks: [
  {
    type: 'product-card',
    name: 'Product Card',
    icon: '<svg>...</svg>',
    fields: [
      { key: 'name', type: 'text', label: 'Product Name', default: 'Product' },
      { key: 'price', type: 'text', label: 'Price', default: '$0.00' },
      { key: 'ctaUrl', type: 'text', label: 'Button URL', default: '#' },
    ],
    template: `
      <div style="padding: 16px;">
        <h3>{{ name }}</h3>
        <p style="font-size: 20px; font-weight: bold;">{{ price }}</p>
        <a href="{{ ctaUrl }}" style="background: #007bff; color: white; padding: 12px 24px; border-radius: 4px; text-decoration: none; display: inline-block;">Shop Now</a>
      </div>
    `,
  },
],

Blöcke können auch eine dataSource zum Laden von Inhalten aus externen Quellen enthalten — Produkte, Artikel, Veranstaltungen usw. — über Ihre eigene Auswahl-Oberfläche. Siehe Datenquellen für Details.

Siehe Benutzerdefinierte Blöcke für die vollständige Referenz, alle Feldtypen und die Template-Syntax.

Instanzmethoden

Die init()-Funktion gibt eine TemplaticalInstance mit folgenden Methoden zurück:

create(content?)

Erstellt eine neue Vorlage und weist ihr eine UUID zu. Rufen Sie dies vor save() auf, wenn Sie von Grund auf neu beginnen.

Akzeptiert ein optionales content-Objekt. Wenn angegeben, wird die Vorlage mit dem übergebenen Inhalt erstellt, anstatt mit dem standardmäßigen leeren Inhalt. Dies ist nützlich, wenn Sie vorgefertigten Vorlageninhalt als Ausgangspunkt verwenden möchten.

Löst den onCreate-Callback aus.

// Mit standardmäßig leerem Inhalt erstellen
const template = await editor.create();
console.log(template.id); // Neue UUID

// Mit vorgefertigtem Inhalt erstellen
const template = await editor.create({
  blocks: [/* Ihre Blöcke */],
  settings: {
    width: 600,
    backgroundColor: '#ffffff',
    fontFamily: 'Arial, sans-serif',
    preheaderText: 'Entdecken Sie unsere neuesten Updates!',
  },
});

Parameter	Typ	Erforderlich	Beschreibung
content	TemplateContent	Nein	Vorlageninhalt (Blöcke und Einstellungen) anstelle der Standardwerte

load('template-id')

Lädt eine vorhandene Vorlage nach ID.

Löst den onLoad-Callback aus.

const template = await editor.load('template-id');

save()

Speichert die aktuelle Vorlage. Erfordert, dass zuvor create() oder load() aufgerufen wurde — wirft einen SdkError, wenn keine Vorlage erstellt oder geladen wurde.

Löst den onSave-Callback aus.

const result = await editor.save();

unmount()

Zerstört die Editor-Instanz und entfernt sie aus dem DOM. Rufen Sie dies auf, wenn Sie den Editor nicht mehr benötigen — zum Beispiel beim Schließen eines Modals oder beim Verlassen der Seite. Nach dem Aufruf von unmount() müssen Sie init() erneut aufrufen, um den Editor neu zu erstellen.

Löst den onUnmount-Callback aus.

editor.unmount();

Callbacks

onCreate

Wird ausgelöst, wenn eine neue Vorlage über create() erstellt wird. Erhält das Template-Objekt mit der neuen UUID und dem Standardinhalt. Verwenden Sie dies, um den Anwendungsstatus mit der neuen Vorlagen-ID zu aktualisieren.

onCreate: (template) => {
  console.log('Erstellt:', template.id);
  // Vorlagen-ID in Ihrer Anwendung speichern
  myApp.currentTemplateId = template.id;
},

Eigenschaft	Typ	Beschreibung
template.id	string	Die eindeutige Kennung der neu erstellten Vorlage
template.content	TemplateContent	Der Vorlageninhalt (Blöcke und Einstellungen)

onSave

Ausgelöst durch save().

Wird ausgelöst, wenn die Vorlage gespeichert wird. Der Speichervorgang rendert die Vorlage automatisch in HTML und MJML, sodass der Callback ein SaveResult-Objekt mit der Vorlagen-ID, der gerenderten Ausgabe und dem Inhalt erhält.

Die Eigenschaft mjml enthält den rohen MJML-Quellcode, der zur HTML-Generierung verwendet wurde. Der MJML-Export ist nur in den Plänen Growth und Scale verfügbar — bei anderen Plänen ist mjml ein leerer String.

onSave: (result) => {
  console.log('Gespeichert:', result.templateId);
  console.log(result.html);     // Vollständige HTML-Ausgabe
  console.log(result.mjml);     // MJML-Quellcode (nur Growth / Scale)
  console.log(result.content);  // Vorlageninhalt (Blöcke + Einstellungen)
},

Eigenschaft	Typ	Beschreibung
result.templateId	string	Die eindeutige Kennung der gespeicherten Vorlage
result.html	string	Die vollständig gerenderte HTML-E-Mail-Ausgabe
result.mjml	string	Der MJML-Quellcode (nur Growth / Scale, sonst leerer String)
result.content	TemplateContent	Der Vorlageninhalt (Blöcke und Einstellungen)

INFO

Hinweis: autoSave löst diesen Callback nicht aus. Automatisches Speichern erstellt Snapshots (Versionsverlauf-Einträge) anstelle einer vollständigen Speicherung.

onLoad

Ausgelöst durch load().

Wird ausgelöst, wenn eine Vorlage geladen wird.

onLoad: (template) => {
  console.log('Geladen:', template.id);
},

onRequestMergeTag

Wird aufgerufen, wenn der Benutzer auf die Merge-Tag-Schaltfläche in der Editor-Toolbar klickt. Verwenden Sie dies, um Ihre eigene Merge-Tag-Auswahl-Oberfläche (z. B. ein Modal oder Dropdown) anzuzeigen und den ausgewählten Merge-Tag zurückzugeben. Das zurückgegebene Objekt muss ein label und einen value haben, genau wie die Einträge in der mergeTags.tags-Liste. Das label wird im Editor angezeigt und der value wird in das Vorlagen-HTML eingefügt. Geben Sie null zurück, wenn der Benutzer die Auswahl abbricht.

onRequestMergeTag: async () => {
  // Eigenes Merge-Tag-Auswahl-Modal anzeigen
  const selected = await showMergeTagModal();

  if (!selected) {
    return null; // Benutzer hat abgebrochen
  }

  // MergeTag-Objekt mit label und value zurückgeben
  return {
    label: selected.name,            // z. B. "Vorname"
    value: selected.mergeTag,        // z. B. "{{first_name}}"
  };
},

onError

Wird ausgelöst, wenn ein Fehler auftritt. Der Fehler ist eine Instanz von SdkError mit den Eigenschaften statusCode, isNotFound, isUnauthorized und isServerError.

onError: (error) => {
  console.error('Editor-Fehler:', error.message);
},

onUnmount

Ausgelöst durch unmount().

Wird ausgelöst, nachdem die Editor-Instanz zerstört und aus dem DOM entfernt wurde. Verwenden Sie dies, um Aufräumlogik auszuführen — zum Beispiel zum Zurücksetzen des UI-Zustands oder zum Entfernen von Event-Listenern in Ihrer Anwendung.

onUnmount: () => {
  console.log('Editor entfernt');
  // Anwendungszustand zurücksetzen
  myApp.editorOpen = false;
},