Zum Hauptinhalt springen

Vorlagen als Code

Wenn Ihnen Ihr Editor und Git lieber sind als eine Weboberfläche, hält die CLI formfeed jede Vorlage als Ordner mit einfachen Dateien. Sie erhalten eine lokale Vorschau mit Hot-Reload, Offline-Validierung mit der Engine der Produktion, Snapshot-Tests und einen Veröffentlichungsschritt für die CI. Web-Editor und Dateien bleiben austauschbar: Was Sie pushen, erscheint im Editor, und was jemand dort bearbeitet, können Sie pullen.

Sie brauchen Node.js 22 oder neuer.

1. Anmelden​

npx formfeed login

Die CLI zeigt einen kurzen Code an und öffnet app.formfeed.dev/device. Bestätigen Sie ihn und wählen Sie einen Workspace. Die CLI speichert dann einen API-Schlüssel mit dem Namen „Formfeed CLI on“ und dem Namen Ihres Rechners. Dieser Schlüssel ist ein Live-Schlüssel mit den Scopes Ihrer Rolle in der Organisation; Renderings mit ihm werden also abgerechnet. Auf einem Server oder über SSH ergänzen Sie --no-browser und öffnen die angezeigte URL selbst.

Um stattdessen mit einem kostenlosen Test-Schlüssel zu arbeiten, legen Sie einen auf der Seite API-Schlüssel an und speichern ihn mit npx formfeed login ff_test_…. In der CI lassen Sie die Anmeldung weg und setzen FORMFEED_API_KEY. Sind mehrere vorhanden, gewinnt --api-key vor FORMFEED_API_KEY und dieses vor dem gespeicherten Schlüssel.

npx formfeed whoami     # Workspace, Plan und Verbrauch des verwendeten Schlüssels

2. Projekt anlegen​

Beginnen Sie mit den veröffentlichten Vorlagen Ihres Workspace, zusammen mit den geteilten Partials der Organisation, die sie einbinden können:

npx formfeed init my-templates --from-workspace
cd my-templates

Oder beginnen Sie leer. Ohne --from-workspace erhalten Sie die Startvorlage hello. --engine legt die Vorlagensprache neuer Vorlagen fest (jinja2, die Voreinstellung, liquid oder handlebars):

npx formfeed init my-templates --engine liquid

In beiden Fällen entsteht diese Struktur (die vollständige Referenz steht unter Projektstruktur):

my-templates/
  formfeed.json            Projekteinstellungen
  templates/
    invoice/
      template.json        Name, Art, Engine
      template.html        der Hauptteil
      style.css
      header.html          optionale Kopfzeile
      footer.html          optionale Fußzeile
      settings.json        Papier, Ränder, Locale…
      data/default.json    Beispieldaten (eine Datei pro Datensatz)
    offer/
      template.json        Art docx
      template.docx        eine Word-Vorlage: das Dokument statt der HTML-Dateien
      settings.json
      data/default.json
  partials/                gemeinsame Fragmente

Eine Word- oder PowerPoint-Vorlage ist ein Ordner mit template.docx oder template.pptx, bearbeitet in Word oder PowerPoint.

3. Vorschau mit Hot-Reload​

npx formfeed dev invoice
# ➜ Vorschau unter http://localhost:4400

--port wählt einen anderen Port, --data den Datensatz, mit dem die Vorschau beginnt, und --open öffnet den Browser. Bearbeiten Sie template.html, style.css oder eine Datendatei, und der Browser zeigt die neuen Seiten, sobald Sie speichern, mit Kopf- und Fußzeilen und Seitenzahlen. Diagnosen (unbekannte Variablen, nicht geschlossene Tags, unbekannte Filter) erscheinen mit ihren Zeilennummern. Die Vorschau läuft offline; an Formfeed geht nichts, bis Sie ein echtes Rendering anfordern. Bei einer Word- oder PowerPoint-Vorlage listet die Seite die Funde zu ihren Tags nach Teil und Absatz, und das echte Rendering zeigt das umgewandelte PDF. Siehe Dev-Server.

4. Validieren und testen​

npx formfeed validate            # jede Vorlage kompilieren und gegen ihren Standard-Datensatz prüfen; Exit-Code 1 bei Fehlern
npx formfeed test                # jeden Datensatz rendern und das HTML (bei Word und PowerPoint das XML) mit freigegebenen Snapshots vergleichen
npx formfeed test -u             # die aktuelle Ausgabe als neuen Snapshot freigeben

validate prüft gegen den Datensatz default, sofern --data <name> keinen anderen nennt; test --data <name> führt nur einen Datensatz aus. Beide nehmen einen Slug, um eine einzelne Vorlage zu prüfen, und beide laufen offline mit derselben Engine wie die Produktion. Nehmen Sie validate in einen Pre-Commit-Hook auf. Für Assertions in Ihrer eigenen Testsuite (Vitest oder Jest) siehe Vorlagen testen.

5. Ein echtes PDF rendern​

npx formfeed render invoice --data default --out invoice.pdf

Das füllt Ihre lokalen Dateien auf Ihrem Rechner mit dem Datensatz, schickt das Dokument durch die API und schreibt das PDF, das die Produktion erzeugen würde. --data nimmt den Namen eines Datensatzes oder den Pfad einer JSON-Datei; --remote rendert statt der lokalen Dateien die veröffentlichte Version im Workspace. Mit einem Test-Schlüssel ist das kostenlos; mit dem Live-Schlüssel, den formfeed login speichert, kostet es Einheiten.

Eine Word- oder PowerPoint-Vorlage wird stattdessen auf Ihrem Rechner gefüllt, mit der Engine der Render-Server, denn die API rendert von solchen Vorlagen nur gespeicherte Versionen:

npx formfeed render offer --output docx --out offer.docx   # das gefüllte Dokument, kein Rendering
npx formfeed render offer --output pdf --out offer.pdf     # hier gefüllt, von der API umgewandelt

Ohne --output entscheidet die Standardausgabe der Vorlage (office.output in settings.json, sonst das Format des Dokuments). Das PDF kommt von POST /pdf/convert, was den Starter-Plan oder höher braucht; für das gefüllte Dokument genügt ein Schlüssel. QR-Codes, Barcodes und SVG-Bilder zeichnet @resvg/resvg-js, eine optionale Abhängigkeit, die npm mit der CLI installiert, wenn das Paket die Plattform unterstützt; ohne es fehlen sie, und eine Warnung sagt es.

6. Pushen und veröffentlichen​

npx formfeed templates diff              # was sich gegenüber dem Workspace geändert hat
npx formfeed templates push --dry-run    # welche Vorlagen neu, geändert oder unverändert sind
npx formfeed templates push              # Entwurfsversionen aus Ihren Dateien anlegen
npx formfeed templates push --publish    # …und veröffentlichen
npx formfeed templates push --channel staging   # …oder den Channel staging darauf zeigen lassen

push überspringt Vorlagen, deren Dateien sich seit dem letzten Pull oder Push nicht geändert haben (sofern --publish oder --channel nicht mehr verlangt), und --message gibt den neuen Versionen eine Notiz. Es weigert sich zu überschreiben, wenn die Vorlage seit Ihrem letzten Pull oder Push im Workspace eine neuere Version bekommen hat, im Editor gespeichert oder von jemand anderem gepusht: Stattdessen antwortet es mit einem Konflikt. Führen Sie npx formfeed templates pull <slug> aus, führen Sie die Änderungen zusammen und pushen Sie erneut, oder übergeben Sie --force, um darüber hinweg zu pushen.

Speichert eine Vorlage ein Datenschema, lehnen --publish und --channel außerdem eine Änderung ab, die Aufrufer der aktuellen Version brechen würde, bis Sie --allow-breaking angeben; siehe Release Channels. npx formfeed types erzeugt aus denselben Schemas Typen für Ihren Anwendungscode (Typisierte Vorlagendaten).

7. Die CI übernehmen lassen​

Validieren und Vorschau bei jedem Pull Request, Veröffentlichen beim Merge. Nutzen Sie für die Prüfungen einen Test-Schlüssel und einen Live-Schlüssel nur für den Veröffentlichungsschritt:

# .github/workflows/templates.yml
name: templates
on:
  pull_request: { paths: ['templates/**', 'partials/**'] }
  push: { branches: [main], paths: ['templates/**', 'partials/**'] }

jobs:
  templates:
    runs-on: ubuntu-latest
    env:
      FORMFEED_API_KEY: ${{ secrets.FORMFEED_TEST_KEY }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx formfeed validate --ci
      - run: npx formfeed test --ci
      - if: github.event_name == 'pull_request'
        run: npx formfeed ci preview --base origin/main --ci
      - if: github.event_name == 'push'
        run: npx formfeed templates push --publish --message "${{ github.sha }}" --ci
        env:
          FORMFEED_API_KEY: ${{ secrets.FORMFEED_LIVE_KEY }}

formfeed ci preview rendert nur die Vorlagen, die sich seit der Basis-Ref geändert haben (daher fetch-depth: 0), nach formfeed-preview/ und schreibt eine Markdown-Zusammenfassung, formfeed-preview.md, die Sie als Kommentar im Pull Request posten können. Mehr unter Einsatz in der CI. Auf GitHub erledigt die Formfeed GitHub Action dieselben Schritte und hält den Kommentar für Sie aktuell.

Wie es weitergeht​