Engine-Paket

Fortgeschritten

Die meisten Projekte brauchen nur die CLI und die Test-Helfer. Das Engine-Paket ist für Tools gedacht, die die Vorlagenkompilierung einbetten, etwa eine eigene Vorschau in Ihrer Admin-Oberfläche.

@formfeed/engine ist die Template-Engine, die im Formfeed-Editor, in der CLI und auf den Render-Servern läuft. Sie funktioniert in Browsern und in Node 22+, hat keine Node-spezifischen Abhängigkeiten und wird mit ESM- und CommonJS-Builds ausgeliefert.

npm install @formfeed/engine

import {
  getEngine,
  defaultHelpers,
  defaultLimits,
  assembleDocument,
} from '@formfeed/engine';

const engine = getEngine('liquid');
const compiled = engine.compile('<h1>{{ title | upper }}</h1>', {});
const analysis = engine.analyze('<h1>{{ title | upper }}</h1>');
// analysis.variables → [{ path: ['title'], ... }], analysis.diagnostics → []

const html = await engine.render(
  compiled,
  { title: 'Hello' },
  {
    locale: 'de-DE',
    timezone: 'Europe/Berlin',
    currency: 'EUR',
    partials: () => undefined,
    helpers: defaultHelpers(),
    limits: defaultLimits,
  },
);

const document = assembleDocument({
  html,
  css: '',
  head: '',
  settings: { paper: { format: 'A4' } },
  kind: 'pdf',
});

Was Sie bekommen

• getEngine('jinja2' | 'liquid' | 'handlebars') liefert eine Engine mit drei Methoden: compile(source, { name }) parst eine Vorlage und wirft bei Fehlern einen EngineSyntaxError mit line und column; analyze(source, { sampleData }) liefert die Variablen, die die Vorlage liest, und dieselben Diagnosen, die der Editor unterstreicht, und warnt mit sampleData zusätzlich (unknown-variable) vor jeder Variablen, die in den Daten fehlt; render(compiled, data, context) erzeugt HTML und wirft einen RenderError, wenn die Vorlage mit diesen Daten scheitert.
• defaultHelpers() ist die Helfer-Registry der Helfer-Referenz, und defaultLimits sind die Ausführungslimits, die ein Rendering braucht.
• assembleDocument() verpackt gerendertes HTML in das vollständige Dokument, das Chromium druckt, mit dem Druck-Reset und den @page-Regeln aus den Einstellungen.
• renderVersion() erledigt all das für eine Vorlagenversion auf einmal: Body, Kopfzeile, Fußzeile und PDF-Titel.
• inferSchema(sample) macht aus Beispieldaten ein JSON-Schema (Draft 2020-12), so wie der Editor.
• renderOffice(file, options) füllt eine Word- oder PowerPoint-Vorlage, die als Bytes (Uint8Array) vorliegt, mit engine, data und dem Render-context und liefert die gefüllte Datei mit format, warnings und diagnostics. Ein Dokument, das sich nicht füllen lässt, wirft einen OfficeTemplateError, dessen diagnostics Teil und Absatz nennen. Bilder und Codes brauchen einen images-Host, der sie lädt und rastert; ohne ihn werden nur PNG- und JPEG-Data-URLs eingesetzt.
• analyzeOffice(file, { engine, sampleData }) listet die Tags einer Word- oder PowerPoint-Vorlage, die Variablen, die sie liest, ihre Schriften und ihre Funde je Teil und Absatz, so wie die Office-Vorlagenseite der App sie zeigt.
• starterDocument(engine) und starterPresentation(engine) liefern die Beispieldateien der App für Word und PowerPoint mit den Beispieldaten, die sie füllen.

Der Render-Kontext

render nimmt einen Kontext mit diesen Feldern:

Feld	Pflicht	Bedeutung
locale, timezone, currency	ja	Standardwerte der Formatierungshelfer (de-DE, Europe/Berlin, EUR); in renderVersion überschreiben die Einstellungen der Vorlage sie
partials	ja	Liefert den Quelltext eines eingebundenen Partials zu seinem Namen oder undefined, wenn es keins gibt
helpers	ja	Die Helfer-Registry, normalerweise defaultHelpers()
limits	ja	defaultLimits: die Zeit, die ein Rendering dauern darf, die Größe seiner Ausgabe und die Tiefe der Includes
i18n	nein	Übersetzungen für den Helfer t: Sprache → Schlüssel → Text
assetBaseUrl	nein	Wohin asset() zeigt; ohne Angabe bleiben relative Verweise relativ
brand	nein	Das Brand Kit, das Vorlagen als brand sehen

assembleDocument({ html, css, head, settings, kind }) nimmt den gerenderten Body, CSS und <head>-Inhalt der Vorlage, ihre Einstellungen und ihre Art (pdf oder image); assetBaseUrl ergänzt ein <base href>, title einen <title>.

Die Engine erzeugt HTML oder eine gefüllte Word- oder PowerPoint-Datei. Das PDF entsteht auf den Formfeed-Servern: aus HTML in Chromium, senden Sie das Dokument also als html an die API oder nutzen Sie formfeed render, um die exakte Ausgabe zu erhalten; aus einer gefüllten Word- oder PowerPoint-Datei über POST /pdf/convert.