Von PDFMonkey migrieren
PDFMonkey-Code-Vorlagen bestehen aus HTML mit Liquid, einem CSS- oder SCSS-Stylesheet, Beispieldaten und Seiteneinstellungen. Formfeed verwendet ebenfalls Liquid; der Import passt deshalb nur die Stellen an, an denen sich PDFMonkeys Ruby-Liquid und seine eigenen Filter unterscheiden, und meldet alles, was er nicht umwandeln kann, mit der Zeile.
Vorlagen importieren
In der App: Vorlagen → Importieren → PDFMonkey.
- Geben Sie einen geheimen API-Schlüssel aus PDFMonkey ein (My account → API). Er wird einmal zum Lesen der Vorlagen gesendet und nicht gespeichert.
- Geben Sie Ihre Workspace-ID ein und wählen Sie Vorlagen auflisten, oder fügen Sie Vorlagen-IDs ein (eine pro Zeile).
- Wenn Ihre Vorlagen
load_snippetsverwenden, fügen Sie die Snippets ein (siehe Snippets). - Analysieren wandelt jede ausgewählte Vorlage um und zeigt je Vorlage einen Bericht: Fehler, die das Rendern verhindern, Punkte zum Prüfen und was der Import geändert hat.
- Entwürfe anlegen erstellt je Bericht eine Liquid-Vorlage mit den übernommenen Einstellungen und den Beispieldaten als Standard-Datensatz. Ihre erste Version ist ein Entwurf; veröffentlichen Sie sie im Editor.
Die App importiert die veröffentlichte Version jeder PDFMonkey-Vorlage oder ihren Entwurf, wenn sie nie veröffentlicht wurde.
Mit der CLI, in einem Vorlagenprojekt (der Schlüssel kommt aus --key oder PDFMONKEY_API_KEY):
export PDFMONKEY_API_KEY=sk_…
formfeed import pdfmonkey --workspace-id 6f1c… # alle Code-Vorlagen des Workspace
formfeed import pdfmonkey --template 3b9e… 71aa… # oder ausgewählte Vorlagen
formfeed import pdfmonkey --template 3b9e… --snippet address=snippets/address.liquid
formfeed import pdfmonkey --template 3b9e… --draft # stattdessen den unveröffentlichten Entwurf
Jede Vorlage wird zu einem Ordner unter templates/, und die CLI gibt denselben Bericht aus wie die App.
Nur Code-Vorlagen lassen sich importieren. Builder-Vorlagen (der visuelle Builder von PDFMonkey) nicht,
weil ihr Format nicht veröffentlicht ist; --workspace-id überspringt sie, und eine mit --template
genannte Builder-Vorlage ist im Bericht ein Fehler. Legen Sie diese im Editor neu an.
Datumsangaben
PDFMonkey formatiert Datumsangaben mit Rubys strftime (%d.%m.%Y), der date-Helfer von Formfeed mit
date-fns-Tokens (dd.MM.yyyy). Der Import schreibt jedes Format um, auch Wörter im Format
(%d de %B wird dd' de 'MMMM), und aus "today" | date wird "now" | date. Ein in_time_zone
unmittelbar vor date wird zum Zeitzonen-Argument von date (erste Zeile vorher, zweite nachher):
{{ order.created_at | in_time_zone: "Europe/Berlin" | date: "%H:%M" }}
{{ order.created_at | date: "HH:mm", "Europe/Berlin" }}
Ein in_time_zone an anderer Stelle ist im Bericht ein Fehler. Außerdem nennt der Bericht
strftime-Direktiven ohne date-fns-Entsprechung (etwa %j oder %s); sie bleiben unverändert stehen.
Zahlen
with_delimiter wird zu number mit der Locale, deren Trennzeichen passen: Trennzeichen . und
Dezimalzeichen , ergeben de-DE, ein Leerzeichen und , ergeben fr-FR, ' und . ergeben de-CH,
die Voreinstellung (, und .) ergibt en-US. Jedes andere Paar bleibt stehen, wird gemeldet und lässt
das Rendern scheitern. precision: 2 wird zu zwei Nachkommastellen. strip_insignificant_zeros hat
keine Entsprechung und wird gemeldet; number zeigt dann bis zu drei Nachkommastellen.
PDFMonkeys Ruby-Liquid teilt zwei Ganzzahlen ohne Rest (7 | divided_by: 2 ergibt 3); Formfeed
liefert 3.5. Der Import ändert die Rechnung nicht, listet aber jede Ganzzahl-Division mit ihrer
Zeile auf, damit Sie | floor ergänzen können, wo die Vorlage darauf angewiesen ist.
Filter
| PDFMonkey | Formfeed |
|---|---|
slice_by: 3 | chunk: 3 (vom Import umbenannt) |
sum, push, json, where_exp | unverändert |
with_delimiter, in_time_zone | siehe Zahlen und Datumsangaben |
entities | nicht nötig, entfernt: Kopf- und Fußzeilen stellen UTF-8 direkt dar |
to_sentence | Fehler; nutzen Sie join: ", " oder array_to_sentence_string für „a, b, and c“ |
format (printf) | Fehler; nutzen Sie number: 2 oder round: 2 (printf-Auffüllung hat keine Entsprechung) |
ensure_protocol, parse_json | Fehler; speichern Sie vollständige URLs (oder prepend: "https:") und senden Sie JSON als Objekt |
Liquid gibt Werte aus, wie sie sind, bei Formfeed wie bei PDFMonkey: Es maskiert HTML in der Ausgabe
nicht. Wo eine Vorlage Text ausgibt, den Ihre Nutzer eingegeben haben, behalten oder ergänzen Sie
| escape ({{ customer.name | escape }}), damit ein < in einem Namen das Dokument nicht verändern kann.
Filter ohne Entsprechung sind im Bericht Fehler: Das Liquid von Formfeed läuft mit strikten Filtern,
ein unbekannter Filter bricht das Rendern also ab, statt nichts auszugeben. Ruby akzeptiert außerdem
ein Komma nach dem Filternamen (| with_delimiter, precision: 2); der Import schreibt den Doppelpunkt,
den LiquidJS braucht.
Snippets
Die API von PDFMonkey liefert den Code von Snippets nicht mit. Fügen Sie jedes Snippet, das die
Vorlagen laden, in das Feld Snippets ein: eine Zeile --- name, danach sein Code:
--- address
<address>{{ who.name }}<br>{{ who.street }}</address>
--- legal-footer
<small>Fennlor Studio GmbH · Musterstraße 1</small>
{% include 'address', who: customer %} und eingebettete {% partial %}-Blöcke werden in die Vorlage
eingefügt, die Parameter als assign. Ein Include, dessen Snippet fehlt, ist ein Fehler.
Styles
Das Stylesheet darf SCSS sein. Die App kompiliert es mit Sass, die CLI, wenn sass im Projekt
installiert ist (npm install -D sass). Ohne Compiler werden $variablen auf oberster Ebene ersetzt
und //-Kommentare entfernt; alles, was Sass braucht (@mixin und @include, @extend, @use und
@forward, @if, @each und die übrigen Kontrollregeln, Funktionen), wird gemeldet.
Verschachtelte Regeln funktionieren in beiden Fällen: Chromium beherrscht CSS-Nesting.
Einstellungen
Papierformat (A0 bis A6, Letter, eigene Größen in Millimetern), Ausrichtung und Ränder werden in die
Einstellungen der Vorlage übernommen; jedes andere Format wird mit einer
Warnung zu A4, und leere Ränder sind bei PDFMonkey 10 mm. Die einfache Kopf- und Fußzeile (links,
Mitte, rechts mit [page] und [topage]) wird zu einer HTML-Kopfzeile mit Seitenzahlen in 10px
Schriftgröße; die erweiterte HTML-Kopf- und Fußzeile landet in den Tabs Kopfzeile und Fußzeile, mit
denselben Liquid-Umwandlungen wie der Hauptteil. Bildvorlagen werden zu Bildvorlagen mit 1200 × 630
Pixeln (PDFMonkey setzt die Größe je Anfrage), mit transparentem Hintergrund, wo die Vorlage einen
hatte; ändern Sie die Größe unter Seiteneinrichtung im Editor.
Hat die Vorlage Tailwind mit einem <script>- oder Stylesheet-Tag geladen, wird das Tag entfernt und
der Tailwind-Modus eingeschaltet: Formfeed kompiliert die Klassen, die die Vorlage verwendet.
JavaScript
PDFMonkey kann die Nutzdaten Skripten als $docPayload bereitstellen. Formfeed tut das nicht; geben
Sie die Werte im Markup aus oder schreiben Sie sie in ein Script-Tag:
<script>const order = {{ order | json }};</script>
Für QR-Codes ersetzt der Helfer qrcode JavaScript-Bibliotheken:
<img src="{{ payment.url | qrcode }}" alt="QR code: {{ payment.url }}">. Der Bericht weist auf eine
QR-Bibliothek hin, die er in der Vorlage findet.
Paged.js
Formfeed paginiert mit Chromium und zeigt im Editor eine Paged.js-Vorschau. Vorlagen, die Paged.js selbst geladen haben, behalten das Skript; prüfen Sie laufende Kopfzeilen und Randfelder im echten Rendering.
Formulare
Marker für PDF-Formularfelder ([% data_form_field … %]) werden nicht unterstützt und bleiben als Text
stehen.
Beispieldaten
Die Beispieldaten aus PDFMonkey werden zum Standard-Datensatz der Vorlage; Vervollständigung,
Vorschau und die Prüfung auf fehlende Variablen im Bericht verwenden sie. Ihre API-Anfragen senden die
Nutzdaten weiter wie bisher, jetzt als data eines Renderings.
API umstellen
Ersetzen Sie den Aufruf des Documents-Endpunkts von PDFMonkey durch ein Rendering. Der Import legt Entwürfe an, und die API rendert die veröffentlichte Version; veröffentlichen Sie also jede Vorlage zuerst. Die Anfrage nennt die Vorlage mit ihrem Slug (dem Identifier der PDFMonkey-Vorlage in Kleinbuchstaben mit Bindestrichen):
curl https://api-eu.formfeed.dev/v1/renders \
-H "Authorization: Bearer ff_live_…" \
-H "Content-Type: application/json" \
-d '{ "template": "order-confirmation", "data": { "order": { "id": "A-1" } } }'
mode: "async" mit einem Webhook ersetzt die wartenden Dokumente und Webhook-Ereignisse von PDFMonkey;
siehe Asynchron und Batches.