Projektstruktur

Ein Formfeed-Projekt ist ein Ordner mit einer formfeed.json. Jede Vorlage ist ein Ordner mit einfachen Dateien unter templates/, benannt nach dem Slug der Vorlage.

formfeed.json                  Workspace-Bindung und Optionen
templates/
  invoice-de/
    template.json               Name, Art (pdf, image, docx oder pptx), Engine, Beschreibung, Tags
    template.html               Body in der Vorlagensprache
    style.css                   optionales Stylesheet
    head.html                   optionaler zusätzlicher <head>-Inhalt (Schriften, Skripte)
    header.html, footer.html    optionale laufende Kopf- und Fußzeile
    settings.json               Seiteneinstellungen: Papier, Ränder, Größe von Kopf- und Fußzeile, Bildgröße, Sprache, PDF-Optionen …
    design.json                 Ebenen einer Vorlage aus dem visuellen Editor (nur Bildvorlagen)
    schema.json                 Datenschema (optional, sonst abgeleitet); nutzen formfeed types und die Prüfung beim Veröffentlichen
    i18n.json                   Übersetzungen (optional)
    data/
      default.json              Beispieldatensätze, eine Datei je Satz; dieselben Sätze wie im Editor
      many-lines.json
    tests/
      __snapshots__/            genehmigte Snapshots (`formfeed test`), einer je Datensatz
        default.html
        many-lines.html
partials/
  footer.html                   Fragmente, die die Vorlagen einbinden
files/
  logo.png                      die Dateibibliothek des Workspace: asset('logo.png')
  brand/header.svg              Ordner werden Teil des Namens: asset('brand/header.svg')
.formfeed/
  state.json                    was zuletzt gezogen oder gepusht wurde (schreibt die CLI)
  brand.json                    das Brand Kit der Organisation (formfeed brand pull)

formfeed templates pull schreibt diese Struktur; push liest sie. Dateien entsprechen eins zu eins den Tabs im Web-Editor, eine Vorlage lässt sich also an beiden Orten bearbeiten. Die Ordnernamen stammen aus formfeed.json (templatesDir, partialsDir, filesDir; siehe Konfiguration).

Die Dateien einer Vorlage

Datei	Pflicht	Inhalt
`template.html`	ja, oder `template.docx` / `template.pptx`	Der Body in der Sprache der Vorlage (Jinja2, Liquid oder Handlebars); siehe Vorlagensprachen
`template.json`	nein	`name`, `kind` (`pdf`, `image`, `docx`, `pptx`), `engine` (`jinja2`, `liquid`, `handlebars`), `description`, `tags`. Fehlende Felder werden zu einem Titel aus dem Slug (aus `invoice-de` wird `Invoice De`), `pdf` (oder der Art des Dokuments im Ordner), der `engine` aus `formfeed.json`, keiner Beschreibung und keinen Tags. `push` verwendet sie, wenn es eine Vorlage anlegt, die es noch nicht gibt; an einer bestehenden Vorlage ändert es keines davon.
`style.css`, `head.html`	nein	Das Stylesheet der Vorlage und zusätzlicher `<head>`-Inhalt
`header.html`, `footer.html`	nein	Die laufende Kopf- und Fußzeile eines PDFs; sie werden als `settings.header.html` und `settings.footer.html` übertragen
`settings.json`	nein	Die Einstellungen der Vorlage ohne das HTML von Kopf- und Fußzeile; siehe Einstellungen unten
`design.json`	nein	Die Ebenen einer Bildvorlage aus dem visuellen Editor; sie wird als `settings.design` übertragen
`schema.json`	nein	Das JSON-Schema der Daten. Ohne die Datei leiten `formfeed types` und die Prüfung beim Veröffentlichen eines aus den Datensätzen ab; siehe Typisierte Vorlagendaten
`i18n.json`	nein	Übersetzungen für den Helfer `t`: Sprache → Schlüssel → Text
`data/<name>.json`	nein	Datensätze. `default.json` sind die Beispieldaten der Version (`sample_data` in der API), der Satz, den `validate` und `ci preview` verwenden; fehlt die Datei, tritt die alphabetisch erste an ihre Stelle. Die übrigen Dateien sind die benannten Datensätze, die der Editor zeigt (`data_sets`). `test` rendert jeden davon.
`tests/__snapshots__/<name>.html`	nein	Genehmigte Snapshots von `formfeed test`, einer je Datensatz

Eine Vorlage aus dem visuellen Editor hat außerdem design.json: ihre Ebenen, aus denen der Editor template.html und style.css schreibt. Wer diese beiden Dateien von Hand ändert, entfernt sie vom Design; formfeed validate warnt dann (design-stale), und die App öffnet die Vorlage als Code, bis jemand entscheidet, den Code zu behalten oder das Design erneut anzuwenden.

Partials

partials/ enthält die Fragmente, die Vorlagen über ihren Namen einbinden ({% include "footer" %} liest partials/footer oder partials/footer.html; ein Name darf Ordner enthalten). Es gibt zwei Arten:

Partials des Projekts. templates push sendet jedes Partial, das eine Vorlage einbindet, mit der Version der Vorlage, und templates pull schreibt die Partials der geholten Version zurück in den Ordner. Eine Vorlage, die ein Partial ohne Datei einbindet, scheitert bei validate und wird von push abgewiesen.
Geteilte Partials der Organisation. formfeed partials pull schreibt sie als <name>.html und hält ihre Versionen in .formfeed/state.json fest; partials push sendet Änderungen zurück. Sie gehören zu keiner Vorlagenversion: Jedes Rendering verwendet ihre aktuelle Version, deshalb lässt templates push sie aus.

Synchronisationsstand

Nach jedem Pull oder Push hält die CLI Nummer und Prüfsumme der Remote-Version und einen Hash der lokalen Dateien in .formfeed/state.json fest.

push überspringt Ordner, deren Dateien sich seitdem nicht geändert haben. Mit --publish pusht es sie trotzdem und veröffentlicht die neue Version; mit --channel allein richtet es den Channel auf die festgehaltene Version.
push sendet die festgehaltene Prüfsumme als base_checksum. Wurde zwischenzeitlich eine neuere Version gespeichert, im Editor oder durch einen anderen Push, antwortet die API mit 409 conflict, und nichts wird gepusht: Ziehen Sie die Vorlage, führen Sie Ihre Änderungen zusammen und pushen Sie erneut, oder pushen Sie mit --force, um zu überschreiben.
--dry-run zeigt neue, geänderte, unveränderte und ausgelassene Ordner, ohne den Server anzufassen.

Committen Sie .formfeed/state.json, wenn das ganze Team aus dem Repository pusht und sonst niemand veröffentlicht; ignorieren Sie die Datei, wenn jeder seine eigene Kopie zieht. Wenn die CI veröffentlicht, committen Sie sie nicht: Die CI committet nicht zurück, was sie festhält, also veraltet der committete Stand mit der ersten Veröffentlichung; siehe Einsatz in der CI.

Die Dateibibliothek

files/ spiegelt die Dateibibliothek des Workspace. Der Pfad einer Datei unterhalb des Ordners ist ihr Name in der Bibliothek, und Vorlagen erreichen sie mit asset('brand/header.svg') oder einem relativen Pfad wie <img src="logo.png">.

formfeed files push lädt neue und geänderte Dateien hoch (verglichen per Hash, ein unverändertes Logo wird also nie erneut hochgeladen). Derselbe Name ersetzt die Datei in der Bibliothek für alle Vorlagen.
formfeed files pull lädt herunter, was im Ordner fehlt, und ersetzt lokale Dateien, deren Inhalt von dem der Bibliothek abweicht.
formfeed dev liefert den Ordner aus, damit asset() und relative Bildpfade offline funktionieren.
Eine Datei, die die Bibliothek ablehnen würde, wird mit einer Meldung übersprungen: ein Name mit anderen Zeichen als Buchstaben, Ziffern, ., - und _ (dazu / zwischen Ordnern), ein anderer Typ als PNG, JPEG, WebP, GIF, SVG, AVIF und PDF, eine leere Datei oder eine über 10 MB.

Der Ordner ist nicht an eine Vorlagenversion gebunden: Eine Datei gilt für alle Vorlagen des Workspace.

Word- und PowerPoint-Vorlagen

Eine Word- oder PowerPoint-Vorlage legt ihr Dokument statt template.html in den Ordner:

templates/
  offer/
    template.json               Art docx, Engine, Name, Beschreibung, Tags
    template.docx               das Word-Dokument mit Tags im Text (template.pptx für PowerPoint)
    settings.json               Standardausgabe, Sprache, Zeitzone, Währung
    schema.json, i18n.json      wie bei HTML-Vorlagen
    data/
      default.json
    tests/
      __snapshots__/
        default.xml             das XML des gefüllten Dokuments (`formfeed test`)

Ein Ordner enthält genau eine der Dateien template.html, template.docx und template.pptx; ein Ordner mit zweien davon ist ein Fehler. Die Datei bestimmt die Art, und eine template.json, deren kind etwas anderes sagt, ist ebenfalls ein Fehler.
Es gibt kein style.css, head.html, header.html, footer.html und kein Partial: Das Dokument bringt seine eigenen Formatvorlagen, Kopf- und Fußzeilen mit, und Office-Vorlagen können keine Partials einbinden.
templates pull schreibt das Dokument genau der Version, die es holt, und entfernt die HTML-Dateien, wenn sich die Art einer Vorlage geändert hat.
templates push lädt das Dokument nur hoch, wenn sein SHA-256 von fileSha256 abweicht, dem Hash, den .formfeed/state.json beim letzten Pull oder Push festgehalten hat. Sonst behält die neue Version das letzte Dokument und ändert nur Einstellungen, Daten, Schema oder Übersetzungen.
templates diff vergleicht das Dokument über seinen Hash und nennt die Größen; um zu sehen, was sich geändert hat, öffnen Sie beide Dateien in Word oder PowerPoint.
formfeed test schreibt die Snapshots als .xml: das XML jedes gefüllten Teils, ein Element pro Zeile, gefüllt, ohne Bilder zu laden oder zu zeichnen, damit ein Diff lesbar und wiederholbar ist.

Einstellungen

settings.json enthält die Einstellungen der Vorlage, dasselbe Objekt, das die Seiteneinrichtung des Editors schreibt. Beispiel für Einstellungen einer HTML-Vorlage:

{
  "paper": { "format": "A4", "landscape": false },
  "margin": {
    "top": "20mm",
    "right": "15mm",
    "bottom": "20mm",
    "left": "15mm"
  },
  "header": { "height": "12mm" },
  "footer": { "height": "10mm" },
  "locale": "de-DE",
  "timezone": "Europe/Berlin",
  "currency": "EUR",
  "tailwind": true
}

Die Einstellungen einer Word- oder PowerPoint-Vorlage enthalten die Ausgabe, die ein Rendering ohne eigene Angabe bekommt, pdf oder das Format des Dokuments (der Standard), und die Formatierung ihrer Helfer:

{
  "office": { "output": "pdf" },
  "locale": "de-DE",
  "timezone": "Europe/Berlin",
  "currency": "EUR"
}

Die Dateien einer Vorlage​

Partials​

Synchronisationsstand​

Die Dateibibliothek​

Word- und PowerPoint-Vorlagen​

Einstellungen​